@sanning/proof 0.18.0 → 0.19.0

package/src/exit-codes.ts

@@ -16,6 +16,14 @@ export const EXIT_FAILED = 1;
 export const EXIT_MALFORMED = 2;
 export const EXIT_UNDETERMINED = 3;
 export const EXIT_MIXED = 4;
+/**
+ * Sandbox evidence (envelope-spec §2): a run that would exit 0 over a pack or
+ * case holding a record signed `environment: "dev"`, or a run over records
+ * that are ALL signed `dev` whose only unsettled witnesses are simulated.
+ * Not a verdict word: the verdict stays what the checks established
+ * (`sandboxExit`). No flag turns 5 into 0.
+ */
+export const EXIT_SANDBOX = 5;
 
 /**
  * The exit code of each of the eight verdict words (`evidence-bundle.md` §3).
@@ -40,6 +48,7 @@ export const EXIT_CODES_HELP = [
   "  2  usage or malformed",
   "  3  undetermined: partial, pending, incomplete or not_found",
   "  4  mixed: more than one outcome, none failed; read the exceptions",
+  "  5  sandbox: a record is signed environment dev; would be 0, or only a simulated witness is unchecked",
 ].join("\n");
 
 /**
@@ -52,3 +61,22 @@ export function exitCodeFor(verdict: unknown): number {
   }
   return EXIT_MALFORMED;
 }
+
+/**
+ * The code a verb exits with once the environment marker is read. 5 where the
+ * run would otherwise exit 0 and the pack or case holds a record signed `dev`;
+ * 5 where the run is undetermined only because a simulated witness could not
+ * be looked up (`onlySimulatedUnsettled`, which the caller works out) and
+ * EVERY record is signed `dev`, so a production or mixed pack carrying a
+ * simulated witness keeps 3; the code unchanged everywhere else. A failure
+ * stays 1, malformed 2 and mixed 4.
+ */
+export function sandboxExit(
+  code: number,
+  environmentMarker: string | null,
+  onlySimulatedUnsettled = false,
+): number {
+  if (code === EXIT_VERIFIED && environmentMarker !== null) return EXIT_SANDBOX;
+  if (code === EXIT_UNDETERMINED && environmentMarker === "dev" && onlySimulatedUnsettled) return EXIT_SANDBOX;
+  return code;
+}

package/src/index.ts

@@ -25,6 +25,15 @@ export {
   specVersionSupported,
   verifyEnvelope,
 } from "./verifier.js";
+// The strict reader of bytes that claim to be JCS, the twin of Python's public
+// `canonicalize.jcs_loads`. The enclave attestation adapters read a token's
+// JSON through it, so they refuse what the kernel refuses. Additive.
+export { jcsParse } from "./verifier.js";
+// The same reader within the enclave readers' limits (enclave-attestation
+// section 2.1): depth checked on the bytes first, every number finite. The
+// adapters read a token's header and claims and the manifest through it.
+// Additive.
+export { exceedsTextDepth, hasNonFiniteNumber, jcsParseWithinLimits, MAX_READ_DEPTH } from "./verifier.js";
 export {
   bytesToHex,
   deriveOperatorAddress,
@@ -175,6 +184,7 @@ export {
   DECLARATION_VERDICTS,
   DECLARATION_VERSION,
   DECLARATION_VERSION_V2,
+  DECLARATION_VERSION_V3,
   DECLARATION_VERSIONS,
   checkDeclaration,
   declarationClaims,
@@ -353,7 +363,10 @@ export type {
 // `vectors/chain-reading.json` beside the pack-grading table for the same
 // reason: a rule consumers must agree with needs a statement they can fetch.
 //
-// It returns FINDINGS, never a verdict, and it feeds no status. Chain links are
+// It returns FINDINGS, never a verdict, and it feeds no status on its own: a
+// pack's signed v3 declaration can claim a chain complete and in order, and
+// `checkDeclaration` holds that claim to the links `readChainLinks` reads
+// (evidence-bundle.md 5.4.2 rule 11). Chain links are
 // deletion/reorder-evidence for the events present and NOT a completeness proof
 // (`anchor/docs/profile-sanning.events-v2.md` §5), drop the last N events of a
 // chain and nothing dangles. `CHAIN_READING_SCOPE` is that sentence, exported so
@@ -362,12 +375,14 @@ export type {
 export {
   ADAPTER_CHAIN_NAMESPACES,
   CHAIN_READING_SCOPE,
+  readChainLinks,
   readChains,
   renderChainFinding,
 } from "./chain.js";
 export type {
   ChainFinding,
   ChainFindingKind,
+  ChainLink,
   ChainReading,
   ChainSource,
   ChainSummary,
@@ -385,10 +400,24 @@ export {
   EXIT_FAILED,
   EXIT_MALFORMED,
   EXIT_MIXED,
+  EXIT_SANDBOX,
   EXIT_UNDETERMINED,
   EXIT_VERIFIED,
   exitCodeFor,
+  sandboxExit,
 } from "./exit-codes.js";
+// Sandbox evidence: the environment marker over the envelopes a pack or case
+// holds (envelope-spec §2, the `environment_marker` MAY), and the headline and
+// line both commands print for it. Additive.
+export {
+  SANDBOX_HEADLINE,
+  SANDBOX_LINE,
+  SANDBOX_TITLE,
+  environmentMarker,
+  onlySimulatedUnsettled,
+  packEnvelopes,
+} from "./environment.js";
+export type { EnvironmentMarker } from "./environment.js";
 export { attestationSignatureToHex, composeExport } from "./compose.js";
 export type { ComposeExportOptions, ComposeExportResult, ExporterKey } from "./compose.js";
 

package/src/run-adapters.ts

@@ -0,0 +1,44 @@
+// Loading the enclave attestation adapters a reader has installed. Kept out of
+// `index.ts` on purpose: it imports packages by name, which a browser bundle
+// cannot resolve, and only the command line needs it. `run.ts` imports nothing.
+//
+// The packages are named by `ADAPTER_MODULES` and by nothing else: a provider
+// id read from a pack is never turned into a module name.
+
+import { ADAPTER_MODULES, declaredKinds, type EnclaveAdapter } from "./run.js";
+
+/** Import a module by name. A parameter so a test can watch what is asked for. */
+export type Importer = (name: string) => Promise<unknown>;
+
+const dynamicImport: Importer = (name) => import(/* @vite-ignore */ name);
+
+/**
+ * The adapters this environment holds, loaded from `ADAPTER_MODULES` and
+ * nothing else. A module counts only when it exports the provider it was
+ * loaded for as `provider`, a `check` function, and the failure kinds it
+ * declares as `kinds` (`declaredKinds`).
+ */
+export async function loadInstalledAdapters(
+  importer: Importer = dynamicImport,
+): Promise<Map<string, EnclaveAdapter>> {
+  const found = new Map<string, EnclaveAdapter>();
+  for (const [provider, name] of Object.entries(ADAPTER_MODULES)) {
+    let module: unknown;
+    try {
+      module = await importer(name);
+    } catch {
+      continue;
+    }
+    const m = module as Partial<EnclaveAdapter> | null;
+    if (
+      m !== null &&
+      typeof m === "object" &&
+      m.provider === provider &&
+      typeof m.check === "function" &&
+      declaredKinds(m) !== null
+    ) {
+      found.set(provider, m as EnclaveAdapter);
+    }
+  }
+  return found;
+}