@poppykit/server 0.4.0 → 0.5.0

package/dist/sqlite.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 { ConversationStore } from './conversation/store.js';
 import type { IssuerStore } from './reference-auth/store.js';
 /** Share this instance between issuer and conversations so authorization and mutation commit together. */
@@ -20,7 +23,15 @@ export declare class SqliteCompanyDatabase {
     private put;
     private save;
     private meta;
+    businessOperations(namespace: string): BusinessOperationStore;
+    /** Same-database business effects only. The callback and operation receipt share the outer transaction. */
+    withTransaction<T>(action: (connection: {
+        run(sql: string, values?: (string | number | null)[]): void;
+        get(sql: string, values?: (string | number | null)[]): Record<string, unknown> | undefined;
+    }) => Promise<T>): Promise<T>;
     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/sqlite.js

@@ -1,3 +1,4 @@
+import { randomUUID } from 'node:crypto';
 import { DatabaseSync } from 'node:sqlite';
 import { initializeSqlite } from './sqlite-init.js';
 import { AsyncLocalStorage } from 'node:async_hooks';
@@ -117,6 +118,39 @@ export class SqliteCompanyDatabase {
         this.put(ns, kind, 'meta', value);
         return value;
     }
+    businessOperations(namespace) {
+        return { transaction: (operationId, action) => this.run(async () => {
+                const name = 'operation_' + ++this.savepoint;
+                this.db.exec('SAVEPOINT ' + name);
+                try {
+                    const slot = { record: 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');
+                        this.put(namespace, 'business_operations', operationId, slot.record);
+                    }
+                    this.db.exec('RELEASE ' + name);
+                    return structuredClone(result);
+                }
+                catch (error) {
+                    this.db.exec('ROLLBACK TO ' + name);
+                    this.db.exec('RELEASE ' + name);
+                    throw error;
+                }
+            }) };
+    }
+    /** Same-database business effects only. The callback and operation receipt share the outer transaction. */
+    withTransaction(action) {
+        return this.run(async () => {
+            const context = this.inside.getStore();
+            const check = () => { if (!context.active || this.inside.getStore() !== context)
+                throw new Error('expired SQLite transaction'); };
+            return action({ run: (sql, values = []) => { check(); this.db.prepare(sql).run(...values); }, get: (sql, values = []) => { check(); return this.db.prepare(sql).get(...values); } });
+        });
+    }
     conversations(namespace) {
         const load = (selection) => {
             const state = { ...this.meta(namespace, 'conversation_meta', () => { const { version, generation } = initialConversationState(); return { version, generation }; }), conversations: {}, bindings: {}, messages: {}, work: [] };
@@ -255,6 +289,52 @@ export class SqliteCompanyDatabase {
             })),
         };
     }
