@labacacia/nps-sdk 1.0.0-alpha.1

package/nip-ca-server/src/db.ts

@@ -0,0 +1,104 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+import Database from "better-sqlite3";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const SCHEMA_PATH = path.join(__dirname, "..", "db", "001_init.sql");
+
+export interface CertRecord {
+  id: number;
+  nid: string;
+  entity_type: string;
+  serial: string;
+  pub_key: string;
+  capabilities: string[];
+  scope: Record<string, unknown>;
+  issued_by: string;
+  issued_at: string;
+  expires_at: string;
+  revoked_at: string | null;
+  revoke_reason: string | null;
+  metadata: Record<string, unknown> | null;
+}
+
+export class CaDb {
+  private db: Database.Database;
+
+  constructor(dbPath: string) {
+    fs.mkdirSync(path.dirname(dbPath), { recursive: true });
+    this.db = new Database(dbPath);
+    this.db.pragma("journal_mode = WAL");
+    this.db.pragma("foreign_keys = ON");
+    this.db.exec(fs.readFileSync(SCHEMA_PATH, "utf8"));
+  }
+
+  nextSerial(): string {
+    const row = this.db
+      .prepare(
+        "SELECT COALESCE(MAX(CAST(REPLACE(serial,'0x','') AS INTEGER)),0)+1 AS n FROM nip_certificates",
+      )
+      .get() as { n: number };
+    return `0x${row.n.toString(16).toUpperCase().padStart(6, "0")}`;
+  }
+
+  insert(rec: {
+    nid: string; entity_type: string; serial: string; pub_key: string;
+    capabilities: string[]; scope: Record<string, unknown>; issued_by: string;
+    issued_at: string; expires_at: string; metadata?: Record<string, unknown> | null;
+  }): number {
+    const result = this.db.prepare(
+      `INSERT INTO nip_certificates
+       (nid, entity_type, serial, pub_key, capabilities, scope_json,
+        issued_by, issued_at, expires_at, metadata_json)
+       VALUES (?,?,?,?,?,?,?,?,?,?)`,
+    ).run(
+      rec.nid, rec.entity_type, rec.serial, rec.pub_key,
+      JSON.stringify(rec.capabilities), JSON.stringify(rec.scope),
+      rec.issued_by, rec.issued_at, rec.expires_at,
+      rec.metadata ? JSON.stringify(rec.metadata) : null,
+    );
+    return Number(result.lastInsertRowid);
+  }
+
+  getActive(nid: string): CertRecord | null {
+    const row = this.db.prepare(
+      `SELECT * FROM nip_certificates
+       WHERE nid=? AND revoked_at IS NULL
+       ORDER BY issued_at DESC LIMIT 1`,
+    ).get(nid);
+    return row ? this._toRecord(row as any) : null;
+  }
+
+  revoke(nid: string, reason: string): boolean {
+    const now = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+    const r = this.db.prepare(
+      "UPDATE nip_certificates SET revoked_at=?, revoke_reason=? WHERE nid=? AND revoked_at IS NULL",
+    ).run(now, reason, nid);
+    return r.changes > 0;
+  }
+
+  crl(): Array<{ serial: string; nid: string; revoked_at: string; revoke_reason: string | null }> {
+    return this.db.prepare(
+      "SELECT serial, nid, revoked_at, revoke_reason FROM nip_certificates WHERE revoked_at IS NOT NULL ORDER BY revoked_at DESC",
+    ).all() as any;
+  }
+
+  private _toRecord(row: any): CertRecord {
+    return {
+      id: row.id,
+      nid: row.nid,
+      entity_type: row.entity_type,
+      serial: row.serial,
+      pub_key: row.pub_key,
+      capabilities: JSON.parse(row.capabilities),
+      scope: JSON.parse(row.scope_json),
+      issued_by: row.issued_by,
+      issued_at: row.issued_at,
+      expires_at: row.expires_at,
+      revoked_at: row.revoked_at ?? null,
+      revoke_reason: row.revoke_reason ?? null,
+      metadata: row.metadata_json ? JSON.parse(row.metadata_json) : null,
+    };
+  }
+}

package/nip-ca-server/src/index.ts

