@labacacia/nps-sdk 1.0.0-alpha.6 → 1.0.0-alpha.8

package/src/ncp/stream-manager.ts

@@ -1,212 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// Copyright (c) 2026 LabAcacia / INNO LOTUS PTY LTD
-//
-// StreamManager — Concurrent stream tracking, sequence validation, flow control
-// NPS-1 §4.3, §7.3
-
-import { NcpError } from "../core/frame-header.js";
-import { NCP_ERROR_CODES } from "./ncp-error-codes.js";
-import type { StreamFrame } from "./frames/stream-frame.js";
-
-interface ActiveStream {
-  streamId: string;
-  expectedSeq: number;
-  chunks: unknown[][];
-  completed: boolean;
-  errorCode?: string;
-}
-
-interface OutgoingStream {
-  streamId: string;
-  remainingWindow: number | undefined; // undefined = no flow control
-  paused: boolean;
-}
-
-/**
- * Manages concurrent StreamFrame streams.
- *
- * - Tracks active streams by stream_id
- * - Validates sequential seq numbers
- * - Enforces max concurrent stream limit (NPS-1 §7.3, default 32)
- * - Detects early termination via error_code
- * - Enforces window-based flow control on outgoing streams (NCP-S-07–11)
- */
-export class StreamManager {
-  private readonly streams = new Map<string, ActiveStream>();
-  private readonly outgoing = new Map<string, OutgoingStream>();
-  private readonly maxConcurrent: number;
-
-  constructor(options?: { maxConcurrent?: number }) {
-    this.maxConcurrent = options?.maxConcurrent ?? 32;
-  }
-
-  /**
-   * Receive a StreamFrame chunk.
-   *
-   * @returns true if stream is complete (is_last=true or error_code set).
-   * @throws {NcpError} NCP-STREAM-LIMIT-EXCEEDED if too many concurrent streams.
-   * @throws {NcpError} NCP-STREAM-NOT-FOUND if frame.seq > 0 for a stream that was never opened.
-   * @throws {NcpError} NPS-CLIENT-CONFLICT if the stream_id was already completed (stream-id reuse; see test_cases NCP-S-04).
-   * @throws {NcpError} NCP-STREAM-SEQ-GAP if sequence number is not expected.
-   */
-  receive(frame: StreamFrame): boolean {
-    let stream = this.streams.get(frame.stream_id);
-
-    if (!stream) {
-      // A stream is opened only by seq=0. Any other seq on an unknown stream_id
-      // means the opener was never seen (NCP-S-13: unknown stream_id).
-      if (frame.seq !== 0) {
-        throw new NcpError(
-          NCP_ERROR_CODES.NCP_STREAM_NOT_FOUND,
-          `Unknown stream_id ${frame.stream_id} — first frame must have seq=0`,
-        );
-      }
-
-      // New stream — check concurrent limit
-      if (this.streams.size >= this.maxConcurrent) {
-        throw new NcpError(
-          NCP_ERROR_CODES.NCP_STREAM_LIMIT_EXCEEDED,
-          `Max concurrent streams (${this.maxConcurrent}) exceeded`,
-        );
-      }
-
-      stream = {
-        streamId: frame.stream_id,
-        expectedSeq: 0,
-        chunks: [],
-        completed: false,
-      };
-      this.streams.set(frame.stream_id, stream);
-    }
-
-    // Reject writes to completed streams. Per test_cases NCP-S-04, the spec does
-    // not assign a dedicated NCP code for stream-id reuse; interim mapping uses
-    // the NPS-level NPS-CLIENT-CONFLICT until a spec-side code is added.
-    if (stream.completed) {
-      throw new NcpError(
-        "NPS-CLIENT-CONFLICT",
-        `Stream ${frame.stream_id} is already completed — cannot reuse stream_id`,
-      );
-    }
-
-    // Sequence validation
-    if (frame.seq !== stream.expectedSeq) {
-      // Duplicate detection — same seq as last accepted
-      if (frame.seq < stream.expectedSeq) {
-        // Ignore duplicate (idempotent)
-        return false;
-      }
-      throw new NcpError(
-        NCP_ERROR_CODES.NCP_STREAM_SEQ_GAP,
-        `Expected seq ${stream.expectedSeq}, got ${frame.seq} on stream ${frame.stream_id}`,
-      );
-    }
-
-    stream.chunks.push(frame.data);
-    stream.expectedSeq = frame.seq + 1;
-
-    // Early termination via error_code
-    if (frame.error_code) {
-      stream.completed = true;
-      stream.errorCode = frame.error_code;
-      return true;
-    }
-
-    // Normal completion
-    if (frame.is_last) {
-      stream.completed = true;
-      return true;
-    }
-
-    return false;
-  }
-
-  /**
-   * Send a StreamFrame on an outgoing stream, enforcing window-based flow control.
-   *
-   * - seq=0 with window_size initialises remainingWindow (no decrement for opening frame).
-   * - Subsequent sends decrement remainingWindow when flow control is active.
-   * - Throws NCP-STREAM-WINDOW-OVERFLOW when remainingWindow === 0.
-   *
-   * @throws {NcpError} NCP-STREAM-WINDOW-OVERFLOW if window is exhausted.
-   */
-  send(frame: StreamFrame): void {
-    let out = this.outgoing.get(frame.stream_id);
-
-    if (!out) {
-      out = {
-        streamId: frame.stream_id,
-        remainingWindow: undefined,
-        paused: false,
-      };
-      this.outgoing.set(frame.stream_id, out);
-    }
-
-    // Opening frame: initialise window from window_size if provided.
-    if (frame.seq === 0 && frame.window_size !== undefined) {
-      out.remainingWindow = frame.window_size;
-      return; // opening frame does not consume a window slot
-    }
-
-    // Flow control check for subsequent frames.
-    if (out.remainingWindow !== undefined) {
-      if (out.remainingWindow === 0) {
-        throw new NcpError(
-          NCP_ERROR_CODES.NCP_STREAM_WINDOW_OVERFLOW,
-          `Window exhausted on stream ${frame.stream_id}`,
-        );
-      }
-      out.remainingWindow -= 1;
-    }
-  }
-
-  /**
-   * Update the send window for a stream.
-   *
-   * Called when a reverse-direction StreamFrame arrives with data=[] and window_size set.
-   * Replaces remainingWindow with new_size. Sets paused=true when new_size === 0.
-   */
-  updateWindow(streamId: string, newSize: number): void {
-    let out = this.outgoing.get(streamId);
-    if (!out) {
-      out = {
-        streamId,
-        remainingWindow: newSize,
-        paused: newSize === 0,
-      };
-      this.outgoing.set(streamId, out);
-      return;
-    }
-    out.remainingWindow = newSize;
-    out.paused = newSize === 0;
-  }
-
-  /**
-   * Returns true when the outgoing stream is paused (window=0 was received).
-   * Resumes (returns false) once a non-zero window update arrives.
-   */
-  isPaused(streamId: string): boolean {
-    return this.outgoing.get(streamId)?.paused ?? false;
-  }
-
-  /** Get reassembled data for a completed stream. */
-  getData(streamId: string): unknown[] | null {
-    const stream = this.streams.get(streamId);
-    if (!stream || !stream.completed) return null;
-    return stream.chunks.flat();
-  }
-
-  /** Get error code if stream terminated with error. */
-  getError(streamId: string): string | undefined {
-    return this.streams.get(streamId)?.errorCode;
-  }
-
-  /** Number of active (non-completed) streams. */
-  get activeCount(): number {
-    let count = 0;
-    for (const s of this.streams.values()) {
-      if (!s.completed) count++;
-    }
-    return count;
-  }
-}

