@poppykit/client 0.1.0 → 0.2.0

package/dist/provider.d.ts

@@ -11,10 +11,40 @@ export interface ProviderTransaction {
         value: Row;
     }[];
 }
-/** Must commit synchronously, atomically across processes; callback must not perform I/O. */
+export type ProviderSelection = {
+    kind: 'enroll';
+    subjectHash: string;
+    requestHash: string;
+} | {
+    kind: 'identity';
+    enrollmentId: string;
+    issuer: string;
+} | {
+    kind: 'operation';
+    enrollmentId: string;
+    operationId: string;
+} | {
+    kind: 'begin';
+    enrollmentId: string;
+    operationId: string;
+    issuer: string;
+    stateHash?: string;
+    at: number;
+} | {
+    kind: 'callback';
+    stateHash: string;
+} | {
+    kind: 'revoke';
+    enrollmentId: string;
+};
+/** Atomic asynchronous I/O around a pure synchronous, selection-bounded callback. */
 export interface ProviderStore {
-    transaction<T>(action: (tx: ProviderTransaction) => T): T;
+    transaction<T>(selection: ProviderSelection, action: (tx: ProviderTransaction) => T): Promise<T>;
 }
+/** Explicit migration aid for existing local synchronous stores; unsuitable for remote I/O. */
+export declare function adaptLegacyProviderStore(store: {
+    transaction<T>(action: (tx: ProviderTransaction) => T): T;
+}): ProviderStore;
 export interface ResultCipher {
     seal(value: string): string;
     open(value: string): string;
@@ -70,22 +100,22 @@ export declare function createProvider(options: ProviderOptions): {
         assertion: string;
         expiresAt: number;
     }>;
-    callback(callbackUrl: string): {
+    callback(callbackUrl: string): Promise<{
         status: string;
-    };
-    takeResult(credential: string, input: Row): {
+    }>;
+    takeResult(credential: string, input: Row): Promise<{
         status: string;
         callbackUrl?: undefined;
     } | {
         status: string;
         callbackUrl: string;
-    };
-    cancel(credential: string, input: Row): {
+    }>;
+    cancel(credential: string, input: Row): Promise<{
         status: string;
-    };
-    revokeEnrollment(credential: string, input: Row): {
+    }>;
+    revokeEnrollment(credential: string, input: Row): Promise<{
         status: string;
-    };
+    }>;
     handle(request: Request): Promise<Response>;
 };
 /** Bound trusted adapter: credentials/assertions/results never belong in harness output. */

package/dist/provider.js

@@ -1,6 +1,17 @@
 /** Optional PoppyKit provider v1. Hosting, human authentication and key custody belong to the operator. */
 import { createHash, randomBytes, createCipheriv, createDecipheriv } from 'node:crypto';
 import { secureUrl } from './network/transport.js';