@@ -0,0 +1,157 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import Fastify from "fastify";
+import { CaDb } from "./db.js";
+import * as ca from "./ca.js";
+
+// ── Config ────────────────────────────────────────────────────────────────────
+const CA_NID        = process.env["NIP_CA_NID"]!;
+const CA_PASSPHRASE = process.env["NIP_CA_PASSPHRASE"]!;
+const CA_BASE_URL   = (process.env["NIP_CA_BASE_URL"] ?? "").replace(/\/$/, "");
+const KEY_FILE      = process.env["NIP_CA_KEY_FILE"]     ?? "/data/ca.key.enc";
+const DB_PATH       = process.env["NIP_CA_DB_PATH"]      ?? "/data/ca.db";
+const DISPLAY_NAME  = process.env["NIP_CA_DISPLAY_NAME"] ?? "NPS CA";
+const AGENT_DAYS    = parseInt(process.env["NIP_CA_AGENT_VALIDITY_DAYS"] ?? "30");
+const NODE_DAYS     = parseInt(process.env["NIP_CA_NODE_VALIDITY_DAYS"]  ?? "90");
+const RENEWAL_DAYS  = parseInt(process.env["NIP_CA_RENEWAL_WINDOW_DAYS"] ?? "7");
+const PORT          = parseInt(process.env["PORT"] ?? "17440");
+
+for (const k of ["NIP_CA_NID", "NIP_CA_PASSPHRASE", "NIP_CA_BASE_URL"]) {
+  if (!process.env[k]) throw new Error(`${k} is required`);
+}
+
+const CA_DOMAIN = CA_NID.split(":").slice(-2)[0] ?? "ca.local";
+
+// ── Bootstrap ─────────────────────────────────────────────────────────────────
+let caPriv: crypto.KeyObject;
+let caPubStr: string;
+
+if (!fs.existsSync(KEY_FILE)) {
+  caPriv = ca.generateKey();
+  ca.saveKey(caPriv, KEY_FILE, CA_PASSPHRASE);
+} else {
+  caPriv = ca.loadKey(KEY_FILE, CA_PASSPHRASE);
+}
+caPubStr = ca.pubKeyString(crypto.createPublicKey(caPriv));
+
+const db = new CaDb(DB_PATH);
+
+// ── Server ─────────────────────────────────────────────────────────────────────
+const app = Fastify({ logger: true });
+
+// ── Helpers ────────────────────────────────────────────────────────────────────
+function register(
+  body: { nid?: string; pub_key: string; capabilities?: string[]; scope?: object; metadata?: object },
+  entityType: string,
+  validityDays: number,
+  reply: any,
+): void {
+  const nid = body.nid ?? ca.generateNid(CA_DOMAIN, entityType);
+  if (db.getActive(nid)) {
+    reply.code(409).send({ error_code: "NIP-CA-NID-ALREADY-EXISTS",
+      message: `${nid} already has an active certificate` });
+    return;
+  }
+  const serial = db.nextSerial();
+  const cert = ca.issueCert(caPriv, CA_NID, nid, body.pub_key,
+    body.capabilities ?? [], body.scope as any ?? {}, validityDays, serial,
+    (body as any).metadata ?? null);
+  db.insert({ nid, entity_type: entityType, serial, pub_key: body.pub_key,
+    capabilities: body.capabilities ?? [], scope: body.scope as any ?? {},
+    issued_by: CA_NID, issued_at: cert.issued_at, expires_at: cert.expires_at,
+    metadata: (body as any).metadata ?? null });
+  reply.code(201).send({ nid, serial, issued_at: cert.issued_at,
+    expires_at: cert.expires_at, ident_frame: cert });
+}
+
+// ── Routes ─────────────────────────────────────────────────────────────────────
+app.post("/v1/agents/register", async (req, reply) => {
+  register(req.body as any, "agent", AGENT_DAYS, reply);
+});
+
+app.post("/v1/nodes/register", async (req, reply) => {
+  register(req.body as any, "node", NODE_DAYS, reply);
+});
+
+app.post<{ Params: { "*": string } }>("/v1/agents/*", async (req, reply) => {
+  const parts = (req.params["*"] as string).split("/");
+  const action = parts.pop();
+  const nid = parts.join("/");
+
+  if (action === "renew") {
+    const rec = db.getActive(nid);
+    if (!rec) return reply.code(404).send({ error_code: "NIP-CA-NID-NOT-FOUND", message: `${nid} not found` });
+    const expMs = new Date(rec.expires_at).getTime();
+    const daysLeft = Math.floor((expMs - Date.now()) / 86400_000);
+    if (daysLeft > RENEWAL_DAYS)
+      return reply.code(400).send({ error_code: "NIP-CA-RENEWAL-TOO-EARLY",
+        message: `Renewal window opens in ${daysLeft - RENEWAL_DAYS} days` });
+    const serial = db.nextSerial();
+    const days = rec.entity_type === "agent" ? AGENT_DAYS : NODE_DAYS;
+    const cert = ca.issueCert(caPriv, CA_NID, nid, rec.pub_key,
+      rec.capabilities, rec.scope, days, serial, rec.metadata);
+    db.insert({ nid, entity_type: rec.entity_type, serial, pub_key: rec.pub_key,
+      capabilities: rec.capabilities, scope: rec.scope,
+      issued_by: CA_NID, issued_at: cert.issued_at, expires_at: cert.expires_at,
+      metadata: rec.metadata });
+    return reply.send({ nid, serial, issued_at: cert.issued_at,
+      expires_at: cert.expires_at, ident_frame: cert });
+  }
+
+  if (action === "revoke") {
+    const body = req.body as any;
+    if (!db.revoke(nid, body?.reason ?? "cessation_of_operation"))
+      return reply.code(404).send({ error_code: "NIP-CA-NID-NOT-FOUND",
+        message: `${nid} not found or already revoked` });
+    return reply.send({ nid, revoked_at: new Date().toISOString().replace(/\.\d{3}Z$/, "Z"),
+      reason: body?.reason ?? "cessation_of_operation" });
+  }
+
+  reply.code(404).send({ message: "Not found" });
+});
+
+app.get<{ Params: { "*": string } }>("/v1/agents/*", async (req, reply) => {
+  const parts = (req.params["*"] as string).split("/");
+  const action = parts.pop();
+  const nid = parts.join("/");
+
+  if (action === "verify") {
+    const rec = db.getActive(nid);
+    if (!rec) return reply.code(404).send({ error_code: "NIP-CA-NID-NOT-FOUND", message: `${nid} not found` });
+    const valid = new Date(rec.expires_at).getTime() > Date.now();
+    return reply.send({ valid, nid, entity_type: rec.entity_type, pub_key: rec.pub_key,
+      capabilities: rec.capabilities, issued_by: rec.issued_by,
+      issued_at: rec.issued_at, expires_at: rec.expires_at, serial: rec.serial,
+      error_code: valid ? null : "NIP-CERT-EXPIRED" });
+  }
+  reply.code(404).send({ message: "Not found" });
+});
+
+app.get("/v1/ca/cert", async (_req, reply) =>
+  reply.send({ nid: CA_NID, display_name: DISPLAY_NAME, pub_key: caPubStr, algorithm: "ed25519" }));
+
+app.get("/v1/crl", async (_req, reply) =>
+  reply.send({ revoked: db.crl() }));
+
+app.get("/.well-known/nps-ca", async (_req, reply) =>
+  reply.send({
+    nps_ca: "0.1", issuer: CA_NID, display_name: DISPLAY_NAME, public_key: caPubStr,
+    algorithms: ["ed25519"],
+    endpoints: {
+      register: `${CA_BASE_URL}/v1/agents/register`,
+      verify:   `${CA_BASE_URL}/v1/agents/{nid}/verify`,
+      ocsp:     `${CA_BASE_URL}/v1/agents/{nid}/verify`,
+      crl:      `${CA_BASE_URL}/v1/crl`,
+    },
+    capabilities: ["agent", "node"],
+    max_cert_validity_days: Math.max(AGENT_DAYS, NODE_DAYS),
+  }));
+
+app.get("/health", async (_req, reply) => reply.send({ status: "ok" }));
+
+app.listen({ port: PORT, host: "0.0.0.0" }, (err) => {
+  if (err) { console.error(err); process.exit(1); }
+  console.log(`NIP CA Server listening on :${PORT}`);
+});

