@poppykit/server 0.3.1 → 0.4.0

package/API.md

@@ -7,6 +7,7 @@ completion for complete options and results; this map identifies the integration
 | --- | --- | --- |
 | `@poppykit/server` | `createRequestAuthenticator`, `AuthorityError`, authority types | [authentication](AUTH.md) |
 | `@poppykit/server` | `createConversationService`, `createConversationNotifications` | [delivery](DELIVERY.md) |
+| `@poppykit/server` | `Author`, `AuthorType`, `Message`, `RecordedMessage`, conversation/event types | [delivery](DELIVERY.md) |
 | `@poppykit/server` | `createBrowserSessions`, `createFeedbackHandler`, MCP metadata/error helpers | [integrations](INTEGRATIONS.md) |
 | `@poppykit/server/reference-auth` | `createReferenceIssuer`, `createMetadataResolver`, `createNodeTransport` | [authentication](AUTH.md) |
 | `@poppykit/server/sqlite` | `SqliteCompanyDatabase` | [storage](STORAGE.md) |

package/AUTH.md

@@ -7,10 +7,24 @@ order authorization checks with protected work. The reference issuer is a
 separate `/reference-auth` import and uses the shared company database coordinator
 for immediate revocation visibility.
 
+For draft 0.3 discovery configure `protectedResources`, including
+`https://company.example` (host only, no port/path/trailing slash), and
+`supportedScopes`, the company-defined account scopes. This replaces
+`poppyDomains` and `directScopes` in reference issuer options. Direct and Device
+use that same supported list; Device configuration no longer has a `scopes` field.
+Mediated retains its own subset. Publish descriptions in company `auth.scopes` or
+a listed OpenAPI document. Names starting with `poppy:` are reserved. Issuer
+metadata emits the mandatory session/refresh grants and enabled sign-in grants.
+Token exchange for Bearer-only MCP remains a later migration stage.
+
 Reference Direct sign-in uses `beginAuthorization` / `completeAuthorization`.
 The host authenticates the human and protects consent with its own browser
 session/CSRF controls; pass a high-entropy browser binding. Registered callback
-URLs must be HTTPS on the client metadata domain and exactly match registration.
+URLs must be HTTPS on the client metadata domain, or RFC 8252 HTTP loopback IP
+callbacks (`127.0.0.1` or `[::1]`). Registration matching permits only the loopback
+port to vary; exchange must repeat the actual authorization redirect exactly.
+Direct requests require `dpop_jkt`; codes retain it and exchange requires that
+Session Key. Missing bindings in old pending authorizations/codes fail closed.
 
 Direct hosts must configure `authorizationResultCipher: { seal, open }` with
 synchronous authenticated encryption and a durable protected key before calling
@@ -36,13 +50,13 @@ preserving the accepted scope ceiling, reset generation and configured revocatio
 Account Token rotation retains all issued hashes through the fixed grant lifetime.
 Replaying any ancestor revokes its entire lineage and signs its Sessions out;
 rotation never extends the grant. Client authentication remains mandatory, while
-Session Tokens can move to a new DPoP key as the protocol permits. Shared provider
+Account Tokens can start Sessions with new keys; a Session never changes its key. Shared provider
 signing does not bind a copied refresh token to one provider enrollment. Keep
 tokens secret and serialize rotation; never retry a lost token response blindly.
 Bounded database cleanup removes hashes only after their lineage is expired,
 revoked or absent. No plaintext callback code is persisted.
 
-Upgrade prerequisite: older issuers discarded ancestors beyond the previous hash.
+Pre-version-3 upgrade prerequisite: older issuers discarded ancestors beyond the previous hash.
 Those missing hashes cannot be reconstructed by this update. Before public
 enablement, revoke every pre-upgrade live lineage through the issuer's normal
 revocation/disconnect flow and require fresh consent, or prove it has expired.
