@poppykit/client 0.1.0 → 0.2.0

package/dist/postgres-runtime.js

@@ -0,0 +1,172 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { readFile } from 'node:fs/promises';
+import pg from 'pg';
+export function json(value) {
+    return JSON.stringify(value, (_key, item) => {
+        if (item === undefined || typeof item === 'function' || typeof item === 'bigint' || (typeof item === 'number' && !Number.isFinite(item)))
+            throw new TypeError('non-JSON record');
+        return item;
+    });
+}
+export function synchronous(value) {
+    if (value && typeof value.then === 'function')
+        throw new TypeError('transaction callback must be synchronous');
+    return structuredClone(value);
+}
+/** Remote defaults verify TLS; plaintext must be explicitly selected for a trusted local test server. */
+export function createPostgresPool(config) {
+    if (config.ssl && typeof config.ssl === 'object' && config.ssl.rejectUnauthorized === false)
+        throw new TypeError('Postgres TLS verification is required');
+    if (config.connectionString && [...new URL(config.connectionString).searchParams.keys()].some(key => key.toLowerCase().startsWith('ssl') || key === 'uselibpqcompat'))
+        throw new TypeError('configure verified TLS through ssl, not connection-string overrides');
+    return new pg.Pool({ max: 2, connectionTimeoutMillis: 3000, idleTimeoutMillis: 10000, ...config, ssl: config.ssl ?? { rejectUnauthorized: true } });
+}
+export const postgresSchemaVersion = 1;
+function schemaName(schema) {
+    if (!['poppy_client', 'poppy_provider', 'poppy_server'].includes(schema))
+        throw new TypeError('unsupported Postgres schema');
+    return schema;
+}
+export async function postgresMigration(schema) {
+    schemaName(schema);
+    return readFile(new URL(`../migrations/postgres/0001_${schema}.sql`, import.meta.url), 'utf8');
+}
+/** Explicit administration only. Constructors never execute DDL. */
+export async function migratePostgres(pool, schema) {
+    schemaName(schema);
+    const client = await pool.connect();
+    try {
+        await client.query('BEGIN');
+        await client.query("SET LOCAL statement_timeout='5s'");
+        await client.query('SELECT pg_advisory_xact_lock(hashtextextended($1,0))', [`poppykit:migrate:${schema}`]);
+        const exists = (await client.query('SELECT to_regclass($1) AS name', [`${schema}.schema_version`])).rows[0].name;
+        if (exists) {
+            const rows = (await client.query(`SELECT version FROM ${schema}.schema_version`)).rows;
+            if (rows.length !== 1 || rows[0].version !== postgresSchemaVersion)
+                throw new Error('unsupported Postgres schema version');
+        }
+        else
+            await client.query(await postgresMigration(schema));
+        await client.query('COMMIT');
+    }
+    catch (error) {
+        await client.query('ROLLBACK');
+        throw error;
+    }
+    finally {
+        client.release();
+    }
+}
+function scopeActive(context) {
+    for (let scope = context; scope; scope = scope.parent)
+        if (!scope.active || !scope.state.active)
+            return false;
+    return true;
+}
+export class PostgresRuntime {
+    pool;
+    schema;
+    ownsPool;
+    context = new AsyncLocalStorage();
+    closed = false;
+    metrics = { rowsRead: 0, rowsWritten: 0 };
+    constructor(pool, schema, ownsPool = false) {
+        this.pool = pool;
+        this.schema = schema;
+        this.ownsPool = ownsPool;
+    }
+    async close() { this.closed = true; if (this.ownsPool)
+        await this.pool.end(); }
+    async run(action) {
+        if (this.closed)
+            throw new Error('Postgres adapter is closed');
+        const parent = this.context.getStore();
+        if (parent) {
+            if (!scopeActive(parent))
+                throw new Error('expired Postgres transaction');
+            if (parent.childActive)
+                throw new Error('concurrent nested Postgres transactions are unsupported; await each mutation');
+            parent.childActive = true;
+            const savepoint = `nested_${++parent.state.serial}`;
+            const child = { ...parent, parent, active: true, childActive: false, locks: new Set(parent.locks) };
+            let started = false;
+            try {
+                await parent.client.query(`SAVEPOINT ${savepoint}`);
+                started = true;
+                const result = await this.context.run(child, action);
+                if (!scopeActive(child))
+                    throw new Error('expired Postgres transaction');
+                if (child.childActive)
+                    throw new Error('unawaited nested Postgres transaction');
+                child.active = false;
+                await parent.client.query(`RELEASE SAVEPOINT ${savepoint}`);
+                parent.locks = child.locks;
+                return result;
+            }
+            catch (error) {
+                child.active = false;
+                if (started && scopeActive(parent)) {
+                    await parent.client.query(`ROLLBACK TO SAVEPOINT ${savepoint}`);
+                    await parent.client.query(`RELEASE SAVEPOINT ${savepoint}`);
+                }
+                throw error;
+            }
+            finally {
+                child.active = false;
+                parent.childActive = false;
+            }
+        }
+        const client = await this.pool.connect(), context = { client, active: true, locks: new Set(), state: { serial: 0, active: true }, childActive: false };
+        try {
+            await client.query('BEGIN');
+            await client.query("SET LOCAL statement_timeout='5s'");
+            await client.query("SET LOCAL lock_timeout='2s'");
+            await client.query("SET LOCAL idle_in_transaction_session_timeout='5s'");
+            await client.query("SET LOCAL transaction_timeout='5s'");
+            const versions = (await client.query(`SELECT version FROM ${this.schema}.schema_version`)).rows;
+            if (versions.length !== 1 || versions[0].version !== postgresSchemaVersion)
+                throw new Error('unsupported Postgres schema version');
+            const result = await this.context.run(context, action);
+            if (context.childActive)
+                throw new Error('unawaited nested Postgres transaction');
+            await client.query('COMMIT');
+            return result;
+        }
+        catch (error) {
+            context.state.active = false;
+            await client.query('ROLLBACK').catch(() => { });
+            throw error;
+        }
+        finally {
+            context.active = false;
+            context.state.active = false;
+            client.release();
+        }
+    }
+    connection() {
+        const context = this.context.getStore();
+        if (!context || !scopeActive(context))
+            throw new Error('no active Postgres transaction');
+        return { query: async (sql, values) => {
+                if (!scopeActive(context) || this.context.getStore() !== context)
+                    throw new Error('expired Postgres transaction');
+                if (context.childActive)
+                    throw new Error('concurrent Postgres transaction use is unsupported; await each mutation');
+                return context.client.query(sql, values);
+            } };
+    }
+    async query(sql, values = []) {
+        const result = await this.connection().query(sql, values);
+        this.metrics.rowsRead += result.rows.length;
+        return result.rows;
+    }
+    async lock(key) {
+        const context = this.context.getStore();
+        if (!context || !scopeActive(context))
+            throw new Error('no active Postgres transaction');
+        if (!context.locks.has(key)) {
+            await this.query('SELECT pg_advisory_xact_lock(hashtextextended($1,0))', [`${this.schema}:${key}`]);
+            context.locks.add(key);
+        }
+    }
+}

