Merge pull request #10 from devlux76/copilot/p0-a-crypto-helpers-implementation

Author: devlux76

PLAN.md

@@ -23,9 +23,9 @@ This document tracks the implementation status of each major module in CORTEX. I
 | Core Types | ✅ Complete | `core/types.ts` | All entity interfaces defined (Page, Book, Volume, Shelf, Edge, MetroidNeighbor, storage interfaces) |
 | Model Profiles | ✅ Complete | `core/ModelProfile.ts`, `core/ModelDefaults.ts`, `core/ModelProfileResolver.ts`, `core/BuiltInModelProfiles.ts` | Source-of-truth for model-derived numerics; guard script enforces compliance |
 | Numeric Constants | ✅ Complete | `core/NumericConstants.ts` | Runtime constants (byte sizes, workgroup limits) centralized |
-| Crypto Helpers | ❌ Missing | `core/crypto/*` (planned) | Hash, sign, verify utilities not yet implemented |
+| Crypto Helpers | ✅ Complete | `core/crypto/hash.ts`, `core/crypto/sign.ts`, `core/crypto/verify.ts` | SHA-256 hashing; Ed25519 sign/verify; 26 tests passing |
 
-**Foundation Status:** 3/4 complete (75%)
+**Foundation Status:** 4/4 complete (100%)
 
 ---
 
@@ -148,7 +148,7 @@ This document tracks the implementation status of each major module in CORTEX. I
 
 | Module | Status | Files | Notes |
 |--------|--------|-------|-------|
-| Unit Tests | ✅ Complete | `tests/*.test.ts`, `tests/**/*.test.ts` | 89 tests across 10 files; all passing |
+| Unit Tests | ✅ Complete | `tests/*.test.ts`, `tests/**/*.test.ts` | 115 tests across 13 files; all passing |
 | Persistence Tests | ✅ Complete | `tests/Persistence.test.ts` | Full storage layer coverage (OPFS, IndexedDB, Metroid neighbors) |
 | Model Tests | ✅ Complete | `tests/model/*.test.ts` | Profile resolution, defaults, routing policy |
 | Embedding Tests | ✅ Complete | `tests/embeddings/*.test.ts` | Provider resolver, runner, real/dummy backends |
@@ -180,7 +180,7 @@ This document tracks the implementation status of each major module in CORTEX. I
 
 | Layer | Completion | Critical Gap |
 |-------|-----------|--------------|
-| Foundation | 75% | Crypto helpers |
+| Foundation | 100% | — |
 | Storage | 100% | — |
 | Vector Compute | 100% | — |
 | Embedding | 83% | WebGL provider (low priority) |
@@ -203,14 +203,14 @@ This document tracks the implementation status of each major module in CORTEX. I
 - ✅ Generate real embeddings via Transformers.js
 - ✅ Resolve model profiles and derive routing policies
 - ✅ Run browser/Electron runtime harness
-- ✅ Pass 89 unit tests
+- ✅ Pass 115 unit tests
+- ✅ Hash text/binary content (SHA-256) and sign/verify Ed25519 signatures
 
 ## What Doesn't Work Today
 
 - ❌ **Cannot ingest text** — No chunking or hierarchy builder
 - ❌ **Cannot query memories** — No ranking pipeline or TSP solver
 - ❌ **Cannot consolidate** — No Daydreamer loop
-- ❌ **Cannot sign/verify** — No crypto helpers
 
 ---
 
@@ -220,10 +220,10 @@ This document tracks the implementation status of each major module in CORTEX. I
 
 **Goal:** Enable ingest and retrieval for a single user session.
 
-1. **Crypto Helpers** (`core/crypto/*`)
-   - Implement SHA-256 hashing
-   - Implement Ed25519 signing/verification
-   - Test coverage
+1. **Crypto Helpers** (`core/crypto/*`) ✅ **Complete**
+   - SHA-256 hashing for text and binary
+   - Ed25519 signing/verification
+   - 26 tests passing
 
 2. **Text Chunking** (`hippocampus/Chunker.ts`)
    - Token-aware splitting respecting ModelProfile limits
