@poppykit/server 0.4.0 → 0.5.0

package/dist/operations.d.ts

@@ -0,0 +1,115 @@
+import type { AuthorityPolicy, Principal } from './auth/authority.js';
+import type { MetadataResolver } from './network/discovery.js';
+import type { Json } from './protocol/wire.js';
+import type { BusinessOperation, OperationApproval, OperationRequest } from './protocol/operations.js';
+export type BusinessOwner = {
+    companyId: string;
+    clientId: string;
+    userId: string;
+} & ({
+    accountId: string;
+} | {
+    sessionId: string;
+    sessionInstanceId: string;
+    sessionGeneration: string;
+});
+export interface OperationRevision {
+    operation: BusinessOperation;
+    request: OperationRequest;
+}
+export interface BusinessOperationRecord {
+    version: 1;
+    id: string;
+    owner: BusinessOwner;
+    scopes: string[];
+    revisions: Record<string, OperationRevision>;
+    execution?: {
+        revision: string;
+        key: string;
+        claimedAt: number;
+        retainUntil: number;
+        phase: 'uncertain' | 'completed';
+        result?: Json;
+    };
+}
+/** Cross-process serializable transaction for one business action. Keep tombstones/claims forever until explicit safe retirement.
+ * Local effects MUST enlist in this transaction; roll back records and effects on any throw, including commit failure.
+ * External effects MUST NOT run inside it. Implementations reject unknown versions and return detached snapshots.
+ */
+export interface BusinessOperationStore {
+    transaction<T>(operationId: string, action: (slot: {
+        record?: BusinessOperationRecord;
+    }) => Promise<T>): Promise<T>;
+}
+export interface OperationInput {
+    /** Host-selected business identity, stable across revisions/retries; never take this from an untrusted approval. */
+    operationId: string;
+    principal: Principal;
+    request: OperationRequest;
+    scopes: readonly string[];
+    approval?: OperationApproval;
+    proposal(): {
+        summary: string;
+        terms?: BusinessOperation['terms'];
+        expires_at: string;
+    };
+}
+export type OperationOutcome = {
+    kind: 'approval_required';
+    operation: BusinessOperation;
+} | {
+    kind: 'pending';
+    retryAfter: number;
+} | {
+    kind: 'completed';
+    result: Json;
+    replay: boolean;
+};
+export interface ExternalOperationEffect {
+    /** Host guarantees one durable effect per key, including concurrent callers and retries after process death. */
+    execute(input: {
+        key: string;
+        operation: BusinessOperation;
+    }): Promise<Json>;
+    /** Never return absent until the old worker cannot later commit outside the same idempotency fence. */
+    reconcile(input: {
+        key: string;
+        operation: BusinessOperation;
+    }): Promise<{
+        kind: 'pending';
+    } | {
+        kind: 'completed';
+        result: Json;
+    } | {
+        kind: 'absent';
+    }>;
+}
+export declare class BusinessOperationError extends Error {
+    readonly code: 'operation_not_found' | 'extension_required';
+    constructor(code: 'operation_not_found' | 'extension_required');
+    response(): Response;
+}
+export declare function operationPendingResponse(retryAfter?: number): Response;
+export declare function createBusinessOperations(options: {
+    companyId: string;
+    metadata: MetadataResolver;
+    policy: AuthorityPolicy;
+    store: BusinessOperationStore;
+    now?: () => number;
+    retentionMs?: number;
+    maxRevisions?: number;
+    effectTimeoutMs?: number;
+}): {
+    /** No effect: proposes terms or returns an existing execution's state. */
+    propose(input: OperationInput): Promise<OperationOutcome>;
+    /** Only same-database effects. The host must use this store's coordinator/transaction handle. No network I/O. */
+    local(input: OperationInput, effect: (revision: BusinessOperation) => Promise<Json>): Promise<OperationOutcome>;
+    external(input: OperationInput, effect: ExternalOperationEffect): Promise<OperationOutcome>;
+    /** Explicit host reconciliation only; a lease expiring never releases an execution claim. */
+    reconcile(input: OperationInput, effect: ExternalOperationEffect): Promise<OperationOutcome>;
+    /** Drop protected result bodies only after retention; retain the action fence and never re-execute it. */
+    prune(operationId: string): Promise<void>;
+};
+export declare function operationApiResponse(outcome: OperationOutcome, success?: (result: Json) => Response): Response;
+/** A tool's missing extension is an ordinary tool error, not an OAuth refusal of the whole MCP client. */
+export declare function operationMcpResponse(outcome: OperationOutcome | BusinessOperationError): Response;