package/dist/postgres.d.ts

@@ -0,0 +1,39 @@
+import type { Pool } from 'pg';
+import type { ClientAuthState } from './auth/client-auth.js';
+import type { AuthSelection, AuthStore } from './auth/store.js';
+import type { ConversationKey, ConversationStore } from './conversation-store.js';
+import type { ConsumerCheckpoint, OutboundRecord } from './conversation.js';
+export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
+/** Namespaced references only; credentials still belong in SecretStore. The pool remains caller-owned. */
+export declare class PostgresAuthStore implements AuthStore {
+    readonly namespace: string;
+    private readonly db;
+    constructor(pool: Pool, namespace: string);
+    close(): Promise<void>;
+    get metrics(): {
+        rowsRead: number;
+        rowsWritten: number;
+    };
+    private select;
+    read(selection: AuthSelection): Promise<ClientAuthState>;
+    transaction<T>(selection: AuthSelection, change: (draft: ClientAuthState) => T): Promise<T>;
+    private put;
+    pendingOperations(after: string | undefined, limit: number): Promise<string[]>;
+    cleanup(before: number, limit?: number): Promise<number>;
+}
+export declare class PostgresConversationStore implements ConversationStore {
+    readonly namespace: string;
+    private readonly db;
+    constructor(pool: Pool, namespace: string);
+    close(): Promise<void>;
+    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>;
+    removeOutbound(key: ConversationKey, id: string): Promise<void>;
+    private checkpointValues;
+    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/postgres.js

@@ -0,0 +1,143 @@
+import { initialClientAuthState } from './auth/client-auth.js';
+import { PostgresRuntime, json, synchronous } from './postgres-runtime.js';
+export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
+const tables = ['identities', 'connections', 'grants', 'operations', 'cleanup'];
+/** Namespaced references only; credentials still belong in SecretStore. The pool remains caller-owned. */
+export class PostgresAuthStore {
+    namespace;
+    db;
+    constructor(pool, namespace) {
+        this.namespace = namespace;
+        this.db = new PostgresRuntime(pool, 'poppy_client');
+    }
+    close() { return this.db.close(); }
+    get metrics() { return this.db.metrics; }
+    async select(selection) {
+        // Epoch/owner are shared by this auth namespace and must fence every connection mutation.
+        await this.db.lock(`${this.namespace}:auth`);
+        const get = async (table, id) => (await this.db.query('SELECT body FROM poppy_client.records WHERE ns=$1 AND kind=$2 AND id=$3', [this.namespace, table, id]))[0];
+        const meta = await get('auth_meta', 'meta');
+        const initial = initialClientAuthState();
+        if (!meta)
+            await this.put('auth_meta', 'meta', { version: initial.version, epoch: initial.epoch, owner: initial.owner });
+        const state = { ...(meta ? JSON.parse(meta.body) : { version: initial.version, epoch: initial.epoch, owner: initial.owner }), identities: {}, connections: {}, grants: {}, operations: {}, cleanup: {} };
+        const one = async (table, id) => { const row = await get(table, id); if (row)
+            state[table][id] = JSON.parse(row.body); };
+        const rows = async (table, where, values = []) => {
+            for (const row of await this.db.query(`SELECT id,body FROM poppy_client.records WHERE ns=$1 AND kind=$2 ${where}`, [this.namespace, table, ...values]))
+                state[table][row.id] = JSON.parse(row.body);
+        };
+        if ('issuer' in selection)
+            await one('identities', selection.issuer);
+        else {
+            if ('connectionId' in selection)
+                await one('connections', selection.connectionId);
+            else if ('operationId' in selection)
+                await one('operations', selection.operationId);
+            else if ('callbackHash' in selection)
+                await rows('operations', "AND body::jsonb#>>'{direct,stateHash}'=$3", [selection.callbackHash]);
+            else
+                await rows('connections', '');
+            for (const operation of Object.values(state.operations))
+                await one('connections', operation.connectionId);
+            for (const connection of Object.values(state.connections)) {
+                if (connection.grantId)
+                    await one('grants', connection.grantId);
+                if (!('list' in selection)) {
+                    await rows('operations', "AND body::jsonb->>'connectionId'=$3", [connection.id]);
+                    await rows('cleanup', "AND body::jsonb->>'connectionId'=$3", [connection.id]);
+                }
+            }
+            for (const operation of Object.values(state.operations))
+                if (operation.grantId)
+                    await one('grants', operation.grantId);
+        }
+        return state;
+    }
+    read(selection) { return this.db.run(() => this.select(selection)); }
+    transaction(selection, change) {
+        return this.db.run(async () => {
+            const state = await this.select(selection), before = structuredClone(state), result = synchronous(change(state));
+            const { version, epoch, owner } = state;
+            await this.put('auth_meta', 'meta', { version, epoch, owner });
+            for (const table of tables) {
+                for (const id of Object.keys(before[table]))
+                    if (!Object.hasOwn(state[table], id))
+                        await this.db.query('DELETE FROM poppy_client.records WHERE ns=$1 AND kind=$2 AND id=$3', [this.namespace, table, id]);
+                for (const [id, value] of Object.entries(state[table]))
+                    if (json(value) !== json(before[table][id] ?? null))
+                        await this.put(table, id, value);
+            }
+            return result;
+        });
+    }
+    async put(kind, id, value) {
+        await this.db.query('INSERT INTO poppy_client.records(ns,kind,id,body) VALUES($1,$2,$3,$4) ON CONFLICT(ns,kind,id) DO UPDATE SET body=excluded.body', [this.namespace, kind, id, json(value)]);
+        this.db.metrics.rowsWritten++;
+    }
+    async pendingOperations(after, limit) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new TypeError('recovery limit');
+        return this.db.run(async () => (await this.db.query("SELECT id FROM poppy_client.records WHERE ns=$1 AND kind='operations' AND body::jsonb->>'phase'!='terminal' AND id>$2 ORDER BY id LIMIT $3", [this.namespace, after ?? '', limit])).map(row => row.id));
+    }
+    async cleanup(before, limit = 100) {
+        if (!Number.isFinite(before) || !Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new TypeError('cleanup limit');
+        return this.db.run(async () => { await this.db.lock(`${this.namespace}:auth`); return (await this.db.query("DELETE FROM poppy_client.records WHERE ns=$1 AND kind='operations' AND id IN (SELECT id FROM poppy_client.records WHERE ns=$1 AND kind='operations' AND body::jsonb->>'phase'='terminal' AND body::jsonb->>'status'!='uncertain' AND (body::jsonb->>'createdAt')::double precision<$2 ORDER BY (body::jsonb->>'createdAt')::double precision LIMIT $3) RETURNING id", [this.namespace, before, limit])).length; });
+    }
+}
+export class PostgresConversationStore {
+    namespace;
+    db;
+    constructor(pool, namespace) {
+        this.namespace = namespace;
+        this.db = new PostgresRuntime(pool, 'poppy_client');
+    }
+    close() { return this.db.close(); }
+    async outbound(key, id) {
+        const row = (await this.db.query('SELECT body FROM poppy_client.outbound WHERE ns=$1 AND connection=$2 AND issuer=$3 AND id=$4', [this.namespace, key.connectionId, key.issuer, id]))[0];
+        return row ? JSON.parse(row.body) : undefined;
+    }
+    getOutbound(key, id) { return this.db.run(() => 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.db.run(async () => {
+            await this.db.query('INSERT INTO poppy_client.outbound VALUES($1,$2,$3,$4,$5) ON CONFLICT DO NOTHING', [this.namespace, key.connectionId, key.issuer, record.id, json(record)]);
+            return (await this.outbound(key, record.id));
+        });
+    }
+    settleOutbound(key, id, result) {
+        return this.db.run(async () => {
+            await this.db.lock(JSON.stringify([this.namespace, 'outbound', key.connectionId, key.issuer, id]));
+            const record = await this.outbound(key, id);
+            if (!record || record.endpoint !== key.endpoint)
+                throw new TypeError('outbound binding');
+            if (record.phase === 'pending')
+                await this.db.query('UPDATE poppy_client.outbound SET body=$5 WHERE ns=$1 AND connection=$2 AND issuer=$3 AND id=$4', [this.namespace, key.connectionId, key.issuer, id, json({ ...record, ...result })]);
+        });
+    }
+    removeOutbound(key, id) {
+        return this.db.run(async () => {
+            await this.db.lock(JSON.stringify([this.namespace, 'outbound', key.connectionId, key.issuer, id]));
+            const record = await this.outbound(key, id);
+            if (record && record.endpoint !== key.endpoint)
+                throw new TypeError('outbound binding');
+            await this.db.query('DELETE FROM poppy_client.outbound WHERE ns=$1 AND connection=$2 AND issuer=$3 AND id=$4', [this.namespace, key.connectionId, key.issuer, id]);
+        });
+    }
+    checkpointValues(key, conversation, name) { return [this.namespace, key.connectionId, key.issuer, key.endpoint, conversation, name]; }
+    async checkpoint(key, conversation, name) { return (await this.db.query('SELECT cursor FROM poppy_client.checkpoints WHERE ns=$1 AND connection=$2 AND issuer=$3 AND endpoint=$4 AND conversation=$5 AND name=$6', this.checkpointValues(key, conversation, name)))[0]?.cursor; }
+    getCheckpoint(key, conversation, name) { return this.db.run(() => this.checkpoint(key, conversation, name)); }
+    async advanceCheckpoint(key, row, from) {
+        if (row.connectionId !== key.connectionId || row.issuer !== key.issuer)
+            throw new TypeError('checkpoint binding');
+        return this.db.run(async () => {
+            const values = this.checkpointValues(key, row.conversationId, row.name);
+            await this.db.lock(JSON.stringify(['checkpoint', ...values]));
+            if (from.includes(await this.checkpoint(key, row.conversationId, row.name)))
+                await this.db.query('INSERT INTO poppy_client.checkpoints VALUES($1,$2,$3,$4,$5,$6,$7) ON CONFLICT(ns,connection,issuer,endpoint,conversation,name) DO UPDATE SET cursor=excluded.cursor', [...values, row.cursor]);
+        });
+    }
+    resetCheckpoint(key, conversation, name) { return this.db.run(async () => { const values = this.checkpointValues(key, conversation, name); await this.db.lock(JSON.stringify(['checkpoint', ...values])); await this.db.query('DELETE FROM poppy_client.checkpoints WHERE ns=$1 AND connection=$2 AND issuer=$3 AND endpoint=$4 AND conversation=$5 AND name=$6', values); }); }
+}

package/dist/provider-postgres.d.ts

@@ -0,0 +1,15 @@
+import type { Pool } from 'pg';
+import type { ProviderSelection, ProviderStore, ProviderTransaction } from './provider.js';
+export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } 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;
+    private readonly db;
+    constructor(pool: Pool, namespace: string);
+    close(): Promise<void>;
+    get metrics(): {
+        rowsRead: number;
+        rowsWritten: number;
+    };
+    transaction<T>(selection: ProviderSelection, action: (tx: ProviderTransaction) => T): Promise<T>;
+}

