Repository navigation
feat(keycardai-oauth): add a resource token source backed by the local Keycard agent - #382
benburkert wants to merge 3 commits into
Conversation
…l Keycard agent AgentTokenSource asks the Keycard CLI over KEYCARD_SOCKET for an access token for a named third-party resource, so an application running beside the CLI needs no client secret of its own. The CLI mints the token once a human approves the request, and remembers the approval rather than the token, so tokens are cached per source until 30 seconds before they expire, and concurrent first requests share one mint. It ports keycardai/go-sdk#51: the Connect unary JSON call to AgentService/IssueToken, the optional app_id the CLI resolves to an application name, AgentError with predicates for each refusal code, and ResourceAuth to attach the token to an httpx.AsyncClient's requests. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…e through the local Keycard agent agent_resource_access is the shape for a FastMCP server running on a developer's machine beside the Keycard CLI: it holds no client secret and has no inbound user token to exchange, so its tools ask the CLI for a resource token through keycardai-oauth's AgentTokenSource, and a human approves each new resource. The resource and the URL the token is sent to are configuration rather than tool arguments, and the token itself never appears in tool output, which reaches the model. The smoke test skips when the installed keycardai-oauth predates AgentTokenSource, which is what the sibling-floors job installs. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
…ion ids in the agent_resource_access example Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
|
Caution Review the following alerts detected in dependencies. According to your organization's Security Policy, you must resolve all "Block" alerts before proceeding. Learn more about Socket for GitHub.
|
Release previewkeycardai-oauth 0.33.2 → 0.34.0 (minor)
No other package releases. This comment was automatically generated by the release preview workflow. |
|
Superseded by #435, generated from the merged Local Agent Token Source spec (keycard-sdk-spec 21b11f0). Unlike this draft it resolves the daemon's default socket (integration rows 7 and 8) and leaves caching to the agent. |
The gap
A Python application that needs to call a third-party resource has no way to get a credential for it from
keycardai-oauth. Every flow here either authenticates the client to the authorization server or exchanges an inbound user token. Nothing answers "give me a token for resource X", which is what an application running beside the Keycard CLI needs, and why it otherwise still carries a client secret.What this adds
The Python port of keycardai/go-sdk#51.
ResourceTokenSourceasync resource_token(resource, *scopes) -> TokenResponseAgentTokenSourceKEYCARD_SOCKETvia the agent'sIssueTokenprocedure;socket,workload,app_id,org,zoneResourceAuthhttpx.Auththat attaches a resource token to every request of anhttpx.AsyncClientAgentError,AgentCode,is_declined,is_rate_limited,is_prompter_unavailable,is_authorization_required,is_application_not_found,is_unavailablePlus two examples:
packages/oauth/examples/agent_token_source(a plain script) andpackages/fastmcp/examples/agent_resource_access(a FastMCP server whose tools reach a resource through the agent and never put the token in tool output, which reaches the model).No new dependencies; the Unix socket is reached with
httpx.AsyncHTTPTransport(uds=...).CLI compatibility
/keycard.agent.v1.AgentService/IssueToken. Connect addresses a procedure by URL path, so a CLI predating it answers 404.app_idrelies on keycardlabs/cli#1255–#1257, all merged. It is sent asappIdonly when set. A CLI without those PRs drops the unknown field. With them, the server labels the id self-asserted in the approval prompt and audit log, resolves it to the application's name in the session's zone, and forwards it to the authorization server.keycard_declared_app_idtoken claim waits on keycardlabs/svc-sts#739, still open. Until it deploys, a mint that declares an id succeeds with no claim. Theagent_resource_accessexample prints bothkeycard_declared_app_idandkeycard_app_idso the difference is visible.Decisions rather than details
These follow go-sdk#51; see its description for the longer reasoning.
ResourceAuthbinds to one resource rather than deriving one from each request URL. Normalizing here would be a second opinion about what was requested.(resource, scopes)until 30s before expiry, and concurrent first requests for the same key share one mint behind a per-keyasyncio.Lock. A credential with no expiry (a static API key, keycardlabs/cli#1198) is cached indefinitely. The agent remembers the human's approval, not the token, so without a client-side cache every request costs an authorization server round trip.asyncio.timeout.Authorizationheader.ResourceAuth.sync_auth_flowraises rather than inheriting httpx's default, which would pass the request through unauthenticated.expiresAtis parsed by hand: protojson emits up to nine fractional digits, whichdatetime.fromisoformatrejects before Python 3.11.Verified end to end
Beyond the unit tests (
test_agent.py, which drive the source through a mock transport), the FastMCP example was driven against a live Keycard daemon and a live authorization server on 2026-10-14: k3dlocaldev, a CLI built from keycardlabs/cli#1256,ITL_PROMPT=native. A separate driver reached the server only through MCP tool calls over stdio, and a resource server verified the bearer against the zone's JWKS rather than decoding it.issis the zone issuer,audincludes the resource; the first call writes exactly onetoken_issueaudit record and the repeat writes none200, signature verified against the zone JWKSnot_found, with no promptpermission_deniedThat CLI build predates #1257, so the run covers the local app-id lookup but not the forwarding, and the
keycard_declared_app_idclaim has not been seen on a real token.Open for review
TokenResponse.scopeechoes what was requested, not what was granted, the same open question as go-sdk#51.IssueTokenreturns only a token and an expiry; ask for no scopes and the field isNonewhile the token carries the session's full set.is_application_not_found's docstring lags go-sdk. go-sdk updated its equivalent to say thatnot_foundalso covers an id the authorization server refuses at the mint (keycardlabs/cli#1257). The code is the same here; only the docstring is out of date.Draft
Draft for review of the API shape, and until svc-sts#739 merges so the
app_idclaim isn't documented ahead of the server that stamps it. Locally:ruff check,cz check,ty check, and the oauth (603 passed, 89% coverage) and fastmcp (94 passed, 85%) suites pass.🤖 Generated with Claude Code