@thehonestmachine/oath-core 0.1.0

package/dist/index.js

@@ -0,0 +1,11 @@
+export { ProtocolError } from './errors.js';
+export { bytesToHex, hexToBytes, bytesEqual, concatBytes, utf8Bytes } from './bytes.js';
+export { sha256, sha256Hex } from './hash.js';
+export { canonicalize, canonicalBytes } from './jcs.js';
+export { HANDLE_RE, isHandle, isTimestamp, isHex, isPositiveInteger, isNonNegativeInteger, isNonEmptyString, assertPlainObject, assertKeys, } from './validate.js';
+export { edPublicKey, edSign, edVerify } from './ed25519.js';
+export { EMPTY_ROOT, leafHash, nodeHash, rootFromLeafHashes, inclusionPath, consistencyPath, verifyInclusion, verifyConsistency, } from './merkle.js';
+export { SPEC_VERSION, DEFAULT_MAX_LATENCY_SECONDS, assertValidOathDoc, assertValidUnsignedOathDoc, oathSigningInput, oathHash, signOathDoc, verifyOathSignature, assertValidAmendment, } from './oath.js';
+export { RESERVED_ACTION_TYPES, assertValidEntry, assertValidUnsignedEntry, entrySigningInput, leafBytesOf, entryLeafHash, signEntry, verifyEntrySignature, assertEntryUnderOath, isPrompt, } from './entry.js';
+export { assertValidSth, assertValidUnsignedSth, sthSigningInput, signSth, verifySthSignature, assertValidReceipt, assertValidUnsignedReceipt, receiptSigningInput, signReceipt, verifyReceiptSignature, } from './sth.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACxF,OAAO,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AACxD,OAAO,EACL,SAAS,EACT,QAAQ,EACR,WAAW,EACX,KAAK,EACL,iBAAiB,EACjB,oBAAoB,EACpB,gBAAgB,EAChB,iBAAiB,EACjB,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7D,OAAO,EACL,UAAU,EACV,QAAQ,EACR,QAAQ,EACR,kBAAkB,EAClB,aAAa,EACb,eAAe,EACf,eAAe,EACf,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,YAAY,EACZ,2BAA2B,EAC3B,kBAAkB,EAClB,0BAA0B,EAC1B,gBAAgB,EAChB,QAAQ,EACR,WAAW,EACX,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,wBAAwB,EACxB,iBAAiB,EACjB,WAAW,EACX,aAAa,EACb,SAAS,EACT,oBAAoB,EACpB,oBAAoB,EACpB,QAAQ,GACT,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,eAAe,EACf,OAAO,EACP,kBAAkB,EAClB,kBAAkB,EAClB,0BAA0B,EAC1B,mBAAmB,EACnB,WAAW,EACX,sBAAsB,GACvB,MAAM,UAAU,CAAC"}

package/dist/jcs.d.ts

@@ -0,0 +1,19 @@
+/**
+ * JSON Canonicalization Scheme (RFC 8785).
+ *
+ * Deliberately stricter than JSON.stringify: undefined values, non-plain
+ * objects (Date, Map, class instances), functions, symbols, bigints,
+ * non-finite numbers, and array holes are protocol errors rather than
+ * silent coercions. Trust structures do not get repaired on the way to
+ * being hashed.
+ *
+ * Number and string serialization delegate to JSON.stringify, which
+ * implements exactly the ECMAScript serializations RFC 8785 requires
+ * (including -0 → "0" and lowercase \u escapes for control characters).
+ * Property keys sort by UTF-16 code units, which is the default behavior
+ * of Array.prototype.sort for strings.
+ */
+export declare function canonicalize(value: unknown): string;
+/** UTF-8 bytes of the canonical serialization — what gets hashed and signed. */
+export declare function canonicalBytes(value: unknown): Uint8Array;
+//# sourceMappingURL=jcs.d.ts.map

package/dist/jcs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jcs.d.ts","sourceRoot":"","sources":["../src/jcs.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAoCnD;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAEzD"}

package/dist/jcs.js

