@oxy.so/protocol 1.0.0

package/dist/cjs/platform/platform.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Platform Detection — runtime predicates.
+ *
+ * Detects the host runtime WITHOUT importing from 'react-native', so the
+ * protocol's crypto modules can be used in web / Node.js / React Native
+ * environments without bundlers failing on react-native imports.
+ *
+ * Only the two predicates the protocol's platform-crypto loaders need live
+ * here. Richer platform detection (`getPlatformOS`, `isWeb`, `isNative`, …)
+ * is an SDK concern and stays in `@oxy.so/core`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isReactNative = isReactNative;
+exports.isNodeJS = isNodeJS;
+/**
+ * Check if running in React Native.
+ *
+ * Selects the React Native crypto variant (`expo-crypto` /
+ * `expo-secure-store` / async-storage) over the Node/web variant.
+ */
+function isReactNative() {
+    return typeof navigator !== 'undefined' && navigator.product === 'ReactNative';
+}
+/**
+ * Check if running in Node.js.
+ *
+ * Gates use of Node's built-in `crypto` (the synchronous SHA-256 path and
+ * `randomBytes`) and the `await import('node:crypto')` loader.
+ */
+function isNodeJS() {
+    return typeof process !== 'undefined' && process.versions != null && process.versions.node != null;
+}

package/dist/cjs/secp256k1.js

