run402 4.24.1 → 4.26.0

package/sdk/dist/namespaces/gitvault.crypto.js

@@ -0,0 +1,690 @@
+/**
+ * gitvault — `r402s/v0` crypto core (protocol rev 40, §1 + §2; task 5.1).
+ *
+ * Pure, isomorphic (WebCrypto + noble + `@hpke/core`), no I/O. Everything
+ * byte-level the protocol pins lives here ONCE and is replayed against the
+ * frozen vector set (`gitvault.crypto.test.ts`):
+ *
+ *   - JCS (RFC 8785) for the no-JSON-numbers profile + the strict-parse profile
+ *   - the two hash rules: stored bytes (JCS INCLUDING `signature`) and the
+ *     signature preimage `"r402s/v0/" + object_kind + "\n" + JCS(object minus signature)`
+ *   - Ed25519 strict RFC 8032 — noble with `zip215: false` pinned; a
+ *     ZIP215-only signature is REJECTED (vector `zip215-002`)
+ *   - `lp` / `lp_opt` length prefixes + the open-id / open-binding preimages
+ *   - HKDF-SHA-256 `k_obj` / `K_digest` derivations and HMAC keyed commitments
+ *   - the XChaCha20-Poly1305 frame (`"R402S0"` ‖ suite byte ‖ 24-byte nonce ‖ ct‖tag)
+ *     with its seven-member JCS AAD
+ *   - the `key_envelope` HPKE seal/open (Base mode, DHKEM(X25519,HKDF-SHA256) /
+ *     HKDF-SHA256 / ChaCha20-Poly1305) with the EXACT D188 `info` / AAD bytes
+ *   - genesis key-binding + recovery-receipt checks
+ *
+ * Design rules carried from the protocol: HPKE is a NAMED implementation
+ * (`@hpke/core` + `@hpke/chacha20poly1305`), never assembled from primitives
+ * (D38); an envelope's signature is verified BEFORE any open; plain hashes of
+ * plaintext content never leave the client (every server-comparable digest is
+ * keyed); object ids are single-use key labels — callers MUST NOT re-encrypt
+ * under an id (retries read-and-compare).
+ */
+import { parse, evaluate } from "@humanwhocodes/momoa";
+import { ed25519, x25519 } from "@noble/curves/ed25519.js";
+import { xchacha20poly1305 } from "@noble/ciphers/chacha.js";
+import { sha256 } from "@noble/hashes/sha2.js";
+import { hkdf } from "@noble/hashes/hkdf.js";
+import { hmac } from "@noble/hashes/hmac.js";
+import { bytesToHex, hexToBytes, utf8ToBytes, concatBytes } from "@noble/hashes/utils.js";
+import { base64urlnopad } from "@scure/base";
+import { canonicalize } from "json-canonicalize";
+import { CipherSuite, DhkemX25519HkdfSha256, HkdfSha256 } from "@hpke/core";
+import { Chacha20Poly1305 } from "@hpke/chacha20poly1305";
+import { LocalError } from "../errors.js";
+// ─── Constants ───────────────────────────────────────────────────────────────
+/** Wire format tag (retained by decision D181 across the product rename). */
+export const GITVAULT_FORMAT = "r402s/v0";
+/** The one V0 cryptographic suite. */
+export const GITVAULT_SUITE = "r402s-1";
+/** Frame magic, bytes 0–5 of every encrypted object. */
+export const GITVAULT_FRAME_MAGIC = "R402S0";
+/** Frame suite byte (byte 6) and its two-char AAD spelling. */
+export const GITVAULT_FRAME_SUITE_BYTE = 0x01;
+export const GITVAULT_FRAME_SUITE_ID = "01";
+/** Protocol §2: max plaintext per encrypted object (256 MiB). */
+export const GITVAULT_MAX_PLAINTEXT_BYTES = 256 * 1024 * 1024;
+/** The genesis generation / epoch constants (schema consts). */
+export const GITVAULT_GENESIS_GENERATION = "0000000000000000";
+export const GITVAULT_GENESIS_EPOCH = "0000000000000001";
+/** HPKE `info` label for `key_envelope` (D188). */
+export const GITVAULT_ENVELOPE_INFO_LABEL = "r402s/v0/envelope";
+/**
+ * The V0-A terminal-loss sentence — protocol §0 / client-surface spec. Doctor
+ * and status surfaces MUST state it verbatim while V0-A is current. Do not
+ * paraphrase; the wording is a reviewed product commitment.
+ */
+export const GITVAULT_TERMINAL_LOSS_STATEMENT = "whole-machine or whole-keystore loss is terminal for vault history until human envelopes ship";
+/** Protocol §0 sentence in full, as `doctor`/`status` print it. */
+export const GITVAULT_TERMINAL_LOSS_DOCTOR_TEXT = "In V0-A, whole-machine or whole-keystore loss is terminal for vault history (VAULT_UNRECOVERABLE) until human envelopes ship. " +
+    "The vault protects source history from host-side loss while a principal keystore survives. " +
+    "The remaining paths are the platform's custodial restore of deployed artifacts (the deploy lane's CAS) and org/infra recovery; " +
+    "a recovery receipt authenticates a genesis — it cannot decrypt anything.";
+const FRAME_NONCE_BYTES = 24;
+const FRAME_HEADER_BYTES = 6 + 1 + FRAME_NONCE_BYTES;
+const AEAD_TAG_BYTES = 16;
+// ─── Scalar grammars (common.json) ───────────────────────────────────────────
+export const GITVAULT_HEX16_RE = /^[0-9a-f]{16}$/;
+export const GITVAULT_HEX32_RE = /^[0-9a-f]{32}$/;
+export const GITVAULT_SHA256_RE = /^[0-9a-f]{64}$/;
+export const GITVAULT_OID40_RE = /^[0-9a-f]{40}$/;
+export const GITVAULT_VK_RE = /^vk_[0-9a-f]{32}$/;
+export const GITVAULT_EK_RE = /^ek_[0-9a-f]{32}$/;
+export const GITVAULT_SRC_RE = /^src_[0-9a-f]{32}$/;
+export const GITVAULT_SERVICE_KEY_ID_RE = /^sk_[0-9a-z-]{4,64}$/;
+export const GITVAULT_SIZE_BYTES_RE = /^(0|[1-9][0-9]{0,14})$/;
+/** 32 bytes base64url: 43 chars, final char in the 16-value padding class. */
+export const GITVAULT_B64U_32_RE = /^[A-Za-z0-9_-]{42}[AEIMQUYcgkosw048]$/;
+/** 64 bytes base64url: 86 chars, final char ∈ {A,Q,g,w}. */
+export const GITVAULT_B64U_64_RE = /^[A-Za-z0-9_-]{85}[AQgw]$/;
+/** The HPKE-sealed K_repo: 48 bytes = exactly 64 base64url chars. */
+export const GITVAULT_HPKE_CT_RE = /^[A-Za-z0-9_-]{64}$/;
+export const GITVAULT_TIMESTAMP_RE = /^[0-9]{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])T([01][0-9]|2[0-3]):[0-5][0-9]:[0-5][0-9]\.[0-9]{3}Z$/;
+function fail(code, message, context, details) {
+    throw new LocalError(message, context, { code, details });
+}
+/** Canonical base64url (no padding, length mod 4 ≠ 1, zero trailing bits): decode→encode round-trips. */
+export function isCanonicalBase64url(value) {
+    if (!/^[A-Za-z0-9_-]*$/.test(value) || value.length % 4 === 1)
+        return false;
+    try {
+        return base64urlnopad.encode(base64urlnopad.decode(value)) === value;
+    }
+    catch {
+        return false;
+    }
+}
+/** Decode canonical base64url or throw (`GITVAULT_NONCANONICAL_BASE64URL`). */
+export function fromBase64url(value, field = "value") {
+    if (!isCanonicalBase64url(value)) {
+        fail("GITVAULT_NONCANONICAL_BASE64URL", `${field} is not canonical base64url`, "decoding r402s/v0 scalar", { field });
+    }
+    return base64urlnopad.decode(value);
+}
+export function toBase64url(bytes) {
+    return base64urlnopad.encode(bytes);
+}
+/** RFC 3339 UTC ms `Z` with semantic calendar validation (D187: `2026-02-31` and a non-leap Feb 29 are rejects). */
+export function isValidGitvaultTimestamp(value) {
+    if (!GITVAULT_TIMESTAMP_RE.test(value))
+        return false;
+    const year = Number(value.slice(0, 4));
+    const month = Number(value.slice(5, 7));
+    const day = Number(value.slice(8, 10));
+    const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    const daysInMonth = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
+    return day <= daysInMonth;
+}
+/** Format a Date as the protocol timestamp grammar (RFC 3339 UTC, milliseconds, `Z`). */
+export function formatGitvaultTimestamp(date = new Date()) {
+    return date.toISOString();
+}
+// ─── Encoding helpers ────────────────────────────────────────────────────────
+/** `lp(x)` = 4-byte big-endian UTF-8 byte length ‖ UTF-8 bytes (protocol §1). */
+export function lp(value) {
+    const bytes = utf8ToBytes(value);
+    const out = new Uint8Array(4 + bytes.length);
+    new DataView(out.buffer).setUint32(0, bytes.length, false);
+    out.set(bytes, 4);
+    return out;
+}
+/** `lp_opt(null)` = `0x00`; `lp_opt(x)` = `0x01` ‖ `lp(x)`. */
+export function lpOpt(value) {
+    return value === null ? new Uint8Array([0]) : concatBytes(new Uint8Array([1]), lp(value));
+}
+export function sha256Hex(bytes) {
+    return bytesToHex(sha256(bytes));
+}
+/** CSPRNG bytes from the platform WebCrypto (protocol §2: all keys/nonces/ephemerals from the OS CSPRNG). */
+export function randomBytes(length) {
+    const out = new Uint8Array(length);
+    globalThis.crypto.getRandomValues(out);
+    return out;
+}
+/** A fresh `<prefix>_<32 lowercase hex>` id (protocol §1: ids are CSPRNG). */
+export function newGitvaultId(prefix) {
+    return `${prefix}_${bytesToHex(randomBytes(16))}`;
+}
+/** A fresh 32-lowercase-hex scalar (client_creation_id, capture_id, …). */
+export function newHex32() {
+    return bytesToHex(randomBytes(16));
+}
+// ─── JCS + strict parse ──────────────────────────────────────────────────────
+function assertProfileValue(value, path) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number" || typeof value === "bigint") {
+        fail("GITVAULT_JSON_NUMBER", `r402s/v0 profile forbids JSON numbers (at ${path})`, "canonicalizing r402s/v0 object", { path });
+    }
+    if (Array.isArray(value)) {
+        value.forEach((entry, i) => assertProfileValue(entry, `${path}[${i}]`));
+        return;
+    }
+    if (typeof value === "object") {
+        for (const [key, entry] of Object.entries(value)) {
+            if (entry === undefined) {
+                fail("GITVAULT_JSON_UNDEFINED", `undefined member at ${path}.${key}`, "canonicalizing r402s/v0 object", { path: `${path}.${key}` });
+            }
+            assertProfileValue(entry, `${path}.${key}`);
+        }
+        return;
+    }
+    fail("GITVAULT_JSON_UNSUPPORTED", `unsupported value at ${path}`, "canonicalizing r402s/v0 object", { path });
+}
+/** RFC 8785 canonical JSON (no-numbers profile) as UTF-8 bytes. */
+export function jcs(value) {
+    assertProfileValue(value, "$");
+    return utf8ToBytes(canonicalize(value));
+}
+/** RFC 8785 canonical JSON as a string. */
+export function jcsString(value) {
+    assertProfileValue(value, "$");
+    return canonicalize(value);
+}
+function inspectStrict(node, path) {
+    switch (node.type) {
+        case "Document":
+            return inspectStrict(node.body, path);
+        case "Number":
+            fail("GITVAULT_STRICT_PARSE", `JSON number at ${path}`, "strict-parsing r402s/v0 object", { reason: "json-number", path });
+        // eslint-disable-next-line no-fallthrough
+        case "Object": {
+            const seen = new Set();
+            for (const member of node.members) {
+                const name = member.name.type === "String" ? member.name.value : member.name.name;
+                if (seen.has(name)) {
+                    fail("GITVAULT_STRICT_PARSE", `duplicate member ${name} at ${path}`, "strict-parsing r402s/v0 object", { reason: "duplicate-member", path: `${path}.${name}` });
+                }
+                seen.add(name);
+                inspectStrict(member.value, `${path}.${name}`);
+            }
+            return;
+        }
+        case "Array":
+            node.elements.forEach((entry, i) => inspectStrict(entry.value, `${path}[${i}]`));
+            return;
+        default:
+            return;
+    }
+}
+/**
+ * The §1 strict-parse profile: reject ANY JSON number, duplicate members,
+ * invalid JSON, and any text that is not byte-for-byte the JCS of its value
+ * (member order, whitespace, escapes). Schema-awareness (unknown members,
+ * hex case, scalar lengths) is the caller's job.
+ */
+export function parseGitvaultStrict(text) {
+    let ast;
+    try {
+        ast = parse(text, { mode: "json", allowTrailingCommas: false });
+    }
+    catch {
+        fail("GITVAULT_STRICT_PARSE", "invalid JSON", "strict-parsing r402s/v0 object", { reason: "invalid-json" });
+    }
+    inspectStrict(ast, "$");
+    const value = evaluate(ast);
+    if (jcsString(value) !== text) {
+        fail("GITVAULT_STRICT_PARSE", "text is not canonical JCS", "strict-parsing r402s/v0 object", { reason: "noncanonical-encoding" });
+    }
+    return value;
+}
+/** Classify a strict-parse failure (for vector replay + diagnostics). */
+export function gitvaultStrictParseReason(error) {
+    if (error instanceof LocalError && error.code === "GITVAULT_STRICT_PARSE") {
+        const details = error.details;
+        return details?.reason ?? null;
+    }
+    return null;
+}
+// ─── Hash rules: stored bytes + signature preimage ───────────────────────────
+/** Stored bytes of a signed object = JCS of the COMPLETE object including `signature`. */
+export function storedBytes(object) {
+    return jcs(object);
+}
+/** SHA-256 over stored bytes — what every `*_sha256` naming a signed object means. */
+export function storedBytesSha256(object) {
+    return sha256Hex(storedBytes(object));
+}
+function withoutSignature(object) {
+    const { signature: _signature, ...rest } = object;
+    void _signature;
+    return rest;
+}
+/** Signature preimage = `"r402s/v0/" + object_kind + "\n" + JCS(object without its single top-level signature)`. */
+export function signaturePreimage(objectKind, objectWithoutSignature) {
+    if ("signature" in objectWithoutSignature) {
+        fail("GITVAULT_PREIMAGE_HAS_SIGNATURE", "preimage input must not carry a signature member", "building r402s/v0 signature preimage");
+    }
+    return concatBytes(utf8ToBytes(`${GITVAULT_FORMAT}/${objectKind}\n`), jcs(objectWithoutSignature));
+}
+// ─── Ed25519 strict (RFC 8032, zip215:false) ─────────────────────────────────
+export function ed25519PublicKey(seed) {
+    return ed25519.getPublicKey(seed);
+}
+export function ed25519Sign(message, seed) {
+    return ed25519.sign(message, seed);
+}
+/**
+ * Strict RFC 8032 verification: `zip215: false` is PINNED. Non-canonical R or A
+ * encodings, non-canonical S, and wrong-length inputs are all `false` — never
+ * an exception a caller could mistake for a transport error.
+ */
+export function ed25519VerifyStrict(signature, message, publicKey) {
+    if (signature.length !== 64 || publicKey.length !== 32)
+        return false;
+    try {
+        return ed25519.verify(signature, message, publicKey, { zip215: false });
+    }
+    catch {
+        return false;
+    }
+}
+/** Sign an object under its `object_kind` domain; returns the complete signed object. */
+export function signGitvaultObject(objectWithoutSignature, seed) {
+    const preimage = signaturePreimage(objectWithoutSignature.object_kind, objectWithoutSignature);
+    return { ...objectWithoutSignature, signature: toBase64url(ed25519Sign(preimage, seed)) };
+}
+/**
+ * Verify a signed object against a raw public key. Exact scalar lengths are
+ * checked FIRST (an 85-char signature or a 42-char key is a schema reject,
+ * never a decode-time surprise), then strict Ed25519 under the object's domain.
+ */
+export function verifyGitvaultObject(object, publicKey) {
+    if (typeof object.signature !== "string" || !GITVAULT_B64U_64_RE.test(object.signature) || !isCanonicalBase64url(object.signature))
+        return false;
+    let pub;
+    if (typeof publicKey === "string") {
+        if (!GITVAULT_B64U_32_RE.test(publicKey) || !isCanonicalBase64url(publicKey))
+            return false;
+        pub = fromBase64url(publicKey);
+    }
+    else {
+        pub = publicKey;
+    }
+    const preimage = signaturePreimage(object.object_kind, withoutSignature(object));
+    return ed25519VerifyStrict(fromBase64url(object.signature), preimage, pub);
+}
+/** Verify or throw `GITVAULT_SIGNATURE_INVALID`. */
+export function assertGitvaultSignature(object, publicKey, context = "verifying r402s/v0 signature") {
+    if (!verifyGitvaultObject(object, publicKey)) {
+        fail("GITVAULT_SIGNATURE_INVALID", `${object.object_kind} signature does not verify (strict RFC 8032)`, context, { object_kind: object.object_kind });
+    }
+}
+// ─── Key fingerprints + keypairs ─────────────────────────────────────────────
+/** First 16 bytes of SHA-256(raw pubkey), lowercase hex (32 chars). */
+export function keyFingerprintHex(rawPublicKey) {
+    return sha256Hex(rawPublicKey).slice(0, 32);
+}
+/** `vk_` fingerprint of a raw Ed25519 public key. */
+export function vkFingerprint(rawPublicKey) {
+    return `vk_${keyFingerprintHex(rawPublicKey)}`;
+}
+/** `ek_` fingerprint of a raw X25519 public key. */
+export function ekFingerprint(rawPublicKey) {
+    return `ek_${keyFingerprintHex(rawPublicKey)}`;
+}
+export function generateSigningKeypair(seed = randomBytes(32)) {
+    if (seed.length !== 32)
+        fail("GITVAULT_BAD_SEED", "Ed25519 seed must be 32 bytes", "generating signing keypair");
+    return { seed, public_key: ed25519PublicKey(seed) };
+}
+export function generateEncryptionKeypair(privateKey = randomBytes(32)) {
+    if (privateKey.length !== 32)
+        fail("GITVAULT_BAD_SEED", "X25519 private key must be 32 bytes", "generating encryption keypair");
+    return { private_key: privateKey, public_key: x25519.getPublicKey(privateKey) };
+}
+// ─── HKDF: k_obj / K_digest, keyed commitments ──────────────────────────────
+/** `k_obj` info = lp("r402s/v0") ‖ lp(suite) ‖ lp(repo_id) ‖ lp(epoch) ‖ lp(object_kind) ‖ lp(object_id) ‖ lp("L=32"). */
+export function objectKeyInfo(repoId, epoch, objectKind, objectId) {
+    return concatBytes(lp(GITVAULT_FORMAT), lp(GITVAULT_SUITE), lp(repoId), lp(epoch), lp(objectKind), lp(objectId), lp("L=32"));
+}
+/** `k_obj = HKDF-SHA-256(ikm=K_repo, salt=∅, info, L=32)`. */
+export function deriveObjectKey(kRepo, repoId, epoch, objectKind, objectId) {
+    return hkdf(sha256, kRepo, undefined, objectKeyInfo(repoId, epoch, objectKind, objectId), 32);
+}
+/** `K_digest` info = lp("r402s/v0") ‖ lp("r402s-1") ‖ lp(repo_id) ‖ lp(epoch) ‖ lp("digest") ‖ lp(label) ‖ lp("L=32"). */
+export function digestKeyInfo(repoId, epoch, label) {
+    return concatBytes(lp(GITVAULT_FORMAT), lp(GITVAULT_SUITE), lp(repoId), lp(epoch), lp("digest"), lp(label), lp("L=32"));
+}
+export function deriveDigestKey(kRepo, repoId, epoch, label) {
+    return hkdf(sha256, kRepo, undefined, digestKeyInfo(repoId, epoch, label), 32);
+}
+/** Commitment = HMAC-SHA-256(K_digest(label), JCS(content)), lowercase hex. */
+export function keyedCommitment(kDigest, content) {
+    return bytesToHex(hmac(sha256, kDigest, jcs(content)));
+}
+/** The `"objectset"` content shape: `{oids:[sorted unique lowercase 40-hex]}`. */
+export function objectsetContent(oids) {
+    const unique = [...new Set(oids)];
+    for (const oid of unique) {
+        if (!GITVAULT_OID40_RE.test(oid))
+            fail("GITVAULT_BAD_OID", `not a lowercase 40-hex oid: ${oid}`, "building objectset content");
+    }
+    return { oids: unique.sort() };
+}
+/** True iff an `objectset` content is already in canonical (sorted-unique) order. */
+export function isCanonicalObjectset(content) {
+    const canonical = objectsetContent(content.oids).oids;
+    return canonical.length === content.oids.length && canonical.every((oid, i) => oid === content.oids[i]);
+}
+/** The `"snapshot_oid"` content shape. */
+export function snapshotOidContent(oid) {
+    if (!GITVAULT_OID40_RE.test(oid))
+        fail("GITVAULT_BAD_OID", `not a lowercase 40-hex oid: ${oid}`, "building snapshot_oid content");
+    return { oid, format: "sha1" };
+}
+// ─── Golden preimages (open-id / open-binding) ──────────────────────────────
+/** `"r402s/v0/open-id" ‖ lp(org_id) ‖ lp(repo_id) ‖ lp(client_open_id)`. */
+export function openIdPreimage(orgId, repoId, clientOpenId) {
+    return concatBytes(utf8ToBytes("r402s/v0/open-id"), lp(orgId), lp(repoId), lp(clientOpenId));
+}
+/** `"r402s/v0/open-binding" ‖ lp(client_open_id) ‖ lp(base_head_sha256) ‖ lp_opt(prior) ‖ lp(requested_r2_cap_size_bytes)`. */
+export function openBindingPreimage(clientOpenId, baseHeadSha256, priorCheckpointClaimSetSha256, requestedR2CapSizeBytes) {
+    return concatBytes(utf8ToBytes("r402s/v0/open-binding"), lp(clientOpenId), lp(baseHeadSha256), lpOpt(priorCheckpointClaimSetSha256), lp(requestedR2CapSizeBytes));
+}
+// ─── AEAD frame (XChaCha20-Poly1305) ────────────────────────────────────────
+/** The seven-member frame AAD, as the object JCS serializes. */
+export function frameAad(repoId, objectKind, objectId, epoch) {
+    return { repo_id: repoId, object_kind: objectKind, object_id: objectId, epoch, suite: GITVAULT_SUITE, magic: GITVAULT_FRAME_MAGIC, suite_id: GITVAULT_FRAME_SUITE_ID };
+}
+/**
+ * Seal a plaintext into the §2 frame: `"R402S0"` ‖ `0x01` ‖ nonce(24) ‖ ct‖tag.
+ * `ciphertext_sha256` covers the COMPLETE frame. Callers own the single-use
+ * rule: one object id, one seal — never re-encrypt under an id.
+ */
+export function sealFrame(input) {
+    if (input.k_obj.length !== 32)
+        fail("GITVAULT_BAD_KEY", "k_obj must be 32 bytes", "sealing r402s/v0 frame");
+    if (input.plaintext.length > GITVAULT_MAX_PLAINTEXT_BYTES) {
+        fail("GIT_OBJECT_TOO_LARGE", "plaintext exceeds the 256 MiB per-object cap", "sealing r402s/v0 frame", { size_bytes: String(input.plaintext.length) });
+    }
+    const nonce = input.nonce ?? randomBytes(FRAME_NONCE_BYTES);
+    if (nonce.length !== FRAME_NONCE_BYTES)
+        fail("GITVAULT_BAD_NONCE", "frame nonce must be 24 bytes", "sealing r402s/v0 frame");
+    const aad = jcs(frameAad(input.repo_id, input.object_kind, input.object_id, input.epoch));
+    const ct = xchacha20poly1305(input.k_obj, nonce, aad).encrypt(input.plaintext);
+    const frame = concatBytes(utf8ToBytes(GITVAULT_FRAME_MAGIC), new Uint8Array([GITVAULT_FRAME_SUITE_BYTE]), nonce, ct);
+    return { frame, ciphertext_sha256: sha256Hex(frame), size_bytes: String(frame.length), nonce_hex: bytesToHex(nonce) };
+}
+/**
+ * Open a §2 frame: header checked (magic, suite byte, length), receipt
+ * compared when supplied, then the AEAD opened under the seven-member AAD.
+ * No unverified streaming release — the whole plaintext or nothing.
+ */
+export function openFrame(input) {
+    const { frame } = input;
+    if (input.expected_ciphertext_sha256 !== undefined && sha256Hex(frame) !== input.expected_ciphertext_sha256) {
+        fail("GITVAULT_RECEIPT_MISMATCH", "frame bytes do not hash to the receipt's ciphertext_sha256", "opening r402s/v0 frame", { object_id: input.object_id });
+    }
+    if (frame.length < FRAME_HEADER_BYTES + AEAD_TAG_BYTES) {
+        fail("GITVAULT_FRAME_INVALID", "frame shorter than header + tag", "opening r402s/v0 frame", { object_id: input.object_id });
+    }
+    const magic = new TextDecoder().decode(frame.subarray(0, 6));
+    if (magic !== GITVAULT_FRAME_MAGIC || frame[6] !== GITVAULT_FRAME_SUITE_BYTE) {
+        fail("GITVAULT_FRAME_INVALID", "frame header magic/suite mismatch", "opening r402s/v0 frame", { object_id: input.object_id });
+    }
+    return openFrameWithAad(input.k_obj, frame, jcs(frameAad(input.repo_id, input.object_kind, input.object_id, input.epoch)), input.object_id);
+}
+/**
+ * The AEAD half of {@link openFrame} with the AAD supplied verbatim — the
+ * vector replay uses it to prove every one of the seven AAD members is
+ * authenticated (including the constant `suite`/`magic`/`suite_id` members
+ * that {@link openFrame}'s typed input cannot vary). Header already checked.
+ */
+export function openFrameWithAad(kObj, frame, aad, objectId = "?") {
+    if (frame.length < FRAME_HEADER_BYTES + AEAD_TAG_BYTES) {
+        fail("GITVAULT_FRAME_INVALID", "frame shorter than header + tag", "opening r402s/v0 frame", { object_id: objectId });
+    }
+    const nonce = frame.subarray(7, FRAME_HEADER_BYTES);
+    const ct = frame.subarray(FRAME_HEADER_BYTES);
+    try {
+        return xchacha20poly1305(kObj, nonce, aad).decrypt(ct);
+    }
+    catch {
+        fail("GITVAULT_AEAD_AUTH_FAILURE", "frame failed AEAD authentication", "opening r402s/v0 frame", { object_id: objectId });
+    }
+}
+// ─── HPKE (named implementation: @hpke/core + @hpke/chacha20poly1305) ───────
+let hpkeSuite;
+/** The one `r402s-1` HPKE suite: Base mode, DHKEM(X25519,HKDF-SHA256) 0x0020 / HKDF-SHA256 0x0001 / ChaCha20-Poly1305 0x0003. */
+export function gitvaultHpkeSuite() {
+    hpkeSuite ??= new CipherSuite({ kem: new DhkemX25519HkdfSha256(), kdf: new HkdfSha256(), aead: new Chacha20Poly1305() });
+    return hpkeSuite;
+}
+function toArrayBuffer(bytes) {
+    const copy = new Uint8Array(bytes.length);
+    copy.set(bytes);
+    return copy.buffer;
+}
+/** HPKE `info` (D188): lp("r402s/v0/envelope") ‖ lp("r402s-1") ‖ lp(lowerhex(SHA-256(recipient raw X25519 pubkey))) ‖ lp(created_by). */
+export function envelopeInfo(recipientPublicKeyRaw, createdBy) {
+    return concatBytes(lp(GITVAULT_ENVELOPE_INFO_LABEL), lp(GITVAULT_SUITE), lp(sha256Hex(recipientPublicKeyRaw)), lp(createdBy));
+}
+/** HPKE AAD (D188): JCS of exactly `{repo_id, epoch, recipient_kind:"principal", recipient_fingerprint}`. */
+export function envelopeAad(repoId, epoch, recipientFingerprint) {
+    return { repo_id: repoId, epoch, recipient_kind: "principal", recipient_fingerprint: recipientFingerprint };
+}
+/** Single-shot HPKE seal (Base mode) returning `{enc, ct}`. */
+export async function hpkeSeal(input) {
+    const suite = gitvaultHpkeSuite();
+    const recipientPublicKey = await suite.kem.deserializePublicKey(toArrayBuffer(input.recipient_public_key));
+    const ekm = input.ikm_e ? await suite.kem.deriveKeyPair(toArrayBuffer(input.ikm_e)) : undefined;
+    const sender = await suite.createSenderContext({ recipientPublicKey, info: toArrayBuffer(input.info), ...(ekm ? { ekm } : {}) });
+    const ct = new Uint8Array(await sender.seal(toArrayBuffer(input.plaintext), toArrayBuffer(input.aad)));
+    return { enc: new Uint8Array(sender.enc), ct };
+}
+/** Single-shot HPKE open; any failure is `GITVAULT_HPKE_OPEN_FAILED` (never garbage plaintext). */
+export async function hpkeOpen(input) {
+    const suite = gitvaultHpkeSuite();
+    try {
+        const recipientKey = await suite.kem.deserializePrivateKey(toArrayBuffer(input.recipient_private_key));
+        const recipient = await suite.createRecipientContext({ recipientKey, enc: toArrayBuffer(input.enc), info: toArrayBuffer(input.info) });
+        return new Uint8Array(await recipient.open(toArrayBuffer(input.ct), toArrayBuffer(input.aad)));
+    }
+    catch {
+        fail("GITVAULT_HPKE_OPEN_FAILED", "HPKE open failed — the recipient recovers no key", "opening r402s/v0 key envelope");
+    }
+}
+/** Seal + sign a `key_envelope` for one principal; returns the object with its stored-bytes identity + genesis receipt. */
+export async function sealKeyEnvelope(input) {
+    if (input.k_repo.length !== 32)
+        fail("GITVAULT_BAD_KEY", "K_repo must be 32 bytes", "sealing r402s/v0 key envelope");
+    if (!isValidGitvaultTimestamp(input.created_at))
+        fail("GITVAULT_BAD_TIMESTAMP", "created_at is not an RFC 3339 UTC ms timestamp", "sealing r402s/v0 key envelope");
+    const createdBy = vkFingerprint(input.signer.public_key);
+    const recipientFingerprint = ekFingerprint(input.recipient_public_key);
+    const { enc, ct } = await hpkeSeal({
+        recipient_public_key: input.recipient_public_key,
+        info: envelopeInfo(input.recipient_public_key, createdBy),
+        aad: jcs(envelopeAad(input.repo_id, input.epoch, recipientFingerprint)),
+        plaintext: input.k_repo,
+        ikm_e: input.ikm_e,
+    });
+    const unsigned = {
+        format: GITVAULT_FORMAT,
+        object_kind: "key_envelope",
+        suite: GITVAULT_SUITE,
+        repo_id: input.repo_id,
+        epoch: input.epoch,
+        recipient_kind: "principal",
+        recipient_fingerprint: recipientFingerprint,
+        enc: toBase64url(enc),
+        ct: toBase64url(ct),
+        created_by: createdBy,
+        created_at: input.created_at,
+    };
+    const envelope = signGitvaultObject(unsigned, input.signer.seed);
+    const bytes = storedBytes(envelope);
+    const hash = sha256Hex(bytes);
+    return {
+        envelope,
+        stored_bytes: bytes,
+        stored_bytes_sha256: hash,
+        size_bytes: String(bytes.length),
+        receipt: { object_kind: "key_envelope", epoch: input.epoch, recipient_fingerprint: recipientFingerprint, stored_bytes_sha256: hash, size_bytes: String(bytes.length) },
+    };
+}
+/**
+ * Open a `key_envelope`: exact-scalar checks → signature (strict, domain
+ * `key_envelope`) → path identity (recipient fingerprint = ours) → HPKE open
+ * with the D188 info/AAD. Returns the raw 32-byte K_repo.
+ */
+export async function openKeyEnvelope(input) {
+    const env = input.envelope;
+    if (!GITVAULT_HPKE_CT_RE.test(env.ct) || !GITVAULT_B64U_32_RE.test(env.enc) || !isCanonicalBase64url(env.ct) || !isCanonicalBase64url(env.enc)) {
+        fail("GITVAULT_SCHEMA_REJECT", "key_envelope enc/ct are not the exact scalar lengths", "opening r402s/v0 key envelope");
+    }
+    assertGitvaultSignature(env, input.signer_public_key, "opening r402s/v0 key envelope");
+    const ours = ekFingerprint(input.recipient.public_key);
+    if (env.recipient_fingerprint !== ours || env.recipient_kind !== "principal") {
+        fail("GITVAULT_ENVELOPE_NOT_FOR_RECIPIENT", "key_envelope is addressed to another recipient", "opening r402s/v0 key envelope", { recipient_fingerprint: env.recipient_fingerprint });
+    }
+    const kRepo = await hpkeOpen({
+        recipient_private_key: input.recipient.private_key,
+        enc: fromBase64url(env.enc, "enc"),
+        info: envelopeInfo(input.recipient.public_key, env.created_by),
+        aad: jcs(envelopeAad(env.repo_id, env.epoch, env.recipient_fingerprint)),
+        ct: fromBase64url(env.ct, "ct"),
+    });
+    if (kRepo.length !== 32)
+        fail("GITVAULT_HPKE_OPEN_FAILED", "opened plaintext is not a 32-byte K_repo", "opening r402s/v0 key envelope");
+    return kRepo;
+}
+/** Build + sign a `vault_genesis` (generation 0, epoch 1, the creator's single envelope). */
+export function buildVaultGenesis(input) {
+    const unsigned = {
+        format: GITVAULT_FORMAT,
+        object_kind: "vault_genesis",
+        suite: GITVAULT_SUITE,
+        repo_id: input.repo_id,
+        org_id: input.org_id,
+        project_id: input.project_id,
+        allocation_nonce: input.allocation_nonce,
+        generation: GITVAULT_GENESIS_GENERATION,
+        epoch: GITVAULT_GENESIS_EPOCH,
+        git_object_format: "sha1",
+        creator_signing_pubkey: toBase64url(input.creator_signing.public_key),
+        creator_encryption_pubkey: toBase64url(input.creator_encryption_public_key),
+        envelopes: [input.envelope_receipt],
+        writer_key_id: vkFingerprint(input.creator_signing.public_key),
+        created_at: input.created_at,
+    };
+    return signGitvaultObject(unsigned, input.creator_signing.seed);
+}
+/**
+ * The genesis key bindings (round-10 A6): exactly one envelope at epoch 1 whose
+ * `recipient_fingerprint` is the creator's `ek_`; `writer_key_id` is the
+ * creator's `vk_`; and, when the stored envelope is supplied, the receipt's
+ * hash/size name its stored bytes and its path identity + `created_by` equal
+ * the genesis values. Schema-valid-but-protocol-invalid objects surface here.
+ */
+export function checkGenesisKeyBindings(genesis, storedEnvelope) {
+    const problems = [];
+    if (genesis.envelopes.length !== 1)
+        problems.push("envelope_count");
+    const receipt = genesis.envelopes[0];
+    if (receipt && receipt.epoch !== GITVAULT_GENESIS_EPOCH)
+        problems.push("envelope_epoch");
+    const expectedEk = ekFingerprint(fromBase64url(genesis.creator_encryption_pubkey, "creator_encryption_pubkey"));
+    if (receipt && receipt.recipient_fingerprint !== expectedEk)
+        problems.push("envelope_recipient_fingerprint");
+    const expectedVk = vkFingerprint(fromBase64url(genesis.creator_signing_pubkey, "creator_signing_pubkey"));
+    if (genesis.writer_key_id !== expectedVk)
+        problems.push("writer_key_id");
+    if (storedEnvelope && receipt) {
+        const bytes = storedBytes(storedEnvelope);
+        if (sha256Hex(bytes) !== receipt.stored_bytes_sha256)
+            problems.push("stored_envelope_hash");
+        if (String(bytes.length) !== receipt.size_bytes)
+            problems.push("stored_envelope_size");
+        if (storedEnvelope.repo_id !== genesis.repo_id)
+            problems.push("stored_envelope_repo_id");
+        if (storedEnvelope.epoch !== genesis.epoch)
+            problems.push("stored_envelope_epoch");
+        if (storedEnvelope.recipient_fingerprint !== receipt.recipient_fingerprint)
+            problems.push("stored_envelope_recipient_fingerprint");
+        if (storedEnvelope.created_by !== genesis.writer_key_id)
+            problems.push("stored_envelope_created_by");
+    }
+    return problems;
+}
+/** Build + sign the creator's `recovery_receipt` (emitted at ACTIVE; integrity data, not a secret). */
+export function buildRecoveryReceipt(input) {
+    const unsigned = {
+        format: GITVAULT_FORMAT,
+        object_kind: "recovery_receipt",
+        suite: GITVAULT_SUITE,
+        repo_id: input.repo_id,
+        org_id: input.org_id,
+        project_id: input.project_id,
+        genesis_sha256: input.genesis_sha256,
+        creator_signing_fingerprint: vkFingerprint(input.creator_signing.public_key),
+        creator_encryption_fingerprint: ekFingerprint(input.creator_encryption_public_key),
+    };
+    return signGitvaultObject(unsigned, input.creator_signing.seed);
+}
+/**
+ * Check a recovery receipt against a genesis it claims to pin: the receipt's
+ * signature (under the genesis's creator key), the genesis stored-bytes hash,
+ * and every identity field. A substituted, internally consistent vault fails
+ * on `genesis_sha256` — exactly the fabricated-vault scenario.
+ */
+export function checkRecoveryReceipt(receipt, genesis) {
+    const problems = [];
+    if (!verifyGitvaultObject(receipt, genesis.creator_signing_pubkey))
+        problems.push("signature");
+    if (receipt.genesis_sha256 !== storedBytesSha256(genesis))
+        problems.push("genesis_sha256");
+    if (receipt.repo_id !== genesis.repo_id)
+        problems.push("repo_id");
+    if (receipt.org_id !== genesis.org_id)
+        problems.push("org_id");
+    if (receipt.project_id !== genesis.project_id)
+        problems.push("project_id");
+    if (receipt.creator_signing_fingerprint !== genesis.writer_key_id)
+        problems.push("creator_signing_fingerprint");
+    const expectedEk = ekFingerprint(fromBase64url(genesis.creator_encryption_pubkey, "creator_encryption_pubkey"));
+    if (receipt.creator_encryption_fingerprint !== expectedEk)
+        problems.push("creator_encryption_fingerprint");
+    return problems;
+}
+/**
+ * Field-level checks on an `allocation` for THIS creation attempt (the
+ * control-plane signature itself is verified through the service-key registry,
+ * which task 5.4 wires; pass `service_public_key` once it is pinned).
+ */
+export function checkAllocation(allocation, expected, servicePublicKey) {
+    const problems = [];
+    if (allocation.format !== GITVAULT_FORMAT || allocation.object_kind !== "allocation" || allocation.suite !== GITVAULT_SUITE)
+        problems.push("envelope");
+    if (!GITVAULT_SRC_RE.test(allocation.repo_id))
+        problems.push("repo_id");
+    if (!GITVAULT_HEX32_RE.test(allocation.allocation_nonce))
+        problems.push("allocation_nonce");
+    if (!GITVAULT_HEX16_RE.test(allocation.allocation_generation))
+        problems.push("allocation_generation");
+    if (!GITVAULT_SERVICE_KEY_ID_RE.test(allocation.service_key_id))
+        problems.push("service_key_id");
+    if (allocation.client_creation_id !== expected.client_creation_id)
+        problems.push("client_creation_id");
+    if (allocation.creator_signing_fingerprint !== expected.creator_signing_fingerprint)
+        problems.push("creator_signing_fingerprint");
+    if (allocation.creator_encryption_fingerprint !== expected.creator_encryption_fingerprint)
+        problems.push("creator_encryption_fingerprint");
+    if (allocation.org_id !== expected.org_id)
+        problems.push("org_id");
+    if (allocation.project_id !== expected.project_id)
+        problems.push("project_id");
+    if (!isValidGitvaultTimestamp(allocation.issued_at) || !isValidGitvaultTimestamp(allocation.created_at))
+        problems.push("timestamp");
+    if (servicePublicKey !== undefined && !verifyGitvaultObject(allocation, servicePublicKey))
+        problems.push("signature");
+    return problems;
+}
+export { bytesToHex, hexToBytes };
+//# sourceMappingURL=gitvault.crypto.js.map