Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
70 changes: 70 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,76 @@

# Changelog

## 0.37.5 (2026-11-18)

A client that registers itself is registered as a public client, whatever it asked for. In
both SDKs; it concerns only a company with `client_registration` on.

- **`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: the response's `token_endpoint_auth_method` is `none`, with no `client_secret` and
no `client_secret_expires_at` (RFC 7591 §3.2.1: the server may replace what was requested,
and the client uses what is returned). 0.37.4 registered only a client that said `none`
itself, which refused MCP clients whose SDK leaves the method out or defaults to a secret.
- **Unchanged:** a registration that names 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
(`private_key_jwt`, an unknown one, one that is no text) is refused; grant types are
`authorization_code` and `refresh_token`; PKCE `S256` is mandatory; the redirect rules.
A client ID metadata document still says `none` itself.
- **A request that carries a client secret is refused.** A token or revocation request
without a client assertion that sends `client_secret`, in its form or as HTTP Basic, is
`invalid_client` with a description saying the client has none. No secret is issued,
checked, or ignored: a request is never served as if a secret had been right. It is
refused before the code or the refresh token is looked at, so it spends nothing.

## 0.37.4 (2026-11-18)

Clients that are no personal agents. In both SDKs; additive API only, off by default, and a
company that turns nothing on behaves exactly as before.

- **`public_clients` (`publicClients`) on `CompanyConfig`** (spec 7: MCP clients sign in with
MCP's own OAuth flow). A public client, such as an MCP client, authenticates with nothing but
PKCE (S256) at Direct Sign-In's authorization endpoint. It is either verified by its domain,
a client ID metadata document that says `token_endpoint_auth_method` is `none` and names no
key, read by the client resolver's new optional `resolve_public` (`resolvePublic`); or, with
**`client_registration` (`clientRegistration`)**, registered at `POST /oauth/register`
(RFC 7591), unverified. A document that names a key is a personal agent's and no document is
both, so a personal agent can't skip its assertion. Guide: guides/company, *Other clients
than personal agents*.
- **One service, and nothing of the protocol.** A public client's token is a Bearer token for
one of `resource_servers` or the company's own MCP server, named as `resource` in every
request; never the default token. It is refused at every endpoint of the protocol, with or
without a Session header; at the MCP server it calls tools with no Session, and a tool that
needs approval returns no operation. `access_token_for` (`accessTokenFor`) returns such a
token's record with `public` true, and asks the client policy as before. Scopes are
`public_client_scopes` (`publicClientScopes`), never `poppy:browser-sign-in`.
- **Refresh tokens** of a public client are rotated at every use and one used twice ends the
sign-in whole, whatever `refresh_reuse_revokes` says; a sign-in lasts
`public_client_refresh_lifetime` (`publicClientRefreshLifetimeSeconds`, 30 days) from the
consent, and no access token of it outlives it.
- **Redirect URIs** of a public client are loopback or HTTPS, written without user
information, fragment, backslash or space, compared as text, exactly but for a loopback
port (`public_redirect_uri`, `public_redirect_uri_matches`). An unverified client's errors
are pages, never redirects.
- **For a consent page**: `authorization_request` (`authorizationRequest`) adds `client_class`
(`personal_agent` or `public_client`), `verified`, `redirect_host`, and `resource` for a
public client. The company's own page says when a client is unverified and where the
browser goes back to.
- **Registration is bounded**: the host's rate limit is asked with `registration:{address}`,
then `client_registrations_per_hour` (10) for each address; a client that never signs in is
forgotten after an hour. A token or revocation request without an assertion asks the host's
rate limit with `public:{address}` before its client is looked at. `CompanyRequest` has an
optional `client_address` (`clientAddress`), which the ASGI and Node adapters fill with the
peer's.
- **The client policy** may answer for public clients apart, with an optional
`allows_public(client_id)` (`allowsPublic`); without it, `allows` answers for both classes.
- **For the company's owner**: `public_client_sign_ins` (`publicClientSignIns`) and
`revoke_public_client_sign_in` (`revokePublicClientSignIn`).
- The issuer's metadata gains `none` in `token_endpoint_auth_methods_supported` and
`authorization_response_iss_parameter_supported` only with `public_clients`, and
`registration_endpoint` only with `client_registration`. New record kinds `public_client` and
`registration_count`; a personal agent's records are written as before.

## 0.37.3 (2026-11-18)

A company's services at URLs of their own. In both SDKs; additive API only, and a company that
Expand Down
136 changes: 136 additions & 0 deletions docs/docs/guides/company.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -692,6 +692,142 @@ enforces the scopes on every call.

A company that names no resource server behaves as before.

### Other clients than personal agents

An MCP client that is no personal agent, such as a desktop assistant or an IDE, has no
key and no Session: it signs in with MCP's own OAuth flow, the authorization code grant
with PKCE and nothing else. The protocol leaves such clients outside (§7), and the
reference company refuses them unless it is told otherwise:

```python
config = CompanyConfig(
name="Example",
domain="example.com",
scopes=("orders:read", "orders:write"),
agent_description="Your orders",
scope_descriptions={"orders:read": "See your orders", "orders:write": "Change your orders"},
write_scopes=("orders:write",),
resource_servers=("https://mcp.example.com/mcp",),
public_clients=True,
client_registration=True,
public_client_scopes=("orders:read",),
)
print(config.registration_endpoint)
```

`public_clients` (`publicClients`) lets public clients sign in at Direct Sign-In's
authorization endpoint, so it needs `direct`. Everything below is off without it, and a
company that leaves it off behaves exactly as before.

**Two ways to be a public client.** Which one a client is, is never the request's to say.

- **Verified by its domain.** Its `client_id` is the URL of a client ID metadata
document that says `token_endpoint_auth_method` is `none` and names no `jwks_uri`,
`jwks` or `client_secret`. A document that names a key is a personal agent's, and no
document is both: a personal agent can't present itself as a public client to skip its
assertion. The document is read by the `pap.company.clientResolver` contribution's
`resolve_public` (`resolvePublic`), as a personal agent's is: HTTPS, no redirect,
bounded, and never at a private address. A resolver without the method verifies none.
The redirect URIs used from it are the loopback ones and the HTTPS ones on the
`client_id`'s own host.
- **Registered itself**, with `client_registration` (`clientRegistration`): `POST
/oauth/register` (RFC 7591) gives it a `client_id` that is no URL, and no secret.
Every client registered is a public client, whatever it asked for:
`token_endpoint_auth_method` left out, `none`, `client_secret_post` or
`client_secret_basic` is registered the same way, and the response says
`"token_endpoint_auth_method": "none"` with no `client_secret` (RFC 7591 §3.2.1: the
server may replace what was requested, and the client uses what is returned). A
registration that names a `client_secret`, `jwks` or `jwks_uri` of its own, or any
other method (`private_key_jwt` among them), is `invalid_client_metadata`, with an
`error_description` saying what to send: a personal agent can't register as a public
client. A token or revocation request that carries a `client_secret`, in its form or
as HTTP Basic, is `invalid_client`: no secret is ever issued, checked or ignored.
That includes a library that sends a public client's `client_id` as HTTP Basic with
an empty password: the `client_id` goes in the form, and no `Authorization` header.
Nothing verifies what a registered client says of itself, its name least of all.

**Redirect URIs** of a public client are `http` to the loopback (`127.0.0.1`, `[::1]`,
`localhost`) or HTTPS to a host written in small letters, with no user information,
fragment, backslash or space, and are compared as text. A request's `redirect_uri`
matches a registered one exactly; only a loopback one may differ by its port
(RFC 8252 §7.3). Any other scheme is refused.

**The consent page** is shown for every request. `authorization_request` says who asks:
`client_class` is `public_client` (`personal_agent` otherwise), `verified` is false for
a client that registered itself, `redirect_host` is where the browser goes back to and
`resource` the service the sign-in is for. A hosted consent page shows the return host
prominently, marks an unverified client as such, keeps `caution` (§10.8), and is never
framed (`frame-ancestors 'none'`), as the company's own page does. An error of a request
from an unverified client is a page, never a redirect: anyone can register any HTTPS
redirect, and answering it without anyone's consent would make the endpoint an open
redirector. Every answer carries `iss` (RFC 9207) and the request's `state`.

**What a public client gets**, and what it never gets:

- a Bearer token for one service, which every request names as `resource`: the
authorization request, the code exchange and each refresh, always the same one. The
services are `resource_servers` and the company's own MCP server. Never the default
token, never the conversation endpoint;
- the scopes of `public_client_scopes` (`publicClientScopes`), or every scope of the
company's own when it names none; never `poppy:browser-sign-in`;
- the code and refresh grants only. The device and mediated grants answer
`unauthorized_client`, and it can't push an authorization request;
- no Session. Its token is refused at every endpoint of the protocol (conversations,
operations, tasks, feedback, the browser session, the APIs), with or without a
Session header, and at the MCP server once a Session header comes with it;
- no operation. At the company's own MCP server a tool that needs the person's approval
answers an error and returns no operation: only a personal agent approves one.

**Refresh tokens** of a public client are rotated at every use, and one used twice ends
the whole sign-in, whatever `refresh_reuse_revokes` says for personal agents. A sign-in
lasts `public_client_refresh_lifetime` (`publicClientRefreshLifetimeSeconds`, 30 days)
from the moment the person allowed it, however often it refreshes; then they sign in
again. No token outlives it: an access token issued near the end expires with the
sign-in (`expires_in` says so), and a public client's token whose sign-in is over,
ended or no longer on record is refused wherever it is read. A public client ends
its own sign-in at the revocation endpoint with its `client_id` and the refresh token.

**The client policy** is asked as for a personal agent: `allows` before anything is
fetched or read for a `client_id`, `allows_sign_in` at the authorization endpoint and
again when the code is exchanged, `allows_resource` for the service, at each token
request and each time `access_token_for` reads a token. A service at a URL of its own
reads `public` on the record `access_token_for` returns: true for a public client's
token, to which it gives no Session and from which it takes no approval.

A policy may answer for public clients apart, with `allows_public(client_id)`
(`allowsPublic`): a company that lists the personal agents it serves takes public
clients all the same, or none. Without the method, `allows` answers for both classes.
`sign_in_disabled` is about personal agents only: it neither stops nor allows public
clients, which `public_clients` alone decides.

A client verified by its domain is read again at each token request, so a document that
went away or became a personal agent's gets nothing more. The resolver's cache decides
how often that is a fetch: the default one keeps a document as its `Cache-Control` says,
and remembers for 30 seconds that one could not be read.

**Registration is bounded.** The host's `pap.company.rateLimit` is asked first, with
`registration:{address}` where it is asked a `client_id`; then the company counts
`client_registrations_per_hour` (`clientRegistrationsPerHour`, 10) for each address.
The address is the request's `client_address` (`clientAddress`): the peer's, which the
ASGI and Node adapters fill in. Behind a proxy that is the proxy's, one count for
everyone, unless the host passes the address its proxy vouches for. A registration is at
most 16 KiB, names at most 10 redirect URIs and a name of at most 100 characters with
no control or direction mark. A client that never signs in is forgotten an hour after
it registered; one that signs in is kept `client_registration_lifetime` (90 days) from
its last sign-in. A token or revocation request without a client assertion asks the
host's rate limit too, with `public:{address}`, before the client it names is looked at.

**For the company's owner.** `await service.public_client_sign_ins()`
(`publicClientSignIns`) lists the sign-ins that have not ended: the client, its name,
whether it is verified, the return host, the service, the account, the scopes, when it
signed in and last got tokens, and when it ends.
`revoke_public_client_sign_in(sign_in_id)` (`revokePublicClientSignIn`) ends one: its
refresh and access tokens stop working at once.

The issuer's metadata says `none` in `token_endpoint_auth_methods_supported` and
`authorization_response_iss_parameter_supported` only with `public_clients`, and
`registration_endpoint` only with `client_registration`.

### Before production

The defaults keep state in one process. A deployment contributes a durable
Expand Down
2 changes: 1 addition & 1 deletion docs/docs/protocol/conformance-report.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ title: Compatibility and conformance report

# Compatibility and conformance report

SDK version **0.37.3**, PAP profile **0.4** (as published 2026-11-10), Operations extension **v3**; the pairings run at protocol version **1.0**, the default (1.0 as published 2026-11-14); the suite also runs at 0.4 in every pairing. Each pairing runs every positive, negative and recovery fixture case over real TCP and TLS, the personal agent in one language and the reference company (Manzanita) in the other. A case is skipped, never passed, when a side lacks what it needs; the reason is listed below.
SDK version **0.37.5**, PAP profile **0.4** (as published 2026-11-10), Operations extension **v3**; the pairings run at protocol version **1.0**, the default (1.0 as published 2026-11-14); the suite also runs at 0.4 in every pairing. Each pairing runs every positive, negative and recovery fixture case over real TCP and TLS, the personal agent in one language and the reference company (Manzanita) in the other. A case is skipped, never passed, when a side lacks what it needs; the reason is listed below.

## Pairings

Expand Down
4 changes: 3 additions & 1 deletion docs/docs/releases/compatibility.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ title: Compatibility

# Compatibility

This page is versioned with the SDK: it describes **SDK 0.37.3**.
This page is versioned with the SDK: it describes **SDK 0.37.5**.

## The PAP version implemented

Expand Down Expand Up @@ -35,6 +35,8 @@ profile, never picked up from an unattended fetch.

| SDK (PyPI and npm) | PAP profile | Specification revision | Operations | Breaking changes |
| --- | --- | --- | --- | --- |
| `0.37.5` | `0.4` | 2026-11-10 | v3 | none: a client that registers itself (`client_registration`) is registered as a public client whatever `token_endpoint_auth_method` it asked for among `none`, `client_secret_post`, `client_secret_basic` or none at all, and told `none`; a request that sends a client secret is refused |
| `0.37.4` | `0.4` | 2026-11-10 | v3 | none: a company may let clients that are no personal agents sign in (`public_clients`: MCP clients, with PKCE alone, verified by their client ID metadata document or registered at `/oauth/register` with `client_registration`), for tokens that work at one service and at no endpoint of the protocol; off by default |
| `0.37.3` | `0.4` | 2026-11-10 | v3 | none: a company names its services at URLs of their own (`resource_servers`, an MCP server on another host), which its issuer lists in `protected_resources` and issues Bearer tokens for, and which verify them with `access_token_for` |
| `0.37.2` | `0.4` | 2026-11-10 | v3 | none: opening a sign-in link reads its record without consuming it (the state store's optional `get`), a link begun by 0.37.0 still opens after an upgrade, and the Direct Sign-In start names its `state` for hosts whose redirect lands elsewhere |
| `0.37.1` | `0.4` | 2026-11-10 | v3 | none: a bound refresh token keeps its sign-in at a Bearer-only MCP server, `open_link` leaves the callback state to `complete`, an empty SSE event name is a message, and `effectiveContext` keeps a `__proto__` field as a field |
Expand Down
1 change: 1 addition & 0 deletions docs/docs/sdk/python-api.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -199,6 +199,7 @@ Unknown or internal symbols are deliberately excluded.
- [`PROTOCOL_REVISION`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/profile.py) — Constant. Public `PROTOCOL_REVISION` constant.
- [`ProtocolCache`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Class. Bound cached public protocol data by an absolute expiry.
- [`ProtocolValidationError`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/errors.py) — Class. A protocol document is malformed or internally inconsistent.
- [`PublicClientMetadata`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. The client ID metadata document of a public client: an MCP client, never a
- [`RANDOM_SOURCES`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Constant. Public `RANDOM_SOURCES` constant.
- [`RandomSource`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Class. Supply cryptographically secure random bytes.
- [`RATE_LIMIT_BUDGETS`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Constant. Public `RATE_LIMIT_BUDGETS` constant.
Expand Down
Loading
Loading