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

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/index.ts

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

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

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

package/src/nip/frames.ts

@@ -1,106 +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 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,
-    );
-  }
-}

package/src/nip/identity.ts

@@ -1,113 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-/**
- * NipIdentity — Ed25519 key management and signing for NPS NID identity.
- * Uses @noble/ed25519 for signing; node:crypto for key storage encryption.
- */
-
-import * as ed25519 from "@noble/ed25519";
-import { sha512 } from "@noble/hashes/sha512";
-import { createCipheriv, createDecipheriv, pbkdf2Sync, randomBytes } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
-
-// noble/ed25519 requires sha512 to be set explicitly in Node environments
-ed25519.etc.sha512Sync = (...m) => sha512(ed25519.etc.concatBytes(...m));
-
-const KEY_FILE_VERSION = 1;
-const PBKDF2_ITERS     = 600_000;
-const SALT_BYTES       = 16;
-const IV_BYTES         = 12;
-const KEY_BYTES        = 32;
-
-interface KeyFileEnvelope {
-  version:    number;
-  salt:       string; // hex
-  iv:         string; // hex
-  ciphertext: string; // hex
-  pubKey:     string; // hex
-}
-
-export class NipIdentity {
-  private constructor(
-    private readonly _privKey: Uint8Array,
-    public  readonly pubKey:   Uint8Array,
-  ) {}
-
-  // ── Factory ───────────────────────────────────────────────────────────────
-
-  static generate(): NipIdentity {
-    const priv = ed25519.utils.randomPrivateKey();
-    const pub  = ed25519.getPublicKey(priv);
-    return new NipIdentity(priv, pub);
-  }
-
-  static fromPrivateKey(privKey: Uint8Array): NipIdentity {
-    const pub = ed25519.getPublicKey(privKey);
-    return new NipIdentity(privKey, pub);
-  }
-
-  /** Load from an AES-256-GCM encrypted key file. */
-  static load(path: string, passphrase: string): NipIdentity {
-    const envelope = JSON.parse(readFileSync(path, "utf8")) as KeyFileEnvelope;
-    const salt      = Buffer.from(envelope.salt,       "hex");
-    const iv        = Buffer.from(envelope.iv,         "hex");
-    const ct        = Buffer.from(envelope.ciphertext, "hex");
-
-    const dk = pbkdf2Sync(passphrase, salt, PBKDF2_ITERS, KEY_BYTES, "sha256");
-    const decipher = createDecipheriv("aes-256-gcm", dk, iv);
-    // Last 16 bytes of ciphertext are the GCM auth tag
-    const authTag = ct.slice(ct.length - 16);
-    const body    = ct.slice(0, ct.length - 16);
-    (decipher as ReturnType<typeof createDecipheriv> & { setAuthTag(tag: Buffer): void }).setAuthTag(authTag);
-    const priv = Buffer.concat([decipher.update(body), decipher.final()]);
-    return NipIdentity.fromPrivateKey(new Uint8Array(priv));
-  }
-
-  /** Save to an AES-256-GCM encrypted key file. */
-  save(path: string, passphrase: string): void {
-    const salt   = randomBytes(SALT_BYTES);
-    const iv     = randomBytes(IV_BYTES);
-    const dk     = pbkdf2Sync(passphrase, salt, PBKDF2_ITERS, KEY_BYTES, "sha256");
-    const cipher = createCipheriv("aes-256-gcm", dk, iv);
-    const body   = Buffer.concat([cipher.update(Buffer.from(this._privKey)), cipher.final()]);
-    const tag    = (cipher as ReturnType<typeof createCipheriv> & { getAuthTag(): Buffer }).getAuthTag();
-
-    const envelope: KeyFileEnvelope = {
-      version:    KEY_FILE_VERSION,
-      salt:       salt.toString("hex"),
-      iv:         iv.toString("hex"),
-      ciphertext: Buffer.concat([body, tag]).toString("hex"),
-      pubKey:     Buffer.from(this.pubKey).toString("hex"),
-    };
-    writeFileSync(path, JSON.stringify(envelope, null, 2), "utf8");
-  }
-
-  // ── Signing ───────────────────────────────────────────────────────────────
-
-  /** Sign a dict payload. Returns `ed25519:<base64url>`. */
-  sign(payload: Record<string, unknown>): string {
-    const canonical = JSON.stringify(payload, Object.keys(payload).sort());
-    const bytes     = new TextEncoder().encode(canonical);
-    const sig       = ed25519.sign(bytes, this._privKey);
-    return `ed25519:${Buffer.from(sig).toString("base64")}`;
-  }
-
-  /** Verify a signature string against a dict payload. */
-  verify(payload: Record<string, unknown>, signature: string): boolean {
-    if (!signature.startsWith("ed25519:")) return false;
-    try {
-      const canonical = JSON.stringify(payload, Object.keys(payload).sort());
-      const bytes     = new TextEncoder().encode(canonical);
-      const sigBytes  = Buffer.from(signature.slice("ed25519:".length), "base64");
-      return ed25519.verify(sigBytes, bytes, this.pubKey);
-    } catch {
-      return false;
-    }
-  }
-
-  /** Public key as `ed25519:<hex>` string. */
-  get pubKeyString(): string {
-    return `ed25519:${Buffer.from(this.pubKey).toString("hex")}`;
-  }
-}

