@alpacakit/agents 0.1.0-beta.20 → 0.1.0-beta.21

package/dist/internal/controlled-process/lifecycle.d.ts

@@ -0,0 +1,5 @@
+import type { ControlledProcessState } from "./model.js";
+export declare const CONTROLLED_PROCESS_TRANSITIONS: readonly [readonly ["reserved", "acked"], readonly ["reserved", "absent"], readonly ["acked", "running"], readonly ["acked", "absent"], readonly ["running", "term"], readonly ["running", "absent"], readonly ["term", "kill_sent"], readonly ["term", "absent"], readonly ["kill_sent", "absent"], readonly ["absent", "released"]];
+export declare function isControlledProcessTransitionAllowed(from: ControlledProcessState, to: ControlledProcessState): boolean;
+export declare function transitionControlledProcess(from: ControlledProcessState, to: ControlledProcessState): ControlledProcessState;
+//# sourceMappingURL=lifecycle.d.ts.map

package/dist/internal/controlled-process/lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lifecycle.d.ts","sourceRoot":"","sources":["../../../src/internal/controlled-process/lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AAQzD,eAAO,MAAM,8BAA8B,uUAWgB,CAAC;AAE5D,wBAAgB,oCAAoC,CAClD,IAAI,EAAE,sBAAsB,EAC5B,EAAE,EAAE,sBAAsB,GACzB,OAAO,CAIT;AAED,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,sBAAsB,EAC5B,EAAE,EAAE,sBAAsB,GACzB,sBAAsB,CAKxB"}

package/dist/internal/controlled-process/lifecycle.js

@@ -0,0 +1,22 @@
+import { CONTROLLED_PROCESS_STATE } from "./values.js";
+export const CONTROLLED_PROCESS_TRANSITIONS = [
+    [CONTROLLED_PROCESS_STATE.reserved, CONTROLLED_PROCESS_STATE.acked],
+    [CONTROLLED_PROCESS_STATE.reserved, CONTROLLED_PROCESS_STATE.absent],
+    [CONTROLLED_PROCESS_STATE.acked, CONTROLLED_PROCESS_STATE.running],
+    [CONTROLLED_PROCESS_STATE.acked, CONTROLLED_PROCESS_STATE.absent],
+    [CONTROLLED_PROCESS_STATE.running, CONTROLLED_PROCESS_STATE.term],
+    [CONTROLLED_PROCESS_STATE.running, CONTROLLED_PROCESS_STATE.absent],
+    [CONTROLLED_PROCESS_STATE.term, CONTROLLED_PROCESS_STATE.killSent],
+    [CONTROLLED_PROCESS_STATE.term, CONTROLLED_PROCESS_STATE.absent],
+    [CONTROLLED_PROCESS_STATE.killSent, CONTROLLED_PROCESS_STATE.absent],
+    [CONTROLLED_PROCESS_STATE.absent, CONTROLLED_PROCESS_STATE.released],
+];
+export function isControlledProcessTransitionAllowed(from, to) {
+    return CONTROLLED_PROCESS_TRANSITIONS.some((transition) => transition[0] === from && transition[1] === to);
+}
+export function transitionControlledProcess(from, to) {
+    if (!isControlledProcessTransitionAllowed(from, to)) {
+        throw new Error(`Invalid controlled process transition: ${from} -> ${to}`);
+    }
+    return to;
+}

package/dist/internal/controlled-process/model.d.ts