@@ -0,0 +1,148 @@
+"use strict";
+/**
+ * secp256k1 primitives shared by every Oxy runtime.
+ *
+ * This module owns the curve binding and the wire formats used across Oxy:
+ * 32-byte private keys, compressed or uncompressed SEC1 public keys,
+ * RFC 6979 deterministic ECDSA signatures encoded as DER, and the 32-byte
+ * ECDH x-coordinate. Callers never receive a library-specific key object.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeSecp256k1PrivateKey = normalizeSecp256k1PrivateKey;
+exports.isValidSecp256k1PrivateKey = isValidSecp256k1PrivateKey;
+exports.isValidSecp256k1PublicKey = isValidSecp256k1PublicKey;
+exports.generateSecp256k1KeyPair = generateSecp256k1KeyPair;
+exports.deriveSecp256k1PublicKey = deriveSecp256k1PublicKey;
+exports.normalizeSecp256k1PublicKey = normalizeSecp256k1PublicKey;
+exports.signSecp256k1Digest = signSecp256k1Digest;
+exports.verifySecp256k1Digest = verifySecp256k1Digest;
+exports.deriveSecp256k1SharedSecret = deriveSecp256k1SharedSecret;
+const secp256k1_js_1 = require("@noble/curves/secp256k1.js");
+const HEX = /^[0-9a-fA-F]+$/;
+const COMPRESSED_PUBLIC_KEY = /^(02|03)[0-9a-fA-F]{64}$/;
+const UNCOMPRESSED_PUBLIC_KEY = /^04[0-9a-fA-F]{128}$/;
+function bytesToHex(bytes) {
+    let result = "";
+    for (const byte of bytes) {
+        result += byte.toString(16).padStart(2, "0");
+    }
+    return result;
+}
+function hexToBytes(value, label) {
+    if (value.length === 0 || value.length % 2 !== 0 || !HEX.test(value)) {
+        throw new Error(`${label} must be an even-length hexadecimal string`);
+    }
+    const bytes = new Uint8Array(value.length / 2);
+    for (let index = 0; index < bytes.length; index += 1) {
+        bytes[index] = Number.parseInt(value.slice(index * 2, index * 2 + 2), 16);
+    }
+    return bytes;
+}
+/**
+ * Normalize a legacy short/cased scalar to canonical 32-byte lowercase hex.
+ * The scalar must be within the secp256k1 order; zero and overflow are rejected.
+ */
+function normalizeSecp256k1PrivateKey(privateKeyHex) {
+    if (typeof privateKeyHex !== "string" ||
+        privateKeyHex.length === 0 ||
+        privateKeyHex.length > 64 ||
+        !HEX.test(privateKeyHex)) {
+        throw new Error("secp256k1 private key must contain 1 to 64 hexadecimal characters");
+    }
+    const normalized = privateKeyHex.toLowerCase().padStart(64, "0");
+    const privateKey = hexToBytes(normalized, "secp256k1 private key");
+    if (!secp256k1_js_1.secp256k1.utils.isValidSecretKey(privateKey)) {
+        throw new Error("secp256k1 private key is outside the valid scalar range");
+    }
+    return normalized;
+}
+/** True when a value is a valid secp256k1 scalar (legacy short hex accepted). */
+function isValidSecp256k1PrivateKey(privateKeyHex) {
+    try {
+        normalizeSecp256k1PrivateKey(privateKeyHex);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function parsePrivateKey(privateKeyHex) {
+    return hexToBytes(normalizeSecp256k1PrivateKey(privateKeyHex), "secp256k1 private key");
+}
+function parsePublicKey(publicKeyHex) {
+    if (typeof publicKeyHex !== "string" ||
+        (!COMPRESSED_PUBLIC_KEY.test(publicKeyHex) &&
+            !UNCOMPRESSED_PUBLIC_KEY.test(publicKeyHex))) {
+        throw new Error("secp256k1 public key must be a compressed or uncompressed SEC1 hex key");
+    }
+    const publicKey = hexToBytes(publicKeyHex, "secp256k1 public key");
+    // Parsing validates the SEC1 prefix, coordinate range, and curve equation.
+    secp256k1_js_1.secp256k1.Point.fromBytes(publicKey);
+    return publicKey;
+}
+function parseDigest(digestHex) {
+    if (typeof digestHex !== "string" || digestHex.length !== 64) {
+        throw new Error("secp256k1 digest must be exactly 32 bytes of hexadecimal data");
+    }
+    return hexToBytes(digestHex, "secp256k1 digest");
+}
+/** True for a valid compressed or uncompressed SEC1 secp256k1 public key. */
+function isValidSecp256k1PublicKey(publicKeyHex) {
+    try {
+        parsePublicKey(publicKeyHex);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Generate a canonical private key and its uncompressed public key. */
+function generateSecp256k1KeyPair() {
+    const privateKey = secp256k1_js_1.secp256k1.utils.randomSecretKey();
+    return {
+        privateKey: bytesToHex(privateKey),
+        publicKey: bytesToHex(secp256k1_js_1.secp256k1.getPublicKey(privateKey, false)),
+    };
+}
+/** Derive a compressed or uncompressed SEC1 public key from a private scalar. */
+function deriveSecp256k1PublicKey(privateKeyHex, compressed = false) {
+    return bytesToHex(secp256k1_js_1.secp256k1.getPublicKey(parsePrivateKey(privateKeyHex), compressed));
+}
+/** Parse and re-encode a public key in canonical lowercase SEC1 form. */
+function normalizeSecp256k1PublicKey(publicKeyHex, compressed = false) {
+    const point = secp256k1_js_1.secp256k1.Point.fromBytes(parsePublicKey(publicKeyHex));
+    return point.toHex(compressed);
+}
+/**
+ * Sign a 32-byte digest with deterministic RFC 6979 ECDSA and return DER hex.
+ *
+ * `lowS` defaults to false because historical Oxy signatures used elliptic's
+ * default and therefore may occupy either half of the curve order. Verification
+ * accepts both forms; callers that require low-S normalization opt in explicitly.
+ */
+function signSecp256k1Digest(privateKeyHex, digestHex, options = {}) {
+    const signature = secp256k1_js_1.secp256k1.sign(parseDigest(digestHex), parsePrivateKey(privateKeyHex), {
+        lowS: options.lowS ?? false,
+    });
+    return signature.toHex("der");
+}
+/** Verify a DER-encoded ECDSA signature, accepting historical high-S signatures. */
+function verifySecp256k1Digest(publicKeyHex, digestHex, signatureDerHex) {
+    const publicKey = parsePublicKey(publicKeyHex);
+    const digest = parseDigest(digestHex);
+    const signature = hexToBytes(signatureDerHex, "secp256k1 DER signature");
+    // Parse once up front so malformed or non-DER input is rejected explicitly.
+    secp256k1_js_1.secp256k1.Signature.fromBytes(signature, "der");
+    return secp256k1_js_1.secp256k1.verify(signature, digest, publicKey, {
+        format: "der",
+        lowS: false,
+    });
+}
+/** Derive the fixed-width 32-byte ECDH x-coordinate shared secret. */
+function deriveSecp256k1SharedSecret(privateKeyHex, publicKeyHex) {
+    const encodedPoint = secp256k1_js_1.secp256k1.getSharedSecret(parsePrivateKey(privateKeyHex), parsePublicKey(publicKeyHex), true);
+    if (encodedPoint.length !== 33) {
+        throw new Error("secp256k1 ECDH returned an unexpected point encoding");
+    }
+    return encodedPoint.slice(1);
+}

package/dist/cjs/transparency/checkpoint.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Transparency checkpoint — the signed, hash-linked commitment to a tree root.
+ *
+ * A checkpoint is what the operator PUBLISHES: "at `periodEnd` I committed to
+ * `root` over `treeSize` subjects, and the previous checkpoint hashed to
+ * `prevCheckpointHash`". The `prevCheckpointHash` link makes the checkpoint
+ * sequence itself append-only: once any checkpoint is anchored publicly, none of
+ * its ancestors can be rewritten without breaking the chain of hashes.
+ *
+ * ## Why the signature covers ONLY the five fields
+ *
+ * The signing input is derived from exactly `{index, periodEnd, treeSize, root,
+ * prevCheckpointHash}` — never from the surrounding storage document, and never
+ * from other signatures. That is what makes a checkpoint CO-SIGNABLE: the
+ * operator and any number of independent witnesses (e.g. user-run
+ * `@oxy.so/node` deployments) each sign the identical bytes with their own key,
+ * with zero coordination and in any order. Two conflicting roots for one
+ * `index`, each carrying valid signatures, is then transferable proof of
+ * equivocation that needs no cooperation from the operator to demonstrate.
+ *
+ * Extra fields on the object passed in are ignored by design, so handing this a
+ * database document cannot change what was signed.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkpointSigningInput = checkpointSigningInput;
+exports.checkpointHash = checkpointHash;
+exports.signCheckpoint = signCheckpoint;
+exports.verifyCheckpointSignature = verifyCheckpointSignature;
+const canonicalJson_1 = require("../envelope/canonicalJson");
+const recordId_1 = require("../envelope/recordId");
+const sign_1 = require("../envelope/sign");
+const secp256k1_1 = require("../secp256k1");
+/** Domain prefix for checkpoint signing bytes. */
+const CHECKPOINT_PREFIX = 'oxy.transparency.checkpoint.v1:';
+/** The one signature algorithm the protocol emits. */
+const ALG = 'ES256K-DER-SHA256';
+/**
+ * The exact bytes every co-signer signs: the canonical JSON of the five signed
+ * fields under the checkpoint domain prefix. Key order in the input object is
+ * irrelevant; extra properties are dropped.
+ */
+function checkpointSigningInput(fields) {
+    return `${CHECKPOINT_PREFIX}${(0, canonicalJson_1.canonicalize)({
+        index: fields.index,
+        periodEnd: fields.periodEnd,
+        treeSize: fields.treeSize,
+        root: fields.root,
+        prevCheckpointHash: fields.prevCheckpointHash,
+    })}`;
+}
+/**
+ * The content address of a checkpoint — what the NEXT checkpoint's
+ * `prevCheckpointHash` references.
+ */
+async function checkpointHash(fields) {
+    return (0, recordId_1.sha256)(checkpointSigningInput(fields));
+}
+/**
+ * Sign a checkpoint with an explicit private key. Used by the operator and,
+ * identically, by every witness that co-signs the same checkpoint.
+ */
+async function signCheckpoint(fields, privateKeyHex) {
+    return {
+        publicKey: (0, secp256k1_1.deriveSecp256k1PublicKey)(privateKeyHex),
+        alg: ALG,
+        signature: await (0, sign_1.signMessage)(checkpointSigningInput(fields), privateKeyHex),
+    };
+}
+/**
+ * Verify one signature over a checkpoint's signed fields.
+ *
+ * Confirms the signature matches the embedded `publicKey` for exactly these
+ * fields. It does NOT establish that the key belongs to a trusted operator or an
+ * accepted witness — that policy lives with the verifier's key list.
+ */
+async function verifyCheckpointSignature(fields, signature) {
+    return (0, sign_1.verifySignature)(checkpointSigningInput(fields), signature.signature, signature.publicKey);
+}

package/dist/cjs/transparency/tree.js

@@ -0,0 +1,197 @@
+"use strict";
+/**
+ * Transparency Merkle tree — leaf hashing, root computation, and inclusion
+ * proofs over a snapshot of chain heads.
+ *
+ * ## What this is for
+ *
+ * A per-subject hash chain proves nobody edited a record. It does NOT prove the
+ * SERVER didn't serve two different histories to two parties (equivocation), or
+ * quietly drop a record. That gap is closed by committing to every subject's
+ * chain head at once, publishing the commitment, and letting anyone verify that
+ * their own head is inside it — which is exactly what this tree does. The
+ * commitment (the root) is what gets signed into a checkpoint (`./checkpoint`)
+ * and anchored on a public chain.
+ *
+ * ## Shape
+ *
+ * The tree follows RFC 6962 (Certificate Transparency) so the algorithms are
+ * standard and independently reimplementable: leaves and interior nodes are
+ * hashed under DISTINCT domain prefixes (a leaf hash can never be reinterpreted
+ * as an interior node), an odd level splits so the LEFT subtree is the largest
+ * power of two below the size, and a single-leaf tree's root is the leaf itself.
+ *
+ * A built tree keeps every LEVEL, not just its leaves, because that is what
+ * makes serving proofs cheap: {@link inclusionProof} reads siblings straight out
+ * of the levels instead of re-hashing subtrees, so one build amortizes over all
+ * the proofs cut from it (a checkpoint is built once and proved thousands of
+ * times, once per subject that audits it).
+ *
+ * Crucially, {@link verifyInclusionProof} needs only the verifier's OWN leaf,
+ * its index, the tree size, the audit path, and the signed root — never the
+ * other leaves. So a device or node can audit its own history against a
+ * published checkpoint without downloading anyone else's data.
+ *
+ * The leaf order is fixed by {@link buildTransparencyTreeFromHeads}: ascending
+ * by `subjectDid` in UTF-16 code-unit order. Order is part of the commitment, so
+ * every implementation MUST sort identically or the roots diverge.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_TRANSPARENCY_ROOT = void 0;
+exports.transparencyLeafHash = transparencyLeafHash;
+exports.buildTransparencyTree = buildTransparencyTree;
+exports.buildTransparencyTreeFromHeads = buildTransparencyTreeFromHeads;
+exports.inclusionProof = inclusionProof;
+exports.verifyInclusionProof = verifyInclusionProof;
+const recordId_1 = require("../envelope/recordId");
+const canonicalJson_1 = require("../envelope/canonicalJson");
+/** Domain prefix for a leaf hash. Distinct from {@link NODE_PREFIX}. */
+const LEAF_PREFIX = 'oxy.transparency.leaf.v1:';
+/** Domain prefix for an interior node hash. Distinct from {@link LEAF_PREFIX}. */
+const NODE_PREFIX = 'oxy.transparency.node.v1:';
+/** The pre-image of {@link EMPTY_TRANSPARENCY_ROOT}. */
+const EMPTY_PREIMAGE = 'oxy.transparency.empty.v1';
+/**
+ * The root of a tree with zero leaves: `sha256("oxy.transparency.empty.v1")`.
+ *
+ * Hard-coded because hashing is async and this is needed as a value; a Jest
+ * regression test pins it against the live hash of {@link EMPTY_PREIMAGE}.
+ */
+exports.EMPTY_TRANSPARENCY_ROOT = '315338df4bc34de7d057b583a082268016888323c79c0376586406a64f441b1e';
+/**
+ * Hash one subject's head into a leaf.
+ *
+ * The pre-image is the canonical JSON of the three committed fields under the
+ * leaf domain prefix — so a DID containing a delimiter-like character cannot
+ * forge another subject's leaf (JSON escaping makes the encoding unambiguous),
+ * and a leaf can never collide with an interior node.
+ */
+async function transparencyLeafHash(entry) {
+    const preimage = (0, canonicalJson_1.canonicalize)({
+        subjectDid: entry.subjectDid,
+        seq: entry.seq,
+        headRecordId: entry.headRecordId,
+    });
+    return (0, recordId_1.sha256)(`${LEAF_PREFIX}${preimage}`);
+}
+/** Hash an interior node over its ordered children. */
+async function nodeHash(left, right) {
+    return (0, recordId_1.sha256)(`${NODE_PREFIX}${left}${right}`);
+}
+/**
+ * Build a tree over already-hashed leaves, in the given order.
+ *
+ * Levels are built bottom-up, each one pairing the level below and carrying a
+ * trailing odd node up unchanged — which yields exactly RFC 6962's tree, whose
+ * recursive definition splits at the largest power of two below the size.
+ * `transparency.test.ts` pins that equivalence against a direct transcription of
+ * the RFC's MTH for every size up to 40, so the shape can never silently drift.
+ *
+ * The order IS part of the commitment — prefer
+ * {@link buildTransparencyTreeFromHeads}, which owns the canonical ordering.
+ */
+async function buildTransparencyTree(leaves) {
+    const levels = [[...leaves]];
+    let current = levels[0];
+    while (current.length > 1) {
+        const pairCount = Math.floor(current.length / 2);
+        const parents = await Promise.all(Array.from({ length: pairCount }, (_unused, pair) => nodeHash(current[pair * 2], current[pair * 2 + 1])));
+        if (current.length % 2 === 1) {
+            parents.push(current[current.length - 1]);
+        }
+        levels.push(parents);
+        current = parents;
+    }
+    const top = levels[levels.length - 1];
+    return {
+        root: top.length === 1 ? top[0] : exports.EMPTY_TRANSPARENCY_ROOT,
+        treeSize: leaves.length,
+        levels,
+    };
+}
+/**
+ * Build the canonical tree for a snapshot of chain heads.
+ *
+ * Sorts ascending by `subjectDid` in UTF-16 code-unit order — NEVER
+ * `localeCompare`, whose order is locale-dependent and would make two
+ * verifiers compute different roots from identical data.
+ *
+ * Throws on a duplicate `subjectDid`: a snapshot must commit to exactly one head
+ * per subject, and silently keeping one of two would hide the other's history.
+ */
+async function buildTransparencyTreeFromHeads(entries) {
+    const ordered = [...entries].sort((a, b) => a.subjectDid < b.subjectDid ? -1 : a.subjectDid > b.subjectDid ? 1 : 0);
+    const indexBySubject = {};
+    ordered.forEach((entry, index) => {
+        if (indexBySubject[entry.subjectDid] !== undefined) {
+            throw new Error(`Duplicate subject in transparency snapshot: ${entry.subjectDid}`);
+        }
+        indexBySubject[entry.subjectDid] = index;
+    });
+    const leaves = await Promise.all(ordered.map(transparencyLeafHash));
+    return { ...(await buildTransparencyTree(leaves)), indexBySubject };
+}
+/**
+ * The audit path proving `index` is committed in `tree` (RFC 6962 PATH): each
+ * step is the sibling subtree hash, leaf-adjacent first.
+ *
+ * Pure index arithmetic over the tree's levels — no hashing, so cutting a proof
+ * costs O(log n) array reads however large the checkpoint is.
+ */
+function inclusionProof(tree, index) {
+    if (!Number.isInteger(index) || index < 0 || index >= tree.treeSize) {
+        throw new Error(`Leaf index ${index} is outside a tree of ${tree.treeSize} leaves`);
+    }
+    const proof = [];
+    let position = index;
+    for (let level = 0; level < tree.levels.length - 1; level += 1) {
+        const nodes = tree.levels[level];
+        const sibling = position % 2 === 0 ? position + 1 : position - 1;
+        // A trailing odd node is carried up unpaired, so it contributes no step.
+        if (sibling < nodes.length) {
+            proof.push(nodes[sibling]);
+        }
+        position = Math.floor(position / 2);
+    }
+    return proof;
+}
+/**
+ * Verify an audit path against a committed root (RFC 6962 §2.1.1).
+ *
+ * Recomputes the root from the leaf upward using only the path, so the verifier
+ * never needs another subject's data. Returns `false` for every failure mode —
+ * tampered leaf, replayed index, truncated path, foreign root — rather than
+ * throwing, so callers treat auditing as a boolean.
+ */
+async function verifyInclusionProof(check) {
+    const { leaf, index, treeSize, proof, root } = check;
+    if (!Number.isInteger(index) || !Number.isInteger(treeSize)) {
+        return false;
+    }
+    if (index < 0 || treeSize <= 0 || index >= treeSize) {
+        return false;
+    }
+    let fn = index;
+    let sn = treeSize - 1;
+    let computed = leaf;
+    for (const sibling of proof) {
+        if (sn === 0) {
+            // The path claims more levels than the tree has.
+            return false;
+        }
+        if (fn % 2 === 1 || fn === sn) {
+            computed = await nodeHash(sibling, computed);
+            while (fn % 2 === 0 && fn !== 0) {
+                fn = Math.floor(fn / 2);
+                sn = Math.floor(sn / 2);
+            }
+        }
+        else {
+            computed = await nodeHash(computed, sibling);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    // `sn > 0` means the path was truncated before reaching the root.
+    return sn === 0 && computed === root;
+}