Skip to content

Speak the 1.0 draft beside 0.4 - #69

Merged
adewale merged 5 commits into
mainfrom
spec/1.0-beside-0.4
Nov 13, 2026
Merged

adewale merged 5 commits into
mainfrom
spec/1.0-beside-0.4

Conversation

@adewale

@adewale adewale commented Nov 13, 2026 •

Copy link
Copy Markdown
Owner

Upstream's 1.0 draft, as of 13 November at commit bb98332, has six breaking changes against 0.4. Today PDA refuses any Company that declares 1.0, and could not sign in at one that requires Pushed Authorization Requests. This PR makes the agent, mock and validator speak 1.0 beside 0.4 (decision 51), so 0.4 Companies keep working while others move to 1.0.

The pin is the site as of 15:48 UTC. A snapshot from 13:36 UTC (736ef95) was replaced before this PR was opened, because upstream added ten changelog entries in between.

The first commit is the upstream snapshot and kit, unmodified (135 files, 27,149 lines). The second is the change itself: 53 files, +1,385 and −158. The third moves the Python Hypothesis client and the Docker interop grid to 1.0 as well, and the last fixes what a code review of the whole branch found. No UI file changes, and the HTML files in the diff are the snapshot's pages.

What changes for a Company

1.0 change Applies under What PDA does
A description on each agent.protocols entry (8.1) 1.0 Discovery refuses a 1.0 Company without one. poppy_discover gives the model the description so it can choose between the Company's agent and its APIs
Pushed Authorization Requests (4.2; RFC 9126) 0.4 and 1.0 When the issuer lists pushed_authorization_request_endpoint, the sign-in card links to the agent's new /poppy/sign-in page. Each time the User opens it, the agent pushes the request with its client assertion and a DPoP proof, then answers 303 to the authorization endpoint with only client_id and request_uri
Consent for scopes granted before (4.2, 10.8) 1.0 Every Direct Sign-In request carries prompt=consent. We don't claim the exception for a redirect received only on the opening device (reading)
The same DPoP key at refresh (4.4) 0.4 and 1.0 DPoP keys are sealed in poppy_dpop_keys, so a refresh after a restart uses the key the refresh token was issued with. Each server's latest nonce goes in poppy_dpop_nonces, so the kept key keeps sending it
PS384 required (4.1, 5.2) 1.0 Nothing in the agent, which signs with ES256. The validator reports an issuer whose listed client-assertion algorithms leave out ES256 or PS384
UCP scope requests name every scope — PDA doesn't speak UCP. Its general sign-in already requests every scope still needed (4.7)

PAR and stored keys apply under 0.4 too, since RFC 9126 defines the metadata for any client and 0.4 allows keeping a key (reading). That keeps one sign-in path and one refresh path.

Of the minor changes, two reach the agent (reading). A message with a role it doesn't know is now relayed as the Company's content; before, it was dropped. In a 1.x conversation, a stream event with an SSE name it doesn't know is skipped. From 1.0 a newer minor version is compatible (3.4), so a Company serving 1.1 is used as 1.0 and every request declares Poppy-Version: 1.0.

