@namzu/sdk 49.0.0 → 50.0.0

package/src/pals/channels/routing.ts

@@ -0,0 +1,197 @@
+import { isDeepStrictEqual } from 'node:util'
+import { z } from 'zod'
+import type { SessionId } from '../../types/ids/index.js'
+import type { InboundDeliveryRef } from '../../types/message/inbound-delivery.js'
+import { isEntityId } from '../../utils/id.js'
+import { ingressInboxSchema } from '../communication/ingress-schema.js'
+import type { PalChannelIntent } from '../communication/ingress-types.js'
+import { PAL_CHANNEL_NAMESPACE, ingressMessageRef } from '../communication/ingress-types.js'
+import { addressSchema, freezeCommunicationValue, label } from '../communication/schema.js'
+import { verifyIngressRecorded } from '../communication/verify.js'
+import { captureConnection, nativeTuple, verifiedActionSchema } from './schema.js'
+import type {
+	PalChannelExecutionContext,
+	PalChannelResolvedRoute,
+	PalChannelRouterOptions,
+	PalChannelVerifiedAction,
+} from './types.js'
+
+const contextSchema = z
+	.object({
+		recipient: addressSchema,
+		sessionId: z.custom<SessionId>((value) => isEntityId(value, 'session')),
+		profileRevision: z.number().int().positive().safe(),
+	})
+	.strict()
+const refSchema = z
+	.object({
+		namespace: z.literal(PAL_CHANNEL_NAMESPACE),
+		id: z.string().regex(/^[a-f0-9]{64}$/),
+		digest: z.string().regex(/^[a-f0-9]{64}$/),
+	})
+	.strict()
+
+/** Resolves original authenticated destinations. It does not imply remote delivery. */
+export class PalChannelRouter {
+	private readonly options: PalChannelRouterOptions
+	private readonly connection
+	constructor(options: PalChannelRouterOptions) {
+		if (typeof options.verify !== 'function' || typeof options.authorize !== 'function')
+			throw new Error('Channel routing requires trusted verification and current authorization.')
+		this.options = Object.freeze({ ...options })
+		this.connection = captureConnection(options.connection)
+	}
+	private assertRecipient(context: PalChannelExecutionContext) {
+		if (context.recipient.tenantId !== this.connection.tenantId)
+			throw new Error('Foreign channel response tenant.')
+		const pal = this.options.pals.get(context.recipient.palId)
+		if (!pal || pal.paused) throw new Error('Channel response Pal is paused or unavailable.')
+		return this.options.pals.getRevision(pal.id, context.profileRevision)
+	}
+	private async recorded(
+		input: InboundDeliveryRef,
+		context: PalChannelExecutionContext,
+		signal: AbortSignal,
+	) {
+		const ref = freezeCommunicationValue(refSchema.parse(input))
+		const definition = this.assertRecipient(context)
+		const snapshot = await this.options.store.readIngress(context.recipient)
+		const found = snapshot?.messages.find((message) => message.id === ref.id)
+		if (!found) throw new Error('Channel response does not name an accepted delivery.')
+		const message = freezeCommunicationValue(ingressInboxSchema.parse(found))
+		if (
+			!('kind' in message) ||
+			message.kind !== 'channel' ||
+			message.phase !== 'recorded' ||
+			!message.receipt ||
+			!isDeepStrictEqual(ingressMessageRef(message), ref)
+		)
+			throw new Error('Channel response requires the exact recorded channel delivery.')
+		if (
+			message.source.tenantId !== this.connection.tenantId ||
+			message.source.provider !== this.connection.provider ||
+			message.source.connectionId !== this.connection.connectionId ||
+			message.source.externalTenantId !== this.connection.externalTenantId
+		)
+			throw new Error('Channel response belongs to another connection.')
+		if (!isDeepStrictEqual(nativeTuple(message.source), nativeTuple(message.routeKey)))
+			throw new Error('Channel message source does not match its original native route.')
+		const binding = await this.options.store.routeIngress(message.routeKey)
+		if (
+			!binding ||
+			binding.id !== message.routeId ||
+			binding.phase !== 'active' ||
+			binding.sessionId !== context.sessionId ||
+			binding.profileRevision !== context.profileRevision ||
+			binding.key.recipient.palId !== context.recipient.palId ||
+			binding.key.recipient.tenantId !== context.recipient.tenantId
+		)
+			throw new Error('Channel response belongs to another Pal conversation or profile.')
+		signal.throwIfAborted()
+		await verifyIngressRecorded(message, message.receipt, {
+			binding,
+			definition,
+			access: await this.options.host.openConversation(binding, signal),
+		})
+		signal.throwIfAborted()
+		this.assertRecipient(context)
+		return { ...message, receipt: message.receipt }
+	}
+	private async resolve(
+		input: InboundDeliveryRef,
+		context: PalChannelExecutionContext,
+		signal: AbortSignal,
+		action?: PalChannelVerifiedAction,
+	): Promise<PalChannelResolvedRoute> {
+		const message = await this.recorded(input, context, signal)
+		if (
+			action &&
+			(action.externalTenantId !== message.source.externalTenantId ||
+				!isDeepStrictEqual(
+					nativeTuple({
+						...action,
+						provider: this.connection.provider,
+						connectionId: this.connection.connectionId,
+					}),
+					nativeTuple(message.source),
+				))
+		)
+			throw new Error('Channel action belongs to another native conversation, channel or thread.')
+		const allowed = await this.options.authorize(
+			freezeCommunicationValue({
+				phase: action ? 'action' : 'reply',
+				message: message as PalChannelIntent,
+				context,
+				actorId: action?.actorId ?? message.source.actorId,
+				...(action ? { action } : {}),
+			}),
+		)
+		signal.throwIfAborted()
+		if (allowed.allow !== true) throw new Error(`Channel routing refused: ${allowed.reason}`)
+		this.assertRecipient(context)
+		return freezeCommunicationValue({
+			connection: this.connection,
+			identity: {
+				provider: message.source.provider,
+				connectionId: message.source.connectionId,
+				externalTenantId: message.source.externalTenantId,
+				nativeConversationId: message.source.nativeConversationId,
+				nativeChannelId: message.source.nativeChannelId,
+				nativeThreadId: message.source.nativeThreadId,
+			},
+			deliveryRef: {
+				namespace: PAL_CHANNEL_NAMESPACE,
+				id: message.id,
+				digest: message.digest,
+			},
+			recordedReceipt: message.receipt,
+			eventActorId: message.source.actorId,
+			currentActorId: action?.actorId ?? message.source.actorId,
+			context,
+		})
+	}
+	async replyRoute(
+		input: InboundDeliveryRef,
+		execution: PalChannelExecutionContext,
+		signal: AbortSignal = new AbortController().signal,
+	) {
+		const context = freezeCommunicationValue(contextSchema.parse(execution))
+		const ref = refSchema.parse(input)
+		signal.throwIfAborted()
+		return this.resolve(ref, context, signal)
+	}
+	async actionRoute(
+		raw: unknown,
+		execution: PalChannelExecutionContext,
+		signal: AbortSignal = new AbortController().signal,
+	) {
+		const context = freezeCommunicationValue(contextSchema.parse(execution))
+		signal.throwIfAborted()
+		const action = freezeCommunicationValue(
+			verifiedActionSchema.parse(
+				await this.options.verify(structuredClone(raw), this.connection, signal),
+			),
+		)
+		signal.throwIfAborted()
+		const route = await this.resolve(action.deliveryRef, context, signal, action)
+		return freezeCommunicationValue({ route, action })
+	}
+	async executeAction(
+		raw: unknown,
+		execution: PalChannelExecutionContext,
+		signal: AbortSignal = new AbortController().signal,
+	) {
+		if (!this.options.actions)
+			throw new Error('Channel action execution is unsupported by this host.')
+		const context = await this.actionRoute(raw, execution, signal)
+		signal.throwIfAborted()
+		this.assertRecipient(context.route.context)
+		const result = await this.options.actions.execute(context, signal)
+		return freezeCommunicationValue(
+			z
+				.object({ status: z.enum(['applied', 'rejected']), receiptId: label })
+				.strict()
+				.parse(result),
+		)
+	}
+}

