@poppykit/client 0.0.0-stage → 0.1.1

package/dist/protocol/wire.js

@@ -0,0 +1,278 @@
+export class ValidationError extends Error {
+    field;
+    constructor(field) {
+        super(`Invalid protocol field: ${field}`);
+        this.field = field;
+        this.name = 'ValidationError';
+    }
+}
+export function validateJson(value) {
+    const stack = [{ value, depth: 0 }];
+    while (stack.length) {
+        const current = stack.pop();
+        if (current.depth > 64)
+            throw new ValidationError('json.depth');
+        if (current.value === null || typeof current.value === 'string' || typeof current.value === 'boolean')
+            continue;
+        if (typeof current.value === 'number' && Number.isFinite(current.value))
+            continue;
+        if (typeof current.value !== 'object' || (Object.getPrototypeOf(current.value) !== Object.prototype && !Array.isArray(current.value)))
+            throw new ValidationError('json');
+        for (const child of Object.values(current.value))
+            stack.push({ value: child, depth: current.depth + 1 });
+    }
+}
+export function object(value, field = 'document') {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new ValidationError(field);
+    validateJson(value);
+    return value;
+}
+export function string(value, field, nonempty = true) {
+    if (typeof value !== 'string' || (nonempty && !value.length))
+        throw new ValidationError(field);
+    return value;
+}
+export function member(value, values, field) {
+    if (!values.includes(value))
+        throw new ValidationError(field);
+}
+export function id(value, field) {
+    const result = string(value, field);
+    if (!/^[A-Za-z0-9_-]{1,256}$/.test(result))
+        throw new ValidationError(field);
+    return result;
+}
+function positive(value, field) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new ValidationError(field);
+}
+export function parseMessage(value, options = {}) {
+    const message = { ...object(value, 'message') };
+    id(message.id, 'message.id');
+    member(message.sender, ['agent', 'human'], 'message.sender');
+    if (!['text', 'data', 'context'].some(key => key in message))
+        throw new ValidationError('message.content');
+    if ('text' in message)
+        string(message.text, 'message.text', false);
+    if ('data' in message)
+        object(message.data, 'message.data');
+    if (options.recorded)
+        member(message.role, ['user', 'company'], 'message.role');
+    else
+        delete message.role;
+    if ('context' in message) {
+        if (options.company || message.role === 'company')
+            throw new ValidationError('message.context');
+        const context = object(message.context, 'message.context');
+        if ('user_available' in context)
+            member(context.user_available, [true, false], 'message.context.user_available');
+        if ('locale' in context) {
+            const locale = string(context.locale, 'message.context.locale');
+            try {
+                new Intl.Locale(locale);
+            }
+            catch {
+                throw new ValidationError('message.context.locale');
+            }
+        }
+        if ('time_zone' in context) {
+            const zone = string(context.time_zone, 'message.context.time_zone');
+            if (/^[+-]/.test(zone))
+                throw new ValidationError('message.context.time_zone');
+            try {
+                new Intl.DateTimeFormat('en', { timeZone: zone });
+            }
+            catch {
+                throw new ValidationError('message.context.time_zone');
+            }
+        }
+    }
+    return message;
+}
+export function parseConversationRequest(value) {
+    const request = object(value);
+    if ('parent_conversation_id' in request)
+        id(request.parent_conversation_id, 'parent_conversation_id');
+    return { ...request, message: parseMessage(request.message) };
+}
+export function parseConversationState(value) {
+    const state = object(value);
+    id(state.conversation_id, 'conversation_id');
+    member(state.status, ['working', 'idle', 'queued', 'closed'], 'status');
+    member(state.responder, ['agent', 'human'], 'responder');
+    return state;
+}
+export function parseEvent(value) {
+    const event = object(value, 'event');
+    id(event.id, 'event.id');
+    string(event.type, 'event.type');
+    const date = string(event.created_at, 'event.created_at');
+    const parts = /^(\d{4})-(\d{2})-(\d{2})[Tt](\d{2}):(\d{2}):(\d{2})(?:\.\d+)?(?:[Zz]|([+-])(\d{2}):(\d{2}))$/.exec(date);
+    if (!parts)
+        throw new ValidationError('event.created_at');
+    const [, year, month, day, hour, minute, second, , offsetHour = '0', offsetMinute = '0'] = parts;
+    const days = new Date(`${year}-${month}-01T00:00:00Z`);
+    days.setUTCMonth(days.getUTCMonth() + 1);
+    days.setUTCDate(0);
+    if (+month < 1 || +month > 12 || +day < 1 || +day > days.getUTCDate() || +hour > 23 || +minute > 59 || +second > 60 || +offsetHour > 23 || +offsetMinute > 59)
+        throw new ValidationError('event.created_at');
+    switch (event.type) {
+        case 'message':
+            parseMessage(event.message, { recorded: true });
+            break;
+        case 'state':
+            member(event.status, ['working', 'idle', 'queued', 'closed'], 'event.status');
+            member(event.responder, ['agent', 'human'], 'event.responder');
+            break;
+        case 'authorization':
+            member(event.error, ['sign_in_required', 'insufficient_scope'], 'event.error');
+            if (event.error === 'insufficient_scope' || 'scope' in event)
+                string(event.scope, 'event.scope', false);
+            break;
+        case 'user_requested':
+            string(event.reason, 'event.reason', false);
+            break;
+        case 'direct_opened':
+        case 'direct_closed':
+            id(event.conversation_id, 'event.conversation_id');
+            break;
+    }
+    return event;
+}
+export function parseEventPage(value, requestCursor) {
+    const page = parseConversationState(value);
+    if (!Array.isArray(page.events))
+        throw new ValidationError('events');
+    page.events.forEach(parseEvent);
+    member(page.has_more, [true, false], 'has_more');
+    if (page.cursor === null) {
+        if (requestCursor !== undefined || page.events.length || page.has_more)
+            throw new ValidationError('cursor');
+    }
+    else {
+        string(page.cursor, 'cursor');
+        const expected = page.events.length ? page.events.at(-1).id : requestCursor;
+        if (expected !== undefined && page.cursor !== expected)
+            throw new ValidationError('cursor');
+    }
+    return page;
+}
+export function parseTokenResponse(value) {
+    const token = object(value);
+    string(token.access_token, 'access_token');
+    string(token.session_id, 'session_id');
+    string(token.scope, 'scope', false);
+    member(token.token_type, ['DPoP', 'Bearer'], 'token_type');
+    member(token.signed_in, [true, false], 'signed_in');
+    positive(token.expires_in, 'expires_in');
+    if ('refresh_token' in token)
+        string(token.refresh_token, 'refresh_token');
+    if ('refresh_token_expires_in' in token)
+        positive(token.refresh_token_expires_in, 'refresh_token_expires_in');
+    return token;
+}
+export function parseProtocolError(value) {
+    const error = object(value);
+    string(error.error, 'error');
+    for (const key of ['error_description', 'error_uri'])
+        if (key in error)
+            string(error[key], key, false);
+    if (error.error === 'extension_required' || 'extension' in error)
+        string(error.extension, 'extension');
+    if (error.error === 'direct_conversation_open' || 'conversation_id' in error)
+        id(error.conversation_id, 'conversation_id');
+    return error;
+}
+export function parseReadOptions(url, maxWaitSeconds) {
+    if (!Number.isSafeInteger(maxWaitSeconds) || maxWaitSeconds < 0)
+        throw new ValidationError('maxWaitSeconds');
+    for (const key of ['wait', 'cursor'])
+        if (url.searchParams.getAll(key).length > 1)
+            throw new ValidationError(key);
+    const wait = url.searchParams.get('wait') ?? '0';
+    if (!/^\d+$/.test(wait))
+        throw new ValidationError('wait');
+    const cursor = url.searchParams.get('cursor');
+    if (cursor !== null)
+        string(cursor, 'cursor');
+    return { ...(cursor === null ? {} : { cursor }), waitSeconds: Number(BigInt(wait) > BigInt(maxWaitSeconds) ? maxWaitSeconds : BigInt(wait)) };
+}
+export function retryAfterMilliseconds(value, nowMs) {
+    if (!value)
+        return undefined;
+    if (/^\d+$/.test(value)) {
+        const ms = Number(value) * 1000;
+        return Number.isSafeInteger(ms) ? ms : Infinity;
+    } // too large to wait: let the caller's maxDelay check surface it
+    if (!/^[A-Za-z]{3}, \d{2} [A-Za-z]{3} \d{4} \d{2}:\d{2}:\d{2} GMT$/.test(value))
+        return undefined;
+    const date = Date.parse(value);
+    return Number.isFinite(date) ? Math.max(0, date - nowMs) : undefined;
+}
+// Session and client assertions (spec 4.1/4.2): aud is the issuer as a single string, exp - iat <= 300s.
+export function parseAssertionClaims(value) {
+    const claims = object(value, 'claims');
+    for (const key of ['iss', 'sub', 'aud', 'jti'])
+        string(claims[key], key);
+    // 128 random bits is at least 16 bytes; cap length since jti lands in the replay store. Encoding is not constrained.
+    if (claims.jti.length < 16 || claims.jti.length > 256)
+        throw new ValidationError('jti');
+    positive(claims.iat, 'iat');
+    positive(claims.exp, 'exp');
+    if (claims.exp <= claims.iat || claims.exp - claims.iat > 300)
+        throw new ValidationError('exp');
+    return claims;
+}
+// DPoP proof payload (spec 4.3); htu carries no query or fragment.
+export function parseDpopClaims(value) {
+    const claims = object(value, 'claims');
+    string(claims.jti, 'jti');
+    string(claims.htm, 'htm');
+    positive(claims.iat, 'iat');
+    const htu = string(claims.htu, 'htu');
+    try {
+        const url = new URL(htu);
+        if (url.protocol !== 'https:' || url.search || url.hash || htu.includes('?') || htu.includes('#'))
+            throw 0;
+    }
+    catch {
+        throw new ValidationError('htu');
+    }
+    for (const key of ['ath', 'nonce'])
+        if (key in claims)
+            string(claims[key], key);
+    return claims;
+}
+// Sorted keys so structural equality ignores key order but keeps arrays, text and unknown members exact.
+export function canonical(value) {
+    const walk = (item) => {
+        if (Array.isArray(item))
+            return `[${item.map(walk).join(',')}]`;
+        if (item && typeof item === 'object')
+            return `{${Object.keys(item).sort().map(key => `${JSON.stringify(key)}:${walk(item[key])}`).join(',')}}`;
+        return JSON.stringify(item);
+    };
+    return walk(JSON.parse(JSON.stringify(value))); // same shape as the wire (drops undefined members)
+}
+// JSON.parse that rejects duplicate member names (guide "Transport and JSON"); JSON.parse alone keeps the last one.
+export function parseJson(text) {
+    const value = JSON.parse(text); // validates syntax, so the scan below only sees well-formed tokens
+    const stack = [];
+    const tokens = text.match(/"(?:[^"\\]|\\.)*"|[{}[\],:]|[^\s"{}[\],:]+/g) ?? [];
+    tokens.forEach((token, index) => {
+        if (token === '{')
+            stack.push(new Set());
+        else if (token === '[')
+            stack.push(null);
+        else if (token === '}' || token === ']')
+            stack.pop();
+        else if (token[0] === '"' && tokens[index + 1] === ':') {
+            const names = stack.at(-1), name = JSON.parse(token);
+            if (names?.has(name))
+                throw new ValidationError('json.duplicate_member');
+            names?.add(name);
+        }
+    });
+    return value;
+}