+    browserCookies(namespace) {
+        return {
+            put: (hash, binding) => this.run(async () => { this.put(namespace, 'browser_cookies', hash, binding); }),
+            get: hash => this.run(async () => this.one(namespace, 'browser_cookies', hash) ?? null),
+            remove: hash => this.run(async () => { this.db.prepare('DELETE FROM records WHERE ns=? AND kind=? AND id=?').run(namespace, 'browser_cookies', hash); }),
+            putJoin: (hash, binding) => this.run(async () => { this.put(namespace, 'browser_joins', hash, binding); }),
+            authorizeJoin: (hash, principal, at) => this.run(async () => {
+                const row = this.one(namespace, 'browser_joins', hash);
+                if (!row || row.expiresAt <= at || row.principal)
+                    return false;
+                row.principal = structuredClone(principal);
+                this.put(namespace, 'browser_joins', hash, row);
+                return true;
+            }),
+            consumeJoin: hash => this.run(async () => {
+                const row = this.one(namespace, 'browser_joins', hash);
+                if (row)
+                    this.db.prepare('DELETE FROM records WHERE ns=? AND kind=? AND id=?').run(namespace, 'browser_joins', hash);
+                return row ?? null;
+            }),
+        };
+    }
+    sessions(namespace) {
+        const load = (clientId, sid) => {
+            const meta = this.meta(namespace, 'session_meta', () => ({ version: 1, generation: randomUUID() }));
+            if (meta.version !== 1)
+                throw new Error('unsupported Session state version');
+            return { ...meta, record: this.one(namespace, 'resource_sessions', JSON.stringify([clientId, sid])) ?? null };
+        };
+        return {
+            read: (clientId, sid) => this.run(async () => load(clientId, sid)),
+            transaction: (clientId, sid, at, change) => this.run(async () => this.atomic(() => {
+                if (!Number.isFinite(at))
+                    throw new TypeError('Session clock');
+                const counts = this.db.prepare("SELECT count(*) AS n,min(json_extract(body,'$.expiresAt')) AS expiry FROM records WHERE ns=? AND kind='resource_sessions' AND json_extract(body,'$.clientId')=? AND json_extract(body,'$.ended')=0 AND json_extract(body,'$.expiresAt')>?").get(namespace, clientId, at);
+                const state = { ...load(clientId, sid), 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)
+                    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 = (selection) => {
@@ -270,7 +350,7 @@ export class SqliteCompanyDatabase {
                 for (const row of 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)
                     find(kind, '');
                 const before = structuredClone(state);
@@ -281,7 +361,7 @@ export class SqliteCompanyDatabase {
                 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) {
                 get('sessionKeys', selection.sessionKey);
@@ -296,7 +376,7 @@ export class SqliteCompanyDatabase {
                 get('accessTokens', selection.accessHash);
                 for (const key of selection.replayKeys)
                     get('replay', key);
-                const counts = this.db.prepare("SELECT count(*) AS n, sum(CASE WHEN json_extract(body,'$.clientId')=? THEN 1 ELSE 0 END) AS client FROM records WHERE ns=? AND kind='signIns' AND json_extract(body,'$.status') IN ('pending','approved','verifying') AND json_extract(body,'$.expiresAt')>?").get(selection.clientId ?? '', namespace, selection.at);
+                const counts = this.db.prepare("SELECT count(*) AS n, sum(CASE WHEN json_extract(body,'$.clientId')=? THEN 1 ELSE 0 END) AS client FROM records WHERE ns=? AND kind='signIns' AND json_extract(body,'$.status') IN ('pending','approved','verifying') AND (json_extract(body,'$.status')='verifying' OR json_extract(body,'$.expiresAt')>?)").get(selection.clientId ?? '', namespace, selection.at);
                 state.limits = { sessions: 0, earliestSessionExpiry: 0, pending: Number(counts.n), pendingForClient: Number(counts.client ?? 0) };
             }
             if (selection.kind === 'principal') {
@@ -378,7 +458,7 @@ export class SqliteCompanyDatabase {
             throw new TypeError('cleanup limit');
         return this.run(async () => {
             const rows = this.db.prepare(`SELECT kind,id FROM records AS retained WHERE ns=? AND
-        ((kind IN ('authorizations','codes','accessTokens') AND json_extract(body,'$.expiresAt')<=?) OR (kind='signIns' AND json_extract(body,'$.expiresAt')+30000<?) OR (kind='replay' AND CAST(body AS REAL)<?)
+        ((kind IN ('authorizations','codes','accessTokens','browser_cookies','browser_joins','resource_sessions') AND json_extract(body,'$.expiresAt')<=?) OR (kind='signIns' AND coalesce(json_extract(body,'$.status'),'')!='verifying' AND json_extract(body,'$.expiresAt')+30000<?) OR (kind='replay' AND CAST(body AS REAL)<?)
         OR (kind='refreshTokens' AND NOT EXISTS (SELECT 1 FROM records AS lineage WHERE lineage.ns=retained.ns AND lineage.kind='grants' AND lineage.id=json_extract(retained.body,'$') AND json_extract(lineage.body,'$.expiresAt')>? AND json_extract(lineage.body,'$.revoked')=0))) LIMIT ?`).all(namespace, now, now, now, now, limit);
             for (const row of rows)
                 this.db.prepare('DELETE FROM records WHERE ns=? AND kind=? AND id=?').run(namespace, row.kind, row.id);

package/examples/operations.mjs

@@ -0,0 +1,18 @@
+// Local synthetic acceptance only. Production uses createRequestAuthenticator and sessions.policy.
+import assert from 'node:assert/strict';
+import {mkdtemp,rm} from 'node:fs/promises';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {createBusinessOperations,operationApiResponse} from '../dist/index.js';
+import {SqliteCompanyDatabase} from '../dist/sqlite.js';
+const dir=await mkdtemp(join(tmpdir(),'poppy-company-operation-')),db=new SqliteCompanyDatabase(join(dir,'company.db'));
+try{
+  const principal={issuer:'https://example.com',clientId:'https://agent.example/client',userId:'synthetic',sessionId:'sid',sessionInstanceId:'instance',sessionGeneration:'generation',sessionVersion:1,tokenExpiresAt:Date.now()+900000,scopes:[]};
+  const operations=createBusinessOperations({companyId:principal.issuer,store:db.businessOperations(principal.issuer),metadata:{resolveClient:async()=>({extensions:{operations:{version:'2'}}})},policy:{withCurrent:(_principal,_scopes,action)=>db.run(action)}});
+  let effects=0;const input={operationId:'exchange_one',principal,scopes:[],request:{channel:'api',method:'POST',url:'https://example.com/orders/one/exchange',body:Buffer.from('{"sku":"blue"}').toString('base64')},proposal:()=>({summary:'Exchange order one for the blue jacket for $70.',terms:{order_id:'one',sku:'blue',amount:'70.00'},expires_at:new Date(Date.now()+900000).toISOString()})};
+  const required=await operations.local(input,async()=>{effects++;return {done:true};});assert.equal(required.kind,'approval_required');assert.equal(effects,0);assert.equal(operationApiResponse(required).status,403);
+  // This is an independent synthetic wire fixture, never a real consent mechanism.
+  const approval={operation_id:required.operation.operation_id,revision:required.operation.revision};
+  const result=await operations.local({...input,approval},async revision=>db.withTransaction(async tx=>{tx.run('INSERT INTO records VALUES (?,?,?,?)',['example','business','exchange_one',JSON.stringify(revision.terms)]);return {done:true};}));
+  assert.equal(result.kind,'completed');assert.deepEqual((await operations.local({...input,approval},async()=>{throw Error('duplicate effect');})).result,{done:true});console.log('synthetic operation committed and replayed');
+}finally{db.close();await rm(dir,{recursive:true,force:true});}

package/examples/quickstart.mjs

@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { createRequestAuthenticator, createConversationService } from '@poppykit/server';
+import { createRequestAuthenticator, createConversationService, createSessionAuthority } from '@poppykit/server';
 import { createMetadataResolver, createNodeTransport, createReferenceIssuer } from '@poppykit/server/reference-auth';
 import { SqliteCompanyDatabase } from '@poppykit/server/sqlite';
 
@@ -8,21 +8,24 @@ const transport = createNodeTransport();
 try {
   const issuer = 'https://company.example/issuer';
   const endpoint = 'https://company.example/conversations';
+  const metadata = createMetadataResolver(transport);
   const auth = createReferenceIssuer({
     issuer, tokenEndpoint: issuer + '/token', revocationEndpoint: issuer + '/revoke',
     protectedResources: ['https://company.example'], supportedScopes: [], resources: [endpoint],
-    metadata: createMetadataResolver(transport), store: database.issuer(issuer),
+    metadata, store: database.issuer(issuer),
     coordinator: database, now: Date.now,
   });
+  const sessions = createSessionAuthority({companyId:issuer,metadata,store:database.sessions(issuer),
+    coordinator:database,accountPolicy:auth.authority.policy,now:Date.now});
   const conversations = createConversationService({
     historyScopes: ['orders:read'],
-    endpoint, store: database.conversations(issuer), policy: auth.authority.policy,
-    authenticator: createRequestAuthenticator({ authority: auth.authority,
+    endpoint, store: database.conversations(issuer), policy: sessions.policy,
+    authenticator: createRequestAuthenticator({ sessions, authority: auth.authority,
       endpoints: [{ origin: 'https://company.example', pathPrefix: '/conversations', resource: endpoint }],
       now: Date.now }), clock: { now: Date.now },
   });
   // Your HTTPS framework routes trusted public Requests to this handler.
-  assert.equal((await conversations.handle(new Request(endpoint, {method:'POST', headers:{'content-type':'application/json'}, body:'{}'}))).status, 401);
+  assert.equal((await conversations.handle(new Request(endpoint, {method:'POST', headers:{'content-type':'application/json'}, body:'{}'}))).status, 400);
   console.log('Reference issuer and conversation service configured; anonymous request rejected.');
 } finally {
   transport.close?.();

package/migrations/RETIREMENT.md

@@ -0,0 +1,77 @@
+# Explicit retirement of legacy issuer rows
+
+This is an operator-run record migration, separate from the automatic v3/v4 → v5
+record enrichment. It is not called by constructors, requests, cleanup(), or SQL
+schema installation. No existing SQL migration is rewritten. No live data has
+been migrated or deleted by preparing this plan.
+
+Stop every old and new writer, back up the database and its matching protected
+cipher/vault keys, and rehearse on a disposable copy. Select one exact namespace.
+Complete the v5 enrichment first: it backfills access-token client/account identity
+only from proven associations. Unknown/conflicting associations require manual
+reconciliation. Do not guess them from a key, User ID, or a shared host.
+
+Take an exclusive write transaction: BEGIN IMMEDIATE for SQLite; BEGIN followed
+by LOCK TABLE poppy_server.records IN EXCLUSIVE MODE for PostgreSQL. Keep the
+transaction through selection, validation and deletion. Confirm the selected
+issuer_meta record is version 5. Abort on another version or unresolved work.
+
+## Prepare the deletion list
+
+Use the existing bounded cleanup for expired access tokens, codes, authorizations,
+browser cookies/join codes and replay records first. Preserve mediated verifying
+records, active refresh-token ancestry, encrypted callback delivery references,
+grants, conversations, work, receipts and events. A timeout is not proof of failure.
+
+Then inspect legacy sessions/sessionKeys with these rules, in this order:
+
+1. A key mapping must be a JSON string pointing to an absent or expired legacy
+   Session. Retain it if any record in the namespace refers to its key through
+   sessionKey or jkt, or to its target through sessionId, principal.sessionId or
+   authority.principal.sessionId. This includes pending/uncertain sign-ins,
+   authorization/code records, browser snapshots and accepted conversation/work
+   authority. Retain malformed or conflicting mappings for reconciliation.
+2. After deleting only approved, unreferenced mappings, consider an expired legacy
+   Session. Retain it while any mapping points to it or any record has one of the
+   Session references above. An active Session is never a candidate. Current
+   resource_sessions are a different record kind and are excluded.
+3. Do not delete grants or live refreshTokens as part of Session retirement. The
+   ordinary refresh-token expiry/revocation cleanup has its own lineage checks.
+
+The cross-reference scan is deliberately conservative: even completed history can
+retain a reference. Its removal requires a separate, explicit retention decision.
+Never remove a reference merely to make its target eligible for deletion.
+
+For SQLite, read references with json_extract(body,'$.sessionKey'), '$.jkt',
+'$.sessionId', '$.principal.sessionId' and '$.authority.principal.sessionId'.
+Read mapping targets with json_extract(body,'$'), checking json_type(body)='text'.
+For PostgreSQL use body::jsonb->>'sessionKey', body::jsonb->>'jkt',
+body::jsonb->>'sessionId', body::jsonb#>>'{principal,sessionId}' and
+body::jsonb#>>'{authority,principal,sessionId}'; mapping targets use
+body::jsonb#>>'{}' with jsonb_typeof(body::jsonb)='string'. Every lookup includes ns.
+
+## Apply only the reviewed list
+
+Record the approved kind, id and exact original body privately. Recheck all
+references under the same write lock immediately before each removal. Use bound
+parameters and compare the original body, for example:
+
+```sql
+-- SQLite, inside the exclusive transaction and only after the checks above:
+DELETE FROM records WHERE ns=?1 AND kind=?2 AND id=?3 AND body=?4;
+-- PostgreSQL, inside the locked transaction:
+DELETE FROM poppy_server.records WHERE ns=$1 AND kind=$2 AND id=$3 AND body=$4;
+```
+
+Allow only kind=sessionKeys first, then kind=sessions; require exactly one affected
+row for each approved removal. Abort and roll back if a body, reference, version
+or count differs. Work in bounded batches of at most 1000 records. Verify that
+credential, pending/uncertain, recovery and conversation records are unchanged
+before committing. Restart only compatible writers. Keep the backup until the
+production migration has independent acceptance; do not downgrade old writers
+onto the enriched records.
+
+The SDK's existing migration tests prove record preservation across SQLite and
+PostgreSQL. Execution of this optional retirement plan, and deployment-specific
+retention choices, need the operator's disposable rehearsal and later production
+authorization. Automatic legacy-row deletion was intentionally not added.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poppykit/server",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "private": false,
   "description": "Personal Agent Protocol company SDK",
   "repository": {
@@ -42,7 +42,9 @@
     "RELEASING.md",
     "examples",
     "LICENSE",
-    "migrations"
+    "migrations",
+    "CONFORMANCE.md",
+    "OPERATIONS.md"
   ],
   "exports": {
     ".": {
@@ -67,6 +69,7 @@
     }
   },
   "dependencies": {
+    "@agentsig/structured-fields": "0.1.1",
     "jose": "6.2.12"
   },
   "license": "MIT",