console: sync the registration wizard and issue real API tokens

Mirror the Console registration feature: native hook catalog with
activation plans, one-command install that embeds both credentials in
exclusively created owner-only files (mktemp on POSIX, icacls on
Windows), sh/PowerShell tabs, never-expiring default token, focus-visible
styles, merged i18n keys, and the matching e2e specs.

The server previously answered /v1/auth/token with the 7-day Better Auth
session token and ignored ttl_seconds. It now issues opaque 32-byte API
tokens stored as SHA-256 hashes (migration 003), honours ttl_seconds with
null meaning no expiry, and resolves bearer values as API tokens before
session validation. Issuance requires a session credential.

Claude-Session: https://claude.ai/code/session_01QoUjdc7HGKTsgj5GhG8HvF

packages/server/src/i18n/messages.ts

@@ -90,8 +90,8 @@ const messages: Record<string, Record<Lang, string>> = {
     zh: 'Bearer \u4ee4\u724c\u4e3a\u7a7a',
   },
   'auth.ttlMustBePositive': {
-    en: 'ttl_seconds must be a positive number',
-    zh: 'ttl_seconds \u5fc5\u987b\u4e3a\u6b63\u6570',
+    en: 'ttl_seconds must be a whole number of seconds from 1 to 31536000',
+    zh: 'ttl_seconds 必须是 1 到 31536000 之间的整数秒',
   },
 
   // ---------------------------------------------------------------------------
@@ -121,6 +121,14 @@ const messages: Record<string, Record<Lang, string>> = {
     en: 'ttl_seconds must be a number or null',
     zh: 'ttl_seconds \u5fc5\u987b\u4e3a\u6570\u5b57\u6216 null',
   },
+  'auth.issueRequiresSession': {
+    en: 'API token issuance requires a session credential.',
+    zh: '签发 API 令牌需要使用会话凭据。',
+  },
+  'auth.organizationRequiredForApiToken': {
+    en: 'Organization setup is required before issuing an API token.',
+    zh: '签发 API 令牌前需要完成组织设置。',
+  },
 
   // ---------------------------------------------------------------------------
   // Agent routes  (src/routes/agents.ts)

packages/server/src/middleware/auth.ts

@@ -1,14 +1,10 @@
 /**
- * Better Auth authentication middleware.
+ * Authentication middleware for opaque API tokens and Better Auth sessions.
  *
- * Validates requests via Better Auth sessions (cookie or bearer token).
- * On success, extracts `org_id`, `role`, and user `id` (actor) from the
- * session and stores them in the Hono context variables for downstream
- * handlers.
- *
- * Supports:
- *   - Session cookies (browser / console)
- *   - Bearer tokens via Better Auth's bearer plugin (SDK clients)
+ * A bearer value is resolved as a hashed API token first; anything else is
+ * validated as a Better Auth session (cookie or bearer session token).
+ * On success the org_id, role, actor, and credential kind are stored in the
+ * Hono context variables for downstream handlers.
  */
 
 import type { MiddlewareHandler } from 'hono';
@@ -16,13 +12,8 @@ import type { RbacRole } from '../shared/index.js';
 import type { Env, AppVariables } from '../types.js';
 import { AppError } from './error-handler.js';
 import { createAuth } from '../lib/auth.js';
+import { authenticateApiToken } from '../services/api-token-service.js';
 
