@poppykit/client 0.0.0-stage → 0.1.1

package/dist/provider.js

@@ -0,0 +1,342 @@
+/** 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';
+export function createResultCipher(key) {
+    if (key.length !== 32)
+        throw new Error('provider encryption key must be 32 bytes');
+    const secret = Buffer.from(key);
+    return {
+        seal(value) { const iv = randomBytes(12), cipher = createCipheriv('aes-256-gcm', secret, iv); return Buffer.concat([iv, cipher.update(value, 'utf8'), cipher.final(), cipher.getAuthTag()]).toString('base64url'); },
+        open(value) { const bytes = Buffer.from(value, 'base64url'), cipher = createDecipheriv('aes-256-gcm', secret, bytes.subarray(0, 12)); cipher.setAuthTag(bytes.subarray(-16)); return Buffer.concat([cipher.update(bytes.subarray(12, -16)), cipher.final()]).toString('utf8'); },
+    };
+}
+export class ProviderError extends Error {
+    code;
+    retryAt;
+    constructor(code, retryAt) {
+        super(`Provider ${code}`);
+        this.code = code;
+        this.retryAt = retryAt;
+    }
+}
+const id = () => randomBytes(32).toString('base64url');
+const hash = (value) => createHash('sha256').update(value).digest('base64url');
+function fail(code) { throw new ProviderError(code); }
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const text = (value) => typeof value === 'string' && value.length > 0 && value.length <= 2048 ? value : fail('binding_conflict');
+function exact(value, keys) { if (value.version !== 1 || Object.keys(value).some(key => !keys.includes(key)))
+    fail('binding_conflict'); }
+function object(value) { if (!value || typeof value !== 'object' || Array.isArray(value))
+    fail('binding_conflict'); return value; }
+function https(value) { try {
+    return secureUrl(value);
+}
+catch {
+    return fail('binding_conflict');
+} }
+function onDomain(value, domain) { const host = https(value).hostname; return host === domain || host.endsWith(`.${domain}`); }
+function publicKey(value) {
+    if (value.kty !== 'EC' || value.crv !== 'P-256' || typeof value.x !== 'string' || typeof value.y !== 'string' || 'd' in value || 'k' in value)
+        fail('unavailable');
+    return { kty: value.kty, crv: value.crv, x: value.x, y: value.y, kid: text(value.kid), alg: 'ES256', use: 'sig' };
+}
+export function createProvider(options) {
+    const { store, cipher } = options, now = options.now ?? Date.now;
+    const client = https(options.clientId);
+    if ([options.callbackUrl, options.jwksUri].some(value => https(value).hostname !== client.hostname) || https(options.callbackUrl).search)
+        throw new Error('provider metadata endpoints must share client domain; callback cannot contain query');
+    function auth(tx, credential, installationId) {
+        const [enrollmentId, secret, extra] = credential.split('.');
+        const row = enrollmentId ? tx.get('enrollment', enrollmentId) : undefined;
+        if (extra || !row || row.revoked || row.installationId !== installationId || hash(secret ?? '') !== row.verifier)
+            fail('unauthorized');
+        return { ...row, enrollmentId };
+    }
+    function operation(tx, enrollment, operationId) {
+        const row = tx.get('operation', `${enrollment.enrollmentId}:${operationId}`);
+        if (!row)
+            fail('binding_conflict');
+        if (row.expiresAt <= now())
+            fail('expired');
+        if (row.status === 'canceled')
+            fail('canceled');
+        if (row.status === 'consumed')
+            fail('consumed');
+        return row;
+    }
+    async function verified(domain, issuer) {
+        const metadata = await options.metadata.resolveCompany(domain);
+        if (metadata.authorization?.issuer !== issuer)
+            fail('binding_conflict');
+        return metadata;
+    }
+    function user(tx, visitor, issuer) {
+        const key = hash(JSON.stringify([visitor, issuer])), existing = tx.get('user', key);
+        if (existing)
+            return existing.userId;
+        const userId = id();
+        tx.put('user', key, { userId });
+        return userId;
+    }
+    function throttle(tx, enrollment) {
+        const starts = enrollment.starts.filter((at) => at > now() - 60000);
+        if (starts.length >= 60)
+            throw new ProviderError('rate_limited', starts[0] + 60000);
+        starts.push(now());
+        tx.put('enrollment', enrollment.enrollmentId, { ...enrollment, starts });
+    }
+    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))
+            fail('unauthorized'); });
+    }
+    const api = {
+        async enroll(request, input) {
+            exact(input, ['version', 'installationId', 'idempotencyKey']);
+            const human = await options.authenticateEnrollment(request);
+            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 => {
+                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))
+                    throw new ProviderError('rate_limited', now() + 60000);
+                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: [] });
+                tx.put('enrollmentRequest', key, { enrollmentId });
+                return { enrollmentId, credential: `${enrollmentId}.${secret}`, clientId: options.clientId, callbackUrl: options.callbackUrl };
+            });
+        },
+        async identity(credential, input) {
+            exact(input, ['version', 'installationId', 'domain', 'issuer']);
+            authorizeCompany(credential, input);
+            const metadata = await verified(text(input.domain), text(input.issuer));
+            return store.transaction(tx => {
+                const enrollment = auth(tx, credential, text(input.installationId));
+                if (!enrollment.allowedCompanies.includes(metadata.document.organization.domain))
+                    fail('unauthorized');
+                return { clientId: options.clientId, userId: user(tx, enrollment.visitor, input.issuer) };
+            });
+        },
+        async begin(credential, input) {
+            exact(input, ['version', 'installationId', 'operationId', 'domain', 'issuer', 'purpose', 'sessionId', 'returnTo', 'state']);
+            if (!['client-authentication', 'session', 'browser', 'direct'].includes(input.purpose))
+                fail('binding_conflict');
+            text(input.operationId);
+            if (input.sessionId !== undefined)
+                text(input.sessionId);
+            authorizeCompany(credential, input);
+            if (input.purpose === 'client-authentication' && (input.sessionId !== undefined || input.returnTo !== undefined))
+                fail('binding_conflict');
+            if (input.purpose !== 'browser' && input.returnTo !== undefined)
+                fail('binding_conflict');
+            if (input.purpose !== 'direct' && input.state !== undefined)
+                fail('binding_conflict');
+            if (input.purpose === 'direct' && (typeof input.state !== 'string' || !/^[A-Za-z0-9_-]{43}$/.test(input.state) || !input.sessionId))
+                fail('binding_conflict');
+            if (input.purpose === 'browser' && !input.sessionId)
+                fail('binding_conflict');
+            if (input.purpose === 'browser')
+                text(input.returnTo);
+            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 enrollment = auth(tx, credential, text(input.installationId));
+                if (!enrollment.allowedCompanies.includes(metadata.document.organization.domain))
+                    fail('unauthorized');
+                return { enrollment, userId: user(tx, enrollment.visitor, input.issuer) };
+            });
+            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 => {
+                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))
+                        fail('binding_conflict');
+                    operation(tx, enrollment, input.operationId);
+                    return { expiresAt: existing.expiresAt };
+                }
+                const rows = tx.list('operation', `${enrollment.enrollmentId}:`, 1001);
+                // Bounded cleanup preserves tombstones until expiry plus clock tolerance.
+                for (const row of rows)
+                    if (row.value.expiresAt + 30000 <= now()) {
+                        tx.remove('operation', row.id);
+                        if (row.value.binding.stateHash)
+                            tx.remove('state', row.value.binding.stateHash);
+                    }
+                // A hard retained-row cap keeps every quota/revocation scan complete, including tombstones.
+                if (rows.filter(row => row.value.expiresAt + 30000 > now()).length >= 1000)
+                    throw new ProviderError('rate_limited', now() + 60000);
+                if (rows.filter(row => row.value.expiresAt > now() && ['pending', 'ready'].includes(row.value.status)).length >= 10)
+                    throw new ProviderError('rate_limited', now() + 60000);
+                const expiresAt = now() + 600000;
+                if (binding.stateHash && tx.get('state', binding.stateHash))
+                    fail('binding_conflict');
+                tx.put('operation', key, { binding, expiresAt, status: 'pending', result: null, resultHash: null });
+                if (binding.stateHash)
+                    tx.put('state', binding.stateHash, { enrollmentId: enrollment.enrollmentId, operationId: input.operationId });
+                return { expiresAt };
+            });
+        },
+        async assert(credential, input) {
+            exact(input, ['version', 'installationId', 'operationId', 'purpose']);
+            const snapshot = store.transaction(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');
+                throttle(tx, enrollment);
+                return { enrollment, op };
+            });
+            const b = snapshot.op.binding, metadata = await verified(b.domain, b.issuer);
+            if (b.browserEndpoint !== (metadata.document.web?.browser_session_endpoint ?? null))
+                fail('binding_conflict');
+            if (b.purpose === 'browser' && !await options.verifySession?.({ clientId: options.clientId, userId: b.userId, issuer: b.issuer, sessionId: b.sessionId }))
+                fail('unauthorized');
+            const iat = Math.floor(now() / 1000), exp = iat + 60;
+            const claims = { iss: options.clientId, sub: b.purpose === 'client-authentication' ? options.clientId : b.userId, aud: b.purpose === 'browser' ? b.browserEndpoint : b.issuer, iat, exp, jti: id(), ...(b.purpose === 'browser' ? { session_id: b.sessionId, return_to: b.returnTo } : {}) };
+            const header = { alg: 'ES256', kid: options.signer.kid, typ: b.purpose === 'client-authentication' ? 'client-authentication+jwt' : b.purpose === 'browser' ? 'poppy-browser+jwt' : 'JWT' };
+            const unsigned = `${Buffer.from(JSON.stringify(header)).toString('base64url')}.${Buffer.from(JSON.stringify(claims)).toString('base64url')}`;
+            const signature = await options.signer.sign(new TextEncoder().encode(unsigned));
+            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' }); });
+            return { assertion: `${unsigned}.${Buffer.from(signature).toString('base64url')}`, expiresAt: exp };
+        },
+        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 => {
+                const lookup = tx.get('state', hash(state));
+                if (!lookup)
+                    fail('binding_conflict');
+                const enrollment = tx.get('enrollment', lookup.enrollmentId);
+                if (!enrollment || enrollment.revoked)
+                    fail('unauthorized');
+                const op = operation(tx, { enrollmentId: lookup.enrollmentId }, lookup.operationId);
+                if (op.binding.issuer !== issuer || op.binding.purpose !== 'direct')
+                    fail('binding_conflict');
+                const fingerprint = hash(callbackUrl);
+                if (op.status === 'ready') {
+                    if (op.resultHash !== fingerprint)
+                        fail('binding_conflict');
+                    return { status: 'ready' };
+                }
+                tx.put('operation', `${lookup.enrollmentId}:${lookup.operationId}`, { ...op, status: 'ready', result: cipher.seal(callbackUrl), resultHash: fingerprint });
+                return { status: 'ready' };
+            });
+        },
+        takeResult(credential, input) {
+            exact(input, ['version', 'installationId', 'operationId', 'issuer', 'sessionId']);
+            return store.transaction(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');
+                if (op.status !== 'ready')
+                    return { status: 'pending' };
+                const callbackUrl = cipher.open(op.result);
+                tx.put('operation', `${enrollment.enrollmentId}:${input.operationId}`, { ...op, status: 'consumed', result: null });
+                return { status: 'completed', callbackUrl };
+            });
+        },
+        cancel(credential, input) {
+            exact(input, ['version', 'installationId', 'operationId']);
+            return store.transaction(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');
+                tx.put('operation', key, { ...op, status: 'canceled', result: null });
+                return { status: 'canceled' };
+            });
+        },
+        revokeEnrollment(credential, input) {
+            exact(input, ['version', 'installationId']);
+            return store.transaction(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))
+                    tx.put('operation', row.id, { ...row.value, status: 'canceled', result: null });
+                return { status: 'revoked' };
+            });
+        },
+        async handle(request) {
+            const headers = { 'cache-control': 'no-store', 'content-type': 'application/json' };
+            try {
+                if (request.url === options.clientId && request.method === 'GET')
+                    return Response.json({ client_id: options.clientId, client_name: options.clientName, jwks_uri: options.jwksUri, redirect_uris: [options.callbackUrl], token_endpoint_auth_method: 'private_key_jwt' }, { headers });
+                if (request.url === options.jwksUri && request.method === 'GET')
+                    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);
+                    return Response.json({ status: 'received' }, { headers });
+                }
+                if (request.method !== 'POST' || !request.headers.get('content-type')?.startsWith('application/json'))
+                    fail('binding_conflict');
+                const reader = request.body?.getReader();
+                let body = '', bytes = 0;
+                if (reader)
+                    try {
+                        for (;;) {
+                            const part = await reader.read();
+                            if (part.done)
+                                break;
+                            bytes += part.value.length;
+                            if (bytes > 16384)
+                                fail('binding_conflict');
+                            body += new TextDecoder().decode(part.value, { stream: true });
+                        }
+                    }
+                    finally {
+                        await reader.cancel().catch(() => { });
+                    }
+                const input = object(JSON.parse(body));
+                if (input.version !== 1)
+                    fail('binding_conflict');
+                const action = url.pathname.slice(url.pathname.lastIndexOf('/') + 1), credential = request.headers.get('authorization')?.match(/^Bearer (\S+)$/)?.[1] ?? '';
+                const allowed = ['enroll', 'identity', 'begin', 'assert', 'takeResult', 'cancel', 'revokeEnrollment'];
+                if (!allowed.includes(action))
+                    fail('binding_conflict');
+                const result = action === 'enroll' ? await api.enroll(request, input) : await api[action](credential, input);
+                return Response.json(result, { headers });
+            }
+            catch (error) {
+                const code = error instanceof ProviderError ? error.code : 'unavailable';
+                return Response.json({ error: code, ...(error instanceof ProviderError && error.retryAt ? { retryAt: error.retryAt } : {}) }, { status: code === 'unauthorized' ? 401 : code === 'rate_limited' ? 429 : code === 'unavailable' ? 503 : 409, headers });
+            }
+        },
+    };
+    return api;
+}
+/** Bound trusted adapter: credentials/assertions/results never belong in harness output. */
+export function createProviderClient(options) {
+    const base = https(options.url);
+    if (base.search || base.hash)
+        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());
+        if (!response.ok)
+            throw new ProviderError(['unauthorized', 'binding_conflict', 'expired', 'consumed', 'canceled', 'rate_limited'].includes(body.error) ? body.error : 'unavailable', body.retryAt);
+        return body;
+    }
+    const identity = async (issuer) => { const value = await call('identity', { issuer, domain: options.domain }); return { clientId: text(value.clientId), userId: text(value.userId) }; };
+    const assert = async (request) => {
+        await call('begin', { ...request, domain: options.domain });
+        const value = await call('assert', { operationId: request.operationId, purpose: request.purpose });
+        return { assertion: text(value.assertion), expiresAt: value.expiresAt };
+    };
+    return { identity, assert, beginDirect: (input) => call('begin', { ...input, domain: options.domain, purpose: 'direct' }),
+        takeResult: (input) => call('takeResult', input),
+        cancel: (operationId) => call('cancel', { operationId }), revokeEnrollment: () => call('revokeEnrollment', {}) };
+}