package/src/nip/index.ts

@@ -1,6 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-export * from "./frames.js";
-export * from "./identity.js";
-export { registerNipFrames } from "./registry.js";

package/src/nip/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 { IdentFrame, TrustFrame, RevokeFrame } from "./frames.js";
-
-export function registerNipFrames(registry: FrameRegistry): void {
-  registry.register(FrameType.IDENT,  IdentFrame);
-  registry.register(FrameType.TRUST,  TrustFrame);
-  registry.register(FrameType.REVOKE, RevokeFrame);
-}

package/src/nop/client.ts

@@ -1,103 +0,0 @@
-// Copyright 2026 INNO LOTUS PTY LTD
-// SPDX-License-Identifier: Apache-2.0
-
-import { NpsFrameCodec } from "../core/codec.js";
-import { EncodingTier } from "../core/frames.js";
-import { FrameRegistry } from "../core/registry.js";
-import { registerNcpFrames } from "../ncp/registry.js";
-import { registerNopFrames } from "./registry.js";
-import { TaskState } from "./models.js";
-import type { TaskFrame } from "./frames.js";
-
-const TERMINAL_STATES = new Set<TaskState>([
-  TaskState.COMPLETED,
-  TaskState.FAILED,
-  TaskState.CANCELLED,
-]);
-
-export class NopTaskStatus {
-  constructor(private readonly _raw: Record<string, unknown>) {}
-
-  get taskId():           string              { return this._raw["task_id"]  as string; }
-  get state():            TaskState           { return this._raw["state"] as TaskState; }
-  get isTerminal():       boolean             { return TERMINAL_STATES.has(this._raw["state"] as TaskState); }
-  get aggregatedResult(): unknown             { return this._raw["aggregated_result"]; }
-  get errorCode():        string | undefined  { return (this._raw["error_code"]    as string | null) ?? undefined; }
-  get errorMessage():     string | undefined  { return (this._raw["error_message"] as string | null) ?? undefined; }
-  get nodeResults():      Record<string, unknown> { return (this._raw["node_results"] as Record<string, unknown> | undefined) ?? {}; }
-  get raw():              Record<string, unknown> { return this._raw; }
-
-  toString(): string {
-    return `NopTaskStatus(taskId=${this.taskId}, state=${String(this._raw["state"])})`;
-  }
-}
-
-export class NopClient {
-  private readonly _baseUrl: string;
-  private readonly _codec:   NpsFrameCodec;
-  private readonly _tier:    EncodingTier;
-
-  constructor(
-    baseUrl: string,
-    options: { defaultTier?: EncodingTier; registry?: FrameRegistry } = {},
-  ) {
-    this._baseUrl = baseUrl.replace(/\/$/, "");
-    this._tier    = options.defaultTier ?? EncodingTier.MSGPACK;
-
-    const registry = options.registry ?? (() => {
-      const r = new FrameRegistry();
-      registerNcpFrames(r);
-      registerNopFrames(r);
-      return r;
-    })();
-    this._codec = new NpsFrameCodec(registry);
-  }
-
-  async submit(frame: TaskFrame): Promise<string> {
-    const wire = this._codec.encode(frame, { overrideTier: this._tier });
-    const res  = await fetch(`${this._baseUrl}/task`, {
-      method:  "POST",
-      body:    wire,
-      headers: { "Content-Type": "application/x-nps-frame", "Accept": "application/json" },
-    });
-    if (!res.ok) throw new Error(`NOP /task failed: HTTP ${res.status}`);
-    const data = await res.json() as Record<string, unknown>;
-    return data["task_id"] as string;
-  }
-
-  async getStatus(taskId: string): Promise<NopTaskStatus> {
-    const res = await fetch(`${this._baseUrl}/task/${taskId}`, {
-      headers: { "Accept": "application/json" },
-    });
-    if (!res.ok) throw new Error(`NOP /task/${taskId} failed: HTTP ${res.status}`);
-    return new NopTaskStatus(await res.json() as Record<string, unknown>);
-  }
-
-  async cancel(taskId: string): Promise<void> {
-    const res = await fetch(`${this._baseUrl}/task/${taskId}/cancel`, {
-      method:  "POST",
-      headers: { "Accept": "application/json" },
-    });
-    if (!res.ok) throw new Error(`NOP /task/${taskId}/cancel failed: HTTP ${res.status}`);
-  }
-
-  async wait(
-    taskId: string,
-    options: { pollIntervalMs?: number; timeoutMs?: number } = {},
-  ): Promise<NopTaskStatus> {
-    const pollIntervalMs = options.pollIntervalMs ?? 1000;
-    const timeoutMs      = options.timeoutMs      ?? 30_000;
-    const deadline       = Date.now() + timeoutMs;
-
-    while (true) {
-      const status = await this.getStatus(taskId);
-      if (status.isTerminal) return status;
-
-      const remaining = deadline - Date.now();
-      if (remaining <= 0) {
-        throw new Error(`Task '${taskId}' did not complete within ${timeoutMs}ms (state: ${String(status.raw["state"])}).`);
-      }
-      await new Promise((resolve) => setTimeout(resolve, Math.min(pollIntervalMs, remaining)));
-    }
-  }
-}