@poppykit/server 0.3.1 → 0.5.0

package/dist/protocol/session.d.ts

@@ -0,0 +1,28 @@
+import type { MetadataResolver } from '../network/discovery.js';
+export interface SessionClaims {
+    iss: string;
+    aud: string;
+    sid: string;
+    sub: string;
+    agent_id?: string;
+    htm: string;
+    htu: string;
+    iat: number;
+    jti: string;
+    ath?: string;
+}
+export interface VerifiedSession extends SessionClaims {
+    delegationExpiresAt: number;
+}
+export declare function sessionRequestUrl(value: string): string;
+export declare function parseSessionClaims(value: unknown): SessionClaims;
+/** Verifies identity only. The resource must separately admit/continue the client_id + sid under its store fence. */
+export declare function verifySessionJwt(jwt: string | null, expected: {
+    companyId: string;
+    method: string;
+    url: string;
+    nowMs: number;
+    metadata: MetadataResolver;
+    accessToken?: string;
+    tokenClientId?: string;
+}): Promise<VerifiedSession>;

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,17 +1,27 @@
+import type { BusinessOperation, OperationApproval } from './operations.js';
 export type Json = null | boolean | number | string | Json[] | {
     [key: string]: Json;
 };
 export type JsonObject = {
     [key: string]: Json;
 };
