diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index c519b26..b3e1a1e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -82,6 +82,13 @@ jobs: WRANGLER_SEND_METRICS: "false" XDG_CONFIG_HOME: ${{ runner.temp }}/pda-company-kit-04-wrangler + - name: Pinned upstream 1.0 draft Company kit and reviewed findings + if: steps.scope.outputs.specialist == 'true' + run: node scripts/check-company-kit.mjs --protocol 1.0 --reviewed-findings --output "$RUNNER_TEMP/company-kit-1.0.json" + env: + WRANGLER_SEND_METRICS: "false" + XDG_CONFIG_HOME: ${{ runner.temp }}/pda-company-kit-10-wrangler + - name: Separate DPoP-capable kit copy and independent proof controls if: steps.scope.outputs.specialist == 'true' run: node scripts/check-company-kit.mjs --protocol 0.4 --with-dpop --reviewed-findings --output "$RUNNER_TEMP/company-kit-dpop.json" @@ -97,6 +104,7 @@ jobs: name: company-kit-results path: | ${{ runner.temp }}/company-kit-0.4.json + ${{ runner.temp }}/company-kit-1.0.json ${{ runner.temp }}/company-kit-dpop.json ${{ runner.temp }}/approval-crashes.json if-no-files-found: ignore diff --git a/.github/workflows/interop.yml b/.github/workflows/interop.yml index 76aaa5b..388992b 100644 --- a/.github/workflows/interop.yml +++ b/.github/workflows/interop.yml @@ -1,4 +1,4 @@ -# The interop grid: our agent against our mock Company, lenient and strict, +# The interop grid: our agent against our mock Company, lenient and strict at 1.0 and lenient at 0.4, # and against Print with Poppy, an independent Company at a pinned commit, # in containers behind the recording proxy (interop/). # Docker makes it slow, so it runs on pushes to main and on pull requests @@ -53,7 +53,7 @@ jobs: - run: npm ci --legacy-peer-deps - name: Honest agents and Companies, including injected network faults - run: npm run interop -- --agents pda --companies lenient-company,strict-company --require-supported --scenarios D,S0,N,SD,SV,SVN,SM,SMC,SX,SXV,C,CL,CC,CI,CS,CA,SO,O,OX,OU,SE,R,AO,AM,AS,RL,DP,H,DC,W,CM,ML,CDUP,CIDUP,ODUP,NREP + run: npm run interop -- --agents pda --companies lenient-company,strict-company,lenient-company-v04 --require-supported --scenarios D,S0,N,SD,SV,SVN,SM,SMC,SX,SXV,C,CL,CC,CI,CS,CA,SO,O,OX,OU,SE,R,AO,AM,AS,RL,DP,H,DC,W,CM,ML,CDUP,CIDUP,ODUP,NREP # The lenient and strict agents too: each reads the store's documents and tokens differently. - name: An independent Company, Print with Poppy at its pinned commit @@ -63,7 +63,7 @@ jobs: run: npm run interop -- --agents pda --companies evil-company --require-supported --scenarios XH,XI,BX,XB,XN,XP,XE,XR - name: Our Companies refuse malicious agent requests - run: npm run interop -- --agents evil-personal-agent --companies lenient-company,strict-company --require-supported --scenarios YR,YD,YA,YT,YS,YK,YU,YM + run: npm run interop -- --agents evil-personal-agent --companies lenient-company,strict-company,lenient-company-v04 --require-supported --scenarios YR,YD,YA,YT,YS,YK,YU,YM - name: Upload the grid, HAR files and container logs if: always() diff --git a/CHANGELOG.md b/CHANGELOG.md index cc5ad59..b4da26b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -2,6 +2,25 @@ Release notes and upgrade instructions for PDA. Entries are newest first, inspired by [Pi's changelog](https://pi.dev/changelog). PDA's release number is separate from the Poppy version it speaks. **Unreleased entries describe repository changes, not a deployed release.** +## Unreleased — the 1.0 draft beside 0.4 + +The agent, the mock Company and the validator speak the 1.0 draft retrieved on 13 November at 15:48 UTC (upstream `bb98332`) beside 0.4 ([decision 51](docs/decisions.md#51-10-beside-04)). The [1.0 upgrade](docs/poppy-1.0-upgrade.md) gives each of its 15 changelog entries a disposition. + +**On upgrade:** a Company that offers 1.0 is used at 1.0 from its next request: the Session restarts with the new declaration and keeps its account, and an open conversation keeps the version it started in (8.2). The new `poppy_dpop_keys` and `poppy_dpop_nonces` tables are created on first use. Keys held in memory before the update are lost with the restart, so each issuer's first refresh afterwards uses a new key, which is then stored; no live Company binds refresh tokens to a key yet. + +- `PROTOCOL_VERSIONS` is `0.4` and `1.0`. Discovery uses the newest version a Company offers that is compatible with one the agent speaks. From 1.0 a newer minor version is compatible, so a Company serving 1.1 is used as 1.0, and every request declares `Poppy-Version: 1.0`. +- Under 1.0 each `agent.protocols` entry needs a `description`, and discovery refuses a 1.0 Company without one. `poppy_discover` gives the model the description, to choose between the Company's agent and its APIs. +- When an issuer lists `pushed_authorization_request_endpoint`, under either version, the Direct Sign-In card links to the agent's new `/poppy/sign-in` page. Opening it pushes the request with the client assertion and a DPoP proof, then redirects to the authorization endpoint with only `client_id` and `request_uri`. A browser not signed in to PDA is asked to sign in first, and nothing is pushed. +- DPoP keys are stored, sealed, by issuer and User ID, so a refresh after a restart or eviction uses the key the refresh token was issued with (1.0 4.4). The latest nonce from each server is stored too, so those proofs keep carrying it. Both tables are withheld from the data export. +- Direct Sign-In requests to a 1.x Company carry `prompt=consent`, so the Company shows its consent page even for scopes the account granted before (1.0 4.2, 10.8). +- A conversation message with a `role` the agent doesn't know is relayed as the Company's content, where it was dropped. In a 1.x conversation, a stream event with an SSE name the agent doesn't know is skipped (1.0 8.4, 8.6). +- `poppy_discover` tells the model that a Company's name comes from its own `poppy.json`, and to show the User the domain with it when unsure (1.0 10.3 and its guides). +- Fixed: the Worker forwarded `/poppy/*` requests to the person's agent with `redirect: "follow"`, so a redirect from the agent would have been followed inside the Worker rather than reaching the browser. The callback never redirected; the new sign-in page does. +- The validator has a 1.0 profile: 0.4's rules with the required descriptions (`protocol-description-empty`), a port other than 443 allowed in `organization.domain`, and ES256 and PS384 required in an issuer's listed client-assertion algorithms (`metadata-assertion-algs`). Under both versions it checks the PAR endpoint is HTTPS and reports `require_pushed_authorization_requests` without it (`par-endpoint-missing`). A newer 1.x document is checked with the 1.0 profile and noted (`version-newer-minor`). +- The mock serves 1.0 and 1.1, describes its protocols under 1.x, can offer or require PAR (`pushedAuthorization`), bind refresh tokens to their key (`bindRefreshTokens`) and stream an event a later version might add (`laterStreamEvent`). Under 1.x it takes a `context` field set to `null` as cleared. New checks: `authorize.prompt-consent`, `par.not-pushed`, `par.extra-parameters`, `par.code-key` and `dpop.refresh-key-changed`. +- The 1.0 snapshot, kit and requirement ledger are pinned in `spec/`. CI runs the 1.0 kit against the mock with [reviewed findings](test/company-kit/reviewed-findings-1.0.json), the same as the 0.4 kit's. Each request the agent sends is checked against the schemas of the kit for the version it declares. +- The Python Hypothesis client speaks 1.0 beside 0.4, and each run draws the version the mock serves, PAR and bound refresh tokens. The interop grid's `lenient-company` and `strict-company` serve 1.0, and a new `lenient-company-v04` keeps 0.4 in CI. + ## Unreleased — asking to contact a Company, amounts in cents, and checkout links that aren't ready - When the User's request names a Company they haven't selected, the agent asks on a card with the domain, the Company's own name and the photos it would send. **Allow** sends a message from the composer that selects them; the card grants nothing itself, only a run the User started can ask, and a domain without a `poppy.json` the agent can use gets no card ([decision 50](docs/decisions.md#50-the-agent-can-ask-to-contact-a-company)). Its tool line reads "Asked you to let your agent contact shop.example", and `scripts/app-smoke.mjs --company-access-journey` follows it in Chromium from the card to the Company's terms. diff --git a/README.md b/README.md index de9a4bc..e50d98a 100644 --- a/README.md +++ b/README.md @@ -2,21 +2,21 @@ **A Personal Agent for [Poppy](https://personalagentprotocol.org/), the Personal Agent Protocol, built alongside the tools we used to test it: a validator, a strict mock Company, an interop harness, and written-up spec issues for each draft.** It is for the draft's authors and for people implementing either side of the protocol. -Poppy is a draft standard. PDA speaks **0.4 alone**, the 1.0 release candidate published on 10 November 2026 and retrieved on 11 November; it dropped 0.3 on 12 November ([decision 49](docs/decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)), and 0.1 and 0.2 on 28 October ([decision 37](docs/decisions.md#37-03-alone-what-dropping-01-and-02-overturns-and-settles)) ([changelog](CHANGELOG.md), [upgrade procedure](docs/upgrading.md)). This project's agent runs on Cloudflare Workers with one Durable Object per person and Claude Sonnet 5.5 through Pi. It finds a Company that publishes `poppy.json`, names a Session on every request with a signed `Poppy-Session` header, has you sign in on the Company's own page when it needs your account, talks to the Company's agent, calls its APIs, and asks you on the page when the Company returns an operation for approval. The status is alpha. At 0.1 and 0.2 the deployed agent signed in and out at one live Company, Alpine Retail, a colleague's test store (13 and 14 October), and got as far as asking to upload a photo at print-with-poppy's live store (12 October) ([live evidence](docs/history/live-0.2-testing.md)). The [current verification report](docs/poppy-0.4-conformance.md#current-verification) records the 0.4 checks and live limits; the [0.3 review](docs/poppy-0.3-conformance.md) keeps 0.3's independent demo evidence. +Poppy is a draft standard. PDA speaks **0.4**, the 1.0 release candidate published on 10 November 2026 and retrieved on 11 November, and beside it the **1.0 draft** retrieved on 13 November ([decision 51](docs/decisions.md#51-10-beside-04), not yet deployed); it dropped 0.3 on 12 November ([decision 49](docs/decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)), and 0.1 and 0.2 on 28 October ([decision 37](docs/decisions.md#37-03-alone-what-dropping-01-and-02-overturns-and-settles)) ([changelog](CHANGELOG.md), [upgrade procedure](docs/upgrading.md)). This project's agent runs on Cloudflare Workers with one Durable Object per person and Claude Sonnet 5.5 through Pi. It finds a Company that publishes `poppy.json`, names a Session on every request with a signed `Poppy-Session` header, has you sign in on the Company's own page when it needs your account, talks to the Company's agent, calls its APIs, and asks you on the page when the Company returns an operation for approval. The status is alpha. At 0.1 and 0.2 the deployed agent signed in and out at one live Company, Alpine Retail, a colleague's test store (13 and 14 October), and got as far as asking to upload a photo at print-with-poppy's live store (12 October) ([live evidence](docs/history/live-0.2-testing.md)). The [current verification report](docs/poppy-0.4-conformance.md#current-verification) records the 0.4 checks and live limits; the [0.3 review](docs/poppy-0.3-conformance.md) keeps 0.3's independent demo evidence. ## Components and supported Poppy versions -The implementation follows the text retrieved on **11 November 2026**, matching upstream commit `ed47408` ([snapshot](spec/draft-0.4-retrieved-2026-11-11/README.md)). [spec/upstream.json](spec/upstream.json) pins the snapshot and its hashes; `npm run spec:drift` reports later changes. The [conformance review](docs/poppy-0.4-conformance.md) distinguishes implementation, independent checks and live verification. The requirement ledger does not certify full conformance. +The implementation follows the 0.4 text retrieved on **11 November 2026**, matching upstream commit `ed47408` ([snapshot](spec/draft-0.4-retrieved-2026-11-11/README.md)), and the 1.0 draft retrieved on **13 November 2026**, at `bb98332` ([snapshot](spec/draft-1.0-retrieved-2026-11-13/README.md)). [spec/upstream.json](spec/upstream.json) pins the snapshot and its hashes; `npm run spec:drift` reports later changes. The [conformance review](docs/poppy-0.4-conformance.md) distinguishes implementation, independent checks and live verification. The requirement ledger does not certify full conformance. | Component | Poppy versions | What it does | | --- | --- | --- | -| [PDA application and client](pda-spec.md) | 0.4 | Signs in to Companies, uses their APIs, conversations and websites, and asks for approval of the Company's exact terms when it returns an operation (Operations 3), unless a standing instruction you wrote covers them; selected task photos upload without another permission click; unselected files need disclosure consent | -| [Document validator](docs/validator.md) | 0.4 | Checks Company discovery, OAuth and protected resource metadata, client metadata and keys. One library backs the web form, HTTP API and CLI | -| [Reference/mock Company](interop/README.md#the-fake-implementations) | 0.4 | Serves Company endpoints and records violations. Tests select lenient, strict, deliberately flawed or adversarial behavior | +| [PDA application and client](pda-spec.md) | 0.4, 1.0 | Signs in to Companies, uses their APIs, conversations and websites, and asks for approval of the Company's exact terms when it returns an operation (Operations 3), unless a standing instruction you wrote covers them; selected task photos upload without another permission click; unselected files need disclosure consent | +| [Document validator](docs/validator.md) | 0.4, 1.0 | Checks Company discovery, OAuth and protected resource metadata, client metadata and keys. One library backs the web form, HTTP API and CLI | +| [Reference/mock Company](interop/README.md#the-fake-implementations) | 0.4, 1.0 | Serves Company endpoints and records violations. Tests select lenient, strict, deliberately flawed or adversarial behavior | | [Fake test Personal Agents](interop/README.md#the-fake-implementations) | 0.4 | Exercise Companies with lenient, strict or sloppy behavior; the restored malicious agent sends mutated 0.4 requests to our own mocks | | [Interop harness](docs/interop-spec.md) | 0.4 | Runs agent/Company pairs in isolated containers, records exchanges and reports failures by protocol rule. Its 0.1 and 0.2 peers and lanes are retired ([§14](docs/interop-spec.md#14-retired-with-01-and-02)), and its 0.3 pairing with print-with-poppy ([decision 49](docs/decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)) | | Independent client tests | 0.4 | A [Python client and Hypothesis model](test/hypothesis/README.md) of the mock, written apart from `src/poppy` so a misreading both share can show | -| [Specification snapshots and the requirement ledger](docs/poppy-0.4-upgrade.md) | 0.4 | Preserve upstream text, and give each of 0.4's changelog entries a disposition with its code and evidence; [0.3's](docs/poppy-0.3-upgrade.md) are kept as history | +| Specification snapshots and the requirement ledgers ([0.4](docs/poppy-0.4-upgrade.md), [1.0](docs/poppy-1.0-upgrade.md)) | 0.4, 1.0 | Preserve upstream text, and give each changelog entry a disposition with its code and evidence; [0.3's](docs/poppy-0.3-upgrade.md) are kept as history | PDA uses the document validator during discovery, and the fake agents wrap PDA's client. The [ecosystem map](docs/ecosystem.md#current-ecosystem) records observation dates and tested revisions separately for source reviews, grids and live journeys. diff --git a/SECURITY.md b/SECURITY.md index 7b179ed..64ae607 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -23,7 +23,7 @@ We'll acknowledge a report, agree a timeline with you, fix it, and credit you un Each surface below has a defence in the code today, and the link says where it is described. A way round one of them is a vulnerability. So is anything that lets the model approve an action or see a token, key or password, by any route. - **Sign-in, sessions and the allowlists.** The Worker runs Google and GitHub sign-in itself, with `state` and PKCE, and keeps you signed in with an HMAC-signed cookie (HttpOnly, Secure, SameSite=Lax). Each identity gets its own agent, named by a hash of the provider and the account id, and one person's agent can't read another's. `OWNERS`, `SIGNIN_ALLOWLIST` and `DEMO_ALLOWLIST` match a verified Google email, a Google Workspace domain (Workspace accounts only) or a GitHub numeric id. ([decisions §3](docs/decisions.md#3-app-sign-in-in-the-worker-not-cloudflare-access), [§4](docs/decisions.md#4-who-may-sign-in-owners-an-allowlist-and-signup), [§15](docs/decisions.md#15-two-allowlists-and-the-demos-knobs)) -- **Poppy, against a malicious Company.** Discovery documents pass the validator before the client uses them. Everything a Company controls gets the private-host checks, and a Session JWT or access token goes only to the Company's own hosts. Company text reaches the model as information, never approval: no tool confirms an operation, and `poppy_api_call` refuses any URL under a Poppy endpoint. When older conversation is summarised, each message goes to the summarizer as its own JSON line, so Company text can't pass for the User's words or end the conversation early ([§23](docs/decisions.md#23-compaction-a-budget-our-summarizer-the-page)). Task requests run normally; when the Company returns approval_required, only the User's decision on its exact terms authorizes the stored request to be sent with approval. Access tokens, delegated keys and DPoP keys stay in memory; refresh tokens and model keys are sealed with AES-GCM; none reaches the model, a tool result, the transcript or a log. ([decisions §6](docs/decisions.md#6-prompt-injection-defences-that-are-structural), [§22](docs/decisions.md#22-security-hardening), [spec, Safety](pda-spec.md#safety)) +- **Poppy, against a malicious Company.** Discovery documents pass the validator before the client uses them. Everything a Company controls gets the private-host checks, and a Session JWT or access token goes only to the Company's own hosts. Company text reaches the model as information, never approval: no tool confirms an operation, and `poppy_api_call` refuses any URL under a Poppy endpoint. When older conversation is summarised, each message goes to the summarizer as its own JSON line, so Company text can't pass for the User's words or end the conversation early ([§23](docs/decisions.md#23-compaction-a-budget-our-summarizer-the-page)). Task requests run normally; when the Company returns approval_required, only the User's decision on its exact terms authorizes the stored request to be sent with approval. Access tokens and delegated keys stay in memory; refresh tokens, DPoP private keys and model keys are sealed with AES-GCM; none reaches the model, a tool result, the transcript or a log. ([decisions §6](docs/decisions.md#6-prompt-injection-defences-that-are-structural), [§22](docs/decisions.md#22-security-hardening), [spec, Safety](pda-spec.md#safety)) - **`read_url` and Browser Run.** It reads only https pages on the standard port at public hosts, and checks every redirect the same way. It sends the address and nothing else: no cookie, credential or anything about the User. The page reaches the model inside an `` fence that the page can't close, labelled as information that never carries the User's instructions. A render gets a fresh browser that may send only GET and HEAD requests to public https hosts. Sockets, workers, beacons and popups are removed before the page's scripts run, and nothing types, clicks or submits. A response from a private address spoils the read. The limits: 30 reads a minute per agent, 20 seconds a render, 10 renders an hour per agent. ([decisions §27](docs/decisions.md#27-general-tools-beside-poppy-read_url-memory-time-and-maths), [§28](docs/decisions.md#28-browser-run-for-read_url-read-only-not-for-poppy-browsing), [spec, General tools](pda-spec.md#general-tools)) - **Memory and scheduled tasks: your own words only.** Only a turn started by the User's own message can save a note as something the User said, or set or cancel a reminder or task. The check is structural: a turn started by a Company message, one of the agent's notices or a task's own run begins with `[`. Notes, reminders and tasks all refuse text that looks like a password, code, key, token or card number. A task's run has no powers a chat turn lacks. Known and accepted: a page the User asked the agent to read can still talk the model into a note marked as the User's, which Settings shows. ([decisions §27](docs/decisions.md#27-general-tools-beside-poppy-read_url-memory-time-and-maths), [§29](docs/decisions.md#29-reminders-and-scheduled-tasks-on-the-durable-objects-alarm-and-web-push)) - **Photo uploads.** A photo is kept in the person's own agent, its type judged by its first bytes, and served back only to its owner's page. The model sees a preview only in the User's own message, and tools name a photo by its id, never its bytes. A photo selected for the task may upload to that task's Company without another permission click; unselected photos require disclosure consent. Upload destinations remain among the Company's own hosts. ([decisions §26](docs/decisions.md#26-photos-in-the-chat-uploaded-only-with-the-users-approval)) diff --git a/docs/company-testing.md b/docs/company-testing.md index ddc03a6..ae28c15 100644 --- a/docs/company-testing.md +++ b/docs/company-testing.md @@ -19,7 +19,7 @@ Four checks stand between a bug in the mock and a test that passes for the wrong 1. **Tamper rows.** `TAMPERS` in [`test/mock-company.test.ts`](../test/mock-company.test.ts) drives the mock with hand-made requests, never our client. Each row breaks one thing in an otherwise correct request and expects exactly one violation id. A check that stops firing fails a named row. 2. **The catalogue test.** The same file checks that every id in `violations.ts` appears in the mock's source and has a tamper row. An id nobody tests can't be added quietly. 3. **A second client.** Our client and our mock were written by the same people, so a misreading they share passes every test. [`test/hypothesis/`](../test/hypothesis) holds an independent Poppy client in Python, written from the draft rather than ported from `src/poppy`, and five stateful, model-based Hypothesis tests that drive it against the mock. It runs locally, after a change to the draft or a large change to the mock, and not in CI. -4. **The maintainers' validator.** The [pinned 0.4 kit](../spec/company-kit-2026-11-11/README.md) runs unchanged over local HTTPS against the mock serving 0.4 alone, in its lenient, strict, Bearer and issuerless profiles. CI preserves the raw results and checks them against the [reviewed findings](../test/company-kit/reviewed-findings-0.4.json): the documented DPoP prerequisite findings, accepted controls and absent-feature skips. The 0.3 kit, which also checked the hosted dummy Company's handlers, stays pinned as history ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)); its [29 October review](company-kit-review.md) holds the last manual checklist review. The old 0.2 Docker lanes remain historical. +4. **The maintainers' validator.** The [pinned 0.4 kit](../spec/company-kit-2026-11-11/README.md) runs unchanged over local HTTPS against the mock serving 0.4 alone, and the [1.0 draft's kit](../spec/company-kit-2026-11-13/README.md) against the mock serving 1.0 alone, in its lenient, strict, Bearer and issuerless profiles. CI preserves the raw results and checks them against the reviewed findings ([0.4](../test/company-kit/reviewed-findings-0.4.json), [1.0](../test/company-kit/reviewed-findings-1.0.json)): the documented DPoP prerequisite findings, accepted controls and absent-feature skips. The 0.3 kit, which also checked the hosted dummy Company's handlers, stays pinned as history ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)); its [29 October review](company-kit-review.md) holds the last manual checklist review. The old 0.2 Docker lanes remain historical. A new check therefore lands with three things: the check in the mock, its id with a basis in `violations.ts`, and a tamper row. The catalogue test fails until all three are there. diff --git a/docs/decisions.md b/docs/decisions.md index d6d762c..53a7d5e 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -687,3 +687,17 @@ Speaking both versions was superseded by [decision 49](#49-03-dropped-the-agent- - **Cost.** Before consent the agent fetches the Company's public `poppy.json` to learn its name, so a Company learns that someone's agent looked it up. That is an unauthenticated request carrying nothing of the User's. A model can still ask for a Company the User didn't mean; the domain on the card, and the name it calls itself, are there to catch that, and a Company's operations still need the User's approval of exact terms. - **Alternatives.** *Read the domain from the User's prose*: decision 40 removed that because language cannot establish consent reliably. *Let the card grant access directly*: a second authority path beside the composer, invisible in the chat and in a replayed transcript. *Suggest the domain in the composer only*: the User would still have to notice it and resend. - **When.** 12 November 2026, at the owner's request. + +## 51. 1.0 beside 0.4 + +- **Context.** Upstream's draft 1.0 (13 November, commit `bb98332`) has six breaking changes against 0.4: a required `description` on each `agent.protocols` entry (8.1), Pushed Authorization Requests for Direct Sign-In (4.2), `prompt=consent` so a Company shows its consent page for scopes granted before (4.2, 10.8), the same DPoP key at refresh (4.4), PS384 required of Companies (4.1, 5.2), and UCP scope requests naming every scope. Its Operations and Mediated Sign-In versions are 0.4's. Companies will move from 0.4 to 1.0 one at a time, and 3.4 makes newer minor versions of 1.0 compatible with older agents. Decision 49 left the multi-version code in place so the next version could be added as data. A snapshot of the same morning (`736ef95`, three breaking changes) was replaced before this was merged. +- **Decision.** + - **Both versions.** `PROTOCOL_VERSIONS` is `["0.4", "1.0"]` and both pins are `runtime`. Discovery uses the newest version a Company offers that is compatible with one the agent speaks, and every request declares the version the agent implements, so a 1.1 document is used as 1.0. + - **One rule set, a few differences.** 1.0 reuses 0.4's validator profile with three rules added: protocol descriptions, a port in `organization.domain`, and ES256 with PS384 for client assertions. In the agent, `prompt=consent`, skipping stream events with unknown names and reading descriptions apply to 1.x Companies. PAR and stored keys are version-independent: it pushes whenever the issuer lists a PAR endpoint, since RFC 9126 defines that metadata for any client, and it stores DPoP keys, which 0.4 allows. The mock applies 1.0's stricter checks only to 1.x requests. + - **The agent's own sign-in page.** With PAR, the sign-in card links to `/poppy/sign-in` on the agent, which pushes the request when the User opens it, as 4.2 recommends, since a pushed request expires within a minute. + - **Stored keys.** DPoP private keys are sealed in Durable Object storage by issuer and User ID, like refresh tokens, and are withheld from the data export. The latest nonce from each server is stored too, so a kept key keeps using it after a restart instead of appearing to the Company to have dropped it. +- **Why.** A Company serving 1.0 alone, or requiring PAR, would otherwise be refused, while 0.4 Companies still need 0.4. The breaking changes are small enough that a second rule set would be mostly a copy. Making PAR and key storage version-independent keeps one sign-in path and one refresh path, and both are allowed under 0.4. +- **Cost.** A private key is now stored, sealed, where it was memory-only; losing the sealing secret loses the keys with the refresh tokens they protect. The sign-in link needs the User's PDA session in the same browser, so a link opened elsewhere asks them to sign in to PDA first. Two pinned versions mean two kits and ledgers to keep current until 0.4 is dropped. +- **Alternatives.** *Move to 1.0 alone*, as decision 49 did for 0.4: one version, but every 0.4 Company refused until it upgrades. *Push only under 1.0*: a 0.4 Company that requires PAR would be refused for a reason RFC 9126 already answers. *Push when the agent builds the card*: the `request_uri` would expire before most Users open it. +- **Consequences.** This partly supersedes decision 49's "0.4 alone"; its rules for stored state and history stand. The Hypothesis client speaks both versions and draws one per run; in the interop grid the agents declare both, `lenient-company` and `strict-company` serve 1.0 and `lenient-company-v04` serves 0.4 (see the [1.0 upgrade](poppy-1.0-upgrade.md)). +- **When.** 13 November 2026, at the owner's request. diff --git a/docs/ecosystem.md b/docs/ecosystem.md index 888887b..250569b 100644 --- a/docs/ecosystem.md +++ b/docs/ecosystem.md @@ -16,7 +16,7 @@ This page owns current ecosystem observations. The [frozen implementation catalo ## Current ecosystem — 12 November 2026 -PDA speaks **Poppy 0.4 alone** ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)), deployed on 12 November, and refuses a Company that declares anything else. 0.4 was published on 10 November as the 1.0 release candidate. Upstream opened **Draft 1.0** on 11 November (`272cab0`): 0.4 with fixes; at `ad20217` we found it differing only in its version strings. The official kit's validator at `ad20217` checks for `"1.0"` alone, so it fails a 0.4 Company's `discovery.protocol-version`; our validator keeps the [frozen 0.4 pin](../spec/draft-0.4-retrieved-2026-11-11/README.md). Both checks below are read only: no Session, sign-in or order was attempted, and nothing was posted to any project. +PDA speaks **Poppy 0.4** ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)), deployed on 12 November, and refuses a Company that declares anything else. Since 13 November the repository also speaks the 1.0 draft ([decision 51](decisions.md#51-10-beside-04)), not yet deployed. 0.4 was published on 10 November as the 1.0 release candidate. Upstream opened **Draft 1.0** on 11 November (`272cab0`): 0.4 with fixes; at `ad20217` we found it differing only in its version strings, and by `bb98332` (13 November) it had six breaking changes ([1.0 upgrade](poppy-1.0-upgrade.md)). The official kit's validator at `ad20217` checks for `"1.0"` alone, so it fails a 0.4 Company's `discovery.protocol-version`; our validator keeps the [frozen 0.4 pin](../spec/draft-0.4-retrieved-2026-11-11/README.md). Both checks below are read only: no Session, sign-in or order was attempted, and nothing was posted to any project. ### Public discovery — 12 November 2026 diff --git a/docs/interop-spec.md b/docs/interop-spec.md index 33b1ee0..7404ae7 100644 --- a/docs/interop-spec.md +++ b/docs/interop-spec.md @@ -1,6 +1,6 @@ # Poppy interop harness specification -The runner checks Poppy 0.4, published 10 November (pinned in [`spec/upstream.json`](../spec/upstream.json)). The agent dropped 0.3 on 12 November ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)); sections 14 and 15 list what spoke 0.1, 0.2 or 0.3. Each cell records the common `protocolVersion` and local `specificationRevision`; a pair with no common version is unsupported, except two of our own builds (`owner: "self"`), which always speak the same version: for them it is an `error` blamed on the harness. A run in which no cell passed or failed fails (exit 1), so a grid that ran nothing can't pass empty, as CI's did from 28 to 29 October. Retries preserve the version context. A known failure without a version applies to the version we speak. Registry entries marked `vectorsOnly` are explicit provisioning helpers excluded from the default M×N grid. +The runner checks Poppy 0.4, published 10 November, and the 1.0 draft of 13 November, both pinned in [`spec/upstream.json`](../spec/upstream.json) ([decision 51](decisions.md#51-10-beside-04)). The agent dropped 0.3 on 12 November ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)); sections 14 and 15 list what spoke 0.1, 0.2 or 0.3. Each cell records the common `protocolVersion` and local `specificationRevision`; a pair with no common version is unsupported, except two of our own builds (`owner: "self"`), which always speak the same version: for them it is an `error` blamed on the harness. A run in which no cell passed or failed fails (exit 1), so a grid that ran nothing can't pass empty, as CI's did from 28 to 29 October. Retries preserve the version context. A known failure without a version applies to the version we speak. Registry entries marked `vectorsOnly` are explicit provisioning helpers excluded from the default M×N grid. Version 1. What an implementation of the [Personal Agent Protocol](https://personalagentprotocol.org/) (Poppy) provides to join the M×N interop grid, and what the runner does with it. The rationale and plan are in [interop-testing.md](history/interop-testing.md); the code is in [`interop/`](../interop). @@ -51,14 +51,14 @@ The key words MUST, SHOULD and MAY are used as in RFC 2119. ### 2.1 The fake implementations -Our own code with a profile, each set with a lenient and a strict member, both sets an evil one, and the agents a sloppy one. All spoke 0.3 alone from 28 October 2026 (section 14), and 0.4 alone since 0.3 was dropped on 12 November ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)): the agents declare 0.4, both mocks serve it with no other version in `supported_versions` (3.4), and `evil-personal-agent` sends raw 0.4 requests, with `Poppy-Version`, `Poppy-Extensions` and Operations 3 approvals. Renamed on 23 October 2026 (`pda-mock` → `lenient-company`, `pda-mock-strict` → `strict-company`, `pda-mock-v02` → `lenient-company-v02`, `evil-agent` → `evil-personal-agent`); results from before then use the old names. +Our own code with a profile, each set with a lenient and a strict member, both sets an evil one, and the agents a sloppy one. All spoke 0.3 alone from 28 October 2026 (section 14), and 0.4 alone since 0.3 was dropped on 12 November ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)): the agents declare 0.4, both mocks serve it with no other version in `supported_versions` (3.4), and `evil-personal-agent` sends raw 0.4 requests, with `Poppy-Version`, `Poppy-Extensions` and Operations 3 approvals. Since 13 November ([decision 51](decisions.md#51-10-beside-04)) the agents declare 0.4 and 1.0, `lenient-company` and `strict-company` serve 1.0, `lenient-company-v04` serves 0.4 (`INTEROP_MOCK_VERSION`), and `evil-personal-agent` declares the version of the Company it attacks. Renamed on 23 October 2026 (`pda-mock` → `lenient-company`, `pda-mock-strict` → `strict-company`, `pda-mock-v02` → `lenient-company-v02`, `evil-agent` → `evil-personal-agent`); results from before then use the old names. | | Personal Agent (`interop/impls/pda-agent`, `INTEROP_AGENT_PROFILE`) | Company (`interop/impls/pda-mock`, `INTEROP_MOCK_PROFILE`) | | --- | --- | --- | | Lenient | `lenient-personal-agent`, the reference agent (rule 2): accepts every reading of what a Company does that gives no more access. Server metadata at the appended location when the RFC 8414 inserted one is 404 (S3 `either`; the metadata's `issuer` must still equal `auth.issuer`), and, after `invalid_client` at an endpoint the request carries no DPoP proof to, the client assertion again naming the token endpoint, then the issuer, each freshly signed (S1). | `lenient-company`, the reference Company: S2-lenient assertions. | | Strict | `strict-personal-agent`: runs the runner's own Company-side checks (section 8) and the validator over everything it receives, refuses at the first finding of any level, a SHOULD or the Guides included (`company_departure`, or `discovery_failed` for a document), and serves its findings at `GET /violations`. | `strict-company`: `typ: "JWT"`, a published `kid` and 60-second assertions. | | Sloppy | `sloppy-personal-agent`: what real agents get wrong, declared honestly in its readings (S1 `token-endpoint`, S2 `lenient-300s`): client assertions with no `typ`, living 300 seconds, naming the token endpoint as `aud` everywhere, where 4.1 says the issuer. Honest, not adversarial: every departure is a reading some live agent took. | none | -| Evil | `evil-personal-agent`: raw 0.4 requests with accepted controls and precise mutation/refusal oracles (section 13) | `evil-company` (section 13) | +| Evil | `evil-personal-agent`: raw requests at the Company's version, with accepted controls and precise mutation/refusal oracles (section 13) | `evil-company` (section 13) | An agent's profile changes only the adapter's network seam (`interop/impls/pda-agent/profiles.ts`): `src/poppy` runs unchanged, as it does for `pda`. A profile never takes the live identity. @@ -91,7 +91,7 @@ Every adapter serves `GET /manifest` on its control port (8081), with no authent "name": "pda", "role": "agent", "commit": "a7fbe96", - "poppy": ["0.4"], + "poppy": ["0.4", "1.0"], "extensions": ["operations"], "scenarios": ["D", "S0", "N", "SD", "C", "CI", "SO", "O"], "readings": { "S1": "issuer", "S2": "jwt-60s", "S3": "insertion", "S23": "per-origin" }, @@ -332,7 +332,7 @@ This document is version 1; every JSON body above carries `interop: 1` or `versi Adversarial testing (the malicious implementations and the fault-injection proxy of [`docs/adversarial-interop.md`](adversarial-interop.md)) is restricted to implementations this project owns, to control risk and blast radius. -- An adversarial or faulted cell runs only on the **local** lane, and only when every honest side is `owner: "self"`, with one exception: `evil-company` may attack any agent, our own or another project's built at its pinned commit, when the scenario has no proxy faults. The owner approved that exception on 13 October 2026. The runner refuses any other adversarial cell (it marks it `error`, blame `harness`, with the reason) and never runs one in the live lane. The usable cells are therefore `evil-company` × every agent, proxy faults over `pda × lenient-company`/`strict-company`, and `evil-personal-agent × lenient-company`/`strict-company` at 0.4. CI selects these own-project cells explicitly and uses `--require-supported` to fail on skipped coverage. +- An adversarial or faulted cell runs only on the **local** lane, and only when every honest side is `owner: "self"`, with one exception: `evil-company` may attack any agent, our own or another project's built at its pinned commit, when the scenario has no proxy faults. The owner approved that exception on 13 October 2026. The runner refuses any other adversarial cell (it marks it `error`, blame `harness`, with the reason) and never runs one in the live lane. The usable cells are therefore `evil-company` × every agent, proxy faults over `pda × lenient-company`/`strict-company`, and `evil-personal-agent × lenient-company`/`strict-company` at 1.0 and `lenient-company-v04` at 0.4. CI selects these own-project cells explicitly and uses `--require-supported` to fail on skipped coverage. - **No flag lifts the rest.** Running another adversarial implementation against someone else's, or anything adversarial in the live lane, is a code change, which goes through the disclosure process in [`SECURITY.md`](../SECURITY.md). A failure in an adversarial cell may be a vulnerability in someone's project, so its results stay in the gitignored `interop/results/` and go to its maintainers privately before anything about them is committed, and a spec-permitted attack goes to the authors as an N-numbered issue. - `--image-tag ` (default `latest`) builds and runs under a tag, so an adversarial run with `--image-tag adv` never overwrites the `:latest` images a full grid run is using. It is the only way to keep a side build of our images: don't `docker tag` them by hand. A side tag costs disk until it is removed (`docker image rm poppy-interop/:`); the runner never removes images. diff --git a/docs/poppy-0.4-conformance.md b/docs/poppy-0.4-conformance.md index 209d8f4..eb5a78e 100644 --- a/docs/poppy-0.4-conformance.md +++ b/docs/poppy-0.4-conformance.md @@ -4,12 +4,12 @@ This review targets the [11 November 2026 snapshot](../spec/draft-0.4-retrieved- ## Current verification -PDA implements the pinned 11 November 2026 text of Poppy 0.4 alone. It dropped 0.3 on 12 November ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)); the [0.3 review](poppy-0.3-conformance.md) keeps that version's evidence. This is the current verification summary; dated evidence packages keep the results of their own runs. +PDA implements the pinned 11 November 2026 text of Poppy 0.4, and beside it the 13 November 1.0 draft, whose changes and their evidence are in the [1.0 upgrade](poppy-1.0-upgrade.md) ([decision 51](decisions.md#51-10-beside-04)). It dropped 0.3 on 12 November ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)); the [0.3 review](poppy-0.3-conformance.md) keeps that version's evidence. This is the current verification summary; dated evidence packages keep the results of their own runs. | Area | Evidence and limit | | --- | --- | | Repository implementation | [CI](../.github/workflows/ci.yml) runs documentation references on every PR, runtime checks on code/config changes, and specialist checks on their inputs; main runs all CI steps. Passing them does not certify every normative requirement. | -| Offline suite | The client against the strict mock Company, which fails a test on any violation or warning; the kit's own JSON Schemas over every request the agent sends to the mock ([test/kit-schemas.ts](../test/kit-schemas.ts)); the validator; the property tests; and the independent [Python Hypothesis client](../test/hypothesis/README.md). All of them speak 0.4 alone. The multi-version code (choosing a version, `supported_versions`, `version_unsupported`) is tested with a hypothetical newer version. | +| Offline suite | The client against the strict mock Company, which fails a test on any violation or warning; the kit's own JSON Schemas over every request the agent sends to the mock ([test/kit-schemas.ts](../test/kit-schemas.ts)); the validator; the property tests; and the independent [Python Hypothesis client](../test/hypothesis/README.md). All of them speak 0.4, and since 13 November 1.0 too ([1.0 upgrade](poppy-1.0-upgrade.md#how-it-is-checked)). The multi-version code (choosing a version, `supported_versions`, `version_unsupported`) is tested with a hypothetical newer version. | | Own interop and security lanes | CI selects applicable honest/network, malicious-Company and malicious-agent cells explicitly, and refuses skipped required cells ([lane definitions](../.github/workflows/interop.yml)). The lanes pair 0.4 implementations only. The [interop spec](interop-spec.md) records the latest run. | | Official Company kit | CI runs the [pinned 0.4 kit](../spec/company-kit-2026-11-11/README.md), unmodified, against the mock profiles and compares the result with [the reviewed findings](../test/company-kit/reviewed-findings-0.4.json): the DPoP-prerequisite findings already reviewed for 0.3, the two version checks a one-version Company skips ([reading](readings.md#v04-version-missing)), and the issuerless profile's OAuth checks. The DPoP-capable copy runs beside it. The [manual checklist review](company-kit-review.md) was done for the 29 October kit and hasn't been redone for 0.4. This verifies Company-side fixtures, not the full Personal Agent. | | Independent Company | Print with Poppy at `20a3d56`, in its own CI interop step: `pda` passes all ten scenarios it claims (D, S0, OU, CM, SD, SX, SMC, SO, AO, AS), signed-out and signed-in API calls and an Operations 3 order among them, as do the lenient and strict agents in the same step ([interop spec](interop-spec.md#print-with-poppy-at-20a3d56)). At `ae453ed` five failed with `invalid_session`, because the store read the delegation from `pap_dlg` ([interop spec](interop-spec.md#print-with-poppy-delegation)). This is its demo mode in Docker; no live store has run a signed-in journey with our agent. Its 0.3 receipts are in the [0.3 review](poppy-0.3-conformance.md#current-verification). | diff --git a/docs/poppy-0.4-upgrade.md b/docs/poppy-0.4-upgrade.md index 8df5da3..92f38e8 100644 --- a/docs/poppy-0.4-upgrade.md +++ b/docs/poppy-0.4-upgrade.md @@ -128,7 +128,7 @@ The 0.4 changelog has 44 entries. [spec/requirements-0.4.json](../spec/requireme | `extension_required` in a JSON body at APIs | Done | [code](../src/poppy/client.ts), [evidence](../test/poppy-0.4.test.ts) | X1 is done: one reading of the JSON body names the extension for the model and the User at OpenAPI operations, MCP servers and protocol endpoints. The mock answers in a body under 0.4, at its OpenAPI and MCP servers alike. | | Device sign-in links on the issuer or Company domain | Done | [code](../src/poppy/signin.ts), [evidence](../test/ui/device-link.test.tsx) | K3: a device link is shown only on the issuer's host or organization.domain, or a subdomain of either. Another protected resource of the same issuer is refused, which 0.3 allowed; done once 0.3 was dropped (decision 49). | | Refresh token lifetimes left to the Company | Company obligation | [code](../test/mock-company/core.ts), [evidence](../docs/poppy-0.4-upgrade.md) | No agent change. The mock's refreshTokenTtl only sets an expiry at issue, so nothing depends on a fixed lifetime. | -| A DPoP key per User ID | Done | [code](../src/poppy/client.ts), [evidence](../interop/test/dpop-keys.test.ts) | H1: DPoP keys are held by issuer and User ID, so a changed User ID gets a new key. Each issuer still has one stored User ID; the key stays in memory and is regenerated after a restart. Shipped on 0.3, which allows it. | +| A DPoP key per User ID | Done | [code](../src/poppy/client.ts), [evidence](../interop/test/dpop-keys.test.ts) | H1: DPoP keys are held by issuer and User ID, so a changed User ID gets a new key. Each issuer still has one stored User ID; the key was memory-only until decision 51 stored it sealed, so it now survives a restart. Shipped on 0.3, which allows it. | | Checking protected resource metadata | Done | [code](../src/poppy/client.ts), [evidence](../interop/test/resource-metadata-refresh.test.ts) | H2: derived metadata counts only when its resource is exactly the service URL, or the origin and path the well-known segment was inserted into (interop/test/service-resource.test.ts). Per decision 43, metadata from a resource_metadata challenge must name the same service exactly. MCP reads only the URL derived from the server (src/poppy/mcp-transport.ts). The mock records resource.unverified-target for a token request naming any other resource. Shipped on 0.3, which allows it. | | Scopes described twice | Done | [code](../src/poppy/signin.ts), [evidence](../test/poppy-core.test.ts) | K2: describeScopes prefers auth.scopes, and uses an OpenAPI description only for a scope auth.scopes doesn't describe; 0.3's order was the reverse. Done once 0.3 was dropped (decision 49). | | One User ID per delegated key at the Company | Company obligation | [code](../src/poppy/jwt.ts), [evidence](../docs/poppy-0.4-upgrade.md) | The agent already makes one delegated key per User ID (5.2). K1 lets the mock reject a key reused for another User ID. | diff --git a/docs/poppy-1.0-upgrade.md b/docs/poppy-1.0-upgrade.md new file mode 100644 index 0000000..4fad611 --- /dev/null +++ b/docs/poppy-1.0-upgrade.md @@ -0,0 +1,50 @@ +# Poppy 1.0: the upgrade + +PDA speaks the 1.0 draft beside 0.4 since 13 November ([decision 51](decisions.md#51-10-beside-04)). 1.0 is pinned from the [13 November 2026 snapshot](../spec/draft-1.0-retrieved-2026-11-13/README.md), retrieved at 15:48 UTC, and the [official kit](../spec/company-kit-2026-11-13/README.md) downloaded the same afternoon, both at upstream commit `bb98332`. They replaced a snapshot and kit from that morning (`736ef95`) before either was merged, since upstream added ten changelog entries in between. 1.0 is a draft, so a newer snapshot replaces this pin after review ([upgrading](upgrading.md)); 0.4 stays frozen at its [11 November pin](poppy-0.4-upgrade.md). + +## What changes between 0.4 and 1.0 + +Extensions keep their versions: Operations 3 and Mediated Sign-In 1. Of the six breaking changes, three ask something new of the agent, one is the Company's alone, one concerns UCP, which PDA doesn't speak, and one changes only what a 1.0 document must contain: + +- **Conversation protocol descriptions** (8.1) apply to 1.0 alone. The [1.0 validator profile](../src/validator/profiles/draft-1.0.ts) is 0.4's with a required `description` on each `agent.protocols` entry, and discovery refuses a 1.0 Company without one. The model reads the description in `poppy_discover`. +- **Pushed Authorization Requests** (4.2) apply under both versions, because RFC 9126 defines the metadata for any client ([reading](readings.md#pushed-authorization)). When the issuer lists `pushed_authorization_request_endpoint`, the Direct Sign-In card links to the agent's `/poppy/sign-in` page, which pushes the request with the client assertion and a DPoP proof each time the User opens it, then redirects to the authorization endpoint with only `client_id` and `request_uri`. +- **Consent for scopes granted before** (4.2, 10.8) applies to 1.0 alone: every Direct Sign-In request to a 1.x Company carries `prompt=consent` ([reading](readings.md#v10-prompt-consent)). +- **The same DPoP key at refresh** (4.4) applies under both versions, since 0.4 allows keeping a key. Keys by issuer and User ID are sealed in `poppy_dpop_keys`, so a restart refreshes with the key the refresh token was issued with, and each server's latest nonce is kept in `poppy_dpop_nonces` for the key to keep sending ([reading](readings.md#v10-dpop-key)). +- **PS384 required** is a Company obligation. The agent signs with ES256, which every Company must accept. The 1.0 validator profile reports an issuer whose listed client-assertion algorithms leave out ES256 or PS384. +- **UCP scope requests name every scope** concerns UCP, which PDA doesn't speak. Its general sign-in already requests every scope still needed (4.7). + +Of the minor changes, conversations gained room to extend ([reading](readings.md#v10-extend)): a message with a `role` the agent doesn't know is the Company's content, and in a 1.x conversation a stream event with an SSE name it doesn't know is skipped. The 1.0 validator accepts a port other than 443 in `organization.domain`, though the agent uses no Company on another port. Under 1.x the mock takes a `context` field set to `null` as cleared. + +Choosing a version follows 3.4 ([reading](readings.md#v10-choice)). From 1.0, a newer minor version is compatible: a Company serving 1.1 is used as 1.0, and every request declares `Poppy-Version: 1.0`, the version the agent implements. The validator checks such a document with its 1.0 profile and notes the newer version (`version-newer-minor`). + +## How it is checked + +- **The mock** serves 1.0, 1.1 or 0.4, alone or with a linked document, describes its protocols under 1.x, can offer or require PAR (`pushedAuthorization`), bind refresh tokens to their key (`bindRefreshTokens`), and stream an event a later version might add (`laterStreamEvent`). Its new checks are `authorize.prompt-consent`, `par.not-pushed`, `par.extra-parameters`, `par.code-key` and `dpop.refresh-key-changed`, each with a negative `TAMPERS` case. +- **The agent against the mock**: [test/poppy-1.0.test.ts](../test/poppy-1.0.test.ts) covers the version choice and declaration, the description reaching the model, PAR (the card's link, a push with a proof on each opening, a full sign-in, a signed-out browser, an unknown id), `prompt=consent` under 1.0 and not 0.4, unknown roles and stream events, and refresh with the stored key after the agent's memory is lost. Every request is also checked against the schemas of the kit for the version it declared. +- **The kit against the mock**: `node scripts/check-company-kit.mjs --protocol 1.0 --reviewed-findings` gives the same results as the 0.4 kit ([reviewed findings](../test/company-kit/reviewed-findings-1.0.json)). The kit's validator checks none of the agent-side changes, so they rest on our own mock checks. +- **The Hypothesis client** ([its README](../test/hypothesis/README.md#what-the-10-addition-changed)) speaks 1.0 beside 0.4, written from the 1.0 text, and each run draws the version the mock serves (0.4, 1.0, 1.1, or two linked), PAR offered or required, bound refresh tokens and a later version's stream event. Its first run found that its own model refreshed with a User's newer DPoP key, which 1.0 forbids. +- **The interop grid**: the agents declare 0.4 and 1.0, `lenient-company` and `strict-company` serve 1.0, and `lenient-company-v04` serves 0.4, so CI runs our agent and `evil-personal-agent` at both versions. Scenario D accepts either version. + +## The 13 November changelog, entry by entry + +The 1.0 changelog has 15 entries. [spec/requirements-1.0.json](../spec/requirements-1.0.json) gives each a disposition, implementation and evidence, and `npm run check:spec` requires one for each, in order. + + +| Upstream change | Disposition | Implementation / evidence | Scope and limits | +| --- | --- | --- | --- | +| Conversation protocol descriptions | Done | [code](../src/validator/profiles/draft-1.0.ts), [evidence](../test/poppy-1.0.test.ts) | The 1.0 validator profile requires a description on each agent.protocols entry (missing-member) and reports a blank one (protocol-description-empty), so discovery refuses a 1.0 Company without them, as the kit's schema does. poppy_discover gives the model the description beside poppy_message, so it can choose between the Company's agent and its APIs. The mock describes its protocols under 1.x. The 0.4 profile is unchanged. | +| Pushed Authorization Requests | Done | [code](../src/poppy/signin.ts), [evidence](../test/poppy-1.0.test.ts) | When the issuer lists pushed_authorization_request_endpoint, the Direct Sign-In card links to the agent's own /poppy/sign-in page, which pushes the request with the client assertion and a DPoP proof each time it is opened, then redirects to the authorization endpoint with only client_id and request_uri. It does so under 0.4 too, since RFC 9126 defines the metadata (readings.md#pushed-authorization). The page answers only the person signed in to PDA in that browser, and refuses an expired or finished sign-in. Without the endpoint, the card links to the authorization URL as before. The validator checks the endpoint is HTTPS and reports require_pushed_authorization_requests without it (par-endpoint-missing). The mock offers or requires PAR, binds a pushed code to the proof's key, and records par.not-pushed, par.extra-parameters and par.code-key. | +| PS384 required | Company obligation | [code](../src/validator/profiles/draft-1.0.ts), [evidence](../test/validator.test.ts) | Companies MUST accept client assertions and delegations signed with PS384 as well as ES256 (4.1, 5.2). The agent signs with ES256, which every Company accepts, so it doesn't change. The mock already accepted both. The 1.0 validator profile reports an issuer whose token_endpoint_auth_signing_alg_values_supported leaves out ES256 or PS384 (metadata-assertion-algs); delegations have no metadata to check. The kit makes assertion.ps384 and session.delegation-ps384 MUSTs. | +| Consent for scopes granted before | Done | [code](../src/poppy/signin.ts), [evidence](../test/poppy-1.0.test.ts) | Under 1.x every Direct Sign-In request carries prompt=consent, in the URL or pushed. Our redirect goes to a web callback that any browser can reach, so we don't claim the exception for a redirect received only on the opening device, though the callback refuses a sign-in started by another person's agent (readings.md#v10-prompt-consent). 0.4 Companies get the request they always did. The mock records a 1.x request without it to a redirect URI that isn't loopback (authorize.prompt-consent); its consent page always lists every scope it grants. Device Sign-In needs nothing from the agent. | +| Same DPoP key at refresh | Done | [code](../src/poppy/client.ts), [evidence](../test/poppy-1.0.test.ts) | DPoP keys by issuer and User ID are now stored, their private JWK sealed in poppy_dpop_keys, so a restart or eviction refreshes with the key the refresh token was issued with. The latest nonce from each server is stored too (poppy_dpop_nonces), so a kept key keeps sending it. Both tables are withheld from the data export. Version-independent: 0.4 allows keeping the key. A new sign-in keeps the stored key. The mock records dpop.refresh-key-changed under 1.x and, with bindRefreshTokens, refuses the refresh with invalid_grant. | +| UCP scope requests name every scope | Not used | [code](../src/poppy/signin.ts), [evidence](../test/poppy.test.ts) | PDA doesn't speak UCP. Its general sign-in already requests every scope still needed when it asks for more access (4.7), the rule UCP now follows. | +| Ports in organization.domain | Done | [code](../src/validator/profiles/draft-0.4.ts), [evidence](../test/validator.test.ts) | The 1.0 validator profile accepts organization.domain with a port other than 443, and matches protected_resources with its port. The agent uses no Company on another port: a domain the model names has no port, and no deployment setting allows one, which 3.1 permits ("only when configured to on purpose"). Live validation, the agent's discovery, takes a bare host name for the same reason, so only a document given as text is checked with a port. The 0.4 profile still refuses a port. | +| Personal Agents choose their Companies | Done | [code](../src/poppy/tools.ts), [evidence](../test/general-tools.test.ts) | No key word. The agent contacts only Companies the User selected or allowed on a card (decisions 40 and 50). | +| Clearing context | Done | [code](../test/mock-company/conversations.ts), [evidence](../test/mock-company.test.ts) | The agent shares only changes to context and never takes a fact back, so it sends no null. Under 1.x the mock takes a null field as cleared rather than as a violation. | +| Room to extend conversations | Done | [code](../src/poppy/conversations.ts), [evidence](../test/poppy-1.0.test.ts) | A message with any role but user is the Company's content, under both versions, since dropping Company content isn't safer under 0.4. An author.type other than human was already read as the agent's. In a 1.x conversation a stream event with an SSE name other than working or text-delta, or none, is skipped; a 0.4 conversation still reads one, as before. An error code the agent doesn't know was already handled by its HTTP status. The mock can stream such an event (laterStreamEvent). The Company ignoring author fields on our messages needs nothing from us: we send only author.type. | +| Lookalike domains | Done | [code](../src/poppy/tools.ts), [evidence](../spec/draft-1.0-retrieved-2026-11-13/pages/1.0-spec.md) | No key word. PDA already identifies a Company by the domain the model names; poppy_discover returns the domain with organization.name, and every card shows the domain under the Company's own name (N14). poppy_discover's description now says the name is unconfirmed (see the next entry). | +| What a scope description says | Guidance | [code](../src/poppy/signin.ts), [evidence](../spec/draft-1.0-retrieved-2026-11-13/pages/1.0-spec.md) | Company guidance, with no field added. The agent already shows the model and the sign-in card each scope's description as the Company wrote it, so a fuller description reaches both. | +| Unconfirmed company names | Guidance | [code](../src/poppy/tools.ts), [evidence](../spec/draft-1.0-retrieved-2026-11-13/pages/1.0-guides.md) | poppy_discover's description tells the model the name comes from poppy.json and is unconfirmed, and to show the User the domain with it when it isn't sure the domain is the one the User means. | +| What a good scope description says | Guidance | [code](../src/poppy/signin.ts), [evidence](../spec/draft-1.0-retrieved-2026-11-13/pages/1.0-guides.md) | Company guidance; see the entry above. | +| Earlier scopes on the consent page | Guidance | [code](../test/mock-company/auth.ts), [evidence](../spec/draft-1.0-retrieved-2026-11-13/pages/1.0-guides.md) | Company guidance for consent pages. The mock's page lists every scope a request asks for and shows on every request. | + diff --git a/docs/readings.md b/docs/readings.md index 671464a..1e0b3ec 100644 --- a/docs/readings.md +++ b/docs/readings.md @@ -58,7 +58,7 @@ Settled. 4.1 has a client assertion name the Company's issuer as `aud`, as a sin ### S23: DPoP nonce scope -- **Client:** keeps the latest `DPoP-Nonce` per server origin (`#nonces` in `src/poppy/client.ts`), at the token endpoint and at resources, and retries once on `use_dpop_nonce`. That works with a Company that keeps one nonce for all its origins, at the cost of one extra round trip per origin. DPoP is used only when the issuer lists `dpop_signing_alg_values_supported` (4.5). +- **Client:** keeps the latest `DPoP-Nonce` per server origin (`#nonce` in `src/poppy/client.ts`, stored in `poppy_dpop_nonces` since the keys are, [decision 51](decisions.md#51-10-beside-04)), at the token endpoint and at resources, and retries once on `use_dpop_nonce`. That works with a Company that keeps one nonce for all its origins, at the cost of one extra round trip per origin. DPoP is used only when the issuer lists `dpop_signing_alg_values_supported` (4.5). - **Mocks:** one nonce for the whole Company (`nonceScope: "company"`) when nonces are required (`requireNonce`, off by default; the `require_nonce` hook in the grid). The `origin` profile is tested too. - **Why lenient.** A server nonce only bounds how long a proof stays fresh; neither scope gives more access. The strict part is elsewhere: once a key has used a nonce at a server, dropping it is recorded (`dpop.nonce-ignored`), and proofs are checked for `htm`, `htu`, `ath`, `iat` and `jti` replay. @@ -157,6 +157,19 @@ Readings we take to implement [the published 0.4 text, retrieved 11 November](.. | `navigator.poppy.controller` (Browser Control 6) | Always `"user"`, read-only, on HTTPS pages of `organization.domain` and its subdomains: the handover browser exists only while the User holds control. The agent's fetch browser runs no scripts, so no page reads `"agent"`. After an eviction, a document that starts before the next heartbeat (at most 30 seconds) reads no `navigator.poppy`; every later document reads it again | Posts the value in a hidden field and records a marked form posted from a declaring Session without `"user"` (`browser-control.marked-step`) | As the text, with the eviction gap as a known limit: "changes it as soon as control changes" holds, since control never changes while the browser is open | | What counts as taking a marked step (Browser Control 4, 5) | Following a marked link, filling a marked control or any control of an `interaction` form, and submitting a marked form, whether by its selector (which activates its default button, whose mark counts too) or through a marked button. Controls outside a form that name it in `form` aren't modelled by the fetch browser, so their marks are missed | Marks a link with an unknown value, which counts as `interaction` | As the text, except the `form` attribute, a known gap | +## 1.0 readings (13 November draft) + +Readings we take to implement [the draft 1.0 text, retrieved 13 November at 15:48 UTC](../spec/draft-1.0-retrieved-2026-11-13/README.md) beside 0.4 ([decision 51](decisions.md#51-10-beside-04)). The [1.0 upgrade](poppy-1.0-upgrade.md) records the work. + +| Question | Client | Mock | Strict or lenient | +| --- | --- | --- | --- | +| Which version to use, and which to declare (3.4) | The newest version the Company offers that is compatible with one the agent speaks: before 1.0 the same `major.minor`, from 1.0 the same major version and the same or a newer minor. A 1.1 document is used as 1.0, and every request declares `Poppy-Version: 1.0`, the version the agent implements. The validator checks a newer minor version with the newest profile of that major version and notes it (`version-newer-minor`) | Accepts a declared version compatible with one it lists, and records one that isn't (`version.unlisted`) | As the text | +| Pushed Authorization Requests under 0.4 (4.2; RFC 9126) | Pushes whenever the issuer lists `pushed_authorization_request_endpoint`, under 0.4 as under 1.0. 0.4 says nothing about PAR, and RFC 9126 defines the metadata and its use for any OAuth client, so a 0.4 Company that lists it has asked for it | Offers or requires PAR under any version; `par.extra-parameters` applies only under 1.x | **Reading**: 1.0's SHOULD applied to 0.4, where nothing forbids it | +| The page that pushes (4.2) | The card links to `/poppy/sign-in?id=…` on the agent's origin. It pushes on each opening, since a `request_uri` expires within a minute, and answers only the person signed in to PDA in that browser, as the callback does. A signed-out browser is asked to sign in to PDA first; nothing is pushed | Counts pushes and checks each carries a DPoP proof | As the text's SHOULD | +| `prompt=consent` (4.2, 10.8) | Sent on every Direct Sign-In request to a 1.x Company, in the URL or pushed. The exception is for a Personal Agent that "receives the redirect only on the device that opened the authorization URL". Our redirect is a web callback any browser can reach. It refuses a sign-in this person's agent didn't start, so a forwarded link already fails, but the text names a loopback URI or the agent's own app, and asking for the page costs the User one more click. Not sent to a 0.4 Company, where `prompt` is undefined | Records a 1.x request without it unless its redirect URI is loopback (`authorize.prompt-consent`); shows its consent page every time | **Strict**: we don't claim the exception | +| Values a later version adds (8.4, 8.6, 8.13) | A message with any `role` but `user` is the Company's content, under both versions: 0.4 has no rule, and dropping Company content isn't safer. An unknown `author.type` reads as the agent's, as before. In a 1.x conversation a stream event named other than `working` or `text-delta`, or unnamed, is skipped; in a 0.4 conversation its data is still read, since 0.4 didn't say and a 0.4 Company may name events. An unknown error code was already handled by its HTTP status | Can stream an event named `later-version` (`laterStreamEvent`) | As the text | +| Keeping the DPoP key (4.4, 4.5) | One key per issuer and User ID, stored sealed, so a restart refreshes with the key the refresh token was issued with. The latest nonce from each server is stored with it, so the key's proofs keep carrying it (RFC 9449 8). A new sign-in keeps the key; 1.0 allows a new one then, and keeping it is simpler. Under 0.4 too, since 0.4 allows keeping a key | Records a refresh with another key under 1.x (`dpop.refresh-key-changed`), and can refuse it (`bindRefreshTokens`) | As the text | + ## MCP's two lifecycles (7; Guides, "MCP and UCP interoperability") Section 7 names [MCP 2025-06-18](https://modelcontextprotocol.io/specification/2025-06-18) and [MCP 2026-07-28](https://modelcontextprotocol.io/specification/2026-07-28). The guides tell a Personal Agent to use the lifecycle it shares with the server and to follow that version's HTTP binding for headers, negotiation and legacy fallback. The binding makes fallback a MAY and `server/discover` optional, and leaves several choices to the client. These are ours, in `src/poppy/apis.ts` and `src/poppy/mcp-wire.ts`. The mock's MCP server speaks 2025-06-18 by default; `mcpVersions` makes it 2026-07-28 only or both, each enforcing its own version's rules (`mcp.legacy-*`, `mcp.modern-*` in `violations.ts`). diff --git a/docs/upgrading.md b/docs/upgrading.md index e7fdf05..8669b2d 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -2,7 +2,7 @@ PDA release numbers, Poppy wire versions, the interop control protocol, validator output versions, and extension versions are separate. Read [CHANGELOG.md](../CHANGELOG.md) before upgrading. Its reverse-chronological entries use Pi's release-note structure: Breaking Changes, Added, Changed and Fixed, plus migration, validation and rollback instructions. Unreleased means not deployed or certified. -PDA speaks 0.4 alone ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)); it spoke 0.3 beside it from 10 to 12 November ([decision 43](decisions.md#43-03-beside-04-both-versions-website-operations-and-approvals-across-sessions)). The code chooses among `PROTOCOL_VERSIONS`, so a new version can be spoken beside 0.4 by adding it there. A published version is frozen; a draft gets newer snapshots until it is published. A refresh starts when the owner requests it; there is no scheduled discovery refresh, automatic import or automatic pull request. Review the concrete change before promotion. A future support policy needs an explicit decision. +PDA speaks 0.4 and the 1.0 draft ([decision 51](decisions.md#51-10-beside-04)); it spoke 0.4 alone from 12 November ([decision 49](decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)), and 0.3 beside it from 10 to 12 November ([decision 43](decisions.md#43-03-beside-04-both-versions-website-operations-and-approvals-across-sessions)). The code chooses among `PROTOCOL_VERSIONS`, so a new version can be spoken beside 0.4 by adding it there. A published version is frozen; a draft gets newer snapshots until it is published. A refresh starts when the owner requests it; there is no scheduled discovery refresh, automatic import or automatic pull request. Review the concrete change before promotion. A future support policy needs an explicit decision. ## Current protocol inputs @@ -10,6 +10,7 @@ PDA speaks 0.4 alone ([decision 49](decisions.md#49-03-dropped-the-agent-mock-va - **0.3**, published and frozen: the [3 November 2026 snapshot](../spec/draft-0.3-retrieved-2026-11-03/README.md) and [kit](../spec/company-kit-2026-11-03/README.md), upstream commit `7205250`. Retired on 12 November: no longer spoken, but kept and checked as history. Its [requirement ledger](poppy-0.3-upgrade.md) links files at `codeAt`, the commit they were last current in. - **0.4**, published on 10 November as the 1.0 release candidate and frozen: the [11 November 2026 snapshot](../spec/draft-0.4-retrieved-2026-11-11/README.md) and [kit](../spec/company-kit-2026-11-11/README.md), upstream commit `ed47408`. It replaced the draft pins of 9 November (`b2569c5`) and 10 November (`a2f16ec`); all three stay in `spec/`. A fix before 1.0 would come as a draft 1.0, with a pin of its own. Spoken at runtime; the [0.4 upgrade](poppy-0.4-upgrade.md) has the work and its ledger. +- **1.0**, a draft: the [13 November 2026 snapshot](../spec/draft-1.0-retrieved-2026-11-13/README.md) and [kit](../spec/company-kit-2026-11-13/README.md), upstream commit `bb98332`, with Operations 3 and Mediated Sign-In 1. Spoken at runtime beside 0.4; a newer snapshot replaces it after review. The [1.0 upgrade](poppy-1.0-upgrade.md) has the work and its ledger. `npm run check:spec` verifies every pin offline, retired ones included, and that the runtime pins are exactly the versions in `src/poppy/protocol-version.ts`. `npm run spec:drift` compares the pins with the live site: for a frozen version, only its own pages and its changelog entry titles; for a draft, every page. An extension can change between draft revisions without changing its version. diff --git a/interop/README.md b/interop/README.md index f7b8e06..1363290 100644 --- a/interop/README.md +++ b/interop/README.md @@ -29,12 +29,12 @@ npm run interop -- --agents lenient-personal-agent,strict-personal-agent,sloppy- | `--out dir` | Where to write results, instead of `interop/results//`. | | `--image-tag tag` | Build and run under a Docker tag (default `latest`); `--image-tag adv` keeps a full grid run's `:latest` images untouched. The only way to keep a side build of our images: don't `docker tag` them by hand, and `docker image rm poppy-interop/:` a side tag when you're done with it (the runner never removes images). | -**Adversarial cells** (the malicious `evil-company`, the raw 0.4 `evil-personal-agent`, and the fault-injection proxy; [`docs/adversarial-interop.md`](../docs/adversarial-interop.md)) run only against our own `owner: "self"` implementations, on the local lane, never live, with one exception: `evil-company` may attack other projects' agents. No flag lifts the rest ([`SECURITY.md`](../SECURITY.md), [`docs/interop-spec.md`](../docs/interop-spec.md) §13). They appear in a separate security grid in `index.html` and never count toward the interop pass rates. Run with no `--agents` and `--scenarios`, `npm run interop` pairs every adversarial scenario with every implementation too; the runner refuses each such cell with a third-party side, other than an agent facing `evil-company`, before anything is sent and records it as `error`, blame `harness` (spec §13), so that command always exits 1. A full grid is the honest scenarios with every agent and Company ([the command](../docs/interop-results/README.md)) plus the three security commands below. CI runs all three with `--require-supported`, so a missing manifest entry or feature fails the run instead of silently skipping a security check. +**Adversarial cells** (the malicious `evil-company`, the raw `evil-personal-agent`, and the fault-injection proxy; [`docs/adversarial-interop.md`](../docs/adversarial-interop.md)) run only against our own `owner: "self"` implementations, on the local lane, never live, with one exception: `evil-company` may attack other projects' agents. No flag lifts the rest ([`SECURITY.md`](../SECURITY.md), [`docs/interop-spec.md`](../docs/interop-spec.md) §13). They appear in a separate security grid in `index.html` and never count toward the interop pass rates. Run with no `--agents` and `--scenarios`, `npm run interop` pairs every adversarial scenario with every implementation too; the runner refuses each such cell with a third-party side, other than an agent facing `evil-company`, before anything is sent and records it as `error`, blame `harness` (spec §13), so that command always exits 1. A full grid is the honest scenarios with every agent and Company ([the command](../docs/interop-results/README.md)) plus the three security commands below. CI runs all three with `--require-supported`, so a missing manifest entry or feature fails the run instead of silently skipping a security check. ```sh npm run interop -- --image-tag adv --require-supported --agents pda --companies evil-company --scenarios XH,XI,BX,XB,XN,XP,XE,XR -npm run interop -- --image-tag adv --require-supported --agents pda --companies lenient-company,strict-company --scenarios CDUP,CIDUP,ODUP,NREP -npm run interop -- --image-tag adv --require-supported --agents evil-personal-agent --companies lenient-company,strict-company --scenarios YR,YD,YA,YT,YS,YK,YU,YM +npm run interop -- --image-tag adv --require-supported --agents pda --companies lenient-company,strict-company,lenient-company-v04 --scenarios CDUP,CIDUP,ODUP,NREP +npm run interop -- --image-tag adv --require-supported --agents evil-personal-agent --companies lenient-company,strict-company,lenient-company-v04 --scenarios YR,YD,YA,YT,YS,YK,YU,YM ``` `--image-tag adv` builds our images under a side tag so a grid run in progress keeps its `:latest` ones. When no grid is running, `--no-build` reuses `:latest` instead (`evil-company` is our image with `INTEROP_ADVERSARY` set). The YR/YD URL-binding probes include unused jtIs, and NREP retries the consumed authorization code with fresh assertion and DPoP credentials, so optional replay policies cannot hide missing request binding or code single-use checks. A side tag stays on Docker's disk until you remove it: `docker image rm poppy-interop/agent-pda:adv poppy-interop/company-lenient-company:adv poppy-interop/proxy:adv`. @@ -111,7 +111,7 @@ files/ Files scenarios upload (an api step's args.files): lake.jpg runner/ The CLI, cell runner, checks, attribution and report proxy/ The recording TLS proxy and the control relay (Node, no dependencies) impls/pda-agent/ Our agent: src/poppy in Node, no model, registered as pda and the three fake Personal Agents (profiles.ts) -impls/pda-mock/ Our mock Company (test/mock-company) behind the hooks API, registered as lenient-company, strict-company and evil-company +impls/pda-mock/ Our mock Company (test/mock-company) behind the hooks API, registered as lenient-company, strict-company, lenient-company-v04 and evil-company impls/shared/ What our two adapters share: the HTTP shim, the esbuild bundle, and the mock's hooks (mock-hooks.ts, also used by test/hypothesis) test/ Unit tests for the runner, in Node (interop/vitest.config.ts, part of npm test) ``` @@ -142,13 +142,13 @@ Our two adapters each register a set of fakes: our own code with a profile, buil | Lenient | `lenient-personal-agent`, the reference agent: accepts every reading of what a Company does that gives no more access (S3 metadata at either location; another of the Company's names as `aud` after `invalid_client` at an endpoint without DPoP) | `lenient-company`, the reference Company: S2-lenient assertions | | Strict | `strict-personal-agent`: runs the runner's Company-side checks and the validator over everything it receives, refuses at the first finding of any level, a SHOULD or the Guides included, and serves its findings at `GET /violations` | `strict-company`: `typ: "JWT"`, a published `kid` and 60-second assertions | | Sloppy | `sloppy-personal-agent`: the mistakes real agents make, declared honestly in its readings: no `typ`, 300-second assertions, and a token-endpoint `aud` everywhere, where 4.1 says the issuer | none | -| Evil | `evil-personal-agent`: raw 0.4 requests with accepted controls, precise mutation checks and refusal/effect oracles; local own-project Companies only | `evil-company`: the mock reconfigured per attack | +| Evil | `evil-personal-agent`: raw requests at the Company's version, with accepted controls, precise mutation checks and refusal/effect oracles; local own-project Companies only | `evil-company`: the mock reconfigured per attack | -`INTEROP_AGENT_PROFILE` (`lenient`, `strict` or `sloppy`) and `INTEROP_MOCK_PROFILE` set the profile, from the registry's `env`. An agent's profile lives only in the adapter's network seam (`impls/pda-agent/profiles.ts`): `src/poppy` runs unchanged. Since 0.3 was dropped on 12 November 2026 ([decision 49](../docs/decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)), every agent declares 0.4 alone and both mocks serve 0.4 alone; the `print-with-poppy` Company left the registry while it served 0.3 alone, and came back at 0.4 the same day, pinned at `ae453ed`, then at `bd1dc43`, which reads 0.4's `poppy_dlg`, and then at `20a3d56`, which writes approval amounts in whole units ([interop spec §15](../docs/interop-spec.md#15-retired-with-03)). Renamed on 23 October 2026: `pda-mock` is now `lenient-company`, `pda-mock-strict` `strict-company`, `pda-mock-v02` `lenient-company-v02` and `evil-agent` `evil-personal-agent`. Results and dated notes from before then use the old names. +`INTEROP_AGENT_PROFILE` (`lenient`, `strict` or `sloppy`) and `INTEROP_MOCK_PROFILE` set the profile, from the registry's `env`. An agent's profile lives only in the adapter's network seam (`impls/pda-agent/profiles.ts`): `src/poppy` runs unchanged. Since 0.3 was dropped on 12 November 2026 ([decision 49](../docs/decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)), every agent declares 0.4 alone and both mocks serve 0.4 alone; the `print-with-poppy` Company left the registry while it served 0.3 alone, and came back at 0.4 the same day, pinned at `ae453ed`, then at `bd1dc43`, which reads 0.4's `poppy_dlg`, and then at `20a3d56`, which writes approval amounts in whole units ([interop spec §15](../docs/interop-spec.md#15-retired-with-03)). Renamed on 23 October 2026: `pda-mock` is now `lenient-company`, `pda-mock-strict` `strict-company`, `pda-mock-v02` `lenient-company-v02` and `evil-agent` `evil-personal-agent`. Results and dated notes from before then use the old names. Since 13 November ([decision 51](../docs/decisions.md#51-10-beside-04)) every agent declares 0.4 and 1.0; `lenient-company` and `strict-company` serve 1.0, and `lenient-company-v04`, the lenient mock with `INTEROP_MOCK_VERSION=0.4`, serves 0.4, so CI runs our agent and `evil-personal-agent` at both. **pda-agent** bundles `src/poppy` with esbuild and runs it in Node: the same `PoppyClient`, sign-in, conversation, API and operations code the Durable Object runs. Node has no `HTMLRewriter`, so `impls/pda-agent/html-rewriter.ts` gives it Cloudflare's lol-html in WebAssembly (`html-rewriter-wasm`), and the agent reads pages, and the browser join its code, as the Worker does. Node's built-in SQLite stands in for the Durable Object's (`impls/pda-agent/sqlite.ts` implements the part of `SqlStorage` src/poppy uses), and jobs the Durable Object would schedule run when a step waits on them. It needs no relaxation: `*.interop.test` names pass src/poppy's public-host check, and Node trusts the run's CA. `web_join` (scenario W) browses as `poppy_browse` does, with src/poppy's fetch-based browser, which reads the join page's code with the lol-html `HTMLRewriter` above, joins the Session and follows the 303 with the Company's cookie. `confirm_again` (O2) sends the agent's recorded confirm again through the client's own DPoP-bound request, since src/poppy never re-confirms an operation it knows was confirmed. `INTEROP_FAULT=assertion-typ` re-signs every client and Session assertion without `typ`, in the adapter's network seam, to prove attribution; it is off unless set and never reaches `src/`. In the live lane, `INTEROP_LIVE_CLIENT_ID` and `INTEROP_LIVE_KEY` make it sign as the interop test client ([above](#the-live-lanes-identity); `impls/pda-agent/live-identity.ts`), with src/poppy's `PoppyClient` unchanged but for its `identity`. -**pda-mock** runs the conformance suite's mock Company unchanged, moved to `.company.interop.test` by `placeCompanies` in `test/mock-company/types.ts`. It rotates refresh tokens and polls devices every second. Its hooks map to the RPC the conformance tests use, and every violation it records becomes an agent-side error check. `INTEROP_MOCK_PROFILE` picks its settings: `lenient-company`, the reference Company for attribution rule 2, runs the S2-lenient profile (`strictAssertions: false`, as the conformance suite's "lenient assertions" profile: no `typ` or `kid` needed, assertions up to 300 s) and declares S2 `any`, since the spec treats S2 as a warning; **strict-company** is the same image with `INTEROP_MOCK_PROFILE=strict` (registry `env`), refuses assertions without `typ: "JWT"`, a published `kid` and a 60-second lifetime, and declares S2 `jwt-60s`. A typ-less agent that declares S2 `any` fails there by rule 3 (reading), not rule 1. +**pda-mock** runs the conformance suite's mock Company unchanged, moved to `.company.interop.test` by `placeCompanies` in `test/mock-company/types.ts`. It rotates refresh tokens and polls devices every second. Its hooks map to the RPC the conformance tests use, and every violation it records becomes an agent-side error check. `INTEROP_MOCK_PROFILE` picks its settings: `lenient-company`, the reference Company for attribution rule 2, runs the S2-lenient profile (`strictAssertions: false`, as the conformance suite's "lenient assertions" profile: no `typ` or `kid` needed, assertions up to 300 s) and declares S2 `any`, since the spec treats S2 as a warning; **strict-company** is the same image with `INTEROP_MOCK_PROFILE=strict` (registry `env`), refuses assertions without `typ: "JWT"`, a published `kid` and a 60-second lifetime, and declares S2 `jwt-60s`. It also requires Pushed Authorization Requests (`INTEROP_MOCK_PAR=required`): the agent adapter opens the card's link to its own sign-in page as the User's browser would, and the harness gets the Company's URL it redirects to. A typ-less agent that declares S2 `any` fails there by rule 3 (reading), not rule 1. ## Base images diff --git a/interop/impls/pda-agent/adapter.ts b/interop/impls/pda-agent/adapter.ts index cefe838..e8689b7 100644 --- a/interop/impls/pda-agent/adapter.ts +++ b/interop/impls/pda-agent/adapter.ts @@ -6,7 +6,7 @@ * jobs run when a step waits on them instead of by alarms. * * Port 8080: our client metadata and keys at `$INTEROP_ORIGIN/poppy/*.json` - * (behind the recording proxy), and `/poppy/callback` for Direct Sign-In. + * (behind the recording proxy), and `/poppy/callback` and `/poppy/sign-in` for Direct Sign-In. * Port 8081: the manifest and control API, with `Authorization: Bearer $INTEROP_SECRET`. * * No relaxation of src/poppy is needed: `*.interop.test` names already pass @@ -43,6 +43,7 @@ import { handleIdentityRoute } from "../../../src/poppy/routes.ts"; import { completeDirectSignIn, pollDeviceSignIn, + pushDirectSignIn, signOut, startSignIn, submitCredentials, @@ -82,7 +83,7 @@ const MANIFEST = { name: NAME, role: "agent", commit: COMMIT, - // Every version src/poppy speaks, 0.4 alone (decision 49); the adversarial agent's raw requests are 0.4 too (attacks.ts). + // Every version src/poppy speaks, 0.4 and 1.0 (decision 51); the adversarial agent's raw requests declare the Company's version too (attacks.ts). poppy: [...PROTOCOL_VERSIONS], extensions: ["operations"], scenarios: ADVERSARY ? [...ATTACKS] : [ @@ -426,7 +427,17 @@ const STEPS: Record Promise } pending.set(`${c.issuer}|${sessionLabel}`, { id: started.signInId, type: started.type, issuer: c.issuer, label: sessionLabel }); const card = agent.cards.get(`signin-${started.signInId}`); - if (card?.kind === "signin_link") return { pending: { type: "direct", url: card.url } }; + if (card?.kind === "signin_link") { + // With Pushed Authorization Requests the card links to the agent's own page (1.0: 4.2). Opening it pushes + // the request, as the User's browser would, and the harness gets the Company's URL it redirects to. + const page = new URL(card.url); + if (page.origin === ORIGIN && page.pathname === "/poppy/sign-in") { + const pushed = await pushDirectSignIn(agent.client, page.searchParams.get("id") ?? ""); + if (!pushed.ok) throw new StepError(pushed.status, "push_refused", pushed.message); + return { pending: { type: "direct", url: pushed.location } }; + } + return { pending: { type: "direct", url: card.url } }; + } if (card?.kind === "signin_device") { return { pending: { @@ -910,6 +921,13 @@ async function site(request: Request): Promise { const outcome = await completeDirectSignIn(agent.client, url); return new Response(outcome.message, { status: outcome.ok ? 200 : 400, headers: { "content-type": "text/plain" } }); } + // A Company that lists pushed_authorization_request_endpoint: the card links here, and opening it pushes the request (1.0: 4.2). + if (url.pathname === "/poppy/sign-in" && request.method === "GET") { + const pushed = await pushDirectSignIn(agent.client, url.searchParams.get("id") ?? ""); + return pushed.ok + ? new Response(null, { status: 303, headers: { Location: pushed.location, "Cache-Control": "no-store" } }) + : new Response(pushed.message, { status: pushed.status, headers: { "content-type": "text/plain" } }); + } return new Response("Not found", { status: 404 }); } diff --git a/interop/impls/pda-agent/attacks.ts b/interop/impls/pda-agent/attacks.ts index c1d1ea8..c40bc6d 100644 --- a/interop/impls/pda-agent/attacks.ts +++ b/interop/impls/pda-agent/attacks.ts @@ -1,5 +1,5 @@ /** - * Raw, deliberately invalid Poppy 0.4 requests. Only the local adversarial + * Raw, deliberately invalid Poppy requests, declaring the Company's version. Only the local adversarial * adapter imports this; no production client relaxation or live identity. * Every probe first establishes an accepted, otherwise equivalent request. */ diff --git a/interop/impls/pda-mock/adapter.ts b/interop/impls/pda-mock/adapter.ts index e5fbccf..b73a202 100644 --- a/interop/impls/pda-mock/adapter.ts +++ b/interop/impls/pda-mock/adapter.ts @@ -76,16 +76,25 @@ if (process.env.INTEROP_MOCK_PROFILE && process.env.INTEROP_MOCK_PROFILE !== PRO throw new Error(`INTEROP_MOCK_PROFILE must be lenient or strict, not ${process.env.INTEROP_MOCK_PROFILE}`); } /** - * The version the mock serves (3.4): the newest our client speaks, alone in - * poppy.json, so a pair of our own builds can never drift apart (decision 37). - * 0.4 since 0.3 was dropped (decision 49); the adversarial agent's raw - * requests are 0.4 too. + * The version the mock serves (3.4), alone in poppy.json: the newest our + * client speaks, 1.0, so a pair of our own builds can never drift apart + * (decision 37), or the one `INTEROP_MOCK_VERSION` names, so the grid keeps + * 0.4 too (`lenient-company-v04`; decision 51). */ -const WIRE_VERSION = PROTOCOL_VERSIONS.at(-1)!; +const WIRE_VERSION = process.env.INTEROP_MOCK_VERSION ?? PROTOCOL_VERSIONS.at(-1)!; +if (!(PROTOCOL_VERSIONS as readonly string[]).includes(WIRE_VERSION)) { + throw new Error(`INTEROP_MOCK_VERSION must be one of ${PROTOCOL_VERSIONS.join(", ")}, not ${WIRE_VERSION}`); +} +/** Pushed Authorization Requests (1.0: 4.2; RFC 9126), from `INTEROP_MOCK_PAR`: `strict-company` requires them. */ +const PAR = process.env.INTEROP_MOCK_PAR ?? "none"; +if (PAR !== "none" && PAR !== "offered" && PAR !== "required") { + throw new Error(`INTEROP_MOCK_PAR must be none, offered or required, not ${PAR}`); +} const BASE: Partial = { ...MOCK_BASE, protocolVersion: WIRE_VERSION, - strictAssertions: PROFILE === "strict" + strictAssertions: PROFILE === "strict", + pushedAuthorization: PAR }; // `PUBLIC_ORIGIN` is where the mock would reach our Worker directly in tests; diff --git a/interop/registry.json b/interop/registry.json index c48e98b..7ea98bc 100644 --- a/interop/registry.json +++ b/interop/registry.json @@ -73,9 +73,23 @@ "build": "interop/impls/pda-mock", "context": ".", "env": { - "INTEROP_MOCK_PROFILE": "strict" + "INTEROP_MOCK_PROFILE": "strict", + "INTEROP_MOCK_PAR": "required" }, - "notes": "The same image as lenient-company with the mock's strict profile: assertion typ \"JWT\", a kid naming a published key and a 60-second lifetime (S2 jwt-60s), as the strictest live Companies require." + "notes": "The same image as lenient-company with the mock's strict profile: assertion typ \"JWT\", a kid naming a published key and a 60-second lifetime (S2 jwt-60s), as the strictest live Companies require. It also requires Pushed Authorization Requests (1.0 4.2, INTEROP_MOCK_PAR), so every Direct Sign-In in the grid runs both ways." + }, + { + "name": "lenient-company-v04", + "role": "company", + "owner": "self", + "source": "https://github.com/adewale/pda", + "commit": "HEAD", + "build": "interop/impls/pda-mock", + "context": ".", + "env": { + "INTEROP_MOCK_VERSION": "0.4" + }, + "notes": "The same image as lenient-company serving 0.4 alone, while the other mocks serve 1.0 (decision 51), so the grid runs our agent at both versions." }, { "name": "print-with-poppy", diff --git a/interop/runner/checks.ts b/interop/runner/checks.ts index 359d934..e828010 100644 --- a/interop/runner/checks.ts +++ b/interop/runner/checks.ts @@ -153,7 +153,7 @@ export function assertionChecks(all: readonly Exchange[]): Check[] { else if (seen.has(payload.jti)) found.push(check("client-assertion.jti-reused", x, `jti ${payload.jti} again`)); else seen.add(payload.jti); // 4.1: aud is the issuer, as a single string, whichever of its endpoints the assertion goes to. - const issuer = all.filter(isServerMetadata).map((exchange) => jsonBody(exchange.responseBody) as Record | undefined).find((doc) => doc && typeof doc === "object" && !Array.isArray(doc) && [doc.token_endpoint, doc.revocation_endpoint, doc.device_authorization_endpoint].includes(x.url.href)); + const issuer = all.filter(isServerMetadata).map((exchange) => jsonBody(exchange.responseBody) as Record | undefined).find((doc) => doc && typeof doc === "object" && !Array.isArray(doc) && [doc.token_endpoint, doc.revocation_endpoint, doc.device_authorization_endpoint, doc.pushed_authorization_request_endpoint].includes(x.url.href)); if (Array.isArray(payload.aud)) found.push(check("client-assertion.aud-array", x, "aud is an array")); else if (issuer && payload.aud !== issuer.issuer) found.push({ ...check("client-assertion.aud-array", x, `aud ${JSON.stringify(payload.aud)}, not the issuer ${JSON.stringify(issuer.issuer)}`), id: "client-assertion.aud", basis: "MUST", severity: "error" }); if (clientId && (payload.iss !== clientId || payload.sub !== clientId)) { diff --git a/interop/scenarios/D.json b/interop/scenarios/D.json index 914e68b..05e043b 100644 --- a/interop/scenarios/D.json +++ b/interop/scenarios/D.json @@ -7,7 +7,7 @@ "needs": { "agent": ["discover"] }, "steps": [ { "agent": "discover", "save": "d" }, - { "expect": { "${d.issuer}": { "$match": "^https://" }, "${d.poppy_version}": { "$match": "^0\\." } } }, + { "expect": { "${d.issuer}": { "$match": "^https://" }, "${d.poppy_version}": { "$match": "^(0\\.4|1\\.0)$" } } }, { "runner": "assert_trace", "params": { "check": "request_seen", "method": "GET", "path": "^/\\.well-known/poppy\\.json$", "status": 200 } }, { "runner": "assert_trace", "params": { "check": "request_seen", "method": "GET", "path": "/\\.well-known/oauth-authorization-server(/|$)", "status": 200 } } ] diff --git a/interop/test/legacy-conversation-migration.test.ts b/interop/test/legacy-conversation-migration.test.ts index adb3beb..9aec43b 100644 --- a/interop/test/legacy-conversation-migration.test.ts +++ b/interop/test/legacy-conversation-migration.test.ts @@ -5,7 +5,7 @@ import { PoppyClient, type PoppyHost } from "../../src/poppy/client"; import { migrate } from "../../src/poppy/store"; import { readConversation, updateAvailability } from "../../src/poppy/conversations"; import { buildActivity, openAtCompanies } from "../../src/poppy/activity"; -import { PROTOCOL_REVISION } from "../../src/poppy/protocol-version"; +import { PROTOCOL_REVISIONS } from "../../src/poppy/protocol-version"; import type { Company } from "../../src/poppy/discovery"; const ISSUER = "https://auth.shop.example"; @@ -108,7 +108,7 @@ describe("retiring conversations that cannot survive the protocol upgrade", () = expect(evidence(f)).toEqual(kept); }); - it.each([undefined, PROTOCOL_REVISION])("preserves a current conversation with revision=%s on repeated migrations", async specificationRevision => { + it.each([undefined, PROTOCOL_REVISIONS["0.4"]])("preserves a current conversation with revision=%s on repeated migrations", async specificationRevision => { const f = await fixture(); const current = { ...f.company, specificationRevision }; addConversation(f, "cnv_current", current); diff --git a/interop/test/legacy-state-migration.test.ts b/interop/test/legacy-state-migration.test.ts index 665220b..eb9a6f0 100644 --- a/interop/test/legacy-state-migration.test.ts +++ b/interop/test/legacy-state-migration.test.ts @@ -4,7 +4,7 @@ import { PoppyClient, type PoppyHost } from "../../src/poppy/client"; import { recoverSignIns } from "../../src/poppy/signin"; import { migrate } from "../../src/poppy/store"; import type { Company } from "../../src/poppy/discovery"; -import { PROTOCOL_REVISION } from "../../src/poppy/protocol-version"; +import { PROTOCOL_REVISIONS } from "../../src/poppy/protocol-version"; const ISSUER = "https://auth.shop.example"; @@ -65,7 +65,7 @@ describe("state retained across protocol upgrades", () => { it("keeps current 0.4 pending and recovery records, their secrets and cards on repeated migrations", async () => { const f = fixture(); const company = await f.client.company("shop.example"); - expect(company.specificationRevision).toBe(PROTOCOL_REVISION); + expect(company.specificationRevision).toBe(PROTOCOL_REVISIONS["0.4"]); for (const status of ["pending", "code", "exchanging", "exchanged", "stored"]) { const secret = await unfinished(f, company, status, status); const card = JSON.stringify({ id: `signin-${status}`, kind: "signin_link", company: "Shop", open: true }); diff --git a/interop/test/runner.test.ts b/interop/test/runner.test.ts index 8ac03bb..f7a9ba6 100644 --- a/interop/test/runner.test.ts +++ b/interop/test/runner.test.ts @@ -158,7 +158,9 @@ describe("the registry and known failures", () => { const entry = (name: string) => registry.implementations.find((item) => item.role === "company" && item.name === name)!; expect(imageOf(entry("lenient-company"), registry)).toBe("poppy-interop/company-lenient-company:latest"); expect(imageOf(entry("strict-company"), registry)).toBe("poppy-interop/company-lenient-company:latest"); - expect(entry("strict-company").env).toEqual({ INTEROP_MOCK_PROFILE: "strict" }); + expect(entry("strict-company").env).toEqual({ INTEROP_MOCK_PROFILE: "strict", INTEROP_MOCK_PAR: "required" }); + expect(imageOf(entry("lenient-company-v04"), registry)).toBe("poppy-interop/company-lenient-company:latest"); + expect(entry("lenient-company-v04").env).toEqual({ INTEROP_MOCK_VERSION: "0.4" }); }); }); diff --git a/interop/test/spec-drift.test.mjs b/interop/test/spec-drift.test.mjs index d7d3a30..d7f30d1 100644 --- a/interop/test/spec-drift.test.mjs +++ b/interop/test/spec-drift.test.mjs @@ -36,18 +36,19 @@ globalThis.fetch=async input=>{ expect(moved.stdout).toContain("CHANGED 0.4-spec"); expect(moved.stdout).toContain("CHANGED 0.3-guides"); - // The shared changelog: each published version compares only its own entry titles (a draft would compare the whole text). + // The shared changelog: each published version compares only its own entry titles, and the draft the whole text. const changelog = run("changed:changelog"); expect(changelog.status).toBe(1); - expect(changelog.stdout).not.toContain("CHANGED changelog "); expect(changelog.stdout).toContain("CHANGED 0.3 changelog entries"); expect(changelog.stdout).toContain("CHANGED 0.4 changelog entries"); + expect(changelog.stdout.match(/CHANGED changelog /g)).toHaveLength(1); + expect(changelog.stdout).toContain("before updating the 1.0 pin"); - // A shared page is checked once, for the newest pin (a draft if there is one); the older version ignores it. + // A shared page is checked once, for the newest pin (the 1.0 draft); the published versions ignore it. const shared = run("changed:introduction"); expect(shared.status).toBe(1); expect(shared.stdout.match(/CHANGED introduction/g)).toHaveLength(1); - expect(shared.stdout).toContain("the 0.4 pin"); + expect(shared.stdout).toContain("the 1.0 pin"); const unavailable = run("removed:0.3-spec", "500"); expect(unavailable.status).toBe(1); diff --git a/pda-spec.md b/pda-spec.md index 2813425..0a2e228 100644 --- a/pda-spec.md +++ b/pda-spec.md @@ -6,7 +6,7 @@ This spec follows **Personal Agent Protocol ("Poppy") 0.4, published on 10 Novem ## Protocol versions -PDA speaks 0.4 alone. [spec/upstream.json](spec/upstream.json) pins its reviewed snapshot and kit, and the upstream commit whose text they match; `npm run check:spec` checks them, and `npm run spec:drift` reports when the site changes. The agent chooses the newest version a Company offers that it speaks, in its `poppy.json` or through `supported_versions` on the same host (§3.4), declares it in every request of a Session, and keeps a conversation in the versions it started in. A `poppy.json` that declares any other version, 0.3 included, is refused before its issuer is used (§3.1). The version choice stays generic, so a new version is added as data ([upgrading](docs/upgrading.md)). 0.4's agent approvals and browser are [decision 44](docs/decisions.md#44-operations-3-with-agent-approvals-a-real-browser-and-the-fetch-browser-under-04), and the handover browser ships off ([decision 48](docs/decisions.md#48-browser-control-ships-off)). The [0.4 upgrade](docs/poppy-0.4-upgrade.md) gives each of its 44 changelog entries a disposition, and [docs/poppy-0.4-issues.md](docs/poppy-0.4-issues.md) drafts the problems we found in its text; [readings](docs/readings.md) has the smaller choices. The owner dropped 0.3 on 12 November ([decision 49](docs/decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)), after speaking it beside 0.4 ([decision 43](docs/decisions.md#43-03-beside-04-both-versions-website-operations-and-approvals-across-sessions)), and 0.1 and 0.2 on 28 October ([decision 37](docs/decisions.md#37-03-alone-what-dropping-01-and-02-overturns-and-settles)). 0.3's [ledger](docs/poppy-0.3-upgrade.md) and [issues](docs/poppy-0.3-issues.md) are kept as history. +PDA speaks 0.4 and, beside it, the 1.0 draft retrieved on 13 November (upstream commit `bb98332`; [decision 51](docs/decisions.md#51-10-beside-04)). [spec/upstream.json](spec/upstream.json) pins each version's reviewed snapshot and kit, and the upstream commit whose text they match; `npm run check:spec` checks them, and `npm run spec:drift` reports when the site changes. The agent chooses the newest version a Company offers that is compatible with one it speaks, in its `poppy.json` or through `supported_versions` on the same host (§3.4), declares the version it implements in every request of a Session, and keeps a conversation in the versions it started in. From 1.0 a newer minor version is compatible, so a 1.1 document is used as 1.0. A `poppy.json` that declares any other version, 0.3 included, is refused before its issuer is used (§3.1). The version choice stays generic, so a new version is added as data ([upgrading](docs/upgrading.md)). 0.4's agent approvals and browser are [decision 44](docs/decisions.md#44-operations-3-with-agent-approvals-a-real-browser-and-the-fetch-browser-under-04), and the handover browser ships off ([decision 48](docs/decisions.md#48-browser-control-ships-off)). The [1.0 upgrade](docs/poppy-1.0-upgrade.md) gives 1.0's 15 changelog entries a disposition: descriptions of conversation protocols, `prompt=consent` and skipping unknown stream events apply to 1.0 alone, while Pushed Authorization Requests and the same DPoP key at refresh apply under both versions. The [0.4 upgrade](docs/poppy-0.4-upgrade.md) gives each of 0.4's 44 changelog entries a disposition, and [docs/poppy-0.4-issues.md](docs/poppy-0.4-issues.md) drafts the problems we found in its text; [readings](docs/readings.md) has the smaller choices. The owner dropped 0.3 on 12 November ([decision 49](docs/decisions.md#49-03-dropped-the-agent-mock-validator-and-interop-speak-04-alone)), after speaking it beside 0.4 ([decision 43](docs/decisions.md#43-03-beside-04-both-versions-website-operations-and-approvals-across-sessions)), and 0.1 and 0.2 on 28 October ([decision 37](docs/decisions.md#37-03-alone-what-dropping-01-and-02-overturns-and-settles)). 0.3's [ledger](docs/poppy-0.3-upgrade.md) and [issues](docs/poppy-0.3-issues.md) are kept as history. The design is not a deployment record; see [deployment tasks](docs/deployment-tasks.md) for the last recorded commit and live checks. See [the changelog](CHANGELOG.md) and [upgrade procedure](docs/upgrading.md) before promotion or rollback. @@ -153,6 +153,7 @@ App sign-in is the Worker's own Google and GitHub OAuth. It is separate from Pop | `GET /poppy/client.json` | The Poppy client metadata document; its URL is our `client_id` | M3 | | `GET /poppy/jwks.json` | Our public signing keys | M3 | | `GET /poppy/callback` | Direct Sign-In redirect target; the app session picks the person's agent | M3 | +| `GET /poppy/sign-in?id=…` | A Direct Sign-In card's link when the issuer takes Pushed Authorization Requests: the person's agent pushes the request and redirects to the authorization endpoint | Built | | `GET /poppy/interop/client.json`, `GET /poppy/interop/jwks.json` | The interop test client's metadata and public keys (`src/poppy/interop-client.ts`), for the interop harness's live lane. A separate Poppy client: its own `client_id` and keys, no redirect URI, no other route, and nothing to do with anyone's agent. Its private key stays on the machine that runs the harness. 404 unless `INTEROP_LIVE_JWKS` is set | Built | | `GET /validator`, `POST /validator`, `GET`/`POST`/`OPTIONS /validator/api`, `GET /validator/messages` | The public discovery document validator: form, JSON API (any origin, no cookies), message docs. It answers before the deployment check, so it works on a copy nobody has configured | Built | @@ -344,7 +345,7 @@ Settings → Your data streams an export of local records and base64 photo chunk ## Poppy client -The client targets **0.4, the 11 November pin**, and nothing else: a `protocol_version` other than `"0.4"` is refused (`PROTOCOL_VERSIONS` in `src/poppy/protocol-version.ts`). Section numbers below (§) refer to the 0.4 specification, which kept 0.3's; "Guides" means the protocol's guides page; "Ops" means the Operations extension, version 3; "MSI" the Mediated Sign-In extension. The readings 0.4 needed are [0.4 readings](docs/readings.md#04-readings-11-november-text). +The client targets **0.4, the 11 November pin**, and the **1.0 draft, the 13 November pin** (`PROTOCOL_VERSIONS` in `src/poppy/protocol-version.ts`); any other `protocol_version` is refused. 1.0 differs where this section says so. Section numbers below (§) refer to the 0.4 specification, which kept 0.3's; "Guides" means the protocol's guides page; "Ops" means the Operations extension, version 3; "MSI" the Mediated Sign-In extension. The readings 0.4 needed are [0.4 readings](docs/readings.md#04-readings-11-november-text). ### Our agent's identity (§4.1) @@ -386,7 +387,7 @@ For a domain the User or the model names, the client calls `validateCompany` in - **Private addresses, by runtime.** A public-looking name can still resolve to a private address (`127.0.0.1.nip.io`), so the check §3 asks for ("MUST NOT connect to a loopback, private, or link-local address") depends on where the code runs. Workers refuse connections to private destinations themselves, which covers our client and the hosted validator. The Node CLI (`scripts/poppy-validate.ts`) resolves each name itself and refuses it (`http-non-public-address`) if any address is loopback, RFC 1918, link-local, CGNAT, ULA, unspecified, multicast, an IPv4-mapped form of one of those, or in another range that isn't globally reachable; it then connects only to the address it checked (`scripts/node-fetcher.ts`, with `pinnedLookup` from `src/validator/address.ts`). The library alone checks names only, so a caller in any other runtime must supply a fetcher that checks addresses. - **Strict JSON:** a UTF-8 parser that rejects duplicate member names (Guides). 2. **Check the document.** - - Refuse a document whose `protocol_version` isn't `0.4` (§3.1: "MUST NOT use a document whose `major.minor` version it doesn't support"). Choose from `supported_versions` without following a redirect off the host, and fetch `poppy.json` afresh after `version_unsupported` (§3.4). + - Refuse a document whose `protocol_version` isn't `0.4` or a compatible 1.x (§3.1: "MUST NOT use a document whose `major.minor` version it doesn't support"; §3.4). Under 1.0 each `agent.protocols` entry needs a `description`, which the model reads to choose between the Company's agent and its APIs (1.0 §8.1). Choose from `supported_versions` without following a redirect off the host, and fetch `poppy.json` afresh after `version_unsupported` (§3.4). - Require `organization.domain` to equal the host that served the document, after redirects, ignoring case only. - Ignore unknown fields. - Keep only extensions we support (`operations` version `3`, `mediated-sign-in` version `1`, `browser-control` version `1`), read from each extension's list of versions (§3.3), API types we know (`openapi`, `mcp`) and conversation types we know (`poppy`). @@ -417,7 +418,7 @@ For a domain the User or the model names, the client calls `validateCompany` in - **Stable message ids, each with an explanation, a fix and a spec reference**, at `/validator/messages#`. Help links depend on the id only, so changing a message's severity doesn't break them. - **Location.** Each message carries a JSON Pointer and, when parsed from text, a 1-based line and column. The parser keeps going past duplicate member names so it can report them. - **Skipped checks.** A check that needs context the input lacks is listed as skipped rather than passed. Examples: the requested domain for a pasted `poppy.json`, or the fetch URL for client metadata. -- **Versions.** `src/validator/primitives.ts` holds version-independent checks: types, HTTPS URLs, scope tokens, host names, resource indicators, unknown members. `profiles/draft-0.4.ts` composes them into the rules for 0.4, the only version checked, with each rule a separate exported function. A document that declares another version, 0.3 included, is an error, since our client won't use it; a new version adds a profile that imports the rules it keeps from 0.4's and replaces the rest. +- **Versions.** `src/validator/primitives.ts` holds version-independent checks: types, HTTPS URLs, scope tokens, host names, resource indicators, unknown members. `profiles/draft-0.4.ts` composes them into the rules for 0.4, with each rule a separate exported function, and `profiles/draft-1.0.ts` reuses them with 1.0's additions: required protocol descriptions, a port in `organization.domain`, and ES256 and PS384 for client assertions. A newer 1.x minor version is checked with the 1.0 profile and noted (`version-newer-minor`). A document that declares another version, 0.3 included, is an error, since our client won't use it; a new version adds a profile that imports the rules it keeps and replaces the rest. - **The JSON report is versioned** (`outputVersion: 1`). - **Every message is tested.** `test/validator.test.ts` includes a fixture for every message id, and its last test fails if one is missing. The fixtures include the spec's own examples and poppy-demo's live documents. - **Public endpoint limits.** @@ -444,7 +445,8 @@ For a domain the User or the model names, the client calls `validateCompany` in - **Redirects:** it never follows a redirect with a token, Session JWT, assertion or proof (§3). - **DPoP:** only when the issuer lists `dpop_signing_alg_values_supported` with ES256 (§4.5). Then token requests carry a proof, and so do requests with a DPoP-bound access token, signed in a hook that sees the final method and URL, with `ath` and the server's `nonce`. -- **Nonces:** on `use_dpop_nonce` it takes `DPoP-Nonce`, keeps it in memory per server origin, and retries once with a new proof. +- **DPoP keys:** one per issuer and User ID, its private key sealed in `poppy_dpop_keys` and opened as a non-extractable key, so a refresh after a restart or eviction carries a proof from the key the refresh token was issued with (1.0 §4.4, under both versions; [decision 51](docs/decisions.md#51-10-beside-04)). +- **Nonces:** on `use_dpop_nonce` it takes `DPoP-Nonce`, keeps it per server origin in `poppy_dpop_nonces`, since the keys that used it outlive a restart, and retries once with a new proof. - **Operator signatures (§5.3):** with the optional `POPPY_OPERATOR_KEY`, every request that carries the Session header also carries a Web Bot Auth HTTP Message Signature (`src/poppy/operator.ts`). It covers `@method`, `@authority`, `@path`, the `Signature-Agent` member, `Poppy-Session` and `Authorization`, and is made after the Session JWT and DPoP proof. The key, separate from the signing and delegated keys, is published at `/.well-known/http-message-signatures-directory`. - **Session header destinations (§5.2):** endpoints `poppy.json` lists and request URLs its listed API descriptions describe, including an OpenAPI server on another public host; never a link's target, a discovery or description document, an OAuth endpoint or a website page. - **Errors (§7):** `invalid_token` refreshes the access token and retries once; `session_ended` starts a new `sid` once, keeping the account it was signed in to (§5.5); `invalid_session` is final, since a new Session fails the same way; a 401 with no error code and a `scope` challenge is `insufficient_scope`; `extension_required` names the extension. An approval is never sent on a new Session (Operations, below). @@ -489,7 +491,8 @@ A sign-in names no Session. Its tokens sign in whichever Session then sends them **Direct Sign-In (§4.2)** 1. **Prepare.** Create a single-use random `state` and a PKCE verifier (S256). Store them sealed in `poppy_signins` with the issuer. -2. **Send the User.** Push a sign-in card with the authorization URL, opened in a new tab of the User's own browser. The tool returns "waiting for the User", and the model ends its turn. +2. **Send the User.** Push a sign-in card with the authorization URL, opened in a new tab of the User's own browser. The tool returns "waiting for the User", and the model ends its turn. When the issuer lists `pushed_authorization_request_endpoint` (RFC 9126; 1.0 §4.2, under both versions), the card links instead to `GET /poppy/sign-in?id=…` on the agent. Each time the User opens it, the agent pushes the request with the client assertion and a DPoP proof, and redirects (303, `no-store`) to the authorization endpoint with only `client_id` and `request_uri`, since a `request_uri` expires within a minute. The Worker routes it by the app session cookie, as for the callback; without one, it asks the User to sign in to the app and open the link again. + Under 1.x the request also carries `prompt=consent`, so the Company shows its consent page even for scopes the account granted before (1.0 §4.2, §10.8; [reading](docs/readings.md#v10-prompt-consent)). 3. **Route the callback.** `GET /poppy/callback` arrives in the User's browser, so the Worker routes it to their agent by the app session cookie. If the cookie is missing, the Worker asks the User to sign in to the app and start the Company sign-in again. The authorization code is single-use and short-lived, so it is never parked or retried. 4. **Check the callback.** The agent finds the pending sign-in by `state` and rejects any that is missing, expired, already used, or for another Company. It requires `iss` to equal the issuer exactly (RFC 9207), and handles `error=access_denied`. 5. **Exchange the code.** At **that** Company's `token_endpoint`, with `redirect_uri` set exactly to our registered URI, the verifier and the client assertion. The exchange is recorded before it is sent, and its answer kept, sealed, before it is used, so an interrupted sign-in is resolved on the next use of that Company, on restart, or on a reload of the callback. Without a kept answer the code is spent, and the card says the sign-in was interrupted; the Session is untouched, since the sign-in never named it. @@ -772,8 +775,8 @@ Four extensions in `src/tools/`, beside `poppy`, so the agent is useful away fro - Conversation messages aren't gated: under Poppy a message never authorizes an account action (§7.11), and the Company enforces scopes. - **Replay.** Tools are `replay: "safe"` only where a repeat is harmless: reads, message sends with a fixed id, writes with a fixed `Idempotency-Key`, writes with no key that a replay refuses to send again, and writes that only create an approval card, fixed per call. After a crash Pi gives the model an interrupted result for the rest instead of repeating them. - **Secrets** (Guides, "Handling secrets"). - - Access tokens, delegated keys and DPoP keys live only in memory. - - Refresh tokens and pending `state`, verifier, `device_code` and `sign_in_id` values are sealed with AES-GCM, bound to their row. + - Access tokens and delegated keys live only in memory. + - DPoP private keys, refresh tokens and pending `state`, verifier, `device_code` and `sign_in_id` values are sealed with AES-GCM, bound to their row. - Signing keys exist only as a Worker secret. - People's model keys are sealed per agent and provider and opened only to make a model call or check the key (see Model access). - None of them reach the model, tool results, the transcript, logs or URLs. Mediated credentials pass through memory once, from the card to the one request. @@ -912,7 +915,7 @@ Test cases live with their assertions in [test/](test/) and [interop/test/](inte - [ ] **Spec problems.** At 0.4, [`docs/poppy-0.4-issues.md`](docs/poppy-0.4-issues.md) drafts the problems found while implementing it. At 0.3, [`docs/poppy-0.3-issues.md`](docs/poppy-0.3-issues.md) lists 43, written to send to the authors: 39 from reading the 28 October text and 4 found while implementing it. At 0.1, [`docs/history/spec-issues.md`](docs/history/spec-issues.md) listed 64, from comparing implementations (S1 to S23), a full crawl of the site (N1 to N33), the mock's new checks (N34, N35), the interop grid (N39 to N42) and later work (N43 to N47: website submissions with no approval step, when to fetch discovery documents again, a lost code exchange orphaning a token, nothing bounding how long a Company may keep an agent checking, and a refused revocation leaving a grant live), each with a suggested fix and what we do. Six more (S6, S15, S21, N36, N37, N38) were our misreadings and are withdrawn. The ones with the widest effect: sign-in not bound to the Session until the code exchange (N2), step-up revocation signing out other Sessions (N4), non-HTTPS URLs in `poppy.json` (N9), which hosts receive tokens (N10), a shared issuer merging Companies (N11), and the client assertion's `aud` (S1). - [x] **Gaps the crawl found in our own client and mock**, listed in [`docs/history/poppy-issues.md`](docs/history/poppy-issues.md) under "This project". The client's are closed, and so are the mock's. - [x] **M×N interop testing** with the other implementations: built ([`docs/history/interop-testing.md`](docs/history/interop-testing.md), [`docs/interop-spec.md`](docs/interop-spec.md), [`interop/`](interop/README.md)), and so are the adversarial adapters and the fault-injection proxy, run only against our own implementations except `evil-company`, which may also attack other projects' agents on the local lane ([`SECURITY.md`](SECURITY.md) item 5). What's left is the "Not yet" rows of [`docs/adversarial-interop.md`](docs/adversarial-interop.md), and live authenticated journeys. Live 0.3 discovery and the pinned independent demo are recorded separately; the [isolated hosted pair](test/hosted/README.md) is prepared for authenticated checks once its test credentials are configured. -- [ ] **Eviction.** In tests, `evictDurableObject()` timed out after a completed Pi run. If idle agents stay resident, DPoP keys live longer than assumed (harmless); if evictions are frequent, token requests increase. +- [ ] **Eviction.** In tests, `evictDurableObject()` timed out after a completed Pi run. If idle agents stay resident, delegated keys live longer than assumed (harmless); if evictions are frequent, token requests increase. - [x] **Compaction** of the never-ending conversation: a 150k/184k budget, our summarizer, the summary as a notice (The agent, Compaction). Open: a demo-lane turn after a compaction, live. - [ ] **Push notifications** are an open topic, so the agent polls. @@ -1119,7 +1122,7 @@ Historical baseline mapping: the reviewed MUST and MUST NOT requirements that fe - **JSON.** UTF-8, duplicate member names rejected, unknown fields ignored. - **User IDs.** Random, stored per User per issuer, never derived; the privacy notice says each Company recognizes the User by theirs. No anonymous browsing IDs. - **The Session header.** A new Session JWT for each request, signed where the final method and URL are known; redirects from protocol endpoints never followed with it or a token; a random `sid` per Session, never reused; delegated keys made where we sign, non-extractable, in memory, one per User ID; a new delegation ten minutes before the old one expires; `invalid_session` for an ended Session gets a new `sid`. -- **DPoP.** Only at an issuer that lists `dpop_signing_alg_values_supported`: non-extractable keys per User per Company, in memory only, separate from the delegated keys; a nonce kept per server, with one retry. +- **DPoP.** Only at an issuer that lists `dpop_signing_alg_values_supported`: non-extractable keys per User per Company, stored sealed so a refresh uses the key its token was issued with, separate from the delegated keys; a nonce kept per server, also stored, with one retry. - **Tokens.** Refresh tokens sealed, stored by the full issuer and only referenced by tools; access tokens in memory, sent only to the Company's hosts, with the scheme `token_type` names; a service whose protected resource metadata names its own `resource` gets a token of its own, and an MCP server always does; read-only lookups narrowed to the scopes they declare; a rotated refresh token replaces the old one at once; the old one revoked after signing in for more scopes; a refresh token deleted on `invalid_grant`, the Session continuing signed out; a new Session for a second account. - **Sign-in.** A refresh token that covers the task first; then Direct, then Device, then Mediated; the fewest scopes, described as the Company describes them, with their hints; `state` random, single-use and bound to its Company; S256; the authorization URL opened in the User's own browser; device links checked against the issuer's hosts and shown with their code and the Company's name and domain; credentials from a form that skips the model, discarded after use. - **Browsing.** A separate context, with its own host-only cookie jar, per Session of each User; never a credential typed into a site; the join's code read only from our own browser's page and authorized in code the model can't read; a new join when the site stops recognizing the Session; HTTPS on the Company's domain only, redirects included; at most 1 MB, 15 s and 5 redirects a page; forms sent only as the User approved them. diff --git a/scripts/check-company-kit.mjs b/scripts/check-company-kit.mjs index c13aa67..2a08609 100644 --- a/scripts/check-company-kit.mjs +++ b/scripts/check-company-kit.mjs @@ -3,8 +3,8 @@ * Run the verified upstream CLI (optionally a separately patched copy) against local HTTPS/workerd. * `--protocol ` picks the pinned kit for that version (spec/upstream.json); the default is the * newest version the agent speaks. A run needs a version the agent speaks (src/poppy/protocol-version.ts): - * 0.4 alone since 0.3 was dropped (decision 49). `--verify-pin` checks any pinned kit's hashes, so the - * frozen 0.3 kit is still verified. + * 0.4 and 1.0 (decision 51). `--verify-pin` checks any pinned kit's hashes, so the frozen 0.3 kit is + * still verified. */ import assert from "node:assert/strict"; import { spawn, execFileSync } from "node:child_process"; diff --git a/spec/company-kit-2026-11-13/LICENSE b/spec/company-kit-2026-11-13/LICENSE new file mode 100644 index 0000000..d645695 --- /dev/null +++ b/spec/company-kit-2026-11-13/LICENSE @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/spec/company-kit-2026-11-13/README.md b/spec/company-kit-2026-11-13/README.md new file mode 100644 index 0000000..4425f20 --- /dev/null +++ b/spec/company-kit-2026-11-13/README.md @@ -0,0 +1,27 @@ +# Official Company kit, retrieved 13 November 2026 + +The original [website download](https://personalagentprotocol.org/kit/implement-personal-agent-protocol.zip) is `upstream.zip`, an archive dated 13 November 2026 (14:29 in the archive's local time). Its SHA-256 is `81bb287b623e31fc80f8630d149ac415fbe5fe89df46b3d4b33c8ef4adc0c2b0`. It replaced the archive downloaded earlier that day (`78b50cf3…`, upstream `736ef95`) before either was merged. `kit/` contains all 92 extracted files, unmodified. `manifest.json` records every file's hash. The kit is Apache-2.0; its license is retained here. + +This kit is for the 1.0 draft: its validator's `PROTOCOL_VERSION` is `"1.0"`. Its `validate/` and `schemas/` files are upstream `kit/company` at commit `bb98332` apart from links the site rewrites to `/docs/1.0/`; upstream's `validate/test/` isn't in the archive. Its `reference/` pages match our [13 November snapshot](../draft-1.0-retrieved-2026-11-13/README.md) apart from absolute links to the protocol site. + +Against the [11 November kit](../company-kit-2026-11-11/README.md), 39 files changed and none was added: + +- `schemas/poppy.schema.json` requires a `description` on each `agent.protocols` entry (spec 8.1), and allows a port in a domain (3.1). +- `schemas/message.schema.json` lets a `context` field be `null`, which clears it (8.4). +- `schemas/authorization-server-metadata.schema.json` says Companies require PS384 beside ES256 for client assertions, in a description only. +- `validate/catalog.ts` sets `PROTOCOL_VERSION` to `"1.0"`, and makes `assertion.ps384` and `session.delegation-ps384` MUSTs (4.1, 5.2). `discovery.domain-matches-host` and `metadata.protected-resources` allow a port. The validator has no check for the description, Pushed Authorization Requests, `prompt=consent` or DPoP keys at refresh. +- The reference pages, checklist, milestones and patterns for the 1.0 draft. + +Verify the original archive and extracted files from the repository root: + +```sh +node scripts/check-company-kit.mjs --protocol 1.0 --verify-pin +``` + +Run the upstream CLI against our local Companies, which serve 1.0 for this run: + +```sh +node scripts/check-company-kit.mjs --protocol 1.0 --output /tmp/company-kit-1.0.json +``` + +Updates are manual. Download a new artifact only after a request, review its changes, and pin its archive and file hashes together. Neither this command nor CI fetches a newer kit. 1.0 is a draft, so a newer kit replaces this pin after review. diff --git a/spec/company-kit-2026-11-13/kit/SKILL.md b/spec/company-kit-2026-11-13/kit/SKILL.md new file mode 100644 index 0000000..85c369f --- /dev/null +++ b/spec/company-kit-2026-11-13/kit/SKILL.md @@ -0,0 +1,164 @@ +--- +name: implement-personal-agent-protocol +description: Add Personal Agent Protocol (Poppy) support to a Company's existing systems, so personal agents can discover the Company, start Sessions, sign Users in, and use its APIs, MCP servers, Company Agent, and website. Use when an engineer asks to implement Poppy, Personal Agent Protocol, poppy.json, or personal agent access for their company. Covers surveying what exists, designing with the engineer, building in milestones, checking each one with the bundled validator, and drafting an implementation report. +--- + +# Poppy for Companies + +You are working with an engineer at a Company to add Personal Agent Protocol ("Poppy" for short) +support to the Company's systems. You survey what exists, write a design for the engineer to +approve, build it one milestone at a time, check each milestone with the validator, and draft an +implementation report. The engineer makes the decisions this skill marks as theirs. You recommend. + +Always call it "Personal Agent Protocol" or "Poppy". Use the spec's capitalized terms as the spec +does: Personal Agent, Company, User, User ID, Session, Session header, Delegated key, Direct +Sign-In, Device Sign-In, Mediated Sign-In, Company Agent, Direct Conversation. Tokens keep their +OAuth names: access token and refresh token. + +**Done** means the validator passes for everything in the approved design, you have gone through +`checklist.md` for what the validator can't see, and the engineer has a report draft to file. + +## Files in this skill + +`` below is the folder that holds this file. Read the other files when a step calls for +them, not all at once. If you're reading this file from a URL rather than an installed copy, +download and unzip https://personalagentprotocol.org/kit/implement-personal-agent-protocol.zip outside the Company's +repository first, and use the `implement-personal-agent-protocol` folder in it as ``. + +| File | Read it when | +| ----------------------- | --------------------------------------------------------------------------------------------------------------- | +| `survey.md` | Step 1. What to look for, and the template for `plan/survey.md`. | +| `design.md` | Step 2. The decisions, and the template for `plan/design.md`. | +| `patterns/*.md` | Step 2, to choose how to build each component, and again in step 3. | +| `milestones/*.md` | Step 3, one milestone at a time. | +| `checklist.md` | At the end of each milestone, and in step 4. Every Company MUST and SHOULD from the spec, grouped by milestone. | +| `feedback.md` | Before you write the first entry in `plan/feedback.md`. | +| `report.md` | Step 5. | +| `reference/*.md` | Whenever you need the exact rule. `reference/spec.md` is the spec. | +| `schemas/*.schema.json` | When you build a document or message, to check its shape. | +| `validate/` | The validator. Run it, don't edit it. | + +The spec on the site is the same text as `reference/spec.md`. Links in this skill point to the site, +such as [5.6](https://personalagentprotocol.org/docs/1.0/spec#sending-requests). Read the local copy when +you can't fetch the site. + +## The validator + +The validator acts as a Personal Agent against the Company's servers and reports each check as pass, +fail, warn (a SHOULD), or skip. It needs Node 22.18 or later and has no dependencies. + +```sh +node /validate/index.ts survey https://example.com +node /validate/index.ts check https://staging.example.com --milestone foundation +node /validate/index.ts check https://staging.example.com --milestone interfaces +node /validate/index.ts check https://staging.example.com --milestone sign-in +node /validate/index.ts check https://staging.example.com --milestone all +node /validate/index.ts check https://staging.example.com --design plan/design.md +node /validate/index.ts check --file ./poppy.json +node /validate/index.ts keygen --base-url https://static.example.com/poppy-test +node /validate/index.ts report +``` + +- Add `--json` to any command for structured output. The exit code is non-zero when a MUST fails. +- `check --file` checks a `poppy.json` offline, before you deploy it. +- Each failing check gives the requirement with its spec link, what was sent and received (tokens + redacted), the likely cause, and a link to dispute the check. If a check looks wrong, say so in + `plan/feedback.md` (label **Kit**) and tell the engineer about the dispute link. +- Prefer staging or another test environment. `check` works against production too, but there it + starts real Sessions and sends test messages to the company agent, so ask the engineer first. +- This version checks the survey, the foundation milestone, and the signed-out parts of the + interfaces milestone, including browser sessions. For sign-in, handoff, Direct Conversations, and + extensions, the checklist and the manual tests in each milestone file are the check. Don't report + those parts as validated. + +**The test identity.** The validator signs requests as a Personal Agent, so the Company's servers +must be able to fetch its client metadata and keys over HTTPS, as for any Personal Agent +([4.1](https://personalagentprotocol.org/docs/1.0/spec#agent-identity)). In the foundation milestone you +run `keygen` with a base URL the Company controls. It writes `.poppy/` with a private key, +`agent.json`, and `jwks.json`, and adds `.poppy/` to `.gitignore`. The engineer hosts `agent.json` +and `jwks.json` at that base URL, for example in a staging static bucket. `check` then uses +`.poppy/` automatically. The private key never leaves `.poppy/`: never print it, commit it, or copy +it elsewhere. This is a test identity whose key sits on a developer's machine. Don't add it to a production +allowlist. + +## Workflow + +### 1. Survey + +Read `survey.md`, then: + +1. Inspect the code and config you can see: the identity provider or OAuth server and what it + supports, API gateways, OpenAPI descriptions, MCP servers, the support or chat stack and the + live-agent desk, the website's session handling, consent pages, account settings, and the + permission model. +2. Run `node /validate/index.ts survey https://` for what's live. +3. Write `plan/survey.md` from the template in `survey.md`. +4. Ask the engineer the open questions. Vendor-hosted systems, such as an identity provider or a + support platform, are often invisible from code. Don't guess what they support. + +### 2. Design + +Read `design.md` and the patterns that fit what the survey found. Write `plan/design.md` from the +template. It starts with a `poppy-design` block the validator reads. + +**Stop and wait for the engineer's approval** before building anything. Scope (which interfaces, +which sign-in types, which scopes, and the registration or allowlist policy) is the engineer's +decision. Present your recommendation with the trade-offs, and record their decisions in the design. +If the design changes later, update `plan/design.md` and get approval again. + +### 3. Build, one milestone at a time + +For each milestone in the design's plan, in order: + +1. Read `milestones/.md` and the spec sections it lists. +2. Build it, following the patterns chosen in the design. +3. Run the validator for that milestone and fix every failure before moving on. Treat warnings as + SHOULDs: fix them or record in the design why the Company doesn't. +4. Go through the milestone's section of `checklist.md` and do the manual tests the milestone file + lists. +5. Tell the engineer what you built, what passed, and what you checked by hand. + +| Milestone | Builds | Spec | +| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | +| `milestones/foundation.md` | `poppy.json`, protected resource and OAuth server metadata, verifying Personal Agents and the Session header, signed-out Sessions, errors | 3, 4.1, 5.1–5.3, 5.6 | +| `milestones/interfaces.md` | What the design chose: OpenAPI, MCP, conversations, web browsing, feedback. Signed out first. | 6–9 | +| `milestones/sign-in.md` | The chosen sign-in types, refresh and access tokens, sign-out, scope enforcement on every channel, account settings | 4.2–4.7, 5.4–5.5, 8.11, Mediated Sign-In | +| `milestones/extensions.md` | Optional. Extensions the design chose. | 3.3 | + +A Company that offers only its website stops after publishing `poppy.json` without `auth` and +without `web.browser_session_endpoint` ([3.1](https://personalagentprotocol.org/docs/1.0/spec#fields)). + +### 4. Verify + +1. Run `node /validate/index.ts check https:// --design plan/design.md`. + It runs every check and reports progress against the design. Fix every failure. +2. Go through all of `checklist.md` for what the validator can't see, such as logging and secret + redaction, consent page wording, rate limits, and token lifetimes. Mark each item done, not + applicable (with why), or open. +3. Tell the engineer which items are open. + +### 5. Report + +Read `report.md`. Run `node /validate/index.ts report`, review the draft with the +engineer, and let the engineer file it. You never file an issue or post anything yourself. + +## Feedback, throughout + +From the survey on, whenever something in the spec is unclear, missing, contradictory, risky, or +harder than it needs to be, or something in this kit is wrong or confusing, add an entry to +`plan/feedback.md` right away, in the format in `feedback.md`. Don't save it for the end. The report +in step 5 is built from it. + +## Rules + +- Don't invent requirements. A MUST or SHOULD you state comes from the spec or the guides, with a + link. When the spec doesn't say, it's the Company's choice: ask the engineer, and log a **Gap** or + **Question** if it matters. +- Change existing systems as little as the design allows. Poppy is built to sit on top of what the + Company has. +- Keep secrets out of code, logs, test output, plan files, and the report: tokens, keys, client + assertions, Session JWTs, credentials, and one-time codes + ([guides](https://personalagentprotocol.org/docs/1.0/guides#both-secrets)). +- Ask before changing anything in production, shared infrastructure, or a vendor's configuration. +- Don't modify the validator to make a check pass. If you think a check is wrong, log it and tell + the engineer. diff --git a/spec/company-kit-2026-11-13/kit/checklist.md b/spec/company-kit-2026-11-13/kit/checklist.md new file mode 100644 index 0000000..2e772e6 --- /dev/null +++ b/spec/company-kit-2026-11-13/kit/checklist.md @@ -0,0 +1,608 @@ +# Company checklist + +Generated from the Personal Agent Protocol docs, draft 1.0. It lists every +requirement on the Company in the specification and extensions, and the guides' advice for +companies, grouped by milestone. Go through the sections for the milestones and features in +your design. The validator checks some of these. The rest need a review or a manual test. + +Requirements that apply to both parties are included. Requirements only on Personal Agents +are left out. + +## Foundation + +### Specification: [3. Discovery](https://personalagentprotocol.org/docs/1.0/spec#discovery) + +- [ ] **MUST**: A Company MUST publish its `poppy.json` document at `https://{domain}/.well-known/poppy.json` over HTTPS, where `{domain}` is the Company's domain or a subdomain it controls. +- [ ] **MUST**: Every URL this protocol defines or exchanges MUST be an HTTPS URL: in `poppy.json`, in authorization server and protected resource metadata, in client metadata documents (4.1), in extensions, and in assertions, Session JWTs, and responses. +- [ ] **MUST NOT**: Personal Agents MUST NOT use a URL from a Company that has another scheme, and Companies MUST reject one from a Personal Agent. +- [ ] **MUST NOT**: Personal Agents and Companies MUST NOT connect to a loopback, private, or link-local address for a URL the other party gave them, unless they were configured to on purpose. + +### Specification: [3.1 Fields](https://personalagentprotocol.org/docs/1.0/spec#fields) + +- [ ] **MUST**: `domain` MUST be the host that serves the document, after any redirects, with its port when that isn't 443. +- [ ] **MUST**: It MUST be in that list. +- [ ] **MUST**: With one authorization server, the Company MAY leave it out, and if it includes it, it MUST name that server. + +### Specification: [3.2 OAuth server](https://personalagentprotocol.org/docs/1.0/spec#oauth-server) + +- [ ] **MUST**: A Company that offers sign-in MUST have an OAuth issuer. +- [ ] **MUST**: If the Company publishes this metadata, its `resource` MUST be exactly `https://{organization.domain}`, and its `authorization_servers`, when nonempty, names the issuer: + - [ ] HTTP 404, or valid metadata with `authorization_servers` absent or empty, means the Company has no issuer. This is valid only when `auth.issuer` is absent and the Company offers no sign-in. + - [ ] A Personal Agent MUST NOT use the domain fallback after a timeout, another error status, invalid metadata, or a failure to verify an issuer. It MUST NOT fall back for a Company whose issuer it already knows unless a successful discovery explicitly establishes that the issuer was removed. + - [ ] If it lists one authorization server, that is the Company's issuer. `auth.issuer` is optional, and if present MUST name that server (3.1). + - [ ] If it lists more than one, such as one for the Company's employees, `auth.issuer` in `poppy.json` names the one Personal Agents use (3.1). RFC 9728 leaves the choice among them to the client, but User IDs and refresh tokens belong to one issuer (5.1), so every Personal Agent has to choose the same one. +- [ ] **MUST NOT**: It MUST NOT fall back for a Company whose issuer it already knows unless a successful discovery explicitly establishes that the issuer was removed. +- [ ] **MUST**: `auth.issuer` is optional, and if present MUST name that server (3.1). +- [ ] **MUST NOT**: A Company that sets `auth.disabled` MUST NOT list the Mediated Sign-In extension or `signed_in` access (below). +- [ ] **MUST**: The Company MUST select that same issuer on each domain (above). +- [ ] **MUST**: The Company MUST give each scope the same authorization meaning across these domains. +- [ ] **SHOULD**: The Company SHOULD publish the same scope descriptions and hints across these domains, but MAY expose different scopes or capabilities. +- [ ] **MUST**: An issuer MUST represent exactly one Company. +- [ ] **MUST**: A provider that hosts several Companies MUST give each its own issuer, such as `https://auth.provider.example/shop-a`, even when they share servers. +- [ ] **MUST**: The issuer MUST publish OAuth Authorization Server Metadata (RFC 8414), at the URL RFC 8414 §3.1 defines. +- [ ] **MUST**: Its `protected_resources` (RFC 9728 §4) MUST list `https://{domain}` for every domain whose issuer it is, with no path or trailing slash. +- [ ] **MUST**: Required, and it MUST include `refresh_token` (4.4). +- [ ] **SHOULD**: A Company that offers sign-in SHOULD list every scope a Personal Agent can request here, in `scopes_supported` of its protected resource metadata (above), or in both (4.7). +- [ ] **MUST**: A Company that lists `signed_in` MUST have an issuer, and MUST NOT set `auth.disabled`. + +### Specification: [3.4 Versions](https://personalagentprotocol.org/docs/1.0/spec#versions) + +- [ ] **MUST**: Each URL in `supported_versions` MUST be an HTTPS URL on the host that served `poppy.json`, after any redirects. +- [ ] **MUST**: Every document a Company serves at the same time MUST have the same `organization.domain` and select the same issuer (3.2), so that a new version doesn't change the Company's identifier, and with it User IDs and refresh tokens. +- [ ] **MUST**: An endpoint that verifies the Session header (5.3) MUST also check `Poppy-Version`. +- [ ] **MUST NOT**: 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. + +### Specification: [4. OAuth](https://personalagentprotocol.org/docs/1.0/spec#oauth) + +- [ ] **SHOULD**: A Company that offers sign-in SHOULD offer Direct Sign-In. + +### Specification: [4.1 Agent identity](https://personalagentprotocol.org/docs/1.0/spec#agent-identity) + +- [ ] **MUST**: Companies MUST reject a client assertion with any other `aud`, compared character for character, including their token endpoint URL. +- [ ] **MUST**: Companies MUST accept client assertions signed with `ES256` and with `PS384`. + +### Specification: [5.2 The Session header](https://personalagentprotocol.org/docs/1.0/spec#session-header) + +- [ ] **SHOULD**: A Personal Agent that fetches a page of the Company's website with its own HTTP client, rather than a browser, SHOULD send the Session header with it, so the Company can tell which Personal Agent and Session the request is from. + +### Specification: [Delegated keys](https://personalagentprotocol.org/docs/1.0/spec#delegated-keys) + +- [ ] **MUST**: Companies MUST accept delegations signed with `ES256` and with `PS384`. +- [ ] **MUST**: When verifying a Session header (5.3), the Company MUST reject, with `invalid_session`, a Session JWT without a delegation, including one signed directly with a key from `jwks_uri`, and a Session JWT whose delegation fails any of these checks. +- [ ] **MUST NOT**: So a Company MUST NOT expect a User's delegated key to stay the same between requests or Sessions, or treat a new one as a reason to reject a request. + +### Specification: [5.3 Verifying the Session header](https://personalagentprotocol.org/docs/1.0/spec#session-verification) + +- [ ] **SHOULD**: Companies SHOULD verify the Session header on every request that carries it. +- [ ] **MUST**: The Company MUST complete the following checks before relying on Session claims for client or User identity, ownership, continuity, or access to state, including creating or continuing a Session: + - [ ] Fetches the client metadata from `iss` without following redirects, as the CIMD draft (§5) requires, and the public keys from its `jwks_uri` (4.1), following the address checks in section 3. + - [ ] Verifies the JWT's delegation and signature, as Delegated keys (5.2) describes, then `typ` and the claims above: `aud` is its Company's identifier, compared character for character; `htm` and `htu` match the request as RFC 9449 §4.3 describes for DPoP proofs; and `iat` is within an acceptance window it chooses, such as one minute. The JWT never grants account access, whatever else it contains. + - [ ] If the request carries an access token, checks that `ath` matches it, and that the token was issued to the same `client_id` as `iss`. Without an access token, `ath` MUST be absent. + - [ ] Looks up the Session by `client_id`, `sid`, and User ID. An unknown combination starts a signed-out Session with the verified `client_id`, User ID, and optional Agent ID, and a known one continues its Session. It checks ended Sessions at this point too (5.5). +- [ ] **MUST**: Without an access token, `ath` MUST be absent. +- [ ] **MUST NOT**: The Company MUST NOT use unverified Session claims to attribute a request to a Personal Agent, User, or Session, or to look up their state. +- [ ] **MUST**: The Company MUST reject a request without the Session header when handling it depends on Session claims. + +### Specification: [Operator signatures](https://personalagentprotocol.org/docs/1.0/spec#operator-signatures) + +- [ ] **MUST**: Before trusting any Session claim, the Company MUST verify the Session JWT independently (5.3). + +### Specification: [5.6 Sending requests](https://personalagentprotocol.org/docs/1.0/spec#sending-requests) + +- [ ] **MUST**: Companies MUST accept the Session header and access token at their APIs, conversations, and other protocol and extension endpoints without requiring cookies. +- [ ] **MUST NOT**: Personal Agents MUST NOT send tokens or Session JWTs in a URL, and Companies MUST NOT accept them from one. + +### Recommended: [Handling secrets](https://personalagentprotocol.org/docs/1.0/guides#both-secrets) + +These are secrets: + +- Access tokens and refresh tokens. +- Private keys, client assertions, Session JWTs, and DPoP proofs. +- Authorization codes, PKCE code verifiers, device codes, one-time sign-in codes, browser-session codes, and credentials sent in mediated sign-in. + +To handle them: + +- [ ] Keep them out of logs, telemetry, error reports, model context, conversation messages, and URLs. Tokens and Session JWTs MUST NOT be sent in a URL (5.6), and tokens, Session JWTs, private keys, authorization codes, PKCE code verifiers, and device codes MUST NOT go in model context (10.2). +- [ ] Redact the `Authorization`, `Poppy-Session`, `DPoP`, and `Cookie` headers and credential fields before a request reaches a logger or tracer. +- [ ] Send `Cache-Control: no-store` on every response that carries a token or code. + +### Recommended: [Signing and verifying JWTs](https://personalagentprotocol.org/docs/1.0/guides#both-signing) + +Client assertions, delegations, Session JWTs, and DPoP proofs are JWTs. To sign and verify them consistently: + +- [ ] Personal agents: sign Session JWTs with ES256 (MUST, 5.2). Sign client assertions and delegations with ES256, or with PS384 if you sign them blindly (10.7). Companies: accept both in client assertions and delegations (4.1, 5.2). Use RSA keys of 2048 to 4096 bits, and accept any RSA key in that range. +- [ ] Reject `alg: none` and symmetric algorithms such as HS256. +- [ ] Verify client assertions and delegations only with keys from the personal agent's verified `jwks_uri` (4.1), and Session JWTs only with the key their verified delegation names in `cnf.jwk` (5.2). Ignore `jku`, `x5u`, and any other key embedded in a JWT. DPoP proofs for DPoP-bound access tokens are the one other exception: the public key in their `jwk` header is how they work. +- [ ] Check `aud` and `iat`, and `exp` on client assertions and delegations. Session JWTs have no `exp`: accept them only within your `iat` window (5.3). A client assertion has the company's issuer as its `aud`; a Session JWT has the Company's identifier (its issuer, or its HTTPS domain without one), never an endpoint URL (4.1, 5.2). Allow a small clock skew, such as 30 seconds, and reject assertions that claim a long lifetime. +- [ ] Make the `jti` of each client assertion, delegation, Session JWT, and DPoP proof at least 128 random bits, and each Session ID too. +- [ ] Personal agents: set a client assertion's `exp` at most five minutes after its `iat`. +- [ ] Companies: reject a reused client assertion `jti` from the same `client_id` until it expires, as RFC 7523 §3 allows. + +### Recommended: [Operator signatures and bot defenses](https://personalagentprotocol.org/docs/1.0/guides#both-operator-signatures) + +- [ ] Build the request body, any DPoP proof, and Session JWT first, then the operator signature. Cover `poppy-session` and `authorization` when present, as the spec requires. Include method, authority, path, query, and a verified content digest when the verifier relies on those components. +- [ ] Keep operator keys separate from delegated Session keys. Publishing every User's delegated key in an operator directory is not equivalent to verifying a delegation, and exposes a new key mapping. +- [ ] For a centralized agent, signing can happen where requests already pass. For on-device agents, sending requests to an authenticated operator signing service can reveal which Company each User visits. This signature profile does not provide blind signing. Do not send devices a shared operator private key to avoid that service. +- [ ] A verified operator signature establishes control of its key source. It does not establish every client metadata URL on the same origin. Verify the Session JWT's exact `iss` before accepting it as that client, then apply Company policy and account authorization. +- [ ] Test the actual edge and origin together: registration, directory caching, key rotation, accepted signature components, body handling, and forwarded authentication results. Protect the origin from forged forwarding headers. A bot-verification result is not a replay check or account grant. +- [ ] Remove the extra signature where an edge verifies delegated Session JWTs directly. Keep Company acceptance and all remaining Session and OAuth checks. The JWT covers method, URL without query, and access token, not the request body; do not assume removing an operator signature preserves any additional query or body protection it supplied. + +### Recommended: [Rotating keys](https://personalagentprotocol.org/docs/1.0/guides#both-key-rotation) + +- [ ] Give every key in `jwks_uri` a `kid`. +- [ ] Publish a new key in `jwks_uri` before signing with it, early enough for companies' caches to pick it up. +- [ ] Keep an old public key published until every client assertion and delegation signed with it has expired. +- [ ] Personal agents: rotate delegated keys as often as you like. Each Session JWT carries its own delegation, so companies don't depend on a delegated key lasting (5.2). +- [ ] Personal agents: don't rotate DPoP keys. Use each one for one user ID only (4.5), and refresh with the key you got the refresh token with (MUST, 4.4). To move to a new key, have the user sign in again, or use the replacement procedure of an extension the company requires. +- [ ] Companies refetch `jwks_uri` when they see an unknown `kid`. The refetch happens before any signature is checked, so anyone can trigger it by naming a real personal agent and a made-up `kid`. Refetch each `jwks_uri` at most once per interval, such as 30 seconds, and count failed fetches too. Otherwise a stream of bad assertions can flood the personal agent's server. +- [ ] Rotating the keys in `jwks_uri` doesn't affect refresh tokens. They are tied to the `client_id`, and to a DPoP key only if the company binds them to one (4.4). + +### Recommended: [Fetching metadata safely](https://personalagentprotocol.org/docs/1.0/guides#both-fetching) + +Personal agents fetch `poppy.json` files, OAuth and protected resource metadata, and API descriptions. Companies fetch client metadata documents and key sets. Each fetch goes to a URL the other party controls, so: + +- [ ] Set limits: a few redirects at most, a response size such as 100 KB, and a timeout of a few seconds. +- [ ] Validate HTTPS certificates. Personal agents MUST follow discovery redirects only to HTTPS URLs (section 3). +- [ ] Never send cookies, tokens, or other credentials on these fetches. +- [ ] Reject loopback, private, and link-local addresses unless you've configured them on purpose. Check the address you actually connect to, not only the one DNS returned first. +- [ ] Cache according to HTTP caching headers, within bounds you set, such as at least a minute and at most a day. The upper bound means a removed key stops being trusted. + +### Recommended: [Rate limits](https://personalagentprotocol.org/docs/1.0/guides#both-rate-limits) + +- [ ] Companies: limit by `client_id`, by user, and by session, so one busy personal agent or user doesn't crowd out others. Count a request against a `client_id` only after its Session JWT or client assertion's signature checks pass. Otherwise anyone can name a personal agent and use up its limit, so its real users are refused. Limit unverified requests by network instead. +- [ ] Companies: also send the `RateLimit` and `RateLimit-Policy` headers (IETF draft), so personal agents can slow down before they hit a limit. +- [ ] Personal agents: keep track of limits for each company and share them across your tasks and users, rather than letting each task find the limit on its own. +- [ ] Personal agents: prefer long polling or streaming over repeated short polls, and check for changes no more often than the task needs. Checking once a day for a price drop is usually enough. +- [ ] Personal agents: run work that isn't time-sensitive, such as checking order status in the background, outside the company's busy hours, and spread it out instead of starting it all at the same moment. + +### Recommended: [Transport and JSON](https://personalagentprotocol.org/docs/1.0/guides#both-transport) + +- [ ] Use TLS 1.2 or later. Prefer TLS 1.3. +- [ ] Encode JSON as UTF-8 and reject objects with duplicate member names. +- [ ] Write timestamps in RFC 3339 with a time zone offset, such as `2026-10-02T17:15:00-07:00`. +- [ ] Ignore fields you don't recognize, so later versions can add them. + +### Recommended: [Choosing capabilities](https://personalagentprotocol.org/docs/1.0/guides#company-adoption) + +Start with the tasks you want personal agents to accomplish and the interfaces you already have. Publish `poppy.json` with at least one of `apis`, `web`, or `agent` (MUST, 3.1). Then choose the capabilities those tasks need: + +- [ ] Signed-out APIs. You can expose a catalog or other stateless API without an OAuth server. Accept the Session header personal agents send. If the endpoint uses no Session claims, it can serve requests without verifying the header (5.3). +- [ ] Session continuity. Verify Session JWTs when you want to recognize a pseudonymous user, maintain a Session cart, or connect activity across channels. Verification is required before relying on Session identity, ownership, continuity, or state (5.3). This works without OAuth. +- [ ] Account access. Add OAuth when tasks need access to a user's account. Your endpoints can rely on OAuth alone if they use no Session claims. They still validate tokens and enforce scopes and any required DPoP checks. Check your existing authorization server against what Poppy adds to OAuth and client metadata support. Check `protected_resources` in its metadata first (3.2): it's the required field an existing issuer is most likely to be missing, and adding it may need a release from its vendor. +- [ ] Channels and other capabilities. Offer APIs, web browsing, conversations, or a combination. Add browser join to connect website activity to a Session. Advertise excluded tasks, feedback, and extensions where they help users complete the tasks you support. + +### Recommended: [Serving several versions](https://personalagentprotocol.org/docs/1.0/guides#company-versions) + +To add a protocol version (3.4): + +- [ ] Publish the new version's document at a path of your own, such as `/poppy/0.4.json`, on the host that serves `poppy.json`. Static files work: each version is one file. Keep the URL the same for as long as you list the version. +- [ ] Accept both versions at your endpoints, telling them apart by `Poppy-Version`. Where a version needs its own endpoint, such as a browser-session page that changed, give that version's document its own URL. +- [ ] Make it your preferred version: in one deploy, serve it at `/.well-known/poppy.json` and add the older document's URL to `supported_versions`. +- [ ] To retire a version, send `Deprecation` and `Sunset` on its responses for a while, then remove it from `supported_versions`, then stop accepting it. A personal agent with a cached document gets `version_unsupported`, fetches `poppy.json` again, and moves. + +### Recommended: [Verifying personal agents](https://personalagentprotocol.org/docs/1.0/guides#company-agents) + +- [ ] Fetch the `client_id` URL without following redirects. Its `client_id` MUST equal the URL you fetched (4.1). +- [ ] Cache client metadata and key sets, as described in Fetching metadata safely. +- [ ] Keep allowlists or blocklists of `client_id` values, and rate-limit session creation and new `client_id` values (4.1). +- [ ] Check whether your authorization server supports client ID metadata documents. Some do, some support them only for clients an administrator registers by URL, and some don't yet. If yours needs registration, register the personal agents you accept by their `client_id` URL and reject others with `invalid_client`, which 4.1 allows. Your OAuth integration can fetch and check the metadata document. Your resources also fetch it when verifying Session JWTs (5.3). +- [ ] If your authorization server accepts client ID metadata documents, publish `client_id_metadata_document_supported: true` in its metadata, as the CIMD draft §8 defines, so other clients, such as MCP clients, can tell. Personal agents don't need it: a company that offers sign-in already reads their metadata documents (4.1). + +### Recommended: [Verifying the Session header](https://personalagentprotocol.org/docs/1.0/guides#company-session-header) + +Verify Session headers generally (SHOULD, 5.3). Complete all checks before trusting Session claims for identity, ownership, continuity, or state (MUST). Conversations, Session carts, browser join, and approval ownership need that verification. A stateless catalog endpoint can ignore the header. An account endpoint can use OAuth alone if it uses no Session claims or state. It still validates the token, its scopes and audience, and any required DPoP proof. To verify reliably: + +- [ ] Verify the Session header in one place, such as a gateway in front of your APIs, conversation endpoint, and browser-session `/authorize` endpoint, and pass the verified `client_id`, `sid`, user ID, and agent ID to the services behind it. +- [ ] Cache verified delegations until they expire (5.2). Key the cache by a hash of the whole delegation, such as its SHA-256, not by its `jti`, which a forged delegation could copy. Most requests then need one signature check. +- [ ] Behind proxies and load balancers, compare `htu` with the public URL the personal agent used. Build it from your configured public origin, not from the `Host` header your server receives. +- [ ] Use an acceptance window of about one minute for `iat`, plus a small clock skew. +- [ ] Rejecting a reused `jti` is optional, as it is for DPoP proofs, because servers behind one endpoint don't always share state. Without it, a copied Session JWT still works only for the same method and URL, with the same access token, and within the acceptance window. A request that changes something then relies on being idempotent, so a replay doesn't repeat it. Conversation requests already are, through their IDs (8.3). +- [ ] If you keep a replay cache keyed by `jti`, hold entries for the acceptance window and share it across every server. Otherwise a JWT accepted by one server can be replayed at another (5.3). +- [ ] Check `ath` against the access token, and that the token was issued to the JWT's `iss`. Reject an absent header when the request depends on Session claims (MUST, 5.3). Don't use an unverified `iss`, `sub`, or `sid` for attribution, rate limits by identity, cache keys, or state lookup. +- [ ] Return `invalid_session` for a failed check, and keep access token errors in `WWW-Authenticate`, as OAuth does (section 7). +- [ ] Binding access tokens with DPoP is your choice (4.5), and you can choose for each service. If you do, verify the proof as RFC 9449 describes, separately from the Session JWT. For a service that doesn't verify proofs, such as an MCP server built for ordinary MCP clients, have your authorization server issue Bearer tokens for its `resource`. If your authorization server can't issue DPoP-bound tokens, verifying the Session JWT and its `ath` binds the token to the personal agent's key. Endpoints that skip Session verification lose that extra protection. Binding refresh tokens to the same key is your choice too (4.4, Token lifetimes). +- [ ] At an MCP server, accept a token issued for its `resource` only at that server (MUST, section 7). Accept the Session header there too, if you want its calls tied to sessions. Signed-out calls that use no Session state can work without verification. +- [ ] Pages on the host that serves your `poppy.json` can get the Session header too, from personal agents that fetch them without a browser, and never with an access token (5.2). Verify it before using it, for example to recognize the personal agent or to keep the request in its session. Treat the request as signed out, even when the session's browser is signed in. When the check fails, return `invalid_session` as at any endpoint (5.3), so the personal agent can find the mistake. +- [ ] Serve personal agent conversations only from your conversation endpoint (8.2). If your website chat or other channels can open the same conversations, they may not check the Session header, and anyone with a copied token could read them there. + +### Recommended: [Sessions](https://personalagentprotocol.org/docs/1.0/guides#company-sessions) + +When keeping session state: + +- [ ] Behind a load balancer, share session state across the servers that handle it, as with server-side cookie sessions, so requests reach the same state whichever server handles them. +- [ ] Record the user ID and agent ID a session starts with, and reject later Session JWTs for it with different ones (5.3). +- [ ] Session verification needs no state until the session lookup, so a gateway in front of your endpoints can verify the header once and pass the verified claims on. Endpoints that use no Session claims don't need to change (5.3). +- [ ] Your authorization server doesn't see the Session header. Sign-in and refresh are plain OAuth, and a session is signed in on each request that carries an access token (5.4). +- [ ] Remember the `sid`s of sessions you end, and answer them with `session_ended` (5.5). Choose a retention period that fits your session lifetimes. +- [ ] Use separate sessions for separate accounts. If your policy refuses a second account in a session, answer with `session_ended` (5.4). +- [ ] Don't expect a user's delegated key to stay the same (MUST NOT, 5.2). You can reject a delegated key that signs for a second user ID while a delegation for it lasts, which limits a leaked key to one user (10.7). + +### Recommended: [Internal services](https://personalagentprotocol.org/docs/1.0/guides#company-internal) + +- [ ] Don't forward an access token or Session JWT from one of your services to another. +- [ ] Verify them at the edge, then pass the verified `client_id`, session, user ID, account, and scopes to internal services through a gateway or service credentials. +- [ ] Internal credentials used for a request shouldn't allow more than the access token does. + +### Recommended: [Hosting several companies](https://personalagentprotocol.org/docs/1.0/guides#company-hosting) + +- [ ] Publish metadata for each issuer at its own URL, such as `https://auth.platform.example/.well-known/oauth-authorization-server/outfitters` (3.2). Its `issuer` is the full issuer, and its `protected_resources` lists only that company's storefronts and resources, such as `https://outfitters.example`. +- [ ] Publish protected resource metadata on each storefront's domain, with its company's issuer in `authorization_servers` (3.2). +- [ ] Serve each storefront's `poppy.json` on the storefront's own domain. A document redirected to the platform's domain speaks for the platform, not the storefront (3.1). +- [ ] Companies can share a token endpoint, servers, and signing keys. Only the issuer decides which company a token belongs to. +- [ ] Record the issuer with every session and token, and check it on every request. An access token, refresh token, or Session JWT for Outfitters must not work at Books, even when both are served by the same code. +- [ ] Don't use one company's records for another. A user's sessions, user IDs, and accounts at one company are unknown to every other company the platform hosts. + +### Recommended: [Offering personal agents less](https://personalagentprotocol.org/docs/1.0/guides#company-agent-issuer) + +A company can offer personal agents less than its other OAuth clients get without a second issuer: + +- [ ] Limit the scopes it grants by client, as OAuth allows (4.7). It can also leave scopes it doesn't offer personal agents out of `scopes_supported`, as RFC 8414 allows (3.2). When the issuer's metadata can't be tailored, such as a hosted issuer or one shared with other resources, list the scopes personal agents can request in `scopes_supported` of your protected resource metadata instead (4.7). These lists are discovery, not enforcement: agents can request scopes documented by an API or sign-in extension too. +- [ ] Refuse sign-in, or one sign-in type, to a personal agent with `unauthorized_client` from the grant's endpoint, and keep accepting it for signed-out sessions (4.1). `grant_types_supported` lists the grants every client can see, so a refusal by `client_id` is how you keep direct or device sign-in from some personal agents. +- [ ] Turn off sign-in for every personal agent with `auth.disabled`, for example while your issuer serves only other clients, or to keep one identifier across hostname changes before you offer sign-in (3.2). Personal agents don't try to sign in, and still use signed-out sessions. Remove it when you're ready. + +## Interfaces + +### Specification: [6. Web browsing](https://personalagentprotocol.org/docs/1.0/spec#web-browsing) + +- [ ] **MUST NOT**: A Company that sets `web.disabled` MUST NOT list `browser_session_endpoint`, and MUST list `agent` or `apis`. +- [ ] **MUST**: The Company MUST make the code unguessable and short-lived, and each code works once. +- [ ] **MUST**: The Company MUST tie the code to the browser that loaded the page with a cookie set in the same response, so that only that browser can submit it. +- [ ] **MUST NOT**: The cookie MUST NOT be sent with a form submitted from another site, and other hosts on the Company's domain MUST NOT be able to set it. +- [ ] **MUST NOT**: The page MUST NOT be stored by caches, framed by other pages, or kept as a window reference by the page that opened it. +- [ ] **MUST NOT**: Loading the page MUST NOT start, end, or change any Session, or change the browser's other cookies. +- [ ] **MUST**: The Company MUST reject an access token in step 2 that doesn't have the `poppy:browser-sign-in` scope, with `insufficient_scope` as at an API (section 7). +- [ ] **MUST**: A Company that lists `browser_session_endpoint` and offers sign-in MUST support `poppy:browser-sign-in` (4.7), though it MAY grant it to fewer clients or Users, as for any scope. +- [ ] **MUST**: The Company MUST check that: + - [ ] The request has the cookie from step 1, and it matches `code`. + - [ ] The code was authorized in step 2, hasn't expired, and hasn't been submitted before. A code is used by the first request that submits it, whatever the result. +- [ ] **SHOULD NOT**: In a join without an access token, the Company SHOULD NOT end or change that login, because the Personal Agent's browser may have a login it can't easily recreate. +- [ ] **MUST**: MUST be set only in step 3. +- [ ] **MUST**: MUST act for the account and scopes authorized in step 2, if any, and MUST stop acting for the account when the User signs out or disconnects the Personal Agent (5.5). +- [ ] **MUST NOT**: MUST NOT outlive the Session. +- [ ] **MUST**: After a signed-in join, the Company's website MUST either apply the cookie's scopes, as the Company's APIs apply an access token's, or treat `poppy:browser-sign-in` as access to everything the account can do on the website. +- [ ] **MUST**: When `poppy:browser-sign-in` gives the account's full access on the website, the Company MUST describe it that way (4.7), such as "Browse the website, and see and do anything your account can do there," and in Direct and Device Sign-In MUST ask the User to approve it like any other scope. +- [ ] **MUST**: A Company whose website treats `poppy:browser-sign-in` as the account's full access MUST set `web.unscoped` to `true` in `poppy.json`, so the Personal Agent knows what the scope allows before requesting it. +- [ ] **MUST**: A Company that sets `web.unscoped` MUST list `browser_session_endpoint`. +- [ ] **SHOULD**: When the website refuses an action because the Session lacks a scope, it SHOULD show a visible error message that names the missing scopes, so the Personal Agent can request them (5.4). + +### Specification: [7. APIs](https://personalagentprotocol.org/docs/1.0/spec#apis) + +- [ ] **MUST**: Every listed API MUST accept the Session header (5.2) and, when the Company offers account access, its access tokens (4.5), and enforce their scopes. +- [ ] **MUST**: The `resource` in the server's protected resource metadata MUST equal that `url`. +- [ ] **MUST**: The Company MUST reject it elsewhere. +- [ ] **MUST**: It names the Company's issuer, not the Personal Agent: an MCP server that offers account access MUST include the Company's issuer in its `authorization_servers`. + +### Specification: [8.1 Conversation protocols](https://personalagentprotocol.org/docs/1.0/spec#conversation-protocols) + +- [ ] **MUST**: The Company MUST include a `description` in every entry, and MAY say the agent can help with anything. + +### Specification: [8.2 Requests](https://personalagentprotocol.org/docs/1.0/spec#conversation-requests) + +- [ ] **MUST**: The Company MUST reject any other request, as the table shows: +- [ ] **MUST NOT**: Beyond these rules, the side that chooses an ID decides its format, and the other side MUST NOT depend on it. + +### Specification: [8.4 Message fields](https://personalagentprotocol.org/docs/1.0/spec#message-fields) + +- [ ] **MUST**: A message MUST have at least one of `text`, `data`, `context`, or `extensions`. +- [ ] **MUST NOT**: A message from a person at the Company, or written by the User, with `author.type` `human`, MUST NOT include either field. +- [ ] **MUST NOT**: The Company and the Personal Agent MUST NOT depend on either field being present, and treat each only as a hint for interpreting the message. +- [ ] **MUST NOT**: A side MUST NOT send an extension's content unless the other side uses that extension with the same version: the Company checks the request's `Poppy-Extensions` (3.4), and the Personal Agent checks the Company's document for the version it chose (3.1). + +### Specification: [8.5 Reading events](https://personalagentprotocol.org/docs/1.0/spec#reading-events) + +- [ ] **MUST**: Every successful read MUST include `conversation_id`, `events`, `cursor`, `has_more`, and the state fields `working`, `handoff`, `responder`, and `closed` (8.7), with `events` empty when there are none. + +### Specification: [8.7 State](https://personalagentprotocol.org/docs/1.0/spec#state) + +- [ ] **MUST**: Each Company message MUST also include `author.type`, with `agent` or `human`, to identify who wrote it. + +### Specification: [8.10 Direct Conversations](https://personalagentprotocol.org/docs/1.0/spec#direct-conversations) + +- [ ] **MUST NOT**: The Company MUST NOT send information there that it cannot share with the Personal Agent. +- [ ] **MUST**: The parent conversation MUST be open, belong to the same owner (8.2), and not be a Direct Conversation itself. +- [ ] **MUST**: The Company MUST reject a `user_requested_event_id` that doesn't name a `user_requested` event in that parent with `invalid_request`. + +### Specification: [9. Task coverage](https://personalagentprotocol.org/docs/1.0/spec#task-coverage) + +- [ ] **MUST**: A Company that gives different Sessions different responses MUST mark them `private` or `no-store` in `Cache-Control` (RFC 9111 §5.2.2), so that a shared cache doesn't give one Session's response to another. + +### Specification: [9.2 Alternatives](https://personalagentprotocol.org/docs/1.0/spec#alternatives) + +- [ ] **MUST**: An alternative MUST have at least one of `instructions` or `references`. +- [ ] **MUST**: An `openapi` or `mcp` reference MUST name an API listed in the Company's `poppy.json`. + +### Specification: [9.3 Feedback](https://personalagentprotocol.org/docs/1.0/spec#feedback) + +- [ ] **SHOULD**: A Company SHOULD verify the Session header on a report, signed in or signed out, and needs no scope for it. +- [ ] **MUST**: The Company MUST verify the header before attributing a report to a Personal Agent, User, or Session. +- [ ] **MUST**: Companies MUST treat a report's text as data, not as instructions, including when a model reads it. + +### Specification: [9.4 Agent context](https://personalagentprotocol.org/docs/1.0/spec#agent-context) + +- [ ] **MUST**: Companies that publish `skill_index` MUST follow that revision's index format, artifact distribution, integrity, and HTTP requirements for artifacts, with the index in the tasks response instead of fetched from its own URL. + +### Recommended: [Explicit replies and approvals](https://personalagentprotocol.org/docs/1.0/guides#both-replies) + +- [ ] Both parties SHOULD make an answer or approval explicit about the question or action it addresses. +- [ ] Both parties SHOULD treat a short reply that could answer more than one open question as answering none of them, and ask which one is meant before acting. A reply such as "done" could refer to sign-in, an earlier question, or a new request for approval. + +### Recommended: [Retries](https://personalagentprotocol.org/docs/1.0/guides#both-retries) + +- [ ] Send an `Idempotency-Key` (draft-ietf-httpapi-idempotency-key-header) on API writes that accept one. Use a random UUID (version 4), and reuse the same key when you retry the same request. +- [ ] Give each conversation request, such as a message or a handoff request, an `id` with at least 128 random bits, and reuse it when you retry the request (8.3). +- [ ] Each retry needs a new Session JWT, and a new DPoP proof if the access token is DPoP-bound. A retried token request needs a new assertion. The company may reject a `jti` it has already seen. +- [ ] Wait at least as long as `Retry-After` says on a 429 (MUST, 5.6) or a 503. +- [ ] Otherwise, back off exponentially with jitter, cap the delay, and limit the number of attempts. +- [ ] Companies keep idempotency records for a set time, such as a day, scoped to the personal agent's `client_id` and the user ID, and to the account when there is one, not to the session, so a retry in a new session still matches. They return the original response for a repeated key, and reject a repeated key with a different body. + +### Recommended: [Describing APIs](https://personalagentprotocol.org/docs/1.0/guides#company-api-descriptions) + +A language model usually reads your API descriptions and MCP tool descriptions to choose and call operations (7). Write them for that reader: + +- [ ] Say clearly what each operation does and when to use it, in terms of the user's task. +- [ ] Keep them small. The whole description takes room in the model's context, so leave out what personal agents don't need, such as long examples or operations only your own apps call. + +### Recommended: [Browser sessions](https://personalagentprotocol.org/docs/1.0/guides#company-browsing) + +Personal agents work faster and more reliably through a company agent or APIs than through a website, so start there for the tasks users ask for most. Then choose how much of your website personal agents can use, from least to most: + +- [ ] No browsing. Set `web.disabled`, and cover the tasks in your company agent or APIs. Personal agents that follow the protocol won't browse in a browser, but nothing stops one that doesn't (section 6). They can still fetch pages without a browser, with the Session header (5.2). +- [ ] Signed-out browsing. List `web` without a `browser_session_endpoint`. Personal agents browse as ordinary signed-out visitors, and use your company agent and APIs for anything that needs the account. +- [ ] Signed-in browsing with the account's full access. List `browser_session_endpoint`, set `web.unscoped`, and let `poppy:browser-sign-in` allow everything the account can do on the website. This suits a website whose permissions don't match your OAuth scopes. Describe `poppy:browser-sign-in` that way in `auth.scopes`, give it hints that match the website's most consequential action, usually `irreversible` with `personal_data`, and show it on your consent page as its own choice (section 6). +- [ ] Signed-in browsing with your scopes. Your website applies the same scopes as your APIs, so `poppy:browser-sign-in` adds nothing, and you can grant it without asking the user. +- [ ] Put the endpoint on the host personal agents browse when you can. It can be on another host, such as `accounts.example.com`, as long as the session's cookie it sets reaches the pages personal agents browse (section 6). +- [ ] Make each code at least 128 random bits, and expire it within 60 seconds. +- [ ] Set the cookie that ties the code to the browser as `__Host-poppy_join=…; Path=/; Max-Age=60; Secure; HttpOnly; SameSite=Strict`, with `Max-Age` no longer than the code's lifetime. The `__Host-` prefix keeps other hosts on your domain from setting it, and `SameSite=Strict` keeps a form on another site from sending it (RFC 6265bis). +- [ ] Send the page with `Cache-Control: no-store`, `Content-Security-Policy: frame-ancestors 'none'`, and `Cross-Origin-Opener-Policy: same-origin`, so caches don't keep it, other pages can't frame it, and the page that opened it can't keep a reference to its window (section 6). +- [ ] Answer a successful form with `303 See Other`, and a failed one with 400, or 429 when the browser sends too many requests. +- [ ] Don't log the endpoint's responses or request bodies. They contain browser-session codes. +- [ ] Keep a short-lived record for each code: whether it was authorized, for which session and account, and whether it was submitted. A store with a time to live of the code's lifetime works. +- [ ] Use a cookie for the session that's separate from your login cookie, and check it first. After a signed-out join, keep the browser's login cookie. After a signed-in join, clear it, so the browser is signed out when the session's sign-in ends. Section 6 has a table of each case. +- [ ] Make the session's cookie `Secure` and `HttpOnly`, and use the `__Host-` prefix when the endpoint is on the host personal agents browse. When it's on another host, such as `accounts.example.com` for `www.example.com`, the cookie can't use `__Host-` and needs a `Domain` attribute. Set `Domain` to the narrowest domain that covers the hosts personal agents need, because `Domain=example.com` is sent to every subdomain, including one an attacker might take over. The join cookie is only read on the endpoint's host, so it keeps `__Host-` either way. +- [ ] Look up the session on each request, so sign-out and scope changes take effect on the website right away. + +### Recommended: [A conversation endpoint at another provider](https://personalagentprotocol.org/docs/1.0/guides#company-conversation-provider) + +- [ ] List the conversation endpoint in `agent.protocols` in the company's `poppy.json`, with a `description` of what the provider's agent can help with for that company. +- [ ] Use that endpoint URL as the service's resource identifier, including the tenant path so tokens for different companies have different audiences (RFC 8707 §3). Publish its protected resource metadata at the URL RFC 9728 §3.1 defines: +- [ ] Configure the company's issuer to issue access tokens for that resource, with the scopes the conversation service uses. Publishing metadata alone doesn't configure the issuer or establish trust between the providers (RFC 8707 §2.2). +- [ ] The personal agent discovers the resource and requests its access token from the company's issuer with `resource` set to the endpoint URL, at sign-in or refresh (4.5). The issuer can also list the resource in its `protected_resources` (3.2). +- [ ] Arrange for the conversation provider to validate access tokens from that issuer. For JWT access tokens following RFC 9068, use the issuer's metadata and signing keys and check the issuer, audience, expiry, and other validation rules. Another option is authenticated token introspection (RFC 7662). Enforce scopes and verify the Session header separately, including that the token was issued to the same client (5.3). + +### Recommended: [Conversations](https://personalagentprotocol.org/docs/1.0/guides#company-conversations) + +- [ ] Let your company agent do everything customers can do by phone, as fully as you can, so personal agents have no reason to call. +- [ ] Put structured details in `data`, not JSON or other markup in `text` (8.4). +- [ ] To a personal agent that declares the Links extension, send the pages a reply refers to as links, rather than URLs in `text`. +- [ ] To a personal agent that declares the Disclosures extension, send notices users need to see, such as allergen or regulatory warnings, as disclosures, and keep them to those. Personal agents decide which to show, and skip ones that read like promotion. Without the extension, put the notice in `text`. +- [ ] Keep what a message says in `text` and `data`, and use extension content to add to it, so a personal agent that ignores an extension still gets the message (8.4). +- [ ] Write for whoever is on the other side (8.8). With a personal agent, skip greetings and small talk and keep text short. With the user, use plain sentences, a pace they can follow, and details in `text` rather than only in `data`. In a direct conversation, reply as you would to the customer on your own channels. +- [ ] Report `working` as `true` from the moment you accept a request until you've acted on it and finished replying, so a personal agent that reads until `working` is `false` gets the whole reply (8.7). +- [ ] Set `as_of_request` on each company agent message to the latest request the agent saw when it started the turn, and give the agent the `as_of_cursor` of each personal agent message, so it knows which of its messages a reply answers (8.4). Leave `as_of_request` off messages from people. +- [ ] If your help desk can withdraw a request for a person, do so on a handoff cancel, so no one is assigned to a conversation that no longer needs them (8.9). +- [ ] Keep a conversation's events for at least 30 days, so a personal agent that reconnects rarely hits `cursor_expired` (8.5). +- [ ] On a stream with nothing to send, send an SSE comment every 15 to 30 seconds, so proxies don't close it (8.6). +- [ ] When a session signs out, answer requests without an access token on its conversations that used the account with a 401 challenge, including reads of their events, so their account details can't be read signed out (5.5, 8.11). Leave them open, so the user can sign in again and continue, or close them if your policy is to clear everything at sign-out. +- [ ] Before closing an inactive conversation, say so in a message (8.12). +- [ ] When you send an `authorization` event, also ask in a message, so a user in a direct conversation sees the request (8.11). +- [ ] When sign-in can verify the user, send an `authorization` event (8.11) rather than asking for identifying details in messages, such as a date of birth, part of an account number, or a code sent by text. Sign-in proves who the user is, and it keeps codes and personal details out of messages and model context (Handling secrets). +- [ ] Give the people a conversation is handed to (8.9) the same way to ask for sign-in, so they don't fall back to verification questions. + +### Recommended: [Excluded tasks and feedback](https://personalagentprotocol.org/docs/1.0/guides#company-excluded-tasks) + +- [ ] List the tasks you've chosen not to offer to personal agents, such as ones you allow only in your app for security or regulatory reasons (9.1). Personal agents then stop looking for a way to do them, and don't send feedback about them. +- [ ] Write each task the way a customer would ask for it, such as "Send a wire transfer". +- [ ] Give an alternative whenever there is one. Link to the page, or the screen in your app, where the user can do the task (9.2). +- [ ] Serve excluded tasks, skills, and your feedback endpoint from `tasks.endpoint` (section 9). If every Session gets the same response, you can cache it at your edge without verifying the Session header. +- [ ] To try different skills, alternatives, or feedback endpoints with some users, choose each Session's variant after verifying its Session header, and mark the response `private`. Choose by User ID to keep a user in the same variant across Sessions, or by Session ID to vary it from one Session to the next. +- [ ] If different Sessions can get different versions of a skill, give each version its own URL. A personal agent rejects a file whose digest doesn't match the index it got. +- [ ] When a feedback report asks for a task you do offer, answer with an alternative that says how, so the personal agent can finish the task (9.3). +- [ ] Take feedback from personal agents at the `feedback.endpoint` in your tasks response (9.3). If your APIs also serve clients that don't read `poppy.json` and you keep a feedback operation for them, say in its description that personal agents use `feedback.endpoint`. Ideally both feed the same place. + +### Recommended: [Error messages](https://personalagentprotocol.org/docs/1.0/guides#company-errors) + +- [ ] Keep `error_description` and other error text free of account details and other users' data. +- [ ] Return the same error for "doesn't exist" and "belongs to someone else", as `conversation_not_found` does (8.13). + +## Sign-in and accounts + +### Specification: [4.2 Direct Sign-In](https://personalagentprotocol.org/docs/1.0/spec#direct-sign-in) + +- [ ] **MUST**: `redirect_uri` MUST exactly match an entry in the Personal Agent's `redirect_uris` (4.1), except for the port of a loopback redirect URI, as RFC 8252 §7.3 describes. +- [ ] **SHOULD**: 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). + +### Specification: [4.3 Device Sign-In](https://personalagentprotocol.org/docs/1.0/spec#device-sign-in) + +- [ ] **MUST**: Companies that offer Device Sign-In and Personal Agents that use it MUST follow the best practices in RFC 10027 (BCP 247) §2. +- [ ] **MUST NOT**: Opening the link MUST NOT approve the request by itself. +- [ ] **SHOULD**: 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). + +### Specification: [4.7 Scopes and token responses](https://personalagentprotocol.org/docs/1.0/spec#scopes) + +- [ ] **SHOULD**: The Company SHOULD describe each scope it offers Personal Agents, so the Personal Agent can choose the ones a task needs: in the scopes of an OAuth 2.0 security scheme in an OpenAPI description it lists (section 7), or otherwise in `auth.scopes`. +- [ ] **MUST**: A Company MUST include both fields in each entry. +- [ ] **MUST NOT**: The Company MUST NOT grant scopes beyond those requested. + +### Specification: [10.8 Sign-ins someone else started](https://personalagentprotocol.org/docs/1.0/spec#attacker-started-sign-in) + +- [ ] **MUST**: 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). + +### Mediated Sign-In: [1. Introduction](https://personalagentprotocol.org/docs/1.0/extensions/mediated-sign-in#intro) + +- [ ] **SHOULD**: A Company SHOULD offer Mediated Sign-In only until it can add Direct or Device Sign-In, and SHOULD stop offering it once those cover the scopes it grants. + +### Mediated Sign-In: [2. Advertising support](https://personalagentprotocol.org/docs/1.0/extensions/mediated-sign-in#support) + +- [ ] **MUST NOT**: It MUST NOT be `grant_type`, `scope`, `resource`, a client authentication parameter such as `client_id` or `client_assertion`, or a parameter this extension defines, such as `sign_in_id`. +- [ ] **SHOULD**: The Company SHOULD also include them in `scopes_supported`, in its OAuth server metadata or protected resource metadata (spec 3.2). +- [ ] **MUST NOT**: The Company MUST NOT grant scopes beyond those requested and listed here. + +### Recommended: [Token lifetimes and sign-out](https://personalagentprotocol.org/docs/1.0/guides#company-lifetimes) + +- [ ] Give access tokens a lifetime of hours, not days. +- [ ] At sign-out, invalidate the access tokens issued under the revoked refresh token, as RFC 7009 §2.1 describes, or check on each request whether the authorization is still active, so sign-out takes effect right away. If you can do neither, keep access tokens to a few minutes (5.5). +- [ ] Don't stop accepted work because the access token that started it expired. A job can outlast the token. +- [ ] Where work in progress can take consequential actions on the user's account, such as payments or changes that are hard to undo, tie it to the refresh token, so revoking access stops it right away. +- [ ] Give refresh tokens a lifetime that fits the account, such as 90 days, and expire ones that go unused sooner. Keep it long enough that users don't have to sign in again often. +- [ ] Revoke a user's refresh tokens when they reset their password or you suspect the account is compromised. +- [ ] Consider issuing a new refresh token on each refresh and revoking the grant when an old one is used again, as RFC 9700 §4.14.2 describes. If a refresh token is copied, the grant ends as soon as both copies have been used. +- [ ] Where account access has meaningful consequences, bind refresh tokens to the DPoP key they were issued with (4.4), so a copied refresh token is useless without the key. +- [ ] If a personal agent's signing key may have leaked, revoke every refresh token issued to its `client_id` that isn't bound to a DPoP key (4.4). + +### Recommended: [Describing scopes](https://personalagentprotocol.org/docs/1.0/guides#company-scope-descriptions) + +A description gives the personal agent context on what the scope is for and when to request it. A good one answers three questions: + +- [ ] What does it unlock? What the personal agent can see or do with it, in words a user understands. +- [ ] When should an agent request it? The tasks that need it, named the way a user would ask for them, such as tracking an order or starting a return. +- [ ] Can the task be done without it? Some scopes aren't required for any call, and only make the result better. Catalog search might work signed out, and return personalized results with a scope. Checkout might work as a guest, and apply store credit and loyalty discounts when signed in. An insurer might give limited quotes signed out and full quotes signed in, and a brokerage delayed prices signed out and real-time prices signed in. Say what the scope adds and that the task works without it. + +Also: + +- [ ] Be specific enough for a model to match a task to the scopes it needs. "See your orders and returns" works better than "Read access". +- [ ] Say whether the scope only reads, and whether a write scope also allows reading. +- [ ] Say in words which actions can't be undone and what personal data the scope shows. +- [ ] Give each scope its hints in `auth.scope_hints` (4.7). Judge each scope by the most consequential operation that requires it: one operation that can't be undone makes the whole scope `irreversible`. When you're unsure about a scope, leave it out of `auth.scope_hints` rather than guess. +- [ ] Splitting a scope can earn it a better hint. A personal agent may request `orders:read` freely but ask the user first before requesting a scope that can cancel orders. + +### Recommended: [Consent pages](https://personalagentprotocol.org/docs/1.0/guides#company-consent) + +The page where the user approves access, in direct and device sign-in (4.2, 4.3): + +- [ ] Start with a heading that names the personal agent and says it wants to connect to the user's account, such as "Muse wants to connect to your Example account". Show it on your sign-in page too, before the user signs in, since that's where they decide whether to go on. Word it as connecting, not as "Sign in with Muse", which reads as signing in with a Muse account. +- [ ] Let the user sign in with a passkey or another phishing-resistant method, as on your website. Direct and device sign-in happen on your own pages, so passkeys work there. They can't work with mediated sign-in, where the personal agent collects the credentials. A passkey protects against fake sign-in pages, but not against a user approving a sign-in someone else started, so the advice on this page and for device sign-in still applies. +- [ ] Show the personal agent's name and logo, and the domain of its `client_id`. The personal agent chooses its own name, so the domain is what the user can trust. +- [ ] Tell the user to continue only if they just asked that personal agent to connect, such as "Only continue if you asked Muse to do this just now." Anyone can start a sign-in and send the user the link, and nothing in the request says who started it. A user who doesn't use that personal agent, or didn't ask, can then decline. +- [ ] Show the account being connected, the requested scopes in plain language, and how long access lasts. Group related scopes rather than listing their names. +- [ ] Point out scopes that allow changes that can't be undone or that show personal data, the scopes your `auth.scope_hints` mark `irreversible` or with `personal_data`. +- [ ] When `poppy:browser-sign-in` allows everything the account can do on your website, say so in plain language, such as "Use the website as you, with full access to your account", and let the user leave it out while approving the rest (section 6). +- [ ] When your issuer serves several domains, `poppy:browser-sign-in` signs the browser in on each of them that lists a `browser_session_endpoint`. Name those websites when you ask the user to approve it, such as "Use example.com and example.co.uk as you" (3.2). If any of those websites is unscoped, describe the scope as full access and set `web.unscoped` on every domain (section 6). +- [ ] When the user already granted some of the scopes, mark which ones are new, but still list them all (10.8). A personal agent that needs more access requests every scope it needs again (4.7). +- [ ] Show the page in device sign-in, and in direct sign-in when the request has `prompt=consent`, even if the user approved every scope before. Skipping it there lets anyone who forwards a sign-in link get access the person never saw (4.2, 4.3). Without `prompt=consent`, you can skip the page for scopes the user already approved, as your server does for other clients. +- [ ] Protect the page against cross-site request forgery, and against framing by other sites with `Content-Security-Policy: frame-ancestors`. +- [ ] `redirect_uri` MUST exactly match an entry in the personal agent's `redirect_uris` (4.2). +- [ ] Accept PKCE with `S256` only, and reject `plain`. +- [ ] Return `iss` in every redirect, success or error (4.2). Personal agents reject a redirect without it. +- [ ] For extra protection, support Pushed Authorization Requests (RFC 9126), and require them where sign-in grants access with meaningful consequences, such as payments. Personal agents then have to use them (4.2). Give each `request_uri` a lifetime of a minute or two. + +### Recommended: [Device sign-in](https://personalagentprotocol.org/docs/1.0/guides#company-device) + +- [ ] Offer direct sign-in too (SHOULD, 4). Device sign-in is easier to use for phishing. +- [ ] RFC 10027 §6.2.1.5 advises against the device authorization grant for sensitive, high-value, or business-critical resources. A company whose accounts hold them, such as a bank, may offer only direct sign-in. +- [ ] Follow the best practices for cross-device flows in RFC 10027 §2 (MUST, 4.3): assess the risk before offering device sign-in, and choose mitigations from its §6.1, such as short-lived single-use codes, rate limits, limited scopes, and a consent page that says which personal agent is asking and tells the user to decline a code they didn't ask for. +- [ ] Put the verification page on your issuer's host or your domain, or a subdomain of either. Personal agents don't show a link anywhere else (4.3). If one issuer serves several domains, a page on the issuer's host works for all of them. +- [ ] Opening the link MUST NOT approve the request by itself (4.3). The same goes for scanning the QR code. The user signs in and approves on the page. +- [ ] Ask the user to confirm that the code on the page matches the one the personal agent shows. +- [ ] Return `slow_down` to personal agents that poll faster than `interval`, and limit wrong `user_code` entries. +- [ ] Keep `expires_in` short, such as 10 minutes. + +### Recommended: [Mediated sign-in](https://personalagentprotocol.org/docs/1.0/guides#company-mediated) + +If you offer mediated sign-in, protect the credentials you accept (Mediated Sign-In 6): + +- [ ] Rate-limit attempts by account, by `client_id`, and by network address, and cap wrong one-time codes. +- [ ] Require a one-time code when a sign-in looks unusual, including a personal agent's first mediated sign-in after the user disconnected it. +- [ ] Return the same `invalid_grant` error for an unknown account and a wrong password, so responses don't reveal whether an account exists. +- [ ] Never store raw credentials or codes, including in logs, traces, and idempotency records. +- [ ] Tell the user, for example by email, when a personal agent signs in. + +### Recommended: [Account settings](https://personalagentprotocol.org/docs/1.0/guides#company-account-settings) + +- [ ] In account settings, list each connected personal agent with its name, domain, scopes, and when it was last used. +- [ ] Offer a control to disconnect each one. Disconnecting revokes its refresh tokens, and its sessions continue signed out (5.5). Also invalidate the access tokens issued under them, as RFC 7009 §2.1 allows. + +### Recommended: [Enforcing scopes everywhere](https://personalagentprotocol.org/docs/1.0/guides#company-scopes) + +- [ ] Apply the same scope rules on your website, APIs, company agent, and live agents. One shared check that every channel calls is easiest to keep consistent. Until your website can, let `poppy:browser-sign-in` stand for the account's full access there (Browser sessions). +- [ ] Have the company agent's tools check the token's scopes on every call. Don't rely on the model to decide. +- [ ] Give live agents' tools the same checks, so a person can't make a change the token doesn't allow (8.11). +- [ ] Check read and write scopes separately. If a write scope also allows reading, say so in its description. +- [ ] When your website refuses an action for a missing scope, show an error that names the scopes (SHOULD, section 6). + +## Extensions + +### Specification: [3.3 Extensions](https://personalagentprotocol.org/docs/1.0/spec#extensions) + +- [ ] **MUST**: Anyone else MUST start an extension's name with a domain they control, such as `example.com/gift-wrap`. +- [ ] **MUST**: Personal Agents and Companies MUST ignore extensions and versions they don't support and fields they don't recognize, so either side can work with the other under this specification alone. + +### Operations: [2. Advertising support](https://personalagentprotocol.org/docs/1.0/extensions/operations#support) + +- [ ] **MUST NOT**: A Company MUST NOT return operations in response to a request that doesn't declare it. + +### Operations: [3. The operation](https://personalagentprotocol.org/docs/1.0/extensions/operations#operation-object) + +- [ ] **MUST NOT**: It stays the same when the terms change (see "New terms"), and the Company MUST NOT use it for another action. +- [ ] **MUST**: Everything that affects the action, such as what it changes, any amount, date, or recipient, or a condition for cancelling, MUST be in the revision's `terms`, and in `summary` if present. +- [ ] **MUST**: The Company MUST perform only what the approved revision describes, and MUST NOT start the action before it receives an approval for it. +- [ ] **MUST NOT**: It MUST NOT give two different sets of terms the same `revision`, so an approval of one revision never applies to other terms. +- [ ] **MUST**: Whichever revision is approved, the Company MUST perform each operation at most once (7). +- [ ] **SHOULD**: `expires_at` SHOULD leave the User long enough to read the terms and decide, unless the Company can't hold the terms that long, such as a price or a seat that can sell out. + +### Operations: [4. Asking for approval](https://personalagentprotocol.org/docs/1.0/extensions/operations#approval-required) + +- [ ] **SHOULD**: The Company's website SHOULD offer a way to make the original request again, such as a Continue button on the page that's waiting, so the Personal Agent can repeat the action once it's approved (6). +- [ ] **SHOULD**: The Company's website SHOULD answer a page load or form submission with a page that says the action is waiting for approval in the User's personal agent. +- [ ] **SHOULD**: The Company's website SHOULD answer a request from its own scripts that accepts JSON, such as a `fetch`, with a JSON object with `error` set to `approval_required`, like an API's but without the operation. + +### Operations: [6. Sending the approval](https://personalagentprotocol.org/docs/1.0/extensions/operations#sending-approval) + +- [ ] **MUST NOT**: A Company MAY record `approver`, `approved_at`, `input_type`, and `reference`, and MUST NOT reject or decline an approval because an optional member is missing or because it doesn't recognize the `input_type`. +- [ ] **MUST**: Companies MUST ignore members of `Poppy-Approval` they don't recognize, so later versions can add members. +- [ ] **MUST NOT**: The Company MUST NOT accept an approval of a website's operation at an API, MCP server, or conversation, or an approval of another interface's operation at `endpoint`. +- [ ] **MUST**: The Company MUST keep a recorded approval that isn't used up until the approved revision's `expires_at`, and MUST NOT apply it to requests from a Session that can't approve the operation. +- [ ] **MUST**: After the Session header checks in spec 5.3 and the token checks in spec 7, the Company MUST make the following checks before performing the action, and respond as the first one that fails says, whatever order it makes them in internally: + - [ ] The Session can approve the operation (3). If it can't, the Company handles the request as if it had no approval. + - [ ] The operation hasn't been performed already. If it has, or is being performed, the Company responds as section 7 describes. + - [ ] The `revision` is one the Company returned for this operation, it hasn't expired, and the request asks for exactly what it describes. The API request or tool call asks for the same action as the one that returned the operation, in a conversation, the operation is the conversation's, and at `endpoint`, the reference is the operation's. The Company compares what the requests mean, not their bytes, and MAY ignore differences it considers inconsequential, such as the order of JSON members. It MAY treat a revision it has replaced with a later one as failing this check. +- [ ] **MUST NOT**: A Company MUST NOT answer an approval with the revision it names, so a Personal Agent never retries the same approval in a loop. +- [ ] **MUST NOT**: The Company MUST NOT put anything in `reason` that the Session couldn't already see. +- [ ] **MUST NOT**: The Company MUST NOT record a declined approval, so a website never finds it for a later request. + +### Operations: [7. Retries and at most once](https://personalagentprotocol.org/docs/1.0/extensions/operations#at-most-once) + +- [ ] **MUST**: The Company MUST perform each operation at most once, however many times its approval is sent. +- [ ] **MUST**: The Company MUST remember that it performed an operation at least until the approved revision's `expires_at`, and while it is being performed. +- [ ] **MUST NOT**: While an operation is being performed, or the Company doesn't know whether it took effect, for example after a timeout in one of its own systems, the Company MUST NOT respond as if it failed. + +### Browser Control: [2. Browser control and Operations](https://personalagentprotocol.org/docs/1.0/extensions/browser-control#operations) + +- [ ] **SHOULD**: A Company SHOULD use Operations for an action that it can describe as terms to approve. + +### Browser Control: [4. Marking steps](https://personalagentprotocol.org/docs/1.0/extensions/browser-control#marking) + +- [ ] **SHOULD**: The Company SHOULD mark every control that performs the step, or the form it is in, and SHOULD mark them before they can be used. +- [ ] **SHOULD NOT**: The Company SHOULD NOT let filling in a `submission` form perform the step itself. +- [ ] **MUST**: Whatever it marks, the Company's servers MUST check the action's conditions themselves, because marks don't stop anything (8.1). + +### Browser Control: [5. Handing control to the User](https://personalagentprotocol.org/docs/1.0/extensions/browser-control#user-control) + +- [ ] **MUST NOT**: A timeout, a change to the page's marks, or anything the Company sends MUST NOT end it. + +### Browser Control: [6. Who controls the browser](https://personalagentprotocol.org/docs/1.0/extensions/browser-control#controller) + +- [ ] **MUST NOT**: It MUST NOT rely on `"user"` as a guarantee that the User took the step. + +### Recommended: [Operations](https://personalagentprotocol.org/docs/1.0/guides#company-operations) + +When you offer the Operations extension: + +- [ ] Ask for approval for actions with a business effect that the user would want to confirm, such as ones that cost money or can't be undone. Don't ask for routine changes the user already asked for in so many words, such as updating a saved address. +- [ ] Put everything that affects the action in `terms`. Name its keys after the fields of the request or of your API's resources, such as `order_id`, so personal agents can compare them with what they asked for, and make each value clear on its own, such as an amount with its currency. Personal agents show `terms` to users, or describe them in their own words (Operations 3). +- [ ] Send a `summary` when you want users to read your wording. Write it so it stands alone: what will happen, to what, and any cost, date, or condition. Use bold for what matters most, such as the amount, and keep links out of it. Personal agents that show a summary show yours as is (Operations 3). +- [ ] Say in your OpenAPI description which endpoints can return `approval_required` or `approval_declined` (Operations 4). +- [ ] An approval is a user approval, or an agent approval on the user's instruction, and says which in `approver`. Record `approver` and `reference` with the operation, so you can look into an approval with the personal agent's operator later (Operations 8.1). +- [ ] For actions where you want to see the user approve, don't return operations. Handle them on your website or in your app until signed user approvals exist (roadmap). +- [ ] Choose `expires_at` for each kind of action. Give the user at least 15 minutes, and longer for terms that don't change, such as cancelling a subscription at the end of the month. Keep it short when you hold something for the user, such as a seat or a sale price. If you don't store operations, you can't hold a price: an approval that arrives after the price changed gets a new revision (Operations 3). +- [ ] Keep your record of a performed operation until its approved revision expires, and no longer than you need to. A store with a time to live set from `expires_at` works (Operations 7). +- [ ] To avoid storing operations nobody has approved, compute them from the request (Operations 3). Give a request without an approval a new random `operation_id`, such as `exc_5Rt2`, so a user can repeat an action on purpose. When a request with an approval no longer matches, return the new revision with that approval's `operation_id`. In a conversation, keep the `operation_id` when the user asks for different terms. +- [ ] When you compute operations, make the `revision` the expiry as a Unix time and an HMAC-SHA256, with a key kept like your other signing keys, over the `operation_id`, the expiry, the terms in a canonical form such as RFC 8785 whether or not you return `terms`, and who can approve it: the `client_id`, the User ID, and the account when signed in. Include the method, URL, and the parts of the body or tool arguments that affect the action. Leave out the `summary`, so you can reword it. +- [ ] When the request comes back with an approval, compute the terms again from your current data, such as today's price, then the HMAC. Compare it in constant time and check the expiry. If the price or anything else changed, the HMAC doesn't match, and you return a new revision for the current terms. The revision only shows that the terms changed: always use your current price. If you store operations instead, store each revision's terms with such a fingerprint of the request, so you can check that a request with an approval asks for exactly what was approved (Operations 6). +- [ ] When you call another system to perform the action, such as a payment processor or a warehouse, derive its idempotency key from the operation ID. A retry then can't perform the action twice downstream either. +- [ ] If a downstream call times out, ask that system whether the action happened, using your business reference, before trying again. Until you know, answer retries with 503 and `Retry-After` (Operations 7). +- [ ] Keep a record of each approval: the operation, revision, `client_id`, account, and time. It shows what the personal agent stated the user approved (Operations 8.1). +- [ ] To ask for approval on your website, make the reference in `Poppy-Operation` a sealed copy of the operation and the request's fingerprint, such as a JWS or an HMAC over who can approve it as for the `revision`, so you don't store operations nobody approved (Operations 4). +- [ ] Keep recorded approvals in the store you use for performed operations, by the account, or by the personal agent's `client_id` and User ID when signed out, with a time to live set from `expires_at`. One record can go from approved to performing to performed (Operations 6). +- [ ] When the browser repeats the request, check it against each unused approval recorded for that account or user as you would check a request that carries the approval: compute the terms and the HMAC again with the approved revision's `operation_id` and expiry. Mark the approval used when you perform the action, so a later request gets a new operation. +- [ ] On the page that's waiting, tell the user the action needs their approval in their personal agent, and offer a Continue button that makes the original request again. A page that polls your own status endpoint can repeat the request itself once the approval is recorded. Don't use operations on the website for an action you can't repeat, such as one behind a single-use form token. Handle its approval yourself instead. Send `Poppy-Operation` on the response to the request itself, including a script's `fetch`, so it works for buttons as well as forms. +- [ ] Make sure your CDN or web application firewall passes a 403 with `Poppy-Operation` through unchanged. Some replace the body of error responses with their own page or drop headers, and the personal agent then can't find the operation (Operations 4). diff --git a/spec/company-kit-2026-11-13/kit/design.md b/spec/company-kit-2026-11-13/kit/design.md new file mode 100644 index 0000000..11b2fe8 --- /dev/null +++ b/spec/company-kit-2026-11-13/kit/design.md @@ -0,0 +1,178 @@ +# Design + +The design says what the Company will offer, how each part is built on its existing systems, and in +what order. Write it to `plan/design.md` from the template below, then **stop and wait for the +engineer's approval**. Build nothing before that. + +## The decisions + +Scope decisions are the engineer's. For each one, recommend an option with your reasons, drawing on +the survey, and record what the engineer chose. + +**Interfaces** ([3.1](https://personalagentprotocol.org/docs/1.0/spec#fields)). Which of these to +offer. A Company can start with one and add more later. + +- `openapi`: existing APIs, described in OpenAPI 3.0 or 3.1, accepting the Session header and the + Company's access tokens ([section 7](https://personalagentprotocol.org/docs/1.0/spec#apis)). +- `mcp`: an MCP server accepting the Company's access tokens issued for its `url`, as MCP + authorization already requires. It MAY ignore the Session header if it uses no Session claims. + Then its calls belong to no Session, so they don't join the cart, conversations, or website + (section 7). +- `conversations`: the Company Agent, through Poppy conversations + ([section 8](https://personalagentprotocol.org/docs/1.0/spec#conversations)). +- `web`: a browser-session endpoint so the Personal Agent's browser joins the Session + ([section 6](https://personalagentprotocol.org/docs/1.0/spec#web-browsing)). Without it, Personal + Agents browse as ordinary signed-out visitors. A Company offering only `web` without the endpoint + needs no `auth` at all. + +**Sign-in types** ([5.4](https://personalagentprotocol.org/docs/1.0/spec#sign-in)). None (signed-out +Sessions only), or any of Direct, Device, and Mediated Sign-In. Direct Sign-In keeps the User's +password with the Company and suits most Companies. Device Sign-In suits Companies that already +offer it. Mediated Sign-In is an extension that means accepting credentials from Personal Agents, +with the duties in the [extension](https://personalagentprotocol.org/docs/1.0/extensions/mediated-sign-in) and the +[guides](https://personalagentprotocol.org/docs/1.0/guides#company-mediated). It is transitional: the +protocol plans to remove it, on a date set when version 1.0 is published. Choose it only as a bridge +to Direct or Device Sign-In, and record when you plan to add those. + +**Scopes** ([4.7](https://personalagentprotocol.org/docs/1.0/spec#scopes)). Which scopes to offer, +usually the OAuth scopes the Company already has, where each one +is described (an OpenAPI description or `auth.scopes`), and which scopes Mediated Sign-In can grant. +See `patterns/scopes.md`. + +**Which Personal Agents** ([4.1](https://personalagentprotocol.org/docs/1.0/spec#agent-identity)). +Accept any Personal Agent, keep an allowlist or blocklist by `client_id`, or require registration. +Also rate limits on Session creation and on new `client_id` values. + +**Access tokens** ([4.5](https://personalagentprotocol.org/docs/1.0/spec#access-tokens)). Bearer or +DPoP-bound, as for any OAuth client: DPoP is the Company's choice, and Personal Agents should +support it. Which services, if any, accept only tokens issued for them, by publishing RFC 9728 +protected resource metadata. MCP servers that offer account access always do. + +**Lifetimes.** The acceptance window for a Session JWT's `iat`, such as one minute +([5.3](https://personalagentprotocol.org/docs/1.0/spec#session-verification)), and the largest +delegation lifetime you accept, up to 24 hours +([Delegated keys](https://personalagentprotocol.org/docs/1.0/spec#delegated-keys)). The lifetime of +access tokens, refresh tokens, and Sessions, how long to remember ended Sessions, and the sign-out +checks in [5.5](https://personalagentprotocol.org/docs/1.0/spec#ending-sessions). See the +[guides](https://personalagentprotocol.org/docs/1.0/guides#company-lifetimes). + +**Operations.** Which actions, if any, need approval before you perform them +([Operations 1](https://personalagentprotocol.org/docs/1.0/extensions/operations#intro)). Build the +optional `operations` version 3 extension in the extensions milestone. + +**Extensions.** Whether to define any of the Company's own +([3.3](https://personalagentprotocol.org/docs/1.0/spec#extensions)). Usually none. + +The architecture is yours to propose, with the engineer's review. Choose a pattern from +`patterns/` for each component. If none fits, describe your own and say why, and add a **Kit** entry +to `plan/feedback.md`. + +## Template for plan/design.md + +The first block is read by the validator (`check https:// --design plan/design.md`). Keep its exact shape: + +- `domain`: the Company's `organization.domain`. +- `milestones`: in build order, from `foundation`, `interfaces`, `sign-in`, `extensions`. +- `interfaces`: any of `openapi`, `mcp`, `conversations`, `web`. `web` means a + `browser_session_endpoint`. +- `sign_in`: any of `direct`, `device`. Empty for signed-out only, or Mediated Sign-In only. + Mediated Sign-In goes in `extensions` as `mediated-sign-in`. +- `extensions`: extension names, such as `operations` or `example.com/gift-wrap`. Empty when none are needed. + +````markdown +# Poppy design: + +Status: on > + +```json poppy-design +{ + "domain": "example.com", + "milestones": ["foundation", "interfaces", "sign-in"], + "interfaces": ["openapi", "mcp", "conversations", "web"], + "sign_in": ["direct", "device"], + "extensions": [] +} +``` + +## 1. Scope + +| Decision | Recommendation and why | Engineer's decision | +| ----------------------- | ---------------------- | ------------------- | +| Interfaces | | | +| Sign-in types | | | +| Scopes and descriptions | | | +| Scopes per sign-in type | | | +| Which Personal Agents | | | +| Rate limits | | | +| Access tokens (DPoP?) | | | +| Session JWT window | | | +| Access token lifetime | | | +| Refresh token lifetime | | | +| Extensions | | | + + + +## 2. Architecture + +| Component | Pattern (from patterns/) | Why | Existing system it builds on | +| ------------------------------------------------------ | ------------------------ | --- | ---------------------------- | +| poppy.json and protected resource metadata | | | | +| OAuth server and token endpoint | | | | +| Verifying Personal Agents | | | | +| Session header verification | | | | +| Session JWT replay cache (shared, per server, or none) | | | | +| Session records | | | | +| APIs (OpenAPI) | | | | +| MCP | | | | +| Conversations | | | | +| Web browsing | | | | +| Sign-in and consent pages | | | | +| Scope enforcement | | | | +| Account settings | | | | + + + +```mermaid +flowchart LR + PA[Personal Agent] --> WK[poppy.json] + PA --> TE[Token endpoint] + PA --> API[APIs] + TE --> IDP[Existing OAuth server] +``` + + + +## 3. Mapping + +### Scopes + +| Scope | Description | Existing permissions it grants | Mediated Sign-In | +| ----- | ----------- | ------------------------------ | ---------------- | +| | | | | + +### Sessions and tokens + + + +| Record | Fields | Stored in | Maps to existing | +| ------------- | --------------------------------------------------------------------------------------------- | --------- | ---------------- | +| Session | `client_id`, `sid`, and User ID (the key), Agent ID, account it has used, ended or not | | | +| Refresh token | `client_id`, account, scopes, expiry | | | +| Access token | `client_id`, account, scopes, `resource` (if any), DPoP key (if bound), refresh token, expiry | | | + +## 4. Plan + +| Milestone | What it delivers | Validator command | Manual checks | +| ---------- | ---------------- | ----------------------------------------------------------------------------------- | ------------- | +| foundation | | `node /validate/index.ts check https:// --milestone foundation` | | +| interfaces | | `node /validate/index.ts check https:// --milestone interfaces` | | +| sign-in | | `node /validate/index.ts check https:// --milestone sign-in` | | + +Staging domain: . Test identity hosted at: . + +## 5. Open questions and risks + +- +```` + +Keep the design current. When something changes during the build, update it and tell the engineer. diff --git a/spec/company-kit-2026-11-13/kit/feedback.md b/spec/company-kit-2026-11-13/kit/feedback.md new file mode 100644 index 0000000..779d5f8 --- /dev/null +++ b/spec/company-kit-2026-11-13/kit/feedback.md @@ -0,0 +1,71 @@ +# Feedback + +The spec is a draft, and it improves from what implementers run into. Keep a running log in +`plan/feedback.md` from the survey on. The implementation report (`report.md`) is built from it, so +nobody has to remember at the end. + +## When to add an entry + +Add one as soon as it happens, not at the end: + +- The spec is unclear, and you had to choose an interpretation. +- The spec doesn't cover something you needed. +- Two parts of the spec, or the spec and the guides, disagree. +- A rule creates a security or privacy risk, or doesn't prevent one it should. +- Something was much harder to build on existing systems than it needed to be. +- Wording misled you or the engineer. +- You had to ask the engineer something the spec should answer. +- Something in this kit was wrong or confusing: a pattern that didn't fit, a milestone missing a + step, a checklist item that's unclear, or a validator check that seems wrong. + +Don't log ordinary bugs in the Company's code, or decisions the spec rightly leaves to the Company. + +## Labels + +| Label | Use for | +| ------------------ | ------------------------------------------------------------------- | +| **Gap** | Something needed that the spec doesn't cover. | +| **Ambiguous** | Text you could read more than one way. | +| **Contradiction** | Two places that disagree. | +| **Risk** | A privacy or security weakness. | +| **Simplification** | A part that could be simpler without losing what it makes possible. | +| **Wording** | Text that's correct but misleading or hard to follow. | +| **Question** | Something you'd like the authors to answer. | +| **Kit** | A problem with this skill, its checklist, or the validator. | + +## Entry format + +Append entries to `plan/feedback.md` in this form. Start the file with the first heading. + +```markdown +# Poppy feedback + +###