@poppykit/client 0.3.0 → 0.4.1

package/API.md

@@ -27,3 +27,12 @@ or general API executors.
 The optional Postgres entry point ships its adapters, `createPostgresPool`,
 `postgresMigration`, `migratePostgres` and schema-version export; see [storage](STORAGE.md).
 TypeScript Postgres consumers also install `@types/pg@8.23.1` as a development dependency.
+
+Custom `AuthStore` implementations must honor `AuthSelection.history` as described
+in [STORAGE.md](STORAGE.md). Provider callbacks now acknowledge identical consumed
+results without making `takeResult` reusable; see [PROVIDER.md](PROVIDER.md).
+
+`PostgresProviderStore.withTransaction(connection, action)` and its structural
+`PostgresConnection` type are exported only by `@poppykit/client/provider/postgres`.
+They explicitly enlist provider SQL in a host-owned guarded transaction; the host
+retains commit/rollback, deadline and privilege responsibility.

package/AUTH.md

@@ -16,6 +16,11 @@ implements this adapter. Values are cleared after each submission and never
 persisted by the SDK or exposed in public results. Input adapters must not log
 values, keep copies, or return them through model tools.
 
+Direct callbacks accept OAuth error details and ignore unknown response fields.
+The registered origin/path/query, browser binding, state and exact issuer still
+have to match; duplicate recognized fields and a simultaneous code/error fail.
+Error descriptions and error URLs are never included in public auth outcomes.
+
 First-time partial grants complete with `grantedScopes` and `missingScopes`.
 Replacement preserves every old grant scope by default. An explicit
 `requiredExistingScopes` subset permits dropping other old scopes. A rejected
@@ -43,6 +48,17 @@ separate local `IdentitySigner` is required and its key must also be published i
 the client's JWKS. A provider-only configuration reports `anonymous_unavailable`;
 it never substitutes the provider's stable identity for an anonymous one.
 
+Provider `expiresAt` values are Unix seconds. Session/client assertions and browser
+joins accept a local freshness horizon of 60 seconds plus 30 seconds of clock skew;
+an assertion at or before the local current time is rejected. This freshness check
+does not verify the signed assertion's lifetime: the issuer verifies the signature,
+claims, replay and protocol maximum of five minutes between `iat` and `exp`.
+`provider_clock_skew` and `provider_assertion_expired` suggest checking automatic
+date/time and retrying. `provider_invalid_response`, `provider_unauthorized`,
+`provider_rate_limited` and `provider_network_error` distinguish malformed data,
+enrollment rejection, throttling and connectivity. Unknown failures remain
+`provider_unavailable`. Errors never include assertion or provider response text.
+
 Account Tokens, device codes, PKCE and DPoP keys belong in the configured
 SecretStore; Session Tokens stay in memory. SQLite and secret storage are separate
 commit boundaries. A host must sweep orphan staged secrets only after checking

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.4.1
+
+Support Node 24.21.0 and later within Node 24 under the owner-accepted runtime policy.
+Build, verification and publication tooling read .node-version.
+
+## 0.4.0
+
+Require Node 24 >=24.22.1 within 24.x. Accept conforming OAuth callback fields,
+decode chunked UTF-8 strictly and bound durable terminal-operation history.
+Custom auth stores must implement the documented `history` selection. The
+explicit provider Postgres adapter can enlist in a guarded host transaction for
+atomic consent delivery; protocol-only imports still load no database drivers.
+Required release verification now includes isolated PostgreSQL contracts.
+
+## 0.3.1 (release candidate)
+
+Allow 30 seconds of provider clock skew in the local assertion freshness check,
+including browser joins. Already-expired assertions remain rejected; the issuer
+still verifies signatures, signed lifetime and replay. Safe errors now distinguish
+clock/expiry, malformed responses, provider authorization, rate limits and network
+failure. No wire protocol, storage format or dependency change.
+
 ## 0.3.0 (release candidate)
 
 Add the optional challenge-bound browser enrollment client under `/provider`.

package/CONTRIBUTING.md