@@ -50,12 +64,21 @@ Until then, the full-ancestor guarantee applies only to newly created lineages.
 This update does not reset stored data or silently revoke legacy grants.
 
 Enable reference Device sign-in with `device: { endpoint, verificationUri,
-scopes }`. Route the configured device endpoint to `deviceAuthorization`.
+}`. Route the configured device endpoint to `deviceAuthorization`.
 On the human page call `beginDeviceAuthorization(userCode, browserBinding)` and
 show the client identity and requested scopes. After an authenticated explicit
 approve/decline action call `completeDeviceAuthorization`. Opening a link must
 never approve it. The token endpoint handles durable polling intervals, slowdown,
 denial, expiry, partial consent, one-use codes and the Session's sticky account.
+The first authenticated poll atomically binds the device code to its live Session
+Key, including pending/slow-down polls. Other keys receive `invalid_grant`.
+Old device records without the new binding slot require a fresh flow. Prefer
+Direct whenever viable; enable Device only for appropriate device constraints
+under RFC 10027. Verification links remain HTTPS on issuer/protected-resource hosts.
+
+Hosted consent can resolve `sessionForKey({ clientId, userId, sessionKey })` to the
+current company Session without treating a client's local Session ID as a server
+ID. It validates live client/User ownership and returns current account/scopes.
 
 Enable Mediated sign-in with `mediated: { endpoint, scopes, fields,
 authenticate, verifyCode }` and route that endpoint and its sign-in-ID children
@@ -88,9 +111,15 @@ revision. Revision and per-account fence records remain until explicit issuer
 reset and never count as pending requests. Terminal method tombstones also do
 not consume pending quota.
 
-Issuer state is version 3. Older development state is refused without mutation;
-there is no automatic migration. Follow the explicit stop/backup/reset procedure
-in [STORAGE.md](STORAGE.md) only for state you choose to discard.
+Issuer state is version 4. SQLite/PostgreSQL upgrade normalized version 3 under
+their writer lock; grant lineage survives. Earlier unsupported development versions
+still fail closed. See [STORAGE.md](STORAGE.md) for the exact upgrade behavior.
+
+Token admission selects an internal Session ID atomically by the DPoP thumbprint.
+It checks the client, User and optional assertion `agent_id` against the existing
+Session. Known ended keys return `invalid_grant`; key mappings/tombstones are
+retained indefinitely in this reference implementation. Token requests reject the
+old `session_id` parameter; responses omit `session_id` and `signed_in`.
 
 Advertise only configured methods in your `poppy.json`; `authorizationMetadata()`
 adds the device endpoint only when enabled. There is no login/consent UI, identity

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.4.0 — 2026-10-28
+
+Target pinned Personal Agent Protocol draft 0.3. Break discovery, proof-key grants, author, browser joining and MCP Token Exchange contracts. Upgrade issuer state 3→4; stop old writers and reset conversation state to version 2. Require explicit company history scopes.
+
+Local migration candidate only. Publication and deployment require separate approval.
+
 ## 0.3.1
 
 Support Node 24.21.0 and later within Node 24 under the owner-accepted runtime policy.

package/CONTRIBUTING.md

@@ -1,8 +1,10 @@
 # Contributing
 
-Follow the live draft 0.2 [specification](https://personalagentprotocol.org/docs/0.2/spec)
-and [guides](https://personalagentprotocol.org/docs/0.2/guides). Tests/snapshots are
-supporting evidence. Demo/business workflows and individual extensions are excluded.
+Follow the pinned draft 0.3 [specification](https://personalagentprotocol.org/docs/0.3/spec)
+and [guides](https://personalagentprotocol.org/docs/0.3/guides). Tests/snapshots are
+supporting evidence. This unreleased checkout has completed only the discovery
+stage of migration; auth, wire/storage and integrations still need their stages.
+Demo/business workflows and individual extensions are excluded.
 Code is [MIT](LICENSE); confirm rights for third-party contributions.
 
 Use Node 24.21.0, TypeScript 5.9.3 and @types/node 24.10.0.

package/DELIVERY.md

@@ -1,8 +1,13 @@
 # Conversation delivery and transport
 
-The SDK targets Personal Agent Protocol draft 0.2. Company content, messages,
+Conversation messages and authorization events now use draft 0.3. Company content, messages,
 unknown events and partial text remain untrusted data for the host application.
 
+Account-history access requires explicit, nonempty company `historyScopes` in
+`createConversationService`, for example `['orders:read']`. There is no protocol
+read-scope default. The configured scopes and account/owner checks apply to HTTP
+reads and worker history; sending alone grants no read access.
+
 ## Client interoperability
 
 Clients keep immutable retry targets/message IDs, explicitly acknowledge named
@@ -76,3 +81,16 @@ Pruning is explicit operator policy, never automatic data loss. It preserves old
 message receipts and cursor identity. Concurrent reads see a coherent snapshot or
 `cursor_expired`. Invalid/expired waited-POST cursors are rejected before accepting
 the new write; an existing message ID still returns its original receipt.
+
+## Unreleased draft 0.3 breaking change
+
+Protocol messages use `author: { type: 'agent' | 'human' }`; company authors may
+also carry `id`, `name` and an HTTPS `image`. Responder checks use `author.type`,
+and only the server assigns recorded `role`. Authorization events always use
+`insufficient_scope` and name required scopes, including signed-out requests.
+
+Conversation state version 2 requires an explicit clean reset of old runtime
+state; SQLite/PostgreSQL reject version 1. Stop old writers and clear history,
+receipts, cursor identities, work, client outboxes and retry handles together.
+Preserve required configuration. No historical conversion or dual wire format is
+provided. An accepted request's fingerprint is never rewritten.

package/INTEGRATIONS.md

@@ -27,8 +27,12 @@ MCP metadata identifies the exact resource URL, issuer and ES256 support when
 enabled. Challenges include Bearer and, if supported, DPoP with `resource_metadata`.
 The exact endpoint accepts no child paths or added query. All other APIs retain
 DPoP-only authentication. Configure the reference issuer `mcpResources` with the
-same `{url,dpop}` list: every grant chooses Bearer for a non-DPoP MCP server even
-when a proof was provided. DPoP MCP requires a valid proof. Bearer tokens are
+same `{url,dpop}` list. Non-DPoP MCP targets require Token Exchange of a current
+DPoP Session Token, a matching client assertion and the Session Key proof. Other
+grants reject those targets with invalid_target; exchange rejects DPoP MCP targets.
+Exchange preserves the Session and narrows subject scopes without rotating an
+Account Token. Metadata advertises exchange when a Bearer-only MCP resource exists.
+DPoP MCP continues using normal DPoP token grants. Bearer tokens are
 resource-bound; DPoP-bound tokens cannot be presented as Bearer.
 
 An existing issuer can accept ordinary MCP OAuth clients through its own flow.
@@ -43,7 +47,7 @@ implements personal-agent grants; it does not add a general OAuth login product.
 
 ```ts
 const browser = createBrowserSessions({ endpoint: browserEndpoint, domain: companyDomain,
-  metadata, authority: referenceIssuer.browserSessions,
+  authority: referenceIssuer.browserSessions,
   policy: referenceIssuer.authority.policy, cookies: cookieStore, now: Date.now,
 });
 // Mount browser.join on browserEndpoint; no request-body logging at this route.
