airaknit 1.1.2-rc.9

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

@@ -0,0 +1,103 @@
+/**
+ * Callout signing-key management (Stage A, PR1).
+ *
+ * The auth-callout requires two nkey pairs:
+ *   - An **account key pair** — the callout issuer account (public key goes into
+ *     the nats-server config; the seed is held by the responder to sign user JWTs).
+ *   - An **auth-service key pair** — the user listed in `auth_users` whose
+ *     connection bypasses the callout (required by NATS auth-callout spec).
+ *
+ * Both seeds are stored alongside `nats.token` in NATS_DATA_DIR (same on-disk
+ * trust boundary; gitignored). The server reads them at startup; key rotation
+ * is a documented follow-up.
+ */
+
+import { join } from "node:path"
+import { mkdirSync, renameSync, chmodSync } from "node:fs"
+import { createAccount, createUser, fromSeed } from "@nats-io/nkeys"
+import type { KeyPair } from "@nats-io/nkeys"
+
+const ACCOUNT_SEED_FILE = "nats.callout-account.seed"
+const AUTH_USER_SEED_FILE = "nats.callout-auth-user.seed"
+const TOKEN_SECRET_FILE = "nats.callout-token.secret"
+
+/** Loaded callout key material. */
+export interface CalloutKeys {
+  /** KeyPair for the callout issuer account (signs user JWTs). */
+  accountKp: KeyPair
+  /** Public key of the account (goes into nats-server config). */
+  accountPublicKey: string
+  /** KeyPair for the auth-service user (bypasses callout). */
+  authUserKp: KeyPair
+  /** Public key of the auth-service user (goes into nats-server config). */
+  authUserPublicKey: string
+  /**
+   * 32-byte shared secret used to mint and verify stateless credential tokens
+   * (Stage B). Both the server process and the daemon child load this from disk.
+   */
+  tokenSecret: Uint8Array
+}
+
+async function readOrCreateSeed(
+  seedPath: string,
+  generator: () => KeyPair
+): Promise<string> {
+  const file = Bun.file(seedPath)
+  if (await file.exists()) {
+    const seed = (await file.text()).trim()
+    if (seed.length > 0) return seed
+  }
+
+  const kp = generator()
+  const seed = Buffer.from(kp.getSeed()).toString()
+  const tmp = `${seedPath}.tmp.${process.pid}`
+  await Bun.write(tmp, seed + "\n")
+  renameSync(tmp, seedPath) // atomic
+  chmodSync(seedPath, 0o600) // owner-read/write only
+  return seed
+}
+
+async function readOrCreateTokenSecret(secretPath: string): Promise<Uint8Array> {
+  const file = Bun.file(secretPath)
+  if (await file.exists()) {
+    const hex = (await file.text()).trim()
+    if (hex.length === 64) return new Uint8Array(Buffer.from(hex, "hex"))
+  }
+
+  const secret = new Uint8Array(32)
+  crypto.getRandomValues(secret)
+  const hex = Buffer.from(secret).toString("hex")
+  const tmp = `${secretPath}.tmp.${process.pid}`
+  await Bun.write(tmp, hex + "\n")
+  renameSync(tmp, secretPath) // atomic
+  chmodSync(secretPath, 0o600) // owner-read/write only
+  return secret
+}
+
+/**
+ * Ensure callout key material exists in `dataDir`.
+ * Generates both pairs and the token secret on first call; subsequent calls load from disk.
+ * Safe for single-writer use (the NATS daemon); not safe for concurrent writers.
+ */
+export async function ensureCalloutKeys(dataDir: string): Promise<CalloutKeys> {
+  mkdirSync(dataDir, { recursive: true })
+
+  const accountSeedPath = join(dataDir, ACCOUNT_SEED_FILE)
+  const authUserSeedPath = join(dataDir, AUTH_USER_SEED_FILE)
+  const tokenSecretPath = join(dataDir, TOKEN_SECRET_FILE)
+
+  const accountSeed = await readOrCreateSeed(accountSeedPath, createAccount)
+  const authUserSeed = await readOrCreateSeed(authUserSeedPath, createUser)
+  const tokenSecret = await readOrCreateTokenSecret(tokenSecretPath)
+
+  const accountKp = fromSeed(Buffer.from(accountSeed.trim()))
+  const authUserKp = fromSeed(Buffer.from(authUserSeed.trim()))
+
+  return {
+    accountKp,
+    accountPublicKey: accountKp.getPublicKey(),
+    authUserKp,
+    authUserPublicKey: authUserKp.getPublicKey(),
+    tokenSecret,
+  }
+}

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

