@crovia/seal 0.1.0

package/src/canonical.ts

@@ -0,0 +1,171 @@
+/**
+ * CSC-1 — Crovia Seal Canonicalization v1.
+ *
+ * Strict subset of RFC 8785 (JCS):
+ *   - Object keys sorted by UTF-16 code-unit order
+ *   - String escapes per RFC 8259 (mandatory short escapes only)
+ *   - Integers only (floats forbidden in signed payloads)
+ *   - No insignificant whitespace
+ *
+ * This implementation MUST produce byte-identical output to the Python
+ * reference (`reference/python/crovia_seal/canonical.py`) for every shared
+ * conformance vector. Any divergence is a bug.
+ */
+
+// JS-safe integer range — same as Python reference.
+const JS_SAFE_INT_MIN = -(2 ** 53 - 1);
+const JS_SAFE_INT_MAX = 2 ** 53 - 1;
+
+const ESCAPE_MAP: Record<number, string> = {
+  0x22: '\\"',   // "
+  0x5c: "\\\\",  // \
+  0x08: "\\b",
+  0x0c: "\\f",
+  0x0a: "\\n",
+  0x0d: "\\r",
+  0x09: "\\t",
+};
+
+export class CanonicalizationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CanonicalizationError";
+  }
+}
+
+function serializeString(s: string): string {
+  let out = '"';
+  for (let i = 0; i < s.length; i++) {
+    const cp = s.charCodeAt(i);
+    if (cp < 0x20) {
+      const esc = ESCAPE_MAP[cp];
+      if (esc !== undefined) {
+        out += esc;
+      } else {
+        out += "\\u" + cp.toString(16).padStart(4, "0");
+      }
+    } else if (cp === 0x22 || cp === 0x5c) {
+      out += ESCAPE_MAP[cp];
+    } else {
+      out += s[i];
+    }
+  }
+  out += '"';
+  return out;
+}
+
+function serializeNumber(n: number): string {
+  if (typeof n !== "number" || !Number.isFinite(n)) {
+    throw new CanonicalizationError(
+      `CSC-1 forbids non-finite numbers; got ${n}`,
+    );
+  }
+  if (!Number.isInteger(n)) {
+    throw new CanonicalizationError(
+      "CSC-1 forbids float in signed payloads; " +
+        'encode numeric parameters as strings (e.g. temperature="0.7")',
+    );
+  }
+  if (n < JS_SAFE_INT_MIN || n > JS_SAFE_INT_MAX) {
+    throw new CanonicalizationError(
+      `integer ${n} outside JS-safe range [${JS_SAFE_INT_MIN}, ${JS_SAFE_INT_MAX}]; ` +
+        "encode large integers as strings",
+    );
+  }
+  // Number.prototype.toString() on integers produces the shortest decimal,
+  // no leading zeros, leading "-" for negatives, "0" for zero. Matches
+  // Python's str(int) byte-for-byte.
+  return String(n);
+}
+
+function serializeArray(arr: unknown[]): string {
+  const parts = arr.map((v) => serialize(v));
+  return "[" + parts.join(",") + "]";
+}
+
+function utf16Compare(a: string, b: string): number {
+  // RFC 8785 §3.2.3: keys sorted by UTF-16 code-unit value.
+  // JavaScript strings ARE UTF-16, so direct < / > comparison works
+  // for BMP keys. For supplementary-plane keys the surrogate halves
+  // already sort correctly because we compare code units, not code points.
+  const len = Math.min(a.length, b.length);
+  for (let i = 0; i < len; i++) {
+    const ac = a.charCodeAt(i);
+    const bc = b.charCodeAt(i);
+    if (ac !== bc) return ac - bc;
+  }
+  return a.length - b.length;
+}
+
+function serializeObject(obj: Record<string, unknown>): string {
+  // Reject non-string keys via JS prototype. Object keys in JS are always
+  // strings (Symbol keys are skipped by Object.keys), so this is ok by
+  // construction. But we still defend against malformed input shapes.
+  const keys = Object.keys(obj);
+  for (const k of keys) {
+    if (typeof k !== "string") {
+      throw new CanonicalizationError(
+        `object key must be string, got ${typeof k}`,
+      );
+    }
+  }
+
+  // Detect duplicates (impossible from a literal object, but possible
+  // from manually-constructed values).
+  const seen = new Set<string>();
+  for (const k of keys) {
+    if (seen.has(k)) {
+      throw new CanonicalizationError(`duplicate object key: ${k}`);
+    }
+    seen.add(k);
+  }
+
+  const sorted = [...keys].sort(utf16Compare);
+  const parts = sorted.map(
+    (k) => serializeString(k) + ":" + serialize(obj[k]),
+  );
+  return "{" + parts.join(",") + "}";
+}
+
+function serialize(value: unknown): string {
+  if (value === null) return "null";
+  if (value === true) return "true";
+  if (value === false) return "false";
+  if (typeof value === "string") return serializeString(value);
+  if (typeof value === "number") return serializeNumber(value);
+  if (typeof value === "bigint") {
+    if (value < BigInt(JS_SAFE_INT_MIN) || value > BigInt(JS_SAFE_INT_MAX)) {
+      throw new CanonicalizationError(
+        `bigint ${value} outside JS-safe range; encode as string`,
+      );
+    }
+    return value.toString();
+  }
+  if (Array.isArray(value)) return serializeArray(value);
+  if (typeof value === "object") {
+    return serializeObject(value as Record<string, unknown>);
+  }
+  if (value === undefined) {
+    throw new CanonicalizationError("CSC-1 cannot serialize undefined");
+  }
+  throw new CanonicalizationError(
+    `CSC-1 cannot serialize value of type ${typeof value}`,
+  );
+}
+
+/**
+ * Canonicalize a JSON-compatible value to its UTF-8 byte representation.
+ * Output is byte-identical to the Python reference implementation.
+ */
+export function canonicalize(value: unknown): Uint8Array {
+  const str = serialize(value);
+  return new TextEncoder().encode(str);
+}
+
+/**
+ * Canonicalize and return the string form (UTF-8 will be identical).
+ * Useful for debugging.
+ */
+export function canonicalizeString(value: unknown): string {
+  return serialize(value);
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+/**
+ * @crovia/seal — Immutable continuity receipts for evolving AI systems.
+ *
+ * Public API:
+ *   seal(payload, opts?)            → Receipt
+ *   verify(receipt, payload?)       → VerifyResult
+ *   verifyChain(receipts)           → VerifyResult
+ *   register(receipt, opts?)        → RegisterResult   (optional)
+ *   generateKey() / generateKeySync() → KeyPair
+ *   canonicalize(value)             → Uint8Array
+ *
+ * Wire format: crovia.receipt.v1 (Ed25519 + CSC-1 canonical JSON).
+ * Cross-language byte-identity with the Python reference is part of
+ * the conformance contract.
+ */
+export { seal, computePayload, validateReceiptShape } from "./seal.js";
+export { verify, verifyChain } from "./verify.js";
+export { register } from "./register.js";
+export {
+  generateKey,
+  generateKeySync,
+  publicFromPrivate,
+  signBytes,
+  verifyBytes,
+} from "./keys.js";
+export { canonicalize, canonicalizeString, CanonicalizationError } from "./canonical.js";
+
+export type {
+  Receipt,
+  KeyPair,
+  SealOptions,
+  VerifyResult,
+  RegisterOptions,
+  RegisterResult,
+} from "./types.js";

package/src/keys.ts

@@ -0,0 +1,161 @@
+/**
+ * Ed25519 key handling.
+ *
+ * @noble/ed25519 v2 ships only the curve operations and requires a
+ * SHA-512 implementation to be plugged in via `etc.sha512Sync`. We use
+ * @noble/hashes/sha512 for that.
+ */
+// Polyfill MUST be imported BEFORE @noble/ed25519, which captures
+// globalThis.crypto at module load time.
+import "./_polyfill.js";
+
+import * as ed from "@noble/ed25519";
+import { sha512 } from "@noble/hashes/sha512";
+
+import type { KeyPair } from "./types.js";
+
+// Plug SHA-512 into noble-ed25519 (required by v2 API).
+ed.etc.sha512Sync = (...m: Uint8Array[]) => sha512(ed.etc.concatBytes(...m));
+
+/**
+ * Provide random bytes that work everywhere:
+ *   - browsers and modern Node: globalThis.crypto.getRandomValues
+ *   - older Node (18.x ESM): dynamic import of "node:crypto" (top-level await)
+ *
+ * We override `ed.etc.randomBytes` so noble-ed25519's own RNG path
+ * works in older Node, plus expose `randomBytes()` for seal.ts.
+ */
+type RandFn = (n: number) => Uint8Array;
+
+async function pickRandomBytes(): Promise<RandFn> {
+  const g = globalThis as {
+    crypto?: { getRandomValues?: (a: Uint8Array) => Uint8Array };
+  };
+  if (g.crypto && typeof g.crypto.getRandomValues === "function") {
+    return (n: number) => g.crypto!.getRandomValues!(new Uint8Array(n));
+  }
+  // Node ESM fallback for environments where globalThis.crypto is missing
+  // (Node 18.x without --experimental-global-webcrypto). The dynamic import
+  // is a no-op in browsers because the branch above always wins there.
+  try {
+    const nc = (await import("node:crypto")) as unknown as {
+      webcrypto?: { getRandomValues: (a: Uint8Array) => Uint8Array };
+      randomBytes?: (n: number) => Uint8Array;
+    };
+    if (nc.webcrypto?.getRandomValues) {
+      return (n: number) => nc.webcrypto!.getRandomValues(new Uint8Array(n));
+    }
+    if (typeof nc.randomBytes === "function") {
+      return (n: number) => new Uint8Array(nc.randomBytes!(n));
+    }
+  } catch {
+    // not in Node — fall through to throw
+  }
+  throw new Error(
+    "no secure RNG available — need WebCrypto or Node 'crypto' module",
+  );
+}
+
+const _randomBytes: RandFn = await pickRandomBytes();
+// noble-ed25519's randomBytes signature takes (len?: number); default 32.
+ed.etc.randomBytes = (len?: number) => _randomBytes(len ?? 32);
+
+/** Cryptographically-secure random bytes (browser + Node). */
+export function randomBytes(n: number): Uint8Array {
+  return _randomBytes(n);
+}
+
+const HEX64_RE = /^[0-9a-f]{64}$/;
+
+function bytesToHex(bytes: Uint8Array): string {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) {
+    s += bytes[i]!.toString(16).padStart(2, "0");
+  }
+  return s;
+}
+
+function hexToBytes(hex: string): Uint8Array {
+  if (hex.length % 2 !== 0 || !/^[0-9a-f]*$/.test(hex)) {
+    throw new Error(`invalid hex string of length ${hex.length}`);
+  }
+  const out = new Uint8Array(hex.length / 2);
+  for (let i = 0; i < out.length; i++) {
+    out[i] = parseInt(hex.substring(i * 2, i * 2 + 2), 16);
+  }
+  return out;
+}
+
+function hexToBytes32(hex: string): Uint8Array {
+  if (!HEX64_RE.test(hex)) {
+    throw new Error(`expected 64 lowercase hex chars, got ${hex.length} chars`);
+  }
+  return hexToBytes(hex);
+}
+
+/**
+ * Generate a fresh Ed25519 key pair.
+ * Uses crypto.getRandomValues — works in Node 18+ and modern browsers.
+ */
+export async function generateKey(): Promise<KeyPair> {
+  const priv = ed.utils.randomPrivateKey();
+  const pub = await ed.getPublicKeyAsync(priv);
+  return {
+    privateHex: bytesToHex(priv),
+    publicHex: bytesToHex(pub),
+  };
+}
+
+/**
+ * Synchronous variant of generateKey() — usable when running with the
+ * sha512Sync hook installed (Node, Deno, modern browsers).
+ */
+export function generateKeySync(): KeyPair {
+  const priv = ed.utils.randomPrivateKey();
+  const pub = ed.getPublicKey(priv);
+  return {
+    privateHex: bytesToHex(priv),
+    publicHex: bytesToHex(pub),
+  };
+}
+
+/** Derive the public hex from a private hex (does not mutate caller). */
+export async function publicFromPrivate(privateHex: string): Promise<string> {
+  const pub = await ed.getPublicKeyAsync(hexToBytes32(privateHex));
+  return bytesToHex(pub);
+}
+
+/**
+ * Sign raw bytes with an Ed25519 private key (hex).
+ * Returns 64-byte signature as 128 lowercase hex chars.
+ */
+export async function signBytes(
+  privateHex: string,
+  message: Uint8Array,
+): Promise<string> {
+  const sig = await ed.signAsync(message, hexToBytes32(privateHex));
+  return bytesToHex(sig);
+}
+
+/** Verify a signature against bytes and a public key (all hex / Uint8Array). */
+export async function verifyBytes(
+  publicHex: string,
+  signatureHex: string,
+  message: Uint8Array,
+): Promise<boolean> {
+  if (signatureHex.length !== 128 || !/^[0-9a-f]{128}$/.test(signatureHex)) {
+    return false;
+  }
+  if (!HEX64_RE.test(publicHex)) return false;
+  try {
+    return await ed.verifyAsync(
+      hexToBytes(signatureHex),
+      message,
+      hexToBytes32(publicHex),
+    );
+  } catch {
+    return false;
+  }
+}
+
+export { bytesToHex, hexToBytes };

