@celilo/e2e 0.9.3 → 0.10.0

package/registry-server/src/introspection.ts

@@ -0,0 +1,204 @@
+import { ADMIN_SCOPE, bearerToken } from './auth';
+
+/**
+ * RFC 7662 token-introspection verify-bridge
+ * (SECURE_MODULE_PUBLISH.md §5[D-A], MODULE_PACKAGE_SIGNING.md Phase 1).
+ *
+ * The registry POSTs a presented publish token to the idp's introspection
+ * endpoint, authenticating with its own confidential OIDC client credentials
+ * (provisioned on install — ce-7aa). It reads back `{active, sub, groups, exp}`
+ * and maps a verified identity to a publish scope the request path already
+ * understands (ADMIN_SCOPE / per-package — see {@link claimToScope}).
+ *
+ * Two properties this module MUST preserve:
+ *   1. **Fail closed.** Any non-2xx response, network error, or malformed body
+ *      denies the token (returns null). The idp being unreachable never
+ *      degrades into "allow".
+ *   2. **No secrets in logs.** The token and client secret are never logged;
+ *      only HTTP status / error class is.
+ */
+
+/** Validated subset of an RFC 7662 introspection response. */
+export interface IntrospectionResult {
+  active: boolean;
+  sub?: string;
+  groups?: string[];
+  exp?: number;
+}
+
+export interface IntrospectionConfig {
+  /** RFC 7662 introspection endpoint (OIDC_INTROSPECTION_ENDPOINT). */
+  endpoint: string;
+  /** Confidential OIDC client id (OIDC_CLIENT_ID). */
+  clientId: string;
+  /** Confidential OIDC client secret (OIDC_CLIENT_SECRET). */
+  clientSecret: string;
+  /** Group whose members map to ADMIN_SCOPE (REGISTRY_ADMIN_GROUP). */
+  adminGroup: string;
+  /**
+   * Group whose members may publish modules they own (REGISTRY_PUBLISHER_GROUP,
+   * ce-1ch). Configurable, not a literal. Members claim/publish per the
+   * module-owner table; admins additionally publish/reassign anything.
+   */
+  publisherGroup: string;
+}
+
+/**
+ * A verified idp identity (ce-1ch). `identify()` resolves an Authorization
+ * header to this via introspection, or null when the token is inactive/expired/
+ * unverifiable or carries no `sub` (ownership requires a stable subject).
+ */
+export interface VerifiedIdentity {
+  /**
+   * Verified subject — the owner key in the module-owner table. Optional: an
+   * admin identity may publish without one (admins need no ownership anchor),
+   * but the publisher/owner path requires it to attribute a claim.
+   */
+  sub?: string;
+  /** Member of the admin group → may publish/reassign any module. */
+  isAdmin: boolean;
+  /** Member of the publisher group → may claim + publish owned modules. */
+  isPublisher: boolean;
+  /**
+   * The group that grants this identity's publish rights (admin group when
+   * admin, else publisher group when publisher, else undefined). Recorded as
+   * the owner entry's `sourceGroup` at claim time.
+   */
+  group?: string;
+}
+
+/** Default admin group name when REGISTRY_ADMIN_GROUP is unset. */
+const DEFAULT_ADMIN_GROUP = 'celilo-admins';
+
+/** Default publisher group name when REGISTRY_PUBLISHER_GROUP is unset. */
+const DEFAULT_PUBLISHER_GROUP = 'celilo-authors';
+
+/**
+ * Read introspection config from the environment (delivered by the module's
+ * OIDC drop-in EnvironmentFile — ce-7aa). Returns null when introspection is
+ * not configured, in which case the server keeps the opaque-token-only path.
+ */
+export function introspectionConfigFromEnv(): IntrospectionConfig | null {
+  const endpoint = process.env.OIDC_INTROSPECTION_ENDPOINT?.trim();
+  const clientId = process.env.OIDC_CLIENT_ID?.trim();
+  const clientSecret = process.env.OIDC_CLIENT_SECRET?.trim();
+  if (!endpoint || !clientId || !clientSecret) return null;
+  return {
+    endpoint,
+    clientId,
+    clientSecret,
+    adminGroup: process.env.REGISTRY_ADMIN_GROUP?.trim() || DEFAULT_ADMIN_GROUP,
+    publisherGroup: process.env.REGISTRY_PUBLISHER_GROUP?.trim() || DEFAULT_PUBLISHER_GROUP,
+  };
+}
+
+/**
+ * Map a verified identity's claims to a publish scope the request path
+ * consumes. Today: membership in the admin group → ADMIN_SCOPE (`*`).
+ *
+ * ponytail: per-module ownership (a verified non-admin identity may publish
+ * only modules it owns) is the module-owner table — ce-1ch — which extends
+ * this seam. Until then a verified non-admin identity is denied (null).
+ */
+export function claimToScope(claims: IntrospectionResult, adminGroup: string): string | null {
+  if (claims.groups?.includes(adminGroup)) return ADMIN_SCOPE;
+  return null;
+}
+
+/** Hand-validate an untrusted introspection JSON body (no zod dep in this package). */
+function parseIntrospection(json: unknown): IntrospectionResult | null {
+  if (typeof json !== 'object' || json === null) return null;
+  const o = json as Record<string, unknown>;
+  if (typeof o.active !== 'boolean') return null;
+  const groups = Array.isArray(o.groups)
+    ? o.groups.filter((g): g is string => typeof g === 'string')
+    : undefined;
+  return {
+    active: o.active,
+    sub: typeof o.sub === 'string' ? o.sub : undefined,
+    groups,
+    exp: typeof o.exp === 'number' ? o.exp : undefined,
+  };
+}
+
+function errClass(error: unknown): string {
+  return error instanceof Error ? error.name : 'unknown';
+}
+
+export class IntrospectionVerifier {
+  constructor(private readonly config: IntrospectionConfig) {}
+
+  /** Construct from env, or undefined when introspection isn't configured. */
+  static fromEnv(): IntrospectionVerifier | undefined {
+    const config = introspectionConfigFromEnv();
+    return config ? new IntrospectionVerifier(config) : undefined;
+  }
+
+  /**
+   * Verify an Authorization header value via introspection and return the
+   * publish scope of the identity (ADMIN_SCOPE / per-package), or null when
+   * the token is inactive, expired, unverifiable, or maps to no scope.
+   * Fails CLOSED on every error.
+   */
+  async scopeOf(header: string): Promise<string | null> {
+    const token = bearerToken(header);
+    if (!token) return null;
+    const claims = await this.introspect(token);
+    if (!claims || !claims.active) return null;
+    // RFC 7662 `active:false` already covers expiry, but double-check `exp`
+    // defensively (seconds since epoch) so a misbehaving idp can't slip an
+    // expired-but-active token past us.
+    if (typeof claims.exp === 'number' && claims.exp * 1000 <= Date.now()) return null;
+    return claimToScope(claims, this.config.adminGroup);
+  }
+
+  /**
+   * Verify an Authorization header and resolve the caller's identity for the
+   * hybrid group + owner-table authorization (ce-1ch). Returns null on the same
+   * fail-closed conditions as {@link scopeOf}. `sub` may be absent (an admin can
+   * publish without one); the owner path in the server requires it and denies
+   * a publisher identity that lacks it.
+   */
+  async identify(header: string): Promise<VerifiedIdentity | null> {
+    const token = bearerToken(header);
+    if (!token) return null;
+    const claims = await this.introspect(token);
+    if (!claims || !claims.active) return null;
+    if (typeof claims.exp === 'number' && claims.exp * 1000 <= Date.now()) return null;
+    const isAdmin = claims.groups?.includes(this.config.adminGroup) ?? false;
+    const isPublisher = claims.groups?.includes(this.config.publisherGroup) ?? false;
+    const group = isAdmin
+      ? this.config.adminGroup
+      : isPublisher
+        ? this.config.publisherGroup
+        : undefined;
+    return { sub: claims.sub, isAdmin, isPublisher, group };
+  }
+
+  private async introspect(token: string): Promise<IntrospectionResult | null> {
+    try {
+      const basic = Buffer.from(`${this.config.clientId}:${this.config.clientSecret}`).toString(
+        'base64',
+      );
+      const resp = await fetch(this.config.endpoint, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/x-www-form-urlencoded',
+          Authorization: `Basic ${basic}`,
+          Accept: 'application/json',
+        },
+        body: new URLSearchParams({ token, token_type_hint: 'access_token' }).toString(),
+      });
+      if (!resp.ok) {
+        console.error(`[registry] introspection HTTP ${resp.status} — denying (fail closed)`);
+        return null;
+      }
+      return parseIntrospection(await resp.json());
+    } catch (error) {
+      console.error(
+        `[registry] introspection request failed (${errClass(error)}) — denying (fail closed)`,
+      );
+      return null;
+    }
+  }
+}