@@ -0,0 +1,99 @@
+import type { Brand, ValueOf } from "@alpacakit/core";
+import type { ChildProcessAbsenceProof } from "../../core/controlled-process.js";
+import type { CHILD_PROCESS_ABSENCE_PROOF } from "../../core/controlled-process.js";
+import type { CONTROLLED_PROCESS_PLATFORM, CONTROLLED_PROCESS_PROTOCOL_VERSION, CONTROLLED_PROCESS_STATE, SUPERVISOR_AUTHENTICATION_FRAME_KIND, SUPERVISOR_AUTHENTICATION_REJECTION_REASON, SUPERVISOR_AUTHENTICATION_RESULT_KIND, SUPERVISOR_CHALLENGE_STATE_KIND } from "./values.js";
+export type ControlledProcessPlatform = ValueOf<typeof CONTROLLED_PROCESS_PLATFORM>;
+export type ControlledProcessState = ValueOf<typeof CONTROLLED_PROCESS_STATE>;
+export type PersistedChildProcessAbsenceProof = Exclude<ChildProcessAbsenceProof, typeof CHILD_PROCESS_ABSENCE_PROOF.releasedReceipt>;
+export type SupervisorBootId = Brand<string, "SupervisorBootId">;
+export type SupervisorInstanceId = Brand<string, "SupervisorInstanceId">;
+export type ControlledProcessRecordId = Brand<string, "ControlledProcessRecordId">;
+export type SupervisorSocketLocator = Brand<string, "SupervisorSocketLocator">;
+export type SupervisorCapability = Brand<string, "SupervisorCapability">;
+export type ProcessStartToken = Brand<string, "ProcessStartToken">;
+export type ControlledProcessRecordMac = Brand<string, "ControlledProcessRecordMac">;
+export type SupervisorAuthenticationMac = Brand<string, "SupervisorAuthenticationMac">;
+export type SupervisorClientNonce = Brand<string, "SupervisorClientNonce">;
+export type SupervisorServerNonce = Brand<string, "SupervisorServerNonce">;
+export type ShimProcessId = Brand<number, "ShimProcessId">;
+export type ProcessStartTokenFields = {
+    readonly protocolVersion: typeof CONTROLLED_PROCESS_PROTOCOL_VERSION;
+    readonly platform: ControlledProcessPlatform;
+    readonly bootId: SupervisorBootId;
+    readonly supervisorInstanceId: SupervisorInstanceId;
+    readonly recordId: ControlledProcessRecordId;
+    readonly socketLocator: SupervisorSocketLocator;
+    readonly capability: SupervisorCapability;
+};
+/**
+ * Durable supervisor record. `pid` identifies the shim and the supervisor
+ * enforces the private spawn invariant `PGID === shim pid`. Consumers must not
+ * derive a raw process-group signaling authority from this record: only the
+ * authenticated supervisor protocol may terminate or prove group absence.
+ * That proof covers only absence of the shim leader's same POSIX process
+ * group. A descendant that escapes with `setsid` or `setpgid` is outside this
+ * guarantee; `absent` must not be interpreted as an OS-wide descendant census.
+ */
+export type ControlledProcessRecord = {
+    readonly protocolVersion: typeof CONTROLLED_PROCESS_PROTOCOL_VERSION;
+    readonly platform: ControlledProcessPlatform;
+    readonly bootId: SupervisorBootId;
+    readonly supervisorInstanceId: SupervisorInstanceId;
+    readonly recordId: ControlledProcessRecordId;
+    readonly socketLocator: SupervisorSocketLocator;
+    readonly pid: ShimProcessId;
+    readonly state: ControlledProcessState;
+    readonly absenceProof: PersistedChildProcessAbsenceProof | null;
+};
+export type SignedControlledProcessRecord = {
+    readonly record: ControlledProcessRecord;
+    readonly recordMac: ControlledProcessRecordMac;
+};
+export type SupervisorClientChallenge = {
+    readonly kind: typeof SUPERVISOR_AUTHENTICATION_FRAME_KIND.clientChallenge;
+    readonly recordId: ControlledProcessRecordId;
+    readonly clientNonce: SupervisorClientNonce;
+};
+export type SupervisorChallengeTranscript = {
+    readonly protocolVersion: typeof CONTROLLED_PROCESS_PROTOCOL_VERSION;
+    readonly recordId: ControlledProcessRecordId;
+    readonly clientNonce: SupervisorClientNonce;
+    readonly serverNonce: SupervisorServerNonce;
+};
+export type SupervisorChallenge = {
+    readonly kind: typeof SUPERVISOR_AUTHENTICATION_FRAME_KIND.supervisorChallenge;
+    readonly recordId: ControlledProcessRecordId;
+    readonly clientNonce: SupervisorClientNonce;
+    readonly serverNonce: SupervisorServerNonce;
+    readonly supervisorMac: SupervisorAuthenticationMac;
+};
+export type SupervisorClientProof = {
+    readonly kind: typeof SUPERVISOR_AUTHENTICATION_FRAME_KIND.clientProof;
+    readonly recordId: ControlledProcessRecordId;
+    readonly clientNonce: SupervisorClientNonce;
+    readonly serverNonce: SupervisorServerNonce;
+    readonly supervisorMac: SupervisorAuthenticationMac;
+    readonly clientMac: SupervisorAuthenticationMac;
+};
+export type SupervisorChallengeState = {
+    readonly kind: typeof SUPERVISOR_CHALLENGE_STATE_KIND.awaitingClient;
+    readonly transcript: SupervisorChallengeTranscript;
+    readonly supervisorMac: SupervisorAuthenticationMac;
+} | {
+    readonly kind: typeof SUPERVISOR_CHALLENGE_STATE_KIND.consumed;
+    readonly transcript: SupervisorChallengeTranscript;
+    readonly supervisorMac: SupervisorAuthenticationMac;
+};
+export type SupervisorAuthenticationResult = {
+    readonly kind: typeof SUPERVISOR_AUTHENTICATION_RESULT_KIND.accepted;
+    readonly state: Extract<SupervisorChallengeState, {
+        readonly kind: typeof SUPERVISOR_CHALLENGE_STATE_KIND.consumed;
+    }>;
+} | {
+    readonly kind: typeof SUPERVISOR_AUTHENTICATION_RESULT_KIND.rejected;
+    readonly reason: ValueOf<typeof SUPERVISOR_AUTHENTICATION_REJECTION_REASON>;
+    readonly state: Extract<SupervisorChallengeState, {
+        readonly kind: typeof SUPERVISOR_CHALLENGE_STATE_KIND.consumed;
+    }>;
+};
+//# sourceMappingURL=model.d.ts.map

