@vauban-org/agent-sdk 1.0.0 → 1.2.0

package/src/skill-manifest/verifier.ts

@@ -0,0 +1,198 @@
+/**
+ * Skill Lineage Manifest — verifier (sprint-586).
+ *
+ * Zero external dependency verifier — mirrors vauban-claim-verifier philosophy.
+ *
+ * Verification checks:
+ *   1. replayRootMatches  — SHA-256(replaySnapshot) === manifest.trainingReplayRoot
+ *   2. poseidonHashValid  — computeManifestHash(manifest) === manifest.poseidonHash
+ *   3. tsaAnchorValid     — verifyTsaAnchor(manifest) (skipped if no tsaToken)
+ *   4. starknetAnchorValid — merkle inclusion via AnchorWitness (if provided)
+ *
+ * A 1-byte tamper in replaySnapshot causes check 1 to fail.
+ * All checks run independently; errors array collects all failures.
+ *
+ * @module skill-manifest/verifier
+ */
+
+import { createHash } from "node:crypto";
+import { computeManifestHash } from "./builder.js";
+import { verifyTsaAnchor } from "./anchor.js";
+import { verifyProofInclusion } from "../proof/index.js";
+import type { SkillManifest, AnchorWitness } from "./types.js";
+
+// ─── ManifestVerifyResult ────────────────────────────────────────────────────
+
+export interface ManifestVerifyResult {
+  /** Overall validity — true only if all applicable checks pass. */
+  valid: boolean;
+  /** SHA-256(replaySnapshot) === manifest.trainingReplayRoot */
+  replayRootMatches: boolean;
+  /** Poseidon commitment over manifest fields matches stored poseidonHash */
+  poseidonHashValid: boolean;
+  /** RFC 3161 TSA token structurally verifiable (false if no tsaToken) */
+  tsaAnchorValid: boolean;
+  /** Merkle inclusion proof valid (false if no witness or witness.type='none') */
+  starknetAnchorValid: boolean;
+  /** Grade propagated from the manifest (informational). */
+  grade: SkillManifest["grade"];
+  /** Human-readable error messages for every failed check. */
+  errors: string[];
+}
+
+// ─── helpers ─────────────────────────────────────────────────────────────────
+
+function sha256Hex(input: string | Buffer): string {
+  const data = typeof input === "string" ? Buffer.from(input, "utf8") : input;
+  return createHash("sha256").update(data).digest("hex");
+}
+
+/**
+ * Normalise hex strings for comparison: strip "0x" prefix, lowercase.
+ */
+function normaliseHex(h: string): string {
+  return (h.startsWith("0x") ? h.slice(2) : h).toLowerCase();
+}
+
+// ─── verifyManifest ───────────────────────────────────────────────────────────
+
+/**
+ * Verify a SkillManifest against the original training replay snapshot.
+ *
+ * @param manifest         - Manifest to verify.
+ * @param replaySnapshot   - Original training trace bytes (same input used in buildManifest).
+ * @param starknetWitness  - Optional Merkle inclusion witness from the Starknet anchor.
+ */
+export function verifyManifest(
+  manifest: SkillManifest,
+  replaySnapshot: string | Buffer,
+  starknetWitness?: AnchorWitness
+): ManifestVerifyResult {
+  const errors: string[] = [];
+
+  // ── Check 1: replay root integrity ──────────────────────────────────────────
+  const recomputedRoot = sha256Hex(
+    typeof replaySnapshot === "string"
+      ? Buffer.from(replaySnapshot, "utf8")
+      : replaySnapshot
+  );
+  const replayRootMatches =
+    normaliseHex(recomputedRoot) === normaliseHex(manifest.trainingReplayRoot);
+  if (!replayRootMatches) {
+    errors.push(
+      `replayRoot mismatch: expected ${manifest.trainingReplayRoot}, got ${recomputedRoot}`
+    );
+  }
+
+  // ── Check 2: Poseidon hash validity ──────────────────────────────────────────
+  let poseidonHashValid = false;
+  try {
+    const recomputed = computeManifestHash({
+      skillId: manifest.skillId,
+      version: manifest.version,
+      domain: manifest.domain,
+      trainingReplayRoot: manifest.trainingReplayRoot,
+    });
+    poseidonHashValid =
+      normaliseHex(recomputed) === normaliseHex(manifest.poseidonHash);
+    if (!poseidonHashValid) {
+      errors.push(
+        `poseidonHash mismatch: expected ${manifest.poseidonHash}, got ${recomputed}`
+      );
+    }
+  } catch (err) {
+    errors.push(
+      `poseidonHash computation failed: ${
+        err instanceof Error ? err.message : String(err)
+      }`
+    );
+  }
+
+  // ── Check 3: TSA anchor ───────────────────────────────────────────────────────
+  const tsaAnchorValid = manifest.tsaToken ? verifyTsaAnchor(manifest) : false;
+  if (manifest.tsaToken && !tsaAnchorValid) {
+    errors.push("tsaAnchor invalid: token present but verification failed");
+  }
+
+  // ── Check 4: Starknet Merkle inclusion ──────────────────────────────────────
+  let starknetAnchorValid = false;
+  if (starknetWitness && starknetWitness.type === "starknet") {
+    try {
+      // proof field: comma-separated Merkle siblings (hex)
+      const siblings =
+        starknetWitness.proof.length > 0
+          ? starknetWitness.proof.split(",").map((s) => s.trim())
+          : [];
+
+      const leafFelt = manifest.poseidonHash.startsWith("0x")
+        ? manifest.poseidonHash.slice(2)
+        : manifest.poseidonHash;
+
+      // We need a root to verify against; derive it from the first sibling
+      // if the proof is a single-leaf tree (leaf === root).
+      if (siblings.length === 0) {
+        // Degenerate tree: leaf is the root — valid if leaf is consistent.
+        starknetAnchorValid = leafFelt.length > 0;
+      } else {
+        // verifyProofInclusion: leaf + proof[] → recomputed root must match
+        // the last sibling used as root sentinel in single-layer proofs.
+        // For multi-layer proofs the root must be provided externally.
+        // We use the witness.proof first element as root when siblings.length === 1.
+        const root = siblings[siblings.length - 1];
+        const proofSiblings = siblings.slice(0, -1);
+        starknetAnchorValid = verifyProofInclusion(
+          leafFelt,
+          proofSiblings,
+          root
+        );
+      }
+
+      if (!starknetAnchorValid) {
+        errors.push("starknetAnchor: Merkle inclusion proof failed");
+      }
+    } catch (err) {
+      errors.push(
+        `starknetAnchor verification error: ${
+          err instanceof Error ? err.message : String(err)
+        }`
+      );
+    }
+  } else if (starknetWitness && starknetWitness.type === "tsa") {
+    // TSA witness — treat as tsaAnchorValid supplement (already checked above).
+    starknetAnchorValid = false;
+  }
+  // type === 'none' or no witness → starknetAnchorValid remains false (expected).
+
+  // ── Grade propagation ─────────────────────────────────────────────────────────
+  const grade = manifest.grade;
+
+  // Warn about unanchored grade in errors (non-fatal, but caller should know).
+  if (grade === "unanchored") {
+    errors.push(
+      "grade=unanchored: manifest has no anchor — development/testing only"
+    );
+  }
+
+  // ── Overall validity ──────────────────────────────────────────────────────────
+  // An anchored manifest is valid when the integrity checks pass.
+  // For unanchored: valid = replayRootMatches && poseidonHashValid only.
+  const anchorErrors = errors.filter(
+    (e) =>
+      e.startsWith("tsa") ||
+      e.startsWith("starknet") ||
+      e.startsWith("grade=unanchored")
+  );
+  const integrityErrors = errors.filter((e) => !anchorErrors.includes(e));
+
+  const valid = integrityErrors.length === 0;
+
+  return {
+    valid,
+    replayRootMatches,
+    poseidonHashValid,
+    tsaAnchorValid,
+    starknetAnchorValid,
+    grade,
+    errors,
+  };
+}

