@labacacia/nps-sdk 1.0.0-alpha.5 → 1.0.0-alpha.7

package/src/core/anchor-cache.ts

@@ -1,129 +0,0 @@
-// 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

@@ -1,93 +0,0 @@
-// 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

@@ -1,50 +0,0 @@
-// 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;
-}

package/src/core/codec.ts

@@ -1,158 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * NPS frame codec: Tier-1 (JSON) and Tier-2 (MsgPack) encode/decode,
- * plus the top-level NpsFrameCodec dispatcher.
- */
-
-import * as msgpack from "@msgpack/msgpack";
-import { NpsCodecError } from "./exceptions.js";
-import {
-  DEFAULT_MAX_PAYLOAD,
-  EncodingTier,
-  FrameFlags,
-  FrameHeader,
-  FrameType,
-} from "./frames.js";
-import type { FrameRegistry } from "./registry.js";
-
-// ── NpsFrame interface ────────────────────────────────────────────────────────
-
-export interface NpsFrame {
-  readonly frameType: FrameType;
-  readonly preferredTier: EncodingTier;
-  toDict(): Record<string, unknown>;
-}
-
-// ── Tier-1 JSON codec ─────────────────────────────────────────────────────────
-
-export class Tier1JsonCodec {
-  encode(frame: NpsFrame): Uint8Array {
-    try {
-      const json = JSON.stringify(frame.toDict());
-      return new TextEncoder().encode(json);
-    } catch (err) {
-      throw new NpsCodecError(
-        `Tier-1 JSON encode failed for 0x${frame.frameType.toString(16).padStart(2, "0")}: ${String(err)}`,
-      );
-    }
-  }
-
-  decode(frameType: FrameType, payload: Uint8Array, registry: FrameRegistry): NpsFrame {
-    const cls = registry.resolve(frameType);
-    try {
-      const text = new TextDecoder().decode(payload);
-      const data = JSON.parse(text) as Record<string, unknown>;
-      return cls.fromDict(data);
-    } catch (err) {
-      throw new NpsCodecError(
-        `Tier-1 JSON decode failed for 0x${frameType.toString(16).padStart(2, "0")}: ${String(err)}`,
-      );
-    }
-  }
-}
-
-// ── Tier-2 MsgPack codec ──────────────────────────────────────────────────────
-
-export class Tier2MsgPackCodec {
-  encode(frame: NpsFrame): Uint8Array {
-    try {
-      return msgpack.encode(frame.toDict());
-    } catch (err) {
-      throw new NpsCodecError(
-        `Tier-2 MsgPack encode failed for 0x${frame.frameType.toString(16).padStart(2, "0")}: ${String(err)}`,
-      );
-    }
-  }
-
-  decode(frameType: FrameType, payload: Uint8Array, registry: FrameRegistry): NpsFrame {
-    const cls = registry.resolve(frameType);
-    try {
-      const data = msgpack.decode(payload) as Record<string, unknown>;
-      return cls.fromDict(data);
-    } catch (err) {
-      throw new NpsCodecError(
-        `Tier-2 MsgPack decode failed for 0x${frameType.toString(16).padStart(2, "0")}: ${String(err)}`,
-      );
-    }
-  }
-}
-
-// ── NpsFrameCodec (dispatcher) ────────────────────────────────────────────────
-
-export class NpsFrameCodec {
-  private readonly _registry: FrameRegistry;
-  private readonly _maxPayload: number;
-  private readonly _json    = new Tier1JsonCodec();
-  private readonly _msgpack = new Tier2MsgPackCodec();
-
-  constructor(registry: FrameRegistry, options: { maxPayload?: number } = {}) {
-    this._registry   = registry;
-    this._maxPayload = options.maxPayload ?? DEFAULT_MAX_PAYLOAD;
-  }
-
-  // ── Encode ────────────────────────────────────────────────────────────────
-
-  encode(frame: NpsFrame, options: { overrideTier?: EncodingTier } = {}): Uint8Array {
-    const tier    = options.overrideTier ?? frame.preferredTier;
-    const tierCodec = this._selectCodec(tier);
-
-    let payload: Uint8Array;
-    try {
-      payload = tierCodec.encode(frame);
-    } catch (err) {
-      if (err instanceof NpsCodecError) throw err;
-      throw new NpsCodecError(`Encode failed for 0x${frame.frameType.toString(16)}.`);
-    }
-
-    if (payload.length > this._maxPayload) {
-      throw new NpsCodecError(
-        `Encoded payload for 0x${frame.frameType.toString(16).padStart(2, "0")} exceeds max_frame_payload` +
-        ` (${payload.length} bytes > ${this._maxPayload}). Use StreamFrame (0x03) for large payloads.`,
-      );
-    }
-
-    const useExt = payload.length > DEFAULT_MAX_PAYLOAD;
-    let flags    = this._buildFlags(frame, tier);
-    if (useExt) flags |= FrameFlags.EXT;
-
-    const header     = new FrameHeader(frame.frameType, flags, payload.length);
-    const headerBytes = header.toBytes();
-    const wire       = new Uint8Array(headerBytes.length + payload.length);
-    wire.set(headerBytes, 0);
-    wire.set(payload, headerBytes.length);
-    return wire;
-  }
-
-  // ── Decode ────────────────────────────────────────────────────────────────
-
-  decode(wire: Uint8Array): NpsFrame {
-    const header  = FrameHeader.parse(wire);
-    const payload = wire.slice(header.headerSize, header.headerSize + header.payloadLength);
-    const codec   = this._selectCodec(header.encodingTier);
-    return codec.decode(header.frameType, payload, this._registry);
-  }
-
-  static peekHeader(wire: Uint8Array): FrameHeader {
-    return FrameHeader.parse(wire);
-  }
-
-  // ── Private ───────────────────────────────────────────────────────────────
-
-  private _buildFlags(frame: NpsFrame, tier: EncodingTier): number {
-    let flags = tier === EncodingTier.JSON ? FrameFlags.TIER1_JSON : FrameFlags.TIER2_MSGPACK;
-
-    const isStreamFrame = "isLast" in frame;
-    const isFinal       = !isStreamFrame || (frame as { isLast: boolean }).isLast;
-    if (isFinal) flags |= FrameFlags.FINAL;
-
-    return flags;
-  }
-
-  private _selectCodec(tier: EncodingTier): Tier1JsonCodec | Tier2MsgPackCodec {
-    if (tier === EncodingTier.JSON)    return this._json;
-    if (tier === EncodingTier.MSGPACK) return this._msgpack;
-    throw new NpsCodecError(`Unsupported encoding tier: 0x${(tier as number).toString(16).padStart(2, "0")}.`);
-  }
-}

