@cello-protocol/crypto 0.0.2

package/dist/relay-registration.d.ts

@@ -0,0 +1,62 @@
+/**
+ * FEDERATION-003 — Relay registration TBS (to-be-signed) serialization and signature verification.
+ *
+ * buildRelayRegistrationTbs produces the canonical byte representation for a relay
+ * registration self-signature:
+ *
+ *   TBS = SHA-256(relay_id_bytes || public_key_hex_bytes || timestamp_BE8)
+ *
+ * where:
+ *   relay_id_bytes:        UTF-8 encoding of the relay_id string
+ *   public_key_hex_bytes:  UTF-8 encoding of the public_key_hex string
+ *   timestamp_BE8:         Unix millisecond timestamp as 8-byte big-endian uint64
+ *
+ * SI-003: This TBS must be used by both the relay (which signs) and the directory
+ * (which verifies). Keeping it in @cello-protocol/crypto ensures neither side can diverge.
+ *
+ * verifyRelayRegistrationSignature verifies that the signature was produced by the
+ * private key corresponding to publicKeyHex, preventing an attacker from registering
+ * a relay_id for a key they do not control.
+ *
+ * References: RFC 8032 (Ed25519), FIPS 180-4 (SHA-256).
+ */
+/**
+ * Build the canonical TBS bytes for a relay registration self-signature.
+ *
+ * Pseudocode (SPARC Phase P):
+ *   1. UTF-8 encode relay_id as relayIdBytes
+ *   2. UTF-8 encode public_key_hex as pubKeyHexBytes
+ *   3. Encode timestamp as 8-byte big-endian uint64 (BigInt, safe for Unix ms)
+ *   4. Concatenate: relayIdBytes || pubKeyHexBytes || timestamp_BE8
+ *   5. SHA-256(concatenation) — FIPS 180-4
+ *   6. Return 32-byte digest as Uint8Array
+ *
+ * @param relayId - The relay identifier (hex encoding of the relay's Ed25519 public key)
+ * @param publicKeyHex - 64-char hex string of the relay's Ed25519 public key
+ * @param timestamp - Unix millisecond timestamp at registration time
+ * @returns 32-byte SHA-256 digest — FIPS 180-4
+ */
+export declare function buildRelayRegistrationTbs(relayId: string, publicKeyHex: string, timestamp: number): Uint8Array;
+/**
+ * Verify a relay registration self-signature.
+ *
+ * SI-003: The relay signs the registration TBS with its Ed25519 private key.
+ * The directory verifies against the public_key_hex submitted in the request.
+ * Only a caller that controls the private key corresponding to public_key_hex
+ * can produce a valid signature.
+ *
+ * Pseudocode:
+ *   1. Decode publicKeyHex as 32 bytes
+ *   2. Compute tbs = buildRelayRegistrationTbs(relayId, publicKeyHex, timestamp)
+ *   3. Return ed25519.verify(signature, tbs, publicKeyBytes)
+ *      — RFC 8032 §5.1.7 verify algorithm
+ *
+ * @param publicKeyHex - 64-char hex string of the relay's submitted Ed25519 public key
+ * @param relayId - The relay identifier submitted in the registration request
+ * @param publicKeyHexInTbs - The public_key_hex value used in the TBS (must match publicKeyHex)
+ * @param timestamp - The Unix millisecond timestamp from the registration request
+ * @param signature - 64-byte Ed25519 signature from the relay
+ * @returns true if signature is valid, false otherwise
+ */
+export declare function verifyRelayRegistrationSignature(publicKeyHex: string, relayId: string, publicKeyHexInTbs: string, timestamp: number, signature: Uint8Array): Promise<boolean>;
+//# sourceMappingURL=relay-registration.d.ts.map

package/dist/relay-registration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-registration.d.ts","sourceRoot":"","sources":["../src/relay-registration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAKH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,yBAAyB,CACvC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAChB,UAAU,CAeZ;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAsB,gCAAgC,CACpD,YAAY,EAAE,MAAM,EACpB,OAAO,EAAE,MAAM,EACf,iBAAiB,EAAE,MAAM,EACzB,SAAS,EAAE,MAAM,EACjB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC,CAWlB"}

