@poppykit/client 0.0.0-stage → 0.1.1

package/STORAGE.md

@@ -0,0 +1,96 @@
+# Persistence and recovery
+
+Use targeted storage contracts. Node 24.12.0
+or later is required. The optional `@poppykit/client/sqlite` entry point exports
+`SqliteAuthStore` and `SqliteConversationStore`; importing the client core does not
+load SQLite. `node:sqlite` is experimental in the tested Node 24.12.0 runtime.
+Consumers can implement `AuthStore` and `ConversationStore` using their own database.
+
+```ts
+import { SqliteAuthStore, SqliteConversationStore } from '@poppykit/client/sqlite';
+const authStore = new SqliteAuthStore('/private/path/auth.db');
+const conversationStore = new SqliteConversationStore('/private/path/messages.db');
+// Pass authStore to createClientAuth and conversationStore to createConversationClient.
+// Close both after all operations have finished.
+```
+
+Use one auth database per namespace/local user/client identity. The owner tuple is
+checked on every SDK auth read and mutation. Identities are keyed by the exact full
+issuer, connections by immutable IDs, operations by ID and callback state hash,
+cleanup by connection, and token slots by session/resource. Secret values are never
+stored in auth records: immutable references point to the host's `SecretStore`.
+Session Tokens remain in process memory. Conversation databases contain message
+bodies; operators must provide private storage and their required encryption.
+
+Auth selections load an identity or a connection aggregate (its grants, operations,
+and cleanup), never unrelated connections. Operation/callback selectors resolve the
+owning connection through indexes. `list` explicitly enumerates connections.
+Recovery pages nonterminal operation IDs in batches of 100, then rechecks each
+operation and its owner inside its transaction. `cleanup(before, limit)` removes
+only terminal, non-uncertain auth history; the limit is at most 1000. It does not
+erase grants, pending exchanges, uncertain results, or secrets.
+
+Transactions must serialize conflicting domain updates across processes, roll back
+on exceptions, reject asynchronous mutation callbacks and non-JSON persisted values,
+enforce unique keys, and return detached values. SQLite uses WAL, FULL synchronous
+commits and a bounded busy wait. It serializes writers; parallel writers are not a
+promise. The database file must be on a local filesystem that supports SQLite's
+locking; this is not a distributed database. Create adapters before starting work,
+and keep network/vault calls outside transaction callbacks.
+
+Conversation storage has separate prepare/get/settle operations and checkpoint
+compare-and-set. An outbound ID is unique per connection/full issuer, and also
+records its endpoint. Retry rejects an endpoint change before sending. Preparation
+returns the existing record instead of replacing content; terminal outcomes cannot
+be overwritten by a late sender. Checkpoints include endpoint, conversation and
+consumer. Receipts remain available for retries: the old `keepCompleted` deletion
+behavior is removed. Retention preserves message identity and bounds payload cleanup; no automatic
+age-based deletion is performed.
+
+`MemoryConversationStore` from `@poppykit/client/memory` is non-durable and confined
+to one process. The SQLite adapters also accept `:memory:` for non-durable tests;
+each such adapter has its own database. Neither mode demonstrates process recovery.
+
+## Operation ownership
+
+Each active rotation or code exchange records a random execution owner, host name,
+and PID before dispatch. The default liveness check keeps other running local
+processes live; within this process it tracks actual active executions. Unknown
+remote hosts and permission errors are conservatively live. A new invocation cannot
+invalidate an active exchange just by starting recovery. A reused PID can delay
+recovery; it cannot authorize replay. Multi-host adapters must supply a trustworthy
+`ownerAlive` hook backed by their deployment's ownership/fencing mechanism. Returning
+false is an assertion of abandonment, not a request to cancel an active operation.
+
+Recovery rechecks phase/generation and liveness under the database transaction. A
+prepared abandoned rotation can release its claim; a dispatched exchange without a
+durably staged response becomes uncertain. A staged rotation can activate locally
+only if its connection/grant generations still match. Cancellation, disconnection,
+or another generation wins over late activation. No remote token exchange is replayed
+by recovery, and lease expiry would not prove that a request was never sent.
+
+The vault and remote issuer are outside the database transaction. Stage immutable
+secrets first, conditionally activate references, then remove superseded secrets.
+Vault failure or process death can leave an unreferenced staged secret; the host
+needs an orphan-secret sweep that respects active owners and a grace period. A lost
+remote rotation response remains uncertain. This adapter does not promise automatic
+recovery of a token that the issuer rotated but never delivered.
+
+## Development reset
+
+There is no automatic migration from old whole-state development stores. Stop all
+users of a disposable store, resolve uncertain remote outcomes, and explicitly move
+aside its database and WAL/SHM files and the matching host-managed secret namespace
+before creating a fresh store. Never reset live credentials by deleting a database
+behind a running process. Old stores are not silently deleted or reinterpreted.
+
+Contract tests cover real child-process contention, crash recovery, uncertain
+external effects, staged secrets and revocation races; see [contributing](CONTRIBUTING.md).
+
+## Conversation delivery lifetime
+
+See [DELIVERY.md](DELIVERY.md) for the retention table. Outbound records and
+checkpoints are retained until explicit local deletion; pending/uncertain retries
+must first be reconciled. Checkpoint acknowledgements use compare-and-set and do
+not acknowledge merely because a page or stream frame was read. Local deletion
+never deletes company history, revokes access or cancels accepted business work.