package/src/core/codecs/index.ts

@@ -1,5 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-export * from "./ncp-codec.js";
-export { encodeJson, decodeJson } from "./tier1-json-codec.js";
-export { encodeMsgPack, decodeMsgPack } from "./tier2-msgpack-codec.js";

package/src/core/codecs/ncp-codec.ts

@@ -1,170 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// NCP Codec — Top-level encode/decode dispatcher
-// Routes to Tier-1 JSON or Tier-2 MsgPack based on frame header flags.
-
-import {
-  parseFrameHeader,
-  writeFrameHeader,
-  buildFlags,
-  EncodingTier,
-  NcpError,
-  DEFAULT_MAX_PAYLOAD,
-  type FrameHeader,
-} from "../frame-header.js";
-import { encodeJson, decodeJson } from "./tier1-json-codec.js";
-import { encodeMsgPack, decodeMsgPack } from "./tier2-msgpack-codec.js";
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-export interface DecodeResult {
-  /** Parsed frame header. */
-  header: FrameHeader;
-  /** Decoded payload object. */
-  payload: unknown;
-  /** Total bytes consumed (header + payload). */
-  bytesConsumed: number;
-}
-
-export interface EncodeOptions {
-  /** Frame type byte. */
-  frameType: number;
-  /** Encoding tier (default: JSON). */
-  tier?: EncodingTier;
-  /** Set FINAL flag. */
-  final?: boolean;
-  /** Set ENC flag. */
-  encrypted?: boolean;
-  /** Use extended header (for payloads > 64KB). */
-  extended?: boolean;
-}
-
-export interface CodecOptions {
-  /** Maximum frame payload in bytes (negotiated via CapsFrame). Default: 65535. */
-  maxFramePayload?: number;
-}
-
-// ---------------------------------------------------------------------------
-// Decode
-// ---------------------------------------------------------------------------
-
-/**
- * Decode a complete NCP frame from a buffer.
- *
- * @returns Decoded header + payload + bytes consumed.
- * @throws {NcpError} NCP-ENCODING-UNSUPPORTED for reserved tiers.
- * @throws {NcpError} NCP-FRAME-PAYLOAD-TOO-LARGE if payload exceeds max.
- * @throws {NcpError} NCP-FRAME-INCOMPLETE if buffer doesn't have enough data.
- */
-export function decodeFrame(
-  buffer: Uint8Array,
-  options?: CodecOptions,
-): DecodeResult {
-  const header = parseFrameHeader(buffer);
-  const maxPayload = options?.maxFramePayload ?? DEFAULT_MAX_PAYLOAD;
-
-  // NCP-F-09: Validate against negotiated max_frame_payload
-  if (header.payloadLength > maxPayload) {
-    throw new NcpError(
-      "NCP-FRAME-PAYLOAD-TOO-LARGE",
-      `Payload ${header.payloadLength} exceeds max_frame_payload ${maxPayload}`,
-    );
-  }
-
-  const totalSize = header.headerSize + header.payloadLength;
-
-  // NCP-F-05: Buffer underrun — not enough data for payload
-  if (buffer.length < totalSize) {
-    throw new NcpError(
-      "NCP-FRAME-INCOMPLETE",
-      `Buffer has ${buffer.length} bytes but frame needs ${totalSize}`,
-    );
-  }
-
-  // Extract payload bytes
-  const payloadBytes = buffer.subarray(
-    header.headerSize,
-    header.headerSize + header.payloadLength,
-  );
-
-  // Route to codec by tier
-  let payload: unknown;
-  switch (header.tier) {
-    case EncodingTier.Json:
-      payload = decodeJson(payloadBytes);
-      break;
-    case EncodingTier.MsgPack:
-      payload = decodeMsgPack(payloadBytes);
-      break;
-    default:
-      // NCP-E-05: Reserved tiers (0x02, 0x03)
-      throw new NcpError(
-        "NCP-ENCODING-UNSUPPORTED",
-        `Unsupported encoding tier: 0x${(header.tier as number).toString(16).padStart(2, "0")}`,
-      );
-  }
-
-  return { header, payload, bytesConsumed: totalSize };
-}
-
-// ---------------------------------------------------------------------------
-// Encode
-// ---------------------------------------------------------------------------
-
-/**
- * Encode a payload into a complete NCP frame (header + payload bytes).
- */
-export function encodeFrame(
-  payload: unknown,
-  options: EncodeOptions,
-): Uint8Array {
-  const tier = options.tier ?? EncodingTier.Json;
-
-  // Encode payload
-  let payloadBytes: Uint8Array;
-  switch (tier) {
-    case EncodingTier.Json:
-      payloadBytes = encodeJson(payload);
-      break;
-    case EncodingTier.MsgPack:
-      payloadBytes = encodeMsgPack(payload);
-      break;
-    default:
-      throw new NcpError(
-        "NCP-ENCODING-UNSUPPORTED",
-        `Unsupported encoding tier for encode: ${tier}`,
-      );
-  }
-
-  // Determine if extended header is needed
-  const needsExtended =
-    options.extended || payloadBytes.length > DEFAULT_MAX_PAYLOAD;
-
-  const flags = buildFlags({
-    tier,
-    final: options.final,
-    encrypted: options.encrypted,
-    extended: needsExtended,
-  });
-
-  const header: FrameHeader = {
-    frameType: options.frameType,
-    flags,
-    payloadLength: payloadBytes.length,
-    tier,
-    isFinal: options.final ?? false,
-    isEncrypted: options.encrypted ?? false,
-    isExtended: needsExtended,
-    headerSize: needsExtended ? 8 : 4,
-  };
-
-  // Write frame
-  const frame = new Uint8Array(header.headerSize + payloadBytes.length);
-  writeFrameHeader(header, frame);
-  frame.set(payloadBytes, header.headerSize);
-
-  return frame;
-}

