Skip to content

0.37.4, 0.37.5: clients that are no personal agents sign in with PKCE alone (public clients, off by default) - #22

Merged
echarles merged 7 commits into
mainfrom
feat/public-mcp-clients
Nov 18, 2026
Merged

echarles merged 7 commits into
mainfrom
feat/public-mcp-clients

Conversation

@echarles

@echarles echarles commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

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).
    • Verified by its domain: a client ID metadata document that says token_endpoint_auth_method: none and names no jwks_uri, jwks or client_secret, read through the client resolver's new optional resolve_public (resolvePublic), with the same fetch rules as a personal agent's (HTTPS, no redirect, bounded, URL safety policy).
    • Registered itself, with client_registration (clientRegistration): POST /oauth/register (RFC 7591), public clients only, unverified.
  • Tokens: Bearer, for one service named as resource in the authorization request, the code exchange and every refresh (resource_servers, the company's own MCP server). Never the default token.
  • Refresh tokens: rotated at every use; one used twice ends the whole sign-in whatever refresh_reuse_revokes says; 30 days from the sign-in (public_client_refresh_lifetime).
  • Consent: authorization_request adds client_class, verified, redirect_host, and resource; the company's own page says "Unverified app" and where the browser goes back to.
  • Owner: public_client_sign_ins, revoke_public_client_sign_in.
  • Metadata: none in token_endpoint_auth_methods_supported and authorization_response_iss_parameter_supported only with public_clients; registration_endpoint only with client_registration.

Guide: docs/docs/guides/company.mdx, Other clients than personal agents.

The protocol's boundaries

  • A public client's token is refused at every endpoint of the protocol (conversations, operations, tasks, feedback, browser session, APIs), alone or inside a personal agent's Session, and at the MCP server once a Session header comes with it. No Session is ever started for it.
  • A personal agent can't downgrade: which class a client is of comes from its own document, never from the request. A request without an assertion never refreshes a personal agent's sign-in or exchanges its code, and a public client's code or refresh token is nothing to a personal agent's assertion.
  • At the company's own MCP server a tool that needs approval returns an error and no operation.
  • access_token_for keeps asking the client policy, and returns public on the record.

What was checked as an attacker

Attack What stops it Test
Redirect URI tricks: user information, fragment, backslash, spaces and controls, upper-case host or scheme, other schemes, 127.0.0.1.evil, 127.1, decimal IPs, 0.0.0.0, bad ports, added path or query Redirect URIs are read as text with one regular expression per form, never through a URL parser, and compared exactly; only a loopback port may differ (RFC 8252 §7.3) a redirect URI is loopback or HTTPS and nothing else, matches exactly but for a loopback port, a request with another redirect is never redirected
The authorization endpoint as an open redirector (anyone registers any HTTPS redirect) An unverified client's errors are pages, never redirects; a redirect only follows the person's decision an unverified client's errors are pages and a verified one's redirects
Mix-up between the two client classes One document is one class; codes, refresh tokens and sign-ins carry their class and are used only by it; a registered client_id is never a URL a personal agent cannot become a public client, a document is one class of client and never both
Authorization code injection, PKCE skipped or downgraded S256 only, challenge and verifier checked as RFC 7636 writes them; the code is bound to client, redirect and resource; a refused exchange spends the code PKCE is the only proof and is never skipped
resource confusion resource required at every step and equal throughout; never the default token or the conversation endpoint a public client never gets the default token
Refresh token replay Rotation, and reuse ends the family; the class is checked before reuse is acted on, so an unauthenticated request can't end a personal agent's sign-in a refresh token is rotated and one used twice ends the sign-in
Registration flooding Rate limit by address before the body is read (host's RateLimit, then a count per address), 16 KiB, 10 redirect URIs, names bounded, registrations expire registration is limited by address, the host's rate limit is asked by address before anything is read
Metadata document SSRF Same fetch path as a personal agent's document: URL safety policy, no redirects, bounded; a blocked client_id is never fetched a 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 fetched
Consent page clickjacking, name spoofing X-Frame-Options: DENY, frame-ancestors 'none'; names escaped, and refused when they hold control or direction marks a 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 text
state and iss Every answer of the authorization endpoint carries iss (RFC 9207) and the request's state, error answers too same tests
Ordering of authentication and authorization Token endpoint: the client (policy, then registration or document, again at each request), the grant type, the resource, then the grant the client policy is asked each time..., a verified client is read again at each token request

After review

  • No token outlives its sign-in. A public client's access token expires with its sign-in at the latest, and one whose sign-in is over, ended or no longer on record is refused wherever a token is read: the 30 days hold exactly.
  • A malformed registration is never a 500. Every member read is type-checked before it is used, and anything a body makes go wrong that no check names is invalid_client_metadata, logged whole. Tables of malformed bodies and documents in both SDKs.
  • An unused registration lasts an hour, and client_registration_lifetime from each sign-in, so registering from many addresses fills nothing.
  • Requests without an assertion ask the host's rate limit with public:{address} before the client they name is looked at or fetched.
  • A policy may answer for public clients apart (allows_public), so a company that lists the personal agents it serves can take public clients, or none.
  • A registration that is not a public client's is told exactly what to send.

0.37.5, on top (13eda49)

0.37.4 was tagged from 83eec98 on this branch. One change since, released as 0.37.5:

  • A client that registers itself is registered as a public client, whatever it asked for. token_endpoint_auth_method left out, none, client_secret_post or client_secret_basic registers a public client, and the response says none with no client_secret (RFC 7591 §3.2.1). 0.37.4 took only an explicit none, which refused MCP clients whose SDK leaves the method out.
  • Unchanged: a registration naming a client_secret, jwks or jwks_uri of its own, or any other method, is refused; PKCE S256, the grant types and the redirect rules.
  • A token or revocation request without an assertion that carries a client secret (form or HTTP Basic) is 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

  • CORS on the token and registration endpoints, for MCP clients that run in a browser: a host adds it.
  • Custom URI schemes for redirect URIs.

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.

…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
Copilot AI balanced review requested due to automatic review settings November 18, 2026 12:29

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

Comment thread src/company/service.ts
family,
...(resource === undefined ? {} : { resource }),
...(jkt === undefined ? {} : { dpopJkt: jkt }),
...(options.isPublic === true ? { public: true as const } : {}),

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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)
@echarles echarles changed the title 0.37.4: clients that are no personal agents sign in with PKCE alone (public clients, off by default) 0.37.4, 0.37.5: clients that are no personal agents sign in with PKCE alone (public clients, off by default) Nov 18, 2026
…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
@echarles
echarles merged commit 3d1463e into main Nov 18, 2026
17 checks passed

This branch was successfully deployed

2 active deployments
pypi — 140d42ec Deployed Nov 18, 2026 by echarles via pypi #51
npm — 140d42ec Deployed Nov 18, 2026 by echarles via npm #51
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants