From d6c1d530b6c7bea4939cbf1471494ea679bdb75f Mon Sep 17 00:00:00 2001 From: Eric Charles Date: Tue, 17 Nov 2026 11:48:37 +0100 Subject: [PATCH 1/2] 0.37.0: Poppy 1.0 as published Version 1.0 as published (upstream 8c02b42, frozen 2026-11-14; reviewed through 6764732), the default, in both SDKs and both reference companies; 0.4 as published unchanged. Required conversation protocol descriptions (CompanyConfig.agent_description), Pushed Authorization Requests (agent pushes when offered; company offers or requires), prompt=consent and consent pages that list every scope, refresh tokens bound to their DPoP key (bind_refresh_tokens), UCP sign-ins naming every scope, ports in organization.domain (allow_ports), PS384 with RSA 2048-4096, invalid_target for a left-out service, null clears context, unknown roles, author types, SSE events and error codes read safely, working only while replying, unknown authorization errors, and the Mediated Sign-In retirement date. Conformance: new cases and a pushed-requests world in all four pairings, at 1.0 and 0.4. Ledger, coverage, migration, compatibility, conformance report, upstream snapshot and schemas updated. Agent Runtimes adopts on feat/scenes. --- .github/workflows/examples.yaml | 6 +- CHANGELOG.md | 74 ++ README.md | 8 +- docs/docs/guides/acting-for-a-person.mdx | 4 + docs/docs/guides/company.mdx | 40 +- docs/docs/guides/conversations.mdx | 6 +- docs/docs/guides/direct-sign-in.mdx | 29 + docs/docs/guides/mediated-sign-in.mdx | 4 +- docs/docs/guides/personal-agent.mdx | 9 +- docs/docs/protocol/conformance-report.mdx | 24 +- docs/docs/protocol/coverage.mdx | 29 +- docs/docs/protocol/coverage/conversations.mdx | 4 +- docs/docs/protocol/coverage/discovery.mdx | 5 +- .../protocol/coverage/identity-sessions.mdx | 6 +- .../coverage/security-considerations.mdx | 3 +- docs/docs/protocol/coverage/sign-in.mdx | 11 +- docs/docs/protocol/coverage/ucp.mdx | 2 +- docs/docs/protocol/open-topics.mdx | 33 +- docs/docs/protocol/status.mdx | 8 +- docs/docs/releases/compatibility.mdx | 14 +- docs/docs/releases/migration.mdx | 25 + docs/docs/releases/support.mdx | 4 +- docs/docs/sdk/python-api.mdx | 15 +- docs/docs/sdk/typescript-api.mdx | 28 +- docs/docs/sdk/typescript.mdx | 1 + examples/pydantic-ai/company-service/app.py | 1 + package.json | 2 +- personal_agent_protocol/__init__.py | 26 + .../__tests__/test_conformance.py | 23 +- .../__tests__/test_conversations.py | 6 +- .../__tests__/test_cross_language.py | 1 + .../__tests__/test_docs_examples.py | 11 +- .../__tests__/test_draft_04.py | 1 + .../__tests__/test_draft_10.py | 2 +- .../__tests__/test_fixtures.py | 13 + .../__tests__/test_hosted_pages.py | 4 + .../__tests__/test_issuerless.py | 13 +- .../__tests__/test_operator_signatures.py | 1 + .../__tests__/test_published_10.py | 894 ++++++++++++++++++ .../__tests__/test_reactor_points.py | 1 + .../__tests__/test_schemas.py | 5 +- .../__tests__/test_security_review.py | 3 + personal_agent_protocol/__tests__/test_ucp.py | 5 +- personal_agent_protocol/__version__.py | 2 +- personal_agent_protocol/accounts.py | 29 +- personal_agent_protocol/auth.py | 234 ++++- personal_agent_protocol/browser_control.py | 4 +- personal_agent_protocol/cli_commands.py | 3 + personal_agent_protocol/company/__init__.py | 2 +- personal_agent_protocol/company/points.py | 15 +- personal_agent_protocol/company/service.py | 294 +++++- personal_agent_protocol/company/store.py | 82 +- personal_agent_protocol/company/testing.py | 22 +- personal_agent_protocol/company/verify.py | 36 +- personal_agent_protocol/conformance.py | 95 +- personal_agent_protocol/conversations.py | 81 +- personal_agent_protocol/demo/ledgerly.py | 1 + personal_agent_protocol/demo/manzanita.py | 1 + personal_agent_protocol/demo/northwind.py | 1 + personal_agent_protocol/device.py | 5 +- personal_agent_protocol/discovery.py | 39 +- personal_agent_protocol/mediated.py | 6 +- personal_agent_protocol/models.py | 162 +++- personal_agent_protocol/pages.py | 18 +- personal_agent_protocol/profile.py | 18 +- personal_agent_protocol/reactor.py | 2 +- personal_agent_protocol/ucp.py | 27 +- protocol/UPSTREAM.md | 36 +- protocol/fixtures/conformance/dpop.json | 28 +- protocol/fixtures/conformance/protocol.json | 297 +++++- protocol/fixtures/discovery-valid.json | 3 +- protocol/requirements.yaml | 305 +++++- .../authorization-server-metadata.schema.json | 2 +- protocol/schemas/message.schema.json | 8 +- protocol/schemas/poppy.schema.json | 9 +- scripts/conformance_report.py | 4 +- scripts/generate_coverage.py | 7 +- src/__tests__/company.test.mjs | 6 +- src/__tests__/conformance-fixtures.test.mjs | 24 +- src/__tests__/conformance-pairing.test.mjs | 24 +- src/__tests__/dpop.test.mjs | 1 + src/__tests__/draft-04.test.mjs | 1 + src/__tests__/draft-10.test.mjs | 2 +- src/__tests__/idempotency.test.mjs | 2 +- src/__tests__/issuerless.test.mjs | 5 +- src/__tests__/operator-signatures.test.mjs | 2 +- src/__tests__/published-10.test.mjs | 729 ++++++++++++++ src/__tests__/reactor-points.test.mjs | 2 +- src/__tests__/schemas.test.mjs | 6 +- src/__tests__/security-review.test.mjs | 8 +- src/__tests__/support/conformance.mjs | 81 +- src/__tests__/ucp.test.mjs | 4 +- src/accounts.ts | 21 +- src/auth.ts | 305 +++++- src/browser-control.ts | 4 +- src/company/index.ts | 3 +- src/company/points.ts | 22 +- src/company/service.ts | 309 +++++- src/company/store.ts | 35 + src/company/testing.ts | 11 + src/company/verify.ts | 31 +- src/conversations.ts | 73 +- src/demo/manzanita.ts | 1 + src/device.ts | 4 +- src/discovery.ts | 43 +- src/index.ts | 14 + src/mediated.ts | 8 +- src/models.ts | 213 ++++- src/pages.ts | 19 +- src/profile.ts | 16 +- src/reactor.ts | 2 +- src/ucp.ts | 24 +- 112 files changed, 4958 insertions(+), 379 deletions(-) create mode 100644 personal_agent_protocol/__tests__/test_published_10.py create mode 100644 src/__tests__/published-10.test.mjs diff --git a/.github/workflows/examples.yaml b/.github/workflows/examples.yaml index 7b266eda..e82ce807 100644 --- a/.github/workflows/examples.yaml +++ b/.github/workflows/examples.yaml @@ -59,9 +59,9 @@ jobs: # to have no upper bound. The ref is the Agent Runtimes branch that adopts the new # SDK. # - # Empty: Agent Runtimes 1.6.74 accepts 0.36 (personal-agent-protocol >=0.36.0,<0.37), - # so the job tests the released package. - AGENT_RUNTIMES_REF: '' + # 0.37 breaks the API: Agent Runtimes adopts it on feat/scenes (pin >=0.37.0,<0.38), so + # the job installs Agent Runtimes from that branch until a release accepts 0.37. + AGENT_RUNTIMES_REF: feat/scenes steps: - uses: actions/checkout@v6 - uses: astral-sh/setup-uv@v7 diff --git a/CHANGELOG.md b/CHANGELOG.md index 7e762cdd..8c926567 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,80 @@ # Changelog +## 0.37.0 (2026-11-17) + +Version 1.0 **as published** (upstream `8c02b42`, frozen 2026-11-14; reviewed through +`6764732`, whose later commits restructure the site and change no normative text), the +default version, in both SDKs and both reference companies. **Breaking**: see the +[0.36 → 0.37 migration](https://personal-agent-protocol.datalayer.tech/releases/migration/#036--037). +0.4 as published is unchanged: where 1.0 changes a rule, the SDK applies it at 1.0 only. + +- **Conversation protocol descriptions** (spec 3.1, 8.1, UCP 5). `AgentProtocol.description`; + `DiscoveryDocument` (`parseDiscoveryDocument`) refuses a 1.0 document whose + `agent.protocols` entry has none. `CompanyConfig.agent_description` (`agentDescription`) is + required and goes in the 1.0 document only. +- **Pushed Authorization Requests** (spec 3.2, 4.2, 4.8; RFC 9126). + `OAuthServerMetadata.require_pushed_authorization_requests`; `DirectSignInClient.begin` + pushes when given `pushed_authorization_request_endpoint` (and must when + `require_pushed_authorization_requests`), with a client assertion and a DPoP proof when + tokens are bound, and opens the authorization endpoint with `client_id` and `request_uri` + only; `link_page` and `open_link(link)` push when a link opened later is opened + (TypeScript `pushedAuthorizationRequestEndpoint`, `requirePushedAuthorizationRequests`, + `linkPage`, `openLink`). The `pap` CLI and the conformance runner push whenever the issuer + lists the endpoint. A company offers or requires it with + `CompanyConfig.pushed_authorization_requests` (`"off"`, the default, `"offered"`, + `"required"`): `POST /oauth/par`, a one-use `request_uri`, the code bound to the pushing + DPoP key. +- **Minor versions** (spec 3.4). Nothing 1.0 adds goes into a 0.4 exchange: a 0.4 document + has no description and no port, and a 0.4 Session sends no `null` context + (`context_clear_unsupported`). +- **PS384 required** (spec 4.1, 5.2, 10.7). Both reference companies accept `PS384` and + `ES256` client assertions and delegations, and now refuse RSA keys outside 2048 to 4096 + bits (`RSA_KEY_BITS`). +- **Consent for scopes granted before** (spec 4.2, 4.3, 10.8, 11). Direct Sign-In requests + carry `prompt=consent` (`PROMPT_CONSENT`) unless `same_device_redirect` + (`sameDeviceRedirect`). The reference companies show their consent page for every Direct + and Device Sign-In, list every scope, and with `account_id` mark each scope + `granted_before` in `authorization_request` and `device_request`, which also give `prompt`. +- **Same DPoP key at refresh** (spec 4.4, 4.5, 4.8, 10.7). The agent keeps one DPoP key per + User ID across refreshes, as before. `CompanyConfig.bind_refresh_tokens` + (`bindRefreshTokens`) binds refresh tokens to the issuing request's key, rotated ones too: + another key is `invalid_grant`. +- **UCP scope requests** (UCP 4, 11). `ucp_scopes(profile, held, needed=, protocol_version=)` + (`ucpScopes`) requests every scope still needed at 1.0, the missing ones at 0.4; the + reference companies grant only the scopes a request names. +- **Ports in `organization.domain`** (spec 3.1, 3.2). A 1.0 domain includes its port when that + isn't 443, also in `protected_resources`; `DiscoveryClient(allow_ports=True)` + (`allowPorts`) uses such a company, refused otherwise (`port_not_allowed`). `split_domain`, + `domain_host`, `url_domain` (`splitDomain`, `domainHost`, `urlDomain`); a company serves a + domain with a port at 1.0 only. +- **Client assertion lifetime** (spec 4.1). Already the rule: the SDK's assertions last 60 + seconds, at most 300, and the reference companies accept up to five minutes. +- **One sign-in for every resource** (spec 4.5, 4.7, 4.8, 7). Already so on both sides (no + `resource` at sign-in, one per token request). New: a client policy's + `allows_resource(client_id, resource)` (`allowsResource`) leaves a service out + (`invalid_target`), and `ServiceTokens` then uses it signed out. +- **Clearing context** (spec 8.4). A `context` field set to `null` clears it: + `effective_context` (`effectiveContext`), `clears_context`; the company agent's + `Turn.context` is the shared context. +- **Room to extend conversations** (spec 8.4, 8.6, 8.13). Unknown `role` reads `company`, + unknown `author.type` reads `agent` (`known_role`, `known_author_type`); the company drops + `author.id`, `name` and `image` from the agent's messages; unknown SSE event names are + skipped; an unknown conversation error code is `conversation_request_failed`, the code kept + in `details["error"]` (`KNOWN_CONVERSATION_ERRORS`, `known_conversation_error`). +- **What `working` means** (spec 8.7). Already so: the reference companies set `working` + only while replying. The docs say so. +- **Unknown sign-in errors** (spec 8.11). `ConversationEvent.error` is any string, and + `sign_in_scopes` (`signInScopes`) gives the scopes to sign in again for. +- **Mediated Sign-In retirement date**: `MEDIATED_RETIREMENT_DATE` (`2027-03-17`). +- **Scope descriptions** (spec 4.7, guides): the docs say what a good description says. +- **Open topic**: what happens to an operation in flight at sign-out is open upstream + (personal-agent-protocol#84); the open-topics page says what the reference companies do. +- **Conformance and records.** New fixture cases and a `pushed-requests` world (PAR required, + refresh tokens bound), run in all four pairings; the suite runs at 1.0 and at 0.4. The + vendored JSON Schemas are upstream's at `8c02b42`. The ledger adds the 1.0 statements + (`PAP10-*`, marked `version: '1.0'`) and marks UCP-4-06 as 0.4's. + ## 0.36.1 (2026-11-16) - **A persisted Session keeps its version** (TypeScript). `PapSession.fromJson()` restores a diff --git a/README.md b/README.md index 47195d24..3f9d3bf8 100644 --- a/README.md +++ b/README.md @@ -10,10 +10,10 @@ Python and TypeScript SDKs for the [Personal Agent Protocol](https://personalagentprotocol.org): both implement +[version 1.0](https://personalagentprotocol.org/docs/1.0/spec) as published +(2026-11-14), the default, and [version 0.4](https://personalagentprotocol.org/docs/0.4/spec) (2026-11-10), as -published, and its Operations extension v3, and the -[1.0 draft](https://personalagentprotocol.org/docs/spec), the default since 0.36 -(0.4 is used when named in `protocol_versions`). See +published, used when named in `protocol_versions`, with the Operations extension v3. See [Compatibility](https://personal-agent-protocol.datalayer.tech/releases/compatibility/), [Migration](https://personal-agent-protocol.datalayer.tech/releases/migration/), the [conformance report](https://personal-agent-protocol.datalayer.tech/protocol/conformance-report/), @@ -201,7 +201,7 @@ Duplicate JSON members are rejected at Python and TypeScript trust boundaries. ## What is not implemented yet -Every flow of version 0.4 and Operations version 3 is implemented in both SDKs and +Every flow of versions 1.0 and 0.4 and Operations version 3 is implemented in both SDKs and both reference companies: discovery, Sessions, Direct, Device and Mediated Sign-In, refresh tokens, DPoP, OpenAPI and MCP, conversations with SSE, handoff and close, browser sessions, feedback, and Operations. What remains: diff --git a/docs/docs/guides/acting-for-a-person.mdx b/docs/docs/guides/acting-for-a-person.mdx index 0d52c7b5..681faa17 100644 --- a/docs/docs/guides/acting-for-a-person.mdx +++ b/docs/docs/guides/acting-for-a-person.mdx @@ -75,6 +75,8 @@ config = CompanyConfig( name="Example Store", domain="store.example", scopes=("orders:read", "orders:cancel"), + # What the Company Agent can help with: agent.protocols[].description (spec 8.1). + agent_description="Your orders: tracking, changes, and cancellations", # What a Session must hold to approve an operation. write_scopes=("orders:cancel",), scope_descriptions={ @@ -149,6 +151,8 @@ const config = new CompanyConfig({ name: 'Example Store', domain: 'store.example', scopes: ['orders:read', 'orders:cancel'], + // What the Company Agent can help with: agent.protocols[].description (spec 8.1). + agentDescription: 'Your orders: tracking, changes, and cancellations', // What a Session must hold to approve an operation. writeScopes: ['orders:cancel'], scopeDescriptions: { diff --git a/docs/docs/guides/company.mdx b/docs/docs/guides/company.mdx index 860cd4b9..c0100fbc 100644 --- a/docs/docs/guides/company.mdx +++ b/docs/docs/guides/company.mdx @@ -115,7 +115,7 @@ document is served at `/poppy/{version}.json`, with that `protocol_version` and `supported_versions`. A request whose `Poppy-Version` is missing or names no served version is refused with `version_unsupported` (HTTP 400, JSON body) where the Session header is verified, and is never handled under another version. The -reference company speaks the 1.0 draft (`DEFAULT_PROTOCOL_VERSION`) by default; +reference company speaks 1.0 (`DEFAULT_PROTOCOL_VERSION`) by default; another entry lets a personal agent's choice be exercised and is answered the same way. 0.4 as published (`PROTOCOL_PROFILE`) is opt-in on this side too: a company that adds @@ -184,6 +184,8 @@ config = CompanyConfig( name="Manzanita Outfitters", domain="manzanita.example", scopes=("orders:read", "orders:write"), + # What the Company Agent can help with, in plain language (spec 3.1, 8.1). + agent_description="Anything about your orders, returns, and our outdoor gear", write_scopes=("orders:write",), mediated_fields=(("email", "Email", False), ("password", "Password", True)), # Every scope described, in words a user and a model understand (`auth.scopes`). @@ -538,6 +540,40 @@ TypeScript) when: A hosted consent page (`consent_page`) gets no binding: it protects its own form, and `consent_decision` refuses every POST for its requests. +Every user of a personal agent shares its `client_id`, so the page lists every +scope the sign-in would grant and is shown for every request, `prompt=consent` +or not, and for every Device Sign-In, even when the account granted every scope +before (§4.2, §4.3, §10.8). A hosted page reads the request with +`authorization_request(request_id, account_id=...)` or +`device_request(user_code, account_id=...)` (`{ accountId }`): given the account +signed in on the page, each scope says `granted_before`, which the page may mark +as already granted, never hide. The request's `prompt` is there too. + +### Pushed Authorization Requests and bound refresh tokens + +`pushed_authorization_requests="offered"` (`pushedAuthorizationRequests`) lists +`pushed_authorization_request_endpoint` (`/oauth/par`) in the issuer's metadata, +and `"required"` also sets `require_pushed_authorization_requests`: the +authorization endpoint then takes only a `request_uri` the agent pushed with its +client assertion (RFC 9126, §4.2). A push with a DPoP proof binds the code to its +key. `bind_refresh_tokens=True` (`bindRefreshTokens`, with `dpop_binding`) binds +each refresh token, and those rotated from it, to the DPoP key of the request that +issued it: a copied refresh token is useless with another key (§4.4). Both are off +by default. A client policy may leave a service out for an agent with +`allows_resource(client_id, resource)` (`allowsResource`): its token requests are +`invalid_target` (§4.5). + +### Describing the agent and the scopes + +`agent_description` (`agentDescription`) is required: what the Company Agent can +help with, in plain language, published as `agent.protocols[].description` at +1.0 (§3.1, §8.1). It may say the agent can help with anything. Each scope's +description (`scope_descriptions`) is most useful when it says what the scope +unlocks, which tasks need it, and whether a task can be done without it, such as +"See your orders, returns, and bookings. Needed to track an order or find one to +change", or "Personalized search results. Not needed to search the catalog" +(§4.7; upstream guides, *Describing scopes*). + `test_guide_security.py` and `guide-security.test.mjs` test each case. ### Hosted sign-in pages @@ -550,6 +586,7 @@ config = CompanyConfig( name="Orders helper", domain="orders.example", scopes=("orders:read",), + agent_description="Your orders", scope_descriptions={"orders:read": "See your orders"}, operations=False, device_page="https://pap.orders.example/device?slug=orders-helper", @@ -586,6 +623,7 @@ config = CompanyConfig( name="Orders helper", domain="orders-helper.apps.datalayer.ai", scopes=("orders:read",), + agent_description="Your orders", scope_descriptions={"orders:read": "See your orders"}, operations=False, aliases=("orders.example.com",), diff --git a/docs/docs/guides/conversations.mdx b/docs/docs/guides/conversations.mdx index 5dc75695..7cfde4c3 100644 --- a/docs/docs/guides/conversations.mdx +++ b/docs/docs/guides/conversations.mdx @@ -113,8 +113,10 @@ and the company sends nothing there that it cannot share with the agent. ## Where a conversation stands (§8.7) Every read and every receipt reports the conversation's state in four fields, -each independent of the others: `working` (the company has work in progress: a -request it accepted but hasn't acted on, a reply being written), `handoff` +each independent of the others: `working` (the company is still replying: a +request it accepted but hasn't acted on, or a reply being written; since 1.0 not +work it finishes later, such as a refund that takes days, which it says in a +message and follows with another when done), `handoff` (`pending` while it looks for a person), `responder` (`agent` or `human`), and `closed`. A successful `POST` only means the company accepted the request, so `working` is `true` from that moment; `ConversationClient.read_until_done` diff --git a/docs/docs/guides/direct-sign-in.mdx b/docs/docs/guides/direct-sign-in.mdx index f5aa38da..b5893221 100644 --- a/docs/docs/guides/direct-sign-in.mdx +++ b/docs/docs/guides/direct-sign-in.mdx @@ -99,6 +99,35 @@ The company's page does its part: it names the personal agent that wants to connect and tells the person to continue only if they just asked it to (see the [company guide](/guides/company/)). +## Consent every time (§4.2, §10.8) + +Every user of a personal agent shares its `client_id`, so a company that skipped +its consent page because the account had granted every scope before would let a +forwarded link get tokens with no page at all. Since 1.0 a Direct Sign-In request +carries `prompt=consent` (`PROMPT_CONSENT`): the company shows its page whatever +the account granted. `begin` adds it; pass `same_device_redirect=True` +(`sameDeviceRedirect`) only when you receive the redirect on the device that +opened the URL, where a forwarded link fails anyway. + +## Pushed Authorization Requests (§4.2, RFC 9126) + +When the issuer's metadata lists `pushed_authorization_request_endpoint`, pass it +to `begin` with `require_pushed_authorization_requests`, both read from the +`OAuthServerMetadata` (TypeScript `pushedAuthorizationRequestEndpoint`, +`requirePushedAuthorizationRequests`). The request is then pushed with a client assertion, and a DPoP proof when tokens +are bound, so the code is bound to the key, and the browser opens the +authorization endpoint with only `client_id` and `request_uri`. A company that +requires it takes nothing else; the protocol asks agents to push whenever it is +offered. A `request_uri` expires quickly, so a link the user opens later, such as +on their phone, goes to a page of your own: pass +`link_page="https://agent.example/sign-in/{link}"` (`linkPage`) and the browser +handoff gets that page; when it is opened, it calls `open_link(link)` +(`openLink`), which pushes the request then, and redirects to the URL it returns. + +A sign-in names no `resource`: it covers every service the company offers, those +it adds later too, and each token request names one (§4.5, see +[Refresh tokens](/guides/account-tokens/)). + ## TypeScript ```typescript diff --git a/docs/docs/guides/mediated-sign-in.mdx b/docs/docs/guides/mediated-sign-in.mdx index 0785f2a7..7f7ffe3f 100644 --- a/docs/docs/guides/mediated-sign-in.mdx +++ b/docs/docs/guides/mediated-sign-in.mdx @@ -41,8 +41,8 @@ company offers, or `None`. Like OAuth's password grant, which OAuth 2.1 removes, Mediated Sign-In is a step on the way, not where the protocol is headed. A company should offer it only until it can add Direct or Device Sign-In, and stop once those cover the -scopes it grants. The protocol plans to remove it, on a date set when version -1.0 is published. +scopes it grants. The protocol plans to retire it on March 17, 2027 +(`MEDIATED_RETIREMENT_DATE`), as version 1.0 says. ::: diff --git a/docs/docs/guides/personal-agent.mdx b/docs/docs/guides/personal-agent.mdx index 6cb87cf9..0fe55936 100644 --- a/docs/docs/guides/personal-agent.mdx +++ b/docs/docs/guides/personal-agent.mdx @@ -67,12 +67,15 @@ own, and the company's domain and issuer; anything else is refused document and `company.protocol_version` (`companyProtocolVersion(company)`) names it. -The versions the agent implements are `DEFAULT_PROTOCOL_VERSION`, the 1.0 draft -(`DRAFT_PROTOCOL_VERSION`, `1.0`), unless you ask for others. 0.4 as published +The versions the agent implements are `DEFAULT_PROTOCOL_VERSION`, 1.0 as published +(`DRAFT_PROTOCOL_VERSION`, `1.0`, named while it was the draft), unless you ask for others. 0.4 as published (`PROTOCOL_PROFILE`) is opt-in: `DiscoveryClient(protocol_versions=("1.0", "0.4"))` (`discoverCompany(domain, { protocolVersions: ["1.0", "0.4"] })`) uses a company at 1.0 when it serves it and at 0.4 otherwise; `("0.4",)` alone uses only companies that -serve 0.4. Today the draft differs from 0.4 on the wire in the version string only. +serve 0.4. Where 1.0 changes a rule, the SDK follows it at 1.0 and 0.4's at 0.4: a 1.0 +document must describe each conversation protocol, a domain may name a port only at 1.0 +(and only with `allow_ports=True`, `allowPorts`, which uses a company on another port +for testing), and a 0.4 Session never sends a `null` context field. `SessionClient.start(..., company=company)` names the version the company was discovered at (`company.session_version`, `companySessionVersion(company)`) in the Session, or pass `protocol_version` (`protocolVersion`) yourself. diff --git a/docs/docs/protocol/conformance-report.mdx b/docs/docs/protocol/conformance-report.mdx index a5510c84..dec235f0 100644 --- a/docs/docs/protocol/conformance-report.mdx +++ b/docs/docs/protocol/conformance-report.mdx @@ -6,16 +6,16 @@ title: Compatibility and conformance report # Compatibility and conformance report -SDK version **0.36.1**, PAP profile **0.4** (as published 2026-11-10), Operations extension **v3**; the pairings run at protocol version **1.0**, the default (the 1.0 draft as of 2026-11-11). 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.0**, 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 | Personal agent | Company | Passed | Failed | Skipped | | --- | --- | ---: | ---: | ---: | -| Python | Python | 175 | 0 | 0 | -| Python | TypeScript | 175 | 0 | 0 | -| TypeScript | Python | 175 | 0 | 0 | -| TypeScript | TypeScript | 175 | 0 | 0 | +| Python | Python | 178 | 0 | 0 | +| Python | TypeScript | 178 | 0 | 0 | +| TypeScript | Python | 178 | 0 | 0 | +| TypeScript | TypeScript | 178 | 0 | 0 | ## Protocol @@ -28,6 +28,7 @@ SDK version **0.36.1**, PAP profile **0.4** (as published 2026-11-10), Operation | `protocol.tasks-per-session` | positive | PAP-9-01 | pass | pass | pass | pass | | `protocol.feedback-report` | positive | PAP-9.3-01, PAP-9.3-06 | pass | pass | pass | pass | | `protocol.ucp-profile` | positive | UCP-4-03, UCP-4-04 | pass | pass | pass | pass | +| `protocol.agent-protocols-described` | positive | PAP10-8.1-01, PAP10-3.4-01 | pass | pass | pass | pass | ## Security @@ -186,6 +187,8 @@ SDK version **0.36.1**, PAP profile **0.4** (as published 2026-11-10), Operation | `dpop.mcp-challenges-bearer-then-dpop` | positive | GUIDE-co-session-06, GUIDE-mcp-01 | pass | pass | pass | pass | | `dpop.mcp-bearer-without-a-proof` | positive | GUIDE-mcp-01 | pass | pass | pass | pass | | `dpop.mcp-server-decides-the-proof` | positive | GUIDE-mcp-01 | pass | pass | pass | pass | +| `dpop.refresh-bound-to-its-key` | recovery | PAP10-4.4-01 | pass | pass | pass | pass | +| `dpop.pushed-authorization-request` | positive | PAP10-4.2-02, PAP10-4.2-03 | pass | pass | pass | pass | ## Operator signatures @@ -218,7 +221,7 @@ SDK version **0.36.1**, PAP profile **0.4** (as published 2026-11-10), Operation ## Decided by each SDK alone -82 fixture cases need no company: parsing, extension negotiation, URL safety and bounded discovery. Python runs them in `test_fixtures.py` and TypeScript in `conformance-fixtures.test.mjs`; a case marked for one SDK only is listed with it. +91 fixture cases need no company: parsing, extension negotiation, URL safety and bounded discovery. Python runs them in `test_fixtures.py` and TypeScript in `conformance-fixtures.test.mjs`; a case marked for one SDK only is listed with it. | Case | Kind | Check | SDKs | | --- | --- | --- | --- | @@ -281,6 +284,15 @@ SDK version **0.36.1**, PAP profile **0.4** (as published 2026-11-10), Operation | `protocol.tasks-endpoint-https` | negative | discovery_document | python, typescript | | `protocol.tasks-endpoint-listed` | positive | discovery_document | python, typescript | | `protocol.extensions-header` | positive | extensions_header | python, typescript | +| `protocol.agent-protocol-description-required` | negative | discovery_document | python, typescript | +| `protocol.agent-protocol-description-not-in-04` | positive | discovery_document | python, typescript | +| `protocol.organization-domain-port` | positive | discovery | python, typescript | +| `protocol.organization-domain-port-not-allowed` | negative | discovery | python, typescript | +| `protocol.organization-domain-port-other-domain` | negative | discovery | python, typescript | +| `protocol.organization-domain-port-04` | negative | discovery_document | python, typescript | +| `protocol.unknown-role-and-author-type` | positive | message_tolerance | python, typescript | +| `protocol.authorization-error-unknown` | positive | authorization_event | python, typescript | +| `protocol.context-cleared` | positive | effective_context | python, typescript | | `security.duplicate-json-members` | negative | strict_json | python, typescript | | `security.ssrf-loopback` | negative | url_safety | python, typescript | | `security.ssrf-private` | negative | url_safety | python, typescript | diff --git a/docs/docs/protocol/coverage.mdx b/docs/docs/protocol/coverage.mdx index 9147239d..3f1d3809 100644 --- a/docs/docs/protocol/coverage.mdx +++ b/docs/docs/protocol/coverage.mdx @@ -4,10 +4,10 @@ title: Protocol coverage # Protocol coverage -The SDKs target **Personal Agent Protocol version 0.3, as published on November 4, 2026** -(upstream commit `2289293`, reviewed November 7, 2026) and the Operations -extension version 2. The -upstream draft remains authoritative. This page records, requirement by +The SDKs target **Personal Agent Protocol version 1.0, as published on November 14, 2026** +(upstream commit `8c02b42`, reviewed through `6764732` on November 17, 2026), the default, +and **version 0.4 as published on November 10, 2026** (upstream `4803900`), with the +Operations extension version 3. The upstream text remains authoritative. This page records, requirement by requirement, what the implementation and the conformance suite cover. ## Sources @@ -16,7 +16,7 @@ The specification is published by the [Personal Agent Protocol organization](https://github.com/personal-agent-protocol) at [personalagentprotocol.org](https://personalagentprotocol.org), built from [personal-agent-protocol/personal-agent-protocol](https://github.com/personal-agent-protocol/personal-agent-protocol). -Version 0.4, which SDK 0.33 and 0.34 implement as published (SDK 0.32 implemented its draft as of upstream `46beb21`), is frozen at [/docs/0.4/spec](https://personalagentprotocol.org/docs/0.4/spec), and draft 1.0 is in progress at [/docs/spec](https://personalagentprotocol.org/docs/spec); version 0.3, which SDK 0.27 to 0.31 implement, is frozen at [/docs/0.3/spec](https://personalagentprotocol.org/docs/0.3/spec); version 0.2, which SDK 0.25 and 0.26 +Version 0.4, which SDK 0.33 and 0.34 implement as published (SDK 0.32 implemented its draft as of upstream `46beb21`), is frozen at [/docs/0.4/spec](https://personalagentprotocol.org/docs/0.4/spec), and version 1.0, which SDK 0.37 implements as published (SDK 0.35 and 0.36 implemented its draft as of `c71f515`), at [/docs/1.0/spec](https://personalagentprotocol.org/docs/1.0/spec); version 0.3, which SDK 0.27 to 0.31 implement, is frozen at [/docs/0.3/spec](https://personalagentprotocol.org/docs/0.3/spec); version 0.2, which SDK 0.25 and 0.26 implement, is frozen at [/docs/0.2/spec](https://personalagentprotocol.org/docs/0.2/spec), and version 0.1, which SDK 0.24 and earlier implement, at [/docs/0.1/spec](https://personalagentprotocol.org/docs/0.1/spec). What changed @@ -25,11 +25,11 @@ between them is in the upstream SDKs, in [Migration](/releases/migration/#027--028). - [Overview and principles](https://personalagentprotocol.org/docs/introduction) -- [Draft specification](https://personalagentprotocol.org/docs/spec) +- [Specification 1.0](https://personalagentprotocol.org/docs/1.0/spec) - [Implementation guides](https://personalagentprotocol.org/docs/guides) - [Extensions](https://personalagentprotocol.org/docs/extensions) -- [Operations version 2](https://personalagentprotocol.org/docs/extensions/operations) -- [Open topics](https://personalagentprotocol.org/docs/path-to-1#open-topics) +- [Operations version 3](https://personalagentprotocol.org/docs/1.0/extensions/operations) +- [Open topics](https://personalagentprotocol.org/docs/introduction#open-topics) The repository records the reviewed upstream revision in `protocol/UPSTREAM.md` and maps individual normative requirements in @@ -46,20 +46,21 @@ validating the required shape of known types. Every entry of `protocol/requirements.yaml`, one page per area, with its upstream section, normative level, SDK symbols, tests and status. The Guides' recommendations are on their own page, apart from the specification's MUSTs -and SHOULDs. +and SHOULDs. A section marked `(1.0)` is a statement 1.0 as published adds or +changes, applied at 1.0; one marked `(0.4)` holds at 0.4 only. {/* coverage:begin (generated by scripts/generate_coverage.py) */} | Area | Entries | Implemented | Partial | Open | Not applicable | | --- | ---: | ---: | ---: | ---: | ---: | -| [Discovery](/protocol/coverage/discovery/) | 50 | 48 | 1 | 0 | 1 | -| [Identity and Sessions](/protocol/coverage/identity-sessions/) | 58 | 54 | 2 | 0 | 2 | -| [Sign-in and OAuth tokens](/protocol/coverage/sign-in/) | 21 | 16 | 4 | 1 | 0 | +| [Discovery](/protocol/coverage/discovery/) | 53 | 51 | 1 | 0 | 1 | +| [Identity and Sessions](/protocol/coverage/identity-sessions/) | 62 | 58 | 2 | 0 | 2 | +| [Sign-in and OAuth tokens](/protocol/coverage/sign-in/) | 30 | 23 | 6 | 1 | 0 | | [Browser](/protocol/coverage/browser/) | 19 | 16 | 1 | 1 | 1 | | [APIs](/protocol/coverage/apis/) | 6 | 6 | 0 | 0 | 0 | -| [Conversations](/protocol/coverage/conversations/) | 20 | 19 | 0 | 0 | 1 | +| [Conversations](/protocol/coverage/conversations/) | 22 | 21 | 0 | 0 | 1 | | [Task coverage](/protocol/coverage/feedback/) | 21 | 14 | 6 | 0 | 1 | -| [Security considerations](/protocol/coverage/security-considerations/) | 9 | 4 | 2 | 0 | 3 | +| [Security considerations](/protocol/coverage/security-considerations/) | 10 | 5 | 2 | 0 | 3 | | [Operations](/protocol/coverage/operations/) | 35 | 31 | 3 | 0 | 1 | | [Mediated Sign-In](/protocol/coverage/mediated-sign-in/) | 12 | 10 | 0 | 1 | 1 | | [UCP](/protocol/coverage/ucp/) | 13 | 10 | 0 | 1 | 2 | diff --git a/docs/docs/protocol/coverage/conversations.mdx b/docs/docs/protocol/coverage/conversations.mdx index fb53b5e2..9c40baf7 100644 --- a/docs/docs/protocol/coverage/conversations.mdx +++ b/docs/docs/protocol/coverage/conversations.mdx @@ -8,7 +8,7 @@ title: Conversations coverage Messages, events, streaming, handoff, Direct Conversations, and closing (§8). Upstream: [personalagentprotocol.org/docs/spec](https://personalagentprotocol.org/docs/spec). -20 entries: 19 implemented, 1 not-applicable. Each row is one atomic statement of the upstream text, with the SDK symbols that implement it (Python; TypeScript mirrors them), the tests and shared conformance cases that show it, and its status. +22 entries: 21 implemented, 1 not-applicable. Each row is one atomic statement of the upstream text, with the SDK symbols that implement it (Python; TypeScript mirrors them), the tests and shared conformance cases that show it, and its status. | ID | Section | Level | Role | Requirement | SDK symbol | Tests | Status | | --- | --- | --- | --- | --- | --- | --- | --- | @@ -32,5 +32,7 @@ Messages, events, streaming, handoff, Direct Conversations, and closing (§8). U | `PAP-8.10-02` | §8.10 | MUST | company | The Company MUST reject a user_requested_event_id that doesn't name a user_requested event in that parent with invalid_request. | [`CompanyService._accept_user_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_company_refusals.py::test_the_company_speaks_first_in_a_direct_conversation_the_user_accepted`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_company_refusals.py) | implemented | | `PAP-8.10-03` | §8.10 | MUST NOT | company | The Personal Agent may observe every message in a Direct Conversation. The Company MUST NOT send information there that it cannot share with the Personal Agent. | — | — | **not-applicable**: What a Company may say to the User but not to the Personal Agent is the Company's policy; the reference companies' agents say nothing in a Direct Conversation they would not say to the agent. | | `PAP-8.11-01` | §8.11 | MUST NOT | personal-agent | The Personal Agent MUST handle the event and matching challenge as one authorization need, and MUST NOT resubmit an accepted message because it received the challenge. | [`ConversationClient`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/conversations.py) | [`test_conversations.py::test_an_authorization_event_with_its_challenge_on_an_accepted_message_is_one_need`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_conversations.py) | implemented | +| `PAP10-8.1-01` | §8.1 (1.0) | MUST | company | An entry's description says, in plain language, what the agent at that endpoint can help with. The Company MUST include a description in every entry, and MAY say the agent can help with anything. | [`CompanyConfig`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`CompanyService.discovery_document`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`AgentProtocol`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py)
[`DiscoveryDocument.validate_version_fields`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) | [`test_published_10.py::test_a_10_document_needs_a_description_for_each_conversation_protocol`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_published_10.py::test_the_reference_company_describes_its_agent_at_10_and_not_at_04`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
`protocol.agent-protocol-description-required`
`protocol.agent-protocols-described` | implemented | +| `PAP10-8.6-01` | §8.6 (1.0) | MUST | personal-agent | Personal Agents MUST skip stream events with an SSE event name they don't recognize, so later versions and extensions can add them. | [`ConversationClient.stream`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/conversations.py) | [`test_published_10.py::test_a_stream_skips_event_names_it_doesnt_know`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py) | implemented | Conformance case IDs name `protocol/fixtures/conformance` cases; see the [conformance report](/protocol/conformance-report/) for their outcome in every language pairing. diff --git a/docs/docs/protocol/coverage/discovery.mdx b/docs/docs/protocol/coverage/discovery.mdx index 5e1038fa..a4d60ee2 100644 --- a/docs/docs/protocol/coverage/discovery.mdx +++ b/docs/docs/protocol/coverage/discovery.mdx @@ -8,7 +8,7 @@ title: Discovery coverage Company discovery, OAuth metadata, versions, and extensions (§3). Upstream: [personalagentprotocol.org/docs/spec](https://personalagentprotocol.org/docs/spec). -50 entries: 48 implemented, 1 partial, 1 not-applicable. Each row is one atomic statement of the upstream text, with the SDK symbols that implement it (Python; TypeScript mirrors them), the tests and shared conformance cases that show it, and its status. +53 entries: 51 implemented, 1 partial, 1 not-applicable. Each row is one atomic statement of the upstream text, with the SDK symbols that implement it (Python; TypeScript mirrors them), the tests and shared conformance cases that show it, and its status. | ID | Section | Level | Role | Requirement | SDK symbol | Tests | Status | | --- | --- | --- | --- | --- | --- | --- | --- | @@ -62,5 +62,8 @@ Company discovery, OAuth metadata, versions, and extensions (§3). Upstream: [pe | `PAP-3.4-07` | §3.4 | MUST | personal-agent | On every request with the Session header (5.2), the Personal Agent sends the protocol version it implements, compatible with the chosen one, in Poppy-Version, as major.minor. When it uses extensions with the Company, it also sends Poppy-Extensions, an RFC 9651 List of Strings, each the name of an extension in the chosen document, with the version it uses as a String in the v parameter. The Personal Agent MUST send the same values on every request in a Session, and starts a new Session to change them. | [`PapSession`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/sessions.py)
[`SessionClient.start`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/sessions.py)
[`DiscoveredCompany.session_version`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py)
[`implemented_version_for`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py)
[`session_headers`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/transport.py)
[`VERSION_HEADER`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/transport.py)
[`format_extensions_header`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/extensions.py)
[`negotiate_extensions`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/extensions.py) | [`test_draft_04.py::test_every_request_with_the_session_header_names_the_sessions_version`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_draft_04.py)
[`test_draft_10.py::test_a_session_names_the_version_given_else_the_companys_else_the_default_one`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_draft_10.py)
[`test_draft_04.py::test_a_session_declares_the_extensions_it_uses_with_the_company`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_draft_04.py)
[`test_fixtures.py::test_local_fixture_case`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_fixtures.py)
`protocol.extensions-header`
`protocol.unknown-extension-ignored` | implemented | | `PAP-3.4-08` | §3.4 | MUST | company | An endpoint that verifies the Session header (5.3) MUST also check Poppy-Version. | [`CompanyService._caller`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`CompanyConfig.serves_version`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_draft_04.py::test_a_request_without_poppy_version_or_in_an_unserved_one_is_refused`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_draft_04.py)
`protocol.version-header-required`
`protocol.version-unserved` | implemented | | `PAP-3.4-09` | §3.4 | MUST NOT | company | It rejects a request without it, or with a version that isn't compatible with one the Company serves, with version_unsupported (HTTP 400, JSON body), and MUST NOT handle the request under another version. | [`CompanyService._caller`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_draft_04.py::test_a_request_without_poppy_version_or_in_an_unserved_one_is_refused`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_draft_04.py)
`protocol.version-header-required`
`protocol.version-unserved` | implemented | +| `PAP10-3.1-01` | §3.1 (1.0) | MUST | both | domain MUST be the host that serves the document, after any redirects, with its port when that isn't 443. Personal Agents use a Company on another port only when configured to on purpose, such as for testing (section 3). | [`split_domain`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py)
[`DiscoveryDocument.validate_version_fields`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py)
[`DiscoveryClient.discover`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/discovery.py)
[`CompanyConfig`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_published_10.py::test_a_domain_names_its_port_when_that_isnt_443_from_10_only`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_published_10.py::test_an_agent_uses_a_company_on_another_port_only_when_configured_to`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
`protocol.organization-domain-port`
`protocol.organization-domain-port-not-allowed`
`protocol.organization-domain-port-other-domain` | implemented | +| `PAP10-3.4-01` | §3.4 (1.0) | MUST NOT | company | The Company MUST NOT send the Personal Agent a field, value, or event that only a minor version later than the request's Poppy-Version defines. | [`CompanyService.discovery_document`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_published_10.py::test_the_reference_company_describes_its_agent_at_10_and_not_at_04`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_published_10.py::test_nothing_of_10_goes_into_a_04_exchange`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
`protocol.agent-protocols-described` | implemented | +| `PAP10-3.4-02` | §3.4 (1.0) | MUST NOT | personal-agent | The Personal Agent MUST NOT send the Company one that only a version later than the chosen document's protocol_version defines. | [`ConversationClient._outgoing_message`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/conversations.py)
[`clears_context`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py)
[`DiscoveryDocument.validate_version_fields`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) | [`test_published_10.py::test_nothing_of_10_goes_into_a_04_exchange`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_published_10.py::test_a_10_document_needs_a_description_for_each_conversation_protocol`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
`protocol.agent-protocol-description-not-in-04`
`protocol.organization-domain-port-04` | implemented | Conformance case IDs name `protocol/fixtures/conformance` cases; see the [conformance report](/protocol/conformance-report/) for their outcome in every language pairing. diff --git a/docs/docs/protocol/coverage/identity-sessions.mdx b/docs/docs/protocol/coverage/identity-sessions.mdx index 2869d00a..d6c5edc8 100644 --- a/docs/docs/protocol/coverage/identity-sessions.mdx +++ b/docs/docs/protocol/coverage/identity-sessions.mdx @@ -8,7 +8,7 @@ title: Identity and Sessions coverage Personal-agent identity, User IDs, the Session header and delegated keys (§4.1, §5). Upstream: [personalagentprotocol.org/docs/spec](https://personalagentprotocol.org/docs/spec). -58 entries: 54 implemented, 2 partial, 2 not-applicable. Each row is one atomic statement of the upstream text, with the SDK symbols that implement it (Python; TypeScript mirrors them), the tests and shared conformance cases that show it, and its status. +62 entries: 58 implemented, 2 partial, 2 not-applicable. Each row is one atomic statement of the upstream text, with the SDK symbols that implement it (Python; TypeScript mirrors them), the tests and shared conformance cases that show it, and its status. | ID | Section | Level | Role | Requirement | SDK symbol | Tests | Status | | --- | --- | --- | --- | --- | --- | --- | --- | @@ -70,5 +70,9 @@ Personal-agent identity, User IDs, the Session header and delegated keys (§4.1, | `PAP-5.6-03` | §5.6 | MUST NOT | personal-agent | Personal Agents MUST NOT send tokens or Session JWTs in a URL, and Companies MUST NOT accept them from one. | [`SessionHttpClient.request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/transport.py)
[`ConversationClient._query`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/conversations.py) | [`test_transport.py::test_session_ended_restarts_once_with_a_fresh_jwt_and_a_redirect_gets_nothing`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_transport.py)
[`test_conformance.py::test_python_agent_python_company_over_tls`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_conformance.py)
`security.token-in-url-refused` | implemented | | `PAP-5.6-04` | §5.6 | MUST NOT | company | Personal Agents MUST NOT send tokens or Session JWTs in a URL, and Companies MUST NOT accept them from one. | [`CompanyService._caller`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_conformance.py::test_python_agent_python_company_over_tls`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_conformance.py)
`security.token-in-url-refused` | implemented | | `PAP-5.6-05` | §5.6 | MUST | personal-agent | A Company that limits how often a Personal Agent can make requests returns HTTP 429 with a Retry-After header when a request goes over the limit, on any of its endpoints, APIs, conversations, or website. The Personal Agent MUST wait at least that long before sending the request again. | [`ApiClient.call`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/apis.py)
[`ConversationClient._rejected`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/conversations.py)
[`SessionClient.token_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/sessions.py) | [`test_mediated.py::test_rate_limited_is_reported_with_retry_after_and_no_credential`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_mediated.py)
[`test_fixtures.py::test_local_fixture_case`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_fixtures.py)
`lifecycle.rate-limit-retry-after` | implemented | +| `PAP10-4.1-01` | §4.1 (1.0) | MUST | personal-agent | Client assertions follow RFC 7523 §3. The Personal Agent MUST include iat and a unique, unguessable jti, and MUST set exp at most 5 minutes after iat. | [`build_client_assertion_claims`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/sessions.py) | [`test_published_10.py::test_an_assertion_lasts_at_most_five_minutes_and_one_that_does_is_accepted`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py) | implemented | +| `PAP10-4.1-02` | §4.1 (1.0) | MUST NOT | company | A Company MAY reject a client assertion that lasts longer than 5 minutes, and MUST NOT reject one for lasting 5 minutes or less. | [`verify_assertion`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/verify.py) | [`test_published_10.py::test_an_assertion_lasts_at_most_five_minutes_and_one_that_does_is_accepted`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py) | implemented | +| `PAP10-4.1-03` | §4.1 (1.0) | MUST | company | Companies MUST accept client assertions signed with ES256 and with PS384. | [`verify_assertion`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/verify.py)
[`RSA_KEY_BITS`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/verify.py) | [`test_published_10.py::test_companies_accept_ps384_assertions_and_delegations`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_published_10.py::test_an_rsa_key_outside_2048_to_4096_bits_is_refused`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_blind_signing.py::test_a_company_takes_an_agent_that_signs_everything_blindly`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_blind_signing.py) | implemented | +| `PAP10-5.2-01` | §5.2 (1.0) | MUST | company | alg is ES256 or PS384. Companies MUST accept delegations signed with ES256 and with PS384. | [`verify_delegation`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/verify.py) | [`test_published_10.py::test_companies_accept_ps384_assertions_and_delegations`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py) | implemented | Conformance case IDs name `protocol/fixtures/conformance` cases; see the [conformance report](/protocol/conformance-report/) for their outcome in every language pairing. diff --git a/docs/docs/protocol/coverage/security-considerations.mdx b/docs/docs/protocol/coverage/security-considerations.mdx index 36ba7f3f..0420269b 100644 --- a/docs/docs/protocol/coverage/security-considerations.mdx +++ b/docs/docs/protocol/coverage/security-considerations.mdx @@ -8,7 +8,7 @@ title: Security considerations coverage Content from companies, secrets and the model, and delegated keys (§10). Upstream: [personalagentprotocol.org/docs/spec](https://personalagentprotocol.org/docs/spec). -9 entries: 4 implemented, 2 partial, 3 not-applicable. Each row is one atomic statement of the upstream text, with the SDK symbols that implement it (Python; TypeScript mirrors them), the tests and shared conformance cases that show it, and its status. +10 entries: 5 implemented, 2 partial, 3 not-applicable. Each row is one atomic statement of the upstream text, with the SDK symbols that implement it (Python; TypeScript mirrors them), the tests and shared conformance cases that show it, and its status. | ID | Section | Level | Role | Requirement | SDK symbol | Tests | Status | | --- | --- | --- | --- | --- | --- | --- | --- | @@ -21,5 +21,6 @@ Content from companies, secrets and the model, and delegated keys (§10). Upstre | `PAP-10.7-02` | §10.7 | MUST | personal-agent | The jti of a client assertion or delegation is that value, so the Personal Agent MUST generate it on the User's device. | [`BlindJoseSigner`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/blind.py) | [`test_blind_signing.py::test_the_key_holder_sees_only_the_blinded_message`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_blind_signing.py) | implemented | | `PAP-10.7-03` | §10.7 | MUST | personal-agent | A Personal Agent that signs blindly MUST therefore sign both its client assertions and its delegations blindly | [`BlindJoseSigner`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/blind.py) | [`test_blind_signing.py::test_a_delegation_is_signed_blindly_too`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_blind_signing.py)
[`test_blind_signing.py::test_a_company_takes_an_agent_that_signs_everything_blindly`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_blind_signing.py) | implemented | | `PAP-10.7-04` | §10.7 | MUST NOT | personal-agent | and MUST NOT rely on a signature by a key in its jwks_uri to mean its own systems approved what it signed, for example to limit delegation lifetimes or to stop a User. | — | — | **not-applicable**: What a host's systems rely on is theirs: the SDK's blind key holder approves nothing, and sees only blinded messages. | +| `PAP10-10.8-01` | §10.8 (1.0) | MUST | company | In Direct and Device Sign-In, the Company's consent page MUST list every scope it will grant, except a poppy:browser-sign-in it MAY grant without asking (section 6). It MAY mark the ones the User already granted. | [`CompanyService._authorize`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`CompanyService.authorization_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`CompanyService.device_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_published_10.py::test_the_consent_page_lists_every_scope_and_marks_the_earlier_ones`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_published_10.py::test_every_device_sign_in_shows_its_page_with_the_earlier_scopes_marked`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py) | implemented | Conformance case IDs name `protocol/fixtures/conformance` cases; see the [conformance report](/protocol/conformance-report/) for their outcome in every language pairing. diff --git a/docs/docs/protocol/coverage/sign-in.mdx b/docs/docs/protocol/coverage/sign-in.mdx index 13c6a175..72edacb3 100644 --- a/docs/docs/protocol/coverage/sign-in.mdx +++ b/docs/docs/protocol/coverage/sign-in.mdx @@ -8,7 +8,7 @@ title: Sign-in and OAuth tokens coverage Direct and Device Sign-In, refresh and access tokens, and scopes (§4, §4.2 to §4.8). Upstream: [personalagentprotocol.org/docs/spec](https://personalagentprotocol.org/docs/spec). -21 entries: 16 implemented, 4 partial, 1 open. Each row is one atomic statement of the upstream text, with the SDK symbols that implement it (Python; TypeScript mirrors them), the tests and shared conformance cases that show it, and its status. +30 entries: 23 implemented, 6 partial, 1 open. Each row is one atomic statement of the upstream text, with the SDK symbols that implement it (Python; TypeScript mirrors them), the tests and shared conformance cases that show it, and its status. | ID | Section | Level | Role | Requirement | SDK symbol | Tests | Status | | --- | --- | --- | --- | --- | --- | --- | --- | @@ -33,5 +33,14 @@ Direct and Device Sign-In, refresh and access tokens, and scopes (§4, §4.2 to | `PAP-4.7-05` | §4.7 | MUST | personal-agent | Each sign-in request MUST include scope, except where an extension continues an earlier request, as a space-separated string, following OAuth scope syntax. | [`_scopes`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py)
[`DeviceSignInClient.begin`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/device.py)
[`MediatedSignInClient.sign_in`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/mediated.py) | [`test_auth.py::test_builds_direct_sign_in_url_with_s256_pkce`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_auth.py)
[`test_conformance.py::test_python_agent_python_company_over_tls`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_conformance.py)
`lifecycle.sign-in-scopes`
`lifecycle.unknown-scope-refused` | implemented | | `PAP-4.7-06` | §4.7 | SHOULD | personal-agent | A Personal Agent SHOULD request only the scopes the User's tasks need, following RFC 9700 §2.3. | [`_scopes`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/cli_commands.py) | [`test_cli_protocol.py::test_exit_codes_for_setup_input_refusals_and_usage`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_cli_protocol.py) | **partial**: The SDK requests exactly the scopes the host names; the CLI never chooses for the user and refuses to sign in without --scope. | | `PAP-4.7-07` | §4.7 | SHOULD | personal-agent | The new refresh token replaces the old one, which the Personal Agent SHOULD revoke (4.6). | [`RefreshTokenClient.revoke`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/accounts.py) | — | **open**: No helper replaces and revokes the previous Account Token after a wider sign-in; the host calls revoke(). | +| `PAP10-4.2-01` | §4.2 (1.0) | MUST | personal-agent | Unless the Personal Agent receives the redirect only on the device that opened the authorization URL, as below, the authorization request MUST include prompt=consent (OpenID Connect Core §3.1.2.1). | [`build_direct_sign_in_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py)
[`DirectSignInClient.begin`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py)
[`PROMPT_CONSENT`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py) | [`test_published_10.py::test_a_direct_sign_in_asks_for_consent_unless_the_redirect_stays_on_the_device`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_hosted_pages.py::test_authorize_redirects_to_the_hosted_consent_page_which_reads_the_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_hosted_pages.py) | implemented | +| `PAP10-4.2-04` | §4.2 (1.0) | SHOULD | company | The Company SHOULD support prompt=consent, whether or not it supports OpenID Connect, and show its consent page for a request that includes it, even when the account already granted every requested scope to the client_id (10.8). | [`CompanyService._authorize`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`CompanyService.authorization_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_published_10.py::test_the_consent_page_lists_every_scope_and_marks_the_earlier_ones`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_hosted_pages.py::test_authorize_redirects_to_the_hosted_consent_page_which_reads_the_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_hosted_pages.py) | implemented | +| `PAP10-4.2-02` | §4.2 (1.0) | MUST | personal-agent | A Company MAY require Pushed Authorization Requests (PAR, RFC 9126) by setting require_pushed_authorization_requests to true in its issuer's metadata (3.2). The Personal Agent then MUST send the authorization request's parameters to the pushed_authorization_request_endpoint with its client assertion, and open the authorization_endpoint with only client_id and the request_uri it gets back. | [`DirectSignInClient.begin`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py)
[`DirectSignInClient._push`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py)
[`DirectSignInRequest.pushed_authorization_url`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py)
[`OAuthServerMetadata`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py)
[`CompanyService._pushed_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`CompanyConfig`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_published_10.py::test_a_company_offers_or_requires_par_and_the_agent_pushes`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_published_10.py::test_a_company_that_requires_par_takes_nothing_else`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_published_10.py::test_a_push_with_a_dpop_proof_binds_the_code_to_its_key`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
`dpop.pushed-authorization-request` | implemented | +| `PAP10-4.2-03` | §4.2 (1.0) | SHOULD | personal-agent | A Personal Agent SHOULD use PAR whenever the metadata lists the endpoint. | [`DirectSignInClient.begin`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py)
[`ConformanceContext.sign_in`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/conformance.py) | [`test_published_10.py::test_a_company_offers_or_requires_par_and_the_agent_pushes`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
`dpop.pushed-authorization-request` | **partial**: DirectSignInClient pushes whenever the host passes the issuer's pushed_authorization_request_endpoint, as the pap CLI and the conformance runner do; a host that calls it without the endpoint doesn't push. | +| `PAP10-4.2-05` | §4.2 (1.0) | SHOULD | personal-agent | When the Personal Agent sends the User a link to open later, such as on their phone, it SHOULD link to a page of its own that pushes the request when the User opens it and then redirects to the authorization_endpoint. | [`DirectSignInClient.open_link`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py) | [`test_published_10.py::test_a_link_opened_later_goes_to_the_agents_page_which_pushes_then`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py) | **partial**: begin(link_page=...) hands the browser the agent's own page and open_link pushes when it is opened; serving that page and redirecting is the host's. | +| `PAP10-4.3-01` | §4.3 (1.0) | SHOULD | company | The Company SHOULD show its consent page for every request, even when the account already granted every requested scope to the client_id (10.8). | [`CompanyService.device_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`CompanyService.approve_device`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_published_10.py::test_every_device_sign_in_shows_its_page_with_the_earlier_scopes_marked`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py) | implemented | +| `PAP10-4.4-01` | §4.4 (1.0) | MUST | personal-agent | A Personal Agent that sends a DPoP proof when it gets a refresh token (4.5) MUST send a proof from the same key with every refresh of that refresh token, and of the refresh tokens that replace it. | [`InMemoryDpopKeys`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/crypto.py)
[`JoseDpopProver`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/crypto.py)
[`RefreshTokenClient.refresh`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/accounts.py)
[`CompanyConfig`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_published_10.py::test_a_bound_refresh_token_refreshes_only_with_its_key`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
[`test_published_10.py::test_without_binding_a_refresh_with_a_new_key_still_works`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py)
`dpop.refresh-bound-to-its-key` | implemented | +| `PAP10-4.5-01` | §4.5 (1.0) | MUST | company | After a sign-in without resource, the Company MUST issue a token for any resource it offers Personal Agents, at refresh too. | [`CompanyService._refresh_grant`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`CompanyService._resource`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`CompanyService._resource_allowed`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`ServiceTokens.token_for`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/accounts.py) | [`test_published_10.py::test_a_service_left_out_is_invalid_target_and_used_signed_out`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py) | implemented | +| `PAP10-4.5-02` | §4.5 (1.0) | SHOULD NOT | personal-agent | The Personal Agent SHOULD NOT include resource in the request that starts sign-in: if it does, the Company MAY limit the grant to the resources it names, as RFC 8707 §2.2 allows. | [`build_direct_sign_in_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py)
[`DeviceSignInClient.begin`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/device.py) | [`test_published_10.py::test_a_direct_sign_in_asks_for_consent_unless_the_redirect_stays_on_the_device`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_published_10.py) | implemented | Conformance case IDs name `protocol/fixtures/conformance` cases; see the [conformance report](/protocol/conformance-report/) for their outcome in every language pairing. diff --git a/docs/docs/protocol/coverage/ucp.mdx b/docs/docs/protocol/coverage/ucp.mdx index 01986a66..ca593d34 100644 --- a/docs/docs/protocol/coverage/ucp.mdx +++ b/docs/docs/protocol/coverage/ucp.mdx @@ -23,7 +23,7 @@ The UCP extension, version 1. Upstream: [personalagentprotocol.org/docs/extensio | `UCP-4-03` | UCP §4 | MUST | company | A Company that offers both this protocol's sign-in and identity linking makes them one: it MUST offer Direct Sign-In, and MUST list private_key_jwt in its issuer's token_endpoint_auth_methods_supported. | [`CompanyConfig`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py)
[`CompanyService.oauth_metadata`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_ucp.py::test_a_company_that_speaks_ucp_lists_it_and_serves_its_profile_on_its_domain`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_ucp.py)
`protocol.ucp-profile` | implemented | | `UCP-4-04` | UCP §4 | MUST | company | The Company MUST list each scope in its identity linking config.scopes in scopes_supported, as UCP requires. | [`CompanyService.ucp_profile`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | [`test_ucp.py::test_a_company_that_speaks_ucp_lists_it_and_serves_its_profile_on_its_domain`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_ucp.py)
`protocol.ucp-profile` | implemented | | `UCP-4-05` | UCP §4 | MUST NOT | personal-agent | A Personal Agent MUST NOT send a token it got independently of this extension on a request that carries the Session header. | [`UcpClient.call`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) | [`test_ucp.py::test_orders_need_identity_linking_through_this_protocols_sign_in`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/__tests__/test_ucp.py) | implemented | -| `UCP-4-06` | UCP §4 | MUST | company | A Company that offers identity linking MUST keep the scopes the User already granted when it grants the missing ones, so the new token covers both. | [`CompanyService._sign_in`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | — | **open**: The reference companies grant the scopes a sign-in asks for; incremental authorization that keeps earlier grants is not implemented, so a Personal Agent asks again for every scope it still needs. | +| `UCP-4-06` | UCP §4 (0.4) | MUST | company | A Company that offers identity linking MUST keep the scopes the User already granted when it grants the missing ones, so the new token covers both. | [`CompanyService._sign_in`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/company/service.py) | — | **open**: 0.4 only. 1.0 replaced it (UCP 4) - the Personal Agent requests every scope it still needs and the Company grants only the scopes the request names, which the reference companies do at every version (ucp_scopes); incremental authorization that keeps earlier grants is not implemented for 0.4. | | `UCP-8-01` | UCP §8 | MUST NOT | personal-agent | It MUST NOT reuse one User's UCP workflow identifier for another User. | [`UcpClient`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) | — | **not-applicable**: UcpClient keeps no UCP workflow identifier: the host keeps carts, checkouts and orders by Company and User. | Conformance case IDs name `protocol/fixtures/conformance` cases; see the [conformance report](/protocol/conformance-report/) for their outcome in every language pairing. diff --git a/docs/docs/protocol/open-topics.mdx b/docs/docs/protocol/open-topics.mdx index 44f5afae..1fbc4c54 100644 --- a/docs/docs/protocol/open-topics.mdx +++ b/docs/docs/protocol/open-topics.mdx @@ -5,9 +5,9 @@ title: Open topics and SDK gaps # Open topics and SDK gaps -PAP version 0.4 is intentionally incomplete. Its -[upstream open-topics page](https://personalagentprotocol.org/docs/path-to-1#open-topics) -currently leaves three areas unspecified: +PAP version 1.0, published on 2026-11-14, is intentionally incomplete, as 0.4 was. Its +[upstream open topics](https://personalagentprotocol.org/docs/introduction#open-topics) +currently leave three areas unspecified: - **Payments:** how a personal agent pays through PAP or composes PAP with an existing payment protocol. @@ -20,12 +20,33 @@ These are protocol omissions, not SDK backlog items. The Python and TypeScript packages do not invent core wire fields, security semantics, or conformance claims for them. An experiment must use an explicitly negotiated extension, prefer a domain-qualified extension name, and document that it is outside PAP -version 0.4. Applications must continue to work when the other party ignores an -unknown extension. +versions 1.0 and 0.4. Applications must continue to work when the other party ignores +an unknown extension. + +## An operation in flight at sign-out + +Neither the specification nor the guides say what happens to an operation the +Company is already performing when the User signs out (or disconnects the agent). +The question is open upstream, in +[personal-agent-protocol#84](https://github.com/personal-agent-protocol/personal-agent-protocol/issues/84), +and this repository doesn't invent an answer. What the reference companies do +today, in both languages: + +- Sign-out takes effect at once for what comes after it: every refresh token and + access token of the sign-in stops working, so a new request is refused before it + acts, and a refresh is `invalid_grant`. +- An operation whose performing had already started when the User signed out + finishes, once, and its response reports the outcome (performed or failed) to + the request that started it, as for any other operation. Nothing is rolled back. + +An independent study observed exactly this on the Python SDK 0.35.0 (see +[Independent testing](./independent-testing)). Treat it as the SDK's current +behavior, not a protocol guarantee: a later upstream version may define it, and +the reference companies will follow. ## SDK implementation gaps -An SDK gap is different: version 0.4 or Operations version 3 already defines the +An SDK gap is different: version 1.0 or 0.4, or Operations version 3, already defines the behavior, and this repository doesn't implement it yet or leaves it to the host. Current examples include: diff --git a/docs/docs/protocol/status.mdx b/docs/docs/protocol/status.mdx index 795d7252..80f2a597 100644 --- a/docs/docs/protocol/status.mdx +++ b/docs/docs/protocol/status.mdx @@ -7,9 +7,11 @@ title: Protocol status Target: [PAP version 0.4](https://personalagentprotocol.org/docs/0.4/spec) as published (upstream `4803900`, November 10, 2026), and the Operations extension version 3 (see [Compatibility](/releases/compatibility/)). -The [1.0 draft](https://personalagentprotocol.org/docs/spec) as of upstream `c71f515` (November 11, 2026) is implemented -in Python and TypeScript, and since 0.36.0 it is the default: both roles announce `1.0` unless asked for 0.4 (`protocol_versions`), -and the advice of its spec 10.3 on lookalike domains (show the domain with the name) applies to every version. +[Version 1.0](https://personalagentprotocol.org/docs/1.0/spec) as published (upstream `8c02b42`, November 14, 2026) is +implemented in Python and TypeScript since 0.37.0, and since 0.36.0 1.0 is the default: both roles announce `1.0` unless asked +for 0.4 (`protocol_versions`). Where 1.0 changes 0.4's rules (descriptions, ports, Pushed Authorization Requests, consent, +refresh tokens bound to their DPoP key, unknown values), the SDK applies them at 1.0; the advice of its spec 10.3 on +lookalike domains (show the domain with the name) applies to every version. | Area | Status | | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | diff --git a/docs/docs/releases/compatibility.mdx b/docs/docs/releases/compatibility.mdx index 74d4ce7a..6424333d 100644 --- a/docs/docs/releases/compatibility.mdx +++ b/docs/docs/releases/compatibility.mdx @@ -4,7 +4,7 @@ title: Compatibility # Compatibility -This page is versioned with the SDK: it describes **SDK 0.36.1**. +This page is versioned with the SDK: it describes **SDK 0.37.0**. ## The PAP version implemented @@ -13,15 +13,16 @@ This page is versioned with the SDK: it describes **SDK 0.36.1**. | PAP profile | `PROTOCOL_PROFILE` = `0.4` | `PROTOCOL_PROFILE` = `"0.4"` | | Specification revision | `PROTOCOL_REVISION` = `2026-11-10` | `PROTOCOL_REVISION` = `"2026-11-10"` | | Operations extension | `OPERATIONS_VERSION` = `3` | `OPERATIONS_VERSION` = `"3"` | -| Draft, the default | `DRAFT_PROTOCOL_VERSION` = `1.0` (`DRAFT_PROTOCOL_REVISION` = `2026-11-11`) | `DRAFT_PROTOCOL_VERSION` = `"1.0"` (`DRAFT_PROTOCOL_REVISION` = `"2026-11-11"`) | +| Version 1.0, the default | `DRAFT_PROTOCOL_VERSION` = `1.0` (`DRAFT_PROTOCOL_REVISION` = `2026-11-14`, 1.0 as published) | `DRAFT_PROTOCOL_VERSION` = `"1.0"` (`DRAFT_PROTOCOL_REVISION` = `"2026-11-14"`) | | Default version | `DEFAULT_PROTOCOL_VERSION` = `1.0` | `DEFAULT_PROTOCOL_VERSION` = `"1.0"` | Both SDKs implement [PAP version 0.4](https://personalagentprotocol.org/docs/0.4/spec) as published on **2026-11-10** (upstream commit `4803900`, the 1.0 release candidate, frozen at `/docs/0.4/spec`), the **Operations -extension version 3**, the **Mediated Sign-In extension version 1** and the **Browser Control extension version 1**, and the -1.0 draft as of upstream `c71f515` (2026-11-11), which differs from 0.4 on the wire in its version string only. Since 0.36.0 -the 1.0 draft is the default: both SDKs and both reference companies announce and accept `protocol_version` `1.0` only -unless told otherwise. 0.4 stays available to a personal agent (`protocol_versions` on the discovery client) and a company +extension version 3**, the **Mediated Sign-In extension version 1** and the **Browser Control extension version 1**, and +[version 1.0](https://personalagentprotocol.org/docs/1.0/spec) as published on **2026-11-14** (upstream commit `8c02b42`, +frozen at `/docs/1.0/spec`) since 0.37.0. Since 0.36.0 1.0 is the default: both SDKs and both reference companies announce +and accept `protocol_version` `1.0` only unless told otherwise; where 1.0 changes 0.4's rules, the SDK applies them at 1.0 +only. 0.4 stays available to a personal agent (`protocol_versions` on the discovery client) and a company (`CompanyConfig.protocol_versions`) that name it. With both versions, the newest one both sides serve is chosen (spec 3.4). Operations version 2 is not supported on either side. Operations on websites (the `Poppy-Operation` header and the extension's `endpoint`) are implemented since 0.34.0, with the Browser Control extension. A test holds the two SDKs, this page, the package @@ -34,6 +35,7 @@ profile, never picked up from an unattended fetch. | SDK (PyPI and npm) | PAP profile | Specification revision | Operations | Breaking changes | | --- | --- | --- | --- | --- | +| `0.37.0` | `0.4` | 2026-11-10 | v3 | [0.36 → 0.37](/releases/migration/#036--037): 1.0 as published (`8c02b42`): required conversation protocol descriptions (`agent_description`), Pushed Authorization Requests, `prompt=consent`, refresh tokens bound to their DPoP key, ports in `organization.domain`, one sign-in for every resource, and unknown values read safely | | `0.36.1` | `0.4` | 2026-11-10 | v3 | none: a Session persisted without its version (before 0.36) restores at 0.4 in TypeScript too, as in Python | | `0.36.0` | `0.4` | 2026-11-10 | v3 | [0.35 → 0.36](/releases/migration/#035--036): the 1.0 draft is the default in both SDKs and both reference companies; 0.4 is used only when named (`protocol_versions`) | | `0.35.0` | `0.4` | 2026-11-10 | v3 | none: [0.34 → 0.35](/releases/migration/#034--035) adds the 1.0 draft as an opt-in second version (`protocol_versions`) and shows a company's domain beside its name | diff --git a/docs/docs/releases/migration.mdx b/docs/docs/releases/migration.mdx index ec8d1e1c..7ef6f156 100644 --- a/docs/docs/releases/migration.mdx +++ b/docs/docs/releases/migration.mdx @@ -10,6 +10,31 @@ section names the release that introduced the change; the [changelog](https://github.com/datalayer/personal-agent-protocol/blob/main/CHANGELOG.md) has the full list. +## 0.36 → 0.37 + +0.37.0 implements 1.0 as published (upstream `8c02b42`, frozen on 2026-11-14), the default +version, in both SDKs and both reference companies. It breaks the API: a company must say +what its agent helps with, a 1.0 document without that is refused, and a Direct Sign-In +request now carries `prompt=consent`. 0.4 as published is unchanged: where 1.0 differs, the +SDK applies 1.0's rule only at 1.0. + +| Change | What to do | +| --- | --- | +| Conversation protocol descriptions, required (spec 3.1, 8.1) | A company gives `CompanyConfig(agent_description="...")` (`agentDescription`), a required, non-blank string saying what its Company Agent can help with ("anything" is fine); a 1.0 `poppy.json` puts it in `agent.protocols[].description`, a 0.4 document leaves it out. `DiscoveryDocument` (`parseDiscoveryDocument`) refuses a 1.0 document whose `agent.protocols` entry has no `description` (`invalid_discovery_document` at discovery); `AgentProtocol.description` reads it. A hand-written 1.0 `poppy.json` adds it to every entry | +| Pushed Authorization Requests (spec 3.2, 4.2, 4.8; RFC 9126) | Pass the issuer's `pushed_authorization_request_endpoint` and `require_pushed_authorization_requests` (new on `OAuthServerMetadata`) to `DirectSignInClient.begin(...)` (`pushedAuthorizationRequestEndpoint`, `requirePushedAuthorizationRequests`): the request is pushed with a client assertion, and a DPoP proof when tokens are bound, and the browser opens the authorization endpoint with `client_id` and `request_uri` only. For a link the User opens later, give `link_page="https://your.agent/sign-in/{link}"` (`linkPage`): the browser handoff gets your page, which calls `open_link(link)` (`openLink`) when opened and redirects to the URL it returns. A company offers or requires PAR with `CompanyConfig(pushed_authorization_requests="offered" \| "required")` (`pushedAuthorizationRequests`, default `"off"`); the `pap` CLI and the conformance runner push whenever it's listed | +| `prompt=consent` (spec 4.2, 10.8) | Nothing: Direct Sign-In requests carry `prompt=consent` (`PROMPT_CONSENT`). Only when you receive the redirect on the device that opened the URL, pass `same_device_redirect=True` (`sameDeviceRedirect`) to leave it out. A company's hosted consent page lists every scope and shows even when the account granted them before: `authorization_request(request_id, account_id=...)` and `device_request(user_code, account_id=...)` (`{ accountId }`) now return `prompt` and, with the account, each scope's `granted_before`, which the page may mark | +| Same DPoP key at refresh (spec 4.4, 4.5, 10.7) | Nothing for an agent on the SDK's DPoP keys (one key per User ID, kept across refreshes); a host with its own key store must not rotate a User ID's DPoP key at refresh. A company may bind refresh tokens to the key with `CompanyConfig(bind_refresh_tokens=True)` (`bindRefreshTokens`, needs `dpop_binding`): a refresh with another key is `invalid_grant` | +| UCP scope requests (UCP 4, 11) | `ucp_scopes(profile, held, needed=..., protocol_version=...)` (`ucpScopes(profile, held, { needed, protocolVersion })`) returns every scope still needed at 1.0 (`held`, then those the challenge names); at 0.4 it still returns the missing ones only. The reference companies grant only the scopes a sign-in names | +| Ports in `organization.domain` (spec 3.1, 3.2) | Nothing by default: a domain with a port, or a document on a port other than 443, is refused (`port_not_allowed`). To test against a company on another port, `DiscoveryClient(allow_ports=True)` (`discoverCompany(domain, { allowPorts: true })`). A company serves `CompanyConfig(domain="shop.example:8443")` at 1.0 only. New helpers: `split_domain`, `domain_host`, `url_domain` (`splitDomain`, `domainHost`, `urlDomain`) | +| One sign-in for every resource (spec 4.5, 4.7, 4.8, 7) | Nothing: sign-in names no `resource`, and each refresh names one, as before. A company may leave a service out with a client policy's `allows_resource(client_id, resource)` (`allowsResource`): `invalid_target`, after which `ServiceTokens` uses that service signed out | +| PS384 and RSA key sizes (spec 4.1, 5.2, 10.7) | Nothing: the reference companies accept `PS384` and `ES256`; RSA keys outside 2048 to 4096 bits (`RSA_KEY_BITS`) are now refused for client assertions and delegations | +| Clearing context (spec 8.4) | Set a `context` field to `None` (`null`) to clear it, in a 1.0 Session only: a 0.4 Session refuses to send it (`context_clear_unsupported`). `effective_context(messages)` (`effectiveContext`) gives the shared context; a company's `Turn.context` is it | +| Room to extend conversations (spec 8.4, 8.6, 8.13) | Unknown `role` reads `company` and unknown `author.type` reads `agent` (`known_role`, `known_author_type`); unknown SSE event names are skipped; an unknown conversation `error` becomes `conversation_request_failed` with the original in `details["error"]` and the HTTP status kept (`KNOWN_CONVERSATION_ERRORS`, `known_conversation_error`). Code that matched an error code outside the spec now sees `conversation_request_failed`. The company drops `author.id`, `name` and `image` from the agent's messages | +| Unknown sign-in errors (spec 8.11) | `ConversationEvent.error` is any string; sign in again for `event.sign_in_scopes` (`signInScopes(event)`) whatever it says | +| `working` (spec 8.7) | Nothing: the reference companies set `working` only while replying; a long task is said in a message | +| Mediated Sign-In retirement | `MEDIATED_RETIREMENT_DATE` (`2027-03-17`): plan Direct or Device Sign-In for every company | +| Conformance | New cases (descriptions, ports, PAR, refresh binding, unknown roles and errors, cleared context) and a `pushed-requests` world (PAR required, refresh tokens bound); the suite runs at 1.0 and 0.4 in all four pairings | + ## 0.35 → 0.36 0.36.0 makes the 1.0 draft the default: both SDKs and both reference companies announce diff --git a/docs/docs/releases/support.mdx b/docs/docs/releases/support.mdx index c689fd04..c47629f0 100644 --- a/docs/docs/releases/support.mdx +++ b/docs/docs/releases/support.mdx @@ -8,8 +8,8 @@ title: Support | Version | Supported | | --- | --- | -| `0.36.x` | Yes: fixes and security fixes | -| `0.35.x` and earlier | No: upgrade with the [migration guide](/releases/migration/) | +| `0.37.x` | Yes: fixes and security fixes | +| `0.36.x` and earlier | No: upgrade with the [migration guide](/releases/migration/) | The SDKs are previews while PAP is a draft: only the latest minor release is supported, in both languages at once. A security fix is released as a new diff --git a/docs/docs/sdk/python-api.mdx b/docs/docs/sdk/python-api.mdx index 6c273aa5..aebaef71 100644 --- a/docs/docs/sdk/python-api.mdx +++ b/docs/docs/sdk/python-api.mdx @@ -31,6 +31,7 @@ Unknown or internal symbols are deliberately excluded. - [`ApprovalSurface`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Class. The host's own approval surface: the user, not a model, answers. - [`ApprovedUrl`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Class. A URL the safety policy approved, and the addresses it approved for its host. - [`Author`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. Who wrote a message (§7.4): `agent` or `human`, and for a Company message, who. +- [`AUTHOR_TYPES`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Constant. Public `AUTHOR_TYPES` constant. - [`AUTHORIZATION_CODE_GRANT`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Constant. Public `AUTHORIZATION_CODE_GRANT` constant. - [`AUTHORIZATION_STATE_STORES`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Constant. Public `AUTHORIZATION_STATE_STORES` constant. - [`AuthorizationError`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/errors.py) — Class. An authorization flow failed without exposing callback secrets. @@ -55,6 +56,7 @@ Unknown or internal symbols are deliberately excluded. - [`build_direct_sign_in_request`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py) — Function. Build a user-browser authorization URL with random state and S256 PKCE (§4.2). - [`build_pap_reactor`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Function. Build a PAP Reactor host with plugins and return any HTTP client it owns. - [`CACHES`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Constant. Public `CACHES` constant. +- [`clears_context`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Function. Whether a message sets a `context` field to `null` to clear it (§8.4): 1.0's, so a - [`ClientMetadata`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. Public `ClientMetadata` class. - [`Clock`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Class. Supply timezone-aware wall-clock time to expiring protocol state. - [`CLOCKS`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Constant. Public `CLOCKS` constant. @@ -90,6 +92,7 @@ Unknown or internal symbols are deliberately excluded. - [`DiscoveryClient`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/discovery.py) — Class. Discover and authenticate a company's PAP declaration. - [`DiscoveryDocument`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. Public `DiscoveryDocument` class. - [`DiscoveryError`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/errors.py) — Class. Discovery could not be completed safely. +- [`domain_host`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Function. The host of `organization.domain`, without the port it names (§3.1). - [`DPOP_PROVERS`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Constant. Public `DPOP_PROVERS` constant. - [`DpopKey`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/crypto.py) — Class. One DPoP key: `thumbprint` is what the Company binds a token to (RFC 9449 §6). - [`DpopKeyCustody`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/crypto.py) — Class. Where DPoP keys live: one per User ID, made on first use. @@ -98,6 +101,7 @@ Unknown or internal symbols are deliberately excluded. - [`DRAFT_PROTOCOL_REVISION`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/profile.py) — Constant. Public `DRAFT_PROTOCOL_REVISION` constant. - [`DRAFT_PROTOCOL_VERSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/profile.py) — Constant. Public `DRAFT_PROTOCOL_VERSION` constant. - [`Ed25519OperatorKey`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/operator_signatures.py) — Class. An operator's Ed25519 key in this process's memory. +- [`effective_context`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Function. The context the Personal Agent's messages share, in order (§8.4): fields a message - [`ExcludedTask`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. A task the company chose not to offer through the protocol (§8.1). - [`FeedbackClient`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/feedback.py) — Class. Send feedback reports in a Session, signed in or out. - [`FeedbackDescriptor`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. Where personal agents report a task the protocol can't do at this company (§9.3): @@ -120,16 +124,22 @@ Unknown or internal symbols are deliberately excluded. - [`JsonWebKeySet`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. A non-empty set of public keys suitable for PAP assertion verification. - [`jwk_thumbprint`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/crypto.py) — Function. A public JWK's RFC 7638 SHA-256 thumbprint: a Session JWT's `kid` (§5.2). - [`JWT_CLIENT_ASSERTION`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/sessions.py) — Constant. Public `JWT_CLIENT_ASSERTION` constant. +- [`known_author_type`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Function. An `author.type` this SDK doesn't recognize reads as `agent` (§8.4): a message is a +- [`known_conversation_error`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/conversations.py) — Function. `code` when this version defines it, else `default`: an error a later version or an +- [`KNOWN_CONVERSATION_ERRORS`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/conversations.py) — Constant. Public `KNOWN_CONVERSATION_ERRORS` constant. +- [`known_role`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Function. A `role` this SDK doesn't recognize reads as `company` (§8.4): content from the - [`Link`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. A web page a Company message refers to (Links 3): its HTTPS `url`, and its `title` - [`LinksContent`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. The Links extension's content of a Company message, `extensions.links` (Links 3). - [`MEDIATED_EXTENSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/mediated.py) — Constant. Public `MEDIATED_EXTENSION` constant. - [`MEDIATED_GRANT`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/mediated.py) — Constant. Public `MEDIATED_GRANT` constant. +- [`MEDIATED_RETIREMENT_DATE`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/mediated.py) — Constant. Public `MEDIATED_RETIREMENT_DATE` constant. - [`mediated_sign_in`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/mediated.py) — Function. What the company's Mediated Sign-In asks for, or `None` when it offers none. - [`MEDIATED_VERSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/mediated.py) — Constant. Public `MEDIATED_VERSION` constant. - [`MediatedSignIn`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. `extensions["mediated-sign-in"]`, version 1: the credentials to collect, its scopes. - [`MediatedSignInClient`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/mediated.py) — Class. Sign in with the user's credentials at the issuer's token endpoint, once. - [`MediatedSignInResult`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/mediated.py) — Class. Where a Mediated Sign-In stands, without any credential. - [`Message`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. A message sent by either side, or returned in a conversation event (§8.4). +- [`MESSAGE_ROLES`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Constant. Public `MESSAGE_ROLES` constant. - [`MetadataFetch`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Class. The bounds of one public metadata fetch: size, total time, approved addresses. - [`new_approval_reference`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/operations.py) — Function. A `reference` for one approval (Operations 6): `apr_` and 16 random bytes, so it is - [`new_dpop_key`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/crypto.py) — Function. A new P-256 key, used for nothing but DPoP proofs (§5.2). @@ -178,6 +188,7 @@ Unknown or internal symbols are deliberately excluded. - [`PersonalAgentProtocolError`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/errors.py) — Class. Base error whose string representation never includes response bodies. - [`pin_connections`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Function. Make `client`'s socket transports dial approved addresses during metadata fetches. - [`PinnedNetworkBackend`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Class. Dial the address the URL safety policy approved, never the host name again. +- [`PROMPT_CONSENT`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/auth.py) — Constant. Public `PROMPT_CONSENT` constant. - [`ProofError`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/errors.py) — Class. A signed assertion or proof-of-possession value is invalid. - [`PROTECTED_INPUTS`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Constant. Public `PROTECTED_INPUTS` constant. - [`ProtectedInput`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Class. Collect protected values from the user outside model context (PAP §4.7). @@ -225,6 +236,7 @@ Unknown or internal symbols are deliberately excluded. - [`SKILL_INDEX_SCHEMA`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Constant. Public `SKILL_INDEX_SCHEMA` constant. - [`SkillEntry`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Class. A skill a Company publishes for Personal Agents acting for the User there (§9.4). - [`speaks_ucp`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) — Function. Whether the Company lists the UCP extension at this version (UCP extension 2). +- [`split_domain`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Function. `organization.domain` as its host and its port, `None` for 443 (§3.1). - [`SqlitePairwiseUserIdStore`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/pairwise.py) — Class. Atomically persist random pairwise IDs in a local SQLite database. - [`stale_resource_metadata`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/accounts.py) — Function. Whether a service refused a token not issued for it (§4.5). - [`StreamItem`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/conversations.py) — Constant. Public `StreamItem` constant. @@ -255,12 +267,13 @@ Unknown or internal symbols are deliberately excluded. - [`UCP_PROFILE_PATH`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) — Constant. Public `UCP_PROFILE_PATH` constant. - [`ucp_profile_url`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) — Function. `https://{organization.domain}/.well-known/ucp`: on the validated domain, so the - [`UCP_PROFILE_VERSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) — Constant. Public `UCP_PROFILE_VERSION` constant. -- [`ucp_scopes`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) — Function. The identity linking scopes not in `held`: for `insufficient_scope`, UCP asks only +- [`ucp_scopes`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) — Function. The scopes a sign-in requests after a UCP `insufficient_scope` (UCP extension 4). - [`UCP_SHOPPING`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) — Constant. Public `UCP_SHOPPING` constant. - [`UCP_VERSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) — Constant. Public `UCP_VERSION` constant. - [`UcpClient`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) — Class. Send UCP REST requests through this extension (UCP extension 4). - [`UcpError`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) — Class. A UCP profile or request refused: its code, and `details` such as the scopes to get. - [`UcpProfile`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/ucp.py) — Class. A Company's UCP profile, as far as this extension reads it (UCP extension 3). +- [`url_domain`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/models.py) — Function. The domain an HTTPS URL is on, as `organization.domain` names it (§3.1): its host, - [`URL_SAFETY_POLICIES`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/reactor.py) — Constant. Public `URL_SAFETY_POLICIES` constant. - [`USER_STEP_ATTRIBUTE`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/browser_control.py) — Constant. Public `USER_STEP_ATTRIBUTE` constant. - [`user_step_kind`](https://github.com/datalayer/personal-agent-protocol/blob/main/personal_agent_protocol/browser_control.py) — Function. What a `data-poppy-user-step` value asks, or `None` without one (Browser Control 4). diff --git a/docs/docs/sdk/typescript-api.mdx b/docs/docs/sdk/typescript-api.mdx index d07faa5a..fe3038d6 100644 --- a/docs/docs/sdk/typescript-api.mdx +++ b/docs/docs/sdk/typescript-api.mdx @@ -18,7 +18,7 @@ Unknown or internal symbols are deliberately excluded. - [`AgentIdentityClientOptions`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/identity.ts) — Interface; entry `.`. Public TypeScript interface `AgentIdentityClientOptions`. - [`agentInstruction`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/operations.ts) — Function; entry `.`. An `AgentInstruction`, checked: an agent approval rests on an instruction the User gave. - [`AgentInstruction`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/operations.ts) — Interface; entry `.`. An instruction the User gave the Personal Agent, which an agent approval rests on -- [`AgentProtocol`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. A conversation protocol the Company Agent speaks (§3.1, §8); read `access` with `accountAccess`. +- [`AgentProtocol`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. A conversation protocol the Company Agent speaks (§3.1, §8.1); read `access` with - [`Alternative`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. Another way to do a task (§8.2): `instructions`, `references`, or both. - [`AlternativeReference`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. Where an alternative points (§8.2): an OpenAPI operation, an MCP tool, or a page. - [`ApiCallOptions`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/apis.ts) — Interface; entry `.`. Public TypeScript interface `ApiCallOptions`. @@ -45,11 +45,12 @@ Unknown or internal symbols are deliberately excluded. - [`ASSERTION_MAX_LIFETIME_SECONDS`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/sessions.ts) — Const; entry `.`. A client assertion's `exp` is at most this long after its `iat` (§4.1). - [`AuthCapabilities`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. `auth` (§3.1): optional; the issuer it names, and the Company's scopes. - [`Author`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. Who wrote a message (§7.4): `agent` or `human`, and for a Company message, who. +- [`AUTHOR_TYPES`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Const; entry `.`. The `author.type` values this version defines (§8.4). - [`AUTHORIZATION_CODE_GRANT`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Const; entry `.`. The grants that say the Company offers Direct and Device Sign-In (§3.2, §4.4). - [`AuthorizationError`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/errors.ts) — Class; entry `.`. Public TypeScript class `AuthorizationError`. - [`AuthorizationStateStore`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Interface; entry `.`. Public TypeScript interface `AuthorizationStateStore`. - [`AuthorizationStateStores`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Const; entry `.`. Public TypeScript const `AuthorizationStateStores`. -- [`AVAILABLE_PROTOCOL_VERSIONS`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Const; entry `.`. Every protocol version this SDK implements: 0.4 as published and the 1.0 draft. A Personal +- [`AVAILABLE_PROTOCOL_VERSIONS`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Const; entry `.`. Every protocol version this SDK implements: 0.4 and 1.0, both as published. A Personal - [`BlindJoseSigner`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/blind.ts) — Class; entry `.`. `pap.signer` on the User's device: PS384 signatures a key signs blindly (§10.7). - [`BlindJoseSignerOptions`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/blind.ts) — Interface; entry `.`. Public TypeScript interface `BlindJoseSignerOptions`. - [`BlindSigningKey`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/blind.ts) — Interface; entry `.`. The holder of a key in `jwks_uri`: it signs a blinded message, never seeing the JWT. @@ -81,6 +82,7 @@ Unknown or internal symbols are deliberately excluded. - [`challengeParameters`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/refusals.ts) — Function; entry `.`. The quoted parameters of a `WWW-Authenticate` header: `error`, `scope`, `extension`... - [`chooseProtocolVersion`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. The newest version, among `protocolVersion` and `supportedVersions`, that is compatible with - [`chosenVersion`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. The version a Personal Agent that implements `implemented` (this SDK's default versions +- [`clearsContext`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. Whether a message sets a `context` field to `null` to clear it (§8.4): 1.0's, so a Personal - [`ClientAssertionClaims`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/sessions.ts) — Interface; entry `.`. The claims of a `private_key_jwt` client assertion (§4.1). - [`ClientAssertionOptions`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/sessions.ts) — Interface; entry `.`. Public TypeScript interface `ClientAssertionOptions`. - [`ClientMetadata`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. Public TypeScript interface `ClientMetadata`. @@ -116,7 +118,7 @@ Unknown or internal symbols are deliberately excluded. - [`CROSS_DEVICE_LIFETIME_SECONDS`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/auth.ts) — Const; entry `.`. The longest a Direct Sign-In request lives when its link opens on another device: a - [`declinedFrom`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/operations.ts) — Function; entry `.`. The decline a Company answered an approval with, or `undefined` (Operations 6). - [`DEFAULT_CACHE_BOUNDS`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/limits.ts) — Const; entry `.`. At least a minute, at most a day (the Guides' example bounds). -- [`DEFAULT_PROTOCOL_VERSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/profile.ts) — Const; entry `.`. The version used unless a Personal Agent or a Company names others: the 1.0 draft. +- [`DEFAULT_PROTOCOL_VERSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/profile.ts) — Const; entry `.`. The version used unless a Personal Agent or a Company names others: 1.0. - [`DelegatedKey`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/crypto.ts) — Interface; entry `.`. One delegated key, its delegation, and when the delegation expires (§5.2). - [`DelegatedKeyCustody`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/crypto.ts) — Interface; entry `.`. Where delegated keys live: one current key per User ID, replaced when it rotates. - [`DelegatedKeyWho`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/crypto.ts) — Interface; entry `.`. Public TypeScript interface `DelegatedKeyWho`. @@ -137,7 +139,7 @@ Unknown or internal symbols are deliberately excluded. - [`DirectSignInClientOptions`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/auth.ts) — Interface; entry `.`. Public TypeScript interface `DirectSignInClientOptions`. - [`DirectSignInCompleteOptions`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/auth.ts) — Interface; entry `.`. Public TypeScript interface `DirectSignInCompleteOptions`. - [`DirectSignInOptions`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/auth.ts) — Interface; entry `.`. Public TypeScript interface `DirectSignInOptions`. -- [`DirectSignInRequest`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/auth.ts) — Interface; entry `.`. Public TypeScript interface `DirectSignInRequest`. +- [`DirectSignInRequest`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/auth.ts) — Interface; entry `.`. Authorization request state; its URL and PKCE values are secrets. - [`DirectSignInResult`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/auth.ts) — Type; entry `.`. A completed Direct Sign-In: the access token, and the refresh token's reference. - [`DirectSignInStart`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/auth.ts) — Interface; entry `.`. Public TypeScript interface `DirectSignInStart`. - [`Disclosure`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. A notice a Company marks apart from the rest of a message (Disclosures 3), such as an @@ -152,6 +154,7 @@ Unknown or internal symbols are deliberately excluded. - [`DiscoveryTransport`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Interface; entry `.`. Public TypeScript interface `DiscoveryTransport`. - [`DiscoveryTransports`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Const; entry `.`. Public TypeScript const `DiscoveryTransports`. - [`DisplayLike`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/ui.ts) — Type; entry `.`. Anything shaped like a display: Reactor's `Display`, or a tool result's `_meta["reactor.ui/display"]`. +- [`domainHost`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. The host of `organization.domain`, without the port it names (§3.1). - [`DPOP_ALGORITHM`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/crypto.ts) — Const; entry `.`. Public TypeScript const `DPOP_ALGORITHM`. - [`DPOP_HEADER`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/sessions.ts) — Const; entry `.`. The header that carries a DPoP proof (RFC 9449 §4.1). - [`DPOP_NONCE_HEADER`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/sessions.ts) — Const; entry `.`. The header a server gives a DPoP nonce in (RFC 9449 §8). @@ -164,10 +167,11 @@ Unknown or internal symbols are deliberately excluded. - [`DpopProofRequest`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Interface; entry `.`. What one DPoP proof is signed for (§4.5, RFC 9449 §4.2). - [`DpopProver`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Interface; entry `.`. Sign the DPoP proof of one request (§4.5). - [`DpopProvers`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Const; entry `.`. `DpopProver`: the DPoP proof of a request, when the Company lists ES256 or bound a token. -- [`DRAFT_PROTOCOL_REVISION`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/profile.ts) — Const; entry `.`. The draft's revision implemented: lookalike domains, its first fix (commit c71f515). -- [`DRAFT_PROTOCOL_VERSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/profile.ts) — Const; entry `.`. The draft protocol version, the 1.0 draft: the default since 0.36. +- [`DRAFT_PROTOCOL_REVISION`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/profile.ts) — Const; entry `.`. The 1.0 text implemented: 1.0 as published and frozen on 2026-11-14 (commit 8c02b42). +- [`DRAFT_PROTOCOL_VERSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/profile.ts) — Const; entry `.`. Protocol version 1.0, the default since 0.36 (named while it was the draft). - [`Ed25519OperatorKey`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/operator-signatures.ts) — Class; entry `.`. An operator's Ed25519 key in this process's memory. - [`effectiveChanges`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. A hint's `changes`, with a value this SDK doesn't know read as `irreversible` (§4.4). +- [`effectiveContext`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. The context the Personal Agent's messages share, in order (§8.4): fields a message leaves out - [`emsaPssEncode`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/blind.ts) — Value; entry `.`. Public TypeScript value `emsaPssEncode`. - [`ExcludedTask`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. A task the company chose not to offer through the protocol (§8.1). - [`ExtensionDescriptor`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. Public TypeScript interface `ExtensionDescriptor`. @@ -217,9 +221,13 @@ Unknown or internal symbols are deliberately excluded. - [`jwkThumbprint`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/crypto.ts) — Function; entry `.`. A public JWK's RFC 7638 SHA-256 thumbprint: a Session JWT's `kid` (§5.2). - [`JWT_CLIENT_ASSERTION`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/sessions.ts) — Const; entry `.`. Public TypeScript const `JWT_CLIENT_ASSERTION`. - [`KNOWN_API_TYPES`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/apis.ts) — Const; entry `.`. The API types this SDK speaks. +- [`KNOWN_CONVERSATION_ERRORS`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/conversations.ts) — Const; entry `.`. The conversation error codes this version defines (§7, §8.13, §5.6, §3.3): a code outside them - [`knownApis`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/apis.ts) — Function; entry `.`. The advertised APIs of a type this SDK speaks, in the company's order. +- [`knownAuthorType`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. An `author.type` this SDK doesn't recognize reads as `agent` (§8.4): a message is a person's +- [`knownConversationError`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/conversations.ts) — Function; entry `.`. `code` when this version defines it, else `fallback`: an error a later version or an extension - [`knownHandoff`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. A `handoff` this SDK doesn't recognize reads as `pending` (§8.7). - [`knownResponder`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. A `responder` this SDK doesn't recognize reads as `human` (§8.7). +- [`knownRole`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. A `role` this SDK doesn't recognize reads as `company` (§8.4): content from the Company, never - [`Link`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. A web page a Company message refers to (Links 3): its HTTPS `url`, and its `title` as the - [`LINKS_EXTENSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Const; entry `.`. Public TypeScript const `LINKS_EXTENSION`. - [`LINKS_VERSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Const; entry `.`. Public TypeScript const `LINKS_VERSION`. @@ -235,6 +243,7 @@ Unknown or internal symbols are deliberately excluded. - [`McpToolResult`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/mcp.ts) — Interface; entry `.`. A tool's answer; `operation` is set when it needs the user's approval (Operations 4). - [`MEDIATED_EXTENSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/mediated.ts) — Value; entry `.`. Public TypeScript value `MEDIATED_EXTENSION`. - [`MEDIATED_GRANT`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Const; entry `.`. The Mediated Sign-In extension's grant type (Mediated Sign-In 2). +- [`MEDIATED_RETIREMENT_DATE`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/mediated.ts) — Const; entry `.`. The day the protocol plans to retire the Mediated Sign-In extension (Mediated Sign-In 1, from - [`MEDIATED_VERSION`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/mediated.ts) — Const; entry `.`. Public TypeScript const `MEDIATED_VERSION`. - [`mediatedSignIn`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/mediated.ts) — Function; entry `.`. What the company's Mediated Sign-In asks for, or `undefined` when it offers none. - [`MediatedSignInClient`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/mediated.ts) — Class; entry `.`. Sign in with the user's credentials at the issuer's token endpoint, once. @@ -242,6 +251,7 @@ Unknown or internal symbols are deliberately excluded. - [`MediatedSignInOptions`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/mediated.ts) — Interface; entry `.`. Public TypeScript interface `MediatedSignInOptions`. - [`MediatedSignInResult`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/mediated.ts) — Interface; entry `.`. Where a Mediated Sign-In stands, without any credential. - [`Message`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. A message sent by either side, or returned in a conversation event (§8.4). +- [`MESSAGE_ROLES`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Const; entry `.`. The message roles this version defines (§8.4). - [`messageApproval`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. A Personal Agent message's approval: only this approves, never `text` (Operations 6). - [`messageDeclined`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. A Company message's decline of an approval: nothing was performed (Operations 6). - [`messageDisclosures`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. The notices a Company message marks apart (Disclosures 3); none without the extension. @@ -363,6 +373,7 @@ Unknown or internal symbols are deliberately excluded. - [`parseVersion`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. `major.minor` as numbers, or `ProtocolValidationError`. - [`PersonalAgentProtocolError`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/errors.ts) — Class; entry `.`. Safe base error for Personal Agent Protocol failures. - [`preferredSignIn`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. The sign-in type to use (§4): Direct Sign-In when the Company offers it, else Device Sign-In, +- [`PROMPT_CONSENT`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/auth.ts) — Const; entry `.`. The OpenID Connect `prompt` a Direct Sign-In request carries (OpenID Connect Core §3.1.2.1, - [`ProofError`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/errors.ts) — Class; entry `.`. Public TypeScript class `ProofError`. - [`ProtectedInput`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Interface; entry `.`. The host's trusted input surface: answers never pass through a model. - [`ProtectedInputField`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Interface; entry `.`. Public TypeScript interface `ProtectedInputField`. @@ -440,6 +451,7 @@ Unknown or internal symbols are deliberately excluded. - [`Signers`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Const; entry `.`. Public TypeScript const `Signers`. - [`signInDisabled`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. Whether the Company turned sign-in off (`auth.disabled`, §3.2): a Personal Agent starts no - [`SignInResult`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/sessions.ts) — Interface; entry `.`. A completed sign-in (§4.7): the access token, and the refresh token's reference. +- [`signInScopes`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. For an `authorization` event, the scopes to sign in again for (§5.4, §8.11): those in `scope`, - [`SignInType`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Type; entry `.`. Public TypeScript type `SignInType`. - [`signInTypes`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. The sign-in types the Company offers a Personal Agent, in the order it prefers them (§4): - [`signOperatorRequest`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/operator-signatures.ts) — Value; entry `.`. Public TypeScript value `signOperatorRequest`. @@ -449,6 +461,7 @@ Unknown or internal symbols are deliberately excluded. - [`SKILL_TYPES`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Const; entry `.`. The artifact types the SDK recognizes (§9.4): a single `SKILL.md`, or an archive with - [`SkillEntry`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Interface; entry `.`. A skill a Company publishes for Personal Agents acting for the User there (§9.4). - [`speaksUcp`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/ucp.ts) — Function; entry `.`. Whether the Company lists the UCP extension at this version (UCP extension 2). +- [`splitDomain`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. `organization.domain` as its host and its port, `undefined` for 443 (§3.1). - [`staleResourceMetadata`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/accounts.ts) — Function; entry `.`. Whether a service refused a token not issued for it (§4.5). - [`StartConversationOptions`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/conversations.ts) — Interface; entry `.`. Public TypeScript interface `StartConversationOptions`. - [`StreamItem`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/conversations.ts) — Type; entry `.`. Public TypeScript type `StreamItem`. @@ -497,7 +510,8 @@ Unknown or internal symbols are deliberately excluded. - [`ucpOffers`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/ucp.ts) — Function; entry `.`. Whether the profile lists `capability` (UCP's name, such as `dev.ucp.shopping.order`). - [`UcpProfile`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/ucp.ts) — Interface; entry `.`. A Company's UCP profile, as far as this extension reads it (UCP extension 3): data, never instructions. - [`ucpProfileUrl`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/ucp.ts) — Function; entry `.`. `https://{organization.domain}/.well-known/ucp`, on the validated domain (UCP extension 3). -- [`ucpScopes`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/ucp.ts) — Function; entry `.`. The identity linking scopes not in `held`: UCP asks only for the missing ones (UCP extension 4). +- [`ucpScopes`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/ucp.ts) — Function; entry `.`. The scopes a sign-in requests after a UCP `insufficient_scope` (UCP extension 4). +- [`urlDomain`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. The domain an HTTPS URL is on, as `organization.domain` names it (§3.1): its host, lowercase, - [`UrlSafetyPolicies`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Const; entry `.`. Public TypeScript const `UrlSafetyPolicies`. - [`UrlSafetyPolicy`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/reactor.ts) — Interface; entry `.`. Public TypeScript interface `UrlSafetyPolicy`. - [`usableReferences`](https://github.com/datalayer/personal-agent-protocol/blob/main/src/models.ts) — Function; entry `.`. The references an agent may follow (§8.2). diff --git a/docs/docs/sdk/typescript.mdx b/docs/docs/sdk/typescript.mdx index 9819ccde..32228c98 100644 --- a/docs/docs/sdk/typescript.mdx +++ b/docs/docs/sdk/typescript.mdx @@ -339,6 +339,7 @@ const config = new CompanyConfig({ name: "Example Shop", domain: "shop.example", scopes: ["orders:read", "orders:write"], + agentDescription: "Anything about your orders and returns", scopeDescriptions: { "orders:read": "See your orders", "orders:write": "Exchange or return items in your orders", diff --git a/examples/pydantic-ai/company-service/app.py b/examples/pydantic-ai/company-service/app.py index 3b0fa27c..36719020 100644 --- a/examples/pydantic-ai/company-service/app.py +++ b/examples/pydantic-ai/company-service/app.py @@ -73,6 +73,7 @@ name="Juniper Library", domain=DOMAIN, scopes=("loans:read", "loans:write"), + agent_description="Anything about your account", write_scopes=("loans:write",), # The library's own scopes, each described in words a user and a model understand # (`auth.scopes`), with what its most consequential operation changes and whether it diff --git a/package.json b/package.json index 0ac5a068..9cdb6ea2 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@datalayer/personal-agent-protocol", - "version": "0.36.1", + "version": "0.37.0", "description": "TypeScript SDK for Personal Agent Protocol 0.4 (2026-11-10) and its Operations extension v3", "repository": { "type": "git", diff --git a/personal_agent_protocol/__init__.py b/personal_agent_protocol/__init__.py index 7082fc72..ec7161f7 100644 --- a/personal_agent_protocol/__init__.py +++ b/personal_agent_protocol/__init__.py @@ -24,6 +24,7 @@ openapi_url, ) from .auth import ( + PROMPT_CONSENT, DirectSignInCallback, DirectSignInClient, DirectSignInRequest, @@ -54,6 +55,7 @@ user_step_kind, ) from .conversations import ( + KNOWN_CONVERSATION_ERRORS, ConversationClient, ConversationReceipt, ConversationResponse, @@ -63,6 +65,7 @@ TextDelta, WorkingChanged, generate_request_id, + known_conversation_error, ) from .crypto import ( DelegatedKey, @@ -104,15 +107,18 @@ from .mediated import ( MEDIATED_EXTENSION, MEDIATED_GRANT, + MEDIATED_RETIREMENT_DATE, MEDIATED_VERSION, MediatedSignInClient, MediatedSignInResult, mediated_sign_in, ) from .models import ( + AUTHOR_TYPES, AUTHORIZATION_CODE_GRANT, AVAILABLE_PROTOCOL_VERSIONS, BROWSER_SIGN_IN_SCOPE, + MESSAGE_ROLES, SKILL_INDEX_SCHEMA, SUPPORTED_PROTOCOL_VERSIONS, Alternative, @@ -144,9 +150,16 @@ SkillEntry, TasksDescriptor, TasksResponse, + clears_context, + domain_host, + effective_context, is_loopback_redirect, + known_author_type, + known_role, operations_content, redirect_uri_matches, + split_domain, + url_domain, ) from .operations import ( ACTION_FAILED, @@ -301,6 +314,7 @@ "APPROVAL_SURFACES", "AUTHORIZATION_CODE_GRANT", "AUTHORIZATION_STATE_STORES", + "AUTHOR_TYPES", "AVAILABLE_PROTOCOL_VERSIONS", "BROWSER_CONTROL_EXTENSION", "BROWSER_CONTROL_VERSION", @@ -316,15 +330,19 @@ "DRAFT_PROTOCOL_REVISION", "DRAFT_PROTOCOL_VERSION", "JWT_CLIENT_ASSERTION", + "KNOWN_CONVERSATION_ERRORS", "MEDIATED_EXTENSION", "MEDIATED_GRANT", + "MEDIATED_RETIREMENT_DATE", "MEDIATED_VERSION", + "MESSAGE_ROLES", "OPERATIONS_EXTENSION", "OPERATIONS_VERSION", "OPERATION_HEADER", "OPERATION_REFERENCE", "OPERATOR_SIGNERS", "PAIRWISE_USER_ID_STORES", + "PROMPT_CONSENT", "PROTECTED_INPUTS", "PROTOCOL_PROFILE", "PROTOCOL_REVISION", @@ -512,15 +530,21 @@ "build_client_assertion_claims", "build_direct_sign_in_request", "build_pap_reactor", + "clears_context", "controller_script", "controller_update_script", "create_resolving_client", "declined_from", + "domain_host", + "effective_context", "fetch_ucp_profile", "generate_pairwise_user_id", "generate_request_id", "is_loopback_redirect", "jwk_thumbprint", + "known_author_type", + "known_conversation_error", + "known_role", "mediated_sign_in", "new_approval_reference", "new_dpop_key", @@ -546,12 +570,14 @@ "scopes_to_request", "sign_operator_request", "speaks_ucp", + "split_domain", "stale_resource_metadata", "tasks_endpoint", "terms_differences", "ucp_agent_header", "ucp_profile_url", "ucp_scopes", + "url_domain", "user_step_kind", "validate_direct_sign_in_callback", "verification_host_allowed", diff --git a/personal_agent_protocol/__tests__/test_conformance.py b/personal_agent_protocol/__tests__/test_conformance.py index e1a7b473..bebc0549 100644 --- a/personal_agent_protocol/__tests__/test_conformance.py +++ b/personal_agent_protocol/__tests__/test_conformance.py @@ -22,6 +22,7 @@ from personal_agent_protocol.demo.conformance import ManzanitaConformance DPOP_WORLD = "dpop-binding" +PUSHED_WORLD = "pushed-requests" NO_ISSUER_WORLD = "no-issuer" OPERATOR_WORLDS = ("operator-signatures", "operator-signatures-required") @@ -81,6 +82,26 @@ async def test_python_agent_python_company_binding_with_dpop_over_tls() -> None: assert len(cases) >= 20 +@pytest.mark.asyncio +async def test_python_agent_python_company_with_pushed_requests_over_tls() -> None: + """The pushed-requests world's cases: Manzanita requires Pushed Authorization Requests + and binds refresh tokens to their DPoP key (§4.2, §4.4, RFC 9126).""" + + pytest.importorskip("uvicorn") + from personal_agent_protocol.demo.sockets import served_over_tls + + world = ManzanitaConformance(PUSHED_WORLD) + cases = select_cases(world=PUSHED_WORLD) + async with served_over_tls(world.network) as network: + assert network.socket_transport is not None + report = await run_conformance(world.context(), cases=cases) + save_world_report(report, "python-agent-python-company", PUSHED_WORLD) + assert _failures(report) == [] + assert {r.id for r in report.results} == {case.id for case in cases} + assert {r.outcome for r in report.results} == {"passed"} + assert len(cases) >= 2 + + @pytest.mark.asyncio async def test_python_agent_python_company_with_no_issuer_over_tls() -> None: """The no-issuer world's cases: Manzanita runs no OAuth server (§3.2).""" @@ -120,7 +141,7 @@ async def test_python_agent_python_company_with_operator_signatures_over_tls(nam def test_every_runner_case_belongs_to_one_world() -> None: - worlds = (None, DPOP_WORLD, NO_ISSUER_WORLD, *OPERATOR_WORLDS) + worlds = (None, DPOP_WORLD, PUSHED_WORLD, NO_ISSUER_WORLD, *OPERATOR_WORLDS) selected = [case.id for world in worlds for case in select_cases(world=world)] assert sorted(selected) == sorted(CASES) diff --git a/personal_agent_protocol/__tests__/test_conversations.py b/personal_agent_protocol/__tests__/test_conversations.py index a0a254ef..fe24026d 100644 --- a/personal_agent_protocol/__tests__/test_conversations.py +++ b/personal_agent_protocol/__tests__/test_conversations.py @@ -116,9 +116,9 @@ def company(request: httpx.Request) -> httpx.Response: @pytest.mark.asyncio -async def test_surfaces_message_id_conflict_without_response_body() -> None: +async def test_surfaces_request_id_conflict_without_response_body() -> None: def company(_: httpx.Request) -> httpx.Response: - return httpx.Response(409, json={"error": "message_id_conflict", "secret": "omit"}) + return httpx.Response(409, json={"error": "request_id_conflict", "secret": "omit"}) async with httpx.AsyncClient(transport=httpx.MockTransport(company)) as http: reactor, _ = build_pap_reactor(http_client=http) @@ -132,7 +132,7 @@ def company(_: httpx.Request) -> httpx.Response: ) reactor.stop() - assert caught.value.code == "message_id_conflict" + assert caught.value.code == "request_id_conflict" assert "secret" not in str(caught.value) diff --git a/personal_agent_protocol/__tests__/test_cross_language.py b/personal_agent_protocol/__tests__/test_cross_language.py index ce6f7f2d..68b359d5 100644 --- a/personal_agent_protocol/__tests__/test_cross_language.py +++ b/personal_agent_protocol/__tests__/test_cross_language.py @@ -65,6 +65,7 @@ TYPESCRIPT_WORLDS: tuple[str | None, ...] = ( None, "dpop-binding", + "pushed-requests", "no-issuer", "operator-signatures", "operator-signatures-required", diff --git a/personal_agent_protocol/__tests__/test_docs_examples.py b/personal_agent_protocol/__tests__/test_docs_examples.py index 9f2e3ecf..a3ca786e 100644 --- a/personal_agent_protocol/__tests__/test_docs_examples.py +++ b/personal_agent_protocol/__tests__/test_docs_examples.py @@ -205,6 +205,7 @@ def _company(self, domain: str, name: str) -> Any: name=name, domain=domain, scopes=SCOPES, + agent_description="Anything about your account", scope_descriptions={scope: f"The {scope} scope" for scope in SCOPES}, write_scopes=("orders:write",), mediated_fields=(("email", "Email", False), ("password", "Password", True)), @@ -1049,7 +1050,15 @@ def test_the_json_example_is_valid(key: str) -> None: "protocol_version": "0.4", "organization": {"name": "Example", "domain": "example.com"}, "auth": {"issuer": "https://example.com", "scopes": {"a:read": "Read a"}}, - "agent": {"protocols": [{"type": "poppy", "endpoint": "https://example.com/c"}]}, + "agent": { + "protocols": [ + { + "type": "poppy", + "endpoint": "https://example.com/c", + "description": "Anything", + } + ] + }, **value, } ) diff --git a/personal_agent_protocol/__tests__/test_draft_04.py b/personal_agent_protocol/__tests__/test_draft_04.py index 47ad1310..87bff07a 100644 --- a/personal_agent_protocol/__tests__/test_draft_04.py +++ b/personal_agent_protocol/__tests__/test_draft_04.py @@ -135,6 +135,7 @@ def test_the_reference_company_offers_direct_sign_in() -> None: name="Bank", domain="bank.example", scopes=("accounts:read",), + agent_description="Anything about your account", scope_descriptions={"accounts:read": "See your accounts"}, operations=False, device=False, diff --git a/personal_agent_protocol/__tests__/test_draft_10.py b/personal_agent_protocol/__tests__/test_draft_10.py index 51d3611f..a5f9b110 100644 --- a/personal_agent_protocol/__tests__/test_draft_10.py +++ b/personal_agent_protocol/__tests__/test_draft_10.py @@ -83,7 +83,7 @@ async def _session(world: World, *versions: str) -> PapSession: def test_the_draft_is_the_default_and_the_published_version_is_available() -> None: assert (PROTOCOL_PROFILE, DRAFT_PROTOCOL_VERSION) == ("0.4", "1.0") assert DEFAULT_PROTOCOL_VERSION == DRAFT_PROTOCOL_VERSION - assert DRAFT_PROTOCOL_REVISION == "2026-11-11" + assert DRAFT_PROTOCOL_REVISION == "2026-11-14" assert SUPPORTED_PROTOCOL_VERSIONS == {"1.0"} assert AVAILABLE_PROTOCOL_VERSIONS == {"0.4", "1.0"} assert implemented_protocol_versions() == {"1.0"} diff --git a/personal_agent_protocol/__tests__/test_fixtures.py b/personal_agent_protocol/__tests__/test_fixtures.py index 19a444db..a56dad5f 100644 --- a/personal_agent_protocol/__tests__/test_fixtures.py +++ b/personal_agent_protocol/__tests__/test_fixtures.py @@ -59,12 +59,14 @@ from personal_agent_protocol.json import loads_strict from personal_agent_protocol.models import ( Author, + ConversationEvent, ConversationEventPage, DiscoveryDocument, ExtensionDescriptor, Message, Operation, ProtectedResourceMetadata, + effective_context, ) from personal_agent_protocol.operator_signatures import ( operator_key_from, @@ -217,6 +219,16 @@ async def _check(case: Any) -> None: # noqa: C901 - one branch per fixture chec for context in given["invalid"]: with pytest.raises(ValueError): Message(id="msg_ctx", author=Author(type="agent"), context=context) + elif case.check == "message_tolerance": + messages = [Message.model_validate(value) for value in given] + assert [message.role for message in messages] == expect["roles"] + assert [message.author.type for message in messages] == expect["author_types"] + elif case.check == "authorization_event": + event = ConversationEvent.model_validate(given) + assert list(event.sign_in_scopes) == expect["sign_in_scopes"] + elif case.check == "effective_context": + messages = [Message(author=Author(type="agent"), context=value) for value in given] + assert effective_context(messages) == expect["context"] elif case.check == "operation": if not expect["valid"]: with pytest.raises(ValueError): @@ -231,6 +243,7 @@ async def _check(case: Any) -> None: # noqa: C901 - one branch per fixture chec http_client=http, address_resolver=_public, timeout=float(given.get("timeout_seconds", 5.0)), + allow_ports=bool(given.get("allow_ports", False)), ) try: if "error" in expect: diff --git a/personal_agent_protocol/__tests__/test_hosted_pages.py b/personal_agent_protocol/__tests__/test_hosted_pages.py index 27892c38..17edefab 100644 --- a/personal_agent_protocol/__tests__/test_hosted_pages.py +++ b/personal_agent_protocol/__tests__/test_hosted_pages.py @@ -52,6 +52,7 @@ def test_hosted_page_templates_are_checked() -> None: "name": "Shop", "domain": "shop.example", "scopes": ("orders:read",), + "agent_description": "Anything about your orders", "scope_descriptions": {"orders:read": "See orders"}, "operations": False, } @@ -126,8 +127,11 @@ async def test_authorize_redirects_to_the_hosted_consent_page_which_reads_the_re "heading", "caution", "scopes", + "prompt", "expires_at", } + # The agent asked for the consent page whatever the account granted before (spec 4.2). + assert summary["prompt"] == "consent" # The user allows on the hosted page; the sign-in completes as before. callback = await world.shop.approve_authorization(request_id, account_id="acct_ada") diff --git a/personal_agent_protocol/__tests__/test_issuerless.py b/personal_agent_protocol/__tests__/test_issuerless.py index 334bc13a..baea2b4c 100644 --- a/personal_agent_protocol/__tests__/test_issuerless.py +++ b/personal_agent_protocol/__tests__/test_issuerless.py @@ -27,7 +27,11 @@ "protocol_version": "1.0", "organization": {"name": "Example", "domain": "Example.COM"}, "apis": [{"type": "openapi", "url": "https://example.com/o.json", "description": "Catalog"}], - "agent": {"protocols": [{"type": "poppy", "endpoint": "https://example.com/poppy"}]}, + "agent": { + "protocols": [ + {"type": "poppy", "endpoint": "https://example.com/poppy", "description": "Anything"} + ] + }, "feedback": {"endpoint": "https://example.com/feedback"}, "web": {"browser_session_endpoint": "https://example.com/join"}, } @@ -111,7 +115,12 @@ async def test_with_an_issuer_the_identifier_is_the_issuer() -> None: { "agent": { "protocols": [ - {"type": "poppy", "endpoint": "https://example.com/p", "access": "signed_in"} + { + "type": "poppy", + "endpoint": "https://example.com/p", + "description": "Anything", + "access": "signed_in", + } ] } }, diff --git a/personal_agent_protocol/__tests__/test_operator_signatures.py b/personal_agent_protocol/__tests__/test_operator_signatures.py index 08939bf3..777a87c8 100644 --- a/personal_agent_protocol/__tests__/test_operator_signatures.py +++ b/personal_agent_protocol/__tests__/test_operator_signatures.py @@ -221,6 +221,7 @@ def test_a_company_takes_off_optional_or_required() -> None: domain="shop.example", name="Shop", scopes=("orders:read",), + agent_description="Anything about your account", operator_signatures=cast(Any, "sometimes"), ) diff --git a/personal_agent_protocol/__tests__/test_published_10.py b/personal_agent_protocol/__tests__/test_published_10.py new file mode 100644 index 00000000..cb3c136f --- /dev/null +++ b/personal_agent_protocol/__tests__/test_published_10.py @@ -0,0 +1,894 @@ +# Copyright (c) 2025-2026 Datalayer, Inc. +# +# BSD 3-Clause License + +"""Version 1.0 as published (upstream 8c02b42, frozen 2026-11-14): what changed after the +draft as of c71f515, both sides, in one process; `src/__tests__/published-10.test.mjs` +ports it. + +Conversation protocol descriptions, Pushed Authorization Requests, minor versions, PS384, +consent for scopes granted before, the same DPoP key at refresh, UCP scope requests, ports +in `organization.domain`, client assertion lifetimes, one sign-in for every resource, +clearing context, room to extend conversations, what `working` means, unknown sign-in +errors, and the Mediated Sign-In retirement date. 0.4 as published is unchanged. +""" + +from __future__ import annotations + +import json +from dataclasses import replace +from datetime import datetime, timedelta, timezone +from typing import Any +from urllib.parse import parse_qs, urlsplit + +import httpx +import jwt +import pytest +from cryptography.hazmat.primitives.asymmetric import ec, rsa +from pydantic import SecretStr +from reactor import PluginManifest # type: ignore[import-untyped] + +from personal_agent_protocol import ( + KNOWN_CONVERSATION_ERRORS, + MEDIATED_RETIREMENT_DATE, + PROMPT_CONSENT, + AuthorizationError, + ConversationClient, + ConversationError, + DirectSignInClient, + DiscoveryClient, + DiscoveryDocument, + PapSession, + ProtocolValidationError, + RefreshTokenClient, + build_pap_reactor, + clears_context, + effective_context, + known_conversation_error, + page_carries_session, + ucp_scopes, + url_domain, +) +from personal_agent_protocol.auth import build_direct_sign_in_request +from personal_agent_protocol.company import CompanyConfig, CompanyRequest, MemoryReplayCache +from personal_agent_protocol.company.points import CLIENT_POLICIES, COMPANY_AGENTS +from personal_agent_protocol.company.verify import RSA_KEY_BITS, verify_assertion, verify_delegation +from personal_agent_protocol.conformance import ConformanceContext, SignedIn, _prover +from personal_agent_protocol.crypto import JoseSigner, delegation_claims +from personal_agent_protocol.demo.conformance import MANZANITA_SCENARIO, ManzanitaConformance +from personal_agent_protocol.demo.kit import ScriptedBrowser, personal_agent_reactor +from personal_agent_protocol.demo.manzanita import CONFIG, manzanita +from personal_agent_protocol.device import verification_host_allowed +from personal_agent_protocol.errors import DiscoveryError, SessionError +from personal_agent_protocol.models import ( + Author, + ConversationEvent, + JsonWebKeySet, + Message, + OAuthServerMetadata, + Organization, + split_domain, +) +from personal_agent_protocol.reactor import first_contribution +from personal_agent_protocol.sessions import build_client_assertion_claims +from personal_agent_protocol.transport import SessionHttpClient + +from .test_company_end_to_end import TENANT, World +from .test_company_refusals import signed_in +from .test_conversations import Plugin +from .test_conversations import session as conversation_session +from .test_direct_and_api import begin, direct_world + +SHOP = "https://manzanita.example" +DOCUMENT: dict[str, Any] = { + "protocol_version": "1.0", + "organization": {"name": "Example", "domain": "example.com"}, + "agent": { + "protocols": [ + { + "type": "poppy", + "endpoint": "https://example.com/poppy/conversations", + "description": "Anything about your orders", + } + ] + }, +} + + +def _without_description(version: str) -> dict[str, Any]: + entry = {"type": "poppy", "endpoint": "https://example.com/poppy/conversations"} + return {**DOCUMENT, "protocol_version": version, "agent": {"protocols": [entry]}} + + +def _binding(monkeypatch: pytest.MonkeyPatch, **changes: object) -> ManzanitaConformance: + monkeypatch.setattr("personal_agent_protocol.demo.conformance.world_config", lambda _: changes) + return ManzanitaConformance("a-test-world") + + +async def _signed_in(ctx: ConformanceContext) -> SignedIn: + user = ctx.new_user() + return await ctx.sign_in(user, await ctx.session(user)) + + +class RecordingBrowser(ScriptedBrowser): + """The user's browser: opens the company's pages, and records every URL handed to it, + the agent's own pages unopened.""" + + def __init__(self, http: httpx.AsyncClient) -> None: + super().__init__(http) + self.urls: list[str] = [] + + async def open(self, authorization_url: SecretStr) -> None: + url = authorization_url.get_secret_value() + self.urls.append(url) + if url.startswith(SHOP): + await super().open(authorization_url) + + +def _recording_world(config: CompanyConfig | None = None) -> tuple[World, RecordingBrowser]: + world, _ = direct_world() + if config is not None: + world.shop, world.plugin = manzanita(world.network, world.clock, config=config) + browser = RecordingBrowser(world.http) + world.host.browser = browser + world.reactor = personal_agent_reactor( + world.host, network=world.network, http_client=world.http + ) + world.transport = SessionHttpClient(reactor=world.reactor, http_client=world.http) + return world, browser + + +def _direct_arguments(world: World, **more: Any) -> dict[str, Any]: + metadata = world.company.oauth_metadata + assert metadata is not None + return { + "authorization_endpoint": metadata.authorization_endpoint, + "token_endpoint": metadata.token_endpoint, + "issuer": metadata.issuer, + "client_id": world.atlas.client_id, + "redirect_uri": f"https://{world.atlas.domain}/oauth/callback", + "scopes": ("orders:read",), + "tenant_id": TENANT, + **more, + } + + +# Conversation protocol descriptions (§3.1, §8.1) ------------------------------------------ + + +def test_a_10_document_needs_a_description_for_each_conversation_protocol() -> None: + entry = DiscoveryDocument.model_validate(DOCUMENT).agent.protocols[0] # type: ignore[union-attr] + assert entry.description == "Anything about your orders" + with pytest.raises(ValueError, match="description"): + DiscoveryDocument.model_validate(_without_description("1.0")) + with pytest.raises(ValueError): + DiscoveryDocument.model_validate( + {**DOCUMENT, "agent": {"protocols": [{**_entry(), "description": ""}]}} + ) + # 0.4 doesn't define it: a 0.4 document without one is valid, as published. + published = DiscoveryDocument.model_validate(_without_description("0.4")) + assert published.agent.protocols[0].description is None # type: ignore[union-attr] + + +def _entry() -> dict[str, str]: + return {"type": "poppy", "endpoint": "https://example.com/poppy/conversations"} + + +def test_the_reference_company_describes_its_agent_at_10_and_not_at_04() -> None: + world = World() + document = world.shop.discovery_document() + (entry,) = document["agent"]["protocols"] + assert entry["description"] == CONFIG.agent_description + both = replace(CONFIG, protocol_versions=("1.0", "0.4")) + world.shop, world.plugin = manzanita(world.network, world.clock, config=both) + published = world.shop.discovery_document(version="0.4") + assert "description" not in published["agent"]["protocols"][0] + with pytest.raises(ValueError, match="agent_description"): + replace(CONFIG, agent_description=" ") + + +# Pushed Authorization Requests (§3.2, §4.2, §4.8) ---------------------------------------- + + +@pytest.mark.asyncio +async def test_a_company_offers_or_requires_par_and_the_agent_pushes() -> None: + world, browser = _recording_world(replace(CONFIG, pushed_authorization_requests="offered")) + await world.signed_out_session() + metadata = world.company.oauth_metadata + assert metadata is not None + assert metadata.pushed_authorization_request_endpoint == f"{SHOP}/oauth/par" + assert not metadata.require_pushed_authorization_requests + client = DirectSignInClient(reactor=world.reactor, http_client=world.http) + await client.begin( + **_direct_arguments( + world, + pushed_authorization_request_endpoint=metadata.pushed_authorization_request_endpoint, + ) + ) + # The browser gets only client_id and request_uri (RFC 9126 §4). + query = parse_qs(urlsplit(browser.urls[-1]).query) + assert set(query) == {"client_id", "request_uri"} + assert query["request_uri"][0].startswith("urn:ietf:params:oauth:request_uri:") + callback = await world.shop.approve_authorization(browser.request_id, account_id="acct_ada") # type: ignore[arg-type] + done = await client.complete(callback) + assert done.token.scopes == ("orders:read",) + # A request_uri is used once. + again = await world.http.get(browser.urls[-1]) + assert again.status_code == 400 + + +@pytest.mark.asyncio +async def test_a_company_that_requires_par_takes_nothing_else() -> None: + world, browser = _recording_world(replace(CONFIG, pushed_authorization_requests="required")) + await world.signed_out_session() + metadata = world.company.oauth_metadata + assert metadata is not None and metadata.require_pushed_authorization_requests + client = DirectSignInClient(reactor=world.reactor, http_client=world.http) + # Not pushed: the company's page refuses the request. + await client.begin(**_direct_arguments(world)) + assert "not valid" in browser.pages[-1] and 'name="request_id"' not in browser.pages[-1] + # A required push needs the endpoint, refused before anything is sent. + with pytest.raises(ValueError, match="PAR"): + await client.begin(**_direct_arguments(world, require_pushed_authorization_requests=True)) + with pytest.raises(ValueError): + OAuthServerMetadata.model_validate( + {**metadata.model_dump(), "pushed_authorization_request_endpoint": None} + ) + # Pushed, the sign-in completes. + await client.begin( + **_direct_arguments( + world, + pushed_authorization_request_endpoint=metadata.pushed_authorization_request_endpoint, + require_pushed_authorization_requests=True, + ) + ) + callback = await world.shop.approve_authorization(browser.request_id, account_id="acct_ada") # type: ignore[arg-type] + assert (await client.complete(callback)).token is not None + # A push is checked as an authorization request: an unknown redirect is refused. + form = { + "response_type": "code", + "client_id": world.atlas.client_id, + "redirect_uri": "https://elsewhere.example/cb", + "scope": "orders:read", + "code_challenge": "x" * 43, + "code_challenge_method": "S256", + **await client.sessions.client_authentication(client_id=world.atlas.client_id, issuer=SHOP), + } + refused = await world.http.post(f"{SHOP}/oauth/par", data=form) + assert (refused.status_code, refused.json()["error"]) == (400, "invalid_request") + with pytest.raises(ValueError, match="direct"): + replace(CONFIG, pushed_authorization_requests="offered", direct=False) + + +@pytest.mark.asyncio +async def test_a_link_opened_later_goes_to_the_agents_page_which_pushes_then() -> None: + world, browser = _recording_world(replace(CONFIG, pushed_authorization_requests="required")) + await world.signed_out_session() + metadata = world.company.oauth_metadata + assert metadata is not None + client = DirectSignInClient(reactor=world.reactor, http_client=world.http) + await client.begin( + **_direct_arguments( + world, + pushed_authorization_request_endpoint=metadata.pushed_authorization_request_endpoint, + require_pushed_authorization_requests=True, + cross_device=True, + link_page="https://atlas.example/sign-in/{link}", + ) + ) + # The handoff got the agent's own page: nothing was pushed yet. + link_url = browser.urls[-1] + assert link_url.startswith("https://atlas.example/sign-in/") + link = link_url.rsplit("/", 1)[1] + # Opened much later: the page pushes now, so the request_uri is fresh. + world.clock.advance(120) + authorization_url = await client.open_link(link) + assert "request_uri=" in authorization_url.get_secret_value() + await browser.open(authorization_url) + callback = await world.shop.approve_authorization(browser.request_id, account_id="acct_ada") # type: ignore[arg-type] + assert (await client.complete(callback)).token is not None + with pytest.raises(AuthorizationError): + await client.open_link(link) # the sign-in is done + with pytest.raises(AuthorizationError): + await client.open_link("unknown") + with pytest.raises(ValueError): + await client.begin(**_direct_arguments(world, link_page="https://atlas.example/no-link")) + + +@pytest.mark.asyncio +async def test_a_push_with_a_dpop_proof_binds_the_code_to_its_key( + monkeypatch: pytest.MonkeyPatch, +) -> None: + world = _binding(monkeypatch, dpop_binding="required", pushed_authorization_requests="required") + ctx = world.context() + metadata = await ctx.metadata() + assert metadata.require_pushed_authorization_requests + signed = await _signed_in(ctx) # the conformance agent pushes, with a proof + assert signed.token.token_type == "DPoP" + # Pushed with one key, exchanged with another: the code is bound to the first. + user = ctx.new_user() + session = await ctx.session(user) + client = DirectSignInClient(reactor=ctx.agent.reactor, http_client=ctx.http) + await client.begin( + authorization_endpoint=metadata.authorization_endpoint, # type: ignore[arg-type] + token_endpoint=metadata.token_endpoint, + issuer=metadata.issuer, + client_id=ctx.agent.identity.client_id, + redirect_uri=str(ctx.agent.identity.metadata["redirect_uris"][0]), + scopes=MANZANITA_SCENARIO.scopes, + tenant_id=ctx.tenant_id, + dpop_signing_algs=metadata.dpop_signing_alg_values_supported, + pairwise_user_id=session.sub, + pushed_authorization_request_endpoint=metadata.pushed_authorization_request_endpoint, + require_pushed_authorization_requests=True, + ) + callback = await ctx.driver.approve_authorization( + ctx.agent.user_browser.urls[-1], account=ctx.driver.accounts[0] + ) + await _prover(ctx).keys.forget(tenant_id=ctx.tenant_id, issuer=metadata.issuer, sub=session.sub) + with pytest.raises(AuthorizationError) as refused: + await client.complete(callback) + assert refused.value.code == "invalid_grant" + + +# Minor versions (§3.4) -------------------------------------------------------------------- + + +@pytest.mark.asyncio +async def test_nothing_of_10_goes_into_a_04_exchange() -> None: + """A 0.4 document has no description, and a 0.4 Session sends no `null` context.""" + + world = World() + world.shop, world.plugin = manzanita( + world.network, world.clock, config=replace(CONFIG, protocol_versions=("0.4",)) + ) + document = world.shop.discovery_document() + assert document["protocol_version"] == "0.4" + assert all("description" not in entry for entry in document["agent"]["protocols"]) + session = PapSession( + sid="sid_" + "a" * 22, + sub="u", + issuer=SHOP, + client_id="https://atlas.example/agent.json", + tenant_id=TENANT, + protocol_version="0.4", + ) + clearing = Message(author=Author(type="agent"), context={"locale": None}) + assert clears_context(clearing) + with pytest.raises(ProtocolValidationError) as refused: + ConversationClient._outgoing_message(clearing, session) + assert refused.value.code == "context_clear_unsupported" + later = replace(session, protocol_version="1.0") + assert ConversationClient._outgoing_message(clearing, later)["context"] == {"locale": None} + + +# PS384 required, RSA 2048 to 4096 bits (§4.1, §5.2, §10.7) -------------------------------- + + +def _rsa_jwks(key: rsa.RSAPrivateKey, kid: str) -> JsonWebKeySet: + public = json.loads(jwt.algorithms.RSAAlgorithm.to_jwk(key.public_key())) + return JsonWebKeySet.model_validate({"keys": [{**public, "kid": kid, "alg": "PS384"}]}) + + +async def _assertion(key: rsa.RSAPrivateKey, *, lifetime: int = 60) -> tuple[str, datetime]: + now = datetime(2026, 11, 17, 9, tzinfo=timezone.utc) + claims = build_client_assertion_claims( + client_id="https://atlas.example/agent.json", + issuer=SHOP, + now=now, + lifetime_seconds=min(lifetime, 300), + ) + payload = {**claims.model_dump(), "exp": claims.iat + lifetime} + signer = JoseSigner(key, algorithm="PS384", key_id="k") + return (await signer.sign(payload, purpose="client_assertion")).get_secret_value(), now + + +@pytest.mark.asyncio +@pytest.mark.parametrize("bits", [2048, 3072, 4096]) +async def test_companies_accept_ps384_assertions_and_delegations(bits: int) -> None: + key = rsa.generate_private_key(public_exponent=65537, key_size=bits) + compact, now = await _assertion(key) + claims = await verify_assertion( + compact, + keys=_rsa_jwks(key, "k"), + issuer="https://atlas.example/agent.json", + subject="https://atlas.example/agent.json", + audience=SHOP, + replay_cache=MemoryReplayCache(), + now=now, + ) + assert claims["aud"] == SHOP + delegated = ec.generate_private_key(ec.SECP256R1()) + public = json.loads(jwt.algorithms.ECAlgorithm.to_jwk(delegated.public_key())) + signer = JoseSigner(key, algorithm="PS384", key_id="k") + delegation = await signer.sign( + delegation_claims( + client_id="https://atlas.example/agent.json", + public=public, + issued_at=now, + lifetime=timedelta(hours=1), + ), + purpose="delegation", + ) + + async def resolve(_client: str, _kid: str | None) -> tuple[Any, JsonWebKeySet]: + return None, _rsa_jwks(key, "k") + + verified = await verify_delegation( + delegation.get_secret_value(), + client_id="https://atlas.example/agent.json", + resolve=resolve, + now=now, + ) + assert verified.client_id == "https://atlas.example/agent.json" + + +@pytest.mark.asyncio +@pytest.mark.filterwarnings("ignore::jwt.warnings.InsecureKeyLengthWarning") # the test signs +async def test_an_rsa_key_outside_2048_to_4096_bits_is_refused() -> None: + assert RSA_KEY_BITS == (2048, 4096) + weak = rsa.generate_private_key(public_exponent=65537, key_size=1024) # noqa: S505 - refused, as it should be + compact, now = await _assertion(weak) + with pytest.raises(SessionError) as refused: + await verify_assertion( + compact, + keys=_rsa_jwks(weak, "k"), + issuer="https://atlas.example/agent.json", + audience=SHOP, + replay_cache=MemoryReplayCache(), + now=now, + ) + assert refused.value.code == "invalid_client" + + +# Client assertion lifetime (§4.1) --------------------------------------------------------- + + +@pytest.mark.asyncio +async def test_an_assertion_lasts_at_most_five_minutes_and_one_that_does_is_accepted() -> None: + with pytest.raises(ValueError): + build_client_assertion_claims( + client_id="https://atlas.example/agent.json", issuer=SHOP, lifetime_seconds=301 + ) + key = rsa.generate_private_key(public_exponent=65537, key_size=2048) + for lifetime, accepted in ((300, True), (301, False)): + compact, now = await _assertion(key, lifetime=lifetime) + verify = verify_assertion( + compact, + keys=_rsa_jwks(key, "k"), + issuer="https://atlas.example/agent.json", + audience=SHOP, + replay_cache=MemoryReplayCache(), + now=now, + ) + if accepted: + await verify + else: + with pytest.raises(SessionError): + await verify + + +# Consent for scopes granted before (§4.2, §4.3, §10.8) ------------------------------------ + + +def test_a_direct_sign_in_asks_for_consent_unless_the_redirect_stays_on_the_device() -> None: + arguments = { + "authorization_endpoint": f"{SHOP}/oauth/authorize?prompt=none", + "issuer": SHOP, + "client_id": "https://atlas.example/agent.json", + "redirect_uri": "https://atlas.example/oauth/callback", + "scopes": ("orders:read",), + } + request = build_direct_sign_in_request(**arguments) # type: ignore[arg-type] + query = parse_qs(urlsplit(request.authorization_url.get_secret_value()).query) + assert query["prompt"] == [PROMPT_CONSENT] == ["consent"] + assert "resource" not in query # one sign-in for every resource (§4.5) + same_device = build_direct_sign_in_request(**arguments, prompt_consent=False) # type: ignore[arg-type] + assert "prompt" not in parse_qs( + urlsplit(same_device.authorization_url.get_secret_value()).query + ) + + +@pytest.mark.asyncio +async def test_the_consent_page_lists_every_scope_and_marks_the_earlier_ones() -> None: + world, browser = direct_world() + session = await world.signed_out_session() + client = await begin(world, browser, session, ("orders:read",)) + callback = await world.shop.approve_authorization(browser.request_id, account_id="acct_ada") # type: ignore[arg-type] + await client.complete(callback) + # Every scope again, the earlier one included: the page is shown all the same. + client = await begin(world, browser, session, ("orders:read", "orders:write")) + page = browser.pages[-1] + assert 'name="request_id"' in page and "See your orders" in page + summary = await world.shop.authorization_request(browser.request_id, account_id="acct_ada") # type: ignore[arg-type] + assert summary["prompt"] == "consent" + assert [(item["scope"], item["granted_before"]) for item in summary["scopes"]] == [ + ("orders:read", True), + ("orders:write", False), + ] + unmarked = await world.shop.authorization_request(browser.request_id) # type: ignore[arg-type] + assert all("granted_before" not in item for item in unmarked["scopes"]) + # Another account granted nothing. + other = await world.shop.authorization_request(browser.request_id, account_id="acct_bob") # type: ignore[arg-type] + assert not any(item["granted_before"] for item in other["scopes"]) + + +@pytest.mark.asyncio +async def test_every_device_sign_in_shows_its_page_with_the_earlier_scopes_marked() -> None: + world = World() + await signed_in(world, ("orders:read",)) + from personal_agent_protocol.device import DeviceSignInClient + + metadata = world.company.oauth_metadata + assert metadata is not None + started = await DeviceSignInClient(reactor=world.reactor, http_client=world.http).begin( + device_authorization_endpoint=metadata.device_authorization_endpoint, # type: ignore[arg-type] + token_endpoint=metadata.token_endpoint, + issuer=metadata.issuer, + client_id=world.atlas.client_id, + scopes=("orders:read", "orders:write"), + tenant_id=TENANT, + organization=world.company.document.organization, + ) + shown = await world.shop.device_request(started.user_code, account_id="acct_ada") + assert [(item["scope"], item["granted_before"]) for item in shown["scopes"]] == [ + ("orders:read", True), + ("orders:write", False), + ] + + +# Same DPoP key at refresh (§4.4, §4.5, §10.7) --------------------------------------------- + + +@pytest.mark.asyncio +async def test_a_bound_refresh_token_refreshes_only_with_its_key( + monkeypatch: pytest.MonkeyPatch, +) -> None: + with pytest.raises(ValueError, match="bind_refresh_tokens"): + replace(CONFIG, bind_refresh_tokens=True) + world = _binding(monkeypatch, dpop_binding="required", bind_refresh_tokens=True) + ctx = world.context() + signed = await _signed_in(ctx) + context = await ctx.account_context(signed.session.sub) + # The same key, twice: the rotated token stays bound to it. + for _ in range(2): + refreshed = await ctx.agent.accounts.refresh(signed.reference, context=context) + assert refreshed.status == "signed_in" and refreshed.rotated + metadata = await ctx.metadata() + await _prover(ctx).keys.forget( + tenant_id=ctx.tenant_id, issuer=metadata.issuer, sub=signed.session.sub + ) + # Another key: invalid_grant, so the copy is useless and the agent signs in again. + lost = await ctx.agent.accounts.refresh(signed.reference, context=context) + assert lost.status == "signed_out" + + +@pytest.mark.asyncio +async def test_without_binding_a_refresh_with_a_new_key_still_works( + monkeypatch: pytest.MonkeyPatch, +) -> None: + world = _binding(monkeypatch, dpop_binding="required") + ctx = world.context() + signed = await _signed_in(ctx) + metadata = await ctx.metadata() + await _prover(ctx).keys.forget( + tenant_id=ctx.tenant_id, issuer=metadata.issuer, sub=signed.session.sub + ) + context = await ctx.account_context(signed.session.sub) + assert (await ctx.agent.accounts.refresh(signed.reference, context=context)).status == ( + "signed_in" + ) + url = ctx.url(MANZANITA_SCENARIO.read_path) + assert url.startswith("https://") + + +# UCP scope requests name every scope (UCP 4, 11) ------------------------------------------ + + +@pytest.mark.asyncio +async def test_a_ucp_sign_in_requests_every_scope_and_gets_only_those() -> None: + held, needed = ("orders:write",), ("orders:read",) + fake = type("Profile", (), {"identity_linking_scopes": ("orders:read",)})() + assert ucp_scopes(fake, held, needed=needed) == ("orders:write", "orders:read") # type: ignore[arg-type] + assert ucp_scopes(fake, held) == ("orders:write", "orders:read") # type: ignore[arg-type] + # 0.4 kept UCP's incremental authorization: only the missing scopes. + assert ucp_scopes(fake, held, needed=needed, protocol_version="0.4") == ("orders:read",) # type: ignore[arg-type] + # The company grants only the scopes a sign-in names, whatever was granted before. + world = World() + await signed_in(world, ("orders:read", "orders:write")) + narrower = await signed_in(world, ("orders:read",)) + assert narrower.scopes == ("orders:read",) + + +# Ports in organization.domain (§3.1, §3.2) ------------------------------------------------ + + +def test_a_domain_names_its_port_when_that_isnt_443_from_10_only() -> None: + assert split_domain("shop.example:8443") == ("shop.example", 8443) + assert Organization(name="Shop", domain="Shop.Example:8443").domain == "shop.example:8443" + for invalid in ("shop.example:443", "shop.example:0", "shop.example:99999", "x.example:y"): + with pytest.raises(ValueError): + Organization(name="Shop", domain=invalid) + on_a_port = {**DOCUMENT, "organization": {"name": "Shop", "domain": "shop.example:8443"}} + assert DiscoveryDocument.model_validate(on_a_port).organization.domain == "shop.example:8443" + with pytest.raises(ValueError, match="port"): + DiscoveryDocument.model_validate({**on_a_port, "protocol_version": "0.4"}) + assert url_domain("https://shop.example:8443/x") == "shop.example:8443" + assert url_domain("https://shop.example:443/x") == "shop.example" + assert page_carries_session("https://shop.example:8443/page", "shop.example:8443") + assert not page_carries_session("https://shop.example/page", "shop.example:8443") + assert verification_host_allowed( + "https://shop.example/device", issuer="https://auth.example", domain="shop.example:8443" + ) + metadata = OAuthServerMetadata.model_validate( + { + "issuer": "https://shop.example:8443", + "token_endpoint": "https://shop.example:8443/oauth/token", + "revocation_endpoint": "https://shop.example:8443/oauth/revoke", + "grant_types_supported": ["refresh_token"], + "protected_resources": ["https://shop.example:8443"], + } + ) + assert metadata.lists_resource("shop.example:8443") + assert not metadata.lists_resource("shop.example") + # A company serves a domain with a port at 1.0 only. + replace(CONFIG, domain="manzanita.example:8443") + with pytest.raises(ValueError, match="port"): + replace(CONFIG, domain="manzanita.example:8443", protocol_versions=("1.0", "0.4")) + + +def _port_network(organization: str) -> httpx.AsyncClient: + base = "https://shop.example:8443" + answers = { + f"{base}/.well-known/poppy.json": { + **DOCUMENT, + "organization": {"name": "Shop", "domain": organization}, + "agent": { + "protocols": [{**_entry(), "endpoint": f"{base}/poppy", "description": "All"}] + }, + }, + f"{base}/.well-known/oauth-protected-resource": { + "resource": base, + "authorization_servers": [base], + }, + f"{base}/.well-known/oauth-authorization-server": { + "issuer": base, + "token_endpoint": f"{base}/oauth/token", + "revocation_endpoint": f"{base}/oauth/revoke", + "grant_types_supported": ["refresh_token"], + "protected_resources": [base], + }, + } + + async def handler(request: httpx.Request) -> httpx.Response: + body = answers.get(str(request.url)) + return httpx.Response(200 if body else 404, json=body or {"error": "not_found"}) + + return httpx.AsyncClient(transport=httpx.MockTransport(handler)) + + +async def _public(_: str) -> list[str]: + return ["93.184.216.34"] + + +@pytest.mark.asyncio +async def test_an_agent_uses_a_company_on_another_port_only_when_configured_to() -> None: + async with _port_network("shop.example:8443") as http: + with pytest.raises(DiscoveryError) as refused: + await DiscoveryClient(http_client=http, address_resolver=_public).discover( + "shop.example:8443" + ) + assert refused.value.code == "port_not_allowed" + client = DiscoveryClient(http_client=http, address_resolver=_public, allow_ports=True) + company = await client.discover("shop.example:8443") + assert company.document.organization.domain == "shop.example:8443" + # A document on shop.example:8443 speaks for shop.example:8443, not shop.example. + async with _port_network("shop.example") as http: + client = DiscoveryClient(http_client=http, address_resolver=_public, allow_ports=True) + with pytest.raises(DiscoveryError) as mismatch: + await client.discover("shop.example:8443") + assert mismatch.value.code == "organization_domain_mismatch" + + +# One sign-in for every resource (§4.5, §4.7, §4.8, §7) ------------------------------------ + + +@pytest.mark.asyncio +async def test_a_service_left_out_is_invalid_target_and_used_signed_out( + monkeypatch: pytest.MonkeyPatch, +) -> None: + world = World() + await signed_in(world) + context = world.account_context() + client = RefreshTokenClient(reactor=world.reactor, http_client=world.http) + mcp = f"{SHOP}/mcp" + # Signed in with no resource: a token for the MCP server, added or not. + result = await client.refresh(world.refresh_reference, context=context, resource=mcp) # type: ignore[arg-type] + assert result.status == "signed_in" and result.token is not None + assert result.token.resource == mcp + + # The client policy leaves the MCP server out for this agent (`allows_resource`). + policy = first_contribution(world.shop.reactor, CLIENT_POLICIES, "policy") + + async def allows_resource(client_id: str, resource: str) -> bool: + return resource != mcp + + monkeypatch.setattr(policy, "allows_resource", allows_resource, raising=False) + with pytest.raises(AuthorizationError) as refused: + await client.refresh(world.refresh_reference, context=context, resource=mcp) # type: ignore[arg-type] + assert refused.value.code == "invalid_target" + # The default token still comes; the agent uses the server signed out. + default = await client.refresh(world.refresh_reference, context=context) # type: ignore[arg-type] + assert default.status == "signed_in" + + +# Clearing context, room to extend conversations (§8.4, §8.6, §8.13) ----------------------- + + +def test_null_clears_a_context_field_as_if_never_shared() -> None: + messages = [ + Message(author=Author(type="agent"), context={"locale": "fr", "time_zone": "Europe/Paris"}), + Message(author=Author(type="agent"), context={"user_available": True}), + Message(author=Author(type="agent"), context={"locale": None}), + ] + assert effective_context(messages) == {"time_zone": "Europe/Paris", "user_available": True} + + +@pytest.mark.asyncio +async def test_the_company_agent_sees_the_context_cleared( + monkeypatch: pytest.MonkeyPatch, +) -> None: + world = World() + await signed_in(world) + seen: list[dict[str, Any]] = [] + agent = first_contribution(world.shop.reactor, COMPANY_AGENTS, "company agent") + original = agent.respond + + async def respond(turn: Any) -> Any: + seen.append(dict(turn.context)) + return await original(turn) + + monkeypatch.setattr(agent, "respond", respond) + endpoint = world.company.document.agent.protocols[0].endpoint # type: ignore[union-attr] + started = await world.conversations.start( + endpoint, + Message(author=Author(type="agent"), text="Hello", context={"locale": "fr"}), + session=world.session, # type: ignore[arg-type] + wait=5, + ) + await world.conversations.send( + endpoint, + started.conversation_id, + Message(author=Author(type="agent"), text="Again", context={"locale": None}), + session=world.session, # type: ignore[arg-type] + wait=5, + ) + assert seen == [{"locale": "fr"}, {}] + + +def test_unknown_roles_and_author_types_are_read_safely() -> None: + message = Message.model_validate( + {"author": {"type": "organization"}, "role": "system", "text": "Hi"} + ) + assert (message.role, message.author.type) == ("company", "agent") + + +@pytest.mark.asyncio +async def test_the_company_ignores_author_fields_on_the_agents_messages() -> None: + world = World() + session = await world.signed_out_session() + endpoint = world.company.document.agent.protocols[0].endpoint # type: ignore[union-attr] + body = { + "id": "req_" + "a" * 22, + "message": { + "author": {"type": "agent", "id": "pretend", "name": "Support", "image": f"{SHOP}/i"}, + "text": "Hello", + }, + } + transport = SessionHttpClient(reactor=world.reactor, http_client=world.http) + response = await transport.request( + "POST", + endpoint, + session=session, + headers={"Content-Type": "application/json"}, + content=json.dumps(body).encode(), + ) + assert response.status_code == 201 + page = await world.conversations.read_events( + endpoint, response.json()["conversation_id"], session=session + ) + first = page.events[0].message + assert first is not None and first.author.model_dump(exclude_none=True) == {"type": "agent"} + + +@pytest.mark.asyncio +async def test_a_stream_skips_event_names_it_doesnt_know() -> None: + lines = ( + 'event: working\ndata: {"working":true}\n\n' + 'event: future-thing\ndata: {"anything":1}\n\n' + "id: evt_1\ndata: " + + json.dumps( + { + "id": "evt_1", + "type": "state", + "created_at": "2026-11-17T09:00:00Z", + "handoff": "none", + "responder": "agent", + "closed": True, + } + ) + + "\n\n" + ) + + async def company(_: httpx.Request) -> httpx.Response: + return httpx.Response( + 200, headers={"content-type": "text/event-stream"}, content=lines.encode() + ) + + async with httpx.AsyncClient(transport=httpx.MockTransport(company)) as http: + reactor, _ = build_pap_reactor(http_client=http) + reactor.register_plugin(PluginManifest(name="stream-test", version="1"), Plugin()) + client = ConversationClient(transport=SessionHttpClient(reactor=reactor, http_client=http)) + items = [ + item + async for item in client.stream( + f"{SHOP}/poppy", "cnv_1", session=conversation_session() + ) + ] + reactor.stop() + assert [type(item).__name__ for item in items] == ["WorkingChanged", "ConversationEvent"] + + +def test_an_unknown_error_code_is_handled_by_its_http_status() -> None: + assert known_conversation_error("conversation_closed") == "conversation_closed" + assert known_conversation_error("stronger_sign_in_needed") == "conversation_request_failed" + assert "conversation_closed" in KNOWN_CONVERSATION_ERRORS + refused = ConversationClient._rejected( + httpx.Response(409, json={"error": "something_new"}), {"error": "something_new"} + ) + assert (refused.code, refused.status_code, refused.details) == ( + "conversation_request_failed", + 409, + {"error": "something_new"}, + ) + assert isinstance(refused, ConversationError) + + +# What working means, unknown sign-in errors (§8.7, §8.11) --------------------------------- + + +@pytest.mark.asyncio +async def test_working_is_false_once_the_reply_is_written() -> None: + world = World() + await signed_in(world) + endpoint = world.company.document.agent.protocols[0].endpoint # type: ignore[union-attr] + page = await world.conversations.start( + endpoint, + Message(author=Author(type="agent"), text="Exchange my jacket for a size L"), + session=world.session, # type: ignore[arg-type] + wait=5, + ) + # The reply proposes an exchange the User has yet to approve: not `working`. + assert getattr(page, "working", False) is False + + +def test_an_unknown_authorization_error_signs_in_again_for_its_scopes() -> None: + event = ConversationEvent.model_validate( + { + "id": "evt_1", + "type": "authorization", + "created_at": "2026-11-17T09:00:00Z", + "error": "stronger_sign_in", + "scope": "orders:read orders:write orders:read", + } + ) + assert event.error == "stronger_sign_in" + assert event.sign_in_scopes == ("orders:read", "orders:write") + + +# Mediated Sign-In retirement date --------------------------------------------------------- + + +def test_mediated_sign_in_is_retired_on_17_march_2027() -> None: + assert MEDIATED_RETIREMENT_DATE == "2027-03-17" + assert CompanyRequest is not None diff --git a/personal_agent_protocol/__tests__/test_reactor_points.py b/personal_agent_protocol/__tests__/test_reactor_points.py index c953255b..e419aa0c 100644 --- a/personal_agent_protocol/__tests__/test_reactor_points.py +++ b/personal_agent_protocol/__tests__/test_reactor_points.py @@ -89,6 +89,7 @@ def _reactor(entry: dict[str, Any]) -> PluginPlatform: name="Points", domain="points.example", scopes=("a:read",), + agent_description="Anything about your account", scope_descriptions={"a:read": "Read"}, operations=False, ) diff --git a/personal_agent_protocol/__tests__/test_schemas.py b/personal_agent_protocol/__tests__/test_schemas.py index 9ccd41de..c44b439b 100644 --- a/personal_agent_protocol/__tests__/test_schemas.py +++ b/personal_agent_protocol/__tests__/test_schemas.py @@ -98,7 +98,10 @@ def test_an_operations_fixture_is_valid_by_its_upstream_schema(fixture: str, sch [ case for case in load_fixture_cases(("protocol",)) - if case.check == "discovery_document" and case.kind == "positive" + if case.check == "discovery_document" + and case.kind == "positive" + # The schemas are 1.0's: a 0.4 document is checked by the SDK alone. + and not str(case.input.get("protocol_version", "")).startswith("0.") ], ids=lambda case: case.id, ) diff --git a/personal_agent_protocol/__tests__/test_security_review.py b/personal_agent_protocol/__tests__/test_security_review.py index 07a6d9b8..b7c48fad 100644 --- a/personal_agent_protocol/__tests__/test_security_review.py +++ b/personal_agent_protocol/__tests__/test_security_review.py @@ -227,6 +227,7 @@ def test_finding_5_operations_without_a_write_scope_is_a_configuration_error() - name="Shop", domain="shop.example", scopes=("orders:read",), + agent_description="Anything about your account", scope_descriptions={"orders:read": "See orders"}, ) with pytest.raises(ValueError, match="among scopes"): @@ -234,6 +235,7 @@ def test_finding_5_operations_without_a_write_scope_is_a_configuration_error() - name="Shop", domain="shop.example", scopes=("a:read",), + agent_description="Anything about your account", write_scopes=("a:write",), scope_descriptions={"a:read": "Read"}, ) @@ -241,6 +243,7 @@ def test_finding_5_operations_without_a_write_scope_is_a_configuration_error() - name="Shop", domain="shop.example", scopes=("orders:read",), + agent_description="Anything about your account", scope_descriptions={"orders:read": "See orders"}, operations=False, ) diff --git a/personal_agent_protocol/__tests__/test_ucp.py b/personal_agent_protocol/__tests__/test_ucp.py index c615ba6e..27e6e633 100644 --- a/personal_agent_protocol/__tests__/test_ucp.py +++ b/personal_agent_protocol/__tests__/test_ucp.py @@ -71,7 +71,10 @@ async def test_a_company_that_speaks_ucp_lists_it_and_serves_its_profile_on_its_ assert set(profile.identity_linking_scopes) <= set(metadata.scopes_supported or []) assert metadata.offers_direct assert "private_key_jwt" in world.shop.oauth_metadata()["token_endpoint_auth_methods_supported"] - assert ucp_scopes(profile, ("orders:read",)) == () + # From 1.0 a sign-in after insufficient_scope requests every scope still needed; 0.4 + # requested only the missing ones (UCP extension 4). + assert ucp_scopes(profile, ("orders:read",)) == ("orders:read",) + assert ucp_scopes(profile, ("orders:read",), protocol_version="0.4") == () # A company that doesn't speak UCP lists nothing, and its profile isn't fetched. world = World() world.shop, world.plugin = manzanita( diff --git a/personal_agent_protocol/__version__.py b/personal_agent_protocol/__version__.py index 05972e33..10af0c0c 100644 --- a/personal_agent_protocol/__version__.py +++ b/personal_agent_protocol/__version__.py @@ -7,4 +7,4 @@ """Personal Agent Protocol.""" -__version__ = "0.36.1" +__version__ = "0.37.0" diff --git a/personal_agent_protocol/accounts.py b/personal_agent_protocol/accounts.py index 4c6ef99e..6ce7efd8 100644 --- a/personal_agent_protocol/accounts.py +++ b/personal_agent_protocol/accounts.py @@ -388,6 +388,8 @@ class ServiceTokens: context: RefreshTokenContext scopes: tuple[str, ...] | None = None _tokens: dict[str | None, AccessToken] = field(default_factory=dict) + #: Services the Company answered `invalid_target` for (§4.5): used signed out. + _left_out: set[str] = field(default_factory=set) async def resource_for(self, service_url: str, *, fresh: bool = False) -> str | None: """The `resource` to request for `service_url`, or `None` for the default token.""" @@ -404,14 +406,24 @@ async def token_for(self, service_url: str, *, fresh: bool = False) -> AccessTok known = self._tokens.get(resource) if known is not None: return known - if metadata is not None and self._is_mcp(metadata.resource): - result = await self.refresh.token_for_mcp( - self.reference, context=self.context, server=metadata, scopes=self.scopes - ) - else: - result = await self.refresh.refresh( - self.reference, context=self.context, scopes=self.scopes, resource=resource - ) + if resource in self._left_out: + return None + try: + if metadata is not None and self._is_mcp(metadata.resource): + result = await self.refresh.token_for_mcp( + self.reference, context=self.context, server=metadata, scopes=self.scopes + ) + else: + result = await self.refresh.refresh( + self.reference, context=self.context, scopes=self.scopes, resource=resource + ) + except AuthorizationError as exc: + if exc.code != "invalid_target" or resource is None: + raise + # The Company leaves this service out for this agent (§4.5): it is used signed + # out, and not asked again until `forget`. + self._left_out.add(resource) + return None if result.status != "signed_in" or result.token is None: self._tokens.clear() return None @@ -425,6 +437,7 @@ def forget(self) -> None: """Drop every access token held: signed out, or a new sign-in replaces them.""" self._tokens.clear() + self._left_out.clear() __all__ = [ diff --git a/personal_agent_protocol/auth.py b/personal_agent_protocol/auth.py index 91bd375a..50af480e 100644 --- a/personal_agent_protocol/auth.py +++ b/personal_agent_protocol/auth.py @@ -21,7 +21,8 @@ from pydantic import SecretStr, field_validator from reactor import PluginPlatform # type: ignore[import-untyped] -from .errors import AuthorizationError +from .errors import AuthorizationError, ProtocolValidationError +from .json import loads_strict from .models import ProtocolModel, is_loopback_redirect from .reactor import ( AUTHORIZATION_STATE_STORES, @@ -33,7 +34,9 @@ Clock, RandomSource, first_contribution, + send_bounded, ) +from .refusals import refusal_code, refuse_redirect, refused_without_body from .sessions import ( SessionClient, SignInResult, @@ -53,7 +56,24 @@ "state", "code_challenge", "code_challenge_method", + "prompt", + "request_uri", } +#: The OpenID Connect `prompt` a Direct Sign-In request carries (OpenID Connect Core +#: §3.1.2.1, §4.2): the Company shows its consent page even when the account granted +#: every scope to the `client_id` before (§10.8). +PROMPT_CONSENT = "consent" + + +def _json(response: httpx.Response) -> object: + """A response's JSON body, or `None` when it has none that parses.""" + + if response.headers.get("content-type", "").split(";", 1)[0].strip() != "application/json": + return None + try: + return loads_strict(response.content) + except (ProtocolValidationError, UnicodeDecodeError, ValueError): + return None def _base64url(value: bytes) -> str: @@ -88,7 +108,12 @@ def _scopes(values: Iterable[str]) -> tuple[str, ...]: class DirectSignInRequest(ProtocolModel): - """Authorization request state that redacts its URL and PKCE values.""" + """Authorization request state that redacts its URL and PKCE values. + + `authorization_url` carries every parameter; `parameters`, the same parameters form + encoded, is what a Pushed Authorization Request sends (RFC 9126, §4.2), after which + the browser opens `pushed_authorization_url` with only `client_id` and `request_uri`. + """ authorization_url: SecretStr issuer: str @@ -97,6 +122,27 @@ class DirectSignInRequest(ProtocolModel): scopes: tuple[str, ...] state: SecretStr code_verifier: SecretStr + authorization_endpoint: str | None = None + parameters: SecretStr | None = None + + def pushed_authorization_url(self, request_uri: str) -> SecretStr: + """The authorization URL after a push (RFC 9126 §4): `client_id` and + `request_uri` only, on the authorization endpoint.""" + + if self.authorization_endpoint is None: + raise ValueError("this request has no authorization endpoint") + parsed = urlsplit(self.authorization_endpoint) + query = [ + item + for item in parse_qsl(parsed.query, keep_blank_values=True) + if item[0] not in _AUTHORIZATION_PARAMETERS + ] + query.extend([("client_id", self.client_id), ("request_uri", request_uri)]) + return SecretStr( + urlunsplit( + (parsed.scheme, parsed.netloc, parsed.path, urlencode(query, quote_via=quote), "") + ) + ) @field_validator("issuer", "client_id") @classmethod @@ -118,11 +164,17 @@ def build_direct_sign_in_request( redirect_uri: str, scopes: Iterable[str], random_bytes: RandomBytes = secrets.token_bytes, + prompt_consent: bool = True, ) -> DirectSignInRequest: """Build a user-browser authorization URL with random state and S256 PKCE (§4.2). Plain OAuth: the sign-in names no Session, and any of the User's Sessions uses - the tokens it returns (§5.4). + the tokens it returns (§5.4). It names no `resource` either: one sign-in covers + every service the Company offers, and each token request names one (§4.5). + + `prompt_consent` adds `prompt=consent` (§4.2, §10.8), which a request MUST carry + unless the Personal Agent receives the redirect only on the device that opened the + authorization URL; only then is it `False`. """ endpoint = _https_url(authorization_endpoint, "authorization endpoint") @@ -136,17 +188,18 @@ def build_direct_sign_in_request( for item in parse_qsl(parsed.query, keep_blank_values=True) if item[0] not in _AUTHORIZATION_PARAMETERS ] - query.extend( - [ - ("response_type", "code"), - ("client_id", _https_url(client_id, "client ID")), - ("redirect_uri", _redirect_url(redirect_uri, "redirect URI")), - ("scope", " ".join(validated_scopes)), - ("state", state), - ("code_challenge", challenge), - ("code_challenge_method", "S256"), - ] - ) + parameters = [ + ("response_type", "code"), + ("client_id", _https_url(client_id, "client ID")), + ("redirect_uri", _redirect_url(redirect_uri, "redirect URI")), + ("scope", " ".join(validated_scopes)), + ("state", state), + ("code_challenge", challenge), + ("code_challenge_method", "S256"), + ] + if prompt_consent: + parameters.append(("prompt", PROMPT_CONSENT)) + query.extend(parameters) authorization_url = urlunsplit( (parsed.scheme, parsed.netloc, parsed.path, urlencode(query, quote_via=quote), "") ) @@ -158,6 +211,8 @@ def build_direct_sign_in_request( scopes=validated_scopes, state=SecretStr(state), code_verifier=SecretStr(verifier), + authorization_endpoint=endpoint, + parameters=SecretStr(urlencode(parameters, quote_via=quote)), ) @@ -235,6 +290,16 @@ class _PendingDirectSignIn: expires_at: datetime dpop_signing_algs: Sequence[str] | None = None pairwise_user_id: str | None = None + #: Where the request is pushed (RFC 9126), when it is: each opening pushes it again. + pushed_authorization_request_endpoint: str | None = None + + +def _link_reference(link: str) -> str: + try: + encoded = link.encode("ascii") + except UnicodeEncodeError as exc: + raise AuthorizationError("invalid_or_expired_state", "sign-in link is invalid") from exc + return "direct-link:" + hashlib.sha256(encoded).hexdigest() def _state_reference(state: str) -> str: @@ -292,9 +357,28 @@ async def begin( dpop_signing_algs: Sequence[str] | None = None, pairwise_user_id: str | None = None, cross_device: bool = False, + same_device_redirect: bool = False, + pushed_authorization_request_endpoint: str | None = None, + require_pushed_authorization_requests: bool = False, + link_page: str | None = None, ) -> DirectSignInStart: """Store one-use state, then open the authorization URL for the user (§4.2). + The request carries `prompt=consent`, so the Company shows its consent page even + for scopes the account granted before (§4.2, §10.8), unless `same_device_redirect` + says the host receives the redirect only on the device that opened the URL (a + loopback `redirect_uri`, or its own app signed in as the User who started). + + `pushed_authorization_request_endpoint` and `require_pushed_authorization_requests` + are the issuer's (RFC 9126, §3.2): with an endpoint, the request is pushed there + with a client assertion, and a DPoP proof when tokens are bound, and the browser + opens the authorization endpoint with only `client_id` and `request_uri` (§4.2: a + SHOULD whenever it is listed, a MUST when required). A `request_uri` expires + quickly, so a link the User opens later SHOULD go to the agent's own page: + `link_page`, an HTTPS URL with `{link}`, is what the browser handoff then gets, and + that page calls `open_link(link)` when opened, which pushes the request and + returns the authorization URL to redirect to. + `dpop_signing_algs` is the issuer's `dpop_signing_alg_values_supported`: the code exchange sends a DPoP proof when it includes ES256 (§4.5), by the DPoP key of `pairwise_user_id`, the User ID the sign-in is for, which proving needs. @@ -318,6 +402,12 @@ async def begin( ) if not tenant_id or len(tenant_id) > 256: raise ValueError("tenant_id must contain between 1 and 256 characters") + if require_pushed_authorization_requests and pushed_authorization_request_endpoint is None: + raise ValueError("a Company that requires PAR lists where to push (RFC 9126 §5)") + if link_page is not None: + if "{link}" not in link_page: + raise ValueError("link_page is an HTTPS URL with {link}") + _https_url(link_page.replace("{link}", "x"), "link page") proves_with_dpop(dpop_signing_algs, pairwise_user_id) clock = cast(Clock, first_contribution(self.reactor, CLOCKS, "clock")) random_source = cast( @@ -343,6 +433,7 @@ async def begin( redirect_uri=redirect_uri, scopes=scopes, random_bytes=random_source.bytes, + prompt_consent=not same_device_redirect, ) expires_at = clock.now() + timedelta(seconds=lifetime_seconds) reference = _state_reference(request.state.get_secret_value()) @@ -353,12 +444,25 @@ async def begin( expires_at=expires_at, dpop_signing_algs=dpop_signing_algs, pairwise_user_id=pairwise_user_id, + pushed_authorization_request_endpoint=( + None + if pushed_authorization_request_endpoint is None + else _https_url(pushed_authorization_request_endpoint, "PAR endpoint") + ), ) await store.put(reference, pending, expires_at=expires_at) + link: str | None = None try: - await browser.open(request.authorization_url) + if link_page is not None: + link = _base64url(_entropy(16, random_source.bytes)) + await store.put(_link_reference(link), reference, expires_at=expires_at) + await browser.open(SecretStr(link_page.replace("{link}", link))) + else: + await browser.open(await self._authorization_url(pending)) except Exception: await store.take(reference) + if link is not None: + await store.take(_link_reference(link)) raise return DirectSignInStart( expires_at=expires_at, @@ -366,6 +470,106 @@ async def begin( cross_device=cross_device, ) + async def open_link(self, link: str) -> SecretStr: + """The authorization URL for a sign-in link the User opened on the agent's own + page (`begin(link_page=...)`, §4.2): the request pushed now when the Company takes + PAR, so its short-lived `request_uri` is fresh, else the full URL. The page + redirects the browser there. A link may be opened again until the sign-in + completes or expires; `AuthorizationError` for an unknown or expired one.""" + + store = cast( + AuthorizationStateStore, + first_contribution( + self.reactor, AUTHORIZATION_STATE_STORES, "authorization state store" + ), + ) + clock = cast(Clock, first_contribution(self.reactor, CLOCKS, "clock")) + link_reference = _link_reference(link) + reference = await store.take(link_reference) + pending = await store.take(reference) if isinstance(reference, str) else None + if not isinstance(pending, _PendingDirectSignIn) or clock.now() > pending.expires_at: + raise AuthorizationError( + "invalid_or_expired_state", "the sign-in link is unknown or has expired" + ) + await store.put(cast(str, reference), pending, expires_at=pending.expires_at) + await store.put(link_reference, cast(str, reference), expires_at=pending.expires_at) + return await self._authorization_url(pending) + + async def _authorization_url(self, pending: _PendingDirectSignIn) -> SecretStr: + """The URL the browser opens: after a push when the Company takes PAR (§4.2).""" + + if pending.pushed_authorization_request_endpoint is None: + return pending.request.authorization_url + return pending.request.pushed_authorization_url(await self._push(pending)) + + async def _push(self, pending: _PendingDirectSignIn) -> str: + """Push the request (RFC 9126 §2): its parameters, a fresh client assertion, and a + DPoP proof when tokens are bound, so the code is bound to the key (RFC 9449 + §10.1); a `use_dpop_nonce` refusal is retried once. The `request_uri`.""" + + request = pending.request + endpoint = cast(str, pending.pushed_authorization_request_endpoint) + proves = proves_with_dpop(pending.dpop_signing_algs, pending.pairwise_user_id) + nonce: str | None = None + while True: + form = dict(parse_qsl(cast(SecretStr, request.parameters).get_secret_value())) + form.update( + await self.sessions.client_authentication( + client_id=request.client_id, issuer=request.issuer + ) + ) + headers = {"Accept": "application/json"} + if proves: + proof = await self.sessions._proof( + endpoint, + pending.tenant_id, + request.issuer, + cast(str, pending.pairwise_user_id), + nonce, + ) + headers["DPoP"] = proof.get_secret_value() + try: + response = await send_bounded( + self.http, + self.http.build_request("POST", endpoint, data=form, headers=headers), + max_bytes=self.max_response_bytes, + ) + except httpx.HTTPError as exc: + raise AuthorizationError("request_failed", "Pushed authorization failed") from exc + refuse_redirect(response, AuthorizationError) + payload = None if refused_without_body(response) else _json(response) + given = response.headers.get("dpop-nonce") + if ( + proves + and nonce is None + and given is not None + and response.status_code == 400 + and isinstance(payload, dict) + and payload.get("error") == "use_dpop_nonce" + ): + nonce = given + continue + break + if response.status_code not in {200, 201}: + raise AuthorizationError( + refusal_code(response, payload, "http_error"), + "The company refused the pushed authorization request", + status_code=response.status_code, + ) + request_uri = payload.get("request_uri") if isinstance(payload, dict) else None + expires_in = payload.get("expires_in") if isinstance(payload, dict) else None + if ( + not isinstance(request_uri, str) + or not request_uri + or not isinstance(expires_in, int) + or isinstance(expires_in, bool) + or expires_in <= 0 + ): + raise AuthorizationError( + "invalid_par_response", "The pushed authorization response is malformed" + ) + return request_uri + @traced("pap.sign_in.direct.complete", before=sign_in_method("direct"), after=sign_in_result) async def complete( self, callback_url: str, *, completed_by: str | None = None diff --git a/personal_agent_protocol/browser_control.py b/personal_agent_protocol/browser_control.py index a8c6bfec..239ec7e8 100644 --- a/personal_agent_protocol/browser_control.py +++ b/personal_agent_protocol/browser_control.py @@ -32,7 +32,7 @@ from typing import Literal from .errors import PersonalAgentProtocolError -from .models import DiscoveryDocument +from .models import DiscoveryDocument, domain_host from .sessions import PapSession BROWSER_CONTROL_EXTENSION = "browser-control" @@ -266,7 +266,7 @@ def on_company_host(host: str, organization_domain: str) -> bool: """Whether `host` is `organization.domain` or one of its subdomains: the only pages that get `navigator.poppy` (Browser Control 6).""" - host, domain = host.lower().rstrip("."), organization_domain.lower().rstrip(".") + host, domain = host.lower().rstrip("."), domain_host(organization_domain) return host == domain or host.endswith(f".{domain}") diff --git a/personal_agent_protocol/cli_commands.py b/personal_agent_protocol/cli_commands.py index b084d838..eb3f6988 100644 --- a/personal_agent_protocol/cli_commands.py +++ b/personal_agent_protocol/cli_commands.py @@ -632,6 +632,9 @@ async def work(runtime: CliRuntime) -> dict[str, Any]: tenant_id=record.tenant_id, dpop_signing_algs=metadata.dpop_signing_alg_values_supported, pairwise_user_id=record.pairwise_user_id, + # Pushed whenever the issuer takes PAR (§4.2, RFC 9126). + pushed_authorization_request_endpoint=metadata.pushed_authorization_request_endpoint, + require_pushed_authorization_requests=metadata.require_pushed_authorization_requests, ) callback = runtime.input.read("Callback URL", secret=True) result = await client.complete(callback.get_secret_value()) diff --git a/personal_agent_protocol/company/__init__.py b/personal_agent_protocol/company/__init__.py index 407ba21a..ccad5ab4 100644 --- a/personal_agent_protocol/company/__init__.py +++ b/personal_agent_protocol/company/__init__.py @@ -182,7 +182,7 @@ def build_company( reactor.register_plugin( PluginManifest( name="personal-agent-protocol.company", - version="0.36.1", + version="0.37.0", contribution_points=[ COMPANY_STORES.id, COMPANY_ACCOUNTS.id, diff --git a/personal_agent_protocol/company/points.py b/personal_agent_protocol/company/points.py index 643c6ecd..aac98922 100644 --- a/personal_agent_protocol/company/points.py +++ b/personal_agent_protocol/company/points.py @@ -149,6 +149,9 @@ class Turn: #: The Company speaks first: the user accepted a `user_requested` invitation and the #: Direct Conversation has no message yet (§8.10). `text` and `data` are then None. opening: bool = False + #: The context the personal agent's messages in this conversation share (§8.4): each + #: field's latest value, and none for a field a message set to `null` (from 1.0). + context: Mapping[str, Any] = field(default_factory=dict) @dataclass(frozen=True) @@ -270,13 +273,20 @@ class ClientPolicy(Protocol): signed out, with `allows_sign_in(client_id, grant_type)` (§4.1): the grant's endpoint then answers `unauthorized_client`. Without the method, every agent the policy allows may sign in. + + A sign-in covers every resource the company offers personal agents (§4.5): with + `allows_resource(client_id, resource)` a policy may leave a service out, for every + agent or by `client_id`, and a token request for it is `invalid_target`. `resource` + is the service's (the MCP server's `url`, the conversation endpoint), never the + default token's. Without the method, every agent gets a token for every service. """ async def allows(self, client_id: str) -> bool: ... class AllowEveryAgent: - """The default policy: any agent with valid identity is welcome, and may sign in.""" + """The default policy: any agent with valid identity is welcome, may sign in, and gets + tokens for every service.""" async def allows(self, client_id: str) -> bool: return True @@ -284,6 +294,9 @@ async def allows(self, client_id: str) -> bool: async def allows_sign_in(self, client_id: str, grant_type: str) -> bool: return True + async def allows_resource(self, client_id: str, resource: str) -> bool: + return True + @runtime_checkable class RateLimit(Protocol): diff --git a/personal_agent_protocol/company/service.py b/personal_agent_protocol/company/service.py index a0e97496..4c6eca8a 100644 --- a/personal_agent_protocol/company/service.py +++ b/personal_agent_protocol/company/service.py @@ -122,9 +122,12 @@ Message, Operation, compatible_versions, + domain_host, + effective_context, operations_content, parse_version, redirect_uri_matches, + split_domain, ) from ..operations import ( ACTION_FAILED, @@ -222,6 +225,7 @@ MEDIATED, OPERATION, PROPOSAL, + PUSHED_REQUEST, REFRESH_TOKEN, REQUEST_ID, SESSION, @@ -246,6 +250,7 @@ PendingAuthorization, PendingDevice, PendingMediated, + PushedAuthorization, RequestReceipt, SignInAttempts, StoredConversation, @@ -374,6 +379,10 @@ class CompanyConfig: name: str domain: str scopes: tuple[str, ...] + #: What the Company Agent can help with, in plain language: the `description` of its + #: `agent.protocols` entry (§3.1, §8.1), which a 1.0 document requires. It may say the + #: agent can help with anything. + agent_description: str write_scopes: tuple[str, ...] = () #: Mediated Sign-In's `fields`: `(name, label, secret)`. None, it isn't offered. mediated_fields: tuple[tuple[str, str, bool], ...] = () @@ -414,6 +423,17 @@ class CompanyConfig: access_token_lifetime: timedelta = timedelta(hours=1) #: How long a sign-in's refresh tokens work (§4.4). refresh_token_lifetime: timedelta = timedelta(days=90) + #: Bind each refresh token to the DPoP key of the request that issued it, and the + #: tokens rotated from it (§4.4, a MAY from 1.0): a refresh whose proof is missing or + #: by another key is `invalid_grant`. Off by default; needs `dpop_binding`. + bind_refresh_tokens: bool = False + #: Pushed Authorization Requests for Direct Sign-In (RFC 9126, §4.2, a MAY from 1.0): + #: `offered` lists `pushed_authorization_request_endpoint` (`/oauth/par`), and + #: `required` also sets `require_pushed_authorization_requests`, so the authorization + #: endpoint takes only a `request_uri` the agent pushed. Off by default. + pushed_authorization_requests: Literal["off", "offered", "required"] = "off" + #: How long a pushed request's `request_uri` lasts (RFC 9126 §2.2: briefly). + pushed_request_lifetime: timedelta = timedelta(seconds=60) #: A refresh token used again after it was rotated ends its whole sign-in, as RFC 9700 #: §4.14.2 describes (guides, *Token lifetimes*): if a refresh token was copied, the grant #: ends as soon as both copies have been used. Off by default. @@ -538,6 +558,14 @@ def __post_init__(self) -> None: # noqa: C901 - one branch per protocol rule raise ValueError("protocol_versions lists each version the company serves once") for version in self.protocol_versions: parse_version(version) + if not self.agent_description.strip(): + # Every conversation protocol says what its agent helps with (§3.1, §8.1). + raise ValueError("agent_description says what the Company Agent can help with") + if split_domain(self.domain)[1] is not None and any( + parse_version(version)[0] < 1 for version in self.protocol_versions + ): + # A domain names its port when that isn't 443 from 1.0 only (§3.1). + raise ValueError("a domain with a port is served at 1.0 or later only") if any(version not in self.protocol_versions for version in self.deprecated_versions): raise ValueError("deprecated_versions are served versions") _check_positive( @@ -549,7 +577,14 @@ def __post_init__(self) -> None: # noqa: C901 - one branch per protocol rule dpop_nonce_lifetime=self.dpop_nonce_lifetime, dpop_proof_window=self.dpop_proof_window, operator_signature_window=self.operator_signature_window, + pushed_request_lifetime=self.pushed_request_lifetime, ) + if self.pushed_authorization_requests not in ("off", "offered", "required"): + raise ValueError("pushed_authorization_requests is off, offered or required") + if self.pushed_authorization_requests != "off" and not self.direct: + raise ValueError("pushed_authorization_requests are Direct Sign-In's: direct is on") + if self.bind_refresh_tokens and self.dpop_binding == "off": + raise ValueError("bind_refresh_tokens needs dpop_binding") if not self.oauth and ( self.mediated_fields or self.operations or self.aliases or self.dpop_binding != "off" ): @@ -580,7 +615,8 @@ def __post_init__(self) -> None: # noqa: C901 - one branch per protocol rule raise ValueError("consent_page must contain {request_id}") if self.device_page is not None: host = (urlsplit(self.device_page).hostname or "").lower() - if not (host == self.domain or host.endswith(f".{self.domain}")): + own = domain_host(self.domain) + if not (host == own or host.endswith(f".{own}")): # A personal agent shows the link only on the issuer's host or # `organization.domain`, or a subdomain of either (§4.3). The issuer is on # `domain`, and an agent that found the company at an alias knows only that @@ -663,6 +699,10 @@ def token_endpoint(self) -> str: def device_endpoint(self) -> str: return f"{self.base}/oauth/device" + @property + def pushed_authorization_request_endpoint(self) -> str: + return f"{self.base}/oauth/par" + @property def authorization_endpoint(self) -> str: return f"{self.base}/oauth/authorize" @@ -1012,10 +1052,23 @@ def _wait(request: CompanyRequest) -> int | None: def _incoming(value: object, request_id: str) -> Message: """A message as the personal agent sent it (§8.4): its ID is its request's, and a - `role` or `id` it set is ignored.""" + `role` or `id` it set is ignored, as are `author.id`, `name` and `image`, which only + Company messages have (a later version may define them here).""" message = Message.model_validate(value) - return message.model_copy(update={"role": None, "id": request_id}) + author = Author(type=message.author.type) + return message.model_copy(update={"role": None, "id": request_id, "author": author}) + + +def _shared_context(conversation: StoredConversation) -> dict[str, Any]: + """The context the personal agent's messages in a conversation share (§8.4).""" + + return effective_context( + Message.model_validate(event.payload["message"]) + for event in conversation.events + if event.payload.get("type") == "message" + and event.payload.get("message", {}).get("role") == "user" + ) def _request_id(body: Mapping[str, Any]) -> str: @@ -1355,6 +1408,12 @@ async def _dispatch(self, request: CompanyRequest) -> CompanyResponse: # noqa: return await self._token(request) if method == "GET" and path == "/oauth/authorize" and self.config.direct: return await self._authorize(request) + if ( + method == "POST" + and path == "/oauth/par" + and self.config.pushed_authorization_requests != "off" + ): + return await self._pushed_request(request) if method == "GET" and path == "/api/openapi.json" and self._api() is not None: return CompanyResponse(200, cast(CompanyApi, self._api()).openapi()) if path.startswith("/api/") and self._api() is not None: @@ -1534,10 +1593,16 @@ def discovery_document( # noqa: C901 - one branch per member """ config = self.config organization = config.organization_domain(domain) + protocol_version = version or config.preferred_version + poppy: dict[str, Any] = {"type": "poppy", "endpoint": config.conversations_endpoint} + if parse_version(protocol_version)[0] >= 1: + # 1.0 requires it (§3.1, §8.1); 0.4 doesn't define it, so its document leaves it + # out: each side sends only what the other's version defines (§3.4). + poppy["description"] = config.agent_description document: dict[str, Any] = { - "protocol_version": version or config.preferred_version, + "protocol_version": protocol_version, "organization": {"name": config.name, "domain": organization}, - "agent": {"protocols": [{"type": "poppy", "endpoint": config.conversations_endpoint}]}, + "agent": {"protocols": [poppy]}, } if version is None and len(config.protocol_versions) > 1: document["supported_versions"] = { @@ -1723,6 +1788,13 @@ def oauth_metadata(self) -> dict[str, Any]: grants.append(AUTHORIZATION_CODE_GRANT) metadata["authorization_endpoint"] = config.authorization_endpoint metadata["code_challenge_methods_supported"] = ["S256"] + if config.pushed_authorization_requests != "off": + # RFC 9126 §5 (§3.2, §4.2): where to push, and whether Direct Sign-In needs it. + metadata["pushed_authorization_request_endpoint"] = ( + config.pushed_authorization_request_endpoint + ) + if config.pushed_authorization_requests == "required": + metadata["require_pushed_authorization_requests"] = True if config.device: grants.append(DEVICE_CODE_GRANT) metadata["device_authorization_endpoint"] = config.device_endpoint @@ -1847,8 +1919,12 @@ async def _token(self, request: CompanyRequest) -> CompanyResponse: # unverified (§3.2). raise _RefusedError(400, "invalid_grant") client_id = await self._client(form) + resource = self._resource(form) + if resource is not None and not await self._resource_allowed(client_id, resource): + # A service the company leaves out, for every agent or this one (§4.5). + raise _RefusedError(400, "invalid_target") # Before any grant is used: a proof refused spends no code. - jkt = await self._token_binding(request, self._resource(form)) + jkt = await self._token_binding(request, resource) if grant == REFRESH_TOKEN_GRANT: return await self._refresh_grant(form, client_id, jkt) if grant == AUTHORIZATION_CODE_GRANT and self.config.direct: @@ -1929,11 +2005,21 @@ async def _give_dpop_nonce(self) -> str: async def _dpop_nonce_given(self, nonce: str | None) -> bool: return nonce is not None and await self.store.get(DPOP_NONCE, nonce) is not None + async def _resource_allowed(self, client_id: str, resource: str) -> bool: + """Whether the client policy offers this agent a token for this service (§4.5): + `allows_resource`, when the policy has it; every service otherwise.""" + + policy = first_contribution(self.reactor, CLIENT_POLICIES, "policy") + decide = getattr(policy, "allows_resource", None) + return True if decide is None else bool(await decide(client_id, resource)) + def _resource(self, form: Mapping[str, str]) -> str | None: """The `resource` a token is issued for (RFC 8707, §4.5): one this company serves. `https://{domain}` (or an alias's) is the default token's, `None`; the MCP - server's `url` gets a token for it alone; anything else is `invalid_target`. + server's `url` gets a token for it alone; anything else is `invalid_target`. A + sign-in names no resource and covers every one, those added after it too: each + token request, the one that completes the sign-in or a refresh, names one. """ resource = form.get("resource") @@ -1982,6 +2068,12 @@ async def _refresh_grant( raise _RefusedError(400, "invalid_grant") if await self._sign_in_ended(grant): raise _RefusedError(400, "invalid_grant") + if grant.dpop_jkt is not None and ( + jkt is None or not hmac.compare_digest(jkt, grant.dpop_jkt) + ): + # Bound to the key it was issued with (§4.4): a copied refresh token is useless + # with any other, and nothing is issued for it. + raise _RefusedError(400, "invalid_grant") requested = tuple(scope for scope in form.get("scope", "").split(" ") if scope) if requested and any(scope not in grant.scopes for scope in requested): raise _RefusedError(400, "invalid_scope") @@ -2106,13 +2198,17 @@ def approve(pending: PendingDevice) -> PendingDevice: raise KeyError("unknown or already approved user code") return changed[1].granted - async def device_request(self, user_code: str) -> dict[str, Any]: + async def device_request( + self, user_code: str, *, account_id: str | None = None + ) -> dict[str, Any]: """A pending Device Sign-In request, for the company's verification page to show; not consumed. Who asks (the agent's `client_name` and its `client_id` domain), with the `heading` and `caution` the page starts with (§10.8), and for what. Raises - `KeyError` for an unknown, expired, approved or denied code. + `KeyError` for an unknown, expired, approved or denied code. The page is shown for + every Device Sign-In and lists every scope, those the account granted before too + (§4.3, §10.8): with `account_id`, each says whether it did (`granted_before`). """ pointer = await self._read(USER_CODE, user_code, UserCode.from_json) @@ -2137,10 +2233,12 @@ async def device_request(self, user_code: str) -> dict[str, Any]: "client_domain": urlsplit(pending.client_id).hostname or "", "heading": connect_heading(metadata.client_name, self.config.name), "caution": connect_caution(metadata.client_name), - "scopes": [ - {"scope": scope, "description": self.config.describe(scope)} - for scope in pending.scopes - ], + "scopes": self._consent_scopes( + pending.scopes, + None + if account_id is None + else await self._granted_before(pending.client_id, account_id), + ), "expires_at": pending.expires_at.isoformat().replace("+00:00", "Z"), } @@ -2384,6 +2482,7 @@ async def _sign_in( expires_at=expires_at, family=family, signed_in_at=self._now(), + dpop_jkt=jkt if self.config.bind_refresh_tokens else None, ).to_json(), expires_at=expires_at, ) @@ -2434,9 +2533,9 @@ async def _issue( ) -> CompanyResponse: """A token response (§4.7): an access token, and the refresh token if any. - Bearer, or `DPoP` bound to the key `jkt` names; a refresh token is never bound - (RFC 9449 §5). `scope` follows RFC 6749: left out when it grants exactly the - scopes requested. + Bearer, or `DPoP` bound to the key `jkt` names. A refresh token is bound to that + key only with `bind_refresh_tokens` (§4.4), recorded with its grant. `scope` + follows RFC 6749: left out when it grants exactly the scopes requested. """ access_token = self._id("at") @@ -2506,10 +2605,101 @@ async def _sign_in_ended(self, grant: AccountGrant) -> bool: # Direct Sign-In (§4.5) ------------------------------------------------------------- - async def _authorize(self, request: CompanyRequest) -> CompanyResponse: - """The company's own sign-in and consent page for a personal agent's request.""" + async def _pushed_request(self, request: CompanyRequest) -> CompanyResponse: + """`POST /oauth/par` (RFC 9126, §4.2): an authorization request's parameters, pushed + with the agent's client assertion, and a DPoP proof when it sends them (RFC 9449 + §10.1). Checked as the authorization endpoint would check them; answered with a + one-use `request_uri` that lasts `pushed_request_lifetime`. + """ + + form = dict(parse_qsl(request.body.decode())) + if "request_uri" in form: + # A pushed request can't name another (RFC 9126 §2.1). + raise _RefusedError(400, "invalid_request") + client_id = await self._client(form) + jkt = ( + await self._dpop_proof(request, status=400) + if request.headers.get("dpop") and self.config.dpop_binding != "off" + else None + ) + resolver = cast( + ClientResolver, first_contribution(self.reactor, CLIENT_RESOLVERS, "client") + ) + metadata, _ = await resolver.resolve(client_id) + redirect_uri = form.get("redirect_uri", "") + if not any(redirect_uri_matches(entry, redirect_uri) for entry in metadata.redirect_uris): + raise _RefusedError(400, "invalid_request") + scopes = tuple(scope for scope in form.get("scope", "").split(" ") if scope) + if form.get("response_type") != "code": + raise _RefusedError(400, "unsupported_response_type") + if form.get("code_challenge_method") != "S256" or not form.get("code_challenge"): + raise _RefusedError(400, "invalid_request") + if not scopes or any(scope not in self.config.offered_scopes for scope in scopes): + raise _RefusedError(400, "invalid_scope") + if not await self._sign_in_allowed(client_id, AUTHORIZATION_CODE_GRANT): + raise _RefusedError(400, "unauthorized_client") + parameters = { + name: value + for name, value in form.items() + if name not in {"client_assertion", "client_assertion_type"} + } + request_uri = f"urn:ietf:params:oauth:request_uri:{self._id('par')}" + expires_at = self._now() + self.config.pushed_request_lifetime + await self.store.put( + PUSHED_REQUEST, + request_uri, + PushedAuthorization( + client_id=client_id, parameters=parameters, expires_at=expires_at, dpop_jkt=jkt + ).to_json(), + expires_at=expires_at, + ) + return CompanyResponse( + 201, + { + "request_uri": request_uri, + "expires_in": int(self.config.pushed_request_lifetime.total_seconds()), + }, + {"Cache-Control": "no-store"}, + ) + + async def _pushed_parameters( + self, query: Mapping[str, str] + ) -> tuple[dict[str, str], str | None] | None: + """The authorization request a `request_uri` names, taken once, and the DPoP key + that pushed it (RFC 9126 §4); `None` for an unknown, used or expired one, or one + another agent pushed. Every other query parameter but `client_id` is ignored.""" + + taken = await self.store.take(PUSHED_REQUEST, query.get("request_uri", "")) + pushed = None if taken is None else PushedAuthorization.from_json(taken) + if ( + pushed is None + or self._now() >= pushed.expires_at + or pushed.client_id != query.get("client_id") + ): + return None + return pushed.parameters, pushed.dpop_jkt + + async def _authorize( # noqa: C901 - the checks of §4.2, then the page + self, request: CompanyRequest + ) -> CompanyResponse: + """The company's own sign-in and consent page for a personal agent's request. + + With `pushed_authorization_requests`, a `request_uri` the agent pushed stands for + the request (RFC 9126 §4); `required` takes nothing else. The page lists every + scope the sign-in would grant and is shown for every request, `prompt=consent` or + not, even when the account granted every scope before (§4.2, §10.8). + """ query = dict(parse_qsl(urlsplit(request.url).query)) + pushed_by: str | None = None + if "request_uri" in query and self.config.pushed_authorization_requests != "off": + pushed = await self._pushed_parameters(query) + if pushed is None: + return self._page(400, "This sign-in request is not valid or has expired.") + query, pushed_by = pushed + elif self.config.pushed_authorization_requests == "required": + # Only a pushed request (RFC 9126 §5): nothing the browser carried is trusted. + return self._page(400, "This sign-in request is not valid.") client_id = query.get("client_id", "") redirect_uri = query.get("redirect_uri", "") if not client_id or not await self._allowed(client_id): @@ -2560,6 +2750,8 @@ async def _authorize(self, request: CompanyRequest) -> CompanyResponse: expires_at=expires_at, client_name=metadata.client_name, browser_binding=None if hosted is not None else _digest(browser), + prompt=query.get("prompt"), + dpop_jkt=pushed_by, ).to_json(), expires_at=expires_at, ) @@ -2628,18 +2820,31 @@ async def consent_decision(self, request: CompanyRequest) -> ConsentDecision: raise refused return ConsentDecision(request_id=request_id, allow=form["decision"] == "allow") - async def authorization_request(self, request_id: str) -> dict[str, Any]: + async def authorization_request( + self, request_id: str, *, account_id: str | None = None + ) -> dict[str, Any]: """A pending Direct Sign-In request, for a consent page to show; not consumed. Who asks (the agent's `client_name` and its `client_id` domain), for what - (each requested scope with its `custom_scopes` words), until when. No - `state`, PKCE challenge, or redirect: nothing that helps answer it. - Raises `KeyError` for an unknown, used, or expired request. + (each requested scope with its `custom_scopes` words), until when, and the + request's `prompt`. No `state`, PKCE challenge, or redirect: nothing that helps + answer it. Raises `KeyError` for an unknown, used, or expired request. + + The page lists every scope in `scopes`, the ones the account granted this agent + before too, and is shown even when it granted them all (§4.2, §10.8): every User + of an agent shares its `client_id`. With `account_id`, the person signed in on + the page, each scope says whether that account granted it to this `client_id` + before (`granted_before`), which the page MAY mark. """ pending = await self._read(AUTHORIZATION, request_id, PendingAuthorization.from_json) if pending is None or self._now() >= pending.expires_at: raise KeyError("unknown, used, or expired sign-in request") + before = ( + await self._granted_before(pending.client_id, account_id) + if account_id is not None + else None + ) return { "request_id": request_id, "client_name": pending.client_name, @@ -2647,13 +2852,43 @@ async def authorization_request(self, request_id: str) -> dict[str, Any]: # What the page starts with and says before the person goes on (§10.8). "heading": connect_heading(pending.client_name, self.config.name), "caution": connect_caution(pending.client_name), - "scopes": [ - {"scope": scope, "description": self.config.describe(scope)} - for scope in pending.scopes - ], + "scopes": self._consent_scopes(pending.scopes, before), + "prompt": pending.prompt, "expires_at": pending.expires_at.isoformat().replace("+00:00", "Z"), } + def _consent_scopes( + self, scopes: Sequence[str], before: frozenset[str] | None + ) -> list[dict[str, Any]]: + """Every scope a sign-in would grant, for its consent page (§10.8), each marked + `granted_before` when the account's earlier grants are known.""" + + return [ + { + "scope": scope, + "description": self.config.describe(scope), + **({} if before is None else {"granted_before": scope in before}), + } + for scope in scopes + ] + + async def _granted_before(self, client_id: str, account_id: str) -> frozenset[str]: + """The scopes the account's live sign-ins granted this `client_id` (§10.8).""" + + agent = await self._read( + ACCOUNT_AGENT, _composite(client_id, account_id), AccountAgent.from_json + ) + granted: set[str] = set() + for family_id in () if agent is None else agent.families: + family = await self._read(ACCOUNT_FAMILY, family_id, AccountFamily.from_json) + if family is None or family.revoked: + continue + for token in family.tokens: + grant = await self._read(REFRESH_TOKEN, token, AccountGrant.from_json) + if grant is not None and not grant.revoked and self._now() < grant.expires_at: + granted.update(grant.scopes) + return frozenset(granted) + async def approve_authorization( self, request_id: str, *, account_id: str, scopes: Sequence[str] | None = None ) -> str: @@ -2677,6 +2912,7 @@ async def approve_authorization( account_id=account_id, scopes=granted, expires_at=expires_at, + dpop_jkt=pending.dpop_jkt, ).to_json(), expires_at=expires_at, ) @@ -2716,6 +2952,11 @@ async def _code_grant( ) if not hmac.compare_digest(challenge.decode(), issued.code_challenge): raise _RefusedError(400, "invalid_grant") + if issued.dpop_jkt is not None and ( + jkt is None or not hmac.compare_digest(jkt, issued.dpop_jkt) + ): + # Pushed with a DPoP proof, the code is bound to its key (RFC 9449 §10.1). + raise _RefusedError(400, "invalid_grant") return await self._sign_in( client_id, issued.account_id, @@ -3825,6 +4066,7 @@ def accept(current: StoredConversation) -> StoredConversation: client_id=session.client_id, is_direct=conversation.parent_id is not None, supports_operations=negotiated, + context=_shared_context(conversation), ) ) for reply in replies: diff --git a/personal_agent_protocol/company/store.py b/personal_agent_protocol/company/store.py index 6aa9364f..8a756c62 100644 --- a/personal_agent_protocol/company/store.py +++ b/personal_agent_protocol/company/store.py @@ -45,6 +45,9 @@ DEVICE = "device" USER_CODE = "user_code" AUTHORIZATION = "authorization" +#: A Pushed Authorization Request by its `request_uri` (RFC 9126, §4.2): the parameters a +#: personal agent pushed with its client assertion, used once, briefly. +PUSHED_REQUEST = "pushed_request" CODE = "code" MEDIATED = "mediated" CONVERSATION = "conversation" @@ -80,6 +83,7 @@ DEVICE, USER_CODE, AUTHORIZATION, + PUSHED_REQUEST, CODE, MEDIATED, CONVERSATION, @@ -372,6 +376,10 @@ class AccountGrant: #: sign-in from before the account's sign-ins all ended (a password reset) #: ends. Unknown (`None`) is taken for before any such moment. signed_in_at: datetime | None = None + #: With `bind_refresh_tokens`, the thumbprint of the DPoP key of the request that + #: issued it, carried by every token rotated from it: a refresh proves with that + #: key, or is `invalid_grant` (§4.4). `None`: not bound. + dpop_jkt: str | None = None def to_json(self) -> JsonObject: return { @@ -382,6 +390,7 @@ def to_json(self) -> JsonObject: "revoked": self.revoked, "family": self.family, "signed_in_at": _maybe_time(self.signed_in_at), + "dpop_jkt": self.dpop_jkt, } @classmethod @@ -394,6 +403,7 @@ def from_json(cls, value: JsonObject) -> AccountGrant: revoked=value["revoked"], family=value["family"], signed_in_at=_maybe_parse(value.get("signed_in_at")), + dpop_jkt=value.get("dpop_jkt"), ) @@ -506,20 +516,6 @@ def from_json(cls, value: JsonObject) -> PendingDevice: ) -@dataclass(frozen=True) -class UserCode: - """The device sign-in a user code stands for (by device-code digest).""" - - device: str - - def to_json(self) -> JsonObject: - return {"device": self.device} - - @classmethod - def from_json(cls, value: JsonObject) -> UserCode: - return cls(device=value["device"]) - - @dataclass(frozen=True) class PendingAuthorization: """A Direct Sign-In request waiting on the user's decision on the company's page.""" @@ -537,6 +533,12 @@ class PendingAuthorization: #: The scopes the agent asked for, when `scopes` grants fewer (§4.7): the token #: response then says which were granted. requested: tuple[str, ...] | None = None + #: The request's `prompt` (OpenID Connect Core §3.1.2.1, §4.2): `consent` asks for the + #: consent page even when the account granted every scope before. + prompt: str | None = None + #: The thumbprint of the DPoP key that pushed the request (RFC 9449 §10.1): the code is + #: exchanged only with a proof by that key. + dpop_jkt: str | None = None def to_json(self) -> JsonObject: return { @@ -549,6 +551,8 @@ def to_json(self) -> JsonObject: "client_name": self.client_name, "browser_binding": self.browser_binding, "requested": None if self.requested is None else list(self.requested), + "prompt": self.prompt, + "dpop_jkt": self.dpop_jkt, } @classmethod @@ -563,9 +567,54 @@ def from_json(cls, value: JsonObject) -> PendingAuthorization: client_name=value["client_name"], browser_binding=value["browser_binding"], requested=None if value.get("requested") is None else tuple(value["requested"]), + prompt=value.get("prompt"), + dpop_jkt=value.get("dpop_jkt"), + ) + + +@dataclass(frozen=True) +class PushedAuthorization: + """A Pushed Authorization Request (RFC 9126, §4.2): the authorization request's + parameters, the agent whose client assertion pushed them, and the DPoP key that + proved the push, if any. Used once, by the authorization endpoint.""" + + client_id: str + parameters: dict[str, str] + expires_at: datetime + dpop_jkt: str | None = None + + def to_json(self) -> JsonObject: + return { + "client_id": self.client_id, + "parameters": dict(self.parameters), + "expires_at": _time(self.expires_at), + "dpop_jkt": self.dpop_jkt, + } + + @classmethod + def from_json(cls, value: JsonObject) -> PushedAuthorization: + return cls( + client_id=value["client_id"], + parameters=dict(value["parameters"]), + expires_at=_parse(value["expires_at"]), + dpop_jkt=value.get("dpop_jkt"), ) +@dataclass(frozen=True) +class UserCode: + """The device sign-in a user code stands for (by device-code digest).""" + + device: str + + def to_json(self) -> JsonObject: + return {"device": self.device} + + @classmethod + def from_json(cls, value: JsonObject) -> UserCode: + return cls(device=value["device"]) + + @dataclass(frozen=True) class IssuedCode: """A one-use authorization code, at most a minute old.""" @@ -577,6 +626,8 @@ class IssuedCode: account_id: str scopes: tuple[str, ...] expires_at: datetime + #: The DPoP key that pushed the request (RFC 9449 §10.1): the exchange proves with it. + dpop_jkt: str | None = None def to_json(self) -> JsonObject: return { @@ -587,6 +638,7 @@ def to_json(self) -> JsonObject: "account_id": self.account_id, "scopes": list(self.scopes), "expires_at": _time(self.expires_at), + "dpop_jkt": self.dpop_jkt, } @classmethod @@ -599,6 +651,7 @@ def from_json(cls, value: JsonObject) -> IssuedCode: account_id=value["account_id"], scopes=tuple(value["scopes"]), expires_at=_parse(value["expires_at"]), + dpop_jkt=value.get("dpop_jkt"), ) @@ -1133,6 +1186,7 @@ def from_json(cls, value: JsonObject) -> IdempotencyRecord: DEVICE: PendingDevice.from_json, USER_CODE: UserCode.from_json, AUTHORIZATION: PendingAuthorization.from_json, + PUSHED_REQUEST: PushedAuthorization.from_json, CODE: IssuedCode.from_json, MEDIATED: PendingMediated.from_json, CONVERSATION: StoredConversation.from_json, diff --git a/personal_agent_protocol/company/testing.py b/personal_agent_protocol/company/testing.py index c6ed6bb2..3f81be06 100644 --- a/personal_agent_protocol/company/testing.py +++ b/personal_agent_protocol/company/testing.py @@ -58,6 +58,7 @@ async def test_my_replay_cache_conforms() -> None: MEDIATED, OPERATION, PROPOSAL, + PUSHED_REQUEST, RECORD_KINDS, RECORD_TYPES, REFRESH_TOKEN, @@ -84,6 +85,7 @@ async def test_my_replay_cache_conforms() -> None: PendingAuthorization, PendingDevice, PendingMediated, + PushedAuthorization, ReplayMark, RequestReceipt, SignInAttempts, @@ -164,16 +166,30 @@ def record_samples(now: datetime) -> dict[str, Any]: ended=True, ), ACCESS_TOKEN: access, - REFRESH_TOKEN: AccountGrant("acct_1", "c", ("a", "b"), later, True, "fam_1", now), + REFRESH_TOKEN: AccountGrant("acct_1", "c", ("a", "b"), later, True, "fam_1", now, "jkt"), ACCOUNT_FAMILY: AccountFamily("c", "acct_1", ("t1", "t2"), ("a1",), True), ACCOUNT_AGENT: AccountAgent(("fam_1", "fam_2")), CLIENT: KnownClient(), DEVICE: PendingDevice("c", ("a",), "ABCD-EFGH", later, 10, now, "acct_1", ("a",), True), USER_CODE: UserCode("dev_digest"), AUTHORIZATION: PendingAuthorization( - "c", "https://atlas.example/cb", ("a",), "st", "chal", later, "Atlas", "bind" + "c", + "https://atlas.example/cb", + ("a",), + "st", + "chal", + later, + "Atlas", + "bind", + prompt="consent", + dpop_jkt="jkt", + ), + PUSHED_REQUEST: PushedAuthorization( + "c", {"response_type": "code", "scope": "a"}, later, dpop_jkt="jkt" + ), + CODE: IssuedCode( + "c", "https://atlas.example/cb", "chal", ("a",), "acct_1", ("a",), later, "jkt" ), - CODE: IssuedCode("c", "https://atlas.example/cb", "chal", ("a",), "acct_1", ("a",), later), MEDIATED: PendingMediated( "c", "acct_1", ("a",), "ref", later, "a•••@example.com", ("k1", "k2"), 2, "failed" ), diff --git a/personal_agent_protocol/company/verify.py b/personal_agent_protocol/company/verify.py index a53d90ce..97d0148a 100644 --- a/personal_agent_protocol/company/verify.py +++ b/personal_agent_protocol/company/verify.py @@ -6,6 +6,7 @@ from __future__ import annotations +import base64 import hashlib import hmac import json @@ -36,8 +37,12 @@ from ..models import ClientMetadata, JsonWebKeySet from .points import ReplayCache -#: Companies accept client assertions and delegations signed with these (§4.1, §5.2). +#: Companies accept client assertions and delegations signed with these (§4.1, §5.2): both +#: are required from 1.0. _ALGORITHMS = ("ES256", "PS384") +#: The RSA key sizes accepted for `PS384`, in bits (guides, *Signing and verifying JWTs*): +#: 2048 to 4096. A smaller key is weak, a larger one costly to verify. +RSA_KEY_BITS = (2048, 4096) #: An assertion lives at most this long: `exp` at most five minutes after `iat` (§4.1). #: The SDKs' own assertions live 60 seconds. _MAX_LIFETIME = timedelta(seconds=300) @@ -128,9 +133,10 @@ def _decode( continue if key.alg is not None and key.alg != algorithm: continue - public = jwt.PyJWK.from_dict( - json.loads(key.model_dump_json(exclude_none=True)), algorithm=algorithm - ).key + jwk_value = json.loads(key.model_dump_json(exclude_none=True)) + if not _key_size_accepted(jwk_value): + continue + public = jwt.PyJWK.from_dict(jwk_value, algorithm=algorithm).key try: return jwt.decode( compact, @@ -151,6 +157,21 @@ def _decode( return None +def _key_size_accepted(jwk_value: dict[str, Any]) -> bool: + """Whether a verifying key's size is accepted, read from the JWK before it is loaded: + an RSA key of 2048 to 4096 bits (`RSA_KEY_BITS`); an EC key's curve is `ES256`'s.""" + + if jwk_value.get("kty") != "RSA": + return True + modulus = str(jwk_value.get("n", "")) + try: + bits = int.from_bytes(base64.urlsafe_b64decode(modulus + "=" * (-len(modulus) % 4))) + except (ValueError, TypeError): + return False + low, high = RSA_KEY_BITS + return low <= bits.bit_length() <= high + + def _status(error: str) -> int: return 401 if error == "invalid_client" else 400 @@ -265,9 +286,10 @@ async def verify_delegation( # noqa: C901 - the four steps of §5.2, in order if key is None or (key.alg is not None and key.alg != algorithm): raise _refused("No key of the agent's jwks_uri signed the delegation") try: - public = jwt.PyJWK.from_dict( - json.loads(key.model_dump_json(exclude_none=True)), algorithm=algorithm - ).key + jwk_value = json.loads(key.model_dump_json(exclude_none=True)) + if not _key_size_accepted(jwk_value): + raise ValueError("an RSA key is 2048 to 4096 bits") + public = jwt.PyJWK.from_dict(jwk_value, algorithm=algorithm).key claims = jwt.decode( compact, public, diff --git a/personal_agent_protocol/conformance.py b/personal_agent_protocol/conformance.py index 41bb4e32..b65ba328 100644 --- a/personal_agent_protocol/conformance.py +++ b/personal_agent_protocol/conformance.py @@ -41,7 +41,7 @@ from dataclasses import dataclass, field from datetime import datetime, timedelta, timezone from typing import Any, Literal, Protocol, cast, runtime_checkable -from urllib.parse import urlencode, urlsplit +from urllib.parse import parse_qsl, urlencode, urlsplit from xml.etree import ElementTree import httpx @@ -57,7 +57,7 @@ stale_resource_metadata, ) from .apis import ApiClient, ApiError, conversation_endpoint, openapi_url -from .auth import DirectSignInClient +from .auth import DirectSignInClient, build_direct_sign_in_request from .browser import BrowserSessionClient from .conversations import ConversationClient, TextDelta from .crypto import ( @@ -93,6 +93,7 @@ TasksResponse, implemented_protocol_versions, operations_content, + parse_version, ) from .operations import ( APPROVAL_HEADER, @@ -607,6 +608,9 @@ async def _direct_sign_in( tenant_id=self.tenant_id, dpop_signing_algs=metadata.dpop_signing_alg_values_supported, pairwise_user_id=session.sub, + # Pushed whenever the issuer takes PAR, as 1.0 asks (§4.2, RFC 9126). + pushed_authorization_request_endpoint=metadata.pushed_authorization_request_endpoint, + require_pushed_authorization_requests=metadata.require_pushed_authorization_requests, ) callback = await self.driver.approve_authorization( actor.user_browser.urls[-1], @@ -2814,6 +2818,27 @@ async def _version_unserved(ctx: ConformanceContext, _: FixtureCase) -> None: expect_refusal(response, 400, "version_unsupported", "an unserved Poppy-Version") +@case("protocol.agent-protocols-described") +async def _agent_protocols_described(ctx: ConformanceContext, _: FixtureCase) -> None: + """At 1.0 each conversation protocol says what its agent helps with (§3.1, §8.1).""" + + company = await ctx.company() + if parse_version(company.document.protocol_version)[0] < 1: + raise SkipCase("0.4 defines no description") + raw = (await ctx.send("GET", company.discovery_url)).json() + entries = (raw.get("agent") or {}).get("protocols") or [] + if not entries: + raise SkipCase("the company lists no conversation protocol") + for entry in entries: + description = entry.get("description") + check(isinstance(description, str) and description, "every entry has a description") + for version, url in (raw.get("supported_versions") or {}).items(): + if parse_version(version)[0] < 1: + document = (await ctx.send("GET", url)).json() + for entry in (document.get("agent") or {}).get("protocols") or []: + check("description" not in entry, f"{version}: nothing 1.0 adds (§3.4)") + + @case("protocol.supported-versions-published") async def _supported_versions_published(ctx: ConformanceContext, _: FixtureCase) -> None: """Each version `poppy.json` lists is served as §3.4 says; nothing to check when none is.""" @@ -3680,6 +3705,61 @@ async def _dpop_key_lost(ctx: ConformanceContext, _: FixtureCase) -> None: _proof_refused(stale, "the token of the lost key") +@case("dpop.refresh-bound-to-its-key") +async def _dpop_refresh_bound(ctx: ConformanceContext, _: FixtureCase) -> None: + """The agent refreshes with the key it signed in with (§4.4); a company that binds + refresh tokens refuses another key, rotated tokens included.""" + + signed, url = await _bound(ctx) + context = await ctx.account_context(signed.session.sub) + for turn in ("first", "second"): + refreshed = await ctx.agent.accounts.refresh(signed.reference, context=context) + check(refreshed.status == "signed_in", f"the {turn} refresh with the same key works") + token = cast(AccessToken, refreshed.token) + answer = await ctx.agent.transport.request("GET", url, session=signed.session, token=token) + check(answer.status_code == 200, f"its token works, got {answer.status_code}") + metadata = await ctx.metadata() + await _prover(ctx).keys.forget( + tenant_id=ctx.tenant_id, issuer=metadata.issuer, sub=signed.session.sub + ) + lost = await ctx.agent.accounts.refresh(signed.reference, context=context) + check(lost.status == "signed_out", "a refresh with another key is invalid_grant") + again = await ctx.sign_in(signed.session.sub, signed.session) + check(again.token.token_type == "DPoP", "and the agent signs in again") # noqa: S105 + + +@case("dpop.pushed-authorization-request") +async def _dpop_pushed(ctx: ConformanceContext, _: FixtureCase) -> None: + """Pushed Authorization Requests, required (§3.2, §4.2, RFC 9126).""" + + metadata = await ctx.metadata() + if metadata.pushed_authorization_request_endpoint is None: + raise SkipCase("the company takes no Pushed Authorization Requests") + check(metadata.offers_direct, "PAR is for Direct Sign-In") + if not metadata.require_pushed_authorization_requests: + raise SkipCase("the company offers PAR without requiring it") + if "direct_sign_in" not in ctx.driver.capabilities: + raise SkipCase("the driver can't play the user on the company's consent page") + await _signed_in_user(ctx) # pushed, as the SDK does when it's offered + opened = urlsplit(ctx.agent.user_browser.urls[-1]) + names = {name for name, _ in parse_qsl(opened.query)} + check(names == {"client_id", "request_uri"}, f"only client_id and request_uri, got {names}") + request = build_direct_sign_in_request( + authorization_endpoint=cast(str, metadata.authorization_endpoint), + issuer=metadata.issuer, + client_id=ctx.agent.identity.client_id, + redirect_uri=str(ctx.agent.identity.metadata["redirect_uris"][0]), + scopes=ctx.scenario.scopes, + ) + unpushed = await ctx.send("GET", request.authorization_url.get_secret_value()) + location = unpushed.headers.get("location", "") + check( + unpushed.status_code >= 400 or "code=" not in location, + f"a request that wasn't pushed is refused, got {unpushed.status_code}", + ) + check("request_id" not in unpushed.text, "no consent page for it") + + @case("dpop.conversation-and-stream") async def _dpop_conversation(ctx: ConformanceContext, _: FixtureCase) -> None: signed, _url = await _bound(ctx) @@ -3995,7 +4075,16 @@ async def _no_fallback_issuer(ctx: ConformanceContext, fixture: FixtureCase) -> async def _sign_in_without_issuer(ctx: ConformanceContext, fixture: FixtureCase) -> None: served = (await ctx.company()).document.model_dump(mode="json", exclude_none=True) endpoint = await ctx.conversations_endpoint() - agent = {"protocols": [{"type": "poppy", "endpoint": endpoint, "access": "signed_in"}]} + agent = { + "protocols": [ + { + "type": "poppy", + "endpoint": endpoint, + "description": "Anything about your account", + "access": "signed_in", + } + ] + } inner = ctx.http._transport for offers in ( {"auth": {"issuer": ctx.base_url}}, diff --git a/personal_agent_protocol/conversations.py b/personal_agent_protocol/conversations.py index 2fd93cb0..088d1657 100644 --- a/personal_agent_protocol/conversations.py +++ b/personal_agent_protocol/conversations.py @@ -19,7 +19,14 @@ from .errors import ConversationError, ProtocolValidationError from .json import loads_strict -from .models import ConversationEvent, ConversationEventPage, Message, ProtocolModel +from .models import ( + ConversationEvent, + ConversationEventPage, + Message, + ProtocolModel, + clears_context, + parse_version, +) from .reactor import RANDOM_SOURCES, RandomSource, first_contribution from .refusals import refusal_code, refusal_details from .sessions import AccessToken, PapSession @@ -121,7 +128,7 @@ async def start( body: dict[str, object] = {"id": self._request_id(request_id, message)} if message is not None: - body["message"] = self._outgoing_message(message) + body["message"] = self._outgoing_message(message, session) if parent_conversation_id is not None: self._identifier(parent_conversation_id, "parent conversation ID") body["parent_conversation_id"] = parent_conversation_id @@ -175,7 +182,7 @@ async def send( url, { "id": self._request_id(request_id, message), - "message": self._outgoing_message(message), + "message": self._outgoing_message(message, session), }, expected_status=202, session=session, @@ -471,10 +478,13 @@ async def stream( # noqa: C901 - one SSE reader with its reconnect rules httpx.Response(200, content=await response.aread()) ) code = payload.get("error") if isinstance(payload, dict) else None + sent = code if isinstance(code, str) else "" + known = known_conversation_error(sent) raise ConversationError( - code if isinstance(code, str) else "conversation_request_failed", + known, "conversation stream was rejected", status_code=response.status_code, + details={"error": sent} if sent and sent != known else None, ) if content_type != "text/event-stream": raise ConversationError( @@ -492,6 +502,9 @@ async def stream( # noqa: C901 - one SSE reader with its reconnect rules "invalid_response", "working event was malformed" ) from exc continue + if name not in _STREAM_EVENT_NAMES: + # A name a later version or an extension adds (§8.6): skipped. + continue if name == "text-delta": try: delta = TextDelta.model_validate(loads_strict(data)) @@ -592,8 +605,11 @@ def _rejected(response: httpx.Response, payload: object) -> ConversationError: started_in = payload.get("protocol_version") if isinstance(started_in, str) and re.fullmatch(r"[0-9]+\.[0-9]+", started_in): details["protocol_version"] = started_in + known = known_conversation_error(code) + if known != code: + details["error"] = code return ConversationError( - code if isinstance(code, str) else "conversation_request_failed", + known, "conversation request was rejected", status_code=response.status_code, details=details or None, @@ -659,11 +675,21 @@ def _parse_page( ) from exc @staticmethod - def _outgoing_message(message: Message) -> dict[str, object]: - """The message as sent: no `id` (the request's is top-level) and no `role` (§8.4).""" + def _outgoing_message(message: Message, session: PapSession) -> dict[str, object]: + """The message as sent: no `id` (the request's is top-level) and no `role` (§8.4). + + A `context` field set to `null` clears it from 1.0 (§8.4): a Session at 0.4 doesn't + send one, since each side sends only what the other's version defines (§3.4). + """ if message.role is not None: raise ProtocolValidationError("invalid_message", "outgoing messages cannot set role") + if clears_context(message) and parse_version(session.protocol_version)[0] < 1: + raise ProtocolValidationError( + "context_clear_unsupported", + "clearing a context field with null is version 1.0's: this Session is at " + f"{session.protocol_version}", + ) return message.model_dump(mode="json", exclude_none=True, exclude={"id"}) @staticmethod @@ -689,6 +715,47 @@ def _query(cls, value: str, *, cursor: str | None, wait: int | None) -> str: return urlunsplit((*parsed[:3], urlencode(query), "")) +#: The SSE event names this version defines (§8.6): `message`, the default, for recorded +#: events, `working` and `text-delta`. A Personal Agent skips any other. +_STREAM_EVENT_NAMES = frozenset({"message", "working", "text-delta"}) +#: The conversation error codes this version defines (§7, §8.13, §5.6, §3.3): a code +#: outside them is handled by the response's HTTP status, as an error with no code is. +KNOWN_CONVERSATION_ERRORS = frozenset( + { + "conversation_not_found", + "conversation_closed", + "direct_conversation_open", + "request_id_conflict", + "invalid_cursor", + "cursor_expired", + "invalid_request", + "extension_required", + "version_mismatch", + "version_unsupported", + "invalid_session", + "session_ended", + "invalid_token", + "insufficient_scope", + "invalid_dpop_proof", + "use_dpop_nonce", + "rate_limited", + "temporarily_unavailable", + # The Operations extension's (Operations 6), for a Session that declares it. + "approval_declined", + "action_failed", + } +) + + +def known_conversation_error(code: str, default: str = "conversation_request_failed") -> str: + """`code` when this version defines it, else `default`: an error a later version or an + extension adds is handled by the response's HTTP status (§8.13, RFC 9110 §15), as + an error with no code is. The `ConversationError` keeps the status, and the code as + sent in `details["error"]`.""" + + return code if code in KNOWN_CONVERSATION_ERRORS else default + + async def _sse_frames( lines: AsyncIterator[str], max_event_bytes: int ) -> AsyncIterator[tuple[str, str, str | None]]: diff --git a/personal_agent_protocol/demo/ledgerly.py b/personal_agent_protocol/demo/ledgerly.py index 487e2944..6a4e8cd7 100644 --- a/personal_agent_protocol/demo/ledgerly.py +++ b/personal_agent_protocol/demo/ledgerly.py @@ -94,6 +94,7 @@ def decline_agent_payments(request: DeclineRequest) -> Decline | None: name="Ledgerly", domain=DOMAIN, scopes=("books:read", "payments:write"), + agent_description="Your books: invoices, bills, and payments", write_scopes=("payments:write",), scope_descriptions={ "books:read": "See your books: invoices, bills and payments", diff --git a/personal_agent_protocol/demo/manzanita.py b/personal_agent_protocol/demo/manzanita.py index 128fe46a..5313ec9b 100644 --- a/personal_agent_protocol/demo/manzanita.py +++ b/personal_agent_protocol/demo/manzanita.py @@ -132,6 +132,7 @@ def decline_agent_returns(request: DeclineRequest) -> Decline | None: name="Manzanita Outfitters", domain=DOMAIN, scopes=("orders:read", "orders:write"), + agent_description="Anything about your orders, returns, and our outdoor gear", write_scopes=("orders:write",), mediated_fields=(("email", "Email", False), ("password", "Password", True)), links=True, diff --git a/personal_agent_protocol/demo/northwind.py b/personal_agent_protocol/demo/northwind.py index 8d2293e8..171b54f7 100644 --- a/personal_agent_protocol/demo/northwind.py +++ b/personal_agent_protocol/demo/northwind.py @@ -48,6 +48,7 @@ name="Northwind Bank", domain=DOMAIN, scopes=("accounts:read", "payments:write"), + agent_description="Your accounts, balances, and payments", write_scopes=("payments:write",), mediated_fields=(("account_number", "Account number", False), ("pin", "PIN", True)), mediated_scopes=("accounts:read",), diff --git a/personal_agent_protocol/device.py b/personal_agent_protocol/device.py index 3599e316..1b0188b5 100644 --- a/personal_agent_protocol/device.py +++ b/personal_agent_protocol/device.py @@ -19,7 +19,7 @@ from .auth import _https_url, _scopes from .errors import AuthorizationError, ProtocolValidationError from .json import loads_strict -from .models import Organization, ProtocolModel +from .models import Organization, ProtocolModel, domain_host from .reactor import ( AUTHORIZATION_STATE_STORES, CLOCKS, @@ -82,7 +82,8 @@ def verification_host_allowed(url: str, *, issuer: str, domain: str) -> bool: """ host = _host(url) - allowed = [_host(issuer), domain.lower().rstrip(".")] + # The host of `organization.domain`, without the port it names from 1.0 (§3.1). + allowed = [_host(issuer), domain_host(domain)] return bool(host) and any(name and _within(host, name) for name in allowed) diff --git a/personal_agent_protocol/discovery.py b/personal_agent_protocol/discovery.py index 8cd30a33..a7aa60a8 100644 --- a/personal_agent_protocol/discovery.py +++ b/personal_agent_protocol/discovery.py @@ -27,6 +27,8 @@ choose_protocol_version, implemented_protocol_versions, protected_resource_metadata_url, + split_domain, + url_domain, ) from .reactor import ( DISCOVERY_TRANSPORTS, @@ -72,11 +74,17 @@ def __init__( timeout: float = 5.0, cache_bounds: CacheBounds | None = None, protocol_versions: Iterable[str] | None = None, + allow_ports: bool = False, ) -> None: """`protocol_versions` are the protocol versions this Personal Agent implements - (§3.4): `SUPPORTED_PROTOCOL_VERSIONS`, the 1.0 draft, by default. Name - `PROTOCOL_PROFILE` among them to use Companies that serve only 0.4 as published, - such as `("0.4", "1.0")`; the newest compatible version a Company serves is chosen.""" + (§3.4): `SUPPORTED_PROTOCOL_VERSIONS`, 1.0, by default. Name `PROTOCOL_PROFILE` + among them to use Companies that serve only 0.4 as published, such as + `("0.4", "1.0")`; the newest compatible version a Company serves is chosen. + + `allow_ports` uses a Company on a port other than 443, such as + `shop.example:8443` for testing: from 1.0 its `organization.domain` includes the + port (§3.1). Off by default: a Personal Agent uses such a Company only when + configured to on purpose.""" if timeout <= 0: raise ValueError("timeout must be positive") @@ -96,6 +104,7 @@ def __init__( self._timeout = timeout self._cache = MetadataCache(reactor, cache_bounds) self.protocol_versions = implemented_protocol_versions(protocol_versions) + self.allow_ports = allow_ports async def __aenter__(self) -> DiscoveryClient: return self @@ -147,7 +156,13 @@ async def discover( # noqa: C901 - the checks of §3, §3.2 and §3.4, in order # The document speaks for the host that served it, after redirects, compared # ignoring case and nothing else (§3, §3.1). - served_by = (final_url.host or "").lower().rstrip(".") + served_by = url_domain(str(final_url)) or "" + if split_domain(served_by)[1] is not None and not self.allow_ports: + # A Company on another port is used only when configured on purpose (§3.1). + raise DiscoveryError( + "port_not_allowed", + "The company is served on a port other than 443: allow_ports uses it", + ) if document.organization.domain != served_by: raise DiscoveryError( "organization_domain_mismatch", @@ -362,12 +377,20 @@ async def service_metadata( ) return metadata - @staticmethod - def _normalize_domain(domain: str) -> str: - value = domain.rstrip(".").lower() + def _normalize_domain(self, domain: str) -> str: + value = domain.lower() if "://" in value or "/" in value or not value: raise DiscoveryError("invalid_domain", "Discovery requires a DNS domain name") - return value + try: + host, port = split_domain(value) + except ValueError as exc: + raise DiscoveryError("invalid_domain", "Discovery requires a DNS domain name") from exc + if port is not None and not self.allow_ports: + raise DiscoveryError( + "port_not_allowed", "A domain with a port is used only with allow_ports (§3.1)" + ) + host = host.rstrip(".") + return host if port is None else f"{host}:{port}" async def _get_json( self, url: str, *, follow_redirects: bool = True diff --git a/personal_agent_protocol/mediated.py b/personal_agent_protocol/mediated.py index e2201111..e7b1435f 100644 --- a/personal_agent_protocol/mediated.py +++ b/personal_agent_protocol/mediated.py @@ -22,7 +22,8 @@ Errors are OAuth errors from the token endpoint, raised as `AuthorizationError`: `invalid_grant`, `expired_token`, `access_denied`, `invalid_scope`, and a rate limit (`rate_limited`, HTTP 429 with `Retry-After`). Mediated Sign-In is -transitional: prefer Direct or Device Sign-In when the company offers them. +transitional: prefer Direct or Device Sign-In when the company offers them. The +protocol plans to retire it on March 17, 2027 (`MEDIATED_RETIREMENT_DATE`). """ from __future__ import annotations @@ -70,6 +71,9 @@ from .telemetry import sign_in_result, signed_in_as, traced MEDIATED_VERSION = "1" +#: The day the protocol plans to retire the Mediated Sign-In extension (Mediated Sign-In +#: 1, from 1.0; guides, *Mediated sign-in*): after it, Direct and Device Sign-In remain. +MEDIATED_RETIREMENT_DATE = "2027-03-17" _SIGN_IN_ID = re.compile(r"^[A-Za-z0-9_-]{1,256}$") diff --git a/personal_agent_protocol/models.py b/personal_agent_protocol/models.py index 968059b9..8f81cdc2 100644 --- a/personal_agent_protocol/models.py +++ b/personal_agent_protocol/models.py @@ -32,9 +32,9 @@ _VERSION = re.compile(r"^(?P0|[1-9][0-9]*)\.(?P0|[1-9][0-9]*)$") #: The protocol versions a Personal Agent implements unless it asks for others (§3.4): a #: Company's document is used at a version compatible with one of them, the same major -#: and, before 1.0, the same minor. The 1.0 draft only (`DEFAULT_PROTOCOL_VERSION`). +#: and, before 1.0, the same minor. 1.0 only (`DEFAULT_PROTOCOL_VERSION`). SUPPORTED_PROTOCOL_VERSIONS = frozenset({DEFAULT_PROTOCOL_VERSION}) -#: Every protocol version this SDK implements: 0.4 as published and the 1.0 draft. A +#: Every protocol version this SDK implements: 0.4 and 1.0, both as published. A #: Personal Agent (`DiscoveryClient(protocol_versions=...)`) or a Company #: (`CompanyConfig.protocol_versions`) uses 0.4 only when it names it. AVAILABLE_PROTOCOL_VERSIONS = frozenset({PROTOCOL_PROFILE, DRAFT_PROTOCOL_VERSION}) @@ -200,10 +200,51 @@ def redirect_uri_matches(registered: str, given: str) -> bool: def _domain(value: str) -> str: - normalized = value.rstrip(".").lower() - if not _DOMAIN.fullmatch(normalized): - raise ValueError("must be a DNS domain name") - return normalized + normalized = value.lower() + host, port = split_domain(normalized) + host = host.rstrip(".") + if not _DOMAIN.fullmatch(host): + raise ValueError("must be a DNS domain name, with its port when that isn't 443") + return host if port is None else f"{host}:{port}" + + +def split_domain(domain: str) -> tuple[str, int | None]: + """`organization.domain` as its host and its port, `None` for 443 (§3.1). + + From 1.0 a domain includes its port when that isn't 443, such as + `shop.example:8443`; `ValueError` for a port that isn't a number from 1 to 65535, + or `:443`, which a domain never names.""" + + host, colon, port = domain.rpartition(":") + if not colon: + return domain, None + if not port.isdigit() or port.startswith("0") or not 0 < int(port) <= 65535: + raise ValueError("a domain's port is a number from 1 to 65535") + if int(port) == 443: + raise ValueError("a domain names its port only when that isn't 443") + return host, int(port) + + +def domain_host(domain: str) -> str: + """The host of `organization.domain`, without the port it names (§3.1).""" + + return split_domain(domain)[0].rstrip(".").lower() + + +def url_domain(url: str) -> str | None: + """The domain an HTTPS URL is on, as `organization.domain` names it (§3.1): its host, + lowercase, with its port when that isn't 443. `None` for another scheme, user + information or an invalid port.""" + + parsed = urlsplit(url) + try: + port = parsed.port + except ValueError: + return None + if parsed.scheme != "https" or not parsed.hostname or parsed.username or parsed.password: + return None + host = parsed.hostname.lower().rstrip(".") + return host if port in {None, 443} else f"{host}:{port}" class ProtocolModel(BaseModel): @@ -371,13 +412,18 @@ def validate_hint_names(cls, value: dict[str, ScopeHint]) -> dict[str, ScopeHint class AgentProtocol(ProtocolModel): - """A conversation protocol the Company Agent speaks (§3.1, §8). + """A conversation protocol the Company Agent speaks (§3.1, §8.1). + `description` says, in plain language, what the agent at `endpoint` can help with, + so the Personal Agent can decide whether a conversation serves the task at hand and + choose between the entries and the Company's APIs. Required from 1.0: a 1.0 document + whose entry has none is invalid (`DiscoveryDocument`); 0.4 doesn't define it. `access` is kept as written, whatever it says; read `account_access`. """ type: str = Field(min_length=1) endpoint: str + description: str | None = Field(default=None, min_length=1) access: str | None = None @property @@ -533,6 +579,19 @@ def validate_interfaces(self) -> DiscoveryDocument: raise ValueError("web.disabled needs agent or apis") return self + @model_validator(mode="after") + def validate_version_fields(self) -> DiscoveryDocument: + # What 1.0 adds to the document, checked by the version the document follows. + major = parse_version(self.protocol_version)[0] + if major >= 1 and self.agent is not None: + if any(entry.description is None for entry in self.agent.protocols): + # Every conversation protocol says what its agent helps with (§3.1, §8.1). + raise ValueError("each agent.protocols entry needs a description") + if major < 1 and split_domain(self.organization.domain)[1] is not None: + # A port in organization.domain is 1.0's (§3.1); 0.4 names a host only. + raise ValueError("organization.domain names a port only from version 1.0") + return self + @model_validator(mode="after") def validate_version_used(self, info: ValidationInfo) -> DiscoveryDocument: # A document is used only at a version compatible with one the Personal Agent @@ -651,7 +710,10 @@ class OAuthServerMetadata(ProtocolModel): protected_resources: list[str] = Field(min_length=1) authorization_endpoint: str | None = None device_authorization_endpoint: str | None = None + #: Where Direct Sign-In's request is pushed (RFC 9126, §3.2, §4.2): a Personal Agent + #: SHOULD push whenever it is listed, and MUST when `require_pushed_authorization_requests`. pushed_authorization_request_endpoint: str | None = None + require_pushed_authorization_requests: bool = False scopes_supported: list[str] | None = None dpop_signing_alg_values_supported: list[str] | None = None @@ -678,6 +740,14 @@ def validate_sign_in_endpoints(self) -> OAuthServerMetadata: raise ValueError("authorization_code needs authorization_endpoint") if self.offers_device and self.device_authorization_endpoint is None: raise ValueError("the device grant needs device_authorization_endpoint") + if ( + self.require_pushed_authorization_requests + and self.pushed_authorization_request_endpoint is None + ): + # A Company that requires PAR lists where to push (RFC 9126 §5). + raise ValueError( + "require_pushed_authorization_requests needs pushed_authorization_request_endpoint" + ) return self @property @@ -695,8 +765,9 @@ def offers_device(self) -> bool: def lists_resource(self, domain: str) -> bool: """Whether `protected_resources` names `https://{domain}` (§3.2). - Exactly, except that the host compares ignoring case: an entry with a path, a - port or a trailing slash does not match. + Exactly, except that the host compares ignoring case: an entry with a path or a + trailing slash does not match, nor one whose port isn't the domain's. From 1.0 a + domain includes its port when that isn't 443, and so does its entry (§3.1, §3.2). """ wanted = domain.lower().rstrip(".") @@ -704,7 +775,7 @@ def lists_resource(self, domain: str) -> bool: if not entry.startswith("https://"): continue host = entry[len("https://") :] - if host and not any(char in host for char in "/?#:@") and host.lower() == wanted: + if host and not any(char in host for char in "/?#@") and host.lower() == wanted: return True return False @@ -1051,6 +1122,25 @@ def operations_content( return {"operations": content.model_dump(mode="json", exclude_none=True)} +#: The `author.type` values and message roles this version defines (§8.4). +AUTHOR_TYPES = ("agent", "human") +MESSAGE_ROLES = ("user", "company") + + +def known_author_type(value: object) -> object: + """An `author.type` this SDK doesn't recognize reads as `agent` (§8.4): a message is a + person's own words only when it says so.""" + + return value if not isinstance(value, str) or value in AUTHOR_TYPES else "agent" + + +def known_role(value: object) -> object: + """A `role` this SDK doesn't recognize reads as `company` (§8.4): content from the + Company, never the User's (§10.1).""" + + return value if not isinstance(value, str) or value in MESSAGE_ROLES else "company" + + class Author(ProtocolModel): """Who wrote a message (§7.4): `agent` or `human`, and for a Company message, who. @@ -1063,6 +1153,10 @@ class Author(ProtocolModel): name: str | None = Field(default=None, min_length=1) image: str | None = None + _type = field_validator("type", mode="before")( + classmethod(lambda cls, value: known_author_type(value)) + ) + @field_validator("id") @classmethod def validate_id(cls, value: str | None) -> str | None: @@ -1088,6 +1182,10 @@ class Message(ProtocolModel): id: str | None = None author: Author role: Literal["user", "company"] | None = None + + _role = field_validator("role", mode="before")( + classmethod(lambda cls, value: known_role(value)) + ) #: What the writer had seen (§8.4), hints neither side depends on: on a Company Agent #: message, the ID of the latest request it took into account; on a message the #: Personal Agent wrote, the last cursor it had read. A person's message carries neither. @@ -1205,6 +1303,28 @@ def validate_content(self) -> Message: return self +def effective_context(messages: Iterable[Message]) -> dict[str, Any]: + """The context the Personal Agent's messages share, in order (§8.4): fields a message + leaves out keep their previous values, and a field set to `null` is cleared, as if + it had never been shared (from 1.0).""" + + shared: dict[str, Any] = {} + for message in messages: + for name, value in (message.context or {}).items(): + if value is None: + shared.pop(name, None) + else: + shared[name] = value + return shared + + +def clears_context(message: Message) -> bool: + """Whether a message sets a `context` field to `null` to clear it (§8.4): 1.0's, so a + Personal Agent sends it only in a Session at 1.0 or later (§3.4).""" + + return any(value is None for value in (message.context or {}).values()) + + #: The `handoff` values and responders this version defines (§8.7). HANDOFF_STATES = ("none", "pending") RESPONDERS = ("agent", "human") @@ -1225,9 +1345,11 @@ def known_responder(value: object) -> object: class ConversationState(ProtocolModel): """Where a conversation stands, in four fields each independent of the others (§8.7). - `working` is true while the Company has work in progress: a request it accepted but - hasn't acted on, a reply being written, or work it started on its own; a Personal - Agent that wants the whole reply reads until it is false. `handoff` is `pending` + `working` is true only while the Company is still replying: a request it accepted but + hasn't acted on, or a reply being written (§8.7, from 1.0). Work it finishes later, + such as a refund that takes days, isn't `working`: the Company says so in a message, + and adds another when it's done. A Personal Agent that wants the whole reply reads + until it is false. `handoff` is `pending` while the Company looks for a person (§8.9). `responder` is who handles the Company side. `closed` means the conversation takes no more messages (§8.12). A new conversation starts with `handoff` `none`, `responder` `agent` and `closed` false. @@ -1264,7 +1386,9 @@ class ConversationEvent(ProtocolModel): handoff: Literal["none", "pending"] | None = None responder: Literal["agent", "human"] | None = None closed: bool | None = None - error: Literal["insufficient_scope"] | None = None + #: An `authorization` event's error (§8.11): `insufficient_scope`, or a value a later + #: version adds. Whatever it says, the Personal Agent signs in again for `scope`. + error: str | None = Field(default=None, min_length=1) scope: str | None = None reason: str | None = None conversation_id: str | None = None @@ -1289,6 +1413,16 @@ def known(self) -> bool: return self.type in KNOWN_EVENT_TYPES + @property + def sign_in_scopes(self) -> tuple[str, ...]: + """For an `authorization` event, the scopes to sign in again for (§5.4, §8.11): + those in `scope`, whatever `error` says, a value this SDK doesn't recognize + included. Empty for any other event.""" + + if self.type != "authorization" or not self.scope: + return () + return tuple(dict.fromkeys(scope for scope in self.scope.split(" ") if scope)) + @field_validator("created_at") @classmethod def validate_timestamp(cls, value: datetime) -> datetime: diff --git a/personal_agent_protocol/pages.py b/personal_agent_protocol/pages.py index 9bd724b7..6551140b 100644 --- a/personal_agent_protocol/pages.py +++ b/personal_agent_protocol/pages.py @@ -50,7 +50,7 @@ import httpx from .errors import TransportError -from .models import DiscoveredCompany, DiscoveryDocument +from .models import DiscoveredCompany, DiscoveryDocument, url_domain from .reactor import ( URL_SAFETY_POLICIES, ApprovedUrl, @@ -82,20 +82,10 @@ class FetchedPage: def page_carries_session(url: str, domain: str) -> bool: """Whether a page fetch carries the Session header (§5.2): an HTTPS URL whose host is - exactly `organization.domain`, compared ignoring case, on the default port.""" + exactly `organization.domain`, compared ignoring case, on its port: 443, or from 1.0 + the one the domain names (§3.1).""" - parsed = urlsplit(url) - try: - port = parsed.port - except ValueError: - return False - return ( - parsed.scheme == "https" - and (parsed.hostname or "").lower() == domain.lower().rstrip(".") - and port in {None, 443} - and not parsed.username - and not parsed.password - ) + return url_domain(url) == domain.lower().rstrip(".") def _document_key(url: str) -> str | None: diff --git a/personal_agent_protocol/profile.py b/personal_agent_protocol/profile.py index e35b2e68..f156161e 100644 --- a/personal_agent_protocol/profile.py +++ b/personal_agent_protocol/profile.py @@ -11,10 +11,12 @@ `protocol/UPSTREAM.md` and the compatibility page state them too, and a test holds all of them equal. -`DRAFT_PROTOCOL_VERSION` is the 1.0 draft, and `DRAFT_PROTOCOL_REVISION` the -date of the draft text implemented. Since 0.36 it is `DEFAULT_PROTOCOL_VERSION`, -the version a Personal Agent or a Company uses unless it asks for others -(`protocol_versions`): 0.4 as published stays available, used only when named. +`DRAFT_PROTOCOL_VERSION` is version 1.0, a draft until upstream published and +froze it on 2026-11-14, and `DRAFT_PROTOCOL_REVISION` the date of the text +implemented: since 0.37, 1.0 as published (commit 8c02b42). The names stay from +the draft. Since 0.36 it is `DEFAULT_PROTOCOL_VERSION`, the version a Personal +Agent or a Company uses unless it asks for others (`protocol_versions`): 0.4 as +published stays available, used only when named. """ from __future__ import annotations @@ -24,11 +26,11 @@ #: The upstream specification revision implemented: the day 0.4 was published (commit 4803900). PROTOCOL_REVISION = "2026-11-10" -#: The draft protocol version, the 1.0 draft: the default since 0.36. +#: Protocol version 1.0, the default since 0.36 (named while it was the draft). DRAFT_PROTOCOL_VERSION = "1.0" -#: The draft's revision implemented: lookalike domains, its first fix (commit c71f515). -DRAFT_PROTOCOL_REVISION = "2026-11-11" -#: The version used unless a Personal Agent or a Company names others: the 1.0 draft. +#: The 1.0 text implemented: 1.0 as published and frozen on 2026-11-14 (commit 8c02b42). +DRAFT_PROTOCOL_REVISION = "2026-11-14" +#: The version used unless a Personal Agent or a Company names others: 1.0. DEFAULT_PROTOCOL_VERSION = DRAFT_PROTOCOL_VERSION __all__ = [ diff --git a/personal_agent_protocol/reactor.py b/personal_agent_protocol/reactor.py index 3d08d3a6..050966eb 100644 --- a/personal_agent_protocol/reactor.py +++ b/personal_agent_protocol/reactor.py @@ -1081,7 +1081,7 @@ def build_pap_reactor( platform.register_plugin( PluginManifest( name="personal-agent-protocol.core", - version="0.36.1", + version="0.37.0", contribution_points=[ DISCOVERY_TRANSPORTS.id, URL_SAFETY_POLICIES.id, diff --git a/personal_agent_protocol/ucp.py b/personal_agent_protocol/ucp.py index 8708fe93..0a086739 100644 --- a/personal_agent_protocol/ucp.py +++ b/personal_agent_protocol/ucp.py @@ -23,9 +23,11 @@ import httpx from pydantic import Field, ValidationError +from .accounts import scopes_to_request from .errors import PersonalAgentProtocolError, SessionError from .json import loads_strict -from .models import DiscoveredCompany, DiscoveryDocument, ProtocolModel +from .models import DiscoveredCompany, DiscoveryDocument, ProtocolModel, parse_version +from .profile import DEFAULT_PROTOCOL_VERSION from .reactor import send_bounded from .refusals import challenge_parameters from .sessions import AccessToken, PapSession @@ -251,11 +253,26 @@ def _refusal(self, response: httpx.Response) -> UcpError: ) -def ucp_scopes(profile: UcpProfile, held: Sequence[str] = ()) -> tuple[str, ...]: - """The identity linking scopes not in `held`: for `insufficient_scope`, UCP asks only - for the missing ones, by incremental authorization (UCP extension 4).""" +def ucp_scopes( + profile: UcpProfile, + held: Sequence[str] = (), + *, + needed: Sequence[str] = (), + protocol_version: str = DEFAULT_PROTOCOL_VERSION, +) -> tuple[str, ...]: + """The scopes a sign-in requests after a UCP `insufficient_scope` (UCP extension 4). + + From 1.0, every scope the Personal Agent still needs, as spec 4.7 describes: the + ones `held` that it wants to keep, then those the challenge names (`needed`, the + profile's identity linking scopes when it names none), once each; the Company grants + only what the request names. At 0.4, UCP's incremental authorization: only the + identity linking scopes not `held`, and the Company keeps the earlier ones. + """ - return tuple(scope for scope in profile.identity_linking_scopes if scope not in held) + wanted = tuple(needed) or tuple(profile.identity_linking_scopes) + if parse_version(protocol_version)[0] >= 1: + return scopes_to_request(held, wanted) + return tuple(scope for scope in wanted if scope not in held) __all__ = [ diff --git a/protocol/UPSTREAM.md b/protocol/UPSTREAM.md index ae2de9ca..3ed2e1b8 100644 --- a/protocol/UPSTREAM.md +++ b/protocol/UPSTREAM.md @@ -3,10 +3,10 @@ - Protocol: Personal Agent Protocol (Poppy) - Profile implemented: 0.4 as published - Upstream page revision: 2026-11-10 -- Draft implemented, the default since SDK 0.36: 1.0 as of 2026-11-11 (c71f515; nothing after it through ad20217) -- Draft specification: https://personalagentprotocol.org/docs/spec -- Upstream source: commit 4803900 of https://github.com/personal-agent-protocol/personal-agent-protocol (the frozen text as of ed47408, which only dropped the word "draft" from it) -- Last reviewed by this repository: 2026-11-12 (through ad20217) +- Version 1.0 implemented, the default since SDK 0.36: 1.0 as published, frozen on 2026-11-14 (commit 8c02b42), since SDK 0.37 +- Version 1.0 specification: https://personalagentprotocol.org/docs/1.0/spec +- Upstream source: commit 8c02b42 of https://github.com/personal-agent-protocol/personal-agent-protocol for 1.0; commit 4803900 for 0.4 (the frozen text as of ed47408, which only dropped the word "draft" from it) +- Last reviewed by this repository: 2026-11-17 (through 6764732) - Specification: https://personalagentprotocol.org/docs/0.4/spec - Guides: https://personalagentprotocol.org/docs/0.4/guides - Operations extension: version 3 @@ -41,6 +41,30 @@ operations on websites (the `Poppy-Operation` header and the extension's `endpoint`, Operations 4 and 6) and the Browser Control extension, version 1. Upstream had no commit after ad20217 when 0.34 was built. +Upstream published and froze 1.0 on 2026-11-14 (8c02b42, "Publish and freeze +1.0"), at /docs/1.0/spec. SDK 0.37 implements 1.0 as published: every change the +upstream changelog lists for 1.0 after c71f515, in both SDKs and both reference +companies, each in the CHANGELOG and the 0.36 → 0.37 migration page. A +conversation protocol's `description`, required; Pushed Authorization Requests +(the agent pushes whenever the issuer lists the endpoint, and a company may offer +or require it); minor versions (each side sends only what the other's version +defines); PS384 required for client assertions and delegations, RSA keys of 2048 +to 4096 bits; `prompt=consent`, and the consent page for scopes granted before; the +same DPoP key at refresh (a company may bind refresh tokens to it); UCP sign-ins +that request every scope still needed, the company granting only those; ports in +`organization.domain`, used only when the agent is configured to; client +assertions of at most five minutes; one sign-in for every resource, `invalid_target` +for a service a company leaves out; `context` cleared with `null`; unknown roles, +author types, stream event names and error codes; `working` meaning only that the +company is still replying; unknown `authorization` errors; and the Mediated +Sign-In retirement date, March 17, 2027. The commits after 8c02b42 through +6764732 (85b41ff, 6561853, 6764732) restructure the site and change no normative +text: content/versions/1.0 and kit/company are unchanged. 0.4 as published is +unchanged: where the 1.0 text differs, the SDK applies it at 1.0 only, by the +version the Session or document uses. What happens to an operation in flight at +sign-out is open upstream (issue #84); the docs' open-topics page says what the +reference companies do today. + Draft 1.0 opened upstream on 2026-11-11 (272cab0, "Start the 1.0 draft") at /docs/spec: 0.4 plus fixes for problems implementers find, which can include changes that are not backward compatible. Upstream now says to build against @@ -129,12 +153,12 @@ from an unattended documentation fetch. Draft 0.1 stays readable, frozen, at https://personalagentprotocol.org/docs/0.1/spec; draft 0.2 is frozen at https://personalagentprotocol.org/docs/0.2/spec, and 0.3 at https://personalagentprotocol.org/docs/0.3/spec. This repository implements -0.4 as published only and uses no earlier document. +1.0 and 0.4 as published only and uses no earlier document. ## Vendored JSON Schemas `protocol/schemas/` holds JSON Schemas copied unchanged from the upstream -company kit (`kit/company/schemas/`) at commit ed47408 (0.4 as published), under the upstream +company kit (`kit/company/schemas/`) at commit 8c02b42 (1.0 as published), under the upstream repository's license (Apache License 2.0). The tests check the shared fixtures and the reference company's documents against them (`personal_agent_protocol/__tests__/test_schemas.py`). They are replaced diff --git a/protocol/fixtures/conformance/dpop.json b/protocol/fixtures/conformance/dpop.json index 59757a7d..15f5f52c 100644 --- a/protocol/fixtures/conformance/dpop.json +++ b/protocol/fixtures/conformance/dpop.json @@ -6,6 +6,11 @@ "dpop-binding": { "dpop_binding": "required", "dpop_nonces": true + }, + "pushed-requests": { + "dpop_binding": "required", + "bind_refresh_tokens": true, + "pushed_authorization_requests": "required" } }, "cases": [ @@ -422,7 +427,7 @@ "requirements": [ "PAP-4.5-01" ], - "description": "Refresh tokens aren't bound: after the DPoP key is lost a refresh gets a token for a new key, which works, and the old token is refused.", + "description": "This company binds access tokens, not refresh tokens: after the DPoP key is lost a refresh gets a token for a new key, which works, and the old token is refused. A company that binds refresh tokens too refuses that refresh (§4.4, dpop.refresh-bound-to-its-key).", "world": "dpop-binding" }, { @@ -522,6 +527,27 @@ ], "world": "dpop-binding", "description": "At an issuer that lists DPoP, a server whose metadata doesn't gets a Bearer token and no proof, and accepts it." + }, + { + "id": "dpop.refresh-bound-to-its-key", + "kind": "recovery", + "role": "both", + "requirements": [ + "PAP10-4.4-01" + ], + "description": "The agent refreshes with the DPoP key it got the refresh token with, every time (§4.4): a company that binds refresh tokens accepts it, rotated tokens included, and refuses a refresh with another key (invalid_grant), so the agent is signed out and signs in again.", + "world": "pushed-requests" + }, + { + "id": "dpop.pushed-authorization-request", + "kind": "positive", + "role": "both", + "requirements": [ + "PAP10-4.2-02", + "PAP10-4.2-03" + ], + "description": "A company that requires Pushed Authorization Requests says so in its metadata (§3.2); the agent pushes the request with its client assertion and a DPoP proof and opens the authorization endpoint with client_id and request_uri only, and the sign-in completes; a request that wasn't pushed is refused (§4.2, RFC 9126).", + "world": "pushed-requests" } ] } diff --git a/protocol/fixtures/conformance/protocol.json b/protocol/fixtures/conformance/protocol.json index 1dcca013..79b96898 100644 --- a/protocol/fixtures/conformance/protocol.json +++ b/protocol/fixtures/conformance/protocol.json @@ -119,26 +119,31 @@ "protocols": [ { "type": "poppy", - "endpoint": "https://example.com/poppy" + "endpoint": "https://example.com/poppy", + "description": "Anything about your orders, returns, account, and our products" }, { "type": "poppy", "endpoint": "https://example.com/poppy", + "description": "Anything about your orders, returns, account, and our products", "access": "session" }, { "type": "poppy", "endpoint": "https://example.com/poppy", + "description": "Anything about your orders, returns, account, and our products", "access": "signed_in" }, { "type": "poppy", "endpoint": "https://example.com/poppy", + "description": "Anything about your orders, returns, account, and our products", "access": "members_only" }, { "type": "a2a", "endpoint": "https://example.com/poppy", + "description": "Anything about your orders, returns, account, and our products", "access": "signed_in" } ] @@ -221,7 +226,8 @@ "protocols": [ { "type": "poppy", - "endpoint": "https://api.example.com/poppy/conversations" + "endpoint": "https://api.example.com/poppy/conversations", + "description": "Anything about your orders, returns, account, and our products" } ] }, @@ -341,11 +347,13 @@ "protocols": [ { "type": "a2a", - "endpoint": "https://api.example.com/a2a" + "endpoint": "https://api.example.com/a2a", + "description": "Anything about your orders, returns, account, and our products" }, { "type": "poppy", - "endpoint": "https://api.example.com/poppy/conversations" + "endpoint": "https://api.example.com/poppy/conversations", + "description": "Anything about your orders, returns, account, and our products" } ] } @@ -1078,7 +1086,8 @@ "protocols": [ { "type": "poppy", - "endpoint": "https://api.example.com/poppy/conversations" + "endpoint": "https://api.example.com/poppy/conversations", + "description": "Anything about your orders, returns, account, and our products" } ] } @@ -2145,7 +2154,8 @@ "protocols": [ { "type": "poppy", - "endpoint": "https://api.example.com/poppy/conversations" + "endpoint": "https://api.example.com/poppy/conversations", + "description": "Anything about your orders, returns, account, and our products" } ] } @@ -2430,6 +2440,281 @@ "UCP-4-04" ], "description": "A Company that lists the UCP extension serves its UCP profile at https://{organization.domain}/.well-known/ucp with no redirect; identity linking's scopes are in scopes_supported, and with sign-in it offers Direct Sign-In and private_key_jwt (UCP extension 2 to 4); skipped when it doesn't list the extension." + }, + { + "id": "protocol.agent-protocol-description-required", + "kind": "negative", + "role": "personal-agent", + "requirements": [ + "PAP10-8.1-01" + ], + "check": "discovery_document", + "description": "From 1.0 every agent.protocols entry has a description of what the agent there can help with (§3.1, §8.1): a 1.0 document whose entry has none is invalid.", + "input": { + "protocol_version": "1.0", + "organization": { + "name": "Example", + "domain": "example.com" + }, + "agent": { + "protocols": [ + { + "type": "poppy", + "endpoint": "https://example.com/poppy/conversations" + } + ] + } + }, + "expect": { + "valid": false + } + }, + { + "id": "protocol.agent-protocol-description-not-in-04", + "kind": "positive", + "role": "personal-agent", + "requirements": [ + "PAP10-3.4-02" + ], + "check": "discovery_document", + "description": "0.4 as published defines no description: a 0.4 document without one is used as before (§3.4).", + "input": { + "protocol_version": "0.4", + "organization": { + "name": "Example", + "domain": "example.com" + }, + "agent": { + "protocols": [ + { + "type": "poppy", + "endpoint": "https://example.com/poppy/conversations" + } + ] + } + }, + "expect": { + "valid": true, + "conversation_endpoint": "https://example.com/poppy/conversations" + } + }, + { + "id": "protocol.agent-protocols-described", + "kind": "positive", + "role": "company", + "requirements": [ + "PAP10-8.1-01", + "PAP10-3.4-01" + ], + "description": "At 1.0 every agent.protocols entry of poppy.json has a non-empty description (§3.1, §8.1); the company's 0.4 document, if any, has none, since 0.4 doesn't define it (§3.4). Nothing to check at 0.4." + }, + { + "id": "protocol.organization-domain-port", + "kind": "positive", + "role": "personal-agent", + "requirements": [ + "PAP10-3.1-01" + ], + "check": "discovery", + "description": "From 1.0 organization.domain includes its port when that isn't 443, and an agent configured to use a company on another port does (§3.1).", + "input": { + "domain": "shop.example:8443", + "allow_ports": true, + "responses": { + "https://shop.example:8443/.well-known/poppy.json": { + "status": 200, + "json": { + "protocol_version": "1.0", + "organization": { + "name": "Shop", + "domain": "shop.example:8443" + }, + "web": {} + } + } + } + }, + "expect": { + "organization_domain": "shop.example:8443" + } + }, + { + "id": "protocol.organization-domain-port-not-allowed", + "kind": "negative", + "role": "personal-agent", + "requirements": [ + "PAP10-3.1-01" + ], + "check": "discovery", + "description": "A company on another port is used only when the agent is configured to on purpose (§3.1).", + "input": { + "domain": "shop.example:8443", + "responses": { + "https://shop.example:8443/.well-known/poppy.json": { + "status": 200, + "json": { + "protocol_version": "1.0", + "organization": { + "name": "Shop", + "domain": "shop.example:8443" + }, + "web": {} + } + } + } + }, + "expect": { + "error": "port_not_allowed" + } + }, + { + "id": "protocol.organization-domain-port-other-domain", + "kind": "negative", + "role": "personal-agent", + "requirements": [ + "PAP10-3.1-01", + "PAP-3.1-02" + ], + "check": "discovery", + "description": "A document on shop.example:8443 speaks for shop.example:8443, not shop.example (§3.1).", + "input": { + "domain": "shop.example:8443", + "allow_ports": true, + "responses": { + "https://shop.example:8443/.well-known/poppy.json": { + "status": 200, + "json": { + "protocol_version": "1.0", + "organization": { + "name": "Shop", + "domain": "shop.example" + }, + "web": {} + } + } + } + }, + "expect": { + "error": "organization_domain_mismatch" + } + }, + { + "id": "protocol.organization-domain-port-04", + "kind": "negative", + "role": "personal-agent", + "requirements": [ + "PAP10-3.4-02" + ], + "check": "discovery_document", + "description": "0.4 names a host only: a 0.4 document whose organization.domain has a port is invalid (§3.1, §3.4).", + "input": { + "protocol_version": "0.4", + "organization": { + "name": "Shop", + "domain": "shop.example:8443" + }, + "web": {} + }, + "expect": { + "valid": false + } + }, + { + "id": "protocol.unknown-role-and-author-type", + "kind": "positive", + "role": "personal-agent", + "requirements": [ + "PAP-3.3-02", + "PAP-3.3-04" + ], + "check": "message_tolerance", + "description": "A role the agent doesn't recognize is content from the Company, and an author.type it doesn't recognize is agent (§8.4).", + "input": [ + { + "author": { + "type": "organization" + }, + "role": "system", + "text": "Hi" + }, + { + "author": { + "type": "human" + }, + "role": "user", + "text": "Me" + }, + { + "author": { + "type": "agent" + }, + "role": "company", + "text": "Us" + } + ], + "expect": { + "roles": [ + "company", + "user", + "company" + ], + "author_types": [ + "agent", + "human", + "agent" + ] + } + }, + { + "id": "protocol.authorization-error-unknown", + "kind": "positive", + "role": "personal-agent", + "requirements": [ + "PAP-8.11-01" + ], + "check": "authorization_event", + "description": "An authorization event with an error the agent doesn't recognize asks it to sign in again for the scopes in scope (§8.11).", + "input": { + "id": "evt_a1", + "type": "authorization", + "created_at": "2026-11-14T09:00:00Z", + "error": "stronger_sign_in", + "scope": "orders:read orders:write" + }, + "expect": { + "sign_in_scopes": [ + "orders:read", + "orders:write" + ] + } + }, + { + "id": "protocol.context-cleared", + "kind": "positive", + "role": "both", + "requirements": [ + "PAP-8.4-02" + ], + "check": "effective_context", + "description": "Context fields a message leaves out keep their values, and a field set to null is cleared, as if never shared (§8.4).", + "input": [ + { + "locale": "fr", + "time_zone": "Europe/Paris" + }, + { + "user_available": true + }, + { + "locale": null + } + ], + "expect": { + "context": { + "time_zone": "Europe/Paris", + "user_available": true + } + } } ] } diff --git a/protocol/fixtures/discovery-valid.json b/protocol/fixtures/discovery-valid.json index 31e59fdc..4e0cc4b2 100644 --- a/protocol/fixtures/discovery-valid.json +++ b/protocol/fixtures/discovery-valid.json @@ -32,7 +32,8 @@ "protocols": [ { "type": "poppy", - "endpoint": "https://api.example.com/poppy/conversations" + "endpoint": "https://api.example.com/poppy/conversations", + "description": "Anything about your orders, returns, account, and our products" } ] }, diff --git a/protocol/requirements.yaml b/protocol/requirements.yaml index 832538c3..40e0bad8 100644 --- a/protocol/requirements.yaml +++ b/protocol/requirements.yaml @@ -1,4 +1,4 @@ -# Personal Agent Protocol 0.4 as published (upstream 4803900, frozen text as of ed47408), Operations version 3, Mediated Sign-In and Browser Control version 1: the normative requirement ledger. +# Personal Agent Protocol 0.4 as published (upstream 4803900, frozen text as of ed47408), Operations version 3, Mediated Sign-In and Browser Control version 1, and what 1.0 as published (upstream 8c02b42) changes: the normative requirement ledger. # # requirements: every MUST, MUST NOT, SHOULD, and SHOULD NOT of the specification # (source: spec, the default), the Operations extension (source: operations), the @@ -12,13 +12,16 @@ # run by test_fixtures.py (decided by the SDK) or by the conformance runner # (test_conformance.py, against the reference company over TLS). # status: implemented | partial | open | not-applicable, with a reason unless implemented. +# version: '1.0' marks a statement 1.0 as published adds or changes (PAP10-*), and '0.4' one +# that holds at 0.4 only; an entry without it holds at both versions. # test_requirements.py checks every test and case exists. protocol: personal-agent-protocol profile: '0.4' upstream_revision: '2026-11-10' -reviewed: '2026-11-12' +reviewed: '2026-11-17' sources: + spec-1.0: https://personalagentprotocol.org/docs/1.0/spec spec: https://personalagentprotocol.org/docs/0.4/spec operations: https://personalagentprotocol.org/docs/0.4/extensions/operations guide: https://personalagentprotocol.org/docs/0.4/guides @@ -3746,6 +3749,7 @@ requirements: - personal_agent_protocol/__tests__/test_ucp.py::test_orders_need_identity_linking_through_this_protocols_sign_in - id: UCP-4-06 source: ucp + version: '0.4' section: '4' level: MUST role: company @@ -3754,8 +3758,9 @@ requirements: status: open implementation: - personal_agent_protocol.company.service:CompanyService._sign_in - reason: The reference companies grant the scopes a sign-in asks for; incremental authorization that keeps - earlier grants is not implemented, so a Personal Agent asks again for every scope it still needs. + reason: 0.4 only. 1.0 replaced it (UCP 4) - the Personal Agent requests every scope it still needs and + the Company grants only the scopes the request names, which the reference companies do at every version + (ucp_scopes); incremental authorization that keeps earlier grants is not implemented for 0.4. - id: UCP-8-01 source: ucp section: '8' @@ -3877,6 +3882,298 @@ requirements: - personal_agent_protocol.demo.manzanita:ManzanitaWebsite tests: - personal_agent_protocol/__tests__/test_browser_control.py::test_the_company_lists_browser_control_and_the_join_carries_the_declaration +- id: PAP10-3.1-01 + version: '1.0' + section: '3.1' + level: MUST + role: both + text: domain MUST be the host that serves the document, after any redirects, with its port when that isn't + 443. Personal Agents use a Company on another port only when configured to on purpose, such as for testing + (section 3). + status: implemented + implementation: + - personal_agent_protocol.models:split_domain + - personal_agent_protocol.models:DiscoveryDocument.validate_version_fields + - personal_agent_protocol.discovery:DiscoveryClient.discover + - personal_agent_protocol.company.service:CompanyConfig + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_a_domain_names_its_port_when_that_isnt_443_from_10_only + - personal_agent_protocol/__tests__/test_published_10.py::test_an_agent_uses_a_company_on_another_port_only_when_configured_to + conformance: + - protocol.organization-domain-port + - protocol.organization-domain-port-not-allowed + - protocol.organization-domain-port-other-domain +- id: PAP10-3.4-01 + version: '1.0' + section: '3.4' + level: MUST NOT + role: company + text: The Company MUST NOT send the Personal Agent a field, value, or event that only a minor version later + than the request's Poppy-Version defines. + status: implemented + implementation: + - personal_agent_protocol.company.service:CompanyService.discovery_document + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_the_reference_company_describes_its_agent_at_10_and_not_at_04 + - personal_agent_protocol/__tests__/test_published_10.py::test_nothing_of_10_goes_into_a_04_exchange + conformance: + - protocol.agent-protocols-described +- id: PAP10-3.4-02 + version: '1.0' + section: '3.4' + level: MUST NOT + role: personal-agent + text: The Personal Agent MUST NOT send the Company one that only a version later than the chosen document's + protocol_version defines. + status: implemented + implementation: + - personal_agent_protocol.conversations:ConversationClient._outgoing_message + - personal_agent_protocol.models:clears_context + - personal_agent_protocol.models:DiscoveryDocument.validate_version_fields + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_nothing_of_10_goes_into_a_04_exchange + - personal_agent_protocol/__tests__/test_published_10.py::test_a_10_document_needs_a_description_for_each_conversation_protocol + conformance: + - protocol.agent-protocol-description-not-in-04 + - protocol.organization-domain-port-04 +- id: PAP10-4.1-01 + version: '1.0' + section: '4.1' + level: MUST + role: personal-agent + text: Client assertions follow RFC 7523 §3. The Personal Agent MUST include iat and a unique, unguessable + jti, and MUST set exp at most 5 minutes after iat. + status: implemented + implementation: + - personal_agent_protocol.sessions:build_client_assertion_claims + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_an_assertion_lasts_at_most_five_minutes_and_one_that_does_is_accepted +- id: PAP10-4.1-02 + version: '1.0' + section: '4.1' + level: MUST NOT + role: company + text: A Company MAY reject a client assertion that lasts longer than 5 minutes, and MUST NOT reject one for + lasting 5 minutes or less. + status: implemented + implementation: + - personal_agent_protocol.company.verify:verify_assertion + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_an_assertion_lasts_at_most_five_minutes_and_one_that_does_is_accepted +- id: PAP10-4.1-03 + version: '1.0' + section: '4.1' + level: MUST + role: company + text: Companies MUST accept client assertions signed with ES256 and with PS384. + status: implemented + implementation: + - personal_agent_protocol.company.verify:verify_assertion + - personal_agent_protocol.company.verify:RSA_KEY_BITS + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_companies_accept_ps384_assertions_and_delegations + - personal_agent_protocol/__tests__/test_published_10.py::test_an_rsa_key_outside_2048_to_4096_bits_is_refused + - personal_agent_protocol/__tests__/test_blind_signing.py::test_a_company_takes_an_agent_that_signs_everything_blindly +- id: PAP10-4.2-01 + version: '1.0' + section: '4.2' + level: MUST + role: personal-agent + text: Unless the Personal Agent receives the redirect only on the device that opened the authorization URL, + as below, the authorization request MUST include prompt=consent (OpenID Connect Core §3.1.2.1). + status: implemented + implementation: + - personal_agent_protocol.auth:build_direct_sign_in_request + - personal_agent_protocol.auth:DirectSignInClient.begin + - personal_agent_protocol.auth:PROMPT_CONSENT + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_a_direct_sign_in_asks_for_consent_unless_the_redirect_stays_on_the_device + - personal_agent_protocol/__tests__/test_hosted_pages.py::test_authorize_redirects_to_the_hosted_consent_page_which_reads_the_request +- id: PAP10-4.2-04 + version: '1.0' + section: '4.2' + level: SHOULD + role: company + text: The Company SHOULD support prompt=consent, whether or not it supports OpenID Connect, and show its + consent page for a request that includes it, even when the account already granted every requested scope + to the client_id (10.8). + status: implemented + implementation: + - personal_agent_protocol.company.service:CompanyService._authorize + - personal_agent_protocol.company.service:CompanyService.authorization_request + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_the_consent_page_lists_every_scope_and_marks_the_earlier_ones + - personal_agent_protocol/__tests__/test_hosted_pages.py::test_authorize_redirects_to_the_hosted_consent_page_which_reads_the_request +- id: PAP10-4.2-02 + version: '1.0' + section: '4.2' + level: MUST + role: personal-agent + text: A Company MAY require Pushed Authorization Requests (PAR, RFC 9126) by setting require_pushed_authorization_requests + to true in its issuer's metadata (3.2). The Personal Agent then MUST send the authorization request's parameters + to the pushed_authorization_request_endpoint with its client assertion, and open the authorization_endpoint + with only client_id and the request_uri it gets back. + status: implemented + implementation: + - personal_agent_protocol.auth:DirectSignInClient.begin + - personal_agent_protocol.auth:DirectSignInClient._push + - personal_agent_protocol.auth:DirectSignInRequest.pushed_authorization_url + - personal_agent_protocol.models:OAuthServerMetadata + - personal_agent_protocol.company.service:CompanyService._pushed_request + - personal_agent_protocol.company.service:CompanyConfig + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_a_company_offers_or_requires_par_and_the_agent_pushes + - personal_agent_protocol/__tests__/test_published_10.py::test_a_company_that_requires_par_takes_nothing_else + - personal_agent_protocol/__tests__/test_published_10.py::test_a_push_with_a_dpop_proof_binds_the_code_to_its_key + conformance: + - dpop.pushed-authorization-request +- id: PAP10-4.2-03 + version: '1.0' + section: '4.2' + level: SHOULD + role: personal-agent + text: A Personal Agent SHOULD use PAR whenever the metadata lists the endpoint. + status: partial + reason: DirectSignInClient pushes whenever the host passes the issuer's pushed_authorization_request_endpoint, + as the pap CLI and the conformance runner do; a host that calls it without the endpoint doesn't push. + implementation: + - personal_agent_protocol.auth:DirectSignInClient.begin + - personal_agent_protocol.conformance:ConformanceContext.sign_in + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_a_company_offers_or_requires_par_and_the_agent_pushes + conformance: + - dpop.pushed-authorization-request +- id: PAP10-4.2-05 + version: '1.0' + section: '4.2' + level: SHOULD + role: personal-agent + text: When the Personal Agent sends the User a link to open later, such as on their phone, it SHOULD link + to a page of its own that pushes the request when the User opens it and then redirects to the authorization_endpoint. + status: partial + reason: begin(link_page=...) hands the browser the agent's own page and open_link pushes when it is opened; + serving that page and redirecting is the host's. + implementation: + - personal_agent_protocol.auth:DirectSignInClient.open_link + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_a_link_opened_later_goes_to_the_agents_page_which_pushes_then +- id: PAP10-4.3-01 + version: '1.0' + section: '4.3' + level: SHOULD + role: company + text: The Company SHOULD show its consent page for every request, even when the account already granted every + requested scope to the client_id (10.8). + status: implemented + implementation: + - personal_agent_protocol.company.service:CompanyService.device_request + - personal_agent_protocol.company.service:CompanyService.approve_device + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_every_device_sign_in_shows_its_page_with_the_earlier_scopes_marked +- id: PAP10-4.4-01 + version: '1.0' + section: '4.4' + level: MUST + role: personal-agent + text: A Personal Agent that sends a DPoP proof when it gets a refresh token (4.5) MUST send a proof from + the same key with every refresh of that refresh token, and of the refresh tokens that replace it. + status: implemented + implementation: + - personal_agent_protocol.crypto:InMemoryDpopKeys + - personal_agent_protocol.crypto:JoseDpopProver + - personal_agent_protocol.accounts:RefreshTokenClient.refresh + - personal_agent_protocol.company.service:CompanyConfig + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_a_bound_refresh_token_refreshes_only_with_its_key + - personal_agent_protocol/__tests__/test_published_10.py::test_without_binding_a_refresh_with_a_new_key_still_works + conformance: + - dpop.refresh-bound-to-its-key +- id: PAP10-4.5-01 + version: '1.0' + section: '4.5' + level: MUST + role: company + text: After a sign-in without resource, the Company MUST issue a token for any resource it offers Personal + Agents, at refresh too. + status: implemented + implementation: + - personal_agent_protocol.company.service:CompanyService._refresh_grant + - personal_agent_protocol.company.service:CompanyService._resource + - personal_agent_protocol.company.service:CompanyService._resource_allowed + - personal_agent_protocol.accounts:ServiceTokens.token_for + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_a_service_left_out_is_invalid_target_and_used_signed_out +- id: PAP10-4.5-02 + version: '1.0' + section: '4.5' + level: SHOULD NOT + role: personal-agent + text: 'The Personal Agent SHOULD NOT include resource in the request that starts sign-in: if it does, the + Company MAY limit the grant to the resources it names, as RFC 8707 §2.2 allows.' + status: implemented + implementation: + - personal_agent_protocol.auth:build_direct_sign_in_request + - personal_agent_protocol.device:DeviceSignInClient.begin + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_a_direct_sign_in_asks_for_consent_unless_the_redirect_stays_on_the_device +- id: PAP10-5.2-01 + version: '1.0' + section: '5.2' + level: MUST + role: company + text: alg is ES256 or PS384. Companies MUST accept delegations signed with ES256 and with PS384. + status: implemented + implementation: + - personal_agent_protocol.company.verify:verify_delegation + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_companies_accept_ps384_assertions_and_delegations +- id: PAP10-8.1-01 + version: '1.0' + section: '8.1' + level: MUST + role: company + text: An entry's description says, in plain language, what the agent at that endpoint can help with. The + Company MUST include a description in every entry, and MAY say the agent can help with anything. + status: implemented + implementation: + - personal_agent_protocol.company.service:CompanyConfig + - personal_agent_protocol.company.service:CompanyService.discovery_document + - personal_agent_protocol.models:AgentProtocol + - personal_agent_protocol.models:DiscoveryDocument.validate_version_fields + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_a_10_document_needs_a_description_for_each_conversation_protocol + - personal_agent_protocol/__tests__/test_published_10.py::test_the_reference_company_describes_its_agent_at_10_and_not_at_04 + conformance: + - protocol.agent-protocol-description-required + - protocol.agent-protocols-described +- id: PAP10-8.6-01 + version: '1.0' + section: '8.6' + level: MUST + role: personal-agent + text: Personal Agents MUST skip stream events with an SSE event name they don't recognize, so later versions + and extensions can add them. + status: implemented + implementation: + - personal_agent_protocol.conversations:ConversationClient.stream + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_a_stream_skips_event_names_it_doesnt_know +- id: PAP10-10.8-01 + version: '1.0' + section: '10.8' + level: MUST + role: company + text: In Direct and Device Sign-In, the Company's consent page MUST list every scope it will grant, except + a poppy:browser-sign-in it MAY grant without asking (section 6). It MAY mark the ones the User already + granted. + status: implemented + implementation: + - personal_agent_protocol.company.service:CompanyService._authorize + - personal_agent_protocol.company.service:CompanyService.authorization_request + - personal_agent_protocol.company.service:CompanyService.device_request + tests: + - personal_agent_protocol/__tests__/test_published_10.py::test_the_consent_page_lists_every_scope_and_marks_the_earlier_ones + - personal_agent_protocol/__tests__/test_published_10.py::test_every_device_sign_in_shows_its_page_with_the_earlier_scopes_marked guide: - id: GUIDE-secrets-01 source: guide diff --git a/protocol/schemas/authorization-server-metadata.schema.json b/protocol/schemas/authorization-server-metadata.schema.json index c7ba32ee..c0313b78 100644 --- a/protocol/schemas/authorization-server-metadata.schema.json +++ b/protocol/schemas/authorization-server-metadata.schema.json @@ -18,7 +18,7 @@ "authorization_endpoint": { "$ref": "#/$defs/https_url" }, "device_authorization_endpoint": { "$ref": "#/$defs/https_url" }, "token_endpoint_auth_signing_alg_values_supported": { - "description": "RFC 8414 section 2. Accepted client-assertion algorithms, not delegation algorithms. Poppy requires ES256 and recommends PS384.", + "description": "RFC 8414 section 2. Accepted client-assertion algorithms, not delegation algorithms. Poppy requires ES256 and PS384.", "type": "array", "items": { "type": "string", "minLength": 1 } }, diff --git a/protocol/schemas/message.schema.json b/protocol/schemas/message.schema.json index 93c6f817..ece8ce0c 100644 --- a/protocol/schemas/message.schema.json +++ b/protocol/schemas/message.schema.json @@ -2,7 +2,7 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "message.schema.json", "title": "Conversation message", - "description": "A message in a Personal Agent Protocol conversation, from either side. Spec sections 8.3 (Sending messages) and 8.4 (Message fields). A message has text, data, context, or extensions. extensions holds content that extensions define, keyed by extension name: operations (Operations extension 2, 4, 6), links, and disclosures are checked here, and other extensions' content must be an object. id and role are set by the Company when it records the message as an event: a Personal Agent message's id is its request's ID. The Personal Agent doesn't send them. as_of_request is only on Company Agent messages and as_of_cursor only on messages the Personal Agent wrote; a message with author.type human has neither (8.4). Unknown fields are allowed.", + "description": "A message in a Personal Agent Protocol conversation, from either side. Spec sections 8.3 (Sending messages) and 8.4 (Message fields). A message has text, data, context, or extensions. extensions holds content that extensions define, keyed by extension name: operations (Operations extension 2, 4, 6), links, and disclosures are checked here, and other extensions' content must be an object. id and role are set by the Company when it records the message as an event: a Personal Agent message's id is its request's ID. The Personal Agent doesn't send them. as_of_request is only on Company Agent messages and as_of_cursor only on messages the Personal Agent wrote; a message with author.type human has neither (8.4). A context field set to null clears it (8.4). Unknown fields are allowed.", "type": "object", "required": ["author"], "properties": { @@ -51,15 +51,15 @@ "type": "object", "properties": { "locale": { - "type": "string", + "type": ["string", "null"], "minLength": 1 }, "time_zone": { - "type": "string", + "type": ["string", "null"], "minLength": 1 }, "user_available": { - "type": "boolean" + "type": ["boolean", "null"] } } }, diff --git a/protocol/schemas/poppy.schema.json b/protocol/schemas/poppy.schema.json index af2043d9..1cf9a2af 100644 --- a/protocol/schemas/poppy.schema.json +++ b/protocol/schemas/poppy.schema.json @@ -82,7 +82,7 @@ "minItems": 1, "items": { "type": "object", - "required": ["type", "endpoint"], + "required": ["type", "endpoint", "description"], "properties": { "type": { "type": "string", @@ -91,6 +91,11 @@ "endpoint": { "$ref": "#/$defs/https_url" }, + "description": { + "type": "string", + "minLength": 1, + "description": "What the agent at this endpoint can help with. It may say anything (spec 8.1)." + }, "access": { "type": "string", "description": "For a poppy protocol entry, session (the default) or signed_in. Unknown values are ignored as an absent hint (spec 3.2)." @@ -261,7 +266,7 @@ }, "domain": { "type": "string", - "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)+$" + "pattern": "^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)+(:[1-9][0-9]{0,4})?$" }, "scopes": { "type": "array", diff --git a/scripts/conformance_report.py b/scripts/conformance_report.py index cc61212c..1635aada 100644 --- a/scripts/conformance_report.py +++ b/scripts/conformance_report.py @@ -137,8 +137,8 @@ def render(reports: dict[str, dict[str, Any]]) -> str: "", f"SDK version **{_version()}**, PAP profile **{_PROFILE}** (as published " f"{_REVISION}), Operations extension **v{_OPERATIONS}**; the pairings run at " - f"protocol version **{_DRAFT}**, the default (the {_DRAFT} draft as of " - f"{_DRAFT_REVISION}). Each pairing runs every " + f"protocol version **{_DRAFT}**, the default ({_DRAFT} as published " + f"{_DRAFT_REVISION}); 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 " diff --git a/scripts/generate_coverage.py b/scripts/generate_coverage.py index 541c14b4..976d809b 100644 --- a/scripts/generate_coverage.py +++ b/scripts/generate_coverage.py @@ -5,7 +5,8 @@ """Generate the protocol coverage reference from the requirement ledger. `protocol/requirements.yaml` has one entry per normative statement of PAP 0.4 as published -and Operations version 3, and the Guides' recommendations apart. This script writes one +and Operations version 3, with what 1.0 as published adds or changes marked `(1.0)`, and the +Guides' recommendations apart. This script writes one page per area under `docs/docs/protocol/coverage/` — every entry with its upstream section, normative level, SDK symbols, test IDs and status — and the summary table between the markers of `docs/docs/protocol/coverage.mdx`. @@ -212,7 +213,9 @@ def _section(entry: dict[str, Any]) -> str: "browser-control": "Browser Control §", } prefix = prefixes.get(entry["source"], "§") - return f"{prefix}{entry['section']}" + # A statement of one version only: 1.0 as published adds or changes it, or 0.4 alone has it. + version = f" ({entry['version']})" if entry.get("version") else "" + return f"{prefix}{entry['section']}{version}" def _status(entry: dict[str, Any]) -> str: diff --git a/src/__tests__/company.test.mjs b/src/__tests__/company.test.mjs index 3be41c1c..1cf76999 100644 --- a/src/__tests__/company.test.mjs +++ b/src/__tests__/company.test.mjs @@ -1279,7 +1279,7 @@ const CONSENT_PAGE = "https://datalayer.ai/pap/consent?slug=orders-helper&reques test("hosted page templates are checked", async () => { const { CompanyConfig } = await import("../../lib/server.js"); - const base = { name: "Shop", domain: "shop.example", scopes: ["orders:read"], operations: false }; + const base = { name: "Shop", domain: "shop.example", scopes: ["orders:read"], agentDescription: "Anything about your orders", operations: false }; assert.throws(() => new CompanyConfig({ ...base, consentPage: "https://datalayer.ai/pap/consent" }), /consentPage/); assert.throws(() => new CompanyConfig({ ...base, devicePage: "http://pap.shop.example/device" }), /HTTPS/); // A device page off the company's domains is a link personal agents refuse (§4.6). @@ -1327,7 +1327,9 @@ test("authorize redirects to the hosted consent page, which reads the request ba // What the page starts with and says before the person goes on (§10.8). assert.equal(summary.heading, "Atlas wants to connect to your Manzanita Outfitters account"); assert.equal(summary.caution, "Only continue if you asked Atlas to do this just now."); - assert.deepEqual(Object.keys(summary).sort(), ["caution", "client_domain", "client_name", "expires_at", "heading", "request_id", "scopes"]); + assert.deepEqual(Object.keys(summary).sort(), ["caution", "client_domain", "client_name", "expires_at", "heading", "prompt", "request_id", "scopes"]); + // The agent asked for the consent page whatever the account granted before (spec 4.2). + assert.equal(summary.prompt, "consent"); const callbackUrl = await w.shop.approveAuthorization(requestId, { accountId: "acct_ada" }); const result = await client.complete({ callbackUrl }); assert.ok(result.token); diff --git a/src/__tests__/conformance-fixtures.test.mjs b/src/__tests__/conformance-fixtures.test.mjs index 0b97c63a..74df883e 100644 --- a/src/__tests__/conformance-fixtures.test.mjs +++ b/src/__tests__/conformance-fixtures.test.mjs @@ -45,8 +45,11 @@ import { browserSignInUnscoped, formatExtensionsHeader, parseExtensionsHeader, + effectiveContext, + parseConversationEvent, parseConversationEventPage, parseDiscoveryDocument, + signInScopes, parseJsonStrict, parseMessage, parseOperation, @@ -183,6 +186,21 @@ const CHECKS = { for (const context of given.invalid) assert.throws(() => parseMessage({ id: "msg_ctx", author: { type: "agent" }, context })); }, + message_tolerance(given, expect) { + const messages = given.map(parseMessage); + assert.deepEqual(messages.map((message) => message.role), expect.roles); + assert.deepEqual(messages.map((message) => message.author.type), expect.author_types); + }, + + authorization_event(given, expect) { + assert.deepEqual([...signInScopes(parseConversationEvent(given))], expect.sign_in_scopes); + }, + + effective_context(given, expect) { + const messages = given.map((context) => parseMessage({ author: { type: "agent" }, context })); + assert.deepEqual(effectiveContext(messages), expect.context); + }, + operation(given, expect) { if (expect.valid === false) { assert.throws(() => parseOperation(given)); @@ -193,7 +211,11 @@ const CHECKS = { }, async discovery(given, expect) { - const options = { fetch: mockNetwork(given.responses), ...(given.timeout_seconds ? { timeoutMs: given.timeout_seconds * 1000 } : {}) }; + const options = { + fetch: mockNetwork(given.responses), + ...(given.timeout_seconds ? { timeoutMs: given.timeout_seconds * 1000 } : {}), + ...(given.allow_ports ? { allowPorts: true } : {}), + }; if ("error" in expect) { await assert.rejects(discoverCompany(given.domain, options), rejectsWith(expect.error)); return; diff --git a/src/__tests__/conformance-pairing.test.mjs b/src/__tests__/conformance-pairing.test.mjs index 9b4dd1c3..0c65be37 100644 --- a/src/__tests__/conformance-pairing.test.mjs +++ b/src/__tests__/conformance-pairing.test.mjs @@ -115,7 +115,10 @@ test("the conformance cases at 0.4 as published: TypeScript agent ↔ TypeScript const failed = Object.fromEntries(report.cases.filter((item) => item.outcome === "failed").map((item) => [item.id, item.message])); assert.deepEqual(failed, {}); assert.equal(report.profile, "0.4"); - assert.deepEqual(report.summary, { passed: report.cases.length, failed: 0, skipped: 0 }); + // What only 1.0 defines has nothing to check at 0.4. + const skipped = report.cases.filter((item) => item.outcome === "skipped").map((item) => item.id); + assert.deepEqual(skipped, ["protocol.agent-protocols-described"]); + assert.deepEqual(report.summary, { passed: report.cases.length - 1, failed: 0, skipped: 1 }); }); test("the DPoP cases: TypeScript agent ↔ TypeScript company over TLS, in the world that binds", async () => { @@ -134,6 +137,23 @@ test("the DPoP cases: TypeScript agent ↔ TypeScript company over TLS, in the w assert.deepEqual(new Set(report.cases.map((item) => item.kind)), new Set(["positive", "negative", "recovery"])); }); +test("the pushed-requests cases: TypeScript agent ↔ TypeScript company over TLS, PAR required", async () => { + // Manzanita requires Pushed Authorization Requests and binds refresh tokens to their DPoP key + // (§4.2, §4.4, RFC 9126). + const world = "pushed-requests"; + const cases = companyCases(world); + assert.ok(cases.length >= 2); + const report = await runPairing({ config: worldConfig(world), cases }); + const reports = process.env.PAP_CONFORMANCE_REPORTS; + if (reports) { + mkdirSync(reports, { recursive: true }); + writeFileSync(join(reports, `typescript-agent-typescript-company.${world}.json`), `${JSON.stringify(report, null, 2)}\n`); + } + const failed = Object.fromEntries(report.cases.filter((item) => item.outcome === "failed").map((item) => [item.id, item.message])); + assert.deepEqual(failed, {}); + assert.deepEqual(report.summary, { passed: cases.length, failed: 0, skipped: 0 }); +}); + for (const world of ["operator-signatures", "operator-signatures-required"]) { test(`the operator cases: TypeScript agent ↔ TypeScript company over TLS, in ${world}`, async () => { const cases = companyCases(world); @@ -171,7 +191,7 @@ test("every case belongs to one world", () => { JSON.parse(readFileSync(new URL(`../../protocol/fixtures/conformance/${suite}.json`, import.meta.url), "utf8")) .cases.filter((item) => item.check === undefined), ); - const worlds = [undefined, "dpop-binding", "no-issuer", "operator-signatures", "operator-signatures-required"]; + const worlds = [undefined, "dpop-binding", "pushed-requests", "no-issuer", "operator-signatures", "operator-signatures-required"]; const selected = worlds.flatMap((world) => companyCases(world)).map((item) => item.id); assert.deepEqual(selected.sort(), fixtures.map((item) => item.id).sort()); }); diff --git a/src/__tests__/dpop.test.mjs b/src/__tests__/dpop.test.mjs index 9cc6ab3a..181e2a32 100644 --- a/src/__tests__/dpop.test.mjs +++ b/src/__tests__/dpop.test.mjs @@ -382,6 +382,7 @@ const baseConfig = { name: "Shop", domain: "shop.example", scopes: ["a:read"], + agentDescription: "Anything about your account", scopeDescriptions: { "a:read": "Read" }, operations: false, }; diff --git a/src/__tests__/draft-04.test.mjs b/src/__tests__/draft-04.test.mjs index 0696d9d1..02630925 100644 --- a/src/__tests__/draft-04.test.mjs +++ b/src/__tests__/draft-04.test.mjs @@ -135,6 +135,7 @@ test("the reference company offers Direct Sign-In", () => { name: "Bank", domain: "bank.example", scopes: ["accounts:read"], + agentDescription: "Anything about your account", scopeDescriptions: { "accounts:read": "See your accounts" }, operations: false, device: false, diff --git a/src/__tests__/draft-10.test.mjs b/src/__tests__/draft-10.test.mjs index 8fcfa177..56bf5b24 100644 --- a/src/__tests__/draft-10.test.mjs +++ b/src/__tests__/draft-10.test.mjs @@ -80,7 +80,7 @@ const hello = () => ({ id: `req_draft10_${String((requests += 1)).padStart(10, " // Protocol version 1.0, the default (§3.1, §3.4) -------------------------------------- test("the draft is the default and the published version is available", () => { - assert.deepEqual([PROTOCOL_PROFILE, DRAFT_PROTOCOL_VERSION, DRAFT_PROTOCOL_REVISION], ["0.4", "1.0", "2026-11-11"]); + assert.deepEqual([PROTOCOL_PROFILE, DRAFT_PROTOCOL_VERSION, DRAFT_PROTOCOL_REVISION], ["0.4", "1.0", "2026-11-14"]); assert.equal(DEFAULT_PROTOCOL_VERSION, DRAFT_PROTOCOL_VERSION); assert.deepEqual([...SUPPORTED_PROTOCOL_VERSIONS], ["1.0"]); assert.deepEqual([...AVAILABLE_PROTOCOL_VERSIONS].sort(), ["0.4", "1.0"]); diff --git a/src/__tests__/idempotency.test.mjs b/src/__tests__/idempotency.test.mjs index 9d44c0c2..8bf2e817 100644 --- a/src/__tests__/idempotency.test.mjs +++ b/src/__tests__/idempotency.test.mjs @@ -104,7 +104,7 @@ async function scripted(answer) { test("every write carries a random UUID v4, and a read none", async () => { assert.match(newIdempotencyKey(), UUID_V4); assert.equal( - new CompanyConfig({ name: "x", domain: "x.example", scopes: ["a"], scopeDescriptions: { a: "A" }, operations: false }).idempotencyLifetimeSeconds, + new CompanyConfig({ name: "x", domain: "x.example", scopes: ["a"], agentDescription: "Anything about your account", scopeDescriptions: { a: "A" }, operations: false }).idempotencyLifetimeSeconds, FIXTURE.default_lifetime_seconds, ); const s = await scripted(() => Response.json({ ok: true })); diff --git a/src/__tests__/issuerless.test.mjs b/src/__tests__/issuerless.test.mjs index 6f2a5813..3ecfebe9 100644 --- a/src/__tests__/issuerless.test.mjs +++ b/src/__tests__/issuerless.test.mjs @@ -18,7 +18,7 @@ const SIGNED_OUT = { protocol_version: "1.0", organization: { name: "Example", domain: "Example.COM" }, apis: [{ type: "openapi", url: "https://example.com/o.json", description: "Catalog" }], - agent: { protocols: [{ type: "poppy", endpoint: "https://example.com/poppy" }] }, + agent: { protocols: [{ type: "poppy", endpoint: "https://example.com/poppy", description: "Anything" }] }, feedback: { endpoint: "https://example.com/feedback" }, web: { browser_session_endpoint: "https://example.com/join" }, }; @@ -66,7 +66,7 @@ test("with an issuer the identifier is the issuer", async () => { for (const [name, offers] of [ ["auth.issuer", { auth: { issuer: "https://auth.example.com" } }], - ["access", { agent: { protocols: [{ type: "poppy", endpoint: "https://example.com/p", access: "signed_in" }] } }], + ["access", { agent: { protocols: [{ type: "poppy", endpoint: "https://example.com/p", description: "Anything", access: "signed_in" }] } }], ["mediated", { extensions: { "mediated-sign-in": [{ version: "2" }] } }], ]) { test(`no issuer is refused for a company that offers sign-in (${name})`, async () => { @@ -137,6 +137,7 @@ const config = (changes = {}) => name: "Shop", domain: "Shop.Example", scopes: ["orders:read"], + agentDescription: "Anything about your orders", scopeDescriptions: { "orders:read": "See your orders" }, oauth: false, operations: false, diff --git a/src/__tests__/operator-signatures.test.mjs b/src/__tests__/operator-signatures.test.mjs index 1000d049..7d180521 100644 --- a/src/__tests__/operator-signatures.test.mjs +++ b/src/__tests__/operator-signatures.test.mjs @@ -170,7 +170,7 @@ test("a signer refuses a Signature-Agent it cannot write", async () => { test("a company takes off, optional or required", () => { assert.throws( - () => new CompanyConfig({ domain: "shop.example", name: "Shop", scopes: ["orders:read"], operatorSignatures: "sometimes" }), + () => new CompanyConfig({ domain: "shop.example", name: "Shop", scopes: ["orders:read"], agentDescription: "Anything about your account", operatorSignatures: "sometimes" }), /operatorSignatures/, ); }); diff --git a/src/__tests__/published-10.test.mjs b/src/__tests__/published-10.test.mjs new file mode 100644 index 00000000..1c618300 --- /dev/null +++ b/src/__tests__/published-10.test.mjs @@ -0,0 +1,729 @@ +/* + * Copyright (c) 2025-2026 Datalayer, Inc. + * + * BSD 3-Clause License + */ + +// Version 1.0 as published (upstream 8c02b42, frozen 2026-11-14): what changed after the draft +// as of c71f515, both sides, in one process; the port of +// personal_agent_protocol/__tests__/test_published_10.py. +// +// Conversation protocol descriptions, Pushed Authorization Requests, minor versions, PS384, +// consent for scopes granted before, the same DPoP key at refresh, UCP scope requests, ports in +// `organization.domain`, client assertion lifetimes, one sign-in for every resource, clearing +// context, room to extend conversations, what `working` means, unknown sign-in errors, and the +// Mediated Sign-In retirement date. 0.4 as published is unchanged. +import assert from "node:assert/strict"; +import { constants, generateKeyPairSync, sign as nodeSign } from "node:crypto"; +import { readFileSync } from "node:fs"; +import test from "node:test"; + +import { exportJWK, generateKeyPair } from "jose"; + +import { + AuthorizationError, + ConversationClient, + ConversationError, + DirectSignInClient, + DeviceSignInClient, + DpopProvers, + KNOWN_CONVERSATION_ERRORS, + MEDIATED_RETIREMENT_DATE, + PROMPT_CONSENT, + PapSession, + ServiceTokens, + SessionClient, + UCP_IDENTITY_LINKING, + buildClientAssertionClaims, + buildDirectSignInRequest, + clearsContext, + delegationClaims, + discoverCompany, + effectiveContext, + firstContribution, + knownConversationError, + pageCarriesSession, + parseConversationEvent, + parseDiscoveryDocument, + parseMessage, + parseOAuthServerMetadata, + signInScopes, + splitDomain, + ucpScopes, + urlDomain, + listsResource, + verificationHostAllowed, +} from "../../lib/index.js"; +import { + ClientPolicies, + CompanyAgents, + CompanyConfig, + JoseSigner, + MemoryReplayCache, + RSA_KEY_BITS, + verifyAssertion, + verifyDelegation, +} from "../../lib/server.js"; +import { CONFIG, CONFIG_OPTIONS, manzanita } from "../../lib/demo/manzanita.js"; +import { Context, identityFrom } from "./support/conformance.mjs"; +import { SHOP, TENANT, mockTransport, rejection, shopWorld, signedIn } from "./support/shop.mjs"; +import { MutableClock, inProcessFetch } from "./support/world.mjs"; + +const AGENT = "https://atlas.example/agent.json"; +const REDIRECT = "https://atlas.example/oauth/callback"; +const scenario = JSON.parse(readFileSync(new URL("../../protocol/scenarios/manzanita-conformance.json", import.meta.url), "utf8")); + +const DOCUMENT = { + protocol_version: "1.0", + organization: { name: "Example", domain: "example.com" }, + agent: { + protocols: [ + { type: "poppy", endpoint: "https://example.com/poppy/conversations", description: "Anything about your orders" }, + ], + }, +}; +const entry = () => ({ type: "poppy", endpoint: "https://example.com/poppy/conversations" }); +const withoutDescription = (version) => ({ ...DOCUMENT, protocol_version: version, agent: { protocols: [entry()] } }); + +/** + * Atlas and Manzanita, configured by `config`; the user's browser opens only the company's pages + * and records every URL handed to it, the agent's own pages unopened. + */ +async function recordingWorld(config) { + const w = await shopWorld(config === undefined ? {} : { config }); + const browser = w.host.browser; + const open = browser.open.bind(browser); + browser.open = async (url) => { + if (url.reveal().startsWith(SHOP)) return open(url); + browser.urls.push(url.reveal()); + }; + return { w, browser }; +} + +function directArguments(w, more = {}) { + return { + authorizationEndpoint: w.metadata.authorization_endpoint, + tokenEndpoint: w.metadata.token_endpoint, + issuer: w.metadata.issuer, + clientId: w.identity.clientId, + redirectUri: REDIRECT, + scopes: ["orders:read"], + tenantId: TENANT, + ...more, + }; +} + +/** Manzanita in process, configured by `config`, and a conformance context of Atlas that signs in directly. */ +async function binding(config) { + const clock = new MutableClock(); + const sites = {}; + const fetch = inProcessFetch(sites); + const { service } = manzanita({ fetch, clock, ...(config === undefined ? {} : { config }) }); + sites["manzanita.example"] = service; + const pair = await generateKeyPair("ES256", { extractable: true }); + const atlas = await identityFrom({ domain: "atlas.example", name: "Atlas", privateJwk: await exportJWK(pair.privateKey) }); + sites[atlas.domain] = { "/agent.json": atlas.metadata, "/jwks.json": atlas.jwks }; + const driver = { + capabilities: new Set(["clock", "direct_sign_in"]), + accounts: ["acct_ada", "acct_ada_business"], + async approveAuthorization(url, { account, scopes }) { + const page = await (await fetch(url, { method: "GET" })).text(); + const requestId = page.split('name="request_id" value="')[1].split('"')[0]; + return service.approveAuthorization(requestId, { accountId: account, ...(scopes ? { scopes } : {}) }); + }, + async approveDevice(userCode, { account }) { + await service.approveDevice(userCode, { accountId: account }); + }, + async wait(seconds) { + clock.advance(seconds); + }, + }; + return new Context({ baseUrl: SHOP, identity: atlas, fetch, scenario, clock, driver }); +} + +async function signedInUser(ctx) { + const user = ctx.newUser(); + return ctx.signIn(user, await ctx.session(user)); +} + +const prover = (ctx) => firstContribution(ctx.agent.reactor, DpopProvers, "DPoP prover"); + +// Conversation protocol descriptions (§3.1, §8.1) ------------------------------------------ + +test("a 1.0 document needs a description for each conversation protocol", () => { + assert.equal(parseDiscoveryDocument(DOCUMENT).agent.protocols[0].description, "Anything about your orders"); + assert.throws(() => parseDiscoveryDocument(withoutDescription("1.0")), /description/); + assert.throws(() => parseDiscoveryDocument({ ...DOCUMENT, agent: { protocols: [{ ...entry(), description: "" }] } })); + // 0.4 doesn't define it: a 0.4 document without one is valid, as published. + assert.equal(parseDiscoveryDocument(withoutDescription("0.4")).agent.protocols[0].description, undefined); +}); + +test("the reference company describes its agent at 1.0 and not at 0.4", async () => { + const w = await shopWorld(); + const [described] = w.shop.discoveryDocument().agent.protocols; + assert.equal(described.description, CONFIG.agentDescription); + const both = await shopWorld({ config: { protocolVersions: ["1.0", "0.4"] } }); + assert.ok(!("description" in both.shop.discoveryDocument(undefined, "0.4").agent.protocols[0])); + assert.throws(() => new CompanyConfig({ ...CONFIG_OPTIONS, agentDescription: " " }), /agentDescription/); +}); + +// Pushed Authorization Requests (§3.2, §4.2, §4.8) ---------------------------------------- + +test("a company offers or requires PAR and the agent pushes", async () => { + const { w, browser } = await recordingWorld({ pushedAuthorizationRequests: "offered" }); + assert.equal(w.metadata.pushed_authorization_request_endpoint, `${SHOP}/oauth/par`); + assert.equal(w.metadata.require_pushed_authorization_requests, false); + const client = new DirectSignInClient({ reactor: w.reactor, fetch: w.fetch }); + await client.begin(directArguments(w, { pushedAuthorizationRequestEndpoint: w.metadata.pushed_authorization_request_endpoint })); + // The browser gets only client_id and request_uri (RFC 9126 §4). + const opened = new URL(browser.urls.at(-1)); + assert.deepEqual([...opened.searchParams.keys()].sort(), ["client_id", "request_uri"]); + assert.ok(opened.searchParams.get("request_uri").startsWith("urn:ietf:params:oauth:request_uri:")); + const callbackUrl = await w.shop.approveAuthorization(browser.requestId, { accountId: "acct_ada" }); + const done = await client.complete({ callbackUrl }); + assert.deepEqual(done.token.scopes, ["orders:read"]); + // A request_uri is used once. + assert.equal((await w.fetch(browser.urls.at(-1), { method: "GET" })).status, 400); +}); + +test("a company that requires PAR takes nothing else", async () => { + const { w, browser } = await recordingWorld({ pushedAuthorizationRequests: "required" }); + assert.equal(w.metadata.require_pushed_authorization_requests, true); + const client = new DirectSignInClient({ reactor: w.reactor, fetch: w.fetch }); + // Not pushed: the company's page refuses the request. + await client.begin(directArguments(w)); + assert.ok(browser.pages.at(-1).includes("not valid") && !browser.pages.at(-1).includes('name="request_id"')); + // A required push needs the endpoint, refused before anything is sent. + await assert.rejects(client.begin(directArguments(w, { requirePushedAuthorizationRequests: true })), /PAR/); + const raw = w.shop.oauthMetadata(); + assert.throws(() => parseOAuthServerMetadata({ ...raw, pushed_authorization_request_endpoint: undefined })); + // Pushed, the sign-in completes. + await client.begin( + directArguments(w, { + pushedAuthorizationRequestEndpoint: w.metadata.pushed_authorization_request_endpoint, + requirePushedAuthorizationRequests: true, + }), + ); + const callbackUrl = await w.shop.approveAuthorization(browser.requestId, { accountId: "acct_ada" }); + assert.ok((await client.complete({ callbackUrl })).token !== undefined); + // A push is checked as an authorization request: an unknown redirect is refused. + const sessions = new SessionClient({ reactor: w.reactor, fetch: w.fetch }); + const form = new URLSearchParams({ + response_type: "code", + client_id: w.identity.clientId, + redirect_uri: "https://elsewhere.example/cb", + scope: "orders:read", + code_challenge: "x".repeat(43), + code_challenge_method: "S256", + ...(await sessions.clientAuthentication({ clientId: w.identity.clientId, issuer: SHOP })), + }); + const refused = await w.fetch(`${SHOP}/oauth/par`, { + method: "POST", + headers: { "Content-Type": "application/x-www-form-urlencoded" }, + body: form.toString(), + }); + assert.deepEqual([refused.status, (await refused.json()).error], [400, "invalid_request"]); + assert.throws( + () => new CompanyConfig({ ...CONFIG_OPTIONS, ucp: false, pushedAuthorizationRequests: "offered", direct: false }), + /direct/, + ); +}); + +test("a link opened later goes to the agent's page, which pushes then", async () => { + const { w, browser } = await recordingWorld({ pushedAuthorizationRequests: "required" }); + const client = new DirectSignInClient({ reactor: w.reactor, fetch: w.fetch }); + await client.begin( + directArguments(w, { + pushedAuthorizationRequestEndpoint: w.metadata.pushed_authorization_request_endpoint, + requirePushedAuthorizationRequests: true, + crossDevice: true, + linkPage: "https://atlas.example/sign-in/{link}", + }), + ); + // The handoff got the agent's own page: nothing was pushed yet. + const linkUrl = browser.urls.at(-1); + assert.ok(linkUrl.startsWith("https://atlas.example/sign-in/")); + const link = linkUrl.split("/").at(-1); + // Opened much later: the page pushes now, so the request_uri is fresh. + w.clock.advance(120); + const authorizationUrl = await client.openLink(link); + assert.ok(authorizationUrl.reveal().includes("request_uri=")); + await browser.open(authorizationUrl); + const callbackUrl = await w.shop.approveAuthorization(browser.requestId, { accountId: "acct_ada" }); + assert.ok((await client.complete({ callbackUrl })).token !== undefined); + await assert.rejects(client.openLink(link), AuthorizationError); // the sign-in is done + await assert.rejects(client.openLink("unknown"), AuthorizationError); + await assert.rejects(client.begin(directArguments(w, { linkPage: "https://atlas.example/no-link" })), RangeError); +}); + +test("a push with a DPoP proof binds the code to its key", async () => { + const ctx = await binding({ dpopBinding: "required", pushedAuthorizationRequests: "required" }); + const metadata = await ctx.metadata(); + assert.equal(metadata.require_pushed_authorization_requests, true); + const signed = await signedInUser(ctx); // the conformance agent pushes, with a proof + assert.equal(signed.token.tokenType, "DPoP"); + // Pushed with one key, exchanged with another: the code is bound to the first. + const user = ctx.newUser(); + const session = await ctx.session(user); + const client = new DirectSignInClient({ reactor: ctx.agent.reactor, fetch: ctx.fetch }); + await client.begin({ + authorizationEndpoint: metadata.authorization_endpoint, + tokenEndpoint: metadata.token_endpoint, + issuer: metadata.issuer, + clientId: ctx.agent.identity.clientId, + redirectUri: ctx.agent.identity.metadata.redirect_uris[0], + scopes: scenario.scopes, + tenantId: ctx.tenantId, + dpopSigningAlgs: metadata.dpop_signing_alg_values_supported, + pairwiseUserId: session.sub, + pushedAuthorizationRequestEndpoint: metadata.pushed_authorization_request_endpoint, + requirePushedAuthorizationRequests: true, + }); + const callbackUrl = await ctx.driver.approveAuthorization(ctx.agent.userBrowser.urls.at(-1), { account: ctx.driver.accounts[0] }); + await prover(ctx).keys.forget({ tenantId: ctx.tenantId, issuer: metadata.issuer, sub: session.sub }); + const refused = await rejection(client.complete({ callbackUrl })); + assert.equal(refused.code, "invalid_grant"); +}); + +// Minor versions (§3.4) -------------------------------------------------------------------- + +test("nothing of 1.0 goes into a 0.4 exchange", async () => { + // A 0.4 document has no description, and a 0.4 Session sends no `null` context. + const w = await shopWorld(); + const { service: published } = manzanita({ fetch: w.fetch, clock: w.clock, config: { protocolVersions: ["0.4"] } }); + const document = published.discoveryDocument(); + assert.equal(document.protocol_version, "0.4"); + assert.ok(document.agent.protocols.every((item) => !("description" in item))); + const sent = []; + const transport = mockTransport(w, async (_url, init) => { + sent.push(JSON.parse(init.body)); + throw new TypeError("not sent further"); + }); + const conversations = new ConversationClient({ reactor: w.reactor, transport }); + const session = (protocolVersion) => + new PapSession({ sid: `sid_${"a".repeat(22)}`, sub: "u", issuer: SHOP, clientId: AGENT, tenantId: TENANT, protocolVersion }); + const clearing = { id: "req_clear_0000000000000000", author: { type: "agent" }, context: { locale: null } }; + assert.ok(clearsContext(clearing)); + const refused = await rejection(conversations.start(`${SHOP}/poppy/conversations`, clearing, { session: session("0.4") })); + assert.equal(refused.code, "context_clear_unsupported"); + assert.equal(sent.length, 0); + await rejection(conversations.start(`${SHOP}/poppy/conversations`, clearing, { session: session("1.0") })); + assert.deepEqual(sent.at(-1).message.context, { locale: null }); +}); + +// PS384 required, RSA 2048 to 4096 bits (§4.1, §5.2, §10.7) -------------------------------- + +const rsaJwks = (jwk, kid) => ({ keys: [{ ...jwk, kid, alg: "PS384" }] }); +const NOW = new Date("2026-11-17T09:00:00Z"); + +/** A client assertion signed by `privateKey`, lasting `lifetime` seconds. */ +async function assertion(privateKey, { lifetime = 60 } = {}) { + const claims = buildClientAssertionClaims({ clientId: AGENT, issuer: SHOP, now: NOW, lifetimeSeconds: Math.min(lifetime, 300) }); + const signer = new JoseSigner({ privateKey, algorithm: "PS384", keyId: "k" }); + return (await signer.sign({ ...claims, exp: claims.iat + lifetime }, { purpose: "client_assertion" })).reveal(); +} + +for (const bits of [2048, 3072, 4096]) { + test(`companies accept PS384 assertions and delegations (${bits} bits)`, async () => { + const { privateKey, publicKey } = await generateKeyPair("PS384", { modulusLength: bits, extractable: true }); + const keys = rsaJwks(await exportJWK(publicKey), "k"); + const claims = await verifyAssertion(await assertion(privateKey), { + keys, + issuer: AGENT, + subject: AGENT, + audience: SHOP, + replayCache: new MemoryReplayCache(), + now: NOW, + }); + assert.equal(claims.aud, SHOP); + const delegated = await generateKeyPair("ES256", { extractable: true }); + const { d: _d, ...publicJwk } = await exportJWK(delegated.privateKey); + const signer = new JoseSigner({ privateKey, algorithm: "PS384", keyId: "k" }); + const delegation = await signer.sign( + delegationClaims({ clientId: AGENT, publicKey: publicJwk, issuedAt: NOW, lifetimeSeconds: 3600 }), + { purpose: "delegation" }, + ); + const verified = await verifyDelegation(delegation.reveal(), { + clientId: AGENT, + resolve: async () => [undefined, keys], + now: NOW, + }); + assert.equal(verified.clientId, AGENT); + }); +} + +test("an RSA key outside 2048 to 4096 bits is refused", async () => { + assert.deepEqual([...RSA_KEY_BITS], [2048, 4096]); + // Signed by hand: jose refuses to sign with a key this weak, as it should. + const weak = generateKeyPairSync("rsa", { modulusLength: 1024 }); + const claims = buildClientAssertionClaims({ clientId: AGENT, issuer: SHOP, now: NOW, lifetimeSeconds: 60 }); + const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url"); + const input = `${encode({ alg: "PS384", typ: "JWT", kid: "k" })}.${encode(claims)}`; + const signature = nodeSign("sha384", Buffer.from(input), { + key: weak.privateKey, + padding: constants.RSA_PKCS1_PSS_PADDING, + saltLength: 48, + }); + const refused = await rejection( + verifyAssertion(`${input}.${signature.toString("base64url")}`, { + keys: rsaJwks(weak.publicKey.export({ format: "jwk" }), "k"), + issuer: AGENT, + audience: SHOP, + replayCache: new MemoryReplayCache(), + now: NOW, + }), + ); + assert.equal(refused.code, "invalid_client"); +}); + +// Client assertion lifetime (§4.1) --------------------------------------------------------- + +test("an assertion lasts at most five minutes, and one that does is accepted", async () => { + assert.throws(() => buildClientAssertionClaims({ clientId: AGENT, issuer: SHOP, lifetimeSeconds: 301 })); + const { privateKey, publicKey } = await generateKeyPair("PS384", { modulusLength: 2048, extractable: true }); + const keys = rsaJwks(await exportJWK(publicKey), "k"); + for (const [lifetime, accepted] of [[300, true], [301, false]]) { + const verify = verifyAssertion(await assertion(privateKey, { lifetime }), { + keys, + issuer: AGENT, + audience: SHOP, + replayCache: new MemoryReplayCache(), + now: NOW, + }); + if (accepted) await verify; + else await assert.rejects(verify, (error) => error.code === "invalid_client"); + } +}); + +// Consent for scopes granted before (§4.2, §4.3, §10.8) ------------------------------------ + +test("a direct sign-in asks for consent unless the redirect stays on the device", async () => { + const options = { + authorizationEndpoint: `${SHOP}/oauth/authorize?prompt=none`, + issuer: SHOP, + clientId: AGENT, + redirectUri: REDIRECT, + scopes: ["orders:read"], + }; + const query = new URL((await buildDirectSignInRequest(options)).authorizationUrl.reveal()).searchParams; + assert.deepEqual(query.getAll("prompt"), [PROMPT_CONSENT]); + assert.equal(PROMPT_CONSENT, "consent"); + assert.ok(!query.has("resource")); // one sign-in for every resource (§4.5) + const sameDevice = await buildDirectSignInRequest({ ...options, promptConsent: false }); + assert.ok(!new URL(sameDevice.authorizationUrl.reveal()).searchParams.has("prompt")); +}); + +test("the consent page lists every scope and marks the earlier ones", async () => { + const w = await shopWorld(); + const begin = async (scopes) => { + const client = new DirectSignInClient({ reactor: w.reactor, fetch: w.fetch }); + await client.begin(directArguments(w, { scopes })); + return client; + }; + const client = await begin(["orders:read"]); + const callbackUrl = await w.shop.approveAuthorization(w.host.browser.requestId, { accountId: "acct_ada" }); + await client.complete({ callbackUrl }); + // Every scope again, the earlier one included: the page is shown all the same. + await begin(["orders:read", "orders:write"]); + const shown = w.host.browser.pages.at(-1); + assert.ok(shown.includes('name="request_id"') && shown.includes("See your orders")); + const requestId = w.host.browser.requestId; + const summary = await w.shop.authorizationRequest(requestId, { accountId: "acct_ada" }); + assert.equal(summary.prompt, "consent"); + assert.deepEqual( + summary.scopes.map((item) => [item.scope, item.granted_before]), + [ + ["orders:read", true], + ["orders:write", false], + ], + ); + const unmarked = await w.shop.authorizationRequest(requestId); + assert.ok(unmarked.scopes.every((item) => !("granted_before" in item))); + // Another account granted nothing. + const other = await w.shop.authorizationRequest(requestId, { accountId: "acct_bob" }); + assert.ok(!other.scopes.some((item) => item.granted_before)); +}); + +test("every device sign-in shows its page with the earlier scopes marked", async () => { + const w = await shopWorld(); + await signedIn(w, ["orders:read"]); + const started = await new DeviceSignInClient({ reactor: w.reactor, fetch: w.fetch }).begin({ + deviceAuthorizationEndpoint: w.metadata.device_authorization_endpoint, + tokenEndpoint: w.metadata.token_endpoint, + issuer: w.metadata.issuer, + clientId: w.identity.clientId, + scopes: ["orders:read", "orders:write"], + tenantId: TENANT, + organization: w.company.document.organization, + }); + const shown = await w.shop.deviceRequest(started.userCode, { accountId: "acct_ada" }); + assert.deepEqual( + shown.scopes.map((item) => [item.scope, item.granted_before]), + [ + ["orders:read", true], + ["orders:write", false], + ], + ); +}); + +// Same DPoP key at refresh (§4.4, §4.5, §10.7) --------------------------------------------- + +test("a bound refresh token refreshes only with its key", async () => { + assert.throws(() => new CompanyConfig({ ...CONFIG_OPTIONS, bindRefreshTokens: true }), /bindRefreshTokens/); + const ctx = await binding({ dpopBinding: "required", bindRefreshTokens: true }); + const signed = await signedInUser(ctx); + const context = await ctx.accountContext(signed.session.sub); + // The same key, twice: the rotated token stays bound to it. + for (let turn = 0; turn < 2; turn += 1) { + const refreshed = await ctx.agent.accounts.refresh(signed.reference, { context }); + assert.ok(refreshed.status === "signed_in" && refreshed.rotated); + } + const metadata = await ctx.metadata(); + await prover(ctx).keys.forget({ tenantId: ctx.tenantId, issuer: metadata.issuer, sub: signed.session.sub }); + // Another key: invalid_grant, so the copy is useless and the agent signs in again. + const lost = await ctx.agent.accounts.refresh(signed.reference, { context }); + assert.equal(lost.status, "signed_out"); +}); + +test("without binding a refresh with a new key still works", async () => { + const ctx = await binding({ dpopBinding: "required" }); + const signed = await signedInUser(ctx); + const metadata = await ctx.metadata(); + await prover(ctx).keys.forget({ tenantId: ctx.tenantId, issuer: metadata.issuer, sub: signed.session.sub }); + const context = await ctx.accountContext(signed.session.sub); + assert.equal((await ctx.agent.accounts.refresh(signed.reference, { context })).status, "signed_in"); + assert.ok(ctx.url(scenario.read_path).startsWith("https://")); +}); + +// UCP scope requests name every scope (UCP 4, 11) ------------------------------------------ + +test("a UCP sign-in requests every scope and gets only those", async () => { + const held = ["orders:write"]; + const needed = ["orders:read"]; + const profile = { capabilities: { [UCP_IDENTITY_LINKING]: [{ config: { scopes: { "orders:read": {} } } }] } }; + assert.deepEqual(ucpScopes(profile, held, { needed }), ["orders:write", "orders:read"]); + assert.deepEqual(ucpScopes(profile, held), ["orders:write", "orders:read"]); + // 0.4 kept UCP's incremental authorization: only the missing scopes. + assert.deepEqual(ucpScopes(profile, held, { needed, protocolVersion: "0.4" }), ["orders:read"]); + // The company grants only the scopes a sign-in names, whatever was granted before. + const w = await shopWorld(); + await signedIn(w, ["orders:read", "orders:write"]); + const narrower = await signedIn(w, ["orders:read"]); + assert.deepEqual(narrower.token.scopes, ["orders:read"]); +}); + +// Ports in organization.domain (§3.1, §3.2) ------------------------------------------------ + +test("a domain names its port when that isn't 443, from 1.0 only", () => { + assert.deepEqual(splitDomain("shop.example:8443"), ["shop.example", 8443]); + const organization = (domain) => parseDiscoveryDocument({ ...DOCUMENT, organization: { name: "Shop", domain } }).organization; + assert.equal(organization("Shop.Example:8443").domain, "shop.example:8443"); + for (const invalid of ["shop.example:443", "shop.example:0", "shop.example:99999", "x.example:y"]) { + assert.throws(() => organization(invalid), invalid); + } + const onAPort = { ...DOCUMENT, organization: { name: "Shop", domain: "shop.example:8443" } }; + assert.equal(parseDiscoveryDocument(onAPort).organization.domain, "shop.example:8443"); + assert.throws(() => parseDiscoveryDocument({ ...onAPort, protocol_version: "0.4" }), /port/); + assert.equal(urlDomain("https://shop.example:8443/x"), "shop.example:8443"); + assert.equal(urlDomain("https://shop.example:443/x"), "shop.example"); + assert.ok(pageCarriesSession("https://shop.example:8443/page", "shop.example:8443")); + assert.ok(!pageCarriesSession("https://shop.example/page", "shop.example:8443")); + assert.ok(verificationHostAllowed("https://shop.example/device", { issuer: "https://auth.example", domain: "shop.example:8443" })); + const metadata = parseOAuthServerMetadata({ + issuer: "https://shop.example:8443", + token_endpoint: "https://shop.example:8443/oauth/token", + revocation_endpoint: "https://shop.example:8443/oauth/revoke", + grant_types_supported: ["refresh_token"], + protected_resources: ["https://shop.example:8443"], + }); + assert.ok(listsResource(metadata, "shop.example:8443")); + assert.ok(!listsResource(metadata, "shop.example")); + // A company serves a domain with a port at 1.0 only. + new CompanyConfig({ ...CONFIG_OPTIONS, domain: "manzanita.example:8443" }); + assert.throws( + () => new CompanyConfig({ ...CONFIG_OPTIONS, domain: "manzanita.example:8443", protocolVersions: ["1.0", "0.4"] }), + /port/, + ); +}); + +/** A network answering a company on shop.example:8443, whose poppy.json names `organization`. */ +function portNetwork(organization) { + const base = "https://shop.example:8443"; + const answers = { + [`${base}/.well-known/poppy.json`]: { + ...DOCUMENT, + organization: { name: "Shop", domain: organization }, + agent: { protocols: [{ ...entry(), endpoint: `${base}/poppy`, description: "All" }] }, + }, + [`${base}/.well-known/oauth-protected-resource`]: { resource: base, authorization_servers: [base] }, + [`${base}/.well-known/oauth-authorization-server`]: { + issuer: base, + token_endpoint: `${base}/oauth/token`, + revocation_endpoint: `${base}/oauth/revoke`, + grant_types_supported: ["refresh_token"], + protected_resources: [base], + }, + }; + return async (input) => { + const body = answers[String(input)]; + return new Response(JSON.stringify(body ?? { error: "not_found" }), { + status: body ? 200 : 404, + headers: { "content-type": "application/json" }, + }); + }; +} + +test("an agent uses a company on another port only when configured to", async () => { + const fetch = portNetwork("shop.example:8443"); + await assert.rejects(discoverCompany("shop.example:8443", { fetch }), (error) => error.code === "port_not_allowed"); + const company = await discoverCompany("shop.example:8443", { fetch, allowPorts: true }); + assert.equal(company.document.organization.domain, "shop.example:8443"); + // A document on shop.example:8443 speaks for shop.example:8443, not shop.example. + await assert.rejects( + discoverCompany("shop.example:8443", { fetch: portNetwork("shop.example"), allowPorts: true }), + (error) => error.code === "organization_domain_mismatch", + ); +}); + +// One sign-in for every resource (§4.5, §4.7, §4.8, §7) ------------------------------------ + +test("a service left out is invalid_target and used signed out", async () => { + const w = await shopWorld(); + const { reference } = await signedIn(w); + const mcp = `${SHOP}/mcp`; + // Signed in with no resource: a token for the MCP server, added or not. + const result = await w.accounts.refresh(reference, { context: w.context, resource: mcp }); + assert.equal(result.status, "signed_in"); + assert.equal(result.token.resource, mcp); + // The client policy leaves the MCP server out for this agent (`allowsResource`). + const policy = firstContribution(w.shop.reactor, ClientPolicies, "policy"); + policy.allowsResource = async (_clientId, resource) => resource !== mcp; + const refused = await rejection(w.accounts.refresh(reference, { context: w.context, resource: mcp })); + assert.ok(refused instanceof AuthorizationError); + assert.equal(refused.code, "invalid_target"); + // The default token still comes; the agent uses the server signed out. + assert.equal((await w.accounts.refresh(reference, { context: w.context })).status, "signed_in"); + const tokens = new ServiceTokens({ + refresh: w.accounts, + reference, + context: w.context, + company: w.company, + discovery: { reactor: w.reactor }, + }); + assert.equal(await tokens.tokenFor(mcp), undefined); + assert.ok((await tokens.tokenFor(SHOP)) !== undefined); +}); + +// Clearing context, room to extend conversations (§8.4, §8.6, §8.13) ----------------------- + +test("null clears a context field as if never shared", () => { + const messages = [ + { locale: "fr", time_zone: "Europe/Paris" }, + { user_available: true }, + { locale: null }, + ].map((context) => parseMessage({ author: { type: "agent" }, context })); + assert.deepEqual(effectiveContext(messages), { time_zone: "Europe/Paris", user_available: true }); +}); + +test("the company agent sees the context cleared", async () => { + const w = await shopWorld(); + const { session, token } = await signedIn(w); + const seen = []; + const agent = firstContribution(w.shop.reactor, CompanyAgents, "company agent"); + const original = agent.respond.bind(agent); + agent.respond = async (turn) => { + seen.push({ ...turn.context }); + return original(turn); + }; + const message = (text, context) => ({ id: w.conversations.generateRequestId(), author: { type: "agent" }, text, context }); + const started = await w.conversations.start(w.endpoint, message("Hello", { locale: "fr" }), { session, token, wait: 5 }); + await w.conversations.send(w.endpoint, started.conversation_id, message("Again", { locale: null }), { session, token, wait: 5 }); + assert.deepEqual(seen, [{ locale: "fr" }, {}]); +}); + +test("unknown roles and author types are read safely", () => { + const message = parseMessage({ author: { type: "organization" }, role: "system", text: "Hi" }); + assert.deepEqual([message.role, message.author.type], ["company", "agent"]); +}); + +test("the company ignores author fields on the agent's messages", async () => { + const w = await shopWorld(); + const session = await w.start(); + const body = { + id: `req_${"a".repeat(22)}`, + message: { author: { type: "agent", id: "pretend", name: "Support", image: `${SHOP}/i` }, text: "Hello" }, + }; + const response = await w.transport.request("POST", w.endpoint, { + session, + headers: { "Content-Type": "application/json" }, + body: JSON.stringify(body), + }); + assert.equal(response.status, 201); + const page = await w.conversations.readEvents(w.endpoint, (await response.json()).conversation_id, { session }); + assert.deepEqual(page.events[0].message.author, { type: "agent" }); +}); + +test("a stream skips event names it doesn't know", async () => { + const w = await shopWorld(); + const session = await w.start(); + const state = { id: "evt_1", type: "state", created_at: "2026-11-17T09:00:00Z", handoff: "none", responder: "agent", closed: true }; + const lines = + 'event: working\ndata: {"working":true}\n\n' + + 'event: future-thing\ndata: {"anything":1}\n\n' + + `id: evt_1\ndata: ${JSON.stringify(state)}\n\n`; + const transport = mockTransport(w, async () => new Response(lines, { status: 200, headers: { "content-type": "text/event-stream" } })); + const conversations = new ConversationClient({ reactor: w.reactor, transport }); + const items = []; + for await (const item of conversations.stream(`${SHOP}/poppy`, "cnv_1", { session })) items.push(item); + assert.deepEqual( + items.map((item) => item.kind ?? item.type), + ["working", "state"], + ); +}); + +test("an unknown error code is handled by its HTTP status", async () => { + assert.equal(knownConversationError("conversation_closed"), "conversation_closed"); + assert.equal(knownConversationError("stronger_sign_in_needed"), "conversation_request_failed"); + assert.ok(KNOWN_CONVERSATION_ERRORS.has("conversation_closed")); + const w = await shopWorld(); + const session = await w.start(); + const transport = mockTransport( + w, + async () => new Response(JSON.stringify({ error: "something_new" }), { status: 409, headers: { "content-type": "application/json" } }), + ); + const refused = await rejection(new ConversationClient({ reactor: w.reactor, transport }).readEvents(`${SHOP}/poppy`, "cnv_1", { session })); + assert.ok(refused instanceof ConversationError); + assert.deepEqual([refused.code, refused.statusCode, refused.details], ["conversation_request_failed", 409, { error: "something_new" }]); +}); + +// What working means, unknown sign-in errors (§8.7, §8.11) --------------------------------- + +test("working is false once the reply is written", async () => { + const w = await shopWorld(); + const { session, token } = await signedIn(w); + const page = await w.conversations.start( + w.endpoint, + { id: w.conversations.generateRequestId(), author: { type: "agent" }, text: "Exchange my jacket for a size L" }, + { session, token, wait: 5 }, + ); + // The reply proposes an exchange the User has yet to approve: not `working`. + assert.equal(page.working ?? false, false); +}); + +test("an unknown authorization error signs in again for its scopes", () => { + const event = parseConversationEvent({ + id: "evt_1", + type: "authorization", + created_at: "2026-11-17T09:00:00Z", + error: "stronger_sign_in", + scope: "orders:read orders:write orders:read", + }); + assert.equal(event.error, "stronger_sign_in"); + assert.deepEqual([...signInScopes(event)], ["orders:read", "orders:write"]); +}); + +// Mediated Sign-In retirement date --------------------------------------------------------- + +test("Mediated Sign-In is retired on 17 March 2027", () => { + assert.equal(MEDIATED_RETIREMENT_DATE, "2027-03-17"); +}); diff --git a/src/__tests__/reactor-points.test.mjs b/src/__tests__/reactor-points.test.mjs index 48202ee0..10567fd9 100644 --- a/src/__tests__/reactor-points.test.mjs +++ b/src/__tests__/reactor-points.test.mjs @@ -45,7 +45,7 @@ const pointOf = (entry) => (entry.role === "company" ? server : portable)[entry. function reactorFor(entry, plugins = []) { if (entry.role === "company") { - const config = new server.CompanyConfig({ name: "Points", domain: "points.example", scopes: ["a:read"], scopeDescriptions: { "a:read": "Read" }, operations: false }); + const config = new server.CompanyConfig({ name: "Points", domain: "points.example", scopes: ["a:read"], agentDescription: "Anything about your account", scopeDescriptions: { "a:read": "Read" }, operations: false }); return server.buildCompany(config, { plugins }).reactor; } return portable.buildPapReactor({}, plugins); diff --git a/src/__tests__/schemas.test.mjs b/src/__tests__/schemas.test.mjs index d0049c64..e2b641c3 100644 --- a/src/__tests__/schemas.test.mjs +++ b/src/__tests__/schemas.test.mjs @@ -57,7 +57,11 @@ test("the schemas refuse what they should", () => { test("each positive discovery case is valid by the upstream schema", () => { const cases = read("fixtures/conformance/protocol.json").cases.filter( - (item) => item.check === "discovery_document" && item.kind === "positive", + // The schemas are 1.0's: a 0.4 document is checked by the SDK alone. + (item) => + item.check === "discovery_document" && + item.kind === "positive" && + !String(item.input.protocol_version ?? "").startsWith("0."), ); assert.ok(cases.length > 0); for (const item of cases) assert.deepEqual(errors("poppy", item.input), [], item.id); diff --git a/src/__tests__/security-review.test.mjs b/src/__tests__/security-review.test.mjs index 2a8311e3..d1c33864 100644 --- a/src/__tests__/security-review.test.mjs +++ b/src/__tests__/security-review.test.mjs @@ -220,14 +220,14 @@ test("finding 3: a retried start answers only who may read the conversation", as test("finding 5: operations without a write scope is a configuration error", () => { assert.throws( - () => new CompanyConfig({ name: "Shop", domain: "shop.example", scopes: ["orders:read"], scopeDescriptions: { "orders:read": "See orders" } }), + () => new CompanyConfig({ name: "Shop", domain: "shop.example", agentDescription: "Anything about your account", scopes: ["orders:read"], scopeDescriptions: { "orders:read": "See orders" } }), /writeScopes/, ); assert.throws( - () => new CompanyConfig({ name: "Shop", domain: "shop.example", scopes: ["a:read"], writeScopes: ["a:write"], scopeDescriptions: { "a:read": "Read" } }), + () => new CompanyConfig({ name: "Shop", domain: "shop.example", agentDescription: "Anything about your account", scopes: ["a:read"], writeScopes: ["a:write"], scopeDescriptions: { "a:read": "Read" } }), /among scopes/, ); - new CompanyConfig({ name: "Shop", domain: "shop.example", scopes: ["orders:read"], scopeDescriptions: { "orders:read": "See orders" }, operations: false }); + new CompanyConfig({ name: "Shop", domain: "shop.example", agentDescription: "Anything about your account", scopes: ["orders:read"], scopeDescriptions: { "orders:read": "See orders" }, operations: false }); }); test("finding 5: an operation records and requires its scopes", async () => { @@ -564,7 +564,7 @@ test("finding 12: the Node company fetches over the resolving transport by defau const { hostname } = await import("node:os"); const { DiscoveryTransports } = await import("../../lib/index.js"); const { buildCompany } = await import("../../lib/server.js"); - const service = buildCompany(new CompanyConfig({ name: "Shop", domain: "shop.example", scopes: ["a:read"], scopeDescriptions: { "a:read": "Read" }, operations: false })); + const service = buildCompany(new CompanyConfig({ name: "Shop", domain: "shop.example", agentDescription: "Anything about your account", scopes: ["a:read"], scopeDescriptions: { "a:read": "Read" }, operations: false })); const transport = firstContribution(service.reactor, DiscoveryTransports, "transport"); // This machine's own name resolves (through /etc/hosts) to a loopback or private address. await assert.rejects(transport.fetch(new URL(`https://${hostname()}/agent.json`), {}), (error) => ["unsafe_address", "dns_failed"].includes(error.code)); diff --git a/src/__tests__/support/conformance.mjs b/src/__tests__/support/conformance.mjs index c092d2ef..3984dc01 100644 --- a/src/__tests__/support/conformance.mjs +++ b/src/__tests__/support/conformance.mjs @@ -67,6 +67,7 @@ import { TokenStores, TransportError, approvalHeader, + buildDirectSignInRequest, buildPapReactor, challengeParameters, companyIdentifier, @@ -80,6 +81,7 @@ import { tasksEndpoint, parseTasksResponse, parseApprovalDeclined, + parseVersion, usableSkills, operationShown, newApprovalReference, @@ -489,6 +491,9 @@ export class Context { tenantId: this.tenantId, dpopSigningAlgs: metadata.dpop_signing_alg_values_supported, pairwiseUserId: session.sub, + // Pushed whenever the issuer takes PAR, as 1.0 asks (§4.2, RFC 9126). + pushedAuthorizationRequestEndpoint: metadata.pushed_authorization_request_endpoint, + requirePushedAuthorizationRequests: metadata.require_pushed_authorization_requests, }); const callbackUrl = await this.driver.approveAuthorization(actor.userBrowser.urls.at(-1), { account: account ?? this.driver.accounts[0], @@ -2042,6 +2047,26 @@ caseFor("protocol.version-unserved")(async (ctx) => { await expectRefusal(response, 400, "version_unsupported", "an unserved Poppy-Version"); }); +caseFor("protocol.agent-protocols-described")(async (ctx) => { + // At 1.0 each conversation protocol says what its agent helps with (§3.1, §8.1). + const company = await ctx.company(); + if (parseVersion(company.document.protocol_version)[0] < 1) throw new SkipCase("0.4 defines no description"); + const raw = await (await ctx.send("GET", company.discoveryUrl)).json(); + const entries = raw.agent?.protocols ?? []; + if (!entries.length) throw new SkipCase("the company lists no conversation protocol"); + for (const entry of entries) { + check(typeof entry.description === "string" && entry.description.length > 0, "every entry has a description"); + } + for (const [version, url] of Object.entries(raw.supported_versions ?? {})) { + if (parseVersion(version)[0] < 1) { + const document = await (await ctx.send("GET", url)).json(); + for (const entry of document.agent?.protocols ?? []) { + check(!("description" in entry), `${version}: nothing 1.0 adds (§3.4)`); + } + } + } +}); + caseFor("protocol.supported-versions-published")(async (ctx) => { const company = await ctx.company(); const preferred = await (await ctx.send("GET", company.discoveryUrl)).json(); @@ -2669,6 +2694,60 @@ caseFor("dpop.refresh-after-the-key-is-lost")(async (ctx) => { await proofRefused(stale, "the token of the lost key"); }); +caseFor("dpop.refresh-bound-to-its-key")(async (ctx) => { + // The agent refreshes with the key it signed in with (§4.4); a company that binds refresh + // tokens refuses another key, rotated tokens included. + const [signed, url] = await boundUser(ctx); + const context = await ctx.accountContext(signed.session.sub); + let refreshed; + for (const turn of ["first", "second"]) { + refreshed = await ctx.agent.accounts.refresh(signed.reference, { context }); + check(refreshed.status === "signed_in", `the ${turn} refresh with the same key works`); + } + const answer = await ctx.agent.transport.request("GET", url, { session: signed.session, token: refreshed.token }); + check(answer.status === 200, `its token works, got ${answer.status}`); + const metadata = await ctx.metadata(); + await prover(ctx).keys.forget({ tenantId: ctx.tenantId, issuer: metadata.issuer, sub: signed.session.sub }); + const lost = await ctx.agent.accounts.refresh(signed.reference, { context }); + check(lost.status === "signed_out", "a refresh with another key is invalid_grant"); + const again = await ctx.signIn(signed.session.sub, signed.session); + check(again.token.tokenType === "DPoP", "and the agent signs in again"); +}); + +caseFor("dpop.pushed-authorization-request")(async (ctx) => { + // Pushed Authorization Requests, required (§3.2, §4.2, RFC 9126). + const metadata = await ctx.metadata(); + if (metadata.pushed_authorization_request_endpoint === undefined) { + throw new SkipCase("the company takes no Pushed Authorization Requests"); + } + check(offersDirect(metadata), "PAR is for Direct Sign-In"); + if (!metadata.require_pushed_authorization_requests) throw new SkipCase("the company offers PAR without requiring it"); + if (!ctx.driver.capabilities.has("direct_sign_in")) { + throw new SkipCase("the driver can't play the user on the company's consent page"); + } + await signedInUser(ctx); // pushed, as the SDK does when it's offered + const opened = new URL(ctx.agent.userBrowser.urls.at(-1)); + const names = new Set(opened.searchParams.keys()); + check( + names.size === 2 && names.has("client_id") && names.has("request_uri"), + `only client_id and request_uri, got ${[...names].join(", ")}`, + ); + const request = await buildDirectSignInRequest({ + authorizationEndpoint: metadata.authorization_endpoint, + issuer: metadata.issuer, + clientId: ctx.agent.identity.clientId, + redirectUri: ctx.agent.identity.metadata.redirect_uris[0], + scopes: ctx.scenario.scopes, + }); + const unpushed = await ctx.send("GET", request.authorizationUrl.reveal()); + const location = unpushed.headers.get("location") ?? ""; + check( + unpushed.status >= 400 || !location.includes("code="), + `a request that wasn't pushed is refused, got ${unpushed.status}`, + ); + check(!(await textOf(unpushed)).includes("request_id"), "no consent page for it"); +}); + caseFor("dpop.conversation-and-stream")(async (ctx) => { const [signed] = await boundUser(ctx); const endpoint = await ctx.conversationsEndpoint(); @@ -2894,7 +2973,7 @@ caseFor("no-issuer.sign-in-offered-without-issuer")(async (ctx, fixture) => { const endpoint = await ctx.conversationsEndpoint(); for (const offers of [ { auth: { issuer: ctx.baseUrl } }, - { agent: { protocols: [{ type: "poppy", endpoint, access: "signed_in" }] } }, + { agent: { protocols: [{ type: "poppy", endpoint, description: "Anything about your account", access: "signed_in" }] } }, { extensions: { "mediated-sign-in": [{ version: "1" }] } }, ]) { const answer = jsonAnswer(200, { ...company.document, ...offers }); diff --git a/src/__tests__/ucp.test.mjs b/src/__tests__/ucp.test.mjs index 2348d644..4ba123c5 100644 --- a/src/__tests__/ucp.test.mjs +++ b/src/__tests__/ucp.test.mjs @@ -97,7 +97,9 @@ test("a company that speaks UCP lists it and serves its profile on its domain", assert.deepEqual(ucpIdentityLinkingScopes(profile), ["orders:read"]); for (const scope of ucpIdentityLinkingScopes(profile)) assert.ok(w.company.oauthMetadata.scopes_supported.includes(scope)); assert.ok(w.shop.oauthMetadata().token_endpoint_auth_methods_supported.includes("private_key_jwt")); - assert.deepEqual(ucpScopes(profile, ["orders:read"]), []); + // From 1.0 a sign-in names every scope it still needs (spec 4.7); 0.4 asked only for the missing. + assert.deepEqual(ucpScopes(profile, ["orders:read"]), ["orders:read"]); + assert.deepEqual(ucpScopes(profile, ["orders:read"], { protocolVersion: "0.4" }), []); const plain = await world(new CompanyConfig({ ...CONFIG_OPTIONS, ucp: false })); assert.ok(!speaksUcp(plain.company.document)); await assert.rejects(fetchUcpProfile(plain.company, { fetch: plain.fetch }), (error) => error.code === "ucp_not_offered"); diff --git a/src/accounts.ts b/src/accounts.ts index 65209673..eece2889 100644 --- a/src/accounts.ts +++ b/src/accounts.ts @@ -420,6 +420,8 @@ export interface ServiceTokensOptions { export class ServiceTokens { readonly #options: ServiceTokensOptions; readonly #tokens = new Map(); + /** Services the Company answered `invalid_target` for (§4.5): used signed out. */ + readonly #leftOut = new Set(); constructor(options: ServiceTokensOptions) { this.#options = options; @@ -444,11 +446,21 @@ export class ServiceTokens { if (options.fresh === true) this.#tokens.delete(resource); const known = this.#tokens.get(resource); if (known !== undefined) return known; + if (resource !== undefined && this.#leftOut.has(resource)) return undefined; const narrowed = scopes === undefined ? {} : { scopes }; - const result = - metadata !== undefined && this.#isMcp(metadata.resource) - ? await refresh.tokenForMcp(reference, { context, server: metadata, ...narrowed }) - : await refresh.refresh(reference, { context, ...narrowed, resource }); + let result: RefreshResult; + try { + result = + metadata !== undefined && this.#isMcp(metadata.resource) + ? await refresh.tokenForMcp(reference, { context, server: metadata, ...narrowed }) + : await refresh.refresh(reference, { context, ...narrowed, resource }); + } catch (error) { + if (!(error instanceof AuthorizationError) || error.code !== "invalid_target" || resource === undefined) throw error; + // The Company leaves this service out for this agent (§4.5): it is used signed out, and + // not asked again until `forget`. + this.#leftOut.add(resource); + return undefined; + } if (result.status !== "signed_in" || result.token === undefined) { this.#tokens.clear(); return undefined; @@ -464,5 +476,6 @@ export class ServiceTokens { /** Drop every access token held: signed out, or a new sign-in replaces them. */ forget(): void { this.#tokens.clear(); + this.#leftOut.clear(); } } diff --git a/src/auth.ts b/src/auth.ts index 2827cf33..5f1f6be0 100644 --- a/src/auth.ts +++ b/src/auth.ts @@ -7,18 +7,69 @@ import type { ReactorPlatformView } from "@datalayer/reactor"; import { AuthorizationError } from "./errors.js"; +import { parseJsonStrict } from "./json.js"; +import { readLimitedText } from "./limits.js"; import { isLoopbackRedirect } from "./models.js"; import { SecretValue } from "./secret.js"; -import { SessionClient, finishSignIn, provesWithDpop, type RandomBytes, type SignInResult } from "./sessions.js"; +import { + DPOP_HEADER, + DPOP_NONCE_HEADER, + SessionClient, + finishSignIn, + provesWithDpop, + type RandomBytes, + type SignInResult, +} from "./sessions.js"; import { AuthorizationStateStores, BrowserHandoffs, Clocks, + DpopProvers, RandomSources, firstContribution, } from "./reactor.js"; +import { refusalCode, refuseRedirect, refusedWithoutBody } from "./refusals.js"; import { byIssuer, signInResult, traced } from "./telemetry.js"; +/** The parameters a Direct Sign-In request sets: an endpoint's own values for them are dropped. */ +const AUTHORIZATION_PARAMETERS = [ + "response_type", + "client_id", + "redirect_uri", + "scope", + "state", + "code_challenge", + "code_challenge_method", + "prompt", + "request_uri", +] as const; + +/** + * The OpenID Connect `prompt` a Direct Sign-In request carries (OpenID Connect Core §3.1.2.1, + * §4.2): the Company shows its consent page even when the account granted every scope to the + * `client_id` before (§10.8). + */ +export const PROMPT_CONSENT = "consent"; + +/** The authorization endpoint with none of the parameters a Direct Sign-In request sets. */ +function bareEndpoint(endpoint: string): URL { + const url = new URL(endpoint); + for (const name of AUTHORIZATION_PARAMETERS) url.searchParams.delete(name); + url.hash = ""; + return url; +} + +/** + * The authorization URL after a push (RFC 9126 §4): `client_id` and `request_uri` only, on the + * authorization endpoint. + */ +function pushedUrl(authorizationEndpoint: string, clientId: string, requestUri: string): SecretValue { + const url = bareEndpoint(authorizationEndpoint); + url.searchParams.append("client_id", clientId); + url.searchParams.append("request_uri", requestUri); + return new SecretValue(url.toString()); +} + function defaultRandomBytes(length: number): Uint8Array { if (!globalThis.crypto) { throw new AuthorizationError("crypto_unavailable", "Web Crypto is required"); @@ -90,8 +141,21 @@ export interface DirectSignInOptions { readonly redirectUri: string; readonly scopes: readonly string[]; readonly randomBytes?: RandomBytes; + /** + * Add `prompt=consent` (§4.2, §10.8): a request MUST carry it unless the Personal Agent + * receives the redirect only on the device that opened the authorization URL; only then is it + * `false`. Default `true`. + */ + readonly promptConsent?: boolean; } +/** + * Authorization request state; its URL and PKCE values are secrets. + * + * `authorizationUrl` carries every parameter; `parameters`, the same parameters form encoded, is + * what a Pushed Authorization Request sends (RFC 9126, §4.2), after which the browser opens + * `pushedAuthorizationUrl(requestUri)` with only `client_id` and `request_uri`. + */ export interface DirectSignInRequest { readonly authorizationUrl: SecretValue; readonly issuer: string; @@ -100,8 +164,25 @@ export interface DirectSignInRequest { readonly scopes: readonly string[]; readonly state: SecretValue; readonly codeVerifier: SecretValue; + /** The authorization endpoint, as given. */ + readonly authorizationEndpoint: string; + /** The request's parameters, form encoded: what a push sends (RFC 9126 §2.1). */ + readonly parameters: SecretValue; + /** + * The authorization URL after a push (RFC 9126 §4): `client_id` and `requestUri` only, on the + * authorization endpoint. + */ + pushedAuthorizationUrl(requestUri: string): SecretValue; } +/** + * Build a user-browser authorization URL with random state and S256 PKCE (§4.2). + * + * Plain OAuth: the sign-in names no Session, and any of the User's Sessions uses the tokens it + * returns (§5.4). It names no `resource` either: one sign-in covers every service the Company + * offers, and each token request names one (§4.5). It carries `prompt=consent` unless + * `promptConsent` is `false` (§4.2, §10.8). + */ export async function buildDirectSignInRequest( options: DirectSignInOptions, ): Promise { @@ -122,22 +203,30 @@ export async function buildDirectSignInRequest( // Kept exactly as written: the callback's `iss` is compared character for character (§3.2). httpsUrl(options.issuer, "issuer"); const issuer = options.issuer; - endpoint.searchParams.set("response_type", "code"); - endpoint.searchParams.set("client_id", clientId); - endpoint.searchParams.set("redirect_uri", redirectUri); - endpoint.searchParams.set("scope", scopes.join(" ")); - endpoint.searchParams.set("state", state); - endpoint.searchParams.set("code_challenge", challenge); - endpoint.searchParams.set("code_challenge_method", "S256"); - endpoint.hash = ""; + const parameters: [string, string][] = [ + ["response_type", "code"], + ["client_id", clientId], + ["redirect_uri", redirectUri], + ["scope", scopes.join(" ")], + ["state", state], + ["code_challenge", challenge], + ["code_challenge_method", "S256"], + ]; + if (options.promptConsent !== false) parameters.push(["prompt", PROMPT_CONSENT]); + const url = bareEndpoint(endpoint.toString()); + for (const [name, value] of parameters) url.searchParams.append(name, value); + const authorizationEndpoint = endpoint.toString(); return { - authorizationUrl: new SecretValue(endpoint.toString()), + authorizationUrl: new SecretValue(url.toString()), issuer, clientId, redirectUri, scopes, state: new SecretValue(state), codeVerifier: new SecretValue(verifier), + authorizationEndpoint, + parameters: new SecretValue(new URLSearchParams(parameters).toString()), + pushedAuthorizationUrl: (requestUri: string) => pushedUrl(authorizationEndpoint, clientId, requestUri), }; } @@ -210,6 +299,8 @@ interface PendingDirectSignIn { readonly expiresAt: Date; readonly dpopSigningAlgs: readonly string[] | undefined; readonly pairwiseUserId: string | undefined; + /** Where the request is pushed (RFC 9126), when it is: each opening pushes it again. */ + readonly pushedAuthorizationRequestEndpoint: string | undefined; } export interface DirectSignInStart { @@ -232,7 +323,7 @@ export const CROSS_DEVICE_LIFETIME_SECONDS = 300; export type DirectSignInResult = SignInResult; /** Plain OAuth: the sign-in names no Session, and any of the User's Sessions uses its tokens (§5.4). */ -export interface DirectSignInBeginOptions extends DirectSignInOptions { +export interface DirectSignInBeginOptions extends Omit { readonly tokenEndpoint: string; readonly tenantId: string; /** How long the one-use state lives: 600 seconds by default, 300 at most with `crossDevice`. */ @@ -254,6 +345,32 @@ export interface DirectSignInBeginOptions extends DirectSignInOptions { readonly dpopSigningAlgs?: readonly string[] | undefined; /** The User ID the sign-in is for: its DPoP key proves the code exchange (§4.5). */ readonly pairwiseUserId?: string | undefined; + /** + * The host receives the redirect only on the device that opened the URL (a loopback + * `redirectUri`, or its own app signed in as the User who started): only then does the request + * go without `prompt=consent`, which otherwise has the Company show its consent page even for + * scopes the account granted before (§4.2, §10.8). + */ + readonly sameDeviceRedirect?: boolean; + /** + * The issuer's `pushed_authorization_request_endpoint` (RFC 9126, §3.2): the request is pushed + * there with a client assertion, and a DPoP proof when tokens are bound, and the browser opens + * the authorization endpoint with only `client_id` and `request_uri` (§4.2: a SHOULD whenever + * it is listed, a MUST when required). + */ + readonly pushedAuthorizationRequestEndpoint?: string | undefined; + /** + * The issuer's `require_pushed_authorization_requests`: refused (`RangeError`) without + * `pushedAuthorizationRequestEndpoint`, before anything is sent (RFC 9126 §5). + */ + readonly requirePushedAuthorizationRequests?: boolean; + /** + * The agent's own page for a link the User opens later, an HTTPS URL with `{link}`: a + * `request_uri` expires quickly, so the browser handoff gets this page, and the page calls + * `openLink(link)` when opened, which pushes the request and returns the authorization URL to + * redirect to (§4.2). + */ + readonly linkPage?: string; } export interface DirectSignInCompleteOptions { @@ -290,6 +407,29 @@ async function stateReference(state: string): Promise { ).join("")}`; } +/** A sign-in link's key in the authorization state store: its digest, never the link. */ +async function linkReference(link: string): Promise { + if ([...link].some((character) => character.charCodeAt(0) > 0x7f)) { + throw new AuthorizationError("invalid_or_expired_state", "The sign-in link is invalid"); + } + const cryptoApi = globalThis.crypto; + if (!cryptoApi) { + throw new AuthorizationError("crypto_unavailable", "Web Crypto is required"); + } + const digest = await cryptoApi.subtle.digest("SHA-256", new TextEncoder().encode(link)); + return `direct-link:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`; +} + +/** A response's JSON body, or `undefined` when it has none that parses. */ +function jsonBody(response: Response, text: string): unknown { + if (response.headers.get("content-type")?.split(";", 1)[0]?.trim() !== "application/json") return undefined; + try { + return parseJsonStrict(text); + } catch { + return undefined; + } +} + function callbackState(callbackUrl: string): string { const callback = redirectUrl(callbackUrl, "callbackUrl"); if (callback.hash) { @@ -322,6 +462,8 @@ function isPendingDirectSignIn(value: unknown): value is PendingDirectSignIn { export class DirectSignInClient { readonly #reactor: ReactorPlatformView; readonly #sessions: SessionClient; + readonly #fetch: typeof globalThis.fetch; + readonly #maxResponseBytes: number; constructor(options: DirectSignInClientOptions) { const fetcher = options.fetch ?? globalThis.fetch; @@ -333,6 +475,8 @@ export class DirectSignInClient { throw new RangeError("maxResponseBytes must be a positive integer"); } this.#reactor = options.reactor; + this.#fetch = fetcher; + this.#maxResponseBytes = maxResponseBytes; this.#sessions = new SessionClient({ reactor: options.reactor, fetch: fetcher, @@ -360,6 +504,18 @@ export class DirectSignInClient { if (!options.tenantId || options.tenantId.length > 256) { throw new RangeError("tenantId must contain between 1 and 256 characters"); } + if (options.requirePushedAuthorizationRequests === true && options.pushedAuthorizationRequestEndpoint === undefined) { + throw new RangeError("a Company that requires PAR lists where to push (RFC 9126 §5)"); + } + const linkPage = options.linkPage; + if (linkPage !== undefined) { + if (!linkPage.includes("{link}")) throw new RangeError("linkPage is an HTTPS URL with {link}"); + httpsUrl(linkPage.replaceAll("{link}", "x"), "linkPage"); + } + const pushedEndpoint = + options.pushedAuthorizationRequestEndpoint === undefined + ? undefined + : httpsUrl(options.pushedAuthorizationRequestEndpoint, "pushedAuthorizationRequestEndpoint").toString(); provesWithDpop(options.dpopSigningAlgs, options.pairwiseUserId); const clock = firstContribution(this.#reactor, Clocks, "clock"); const random = firstContribution(this.#reactor, RandomSources, "random source"); @@ -376,6 +532,7 @@ export class DirectSignInClient { redirectUri: options.redirectUri, scopes: options.scopes, randomBytes: (length) => random.bytes(length), + promptConsent: options.sameDeviceRedirect !== true, }); const tokenEndpoint = httpsUrl(options.tokenEndpoint, "tokenEndpoint").toString(); const expiresAt = new Date(clock.now().getTime() + lifetimeSeconds * 1000); @@ -388,17 +545,141 @@ export class DirectSignInClient { expiresAt, dpopSigningAlgs: options.dpopSigningAlgs, pairwiseUserId: options.pairwiseUserId, + pushedAuthorizationRequestEndpoint: pushedEndpoint, }; await store.put(reference, pending, { expiresAt }); + let link: string | undefined; + let opened: SecretValue; + try { + if (linkPage !== undefined) { + link = base64Url(entropy(16, (length) => random.bytes(length))); + await store.put(await linkReference(link), reference, { expiresAt }); + opened = new SecretValue(linkPage.replaceAll("{link}", link)); + } else { + opened = await this.#authorizationUrl(pending); + } + } catch (error) { + await store.take(reference); + if (link !== undefined) await store.take(await linkReference(link)); + throw error; + } try { - await browser.open(request.authorizationUrl); + await browser.open(opened); } catch (cause) { await store.take(reference); + if (link !== undefined) await store.take(await linkReference(link)); throw new AuthorizationError("browser_handoff_failed", "Browser handoff failed", { cause }); } return { expiresAt, requestedScopes: request.scopes, crossDevice }; } + /** + * The authorization URL for a sign-in link the User opened on the agent's own page + * (`begin({ linkPage })`, §4.2): the request pushed now when the Company takes PAR, so its + * short-lived `request_uri` is fresh, else the full URL. The page redirects the browser there. + * A link may be opened again until the sign-in completes or expires; `AuthorizationError` + * (`invalid_or_expired_state`) for an unknown or expired one. + */ + async openLink(link: string): Promise { + const store = firstContribution(this.#reactor, AuthorizationStateStores, "authorization state store"); + const clock = firstContribution(this.#reactor, Clocks, "clock"); + const linkKey = await linkReference(link); + const reference = await store.take(linkKey); + const pending = typeof reference === "string" ? await store.take(reference) : undefined; + if (!isPendingDirectSignIn(pending) || clock.now().getTime() > pending.expiresAt.getTime()) { + throw new AuthorizationError("invalid_or_expired_state", "The sign-in link is unknown or has expired"); + } + await store.put(reference as string, pending, { expiresAt: pending.expiresAt }); + await store.put(linkKey, reference, { expiresAt: pending.expiresAt }); + return this.#authorizationUrl(pending); + } + + /** The URL the browser opens: after a push when the Company takes PAR (§4.2). */ + async #authorizationUrl(pending: PendingDirectSignIn): Promise { + if (pending.pushedAuthorizationRequestEndpoint === undefined) return pending.request.authorizationUrl; + const request = pending.request; + return pushedUrl(request.authorizationEndpoint, request.clientId, await this.#push(pending)); + } + + /** + * Push the request (RFC 9126 §2): its parameters, a fresh client assertion, and a DPoP proof + * when tokens are bound, so the code is bound to the key (RFC 9449 §10.1); a `use_dpop_nonce` + * refusal is retried once. The `request_uri`. + */ + async #push(pending: PendingDirectSignIn): Promise { + const request = pending.request; + const endpoint = pending.pushedAuthorizationRequestEndpoint as string; + const proves = provesWithDpop(pending.dpopSigningAlgs, pending.pairwiseUserId); + let nonce: string | undefined; + let response: Response; + let payload: unknown; + while (true) { + const body = new URLSearchParams(request.parameters.reveal()); + for (const [name, value] of Object.entries( + await this.#sessions.clientAuthentication({ clientId: request.clientId, issuer: request.issuer }), + )) { + body.set(name, value); + } + const headers: Record = { Accept: "application/json" }; + if (proves) { + const proof = await firstContribution(this.#reactor, DpopProvers, "DPoP prover").prove({ + method: "POST", + url: endpoint, + tenantId: pending.tenantId, + issuer: request.issuer, + sub: pending.pairwiseUserId as string, + ...(nonce === undefined ? {} : { nonce }), + }); + headers[DPOP_HEADER] = proof.reveal(); + } + try { + response = await this.#fetch(endpoint, { + method: "POST", + headers, + body, + credentials: "omit", + redirect: "manual", + }); + } catch (cause) { + throw new AuthorizationError("request_failed", "Pushed authorization failed", { cause }); + } + await refuseRedirect(response, AuthorizationError); + const text = await readLimitedText(response, this.#maxResponseBytes); + if (new TextEncoder().encode(text).byteLength > this.#maxResponseBytes) { + throw new AuthorizationError("response_too_large", "Pushed authorization response exceeds size limit", { + statusCode: response.status, + }); + } + payload = refusedWithoutBody(response, text) ? undefined : jsonBody(response, text); + const given = response.headers.get(DPOP_NONCE_HEADER); + if ( + proves && + nonce === undefined && + given !== null && + response.status === 400 && + (payload as { error?: unknown } | undefined)?.error === "use_dpop_nonce" + ) { + nonce = given; + continue; + } + break; + } + if (response.status !== 200 && response.status !== 201) { + throw new AuthorizationError( + refusalCode(response, payload, "http_error"), + "The company refused the pushed authorization request", + { statusCode: response.status }, + ); + } + const answer = (typeof payload === "object" && payload !== null ? payload : {}) as Record; + const requestUri = answer.request_uri; + const expiresIn = answer.expires_in; + if (typeof requestUri !== "string" || !requestUri || !Number.isInteger(expiresIn) || (expiresIn as number) <= 0) { + throw new AuthorizationError("invalid_par_response", "The pushed authorization response is malformed"); + } + return requestUri; + } + complete(options: DirectSignInCompleteOptions): Promise { return traced( this.#reactor, diff --git a/src/browser-control.ts b/src/browser-control.ts index f0dde0f7..7a5e43a6 100644 --- a/src/browser-control.ts +++ b/src/browser-control.ts @@ -26,7 +26,7 @@ */ import { PersonalAgentProtocolError } from "./errors.js"; -import { companyExtension, type DiscoveryDocument } from "./models.js"; +import { companyExtension, domainHost, type DiscoveryDocument } from "./models.js"; import type { PapSession } from "./sessions.js"; export const BROWSER_CONTROL_EXTENSION = "browser-control"; @@ -284,7 +284,7 @@ export function pageMarks(html: string): PageMarks { */ export function onCompanyHost(host: string, organizationDomain: string): boolean { const name = host.toLowerCase().replace(/\.$/, ""); - const domain = organizationDomain.toLowerCase().replace(/\.$/, ""); + const domain = domainHost(organizationDomain); return name === domain || name.endsWith(`.${domain}`); } diff --git a/src/company/index.ts b/src/company/index.ts index 6f011d13..01b1866f 100644 --- a/src/company/index.ts +++ b/src/company/index.ts @@ -127,7 +127,7 @@ export function createCompanyDefaultsPlugin( ) { return definePlugin({ name: "personal-agent-protocol.company", - version: "0.36.1", + version: "0.37.0", contributionPoints: [ CompanyStores, CompanyAccounts, @@ -199,6 +199,7 @@ export * from "./points.js"; export * from "./service.js"; export { DelegationCache, + RSA_KEY_BITS, SESSION_JWT_WINDOW_SECONDS, unverifiedSessionIssuer, verifyAssertion, diff --git a/src/company/points.ts b/src/company/points.ts index 437152f1..d77da88f 100644 --- a/src/company/points.ts +++ b/src/company/points.ts @@ -111,6 +111,11 @@ export interface Turn { * Conversation has no message yet (§8.10). `text` and `data` are then absent. */ readonly opening?: boolean; + /** + * The context the personal agent's messages in this conversation share (§8.4): each field's + * latest value, and none for a field a message set to `null` (from 1.0). + */ + readonly context: Readonly>; } /** @@ -235,9 +240,20 @@ export interface ClientPolicy { * and the agent is served signed out. Without the method, every allowed agent may. */ allowsSignIn?(clientId: string, grantType: string): Promise; + /** + * A sign-in covers every resource the company offers personal agents (§4.5): with this method + * a policy may leave a service out, for every agent or by `clientId`, and a token request for + * it is `invalid_target`. `resource` is the service's (the MCP server's `url`, the conversation + * endpoint), never the default token's. Without the method, every agent gets a token for every + * service. + */ + allowsResource?(clientId: string, resource: string): Promise; } -/** The default policy: any agent with valid identity is welcome, and may sign in. */ +/** + * The default policy: any agent with valid identity is welcome, may sign in, and gets tokens for + * every service. + */ export class AllowEveryAgent implements ClientPolicy { async allows(_clientId: string): Promise { return true; @@ -246,6 +262,10 @@ export class AllowEveryAgent implements ClientPolicy { async allowsSignIn(_clientId: string, _grantType: string): Promise { return true; } + + async allowsResource(_clientId: string, _resource: string): Promise { + return true; + } } /** diff --git a/src/company/service.ts b/src/company/service.ts index d253fecd..ddb8e3e2 100644 --- a/src/company/service.ts +++ b/src/company/service.ts @@ -27,7 +27,8 @@ * `invalid_session` (HTTP 400); one for a Session that has ended `session_ended` (§5.5). * Its own access token without the header is refused. * - OAuth (§4): access tokens, Bearer or, with `dpopBinding`, bound with DPoP (§4.5), and - * refresh tokens, never bound; Direct Sign-In, Device + * refresh tokens, bound to the same key only with `bindRefreshTokens` (§4.4); Direct Sign-In, + * with Pushed Authorization Requests when `pushedAuthorizationRequests` (RFC 9126), Device * Sign-In with `authorization_pending` and `slow_down`, refresh with rotation, * narrower scopes and `resource` (RFC 8707: `invalid_target` for one it doesn't * serve), and revocation (RFC 7009) whose sign-in ends whole. @@ -111,7 +112,10 @@ import { type Message, type Operation, compatibleVersions, + domainHost, + effectiveContext, parseVersion, + splitDomain, } from "../models.js"; import { APPROVAL_DECLINED, @@ -183,6 +187,7 @@ import { type PendingAuthorization, type PendingDevice, type PendingMediated, + type PushedAuthorization, type Acceptance, type SignInAttempts, type StoreWriteOptions, @@ -245,11 +250,23 @@ export type MediatedFieldSpec = readonly [name: string, label: string, secret: b export type DpopBinding = "off" | "optional" | "required"; /** Whether a company checks operator signatures (§5.3). */ export type OperatorSignatures = "off" | "optional" | "required"; +/** Whether a company takes Pushed Authorization Requests for Direct Sign-In (RFC 9126, §4.2). */ +export type PushedAuthorizationRequests = "off" | "offered" | "required"; export interface CompanyConfigOptions { readonly name: string; + /** + * The company's domain, `organization.domain` (§3.1): with its port when that isn't 443, such + * as `shop.example:8443`, only when every protocol version it serves is 1.0 or later. + */ readonly domain: string; readonly scopes: readonly string[]; + /** + * What the Company Agent can help with, in plain language: the `description` of its + * `agent.protocols` entry (§3.1, §8.1), which a 1.0 document requires. It may say the agent can + * help with anything. + */ + readonly agentDescription: string; readonly writeScopes?: readonly string[]; /** Mediated Sign-In's `fields`. None, it isn't offered. */ readonly mediatedFields?: readonly MediatedFieldSpec[]; @@ -295,6 +312,21 @@ export interface CompanyConfigOptions { readonly accessTokenLifetimeSeconds?: number; /** How long a sign-in's refresh tokens work (§4.4; default 90 days). */ readonly refreshTokenLifetimeSeconds?: number; + /** + * Bind each refresh token to the DPoP key of the request that issued it, and the tokens rotated + * from it (§4.4, a MAY from 1.0): a refresh whose proof is missing or by another key is + * `invalid_grant`. Off by default; needs `dpopBinding`. + */ + readonly bindRefreshTokens?: boolean; + /** + * Pushed Authorization Requests for Direct Sign-In (RFC 9126, §4.2, a MAY from 1.0): `offered` + * lists `pushed_authorization_request_endpoint` (`/oauth/par`), and `required` also sets + * `require_pushed_authorization_requests`, so the authorization endpoint takes only a + * `request_uri` the agent pushed. Off by default; needs `direct`. + */ + readonly pushedAuthorizationRequests?: PushedAuthorizationRequests; + /** How long a pushed request's `request_uri` lasts, in seconds (RFC 9126 §2.2: briefly; default 60). */ + readonly pushedRequestLifetimeSeconds?: number; /** * A refresh token used again after it was rotated ends its whole sign-in, as RFC 9700 §4.14.2 * describes (guides, *Token lifetimes*): a copied refresh token's grant ends as soon as both @@ -480,6 +512,7 @@ export class CompanyConfig { readonly name: string; readonly domain: string; readonly scopes: readonly string[]; + readonly agentDescription: string; readonly writeScopes: readonly string[]; readonly mediatedFields: readonly MediatedFieldSpec[]; readonly mediatedScopes: readonly string[]; @@ -496,6 +529,9 @@ export class CompanyConfig { readonly accessTokenLifetimeSeconds: number; readonly refreshTokenLifetimeSeconds: number; readonly refreshReuseRevokes: boolean; + readonly bindRefreshTokens: boolean; + readonly pushedAuthorizationRequests: PushedAuthorizationRequests; + readonly pushedRequestLifetimeSeconds: number; readonly operationLifetimeSeconds: number; readonly deviceInterval: number; readonly maxCodeAttempts: number; @@ -539,6 +575,11 @@ export class CompanyConfig { this.name = options.name; this.domain = options.domain; this.scopes = [...options.scopes]; + this.agentDescription = options.agentDescription; + if (typeof this.agentDescription !== "string" || !this.agentDescription.trim()) { + // Every conversation protocol says what its agent helps with (§3.1, §8.1). + throw new RangeError("agentDescription says what the Company Agent can help with"); + } this.writeScopes = [...(options.writeScopes ?? [])]; this.mediatedFields = [...(options.mediatedFields ?? [])]; this.mediatedScopes = [...(options.mediatedScopes ?? [])]; @@ -565,6 +606,9 @@ export class CompanyConfig { this.accessTokenLifetimeSeconds = options.accessTokenLifetimeSeconds ?? 60 * 60; this.refreshTokenLifetimeSeconds = options.refreshTokenLifetimeSeconds ?? 90 * 24 * 60 * 60; this.refreshReuseRevokes = options.refreshReuseRevokes ?? false; + this.bindRefreshTokens = options.bindRefreshTokens ?? false; + this.pushedAuthorizationRequests = options.pushedAuthorizationRequests ?? "off"; + this.pushedRequestLifetimeSeconds = options.pushedRequestLifetimeSeconds ?? 60; this.operationLifetimeSeconds = options.operationLifetimeSeconds ?? 15 * 60; this.deviceInterval = options.deviceInterval ?? 5; this.maxCodeAttempts = options.maxCodeAttempts ?? 3; @@ -580,6 +624,10 @@ export class CompanyConfig { throw new RangeError("protocolVersions lists each version the company serves once"); } for (const version of this.protocolVersions) parseVersion(version); + if (splitDomain(this.domain)[1] !== undefined && this.protocolVersions.some((version) => parseVersion(version)[0] < 1)) { + // A domain names its port when that isn't 443 from 1.0 only (§3.1). + throw new RangeError("a domain with a port is served at 1.0 or later only"); + } this.deprecatedVersions = { ...(options.deprecatedVersions ?? {}) }; this.conversationCarryOver = options.conversationCarryOver ?? true; if (Object.keys(this.deprecatedVersions).some((version) => !this.protocolVersions.includes(version))) { @@ -628,9 +676,19 @@ export class CompanyConfig { dpopNonceLifetimeSeconds: this.dpopNonceLifetimeSeconds, dpopProofWindowSeconds: this.dpopProofWindowSeconds, operatorSignatureWindowSeconds: this.operatorSignatureWindowSeconds, + pushedRequestLifetimeSeconds: this.pushedRequestLifetimeSeconds, })) { if (!(lifetime > 0)) throw new RangeError(`${name} must be positive`); } + if (!["off", "offered", "required"].includes(this.pushedAuthorizationRequests)) { + throw new RangeError("pushedAuthorizationRequests is off, offered or required"); + } + if (this.pushedAuthorizationRequests !== "off" && !this.direct) { + throw new RangeError("pushedAuthorizationRequests are Direct Sign-In's: direct is on"); + } + if (this.bindRefreshTokens && this.dpopBinding === "off") { + throw new RangeError("bindRefreshTokens needs dpopBinding"); + } if ( !this.oauth && (this.mediatedFields.length > 0 || this.operations || this.aliases.length > 0 || this.dpopBinding !== "off") @@ -655,7 +713,8 @@ export class CompanyConfig { } if (this.devicePage !== undefined) { const host = new URL(this.devicePage).hostname.toLowerCase(); - if (!(host === this.domain || host.endsWith(`.${this.domain}`))) { + const own = domainHost(this.domain); + if (!(host === own || host.endsWith(`.${own}`))) { // A personal agent shows the link only on the issuer's host or `organization.domain`, // or a subdomain of either (§4.3). The issuer is on `domain`, and an agent that found // the company at an alias knows only that alias as its domain, so a page on another @@ -732,6 +791,10 @@ export class CompanyConfig { get authorizationEndpoint(): string { return `${this.base}/oauth/authorize`; } + /** Where a Pushed Authorization Request goes (RFC 9126 §2). */ + get pushedAuthorizationRequestEndpoint(): string { + return `${this.base}/oauth/par`; + } get apiDescription(): string { return `${this.base}/api/openapi.json`; } @@ -830,6 +893,16 @@ export class CompanyConfig { } } +/** + * A scope on a consent page (§10.8): its words, and with the signed-in account known, whether it + * granted the scope to this agent before (`granted_before`). + */ +export interface ConsentScope { + readonly scope: string; + readonly description: string; + readonly granted_before?: boolean; +} + /** A request as any framework hands it over: full HTTPS URL, lower-case headers. */ export interface CompanyRequest { readonly method: string; @@ -1048,11 +1121,24 @@ function waitOf(request: CompanyRequest): number | undefined { /** A message as the personal agent sent it; a `role` it set is ignored (§7.4). */ /** * A message as the personal agent sent it (§8.4): its ID is its request's, and a `role` or `id` - * it set is ignored. + * it set is ignored, as are `author.id`, `name` and `image`, which only Company messages have. */ function incoming(value: unknown, requestId: string): Message { - const { role: _role, id: _id, ...rest } = parseMessage(value); - return { ...rest, id: requestId } as Message; + const { role: _role, id: _id, author, ...rest } = parseMessage(value); + // `author.id`, `name` and `image` are Company messages' only (a later version may define + // them here): ignored. + return { ...rest, author: { type: author.type }, id: requestId } as Message; +} + +/** The context the personal agent's messages in a conversation share (§8.4). */ +function sharedContext(conversation: StoredConversation): Record { + return effectiveContext( + conversation.events + .map((event) => event.payload) + .filter((payload) => payload.type === "message") + .map((payload) => payload.message as Message | undefined) + .filter((message): message is Message => message !== undefined && message.role === "user"), + ); } /** The request's `id` (§8.3): required, in the URL-safe base64 alphabet, else `invalid_request`. */ @@ -1534,6 +1620,9 @@ export class CompanyService { if (method === "GET" && path === "/oauth/authorize" && this.config.direct) { return await this.#authorize(request); } + if (method === "POST" && path === "/oauth/par" && this.config.pushedAuthorizationRequests !== "off") { + return await this.#pushedRequest(request); + } const api = this.#api(); if (method === "GET" && path === "/api/openapi.json" && api !== undefined) { return { status: 200, body: api.openapi(), headers: {} }; @@ -1715,8 +1804,15 @@ export class CompanyService { if (domain !== undefined && domain !== config.domain && !config.aliases.includes(domain)) { throw new RangeError(`${domain} is not one of this company's domains`); } + const protocolVersion = version ?? config.preferredVersion; + const poppy: Record = { type: "poppy", endpoint: config.conversationsEndpoint }; + if (parseVersion(protocolVersion)[0] >= 1) { + // 1.0 requires it (§3.1, §8.1); 0.4 doesn't define it, so its document leaves it out: + // each side sends only what the other's version defines (§3.4). + poppy.description = config.agentDescription; + } const document: Record = { - protocol_version: version ?? config.preferredVersion, + protocol_version: protocolVersion, ...(version === undefined && config.protocolVersions.length > 1 ? { supported_versions: Object.fromEntries( @@ -1729,7 +1825,7 @@ export class CompanyService { domain: domain ?? config.domain, ...(config.logoUri === undefined ? {} : { logo_uri: config.logoUri }), }, - agent: { protocols: [{ type: "poppy", endpoint: config.conversationsEndpoint }] }, + agent: { protocols: [poppy] }, }; if (config.oauth) { // Direct and Device Sign-In are the issuer's grants, not listed here (§3.2, §4.4). @@ -1901,6 +1997,11 @@ export class CompanyService { metadata.authorization_endpoint = config.authorizationEndpoint; metadata.code_challenge_methods_supported = ["S256"]; } + if (config.pushedAuthorizationRequests !== "off") { + // RFC 9126 §5 (§3.2, §4.2): where to push, and whether Direct Sign-In needs it. + metadata.pushed_authorization_request_endpoint = config.pushedAuthorizationRequestEndpoint; + if (config.pushedAuthorizationRequests === "required") metadata.require_pushed_authorization_requests = true; + } if (config.device) { grants.push(DEVICE_CODE_GRANT); metadata.device_authorization_endpoint = config.deviceEndpoint; @@ -2021,8 +2122,13 @@ export class CompanyService { // No tokens to protect: every refresh is `invalid_grant`, the client assertion unverified (§3.2). if (grant === REFRESH_TOKEN_GRANT && (await this.#neverIssued())) throw new Refused(400, "invalid_grant"); const clientId = await this.#client(form); + const resource = this.#resource(form); + if (resource !== undefined && !(await this.#resourceAllowed(clientId, resource))) { + // A service the company leaves out, for every agent or this one (§4.5). + throw new Refused(400, "invalid_target"); + } // Before any grant is used: a proof refused spends no code. - const jkt = await this.#tokenBinding(request, this.#resource(form)); + const jkt = await this.#tokenBinding(request, resource); if (grant === REFRESH_TOKEN_GRANT) return this.#refreshGrant(form, clientId, jkt); if (grant === AUTHORIZATION_CODE_GRANT && this.config.direct) return this.#codeGrant(form, clientId, jkt); if (grant === DEVICE_CODE_GRANT && this.config.device) return this.#deviceGrant(form, clientId, jkt); @@ -2099,11 +2205,22 @@ export class CompanyService { return nonce !== undefined && (await this.store.get(RecordKinds.dpopNonce, nonce)) !== undefined; } + /** + * Whether the client policy offers this agent a token for this service (§4.5): + * `allowsResource`, when the policy has it; every service otherwise. + */ + async #resourceAllowed(clientId: string, resource: string): Promise { + const policy = firstContribution(this.reactor, ClientPolicies, "policy"); + return policy.allowsResource === undefined ? true : policy.allowsResource(clientId, resource); + } + /** * The `resource` a token is issued for (RFC 8707, §4.5): one this company serves. * * `https://{domain}` (or an alias's) is the default token's, `undefined`; the MCP server's - * `url` gets a token for it alone; anything else is `invalid_target`. + * `url` gets a token for it alone; anything else is `invalid_target`. A sign-in names no + * resource and covers every one, those added after it too: each token request, the one that + * completes the sign-in or a refresh, names one. */ #resource(form: Readonly>): string | undefined { const resource = form.resource; @@ -2151,6 +2268,11 @@ export class CompanyService { throw new Refused(400, "invalid_grant"); } if (await this.#signInEnded(grant)) throw new Refused(400, "invalid_grant"); + if (grant.dpopJkt !== undefined && (jkt === undefined || !sameText(jkt, grant.dpopJkt))) { + // Bound to the key it was issued with (§4.4): a copied refresh token is useless with any + // other, and nothing is issued for it. + throw new Refused(400, "invalid_grant"); + } const requested = words(form.scope); if (requested.length && requested.some((scope) => !grant.scopes.includes(scope))) { throw new Refused(400, "invalid_scope"); @@ -2287,14 +2409,19 @@ export class CompanyService { * * Who asks (the agent's `client_name` and its `client_id` domain), with the `heading` and * `caution` the page starts with (§10.8), and for what. Rejects for an unknown, expired, - * approved or denied code. + * approved or denied code. The page is shown for every Device Sign-In and lists every scope, + * those the account granted before too (§4.3, §10.8): with `accountId`, each says whether it + * did (`granted_before`). */ - async deviceRequest(userCode: string): Promise<{ + async deviceRequest( + userCode: string, + options: { readonly accountId?: string } = {}, + ): Promise<{ readonly client_name: string; readonly client_domain: string; readonly heading: string; readonly caution: string; - readonly scopes: readonly { readonly scope: string; readonly description: string }[]; + readonly scopes: readonly ConsentScope[]; readonly expires_at: string; }> { const pointer = await this.#read(RecordKinds.userCode, userCode); @@ -2310,7 +2437,10 @@ export class CompanyService { client_domain: new URL(pending.clientId).hostname, heading: connectHeading(metadata.client_name, this.config.name), caution: connectCaution(metadata.client_name), - scopes: pending.scopes.map((scope) => ({ scope, description: this.config.describe(scope) })), + scopes: this.#consentScopes( + pending.scopes, + options.accountId === undefined ? undefined : await this.#grantedBefore(pending.clientId, options.accountId), + ), expires_at: isoZ(new Date(pending.expiresAt)), }; } @@ -2556,6 +2686,8 @@ export class CompanyService { revoked: false, family, signedInAt: this.#now().toISOString(), + // Bound to the key of the request that issued it, and every token rotated from it (§4.4). + ...(this.config.bindRefreshTokens && jkt !== undefined ? { dpopJkt: jkt } : {}), }; await this.store.put(RecordKinds.refreshToken, family, json(grant), expiry(expiresAt)); const signIn: AccountFamily = { @@ -2595,8 +2727,9 @@ export class CompanyService { /** * A token response (§4.7): an access token, and the refresh token if any. * - * Bearer, or `DPoP` bound to the key `jkt` names; a refresh token is never bound (RFC 9449 - * §5). `scope` follows RFC 6749: left out when it grants exactly the scopes requested. + * Bearer, or `DPoP` bound to the key `jkt` names. A refresh token is bound to that key only + * with `bindRefreshTokens` (§4.4), recorded with its grant. `scope` follows RFC 6749: left out + * when it grants exactly the scopes requested. */ async #issue(options: { readonly clientId: string; @@ -2674,9 +2807,91 @@ export class CompanyService { // Direct Sign-In (§4.5) ------------------------------------------------------------- - /** The company's own sign-in and consent page for a personal agent's request. */ + /** + * `POST /oauth/par` (RFC 9126, §4.2): an authorization request's parameters, pushed with the + * agent's client assertion, and a DPoP proof when it sends them (RFC 9449 §10.1). Checked as the + * authorization endpoint would check them; answered with a one-use `request_uri` that lasts + * `pushedRequestLifetimeSeconds`. + */ + async #pushedRequest(request: CompanyRequest): Promise { + const form = pairs(text(request.body)); + // A pushed request can't name another (RFC 9126 §2.1). + if ("request_uri" in form) throw new Refused(400, "invalid_request"); + const clientId = await this.#client(form); + const jkt = + request.headers.dpop && this.config.dpopBinding !== "off" + ? await this.#dpopProof(request, { status: 400 }) + : undefined; + const resolver = firstContribution(this.reactor, ClientResolvers, "client"); + const [metadata] = await resolver.resolve(clientId); + const redirectUri = form.redirect_uri ?? ""; + if (!metadata.redirect_uris.some((entry) => redirectUriMatches(entry, redirectUri))) { + throw new Refused(400, "invalid_request"); + } + const scopes = words(form.scope); + if (form.response_type !== "code") throw new Refused(400, "unsupported_response_type"); + if (form.code_challenge_method !== "S256" || !form.code_challenge) throw new Refused(400, "invalid_request"); + if (!scopes.length || scopes.some((scope) => !this.config.offeredScopes.includes(scope))) { + throw new Refused(400, "invalid_scope"); + } + if (!(await this.#signInAllowed(clientId, AUTHORIZATION_CODE_GRANT))) { + throw new Refused(400, "unauthorized_client"); + } + const parameters = Object.fromEntries( + Object.entries(form).filter(([name]) => name !== "client_assertion" && name !== "client_assertion_type"), + ); + const requestUri = `urn:ietf:params:oauth:request_uri:${this.#id("par")}`; + const expiresAt = this.#later(this.config.pushedRequestLifetimeSeconds); + const pushed: PushedAuthorization = { + clientId, + parameters, + expiresAt: expiresAt.toISOString(), + ...(jkt === undefined ? {} : { dpopJkt: jkt }), + }; + await this.store.put(RecordKinds.pushedRequest, requestUri, json(pushed), expiry(expiresAt)); + return { + status: 201, + body: { request_uri: requestUri, expires_in: Math.floor(this.config.pushedRequestLifetimeSeconds) }, + headers: { ...NO_STORE }, + }; + } + + /** + * The authorization request a `request_uri` names, taken once, and the DPoP key that pushed it + * (RFC 9126 §4); `undefined` for an unknown, used or expired one, or one another agent pushed. + * Every other query parameter but `client_id` is ignored. + */ + async #pushedParameters( + query: Readonly>, + ): Promise, string | undefined] | undefined> { + const pushed = (await this.store.take(RecordKinds.pushedRequest, query.request_uri ?? "")) as unknown as + | PushedAuthorization + | undefined; + if (pushed === undefined || this.#passed(pushed.expiresAt) || pushed.clientId !== query.client_id) { + return undefined; + } + return [{ ...pushed.parameters }, pushed.dpopJkt]; + } + + /** + * The company's own sign-in and consent page for a personal agent's request. + * + * With `pushedAuthorizationRequests`, a `request_uri` the agent pushed stands for the request + * (RFC 9126 §4); `required` takes nothing else. The page lists every scope the sign-in would + * grant and is shown for every request, `prompt=consent` or not, even when the account granted + * every scope before (§4.2, §10.8). + */ async #authorize(request: CompanyRequest): Promise { - const query = pairs(new URL(request.url).search); + let query = pairs(new URL(request.url).search); + let pushedBy: string | undefined; + if ("request_uri" in query && this.config.pushedAuthorizationRequests !== "off") { + const pushed = await this.#pushedParameters(query); + if (pushed === undefined) return page(400, "This sign-in request is not valid or has expired."); + [query, pushedBy] = pushed; + } else if (this.config.pushedAuthorizationRequests === "required") { + // Only a pushed request (RFC 9126 §5): nothing the browser carried is trusted. + return page(400, "This sign-in request is not valid."); + } const clientId = query.client_id ?? ""; const redirectUri = query.redirect_uri ?? ""; if (!clientId || !(await this.#allowed(clientId))) { @@ -2731,6 +2946,8 @@ export class CompanyService { expiresAt: expiresAt.toISOString(), clientName: metadata.client_name, ...(hosted === undefined ? { browserBinding: digest(browser) } : {}), + ...(query.prompt === undefined ? {} : { prompt: query.prompt }), + ...(pushedBy === undefined ? {} : { dpopJkt: pushedBy }), }; await this.store.put(RecordKinds.authorization, requestId, json(pending), expiry(expiresAt)); if (hosted !== undefined) { @@ -2801,22 +3018,33 @@ export class CompanyService { * A pending Direct Sign-In request, for a consent page to show; not consumed. * * Who asks (`client_name`, the `client_id` domain), for what (each scope with its - * `scopeDescriptions` words), until when; never `state`, PKCE, or the redirect. Rejects - * for an unknown, used, or expired request. + * `scopeDescriptions` words), until when, and the request's `prompt`; never `state`, PKCE, or + * the redirect. Rejects for an unknown, used, or expired request. + * + * The page lists every scope in `scopes`, the ones the account granted this agent before too, + * and is shown even when it granted them all (§4.2, §10.8): every User of an agent shares its + * `client_id`. With `accountId`, the person signed in on the page, each scope says whether that + * account granted it to this `client_id` before (`granted_before`), which the page MAY mark. */ - async authorizationRequest(requestId: string): Promise<{ + async authorizationRequest( + requestId: string, + options: { readonly accountId?: string } = {}, + ): Promise<{ readonly request_id: string; readonly client_name: string; readonly client_domain: string; readonly heading: string; readonly caution: string; - readonly scopes: readonly { readonly scope: string; readonly description: string }[]; + readonly scopes: readonly ConsentScope[]; + readonly prompt: string | null; readonly expires_at: string; }> { const pending = await this.#read(RecordKinds.authorization, requestId); if (pending === undefined || this.#passed(pending.expiresAt)) { throw new Error("unknown, used, or expired sign-in request"); } + const before = + options.accountId === undefined ? undefined : await this.#grantedBefore(pending.clientId, options.accountId); return { request_id: requestId, client_name: pending.clientName ?? "", @@ -2824,11 +3052,41 @@ export class CompanyService { // What the page starts with and says before the person goes on (§10.8). heading: connectHeading(pending.clientName ?? "", this.config.name), caution: connectCaution(pending.clientName ?? ""), - scopes: pending.scopes.map((scope) => ({ scope, description: this.config.describe(scope) })), + scopes: this.#consentScopes(pending.scopes, before), + prompt: pending.prompt ?? null, expires_at: isoZ(new Date(pending.expiresAt)), }; } + /** + * Every scope a sign-in would grant, for its consent page (§10.8), each marked + * `granted_before` when the account's earlier grants are known. + */ + #consentScopes(scopes: readonly string[], before: ReadonlySet | undefined): ConsentScope[] { + return scopes.map((scope) => ({ + scope, + description: this.config.describe(scope), + ...(before === undefined ? {} : { granted_before: before.has(scope) }), + })); + } + + /** The scopes the account's live sign-ins granted this `client_id` (§10.8). */ + async #grantedBefore(clientId: string, accountId: string): Promise> { + const agent = await this.#read(RecordKinds.accountAgent, composite(clientId, accountId)); + const granted = new Set(); + for (const familyId of agent?.families ?? []) { + const family = await this.#read(RecordKinds.accountFamily, familyId); + if (family === undefined || family.revoked) continue; + for (const token of family.tokens) { + const grant = await this.#read(RecordKinds.refreshToken, token); + if (grant !== undefined && !grant.revoked && !this.#passed(grant.expiresAt)) { + for (const scope of grant.scopes) granted.add(scope); + } + } + } + return granted; + } + /** * The user, signed in on the company's page, allowed: where their browser goes next. * @@ -2852,6 +3110,7 @@ export class CompanyService { accountId: options.accountId, scopes: granted, expiresAt: expiresAt.toISOString(), + ...(pending.dpopJkt === undefined ? {} : { dpopJkt: pending.dpopJkt }), }; await this.store.put(RecordKinds.code, digest(code), json(issued), expiry(expiresAt)); return this.#redirectUrl(pending.redirectUri, { code, state: pending.state }); @@ -2898,6 +3157,10 @@ export class CompanyService { .update(form.code_verifier ?? "") .digest("base64url"); if (!sameText(verifier, issued.codeChallenge)) throw new Refused(400, "invalid_grant"); + if (issued.dpopJkt !== undefined && (jkt === undefined || !sameText(jkt, issued.dpopJkt))) { + // Pushed with a DPoP proof, the code is bound to its key (RFC 9449 §10.1). + throw new Refused(400, "invalid_grant"); + } return this.#signIn(clientId, issued.accountId, issued.scopes, issued.requested, jkt, this.#resource(form)); } @@ -3919,6 +4182,7 @@ export class CompanyService { isDirect: true, supportsOperations: negotiated, opening: true, + context: {}, }); const events: StoredEvent[] = []; for (const reply of replies) { @@ -4151,6 +4415,7 @@ export class CompanyService { clientId: session.clientId, isDirect: conversation.parentId !== undefined, supportsOperations: negotiated, + context: sharedContext(conversation), }); for (const reply of replies) { const event = await this.#reply(conversationId, session, reply, message.id); diff --git a/src/company/store.ts b/src/company/store.ts index a82882a6..471f02dd 100644 --- a/src/company/store.ts +++ b/src/company/store.ts @@ -217,6 +217,11 @@ export const RecordKinds = { device: "device", userCode: "user_code", authorization: "authorization", + /** + * A Pushed Authorization Request by its `request_uri` (RFC 9126, §4.2): the parameters a + * personal agent pushed with its client assertion, used once, briefly. + */ + pushedRequest: "pushed_request", code: "code", mediated: "mediated", conversation: "conversation", @@ -307,6 +312,12 @@ export interface AccountGrant { * before any such moment. */ readonly signedInAt?: string; + /** + * With `bindRefreshTokens`, the thumbprint of the DPoP key of the request that issued it, + * carried by every token rotated from it: a refresh proves with that key, or is + * `invalid_grant` (§4.4). Absent: not bound. + */ + readonly dpopJkt?: string; } /** One sign-in: every refresh token rotated from it, and the access tokens it gave. */ @@ -380,6 +391,28 @@ export interface PendingAuthorization { * then says which were granted. */ readonly requested?: readonly string[]; + /** + * The request's `prompt` (OpenID Connect Core §3.1.2.1, §4.2): `consent` asks for the consent + * page even when the account granted every scope before. + */ + readonly prompt?: string; + /** + * The thumbprint of the DPoP key that pushed the request (RFC 9449 §10.1): the code is + * exchanged only with a proof by that key. + */ + readonly dpopJkt?: string; +} + +/** + * A Pushed Authorization Request (RFC 9126, §4.2): the authorization request's parameters, the + * agent whose client assertion pushed them, and the DPoP key that proved the push, if any. Used + * once, by the authorization endpoint. + */ +export interface PushedAuthorization { + readonly clientId: string; + readonly parameters: Readonly>; + readonly expiresAt: string; + readonly dpopJkt?: string; } /** A one-use authorization code, at most a minute old. */ @@ -392,6 +425,8 @@ export interface IssuedCode { readonly accountId: string; readonly scopes: readonly string[]; readonly expiresAt: string; + /** The DPoP key that pushed the request (RFC 9449 §10.1): the exchange proves with it. */ + readonly dpopJkt?: string; } export interface PendingMediated { diff --git a/src/company/testing.ts b/src/company/testing.ts index f95dced4..4057a2e5 100644 --- a/src/company/testing.ts +++ b/src/company/testing.ts @@ -45,6 +45,7 @@ import { type PendingAuthorization, type PendingDevice, type PendingMediated, + type PushedAuthorization, type ReplayMark, type SignInAttempts, type StoredConversation, @@ -124,6 +125,7 @@ export function recordSamples(now: Date): Readonly> { revoked: true, family: "fam_1", signedInAt: now.toISOString(), + dpopJkt: "jkt", } satisfies AccountGrant, [RecordKinds.accountFamily]: { clientId: "c", @@ -155,7 +157,15 @@ export function recordSamples(now: Date): Readonly> { expiresAt: later, clientName: "Atlas", browserBinding: "bind", + prompt: "consent", + dpopJkt: "jkt", } satisfies PendingAuthorization, + [RecordKinds.pushedRequest]: { + clientId: "c", + parameters: { response_type: "code", scope: "a" }, + expiresAt: later, + dpopJkt: "jkt", + } satisfies PushedAuthorization, [RecordKinds.code]: { clientId: "c", redirectUri: "https://atlas.example/cb", @@ -164,6 +174,7 @@ export function recordSamples(now: Date): Readonly> { accountId: "acct_1", scopes: ["a"], expiresAt: later, + dpopJkt: "jkt", } satisfies IssuedCode, [RecordKinds.mediated]: { clientId: "c", diff --git a/src/company/verify.ts b/src/company/verify.ts index 1c52df44..e8debfb1 100644 --- a/src/company/verify.ts +++ b/src/company/verify.ts @@ -6,6 +6,8 @@ /** Verify a personal agent's client assertions, Session JWTs and DPoP proofs (§4.1, §4.5, §5.3). */ +import { Buffer } from "node:buffer"; + import { compactVerify, decodeJwt, @@ -36,8 +38,33 @@ import type { ClientMetadata, JsonWebKeySet } from "../models.js"; import { SecretValue } from "../secret.js"; import type { ReplayCache } from "./points.js"; -/** Companies accept client assertions and delegations signed with these (§4.1, §5.2). */ +/** + * Companies accept client assertions and delegations signed with these (§4.1, §5.2): both are + * required from 1.0. + */ const ALGORITHMS = new Set(["ES256", "PS384"]); +/** + * The RSA key sizes accepted for `PS384`, in bits (guides, *Signing and verifying JWTs*): 2048 to + * 4096. A smaller key is weak, a larger one costly to verify. + */ +export const RSA_KEY_BITS = [2048, 4096] as const; + +/** + * Whether a verifying key's size is accepted, read from the JWK before it is imported: an RSA key + * of 2048 to 4096 bits (`RSA_KEY_BITS`); an EC key's curve is `ES256`'s. + */ +function keySizeAccepted(jwk: Readonly>): boolean { + if (jwk.kty !== "RSA") return true; + const modulus = typeof jwk.n === "string" ? jwk.n : ""; + if (!/^[A-Za-z0-9_-]+$/.test(modulus)) return false; + const bytes = Buffer.from(modulus, "base64url"); + let start = 0; + while (start < bytes.length && bytes[start] === 0) start += 1; + if (start === bytes.length) return false; + const bits = (bytes.length - start - 1) * 8 + (32 - Math.clz32(bytes[start] as number)); + const [low, high] = RSA_KEY_BITS; + return low <= bits && bits <= high; +} /** * An assertion lives at most this long: `exp` at most five minutes after `iat` (§4.1). * The SDKs' own assertions live 60 seconds. @@ -137,6 +164,7 @@ async function decode( for (const key of keys.keys) { if (kid !== undefined && key.kid !== undefined && key.kid !== kid) continue; if (key.alg !== undefined && key.alg !== algorithm) continue; + if (!keySizeAccepted(key)) continue; const publicKey = await importJWK({ ...key } as JWK, algorithm); try { const { payload } = await jwtVerify(compact, publicKey, { @@ -298,6 +326,7 @@ export async function verifyDelegation( } let claims: Record; try { + if (!keySizeAccepted(key)) throw new RangeError("an RSA key is 2048 to 4096 bits"); claims = await verifiedClaims(compact, { ...key } as JWK, algorithm); } catch (cause) { throw refused("The delegation's signature is invalid", cause); diff --git a/src/conversations.ts b/src/conversations.ts index 62753649..aca0d4d7 100644 --- a/src/conversations.ts +++ b/src/conversations.ts @@ -9,9 +9,11 @@ import type { ReactorPlatformView } from "@datalayer/reactor"; import { ConversationError, ProtocolValidationError } from "./errors.js"; import { parseJsonStrict } from "./json.js"; import { + clearsContext, parseConversationEvent, parseConversationEventPage, parseMessage, + parseVersion, type ConversationEvent, type ConversationEventPage, type ConversationResponder, @@ -219,7 +221,7 @@ export class ConversationClient { options: StartConversationOptions, ): Promise { const body: Record = { id: this.#requestId(options.requestId, message) }; - if (message !== undefined) body.message = this.#outgoing(message); + if (message !== undefined) body.message = this.#outgoing(message, options.session); if (options.parentConversationId !== undefined) { assertIdentifier(options.parentConversationId, "parent conversation ID"); body.parent_conversation_id = options.parentConversationId; @@ -289,7 +291,7 @@ export class ConversationClient { : message; return this.#send( `${endpoint.replace(/\/$/, "")}/${conversationId}/messages`, - { id: this.#requestId(options.requestId, message), message: this.#outgoing(written) }, + { id: this.#requestId(options.requestId, message), message: this.#outgoing(written, options.session) }, 202, options, ); @@ -595,6 +597,10 @@ export class ConversationClient { throw new ConversationError("sse_unsupported", "the company does not stream this conversation"); } for await (const frame of sseFrames(response.body, this.#maxResponseBytes)) { + if (frame.event !== undefined && !STREAM_EVENT_NAMES.has(frame.event)) { + // A name a later version or an extension adds (§8.6): skipped. + continue; + } if (frame.event === "working") { // No recorded event: `working` as the company sends it (§8.6). yield parseWorking(frame.data); @@ -669,8 +675,13 @@ export class ConversationClient { return parsed; } - /** The message as sent: no `id` (the request's is top-level) and no `role` (§8.4). */ - #outgoing(message: Message): Message { + /** + * The message as sent: no `id` (the request's is top-level) and no `role` (§8.4). + * + * A `context` field set to `null` clears it from 1.0 (§8.4): a Session at 0.4 doesn't send one, + * since each side sends only what the other's version defines (§3.4). + */ + #outgoing(message: Message, session: PapSession): Message { const parsed = parseMessage(message); if (parsed.role !== undefined) { throw new ProtocolValidationError( @@ -678,6 +689,12 @@ export class ConversationClient { "outgoing messages cannot set role", ); } + if (clearsContext(parsed) && parseVersion(session.protocolVersion)[0] < 1) { + throw new ProtocolValidationError( + "context_clear_unsupported", + `clearing a context field with null is version 1.0's: this Session is at ${session.protocolVersion}`, + ); + } const { id: _id, ...rest } = parsed; return rest as Message; } @@ -781,7 +798,8 @@ export class ConversationClient { } if (response.status !== expectedStatus) { // In the JSON body, or a token error in WWW-Authenticate (§3.3, §7). - const error = refusalCode(response, payload, "conversation_request_failed"); + const sent = refusalCode(response, payload, "conversation_request_failed"); + const error = knownConversationError(sent); const openId = error === "direct_conversation_open" && typeof (payload as Record).conversation_id === "string" && @@ -799,6 +817,8 @@ export class ConversationClient { ...(error === "version_mismatch" && typeof startedIn === "string" && /^[0-9]+\.[0-9]+$/.test(startedIn) ? { protocol_version: startedIn } : {}), + // A code this version doesn't define, as sent: handled by the HTTP status (§8.13). + ...(sent === error ? {} : { error: sent }), }; throw new ConversationError( error, @@ -813,6 +833,49 @@ export class ConversationClient { } } +/** + * The SSE event names this version defines (§8.6): `message`, the default, for recorded events, + * `working` and `text-delta`. A Personal Agent skips any other. + */ +const STREAM_EVENT_NAMES: ReadonlySet = new Set(["message", "working", "text-delta"]); + +/** + * The conversation error codes this version defines (§7, §8.13, §5.6, §3.3): a code outside them + * is handled by the response's HTTP status, as an error with no code is. + */ +export const KNOWN_CONVERSATION_ERRORS: ReadonlySet = new Set([ + "conversation_not_found", + "conversation_closed", + "direct_conversation_open", + "request_id_conflict", + "invalid_cursor", + "cursor_expired", + "invalid_request", + "extension_required", + "version_mismatch", + "version_unsupported", + "invalid_session", + "session_ended", + "invalid_token", + "insufficient_scope", + "invalid_dpop_proof", + "use_dpop_nonce", + "rate_limited", + "temporarily_unavailable", + // The Operations extension's (Operations 6), for a Session that declares it. + "approval_declined", + "action_failed", +]); + +/** + * `code` when this version defines it, else `fallback`: an error a later version or an extension + * adds is handled by the response's HTTP status (§8.13, RFC 9110 §15), as an error with no code + * is. The `ConversationError` keeps the status, and the code as sent in `details.error`. + */ +export function knownConversationError(code: string, fallback = "conversation_request_failed"): string { + return KNOWN_CONVERSATION_ERRORS.has(code) ? code : fallback; +} + function parseConversationResponse(value: unknown): ConversationResponse { if (typeof value !== "object" || value === null || Array.isArray(value)) { throw new ConversationError( diff --git a/src/demo/manzanita.ts b/src/demo/manzanita.ts index 139e67d5..c102d6c0 100644 --- a/src/demo/manzanita.ts +++ b/src/demo/manzanita.ts @@ -146,6 +146,7 @@ export const CONFIG_OPTIONS: CompanyConfigOptions = { name: "Manzanita Outfitters", domain: DOMAIN, scopes: ["orders:read", "orders:write"], + agentDescription: "Anything about your orders, returns, and our outdoor gear", writeScopes: ["orders:write"], links: true, disclosures: true, diff --git a/src/device.ts b/src/device.ts index 7594d8bd..b0aa6322 100644 --- a/src/device.ts +++ b/src/device.ts @@ -8,6 +8,7 @@ import type { ReactorPlatformView } from "@datalayer/reactor"; import { AuthorizationError } from "./errors.js"; import { parseJsonStrict } from "./json.js"; +import { domainHost } from "./models.js"; import { AuthorizationStateStores, Clocks, @@ -68,7 +69,8 @@ export function verificationHostAllowed( options: { readonly issuer: string; readonly domain: string }, ): boolean { const host = hostOf(url); - const allowed = [hostOf(options.issuer), options.domain.toLowerCase().replace(/\.+$/, "")]; + // The host of `organization.domain`, without the port it names from 1.0 (§3.1). + const allowed = [hostOf(options.issuer), domainHost(options.domain)]; return host !== "" && allowed.some((name) => name !== "" && within(host, name)); } diff --git a/src/discovery.ts b/src/discovery.ts index c9c20197..fe00f5ab 100644 --- a/src/discovery.ts +++ b/src/discovery.ts @@ -20,6 +20,8 @@ import { parseOAuthServerMetadata, parseProtectedResourceMetadata, protectedResourceMetadataUrl, + splitDomain, + urlDomain, type DiscoveredCompany, type DiscoveryDocument, type SkillEntry, @@ -56,19 +58,37 @@ export interface DiscoveryOptions { readonly fresh?: boolean; /** * The protocol versions this Personal Agent implements (§3.4): `SUPPORTED_PROTOCOL_VERSIONS`, - * the 1.0 draft, by default. Name `PROTOCOL_PROFILE` among them to use Companies that serve - * only 0.4 as published, such as `["0.4", "1.0"]`; the newest compatible version a Company - * serves is chosen. + * 1.0, by default. Name `PROTOCOL_PROFILE` among them to use Companies that serve only 0.4 as + * published, such as `["0.4", "1.0"]`; the newest compatible version a Company serves is + * chosen. */ readonly protocolVersions?: Iterable; + /** + * Use a Company on a port other than 443, such as `shop.example:8443` for testing: from 1.0 + * its `organization.domain` includes the port (§3.1). Off by default: a Personal Agent uses + * such a Company only when configured to on purpose; otherwise `port_not_allowed`. + */ + readonly allowPorts?: boolean; } -function normalizeDomain(domain: string): string { - const value = domain.replace(/\.$/, "").toLowerCase(); +function normalizeDomain(domain: string, allowPorts: boolean): string { + const value = domain.toLowerCase(); if (!value || value.includes("://") || value.includes("/")) { throw new DiscoveryError("invalid_domain", "Discovery requires a DNS domain name"); } - return value; + let split: readonly [string, number | undefined]; + try { + split = splitDomain(value); + } catch (cause) { + throw new DiscoveryError("invalid_domain", "Discovery requires a DNS domain name", { cause }); + } + const [rawHost, port] = split; + if (port !== undefined && !allowPorts) { + throw new DiscoveryError("port_not_allowed", "A domain with a port is used only with allowPorts (§3.1)"); + } + const host = rawHost.replace(/\.$/, ""); + if (!host) throw new DiscoveryError("invalid_domain", "Discovery requires a DNS domain name"); + return port === undefined ? host : `${host}:${port}`; } /** @@ -286,7 +306,7 @@ function readOptions(options: DiscoveryOptions): { reactor: ReactorPlatformView; * (§3.4). `fresh` reads `poppy.json` again, not a cached copy. */ async function discover(domain: string, options: DiscoveryOptions): Promise { - const requestedDomain = normalizeDomain(domain); + const requestedDomain = normalizeDomain(domain, options.allowPorts === true); const { read } = readOptions(options); const poppyUrl = new URL(`https://${requestedDomain}/.well-known/poppy.json`); if (options.fresh) await read.cache.delete(`pap.metadata:${poppyUrl.toString()}`); @@ -312,7 +332,14 @@ async function discover(domain: string, options: DiscoveryOptions): Promise>; */ export const SUPPORTED_PROTOCOL_VERSIONS: ReadonlySet = new Set([DEFAULT_PROTOCOL_VERSION]); /** - * Every protocol version this SDK implements: 0.4 as published and the 1.0 draft. A Personal + * Every protocol version this SDK implements: 0.4 and 1.0, both as published. A Personal * Agent (`discoverCompany(domain, { protocolVersions })`) or a Company * (`CompanyConfigOptions.protocolVersions`) uses 0.4 only when it names it. */ @@ -270,10 +270,20 @@ export interface AuthCapabilities extends UnknownFields { readonly scope_hints: Readonly>; } -/** A conversation protocol the Company Agent speaks (§3.1, §8); read `access` with `accountAccess`. */ +/** + * A conversation protocol the Company Agent speaks (§3.1, §8.1); read `access` with + * `accountAccess`. + * + * `description` says, in plain language, what the agent at `endpoint` can help with, so the + * Personal Agent can decide whether a conversation serves the task at hand and choose between + * the entries and the Company's APIs. Required from 1.0: `parseDiscoveryDocument` refuses a 1.0 + * document whose entry has none; 0.4 doesn't define it. `access` is kept as written, whatever it + * says. + */ export interface AgentProtocol extends UnknownFields { readonly type: string; readonly endpoint: string; + readonly description?: string; readonly access?: string; } @@ -422,7 +432,12 @@ export interface OAuthServerMetadata extends UnknownFields { readonly protected_resources: readonly string[]; readonly authorization_endpoint?: string; readonly device_authorization_endpoint?: string; + /** + * Where Direct Sign-In's request is pushed (RFC 9126, §3.2, §4.2): a Personal Agent SHOULD + * push whenever it is listed, and MUST when `require_pushed_authorization_requests`. + */ readonly pushed_authorization_request_endpoint?: string; + readonly require_pushed_authorization_requests: boolean; readonly scopes_supported?: readonly string[]; readonly dpop_signing_alg_values_supported?: readonly string[]; } @@ -440,15 +455,16 @@ export function offersDevice(metadata: OAuthServerMetadata): boolean { /** * Whether `protected_resources` names `https://{domain}` (§3.2). * - * Exactly, except that the host compares ignoring case: an entry with a path, a port or - * a trailing slash does not match. + * Exactly, except that the host compares ignoring case: an entry with a path or a trailing + * slash does not match, nor one whose port isn't the domain's. From 1.0 a domain includes its + * port when that isn't 443, and so does its entry (§3.1, §3.2). */ export function listsResource(metadata: OAuthServerMetadata, domain: string): boolean { const wanted = domain.toLowerCase().replace(/\.$/, ""); return metadata.protected_resources.some((entry) => { if (!entry.startsWith("https://")) return false; const host = entry.slice("https://".length); - return Boolean(host) && !/[/?#:@]/.test(host) && host.toLowerCase() === wanted; + return Boolean(host) && !/[/?#@]/.test(host) && host.toLowerCase() === wanted; }); } @@ -726,9 +742,11 @@ export function knownHandoff(value: unknown, label = "handoff"): ConversationHan /** * Where a conversation stands, in four fields each independent of the others (§8.7). * - * `working` is true while the Company has work in progress: a request it accepted but hasn't - * acted on, a reply being written, or work it started on its own; a Personal Agent that wants - * the whole reply reads until it is false. `handoff` is `pending` while the Company looks for + * `working` is true only while the Company is still replying: a request it accepted but hasn't + * acted on, or a reply being written (§8.7, from 1.0). Work it finishes later, such as a refund + * that takes days, isn't `working`: the Company says so in a message, and adds another when it's + * done. A Personal Agent that wants the whole reply reads until it is false. `handoff` is + * `pending` while the Company looks for * a person (§8.9). `responder` is who handles the Company side. `closed` means the conversation * takes no more messages (§8.12). A new conversation starts with `handoff` `none`, `responder` * `agent` and `closed` false. @@ -772,12 +790,50 @@ export interface ConversationEvent extends UnknownFields { readonly handoff?: ConversationHandoff; readonly responder?: ConversationResponder; readonly closed?: boolean; - readonly error?: "insufficient_scope"; + /** + * An `authorization` event's error (§8.11): `insufficient_scope`, or a value a later version + * adds. Whatever it says, the Personal Agent signs in again for `scope` (`signInScopes`). + */ + readonly error?: string; readonly scope?: string; readonly reason?: string; readonly conversation_id?: string; } +/** + * For an `authorization` event, the scopes to sign in again for (§5.4, §8.11): those in `scope`, + * once each, whatever `error` says, a value this SDK doesn't recognize included. Empty for any + * other event. + */ +export function signInScopes(event: ConversationEvent): readonly string[] { + if (event.type !== "authorization" || !event.scope) return []; + return [...new Set(event.scope.split(" ").filter(Boolean))]; +} + +/** + * The context the Personal Agent's messages share, in order (§8.4): fields a message leaves out + * keep their previous values, and a field set to `null` is cleared, as if it had never been + * shared (from 1.0). + */ +export function effectiveContext(messages: Iterable>): Record { + const shared: Record = {}; + for (const message of messages) { + for (const [name, value] of Object.entries(message.context ?? {})) { + if (value === null) delete shared[name]; + else shared[name] = value; + } + } + return shared; +} + +/** + * Whether a message sets a `context` field to `null` to clear it (§8.4): 1.0's, so a Personal + * Agent sends it only in a Session at 1.0 or later (§3.4). + */ +export function clearsContext(message: Pick): boolean { + return Object.values(message.context ?? {}).some((value) => value === null); +} + /** * A cursor page returned by a read or a waited write, with the conversation's state when the * Company responded (§8.5, §8.7). While `has_more` is true the state fields can be newer than @@ -1138,15 +1194,67 @@ function httpsUrl(value: unknown, label: string): string { } function domain(value: unknown, label: string): string { - const result = string(value, label).replace(/\.$/, "").toLowerCase(); + const normalized = string(value, label).toLowerCase(); + let split: readonly [string, number | undefined]; + try { + split = splitDomain(normalized); + } catch (cause) { + throw new ProtocolValidationError("invalid_domain", `${label} must be a DNS domain`, { cause }); + } + const host = split[0].replace(/\.$/, ""); if ( !/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test( - result, + host, ) ) { - throw new ProtocolValidationError("invalid_domain", `${label} must be a DNS domain`); + throw new ProtocolValidationError( + "invalid_domain", + `${label} must be a DNS domain, with its port when that isn't 443`, + ); } - return result; + return split[1] === undefined ? host : `${host}:${split[1]}`; +} + +/** + * `organization.domain` as its host and its port, `undefined` for 443 (§3.1). + * + * From 1.0 a domain includes its port when that isn't 443, such as `shop.example:8443`; + * `RangeError` for a port that isn't a number from 1 to 65535, or `:443`, which a domain never + * names. + */ +export function splitDomain(domain: string): readonly [host: string, port: number | undefined] { + const colon = domain.lastIndexOf(":"); + if (colon < 0) return [domain, undefined]; + const host = domain.slice(0, colon); + const port = domain.slice(colon + 1); + if (!/^[1-9][0-9]*$/.test(port) || Number(port) > 65535) { + throw new RangeError("a domain's port is a number from 1 to 65535"); + } + if (Number(port) === 443) throw new RangeError("a domain names its port only when that isn't 443"); + return [host, Number(port)]; +} + +/** The host of `organization.domain`, without the port it names (§3.1). */ +export function domainHost(domain: string): string { + return splitDomain(domain)[0].replace(/\.+$/, "").toLowerCase(); +} + +/** + * The domain an HTTPS URL is on, as `organization.domain` names it (§3.1): its host, lowercase, + * with its port when that isn't 443. `undefined` for another scheme, user information or an + * invalid URL. + */ +export function urlDomain(url: string): string | undefined { + let parsed: URL; + try { + parsed = new URL(url); + } catch { + return undefined; + } + if (parsed.protocol !== "https:" || !parsed.hostname || parsed.username || parsed.password) return undefined; + const host = parsed.hostname.toLowerCase().replace(/\.+$/, ""); + // WHATWG URL drops the scheme's default port: `port` is empty for 443. + return parsed.port === "" || parsed.port === "443" ? host : `${host}:${parsed.port}`; } function scopes(value: unknown, label: string): ScopeOption { @@ -1205,6 +1313,13 @@ export function parseDiscoveryDocument( ? {} : { logo_uri: httpsUrl(organizationSource.logo_uri, "organization.logo_uri") }), } as Organization; + if (parseVersion(version)[0] < 1 && splitDomain(organization.domain)[1] !== undefined) { + // A port in organization.domain is 1.0's (§3.1); 0.4 names a host only. + throw new ProtocolValidationError( + "invalid_domain", + "organization.domain names a port only from version 1.0", + ); + } let auth: AuthCapabilities | undefined; if (source.auth !== undefined) { @@ -1260,10 +1375,22 @@ export function parseDiscoveryDocument( if (protocol.access !== undefined && typeof protocol.access !== "string") { throw new ProtocolValidationError("invalid_type", `agent.protocols[${index}].access must be a string`); } + const description = + protocol.description === undefined || protocol.description === null + ? undefined + : string(protocol.description, `agent.protocols[${index}].description`); + if (description === undefined && parseVersion(version)[0] >= 1) { + // Every conversation protocol says what its agent helps with (§3.1, §8.1). + throw new ProtocolValidationError( + "invalid_agent", + `agent.protocols[${index}] needs a description from version 1.0`, + ); + } return { ...protocol, type: string(protocol.type, `agent.protocols[${index}].type`), endpoint: httpsUrl(protocol.endpoint, `agent.protocols[${index}].endpoint`), + ...(description === undefined ? {} : { description }), } as AgentProtocol; }); if (protocols.length === 0) { @@ -1424,6 +1551,10 @@ export function parseOAuthServerMetadata(value: unknown): OAuthServerMetadata { const item = source[name]; return item === undefined || item === null ? {} : { [name]: httpsUrl(item, name) }; }; + const requirePushed = + source.require_pushed_authorization_requests === undefined || source.require_pushed_authorization_requests === null + ? false + : boolean(source.require_pushed_authorization_requests, "require_pushed_authorization_requests"); const metadata = { ...source, // Compared with `auth.issuer` character for character (§3.2): never normalized. @@ -1433,6 +1564,7 @@ export function parseOAuthServerMetadata(value: unknown): OAuthServerMetadata { ...endpoint("authorization_endpoint"), ...endpoint("device_authorization_endpoint"), ...endpoint("pushed_authorization_request_endpoint"), + require_pushed_authorization_requests: requirePushed, grant_types_supported: grants, protected_resources: resources, ...(scopesSupported === undefined ? {} : { scopes_supported: scopesSupported }), @@ -1450,6 +1582,13 @@ export function parseOAuthServerMetadata(value: unknown): OAuthServerMetadata { "the device grant needs device_authorization_endpoint", ); } + if (metadata.require_pushed_authorization_requests && metadata.pushed_authorization_request_endpoint === undefined) { + // A Company that requires PAR lists where to push (RFC 9126 §5). + throw new ProtocolValidationError( + "invalid_oauth_metadata", + "require_pushed_authorization_requests needs pushed_authorization_request_endpoint", + ); + } return metadata; } @@ -1710,30 +1849,54 @@ function ianaZone(value: unknown): boolean { } } -/** The facts §7.4 defines use its field names and formats; others pass through. */ +/** + * The facts §7.4 defines use its field names and formats; others pass through. A field set to + * `null` clears it (§8.4, from 1.0): see `effectiveContext`. + */ function messageContext( context: Readonly> | undefined, ): Readonly> | undefined { if (context === undefined) return context; const { locale, time_zone: zone, user_available: available } = context; - if (locale !== undefined && (typeof locale !== "string" || !LOCALE.test(locale))) { + if (locale !== undefined && locale !== null && (typeof locale !== "string" || !LOCALE.test(locale))) { throw new ProtocolValidationError("invalid_message", "context.locale must be a language tag such as en-US"); } - if (zone !== undefined && !ianaZone(zone)) { + if (zone !== undefined && zone !== null && !ianaZone(zone)) { throw new ProtocolValidationError("invalid_message", "context.time_zone must be an IANA time zone name"); } - if (available !== undefined && typeof available !== "boolean") { + if (available !== undefined && available !== null && typeof available !== "boolean") { throw new ProtocolValidationError("invalid_message", "context.user_available must be true or false"); } return context; } +/** The `author.type` values this version defines (§8.4). */ +export const AUTHOR_TYPES = ["agent", "human"] as const; +/** The message roles this version defines (§8.4). */ +export const MESSAGE_ROLES = ["user", "company"] as const; + +/** + * An `author.type` this SDK doesn't recognize reads as `agent` (§8.4): a message is a person's + * own words only when it says so. A value that isn't a string is returned as it is. + */ +export function knownAuthorType(value: unknown): unknown { + return typeof value !== "string" || (AUTHOR_TYPES as readonly string[]).includes(value) ? value : "agent"; +} + +/** + * A `role` this SDK doesn't recognize reads as `company` (§8.4): content from the Company, never + * the User's (§10.1). A value that isn't a string is returned as it is. + */ +export function knownRole(value: unknown): unknown { + return typeof value !== "string" || (MESSAGE_ROLES as readonly string[]).includes(value) ? value : "company"; +} + /** Who wrote a message (§7.4): `type`, and the Company's optional `id`, `name`, `image`. */ export function parseAuthor(value: unknown): Author { const source = nullsAbsent(value, "message.author", ["id", "name", "image"]); return { ...source, - type: oneOf(source.type, ["agent", "human"] as const, "message.author.type"), + type: oneOf(knownAuthorType(source.type), AUTHOR_TYPES, "message.author.type"), ...(source.id === undefined ? {} : { id: identifier(source.id, "message.author.id") }), ...(source.name === undefined ? {} : { name: string(source.name, "message.author.name") }), ...(source.image === undefined @@ -1756,7 +1919,7 @@ export function parseMessage(value: unknown): Message { ); } const author = parseAuthor(source.author); - const role = source.role === undefined ? undefined : oneOf(source.role, ["user", "company"] as const, "message.role"); + const role = source.role === undefined ? undefined : oneOf(knownRole(source.role), MESSAGE_ROLES, "message.role"); const asOfRequest = source.as_of_request === undefined ? undefined : identifier(source.as_of_request, "message.as_of_request"); const asOfCursor = source.as_of_cursor === undefined ? undefined : identifier(source.as_of_cursor, "message.as_of_cursor"); // Only messages written by an AI say what they took into account (§8.4): a person types @@ -1813,15 +1976,7 @@ export function parseConversationEvent(value: unknown): ConversationEvent { responder: knownResponder(source.responder, "conversation event.responder"), }), ...(source.closed === undefined ? {} : { closed: boolean(source.closed, "conversation event.closed") }), - ...(source.error === undefined - ? {} - : { - error: oneOf( - source.error, - ["insufficient_scope"] as const, - "conversation event.error", - ), - }), + ...(source.error === undefined ? {} : { error: string(source.error, "conversation event.error") }), ...(source.scope === undefined ? {} : { scope: string(source.scope, "conversation event.scope") }), ...(source.reason === undefined ? {} @@ -1844,7 +1999,7 @@ export function parseConversationEvent(value: unknown): ConversationEvent { ) { throw new ProtocolValidationError("invalid_event", "a state event requires handoff, responder and closed"); } - // Always both: the error, and the scopes the request needs (§7.11). + // Always both: the error, whatever it says, and the scopes the request needs (§8.11). if (type === "authorization" && (parsed.error === undefined || !parsed.scope)) { throw new ProtocolValidationError( "invalid_event", diff --git a/src/pages.ts b/src/pages.ts index cc1c98cb..4a1f6111 100644 --- a/src/pages.ts +++ b/src/pages.ts @@ -45,7 +45,7 @@ */ import { TransportError } from "./errors.js"; import { readLimited } from "./limits.js"; -import type { DiscoveredCompany, DiscoveryDocument } from "./models.js"; +import { urlDomain, type DiscoveredCompany, type DiscoveryDocument } from "./models.js"; import { UrlSafetyPolicies, optionalContribution } from "./reactor.js"; import { REDIRECT_STATUSES } from "./refusals.js"; import type { PapSession } from "./sessions.js"; @@ -72,22 +72,11 @@ export interface FetchedPage { /** * Whether a page fetch carries the Session header (§5.2): an HTTPS URL whose host is exactly - * `organization.domain`, compared ignoring case, on the default port. + * `organization.domain`, compared ignoring case, on its port: 443, or from 1.0 the one the + * domain names (§3.1). */ export function pageCarriesSession(url: string, domain: string): boolean { - let parsed: URL; - try { - parsed = new URL(url); - } catch { - return false; - } - return ( - parsed.protocol === "https:" && - parsed.hostname.toLowerCase() === domain.toLowerCase().replace(/\.+$/, "") && - parsed.port === "" && - !parsed.username && - !parsed.password - ); + return urlDomain(url) === domain.toLowerCase().replace(/\.+$/, ""); } /** A URL's origin and path: what names a document, whatever its query. */ diff --git a/src/profile.ts b/src/profile.ts index 093fe960..19f76f37 100644 --- a/src/profile.ts +++ b/src/profile.ts @@ -14,13 +14,15 @@ export const PROTOCOL_PROFILE = "0.4"; /** The upstream specification revision implemented: the day 0.4 was published (commit 4803900). */ export const PROTOCOL_REVISION = "2026-11-10"; -// DRAFT_PROTOCOL_VERSION is the 1.0 draft. Since 0.36 it is DEFAULT_PROTOCOL_VERSION, the -// version a Personal Agent or a Company uses unless it asks for others (`protocolVersions`): -// 0.4 as published stays available, used only when named. +// DRAFT_PROTOCOL_VERSION is version 1.0, a draft until upstream published and froze it on +// 2026-11-14, and DRAFT_PROTOCOL_REVISION the date of the text implemented: since 0.37, 1.0 as +// published (commit 8c02b42). The names stay from the draft. Since 0.36 it is +// DEFAULT_PROTOCOL_VERSION, the version a Personal Agent or a Company uses unless it asks for +// others (`protocolVersions`): 0.4 as published stays available, used only when named. -/** The draft protocol version, the 1.0 draft: the default since 0.36. */ +/** Protocol version 1.0, the default since 0.36 (named while it was the draft). */ export const DRAFT_PROTOCOL_VERSION = "1.0"; -/** The draft's revision implemented: lookalike domains, its first fix (commit c71f515). */ -export const DRAFT_PROTOCOL_REVISION = "2026-11-11"; -/** The version used unless a Personal Agent or a Company names others: the 1.0 draft. */ +/** The 1.0 text implemented: 1.0 as published and frozen on 2026-11-14 (commit 8c02b42). */ +export const DRAFT_PROTOCOL_REVISION = "2026-11-14"; +/** The version used unless a Personal Agent or a Company names others: 1.0. */ export const DEFAULT_PROTOCOL_VERSION = DRAFT_PROTOCOL_VERSION; diff --git a/src/reactor.ts b/src/reactor.ts index b143fea3..fed9fd1b 100644 --- a/src/reactor.ts +++ b/src/reactor.ts @@ -364,7 +364,7 @@ export function createPapCorePlugin(options: PapCoreOptions = {}) { } return definePlugin({ name: "@datalayer/personal-agent-protocol-core", - version: "0.36.1", + version: "0.37.0", contributionPoints: [ DiscoveryTransports, UrlSafetyPolicies, diff --git a/src/ucp.ts b/src/ucp.ts index ba60cf72..a41722ac 100644 --- a/src/ucp.ts +++ b/src/ucp.ts @@ -15,7 +15,9 @@ import { PersonalAgentProtocolError, SessionError, TransportError } from "./errors.js"; import { parseJsonStrict } from "./json.js"; import { readLimited } from "./limits.js"; -import { companyExtension, type DiscoveredCompany, type DiscoveryDocument } from "./models.js"; +import { scopesToRequest } from "./accounts.js"; +import { companyExtension, parseVersion, type DiscoveredCompany, type DiscoveryDocument } from "./models.js"; +import { DEFAULT_PROTOCOL_VERSION } from "./profile.js"; import { challengeParameters, refuseRedirect } from "./refusals.js"; import type { AccessToken, PapSession } from "./sessions.js"; import { sessionError, type SessionFetchClient } from "./transport.js"; @@ -126,9 +128,23 @@ export function ucpIdentityLinkingScopes(profile: UcpProfile): readonly string[] return scopes; } -/** The identity linking scopes not in `held`: UCP asks only for the missing ones (UCP extension 4). */ -export function ucpScopes(profile: UcpProfile, held: readonly string[] = []): readonly string[] { - return ucpIdentityLinkingScopes(profile).filter((scope) => !held.includes(scope)); +/** + * The scopes a sign-in requests after a UCP `insufficient_scope` (UCP extension 4). + * + * From 1.0, every scope the Personal Agent still needs, as spec 4.7 describes: the ones `held` + * that it wants to keep, then those the challenge names (`needed`, the profile's identity + * linking scopes when it names none), once each; the Company grants only what the request names. + * At 0.4, UCP's incremental authorization: only the identity linking scopes not `held`, and the + * Company keeps the earlier ones. + */ +export function ucpScopes( + profile: UcpProfile, + held: readonly string[] = [], + options: { readonly needed?: readonly string[]; readonly protocolVersion?: string } = {}, +): readonly string[] { + const wanted = options.needed?.length ? [...options.needed] : [...ucpIdentityLinkingScopes(profile)]; + if (parseVersion(options.protocolVersion ?? DEFAULT_PROTOCOL_VERSION)[0] >= 1) return scopesToRequest(held, wanted); + return wanted.filter((scope) => !held.includes(scope)); } /** Whether the Company lists the UCP extension at this version (UCP extension 2). */ From af0b11b139d9a85c762c75f96ef6c5121d7396fb Mon Sep 17 00:00:00 2001 From: Eric Charles Date: Tue, 17 Nov 2026 11:52:11 +0100 Subject: [PATCH 2/2] Python 3.10: read an RSA modulus with an explicit byte order --- personal_agent_protocol/company/verify.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/personal_agent_protocol/company/verify.py b/personal_agent_protocol/company/verify.py index 97d0148a..49df4a75 100644 --- a/personal_agent_protocol/company/verify.py +++ b/personal_agent_protocol/company/verify.py @@ -165,7 +165,7 @@ def _key_size_accepted(jwk_value: dict[str, Any]) -> bool: return True modulus = str(jwk_value.get("n", "")) try: - bits = int.from_bytes(base64.urlsafe_b64decode(modulus + "=" * (-len(modulus) % 4))) + bits = int.from_bytes(base64.urlsafe_b64decode(modulus + "=" * (-len(modulus) % 4)), "big") except (ValueError, TypeError): return False low, high = RSA_KEY_BITS