package/src/pals/channels/schema.ts

@@ -0,0 +1,108 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import { channelRouteKeySchema, channelSourceSchema } from '../communication/ingress-schema.js'
+import type { PalChannelIdentity } from '../communication/ingress-types.js'
+import { addressSchema, freezeCommunicationValue, hash, label } from '../communication/schema.js'
+import type { PalChannelConnection, PalChannelRouteDecision } from './types.js'
+
+export const connectionSchema = z
+	.object({
+		tenantId: addressSchema.shape.tenantId,
+		provider: label,
+		connectionId: label,
+		externalTenantId: label,
+	})
+	.strict()
+const verifiedIdentity = {
+	externalTenantId: label,
+	nativeConversationId: label,
+	nativeChannelId: label.nullable(),
+	nativeThreadId: label.nullable(),
+	actorId: label,
+	eventId: label,
+}
+export const verifiedMessageSchema = z
+	.object({
+		...verifiedIdentity,
+		kind: z.literal('message'),
+		body: z
+			.string()
+			.min(1)
+			.max(32_000)
+			.refine((value) => !value.includes('\0')),
+	})
+	.strict()
+export const verifiedActionSchema = z
+	.object({
+		...verifiedIdentity,
+		kind: z.literal('action'),
+		deliveryRef: z
+			.object({
+				namespace: z.literal('namzu-pal-channel/1'),
+				id: z.string().regex(/^[a-f0-9]{64}$/),
+				digest: z.string().regex(/^[a-f0-9]{64}$/),
+			})
+			.strict(),
+		actionId: label,
+		payloadDigest: z.string().regex(/^[a-f0-9]{64}$/),
+		payload: z
+			.string()
+			.min(1)
+			.max(32_000)
+			.refine((value) => !value.includes('\0')),
+	})
+	.strict()
+	.refine(
+		(value) => createHash('sha256').update(value.payload).digest('hex') === value.payloadDigest,
+		'Channel action payload does not match its authenticated digest.',
+	)
+export const routeDecisionSchema = z
+	.object({
+		v: z.literal(1),
+		revision: z.literal(1),
+		identity: channelRouteKeySchema.omit({
+			v: true,
+			kind: true,
+			recipient: true,
+		}),
+		recipient: addressSchema,
+		profileRevision: z.number().int().positive().safe(),
+	})
+	.strict()
+
+export function captureConnection(input: PalChannelConnection): PalChannelConnection {
+	return freezeCommunicationValue(connectionSchema.parse(input))
+}
+
+export function checkedIdentity(connection: PalChannelConnection, event: unknown) {
+	const source = channelSourceSchema.parse(event)
+	if (
+		source.tenantId !== connection.tenantId ||
+		source.provider !== connection.provider ||
+		source.connectionId !== connection.connectionId ||
+		source.externalTenantId !== connection.externalTenantId
+	)
+		throw new Error('Channel identity does not belong to the authenticated connection.')
+	return freezeCommunicationValue(source)
+}
+
+export function nativeTuple(identity: PalChannelIdentity): readonly unknown[] {
+	return [
+		identity.provider,
+		identity.connectionId,
+		identity.externalTenantId,
+		identity.nativeConversationId,
+		identity.nativeChannelId,
+		identity.nativeThreadId,
+	]
+}
+
+export function decisionId(
+	decision: Pick<PalChannelRouteDecision, 'identity' | 'recipient'>,
+): string {
+	return hash([1, decision.recipient.tenantId, nativeTuple(decision.identity)])
+}
+
+export function checkedDecision(input: unknown): PalChannelRouteDecision {
+	return freezeCommunicationValue(routeDecisionSchema.parse(input))
+}

