@poppykit/client 0.4.1 → 0.6.0

package/OPERATIONS.md

@@ -0,0 +1,120 @@
+# Business operations (Operations v2)
+
+Operations are optional on the wire and have no separate endpoint. Both verified
+metadata documents must list `extensions.operations.version: "2"`. Publish support
+only after configuring trusted consent, durable attempt storage and recovery for
+every API, MCP and conversation interface your agent uses. Import `operationsV2`
+for the metadata value; the SDK never advertises it automatically. OAuth consent,
+provider enrollment, Company text and model output never approve business work.
+
+`BusinessOperation` has `operation_id`, `revision`, `summary`, optional object
+`terms`, and RFC3339 `expires_at`. `OperationApproval` names the exact ID/revision.
+`parseBusinessOperation`, `parseOperationApproval`, `parseApprovalHeader`,
+`approvalHeader`, `mcpApproval` and `approvalMetaKey` implement the wire contract.
+Unknown JSON members survive; unknown valid Structured Field members are ignored.
+The pinned RFC9651 parser has no runtime dependencies. The API body snapshot is
+base64, preserving arbitrary bytes and the complete URL/query.
+
+## Trusted client
+
+Configure `createOperationClient` with:
+
+- `store`: `SqliteBusinessAttemptStore(path,namespace)`,
+  `PostgresBusinessAttemptStore(pool,namespace)`, or `BusinessAttemptStore`.
+- `context`: `() => auth.businessContext(connectionId)`. This reads current
+  verified Company/client metadata and binds Company, User, client and local
+  authority. Signed-in contexts use the local grant identity; signed-out contexts
+  use the exact sid. Separate grants are conservatively distinct because OAuth
+  does not expose a portable account identifier. Share the same grant via
+  `start(domain,{accountFrom})` for an account continuation in another Session.
+- `consent.confirm`: your trusted interface, outside model tools. Display the
+  Company name, exact summary and comparison differences. Treat all of them as
+  inert literal text, including terminal controls; render no links, images or
+  HTML. Collect a fresh actual User answer for each operation/revision. Only this
+  callback can transition a pending attempt to approved. Return `approve` or
+  `decline`; a thrown/interrupted callback never becomes approval.
+- `checkTerms`: trusted comparison of the saved request, summary and structured
+  terms. Return discrepancies for the UI to display. The SDK cannot establish
+  the semantic agreement of arbitrary Company business JSON.
+- `send`: `createOperationSender` with the actual channel integrations below.
+
+Choose one stable local attempt ID per business action in trusted application
+code. Keep that ID through revisions and recovery; do not let a model invent a
+new attempt ID to bypass an unresolved action. A received revision is persisted
+with its original request before asking the User. Authentication lifecycle
+`OperationRecord`/`AuthOutcome.operationId`, provider operation IDs, conversation
+message receipts and business attempt IDs are separate concepts/stores.
+
+`receiveApi(id,originalRequest,response)` accepts a 403 `approval_required`.
+`receiveMcp(id,{channel:'mcp',url,name,arguments},toolResult)` accepts
+`isError:true` and `structuredContent.operation`.
+`receiveConversation(id,{channel:'conversation',endpoint,conversationId},message)`
+accepts only a recorded Company message's operation. None reports an action done.
+`receive` is the lower-level equivalent for an already validated channel result.
+It rejects changed terms under the same revision and replacing uncertain work.
+A new revision before sending requires fresh consent and invalidates late UI
+answers; previous decisions remain in the attempt.
+
+Call `requestConsent(id)`, then explicitly `retry(id)`. There is no `approve` API
+or unattended consent flag. Rejection, withdrawal and expiry are durable.
+`get` reads a bound attempt. `recover(after?,limit=100)` pages pending IDs and
+returns attempts or ownership errors without sending or approving anything.
+After dismissing an interrupted UI, `resumeConsent` fences its late answer and
+requires a new one. `withdraw` cancels a local dispatch through its AbortSignal.
+Channel adapters must observe that signal before actual dispatch. After a send
+may have started, withdrawal preserves uncertainty and suppresses later retries;
+it does not claim to cancel the Company's effect.
+
+`retry` commits uncertainty before sending. A crash, network error, authorization
+failure, new operation on retry, or 503 retains the same request and approval.
+Respect the stored `retryAt`; expiry after dispatch does not discard an uncertain
+attempt. Do not ask for another operation until the old action's outcome is known.
+Use `reconcile(id,lookup)` with trusted business-state lookup; a new operation is
+not evidence of failure. Completed results cannot be overwritten by late sends.
+
+## Channel adapters
+
+`createOperationSender({api,mcp,conversation})` preserves the saved channel:
+
+- API: implement `api(request,context)` with `auth.apiFetch(connectionId,request,target,
+  scopes,context)` using the verified original target. `approvedApiRequest` repeats the
+  exact method, URL and bytes with `Poppy-Approval`. It drops the initial
+  Idempotency-Key; approved retries use the operation ID and no additional key.
+  Saved headers exclude credentials/cookies. Successful final status, headers and body
+  are stored as JSON (body base64); HTTP202 and non-success remain uncertain with Retry-After.
+- MCP: implement `mcp(url,params,signal,context)` with your authenticated Streamable HTTP
+  transport. `approvedMcpParams` repeats the original tool/arguments with approval
+  in `params._meta['personalagentprotocol.org/approval']`. Preserve HTTP503 and
+  Retry-After as a pending delivery in custom transport adapters. An error tool
+  result remains uncertain, including a new operation.
+- Conversation: configure `createConversationClient` with `operations:{client,
+  company}` from verified metadata. Both must advertise v2. Implement
+  `conversation(binding,message,signal,context)` with that client's `send` and original
+  conversation ID. `approvedConversationMessage` is approval-only and retains its
+  message ID on retry. Acceptance is pending, not completion; reconcile the later
+  business result. Event pages and SSE support operation-only Company messages.
+
+Raw serialization helpers are trusted low-level APIs; exposing them as model
+approval tools would violate the consent contract. Account credentials remain
+inside the authentication lifecycle, never in consent inputs or model messages.
+
+## Persistence and migration
+
+Attempt format is version1, separate from auth v3. SQLite creates the additive
+`business_attempts(ns,id,body)` table. PostgreSQL uses existing
+`poppy_client.records`, kind `business_attempts`; no applied SQL migration changes.
+Existing rows, grants and pending/uncertain work are untouched. Use a private
+namespace per local user/client and protect stored requests/terms/results as
+personal data. Custom adapters serialize absent-row races across processes,
+reject async callbacks/non-JSON/unknown versions, roll back on exceptions, return
+detached snapshots and page nonterminal IDs in ascending binary order. Run
+`runBusinessAttemptAdapterContract` from the adapter-contract subpath. Never prune
+uncertain attempts. Explicit application retention may archive terminal decisions
+only after recovery references no longer need them; storage removal is not remote
+cancellation. Bundled adapters preserve all decisions by default.
+
+Run `node examples/operations.mjs --self-check` for a local synthetic flow that
+declines without dispatch. Without the flag it asks through a terminal interface.
+See tests/operations.test.mts for independent-wire and real persistent cases.
+
+Every sender callback receives the original `BusinessClientContext`. Pass it as the final `expectedContext` argument to `auth.apiFetch` or `auth.authorizedFetch`, including conversation approval dispatch. The authentication lifecycle checks it through metadata/credential waits and retries, so a changed Session/account cannot silently supply replacement authority. Custom MCP transports must pin that same context through their final dispatch.

