@crewhaus/spec 0.1.1 → 0.1.3

package/src/index.ts

@@ -2,6 +2,22 @@ import { SpecParseError } from "@crewhaus/errors";
 import { parse as parseYaml } from "yaml";
 import { z } from "zod";
 
+// SECURITY (codegen-injection backstop, #147/#148): spec/role/node/step names
+// flow verbatim into generated source across ~14 emitters — `//` and `/* */`
+// comments, template literals, JSON `package.json` manifests, YAML frontmatter,
+// and on-disk file paths (`skills/<name>/SKILL.md`). A raw newline, `*/`, quote,
+// backtick or `/` lets a crafted name break out of those contexts (RCE on
+// build/run, dependency injection, path traversal). The emitters escape per-site
+// as defense-in-depth, but this is the systemic floor: restrict names to a
+// single-line safe charset so the breakout characters can never enter the IR.
+const safeName = z
+  .string()
+  .min(1)
+  .regex(
+    /^[\w .:-]+$/,
+    "name may contain only letters, digits, spaces, and '_ . - :' (no newlines, quotes, slashes, or comment/template delimiters)",
+  );
+
 /**
  * v0 spec schema — a discriminated union over `target`.
  *
@@ -83,7 +99,7 @@ const subAgentDefinitionSchema = z
   })
   .strict();
 
-const subAgentsBlock = z.record(z.string().min(1), subAgentDefinitionSchema).optional();
+const subAgentsBlock = z.record(safeName, subAgentDefinitionSchema).optional();
 
 /**
  * Section 14 — per-tool runtime config map. Tool-specific schemas live
@@ -91,8 +107,80 @@ const subAgentsBlock = z.record(z.string().min(1), subAgentDefinitionSchema).opt
  * `unknown` and forwards it verbatim to the IR. The codegen layer emits
  * an init call (e.g. `registerFetchConfig({ ... })`) for tools whose
  * BUILTIN_TOOL_MAP entry declares an `initSymbol`.
+ *
+ * SECURITY (sandbox-override hardening): the code-execution config is the
+ * one exception to "opaque `unknown`". Its blob is compiled verbatim into
+ * `registerCodeExecutionConfig(...)` in the generated bundle, and the
+ * @crewhaus/sandbox boundary validates images/mounts against THIS same
+ * blob's allowlist (`allowedImages`, `mountWhitelist`). If a spec could set
+ * those — or `backend` (e.g. force `noop`, which is no isolation at all),
+ * `images`, or `mounts` — an untrusted marketplace/template spec would be
+ * supplying its own sandbox allowlist, making the controls self-defeating.
+ * The sandbox boundary must come only from trusted operator config (the CLI
+ * / `CREWHAUS_SANDBOX*` env vars), never from a spec file. So the
+ * code-execution config is constrained to a strict allowlist of non-security
+ * knobs; any sandbox-override key is rejected at parse time (defense in
+ * depth, mirroring `permissions.mode: bypass`).
+ *
+ * The code-execution config can arrive under any of the keys whose
+ * BUILTIN_TOOL_MAP entry maps to `registerCodeExecutionConfig` — the
+ * `codeExecution`/`code_execution` aliases AND the per-tool keys
+ * `python`/`javascript`/`shell` (target-cli `resolveTools` reads the
+ * per-tool key first, then the aliases). All of them must be constrained,
+ * or the guard is trivially bypassed by nesting the blob under `python`.
  */