@@ -0,0 +1,63 @@
+import { ProtocolError } from './errors.js';
+import { utf8Bytes } from './bytes.js';
+/**
+ * JSON Canonicalization Scheme (RFC 8785).
+ *
+ * Deliberately stricter than JSON.stringify: undefined values, non-plain
+ * objects (Date, Map, class instances), functions, symbols, bigints,
+ * non-finite numbers, and array holes are protocol errors rather than
+ * silent coercions. Trust structures do not get repaired on the way to
+ * being hashed.
+ *
+ * Number and string serialization delegate to JSON.stringify, which
+ * implements exactly the ECMAScript serializations RFC 8785 requires
+ * (including -0 → "0" and lowercase \u escapes for control characters).
+ * Property keys sort by UTF-16 code units, which is the default behavior
+ * of Array.prototype.sort for strings.
+ */
+export function canonicalize(value) {
+    if (value === null)
+        return 'null';
+    switch (typeof value) {
+        case 'boolean':
+            return value ? 'true' : 'false';
+        case 'number':
+            if (!Number.isFinite(value))
+                throw new ProtocolError('cannot canonicalize non-finite number');
+            return JSON.stringify(value);
+        case 'string':
+            return JSON.stringify(value);
+        case 'object':
+            break;
+        default:
+            throw new ProtocolError(`cannot canonicalize value of type ${typeof value}`);
+    }
+    if (Array.isArray(value)) {
+        const parts = [];
+        for (let i = 0; i < value.length; i++) {
+            if (!(i in value))
+                throw new ProtocolError('cannot canonicalize array with holes');
+            parts.push(canonicalize(value[i]));
+        }
+        return '[' + parts.join(',') + ']';
+    }
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null) {
+        throw new ProtocolError('cannot canonicalize non-plain object');
+    }
+    const record = value;
+    const keys = Object.keys(record).sort();
+    const parts = [];
+    for (const key of keys) {
+        const v = record[key];
+        if (v === undefined)
+            throw new ProtocolError(`cannot canonicalize undefined value at key "${key}"`);
+        parts.push(JSON.stringify(key) + ':' + canonicalize(v));
+    }
+    return '{' + parts.join(',') + '}';
+}
+/** UTF-8 bytes of the canonical serialization — what gets hashed and signed. */
+export function canonicalBytes(value) {
+    return utf8Bytes(canonicalize(value));
+}
+//# sourceMappingURL=jcs.js.map

package/dist/jcs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jcs.js","sourceRoot":"","sources":["../src/jcs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAClC,QAAQ,OAAO,KAAK,EAAE,CAAC;QACrB,KAAK,SAAS;YACZ,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;QAClC,KAAK,QAAQ;YACX,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;gBAAE,MAAM,IAAI,aAAa,CAAC,uCAAuC,CAAC,CAAC;YAC9F,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,QAAQ;YACX,OAAO,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;QAC/B,KAAK,QAAQ;YACX,MAAM;QACR;YACE,MAAM,IAAI,aAAa,CAAC,qCAAqC,OAAO,KAAK,EAAE,CAAC,CAAC;IACjF,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,MAAM,KAAK,GAAa,EAAE,CAAC;QAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACtC,IAAI,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC;gBAAE,MAAM,IAAI,aAAa,CAAC,sCAAsC,CAAC,CAAC;YACnF,KAAK,CAAC,IAAI,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACrC,CAAC;QACD,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;IACrC,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QACjD,MAAM,IAAI,aAAa,CAAC,sCAAsC,CAAC,CAAC;IAClE,CAAC;IACD,MAAM,MAAM,GAAG,KAAgC,CAAC;IAChD,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IACxC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,MAAM,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;QACtB,IAAI,CAAC,KAAK,SAAS;YAAE,MAAM,IAAI,aAAa,CAAC,+CAA+C,GAAG,GAAG,CAAC,CAAC;QACpG,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,GAAG,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1D,CAAC;IACD,OAAO,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,GAAG,CAAC;AACrC,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,cAAc,CAAC,KAAc;IAC3C,OAAO,SAAS,CAAC,YAAY,CAAC,KAAK,CAAC,CAAC,CAAC;AACxC,CAAC"}

package/dist/merkle.d.ts