package/dist/internal/controlled-process/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../../src/internal/controlled-process/model.ts"],"names":[],"mappings":"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"}

package/dist/internal/controlled-process/model.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/controlled-process/record-store.d.ts

@@ -0,0 +1,17 @@
+import type { ControlledProcessPlatform, ControlledProcessRecordId, SignedControlledProcessRecord, SupervisorSocketLocator } from "./model.js";
+export declare function assertSecureRuntimeDirectory(runtimeDirectory: string, uid: number): Promise<string>;
+export declare function resolveSupervisorSocketNamespace(platform: ControlledProcessPlatform, uid: number): Promise<string>;
+export declare function supervisorSocketPath(input: {
+    readonly socketDirectory: string;
+    readonly socketLocator: SupervisorSocketLocator;
+    readonly platform: ControlledProcessPlatform;
+}): string;
+export declare class SignedRecordStore {
+    private readonly uid;
+    readonly filePath: string;
+    constructor(runtimeDirectory: string, recordId: ControlledProcessRecordId, uid: number);
+    read(): Promise<SignedControlledProcessRecord>;
+    write(record: SignedControlledProcessRecord): Promise<void>;
+    removeUnpublished(): Promise<void>;
+}
+//# sourceMappingURL=record-store.d.ts.map

package/dist/internal/controlled-process/record-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-store.d.ts","sourceRoot":"","sources":["../../../src/internal/controlled-process/record-store.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,yBAAyB,EACzB,yBAAyB,EACzB,6BAA6B,EAC7B,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAkBpB,wBAAsB,4BAA4B,CAChD,gBAAgB,EAAE,MAAM,EACxB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,CAkBjB;AAED,wBAAsB,gCAAgC,CACpD,QAAQ,EAAE,yBAAyB,EACnC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,CAAC,CAiBjB;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE;IAC1C,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,uBAAuB,CAAC;IAChD,QAAQ,CAAC,QAAQ,EAAE,yBAAyB,CAAC;CAC9C,GAAG,MAAM,CAWT;AAkDD,qBAAa,iBAAiB;IAM1B,OAAO,CAAC,QAAQ,CAAC,GAAG;IALtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;gBAGxB,gBAAgB,EAAE,MAAM,EACxB,QAAQ,EAAE,yBAAyB,EAClB,GAAG,EAAE,MAAM;IAQxB,IAAI,IAAI,OAAO,CAAC,6BAA6B,CAAC;IAO9C,KAAK,CAAC,MAAM,EAAE,6BAA6B,GAAG,OAAO,CAAC,IAAI,CAAC;IAyB3D,iBAAiB,IAAI,OAAO,CAAC,IAAI,CAAC;CAWzC"}

package/dist/internal/controlled-process/record-store.js