-const toolConfigBlock = z.record(z.string().min(1), z.unknown()).optional();
+const SANDBOX_OVERRIDE_KEYS = [
+  "sandbox",
+  "backend",
+  "allowedImages",
+  "allowed_images",
+  "mountWhitelist",
+  "mount_whitelist",
+  "images",
+  "mounts",
+] as const;
+
+const CODE_EXECUTION_CONFIG_KEYS = [
+  "codeExecution",
+  "code_execution",
+  "python",
+  "javascript",
+  "shell",
+] as const;
+
+const codeExecutionConfigSchema = z
+  .object({
+    // Non-security knobs only. The sandbox boundary (backend, image
+    // allowlist, mount whitelist, per-language images, mounts) is owned by
+    // trusted operator config and is intentionally NOT settable from a spec.
+    defaultTimeoutMs: z.number().int().positive().optional(),
+    default_timeout_ms: z.number().int().positive().optional(),
+    warmPoolSize: z.number().int().nonnegative().optional(),
+    warm_pool_size: z.number().int().nonnegative().optional(),
+  })
+  .strict(
+    `code-execution config may only set non-security knobs (defaultTimeoutMs, warmPoolSize); sandbox-boundary keys (${SANDBOX_OVERRIDE_KEYS.join(", ")}) are owned by trusted operator config and rejected from specs`,
+  );
+
+const toolConfigBlock = z
+  .record(z.string().min(1), z.unknown())
+  .superRefine((cfg, ctx) => {
+    for (const key of CODE_EXECUTION_CONFIG_KEYS) {
+      const value = cfg[key];
+      if (value === undefined) continue;
+      const parsed = codeExecutionConfigSchema.safeParse(value);
+      if (!parsed.success) {
+        for (const issue of parsed.error.issues) {
+          ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: [key, ...issue.path],
+            message: issue.message,
+          });
+        }
+      }
+    }
+  })
+  .optional();
 
 /**
  * Section 17 — optional override for the model used by
@@ -122,6 +210,67 @@ const compactionBlock = z
   .strict()
   .optional();
 
+/**
+ * Pillar 3 (FR-004) — per-target security fabric block. Today it carries
+ * the intent-gate's judge selection; the optimizable path
+ * `["security", "justification"]` is already registered in
+ * `spec-patch`'s `OPTIMIZABLE_PATHS`, so this block MUST be named
+ * `security` with a `justification` sub-field to honour it.
+ *
+ * `justification.judge` selects which `JustificationJudge` the cli run
+ * path wires: `"rule-based"` (the deterministic default for tests/offline
+ * runs) or `"claude"` (the model-backed `@crewhaus/justification-judge-claude`,
+ * the documented production recommendation). `model` is the judge model
+ * id for the claude judge; the consumer defaults it to a haiku-class
+ * model when omitted.
+ *
+ * NOTE: `egressPolicy` is reserved — `OPTIMIZABLE_PATHS` also lists
+ * `["security", "egressPolicy"]`, owned by the egress-fabric FRs
+ * (FR-002/006). Do NOT add `egressPolicy` here; that would clobber their
+ * sub-field. FR-004 added `justification`; FR-006 added `egressMatcher`
+ * (the substring/semantic selector) alongside it — both are independent
+ * optional sub-fields of this same block.
+ */
+const securityBlock = z
+  .object({
+    justification: z
+      .object({
+        judge: z.enum(["rule-based", "claude"]).default("rule-based"),
+        model: z.string().min(1).optional(),
+      })
+      .strict()
+      .optional(),
+    /**
+     * Pillar 3 sink-side fabric (FR-006) — select the egress-matching
+     * strategy. `"substring"` (the default when omitted) is the
+     * behavior-preserving `SubstringEgressMatcher` with `MIN_MATCH_LENGTH`.
+     * `"semantic"` selects the optional embedding-backed
+     * `@crewhaus/egress-matcher-semantic`, which scores outbound payloads
+     * against tagged data-lineage by cosine similarity. Switching the
+     * matcher changes *how* lineage matches are detected; the per-origin/
+     * per-sink policy and the three audit outcomes are unaffected.
+     *
+     * This field is lowered to `IrSecurity.egressMatcher` (FR-006) and
+     * honoured by the `crewhaus run` path, which resolves the selector and
+     * threads the matcher into `runChatLoop({ egressMatcher })` — exactly
+     * how `security.justification.judge` selects the intent-gate judge on
+     * the same path. `"semantic"` constructs the optional
+     * `@crewhaus/egress-matcher-semantic` (with an injected embedder; see
+     * `--egress-embedder`). The runtime SEAM
+     * (`RunChatLoopOptions.egressMatcher`) underlies both.
+     *
+     * The *generated cli bundle* also honours this field: `@crewhaus/target-cli`
+     * emits the matcher construction (the semantic one with an injected
+     * `@crewhaus/embedder` embedder) into the bundle's
+     * `runChatLoop({ egressMatcher })`, so a compiled standalone artifact uses
+     * `semantic` WITHOUT the `crewhaus run` path. The substring default emits
+     * nothing, keeping the bundle free of any embedding dependency.
+     */
+    egressMatcher: z.enum(["substring", "semantic"]).optional(),
+  })
+  .strict()
+  .optional();
+
 /**
  * Section 55 (Track A) — named failure taxonomy. Cross-cutting block
  * available on every target shape. Each entry names a failure class and
@@ -202,6 +351,16 @@ const transactionPolicySchema = z
   .object({
     defaultWriteApproval: z.enum(["required", "policy", "none"]).default("required"),
     maxValueUsd: z.number().positive().optional(),
+    // Oracle-free native-token spend ceiling (wei). This is the ONLY value cap
+    // wallet-engine can actually enforce — maxValueUsd hard-throws without a
+    // price oracle. Decimal or 0x-hex string (parsed via BigInt downstream).
+    maxValueWei: z
+      .string()
+      .regex(
+        /^(0x[0-9a-fA-F]+|[0-9]+)$/,
+        "maxValueWei must be a wei amount as a decimal or 0x-hex string",
+      )
+      .optional(),
     allowedContracts: z.array(z.string().min(1)).default([]),
     simulationRequired: z.boolean().default(true),
   })
@@ -282,7 +441,7 @@ const channelGatewayBlock = z
 
 const cliSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("cli"),
     agent: z
       .object({
@@ -296,6 +455,7 @@ const cliSchema = z
     mcp_servers: mcpServersBlock,
     permissions: permissionsBlock,
     compaction: compactionBlock,
+    security: securityBlock,
     failure_taxonomy: failureTaxonomyBlock,
     cli: cliOptionsBlock,
     chains: chainsBlock,
@@ -307,7 +467,7 @@ const cliSchema = z
 
 const workflowStepSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     instructions: z.string().min(1),
     model: z.string().min(1).optional(),
     tools: z.array(z.string().min(1)).optional(),
@@ -317,7 +477,7 @@ const workflowStepSchema = z
 
 const workflowSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("workflow"),
     model: z.string().min(1),
     steps: z.array(workflowStepSchema).min(1),
@@ -414,7 +574,7 @@ const channelAgentSchema = z
 
 const channelSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("channel"),
     agent: channelAgentSchema,
     channels: channelsBlock,
@@ -464,11 +624,11 @@ const graphEdgeSchema = z
 
 const graphSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("graph"),
     model: z.string().min(1),
     entry: z.string().min(1),
-    nodes: z.record(z.string().min(1), graphNodeSchema),
+    nodes: z.record(safeName, graphNodeSchema),
     edges: z.array(graphEdgeSchema).default([]),
     permissions: permissionsBlock,
     compaction: compactionBlock,
@@ -505,7 +665,7 @@ const managedAgentSchema = z
 
 const managedSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("managed"),
     agent: managedAgentSchema,
     tenants: z.array(managedTenantSchema).min(1),
@@ -515,6 +675,17 @@ const managedSchema = z
   })
   .strict();
 
+// Vector-store backend ids accepted in specs. Mirrors `VectorBackendId`
+// from @crewhaus/vector-store (and `IrVectorBackend`) — the canonical set
+// of implemented backends — kept inline so the spec stays dependency-light.
+// Keep in sync when a backend is added or removed.
+const VECTOR_BACKENDS = ["in-memory", "lance", "qdrant", "pinecone", "weaviate"] as const;
+
+// The HTTP backends construct only with a `url` + `collection` (the
+// vector-store factory throws otherwise); parseSpec requires both so a
+// spec that selects one without them fails at compile, not at runtime.
+const HTTP_VECTOR_BACKENDS = new Set(["qdrant", "pinecone", "weaviate"]);
+
 // Pipeline / RAG target (Section 21). Carries the embedder + vector-store
 // config, an indexing pipeline, and a chat agent that uses Retrieve.
 const pipelineDocumentSchema = z
@@ -527,7 +698,7 @@ const pipelineDocumentSchema = z
 
 const pipelineSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("pipeline"),
     agent: z
       .object({
@@ -538,8 +709,16 @@ const pipelineSchema = z
     retrieve: z
       .object({
         embedderModel: z.string().min(1),
-        vectorBackend: z.enum(["in-memory"]).default("in-memory"),
+        vectorBackend: z.enum(VECTOR_BACKENDS).default("in-memory"),
         defaultK: z.number().int().positive().max(50).default(5),
+        // Remote (qdrant/pinecone/weaviate) + file (lance) backend config.
+        // `url` is the service base URL (or, for lance, the on-disk index
+        // path); `apiKey` accepts a `$ENV_REF` so the secret resolves from
+        // `process.env` in the bundle rather than being baked into it. The
+        // HTTP backends require `url` + `collection` (enforced in parseSpec).
+        url: z.string().min(1).optional(),
+        collection: z.string().min(1).optional(),
+        apiKey: z.string().min(1).optional(),
       })
       .strict(),
     indexing: z
@@ -588,12 +767,12 @@ const crewRoutingSchema = z
 
 const crewSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("crew"),
     /** Crew-wide model fallback used by any role that omits `role.model`. */
     model: z.string().min(1),
     entry: z.string().min(1),
