airaknit 1.1.2-rc.9

package/src/server/pairing-endpoints.test.ts

@@ -0,0 +1,171 @@
+/**
+ * Integration tests for the pairing endpoints (PR2 Stage 1).
+ *
+ * Starts a real embedded NATS server on a dedicated port and exercises
+ * POST /api/pairing/code and POST /api/pairing/exchange over HTTP.
+ *
+ * Covers:
+ *  - code → exchange round-trip; returned token verifies via verifyCredentialToken.
+ *  - second exchange of same code → 410 (consumed).
+ *  - unknown code → 400.
+ *  - token mode (no callout tokenSecret) → 409 on code issue.
+ */
+
+import { afterEach, describe, test, expect } from "bun:test"
+import { startServer } from "./server"
+import { verifyCredentialToken } from "../nats/auth-callout/token"
+import { ensureCalloutKeys } from "../nats/auth-callout/keys"
+import path from "node:path"
+import os from "node:os"
+import fs from "node:fs"
+
+type StartedServer = Awaited<ReturnType<typeof startServer>>
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+async function post(port: number, pathname: string, body?: unknown): Promise<Response> {
+  return fetch(`http://127.0.0.1:${port}${pathname}`, {
+    method: "POST",
+    headers: body !== undefined ? { "Content-Type": "application/json" } : {},
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  })
+}
+
+// ── Callout-mode suite ────────────────────────────────────────────────────────
+
+describe("pairing endpoints (callout mode)", () => {
+  let started: StartedServer | null = null
+  let natsDataDir: string
+
+  afterEach(async () => {
+    await started?.stop()
+    started = null
+  })
+
+  test("code → exchange round-trip; token verifies as runner credential", async () => {
+    natsDataDir = fs.mkdtempSync(path.join(os.tmpdir(), "pr2-pair-test-"))
+    process.env.NATS_AUTH_MODE = "callout"
+    process.env.NATS_DATA_DIR = natsDataDir
+    started = await startServer({ port: 4381, host: "127.0.0.1", strictPort: true })
+    const port = started.port
+
+    // Issue a pairing code.
+    const issueRes = await post(port, "/api/pairing/code")
+    expect(issueRes.status).toBe(200)
+    const issued = await issueRes.json() as { code: string; expiresAt: number }
+    expect(typeof issued.code).toBe("string")
+    expect(issued.code).toMatch(/^[a-z2-7]{5}-[a-z2-7]{5}-[a-z2-7]{6}$/)
+    expect(typeof issued.expiresAt).toBe("number")
+    expect(issued.expiresAt).toBeGreaterThan(Date.now())
+
+    // Exchange the code.
+    const exchangeRes = await post(port, "/api/pairing/exchange", { code: issued.code })
+    expect(exchangeRes.status).toBe(200)
+    const exchanged = await exchangeRes.json() as {
+      runnerId: string; token: string; natsUrl: string; natsWsUrl: string
+    }
+    expect(typeof exchanged.runnerId).toBe("string")
+    expect(exchanged.runnerId).toMatch(/^runner-/)
+    expect(typeof exchanged.token).toBe("string")
+    expect(typeof exchanged.natsUrl).toBe("string")
+    expect(typeof exchanged.natsWsUrl).toBe("string")
+
+    // Verify the returned token decodes to the correct runner identity.
+    const keys = await ensureCalloutKeys(natsDataDir)
+    const identity = await verifyCredentialToken(exchanged.token, keys.tokenSecret)
+    expect(identity).toEqual({ class: "runner", runnerId: exchanged.runnerId })
+  }, 30_000)
+
+  test("second exchange of same code returns 410 (consumed)", async () => {
+    natsDataDir = fs.mkdtempSync(path.join(os.tmpdir(), "pr2-pair-test-"))
+    process.env.NATS_AUTH_MODE = "callout"
+    process.env.NATS_DATA_DIR = natsDataDir
+    started = await startServer({ port: 4382, host: "127.0.0.1", strictPort: true })
+    const port = started.port
+
+    const { code } = await post(port, "/api/pairing/code").then((r) => r.json()) as { code: string }
+    // First exchange — succeeds.
+    const first = await post(port, "/api/pairing/exchange", { code })
+    expect(first.status).toBe(200)
+    // Second exchange — consumed.
+    const second = await post(port, "/api/pairing/exchange", { code })
+    expect(second.status).toBe(410)
+    const body = await second.json() as { error: string }
+    expect(body.error).toBe("consumed")
+  }, 30_000)
+
+  test("unknown code returns 400", async () => {
+    natsDataDir = fs.mkdtempSync(path.join(os.tmpdir(), "pr2-pair-test-"))
+    process.env.NATS_AUTH_MODE = "callout"
+    process.env.NATS_DATA_DIR = natsDataDir
+    started = await startServer({ port: 4383, host: "127.0.0.1", strictPort: true })
+    const port = started.port
+
+    const res = await post(port, "/api/pairing/exchange", { code: "aaaaa-bbbbb-cccccc" })
+    expect(res.status).toBe(400)
+    const body = await res.json() as { error: string }
+    expect(body.error).toBe("unknown")
+  }, 30_000)
+
+  test("bound to 0.0.0.0 without NATS_ADVERTISED_HOST → exchange rejects with 409", async () => {
+    natsDataDir = fs.mkdtempSync(path.join(os.tmpdir(), "pr2-pair-test-"))
+    process.env.NATS_AUTH_MODE = "callout"
+    process.env.NATS_DATA_DIR = natsDataDir
+    delete process.env.NATS_ADVERTISED_HOST
+    // Bind to 0.0.0.0 — the daemon URL becomes nats://0.0.0.0:<port>, which a
+    // remote runner cannot reach. The exchange must refuse, not hand it out.
+    started = await startServer({ port: 4385, host: "0.0.0.0", strictPort: true })
+    const port = started.port
+
+    const { code } = await post(port, "/api/pairing/code").then((r) => r.json()) as { code: string }
+    const res = await post(port, "/api/pairing/exchange", { code })
+    expect(res.status).toBe(409)
+    const body = await res.json() as { error: string }
+    expect(body.error).toContain("NATS_ADVERTISED_HOST")
+  }, 30_000)
+
+  test("bound to 0.0.0.0 with NATS_ADVERTISED_HOST → natsUrl carries the advertised host", async () => {
+    natsDataDir = fs.mkdtempSync(path.join(os.tmpdir(), "pr2-pair-test-"))
+    process.env.NATS_AUTH_MODE = "callout"
+    process.env.NATS_DATA_DIR = natsDataDir
+    process.env.NATS_ADVERTISED_HOST = "100.64.0.2"
+    try {
+      started = await startServer({ port: 4386, host: "0.0.0.0", strictPort: true })
+      const port = started.port
+
+      const { code } = await post(port, "/api/pairing/code").then((r) => r.json()) as { code: string }
+      const res = await post(port, "/api/pairing/exchange", { code })
+      expect(res.status).toBe(200)
+      const body = await res.json() as { natsUrl: string; natsWsUrl: string }
+      expect(new URL(body.natsUrl).hostname).toBe("100.64.0.2")
+      expect(new URL(body.natsWsUrl).hostname).toBe("100.64.0.2")
+    } finally {
+      delete process.env.NATS_ADVERTISED_HOST
+    }
+  }, 30_000)
+})
+
+// ── Token-mode suite ──────────────────────────────────────────────────────────
+
+describe("pairing endpoints (token mode)", () => {
+  let started: StartedServer | null = null
+
+  afterEach(async () => {
+    await started?.stop()
+    started = null
+    delete process.env.NATS_AUTH_MODE
+    delete process.env.NATS_DATA_DIR
+  })
+
+  test("POST /api/pairing/code returns 409 in token mode", async () => {
+    process.env.NATS_AUTH_MODE = "token"
+    delete process.env.NATS_DATA_DIR
+    started = await startServer({ port: 4384, host: "127.0.0.1", strictPort: true })
+    const port = started.port
+
+    const res = await post(port, "/api/pairing/code")
+    expect(res.status).toBe(409)
+    const body = await res.json() as { error: string }
+    expect(body.error).toContain("callout")
+  }, 30_000)
+})