@@ -0,0 +1,170 @@
+import { lstat, mkdir, open, readFile, realpath, rename, unlink, } from "node:fs/promises";
+import path from "node:path";
+import { decodeSignedControlledProcessRecord, encodeSignedControlledProcessRecord, } from "./record.js";
+const RUNTIME_DIRECTORY_MODE = 0o700;
+const RECORD_FILE_MODE = 0o600;
+const PERMISSION_BITS = 0o777;
+const RECORD_FILE_SUFFIX = ".record.json";
+const SOCKET_FILE_SUFFIX = ".sock";
+const SOCKET_PATH_LIMIT = { darwin: 103, linux: 107 };
+const SOCKET_NAMESPACE_PARENT = {
+    darwin: "/private/tmp",
+    linux: "/tmp",
+};
+const SOCKET_NAMESPACE_PREFIX = "alpacakit-agents-";
+export async function assertSecureRuntimeDirectory(runtimeDirectory, uid) {
+    const resolved = path.resolve(runtimeDirectory);
+    const stat = await lstat(resolved);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error("Supervisor runtime path must be a real directory.");
+    }
+    if (stat.uid !== uid) {
+        throw new Error("Supervisor runtime directory owner does not match uid.");
+    }
+    if ((stat.mode & PERMISSION_BITS) !== RUNTIME_DIRECTORY_MODE) {
+        throw new Error("Supervisor runtime directory mode must be 0700.");
+    }
+    if ((await realpath(resolved)) !== resolved) {
+        throw new Error("Supervisor runtime directory path must contain no symlink.");
+    }
+    return resolved;
+}
+export async function resolveSupervisorSocketNamespace(platform, uid) {
+    if (!Number.isSafeInteger(uid) || uid < 0) {
+        throw new Error("Supervisor socket namespace requires a real POSIX uid.");
+    }
+    const socketDirectory = path.join(SOCKET_NAMESPACE_PARENT[platform], `${SOCKET_NAMESPACE_PREFIX}${uid}`);
+    await assertRealDirectoryAncestors(path.dirname(socketDirectory));
+    try {
+        await mkdir(socketDirectory, { mode: RUNTIME_DIRECTORY_MODE });
+    }
+    catch (error) {
+        if (!isErrno(error, "EEXIST")) {
+            throw error;
+        }
+    }
+    return assertSecureSocketDirectory(socketDirectory, uid);
+}
+export function supervisorSocketPath(input) {
+    const socketPath = path.join(input.socketDirectory, `${input.socketLocator}${SOCKET_FILE_SUFFIX}`);
+    if (Buffer.byteLength(socketPath, "utf8") > SOCKET_PATH_LIMIT[input.platform]) {
+        throw new Error("Supervisor Unix socket path exceeds the platform limit.");
+    }
+    return socketPath;
+}
+async function assertSecureSocketDirectory(socketDirectory, uid) {
+    const resolved = path.resolve(socketDirectory);
+    const stat = await lstat(resolved);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error("Supervisor socket namespace must be a real directory.");
+    }
+    if (stat.uid !== uid) {
+        throw new Error("Supervisor socket namespace owner does not match uid.");
+    }
+    if ((stat.mode & PERMISSION_BITS) !== RUNTIME_DIRECTORY_MODE) {
+        throw new Error("Supervisor socket namespace mode must be 0700.");
+    }
+    if ((await realpath(resolved)) !== resolved) {
+        throw new Error("Supervisor socket namespace path must contain no symlink.");
+    }
+    return resolved;
+}
+async function assertRealDirectoryAncestors(directory) {
+    const resolved = path.resolve(directory);
+    const { root } = path.parse(resolved);
+    let componentPath = root;
+    await assertRealDirectoryComponent(componentPath);
+    for (const component of path.relative(root, resolved).split(path.sep)) {
+        if (component.length === 0) {
+            continue;
+        }
+        componentPath = path.join(componentPath, component);
+        await assertRealDirectoryComponent(componentPath);
+    }
+}
+async function assertRealDirectoryComponent(componentPath) {
+    const stat = await lstat(componentPath);
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error("Supervisor socket namespace ancestors must be real directories.");
+    }
+}
+export class SignedRecordStore {
+    uid;
+    filePath;
+    constructor(runtimeDirectory, recordId, uid) {
+        this.uid = uid;
+        this.filePath = path.join(runtimeDirectory, `${recordId}${RECORD_FILE_SUFFIX}`);
+    }
+    async read() {
+        await assertSecureOwnedFile(this.filePath, this.uid);
+        return decodeSignedControlledProcessRecord(await readFile(this.filePath, "utf8"));
+    }
+    async write(record) {
+        await assertReplaceableTarget(this.filePath, this.uid);
+        const temporaryPath = `${this.filePath}.tmp-${process.pid}-${Date.now()}`;
+        const handle = await open(temporaryPath, "wx", RECORD_FILE_MODE);
+        let renamed = false;
+        try {
+            await handle.chmod(RECORD_FILE_MODE);
+            await handle.writeFile(encodeSignedControlledProcessRecord(record), "utf8");
+            await handle.sync();
+            await handle.close();
+            await rename(temporaryPath, this.filePath);
+            renamed = true;
+            await syncDirectory(path.dirname(this.filePath));
+            await assertSecureOwnedFile(this.filePath, this.uid);
+        }
+        finally {
+            await handle.close().catch(() => undefined);
+            if (!renamed) {
+                await unlink(temporaryPath).catch(() => undefined);
+            }
+        }
+    }
+    async removeUnpublished() {
+        try {
+            await unlink(this.filePath);
+        }
+        catch (error) {
+            if (!isErrno(error, "ENOENT")) {
+                throw error;
+            }
+            return;
+        }
+        await syncDirectory(path.dirname(this.filePath));
+    }
+}
+async function assertReplaceableTarget(filePath, uid) {
+    try {
+        await assertSecureOwnedFile(filePath, uid);
+    }
+    catch (error) {
+        if (!isErrno(error, "ENOENT")) {
+            throw error;
+        }
+    }
+}
+async function assertSecureOwnedFile(filePath, uid) {
+    const stat = await lstat(filePath);
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error("Supervisor record must be a real regular file.");
+    }
+    if (stat.uid !== uid) {
+        throw new Error("Supervisor record owner does not match uid.");
+    }
+    if ((stat.mode & PERMISSION_BITS) !== RECORD_FILE_MODE) {
+        throw new Error("Supervisor record mode must be 0600.");
+    }
+}
+async function syncDirectory(directory) {
+    const handle = await open(directory, "r");
+    try {
+        await handle.sync();
+    }
+    finally {
+        await handle.close();
+    }
+}
+function isErrno(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}