@@ -52,15 +56,21 @@ const result = await browser.withSession(request, ['records:read'], principal =>
 
 `BrowserCookieStore.put/get` stores SHA256 cookie-value hashes, session bindings and
 expiry. Supply durable storage with targeted operations and expire old rows. Never
-store plaintext cookie values. `BrowserSessionAuthority.join` must atomically
-consume assertion jti and validate an active same-client/same-user session; `current`
-must read current session permissions. The reference issuer implements both on its
-existing durable issuer store/coordinator; SQLite uses targeted browser selectors.
+store plaintext cookie values. The same store must implement `putJoin(codeHash,
+{cookieHash, expiresAt})` and atomic `consumeJoin(codeHash)`, which removes and
+returns the entry even if expired. Expire abandoned joins and rate-limit the public
+route in the host. Cookie/code hashes may be shared durably across handler replicas.
+`BrowserSessionAuthority.join(sessionKey)` resolves an existing active key; it never
+creates a Session. `current` reads current permissions. The reference issuer uses
+targeted key/Session selectors on its existing memory/SQLite/PostgreSQL stores.
 
-The browser handler verifies JWKS signature, asymmetric algorithm, typ, exact aud,
-times/lifetime, replay, client/user/session and HTTPS company return URL. Invalid
-requests return 400 with no cookie; successful requests set a host-only cookie and
-return 303 to the validated URL. Defaults are `__Host-poppy-session`, Path=/, Secure,
+Mount both GET and POST. GET sets only a 60-second Strict __Host-poppy_join cookie
+and emits a random 256-bit hidden code, no-store, frame-ancestors none and same-origin
+opener isolation. POST consumes the submitted code first, including failed cookie,
+origin and proof checks. It requires that browser's cookie and a valid Session Key
+DPoP proof whose nonce is the code and which has no ath. Invalid requests return 400
+with no cookie; success clears the join cookie, sets the Session cookie and returns
+303 to the endpoint's website root. No provider signing/JWKS assertion is involved. Defaults are `__Host-poppy-session`, Path=/, Secure,
 HttpOnly, SameSite=Lax and max 3600 seconds capped by the current session lifetime.
 SameSite=None is supported; Strict is refused. `authenticate` resolves current
 authority on every request. Use `withSession` for scoped mutations so permission

package/README.md

@@ -1,14 +1,19 @@
 # PoppyKit server
 
+Draft 0.3 migration (2026-10-28), pinned to the public source captured that day.
+Client/CLI 0.5.0 and server 0.4.0 break the earlier protocol contracts. Stop old
+writers and follow the documented storage/reset procedure before compatible
+writers resume. Registry, deployment and live acceptance have separate receipts.
+
 The Node 24.21.0 minimum is an owner-accepted compatibility baseline. Use a current patched Node 24 runtime where available; this minimum does not establish that older runtimes contain later security fixes. Build and release CI read `.node-version`.
 
-TypeScript SDK for companies implementing [Personal Agent Protocol draft 0.2](https://personalagentprotocol.org/docs/0.2/spec).
+TypeScript SDK for companies implementing [Personal Agent Protocol draft 0.3](https://personalagentprotocol.org/docs/0.3/spec).
 Verify requests, serve conversations and enforce current authority. Your company
 supplies accounts, consent UI, agent, business tools and HTTPS routing. [MIT](LICENSE).
 
 ## Install
 
-This source contains unreleased repairs; final version selection and publication are pending.
+Use the exact version verified by its protected release workflow; check registry publication before installation.
 
 Requires Node **24.x, at least 24.21.0**, and ESM. CI tests Node 24.21.0 on Linux, macOS and Windows;
 other Node majors are unsupported. SQLite is optional/experimental and
@@ -37,11 +42,12 @@ try {
   const endpoint = 'https://company.example/conversations';
   const auth = createReferenceIssuer({
     issuer, tokenEndpoint: issuer + '/token', revocationEndpoint: issuer + '/revoke',
-    poppyDomains: ['company.example'], directScopes: [], resources: [endpoint],
+    protectedResources: ['https://company.example'], supportedScopes: [], resources: [endpoint],
     metadata: createMetadataResolver(transport), store: database.issuer(issuer),
     coordinator: database, now: Date.now,
   });
   const service = createConversationService({
+    historyScopes: ['orders:read'],
     endpoint, store: database.conversations(issuer), policy: auth.authority.policy,
     authenticator: createRequestAuthenticator({ authority: auth.authority,
       endpoints: [{ origin: 'https://company.example', pathPrefix: '/conversations', resource: endpoint }],

package/STORAGE.md

@@ -81,6 +81,22 @@ force another conversation's receipts out of storage.
 
 ## Non-durable use and resets
 
+Normalized issuer state version 3 upgrades to version 4 once, under the existing
+SQLite writer/PostgreSQL namespace lock. Stop old writers before using the new
+adapter. No SQL schema change is needed: `sessionKeys` records use the existing
+namespace/kind/ID primary key. Token selectors load that mapping and its internal
+Session ID in the same transaction as creation, ownership checks and rotation.
+Mappings remain indefinitely after a Session ends, preventing key reuse.
+
+Old keys could belong to several Sessions, so the upgrade ends old Sessions and
+tombstones every known old access-token key rather than guessing a mapping.
+Internal Session IDs, sticky account records, stable Users, grants, all retained
+Account Token hashes, revocation fences and accepted-work authority remain.
+Legacy pending authorization/code/Device/Mediated records are retired: restart
+sign-in rather than accepting consent without the new binding. Existing compatible
+Account Tokens can create fresh-key Sessions. Unsupported earlier state versions
+are refused. The upgrade scans a namespace once; normal selectors stay targeted.
+
 `new SqliteCompanyDatabase(':memory:')` is an explicit non-durable adapter for tests
 and development. Each instance is separate, is lost at close/process death, and
 offers no cross-process persistence. The test fixture's object store is also

package/dist/adapter-contract.js

@@ -27,11 +27,11 @@ const endpoint = 'https://contract.example.test/poppy/conversations';
 const base = { issuer: 'https://auth.contract.test', clientId: 'https://agent.contract.test/client', sessionId: 's1', userId: 'u_1', scopes: [], tokenExpiresAt: 9e12, sessionVersion: 1 };
 const principals = {
     signedOut: base,
-    account1: { ...base, accountId: 'acct_1', scopes: ['poppy:read'] },
-    account2: { ...base, accountId: 'acct_2', scopes: ['poppy:read'] },
+    account1: { ...base, accountId: 'acct_1', scopes: ['orders:read'] },
+    account2: { ...base, accountId: 'acct_2', scopes: ['orders:read'] },
 };
-const message = { id: 'msg_1', sender: 'agent', text: 'Where is order 1042?' };
-const reply = { id: 'msg_r1', sender: 'agent', text: 'Shipped.' };
+const message = { id: 'msg_1', author: { type: 'agent' }, text: 'Where is order 1042?' };
+const reply = { id: 'msg_r1', author: { type: 'agent' }, text: 'Shipped.' };
 function check(held, needed, action) {
     if (!needed.every(scope => held.includes(scope)))
         return Promise.reject(new AuthorityError('insufficient_scope'));
@@ -50,7 +50,7 @@ function serviceOn(store, clock) {
             return principal;
         },
     };
-    return createConversationService({ endpoint, store, authenticator, policy, clock, leaseMs: 1000, supportedScopes: ['poppy:read'] });
+    return createConversationService({ historyScopes: ['orders:read'], endpoint, store, authenticator, policy, clock, leaseMs: 1000, supportedScopes: ['orders:read'] });
 }
 async function call(service, path, as, body, query = '') {
     const response = await service.handle(new Request(`${endpoint}${path}${query}`, {
@@ -114,12 +114,12 @@ export function runConversationAdapterContract(fixture) {
         const parentWork = (await a.claim());
         const outcome = (promise) => promise.then(value => value.accountId, error => String(error.code));
         const results = await Promise.all([
-            outcome(a.requireAccount(parentWork, ['poppy:read'])),
+            outcome(a.requireAccount(parentWork, ['orders:read'])),
             (async () => {
-                const opened = await call(b, '', 'account2', { parent_conversation_id: parent, message: { id: 'msg_c', sender: 'human', text: 'Hi.' } });
+                const opened = await call(b, '', 'account2', { parent_conversation_id: parent, message: { id: 'msg_c', author: { type: 'human' }, text: 'Hi.' } });
                 if (opened.status !== 201)
                     return String(opened.body.error);
-                return outcome(b.claim().then(work => b.requireAccount(work, ['poppy:read'])));
+                return outcome(b.claim().then(work => b.requireAccount(work, ['orders:read'])));
             })(),
         ]);
         const winners = results.filter(result => result.startsWith('acct_'));
@@ -129,7 +129,7 @@ export function runConversationAdapterContract(fixture) {
         assert.deepEqual(state.bindings[parent], { accountId: winners[0] });
         const loser = winners[0] === 'acct_1' ? 'account2' : 'account1';
         for (const id of Object.keys(state.conversations))
-            assert.deepEqual((await call(b, `/${id}/events`, loser)).body, { error: 'sign_in_required' });
+            assert.deepEqual((await call(b, `/${id}/events`, loser)).body, { error: 'insufficient_scope' });
     }));
     test('adapter contract: lease reclaim on the other handle fences the old worker; output IDs dedupe', () => withFixture(async ({ store, second }) => {
         const [a, b] = [serviceOn(store, clock), serviceOn(second, clock)];
@@ -155,8 +155,8 @@ export function runConversationAdapterContract(fixture) {
             await a.reply(work, outputId, value);
             await b.reply(work, outputId, value);
             await assert.rejects(b.reply(work, outputId, { ...value, text: 'changed' }), { code: 'output_conflict' });
-            await a.requestAuthorization(work, `auth_${outputId}`, ['poppy:read']);
-            await b.requestAuthorization(work, `auth_${outputId}`, ['poppy:read']);
+            await a.requestAuthorization(work, `auth_${outputId}`, ['orders:read']);
+            await b.requestAuthorization(work, `auth_${outputId}`, ['orders:read']);
             await a.requestUser(work, `user_${outputId}`, outputId);
             await b.requestUser(work, `user_${outputId}`, outputId);
             await assert.rejects(b.requestUser(work, `user_${outputId}`, 'changed'), { code: 'output_conflict' });

package/dist/browser.d.ts

@@ -1,4 +1,3 @@
-import type { MetadataResolver } from './network/discovery.js';
 import type { Principal, AuthorityPolicy } from './auth/authority.js';
 export interface BrowserBinding {
     clientId: string;
@@ -11,10 +10,7 @@ export interface BrowserSession extends BrowserBinding {
     expiresAt: number;
 }
 export interface BrowserSessionAuthority {
-    join(binding: BrowserBinding, assertion: {
-        jti: string;
-        expiresAt: number;
-    }): Promise<BrowserSession>;
+    join(sessionKey: string): Promise<BrowserSession>;
     current(binding: BrowserBinding): Promise<BrowserSession>;
 }
 export interface BrowserCookieStore {
@@ -24,12 +20,19 @@ export interface BrowserCookieStore {
     get(hash: string): Promise<(BrowserBinding & {
         expiresAt: number;
     }) | null>;
+    putJoin(codeHash: string, binding: {
+        cookieHash: string;
+        expiresAt: number;
+    }): Promise<void>;
+    consumeJoin(codeHash: string): Promise<{
+        cookieHash: string;
+        expiresAt: number;
+    } | null>;
 }
 export declare function boundedText(request: Request, max: number): Promise<string>;
 export declare function createBrowserSessions(options: {
     endpoint: string;
     domain: string;
-    metadata: MetadataResolver;
     authority: BrowserSessionAuthority;
     cookies: BrowserCookieStore;
     policy: AuthorityPolicy;

package/dist/browser.js

@@ -1,8 +1,6 @@
 import { createHash, randomBytes } from 'node:crypto';
-import { compactVerify, createLocalJWKSet, decodeJwt, errors } from 'jose';
 import { secureUrl } from './network/transport.js';
-import { parseJson, object } from './protocol/wire.js';
-import { assertUniqueJwtMembers } from './auth/dpop.js';
+import { verifyDpopProof } from './auth/dpop.js';
 import { AuthorityError } from './auth/authority.js';
 const hash = (value) => createHash('sha256').update(value).digest('base64url');
 export async function boundedText(request, max) {
@@ -32,10 +30,12 @@ export async function boundedText(request, max) {
     return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts));
 }
 export function createBrowserSessions(options) {
-    secureUrl(options.endpoint);
+    const endpoint = secureUrl(options.endpoint);
     const name = options.cookieName ?? '__Host-poppy-session', sameSite = options.sameSite ?? 'Lax', lifetime = options.cookieLifetimeSeconds ?? 3600;
     if (!/^[A-Za-z0-9_-]+$/.test(name) || !['Lax', 'None'].includes(sameSite) || !Number.isSafeInteger(lifetime) || lifetime < 1 || !/^[a-z0-9.-]+$/i.test(options.domain))
         throw new TypeError('browser options');
+    if (name === '__Host-poppy_join' || (endpoint.hostname !== options.domain.toLowerCase() && !endpoint.hostname.endsWith(`.${options.domain.toLowerCase()}`)))
+        throw new TypeError('browser options');
     const invalid = () => new Error('Invalid browser session');
     async function authenticate(request) {
         const cookies = (request.headers.get('cookie') ?? '').split(';').map(part => part.trim().split('='));
@@ -63,44 +63,46 @@ export function createBrowserSessions(options) {
         },
         async join(request) {
             try {
-                if (request.method !== 'POST' || request.url !== options.endpoint || request.headers.get('content-type')?.split(';')[0] !== 'application/x-www-form-urlencoded')
+                if (request.url !== options.endpoint)
                     throw invalid();
-                const fields = new URLSearchParams(await boundedText(request, 16384));
-                if (fields.getAll('assertion').length !== 1 || [...fields.keys()].some(key => key !== 'assertion'))
+                if (request.method === 'GET') {
+                    const code = randomBytes(32).toString('base64url'), cookie = randomBytes(32).toString('base64url');
+                    await options.cookies.putJoin(hash(code), { cookieHash: hash(cookie), expiresAt: options.now() + 60000 });
+                    return new Response(`<!doctype html><title>Connecting</title><form method="post"><input type="hidden" name="code" value="${code}"><input type="text" name="proof"></form>`, { headers: {
+                            'Content-Type': 'text/html; charset=utf-8', 'Cache-Control': 'no-store',
+                            'Content-Security-Policy': "default-src 'none'; form-action 'self'; frame-ancestors 'none'", 'Cross-Origin-Opener-Policy': 'same-origin',
+                            'Set-Cookie': '__Host-poppy_join=' + cookie + '; Path=/; Max-Age=60; Secure; HttpOnly; SameSite=Strict',
+                        } });
+                }
+                if (request.method !== 'POST' || request.headers.get('content-type')?.split(';')[0] !== 'application/x-www-form-urlencoded')
                     throw invalid();
-                const jwt = fields.get('assertion');
-                if (jwt.length > 8192)
+                const fields = new URLSearchParams(await boundedText(request, 16384));
+                const codes = fields.getAll('code');
+                // Consume every identifiable code before checking cookies, origin, proof or duplicate fields.
+                const issued = await Promise.all([...new Set(codes)].map(code => options.cookies.consumeJoin(hash(code))));
+                if (codes.length !== 1 || fields.getAll('proof').length !== 1 || [...fields.keys()].some(key => !['code', 'proof'].includes(key)))
                     throw invalid();
-                assertUniqueJwtMembers(jwt);
-                const untrusted = decodeJwt(jwt);
-                if (typeof untrusted.iss !== 'string')
+                const binding = issued[0];
+                const cookies = (request.headers.get('cookie') ?? '').split(';').map(part => part.trim().split('='));
+                const matches = cookies.filter(([key]) => key === '__Host-poppy_join');
+                if (!binding || binding.expiresAt <= options.now() || matches.length !== 1 || matches[0].length !== 2 || hash(matches[0][1]) !== binding.cookieHash)
                     throw invalid();
-                const client = await options.metadata.resolveClient(untrusted.iss);
-                let keys = await options.metadata.resolveJwks(client.jwks_uri);
-                let verified;
-                try {
-                    verified = await compactVerify(jwt, createLocalJWKSet(keys), { algorithms: ['ES256', 'RS256'] });
-                }
-                catch (error) {
-                    if (!(error instanceof errors.JWKSNoMatchingKey))
-                        throw error;
-                    keys = await options.metadata.resolveJwks(client.jwks_uri, { refresh: true });
-                    verified = await compactVerify(jwt, createLocalJWKSet(keys), { algorithms: ['ES256', 'RS256'] });
-                }
-                const claims = object(parseJson(new TextDecoder().decode(verified.payload)));
-                if (verified.protectedHeader.typ?.toLowerCase().replace(/^application\//, '') !== 'poppy-browser+jwt' || claims.iss !== client.client_id || claims.aud !== options.endpoint || typeof claims.sub !== 'string' || !claims.sub || claims.sub.length > 256 || typeof claims.session_id !== 'string' || !claims.session_id || typeof claims.jti !== 'string' || !claims.jti || claims.jti.length > 256 || !Number.isSafeInteger(claims.iat) || !Number.isSafeInteger(claims.exp) || claims.exp <= options.now() / 1000 || claims.iat > options.now() / 1000 + 30 || claims.exp <= claims.iat || claims.exp - claims.iat > 60 || typeof claims.return_to !== 'string')
+                const origin = request.headers.get('origin'), site = request.headers.get('sec-fetch-site');
+                if ((origin !== null && origin !== new URL(options.endpoint).origin) || (site !== null && !['same-origin', 'none'].includes(site)))
                     throw invalid();
-                const destination = secureUrl(claims.return_to);
-                if (destination.hostname !== options.domain.toLowerCase() && !destination.hostname.endsWith(`.${options.domain.toLowerCase()}`))
+                const verified = await verifyDpopProof(fields.get('proof'), { method: 'POST', url: options.endpoint, nowMs: options.now() });
+                if (verified.claims.nonce !== codes[0])
                     throw invalid();
-                const session = await options.authority.join({ clientId: client.client_id, userId: claims.sub, sessionId: claims.session_id }, { jti: claims.jti, expiresAt: claims.exp * 1000 });
+                const session = await options.authority.join(verified.jkt);
                 const seconds = Math.floor(Math.min(session.expiresAt - options.now(), lifetime * 1000) / 1000);
                 if (seconds < 1)
                     throw invalid();
                 const value = randomBytes(32).toString('base64url');
                 const { clientId, userId, sessionId, issuerGeneration } = session;
                 await options.cookies.put(hash(value), { clientId, userId, sessionId, ...(issuerGeneration === undefined ? {} : { issuerGeneration }), expiresAt: options.now() + seconds * 1000 });
-                return new Response(null, { status: 303, headers: { Location: claims.return_to, 'Set-Cookie': `${name}=${value}; Path=/; Secure; HttpOnly; SameSite=${sameSite}; Max-Age=${seconds}`, 'Cache-Control': 'no-store' } });
+                const headers = new Headers({ Location: new URL('/', options.endpoint).href, 'Set-Cookie': `${name}=${value}; Path=/; Secure; HttpOnly; SameSite=${sameSite}; Max-Age=${seconds}`, 'Cache-Control': 'no-store' });
+                headers.append('Set-Cookie', '__Host-poppy_join=; Path=/; Max-Age=0; Secure; HttpOnly; SameSite=Strict');
+                return new Response(null, { status: 303, headers });
             }
             catch {
                 return new Response('Invalid browser session', { status: 400, headers: { 'Cache-Control': 'no-store', 'Content-Type': 'text/plain' } });

package/dist/conversation/service.d.ts

@@ -1,4 +1,4 @@
-import type { ConversationEvent, JsonObject, Message, Sender, Status } from '../protocol/wire.js';
+import type { ConversationEvent, JsonObject, Message, AuthorType, Status } from '../protocol/wire.js';
 import type { ConversationStore, ConversationNotifications } from './store.js';
 import type { AcceptedAuthority, AuthorityPolicy, RequestAuthenticator, WorkRevocationPolicy } from '../auth/authority.js';
 export interface ConversationRecord {
@@ -9,7 +9,7 @@ export interface ConversationRecord {
     bindingId: string;
     lastUserMessage?: Message;
     status: Status;
-    responder: Sender;
+    responder: AuthorType;
     context: JsonObject;
     events: ConversationEvent[];
     eventWindow?: {
@@ -43,7 +43,7 @@ export interface MessageRecord {
 }
 export interface ConversationStoreState {
     cursorStatus?: 'expired' | 'invalid';
-    version: 1;
+    version: 2;
     generation: string;
     conversations: Record<string, ConversationRecord>;
     bindings: Record<string, {
@@ -76,8 +76,8 @@ export interface ConversationOptions {
     authorizeOperator?: (operator: unknown, conversationId: string) => Promise<void>;
     /** Mandatory for requestAuthorization: the scopes the issuer's Direct Sign-In grants; work may ask only for these. */
     directScopes?: readonly string[];
-    /** Scopes that allow reading account-bound history; default ['poppy:read']. A Company offering only custom scopes sets its own. */
-    historyScopes?: readonly string[];
+    /** Required nonempty company scopes for account-bound history. */
+    historyScopes: readonly string[];
 }
 export interface WorkRef {
     workId: string;
@@ -93,7 +93,7 @@ export interface ConversationService {
     handle(request: Request): Promise<Response>;
     claim(): Promise<WorkClaim | null>;
     renew(work: WorkRef): Promise<void>;
-    /** Conversation history for a model or handler; account-bound history needs the bound account and poppy:read. */
+    /** Conversation history for a model or handler; account-bound history needs the bound account and configured historyScopes. */
     history(work: WorkRef): Promise<ConversationEvent[]>;
     /** Account-use gate: call before any account read or tool. Checks accepted authority, then binds the shared ownership once. */
     requireAccount(work: WorkRef, scopes: readonly string[]): Promise<{
@@ -109,7 +109,7 @@ export interface ConversationService {
     handoff(work: WorkRef): Promise<void>;
     /** The company closes the conversation (and its open Direct Conversation); idempotent. */
     close(work: WorkRef): Promise<void>;
-    /** A person joins: automated work is fenced and the returned claim publishes with sender human. Renew it within operatorLeaseMs. */
+    /** A person joins: automated work is fenced and the returned claim publishes with author.type human. Renew it within operatorLeaseMs. */
     joinHuman(operator: unknown, conversationId: string): Promise<WorkClaim>;
     /** Nobody can join a queued conversation: the agent says why and the conversation leaves the queue. No-op unless queued. */
     noHumanAvailable(operator: unknown, conversationId: string, reason: string): Promise<void>;