feat(kilo-chat): add SandboxRegistryDO for per-sandbox token registry

Foundation for replacing the shared KILOCHAT_API_TOKEN with per-sandbox
tokens. A singleton Durable Object owns the (token_hash → sandbox_id)
mapping used by the hot auth path, and a sandbox_id unique index
supports mint/revoke operations by sandbox.

Tokens are 24 random bytes (192 bits entropy) prefixed with "ksk_" so
accidental leaks are easy to grep. SHA-256 hashes are stored — the
plaintext token is only ever returned once at mint time.

The DO itself does not validate sandbox_id format; callers MUST use
isValidSandboxId at the admin boundary. Throwing inside a DO RPC method
corrupts miniflare's storage isolation during tests, and validation
belongs at the API layer anyway.

No wiring yet — the DO is added but not referenced by auth or routes
in this commit. Following commits swap the auth path and add the admin
API that mints tokens.

Author: iscekic

services/kilo-chat/drizzle-sandbox-registry.config.ts

@@ -0,0 +1,7 @@
+import { defineConfig } from 'drizzle-kit';
+export default defineConfig({
+  out: './drizzle/sandbox-registry',
+  schema: './src/db/sandbox-registry-schema.ts',
+  dialect: 'sqlite',
+  driver: 'durable-sqlite',
+});

services/kilo-chat/drizzle/sandbox-registry/0000_sandbox_registry.sql

@@ -0,0 +1,7 @@
+CREATE TABLE `sandbox_tokens` (
+	`token_hash` text PRIMARY KEY NOT NULL,
+	`sandbox_id` text NOT NULL,
+	`created_at` integer NOT NULL
+);
+--> statement-breakpoint
+CREATE UNIQUE INDEX `sandbox_tokens_sandbox_id_unique` ON `sandbox_tokens` (`sandbox_id`);

services/kilo-chat/drizzle/sandbox-registry/meta/_journal.json

@@ -0,0 +1,13 @@
+{
+  "version": "7",
+  "dialect": "sqlite",
+  "entries": [
+    {
+      "idx": 0,
+      "version": "6",
+      "when": 1776200000000,
+      "tag": "0000_sandbox_registry",
+      "breakpoints": true
+    }
+  ]
+}

services/kilo-chat/drizzle/sandbox-registry/migrations.js

@@ -0,0 +1,9 @@
+import journal from './meta/_journal.json';
+import m0000 from './0000_sandbox_registry.sql';
+
+export default {
+  journal,
+  migrations: {
+    m0000,
+  },
+};

services/kilo-chat/src/__tests__/sandbox-registry-do.test.ts

