@synoi/sraid 0.2.0 → 0.4.0

package/src/oid.ts

@@ -22,6 +22,16 @@
 
 import { createHash } from 'node:crypto'
 import { canonicalize } from './canonicalize.js'
+import { CDRO_ENVELOPE_FIELDS, cdroContentCore } from './internal/content-core.js'
+
+// The CDRO strip-set and its content-core projection are the SINGLE NORMATIVE
+// SOURCE (ADR_019) and live in the PURE ./internal/content-core module (no
+// node:crypto), so the browser verify surface can share them byte-for-byte.
+// oid.ts re-exports them and layers the SHA-256 hashing (below) on top; this
+// keeps the public surface (`import { cdroContentCore, CDRO_ENVELOPE_FIELDS }
+// from '@synoi/sraid'`) unchanged. See ./internal/content-core.ts for the
+// normative strip-set documentation; do not re-list it here.
+export { CDRO_ENVELOPE_FIELDS, cdroContentCore }
 
 /**
  * Compute an OID over an arbitrary canonical-compatible value.
@@ -53,79 +63,6 @@ export function oidOfCanonical(canonical: string | Uint8Array): string {
   return 'sha256:' + createHash('sha256').update(bytes).digest('hex')
 }
 
-/**
- * The detached-signature / envelope fields removed by `cdroContentCore`
- * before hashing. This is the SINGLE NORMATIVE strip-set for the CDRO OID
- * projection (ADR_019 decision 1); every other surface (GAP SDKs, the
- * gateway signer, IMPLEMENTING.md) derives from THIS set, never re-lists it.
- *
- * The set is defined SEMANTICALLY: it is "every field produced BY the signer
- * after canonicalization, plus the OID output itself." Concretely:
- *
- *   oid                  — the projection OUTPUT (cannot be an input to itself).
- *   signature            — legacy hybrid SignatureEnvelope (attaches after hash).
- *   ml_dsa_signature     — detached PQ signature (attaches after hash).
- *   signature_key_id     — signer-stamped key id (produced by the signer).
- *   signature_algorithm  — signer-stamped alg id (produced by the signer).
- *   attestation          — DSSE AttestationEnvelope (attaches after hash).
- *
- * EVERYTHING ELSE IS KEPT and hashed into the OID, including in particular:
- *   - `gap_version` — IN identity so a protocol downgrade is OID-detectable.
- *   - `supersedes`  — IN identity because the SRAID Merkle-DAG head-proves-
- *                     history property requires every lineage edge inside the
- *                     hash. Superseding mints a NEW object; it never mutates
- *                     the old one's bytes, so keeping it here is safe and
- *                     makes the lineage edge tamper-evident.
- *   - `type`, `sraid_version`, `tenant_id`, `created_at_ms`, `created_by`,
- *     `body`, `authority`, `sensitivity`, `prev`, `links`, and any other
- *     content field.
- *
- * This is the ONE projection that yields the SAME OID whether the object is
- * pre- or post-attestation: attaching an `attestation` (or `signature`,
- * `ml_dsa_signature`, `signature_key_id`, `signature_algorithm`) after hashing
- * is stripped back out here, so `cdroOid(obj)` is invariant across signing.
- *
- * It is FROZEN so no caller can mutate the normative set at runtime.
- */
-export const CDRO_ENVELOPE_FIELDS: readonly string[] = Object.freeze([
-  'oid',
-  'signature',
-  'ml_dsa_signature',
-  'signature_key_id',
-  'signature_algorithm',
-  'attestation',
-])
-
-const CDRO_ENVELOPE_FIELD_SET: ReadonlySet<string> = new Set(CDRO_ENVELOPE_FIELDS)
-
-/**
- * Build the OID content core of a full CDRO: the object with EXACTLY the six
- * detached-signature / envelope fields in `CDRO_ENVELOPE_FIELDS` removed at
- * the top level, and everything else kept.
- *
- * This is the mechanism that makes the L4 `authority` block, the L3 lineage
- * edges (`prev`, `links`, `supersedes`), the propagating `sensitivity` tier,
- * and `gap_version` tamper-evident: they are hashed into identity by
- * construction, so a field cannot be added, stripped, re-pointed, or
- * downgraded without producing a different OID (and invalidating the
- * signature, which is computed over these same bytes). Because `prev`/`links`/
- * `supersedes` OIDs are inside the hash, a node's OID transitively commits its
- * whole reachable history (the Merkle-DAG "head proves history" property).
- *
- * Returns a plain object suitable for `canonicalize` / `oidOf`.
- */
-export function cdroContentCore(cdro: unknown): Record<string, unknown> {
-  if (cdro === null || typeof cdro !== 'object' || Array.isArray(cdro)) {
-    throw new TypeError('cdroContentCore: argument must be a CDRO object')
-  }
-  const core: Record<string, unknown> = {}
-  for (const [k, v] of Object.entries(cdro as Record<string, unknown>)) {
-    if (CDRO_ENVELOPE_FIELD_SET.has(k)) continue
-    core[k] = v
-  }
-  return core
-}
-
 /**
  * Compute the OID of a full CDRO over its content core (see
  * `cdroContentCore`). This is the correct way to derive identity for a

package/src/types.ts

@@ -233,14 +233,15 @@ export interface AttestationEnvelope {
  * CDRO — Canonical Data Record Object.
  *
  * The base shape every signed CDRO object takes. The `oid` field is
- * `sha256:` + hex(sha256(canonicalize(body))) where the body is the CDRO
- * minus the `oid` and `signature` fields.
+ * `sha256:` + hex(sha256(canonicalize(cdroContentCore(obj)))) — the WHOLE
+ * object minus the six detached envelope fields (`CDRO_ENVELOPE_FIELDS`).
+ * It is NOT a hash of `body` alone: use `cdroOid`, not `oidOf(cdro.body)`.
  *
  * Mirrors `GapCdroEnvelope` in synoi-gateway so a GAP object IS a CDRO.
  * Higher-layer packages narrow `body` with their own type.
  */
 export interface CDRO<TBody = unknown> {
-  /** "sha256:" + hex(sha256(canonicalize(cdro_minus_oid_and_signature))). */
+  /** "sha256:" + hex(sha256(canonicalize(cdroContentCore(this)))). */
   oid: string
   /** Object type discriminator (e.g. "gap:capability_grant"). */
   type: string
@@ -321,31 +322,22 @@ export interface CDRO<TBody = unknown> {
   signature?: SignatureEnvelope
 }
 
-// ── SRO ───────────────────────────────────────────────────────────────────────
-
-/**
- * SRO — Mutation / Supersession Record.
- *
- * Links a successor CDRO to its predecessor and the actor that authorized
- * the supersession. SROs are themselves CDRO objects (so they're CDROs with
- * an `oid` and `signature`), but they have a specific body shape.
- *
- * Where CDROs are the "what" of the system, SROs are the "what changed."
- * They form an append-only chain: every supersedes pointer in a CDRO is
- * accompanied by an SRO that explains and witnesses the change.
- */
-export interface SROBody {
-  /** OID of the predecessor object being superseded. */
-  predecessor_oid: string
-  /** OID of the successor object that supersedes it. */
-  successor_oid: string
-  /** Why the predecessor was superseded. Free-form short string. */
-  reason: string
-  /** OID of the actor that authorized this mutation. */
-  authorized_by: string
-  /** Optional list of supporting evidence OIDs (audit trail). */
-  evidence_oids?: string[]
-}
-
-/** SRO is just a CDRO with a fixed body type. */
-export type SRO = CDRO<SROBody> & { type: 'sraid:sro' }
+// ── Supersession ──────────────────────────────────────────────────────────────
+//
+// The standalone SRO (Supersession Record Object, `type: 'sraid:sro'`) was
+// REMOVED in 0.4.0. It was the third of three overlapping supersession
+// mechanisms and the only one nothing consumed: `lineage.ts` never handled it,
+// no repo in the SynOI stack referenced it in any language, and the canon had
+// already retired the term (ADR_022 section 0: "an earlier, retired
+// object-format term").
+//
+// Supersession is now expressed by exactly two things, both identity-bound
+// because `cdroContentCore` hashes them:
+//
+//   prev / links[]  the Merkle edges - a head OID commits its whole reachable
+//                   history. Resolve a version set with `latestWins`.
+//   supersedes      the legacy self-asserted string, kept for compatibility.
+//
+// A caller that needs to record WHY something was superseded should put that
+// in the successor's own `body`, where it is hashed and signed, rather than in
+// a separate object whose linkage was never verified.

package/src/validate.ts

@@ -20,7 +20,6 @@ import type {
   LineageLink,
   LinkRel,
   SignatureEnvelope,
-  SRO,
 } from './types.js'
 import { SENSITIVITY_TIERS, isSensitivityTier } from './sensitivity.js'
 
@@ -327,68 +326,7 @@ function validateAttestationEnvelopeShape(x: unknown): string[] {
   return errors
 }
 
-// ── SRO validation ───────────────────────────────────────────────────────────
-
-/**
- * Validate that `x` matches the SRO shape — a CDRO whose `type` is
- * "sraid:sro" and whose `body` carries predecessor/successor pointers and
- * an authorizer. Reuses validateCdro and layers SRO-specific checks on
- * top.
- *
- *   [S01] envelope is not a valid CDRO
- *   [S02] type is not "sraid:sro"
- *   [S03] body.predecessor_oid not a canonical OID (sha256:<64 hex>)
- *   [S04] body.successor_oid not a canonical OID (sha256:<64 hex>)
- *   [S05] body.reason not a non-empty string
- *   [S06] body.authorized_by not a non-empty string
- *   [S07] body.evidence_oids, if present, not an array of non-empty strings
- */
-export function validateSro(x: unknown): ValidationResult {
-  const cdroResult = validateCdro(x)
-  if (!cdroResult.ok) {
-    return { ok: false, errors: cdroResult.errors.map((e) => '[S01] ' + e) }
-  }
-  const errors: string[] = []
-  const o = x as { type?: unknown; body?: unknown }
-
-  if (o.type !== 'sraid:sro') {
-    errors.push('[S02] type must be "sraid:sro" for an SRO')
-  }
-  if (o.body === null || typeof o.body !== 'object' || Array.isArray(o.body)) {
-    errors.push('[S01] body must be an object')
-    return { ok: false, errors }
-  }
-  const b = o.body as Record<string, unknown>
-
-  if (!isCanonicalOid(b['predecessor_oid'])) {
-    errors.push('[S03] body.predecessor_oid must be a canonical OID (sha256:<64 hex>)')
-  }
-  if (!isCanonicalOid(b['successor_oid'])) {
-    errors.push('[S04] body.successor_oid must be a canonical OID (sha256:<64 hex>)')
-  }
-  if (typeof b['reason'] !== 'string' || (b['reason'] as string).length === 0) {
-    errors.push('[S05] body.reason must be a non-empty string')
-  }
-  if (typeof b['authorized_by'] !== 'string' || (b['authorized_by'] as string).length === 0) {
-    errors.push('[S06] body.authorized_by must be a non-empty string')
-  }
-  if (b['evidence_oids'] !== undefined) {
-    if (!Array.isArray(b['evidence_oids'])) {
-      errors.push('[S07] body.evidence_oids, if present, must be an array')
-    } else {
-      const arr = b['evidence_oids'] as unknown[]
-      for (let i = 0; i < arr.length; i++) {
-        if (typeof arr[i] !== 'string' || (arr[i] as string).length === 0) {
-          errors.push(`[S07] body.evidence_oids[${i}] must be a non-empty string`)
-        }
-      }
-    }
-  }
-
-  return { ok: errors.length === 0, errors }
-}
-
-// Type-only re-exports so consumers can do `import type { CDRO, SRO } from '@synoi/sraid'`
+// Type-only re-exports so consumers can do `import type { CDRO } from '@synoi/sraid'`
 // after pulling validators from this module.
 export type {
   AttestationEnvelope,
@@ -397,6 +335,5 @@ export type {
   CDRO,
   LineageLink,
   LinkRel,
-  SRO,
   SignatureEnvelope,
 }

package/src/verify-browser.ts

@@ -0,0 +1,185 @@
+/**
+ * @synoi/sraid/verify-browser — browser / Chrome-extension / service-worker
+ * verify surface.
+ *
+ * The default (`.`) entry statically imports `node:crypto` in three places:
+ * ed25519.ts (node-only Ed25519 verify), mldsa.ts (native ML-DSA + polyfill),
+ * and oid.ts (createHash). `node:crypto` does not exist in a browser or
+ * service-worker context, so `import '@synoi/sraid'` breaks any browser bundle.
+ * This entry is the browser-safe alternative: it carries exactly what a v2
+ * hybrid DSSE receipt verifier needs, implemented WITHOUT any static
+ * node:crypto import.
+ *
+ * WHAT THIS EXPOSES (all browser-safe):
+ *   - canonicalize            — pure RFC 8785 JCS serializer (shared, unchanged).
+ *   - cdroContentCore,        — the CDRO OID content-core projection and its
+ *     CDRO_ENVELOPE_FIELDS       normative strip-set (pure; shared byte-for-byte
+ *                                with the node entry via internal/content-core).
+ *   - verifyAttestation       — hybrid DSSE verify (Ed25519 AND ML-DSA-65, both
+ *                                required over the PAE). ASYNC here: WebCrypto
+ *                                Ed25519 verify is Promise-based.
+ *   - pae, ALG_ED25519,       — the DSSE PAE encoder and algorithm ids (pure,
+ *     ALG_ML_DSA_65              shared with the node entry).
+ *   - cdroOid, oidOf,         — OID helpers over WebCrypto SHA-256. ASYNC here
+ *     oidOfCanonical             (subtle.digest is Promise-based).
+ *
+ * CRYPTO BACKENDS (browsers have no native ML-DSA and no node:crypto):
+ *   - Ed25519 verify  → WebCrypto (RFC 8032 cofactored, matching the node path),
+ *                       with a @noble/curves fallback below the WebCrypto-Ed25519
+ *                       support floor. See internal/ed25519-browser.ts.
+ *   - ML-DSA-65 verify → @noble/post-quantum (pure JS). See internal/mldsa-browser.ts.
+ *   - SHA-256          → WebCrypto subtle.digest. See internal/sha256-browser.ts.
+ *
+ * NODE PARITY: the node default entry (`@synoi/sraid`) is unchanged and stays
+ * synchronous with its node:crypto fast paths. This entry is purely additive.
+ * The only surface difference is async: verifyAttestation, cdroOid, oidOf, and
+ * oidOfCanonical return Promises here because WebCrypto is Promise-based.
+ *
+ * Downstream: @synoi/verify's browser build imports this subpath to bring v2
+ * hybrid DSSE verification (verifyReceiptV2) to the browser, replacing the
+ * fail-closed `v2-not-supported-in-browser-build` stub.
+ */
+
+import { canonicalize } from './canonicalize.js'
+import { CDRO_ENVELOPE_FIELDS, cdroContentCore } from './internal/content-core.js'
+import { decodeBase64StrictBrowser } from './internal/base64-browser.js'
+import { verifyEd25519Browser } from './internal/ed25519-browser.js'
+import { verifyMlDsa65Browser } from './internal/mldsa-browser.js'
+import { sha256HexPrefixed } from './internal/sha256-browser.js'
+import {
+  ALG_ED25519,
+  ALG_ML_DSA_65,
+  findSig,
+  isWellFormedEnvelope,
+  pae,
+  type VerifyAttestationInput,
+  type VerifyAttestationResult,
+} from './internal/attestation-core.js'
+
+// ── Pure / shared re-exports (byte-for-byte identical to the node entry) ──────
+
+export { canonicalize } from './canonicalize.js'
+export { CDRO_ENVELOPE_FIELDS, cdroContentCore } from './internal/content-core.js'
+export {
+  pae,
+  ALG_ED25519,
+  ALG_ML_DSA_65,
+  type VerifyAttestationInput,
+  type VerifyAttestationResult,
+}
+
+// ── Hybrid DSSE attestation verify (browser, ASYNC) ───────────────────────────
+
+/**
+ * Verify a hybrid DSSE attestation envelope in a browser context. Returns
+ * `valid: true` only when the envelope carries BOTH an `ed25519` and an
+ * `ml-dsa-65` signature and BOTH verify against the supplied public keys over
+ * `PAE(payloadType, payload)`. The payloadType is bound into the signed bytes,
+ * so a signature minted for a different payloadType will not verify.
+ *
+ * ASYNC counterpart of the node `verifyAttestation`: identical envelope shape,
+ * AND policy, PAE bytes, and reason strings — only the return is a Promise,
+ * because Ed25519 verify runs on WebCrypto. Never rejects: any malformed input
+ * or verification failure resolves to `{ valid: false, reasons: [...] }`.
+ */
+export async function verifyAttestation(
+  input: VerifyAttestationInput,
+): Promise<VerifyAttestationResult> {
+  const reasons: string[] = []
+
+  const env = input.envelope
+  if (!isWellFormedEnvelope(env)) {
+    return { valid: false, reasons: ['envelope-malformed'] }
+  }
+
+  if (
+    input.expectedPayloadType !== undefined &&
+    env.payloadType !== input.expectedPayloadType
+  ) {
+    return { valid: false, reasons: ['payload-type-mismatch'] }
+  }
+
+  // The signed bytes: PAE binds payloadType + payload together.
+  const message = pae(env.payloadType, env.payload)
+
+  // Find the required hybrid pair. The AND policy: both must be present.
+  const edEntry = findSig(env.signatures, ALG_ED25519)
+  const mlEntry = findSig(env.signatures, ALG_ML_DSA_65)
+
+  if (!edEntry) reasons.push('missing-ed25519')
+  if (!mlEntry) reasons.push('missing-ml-dsa-65')
+
+  let edOk = false
+  let mlOk = false
+
+  if (edEntry) {
+    let edSig: Uint8Array | null = null
+    try {
+      edSig = decodeBase64StrictBrowser(edEntry.sig)
+    } catch {
+      reasons.push('ed25519-malformed')
+    }
+    if (edSig) {
+      try {
+        edOk = await verifyEd25519Browser(edSig, message, input.ed25519_pub)
+      } catch {
+        edOk = false
+      }
+      if (!edOk) reasons.push('ed25519-invalid')
+    }
+  }
+
+  if (mlEntry) {
+    let mlSig: Uint8Array | null = null
+    try {
+      mlSig = decodeBase64StrictBrowser(mlEntry.sig)
+    } catch {
+      reasons.push('ml-dsa-malformed')
+    }
+    if (mlSig) {
+      try {
+        mlOk = verifyMlDsa65Browser(mlSig, message, input.ml_dsa_pub)
+      } catch {
+        mlOk = false
+      }
+      if (!mlOk) reasons.push('ml-dsa-invalid')
+    }
+  }
+
+  return { valid: edOk && mlOk && !!edEntry && !!mlEntry, reasons }
+}
+
+// ── OID helpers (browser, ASYNC via WebCrypto SHA-256) ────────────────────────
+
+/**
+ * Compute an OID over an arbitrary canonical-compatible value using WebCrypto
+ * SHA-256. Returns `sha256:` followed by 64 lowercase hex characters.
+ *
+ * ASYNC counterpart of the node `oidOf`: same canonical bytes and same
+ * `sha256:`-prefixed output, but returns a Promise because subtle.digest is
+ * Promise-based. Byte-identical result to the node entry for the same input.
+ */
+export async function oidOf(canonical: unknown): Promise<string> {
+  const bytes = new TextEncoder().encode(canonicalize(canonical))
+  return sha256HexPrefixed(bytes)
+}
+
+/**
+ * Compute an OID directly from already-canonicalized bytes using WebCrypto
+ * SHA-256. ASYNC counterpart of the node `oidOfCanonical`.
+ */
+export async function oidOfCanonical(canonical: string | Uint8Array): Promise<string> {
+  const bytes =
+    typeof canonical === 'string' ? new TextEncoder().encode(canonical) : canonical
+  return sha256HexPrefixed(bytes)
+}
+
+/**
+ * Compute the OID of a full CDRO over its content core (see `cdroContentCore`),
+ * using WebCrypto SHA-256. ASYNC counterpart of the node `cdroOid`; yields the
+ * SAME OID whether the object is pre- or post-attestation, and the SAME value
+ * the node entry produces for the same object.
+ */
+export async function cdroOid(cdro: unknown): Promise<string> {
+  return oidOf(cdroContentCore(cdro))
+}