@poppykit/server 0.4.0 → 0.5.0

package/dist/protocol/session.js

@@ -0,0 +1,93 @@
+import { createHash } from 'node:crypto';
+import { calculateJwkThumbprint, compactVerify, createLocalJWKSet, decodeProtectedHeader, errors, importJWK } from 'jose';
+import { id, object, parseJson, string, ValidationError } from './wire.js';
+import { validateClientId } from '../network/discovery.js';
+import { secureUrl } from '../network/transport.js';
+const COMPACT = /^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$/;
+const PRIVATE = ['d', 'p', 'q', 'dp', 'dq', 'qi', 'oth', 'k'];
+const hash = (value) => createHash('sha256').update(value).digest('base64url');
+function unique(jwt) {
+    if (!COMPACT.test(jwt))
+        throw new ValidationError('session.jwt');
+    for (const segment of jwt.split('.').slice(0, 2))
+        parseJson(Buffer.from(segment, 'base64url').toString('utf8'));
+}
+function timestamp(value) {
+    if (!Number.isSafeInteger(value) || value < 0)
+        throw new ValidationError('session.time');
+    return value;
+}
+function bounded(value, field) {
+    const result = string(value, field);
+    if (result.length > 256)
+        throw new ValidationError(field);
+    return result;
+}
+export function sessionRequestUrl(value) {
+    const url = secureUrl(value);
+    return `${url.origin}${url.pathname}`;
+}
+export function parseSessionClaims(value) {
+    const claims = object(value, 'session');
+    validateClientId(string(claims.iss, 'session.iss'));
+    secureUrl(string(claims.aud, 'session.aud'));
+    id(claims.sid, 'session.sid');
+    bounded(claims.sub, 'session.sub');
+    if ('agent_id' in claims)
+        bounded(claims.agent_id, 'session.agent_id');
+    string(claims.htm, 'session.htm');
+    const htu = string(claims.htu, 'session.htu');
+    if (htu.includes('?') || htu.includes('#'))
+        throw new ValidationError('session.htu');
+    secureUrl(htu);
+    timestamp(claims.iat);
+    const jti = bounded(claims.jti, 'session.jti');
+    if (jti.length < 16)
+        throw new ValidationError('session.jti');
+    if ('ath' in claims)
+        string(claims.ath, 'session.ath');
+    return claims;
+}
+/** Verifies identity only. The resource must separately admit/continue the client_id + sid under its store fence. */
+export async function verifySessionJwt(jwt, expected) {
+    if (!jwt || jwt.length > 32768)
+        throw new ValidationError('session.jwt');
+    unique(jwt);
+    const header = decodeProtectedHeader(jwt);
+    if (header.typ !== 'poppy-session+jwt' || header.alg !== 'ES256' || typeof header.kid !== 'string' || typeof header.pap_dlg !== 'string')
+        throw new ValidationError('session.header');
+    const claims = parseSessionClaims(parseJson(Buffer.from(jwt.split('.')[1], 'base64url').toString('utf8')));
+    const delegation = header.pap_dlg;
+    unique(delegation);
+    const delegatedHeader = decodeProtectedHeader(delegation);
+    if (delegatedHeader.typ !== 'pap-delegation+jwt' || typeof delegatedHeader.alg !== 'string' || !['ES256', 'PS384'].includes(delegatedHeader.alg) || typeof delegatedHeader.kid !== 'string')
+        throw new ValidationError('delegation.header');
+    const client = await expected.metadata.resolveClient(claims.iss);
+    let jwks = await expected.metadata.resolveJwks(client.jwks_uri);
+    let verified;
+    try {
+        verified = await compactVerify(delegation, createLocalJWKSet(jwks), { algorithms: ['ES256', 'PS384'] });
+    }
+    catch (error) {
+        if (!(error instanceof errors.JWKSNoMatchingKey))
+            throw error;
+        jwks = await expected.metadata.resolveJwks(client.jwks_uri, { refresh: true });
+        verified = await compactVerify(delegation, createLocalJWKSet(jwks), { algorithms: ['ES256', 'PS384'] });
+    }
+    const delegated = object(parseJson(new TextDecoder().decode(verified.payload)), 'delegation');
+    const issued = timestamp(delegated.iat), expires = timestamp(delegated.exp), at = expected.nowMs / 1000;
+    bounded(delegated.jti, 'delegation.jti');
+    if (delegated.jti.length < 16 || delegated.iss !== claims.iss || expires <= issued || expires - issued > 86400 || expires <= at || issued > at + 30)
+        throw new ValidationError('delegation.claims');
+    const key = object(object(delegated.cnf, 'delegation.cnf').jwk, 'delegation.key');
+    if (key.kty !== 'EC' || key.crv !== 'P-256' || PRIVATE.some(name => name in key) || typeof key.x !== 'string' || typeof key.y !== 'string')
+        throw new ValidationError('delegation.key');
+    if (header.kid !== await calculateJwkThumbprint(key) || claims.iat > expires)
+        throw new ValidationError('session.key');
+    await compactVerify(jwt, await importJWK(key, 'ES256'), { algorithms: ['ES256'] });
+    if (claims.aud !== expected.companyId || claims.htm !== expected.method || sessionRequestUrl(claims.htu) !== sessionRequestUrl(expected.url) || claims.iat < at - 60 || claims.iat > at + 30)
+        throw new ValidationError('session.binding');
+    if (expected.accessToken === undefined ? 'ath' in claims : claims.ath !== hash(expected.accessToken) || expected.tokenClientId !== claims.iss)
+        throw new ValidationError('session.token');
+    return { ...claims, delegationExpiresAt: expires * 1000 };
+}