package/PROVIDER.md

@@ -75,18 +75,18 @@ const provider = createProvider({
     const human = await operatorLogin.authenticateEnrollment(request);
     return human ? { subject: human.stableSubject, allowedCompanies: human.companyDomains } : null;
   },
-  verifySession: binding => operatorSessionVerifier.owns(binding),
 });
 // Route Fetch Requests under /v1/{operation}, plus the exact public URLs above:
 // await provider.handle(request)
 ```
 
-`operatorKeys`, `operatorLogin`, `operatorSessionVerifier` and
-`verifiedCompanyResolver` are operator-owned adapters, not globals supplied by
-the package. A session verifier must independently verify both the provider client
-and derived UserID; an opaque session ID alone does not prove ownership. Browser
-signing fails closed without that verifier. Starting a session signs a derived
-UserID assertion; the company checks session/client/UserID association on renewals.
+`operatorKeys`, `operatorLogin` and `verifiedCompanyResolver` are operator-owned
+adapters. A new enrollment receives a unique HTTPS client metadata URL beneath
+the configured clientId path. Serve that exact URL through provider.handle; the
+shared JWKS and callback remain unchanged. A shared origin does not make those
+client IDs interchangeable. Existing shared-client enrollments are retained for
+legacy assertion/cleanup, but cannot receive delegations; obtain fresh explicit
+enrollment rather than transferring old account grants to a different client ID.
 
 POST JSON operations use `version: 1` and `installationId`. Enroll additionally
 takes a fresh `idempotencyKey`; private operations carry `Authorization: Bearer
