akm-cli 0.9.1 → 0.9.2-alpha.2

package/dist/workflows/ir/environment-v4.js

@@ -0,0 +1,328 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Durable-v4 symbolic workflow environments.
+ *
+ * Env-file values are the deliberately narrow live-value exception to a
+ * frozen workflow plan. Freeze persists only the qualified owner, physical
+ * containment, exact key set, and secret-token topology. Materialization
+ * later reads current values directly through that descriptor, without
+ * consulting config, the index, or authored workflow source.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import dotenv from "dotenv";
+import { assetPathForName } from "../../core/asset/asset-placement.js";
+import { isWithin } from "../../core/common.js";
+import { NotFoundError, UsageError } from "../../core/errors.js";
+import { captureGuardedExecutionSource, GuardedExecutionSourceCollector } from "../../execution/guarded-source.js";
+const SECRET_TOKEN_RE = /\$\{secret:([A-Za-z0-9_./-]+)\}/g;
+const ENVIRONMENT_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const QUALIFIED_ENV_REF_RE = /^([^/]+)\/\/env\/(.+)$/;
+/** Freeze value-free descriptors in authored ref order. */
+export function freezeWorkflowEnvironment(refs, options) {
+    const collector = options.collector ?? new GuardedExecutionSourceCollector();
+    const logical = new Set();
+    const physical = new Map();
+    const out = [];
+    for (const [precedence, inputRef] of refs.entries()) {
+        const resolved = options.resolveRef(inputRef);
+        const match = QUALIFIED_ENV_REF_RE.exec(resolved.ref);
+        if (!match || match[1] !== resolved.bundle) {
+            throw new UsageError(`Workflow env ref ${JSON.stringify(inputRef)} did not resolve to a canonical fully-qualified owner.`, "INVALID_FLAG_VALUE");
+        }
+        if (logical.has(resolved.ref)) {
+            throw new UsageError(`Workflow environment contains duplicate ref ${resolved.ref}.`, "INVALID_FLAG_VALUE");
+        }
+        logical.add(resolved.ref);
+        trackParentDirectories(collector, resolved.root, resolved.path);
+        const retained = collector.capture(resolved.path, resolved.root, { authored: true });
+        const captured = collector.bindIdentity(resolved.path, resolved.root, {
+            ref: resolved.ref,
+            bundle: resolved.bundle,
+            adapter: resolved.adapter,
+            file: retained.relativePath,
+            hash: retained.sha256,
+        });
+        const physicalKey = `${captured.containmentPhysicalIdentity}\0${captured.physicalIdentity}`;
+        const alias = physical.get(physicalKey);
+        if (alias !== undefined && alias !== resolved.ref) {
+            throw new UsageError(`${resolved.ref} aliases the same physical environment source as ${alias} under a different logical owner.`, "RESOURCE_ALREADY_EXISTS");
+        }
+        physical.set(physicalKey, resolved.ref);
+        const parsed = dotenv.parse(Buffer.from(captured.bytesBase64, "base64"));
+        const keys = sortedCodePoints(Object.keys(parsed));
+        const secretNames = secretTokenNames(parsed);
+        out.push(Object.freeze({
+            kind: "env-ref",
+            ref: resolved.ref,
+            owner: Object.freeze({
+                bundle: resolved.bundle,
+                adapter: resolved.adapter,
+                requestedRoot: captured.containmentRoot,
+                realRoot: captured.containmentRealPath,
+                rootPhysicalIdentity: captured.containmentPhysicalIdentity,
+                requestedPath: captured.sourcePath,
+                realPath: captured.realPath,
+                relativePath: captured.relativePath,
+            }),
+            keys: Object.freeze(keys),
+            secretNames: Object.freeze(secretNames),
+            precedence,
+        }));
+    }
+    return out;
+}
+/**
+ * Materialize all current values atomically from frozen descriptors. Nothing
+ * is returned until every owner/key/token check and every secret lookup has
+ * succeeded.
+ */
+export function materializeFrozenWorkflowEnvironment(descriptors, options = {}) {
+    const values = {};
+    const sensitive = new Set();
+    const audits = [];
+    const seenRefs = new Set();
+    let priorPrecedence = -1;
+    for (const descriptor of descriptors) {
+        if (!descriptor || typeof descriptor !== "object")
+            invalid("environment descriptor must be an object");
+        if (descriptor.kind === "literal") {
+            exactKeys(descriptor, ["kind", "name", "value"]);
+            environmentName(descriptor.name);
+            if (typeof descriptor.value !== "string")
+                invalid("literal environment value must be a string");
+            values[descriptor.name] = descriptor.value;
+            if (descriptor.value)
+                sensitive.add(descriptor.value);
+            continue;
+        }
+        if (descriptor.kind === "pass-through") {
+            exactKeys(descriptor, ["kind", "name"]);
+            environmentName(descriptor.name);
+            const value = options.readPassThrough ? options.readPassThrough(descriptor.name) : process.env[descriptor.name];
+            if (value !== undefined) {
+                values[descriptor.name] = value;
+                if (value)
+                    sensitive.add(value);
+            }
+            continue;
+        }
+        if (descriptor.kind !== "env-ref")
+            invalid("environment descriptor has an unsupported kind");
+        exactKeys(descriptor, ["kind", "ref", "owner", "keys", "secretNames", "precedence"]);
+        validateEnvRefDescriptor(descriptor);
+        if (seenRefs.has(descriptor.ref))
+            invalid(`duplicate environment ref ${descriptor.ref}`);
+        if (descriptor.precedence <= priorPrecedence)
+            invalid("env-ref precedence must be strictly increasing");
+        seenRefs.add(descriptor.ref);
+        priorPrecedence = descriptor.precedence;
+        const source = options.readEnvFile ? options.readEnvFile(descriptor) : readFrozenEnvironmentFile(descriptor.owner);
+        const parsed = dotenv.parse(typeof source === "string" ? source : Buffer.from(source));
+        const keys = sortedCodePoints(Object.keys(parsed));
+        const tokenNames = secretTokenNames(parsed);
+        if (!sameStrings(keys, descriptor.keys)) {
+            invalid(`environment ${descriptor.ref} key set changed after it was frozen`);
+        }
+        if (!sameStrings(tokenNames, descriptor.secretNames)) {
+            invalid(`environment ${descriptor.ref} secret-token topology changed after it was frozen`);
+        }
+        const secretValues = new Map();
+        for (const name of descriptor.secretNames) {
+            const raw = options.readSecret
+                ? options.readSecret({ name, descriptor })
+                : readFrozenSecret(descriptor.owner, name);
+            if (raw === undefined) {
+                throw new NotFoundError(`Environment ${descriptor.ref} references missing secret ${name}; nothing was materialized.`, "FILE_NOT_FOUND");
+            }
+            const value = typeof raw === "string" ? raw : Buffer.from(raw).toString("utf8");
+            secretValues.set(name, value);
+            if (value)
+                sensitive.add(value);
+        }
+        for (const [key, rawValue] of Object.entries(parsed)) {
+            const resolved = rawValue.replace(SECRET_TOKEN_RE, (_token, name) => {
+                const secret = secretValues.get(name);
+                if (secret === undefined)
+                    invalid(`environment ${descriptor.ref} secret ${name} was not materialized`);
+                return secret;
+            });
+            values[key] = resolved;
+            if (resolved)
+                sensitive.add(resolved);
+        }
+        audits.push(Object.freeze({
+            eventType: "env_access",
+            ref: descriptor.ref,
+            keys: Object.freeze([...descriptor.keys]),
+            secretNames: Object.freeze([...descriptor.secretNames]),
+        }));
+    }
+    return {
+        values,
+        sensitiveValues: [...sensitive],
+        audits,
+    };
+}
+function validateEnvRefDescriptor(descriptor) {
+    const match = QUALIFIED_ENV_REF_RE.exec(descriptor.ref);
+    if (!match || match[1] !== descriptor.owner.bundle)
+        invalid("env-ref has a noncanonical qualified owner");
+    exactKeys(descriptor.owner, [
+        "bundle",
+        "adapter",
+        "requestedRoot",
+        "realRoot",
+        "rootPhysicalIdentity",
+        "requestedPath",
+        "realPath",
+        "relativePath",
+    ]);
+    for (const value of [descriptor.owner.bundle, descriptor.owner.adapter, descriptor.owner.rootPhysicalIdentity]) {
+        if (typeof value !== "string" || !value)
+            invalid("env-ref owner identity is incomplete");
+    }
+    for (const value of [
+        descriptor.owner.requestedRoot,
+        descriptor.owner.realRoot,
+        descriptor.owner.requestedPath,
+        descriptor.owner.realPath,
+    ]) {
+        if (typeof value !== "string" || !path.isAbsolute(value))
+            invalid("env-ref owner paths must be absolute");
+    }
+    const relative = descriptor.owner.relativePath;
+    if (typeof relative !== "string" ||
+        !relative ||
+        relative.includes("\\") ||
+        relative.startsWith("../") ||
+        path.isAbsolute(relative)) {
+        invalid("env-ref owner relative path is noncanonical");
+    }
+    if (path.resolve(descriptor.owner.requestedRoot, relative) !== path.resolve(descriptor.owner.requestedPath)) {
+        invalid("env-ref requested path does not match its owner");
+    }
+    if (path.resolve(descriptor.owner.realRoot, relative) !== path.resolve(descriptor.owner.realPath)) {
+        invalid("env-ref real path does not match its owner");
+    }
+    sortedUnique(descriptor.keys, "env-ref keys", ENVIRONMENT_NAME_RE);
+    sortedUnique(descriptor.secretNames, "env-ref secret names", /^[A-Za-z0-9_./-]+$/);
+    if (!Number.isSafeInteger(descriptor.precedence) || descriptor.precedence < 0) {
+        invalid("env-ref precedence is invalid");
+    }
+}
+function readFrozenEnvironmentFile(owner) {
+    const rootLstat = fs.lstatSync(owner.requestedRoot, { bigint: true });
+    if (rootLstat.isSymbolicLink() || !rootLstat.isDirectory())
+        invalid("environment owner root physical identity changed");
+    const currentRealRoot = fs.realpathSync(owner.requestedRoot);
+    if (currentRealRoot !== owner.realRoot ||
+        physicalIdentity(currentRealRoot, rootLstat) !== owner.rootPhysicalIdentity) {
+        invalid("environment owner root physical identity changed");
+    }
+    const captured = captureGuardedExecutionSource(owner.requestedPath, owner.requestedRoot, { authored: true });
+    if (captured.realPath !== owner.realPath ||
+        captured.relativePath !== owner.relativePath ||
+        captured.containmentRealPath !== owner.realRoot ||
+        captured.containmentPhysicalIdentity !== owner.rootPhysicalIdentity) {
+        invalid("environment owner/path physical identity changed");
+    }
+    return Buffer.from(captured.bytesBase64, "base64");
+}
+function readFrozenSecret(owner, name) {
+    const secretsRoot = path.join(owner.requestedRoot, "secrets");
+    const secretPath = assetPathForName("secret", secretsRoot, name);
+    if (!isWithin(secretPath, secretsRoot))
+        invalid(`secret name ${name} escapes its frozen owner`);
+    let descriptor;
+    try {
+        const noFollow = typeof fs.constants.O_NOFOLLOW === "number" ? fs.constants.O_NOFOLLOW : 0;
+        descriptor = fs.openSync(secretPath, fs.constants.O_RDONLY | noFollow);
+        const before = fs.fstatSync(descriptor, { bigint: true });
+        if (!before.isFile())
+            invalid(`secret ${name} is not a regular file`);
+        const bytes = fs.readFileSync(descriptor);
+        const after = fs.fstatSync(descriptor, { bigint: true });
+        if (before.dev !== after.dev ||
+            before.ino !== after.ino ||
+            before.size !== after.size ||
+            before.mtimeNs !== after.mtimeNs) {
+            invalid(`secret ${name} changed while it was read`);
+        }
+        return bytes;
+    }
+    catch (cause) {
+        if (cause.code === "ENOENT")
+            return undefined;
+        throw cause;
+    }
+    finally {
+        if (descriptor !== undefined)
+            fs.closeSync(descriptor);
+    }
+}
+function trackParentDirectories(collector, rootInput, fileInput) {
+    const root = path.resolve(rootInput);
+    const parent = path.dirname(path.resolve(fileInput));
+    const relative = path.relative(root, parent);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        invalid("environment source escapes its owner root");
+    let current = root;
+    collector.trackDirectory(current, root);
+    if (relative === "")
+        return;
+    for (const segment of relative.split(path.sep)) {
+        current = path.join(current, segment);
+        collector.trackDirectory(current, root);
+    }
+}
+function secretTokenNames(values) {
+    const names = new Set();
+    for (const value of Object.values(values)) {
+        for (const match of value.matchAll(SECRET_TOKEN_RE)) {
+            const name = match[1];
+            if (name)
+                names.add(name);
+        }
+    }
+    return sortedCodePoints([...names]);
+}
+function sortedCodePoints(values) {
+    return values.sort((left, right) => (left < right ? -1 : left > right ? 1 : 0));
+}
+function sortedUnique(values, label, pattern) {
+    if (!Array.isArray(values))
+        invalid(`${label} must be an array`);
+    let prior;
+    for (const value of values) {
+        if (typeof value !== "string" || !pattern.test(value) || value.includes(".."))
+            invalid(`${label} is invalid`);
+        if (prior !== undefined && prior >= value)
+            invalid(`${label} must be sorted and unique`);
+        prior = value;
+    }
+}
+function sameStrings(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function exactKeys(value, keys) {
+    const allowed = new Set(keys);
+    for (const key of Object.keys(value))
+        if (!allowed.has(key))
+            invalid(`environment descriptor contains unknown key ${key}`);
+    for (const key of keys)
+        if (!Object.hasOwn(value, key))
+            invalid(`environment descriptor is missing ${key}`);
+}
+function environmentName(value) {
+    if (typeof value !== "string" || !ENVIRONMENT_NAME_RE.test(value))
+        invalid("environment name is invalid");
+}
+function physicalIdentity(realPath, stat) {
+    return stat.ino === 0n ? `path:${realPath}` : `inode:${stat.dev}:${stat.ino}`;
+}
+function invalid(message) {
+    throw new UsageError(`Invalid frozen workflow environment: ${message}.`, "INVALID_FLAG_VALUE");
+}

package/dist/workflows/ir/freeze-v4.js

@@ -0,0 +1,122 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { parseBundleRef } from "../../core/asset/asset-ref.js";
+import { UsageError } from "../../core/errors.js";
+import { GuardedExecutionSourceCollector } from "../../execution/guarded-source.js";
+import { defaultMapConcurrency, workflowMaxConcurrency } from "../concurrency-policy.js";
+import { compileWorkflowPlan } from "./compile.js";
+import { canonicalJson } from "./plan-hash.js";
+import { decodeWorkflowPlanV4, WORKFLOW_IR_V4_VERSION, } from "./schema-v4.js";
+import { resolveWorkflowSourceV4 } from "./source-freeze-v4.js";
+/** Compile, resolve, and freeze one executable plan without publishing any state. */
+export async function compileResolveFreezeWorkflowV4(asset, config, options = {}) {
+    const sourceCollector = options.sourceCollector ?? new GuardedExecutionSourceCollector();
+    const workflowSource = captureWorkflowSource(asset, sourceCollector);
+    const resolved = await resolveWorkflowSourceV4(asset, workflowSource, config, sourceCollector);
+    const compiled = compileWorkflowPlan(resolved.sourceIr, asset.title, resolved.units);
+    if (!compiled.ok) {
+        throw new UsageError(compiled.errors.map((error) => `${asset.path}:${error.line}: ${error.message}`).join("\n"), "INVALID_FLAG_VALUE");
+    }
+    const steps = compiled.plan.steps.map((step) => {
+        const frozenJudge = step.gate.criteria.length === 0 ? null : resolved.judges.get(step.stepId);
+        if (step.gate.criteria.length > 0 && !frozenJudge) {
+            throw new Error(`resolved workflow judge missing for step ${step.stepId}`);
+        }
+        const gate = Object.freeze({ ...step.gate, maxLoops: step.gate.maxLoops ?? 1, frozenJudge: frozenJudge ?? null });
+        if (!step.root) {
+            const { root: _root, ...withoutRoot } = step;
+            return Object.freeze({ ...withoutRoot, gate });
+        }
+        const frozen = resolved.units.get(step.stepId);
+        if (!frozen)
+            throw new Error(`resolved workflow target missing for step ${step.stepId}`);
+        const root = step.root.kind === "map"
+            ? {
+                ...step.root,
+                concurrency: step.root.concurrency ?? defaultMapConcurrency(config.workflow?.defaultMapConcurrency),
+                template: freezeResolvedUnit(step.root.template, frozen),
+            }
+            : freezeResolvedUnit(step.root, frozen);
+        return Object.freeze({ ...step, root, gate });
+    });
+    const sourceReadSet = sourceCollector
+        .snapshot()
+        .sources.filter((source) => Boolean(source.identity))
+        .map((source) => sourceSnapshot(source));
+    const plan = decodeWorkflowPlanV4({
+        irVersion: WORKFLOW_IR_V4_VERSION,
+        title: compiled.plan.title,
+        ...(compiled.plan.params ? { params: compiled.plan.params } : {}),
+        ...(compiled.plan.paramSchemas ? { paramSchemas: compiled.plan.paramSchemas } : {}),
+        ...(compiled.plan.budget ? { budget: compiled.plan.budget } : {}),
+        execution: { maxConcurrency: workflowMaxConcurrency(config.workflow?.maxConcurrency) },
+        sourceReadSet,
+        steps,
+    });
+    return Object.freeze({
+        plan,
+        warnings: compiled.warnings,
+        ...(resolved.engineAnnouncement ? { engineAnnouncement: resolved.engineAnnouncement } : {}),
+        sourceCollector,
+    });
+}
+function freezeResolvedUnit(unit, resolved) {
+    const frozenTarget = resolved.target.kind === "shell"
+        ? Object.freeze({
+            ...resolved.target,
+            contentHash: createHash("sha256")
+                .update("akm.workflow.shell.v1\0")
+                .update(canonicalJson({
+                exec: resolved.target.exec,
+                environment: resolved.environment,
+                cwdIdentity: resolved.target.cwdIdentity,
+            }))
+                .digest("hex"),
+        })
+        : resolved.target;
+    const { exec: _exec, ...common } = unit;
+    return Object.freeze({
+        ...common,
+        isolation: common.isolation ?? "none",
+        frozenTarget,
+        environment: Object.freeze([...resolved.environment]),
+    });
+}
+function captureWorkflowSource(asset, collector) {
+    const root = path.resolve(asset.sourcePath);
+    const file = path.resolve(asset.path);
+    collector.trackDirectory(root, root);
+    const parent = path.dirname(file);
+    const relativeParent = path.relative(root, parent);
+    if (relativeParent.startsWith("..") || path.isAbsolute(relativeParent)) {
+        throw new UsageError(`${file} resolves outside its workflow source root.`, "PATH_ESCAPE_VIOLATION");
+    }
+    let current = root;
+    for (const segment of relativeParent === "" ? [] : relativeParent.split(path.sep)) {
+        current = path.join(current, segment);
+        collector.trackDirectory(current, root);
+    }
+    const captured = collector.capture(file, root, { authored: true });
+    const parsed = parseBundleRef(asset.ref);
+    if (!parsed.bundle || !asset.adapterId) {
+        throw new UsageError(`Workflow ${asset.ref} has no fully-qualified bundle/adapter owner for durable publication.`, "INVALID_FLAG_VALUE");
+    }
+    return collector.bindIdentity(file, root, {
+        ref: asset.ref,
+        bundle: parsed.bundle,
+        adapter: asset.adapterId,
+        file: captured.relativePath,
+        hash: captured.sha256,
+    });
+}
+function sourceSnapshot(source) {
+    return Object.freeze({
+        identity: source.identity,
+        containmentPhysicalIdentity: source.containmentPhysicalIdentity,
+        physicalIdentity: source.physicalIdentity,
+        size: source.size,
+    });
+}

package/dist/workflows/ir/plan-hash.js

@@ -14,7 +14,7 @@
  */
 import { createHash } from "node:crypto";
 import { utf8Bytes, WORKFLOW_MAX_JSON_DEPTH, WORKFLOW_MAX_PLAN_BYTES } from "../resource-limits.js";
-import { decodeWorkflowPlanV3 } from "./schema.js";
+import { decodeWorkflowPlanV4, WORKFLOW_IR_V4_VERSION } from "./schema-v4.js";
 /** sha256 hex of the canonical (recursively sorted-keys) JSON of the plan. */
 export function computePlanHash(plan) {
     return createHash("sha256").update(canonicalPlanJson(plan)).digest("hex");
@@ -23,12 +23,12 @@ export function computePlanHash(plan) {
 export function canonicalPlanJson(plan) {
     return canonicalJson(plan);
 }
-/** Canonical JSON used by every v3 plan and input hash. */
+/** Canonical JSON used by every plan and input hash. */
 export function canonicalJson(value) {
     return JSON.stringify(sortKeys(value));
 }
 /** Decode, require stored canonical bytes, then verify the stored SHA-256. */
-export function decodeCanonicalPlan(runId, planJson, planHash) {
+export function decodeCanonicalPlan(runId, planJson, planHash, expectedVersion) {
     if (utf8Bytes(planJson) > WORKFLOW_MAX_PLAN_BYTES)
         throw new Error(`Workflow run ${runId} frozen plan exceeds the 2 MiB resource limit.`);
     let parsed;
@@ -38,13 +38,19 @@ export function decodeCanonicalPlan(runId, planJson, planHash) {
     catch {
         throw new Error(`Workflow run ${runId} has corrupt frozen plan JSON.`);
     }
-    const plan = decodeWorkflowPlanV3(parsed);
-    const canonical = canonicalPlanJson(plan);
-    if (planJson !== canonical)
+    const canonicalWire = canonicalJson(parsed);
+    if (planJson !== canonicalWire)
         throw new Error(`Workflow run ${runId} has noncanonical frozen plan JSON.`);
-    const actual = computePlanHash(plan);
+    const actual = createHash("sha256").update(planJson).digest("hex");
     if (!planHash || !/^[0-9a-f]{64}$/.test(planHash) || actual !== planHash)
         throw new Error(`Workflow run ${runId} frozen plan integrity check failed.`);
+    if (expectedVersion !== undefined && expectedVersion !== null && expectedVersion !== WORKFLOW_IR_V4_VERSION) {
+        throw new Error(`Workflow run ${runId} uses unsupported workflow IR version ${expectedVersion}; this runtime supports only workflow IR version 4.`);
+    }
+    const plan = decodeWorkflowPlanV4(parsed);
+    const canonical = canonicalPlanJson(plan);
+    if (planJson !== canonical)
+        throw new Error(`Workflow run ${runId} has noncanonical frozen plan JSON.`);
     return plan;
 }
 function sortKeys(value, depth = 0) {