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

[davidmiuraactualai]

Actual Adversarial Review

Key findings

• ⚠️ APR-001 P2 Emit a recoverable token before fallible stderr output — the post-mint recovery path can return before writing the token to stdout at create_token.rs:113.

---

⚠️ APR-001 P2 Emit a recoverable token before fallible stderr output

Location: src/cli/commands/create_token.rs:113 at 92954b0b2242e2e7de9fb0e9f96b1c001230569c

Risk: A live PAT can again become unrecoverable when local storage fails and stderr is unavailable, even though stdout remains writable.

Evidence and required correction

• Code: after a successful server-side mint, run_inner calls print_unstored_token(out, err, ...) and deliberately discards its result. That helper first writes error chrome to err at line 194 with ?; an I/O failure therefore returns before reaching the only stdout token write at line 223. The caller then returns only store_err.
• Repository ADR: secure secrets management requires secure credential handling across CLI commands and runtime environments.
• Public: Rust std::io::Write documents that writes and formatted writes return I/O errors; a fallible stderr write is a normal error path, not a guaranteed side effect.
• Verification: cargo test print_unstored_token_propagates_stderr_write_failure --lib -- --nocapture passed. That existing test proves the helper returns an error for a failing stderr writer, but it does not assert that the available stdout writer still receives the minted secret.

Required correction: Once a PAT has been minted and local storage fails, attempt the stdout-only token emission before any fallible stderr diagnostics, and independently make best-effort diagnostics afterward. Add a regression with a writable stdout buffer and an immediately failing stderr writer that asserts stdout contains exactly the minted token and the command still returns the storage error.

🤖 Corrective action — ⚠️ APR-001 P2 — Option A: preserve stdout recovery first

Tradeoff: This retains the current stream contract while prioritizing the only recoverability channel; stderr diagnostics may be incomplete when stderr itself is broken.

Fix APR-001 P2, “Emit a recoverable token before fallible stderr output,” in actual-software/actual-cli at src/cli/commands/create_token.rs:113 on 92954b0b2242e2e7de9fb0e9f96b1c001230569c.

Problem: after PAT issuance succeeds but token_store::store fails, run_inner ignores print_unstored_token errors. That helper writes multiple diagnostics to stderr before it writes the secret to stdout. If stderr fails first while stdout remains available, the helper returns early, the token is never emitted, and the already-live PAT cannot be captured or revoked.

Required invariant: after a successful mint with failed local storage, the command attempts to emit the raw PAT exactly once on stdout whenever stdout is writable, regardless of stderr availability; it still returns the storage failure.

Constraints: Follow AGENTS.md, src/AGENTS.md, and docs/adr/8d11aed5-d4a3-4ef6-937a-085f723bd997-adopt-secure-secrets-management-in-ci-cd-pipeline.md; honor .gitignore. Preserve stdout as token-only, never write the PAT to stderr or logs, retain the pre-mint storage check, and keep normal successful output behavior compatible.

Implement: restructure only the post-mint store-failure recovery path so stdout token emission is attempted before fallible stderr chrome, then perform diagnostics independently on a best-effort basis. Preserve the original storage error as the command result.

Verify: add a regression using a writable stdout buffer and a stderr writer that fails on its first write. Assert stdout is exactly the minted token plus newline, stderr contains no secret, and run_inner returns the original storage error. Run cargo test print_unstored_token --lib and cargo test create_token --lib.

Do not: print a raw PAT on stderr, logs, command arguments, or a second stdout line; silently report success after storage failure; or change unrelated token-storage backends.

Copy into a coding agent to run.

Architecture intent

No architecture-intent decision is needed for this localized recovery-order correction.

---

Review metadata

Important

One P2 finding remains unresolved at head 92954b0b2242e2e7de9fb0e9f96b1c001230569c. This is the canonical remediation record for the PR.

Compared: upstream main at cfcae4cd84645417e7d8042517a69cbd55d22404 … PR head 92954b0b2242e2e7de9fb0e9f96b1c001230569c
CI: Build for x86_64 and aarch64, Test, Lint, Coverage Enforcement, and CodeQL pass; Live E2E is skipped. Local verification: the focused stderr-failure unit test passes, and git diff --check reports no whitespace errors.