package/src/ndp/dns-txt.ts

@@ -1,86 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-import type { NdpResolveResult } from "./frames.js";
-
-export const DNS_TXT_DEFAULT_TTL = 300;
-
-/**
- * Extract the hostname from an NWP target URI.
- * e.g. "nwp://api.example.com/products" → "api.example.com"
- */
-export function extractHostFromTarget(target: string): string | undefined {
-  if (!target.startsWith("nwp://")) return undefined;
-  const rest     = target.slice("nwp://".length);
-  const slashIdx = rest.indexOf("/");
-  const host     = slashIdx === -1 ? rest : rest.slice(0, slashIdx);
-  return host.length > 0 ? host : undefined;
-}
-
-/**
- * Parse one TXT record (array of string chunks) into an NdpResolveResult.
- *
- * Expected format (chunks joined with a single space):
- *   v=nps1 type=<type> port=<port> nid=<nid> fp=sha256:<fingerprint>
- *
- * Rules:
- *  - `v` MUST be present and equal to "nps1"
- *  - `nid` MUST be present
- *  - `port` defaults to 17433 when absent
- *  - `fp` is mapped to certFingerprint
- */
-export function parseNpsTxtRecord(
-  parts: string[],
-  host: string,
-): NdpResolveResult | undefined {
-  const joined = parts.join(" ");
-  const kv     = new Map<string, string>();
-
-  for (const token of joined.split(/\s+/)) {
-    const eq = token.indexOf("=");
-    if (eq === -1) continue;
-    const key = token.slice(0, eq);
-    const val = token.slice(eq + 1);
-    kv.set(key, val);
-  }
-
-  if (kv.get("v") !== "nps1") return undefined;
-
-  const nid = kv.get("nid");
-  if (!nid) return undefined;
-
-  const rawPort = kv.get("port");
-  const port    = rawPort !== undefined ? Number(rawPort) : 17433;
-  const fp      = kv.get("fp");
-
-  const result: NdpResolveResult = {
-    host,
-    port,
-    ttl: DNS_TXT_DEFAULT_TTL,
-  };
-
-  if (fp !== undefined) {
-    result.certFingerprint = fp;
-  }
-
-  return result;
-}
-
-/**
- * Abstraction over DNS TXT lookups.
- * The default implementation uses Node's `dns.promises`; pass a mock in tests.
- */
-export interface DnsTxtLookup {
-  resolveTxt(hostname: string): Promise<string[][]>;
-}
-
-/**
- * System DNS TXT resolver backed by Node's built-in `dns.promises`.
- * The dynamic `import()` keeps browser bundles from failing at parse time.
- */
-export class SystemDnsTxtLookup implements DnsTxtLookup {
-  async resolveTxt(hostname: string): Promise<string[][]> {
-    const { promises: dns } = await import("node:dns");
-    return dns.resolveTxt(hostname);
-  }
-}