@@ -0,0 +1,35 @@
+/** MTH of the empty tree: SHA-256 of the empty string. */
+export declare const EMPTY_ROOT: Uint8Array;
+export declare function leafHash(leafBytes: Uint8Array): Uint8Array;
+export declare function nodeHash(left: Uint8Array, right: Uint8Array): Uint8Array;
+/** MTH over precomputed leaf hashes (leafHash of each entry's leaf bytes). */
+export declare function rootFromLeafHashes(hashes: readonly Uint8Array[]): Uint8Array;
+/** Audit path for the leaf at `leafIndex` — PATH(m, D[n]) of RFC 6962 §2.1.1. */
+export declare function inclusionPath(leafIndex: number, hashes: readonly Uint8Array[]): Uint8Array[];
+/** Consistency path from `oldSize` to the full list — PROOF(m, D[n]) of RFC 6962 §2.1.2. */
+export declare function consistencyPath(oldSize: number, hashes: readonly Uint8Array[]): Uint8Array[];
+/**
+ * Verify an inclusion proof (spec §6.1). Returns false — never throws — on
+ * any mismatch, so attacker-supplied proofs cannot crash a monitor.
+ */
+export declare function verifyInclusion(options: {
+    leafHash: Uint8Array;
+    leafIndex: number;
+    treeSize: number;
+    auditPath: readonly Uint8Array[];
+    rootHash: Uint8Array;
+}): boolean;
+/**
+ * Verify a consistency proof (spec §6.2): the tree at `newSize` is an
+ * append-only extension of the tree at `oldSize`. Returns false — never
+ * throws — on any mismatch. A false result against two signature-valid
+ * STHs is oathbreaker proof (spec §6.3).
+ */
+export declare function verifyConsistency(options: {
+    oldSize: number;
+    newSize: number;
+    oldRoot: Uint8Array;
+    newRoot: Uint8Array;
+    path: readonly Uint8Array[];
+}): boolean;
+//# sourceMappingURL=merkle.d.ts.map

package/dist/merkle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle.d.ts","sourceRoot":"","sources":["../src/merkle.ts"],"names":[],"mappings":"AAcA,0DAA0D;AAC1D,eAAO,MAAM,UAAU,EAAE,UAAsC,CAAC;AAEhE,wBAAgB,QAAQ,CAAC,SAAS,EAAE,UAAU,GAAG,UAAU,CAE1D;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,UAAU,GAAG,UAAU,CAExE;AAqBD,8EAA8E;AAC9E,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,CAI5E;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,EAAE,CAY5F;AAED,4FAA4F;AAC5F,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,UAAU,EAAE,GAAG,UAAU,EAAE,CAc5F;AAgBD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE;IACvC,QAAQ,EAAE,UAAU,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,SAAS,UAAU,EAAE,CAAC;IACjC,QAAQ,EAAE,UAAU,CAAC;CACtB,GAAG,OAAO,CAsBV;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,UAAU,CAAC;IACpB,OAAO,EAAE,UAAU,CAAC;IACpB,IAAI,EAAE,SAAS,UAAU,EAAE,CAAC;CAC7B,GAAG,OAAO,CAmCV"}

package/dist/merkle.js

