key-cape/docs/native-authentication.md

# Native caller authentication

KeyCape owns the `keycape service-token` and `keycape login` commands. They
produce issuer-verified JWTs in a new mode-0600 JSON file outside Git worktrees.
Existing files and symlinks are refused. Token responses and provider error
bodies are never printed. Commands exit nonzero on verification or delivery
failure and remove incomplete output files.

## Service exchange

Have the existing custody mechanism inject the registered client secret into a
named environment variable, then run:

```sh
keycape service-token --issuer https://kc.coulomb.social \
  --client-id rapp-qonto --scope qonto:read \
  --secret-env KEYCAPE_RAPP_QONTO_CLIENT_SECRET \
  --out /private/runtime/qonto-token.json
```

The output directory must already exist. No secret belongs on argv. The command
uses client_secret_basic with OAuth form encoding. The server must include the
matching decoding fix for secrets containing reserved characters. The Qonto
client ID and scope above follow the deployed KEY-WP-0006 registration.

For approval-engine clients, set `--audience approval-engine` explicitly; the
expected audience otherwise defaults to the client ID. Both requested scopes
and audience must match the issuer's static registration. The output contains
`access_token`, `token_type`, and `expires_in`; a service exchange has no ID token.
Re-exchange before expiry for renewal. There is no refresh token or credential
cache. Client disablement stops new issuance; already-issued JWTs expire normally.

## Browser login

Use a registered **public PKCE** client with an exact literal-loopback callback:

```sh
keycape login --issuer https://kc.coulomb.social \
  --client-id APPROVER_CLIENT_ID --audience approval-engine \
  --scope 'openid approval:approve' \
  --redirect-uri http://127.0.0.1:REGISTERED_PORT/callback \
  --out /private/runtime/approver-token.json
```

Replace the client ID and port with the approved registration. This command
prints a browser authorization URL and waits up to five minutes. The provider
handles password and MFA; KeyCape CLI never receives those credentials. Configure
`mfaRequired: true` on the approver registration. State, nonce and S256 PKCE are
fresh for each attempt. The listener binds before the URL is printed, validates
callback host/path/state, and closes when the attempt ends.

Both tokens are verified against same-origin HTTPS discovery/JWKS. Access tokens
bind the expected resource audience and requested scopes. ID tokens bind the
client ID, nonce and matching subject. There is no insecure TLS switch and no
HTTP redirect following during credential exchange. Cross-origin discovery
endpoints and confidential browser clients are intentionally unsupported.

## OpenBao login boundary

The existing ops-warden login route runs
`bao login -no-print -method=oidc -path=netkingdom role=<domain>`. That produces an
**OpenBao token**, unlike KeyCape's new issuer JWT output. These commands are not
interchangeable. KeyCape owns browser authentication and issuer JWTs; OpenBao's
role mapping, token store and enforcement remain platform-owned. Do not replace
that route with `keycape login` without adapting and verifying its consumer
contract. No ops-warden route is retired by this change.

## Qonto rotation boundary

Native exchange is implemented. Rotation still needs a coordinated custody and
provider update, not a wrapper around a raw KV read. The reviewed sequence is:

1. Resolve exact existing authority for
   `platform/workloads/rapp-qonto/keycape-client`, field `client_secret`, and
   `sso/keycape-rapp-qonto-client`, key `client-secret`.
2. Generate the successor inside the approved custody execution transport;
   retain the predecessor only there for bounded rollback and denial checks.
3. CAS-update that KV field while preserving siblings, update the matching
   Kubernetes delivery reference, and restart KeyCape in the agreed window.
4. Verify the new `qonto:read` exchange, predecessor rejection and excess-scope
   denial without exposing tokens; verify downstream readiness.
5. On failure, reconcile both custodians to the same version and reload KeyCape
   before declaring rollback complete. Record versions and outcomes, never values.

No general rotation command is shipped until that cross-owner transaction has
an admitted execution and rollback contract. Calling secrets-engine's KV
rotation alone would leave the provider and consumers inconsistent.

Steps 1-3 are custody's and are not automated here. Step 4, and the denial
checks step 5 depends on, are KeyCape's and now have a command.

## Verifying a live registration

`keycape verify-client` proves a deployed registration behaves as its contract
says, without writing a token file or printing any value. It is the evidence for
a rollout (KEY-WP-0013-T02) and for step 4 of the rotation sequence above.

```
keycape verify-client \
  -issuer https://kc.coulomb.social \
  -client-id secrets-engine-approval \
  -audience approval-engine \
  -scope "approval:read approval:consume" \
  -secret-env KEYCAPE_SECRETS_ENGINE_APPROVAL_CLIENT_SECRET \
  -expect-subject service:secrets-engine \
  -expect-tenant tenant:platform \
  -expect-roles secrets-engine \
  -deny-scope "approval:approve approval:revoke"
```

It checks, and prints one `PASS`/`FAIL` line per check:

- discovery resolves over HTTPS and every endpoint shares the issuer origin;
- the `client_credentials` exchange succeeds and its access token verifies RS256
  against the discovered JWKS, with exact issuer, audience and validity window;
- `principal_type` is `service`, and `sub`, `tenant` and `roles` match what the
  registration declares — exact comparison, no alias;
- the token carries **no scope that was not requested**, which the caller
  commands do not check: they prove every requested scope was granted, not that
  nothing extra came back;
- every `-deny-scope` is refused. A success there is the failure.

Add `-previous-secret-env` after a rotation to require that the predecessor is
refused. It also fails if the predecessor and current values are identical,
which means no rotation occurred.

Every check runs before the command reports, so one failure does not hide the
rest; the exit status is non-zero if any failed. Failures name the **claim**,
never the observed value — running this against production must not turn a
verification into a disclosure. Nothing is written to disk.

The command needs the client secret in the named environment variable, so it
runs wherever custody already delivers that value. It never reads OpenBao or
Kubernetes itself.