package/registry-server/src/landing.ts

@@ -0,0 +1,90 @@
+/**
+ * Landing-page response for `GET /` (and `/index.html`) on the registry.
+ *
+ * This is the polite-301 from the design doc:
+ * (apps/celilo/designs/REGISTRY_BROWSE_UI.md, decision D2). The response
+ * carries `301 Moved Permanently` with `Location:` pointing at the
+ * celilo.computer site's `/modules/` browse UI — interactive browsers
+ * follow the redirect. Clients that don't follow by default (curl
+ * without `-L`, naive bots, bare-bones HTTP libraries) see the body,
+ * which carries the install one-liner, a link to the browse UI, and
+ * the API endpoints they probably actually wanted.
+ *
+ * Single endpoint, no Astro dep, no client JS, no asset pipeline.
+ */
+
+/**
+ * HTML-escape `<`, `>`, `&`, `"` so values interpolated into the body
+ * can't inject markup. Operator-controlled values (publicUrl) are
+ * trusted in practice, but defensive escaping costs nothing.
+ */
+function escapeHtml(s: string): string {
+  return s
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+/**
+ * Build the polite-301 response.
+ *
+ * @param publicUrl  The registry's public URL (typically
+ *                   `https://celilo.computer/registry`). The site's
+ *                   origin is derived by stripping the path. The
+ *                   `/modules/` browse URL on that origin is the
+ *                   redirect target.
+ */
+export function landingResponse(publicUrl: string): Response {
+  const u = new URL(publicUrl);
+  const siteOrigin = u.origin;
+  const browseUrl = `${siteOrigin}/modules/`;
+  const installUrl = `${siteOrigin}/install.sh`;
+  const apiBase = publicUrl.replace(/\/$/, '');
+
+  const body = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Celilo Module Registry</title>
+<style>
+  body { font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+         max-width: 640px; margin: 4em auto; padding: 0 1em;
+         line-height: 1.6; color: #222; }
+  h1 { margin-bottom: 0.2em; }
+  .lead { color: #666; margin-top: 0; }
+  pre { background: #f5f5f5; padding: 0.8em 1em; border-radius: 6px;
+        overflow-x: auto; font-size: 0.9em; }
+  a { color: #0d72b9; }
+  small { color: #888; }
+</style>
+</head>
+<body>
+<h1>Celilo Module Registry</h1>
+<p class="lead">Home-lab orchestration modules — published, versioned, install via the Celilo CLI.</p>
+
+<p>If you're a person, head to <a href="${escapeHtml(browseUrl)}">browse the modules →</a></p>
+
+<p>Install the Celilo CLI:</p>
+<pre><code>curl -fsSL ${escapeHtml(installUrl)} | bash</code></pre>
+
+<p>If you're a tool, the JSON API is here:</p>
+<pre><code>GET ${escapeHtml(apiBase)}/api/v1/modules
+GET ${escapeHtml(apiBase)}/api/v1/modules/{name}
+GET ${escapeHtml(apiBase)}/api/v1/modules/{name}/{version}/download</code></pre>
+
+<p><small>This URL is a 301 to <a href="${escapeHtml(browseUrl)}">${escapeHtml(browseUrl)}</a>. Most browsers followed it before you saw this.</small></p>
+</body>
+</html>
+`;
+
+  return new Response(body, {
+    status: 301,
+    headers: {
+      Location: browseUrl,
+      'Content-Type': 'text/html; charset=utf-8',
+      'Cache-Control': 'public, max-age=300',
+    },
+  });
+}

package/registry-server/src/module-owner-store.test.ts

@@ -0,0 +1,85 @@
+import { describe, expect, test } from 'bun:test';
+import {
+  type ModuleOwnerEntry,
+  type ModuleOwnerPersistence,
+  ModuleOwnerStore,
+} from './module-owner-store';
+
+/** In-memory persistence seam so the store is testable without the filesystem. */
+function memPersistence(initial: ModuleOwnerEntry[] = []): ModuleOwnerPersistence & {
+  saved: ModuleOwnerEntry[];
+} {
+  const state = { saved: [...initial] };
+  return {
+    saved: state.saved,
+    load: () => [...state.saved],
+    save(entries) {
+      state.saved.length = 0;
+      state.saved.push(...entries);
+    },
+  };
+}
+
+const fixedNow = () => '2026-01-01T00:00:00.000Z';
+
+describe('ModuleOwnerStore', () => {
+  test('claim records ownership of an unclaimed name', () => {
+    const p = memPersistence();
+    const store = new ModuleOwnerStore(p, fixedNow);
+    const entry = store.claim('homebridge', 'alice', 'celilo-authors');
+    expect(entry).toEqual({
+      moduleName: 'homebridge',
+      ownerSub: 'alice',
+      claimedAt: fixedNow(),
+      sourceGroup: 'celilo-authors',
+    });
+    expect(store.get('homebridge')?.ownerSub).toBe('alice');
+    expect(p.saved).toHaveLength(1);
+  });
+
+  test('claim never steals an already-owned name (returns existing)', () => {
+    const store = new ModuleOwnerStore(memPersistence(), fixedNow);
+    store.claim('homebridge', 'alice', 'celilo-authors');
+    const second = store.claim('homebridge', 'bob', 'celilo-authors');
+    expect(second.ownerSub).toBe('alice');
+    expect(store.get('homebridge')?.ownerSub).toBe('alice');
+  });
+
+  test('reassign overwrites an existing owner (admin path)', () => {
+    const store = new ModuleOwnerStore(memPersistence(), fixedNow);
+    store.claim('homebridge', 'alice', 'celilo-authors');
+    const reassigned = store.reassign('homebridge', 'bob', 'admin-reassign');
+    expect(reassigned.ownerSub).toBe('bob');
+    expect(store.get('homebridge')?.ownerSub).toBe('bob');
+    // No duplicate rows for the same name.
+    expect(store.list().filter((e) => e.moduleName === 'homebridge')).toHaveLength(1);
+  });
+
+  test('reassign creates a record when the name was unclaimed', () => {
+    const store = new ModuleOwnerStore(memPersistence(), fixedNow);
+    store.reassign('caddy', 'carol', 'admin-reassign');
+    expect(store.get('caddy')?.ownerSub).toBe('carol');
+  });
+
+  test('get returns undefined for an unclaimed name', () => {
+    const store = new ModuleOwnerStore(memPersistence(), fixedNow);
+    expect(store.get('nope')).toBeUndefined();
+  });
+
+  test('loads persisted entries on construction', () => {
+    const p = memPersistence([
+      { moduleName: 'caddy', ownerSub: 'dan', claimedAt: fixedNow(), sourceGroup: 'celilo-admins' },
+    ]);
+    const store = new ModuleOwnerStore(p, fixedNow);
+    expect(store.get('caddy')?.ownerSub).toBe('dan');
+    expect(store.list()).toHaveLength(1);
+  });
+
+  test('list returns a copy (mutating it does not affect the store)', () => {
+    const store = new ModuleOwnerStore(memPersistence(), fixedNow);
+    store.claim('a', 'x', 'g');
+    const list = store.list();
+    list.pop();
+    expect(store.list()).toHaveLength(1);
+  });
+});

package/registry-server/src/module-owner-store.ts

@@ -0,0 +1,108 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+/**
+ * Persisted module-owner table (SECURE_MODULE_PUBLISH.md §5[D-C], ce-1ch).
+ *
+ * The introspection verify-bridge (ce-s7e) proves *who* a publish token belongs
+ * to (a verified `sub` + group claims). This table gates *which modules* that
+ * identity may publish: a module name is **first-publish-claims** — the first
+ * verified publisher of an unclaimed name records ownership; thereafter only the
+ * owner (or an admin) may publish it. This defends the confused-deputy case:
+ * Author-A holding a valid idp token cannot publish Author-B's module.
+ *
+ * Ownership is low-friction / npm-style: no pre-registration, admin can reassign.
+ * Mirrors {@link ScopedTokenStore} (JSON file + I/O seam for unit testing).
+ */
+
+export interface ModuleOwnerEntry {
+  /** Module name this ownership record governs. */
+  moduleName: string;
+  /** Verified idp subject that owns the name (from introspection `sub`). */
+  ownerSub: string;
+  /** ISO timestamp the name was first claimed. */
+  claimedAt: string;
+  /** Group claim that granted the claim (admin or publisher group at claim time). */
+  sourceGroup: string;
+}
+
+/** I/O seam (Rule 2.3) so the store is unit-testable without the filesystem. */
+export interface ModuleOwnerPersistence {
+  load(): ModuleOwnerEntry[];
+  save(entries: ModuleOwnerEntry[]): void;
+}
+
+/** File-backed persistence: a JSON array at `filePath`, tolerant of a missing file. */
+export function fileModuleOwnerPersistence(filePath: string): ModuleOwnerPersistence {
+  return {
+    load() {
+      if (!existsSync(filePath)) return [];
+      try {
+        const parsed = JSON.parse(readFileSync(filePath, 'utf-8'));
+        return Array.isArray(parsed) ? (parsed as ModuleOwnerEntry[]) : [];
+      } catch {
+        return [];
+      }
+    },
+    save(entries) {
+      mkdirSync(dirname(filePath), { recursive: true });
+      writeFileSync(filePath, JSON.stringify(entries, null, 2));
+    },
+  };
+}
+
+export class ModuleOwnerStore {
+  private entries: ModuleOwnerEntry[];
+
+  constructor(
+    private readonly persistence: ModuleOwnerPersistence,
+    private readonly now: () => string = () => new Date().toISOString(),
+  ) {
+    this.entries = persistence.load();
+  }
+
+  list(): ModuleOwnerEntry[] {
+    return [...this.entries];
+  }
+
+  /** The ownership record for `moduleName`, or undefined when unclaimed. */
+  get(moduleName: string): ModuleOwnerEntry | undefined {
+    return this.entries.find((e) => e.moduleName === moduleName);
+  }
+
+  /**
+   * Record ownership of an **unclaimed** name for `ownerSub`. If the name is
+   * already claimed this is a no-op and returns the *existing* entry — claiming
+   * never steals a name (use {@link reassign} for admin overwrite). Returns the
+   * effective owner entry either way.
+   */
+  claim(moduleName: string, ownerSub: string, sourceGroup: string): ModuleOwnerEntry {
+    const existing = this.get(moduleName);
+    if (existing) return existing;
+    const entry: ModuleOwnerEntry = {
+      moduleName,
+      ownerSub,
+      claimedAt: this.now(),
+      sourceGroup,
+    };
+    this.entries = [...this.entries, entry];
+    this.persistence.save(this.entries);
+    return entry;
+  }
+
+  /**
+   * Overwrite (or create) the ownership record for `moduleName` — admin
+   * reassignment. Unlike {@link claim} this steals an already-owned name.
+   */
+  reassign(moduleName: string, ownerSub: string, sourceGroup: string): ModuleOwnerEntry {
+    const entry: ModuleOwnerEntry = {
+      moduleName,
+      ownerSub,
+      claimedAt: this.now(),
+      sourceGroup,
+    };
+    this.entries = [...this.entries.filter((e) => e.moduleName !== moduleName), entry];
+    this.persistence.save(this.entries);
+    return entry;
+  }
+}

package/registry-server/src/rate-limit.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from 'bun:test';
+import { clientIp, createRateLimiter } from './rate-limit';
+
+describe('createRateLimiter', () => {
+  test('allows up to max, then rejects', () => {
+    const limiter = createRateLimiter({ max: 3, windowMs: 60_000, now: () => 0 });
+    expect(limiter.take('1.1.1.1').ok).toBe(true);
+    expect(limiter.take('1.1.1.1').ok).toBe(true);
+    expect(limiter.take('1.1.1.1').ok).toBe(true);
+    const over = limiter.take('1.1.1.1');
+    expect(over.ok).toBe(false);
+    if (!over.ok) expect(over.retryAfterSec).toBeGreaterThan(0);
+  });
+
+  test('distinct IPs are tracked separately', () => {
+    const limiter = createRateLimiter({ max: 1, windowMs: 60_000, now: () => 0 });
+    expect(limiter.take('1.1.1.1').ok).toBe(true);
+    expect(limiter.take('2.2.2.2').ok).toBe(true); // different IP, fresh allowance
+    expect(limiter.take('1.1.1.1').ok).toBe(false);
+  });
+
+  test('bucket resets after window elapses', () => {
+    let t = 0;
+    const limiter = createRateLimiter({ max: 1, windowMs: 1000, now: () => t });
+    expect(limiter.take('1.1.1.1').ok).toBe(true);
+    expect(limiter.take('1.1.1.1').ok).toBe(false);
+    t = 1001;
+    expect(limiter.take('1.1.1.1').ok).toBe(true);
+  });
+
+  test('retryAfterSec reflects remaining window', () => {
+    const limiter = createRateLimiter({ max: 1, windowMs: 60_000, now: () => 0 });
+    limiter.take('1.1.1.1');
+    const r = limiter.take('1.1.1.1');
+    expect(r.ok).toBe(false);
+    if (!r.ok) {
+      expect(r.retryAfterSec).toBeLessThanOrEqual(60);
+      expect(r.retryAfterSec).toBeGreaterThan(0);
+    }
+  });
+});
+
+describe('clientIp', () => {
+  function req(headers: Record<string, string>): Request {
+    return new Request('http://x/', { headers });
+  }
+  const stubServer = {
+    requestIP: () => ({ address: '10.0.0.1' }),
+  };
+
+  test('uses X-Forwarded-For first entry when present', () => {
+    expect(clientIp(req({ 'x-forwarded-for': '1.1.1.1, 2.2.2.2' }), stubServer)).toBe('1.1.1.1');
+  });
+
+  test('falls back to Bun.Server.requestIP when XFF absent', () => {
+    expect(clientIp(req({}), stubServer)).toBe('10.0.0.1');
+  });
+
+  test('returns "unknown" when neither available', () => {
+    expect(clientIp(req({}), { requestIP: () => null })).toBe('unknown');
+  });
+});

package/registry-server/src/rate-limit.ts

@@ -0,0 +1,83 @@
+/**
+ * Simple in-memory per-IP rate limiter for the auth-gated endpoints
+ * (publish, yank, unyank). The public-read endpoints (download, index,
+ * search) are left unlimited — they're cacheable and the body-size cap
+ * on publish already covers the main DoS vector.
+ *
+ * We implement this in-process rather than in Caddy because the stock
+ * apt-installed Caddy doesn't include the community `caddy-ratelimit`
+ * plugin. If we ever switch the caddy module to `xcaddy build` with the
+ * plugin, we can move this upstream and delete this file.
+ *
+ * The limiter is a fixed window counter: each IP gets a fresh allowance
+ * every `windowMs`. No burst smoothing, which is fine for the tiny
+ * traffic a registry actually sees — we just want to keep a bad actor
+ * from flooding the disk via repeated publish attempts.
+ */
+
+interface Bucket {
+  count: number;
+  /** Epoch ms when this bucket resets to 0 and `windowMs` restarts. */
+  resetAt: number;
+}
+
+export interface RateLimiter {
+  /**
+   * Record one hit from `ip`. Returns {ok: true, remaining} if under the
+   * limit; {ok: false, retryAfterSec} if the window is exhausted.
+   */
+  take(ip: string): { ok: true; remaining: number } | { ok: false; retryAfterSec: number };
+}
+
+export function createRateLimiter(opts: {
+  /** Max events per IP per window. */
+  max: number;
+  /** Window length in ms. */
+  windowMs: number;
+  /** Inject a clock for tests; defaults to Date.now. */
+  now?: () => number;
+}): RateLimiter {
+  const buckets = new Map<string, Bucket>();
+  const now = opts.now ?? (() => Date.now());
+
+  // Opportunistic cleanup: if the map grows past a size threshold, drop
+  // expired entries. Keeps memory bounded even under churny attackers
+  // hitting from rotating IPs.
+  const CLEANUP_AT = 1000;
+
+  return {
+    take(ip: string) {
+      const t = now();
+      let bucket = buckets.get(ip);
+      if (!bucket || t >= bucket.resetAt) {
+        bucket = { count: 0, resetAt: t + opts.windowMs };
+        buckets.set(ip, bucket);
+      }
+      bucket.count += 1;
+      if (bucket.count > opts.max) {
+        return { ok: false, retryAfterSec: Math.max(1, Math.ceil((bucket.resetAt - t) / 1000)) };
+      }
+      if (buckets.size > CLEANUP_AT) {
+        for (const [k, v] of buckets) if (t >= v.resetAt) buckets.delete(k);
+      }
+      return { ok: true, remaining: opts.max - bucket.count };
+    },
+  };
+}
+
+/**
+ * Extract the caller's IP for rate-limit keying. Prefers the first entry
+ * of X-Forwarded-For (trusted-proxy assumption — we sit behind Caddy);
+ * falls back to the raw socket peer via Bun.Server.requestIP.
+ */
+export function clientIp(
+  req: Request,
+  server: { requestIP(r: Request): { address: string } | null },
+): string {
+  const xff = req.headers.get('x-forwarded-for');
+  if (xff) {
+    const first = xff.split(',')[0]?.trim();
+    if (first) return first;
+  }
+  return server.requestIP(req)?.address ?? 'unknown';
+}