package/dist/internal/controlled-process/record.d.ts

@@ -0,0 +1,12 @@
+import type { ValueOf } from "@alpacakit/core";
+import type { ControlledProcessRecord, ProcessStartTokenFields, SignedControlledProcessRecord, SupervisorCapability } from "./model.js";
+import { SUPERVISOR_MAC_DOMAIN } from "./values.js";
+export declare function encodeCanonicalControlledProcessRecord(record: ControlledProcessRecord): string;
+export declare function signControlledProcessRecord(record: ControlledProcessRecord, capability: SupervisorCapability): SignedControlledProcessRecord;
+export declare function encodeSignedControlledProcessRecord(signedRecord: SignedControlledProcessRecord): string;
+export declare function decodeSignedControlledProcessRecord(value: string): SignedControlledProcessRecord;
+export declare function controlledProcessRecordMatchesToken(record: ControlledProcessRecord, token: ProcessStartTokenFields): boolean;
+export declare function verifySignedControlledProcessRecord(signedRecordInput: unknown, identityInput: unknown): signedRecordInput is SignedControlledProcessRecord;
+export declare function createDomainSeparatedMac(domain: ValueOf<typeof SUPERVISOR_MAC_DOMAIN>, transcript: string, capability: SupervisorCapability): string;
+export declare function constantTimeMacEqual(left: string, right: string): boolean;
+//# sourceMappingURL=record.d.ts.map

package/dist/internal/controlled-process/record.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"record.d.ts","sourceRoot":"","sources":["../../../src/internal/controlled-process/record.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAG/C,OAAO,KAAK,EACV,uBAAuB,EAEvB,uBAAuB,EACvB,6BAA6B,EAC7B,oBAAoB,EACrB,MAAM,YAAY,CAAC;AASpB,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAMpD,wBAAgB,sCAAsC,CACpD,MAAM,EAAE,uBAAuB,GAC9B,MAAM,CAYR;AAED,wBAAgB,2BAA2B,CACzC,MAAM,EAAE,uBAAuB,EAC/B,UAAU,EAAE,oBAAoB,GAC/B,6BAA6B,CAM/B;AAED,wBAAgB,mCAAmC,CACjD,YAAY,EAAE,6BAA6B,GAC1C,MAAM,CAMR;AAED,wBAAgB,mCAAmC,CACjD,KAAK,EAAE,MAAM,GACZ,6BAA6B,CAQ/B;AAED,wBAAgB,mCAAmC,CACjD,MAAM,EAAE,uBAAuB,EAC/B,KAAK,EAAE,uBAAuB,GAC7B,OAAO,CAST;AAED,wBAAgB,mCAAmC,CACjD,iBAAiB,EAAE,OAAO,EAC1B,aAAa,EAAE,OAAO,GACrB,iBAAiB,IAAI,6BAA6B,CA0BpD;AA0BD,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,OAAO,CAAC,OAAO,qBAAqB,CAAC,EAC7C,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,oBAAoB,GAC/B,MAAM,CAMR;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAQzE"}

package/dist/internal/controlled-process/record.js