package/dist/provider-postgres.js

@@ -0,0 +1,96 @@
+import { providerMemoryTransaction, providerUserKey, scopedProviderTransaction } from './provider-storage.js';
+import { PostgresRuntime, json, synchronous } from './postgres-runtime.js';
+export { createPostgresPool, migratePostgres, postgresMigration, postgresSchemaVersion } from './postgres-runtime.js';
+/** Targeted provider aggregates. Cryptography and human/session verification run outside its transactions. */
+export class PostgresProviderStore {
+    namespace;
+    db;
+    constructor(pool, namespace) {
+        this.namespace = namespace;
+        this.db = new PostgresRuntime(pool, 'poppy_provider');
+    }
+    close() { return this.db.close(); }
+    get metrics() { return this.db.metrics; }
+    transaction(selection, action) {
+        return this.db.run(async () => {
+            const rows = new Map();
+            const one = async (kind, id) => {
+                const row = (await this.db.query('SELECT body FROM poppy_provider.records WHERE ns=$1 AND kind=$2 AND id=$3', [this.namespace, kind, id]))[0];
+                const key = JSON.stringify([kind, id]);
+                rows.delete(key);
+                if (row)
+                    rows.set(key, JSON.parse(row.body));
+                return row ? JSON.parse(row.body) : undefined;
+            };
+            const lock = (kind, id) => this.db.lock(JSON.stringify([this.namespace, kind, id]));
+            if (selection.kind === 'enroll') {
+                await lock('capacity', 'enrollments');
+                await one('capacity', 'enrollments');
+                await one('visitor', selection.subjectHash);
+                await one('enrollmentRequest', selection.requestHash);
+            }
+            else {
+                const lookup = selection.kind === 'callback' ? await one('state', selection.stateHash) : undefined;
+                const enrollmentId = selection.kind === 'callback' ? lookup?.enrollmentId : selection.enrollmentId;
+                if (enrollmentId) {
+                    await lock('enrollment', enrollmentId);
+                    const enrollment = await one('enrollment', enrollmentId);
+                    if ('issuer' in selection && enrollment) {
+                        const key = providerUserKey(enrollment.visitor, selection.issuer);
+                        await lock('user', key);
+                        await one('user', key);
+                    }
+                    if (selection.kind === 'begin' || selection.kind === 'revoke') {
+                        const operations = await this.db.query("SELECT id,body FROM poppy_provider.records WHERE ns=$1 AND kind='operation' AND split_part(id,':',1)=$2 ORDER BY id LIMIT 1001", [this.namespace, enrollmentId]);
+                        for (const row of operations)
+                            rows.set(JSON.stringify(['operation', row.id]), JSON.parse(row.body));
+                        if (operations.length > 1000)
+                            throw new Error('provider aggregate exceeds retained operation limit');
+                        if (selection.kind === 'begin') {
+                            const states = new Set();
+                            if (selection.stateHash)
+                                states.add(selection.stateHash);
+                            for (const row of operations) {
+                                const hash = JSON.parse(row.body).binding?.stateHash;
+                                if (hash)
+                                    states.add(hash);
+                            }
+                            for (const hash of [...states].sort()) {
+                                await lock('state', hash);
+                                await one('state', hash);
+                            }
+                        }
+                    }
+                    else {
+                        if (selection.kind === 'callback') {
+                            // Re-resolve after the enrollment lock; cleanup may have removed/rebound the selector.
+                            const current = await one('state', selection.stateHash);
+                            if (json(current ?? null) !== json(lookup ?? null))
+                                throw new Error('provider callback selector changed');
+                        }
+                        const operationId = selection.kind === 'callback' ? lookup?.operationId : 'operationId' in selection ? selection.operationId : undefined;
+                        if (operationId)
+                            await one('operation', `${enrollmentId}:${operationId}`);
+                    }
+                }
+            }
+            const before = new Map([...rows].map(([key, value]) => [key, json(value)]));
+            const result = synchronous(action(scopedProviderTransaction(selection, providerMemoryTransaction(rows))));
+            const removed = [...before.keys()].filter(key => !rows.has(key)).map(key => { const [kind, id] = JSON.parse(key); return { kind, id }; });
+            if (removed.length)
+                await this.db.query('DELETE FROM poppy_provider.records r USING jsonb_to_recordset($2::jsonb) AS d(kind text,id text) WHERE r.ns=$1 AND r.kind=d.kind AND r.id=d.id', [this.namespace, json(removed)]);
+            const changed = [];
+            for (const [key, value] of rows) {
+                const body = json(value);
+                if (before.get(key) === body)
+                    continue;
+                const [kind, id] = JSON.parse(key);
+                changed.push({ kind, id, body });
+            }
+            if (changed.length)
+                await this.db.query('INSERT INTO poppy_provider.records(ns,kind,id,body) SELECT $1,kind,id,body FROM jsonb_to_recordset($2::jsonb) AS d(kind text,id text,body text) ON CONFLICT(ns,kind,id) DO UPDATE SET body=excluded.body', [this.namespace, json(changed)]);
+            this.metrics.rowsWritten += removed.length + changed.length;
+            return result;
+        });
+    }
+}

