Skip to content

Commit 7052616

Browse files
ijrothclaude
andauthored
cloud: store the sync token in the OS keyring on every platform (#37)
Spec §20 has always said "OS keychain where available". Only macOS satisfied it: Windows and Linux dropped the token into a plaintext ~/.ark/credentials.toml. This is the conformance fix. Resolution stays ARK_TOKEN -> keyring -> restricted file, and credentials stay keyed by sync-service host, so one `ark login` still covers every repository on that service. Three things change beyond the platform coverage: - The token no longer appears in argv. The old macOS path ran `security add-generic-password -w <token>`, which put the secret in the process table for any user on the machine to read for the duration of the call. go-keyring feeds `security -i` on stdin instead. - A keyring that fails is no longer silent. The old code guarded the success path with `err == nil` and no else, so a locked or denied keychain fell straight through to plaintext with no word to anyone. That is the bug the GitHub CLI maintainers now regret (cli/cli#10108, cli/cli#13317); we say so on stderr before touching the file. A keyring that answers and holds nothing is a miss, not a failure, and stays quiet. - Storage is legible from both ends. `ark login` already named where it wrote the token; `ark status` now names where it resolved one from, as `token_source` in --json (a new field; nothing renamed) and a `token` line for humans. Neither prints the token. Two smaller consequences of getting a real keyring: - Once the keyring holds a host's token, `ark login` removes that host's entry from the fallback file, and the file itself once it is empty. The keyring outranks it, so the copy was a secret on disk nothing would ever read again — this is the upgrade path for anyone who logged in on Windows or Linux before today. - ARK_NO_KEYRING=1 skips the keyring for machines where the file is the deliberate choice: a headless box with no Secret Service, a CI image where a prompt would hang. That path is quiet, because it was asked for. zalando/go-keyring is pure Go (wincred, godbus, x/sys), so the no-CGO invariant holds; all six release targets build with CGO_ENABLED=0. 99designs/keyring would not have — it uses cgo on macOS. internal/cli grows a TestMain that redirects HOME/USERPROFILE and opts out of the keyring, because `ark status` now resolves a credential and no test should be able to reach the developer's real one. Claude-Session: https://claude.ai/code/session_01LbNXVAkmXtXnSfCWRMwBc9 Co-authored-by: Claude Opus 5 (1M context) <[email protected]>
1 parent e9099e8 commit 7052616

17 files changed

Lines changed: 759 additions & 79 deletions

‎CLAUDE.md‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -54,8 +54,11 @@ retry, so they must be idempotent and reset their accumulators. The client
5454
blobs via signed URLs, then pulls records after its cursor and upserts them
5555
(internal/store/sync.go) with deferred FK checks. Server-assigned display
5656
numbers can be rewritten on collision — the ULID is authoritative, so local
57-
numbers are indexed but not unique. Tokens resolve ARK_TOKEN → macOS
58-
keychain → ~/.ark/credentials.toml and never live in the repository.
57+
numbers are indexed but not unique. Tokens resolve ARK_TOKEN → OS keyring
58+
(macOS Keychain, Windows Credential Manager, Secret Service, via
59+
zalando/go-keyring — pure Go) → ~/.ark/credentials.toml, never live in the
60+
repository, and never reach another process's argv. A keyring that fails
61+
warns on stderr before the fallback; see spec §20.
5962

6063
## This repository is not itself managed by Ark
6164

‎README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -31,7 +31,7 @@ See [docs/v1-spec.md](docs/v1-spec.md) for the full specification and
3131

3232
```sh
3333
ark remote set https://ark.example.com # per repository
34-
ark login # token -> keychain or user credentials file
34+
ark login # token -> OS keyring, else credentials file
3535
ark sync # push mutations, upload blobs, pull records
3636
```
3737

‎docs/self-hosting.md‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -227,15 +227,26 @@ carrying a one-hour expiry.
227227
**Client side.** The token resolves in this order:
228228

229229
1. `ARK_TOKEN` in the environment
230-
2. the macOS keychain, service `ark`, account = the remote's host
230+
2. the OS keyring, service `ark`, account = the remote's host:
231+
- macOS: the login keychain
232+
- Windows: Credential Manager, as generic credential `ark:<host>`
233+
- Linux: the Secret Service (GNOME Keyring, KWallet, `keepassxc`, …)
231234
3. the user credential file, keyed by remote host:
232235
- macOS/Linux: `~/.ark/credentials.toml`, mode 0600
233236
- Windows: `%USERPROFILE%\.ark\credentials.toml`, protected by a
234237
current-user-only ACL
235238

236239
Tokens are never written into the repository — not into `.ark/config.toml`,
237-
not anywhere under `.ark/`. `ark login` writes to the keychain on macOS
238-
and falls back to the credentials file elsewhere.
240+
not anywhere under `.ark/` — and never passed to another process as a
241+
command-line argument.
242+
243+
`ark login` writes to the keyring. When the keyring is unavailable — no
244+
Secret Service on a headless box, a locked or denied keychain — it says so
245+
on stderr and falls back to the credentials file; it never degrades to
246+
plaintext silently. `ark status` reports which of the three answered.
247+
248+
Set `ARK_NO_KEYRING=1` to skip the keyring and use the file deliberately;
249+
that path is quiet, because you asked for it.
239250

240251
### Operational warnings
241252

@@ -383,9 +394,9 @@ ark sync
383394
```
384395

385396
`ark remote set` writes the URL to `.ark/config.toml`. `ark login`
386-
stores the token outside the repository (keychain, else
387-
`~/.ark/credentials.toml`). Piping is preferred over `--token` to keep
388-
the value out of shell history:
397+
stores the token outside the repository (the OS keyring, else
398+
`~/.ark/credentials.toml`) and prints which one it used. Piping is
399+
preferred over `--token` to keep the value out of shell history:
389400

390401
```sh
391402
<your secret store: read the token> | ark login

‎docs/v1-spec.md‎

Lines changed: 31 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -1185,11 +1185,37 @@ The client stores credentials outside the repository.
11851185

11861186
Do not store tokens in `.ark/config.toml`.
11871187

1188-
Use:
1189-
1190-
- OS keychain where available
1191-
- environment variable fallback
1192-
- local credential file with restricted permissions only as a development fallback
1188+
Token resolution is ordered, and the order is fixed:
1189+
1190+
1. the `ARK_TOKEN` environment variable
1191+
2. the OS keyring — macOS Keychain, Windows Credential Manager, or the
1192+
freedesktop Secret Service — keyed by the sync service's host, so one
1193+
login covers every repository pointing at that service
1194+
3. a local credential file with restricted permissions, as a fallback only
1195+
1196+
A token must never be passed to another process as a command-line argument.
1197+
The process table is readable by every user on the machine.
1198+
1199+
The keyring is not optional where the platform has one. If the keyring is
1200+
unavailable — absent, locked, denied, or a platform without one — the client
1201+
must say so on the standard error stream **before** it falls back to the
1202+
file. Degrading to plaintext in silence is not permitted. A keyring that
1203+
answers and simply holds no entry for the host is a miss, not a failure, and
1204+
is not announced.
1205+
1206+
The fallback file is restricted to the current user before any token is
1207+
written into it: mode 0600 on Unix, a DACL granting only the current account
1208+
on Windows. Once the keyring holds a host's token, the client removes that
1209+
host's entry from the fallback file — the keyring outranks it, so the copy
1210+
would be a secret on disk that nothing will ever read.
1211+
1212+
`ARK_NO_KEYRING` skips the keyring entirely, for a machine where the file is
1213+
the deliberate choice. Storage then goes straight to the file, without a
1214+
warning, because the operator asked for it.
1215+
1216+
Commands report which store answered. `ark login` names where it wrote the
1217+
token; `ark status` names where the token resolved from. Neither prints the
1218+
token itself (§21).
11931219

11941220
The cloud service must identify:
11951221

‎docs/windows.md‎

Lines changed: 11 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -79,9 +79,17 @@ ark status
7979

8080
`ark login` accepts one token line on standard input. It stores a credential
8181
once per sync-service host, not once per project, so that login covers every
82-
Ark project using the same service. On Windows the fallback credential file is
83-
`%USERPROFILE%\.ark\credentials.toml`, protected by a current-user-only ACL;
84-
tokens are never stored inside the project. For CI and coding agents, set
82+
Ark project using the same service.
83+
84+
On Windows the token goes to **Credential Manager**, as the generic credential
85+
`ark:<host>` — you can see it under *Control Panel → Credential Manager →
86+
Windows Credentials*. If Credential Manager is unavailable, `ark login` says so
87+
on stderr and falls back to `%USERPROFILE%\.ark\credentials.toml`, protected by
88+
a current-user-only ACL. It never falls back silently, and `ark status` reports
89+
which store the token came from. Set `ARK_NO_KEYRING=1` to choose the file
90+
deliberately.
91+
92+
Tokens are never stored inside the project. For CI and coding agents, set
8593
`ARK_TOKEN` in the process environment instead:
8694

8795
```powershell

‎go.mod‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@ require (
77
github.com/BurntSushi/toml v1.6.0
88
github.com/oklog/ulid/v2 v2.1.1
99
github.com/spf13/cobra v1.10.2
10+
github.com/zalando/go-keyring v0.2.8
1011
golang.org/x/sys v0.46.0
1112
google.golang.org/api v0.285.0
1213
modernc.org/sqlite v1.53.0
@@ -25,13 +26,15 @@ require (
2526
github.com/GoogleCloudPlatform/opentelemetry-operations-go/internal/resourcemapping v0.57.0 // indirect
2627
github.com/cespare/xxhash/v2 v2.3.0 // indirect
2728
github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 // indirect
29+
github.com/danieljoos/wincred v1.2.3 // indirect
2830
github.com/dustin/go-humanize v1.0.1 // indirect
2931
github.com/envoyproxy/go-control-plane/envoy v1.37.0 // indirect
3032
github.com/envoyproxy/protoc-gen-validate v1.3.3 // indirect
3133
github.com/felixge/httpsnoop v1.0.4 // indirect
3234
github.com/go-jose/go-jose/v4 v4.1.4 // indirect
3335
github.com/go-logr/logr v1.4.3 // indirect
3436
github.com/go-logr/stdr v1.2.2 // indirect
37+
github.com/godbus/dbus/v5 v5.2.2 // indirect
3538
github.com/google/s2a-go v0.1.9 // indirect
3639
github.com/google/uuid v1.6.0 // indirect
3740
github.com/googleapis/enterprise-certificate-proxy v0.3.16 // indirect

‎go.sum‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,8 @@ github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XL
3535
github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2 h1:aBangftG7EVZoUb69Os8IaYg++6uMOdKK83QtkkvJik=
3636
github.com/cncf/xds/go v0.0.0-20260202195803-dba9d589def2/go.mod h1:qwXFYgsP6T7XnJtbKlf1HP8AjxZZyzxMmc+Lq5GjlU4=
3737
github.com/cpuguy83/go-md2man/v2 v2.0.6/go.mod h1:oOW0eioCTA6cOiMLiUPZOpcVxMig6NIQQ7OS05n1F4g=
38+
github.com/danieljoos/wincred v1.2.3 h1:v7dZC2x32Ut3nEfRH+vhoZGvN72+dQ/snVXo/vMFLdQ=
39+
github.com/danieljoos/wincred v1.2.3/go.mod h1:6qqX0WNrS4RzPZ1tnroDzq9kY3fu1KwE7MRLQK4X0bs=
3840
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc h1:U9qPSI2PIWSS1VwoXQT9A3Wy9MM3WgvqSxFWenqJduM=
3941
github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
4042
github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
@@ -56,6 +58,8 @@ github.com/go-logr/logr v1.4.3 h1:CjnDlHq8ikf6E492q6eKboGOC0T8CDaOvkHCIg8idEI=
5658
github.com/go-logr/logr v1.4.3/go.mod h1:9T104GzyrTigFIr8wt5mBrctHMim0Nb2HLGrmQ40KvY=
5759
github.com/go-logr/stdr v1.2.2 h1:hSWxHoqTgW2S2qGc0LTAI563KZ5YKYRhT3MFKZMbjag=
5860
github.com/go-logr/stdr v1.2.2/go.mod h1:mMo/vtBO5dYbehREoey6XUKy/eSumjCCveDpRre4VKE=
61+
github.com/godbus/dbus/v5 v5.2.2 h1:TUR3TgtSVDmjiXOgAAyaZbYmIeP3DPkld3jgKGV8mXQ=
62+
github.com/godbus/dbus/v5 v5.2.2/go.mod h1:3AAv2+hPq5rdnr5txxxRwiGjPXamgoIHgz9FPBfOp3c=
5963
github.com/golang/protobuf v1.5.4 h1:i7eJL8qZTpSEXOPTxNKhASYpMn+8e5Q6AdndVa1dWek=
6064
github.com/golang/protobuf v1.5.4/go.mod h1:lnTiLA8Wa4RWRcIUkrtSVa5nRhsEGBg48fD6rSs7xps=
6165
github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
@@ -96,8 +100,12 @@ github.com/spf13/pflag v1.0.9 h1:9exaQaMOCwffKiiiYk6/BndUBv+iRViNW+4lEMi0PvY=
96100
github.com/spf13/pflag v1.0.9/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
97101
github.com/spiffe/go-spiffe/v2 v2.6.0 h1:l+DolpxNWYgruGQVV0xsfeya3CsC7m8iBzDnMpsbLuo=
98102
github.com/spiffe/go-spiffe/v2 v2.6.0/go.mod h1:gm2SeUoMZEtpnzPNs2Csc0D/gX33k1xIx7lEzqblHEs=
103+
github.com/stretchr/objx v0.5.2 h1:xuMeJ0Sdp5ZMRXx/aWO6RZxdr3beISkG5/G/aIRr3pY=
104+
github.com/stretchr/objx v0.5.2/go.mod h1:FRsXN1f5AsAjCGJKqEizvkpNtU+EGNCLh3NxZ/8L+MA=
99105
github.com/stretchr/testify v1.11.1 h1:7s2iGBzp5EwR7/aIZr8ao5+dra3wiQyKjjFuvgVKu7U=
100106
github.com/stretchr/testify v1.11.1/go.mod h1:wZwfW3scLgRK+23gO65QZefKpKQRnfz6sD981Nm4B6U=
107+
github.com/zalando/go-keyring v0.2.8 h1:6sD/Ucpl7jNq10rM2pgqTs0sZ9V3qMrqfIIy5YPccHs=
108+
github.com/zalando/go-keyring v0.2.8/go.mod h1:tsMo+VpRq5NGyKfxoBVjCuMrG47yj8cmakZDO5QGii0=
101109
go.opentelemetry.io/auto/sdk v1.2.1 h1:jXsnJ4Lmnqd11kwkBV2LgLoFMZKizbCi5fNZ/ipaZ64=
102110
go.opentelemetry.io/auto/sdk v1.2.1/go.mod h1:KRTj+aOaElaLi+wW1kO/DZRXwkF4C5xPbEe3ZiIhN7Y=
103111
go.opentelemetry.io/contrib/detectors/gcp v1.42.0 h1:kpt2PEJuOuqYkPcktfJqWWDjTEd/FNgrxcniL7kQrXQ=

‎internal/cli/main_test.go‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
package cli
2+
3+
import (
4+
"os"
5+
"testing"
6+
)
7+
8+
// TestMain fences this package's tests off from the developer's real
9+
// credentials. `ark status` and `ark sync` resolve a sync token, and
10+
// resolution reaches the OS keyring and then the credentials file — so
11+
// without this, a test that configures a remote and forgets to set ARK_TOKEN
12+
// would read the machine's actual keychain and ~/.ark/credentials.toml. The
13+
// sync tests do set ARK_TOKEN and never get that far; this is here for the
14+
// next test that does not.
15+
//
16+
// os.UserHomeDir reads USERPROFILE on Windows and HOME everywhere else, so
17+
// both are redirected. A test that wants the real resolution path has to
18+
// clear ARK_NO_KEYRING and point HOME/USERPROFILE somewhere of its own.
19+
func TestMain(m *testing.M) {
20+
home, err := os.MkdirTemp("", "ark-cli-home")
21+
if err != nil {
22+
panic(err)
23+
}
24+
os.Setenv("HOME", home)
25+
os.Setenv("USERPROFILE", home)
26+
os.Setenv("ARK_NO_KEYRING", "1")
27+
28+
code := m.Run()
29+
30+
os.RemoveAll(home)
31+
os.Exit(code)
32+
}

‎internal/cli/remote.go‎

Lines changed: 19 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -83,11 +83,15 @@ means one ` + "`ark login`" + `, not one per repository.
8383
Run it anywhere with --remote, or inside a repository to use that
8484
repository's configured remote.
8585
86-
The token goes to the macOS keychain when available, otherwise to a
87-
per-user credentials file: ~/.ark/credentials.toml (mode 0600), or
88-
%USERPROFILE%\.ark\credentials.toml with a current-user-only ACL on Windows.
89-
Tokens are never written inside the repository. Pass --token, or pipe the
90-
token on stdin.`,
86+
The token goes to this machine's OS keyring: the macOS keychain, Windows
87+
Credential Manager, or the Secret Service. If the keyring is unavailable Ark
88+
says so on stderr and falls back to a per-user credentials file —
89+
~/.ark/credentials.toml (mode 0600), or %USERPROFILE%\.ark\credentials.toml
90+
with a current-user-only ACL on Windows. Set ARK_NO_KEYRING=1 to choose that
91+
file deliberately and skip the keyring.
92+
93+
Tokens are never written inside the repository, and never passed to another
94+
process as a command-line argument. Pass --token, or pipe the token on stdin.`,
9195
Args: cobra.NoArgs,
9296
RunE: func(cmd *cobra.Command, args []string) error {
9397
remote := strings.TrimRight(remoteFlag, "/")
@@ -131,13 +135,21 @@ token on stdin.`,
131135
}
132136
}
133137