+/** Explicit migration aid for existing local synchronous stores; unsuitable for remote I/O. */
+export function adaptLegacyProviderStore(store) {
+    return { async transaction(_selection, action) {
+            return store.transaction(tx => {
+                const result = action(tx);
+                if (result && typeof result.then === 'function')
+                    throw new TypeError('provider transaction must be synchronous');
+                return structuredClone(result);
+            });
+        } };
+}
 export function createResultCipher(key) {
     if (key.length !== 32)
         throw new Error('provider encryption key must be 32 bytes');
@@ -85,10 +96,12 @@ export function createProvider(options) {
         starts.push(now());
         tx.put('enrollment', enrollment.enrollmentId, { ...enrollment, starts });
     }
-    function authorizeCompany(credential, input) {
+    const enrollmentId = (credential) => credential.split('.')[0] ?? '';
+    const selectedOperation = (credential, input) => ({ kind: 'operation', enrollmentId: enrollmentId(credential), operationId: text(input.operationId) });
+    async function authorizeCompany(credential, input) {
         const domain = text(input.domain);
         text(input.issuer);
-        store.transaction(tx => { const enrollment = auth(tx, credential, text(input.installationId)); if (!enrollment.allowedCompanies.includes(domain))
+        await store.transaction({ kind: 'identity', enrollmentId: enrollmentId(credential), issuer: input.issuer }, tx => { const enrollment = auth(tx, credential, text(input.installationId)); if (!enrollment.allowedCompanies.includes(domain))
             fail('unauthorized'); });
     }
     const api = {
@@ -98,12 +111,14 @@ export function createProvider(options) {
             if (!human?.subject || !human.allowedCompanies.length)
                 fail('unauthorized');
             const installationId = text(input.installationId), key = hash(JSON.stringify([human.subject, text(input.idempotencyKey)]));
-            return store.transaction(tx => {
+            return store.transaction({ kind: 'enroll', subjectHash: hash(human.subject), requestHash: key }, tx => {
                 if (tx.get('enrollmentRequest', key))
                     fail('consumed'); // Credential delivery cannot be replayed from a verifier.
                 const subjectKey = hash(human.subject), visitor = tx.get('visitor', subjectKey)?.id ?? id();
-                if (tx.list('enrollment', '', (options.maxEnrollments ?? 10000) + 1).length >= (options.maxEnrollments ?? 10000))
+                const count = tx.get('capacity', 'enrollments')?.count ?? 0;
+                if (count >= (options.maxEnrollments ?? 10000))
                     throw new ProviderError('rate_limited', now() + 60000);
+                tx.put('capacity', 'enrollments', { count: count + 1 });
                 tx.put('visitor', subjectKey, { id: visitor });
                 const enrollmentId = id(), secret = id();
                 tx.put('enrollment', enrollmentId, { installationId, visitor, verifier: hash(secret), allowedCompanies: [...new Set(human.allowedCompanies)], revoked: false, starts: [] });
@@ -113,9 +128,9 @@ export function createProvider(options) {
         },
         async identity(credential, input) {
             exact(input, ['version', 'installationId', 'domain', 'issuer']);
-            authorizeCompany(credential, input);
+            await authorizeCompany(credential, input);
             const metadata = await verified(text(input.domain), text(input.issuer));
-            return store.transaction(tx => {
+            return store.transaction({ kind: 'identity', enrollmentId: enrollmentId(credential), issuer: input.issuer }, tx => {
                 const enrollment = auth(tx, credential, text(input.installationId));
                 if (!enrollment.allowedCompanies.includes(metadata.document.organization.domain))
                     fail('unauthorized');
@@ -129,7 +144,7 @@ export function createProvider(options) {
             text(input.operationId);
             if (input.sessionId !== undefined)
                 text(input.sessionId);
-            authorizeCompany(credential, input);
+            await authorizeCompany(credential, input);
             if (input.purpose === 'client-authentication' && (input.sessionId !== undefined || input.returnTo !== undefined))
                 fail('binding_conflict');
             if (input.purpose !== 'browser' && input.returnTo !== undefined)
@@ -145,7 +160,7 @@ export function createProvider(options) {
             const metadata = await verified(text(input.domain), text(input.issuer));
             if (input.purpose === 'browser' && (!onDomain(input.returnTo, metadata.document.organization.domain) || !metadata.document.web?.browser_session_endpoint))
                 fail('binding_conflict');
-            const identity = store.transaction(tx => {
+            const identity = await store.transaction({ kind: 'identity', enrollmentId: enrollmentId(credential), issuer: input.issuer }, tx => {
                 const enrollment = auth(tx, credential, text(input.installationId));
                 if (!enrollment.allowedCompanies.includes(metadata.document.organization.domain))
                     fail('unauthorized');
@@ -154,7 +169,7 @@ export function createProvider(options) {
             if (input.purpose === 'browser' && !await options.verifySession?.({ clientId: options.clientId, userId: identity.userId, issuer: input.issuer, sessionId: input.sessionId }))
                 fail('unauthorized');
             const binding = { issuer: input.issuer, domain: metadata.document.organization.domain, purpose: input.purpose, sessionId: input.sessionId ?? null, returnTo: input.returnTo ?? null, stateHash: input.state ? hash(input.state) : null, userId: identity.userId, browserEndpoint: metadata.document.web?.browser_session_endpoint ?? null };
-            return store.transaction(tx => {
+            return store.transaction({ kind: 'begin', enrollmentId: enrollmentId(credential), operationId: input.operationId, issuer: input.issuer, ...(binding.stateHash ? { stateHash: binding.stateHash } : {}), at: now() }, tx => {
                 const enrollment = auth(tx, credential, text(input.installationId)), key = `${enrollment.enrollmentId}:${text(input.operationId)}`, existing = tx.get('operation', key);
                 if (existing) {
                     if (!same(existing.binding, binding))
@@ -186,7 +201,7 @@ export function createProvider(options) {
         },
         async assert(credential, input) {
             exact(input, ['version', 'installationId', 'operationId', 'purpose']);
-            const snapshot = store.transaction(tx => {
+            const snapshot = await store.transaction(selectedOperation(credential, input), tx => {
                 const enrollment = auth(tx, credential, text(input.installationId)), op = operation(tx, enrollment, text(input.operationId));
                 if (op.binding.purpose !== input.purpose || !['client-authentication', 'session', 'browser'].includes(input.purpose))
                     fail('binding_conflict');
@@ -206,17 +221,17 @@ export function createProvider(options) {
             if (signature.length !== 64)
                 fail('unavailable');
             // A revoke/cancel racing external KMS signing wins before the assertion leaves the provider.
-            store.transaction(tx => { const enrollment = auth(tx, credential, input.installationId), op = operation(tx, enrollment, input.operationId); tx.put('operation', `${enrollment.enrollmentId}:${input.operationId}`, { ...op, status: 'signed' }); });
+            await store.transaction(selectedOperation(credential, input), tx => { const enrollment = auth(tx, credential, input.installationId), op = operation(tx, enrollment, input.operationId); tx.put('operation', `${enrollment.enrollmentId}:${input.operationId}`, { ...op, status: 'signed' }); });
             return { assertion: `${unsigned}.${Buffer.from(signature).toString('base64url')}`, expiresAt: exp };
         },
-        callback(callbackUrl) {
+        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))
                 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)
                 fail('binding_conflict');
-            return store.transaction(tx => {
+            return store.transaction({ kind: 'callback', stateHash: hash(state) }, tx => {
                 const lookup = tx.get('state', hash(state));
                 if (!lookup)
                     fail('binding_conflict');
@@ -236,9 +251,9 @@ export function createProvider(options) {
                 return { status: 'ready' };
             });
         },
-        takeResult(credential, input) {
+        async takeResult(credential, input) {
             exact(input, ['version', 'installationId', 'operationId', 'issuer', 'sessionId']);
-            return store.transaction(tx => {
+            return store.transaction(selectedOperation(credential, input), tx => {
                 const enrollment = auth(tx, credential, text(input.installationId)), op = operation(tx, enrollment, text(input.operationId));
                 if (op.binding.issuer !== input.issuer || op.binding.sessionId !== input.sessionId || op.binding.purpose !== 'direct')
                     fail('binding_conflict');
@@ -249,9 +264,9 @@ export function createProvider(options) {
                 return { status: 'completed', callbackUrl };
             });
         },
-        cancel(credential, input) {
+        async cancel(credential, input) {
             exact(input, ['version', 'installationId', 'operationId']);
-            return store.transaction(tx => {
+            return store.transaction(selectedOperation(credential, input), tx => {
                 const enrollment = auth(tx, credential, text(input.installationId)), key = `${enrollment.enrollmentId}:${text(input.operationId)}`, op = tx.get('operation', key);
                 if (!op)
                     fail('binding_conflict');
@@ -259,9 +274,9 @@ export function createProvider(options) {
                 return { status: 'canceled' };
             });
         },
-        revokeEnrollment(credential, input) {
+        async revokeEnrollment(credential, input) {
             exact(input, ['version', 'installationId']);
-            return store.transaction(tx => {
+            return store.transaction({ kind: 'revoke', enrollmentId: enrollmentId(credential) }, tx => {
                 const enrollment = auth(tx, credential, text(input.installationId));
                 tx.put('enrollment', enrollment.enrollmentId, { ...enrollment, revoked: true });
                 for (const row of tx.list('operation', `${enrollment.enrollmentId}:`, 1000))
@@ -278,7 +293,7 @@ export function createProvider(options) {
                     return Response.json({ keys: (options.publishedKeys ? await options.publishedKeys() : [{ ...await options.signer.publicJwk(), kid: options.signer.kid }]).map(publicKey) }, { headers });
                 const url = new URL(request.url);
                 if (url.origin === new URL(options.callbackUrl).origin && url.pathname === new URL(options.callbackUrl).pathname && request.method === 'GET') {
-                    api.callback(request.url);
+                    await api.callback(request.url);
                     return Response.json({ status: 'received' }, { headers });
                 }
                 if (request.method !== 'POST' || !request.headers.get('content-type')?.startsWith('application/json'))

package/migrations/postgres/0001_poppy_client.sql

@@ -0,0 +1,16 @@
+CREATE SCHEMA poppy_client;
+CREATE TABLE poppy_client.schema_version (version integer PRIMARY KEY CHECK(version > 0));
+INSERT INTO poppy_client.schema_version VALUES (1);
+CREATE TABLE poppy_client.records (ns text NOT NULL, kind text NOT NULL, id text NOT NULL, body text NOT NULL CHECK (body::jsonb IS NOT NULL), ordinal bigint GENERATED ALWAYS AS IDENTITY, PRIMARY KEY(ns,kind,id));
+CREATE INDEX by_conversation ON poppy_client.records (ns,kind,(body::jsonb->>'conversationId'));
+CREATE INDEX by_binding ON poppy_client.records (ns,kind,(body::jsonb->>'bindingId'));
+CREATE INDEX by_client ON poppy_client.records (ns,kind,(body::jsonb->>'clientId'));
+CREATE INDEX by_account ON poppy_client.records (ns,kind,(body::jsonb->>'accountId'));
+CREATE INDEX by_grant ON poppy_client.records (ns,kind,(body::jsonb->>'grantId'));
+CREATE INDEX by_phase ON poppy_client.records (ns,kind,(body::jsonb->>'phase'));
+CREATE INDEX by_expiry ON poppy_client.records (ns,kind,((body::jsonb->>'expiresAt')::double precision));
+CREATE INDEX by_connection ON poppy_client.records (ns,kind,(body::jsonb->>'connectionId'));
+CREATE INDEX by_callback ON poppy_client.records (ns,kind,(body::jsonb#>>'{direct,stateHash}'));
+CREATE TABLE poppy_client.outbound (ns text NOT NULL, connection text NOT NULL, issuer text NOT NULL, id text NOT NULL, body text NOT NULL, PRIMARY KEY(ns,connection,issuer,id));
+CREATE TABLE poppy_client.checkpoints (ns text NOT NULL, connection text NOT NULL, issuer text NOT NULL, endpoint text NOT NULL, conversation text NOT NULL, name text NOT NULL, cursor text NOT NULL, PRIMARY KEY(ns,connection,issuer,endpoint,conversation,name));
+CREATE UNIQUE INDEX auth_callback ON poppy_client.records(ns,((body::jsonb)#>>'{direct,stateHash}')) WHERE kind='operations';

package/migrations/postgres/0001_poppy_provider.sql

@@ -0,0 +1,14 @@
+CREATE SCHEMA poppy_provider;
+CREATE TABLE poppy_provider.schema_version (version integer PRIMARY KEY CHECK(version > 0));
+INSERT INTO poppy_provider.schema_version VALUES (1);
+CREATE TABLE poppy_provider.records (ns text NOT NULL, kind text NOT NULL, id text NOT NULL, body text NOT NULL CHECK (body::jsonb IS NOT NULL), ordinal bigint GENERATED ALWAYS AS IDENTITY, PRIMARY KEY(ns,kind,id));
+CREATE INDEX operations_enrollment ON poppy_provider.records(ns,(split_part(id,':',1)),id) WHERE kind='operation';
+CREATE INDEX by_conversation ON poppy_provider.records (ns,kind,(body::jsonb->>'conversationId'));
+CREATE INDEX by_binding ON poppy_provider.records (ns,kind,(body::jsonb->>'bindingId'));
+CREATE INDEX by_client ON poppy_provider.records (ns,kind,(body::jsonb->>'clientId'));
+CREATE INDEX by_account ON poppy_provider.records (ns,kind,(body::jsonb->>'accountId'));
+CREATE INDEX by_grant ON poppy_provider.records (ns,kind,(body::jsonb->>'grantId'));
+CREATE INDEX by_phase ON poppy_provider.records (ns,kind,(body::jsonb->>'phase'));
+CREATE INDEX by_expiry ON poppy_provider.records (ns,kind,((body::jsonb->>'expiresAt')::double precision));
+CREATE INDEX by_connection ON poppy_provider.records (ns,kind,(body::jsonb->>'connectionId'));
+CREATE INDEX by_callback ON poppy_provider.records (ns,kind,(body::jsonb#>>'{direct,stateHash}'));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poppykit/client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "private": false,
   "description": "Personal Agent Protocol client SDK",
   "repository": {
@@ -24,7 +24,9 @@
   },
   "devDependencies": {
     "@types/node": "24.10.0",
-    "typescript": "5.9.3"
+    "typescript": "5.9.3",
+    "pg": "8.23.1",
+    "@types/pg": "8.23.1"
   },
   "files": [
     "dist",
@@ -40,7 +42,8 @@
     "CHANGELOG.md",
     "RELEASING.md",
     "examples",
-    "LICENSE"
+    "LICENSE",
+    "migrations"
   ],
   "exports": {
     ".": {
@@ -62,6 +65,18 @@
     "./provider/sqlite": {
       "import": "./dist/provider-sqlite.js",
       "types": "./dist/provider-sqlite.d.ts"
+    },
+    "./postgres": {
+      "types": "./dist/postgres.d.ts",
+      "import": "./dist/postgres.js"
+    },
+    "./provider/postgres": {
+      "types": "./dist/provider-postgres.d.ts",
+      "import": "./dist/provider-postgres.js"
+    },
+    "./adapter-contract": {
+      "types": "./dist/adapter-contract.d.ts",
+      "import": "./dist/adapter-contract.js"
     }
   },
   "dependencies": {
@@ -70,5 +85,13 @@
   "license": "MIT",
   "publishConfig": {
     "access": "public"
+  },
+  "peerDependencies": {
+    "pg": "^8.23.1"
+  },
+  "peerDependenciesMeta": {
+    "pg": {
+      "optional": true
+    }
   }
 }