@@ -0,0 +1,241 @@
+/**
+ * Auth-callout responder (Stage B, PR1).
+ *
+ * Subscribes to $SYS.REQ.USER.AUTH. For each request:
+ *  1. Decode the AuthorizationRequest JWT from NATS.
+ *  2. Validate the credential in connect_opts.auth_token via verifyCredentialToken.
+ *  3. Resolve the connection class (and runnerId for runner class).
+ *  4. Mint a scoped user JWT and respond with a signed AuthorizationResponse.
+ *  5. Audit every decision (grant/deny).
+ *
+ * The responding connection itself uses the auth-service nkey (authUserKp) and
+ * bypasses the callout, per the NATS auth_callout spec.
+ *
+ * Stage B: replaced in-memory credential registry with stateless HMAC-signed
+ * tokens (verifyCredentialToken). No registration step; both the server process
+ * (issuer) and this daemon child (verifier) share only the on-disk token secret.
+ */
+
+import { connect, type NatsConnection, type Subscription } from "@nats-io/transport-node"
+import { nkeyAuthenticator } from "@nats-io/nats-core"
+import {
+  encodeUser,
+  encodeAuthorizationResponse,
+  decode,
+  Algorithms,
+  fromPublic,
+  createUser,
+} from "@nats-io/jwt"
+import type { AuthorizationRequest } from "@nats-io/jwt"
+import type { KeyPair } from "@nats-io/nkeys"
+import { permissionsFor } from "./scope-policy"
+import type { ResolvedIdentity } from "./scope-policy"
+import { verifyCredentialToken } from "./token"
+
+const CALLOUT_SUBJECT = "$SYS.REQ.USER.AUTH"
+
+// ── Responder ─────────────────────────────────────────────────────────────────
+
+export interface ResponderOptions {
+  /** NATS URL to connect to (TCP). */
+  natsUrl: string
+  /** KeyPair for the auth-service user (bypasses callout). */
+  authUserKp: KeyPair
+  /** KeyPair for the callout issuer account (signs user JWTs). */
+  accountKp: KeyPair
+  /** Public key of the callout account (needed for encodeUser issuer_account). */
+  accountPublicKey: string
+  /**
+   * Account name as declared in the nats-server config accounts block.
+   * This becomes the `aud` (audience) of the issued user JWT so NATS knows
+   * which account to place the connection in.
+   */
+  accountName?: string
+  /**
+   * 32-byte shared secret loaded from NATS_DATA_DIR by the daemon child.
+   * Used to verify stateless credential tokens without any in-memory registry.
+   */
+  tokenSecret: Uint8Array
+}
+
+export class CalloutResponder {
+  private nc: NatsConnection | null = null
+  private sub: Subscription | null = null
+  private readonly opts: ResponderOptions
+
+  constructor(opts: ResponderOptions) {
+    this.opts = opts
+  }
+
+  /**
+   * Connect to NATS as the auth-service user (bypasses callout) and
+   * start the subscription loop.
+   */
+  async start(): Promise<void> {
+    const { authUserKp, natsUrl } = this.opts
+
+    // Connect using the auth-service nkey (bypasses the callout per NATS spec).
+    // nkeyAuthenticator takes the seed bytes; the server verifies the public key
+    // against auth_users in the config.
+    this.nc = await connect({
+      servers: natsUrl,
+      authenticator: nkeyAuthenticator(authUserKp.getSeed()),
+    })
+
+    this.sub = this.nc.subscribe(CALLOUT_SUBJECT)
+    void this.listenLoop().catch((err) => {
+      console.error("[nats-callout] listenLoop fatal:", err)
+    })
+  }
+
+  /** Stop the responder and drain the NATS connection. */
+  async stop(): Promise<void> {
+    this.sub?.unsubscribe()
+    if (this.nc) {
+      try { await this.nc.drain() } catch { /* ignore drain errors on shutdown */ }
+      this.nc = null
+    }
+  }
+
+  private async listenLoop(): Promise<void> {
+    if (!this.sub) return
+    for await (const msg of this.sub) {
+      await this.handleCallout(msg)
+    }
+  }
+
+  private async handleCallout(msg: { data: Uint8Array; respond: (data: Uint8Array) => void }): Promise<void> {
+    const { accountKp, accountPublicKey, accountName = "CALLOUT_ACCOUNT" } = this.opts
+
+    // The callout request body is a JWT (not plain JSON).
+    // Decode it to get the AuthorizationRequest payload from the `nats` claim.
+    let req: AuthorizationRequest
+    try {
+      const jwt = new TextDecoder().decode(msg.data)
+      const claims = decode<AuthorizationRequest>(jwt)
+      req = claims.nats as unknown as AuthorizationRequest
+    } catch (err) {
+      this.audit("deny", "unparseable-request", null, `decode error: ${err}`)
+      await this.respondError(msg, accountKp, null, "invalid authorization request")
+      return
+    }
+
+    const userNkey = req.user_nkey
+    const serverNkey = req.server_id.id
+    const presentedToken = req.connect_opts?.auth_token
+
+    // Verify the stateless signed credential token.
+    const identity = await verifyCredentialToken(presentedToken, this.opts.tokenSecret)
+    if (!identity) {
+      this.audit("deny", userNkey, null, "unknown or invalid credential")
+      await this.respondError(msg, accountKp, serverNkey, "unknown credential")
+      return
+    }
+    const scope = permissionsFor(identity)
+
+    // Mint a fresh user keypair for this connection (the JWT subject).
+    // The user nkey from the request is the connecting client's key;
+    // we use fromPublic to get a Key that encodeUser can use as ukp.
+    let userKey: ReturnType<typeof fromPublic>
+    try {
+      userKey = fromPublic(userNkey)
+    } catch (err) {
+      this.audit("deny", userNkey, identity, `invalid user nkey: ${err}`)
+      await this.respondError(msg, accountKp, serverNkey, "invalid user nkey")
+      return
+    }
+
+    // Encode the scoped user JWT.
+    // The `aud` field must be the account name from the nats-server config so
+    // NATS knows which account to place this connection in.
+    let userJwt: string
+    try {
+      userJwt = await encodeUser(
+        connectionClassName(identity),
+        userKey,
+        accountKp, // issuer — the account key pair
+        {
+          pub: scope.pub,
+          sub: scope.sub,
+        },
+        { algorithm: Algorithms.v2, aud: accountName }
+      )
+    } catch (err) {
+      this.audit("deny", userNkey, identity, `jwt encode failed: ${err}`)
+      await this.respondError(msg, accountKp, serverNkey, "internal error minting JWT")
+      return
+    }
+
+    // Build and sign the authorization response.
+    try {
+      const serverKp = fromPublic(serverNkey)
+      const responseJwt = await encodeAuthorizationResponse(
+        userKey,
+        serverKp,
+        accountKp,
+        { jwt: userJwt },
+        { algorithm: Algorithms.v2 }
+      )
+
+      this.audit("grant", userNkey, identity, "ok")
+      msg.respond(new TextEncoder().encode(responseJwt))
+    } catch (err) {
+      this.audit("deny", userNkey, identity, `response encode failed: ${err}`)
+      await this.respondError(msg, accountKp, serverNkey, "internal error building response")
+    }
+  }
+
+  private async respondError(
+    msg: { respond: (data: Uint8Array) => void },
+    accountKp: KeyPair,
+    serverNkey: string | null,
+    reason: string
+  ): Promise<void> {
+    try {
+      // For error responses we need a server key; if we don't have one, create
+      // a throwaway keypair (NATS only needs a valid structure for the error path).
+      const serverKp = serverNkey
+        ? fromPublic(serverNkey)
+        : createUser()
+
+      // The user key in an error response is also a throwaway.
+      const throwawayUser = createUser()
+
+      const responseJwt = await encodeAuthorizationResponse(
+        throwawayUser,
+        serverKp,
+        accountKp,
+        { error: reason },
+        { algorithm: Algorithms.v2 }
+      )
+      msg.respond(new TextEncoder().encode(responseJwt))
+    } catch {
+      // Last resort: send empty bytes; NATS will treat as rejection.
+      msg.respond(new Uint8Array(0))
+    }
+  }
+
+  private audit(
+    decision: "grant" | "deny",
+    userNkey: string | null,
+    identity: ResolvedIdentity | null,
+    detail: string
+  ): void {
+    const ts = new Date().toISOString()
+    const cls = identity ? connectionClassName(identity) : "unknown"
+    const rid = identity?.class === "runner" ? identity.runnerId : "-"
+    console.warn(
+      `[nats-callout] ${ts} decision=${decision} class=${cls} runnerId=${rid}`,
+      `nkey=${userNkey?.slice(0, 12) ?? "?"}… detail=${detail}`
+    )
+  }
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function connectionClassName(identity: ResolvedIdentity): string {
+  return identity.class === "runner"
+    ? `runner:${identity.runnerId}`
+    : identity.class
+}
+

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

@@ -0,0 +1,159 @@
+import { describe, test, expect } from "bun:test"
+import { permissionsFor, runnerKvKeySubject, runnerCmdWildcard } from "./scope-policy"
+
+// Helper: check whether a subject is covered by an allow list.
+// NATS uses prefix-match with ">" wildcard and exact ">" suffix.
+function matchesAny(subject: string, patterns: string[]): boolean {
+  for (const pattern of patterns) {
+    if (matchesNats(subject, pattern)) return true
+  }
+  return false
+}
+
+function matchesNats(subject: string, pattern: string): boolean {
+  if (pattern === subject) return true
+  if (pattern.endsWith(".>")) {
+    const prefix = pattern.slice(0, -1) // "foo.>"  -> "foo."
+    if (subject.startsWith(prefix)) return true
+  }
+  return false
+}
+
+// ── server-admin ──────────────────────────────────────────────────────────────
+
+describe("server-admin scope", () => {
+  const scope = permissionsFor({ class: "server-admin" })
+
+  test("may publish to runtime.>", () => {
+    expect(matchesAny("runtime.runner.cmd.A.start", scope.pub.allow)).toBe(true)
+  })
+
+  test("may publish JetStream ACKs (regression: $JS.ACK is a separate tree from $JS.API)", () => {
+    expect(matchesAny("$JS.ACK.KANNA_RUNNER_EVENTS.consumer.1.1.1.1.0", scope.pub.allow)).toBe(true)
+  })
+
+  test("may publish to JetStream API", () => {
+    expect(matchesAny("$JS.API.STREAM.INFO", scope.pub.allow)).toBe(true)
+  })
+
+  test("may publish to KV", () => {
+    expect(matchesAny("$KV.runtime_runner_registry.someRunner", scope.pub.allow)).toBe(true)
+  })
+
+  test("may subscribe to callout subject", () => {
+    expect(matchesAny("$SYS.REQ.USER.AUTH", scope.sub.allow)).toBe(true)
+  })
+
+  test("no deny rules", () => {
+    expect(scope.pub.deny).toHaveLength(0)
+    expect(scope.sub.deny).toHaveLength(0)
+  })
+})
+
+// ── ui-client ─────────────────────────────────────────────────────────────────
+
+describe("ui-client scope", () => {
+  const scope = permissionsFor({ class: "ui-client" })
+
+  test("may publish to runtime.cmd.>", () => {
+    expect(matchesAny("runtime.cmd.someCommand", scope.pub.allow)).toBe(true)
+  })
+
+  test("may subscribe to runner events", () => {
+    expect(matchesAny("runtime.runner.evt.chat123", scope.sub.allow)).toBe(true)
+  })
+
+  test("may pull chat messages via JS CONSUMER.MSG.NEXT (regression: was denied)", () => {
+    // The browser uses a pull consumer; without this it got Publish Violations
+    // and could not read chat messages. See intake #21.
+    expect(
+      matchesAny("$JS.API.CONSUMER.MSG.NEXT.KANNA_CHAT_MESSAGE_EVENTS.someConsumer_1", scope.pub.allow),
+    ).toBe(true)
+  })
+
+  test("pull fetch is still scoped to the chat stream only (not other streams)", () => {
+    expect(
+      matchesAny("$JS.API.CONSUMER.MSG.NEXT.KANNA_RUNNER_EVENTS.c", scope.pub.allow),
+    ).toBe(false)
+  })
+
+  test("may subscribe to snapshots", () => {
+    expect(matchesAny("runtime.snap.chat.abc", scope.sub.allow)).toBe(true)
+  })
+
+  test("runtime.runner.cmd.> is NOT in pub allow list (excluded by default)", () => {
+    // NATS: not in allow list means denied. No explicit deny needed.
+    expect(matchesAny("runtime.runner.cmd.A.start", scope.pub.allow)).toBe(false)
+  })
+
+  test("may NOT subscribe to runner cmd subjects (not in allow list)", () => {
+    expect(matchesAny("runtime.runner.cmd.A.>", scope.sub.allow)).toBe(false)
+  })
+
+  test("no deny rules (allow-only policy)", () => {
+    expect(scope.pub.deny).toHaveLength(0)
+    expect(scope.sub.deny).toHaveLength(0)
+  })
+})
+
+// ── runner (per-runnerId) ─────────────────────────────────────────────────────
+
+describe("runner scope", () => {
+  const runnerId = "runner-A"
+  const otherRunnerId = "runner-B"
+  const scope = permissionsFor({ class: "runner", runnerId })
+
+  test("may subscribe to its own cmd subject", () => {
+    expect(matchesAny(runnerCmdWildcard(runnerId), scope.sub.allow)).toBe(true)
+    expect(matchesAny(`runtime.runner.cmd.${runnerId}.start`, scope.sub.allow)).toBe(true)
+  })
+
+  test("another runner cmd subject is NOT in sub allow (excluded by default)", () => {
+    // NATS: not in allow list means denied. No explicit deny needed.
+    expect(matchesAny(runnerCmdWildcard(otherRunnerId), scope.sub.allow)).toBe(false)
+    expect(matchesAny(`runtime.runner.cmd.${otherRunnerId}.start`, scope.sub.allow)).toBe(false)
+  })
+
+  test("may publish its own heartbeat", () => {
+    expect(matchesAny(`runtime.runner.heartbeat.${runnerId}`, scope.pub.allow)).toBe(true)
+  })
+
+  test("another runner heartbeat is NOT in pub allow (excluded by default)", () => {
+    expect(matchesAny(`runtime.runner.heartbeat.${otherRunnerId}`, scope.pub.allow)).toBe(false)
+  })
+
+  test("may publish runner events", () => {
+    expect(matchesAny("runtime.runner.evt.chat1", scope.pub.allow)).toBe(true)
+  })
+
+  test("may publish its own KV registry key", () => {
+    const ownKey = runnerKvKeySubject(runnerId)
+    expect(matchesAny(ownKey, scope.pub.allow)).toBe(true)
+  })
+
+  test("another runner KV key is NOT in pub allow (excluded by default)", () => {
+    // NATS: not in allow means denied. We use specific-allow only (no wildcard allow,
+    // no deny list) so other keys are automatically excluded.
+    const foreignKey = runnerKvKeySubject(otherRunnerId)
+    expect(matchesAny(foreignKey, scope.pub.allow)).toBe(false)
+  })
+
+  test("no deny rules (allow-only policy)", () => {
+    expect(scope.pub.deny).toHaveLength(0)
+    expect(scope.sub.deny).toHaveLength(0)
+  })
+})
+
+// ── runnerKvKeySubject helper ─────────────────────────────────────────────────
+
+describe("runnerKvKeySubject", () => {
+  test("returns expected KV subject", () => {
+    expect(runnerKvKeySubject("abc")).toBe("$KV.runtime_runner_registry.abc")
+  })
+})
+
+describe("runnerCmdWildcard", () => {
+  test("returns expected wildcard", () => {
+    expect(runnerCmdWildcard("xyz")).toBe("runtime.runner.cmd.xyz.>")
+  })
+})