Changes

  • Agent. PROTOCOL_VERSIONS is ["0.4", "1.0"]. The new /poppy/sign-in route answers only the person signed in to PDA in that browser, like the callback. It refuses an expired or finished sign-in and answers 404 for an unknown id. A signed-out browser is asked to sign in to PDA first, and nothing is pushed. poppy_discover also tells the model that a Company's name comes from its own poppy.json (1.0 10.3).

  • A Worker bug the new route found. handlePoppy forwarded requests to the person's Durable Object with the default redirect: "follow", so the stub followed the agent's 303 itself and the browser got a 404. It now passes redirect: "manual". No existing route redirected, so nothing deployed was affected.

  • Validator. A 1.0 profile (draft-1.0.ts) is 0.4's rules plus three additions:

    • the required descriptions (protocol-description-empty);
    • a port other than 443 in organization.domain;
    • ES256 and PS384 in listed client-assertion algorithms (metadata-assertion-algs).

    Under both versions it checks the PAR endpoint is HTTPS, and reports require_pushed_authorization_requests without an endpoint (par-endpoint-missing). A 1.x document newer than 1.0 is checked with the 1.0 profile and noted (version-newer-minor).

  • Mock.

    • Serves 1.0 and 1.1, and describes its protocols under 1.x.
    • New options: pushedAuthorization: "offered" | "required", bindRefreshTokens, and laterStreamEvent.
    • Under 1.x it takes a context field set to null as cleared.
    • New checks authorize.prompt-consent, par.not-pushed, par.extra-parameters, par.code-key and dpop.refresh-key-changed each have an id in violations.ts and a TAMPERS row.
  • Pins.

    • The 1.0 snapshot and kit are pinned in their own commit.
    • spec/requirements-1.0.json gives each of the 15 changelog entries a disposition.
    • A new CI step runs the 1.0 kit against the mock with reviewed findings.
    • The design, readings, README, upgrading and conformance pages say PDA speaks both versions. A new page, docs/poppy-1.0-upgrade.md, has the details.
  • Hypothesis client. The Python client now speaks 1.0 beside 0.4, written from the 1.0 text rather than ported from src/poppy. Each run draws the version the mock serves (0.4, 1.0, 1.1, or two linked), PAR offered or required, bound refresh tokens, and the new stream events. On its first run the mock's dpop.refresh-key-changed check caught the model itself: its new_dpop_key rule switched a User to a new key, and later refreshes proved with it, which 1.0 forbids. Each sign-in now keeps its key for refresh under 1.x (its README).

  • Interop grid. The mocks had been serving 1.0 since PROTOCOL_VERSIONS gained it, and scenario D failed because it expected 0.x. D now accepts 0.4 or 1.0. A new lenient-company-v04 keeps 0.4 in CI for our agent and evil-personal-agent. strict-company now requires PAR, and the agent adapter opens its own sign-in page as the User's browser would, so every Direct Sign-In in the grid runs both ways.

  • Review fixes. A high-effort review of the whole branch found these, each now with a test that fails without its fix:

    • A push that came back after the sign-in had finished in another tab, or been cancelled, could mark it failed. It now ends only a sign-in that is still pending.
    • Rewording a 1.0 protocol description counted as an interface change, so pending work failed with company_changed. Only the endpoint counts now.
    • An empty SSE event: field, which means message, made a 1.0 conversation skip the message. The Python client had the same bug.
    • The protocol log recorded the push as a token request. It is now its own step, signin.direct.push.
    • A Company that dropped PAR left the sign-in waiting. It now ends.

    Smaller fixes, without tests:

    • an origin that never sent a DPoP nonce no longer costs a SQL read per request;
    • the store header and SECURITY.md now say DPoP keys are sealed at rest;
    • the runner checks the client assertion's aud at the PAR endpoint too;
    • the validator reuses the shared version rule.

    The review also said a 1.0 Company with a port in organization.domain can't pass live discovery. That is our documented policy: the agent uses no Company on another port. The ledger now says that only a document given as text is checked with a port.

Verification

  • test/poppy-1.0.test.ts (19 tests) covers:
    • the version choice and declaration for 1.0, 0.4 linking 1.0, 1.0 linking 0.4, 1.1, and 0.4;
    • the description reaching the model;
    • PAR required and offered under 1.0, and offered under 0.4: the card's link, a push carrying a DPoP proof each time the link is opened, a full sign-in, a signed-out browser, an unknown id;
    • prompt=consent under 1.0, pushed or in the URL, and not under 0.4;
    • a message with an unknown role and author type, and a stream event with an unknown name, under 1.0 and 0.4;
    • a refresh with the stored key after the agent's memory is lost, at a Company that binds refresh tokens.
  • Every request the agent sends to the mock is checked against the schemas of the kit for the version it declared, 0.4 or 1.0.
  • Reverting each fix makes its tests fail:
    • Without prompt=consent, both 1.0 consent tests fail.
    • Dropping unknown roles again, or reading every stream event again, fails the matching test.
    • With memory-only DPoP keys, the refresh test fails: the mock answers invalid_grant.
    • With nonces back in memory only, the new nonce test in test/poppy.test.ts fails in all three DPoP profiles. Before that fix, test/poppy.test.ts failed about one run in three. A kept key arrived without the nonce it had used, and the mock recorded dpop.nonce-ignored whenever the clock had crossed a second.
  • npm test: all five projects pass (1755, 3, 314, 454, 211). npm run typecheck, check:spec, check:docs and npm run test:hypothesis (63) pass. Reverting prompt=consent in the Python client fails its suite with authorize.prompt-consent.
  • The interop grid in CI passes all 170 cells with no known failures: 108 honest cells for our agent against lenient-company and strict-company at 1.0 and lenient-company-v04 at 0.4, 30 at Print with Poppy, 8 against evil-company, and 24 for evil-personal-agent against the three mocks. The HAR files show 14 pushes at strict-company and no authorization request there that wasn't pushed.
  • node scripts/check-company-kit.mjs --protocol 1.0 --reviewed-findings passes with and without --with-dpop. Its findings match the 0.4 kit's: lenient and strict 122 pass, 1 fail and 7 warnings, all from the documented DPoP prerequisite.