package/dist/sqlite-init.d.ts

@@ -0,0 +1,2 @@
+import type { DatabaseSync } from 'node:sqlite';
+export declare function initializeSqlite(db: DatabaseSync, initialize: () => void): void;

package/dist/sqlite-init.js

@@ -0,0 +1,17 @@
+// SQLite may return BUSY immediately when two processes first enable WAL, despite busy_timeout.
+export function initializeSqlite(db, initialize) {
+    const deadline = Date.now() + 5000;
+    for (;;) {
+        try {
+            initialize();
+            return;
+        }
+        catch (error) {
+            if (![5, 6].includes(error.errcode ?? 0) || Date.now() >= deadline) {
+                db.close();
+                throw error;
+            }
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+    }
+}

package/dist/sqlite.d.ts

@@ -0,0 +1,20 @@
+export { SqliteAuthStore } from './auth/sqlite-store.js';
+import type { ConversationKey, ConversationStore } from './conversation-store.js';
+import type { ConsumerCheckpoint, OutboundRecord } from './conversation.js';
+/** Optional durable adapter. One local SQLite database; not a secret vault. */
+export declare class SqliteConversationStore implements ConversationStore {
+    private readonly db;
+    constructor(path: string);
+    close(): void;
+    /** Explicit local administration only; forgetting a retry does not cancel accepted remote work. */
+    removeOutbound(key: ConversationKey, id: string): void;
+    private atomic;
+    private outbound;
+    getOutbound(key: ConversationKey, id: string): Promise<OutboundRecord | undefined>;
+    prepareOutbound(key: ConversationKey, record: OutboundRecord): Promise<OutboundRecord>;
+    settleOutbound(key: ConversationKey, id: string, result: Pick<OutboundRecord, 'phase' | 'response' | 'error'>): Promise<void>;
+    private checkpoint;
+    getCheckpoint(key: ConversationKey, conversation: string, name: string): Promise<string | undefined>;
+    advanceCheckpoint(key: ConversationKey, row: ConsumerCheckpoint, from: readonly (string | undefined)[]): Promise<void>;
+    resetCheckpoint(key: ConversationKey, conversation: string, name: string): Promise<void>;
+}

package/dist/sqlite.js

@@ -0,0 +1,80 @@
+import { DatabaseSync } from 'node:sqlite';
+import { initializeSqlite } from './sqlite-init.js';
+export { SqliteAuthStore } from './auth/sqlite-store.js';
+/** Optional durable adapter. One local SQLite database; not a secret vault. */
+export class SqliteConversationStore {
+    db;
+    constructor(path) {
+        this.db = new DatabaseSync(path);
+        initializeSqlite(this.db, () => this.db.exec(`PRAGMA busy_timeout=5000; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
+      CREATE TABLE IF NOT EXISTS outbound (
+        connection TEXT NOT NULL, issuer TEXT NOT NULL, id TEXT NOT NULL, body TEXT NOT NULL,
+        PRIMARY KEY(connection, issuer, id));
+      CREATE TABLE IF NOT EXISTS checkpoints (
+        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(connection, issuer, endpoint, conversation, name));`));
+    }
+    close() { this.db.close(); }
+    /** Explicit local administration only; forgetting a retry does not cancel accepted remote work. */
+    removeOutbound(key, id) {
+        this.atomic(() => {
+            const record = this.outbound(key, id);
+            if (record && record.endpoint !== key.endpoint)
+                throw new TypeError('outbound binding');
+            this.db.prepare('DELETE FROM outbound WHERE connection=? AND issuer=? AND id=?').run(key.connectionId, key.issuer, id);
+        });
+    }
+    atomic(action) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = action();
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    outbound(key, id) {
+        const row = this.db.prepare('SELECT body FROM outbound WHERE connection=? AND issuer=? AND id=?').get(key.connectionId, key.issuer, id);
+        return row ? JSON.parse(row.body) : undefined;
+    }
+    async getOutbound(key, id) { return this.outbound(key, id); }
+    async prepareOutbound(key, record) {
+        if (record.connectionId !== key.connectionId || record.issuer !== key.issuer || record.endpoint !== key.endpoint)
+            throw new TypeError('outbound binding');
+        return this.atomic(() => {
+            this.db.prepare('INSERT OR IGNORE INTO outbound VALUES (?,?,?,?)').run(key.connectionId, key.issuer, record.id, JSON.stringify(record));
+            return this.outbound(key, record.id);
+        });
+    }
+    async settleOutbound(key, id, result) {
+        this.atomic(() => {
+            const record = this.outbound(key, id);
+            if (!record || record.endpoint !== key.endpoint)
+                throw new TypeError('outbound binding');
+            if (record.phase !== 'pending')
+                return;
+            this.db.prepare('UPDATE outbound SET body=? WHERE connection=? AND issuer=? AND id=?').run(JSON.stringify({ ...record, ...result }), key.connectionId, key.issuer, id);
+        });
+    }
+    checkpoint(key, conversation, name) {
+        return this.db.prepare('SELECT cursor FROM checkpoints WHERE connection=? AND issuer=? AND endpoint=? AND conversation=? AND name=?')
+            .get(key.connectionId, key.issuer, key.endpoint, conversation, name)?.cursor;
+    }
+    async getCheckpoint(key, conversation, name) { return this.checkpoint(key, conversation, name); }
+    async advanceCheckpoint(key, row, from) {
+        if (row.connectionId !== key.connectionId || row.issuer !== key.issuer)
+            throw new TypeError('checkpoint binding');
+        this.atomic(() => {
+            if (!from.includes(this.checkpoint(key, row.conversationId, row.name)))
+                return;
+            this.db.prepare('INSERT OR REPLACE INTO checkpoints VALUES (?,?,?,?,?,?)').run(key.connectionId, key.issuer, key.endpoint, row.conversationId, row.name, row.cursor);
+        });
+    }
+    async resetCheckpoint(key, conversation, name) {
+        this.db.prepare('DELETE FROM checkpoints WHERE connection=? AND issuer=? AND endpoint=? AND conversation=? AND name=?').run(key.connectionId, key.issuer, key.endpoint, conversation, name);
+    }
+}

package/examples/quickstart.mjs

@@ -0,0 +1,19 @@
+import assert from 'node:assert/strict';
+import { createMetadataResolver, createNodeTransport } from '@poppykit/client';
+
+const selfCheck = process.argv.includes('--self-check');
+const domain = selfCheck ? 'company.example' : process.argv[2];
+if (!domain) throw new Error('usage: node examples/quickstart.mjs DOMAIN|--self-check');
+const transport = selfCheck ? {
+  async fetch(request) {
+    assert.equal(request.url, 'https://company.example/.well-known/poppy.json');
+    return Response.json({ protocol_version: '0.2', organization: { name: 'Example Company', domain }, web: {} });
+  },
+} : createNodeTransport();
+try {
+  const company = await createMetadataResolver(transport).resolveCompany(domain);
+  if (selfCheck) assert.equal(company.document.organization.name, 'Example Company');
+  console.log(company.document.organization);
+} finally {
+  transport.close?.();
+}

package/package.json

@@ -1,6 +1,74 @@
 {
   "name": "@poppykit/client",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "private": false,
+  "description": "Personal Agent Protocol client SDK",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LMol-4/poppykit-client.git"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.12.0"
+  },
+  "packageManager": "pnpm@11.25.0",
+  "scripts": {
+    "build": "tsc",
+    "pack": "pnpm pack",
+    "test": "npm run build:tests && node scripts/run-checks.mjs all",
+    "typecheck": "tsc --noEmit",
+    "check:docs": "node scripts/check-docs.mjs",
+    "typecheck:tests": "tsc -p tsconfig.tests.json --noEmit",
+    "build:tests": "node scripts/build-tests.mjs",
+    "coverage": "npm run build && npm run build:tests && node scripts/coverage.mjs"
+  },
+  "devDependencies": {
+    "@types/node": "24.10.0",
+    "typescript": "5.9.3"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "STORAGE.md",
+    "AUTH.md",
+    "DELIVERY.md",
+    "PROVIDER.md",
+    "INTEGRATIONS.md",
+    "API.md",
+    "CONTRIBUTING.md",
+    "SECURITY.md",
+    "CHANGELOG.md",
+    "RELEASING.md",
+    "examples",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./sqlite": {
+      "types": "./dist/sqlite.d.ts",
+      "import": "./dist/sqlite.js"
+    },
+    "./memory": {
+      "types": "./dist/memory.d.ts",
+      "import": "./dist/memory.js"
+    },
+    "./provider": {
+      "import": "./dist/provider.js",
+      "types": "./dist/provider.d.ts"
+    },
+    "./provider/sqlite": {
+      "import": "./dist/provider-sqlite.js",
+      "types": "./dist/provider-sqlite.d.ts"
+    }
+  },
+  "dependencies": {
+    "jose": "6.2.12"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}