@@ -5,8 +5,8 @@ and [guides](https://personalagentprotocol.org/docs/0.2/guides). Tests/snapshots
 supporting evidence. Demo/business workflows and individual extensions are excluded.
 Code is [MIT](LICENSE); confirm rights for third-party contributions.
 
-Use Node 24.12.0, TypeScript 5.9.3 and @types/node 24.10.0.
-Install the packageManager-pinned pnpm and run pnpm install --frozen-lockfile.
+Use Node 24.21.0, TypeScript 5.9.3 and @types/node 24.10.0.
+Install the packageManager-pinned pnpm and run pnpm install --frozen-lockfile --ignore-scripts.
 
 ```sh
 npm run typecheck
@@ -36,3 +36,11 @@ Preserve credential/destination validation, private errors and persisted data.
 Report checks actually run and limits. Use Issues for non-sensitive defects and
 [SECURITY.md](SECURITY.md) for vulnerabilities. Follow [RELEASING.md](RELEASING.md)
 before tagging/publishing; obtain explicit owner authorization.
+
+Required CI also runs scripts/postgres-ci.mjs in a dedicated disposable PostgreSQL17
+cluster with POPPY_DISPOSABLE_POSTGRES=1, D1_LOCAL=1 and explicit loopback PGHOST,
+PGPORT, PGUSER, PGPASSWORD, PGDATABASE. Build production/tests first; use a fresh
+database without SDK schemas. Never point it at shared/cloud data. It migrates
+only this package's schemas, runs all named durable suites, rejects skips/missing
+discovery and leaves cluster destruction to its owner. Default source-suite skips
+do not replace this gate. See the workflow for the pinned image and setup.

package/PROVIDER.md

@@ -14,7 +14,7 @@ Import `createProvider`, `createProviderClient`, and `createResultCipher` from
 `@poppykit/client/provider`; durable `SqliteProviderStore` is separately exported
 from `@poppykit/client/provider/sqlite`. Neither is loaded by the core import.
 The wire protocol remains PoppyKit provider **v1**; the 0.2 TypeScript API uses async storage, not a Personal Agent Protocol extension.
-Node 24.12+ is required for the SQLite reference adapter.
+Node 24.x (at least 24.21.0) is required for the SQLite reference adapter.
 
 An operator supplies HTTPS hosting, a provider client metadata URL, JWKS URL,
 HTTPS callback URL on that same domain, an ES256 signer/KMS, a verified company
@@ -22,6 +22,44 @@ metadata resolver, authenticated enrollment and encrypted callback-result storag
 The provider has no company account-token vault, token-exchange proxy, login UI,
 deployment dependency or cloud dependency.
 
+HTTP JSON is limited to 16 KiB of UTF-8 bytes. Chunk boundaries preserve Unicode;
+invalid/truncated UTF-8 fails before enrollment, signing or operation creation.
+Callbacks accept optional OAuth error details and unknown response fields while
+checking state/issuer, destination and duplicate recognized fields. An identical
+callback after consumption acknowledges `consumed` without recreating ciphertext;
+a changed callback conflicts. `takeResult` remains one-time, including after restart.
+
+`ProviderError` codes `unauthorized`, `expired` and `canceled` are definite
+rejections. `consumed` means retrieval already happened and does not prove the
+caller staged its result. Network failure, `unavailable` and `invalid_response`
+are ambiguous; preserve uncertainty rather than repeating one-time retrieval.
+`rate_limited` carries a retry deadline. Never expose raw errors, credentials,
+assertions or callback URLs through model tools.
+
+Postgres hosts can explicitly enlist the store in their existing transaction:
+
+```js
+await companyDatabase.withTransaction(async connection => {
+  await providerStore.withTransaction(connection, async () => {
+    const callback = await issuer.completeAuthorization(id, browserBinding, decision);
+    await provider.callback(callback.href);
+    await saveHostReceipt(connection); // host-owned bounded SQL
+  });
+});
+```
+
+The handle must come from `PostgresCompanyDatabase.withTransaction` (or an
+equivalent host guard that rejects expired/escaped handles), on the same database
+with the required provider schema privileges. Normal operations still use the
+configured provider pool; enlisted operations never fall back to it. The host
+owns commit/rollback and must propagate failures to abort the whole transaction.
+Only bounded SQL and synchronous cryptography belong in the scope; no HTTP,
+model, signing service or other remote work. Persist the authenticated human
+decision first, then issue the code, provider-ready callback and host receipt in
+one atomic transaction. A rolled-back attempt can retry that decision; an
+uncertain one-time code/token redemption must never be retried. Escaped participant
+work fails closed. Code/consent lifetimes are unchanged.
+
 ```js
 import { createProvider, createResultCipher } from '@poppykit/client/provider';
 import { SqliteProviderStore } from '@poppykit/client/provider/sqlite';

package/README.md

@@ -1,18 +1,20 @@
 # 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).
 
 ## Install
 
-Version 0.3.0 is a release candidate until its publishing workflow completes.
+This source contains unreleased repairs; final version selection and publication are pending.
 
-Requires Node **24.12.0+**, ESM and HTTPS. CI tests Node 24.12.0 on Linux, macOS and
-Windows; later majors are not separately certified.
+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@0.3.0
+npm install @poppykit/client
 ```
 
 ## Discover a company

package/RELEASING.md

@@ -6,7 +6,7 @@ changing runtime APIs. Each new version needs its own source/artifact evidence.
 
 ## Before tagging
 
-- Confirm npm ownership, unused versions, supported Node 24.12.0 and npm>=11.5.1.
+- Confirm npm ownership, unused versions, supported Node 24.x (at least 24.21.0) and npm>=11.5.1.
   Keep the pinned compiler/dependencies; do not upgrade tooling during a release.
 - Update version, changelog and shipped docs. CLI's client dependency and both
   candidate JSON files must match exact final SDK versions/full source SHAs.
@@ -47,7 +47,7 @@ guard requires its tested client tarball integrity to equal the published one.
    ```
 
 4. Wait for candidate, fast, contracts, integration, packaged-linux/windows/macos,
-   validation and gate to succeed. Missing, failed, canceled or skipped prerequisites
+   validation, postgres and gate to succeed. The postgres job uses its own disposable PostgreSQL17 cluster and the same-run checked candidate/harness; zero discovery or any skipped database case fails. Missing, failed, canceled or skipped prerequisites
    fail closed. Then follow the Actions environment-approval link. Do not bypass it.
 5. The publisher rechecks source/tag/ref/version, trusted manifest digest, unchanged
    tarball metadata/bytes, owner enablement, registry absence and dependency integrity.

package/STORAGE.md

@@ -1,9 +1,8 @@
 # Persistence and recovery
 
-Use targeted storage contracts. Node 24.12.0
-or later is required. The optional `@poppykit/client/sqlite` entry point exports
+Use targeted storage contracts. Node 24.x, at least 24.21.0, is required. The optional `@poppykit/client/sqlite` entry point exports
 `SqliteAuthStore` and `SqliteConversationStore`; importing the client core does not
-load SQLite. `node:sqlite` is experimental in the tested Node 24.12.0 runtime.
+load SQLite. `node:sqlite` is experimental in the tested Node 24.21.0 runtime.
 Consumers can implement `AuthStore` and `ConversationStore` using their own database.
 
 ```ts
@@ -30,6 +29,17 @@ operation and its owner inside its transaction. `cleanup(before, limit)` removes
 only terminal, non-uncertain auth history; the limit is at most 1000. It does not
 erase grants, pending exchanges, uncertain results, or secrets.
 
+Starting a connection or sign-in also selects bounded terminal history with
+`history: true`: at most the newest 201 eligible operation records across this
+auth namespace, without loading their connections. Before creating new work it
+keeps 100 terminal start/sign-in results (creation time, then ID order); the just
+completed result can bring that to 101. Repeated starts drain older excess in
+bounded batches. Pending, dispatched, staged and uncertain operations remain;
+grant references, retirement cleanup and conversation receipts are unaffected.
+Custom AuthStore adapters must honor this history selection. Old pruned callback
+state becomes unknown; uncertain callbacks retain their recorded result and are
+never exchanged again. No vault or connection reset is involved.
+
 Transactions must serialize conflicting domain updates across processes, roll back
 on exceptions, reject asynchronous mutation callbacks and non-JSON persisted values,
 enforce unique keys, and return detached values. SQLite uses WAL, FULL synchronous
@@ -100,7 +110,7 @@ never deletes company history, revokes access or cancels accepted business work.
 The optional `@poppykit/client/postgres` exports `PostgresAuthStore` and
 `PostgresConversationStore`; `/provider/postgres` exports `PostgresProviderStore`.
 Install the optional peer `pg@8.23.1` only when choosing these subpaths.
-Protocol-only imports load neither pg nor SQLite. PostgreSQL 17 and Node 24.12+
+Protocol-only imports load neither pg nor SQLite. PostgreSQL 17 and Node 24.x (at least 24.21.0)
 are supported; plain PostgreSQL and Supabase transaction pooling use the same adapter.
 There is no Supabase Auth or application dependency.
 
@@ -154,3 +164,10 @@ Custom backends can run `runClientConversationAdapterContract` and
 handles to a fresh shared namespace. Real process death and engine atomicity still
 need backend-specific checks. Database credentials and encryption keys stay outside
 records, prompts and logs; provider callback URLs remain encrypted by ResultCipher.
+
+For atomic issuer/provider/host delivery, explicitly enlist `PostgresProviderStore`
+using its `withTransaction(connection, action)` method and the host's guarded
+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).

package/dist/auth/client-auth.js

@@ -26,6 +26,12 @@ const SKEW_MS = 30_000;
 const AMBIGUOUS = new Set(['transport_error', 'invalid_response', 'token_error']);
 const CLIENT_ASSERTION = 'urn:ietf:params:oauth:client-assertion-type:jwt-bearer';
 const ASSERTION_SECONDS = 60;
+function providerFailure(error, connectionId) {
+    const code = error?.code;
+    return new AuthFailure(code === 'unauthorized' ? 'provider_unauthorized' : code === 'rate_limited' ? 'provider_rate_limited'
+        : ['timeout', 'network_error', 'blocked_address', 'overloaded', 'closed'].includes(String(code)) ? 'provider_network_error'
+            : ['invalid_response', 'binding_conflict', 'expired', 'consumed', 'canceled'].includes(String(code)) ? 'provider_invalid_response' : 'provider_unavailable', connectionId);
+}
 // OAuth codes the token endpoint may return (spec 4.2, RFC 6749/8707); anything else is reported as token_error.
 const SAFE_ERRORS = new Set(['invalid_request', 'invalid_client', 'invalid_grant', 'unauthorized_client', 'unsupported_grant_type', 'invalid_scope', 'invalid_target', 'invalid_session', 'account_mismatch', 'invalid_dpop_proof', 'use_dpop_nonce', 'extension_required', 'rate_limited']);
 const b64 = (data) => Buffer.from(data).toString('base64url');
@@ -55,8 +61,11 @@ function allowedHost(value, hosts) {
     const hostname = new URL(value).hostname.toLowerCase();
     return hosts.some(host => hostname === host.toLowerCase() || hostname.endsWith(`.${host.toLowerCase()}`));
 }
-// Redirect identity without the response parameters; origin alone would hide userinfo.
-const redirectShape = (url) => JSON.stringify([url.origin, url.username, url.password, url.pathname, [...url.searchParams]]);
+// Ignore unknown OAuth response fields, but preserve every registered redirect component.
+function redirectMatches(url, registered) {
+    return url.origin === registered.origin && url.username === registered.username && url.password === registered.password && url.pathname === registered.pathname
+        && [...registered.searchParams.keys()].every(key => JSON.stringify(url.searchParams.getAll(key)) === JSON.stringify(registered.searchParams.getAll(key)));
+}
 function parseCallback(callbackUrl) {
     if (typeof callbackUrl !== 'string' || !URL.canParse(callbackUrl))
         throw new AuthFailure('invalid_callback');
@@ -226,15 +235,25 @@ export function createClientAuth(options) {
     async function assertion(purpose, issuer, key, sub = clientId, operationId = randomId('op_')) {
         if (!options.assertions)
             return signIdentity({ typ: purpose === 'session' ? 'JWT' : 'client-authentication+jwt' }, assertionClaims(sub, issuer), key.thumbprint);
+        let result;
         try {
-            const result = await options.assertions.assert({ operationId, issuer, purpose });
-            if (typeof result.assertion !== 'string' || !result.assertion || !Number.isFinite(result.expiresAt) || result.expiresAt * 1000 <= now() || result.expiresAt * 1000 > now() + ASSERTION_SECONDS * 1000)
-                throw 0;
-            return result.assertion;
+            result = await options.assertions.assert({ operationId, issuer, purpose });
         }
-        catch {
-            throw new AuthFailure('provider_unavailable');
+        catch (error) {
+            throw providerFailure(error);
         }
+        return providerAssertion(result);
+    }
+    function providerAssertion(result, connectionId) {
+        if (!result || typeof result.assertion !== 'string' || !result.assertion || !Number.isFinite(result.expiresAt))
+            throw new AuthFailure('provider_invalid_response', connectionId);
+        const at = now(), expires = result.expiresAt * 1000;
+        if (expires <= at)
+            throw new AuthFailure('provider_assertion_expired', connectionId);
+        // Local freshness tolerance; the issuer still verifies signed claims, lifetime and replay.
+        if (expires > at + ASSERTION_SECONDS * 1000 + SKEW_MS)
+            throw new AuthFailure('provider_clock_skew', connectionId);
+        return result.assertion;
     }
     function responseFailure(response, code) {
         const value = response.headers.get('retry-after');
@@ -340,16 +359,19 @@ export function createClientAuth(options) {
         const dpopKeyRef = await secrets.stage(JSON.stringify({ kty, crv, x, y, d }));
         let userId = randomId('usr_');
         if (options.providerIdentity && !anonymous) {
+            let bound;
             try {
-                const bound = await options.providerIdentity.identity(issuer);
-                if (bound.clientId !== clientId || typeof bound.userId !== 'string' || !bound.userId)
-                    throw 0;
-                userId = bound.userId;
+                bound = await options.providerIdentity.identity(issuer);
             }
-            catch {
+            catch (error) {
+                await secrets.remove(dpopKeyRef);
+                throw providerFailure(error);
+            }
+            if (!bound || bound.clientId !== clientId || typeof bound.userId !== 'string' || !bound.userId) {
                 await secrets.remove(dpopKeyRef);
-                throw new AuthFailure('provider_unavailable');
+                throw new AuthFailure('provider_invalid_response');
             }
+            userId = bound.userId;
         }
         if (anonymous)
             return { userId, dpopKeyRef };
@@ -402,8 +424,7 @@ export function createClientAuth(options) {
     }
     // Terminal start/sign-in results only answer late duplicate callbacks, so keep the newest few; uncertain ones decide the cleanup status.
     function pruneHistory(state) {
-        // Newest first; reverse() keeps insertion order as the tie-break for equal timestamps.
-        const done = Object.values(state.operations).reverse().filter(op => op.kind !== 'renew' && op.phase === 'terminal' && op.status !== 'uncertain').sort((a, b) => b.createdAt - a.createdAt);
+        const done = Object.values(state.operations).filter(op => op.kind !== 'renew' && op.phase === 'terminal' && op.status !== 'uncertain').sort((a, b) => b.createdAt - a.createdAt || (a.id < b.id ? 1 : a.id > b.id ? -1 : 0));
         for (const op of done.slice(KEEP_OPERATIONS))
             delete state.operations[op.id];
     }
@@ -1206,7 +1227,7 @@ export function createClientAuth(options) {
             const token = await signedOutToken(metadata, userId, dpopKeyRef, null, null, anonymous);
             const secretRef = await stageSessionToken(token.access_token);
             const id = randomId('con_'), operationId = randomId('op_');
-            return commit({ issuer }, [secretRef], state => {
+            return commit({ issuer, history: true }, [secretRef], state => {
                 // A reset or competing identity since we signed means this session belongs to no current identity.
                 if (!anonymous && own(state.identities, issuer)?.dpopKeyRef !== dpopKeyRef)
                     throw new AuthFailure('state_changed');
@@ -1304,7 +1325,7 @@ export function createClientAuth(options) {
             const verifier = b64(crypto.getRandomValues(new Uint8Array(32)));
             const verifierRef = method === 'direct' ? await secrets.stage(verifier) : null;
             const createdAt = now(), operationId = randomId('op_');
-            const outcome = await commit({ connectionId }, [verifierRef], draft => {
+            const outcome = await commit({ connectionId, history: true }, [verifierRef], draft => {
                 const current = own(draft.connections, connectionId);
                 if (!current || current.generation !== connection.generation || current.status !== connection.status || current.sessionId !== connection.sessionId)
                     throw new AuthFailure('state_changed', connectionId);
@@ -1342,7 +1363,7 @@ export function createClientAuth(options) {
                 const found = Object.values(snapshot.operations).find(operation => operation.kind === 'sign_in' && operation.epoch === snapshot.epoch && operation.direct?.stateHash === stateHash);
                 const direct = found?.direct;
                 // A wrong browser, redirect or issuer (mix-up, spec 4.5) leaves the operation untouched so the genuine callback still completes.
-                if (!found || !direct || direct.browserHash !== browserHash || redirectShape(base) !== redirectShape(new URL(direct.redirectUri)) || params.iss !== direct.issuer)
+                if (!found || !direct || direct.browserHash !== browserHash || !redirectMatches(base, new URL(direct.redirectUri)) || params.iss !== direct.issuer)
                     throw new AuthFailure('invalid_callback');
                 checkCooldown(await record(found.connectionId));
                 const operationId = found.id;
@@ -1540,15 +1561,14 @@ export function createClientAuth(options) {
             const key = await loadDpopKey(connection.dpopKeyRef);
             let value;
             if (options.assertions && !connection.anonymous) {
+                let result;
                 try {
-                    const result = await options.assertions.assert({ purpose: 'browser', operationId: randomId('op_'), issuer: connection.issuer, sessionId: connection.sessionId, returnTo });
-                    if (!result.assertion || result.expiresAt * 1000 <= now() || result.expiresAt * 1000 > now() + 60000)
-                        throw 0;
-                    value = result.assertion;
+                    result = await options.assertions.assert({ purpose: 'browser', operationId: randomId('op_'), issuer: connection.issuer, sessionId: connection.sessionId, returnTo });
                 }
-                catch {
-                    throw new AuthFailure('provider_unavailable', connectionId);
+                catch (error) {
+                    throw providerFailure(error, connectionId);
                 }
+                value = providerAssertion(result, connectionId);
             }
             else
                 value = await signIdentity({ typ: 'poppy-browser+jwt' }, { ...assertionClaims(connection.userId, endpoint), session_id: connection.sessionId, return_to: returnTo }, key.thumbprint);

package/dist/auth/sqlite-store.js

@@ -51,8 +51,13 @@ export class SqliteAuthStore {
             for (const row of this.db.prepare(`SELECT id,body FROM auth_${table} ${clause}`).all(...params))
                 state[table][row.id] = JSON.parse(row.body);
         };
+        const history = () => {
+            if (selection.history)
+                rows('operations', "WHERE json_extract(body,'$.phase')='terminal' AND json_extract(body,'$.status')!='uncertain' AND json_extract(body,'$.kind')!='renew' ORDER BY json_extract(body,'$.createdAt') DESC,id DESC LIMIT 201");
+        };
         if ('issuer' in selection) {
             get('identities', selection.issuer);
+            history();
             return state;
         }
         if ('connectionId' in selection)
@@ -76,6 +81,7 @@ export class SqliteAuthStore {
         for (const operation of Object.values(state.operations))
             if (operation.grantId)
                 get('grants', operation.grantId);
+        history();
         return state;
     }
     async read(selection) {

package/dist/auth/store.d.ts

@@ -1,6 +1,6 @@
 import type { ClientAuthState } from './client-auth.js';
 /** A connection aggregate includes its grants, operations and cleanup; never other connections. */
-export type AuthSelection = {
+export type AuthSelection = ({
     connectionId: string;
 } | {
     operationId: string;
@@ -10,6 +10,8 @@ export type AuthSelection = {
     callbackHash: string;
 } | {
     list: true;
+}) & {
+    history?: true;
 };
 export interface AuthStore {
     read(selection: AuthSelection): Promise<ClientAuthState>;

package/dist/postgres-runtime.d.ts

@@ -23,6 +23,8 @@ export declare class PostgresRuntime {
     };
     constructor(pool: Pool, schema: PostgresSchema, ownsPool?: boolean);
     close(): Promise<void>;
+    /** Enlist in a host-owned transaction; the host handle must enforce its own lifetime. */
+    withConnection<T>(connection: PostgresConnection, action: () => Promise<T>): Promise<T>;
     run<T>(action: () => Promise<T>): Promise<T>;
     connection(): PostgresConnection;
     query<R extends QueryResultRow = QueryResultRow>(sql: string, values?: unknown[]): Promise<R[]>;

package/dist/postgres-runtime.js

@@ -77,6 +77,33 @@ export class PostgresRuntime {
     }
     async close() { this.closed = true; if (this.ownsPool)
         await this.pool.end(); }
+    /** Enlist in a host-owned transaction; the host handle must enforce its own lifetime. */
+    async withConnection(connection, action) {
+        if (this.closed)
+            throw new Error('Postgres adapter is closed');
+        if (this.context.getStore())
+            throw new Error('cannot enlist an adapter with an active Postgres transaction');
+        const context = { client: connection, active: true, locks: new Set(), state: { serial: 0, active: true }, childActive: false };
+        const savepoint = `enlisted_${this.schema}`;
+        // Probe only: rolling back a host scope would invalidate the owner's cached locks.
+        await connection.query(`SAVEPOINT ${savepoint}`);
+        await connection.query(`RELEASE SAVEPOINT ${savepoint}`);
+        try {
+            const result = await this.context.run(context, async () => {
+                const versions = await this.query(`SELECT version FROM ${this.schema}.schema_version`);
+                if (versions.length !== 1 || versions[0].version !== postgresSchemaVersion)
+                    throw new Error('unsupported Postgres schema version');
+                return action();
+            });
+            if (context.childActive)
+                throw new Error('unawaited nested Postgres transaction');
+            return result;
+        }
+        finally {
+            context.active = false;
+            context.state.active = false;
+        }
+    }
     async run(action) {
         if (this.closed)
             throw new Error('Postgres adapter is closed');

package/dist/postgres.js

@@ -52,6 +52,8 @@ export class PostgresAuthStore {
                 if (operation.grantId)
                     await one('grants', operation.grantId);
         }
+        if (selection.history)
+            await rows('operations', "AND body::jsonb->>'phase'='terminal' AND body::jsonb->>'status'!='uncertain' AND body::jsonb->>'kind'!='renew' ORDER BY (body::jsonb->>'createdAt')::double precision DESC,id COLLATE \"C\" DESC LIMIT 201");
         return state;
     }
     read(selection) { return this.db.run(() => this.select(selection)); }

package/dist/provider-postgres.d.ts

@@ -1,6 +1,8 @@
 import type { Pool } from 'pg';
 import type { ProviderSelection, ProviderStore, ProviderTransaction } from './provider.js';
+import type { PostgresConnection } from './postgres-runtime.js';
 export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
+export type { PostgresConnection } from './postgres-runtime.js';
 /** Targeted provider aggregates. Cryptography and human/session verification run outside its transactions. */
 export declare class PostgresProviderStore implements ProviderStore {
     readonly namespace: string;
@@ -11,5 +13,7 @@ export declare class PostgresProviderStore implements ProviderStore {
         rowsRead: number;
         rowsWritten: number;
     };
+    /** Only bounded SQL/crypto work; connection comes from the host's active transaction. */
+    withTransaction<T>(connection: PostgresConnection, action: () => Promise<T>): Promise<T>;
     transaction<T>(selection: ProviderSelection, action: (tx: ProviderTransaction) => T): Promise<T>;
 }

package/dist/provider-postgres.js

@@ -11,6 +11,8 @@ export class PostgresProviderStore {
     }
     close() { return this.db.close(); }
     get metrics() { return this.db.metrics; }
+    /** Only bounded SQL/crypto work; connection comes from the host's active transaction. */
+    withTransaction(connection, action) { return this.db.withConnection(connection, action); }
     transaction(selection, action) {
         return this.db.run(async () => {
             const rows = new Map();

package/dist/provider.d.ts

@@ -50,7 +50,7 @@ export interface ResultCipher {
     open(value: string): string;
 }
 export declare function createResultCipher(key: Uint8Array): ResultCipher;
-export type ProviderErrorCode = 'unauthorized' | 'binding_conflict' | 'expired' | 'consumed' | 'canceled' | 'rate_limited' | 'unavailable';
+export type ProviderErrorCode = 'unauthorized' | 'binding_conflict' | 'expired' | 'consumed' | 'canceled' | 'rate_limited' | 'unavailable' | 'invalid_response';
 export declare class ProviderError extends Error {
     readonly code: ProviderErrorCode;
     readonly retryAt?: number | undefined;
@@ -101,7 +101,7 @@ export declare function createProvider(options: ProviderOptions): {
         expiresAt: number;
     }>;
     callback(callbackUrl: string): Promise<{
-        status: string;
+        status: any;
     }>;
     takeResult(credential: string, input: Row): Promise<{
         status: string;

package/dist/provider.js

@@ -63,7 +63,7 @@ export function createProvider(options) {
             fail('unauthorized');
         return { ...row, enrollmentId };
     }
-    function operation(tx, enrollment, operationId) {
+    function operation(tx, enrollment, operationId, allowConsumed = false) {
         const row = tx.get('operation', `${enrollment.enrollmentId}:${operationId}`);
         if (!row)
             fail('binding_conflict');
@@ -71,7 +71,7 @@ export function createProvider(options) {
             fail('expired');
         if (row.status === 'canceled')
             fail('canceled');
-        if (row.status === 'consumed')
+        if (row.status === 'consumed' && !allowConsumed)
             fail('consumed');
         return row;
     }
@@ -226,10 +226,10 @@ export function createProvider(options) {
         },
         async callback(callbackUrl) {
             const url = new URL(callbackUrl), base = new URL(options.callbackUrl);
-            if (url.origin !== base.origin || url.pathname !== base.pathname || url.username || url.password || url.hash || [...url.searchParams.keys()].some(key => !['state', 'iss', 'code', 'error'].includes(key)) || ['state', 'iss', 'code', 'error'].some(key => url.searchParams.getAll(key).length > 1))
+            if (url.origin !== base.origin || url.pathname !== base.pathname || url.username || url.password || url.hash || ['state', 'iss', 'code', 'error', 'error_description', 'error_uri'].some(key => url.searchParams.getAll(key).length > 1))
                 fail('binding_conflict');
             const state = text(url.searchParams.get('state')), issuer = text(url.searchParams.get('iss'));
-            if (!!url.searchParams.get('code') === !!url.searchParams.get('error') || callbackUrl.length > 8192)
+            if (url.searchParams.has('code') === url.searchParams.has('error') || !(url.searchParams.get('code') || url.searchParams.get('error')) || callbackUrl.length > 8192)
                 fail('binding_conflict');
             return store.transaction({ kind: 'callback', stateHash: hash(state) }, tx => {
                 const lookup = tx.get('state', hash(state));
@@ -238,14 +238,14 @@ export function createProvider(options) {
                 const enrollment = tx.get('enrollment', lookup.enrollmentId);
                 if (!enrollment || enrollment.revoked)
                     fail('unauthorized');
-                const op = operation(tx, { enrollmentId: lookup.enrollmentId }, lookup.operationId);
+                const op = operation(tx, { enrollmentId: lookup.enrollmentId }, lookup.operationId, true);
                 if (op.binding.issuer !== issuer || op.binding.purpose !== 'direct')
                     fail('binding_conflict');
                 const fingerprint = hash(callbackUrl);
-                if (op.status === 'ready') {
+                if (op.status === 'ready' || op.status === 'consumed') {
                     if (op.resultHash !== fingerprint)
                         fail('binding_conflict');
-                    return { status: 'ready' };
+                    return { status: op.status };
                 }
                 tx.put('operation', `${lookup.enrollmentId}:${lookup.operationId}`, { ...op, status: 'ready', result: cipher.seal(callbackUrl), resultHash: fingerprint });
                 return { status: 'ready' };
@@ -300,6 +300,7 @@ export function createProvider(options) {
                     fail('binding_conflict');
                 const reader = request.body?.getReader();
                 let body = '', bytes = 0;
+                const decoder = new TextDecoder('utf-8', { fatal: true });
                 if (reader)
                     try {
                         for (;;) {
@@ -309,8 +310,12 @@ export function createProvider(options) {
                             bytes += part.value.length;
                             if (bytes > 16384)
                                 fail('binding_conflict');
-                            body += new TextDecoder().decode(part.value, { stream: true });
+                            body += decoder.decode(part.value, { stream: true });
                         }
+                        body += decoder.decode();
+                    }
+                    catch {
+                        fail('binding_conflict');
                     }
                     finally {
                         await reader.cancel().catch(() => { });
@@ -340,7 +345,13 @@ export function createProviderClient(options) {
         throw new Error('provider URL must not contain query/fragment');
     async function call(action, input) {
         const response = await options.transport.fetch(new Request(`${options.url.replace(/\/$/, '')}/${action}`, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${await options.credential()}` }, body: JSON.stringify({ version: 1, installationId: options.installationId, ...input }) }));
-        const body = object(await response.json());
+        let body;
+        try {
+            body = object(await response.json());
+        }
+        catch {
+            throw new ProviderError('invalid_response');
+        }
         if (!response.ok)
             throw new ProviderError(['unauthorized', 'binding_conflict', 'expired', 'consumed', 'canceled', 'rate_limited'].includes(body.error) ? body.error : 'unavailable', body.retryAt);
         return body;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poppykit/client",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "private": false,
   "description": "Personal Agent Protocol client SDK",
   "repository": {
@@ -9,7 +9,7 @@
   },
   "type": "module",
   "engines": {
-    "node": ">=24.12.0"
+    "node": ">=24.21.0 <25"
   },
   "packageManager": "pnpm@11.25.0",
   "scripts": {