@@ -0,0 +1,74 @@
+import { env } from 'cloudflare:test';
+import { describe, it, expect } from 'vitest';
+import {
+  SANDBOX_TOKEN_PREFIX,
+  hashToken,
+  isValidSandboxId,
+  type SandboxRegistryDO,
+} from '../do/sandbox-registry-do';
+import { getSandboxRegistryStub } from '../do/sandbox-registry-client';
+
+function stub(): DurableObjectStub<SandboxRegistryDO> {
+  return getSandboxRegistryStub(env.SANDBOX_REGISTRY_DO);
+}
+
+describe('SandboxRegistryDO', () => {
+  it('mintToken returns a prefixed token and matching SHA-256 hash', async () => {
+    const result = await stub().mintToken('sbx_test_mint_1');
+    expect(result.token.startsWith(SANDBOX_TOKEN_PREFIX)).toBe(true);
+    // 24 random bytes → 32 base64url chars + prefix.
+    expect(result.token.length).toBe(SANDBOX_TOKEN_PREFIX.length + 32);
+    expect(result.tokenHash).toBe(await hashToken(result.token));
+    expect(result.tokenHash).toMatch(/^[0-9a-f]{64}$/);
+  });
+
+  it('lookupSandbox round-trips a freshly minted token', async () => {
+    const { token } = await stub().mintToken('sbx_test_lookup_1');
+    const sandboxId = await stub().lookupSandbox(token);
+    expect(sandboxId).toBe('sbx_test_lookup_1');
+  });
+
+  it('lookupSandbox returns null for tokens without the prefix', async () => {
+    const sandboxId = await stub().lookupSandbox('not-a-ksk-token');
+    expect(sandboxId).toBeNull();
+  });
+
+  it('lookupSandbox returns null for a well-formed but unknown token', async () => {
+    // Valid shape but never minted.
+    const fake = `${SANDBOX_TOKEN_PREFIX}${'a'.repeat(32)}`;
+    const sandboxId = await stub().lookupSandbox(fake);
+    expect(sandboxId).toBeNull();
+  });
+
+  it('minting for the same sandbox replaces the previous token atomically', async () => {
+    const s = stub();
+    const first = await s.mintToken('sbx_test_replace');
+    const second = await s.mintToken('sbx_test_replace');
+    expect(second.token).not.toBe(first.token);
+    expect(await s.lookupSandbox(first.token)).toBeNull();
+    expect(await s.lookupSandbox(second.token)).toBe('sbx_test_replace');
+  });
+
+  it('revokeSandbox deletes the token and makes lookup return null', async () => {
+    const s = stub();
+    const { token } = await s.mintToken('sbx_test_revoke');
+    expect(await s.revokeSandbox('sbx_test_revoke')).toBe(true);
+    expect(await s.lookupSandbox(token)).toBeNull();
+  });
+
+  it('revokeSandbox returns false for an unknown sandbox', async () => {
+    expect(await stub().revokeSandbox('sbx_does_not_exist')).toBe(false);
+  });
+
+  it('isValidSandboxId rejects malformed sandbox ids (enforced at admin boundary)', () => {
+    // The DO intentionally does not re-validate — throwing inside a DO RPC
+    // method corrupts miniflare's storage isolation. Callers MUST use
+    // isValidSandboxId upstream.
+    expect(isValidSandboxId('sbx_AZaz09-_')).toBe(true);
+    expect(isValidSandboxId('')).toBe(false);
+    expect(isValidSandboxId('has spaces')).toBe(false);
+    expect(isValidSandboxId('a'.repeat(65))).toBe(false);
+    expect(isValidSandboxId('tab\there')).toBe(false);
+    expect(isValidSandboxId('colon:here')).toBe(false);
+  });
+});

services/kilo-chat/src/db/sandbox-registry-schema.ts

@@ -0,0 +1,15 @@
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
+
+/**
+ * Per-sandbox API token registry.
+ *
+ * One row per sandbox; minting for an existing sandbox replaces the row
+ * (old token is invalidated atomically). The token's SHA-256 hash is the
+ * primary key so lookups on the hot auth path hit a b-tree index, while
+ * sandbox_id has a UNIQUE index for mint/revoke by sandbox.
+ */
+export const sandbox_tokens = sqliteTable('sandbox_tokens', {
+  token_hash: text('token_hash').primaryKey(),
+  sandbox_id: text('sandbox_id').notNull().unique(),
+  created_at: integer('created_at').notNull(),
+});

services/kilo-chat/src/do/sandbox-registry-client.ts

@@ -0,0 +1,18 @@
+import type { SandboxRegistryDO } from './sandbox-registry-do';
+
+/**
+ * Helpers for reaching the singleton SandboxRegistryDO.
+ *
+ * All callers must use `getSandboxRegistryStub` so the fixed name stays
+ * consistent across the worker. If we ever shard by hash prefix, this is
+ * the only place that needs to change.
+ */
+
+/** Fixed DO name — there is exactly one registry instance. */
+const REGISTRY_DO_NAME = 'registry';
+
+export function getSandboxRegistryStub(
+  binding: DurableObjectNamespace<SandboxRegistryDO>
+): DurableObjectStub<SandboxRegistryDO> {
+  return binding.get(binding.idFromName(REGISTRY_DO_NAME));
+}

services/kilo-chat/src/do/sandbox-registry-do.ts