@@ -0,0 +1,87 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { readJsonRecord } from "../../core/json.js";
+import { controlledProcessIdentitySchema, controlledProcessRecordSchema, controlledProcessRecordMacSchema, lowerHex32ByteSchema, signedControlledProcessRecordSchema, } from "./schema.js";
+import { decodeProcessStartToken } from "./token.js";
+import { SUPERVISOR_MAC_DOMAIN } from "./values.js";
+const MAC_ENCODING = "hex";
+const MAC_ALGORITHM = "sha256";
+const MAC_TRANSCRIPT_SEPARATOR = "\0";
+export function encodeCanonicalControlledProcessRecord(record) {
+    return JSON.stringify({
+        protocolVersion: record.protocolVersion,
+        platform: record.platform,
+        bootId: record.bootId,
+        supervisorInstanceId: record.supervisorInstanceId,
+        recordId: record.recordId,
+        socketLocator: record.socketLocator,
+        pid: record.pid,
+        state: record.state,
+        absenceProof: record.absenceProof,
+    });
+}
+export function signControlledProcessRecord(record, capability) {
+    const validatedRecord = controlledProcessRecordSchema.parse(record);
+    return {
+        record: validatedRecord,
+        recordMac: createRecordMac(validatedRecord, capability),
+    };
+}
+export function encodeSignedControlledProcessRecord(signedRecord) {
+    const validatedRecord = signedControlledProcessRecordSchema.parse(signedRecord);
+    return `{"record":${encodeCanonicalControlledProcessRecord(validatedRecord.record)},"recordMac":"${validatedRecord.recordMac}"}`;
+}
+export function decodeSignedControlledProcessRecord(value) {
+    const parsed = signedControlledProcessRecordSchema.parse(readJsonRecord(value));
+    if (encodeSignedControlledProcessRecord(parsed) !== value) {
+        throw new Error("Controlled process record is not canonically encoded.");
+    }
+    return parsed;
+}
+export function controlledProcessRecordMatchesToken(record, token) {
+    return (record.protocolVersion === token.protocolVersion &&
+        record.platform === token.platform &&
+        record.bootId === token.bootId &&
+        record.supervisorInstanceId === token.supervisorInstanceId &&
+        record.recordId === token.recordId &&
+        record.socketLocator === token.socketLocator);
+}
+export function verifySignedControlledProcessRecord(signedRecordInput, identityInput) {
+    const signedRecord = signedControlledProcessRecordSchema.safeParse(signedRecordInput);
+    if (!signedRecord.success) {
+        return false;
+    }
+    const identity = controlledProcessIdentitySchema.safeParse(identityInput);
+    if (!identity.success) {
+        return false;
+    }
+    const token = decodeProcessStartToken(identity.data.processStartToken);
+    if (!controlledProcessRecordMatchesIdentity(signedRecord.data.record, token, identity.data)) {
+        return false;
+    }
+    return constantTimeMacEqual(signedRecord.data.recordMac, createRecordMac(signedRecord.data.record, token.capability));
+}
+function controlledProcessRecordMatchesIdentity(record, token, identity) {
+    return (controlledProcessRecordMatchesToken(record, token) &&
+        record.pid === identity.pid);
+}
+function createRecordMac(record, capability) {
+    return controlledProcessRecordMacSchema.parse(createDomainSeparatedMac(SUPERVISOR_MAC_DOMAIN.record, encodeCanonicalControlledProcessRecord(record), capability));
+}
+export function createDomainSeparatedMac(domain, transcript, capability) {
+    return createHmac(MAC_ALGORITHM, Buffer.from(capability, MAC_ENCODING))
+        .update(domain)
+        .update(MAC_TRANSCRIPT_SEPARATOR)
+        .update(transcript)
+        .digest(MAC_ENCODING);
+}
+export function constantTimeMacEqual(left, right) {
+    const leftBytes = decodeMac(left);
+    const rightBytes = decodeMac(right);
+    return (leftBytes !== null &&
+        rightBytes !== null &&
+        timingSafeEqual(leftBytes, rightBytes));
+}
+function decodeMac(value) {
+    const parsed = lowerHex32ByteSchema.safeParse(value);
+    return parsed.success ? Buffer.from(parsed.data, MAC_ENCODING) : null;
+}

package/dist/internal/controlled-process/schema.d.ts

