@nanobpm/agentic 0.1.0

package/src/channel/auth.ts

@@ -0,0 +1,101 @@
+/**
+ * Connection authentication.
+ *
+ * A peer authenticates at the app-tier handshake with an ADR 0028 identity
+ * token PLUS a capability credential — the same pattern nano-workforce's
+ * blackboard hook already uses (`?token=…`). This is a connection-level gate:
+ * capability (cognition / weight / family / host) travels later on the
+ * `register` frame as an enrolment attribute and is NEVER a routing token.
+ *
+ * The hub takes any {@link Authenticator}; {@link sharedSecretAuthenticator} is
+ * the batteries-included default.
+ */
+import { timingSafeEqual } from "node:crypto";
+import type { HandshakeRequest } from "./connection.ts";
+
+/** What the authenticator grants a peer once it passes the gate. */
+export interface AuthGrant {
+  /** The authenticated principal (ADR 0028 identity). */
+  readonly identity: string;
+  /** Optional scope the identity is confined to (e.g. a plan/network). */
+  readonly scope?: string;
+  /** The capability credential the peer presented, if any. */
+  readonly capability?: string;
+}
+
+/** Application close code for a rejected identity token. */
+export const AUTH_UNAUTHORIZED = 4401;
+/** Application close code for a missing/rejected capability credential. */
+export const AUTH_FORBIDDEN = 4403;
+
+export type AuthResult =
+  | { readonly ok: true; readonly grant: AuthGrant }
+  | { readonly ok: false; readonly code: number; readonly reason: string };
+
+/** Verifies a handshake and either grants or rejects the connection. */
+export type Authenticator = (req: HandshakeRequest) => AuthResult | Promise<AuthResult>;
+
+/**
+ * Constant-time string comparison. Unequal-length inputs short-circuit to
+ * `false` (length is not itself secret here); equal-length inputs are compared
+ * in constant time via {@link timingSafeEqual}.
+ */
+function safeEqual(a: string, b: string): boolean {
+  const ab = new TextEncoder().encode(a);
+  const bb = new TextEncoder().encode(b);
+  if (ab.length !== bb.length) {
+    return false;
+  }
+  return timingSafeEqual(ab, bb);
+}
+
+/** Read the identity token from the handshake (explicit field or `token` query). */
+function tokenOf(req: HandshakeRequest): string | undefined {
+  return req.token ?? req.query?.token;
+}
+
+/**
+ * Read the capability credential from the handshake: explicit field, the
+ * `capability` query param, or the `x-capability-credential` header.
+ */
+function credentialOf(req: HandshakeRequest): string | undefined {
+  return req.credential ?? req.query?.capability ?? req.headers?.["x-capability-credential"];
+}
+
+export interface SharedSecretAuthOptions {
+  /** The shared identity-token secret every valid peer presents. */
+  readonly secret: string;
+  /** Require a capability credential too (default true). */
+  readonly requireCredential?: boolean;
+  /** Extra check on the credential; return false to reject. Default accept-any. */
+  readonly verifyCredential?: (credential: string, identity: string) => boolean;
+  /** Derive the identity from the handshake. Default: the connection's remote address (`req.remote`), or `anonymous`. */
+  readonly identityFor?: (req: HandshakeRequest) => string;
+}
+
+/**
+ * The default authenticator: a shared-secret identity token gate plus a required
+ * capability credential. Mirrors nano-workforce's blackboard-hook `?token=…`
+ * pattern; swap in a real ADR 0028 verifier by passing your own
+ * {@link Authenticator} to the hub.
+ */
+export function sharedSecretAuthenticator(options: SharedSecretAuthOptions): Authenticator {
+  const requireCredential = options.requireCredential ?? true;
+  return (req: HandshakeRequest): AuthResult => {
+    const token = tokenOf(req);
+    if (token === undefined || !safeEqual(token, options.secret)) {
+      return { ok: false, code: AUTH_UNAUTHORIZED, reason: "invalid identity token" };
+    }
+    const identity = options.identityFor ? options.identityFor(req) : (req.remote ?? "anonymous");
+    const credential = credentialOf(req);
+    if (requireCredential) {
+      if (credential === undefined || credential.length === 0) {
+        return { ok: false, code: AUTH_FORBIDDEN, reason: "missing capability credential" };
+      }
+      if (options.verifyCredential && !options.verifyCredential(credential, identity)) {
+        return { ok: false, code: AUTH_FORBIDDEN, reason: "capability credential rejected" };
+      }
+    }
+    return { ok: true, grant: { identity, capability: credential } };
+  };
+}