@@ -0,0 +1,119 @@
+import { DurableObject } from 'cloudflare:workers';
+import { drizzle } from 'drizzle-orm/durable-sqlite';
+import { migrate } from 'drizzle-orm/durable-sqlite/migrator';
+import { eq } from 'drizzle-orm';
+import { sandbox_tokens } from '../db/sandbox-registry-schema';
+import migrations from '../../drizzle/sandbox-registry/migrations';
+
+/** Prefix makes accidental-leak grepping easy ("kilo sandbox key"). */
+export const SANDBOX_TOKEN_PREFIX = 'ksk_';
+/** 24 bytes → 32 base64url chars. ~192 bits entropy. */
+const TOKEN_RANDOM_BYTES = 24;
+
+const SANDBOX_ID_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+
+export type MintTokenResult = {
+  /** Plaintext token — shown to the admin once, never retrievable again. */
+  token: string;
+  /** SHA-256 hex of the token — safe to log / return from list endpoints. */
+  tokenHash: string;
+};
+
+export function isValidSandboxId(sandboxId: string): boolean {
+  return SANDBOX_ID_PATTERN.test(sandboxId);
+}
+
+function bytesToHex(bytes: Uint8Array): string {
+  let s = '';
+  for (const b of bytes) {
+    s += b.toString(16).padStart(2, '0');
+  }
+  return s;
+}
+
+function base64urlEncode(bytes: Uint8Array): string {
+  let s = '';
+  for (const b of bytes) {
+    s += String.fromCharCode(b);
+  }
+  return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export async function hashToken(token: string): Promise<string> {
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(token));
+  return bytesToHex(new Uint8Array(digest));
+}
+
+function generateToken(): string {
+  const bytes = new Uint8Array(TOKEN_RANDOM_BYTES);
+  crypto.getRandomValues(bytes);
+  return `${SANDBOX_TOKEN_PREFIX}${base64urlEncode(bytes)}`;
+}
+
+/**
+ * Singleton DO that owns the per-sandbox API token registry.
+ *
+ * All instances are keyed by a fixed name ("registry") — this is a single
+ * point of contention for every authenticated bot request. If/when kilo-chat
+ * outgrows a single DO's throughput, shard by token-hash prefix.
+ */
+export class SandboxRegistryDO extends DurableObject<Env> {
+  private db;
+
+  constructor(ctx: DurableObjectState, env: Env) {
+    super(ctx, env);
+    this.db = drizzle(ctx.storage, { logger: false });
+    void ctx.blockConcurrencyWhile(() => migrate(this.db, migrations));
+  }
+
+  /**
+   * Mint a fresh token for `sandboxId`. If a token already exists for this
+   * sandbox it is atomically replaced — the old token stops working
+   * immediately. The plaintext token is returned only here.
+   *
+   * Callers MUST validate `sandboxId` via `isValidSandboxId` at the admin
+   * boundary. This method does not re-validate — throwing from a DO RPC
+   * method leaves miniflare's storage isolation in a bad state during tests.
+   */
+  async mintToken(sandboxId: string): Promise<MintTokenResult> {
+    const token = generateToken();
+    const tokenHash = await hashToken(token);
+    this.db.delete(sandbox_tokens).where(eq(sandbox_tokens.sandbox_id, sandboxId)).run();
+    this.db
+      .insert(sandbox_tokens)
+      .values({
+        token_hash: tokenHash,
+        sandbox_id: sandboxId,
+        created_at: Date.now(),
+      })
+      .run();
+    return { token, tokenHash };
+  }
+
+  /**
+   * Resolve a plaintext token to its sandbox. Returns `null` for unknown or
+   * malformed tokens. Hot-path auth lookup — kept index-only (SHA-256 hash).
+   */
+  async lookupSandbox(token: string): Promise<string | null> {
+    if (!token.startsWith(SANDBOX_TOKEN_PREFIX)) return null;
+    const tokenHash = await hashToken(token);
+    const row = this.db
+      .select()
+      .from(sandbox_tokens)
+      .where(eq(sandbox_tokens.token_hash, tokenHash))
+      .get();
+    return row?.sandbox_id ?? null;
+  }
+
+  /** Revoke the token for `sandboxId`. Returns true if a row was deleted. */
+  revokeSandbox(sandboxId: string): boolean {
+    const existing = this.db
+      .select()
+      .from(sandbox_tokens)
+      .where(eq(sandbox_tokens.sandbox_id, sandboxId))
+      .get();
+    if (!existing) return false;
+    this.db.delete(sandbox_tokens).where(eq(sandbox_tokens.sandbox_id, sandboxId)).run();
+    return true;
+  }
+}