package/nip-ca-server/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["src"]
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@labacacia/nps-sdk",
+  "version": "1.0.0-alpha.1",
+  "description": "TypeScript SDK for the Neural Protocol Suite (NPS)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    },
+    "./core": {
+      "import": "./dist/core/index.js",
+      "types": "./dist/core/index.d.ts"
+    },
+    "./ncp": {
+      "import": "./dist/ncp/index.js",
+      "types": "./dist/ncp/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/labacacia/nps.git",
+    "directory": "impl/typescript"
+  },
+  "license": "Apache-2.0",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "dependencies": {
+    "@msgpack/msgpack": "^3.0.0",
+    "canonicalize": "^2.0.0",
+    "fast-json-patch": "^3.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^3.1.0"
+  }
+}

package/src/core/anchor-cache.ts

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// AnchorCache — Schema cache with TTL, LRU eviction, poison detection
+// NPS-1 §5.3, §7.2, §9
+
+import { NcpError } from "./frame-header.js";
+import type { AnchorFrame } from "../ncp/frames/anchor-frame.js";
+
+interface CacheEntry {
+  frame: AnchorFrame;
+  expiresAt: number; // epoch ms
+  lastAccessed: number; // epoch ms
+}
+
+/**
+ * AnchorFrame cache with:
+ * - TTL-based expiry (NPS-1 §5.3)
+ * - LRU eviction at maxSize (NPS-1 §9, default 1000)
+ * - Anchor poisoning detection (NPS-1 §7.2)
+ */
+export class AnchorCache {
+  private readonly cache = new Map<string, CacheEntry>();
+  private readonly maxSize: number;
+  private readonly getNow: () => number;
+
+  constructor(options?: { maxSize?: number; getNow?: () => number }) {
+    this.maxSize = options?.maxSize ?? 1000;
+    this.getNow = options?.getNow ?? (() => Date.now());
+  }
+
+  /**
+   * Cache an AnchorFrame.
+   *
+   * - ttl=0: frame is valid but not cached (NPS-1 §4.1)
+   * - Same anchor_id + same schema: idempotent (no-op)
+   * - Same anchor_id + different schema: NCP-ANCHOR-ID-MISMATCH (poison detection)
+   *
+   * @throws {NcpError} NCP-ANCHOR-ID-MISMATCH on anchor poisoning.
+   */
+  set(frame: AnchorFrame): void {
+    // ttl=0 means use once, don't cache
+    if (frame.ttl === 0) return;
+
+    const existing = this.cache.get(frame.anchor_id);
+    if (existing) {
+      // Poison detection: same ID, different schema
+      const existingJson = JSON.stringify(existing.frame.schema);
+      const newJson = JSON.stringify(frame.schema);
+      if (existingJson !== newJson) {
+        throw new NcpError(
+          "NCP-ANCHOR-ID-MISMATCH",
+          `Anchor poisoning detected: anchor_id ${frame.anchor_id} received with different schema`,
+        );
+      }
+      // Same schema — idempotent, update access time
+      existing.lastAccessed = this.getNow();
+      return;
+    }
+
+    // LRU eviction if at capacity
+    if (this.cache.size >= this.maxSize) {
+      this.evictLru();
+    }
+
+    const ttlMs = (frame.ttl ?? 3600) * 1000;
+    this.cache.set(frame.anchor_id, {
+      frame,
+      expiresAt: this.getNow() + ttlMs,
+      lastAccessed: this.getNow(),
+    });
+  }
+
+  /**
+   * Get a cached AnchorFrame by anchor_id.
+   *
+   * @returns The cached frame, or null if not found or expired.
+   */
+  get(anchorId: string): AnchorFrame | null {
+    const entry = this.cache.get(anchorId);
+    if (!entry) return null;
+
+    // Check TTL expiry
+    if (this.getNow() >= entry.expiresAt) {
+      this.cache.delete(anchorId);
+      return null;
+    }
+
+    entry.lastAccessed = this.getNow();
+    return entry.frame;
+  }
+
+  /**
+   * Get a cached AnchorFrame, throwing if not found.
+   * @throws {NcpError} NCP-ANCHOR-NOT-FOUND if not in cache or expired.
+   */
+  getRequired(anchorId: string): AnchorFrame {
+    const frame = this.get(anchorId);
+    if (!frame) {
+      throw new NcpError(
+        "NCP-ANCHOR-NOT-FOUND",
+        `Schema anchor ${anchorId} not found in cache`,
+      );
+    }
+    return frame;
+  }
+
+  /** Current cache size. */
+  get size(): number {
+    return this.cache.size;
+  }
+
+  /** Evict the least recently accessed entry. */
+  private evictLru(): void {
+    let oldestKey: string | undefined;
+    let oldestTime = Infinity;
+
+    for (const [key, entry] of this.cache) {
+      if (entry.lastAccessed < oldestTime) {
+        oldestTime = entry.lastAccessed;
+        oldestKey = key;
+      }
+    }
+
+    if (oldestKey) {
+      this.cache.delete(oldestKey);
+    }
+  }
+}