134-
where, err := cloud.StoreToken(remote, token)
138+
src, err := cloud.StoreToken(remote, token)
135139
if err != nil {
136140
return err
137141
}
138142
host := cloud.RemoteHost(remote)
143+
where := src.Description()
139144
p := g.printer(cmd)
140-
return p.Result(map[string]string{"stored_in": where, "remote": remote, "host": host}, func() {
145+
// storage is the machine-readable half of stored_in: agents branch
146+
// on "keyring" vs "file", humans read the keychain's name or a path.
147+
return p.Result(map[string]string{
148+
"stored_in": where,
149+
"storage": string(src),
150+
"remote": remote,
151+
"host": host,
152+
}, func() {
141153
p.Line("Token stored in %s for %s", where, host)
142154
p.Line("Covers every repository on this machine whose remote is %s.", host)
143155
})

‎internal/cli/status.go‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,7 @@ package cli
33
import (
44
"github.com/spf13/cobra"
55

6+
"github.com/elk-work/ark/internal/cloud"
67
"github.com/elk-work/ark/internal/records"
78
)
89

@@ -18,6 +19,12 @@ type statusReport struct {
1819
PendingMutations int64 `json:"pending_mutations"`
1920
Conflicts int64 `json:"unresolved_conflicts"`
2021
Remote string `json:"remote,omitempty"`
22+
// TokenSource is which store answered for the sync token — env, keyring,
23+
// file, or none — and is set only when a remote is configured. `ark login`
24+
// says where it wrote the token; resolution deserves to be as legible,
25+
// because reading one out of a plaintext file is a different state from
26+
// reading one out of the keychain. Never the token itself.
27+
TokenSource string `json:"token_source,omitempty"`
2128
}
2229

2330
func newStatusCmd(g *globals) *cobra.Command {
@@ -43,6 +50,18 @@ func newStatusCmd(g *globals) *cobra.Command {
4350
rep.Branch, _ = a.Git.CurrentBranch(ctx)
4451
rep.Head, _ = a.Git.Head(ctx)
4552

53+
// Resolving here can warn on stderr that the keyring is locked or
54+
// absent, which is exactly where someone would want to hear it. A
55+
// missing credential is not a status failure — it is a state to
56+
// report — so the error is deliberately dropped for the source.
57+
tokenAt := cloud.SourceNone
58+
if rep.Remote != "" {
59+
if cred, err := cloud.ResolveCredential(rep.Remote); err == nil {
60+
tokenAt = cred.Source
61+
}
62+
rep.TokenSource = string(tokenAt)
63+
}
64+
4665
count := func(query string, dest *int64, args ...any) error {
4766
if err := a.DB.QueryRowContext(ctx, query, args...).Scan(dest); err != nil {
4867
return records.DBErr("count records", err)
@@ -75,6 +94,14 @@ func newStatusCmd(g *globals) *cobra.Command {
7594
p.Line("sync no remote configured; %d local mutations recorded", rep.PendingMutations)
7695
} else {
7796
p.Line("sync %s (%d pending mutations)", rep.Remote, rep.PendingMutations)
97+
switch tokenAt {
98+
case cloud.SourceNone:
99+
p.Line("token none — run `ark login`")
100+
case cloud.SourceFile:
101+
p.Line("token %s (plaintext fallback)", tokenAt.Description())
102+
default:
103+
p.Line("token %s", tokenAt.Description())
104+
}
78105
}
79106
if rep.Conflicts > 0 {
80107
p.Line("conflicts %d unresolved (see `ark conflict list`)", rep.Conflicts)

0 commit comments

Comments
 (0)