feat(auth): add headless jwt-bearer client (actual mint-token)

[benw5483]

Summary

Adds actual mint-token, a fully-headless RFC 7523 jwt-bearer client: it signs a short-lived service-account assertion with a registered private key and exchanges it for an access token — no browser, no human, no stored long-lived secret. This is the unattended-agent path that the existing enrollment commands (login, and auth create-token / login --device in #801 / #802) do not cover: those establish a human-delegated session, whereas an autonomous agent on a dev box or in CI holds its own key and self-issues an assertion.

The command mirrors the authorization server's jwt-bearer grant exactly:

• Assertion header — { alg: RS256 | ES256, kid, typ: JWT }. HS* and none cannot be represented, let alone emitted — closing alg-confusion on the client the same way the server closes it.
• Assertion claims — iss == sub == <service-account-id> (validated as a UUID before signing), aud defaulting to the issuer origin, a fresh unique jti per call, iat = now, and exp clamped to at most 300s after iat.
• Request — POST <issuer>/api/oauth/token with grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer, assertion=<JWS>, and an optional space-delimited scope.

Headless usage

Every input comes from a flag, an environment variable, or a file:

# Key inline via env (preferred with a secret manager — keeps it off argv):
export ACTUAL_SERVICE_ACCOUNT_KEY="$(cat service-account.pem)"
TOKEN=$(actual mint-token \
  --service-account-id 3f8a1c2e-4b5d-4e6f-8a9b-0c1d2e3f4a5b \
  --kid my-registered-key \
  --scope adr:query --scope adr:review)
# $TOKEN is exactly the access token — nothing else on stdout.

--key <PATH> (or ACTUAL_SERVICE_ACCOUNT_KEY_FILE) reads the key from a file instead. The algorithm is inferred from the key (RSA → RS256, EC P-256 → ES256) unless --alg is given. --json swaps stdout for the full token response.

Output contract: the raw access token is the only thing on stdout, so TOKEN=$(actual mint-token …) captures exactly the token; all status goes to stderr. This matches the capture contract used by the other auth commands.

Scope decisions

A few calls the spec left open, surfaced here for review:

1. New top-level mint-token command, not an auth subcommand. feat(auth): add actual auth create-token for non-interactive auth #801 and feat(auth): add actual login --device for browserless sign-in #802 are still open and both restructure the auth surface; adding a sibling auth subcommand now would collide with them. A standalone command keeps this change independent. It can fold under auth once those land and that surface settles.
2. Token goes to stdout; persisting it is deferred. The load-bearing deliverable is the headless mint with the stdout-capture contract — an agent captures the token and uses it directly. Persisting into the existing on-disk credential store is deferred: that store models a browser-login user session (it requires a member id), which a service-account grant has no natural value for. A follow-up can add an opt-in service-account store if wanted.
3. RS256 and ES256 both supported — the server accepts both, so the client does too, inferring from the key type.
4. Key generation + registration is out of scope (assumes an already-registered key), as this change is scoped to the sign→mint core.

Test plan

Unit tests (src/auth/jwt_bearer.rs, src/cli/commands/mint_token.rs) and end-to-end binary tests (tests/mint_token_cli.rs):

• A signed assertion verifies under the server's exact validation for both RS256 and ES256 (ephemeral keypair generated at test time; verified with the pinned algorithm, required audience, and exp), and carries iss == sub == UUID, an accepted aud, exp - iat <= 300, a header alg ∈ {RS256, ES256} + kid, and a fresh unique jti per call.
• Forbidden algorithms (HS256, none, RS512, …) are refused; a non-UUID principal and a wrong-key-for-alg fail cleanly (no panic, no key material in the message).
• The mint request carries the right wire shape (grant_type, assertion, scope); a server invalid_grant surfaces cleanly with no stack trace or secret leakage.
• End-to-end against a mock token endpoint: the real binary signs, mints, and prints only the token to stdout (status on stderr); --json stays machine-parseable; a non-HTTPS non-loopback issuer is refused before anything is sent; a non-UUID principal exits non-zero with an empty stdout.
• cargo fmt --check, cargo clippy -- -D warnings, cargo test, cargo build --release all green.

A live end-to-end mint against the running server is not included: the server-side grant is not yet reachable from this repo's test environment (it needs a full app + database stack and a pre-registered key). The client is instead proven to produce a spec-compliant, server-verifiable assertion (the unit tests verify the signature under the server's exact validation) and to capture the token correctly.

Security notes

• Transport — reuses the existing HTTPS-only guard; a non-HTTPS, non-loopback issuer is rejected before any assertion leaves the process.
• No secret logging — the minted token's Debug impl redacts the token; nothing logs key or token material; the private key is read from a file or env, never a CLI arg.
• One-shot assertions — a fresh jti per call and a short (default 60s, ≤300s) lifetime bound the replay/leak window; the server anti-replays on the jti.
• No symmetric/unsigned algorithms — the client can only emit RS256 or ES256.

Test plan for a reviewer

• cargo test (unit + tests/mint_token_cli.rs)
• cargo clippy -- -D warnings and cargo fmt --check
• actual mint-token --help reads clearly for a headless caller

---

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

[davidmiuraactualai]

Actual Adversarial Review

Key findings

