@labacacia/nps-sdk 1.0.0-alpha.1

package/src/nip/identity.ts

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

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

@@ -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 { 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

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

package/src/nop/frames.ts

@@ -0,0 +1,181 @@
+// 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";
+import type { AggregateStrategy, TaskContext, TaskDag, TaskPriority } from "./models.js";
+
+// ── TaskFrame ─────────────────────────────────────────────────────────────────
+
+export class TaskFrame implements NpsFrame {
+  readonly frameType     = FrameType.TASK;
+  readonly preferredTier = EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly taskId:       string,
+    public readonly dag:          TaskDag,
+    public readonly timeoutMs?:   number,
+    public readonly callbackUrl?: string,
+    public readonly context?:     TaskContext,
+    public readonly priority?:    TaskPriority,
+    public readonly depth?:       number,
+  ) {}
+
+  toDict(): Record<string, unknown> {
+    return {
+      task_id:      this.taskId,
+      dag:          this.dag,
+      timeout_ms:   this.timeoutMs   ?? null,
+      callback_url: this.callbackUrl ?? null,
+      context:      this.context     ?? null,
+      priority:     this.priority    ?? null,
+      depth:        this.depth       ?? null,
+    };
+  }
+
+  static fromDict(data: Record<string, unknown>): TaskFrame {
+    return new TaskFrame(
+      data["task_id"]      as string,
+      data["dag"]          as TaskDag,
+      (data["timeout_ms"]   as number | null) ?? undefined,
+      (data["callback_url"] as string | null) ?? undefined,
+      (data["context"]      as TaskContext | null) ?? undefined,
+      (data["priority"]     as TaskPriority | null) ?? undefined,
+      (data["depth"]        as number | null) ?? undefined,
+    );
+  }
+}
+
+// ── DelegateFrame ─────────────────────────────────────────────────────────────
+
+export class DelegateFrame implements NpsFrame {
+  readonly frameType     = FrameType.DELEGATE;
+  readonly preferredTier = EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly taskId:         string,
+    public readonly subtaskId:      string,
+    public readonly action:         string,
+    public readonly agentNid:       string,
+    public readonly inputs?:        Record<string, unknown>,
+    public readonly params?:        Record<string, unknown>,
+    public readonly idempotencyKey?: string,
+  ) {}
+
+  toDict(): Record<string, unknown> {
+    return {
+      task_id:         this.taskId,
+      subtask_id:      this.subtaskId,
+      action:          this.action,
+      agent_nid:       this.agentNid,
+      inputs:          this.inputs          ?? null,
+      params:          this.params          ?? null,
+      idempotency_key: this.idempotencyKey  ?? null,
+    };
+  }
+
+  static fromDict(data: Record<string, unknown>): DelegateFrame {
+    return new DelegateFrame(
+      data["task_id"]         as string,
+      data["subtask_id"]      as string,
+      data["action"]          as string,
+      data["agent_nid"]       as string,
+      (data["inputs"]          as Record<string, unknown> | null) ?? undefined,
+      (data["params"]          as Record<string, unknown> | null) ?? undefined,
+      (data["idempotency_key"] as string | null) ?? undefined,
+    );
+  }
+}
+
+// ── SyncFrame ─────────────────────────────────────────────────────────────────
+
+export class SyncFrame implements NpsFrame {
+  readonly frameType     = FrameType.SYNC;
+  readonly preferredTier = EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly taskId:      string,
+    public readonly syncId:      string,
+    public readonly waitFor:     readonly string[],
+    public readonly minRequired: number = 0,
+    public readonly aggregate:   AggregateStrategy | string = "merge",
+    public readonly timeoutMs?:  number,
+  ) {}
+
+  toDict(): Record<string, unknown> {
+    return {
+      task_id:      this.taskId,
+      sync_id:      this.syncId,
+      wait_for:     this.waitFor,
+      min_required: this.minRequired,
+      aggregate:    this.aggregate,
+      timeout_ms:   this.timeoutMs ?? null,
+    };
+  }
+
+  static fromDict(data: Record<string, unknown>): SyncFrame {
+    return new SyncFrame(
+      data["task_id"]      as string,
+      data["sync_id"]      as string,
+      data["wait_for"]     as string[],
+      (data["min_required"] as number) ?? 0,
+      (data["aggregate"]    as string) ?? "merge",
+      (data["timeout_ms"]   as number | null) ?? undefined,
+    );
+  }
+}
+
+// ── StreamError ───────────────────────────────────────────────────────────────
+
+export interface StreamError {
+  errorCode: string;
+  message?:  string;
+}
+
+// ── AlignStreamFrame ──────────────────────────────────────────────────────────
+
+export class AlignStreamFrame implements NpsFrame {
+  readonly frameType     = FrameType.ALIGN_STREAM;
+  readonly preferredTier = EncodingTier.MSGPACK;
+
+  constructor(
+    public readonly streamId:   string,
+    public readonly taskId:     string,
+    public readonly subtaskId:  string,
+    public readonly seq:        number,
+    public readonly isFinal:    boolean,
+    public readonly senderNid:  string,
+    public readonly data?:      Record<string, unknown>,
+    public readonly error?:     StreamError,
+    public readonly windowSize?: number,
+  ) {}
+
+  toDict(): Record<string, unknown> {
+    return {
+      stream_id:   this.streamId,
+      task_id:     this.taskId,
+      subtask_id:  this.subtaskId,
+      seq:         this.seq,
+      is_final:    this.isFinal,
+      sender_nid:  this.senderNid,
+      data:        this.data        ?? null,
+      error:       this.error ? { error_code: this.error.errorCode, message: this.error.message ?? null } : null,
+      window_size: this.windowSize  ?? null,
+    };
+  }
+
+  static fromDict(data: Record<string, unknown>): AlignStreamFrame {
+    const rawError = data["error"] as { error_code: string; message?: string } | null;
+    return new AlignStreamFrame(
+      data["stream_id"]  as string,
+      data["task_id"]    as string,
+      data["subtask_id"] as string,
+      data["seq"]        as number,
+      data["is_final"]   as boolean,
+      data["sender_nid"] as string,
+      (data["data"]        as Record<string, unknown> | null) ?? undefined,
+      rawError ? { errorCode: rawError.error_code, ...(rawError.message != null ? { message: rawError.message } : {}) } : undefined,
+      (data["window_size"] as number | null) ?? undefined,
+    );
+  }
+}

