@labacacia/nps-sdk 1.0.0-alpha.1

package/src/ncp/registry.ts

@@ -0,0 +1,14 @@
+// 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 { AnchorFrame, CapsFrame, DiffFrame, ErrorFrame, StreamFrame } from "./frames.js";
+
+export function registerNcpFrames(registry: FrameRegistry): void {
+  registry.register(FrameType.ANCHOR, AnchorFrame);
+  registry.register(FrameType.DIFF,   DiffFrame);
+  registry.register(FrameType.STREAM, StreamFrame);
+  registry.register(FrameType.CAPS,   CapsFrame);
+  registry.register(FrameType.ERROR,  ErrorFrame);
+}

package/src/ncp/stream-manager.ts

@@ -0,0 +1,212 @@
+// 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/frames.ts

@@ -0,0 +1,124 @@
+// 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/index.ts

@@ -0,0 +1,7 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+export * from "./frames.js";
+export * from "./registry.js";
+export * from "./ndp-registry.js";
+export * from "./validator.js";

package/src/ndp/ndp-registry.ts

@@ -0,0 +1,82 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+import type { AnnounceFrame, NdpResolveResult } from "./frames.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;
+  }
+
+  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

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

@@ -0,0 +1,64 @@
+// 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.");
+    }
+  }
+}

package/src/nip/frames.ts

@@ -0,0 +1,106 @@
+// 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 IdentMetadata {
+  issuer:       string;
+  issuedAt:     string;
+  expiresAt?:   string;
+  capabilities?: readonly string[];
+  scopes?:       readonly string[];
+}
+
+export class IdentFrame implements NpsFrame {
+  readonly frameType     = FrameType.IDENT;
+  readonly preferredTier = EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly nid:       string,
+    public readonly pubKey:    string,
+    public readonly metadata:  IdentMetadata,
+    public readonly signature: string,
+  ) {}
+
+  unsignedDict(): Record<string, unknown> {
+    return {
+      nid:      this.nid,
+      pub_key:  this.pubKey,
+      metadata: this.metadata,
+    };
+  }
+
+  toDict(): Record<string, unknown> {
+    return { ...this.unsignedDict(), signature: this.signature };
+  }
+
+  static fromDict(data: Record<string, unknown>): IdentFrame {
+    return new IdentFrame(
+      data["nid"]       as string,
+      data["pub_key"]   as string,
+      data["metadata"]  as IdentMetadata,
+      data["signature"] as string,
+    );
+  }
+}
+
+export class TrustFrame implements NpsFrame {
+  readonly frameType     = FrameType.TRUST;
+  readonly preferredTier = EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly issuerNid:  string,
+    public readonly subjectNid: string,
+    public readonly scopes:     readonly string[],
+    public readonly expiresAt:  string,
+    public readonly signature:  string,
+  ) {}
+
+  toDict(): Record<string, unknown> {
+    return {
+      issuer_nid:  this.issuerNid,
+      subject_nid: this.subjectNid,
+      scopes:      this.scopes,
+      expires_at:  this.expiresAt,
+      signature:   this.signature,
+    };
+  }
+
+  static fromDict(data: Record<string, unknown>): TrustFrame {
+    return new TrustFrame(
+      data["issuer_nid"]  as string,
+      data["subject_nid"] as string,
+      data["scopes"]      as string[],
+      data["expires_at"]  as string,
+      data["signature"]   as string,
+    );
+  }
+}
+
+export class RevokeFrame implements NpsFrame {
+  readonly frameType     = FrameType.REVOKE;
+  readonly preferredTier = EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly nid:       string,
+    public readonly reason?:   string,
+    public readonly revokedAt?: string,
+  ) {}
+
+  toDict(): Record<string, unknown> {
+    return {
+      nid:        this.nid,
+      reason:     this.reason     ?? null,
+      revoked_at: this.revokedAt  ?? null,
+    };
+  }
+
+  static fromDict(data: Record<string, unknown>): RevokeFrame {
+    return new RevokeFrame(
+      data["nid"]        as string,
+      (data["reason"]     as string | null) ?? undefined,
+      (data["revoked_at"] as string | null) ?? undefined,
+    );
+  }
+}