package/dist/provider-sqlite.d.ts

@@ -1,8 +1,8 @@
-import type { ProviderStore, ProviderTransaction } from './provider.js';
+import type { ProviderSelection, ProviderStore, ProviderTransaction } from './provider.js';
 /** Optional durable provider records. Callback results must be encrypted by the separately configured cipher. */
 export declare class SqliteProviderStore implements ProviderStore {
     private readonly db;
     constructor(path: string);
     close(): void;
-    transaction<T>(action: (tx: ProviderTransaction) => T): T;
+    transaction<T>(selection: ProviderSelection, action: (tx: ProviderTransaction) => T): Promise<T>;
 }

package/dist/provider-sqlite.js

@@ -1,26 +1,29 @@
 import { DatabaseSync } from 'node:sqlite';
 import { initializeSqlite } from './sqlite-init.js';
+import { scopedProviderTransaction } from './provider-storage.js';
 /** Optional durable provider records. Callback results must be encrypted by the separately configured cipher. */
 export class SqliteProviderStore {
     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 provider_records(kind TEXT NOT NULL,id TEXT NOT NULL,body TEXT NOT NULL,PRIMARY KEY(kind,id));'));
+        this.db.exec(`INSERT OR IGNORE INTO provider_records SELECT 'capacity','enrollments',json_object('count',count(*)) FROM provider_records WHERE kind='enrollment'`);
     }
     close() { this.db.close(); }