package/src/pals/channels/types.ts

@@ -0,0 +1,156 @@
+import type { SessionId } from '../../types/ids/index.js'
+import type {
+	InboundDeliveryReceipt,
+	InboundDeliveryRef,
+} from '../../types/message/inbound-delivery.js'
+import type {
+	PalChannelIdentity,
+	PalChannelIntent,
+	PalChannelSource,
+	PalIngressAcceptanceReceipt,
+	PalIngressHostPort,
+	PalIngressStore,
+} from '../communication/ingress-types.js'
+import type { PalAddress, PalMessageAuthorization } from '../communication/types.js'
+import type { PalStore } from '../types.js'
+
+/** Host-selected connection identity. Credentials belong only to the verifier closure. */
+export interface PalChannelConnection {
+	readonly tenantId: PalAddress['tenantId']
+	readonly provider: string
+	readonly connectionId: string
+	readonly externalTenantId: string
+}
+
+export interface PalChannelVerifiedIdentity {
+	readonly externalTenantId: string
+	readonly nativeConversationId: string
+	readonly nativeChannelId: string | null
+	readonly nativeThreadId: string | null
+	readonly actorId: string
+	readonly eventId: string
+}
+
+/** Only new, authenticated messages enter the inbox. Edits and service events require another port. */
+export interface PalChannelVerifiedMessage extends PalChannelVerifiedIdentity {
+	readonly kind: 'message'
+	readonly body: string
+}
+
+/** Authentication must cover the action reference, identity and exact action payload. */
+export interface PalChannelVerifiedAction extends PalChannelVerifiedIdentity {
+	readonly kind: 'action'
+	readonly deliveryRef: InboundDeliveryRef
+	readonly actionId: string
+	readonly payloadDigest: string
+	/** Exact authenticated JSON payload; the host action port must parse its native action schema. */
+	readonly payload: string
+}
+
+export type PalChannelVerifiedEvent = PalChannelVerifiedMessage | PalChannelVerifiedAction
+
+/** Required trusted host callback; raw events cannot select a connection or its credentials. */
+export type PalChannelVerifier = (
+	raw: unknown,
+	connection: PalChannelConnection,
+	signal: AbortSignal,
+) => Promise<PalChannelVerifiedEvent>
+
+export interface PalChannelRouteDecision {
+	readonly v: 1
+	readonly revision: 1
+	readonly identity: PalChannelIdentity
+	readonly recipient: PalAddress
+	readonly profileRevision: number
+}
+
+/** One immutable decision per tenant and full native tuple. The inbox owns the actual session. */
+export interface PalChannelRoutes {
+	get(
+		connection: PalChannelConnection,
+		identity: PalChannelIdentity,
+	): Promise<PalChannelRouteDecision | null>
+	reserve(decision: PalChannelRouteDecision): Promise<PalChannelRouteDecision>
+}
+
+export interface PalChannelAuthorizationRequest {
+	readonly phase: 'accept' | 'deliver' | 'wake'
+	readonly kind: 'channel'
+	readonly source: PalChannelSource
+	readonly recipient: PalAddress
+	readonly routeKey: PalChannelIntent['routeKey']
+	readonly body: string
+	readonly replyTo: null
+}
+
+export interface PalChannelIngressOptions {
+	readonly connection: PalChannelConnection
+	readonly verify: PalChannelVerifier
+	readonly routes: PalChannelRoutes
+	readonly store: PalIngressStore
+	readonly pals: PalStore
+	/** Host selection is used only before the first immutable route decision. */
+	readonly selectRecipient: (
+		event: PalChannelVerifiedMessage,
+		connection: PalChannelConnection,
+	) => Promise<PalAddress>
+	readonly authorize: (request: PalChannelAuthorizationRequest) => Promise<PalMessageAuthorization>
+	readonly host?: PalIngressHostPort
+	readonly now?: () => number
+	readonly onNotificationError?: (
+		error: unknown,
+		receipt: PalIngressAcceptanceReceipt,
+	) => void | Promise<void>
+}
+
+export interface PalChannelExecutionContext {
+	readonly recipient: PalAddress
+	readonly sessionId: SessionId
+	readonly profileRevision: number
+}
+
+export interface PalChannelRouteAuthorizationRequest {
+	readonly phase: 'reply' | 'action'
+	readonly message: PalChannelIntent
+	readonly context: PalChannelExecutionContext
+	/** Reply uses its triggering event actor; actions authenticate their current actor independently. */
+	readonly actorId: string
+	readonly action?: PalChannelVerifiedAction
+}
+
+export interface PalChannelResolvedRoute {
+	readonly connection: PalChannelConnection
+	readonly identity: PalChannelIdentity
+	readonly deliveryRef: InboundDeliveryRef
+	readonly recordedReceipt: InboundDeliveryReceipt
+	readonly eventActorId: string
+	readonly currentActorId: string
+	readonly context: PalChannelExecutionContext
+}
+
+export interface PalChannelRouterOptions {
+	readonly connection: PalChannelConnection
+	readonly verify: PalChannelVerifier
+	readonly store: PalIngressStore
+	readonly pals: PalStore
+	readonly host: PalIngressHostPort
+	readonly authorize: (
+		request: PalChannelRouteAuthorizationRequest,
+	) => Promise<PalMessageAuthorization>
+	/** Must durably consume an exact native action once and confirm its result. No transport default. */
+	readonly actions?: PalChannelActionPort
+}
+
+export interface PalChannelActionContext {
+	readonly route: PalChannelResolvedRoute
+	readonly action: PalChannelVerifiedAction
+}
+
+export interface PalChannelActionPort {
+	execute(context: PalChannelActionContext, signal: AbortSignal): Promise<PalChannelActionResult>
+}
+
+export interface PalChannelActionResult {
+	readonly status: 'applied' | 'rejected'
+	readonly receiptId: string
+}