@@ -99,11 +99,14 @@ but cannot recover another installation's result. Enrollment never accepts calle
 subjects, arbitrary audiences, lifetimes, key IDs, raw bytes or signing claims.
 
 `identity` takes domain and exact issuer; `begin` registers immutable operation,
-issuer/domain, purpose (`session`, `client-authentication`, `browser`, `direct`),
-optional session and browser return destination. Company metadata is independently
+issuer/domain, purpose (`client-authentication`, `direct`) and the Direct OAuth DPoP thumbprint (or explicit null for an unbound Bearer code). Company metadata is independently
 resolved and enrollment company policy checked. `assert` takes operation/purpose
-only and constructs a 60-second assertion with fresh 256-bit jti. Browser assertions
-are audience-bound to the verified browser endpoint. `createProviderClient` binds
+only and constructs a 60-second assertion with fresh 256-bit jti. New Sessions use `delegate({operationId,jwk})`: an enrollment restricted to one
+Company can obtain a cnf-only ES256 delegation with coarse half-hour issuance and a one-hour signed lifetime for a public P-256 key.
+The payload contains no User/Company claims. Legacy shared-client and multi-Company
+enrollments are refused. Delegation results are encrypted for idempotent delivery,
+expired results/tombstones are pruned before the 1000-operation cap. Browser joining
+uses separate code authorization with the finalized Session JWT. `createProviderClient` binds
 enrollment credentials and automatically registers SDK assertion operations.
 
 Direct sign-in uses SDK-generated 256-bit state. Trusted CLI code privately
@@ -112,7 +115,10 @@ authorization URL. Only its hash is indexed. The callback accepts state, exact
 issuer, and exactly one code/error; result ciphertext is sealed atomically with
 the immutable binding. Identical pending callbacks are harmless; conflicting,
 canceled, expired and consumed callbacks fail. `takeResult` requires enrollment,
-installation, operation, issuer and exact session; it consumes within the same
+installation, operation, issuer and exact `sessionKey` thumbprint from the SDK's
+authorization URL `dpop_jkt`; the local `Connection.sessionId` cannot identify a
+company Session. Old Direct operations without the key binding must restart.
+Retrieval consumes within the same
 storage transaction before returning private callback data. Lost retrieval delivery
 is uncertain, never a reason to exchange or retrieve again. SDK code owns PKCE and
 the exchange. Never log request URLs or responses on this route.
@@ -140,8 +146,8 @@ expires plus 30-second skew; never publish private JWK fields. The operator owns
 the publication grace period and KMS key lifecycle.
 
 Enrollment revocation stops new signing/retrieval and cancels pending results.
-It cannot invalidate delivered assertions, existing company Session Tokens,
-Account Tokens or DPoP keys. Revoke company authorization **before** disabling
+It cannot invalidate delivered assertions, existing delegated Session JWTs,
+OAuth account credentials or DPoP keys. Revoke company authorization **before** disabling
 provider signing, or use authenticated company account controls afterward.
 This is scoped authority, redaction and provider key custody; it does not isolate
 authority from unrestricted programs running as the same OS user.
@@ -168,3 +174,7 @@ and cannot turn local synchronous I/O into remote persistence. New remote/custom
 stores implement the targeted contract directly. The bundled Postgres adapter is
 `PostgresProviderStore` from `@poppykit/client/provider/postgres`; see
 [storage](STORAGE.md) for explicit migrations, TLS and lifecycle.
