@cassiomc1/forgeloop 0.1.13 → 0.1.15

package/src/core/phase.js

@@ -101,7 +101,7 @@ function reconcileImplementationStep(state, toPhase) {
   };
 }
 
-async function assertPhasePrerequisites(target, state, toPhase, packageRoot) {
+async function assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext) {
   if (toPhase === "CONTRACT_READY" || toPhase === "ROUTED" || toPhase === "EXECUTING") {
     try {
       await readContract(target, packageRoot);
@@ -127,7 +127,7 @@ async function assertPhasePrerequisites(target, state, toPhase, packageRoot) {
     throw phaseError("E_PHASE_EVIDENCE_MISSING", "COMPLETE requires verification evidence");
   }
   if (toPhase === "COMPLETE") {
-    const completion = await evaluateCompletion({ target, packageRoot, persist: false });
+    const completion = await evaluateCompletion({ target, packageRoot, persist: false, authorityContext, runtimeContext });
     if (completion.status !== "VALID") {
       throw phaseError("E_COMPLETION_REJECTED", "COMPLETE requires a valid completion audit", completion.errors.flatMap((error) => error.artifacts ?? []));
     }
@@ -136,11 +136,16 @@ async function assertPhasePrerequisites(target, state, toPhase, packageRoot) {
 
 export async function advanceWorkState(target, toPhase, options = {}) {
   const normalizedOptions = typeof options === "string" ? { packageRoot: options } : options;
-  const { packageRoot, now = new Date().toISOString() } = normalizedOptions;
+  const {
+    packageRoot,
+    now = new Date().toISOString(),
+    authorityContext,
+    runtimeContext,
+  } = normalizedOptions;
   assertWorkPhase(toPhase);
   const state = await readWorkState(target, packageRoot);
   if (!state) throw phaseError("E_PHASE_PREREQUISITE_MISSING", "Cannot advance without work state", [ARTIFACT_PATHS.state]);
-  await assertPhasePrerequisites(target, state, toPhase, packageRoot);
+  await assertPhasePrerequisites(target, state, toPhase, packageRoot, authorityContext, runtimeContext);
   await assertPersistedStateIdentity(target, state, toPhase, packageRoot);
   if (!isValidTransition(state.phase, toPhase)) {
     throw phaseError("E_PHASE_TRANSITION_INVALID", `Invalid work-state transition: ${state.phase} -> ${toPhase}`);
@@ -231,7 +236,12 @@ export async function advanceWorkState(target, toPhase, options = {}) {
       packageRoot,
       additionalEvidence: preflight.policy?.requiredEvidence ?? [],
     });
-    await validateReceipt(receipt.value, packageRoot);
+    await validateReceipt(receipt.value, packageRoot, {
+      target,
+      taskId: contract?.value?.taskId,
+      authorityContext,
+      runtimeContext,
+    });
     assertCompletionRelationships({
       contract,
       route,
@@ -240,12 +250,21 @@ export async function advanceWorkState(target, toPhase, options = {}) {
       requiredEvidence,
       requireRequiredChecks: false,
       requireReceiptStateFingerprint: false,
+      target,
+      taskId: contract?.value?.taskId,
+      authorityContext,
+      runtimeContext,
     });
     nextReceipt = await createReceipt({
       ...receipt.value,
       stateFingerprint: canonicalFingerprint(next),
       verificationCycle: next.verificationCycle ?? receipt.value.verificationCycle ?? 1,
-    }, packageRoot);
+    }, packageRoot, {
+      target,
+      taskId: contract?.value?.taskId,
+      authorityContext,
+      runtimeContext,
+    });
     assertCompletionRelationships({
       contract,
       route,
@@ -253,6 +272,10 @@ export async function advanceWorkState(target, toPhase, options = {}) {
       receipt: nextReceipt,
       requiredEvidence,
       requireRequiredChecks: false,
+      target,
+      taskId: contract?.value?.taskId,
+      authorityContext,
+      runtimeContext,
     });
   } catch (error) {
     if (error.code !== "ARTIFACT_MISSING") throw error;

package/src/core/protocol.js

@@ -81,6 +81,11 @@ export const FAILURE_CODES = Object.freeze([
   "E_TERMINAL_REQUIREMENT_NOT_TERMINAL",
   "E_TERMINAL_REQUIREMENT_TYPE_MISMATCH",
   "E_TERMINAL_STATUS_REGRESSION",
+  "E_INSTALLATION_AUTHORITY_REQUIRED",
+  "E_AUTHORITY_INVALID",
+  "E_AUTHORITY_SCOPE_MISMATCH",
+  "E_AUTHORITY_UNTRUSTED_SOURCE",
+  "E_VERIFICATION_TOOL_UNAVAILABLE",
 ]);
 
 export const WORK_PHASES = Object.freeze([

package/src/core/receipt.js

@@ -56,7 +56,7 @@ function assertKnownGuides(guides) {
   if (new Set(guides).size !== guides.length) throw new Error("Receipt selectedGuides must not contain duplicates");
 }
 
-export function assertReceiptSemantics(receipt) {
+export function assertReceiptSemantics(receipt, options = {}) {
   const evidence = receipt.evidence ?? [];
   if (receipt.verificationCycle !== undefined
     && (!Number.isInteger(receipt.verificationCycle) || receipt.verificationCycle < 1)) {
@@ -66,7 +66,7 @@ export function assertReceiptSemantics(receipt) {
 
   for (const [index, check] of receipt.checks.entries()) {
     if (check?.schemaVersion !== undefined || check?.id !== undefined || check?.evidenceKind !== undefined) {
-      assertCheck(check, `receipt.checks[${index}]`);
+      assertCheck(check, `receipt.checks[${index}]`, options);
       continue;
     }
     if (check?.status === "passed") {
@@ -132,15 +132,15 @@ export function assertReceiptSemantics(receipt) {
   return receipt;
 }
 
-export async function validateReceipt(receipt, packageRoot) {
+export async function validateReceipt(receipt, packageRoot, options = {}) {
   assertSecretFree(receipt);
   const schema = await readSchema("execution-receipt", packageRoot);
   assertSchema(receipt, schema, "execution receipt");
   assertKnownGuides(receipt.selectedGuides);
-  return assertReceiptSemantics(receipt);
+  return assertReceiptSemantics(receipt, options);
 }
 
-export async function createReceipt(input, packageRoot) {
+export async function createReceipt(input, packageRoot, options = {}) {
   assertSecretFree(input);
   const receipt = {
     schemaVersion: RECEIPT_SCHEMA_VERSION,
@@ -169,5 +169,5 @@ export async function createReceipt(input, packageRoot) {
       deployed: false,
     },
   };
-  return validateReceipt(receipt, packageRoot);
+  return validateReceipt(receipt, packageRoot, options);
 }

package/src/core/runtime-context.js

@@ -0,0 +1,80 @@
+export const AUTHORITY_TRUST_MODES = Object.freeze(["NONE", "HOST_ATTESTED"]);
+
+const AUTHORITY_CONTEXT_FIELDS = Object.freeze([
+  "trustedAuthorityFile",
+  "trustedAuthorityDir",
+  "authorities",
+  "authority",
+]);
+
+function configuredValue(value) {
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : undefined;
+}
+
+function providerValue(provider) {
+  if (typeof provider === "function") return provider();
+  return provider && typeof provider === "object" && !Array.isArray(provider) ? provider : {};
+}
+
+function contextInput(input = {}) {
+  const source = input && typeof input === "object" && !Array.isArray(input) ? input : {};
+  const provider = providerValue(source.trustedAuthorityProvider);
+  const explicit = source.authorityContext && typeof source.authorityContext === "object"
+    ? source.authorityContext
+    : {};
+  const { authorityContext: _authorityContext, trustedAuthorityProvider: _trustedAuthorityProvider, ...direct } = source;
+  return { ...direct, ...provider, ...explicit };
+}
+
+export function hasAuthorityContext(options = {}) {
+  if (!options || typeof options !== "object") return false;
+  return Boolean(
+    options.authorityContext
+    || options.runtimeContext?.authorityContext
+    || (options.runtimeContext && typeof options.runtimeContext === "object" && options.runtimeContext.trustMode),
+  );
+}
+
+export function createAuthorityContext(input = {}) {
+  const values = contextInput(input);
+  const trustMode = values.trustMode ?? values.authorityTrustMode ?? "NONE";
+  if (!AUTHORITY_TRUST_MODES.includes(trustMode)) {
+    const error = new Error(`Unsupported authority trust mode: ${trustMode}`);
+    error.code = "E_AUTHORITY_INVALID";
+    throw error;
+  }
+
+  const context = { trustMode };
+  for (const field of AUTHORITY_CONTEXT_FIELDS) {
+    if (field === "trustedAuthorityFile" || field === "trustedAuthorityDir") {
+      const value = configuredValue(values[field]);
+      if (value !== undefined) context[field] = value;
+    } else if (values[field] !== undefined) {
+      context[field] = values[field];
+    }
+  }
+  return Object.freeze(context);
+}
+
+export function resolveAuthorityContext(options = {}) {
+  const source = options && typeof options === "object" && !Array.isArray(options) ? options : {};
+  if (source.authorityContext !== undefined) {
+    return createAuthorityContext(source.authorityContext);
+  }
+  if (source.runtimeContext?.authorityContext !== undefined) {
+    return createAuthorityContext(source.runtimeContext.authorityContext);
+  }
+  if (source.runtimeContext && typeof source.runtimeContext === "object" && source.runtimeContext.trustMode) {
+    return createAuthorityContext(source.runtimeContext);
+  }
+
+  const hasDirectAuthority = AUTHORITY_CONTEXT_FIELDS.some((field) => source[field] !== undefined);
+  // Direct resolver options are legacy source selectors, not a host attestation
+  // channel. They remain NONE unless wrapped in an explicit runtime context.
+  return hasDirectAuthority ? createAuthorityContext({ ...source, trustMode: "NONE" }) : createAuthorityContext();
+}
+
+export function createForgeLoopContext(options = {}) {
+  const authorityContext = createAuthorityContext(options);
+  return Object.freeze({ authorityContext });
+}

package/src/core/schema-validation.js

@@ -24,6 +24,7 @@ export const SHIPPED_SCHEMA_NAMES = Object.freeze([
   "activation",
   "policy",
   "task-bundle",
+  "execution",
 ]);
 
 export class SchemaValidationError extends Error {

package/src/core/templates.js

@@ -59,6 +59,7 @@ export const TEMPLATE_PATHS = [
   "schemas/config.schema.json",
   "schemas/preflight.schema.json",
   "schemas/check.schema.json",
+  "schemas/execution.schema.json",
   "schemas/evidence-coverage.schema.json",
   "schemas/event.schema.json",
   "schemas/activation.schema.json",

package/src/core/trusted-authority.js

@@ -0,0 +1,296 @@
+import { accessSync, constants as fsConstants, lstatSync, readFileSync, realpathSync } from "node:fs";
+import path from "node:path";
+
+import { assertJsonBytes, assertJsonLimits } from "./json-safety.js";
+import {
+  hasAuthorityContext,
+  resolveAuthorityContext,
+} from "./runtime-context.js";
+
+export const E_AUTHORITY_UNTRUSTED_SOURCE = "E_AUTHORITY_UNTRUSTED_SOURCE";
+const E_AUTHORITY_INVALID = "E_AUTHORITY_INVALID";
+const AUTHORITY_FILE_ENV = "FORGELOOP_AUTHORITY_FILE";
+const AUTHORITY_DIR_ENV = "FORGELOOP_AUTHORITY_DIR";
+
+function configuredValue(value) {
+  return typeof value === "string" && value.trim() !== "" ? value.trim() : null;
+}
+
+function authoritySourceOptions(options = {}) {
+  const context = resolveAuthorityContext(options);
+  const contextProvided = hasAuthorityContext(options);
+  const directFile = configuredValue(options.trustedAuthorityFile);
+  const directDir = configuredValue(options.trustedAuthorityDir);
+  const contextFile = configuredValue(context.trustedAuthorityFile);
+  const contextDir = configuredValue(context.trustedAuthorityDir);
+  const file = contextFile ?? (contextProvided ? null : directFile);
+  const dir = contextDir ?? (contextProvided ? null : directDir);
+  const authorities = context.authorities ?? (contextProvided ? undefined : options.authorities);
+  const authority = context.authority ?? (contextProvided ? undefined : options.authority);
+
+  if (contextProvided
+    && context.trustMode !== "HOST_ATTESTED"
+    && !file
+    && !dir
+    && authorities === undefined
+    && authority === undefined) {
+    const envFile = configuredValue(process.env[AUTHORITY_FILE_ENV]);
+    const envDir = configuredValue(process.env[AUTHORITY_DIR_ENV]);
+    return {
+      context,
+      file: envFile,
+      dir: envDir,
+      authorities: undefined,
+      authority: undefined,
+      sourceConfigured: Boolean(envFile || envDir),
+      sourceType: envFile ? "external-file" : envDir ? "external-dir" : null,
+    };
+  }
+
+  if (context.trustMode === "HOST_ATTESTED" || contextProvided || file || dir || authorities !== undefined || authority !== undefined) {
+    return {
+      context,
+      file,
+      dir,
+      authorities,
+      authority,
+      sourceConfigured: Boolean(file || dir || authorities !== undefined || authority !== undefined),
+      sourceType: file ? "external-file" : dir ? "external-dir" : authorities !== undefined || authority !== undefined ? "in-memory" : null,
+    };
+  }
+
+  const envFile = configuredValue(process.env[AUTHORITY_FILE_ENV]);
+  const envDir = configuredValue(process.env[AUTHORITY_DIR_ENV]);
+  return {
+    context,
+    file: envFile,
+    dir: envDir,
+    authorities: undefined,
+    authority: undefined,
+    sourceConfigured: Boolean(envFile || envDir),
+    sourceType: envFile ? "external-file" : envDir ? "external-dir" : null,
+  };
+}
+
+export function trustedAuthorityConfiguration(options = {}) {
+  const { context, sourceConfigured, sourceType, file, dir } = authoritySourceOptions(options);
+  const sourceInsideTarget = options.target && (file || dir)
+    ? isInsideTarget(options.target, file ?? dir)
+    : false;
+  return {
+    sourceConfigured,
+    sourceType,
+    trustMode: context.trustMode,
+    trusted: context.trustMode === "HOST_ATTESTED" && sourceConfigured && !sourceInsideTarget,
+  };
+}
+
+function invalid(message, details = {}) {
+  return {
+    trusted: false,
+    error: { code: E_AUTHORITY_INVALID, message },
+    ...details,
+  };
+}
+
+function untrusted(message) {
+  return {
+    trusted: false,
+    error: { code: E_AUTHORITY_UNTRUSTED_SOURCE, message },
+  };
+}
+
+function authorityFileName(authorityRef) {
+  if (typeof authorityRef !== "string" || authorityRef.trim() === "") return null;
+  const ref = authorityRef.trim();
+  if (ref === "." || ref === ".." || ref.includes("/") || ref.includes("\\")) return null;
+  return ref.endsWith(".json") ? ref : `${ref}.json`;
+}
+
+function resolvedPath(candidate) {
+  const absolute = path.resolve(candidate);
+  const missingSegments = [];
+  let current = absolute;
+  while (true) {
+    try {
+      const existing = realpathSync(current);
+      return path.resolve(existing, ...missingSegments);
+    } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+      const parent = path.dirname(current);
+      if (parent === current) return absolute;
+      missingSegments.unshift(path.basename(current));
+      current = parent;
+    }
+  }
+}
+
+function isWithin(parent, candidate) {
+  const relative = path.relative(parent, candidate);
+  return relative === ""
+    || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function isInsideTarget(target, candidate) {
+  if (!target) return false;
+  // Check both lexical paths and their real paths. The lexical check rejects
+  // actor-created symlinks inside the target that point at an external file.
+  return isWithin(path.resolve(target), path.resolve(candidate))
+    || isWithin(resolvedPath(target), resolvedPath(candidate));
+}
+
+function readExternalJson(candidate, target, kind) {
+  if (isInsideTarget(target, candidate)) {
+    return untrusted(`Configured trusted authority ${kind} must be outside the actor-writable target`);
+  }
+
+  try {
+    accessSync(candidate, fsConstants.R_OK);
+    const info = lstatSync(candidate);
+    if (kind === "file" && !info.isFile()) {
+      return invalid("Configured trusted authority file is not a regular file");
+    }
+    if (kind === "directory" && !info.isDirectory()) {
+      return invalid("Configured trusted authority directory is not a directory");
+    }
+    const bytes = readFileSync(candidate);
+    assertJsonBytes(bytes, `trusted authority ${kind}`);
+    const value = JSON.parse(bytes.toString("utf8"));
+    assertJsonLimits(value, `trusted authority ${kind}`);
+    return { value };
+  } catch {
+    return invalid(`Configured trusted authority ${kind} could not be read or parsed`);
+  }
+}
+
+function grantsFromValue(value) {
+  if (Array.isArray(value)) return value;
+  if (value && typeof value === "object" && Array.isArray(value.authorities)) {
+    if (value.schemaVersion !== 1 || value.protocolVersion !== 1) return null;
+    return value.authorities;
+  }
+  return value && typeof value === "object" ? [value] : null;
+}
+
+function findAuthority(value, authorityRef) {
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const keyedAuthority = value[authorityRef];
+    if (keyedAuthority && typeof keyedAuthority === "object") return keyedAuthority;
+  }
+  const envelope = value && typeof value === "object" && !Array.isArray(value)
+    && Array.isArray(value.authorities)
+    ? value
+    : null;
+  const grants = grantsFromValue(value);
+  if (!grants) return null;
+  const authority = grants.find((item) => item?.authorityId === authorityRef || item?.id === authorityRef) ?? null;
+  if (!authority || !envelope) return authority;
+  return {
+    ...authority,
+    schemaVersion: envelope.schemaVersion,
+    protocolVersion: envelope.protocolVersion,
+  };
+}
+
+function findInMemoryAuthority(authorities, authority, authorityRef) {
+  if (authority !== undefined) {
+    return authority?.authorityId === authorityRef || authority?.id === authorityRef ? authority : null;
+  }
+  if (authorities !== undefined) {
+    return findAuthority(authorities, authorityRef);
+  }
+  return undefined;
+}
+
+function resolveFromExternalFile(authorityRef, target, file) {
+  const read = readExternalJson(file, target, "file");
+  if (read.error) return read;
+  const authority = findAuthority(read.value, authorityRef);
+  return authority
+    ? { trusted: true, authority, sourceType: "external-file" }
+    : invalid(`Referenced installation authority '${authorityRef}' was not found in the trusted authority file`);
+}
+
+function resolveFromExternalDirectory(authorityRef, target, dir) {
+  const fileName = authorityFileName(authorityRef);
+  if (!fileName) return invalid("Installation authority reference must be a simple authority ID");
+  if (isInsideTarget(target, dir)) {
+    return untrusted("Configured trusted authority directory must be outside the actor-writable target");
+  }
+  try {
+    accessSync(dir, fsConstants.R_OK);
+    if (!lstatSync(dir).isDirectory()) {
+      return invalid("Configured trusted authority directory is not a directory");
+    }
+  } catch {
+    return invalid("Configured trusted authority directory could not be read");
+  }
+  const authorityPath = path.join(dir, fileName);
+  const read = readExternalJson(authorityPath, target, "file");
+  if (read.error) return read;
+  const authority = findAuthority(read.value, authorityRef);
+  return authority
+    ? { trusted: true, authority, sourceType: "external-dir" }
+    : invalid(`Referenced installation authority '${authorityRef}' does not match the trusted authority file`);
+}
+
+function projectLocalAuthorityExists(authorityRef, target) {
+  const fileName = authorityFileName(authorityRef);
+  if (!fileName || !target) return false;
+  const localPath = path.join(target, ".forgeloop", "authorities", fileName);
+  try {
+    accessSync(localPath, fsConstants.F_OK);
+    return true;
+  } catch (error) {
+    if (error.code === "ENOENT") return false;
+    return true;
+  }
+}
+
+export function resolveTrustedAuthority({
+  authorityRef,
+  target,
+  trustedAuthorityFile,
+  trustedAuthorityDir,
+  authorities,
+  authority,
+  authorityContext,
+  runtimeContext,
+} = {}) {
+  const fileName = authorityFileName(authorityRef);
+  if (!fileName) return invalid("Installation authority reference must be a simple authority ID");
+
+  const sources = authoritySourceOptions({
+    trustedAuthorityFile,
+    trustedAuthorityDir,
+    authorities,
+    authority,
+    authorityContext,
+    runtimeContext,
+  });
+  if (sources.sourceConfigured && sources.context.trustMode !== "HOST_ATTESTED") {
+    return untrusted("Standalone configuration selects an authority source but does not attest host authority");
+  }
+  if ((sources.file || sources.dir) && !target) {
+    return untrusted("A target path is required to validate trusted authority provenance");
+  }
+  if (sources.file) return resolveFromExternalFile(authorityRef, target, sources.file);
+  if (sources.dir) return resolveFromExternalDirectory(authorityRef, target, sources.dir);
+
+  // In-memory authorities are a host-injected policy interface. They never
+  // originate from project-local files and are intentionally resolved only
+  // after the explicit external sources above.
+  const inMemory = findInMemoryAuthority(sources.authorities, sources.authority, authorityRef);
+  if (inMemory !== undefined) {
+    return inMemory
+      ? { trusted: true, authority: inMemory, sourceType: "in-memory" }
+      : invalid(`Referenced installation authority '${authorityRef}' could not be resolved`);
+  }
+
+  if (projectLocalAuthorityExists(authorityRef, target)) {
+    return untrusted("Project-local authority artifacts are references only and are not trusted authority sources");
+  }
+  return invalid(`Referenced installation authority '${authorityRef}' could not be resolved`, {
+    sourceConfigured: sources.sourceConfigured,
+  });
+}