@labacacia/nps-sdk 1.0.0-alpha.1 → 1.0.0-alpha.13

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",
-    );
-  }
-}

package/src/core/crypto-provider.ts

@@ -1,47 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// CryptoProvider interface — async crypto abstraction for Node + browser.
-// NPS-3 §10 / Q10 resolution in nps-ts-sdk-step7-plan.
-//
-// Implementations (NodeCryptoProvider, WebCryptoProvider) land at P3
-// alongside NIP tests. This file is structural scaffold only.
-
-/**
- * Async crypto operations used across NPS protocols.
- * All keys, IVs, and byte payloads are Uint8Array.
- */
-export interface CryptoProvider {
-  /** Generate cryptographically secure random bytes. */
-  randomBytes(n: number): Uint8Array;
-
-  /** Generate an Ed25519 keypair. */
-  ed25519GenerateKeyPair(): Promise<{ publicKey: Uint8Array; privateKey: Uint8Array }>;
-
-  /** Sign data with an Ed25519 private key. Returns 64-byte signature. */
-  ed25519Sign(privateKey: Uint8Array, data: Uint8Array): Promise<Uint8Array>;
-
-  /** Verify an Ed25519 signature. */
-  ed25519Verify(publicKey: Uint8Array, data: Uint8Array, sig: Uint8Array): Promise<boolean>;
-
-  /**
-   * AES-256-GCM encrypt.
-   * Returns ciphertext || 16-byte tag (single contiguous buffer, matching
-   * Web Crypto subtle.encrypt output and Python pycryptodome layout).
-   */
-  aesGcmEncrypt(key: Uint8Array, iv: Uint8Array, plaintext: Uint8Array): Promise<Uint8Array>;
-
-  /**
-   * AES-256-GCM decrypt.
-   * Input is ciphertext || 16-byte tag (same layout as aesGcmEncrypt output).
-   */
-  aesGcmDecrypt(key: Uint8Array, iv: Uint8Array, ciphertextAndTag: Uint8Array): Promise<Uint8Array>;
-
-  /** PBKDF2-SHA256 key derivation. */
-  pbkdf2Sha256(
-    passphrase: Uint8Array,
-    salt: Uint8Array,
-    iterations: number,
-    keyLen: number,
-  ): Promise<Uint8Array>;
-}

package/src/core/exceptions.ts

@@ -1,57 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// NPS exception hierarchy — ported from nps_sdk/core/exceptions.py
-// NPS-1 §6
-
-/** Base class for all NPS SDK errors. */
-export class NpsError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "NpsError";
-  }
-}
-
-/** Frame parse or structural error. */
-export class NpsFrameError extends NpsError {
-  constructor(message: string) {
-    super(message);
-    this.name = "NpsFrameError";
-  }
-}
-
-/** Encode or decode error. */
-export class NpsCodecError extends NpsError {
-  constructor(message: string) {
-    super(message);
-    this.name = "NpsCodecError";
-  }
-}
-
-/** Anchor cache miss — requested anchor ID not found. */
-export class NpsAnchorNotFoundError extends NpsError {
-  readonly anchorId: string;
-  constructor(anchorId: string, message?: string) {
-    super(message ?? `Anchor not found: ${anchorId}`);
-    this.name = "NpsAnchorNotFoundError";
-    this.anchorId = anchorId;
-  }
-}
-
-/** Anchor ID collision — same ID but different schema content. */
-export class NpsAnchorPoisonError extends NpsError {
-  readonly anchorId: string;
-  constructor(anchorId: string, message?: string) {
-    super(message ?? `Anchor poison detected: ${anchorId}`);
-    this.name = "NpsAnchorPoisonError";
-    this.anchorId = anchorId;
-  }
-}
-
-/** Stream-level error (sequence gap, unknown stream ID, etc.). */
-export class NpsStreamError extends NpsError {
-  constructor(message: string) {
-    super(message);
-    this.name = "NpsStreamError";
-  }
-}

package/src/core/frame-header.ts