package/src/server/pairing-store.test.ts

@@ -0,0 +1,154 @@
+/**
+ * Unit tests for PairingStore (PR2 Stage 1).
+ *
+ * Uses injectable clock and RNG so tests are deterministic and fast.
+ */
+
+import { describe, test, expect } from "bun:test"
+import { PairingStore } from "./pairing-store"
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+
+function makeEntry() {
+  return { runnerId: "runner-test-1", token: "tok.sig" }
+}
+
+/** A store with a controllable clock (ms) and a fixed-byte RNG. */
+function makeStore(startMs = 1_000_000, rngByte = 0xab) {
+  let now = startMs
+  const tick = (ms: number) => { now += ms }
+  const store = new PairingStore({
+    now: () => now,
+    randomBytes: (n) => new Uint8Array(n).fill(rngByte),
+    ttlMs: 60_000, // 1 min for tests
+  })
+  return { store, tick }
+}
+
+/** A store with a controllable clock and a counter-based RNG (unique codes per issue). */
+function makeCounterStore(startMs = 1_000_000) {
+  let now = startMs
+  let counter = 0
+  const tick = (ms: number) => { now += ms }
+  const store = new PairingStore({
+    now: () => now,
+    randomBytes: (n) => {
+      const buf = new Uint8Array(n)
+      // Fill with an incrementing byte so each call produces a distinct value.
+      buf.fill(counter++ & 0xff)
+      return buf
+    },
+    ttlMs: 60_000,
+  })
+  return { store, tick }
+}
+
+// ── Code shape ────────────────────────────────────────────────────────────────
+
+describe("PairingStore.issue", () => {
+  test("returns a code and expiresAt", () => {
+    const startMs = 1_000_000
+    const { store } = makeStore(startMs)
+    const { code, expiresAt } = store.issue(makeEntry())
+    expect(typeof code).toBe("string")
+    expect(code.length).toBeGreaterThan(0)
+    // expiresAt should be in the future relative to our injected clock start
+    expect(expiresAt).toBeGreaterThan(startMs)
+  })
+
+  test("code has dashed base32 shape (xxxxx-xxxxx-xxxxxx)", () => {
+    const { store } = makeStore()
+    const { code } = store.issue(makeEntry())
+    // 5-5-6 groups separated by dashes (16 base32 chars), lowercase a-z and 2-7
+    expect(code).toMatch(/^[a-z2-7]{5}-[a-z2-7]{5}-[a-z2-7]{6}$/)
+  })
+
+  test("codes from different RNG bytes are unique", () => {
+    // Two stores with different RNG seeds produce different codes.
+    const { store: s1 } = makeStore(1_000_000, 0x11)
+    const { store: s2 } = makeStore(1_000_000, 0x22)
+    const { code: c1 } = s1.issue(makeEntry())
+    const { code: c2 } = s2.issue(makeEntry())
+    expect(c1).not.toBe(c2)
+  })
+
+  test("expiresAt equals now + ttlMs", () => {
+    const startMs = 5_000_000
+    const { store } = makeStore(startMs)
+    const { expiresAt } = store.issue(makeEntry())
+    expect(expiresAt).toBe(startMs + 60_000)
+  })
+})
+
+// ── Exchange — happy path ─────────────────────────────────────────────────────
+
+describe("PairingStore.exchange", () => {
+  test("exchange returns runnerId and token on first use", () => {
+    const { store } = makeStore()
+    const entry = makeEntry()
+    const { code } = store.issue(entry)
+    const result = store.exchange(code)
+    expect(result).toEqual({ ok: true, runnerId: entry.runnerId, token: entry.token })
+  })
+
+  test("second exchange of same code returns consumed", () => {
+    const { store } = makeStore()
+    const { code } = store.issue(makeEntry())
+    store.exchange(code) // first — succeeds
+    const result = store.exchange(code) // second
+    expect(result).toEqual({ ok: false, error: "consumed" })
+  })
+
+  // ── Expiry ────────────────────────────────────────────────────────────────
+
+  test("expired code (clock advanced past expiresAt) returns expired", () => {
+    const { store, tick } = makeStore()
+    const { code } = store.issue(makeEntry())
+    tick(60_001) // just past the 1-min TTL
+    const result = store.exchange(code)
+    expect(result).toEqual({ ok: false, error: "expired" })
+  })
+
+  test("code exactly at expiresAt boundary is expired (>= check)", () => {
+    const { store, tick } = makeStore()
+    const { code, expiresAt } = store.issue(makeEntry())
+    // Advance so now === expiresAt exactly.
+    tick(expiresAt - 1_000_000) // start was 1_000_000
+    const result = store.exchange(code)
+    expect(result).toEqual({ ok: false, error: "expired" })
+  })
+
+  test("unknown code returns unknown", () => {
+    const { store } = makeStore()
+    const result = store.exchange("xxxxx-yyyyy-zzzz")
+    expect(result).toEqual({ ok: false, error: "unknown" })
+  })
+
+  // ── Sweep ─────────────────────────────────────────────────────────────────
+
+  test("expired entries are swept from internal map on next issue", () => {
+    // After an issue() triggers a sweep, previously-expired entries are deleted.
+    // A subsequent exchange() of the old code returns "unknown" (entry gone).
+    const { store, tick } = makeCounterStore()
+    const { code } = store.issue(makeEntry())
+    tick(60_001) // expire it
+    // Second issue produces a different code (counter RNG) and triggers sweep.
+    store.issue({ runnerId: "runner-2", token: "tok2.sig" })
+    // First entry was swept — exchange now reports "unknown".
+    const result = store.exchange(code)
+    expect(result).toEqual({ ok: false, error: "unknown" })
+  })
+
+  test("consumed entries are also evicted after TTL (no permanent consumed-oracle / memory leak)", () => {
+    // Within the TTL window a reused code reports "consumed"...
+    const { store, tick } = makeCounterStore()
+    const { code } = store.issue(makeEntry())
+    expect(store.exchange(code).ok).toBe(true) // consume it
+    expect(store.exchange(code)).toEqual({ ok: false, error: "consumed" }) // still in window
+    // ...but once past the TTL it is swept on the next activity and reads as
+    // "unknown" like any dead code — not "consumed" forever (MEDIUM-1 fix).
+    tick(60_001)
+    store.issue({ runnerId: "runner-2", token: "tok2.sig" }) // triggers sweep
+    expect(store.exchange(code)).toEqual({ ok: false, error: "unknown" })
+  })
+})