package/src/ndp/frames.ts

@@ -1,124 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-import { EncodingTier, FrameType } from "../core/frames.js";
-import type { NpsFrame } from "../core/codec.js";
-
-export interface NdpAddress {
-  host:     string;
-  port:     number;
-  protocol: string;
-}
-
-export interface NdpGraphNode {
-  nid:          string;
-  addresses:    readonly NdpAddress[];
-  capabilities: readonly string[];
-  nodeType?:    string;
-}
-
-export interface NdpResolveResult {
-  host:              string;
-  port:              number;
-  ttl:               number;
-  certFingerprint?:  string;
-}
-
-export class AnnounceFrame implements NpsFrame {
-  readonly frameType     = FrameType.ANNOUNCE;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly nid:          string,
-    public readonly addresses:    readonly NdpAddress[],
-    public readonly capabilities: readonly string[],
-    public readonly ttl:          number,
-    public readonly timestamp:    string,
-    public readonly signature:    string,
-    public readonly nodeType?:    string,
-  ) {}
-
-  unsignedDict(): Record<string, unknown> {
-    return {
-      nid:          this.nid,
-      addresses:    this.addresses,
-      capabilities: this.capabilities,
-      ttl:          this.ttl,
-      timestamp:    this.timestamp,
-      node_type:    this.nodeType ?? null,
-    };
-  }
-
-  toDict(): Record<string, unknown> {
-    return { ...this.unsignedDict(), signature: this.signature };
-  }
-
-  static fromDict(data: Record<string, unknown>): AnnounceFrame {
-    return new AnnounceFrame(
-      data["nid"]          as string,
-      data["addresses"]    as NdpAddress[],
-      data["capabilities"] as string[],
-      data["ttl"]          as number,
-      data["timestamp"]    as string,
-      data["signature"]    as string,
-      (data["node_type"]    as string | null) ?? undefined,
-    );
-  }
-}
-
-export class ResolveFrame implements NpsFrame {
-  readonly frameType     = FrameType.RESOLVE;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly target:        string,
-    public readonly requesterNid?: string,
-    public readonly resolved?:     NdpResolveResult,
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      target:        this.target,
-      requester_nid: this.requesterNid ?? null,
-      resolved:      this.resolved     ?? null,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): ResolveFrame {
-    return new ResolveFrame(
-      data["target"]         as string,
-      (data["requester_nid"] as string | null) ?? undefined,
-      (data["resolved"]      as NdpResolveResult | null) ?? undefined,
-    );
-  }
-}
-
-export class GraphFrame implements NpsFrame {
-  readonly frameType     = FrameType.GRAPH;
-  readonly preferredTier = EncodingTier.MSGPACK;
-
-  constructor(
-    public readonly seq:         number,
-    public readonly initialSync: boolean,
-    public readonly nodes?:      readonly NdpGraphNode[],
-    public readonly patch?:      readonly Record<string, unknown>[],
-  ) {}
-
-  toDict(): Record<string, unknown> {
-    return {
-      seq:          this.seq,
-      initial_sync: this.initialSync,
-      nodes:        this.nodes ?? null,
-      patch:        this.patch ?? null,
-    };
-  }
-
-  static fromDict(data: Record<string, unknown>): GraphFrame {
-    return new GraphFrame(
-      data["seq"]          as number,
-      data["initial_sync"] as boolean,
-      (data["nodes"] as NdpGraphNode[] | null) ?? undefined,
-      (data["patch"] as Record<string, unknown>[] | null) ?? undefined,
-    );
-  }
-}