-export type Sender = 'agent' | 'human';
+export type AuthorType = 'agent' | 'human';
+export interface Author {
+    type: AuthorType;
+    id?: string;
+    name?: string;
+    image?: string;
+    [key: string]: unknown;
+}
 export type Status = 'working' | 'idle' | 'queued' | 'closed';
 export interface Message {
     id: string;
-    sender: Sender;
+    author: Author;
     text?: string;
     data?: JsonObject;
     context?: JsonObject;
+    operation?: BusinessOperation;
+    approval?: OperationApproval;
     [key: string]: unknown;
 }
 export interface RecordedMessage extends Message {
@@ -25,7 +35,7 @@ export interface ConversationRequest {
 export interface ConversationState {
     conversation_id: string;
     status: Status;
-    responder: Sender;
+    responder: AuthorType;
     [key: string]: unknown;
 }
 export interface ConversationEvent {
@@ -40,11 +50,7 @@ export type KnownEvent = (ConversationEvent & {
 }) | (ConversationEvent & {
     type: 'state';
     status: Status;
-    responder: Sender;
-}) | (ConversationEvent & {
-    type: 'authorization';
-    error: 'sign_in_required';
-    scope?: string;
+    responder: AuthorType;
 }) | (ConversationEvent & {
     type: 'authorization';
     error: 'insufficient_scope';
@@ -64,10 +70,8 @@ export interface EventPage extends ConversationState {
 export interface TokenResponse {
     access_token: string;
     token_type: 'DPoP' | 'Bearer';
-    expires_in: number;
-    scope: string;
-    session_id: string;
-    signed_in: boolean;
+    expires_in?: number;
+    scope?: string;
     refresh_token?: string;
     refresh_token_expires_in?: number;
     [key: string]: unknown;
@@ -92,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) {
@@ -50,8 +51,38 @@ function positive(value, 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))
+    const author = object(message.author, 'message.author');
+    member(author.type, ['agent', 'human'], 'message.author.type');
+    if ('sender' in message)
+        throw new ValidationError('message.sender');
+    for (const key of ['id', 'name', 'image'])
+        if (key in author) {
+            if (!options.company && !(options.recorded && message.role === 'company'))
+                throw new ValidationError('message.author.' + key);
+            string(author[key], 'message.author.' + key);
+        }
+    if ('image' in author) {
+        try {
+            const url = new URL(author.image);
+            if (url.protocol !== 'https:' || url.username || url.password)
+                throw 0;
+        }
+        catch {
+            throw new ValidationError('message.author.image');
+        }
+    }
+    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);
@@ -90,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');
@@ -119,16 +154,18 @@ 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, ['sign_in_required', 'insufficient_scope'], 'event.error');
-            if (event.error === 'insufficient_scope' || 'scope' in event)
-                string(event.scope, 'event.scope', false);
+            member(event.error, ['insufficient_scope'], 'event.error');
+            if (!/^[\x21\x23-\x5B\x5D-\x7E]+(?: [\x21\x23-\x5B\x5D-\x7E]+)*$/.test(string(event.scope, 'event.scope')))
+                throw new ValidationError('event.scope');
             break;
         case 'user_requested':
             string(event.reason, 'event.reason', false);
@@ -140,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)
@@ -153,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;
@@ -161,11 +198,17 @@ export function parseEventPage(value, requestCursor) {
 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 ('scope' in token) {
+        const scope = string(token.scope, 'scope', false);
+        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');
+    }
+    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)
@@ -215,6 +258,11 @@ export function parseAssertionClaims(value) {
     const claims = object(value, 'claims');
     for (const key of ['iss', 'sub', 'aud', 'jti'])
         string(claims[key], key);
+    if ('agent_id' in claims) {
+        string(claims.agent_id, 'agent_id');
+        if (claims.agent_id.length > 256)
+            throw new ValidationError('agent_id');
+    }
     // 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');

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

@@ -1,13 +1,13 @@
 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;
+    agentId?: string;
     version: number;
     createdAt: number;
     expiresAt: number;
@@ -25,6 +25,8 @@ interface GrantRecord {
     previousHash: string;
 }
 interface AccessTokenRecord {
+    clientId?: string;
+    accountId?: string;
     sessionId: string;
     grantId: string | null;
     scopes: string[];
@@ -33,6 +35,7 @@ interface AccessTokenRecord {
     expiresAt: number;
 }
 interface AuthorizationRecord {
+    sessionKey: string | null;
     clientId: string;
     redirectUri: string;
     state: string;
@@ -47,6 +50,7 @@ interface AuthorizationRecord {
     };
 }
 interface CodeRecord {
+    sessionKey: string | null;
     clientId: string;
     redirectUri: string;
     codeChallenge: string;
@@ -58,6 +62,7 @@ interface CodeRecord {
 }
 export type SignInRecord = {
     kind: 'device';
+    sessionKey: string | null;
     clientId: string;
     scopes: string[];
     expiresAt: number;
@@ -70,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';
@@ -97,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;
@@ -132,9 +137,10 @@ export interface IssuerState {
         pending: number;
         pendingForClient: number;
     };
-    version: 3;
+    version: 3 | 4 | 5;
     generation: string;
     sessions: Record<string, SessionRecord>;
+    sessionKeys: Record<string, string>;
     grants: Record<string, GrantRecord>;
     refreshTokens: Record<string, string>;
     authorizations: Record<string, AuthorizationRecord>;
@@ -152,8 +158,8 @@ export interface ReferenceIssuerOptions {
     tokenEndpoint: string;
     revocationEndpoint: string;
     authorizationEndpoint?: string;
-    poppyDomains: string[];
-    directScopes: string[];
+    protectedResources: string[];
+    supportedScopes: string[];
     resources?: string[];
     mcpResources?: {
         url: string;
@@ -177,7 +183,6 @@ export interface ReferenceIssuerOptions {
     device?: {
         endpoint: string;
         verificationUri: string;
-        scopes: string[];
         intervalSeconds?: number;
     };
     mediated?: MediatedOptions;
@@ -196,7 +201,6 @@ export type AuthorizationDecision = {
     denied: true;
 };
 export interface ReferenceIssuer {
-    browserSessions: BrowserSessionAuthority;
     token(request: Request): Promise<Response>;
     revoke(request: Request): Promise<Response>;
     beginAuthorization(request: Request, browserBinding: string): Promise<AuthorizationView>;
@@ -204,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>;
@@ -214,5 +217,7 @@ export declare class AuthorizationError extends Error {
     readonly redirectTo?: URL | undefined;
     constructor(code: string, redirectTo?: URL | undefined);
 }
+/** Run once over the complete namespace, under the adapter's writer lock. */
+export declare function upgradeIssuerState(state: IssuerState): void;
 export declare function initialIssuerState(): IssuerState;
 export declare function createReferenceIssuer(options: ReferenceIssuerOptions): ReferenceIssuer;