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

Filter by extension

Filter by extension


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

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 — each check quotes the sentence it enforces

The validator called northbound.camp invalid because `scopes_supported` lists scopes, such as `openid`, that `auth.scopes` doesn't describe. 4.7 has said the Company SHOULD describe them since 0.3's text of 3 November; our message was written from the 28 October text, when it was a MUST, and nothing compared it with later pins.

- `scope-undescribed` is a SHOULD, so a warning, and our client no longer refuses a Company over it. When the domain's protected resource metadata lists `scopes_supported`, those are the scopes checked, not the issuer's others ([reading](docs/readings.md#v04-scope-descriptions)).
- `mediated-scope-unsupported` had the same history ("all of them in `scopes_supported`" on 28 October, a SHOULD by 3 November) and is a warning too.
- Each MUST, SHOULD or Rule validator message now quotes its sentence in `requires`, and each such mock check quotes it in its basis. `npm run check:spec` fails when a runtime pin no longer has a quoted sentence, or the sentence lacks the basis's key word (`scripts/check-requirements.mjs`). Writing the quotes moved some bases without changing a severity: `mediated-grant-missing`, `nothing-offered` and `issuer-ambiguous` from MUST to Rule, `not-a-url` and `domain-invalid` from Rule to MUST, `json-duplicate-member` from SHOULD to the Guides, and `jwks-kid-duplicate` now cites RFC 7517 §4.5.
- Mock bases that quoted 0.3 wording now quote 0.4 and 1.0, among them `handoff.body` and `close.body`, which quoted an empty object that 0.4 replaced with a request ID. `version.missing` is a Rule: 3.4's sentence has no key word. `account-token.rotated-reused` rests on RFC 6749 §6, since 4.4 no longer says MUST.
- The mock no longer accepts RS256 client assertions. The 0.4 Guides dropped them ("Companies are no longer told to accept RS256 client assertions"); the mock's own description already said ES256 or PS384.
- `npm run spec:keywords -- <old> <new>` lists the sentences whose key words changed between two snapshots, and the [upgrade procedure](docs/upgrading.md) runs it before a new pin.

**Validation:** `npm run check:spec`, `npm run typecheck`, `npm test`, the interop unit tests and `npm run test:properties`.

**Rollback:** revert the commit. No stored state changes.

## 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.
Expand Down
6 changes: 6 additions & 0 deletions TODO.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,6 +30,12 @@ Keep Node 24 while supported and compatible with dependencies. A new LTS release

## Testing and interop

- [ ] Checks whose behaviour the quote audit of 13 November found broader than their sentence. Each needs its own id, basis and `TAMPERS` row, not only a new quote:
- `message.author`: under 1.0 a Company ignores `id`, `name` and `image` on the Personal Agent's messages, and treats an unknown `author.type` as `agent` (8.8); the mock records the first and refuses the second at both versions.
- `session-jwt.sub-changed`: a known `sid` with another User ID starts a new Session under 0.4 (5.3, step 4), and the Company no longer checks the Agent ID; the mock still refuses. The agent's fault (5.2: "MUST NOT use it for any other Session") stands.
- `authorize.secret-in-url`: 5.6's MUST NOT covers tokens and Session JWTs; an assertion in the URL rests only on the Guides ("Handling secrets").
- `http-non-public-host`: section 3's MUST covers loopback, private and link-local addresses; refusing public IP literals, single-label and special-use names is our fetch policy, reported as that MUST.
- The grid's own `company.*` checks (`interop/runner/checks.ts`) quote nothing; extend `scripts/check-requirements.mjs` to them.
- [ ] Remaining attack coverage: two-Company mix-up (`XM`), a private-host test suffix (`XS`), and the consent-code/browser cases (`YF`, `YC`). [Attack definitions and limits](docs/adversarial-interop.md) own the details; retired Operations 1 scenarios are not current tasks.
- [ ] Evaluate an additional independent peer when it can exercise a missing current-version interface. Historical candidates (openavt, Alpine Retail and typo3) remain in the dated backlog; do not build adapters for incompatible protocols merely to expand the grid. Adversarial use of another project's code retains the consent and disclosure rules in SECURITY.md.

Expand Down
5 changes: 3 additions & 2 deletions docs/conformance-levels.md
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ Profiles no longer filter what a Company reports. Both mocks report every record
A refusal made for safety stays in the behaviour, but its level comes from its basis. It is never promoted to a failure blamed on the other side. RFC 2119 section 6 allows imperatives "to limit behavior which has potential for causing harm". Where the draft gives only a SHOULD or the Guides, the protection is the refusing side's own choice. The other side departed from a recommendation, and a recommendation is not a requirement. So:

- **The mock** keeps refusing on the Guides' hardening, at the warning level:
- the `.alg` allow-lists, ES256 and RS256 (S19);
- the `.alg` allow-lists: ES256 and PS384 for client assertions, ES256 and RS256 for DPoP (S19);
- a client assertion without a `jti`;
- an `iat` in the future;
- `Idempotency-Key` reuse.
Expand All @@ -82,10 +82,11 @@ A refusal made for safety stays in the behaviour, but its level comes from its b

The harm oracle `exchange.performed-twice` and the record-only `secret.one-time-code` are warnings too, because their basis is the Guides.
- **The validator** gives each message a `refuses` flag, separate from its severity: whether our client refuses a Company over it. The report's `refused` says whether our client refuses the documents.
- A basis is only as current as the text it was read from. Each MUST, SHOULD or Rule message quotes its sentence in `requires`, and each such mock check quotes it in its basis; `npm run check:spec` fails when a runtime pin no longer has the sentence with that key word (`scripts/check-requirements.mjs`). `scope-undescribed` and `mediated-scope-unsupported` were written from 0.3's 28 October text as MUSTs, and stayed errors after the text made them SHOULDs on 3 November, until this check found them.
- Our client still refuses everything it refused before, with one exception: an extension `version` written as a number now makes it ignore that extension instead of refusing the Company. It also now refuses a URL with an empty host label, such as `https://.`. The reports no longer call our policy the draft's requirement.
- Warnings our client refuses:
- the Guides' fetch limits: `http-non-public-host`, `http-non-public-address` (added later, for the Node CLI, which checks what a name resolves to), `http-too-many-redirects`, `http-redirect-not-allowed`, `http-too-large`. These now make a report **indeterminate**, because the document was never read.
- `json-duplicate-member` (a SHOULD);
- `json-duplicate-member` (the Guides; RFC 8259's SHOULD);
- HTTPS and no fragment where the draft doesn't ask for them, which is spec-issues N9: `not-https-url-unstated`, `url-has-fragment-unstated`;
- `mediated-fields-empty`.
- Errors our client tolerates, because the draft or an RFC tells a reader to, or because it has a safe fallback:
Expand Down
2 changes: 1 addition & 1 deletion docs/poppy-0.4-upgrade.md
Original file line number Diff line number Diff line change
Expand Up @@ -124,7 +124,7 @@ The 0.4 changelog has 44 entries. [spec/requirements-0.4.json](../spec/requireme
| Operations: declining an approval | Done | [code](../src/poppy/declines.ts), [evidence](../test/poppy-0.4.test.ts) | Under Operations 3 a decline of the approval we sent (its operation_id and revision) at an API (403 approval_declined), an MCP tool (an error result's structuredContent) or in a later Company message (extensions.operations.declined) settles the approval as refused, never resent; the card shows the reason and alternative as the Company's words and the model is told not to retry. A decline in a message clears the unknown-outcome hold. After a decline, and after the Company answers an agent approval with a new revision, only the User approves that operation again. A website's operation is declined at endpoint, as at an API (W3). Mock: declineApprovals and reviseOnFirstApproval; TAMPERS rows approval.declined-resent, approval.agent-after-decline and approval.agent-after-revision. Kit: approval-declined.schema.json. |
| `auth.disabled` without other clients | Company obligation | [code](../test/mock-company/auth.ts), [evidence](../docs/poppy-0.4-upgrade.md) | K1: the mock answers refresh with invalid_grant and revocation with success. No agent change: it already refuses sign-in with auth.disabled. |
| Client assertions when no tokens exist | Company obligation | [code](../test/mock-company/auth.ts), [evidence](../docs/poppy-0.4-upgrade.md) | K1: the mock may skip assertion checks while it has issued no refresh token. |
| Scopes in the protected resource metadata | Done | [code](../src/poppy/discovery.ts), [evidence](../test/poppy-0.4.test.ts) | Discovery uses the union of the issuer's scopes_supported and the domain's protected resource metadata's. The 0.4 validator profile counts either list for scopes-supported-missing, mediated-scope-unsupported and browser-sign-in-unsupported, as the kit's discovery check now does. Mock: resourceScopes. |
| Scopes in the protected resource metadata | Done | [code](../src/poppy/discovery.ts), [evidence](../test/poppy-0.4.test.ts) | Discovery uses the union of the issuer's scopes_supported and the domain's protected resource metadata's. The 0.4 validator profile counts either list for scopes-supported-missing, mediated-scope-unsupported and browser-sign-in-unsupported, as the kit's discovery check now does. scope-undescribed, a SHOULD (4.7), checks the domain's list when it has one, else the issuer's (readings: v04-scope-descriptions). Mock: resourceScopes. |
| `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. |
Expand Down
1 change: 1 addition & 0 deletions docs/readings.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,7 @@ Readings we take to implement [the published 0.4 text, retrieved 11 November](..
| <a id="v04-terms-minor-units"></a>The units of an amount in `terms` (Operations 3, 5) | An integer amount in a currency with minor units is read in them, so `1200` USD is shown as 12.00, when the summary writes that reading and never the integer as written. Otherwise it is shown as written, and a cost the summary doesn't name is pointed out as before. A number under a `total` key beside a `currency` is the card's total too | Writes `{ amount, currency }` with decimal strings, as the text's examples do | **Local policy**: the Company "defines its keys" of `terms`, and the text says nothing about units; its examples write decimal strings (`"70.00"`). The summary decides because it "MUST" name any amount the terms do. Print with Poppy writes integer cents |
| <a id="v04-cookie-domain"></a>A browser-session endpoint on another host (6) | The fetch browser keeps a cookie's `Domain` only when it is the Company's `organization.domain` or a subdomain of it; any other `Domain` leaves the cookie host-only, as before | Can't move its endpoint yet | **Local policy**: with no public suffix list, the Company's own domain is the widest scope a cookie may claim, which covers the text's `accounts.example.com` and `www.example.com` |
| <a id="v04-resource-scopes"></a>`scopes_supported` in the protected resource metadata (3.2, 4.7) | The scopes in either list, the issuer's or the domain's protected resource metadata's | Can list them in its protected resource metadata (`resourceScopes`) | As the text |
| <a id="v04-scope-descriptions"></a>Which scopes need a description (4.7: "each scope it offers Personal Agents") | n/a | n/a | In the validator, a warning (`scope-undescribed`, SHOULD) for each undescribed scope the domain's protected resource metadata lists, or, when it lists none, the issuer's. The issuer's own list may hold scopes for its other resources and clients, such as OpenID Connect's `openid` and `profile` (3.2), which the text lets the Company leave undescribed. The Personal Agent may still request a scope only the issuer lists (4.7), and then has no description to show for it |
| <a id="v04-browser-control"></a>Browser Control's browser (Browser Control 3, 5, 6; [decision 47](decisions.md#47-a-browser-for-the-user-alone-the-agent-keeps-the-fetch-browser)) | The fetch browser stays the agent's browser and leaves every marked step undone. "Hands control to the User" is a Browser Run browser started for the same Session when the User takes control: it gets the fetch browser's cookies, so its requests belong to the Session's join (3: "A browser's requests declare the extensions that step 2 of its browser join declared"), and nothing comes back from it. Declared only where the Company lists the extension beside browser join and the deployment turns `BROWSER_CONTROL` on (off as shipped, decision 48); elsewhere marked steps are still left undone and the User is told to take them on the website | Lists it beside browser join (`browserControl`) and marks a return form `submission`, a field `interaction` and a link with another value | **Reading**: the text has the agent's own browser handed over, not a second one with its cookies; we read the Session's joined browser as what is handed over |
| <a id="v04-controller"></a>`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 |
| <a id="v04-marked-steps"></a>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 |
Expand Down
Loading