package/src/pals/communication/broker.ts

@@ -0,0 +1,131 @@
+import {
+	freezeCommunicationValue,
+	intentDigest,
+	intentSchema,
+	label,
+	messageId,
+	sendRequestSchema,
+	sourceSchema,
+} from './schema.js'
+import { routeId } from './schema.js'
+import {
+	type PalMessageBrokerOptions,
+	type PalMessageSender,
+	type PalMessageSenderContext,
+	type PalRouteBinding,
+	type PalRouteKey,
+	sameAddress,
+} from './types.js'
+import { verifyConversation } from './verify.js'
+
+/** Host-owned identity and current policy; model text never selects its sender. */
+export class PalMessageBroker {
+	constructor(private readonly options: PalMessageBrokerOptions) {
+		if (typeof options.authorize !== 'function')
+			throw new Error('Pal communication requires explicit authorization.')
+	}
+	sender(input: PalMessageSenderContext): PalMessageSender {
+		const source = freezeCommunicationValue(sourceSchema.parse(input))
+		return {
+			send: async (input) => {
+				const request = freezeCommunicationValue(sendRequestSchema.parse(input))
+				const { pals, store, host } = this.options
+				if (!host) throw new Error('Pal sender requires a trusted conversation host.')
+				const sender = pals.get(source.address.palId)
+				if (!sender || sender.paused) throw new Error('Sender Pal is paused or unavailable.')
+				const definition = pals.getRevision(sender.id, source.profileRevision)
+				const recipient = request.recipient
+				if (recipient.tenantId !== source.address.tenantId)
+					throw new Error('Cross-tenant Pal messages are refused.')
+				const target = pals.get(recipient.palId)
+				if (!target) throw new Error('Recipient Pal is unavailable.')
+				const validationKey: PalRouteKey = {
+					v: 1,
+					kind: 'pal',
+					sender: source.address,
+					senderConversationId: source.conversationId,
+					recipient: source.address,
+					dialogKey: 'sender-validation',
+				}
+				const validation: PalRouteBinding = {
+					id: routeId(validationKey),
+					key: validationKey,
+					sessionId: source.conversationId,
+					profileRevision: source.profileRevision,
+					revision: 1,
+					phase: 'active',
+				}
+				const signal = new AbortController().signal
+				await verifyConversation({
+					binding: validation,
+					definition,
+					access: await host.openConversation(validation, signal),
+				})
+				let dialogKey = label.parse(request.dialogKey ?? 'default')
+				let profileRevision = target.revision
+				let conversationId: typeof source.conversationId | undefined
+				const replyTo = request.replyTo ?? null
+				if (replyTo !== null) {
+					const prior = (await store.read(source.address))?.messages.find((m) => m.id === replyTo)
+					if (!prior || prior.phase !== 'recorded' || !sameAddress(prior.source.address, recipient))
+						throw new Error('Reply does not name an observed, authorized incoming Pal message.')
+					const route = await store.route(prior.routeKey)
+					if (!route || route.sessionId !== source.conversationId)
+						throw new Error('Reply belongs to another conversation.')
+					conversationId = prior.source.conversationId
+					profileRevision = prior.source.profileRevision
+					dialogKey = `reply:${conversationId}`
+				}
+				const routeKey: PalRouteKey = {
+					v: 1,
+					kind: 'pal',
+					sender: source.address,
+					senderConversationId: source.conversationId,
+					recipient,
+					dialogKey,
+				}
+				const requestContext = freezeCommunicationValue({
+					phase: 'send' as const,
+					source,
+					recipient,
+					routeKey,
+					body: request.body,
+					replyTo,
+				})
+				const authorization = await this.options.authorize(requestContext)
+				if (!authorization.allow) throw new Error(`Pal send refused: ${authorization.reason}`)
+				if (pals.get(sender.id)?.paused) throw new Error('Sender Pal was paused before acceptance.')
+				const intent = {
+					id: messageId(source, request.operationId),
+					operationId: request.operationId,
+					source,
+					recipient,
+					routeKey,
+					body: request.body,
+					replyTo,
+					grant: authorization.grant,
+					createdAt: (this.options.now ?? Date.now)(),
+				}
+				const immutableIntent = freezeCommunicationValue(
+					intentSchema.parse({ ...intent, digest: intentDigest(intent) }),
+				)
+				const accepted = await store.accept(immutableIntent, profileRevision, conversationId)
+				const report = (error: unknown) => {
+					try {
+						void Promise.resolve(this.options.onNotificationError?.(error, accepted)).catch(
+							() => undefined,
+						)
+					} catch {
+						/* Acceptance already committed. */
+					}
+				}
+				try {
+					void Promise.resolve(host.notify?.(recipient)).catch(report)
+				} catch (error) {
+					report(error)
+				}
+				return accepted
+			},
+		}
+	}
+}