package/dist/operations.js

@@ -0,0 +1,212 @@
+import { randomBytes, createHash } from 'node:crypto';
+import { AuthorityError } from './auth/authority.js';
+import { canonical, id, validateJson } from './protocol/wire.js';
+import { operationRequiredResponse, operationToolError, operationExpiry, parseBusinessOperation, parseOperationApproval, requestFingerprint, supportsOperations } from './protocol/operations.js';
+export class BusinessOperationError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+    response() {
+        return this.code === 'extension_required'
+            ? new Response(null, { status: 403, headers: { 'WWW-Authenticate': 'Bearer error="extension_required", extension="operations"', 'Cache-Control': 'no-store' } })
+            : Response.json({ error: this.code }, { status: 404, headers: { 'Cache-Control': 'no-store' } });
+    }
+}
+function owner(principal) {
+    if (!principal.sessionId || !principal.userId || !principal.sessionInstanceId || !principal.sessionGeneration)
+        throw new AuthorityError('invalid_session');
+    const base = { companyId: principal.issuer, clientId: principal.clientId, userId: principal.userId };
+    if (principal.accountId)
+        return { ...base, accountId: principal.accountId };
+    if (!principal.sessionInstanceId || !principal.sessionGeneration)
+        throw new AuthorityError('invalid_session');
+    return { ...base, sessionId: principal.sessionId, sessionInstanceId: principal.sessionInstanceId, sessionGeneration: principal.sessionGeneration };
+}
+function owned(record, principal) {
+    const o = record.owner;
+    if (o.companyId !== principal.issuer || o.clientId !== principal.clientId || o.userId !== principal.userId)
+        throw new BusinessOperationError('operation_not_found');
+    if ('accountId' in o) {
+        if (!principal.accountId)
+            throw new AuthorityError('account_required', { scope: record.scopes.join(' ') });
+        if (o.accountId !== principal.accountId)
+            throw new BusinessOperationError('operation_not_found');
+    }
+    else if (o.sessionId !== principal.sessionId || o.sessionInstanceId !== principal.sessionInstanceId || o.sessionGeneration !== principal.sessionGeneration)
+        throw new BusinessOperationError('operation_not_found');
+}
+export function operationPendingResponse(retryAfter = 1) {
+    return Response.json({ error: 'operation_pending' }, { status: 503, headers: { 'Retry-After': String(retryAfter), 'Cache-Control': 'no-store' } });
+}
+export function createBusinessOperations(options) {
+    const effectTimeoutMs = options.effectTimeoutMs ?? 30000;
+    if (!Number.isSafeInteger(effectTimeoutMs) || effectTimeoutMs < 1)
+        throw new TypeError('effectTimeoutMs');
+    const maxRevisions = options.maxRevisions ?? 1000;
+    if (!Number.isSafeInteger(maxRevisions) || maxRevisions < 1)
+        throw new TypeError('maxRevisions');
+    const now = options.now ?? Date.now, retentionMs = options.retentionMs ?? 86400000;
+    if (!Number.isSafeInteger(retentionMs) || retentionMs < 0)
+        throw new TypeError('operation retention');
+    async function gate(input, action) {
+        id(input.operationId, 'operation_id');
+        requestFingerprint(input.request);
+        owner(input.principal); // Every channel requires a verified Poppy Session, including signed-in MCP.
+        if (input.principal.issuer !== options.companyId)
+            throw new AuthorityError('invalid_session');
+        if (!supportsOperations(await options.metadata.resolveClient(input.principal.clientId)))
+            throw new BusinessOperationError('extension_required');
+        return options.policy.withCurrent(input.principal, input.scopes, () => options.store.transaction(input.operationId, async (slot) => {
+            if (slot.record && slot.record.version !== 1)
+                throw new Error('unsupported business operation version');
+            const record = slot.record ?? { version: 1, id: input.operationId, owner: owner(input.principal), scopes: [...input.scopes], revisions: {} };
+            owned(record, input.principal);
+            if (canonical(record.scopes.slice().sort()) !== canonical([...input.scopes].sort()))
+                throw new TypeError('operation scope contract changed');
+            slot.record = record;
+            return action(record);
+        }));
+    }
+    function inspect(record, input) {
+        const approval = input.approval && parseOperationApproval(input.approval);
+        // Ownership and current authority precede receipt replay, even for expired revisions.
+        if (record.execution) {
+            if (record.execution.phase === 'completed' && record.execution.result !== undefined)
+                return { kind: 'completed', result: structuredClone(record.execution.result), replay: true };
+            if (record.execution.phase === 'uncertain')
+                return { kind: 'pending', retryAfter: 1 };
+        }
+        const revision = !record.execution && approval?.operation_id === record.id ? (Object.hasOwn(record.revisions, approval.revision) ? record.revisions[approval.revision] : undefined) : undefined;
+        if (revision && operationExpiry(revision.operation.expires_at) > now() && requestFingerprint(revision.request) === requestFingerprint(input.request))
+            return revision;
+        const proposed = input.proposal();
+        const operation = parseBusinessOperation({ ...proposed, operation_id: record.id, revision: randomBytes(24).toString('base64url') });
+        if (operationExpiry(operation.expires_at) <= now())
+            throw new TypeError('proposal already expired');
+        // Completed/uncertain actions are never reopened, even after receipt cleanup or a new revision.
+        if (record.execution)
+            return { kind: 'approval_required', operation };
+        for (const [key, value] of Object.entries(record.revisions))
+            if (operationExpiry(value.operation.expires_at) <= now())
+                delete record.revisions[key];
+        if (Object.keys(record.revisions).length >= maxRevisions)
+            throw new AuthorityError('rate_limited', { retryAfter: 60 });
+        record.revisions[operation.revision] = { operation, request: structuredClone(input.request) };
+        return { kind: 'approval_required', operation };
+    }
+    function claim(record, revision) {
+        record.execution = { revision: revision.operation.revision, key: createHash('sha256').update(canonical([options.companyId, record.id])).digest('base64url'), claimedAt: now(),
+            retainUntil: Math.max(operationExpiry(revision.operation.expires_at), now() + retentionMs), phase: 'uncertain' };
+    }
+    function complete(record, result, input) {
+        if (record.execution?.phase === 'completed')
+            return inspect(record, input);
+        validateJson(result);
+        record.execution.phase = 'completed';
+        record.execution.result = structuredClone(result);
+        return { kind: 'completed', result: structuredClone(result), replay: false };
+    }
+    async function externalResult(action) {
+        let timer;
+        try {
+            return await Promise.race([
+                Promise.resolve().then(action).then(value => ({ ok: true, value }), () => ({ ok: false })),
+                new Promise(resolve => { timer = setTimeout(() => resolve({ ok: false }), effectTimeoutMs); }),
+            ]);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    return {
+        /** No effect: proposes terms or returns an existing execution's state. */
+        propose(input) { return gate({ ...input, approval: undefined }, async (record) => inspect(record, { ...input, approval: undefined })); },
+        /** Only same-database effects. The host must use this store's coordinator/transaction handle. No network I/O. */
+        local(input, effect) {
+            return gate(input, async (record) => {
+                const found = inspect(record, input);
+                if ('kind' in found)
+                    return found;
+                claim(record, found);
+                const result = await effect(structuredClone(found.operation));
+                return complete(record, result, input);
+            });
+        },
+        async external(input, effect) {
+            const selected = await gate(input, async (record) => {
+                const found = inspect(record, input);
+                if ('kind' in found)
+                    return { outcome: found };
+                claim(record, found);
+                return { key: record.execution.key, operation: structuredClone(found.operation) };
+            });
+            if ('outcome' in selected)
+                return selected.outcome;
+            await options.policy.withCurrent(input.principal, input.scopes, async () => { });
+            const attempted = await externalResult(async () => {
+                const result = await effect.execute({ key: selected.key, operation: selected.operation });
+                validateJson(result);
+                return result;
+            });
+            if (!attempted.ok)
+                return { kind: 'pending', retryAfter: 1 };
+            return gate(input, async (record) => complete(record, attempted.value, input));
+        },
+        /** Explicit host reconciliation only; a lease expiring never releases an execution claim. */
+        async reconcile(input, effect) {
+            const selected = await gate(input, async (record) => {
+                if (!record.execution)
+                    throw new BusinessOperationError('operation_not_found');
+                if (record.execution.phase === 'completed') {
+                    if (record.execution.result === undefined)
+                        return { outcome: inspect(record, input) };
+                    return { outcome: { kind: 'completed', result: record.execution.result, replay: true } };
+                }
+                return { key: record.execution.key, operation: structuredClone(record.revisions[record.execution.revision].operation) };
+            });
+            if ('outcome' in selected)
+                return selected.outcome;
+            const checked = await externalResult(() => effect.reconcile({ key: selected.key, operation: selected.operation }));
+            if (!checked.ok)
+                return { kind: 'pending', retryAfter: 1 };
+            let resolved = checked.value;
+            if (resolved.kind === 'pending')
+                return { kind: 'pending', retryAfter: 1 };
+            if (resolved.kind === 'absent') {
+                // Reuse the durable downstream key: a paused original worker still cannot cause a second effect.
+                await options.policy.withCurrent(input.principal, input.scopes, async () => { });
+                const attempted = await externalResult(() => effect.execute({ key: selected.key, operation: selected.operation }));
+                if (!attempted.ok)
+                    return { kind: 'pending', retryAfter: 1 };
+                resolved = { kind: 'completed', result: attempted.value };
+            }
+            const result = resolved.result;
+            return gate(input, async (record) => {
+                return complete(record, result, input);
+            });
+        },
+        /** Drop protected result bodies only after retention; retain the action fence and never re-execute it. */
+        prune(operationId) {
+            return options.store.transaction(operationId, async (slot) => {
+                const record = slot.record;
+                if (record?.version !== undefined && record.version !== 1)
+                    throw new Error('unsupported business operation version');
+                if (record?.execution?.phase === 'completed' && record.execution.retainUntil < now()) {
+                    delete record.execution.result;
+                    record.revisions = {};
+                }
+            });
+        },
+    };
+}
+export function operationApiResponse(outcome, success = result => Response.json(result)) {
+    return outcome.kind === 'approval_required' ? operationRequiredResponse(outcome.operation) : outcome.kind === 'pending' ? operationPendingResponse(outcome.retryAfter) : success(outcome.result);
+}
+/** A tool's missing extension is an ordinary tool error, not an OAuth refusal of the whole MCP client. */
+export function operationMcpResponse(outcome) {
+    if (outcome instanceof BusinessOperationError)
+        return Response.json({ isError: true, content: [{ type: 'text', text: 'This tool requires user approval through Operations v2.' }] });
+    return outcome.kind === 'pending' ? operationPendingResponse(outcome.retryAfter) : Response.json(outcome.kind === 'approval_required' ? operationToolError(outcome.operation) : outcome.result);
+}

package/dist/postgres.d.ts

@@ -1,3 +1,6 @@
+import type { BusinessOperationStore } from './operations.js';
+import type { BrowserCookieStore } from './browser.js';
+import type { SessionStore } from './auth/session.js';
 import type { Pool } from 'pg';
 import type { ConversationStore } from './conversation/store.js';
 import type { IssuerStore } from './reference-auth/store.js';
@@ -24,7 +27,10 @@ export declare class PostgresCompanyDatabase {
     private put;
     private save;
     private meta;
+    businessOperations(namespace: string): BusinessOperationStore;
     conversations(namespace: string): ConversationStore;
+    browserCookies(namespace: string): BrowserCookieStore;
+    sessions(namespace: string): SessionStore;
     issuer(namespace: string): IssuerStore;
     /** Bounded maintenance; never deletes message receipts, events, grants or work intent. */
     cleanup(namespace: string, now: number, limit?: number): Promise<number>;

package/dist/postgres.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { initialConversationState } from './conversation/service.js';
 import { initialIssuerState, upgradeIssuerState } from './reference-auth/index.js';
 import { clientRevisionKey, accountRevisionKey } from './reference-auth/store.js';
@@ -40,6 +41,21 @@ export class PostgresCompanyDatabase {
         await this.put(ns, kind, 'meta', value);
         return value;
     }
+    businessOperations(namespace) {
+        return { transaction: (operationId, action) => this.run(async () => {
+                await this.db.lock(JSON.stringify([namespace, 'business_operations', operationId]));
+                const slot = { record: await this.one(namespace, 'business_operations', operationId) };
+                if (slot.record && slot.record.version !== 1)
+                    throw new Error('unsupported business operation version');
+                const result = await action(slot);
+                if (slot.record) {
+                    if (slot.record.version !== 1 || slot.record.id !== operationId)
+                        throw new TypeError('business operation binding');
+                    await this.put(namespace, 'business_operations', operationId, slot.record);
+                }
+                return structuredClone(result);
+            }) };
+    }
     conversations(namespace) {
         const load = async (selection) => {
             const state = { ...await this.meta(namespace, 'conversation_meta', () => { const { version, generation } = initialConversationState(); return { version, generation }; }), conversations: {}, bindings: {}, messages: {}, work: [] };
@@ -187,6 +203,58 @@ export class PostgresCompanyDatabase {
             })),
         };
     }
+    browserCookies(namespace) {
+        const lock = (hash) => this.db.lock(JSON.stringify([namespace, 'browser_join', hash]));
+        return {
+            put: (hash, binding) => this.run(() => this.put(namespace, 'browser_cookies', hash, binding)),
+            get: hash => this.run(async () => await this.one(namespace, 'browser_cookies', hash) ?? null),
+            remove: hash => this.run(async () => { await this.sqlRun('DELETE FROM poppy_server.records WHERE ns=$1 AND kind=$2 AND id=$3', [namespace, 'browser_cookies', hash]); }),
+            putJoin: (hash, binding) => this.run(async () => { await lock(hash); await this.put(namespace, 'browser_joins', hash, binding); }),
+            authorizeJoin: (hash, principal, at) => this.run(async () => {
+                await lock(hash);
+                const row = await this.one(namespace, 'browser_joins', hash);
+                if (!row || row.expiresAt <= at || row.principal)
+                    return false;
+                row.principal = structuredClone(principal);
+                await this.put(namespace, 'browser_joins', hash, row);
+                return true;
+            }),
+            consumeJoin: hash => this.run(async () => {
+                await lock(hash);
+                const row = await this.one(namespace, 'browser_joins', hash);
+                if (row)
+                    await this.sqlRun('DELETE FROM poppy_server.records WHERE ns=$1 AND kind=$2 AND id=$3', [namespace, 'browser_joins', hash]);
+                return row ?? null;
+            }),
+        };
+    }
+    sessions(namespace) {
+        const load = async (clientId, sid) => {
+            await this.db.lock(JSON.stringify([namespace, 'resource_session_client', clientId]));
+            await this.db.lock(JSON.stringify([namespace, 'resource_session', clientId, sid]));
+            const meta = await this.meta(namespace, 'session_meta', () => ({ version: 1, generation: randomUUID() }));
+            if (meta.version !== 1)
+                throw new Error('unsupported Session state version');
+            return { ...meta, record: await this.one(namespace, 'resource_sessions', JSON.stringify([clientId, sid])) ?? null };
+        };
+        return {
+            read: (clientId, sid) => this.run(() => load(clientId, sid)),
+            transaction: (clientId, sid, at, change) => this.run(async () => this.atomic(async () => {
+                if (!Number.isFinite(at))
+                    throw new TypeError('Session clock');
+                const snapshot = await load(clientId, sid);
+                const counts = (await this.sqlGet("SELECT count(*) AS n,min((body::jsonb->>'expiresAt')::double precision) AS expiry FROM poppy_server.records WHERE ns=$1 AND kind='resource_sessions' AND body::jsonb->>'clientId'=$2 AND body::jsonb->>'ended'='false' AND (body::jsonb->>'expiresAt')::double precision>$3", [namespace, clientId, at]));
+                const state = { ...snapshot, activeCount: Number(counts.n), earliestExpiry: counts.expiry === null ? null : Number(counts.expiry) }, generation = state.generation, result = change(state);
+                if (result && typeof result.then === 'function')
+                    throw new TypeError('async Session transaction');
+                if (state.version !== 1 || state.generation !== generation || (state.record && (state.record.clientId !== clientId || state.record.sid !== sid)))
+                    throw new TypeError('Session state binding');
+                if (state.record)
+                    await this.put(namespace, 'resource_sessions', JSON.stringify([clientId, sid]), state.record);
+                return structuredClone(result);
+            })),
+        };
+    }
     issuer(namespace) {
         const kinds = ['sessions', 'sessionKeys', 'grants', 'refreshTokens', 'authorizations', 'codes', 'signIns', 'accessTokens', 'replay'];
         const load = async (selection) => {
@@ -203,7 +271,7 @@ export class PostgresCompanyDatabase {
                 for (const row of await this.rows(namespace, kind, where, params))
                     state[kind][row.id] = JSON.parse(row.body);
             };
-            if (state.version === 3) {
+            if (state.version === 3 || state.version === 4) {
                 for (const kind of kinds)
                     await find(kind, '');
                 const before = structuredClone(state);
@@ -214,7 +282,7 @@ export class PostgresCompanyDatabase {
                 for (const kind of kinds)
                     state[kind] = {};
             }
-            if (state.version !== 4)
+            if (state.version !== 5)
                 throw new Error('unsupported issuer state version');
             if ((selection.kind === 'token' || selection.kind === 'sign_in') && selection.sessionKey) {
                 await get('sessionKeys', selection.sessionKey);
@@ -229,7 +297,7 @@ export class PostgresCompanyDatabase {
                 await get('accessTokens', selection.accessHash);
                 for (const key of selection.replayKeys)
                     await get('replay', key);
-                const counts = (await this.sqlGet("SELECT count(*) AS n, sum(CASE WHEN (body::jsonb#>>'{clientId}')=$1 THEN 1 ELSE 0 END) AS client FROM poppy_server.records WHERE ns=$2 AND kind='signIns' AND (body::jsonb#>>'{status}') IN ('pending','approved','verifying') AND ((body::jsonb#>>'{expiresAt}')::double precision)>$3", [selection.clientId ?? '', namespace, selection.at]));
+                const counts = (await this.sqlGet("SELECT count(*) AS n, sum(CASE WHEN (body::jsonb#>>'{clientId}')=$1 THEN 1 ELSE 0 END) AS client FROM poppy_server.records WHERE ns=$2 AND kind='signIns' AND (body::jsonb#>>'{status}') IN ('pending','approved','verifying') AND ((body::jsonb#>>'{status}')='verifying' OR ((body::jsonb#>>'{expiresAt}')::double precision)>$3)", [selection.clientId ?? '', namespace, selection.at]));
                 state.limits = { sessions: 0, earliestSessionExpiry: 0, pending: Number(counts.n), pendingForClient: Number(counts.client ?? 0) };
             }
             if (selection.kind === 'principal') {
@@ -312,7 +380,7 @@ export class PostgresCompanyDatabase {
         return this.run(async () => {
             await this.db.lock(JSON.stringify([namespace, 'issuer']));
             const rows = await this.sqlAll(`SELECT kind,id FROM poppy_server.records AS retained WHERE ns=$1 AND
-        ((kind IN ('authorizations','codes','accessTokens') AND ((body::jsonb#>>'{expiresAt}')::double precision)<=$2) OR (kind='signIns' AND ((body::jsonb#>>'{expiresAt}')::double precision)+30000<$3) OR (kind='replay' AND (body::jsonb#>>'{}')::double precision<$4)
+        ((kind IN ('authorizations','codes','accessTokens','browser_cookies','browser_joins','resource_sessions') AND ((body::jsonb#>>'{expiresAt}')::double precision)<=$2) OR (kind='signIns' AND coalesce(body::jsonb->>'status','')!='verifying' AND ((body::jsonb#>>'{expiresAt}')::double precision)+30000<$3) OR (kind='replay' AND (body::jsonb#>>'{}')::double precision<$4)
         OR (kind='refreshTokens' AND NOT EXISTS (SELECT 1 FROM poppy_server.records AS lineage WHERE lineage.ns=retained.ns AND lineage.kind='grants' AND lineage.id=retained.body::jsonb#>>'{}' AND (lineage.body::jsonb->>'expiresAt')::double precision>$5 AND lineage.body::jsonb->>'revoked'='false'))) LIMIT $6`, [namespace, now, now, now, now, limit]);
             for (const row of rows)
                 await this.sqlRun("DELETE FROM poppy_server.records WHERE ns=$1 AND kind=$2 AND id=$3", [namespace, row.kind, row.id]);

package/dist/protocol/operations.d.ts

@@ -0,0 +1,51 @@
+import type { JsonObject } from './wire.js';
+export interface BusinessOperation {
+    operation_id: string;
+    revision: string;
+    summary: string;
+    terms?: JsonObject;
+    expires_at: string;
+    [key: string]: unknown;
+}
+export interface OperationApproval {
+    operation_id: string;
+    revision: string;
+    [key: string]: unknown;
+}
+export declare const operationsV2: {
+    readonly version: "2";
+};
+export declare function supportsOperations(document: {
+    extensions?: unknown;
+}): boolean;
+export declare function parseBusinessOperation(value: unknown): BusinessOperation;
+/** RFC3339 permits a leap second; JavaScript Date.parse does not. */
+export declare function operationExpiry(value: string): number;
+export declare function parseOperationApproval(value: unknown): OperationApproval;
+export declare function parseApprovalHeader(value: string | null): OperationApproval | undefined;
+export declare function approvalHeader(value: OperationApproval): string;
+export declare const approvalMetaKey = "personalagentprotocol.org/approval";
+export declare function mcpApproval(params: unknown): OperationApproval | undefined;
+export type OperationRequest = {
+    channel: 'api';
+    method: string;
+    url: string;
+    body: string | null;
+} | {
+    channel: 'mcp';
+    url: string;
+    name: string;
+    arguments: JsonObject;
+} | {
+    channel: 'conversation';
+    endpoint: string;
+    conversationId: string;
+};
+export declare function operationRequest(value: OperationRequest): OperationRequest;
+export declare function requestFingerprint(value: OperationRequest): string;
+export declare function operationRequiredResponse(operation: BusinessOperation): Response;
+export declare function operationToolError(operation: BusinessOperation): JsonObject;
+/** Base64 preserves exact API body bytes. Bind the complete URL, including its query. */
+export declare function captureApiOperationRequest(request: Request): Promise<Extract<OperationRequest, {
+    channel: 'api';
+}>>;

package/dist/protocol/operations.js

@@ -0,0 +1,98 @@
+import { parse, serialize, getMember } from '@agentsig/structured-fields';
+import { canonical, id, object, string, ValidationError } from './wire.js';
+import { secureUrl } from '../network/transport.js';
+export const operationsV2 = { version: '2' };
+export function supportsOperations(document) {
+    const extensions = document.extensions;
+    return !!extensions && typeof extensions === 'object' && !Array.isArray(extensions)
+        && extensions.operations?.version === '2';
+}
+export function parseBusinessOperation(value) {
+    const operation = object(value, 'operation');
+    id(operation.operation_id, 'operation.operation_id');
+    id(operation.revision, 'operation.revision');
+    string(operation.summary, 'operation.summary');
+    if ('terms' in operation)
+        object(operation.terms, 'operation.terms');
+    const date = string(operation.expires_at, 'operation.expires_at');
+    const match = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:[Zz]|[+-](\d{2}):(\d{2}))$/.exec(date);
+    if (!match)
+        throw new ValidationError('operation.expires_at');
+    const [, y, m, d, h, min, s, oh = '0', om = '0'] = match;
+    const monthEnd = new Date(0);
+    monthEnd.setUTCFullYear(+y, +m, 0);
+    const days = monthEnd.getUTCDate();
+    if (+m < 1 || +m > 12 || +d < 1 || +d > days || +h > 23 || +min > 59 || +s > 60 || +oh > 23 || +om > 59 || !Number.isFinite(operationExpiry(date)))
+        throw new ValidationError('operation.expires_at');
+    return structuredClone(operation);
+}
+/** RFC3339 permits a leap second; JavaScript Date.parse does not. */
+export function operationExpiry(value) {
+    return /:60(?:\.\d+)?(?:[Zz]|[+-]\d{2}:\d{2})$/.test(value)
+        ? Date.parse(value.replace(/:60(?=\.\d+|[Zz]|[+-])/, ':59')) + 1000 : Date.parse(value);
+}
+export function parseOperationApproval(value) {
+    const approval = object(value, 'approval');
+    id(approval.operation_id, 'approval.operation_id');
+    id(approval.revision, 'approval.revision');
+    return { ...approval };
+}
+export function parseApprovalHeader(value) {
+    if (value === null)
+        return;
+    try {
+        const dictionary = parse(value, 'dictionary');
+        const text = (name) => { const member = getMember(dictionary, name); return member?.kind === 'item' && member.bare.kind === 'string' ? member.bare.value : undefined; };
+        return parseOperationApproval({ operation_id: text('operation_id'), revision: text('revision') });
+    }
+    catch {
+        return;
+    } // Invalid Structured Fields are ignored as a whole (RFC 9651 section 2.2).
+}
+export function approvalHeader(value) {
+    const approval = parseOperationApproval(value);
+    return serialize({ kind: 'dictionary', entries: [
+            ['operation_id', { kind: 'item', bare: { kind: 'string', value: approval.operation_id }, parameters: [] }],
+            ['revision', { kind: 'item', bare: { kind: 'string', value: approval.revision }, parameters: [] }],
+        ] });
+}
+export const approvalMetaKey = 'personalagentprotocol.org/approval';
+export function mcpApproval(params) {
+    const meta = object(params, 'params')._meta;
+    if (meta === undefined)
+        return;
+    const value = object(meta, '_meta')[approvalMetaKey];
+    return value === undefined ? undefined : parseOperationApproval(value);
+}
+export function operationRequest(value) {
+    object(value, 'operation.request');
+    if (value.channel === 'api') {
+        secureUrl(value.url);
+        if (!/^[A-Z]+$/.test(value.method) || !(value.body === null || typeof value.body === 'string'))
+            throw new ValidationError('operation.request');
+    }
+    else if (value.channel === 'mcp') {
+        secureUrl(value.url);
+        string(value.name, 'tool.name');
+        object(value.arguments, 'tool.arguments');
+    }
+    else if (value.channel === 'conversation') {
+        secureUrl(value.endpoint);
+        id(value.conversationId, 'conversation_id');
+    }
+    else
+        throw new ValidationError('operation.channel');
+    return structuredClone(value);
+}
+export function requestFingerprint(value) { return canonical(operationRequest(value)); }
+export function operationRequiredResponse(operation) {
+    return Response.json({ error: 'approval_required', operation: parseBusinessOperation(operation) }, { status: 403, headers: { 'Cache-Control': 'no-store' } });
+}
+export function operationToolError(operation) {
+    const parsed = parseBusinessOperation(operation);
+    return { isError: true, content: [{ type: 'text', text: parsed.summary }], structuredContent: { operation: parsed } };
+}
+/** Base64 preserves exact API body bytes. Bind the complete URL, including its query. */
+export async function captureApiOperationRequest(request) {
+    return { channel: 'api', method: request.method, url: request.url, body: request.body === null ? null : Buffer.from(await request.clone().arrayBuffer()).toString('base64') };
+}

package/dist/protocol/session.d.ts

@@ -0,0 +1,28 @@
+import type { MetadataResolver } from '../network/discovery.js';
+export interface SessionClaims {
+    iss: string;
+    aud: string;
+    sid: string;
+    sub: string;
+    agent_id?: string;
+    htm: string;
+    htu: string;
+    iat: number;
+    jti: string;
+    ath?: string;
+}
+export interface VerifiedSession extends SessionClaims {
+    delegationExpiresAt: number;
+}
+export declare function sessionRequestUrl(value: string): string;
+export declare function parseSessionClaims(value: unknown): SessionClaims;
+/** Verifies identity only. The resource must separately admit/continue the client_id + sid under its store fence. */
+export declare function verifySessionJwt(jwt: string | null, expected: {
+    companyId: string;
+    method: string;
+    url: string;
+    nowMs: number;
+    metadata: MetadataResolver;
+    accessToken?: string;
+    tokenClientId?: string;
+}): Promise<VerifiedSession>;