@@ -336,10 +336,6 @@ This document tracks the implementation status of each major module in CORTEX. I
 **Impact:** Cannot retrieve memories.
 **Mitigation:** Phase 1 priority; flat ranking acceptable for v0.1.
 
-### Blocker 3: No Crypto Helpers
-**Impact:** Cannot sign/verify pages (integrity risk).
-**Mitigation:** Phase 1 priority; required for trustworthy storage.
-
 ### Risk 1: TSP Complexity
 Open TSP is NP-hard; heuristic may be slow on large subgraphs.
 **Mitigation:** Bound subgraph size (<30 nodes); defer to Phase 2; use deterministic greedy heuristic.

TODO.md

@@ -10,30 +10,30 @@ This document contains a prioritized, actionable list of specific tasks required
 
 These items **must** be completed to have a usable system. Without them, users cannot ingest or query memories.
 
-### P0-A: Crypto Helpers (BLOCKS: all signed entity creation)
+### P0-A: Crypto Helpers (BLOCKS: all signed entity creation) ✅ COMPLETE
 
 **Why:** Pages require `contentHash`, `vectorHash`, and `signature`. Cannot create valid pages without crypto.
 
-- [ ] **P0-A1:** Implement `core/crypto/hash.ts`
+- [x] **P0-A1:** Implement `core/crypto/hash.ts`
   - SHA-256 for text content
   - SHA-256 for binary vector data
   - Test with known vectors
 
-- [ ] **P0-A2:** Implement `core/crypto/sign.ts`
+- [x] **P0-A2:** Implement `core/crypto/sign.ts`
   - Ed25519 key pair generation
   - Sign canonical page representation
   - Test with example pages
 
-- [ ] **P0-A3:** Implement `core/crypto/verify.ts`
+- [x] **P0-A3:** Implement `core/crypto/verify.ts`
   - Verify signature against public key
   - Test reject invalid signatures
 
-- [ ] **P0-A4:** Add crypto test coverage
+- [x] **P0-A4:** Add crypto test coverage
   - `tests/crypto/hash.test.ts`
   - `tests/crypto/sign.test.ts`
   - `tests/crypto/verify.test.ts`
 
-**Exit Criteria:** Can hash content, sign pages, verify signatures.
+**Exit Criteria:** Can hash content, sign pages, verify signatures. ✅ Met — 26 tests passing.
 
 ---
 
@@ -479,7 +479,7 @@ These items improve quality, performance, and developer experience. Not blockers
 
 | Phase | Items | Status | Blocking |
 |-------|-------|--------|----------|
-| v0.1 (Minimal Viable) | 17 tasks (P0-A through P0-E) | ❌ Not started | User cannot use system |
+| v0.1 (Minimal Viable) | 17 tasks (P0-A through P0-E) | 🟡 In Progress (P0-A complete) | User cannot use system |
 | v0.5 (Hierarchical + Coherent) | 13 tasks (P1-A through P1-F) | ❌ Not started | Blocked by v0.1 |
 | v1.0 (Background Consolidation) | 11 tasks (P2-A through P2-E) | ❌ Not started | Blocked by v0.5 |
 | Polish & Ship | 14 tasks (P3-A through P3-F) | ❌ Not started | Not blocking v1.0 |
@@ -492,13 +492,11 @@ These items improve quality, performance, and developer experience. Not blockers
 
 If you're reading this and want to know "what do I work on right now?", here's the answer:
 
-1. **P0-A1:** Implement `core/crypto/hash.ts` (SHA-256)
-2. **P0-A2:** Implement `core/crypto/sign.ts` (Ed25519)
-3. **P0-A3:** Implement `core/crypto/verify.ts`
-4. **P0-B1:** Implement `hippocampus/Chunker.ts`
-5. **P0-C1:** Implement `hippocampus/PageBuilder.ts`
-
-Complete these 5 tasks and you'll unblock the entire ingest path. Then move to P0-D (query) to complete v0.1.
+1. **P0-B1:** Implement `hippocampus/Chunker.ts`
+2. **P0-C1:** Implement `hippocampus/PageBuilder.ts`
+3. **P0-C2:** Implement `hippocampus/Ingest.ts`
+4. **P0-D1:** Implement `cortex/Query.ts`
+5. **P0-E1:** Implement `tests/integration/IngestQuery.test.ts`
 
 ---
 