package/src/core/cache.ts

@@ -0,0 +1,93 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * AnchorFrameCache — in-process cache for AnchorFrame instances (NPS-1 §4.1).
+ */
+
+import { createHash } from "node:crypto";
+import { NpsAnchorNotFoundError, NpsAnchorPoisonError } from "./exceptions.js";
+import type { AnchorFrame, FrameSchema } from "../ncp/frames.js";
+
+export class AnchorFrameCache {
+  private readonly _store = new Map<string, { frame: AnchorFrame; expiresAt: number }>();
+
+  // Allow clock injection for testing
+  clock: () => number = () => Date.now();
+
+  // ── Public API ────────────────────────────────────────────────────────────
+
+  set(frame: AnchorFrame): string {
+    const anchorId = frame.anchorId.startsWith("sha256:")
+      ? frame.anchorId
+      : AnchorFrameCache.computeAnchorId(frame.schema);
+
+    const existing = this._store.get(anchorId);
+    if (existing !== undefined && this.clock() < existing.expiresAt) {
+      if (!AnchorFrameCache._schemasEqual(existing.frame.schema, frame.schema)) {
+        throw new NpsAnchorPoisonError(anchorId);
+      }
+      // Same schema — idempotent; refresh TTL below
+    }
+
+    const ttlMs   = (frame.ttl ?? 3600) * 1000;
+    const expiresAt = this.clock() + ttlMs;
+    this._store.set(anchorId, { frame, expiresAt });
+    return anchorId;
+  }
+
+  get(anchorId: string): AnchorFrame | undefined {
+    const entry = this._store.get(anchorId);
+    if (entry === undefined) return undefined;
+    if (this.clock() > entry.expiresAt) {
+      this._store.delete(anchorId);
+      return undefined;
+    }
+    return entry.frame;
+  }
+
+  getRequired(anchorId: string): AnchorFrame {
+    const frame = this.get(anchorId);
+    if (frame === undefined) throw new NpsAnchorNotFoundError(anchorId);
+    return frame;
+  }
+
+  invalidate(anchorId: string): void {
+    this._store.delete(anchorId);
+  }
+
+  get size(): number {
+    this._evictExpired();
+    return this._store.size;
+  }
+
+  // ── Static helpers ────────────────────────────────────────────────────────
+
+  static computeAnchorId(schema: FrameSchema): string {
+    const sorted = [...schema.fields]
+      .map((f) => {
+        const obj: Record<string, unknown> = { name: f.name, type: f.type };
+        if (f.semantic !== undefined) obj["semantic"] = f.semantic;
+        if (f.nullable !== undefined) obj["nullable"] = f.nullable;
+        return obj;
+      })
+      .sort((a, b) => String(a["name"]).localeCompare(String(b["name"])));
+
+    const canonical = JSON.stringify(sorted);
+    const digest    = createHash("sha256").update(canonical, "utf8").digest("hex");
+    return `sha256:${digest}`;
+  }
+
+  // ── Private ───────────────────────────────────────────────────────────────
+
+  private _evictExpired(): void {
+    const now = this.clock();
+    for (const [k, entry] of this._store) {
+      if (now > entry.expiresAt) this._store.delete(k);
+    }
+  }
+
+  private static _schemasEqual(a: FrameSchema, b: FrameSchema): boolean {
+    return AnchorFrameCache.computeAnchorId(a) === AnchorFrameCache.computeAnchorId(b);
+  }
+}