package/dist/provider-sqlite.d.ts

@@ -0,0 +1,8 @@
+import type { 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;
+}

package/dist/provider-sqlite.js

@@ -0,0 +1,30 @@
+import { DatabaseSync } from 'node:sqlite';
+import { initializeSqlite } from './sqlite-init.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));'));
+    }
+    close() { this.db.close(); }
+    transaction(action) {
+        this.db.exec('BEGIN IMMEDIATE');
+        try {
+            const result = action({
+                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)
+                throw new TypeError('provider transaction must be synchronous');
+            this.db.exec('COMMIT');
+            return result;
+        }
+        catch (error) {
+            this.db.exec('ROLLBACK');
+            throw error;
+        }
+    }
+}

package/dist/provider.d.ts

@@ -0,0 +1,121 @@
+import type { IdentitySigner } from './auth/client-auth.js';
+import type { MetadataResolver } from './network/discovery.js';
+import type { HttpTransport } from './network/transport.js';
+type Row = Record<string, any>;
+export interface ProviderTransaction {
+    get(kind: string, id: string): Row | undefined;
+    put(kind: string, id: string, value: Row): void;
+    remove(kind: string, id: string): void;
+    list(kind: string, prefix: string, limit: number): {
+        id: string;
+        value: Row;
+    }[];
+}
+/** Must commit synchronously, atomically across processes; callback must not perform I/O. */
+export interface ProviderStore {
+    transaction<T>(action: (tx: ProviderTransaction) => T): T;
+}
+export interface ResultCipher {
+    seal(value: string): string;
+    open(value: string): string;
+}
+export declare function createResultCipher(key: Uint8Array): ResultCipher;
+export type ProviderErrorCode = 'unauthorized' | 'binding_conflict' | 'expired' | 'consumed' | 'canceled' | 'rate_limited' | 'unavailable';
+export declare class ProviderError extends Error {
+    readonly code: ProviderErrorCode;
+    readonly retryAt?: number | undefined;
+    constructor(code: ProviderErrorCode, retryAt?: number | undefined);
+}
+export interface ProviderOptions {
+    clientId: string;
+    callbackUrl: string;
+    jwksUri: string;
+    clientName: string;
+    store: ProviderStore;
+    cipher: ResultCipher;
+    metadata: MetadataResolver;
+    signer: IdentitySigner;
+    /** Publish new keys before use and retain retired public keys through assertion expiry + skew. */
+    publishedKeys?: () => Promise<Record<string, any>[]>;
+    /** Validate operator login and CSRF; caller IDs and public setup URLs are never authentication. */
+    authenticateEnrollment(request: Request): Promise<{
+        subject: string;
+        allowedCompanies: string[];
+    } | null>;
+    /** Required for browser assertions: independently prove session belongs to this client AND derived user. */
+    verifySession?(binding: {
+        clientId: string;
+        userId: string;
+        issuer: string;
+        sessionId: string;
+    }): Promise<boolean>;
+    now?: () => number;
+    maxEnrollments?: number;
+}
+export declare function createProvider(options: ProviderOptions): {
+    enroll(request: Request, input: Row): Promise<{
+        enrollmentId: string;
+        credential: string;
+        clientId: string;
+        callbackUrl: string;
+    }>;
+    identity(credential: string, input: Row): Promise<{
+        clientId: string;
+        userId: string;
+    }>;
+    begin(credential: string, input: Row): Promise<{
+        expiresAt: any;
+    }>;
+    assert(credential: string, input: Row): Promise<{
+        assertion: string;
+        expiresAt: number;
+    }>;
+    callback(callbackUrl: string): {
+        status: string;
+    };
+    takeResult(credential: string, input: Row): {
+        status: string;
+        callbackUrl?: undefined;
+    } | {
+        status: string;
+        callbackUrl: string;
+    };
+    cancel(credential: string, input: Row): {
+        status: string;
+    };
+    revokeEnrollment(credential: string, input: Row): {
+        status: string;
+    };
+    handle(request: Request): Promise<Response>;
+};
+/** Bound trusted adapter: credentials/assertions/results never belong in harness output. */
+export declare function createProviderClient(options: {
+    url: string;
+    installationId: string;
+    credential: () => Promise<string>;
+    transport: HttpTransport;
+    domain: string;
+}): {
+    identity: (issuer: string) => Promise<{
+        clientId: string;
+        userId: string;
+    }>;
+    assert: (request: import("./auth/client-auth.js").AssertionRequest) => Promise<{
+        assertion: string;
+        expiresAt: number;
+    }>;
+    beginDirect: (input: {
+        operationId: string;
+        issuer: string;
+        sessionId: string;
+        state: string;
+    }) => Promise<Row>;
+    takeResult: (input: {
+        operationId: string;
+        issuer: string;
+        sessionId: string;
+    }) => Promise<Row>;
+    cancel: (operationId: string) => Promise<Row>;
+    revokeEnrollment: () => Promise<Row>;
+};
+export {};