@poppykit/client 0.0.0-stage → 0.1.0

package/dist/auth/ownership.d.ts

@@ -0,0 +1,9 @@
+export interface OperationOwner {
+    host: string;
+    pid: number;
+    id: string;
+}
+export declare function acquireOwner(): OperationOwner;
+export declare function releaseOwner(owner: OperationOwner): void;
+/** Unknown remote owners and permission failures are conservatively live. */
+export declare function localOwnerAlive(owner: OperationOwner): boolean;

package/dist/auth/ownership.js

@@ -0,0 +1,23 @@
+import { randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+const active = new Set();
+export function acquireOwner() {
+    const owner = { host: hostname(), pid: process.pid, id: randomUUID() };
+    active.add(owner.id);
+    return owner;
+}
+export function releaseOwner(owner) { active.delete(owner.id); }
+/** Unknown remote owners and permission failures are conservatively live. */
+export function localOwnerAlive(owner) {
+    if (owner.host !== hostname())
+        return true;
+    if (owner.pid === process.pid)
+        return active.has(owner.id);
+    try {
+        process.kill(owner.pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code !== 'ESRCH';
+    }
+}

package/dist/auth/sqlite-store.d.ts

@@ -0,0 +1,14 @@
+import type { ClientAuthState } from './client-auth.js';
+import type { AuthSelection, AuthStore } from './store.js';
+/** One database per local auth namespace/user/client. References only: secrets belong in SecretStore. */
+export declare class SqliteAuthStore implements AuthStore {
+    private readonly db;
+    constructor(path: string);
+    close(): void;
+    pendingOperations(after: string | undefined, limit: number): Promise<string[]>;
+    /** Explicit bounded history cleanup; uncertain outcomes and pending operations always remain. */
+    cleanup(before: number, limit?: number): Promise<number>;
+    private select;
+    read(selection: AuthSelection): Promise<ClientAuthState>;
+    transaction<T>(selection: AuthSelection, change: (draft: ClientAuthState) => T): Promise<T>;
+}

package/dist/auth/sqlite-store.js

@@ -0,0 +1,123 @@
+import { DatabaseSync } from 'node:sqlite';
+import { initializeSqlite } from '../sqlite-init.js';
+import { initialClientAuthState } from './client-auth.js';
+const tables = ['identities', 'connections', 'grants', 'operations', 'cleanup'];
+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 auth record');
+        return item;
+    });
+}
+/** One database per local auth namespace/user/client. References only: secrets belong in SecretStore. */
+export class SqliteAuthStore {
+    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;');
+            this.db.exec('CREATE TABLE IF NOT EXISTS auth_meta (id INTEGER PRIMARY KEY CHECK(id=1), body TEXT NOT NULL)');
+            for (const table of tables)
+                this.db.exec(`CREATE TABLE IF NOT EXISTS auth_${table} (id TEXT PRIMARY KEY, body TEXT NOT NULL)`);
+            this.db.exec(`CREATE INDEX IF NOT EXISTS operations_connection ON auth_operations(json_extract(body,'$.connectionId'));
+      CREATE UNIQUE INDEX IF NOT EXISTS operations_callback ON auth_operations(json_extract(body,'$.direct.stateHash'));
+      CREATE INDEX IF NOT EXISTS operations_pending ON auth_operations(id) WHERE json_extract(body,'$.phase')!='terminal';
+      CREATE INDEX IF NOT EXISTS operations_cleanup ON auth_operations(json_extract(body,'$.createdAt')) WHERE json_extract(body,'$.phase')='terminal' AND json_extract(body,'$.status')!='uncertain';
+      CREATE INDEX IF NOT EXISTS cleanup_connection ON auth_cleanup(json_extract(body,'$.connectionId'));`);
+            const { version, epoch, owner } = initialClientAuthState();
+            this.db.prepare('INSERT OR IGNORE INTO auth_meta VALUES (1,?)').run(json({ version, epoch, owner }));
+        });
+    }
+    close() { this.db.close(); }
+    async pendingOperations(after, limit) {
+        if (!Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new TypeError('recovery limit');
+        return this.db.prepare("SELECT id FROM auth_operations WHERE json_extract(body,'$.phase')!='terminal' AND id>? ORDER BY id LIMIT ?").all(after ?? '', limit).map(row => row.id);
+    }
+    /** Explicit bounded history cleanup; uncertain outcomes and pending operations always remain. */
+    async cleanup(before, limit = 100) {
+        if (!Number.isFinite(before) || !Number.isSafeInteger(limit) || limit < 1 || limit > 1000)
+            throw new TypeError('cleanup limit');
+        return Number(this.db.prepare("DELETE FROM auth_operations WHERE id IN (SELECT id FROM auth_operations WHERE json_extract(body,'$.phase')='terminal' AND json_extract(body,'$.status')!='uncertain' AND json_extract(body,'$.createdAt')<? ORDER BY json_extract(body,'$.createdAt') LIMIT ?)").run(before, limit).changes);
+    }
+    select(selection) {
+        const state = { ...JSON.parse(this.db.prepare('SELECT body FROM auth_meta WHERE id=1').get().body), identities: {}, connections: {}, grants: {}, operations: {}, cleanup: {} };
+        const get = (table, id) => {
+            const row = this.db.prepare(`SELECT body FROM auth_${table} WHERE id=?`).get(id);
+            if (row)
+                state[table][id] = JSON.parse(row.body);
+        };
+        const rows = (table, clause, ...params) => {
+            for (const row of this.db.prepare(`SELECT id,body FROM auth_${table} ${clause}`).all(...params))
+                state[table][row.id] = JSON.parse(row.body);
+        };
+        if ('issuer' in selection) {
+            get('identities', selection.issuer);
+            return state;
+        }
+        if ('connectionId' in selection)
+            get('connections', selection.connectionId);
+        else if ('operationId' in selection)
+            get('operations', selection.operationId);
+        else if ('callbackHash' in selection)
+            rows('operations', "WHERE json_extract(body,'$.direct.stateHash')=?", selection.callbackHash);
+        else if ('list' in selection)
+            rows('connections', '');
+        for (const operation of Object.values(state.operations))
+            get('connections', operation.connectionId);
+        for (const connection of Object.values(state.connections)) {
+            if (connection.grantId)
+                get('grants', connection.grantId);
+            if (!('list' in selection)) {
+                rows('operations', "WHERE json_extract(body,'$.connectionId')=?", connection.id);
+                rows('cleanup', "WHERE json_extract(body,'$.connectionId')=?", connection.id);
+            }
+        }
+        for (const operation of Object.values(state.operations))
+            if (operation.grantId)
+                get('grants', operation.grantId);
+        return state;
+    }
+    async read(selection) {
+        this.db.exec('BEGIN');
+        try {
+            const state = this.select(selection);
+            this.db.exec('COMMIT');
+            return state;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+    async transaction(selection, change) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const state = this.select(selection), before = structuredClone(state);
+            const result = change(state);
+            if (result && typeof result.then === 'function')
+                throw new TypeError('async auth transaction');
+            const { version, epoch, owner } = state;
+            const metadata = json({ version, epoch, owner });
+            if (metadata !== json({ version: before.version, epoch: before.epoch, owner: before.owner }))
+                this.db.prepare('UPDATE auth_meta SET body=? WHERE id=1').run(metadata);
+            for (const table of tables) {
+                for (const id of Object.keys(before[table]))
+                    if (!Object.hasOwn(state[table], id))
+                        this.db.prepare(`DELETE FROM auth_${table} WHERE id=?`).run(id);
+                for (const [id, value] of Object.entries(state[table])) {
+                    const body = json(value);
+                    if (!Object.hasOwn(before[table], id) || body !== json(before[table][id]))
+                        this.db.prepare(`INSERT INTO auth_${table} VALUES (?,?) ON CONFLICT(id) DO UPDATE SET body=excluded.body`).run(id, body);
+                }
+            }
+            const detached = structuredClone(result);
+            this.db.exec('COMMIT');
+            return detached;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+}

package/dist/auth/store.d.ts

@@ -0,0 +1,19 @@
+import type { ClientAuthState } from './client-auth.js';
+/** A connection aggregate includes its grants, operations and cleanup; never other connections. */
+export type AuthSelection = {
+    connectionId: string;
+} | {
+    operationId: string;
+} | {
+    issuer: string;
+} | {
+    callbackHash: string;
+} | {
+    list: true;
+};
+export interface AuthStore {
+    read(selection: AuthSelection): Promise<ClientAuthState>;
+    transaction<T>(selection: AuthSelection, change: (draft: ClientAuthState) => T): Promise<T>;
+    /** Ascending IDs strictly after the cursor. Includes only nonterminal operations. */
+    pendingOperations(after: string | undefined, limit: number): Promise<string[]>;
+}

package/dist/auth/store.js

@@ -0,0 +1 @@
+export {};

package/dist/conversation-store.d.ts

@@ -0,0 +1,15 @@
+import type { ConsumerCheckpoint, OutboundRecord } from './conversation.js';
+export interface ConversationKey {
+    connectionId: string;
+    issuer: string;
+    endpoint: string;
+}
+export interface ConversationStore {
+    getOutbound(key: ConversationKey, id: string): Promise<OutboundRecord | undefined>;
+    /** Insert or return the existing record atomically; never replace its destination/content. */
+    prepareOutbound(key: ConversationKey, record: OutboundRecord): Promise<OutboundRecord>;
+    settleOutbound(key: ConversationKey, id: string, result: Pick<OutboundRecord, 'phase' | 'response' | 'error'>): Promise<void>;
+    getCheckpoint(key: ConversationKey, conversationId: string, name: string): Promise<string | undefined>;
+    advanceCheckpoint(key: ConversationKey, checkpoint: ConsumerCheckpoint, from: readonly (string | undefined)[]): Promise<void>;
+    resetCheckpoint(key: ConversationKey, conversationId: string, name: string): Promise<void>;
+}

package/dist/conversation-store.js

@@ -0,0 +1 @@
+export {};

package/dist/conversation.d.ts

@@ -0,0 +1,118 @@
+import type { AuthorizationRequirement } from './auth/client-auth.js';
+import type { ConversationEvent } from './protocol/wire.js';
+import type { ConversationStore } from './conversation-store.js';
+import type { ConversationRequest, ConversationState, EventPage, Message } from './protocol/wire.js';
+export interface OutboundRecord {
+    connectionId: string;
+    issuer: string;
+    endpoint: string;
+    id: string;
+    target: string | null;
+    request: ConversationRequest;
+    fingerprint: string;
+    phase: 'pending' | 'accepted' | 'rejected';
+    read?: ReadParams;
+    response?: ConversationState | EventPage;
+    error?: {
+        code: string;
+        status: number;
+        conversationId?: string;
+    };
+}
+export interface ReadParams {
+    wait?: number;
+    cursor?: string;
+    signal?: AbortSignal;
+}
+export interface ConsumerCheckpoint {
+    connectionId: string;
+    issuer: string;
+    conversationId: string;
+    name: string;
+    cursor: string;
+}
+export interface ConversationClientState {
+    version: 1;
+    outbound: OutboundRecord[];
+    consumers: ConsumerCheckpoint[];
+}
+export declare const initialConversationClientState: () => ConversationClientState;
+export declare class ConversationError extends Error {
+    readonly code: string;
+    readonly status?: number | undefined;
+    readonly retryAfterMs?: number | undefined;
+    readonly scope?: string | undefined;
+    readonly conversationId?: string | undefined;
+    readonly extension?: string | undefined;
+    readonly extensions: string[];
+    constructor(code: string, status?: number | undefined, retryAfterMs?: number | undefined, scope?: string | undefined, conversationId?: string | undefined, extension?: string | undefined, extensions?: string[]);
+    get requiredScopes(): string[];
+}
+export interface ConversationClientOptions {
+    authorizedRequest(request: Request): Promise<Response>;
+    endpoint: string;
+    connectionId: string;
+    issuer: string;
+    store: ConversationStore;
+    clock: {
+        now(): number;
+    };
+    newId?: () => string;
+    sleep?: (ms: number) => Promise<void>;
+    random?: () => number;
+    /** Optional safe UI hook supplied by the single authentication lifecycle. */
+    authorization?: (connectionId: string, scopes: string[]) => Promise<AuthorizationRequirement>;
+    maxAttempts?: number;
+    baseDelayMs?: number;
+    maxDelayMs?: number;
+    maxPages?: number;
+}
+export interface ReadOptions extends ReadParams {
+    consumer?: string;
+    signal?: AbortSignal;
+}
+export interface WatchOptions extends ReadOptions {
+    lastEventId?: string;
+    maxReconnects?: number;
+    onPartial?: (value: {
+        messageId: string;
+        text: string;
+    } | null) => void;
+    onHistoryGap?: () => Promise<boolean> | boolean;
+}
+export interface WatchedEvent {
+    event: ConversationEvent;
+    ack(): Promise<void>;
+}
+export type OutboundInput = Omit<Message, 'id'> & {
+    id?: string;
+};
+export declare function createConversationClient(options: ConversationClientOptions): {
+    authorization(event: ConversationEvent | ConversationError): Promise<AuthorizationRequirement>;
+    watch(conversationId: string, opts?: WatchOptions): AsyncGenerator<WatchedEvent>;
+    start: (message: OutboundInput, opts?: ReadParams & {
+        parentConversationId?: string;
+    }) => Promise<(ConversationState | EventPage) & {
+        messageId: string;
+    }>;
+    send: (conversationId: string, message: OutboundInput, opts?: ReadParams) => Promise<(ConversationState | EventPage) & {
+        messageId: string;
+    }>;
+    /** Re-dispatch a pending outbound operation with its original ID and content. */
+    retry: (id: string, signal?: AbortSignal) => Promise<ConversationState>;
+    operation(messageId: string): Promise<OutboundRecord | undefined>;
+    handoff: (conversationId: string, opts?: {
+        signal?: AbortSignal;
+    }) => Promise<ConversationState>;
+    close: (conversationId: string, opts?: {
+        signal?: AbortSignal;
+    }) => Promise<ConversationState>;
+    /** Reads one whole page. Explicit `cursor`, or the checkpoint of a named `consumer` (not both). Never acknowledges. */
+    read(conversationId: string, opts?: ReadOptions): Promise<EventPage>;
+    /** Reads pages until has_more is false. Pages are returned whole, never acknowledged. */
+    drain(conversationId: string, opts?: ReadOptions): Promise<EventPage[]>;
+    /** Durably advances the consumer to the page's cursor, after the application processed that page. A page never delivered to this consumer by this client instance is refused. */
+    ack(conversationId: string, consumer: string, page: EventPage): Promise<void>;
+    /** After cursor_expired: forget the checkpoint so the consumer rereads retained history from the start (dedupe by event ID; missing events were not processed). */
+    resetConsumer(conversationId: string, consumer: string): Promise<void>;
+};