package/src/nop/index.ts

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

package/src/nop/models.ts

@@ -0,0 +1,79 @@
+// Copyright 2026 INNO LOTUS PTY LTD
+// SPDX-License-Identifier: Apache-2.0
+
+export enum TaskState {
+  PENDING       = "pending",
+  PREFLIGHT     = "preflight",
+  RUNNING       = "running",
+  WAITING_SYNC  = "waiting_sync",
+  COMPLETED     = "completed",
+  FAILED        = "failed",
+  CANCELLED     = "cancelled",
+  SKIPPED       = "skipped",
+}
+
+export enum TaskPriority {
+  LOW    = "low",
+  NORMAL = "normal",
+  HIGH   = "high",
+}
+
+export enum BackoffStrategy {
+  FIXED       = "fixed",
+  LINEAR      = "linear",
+  EXPONENTIAL = "exponential",
+}
+
+export enum AggregateStrategy {
+  MERGE      = "merge",
+  FIRST      = "first",
+  FASTEST_K  = "fastest_k",
+  ALL        = "all",
+}
+
+export interface RetryPolicy {
+  maxRetries:   number;
+  backoff:      BackoffStrategy;
+  baseDelayMs?: number;
+  maxDelayMs?:  number;
+}
+
+export function computeDelayMs(policy: RetryPolicy, attempt: number): number {
+  const base = policy.baseDelayMs ?? 1000;
+  const cap  = policy.maxDelayMs  ?? 30_000;
+  let delay: number;
+  switch (policy.backoff) {
+    case BackoffStrategy.FIXED:       delay = base; break;
+    case BackoffStrategy.LINEAR:      delay = base * (attempt + 1); break;
+    case BackoffStrategy.EXPONENTIAL: delay = base * Math.pow(2, attempt); break;
+  }
+  return Math.min(delay, cap);
+}
+
+export interface TaskContext {
+  sessionKey?:    string;
+  requesterNid?:  string;
+  traceId?:       string;
+}
+
+export interface DagNode {
+  id:             string;
+  action:         string;
+  agent:          string;
+  inputFrom?:     readonly string[];
+  inputMapping?:  Record<string, string>;
+  timeoutMs?:     number;
+  retryPolicy?:   RetryPolicy;
+  condition?:     string;
+  minRequired?:   number;
+}
+
+export interface DagEdge {
+  from: string;
+  to:   string;
+}
+
+export interface TaskDag {
+  nodes: readonly DagNode[];
+  edges: readonly DagEdge[];
+}