-    transaction(action) {
+    async transaction(selection, action) {
         this.db.exec('BEGIN IMMEDIATE');
         try {
-            const result = action({
+            const result = action(scopedProviderTransaction(selection, {
                 get: (kind, id) => { const row = this.db.prepare('SELECT body FROM provider_records WHERE kind=? AND id=?').get(kind, id); return row ? JSON.parse(row.body) : undefined; },
                 put: (kind, id, value) => { this.db.prepare('INSERT OR REPLACE INTO provider_records VALUES (?,?,?)').run(kind, id, JSON.stringify(value)); },
                 remove: (kind, id) => { this.db.prepare('DELETE FROM provider_records WHERE kind=? AND id=?').run(kind, id); },
-                list: (kind, prefix, limit) => this.db.prepare('SELECT id,body FROM provider_records WHERE kind=? AND id>=? AND id<? ORDER BY id LIMIT ?').all(kind, prefix, `${prefix}\uffff`, limit).map(row => ({ id: row.id, value: JSON.parse(row.body) })),
-            });
-            if (result instanceof Promise)
+                list: (kind, prefix, limit) => this.db.prepare('SELECT id,body FROM provider_records WHERE kind=? AND id>=? AND id<? ORDER BY id LIMIT ?').all(kind, prefix, `${prefix.slice(0, -1)};`, limit).map(row => ({ id: row.id, value: JSON.parse(row.body) })),
+            }));
+            if (result && typeof result.then === 'function')
                 throw new TypeError('provider transaction must be synchronous');
+            const detached = structuredClone(result);
             this.db.exec('COMMIT');
-            return result;
+            return detached;
         }
         catch (error) {
             this.db.exec('ROLLBACK');

package/dist/provider-storage.d.ts

@@ -0,0 +1,7 @@
+import type { ProviderSelection, ProviderTransaction } from './provider.js';
+type Row = Record<string, any>;
+export declare const providerUserKey: (visitor: string, issuer: string) => string;
+/** Enforces the same aggregate boundary for local, remote and custom stores. */
+export declare function scopedProviderTransaction(selection: ProviderSelection, raw: ProviderTransaction): ProviderTransaction;
+export declare function providerMemoryTransaction(rows: Map<string, Row>): ProviderTransaction;
+export {};

package/dist/provider-storage.js

@@ -0,0 +1,61 @@
+import { createHash } from 'node:crypto';
+export const providerUserKey = (visitor, issuer) => createHash('sha256').update(JSON.stringify([visitor, issuer])).digest('base64url');
+/** Enforces the same aggregate boundary for local, remote and custom stores. */
+export function scopedProviderTransaction(selection, raw) {
+    let enrollmentId = 'enrollmentId' in selection ? selection.enrollmentId : undefined;
+    let operationId = 'operationId' in selection ? selection.operationId : undefined;
+    if (selection.kind === 'callback') {
+        const lookup = raw.get('state', selection.stateHash);
+        enrollmentId = lookup?.enrollmentId;
+        operationId = lookup?.operationId;
+    }
+    const enrollment = enrollmentId ? raw.get('enrollment', enrollmentId) : undefined;
+    const userKey = 'issuer' in selection && enrollment ? providerUserKey(enrollment.visitor, selection.issuer) : undefined;
+    const states = new Set();
+    if (selection.kind === 'callback')
+        states.add(selection.stateHash);
+    if (selection.kind === 'begin') {
+        if (selection.stateHash)
+            states.add(selection.stateHash);
+        for (const row of raw.list('operation', `${enrollmentId}:`, 1001))
+            if (row.value.binding?.stateHash)
+                states.add(row.value.binding.stateHash);
+    }
+    let createdEnrollment;
+    const check = (kind, id, write = false) => {
+        let allowed = false;
+        if (selection.kind === 'enroll') {
+            allowed = (kind === 'capacity' && id === 'enrollments') || (kind === 'visitor' && id === selection.subjectHash) || (kind === 'enrollmentRequest' && id === selection.requestHash);
+            if (kind === 'enrollment' && write && (!createdEnrollment || createdEnrollment === id) && !raw.get(kind, id)) {
+                createdEnrollment = id;
+                allowed = true;
+            }
+        }
+        else {
+            allowed = (kind === 'enrollment' && id === enrollmentId) || (kind === 'user' && id === userKey) || (kind === 'state' && states.has(id));
+            if (kind === 'operation')
+                allowed = (selection.kind === 'begin' || selection.kind === 'revoke') ? id.startsWith(`${enrollmentId}:`) : id === `${enrollmentId}:${operationId}`;
+        }
+        if (!allowed)
+            throw new TypeError('provider access outside selection');
+    };
+    return {
+        get(kind, id) { check(kind, id); return raw.get(kind, id); },
+        put(kind, id, value) { check(kind, id, true); raw.put(kind, id, value); },
+        remove(kind, id) { check(kind, id); raw.remove(kind, id); },
+        list(kind, prefix, limit) {
+            if (!['begin', 'revoke'].includes(selection.kind) || kind !== 'operation' || prefix !== `${enrollmentId}:` || !Number.isSafeInteger(limit) || limit < 1 || limit > 1001)
+                throw new TypeError('provider list outside selection');
+            return raw.list(kind, prefix, limit);
+        },
+    };
+}
+export function providerMemoryTransaction(rows) {
+    const key = (kind, id) => JSON.stringify([kind, id]);
+    return {
+        get: (kind, id) => rows.get(key(kind, id)),
+        put: (kind, id, value) => { rows.set(key(kind, id), value); },
+        remove: (kind, id) => { rows.delete(key(kind, id)); },
+        list: (kind, prefix, limit) => [...rows].map(([key, value]) => ({ key: JSON.parse(key), value })).filter(row => row.key[0] === kind && row.key[1].startsWith(prefix)).sort((a, b) => a.key[1].localeCompare(b.key[1])).slice(0, limit).map(row => ({ id: row.key[1], value: row.value })),
+    };
+}