@@ -0,0 +1,133 @@
+import { z } from "zod";
+import type { ControlledProcessRecordId, ControlledProcessRecordMac, ProcessStartToken, ShimProcessId, SupervisorAuthenticationMac, SupervisorBootId, SupervisorCapability, SupervisorClientNonce, SupervisorInstanceId, SupervisorServerNonce, SupervisorSocketLocator } from "./model.js";
+export declare const lowerHex32ByteSchema: z.ZodString;
+export declare const controlledProcessPlatformSchema: z.ZodEnum<{
+    darwin: "darwin";
+    linux: "linux";
+}>;
+export declare const controlledProcessStateSchema: z.ZodEnum<{
+    absent: "absent";
+    reserved: "reserved";
+    acked: "acked";
+    running: "running";
+    term: "term";
+    kill_sent: "kill_sent";
+    released: "released";
+}>;
+export declare const supervisorBootIdSchema: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorBootId, string>>;
+export declare const supervisorInstanceIdSchema: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorInstanceId, string>>;
+export declare const controlledProcessRecordIdSchema: z.ZodPipe<z.ZodString, z.ZodTransform<ControlledProcessRecordId, string>>;
+export declare const supervisorSocketLocatorSchema: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorSocketLocator, string>>;
+export declare const supervisorCapabilitySchema: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorCapability, string>>;
+export declare const controlledProcessRecordMacSchema: z.ZodPipe<z.ZodString, z.ZodTransform<ControlledProcessRecordMac, string>>;
+export declare const supervisorAuthenticationMacSchema: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorAuthenticationMac, string>>;
+export declare const supervisorClientNonceSchema: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorClientNonce, string>>;
+export declare const supervisorServerNonceSchema: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorServerNonce, string>>;
+export declare const shimProcessIdSchema: z.ZodPipe<z.ZodNumber, z.ZodTransform<ShimProcessId, number>>;
+export declare const processStartTokenSchema: z.ZodPipe<z.ZodString, z.ZodTransform<ProcessStartToken, string>>;
+export declare const controlledProcessIdentitySchema: z.ZodReadonly<z.ZodObject<{
+    pid: z.ZodPipe<z.ZodNumber, z.ZodTransform<ShimProcessId, number>>;
+    processStartToken: z.ZodPipe<z.ZodString, z.ZodTransform<ProcessStartToken, string>>;
+}, z.core.$strip>>;
+export declare const controlledProcessRecordSchema: z.ZodReadonly<z.ZodObject<{
+    protocolVersion: z.ZodLiteral<"alpacakit-supervisor-v1">;
+    platform: z.ZodEnum<{
+        darwin: "darwin";
+        linux: "linux";
+    }>;
+    bootId: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorBootId, string>>;
+    supervisorInstanceId: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorInstanceId, string>>;
+    recordId: z.ZodPipe<z.ZodString, z.ZodTransform<ControlledProcessRecordId, string>>;
+    socketLocator: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorSocketLocator, string>>;
+    pid: z.ZodPipe<z.ZodNumber, z.ZodTransform<ShimProcessId, number>>;
+    state: z.ZodEnum<{
+        absent: "absent";
+        reserved: "reserved";
+        acked: "acked";
+        running: "running";
+        term: "term";
+        kill_sent: "kill_sent";
+        released: "released";
+    }>;
+    absenceProof: z.ZodNullable<z.ZodEnum<{
+        supervisor_probe: "supervisor_probe";
+        boot_changed: "boot_changed";
+    }>>;
+}, z.core.$strip>>;
+export declare const signedControlledProcessRecordSchema: z.ZodReadonly<z.ZodObject<{
+    record: z.ZodReadonly<z.ZodObject<{
+        protocolVersion: z.ZodLiteral<"alpacakit-supervisor-v1">;
+        platform: z.ZodEnum<{
+            darwin: "darwin";
+            linux: "linux";
+        }>;
+        bootId: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorBootId, string>>;
+        supervisorInstanceId: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorInstanceId, string>>;
+        recordId: z.ZodPipe<z.ZodString, z.ZodTransform<ControlledProcessRecordId, string>>;
+        socketLocator: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorSocketLocator, string>>;
+        pid: z.ZodPipe<z.ZodNumber, z.ZodTransform<ShimProcessId, number>>;
+        state: z.ZodEnum<{
+            absent: "absent";
+            reserved: "reserved";
+            acked: "acked";
+            running: "running";
+            term: "term";
+            kill_sent: "kill_sent";
+            released: "released";
+        }>;
+        absenceProof: z.ZodNullable<z.ZodEnum<{
+            supervisor_probe: "supervisor_probe";
+            boot_changed: "boot_changed";
+        }>>;
+    }, z.core.$strip>>;
+    recordMac: z.ZodPipe<z.ZodString, z.ZodTransform<ControlledProcessRecordMac, string>>;
+}, z.core.$strip>>;
+export declare const supervisorClientChallengeSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"client_challenge">;
+    recordId: z.ZodPipe<z.ZodString, z.ZodTransform<ControlledProcessRecordId, string>>;
+    clientNonce: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorClientNonce, string>>;
+}, z.core.$strip>>;
+export declare const supervisorChallengeSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"supervisor_challenge">;
+    recordId: z.ZodPipe<z.ZodString, z.ZodTransform<ControlledProcessRecordId, string>>;
+    clientNonce: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorClientNonce, string>>;
+    serverNonce: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorServerNonce, string>>;
+    supervisorMac: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorAuthenticationMac, string>>;
+}, z.core.$strip>>;
+export declare const supervisorClientProofSchema: z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"client_proof">;
+    recordId: z.ZodPipe<z.ZodString, z.ZodTransform<ControlledProcessRecordId, string>>;
+    clientNonce: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorClientNonce, string>>;
+    serverNonce: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorServerNonce, string>>;
+    supervisorMac: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorAuthenticationMac, string>>;
+    clientMac: z.ZodPipe<z.ZodString, z.ZodTransform<SupervisorAuthenticationMac, string>>;
+}, z.core.$strip>>;
+export declare const childProcessTerminationResultSchema: z.ZodDiscriminatedUnion<[z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"absent">;
+    proof: z.ZodEnum<{
+        supervisor_probe: "supervisor_probe";
+        boot_changed: "boot_changed";
+        released_receipt: "released_receipt";
+    }>;
+}, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"pending">;
+    phase: z.ZodEnum<{
+        term_grace: "term_grace";
+        kill_probe: "kill_probe";
+    }>;
+    retryAfterMs: z.ZodNumber;
+}, z.core.$strip>>, z.ZodReadonly<z.ZodObject<{
+    kind: z.ZodLiteral<"unkillable">;
+    reason: z.ZodEnum<{
+        invalid_identity: "invalid_identity";
+        boot_identity_unavailable: "boot_identity_unavailable";
+        supervisor_unreachable: "supervisor_unreachable";
+        record_authentication_failed: "record_authentication_failed";
+        record_identity_mismatch: "record_identity_mismatch";
+        protocol_failure: "protocol_failure";
+        probe_permission_denied: "probe_permission_denied";
+        shim_lost_with_live_group: "shim_lost_with_live_group";
+        group_survived_sigkill: "group_survived_sigkill";
+    }>;
+}, z.core.$strip>>], "kind">;
+//# sourceMappingURL=schema.d.ts.map

