@synoi/sraid 0.2.0

package/src/oid.ts

@@ -0,0 +1,146 @@
+/**
+ * @synoi/sraid — oid.ts
+ *
+ * OID (Object IDentifier) computation. An OID is a content-addressed
+ * identifier for a CDRO object:
+ *
+ *     OID = "sha256:" + hex(sha256(canonicalize(content)))
+ *
+ * The hash input is the canonical form of the OBJECT MINUS the six detached
+ * signature / envelope fields (see `CDRO_ENVELOPE_FIELDS`). Higher-layer code
+ * (e.g. GAP) typically passes the object's `body` directly; this function
+ * accepts any value and canonicalizes it without further interpretation, so
+ * callers stay in control of what enters the hash.
+ *
+ * This module is the SINGLE NORMATIVE SOURCE of the CDRO OID projection
+ * (ADR_019). The strip-set and number rule are specified in prose in
+ * PROJECTION_SPEC.md; all other surfaces derive from here.
+ *
+ * This matches the gateway's `computeGapOid` (src/gap/oid.ts) and
+ * `payloadOid` (src/inference/receipts.ts) byte-for-byte.
+ */
+
+import { createHash } from 'node:crypto'
+import { canonicalize } from './canonicalize.js'
+
+/**
+ * Compute an OID over an arbitrary canonical-compatible value.
+ *
+ *   oidOf({ a: 1, b: 2 }) === oidOf({ b: 2, a: 1 })
+ *
+ * Returns `sha256:` followed by 64 lowercase hex characters.
+ *
+ * Uses the platform SHA-256 (node:crypto / OpenSSL), which is byte-identical
+ * to any conformant SHA-256 and materially faster than a pure-JS hash. The
+ * output contract is unchanged.
+ */
+export function oidOf(canonical: unknown): string {
+  const bytes = new TextEncoder().encode(canonicalize(canonical))
+  return 'sha256:' + createHash('sha256').update(bytes).digest('hex')
+}
+
+/**
+ * Compute an OID directly from already-canonicalized bytes. Useful when
+ * the caller has produced the canonical string itself (for example, when
+ * the same bytes will also feed into a signature) and wants to avoid
+ * canonicalizing twice.
+ */
+export function oidOfCanonical(canonical: string | Uint8Array): string {
+  const bytes =
+    typeof canonical === 'string'
+      ? new TextEncoder().encode(canonical)
+      : canonical
+  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
+ * complete CDRO: it hashes `authority`, `supersedes`, `gap_version`, `body`,
+ * and every other content field, so the L4 authority block is identity-bound
+ * and cannot be silently dropped.
+ *
+ * INVARIANT (ADR_019): `cdroOid(obj)` yields the SAME OID whether `obj` is
+ * pre- or post-attestation, because the detached envelope fields are stripped
+ * (see `CDRO_ENVELOPE_FIELDS`). This is what lets a third party recompute the
+ * OID of a signed receipt and match the value the signer stamped.
+ *
+ * Note this differs from `oidOf(cdro.body)`: a CDRO's identity is over the
+ * whole content core, not just its body.
+ */
+export function cdroOid(cdro: unknown): string {
+  return oidOf(cdroContentCore(cdro))
+}

package/src/sensitivity.ts

@@ -0,0 +1,154 @@
+/**
+ * @synoi/sraid — sensitivity.ts
+ *
+ * L4 GOVERNANCE — the propagating sensitivity label (OBJECT_MODEL_CLEANSHEET
+ * §3.4, SRAID_FOUNDATION_PUNCHLIST A5). A single coarse, OPAQUE tier on the
+ * CDRO that retrieval, summarization, and consolidation MUST carry forward
+ * monotonically: a derived object inherits the HIGHEST tier among its sources,
+ * so a summary of high-sensitivity inputs cannot be downgraded.
+ *
+ * ── Why the tiers are OPAQUE ORDINALS, not literal categories ───────────────
+ *
+ * SPEC §7 is normative and explicit: the envelope is a NON-encrypted, signed,
+ * publicly visible surface. A literal classification label (e.g. `"phi"`,
+ * `"health"`, `"financial"`) on that surface would LEAK the nature of the
+ * encrypted `body` — an observer who cannot read the ciphertext could still
+ * read "this is health data" off the envelope. SPEC §7 therefore requires a
+ * "coarse, OPAQUE sensitivity classifier", and the §9 reserved note says the
+ * same.
+ *
+ * So the tier set here is a small, COARSE, ORDERED ladder of opaque levels
+ * (`s0` < `s1` < `s2` < `s3` < `s4`). It carries an ORDERING (needed for the
+ * monotone `max()` lattice — standard lattice-based information-flow labeling,
+ * Denning 1976) but NO semantic category. The mapping from a regulatory
+ * category (PHI, PII, secret, …) to a tier is a higher-layer POLICY concern
+ * kept OFF the public envelope: an operator's policy decides "PHI → s3"
+ * privately; the wire only ever shows `s3`. This is the "coarse, opaque tier
+ * (or opaque policy-scope handle)" required by the task and SPEC §7.
+ *
+ * The field is hashed into the OID (it is a content-core field; see
+ * `cdroContentCore` in oid.ts), so it cannot be silently stripped or
+ * downgraded without changing the OID and breaking the signature.
+ *
+ * NOTE on maturity (CLAIMS_DISCIPLINE): this module ships the FIELD, the
+ * lattice, the monotone `max()` carry-forward, and the validator, with
+ * vectors. The commitment-based selective-disclosure scheme that would
+ * CONCEAL the tier itself (SPEC §7 / §9) is reserved and NOT built here.
+ */
+
+/**
+ * The coarse, opaque sensitivity tiers, lowest to highest. These are ORDINAL
+ * and OPAQUE by design — they convey relative sensitivity for the monotone
+ * propagation lattice WITHOUT naming a content category (per SPEC §7, a
+ * literal category on the public envelope would leak what the encrypted body
+ * is). The mapping of a real-world classification to a tier is private policy,
+ * not part of this taxonomy.
+ *
+ *   s0 — lowest / unclassified (the default floor; freely shareable)
+ *   s1 — low
+ *   s2 — moderate
+ *   s3 — high
+ *   s4 — highest / most restricted
+ *
+ * Five coarse levels is deliberate: enough granularity for a useful lattice,
+ * few enough to stay coarse (so the tier alone is weakly distinguishing).
+ */
+export type SensitivityTier = 's0' | 's1' | 's2' | 's3' | 's4'
+
+/**
+ * The ordered tier ladder, lowest-first. The index IS the rank used by the
+ * `max()` lattice. Frozen so the ordering is immutable at runtime.
+ */
+export const SENSITIVITY_TIERS: readonly SensitivityTier[] = Object.freeze([
+  's0',
+  's1',
+  's2',
+  's3',
+  's4',
+] as const)
+
+/** The default tier for an object that declares none — the lattice floor. */
+export const SENSITIVITY_DEFAULT: SensitivityTier = 's0'
+
+const RANK: ReadonlyMap<string, number> = new Map(
+  SENSITIVITY_TIERS.map((t, i) => [t, i]),
+)
+
+/** True iff `x` is a defined `SensitivityTier`. */
+export function isSensitivityTier(x: unknown): x is SensitivityTier {
+  return typeof x === 'string' && RANK.has(x)
+}
+
+/**
+ * The ordinal rank of a tier (0 = lowest). Throws on an unknown tier so a
+ * typo can never silently rank as the floor (which would be a downgrade
+ * footgun in the lattice).
+ */
+export function sensitivityRank(tier: SensitivityTier): number {
+  const r = RANK.get(tier)
+  if (r === undefined) {
+    throw new RangeError(`sensitivityRank: "${String(tier)}" is not a known tier`)
+  }
+  return r
+}
+
+/**
+ * The monotone lattice join: the HIGHER (more restricted) of two tiers.
+ * `max('s1','s3') === 's3'`. This is the per-pair operation behind
+ * carry-forward.
+ */
+export function sensitivityMax(
+  a: SensitivityTier,
+  b: SensitivityTier,
+): SensitivityTier {
+  return sensitivityRank(a) >= sensitivityRank(b) ? a : b
+}
+
+/**
+ * Carry-forward over a set of source tiers: the highest tier present.
+ *
+ * This is the rule that makes sensitivity MONOTONE under derivation
+ * (retrieval / summarization / consolidation): a derived object's tier =
+ * max(tiers of all its `consolidated_from` / `derived_from` sources). It can
+ * only ever go UP, never down — a summary of high-sensitivity inputs stays at
+ * the highest input tier.
+ *
+ * `undefined`/absent source tiers are treated as the floor (`s0`): a source
+ * that declared no tier cannot pull the result down, and an explicit higher
+ * source always wins. An empty input set returns the floor.
+ */
+export function sensitivityCarryForward(
+  sources: ReadonlyArray<SensitivityTier | undefined | null>,
+): SensitivityTier {
+  let acc: SensitivityTier = SENSITIVITY_DEFAULT
+  for (const s of sources) {
+    if (s === undefined || s === null) continue
+    if (!isSensitivityTier(s)) {
+      throw new RangeError(
+        `sensitivityCarryForward: "${String(s)}" is not a known tier`,
+      )
+    }
+    acc = sensitivityMax(acc, s)
+  }
+  return acc
+}
+
+/**
+ * Guard a proposed sensitivity assignment against monotone violation: the
+ * `proposed` tier of a derived object MUST be at least as high as the
+ * carry-forward of its `sources`. Returns the floor the derived object is NOT
+ * allowed to fall below, plus whether `proposed` honors it.
+ *
+ * Use this to REJECT an attempt to label a summary of `s3` inputs as `s1`.
+ */
+export function sensitivityMonotoneCheck(
+  proposed: SensitivityTier,
+  sources: ReadonlyArray<SensitivityTier | undefined | null>,
+): { ok: boolean; floor: SensitivityTier; proposed: SensitivityTier } {
+  const floor = sensitivityCarryForward(sources)
+  return {
+    ok: sensitivityRank(proposed) >= sensitivityRank(floor),
+    floor,
+    proposed,
+  }
+}

package/src/signature.ts

@@ -0,0 +1,119 @@
+/**
+ * @synoi/sraid — signature.ts
+ *
+ * Hybrid ed25519 + ml-dsa-65 signature verification for CDRO envelopes.
+ *
+ * SynOI signs every Decision Receipt and every governance object with
+ * BOTH a classical Ed25519 signature and a post-quantum ML-DSA-65
+ * signature. The verifier in this package requires BOTH to be valid
+ * before returning `valid: true` — even though either alone is
+ * cryptographically meaningful, signed objects exit the system only when
+ * both check out.
+ *
+ * The signature bytes are computed over the canonical form of the object
+ * minus the `signature` field itself. Callers are expected to produce
+ * that canonical form (typically via `canonicalize()` in this package)
+ * and pass it as `canonical` here — verifiers MUST use the same exact
+ * bytes that the signer used, so callers control that contract.
+ */
+
+import { verifyEd25519 } from './ed25519.js'
+import { decodeBase64Strict } from './internal/base64.js'
+import { verifyMlDsa65 } from './mldsa.js'
+import type { SignatureEnvelope } from './types.js'
+
+export interface VerifySignatureInput {
+  /** The canonical bytes that were signed (string is utf-8 encoded). */
+  canonical: string | Uint8Array
+  /** Signature envelope to verify. */
+  envelope: SignatureEnvelope
+  /** Raw 32-byte Ed25519 public key. */
+  ed25519_pub: Uint8Array
+  /** Raw ML-DSA-65 public key bytes. */
+  ml_dsa_pub: Uint8Array
+}
+
+export interface VerifySignatureResult {
+  /** True only when BOTH signatures verified successfully. */
+  valid: boolean
+  /**
+   * Human-readable reasons for failure. Empty when valid. Possible
+   * values: 'ed25519-invalid', 'ml-dsa-invalid', 'ed25519-malformed',
+   * 'ml-dsa-malformed', 'envelope-malformed'.
+   */
+  reasons: string[]
+}
+
+/**
+ * Verify a hybrid CDRO signature envelope. Returns `valid: true` only
+ * when both the Ed25519 and the ML-DSA-65 signatures verify against the
+ * supplied public keys and canonical bytes.
+ */
+export function verifySignature(input: VerifySignatureInput): VerifySignatureResult {
+  const reasons: string[] = []
+
+  if (
+    !input.envelope ||
+    typeof input.envelope.ed25519 !== 'string' ||
+    typeof input.envelope.ml_dsa_65 !== 'string' ||
+    typeof input.envelope.signer_kid !== 'string'
+  ) {
+    return { valid: false, reasons: ['envelope-malformed'] }
+  }
+
+  const message =
+    typeof input.canonical === 'string'
+      ? new TextEncoder().encode(input.canonical)
+      : input.canonical
+
+  // Decode the two signatures from base64. If either fails to decode,
+  // the envelope is malformed — but we still want to verify the OTHER
+  // signature so we can report both reasons in one pass.
+  let edSig: Uint8Array | null = null
+  let mlSig: Uint8Array | null = null
+  try {
+    edSig = fromBase64(input.envelope.ed25519)
+  } catch {
+    reasons.push('ed25519-malformed')
+  }
+  try {
+    mlSig = fromBase64(input.envelope.ml_dsa_65)
+  } catch {
+    reasons.push('ml-dsa-malformed')
+  }
+
+  let edOk = false
+  let mlOk = false
+
+  if (edSig) {
+    try {
+      edOk = verifyEd25519(edSig, message, input.ed25519_pub)
+    } catch {
+      // Treat invalid signature shape as a verification failure rather
+      // than a thrown exception, so callers can rely on a clean result.
+      edOk = false
+    }
+    if (!edOk) reasons.push('ed25519-invalid')
+  }
+
+  if (mlSig) {
+    try {
+      mlOk = verifyMlDsa65(mlSig, message, input.ml_dsa_pub)
+    } catch {
+      mlOk = false
+    }
+    if (!mlOk) reasons.push('ml-dsa-invalid')
+  }
+
+  return { valid: edOk && mlOk, reasons }
+}
+
+// ── Base64 helpers (standard, with `=` padding) ──────────────────────────────
+
+// Strict standard base64. Throws Error('base64-malformed') on any deviation
+// rather than silently truncating at the first illegal byte. Both call sites
+// wrap this in try/catch and map the throw to a *-malformed reason, so
+// verifySignature never throws.
+function fromBase64(s: string): Uint8Array {
+  return decodeBase64Strict(s)
+}