-/**
- * Authentication middleware.
- *
- * Uses Better Auth's getSession to validate the request via session
- * cookie or bearer token. Sets org_id, role, and actor on the context.
- */
 export const authMiddleware: MiddlewareHandler<{
   Bindings: Env;
   Variables: AppVariables;
@@ -32,6 +23,19 @@ export const authMiddleware: MiddlewareHandler<{
     throw new AppError(401, 'UNAUTHORIZED', { key: 'auth.missingHeader' });
   }
 
+  const bearerToken = authHeader.startsWith('Bearer ') ? authHeader.slice(7).trim() : '';
+  if (bearerToken) {
+    const apiToken = await authenticateApiToken(c.env.ELYDORA_DB, bearerToken);
+    if (apiToken) {
+      c.set('org_id', apiToken.org_id);
+      c.set('role', apiToken.role);
+      c.set('actor', apiToken.user_id);
+      c.set('auth_token_type', 'api');
+      await next();
+      return;
+    }
+  }
+
   let session: Awaited<ReturnType<ReturnType<typeof createAuth>['api']['getSession']>>;
 
   try {
@@ -57,6 +61,7 @@ export const authMiddleware: MiddlewareHandler<{
   c.set('org_id', user.org_id ?? '');
   c.set('role', ((user.role ?? 'readonly_investigator') as RbacRole));
   c.set('actor', user.id);
+  c.set('auth_token_type', 'session');
 
   await next();
 };

packages/server/src/routes/auth.ts

@@ -2,7 +2,7 @@
  * Auth routes — registration, login, profile retrieval, and token refresh.
  *
  * /register and /login are public (no auth required).
- * /me, /refresh, and /token require a valid Better Auth session.
+ * /me and /refresh require a valid Better Auth session or API token; /token requires a session.
  *
  * Uses Better Auth for session management while preserving the existing
  * API surface (endpoint paths and response formats).
@@ -11,6 +11,8 @@
 import { Hono } from 'hono';
 import type { Env, AppVariables } from '../types.js';
 import { authMiddleware } from '../middleware/auth.js';
+import { AppError } from '../middleware/error-handler.js';
+import { issueApiToken, MAX_TTL_SECONDS } from '../services/api-token-service.js';
 import { getMe } from '../services/auth-service.js';
 import { createAuth } from '../lib/auth.js';
 import { getMessage } from '../i18n/messages.js';
@@ -169,46 +171,32 @@ auth.post('/refresh', authMiddleware, async (c) => {
 });
 
 // ---------------------------------------------------------------------------
-// POST /v1/auth/token — Issue an API token with custom TTL (auth required)
+// POST /v1/auth/token — Issue an opaque API token (session required)
 // ---------------------------------------------------------------------------
 auth.post('/token', authMiddleware, async (c) => {
+  if (c.get('auth_token_type') !== 'session') {
+    throw new AppError(400, 'VALIDATION_ERROR', { key: 'auth.issueRequiresSession' });
+  }
+
   const body = await c.req.json();
   const { ttl_seconds } = body;
 
   if (ttl_seconds !== null && ttl_seconds !== undefined) {
-    if (typeof ttl_seconds !== 'number' || ttl_seconds <= 0) {
-      const lang = c.get('lang') ?? 'en';
-      return c.json({ error: { code: 'VALIDATION_ERROR', message: getMessage('auth.ttlMustBeNumber', lang), request_id: '' } }, 400);
+    if (typeof ttl_seconds !== 'number') {
+      throw new AppError(400, 'VALIDATION_ERROR', { key: 'auth.ttlMustBeNumber' });
+    }
+    if (!Number.isInteger(ttl_seconds) || ttl_seconds <= 0 || ttl_seconds > MAX_TTL_SECONDS) {
+      throw new AppError(400, 'VALIDATION_ERROR', { key: 'auth.ttlMustBePositive' });
     }
   }
 
-  // Get the current session token — Better Auth sessions have a fixed
-  // lifetime configured in the auth instance (7 days by default).
-  // The ttl_seconds parameter is accepted for API compatibility but
-  // session lifetime is governed by Better Auth's session config.
-  const betterAuthInstance = createAuth(
-    process.env.DATABASE_URL!,
-    c.env.BETTER_AUTH_SECRET,
-    c.env.BETTER_AUTH_URL,
-    c.env.ALLOWED_ORIGINS,
-  );
-
-  const session = await betterAuthInstance.api.getSession({
-    headers: c.req.raw.headers,
-  });
-
-  if (!session) {
-    const lang = c.get('lang') ?? 'en';
-    return c.json({ error: { code: 'UNAUTHORIZED', message: getMessage('auth.invalidSession', lang), request_id: '' } }, 401);
+  const orgId = c.get('org_id');
+  if (!orgId) {
+    throw new AppError(409, 'VALIDATION_ERROR', { key: 'auth.organizationRequiredForApiToken' });
   }
 
-  const sessionData = session.session as { token?: string; expiresAt?: Date };
-  const token = sessionData.token ?? '';
-  const expiresAt = sessionData.expiresAt
-    ? Math.floor(new Date(sessionData.expiresAt).getTime() / 1000)
-    : Math.floor(Date.now() / 1000) + 604800;
-
-  return c.json({ token, expires_at: expiresAt }, 200);
+  const issued = await issueApiToken(c.env.ELYDORA_DB, c.get('actor'), orgId, ttl_seconds ?? null);
+  return c.json({ token: issued.token, expires_at: issued.expires_at }, 200);
 });
 
 export { auth };

packages/server/src/services/api-token-service.ts

@@ -0,0 +1,87 @@
+/**
+ * Opaque API tokens: the raw value is returned once; only its SHA-256 hash is stored.
+ */
+
+import { createHash, randomBytes } from 'node:crypto';
+import type { Database } from '../adapters/interfaces.js';
+import type { RbacRole } from '../shared/index.js';
+import { generateUUIDv7 } from '../utils/uuid.js';
+
+export const MAX_TTL_SECONDS = 31_536_000;
+
+interface ApiTokenAuthRow {
+  readonly token_id: string;
+  readonly user_id: string;
+  readonly org_id: string;
+  readonly expires_at: number | null;
+  readonly user_org_id: string | null;
+  readonly user_role: RbacRole;
+  readonly user_status: string;
+}
+
+export interface AuthenticatedApiToken {
+  readonly token_id: string;
+  readonly user_id: string;
+  readonly org_id: string;
+  readonly role: RbacRole;
+}
+
+export interface IssuedApiToken {
+  readonly token: string;
+  readonly token_id: string;
+  readonly expires_at: number | null;
+}
+
+function hashToken(token: string): string {
+  return createHash('sha256').update(token).digest('hex');
+}
+
+export async function authenticateApiToken(
+  db: Database,
+  rawToken: string,
+): Promise<AuthenticatedApiToken | null> {
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const row = await db
+    .prepare(
+      `SELECT t.token_id, t.user_id, t.org_id, t.expires_at,
+              u.org_id AS user_org_id, u.role AS user_role, u.status AS user_status
+       FROM api_tokens AS t
+       JOIN users AS u ON u.user_id = t.user_id
+       WHERE t.token_hash = ?`,
+    )
+    .bind(hashToken(rawToken))
+    .first<ApiTokenAuthRow>();
+
+  if (!row) return null;
+  if (row.expires_at !== null && row.expires_at <= nowSeconds) return null;
+  if (row.user_status !== 'active' || row.user_org_id !== row.org_id) return null;
+
+  return {
+    token_id: row.token_id,
+    user_id: row.user_id,
+    org_id: row.org_id,
+    role: row.user_role,
+  };
+}
+
+export async function issueApiToken(
+  db: Database,
+  userId: string,
+  orgId: string,
+  ttlSeconds: number | null,
+): Promise<IssuedApiToken> {
+  const nowSeconds = Math.floor(Date.now() / 1000);
+  const expiresAt = ttlSeconds === null ? null : nowSeconds + ttlSeconds;
+  const tokenId = generateUUIDv7();
+  const token = randomBytes(32).toString('base64url');
+
+  await db
+    .prepare(
+      `INSERT INTO api_tokens (token_id, user_id, org_id, token_hash, issued_at, expires_at)
+       VALUES (?, ?, ?, ?, ?, ?)`,
+    )
+    .bind(tokenId, userId, orgId, hashToken(token), nowSeconds, expiresAt)
+    .run();
+
+  return { token, token_id: tokenId, expires_at: expiresAt };
+}

packages/server/src/types.ts

@@ -62,6 +62,9 @@ export interface AppVariables {
   /** Actor identifier extracted from the verified session */
   actor: string;
 
+  /** Credential kind that authenticated the request */
+  auth_token_type: 'api' | 'session';
+
   /** Detected language from Accept-Language header (set by i18n middleware) */
   lang: import('./i18n/messages.js').Lang;
 }