@planu/cli 4.13.0 → 5.0.0

package/dist/engine/validation/validation-receipt-codec.js

@@ -0,0 +1,182 @@
+import { createHash, createHmac, timingSafeEqual } from 'node:crypto';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+export const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+export const PROJECT_ID = /^[a-f0-9]{32}$/u;
+export const SPEC_ID = /^SPEC-[1-9]\d*$/u;
+export const ISSUER_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
+const ARTIFACT_KEYS = [
+    'approvedSpec',
+    'discovery',
+    'taskPlan',
+    'traceability',
+    'contractValidation',
+];
+export function sha256(value) {
+    return `sha256:${createHash('sha256').update(value).digest('hex')}`;
+}
+export function canonicalize(value) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean') {
+        return JSON.stringify(value);
+    }
+    if (typeof value === 'number') {
+        if (!Number.isFinite(value)) {
+            throw new Error('[Planu] Receipt values must be finite');
+        }
+        return JSON.stringify(value);
+    }
+    if (Array.isArray(value)) {
+        return `[${value.map(canonicalize).join(',')}]`;
+    }
+    if (typeof value === 'object') {
+        const record = value;
+        return `{${Object.keys(record)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonicalize(record[key])}`)
+            .join(',')}}`;
+    }
+    throw new Error('[Planu] Receipt values must be JSON serializable');
+}
+function normalizedPart(value, label) {
+    const normalized = value.normalize('NFC').trim();
+    if (!normalized || normalized.includes('\0')) {
+        throw new Error(`[Planu] Invalid validation ${label}`);
+    }
+    return normalized;
+}
+export function normalizeValidationCommand(command) {
+    const executable = normalizedPart(command.executable, 'command');
+    const args = (command.args ?? []).map((arg) => normalizedPart(arg, 'command argument'));
+    const hasCwd = command.cwd !== undefined;
+    if (hasCwd) {
+        normalizedPart(command.cwd ?? '', 'working directory');
+    }
+    return JSON.stringify(hasCwd ? [executable, ...args, '<project>'] : [executable, ...args]);
+}
+export function validBindings(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    const artifacts = candidate.artifactDigests;
+    return (Object.keys(candidate).length === 7 &&
+        typeof candidate.projectId === 'string' &&
+        PROJECT_ID.test(candidate.projectId) &&
+        typeof candidate.specId === 'string' &&
+        SPEC_ID.test(candidate.specId) &&
+        ['sourceDigest', 'specDigest', 'policyDigest', 'toolchainDigest'].every((key) => typeof candidate[key] === 'string' && DIGEST.test(candidate[key])) &&
+        artifacts !== null &&
+        typeof artifacts === 'object' &&
+        Object.keys(artifacts).length === ARTIFACT_KEYS.length &&
+        ARTIFACT_KEYS.every((key) => {
+            const digest = artifacts[key];
+            return typeof digest === 'string' && DIGEST.test(digest);
+        }));
+}
+function normalizeVersions(versions) {
+    const entries = Object.entries(versions);
+    if (entries.length === 0) {
+        throw new Error('[Planu] Validation toolchain versions are required');
+    }
+    return Object.fromEntries(entries
+        .map(([name, version]) => [normalizedPart(name, 'version name'), normalizedPart(version, 'version')])
+        .sort(([left], [right]) => left.localeCompare(right)));
+}
+function normalizeGates(gates) {
+    if (gates.length === 0 || gates.some((gate) => gate.status !== 'passed')) {
+        throw new Error('[Planu] A receipt requires passing validation gates');
+    }
+    const names = new Set();
+    return gates.map((gate) => {
+        const name = normalizedPart(gate.gate, 'gate');
+        if (names.has(name) || !Number.isSafeInteger(gate.durationMs) || gate.durationMs < 0) {
+            throw new Error('[Planu] Validation gate results are invalid');
+        }
+        names.add(name);
+        return { gate: name, status: 'passed', durationMs: gate.durationMs };
+    });
+}
+function unsignedReceipt(receipt) {
+    const { authenticity: _authenticity, ...unsigned } = receipt;
+    return unsigned;
+}
+function proofFor(receipt, key) {
+    return createHmac('sha256', key)
+        .update(canonicalize(unsignedReceipt(receipt)))
+        .digest();
+}
+export function safeProof(receipt, key) {
+    try {
+        const received = Buffer.from(receipt.authenticity.proof, 'base64url');
+        const expected = proofFor(receipt, key);
+        return received.length === expected.length && timingSafeEqual(received, expected);
+    }
+    catch (error) {
+        /* reliability-optional: RECEIPT_SIGNATURE_INVALID — false is the fail-closed result */
+        reportClassifiedDegradation('RECEIPT_SIGNATURE_INVALID', error);
+        return false;
+    }
+}
+export function receiptCore(input, issuer, logDigest) {
+    if (!validBindings(input.bindings)) {
+        throw new Error('[Planu] Validation bindings require a canonical projectId and complete digests');
+    }
+    if (input.exitCode !== 0 || !Number.isSafeInteger(input.durationMs) || input.durationMs < 0) {
+        throw new Error('[Planu] A receipt requires passing validation with valid duration');
+    }
+    const issuedAt = input.issuedAt ?? new Date().toISOString();
+    if (new Date(issuedAt).toISOString() !== issuedAt) {
+        throw new Error('[Planu] Receipt issuedAt must be canonical ISO-8601');
+    }
+    return {
+        schemaVersion: 1,
+        issuer,
+        issuedAt,
+        bindings: structuredClone(input.bindings),
+        normalizedCommand: normalizeValidationCommand(input.command),
+        versions: normalizeVersions(input.versions),
+        exitCode: 0,
+        durationMs: input.durationMs,
+        logDigest,
+        gates: normalizeGates(input.gates),
+    };
+}
+function hasReceiptIdentity(candidate) {
+    return (candidate.schemaVersion === 1 &&
+        typeof candidate.receiptId === 'string' &&
+        DIGEST.test(candidate.receiptId) &&
+        typeof candidate.issuer === 'string' &&
+        ISSUER_ID.test(candidate.issuer) &&
+        typeof candidate.issuedAt === 'string' &&
+        Number.isFinite(Date.parse(candidate.issuedAt)));
+}
+function hasReceiptExecution(candidate) {
+    return (validBindings(candidate.bindings) &&
+        typeof candidate.normalizedCommand === 'string' &&
+        candidate.normalizedCommand.length > 0 &&
+        candidate.versions !== null &&
+        typeof candidate.versions === 'object' &&
+        candidate.exitCode === 0 &&
+        Number.isSafeInteger(candidate.durationMs) &&
+        candidate.durationMs >= 0 &&
+        typeof candidate.logDigest === 'string' &&
+        DIGEST.test(candidate.logDigest) &&
+        Array.isArray(candidate.gates) &&
+        candidate.gates.length > 0);
+}
+function hasReceiptAuthenticity(candidate) {
+    if (!candidate.authenticity || typeof candidate.authenticity !== 'object') {
+        return false;
+    }
+    const authenticity = candidate.authenticity;
+    return authenticity.algorithm === 'hmac-sha256' && typeof authenticity.proof === 'string';
+}
+export function validReceiptShape(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const candidate = value;
+    return (hasReceiptIdentity(candidate) &&
+        hasReceiptExecution(candidate) &&
+        hasReceiptAuthenticity(candidate));
+}
+//# sourceMappingURL=validation-receipt-codec.js.map

package/dist/engine/validation/validation-receipt.d.ts

@@ -0,0 +1,62 @@
+import type { ValidationReceipt, ValidationReceiptBindings, ValidationReceiptIssueInput, ValidationReceiptIssuerOptions, ValidationReceiptPersistence, ValidationReceiptVerification, ValidationReceiptVerificationOptions } from '../../types/validation-receipt.js';
+import type { RuntimeDatabase } from '../../storage/runtime-db.js';
+import { type StorageCatalogContext } from '../../storage/storage-catalog.js';
+export { normalizeValidationCommand } from './validation-receipt-codec.js';
+export declare const LOCAL_VALIDATION_RECEIPT_ISSUER = "planu-local-validator";
+export declare class ValidationReceiptStore implements ValidationReceiptPersistence {
+    private readonly options;
+    private readonly logDirectory;
+    constructor(options: {
+        readonly database: RuntimeDatabase;
+        readonly workspaceId: string;
+        readonly catalogContext?: StorageCatalogContext;
+        readonly authorizePersistence?: (database: RuntimeDatabase) => void;
+    });
+    logPath(logDigest: string): string;
+    persist(receipt: ValidationReceipt, log: Buffer): Promise<void>;
+    readReceipt(projectId: string, receiptId: string): Promise<ValidationReceipt | undefined>;
+    readCurrent(projectId: string, specId: string): Promise<ValidationReceipt | undefined>;
+    readCurrentBindings(projectId: string, specId: string): Promise<ValidationReceiptBindings | undefined>;
+    projectCurrentBindings(bindings: ValidationReceiptBindings): Promise<void>;
+    invalidateCurrentBindings(projectId: string, specId: string, receiptId?: string): Promise<void>;
+    readLog(logDigest: string): Promise<Buffer | undefined>;
+    private writeLog;
+}
+export declare function issueValidationReceipt(input: ValidationReceiptIssueInput, options: ValidationReceiptIssuerOptions): Promise<ValidationReceipt>;
+export declare function verifyValidationReceipt(value: unknown, options: ValidationReceiptVerificationOptions): Promise<ValidationReceiptVerification>;
+export declare function validationLogPath(store: ValidationReceiptPersistence, logDigest: string): string;
+export declare function readCurrentValidationReceipt(store: ValidationReceiptPersistence, identity: {
+    readonly projectId: string;
+    readonly specId: string;
+}): Promise<ValidationReceipt | undefined>;
+/** Trust bootstrap is explicit: construct once with locally provisioned opaque issuer references. */
+export declare class ValidationReceiptAuthority {
+    private readonly store;
+    private readonly trustedIssuers;
+    constructor(store: ValidationReceiptPersistence, trustedIssuers: Readonly<Record<string, string>>);
+    verifyCurrent(bindings: ValidationReceiptBindings): Promise<ValidationReceiptVerification>;
+}
+/** Construct the production verifier from runtime/catalog context without exposing key material. */
+export declare function createValidationReceiptAuthority(options: {
+    readonly database: RuntimeDatabase;
+    readonly workspaceId: string;
+    readonly projectId: string;
+    readonly issuerId: string;
+    readonly catalogContext?: StorageCatalogContext;
+    readonly authorizePersistence?: (database: RuntimeDatabase) => void;
+}): {
+    readonly authority: ValidationReceiptAuthority;
+    readonly store: ValidationReceiptStore;
+    readonly signingKeyReference: string;
+};
+/** Provision or resolve a machine-local issuer key without exposing raw key material. */
+export declare function ensureValidationIssuerKey(identity: {
+    readonly projectId: string;
+    readonly issuerId: string;
+}, platform?: NodeJS.Platform): Promise<string>;
+/** Prove that this process can resolve or provision its canonical receipt-signing key. */
+export declare function preflightValidationReceiptSigner(identity: {
+    readonly projectId: string;
+    readonly issuerId: string;
+}, platform?: NodeJS.Platform): Promise<string>;
+//# sourceMappingURL=validation-receipt.d.ts.map

package/dist/engine/validation/validation-receipt.js

@@ -0,0 +1,342 @@
+import { createHmac, randomBytes } from 'node:crypto';
+import { chmod, mkdir, open, readFile, rename, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { TextDecoder } from 'node:util';
+import { reportClassifiedDegradation } from '../../errors/classified-degradation.js';
+import { resolvedStorageArtifactPath, } from '../../storage/storage-catalog.js';
+import { formatSecretReference, getSecretProvider, parseSecretReference, SecretProviderError, } from '../../security/secret-provider.js';
+import { redactText } from '../../security/redactor.js';
+import { ValidationReceiptSignerUnavailableError } from '../macos-keychain-native-port.js';
+import { acquireLock, releaseLock } from '../safety/file-mutex.js';
+import { canonicalize, DIGEST, ISSUER_ID, PROJECT_ID, receiptCore, safeProof, sha256, SPEC_ID, validBindings, validReceiptShape, } from './validation-receipt-codec.js';
+export { normalizeValidationCommand } from './validation-receipt-codec.js';
+export const LOCAL_VALIDATION_RECEIPT_ISSUER = 'planu-local-validator';
+export class ValidationReceiptStore {
+    options;
+    logDirectory;
+    constructor(options) {
+        this.options = options;
+        this.logDirectory = resolvedStorageArtifactPath('validation-logs', options.catalogContext);
+    }
+    logPath(logDigest) {
+        if (!DIGEST.test(logDigest)) {
+            throw new Error('[Planu] Invalid validation log digest');
+        }
+        return join(this.logDirectory, `${logDigest.slice('sha256:'.length)}.log`);
+    }
+    async persist(receipt, log) {
+        if (sha256(log) !== receipt.logDigest) {
+            throw new Error('[Planu] Validation log digest mismatch');
+        }
+        await this.writeLog(receipt.logDigest, log);
+        this.options.database.transaction(() => {
+            this.options.authorizePersistence?.(this.options.database);
+            this.options.database.putRecord({
+                projectId: receipt.bindings.projectId,
+                workspaceId: this.options.workspaceId,
+                kind: 'audit-state',
+                key: `validation-receipt:${receipt.receiptId.slice('sha256:'.length)}`,
+                value: receipt,
+                sourceDigest: receipt.receiptId,
+            });
+            this.options.database.putRecord({
+                projectId: receipt.bindings.projectId,
+                workspaceId: this.options.workspaceId,
+                kind: 'audit-state',
+                key: `validation-current:${receipt.bindings.specId}`,
+                value: receipt,
+                sourceDigest: receipt.receiptId,
+            });
+            this.options.database.putRecord({
+                projectId: receipt.bindings.projectId,
+                workspaceId: this.options.workspaceId,
+                kind: 'audit-state',
+                key: `validation-bindings-current:${receipt.bindings.specId}`,
+                value: receipt.bindings,
+                sourceDigest: receipt.receiptId,
+            });
+        });
+    }
+    readReceipt(projectId, receiptId) {
+        if (!PROJECT_ID.test(projectId) || !DIGEST.test(receiptId)) {
+            return Promise.resolve(undefined);
+        }
+        const record = this.options.database.getRecord(projectId, this.options.workspaceId, 'audit-state', `validation-receipt:${receiptId.slice('sha256:'.length)}`);
+        return Promise.resolve(validReceiptShape(record?.value) ? record.value : undefined);
+    }
+    readCurrent(projectId, specId) {
+        if (!PROJECT_ID.test(projectId) || !SPEC_ID.test(specId)) {
+            return Promise.resolve(undefined);
+        }
+        const record = this.options.database.getRecord(projectId, this.options.workspaceId, 'audit-state', `validation-current:${specId}`);
+        return Promise.resolve(validReceiptShape(record?.value) ? record.value : undefined);
+    }
+    readCurrentBindings(projectId, specId) {
+        if (!PROJECT_ID.test(projectId) || !SPEC_ID.test(specId)) {
+            return Promise.resolve(undefined);
+        }
+        const record = this.options.database.getRecord(projectId, this.options.workspaceId, 'audit-state', `validation-bindings-current:${specId}`);
+        return Promise.resolve(validBindings(record?.value) ? record.value : undefined);
+    }
+    projectCurrentBindings(bindings) {
+        if (!validBindings(bindings)) {
+            throw new Error('[Planu] Current validation bindings are invalid');
+        }
+        this.options.database.putRecord({
+            projectId: bindings.projectId,
+            workspaceId: this.options.workspaceId,
+            kind: 'audit-state',
+            key: `validation-bindings-current:${bindings.specId}`,
+            value: bindings,
+            sourceDigest: sha256(canonicalize(bindings)),
+        });
+        return Promise.resolve();
+    }
+    invalidateCurrentBindings(projectId, specId, receiptId) {
+        if (!PROJECT_ID.test(projectId) ||
+            !SPEC_ID.test(specId) ||
+            (receiptId !== undefined && !DIGEST.test(receiptId))) {
+            throw new Error('[Planu] Validation binding identity is invalid');
+        }
+        this.options.database.transaction(() => {
+            if (receiptId !== undefined) {
+                const current = this.options.database.getRecord(projectId, this.options.workspaceId, 'audit-state', `validation-current:${specId}`);
+                if (!validReceiptShape(current?.value) || current.value.receiptId !== receiptId) {
+                    return;
+                }
+            }
+            this.options.database.putRecord({
+                projectId,
+                workspaceId: this.options.workspaceId,
+                kind: 'audit-state',
+                key: `validation-bindings-current:${specId}`,
+                value: { invalidatedAt: new Date().toISOString() },
+            });
+        });
+        return Promise.resolve();
+    }
+    async readLog(logDigest) {
+        try {
+            return await readFile(this.logPath(logDigest));
+        }
+        catch (error) {
+            if (error.code === 'ENOENT') {
+                return undefined;
+            }
+            throw error;
+        }
+    }
+    async writeLog(logDigest, log) {
+        await mkdir(this.logDirectory, { recursive: true, mode: 0o700 });
+        await chmod(this.logDirectory, 0o700);
+        const target = this.logPath(logDigest);
+        const temporary = `${target}.tmp.${process.pid.toString()}.${randomBytes(4).toString('hex')}`;
+        try {
+            const handle = await open(temporary, 'wx', 0o600);
+            await handle.write(log);
+            await handle.datasync();
+            await handle.close();
+            await rename(temporary, target);
+            await chmod(target, 0o600);
+        }
+        catch (error) {
+            await unlink(temporary).catch((cleanupError) => {
+                /* reliability-cleanup: VALIDATION_TEMP_UNLINK — original persistence error remains authoritative */
+                reportClassifiedDegradation('VALIDATION_TEMP_UNLINK', cleanupError);
+            });
+            if (error.code !== 'EEXIST') {
+                throw error;
+            }
+            const existing = await readFile(target);
+            if (sha256(existing) !== logDigest) {
+                throw new Error('[Planu] Existing validation log failed digest verification', {
+                    cause: error,
+                });
+            }
+        }
+    }
+}
+export async function issueValidationReceipt(input, options) {
+    if (!ISSUER_ID.test(options.issuerId)) {
+        throw new Error('[Planu] Invalid validation receipt issuer');
+    }
+    const signingKey = await getSecretProvider().resolve(parseSecretReference(options.signingKeyReference));
+    if (Buffer.byteLength(signingKey) < 32) {
+        throw new Error('[Planu] Validation issuer key is too short');
+    }
+    const decodedLog = Buffer.isBuffer(input.log)
+        ? new TextDecoder('utf-8', { fatal: true }).decode(input.log)
+        : input.log;
+    const log = Buffer.from(redactText(decodedLog), 'utf8');
+    const core = receiptCore(input, options.issuerId, sha256(log));
+    const receiptId = sha256(canonicalize(core));
+    const unsigned = { ...core, receiptId };
+    const proof = createHmac('sha256', signingKey).update(canonicalize(unsigned)).digest('base64url');
+    const receipt = {
+        ...unsigned,
+        authenticity: { algorithm: 'hmac-sha256', proof },
+    };
+    await options.store.persist(receipt, log);
+    return receipt;
+}
+export async function verifyValidationReceipt(value, options) {
+    if (typeof value === 'object' &&
+        value !== null &&
+        'schemaVersion' in value &&
+        value.schemaVersion !== 1) {
+        return { valid: false, reason: 'unsupported-version' };
+    }
+    if (!validReceiptShape(value) || !validBindings(options.bindings)) {
+        return { valid: false, reason: 'invalid-schema' };
+    }
+    const keyReference = options.trustedIssuers[value.issuer];
+    if (!keyReference) {
+        return { valid: false, reason: 'unknown-issuer' };
+    }
+    let key;
+    try {
+        key = await getSecretProvider().resolve(parseSecretReference(keyReference));
+    }
+    catch {
+        return { valid: false, reason: 'invalid-authenticity' };
+    }
+    if (!safeProof(value, key)) {
+        return { valid: false, reason: 'invalid-authenticity' };
+    }
+    if (canonicalize(value.bindings) !== canonicalize(options.bindings)) {
+        return { valid: false, reason: 'stale-bindings' };
+    }
+    const persisted = await options.store.readReceipt(value.bindings.projectId, value.receiptId);
+    if (!persisted || canonicalize(persisted) !== canonicalize(value)) {
+        return { valid: false, reason: 'missing-receipt' };
+    }
+    const log = await options.store.readLog(value.logDigest);
+    if (!log) {
+        return { valid: false, reason: 'missing-log' };
+    }
+    if (sha256(log) !== value.logDigest) {
+        return { valid: false, reason: 'invalid-log' };
+    }
+    return { valid: true };
+}
+export function validationLogPath(store, logDigest) {
+    return store.logPath(logDigest);
+}
+export function readCurrentValidationReceipt(store, identity) {
+    return store.readCurrent(identity.projectId, identity.specId);
+}
+/** Trust bootstrap is explicit: construct once with locally provisioned opaque issuer references. */
+export class ValidationReceiptAuthority {
+    store;
+    trustedIssuers;
+    constructor(store, trustedIssuers) {
+        this.store = store;
+        this.trustedIssuers = trustedIssuers;
+    }
+    async verifyCurrent(bindings) {
+        const receipt = await this.store.readCurrent(bindings.projectId, bindings.specId);
+        if (!receipt) {
+            return { valid: false, reason: 'missing-receipt' };
+        }
+        return verifyValidationReceipt(receipt, {
+            bindings,
+            trustedIssuers: this.trustedIssuers,
+            store: this.store,
+        });
+    }
+}
+function validationIssuerReference(identity) {
+    if (!PROJECT_ID.test(identity.projectId)) {
+        throw new Error('[Planu] Validation issuer requires a canonical projectId');
+    }
+    if (!ISSUER_ID.test(identity.issuerId)) {
+        throw new Error('[Planu] Invalid validation receipt issuer');
+    }
+    return formatSecretReference(getSecretProvider().reference(`${identity.projectId}/validation/issuer/${identity.issuerId}`, 'validation-signing'));
+}
+/** Construct the production verifier from runtime/catalog context without exposing key material. */
+export function createValidationReceiptAuthority(options) {
+    const store = new ValidationReceiptStore(options);
+    const signingKeyReference = validationIssuerReference(options);
+    return {
+        store,
+        signingKeyReference,
+        authority: new ValidationReceiptAuthority(store, {
+            [options.issuerId]: signingKeyReference,
+        }),
+    };
+}
+/** Provision or resolve a machine-local issuer key without exposing raw key material. */
+export async function ensureValidationIssuerKey(identity, platform = process.platform) {
+    const canonicalProvider = platform === 'darwin'
+        ? 'macos-keychain'
+        : platform === 'linux'
+            ? 'linux-secret-service'
+            : platform === 'win32'
+                ? 'windows-credential-manager'
+                : undefined;
+    if (canonicalProvider === undefined) {
+        throw new ValidationReceiptSignerUnavailableError('PLATFORM_UNSUPPORTED');
+    }
+    let provider;
+    try {
+        provider = getSecretProvider();
+    }
+    catch {
+        throw new ValidationReceiptSignerUnavailableError('PROVIDER_UNAVAILABLE');
+    }
+    if (provider.adapter.kind !== canonicalProvider) {
+        throw new ValidationReceiptSignerUnavailableError('PROVIDER_NONCANONICAL');
+    }
+    const reference = parseSecretReference(validationIssuerReference(identity));
+    let lock;
+    try {
+        lock = await acquireLock(`validation-issuer:${identity.projectId}:${identity.issuerId}`);
+    }
+    catch {
+        throw new ValidationReceiptSignerUnavailableError('PROVIDER_UNAVAILABLE');
+    }
+    let result;
+    try {
+        try {
+            await provider.resolve(reference);
+            result = formatSecretReference(reference);
+        }
+        catch (error) {
+            if (!(error instanceof SecretProviderError) || error.code !== 'SECRET_NOT_FOUND') {
+                throw new ValidationReceiptSignerUnavailableError('PROVIDER_UNAVAILABLE');
+            }
+            try {
+                await provider.store(reference, randomBytes(32).toString('base64url'));
+                result = formatSecretReference(reference);
+            }
+            catch {
+                throw new ValidationReceiptSignerUnavailableError('PROVIDER_UNAVAILABLE');
+            }
+        }
+    }
+    catch (error) {
+        try {
+            await releaseLock(lock);
+        }
+        catch {
+            reportClassifiedDegradation('VALIDATION_ISSUER_LOCK_RELEASE_FAILURE', new Error('Validation issuer lock release failed'));
+        }
+        if (error instanceof ValidationReceiptSignerUnavailableError) {
+            throw error;
+        }
+        throw new ValidationReceiptSignerUnavailableError('PROVIDER_UNAVAILABLE');
+    }
+    try {
+        await releaseLock(lock);
+    }
+    catch {
+        throw new ValidationReceiptSignerUnavailableError('PROVIDER_UNAVAILABLE');
+    }
+    return result;
+}
+/** Prove that this process can resolve or provision its canonical receipt-signing key. */
+export function preflightValidationReceiptSigner(identity, platform = process.platform) {
+    return ensureValidationIssuerKey(identity, platform);
+}
+//# sourceMappingURL=validation-receipt.js.map

package/dist/engine/validation/validation-source-digest.d.ts

@@ -0,0 +1,2 @@
+export declare function gitSourceTreeDigest(projectPath: string): Promise<string>;
+//# sourceMappingURL=validation-source-digest.d.ts.map

package/dist/engine/validation/validation-source-digest.js

@@ -0,0 +1,86 @@
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { isValidationSourcePath } from './validation-source-policy.js';
+const execFileAsync = promisify(execFile);
+const SOURCE_DIGEST_MAX_CONCURRENCY = 8;
+async function mapWithConcurrency(values, concurrency, worker) {
+    const results = new Array(values.length);
+    let cursor = 0;
+    const runners = Array.from({ length: Math.min(concurrency, values.length) }, async () => {
+        for (;;) {
+            const index = cursor;
+            cursor += 1;
+            if (index >= values.length) {
+                return;
+            }
+            results[index] = await worker(values[index]);
+        }
+    });
+    await Promise.all(runners);
+    return results;
+}
+export async function gitSourceTreeDigest(projectPath) {
+    try {
+        const gitOptions = { cwd: projectPath, encoding: 'utf8', maxBuffer: 16 * 1024 * 1024 };
+        const [trackedResult, untrackedResult] = await Promise.all([
+            execFileAsync('git', ['ls-files', '--cached', '-z'], gitOptions),
+            execFileAsync('git', ['ls-files', '--others', '--exclude-standard', '-z'], gitOptions),
+        ]);
+        const sourceEntries = (stdout) => stdout
+            .split('\0')
+            .filter(Boolean)
+            .map((sourcePath) => ({ sourcePath, canonicalPath: sourcePath.normalize('NFC') }))
+            .filter(({ canonicalPath }) => isValidationSourcePath(canonicalPath));
+        const entriesToRead = [
+            ...sourceEntries(trackedResult.stdout),
+            ...sourceEntries(untrackedResult.stdout),
+        ].sort((left, right) => Buffer.compare(Buffer.from(left.canonicalPath), Buffer.from(right.canonicalPath)));
+        if (new Set(entriesToRead.map(({ canonicalPath }) => canonicalPath)).size !== entriesToRead.length) {
+            throw new Error('source paths collide after Unicode normalization');
+        }
+        const entries = await mapWithConcurrency(entriesToRead, SOURCE_DIGEST_MAX_CONCURRENCY, async (entry) => {
+            const { canonicalPath: path, sourcePath } = entry;
+            const absolutePath = join(projectPath, sourcePath);
+            try {
+                const stats = await lstat(absolutePath);
+                if (stats.isSymbolicLink()) {
+                    const target = (await readlink(absolutePath)).normalize('NFC');
+                    return { path, content: Buffer.from(`symlink\0${target}`, 'utf8') };
+                }
+                if (!stats.isFile()) {
+                    throw new Error(`unsupported source entry type: ${path}`);
+                }
+                return {
+                    path,
+                    content: Buffer.concat([Buffer.from('file\0'), await readFile(absolutePath)]),
+                };
+            }
+            catch (error) {
+                if (error.code === 'ENOENT') {
+                    return undefined;
+                }
+                throw error;
+            }
+        });
+        const hash = createHash('sha256');
+        hash.update('planu-source-v1\0');
+        for (const entry of entries) {
+            if (!entry) {
+                continue;
+            }
+            const pathBytes = Buffer.from(entry.path, 'utf8');
+            hash.update(`${pathBytes.length}:`);
+            hash.update(pathBytes);
+            hash.update(`${entry.content.length}:`);
+            hash.update(entry.content);
+        }
+        return `sha256:${hash.digest('hex')}`;
+    }
+    catch (error) {
+        throw new Error('[Planu] Unable to bind validation to the source tree', { cause: error });
+    }
+}
+//# sourceMappingURL=validation-source-digest.js.map

package/dist/engine/validation/validation-source-policy.d.ts

@@ -0,0 +1,4 @@
+/** Generated/runtime roots are not validation source, even when accidentally tracked. */
+export declare const SOURCE_IGNORED_ROOTS: Set<string>;
+export declare function isValidationSourcePath(path: string): boolean;
+//# sourceMappingURL=validation-source-policy.d.ts.map