package/src/core/canonical-json.ts

@@ -0,0 +1,50 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
+//
+// Canonical JSON helpers — two distinct serialisation paths used in NPS.
+//
+// AnchorFrame uses JCS (RFC 8785) for anchor_id hashing → jcsStringify.
+// NIP signing uses Python-compatible sorted-key JSON → sortKeysStringify.
+
+import canonicalizeImport from "canonicalize";
+
+// `canonicalize` is a CJS module whose default export resolves to a namespace
+// under NodeNext. Cast once to the call signature its .d.ts promises.
+const canonicalize = canonicalizeImport as unknown as (
+  input: unknown,
+) => string | undefined;
+
+/**
+ * JCS (RFC 8785) canonical JSON stringify.
+ * Used for AnchorFrame anchor_id computation.
+ */
+export function jcsStringify(obj: unknown): string {
+  const result = canonicalize(obj);
+  if (result === undefined) {
+    throw new Error("canonicalize returned undefined for input");
+  }
+  return result;
+}
+
+/**
+ * Sorted-key JSON stringify — matches Python's
+ * `json.dumps(obj, sort_keys=True, separators=(",",":"))`.
+ * Used for NIP signing.
+ */
+export function sortKeysStringify(obj: unknown): string {
+  return JSON.stringify(sortKeys(obj));
+}
+
+function sortKeys(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map(sortKeys);
+  }
+  if (value !== null && typeof value === "object") {
+    const sorted: Record<string, unknown> = {};
+    for (const key of Object.keys(value as object).sort()) {
+      sorted[key] = sortKeys((value as Record<string, unknown>)[key]);
+    }
+    return sorted;
+  }
+  return value;
+}