package/src/core/codecs/tier1-json-codec.ts

@@ -1,33 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// Tier-1 JSON Codec — UTF-8 JSON encode/decode
-// NPS-1 §8
-
-import { NcpError } from "../frame-header.js";
-
-const encoder = new TextEncoder();
-const decoder = new TextDecoder();
-
-/**
- * Encode a frame payload to Tier-1 JSON bytes.
- */
-export function encodeJson(payload: unknown): Uint8Array {
-  return encoder.encode(JSON.stringify(payload));
-}
-
-/**
- * Decode Tier-1 JSON bytes to a parsed object.
- * @throws {NcpError} NPS-CLIENT-BAD-FRAME on malformed JSON.
- */
-export function decodeJson(bytes: Uint8Array): unknown {
-  const text = decoder.decode(bytes);
-  try {
-    return JSON.parse(text) as unknown;
-  } catch {
-    throw new NcpError(
-      "NPS-CLIENT-BAD-FRAME",
-      "Malformed JSON payload",
-    );
-  }
-}

package/src/core/codecs/tier2-msgpack-codec.ts

@@ -1,30 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// Tier-2 MsgPack Codec — Binary encode/decode
-// NPS-1 §8
-
-import { encode, decode } from "@msgpack/msgpack";
-import { NcpError } from "../frame-header.js";
-
-/**
- * Encode a frame payload to Tier-2 MsgPack bytes.
- */
-export function encodeMsgPack(payload: unknown): Uint8Array {
-  return encode(payload);
-}
-
-/**
- * Decode Tier-2 MsgPack bytes to a parsed object.
- * @throws {NcpError} NPS-CLIENT-BAD-FRAME on malformed MsgPack.
- */
-export function decodeMsgPack(bytes: Uint8Array): unknown {
-  try {
-    return decode(bytes) as unknown;
-  } catch {
-    throw new NcpError(
-      "NPS-CLIENT-BAD-FRAME",
-      "Malformed MsgPack payload",
-    );
-  }
-}