@labacacia/nps-sdk 1.0.0-alpha.1

package/tests/ncp/hello-frame.test.ts

@@ -0,0 +1,122 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Test Cases — NCP-H-01 through H-06: HelloFrame (0x06)
+// Source: test/ncp_test_cases.md §3.5
+
+import { describe, it, expect } from "vitest";
+import { NcpError } from "../../src/core/frame-header.js";
+import { NCP_ERROR_CODES } from "../../src/ncp/ncp-error-codes.js";
+import { validateHelloFrame, type HelloFrame } from "../../src/ncp/frames/hello-frame.js";
+
+function makeValidHello(): HelloFrame {
+  return {
+    frame: "0x06",
+    nps_version: "0.4",
+    supported_encodings: ["msgpack", "json"],
+    supported_protocols: ["ncp", "nwp"],
+  };
+}
+
+describe("NCP-H: HelloFrame (0x06)", () => {
+  // -----------------------------------------------------------------------
+  // NCP-H-01: First frame after TCP connect
+  // Spec: §3.5 — Client sends HelloFrame as very first frame
+  // -----------------------------------------------------------------------
+  it("NCP-H-01: accepts a valid HelloFrame with all required fields", () => {
+    const frame = makeValidHello();
+    expect(() => validateHelloFrame(frame)).not.toThrow();
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-H-02: HelloFrame Not First (protocol enforcement — out of scope for
+  //   unit test; validateHelloFrame validates structure only)
+  // -----------------------------------------------------------------------
+  it("NCP-H-02: valid HelloFrame structure passes validation", () => {
+    // Connection-ordering enforcement is a session-layer concern.
+    // validateHelloFrame validates fields only.
+    const frame = makeValidHello();
+    expect(() => validateHelloFrame(frame)).not.toThrow();
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-H-03: HelloFrame Missing Required Fields
+  // Spec: §3.5 — nps_version, supported_encodings, supported_protocols required
+  // -----------------------------------------------------------------------
+  it("NCP-H-03: rejects HelloFrame missing nps_version", () => {
+    const frame = { ...makeValidHello(), nps_version: "" } as HelloFrame;
+    expect(() => validateHelloFrame(frame)).toThrow(NcpError);
+    try {
+      validateHelloFrame(frame);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NPS-CLIENT-BAD-FRAME");
+    }
+  });
+
+  it("NCP-H-03: rejects HelloFrame missing supported_encodings", () => {
+    const frame = { ...makeValidHello(), supported_encodings: [] } as HelloFrame;
+    expect(() => validateHelloFrame(frame)).toThrow(NcpError);
+    try {
+      validateHelloFrame(frame);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NPS-CLIENT-BAD-FRAME");
+    }
+  });
+
+  it("NCP-H-03: rejects HelloFrame missing supported_protocols", () => {
+    const frame = { ...makeValidHello(), supported_protocols: [] } as HelloFrame;
+    expect(() => validateHelloFrame(frame)).toThrow(NcpError);
+    try {
+      validateHelloFrame(frame);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NPS-CLIENT-BAD-FRAME");
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-H-04: HelloFrame with ENC=1
+  // Spec: §3.5 — ENC=1 on HelloFrame before negotiation → NCP-ENC-NOT-NEGOTIATED
+  //   This is checked at the session layer (frame flags), not by validateHelloFrame.
+  //   We verify the expected error code is a known constant.
+  // -----------------------------------------------------------------------
+  it("NCP-H-04: NCP-ENC-NOT-NEGOTIATED is the named constant for pre-negotiation ENC=1", () => {
+    // Session-layer enforcement: if ENC=1 flag is set on HelloFrame,
+    // the receiver MUST return NCP-ENC-NOT-NEGOTIATED. We assert against the
+    // canonical constant rather than a raw string, and the negotiation path
+    // itself is exercised end-to-end in ncp-e2e-enc-reject.test.ts.
+    expect(NCP_ERROR_CODES.NCP_ENC_NOT_NEGOTIATED).toBe(
+      "NCP-ENC-NOT-NEGOTIATED",
+    );
+    // Sanity: the constant is a member of the NcpErrorCode union, which is
+    // the type-level promise that downstream code can rely on.
+    const code: (typeof NCP_ERROR_CODES)[keyof typeof NCP_ERROR_CODES] =
+      NCP_ERROR_CODES.NCP_ENC_NOT_NEGOTIATED;
+    expect(code).toBeDefined();
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-H-05: HelloFrame encoded Tier-2
+  // Spec: §3.5 — Tier-2 MsgPack is allowed during handshake
+  // -----------------------------------------------------------------------
+  it("NCP-H-05: validates HelloFrame regardless of encoding tier (structure only)", () => {
+    // Tier selection is a codec concern; validateHelloFrame validates fields.
+    const frame = makeValidHello();
+    expect(() => validateHelloFrame(frame)).not.toThrow();
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-H-06: min_version defaults to nps_version
+  // Spec: §3.5 — If min_version omitted, server treats as equal to nps_version
+  // -----------------------------------------------------------------------
+  it("NCP-H-06: accepts HelloFrame without min_version (optional field)", () => {
+    const frame = makeValidHello();
+    expect(frame.min_version).toBeUndefined();
+    expect(() => validateHelloFrame(frame)).not.toThrow();
+  });
+
+  it("NCP-H-06: accepts HelloFrame with explicit min_version", () => {
+    const frame = { ...makeValidHello(), min_version: "0.3" };
+    expect(() => validateHelloFrame(frame)).not.toThrow();
+    expect(frame.min_version).toBe("0.3");
+  });
+});

package/tests/ncp/inline-anchor.test.ts

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Test Cases — NCP-C-05, C-06, C-07: CapsFrame inline_anchor
+// Source: test/ncp_test_cases.md §3.4
+
+import { describe, it, expect } from "vitest";
+import { NcpError } from "../../src/core/frame-header.js";
+import { computeAnchorId, type FrameSchema } from "../../src/ncp/frames/anchor-frame.js";
+import { validateCapsFrame, type CapsFrame } from "../../src/ncp/frames/caps-frame.js";
+
+const schemaV1: FrameSchema = {
+  fields: [
+    { name: "id", type: "uint64", semantic: "entity.id" },
+    { name: "name", type: "string", semantic: "entity.label" },
+  ],
+};
+
+const schemaV2: FrameSchema = {
+  fields: [
+    { name: "id", type: "uint64", semantic: "entity.id" },
+    { name: "name", type: "string", semantic: "entity.label" },
+    { name: "price", type: "decimal", semantic: "commerce.price.usd" },
+  ],
+};
+
+function makeValidCaps(overrides?: Partial<CapsFrame>): CapsFrame {
+  return {
+    frame: "0x04",
+    anchor_ref: computeAnchorId(schemaV1),
+    count: 2,
+    data: [{ id: 1, name: "Alpha" }, { id: 2, name: "Beta" }],
+    ...overrides,
+  };
+}
+
+describe("NCP-C: CapsFrame inline_anchor", () => {
+  // -----------------------------------------------------------------------
+  // NCP-C-05: inline_anchor Present (Valid)
+  // CapsFrame with inline_anchor containing valid AnchorFrame
+  // (correct anchor_id = JCS+SHA-256 of schema). Expected: Success
+  // -----------------------------------------------------------------------
+  it("NCP-C-05: valid inline_anchor passes validation", () => {
+    const anchorId = computeAnchorId(schemaV1);
+    const frame = makeValidCaps({
+      inline_anchor: { anchor_id: anchorId, schema: schemaV1, ttl: 3600 },
+    });
+    expect(() => validateCapsFrame(frame)).not.toThrow();
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-C-06: inline_anchor anchor_id Mismatch
+  // anchor_id != recomputed JCS+SHA-256 of schema → NCP-ANCHOR-SCHEMA-INVALID
+  // cache NOT updated
+  // -----------------------------------------------------------------------
+  it("NCP-C-06: inline_anchor with wrong anchor_id throws NCP-ANCHOR-SCHEMA-INVALID", () => {
+    const frame = makeValidCaps({
+      inline_anchor: {
+        anchor_id: "sha256:deadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef",
+        schema: schemaV1,
+        ttl: 3600,
+      },
+    });
+    expect(() => validateCapsFrame(frame)).toThrow(NcpError);
+    try {
+      validateCapsFrame(frame);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-ANCHOR-SCHEMA-INVALID");
+    }
+  });
+
+  // -----------------------------------------------------------------------
+  // NCP-C-07: inline_anchor Auto-Update Flow
+  // Outer anchor_ref points to NEW anchor; inline_anchor carries its AnchorFrame.
+  // Old anchor retired from cache, new cached. Expected: Success
+  // -----------------------------------------------------------------------
+  it("NCP-C-07: inline_anchor with new schema version passes validation", () => {
+    const newAnchorId = computeAnchorId(schemaV2);
+    const frame = makeValidCaps({
+      anchor_ref: newAnchorId, // outer ref points to new anchor
+      inline_anchor: { anchor_id: newAnchorId, schema: schemaV2, ttl: 3600 },
+    });
+    expect(() => validateCapsFrame(frame)).not.toThrow();
+    // Cache update (retire old, store new) is a session-layer concern.
+    // validateCapsFrame confirms the inline_anchor is structurally valid.
+    expect(frame.inline_anchor!.anchor_id).toBe(newAnchorId);
+  });
+});

package/tests/ncp/security.test.ts

@@ -0,0 +1,184 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Test Cases — Group 5: Security & Edge Cases
+// Covers: NCP-SEC-01 to NCP-SEC-05
+// Source: test/ncp_test_cases.md §5
+
+import { describe, it, expect } from "vitest";
+import {
+  FrameType,
+  NcpError,
+  buildFlags,
+  EncodingTier,
+} from "../../src/core/frame-header.js";
+import { encodeFrame, decodeFrame } from "../../src/core/codecs/ncp-codec.js";
+import { FrameRegistry } from "../../src/core/frame-registry.js";
+
+// ===========================================================================
+// NCP-SEC-01: Replay Attack
+// ===========================================================================
+
+describe("NCP-SEC-01: Replay Attack", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §7.1 — Replay handled by TLS. Non-TLS: Agent SHOULD use nonce.
+  // Codec preserves nonce field for application-level dedup.
+  // -----------------------------------------------------------------------
+  it("preserves nonce field in round-trip", () => {
+    const query = {
+      frame: "0x10",
+      anchor_ref: "sha256:abc",
+      nonce: "550e8400-e29b-41d4-a716-446655440000",
+      limit: 10,
+    };
+
+    const encoded = encodeFrame(query, { frameType: FrameType.Query });
+    const result = decodeFrame(encoded);
+    const decoded = result.payload as typeof query;
+
+    expect(decoded.nonce).toBe("550e8400-e29b-41d4-a716-446655440000");
+  });
+});
+
+// ===========================================================================
+// NCP-SEC-02: Encryption Bit Mismatch
+// ===========================================================================
+
+describe("NCP-SEC-02: Encryption Bit Mismatch", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §7.4 — ENC=1 but payload is plain JSON → decryption failure
+  // At codec level: ENC=1 means payload has Nonce(12B) + ciphertext + Tag(16B).
+  // Plain JSON payload with ENC=1 will fail structure check.
+  // -----------------------------------------------------------------------
+  it("detects ENC flag mismatch (plain payload with ENC=1)", () => {
+    // Craft frame: ENC=1 flag but plain JSON payload
+    const payload = new TextEncoder().encode('{"frame":"0x01"}');
+    const flags = buildFlags({ encrypted: true }); // ENC=1
+
+    const header = new Uint8Array(4);
+    header[0] = FrameType.Anchor;
+    header[1] = flags;
+    const view = new DataView(header.buffer);
+    view.setUint16(2, payload.length, false);
+
+    const frame = new Uint8Array(header.length + payload.length);
+    frame.set(header);
+    frame.set(payload, header.length);
+
+    // Decode succeeds at codec level (JSON is valid bytes),
+    // but the ENC flag signals encryption was expected.
+    // Application layer should check header.isEncrypted and reject.
+    const result = decodeFrame(frame);
+    expect(result.header.isEncrypted).toBe(true);
+    // Application MUST reject: ENC=1 but got plaintext
+  });
+});
+
+// ===========================================================================
+// NCP-SEC-03: Large Frame Attack
+// ===========================================================================
+
+describe("NCP-SEC-03: Large Frame Attack", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §3.3 — EXT=1 max 4GB. Check memory limits before allocation.
+  // -----------------------------------------------------------------------
+  it("rejects frame exceeding memory limit", () => {
+    // Craft extended header declaring a huge payload
+    const header = new Uint8Array(8);
+    header[0] = FrameType.Anchor;
+    header[1] = 0x80; // EXT=1
+    const view = new DataView(header.buffer);
+    view.setUint32(2, 256 * 1024 * 1024, false); // 256MB
+    header[6] = 0;
+    header[7] = 0;
+
+    // Decode with small max_frame_payload
+    expect(() => decodeFrame(header, { maxFramePayload: 1024 * 1024 })).toThrow(
+      NcpError,
+    );
+    try {
+      decodeFrame(header, { maxFramePayload: 1024 * 1024 });
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-FRAME-PAYLOAD-TOO-LARGE");
+    }
+  });
+});
+
+// ===========================================================================
+// NCP-SEC-04: Invalid Port Routing
+// ===========================================================================
+
+describe("NCP-SEC-04: Invalid Port Routing", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §2.3 — Frame type determines protocol. Wrong protocol → unknown type.
+  // -----------------------------------------------------------------------
+  it("rejects NIP frame in NCP-only registry", () => {
+    // Create registry with only NCP frames
+    const registry = FrameRegistry.createDefault();
+
+    // NIP IdentFrame (0x20) — should be unknown if not registered
+    // Default registry doesn't include NIP frames beyond the basic set
+    // Let's test with a truly unregistered type
+    expect(() => registry.resolve(0x88)).toThrow(NcpError);
+    try {
+      registry.resolve(0x88);
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-FRAME-UNKNOWN-TYPE");
+    }
+  });
+
+  it("routes frame types to correct protocols", () => {
+    const registry = FrameRegistry.createDefault();
+
+    // NCP frames resolve to "ncp"
+    expect(registry.resolve(FrameType.Anchor).protocol).toBe("ncp");
+    // System frames resolve to "system"
+    expect(registry.resolve(FrameType.Error).protocol).toBe("system");
+  });
+});
+
+// ===========================================================================
+// NCP-SEC-05: Protocol Version Check
+// ===========================================================================
+
+describe("NCP-SEC-05: Protocol Version Check", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §2.6 — Client min_version > server version → NCP-VERSION-INCOMPATIBLE
+  // -----------------------------------------------------------------------
+  it("detects version incompatibility in HelloFrame", () => {
+    const hello = {
+      frame: "0x06",
+      nps_version: "0.5",
+      min_version: "0.5",
+      supported_encodings: ["json"],
+      supported_protocols: ["ncp"],
+    };
+
+    const serverVersion = "0.4";
+
+    // Simple version check: client's min > server's version
+    const clientMin = parseFloat(hello.min_version);
+    const serverMax = parseFloat(serverVersion);
+
+    expect(clientMin).toBeGreaterThan(serverMax);
+
+    // Server would return this error
+    const error = {
+      frame: "0xFE",
+      status: "NPS-PROTO-VERSION-INCOMPATIBLE",
+      error: "NCP-VERSION-INCOMPATIBLE",
+      message: "No compatible NPS version",
+      details: {
+        server_version: serverVersion,
+        client_min_version: hello.min_version,
+      },
+    };
+    expect(error.error).toBe("NCP-VERSION-INCOMPATIBLE");
+  });
+
+  it("accepts compatible versions", () => {
+    const clientMin = parseFloat("0.3");
+    const serverMax = parseFloat("0.4");
+    expect(serverMax).toBeGreaterThanOrEqual(clientMin); // compatible
+  });
+});

package/tests/ncp/stream-window.test.ts

@@ -0,0 +1,167 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// NCP Test Cases — StreamManager window-based flow control
+// Covers: NCP-S-07 through NCP-S-11
+// Source: test/ncp_test_cases.md §3.3
+
+import { describe, it, expect } from "vitest";
+import { NcpError } from "../../src/core/frame-header.js";
+import { StreamManager } from "../../src/ncp/stream-manager.js";
+import type { StreamFrame } from "../../src/ncp/frames/stream-frame.js";
+
+function outgoing(
+  streamId: string,
+  seq: number,
+  data: unknown[],
+  opts?: { is_last?: boolean; window_size?: number },
+): StreamFrame {
+  return {
+    frame: "0x03",
+    stream_id: streamId,
+    seq,
+    is_last: opts?.is_last ?? false,
+    data,
+    window_size: opts?.window_size,
+  };
+}
+
+// ===========================================================================
+// NCP-S-07: Initial Window
+// ===========================================================================
+
+describe("NCP-S-07: Initial window_size on seq=0 initialises remainingWindow", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §3.3 — window_size=5 on seq=0 sets remainingWindow=5; each send
+  // decrements it by 1.
+  // -----------------------------------------------------------------------
+  it("initialises remainingWindow=5 and decrements on each send", () => {
+    const mgr = new StreamManager();
+
+    // Opening frame with window_size=5 — does not consume a window slot.
+    mgr.send(outgoing("s1", 0, [], { window_size: 5 }));
+    // After 0 sends: isPaused must be false; 5 sends should succeed.
+    expect(mgr.isPaused("s1")).toBe(false);
+
+    // Five sends should each succeed.
+    mgr.send(outgoing("s1", 1, ["a"]));
+    mgr.send(outgoing("s1", 2, ["b"]));
+    mgr.send(outgoing("s1", 3, ["c"]));
+    mgr.send(outgoing("s1", 4, ["d"]));
+    mgr.send(outgoing("s1", 5, ["e"]));
+
+    // Window now exhausted — next send must throw.
+    expect(() => mgr.send(outgoing("s1", 6, ["f"]))).toThrowError(NcpError);
+    try {
+      mgr.send(outgoing("s1", 6, ["f"]));
+    } catch (e) {
+      expect((e as NcpError).code).toBe("NCP-STREAM-WINDOW-OVERFLOW");
+    }
+  });
+});
+
+// ===========================================================================
+// NCP-S-08: No Flow Control
+// ===========================================================================
+
+describe("NCP-S-08: No window_size means unlimited sends", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §3.3 — absence of window_size disables flow control entirely.
+  // -----------------------------------------------------------------------
+  it("allows unlimited sends when no window_size is set", () => {
+    const mgr = new StreamManager();
+
+    // Opening frame without window_size.
+    mgr.send(outgoing("s1", 0, []));
+
+    // Many sends must all succeed without any exception.
+    for (let i = 1; i <= 100; i++) {
+      expect(() => mgr.send(outgoing("s1", i, ["x"]))).not.toThrow();
+    }
+  });
+});
+
+// ===========================================================================
+// NCP-S-09: Reverse Refill
+// ===========================================================================
+
+describe("NCP-S-09: updateWindow replaces remainingWindow with new_size", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §3.3 — a reverse-direction frame (data=[], window_size=N) refills
+  // the sender's window to exactly N.
+  // -----------------------------------------------------------------------
+  it("replaces exhausted window with new_size=10 and allows further sends", () => {
+    const mgr = new StreamManager();
+
+    mgr.send(outgoing("s1", 0, [], { window_size: 2 }));
+    mgr.send(outgoing("s1", 1, ["a"]));
+    mgr.send(outgoing("s1", 2, ["b"]));
+
+    // Window exhausted.
+    expect(() => mgr.send(outgoing("s1", 3, ["c"]))).toThrowError(NcpError);
+
+    // Reverse refill: updateWindow with new_size=10.
+    mgr.updateWindow("s1", 10);
+    expect(mgr.isPaused("s1")).toBe(false);
+
+    // Ten more sends should succeed.
+    for (let i = 3; i <= 12; i++) {
+      expect(() => mgr.send(outgoing("s1", i, ["x"]))).not.toThrow();
+    }
+
+    // 11th send after refill must throw again.
+    expect(() => mgr.send(outgoing("s1", 13, ["y"]))).toThrowError(NcpError);
+  });
+});
+
+// ===========================================================================
+// NCP-S-10: Pause and Resume
+// ===========================================================================
+
+describe("NCP-S-10: window_size=0 sets pause state; non-zero refill resumes", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §3.3 — receiver sends window_size=0 to pause the sender; a later
+  // non-zero window_size resumes it.
+  // -----------------------------------------------------------------------
+  it("sets pause when updateWindow(0) and clears it on non-zero refill", () => {
+    const mgr = new StreamManager();
+
+    mgr.send(outgoing("s1", 0, [], { window_size: 5 }));
+    expect(mgr.isPaused("s1")).toBe(false);
+
+    // Receiver signals pause.
+    mgr.updateWindow("s1", 0);
+    expect(mgr.isPaused("s1")).toBe(true);
+
+    // Receiver sends non-zero refill → resume.
+    mgr.updateWindow("s1", 5);
+    expect(mgr.isPaused("s1")).toBe(false);
+  });
+});
+
+// ===========================================================================
+// NCP-S-11: Overflow
+// ===========================================================================
+
+describe("NCP-S-11: send when remainingWindow=0 throws NCP-STREAM-WINDOW-OVERFLOW", () => {
+  // -----------------------------------------------------------------------
+  // Spec: §3.3 — sending while window is exhausted is a protocol violation.
+  // -----------------------------------------------------------------------
+  it("throws NcpError with code NCP-STREAM-WINDOW-OVERFLOW", () => {
+    const mgr = new StreamManager();
+
+    mgr.send(outgoing("s1", 0, [], { window_size: 1 }));
+    mgr.send(outgoing("s1", 1, ["a"])); // consumes the only slot
+
+    // Window is now 0 — next send must throw with the correct error code.
+    let caught: unknown;
+    try {
+      mgr.send(outgoing("s1", 2, ["b"]));
+    } catch (e) {
+      caught = e;
+    }
+
+    expect(caught).toBeInstanceOf(NcpError);
+    expect((caught as NcpError).code).toBe("NCP-STREAM-WINDOW-OVERFLOW");
+  });
+});