key-cape/docs/current-token-client.md

Shared current-token client and private CLI observations

Source preparation under proposed KEY-WP-0042 and the existing CUST-WP-0080 / NK48 / Apps operation and application obligations. This is a client of the issuer's optional online profile, not another issuer, PDP, approval service or application-local token registry. Native issuer/profile/consumer admission is still required. Actual operation/effect permission remains with existing owners.

One producer, two consumption surfaces

src/internal/authclient/online.go is the single implementation. The existing KeyCape executable exposes it as check-current-token, revoke-token and check-inactive-token for owner processes. Go consumers use the generated adapters/go/tokenstatus module and import keycape/pkg/tokenstatus through an exact pinned source/dependency lock. make tokenstatus-export generates that five-file module; make tokenstatus-check, ordinary make test and the root Go suite refuse drift. The sole client transformation is its first package declaration; all remaining bytes and the shared JOSE primitive are exact. No policy evaluator, signing key, credential, daemon or deployment is exported.

The client uses the existing producer internal/jose verifier. Its additive VerifyTyped path requires the actual RS256 / JWT producer header; legacy Verify callers retain their existing type policy. Keys are independently admitted public JWKS, never fetched from the status response or discovered by the token. The minimal generated module uses Go 1.23 and standard libraries. Its file boundary is the current Linux owner profile: POSIX mode checks do not establish Windows ACL behavior or a broader platform admission.

Current status is an authenticated fact

Online human PKCE ID tokens additionally carry the exact access-token at_hash binding described in online-token-status.md. This client verifies access-token facts; a consumer that also uses an ID token separately authenticates that token, checks its purpose, and joins its signed hash, identity, issuance, assurance and tenant provenance to the exact access grant. Neither token substitutes for the other. The online profile's hash is additive; disabled legacy issuance is unchanged.

OnlineClient.Check(ctx, token, ExpectedIdentity{...}) validates the signature, issuer, exact single resource audience, subject, tenant, human/service type, optional authorized-party binding, access-token purpose, unique jti and integer issued/expiry/not-before bounds before reading the private caller credential. It bounds identity by expiry and an independently admitted token age (at most one hour), then performs a new authenticated introspection. It joins every returned identity/client/audience/jti/scope/time field to those signed facts. After network I/O it checks time again and reloads JWT trust so a delayed answer cannot retain expired facts or a withdrawn signing key. No positive is cached.

The explicit HTTPS issuer origin supplies the exact /introspect and /revoke paths; redirects, query/fragment/ambiguous issuer paths, environment proxies and ambient transports are not used. CA, JWKS and private caller credential files are reread for each operation with regular-file/mode/size guards. File opens do not block on FIFO replacement. Private credentials can be atomically rotated without retaining a cached value. Requests have a five-second bound and responses a 64 KiB bound. Duplicate/null/missing/extra fields, mismatched facts, non-JSON or cacheable status responses and unavailable/unauthenticated transport refuse with one fixed error. Secret, token and response values are never part of errors.

CurrentToken.Claims() returns a separate copy of verified signed facts. Those facts remain snapshots: original authentication time is not the current lookup time. Minimum assurance/authentication age, tenant provenance, current groups, resource/action policy, exact approval and effect authority remain the existing consumer profile's obligations. A fresh status response is not a new MFA act or permission. A Forgejo sign-in token does not grant release-write or inverse authority, and no operator client/route is selected by this source package.

Negative scope and cleanup

ObserveInactive performs an independent read-only status lookup. It never infers inactivity from transport failure, malformed output or an unsuccessful positive check. Revoke sends the exact token, requires an empty successful response and then obtains that separate negative readback. Both return only InactiveForClient: the exact digest is currently inactive for the configured client. Unknown and other-client tokens have the same negative response.

That result alone cannot prove original grant ownership, global revocation or a completed operation's cleanup. The owner retains its independently authenticated original issuance/current-positive evidence, exact token digest/jti and operation correspondence before mapping a negative observation to a parent-session receipt. Cleanup can continue after business-token freshness/key withdrawal; it creates no business authority. Unavailable/ambiguous cleanup remains unverified and requires the existing durable owner retry/recovery path. It is not success.

Existing CLI

The public admission file contains only references and independently admitted bindings; for example (paths/client are placeholders, not operational defaults):

{
  "issuer": "https://owner-admitted-issuer.example",
  "audience": "owner-admitted-resource",
  "client_id": "owner-admitted-confidential-client",
  "ca_file": "/run/owner-identity/issuer-ca.pem",
  "jwks_file": "/run/owner-identity/admitted-jwks.json",
  "secret_file": "/run/owner-identity/current-client-credential",
  "max_token_age": "5m"
}

Use an existing owner-acquired private KeyCape token JSON file, and the access token's exact sha256: digest from the owner-bound session/transaction record. No token or client credential goes in argv. Follow the existing Warden routing / owner-native acquisition and custody path; this source adds no credential lane.

keycape check-current-token --admission-file /ABS/profile.json --token-file /ABS/private-token.json --token-sha256 sha256:OWNER_BOUND_DIGEST --subject OWNER_EXPECTED_SUBJECT --tenant OWNER_EXPECTED_TENANT --principal-type human --out /ABS/PRIVATE-DIR/new-observation.json
keycape revoke-token --admission-file /ABS/profile.json --token-file /ABS/private-token.json --token-sha256 sha256:OWNER_BOUND_DIGEST --out /ABS/PRIVATE-DIR/new-cleanup-observation.json
keycape check-inactive-token --admission-file /ABS/profile.json --token-file /ABS/private-token.json --token-sha256 sha256:OWNER_BOUND_DIGEST --out /ABS/PRIVATE-DIR/new-independent-negative.json

The placeholders deliberately do not form an operational command. Current checks require explicit expected subject/tenant/type. Negative/cleanup commands refuse those business-identity flags because they report only the bounded client status. Duplicate flags and duplicate/unknown/null input fields refuse. The token file must be private, the digest must match the exact parsed access token, and the new observation must have a 0700 parent outside Git. Outputs are exclusive 0600 files; failures remove only their own inode and cannot delete another attempt's replaced file. Standard output/errors expose fixed status, not claims or credential values.

keycape.current-token-observation.v1 is a private, unsigned producer command result, not a portable execution receipt. Current output includes bounded identity/token references and signed assurance/tenant-provenance facts; it omits bearers, credentials and group/role snapshots. Negative output states its client scope. The invoking owner authenticates exact binary/config/custody and binds its own case, acceptance, descriptor, source/target, principal, transaction and effect. Local file presence, digests or a successful command do not supply those grants.

Scope of verification

Source checks use actual token/status handlers over isolated HTTPS, actual human PKCE claim construction and the same CLI implementation. The separate cross-owner fixture runs a built executable, generated public Go consumer and actual Warden Executor/SQLite in distinct Python processes. Synthetic case/catalog/owner attestations and a disposable file target do not establish Forgejo/browser acceptance, real-factor possession, production custody or approved native effects. The online issuer profile, owner mappings and source/package/type admission remain under review; all corresponding native gates stay open.