package/src/server/pairing-store.ts

@@ -0,0 +1,124 @@
+/**
+ * In-memory single-use pairing code store (PR2 Stage 1).
+ *
+ * Issues short-lived, unguessable codes that each map once to a pre-minted
+ * runner credential. Codes are consumed atomically on first exchange; expired
+ * or unknown codes are rejected. Lost on server restart (the 10-min TTL window
+ * means the member can simply re-issue — EventStore persistence is deferred).
+ *
+ * Pure / injectable clock + RNG for unit tests.
+ */
+
+/** Default pairing code TTL: 10 minutes. */
+export const DEFAULT_CODE_TTL_MS = 10 * 60 * 1000
+
+/** Base32 alphabet (RFC 4648, lowercase, human-legible, no padding). */
+const BASE32_CHARS = "abcdefghijklmnopqrstuvwxyz234567"
+
+/** Number of random bytes per code — gives ~80 bits of entropy. */
+const CODE_RANDOM_BYTES = 10
+
+/** Format: xxxxx-xxxxx-xxxxxx (5-5-6, 16 base32 chars total, dashed for readability). */
+function formatCode(raw: string): string {
+  // 10 random bytes → 16 base32 chars; split 5-5-6 for human readability.
+  return `${raw.slice(0, 5)}-${raw.slice(5, 10)}-${raw.slice(10)}`
+}
+
+function encodeBase32(bytes: Uint8Array): string {
+  let bits = 0
+  let value = 0
+  let output = ""
+  for (const byte of bytes) {
+    value = (value << 8) | byte
+    bits += 8
+    while (bits >= 5) {
+      bits -= 5
+      output += BASE32_CHARS[(value >>> bits) & 0x1f]
+    }
+  }
+  return output
+}
+
+interface PairingEntry {
+  runnerId: string
+  /** Pre-minted durable runner credential token. Never logged in full. */
+  token: string
+  expiresAt: number
+  consumed: boolean
+}
+
+export type ExchangeResult =
+  | { ok: true; runnerId: string; token: string }
+  | { ok: false; error: "expired" | "consumed" | "unknown" }
+
+export interface PairingStoreOptions {
+  /** Injected for tests; defaults to Date.now. */
+  now?: () => number
+  /** Injected for tests; defaults to crypto.getRandomValues. */
+  randomBytes?: (n: number) => Uint8Array
+  /** Code TTL in ms; defaults to DEFAULT_CODE_TTL_MS (10 min). */
+  ttlMs?: number
+}
+
+export class PairingStore {
+  private readonly codes = new Map<string, PairingEntry>()
+  private readonly now: () => number
+  private readonly randomBytes: (n: number) => Uint8Array
+  private readonly ttlMs: number
+
+  constructor(options: PairingStoreOptions = {}) {
+    this.now = options.now ?? (() => Date.now())
+    this.randomBytes = options.randomBytes ?? ((n) => {
+      const buf = new Uint8Array(n)
+      crypto.getRandomValues(buf)
+      return buf
+    })
+    this.ttlMs = options.ttlMs ?? DEFAULT_CODE_TTL_MS
+  }
+
+  /**
+   * Issue a new pairing code for the given runner credential.
+   * Returns the code and the timestamp (ms) when it expires.
+   */
+  issue(params: { runnerId: string; token: string }): { code: string; expiresAt: number } {
+    this.sweep()
+    const raw = encodeBase32(this.randomBytes(CODE_RANDOM_BYTES))
+    const code = formatCode(raw)
+    const expiresAt = this.now() + this.ttlMs
+    this.codes.set(code, { runnerId: params.runnerId, token: params.token, expiresAt, consumed: false })
+    return { code, expiresAt }
+  }
+
+  /**
+   * Exchange a code for its runner credential, atomically consuming it.
+   * A second call with the same code returns { error: "consumed" }.
+   * An expired code returns { error: "expired" }.
+   * An unknown code returns { error: "unknown" }.
+   */
+  exchange(code: string): ExchangeResult {
+    // Look up the entry BEFORE sweeping so we can distinguish "expired"
+    // (we know the code, it just timed out) from "unknown" (never issued).
+    const entry = this.codes.get(code)
+    this.sweep()
+    if (!entry) return { ok: false, error: "unknown" }
+    if (entry.consumed) return { ok: false, error: "consumed" }
+    if (this.now() >= entry.expiresAt) return { ok: false, error: "expired" }
+    // Atomically mark consumed before returning.
+    entry.consumed = true
+    return { ok: true, runnerId: entry.runnerId, token: entry.token }
+  }
+
+  /**
+   * Remove expired entries (consumed OR not) to bound memory growth.
+   * Sweeping consumed-and-expired entries also avoids a permanent
+   * "consumed vs. unknown" distinction for long-dead codes — within the TTL
+   * window a reused code still reports "consumed" (the entry has not expired);
+   * after the window it is evicted and reads as "unknown" like any other.
+   */
+  private sweep(): void {
+    const now = this.now()
+    for (const [code, entry] of this.codes) {
+      if (now >= entry.expiresAt) this.codes.delete(code)
+    }
+  }
+}

package/src/server/paths.ts

@@ -0,0 +1,27 @@
+import { mkdir, stat } from "node:fs/promises"
+import { homedir } from "node:os"
+import path from "node:path"
+
+export function resolveLocalPath(localPath: string) {
+  const trimmed = localPath.trim()
+  if (!trimmed) {
+    throw new Error("Project path is required")
+  }
+  if (trimmed === "~") {
+    return homedir()
+  }
+  if (trimmed.startsWith("~/")) {
+    return path.join(homedir(), trimmed.slice(2))
+  }
+  return path.resolve(trimmed)
+}
+
+export async function ensureProjectDirectory(localPath: string) {
+  const resolvedPath = resolveLocalPath(localPath)
+
+  await mkdir(resolvedPath, { recursive: true })
+  const info = await stat(resolvedPath)
+  if (!info.isDirectory()) {
+    throw new Error("Project path must be a directory")
+  }
+}