airaknit 1.1.2-rc.9

package/src/nats/auth-callout/scope-policy.ts

@@ -0,0 +1,210 @@
+/**
+ * Subject-scope policy for NATS auth-callout (Stage A, PR1).
+ *
+ * Three connection classes are defined in design.md; this module is the
+ * single source of truth for what each class may publish and subscribe.
+ * Pure — no I/O, fully unit-testable.
+ */
+
+/** The three connection classes defined by PR1. */
+export type ConnectionClass = "server-admin" | "ui-client" | "runner"
+
+/** Resolved identity, output of credential validation in the responder. */
+export type ResolvedIdentity =
+  | { class: "server-admin" }
+  | { class: "ui-client" }
+  | { class: "runner"; runnerId: string }
+
+/** Allow/deny lists for pub and sub that go into the signed user JWT. */
+export interface SubjectScope {
+  pub: { allow: string[]; deny: string[] }
+  sub: { allow: string[]; deny: string[] }
+}
+
+// ── KV / JetStream subject patterns ─────────────────────────────────────────
+//
+// KV write to a specific key in bucket B maps to:
+//   $KV.B.<key>          — the client publishes to this subject
+// KV reads and JetStream API calls use:
+//   $JS.API.>            — broad JetStream API
+//   $KV.>               — all KV subjects (reads/meta)
+//
+// For a runner scoped to its own registry key, we allow publish on its key
+// and deny publish on any other key in the registry bucket.
+
+/** KV bucket for runner registration (from runner-protocol.ts). */
+const RUNNER_REGISTRY_BUCKET = "runtime_runner_registry"
+
+/** Build the runner's own KV key subject. */
+function runnerOwnKvSubject(runnerId: string): string {
+  return `$KV.${RUNNER_REGISTRY_BUCKET}.${runnerId}`
+}
+
+
+// ── Policy factory ───────────────────────────────────────────────────────────
+
+/**
+ * Return the publish/subscribe allow-deny scope for a resolved identity.
+ * The caller signs these into a user JWT; NATS enforces them.
+ */
+export function permissionsFor(identity: ResolvedIdentity): SubjectScope {
+  switch (identity.class) {
+    case "server-admin":
+      return serverAdminScope()
+    case "ui-client":
+      return uiClientScope()
+    case "runner":
+      return runnerScope(identity.runnerId)
+  }
+}
+
+// ── Per-class policies (match design.md exactly) ─────────────────────────────
+
+function serverAdminScope(): SubjectScope {
+  return {
+    pub: {
+      allow: [
+        "runtime.>",    // all runtime subjects
+        "$JS.API.>",    // JetStream API
+        "$JS.ACK.>",    // JetStream message acknowledgements (separate tree from $JS.API)
+        "$KV.>",        // all KV operations
+        "_INBOX.>",     // inbox replies
+      ],
+      deny: [],
+    },
+    sub: {
+      allow: [
+        "runtime.>",
+        "$JS.API.>",
+        "$JS.ACK.>",
+        "$KV.>",
+        "_INBOX.>",
+        "$SYS.REQ.USER.AUTH", // callout responder subscription
+      ],
+      deny: [],
+    },
+  }
+}
+
+function uiClientScope(): SubjectScope {
+  // ui-client may only publish to runtime.cmd.> (UI commands).
+  // runtime.runner.cmd.> is NOT in the allow list → denied by NATS by default.
+  // No deny list needed: NATS's allow-only model covers this.
+  //
+  // JetStream subjects: the browser calls js.consumers.get(KANNA_CHAT_MESSAGE_EVENTS, ...)
+  // which publishes to these $JS.API.* subjects (empirically confirmed in Stage D):
+  //   $JS.API.STREAM.INFO.KANNA_CHAT_MESSAGE_EVENTS  — stream lookup before consumer create
+  //   $JS.API.CONSUMER.CREATE.KANNA_CHAT_MESSAGE_EVENTS  — ephemeral consumer create
+  //   $JS.API.CONSUMER.CREATE.KANNA_CHAT_MESSAGE_EVENTS.*  — named variant (filter-subject path)
+  //   $JS.API.CONSUMER.INFO.KANNA_CHAT_MESSAGE_EVENTS.*    — status checks on reconnect
+  //   $JS.API.CONSUMER.DELETE.KANNA_CHAT_MESSAGE_EVENTS.*  — cleanup on close
+  //
+  // Scoped to KANNA_CHAT_MESSAGE_EVENTS only — the single stream the browser client
+  // accesses directly (see nats-socket.ts activateJetStreamConsumer). The browser
+  // never touches other KANNA_* streams or any admin API ($JS.API.STREAM.CREATE, etc).
+  return {
+    pub: {
+      allow: [
+        "runtime.cmd.>",  // UI commands only (runner cmds NOT included)
+        "_INBOX.>",
+        // JetStream consumer lifecycle for KANNA_CHAT_MESSAGE_EVENTS only.
+        // When filter_subjects is set, the library appends both an ephemeral name
+        // AND the filter subject token, producing:
+        //   $JS.API.CONSUMER.CREATE.KANNA_CHAT_MESSAGE_EVENTS.<name>.<filter>
+        // so we need ">" (rest-of-subject wildcard) not just "*" (single token).
+        // INFO and DELETE also use "<stream>.<name>" (two tokens past the stream).
+        "$JS.API.STREAM.INFO.KANNA_CHAT_MESSAGE_EVENTS",
+        "$JS.API.CONSUMER.CREATE.KANNA_CHAT_MESSAGE_EVENTS",
+        "$JS.API.CONSUMER.CREATE.KANNA_CHAT_MESSAGE_EVENTS.>",
+        "$JS.API.CONSUMER.INFO.KANNA_CHAT_MESSAGE_EVENTS.>",
+        "$JS.API.CONSUMER.DELETE.KANNA_CHAT_MESSAGE_EVENTS.>",
+        // Pull-consumer fetch: the browser pulls messages via
+        //   $JS.API.CONSUMER.MSG.NEXT.<stream>.<consumer>
+        // This was missing, so every pull was denied (Publish Violation) and the
+        // browser could not read chat messages. Same per-stream scoping as above.
+        "$JS.API.CONSUMER.MSG.NEXT.KANNA_CHAT_MESSAGE_EVENTS.>",
+        // JetStream message acknowledgements for that consumer. $JS.ACK is a
+        // separate subject tree from $JS.API; without it the browser's consumer
+        // can't ack and stalls once max-ack-pending is hit. Scoped to the chat stream.
+        "$JS.ACK.KANNA_CHAT_MESSAGE_EVENTS.>",
+      ],
+      deny: [],
+    },
+    sub: {
+      allow: [
+        "runtime.runner.evt.>",  // runner events
+        "runtime.evt.>",         // general events
+        "runtime.snap.>",        // snapshots
+        "_INBOX.>",
+      ],
+      deny: [],
+    },
+  }
+}
+
+function runnerScope(runnerId: string): SubjectScope {
+  const ownKv = runnerOwnKvSubject(runnerId)
+
+  // NATS permission evaluation: if a subject matches an allow pattern, it is
+  // allowed. If it matches a deny pattern, it is denied regardless of allow.
+  // So for runner isolation we use ALLOW-only lists (no deny needed for sub):
+  //  - allow only the specific runnerId's cmd subject (not a wildcard)
+  //  - this naturally excludes all other runner cmd subjects
+  //
+  // For KV writes (pub): allow the specific key, deny the bucket wildcard so
+  // other keys are blocked. The own key is listed in allow first — but NATS
+  // deny still wins when both match. We rely on a specific-allow narrower than
+  // the deny wildcard to NOT match each other: ownKv is the full key (no
+  // wildcard), and the deny is "$KV.BUCKET.>" which DOES match ownKv.
+  // So we can't use a wildcard deny for the KV bucket.
+  //
+  // Instead: allow ONLY the exact own KV key (specific allow), and do NOT add
+  // a deny wildcard. Other KV subjects are simply not in the allow list →
+  // denied by default (no-allow = deny in NATS).
+
+  return {
+    pub: {
+      allow: [
+        `runtime.runner.heartbeat.${runnerId}`, // its own heartbeat
+        "runtime.runner.evt.>",                 // runner events (any chatId)
+        ownKv,                                  // write its own registry key only
+        "_INBOX.>",
+        // STAGE D TODO: narrow to the minimal $JS.API.* subjects needed for
+        // kvm.open(RUNNER_REGISTRY_BUCKET) + kvStore.put(runnerId, ...).
+        // The server pre-creates the KV bucket so the runner never needs
+        // STREAM.CREATE. The remaining subjects (STREAM.INFO, CONSUMER.CREATE)
+        // are bucket-scoped but the library may use unpredictable subject forms.
+        // Confirmed empirically with -DV trace and narrow in Stage D.
+        // This is a PILOT allowance — a runner can publish to any JS API subject,
+        // including ones for other streams. Flag for Stage D security review.
+        "$JS.API.>",
+        // JetStream message acknowledgements (separate tree from $JS.API). The
+        // runner consumes coordination/oauth streams; without this its consumers
+        // can't ack and stall. Matches the existing broad $JS.API.> pilot grant.
+        "$JS.ACK.>",
+      ],
+      deny: [],
+    },
+    sub: {
+      allow: [
+        `runtime.runner.cmd.${runnerId}.>`, // its own command subject only
+        "_INBOX.>",
+        "$JS.API.>",                        // JetStream reads / consumer create
+        `$KV.${RUNNER_REGISTRY_BUCKET}.>`, // KV reads (for its own entry)
+      ],
+      deny: [],
+    },
+  }
+}
+
+// ── Helpers used by tests ─────────────────────────────────────────────────────
+
+/** Return the KV key subject a runner should be able to write. */
+export function runnerKvKeySubject(runnerId: string): string {
+  return runnerOwnKvSubject(runnerId)
+}
+
+/** Return the cmd subject for a given runnerId. */
+export function runnerCmdWildcard(runnerId: string): string {
+  return `runtime.runner.cmd.${runnerId}.>`
+}

