From ebeb0695c82a4705199ca6a27d38f4912982333b Mon Sep 17 00:00:00 2001 From: Ade Oshineye Date: Fri, 13 Nov 2026 17:48:55 +0000 Subject: [PATCH 1/2] Quote the pinned sentence behind each check scope-undescribed was written as a MUST from 0.3's 28 October text and stayed one after 4.7 became a SHOULD on 3 November, so the validator called northbound.camp invalid and our client refused it. Nothing compared a message's basis with later pins. Each MUST, SHOULD or Rule validator message now quotes its sentence in `requires`, and each such mock check quotes it in its basis. check-requirements.mjs, run by check:spec, fails when a runtime pin lacks the quote or the quote lacks its basis's key word. Writing the quotes found mediated-scope-unsupported (also a SHOULD since 3 November), stale 0.3 quotes in the mock, and RS256 client assertions the 0.4 Guides dropped. scope-undescribed checks the domain's own scopes_supported when its protected resource metadata lists one (a reading). spec:keywords reports key-word changes between snapshots for the upgrade procedure. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 15 +++ TODO.md | 6 + docs/conformance-levels.md | 5 +- docs/poppy-0.4-upgrade.md | 2 +- docs/readings.md | 1 + docs/upgrading.md | 4 +- interop/runner/checks.ts | 2 +- interop/test/attribution.test.ts | 2 +- package.json | 1 + scripts/check-requirements.mjs | 141 +++++++++++++++++++++++ scripts/check-requirements.test.mjs | 38 +++++++ scripts/check-spec.mjs | 10 +- scripts/keyword-changes.mjs | 84 ++++++++++++++ spec/requirements-0.4.json | 2 +- src/validator/messages.ts | 118 +++++++++++++++---- src/validator/profiles/draft-0.4.ts | 24 ++-- src/validator/validate.ts | 2 +- test/mock-company.test.ts | 3 +- test/mock-company/core.ts | 4 +- test/mock-company/violations.ts | 171 ++++++++++++++-------------- test/properties/jwt.test.ts | 6 +- test/validator.test.ts | 23 +++- 22 files changed, 532 insertions(+), 132 deletions(-) create mode 100644 scripts/check-requirements.mjs create mode 100644 scripts/check-requirements.test.mjs create mode 100644 scripts/keyword-changes.mjs diff --git a/CHANGELOG.md b/CHANGELOG.md index b4da26b4..bed437e0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 -- ` 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. diff --git a/TODO.md b/TODO.md index da919a1c..86dec8ef 100644 --- a/TODO.md +++ b/TODO.md @@ -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. diff --git a/docs/conformance-levels.md b/docs/conformance-levels.md index ae02e0a0..01cd4f7c 100644 --- a/docs/conformance-levels.md +++ b/docs/conformance-levels.md @@ -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. @@ -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: diff --git a/docs/poppy-0.4-upgrade.md b/docs/poppy-0.4-upgrade.md index 92f38e8e..76218fd1 100644 --- a/docs/poppy-0.4-upgrade.md +++ b/docs/poppy-0.4-upgrade.md @@ -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. | diff --git a/docs/readings.md b/docs/readings.md index 1e0b3ec0..e6dd96ce 100644 --- a/docs/readings.md +++ b/docs/readings.md @@ -153,6 +153,7 @@ Readings we take to implement [the published 0.4 text, retrieved 11 November](.. | 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 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` | | `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 | +| 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 | | 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 | | `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 | diff --git a/docs/upgrading.md b/docs/upgrading.md index 8669b2d4..a4a5a8d0 100644 --- a/docs/upgrading.md +++ b/docs/upgrading.md @@ -12,7 +12,7 @@ PDA speaks 0.4 and the 1.0 draft ([decision 51](decisions.md#51-10-beside-04)); - **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. +`npm run check:spec` verifies every pin offline, retired ones included, that the runtime pins are exactly the versions in `src/poppy/protocol-version.ts`, and that every MUST, SHOULD, Rule or Guides check in the validator and the mock quotes a sentence each runtime pin still has, with that key word (`scripts/check-requirements.mjs`). `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. 0.1 and 0.2 were dropped on 28 October ([decision 37](decisions.md#37-03-alone-what-dropping-01-and-02-overturns-and-settles)); their snapshots stay in `spec/` as records. @@ -22,7 +22,7 @@ PDA speaks 0.4 and the 1.0 draft ([decision 51](decisions.md#51-10-beside-04)); 1. Run `npm run check:spec`. Then `npm run spec:drift` compares upstream without modifying anything. Drift in a frozen version means upstream changed a published text: review it as a new finding rather than re-pinning. Review the official changelog and specification, guides, Operations and schema diffs. Never fetch rules dynamically at runtime. 2. For the current site-snapshot format, run `node scripts/spec-snapshot.mjs --save` to save a new dated copy without activating it. It names the copy by the version the specification page states, as a draft ("This is draft version 0.4") or published ("This is version 0.4"). Preserve previous snapshots. Review the text and hashes. Download the kit from the protocol site into its own dated `spec/company-kit-*` directory with its manifest, and check it with `node scripts/check-company-kit.mjs --protocol --verify-pin`. Then update the version's pin together with its requirement delta, and the runtime constants only when that version's pin is `runtime`. `npm run spec:import -- --help` can separately archive files from a full upstream commit; its Git-archive manifest is not an active site-snapshot manifest and cannot be selected by the current checker. Supporting that format needs a separately reviewed checker change before activation. -3. Update the version's JSON requirement ledger (`spec/requirements-.json`), then run `npm run spec:docs` to regenerate its table in `docs/poppy--upgrade.md`. Each changed rule names its version, basis, implementation, evidence and remaining limitations. Revisit the readings in [readings.md](readings.md): an ambiguity the new text settles is no longer a reading. +3. Run `npm run spec:keywords -- `: it lists each sentence whose BCP 14 key words changed, such as a MUST that became a SHOULD, including changes the changelog doesn't name because an entry was edited in place. For each one, check the validator messages and mock checks that rest on it. With the new pin in `spec/upstream.json`, `npm run check:spec` then fails for every check whose quoted sentence (`requires` in `src/validator/messages.ts`, the quote in a basis in `test/mock-company/violations.ts`) is no longer in a runtime pin. Change the check's basis, severity and behaviour with its quote; never only the quote. Then update the version's JSON requirement ledger (`spec/requirements-.json`), and run `npm run spec:docs` to regenerate its table in `docs/poppy--upgrade.md`. Each changed rule names its version, basis, implementation, evidence and remaining limitations. Revisit the readings in [readings.md](readings.md): an ambiguity the new text settles is no longer a reading. 4. Run the version's kit against the mock: `node scripts/check-company-kit.mjs --protocol --output `, and compare its results with the reviewed findings. Reuse unchanged client machinery and checks. Each version-dependent rule asks which version its Session uses. Never let an unknown 0.x version fall back to an older profile, and never speak a version the Company doesn't list. Check versionless client metadata with an explicit protocol context. 5. Keep old peer pins and add new ones as separate registry entries. Run the grid with every peer that speaks the version, and any independent checks that do. Preserve unsupported outcomes, trace evidence and version-specific failure attribution. 6. Add an Unreleased changelog entry: operator-visible effects, breaking changes, migration and rollback steps, exact protocol revision, upstream changelog link, and validation actually completed. Don't invent historical release numbers. diff --git a/interop/runner/checks.ts b/interop/runner/checks.ts index e828010e..0b105b0e 100644 --- a/interop/runner/checks.ts +++ b/interop/runner/checks.ts @@ -27,7 +27,7 @@ export type CheckSpec = { export const TRACE_CHECKS = { "client-assertion.typ": { side: "agent", basis: "Reading", mock: true, what: "Client assertion header typ isn't \"JWT\" (S2)" }, "client-assertion.kid": { side: "agent", basis: "Reading", mock: true, what: "Client assertion has no kid (S2)" }, - "client-assertion.alg": { side: "agent", basis: "Guides", mock: true, what: "Client assertion alg isn't ES256 or RS256" }, + "client-assertion.alg": { side: "agent", basis: "Guides", mock: true, what: "Client assertion alg isn't ES256 or PS384" }, "client-assertion.iat-exp-missing": { side: "agent", basis: "MUST", mock: true, what: "Client assertion without iat or exp" }, "client-assertion.lifetime": { side: "agent", basis: "Reading", mock: true, what: "Client assertion lifetime over 60 seconds (S2; the detail says if over 300)" }, "client-assertion.jti-missing": { side: "agent", basis: "MUST", mock: true, what: "Client assertion without a jti" }, diff --git a/interop/test/attribution.test.ts b/interop/test/attribution.test.ts index 9488cf78..d11b21e8 100644 --- a/interop/test/attribution.test.ts +++ b/interop/test/attribution.test.ts @@ -146,7 +146,7 @@ describe("attribution", () => { }); it("rule warning: a SHOULD or Guides refusal on one side blames that side as a warning, not a violation", () => { - // lenient-company refuses an ES384 client assertion (Guides: support ES256 and RS256). + // lenient-company refuses an ES384 client assertion (Guides: ES256, or PS384 when signing blindly). const alg = companyRecorded({ id: "session-assertion.alg", basis: "Guides", detail: "alg ES384" }, "lenient-company", false); const target = cell("a", "lenient-company", "fail", [alg], "C"); expect(attribute(target, [target], none)).toEqual({ blame: "agent", rule: "warning", detail: "session-assertion.alg: a SHOULD or the Guides, not a requirement" }); diff --git a/package.json b/package.json index db390e5d..7e637dda 100644 --- a/package.json +++ b/package.json @@ -32,6 +32,7 @@ "spec:drift": "node --use-env-proxy scripts/check-spec.mjs --drift", "spec:import": "node scripts/spec-import.mjs", "spec:docs": "node scripts/spec-ledger.mjs --write", + "spec:keywords": "node scripts/keyword-changes.mjs", "check:live": "node scripts/check-live.mjs" }, "dependencies": { diff --git a/scripts/check-requirements.mjs b/scripts/check-requirements.mjs new file mode 100644 index 00000000..34566281 --- /dev/null +++ b/scripts/check-requirements.mjs @@ -0,0 +1,141 @@ +#!/usr/bin/env node +/** + * Ties each normative check to the pinned sentence it enforces, so a change + * upstream fails a check instead of leaving a rule at its old strength. + * + * - A validator message (src/validator/messages.ts) whose basis is MUST, + * SHOULD or Rule quotes its sentence in `requires`. + * - A mock violation (test/mock-company/violations.ts) with that basis, or + * MUST NOT, SHOULD NOT or Guides, quotes it in its basis string. + * + * Each quote must appear in every runtime pin (one marked 1.0 only in the 1.0 + * pin), within one paragraph, after removing Markdown links, emphasis and + * code marks; `…` separates parts that appear in that order. The quote must + * carry its basis's key word: MUST (or a required field) for a MUST, SHOULD + * for a SHOULD, and none of MUST or SHOULD for a Rule or the Guides. Quotes + * of another standard (an RFC basis, or a location naming MCP or an RFC) are + * not checked, nor is a validator message whose ref is an RFC. A key word that changes upstream changes the sentence, so the + * quote stops matching and the basis has to be reviewed. A quote that appears in + * no new pin is the first sign: docs/upgrading.md says what to do. + * + * `check-spec.mjs` runs this. Run it alone to list every problem, or with + * `--quote [version]` to test one quote. + */ +import { readFileSync, readdirSync } from "node:fs"; +import path from "node:path"; +import { pathToFileURL } from "node:url"; + +const root = path.resolve(import.meta.dirname, ".."); + +/** Text as quotes are written: no link targets, emphasis, code marks or curly quotes, one space between words. */ +export const normalize = (text) => + text + .replace(/\[([^\]]*)\]\([^)]*\)/g, "$1") + .replace(/[*_`]/g, "") + .replace(/[“”]/g, '"') + .replace(/[‘’]/g, "'") + .replace(/\s+/g, " ") + .trim(); + +/** A runtime pin's paragraphs, from every page. */ +export function paragraphs(snapshot) { + const dir = path.join(root, snapshot, "pages"); + return readdirSync(dir) + .filter((file) => file.endsWith(".md")) + .flatMap((file) => readFileSync(path.join(dir, file), "utf8").split(/\n\s*\n/)) + .map(normalize); +} + +const KEY_WORDS = { + // A required member: the key word, "Required." in a list, or Yes in a table's Req. column. + MUST: /\b(MUST|REQUIRED|SHALL|Required)\b|\b(is|are) required\b|\| Yes \|/, + SHOULD: /\b(SHOULD|RECOMMENDED)\b/ +}; +const STRONGER = /\b(MUST|SHOULD|REQUIRED|RECOMMENDED|SHALL)\b/; + +/** What's wrong with a quote for `basis` ("MUST", "MUST NOT", "SHOULD", "Rule", "Guides"), or nothing. */ +export function quoteProblem(basis, quote, pins) { + const parts = normalize(quote).split(/\s*(?:…|\.\.\.)\s*/).filter(Boolean); + for (const pin of pins) { + const found = pin.paragraphs.some((paragraph) => { + let from = 0; + return parts.every((part) => { + const at = paragraph.indexOf(part, from); + from = at + part.length; + return at >= 0; + }); + }); + if (!found) return `not in the ${pin.version} text`; + } + const kind = basis.split(" ")[0]; + const text = parts.join(" "); + if (KEY_WORDS[kind] && !KEY_WORDS[kind].test(text)) return `a ${basis} basis, but the quote has no ${kind}`; + if ((kind === "Rule" || kind === "Guides") && STRONGER.test(text)) return `a ${basis} basis, but the quote has ${STRONGER.exec(text)[0]}`; + return undefined; +} + +const NEEDS_QUOTE = new Set(["MUST", "MUST NOT", "SHOULD", "SHOULD NOT", "Rule", "Guides"]); + +/** The runtime pins, each with its paragraphs. */ +export function runtimePins() { + const { pins } = JSON.parse(readFileSync(path.join(root, "spec/upstream.json"), "utf8")); + return pins.filter((pin) => pin.runtime).map((pin) => ({ version: pin.protocolVersion, paragraphs: paragraphs(pin.snapshot) })); +} + +/** Every problem with the catalogs' quotes, as "where: what". */ +export async function requirementProblems(pins = runtimePins()) { + const problems = []; + const only = (version) => pins.filter((pin) => pin.version === version); + + const { MESSAGES } = await import(pathToFileURL(path.join(root, "src/validator/messages.ts")).href); + for (const [id, message] of Object.entries(MESSAGES)) { + // A SHOULD of an RFC the draft builds on is quoted by its ref, not here. + if (message.note || !NEEDS_QUOTE.has(message.basis) || message.ref.url.startsWith("https://www.rfc-editor.org/")) continue; + const where = `src/validator/messages.ts ${id}`; + if (!message.requires) { + problems.push(`${where}: a ${message.basis} message with no requires quote`); + continue; + } + const applies = message.ref.url.includes("/docs/1.0/") ? only("1.0") : pins; + const problem = quoteProblem(message.basis, message.requires, applies); + if (problem) problems.push(`${where}: ${problem}: "${message.requires}"`); + } + + const { VIOLATIONS } = await import(pathToFileURL(path.join(root, "test/mock-company/violations.ts")).href); + for (const [id, basis] of Object.entries(VIOLATIONS)) { + const match = /^(MUST NOT|MUST|SHOULD NOT|SHOULD|RFC|Rule|Guides|Reading|MAY) \(([^:)]*)/.exec(basis); + const where = `test/mock-company/violations.ts ${id}`; + if (!match) { + problems.push(`${where}: no basis`); + continue; + } + const [, kind, location] = match; + if (!NEEDS_QUOTE.has(kind) || /^(MCP|RFC)\b/.test(location)) continue; + const quotes = [...basis.matchAll(/"([^"]+)"/g)].map((quote) => quote[1]); + if (quotes.length === 0) { + problems.push(`${where}: a ${kind} basis with no quote`); + continue; + } + const applies = /^1\.0\b/.test(location) ? only("1.0") : pins; + const found = quotes.map((quote) => quoteProblem(kind, quote, applies)); + const missing = found.findIndex((problem) => problem?.startsWith("not in")); + if (missing >= 0) problems.push(`${where}: ${found[missing]}: "${quotes[missing]}"`); + // One quote carries the key word; the others may say where or when. + else if (found.every(Boolean)) problems.push(`${where}: ${found[0]}`); + } + return problems; +} + +if (import.meta.url === pathToFileURL(process.argv[1]).href) { + const at = process.argv.indexOf("--quote"); + if (at >= 0) { + const [basis, quote, version] = process.argv.slice(at + 1); + const pins = runtimePins().filter((pin) => !version || pin.version === version); + console.log(quoteProblem(basis, quote, pins) ?? `ok in ${pins.map((pin) => pin.version).join(" and ")}`); + } else { + const problems = await requirementProblems(); + for (const problem of problems) console.log(problem); + console.log(`${problems.length} problems`); + process.exitCode = problems.length ? 1 : 0; + } +} diff --git a/scripts/check-requirements.test.mjs b/scripts/check-requirements.test.mjs new file mode 100644 index 00000000..72e825c3 --- /dev/null +++ b/scripts/check-requirements.test.mjs @@ -0,0 +1,38 @@ +import { test } from "node:test"; +import assert from "node:assert/strict"; +import { normalize, quoteProblem } from "./check-requirements.mjs"; + +const pin = (version, ...paragraphs) => ({ version, paragraphs: paragraphs.map(normalize) }); +// 0.3's 4.7 before and after its text of 3 November. +const MUST_TEXT = "The Company MUST describe each scope in `scopes_supported`, so the Personal Agent can choose the ones a task needs."; +const SHOULD_TEXT = "The Company SHOULD describe each scope it offers Personal Agents, so the Personal Agent can choose the ones a task needs."; + +test("a MUST quoted from an older text fails once the pin says SHOULD", () => { + const quote = "The Company MUST describe each scope in scopes_supported"; + assert.equal(quoteProblem("MUST", quote, [pin("0.3", MUST_TEXT)]), undefined); + assert.equal(quoteProblem("MUST", quote, [pin("0.4", SHOULD_TEXT)]), "not in the 0.4 text"); +}); + +test("the quote carries its basis's key word", () => { + const quote = "The Company SHOULD describe each scope it offers Personal Agents"; + assert.match(quoteProblem("MUST", quote, [pin("0.4", SHOULD_TEXT)]), /has no MUST/); + assert.equal(quoteProblem("SHOULD", quote, [pin("0.4", SHOULD_TEXT)]), undefined); + assert.match(quoteProblem("Rule", quote, [pin("0.4", SHOULD_TEXT)]), /has SHOULD/); +}); + +test("every runtime pin must have the sentence", () => { + const quote = "The Company SHOULD describe each scope it offers Personal Agents"; + assert.equal(quoteProblem("SHOULD", quote, [pin("0.4", SHOULD_TEXT), pin("1.0", MUST_TEXT)]), "not in the 1.0 text"); +}); + +test("links, code marks and … skips are normalized; parts stay in order within a paragraph", () => { + const text = "On every request with the Session header ([5.2](/docs/0.4/spec#session-header)), the Personal Agent sends the protocol version it implements, compatible with the chosen one, in `Poppy-Version`."; + assert.equal(quoteProblem("Rule", "On every request with the Session header (5.2), the Personal Agent sends … in Poppy-Version", [pin("0.4", text)]), undefined); + assert.equal(quoteProblem("Rule", "in Poppy-Version … the Personal Agent sends", [pin("0.4", text)]), "not in the 0.4 text"); + assert.equal(quoteProblem("Rule", "the Personal Agent sends … in Poppy-Version", [pin("0.4", "the Personal Agent sends", "in Poppy-Version")]), "not in the 0.4 text"); +}); + +test("a required member counts as a MUST", () => { + assert.equal(quoteProblem("MUST", "| protocol_version | Yes |", [pin("0.4", "| protocol_version | Yes | The protocol version |")]), undefined); + assert.equal(quoteProblem("MUST", "resource: Required.", [pin("0.4", "- `resource`: Required.")]), undefined); +}); diff --git a/scripts/check-spec.mjs b/scripts/check-spec.mjs index 38ff0db8..26c814b7 100644 --- a/scripts/check-spec.mjs +++ b/scripts/check-spec.mjs @@ -11,12 +11,15 @@ * and they must agree with src/poppy/protocol-version.ts. A `retired` pin is * a version the agent spoke and no longer does: its text, kit and ledger are * kept and checked as history, and its ledger links files at `codeAt`, the - * commit they were last current in. + * commit they were last current in. Every normative validator message and + * mock check quotes the runtime pins' sentence it enforces + * (check-requirements.mjs). */ import { readFileSync } from "node:fs"; import { createHash } from "node:crypto"; import path from "node:path"; import { LEDGER_START, LEDGER_END, ledgerSection } from "./spec-ledger.mjs"; +import { requirementProblems } from "./check-requirements.mjs"; import { DRAFT_REVISIONS, PROTOCOL_COMMIT, PROTOCOL_REVISIONS, PROTOCOL_VERSIONS } from "../src/poppy/protocol-version.ts"; const root = path.resolve(import.meta.dirname, ".."); @@ -95,6 +98,11 @@ for (const pin of pins) { console.log(`Verified ${ledger.changes.length} changelog dispositions and ${manifest.pages.length} pinned pages (${pin.protocolVersion} ${pin.status}${pin.retired ? ", retired" : ""}, retrieved ${pin.revision}).`); } +// Each normative check quotes the runtime pins' sentence it enforces, with its key word (check-requirements.mjs). +const problems = await requirementProblems(); +if (problems.length) throw new Error(`Checks whose quoted requirement isn't in the pinned text:\n${problems.join("\n")}`); +console.log("Verified the quoted requirement of every normative validator message and mock check against the runtime pins."); + let failed = false; if (process.argv.includes("--drift")) { const live = new Map(); diff --git a/scripts/keyword-changes.mjs b/scripts/keyword-changes.mjs new file mode 100644 index 00000000..7beae596 --- /dev/null +++ b/scripts/keyword-changes.mjs @@ -0,0 +1,84 @@ +#!/usr/bin/env node +/** + * The sentences whose BCP 14 key words changed between two snapshots, such + * as a MUST that became a SHOULD: `node scripts/keyword-changes.mjs `. A report for review when a pin is refreshed + * (docs/upgrading.md), never a gate: it pairs each sentence with the most + * similar one on the same page, which an edit can fool, and a key word can + * move to another sentence. The changelog says what changed on purpose; this + * finds what it doesn't say, such as an entry edited in place. + * + * Pages pair by name without their version (`0.4-spec` with `1.0-spec`). + */ +import { readFileSync, readdirSync } from "node:fs"; +import path from "node:path"; +import { normalize } from "./check-requirements.mjs"; + +const KEY_WORDS = /\b(MUST NOT|MUST|REQUIRED|SHALL NOT|SHALL|SHOULD NOT|SHOULD|NOT RECOMMENDED|RECOMMENDED|MAY|OPTIONAL)\b/g; +const keyWords = (sentence) => [...new Set(sentence.match(KEY_WORDS) ?? [])].sort().join(", "); + +function pages(snapshot) { + const dir = path.join(snapshot, "pages"); + return new Map( + readdirSync(dir) + .filter((file) => file.endsWith(".md")) + .map((file) => [file.replace(/^\d+\.\d+-/, "").replace(/\.md$/, ""), sentences(readFileSync(path.join(dir, file), "utf8"))]) + ); +} + +function sentences(text) { + return text + .split(/\n\s*\n|\n(?=- |\| |\d+\. )/) + .flatMap((block) => normalize(block).split(/(?<=[.;])\s+(?=[A-Z])/)) + .filter((sentence) => sentence.length > 30 && sentence.length < 800) + .map((sentence) => ({ sentence, words: new Set(sentence.toLowerCase().match(/[a-z0-9_.:/-]{4,}/g) ?? []) })); +} + +const similarity = (a, b) => { + let shared = 0; + for (const word of a) if (b.has(word)) shared++; + return shared / Math.max(1, a.size + b.size - shared); +}; + +/** For each sentence with key words in `from`, the most similar sentence in `to`, when its key words differ. */ +function changed(from, to) { + const found = []; + for (const one of from) { + const words = keyWords(one.sentence); + if (!words) continue; + let best, score = 0; + for (const other of to) { + const s = similarity(one.words, other.words); + if (s > score) [best, score] = [other, s]; + } + if (best && score > 0.45 && keyWords(best.sentence) !== words) found.push({ from: one.sentence, to: best.sentence, score }); + } + return found; +} + +const [oldSnapshot, newSnapshot] = process.argv.slice(2); +if (!oldSnapshot || !newSnapshot) { + console.error("Usage: node scripts/keyword-changes.mjs "); + process.exit(2); +} +const before = pages(oldSnapshot), after = pages(newSnapshot); +let count = 0; +for (const [name, old] of before) { + const now = after.get(name); + if (!now) { + console.log(`## ${name}: not in ${newSnapshot}`); + continue; + } + // Both directions: a weakened sentence is found from the old text, a strengthened one from the new. + const seen = new Set(); + const report = [...changed(old, now), ...changed(now, old).map(({ from, to, score }) => ({ from: to, to: from, score }))] + .filter(({ from, to }) => !seen.has(`${from}\n${to}`) && seen.add(`${from}\n${to}`)); + if (report.length === 0) continue; + console.log(`## ${name}`); + for (const { from, to, score } of report) { + count++; + console.log(`\n${keyWords(from) || "no key word"} → ${keyWords(to) || "no key word"} (similarity ${score.toFixed(2)})\n before: ${from}\n after: ${to}`); + } + console.log(""); +} +console.log(`${count} sentences whose key words changed, from ${oldSnapshot} to ${newSnapshot}.`); diff --git a/spec/requirements-0.4.json b/spec/requirements-0.4.json index 87705f0e..e85eda0c 100644 --- a/spec/requirements-0.4.json +++ b/spec/requirements-0.4.json @@ -170,7 +170,7 @@ "disposition": "Done", "implementation": "src/poppy/discovery.ts", "evidence": "test/poppy-0.4.test.ts", - "notes": "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." + "notes": "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." }, { "change": "`extension_required` in a JSON body at APIs", diff --git a/src/validator/messages.ts b/src/validator/messages.ts index e6be74a8..6f0d5b7e 100644 --- a/src/validator/messages.ts +++ b/src/validator/messages.ts @@ -18,9 +18,17 @@ * without a description). Each says so in `explain`, so a report never * presents our policy as the draft's requirement. * - * The draft is 0.4 (spec/draft-0.4-retrieved-2026-11-11), and the links go - * to its pages. Where 0.3 or 0.4 changed a rule a Company may still follow, - * the explanation says what replaced it. + * The messages check 0.4 (spec/draft-0.4-retrieved-2026-11-11) and the 1.0 + * draft (spec/draft-1.0-retrieved-2026-11-13). The links go to 0.4's pages, + * or 1.0's (`spec10`) for a rule 0.4 doesn't have. Where 0.3, 0.4 or 1.0 + * changed a rule a Company may still follow, the explanation says what + * replaced it. + * + * A MUST, SHOULD or Rule message quotes the sentence it enforces in + * `requires`, verbatim in every runtime pin and with its key word, so that + * `npm run check:spec` fails when the text changes upstream + * (scripts/check-requirements.mjs). A message whose ref is an RFC rests on + * that RFC instead. */ import { levelOf, severityOf, type Basis, type Severity } from "./levels.ts"; @@ -58,6 +66,11 @@ export const rfc = (number: number, section?: string): Ref => ({ type Definition = { /** What the message rests on; its severity follows. */ readonly basis: Basis; + /** + * For a MUST, SHOULD or Rule: the sentence it enforces, verbatim from every + * runtime pin, with its key word (scripts/check-requirements.mjs). + */ + readonly requires?: string; /** It reports a fact, not a departure from anything: info, whatever its basis. */ readonly note?: true; /** Whether our client refuses a Company over it, when that differs from "it's an error". */ @@ -81,13 +94,16 @@ const define = >(catalog: T): { readonly [K export const MESSAGES = define({ "version-unsupported": { - basis: "MUST", title: "Unsupported protocol version", + basis: "MUST", + requires: "The Personal Agent chooses the newest version … compatible with one it implements … If none is, it MUST NOT use any of them", + title: "Unsupported protocol version", explain: "Before 1.0, every major.minor version can break compatibility. An agent must explicitly support the declared version.", fix: "Use a supported protocol version or upgrade the agent.", ref: spec("3.1", "fields") }, // Fetching "http-not-https": { basis: "MUST", + requires: "Every URL this protocol defines or exchanges MUST be an HTTPS URL", title: "Not an HTTPS URL", explain: "Discovery documents, metadata and key sets are fetched only over HTTPS.", fix: "Serve the document over HTTPS and link to it with an https:// URL.", @@ -95,6 +111,7 @@ export const MESSAGES = define({ }, "http-non-public-host": { basis: "MUST", + requires: "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", title: "Not a public host", explain: "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 (3). By name alone, this validator, like our client, never fetches IP literals, single-label hosts, or special-use and private-use names such as localhost, .local, .internal and .home.arpa, so it can't check a document there. A name can still resolve to a private address: on Cloudflare Workers the platform refuses those connections, and the command-line validator checks each address a name resolves to (http-non-public-address). Used as a library elsewhere, it checks names only, so the caller must supply a fetcher that checks addresses.", @@ -103,6 +120,7 @@ export const MESSAGES = define({ }, "http-non-public-address": { basis: "MUST", + requires: "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", title: "Resolves to a private address", explain: "Personal Agents and Companies MUST NOT connect to a loopback, private or link-local address for a URL the other party gave them (3), and the Guides say to judge by the address actually connected to. The host name is public, but it resolves to such an address (loopback, RFC 1918, link-local, carrier-grade NAT, unique local, unspecified, multicast or another range that isn't globally reachable), so nothing was checked there. The command-line validator resolves each name itself, refuses these, and connects only to the address it checked.", @@ -111,6 +129,7 @@ export const MESSAGES = define({ }, "http-redirect-not-https": { basis: "MUST", + requires: "Personal Agents MUST follow redirects, and every redirect MUST be to an HTTPS URL", title: "Redirect to a non-HTTPS URL", explain: "Every redirect from the well-known URL must be to an HTTPS URL. Agents stop at the first one that isn't.", fix: "Make each Location header an https:// URL.", @@ -118,6 +137,7 @@ export const MESSAGES = define({ }, "http-too-many-redirects": { basis: "Guides", + requires: "Set limits: a few redirects at most", refuses: true, title: "Too many redirects", explain: @@ -127,6 +147,7 @@ export const MESSAGES = define({ }, "http-redirect-not-allowed": { basis: "Rule", + requires: "Fetches the client metadata from iss without following redirects, as the CIMD draft (§5) requires", title: "Client metadata is served by a redirect", explain: "A Company fetches the client metadata at client_id without following redirects, as the CIMD draft (§5) requires (5.3), and client_id MUST equal the URL the document was fetched from (4.1). A redirect there fails verification at every Company, so this validator doesn't follow it either.", @@ -135,6 +156,7 @@ export const MESSAGES = define({ }, "http-status": { basis: "MUST", + requires: "A Company MUST publish its poppy.json document at https://{domain}/.well-known/poppy.json over HTTPS", title: "Not served with HTTP 200", explain: "The document must be served successfully for anyone to use it.", fix: "Serve the document with status 200.", @@ -142,6 +164,7 @@ export const MESSAGES = define({ }, "http-failed": { basis: "Guides", + requires: "Set limits: … a timeout of a few seconds", refuses: true, title: "Couldn't fetch the document", explain: "The request failed before a response arrived: DNS, TLS, the connection, or the timeout (10 seconds, the top of the Guides' \"few seconds\", so a serverless Company's cold start fits). Nothing was checked, and our client can't use a document it couldn't fetch.", @@ -150,6 +173,7 @@ export const MESSAGES = define({ }, "http-too-large": { basis: "Guides", + requires: "Set limits: … a response size such as 100 KB", refuses: true, title: "Document too large", explain: @@ -209,6 +233,7 @@ export const MESSAGES = define({ }, "json-resource-limit": { basis: "Guides", + requires: "Set limits: a few redirects at most, a response size such as 100 KB, and a timeout of a few seconds", refuses: true, title: "JSON location metadata exceeds the validator's resource allowance", explain: "Our client limits cumulative escaped JSON-pointer strings to one million UTF-16 code units, before constructing them. A long member name repeated in every child's location can otherwise use far more memory than the document's byte size. This is an implementation policy for safely processing untrusted documents, not a JSON syntax error or a protocol requirement. Nothing was checked beyond this limit.", @@ -216,7 +241,8 @@ export const MESSAGES = define({ ref: guides("Fetching metadata safely", "both-fetching") }, "json-duplicate-member": { - basis: "SHOULD", + basis: "Guides", + requires: "Encode JSON as UTF-8 and reject objects with duplicate member names", refuses: true, title: "Duplicate member name", explain: @@ -228,6 +254,7 @@ export const MESSAGES = define({ // Generic structure "missing-member": { basis: "MUST", + requires: "| protocol_version | Yes | The protocol version the document follows, as major.minor", title: "Required member missing", explain: "A member the specification requires isn't there.", fix: "Add the member described in the message.", @@ -235,13 +262,15 @@ export const MESSAGES = define({ }, "wrong-type": { basis: "Rule", + requires: "A list of APIs. Each has a type", title: "Wrong type", explain: "A member has the wrong JSON type, such as a string where an object is required.", fix: "Use the type given in the message.", ref: spec("3.1", "fields") }, "not-a-url": { - basis: "Rule", + basis: "MUST", + requires: "Every URL this protocol defines or exchanges MUST be an HTTPS URL", title: "Not an absolute URL", explain: "The value must be an absolute URL with a host name (or an IP address), such as https://api.example.com/.", fix: "Use a full URL, starting with https://.", @@ -249,6 +278,7 @@ export const MESSAGES = define({ }, "not-https-url": { basis: "MUST", + requires: "Every URL this protocol defines or exchanges MUST be an HTTPS URL", title: "URL isn't HTTPS", explain: "Every URL the protocol defines or exchanges MUST be an HTTPS URL (3): in poppy.json, in authorization server and protected resource metadata, in client metadata and in extensions. The one exception is a loopback redirect URI in a Personal Agent's redirect_uris (4.1), such as http://127.0.0.1/callback.", @@ -285,6 +315,7 @@ export const MESSAGES = define({ // poppy.json "version-format": { basis: "Rule", + requires: "The protocol version the document follows, as major.minor", title: "protocol_version isn't major.minor", explain: 'protocol_version is a string of two numbers, such as "0.4".', fix: 'Set protocol_version to "0.4".', @@ -292,6 +323,7 @@ export const MESSAGES = define({ }, "version-unsupported-major": { basis: "MUST", + requires: "The Personal Agent chooses the newest version … compatible with one it implements … If none is, it MUST NOT use any of them", title: "Unsupported major version", explain: "A Personal Agent must not use a document whose major version it doesn't support. This validator knows the versions listed on the validator page.", fix: "Publish a document for a supported major version, or check a newer validator.", @@ -307,7 +339,8 @@ export const MESSAGES = define({ ref: spec10("3.4", "versions") }, "domain-invalid": { - basis: "Rule", + basis: "MUST", + requires: "domain MUST be the host that serves the document, after any redirects", title: "Not a domain name", explain: "The value must be a DNS host name, such as example.com, with no scheme or path. From 1.0, organization.domain may carry its port when that isn't 443, such as shop.test:8443 for testing (3.1); 0.4 allows no port.", fix: "Use the bare host name, or under 1.0 the host name and a port other than 443.", @@ -315,6 +348,7 @@ export const MESSAGES = define({ }, "organization-domain-mismatch": { basis: "MUST", + requires: "domain MUST be the host that serves the document, after any redirects", title: "organization.domain doesn't match the requested domain", explain: "organization.domain MUST be the host that serves the document, after any redirects, compared ignoring case and nothing else, so www.example.com and example.com differ. Otherwise a document copied to another domain could speak for the Company.", @@ -323,6 +357,7 @@ export const MESSAGES = define({ }, "organization-name-missing": { basis: "Rule", + requires: "The Company's display name, its domain, and an optional logo_uri", title: "No display name", explain: "organization is required and is the Company's \"Display name and domain\" (3.1): a normative statement without a key word, so a missing or blank name is an error. Personal Agents show organization.name to the User, such as next to a Device Sign-In link (4.3), so our client refuses a Company without one.", @@ -330,7 +365,8 @@ export const MESSAGES = define({ ref: spec("3.1", "fields") }, "nothing-offered": { - basis: "MUST", + basis: "Rule", + requires: "| agent | At least one of agent, apis, or web |", title: "No agent, apis or web", explain: "A poppy.json must offer at least one of agent, apis, or web.", fix: "Add the Company Agent, an API, or the website.", @@ -359,11 +395,12 @@ export const MESSAGES = define({ ref: rfc(6749, "3.3") }, "scope-undescribed": { - basis: "MUST", + basis: "SHOULD", + requires: "The Company SHOULD describe each scope it offers Personal Agents, so the Personal Agent can choose the ones a task needs", title: "Supported scope has no description", explain: - "The Company MUST describe each scope in scopes_supported, so agents can choose the ones a task needs and explain them to the User: in an OAuth security scheme of an OpenAPI description poppy.json lists, or otherwise in auth.scopes (4.7). poppy.json lists no OpenAPI description, so auth.scopes has to describe every one. (0.3 replaced 0.2's auth.custom_scopes with auth.scopes.)", - fix: "Add the scope to auth.scopes with a short description, or leave it out of scopes_supported.", + "The Company SHOULD describe each scope it offers Personal Agents, so the Personal Agent can choose the ones a task needs: in an OAuth security scheme of an OpenAPI description poppy.json lists, or otherwise in auth.scopes (4.7). poppy.json lists no OpenAPI description, so only auth.scopes can describe them. When the domain's protected resource metadata lists scopes_supported, those are the scopes checked: the issuer's own list may hold scopes for its other resources and clients (3.2). 0.3's text of 29 October made it a MUST for every scope in scopes_supported; by 3 November it was this SHOULD.", + fix: "Add the scope to auth.scopes with a short description. A scope offered only to other clients can be left out of scopes_supported, or the domain's protected resource metadata can list the scopes it offers.", ref: spec("4.7", "scopes") }, "scopes-empty": { @@ -391,6 +428,7 @@ export const MESSAGES = define({ }, "mediated-field-duplicate": { basis: "Rule", + requires: "name is the parameter the Personal Agent sends", title: "Credential field named twice", explain: "Each field's name is the parameter the agent sends it in, so names must be unique.", fix: "Give each field a different name.", @@ -421,6 +459,7 @@ export const MESSAGES = define({ }, "protocol-description-empty": { basis: "MUST", + requires: "The Company MUST include a description in every entry", title: "Empty conversation protocol description", explain: "From 1.0, every agent.protocols entry has a description of what the agent at that endpoint can help with, which a Personal Agent uses to decide whether a conversation serves the task and to choose between the entries and the Company's APIs (8.1). An empty one says nothing.", @@ -455,6 +494,7 @@ export const MESSAGES = define({ }, "api-description-missing": { basis: "Rule", + requires: "Each has a type, such as those in section 7, a url, and a short description that helps the Personal Agent pick the right one", refuses: false, title: "API has no description", explain: @@ -464,6 +504,7 @@ export const MESSAGES = define({ }, "extension-name": { basis: "MUST", + requires: "Anyone else MUST start an extension's name with a domain they control", title: "Invalid extension name", explain: "Extensions defined with the protocol have plain names. Anyone else must start the name with a domain they control, such as example.com/gift-wrap.", @@ -498,6 +539,7 @@ export const MESSAGES = define({ // OAuth authorization server metadata "metadata-issuer-mismatch": { basis: "MUST", + requires: "the Personal Agent fetches the metadata and MUST check that its issuer exactly matches the issuer it found, character for character", title: "Metadata issuer doesn't match the Company's issuer", explain: "The metadata's issuer must exactly equal the issuer the domain's protected resource metadata names (and auth.issuer, when poppy.json chooses one), character for character. Otherwise any domain could claim another Company's issuer and receive its tokens.", @@ -515,6 +557,7 @@ export const MESSAGES = define({ }, "metadata-pkce": { basis: "Guides", + requires: "Accept PKCE with S256 only, and reject plain", title: "S256 not advertised for PKCE", explain: "Direct Sign-In uses PKCE with S256, and code_challenge_methods_supported doesn't list it.", fix: "Add S256.", @@ -522,6 +565,7 @@ export const MESSAGES = define({ }, "poppy-redirect-path": { basis: "MUST", + requires: "Personal Agents MUST use the document only when the last URL's path is exactly /.well-known/poppy.json and it has no query", title: "Redirected away from the well-known path", explain: "A redirect may move poppy.json to another host, but agents use it only when the last URL's path is exactly /.well-known/poppy.json, with no query. Otherwise anyone who can serve a file from some path on a domain could have it speak for that domain.", fix: "Redirect to /.well-known/poppy.json on the other host, without a query.", @@ -529,6 +573,7 @@ export const MESSAGES = define({ }, "prm-resource-mismatch": { basis: "MUST", + requires: "its resource MUST be exactly https://{organization.domain}", title: "Protected resource metadata names another resource", explain: "The domain's protected resource metadata is how agents find the issuer. Its resource must be exactly https:// and the domain.", fix: "Set resource to https://{organization.domain}.", @@ -544,6 +589,7 @@ export const MESSAGES = define({ }, "issuer-required": { basis: "MUST", + requires: "A Company that offers sign-in MUST have an OAuth issuer", title: "Sign-in offered without an issuer", explain: "A Company that offers sign-in MUST have an OAuth issuer (3.2). auth.issuer, the Mediated Sign-In extension and signed_in access each offer sign-in, but the domain's protected resource metadata says there is no issuer.", fix: "Publish protected resource metadata whose authorization_servers names the issuer, or remove what offers sign-in.", @@ -551,6 +597,7 @@ export const MESSAGES = define({ }, "auth-disabled-sign-in": { basis: "MUST", + requires: "A Company that sets auth.disabled MUST NOT list the Mediated Sign-In extension or signed_in access", title: "auth.disabled, but sign-in is still offered", explain: "A Company that sets auth.disabled offers Personal Agents no sign-in, so it MUST NOT list the Mediated Sign-In extension or signed_in access (3.2).", fix: "Remove the Mediated Sign-In extension and signed_in access, or stop setting auth.disabled.", @@ -566,6 +613,7 @@ export const MESSAGES = define({ }, "scopes-supported-missing": { basis: "SHOULD", + requires: "A Company that offers sign-in SHOULD list every scope a Personal Agent can request here", title: "No scopes_supported", explain: "A Company that offers sign-in SHOULD publish scopes_supported in its OAuth metadata, or in its protected resource metadata, and include every scope a Personal Agent can request (3.2, 4.7). Without either, agents learn scopes only from the Company's OpenAPI descriptions and auth.scopes. (Earlier text of draft 0.3 required it in the OAuth metadata.)", fix: "Add scopes_supported, listing the scopes Personal Agents may request.", @@ -591,13 +639,15 @@ export const MESSAGES = define({ }, "issuer-not-listed": { basis: "MUST", + requires: "naming the one Personal Agents use (3.2). It MUST be in that list.", title: "auth.issuer isn't an authorization server of the domain", explain: "auth.issuer only chooses among the domain's authorization_servers, so it must be one of them.", fix: "Make auth.issuer one of the domain's authorization_servers, or leave it out when there is one.", ref: spec("3.1", "fields") }, "issuer-ambiguous": { - basis: "MUST", + basis: "Rule", + requires: "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", title: "Several authorization servers and no auth.issuer", explain: "User IDs and refresh tokens belong to one issuer, so every agent has to choose the same one. With more than one authorization server, auth.issuer says which.", fix: "Add auth.issuer, naming the server agents use.", @@ -605,6 +655,7 @@ export const MESSAGES = define({ }, "metadata-protected-resources": { basis: "MUST", + requires: "Its protected_resources (RFC 9728 §4) MUST list https://{domain} for every domain whose issuer it is", title: "protected_resources doesn't include the domain", explain: "The issuer confirms the domain from its side by listing https://{domain} in protected_resources. Agents refuse a domain it doesn't list, so a domain can't claim another Company's issuer.", fix: "Add https:// and organization.domain to protected_resources, with no path, port or trailing slash.", @@ -612,6 +663,7 @@ export const MESSAGES = define({ }, "metadata-assertion-algs": { basis: "MUST", + requires: "Companies MUST accept client assertions signed with ES256 and with PS384.", title: "Client assertion algorithms leave out ES256 or PS384", explain: "From 1.0, Companies MUST accept client assertions signed with ES256 and with PS384 (4.1), so a Personal Agent can have them signed blindly (10.7). A token_endpoint_auth_signing_alg_values_supported that leaves either out says the token endpoint refuses them.", @@ -628,6 +680,7 @@ export const MESSAGES = define({ }, "metadata-refresh-grant": { basis: "MUST", + requires: "grant_types_supported lists the grant types the token endpoint accepts. Required, and it MUST include refresh_token", title: "No refresh_token grant", explain: "grant_types_supported must include refresh_token: every sign-in returns a refresh token, which agents use to get access tokens later.", fix: "Add refresh_token to grant_types_supported.", @@ -635,6 +688,7 @@ export const MESSAGES = define({ }, "scope-hint-invalid": { basis: "MUST", + requires: "A Company MUST include both fields in each entry.", title: "Scope hint without changes and personal_data", explain: "Each entry in auth.scope_hints must have both fields: changes, a string, and personal_data, a boolean.", fix: "Give the scope's hint both fields, or leave the scope out of scope_hints.", @@ -650,22 +704,26 @@ export const MESSAGES = define({ }, "mediated-field-reserved": { basis: "MUST", + requires: "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", title: "Mediated Sign-In field with a reserved name", explain: "A field's name is a parameter of the token request, so it can't be grant_type, scope, resource, a client authentication parameter, or one the extension defines.", fix: "Rename the field.", ref: mediatedExt("2", "support") }, "mediated-grant-missing": { - basis: "MUST", + basis: "Rule", + requires: "A Company that offers Mediated Sign-In lists it in extensions in its poppy.json (spec 3.3), and lists the grant type https://personalagentprotocol.org/grant/mediated-sign-in in its issuer's grant_types_supported", title: "Mediated Sign-In's grant isn't advertised", explain: "A Company that offers Mediated Sign-In lists its grant type in the issuer's grant_types_supported.", fix: "Add https://personalagentprotocol.org/grant/mediated-sign-in to grant_types_supported.", ref: mediatedExt("2", "support") }, "mediated-scope-unsupported": { - basis: "MUST", - title: "Mediated Sign-In offers a scope the issuer doesn't support", - explain: "Every scope the extension lists must be in the issuer's scopes_supported.", + basis: "SHOULD", + requires: "The Company SHOULD also include them in scopes_supported", + title: "Mediated Sign-In offers a scope scopes_supported doesn't list", + explain: + "The Company SHOULD also include the scopes the extension lists in scopes_supported, in its OAuth server metadata or protected resource metadata (Mediated Sign-In 2). A Personal Agent may still request a scope a sign-in extension documents (4.7), so this is a warning. 0.3's text of 28 October listed all of them in scopes_supported; by 3 November this was a SHOULD.", fix: "Add the scope to scopes_supported, or remove it from the extension's scopes.", ref: mediatedExt("2", "support") }, @@ -682,6 +740,7 @@ export const MESSAGES = define({ // Client metadata and keys "client-id-mismatch": { basis: "MUST", + requires: "client_id MUST equal the URL the document was fetched from.", title: "client_id isn't the URL it was fetched from", explain: "A Personal Agent's client_id must equal the URL its metadata document was fetched from.", fix: "Set client_id to the exact URL of this document.", @@ -689,6 +748,7 @@ export const MESSAGES = define({ }, "client-other-domain": { basis: "MUST", + requires: "jwks_uri MUST be an HTTPS URL on the same domain as client_id. … Each entry MUST be an HTTPS URL on the same domain as client_id, or a loopback redirect URI", title: "URL on a different domain from client_id", explain: "jwks_uri, and every redirect URI that isn't a loopback redirect URI (RFC 8252 §7.3), must be an HTTPS URL on the same domain as client_id.", fix: "Host them on client_id's domain.", @@ -696,6 +756,7 @@ export const MESSAGES = define({ }, "client-auth-method": { basis: "Rule", + requires: "The Personal Agent authenticates at the token endpoint with a client assertion signed by a key from jwks_uri (private_key_jwt, RFC 7523).", title: "Token endpoint auth method isn't private_key_jwt", explain: "Personal Agents authenticate with private_key_jwt (4.1, 4.8), and the draft's example declares it. The draft has no MUST for the member, but without it OAuth's default (client_secret_basic, RFC 7591 §2) applies, which doesn't fit.", @@ -712,6 +773,7 @@ export const MESSAGES = define({ }, "jwks-empty": { basis: "Rule", + requires: "The Personal Agent authenticates at the token endpoint with a client assertion signed by a key from jwks_uri", title: "No keys", explain: "The key set has no keys, so nothing the agent signs can be verified.", fix: "Publish at least one public signing key.", @@ -719,6 +781,7 @@ export const MESSAGES = define({ }, "jwks-private-key": { basis: "Rule", + requires: "The key set contains only public keys.", title: "Private key material published", explain: "The key set contains only public keys. This key has private members (d, p, q, dp, dq, qi or k), so the key is compromised.", fix: "Remove the key, generate a new one, and publish only its public part.", @@ -726,10 +789,11 @@ export const MESSAGES = define({ }, "jwks-key-type": { basis: "Guides", + requires: "Sign client assertions and delegations with ES256, or with PS384 if you sign them blindly", title: "Unsupported key", explain: - "Companies MUST accept client assertions and delegations signed with ES256, and SHOULD accept PS384 (4.1, 5.2), and the Guides say to sign with one of them, so Companies may accept only EC P-256 and RSA keys. The draft doesn't restrict key types, so this is a warning.", - fix: "Use an EC P-256 key, or an RSA key of at least 2048 bits for PS384.", + "Companies MUST accept client assertions and delegations signed with ES256, and SHOULD accept PS384 (4.1, 5.2; from 1.0 they MUST accept both), and the Guides say to sign with one of them, so Companies may accept only EC P-256 and RSA keys. The draft doesn't restrict key types, so this is a warning.", + fix: "Use an EC P-256 key, or for PS384 an RSA key of at least 2048 bits (from 1.0, 2048 to 4096 bits).", ref: guides("Signing and verifying JWTs", "both-signing") }, "jwks-rsa-small": { @@ -748,14 +812,16 @@ export const MESSAGES = define({ }, "jwks-alg": { basis: "Guides", + requires: "Sign client assertions and delegations with ES256, or with PS384 if you sign them blindly", title: "Key algorithm isn't ES256 or PS384", explain: - "The keys in jwks_uri sign client assertions and delegations. Companies MUST accept both signed with ES256, and SHOULD accept PS384 (4.1, 5.2), a delegation's alg is one of the two (5.2), and the Guides say to sign with ES256, or PS384 when signing blindly; a Company without PS384 can't verify a blind signature. A key marked with another alg may be ignored, and one marked RS256 can't sign delegations, so it can't make Session JWTs.", + "The keys in jwks_uri sign client assertions and delegations. Companies MUST accept both signed with ES256, and SHOULD accept PS384 (4.1, 5.2; from 1.0 they MUST accept both), a delegation's alg is one of the two (5.2), and the Guides say to sign with ES256, or PS384 when signing blindly; a Company without PS384 can't verify a blind signature. A key marked with another alg may be ignored, and one marked RS256 can't sign delegations, so it can't make Session JWTs.", fix: "Use ES256, or PS384 for blind signing.", ref: guides("Signing and verifying JWTs", "both-signing") }, "jwks-no-kid": { basis: "Guides", + requires: "Give every key in jwks_uri a kid.", title: "Key has no kid", explain: "Every key needs a kid so keys can be rotated and Companies can pick the right one.", fix: "Add a unique kid to each key.", @@ -767,11 +833,12 @@ export const MESSAGES = define({ explain: "Different keys in a key set SHOULD have different kids (RFC 7517 §4.5), and the Guides give every key one for rotation. Verifiers may pick the wrong key. A SHOULD, so this is a warning.", fix: "Give each key a unique kid.", - ref: guides("Rotating keys", "both-key-rotation") + ref: rfc(7517, "4.5") }, // Versions (3.4), and what 0.4 changed "supported-version-unusable": { basis: "MUST", + requires: "Each URL in supported_versions MUST be an HTTPS URL on the host that served poppy.json, after any redirects.", refuses: false, title: "A supported_versions entry agents can't use", explain: @@ -781,6 +848,7 @@ export const MESSAGES = define({ }, "linked-document-version": { basis: "MUST", + requires: "The Personal Agent MUST NOT use it if its protocol_version is another one.", title: "A linked document has another protocol version", explain: "The document a supported_versions entry links to has the protocol_version it is listed under, and an agent MUST NOT use it otherwise (3.4).", fix: "Serve the document for the version it is listed under, or fix the entry.", @@ -788,6 +856,7 @@ export const MESSAGES = define({ }, "linked-document-supported-versions": { basis: "Rule", + requires: "The document there has the protocol_version it is listed under, and no supported_versions.", refuses: false, title: "A linked document lists supported_versions", explain: "Only poppy.json lists the versions a Company serves; the document for another version has no supported_versions (3.4). Our client ignores the member there.", @@ -796,6 +865,7 @@ export const MESSAGES = define({ }, "linked-document-domain": { basis: "MUST", + requires: "Every document a Company serves at the same time MUST have the same organization.domain", title: "Versions disagree on the Company's domain", explain: "Every document a Company serves at the same time MUST have the same organization.domain, so a new version doesn't change the Company's identifier, and with it User IDs and refresh tokens (3.4).", fix: "Give every version's document the same organization.domain.", @@ -803,6 +873,7 @@ export const MESSAGES = define({ }, "extension-entries": { basis: "Rule", + requires: "A Company lists the ones it supports in extensions, with an entry for each major version it supports", refuses: false, title: "An extension isn't a list of versions", explain: @@ -821,6 +892,7 @@ export const MESSAGES = define({ }, "web-disabled-browser-session": { basis: "MUST", + requires: "A Company that sets web.disabled MUST NOT list browser_session_endpoint", title: "web.disabled with a browser-session endpoint", explain: "A Company that sets web.disabled asks agents not to use a browser on its website, so it MUST NOT list browser_session_endpoint (6).", fix: "Remove web.browser_session_endpoint, or web.disabled.", @@ -828,6 +900,7 @@ export const MESSAGES = define({ }, "web-disabled-no-alternative": { basis: "MUST", + requires: "A Company that sets web.disabled MUST NOT list browser_session_endpoint, and MUST list agent or apis.", title: "web.disabled with nothing else to use", explain: "A Company that asks agents not to browse its website MUST list agent or apis, so they have something to use instead (6).", fix: "List the Company Agent or an API, or remove web.disabled.", @@ -835,6 +908,7 @@ export const MESSAGES = define({ }, "operations-endpoint-without-join": { basis: "MUST", + requires: "It MUST list web.browser_session_endpoint with it", title: "Website operations without browser join", explain: "An operations entry's endpoint is for operations a website returns to a browser joined to a Session, so the Company MUST list web.browser_session_endpoint with it (Operations 2).", fix: "List web.browser_session_endpoint, or remove the endpoint.", @@ -842,6 +916,7 @@ export const MESSAGES = define({ }, "browser-control-without-join": { basis: "Rule", + requires: "A Company that supports this extension lists it in extensions in its poppy.json (spec 3.3), with web.browser_session_endpoint", title: "Browser Control without browser join", explain: "A Company that supports Browser Control lists it with web.browser_session_endpoint (Browser Control 3): marked steps are for a browser joined to a Session.", fix: "List web.browser_session_endpoint, or remove the extension.", @@ -849,6 +924,7 @@ export const MESSAGES = define({ }, "web-unscoped-without-join": { basis: "MUST", + requires: "A Company that sets web.unscoped MUST list browser_session_endpoint.", title: "web.unscoped without browser join", explain: "web.unscoped says that poppy:browser-sign-in gives a joined browser the account's full access on the website, so a Company that sets it MUST list web.browser_session_endpoint (6).", fix: "List web.browser_session_endpoint, or remove web.unscoped.", @@ -856,6 +932,7 @@ export const MESSAGES = define({ }, "browser-sign-in-unsupported": { basis: "MUST", + requires: "A Company that lists browser_session_endpoint and offers sign-in MUST support poppy:browser-sign-in", title: "Browser join without poppy:browser-sign-in", explain: "A Company that lists browser_session_endpoint and offers sign-in MUST support poppy:browser-sign-in, the scope that signs a joined browser in (6), so its scopes_supported includes it (4.7). It MAY grant the scope to fewer clients or Users.", fix: "Add poppy:browser-sign-in to scopes_supported and describe it in auth.scopes, or remove web.browser_session_endpoint.", @@ -863,6 +940,7 @@ export const MESSAGES = define({ }, "direct-sign-in-preferred": { basis: "SHOULD", + requires: "A Company that offers sign-in SHOULD offer Direct Sign-In.", title: "Device Sign-In without Direct Sign-In", explain: "Direct Sign-In is the preferred sign-in type, and a Company that offers sign-in SHOULD offer it (4). This issuer offers Device Sign-In, which is easier to use for phishing, but not Direct.", fix: "Add authorization_code to grant_types_supported, with an authorization_endpoint.", diff --git a/src/validator/profiles/draft-0.4.ts b/src/validator/profiles/draft-0.4.ts index fe7e7917..5fac2ecf 100644 --- a/src/validator/profiles/draft-0.4.ts +++ b/src/validator/profiles/draft-0.4.ts @@ -382,6 +382,7 @@ export function checkProtectedResource(c: Checker, doc: unknown, poppy: PoppyFac if (resource !== undefined && poppy.domain !== undefined && resource !== `https://${poppy.domain}` && resource.toLowerCase() !== `https://${poppy.domain.toLowerCase()}`) { c.report("prm-resource-mismatch", "/resource", `resource is ${JSON.stringify(resource)}, not https://${poppy.domain}.`); } + if (Array.isArray(doc.scopes_supported)) undescribedScopes(c, doc.scopes_supported, poppy.describedScopes); // 3.2: absent or empty, the Company has no issuer; a value of the wrong type settles nothing. if (!("authorization_servers" in doc)) { noIssuer(c, poppy, "empty"); @@ -410,6 +411,20 @@ export function checkProtectedResource(c: Checker, doc: unknown, poppy: PoppyFac return usable.has(list[0]!) ? list[0] : undefined; } +/** + * 4.7: the Company SHOULD describe each scope it offers Personal Agents, in + * an OpenAPI description or otherwise in auth.scopes. `described` is unset + * when poppy.json lists an OpenAPI description, which may describe the rest. + */ +function undescribedScopes(c: Checker, scopes: unknown[] | undefined, described: readonly string[] | undefined): void { + if (!scopes || !described) return; + scopes.forEach((scope, index) => { + if (typeof scope === "string" && !described.includes(scope)) { + c.report("scope-undescribed", `/scopes_supported/${index}`, `${scope} is in scopes_supported, but poppy.json's auth.scopes doesn't describe it, and poppy.json lists no OpenAPI description that could.`); + } + }); +} + /** * No issuer (3.2): the protected resource metadata is a 404, or names no * authorization server. The Company offers signed-out Sessions only, and @@ -493,13 +508,8 @@ export function checkOAuthMetadata(c: Checker, doc: unknown, poppy: PoppyFacts | for (const scope of poppy?.mediatedScopes ?? []) { if ((scopes || resourceScopes) && !listed.includes(scope)) c.report("mediated-scope-unsupported", "/scopes_supported", `Mediated Sign-In offers ${scope}, which isn't in scopes_supported.`); } - // 4.7: auth.scopes describes each supported scope, unless an OpenAPI description might. - const described = poppy?.describedScopes; - if (described) { - supported.forEach((scope, index) => { - if (!described.includes(scope)) c.report("scope-undescribed", `/scopes_supported/${index}`, `${scope} is in scopes_supported, but poppy.json's auth.scopes doesn't describe it, and poppy.json lists no OpenAPI description that could.`); - }); - } + // The domain's own list, when it has one, names the scopes it offers Personal Agents (docs/readings.md#v04-scope-descriptions). + if (!resourceScopes?.length) undescribedScopes(c, scopes, poppy?.describedScopes); if (rules.assertionAlgs) { const algs = member(c, doc, "", "token_endpoint_auth_signing_alg_values_supported", "array", false, rules.assertionAlgs.ref); const listed = algs ? stringList(c, algs, "/token_endpoint_auth_signing_alg_values_supported", rules.assertionAlgs.ref) : null; diff --git a/src/validator/validate.ts b/src/validator/validate.ts index 6fd82417..77f1ed14 100644 --- a/src/validator/validate.ts +++ b/src/validator/validate.ts @@ -165,7 +165,7 @@ export type TextOptions = { readonly domain?: string; /** client-metadata: the URL it was fetched from. */ readonly fetchedFrom?: string; - /** Documents without their own version: which protocol version to check against. 0.4, the only one, is the default. */ + /** Documents without their own version: which protocol version to check against; the default is the newest, 1.0 (LATEST). */ readonly protocolVersion?: string; }; diff --git a/test/mock-company.test.ts b/test/mock-company.test.ts index 6e949be1..0e5f4e30 100644 --- a/test/mock-company.test.ts +++ b/test/mock-company.test.ts @@ -2263,8 +2263,9 @@ describe("each check the mock Company makes", () => { it("says what each check rests on, and where in 0.4, and files it as a violation or a warning by that basis", () => { // "MUST (5.2: …): …", "RFC (RFC 9449 4.3; 4.5): …", "Guides (Retries: …): …": the basis, where, then what. + // A quote may hold parentheses; scripts/check-requirements.mjs checks it against the pinned text. const malformed = VIOLATION_IDS.filter( - (id) => !/^(?:MUST(?: NOT)?|RFC|Rule|SHOULD(?: NOT)?|Guides|Reading) \([^)]+\)(?:, strict Company only)?: \S/.test(VIOLATIONS[id]) + (id) => !/^(?:MUST(?: NOT)?|RFC|Rule|SHOULD(?: NOT)?|Guides|Reading) \((?:"[^"]*"|[^)"])+\)(?:, strict Company only)?: \S/.test(VIOLATIONS[id]) ); expect(malformed).toEqual([]); // Every section is 0.4's, so none says so, and none names a version's section. diff --git a/test/mock-company/core.ts b/test/mock-company/core.ts index 8662fe59..9b71c1f8 100644 --- a/test/mock-company/core.ts +++ b/test/mock-company/core.ts @@ -32,8 +32,8 @@ export const CLIENT_ASSERTION_TYPE = /** DPoP proofs (RFC 9449; the metadata lists ES256). */ const SIGNING_ALGS = ["ES256", "RS256"]; -/** Client assertions: Companies MUST accept ES256 and PS384 (4.1), and the Guides add RS256 ("Signing and verifying JWTs"). */ -const CLIENT_ASSERTION_ALGS = ["ES256", "PS384", "RS256"]; +/** Client assertions: Companies MUST accept ES256 and PS384 (4.1); since 0.4 the Guides no longer add RS256. */ +const CLIENT_ASSERTION_ALGS = ["ES256", "PS384"]; const PRIVATE_JWK_FIELDS = ["d", "p", "q", "dp", "dq", "qi", "k"]; /** DPoP acceptance window plus clock skew, seconds. */ const DPOP_WINDOW = 60; diff --git a/test/mock-company/violations.ts b/test/mock-company/violations.ts index 5626bdde..1c15f0b5 100644 --- a/test/mock-company/violations.ts +++ b/test/mock-company/violations.ts @@ -10,18 +10,19 @@ * * Each description starts with what the check rests on, then where: spec * sections bare (`5.2`), `Ops n` for the Operations extension, - * `Mediated Sign-In n` for that extension, and a Guides heading by name, - * checked against the 0.4 text of 11 November 2026 in - * `spec/draft-0.4-retrieved-2026-11-11/pages/` (most were first written - * against 0.3, whose section numbers 0.4 kept): + * `Mediated Sign-In n` for that extension, and a Guides heading by name. + * A MUST, SHOULD, Rule or Guides basis quotes the sentence it rests on, + * verbatim in every runtime pin and with its key word, or in the 1.0 pin + * alone when its location starts `1.0`; `npm run check:spec` checks each + * quote (scripts/check-requirements.mjs): * * - `MUST (5.2: …):` or `MUST NOT (…):` a MUST, MUST NOT or required field * in the spec or one of its extensions. * - `RFC (RFC 9449 4.3; 4.5):` a requirement of a standard the spec builds * on, such as DPoP, which the spec leaves to RFC 9449. * - `Rule (8.9: …):` the spec states it as how the protocol works, with no - * RFC 2119 keyword ("asks for a person at the Company with an empty JSON - * object"). + * RFC 2119 keyword ("asks for a person at the Company with a request + * ID"). * - `SHOULD (…):` or `SHOULD NOT (…):` a SHOULD in the spec. * - `Guides (heading: …):` only a recommendation in the Guides. * - `Reading (S2; 4.1):` our answer to an open question in @@ -59,41 +60,41 @@ export type SignedKind = "client-assertion"; export const VIOLATIONS = { // ---- jti: unique and unguessable (4.1, 5.2; RFC 9449 4.2), 128 random bits (Guides) ---- "client-assertion.jti-missing": "MUST (4.1: \"MUST include iat and a unique, unguessable jti\"): Client assertion without a jti", - "client-assertion.jti-weak": "Guides (Signing and verifying JWTs: a jti of at least 128 random bits; 4.1 asks only that it be unguessable): Client assertion jti is not 128 random bits of base64url", - "client-assertion.jti-reused": "MUST (4.1: a unique jti; the Company MAY reject a reused one, as RFC 7523 3 allows): Client assertion jti used twice", + "client-assertion.jti-weak": "Guides (Signing and verifying JWTs: a jti of at least 128 random bits; 4.1 asks only that it be unguessable; \"Make the jti of each client assertion, delegation, Session JWT, and DPoP proof at least 128 random bits\"): Client assertion jti is not 128 random bits of base64url", + "client-assertion.jti-reused": "MUST (4.1: a unique jti; the Company MAY reject a reused one, as RFC 7523 3 allows; \"MUST include iat and a unique, unguessable jti\"): Client assertion jti used twice", "dpop.jti-missing": "RFC (RFC 9449 4.2; 4.5): DPoP proof without a jti", - "dpop.jti-weak": "Guides (Signing and verifying JWTs: at least 128 random bits; RFC 9449 4.2 asks for a negligible chance of reuse): DPoP proof jti is not 128 random bits of base64url", + "dpop.jti-weak": "Guides (Signing and verifying JWTs: at least 128 random bits; RFC 9449 4.2 asks for a negligible chance of reuse; \"Make the jti of each client assertion, delegation, Session JWT, and DPoP proof at least 128 random bits\"): DPoP proof jti is not 128 random bits of base64url", "dpop.jti-reused": "RFC (RFC 9449 4.2: a jti not used by any other proof; 11.1): DPoP proof jti used twice", // ---- Client assertions: private_key_jwt, addressed to the issuer (4.1) ---- - "client-assertion.alg": "Guides (Signing and verifying JWTs: sign client assertions with ES256, or PS384 when signing blindly; reject symmetric algorithms): Client assertion alg isn't ES256 or PS384", - "client-assertion.embedded-key": "Guides (Signing and verifying JWTs: verify only with keys from the verified jwks_uri; ignore jku, x5u and any embedded key): Client assertion embeds or points to a key (jku, x5u, jwk)", + "client-assertion.alg": "Guides (Signing and verifying JWTs: sign client assertions with ES256, or PS384 when signing blindly; reject symmetric algorithms; \"Sign client assertions and delegations with ES256, or with PS384 if you sign them blindly\"): Client assertion alg isn't ES256 or PS384", + "client-assertion.embedded-key": "Guides (Signing and verifying JWTs: verify only with keys from the verified jwks_uri; ignore jku, x5u and any embedded key; \"Ignore jku, x5u, and any other key embedded in a JWT\"): Client assertion embeds or points to a key (jku, x5u, jwk)", "client-assertion.typ": "Reading (S2; 4.1 names no typ), strict Company only: Client assertion header typ isn't \"JWT\"", "client-assertion.kid": "Reading (S2; Guides, Rotating keys: give every key a kid), strict Company only: Client assertion kid names no published key", "client-assertion.signature": "RFC (RFC 7523 3; 4.1: signed by a key from jwks_uri): Client assertion doesn't verify against the client's JWKS, or has expired", "client-assertion.iat-exp-missing": "MUST (4.1: \"MUST include iat\"; RFC 7523 3 requires exp): Client assertion without iat or exp", "client-assertion.lifetime": "Reading (S2: strict 60 s; 4.1: \"MUST make them short-lived\", and the Guides' five minutes is the lenient 300 s): Client assertion lifetime is too long", - "client-assertion.missing": "Rule (4.1, 4.2, 4.3, 4.4, 4.6: each token, device authorization and revocation request carries the client assertion): Token, device or revocation request without a client assertion", + "client-assertion.missing": "Rule (4.1, 4.2, 4.3, 4.4, 4.6: each token, device authorization and revocation request carries the client assertion; \"The Personal Agent authenticates at the token endpoint with a client assertion signed by a key from jwks_uri\"): Token, device or revocation request without a client assertion", "client-assertion.not-jwt": "RFC (RFC 7523 3; 4.1): Client assertion is not a JWT", "client-assertion.wrong-typ": "RFC (RFC 8725 3.11, which 5.2 cites: explicit typing keeps a Session JWT, delegation or DPoP proof from being taken for another JWT): A DPoP proof, Session JWT or delegation used as the client assertion", "client-assertion.aud-array": "MUST (4.1: \"aud MUST be the Company's issuer, as a single string\"): Client assertion aud is an array", - "client-assertion.aud": "MUST (4.1: aud MUST be the issuer; Companies MUST reject any other, including their token endpoint URL): Client assertion aud isn't this Company's issuer", + "client-assertion.aud": "MUST (4.1: aud MUST be the issuer; Companies MUST reject any other, including their token endpoint URL; \"The client assertion's aud MUST be the Company's issuer\"): Client assertion aud isn't this Company's issuer", "client-assertion.iss-sub": "RFC (RFC 7523 3, RFC 7521 5.2; 4.1: client assertions follow RFC 7523 3): Client assertion iss and sub aren't both the client_id", // ---- User IDs (5.1) ---- "user-id.personal": "MUST NOT (5.1: \"MUST NOT contain or be derived from personal information\"): User ID contains personal information", // ---- The client metadata document and JWKS (4.1, 5.3) ---- - "client-metadata.not-url": "MUST (4.1: client_id MUST be an HTTPS URL): client_id is not a URL", - "client-metadata.not-https": "MUST (4.1: client_id MUST be an HTTPS URL): client_id is not an https URL", - "client-metadata.fetch-status": "MUST (4.1: an HTTPS URL that returns its metadata document; 5.3, step 1: fetched without following redirects, as the CIMD draft requires): Fetching client_id didn't return 200 (redirects aren't followed)", - "client-metadata.not-json": "MUST (4.1: the URL returns its metadata document): Client metadata is not JSON", + "client-metadata.not-url": "MUST (4.1: \"client_id MUST be an HTTPS URL\"): client_id is not a URL", + "client-metadata.not-https": "MUST (4.1: \"client_id MUST be an HTTPS URL\"): client_id is not an https URL", + "client-metadata.fetch-status": "MUST (4.1: an HTTPS URL that returns its metadata document; 5.3, step 1: fetched without following redirects, as the CIMD draft requires; \"client_id MUST be an HTTPS URL that returns its metadata document\"): Fetching client_id didn't return 200 (redirects aren't followed)", + "client-metadata.not-json": "MUST (4.1: the URL returns its metadata document; \"client_id MUST be an HTTPS URL that returns its metadata document\"): Client metadata is not JSON", "client-metadata.client-id-mismatch": "MUST (4.1: \"client_id MUST equal the URL the document was fetched from\"): client_id in the document isn't the URL it was fetched from", - "client-metadata.jwks-uri": "MUST (4.1: jwks_uri MUST be HTTPS on the same domain as client_id, read as the same host): jwks_uri isn't https on the client_id domain", - "client-metadata.redirect-uris": "MUST (4.1: each redirect_uri HTTPS on the same domain as client_id, read as the same host, or a loopback redirect URI): A redirect_uri isn't https on the client_id domain or loopback", - "client-metadata.auth-method": "Rule (4.1: the Personal Agent authenticates with private_key_jwt): token_endpoint_auth_method isn't private_key_jwt", - "client-metadata.jwks-status": "Rule (4.1: jwks_uri holds the keys; 5.3, step 1 fetches them): jwks_uri didn't return 200", - "client-metadata.jwks-empty": "Rule (4.1: the keys that sign client assertions and delegations): The JWKS has no keys", + "client-metadata.jwks-uri": "MUST (4.1: jwks_uri MUST be HTTPS on the same domain as client_id, read as the same host; \"jwks_uri MUST be an HTTPS URL on the same domain as client_id\"): jwks_uri isn't https on the client_id domain", + "client-metadata.redirect-uris": "MUST (4.1: each redirect_uri HTTPS on the same domain as client_id, read as the same host, or a loopback redirect URI; \"Each entry MUST be an HTTPS URL on the same domain as client_id, or a loopback redirect URI\"): A redirect_uri isn't https on the client_id domain or loopback", + "client-metadata.auth-method": "Rule (4.1: the Personal Agent authenticates with private_key_jwt; \"The Personal Agent authenticates at the token endpoint with a client assertion signed by a key from jwks_uri (private_key_jwt, RFC 7523)\"): token_endpoint_auth_method isn't private_key_jwt", + "client-metadata.jwks-status": "Rule (4.1: jwks_uri holds the keys; 5.3, step 1 fetches them; \"Fetches the client metadata from iss … and the public keys from its jwks_uri\"): jwks_uri didn't return 200", + "client-metadata.jwks-empty": "Rule (4.1: the keys that sign client assertions and delegations; \"They sign client assertions, and the delegations that vouch for the keys that sign Session JWTs\"): The JWKS has no keys", "client-metadata.jwks-private": "Rule (4.1: \"The key set contains only public keys\"): The JWKS publishes a private key", "client-metadata.key-without-kid": "Guides (Rotating keys: \"Give every key in jwks_uri a kid\"): A JWKS key has no kid", @@ -110,11 +111,11 @@ export const VIOLATIONS = { "dpop.htu": "RFC (RFC 9449 4.2, 4.3; 4.5): DPoP proof htu isn't the request URL without query or fragment", "dpop.iat": "RFC (RFC 9449 4.3: iat within an acceptable window; 4.5): DPoP proof iat is outside the acceptance window", "dpop.ath": "RFC (RFC 9449 4.2, 4.3: ath is the hash of the access token; 4.5): DPoP proof ath isn't the hash of the token sent", - "dpop.nonce-ignored": "Guides (The Session header: support nonces as RFC 9449 8 describes; which server a nonce is for is S23): DPoP proof without the nonce this key already used at this server", + "dpop.nonce-ignored": "Guides (The Session header: support nonces as RFC 9449 8 describes; which server a nonce is for is S23; \"support nonces as RFC 9449 §8 describes\"): DPoP proof without the nonce this key already used at this server", "dpop.key-mismatch": "RFC (RFC 9449 4.3, 7.1: the proof's key is the one the token is bound to; 4.5): DPoP proof key isn't the key the token is bound to", // ---- Access tokens at resources (4.5, 7) ---- - "resource.bearer-scheme": "Rule (4.5: the scheme the token response's token_type names; RFC 9449 7.1): An access token sent with another scheme than its token_type", + "resource.bearer-scheme": "Rule (4.5: the scheme the token response's token_type names; RFC 9449 7.1; \"A signed-in request carries an access token in the Authorization header, with the scheme the token response's token_type names\"): An access token sent with another scheme than its token_type", "resource.unverified-target": "MUST (RFC 9728 3.3, which 4.5 names: metadata whose resource isn't the identifier its URL was derived from \"MUST NOT be used\"): A token request for a resource that no protected resource metadata at its own derived URL names", "mcp.wrong-token": "MUST (7: \"MUST request a token with resource set to the MCP server's url\"; 4.5): MCP request with a token not issued for this MCP server", "mcp.accept": "RFC (MCP 2025-06-18 Streamable HTTP, which 7 names): MCP request doesn't Accept application/json and text/event-stream", @@ -133,33 +134,33 @@ export const VIOLATIONS = { // ---- Rate limits and secrets (5.6, 10.2; Mediated Sign-In 6; Guides) ---- "rate-limit.retry-after-ignored": "MUST (5.6: \"MUST wait at least that long before sending the request again\"): Request sent again before its Retry-After elapsed", - "rate-limit.shared-limit-ignored": "Guides (Rate limits: keep track of limits for each company and share them across your tasks and users; 5.6's MUST covers only the request sent again): A different request sent to the Company before an earlier Retry-After elapsed", + "rate-limit.shared-limit-ignored": "Guides (Rate limits: keep track of limits for each company and share them across your tasks and users; 5.6's MUST covers only the request sent again; \"keep track of limits for each company and share them across your tasks and users\"): A different request sent to the Company before an earlier Retry-After elapsed", "secret.password": "MUST NOT (Mediated Sign-In 6: \"MUST NOT send credentials anywhere other than the token_endpoint of the Company's issuer\"): A password sent anywhere but the token endpoint's body", - "secret.one-time-code": "Guides (Handling secrets: keep one-time sign-in codes out of messages and URLs; Mediated Sign-In 4 sends the code to the token endpoint): A one-time code sent anywhere but the token endpoint's body", - "secret.account-token": "Guides (Handling secrets: keep tokens out of messages, logs and URLs; 4.4 and 4.6 send a refresh token only to the token and revocation endpoints): A refresh token sent anywhere but the token and revocation bodies", + "secret.one-time-code": "Guides (Handling secrets: keep one-time sign-in codes out of messages and URLs; Mediated Sign-In 4 sends the code to the token endpoint; \"Keep them out of logs, telemetry, error reports, model context, conversation messages, and URLs\"): A one-time code sent anywhere but the token endpoint's body", + "secret.account-token": "Guides (Handling secrets: keep tokens out of messages, logs and URLs; 4.4 and 4.6 send a refresh token only to the token and revocation endpoints; \"Keep them out of logs, telemetry, error reports, model context, conversation messages, and URLs\"): A refresh token sent anywhere but the token and revocation bodies", "secret.token-in-url": "MUST NOT (5.6: \"MUST NOT send tokens or Session JWTs in a URL\"): A token sent in a URL", // ---- Token endpoint and refresh tokens (4.4, 4.6) ---- "form.not-form": "RFC (RFC 6749 4.1.3, RFC 7009 2.1, RFC 8628 3.1): OAuth request body isn't application/x-www-form-urlencoded", "account-token.other-client": "RFC (RFC 6749 6: a refresh token is bound to the client it was issued to; 4.4): Refresh token used by a different client_id", - "account-token.rotated-reused": "MUST (4.4: \"The Personal Agent then MUST use the new one from then on\"): Refresh token used after the Company rotated it", + "account-token.rotated-reused": "RFC (RFC 6749 6; 4.4: \"Refresh token rotation follows RFC 6749 §6\", which says the client MUST discard the old one): Refresh token used after the Company rotated it", // ---- Sign-in (4.2, 4.3, 4.7; Mediated Sign-In 3, 4) ---- "signin.no-scope": "MUST (4.7: \"Each sign-in request MUST include scope\"): Sign-in request without scope", "authorize.redirect-uri": "MUST (4.2: \"redirect_uri MUST exactly match an entry\" in redirect_uris, but a loopback port): redirect_uri isn't exactly a registered redirect_uri", - "authorize.no-state": "Guides (Direct and device sign-in: make state random and single-use, and record which company it belongs to; 4.2 relies on PKCE): Authorization request without state", - "authorize.no-pkce": "Rule (4.2: the authorization code grant with PKCE; Guides: S256): Authorization request without PKCE S256", - "authorize.secret-in-url": "MUST NOT (5.6 for tokens; Guides, Handling secrets, for assertions): A token or assertion in the authorization URL", + "authorize.no-state": "Guides (Direct and device sign-in: make state random and single-use, and record which company it belongs to; 4.2 relies on PKCE; \"Make state random and single-use\"): Authorization request without state", + "authorize.no-pkce": "Rule (4.2: the authorization code grant with PKCE; Guides: S256; \"Direct Sign-In is the OAuth 2.0 authorization code grant with PKCE\"): Authorization request without PKCE S256", + "authorize.secret-in-url": "MUST NOT (5.6 for tokens; Guides, Handling secrets, for assertions; \"Personal Agents MUST NOT send tokens or Session JWTs in a URL\"): A token or assertion in the authorization URL", "code.reused": "RFC (RFC 6749 4.1.2; 4.2): Authorization code exchanged twice", "code.redirect-uri": "RFC (RFC 6749 4.1.3; 4.2): redirect_uri at the token endpoint differs from the authorization request", "code.pkce": "RFC (RFC 7636 4.5, 4.6; 4.2): PKCE code_verifier doesn't match the code_challenge", "authorize.prompt-consent": "MUST (1.0 4.2: \"Unless the Personal Agent receives the redirect only on the device that opened the authorization URL, as below, the authorization request MUST include prompt=consent\"; read as a loopback redirect URI): A 1.x Direct Sign-In request without prompt=consent", "par.not-pushed": "MUST (1.0 4.2: with require_pushed_authorization_requests, \"The Personal Agent then MUST send the authorization request's parameters to the pushed_authorization_request_endpoint\"; RFC 9126 5 under 0.4): An authorization request sent in the URL to a Company that accepts only pushed ones", - "par.extra-parameters": "MUST (1.0 4.2: the Personal Agent opens \"the authorization_endpoint with only client_id and the request_uri it gets back\"): The authorization URL for a pushed request carries other parameters", + "par.extra-parameters": "MUST (1.0 4.2: with require_pushed_authorization_requests, \"The Personal Agent then MUST send the authorization request's parameters to the pushed_authorization_request_endpoint with its client assertion, and open the authorization_endpoint with only client_id and the request_uri it gets back\"): The authorization URL for a pushed request carries other parameters", "par.code-key": "RFC (RFC 9449 10.1; 1.0 4.2: a proof sent with the pushed request binds the code to its key): A code from a request pushed with a DPoP proof, exchanged with no proof or one from another key", "dpop.refresh-key-changed": "MUST (1.0 4.4: \"MUST send a proof from the same key with every refresh of that refresh token, and of the refresh tokens that replace it\"): A refresh with no DPoP proof, or one from another key than the refresh token was issued with", - "device.polled-after-final": "Rule (4.3: polls until the User approves or declines, as RFC 8628 3.4 and 3.5 describe): Device polling continued after completion or access_denied", - "device.polled-after-expiry": "Rule (4.3: polls until the request expires, as RFC 8628 3.5 describes): Device polling continued after expired_token", + "device.polled-after-final": "Rule (4.3: polls until the User approves or declines, as RFC 8628 3.4 and 3.5 describe; \"polls the token_endpoint every interval seconds until the User approves or declines\"): Device polling continued after completion or access_denied", + "device.polled-after-expiry": "Rule (4.3: polls until the request expires, as RFC 8628 3.5 describes; \"the Personal Agent polls the token_endpoint every interval seconds until the User approves or declines, or the request expires\"): Device polling continued after expired_token", "device.too-fast": "RFC (RFC 8628 3.5: add 5 seconds to the interval on slow_down; 4.3): Device polling faster than the interval after slow_down", "mediated.missing-field": "Rule (Mediated Sign-In 3: \"every field in fields as a parameter\"): Mediated Sign-In without a field the Company asked for", "mediated.credentials-with-code": "Rule (Mediated Sign-In 4: the code goes with sign_in_id, \"but not the credentials or scope\"): Credentials resent with the one-time code", @@ -167,77 +168,77 @@ export const VIOLATIONS = { "mediated.code-other-client": "Rule (Mediated Sign-In 4: \"Only the client_id that started a sign-in can finish it\"): A one-time code sent by another client", // ---- Writes and retries (Guides; Ops 7) ---- - "idempotency.key-reused": "Guides (Retries: reuse an Idempotency-Key only to retry the same request; companies reject a repeated key with a different body): Idempotency-Key reused with a different body", - "idempotency.key-missing": "Guides (Retries: \"Send an Idempotency-Key on API writes that accept one\"): An API write whose description takes an Idempotency-Key sent without one", + "idempotency.key-reused": "Guides (Retries: reuse an Idempotency-Key only to retry the same request; companies reject a repeated key with a different body; \"reuse the same key when you retry the same request … reject a repeated key with a different body\"): Idempotency-Key reused with a different body", + "idempotency.key-missing": "Guides (Retries: \"Send an Idempotency-Key … on API writes that accept one\"): An API write whose description takes an Idempotency-Key sent without one", "upload.boundary": "RFC (RFC 7578 4.1; RFC 2046 5.1.1): A multipart/form-data body without a boundary parameter", "upload.part-name": "RFC (RFC 7578 4.2): A multipart/form-data part without a Content-Disposition of form-data with a name", - "exchange.performed-twice": "Guides (Retries: reuse the Idempotency-Key when retrying; Ops 7: at most once): The same exchange made twice (a write retried without its key, or approved again as a new operation)", + "exchange.performed-twice": "Guides (Retries: reuse the Idempotency-Key when retrying; Ops 7: at most once; \"reuse the same key when you retry the same request\"): The same exchange made twice (a write retried without its key, or approved again as a new operation)", // ---- Conversations (8) ---- - "message.missing": "Rule (8.3: a request carries its message): Conversation request without a message", + "message.missing": "Rule (8.3: a request carries its message; \"A new conversation starts with its first message, except when accepting a user_requested event without a message\"): Conversation request without a message", "message.empty": "MUST (8.4: \"MUST have at least one of text, data, context, or extensions\"): Message has none of text, data, context or extensions", - "message.extension-unlisted": "MUST NOT (8.4: \"A side MUST NOT send an extension's content unless the other side lists that extension with the same version\"): Extension content for an extension the Company doesn't list", - "message.text-type": "Rule (8.4: text is the message in natural language): Message text isn't a string", - "message.json-in-text": "Guides (Conversations: put structured details in data, not JSON or other markup in text; 8.4 says the same without a keyword): JSON in a message's text", - "message.data-type": "Rule (8.4: data is a JSON object): Message data isn't a JSON object", - "message.context-type": "Rule (8.4: context holds facts about the User's situation, as fields): Message context isn't an object", - "request.id": "MUST (8.3: \"Every POST body has an id\"; 8.2: 1 to 256 URL-safe base64 characters): A conversation request without a valid request id", + "message.extension-unlisted": "MUST NOT (8.4: \"A side MUST NOT send an extension's content unless the other side uses that extension with the same version\"): Extension content for an extension the Company doesn't list", + "message.text-type": "Rule (8.4: text is the message in natural language; \"text | No | The message in natural language.\"): Message text isn't a string", + "message.json-in-text": "Guides (Conversations: put structured details in data, not JSON or other markup in text; 8.4 says the same without a keyword; \"Put structured details in data, not JSON or other markup in text\"): JSON in a message's text", + "message.data-type": "Rule (8.4: data is a JSON object; \"A JSON object for structured details that would need markup, like a list or a table, to fit in a sentence.\"): Message data isn't a JSON object", + "message.context-type": "Rule (8.4: context holds facts about the User's situation, as fields; \"context holds facts about the User's situation that affect how the Company replies\"): Message context isn't an object", + "request.id": "MUST (8.3: \"Every POST body has an id, chosen by the Personal Agent, which MUST make it unique for the User across all its requests\"; 8.2: 1 to 256 URL-safe base64 characters): A conversation request without a valid request id", "message.as-of-human": "MUST NOT (8.4: a message \"with author.type human, MUST NOT include either field\"): as_of_cursor on a message the User wrote", "message.as-of-cursor": "Rule (8.4: as_of_cursor is \"the cursor of the last read it had handled\"): as_of_cursor that isn't a cursor of the conversation", - "request.id-reused": "MUST (8.3: the request ID is \"unique for the User across all its requests\"; a retry repeats the path and body): A request id reused with a different path or body", + "request.id-reused": "MUST (8.3: the Personal Agent \"MUST make it unique for the User across all its requests\"; a retry repeats the path and body): A request id reused with a different path or body", "context.locale": "MUST (8.4: \"it MUST use the field and format defined here\", an RFC 5646 tag): context.locale isn't an RFC 5646 tag", - "context.time-zone": "MUST (8.4: the field and format defined here, an IANA time zone name): context.time_zone isn't an IANA name", - "context.user-available": "MUST (8.4: the field and format defined here, true or false): context.user_available isn't a boolean", + "context.time-zone": "MUST (8.4: the field and format defined here, an IANA time zone name; \"When a Personal Agent shares one of these facts, it MUST use the field and format defined here\"): context.time_zone isn't an IANA name", + "context.user-available": "MUST (8.4: the field and format defined here, true or false; \"When a Personal Agent shares one of these facts, it MUST use the field and format defined here\"): context.user_available isn't a boolean", "direct.agent-words": "Reading (S12; 8.10: the User's messages, as written, with author.type human): Direct Conversation opened with words not marked as the User's", "direct.agent-words-later": "Reading (S12; 8.10): The agent's own words sent into an open Direct Conversation", - "conversation.cross-user": "Rule (8.2: a conversation belongs to the client_id and User ID that started it; 8.13; S17): A conversation of one User reached by another User of the same agent", - "handoff.body": "Rule (8.9: \"with an empty JSON object\"): Handoff body isn't {}", - "close.body": "Rule (8.12: \"by sending an empty JSON object\"): Close body isn't {}", - "message.author": "MUST (8.4: author is required, with type agent or human, and only Company messages have id, name or image; 8.8): A message without a valid author", + "conversation.cross-user": "Rule (8.2: a conversation belongs to the client_id and User ID that started it; 8.13; S17; \"A conversation belongs to the Personal Agent's client_id and the User ID that started it\"): A conversation of one User reached by another User of the same agent", + "handoff.body": "Rule (8.9: \"The Personal Agent asks for a person at the Company with a request ID\"): A handoff or cancel body with more than its request id", + "close.body": "Rule (8.12: \"The Personal Agent closes a conversation it's done with by sending a request ID to its close URL\"): A close body with more than its request id", + "message.author": "MUST (8.4: author is required, with type agent or human, and only Company messages have id, name or image; 8.8; \"the Personal Agent MUST set each message's author.type: agent when the Personal Agent wrote it, and human only when it carries the User's own words\"): A message without a valid author", "message.sender-field": "Reading (8.4 has author where 0.2 had sender; docs/readings.md): A message that still carries sender", // ---- The Session header (5.2, 5.3) ---- - "version.missing": "MUST (3.4: \"On every request with the Session header, the Personal Agent sends the protocol version it implements ... in Poppy-Version\"): A Session request without Poppy-Version to a Company that never served 0.3", + "version.missing": "Rule (3.4: \"On every request with the Session header (5.2), the Personal Agent sends the protocol version it implements, compatible with the chosen one, in Poppy-Version\"): A Session request without Poppy-Version", "version.unlisted": "MUST (3.4: the Personal Agent \"chooses the newest version, among protocol_version and the versions in supported_versions\", and \"If none is, it MUST NOT use any of them\"): Poppy-Version naming a version the Company never listed", "version.changed-in-session": "MUST (3.4: \"MUST send the same values on every request in a Session, and starts a new Session to change them\"): A Session whose Poppy-Version or Poppy-Extensions changed", "session-jwt.missing": "MUST (5.2: \"MUST send a Poppy-Session header on every request\" to APIs, conversations and protocol endpoints): A request to a resource without the Session header", - "session-jwt.missing-with-token": "MUST (5.2; 5.3: the Company MUST reject an access token without the Session header): An access token sent without the Session header", - "session-jwt.not-jwt": "MUST (5.2: the header holds a JWT): The Session header isn't a JWT", + "session-jwt.missing-with-token": "MUST (5.2; 5.3: the Company MUST reject an access token without the Session header; \"The Personal Agent MUST send a Poppy-Session header on every request to a Company's APIs, conversations, and other resource endpoints this protocol or an extension defines\"): An access token sent without the Session header", + "session-jwt.not-jwt": "Rule (5.2: the header holds a JWT; \"The header holds a JWT that the Personal Agent signs for that one request\"): The Session header isn't a JWT", "session-jwt.typ": "MUST (5.2: \"typ MUST be poppy-session+jwt\"): A Session JWT of another typ", "session-jwt.alg": "MUST (5.2: \"alg MUST be ES256\"): A Session JWT not signed with ES256", "operator-signature.invalid": "RFC (RFC 9421 3.2; Web Bot Auth 5.2; 5.3): An operator signature that is malformed, outside its validity, not in the operator's directory, or doesn't verify", "operator-signature.components": "MUST (5.3: \"The Personal Agent's operator signature MUST cover poppy-session, and authorization when present\"): An operator signature that leaves out the Session header or the access token", - "session-jwt.no-delegation": "MUST (5.2 Delegated keys: the Company MUST reject a Session JWT without a delegation): A Session JWT without poppy_dlg", + "session-jwt.no-delegation": "MUST (5.2 Delegated keys: the Company MUST reject a Session JWT without a delegation; \"the Company MUST reject, with invalid_session, a Session JWT without a delegation\"): A Session JWT without poppy_dlg", "session-jwt.iss": "MUST (5.2: \"MUST include every claim except agent_id\", and ath without a token): A Session JWT without iss", - "session-jwt.kid": "MUST (5.2 Delegated keys, step 3: kid is the delegated key's RFC 7638 thumbprint; 5.3: the Company MUST complete these checks): A Session JWT whose kid isn't its key's thumbprint", - "session-jwt.signature": "MUST (5.2 Delegated keys, step 3: verified with the key in cnf.jwk; 5.3): A Session JWT that doesn't verify with the delegated key", - "session-jwt.iat": "MUST (5.2: iat is required; 5.3: within the Company's acceptance window): A Session JWT without iat, or outside the acceptance window", + "session-jwt.kid": "MUST (5.2 Delegated keys, step 3: kid is the delegated key's RFC 7638 thumbprint; 5.3: the Company MUST complete these checks; \"The Company MUST complete the following checks before relying on Session claims\"): A Session JWT whose kid isn't its key's thumbprint", + "session-jwt.signature": "MUST (5.2 Delegated keys, step 3: verified with the key in cnf.jwk; 5.3; \"The Company MUST complete the following checks before relying on Session claims\"): A Session JWT that doesn't verify with the delegated key", + "session-jwt.iat": "MUST (5.2: iat is required; 5.3: within the Company's acceptance window; \"The Personal Agent MUST include every claim except agent_id\"): A Session JWT without iat, or outside the acceptance window", "session-jwt.after-delegation": "MUST NOT (5.2 Delegated keys: \"MUST NOT sign a Session JWT after its delegation's exp\"): A Session JWT signed after its delegation expired", - "session-jwt.aud": "MUST (5.2: aud is the issuer as a single string; 5.3: compared character for character): A Session JWT for another audience", - "session-jwt.htm": "MUST (5.2, 5.3: htm matches the request as RFC 9449 4.3 describes): A Session JWT whose htm isn't the request's method", - "session-jwt.htu": "MUST (5.2, 5.3: htu is the URL without query or fragment, as RFC 9449 4.3 describes): A Session JWT whose htu isn't the request's URL without its query", - "session-jwt.sid": "MUST (5.2: sid is required, with the characters of Conversation IDs): A Session JWT without a valid sid", - "session-jwt.sub": "MUST (5.2: sub is the User ID and required; agent_id a string when present): A Session JWT without sub, or with a malformed agent_id", - "session-jwt.ath": "MUST (5.2: ath is the access token's hash; 5.3, step 3): A Session JWT whose ath doesn't match the access token", - "session-jwt.oauth-endpoint": "Rule (5.2: the Session header \"isn't sent to the Company's OAuth endpoints or website pages\"): A Poppy-Session header sent to the token, device or revocation endpoint", + "session-jwt.aud": "MUST (5.2: aud is the issuer as a single string; 5.3: compared character for character; \"The Company MUST complete the following checks before relying on Session claims\"): A Session JWT for another audience", + "session-jwt.htm": "MUST (5.2, 5.3: htm matches the request as RFC 9449 4.3 describes; \"The Company MUST complete the following checks before relying on Session claims\"): A Session JWT whose htm isn't the request's method", + "session-jwt.htu": "MUST (5.2, 5.3: htu is the URL without query or fragment, as RFC 9449 4.3 describes; \"The Company MUST complete the following checks before relying on Session claims\"): A Session JWT whose htu isn't the request's URL without its query", + "session-jwt.sid": "MUST (5.2: sid is required, with the characters of Conversation IDs; \"The Personal Agent MUST include every claim except agent_id\"): A Session JWT without a valid sid", + "session-jwt.sub": "MUST (5.2: sub is the User ID and required; agent_id a string when present; \"The Personal Agent MUST include every claim except agent_id\"): A Session JWT without sub, or with a malformed agent_id", + "session-jwt.ath": "MUST (5.2: ath is the access token's hash; 5.3, step 3; \"The Company MUST complete the following checks before relying on Session claims\"): A Session JWT whose ath doesn't match the access token", + "session-jwt.oauth-endpoint": "Rule (5.2: \"Discovery and description documents and OAuth endpoints don't carry this header\"): A Poppy-Session header sent to the token, device or revocation endpoint", "session-jwt.ath-without-token": "MUST (5.3, step 3: \"Without an access token, ath MUST be absent\"): A Session JWT with ath and no access token", - "session-jwt.sub-changed": "MUST (5.2: \"MUST send the same sub and agent_id in every Session JWT for a Session\"; 5.3, step 4): A Session's sid sent with another User ID or Agent ID", - "session-jwt.token-other-client": "MUST (5.3, step 3: the token was issued to the same client_id as iss): An access token sent by another client", + "session-jwt.sub-changed": "MUST (5.2: sid \"MUST NOT use it for any other Session\"; \"It MUST send the same sub and agent_id, or no agent_id, in every Session JWT for a Session\"): A Session's sid sent with another User ID or Agent ID", + "session-jwt.token-other-client": "MUST (5.3, step 3: the token was issued to the same client_id as iss; \"The Company MUST complete the following checks before relying on Session claims\"): An access token sent by another client", "session-jwt.jti-missing": "MUST (5.2: \"MUST include every claim except agent_id\"): A Session JWT without a jti", - "session-jwt.jti-weak": "Guides (Signing and verifying JWTs: a jti of at least 128 random bits; 5.2 asks only that it be unguessable): A Session JWT jti that isn't 128 random bits of base64url", + "session-jwt.jti-weak": "Guides (Signing and verifying JWTs: a jti of at least 128 random bits; 5.2 asks only that it be unguessable; \"Make the jti of each client assertion, delegation, Session JWT, and DPoP proof at least 128 random bits\"): A Session JWT jti that isn't 128 random bits of base64url", "session-jwt.jti-reused": "Rule (5.2: \"jti is unique and unguessable\"; 5.3: a Company MAY reject a reused jti): A Session JWT jti used twice", // ---- Delegations (5.2 Delegated keys) ---- - "delegation.not-jwt": "MUST (5.2 Delegated keys: poppy_dlg is the delegation in compact form, and the Company MUST reject one that fails its checks): poppy_dlg isn't a JWT", + "delegation.not-jwt": "MUST (5.2 Delegated keys: poppy_dlg is the delegation in compact form, and the Company MUST reject one that fails its checks; \"the Company MUST reject, with invalid_session, … a Session JWT whose delegation fails any of these checks\"): poppy_dlg isn't a JWT", "delegation.typ": "MUST (5.2 Delegated keys: \"typ MUST be poppy-delegation+jwt\"): A delegation of another typ", "delegation.alg": "Rule (5.2 Delegated keys: \"alg is ES256 or PS384\"): A delegation signed with another algorithm", - "delegation.kid": "MUST (5.2 Delegated keys, step 1: kid names the key in jwks_uri; the Company MUST reject a delegation that fails a check): A delegation whose kid names no published key", - "delegation.signature": "MUST (5.2 Delegated keys, step 1): A delegation that doesn't verify with the key its kid names", - "delegation.iss": "MUST (5.2 Delegated keys, step 2: its iss is the token's iss): A delegation from another client", + "delegation.kid": "MUST (5.2 Delegated keys, step 1: kid names the key in jwks_uri; the Company MUST reject a delegation that fails a check; \"the Company MUST reject, with invalid_session, … a Session JWT whose delegation fails any of these checks\"): A delegation whose kid names no published key", + "delegation.signature": "MUST (5.2 Delegated keys, step 1; \"the Company MUST reject, with invalid_session, … a Session JWT whose delegation fails any of these checks\"): A delegation that doesn't verify with the key its kid names", + "delegation.iss": "MUST (5.2 Delegated keys, step 2: its iss is the token's iss; \"the Company MUST reject, with invalid_session, … a Session JWT whose delegation fails any of these checks\"): A delegation from another client", "delegation.lifetime": "MUST (5.2 Delegated keys: \"exp MUST be at most 24 hours after iat\"; step 2): A delegation without iat and exp, or longer than a day", - "delegation.expired": "MUST (5.2 Delegated keys, step 2: it hasn't expired): A Session JWT carrying an expired delegation", + "delegation.expired": "MUST (5.2 Delegated keys, step 2: it hasn't expired; \"the Company MUST reject, with invalid_session, … a Session JWT whose delegation fails any of these checks\"): A Session JWT carrying an expired delegation", "delegation.jti": "Rule (5.2 Delegated keys: \"jti is a unique, unguessable ID\"; Guides: 128 random bits): A delegation without a jti of 128 random bits", - "delegation.cnf": "MUST (5.2 Delegated keys, step 3: the Session JWT is verified with the key in cnf.jwk): A delegation without cnf.jwk", + "delegation.cnf": "MUST (5.2 Delegated keys, step 3: the Session JWT is verified with the key in cnf.jwk; \"the Company MUST reject, with invalid_session, … a Session JWT whose delegation fails any of these checks\"): A delegation without cnf.jwk", "delegation.private-key": "MUST NOT (5.2 Delegated keys: \"It MUST NOT contain private key members\"): A delegation that carries a private key", "delegation.names-user": "MUST NOT (5.2 Delegated keys: \"MUST NOT put a User ID, an Agent ID, a Company's issuer, or anything else about the User\"): A delegation with claims beyond iss, cnf, iat, exp and jti", "delegation.key-shared": "MUST (5.2: \"MUST use each delegated key, and its delegation, for one User ID only\"): A delegated key that signed for two User IDs", @@ -247,11 +248,11 @@ export const VIOLATIONS = { "token.dpop-not-sent": "SHOULD (4.5: \"Personal Agents SHOULD support DPoP\", and one that does sends a proof when the metadata lists dpop_signing_alg_values_supported): A token request without a DPoP proof at an issuer that asks for one", // ---- Browser join (6) ---- - "browser-join.form": "Rule (6, step 3: the browser submits the form, whose one field is code): The join form not submitted as a form, or with other fields", - "browser-join.code-reused": "MUST (6, step 1: \"each code works once\"; steps 2 and 3: not authorized or submitted before): A join code authorized or submitted twice", - "browser-join.cookie": "MUST (6, step 3: the Company MUST check \"The request has the cookie from step 1\"): A join form submitted without the cookie set with its code", - "browser-join.not-authorized": "MUST (6, step 3: the Company MUST check \"The code was authorized in step 2\"): A join form submitted before the agent authorized its code", - "browser-join.authorize-body": "Rule (6, step 2: a JSON body with the code): An authorize request without the code as JSON", + "browser-join.form": "Rule (6, step 3: the browser submits the form, whose one field is code; \"The Personal Agent has its browser submit the form\"): The join form not submitted as a form, or with other fields", + "browser-join.code-reused": "MUST (6, step 1: \"The Company MUST make the code unguessable and short-lived, and each code works once\"; steps 2 and 3: not authorized or submitted before): A join code authorized or submitted twice", + "browser-join.cookie": "MUST (6, step 3: \"The Company MUST check that:\" \"The request has the cookie from step 1, and it matches code\"): A join form submitted without the cookie set with its code", + "browser-join.not-authorized": "MUST (6, step 3: \"The Company MUST check that:\" \"The code was authorized in step 2\"): A join form submitted before the agent authorized its code", + "browser-join.authorize-body": "Rule (6, step 2: a JSON body with the code; \"The Personal Agent reads the code from the page in its browser and sends it to {browser_session_endpoint}/authorize\"): An authorize request without the code as JSON", "page.session-off-host": "Rule (5.2: the header \"covers only HTTPS URLs whose host is exactly organization.domain\", and a redirect is signed again \"only if its host is still organization.domain\"): A Session header on a page on another host", "page.token": "MUST NOT (5.2: \"MUST NOT send an access token with these requests\"): An access token with a website page", "browser-sign-in.no-endpoint": "Rule (6: \"A Personal Agent requests poppy:browser-sign-in only from a Company that lists browser_session_endpoint\"): A sign-in asking for poppy:browser-sign-in from a Company without browser join", @@ -260,9 +261,9 @@ export const VIOLATIONS = { // ---- Operations extension, version 3 (Ops 6) ---- "approval.header": "RFC (Ops 6: a Dictionary Structured Field, RFC 9651, with operation_id and revision as Strings): A malformed Poppy-Approval", - "approval.idempotency-key-reused": "Rule (Ops 6: \"An Idempotency-Key sent with the first request doesn't carry over\"): The approved request reused the first request's Idempotency-Key", - "approval.mcp-meta": "Rule (Ops 6: the approval as a JSON object in _meta under personalagentprotocol.org/approval): A malformed MCP approval", - "approval.message": "Rule (Ops 6: the approval as a JSON object in the message's approval): A malformed approval in a message", + "approval.idempotency-key-reused": "Rule (Ops 6: an Idempotency-Key \"sent with the first request doesn't carry over: the request with the approval has its own, or none\"): The approved request reused the first request's Idempotency-Key", + "approval.mcp-meta": "Rule (Ops 6: the approval as a JSON object in _meta under personalagentprotocol.org/approval; \"The Personal Agent calls the same tool again, with the same arguments, and the approval as a JSON object in _meta under personalagentprotocol.org/approval\"): A malformed MCP approval", + "approval.message": "Rule (Ops 6: the approval as a JSON object in the message's approval; \"The Personal Agent sends a message with the approval as a JSON object in extensions.operations.approval\"): A malformed approval in a message", "approval.approver": "MUST (Ops 6: \"The Personal Agent MUST include approver\", user or agent): An Operations 3 approval without a valid approver", "approval.approved-at": "Rule (Ops 6: \"approved_at, in Unix seconds\", an Integer in Poppy-Approval): approved_at that isn't an Integer", "approval.input-type-with-agent": "MUST NOT (Ops 6: \"The Personal Agent MUST NOT include it with agent\"): input_type in an agent approval", @@ -277,12 +278,12 @@ export const VIOLATIONS = { "approval.agent-after-revision": "MUST NOT (Ops 5: \"the Personal Agent MUST NOT approve the new one on the same instruction\"): An agent approval of a revision that answered an agent approval", // ---- Feedback (9.3) ---- - "skills.credentials": "Rule (9.4: listing an artifact \"does not authorize sending it credentials or Session headers\"): A skill artifact fetched with a token or Session header", + "skills.credentials": "Rule (9.4: listing an artifact on another domain \"does not make that domain an API endpoint or authorize sending it credentials or Session headers\"): A skill artifact fetched with a token or Session header", "tasks.token": "Rule (9: \"the request carries no access token, even in a signed-in Session\"): GET {tasks.endpoint} with an access token", - "feedback.fields": "MUST (9.3: task and description are required, at most 200 and 2,000 characters): A malformed feedback report", + "feedback.fields": "Rule (9.3: task and description are required, at most 200 and 2,000 characters; \"invalid_request (400) for a report that is malformed or too long\"): A malformed feedback report", "feedback.kind": "Reading (9.3 has no kind; the changelog: \"kind removed from feedback\"): A feedback report that still carries kind", "feedback.excluded-task": "SHOULD NOT (9.3: \"SHOULD NOT report a task the Company lists as excluded\"): A report about an excluded task", - "feedback.repeated": "SHOULD (9.3: \"one report for each task it couldn't do, not one for each attempt\"): A second report about the same task" + "feedback.repeated": "SHOULD (9.3: \"A Personal Agent SHOULD send one report for each task it couldn't do, not one for each attempt\"): A second report about the same task" } as const; export type ViolationId = keyof typeof VIOLATIONS; diff --git a/test/properties/jwt.test.ts b/test/properties/jwt.test.ts index 559e9af1..e0663c29 100644 --- a/test/properties/jwt.test.ts +++ b/test/properties/jwt.test.ts @@ -205,8 +205,8 @@ for (const alg of ["ES256", "RS256"] as const) { }); } -/** Client assertions: Companies MUST accept ES256 and PS384 (4.1), and the Guides add RS256. */ -for (const alg of ["ES256", "PS384", "RS256"] as const) { +/** Client assertions: Companies MUST accept ES256 and PS384 (4.1). */ +for (const alg of ["ES256", "PS384"] as const) { const pair = await generateKeyPair(alg, { extractable: true }); const other = await generateKeyPair(alg); const kid = `accepted-${alg}`; @@ -345,7 +345,7 @@ const assertionMutations = (company: Company) => // A kid that names no published key: strict Companies say so; lenient ones find no key to verify with. gs.text({ minSize: 1, maxSize: 10 }).filter((kid) => !realKids.includes(kid)).map((kid) => ({ name: "kid", mutation: { header: { kid } }, violation: "client-assertion.kid", lenient: "client-assertion.signature" })), gs.just({ name: "no kid", mutation: { header: { kid: undefined } }, violation: "client-assertion.kid", strictOnly: true }), - ...algMutations(["ES256", "PS384", "RS256"], (name, mutation) => ({ name, mutation, violation: "client-assertion.alg" })), + ...algMutations(["ES256", "PS384"], (name, mutation) => ({ name, mutation, violation: "client-assertion.alg" })), gs.sampledFrom(["jwk", "jku", "x5u"]).map((member) => ({ name: `embedded ${member}`, mutation: { header: { [member]: member === "jwk" ? strangerJwk : "https://keys.attacker.example/jwks.json" } }, diff --git a/test/validator.test.ts b/test/validator.test.ts index e5065506..5b664e12 100644 --- a/test/validator.test.ts +++ b/test/validator.test.ts @@ -1026,21 +1026,36 @@ const METADATA: readonly Fixture[] = [ outcome: "invalid" }, { - // 4.7: described in an OpenAPI description poppy.json lists, or otherwise in auth.scopes. - name: "requires auth.scopes to describe each supported scope when no OpenAPI description could", + // 4.7: SHOULD be described in an OpenAPI description poppy.json lists, or otherwise in auth.scopes. + name: "recommends auth.scopes describe each supported scope when no OpenAPI description could", run: () => company({ poppy: (doc) => { doc.apis = doc.apis.filter((api: { type: string }) => api.type !== "openapi"); }, metadata: (doc) => { doc.scopes_supported.push("loyalty"); } }), ids: ["scope-undescribed"], - outcome: "invalid", + outcome: "valid", also: async (report) => { - expect(report.messages[0]!.pointer).toBe("/scopes_supported/4"); + expect(report.messages[0]).toMatchObject({ severity: "warning", document: "oauth-metadata", pointer: "/scopes_supported/4" }); // With an OpenAPI description listed, it may describe the scope: nothing to say. expect((await company({ metadata: (doc) => { doc.scopes_supported.push("loyalty"); } })).messages).toEqual([]); } }, + { + // Readings: the domain's own scopes_supported names the scopes it offers; the issuer's may serve other clients (3.2). + name: "checks the domain's scopes, not the issuer's others, when the protected resource metadata lists them", + run: () => + company({ + poppy: (doc) => { doc.apis = doc.apis.filter((api: { type: string }) => api.type !== "openapi"); }, + prm: { ...SPEC_PRM, scopes_supported: ["orders:read", "orders:write", "loyalty"] }, + metadata: (doc) => { doc.scopes_supported.push("openid", "profile", "offline_access"); } + }), + ids: ["scope-undescribed"], + outcome: "valid", + also: (report) => { + expect(report.messages[0]).toMatchObject({ severity: "warning", document: "protected-resource", pointer: "/scopes_supported/2" }); + } + }, { name: "notes what agents can't use in the advertised capabilities", run: () => From 8e65023970924ba3b20bf302f3e8381e1d3e6069 Mon Sep 17 00:00:00 2001 From: Ade Oshineye Date: Fri, 13 Nov 2026 17:49:36 +0000 Subject: [PATCH 2/2] Name 1.0 as the default in the validator CLI help Co-Authored-By: Claude Opus 5.5 --- scripts/poppy-validate.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/poppy-validate.ts b/scripts/poppy-validate.ts index 4d055c11..83080202 100755 --- a/scripts/poppy-validate.ts +++ b/scripts/poppy-validate.ts @@ -19,7 +19,7 @@ Options: --kind poppy (default), protected-resource, oauth-metadata, client-metadata or jwks --domain For a poppy.json file: the domain that serves it --fetched-from For a client metadata file: the URL that serves it - --protocol Version for documents that don't declare one: 0.4, the only one (the default) + --protocol Version for documents that don't declare one: 0.4, or 1.0 (the default) --json Print the JSON report --strict Fail on warnings too (SHOULDs, the Guides, our readings) --quiet Print errors only