core/crypto/hash.ts

@@ -0,0 +1,26 @@
+import type { Hash } from "../types.js";
+
+function bufferToHex(buffer: ArrayBuffer): string {
+  return Array.from(new Uint8Array(buffer))
+    .map(b => b.toString(16).padStart(2, "0"))
+    .join("");
+}
+
+/**
+ * Returns the SHA-256 hex digest of a UTF-8 encoded text string.
+ * Used to produce `contentHash` on Page entities.
+ */
+export async function hashText(content: string): Promise<Hash> {
+  const encoded = new TextEncoder().encode(content);
+  const buffer = await crypto.subtle.digest("SHA-256", encoded);
+  return bufferToHex(buffer);
+}
+
+/**
+ * Returns the SHA-256 hex digest of raw binary data.
+ * Used to produce `vectorHash` on Page entities.
+ */
+export async function hashBinary(data: BufferSource): Promise<Hash> {
+  const buffer = await crypto.subtle.digest("SHA-256", data);
+  return bufferToHex(buffer);
+}

core/crypto/sign.ts

@@ -0,0 +1,69 @@
+import type { PublicKey, Signature } from "../types.js";
+
+export interface KeyPair {
+  /** JWK JSON string — safe to store and share. */
+  publicKey: PublicKey;
+  /** JWK JSON string — store securely; used to reconstruct `signingKey`. */
+  privateKeyJwk: string;
+  /** Runtime CryptoKey ready for immediate signing operations. */
+  signingKey: CryptoKey;
+}
+
+function bufferToBase64(buffer: ArrayBuffer): Signature {
+  return btoa(String.fromCharCode(...new Uint8Array(buffer)));
+}
+
+/**
+ * Generates a new Ed25519 key pair.
+ * Returns the public key as a JWK string, the private key as both a JWK
+ * string (for secure storage) and a runtime `CryptoKey` (for signing).
+ */
+export async function generateKeyPair(): Promise<KeyPair> {
+  const keyPair = await crypto.subtle.generateKey(
+    { name: "Ed25519" } as Algorithm,
+    true,
+    ["sign", "verify"],
+  ) as CryptoKeyPair;
+
+  const [publicKeyJwk, privateKeyJwk] = await Promise.all([
+    crypto.subtle.exportKey("jwk", keyPair.publicKey),
+    crypto.subtle.exportKey("jwk", keyPair.privateKey),
+  ]);
+
+  return {
+    publicKey: JSON.stringify(publicKeyJwk),
+    privateKeyJwk: JSON.stringify(privateKeyJwk),
+    signingKey: keyPair.privateKey,
+  };
+}
+
+/**
+ * Imports a private key from its JWK JSON string for use in signing.
+ * Call this when restoring a key pair from persistent storage.
+ */
+export async function importSigningKey(privateKeyJwk: string): Promise<CryptoKey> {
+  const jwk = JSON.parse(privateKeyJwk) as JsonWebKey;
+  return crypto.subtle.importKey(
+    "jwk",
+    jwk,
+    { name: "Ed25519" } as Algorithm,
+    false,
+    ["sign"],
+  );
+}
+
+/**
+ * Signs arbitrary data with an Ed25519 private key.
+ * Returns a base64-encoded signature string.
+ *
+ * @param data   - UTF-8 string or raw bytes to sign.
+ * @param signingKey - CryptoKey from `generateKeyPair()` or `importSigningKey()`.
+ */
+export async function signData(
+  data: string | ArrayBuffer,
+  signingKey: CryptoKey,
+): Promise<Signature> {
+  const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+  const signatureBuffer = await crypto.subtle.sign("Ed25519", signingKey, bytes);
+  return bufferToBase64(signatureBuffer);
+}

core/crypto/verify.ts

