@poppykit/server 0.0.0-stage → 0.1.0

package/dist/auth/dpop.js

@@ -0,0 +1,49 @@
+import { createHash } from 'node:crypto';
+import { calculateJwkThumbprint, compactVerify, decodeProtectedHeader, importJWK } from 'jose';
+import { parseDpopClaims, parseJson } from '../protocol/wire.js';
+import { AuthorityError } from './authority.js';
+export const PROOF_WINDOW_SECONDS = 60;
+export const CLOCK_SKEW_SECONDS = 30;
+const COMPACT_JWT = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+export function base64urlSha256(value) { return createHash('sha256').update(value).digest('base64url'); }
+// Origin plus path: the htu form RFC 9449 compares (no query or fragment).
+export function canonicalHtu(url) { const parsed = new URL(url); return `${parsed.origin}${parsed.pathname}`; }
+// Header and payload both go through parseJson: jose's JSON.parse keeps the last of any duplicate member.
+export function assertUniqueJwtMembers(jwt) { for (const segment of jwt.split('.').slice(0, 2))
+    parseJson(Buffer.from(segment, 'base64url').toString('utf8')); }
+// RFC 9449 section 4.3 checks except nonce and replay, which only the token endpoint enforces.
+// accessToken absent means a token-endpoint proof, which must not carry ath.
+export async function verifyDpopProof(proof, expected) {
+    const invalid = () => new AuthorityError('invalid_dpop_proof');
+    // Several DPoP headers arrive joined by ", ", which fails the compact-JWT pattern.
+    if (!proof || proof.length > 8192 || !COMPACT_JWT.test(proof))
+        throw invalid();
+    let claims;
+    let jkt;
+    let htu;
+    try {
+        assertUniqueJwtMembers(proof);
+        const header = decodeProtectedHeader(proof);
+        const jwk = header.jwk;
+        if (header.typ !== 'dpop+jwt' || header.alg !== 'ES256' || !jwk || jwk.kty !== 'EC' || jwk.crv !== 'P-256' || 'd' in jwk)
+            throw invalid();
+        const { payload } = await compactVerify(proof, await importJWK(jwk, 'ES256'), { algorithms: ['ES256'] });
+        claims = parseDpopClaims(JSON.parse(new TextDecoder().decode(payload)));
+        htu = canonicalHtu(claims.htu);
+        jkt = await calculateJwkThumbprint(jwk);
+    }
+    catch {
+        throw invalid();
+    }
+    const nowSeconds = expected.nowMs / 1000;
+    // jti is retained by the token-endpoint replay store, so bound it here (parseDpopClaims does not).
+    if (claims.jti.length > 256 || (claims.nonce?.length ?? 0) > 256)
+        throw invalid();
+    if (claims.htm !== expected.method || htu !== canonicalHtu(expected.url))
+        throw invalid();
+    if (claims.iat > nowSeconds + CLOCK_SKEW_SECONDS || claims.iat < nowSeconds - PROOF_WINDOW_SECONDS)
+        throw invalid();
+    if (expected.accessToken === undefined ? 'ath' in claims : claims.ath !== base64urlSha256(expected.accessToken))
+        throw invalid();
+    return { claims, jkt };
+}

package/dist/browser.d.ts

@@ -0,0 +1,44 @@
+import type { MetadataResolver } from './network/discovery.js';
+import type { Principal, AuthorityPolicy } from './auth/authority.js';
+export interface BrowserBinding {
+    clientId: string;
+    userId: string;
+    sessionId: string;
+    issuerGeneration?: string;
+}
+export interface BrowserSession extends BrowserBinding {
+    principal: Principal;
+    expiresAt: number;
+}
+export interface BrowserSessionAuthority {
+    join(binding: BrowserBinding, assertion: {
+        jti: string;
+        expiresAt: number;
+    }): Promise<BrowserSession>;
+    current(binding: BrowserBinding): Promise<BrowserSession>;
+}
+export interface BrowserCookieStore {
+    put(hash: string, binding: BrowserBinding & {
+        expiresAt: number;
+    }): Promise<void>;
+    get(hash: string): Promise<(BrowserBinding & {
+        expiresAt: number;
+    }) | null>;
+}
+export declare function boundedText(request: Request, max: number): Promise<string>;
+export declare function createBrowserSessions(options: {
+    endpoint: string;
+    domain: string;
+    metadata: MetadataResolver;
+    authority: BrowserSessionAuthority;
+    cookies: BrowserCookieStore;
+    policy: AuthorityPolicy;
+    now: () => number;
+    cookieName?: string;
+    sameSite?: 'Lax' | 'None';
+    cookieLifetimeSeconds?: number;
+}): {
+    authenticate: (request: Request) => Promise<Principal>;
+    withSession<T>(request: Request, scopes: readonly string[], action: (principal: Principal) => Promise<T>): Promise<T>;
+    join(request: Request): Promise<Response>;
+};