package/src/channel/clock.ts

@@ -0,0 +1,14 @@
+/**
+ * An injectable monotonic-ish wall clock. The hub and connection registry read
+ * time only through a {@link Clock} so liveness/TTL behaviour is deterministic
+ * under test (pass a fake clock) without sleeping on the real timer.
+ */
+export interface Clock {
+  /** Current time in epoch milliseconds. */
+  now(): number;
+}
+
+/** The production clock, backed by {@link Date.now}. */
+export const systemClock: Clock = {
+  now: () => Date.now(),
+};

package/src/channel/connection.ts

@@ -0,0 +1,77 @@
+/**
+ * Transport-agnostic connection contracts.
+ *
+ * The hub owns connection lifecycle and framing; it speaks to the network only
+ * through {@link ChannelTransport} / {@link ChannelConnection}. That keeps the
+ * hub deterministically testable over an in-memory transport and lets the real
+ * {@link WebSocketChannelTransport} (or any future transport) be a thin adapter.
+ *
+ * A connection carries opaque, already-encoded protocol frames as bytes — the
+ * hub decodes them with the S0 codec (`@nanobpm/agentic-protocol`). This channel
+ * is served by the app on its OWN bound port; the Camunda-8 engine transport is
+ * a separate connection and is never touched here.
+ */
+
+/**
+ * Everything the transport learns about a peer at connect time, BEFORE any
+ * protocol frame is exchanged. The default authenticator reads the ADR 0028
+ * identity token and the capability credential from here (mirroring the
+ * `?token=…` pattern nano-workforce's blackboard hook already uses).
+ */
+export interface HandshakeRequest {
+  /** ADR 0028 identity token (typically the `token` query param or a header). */
+  readonly token?: string;
+  /** Capability credential authorising the peer to enrol. */
+  readonly credential?: string;
+  /** Remote address, for logging/diagnostics only. */
+  readonly remote?: string;
+  /** Lower-cased request headers. */
+  readonly headers?: Readonly<Record<string, string>>;
+  /** Parsed query-string parameters. */
+  readonly query?: Readonly<Record<string, string>>;
+}
+
+/** Close-status code (WebSocket application range 3000–4999 for our own codes). */
+export type CloseCode = number;
+
+/**
+ * A single duplex connection to a peer. The hub registers exactly one message
+ * and one close listener; a transport may deliver `pong` for keepalive.
+ */
+export interface ChannelConnection {
+  /** Stable per-connection id (unique for the life of the process). */
+  readonly id: string;
+  /** What the transport captured about the peer at connect time. */
+  readonly handshake: HandshakeRequest;
+  /** Send one already-encoded frame as binary bytes. */
+  send(bytes: Uint8Array): void;
+  /** Close the connection with an optional application close code + reason. */
+  close(code?: CloseCode, reason?: string): void;
+  /** Register the (single) inbound-bytes listener. */
+  onMessage(listener: (bytes: Uint8Array) => void): void;
+  /** Register the (single) close listener. */
+  onClose(listener: (code?: CloseCode, reason?: string) => void): void;
+  /** Register a keepalive pong listener, if the transport supports ping/pong. */
+  onPong?(listener: () => void): void;
+  /**
+   * Register an inbound-ping listener, if the transport supports ping/pong. A
+   * peer-driven keepalive typically arrives as an inbound ping (the transport
+   * auto-replies with a pong), so an inbound ping is also proof of life.
+   */
+  onPing?(listener: () => void): void;
+  /** Send a keepalive ping, if the transport supports it. */
+  ping?(): void;
+}
+
+/**
+ * A listening transport, bound to the app's own port. It emits a
+ * {@link ChannelConnection} for every accepted, upgraded peer.
+ */
+export interface ChannelTransport {
+  /** Register the handler invoked for each newly accepted connection. */
+  onConnection(listener: (conn: ChannelConnection) => void): void;
+  /** The bound address once listening, or `null` before/after. */
+  readonly address: { readonly port: number } | null;
+  /** Stop accepting and release the port. */
+  close(): Promise<void>;
+}

