@poppykit/server 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/reference-auth/index.d.ts

@@ -0,0 +1,209 @@
+import type { MetadataResolver } from '../network/discovery.js';
+import type { IssuerStore, IssuerSelection } from './store.js';
+import type { AuthorityCoordinator, ExternalAuthorityAdapter } from '../auth/authority.js';
+import type { BrowserSessionAuthority } from '../browser.js';
+export type { IssuerStore, IssuerSelection };
+export { createMetadataResolver } from '../network/discovery.js';
+export { createNodeTransport } from '../network/transport.js';
+interface SessionRecord {
+    clientId: string;
+    userId: string;
+    version: number;
+    createdAt: number;
+    expiresAt: number;
+    accountId: string | null;
+    grantId: string | null;
+}
+interface GrantRecord {
+    clientId: string;
+    userId: string;
+    accountId: string;
+    scopes: string[];
+    expiresAt: number;
+    revoked: boolean;
+    refreshHash: string;
+    previousHash: string;
+}
+interface AccessTokenRecord {
+    sessionId: string;
+    grantId: string | null;
+    scopes: string[];
+    resource: string | null;
+    jkt: string;
+    expiresAt: number;
+}
+interface AuthorizationRecord {
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    codeChallenge: string;
+    scopes: string[];
+    browserHash: string;
+    expiresAt: number;
+    revision: number;
+}
+interface CodeRecord {
+    clientId: string;
+    redirectUri: string;
+    codeChallenge: string;
+    accountId: string;
+    scopes: string[];
+    expiresAt: number;
+    grantId: string | null;
+    revision: number;
+}
+export type SignInRecord = {
+    kind: 'device';
+    clientId: string;
+    scopes: string[];
+    expiresAt: number;
+    deviceHash: string;
+    status: 'pending' | 'approved' | 'denied' | 'consumed';
+    nextPollAt: number;
+    intervalMs: number;
+    revision: number;
+    browserHash?: string;
+    accountId?: string;
+} | {
+    kind: 'mediated';
+    clientId: string;
+    userId: string;
+    sessionId: string;
+    scopes: string[];
+    expiresAt: number;
+    status: 'verifying' | 'pending' | 'failed' | 'expired' | 'complete';
+    attempts: number;
+    executionId: string;
+    revision: number;
+    accountId?: string;
+    challengeId?: string;
+    sentTo?: string;
+} | {
+    kind: 'attempts';
+    clientId: string;
+    sessionId?: string;
+    expiresAt: number;
+    count: number;
+} | {
+    kind: 'revision';
+    clientId: string;
+    accountId?: string;
+    expiresAt: number;
+    revision: number;
+};
+export interface MediatedContext {
+    clientId: string;
+    userId: string;
+    sessionId: string;
+    issuer: string;
+}
+export interface MediatedOptions {
+    endpoint: string;
+    scopes: string[];
+    fields: {
+        name: string;
+        label: string;
+        secret: boolean;
+    }[];
+    authenticate(credentials: Readonly<Record<string, string>>, context: MediatedContext): Promise<{
+        accountId: string;
+        scopes?: string[];
+        challenge?: {
+            id: string;
+            sentTo: string;
+        };
+    } | null>;
+    verifyCode(input: {
+        challengeId: string;
+        code: string;
+    }, context: MediatedContext): Promise<boolean>;
+    maxCodeAttempts?: number;
+    maxAttemptsPerMinute?: number;
+    maxClientAttemptsPerMinute?: number;
+}
+export interface IssuerState {
+    limits?: {
+        sessions: number;
+        earliestSessionExpiry: number;
+        pending: number;
+        pendingForClient: number;
+    };
+    version: 3;
+    generation: string;
+    sessions: Record<string, SessionRecord>;
+    grants: Record<string, GrantRecord>;
+    refreshTokens: Record<string, string>;
+    authorizations: Record<string, AuthorizationRecord>;
+    codes: Record<string, CodeRecord>;
+    signIns: Record<string, SignInRecord>;
+    accessTokens: Record<string, AccessTokenRecord>;
+    replay: Record<string, number>;
+    nonces: {
+        value: string;
+        expiresAt: number;
+    }[];
+}
+export interface ReferenceIssuerOptions {
+    issuer: string;
+    tokenEndpoint: string;
+    revocationEndpoint: string;
+    authorizationEndpoint?: string;
+    poppyDomains: string[];
+    directScopes: string[];
+    resources?: string[];
+    mcpResources?: {
+        url: string;
+        dpop: boolean;
+    }[];
+    metadata: MetadataResolver;
+    store: IssuerStore;
+    coordinator: AuthorityCoordinator;
+    now: () => number;
+    tokenLifetimeSeconds?: number;
+    accountLifetimeSeconds?: number;
+    requireDpopNonce?: boolean;
+    maxPendingAuthorizations?: number;
+    maxPendingAuthorizationsPerClient?: number;
+    maxSessionsPerClient?: number;
+    device?: {
+        endpoint: string;
+        verificationUri: string;
+        scopes: string[];
+        intervalSeconds?: number;
+    };
+    mediated?: MediatedOptions;
+}
+export interface AuthorizationView {
+    id: string;
+    clientId: string;
+    clientName: string;
+    scopes: string[];
+    expiresAt: number;
+}
+export type AuthorizationDecision = {
+    accountId: string;
+    scopes: string[];
+} | {
+    denied: true;
+};
+export interface ReferenceIssuer {
+    browserSessions: BrowserSessionAuthority;
+    token(request: Request): Promise<Response>;
+    revoke(request: Request): Promise<Response>;
+    beginAuthorization(request: Request, browserBinding: string): Promise<AuthorizationView>;
+    completeAuthorization(id: string, browserBinding: string, decision: AuthorizationDecision): Promise<URL>;
+    deviceAuthorization(request: Request): Promise<Response>;
+    beginDeviceAuthorization(userCode: string, browserBinding: string): Promise<AuthorizationView>;
+    completeDeviceAuthorization(userCode: string, browserBinding: string, decision: AuthorizationDecision): Promise<void>;
+    mediatedSignIn(request: Request): Promise<Response>;
+    authorizationMetadata(): Record<string, unknown>;
+    authority: ExternalAuthorityAdapter;
+    disconnect(clientId: string, accountId: string): Promise<void>;
+}
+export declare class AuthorizationError extends Error {
+    readonly code: string;
+    readonly redirectTo?: URL | undefined;
+    constructor(code: string, redirectTo?: URL | undefined);
+}
+export declare function initialIssuerState(): IssuerState;
+export declare function createReferenceIssuer(options: ReferenceIssuerOptions): ReferenceIssuer;