feat!: lazy credential resolution and populate PKCE identity

[jpage-godaddy]

Context

Two auth defects surfaced via a consumer CLI (gddy), and investigating them exposed a deeper design issue:

1. Local commands provoked auth when they shouldn't. A command like env list only reads local state, yet it triggered the OAuth/PKCE browser flow. Root cause: middleware resolved the credential eagerly for every command not explicitly marked no_auth(true), before the handler ran — so authors had to remember to annotate every read-only/local command, and --schema/--dry-run still triggered a login.
2. auth status showed a blank identity. PkceAuthProvider built its Credential with ..Credential::default() and never inspected the token for identity claims.

What changed

Lazy credential resolution

• New CredentialResolver (memoizing, Clone) on CommandContext. The auth flow runs only when a handler or authorizer calls .resolve() / .try_resolve(). Commands that never ask — and --schema/--dry-run — skip authentication entirely. No per-command no_auth annotation needed.
• Middleware::run builds the resolver and threads it through authz + handler; identity for audit/activity is read post-hoc via peek(); the auth-error audit classification is preserved.
• Convenience: ctx.credential().await? and ctx.try_credential().await?.

Populate identity in PkceAuthProvider

• Decode the access-token JWT payload (display-only, no signature verification) and fill identity/sub from a configurable, prioritized claim list (with_identity_claims, default email, preferred_username, username, name, sub). Opaque/non-JWT tokens degrade to blank. Works for already-stored tokens with no re-login.

Breaking changes (pre-1.0)

• CommandContext.credential: Option<Credential> → CredentialResolver.
• RuntimeCommandSpec::new / new_typed closures receive a CredentialResolver first arg (handlers that ignore it compile unchanged).
• Authorizer::authorize receives &CredentialResolver instead of Option<&Credential>.

Verification

• cargo fmt --all --check, cargo clippy --all-targets -- -D warnings, RUSTDOCFLAGS='-D warnings' cargo doc --no-deps, cargo test --all-targets, cargo test --doc — all green; missing-docs: 0.
• New tests: JWT decode / identity-claim priority / with_identity_claims override; lazy-behavior (zero resolutions when the credential is ignored, one shared resolution across authz+handler, zero for --dry-run).

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR changes the CLI engine’s auth model to lazy credential resolution (so auth only occurs when a handler/authorizer explicitly requests it) and fixes PKCE credentials to populate Credential.identity/sub by decoding access-token JWT claims for display/audit purposes.

Changes:

• Introduces CredentialResolver (memoized + cloneable) and threads it through middleware, handlers, and authorizers to avoid eager auth.
• Updates command/context APIs to use the resolver and adds convenience ctx.credential().await? / ctx.try_credential().await?.
• Enhances PkceAuthProvider to derive identity/sub from decoded JWT claims (configurable claim priority) and adds tests.

Reviewed changes

Copilot reviewed 11 out of 11 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
tests/streaming.rs	Updates streaming test handler to explicitly resolve credentials under lazy auth.
tests/foundation.rs	Updates many middleware/runtime tests for resolver-based auth; adds new lazy-resolution tests.
tests/derive_bridge.rs	Updates derive bridge tests to accept CredentialResolver in typed handlers.
src/middleware.rs	Adds CredentialResolver and refactors middleware flow to resolve credentials lazily + memoize.
src/lib.rs	Re-exports CredentialResolver as part of the public API surface.
src/command.rs	Updates CommandContext + runtime handler signatures to use CredentialResolver and adds convenience methods.
src/auth/pkce.rs	Populates Credential.identity/sub by decoding JWT payload claims; adds configuration + tests.
examples/typed.rs	Updates example typed handler signature to accept CredentialResolver.
docs/design.md	Updates design docs to reflect resolver-based handler/authorizer behavior.
docs/concepts.md	Updates conceptual docs and code snippets to use CredentialResolver + lazy resolution guidance.
AGENTS.md	Updates contributor guidance to explain lazy credential resolution and reduced need for no_auth(true).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 11 out of 11 changed files in this pull request and generated no new comments.

[jgowdy-godaddy]

Follow-up: make the auth requirement fail-closed by default

I pushed two commits (ab18c07, 8d9d2a6) that build on this work. The lazy CredentialResolver, single-resolution memoization, peek()-based identity, and the PKCE JWT identity decode are unchanged — they're the right foundation. The change is to the default direction of the auth policy and one classification detail.

Why

With resolution driven entirely by the handler, a command that doesn't mark no_auth but whose handler never calls resolve() runs unauthenticated, and its audit/activity identity is blank. That makes the default fail-open: forgetting to annotate a gated command lets it execute without a credential. I think the safer default is the inverse — if an annotation is missing, the command should over-prompt, not under-authenticate.

What changed

• CommandSpec.no_auth: bool → CommandSpec.auth: AuthRequirement (Required | Optional | None), default Required. no_auth(true) still works (maps to None); added auth_optional() and auth(..).
• For Required commands the engine resolves the credential before the handler runs and renders auth-error on failure — so a gated command can't run unauthenticated even if its handler ignores the credential, and its identity is always recorded.
• --schema/--dry-run short-circuit before that forced resolve, so they still never trigger an auth flow. Optional defers to the handler (the env list / enrich-if-logged-in case); None never authenticates.
• Auth-error classification now keys off the error a handler/authorizer actually returns (CliCoreError::is_auth(), resolution failures marked at the resolver boundary) instead of a sticky resolver flag. This fixes a case where an Optional handler that best-effort resolves, swallows the failure, and then fails for another reason would have the later error mistagged as auth-error.

Net effect on the breaking surface

Still one breaking release. Surviving breaks: the three from the original commit (CommandContext.credential, handler closures, Authorizer::authorize), plus CommandSpec.no_auth→auth and MiddlewareRequest.no_auth→auth. Builder call sites using .no_auth(true) are unaffected. release-please (bump-minor-pre-major) will cut 0.2.0.

Local: fmt, clippy --all-targets --all-features -D warnings, test --all-targets --all-features, test --doc, doc -D warnings all green; missing-docs: 0. Docs (AGENTS.md, docs/concepts.md, docs/design.md) updated to describe the fail-closed default. Happy to adjust naming (AuthRequirement/auth_optional) or split the classification fix into its own PR if you'd prefer.