package/src/channel/dispatch.test.ts

@@ -0,0 +1,83 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { decodeFrame, encodeFrame } from "../protocol/index.ts";
+import type { Frame } from "../protocol/index.ts";
+import {
+  DuplicateFamilyHandlerError,
+  FamilyRouter,
+  UnknownFamilyError,
+} from "./dispatch.ts";
+
+function frame(family: Frame["family"], seq = 1): Frame {
+  return { lane: "control", family, seq, payload: { seq } };
+}
+
+test("routes each frame to the handler registered for its family (>=2 families)", async () => {
+  const router = new FamilyRouter<string[]>();
+  const heard: string[] = [];
+
+  // Two distinct family modules attach themselves through the seam.
+  router.registerFamilyHandler("register", (f, ctx) => {
+    ctx.push(`register:${f.seq}`);
+  });
+  router.registerFamilyHandler("relay", (f, ctx) => {
+    ctx.push(`relay:${f.seq}`);
+  });
+
+  assert.ok(await router.route(frame("register", 1), heard));
+  assert.ok(await router.route(frame("relay", 2), heard));
+  assert.ok(await router.route(frame("register", 3), heard));
+
+  // Each frame reached exactly its own handler — no cross-talk.
+  assert.deepEqual(heard, ["register:1", "relay:2", "register:3"]);
+  assert.deepEqual(router.families().sort(), ["register", "relay"]);
+});
+
+test("the routing table is derived, not hard-coded — encode/decode round-trips through it", async () => {
+  const router = new FamilyRouter<Frame[]>();
+  const seen: Frame[] = [];
+  router.registerFamilyHandler("heartbeat", (f, ctx) => {
+    ctx.push(f);
+  });
+
+  // Prove the table (not a switch) drives dispatch by feeding a real wire frame:
+  // encode to bytes, decode back, then route the decoded frame so the full
+  // wire->frame->table path is exercised (not a freshly constructed frame).
+  const bytes = encodeFrame(frame("heartbeat", 7));
+  assert.ok(bytes.length > 0);
+  const decoded = decodeFrame(bytes);
+  await router.route(decoded, seen);
+  assert.equal(seen.length, 1);
+  assert.equal(seen[0]?.family, "heartbeat");
+  assert.equal(seen[0]?.seq, 7);
+});
+
+test("a second handler for the same family is refused", () => {
+  const router = new FamilyRouter<void>();
+  router.registerFamilyHandler("blackboard", () => {});
+  assert.throws(
+    () => router.registerFamilyHandler("blackboard", () => {}),
+    (err) => err instanceof DuplicateFamilyHandlerError && err.family === "blackboard",
+  );
+});
+
+test("registering a key outside the S0 family set is refused", () => {
+  const router = new FamilyRouter<void>();
+  const notAFamily = JSON.parse('"telemetry"');
+  assert.throws(
+    () => router.registerFamilyHandler(notAFamily, () => {}),
+    (err) => err instanceof UnknownFamilyError,
+  );
+});
+
+test("an unregistered family falls through to the unhandled fallback", async () => {
+  const router = new FamilyRouter<string[]>();
+  const heard: string[] = [];
+  router.onUnhandled((f, ctx) => {
+    ctx.push(`unhandled:${f.family}`);
+  });
+
+  const handled = await router.route(frame("demand", 1), heard);
+  assert.equal(handled, false);
+  assert.deepEqual(heard, ["unhandled:demand"]);
+});

package/src/channel/dispatch.ts