• 🛑 APR-001 P1 Parse the issuer before allowing plaintext loopback transport — still present at src/cli/commands/mint_token.rs:68.

---

🛑 APR-001 P1 Parse the issuer before allowing plaintext loopback transport

Location: src/cli/commands/mint_token.rs:68 at 21f8500712b06c641ee591d0daed98730e7ae193
Risk: A signed JWT bearer assertion can be sent over plaintext to an attacker-controlled hostname and replayed for an access token during its validity window.

Evidence and required correction

Issue: The new command signs its assertion before calling the shared transport guard. That guard decides whether HTTP is loopback with string prefixes in src/auth/oauth.rs:146, so http://localhost.evil.invalid, http://localhost@evil.invalid, and http://127.0.0.1.evil.invalid are all treated as local. The command can also set --aud to the real authorization-server identity, so an endpoint controlled by that host receives an assertion the authorization server can accept.

Evidence:

• Code: the new command invokes oauth::build_http_client(&base_url) only after build_and_sign_assertion; the predicate uses starts_with rather than parsed URL scheme and host identity.
• ADR: docs/adr/8d11aed5-d4a3-4ef6-937a-085f723bd997-adopt-secure-secrets-management-in-ci-cd-pipeline.md requires secret-handling paths to prevent credential exposure.
• Public: RFC 7523 section 2.1 defines the signed assertion as the JWT-bearer authorization grant submitted to the token endpoint; section 3 requires the authorization server to accept a valid assertion whose audience identifies that server within its expiration window.
• Verification: ACTUAL_SERVICE_ACCOUNT_KEY=<ephemeral P-256 PEM> cargo run --quiet -- mint-token ... --issuer http://localhost.evil.invalid --aud https://app.actual.ai signed the assertion and reached Token mint request failed: error sending request, rather than returning the expected HTTPS configuration error. cargo test auth::oauth::tests::test_build_http_client --lib -- --nocapture passed, but the current test only checks http://example.com and does not exercise prefix lookalikes.

Required correction: Parse the issuer as a URL before signing or dispatching. Permit plaintext only when the parsed scheme is HTTP and the parsed host is exactly an intended loopback host or loopback IP address; require HTTPS otherwise. Reject malformed URLs, user-info host confusion, and lookalike hostnames before an assertion can leave the process. Add coverage for the rejected lookalikes and the allowed loopback forms.

🤖 Corrective action — 🛑 APR-001 P1 — Option A: parsed loopback allowlist

Tradeoff: This preserves HTTP support for local development while making the exception depend on URL semantics rather than a textual prefix.

Fix APR-001 P1, Parse the issuer before allowing plaintext loopback transport, in actual-software/actual-cli at src/auth/oauth.rs:145 and src/cli/commands/mint_token.rs:68 on 21f8500712b06c641ee591d0daed98730e7ae193.

Problem: actual mint-token signs a JWT bearer assertion, then the shared HTTP guard accepts http://localhost.evil.invalid and related prefix lookalikes because it uses starts_with. With --aud set to the real authorization-server identity, an attacker controlling that hostname receives a bearer assertion that can be exchanged during its validity window.
Required invariant: no signed assertion or OAuth credential is sent over plaintext HTTP unless the parsed issuer host is an exact intended loopback host or loopback IP address.
Constraints: Follow AGENTS.md and src/AGENTS.md, including the secure-secrets ADR and comprehensive unit-testing requirement; honor .gitignore; preserve valid HTTPS issuers and supported local HTTP test endpoints.
Implement: parse and validate the issuer URL in the shared transport guard. Require HTTPS except for HTTP with an exact loopback hostname or loopback IP. Reject prefix lookalikes, user-info host confusion, malformed URLs, and non-loopback hosts before creating a client that can send the assertion.
Verify: Add unit coverage that rejects http://localhost.evil.invalid, http://localhost@evil.invalid, http://127.0.0.1.evil.invalid, and an IPv6 lookalike, while allowing http://localhost:<port>, http://127.0.0.1:<port>, and http://[::1]:<port>. Add a mint-token regression that fails with the HTTPS configuration error before any request. Run cargo test --workspace --features integration, cargo clippy -- -D warnings, and cargo fmt --check.
Do not: weaken HTTPS enforcement, send a real assertion to a non-loopback HTTP endpoint, log assertion or key material, or modify unrelated command behavior.

Copy into a coding agent to run.

🧭 ADR option — APR-001: Service-account assertion transport boundary · Policy: JWT-bearer assertions and OAuth credentials may use HTTP only after parsed URL validation establishes an exact loopback destination. — Create · Update

Architecture intent

🧭 Suggested ADR: Service-account assertion transport boundary — Create · Update

• APR-001 Policy: JWT-bearer assertions and OAuth credentials may use HTTP only after parsed URL validation establishes an exact loopback destination.

---

Review metadata

Important

One finding remains unresolved at head 21f8500712b06c641ee591d0daed98730e7ae193. This is the canonical remediation record for the PR.

Compared: upstream main at cfcae4cd84645417e7d8042517a69cbd55d22404 … PR head 21f8500712b06c641ee591d0daed98730e7ae193
CI: Build, Test, Lint, Coverage Enforcement, and CodeQL succeeded for this head; Live E2E was skipped. Local targeted guard tests passed, while the manual prefix-lookalike invocation reproduced the guard bypass.