Repository navigation
0.37.4, 0.37.5: clients that are no personal agents sign in with PKCE alone (public clients, off by default) - #22
Conversation
…with PKCE alone — public_clients, client_registration, public_client_refresh_lifetime, public_client_scopes on CompanyConfig, all off by default; a client ID metadata document that names no key is a public client verified by its domain, POST /oauth/register one that registered itself; tokens for one service, never the default token, never a Session; refresh tokens rotated, one used twice ends the sign-in; public_client_sign_ins and revoke_public_client_sign_in for the owner. Tests: test_public_clients (36)
… (publicClients): a public client, such as an MCP client, signs in with PKCE alone at Direct Sign-In's authorization endpoint, verified by its domain (a client ID metadata document that says token_endpoint_auth_method none and names no key, read by the resolver's optional resolve_public) or, with client_registration, registered at POST /oauth/register (RFC 7591), unverified. Its tokens are Bearer tokens for one service named as resource in every request (resource_servers, the MCP server), never the default token, refused at every endpoint of the protocol; no Session, no operation. Refresh tokens rotate and one used twice ends the sign-in, 30 days. Redirect URIs loopback or HTTPS, compared as text; an unverified client's errors are pages. authorization_request says client_class, verified, redirect_host, resource. Registration bounded by address. public_client_sign_ins and revoke_public_client_sign_in for the owner. In both SDKs, additive, off by default. Docs: guides/company, Other clients than personal agents. Tests: test_public_clients (36), public-clients.test.mjs (33), a docs example case
There was a problem hiding this comment.
🟡 Changes recommended
Public sign-in tokens can remain usable beyond grant expiry when owners can no longer revoke them, and malformed registration metadata can trigger an uncaught TypeError.
2 open issues
What changed in this PR
This PR extends the Python and TypeScript company servers with opt-in, PKCE-only sign-in for public clients such as MCP clients, separate from personal-agent Sessions.
Changes:
- Adds public-client metadata resolution, optional registration, and resource-bound OAuth flows.
- Adds consent trust details, public sign-in management, and protocol-boundary checks.
- Adds tests and documentation, and updates the SDK release to 0.37.4.
| File | Description |
|---|---|
src/reactor.ts |
Updates the core plugin version. |
src/models.ts |
Adds public-client metadata and redirect validation. |
src/index.ts |
Exports public-client models and helpers. |
src/identity.ts |
Resolves public metadata through the shared fetch path. |
src/company/testing.ts |
Adds registration record samples for store conformance. |
src/company/store.ts |
Adds registration records and public-client grant fields. |
src/company/service.ts |
Implements public OAuth, consent, registration, and MCP handling. |
src/company/points.ts |
Adds optional public-client resolution. |
src/company/node.ts |
Supplies peer addresses for registration limits. |
src/company/index.ts |
Wires public metadata resolution and updates the plugin version. |
src/__tests__/public-clients.test.mjs |
Adds public-client flow and security-boundary tests. |
src/__tests__/company.test.mjs |
Updates consent-summary expectations. |
personal_agent_protocol/reactor.py |
Updates the core plugin version. |
personal_agent_protocol/models.py |
Adds public-client metadata and redirect validation. |
personal_agent_protocol/identity.py |
Fetches public metadata through shared identity handling. |
personal_agent_protocol/company/testing.py |
Adds registration record samples for store conformance. |
personal_agent_protocol/company/store.py |
Adds public-client records and serialization support. |
personal_agent_protocol/company/service.py |
Implements public OAuth, consent, registration, and MCP handling. |
personal_agent_protocol/company/points.py |
Defines the optional public-client resolver interface. |
personal_agent_protocol/company/asgi.py |
Supplies peer addresses for registration limits. |
personal_agent_protocol/company/__init__.py |
Exports public-client APIs and wires resolution. |
personal_agent_protocol/__version__.py |
Sets the Python SDK version to 0.37.4. |
personal_agent_protocol/__tests__/test_hosted_pages.py |
Checks the expanded consent summary. |
personal_agent_protocol/__tests__/test_docs_examples.py |
Checks the public-client configuration example. |
personal_agent_protocol/__init__.py |
Exports PublicClientMetadata. |
package.json |
Sets the TypeScript package version to 0.37.4. |
docs/docs/sdk/typescript-api.mdx |
Lists new public-client exports. |
docs/docs/sdk/python-api.mdx |
Lists the public-client metadata model. |
docs/docs/releases/compatibility.mdx |
Records the additive 0.37.4 release. |
docs/docs/protocol/conformance-report.mdx |
Updates the reported SDK version. |
docs/docs/guides/company.mdx |
Documents configuration, consent, limits, and client boundaries. |
CHANGELOG.md |
Summarizes the public-client release. |
Review effort: Balanced
| family, | ||
| ...(resource === undefined ? {} : { resource }), | ||
| ...(jkt === undefined ? {} : { dpopJkt: jkt }), | ||
| ...(options.isPublic === true ? { public: true as const } : {}), |
There was a problem hiding this comment.
Fixed in 83eec98, in both SDKs. A public client's access token now expires with its sign-in at the latest, and expires_in says so; a public token whose original grant is missing or expired, or whose family record is gone or revoked, is refused wherever a token is read (_access_token / #accessToken, so the company's own MCP server and access_token_for). Tests, failing on the head before: a refresh one minute before the 30 days end gives expires_in ≤ 60 and is refused at the resource server at the deadline; a token whose grant or family record is gone is refused.
| if ( | ||
| not isinstance(grants, list) | ||
| or AUTHORIZATION_CODE_GRANT not in grants | ||
| or any(grant not in {AUTHORIZATION_CODE_GRANT, REFRESH_TOKEN_GRANT} for grant in grants) |
There was a problem hiding this comment.
Fixed in 83eec98. Each grant type is checked to be a string before the lookup (scope too), and the endpoint now turns anything a body makes go wrong that no check names into invalid_client_metadata, logged whole so a real bug is still seen. The TypeScript twin did not crash here (includes on mixed values) but got the same string check and the same outer handler. Tests, failing on the head before: a table of every member the endpoint reads with eleven malformed values each, entries of the wrong type, bodies nested 8000 deep, and client ID metadata documents of any shape; all 400.
…t an assertion ask the rate limit, and a policy answers for public clients apart (review of #22). A client that registered and never signed in is forgotten after an hour, and kept client_registration_lifetime from each sign-in, so registering from many addresses fills nothing; a token or revocation request without a client assertion asks the host's rate limit with public:{address} before the client it names is looked at or fetched; an optional allows_public (allowsPublic) on the client policy lets a company that lists its personal agents take public clients, or none, and is asked wherever a public client is. The docstrings say a code is spent once it is taken. Tests: an intercepted personal agent's code posted without an assertion gives nothing and is spent; the return host with a port and an IPv6 loopback; test_public_clients (40), public-clients.test.mjs (37)
…exactly what to send. The refusal's error_description says to send "token_endpoint_auth_method": "none" (never assumed when left out, no other method taken) with no client_secret, jwks or jwks_uri, and to sign in with the authorization code grant and PKCE (S256); the guide says a registration that leaves the method out, or names client_secret_post, is invalid_client_metadata. Tests: both SDKs. (The counts of the commit before: test_public_clients 39, public-clients.test.mjs 36.)
…ration is never an error of ours (review of #22). A public client's access token expires with its sign-in at the latest (expires_in says so), and one whose sign-in is over, ended or no longer on record is refused wherever a token is read (_access_token: the MCP server, access_token_for): thirty days from the consent hold exactly, where a refresh just before the end gave a token good for an hour more that its owner could no longer list or revoke. Registration checks each grant type is a string before looking it up (a list holding an object raised TypeError, a 500), scope too, and anything a body nobody signed makes go wrong that no check names is invalid_client_metadata, logged whole. A client's document of any shape is refused, not raised. Tests, failing on the head before: a refresh a minute before the end gives expires_in ≤ 60 and is refused at the resource server at the deadline; a token whose sign-in or family record is gone; tables of malformed registrations and documents, bodies nested 8000 deep; what no check foresaw is logged. test_public_clients (44), public-clients.test.mjs (41)
…nt, whatever it asked for. POST /oauth/register takes token_endpoint_auth_method left out, none, client_secret_post or client_secret_basic, registers a public client each time and says so (token_endpoint_auth_method none, no client_secret, no client_secret_expires_at; RFC 7591 §3.2.1), where 0.37.4 took only an explicit none. Unchanged: a registration naming a client_secret, jwks or jwks_uri of its own is refused, so a personal agent can't register as a public client; any other method is refused; the grant types, PKCE S256 and the redirect rules. A token or revocation request without an assertion that carries a client secret, in its form or as HTTP Basic, is invalid_client and spends nothing: no secret is issued, checked or ignored. In both SDKs. Docs: guides/company. Tests: each of the four registers as public and signs in; a named key or secret, and other methods, refused; a secret at the token and revocation endpoints refused without spending the code or the refresh token; test_public_clients (46), public-clients.test.mjs (43)
…the guide and the docstrings (review of 0.37.5). A library that sends a public client's client_id as HTTP Basic with an empty password is refused as one sending a secret is: the client_id goes in the form. The 401 names no WWW-Authenticate scheme on purpose, since naming Basic would say Basic works. Tests: an empty-password Basic header, both SDKs


What
A company may let clients that are no personal agents sign in: public clients, such as MCP clients, which authenticate with nothing but PKCE. In both SDKs, additive, and off by default: a company that turns nothing on behaves exactly as before. Released as 0.37.4.
public_clients(publicClients): public clients sign in at Direct Sign-In's authorization endpoint (authorization code + PKCE S256).token_endpoint_auth_method: noneand names nojwks_uri,jwksorclient_secret, read through the client resolver's new optionalresolve_public(resolvePublic), with the same fetch rules as a personal agent's (HTTPS, no redirect, bounded, URL safety policy).client_registration(clientRegistration):POST /oauth/register(RFC 7591), public clients only, unverified.resourcein the authorization request, the code exchange and every refresh (resource_servers, the company's own MCP server). Never the default token.refresh_reuse_revokessays; 30 days from the sign-in (public_client_refresh_lifetime).authorization_requestaddsclient_class,verified,redirect_host, andresource; the company's own page says "Unverified app" and where the browser goes back to.public_client_sign_ins,revoke_public_client_sign_in.noneintoken_endpoint_auth_methods_supportedandauthorization_response_iss_parameter_supportedonly withpublic_clients;registration_endpointonly withclient_registration.Guide:
docs/docs/guides/company.mdx, Other clients than personal agents.The protocol's boundaries
access_token_forkeeps asking the client policy, and returnspublicon the record.What was checked as an attacker
127.0.0.1.evil,127.1, decimal IPs,0.0.0.0, bad ports, added path or querya redirect URI is loopback or HTTPS and nothing else,matches exactly but for a loopback port,a request with another redirect is never redirectedan unverified client's errors are pages and a verified one's redirectsclient_idis never a URLa personal agent cannot become a public client,a document is one class of client and never bothPKCE is the only proof and is never skippedresourceconfusionresourcerequired at every step and equal throughout; never the default token or the conversation endpointa public client never gets the default tokena refresh token is rotated and one used twice ends the sign-inRateLimit, then a count per address), 16 KiB, 10 redirect URIs, names bounded, registrations expireregistration is limited by address,the host's rate limit is asked by address before anything is readclient_idis never fetcheda document at a private address is never fetched,...redirects or names another URL is refused,the client policy is asked each time and before anything is fetchedX-Frame-Options: DENY,frame-ancestors 'none'; names escaped, and refused when they hold control or direction marksa client verified by its domain signs in...,a decision counts once and the name is shown as text,a name holds nothing that hides or reorders textstateandississ(RFC 9207) and the request'sstate, error answers toothe client policy is asked each time...,a verified client is read again at each token requestAfter review
invalid_client_metadata, logged whole. Tables of malformed bodies and documents in both SDKs.client_registration_lifetimefrom each sign-in, so registering from many addresses fills nothing.public:{address}before the client they name is looked at or fetched.allows_public), so a company that lists the personal agents it serves can take public clients, or none.0.37.5, on top (13eda49)
0.37.4 was tagged from 83eec98 on this branch. One change since, released as 0.37.5:
token_endpoint_auth_methodleft out,none,client_secret_postorclient_secret_basicregisters a public client, and the response saysnonewith noclient_secret(RFC 7591 §3.2.1). 0.37.4 took only an explicitnone, which refused MCP clients whose SDK leaves the method out.client_secret,jwksorjwks_uriof its own, or any other method, is refused; PKCE S256, the grant types and the redirect rules.invalid_client, before the code or refresh token is looked at. Refused rather than ignored: a request is never served as if a secret had been right.Not in this change
Tests
test_public_clients.py(46),public-clients.test.mjs(43), one docs example case; the existing suites pass unchanged but for the consent summary's key set.