package/src/nats/auth-callout/token.test.ts

@@ -0,0 +1,163 @@
+/**
+ * Unit tests for stateless credential tokens (token.ts).
+ *
+ * Covers:
+ *  - Basic mint + verify round-trip.
+ *  - byteOffset bug regression: verify a token minted when the secret is a
+ *    sub-array view (non-zero byteOffset) so WebCrypto uses the exact bytes.
+ *  - exp (expiry): valid token accepted, expired token rejected,
+ *    tampered exp rejected (exp is inside the HMAC'd payload).
+ *  - Tokens without exp are rejected (no-legacy-format regression).
+ *  - Malformed / missing tokens rejected.
+ */
+
+import { describe, test, expect } from "bun:test"
+import { mintCredentialToken, verifyCredentialToken } from "./token"
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function freshSecret(): Uint8Array {
+  const s = new Uint8Array(32)
+  crypto.getRandomValues(s)
+  return s
+}
+
+/**
+ * Return a Uint8Array backed by the same buffer as `parent` but with a
+ * non-zero byteOffset so `.buffer` spans more than just the 32 bytes we care
+ * about. This reproduces the pooled-Buffer scenario (Buffer.from pools memory).
+ */
+function subArrayView(data: Uint8Array): Uint8Array {
+  const padded = new Uint8Array(64)
+  padded.set(data, 16) // byteOffset=16 for the view we return
+  return padded.subarray(16, 48)
+}
+
+// ── Round-trip ────────────────────────────────────────────────────────────────
+
+describe("mintCredentialToken / verifyCredentialToken", () => {
+  test("server-admin token round-trips", async () => {
+    const secret = freshSecret()
+    const token = await mintCredentialToken({ class: "server-admin" }, secret)
+    const identity = await verifyCredentialToken(token, secret)
+    expect(identity).toEqual({ class: "server-admin" })
+  })
+
+  test("ui-client token round-trips", async () => {
+    const secret = freshSecret()
+    const token = await mintCredentialToken({ class: "ui-client" }, secret)
+    const identity = await verifyCredentialToken(token, secret)
+    expect(identity).toEqual({ class: "ui-client" })
+  })
+
+  test("runner token round-trips with runnerId", async () => {
+    const secret = freshSecret()
+    const token = await mintCredentialToken({ class: "runner", runnerId: "r-42" }, secret)
+    const identity = await verifyCredentialToken(token, secret)
+    expect(identity).toEqual({ class: "runner", runnerId: "r-42" })
+  })
+
+  // ── byteOffset regression ───────────────────────────────────────────────────
+
+  test("minting with a sub-array secret (non-zero byteOffset) still verifies", async () => {
+    const rawSecret = freshSecret()
+    // subArrayView has byteOffset=16; rawSecret and subView hold the same 32 bytes.
+    const subView = subArrayView(rawSecret)
+    expect(subView.byteOffset).toBe(16)
+
+    // Mint with the sub-view; verify with the canonical flat copy — must succeed.
+    const token = await mintCredentialToken({ class: "ui-client" }, subView)
+    const flatSecret = rawSecret.slice() // byteOffset=0
+    const identity = await verifyCredentialToken(token, flatSecret)
+    expect(identity).toEqual({ class: "ui-client" })
+  })
+
+  test("verifying with a sub-array secret (non-zero byteOffset) succeeds", async () => {
+    const rawSecret = freshSecret()
+    const subView = subArrayView(rawSecret)
+    expect(subView.byteOffset).toBe(16)
+
+    // Mint with the canonical flat copy; verify with the sub-view.
+    const token = await mintCredentialToken({ class: "server-admin" }, rawSecret.slice())
+    const identity = await verifyCredentialToken(token, subView)
+    expect(identity).toEqual({ class: "server-admin" })
+  })
+
+  // ── exp (expiry) ────────────────────────────────────────────────────────────
+
+  test("token with a future exp is accepted", async () => {
+    const secret = freshSecret()
+    // Default TTL is 30 days; token should be valid right now.
+    const token = await mintCredentialToken({ class: "ui-client" }, secret)
+    expect(await verifyCredentialToken(token, secret)).toEqual({ class: "ui-client" })
+  })
+
+  test("token with an already-expired exp is rejected", async () => {
+    const secret = freshSecret()
+    // Pass ttlSeconds=-1 so exp = iat - 1 (already in the past).
+    const token = await mintCredentialToken({ class: "ui-client" }, secret, -1)
+    expect(await verifyCredentialToken(token, secret)).toBeNull()
+  })
+
+  test("token with tampered exp is rejected (exp is inside HMAC'd payload)", async () => {
+    const secret = freshSecret()
+    // Mint a valid token, then decode and modify exp in the payload.
+    const token = await mintCredentialToken({ class: "ui-client" }, secret)
+    const [payloadB64, sigB64] = token.split(".")
+    const payload = JSON.parse(Buffer.from(payloadB64, "base64url").toString())
+    // Extend the exp far into the future by tampering.
+    payload.exp = Math.floor(Date.now() / 1000) + 999999
+    const tamperedPayloadB64 = Buffer.from(JSON.stringify(payload)).toString("base64url")
+    const tamperedToken = `${tamperedPayloadB64}.${sigB64}`
+    // HMAC no longer matches the new payload → must be rejected.
+    expect(await verifyCredentialToken(tamperedToken, secret)).toBeNull()
+  })
+
+  test("token without exp field is rejected (no legacy format)", async () => {
+    const secret = freshSecret()
+    // Craft a token manually without an exp field.
+    const payloadObj = { c: "ui-client", iat: Math.floor(Date.now() / 1000) }
+    const payloadJson = JSON.stringify(payloadObj)
+    const payloadB64 = Buffer.from(payloadJson).toString("base64url")
+
+    // Sign it legitimately so the HMAC is valid.
+    const key = await crypto.subtle.importKey(
+      "raw",
+      secret.buffer.slice(secret.byteOffset, secret.byteOffset + secret.byteLength),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign"]
+    )
+    const rawSig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(payloadJson))
+    const sigB64 = Buffer.from(new Uint8Array(rawSig)).toString("base64url")
+    const legacyToken = `${payloadB64}.${sigB64}`
+
+    expect(await verifyCredentialToken(legacyToken, secret)).toBeNull()
+  })
+
+  // ── Wrong secret ────────────────────────────────────────────────────────────
+
+  test("wrong secret returns null", async () => {
+    const secret = freshSecret()
+    const other = freshSecret()
+    const token = await mintCredentialToken({ class: "server-admin" }, secret)
+    expect(await verifyCredentialToken(token, other)).toBeNull()
+  })
+
+  // ── Malformed inputs ────────────────────────────────────────────────────────
+
+  test("undefined token returns null", async () => {
+    const secret = freshSecret()
+    expect(await verifyCredentialToken(undefined, secret)).toBeNull()
+  })
+
+  test("token without dot separator returns null", async () => {
+    const secret = freshSecret()
+    expect(await verifyCredentialToken("nodothere", secret)).toBeNull()
+  })
+
+  test("garbage token returns null", async () => {
+    const secret = freshSecret()
+    expect(await verifyCredentialToken("!!!.???", secret)).toBeNull()
+  })
+})

