@namzu/sdk 48.3.1 → 50.0.0

package/src/pals/communication/policy.ts

@@ -0,0 +1,174 @@
+import { chmodSync, lstatSync, mkdirSync, readdirSync, realpathSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { z } from 'zod'
+import { DiskRevisionRecordStore } from '../../store/kv/revision-record-store.js'
+import { defineSchema } from '../../store/schema.js'
+import { addressSchema, addressTuple, hash } from './schema.js'
+import {
+	type PalAddress,
+	type PalAuthorizationRequest,
+	type PalMessageAuthorization,
+	sameAddress,
+} from './types.js'
+
+/** Operator-controlled directed consent. Wake is separately opt-in. */
+export interface PalMessagePermission {
+	readonly v: 1
+	readonly source: PalAddress
+	readonly recipient: PalAddress
+	readonly revision: number
+	readonly enabled: boolean
+	readonly allowWake: boolean
+}
+
+export interface PalMessagePermissionUpdate {
+	readonly source: PalAddress
+	readonly recipient: PalAddress
+	/** Zero creates a new rule. Existing rules require their actual revision. */
+	readonly expectedRevision: number
+	readonly enabled: boolean
+	readonly allowWake: boolean
+}
+
+export class PalMessagePermissionConflictError extends Error {
+	override readonly name = 'PalMessagePermissionConflictError'
+}
+
+const permissionSchema = z.object({
+	v: z.literal(1),
+	source: addressSchema,
+	recipient: addressSchema,
+	revision: z.number().int().positive().safe(),
+	enabled: z.boolean(),
+	allowWake: z.boolean(),
+})
+
+function key(source: PalAddress, recipient: PalAddress): string {
+	return hash([addressTuple(source), addressTuple(recipient)])
+}
+
+function checked(
+	input: unknown,
+	source?: PalAddress,
+	recipient?: PalAddress,
+): PalMessagePermission {
+	const value = permissionSchema.parse(input)
+	if (
+		value.source.tenantId !== value.recipient.tenantId ||
+		(source && !sameAddress(source, value.source)) ||
+		(recipient && !sameAddress(recipient, value.recipient))
+	)
+		throw new Error('Foreign Pal communication permission.')
+	Object.freeze(value.source)
+	Object.freeze(value.recipient)
+	return Object.freeze(value)
+}
+
+/**
+ * Optional local operator policy. Missing and revoked rules deny; a stored grant
+ * reference is evidence only. Every authorization reads the current revision.
+ */
+export class DiskPalMessagePolicy {
+	private readonly root: string
+	private readonly secure: (path: string) => void
+	private readonly records = new DiskRevisionRecordStore<PalMessagePermission>(
+		defineSchema({ kind: 'pal-message-permission', current: 1, migrations: {} }),
+		'Pal message permission',
+		(value) => value.revision,
+	)
+	constructor(options: { root: string; secureDirectory?: (path: string) => void }) {
+		this.root = resolve(options.root)
+		this.secure =
+			options.secureDirectory ??
+			((path) => {
+				if (process.platform !== 'win32') chmodSync(path, 0o700)
+			})
+		this.directory(this.root)
+	}
+	private directory(path: string): void {
+		mkdirSync(path, { recursive: true, mode: 0o700 })
+		const entry = lstatSync(path)
+		if (!entry.isDirectory() || entry.isSymbolicLink() || realpathSync(path) !== path)
+			throw new Error('Pal communication policy requires real directories without aliases.')
+		this.secure(path)
+	}
+	private location(source: PalAddress, recipient: PalAddress) {
+		addressSchema.parse(source)
+		addressSchema.parse(recipient)
+		if (source.tenantId !== recipient.tenantId)
+			throw new Error('Cross-tenant Pal grants are refused.')
+		this.directory(this.root)
+		const directory = join(this.root, key(source, recipient))
+		this.directory(directory)
+		const revisionsDir = join(directory, 'revisions')
+		this.directory(revisionsDir)
+		return { legacyPath: join(directory, 'permission.json'), revisionsDir }
+	}
+	async get(source: PalAddress, recipient: PalAddress): Promise<PalMessagePermission | null> {
+		const capturedSource = addressSchema.parse(source)
+		const capturedRecipient = addressSchema.parse(recipient)
+		const value = await this.records.read(this.location(capturedSource, capturedRecipient))
+		return value ? checked(value, capturedSource, capturedRecipient) : null
+	}
+	async update(input: PalMessagePermissionUpdate): Promise<PalMessagePermission> {
+		// Capture all caller data before the first asynchronous storage boundary.
+		const source = addressSchema.parse(input.source)
+		const recipient = addressSchema.parse(input.recipient)
+		const { expectedRevision, enabled, allowWake } = input
+		if (!Number.isSafeInteger(expectedRevision) || expectedRevision < 0)
+			throw new Error('A nonnegative expected permission revision is required.')
+		if (typeof enabled !== 'boolean' || typeof allowWake !== 'boolean')
+			throw new Error('Explicit Pal communication and wake consent are required.')
+		return this.records.transact(this.location(source, recipient), (stored) => {
+			const current = stored ? checked(stored, source, recipient) : null
+			if ((current?.revision ?? 0) !== expectedRevision)
+				throw new PalMessagePermissionConflictError(
+					'Pal communication permission changed; reload it.',
+				)
+			const record = checked({
+				v: 1,
+				source,
+				recipient,
+				revision: expectedRevision + 1,
+				enabled,
+				allowWake,
+			})
+			return { record, result: record }
+		})
+	}
+	async outgoing(source: PalAddress): Promise<readonly PalMessagePermission[]> {
+		const captured = addressSchema.parse(source)
+		this.directory(this.root)
+		const rules: PalMessagePermission[] = []
+		for (const name of readdirSync(this.root)) {
+			if (!/^[a-f0-9]{64}$/.test(name)) continue
+			const directory = join(this.root, name)
+			this.directory(directory)
+			this.directory(join(directory, 'revisions'))
+			const stored = await this.records.read({
+				legacyPath: join(directory, 'permission.json'),
+				revisionsDir: join(directory, 'revisions'),
+			})
+			if (!stored) continue
+			const rule = checked(stored)
+			if (name !== key(rule.source, rule.recipient))
+				throw new Error('Pal permission path identity changed.')
+			if (rule.enabled && sameAddress(rule.source, captured)) rules.push(rule)
+		}
+		return Object.freeze(rules)
+	}
+	async authorize(request: PalAuthorizationRequest): Promise<PalMessageAuthorization> {
+		const phase = request.phase
+		if (!['send', 'deliver', 'wake'].includes(phase))
+			throw new Error('Invalid Pal authorization phase.')
+		const rule = await this.get(request.source.address, request.recipient)
+		if (!rule?.enabled)
+			return { allow: false, reason: 'No current directed Pal communication permission.' }
+		if (phase === 'wake' && !rule.allowWake)
+			return { allow: false, reason: 'This Pal communication permission does not allow wakeup.' }
+		return {
+			allow: true,
+			grant: { id: key(rule.source, rule.recipient), revision: String(rule.revision) },
+		}
+	}
+}

package/src/pals/communication/schema.ts

@@ -0,0 +1,173 @@
+import { createHash } from 'node:crypto'
+import { z } from 'zod'
+import type { MessageId, SessionId, TenantId, TurnId } from '../../types/ids/index.js'
+import { isEntityId } from '../../utils/id.js'
+import type { PalAddress, PalMessageIntent, PalMessageSenderContext, PalRouteKey } from './types.js'
+
+const id = z.string().uuid()
+const sessionId = z.custom<SessionId>((s) => isEntityId(s, 'session'))
+const turnId = z.custom<TurnId>((s) => isEntityId(s, 'turn'))
+const recordMessageId = z.custom<MessageId>((s) => isEntityId(s, 'message'))
+const positive = z.number().int().positive().safe()
+const natural = z.number().int().nonnegative().safe()
+const digest = z.string().regex(/^[a-f0-9]{64}$/)
+export const label = z
+	.string()
+	.min(1)
+	.max(512)
+	.refine((s) => [...s].every((c) => c.charCodeAt(0) >= 32 && c.charCodeAt(0) !== 127))
+export const addressSchema = z
+	.object({
+		tenantId: z.custom<TenantId>((s) => isEntityId(s, 'tenant')),
+		palId: id,
+	})
+	.strict()
+export const routeKeySchema = z
+	.object({
+		v: z.literal(1),
+		kind: z.literal('pal'),
+		sender: addressSchema,
+		senderConversationId: z.custom<SessionId>((s) => isEntityId(s, 'session')),
+		recipient: addressSchema,
+		dialogKey: label,
+	})
+	.strict()
+	.refine((r) => r.sender.tenantId === r.recipient.tenantId, 'Cross-tenant Pal routes are refused.')
+export const sourceSchema = z
+	.object({
+		address: addressSchema,
+		conversationId: z.custom<SessionId>((s) => isEntityId(s, 'session')),
+		profileRevision: positive,
+	})
+	.strict()
+export const sendRequestSchema = z
+	.object({
+		operationId: label,
+		recipient: addressSchema,
+		body: z
+			.string()
+			.min(1)
+			.max(32_000)
+			.refine((s) => !s.includes('\u0000')),
+		dialogKey: label.optional(),
+		replyTo: digest.optional(),
+	})
+	.strict()
+export const intentSchema = z
+	.object({
+		id: digest,
+		digest,
+		operationId: label,
+		source: sourceSchema,
+		recipient: addressSchema,
+		routeKey: routeKeySchema,
+		body: z
+			.string()
+			.min(1)
+			.max(32_000)
+			.refine((s) => !s.includes('\u0000')),
+		replyTo: digest.nullable(),
+		grant: z.object({ id: label, revision: label }).strict(),
+		createdAt: natural,
+	})
+	.strict()
+export const operationReservationSchema = z.object({
+	revision: z.literal(1),
+	intent: intentSchema,
+	recipientRevision: positive,
+	conversationId: sessionId.nullable(),
+})
+export const bindingSchema = z.object({
+	id: digest,
+	key: routeKeySchema,
+	sessionId,
+	profileRevision: positive,
+	revision: positive,
+	phase: z.enum(['reserved', 'active']),
+})
+const headSchema = z
+	.object({
+		pointer: z
+			.object({ seq: positive, offset: natural, length: positive, sha256: digest })
+			.strict(),
+		gen: natural,
+		bytes: positive,
+	})
+	.strict()
+export const receiptSchema = z
+	.object({
+		claimId: id,
+		ref: z.object({ namespace: z.literal('namzu-pal-message/1'), id: digest, digest }).strict(),
+		sessionId,
+		turnId,
+		messageId: recordMessageId,
+		through: headSchema,
+	})
+	.strict()
+export const inboxSchema = intentSchema.extend({
+	ordinal: positive,
+	routeId: digest,
+	phase: z.enum(['pending', 'claimed', 'recorded']),
+	claim: z
+		.object({ id, sessionId, turnId, generation: natural, content: z.string().min(1).max(48_000) })
+		.strict()
+		.nullable(),
+	receipt: receiptSchema.nullable(),
+})
+export const snapshotSchema = z.object({
+	recipient: addressSchema,
+	revision: positive,
+	routes: z.array(bindingSchema),
+	messages: z.array(inboxSchema),
+})
+
+/** Capture parsed values recursively before any host callback can observe them. */
+export function freezeCommunicationValue<T>(value: T): T {
+	if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+		for (const child of Object.values(value)) freezeCommunicationValue(child)
+		Object.freeze(value)
+	}
+	return value
+}
+
+export function hash(value: unknown): string {
+	return createHash('sha256').update(JSON.stringify(value)).digest('hex')
+}
+export function addressTuple(value: PalAddress): readonly string[] {
+	return [value.tenantId, value.palId]
+}
+export function routeTuple(value: PalRouteKey): readonly unknown[] {
+	return [
+		1,
+		'pal',
+		addressTuple(value.sender),
+		value.senderConversationId,
+		addressTuple(value.recipient),
+		value.dialogKey,
+	]
+}
+export function routeId(value: PalRouteKey): string {
+	return hash(routeTuple(routeKeySchema.parse(value)))
+}
+export function messageId(source: PalMessageSenderContext, operationId: string): string {
+	return hash([
+		1,
+		'pal-message',
+		addressTuple(source.address),
+		source.conversationId,
+		label.parse(operationId),
+	])
+}
+export function intentDigest(intent: Omit<PalMessageIntent, 'digest'>): string {
+	return hash([
+		1,
+		addressTuple(intent.source.address),
+		intent.source.conversationId,
+		intent.source.profileRevision,
+		intent.operationId,
+		addressTuple(intent.recipient),
+		routeTuple(intent.routeKey),
+		intent.body,
+		intent.replyTo,
+	])
+}