@@ -0,0 +1,50 @@
+import type { PublicKey, Signature } from "../types.js";
+
+function base64ToBuffer(base64: Signature): ArrayBuffer | null {
+  try {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+      bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes.buffer;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Verifies an Ed25519 signature produced by `signData`.
+ *
+ * Returns `true` if `signature` is a valid Ed25519 signature over `data`
+ * by the key encoded in `publicKey` (JWK JSON string).
+ * Returns `false` for any signature mismatch or malformed signature.
+ * Throws for structurally invalid public key (malformed JWK JSON).
+ *
+ * @param data      - The original data that was signed (string or bytes).
+ * @param signature - Base64-encoded signature from `signData()`.
+ * @param publicKey - JWK JSON string from `KeyPair.publicKey`.
+ */
+export async function verifySignature(
+  data: string | ArrayBuffer,
+  signature: Signature,
+  publicKey: PublicKey,
+): Promise<boolean> {
+  const signatureBuffer = base64ToBuffer(signature);
+  if (signatureBuffer === null) {
+    return false;
+  }
+
+  const bytes = typeof data === "string" ? new TextEncoder().encode(data) : data;
+  const publicKeyJwk = JSON.parse(publicKey) as JsonWebKey;
+
+  const cryptoKey = await crypto.subtle.importKey(
+    "jwk",
+    publicKeyJwk,
+    { name: "Ed25519" } as Algorithm,
+    false,
+    ["verify"],
+  );
+
+  return crypto.subtle.verify("Ed25519", cryptoKey, signatureBuffer, bytes);
+}

tests/crypto/hash.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it } from "vitest";
+import { createHash } from "node:crypto";
+import { hashText, hashBinary } from "../../core/crypto/hash.js";
+
+describe("hashText", () => {
+  it("returns a 64-character hex string (SHA-256)", async () => {
+    const result = await hashText("hello");
+    expect(result).toHaveLength(64);
+    expect(result).toMatch(/^[0-9a-f]+$/);
+  });
+
+  it("cross-validates against node:crypto createHash for consistent output", async () => {
+    const inputs = ["hello", "world", "cortex memory engine", "abc", ""];
+    for (const input of inputs) {
+      const ours = await hashText(input);
+      const native = createHash("sha256").update(input).digest("hex");
+      expect(ours).toBe(native);
+    }
+  });
+
+  it("matches known SHA-256 digest for the empty string", async () => {
+    // SHA-256("") is a well-known NIST constant
+    const result = await hashText("");
+    expect(result).toBe("e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855");
+  });
+
+  it("produces different hashes for different inputs", async () => {
+    const h1 = await hashText("hello");
+    const h2 = await hashText("world");
+    expect(h1).not.toBe(h2);
+  });
+
+  it("is deterministic — same input yields identical hash", async () => {
+    const content = "deterministic test input";
+    const h1 = await hashText(content);
+    const h2 = await hashText(content);
+    expect(h1).toBe(h2);
+  });
+});
+
+describe("hashBinary", () => {
+  it("returns a 64-character hex string (SHA-256)", async () => {
+    const data = new Uint8Array([1, 2, 3, 4]);
+    const result = await hashBinary(data);
+    expect(result).toHaveLength(64);
+    expect(result).toMatch(/^[0-9a-f]+$/);
+  });
+
+  it("matches known SHA-256 digest for single zero byte", async () => {
+    // SHA-256(0x00) = 6e340b9cffb37a989ca544e6bb780a2c78901d3fb33738768511a30617afa01d
+    const data = new Uint8Array([0x00]);
+    const result = await hashBinary(data);
+    expect(result).toBe("6e340b9cffb37a989ca544e6bb780a2c78901d3fb33738768511a30617afa01d");
+  });
+
+  it("accepts ArrayBuffer input", async () => {
+    const data = new Uint8Array([0xde, 0xad, 0xbe, 0xef]).buffer;
+    const result = await hashBinary(data);
+    expect(result).toHaveLength(64);
+  });
+
+  it("produces different hashes for different byte arrays", async () => {
+    const h1 = await hashBinary(new Uint8Array([1, 2, 3]));
+    const h2 = await hashBinary(new Uint8Array([4, 5, 6]));
+    expect(h1).not.toBe(h2);
+  });
+
+  it("is consistent with hashText for the same encoded content", async () => {
+    const content = "consistent";
+    const textHash = await hashText(content);
+    const binaryHash = await hashBinary(new TextEncoder().encode(content));
+    expect(textHash).toBe(binaryHash);
+  });
+});