package/src/nats/auth-callout/token.ts

@@ -0,0 +1,157 @@
+/**
+ * Stateless signed credential tokens (Stage B, PR1).
+ *
+ * Bridges the server process (token issuance) and the daemon child process
+ * (credential validation in the callout responder) without any shared
+ * in-memory state. The two processes share only the 32-byte token secret
+ * stored on disk (loaded by ensureCalloutKeys).
+ *
+ * Token format:
+ *   base64url(JSON payload) + "." + base64url(HMAC-SHA256(secret, JSON payload))
+ *
+ * Payload shape:
+ *   { c: ConnectionClass, r?: string, iat: number, exp: number }
+ *   where r is runnerId (only for class "runner") and exp is expiry epoch seconds.
+ *
+ * Pure — no I/O, fully unit-testable.
+ */
+
+import type { ResolvedIdentity } from "./scope-policy"
+
+/** Default TTL: 30 days in seconds (pilot-safe; per-class TTLs are PR2). */
+const DEFAULT_TTL_SECONDS = 30 * 24 * 60 * 60 // 2592000
+
+interface TokenPayload {
+  /** Connection class. */
+  c: "server-admin" | "ui-client" | "runner"
+  /** Runner ID — only present for class "runner". */
+  r?: string
+  /** Issued-at epoch seconds. */
+  iat: number
+  /** Expiry epoch seconds (iat + ttl). Tokens without exp are rejected. */
+  exp: number
+}
+
+function b64urlEncode(bytes: Uint8Array): string {
+  return Buffer.from(bytes).toString("base64url")
+}
+
+function b64urlDecode(s: string): Uint8Array {
+  return new Uint8Array(Buffer.from(s, "base64url"))
+}
+
+/** Return an ArrayBuffer view that covers exactly the bytes of the given Uint8Array.
+ *  Uint8Array.prototype.buffer may be a pooled backing buffer with a non-zero
+ *  byteOffset, which would cause WebCrypto to sign/verify the wrong bytes.
+ *  We copy into a fresh ArrayBuffer so the type is unambiguously ArrayBuffer
+ *  (not SharedArrayBuffer) and WebCrypto never sees stray pooled bytes. */
+function exactBuffer(view: Uint8Array): ArrayBuffer {
+  return view.buffer.slice(view.byteOffset, view.byteOffset + view.byteLength) as ArrayBuffer
+}
+
+async function hmacSign(secret: Uint8Array, data: string): Promise<Uint8Array> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    exactBuffer(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  )
+  const sig = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(data))
+  return new Uint8Array(sig)
+}
+
+async function hmacVerify(secret: Uint8Array, data: string, sig: Uint8Array): Promise<boolean> {
+  const key = await crypto.subtle.importKey(
+    "raw",
+    exactBuffer(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["verify"]
+  )
+  return crypto.subtle.verify("HMAC", key, exactBuffer(sig), new TextEncoder().encode(data))
+}
+
+/**
+ * Mint a credential token for the given identity.
+ * The token is self-contained and verifiable with only the shared secret.
+ *
+ * @param ttlSeconds — lifetime in seconds (default: 30 days). Per-class TTLs
+ *   and token refresh are deferred to PR2; this param exists so tests can use
+ *   short TTLs without touching the default.
+ */
+export async function mintCredentialToken(
+  identity: ResolvedIdentity,
+  secret: Uint8Array,
+  ttlSeconds: number = DEFAULT_TTL_SECONDS
+): Promise<string> {
+  const iat = Math.floor(Date.now() / 1000)
+  const payload: TokenPayload = {
+    c: identity.class,
+    iat,
+    exp: iat + ttlSeconds,
+    ...(identity.class === "runner" ? { r: identity.runnerId } : {}),
+  }
+  const payloadJson = JSON.stringify(payload)
+  const payloadB64 = b64urlEncode(new TextEncoder().encode(payloadJson))
+  const sig = await hmacSign(secret, payloadJson)
+  return `${payloadB64}.${b64urlEncode(sig)}`
+}
+
+/**
+ * Verify a credential token and return the resolved identity.
+ * Returns null if the token is missing, malformed, has an invalid signature,
+ * or has expired. Tokens without an `exp` field are also rejected.
+ */
+export async function verifyCredentialToken(
+  token: string | undefined,
+  secret: Uint8Array
+): Promise<ResolvedIdentity | null> {
+  if (!token) return null
+
+  const dotIdx = token.indexOf(".")
+  if (dotIdx === -1) return null
+
+  const payloadB64 = token.slice(0, dotIdx)
+  const sigB64 = token.slice(dotIdx + 1)
+
+  let payloadJson: string
+  try {
+    payloadJson = new TextDecoder().decode(b64urlDecode(payloadB64))
+  } catch {
+    return null
+  }
+
+  let sig: Uint8Array
+  try {
+    sig = b64urlDecode(sigB64)
+  } catch {
+    return null
+  }
+
+  const valid = await hmacVerify(secret, payloadJson, sig)
+  if (!valid) return null
+
+  let payload: TokenPayload
+  try {
+    payload = JSON.parse(payloadJson) as TokenPayload
+  } catch {
+    return null
+  }
+
+  // Reject tokens without exp (no persisted tokens exist; defensive against old format).
+  if (typeof payload.exp !== "number") return null
+
+  // Reject expired tokens.
+  const now = Math.floor(Date.now() / 1000)
+  if (now > payload.exp) return null
+
+  if (payload.c === "runner") {
+    if (!payload.r) return null
+    return { class: "runner", runnerId: payload.r }
+  }
+  if (payload.c === "server-admin") return { class: "server-admin" }
+  if (payload.c === "ui-client") return { class: "ui-client" }
+
+  return null
+}