+
+## Operations capability metadata
+
+Provider authentication/callback operations are not business operations. Optional `operations:{ready(enrollmentId)}` publishes `extensions.operations.version:"2"` only for that isolated enrollment when its complete agent consent, all used channels and durable recovery are installed. Omission/false publishes nothing. The legacy shared client document never advertises v2. Readiness must reflect host configuration, never Company/model claims or enrollment/OAuth approval. [OPERATIONS.md](OPERATIONS.md) defines the separate business contract.

package/README.md

@@ -1,18 +1,10 @@
 # PoppyKit client
 
-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 [Personal Agent Protocol draft 0.2](https://personalagentprotocol.org/docs/0.2/spec):
-discovery, authentication, conversations and API/browser/feedback hooks. Your
-application supplies the agent and trusted infrastructure. [MIT](LICENSE).
+TypeScript SDK for [Personal Agent Protocol draft 0.3](https://personalagentprotocol.org/docs/0.3/spec).
+Discover companies, authenticate and manage conversations. [MIT](LICENSE).
 
 ## Install
 
-This source contains unreleased repairs; final version selection and publication are pending.
-
-Requires Node **24.x, at least 24.21.0**, ESM and HTTPS. CI tests Node 24.21.0 on Linux, macOS and
-Windows; other Node majors are unsupported.
-
 ```sh
 npm install @poppykit/client
 ```
@@ -20,7 +12,7 @@ npm install @poppykit/client
 ## Discover a company
 
 No credentials or database are needed. Replace `company.example` with a company
-publishing draft 0.2 discovery:
+publishing draft 0.3 discovery:
 
 ```js
 import { createMetadataResolver, createNodeTransport } from '@poppykit/client';
@@ -39,6 +31,8 @@ without a network service.
 
 ## Guides
 
+- [Business operations](OPERATIONS.md): exact per-operation approval, durable retries and effect contracts.
+
 - [Authentication](AUTH.md): sessions, Direct/Device/Mediated, consent, renewal and revocation.
 - [Storage](STORAGE.md): targeted adapters, secret references, recovery and explicit resets.
 - [Delivery](DELIVERY.md): messages, streaming, cancellation, retries and retention.
@@ -50,5 +44,5 @@ without a network service.
 Keep Account Tokens, DPoP keys and PKCE in a secure SecretStore; never expose them
 to model tools. An uncertain remote result must not be silently replayed. SQLite
 is optional/experimental and is not vault encryption. Production issuers, vaults,
-browsers and hosting require operator validation; individual extensions and
-application business workflows are outside this SDK.
+browsers and hosting require operator validation; Mediated Sign-In v1 is supported. Application business policy belongs to the host;
+see [protocol boundaries](CONFORMANCE.md).

package/RELEASING.md

@@ -89,3 +89,5 @@ certify a production keyring, physical terminal, browser engine, KMS or TLS depl
 Windows GNU tar is given archive basename plus directory cwd to avoid drive-colon
 remote parsing. Failure logs retain seven days. Expired/missing artifacts require a
 new full run, not relabeling old results. See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+The local Operations SDK checkpoint does not satisfy release acceptance. Complete the block3 CLI business-approval experience and stable all-tests/package/native gates before publication. Operations metadata must remain opt-in to fully configured hosts. Include OPERATIONS.md and both operation examples in candidate archives.

package/SECURITY.md

@@ -11,3 +11,5 @@ impact and the trust boundary involved. These draft packages have no promised
 support window or response SLA. Custom vaults, issuers, browser controllers,
 proxy routing and deployment policy remain operator responsibilities. Redaction
 and scoped authority do not isolate an unrestricted same-user program.
+
+Business-operation approval requires the trusted per-operation UI described in [OPERATIONS.md](OPERATIONS.md). Keep Company/model text separate from user consent. Local effects must share the receipt transaction; arbitrary network effects require host idempotency and reconciliation. Retain uncertain claims until the actual outcome is known.

package/STORAGE.md

@@ -14,15 +14,17 @@ const conversationStore = new SqliteConversationStore('/private/path/messages.db
 ```
 
 Use one auth database per namespace/local user/client identity. The owner tuple is
-checked on every SDK auth read and mutation. Identities are keyed by the exact full
-issuer, connections by immutable IDs, operations by ID and callback state hash,
+checked on every SDK auth read and mutation. Identities are keyed by the exact Company
+identifier, connections by immutable IDs, operations by ID and callback state hash,
 cleanup by connection, and token slots by session/resource. Secret values are never
 stored in auth records: immutable references point to the host's `SecretStore`.
-Session Tokens remain in process memory. Conversation databases contain message
+Access tokens remain in process memory; Session JWTs are freshly signed. Conversation databases contain message
 bodies; operators must provide private storage and their required encryption.
 
-Auth selections load an identity or a connection aggregate (its grants, operations,
-and cleanup), never unrelated connections. Operation/callback selectors resolve the
+Auth selections load an identity or a connection aggregate, including all peers
+referencing its shared grants and their operations/cleanup. An `account: {issuer,
+userId}` selector loads every connection for that Company and pairwise User, its
+identity, grants, operations and cleanup; account-wide sign-out is one transaction. Operation/callback selectors resolve the
 owning connection through indexes. `list` explicitly enumerates connections.
 Recovery pages nonterminal operation IDs in batches of 100, then rechecks each
 operation and its owner inside its transaction. `cleanup(before, limit)` removes
@@ -88,6 +90,19 @@ recovery of a token that the issuer rotated but never delivered.
 
 ## Development reset
 
+Normalized auth state versions 1 and 2 upgrade to version 3 atomically on first access
+in both SQLite and PostgreSQL, under the namespace's writer lock. Stop old SDK
+processes before opening the candidate adapters; mixed-version writers are not
+supported. This is a record upgrade, with no SQL schema change. Owner, epoch,
+stable User IDs, grants, scopes, cleanup and internal connection/operation IDs stay.
+Legacy connections discard their volatile token slots and require a fresh key on
+next renewal. Old shared-key references remain retained, but are never used for
+another token request. Prepared old operations are cancelled and private verifier/device references are
+queued for cleanup before history can be pruned; dispatched/staged
+ones still pass through `recover()`, preserving rotated tokens and uncertainty.
+Custom targeted adapters must provide the same complete-namespace upgrade under
+their writer lock; the client's fallback also upgrades whole-state snapshots.
+
 There is no automatic migration from old whole-state development stores. Stop all
 users of a disposable store, resolve uncertain remote outcomes, and explicitly move
 aside its database and WAL/SHM files and the matching host-managed secret namespace
@@ -171,3 +186,7 @@ transaction handle. It uses the supplied handle rather than its configured pool;
 the host owns the entire commit/rollback. Savepoints protect individual provider
 operations, while the host must abort the outer transaction on failure. Never
 span model/network I/O. See the [provider example](PROVIDER.md).
+
+## Business operation persistence
+
+[Operations storage contracts](OPERATIONS.md#persistence-and-migration) are separate from authentication lifecycle operations and message receipts. BusinessAttemptStore uses a synchronous transaction callback and an ascending nonterminal `pending` selector. SQLite adds a separate business_attempts table; PostgreSQL uses a separate record kind. No existing SQL history, credentials or uncertain work is deleted. Unknown versions fail closed. External effects require a durable downstream idempotency/reconciliation contract. Never prune or release an uncertain business claim after a worker deadline.

package/dist/adapter-contract.d.ts

@@ -13,3 +13,9 @@ export type ProviderAdapterFixture = () => Promise<{
 /** Run against two handles sharing a fresh namespace; real engine/process tests remain the host's responsibility. */
 export declare function runClientConversationAdapterContract(fixture: ClientConversationAdapterFixture): void;
 export declare function runProviderAdapterContract(fixture: ProviderAdapterFixture): void;
+export type BusinessAttemptAdapterFixture = () => Promise<{
+    store: import('./operations.js').BusinessAttemptStore;
+    second: import('./operations.js').BusinessAttemptStore;
+    close(): Promise<void>;
+}>;
+export declare function runBusinessAttemptAdapterContract(fixture: BusinessAttemptAdapterFixture): void;

package/dist/adapter-contract.js

@@ -6,7 +6,7 @@ export function runClientConversationAdapterContract(fixture) {
         const f = await fixture();
         try {
             const key = { connectionId: 'contract', issuer: 'https://issuer.example/one', endpoint: 'https://company.example/conversations' };
-            const row = { ...key, id: 'message', fingerprint: 'original', phase: 'pending', target: null, request: { message: { id: 'message', sender: 'agent', text: 'hello' } } };
+            const row = { ...key, id: 'message', fingerprint: 'original', phase: 'pending', target: null, request: { message: { id: 'message', author: { type: 'agent' }, text: 'hello' } } };
             const saved = await Promise.all([f.store.prepareOutbound(key, row), f.second.prepareOutbound(key, { ...row, fingerprint: 'changed' })]);
             assert.equal(saved[0].fingerprint, saved[1].fingerprint);
             saved[0].request.message.text = 'mutated';
@@ -46,3 +46,33 @@ export function runProviderAdapterContract(fixture) {
         }
     });
 }
+export function runBusinessAttemptAdapterContract(fixture) {
+    test('business attempt adapter contract: serial consent claims, detached recovery, rollback and version fences', async () => {
+        const f = await fixture();
+        try {
+            const record = { version: 1, id: 'action', context: { companyId: 'https://company.example', companyName: 'Company', clientId: 'https://agent.example/client', userId: 'user', authority: 'session:sid', operations: true }, request: { channel: 'conversation', endpoint: 'https://company.example/conversations', conversationId: 'conversation' }, operation: { operation_id: 'operation', revision: 'revision', summary: 'Cancel booking', expires_at: '2030-01-01T00:00:00Z' }, phase: 'pending_consent', messageId: 'message' };
+            await f.store.transaction(record.id, slot => { slot.record = record; });
+            let claims = 0;
+            await Promise.all([f.store, f.second].map(store => store.transaction(record.id, slot => { if (slot.record.phase === 'pending_consent') {
+                slot.record.phase = 'consenting';
+                claims++;
+            } })));
+            assert.equal(claims, 1);
+            assert.deepEqual(await f.second.pending(undefined, 10), ['action']);
+            const read = () => f.store.transaction(record.id, slot => structuredClone(slot.record));
+            const value = await read();
+            value.operation.summary = 'mutated';
+            assert.equal((await read()).operation.summary, 'Cancel booking');
+            await assert.rejects(f.store.transaction(record.id, slot => { slot.record.phase = 'approved'; throw Error('rollback'); }), /rollback/);
+            await assert.rejects(f.store.transaction(record.id, async (slot) => { slot.record.phase = 'approved'; }));
+            await assert.rejects(f.store.transaction(record.id, slot => { Object.assign(slot.record, { version: 99 }); }), /binding|version/);
+            assert.equal((await read()).phase, 'consenting');
+            for (const id of ['A', 'Z', '_', 'a'])
+                await f.store.transaction(id, slot => { slot.record = { ...record, id }; });
+            assert.deepEqual(await f.second.pending('Z', 10), ['_', 'a', 'action']);
+        }
+        finally {
+            await f.close();
+        }
+    });
+}

package/dist/auth/challenge.d.ts

@@ -3,12 +3,14 @@ export declare function schemeChallenge(header: string | null, scheme: 'DPoP' |
     scope?: string;
     extension?: string;
     conversation_id?: string;
+    resource_metadata?: string;
 } | undefined;
 export declare const dpopChallenge: (header: string | null) => {
     error?: string;
     scope?: string;
     extension?: string;
     conversation_id?: string;
+    resource_metadata?: string;
 } | undefined;
 export interface AuthChallenge {
     error?: string;

package/dist/auth/challenge.js

@@ -1,4 +1,4 @@
-// Reads the DPoP challenge from a WWW-Authenticate header (RFC 9110 11.6.1, spec 6); other schemes' params are ignored.
+// Read only the requested scheme; commas inside quoted attributes are not challenge boundaries.
 const TOKEN = /[A-Za-z0-9!#$%&'*+.^_`|~-]+/y;
 export function schemeChallenge(header, scheme) {
     if (!header)
@@ -50,7 +50,7 @@ export function schemeChallenge(header, scheme) {
             i += value.length;
         }
         const name = match[0].toLowerCase();
-        if (current.scheme === scheme.toLowerCase() && ['error', 'scope', 'extension', 'conversation_id'].includes(name))
+        if (current.scheme === scheme.toLowerCase() && ['error', 'scope', 'extension', 'conversation_id', 'resource_metadata'].includes(name))
             current.params[name] = value;
     }
     return found;
@@ -58,11 +58,11 @@ export function schemeChallenge(header, scheme) {
 export const dpopChallenge = (header) => schemeChallenge(header, 'DPoP');
 // Combine independent detail channels: a sparse JSON error must not erase header scopes/extensions.
 export function authChallenge(header, body) {
-    const challenge = dpopChallenge(header), json = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
-    const scopes = [challenge?.scope, json.scope].flatMap(value => typeof value === 'string' ? value.split(' ').filter(scope => /^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope)) : []);
-    const extensions = [challenge?.extension, json.extension].filter((value) => typeof value === 'string' && value.length <= 512 && /^(?:[A-Za-z0-9._-]+|(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*)$/.test(value));
-    const safe = new Set(['sign_in_required', 'insufficient_scope', 'invalid_token', 'invalid_dpop_proof', 'use_dpop_nonce', 'extension_required', 'rate_limited', 'invalid_scope']);
-    const error = [challenge?.error, json.error].find((value) => typeof value === 'string' && safe.has(value));
-    const conversationId = [json.conversation_id, challenge?.conversation_id].find((value) => typeof value === 'string' && value.length > 0 && value.length <= 256);
+    const preferred = dpopChallenge(header) ?? schemeChallenge(header, 'Bearer'), challenges = preferred ? [preferred] : [], json = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+    const scopes = [...challenges.map(value => value.scope), json.scope].flatMap(value => typeof value === 'string' ? value.split(' ').filter(scope => /^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope)) : []);
+    const extensions = [...challenges.map(value => value.extension), json.extension].filter((value) => typeof value === 'string' && value.length <= 512 && /^(?:[A-Za-z0-9._-]+|(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*)$/.test(value));
+    const safe = new Set(['insufficient_scope', 'invalid_token', 'invalid_dpop_proof', 'use_dpop_nonce', 'extension_required', 'rate_limited', 'invalid_scope', 'invalid_session']);
+    const error = [...challenges.map(value => value.error), json.error].find((value) => typeof value === 'string' && safe.has(value));
+    const conversationId = [json.conversation_id, ...challenges.map(value => value.conversation_id)].find((value) => typeof value === 'string' && value.length > 0 && value.length <= 256);
     return { ...(error ? { error } : {}), requiredScopes: [...new Set(scopes)], extensions: [...new Set(extensions)], ...(conversationId ? { conversationId } : {}) };
 }

package/dist/auth/client-auth.d.ts

@@ -1,3 +1,5 @@
+import type { BusinessClientContext } from '../operations.js';
+import type { Alternative, ExcludedTask } from '../network/tasks.js';
 import type { AuthSelection, AuthStore } from './store.js';
 import type { OperationOwner } from './ownership.js';
 import type { JsonObject } from '../protocol/wire.js';
@@ -18,20 +20,20 @@ export interface IdentitySigner {
 export type AssertionRequest = {
     operationId: string;
     issuer: string;
-} & ({
     purpose: 'client-authentication';
-} | {
-    purpose: 'session';
-} | {
-    purpose: 'browser';
-    sessionId: string;
-    returnTo: string;
-});
+};
 export interface AssertionProvider {
     assert(request: AssertionRequest): Promise<{
         assertion: string;
         expiresAt: number;
     }>;
+    delegate?(request: {
+        operationId: string;
+        jwk: JsonObject;
+    }): Promise<{
+        delegation: string;
+        expiresAt: number;
+    }>;
 }
 export interface ProviderIdentity {
     identity(issuer: string): Promise<{
@@ -41,6 +43,7 @@ export interface ProviderIdentity {
 }
 export type SignInMethod = 'direct' | 'device' | 'mediated';
 export interface AuthorizationRequirement {
+    scopeDescriptions?: Record<string, string>;
     requiredScopes: string[];
     grantedScopes: string[];
     missingScopes: string[];
@@ -149,9 +152,11 @@ export interface ConversationTarget {
 export interface ClientAuth {
     start(domain: string, input?: {
         anonymous?: boolean;
+        accountFrom?: string;
     }): Promise<AuthOutcome>;
     get(connectionId: string): Promise<Connection | null>;
     list(): Promise<Connection[]>;
+    businessContext(connectionId: string): Promise<BusinessClientContext>;
     target(connectionId: string): Promise<ConversationTarget>;
     authorization(connectionId: string, requiredScopes: readonly string[]): Promise<AuthorizationRequirement>;
     beginSignIn(connectionId: string, input: SignInInput): Promise<SignInStart>;
@@ -169,11 +174,12 @@ export interface ClientAuth {
     signOut(connectionId: string): Promise<SignOutOutcome>;
     retryCleanup(connectionId: string): Promise<SignOutOutcome>;
     recover(): Promise<AuthOutcome[]>;
-    authorizedFetch(connectionId: string, request: Request, target: ConversationTarget, requiredScopes?: readonly string[]): Promise<Response>;
+    authorizedFetch(connectionId: string, request: Request, target: ConversationTarget, requiredScopes?: readonly string[], expectedContext?: BusinessClientContext): Promise<Response>;
     apiTarget(connectionId: string, apiUrl: string, destination?: string): Promise<ApiTarget>;
-    apiFetch(connectionId: string, request: Request, target: ApiTarget, requiredScopes?: readonly string[]): Promise<Response>;
+    apiFetch(connectionId: string, request: Request, target: ApiTarget, requiredScopes?: readonly string[], expectedContext?: BusinessClientContext): Promise<Response>;
     joinBrowser(connectionId: string, returnTo: string, controller: AgentBrowserController): Promise<void>;
-    feedback(connectionId: string, report: FeedbackReport): Promise<void>;
+    feedback(connectionId: string, report: FeedbackReport): Promise<Alternative | void>;
+    excludedTasks(connectionId: string): Promise<ExcludedTask[]>;
 }
 export interface CredentialRecord {
     secretRef: string;
@@ -197,6 +203,13 @@ export interface ConnectionRecord {
     slots: Record<string, CredentialRecord>;
     anonymous?: boolean;
     notBefore?: string;
+    needsSessionKey?: boolean;
+    sessionSigning?: {
+        keyRef: string;
+        delegationRef: string;
+        expiresAt: number;
+    };
+    signingCleanup?: string[];
 }
 export interface GrantRecord {
     id: string;
@@ -239,6 +252,7 @@ export interface OperationRecord {
     method?: SignInMethod;
     requiredExistingScopes?: string[];
     signInSessionId?: string;
+    signInSessionKey?: string;
     device?: {
         codeRef: string;
         intervalMs: number;
@@ -270,7 +284,7 @@ export interface CleanupRecord {
     notBefore?: string;
 }
 export interface ClientAuthState {
-    version: 1;
+    version: 1 | 2 | 3;
     epoch: string;
     owner: {
         namespace: string;
@@ -279,7 +293,7 @@ export interface ClientAuthState {
     } | null;
     identities: Record<string, {
         userId: string;
-        dpopKeyRef: string;
+        dpopKeyRef?: string;
     }>;
     connections: Record<string, ConnectionRecord>;
     grants: Record<string, GrantRecord>;
@@ -294,4 +308,6 @@ export declare class AuthFailure extends Error {
     constructor(code: string, connectionId?: string | undefined, retryAfterMs?: number | undefined, retryAt?: string | undefined);
 }
 export declare function initialClientAuthState(): ClientAuthState;
+/** Upgrade a complete namespace under its writer lock; dispatched/staged work still goes through recover(). */
+export declare function upgradeClientAuthState(state: ClientAuthState): void;
 export declare function createClientAuth(options: ClientAuthOptions): ClientAuth;