package/src/skills/errors.ts

@@ -13,7 +13,9 @@ export class SkillNotConfiguredError extends Error {
   readonly missingEnv: readonly string[];
   constructor(skillName: string, missingEnv: readonly string[]) {
     super(
-      `Skill '${skillName}' not configured: missing env ${missingEnv.join(", ")}`,
+      `Skill '${skillName}' not configured: missing env ${missingEnv.join(
+        ", "
+      )}`
     );
     this.name = "SkillNotConfiguredError";
     this.skillName = skillName;
@@ -28,7 +30,7 @@ export class SkillExecutionError extends Error {
   constructor(
     skillName: string,
     message: string,
-    opts?: { status?: number; cause?: unknown },
+    opts?: { status?: number; cause?: unknown }
   ) {
     super(`Skill '${skillName}' failed: ${message}`);
     this.name = "SkillExecutionError";
@@ -57,3 +59,29 @@ export class HttpFetchAllowlistError extends Error {
     this.host = host;
   }
 }
+
+export class SkillMdParseError extends Error {
+  readonly filePath: string;
+  constructor(filePath: string, reason: string) {
+    super(`SKILL.md at ${filePath}: ${reason}`);
+    this.name = "SkillMdParseError";
+    this.filePath = filePath;
+  }
+}
+
+export class SkillMdValidationError extends Error {
+  readonly filePath: string;
+  readonly issues: ReadonlyArray<{ path: string; message: string }>;
+  constructor(
+    filePath: string,
+    issues: ReadonlyArray<{ path: string; message: string }>
+  ) {
+    const summary = issues
+      .map((i) => `${i.path || "(root)"}: ${i.message}`)
+      .join("; ");
+    super(`SKILL.md at ${filePath}: invalid frontmatter — ${summary}`);
+    this.name = "SkillMdValidationError";
+    this.filePath = filePath;
+    this.issues = issues;
+  }
+}

package/src/skills/index.ts

@@ -18,8 +18,27 @@ export {
   SkillExecutionError,
   SqlReadOnlyViolation,
   HttpFetchAllowlistError,
+  SkillMdParseError,
+  SkillMdValidationError,
 } from "./errors.js";
 
+// SKILL.md loader (agentskills.io standard) — ADR-ECO-034
+export {
+  loadSkillMd,
+  parseSkillMd,
+  toDiscoveryEntry,
+  type ParsedSkillFile,
+} from "./markdown/loader.js";
+export {
+  SkillManifestSchema,
+  resolveTier,
+  parseAllowedTools,
+  type SkillManifest,
+  type VaubanSkillTier,
+  type VaubanBiscuitScope,
+  type VaubanAuditStatus,
+} from "./markdown/schema.js";
+
 export { webSearch } from "./web-search.js";
 export type { WebSearchOutput, WebSearchResult } from "./web-search.js";
 

package/src/skills/markdown/loader.ts

@@ -0,0 +1,129 @@
+/**
+ * SKILL.md loader — agentskills.io standard parser.
+ *
+ * Reads a SKILL.md file, splits frontmatter from body, parses YAML via the
+ * `yaml` package (battle-tested), validates against `SkillManifestSchema`,
+ * and returns a typed `ParsedSkillFile`.
+ *
+ * Constraints:
+ *   - No new npm deps (uses `yaml` already in package.json).
+ *   - Frontmatter delimiters: `---\n` ... `\n---\n`.
+ *   - Body returned verbatim (markdown — no rendering).
+ *   - Validation errors are typed (SkillMdParseError / SkillMdValidationError).
+ *
+ * Progressive disclosure tiers (per agentskills.io spec):
+ *   - Discovery   (~100 tok) — name + description only
+ *   - Pre-activate (~500 tok) — full frontmatter + body excerpt
+ *   - Activate    — full body (≤8000 tok recommended)
+ *
+ * Spec reference: https://agentskills.io/specification
+ * @see ADR-ECO-034 — skills TS↔MD coexistence
+ * @public
+ */
+
+import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
+import { SkillMdParseError, SkillMdValidationError } from "../errors.js";
+import {
+  type SkillManifest,
+  SkillManifestSchema,
+  type VaubanSkillTier,
+  resolveTier,
+} from "./schema.js";
+
+// `---` at line start, then arbitrary content, then `---` at line start. Body follows.
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+
+export interface ParsedSkillFile {
+  manifest: SkillManifest;
+  body: string;
+  tier: VaubanSkillTier;
+  /** Tokens (rough heuristic ~4 chars/token) for progressive disclosure. */
+  bodyTokens: number;
+}
+
+/**
+ * Load and parse a SKILL.md file from disk.
+ *
+ * @throws SkillMdParseError    when frontmatter delimiters are missing or YAML is invalid
+ * @throws SkillMdValidationError when frontmatter fails Zod schema validation
+ */
+export async function loadSkillMd(filePath: string): Promise<ParsedSkillFile> {
+  const raw = await readFile(filePath, "utf-8");
+  return parseSkillMd(raw, filePath);
+}
+
+/**
+ * Parse SKILL.md content from a string (in-memory). Useful for tests and
+ * embedded skills.
+ */
+export function parseSkillMd(
+  raw: string,
+  source = "<inline>"
+): ParsedSkillFile {
+  const match = raw.match(FRONTMATTER_RE);
+  if (!match) {
+    throw new SkillMdParseError(
+      source,
+      "missing or malformed frontmatter (expected '---' delimiters on first line)"
+    );
+  }
+  const [, frontmatterText, body] = match;
+
+  let parsed: unknown;
+  try {
+    parsed = parseYaml(frontmatterText);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new SkillMdParseError(source, `YAML parse error — ${message}`);
+  }
+
+  if (parsed == null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new SkillMdParseError(
+      source,
+      "frontmatter must be a YAML object (got " +
+        (parsed === null
+          ? "null"
+          : Array.isArray(parsed)
+          ? "array"
+          : typeof parsed) +
+        ")"
+    );
+  }
+
+  const result = SkillManifestSchema.safeParse(parsed);
+  if (!result.success) {
+    throw new SkillMdValidationError(
+      source,
+      result.error.issues.map((i) => ({
+        path: i.path.join("."),
+        message: i.message,
+      }))
+    );
+  }
+
+  const manifest = result.data;
+  const trimmedBody = body.trim();
+  return {
+    manifest,
+    body: trimmedBody,
+    tier: resolveTier(manifest),
+    bodyTokens: Math.ceil(trimmedBody.length / 4),
+  };
+}
+
+/**
+ * Produce the "discovery" projection (~100 tokens): name + description only.
+ * Used by the catalogue / progressive disclosure layer to keep startup cost low.
+ */
+export function toDiscoveryEntry(parsed: ParsedSkillFile): {
+  name: string;
+  description: string;
+  tier: VaubanSkillTier;
+} {
+  return {
+    name: parsed.manifest.name,
+    description: parsed.manifest.description,
+    tier: parsed.tier,
+  };
+}

package/src/skills/markdown/schema.ts

@@ -0,0 +1,144 @@
+/**
+ * SKILL.md frontmatter schema — agentskills.io standard + Vauban extensions.
+ *
+ * Standard fields (agentskills.io spec):
+ *   - `name`         1-64 chars, kebab-case
+ *   - `description`  1-1024 chars
+ *   - `license`      free-text (optional)
+ *   - `compatibility` free-text (optional, e.g. "Requires STARKNET_RPC_URL")
+ *   - `allowed-tools` space-separated string, e.g. "Bash(curl:*) Bash(jq:*) Read"
+ *   - `metadata`     arbitrary k/v map (per spec — extension surface)
+ *
+ * Vauban extensions live UNDER `metadata` (spec-compliant — ignored gracefully
+ * by other agentskills.io-conforming tools). Namespaced as `vauban.*` keys
+ * for clarity:
+ *   - `metadata.vauban.tier`           "official" | "verified" | "unverified"
+ *   - `metadata.vauban.subagent`       agent id this skill belongs to
+ *   - `metadata.vauban.model-hint`     suggested LLM (forwarded to EconomyRouter)
+ *   - `metadata.vauban.proof.poseidon_hash`  hex
+ *   - `metadata.vauban.proof.tsa_token`      base64 RFC3161
+ *   - `metadata.vauban.proof.starknet_tx`    hex
+ *   - `metadata.vauban.biscuit.required_caps` array of capability strings
+ *   - `metadata.vauban.biscuit.max_scope`     "project" | "session" | "global"
+ *   - `metadata.vauban.audit_status`   "approved" | "review" | "rejected"
+ *
+ * Spec reference: https://agentskills.io/specification
+ * @see ADR-ECO-034 — skills TS↔MD coexistence
+ * @public
+ */
+
+import { z } from "zod";
+
+// ── Vauban metadata extension schemas ────────────────────────────────────────
+
+export const VaubanSkillTier = z.enum(["official", "verified", "unverified"]);
+export type VaubanSkillTier = z.infer<typeof VaubanSkillTier>;
+
+export const VaubanBiscuitScope = z.enum(["project", "session", "global"]);
+export type VaubanBiscuitScope = z.infer<typeof VaubanBiscuitScope>;
+
+export const VaubanAuditStatus = z.enum(["approved", "review", "rejected"]);
+export type VaubanAuditStatus = z.infer<typeof VaubanAuditStatus>;
+
+const VaubanProofExtensionSchema = z
+  .object({
+    poseidon_hash: z
+      .string()
+      .regex(/^0x[0-9a-fA-F]+$/)
+      .optional(),
+    tsa_token: z.string().optional(),
+    starknet_tx: z
+      .string()
+      .regex(/^0x[0-9a-fA-F]+$/)
+      .optional(),
+    anchored_at: z.string().datetime().optional(),
+  })
+  .strict()
+  .partial();
+
+const VaubanBiscuitExtensionSchema = z
+  .object({
+    required_caps: z.array(z.string()).optional(),
+    max_scope: VaubanBiscuitScope.optional(),
+  })
+  .strict()
+  .partial();
+
+const VaubanExtensionSchema = z
+  .object({
+    tier: VaubanSkillTier.optional(),
+    subagent: z.string().optional(),
+    "model-hint": z.string().optional(),
+    proof: VaubanProofExtensionSchema.optional(),
+    biscuit: VaubanBiscuitExtensionSchema.optional(),
+    audit_status: VaubanAuditStatus.optional(),
+    observability_metric: z.string().optional(),
+  })
+  .strict()
+  .partial();
+
+// ── Generic metadata (per agentskills.io: arbitrary k/v) ─────────────────────
+
+const StandardMetadataKnownKeys = z
+  .object({
+    version: z.string().optional(),
+    category: z.string().optional(),
+    tags: z.union([z.string(), z.array(z.string())]).optional(),
+    author: z.string().optional(),
+    "env-required": z.string().optional(),
+    "env-mode": z.enum(["all", "at-least-one"]).optional(),
+    vauban: VaubanExtensionSchema.optional(),
+  })
+  .partial();
+
+const MetadataSchema = StandardMetadataKnownKeys.passthrough();
+
+// ── Top-level SKILL.md frontmatter schema ────────────────────────────────────
+
+const KEBAB_CASE = /^[a-z0-9][a-z0-9-]*$/;
+
+export const SkillManifestSchema = z
+  .object({
+    name: z
+      .string()
+      .min(1, "name must be 1-64 chars")
+      .max(64, "name must be 1-64 chars")
+      .regex(
+        KEBAB_CASE,
+        "name must be kebab-case (lowercase, digits, hyphens)"
+      ),
+    description: z
+      .string()
+      .min(1, "description must be 1-1024 chars")
+      .max(1024, "description must be 1-1024 chars"),
+    license: z.string().optional(),
+    compatibility: z.string().optional(),
+    "allowed-tools": z.string().optional(),
+    metadata: MetadataSchema.optional(),
+  })
+  .strict();
+
+export type SkillManifest = z.infer<typeof SkillManifestSchema>;
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+/**
+ * Resolve the Vauban tier from a manifest, defaulting to `unverified` per
+ * the trust-stratification rule: any skill without an explicit tier MUST be
+ * sandboxed as community-untrusted.
+ */
+export function resolveTier(manifest: SkillManifest): VaubanSkillTier {
+  return manifest.metadata?.vauban?.tier ?? "unverified";
+}
+
+/**
+ * Parse the space-separated `allowed-tools` string into an array. Empty string
+ * returns []. Whitespace runs collapse. Examples:
+ *   "Bash(curl:*) Read"      → ["Bash(curl:*)", "Read"]
+ *   "Bash(curl:*)  Bash(jq)" → ["Bash(curl:*)", "Bash(jq)"]
+ */
+export function parseAllowedTools(manifest: SkillManifest): string[] {
+  const raw = manifest["allowed-tools"];
+  if (!raw) return [];
+  return raw.split(/\s+/).filter((s) => s.length > 0);
+}