@crovia/seal 0.1.0

package/src/types.ts

@@ -0,0 +1,95 @@
+/**
+ * Core types for @crovia/seal.
+ */
+
+/** A signed continuity receipt over an arbitrary JSON payload. */
+export interface Receipt {
+  /** Format identifier. Always "crovia.receipt.v1" for this version. */
+  v: "crovia.receipt.v1";
+  /** Receipt identifier: "cr_YYYY_<26 base32 chars>". */
+  id: string;
+  /** RFC 3339 UTC timestamp with millisecond precision. */
+  issued_at: string;
+  /** "sha256:<64 lowercase hex>" of the canonical UTF-8 bytes of payload. */
+  payload_hash: string;
+  /** Hash algorithm used for payload_hash. Currently always "sha256". */
+  payload_alg: "sha256";
+  /** Optional content-type hint for the payload (free-form, not signed semantics). */
+  payload_type?: string;
+  /** Previous receipt id from the same signer, or null for genesis. */
+  prev: string | null;
+  /** Monotonic sequence per signer, 0 for genesis. */
+  seq: number;
+  /** Signer's Ed25519 public key as 64 lowercase hex chars. */
+  signer: string;
+  /** Signature algorithm: always "ed25519". */
+  sig_alg: "ed25519";
+  /** Canonicalization scheme: always "csc-1". */
+  canon: "csc-1";
+  /** Domain separator string baked into the signed payload. */
+  domain: "CROVIA-RECEIPT-v1";
+  /** Detached signature over compute_payload(receipt) — 128 lowercase hex. */
+  sig: string;
+}
+
+/** Options for `seal()`. */
+export interface SealOptions {
+  /** Bring-your-own Ed25519 key. If omitted, a fresh key is generated for this call. */
+  key?: KeyPair;
+  /** Previous receipt to chain against (provides prev + seq). */
+  prevReceipt?: Receipt;
+  /** Optional content-type hint (e.g., "text/plain", "application/json", "model-card"). */
+  payloadType?: string;
+  /** Override timestamp (testing only — must be RFC 3339 with ms precision). */
+  issuedAt?: string;
+}
+
+/** Ed25519 key pair, raw 32-byte private + 32-byte public. */
+export interface KeyPair {
+  /** 64 lowercase hex chars (32 bytes). */
+  privateHex: string;
+  /** 64 lowercase hex chars (32 bytes). */
+  publicHex: string;
+}
+
+/** Outcome of `verify()`. */
+export interface VerifyResult {
+  /** True iff structure, signature, and self-consistency all check out. */
+  valid: boolean;
+  /** Errors encountered (empty when valid=true). */
+  errors: string[];
+  /** Receipt id (echoed for convenience). */
+  id?: string;
+  /** Signer pubkey hex. */
+  signer?: string;
+  /** payload_hash echoed for the caller to compare against their payload. */
+  payloadHash?: string;
+  /** prev id, for chain walks. */
+  prev?: string | null;
+  /** sequence, for chain walks. */
+  seq?: number;
+  /** issued_at echoed for time-range checks. */
+  issuedAt?: string;
+}
+
+/** Options for `register()`. */
+export interface RegisterOptions {
+  /** Substrate URL. Defaults to https://croviatrust.com */
+  endpoint?: string;
+  /** Optional fetch override (for testing or custom transports). */
+  fetch?: typeof globalThis.fetch;
+  /** Request timeout in ms. Defaults to 10_000. */
+  timeoutMs?: number;
+}
+
+/** Outcome of `register()`. */
+export interface RegisterResult {
+  /** Whether the substrate accepted the receipt. */
+  accepted: boolean;
+  /** Substrate-assigned anchor id, if any. */
+  anchorId?: string;
+  /** HTTP status code returned by the substrate. */
+  status: number;
+  /** Error message if not accepted. */
+  error?: string;
+}

package/src/verify.ts