package/src/ndp/ndp-registry.ts

@@ -1,116 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-import type { AnnounceFrame, NdpResolveResult } from "./frames.js";
-import {
-  extractHostFromTarget,
-  parseNpsTxtRecord,
-  SystemDnsTxtLookup,
-  type DnsTxtLookup,
-} from "./dns-txt.js";
-
-interface RegistryEntry {
-  frame:     AnnounceFrame;
-  expiresAt: number;
-}
-
-export class InMemoryNdpRegistry {
-  private readonly _store = new Map<string, RegistryEntry>();
-
-  // Replaceable for testing
-  clock: () => number = () => Date.now();
-
-  announce(frame: AnnounceFrame): void {
-    const expiresAt = this.clock() + frame.ttl * 1000;
-    if (frame.ttl === 0) {
-      this._store.delete(frame.nid);
-      return;
-    }
-    this._store.set(frame.nid, { frame, expiresAt });
-  }
-
-  getByNid(nid: string): AnnounceFrame | undefined {
-    const entry = this._store.get(nid);
-    if (entry === undefined) return undefined;
-    if (this.clock() > entry.expiresAt) {
-      this._store.delete(nid);
-      return undefined;
-    }
-    return entry.frame;
-  }
-
-  resolve(target: string): NdpResolveResult | undefined {
-    for (const [nid, entry] of this._store) {
-      if (this.clock() > entry.expiresAt) { this._store.delete(nid); continue; }
-      if (!InMemoryNdpRegistry.nwpTargetMatchesNid(nid, target)) continue;
-      const addr = entry.frame.addresses[0];
-      if (addr === undefined) continue;
-      return { host: addr.host, port: addr.port, ttl: entry.frame.ttl };
-    }
-    return undefined;
-  }
-
-  getAll(): AnnounceFrame[] {
-    const now    = this.clock();
-    const result: AnnounceFrame[] = [];
-    for (const [nid, entry] of this._store) {
-      if (now > entry.expiresAt) { this._store.delete(nid); continue; }
-      result.push(entry.frame);
-    }
-    return result;
-  }
-
-  async resolveWithDns(
-    target: string,
-    resolver: DnsTxtLookup = new SystemDnsTxtLookup(),
-  ): Promise<NdpResolveResult | undefined> {
-    // 1. Try in-memory registry first
-    const cached = this.resolve(target);
-    if (cached !== undefined) return cached;
-
-    // 2. Extract hostname and fall back to DNS TXT lookup
-    const host = extractHostFromTarget(target);
-    if (host === undefined) return undefined;
-
-    const txtHost = `_nps-node.${host}`;
-    let records: string[][];
-    try {
-      records = await resolver.resolveTxt(txtHost);
-    } catch {
-      return undefined;
-    }
-
-    for (const record of records) {
-      const result = parseNpsTxtRecord(record, host);
-      if (result !== undefined) return result;
-    }
-
-    return undefined;
-  }
-
-  static nwpTargetMatchesNid(nid: string, target: string): boolean {
-    // NID: urn:nps:node:{authority}:{path-segment}
-    // target: nwp://{authority}/{path}
-    const nidParts = nid.split(":");
-    if (nidParts.length < 5 || nidParts[0] !== "urn" || nidParts[1] !== "nps" || nidParts[2] !== "node") {
-      return false;
-    }
-    if (!target.startsWith("nwp://")) return false;
-
-    const nidAuthority = nidParts[3]!;
-    const nidPath      = nidParts[4]!;
-    const rest         = target.slice("nwp://".length);
-    const slashIdx     = rest.indexOf("/");
-    if (slashIdx === -1) return false;
-
-    const urlAuthority = rest.slice(0, slashIdx);
-    const urlPath      = rest.slice(slashIdx + 1); // without leading slash
-
-    if (urlAuthority !== nidAuthority) return false;
-
-    // nidPath must be a prefix of urlPath at a segment boundary
-    if (urlPath === nidPath) return true;
-    if (urlPath.startsWith(nidPath + "/")) return true;
-    return false;
-  }
-}