@@ -0,0 +1,102 @@
+/**
+ * The family-handler registration seam — S1's canonical extension point.
+ *
+ * Multiple wave-2 slices (S2 presence/registry, S5 relay, S7 blackboard) each
+ * attach a NEW inbound message-family handler to the single hub. To stop them
+ * colliding on a central `switch (frame.family)`, the hub's frame→family routing
+ * is DERIVED from this registration table: each family is a self-contained
+ * module that attaches itself with {@link FamilyRouter.registerFamilyHandler}
+ * and the router dispatches by table lookup — never a hand-edited switch.
+ *
+ * Family keys are the S0 {@link MessageFamily} set (`@nanobpm/agentic-protocol`),
+ * the one source of truth; registering a key outside that set is rejected.
+ */
+import { isMessageFamily } from "../protocol/index.ts";
+import type { Frame, MessageFamily } from "../protocol/index.ts";
+
+/**
+ * A handler for one message family. `ctx` is whatever per-connection context
+ * the hub threads through (see {@link HubConnection}); the router itself is
+ * generic so it can be unit-tested without the hub.
+ */
+export type FamilyHandler<Ctx> = (frame: Frame, ctx: Ctx) => void | Promise<void>;
+
+/** Raised when a family key outside the S0 {@link MessageFamily} set is used. */
+export class UnknownFamilyError extends Error {
+  readonly family: string;
+  constructor(family: string) {
+    super(`unknown message family: ${family}`);
+    this.name = "UnknownFamilyError";
+    this.family = family;
+  }
+}
+
+/**
+ * Raised when a second handler is registered for a family that already has one.
+ * One family, one owning module — this guard is what stops two sibling slices
+ * silently clobbering each other's handler.
+ */
+export class DuplicateFamilyHandlerError extends Error {
+  readonly family: MessageFamily;
+  constructor(family: MessageFamily) {
+    super(`a handler is already registered for family: ${family}`);
+    this.name = "DuplicateFamilyHandlerError";
+    this.family = family;
+  }
+}
+
+/**
+ * The derived frame→family routing table. The hub holds one of these; every
+ * family module attaches through {@link registerFamilyHandler}.
+ */
+export class FamilyRouter<Ctx> {
+  readonly #handlers = new Map<MessageFamily, FamilyHandler<Ctx>>();
+  #onUnhandled: FamilyHandler<Ctx> | undefined;
+
+  /**
+   * Attach the handler that owns `family`. This is the seam every family module
+   * calls; it keys off the S0 family set and refuses a duplicate so two slices
+   * cannot both claim one family.
+   */
+  registerFamilyHandler(family: MessageFamily, handler: FamilyHandler<Ctx>): void {
+    if (!isMessageFamily(family)) {
+      throw new UnknownFamilyError(family);
+    }
+    if (this.#handlers.has(family)) {
+      throw new DuplicateFamilyHandlerError(family);
+    }
+    this.#handlers.set(family, handler);
+  }
+
+  /** Set the fallback invoked for a frame whose family has no handler. */
+  onUnhandled(handler: FamilyHandler<Ctx>): void {
+    this.#onUnhandled = handler;
+  }
+
+  /** Whether a handler is registered for `family`. */
+  has(family: MessageFamily): boolean {
+    return this.#handlers.has(family);
+  }
+
+  /** The families that currently have a handler (the derived table's keys). */
+  families(): MessageFamily[] {
+    return [...this.#handlers.keys()];
+  }
+
+  /**
+   * Route one decoded frame to its family handler by table lookup. Returns
+   * `true` if a family handler ran, `false` if it fell through to the unhandled
+   * fallback (or nowhere). Any handler rejection propagates to the caller.
+   */
+  async route(frame: Frame, ctx: Ctx): Promise<boolean> {
+    const handler = this.#handlers.get(frame.family);
+    if (handler === undefined) {
+      if (this.#onUnhandled !== undefined) {
+        await this.#onUnhandled(frame, ctx);
+      }
+      return false;
+    }
+    await handler(frame, ctx);
+    return true;
+  }
+}