@@ -0,0 +1,177 @@
+import { ProtocolError } from './errors.js';
+import { bytesEqual, concatBytes } from './bytes.js';
+import { sha256 } from './hash.js';
+/**
+ * RFC 6962-style Merkle tree (spec §4): SHA-256 with 0x00/0x01 domain
+ * separation, split at the largest power of two strictly less than n.
+ * Sizes and indices use plain number arithmetic (no 32-bit bitwise ops),
+ * so trees are correct up to 2^53 leaves.
+ */
+const LEAF_PREFIX = new Uint8Array([0x00]);
+const NODE_PREFIX = new Uint8Array([0x01]);
+/** MTH of the empty tree: SHA-256 of the empty string. */
+export const EMPTY_ROOT = sha256(new Uint8Array(0));
+export function leafHash(leafBytes) {
+    return sha256(concatBytes(LEAF_PREFIX, leafBytes));
+}
+export function nodeHash(left, right) {
+    return sha256(concatBytes(NODE_PREFIX, left, right));
+}
+function largestPowerOfTwoLessThan(n) {
+    let k = 1;
+    while (k * 2 < n)
+        k *= 2;
+    return k;
+}
+function assertHashList(hashes) {
+    for (const h of hashes) {
+        if (h.length !== 32)
+            throw new ProtocolError('leaf hashes must be 32 bytes');
+    }
+}
+function subRoot(hashes, lo, hi) {
+    const n = hi - lo;
+    if (n === 1)
+        return hashes[lo];
+    const k = largestPowerOfTwoLessThan(n);
+    return nodeHash(subRoot(hashes, lo, lo + k), subRoot(hashes, lo + k, hi));
+}
+/** MTH over precomputed leaf hashes (leafHash of each entry's leaf bytes). */
+export function rootFromLeafHashes(hashes) {
+    assertHashList(hashes);
+    if (hashes.length === 0)
+        return EMPTY_ROOT;
+    return subRoot(hashes, 0, hashes.length);
+}
+/** Audit path for the leaf at `leafIndex` — PATH(m, D[n]) of RFC 6962 §2.1.1. */
+export function inclusionPath(leafIndex, hashes) {
+    assertHashList(hashes);
+    if (!Number.isSafeInteger(leafIndex) || leafIndex < 0 || leafIndex >= hashes.length) {
+        throw new ProtocolError('leaf index out of range');
+    }
+    const path = (m, lo, hi) => {
+        if (hi - lo === 1)
+            return [];
+        const k = largestPowerOfTwoLessThan(hi - lo);
+        if (m < k)
+            return [...path(m, lo, lo + k), subRoot(hashes, lo + k, hi)];
+        return [...path(m - k, lo + k, hi), subRoot(hashes, lo, lo + k)];
+    };
+    return path(leafIndex, 0, hashes.length);
+}
+/** Consistency path from `oldSize` to the full list — PROOF(m, D[n]) of RFC 6962 §2.1.2. */
+export function consistencyPath(oldSize, hashes) {
+    assertHashList(hashes);
+    if (!Number.isSafeInteger(oldSize) || oldSize < 0 || oldSize > hashes.length) {
+        throw new ProtocolError('old size out of range');
+    }
+    if (oldSize === 0 || oldSize === hashes.length)
+        return [];
+    const sub = (m, lo, hi, complete) => {
+        const n = hi - lo;
+        if (m === n)
+            return complete ? [] : [subRoot(hashes, lo, hi)];
+        const k = largestPowerOfTwoLessThan(n);
+        if (m <= k)
+            return [...sub(m, lo, lo + k, complete), subRoot(hashes, lo + k, hi)];
+        return [...sub(m - k, lo + k, hi, false), subRoot(hashes, lo, lo + k)];
+    };
+    return sub(oldSize, 0, hashes.length, true);
+}
+/**
+ * Size/index guard for the VERIFIERS, which must fail closed: a malformed
+ * size makes verification return false, never throw, so an attacker cannot
+ * crash a monitor with a bad proof (spec §6, §6.3). The path GENERATORS,
+ * which operate on trusted local data, throw on bad input instead.
+ */
+function isValidSize(value) {
+    return Number.isSafeInteger(value) && value >= 0;
+}
+function allHashes(path) {
+    return path.every((p) => p.length === 32);
+}
+/**
+ * Verify an inclusion proof (spec §6.1). Returns false — never throws — on
+ * any mismatch, so attacker-supplied proofs cannot crash a monitor.
+ */
+export function verifyInclusion(options) {
+    const { leafHash: leaf, leafIndex, treeSize, auditPath, rootHash } = options;
+    if (!isValidSize(leafIndex) || !isValidSize(treeSize))
+        return false;
+    if (leafIndex >= treeSize || leaf.length !== 32 || !allHashes(auditPath))
+        return false;
+    let fn = leafIndex;
+    let sn = treeSize - 1;
+    let hash = leaf;
+    for (const sibling of auditPath) {
+        if (sn === 0)
+            return false;
+        if (fn % 2 === 1 || fn === sn) {
+            hash = nodeHash(sibling, hash);
+            while (fn !== 0 && fn % 2 === 0) {
+                fn = Math.floor(fn / 2);
+                sn = Math.floor(sn / 2);
+            }
+        }
+        else {
+            hash = nodeHash(hash, sibling);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    return sn === 0 && bytesEqual(hash, rootHash);
+}
+/**
+ * Verify a consistency proof (spec §6.2): the tree at `newSize` is an
+ * append-only extension of the tree at `oldSize`. Returns false — never
+ * throws — on any mismatch. A false result against two signature-valid
+ * STHs is oathbreaker proof (spec §6.3).
+ */
+export function verifyConsistency(options) {
+    const { oldSize, newSize, oldRoot, newRoot, path } = options;
+    if (!isValidSize(oldSize) || !isValidSize(newSize))
+        return false;
+    if (oldSize > newSize || oldRoot.length !== 32 || newRoot.length !== 32 || !allHashes(path)) {
+        return false;
+    }
+    if (oldSize === newSize)
+        return path.length === 0 && bytesEqual(oldRoot, newRoot);
+    if (oldSize === 0)
+        return path.length === 0;
+    const nodes = isPowerOfTwo(oldSize) ? [oldRoot, ...path] : [...path];
+    if (nodes.length === 0)
+        return false;
+    let fn = oldSize - 1;
+    let sn = newSize - 1;
+    while (fn % 2 === 1) {
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    let oldHash = nodes[0];
+    let newHash = nodes[0];
+    for (let i = 1; i < nodes.length; i++) {
+        const c = nodes[i];
+        if (sn === 0)
+            return false;
+        if (fn % 2 === 1 || fn === sn) {
+            oldHash = nodeHash(c, oldHash);
+            newHash = nodeHash(c, newHash);
+            while (fn !== 0 && fn % 2 === 0) {
+                fn = Math.floor(fn / 2);
+                sn = Math.floor(sn / 2);
+            }
+        }
+        else {
+            newHash = nodeHash(newHash, c);
+        }
+        fn = Math.floor(fn / 2);
+        sn = Math.floor(sn / 2);
+    }
+    return sn === 0 && bytesEqual(oldHash, oldRoot) && bytesEqual(newHash, newRoot);
+}
+function isPowerOfTwo(n) {
+    while (n % 2 === 0)
+        n /= 2;
+    return n === 1;
+}
+//# sourceMappingURL=merkle.js.map

package/dist/merkle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merkle.js","sourceRoot":"","sources":["../src/merkle.ts"],"names":[],"mappings":"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"}

package/dist/oath.d.ts

@@ -0,0 +1,34 @@
+import type { OathDoc, UnsignedOathDoc } from './types.js';
+/** The spec_version this implementation conforms to (SPEC.md §12). */
+export declare const SPEC_VERSION = "0.1";
+/** Default confession latency commitment in seconds (SPEC.md §2.2, §8.2). */
+export declare const DEFAULT_MAX_LATENCY_SECONDS = 300;
+/** Validate a complete signed oath document (SPEC.md §2.2). Structural only. */
+export declare function assertValidOathDoc(value: unknown): asserts value is OathDoc;
+/** Validate an oath document that has not been signed yet. */
+export declare function assertValidUnsignedOathDoc(value: unknown): asserts value is UnsignedOathDoc;
+/** Canonical bytes of the document without its signature — the signing input. */
+export declare function oathSigningInput(doc: UnsignedOathDoc | OathDoc): Uint8Array;
+/**
+ * The oath hash: SHA-256 (hex) of the canonical bytes of the complete signed
+ * document. Identifies this oath version everywhere in the protocol.
+ */
+export declare function oathHash(doc: OathDoc): string;
+/**
+ * Sign an oath document. For version 1 the signing seed is the agent's own
+ * key; for an amendment it is the previous version's key (SPEC.md §2.2, §9).
+ */
+export declare function signOathDoc(unsigned: UnsignedOathDoc, signingSeedHex: string): OathDoc;
+/**
+ * Verify an oath document's signature. `signerPubkeyHex` defaults to the
+ * document's own pubkey (correct for version 1); for an amendment pass the
+ * previous version's pubkey.
+ */
+export declare function verifyOathSignature(doc: OathDoc, signerPubkeyHex?: string): boolean;
+/**
+ * Validate that `next` is a conforming amendment of `prev` (SPEC.md §9):
+ * same agent, version incremented by exactly 1, signed by the previous
+ * version's key.
+ */
+export declare function assertValidAmendment(prev: OathDoc, next: OathDoc): void;
+//# sourceMappingURL=oath.d.ts.map

package/dist/oath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oath.d.ts","sourceRoot":"","sources":["../src/oath.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE3D,sEAAsE;AACtE,eAAO,MAAM,YAAY,QAAQ,CAAC;AAElC,6EAA6E;AAC7E,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAiE/C,gFAAgF;AAChF,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAE3E;AAED,8DAA8D;AAC9D,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,eAAe,CAE3F;AAED,iFAAiF;AACjF,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,GAAG,UAAU,CAI3E;AAED;;;GAGG;AACH,wBAAgB,QAAQ,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,CAG7C;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,GAAG,OAAO,CAItF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,eAAe,CAAC,EAAE,MAAM,GAAG,OAAO,CAGnF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,GAAG,IAAI,CAYvE"}

package/dist/oath.js

@@ -0,0 +1,128 @@
+import { ProtocolError } from './errors.js';
+import { canonicalBytes } from './jcs.js';
+import { sha256Hex } from './hash.js';
+import { edSign, edVerify } from './ed25519.js';
+import { assertKeys, assertPlainObject, isHandle, isHex, isNonEmptyString, isPositiveInteger, isTimestamp, } from './validate.js';
+/** The spec_version this implementation conforms to (SPEC.md §12). */
+export const SPEC_VERSION = '0.1';
+/** Default confession latency commitment in seconds (SPEC.md §2.2, §8.2). */
+export const DEFAULT_MAX_LATENCY_SECONDS = 300;
+const REQUIRED = ['spec_version', 'agent', 'version', 'pubkey', 'scope', 'laws', 'created_at'];
+const OPTIONAL = ['display_name', 'commitments'];
+const COMMITMENT_KEYS = ['entries_per_30d', 'max_latency_seconds'];
+function validateOathShape(value, requireSignature) {
+    const doc = assertPlainObject(value, 'oath document');
+    const required = requireSignature ? [...REQUIRED, 'signature'] : REQUIRED;
+    const optional = requireSignature ? OPTIONAL : [...OPTIONAL, 'signature'];
+    assertKeys(doc, 'oath document', required, optional);
+    if (doc['spec_version'] !== SPEC_VERSION) {
+        throw new ProtocolError(`oath document spec_version must be "${SPEC_VERSION}"`);
+    }
+    if (!isHandle(doc['agent']))
+        throw new ProtocolError('oath document agent must be a valid handle');
+    if ('display_name' in doc && !isNonEmptyString(doc['display_name'])) {
+        throw new ProtocolError('oath document display_name must be a non-empty string');
+    }
+    if (!isPositiveInteger(doc['version'])) {
+        throw new ProtocolError('oath document version must be an integer >= 1');
+    }
+    if (!isHex(doc['pubkey'], 32)) {
+        throw new ProtocolError('oath document pubkey must be 32 bytes of lowercase hex');
+    }
+    if (!isNonEmptyString(doc['scope'])) {
+        throw new ProtocolError('oath document scope must be a non-empty string');
+    }
+    if ('commitments' in doc) {
+        const commitments = assertPlainObject(doc['commitments'], 'oath commitments');
+        assertKeys(commitments, 'oath commitments', [], COMMITMENT_KEYS);
+        for (const key of COMMITMENT_KEYS) {
+            if (key in commitments && !isPositiveInteger(commitments[key])) {
+                throw new ProtocolError(`oath commitments ${key} must be an integer >= 1`);
+            }
+        }
+    }
+    validateLaws(doc['laws']);
+    if (!isTimestamp(doc['created_at'])) {
+        throw new ProtocolError('oath document created_at must be an RFC 3339 UTC timestamp');
+    }
+    if (requireSignature && !isHex(doc['signature'], 64)) {
+        throw new ProtocolError('oath document signature must be 64 bytes of lowercase hex');
+    }
+}
+function validateLaws(value) {
+    if (!Array.isArray(value) || value.length === 0) {
+        throw new ProtocolError('oath document laws must be a non-empty array');
+    }
+    value.forEach((law, i) => {
+        const obj = assertPlainObject(law, `law at index ${i}`);
+        assertKeys(obj, `law at index ${i}`, ['n', 'mode', 'text'], []);
+        if (obj['n'] !== i + 1) {
+            throw new ProtocolError('laws must be numbered 1..N consecutively');
+        }
+        if (obj['mode'] !== 'machine' && obj['mode'] !== 'judgment') {
+            throw new ProtocolError('law mode must be "machine" or "judgment"');
+        }
+        if (!isNonEmptyString(obj['text'])) {
+            throw new ProtocolError('law text must be a non-empty string');
+        }
+    });
+}
+/** Validate a complete signed oath document (SPEC.md §2.2). Structural only. */
+export function assertValidOathDoc(value) {
+    validateOathShape(value, true);
+}
+/** Validate an oath document that has not been signed yet. */
+export function assertValidUnsignedOathDoc(value) {
+    validateOathShape(value, false);
+}
+/** Canonical bytes of the document without its signature — the signing input. */
+export function oathSigningInput(doc) {
+    const { signature: _signature, ...unsigned } = doc;
+    assertValidUnsignedOathDoc(unsigned);
+    return canonicalBytes(unsigned);
+}
+/**
+ * The oath hash: SHA-256 (hex) of the canonical bytes of the complete signed
+ * document. Identifies this oath version everywhere in the protocol.
+ */
+export function oathHash(doc) {
+    assertValidOathDoc(doc);
+    return sha256Hex(canonicalBytes(doc));
+}
+/**
+ * Sign an oath document. For version 1 the signing seed is the agent's own
+ * key; for an amendment it is the previous version's key (SPEC.md §2.2, §9).
+ */
+export function signOathDoc(unsigned, signingSeedHex) {
+    assertValidUnsignedOathDoc(unsigned);
+    const signature = edSign(canonicalBytes(unsigned), signingSeedHex);
+    return { ...unsigned, signature };
+}
+/**
+ * Verify an oath document's signature. `signerPubkeyHex` defaults to the
+ * document's own pubkey (correct for version 1); for an amendment pass the
+ * previous version's pubkey.
+ */
+export function verifyOathSignature(doc, signerPubkeyHex) {
+    assertValidOathDoc(doc);
+    return edVerify(doc.signature, oathSigningInput(doc), signerPubkeyHex ?? doc.pubkey);
+}
+/**
+ * Validate that `next` is a conforming amendment of `prev` (SPEC.md §9):
+ * same agent, version incremented by exactly 1, signed by the previous
+ * version's key.
+ */
+export function assertValidAmendment(prev, next) {
+    assertValidOathDoc(prev);
+    assertValidOathDoc(next);
+    if (next.agent !== prev.agent) {
+        throw new ProtocolError('amendment must keep the same agent handle');
+    }
+    if (next.version !== prev.version + 1) {
+        throw new ProtocolError('amendment must increment version by exactly 1');
+    }
+    if (!verifyOathSignature(next, prev.pubkey)) {
+        throw new ProtocolError("amendment signature must verify against the previous version's key");
+    }
+}
+//# sourceMappingURL=oath.js.map

package/dist/oath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"oath.js","sourceRoot":"","sources":["../src/oath.ts"],"names":[],"mappings":"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"}

package/dist/sth.d.ts

@@ -0,0 +1,16 @@
+import type { Receipt, SignedTreeHead, UnsignedReceipt, UnsignedTreeHead } from './types.js';
+/** Validate a signed tree head (SPEC.md §5). Structural only. */
+export declare function assertValidSth(value: unknown): asserts value is SignedTreeHead;
+export declare function assertValidUnsignedSth(value: unknown): asserts value is UnsignedTreeHead;
+/** Canonical bytes of the STH without its signature — the signing input. */
+export declare function sthSigningInput(sth: UnsignedTreeHead | SignedTreeHead): Uint8Array;
+export declare function signSth(unsigned: UnsignedTreeHead, ledgerSeedHex: string): SignedTreeHead;
+export declare function verifySthSignature(sth: SignedTreeHead, ledgerPubkeyHex: string): boolean;
+/** Validate a receipt (SPEC.md §11.3). Structural only. */
+export declare function assertValidReceipt(value: unknown): asserts value is Receipt;
+export declare function assertValidUnsignedReceipt(value: unknown): asserts value is UnsignedReceipt;
+/** Canonical bytes of the receipt without its signature — the signing input. */
+export declare function receiptSigningInput(receipt: UnsignedReceipt | Receipt): Uint8Array;
+export declare function signReceipt(unsigned: UnsignedReceipt, ledgerSeedHex: string): Receipt;
+export declare function verifyReceiptSignature(receipt: Receipt, ledgerPubkeyHex: string): boolean;
+//# sourceMappingURL=sth.d.ts.map

package/dist/sth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sth.d.ts","sourceRoot":"","sources":["../src/sth.ts"],"names":[],"mappings":"AAcA,OAAO,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAiC7F,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,cAAc,CAE9E;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,gBAAgB,CAExF;AAED,4EAA4E;AAC5E,wBAAgB,eAAe,CAAC,GAAG,EAAE,gBAAgB,GAAG,cAAc,GAAG,UAAU,CAIlF;AAED,wBAAgB,OAAO,CAAC,QAAQ,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,GAAG,cAAc,CAIzF;AAED,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAGxF;AA4BD,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,OAAO,CAE3E;AAED,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,KAAK,IAAI,eAAe,CAE3F;AAED,gFAAgF;AAChF,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,GAAG,UAAU,CAIlF;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAIrF;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,GAAG,OAAO,CAGzF"}

package/dist/sth.js

@@ -0,0 +1,95 @@
+import { ProtocolError } from './errors.js';
+import { canonicalBytes } from './jcs.js';
+import { bytesToHex } from './bytes.js';
+import { EMPTY_ROOT } from './merkle.js';
+import { edSign, edVerify } from './ed25519.js';
+import { assertKeys, assertPlainObject, isHex, isNonEmptyString, isNonNegativeInteger, isPositiveInteger, isTimestamp, } from './validate.js';
+const EMPTY_ROOT_HEX = bytesToHex(EMPTY_ROOT);
+function validateSthShape(value, requireSignature) {
+    const sth = assertPlainObject(value, 'signed tree head');
+    const required = ['ledger', 'tree_size', 'root_hash', 'timestamp'];
+    assertKeys(sth, 'signed tree head', requireSignature ? [...required, 'signature'] : required, requireSignature ? [] : ['signature']);
+    if (!isNonEmptyString(sth['ledger'])) {
+        throw new ProtocolError('signed tree head ledger must be a non-empty string');
+    }
+    if (!isNonNegativeInteger(sth['tree_size'])) {
+        throw new ProtocolError('signed tree head tree_size must be a non-negative integer');
+    }
+    if (!isHex(sth['root_hash'], 32)) {
+        throw new ProtocolError('signed tree head root_hash must be 32 bytes of lowercase hex');
+    }
+    if (sth['tree_size'] === 0 && sth['root_hash'] !== EMPTY_ROOT_HEX) {
+        throw new ProtocolError('an empty tree has exactly one possible root hash (SPEC.md §4)');
+    }
+    if (!isTimestamp(sth['timestamp'])) {
+        throw new ProtocolError('signed tree head timestamp must be an RFC 3339 UTC timestamp');
+    }
+    if (requireSignature && !isHex(sth['signature'], 64)) {
+        throw new ProtocolError('signed tree head signature must be 64 bytes of lowercase hex');
+    }
+}
+/** Validate a signed tree head (SPEC.md §5). Structural only. */
+export function assertValidSth(value) {
+    validateSthShape(value, true);
+}
+export function assertValidUnsignedSth(value) {
+    validateSthShape(value, false);
+}
+/** Canonical bytes of the STH without its signature — the signing input. */
+export function sthSigningInput(sth) {
+    const { signature: _signature, ...unsigned } = sth;
+    assertValidUnsignedSth(unsigned);
+    return canonicalBytes(unsigned);
+}
+export function signSth(unsigned, ledgerSeedHex) {
+    assertValidUnsignedSth(unsigned);
+    const signature = edSign(canonicalBytes(unsigned), ledgerSeedHex);
+    return { ...unsigned, signature };
+}
+export function verifySthSignature(sth, ledgerPubkeyHex) {
+    assertValidSth(sth);
+    return edVerify(sth.signature, sthSigningInput(sth), ledgerPubkeyHex);
+}
+function validateReceiptShape(value, requireSignature) {
+    const receipt = assertPlainObject(value, 'receipt');
+    const required = ['ledger', 'leaf_hash', 'received_at', 'mmd_seconds'];
+    assertKeys(receipt, 'receipt', requireSignature ? [...required, 'signature'] : required, requireSignature ? [] : ['signature']);
+    if (!isNonEmptyString(receipt['ledger'])) {
+        throw new ProtocolError('receipt ledger must be a non-empty string');
+    }
+    if (!isHex(receipt['leaf_hash'], 32)) {
+        throw new ProtocolError('receipt leaf_hash must be 32 bytes of lowercase hex');
+    }
+    if (!isTimestamp(receipt['received_at'])) {
+        throw new ProtocolError('receipt received_at must be an RFC 3339 UTC timestamp');
+    }
+    if (!isPositiveInteger(receipt['mmd_seconds'])) {
+        throw new ProtocolError('receipt mmd_seconds must be an integer >= 1');
+    }
+    if (requireSignature && !isHex(receipt['signature'], 64)) {
+        throw new ProtocolError('receipt signature must be 64 bytes of lowercase hex');
+    }
+}
+/** Validate a receipt (SPEC.md §11.3). Structural only. */
+export function assertValidReceipt(value) {
+    validateReceiptShape(value, true);
+}
+export function assertValidUnsignedReceipt(value) {
+    validateReceiptShape(value, false);
+}
+/** Canonical bytes of the receipt without its signature — the signing input. */
+export function receiptSigningInput(receipt) {
+    const { signature: _signature, ...unsigned } = receipt;
+    assertValidUnsignedReceipt(unsigned);
+    return canonicalBytes(unsigned);
+}
+export function signReceipt(unsigned, ledgerSeedHex) {
+    assertValidUnsignedReceipt(unsigned);
+    const signature = edSign(canonicalBytes(unsigned), ledgerSeedHex);
+    return { ...unsigned, signature };
+}
+export function verifyReceiptSignature(receipt, ledgerPubkeyHex) {
+    assertValidReceipt(receipt);
+    return edVerify(receipt.signature, receiptSigningInput(receipt), ledgerPubkeyHex);
+}
+//# sourceMappingURL=sth.js.map