package/src/pals/communication/dispatch.ts

@@ -0,0 +1,66 @@
+import { createPalInboxSource, reconcilePalDelivery } from './inbound.js'
+import type { PalIngressStore } from './ingress-types.js'
+import {
+	type PalAddress,
+	type PalDispatchOutcome,
+	type PalMessageBrokerOptions,
+	authorizationRequest,
+	currentRecipient,
+} from './types.js'
+import { verifyConversation } from './verify.js'
+
+/** Finite opt-in operation; host retains normal query/computer ownership. */
+export async function dispatchPalMessagesOnce(
+	options: PalMessageBrokerOptions,
+	recipient: PalAddress,
+	signal: AbortSignal,
+): Promise<PalDispatchOutcome> {
+	signal.throwIfAborted()
+	const host = options.host
+	if (!host)
+		return {
+			status: 'blocked',
+			reason: 'No Pal conversation host is configured.',
+		}
+	const shared = options.store as Partial<PalIngressStore>
+	if (shared.readIngress) {
+		const full = await shared.readIngress(recipient)
+		if (full?.messages.some((message) => message.phase === 'claimed' && 'kind' in message))
+			return { status: 'idle', reason: 'unresolved' }
+	}
+	let state = await options.store.read(recipient)
+	const unresolved = state?.messages.find((m) => m.phase === 'claimed')
+	if (unresolved) {
+		const binding = state?.routes.find((r) => r.id === unresolved.routeId)
+		if (
+			!binding ||
+			!(await reconcilePalDelivery({ ...options, binding, host }, unresolved, signal))
+		)
+			return { status: 'idle', reason: 'unresolved' }
+		state = await options.store.read(recipient)
+	}
+	const message = state?.messages.find((m) => m.phase === 'pending')
+	if (!message) return { status: 'idle', reason: 'empty' }
+	let binding = state?.routes.find((r) => r.id === message.routeId)
+	if (!binding) throw new Error('Pal incoming message has no route binding.')
+	const authorization = await options.authorize(authorizationRequest(message, 'wake'))
+	if (!authorization.allow) return { status: 'blocked', reason: authorization.reason }
+	currentRecipient(options.pals, binding)
+	signal.throwIfAborted()
+	await host.ensureConversation(binding, signal)
+	const definition = currentRecipient(options.pals, binding)
+	const access = await host.openConversation(binding, signal)
+	await verifyConversation({ binding, access, definition })
+	if (binding.phase === 'reserved')
+		binding = await options.store.activate(binding, {
+			binding,
+			access,
+			definition,
+		})
+	const currentAuthorization = await options.authorize(authorizationRequest(message, 'wake'))
+	if (!currentAuthorization.allow) return { status: 'blocked', reason: currentAuthorization.reason }
+	currentRecipient(options.pals, binding)
+	signal.throwIfAborted()
+	await host.runConversation(binding, createPalInboxSource({ ...options, binding, host }), signal)
+	return { status: 'ran', binding }
+}