package/src/register.ts

@@ -0,0 +1,85 @@
+/**
+ * `register()` — optional opt-in: post a receipt to the Crovia substrate.
+ *
+ * The substrate accepts the receipt, returns an anchor id and a position
+ * in the public continuity graph. This is OPTIONAL — `seal()` and
+ * `verify()` work fully offline. Calling `register()` is what causes the
+ * receipt to participate in the public substrate's continuity graph.
+ */
+import type {
+  Receipt,
+  RegisterOptions,
+  RegisterResult,
+} from "./types.js";
+
+const DEFAULT_ENDPOINT = "https://croviatrust.com";
+const DEFAULT_TIMEOUT_MS = 10_000;
+
+/**
+ * Register a receipt with the Crovia substrate.
+ *
+ * @returns A result describing whether the substrate accepted the receipt.
+ *          Never throws on transport errors — they are returned as fields.
+ */
+export async function register(
+  receipt: Receipt,
+  opts: RegisterOptions = {},
+): Promise<RegisterResult> {
+  const endpoint = opts.endpoint ?? DEFAULT_ENDPOINT;
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  const fetchFn = opts.fetch ?? globalThis.fetch;
+
+  if (typeof fetchFn !== "function") {
+    return {
+      accepted: false,
+      status: 0,
+      error: "fetch is not available; pass opts.fetch",
+    };
+  }
+
+  const url = endpoint.replace(/\/+$/, "") + "/api/anchor";
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  try {
+    const res = await fetchFn(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        "user-agent": "crovia-seal/0.1.0",
+      },
+      body: JSON.stringify({ receipt }),
+      signal: controller.signal,
+    });
+
+    let body: unknown = null;
+    try {
+      body = await res.json();
+    } catch {
+      // ignore — body may be empty on errors
+    }
+    const b = body as { anchor_id?: string; error?: string } | null;
+
+    if (res.ok) {
+      return {
+        accepted: true,
+        status: res.status,
+        anchorId: b?.anchor_id,
+      };
+    }
+    return {
+      accepted: false,
+      status: res.status,
+      error: b?.error ?? `HTTP ${res.status}`,
+    };
+  } catch (e) {
+    return {
+      accepted: false,
+      status: 0,
+      error: e instanceof Error ? e.message : String(e),
+    };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/seal.ts

@@ -0,0 +1,231 @@
+/**
+ * `seal()` — produce a continuity receipt over an arbitrary JSON payload.
+ *
+ * Receipt format: `crovia.receipt.v1`. See types.ts for the schema.
+ *
+ * Wire format guarantees:
+ *   - Canonical JSON via CSC-1 (byte-identical with Python reference)
+ *   - Ed25519 signatures over `b"CROVIA-RECEIPT-v1\n" || csc1(receipt without sig)`
+ *   - Domain separator `CROVIA-RECEIPT-v1` distinct from `CROVIA-SEAL-v1`,
+ *     so a receipt signature cannot be replayed as a Seal v1 signature.
+ *   - SHA-256 over canonical bytes of `payload` for `payload_hash`.
+ */
+import { sha256 } from "@noble/hashes/sha256";
+
+import { canonicalize } from "./canonical.js";
+import {
+  bytesToHex,
+  generateKeySync,
+  hexToBytes,
+  randomBytes,
+  signBytes,
+} from "./keys.js";
+import type { KeyPair, Receipt, SealOptions } from "./types.js";
+
+const RECEIPT_VERSION = "crovia.receipt.v1" as const;
+const DOMAIN_STRING = "CROVIA-RECEIPT-v1" as const;
+const DOMAIN_BYTES = new TextEncoder().encode(DOMAIN_STRING + "\n");
+const CANON_ID = "csc-1" as const;
+const SIG_ALG = "ed25519" as const;
+const PAYLOAD_ALG = "sha256" as const;
+const RECEIPT_ID_RE = /^cr_[0-9]{4}_[A-Z2-7]{26}$/;
+
+// 16 random bytes encoded as base32 (no padding) gives 26 chars.
+function randomB32(nBytes = 16): string {
+  const buf = randomBytes(nBytes);
+  // RFC 4648 base32 alphabet, uppercase.
+  const ALPHA = "ABCDEFGHIJKLMNOPQRSTUVWXYZ234567";
+  let out = "";
+  let bits = 0;
+  let acc = 0;
+  for (let i = 0; i < buf.length; i++) {
+    acc = (acc << 8) | buf[i]!;
+    bits += 8;
+    while (bits >= 5) {
+      bits -= 5;
+      out += ALPHA[(acc >>> bits) & 0x1f];
+    }
+  }
+  if (bits > 0) {
+    out += ALPHA[(acc << (5 - bits)) & 0x1f];
+  }
+  return out.slice(0, 26);
+}
+
+function newReceiptId(): string {
+  const year = new Date().getUTCFullYear();
+  return `cr_${year}_${randomB32()}`;
+}
+
+function nowRfc3339Ms(): string {
+  const d = new Date();
+  // toISOString gives e.g. "2026-05-07T15:43:57.123Z" — exactly the shape
+  // the Python reference uses for its emitted_at field.
+  return d.toISOString();
+}
+
+function sha256Prefixed(data: Uint8Array): string {
+  return "sha256:" + bytesToHex(sha256(data));
+}
+
+/**
+ * Compute the exact bytes that are signed.
+ * `payload` here is the receipt object minus its `sig` field.
+ */
+export function computePayload(
+  receiptWithoutSig: Omit<Receipt, "sig">,
+): Uint8Array {
+  const canonical = canonicalize(receiptWithoutSig);
+  const out = new Uint8Array(DOMAIN_BYTES.length + canonical.length);
+  out.set(DOMAIN_BYTES, 0);
+  out.set(canonical, DOMAIN_BYTES.length);
+  return out;
+}
+
+/**
+ * Validate the structural shape of a receipt object.
+ * Returns `null` on success or an error string on failure.
+ */
+export function validateReceiptShape(r: unknown): string | null {
+  if (!r || typeof r !== "object") return "receipt must be an object";
+  const o = r as Record<string, unknown>;
+  if (o["v"] !== RECEIPT_VERSION) return `v must be "${RECEIPT_VERSION}"`;
+  if (typeof o["id"] !== "string" || !RECEIPT_ID_RE.test(o["id"] as string)) {
+    return "id must match cr_YYYY_<26 base32 chars>";
+  }
+  if (
+    typeof o["issued_at"] !== "string" ||
+    !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(
+      o["issued_at"] as string,
+    )
+  ) {
+    return "issued_at must be RFC 3339 UTC with ms precision";
+  }
+  if (
+    typeof o["payload_hash"] !== "string" ||
+    !/^sha256:[0-9a-f]{64}$/.test(o["payload_hash"] as string)
+  ) {
+    return "payload_hash must be 'sha256:<64 hex>'";
+  }
+  if (o["payload_alg"] !== PAYLOAD_ALG) {
+    return `payload_alg must be "${PAYLOAD_ALG}"`;
+  }
+  if (
+    o["payload_type"] !== undefined &&
+    typeof o["payload_type"] !== "string"
+  ) {
+    return "payload_type must be string when present";
+  }
+  if (o["prev"] !== null) {
+    if (
+      typeof o["prev"] !== "string" ||
+      !RECEIPT_ID_RE.test(o["prev"] as string)
+    ) {
+      return "prev must be null or a valid receipt id";
+    }
+  }
+  if (
+    typeof o["seq"] !== "number" ||
+    !Number.isInteger(o["seq"] as number) ||
+    (o["seq"] as number) < 0
+  ) {
+    return "seq must be a non-negative integer";
+  }
+  if (
+    (o["seq"] as number) === 0 &&
+    o["prev"] !== null
+  ) {
+    return "seq=0 (genesis) requires prev=null";
+  }
+  if ((o["seq"] as number) > 0 && o["prev"] === null) {
+    return "seq>0 requires prev to be a receipt id";
+  }
+  if (
+    typeof o["signer"] !== "string" ||
+    !/^[0-9a-f]{64}$/.test(o["signer"] as string)
+  ) {
+    return "signer must be 64 lowercase hex chars";
+  }
+  if (o["sig_alg"] !== SIG_ALG) return `sig_alg must be "${SIG_ALG}"`;
+  if (o["canon"] !== CANON_ID) return `canon must be "${CANON_ID}"`;
+  if (o["domain"] !== DOMAIN_STRING) {
+    return `domain must be "${DOMAIN_STRING}"`;
+  }
+  if (
+    typeof o["sig"] !== "string" ||
+    !/^[0-9a-f]{128}$/.test(o["sig"] as string)
+  ) {
+    return "sig must be 128 lowercase hex chars";
+  }
+  return null;
+}
+
+/**
+ * Produce a continuity receipt over an arbitrary JSON payload.
+ *
+ * Default behaviour: generates a fresh ephemeral key for this call.
+ * Pass `opts.key` to use your own key (recommended for chains).
+ */
+export async function seal(
+  payload: unknown,
+  opts: SealOptions = {},
+): Promise<Receipt> {
+  const key: KeyPair = opts.key ?? generateKeySync();
+
+  // Hash the canonical bytes of the user's payload. This is what makes
+  // the receipt verifiable WITHOUT carrying the payload itself: anyone
+  // with the original bytes can recompute the hash and check it against
+  // payload_hash.
+  const payloadCanonical = canonicalize(payload);
+  const payloadHash = sha256Prefixed(payloadCanonical);
+
+  const prev: string | null = opts.prevReceipt?.id ?? null;
+  const seq: number = opts.prevReceipt
+    ? opts.prevReceipt.seq + 1
+    : 0;
+
+  const issuedAt =
+    opts.issuedAt ??
+    nowRfc3339Ms();
+
+  const unsignedShape: Omit<Receipt, "sig"> = {
+    v: RECEIPT_VERSION,
+    id: newReceiptId(),
+    issued_at: issuedAt,
+    payload_hash: payloadHash,
+    payload_alg: PAYLOAD_ALG,
+    ...(opts.payloadType !== undefined && {
+      payload_type: opts.payloadType,
+    }),
+    prev,
+    seq,
+    signer: key.publicHex,
+    sig_alg: SIG_ALG,
+    canon: CANON_ID,
+    domain: DOMAIN_STRING,
+  };
+
+  const signingPayload = computePayload(unsignedShape);
+  const sigHex = await signBytes(key.privateHex, signingPayload);
+
+  const receipt: Receipt = {
+    ...unsignedShape,
+    sig: sigHex,
+  };
+
+  // Defense in depth: ensure what we return validates.
+  const err = validateReceiptShape(receipt);
+  if (err !== null) {
+    throw new Error(`internal: produced invalid receipt — ${err}`);
+  }
+
+  return receipt;
+}
+
+export {
+  bytesToHex,
+  hexToBytes,
+  RECEIPT_VERSION,
+  DOMAIN_STRING,
+  DOMAIN_BYTES,
+};