package/dist/browser.js

@@ -0,0 +1,110 @@
+import { createHash, randomBytes } from 'node:crypto';
+import { compactVerify, createLocalJWKSet, decodeJwt, errors } from 'jose';
+import { secureUrl } from './network/transport.js';
+import { parseJson, object } from './protocol/wire.js';
+import { assertUniqueJwtMembers } from './auth/dpop.js';
+import { AuthorityError } from './auth/authority.js';
+const hash = (value) => createHash('sha256').update(value).digest('base64url');
+export async function boundedText(request, max) {
+    if (!request.body)
+        throw new TypeError('body');
+    const reader = request.body.getReader();
+    let size = 0;
+    const parts = [];
+    try {
+        for (;;) {
+            const next = await reader.read();
+            if (next.done)
+                break;
+            size += next.value.byteLength;
+            if (size > max)
+                throw new TypeError('body');
+            parts.push(next.value);
+        }
+    }
+    catch (error) {
+        await reader.cancel().catch(() => { });
+        throw error;
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(parts));
+}
+export function createBrowserSessions(options) {
+    secureUrl(options.endpoint);
+    const name = options.cookieName ?? '__Host-poppy-session', sameSite = options.sameSite ?? 'Lax', lifetime = options.cookieLifetimeSeconds ?? 3600;
+    if (!/^[A-Za-z0-9_-]+$/.test(name) || !['Lax', 'None'].includes(sameSite) || !Number.isSafeInteger(lifetime) || lifetime < 1 || !/^[a-z0-9.-]+$/i.test(options.domain))
+        throw new TypeError('browser options');
+    const invalid = () => new Error('Invalid browser session');
+    async function authenticate(request) {
+        const cookies = (request.headers.get('cookie') ?? '').split(';').map(part => part.trim().split('='));
+        const matches = cookies.filter(([key]) => key === name);
+        if (matches.length !== 1 || matches[0].length !== 2 || !/^[A-Za-z0-9_-]{43}$/.test(matches[0][1]))
+            throw invalid();
+        const binding = await options.cookies.get(hash(matches[0][1]));
+        if (!binding || binding.expiresAt <= options.now())
+            throw invalid();
+        const session = await options.authority.current(binding);
+        if (session.expiresAt <= options.now() || session.clientId !== binding.clientId || session.userId !== binding.userId || session.sessionId !== binding.sessionId || session.issuerGeneration !== binding.issuerGeneration)
+            throw invalid();
+        return session.principal;
+    }
+    return {
+        authenticate,
+        async withSession(request, scopes, action) {
+            const principal = await authenticate(request);
+            return options.policy.withCurrent(principal, [], async () => {
+                const current = await options.authority.current(principal);
+                if (!scopes.every(scope => current.principal.scopes.includes(scope)))
+                    throw new AuthorityError('insufficient_scope');
+                return action(current.principal);
+            });
+        },
+        async join(request) {
+            try {
+                if (request.method !== 'POST' || request.url !== options.endpoint || request.headers.get('content-type')?.split(';')[0] !== 'application/x-www-form-urlencoded')
+                    throw invalid();
+                const fields = new URLSearchParams(await boundedText(request, 16384));
+                if (fields.getAll('assertion').length !== 1 || [...fields.keys()].some(key => key !== 'assertion'))
+                    throw invalid();
+                const jwt = fields.get('assertion');
+                if (jwt.length > 8192)
+                    throw invalid();
+                assertUniqueJwtMembers(jwt);
+                const untrusted = decodeJwt(jwt);
+                if (typeof untrusted.iss !== 'string')
+                    throw invalid();
+                const client = await options.metadata.resolveClient(untrusted.iss);
+                let keys = await options.metadata.resolveJwks(client.jwks_uri);
+                let verified;
+                try {
+                    verified = await compactVerify(jwt, createLocalJWKSet(keys), { algorithms: ['ES256', 'RS256'] });
+                }
+                catch (error) {
+                    if (!(error instanceof errors.JWKSNoMatchingKey))
+                        throw error;
+                    keys = await options.metadata.resolveJwks(client.jwks_uri, { refresh: true });
+                    verified = await compactVerify(jwt, createLocalJWKSet(keys), { algorithms: ['ES256', 'RS256'] });
+                }
+                const claims = object(parseJson(new TextDecoder().decode(verified.payload)));
+                if (verified.protectedHeader.typ?.toLowerCase().replace(/^application\//, '') !== 'poppy-browser+jwt' || claims.iss !== client.client_id || claims.aud !== options.endpoint || typeof claims.sub !== 'string' || !claims.sub || claims.sub.length > 256 || typeof claims.session_id !== 'string' || !claims.session_id || typeof claims.jti !== 'string' || !claims.jti || claims.jti.length > 256 || !Number.isSafeInteger(claims.iat) || !Number.isSafeInteger(claims.exp) || claims.exp <= options.now() / 1000 || claims.iat > options.now() / 1000 + 30 || claims.exp <= claims.iat || claims.exp - claims.iat > 60 || typeof claims.return_to !== 'string')
+                    throw invalid();
+                const destination = secureUrl(claims.return_to);
+                if (destination.hostname !== options.domain.toLowerCase() && !destination.hostname.endsWith(`.${options.domain.toLowerCase()}`))
+                    throw invalid();
+                const session = await options.authority.join({ clientId: client.client_id, userId: claims.sub, sessionId: claims.session_id }, { jti: claims.jti, expiresAt: claims.exp * 1000 });
+                const seconds = Math.floor(Math.min(session.expiresAt - options.now(), lifetime * 1000) / 1000);
+                if (seconds < 1)
+                    throw invalid();
+                const value = randomBytes(32).toString('base64url');
+                const { clientId, userId, sessionId, issuerGeneration } = session;
+                await options.cookies.put(hash(value), { clientId, userId, sessionId, ...(issuerGeneration === undefined ? {} : { issuerGeneration }), expiresAt: options.now() + seconds * 1000 });
+                return new Response(null, { status: 303, headers: { Location: claims.return_to, 'Set-Cookie': `${name}=${value}; Path=/; Secure; HttpOnly; SameSite=${sameSite}; Max-Age=${seconds}`, 'Cache-Control': 'no-store' } });
+            }
+            catch {
+                return new Response('Invalid browser session', { status: 400, headers: { 'Cache-Control': 'no-store', 'Content-Type': 'text/plain' } });
+            }
+        },
+    };
+}

package/dist/conversation/service.d.ts

@@ -0,0 +1,126 @@
+import type { ConversationEvent, JsonObject, Message, Sender, Status } from '../protocol/wire.js';
+import type { ConversationStore, ConversationNotifications } from './store.js';
+import type { AcceptedAuthority, AuthorityPolicy, RequestAuthenticator, WorkRevocationPolicy } from '../auth/authority.js';
+export interface ConversationRecord {
+    id: string;
+    issuer: string;
+    clientId: string;
+    userId: string;
+    bindingId: string;
+    lastUserMessage?: Message;
+    status: Status;
+    responder: Sender;
+    context: JsonObject;
+    events: ConversationEvent[];
+    eventWindow?: {
+        invalid?: boolean;
+        expired?: boolean;
+        hasMore: boolean;
+    };
+    authority: AcceptedAuthority;
+    parentId?: string;
+    childId?: string;
+    humanUntil?: number;
+}
+export interface WorkRecord {
+    id: string;
+    conversationId: string;
+    message: Message;
+    authority: AcceptedAuthority;
+    phase: 'held' | 'pending' | 'claimed' | 'completed' | 'suspended' | 'failed' | 'cancelled';
+    fence?: string;
+    leaseUntil?: number;
+    human?: true;
+    outputs: Record<string, string>;
+}
+export interface MessageRecord {
+    conversationId: string;
+    fingerprint: string;
+    receipt: {
+        status: number;
+        body: JsonObject;
+    };
+}
+export interface ConversationStoreState {
+    cursorStatus?: 'expired' | 'invalid';
+    version: 1;
+    generation: string;
+    conversations: Record<string, ConversationRecord>;
+    bindings: Record<string, {
+        accountId?: string;
+    }>;
+    messages: Record<string, MessageRecord>;
+    work: WorkRecord[];
+}
+export interface ConversationOptions {
+    endpoint: string;
+    store: ConversationStore;
+    authenticator: RequestAuthenticator;
+    policy: AuthorityPolicy;
+    clock: {
+        now(): number;
+    };
+    revocationPolicy?: WorkRevocationPolicy;
+    pageSize?: number;
+    leaseMs?: number;
+    operatorLeaseMs?: number;
+    finishedWorkLimit?: number;
+    notifications?: ConversationNotifications;
+    maxPageBytes?: number;
+    maxEventBytes?: number;
+    maxFrameBytes?: number;
+    streamMs?: number;
+    supportedScopes?: readonly string[];
+    pollIntervalMs?: number;
+    /** Mandatory for staff methods: authenticate and authorize this company operator for the conversation, or throw. */
+    authorizeOperator?: (operator: unknown, conversationId: string) => Promise<void>;
+    /** Mandatory for requestAuthorization: the scopes the issuer's Direct Sign-In grants; work may ask only for these. */
+    directScopes?: readonly string[];
+    /** Scopes that allow reading account-bound history; default ['poppy:read']. A Company offering only custom scopes sets its own. */
+    historyScopes?: readonly string[];
+}
+export interface WorkRef {
+    workId: string;
+    fence: string;
+}
+export interface WorkClaim extends WorkRef {
+    conversationId: string;
+    message: Message;
+    context: JsonObject;
+}
+export interface ConversationService {
+    /** Protocol errors become responses; anything else is re-thrown, so hosts must catch it and answer 500. */
+    handle(request: Request): Promise<Response>;
+    claim(): Promise<WorkClaim | null>;
+    renew(work: WorkRef): Promise<void>;
+    /** Conversation history for a model or handler; account-bound history needs the bound account and poppy:read. */
+    history(work: WorkRef): Promise<ConversationEvent[]>;
+    /** Account-use gate: call before any account read or tool. Checks accepted authority, then binds the shared ownership once. */
+    requireAccount(work: WorkRef, scopes: readonly string[]): Promise<{
+        accountId: string;
+    }>;
+    reply(work: WorkRef, outputId: string, message: Message): Promise<void>;
+    /** Spec 7.11: asks the Personal Agent to sign in or grant these scopes. Uses no account, so it still publishes after revocation. */
+    requestAuthorization(work: WorkRef, outputId: string, scopes: readonly string[]): Promise<void>;
+    /** Spec 7.10: asks to talk with the User directly; status and responder are unchanged. */
+    requestUser(work: WorkRef, outputId: string, reason: string): Promise<void>;
+    finish(work: WorkRef, outcome: 'completed' | 'suspended' | 'failed'): Promise<void>;
+    /** The company asks for a person on its own: this attempt ends and the conversation is queued. */
+    handoff(work: WorkRef): Promise<void>;
+    /** The company closes the conversation (and its open Direct Conversation); idempotent. */
+    close(work: WorkRef): Promise<void>;
+    /** A person joins: automated work is fenced and the returned claim publishes with sender human. Renew it within operatorLeaseMs. */
+    joinHuman(operator: unknown, conversationId: string): Promise<WorkClaim>;
+    /** Nobody can join a queued conversation: the agent says why and the conversation leaves the queue. No-op unless queued. */
+    noHumanAvailable(operator: unknown, conversationId: string, reason: string): Promise<void>;
+    /** The person hands back to automation; their claim stops working. No-op unless a person is responding. */
+    returnToAgent(operator: unknown, conversationId: string): Promise<void>;
+}
+export declare class PublicationError extends Error {
+    readonly code: 'stale_work' | 'output_conflict';
+    constructor(code: 'stale_work' | 'output_conflict');
+}
+export declare function initialConversationState(): ConversationStoreState;
+/** For the host's reset transaction: a fresh state with a new generation, so every old fence is stale. */
+export declare function resetConversationState(draft: ConversationStoreState): void;
+export declare function createConversationService(options: ConversationOptions): ConversationService;