@motebit/crypto 0.8.0 → 1.0.0

package/dist/artifacts.js

@@ -5,38 +5,205 @@
  * artifacts. A third party needs these to produce valid signed artifacts that
  * any verifier will accept.
  *
- * Moved from BSL @motebit/crypto to MIT @motebit/crypto.
+ * Moved from BSL @motebit/encryption to the permissive floor in @motebit/crypto (Apache-2.0).
  */
-import { canonicalJson, ed25519Sign, ed25519Verify, toBase64Url, fromBase64Url, bytesToHex, hexToBytes, hash, isScopeNarrowed, } from "./signing.js";
+import { canonicalJson, canonicalSha256, toBase64Url, fromBase64Url, bytesToHex, hexToBytes, hash, isScopeNarrowed, signBySuite, verifyBySuite, } from "./signing.js";
 /**
- * Sign an execution receipt. Produces a canonical JSON representation
- * of all fields except `signature`, signs it with Ed25519, and sets
- * the `signature` field to the base64url-encoded result.
+ * Diagnostic flag for cryptographic-artifact debugging. Reads from
+ * `process.env.DEBUG_RECEIPT_BYTES` in Node and from
+ * `globalThis.__motebit_debug_receipt_bytes` in browsers. When truthy,
+ * `signExecutionReceipt` and `verifyExecutionReceipt*` log the canonical
+ * SHA-256 and a short preview of the canonical JSON, so a verification
+ * mismatch can be byte-diffed against the producer's intended bytes
+ * without re-instrumenting either end. Off by default; zero overhead when
+ * disabled.
+ *
+ * Pattern source: NIST SP 800-57 §5.4 — minimum observability for any
+ * signed-artifact pipeline that crosses a process boundary.
+ */
+function isReceiptDebugEnabled() {
+    const g = globalThis;
+    if (g.__motebit_debug_receipt_bytes === true)
+        return true;
+    const flag = g.process?.env?.DEBUG_RECEIPT_BYTES;
+    return flag === "1" || flag === "true";
+}
+/** The one suite ExecutionReceipts sign under today. */
+export const EXECUTION_RECEIPT_SUITE = "motebit-jcs-ed25519-b64-v1";
+/**
+ * Sign an execution receipt. Stamps the cryptosuite discriminator into
+ * the receipt body, canonicalizes with JCS, dispatches the primitive
+ * signature through `signBySuite`, and encodes as base64url per the
+ * suite's rules.
+ *
+ * Callers pass a receipt *without* `signature` or `suite`; the signer
+ * owns both. The returned object is a full `SignableReceipt` with
+ * `suite` and `signature` set.
  */
 export async function signExecutionReceipt(receipt, privateKey, publicKey) {
     // Embed the public key for portable verification (no relay lookup needed)
-    const body = publicKey ? { ...receipt, public_key: bytesToHex(publicKey) } : receipt;
+    // and stamp the suite into the signed body.
+    const withKey = publicKey ? { ...receipt, public_key: bytesToHex(publicKey) } : receipt;
+    const body = { ...withKey, suite: EXECUTION_RECEIPT_SUITE };
     const canonical = canonicalJson(body);
     const message = new TextEncoder().encode(canonical);
-    const sig = await ed25519Sign(message, privateKey);
-    return { ...body, signature: toBase64Url(sig) };
+    const sig = await signBySuite(EXECUTION_RECEIPT_SUITE, message, privateKey);
+    const signed = { ...body, signature: toBase64Url(sig) };
+    if (isReceiptDebugEnabled()) {
+        const sha = await canonicalSha256(body);
+        // eslint-disable-next-line no-console -- opt-in diagnostic, off by default
+        console.debug(`[motebit/crypto] signExecutionReceipt canonical_sha256=${sha} chain=${Array.isArray(body.delegation_receipts)
+            ? body.delegation_receipts.length
+            : 0} bytes=${canonical.length}`);
+    }
+    // Freeze the returned signed receipt. Receipts are immutable evidence by
+    // contract — the type system already says `readonly` is the intent. Freeze
+    // makes the runtime enforce it: any post-sign mutation throws TypeError
+    // at the mutation site (Node 20 strict mode, browser strict by default),
+    // catching the bug at the producer instead of as wire-corruption noise on
+    // the consumer five hops downstream.
+    return Object.freeze(signed);
 }
 /**
- * Verify an execution receipt's Ed25519 signature.
- * Reconstructs the canonical JSON from all fields except `signature`
- * and verifies against the provided public key.
+ * Verify an execution receipt's signature by dispatching through the
+ * recipe named in `receipt.suite`. Reconstructs the canonical JSON from
+ * all fields except `signature` (the suite IS part of the signed body,
+ * so tampering with it breaks verification).
+ *
+ * Fail-closed on:
+ *   - unknown suite value (dispatcher rejects)
+ *   - suite other than `EXECUTION_RECEIPT_SUITE` (until a PQ variant
+ *     lands in the registry, this narrow check rejects any other
+ *     value — widens when the union widens)
+ *   - base64url decode errors
+ *   - primitive-level verification failure
  */
 export async function verifyExecutionReceipt(receipt, publicKey) {
+    if (receipt.suite !== EXECUTION_RECEIPT_SUITE) {
+        if (isReceiptDebugEnabled()) {
+            // eslint-disable-next-line no-console -- opt-in diagnostic
+            console.debug(`[motebit/crypto] verifyExecutionReceipt EARLY_RETURN suite_mismatch actual=${JSON.stringify(receipt.suite)} expected=${JSON.stringify(EXECUTION_RECEIPT_SUITE)}`);
+        }
+        return false;
+    }
     const { signature, ...body } = receipt;
     const canonical = canonicalJson(body);
     const message = new TextEncoder().encode(canonical);
+    let valid = false;
     try {
         const sig = fromBase64Url(signature);
-        return await ed25519Verify(sig, message, publicKey);
+        valid = await verifyBySuite(receipt.suite, message, sig, publicKey);
+    }
+    catch {
+        valid = false;
+    }
+    if (isReceiptDebugEnabled()) {
+        const sha = await canonicalSha256(body);
+        // eslint-disable-next-line no-console -- opt-in diagnostic, off by default
+        console.debug(`[motebit/crypto] verifyExecutionReceipt canonical_sha256=${sha} valid=${valid} bytes=${canonical.length}`);
+    }
+    return valid;
+}
+export async function verifyExecutionReceiptDetailed(receipt, publicKey) {
+    if (receipt.suite !== EXECUTION_RECEIPT_SUITE) {
+        const { signature: _drop, ...bodyForHash } = receipt;
+        return {
+            valid: false,
+            canonical_sha256: await canonicalSha256(bodyForHash),
+            canonical_preview: canonicalJson(bodyForHash).slice(0, 256),
+            reason: "wrong_suite",
+        };
+    }
+    const { signature, ...body } = receipt;
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    let sigBytes;
+    try {
+        sigBytes = fromBase64Url(signature);
     }
     catch {
+        return {
+            valid: false,
+            canonical_sha256: await hash(message),
+            canonical_preview: canonical.slice(0, 256),
+            reason: "bad_base64",
+        };
+    }
+    const valid = await verifyBySuite(receipt.suite, message, sigBytes, publicKey);
+    return {
+        valid,
+        canonical_sha256: await hash(message),
+        canonical_preview: canonical.slice(0, 256),
+        reason: valid ? "ok" : "ed25519_mismatch",
+    };
+}
+/** The one suite ToolInvocationReceipts sign under today. */
+export const TOOL_INVOCATION_RECEIPT_SUITE = "motebit-jcs-ed25519-b64-v1";
+/**
+ * Compute the `args_hash` / `result_hash` for a tool-invocation receipt.
+ * JCS-canonicalizes the value, then SHA-256s the UTF-8 bytes. Returns
+ * hex. Use on both sides of the wire: the producer computes the hash at
+ * sign time; a verifier with the raw value recomputes and matches.
+ *
+ * For `string` values (e.g., a plain result string), the canonicalization
+ * is the value itself wrapped with JSON escaping rules; `canonicalJson`
+ * handles both scalar and object inputs uniformly.
+ */
+export async function hashToolPayload(value) {
+    return canonicalSha256(value);
+}
+/**
+ * Sign a tool-invocation receipt. Mirrors `signExecutionReceipt`:
+ * stamps the cryptosuite into the body, canonicalizes with JCS,
+ * dispatches through `signBySuite`, and encodes as base64url.
+ *
+ * Callers pass a receipt *without* `signature` or `suite`; the signer
+ * owns both. Also embeds the public key (hex) so the receipt is
+ * independently verifiable with no relay lookup.
+ */
+export async function signToolInvocationReceipt(receipt, privateKey, publicKey) {
+    const withKey = publicKey ? { ...receipt, public_key: bytesToHex(publicKey) } : receipt;
+    const body = { ...withKey, suite: TOOL_INVOCATION_RECEIPT_SUITE };
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    const sig = await signBySuite(TOOL_INVOCATION_RECEIPT_SUITE, message, privateKey);
+    const signed = { ...body, signature: toBase64Url(sig) };
+    if (isReceiptDebugEnabled()) {
+        const sha = await canonicalSha256(body);
+        // eslint-disable-next-line no-console -- opt-in diagnostic, off by default
+        console.debug(`[motebit/crypto] signToolInvocationReceipt canonical_sha256=${sha} tool=${body.tool_name} bytes=${canonical.length}`);
+    }
+    return Object.freeze(signed);
+}
+/**
+ * Verify a tool-invocation receipt. Fails closed on unknown suite, bad
+ * base64, or signature mismatch — same rules as `verifyExecutionReceipt`.
+ */
+export async function verifyToolInvocationReceipt(receipt, publicKey) {
+    if (receipt.suite !== TOOL_INVOCATION_RECEIPT_SUITE) {
+        if (isReceiptDebugEnabled()) {
+            // eslint-disable-next-line no-console -- opt-in diagnostic
+            console.debug(`[motebit/crypto] verifyToolInvocationReceipt EARLY_RETURN suite_mismatch actual=${JSON.stringify(receipt.suite)} expected=${JSON.stringify(TOOL_INVOCATION_RECEIPT_SUITE)}`);
+        }
         return false;
     }
+    const { signature, ...body } = receipt;
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    let valid = false;
+    try {
+        const sig = fromBase64Url(signature);
+        valid = await verifyBySuite(receipt.suite, message, sig, publicKey);
+    }
+    catch {
+        valid = false;
+    }
+    if (isReceiptDebugEnabled()) {
+        const sha = await canonicalSha256(body);
+        // eslint-disable-next-line no-console -- opt-in diagnostic, off by default
+        console.debug(`[motebit/crypto] verifyToolInvocationReceipt canonical_sha256=${sha} valid=${valid} bytes=${canonical.length}`);
+    }
+    return valid;
 }
 /**
  * Construct, canonicalize, and sign a sovereign payment receipt with
@@ -61,6 +228,7 @@ export async function signSovereignPaymentReceipt(input, privateKey, publicKey)
         prompt_hash: input.prompt_hash,
         result_hash: input.result_hash,
         // relay_task_id intentionally omitted — sovereign rail, no relay binding
+        // suite is stamped by signExecutionReceipt
     };
     return signExecutionReceipt(receipt, privateKey, publicKey);
 }
@@ -137,25 +305,41 @@ export async function verifyReceiptSequence(chain) {
     }
     return { valid: true };
 }
+/** The one suite DelegationTokens sign under today. */
+export const DELEGATION_TOKEN_SUITE = "motebit-jcs-ed25519-b64-v1";
 /**
  * Sign a delegation token. The delegator authorizes the delegate to act
- * within the given scope. The signature covers all fields except `signature`.
+ * within the given scope. Stamps the cryptosuite into the signed body,
+ * dispatches the primitive signature through `signBySuite`.
+ *
+ * Callers pass the token without `signature` or `suite`; the signer owns
+ * both. Public keys must already be hex-encoded — this signer does not
+ * transcode, so the input carries the same encoding the output will.
  */
 export async function signDelegation(delegation, delegatorPrivateKey) {
-    const canonical = canonicalJson(delegation);
+    const body = { ...delegation, suite: DELEGATION_TOKEN_SUITE };
+    const canonical = canonicalJson(body);
     const message = new TextEncoder().encode(canonical);
-    const sig = await ed25519Sign(message, delegatorPrivateKey);
-    return { ...delegation, signature: toBase64Url(sig) };
+    const sig = await signBySuite(DELEGATION_TOKEN_SUITE, message, delegatorPrivateKey);
+    return { ...body, signature: toBase64Url(sig) };
 }
 /**
  * Verify a delegation token's signature and (optionally) expiration.
  *
+ * Rejects fail-closed on:
+ *   - missing or unknown `suite` value (anything other than `DELEGATION_TOKEN_SUITE`)
+ *   - expired token (unless `options.checkExpiry === false`)
+ *   - malformed hex public key or base64url signature
+ *   - primitive-level verification failure
+ *
  * @param delegation - The delegation token to verify
  * @param options.checkExpiry - If true (default), reject expired tokens. Pass false
  *   only when verifying historical chains where expiration is irrelevant.
  * @param options.now - Current time in ms (default: Date.now()). For testing.
  */
 export async function verifyDelegation(delegation, options) {
+    if (delegation.suite !== DELEGATION_TOKEN_SUITE)
+        return false;
     const checkExpiry = options?.checkExpiry ?? true;
     if (checkExpiry) {
         const now = options?.now ?? Date.now();
@@ -166,9 +350,9 @@ export async function verifyDelegation(delegation, options) {
     const canonical = canonicalJson(body);
     const message = new TextEncoder().encode(canonical);
     try {
-        const pubKey = fromBase64Url(delegation.delegator_public_key);
+        const pubKey = hexToBytes(delegation.delegator_public_key);
         const sig = fromBase64Url(signature);
-        return await ed25519Verify(sig, message, pubKey);
+        return await verifyBySuite(delegation.suite, message, sig, pubKey);
     }
     catch {
         return false;
@@ -219,14 +403,384 @@ export async function verifyDelegationChain(chain) {
     }
     return { valid: true };
 }
+/** The one suite AdjudicatorVotes sign under today — matches spec/dispute-v1.md §6.4. */
+export const ADJUDICATOR_VOTE_SUITE = "motebit-jcs-ed25519-b64-v1";
+/** The one suite DisputeResolutions sign under today — matches spec/dispute-v1.md §6.4. */
+export const DISPUTE_RESOLUTION_SUITE = "motebit-jcs-ed25519-b64-v1";
+/** The one suite DisputeRequest filings sign under today — spec/dispute-v1.md §4.2. */
+export const DISPUTE_REQUEST_SUITE = "motebit-jcs-ed25519-b64-v1";
+/** The one suite DisputeEvidence submissions sign under today — spec/dispute-v1.md §5.2. */
+export const DISPUTE_EVIDENCE_SUITE = "motebit-jcs-ed25519-b64-v1";
+/** The one suite DisputeAppeal filings sign under today — spec/dispute-v1.md §8.2. */
+export const DISPUTE_APPEAL_SUITE = "motebit-jcs-ed25519-b64-v1";
+/**
+ * Sign a federation peer's adjudication vote. The `dispute_id` IS part
+ * of the signed body — spec §6.5 Foundation Law: "Each AdjudicatorVote
+ * signature MUST cover its `dispute_id`. Votes are not portable across
+ * disputes — a malicious adjudicator collecting old votes from other
+ * disputes cannot stuff them into a new resolution because the
+ * dispute_id binding breaks the signature."
+ *
+ * Callers pass the body without `signature` or `suite`; the signer owns
+ * both.
+ */
+export async function signAdjudicatorVote(vote, peerPrivateKey) {
+    const body = { ...vote, suite: ADJUDICATOR_VOTE_SUITE };
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    const sig = await signBySuite(ADJUDICATOR_VOTE_SUITE, message, peerPrivateKey);
+    return { ...body, signature: toBase64Url(sig) };
+}
+/**
+ * Verify an adjudicator vote against the voting peer's public key.
+ * Fail-closed on unknown suite, base64url decode error, and primitive
+ * verification failure. Matching of `peer_id` to a legitimate federation
+ * peer is the caller's responsibility (this function verifies the
+ * signature; peer-membership is a trust decision).
+ */
+export async function verifyAdjudicatorVote(vote, peerPublicKey) {
+    if (vote.suite !== ADJUDICATOR_VOTE_SUITE)
+        return false;
+    const { signature, ...body } = vote;
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    try {
+        const sig = fromBase64Url(signature);
+        return await verifyBySuite(vote.suite, message, sig, peerPublicKey);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Sign a dispute resolution. For single-relay adjudication
+ * (`adjudicator_votes: []`) the relay signs with its own identity key.
+ * For federation resolutions, the leader collects signed
+ * `AdjudicatorVote` entries, then signs the aggregate.
+ *
+ * Callers pass the body without `signature` or `suite`; the signer
+ * owns both.
+ *
+ * Per spec §6.5 Foundation Law, a federation resolution MUST include
+ * individual `AdjudicatorVote` entries — aggregated-only verdicts are
+ * rejected. This signer does not enforce that at sign time (the
+ * orchestrator decides whether federation is required); the verifier
+ * re-checks every embedded vote signature when the array is non-empty.
+ */
+export async function signDisputeResolution(resolution, adjudicatorPrivateKey) {
+    const body = { ...resolution, suite: DISPUTE_RESOLUTION_SUITE };
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    const sig = await signBySuite(DISPUTE_RESOLUTION_SUITE, message, adjudicatorPrivateKey);
+    return { ...body, signature: toBase64Url(sig) };
+}
+/**
+ * Verify a dispute resolution. Two layers:
+ *   1. Outer signature verifies against `adjudicatorPublicKey`.
+ *   2. When `adjudicator_votes.length > 0`, every embedded
+ *      AdjudicatorVote's signature is re-checked against the
+ *      corresponding `peerKeys` entry (lookup by `peer_id`). Per §6.5,
+ *      aggregated-only verdicts without individual peer signatures are
+ *      rejected — a missing peer key in the lookup is treated as a
+ *      verification failure.
+ *
+ * Fail-closed on unknown suite, decode errors, primitive verification
+ * failures, any missing peer key, and any invalid embedded vote.
+ */
+export async function verifyDisputeResolution(resolution, adjudicatorPublicKey, peerKeys) {
+    if (resolution.suite !== DISPUTE_RESOLUTION_SUITE)
+        return false;
+    const { signature, ...body } = resolution;
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    try {
+        const sig = fromBase64Url(signature);
+        const outerValid = await verifyBySuite(resolution.suite, message, sig, adjudicatorPublicKey);
+        if (!outerValid)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    // Federation resolutions must carry signed peer votes. Verify every
+    // one against the caller-supplied peer-key map. Missing map or
+    // missing peer entry is a verification failure, not a pass-through.
+    if (resolution.adjudicator_votes.length > 0) {
+        if (!peerKeys)
+            return false;
+        for (const vote of resolution.adjudicator_votes) {
+            if (vote.dispute_id !== resolution.dispute_id)
+                return false;
+            const peerKey = peerKeys.get(vote.peer_id);
+            if (!peerKey)
+                return false;
+            const voteValid = await verifyAdjudicatorVote(vote, peerKey);
+            if (!voteValid)
+                return false;
+        }
+    }
+    return true;
+}
+/**
+ * Sign a DisputeRequest. Filing party signs over canonical JSON of
+ * every field except `signature`. The relay verifies against the
+ * filer's registered public key before accepting the filing — without
+ * the signature, anyone could file a dispute as anyone (foundation
+ * law §4.4: filing party must be a direct party to the task; without
+ * the signature binding, the relay cannot enforce that). Callers pass
+ * the body without `signature` or `suite`; the signer owns both.
+ */
+export async function signDisputeRequest(request, filerPrivateKey) {
+    const body = { ...request, suite: DISPUTE_REQUEST_SUITE };
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    const sig = await signBySuite(DISPUTE_REQUEST_SUITE, message, filerPrivateKey);
+    return { ...body, signature: toBase64Url(sig) };
+}
+/**
+ * Verify a DisputeRequest against the filing party's public key.
+ * Fail-closed on unknown suite, base64url decode error, and primitive
+ * verification failure. Eligibility checks (`filed_by` is a real party
+ * to `task_id`, trust threshold, evidence_refs non-empty) are the
+ * caller's responsibility — this verifies the signature only.
+ */
+export async function verifyDisputeRequest(request, filerPublicKey) {
+    if (request.suite !== DISPUTE_REQUEST_SUITE)
+        return false;
+    const { signature, ...body } = request;
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    try {
+        const sig = fromBase64Url(signature);
+        return await verifyBySuite(request.suite, message, sig, filerPublicKey);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Sign a DisputeEvidence submission. The submitting party — either
+ * the dispute's filer or respondent — signs over the canonical JSON
+ * of every field except `signature`. The relay verifies against the
+ * submitter's registered public key (foundation law §5.4: evidence
+ * must be cryptographically verifiable; unsigned/tampered evidence
+ * is rejected).
+ */
+export async function signDisputeEvidence(evidence, submitterPrivateKey) {
+    const body = { ...evidence, suite: DISPUTE_EVIDENCE_SUITE };
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    const sig = await signBySuite(DISPUTE_EVIDENCE_SUITE, message, submitterPrivateKey);
+    return { ...body, signature: toBase64Url(sig) };
+}
+/**
+ * Verify a DisputeEvidence submission against the submitting party's
+ * public key. Inner `evidence_data` validation against its own per-
+ * type schema (e.g. ExecutionReceiptSchema for `execution_receipt`)
+ * is the adjudicator's responsibility — this verifies the outer
+ * envelope signature only.
+ */
+export async function verifyDisputeEvidence(evidence, submitterPublicKey) {
+    if (evidence.suite !== DISPUTE_EVIDENCE_SUITE)
+        return false;
+    const { signature, ...body } = evidence;
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    try {
+        const sig = fromBase64Url(signature);
+        return await verifyBySuite(evidence.suite, message, sig, submitterPublicKey);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Sign a DisputeAppeal. The appealing party — filer or respondent —
+ * signs over the canonical JSON of every field except `signature`.
+ * Foundation law §8.4: one appeal per dispute; the post-appeal state
+ * is terminal. The relay verifies against the appealer's registered
+ * public key before transitioning the dispute to `appealed`.
+ */
+export async function signDisputeAppeal(appeal, appealerPrivateKey) {
+    const body = { ...appeal, suite: DISPUTE_APPEAL_SUITE };
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    const sig = await signBySuite(DISPUTE_APPEAL_SUITE, message, appealerPrivateKey);
+    return { ...body, signature: toBase64Url(sig) };
+}
+/**
+ * Verify a DisputeAppeal against the appealing party's public key.
+ * Fail-closed on unknown suite, base64url decode error, and primitive
+ * verification failure.
+ */
+export async function verifyDisputeAppeal(appeal, appealerPublicKey) {
+    if (appeal.suite !== DISPUTE_APPEAL_SUITE)
+        return false;
+    const { signature, ...body } = appeal;
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    try {
+        const sig = fromBase64Url(signature);
+        return await verifyBySuite(appeal.suite, message, sig, appealerPublicKey);
+    }
+    catch {
+        return false;
+    }
+}
+/** The one suite ConsolidationReceipts sign under today. */
+export const CONSOLIDATION_RECEIPT_SUITE = "motebit-jcs-ed25519-b64-v1";
+/**
+ * Sign a consolidation receipt. The motebit's Ed25519 identity key
+ * commits to the structural counts of work performed during a
+ * consolidation cycle. Receipt is self-attesting: any holder of the
+ * signer's public key verifies without contacting any relay.
+ *
+ * Callers pass the body without `signature` or `suite`; the signer
+ * owns both. Pass `publicKey` to embed it in the receipt for portable
+ * verification (recommended — third parties verify from the receipt
+ * alone).
+ *
+ * The signed receipt is `Object.freeze`d before return so any
+ * post-sign mutation throws synchronously at the producer instead of
+ * surfacing as wire-corruption noise on a downstream verifier.
+ */
+export async function signConsolidationReceipt(receipt, privateKey, publicKey) {
+    const withKey = publicKey
+        ? { ...receipt, public_key: bytesToHex(publicKey) }
+        : receipt;
+    const body = { ...withKey, suite: CONSOLIDATION_RECEIPT_SUITE };
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    const sig = await signBySuite(CONSOLIDATION_RECEIPT_SUITE, message, privateKey);
+    return Object.freeze({ ...body, signature: toBase64Url(sig) });
+}
+/**
+ * Verify a consolidation receipt against the signer's public key.
+ * Fail-closed on unknown `suite`, base64url decode error, primitive
+ * verification failure. The caller is responsible for matching
+ * `motebit_id` to whoever they expect signed; the cryptographic
+ * property here is "this body was signed by the holder of this key."
+ */
+export async function verifyConsolidationReceipt(receipt, publicKey) {
+    if (receipt.suite !== CONSOLIDATION_RECEIPT_SUITE)
+        return false;
+    const { signature, ...body } = receipt;
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    try {
+        const sig = fromBase64Url(signature);
+        return await verifyBySuite(receipt.suite, message, sig, publicKey);
+    }
+    catch {
+        return false;
+    }
+}
+/** The one suite BalanceWaivers sign under today — matches spec/migration-v1.md §7.2. */
+export const BALANCE_WAIVER_SUITE = "motebit-jcs-ed25519-b64-v1";
 /**
- * Build the canonical payload for key succession signing.
+ * Sign a balance waiver. The agent forfeits a named micro-unit amount to
+ * expedite departure from a relay (spec/migration-v1.md §7.2 + §7.3 — a
+ * waiver is one of the two terminal authorizations the depart route will
+ * accept, the other being a confirmed withdrawal).
+ *
+ * Callers pass the body without `signature` or `suite`; the signer owns
+ * both. The agent's identity key signs canonical JSON of the unsigned
+ * body (with `suite` stamped in), base64url-encoded.
+ */
+export async function signBalanceWaiver(waiver, agentPrivateKey) {
+    const body = { ...waiver, suite: BALANCE_WAIVER_SUITE };
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    const sig = await signBySuite(BALANCE_WAIVER_SUITE, message, agentPrivateKey);
+    return { ...body, signature: toBase64Url(sig) };
+}
+/**
+ * Verify a balance waiver against the agent's public key. Rejects
+ * fail-closed on unknown `suite`, base64url decode error, and primitive
+ * verification failure. Matching of `motebit_id` to the authorizing
+ * agent, and `waived_amount` to the actual virtual-account balance, is
+ * the caller's responsibility (neither is a cryptographic property).
+ */
+export async function verifyBalanceWaiver(waiver, agentPublicKey) {
+    if (waiver.suite !== BALANCE_WAIVER_SUITE)
+        return false;
+    const { signature, ...body } = waiver;
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    try {
+        const sig = fromBase64Url(signature);
+        return await verifyBySuite(waiver.suite, message, sig, agentPublicKey);
+    }
+    catch {
+        return false;
+    }
+}
+/** The one suite SettlementRecords sign under today. */
+export const SETTLEMENT_RECORD_SUITE = "motebit-jcs-ed25519-b64-v1";
+/**
+ * Sign a settlement record. The issuing relay commits to the (amount,
+ * fee, rate, status) tuple; a malicious relay therefore cannot issue
+ * inconsistent records to different observers.
+ *
+ * Callers pass the record without `signature` or `suite`; the signer
+ * owns both.
+ *
+ * Foundation Law (services/api/CLAUDE.md rule 6): every truth the
+ * relay asserts is independently verifiable. Per-agent settlements
+ * deliver this through the signature; federation settlements
+ * additionally get Merkle-batched and onchain-anchored.
+ */
+export async function signSettlement(settlement, issuerPrivateKey) {
+    const body = { ...settlement, suite: SETTLEMENT_RECORD_SUITE };
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    const sig = await signBySuite(SETTLEMENT_RECORD_SUITE, message, issuerPrivateKey);
+    return { ...body, signature: toBase64Url(sig) };
+}
+/**
+ * Verify a settlement record's signature. Reconstructs canonical JSON
+ * over all fields except `signature` and verifies Ed25519 against the
+ * issuing relay's public key.
+ *
+ * The caller supplies the public key — typically resolved from the
+ * `issuer_relay_id` via the federation peer registry or a known-keys
+ * store. The signature alone proves the record was issued by the
+ * holder of `issuerPublicKey`; trust in that key is a separate
+ * concern (federation membership, key rotation chain, etc).
+ *
+ * Fail-closed on:
+ *   - missing or unknown `suite` value
+ *   - base64url decode errors
+ *   - primitive-level verification failure
+ */
+export async function verifySettlement(settlement, issuerPublicKey) {
+    if (settlement.suite !== SETTLEMENT_RECORD_SUITE)
+        return false;
+    const { signature, ...body } = settlement;
+    const canonical = canonicalJson(body);
+    const message = new TextEncoder().encode(canonical);
+    try {
+        const sig = fromBase64Url(signature);
+        return await verifyBySuite(settlement.suite, message, sig, issuerPublicKey);
+    }
+    catch {
+        return false;
+    }
+}
+// === Key Succession (Rotation) ===
+/** The one suite KeySuccessionRecords sign under today. */
+export const KEY_SUCCESSION_SUITE = "motebit-jcs-ed25519-hex-v1";
+/**
+ * Build the canonical payload for key succession signing. The `suite`
+ * field is stamped into the signed body so verifiers dispatch the
+ * primitive via `verifyBySuite` rather than assuming Ed25519 implicitly.
  */
 function keySuccessionPayload(oldPublicKeyHex, newPublicKeyHex, timestamp, reason, recovery) {
     const obj = {
         old_public_key: oldPublicKeyHex,
         new_public_key: newPublicKeyHex,
         timestamp,
+        suite: KEY_SUCCESSION_SUITE,
     };
     if (reason !== undefined) {
         obj.reason = reason;
@@ -238,6 +792,8 @@ function keySuccessionPayload(oldPublicKeyHex, newPublicKeyHex, timestamp, reaso
 }
 /**
  * Create a key succession record signed by both the old and new keys.
+ * Dispatches primitive signing through `signBySuite` per the
+ * `motebit-jcs-ed25519-hex-v1` suite.
  */
 export async function signKeySuccession(oldPrivateKey, newPrivateKey, newPublicKey, oldPublicKey, reason) {
     const timestamp = Date.now();
@@ -245,13 +801,14 @@ export async function signKeySuccession(oldPrivateKey, newPrivateKey, newPublicK
     const newPublicKeyHex = bytesToHex(newPublicKey);
     const payload = keySuccessionPayload(oldPublicKeyHex, newPublicKeyHex, timestamp, reason);
     const message = new TextEncoder().encode(payload);
-    const oldSig = await ed25519Sign(message, oldPrivateKey);
-    const newSig = await ed25519Sign(message, newPrivateKey);
+    const oldSig = await signBySuite(KEY_SUCCESSION_SUITE, message, oldPrivateKey);
+    const newSig = await signBySuite(KEY_SUCCESSION_SUITE, message, newPrivateKey);
     return {
         old_public_key: oldPublicKeyHex,
         new_public_key: newPublicKeyHex,
         timestamp,
         ...(reason !== undefined ? { reason } : {}),
+        suite: KEY_SUCCESSION_SUITE,
         old_key_signature: bytesToHex(oldSig),
         new_key_signature: bytesToHex(newSig),
     };
@@ -268,29 +825,34 @@ export async function signGuardianRecoverySuccession(guardianPrivateKey, newPriv
     const effectiveReason = reason ?? "guardian_recovery";
     const payload = keySuccessionPayload(oldPublicKeyHex, newPublicKeyHex, timestamp, effectiveReason, true);
     const message = new TextEncoder().encode(payload);
-    const guardianSig = await ed25519Sign(message, guardianPrivateKey);
-    const newSig = await ed25519Sign(message, newPrivateKey);
+    const guardianSig = await signBySuite(KEY_SUCCESSION_SUITE, message, guardianPrivateKey);
+    const newSig = await signBySuite(KEY_SUCCESSION_SUITE, message, newPrivateKey);
     return {
         old_public_key: oldPublicKeyHex,
         new_public_key: newPublicKeyHex,
         timestamp,
         reason: effectiveReason,
+        suite: KEY_SUCCESSION_SUITE,
         new_key_signature: bytesToHex(newSig),
         recovery: true,
         guardian_signature: bytesToHex(guardianSig),
     };
 }
 /**
- * Verify a key succession record. For normal rotation, checks old_key_signature + new_key_signature.
- * For guardian recovery (recovery: true), checks guardian_signature + new_key_signature.
+ * Verify a key succession record. For normal rotation, checks
+ * old_key_signature + new_key_signature. For guardian recovery
+ * (recovery: true), checks guardian_signature + new_key_signature.
+ * Rejects records whose `suite` is missing or not the succession suite.
  */
 export async function verifyKeySuccession(record, guardianPublicKeyHex) {
+    if (record.suite !== KEY_SUCCESSION_SUITE)
+        return false;
     const payload = keySuccessionPayload(record.old_public_key, record.new_public_key, record.timestamp, record.reason, record.recovery);
     const message = new TextEncoder().encode(payload);
     try {
         const newPubKey = hexToBytes(record.new_public_key);
         const newSig = hexToBytes(record.new_key_signature);
-        const newValid = await ed25519Verify(newSig, message, newPubKey);
+        const newValid = await verifyBySuite(record.suite, message, newSig, newPubKey);
         if (!newValid)
             return false;
         if (record.recovery) {
@@ -298,14 +860,14 @@ export async function verifyKeySuccession(record, guardianPublicKeyHex) {
                 return false;
             const guardianPubKey = hexToBytes(guardianPublicKeyHex);
             const guardianSig = hexToBytes(record.guardian_signature);
-            return await ed25519Verify(guardianSig, message, guardianPubKey);
+            return await verifyBySuite(record.suite, message, guardianSig, guardianPubKey);
         }
         else {
             if (!record.old_key_signature)
                 return false;
             const oldPubKey = hexToBytes(record.old_public_key);
             const oldSig = hexToBytes(record.old_key_signature);
-            return await ed25519Verify(oldSig, message, oldPubKey);
+            return await verifyBySuite(record.suite, message, oldSig, oldPubKey);
         }
     }
     catch {
@@ -392,16 +954,23 @@ export async function verifySuccessionChain(chain, guardianPublicKeyHex) {
     };
 }
 // === Guardian Revocation (§3.3.2) ===
+/** Guardian revocation shares the identity-file suite (JCS + hex). */
+export const GUARDIAN_REVOCATION_SUITE = "motebit-jcs-ed25519-hex-v1";
 /**
  * Sign a guardian revocation payload — requires BOTH identity and guardian keys.
  * Neither party can unilaterally dissolve the custody relationship.
+ * Dispatches the primitive through `signBySuite`.
  */
 export async function signGuardianRevocation(identityPrivateKey, guardianPrivateKey, timestamp) {
     const ts = timestamp ?? Date.now();
-    const payload = canonicalJson({ action: "guardian_revoked", timestamp: ts });
+    const payload = canonicalJson({
+        action: "guardian_revoked",
+        timestamp: ts,
+        suite: GUARDIAN_REVOCATION_SUITE,
+    });
     const message = new TextEncoder().encode(payload);
-    const identitySig = await ed25519Sign(message, identityPrivateKey);
-    const guardianSig = await ed25519Sign(message, guardianPrivateKey);
+    const identitySig = await signBySuite(GUARDIAN_REVOCATION_SUITE, message, identityPrivateKey);
+    const guardianSig = await signBySuite(GUARDIAN_REVOCATION_SUITE, message, guardianPrivateKey);
     return {
         payload,
         identity_signature: bytesToHex(identitySig),
@@ -411,27 +980,35 @@ export async function signGuardianRevocation(identityPrivateKey, guardianPrivate
 }
 /**
  * Verify a guardian revocation proof — both signatures must be valid.
+ * Dispatches primitive verification through `verifyBySuite`.
  */
 export async function verifyGuardianRevocation(revocation, identityPublicKeyHex, guardianPublicKeyHex) {
-    const payload = canonicalJson({ action: "guardian_revoked", timestamp: revocation.timestamp });
+    const payload = canonicalJson({
+        action: "guardian_revoked",
+        timestamp: revocation.timestamp,
+        suite: GUARDIAN_REVOCATION_SUITE,
+    });
     const message = new TextEncoder().encode(payload);
     try {
         const identityPub = hexToBytes(identityPublicKeyHex);
         const guardianPub = hexToBytes(guardianPublicKeyHex);
         const identitySig = hexToBytes(revocation.identity_signature);
         const guardianSig = hexToBytes(revocation.guardian_signature);
-        const identityValid = await ed25519Verify(identitySig, message, identityPub);
-        const guardianValid = await ed25519Verify(guardianSig, message, guardianPub);
+        const identityValid = await verifyBySuite(GUARDIAN_REVOCATION_SUITE, message, identitySig, identityPub);
+        const guardianValid = await verifyBySuite(GUARDIAN_REVOCATION_SUITE, message, guardianSig, guardianPub);
         return identityValid && guardianValid;
     }
     catch {
         return false;
     }
 }
+// === Collaborative Receipt ===
+/** The one suite CollaborativeReceipts sign under today. */
+export const COLLABORATIVE_RECEIPT_SUITE = "motebit-jcs-ed25519-b64-v1";
 /**
  * Sign a collaborative receipt. Computes a content hash over the canonical
- * JSON of all participant receipts, then signs the aggregate with the
- * initiator's Ed25519 private key.
+ * JSON of all participant receipts, then signs the aggregate through
+ * `signBySuite` under `motebit-jcs-ed25519-b64-v1`.
  */
 export async function signCollaborativeReceipt(receipt, initiatorPrivateKey) {
     const receiptsCanonical = canonicalJson(receipt.participant_receipts);
@@ -441,22 +1018,29 @@ export async function signCollaborativeReceipt(receipt, initiatorPrivateKey) {
         proposal_id: receipt.proposal_id,
         plan_id: receipt.plan_id,
         content_hash: contentHash,
+        suite: COLLABORATIVE_RECEIPT_SUITE,
     });
     const sigMessage = new TextEncoder().encode(sigPayload);
-    const sig = await ed25519Sign(sigMessage, initiatorPrivateKey);
+    const sig = await signBySuite(COLLABORATIVE_RECEIPT_SUITE, sigMessage, initiatorPrivateKey);
     return {
         ...receipt,
         content_hash: contentHash,
+        suite: COLLABORATIVE_RECEIPT_SUITE,
         initiator_signature: toBase64Url(sig),
     };
 }
 /**
  * Verify a collaborative receipt:
- * 1. Recomputes content hash from participant receipts and checks it matches.
- * 2. Verifies the initiator's Ed25519 signature over the aggregate.
- * 3. Optionally verifies each participant receipt against known keys.
+ * 1. Rejects any record whose `suite` is missing or not the collaborative suite.
+ * 2. Recomputes content hash from participant receipts and checks it matches.
+ * 3. Verifies the initiator's Ed25519 signature over the aggregate via `verifyBySuite`.
+ * 4. Optionally verifies each participant receipt against known keys.
  */
 export async function verifyCollaborativeReceipt(receipt, initiatorPublicKey, participantKeys) {
+    // 0. Suite discriminator check
+    if (receipt.suite !== COLLABORATIVE_RECEIPT_SUITE) {
+        return { valid: false, error: "Unknown or missing cryptosuite" };
+    }
     // 1. Recompute content hash
     const receiptsCanonical = canonicalJson(receipt.participant_receipts);
     const receiptsBytes = new TextEncoder().encode(receiptsCanonical);
@@ -464,16 +1048,17 @@ export async function verifyCollaborativeReceipt(receipt, initiatorPublicKey, pa
     if (expectedHash !== receipt.content_hash) {
         return { valid: false, error: "Content hash mismatch" };
     }
-    // 2. Verify initiator signature
+    // 2. Verify initiator signature (suite stamped into the signed payload)
     const sigPayload = canonicalJson({
         proposal_id: receipt.proposal_id,
         plan_id: receipt.plan_id,
         content_hash: receipt.content_hash,
+        suite: receipt.suite,
     });
     const sigMessage = new TextEncoder().encode(sigPayload);
     try {
         const sig = fromBase64Url(receipt.initiator_signature);
-        const sigValid = await ed25519Verify(sig, sigMessage, initiatorPublicKey);
+        const sigValid = await verifyBySuite(receipt.suite, sigMessage, sig, initiatorPublicKey);
         if (!sigValid) {
             return { valid: false, error: "Initiator signature invalid" };
         }
@@ -503,4 +1088,71 @@ export async function verifyCollaborativeReceipt(receipt, initiatorPublicKey, pa
     }
     return { valid: true };
 }
+// === Device Self-Registration ===
+//
+// Self-attesting registration: the device proves it controls a private key
+// by signing a canonical-JSON serialization of its own registration request.
+// The relay verifies against the public_key carried in the same request — no
+// prior trust anchor required. Wire format and verification recipe are
+// foundation law in `spec/device-self-registration-v1.md`.
+//
+// Trust posture: a self-registered device starts at trust zero. Trust accrues
+// through receipts, credentials, and onchain anchors — never through
+// registration alone. See `docs/doctrine/protocol-model.md`.
+/** The one suite device-registration requests sign under today. */
+export const DEVICE_REGISTRATION_SUITE = "motebit-jcs-ed25519-b64-v1";
+/**
+ * Sign a device-registration request. Stamps the cryptosuite into the body,
+ * canonicalizes with JCS, dispatches the primitive signature through
+ * `signBySuite`, and encodes as base64url per the suite's rules.
+ *
+ * Callers pass the body without `signature` and (optionally) without `suite`;
+ * the signer owns both. The returned object is a complete signed request
+ * ready to POST to a relay's self-register endpoint.
+ */
+export async function signDeviceRegistration(body, privateKey) {
+    const withSuite = { ...body, suite: DEVICE_REGISTRATION_SUITE };
+    const canonical = canonicalJson(withSuite);
+    const message = new TextEncoder().encode(canonical);
+    const sig = await signBySuite(DEVICE_REGISTRATION_SUITE, message, privateKey);
+    return { ...withSuite, signature: toBase64Url(sig) };
+}
+/** Maximum drift between the signer's claimed timestamp and the verifier's clock. */
+export const DEVICE_REGISTRATION_MAX_AGE_MS = 5 * 60 * 1000;
+export async function verifyDeviceRegistration(body, now = Date.now()) {
+    // Step 1 — shape validation. Any missing / mistyped field is "malformed".
+    if (typeof body.motebit_id !== "string" ||
+        typeof body.device_id !== "string" ||
+        typeof body.public_key !== "string" ||
+        !/^[0-9a-f]{64}$/i.test(body.public_key) ||
+        typeof body.timestamp !== "number" ||
+        typeof body.suite !== "string" ||
+        typeof body.signature !== "string") {
+        return { valid: false, reason: "malformed" };
+    }
+    // Step 2 — replay window.
+    if (Math.abs(now - body.timestamp) > DEVICE_REGISTRATION_MAX_AGE_MS) {
+        return { valid: false, reason: "stale" };
+    }
+    // Step 3 — suite check. Only the registered suite is acceptable today;
+    // future suites add a dispatch arm in suite-dispatch.ts.
+    if (body.suite !== DEVICE_REGISTRATION_SUITE) {
+        return { valid: false, reason: "unsupported_suite" };
+    }
+    // Step 4–7 — canonicalize, decode, verify.
+    const { signature, ...bodyForSig } = body;
+    const canonical = canonicalJson(bodyForSig);
+    const message = new TextEncoder().encode(canonical);
+    let sigBytes;
+    let pkBytes;
+    try {
+        sigBytes = fromBase64Url(signature);
+        pkBytes = hexToBytes(body.public_key);
+    }
+    catch {
+        return { valid: false, reason: "malformed" };
+    }
+    const ok = await verifyBySuite(body.suite, message, sigBytes, pkBytes);
+    return ok ? { valid: true } : { valid: false, reason: "bad_signature" };
+}
 //# sourceMappingURL=artifacts.js.map