package/dist/internal/controlled-process/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/internal/controlled-process/schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAWxB,OAAO,KAAK,EAEV,yBAAyB,EACzB,0BAA0B,EAC1B,iBAAiB,EACjB,aAAa,EAEb,2BAA2B,EAC3B,gBAAgB,EAChB,oBAAoB,EAGpB,qBAAqB,EAErB,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACxB,MAAM,YAAY,CAAC;AAcpB,eAAO,MAAM,oBAAoB,aAA8C,CAAC;AAEhF,eAAO,MAAM,+BAA+B;;;EAE3C,CAAC;AACF,eAAO,MAAM,4BAA4B;;;;;;;;EAExC,CAAC;AAEF,eAAO,MAAM,sBAAsB,kEAElC,CAAC;AACF,eAAO,MAAM,0BAA0B,sEAEtC,CAAC;AACF,eAAO,MAAM,+BAA+B,2EAE3C,CAAC;AACF,eAAO,MAAM,6BAA6B,yEAEzC,CAAC;AACF,eAAO,MAAM,0BAA0B,sEAEtC,CAAC;AACF,eAAO,MAAM,gCAAgC,4EAE5C,CAAC;AACF,eAAO,MAAM,iCAAiC,6EAE7C,CAAC;AACF,eAAO,MAAM,2BAA2B,uEAEvC,CAAC;AACF,eAAO,MAAM,2BAA2B,uEAEvC,CAAC;AACF,eAAO,MAAM,mBAAmB,+DAKe,CAAC;AAEhD,eAAO,MAAM,uBAAuB,mEAGe,CAAC;AAEpD,eAAO,MAAM,+BAA+B;;;kBAGA,CAAC;AAkB7C,eAAO,MAAM,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;kBAWO,CAAC;AAElD,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAGK,CAAC;AAEtD,eAAO,MAAM,+BAA+B;;;;kBAIK,CAAC;AAElD,eAAO,MAAM,yBAAyB;;;;;;kBAMK,CAAC;AAE5C,eAAO,MAAM,2BAA2B;;;;;;;kBAOK,CAAC;AAE9C,eAAO,MAAM,mCAAmC;;;;;;;;;;;;;;;;;;;;;;;;;;;4BAiBI,CAAC"}