Limits

  • The 1.0 kit's validator checks none of the agent-side changes, so they rest on our own mock's checks. No live Company serves 1.0 or offers PAR.
  • Docker isn't available locally, so the interop grid runs only in CI.
  • test/activity.test.ts "describes a 0.4 conversation from its four state fields" failed in 2 of about 9 full runs on this branch, and in none of 3 on main; it passes alone. It writes conversation state in SQL while a background read can overwrite it. I left it unchanged.
  • Not deployed. On deploy, keys held in memory are lost with the restart, so each issuer's first refresh afterwards uses a new key, which is then stored. No live Company binds refresh tokens yet.

🤖 Generated with Claude Code

Ade Oshineye and others added 5 commits November 13, 2026 16:15
The site snapshot of 15:48 UTC (scripts/spec-snapshot.mjs --save) and
the official kit download of the same afternoon, unmodified, at upstream
commit bb98332. The kit's reference pages match the snapshot's pages
apart from absolute links, and its validator and schemas match upstream
kit/company apart from links the site rewrites.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Decision 51. The agent, mock and validator speak 0.4 and the 13 November
1.0 draft (bb98332), and choose the newest compatible version a Company
offers; from 1.0 a newer minor version is compatible and requests
declare 1.0.

- 1.0 requires a description on each agent.protocols entry (8.1); the
  validator's 1.0 profile checks it and poppy_discover shows it.
- Pushed Authorization Requests (4.2), under both versions: the Direct
  Sign-In card links to /poppy/sign-in, which pushes with a DPoP proof
  when opened and redirects with only client_id and request_uri. The
  Worker now forwards /poppy/* with redirect: "manual" so the 303
  reaches the browser.
- prompt=consent on every Direct Sign-In request to a 1.x Company
  (4.2, 10.8).
- The same DPoP key at refresh (4.4), under both versions: keys are
  sealed in poppy_dpop_keys and each server's latest nonce kept in
  poppy_dpop_nonces, both withheld from the data export.
- A message with an unknown role is the Company's content; a 1.x stream
  event with an unknown SSE name is skipped (8.4, 8.6).
- The 1.0 validator allows a port in organization.domain and requires
  ES256 and PS384 in listed client-assertion algorithms.
- The mock offers or requires PAR, binds refresh tokens to their key,
  streams a later-version event, takes null context as cleared under
  1.x, and records authorize.prompt-consent, par.not-pushed,
  par.extra-parameters, par.code-key and dpop.refresh-key-changed, each
  with a TAMPERS case.
- The 1.0 pin, a 15-entry requirement ledger, reviewed kit findings and
  a CI step for the 1.0 kit; docs and readings updated.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
The Python client chooses among 0.4 and 1.0 and declares its own version,
requires 1.0's protocol descriptions, sends prompt=consent under 1.x and
pushes Direct Sign-In when the issuer lists the endpoint. Each run draws
the mock's version (0.4, 1.0, 1.1, or two linked), PAR, bound refresh
tokens and a later version's stream event. Its model now refreshes with
the key each sign-in was issued with under 1.x, which the mock's
dpop.refresh-key-changed check found on the first run.

In the interop grid the mocks already served 1.0 since PROTOCOL_VERSIONS
gained it, and scenario D expected 0.x. D now accepts 0.4 or 1.0, and
lenient-company-v04 (INTEROP_MOCK_VERSION=0.4) keeps 0.4 in CI for our
agent and evil-personal-agent.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- A push answered after the sign-in finished in another tab, or was
  cancelled, no longer marks it failed: only a pending sign-in is ended,
  claimed before anything is awaited.
- A sign-in at a Company that dropped PAR ends instead of waiting.
- Rewording a 1.0 protocol description no longer counts as an interface
  change that fails pending work with company_changed.
- An empty SSE event field is the default name, message, in our client
  and the Python one.
- The protocol log records the push as signin.direct.push, not a token
  request.
- An origin that never sent a DPoP nonce costs no SQL read per request.
- The store header and SECURITY.md say DPoP keys are sealed at rest.
- In the interop grid strict-company requires PAR, and the agent adapter
  opens its own sign-in page as the User's browser would; the runner
  checks the assertion aud at the PAR endpoint too.
- The validator reuses compatibleVersions to pick a profile.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@adewale
adewale merged commit cd08f32 into main Nov 13, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant