@peac/cli 0.15.0 → 0.15.1

package/dist/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { Command, CommanderError, Option } from 'commander';
-import { verifyReceipt, fetchIssuerConfig, parseIssuerConfig, issue, IssueError } from '@peac/protocol';
-import { generateKeypair, base64urlEncode, sign, decode, canonicalize, sha256Hex as sha256Hex$1, validateKeypair, base64urlDecode, derivePublicKey } from '@peac/crypto';
+import { issue, verifyLocal, verifyReceipt, fetchIssuerConfig, parseIssuerConfig, IssueError } from '@peac/protocol';
+import { generateKeypair, base64urlEncode, decode, sign, jwkToPublicKeyBytes, canonicalize, sha256Hex as sha256Hex$1, validateKeypair, base64urlDecode, derivePublicKey } from '@peac/crypto';
 import * as fs6 from 'fs';
 import { writeFileSync, existsSync, readFileSync, openSync, constants, fstatSync, closeSync, statSync, unlinkSync, createReadStream } from 'fs';
 import * as path6 from 'path';
@@ -253,8 +253,8 @@ policy.command("validate").description("Validate a PEAC policy file (YAML or JSO
         );
       } else {
         console.error("Policy validation failed:\n");
-        for (const issue3 of err.issues) {
-          console.error(`   - ${issue3.path.join(".")}: ${issue3.message}`);
+        for (const issue4 of err.issues) {
+          console.error(`   - ${issue4.path.join(".")}: ${issue4.message}`);
         }
       }
       process.exit(1);
@@ -1886,95 +1886,79 @@ Use 'peac conformance list -c <category>' to see fixtures in a category.`);
 });
 var EMBEDDED_SAMPLES = [
   {
-    id: "basic-receipt",
-    name: "Basic Receipt",
-    description: "Minimal valid PEAC receipt with only required fields",
+    id: "basic-record",
+    name: "Basic Record",
+    description: "Minimal valid PEAC signed interaction record",
     category: "valid",
-    claims: {
+    format: "issue-options",
+    input: {
       iss: "https://sandbox.peacprotocol.org",
-      aud: "https://example.com",
-      iat: 0,
-      // Placeholder - will be set at generation time
-      exp: 0,
-      // Placeholder - will be set at generation time
-      rid: "sample-basic-001"
+      kind: "evidence",
+      type: "org.peacprotocol/access"
     }
   },
   {
-    id: "full-receipt",
-    name: "Full Receipt",
-    description: "PEAC receipt with all optional claims populated",
+    id: "full-record",
+    name: "Full Record",
+    description: "Valid PEAC signed interaction record with optional fields",
     category: "valid",
-    claims: {
+    format: "issue-options",
+    input: {
       iss: "https://sandbox.peacprotocol.org",
-      aud: "https://api.example.com",
-      sub: "user:demo-user",
-      iat: 0,
-      exp: 0,
-      rid: "sample-full-001",
-      purpose_declared: ["search", "index"],
-      purpose_enforced: "search",
-      purpose_reason: "allowed"
+      kind: "evidence",
+      type: "org.peacprotocol/access",
+      sub: "agent:demo-agent",
+      purpose_declared: "search"
     }
   },
   {
-    id: "interaction-evidence",
-    name: "Interaction Evidence",
-    description: "Receipt with InteractionEvidence extension for AI agent calls",
+    id: "mcp-tool-run",
+    name: "Mcp Tool Run",
+    description: "Valid PEAC signed interaction record for an MCP tool run",
     category: "valid",
-    claims: {
+    format: "issue-options",
+    input: {
       iss: "https://sandbox.peacprotocol.org",
-      aud: "https://agent.example.com",
-      sub: "agent:demo-agent-v1",
-      iat: 0,
-      exp: 0,
-      rid: "sample-ie-001",
-      ext: {
-        "org.peacprotocol/interaction@0.1": {
-          version: "0.1",
-          interaction_id: "int_sample_001",
-          started_at: "2026-01-01T00:00:00.000Z",
-          completed_at: "2026-01-01T00:00:01.000Z",
-          outcome: { kind: "success" },
-          input: { hash: "sha256:abc123...", byte_length: 1024 },
-          output: { hash: "sha256:def456...", byte_length: 2048 }
+      kind: "evidence",
+      type: "org.peacprotocol/mcp",
+      extensions: {
+        "org.peacprotocol/mcp": {
+          server: "demo",
+          tool: "search"
         }
       }
     }
   },
   {
-    id: "payment-evidence",
-    name: "Payment Evidence",
-    description: "Receipt with payment evidence (402 flow)",
+    id: "payment-event",
+    name: "Payment Event",
+    description: "Valid PEAC signed interaction record for a payment event",
     category: "valid",
-    claims: {
+    format: "issue-options",
+    input: {
       iss: "https://sandbox.peacprotocol.org",
-      aud: "https://api.example.com",
-      iat: 0,
-      exp: 0,
-      rid: "sample-payment-001",
-      amt: "100",
-      cur: "USD",
-      payment: {
-        rail: "x402",
-        reference: "pay_sample_001",
-        amount: "100",
-        currency: "USD"
+      kind: "evidence",
+      type: "org.peacprotocol/payment",
+      extensions: {
+        "org.peacprotocol/commerce": {
+          payment_rail: "stripe",
+          amount_minor: "1000",
+          currency: "USD"
+        }
       }
     }
   },
   {
-    id: "long-expiry",
-    name: "Long Expiry",
-    description: "Receipt with 24-hour expiration",
+    id: "event-time-record",
+    name: "Event Time Record",
+    description: "Valid PEAC signed interaction record with an event time. occurred_at is the interaction time; iat remains issuance time. Generation maps --now to occurred_at.",
     category: "valid",
-    claims: {
+    format: "issue-options",
+    input: {
       iss: "https://sandbox.peacprotocol.org",
-      aud: "https://example.com",
-      iat: 0,
-      exp: 0,
-      // Will be set to iat + 86400 at generation time
-      rid: "sample-long-expiry-001"
+      kind: "evidence",
+      type: "org.peacprotocol/access",
+      occurred_at: "2026-01-01T00:00:00.000Z"
     }
   },
   {
@@ -1982,6 +1966,7 @@ var EMBEDDED_SAMPLES = [
     name: "Expired Receipt",
     description: "Receipt that has already expired (for testing rejection)",
     category: "invalid",
+    format: "legacy-claims",
     claims: {
       iss: "https://sandbox.peacprotocol.org",
       aud: "https://example.com",
@@ -1998,6 +1983,7 @@ var EMBEDDED_SAMPLES = [
     name: "Future IAT",
     description: "Receipt with iat in the future (should be rejected)",
     category: "invalid",
+    format: "legacy-claims",
     claims: {
       iss: "https://sandbox.peacprotocol.org",
       aud: "https://example.com",
@@ -2014,6 +2000,7 @@ var EMBEDDED_SAMPLES = [
     name: "Missing Issuer",
     description: "Receipt missing required iss claim (for testing validation)",
     category: "invalid",
+    format: "legacy-claims",
     claims: {
       aud: "https://example.com",
       iat: 0,
@@ -2024,12 +2011,6 @@ var EMBEDDED_SAMPLES = [
   }
 ];
 function findSamplesDir(customPath) {
-  if (customPath) {
-    if (fs6.existsSync(customPath)) {
-      return customPath;
-    }
-    return null;
-  }
   const cliPath = path6.resolve(__dirname, "../../../../specs/conformance/samples");
   if (fs6.existsSync(cliPath)) {
     return cliPath;
@@ -2047,13 +2028,46 @@ function findSamplesDir(customPath) {
 function loadSampleFromFile(filePath, id, category) {
   try {
     const content = JSON.parse(fs6.readFileSync(filePath, "utf8"));
-    const claims = content.payload ?? content.claims ?? content;
     const description = content.$comment ?? content.description ?? `Sample ${id}`;
+    const name = id.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" ");
+    if (category === "valid") {
+      if (content.format !== "issue-options" || content.input === null || typeof content.input !== "object" || Array.isArray(content.input)) {
+        process.stderr.write(
+          `samples-loader: skipping malformed valid sample '${id}' (expected format "issue-options" with an input object)
+`
+        );
+        return null;
+      }
+      return {
+        id,
+        name,
+        description,
+        category: "valid",
+        format: "issue-options",
+        input: content.input
+      };
+    }
+    if (content.format !== void 0 && content.format !== "legacy-claims") {
+      process.stderr.write(
+        `samples-loader: skipping '${id}' (unexpected format "${content.format}" for ${category} sample)
+`
+      );
+      return null;
+    }
+    const claims = content.payload ?? content.claims ?? content;
+    if (claims === null || typeof claims !== "object" || Array.isArray(claims)) {
+      process.stderr.write(
+        `samples-loader: skipping malformed ${category} sample '${id}' (claims must be an object)
+`
+      );
+      return null;
+    }
     return {
       id,
-      name: id.split("-").map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join(" "),
+      name,
       description,
       category,
+      format: "legacy-claims",
       claims,
       header: content.header,
       expectedError: content.expected_error
@@ -2094,12 +2108,15 @@ function loadSamplesFromDir(samplesDir) {
   return samples2;
 }
 function getSamples(customSamplesPath) {
-  const samplesDir = findSamplesDir(customSamplesPath);
-  if (samplesDir) {
-    const dirSamples = loadSamplesFromDir(samplesDir);
-    if (dirSamples.length > 0) {
-      return dirSamples;
+  if (customSamplesPath !== void 0) {
+    if (!fs6.existsSync(customSamplesPath)) {
+      throw new Error(`Samples directory not found: ${customSamplesPath}`);
     }
+    return loadSamplesFromDir(customSamplesPath);
+  }
+  const samplesDir = findSamplesDir();
+  if (samplesDir) {
+    return loadSamplesFromDir(samplesDir);
   }
   return EMBEDDED_SAMPLES;
 }
@@ -2127,7 +2144,6 @@ function outputError3(error, details, opts) {
 function applyTimeAdjustments(claims, sampleId, now) {
   const adjusted = { ...claims };
   const standardExpiry = 3600;
-  const longExpiry = 86400;
   switch (sampleId) {
     case "expired":
       adjusted.iat = now - 7200;
@@ -2137,10 +2153,6 @@ function applyTimeAdjustments(claims, sampleId, now) {
       adjusted.iat = now + 3600;
       adjusted.exp = now + 7200;
       break;
-    case "long-expiry":
-      adjusted.iat = now;
-      adjusted.exp = now + longExpiry;
-      break;
     default:
       if (adjusted.iat === 0 || !adjusted.iat) {
         adjusted.iat = now;
@@ -2151,10 +2163,19 @@ function applyTimeAdjustments(claims, sampleId, now) {
   }
   return adjusted;
 }
-var samples = new Command("samples").description("Work with PEAC sample receipts (v0.10.8+)").option("--json", "Output in JSON format");
-samples.command("list").description("List available sample receipts").option("-c, --category <category>", "Filter by category: valid, invalid, edge").option("--samples <path>", "Path to samples directory").action((options, cmd) => {
+var samples = new Command("samples").description("Work with PEAC sample records (v0.10.8+)").option("--json", "Output in JSON format");
+samples.command("list").description("List available sample records").option("-c, --category <category>", "Filter by category: valid, invalid, edge").option("--samples <path>", "Path to samples directory").action((options, cmd) => {
   const globalOpts = getGlobalOptions3(cmd);
   try {
+    if (options.category !== void 0 && !["valid", "invalid", "edge"].includes(options.category)) {
+      outputError3(
+        "Unknown sample category",
+        { category: options.category, supported: ["valid", "invalid", "edge"] },
+        globalOpts
+      );
+      process.exitCode = 1;
+      return;
+    }
     const allSamples = getSamples(options.samples);
     let filteredSamples = allSamples;
     if (options.category) {
@@ -2174,7 +2195,7 @@ samples.command("list").description("List available sample receipts").option("-c
       }));
       console.log(JSON.stringify({ samples: data }, null, 2));
     } else {
-      console.log("Available PEAC Sample Receipts\n");
+      console.log("Available PEAC Sample Records\n");
       console.log("VALID SAMPLES:");
       for (const s of filteredSamples.filter((x) => x.category === "valid")) {
         console.log(`  ${s.id}`);
@@ -2228,11 +2249,16 @@ samples.command("show").description("Show details of a specific sample").argumen
       console.log(`Category: ${sample.category}`);
       console.log(`Description: ${sample.description}
 `);
-      console.log("Claims:");
-      console.log(JSON.stringify(sample.claims, null, 2));
-      if (sample.expectedError) {
-        console.log(`
+      if (sample.category === "valid") {
+        console.log("Issue input (current PEAC signed interaction record):");
+        console.log(JSON.stringify(sample.input, null, 2));
+      } else {
+        console.log("Claims (legacy rejection fixture):");
+        console.log(JSON.stringify(sample.claims, null, 2));
+        if (sample.expectedError) {
+          console.log(`
 Expected Error: ${sample.expectedError}`);
+        }
       }
     }
     process.exitCode = 0;
@@ -2241,10 +2267,81 @@ Expected Error: ${sample.expectedError}`);
     process.exitCode = 1;
   }
 });
-samples.command("generate").description("Generate sample receipt files").requiredOption("-o, --output <dir>", "Output directory").option("-f, --format <format>", "Output format: jws, json, bundle", "jws").option("--category <category>", "Generate only specific category").option("--samples <path>", "Path to samples directory").option("--now <timestamp>", "Unix timestamp for iat/exp (for deterministic generation)").option("--kid <kid>", "Key ID to use").action(async (options, cmd) => {
+samples.command("generate").description("Generate sample record files").requiredOption("-o, --output <dir>", "Output directory").option("-f, --format <format>", "Output format: jws, json", "jws").option("--category <category>", "Generate only specific category").option("--samples <path>", "Path to samples directory").option(
+  "--now <timestamp>",
+  "Unix event time (seconds) for valid samples; sets occurred_at (must not be in the future)"
+).option("--kid <kid>", "Key ID to use").action(async (options, cmd) => {
   const globalOpts = getGlobalOptions3(cmd);
   try {
     const outputDir = options.output;
+    const allowedFormats = /* @__PURE__ */ new Set(["jws", "json"]);
+    if (!allowedFormats.has(options.format)) {
+      outputError3(
+        "Unsupported sample format",
+        { format: options.format, supported: ["jws", "json"] },
+        globalOpts
+      );
+      process.exitCode = 1;
+      return;
+    }
+    const allowedCategories = /* @__PURE__ */ new Set(["valid", "invalid", "edge"]);
+    if (options.category !== void 0 && !allowedCategories.has(options.category)) {
+      outputError3(
+        "Unknown sample category",
+        { category: options.category, supported: ["valid", "invalid", "edge"] },
+        globalOpts
+      );
+      process.exitCode = 1;
+      return;
+    }
+    let samplesToGenerate = getSamples(options.samples);
+    if (options.category) {
+      samplesToGenerate = samplesToGenerate.filter((s) => s.category === options.category);
+    }
+    if (samplesToGenerate.length === 0) {
+      outputError3(
+        "No samples selected to generate",
+        { category: options.category ?? null },
+        globalOpts
+      );
+      process.exitCode = 1;
+      return;
+    }
+    let eventTime;
+    if (options.now !== void 0) {
+      const parsed = Number(options.now);
+      if (!Number.isInteger(parsed)) {
+        outputError3(
+          "--now must be an integer Unix timestamp (seconds)",
+          { now: options.now },
+          globalOpts
+        );
+        process.exitCode = 1;
+        return;
+      }
+      if (!Number.isFinite(new Date(parsed * 1e3).getTime())) {
+        outputError3(
+          "--now is outside the supported date range",
+          { now: options.now },
+          globalOpts
+        );
+        process.exitCode = 1;
+        return;
+      }
+      eventTime = parsed;
+    }
+    const generationNow = Math.floor(Date.now() / 1e3);
+    const SKEW_SECONDS = 300;
+    const generatesValid = samplesToGenerate.some((s) => s.category === "valid");
+    if (eventTime !== void 0 && generatesValid && eventTime > generationNow + SKEW_SECONDS) {
+      outputError3(
+        "--now sets occurred_at (event time) for valid samples and must not be in the future",
+        { now: eventTime, wall_clock: generationNow, skew_seconds: SKEW_SECONDS },
+        globalOpts
+      );
+      process.exitCode = 1;
+      return;
+    }
     const validDir = path6.join(outputDir, "valid");
     const invalidDir = path6.join(outputDir, "invalid");
     const edgeDir = path6.join(outputDir, "edge");
@@ -2253,11 +2350,10 @@ samples.command("generate").description("Generate sample receipt files").require
     fs6.mkdirSync(invalidDir, { recursive: true });
     fs6.mkdirSync(edgeDir, { recursive: true });
     fs6.mkdirSync(bundlesDir, { recursive: true });
-    const now = options.now ? parseInt(options.now, 10) : Math.floor(Date.now() / 1e3);
     const keyPair = await generateKeypair();
     const publicKeyBytes = keyPair.publicKey;
     const privateKeyBytes = keyPair.privateKey;
-    const kid = options.kid || `sandbox-${new Date(now * 1e3).toISOString().slice(0, 7)}`;
+    const kid = options.kid || `sandbox-${new Date(generationNow * 1e3).toISOString().slice(0, 7)}`;
     const publicJwk = {
       kty: "OKP",
       crv: "Ed25519",
@@ -2267,30 +2363,41 @@ samples.command("generate").description("Generate sample receipt files").require
       alg: "EdDSA"
     };
     const generatedFiles = [];
-    let samplesToGenerate = getSamples(options.samples);
-    if (options.category) {
-      samplesToGenerate = samplesToGenerate.filter((s) => s.category === options.category);
-    }
     for (const sample of samplesToGenerate) {
       const targetDir = sample.category === "valid" ? validDir : sample.category === "edge" ? edgeDir : invalidDir;
       const filename = `${sample.id}.${options.format === "json" ? "json" : "jws"}`;
       const filepath = path6.join(targetDir, filename);
-      const adjustedClaims = applyTimeAdjustments(sample.claims, sample.id, now);
-      if (options.format === "json") {
-        const output2 = {
-          $comment: sample.description,
-          header: {
-            alg: "EdDSA",
-            typ: "interaction-record+jwt",
-            kid
-          },
-          payload: adjustedClaims,
-          ...sample.expectedError ? { expected_error: sample.expectedError } : {}
+      if (sample.category === "valid") {
+        const issueOptions = {
+          ...sample.input,
+          privateKey: privateKeyBytes,
+          kid,
+          ...eventTime !== void 0 ? { occurred_at: new Date(eventTime * 1e3).toISOString() } : {}
         };
-        fs6.writeFileSync(filepath, JSON.stringify(output2, null, 2));
+        const { jws } = await issue(issueOptions);
+        if (options.format === "json") {
+          const { header, payload } = decode(jws);
+          fs6.writeFileSync(
+            filepath,
+            JSON.stringify({ $comment: sample.description, header, payload }, null, 2)
+          );
+        } else {
+          fs6.writeFileSync(filepath, jws);
+        }
       } else {
-        const jws = await sign(adjustedClaims, privateKeyBytes, kid);
-        fs6.writeFileSync(filepath, jws);
+        const adjustedClaims = applyTimeAdjustments(sample.claims, sample.id, generationNow);
+        if (options.format === "json") {
+          const output2 = {
+            $comment: sample.description,
+            header: { alg: "EdDSA", typ: "interaction-record+jwt", kid },
+            payload: adjustedClaims,
+            ...sample.expectedError ? { expected_error: sample.expectedError } : {}
+          };
+          fs6.writeFileSync(filepath, JSON.stringify(output2, null, 2));
+        } else {
+          const jws = await sign(adjustedClaims, privateKeyBytes, kid);
+          fs6.writeFileSync(filepath, jws);
+        }
       }
       generatedFiles.push(filepath);
     }
@@ -2302,9 +2409,9 @@ samples.command("generate").description("Generate sample receipt files").require
     generatedFiles.push(jwksPath);
     const bundlePath = path6.join(bundlesDir, "offline-verification.json");
     const bundle = {
-      $comment: "Offline verification bundle with sample receipts and JWKS",
-      description: "Bundle for offline verification testing. Contains test JWKS and sample metadata.",
-      generated_at: new Date(now * 1e3).toISOString(),
+      $comment: "Offline verification bundle with sample records and JWKS",
+      description: "Sample record metadata and the sandbox public verification keys.",
+      generated_at: new Date(generationNow * 1e3).toISOString(),
       generator: {
         name: "peac-cli",
         version: getVersion()
@@ -2316,8 +2423,10 @@ samples.command("generate").description("Generate sample receipt files").require
         category: s.category
       })),
       notes: [
-        "Sample timestamps are based on --now parameter or generation time.",
-        "Do NOT use sandbox samples in production."
+        "Valid samples are issued through issue() and pass local verification (verifyLocal).",
+        "Invalid samples are intentionally invalid rejection fixtures.",
+        "For valid samples, --now sets the event time (occurred_at); iat is issuance time.",
+        "Sandbox samples are for local testing and demonstration; do NOT use them in production."
       ]
     };
     fs6.writeFileSync(bundlePath, JSON.stringify(bundle, null, 2));
@@ -2330,7 +2439,8 @@ samples.command("generate").description("Generate sample receipt files").require
             output_dir: outputDir,
             files_generated: generatedFiles.length,
             files: generatedFiles,
-            timestamp: now,
+            generation_time: generationNow,
+            event_time: eventTime ?? null,
             kid
           },
           null,
@@ -2338,11 +2448,16 @@ samples.command("generate").description("Generate sample receipt files").require
         )
       );
     } else {
-      console.log(`Sample receipts generated successfully!
+      console.log(`Sample records generated successfully!
 `);
       console.log(`Output directory: ${outputDir}`);
       console.log(`Files generated: ${generatedFiles.length}`);
-      console.log(`Timestamp: ${now} (${new Date(now * 1e3).toISOString()})`);
+      console.log(
+        `Generation time: ${generationNow} (${new Date(generationNow * 1e3).toISOString()})`
+      );
+      if (eventTime !== void 0) {
+        console.log(`Event time: ${eventTime} (${new Date(eventTime * 1e3).toISOString()})`);
+      }
       console.log(`Key ID: ${kid}
 `);
       console.log("Generated files:");
@@ -4794,15 +4909,128 @@ function emitCommand() {
   emit.addCommand(emitLifecycleSubcommand());
   return emit;
 }
+function parsePublicKey(content) {
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch {
+    throw new Error("public key file is not valid JSON");
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    throw new Error("public key file must be a JWK or single-key JWKS object");
+  }
+  const obj = parsed;
+  let jwk;
+  if ("keys" in obj) {
+    const keys = obj.keys;
+    if (!Array.isArray(keys) || keys.length === 0) {
+      throw new Error("JWKS contains no keys");
+    }
+    if (keys.length > 1) {
+      throw new Error(
+        "JWKS contains multiple keys; a single-key JWKS is required (multi-key JWKS is not supported)"
+      );
+    }
+    const first = keys[0];
+    if (first === null || typeof first !== "object" || Array.isArray(first)) {
+      throw new Error("JWKS key entry is not a JWK object");
+    }
+    jwk = first;
+  } else {
+    jwk = obj;
+  }
+  if ("d" in jwk) {
+    throw new Error("public key required: the file contains private key material");
+  }
+  const { kty, crv, x } = jwk;
+  if (kty !== "OKP" || crv !== "Ed25519") {
+    throw new Error('unsupported key: expected a public Ed25519 JWK (kty "OKP", crv "Ed25519")');
+  }
+  if (typeof x !== "string" || x.length === 0) {
+    throw new Error('invalid JWK: missing public key value "x"');
+  }
+  try {
+    return jwkToPublicKeyBytes({ kty: "OKP", crv: "Ed25519", x });
+  } catch {
+    throw new Error('invalid JWK: "x" is not a 32-byte base64url Ed25519 public key');
+  }
+}
 
 // src/index.ts
+var MAX_PUBLIC_KEY_FILE_BYTES = 16384;
+var MAX_VERIFY_JWS_FILE_BYTES = 512 * 1024;
 var program = new Command();
 program.name("peac").description("PEAC protocol command-line tools").version(getVersion()).exitOverride();
-program.command("verify").description("Verify a PEAC receipt JWS").argument("<jws>", "JWS compact serialization or path to file containing JWS").option("-v, --verbose", "Show detailed output").action(async (jwsInput, options) => {
+program.command("verify").description("Verify a PEAC receipt JWS").argument("<jws>", "JWS compact serialization or path to file containing JWS").option("-v, --verbose", "Show detailed output").option(
+  "--public-key <path>",
+  "Verify offline with a public Ed25519 JWK or single-key JWKS file (no network)"
+).action(async (jwsInput, options) => {
   try {
     let jws = jwsInput;
     if (fs6.existsSync(jwsInput)) {
-      jws = fs6.readFileSync(jwsInput, "utf-8").trim();
+      try {
+        jws = readFileBufferSnapshot(jwsInput, { maxBytes: MAX_VERIFY_JWS_FILE_BYTES }).toString("utf8").trim();
+      } catch (readErr) {
+        const code = readErr.code;
+        if (code === "E_PEAC_FILE_TOO_LARGE") {
+          console.log(
+            `Verification failed: receipt file exceeds ${MAX_VERIFY_JWS_FILE_BYTES} bytes`
+          );
+        } else if (code === "EISDIR") {
+          console.log("Verification failed: receipt path is a directory");
+        } else {
+          console.log("Verification failed: could not read receipt file");
+        }
+        process.exitCode = 1;
+        return;
+      }
+    }
+    if (options.publicKey) {
+      console.log("Verifying PEAC receipt offline...\n");
+      let keyContent;
+      try {
+        keyContent = readFileBufferSnapshot(options.publicKey, {
+          maxBytes: MAX_PUBLIC_KEY_FILE_BYTES
+        }).toString("utf8");
+      } catch (readErr) {
+        const code = readErr.code;
+        if (code === "E_PEAC_FILE_TOO_LARGE") {
+          console.log(
+            `Verification failed: public key file exceeds ${MAX_PUBLIC_KEY_FILE_BYTES} bytes`
+          );
+        } else if (code === "EISDIR") {
+          console.log("Verification failed: public key path is a directory");
+        } else {
+          console.log("Verification failed: could not read public key file");
+        }
+        process.exitCode = 1;
+        return;
+      }
+      let publicKey;
+      try {
+        publicKey = parsePublicKey(keyContent);
+      } catch (keyErr) {
+        console.log(
+          `Verification failed: ${keyErr instanceof Error ? keyErr.message : "invalid public key"}`
+        );
+        process.exitCode = 1;
+        return;
+      }
+      const localResult = await verifyLocal(jws, publicKey);
+      if (localResult.valid) {
+        console.log("Signature valid (offline).");
+        console.log(
+          "   Verified the receipt signature and declared receipt structure against the supplied public key."
+        );
+        process.exitCode = 0;
+      } else {
+        console.log(`Verification failed: ${localResult.message}`);
+        if (localResult.code) {
+          console.log(`   Code: ${localResult.code}`);
+        }
+        process.exitCode = 1;
+      }
+      return;
     }
     console.log("Verifying PEAC receipt...\n");
     const { payload } = decode(jws);