feat(auth): add actual auth create-token for non-interactive auth

[benw5483]

Summary

Adds actual auth create-token, a scoped personal access token (PAT) path so CI jobs and autonomous agents can authenticate without a browser. It builds on the existing actual login session, so it doesn't add a second login flow.

• Reuses the logged-in session: loads stored credentials, refreshes the access token if near expiry, calls the authenticated issuance endpoint with that token as the bearer, and prints the raw actl_pat_… once.
• Stores the token in the OS keychain (the keyring crate) with an XChaCha20-Poly1305 + Argon2id encrypted-file fallback for headless Linux / CI where no OS keychain is available.
• Non-interactive callers resolve a token from ACTUAL_TOKEN, then the keychain, then the encrypted file.
• actual auth with no subcommand keeps its existing runner-auth check, so this is backward compatible.

Proof of concept / draft. The server-side issuance endpoint isn't live yet. The CLI is built against the documented contract (POST <base>/api/oauth/tokens, the session token as bearer) and is repointed with --api-url / ACTUAL_API_URL. See docs/AGENT_AUTH.md.

Headless-storage finding (the question this POC answers)

Does the keychain library degrade gracefully on a headless Linux box / CI runner with no desktop keyring?

The finding turned out sharper than we'd have guessed from a runtime check. The keyring crate's Secret Service backend links the system libdbus at build time through pkg-config, so a host without libdbus-1-dev can't compile the CLI at all. On stock Linux CI runners every job went red on The system library dbus-1 required by crate libdbus-sys was not found. A missing runtime daemon is recoverable. A binary that never builds is not.

The fix is a Linux backend with no build-time system dependency. This CLI uses linux-native, the kernel keyutils keyring, reached through raw syscalls: no libdbus, no pkg-config, no D-Bus daemon. It compiles on any Linux, including a bare CI container, and stores secrets headless. macOS and Windows keep their native keychains.

Runtime degradation stays explicit. In the default auto mode a keychain error routes to the encrypted-file store when ACTUAL_TOKEN_PASSPHRASE is set, and otherwise fails loudly rather than writing a weaker store. keyutils is session / persistent-keyring scoped, so for durable non-interactive use the recommended paths are ACTUAL_TOKEN (CI) and the encrypted-file fallback (headless Linux).

Library chosen: keyring v3 — linux-native (keyutils) on Linux, apple-native / windows-native elsewhere. Fallback: XChaCha20-Poly1305 AEAD, key derived by Argon2id from a passphrase, file written 0600. Without a passphrase the fallback is refused rather than writing anything weaker.

Security model for agents

Two rules, documented in --help and docs/AGENT_AUTH.md:

• A dedicated token per agent (--name <agent>): never share the human's interactive login. One PAT per agent makes every action attributable and lets a single agent be revoked on its own.
• Never in the model's context: the secret lives only in the keychain or ACTUAL_TOKEN, never in a prompt, shell history, command-line argument, or log. This guards against the agent-specific prompt-injection exfiltration path, where untrusted input an agent reads can instruct it to leak any secret in its context.

The raw token is printed once to stdout (for capture) and is never written to a log or Debug output. The Debug impls redact it, and the encrypted file holds no plaintext.

Test plan

• cargo fmt --check and cargo clippy -- -D warnings are clean.
• Unit tests cover token storage (the keychain backends via an injectable in-memory keystore, the encrypted-file round-trip and error paths, env / backend selection), the issuance client (mocked HTTP), and command orchestration (mint → store → retrieve, and the token-refresh path). The three new modules sit at 100% line coverage.
• Backward compatibility: bare actual auth still runs the runner-auth check.
• End-to-end run against a local mock issuance endpoint (transcript below, secret masked).

End-to-end run against a mock issuance endpoint (secret masked)

$ actual auth create-token --name demo-agent --scopes adr:query,adr:review --api-url http://127.0.0.1:$PORT
✔ Created scoped access token "demo-agent"
  Token id:    tok_ed9529ca
  Scopes:      adr:query adr:review
  Expires:     2026-09-28T00:00:00Z
  Stored in:   encrypted file

Your token is shown once below. Copy it now:

[stdout, MASKED] actl_pat_Bic9…Tmxi
create-token exit: 0

# The mock confirmed the request arrived authenticated at the issuance route.
[mock] POST /api/oauth/tokens authenticated=yes name='demo-agent' scopes=['adr:query', 'adr:review']

# At-rest check: the stored file is ciphertext, not the plaintext token.
OK: plaintext token is NOT present on disk
file mode: 600
{
  "version": 1,
  "kdf": "argon2id",
  "salt": "qfUeK/5DQCw8b7xgBYdU4g==",
  "nonce": "77FsOPjRsQUGBOpDsEB30Ou24tfLG6PR",
  "ciphertext": "LsjnH1ydrhsGrZXr8wL5kaYMRacShkh1…"
}

Follow-ups

• Point the issuance call at the real endpoint once the server side ships, and verify the full path against staging.
• The PAT → short-lived-JWT exchange and the commands that consume the token are tracked separately and are out of scope here.

Revision — never orphan an unrevocable token on store failure

A self-review found the PAT was minted server-side before the local store ran, so a store error bailed via ? before the token or its id were printed — losing a live, unrevocable token. The likeliest trigger is the target env itself (headless Linux, no ACTUAL_TOKEN_PASSPHRASE, no OS keychain). This revision closes the gap from both ends:

• token_store::precheck is a non-writing probe that confirms a backend is available; create-token now calls it before minting, so the predictable headless / no-passphrase case fails with no token minted at all.
• On any residual post-mint store failure (a full disk, a keychain lock race the precheck cannot foresee), the token and its id are still surfaced — stdout=secret, stderr=chrome — so the user can capture and revoke, and the error still propagates.
• New tests cover the pre-mint precheck refusal, the store-fails-after-mint recovery, and that stdout carries only the token.

Audit matrix

Resource	Rule	Threat	Covered
create-token mint/store ordering	A minted token is always capturable + revocable; never mint an uncapturable token, or surface it on store failure	Orphaned unrevocable live token on a headless-Linux store failure (the target env)	yes — pre-mint precheck + post-mint surface + store-fail test
token output channel	stdout carries ONLY the token; chrome / status to stderr	Secret token leaks into logs mixed with UI text; the capture contract breaks	yes — stdout-carries-only-the-token assertion test

---

Generated by the operator's software factory.
• On behalf of: @benw5483