@@ -1,282 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// NCP Frame Header — Binary parse/write for NPS wire format
-// NPS-1 Neural Communication Protocol §3.1, §3.2
-
-// ---------------------------------------------------------------------------
-// Enums
-// ---------------------------------------------------------------------------
-
-/** Wire encoding tier (NPS-1 §3.2, flags bits 0-1). */
-export enum EncodingTier {
-  /** Tier-1: UTF-8 JSON — development & compatibility. */
-  Json = 0x00,
-  /** Tier-2: MessagePack binary — production (~60% compression). */
-  MsgPack = 0x01,
-  // 0x02 = Reserved
-  // 0x03 = Reserved
-}
-
-/** Unified frame type namespace for the full NPS suite (NPS-0 §9). */
-export enum FrameType {
-  // NCP 0x01–0x0F
-  Anchor = 0x01,
-  Diff = 0x02,
-  Stream = 0x03,
-  Caps = 0x04,
-  Align = 0x05, // deprecated — use AlignStream (0x43)
-  Hello = 0x06,
-  // NWP 0x10–0x1F
-  Query = 0x10,
-  Action = 0x11,
-  Subscribe = 0x12,
-  // NIP 0x20–0x2F
-  Ident = 0x20,
-  Trust = 0x21,
-  Revoke = 0x22,
-  // NDP 0x30–0x3F
-  Announce = 0x30,
-  Resolve = 0x31,
-  Graph = 0x32,
-  // NOP 0x40–0x4F
-  Task = 0x40,
-  Delegate = 0x41,
-  Sync = 0x42,
-  AlignStream = 0x43,
-  // System 0xF0–0xFF
-  Error = 0xfe,
-}
-
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-
-/** Default (compact) header size in bytes. */
-export const DEFAULT_HEADER_SIZE = 4;
-
-/** Extended header size in bytes (EXT=1). */
-export const EXTENDED_HEADER_SIZE = 8;
-
-/** Maximum payload in default mode (64 KiB − 1). */
-export const DEFAULT_MAX_PAYLOAD = 0xffff;
-
-/** Maximum payload in extended mode (4 GiB − 1). */
-export const EXTENDED_MAX_PAYLOAD = 0xffffffff;
-
-// Flag bit positions (NPS-1 §3.2)
-const TIER_MASK = 0x03; // bits 0-1
-const FINAL_BIT = 0x04; // bit 2
-const ENC_BIT = 0x08; // bit 3
-const RESERVED_MASK = 0x70; // bits 4-6
-const EXT_BIT = 0x80; // bit 7
-
-// ---------------------------------------------------------------------------
-// Error
-// ---------------------------------------------------------------------------
-
-/** NCP protocol error with machine-readable error code. */
-export class NcpError extends Error {
-  // `code` accepts NcpErrorCode constants (preferred) as well as NPS status
-  // strings that are not NCP-prefixed (e.g. "NPS-CLIENT-CONFLICT") for cases
-  // where the spec delegates to NPS-level codes without assigning an NCP code.
-  constructor(
-    public readonly code: string,
-    message: string,
-  ) {
-    super(message);
-    this.name = "NcpError";
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Parsed header
-// ---------------------------------------------------------------------------
-
-/** Parsed frame header. */
-export interface FrameHeader {
-  /** Raw frame type byte. */
-  frameType: number;
-  /** Raw flags byte. */
-  flags: number;
-  /** Payload length in bytes. */
-  payloadLength: number;
-  /** Encoding tier extracted from flags bits 0-1. */
-  tier: EncodingTier;
-  /** True when FINAL flag (bit 2) is set. */
-  isFinal: boolean;
-  /** True when ENC flag (bit 3) is set. */
-  isEncrypted: boolean;
-  /** True when EXT flag (bit 7) is set — 8-byte header. */
-  isExtended: boolean;
-  /** Header size in bytes (4 or 8). */
-  headerSize: number;
-}
-
-// ---------------------------------------------------------------------------
-// Parse
-// ---------------------------------------------------------------------------
-
-/**
- * Parse a frame header from the start of the buffer.
- * Reads 2 bytes first to determine EXT, then reads remaining bytes.
- *
- * @throws {NcpError} NCP-FRAME-FLAGS-INVALID if reserved bits 4-6 are non-zero.
- * @throws {NcpError} NCP-FRAME-PARSE-ERROR if buffer is too small.
- * @throws {NcpError} NCP-FRAME-PAYLOAD-TOO-LARGE if opts.max_frame_payload is set and exceeded.
- */
-export function parseFrameHeader(
-  buffer: Uint8Array,
-  opts?: { max_frame_payload?: number },
-): FrameHeader {
-  if (buffer.length < 2) {
-    throw new NcpError(
-      "NCP-FRAME-PARSE-ERROR",
-      `Buffer too small to read frame type and flags: need >= 2 bytes, got ${buffer.length}`,
-    );
-  }
-
-  const frameType = buffer[0]!;
-  const flags = buffer[1]!;
-
-  // Validate reserved bits (NPS-1 §3.2: bits 4-6 MUST be 0)
-  if ((flags & RESERVED_MASK) !== 0) {
-    throw new NcpError(
-      "NCP-FRAME-FLAGS-INVALID",
-      "Reserved flag bits 4-6 must be zero",
-    );
-  }
-
-  const isExtended = (flags & EXT_BIT) !== 0;
-
-  if (isExtended) {
-    if (buffer.length < EXTENDED_HEADER_SIZE) {
-      throw new NcpError(
-        "NCP-FRAME-PARSE-ERROR",
-        `Buffer too small for extended header: need ${EXTENDED_HEADER_SIZE} bytes, got ${buffer.length}`,
-      );
-    }
-
-    const view = new DataView(
-      buffer.buffer,
-      buffer.byteOffset,
-      buffer.byteLength,
-    );
-    const payloadLength = view.getUint32(2, false); // big-endian
-
-    if (
-      opts?.max_frame_payload !== undefined &&
-      payloadLength > opts.max_frame_payload
-    ) {
-      throw new NcpError(
-        "NCP-FRAME-PAYLOAD-TOO-LARGE",
-        `Payload length ${payloadLength} exceeds max_frame_payload ${opts.max_frame_payload}`,
-      );
-    }
-
-    return {
-      frameType,
-      flags,
-      payloadLength,
-      tier: (flags & TIER_MASK) as EncodingTier,
-      isFinal: (flags & FINAL_BIT) !== 0,
-      isEncrypted: (flags & ENC_BIT) !== 0,
-      isExtended: true,
-      headerSize: EXTENDED_HEADER_SIZE,
-    };
-  }
-
-  // Default 4-byte header
-  if (buffer.length < DEFAULT_HEADER_SIZE) {
-    throw new NcpError(
-      "NCP-FRAME-PARSE-ERROR",
-      `Buffer too small for header: need ${DEFAULT_HEADER_SIZE} bytes, got ${buffer.length}`,
-    );
-  }
-
-  const view = new DataView(
-    buffer.buffer,
-    buffer.byteOffset,
-    buffer.byteLength,
-  );
-  const payloadLength = view.getUint16(2, false); // big-endian
-
-  if (
-    opts?.max_frame_payload !== undefined &&
-    payloadLength > opts.max_frame_payload
-  ) {
-    throw new NcpError(
-      "NCP-FRAME-PAYLOAD-TOO-LARGE",
-      `Payload length ${payloadLength} exceeds max_frame_payload ${opts.max_frame_payload}`,
-    );
-  }
-
-  return {
-    frameType,
-    flags,
-    payloadLength,
-    tier: (flags & TIER_MASK) as EncodingTier,
-    isFinal: (flags & FINAL_BIT) !== 0,
-    isEncrypted: (flags & ENC_BIT) !== 0,
-    isExtended: false,
-    headerSize: DEFAULT_HEADER_SIZE,
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Write
-// ---------------------------------------------------------------------------
-
-/**
- * Write a frame header into the buffer.
- * @returns Number of bytes written (4 or 8).
- * @throws {Error} if buffer is too small.
- */
-export function writeFrameHeader(
-  header: FrameHeader,
-  buffer: Uint8Array,
-): number {
-  const size = header.isExtended ? EXTENDED_HEADER_SIZE : DEFAULT_HEADER_SIZE;
-  if (buffer.length < size) {
-    throw new Error(
-      `Destination buffer must be at least ${size} bytes, got ${buffer.length}`,
-    );
-  }
-
-  buffer[0] = header.frameType;
-  buffer[1] = header.flags;
-
-  const view = new DataView(
-    buffer.buffer,
-    buffer.byteOffset,
-    buffer.byteLength,
-  );
-
-  if (header.isExtended) {
-    view.setUint32(2, header.payloadLength, false); // big-endian
-    buffer[6] = 0; // reserved
-    buffer[7] = 0; // reserved
-  } else {
-    view.setUint16(2, header.payloadLength, false); // big-endian
-  }
-
-  return size;
-}
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-/** Build a flags byte from individual options. */
-export function buildFlags(options: {
-  tier?: EncodingTier;
-  final?: boolean;
-  encrypted?: boolean;
-  extended?: boolean;
-}): number {
-  let flags = (options.tier ?? EncodingTier.Json) & TIER_MASK;
-  if (options.final) flags |= FINAL_BIT;
-  if (options.encrypted) flags |= ENC_BIT;
-  if (options.extended) flags |= EXT_BIT;
-  return flags;
-}