@motebit/crypto 1.1.0 → 1.2.0

package/dist/skills.js

@@ -0,0 +1,228 @@
+/**
+ * Skill manifest + envelope signing and verification — spec/skills-v1.md.
+ *
+ * Skills are motebit-internal protocol artifacts. They install locally,
+ * verify on motebit runtimes, and are signed by their author's motebit
+ * identity using `motebit-jcs-ed25519-b64-v1` — the same suite used for
+ * execution receipts, tool invocation receipts, settlement anchors, and
+ * migration artifacts. NOT W3C `eddsa-jcs-2022` (that suite is reserved for
+ * credentials, identity files, and presentations needing third-party W3C
+ * interop).
+ *
+ * Signature recipe (spec §5.1):
+ *
+ *   manifest_bytes = JCS(manifest_with_signature_value_removed) || 0x0A || lf_body
+ *   envelope_bytes = JCS(envelope_with_signature_value_removed)
+ *   signature = Ed25519.sign(bytes, privateKey)  -- routed through verifyBySuite
+ *
+ * Verification is offline: no relay, no registry, no external service. Per
+ * @motebit/crypto/CLAUDE.md rule 4, third-party verifiers using only this
+ * package and the signer's public key can validate any motebit-signed skill.
+ */
+import { canonicalJson, fromBase64Url, hexToBytes, signBySuite, toBase64Url, verifyBySuite, } from "./signing.js";
+/** The suite skills sign under in v1. Mirrors EXECUTION_RECEIPT_SUITE. */
+export const SKILL_SIGNATURE_SUITE = "motebit-jcs-ed25519-b64-v1";
+// ---------------------------------------------------------------------------
+// Canonicalization — pure, deterministic, dependency-free
+// ---------------------------------------------------------------------------
+/**
+ * Strip `signature.value` from a SkillSignature, preserving `suite` and
+ * `public_key` (those ARE part of the signed canonical form per spec §5.1).
+ */
+function signatureWithoutValue(sig) {
+    return { suite: sig.suite, public_key: sig.public_key };
+}
+/**
+ * Compute the canonical bytes that a SkillManifest signature is computed over.
+ * `body` is the LF-normalized SKILL.md body bytes (everything after the
+ * closing `---` delimiter), with CRLF/CR converted to LF, no BOM, UTF-8.
+ *
+ * Caller is responsible for body normalization. The reference parser in
+ * @motebit/skills (BSL) does the normalization at file-read time.
+ *
+ * The manifest's `motebit.signature.value` is removed before canonicalization;
+ * `suite` and `public_key` are preserved (they are signature-bound).
+ */
+export function canonicalizeSkillManifestBytes(manifest, body) {
+    const motebitForCanonical = manifest.motebit.signature
+        ? {
+            ...manifest.motebit,
+            signature: signatureWithoutValue(manifest.motebit.signature),
+        }
+        : manifest.motebit;
+    const manifestForCanonical = { ...manifest, motebit: motebitForCanonical };
+    const canonical = canonicalJson(manifestForCanonical);
+    const manifestBytes = new TextEncoder().encode(canonical);
+    const out = new Uint8Array(manifestBytes.length + 1 + body.length);
+    out.set(manifestBytes, 0);
+    out[manifestBytes.length] = 0x0a; // LF separator
+    out.set(body, manifestBytes.length + 1);
+    return out;
+}
+/**
+ * Compute the canonical bytes that a SkillEnvelope signature is computed
+ * over. Sibling to manifest canonicalization; envelope is pure JSON so no
+ * body concatenation.
+ */
+export function canonicalizeSkillEnvelopeBytes(envelope) {
+    const envelopeForCanonical = {
+        ...envelope,
+        signature: signatureWithoutValue(envelope.signature),
+    };
+    const canonical = canonicalJson(envelopeForCanonical);
+    return new TextEncoder().encode(canonical);
+}
+// ---------------------------------------------------------------------------
+// Signing — for skill authors
+// ---------------------------------------------------------------------------
+/**
+ * Sign a SkillManifest, returning the signed manifest with `motebit.signature`
+ * populated. Caller provides the LF-normalized body bytes; signing recipe is
+ * spec §5.1.
+ *
+ * The returned manifest's `motebit.signature.public_key` is hex-encoded and
+ * `motebit.signature.value` is base64url-encoded, matching the suite contract.
+ */
+export async function signSkillManifest(unsigned, privateKey, publicKey, body) {
+    const publicKeyHex = bytesToLowerHex(publicKey);
+    // Stamp the unsigned signature block (suite + public_key) so it participates
+    // in canonicalization at sign time.
+    const unsignedWithSig = {
+        ...unsigned,
+        motebit: {
+            ...unsigned.motebit,
+            signature: {
+                suite: SKILL_SIGNATURE_SUITE,
+                public_key: publicKeyHex,
+                value: "", // placeholder; stripped by canonicalize
+            },
+        },
+    };
+    const message = canonicalizeSkillManifestBytes(unsignedWithSig, body);
+    const sig = await signBySuite(SKILL_SIGNATURE_SUITE, message, privateKey);
+    return {
+        ...unsigned,
+        motebit: {
+            ...unsigned.motebit,
+            signature: {
+                suite: SKILL_SIGNATURE_SUITE,
+                public_key: publicKeyHex,
+                value: toBase64Url(sig),
+            },
+        },
+    };
+}
+/**
+ * Sign a SkillEnvelope, returning the signed envelope. Sibling to
+ * `signSkillManifest`. Envelope canonicalization is pure JSON (§5.1).
+ */
+export async function signSkillEnvelope(unsigned, privateKey, publicKey) {
+    const publicKeyHex = bytesToLowerHex(publicKey);
+    const unsignedWithSig = {
+        ...unsigned,
+        signature: {
+            suite: SKILL_SIGNATURE_SUITE,
+            public_key: publicKeyHex,
+            value: "", // placeholder; stripped by canonicalize
+        },
+    };
+    const message = canonicalizeSkillEnvelopeBytes(unsignedWithSig);
+    const sig = await signBySuite(SKILL_SIGNATURE_SUITE, message, privateKey);
+    return {
+        ...unsigned,
+        signature: {
+            suite: SKILL_SIGNATURE_SUITE,
+            public_key: publicKeyHex,
+            value: toBase64Url(sig),
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Verification — fail-closed on every error path
+// ---------------------------------------------------------------------------
+/**
+ * Verify a SkillManifest's signature against the provided public key and
+ * LF-normalized body bytes. Returns `false` on any failure path:
+ *
+ *  - manifest is unsigned (`motebit.signature` absent)
+ *  - suite mismatch (only `motebit-jcs-ed25519-b64-v1` accepted in v1)
+ *  - public_key in the signature doesn't match the supplied public key
+ *  - signature value fails base64url decode
+ *  - Ed25519 verification fails
+ *
+ * Per CLAUDE.md rule 4, this is the third-party self-verification entry
+ * point. Only this package + the signer's public key are required.
+ */
+export async function verifySkillManifest(manifest, body, publicKey) {
+    return (await verifySkillManifestDetailed(manifest, body, publicKey)).valid;
+}
+/**
+ * Companion to `verifySkillManifest` that returns a categorized failure
+ * reason for observability. Same recipe; same fail-closed behavior.
+ */
+export async function verifySkillManifestDetailed(manifest, body, publicKey) {
+    const sig = manifest.motebit.signature;
+    if (!sig)
+        return { valid: false, reason: "no_signature" };
+    if (sig.suite !== SKILL_SIGNATURE_SUITE)
+        return { valid: false, reason: "wrong_suite" };
+    const publicKeyHex = bytesToLowerHex(publicKey);
+    if (sig.public_key.toLowerCase() !== publicKeyHex) {
+        return { valid: false, reason: "bad_public_key" };
+    }
+    let sigBytes;
+    try {
+        sigBytes = fromBase64Url(sig.value);
+    }
+    catch {
+        return { valid: false, reason: "bad_signature_value" };
+    }
+    const message = canonicalizeSkillManifestBytes(manifest, body);
+    const valid = await verifyBySuite(SKILL_SIGNATURE_SUITE, message, sigBytes, publicKey);
+    return { valid, reason: valid ? "ok" : "ed25519_mismatch" };
+}
+/**
+ * Verify a SkillEnvelope's signature. Sibling to `verifySkillManifest` —
+ * same suite, same fail-closed semantics. Note: envelope verification does
+ * NOT cross-check `body_hash` or `files[].hash` against on-disk bytes; the
+ * caller (install-time logic in the registry) is responsible for that pass
+ * after signature verification succeeds.
+ */
+export async function verifySkillEnvelope(envelope, publicKey) {
+    return (await verifySkillEnvelopeDetailed(envelope, publicKey)).valid;
+}
+export async function verifySkillEnvelopeDetailed(envelope, publicKey) {
+    const sig = envelope.signature;
+    if (sig.suite !== SKILL_SIGNATURE_SUITE)
+        return { valid: false, reason: "wrong_suite" };
+    const publicKeyHex = bytesToLowerHex(publicKey);
+    if (sig.public_key.toLowerCase() !== publicKeyHex) {
+        return { valid: false, reason: "bad_public_key" };
+    }
+    let sigBytes;
+    try {
+        sigBytes = fromBase64Url(sig.value);
+    }
+    catch {
+        return { valid: false, reason: "bad_signature_value" };
+    }
+    const message = canonicalizeSkillEnvelopeBytes(envelope);
+    const valid = await verifyBySuite(SKILL_SIGNATURE_SUITE, message, sigBytes, publicKey);
+    return { valid, reason: valid ? "ok" : "ed25519_mismatch" };
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Hex-encode a 32-byte public key as 64 lowercase hex chars. */
+function bytesToLowerHex(bytes) {
+    let hex = "";
+    for (const b of bytes) {
+        hex += b.toString(16).padStart(2, "0");
+    }
+    return hex;
+}
+/** Decode a hex public key from a SkillSignature for caller convenience. */
+export function decodeSkillSignaturePublicKey(sig) {
+    return hexToBytes(sig.public_key);
+}
+//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

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