package/dist/relay-registration.js

@@ -0,0 +1,87 @@
+/**
+ * FEDERATION-003 — Relay registration TBS (to-be-signed) serialization and signature verification.
+ *
+ * buildRelayRegistrationTbs produces the canonical byte representation for a relay
+ * registration self-signature:
+ *
+ *   TBS = SHA-256(relay_id_bytes || public_key_hex_bytes || timestamp_BE8)
+ *
+ * where:
+ *   relay_id_bytes:        UTF-8 encoding of the relay_id string
+ *   public_key_hex_bytes:  UTF-8 encoding of the public_key_hex string
+ *   timestamp_BE8:         Unix millisecond timestamp as 8-byte big-endian uint64
+ *
+ * SI-003: This TBS must be used by both the relay (which signs) and the directory
+ * (which verifies). Keeping it in @cello-protocol/crypto ensures neither side can diverge.
+ *
+ * verifyRelayRegistrationSignature verifies that the signature was produced by the
+ * private key corresponding to publicKeyHex, preventing an attacker from registering
+ * a relay_id for a key they do not control.
+ *
+ * References: RFC 8032 (Ed25519), FIPS 180-4 (SHA-256).
+ */
+import { createHash } from "node:crypto";
+import { ed25519 } from "@noble/curves/ed25519.js";
+/**
+ * Build the canonical TBS bytes for a relay registration self-signature.
+ *
+ * Pseudocode (SPARC Phase P):
+ *   1. UTF-8 encode relay_id as relayIdBytes
+ *   2. UTF-8 encode public_key_hex as pubKeyHexBytes
+ *   3. Encode timestamp as 8-byte big-endian uint64 (BigInt, safe for Unix ms)
+ *   4. Concatenate: relayIdBytes || pubKeyHexBytes || timestamp_BE8
+ *   5. SHA-256(concatenation) — FIPS 180-4
+ *   6. Return 32-byte digest as Uint8Array
+ *
+ * @param relayId - The relay identifier (hex encoding of the relay's Ed25519 public key)
+ * @param publicKeyHex - 64-char hex string of the relay's Ed25519 public key
+ * @param timestamp - Unix millisecond timestamp at registration time
+ * @returns 32-byte SHA-256 digest — FIPS 180-4
+ */
+export function buildRelayRegistrationTbs(relayId, publicKeyHex, timestamp) {
+    const encoder = new TextEncoder();
+    const relayIdBytes = encoder.encode(relayId);
+    const pubKeyHexBytes = encoder.encode(publicKeyHex);
+    const tsBuf = Buffer.allocUnsafe(8);
+    tsBuf.writeBigUInt64BE(BigInt(timestamp), 0);
+    const preimage = Buffer.concat([
+        Buffer.from(relayIdBytes),
+        Buffer.from(pubKeyHexBytes),
+        tsBuf,
+    ]);
+    return new Uint8Array(createHash("sha256").update(preimage).digest());
+}
+/**
+ * Verify a relay registration self-signature.
+ *
+ * SI-003: The relay signs the registration TBS with its Ed25519 private key.
+ * The directory verifies against the public_key_hex submitted in the request.
+ * Only a caller that controls the private key corresponding to public_key_hex
+ * can produce a valid signature.
+ *
+ * Pseudocode:
+ *   1. Decode publicKeyHex as 32 bytes
+ *   2. Compute tbs = buildRelayRegistrationTbs(relayId, publicKeyHex, timestamp)
+ *   3. Return ed25519.verify(signature, tbs, publicKeyBytes)
+ *      — RFC 8032 §5.1.7 verify algorithm
+ *
+ * @param publicKeyHex - 64-char hex string of the relay's submitted Ed25519 public key
+ * @param relayId - The relay identifier submitted in the registration request
+ * @param publicKeyHexInTbs - The public_key_hex value used in the TBS (must match publicKeyHex)
+ * @param timestamp - The Unix millisecond timestamp from the registration request
+ * @param signature - 64-byte Ed25519 signature from the relay
+ * @returns true if signature is valid, false otherwise
+ */
+export async function verifyRelayRegistrationSignature(publicKeyHex, relayId, publicKeyHexInTbs, timestamp, signature) {
+    try {
+        const publicKeyBytes = Buffer.from(publicKeyHex, "hex");
+        if (publicKeyBytes.length !== 32)
+            return false;
+        const tbs = buildRelayRegistrationTbs(relayId, publicKeyHexInTbs, timestamp);
+        return ed25519.verify(signature, tbs, publicKeyBytes);
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=relay-registration.js.map

package/dist/relay-registration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relay-registration.js","sourceRoot":"","sources":["../src/relay-registration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAC;AAEnD;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,yBAAyB,CACvC,OAAe,EACf,YAAoB,EACpB,SAAiB;IAEjB,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;IAClC,MAAM,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC7C,MAAM,cAAc,GAAG,OAAO,CAAC,MAAM,CAAC,YAAY,CAAC,CAAC;IAEpD,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IACpC,KAAK,CAAC,gBAAgB,CAAC,MAAM,CAAC,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;IAE7C,MAAM,QAAQ,GAAG,MAAM,CAAC,MAAM,CAAC;QAC7B,MAAM,CAAC,IAAI,CAAC,YAAY,CAAC;QACzB,MAAM,CAAC,IAAI,CAAC,cAAc,CAAC;QAC3B,KAAK;KACN,CAAC,CAAC;IAEH,OAAO,IAAI,UAAU,CAAC,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,CAAC,KAAK,UAAU,gCAAgC,CACpD,YAAoB,EACpB,OAAe,EACf,iBAAyB,EACzB,SAAiB,EACjB,SAAqB;IAErB,IAAI,CAAC;QACH,MAAM,cAAc,GAAG,MAAM,CAAC,IAAI,CAAC,YAAY,EAAE,KAAK,CAAC,CAAC;QACxD,IAAI,cAAc,CAAC,MAAM,KAAK,EAAE;YAAE,OAAO,KAAK,CAAC;QAE/C,MAAM,GAAG,GAAG,yBAAyB,CAAC,OAAO,EAAE,iBAAiB,EAAE,SAAS,CAAC,CAAC;QAE7E,OAAO,OAAO,CAAC,MAAM,CAAC,SAAS,EAAE,GAAG,EAAE,cAAc,CAAC,CAAC;IACxD,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,KAAK,CAAC;IACf,CAAC;AACH,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,11 @@
+export type PublicKey = Uint8Array;
+export type Signature = Uint8Array;
+export interface KeyProvider {
+    getPublicKey(): Promise<PublicKey>;
+    sign(data: Uint8Array): Promise<Signature>;
+}
+export interface KeyFileCorruptError {
+    reason: "key_file_corrupt";
+    message: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC;AACnC,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC;AAEnC,MAAM,WAAW,WAAW;IAC1B,YAAY,IAAI,OAAO,CAAC,SAAS,CAAC,CAAC;IACnC,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,kBAAkB,CAAC;IAC3B,OAAO,EAAE,MAAM,CAAC;CACjB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@cello-protocol/crypto",
+  "version": "0.0.2",
+  "private": false,
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./frost/frost-threshold-signer.js": {
+      "import": "./dist/frost/frost-threshold-signer.js",
+      "types": "./dist/frost/frost-threshold-signer.d.ts"
+    },
+    "./frost/stubs.js": {
+      "import": "./dist/frost/stubs.js",
+      "types": "./dist/frost/stubs.d.ts"
+    },
+    "./frost/types.js": {
+      "import": "./dist/frost/types.js",
+      "types": "./dist/frost/types.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "package.json"
+  ],
+  "dependencies": {
+    "@noble/curves": "2.2.0",
+    "@noble/hashes": "2.2.0",
+    "@oqs/liboqs-js": "^0.15.1"
+  },
+  "devDependencies": {
+    "@claude-flow/testing": "3.0.0-alpha.6",
+    "@types/node": "^25.6.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "test": "vitest run"
+  }
+}