@@ -0,0 +1,166 @@
+/**
+ * `verify()` — check the structure and signature of a receipt.
+ *
+ * If you also have the original payload, pass it as the second argument
+ * to additionally verify the payload_hash. Without the payload, only
+ * the signature and structure are checked.
+ */
+import { sha256 } from "@noble/hashes/sha256";
+
+import { canonicalize } from "./canonical.js";
+import { bytesToHex, verifyBytes } from "./keys.js";
+import {
+  computePayload,
+  validateReceiptShape,
+} from "./seal.js";
+import type { Receipt, VerifyResult } from "./types.js";
+
+function sha256Prefixed(data: Uint8Array): string {
+  return "sha256:" + bytesToHex(sha256(data));
+}
+
+/**
+ * Verify a continuity receipt.
+ *
+ * @param receipt The receipt object (or any value to be type-checked).
+ * @param payload Optional original payload to verify payload_hash against.
+ *                If omitted, only the signature and structure are checked.
+ * @returns A VerifyResult — never throws.
+ */
+export async function verify(
+  receipt: unknown,
+  payload?: unknown,
+): Promise<VerifyResult> {
+  const errors: string[] = [];
+
+  // Step 1: structural validation.
+  const shapeErr = validateReceiptShape(receipt);
+  if (shapeErr !== null) {
+    errors.push(`schema: ${shapeErr}`);
+    return { valid: false, errors };
+  }
+
+  const r = receipt as Receipt;
+
+  // Step 2: signature.
+  const { sig, ...withoutSig } = r;
+  const signingPayload = computePayload(withoutSig);
+
+  let sigOk = false;
+  try {
+    sigOk = await verifyBytes(r.signer, sig, signingPayload);
+  } catch (e) {
+    errors.push(
+      `signature-verify: ${e instanceof Error ? e.message : String(e)}`,
+    );
+    return { valid: false, errors };
+  }
+
+  if (!sigOk) {
+    errors.push("signature: invalid");
+    return {
+      valid: false,
+      errors,
+      id: r.id,
+      signer: r.signer,
+      payloadHash: r.payload_hash,
+      prev: r.prev,
+      seq: r.seq,
+      issuedAt: r.issued_at,
+    };
+  }
+
+  // Step 3: payload-hash check (only if caller provided the payload).
+  if (payload !== undefined) {
+    let computed: string;
+    try {
+      computed = sha256Prefixed(canonicalize(payload));
+    } catch (e) {
+      errors.push(
+        `payload-canonicalize: ${e instanceof Error ? e.message : String(e)}`,
+      );
+      return { valid: false, errors };
+    }
+    if (computed !== r.payload_hash) {
+      errors.push(
+        `payload_hash mismatch: receipt=${r.payload_hash} computed=${computed}`,
+      );
+      return {
+        valid: false,
+        errors,
+        id: r.id,
+        signer: r.signer,
+        payloadHash: r.payload_hash,
+        prev: r.prev,
+        seq: r.seq,
+        issuedAt: r.issued_at,
+      };
+    }
+  }
+
+  return {
+    valid: true,
+    errors: [],
+    id: r.id,
+    signer: r.signer,
+    payloadHash: r.payload_hash,
+    prev: r.prev,
+    seq: r.seq,
+    issuedAt: r.issued_at,
+  };
+}
+
+/**
+ * Verify a chain of receipts in order: each receipt[i].prev must equal
+ * receipt[i-1].id, sequence must increment by 1, and signer must remain
+ * the same. All signatures must verify.
+ *
+ * @returns true iff the chain is internally consistent and all sigs valid.
+ */
+export async function verifyChain(receipts: Receipt[]): Promise<VerifyResult> {
+  if (receipts.length === 0) {
+    return { valid: false, errors: ["empty chain"] };
+  }
+  let prevId: string | null = null;
+  let prevSeq = -1;
+  let signer: string | null = null;
+  for (let i = 0; i < receipts.length; i++) {
+    const r = receipts[i]!;
+    const single = await verify(r);
+    if (!single.valid) {
+      return {
+        valid: false,
+        errors: [`chain[${i}] invalid: ${single.errors.join("; ")}`],
+      };
+    }
+    if (signer === null) signer = r.signer;
+    else if (signer !== r.signer) {
+      return {
+        valid: false,
+        errors: [`chain[${i}] signer changed from ${signer} to ${r.signer}`],
+      };
+    }
+    if (r.seq !== prevSeq + 1) {
+      return {
+        valid: false,
+        errors: [
+          `chain[${i}] seq=${r.seq} but expected ${prevSeq + 1}`,
+        ],
+      };
+    }
+    if (r.prev !== prevId) {
+      return {
+        valid: false,
+        errors: [`chain[${i}] prev=${r.prev} but expected ${prevId}`],
+      };
+    }
+    prevId = r.id;
+    prevSeq = r.seq;
+  }
+  return {
+    valid: true,
+    errors: [],
+    id: receipts[receipts.length - 1]!.id,
+    signer: signer!,
+  };
+}