package/dist/auth/challenge.d.ts

@@ -0,0 +1,19 @@
+export declare function schemeChallenge(header: string | null, scheme: 'DPoP' | 'Bearer'): {
+    error?: string;
+    scope?: string;
+    extension?: string;
+    conversation_id?: string;
+} | undefined;
+export declare const dpopChallenge: (header: string | null) => {
+    error?: string;
+    scope?: string;
+    extension?: string;
+    conversation_id?: string;
+} | undefined;
+export interface AuthChallenge {
+    error?: string;
+    requiredScopes: string[];
+    extensions: string[];
+    conversationId?: string;
+}
+export declare function authChallenge(header: string | null, body?: unknown): AuthChallenge;

package/dist/auth/challenge.js

@@ -0,0 +1,68 @@
+// Reads the DPoP challenge from a WWW-Authenticate header (RFC 9110 11.6.1, spec 6); other schemes' params are ignored.
+const TOKEN = /[A-Za-z0-9!#$%&'*+.^_`|~-]+/y;
+export function schemeChallenge(header, scheme) {
+    if (!header)
+        return undefined;
+    let i = 0;
+    let current;
+    let found;
+    const skip = (chars) => { while (i < header.length && chars.test(header[i]))
+        i++; };
+    while (i < header.length) {
+        skip(/[\s,]/);
+        TOKEN.lastIndex = i;
+        const match = TOKEN.exec(header);
+        if (!match) {
+            i++;
+            continue;
+        }
+        i += match[0].length;
+        const afterToken = i;
+        skip(/\s/);
+        if (header[i] !== '=' || !current) {
+            if (header[i] === '=') {
+                i = afterToken;
+                skip(/[=\s]/);
+                continue;
+            } // token68 or stray param before any scheme
+            current = { scheme: match[0].toLowerCase(), params: {} };
+            if (current.scheme === scheme.toLowerCase())
+                found = current.params;
+            i = afterToken;
+            continue;
+        }
+        i++;
+        skip(/\s/);
+        let value = '';
+        if (header[i] === '"') {
+            i++;
+            while (i < header.length && header[i] !== '"') {
+                if (header[i] === '\\')
+                    i++;
+                value += header[i] ?? '';
+                i++;
+            }
+            i++;
+        }
+        else {
+            TOKEN.lastIndex = i;
+            value = TOKEN.exec(header)?.[0] ?? '';
+            i += value.length;
+        }
+        const name = match[0].toLowerCase();
+        if (current.scheme === scheme.toLowerCase() && ['error', 'scope', 'extension', 'conversation_id'].includes(name))
+            current.params[name] = value;
+    }
+    return found;
+}
+export const dpopChallenge = (header) => schemeChallenge(header, 'DPoP');
+// Combine independent detail channels: a sparse JSON error must not erase header scopes/extensions.
+export function authChallenge(header, body) {
+    const challenge = dpopChallenge(header), json = body && typeof body === 'object' && !Array.isArray(body) ? body : {};
+    const scopes = [challenge?.scope, json.scope].flatMap(value => typeof value === 'string' ? value.split(' ').filter(scope => /^[\x21\x23-\x5B\x5D-\x7E]+$/.test(scope)) : []);
+    const extensions = [challenge?.extension, json.extension].filter((value) => typeof value === 'string' && value.length <= 512 && /^(?:[A-Za-z0-9._-]+|(?:[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\.)+[A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?\/[A-Za-z0-9._~-]+(?:\/[A-Za-z0-9._~-]+)*)$/.test(value));
+    const safe = new Set(['sign_in_required', 'insufficient_scope', 'invalid_token', 'invalid_dpop_proof', 'use_dpop_nonce', 'extension_required', 'rate_limited', 'invalid_scope']);
+    const error = [challenge?.error, json.error].find((value) => typeof value === 'string' && safe.has(value));
+    const conversationId = [json.conversation_id, challenge?.conversation_id].find((value) => typeof value === 'string' && value.length > 0 && value.length <= 256);
+    return { ...(error ? { error } : {}), requiredScopes: [...new Set(scopes)], extensions: [...new Set(extensions)], ...(conversationId ? { conversationId } : {}) };
+}

package/dist/auth/client-auth.d.ts

@@ -0,0 +1,297 @@
+import type { AuthSelection, AuthStore } from './store.js';
+import type { OperationOwner } from './ownership.js';
+import type { JsonObject } from '../protocol/wire.js';
+import type { CompanyMetadata, MetadataResolver } from '../network/discovery.js';
+import type { HttpTransport } from '../network/transport.js';
+import type { ApiTarget, AgentBrowserController, FeedbackReport } from '../integrations.js';
+export type { AuthStore, AuthSelection };
+export interface SecretStore {
+    stage(secret: string): Promise<string>;
+    read(reference: string): Promise<string | null>;
+    remove(reference: string): Promise<void>;
+}
+export interface IdentitySigner {
+    readonly kid: string;
+    publicJwk(): Promise<JsonObject>;
+    sign(input: Uint8Array): Promise<Uint8Array>;
+}
+export type AssertionRequest = {
+    operationId: string;
+    issuer: string;
+} & ({
+    purpose: 'client-authentication';
+} | {
+    purpose: 'session';
+} | {
+    purpose: 'browser';
+    sessionId: string;
+    returnTo: string;
+});
+export interface AssertionProvider {
+    assert(request: AssertionRequest): Promise<{
+        assertion: string;
+        expiresAt: number;
+    }>;
+}
+export interface ProviderIdentity {
+    identity(issuer: string): Promise<{
+        clientId: string;
+        userId: string;
+    }>;
+}
+export type SignInMethod = 'direct' | 'device' | 'mediated';
+export interface AuthorizationRequirement {
+    requiredScopes: string[];
+    grantedScopes: string[];
+    missingScopes: string[];
+    sufficient: boolean;
+    methods: {
+        method: SignInMethod;
+        scopes: string[];
+    }[];
+    organization: {
+        name: string;
+        domain: string;
+    };
+}
+export interface TrustedInput {
+    collect(request: {
+        operationId: string;
+        issuer: string;
+        organization: {
+            name: string;
+            domain: string;
+        };
+        fields: {
+            name: string;
+            label: string;
+            secret: boolean;
+        }[];
+        challenge?: {
+            id: string;
+            sentTo: string;
+            expiresAt: number;
+        };
+    }): Promise<Record<string, string> | null>;
+}
+export interface SignInInput {
+    method?: SignInMethod;
+    scopes: string[];
+    redirectUri?: string;
+    browserBinding?: string;
+    force?: boolean;
+    requiredExistingScopes?: string[];
+}
+export interface SignInStart {
+    outcome: AuthOutcome;
+    authorizationUrl?: string;
+    device?: {
+        verificationUri: string;
+        verificationUriComplete?: string;
+        userCode: string;
+        organization: {
+            name: string;
+            domain: string;
+        };
+        nextPollAt: number;
+    };
+}
+export interface ClientAuthOptions {
+    namespace: string;
+    localUserId: string;
+    clientId: string;
+    redirectUris: readonly string[];
+    identity?: IdentitySigner;
+    assertions?: AssertionProvider;
+    providerIdentity?: ProviderIdentity;
+    trustedInput?: TrustedInput;
+    store: AuthStore;
+    secrets: SecretStore;
+    transport: HttpTransport;
+    metadata: MetadataResolver;
+    now?: () => number;
+    ownerAlive?: (owner: OperationOwner) => boolean;
+}
+export type ConnectionStatus = 'signed_out' | 'signed_in' | 'disconnected' | 'uncertain';
+export interface Connection {
+    id: string;
+    domain: string;
+    issuer: string;
+    organization: {
+        name: string;
+        domain: string;
+    };
+    sessionId: string | null;
+    generation: number;
+    status: ConnectionStatus;
+    scopes: string[];
+}
+export type OperationStatus = 'pending' | 'completed' | 'denied' | 'expired' | 'cancelled' | 'failed' | 'uncertain';
+export interface AuthOutcome {
+    operationId: string;
+    status: OperationStatus;
+    connection: Connection;
+    error?: string;
+    grantedScopes?: string[];
+    missingScopes?: string[];
+    retryAfterMs?: number;
+    nextAction?: 'wait' | 'sign_in' | 'retry_cleanup';
+}
+export interface SignOutOutcome {
+    connection: Connection;
+    cleanup: 'complete' | 'pending' | 'uncertain';
+}
+export interface ConversationTarget {
+    issuer: string;
+    endpoint: string;
+    resource?: string;
+}
+export interface ClientAuth {
+    start(domain: string, input?: {
+        anonymous?: boolean;
+    }): Promise<AuthOutcome>;
+    get(connectionId: string): Promise<Connection | null>;
+    list(): Promise<Connection[]>;
+    target(connectionId: string): Promise<ConversationTarget>;
+    authorization(connectionId: string, requiredScopes: readonly string[]): Promise<AuthorizationRequirement>;
+    beginSignIn(connectionId: string, input: SignInInput): Promise<SignInStart>;
+    continueSignIn(operationId: string): Promise<AuthOutcome>;
+    completeSignIn(input: {
+        callbackUrl: string;
+        browserBinding: string;
+    }): Promise<AuthOutcome>;
+    cancelSignIn(operationId: string): Promise<AuthOutcome>;
+    operation(operationId: string): Promise<AuthOutcome | null>;
+    renew(connectionId: string, input?: {
+        resource?: string;
+        scopes?: string[];
+    }): Promise<AuthOutcome>;
+    signOut(connectionId: string): Promise<SignOutOutcome>;
+    retryCleanup(connectionId: string): Promise<SignOutOutcome>;
+    recover(): Promise<AuthOutcome[]>;
+    authorizedFetch(connectionId: string, request: Request, target: ConversationTarget, requiredScopes?: readonly string[]): Promise<Response>;
+    apiTarget(connectionId: string, apiUrl: string, destination?: string): Promise<ApiTarget>;
+    apiFetch(connectionId: string, request: Request, target: ApiTarget, requiredScopes?: readonly string[]): Promise<Response>;
+    joinBrowser(connectionId: string, returnTo: string, controller: AgentBrowserController): Promise<void>;
+    feedback(connectionId: string, report: FeedbackReport): Promise<void>;
+}
+export interface CredentialRecord {
+    secretRef: string;
+    tokenType: 'DPoP' | 'Bearer';
+    dpopKeyRef: string;
+    scopes: string[];
+    expiresAt: number;
+    generation: number;
+}
+export interface ConnectionRecord {
+    id: string;
+    domain: string;
+    issuer: string;
+    metadata: CompanyMetadata;
+    userId: string;
+    dpopKeyRef: string;
+    sessionId: string | null;
+    generation: number;
+    status: ConnectionStatus;
+    grantId: string | null;
+    slots: Record<string, CredentialRecord>;
+    anonymous?: boolean;
+    notBefore?: string;
+}
+export interface GrantRecord {
+    id: string;
+    issuer: string;
+    userId: string;
+    secretRef: string;
+    scopes: string[];
+    expiresAt: number | null;
+    generation: number;
+    status: 'active' | 'uncertain' | 'revoking' | 'revoked';
+    operationId: string | null;
+}
+export interface DirectRecord {
+    stateHash: string;
+    verifierRef: string;
+    browserHash: string;
+    redirectUri: string;
+    issuer: string;
+    clientId: string;
+    sessionId: string;
+}
+export interface OperationRecord {
+    owner?: OperationOwner;
+    epoch: string;
+    id: string;
+    kind: 'start' | 'renew' | 'sign_in';
+    connectionId: string;
+    connectionGeneration: number;
+    grantId: string | null;
+    grantGeneration: number | null;
+    phase: 'prepared' | 'dispatched' | 'staged' | 'terminal';
+    status: OperationStatus;
+    createdAt: number;
+    expiresAt: number;
+    resource: string | null;
+    scopes: string[];
+    direct: DirectRecord | null;
+    staged: StagedRefresh | null;
+    result: AuthOutcome | null;
+    method?: SignInMethod;
+    requiredExistingScopes?: string[];
+    signInSessionId?: string;
+    device?: {
+        codeRef: string;
+        intervalMs: number;
+        nextPollAt: number;
+    };
+    mediated?: {
+        challengeId: string;
+        sentTo: string;
+    };
+    cancelRequested?: boolean;
+}
+export interface StagedRefresh {
+    tokenType?: 'DPoP' | 'Bearer';
+    accessRef: string;
+    refreshRef: string | null;
+    sessionId: string;
+    scopes: string[];
+    signedIn: boolean;
+    expiresAt: number;
+    refreshExpiresAt: number | null;
+}
+export interface CleanupRecord {
+    id: string;
+    connectionId: string;
+    issuer: string;
+    revocationEndpoint: string;
+    secretRef: string;
+    status: 'pending' | 'uncertain';
+    notBefore?: string;
+}
+export interface ClientAuthState {
+    version: 1;
+    epoch: string;
+    owner: {
+        namespace: string;
+        clientId: string;
+        localUserId: string;
+    } | null;
+    identities: Record<string, {
+        userId: string;
+        dpopKeyRef: string;
+    }>;
+    connections: Record<string, ConnectionRecord>;
+    grants: Record<string, GrantRecord>;
+    operations: Record<string, OperationRecord>;
+    cleanup: Record<string, CleanupRecord>;
+}
+export declare class AuthFailure extends Error {
+    readonly code: string;
+    readonly connectionId?: string | undefined;
+    readonly retryAfterMs?: number | undefined;
+    readonly retryAt?: string | undefined;
+    constructor(code: string, connectionId?: string | undefined, retryAfterMs?: number | undefined, retryAt?: string | undefined);
+}
+export declare function initialClientAuthState(): ClientAuthState;
+export declare function createClientAuth(options: ClientAuthOptions): ClientAuth;