-    roles: z.record(z.string().min(1), crewRoleSchema),
+    roles: z.record(safeName, crewRoleSchema),
     routing: crewRoutingSchema.optional(),
     mcp_servers: mcpServersBlock,
     permissions: permissionsBlock,
@@ -618,13 +797,13 @@ const researchRetrieveSchema = z
   .object({
     allowedOrigins: z.array(z.string().min(1)).default([]),
     allowedFileRoots: z.array(z.string().min(1)).default([]),
-    vectorBackend: z.enum(["in-memory"]).optional(),
+    vectorBackend: z.enum(VECTOR_BACKENDS).optional(),
   })
   .strict();
 
 const researchSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("research"),
     agent: z
       .object({
@@ -665,7 +844,7 @@ const batchQueueSchema = z
 
 const batchSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("batch"),
     agent: z
       .object({
@@ -708,7 +887,7 @@ const voiceTelephonySchema = z
 
 const voiceSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("voice"),
     agent: z
       .object({
@@ -744,7 +923,7 @@ const browserDriverSchema = z
 
 const browserSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("browser"),
     agent: z
       .object({
@@ -774,7 +953,7 @@ const browserSchema = z
  */
 const evalSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("eval"),
     agent: z
       .object({
@@ -785,7 +964,7 @@ const evalSchema = z
       .strict(),
     dataset: z
       .object({
-        name: z.string().min(1),
+        name: safeName,
         version: z.string().min(1),
         split: z.enum(["train", "dev", "test"]).default("dev"),
       })
@@ -794,7 +973,7 @@ const evalSchema = z
       .array(
         z
           .object({
-            name: z.string().min(1),
+            name: safeName,
             opts: z.record(z.unknown()).optional(),
           })
           .strict(),
@@ -842,7 +1021,7 @@ const onchainTriggerSchema = z.discriminatedUnion("kind", [
 
 const onchainSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("onchain"),
     agent: z
       .object({
@@ -877,7 +1056,7 @@ const onchainSchema = z
  */
 const onchainGameSchema = z
   .object({
-    name: z.string().min(1),
+    name: safeName,
     target: z.literal("onchain-game"),
     agent: z
       .object({
@@ -965,6 +1144,7 @@ export type SpecEval = z.infer<typeof evalSchema>;
 export type SpecMcpServerConfig = z.infer<typeof mcpServerConfigSchema>;
 export type SpecSubAgentDefinition = z.infer<typeof subAgentDefinitionSchema>;
 export type SpecCompactionBlock = z.infer<typeof compactionBlock>;
+export type SpecSecurityBlock = z.infer<typeof securityBlock>;
 export type SpecFailureTaxonomyEntry = z.infer<typeof failureTaxonomyEntrySchema>;
 export type SpecFailureTaxonomy = z.infer<typeof failureTaxonomyBlock>;
 
@@ -1031,5 +1211,23 @@ export function parseSpec(yamlText: string): Spec {
       }
     }
   }
+  // Section 21 — pipeline HTTP-backend invariants. qdrant/pinecone/weaviate
+  // throw at construction without a url + collection, so selecting one
+  // without both would emit an unrunnable bundle. Reject at parse time with
+  // a message naming the missing field (kept here, not as a `.refine()`, so
+  // the discriminated-union member stays a plain ZodObject).
+  if (data.target === "pipeline" && HTTP_VECTOR_BACKENDS.has(data.retrieve.vectorBackend)) {
+    const { vectorBackend, url, collection } = data.retrieve;
+    if (!url) {
+      throw new SpecParseError(
+        `pipeline retrieve.vectorBackend "${vectorBackend}" requires retrieve.url (the remote service base URL)`,
+      );
+    }
+    if (!collection) {
+      throw new SpecParseError(
+        `pipeline retrieve.vectorBackend "${vectorBackend}" requires retrieve.collection`,
+      );
+    }
+  }
   return data;
 }