package/dist/protocol/sse.d.ts

@@ -12,4 +12,5 @@ export declare function parseEventStream(body: ReadableStream<Uint8Array>, optio
     maxFrameBytes?: number;
     maxStreamBytes?: number;
     signal?: AbortSignal;
+    operations?: boolean;
 }): AsyncGenerator<StreamFrame>;

package/dist/protocol/sse.js

@@ -18,7 +18,7 @@ export async function* parseEventStream(body, options = {}) {
             const delta = object(value);
             return { kind: 'delta', messageId: id(delta.message_id, 'message_id'), text: string(delta.text, 'text', false) };
         }
-        const event = parseEvent(value);
+        const event = parseEvent(value, options.operations);
         if (eventId !== event.id)
             throw new ValidationError('sse.id');
         return { kind: 'event', event };

package/dist/protocol/wire.d.ts

@@ -1,3 +1,4 @@
+import type { BusinessOperation, OperationApproval } from './operations.js';
 export type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
@@ -19,6 +20,8 @@ export interface Message {
     text?: string;
     data?: JsonObject;
     context?: JsonObject;
+    operation?: BusinessOperation;
+    approval?: OperationApproval;
     [key: string]: unknown;
 }
 export interface RecordedMessage extends Message {
@@ -67,7 +70,7 @@ export interface EventPage extends ConversationState {
 export interface TokenResponse {
     access_token: string;
     token_type: 'DPoP' | 'Bearer';
-    expires_in: number;
+    expires_in?: number;
     scope?: string;
     refresh_token?: string;
     refresh_token_expires_in?: number;
@@ -93,11 +96,12 @@ export declare function id(value: unknown, field: string): string;
 export declare function parseMessage(value: unknown, options?: {
     recorded?: boolean;
     company?: boolean;
+    operations?: boolean;
 }): Message | RecordedMessage;
-export declare function parseConversationRequest(value: unknown): ConversationRequest;
+export declare function parseConversationRequest(value: unknown, operations?: boolean): ConversationRequest;
 export declare function parseConversationState(value: unknown): ConversationState;
-export declare function parseEvent(value: unknown): ConversationEvent;
-export declare function parseEventPage(value: unknown, requestCursor?: string): EventPage;
+export declare function parseEvent(value: unknown, operations?: boolean): ConversationEvent;
+export declare function parseEventPage(value: unknown, requestCursor?: string, operations?: boolean): EventPage;
 export declare function parseTokenResponse(value: unknown): TokenResponse;
 export declare function parseProtocolError(value: unknown): ProtocolErrorBody;
 export declare function parseReadOptions(url: URL, maxWaitSeconds: number): {

package/dist/protocol/wire.js

@@ -1,3 +1,4 @@
+import { parseBusinessOperation, parseOperationApproval } from './operations.js';
 export class ValidationError extends Error {
     field;
     constructor(field) {
@@ -70,7 +71,18 @@ export function parseMessage(value, options = {}) {
             throw new ValidationError('message.author.image');
         }
     }
-    if (!['text', 'data', 'context'].some(key => key in message))
+    const company = options.company || (options.recorded && message.role === 'company');
+    if ('operation' in message) {
+        if (!company || !options.operations)
+            throw new ValidationError('message.operation');
+        message.operation = parseBusinessOperation(message.operation);
+    }
+    if ('approval' in message) {
+        if (company || !options.operations)
+            throw new ValidationError('message.approval');
+        message.approval = parseOperationApproval(message.approval);
+    }
+    if (!['text', 'data', 'context', ...(options.operations ? [company ? 'operation' : 'approval'] : [])].some(key => key in message))
         throw new ValidationError('message.content');
     if ('text' in message)
         string(message.text, 'message.text', false);
@@ -109,20 +121,24 @@ export function parseMessage(value, options = {}) {
     }
     return message;
 }
-export function parseConversationRequest(value) {
+export function parseConversationRequest(value, operations = false) {
     const request = object(value);
     if ('parent_conversation_id' in request)
         id(request.parent_conversation_id, 'parent_conversation_id');
-    return { ...request, message: parseMessage(request.message) };
+    return { ...request, message: parseMessage(request.message, { operations }) };
 }
 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');
+    string(state.status, 'status');
+    string(state.responder, 'responder');
+    if (!['working', 'idle', 'queued', 'closed'].includes(state.status))
+        state.status = 'working';
+    if (!['agent', 'human'].includes(state.responder))
+        state.responder = 'human';
     return state;
 }
-export function parseEvent(value) {
+export function parseEvent(value, operations = false) {
     const event = object(value, 'event');
     id(event.id, 'event.id');
     string(event.type, 'event.type');
@@ -138,12 +154,14 @@ export function parseEvent(value) {
         throw new ValidationError('event.created_at');
     switch (event.type) {
         case 'message':
-            parseMessage(event.message, { recorded: true });
+            parseMessage(event.message, { recorded: true, operations });
             break;
-        case 'state':
-            member(event.status, ['working', 'idle', 'queued', 'closed'], 'event.status');
-            member(event.responder, ['agent', 'human'], 'event.responder');
+        case 'state': {
+            const state = parseConversationState({ conversation_id: 'state', status: event.status, responder: event.responder });
+            event.status = state.status;
+            event.responder = state.responder;
             break;
+        }
         case 'authorization':
             member(event.error, ['insufficient_scope'], 'event.error');
             if (!/^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/.test(string(event.scope, 'event.scope')))
@@ -159,11 +177,11 @@ export function parseEvent(value) {
     }
     return event;
 }
-export function parseEventPage(value, requestCursor) {
+export function parseEventPage(value, requestCursor, operations = false) {
     const page = parseConversationState(value);
     if (!Array.isArray(page.events))
         throw new ValidationError('events');
-    page.events.forEach(parseEvent);
+    page.events.forEach(event => parseEvent(event, operations));
     member(page.has_more, [true, false], 'has_more');
     if (page.cursor === null) {
         if (requestCursor !== undefined || page.events.length || page.has_more)
@@ -172,7 +190,7 @@ export function parseEventPage(value, requestCursor) {
     else {
         string(page.cursor, 'cursor');
         const expected = page.events.length ? page.events.at(-1).id : requestCursor;
-        if (expected !== undefined && page.cursor !== expected)
+        if (expected === undefined || page.cursor !== expected)
             throw new ValidationError('cursor');
     }
     return page;
@@ -185,8 +203,12 @@ export function parseTokenResponse(value) {
         if (scope !== '' && (!/^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/.test(scope) || new Set(scope.split(' ')).size !== scope.split(' ').length))
             throw new ValidationError('scope');
     }
-    member(token.token_type, ['DPoP', 'Bearer'], 'token_type');
-    positive(token.expires_in, 'expires_in');
+    const type = string(token.token_type, 'token_type').toLowerCase();
+    if (type !== 'bearer' && type !== 'dpop')
+        throw new ValidationError('token_type');
+    token.token_type = type === 'bearer' ? 'Bearer' : 'DPoP';
+    if ('expires_in' in token && (!Number.isSafeInteger(token.expires_in) || token.expires_in < 0))
+        throw new ValidationError('expires_in');
     if ('refresh_token' in token)
         string(token.refresh_token, 'refresh_token');
     if ('refresh_token_expires_in' in token)

package/dist/reference-auth/index.d.ts

@@ -1,7 +1,6 @@
 import type { MetadataResolver } from '../network/discovery.js';
 import type { IssuerStore, IssuerSelection } from './store.js';
 import type { AuthorityCoordinator, ExternalAuthorityAdapter } from '../auth/authority.js';
-import type { BrowserSession, BrowserSessionAuthority } from '../browser.js';
 export type { IssuerStore, IssuerSelection };
 export { createMetadataResolver } from '../network/discovery.js';
 export { createNodeTransport } from '../network/transport.js';
@@ -26,6 +25,8 @@ interface GrantRecord {
     previousHash: string;
 }
 interface AccessTokenRecord {
+    clientId?: string;
+    accountId?: string;
     sessionId: string;
     grantId: string | null;
     scopes: string[];
@@ -34,7 +35,7 @@ interface AccessTokenRecord {
     expiresAt: number;
 }
 interface AuthorizationRecord {
-    sessionKey: string;
+    sessionKey: string | null;
     clientId: string;
     redirectUri: string;
     state: string;
@@ -49,7 +50,7 @@ interface AuthorizationRecord {
     };
 }
 interface CodeRecord {
-    sessionKey: string;
+    sessionKey: string | null;
     clientId: string;
     redirectUri: string;
     codeChallenge: string;
@@ -74,9 +75,11 @@ export type SignInRecord = {
     accountId?: string;
 } | {
     kind: 'mediated';
+    resource?: string | null;
+    grantId?: string;
     clientId: string;
-    userId: string;
-    sessionId: string;
+    userId?: string;
+    sessionId?: string;
     scopes: string[];
     expiresAt: number;
     status: 'verifying' | 'pending' | 'failed' | 'expired' | 'complete';
@@ -101,12 +104,10 @@ export type SignInRecord = {
 };
 export interface MediatedContext {
     clientId: string;
-    userId: string;
-    sessionId: string;
     issuer: string;
 }
 export interface MediatedOptions {
-    endpoint: string;
+    endpoint?: string;
     scopes: string[];
     fields: {
         name: string;
@@ -136,7 +137,7 @@ export interface IssuerState {
         pending: number;
         pendingForClient: number;
     };
-    version: 3 | 4;
+    version: 3 | 4 | 5;
     generation: string;
     sessions: Record<string, SessionRecord>;
     sessionKeys: Record<string, string>;
@@ -200,12 +201,6 @@ export type AuthorizationDecision = {
     denied: true;
 };
 export interface ReferenceIssuer {
-    browserSessions: BrowserSessionAuthority;
-    sessionForKey(binding: {
-        clientId: string;
-        userId: string;
-        sessionKey: string;
-    }): Promise<BrowserSession>;
     token(request: Request): Promise<Response>;
     revoke(request: Request): Promise<Response>;
     beginAuthorization(request: Request, browserBinding: string): Promise<AuthorizationView>;
@@ -213,7 +208,6 @@ export interface ReferenceIssuer {
     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>;