@timurproko/a1 0.1.8-dev.ece8cef → 0.2.0

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

@@ -0,0 +1,466 @@
+import { randomUUID } from "node:crypto";
+import { chmod, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, posix, relative, resolve, sep } from "node:path";
+import { mapWithConcurrency } from "./concurrency.js";
+import { assertImmutableFileMode } from "./immutable-platform.js";
+import { readDependencyCertification, writeDependencyCertification as writeLayerCertification } from "./dependency-certification.js";
+export { dependencyLayerCertificationPath, legacyDependencyLayerCertificationPath } from "./dependency-certification.js";
+import { digestManifestFiles, releaseFileIdentity, resolveWithin } from "./release.js";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+const LAYER_IO_CONCURRENCY = 32;
+export const DEPENDENCY_LAYER_SCHEMA = PRODUCT_IDENTITY.evidence.dependencyLayerSchema;
+export const DEPENDENCY_LAYER_MANIFEST = "dependency-layer-manifest.json";
+export const RUNTIME_PAYLOAD_INVENTORY = "dist/runtime-payload-inventory.json";
+/** Consume topology-independent publication classifications, retaining unknown installed content. */
+export async function selectPublishedDependencyRuntimePayload(packageRoot, paths) {
+    const inventoryPath = resolve(packageRoot, RUNTIME_PAYLOAD_INVENTORY);
+    const published = await readFile(inventoryPath, "utf8").then(source => JSON.parse(source)).catch(() => null);
+    if (published === null)
+        return await selectDependencyRuntimePayload(packageRoot, paths);
+    if (published.schema !== PRODUCT_IDENTITY.evidence.runtimePayloadSchema || !Array.isArray(published.paths)
+        || !Array.isArray(published.entryPoints) || !Array.isArray(published.declaredAssets) || !Array.isArray(published.classifications)
+        || !published.inventory || published.inventory.schema !== PRODUCT_IDENTITY.evidence.runtimePayloadSchema
+        || published.classifications.some(classification => !validPublishedClassification(classification))) {
+        throw new Error("published runtime payload inventory is invalid");
+    }
+    const classificationByKey = new Map();
+    for (const classification of published.classifications) {
+        const key = classificationKey(classification.packageName, classification.packageVersion, classification.packagePath);
+        const existing = classificationByKey.get(key);
+        if (existing && (existing.disposition !== classification.disposition || existing.reason !== classification.reason)) {
+            throw new Error("published runtime payload inventory contains conflicting classifications");
+        }
+        classificationByKey.set(key, classification);
+    }
+    const descriptors = await dependencyPackageDescriptors(packageRoot, paths);
+    const selected = [];
+    const exclusions = [];
+    let includedBytes = 0;
+    let excludedBytes = 0;
+    let uncertaintyRetainedFiles = 0;
+    await mapWithConcurrency([...paths].sort(), LAYER_IO_CONCURRENCY, async (path) => {
+        const descriptor = descriptorForPath(path, descriptors);
+        const packagePath = descriptor === null ? null : path.slice(descriptor.root.length + 1);
+        const classification = descriptor === null || packagePath === null
+            ? undefined
+            : classificationByKey.get(classificationKey(descriptor.name, descriptor.version, packagePath));
+        const bytes = (await lstat(resolveWithin(packageRoot, path))).size;
+        const intrinsicExclusion = /\.d\.(?:ts|mts|cts)$/.test(path) ? "type-declaration"
+            : /\.map$/.test(path) ? "source-map"
+                : null;
+        if (classification?.disposition === "exclude" || intrinsicExclusion !== null) {
+            exclusions.push({ path, reason: classification?.disposition === "exclude" ? classification.reason : intrinsicExclusion });
+            excludedBytes += bytes;
+            return;
+        }
+        selected.push(path);
+        includedBytes += bytes;
+        if (classification === undefined || !isKnownRuntimePath(path))
+            uncertaintyRetainedFiles += 1;
+    });
+    selected.sort();
+    exclusions.sort((left, right) => left.path.localeCompare(right.path));
+    return {
+        paths: selected,
+        inventory: {
+            schema: PRODUCT_IDENTITY.evidence.runtimePayloadSchema,
+            includedFiles: selected.length,
+            includedBytes,
+            excludedFiles: exclusions.length,
+            excludedBytes,
+            uncertaintyRetainedFiles,
+            exclusions,
+        },
+    };
+}
+/** Generate publication evidence from literal module reachability and declared runtime assets. */
+export async function generateDependencyRuntimePayload(packageRoot, allPaths, productPaths) {
+    const available = new Set(allPaths);
+    const selected = new Set();
+    const queue = productPaths.filter(isJavaScriptModule);
+    for (const manifestPath of allPaths.filter(path => path.startsWith("node_modules/") && path.endsWith("/package.json"))) {
+        try {
+            const manifest = JSON.parse(await readFile(resolveWithin(packageRoot, manifestPath), "utf8"));
+            const packagePath = manifestPath.slice(0, -"/package.json".length);
+            const target = exportedTarget(manifest.exports, "")
+                ?? (typeof manifest.module === "string" ? manifest.module : typeof manifest.main === "string" ? manifest.main : "index.js");
+            const entry = availableModule(relativePath(packagePath, target), available);
+            if (entry !== null && !selected.has(entry)) {
+                selected.add(entry);
+                if (isJavaScriptModule(entry))
+                    queue.push(entry);
+            }
+        }
+        catch { }
+    }
+    const visited = new Set();
+    while (queue.length > 0) {
+        const importer = queue.shift();
+        if (visited.has(importer))
+            continue;
+        visited.add(importer);
+        const source = await readFile(resolveWithin(packageRoot, importer), "utf8");
+        const specifiers = [...source.matchAll(/(?:\bimport\s*(?:[^"'`]*?\sfrom\s*)?|\bexport\s+[^"'`]*?\sfrom\s*|\bimport\s*\(|\brequire\s*\()\s*["'`]([^"'`]+)["'`]/g)]
+            .map(match => match[1])
+            .filter(specifier => !specifier.startsWith("node:"));
+        for (const specifier of specifiers) {
+            const resolved = await resolvePublishedSpecifier(packageRoot, importer, specifier, available);
+            if (resolved === null || !resolved.startsWith("node_modules/"))
+                continue;
+            if (!selected.has(resolved)) {
+                selected.add(resolved);
+                if (isJavaScriptModule(resolved))
+                    queue.push(resolved);
+            }
+        }
+        if (importer.startsWith("node_modules/") && /\b(?:import|require)\s*\(\s*(?!["'`])/.test(source)) {
+            const prefix = dependencyPackagePrefix(importer);
+            for (const path of allPaths)
+                if (path.startsWith(`${prefix}/`))
+                    selected.add(path);
+        }
+    }
+    for (const path of allPaths) {
+        if (!path.startsWith("node_modules/"))
+            continue;
+        if (path.endsWith("/package.json") || /(?:^|\/)LICENSE(?:\.|$)/i.test(path)
+            || /\.(?:json|node|wasm|css|html|png|jpg|jpeg|gif|svg|md)$/.test(path))
+            selected.add(path);
+    }
+    const conservative = await selectDependencyRuntimePayload(packageRoot, allPaths.filter(path => path.startsWith("node_modules/")));
+    const paths = conservative.paths.filter(path => selected.has(path)).sort();
+    const exclusions = [];
+    let includedBytes = 0;
+    let excludedBytes = 0;
+    let uncertaintyRetainedFiles = 0;
+    const conservativeReasons = new Map(conservative.inventory.exclusions.map(item => [item.path, item.reason]));
+    for (const path of allPaths.filter(path => path.startsWith("node_modules/")).sort()) {
+        const bytes = (await lstat(resolveWithin(packageRoot, path))).size;
+        if (paths.includes(path)) {
+            includedBytes += bytes;
+            if (!isJavaScriptModule(path) && !/\.(?:json|node|wasm|css|html|png|jpg|jpeg|gif|svg)$/.test(path))
+                uncertaintyRetainedFiles += 1;
+        }
+        else {
+            excludedBytes += bytes;
+            exclusions.push({ path, reason: conservativeReasons.get(path) ?? "unreachable-development" });
+        }
+    }
+    const inventory = {
+        schema: PRODUCT_IDENTITY.evidence.runtimePayloadSchema,
+        includedFiles: paths.length,
+        includedBytes,
+        excludedFiles: exclusions.length,
+        excludedBytes,
+        uncertaintyRetainedFiles,
+        exclusions,
+    };
+    return {
+        paths,
+        inventory,
+        classifications: await createPublishedClassifications(packageRoot, allPaths, new Set(paths), new Map(exclusions.map(item => [item.path, item.reason]))),
+    };
+}
+/** Conservatively omit only files Node never executes; uncertain assets remain selected. */
+export async function selectDependencyRuntimePayload(packageRoot, paths) {
+    const included = [];
+    const exclusions = [];
+    let includedBytes = 0;
+    let excludedBytes = 0;
+    let uncertaintyRetainedFiles = 0;
+    await mapWithConcurrency([...paths].sort(), LAYER_IO_CONCURRENCY, async (path) => {
+        const metadata = await lstat(resolveWithin(packageRoot, path));
+        const reason = /\.d\.(?:ts|mts|cts)$/.test(path) ? "type-declaration"
+            : /\.map$/.test(path) ? "source-map"
+                : null;
+        if (reason !== null) {
+            exclusions.push({ path, reason });
+            excludedBytes += metadata.size;
+            return;
+        }
+        included.push(path);
+        includedBytes += metadata.size;
+        if (!/\.(?:js|mjs|cjs|json|node|wasm|css|html|png|jpg|jpeg|gif|svg)$/.test(path) && !/(?:^|\/)LICENSE(?:\.|$)/i.test(path)) {
+            uncertaintyRetainedFiles += 1;
+        }
+    });
+    exclusions.sort((left, right) => left.path.localeCompare(right.path));
+    included.sort();
+    return {
+        paths: included,
+        inventory: {
+            schema: PRODUCT_IDENTITY.evidence.runtimePayloadSchema,
+            includedFiles: included.length,
+            includedBytes,
+            excludedFiles: exclusions.length,
+            excludedBytes,
+            uncertaintyRetainedFiles,
+            exclusions,
+        },
+    };
+}
+/** Materialize or reuse an exact immutable dependency layer after one source-content pass. */
+export async function materializeDependencyLayer(packageRoot, dataDir, paths, options) {
+    if (paths.length === 0)
+        return null;
+    const sourceRoot = await realpath(packageRoot);
+    const selected = [...paths].sort();
+    const content = await mapWithConcurrency(selected, LAYER_IO_CONCURRENCY, async (path) => {
+        const source = resolveWithin(sourceRoot, path);
+        const metadata = await lstat(source);
+        if (!metadata.isFile() || metadata.isSymbolicLink())
+            throw new Error(`dependency-layer input is not a regular file: ${path}`);
+        const cached = options.cachedFiles?.get(path);
+        const bytes = cached ?? await readFile(source);
+        if (!cached)
+            options.onOperation?.({ operation: "source-read", path, bytes: bytes.length });
+        return { path, bytes, mode: (metadata.mode & 0o111) !== 0 ? 0o500 : 0o400, identity: releaseFileIdentity(path, bytes, (metadata.mode & 0o111) !== 0) };
+    });
+    const files = content.map(item => item.identity);
+    const contentDigest = digestManifestFiles(files);
+    const identity = {
+        schema: DEPENDENCY_LAYER_SCHEMA,
+        layerId: `dependencies-${contentDigest.slice(0, 32)}`,
+        contentDigest,
+        files,
+        inventory: options.inventory,
+    };
+    const layersRoot = resolve(dataDir, "dependency-layers");
+    await mkdir(layersRoot, { recursive: true, mode: 0o700 });
+    const layerRoot = resolveWithin(layersRoot, identity.layerId);
+    if (await lstat(layerRoot).catch(() => null)) {
+        const reused = await reuseDependencyLayer(dataDir, identity);
+        for (const file of reused.files)
+            options.onOperation?.({ operation: "layer-reuse", path: file.path, bytes: file.bytes });
+        return { ...reused, reused: true };
+    }
+    const candidate = resolveWithin(layersRoot, `.candidate-${randomUUID()}`);
+    await mkdir(candidate, { mode: 0o700 });
+    try {
+        const directories = [...new Set(content.map(item => dirname(resolveWithin(candidate, item.path))))];
+        await mapWithConcurrency(directories, LAYER_IO_CONCURRENCY, async (directory) => await mkdir(directory, { recursive: true, mode: 0o700 }));
+        await mapWithConcurrency(content, LAYER_IO_CONCURRENCY, async (item) => {
+            const destination = resolveWithin(candidate, item.path);
+            if (options.writeCandidateFile)
+                await options.writeCandidateFile(destination, item.bytes, item.mode);
+            else {
+                await writeFile(destination, item.bytes, { flag: "wx", mode: item.mode });
+                await chmod(destination, item.mode);
+            }
+            options.onOperation?.({ operation: "layer-write", path: item.path, bytes: item.bytes.length });
+        });
+        await writeFile(resolve(candidate, DEPENDENCY_LAYER_MANIFEST), JSON.stringify(identity, null, 2), { flag: "wx", mode: 0o400 });
+        try {
+            await rename(candidate, layerRoot);
+        }
+        catch (error) {
+            if (!await lstat(layerRoot).catch(() => null))
+                throw error;
+            await rm(candidate, { recursive: true, force: true });
+            const winner = await reuseDependencyLayer(dataDir, identity);
+            for (const file of winner.files)
+                options.onOperation?.({ operation: "layer-reuse", path: file.path, bytes: file.bytes });
+            return { ...winner, reused: true };
+        }
+        await writeLayerCertification(dataDir, identity);
+        return { ...identity, layerRoot: await realpath(layerRoot), reused: false };
+    }
+    catch (error) {
+        await rm(candidate, { recursive: true, force: true });
+        throw error;
+    }
+}
+/** Read trusted layer certification and canonical metadata without rereading every payload byte. */
+export async function readCertifiedDependencyLayer(dataDir, layerId, expected, options = {}) {
+    const layersRoot = await realpath(resolve(dataDir, "dependency-layers"));
+    const layerRoot = await realpath(resolveWithin(layersRoot, layerId));
+    assertDirectChild(layersRoot, layerRoot);
+    const metadata = await lstat(resolve(layersRoot, layerId));
+    if (!metadata.isDirectory() || metadata.isSymbolicLink())
+        throw new Error(`dependency layer is not a managed non-link directory: ${layerId}`);
+    const manifest = JSON.parse(await readFile(resolve(layerRoot, DEPENDENCY_LAYER_MANIFEST), "utf8"));
+    validateLayerManifest(manifest);
+    if (expected && (expected.layerId !== manifest.layerId || expected.contentDigest !== manifest.contentDigest)) {
+        throw new Error(`dependency layer identity mismatch: ${layerId}`);
+    }
+    if (manifest.layerId !== layerId)
+        throw new Error(`dependency layer identity mismatch: ${layerId}`);
+    await readDependencyCertification(dataDir, manifest, options);
+    return { ...manifest, layerRoot };
+}
+/** Fully verify a layer when certification is absent or explicit tamper evidence is required. */
+export async function verifyDependencyLayer(dataDir, reference, onOperation) {
+    const layersRoot = await realpath(resolve(dataDir, "dependency-layers"));
+    const layerRoot = await realpath(resolveWithin(layersRoot, reference.layerId));
+    assertDirectChild(layersRoot, layerRoot);
+    const manifest = JSON.parse(await readFile(resolve(layerRoot, DEPENDENCY_LAYER_MANIFEST), "utf8"));
+    validateLayerManifest(manifest);
+    if (manifest.layerId !== reference.layerId || manifest.contentDigest !== reference.contentDigest)
+        throw new Error(`dependency layer reference mismatch: ${reference.layerId}`);
+    await mapWithConcurrency(manifest.files, LAYER_IO_CONCURRENCY, async (file) => {
+        const path = resolveWithin(layerRoot, file.path);
+        const metadata = await lstat(path);
+        if (!metadata.isFile() || metadata.isSymbolicLink() || metadata.size !== file.bytes)
+            throw new Error(`dependency layer file mismatch: ${file.path}`);
+        assertImmutableFileMode(metadata, path);
+        const bytes = await readFile(path);
+        onOperation?.({ operation: "verification-read", path: file.path, bytes: bytes.length });
+        const actual = releaseFileIdentity(file.path, bytes, file.executable);
+        if (actual.sha256 !== file.sha256)
+            throw new Error(`dependency layer file digest mismatch: ${file.path}`);
+    });
+    if (digestManifestFiles(manifest.files) !== manifest.contentDigest)
+        throw new Error(`dependency layer content digest mismatch: ${manifest.layerId}`);
+    await writeLayerCertification(dataDir, manifest);
+    return { ...manifest, layerRoot };
+}
+export function dependencyReference(layer) {
+    return { layerId: layer.layerId, contentDigest: layer.contentDigest, binding: "node_modules" };
+}
+async function reuseDependencyLayer(dataDir, identity) {
+    try {
+        return await readCertifiedDependencyLayer(dataDir, identity.layerId, identity);
+    }
+    catch (error) {
+        const verified = await verifyDependencyLayer(dataDir, dependencyReference({ ...identity, layerRoot: resolve(dataDir, "dependency-layers", identity.layerId), reused: true }));
+        if (verified.layerId !== identity.layerId || verified.contentDigest !== identity.contentDigest)
+            throw error;
+        return verified;
+    }
+}
+function validateLayerManifest(value) {
+    if (value.schema !== DEPENDENCY_LAYER_SCHEMA || !/^dependencies-[a-f0-9]{32}$/.test(value.layerId)
+        || !/^[a-f0-9]{64}$/.test(value.contentDigest) || !Array.isArray(value.files) || value.files.length === 0
+        || value.files.some(file => !file.path.startsWith("node_modules/") || file.path.includes("..") || !/^[a-f0-9]{64}$/.test(file.sha256))) {
+        throw new Error("dependency layer manifest is invalid");
+    }
+    if (digestManifestFiles(value.files) !== value.contentDigest || value.layerId !== `dependencies-${value.contentDigest.slice(0, 32)}`) {
+        throw new Error(`dependency layer manifest identity is invalid: ${value.layerId}`);
+    }
+}
+async function resolvePublishedSpecifier(packageRoot, importer, specifier, available) {
+    if (specifier.startsWith("."))
+        return availableModule(relativePath(dirname(importer), specifier), available);
+    if (specifier.startsWith("/") || specifier.startsWith("#"))
+        return null;
+    const parts = specifier.split("/");
+    const packageName = parts[0].startsWith("@") ? parts.slice(0, 2).join("/") : parts[0];
+    const subpath = parts.slice(packageName.startsWith("@") ? 2 : 1).join("/");
+    const suffix = `node_modules/${packageName}/package.json`;
+    const manifests = [...available].filter(path => path.endsWith(suffix));
+    manifests.sort((left, right) => commonPrefixLength(importer, right) - commonPrefixLength(importer, left));
+    for (const manifestPath of manifests) {
+        try {
+            const manifest = JSON.parse(await readFile(resolveWithin(packageRoot, manifestPath), "utf8"));
+            const packagePath = manifestPath.slice(0, -"/package.json".length);
+            const target = exportedTarget(manifest.exports, subpath) ?? (subpath.length > 0 ? subpath
+                : typeof manifest.module === "string" ? manifest.module
+                    : typeof manifest.main === "string" ? manifest.main
+                        : "index.js");
+            const resolved = availableModule(relativePath(packagePath, target), available);
+            if (resolved !== null)
+                return resolved;
+        }
+        catch { }
+    }
+    return null;
+}
+function exportedTarget(exportsValue, subpath) {
+    const select = (value) => {
+        if (typeof value === "string")
+            return value;
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return null;
+        const record = value;
+        return select(record.import) ?? select(record.node) ?? select(record.default);
+    };
+    if (typeof exportsValue === "string")
+        return subpath.length === 0 ? exportsValue : null;
+    if (!exportsValue || typeof exportsValue !== "object" || Array.isArray(exportsValue))
+        return null;
+    const record = exportsValue;
+    return select(record[subpath.length === 0 ? "." : `./${subpath}`]) ?? (subpath.length === 0 ? select(exportsValue) : null);
+}
+function relativePath(root, target) {
+    return posix.normalize(posix.join(root.split(sep).join("/"), target));
+}
+function availableModule(path, available) {
+    const normalized = path.replace(/^\.\//, "");
+    for (const candidate of [normalized, `${normalized}.js`, `${normalized}.mjs`, `${normalized}.cjs`, `${normalized}.json`, `${normalized}/index.js`]) {
+        if (available.has(candidate))
+            return candidate;
+    }
+    return null;
+}
+function commonPrefixLength(left, right) {
+    const leftParts = left.split("/");
+    const rightParts = right.split("/");
+    let index = 0;
+    while (leftParts[index] === rightParts[index])
+        index += 1;
+    return index;
+}
+function dependencyPackagePrefix(path) {
+    const parts = path.split("/");
+    const nodeModules = parts.lastIndexOf("node_modules");
+    const packageParts = parts[nodeModules + 1]?.startsWith("@") ? 2 : 1;
+    return parts.slice(0, nodeModules + 1 + packageParts).join("/");
+}
+async function dependencyPackageDescriptors(packageRoot, paths) {
+    const descriptors = [];
+    for (const path of paths.filter(path => path.endsWith("/package.json")).sort()) {
+        try {
+            const manifest = JSON.parse(await readFile(resolveWithin(packageRoot, path), "utf8"));
+            if (typeof manifest.name !== "string" || manifest.name.length === 0 || typeof manifest.version !== "string" || manifest.version.length === 0)
+                continue;
+            descriptors.push({ root: path.slice(0, -"/package.json".length), name: manifest.name, version: manifest.version });
+        }
+        catch { }
+    }
+    return descriptors.sort((left, right) => right.root.length - left.root.length || left.root.localeCompare(right.root));
+}
+function descriptorForPath(path, descriptors) {
+    return descriptors.find(descriptor => path.startsWith(`${descriptor.root}/`)) ?? null;
+}
+async function createPublishedClassifications(packageRoot, paths, included, exclusionReasons) {
+    const descriptors = await dependencyPackageDescriptors(packageRoot, paths);
+    const classifications = new Map();
+    for (const path of paths.filter(path => path.startsWith("node_modules/")).sort()) {
+        const descriptor = descriptorForPath(path, descriptors);
+        if (descriptor === null)
+            continue;
+        const packagePath = path.slice(descriptor.root.length + 1);
+        const classification = included.has(path)
+            ? { packageName: descriptor.name, packageVersion: descriptor.version, packagePath, disposition: "include" }
+            : { packageName: descriptor.name, packageVersion: descriptor.version, packagePath, disposition: "exclude", reason: exclusionReasons.get(path) ?? "unreachable-development" };
+        const key = classificationKey(classification.packageName, classification.packageVersion, classification.packagePath);
+        const existing = classifications.get(key);
+        if (existing?.disposition === "include")
+            continue;
+        if (classification.disposition === "include" || existing === undefined)
+            classifications.set(key, classification);
+    }
+    return [...classifications.values()].sort((left, right) => classificationKey(left.packageName, left.packageVersion, left.packagePath)
+        .localeCompare(classificationKey(right.packageName, right.packageVersion, right.packagePath)));
+}
+function validPublishedClassification(value) {
+    const validReason = value.reason === "type-declaration" || value.reason === "source-map" || value.reason === "unreachable-development";
+    return typeof value.packageName === "string" && value.packageName.length > 0
+        && typeof value.packageVersion === "string" && value.packageVersion.length > 0
+        && typeof value.packagePath === "string" && value.packagePath.length > 0
+        && !value.packagePath.startsWith("/") && !value.packagePath.includes("\\")
+        && !value.packagePath.split("/").includes("..")
+        && (value.disposition === "include" ? value.reason === undefined : value.disposition === "exclude" && validReason);
+}
+function classificationKey(packageName, packageVersion, packagePath) {
+    return `${packageName}\0${packageVersion}\0${packagePath}`;
+}
+function isKnownRuntimePath(path) {
+    return /\.(?:js|mjs|cjs|json|node|wasm|css|html|png|jpg|jpeg|gif|svg)$/.test(path) || /(?:^|\/)LICENSE(?:\.|$)/i.test(path);
+}
+function isJavaScriptModule(path) { return /\.(?:js|mjs|cjs)$/.test(path); }
+function assertDirectChild(parent, child) {
+    const path = relative(parent, child);
+    if (path.length === 0 || path === ".." || path.startsWith(`..${sep}`) || path.includes(sep))
+        throw new Error(`dependency layer escapes managed storage: ${child}`);
+}

package/dist/foundation/release/endpoints.d.ts

@@ -0,0 +1,24 @@
+import type { OwnershipProbe } from "./cohort-selection.js";
+import type { SupervisorEndpointMetadata } from "./cohort-state.js";
+import type { CohortEndpointPaths, ProductPaths } from "../lifecycle/index.js";
+export interface RecordedEndpoint {
+    readonly metadata: SupervisorEndpointMetadata;
+    readonly paths: CohortEndpointPaths;
+}
+/**
+ * Every endpoint recorded under this runtime directory: one per cohort, plus the single
+ * endpoint published by releases that predate cohort-scoped identity. More than one can be
+ * live at a time, and each is validated on its own identity rather than by being the only one.
+ */
+export declare function listRecordedEndpoints(paths: ProductPaths): Promise<readonly RecordedEndpoint[]>;
+/**
+ * Removes the records of cohorts whose processes are gone. A record left by a cohort that
+ * exited without cleaning up is not evidence of ownership, and a later launch should not have
+ * to reason about it. Returns the release ids whose records were removed.
+ */
+export declare function sweepDeadEndpoints(paths: ProductPaths): Promise<readonly string[]>;
+/** The releases that an identity-verified live cohort runs from and that must be retained. */
+export declare function liveReleaseIds(paths: ProductPaths): Promise<readonly string[]>;
+export declare function readEndpointMetadata(path: string): Promise<SupervisorEndpointMetadata | null>;
+export declare function probeOwnership(metadata: SupervisorEndpointMetadata): Promise<OwnershipProbe>;
+export declare function removeEndpointArtifacts(metadataPath: string, endpoint: string): Promise<void>;

package/dist/foundation/release/endpoints.js

@@ -0,0 +1,134 @@
+import { readdir, readFile, rm } from "node:fs/promises";
+import { connect } from "node:net";
+import { platform } from "node:os";
+import { resolve } from "node:path";
+import { PRODUCT_IDENTITY } from "../../product-identity.js";
+import { encodeFrame, LineFrameDecoder } from "../protocol/index.js";
+import { processIsAlive } from "./process-cleanup.js";
+/**
+ * Every endpoint recorded under this runtime directory: one per cohort, plus the single
+ * endpoint published by releases that predate cohort-scoped identity. More than one can be
+ * live at a time, and each is validated on its own identity rather than by being the only one.
+ */
+export async function listRecordedEndpoints(paths) {
+    const recorded = [];
+    const legacy = await readEndpointMetadata(paths.endpointMetadataPath);
+    if (legacy) {
+        recorded.push({ metadata: legacy, paths: { endpoint: paths.endpoint, endpointMetadataPath: paths.endpointMetadataPath } });
+    }
+    const names = await readdir(paths.endpointsDir).catch(() => []);
+    for (const name of names) {
+        if (!name.endsWith(".json"))
+            continue;
+        const endpointMetadataPath = resolve(paths.endpointsDir, name);
+        const metadata = await readEndpointMetadata(endpointMetadataPath);
+        if (metadata)
+            recorded.push({ metadata, paths: { endpoint: metadata.endpoint, endpointMetadataPath } });
+    }
+    return recorded;
+}
+/**
+ * Removes the records of cohorts whose processes are gone. A record left by a cohort that
+ * exited without cleaning up is not evidence of ownership, and a later launch should not have
+ * to reason about it. Returns the release ids whose records were removed.
+ */
+export async function sweepDeadEndpoints(paths) {
+    const swept = [];
+    for (const recorded of await listRecordedEndpoints(paths)) {
+        if (processIsAlive(recorded.metadata.pid))
+            continue;
+        await removeEndpointArtifacts(recorded.paths.endpointMetadataPath, recorded.paths.endpoint);
+        swept.push(recorded.metadata.releaseId);
+    }
+    return swept;
+}
+/** The releases that an identity-verified live cohort runs from and that must be retained. */
+export async function liveReleaseIds(paths) {
+    const recorded = await listRecordedEndpoints(paths);
+    const ownership = await Promise.all(recorded.map(async (endpoint) => ({
+        releaseId: endpoint.metadata.releaseId,
+        probe: await probeOwnership(endpoint.metadata),
+    })));
+    return [...new Set(ownership.filter(item => item.probe === "live-verified").map(item => item.releaseId))].sort();
+}
+export async function readEndpointMetadata(path) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        const ownership = value.ownership;
+        const liveInstanceIds = Array.isArray(ownership?.liveInstanceIds)
+            ? ownership.liveInstanceIds
+            : Array.isArray(ownership?.liveGenerationIds) ? ownership.liveGenerationIds : null;
+        const nonResumableInstanceIds = Array.isArray(ownership?.nonResumableInstanceIds)
+            ? ownership.nonResumableInstanceIds
+            : Array.isArray(ownership?.nonResumableGenerationIds) ? ownership.nonResumableGenerationIds : null;
+        const uncertainInstanceIds = Array.isArray(ownership?.uncertainInstanceIds) ? ownership.uncertainInstanceIds : [];
+        if (!value || value.schema !== PRODUCT_IDENTITY.protocol.supervisorSchema || typeof value.supervisorId !== "string" || typeof value.endpoint !== "string" || !Number.isSafeInteger(value.pid)
+            || typeof value.pidStartIdentity !== "string" || typeof value.bootNonce !== "string" || typeof value.releaseId !== "string"
+            || typeof value.releaseRoot !== "string" || typeof value.contentDigest !== "string" || !ownership
+            || !isStringArray(liveInstanceIds) || !isStringArray(nonResumableInstanceIds) || !isStringArray(uncertainInstanceIds)) {
+            return null;
+        }
+        return {
+            ...value,
+            ownership: {
+                ...ownership,
+                liveInstanceIds,
+                nonResumableInstanceIds,
+                uncertainInstanceIds,
+            },
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function probeOwnership(metadata) {
+    if (!processIsAlive(metadata.pid))
+        return "dead";
+    const identity = await requestIdentity(metadata.endpoint, 500);
+    if (!identity)
+        return "unresponsive";
+    return identity.supervisorId === metadata.supervisorId
+        && identity.bootNonce === metadata.bootNonce
+        && identity.pidStartIdentity === metadata.pidStartIdentity
+        && identity.releaseId === metadata.releaseId
+        ? "live-verified"
+        : "identity-mismatch";
+}
+async function requestIdentity(endpoint, timeoutMs) {
+    return await new Promise(resolvePromise => {
+        const socket = connect(endpoint);
+        const decoder = new LineFrameDecoder();
+        let settled = false;
+        const finish = (value) => {
+            if (settled)
+                return;
+            settled = true;
+            socket.destroy();
+            resolvePromise(value);
+        };
+        socket.once("error", () => finish(null));
+        socket.once("connect", () => socket.write(encodeFrame({ type: "identity-probe" })));
+        socket.on("data", chunk => {
+            try {
+                const message = decoder.push(chunk)[0];
+                if (message?.type === "identity" && typeof message.supervisorId === "string" && typeof message.bootNonce === "string"
+                    && typeof message.pidStartIdentity === "string" && typeof message.releaseId === "string") {
+                    finish({ supervisorId: message.supervisorId, bootNonce: message.bootNonce, pidStartIdentity: message.pidStartIdentity, releaseId: message.releaseId });
+                }
+            }
+            catch {
+                finish(null);
+            }
+        });
+        setTimeout(() => finish(null), timeoutMs).unref();
+    });
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every(item => typeof item === "string" && item.length > 0);
+}
+export async function removeEndpointArtifacts(metadataPath, endpoint) {
+    await rm(metadataPath, { force: true });
+    if (platform() !== "win32")
+        await rm(endpoint, { force: true });
+}

package/dist/foundation/release/immutable-platform.d.ts

@@ -0,0 +1,6 @@
+import type { Stats } from "node:fs";
+export type ImmutablePlatformPolicy = "windows-readonly-content-v1" | "posix-readonly-content-v1";
+/** Name the platform protection established while complete payload verification owns every file. */
+export declare function immutablePlatformPolicy(platform?: NodeJS.Platform): ImmutablePlatformPolicy | null;
+/** Refuse certification when a payload file is writable after immutable materialization. */
+export declare function assertImmutableFileMode(metadata: Pick<Stats, "mode">, path: string): void;

package/dist/foundation/release/immutable-platform.js

@@ -0,0 +1,13 @@
+/** Name the platform protection established while complete payload verification owns every file. */
+export function immutablePlatformPolicy(platform = process.platform) {
+    if (platform === "win32")
+        return "windows-readonly-content-v1";
+    if (platform === "linux" || platform === "darwin")
+        return "posix-readonly-content-v1";
+    return null;
+}
+/** Refuse certification when a payload file is writable after immutable materialization. */
+export function assertImmutableFileMode(metadata, path) {
+    if ((metadata.mode & 0o222) !== 0)
+        throw new Error(`immutable payload file is writable: ${path}`);
+}