package/src/ndp/registry.ts

@@ -1,12 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-import { FrameRegistry } from "../core/registry.js";
-import { FrameType } from "../core/frames.js";
-import { AnnounceFrame, GraphFrame, ResolveFrame } from "./frames.js";
-
-export function registerNdpFrames(registry: FrameRegistry): void {
-  registry.register(FrameType.ANNOUNCE, AnnounceFrame);
-  registry.register(FrameType.RESOLVE,  ResolveFrame);
-  registry.register(FrameType.GRAPH,    GraphFrame);
-}

package/src/ndp/validator.ts

@@ -1,64 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-import * as ed25519 from "@noble/ed25519";
-import { sha512 } from "@noble/hashes/sha512";
-import type { AnnounceFrame } from "./frames.js";
-
-ed25519.etc.sha512Sync = (...m) => sha512(ed25519.etc.concatBytes(...m));
-
-export interface NdpAnnounceResult {
-  isValid:    boolean;
-  errorCode?: string;
-  message?:   string;
-}
-
-export const NdpAnnounceResult = {
-  ok: (): NdpAnnounceResult => ({ isValid: true }),
-  fail: (errorCode: string, message: string): NdpAnnounceResult => ({ isValid: false, errorCode, message }),
-};
-
-export class NdpAnnounceValidator {
-  private readonly _keys = new Map<string, string>(); // nid → "ed25519:<hex>"
-
-  registerPublicKey(nid: string, encodedPubKey: string): void {
-    this._keys.set(nid, encodedPubKey);
-  }
-
-  removePublicKey(nid: string): void {
-    this._keys.delete(nid);
-  }
-
-  get knownPublicKeys(): ReadonlyMap<string, string> {
-    return this._keys;
-  }
-
-  validate(frame: AnnounceFrame): NdpAnnounceResult {
-    const encoded = this._keys.get(frame.nid);
-    if (encoded === undefined) {
-      return NdpAnnounceResult.fail("NDP-ANNOUNCE-NID-MISMATCH", `No public key registered for NID: ${frame.nid}`);
-    }
-
-    try {
-      const prefix  = "ed25519:";
-      const pubHex  = encoded.startsWith(prefix) ? encoded.slice(prefix.length) : encoded;
-      const pubKey  = Buffer.from(pubHex, "hex");
-
-      const sig = frame.signature;
-      if (!sig.startsWith(prefix)) {
-        return NdpAnnounceResult.fail("NDP-ANNOUNCE-SIG-INVALID", "Signature must start with 'ed25519:'");
-      }
-      const sigBytes = Buffer.from(sig.slice(prefix.length), "base64");
-
-      const unsigned  = frame.unsignedDict();
-      const canonical = JSON.stringify(unsigned, Object.keys(unsigned).sort());
-      const message   = new TextEncoder().encode(canonical);
-
-      const valid = ed25519.verify(sigBytes, message, pubKey);
-      if (!valid) return NdpAnnounceResult.fail("NDP-ANNOUNCE-SIG-INVALID", "Ed25519 signature verification failed.");
-      return NdpAnnounceResult.ok();
-    } catch {
-      return NdpAnnounceResult.fail("NDP-ANNOUNCE-SIG-INVALID", "Ed25519 signature verification failed.");
-    }
-  }
-}