@timurproko/a1 0.1.8-dev.ece8cef → 0.2.0

package/dist/foundation/release/dependency-certification.js

@@ -0,0 +1,266 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { immutablePlatformPolicy } from "./immutable-platform.js";
+export const DEPENDENCY_CERTIFICATIONS_DIRECTORY = "dependency-certifications";
+/** Derive the canonical record path without accepting path components as layer identities. */
+export function dependencyLayerCertificationPath(dataDir, layerId) {
+    assertLayerId(layerId);
+    return resolve(dataDir, DEPENDENCY_CERTIFICATIONS_DIRECTORY, `${layerId}.json`);
+}
+/** Keep the historical filename solely for compatibility reads and managed cleanup. */
+export function legacyDependencyLayerCertificationPath(dataDir, layerId) {
+    assertLayerId(layerId);
+    return resolve(dataDir, `dependency-layer-certification-${layerId}.json`);
+}
+/** Validate the dedicated directory before reading, creating, or deleting any contained record. */
+export async function dependencyCertificationDirectory(dataDir, create = false) {
+    const canonicalData = await realpath(dataDir);
+    const directory = resolve(canonicalData, DEPENDENCY_CERTIFICATIONS_DIRECTORY);
+    if (create)
+        await mkdir(directory, { mode: 0o700 }).catch(error => {
+            if (!hasCode(error, "EEXIST"))
+                throw error;
+        });
+    const metadata = await lstat(directory).catch(missingOrThrow);
+    if (metadata === null)
+        return null;
+    if (!metadata.isDirectory() || metadata.isSymbolicLink() || await realpath(directory) !== directory) {
+        throw new Error("dependency certification directory is not a managed non-link directory");
+    }
+    return directory;
+}
+/** Resolve only direct regular managed records; callers never follow directory or record links. */
+export async function managedDependencyCertificationPath(dataDir, layerId, legacy = false) {
+    const canonicalData = await realpath(dataDir);
+    const path = legacy ? legacyDependencyLayerCertificationPath(canonicalData, layerId) : dependencyLayerCertificationPath(canonicalData, layerId);
+    if (!legacy && await dependencyCertificationDirectory(canonicalData) === null)
+        return null;
+    const metadata = await lstat(path).catch(missingOrThrow);
+    if (metadata === null)
+        return null;
+    if (!metadata.isFile() || metadata.isSymbolicLink() || await realpath(path) !== path) {
+        throw new Error(`dependency certification is not a managed regular file: ${path}`);
+    }
+    return path;
+}
+/** Prefer canonical evidence; copy validated legacy evidence without changing its sealed source. */
+export async function readDependencyCertification(dataDir, identity, options = {}) {
+    const canonical = await managedDependencyCertificationPath(dataDir, identity.layerId);
+    const source = canonical ?? (options.canonicalOnly ? null : await managedDependencyCertificationPath(dataDir, identity.layerId, true));
+    if (source === null)
+        throw new Error(`dependency layer certification is absent: ${identity.layerId}`);
+    const document = JSON.parse(await readFile(source, "utf8"));
+    const legacyPlatform = validateCertification(document, identity, options.allowLegacyParentCertification === true);
+    if (!legacyPlatform && ((await lstat(source)).mode & 0o222) !== 0)
+        throw new Error("dependency certification is writable");
+    if (legacyPlatform) {
+        // Compatibility: only the authenticated parent path may replace older platform-less evidence.
+        await writeDependencyCertification(dataDir, identity);
+    }
+    else if (canonical === null) {
+        await publishCertification(dataDir, identity, document, false);
+    }
+}
+/** Publish certification after materialization/full verification, preserving an already-valid winner. */
+export async function writeDependencyCertification(dataDir, identity) {
+    await publishCertification(dataDir, identity, {
+        schema: PRODUCT_IDENTITY.evidence.dependencyLayerCertificationSchema,
+        layerId: identity.layerId,
+        contentDigest: identity.contentDigest,
+        platform: process.platform,
+        platformPolicy: immutablePlatformPolicy(),
+        certifiedAt: new Date().toISOString(),
+    }, true);
+}
+async function publishCertification(dataDir, identity, document, replaceInvalid) {
+    const directory = (await dependencyCertificationDirectory(dataDir, true));
+    const path = dependencyLayerCertificationPath(dirname(directory), identity.layerId);
+    const lockPath = `${path}.lock`;
+    const releaseLock = await acquirePublicationLock(lockPath);
+    try {
+        await publishLockedCertification(dataDir, identity, document, replaceInvalid, path);
+    }
+    catch (publicationError) {
+        try {
+            await releaseLock();
+        }
+        catch (releaseError) {
+            throw new AggregateError([publicationError, releaseError], "dependency certification publication and lease release failed");
+        }
+        throw publicationError;
+    }
+    await releaseLock();
+}
+async function publishLockedCertification(dataDir, identity, document, replaceInvalid, path) {
+    const existing = await managedDependencyCertificationPath(dataDir, identity.layerId);
+    if (existing !== null) {
+        const source = await readFile(existing, "utf8");
+        const metadata = await lstat(existing);
+        try {
+            validateCertification(JSON.parse(source), identity);
+            // Invariant: full verification restores writable evidence; ordinary valid reuse is read-only.
+            if ((metadata.mode & 0o222) === 0)
+                return;
+            if (!replaceInvalid)
+                throw new Error("dependency certification is writable");
+        }
+        catch (error) {
+            if (!replaceInvalid)
+                throw error;
+        }
+        await rm(existing, { force: true });
+    }
+    const temporary = `${path}.${process.pid}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporary, JSON.stringify(document, null, 2), { flag: "wx", mode: 0o400 });
+        await chmod(temporary, 0o400);
+        await dependencyCertificationDirectory(dataDir);
+        // Concurrency: the per-layer lease protects the winner check and atomic publication together.
+        // Rename publishes final read-only metadata; no later temporary unlink changes sealed evidence.
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+async function acquirePublicationLock(path) {
+    const token = randomUUID();
+    const candidate = `${path}.candidate-${token}`;
+    await mkdir(candidate, { mode: 0o700 });
+    try {
+        await writeFile(resolve(candidate, "owner.json"), JSON.stringify({ pid: process.pid, token }), { flag: "wx", mode: 0o600 });
+        const deadline = Date.now() + 5_000;
+        while (true) {
+            try {
+                // Concurrency: a nonempty directory cannot replace another nonempty directory on either
+                // platform. Publishing the complete owner atomically also avoids partially written leases.
+                await rename(candidate, path);
+                return () => releasePublicationLock(path, token);
+            }
+            catch (error) {
+                if (!["EEXIST", "ENOTEMPTY", "EPERM", "EACCES"].some(code => hasCode(error, code)))
+                    throw error;
+                const metadata = await lstat(path).catch(missingOrThrow);
+                if (metadata !== null) {
+                    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+                        throw new Error("dependency certification publication lock is not a managed directory");
+                    const ownerPath = resolve(path, "owner.json");
+                    const ownerMetadata = await lstat(ownerPath).catch(missingOrThrow);
+                    if (ownerMetadata !== null) {
+                        if (!ownerMetadata.isFile() || ownerMetadata.isSymbolicLink())
+                            throw new Error("dependency certification publication owner is not a regular file");
+                        const owner = await readFile(ownerPath, "utf8").then(source => JSON.parse(source)).catch(error => {
+                            if (hasCode(error, "ENOENT"))
+                                return null;
+                            throw error;
+                        });
+                        if (owner !== null && Number.isSafeInteger(owner.pid) && owner.pid > 0 && /^[a-f0-9-]{36}$/.test(owner.token)) {
+                            let abandoned = false;
+                            try {
+                                process.kill(owner.pid, 0);
+                            }
+                            catch (probeError) {
+                                abandoned = hasCode(probeError, "ESRCH");
+                            }
+                            if (abandoned) {
+                                // Concurrency: retain this generation's nonempty tombstone. A delayed second reclaimer
+                                // cannot overwrite it and accidentally steal a newly acquired replacement lease.
+                                await rename(path, `${path}.abandoned-${owner.token}`).catch(error => {
+                                    if (!["ENOENT", "EEXIST", "ENOTEMPTY", "EPERM", "EACCES"].some(code => hasCode(error, code)))
+                                        throw error;
+                                });
+                            }
+                        }
+                    }
+                }
+                if (Date.now() >= deadline)
+                    throw new Error("dependency certification publication is busy");
+                await new Promise(resolvePromise => setTimeout(resolvePromise, 20));
+            }
+        }
+    }
+    finally {
+        await rm(candidate, { recursive: true, force: true });
+    }
+}
+/** Retire this generation once; retries after retirement can only touch its private cleanup path. */
+async function releasePublicationLock(path, token) {
+    const released = `${path}.released-${token}`;
+    const deadline = Date.now() + 1_000;
+    let retired = false;
+    let delay = 20;
+    while (true) {
+        try {
+            if (!retired) {
+                await assertPublicationLockOwner(path, token);
+                await rename(path, released);
+                retired = true;
+            }
+            // Concurrency: a successor can own `path` now. Never inspect or delete it during cleanup.
+            await rm(released, { recursive: true, force: true });
+            return;
+        }
+        catch (error) {
+            const phase = retired ? "cleanup" : "retirement";
+            if (!isReleaseContention(error)) {
+                throw new Error(`dependency certification lease release ${phase} failed: ${error instanceof Error ? error.message : "unknown error"}`, { cause: error });
+            }
+            const remaining = deadline - Date.now();
+            if (remaining <= 0) {
+                throw new Error(`dependency certification lease release ${phase} deadline exceeded (${error.code})`, { cause: error });
+            }
+            await new Promise(resolvePromise => setTimeout(resolvePromise, Math.min(delay, remaining)));
+            delay = Math.min(delay * 2, 100);
+        }
+    }
+}
+/** Ownership uncertainty is never authority to retire a missing, linked, or replaced generation. */
+async function assertPublicationLockOwner(path, token) {
+    try {
+        const metadata = await lstat(path);
+        if (!metadata.isDirectory() || metadata.isSymbolicLink() || await realpath(path) !== path)
+            throw new Error("invalid lock directory");
+        const ownerPath = resolve(path, "owner.json");
+        const ownerMetadata = await lstat(ownerPath);
+        if (!ownerMetadata.isFile() || ownerMetadata.isSymbolicLink() || await realpath(ownerPath) !== ownerPath)
+            throw new Error("invalid owner file");
+        const owner = JSON.parse(await readFile(ownerPath, "utf8"));
+        if (!owner || typeof owner !== "object" || !("pid" in owner) || !("token" in owner)
+            || owner.pid !== process.pid || owner.token !== token)
+            throw new Error("owner generation differs");
+    }
+    catch (error) {
+        if (isReleaseContention(error))
+            throw error;
+        throw new Error("publication lease release ownership could not be verified", { cause: error });
+    }
+}
+function isReleaseContention(error) {
+    return ["EPERM", "EACCES", "EBUSY"].some(code => hasCode(error, code));
+}
+function validateCertification(value, identity, allowLegacyPlatform = false) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`dependency layer certification differs from manifest: ${identity.layerId}`);
+    const certification = value;
+    const identityMatches = certification.schema === PRODUCT_IDENTITY.evidence.dependencyLayerCertificationSchema
+        && certification.layerId === identity.layerId && certification.contentDigest === identity.contentDigest;
+    const currentPlatform = certification.platform === process.platform && certification.platformPolicy === immutablePlatformPolicy();
+    const legacyPlatform = allowLegacyPlatform && certification.platform === undefined && certification.platformPolicy === undefined;
+    if (!identityMatches || (!currentPlatform && !legacyPlatform))
+        throw new Error(`dependency layer certification differs from manifest: ${identity.layerId}`);
+    return legacyPlatform;
+}
+function assertLayerId(layerId) {
+    if (!/^dependencies-[a-f0-9]{32}$/.test(layerId))
+        throw new Error(`invalid dependency layer identity: ${layerId}`);
+}
+function hasCode(error, code) {
+    return error instanceof Error && "code" in error && error.code === code;
+}
+function missingOrThrow(error) {
+    if (hasCode(error, "ENOENT"))
+        return null;
+    throw error;
+}

package/dist/foundation/release/dependency-layer.d.ts

@@ -0,0 +1,78 @@
+import { type ReadDependencyCertificationOptions } from "./dependency-certification.js";
+export { dependencyLayerCertificationPath, legacyDependencyLayerCertificationPath } from "./dependency-certification.js";
+import { type ReleaseFileIdentity } from "./release.js";
+import type { DependencyLayerReference } from "./types.js";
+export type { DependencyLayerReference } from "./types.js";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+export declare const DEPENDENCY_LAYER_SCHEMA: string;
+export declare const DEPENDENCY_LAYER_MANIFEST = "dependency-layer-manifest.json";
+export declare const RUNTIME_PAYLOAD_INVENTORY = "dist/runtime-payload-inventory.json";
+export interface RuntimePayloadExclusion {
+    readonly path: string;
+    readonly reason: "type-declaration" | "source-map" | "unreachable-development";
+}
+export interface RuntimePayloadInventory {
+    readonly schema: typeof PRODUCT_IDENTITY.evidence.runtimePayloadSchema;
+    readonly includedFiles: number;
+    readonly includedBytes: number;
+    readonly excludedFiles: number;
+    readonly excludedBytes: number;
+    readonly uncertaintyRetainedFiles: number;
+    readonly exclusions: readonly RuntimePayloadExclusion[];
+}
+export interface DependencyLayerIdentity {
+    readonly schema: typeof DEPENDENCY_LAYER_SCHEMA;
+    readonly layerId: string;
+    readonly contentDigest: string;
+    readonly files: readonly ReleaseFileIdentity[];
+    readonly inventory: RuntimePayloadInventory;
+}
+export interface MaterializedDependencyLayer extends DependencyLayerIdentity {
+    readonly layerRoot: string;
+    readonly reused: boolean;
+}
+export interface DependencyLayerOperationEvent {
+    readonly operation: "source-read" | "layer-write" | "layer-reuse" | "verification-read";
+    readonly path: string;
+    readonly bytes: number;
+}
+export interface ReadCertifiedDependencyLayerOptions extends ReadDependencyCertificationOptions {
+}
+export interface SelectedRuntimePayload {
+    readonly paths: readonly string[];
+    readonly inventory: RuntimePayloadInventory;
+}
+export interface PublishedRuntimeFileClassification {
+    readonly packageName: string;
+    readonly packageVersion: string;
+    readonly packagePath: string;
+    readonly disposition: "include" | "exclude";
+    readonly reason?: RuntimePayloadExclusion["reason"];
+}
+export interface GeneratedRuntimePayload extends SelectedRuntimePayload {
+    readonly classifications: readonly PublishedRuntimeFileClassification[];
+}
+export interface PublishedRuntimePayload extends GeneratedRuntimePayload {
+    readonly schema: typeof PRODUCT_IDENTITY.evidence.runtimePayloadSchema;
+    readonly entryPoints: readonly string[];
+    readonly declaredAssets: readonly string[];
+}
+/** Consume topology-independent publication classifications, retaining unknown installed content. */
+export declare function selectPublishedDependencyRuntimePayload(packageRoot: string, paths: readonly string[]): Promise<SelectedRuntimePayload>;
+/** Generate publication evidence from literal module reachability and declared runtime assets. */
+export declare function generateDependencyRuntimePayload(packageRoot: string, allPaths: readonly string[], productPaths: readonly string[]): Promise<GeneratedRuntimePayload>;
+/** Conservatively omit only files Node never executes; uncertain assets remain selected. */
+export declare function selectDependencyRuntimePayload(packageRoot: string, paths: readonly string[]): Promise<SelectedRuntimePayload>;
+export interface MaterializeDependencyLayerOptions {
+    readonly inventory: RuntimePayloadInventory;
+    readonly cachedFiles?: ReadonlyMap<string, Buffer>;
+    readonly onOperation?: (event: DependencyLayerOperationEvent) => void;
+    readonly writeCandidateFile?: (path: string, bytes: Uint8Array, mode: number) => Promise<void>;
+}
+/** Materialize or reuse an exact immutable dependency layer after one source-content pass. */
+export declare function materializeDependencyLayer(packageRoot: string, dataDir: string, paths: readonly string[], options: MaterializeDependencyLayerOptions): Promise<MaterializedDependencyLayer | null>;
+/** Read trusted layer certification and canonical metadata without rereading every payload byte. */
+export declare function readCertifiedDependencyLayer(dataDir: string, layerId: string, expected?: Pick<DependencyLayerIdentity, "layerId" | "contentDigest">, options?: ReadCertifiedDependencyLayerOptions): Promise<Omit<MaterializedDependencyLayer, "reused">>;
+/** Fully verify a layer when certification is absent or explicit tamper evidence is required. */
+export declare function verifyDependencyLayer(dataDir: string, reference: DependencyLayerReference, onOperation?: (event: DependencyLayerOperationEvent) => void): Promise<Omit<MaterializedDependencyLayer, "reused">>;
+export declare function dependencyReference(layer: MaterializedDependencyLayer): DependencyLayerReference;