incremnt 0.1.0

package/src/sync-service.js

@@ -0,0 +1,1165 @@
+import { timingSafeEqual } from 'node:crypto';
+import { capabilities as cliCapabilities, contractVersion, officialCommands } from './contract.js';
+import { executeReadCommand } from './queries.js';
+
+const MAX_BODY_BYTES = 10 * 1024 * 1024; // 10 MB
+const DEFAULT_RATE_LIMIT_WINDOW_MS = 60_000;
+const DEFAULT_RATE_LIMIT_RULES = {
+  'dev-login': 10,
+  'device-start': 20,
+  'device-poll': 300,
+  'device-approve': 30,
+  'google-start': 20,
+  'google-callback': 20,
+  'apple-start': 20,
+  'apple-callback': 20,
+  'session-login': 60,
+  'session-refresh': 30
+};
+
+function json(response, statusCode, payload) {
+  response.writeHead(statusCode, { 'content-type': 'application/json' });
+  response.end(JSON.stringify(payload));
+}
+
+function logRequest(request, statusCode, extra = '') {
+  const method = request.method ?? '?';
+  const rawUrl = request.url ?? '/';
+  const path = rawUrl.split('?')[0];
+  const suffix = extra ? ` ${extra}` : '';
+  console.log(`${method} ${path} ${statusCode}${suffix}`);
+}
+
+function unauthorized(response, request) {
+  if (request) logRequest(request, 401);
+  json(response, 401, { error: 'Unauthorized' });
+}
+
+function notFound(response, message = 'Not found') {
+  json(response, 404, { error: message });
+}
+
+function badRequest(response, message) {
+  json(response, 400, { error: message });
+}
+
+function methodNotAllowed(response, message = 'Method not allowed') {
+  json(response, 405, { error: message });
+}
+
+function internalError(response, error) {
+  console.error('Internal error:', error.message);
+  json(response, 500, { error: 'Internal server error' });
+}
+
+function constantTimeEqual(a, b) {
+  if (!a || !b) return false;
+  const bufA = Buffer.from(a);
+  const bufB = Buffer.from(b);
+  if (bufA.length !== bufB.length) return false;
+  return timingSafeEqual(bufA, bufB);
+}
+
+function bearerToken(request) {
+  const value = request.headers.authorization ?? '';
+  return value.startsWith('Bearer ') ? value.slice('Bearer '.length) : null;
+}
+
+function adminSecret(request) {
+  return request.headers['x-incremnt-admin-secret'] ?? '';
+}
+
+function clientAddress(request, { trustProxy = false } = {}) {
+  if (trustProxy) {
+    const forwarded = request.headers['x-forwarded-for'];
+    if (typeof forwarded === 'string' && forwarded.trim()) {
+      return forwarded.split(',')[0].trim();
+    }
+  }
+
+  return request.socket?.remoteAddress ?? 'unknown';
+}
+
+function createRateLimiter({
+  windowMs = DEFAULT_RATE_LIMIT_WINDOW_MS,
+  rules = {},
+  trustProxy = false
+} = {}) {
+  const mergedRules = { ...DEFAULT_RATE_LIMIT_RULES, ...rules };
+  const buckets = new Map();
+
+  return {
+    check(request, command) {
+      const limit = mergedRules[command];
+      if (!limit) {
+        return { allowed: true };
+      }
+
+      const key = `${command}:${clientAddress(request, { trustProxy })}`;
+      const now = Date.now();
+      const bucket = buckets.get(key);
+
+      if (!bucket || bucket.resetAt <= now) {
+        buckets.set(key, { count: 1, resetAt: now + windowMs });
+        return { allowed: true };
+      }
+
+      if (bucket.count >= limit) {
+        return { allowed: false };
+      }
+
+      bucket.count += 1;
+      buckets.set(key, bucket);
+      return { allowed: true };
+    }
+  };
+}
+
+function routeRequest(url) {
+  const pathname = url.pathname;
+
+  if (pathname === '/healthz') {
+    return { command: 'healthz', options: {} };
+  }
+
+  if (pathname === '/auth/dev-login') {
+    return { command: 'dev-login', options: {} };
+  }
+
+  if (pathname === '/auth/config') {
+    return { command: 'auth-config', options: {} };
+  }
+
+  if (pathname === '/auth/session') {
+    return { command: 'session-login', options: {} };
+  }
+
+  if (pathname === '/auth/refresh') {
+    return { command: 'session-refresh', options: {} };
+  }
+
+  if (pathname === '/auth/device/start') {
+    return { command: 'device-start', options: {} };
+  }
+
+  if (pathname === '/auth/device/poll') {
+    return { command: 'device-poll', options: {} };
+  }
+
+  if (pathname === '/auth/device/approve') {
+    return { command: 'device-approve', options: {} };
+  }
+
+  if (pathname === '/auth/google/start') {
+    return { command: 'google-start', options: {} };
+  }
+
+  if (pathname === '/auth/google/callback') {
+    return { command: 'google-callback', options: {} };
+  }
+
+  if (pathname === '/auth/apple/start') {
+    return { command: 'apple-start', options: {} };
+  }
+
+  if (pathname === '/auth/apple/callback') {
+    return { command: 'apple-callback', options: {} };
+  }
+
+  if (pathname === '/admin/bootstrap-user') {
+    return { command: 'admin-bootstrap-user', options: {} };
+  }
+
+  if (pathname === '/cli/contract') {
+    return { command: 'contract', options: {} };
+  }
+
+  if (pathname === '/sync/snapshot') {
+    return { command: 'sync-upload', options: {} };
+  }
+
+  if (pathname === '/cli/sessions') {
+    return {
+      command: 'session-insights',
+      options: {
+        limit: url.searchParams.get('limit') ?? undefined
+      }
+    };
+  }
+
+  if (pathname === '/cli/programs') {
+    return { command: 'program-list', options: {} };
+  }
+
+  if (pathname === '/cli/programs/current') {
+    return { command: 'program-summary', options: {} };
+  }
+
+  if (pathname === '/cli/exercises/history') {
+    return {
+      command: 'exercise-history',
+      options: {
+        name: url.searchParams.get('name') ?? undefined
+      }
+    };
+  }
+
+  if (pathname === '/cli/records') {
+    return { command: 'records', options: {} };
+  }
+
+  const compareMatch = pathname.match(/^\/cli\/sessions\/([^/]+)\/compare$/);
+  if (compareMatch) {
+    return {
+      command: 'planned-vs-actual',
+      options: {
+        'session-id': decodeURIComponent(compareMatch[1])
+      }
+    };
+  }
+
+  const explainMatch = pathname.match(/^\/cli\/sessions\/([^/]+)\/explain$/);
+  if (explainMatch) {
+    return {
+      command: 'why-did-this-change',
+      options: {
+        'session-id': decodeURIComponent(explainMatch[1])
+      }
+    };
+  }
+
+  const showMatch = pathname.match(/^\/cli\/sessions\/([^/]+)$/);
+  if (showMatch) {
+    return {
+      command: 'session-show',
+      options: {
+        id: decodeURIComponent(showMatch[1])
+      }
+    };
+  }
+
+  return null;
+}
+
+async function readJsonBody(request) {
+  const chunks = [];
+  let totalSize = 0;
+  for await (const chunk of request) {
+    totalSize += chunk.length;
+    if (totalSize > MAX_BODY_BYTES) {
+      throw new Error('Request body too large.');
+    }
+    chunks.push(chunk);
+  }
+
+  const raw = Buffer.concat(chunks).toString('utf8');
+  if (!raw.trim()) {
+    throw new Error('Request body is required.');
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch {
+    throw new Error('Invalid JSON in request body.');
+  }
+}
+
+async function readUrlEncodedBody(request) {
+  const chunks = [];
+  let totalSize = 0;
+  for await (const chunk of request) {
+    totalSize += chunk.length;
+    if (totalSize > MAX_BODY_BYTES) {
+      throw new Error('Request body too large.');
+    }
+    chunks.push(chunk);
+  }
+
+  const raw = Buffer.concat(chunks).toString('utf8');
+  if (!raw.trim()) {
+    throw new Error('Request body is required.');
+  }
+
+  return Object.fromEntries(new URLSearchParams(raw));
+}
+
+function html(response, statusCode, markup) {
+  response.writeHead(statusCode, { 'content-type': 'text/html; charset=utf-8' });
+  response.end(markup);
+}
+
+function deviceApprovalPage({
+  title,
+  message,
+  userCode = '',
+  email = '',
+  userId = '',
+  includeManualForm = true,
+  appleStartPath = null,
+  googleStartPath = null,
+  isError = false
+}) {
+  const escapedTitle = escapeHtml(title);
+  const escapedMessage = escapeHtml(message);
+  const escapedUserCode = escapeHtml(userCode);
+  const escapedEmail = escapeHtml(email);
+  const escapedUserId = escapeHtml(userId);
+  const accent = isError ? '#7f1d1d' : '#16324f';
+  const panel = isError ? '#fef2f2' : '#f6fbff';
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>${escapedTitle}</title>
+    <style>
+      :root {
+        color-scheme: light;
+        font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", sans-serif;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        background: linear-gradient(180deg, #f7fbff 0%, #edf4ff 100%);
+        color: #12212f;
+      }
+      main {
+        width: min(92vw, 28rem);
+        background: white;
+        border-radius: 24px;
+        box-shadow: 0 18px 50px rgba(17, 38, 57, 0.12);
+        padding: 1.5rem;
+      }
+      .badge {
+        display: inline-block;
+        padding: 0.35rem 0.65rem;
+        border-radius: 999px;
+        background: ${panel};
+        color: ${accent};
+        font-size: 0.85rem;
+        font-weight: 600;
+      }
+      h1 {
+        margin: 0.9rem 0 0.5rem;
+        font-size: 1.6rem;
+        line-height: 1.2;
+      }
+      p {
+        margin: 0 0 1rem;
+        color: #41576d;
+      }
+      form {
+        display: grid;
+        gap: 0.85rem;
+        margin-top: 1rem;
+      }
+      .actions {
+        display: grid;
+        gap: 0.75rem;
+      }
+      .oauth-link {
+        display: block;
+        text-align: center;
+        text-decoration: none;
+        border-radius: 14px;
+        background: #ffffff;
+        color: #12212f;
+        border: 1px solid #d0dded;
+        font-weight: 700;
+        padding: 0.9rem 1rem;
+      }
+      label {
+        display: grid;
+        gap: 0.35rem;
+        font-size: 0.95rem;
+        font-weight: 600;
+      }
+      input {
+        border: 1px solid #d0dded;
+        border-radius: 12px;
+        padding: 0.8rem 0.9rem;
+        font: inherit;
+      }
+      button {
+        margin-top: 0.4rem;
+        border: 0;
+        border-radius: 14px;
+        background: #0f4c81;
+        color: white;
+        font: inherit;
+        font-weight: 700;
+        padding: 0.9rem 1rem;
+      }
+      small {
+        color: #66798b;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <span class="badge">incremnt device login</span>
+      <h1>${escapedTitle}</h1>
+      <p>${escapedMessage}</p>
+      ${(appleStartPath || googleStartPath) ? `
+      <div class="actions">
+        ${appleStartPath ? `<a class="oauth-link" href="${escapeHtml(appleStartPath)}">Continue with Apple</a>` : ''}
+        ${googleStartPath ? `<a class="oauth-link" href="${escapeHtml(googleStartPath)}">Continue with Google</a>` : ''}
+      </div>
+      ` : ''}
+      ${includeManualForm ? `
+      <form method="post" action="/auth/device/approve">
+        <label>
+          Approval code
+          <input name="userCode" value="${escapedUserCode}" autocapitalize="characters" autocomplete="one-time-code" required />
+        </label>
+        <label>
+          Email
+          <input name="email" type="email" value="${escapedEmail}" autocomplete="email" />
+        </label>
+        <label>
+          User ID
+          <input name="userId" value="${escapedUserId}" />
+        </label>
+        <button type="submit">Approve login</button>
+      </form>
+      <small>Enter the code shown by <code>incremnt login</code>. Provide either the email or user ID for the account that should own this session.</small>
+      ` : `
+      <small>Continue with a configured identity provider to approve the code shown by <code>incremnt login</code>.</small>
+      `}
+    </main>
+  </body>
+</html>`;
+}
+
+function deviceApprovalSuccessPage({ email, userId }) {
+  const displayName = escapeHtml(email || userId || 'your account');
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Connected</title>
+    <style>
+      :root {
+        color-scheme: light;
+        font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Helvetica Neue", sans-serif;
+      }
+      body {
+        margin: 0;
+        min-height: 100vh;
+        display: grid;
+        place-items: center;
+        background: linear-gradient(180deg, #f7fbff 0%, #edf4ff 100%);
+        color: #12212f;
+      }
+      main {
+        width: min(92vw, 28rem);
+        background: white;
+        border-radius: 24px;
+        box-shadow: 0 18px 50px rgba(17, 38, 57, 0.12);
+        padding: 2rem 1.5rem;
+        text-align: center;
+      }
+      .checkmark {
+        font-size: 3rem;
+        margin-bottom: 0.5rem;
+      }
+      h1 {
+        margin: 0 0 0.5rem;
+        font-size: 1.6rem;
+        line-height: 1.2;
+      }
+      p {
+        margin: 0;
+        color: #41576d;
+      }
+    </style>
+  </head>
+  <body>
+    <main>
+      <div class="checkmark">&#x2705;</div>
+      <h1>You're all set</h1>
+      <p>Signed in as ${displayName}. You can close this tab and return to your terminal.</p>
+    </main>
+  </body>
+</html>`;
+}
+
+function escapeHtml(value) {
+  return String(value ?? '')
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+    .replaceAll("'", '&#39;');
+}
+
+export function syncServiceContractPayload({
+  auth = {
+    tokenBootstrap: true,
+    deviceFlow: false,
+    browserApproval: false,
+    devEmail: false
+  },
+  providers = {
+    apple: {
+      available: true,
+      configured: false
+    },
+    google: {
+      available: true,
+      configured: false
+    }
+  }
+} = {}) {
+  return {
+    contractVersion,
+    binary: 'incremnt',
+    capabilities: {
+      ...cliCapabilities,
+      localSnapshots: false,
+      remoteReads: true,
+      remoteBootstrap: false
+    },
+    auth,
+    providers,
+    officialCommands
+  };
+}
+
+export function createSyncServiceRequestHandler({
+  loadSnapshot,
+  token,
+  authenticateToken,
+  authenticateReadToken,
+  authenticateWriteToken,
+  loadSnapshotForAccount,
+  writeSnapshotForAccount,
+  issueDevLogin,
+  issueSession,
+  issueDeviceChallenge,
+  consumeDeviceChallenge,
+  readDeviceChallengeByUserCode,
+  approveDeviceChallenge,
+  completeGoogleDeviceApproval,
+  adminBootstrapSecret,
+  bootstrapAccount,
+  appleAuth = {
+    available: true,
+    configured: false
+  },
+  buildAppleAuthUrl = null,
+  completeAppleDeviceApproval,
+  googleAuth = {
+    available: true,
+    configured: false
+  },
+  buildGoogleAuthUrl = null,
+  refreshSession,
+  allowManualDeviceApproval = false,
+  rateLimitConfig = null
+}) {
+  const rateLimiter = createRateLimiter(rateLimitConfig ?? {});
+
+  return async function handle(request, response) {
+    try {
+      const url = new URL(request.url ?? '/', `http://${request.headers.host ?? '127.0.0.1'}`);
+      const route = routeRequest(url);
+      if (!route) {
+        notFound(response);
+        return;
+      }
+
+      if (route.command === 'healthz') {
+        json(response, 200, { ok: true });
+        return;
+      }
+
+      if (!rateLimiter.check(request, route.command).allowed) {
+        json(response, 429, { error: 'Too many requests' });
+        return;
+      }
+
+      logRequest(request, '-', route.command);
+
+      const providerApprovalAvailable = Boolean(appleAuth?.configured || googleAuth?.configured);
+      const manualDeviceApprovalEnabled = allowManualDeviceApproval || !providerApprovalAvailable;
+
+      if (route.command === 'auth-config') {
+        json(response, 200, {
+          ok: true,
+          auth: {
+            tokenBootstrap: Boolean(issueSession || token),
+            deviceFlow: Boolean(issueDeviceChallenge && consumeDeviceChallenge),
+            browserApproval: Boolean(approveDeviceChallenge),
+            devEmail: Boolean(issueDevLogin)
+          },
+          providers: {
+            apple: {
+              available: Boolean(appleAuth?.available),
+              configured: Boolean(appleAuth?.configured)
+            },
+            google: {
+              available: Boolean(googleAuth?.available),
+              configured: Boolean(googleAuth?.configured)
+            }
+          }
+        });
+        return;
+      }
+
+      if (route.command === 'dev-login') {
+        if (request.method !== 'POST') {
+          methodNotAllowed(response, 'Use POST for /auth/dev-login.');
+          return;
+        }
+
+        if (!issueDevLogin) {
+          methodNotAllowed(response, 'Dev login is not enabled for this service mode.');
+          return;
+        }
+
+        try {
+          const body = await readJsonBody(request);
+          if (!body.email && !body.userId) {
+            badRequest(response, 'email or userId is required.');
+            return;
+          }
+
+          const result = await issueDevLogin({
+            email: body.email ?? null,
+            userId: body.userId ?? null
+          });
+          json(response, 200, {
+            ok: true,
+            token: result.token,
+            account: result.account
+          });
+          return;
+        } catch (error) {
+          badRequest(response, error.message);
+          return;
+        }
+      }
+
+      if (route.command === 'device-start') {
+        if (request.method !== 'POST') {
+          methodNotAllowed(response, 'Use POST for /auth/device/start.');
+          return;
+        }
+
+        if (!issueDeviceChallenge) {
+          methodNotAllowed(response, 'Device login is not enabled for this service mode.');
+          return;
+        }
+
+        const challenge = await issueDeviceChallenge();
+        json(response, 200, {
+          ok: true,
+          deviceCode: challenge.deviceCode,
+          userCode: challenge.userCode,
+          expiresAt: challenge.expiresAt,
+          intervalSeconds: challenge.intervalSeconds,
+          verificationUri: '/auth/device/approve'
+        });
+        return;
+      }
+
+      if (route.command === 'device-poll') {
+        if (request.method !== 'POST') {
+          methodNotAllowed(response, 'Use POST for /auth/device/poll.');
+          return;
+        }
+
+        if (!consumeDeviceChallenge) {
+          methodNotAllowed(response, 'Device login is not enabled for this service mode.');
+          return;
+        }
+
+        try {
+          const body = await readJsonBody(request);
+          if (!body.deviceCode) {
+            badRequest(response, 'deviceCode is required.');
+            return;
+          }
+
+          const result = await consumeDeviceChallenge(body.deviceCode);
+          if (result.status === 'pending') {
+            json(response, 202, {
+              ok: false,
+              error: 'authorization_pending',
+              intervalSeconds: result.intervalSeconds ?? 1
+            });
+            return;
+          }
+
+          if (result.status === 'expired') {
+            json(response, 410, { ok: false, error: 'expired_token' });
+            return;
+          }
+
+          if (result.status === 'not_found') {
+            badRequest(response, 'Unknown deviceCode.');
+            return;
+          }
+
+          json(response, 200, {
+            ok: true,
+            session: {
+              accessToken: result.session.accessToken,
+              expiresAt: result.session.expiresAt
+            },
+            account: result.session.account
+          });
+          return;
+        } catch (error) {
+          badRequest(response, error.message);
+          return;
+        }
+      }
+
+      if (route.command === 'google-start') {
+        if (request.method !== 'GET') {
+          methodNotAllowed(response, 'Use GET for /auth/google/start.');
+          return;
+        }
+
+        if (!googleAuth?.configured || !buildGoogleAuthUrl || !readDeviceChallengeByUserCode) {
+          methodNotAllowed(response, 'Google auth is not enabled for this service mode.');
+          return;
+        }
+
+        const userCode = url.searchParams.get('userCode') ?? '';
+        const challenge = await readDeviceChallengeByUserCode(userCode);
+        if (!challenge) {
+          badRequest(response, 'Unknown or expired userCode.');
+          return;
+        }
+
+        response.writeHead(302, {
+          location: buildGoogleAuthUrl(googleAuth, {
+            userCode: challenge.userCode,
+            nonce: challenge.oauthStateNonce
+          })
+        });
+        response.end();
+        return;
+      }
+
+      if (route.command === 'google-callback') {
+        if (request.method !== 'GET') {
+          methodNotAllowed(response, 'Use GET for /auth/google/callback.');
+          return;
+        }
+
+        if (!googleAuth?.configured || !completeGoogleDeviceApproval) {
+          methodNotAllowed(response, 'Google auth is not enabled for this service mode.');
+          return;
+        }
+
+        const code = url.searchParams.get('code') ?? '';
+        const state = url.searchParams.get('state') ?? '';
+        if (!code || !state) {
+          badRequest(response, 'code and state are required.');
+          return;
+        }
+
+        try {
+          const result = await completeGoogleDeviceApproval({ code, state });
+          html(response, 200, deviceApprovalSuccessPage({
+            email: result.account.email ?? '',
+            userId: result.account.id
+          }));
+          return;
+        } catch (error) {
+          html(response, 400, deviceApprovalPage({
+            title: 'Approval failed',
+            message: error.message,
+            isError: true
+          }));
+          return;
+        }
+      }
+
+      if (route.command === 'apple-start') {
+        if (request.method !== 'GET') {
+          methodNotAllowed(response, 'Use GET for /auth/apple/start.');
+          return;
+        }
+
+        if (!appleAuth?.configured || !buildAppleAuthUrl || !readDeviceChallengeByUserCode) {
+          methodNotAllowed(response, 'Apple auth is not enabled for this service mode.');
+          return;
+        }
+
+        const userCode = url.searchParams.get('userCode') ?? '';
+        const challenge = await readDeviceChallengeByUserCode(userCode);
+        if (!challenge) {
+          badRequest(response, 'Unknown or expired userCode.');
+          return;
+        }
+
+        response.writeHead(302, {
+          location: buildAppleAuthUrl(appleAuth, {
+            userCode: challenge.userCode,
+            nonce: challenge.oauthStateNonce
+          })
+        });
+        response.end();
+        return;
+      }
+
+      if (route.command === 'apple-callback') {
+        if (request.method !== 'GET' && request.method !== 'POST') {
+          methodNotAllowed(response, 'Use GET or POST for /auth/apple/callback.');
+          return;
+        }
+
+        if (!appleAuth?.configured || !completeAppleDeviceApproval) {
+          methodNotAllowed(response, 'Apple auth is not enabled for this service mode.');
+          return;
+        }
+
+        let code = url.searchParams.get('code') ?? '';
+        let state = url.searchParams.get('state') ?? '';
+        if (request.method === 'POST') {
+          const body = await readUrlEncodedBody(request);
+          code = body.code ?? code;
+          state = body.state ?? state;
+        }
+
+        if (!code || !state) {
+          badRequest(response, 'code and state are required.');
+          return;
+        }
+
+        try {
+          const result = await completeAppleDeviceApproval({ code, state });
+          html(response, 200, deviceApprovalSuccessPage({
+            email: result.account.email ?? '',
+            userId: result.account.id
+          }));
+          return;
+        } catch (error) {
+          console.error('Apple device approval failed', {
+            message: error?.message ?? String(error),
+            method: request.method,
+            hasCode: Boolean(code),
+            hasState: Boolean(state)
+          });
+          html(response, 400, deviceApprovalPage({
+            title: 'Approval failed',
+            message: error.message,
+            isError: true
+          }));
+          return;
+        }
+      }
+
+      if (route.command === 'device-approve') {
+        if (!approveDeviceChallenge) {
+          methodNotAllowed(response, 'Device approval is not enabled for this service mode.');
+          return;
+        }
+
+        if (request.method === 'GET') {
+          html(response, 200, deviceApprovalPage({
+            title: 'Approve incremnt login',
+            message: 'Enter the approval code shown by the CLI and the account identity that should own the session.',
+            userCode: url.searchParams.get('userCode') ?? '',
+            email: url.searchParams.get('email') ?? '',
+            userId: url.searchParams.get('userId') ?? '',
+            includeManualForm: manualDeviceApprovalEnabled,
+            appleStartPath: appleAuth?.configured
+              ? `/auth/apple/start?userCode=${encodeURIComponent(url.searchParams.get('userCode') ?? '')}`
+              : null,
+            googleStartPath: googleAuth?.configured
+              ? `/auth/google/start?userCode=${encodeURIComponent(url.searchParams.get('userCode') ?? '')}`
+              : null
+          }));
+          return;
+        }
+
+        if (request.method !== 'POST') {
+          methodNotAllowed(response, 'Use GET or POST for /auth/device/approve.');
+          return;
+        }
+
+        if (!manualDeviceApprovalEnabled) {
+          methodNotAllowed(response, 'Manual device approval is disabled for this service.');
+          return;
+        }
+
+        try {
+          const contentType = request.headers['content-type'] ?? '';
+          const body = contentType.includes('application/json')
+            ? await readJsonBody(request)
+            : await readUrlEncodedBody(request);
+          const result = await approveDeviceChallenge({
+            deviceCode: body.deviceCode ?? null,
+            userCode: body.userCode ?? body.user_code ?? null,
+            userId: body.userId ?? body.user_id ?? null,
+            email: body.email ?? null
+          });
+
+          if (contentType.includes('application/json')) {
+            json(response, 200, {
+              ok: true,
+              deviceCode: result.deviceCode,
+              userCode: result.userCode,
+              account: result.account,
+              expiresAt: result.expiresAt
+            });
+            return;
+          }
+
+          html(response, 200, deviceApprovalPage({
+            title: 'Login approved',
+            message: `The session for ${result.account.email ?? result.account.id} is ready. Return to the CLI to finish login.`,
+            userCode: result.userCode,
+            email: result.account.email ?? '',
+            userId: result.account.id
+          }));
+          return;
+        } catch (error) {
+          html(response, 400, deviceApprovalPage({
+            title: 'Approval failed',
+            message: error.message,
+            userCode: url.searchParams.get('userCode') ?? '',
+            email: url.searchParams.get('email') ?? '',
+            userId: url.searchParams.get('userId') ?? '',
+            isError: true
+          }));
+          return;
+        }
+      }
+
+      if (route.command === 'admin-bootstrap-user') {
+        if (request.method !== 'POST') {
+          methodNotAllowed(response, 'Use POST for /admin/bootstrap-user.');
+          return;
+        }
+
+        if (!adminBootstrapSecret || !bootstrapAccount) {
+          methodNotAllowed(response, 'Admin bootstrap is not enabled for this service mode.');
+          return;
+        }
+
+        if (!constantTimeEqual(adminSecret(request), adminBootstrapSecret)) {
+          unauthorized(response, request);
+          return;
+        }
+
+        try {
+          const body = await readJsonBody(request);
+          if (!body.userId) {
+            badRequest(response, 'userId is required.');
+            return;
+          }
+
+          if (!body.bootstrapToken) {
+            badRequest(response, 'bootstrapToken is required.');
+            return;
+          }
+
+          const result = await bootstrapAccount({
+            userId: body.userId,
+            email: body.email ?? null,
+            bootstrapToken: body.bootstrapToken,
+            snapshot: body.snapshot ?? null
+          });
+          json(response, 200, {
+            ok: true,
+            userId: result.userId,
+            email: result.email,
+            snapshotPath: result.snapshotPath
+          });
+          return;
+        } catch (error) {
+          badRequest(response, error.message);
+          return;
+        }
+      }
+
+      const requestToken = bearerToken(request);
+      if (route.command === 'session-login') {
+        if (request.method !== 'POST') {
+          methodNotAllowed(response, 'Use POST for /auth/session.');
+          return;
+        }
+
+        if (!requestToken) {
+          unauthorized(response, request);
+          return;
+        }
+
+        const session = issueSession
+          ? await issueSession(requestToken)
+          : requestToken === token
+            ? {
+                accessToken: token,
+                expiresAt: '2999-01-01T00:00:00Z',
+                account: { id: 'remote-user', email: null }
+              }
+            : null;
+
+        if (!session) {
+          unauthorized(response, request);
+          return;
+        }
+
+        json(response, 200, {
+          ok: true,
+          session: {
+            accessToken: session.accessToken,
+            expiresAt: session.expiresAt
+          },
+          account: session.account
+        });
+        return;
+      }
+
+      if (route.command === 'session-refresh') {
+        if (request.method !== 'POST') {
+          methodNotAllowed(response, 'Use POST for /auth/refresh.');
+          return;
+        }
+
+        if (!requestToken) {
+          unauthorized(response, request);
+          return;
+        }
+
+        if (!refreshSession) {
+          methodNotAllowed(response, 'Session refresh is not enabled for this service mode.');
+          return;
+        }
+
+        const result = await refreshSession(requestToken);
+        if (!result) {
+          unauthorized(response, request);
+          return;
+        }
+
+        json(response, 200, {
+          ok: true,
+          session: {
+            accessToken: result.accessToken,
+            expiresAt: result.expiresAt
+          },
+          account: result.account
+        });
+        return;
+      }
+
+      const readAuthenticator = authenticateReadToken ?? authenticateToken;
+      const writeAuthenticator = authenticateWriteToken ?? authenticateToken;
+
+      if (route.command === 'contract') {
+        const account = readAuthenticator
+          ? await readAuthenticator(requestToken)
+          : requestToken === token
+            ? { id: 'remote-user', email: null }
+            : null;
+        if (!account) {
+          unauthorized(response, request);
+          return;
+        }
+        json(response, 200, syncServiceContractPayload({
+          auth: {
+            tokenBootstrap: Boolean(issueSession || token),
+            deviceFlow: Boolean(issueDeviceChallenge && consumeDeviceChallenge),
+            browserApproval: Boolean(approveDeviceChallenge),
+            devEmail: Boolean(issueDevLogin)
+          }
+        }));
+        return;
+      }
+
+      if (route.command === 'sync-upload') {
+        if (request.method !== 'POST' && request.method !== 'PUT') {
+          methodNotAllowed(response, 'Use POST or PUT for /sync/snapshot.');
+          return;
+        }
+
+        if (!writeSnapshotForAccount) {
+          methodNotAllowed(response, 'Snapshot uploads are not enabled for this service mode.');
+          return;
+        }
+
+        const account = writeAuthenticator
+          ? await writeAuthenticator(requestToken)
+          : requestToken === token
+            ? { id: 'remote-user', email: null }
+            : null;
+        if (!account) {
+          unauthorized(response, request);
+          return;
+        }
+
+        try {
+          const snapshot = await readJsonBody(request);
+          if (
+            !snapshot ||
+            typeof snapshot !== 'object' ||
+            !Array.isArray(snapshot.sessions)
+          ) {
+            badRequest(
+              response,
+              'Invalid snapshot: must be an object with a sessions array'
+            );
+            return;
+          }
+          const result = await writeSnapshotForAccount(account, snapshot);
+          const sessionCount = snapshot.sessions?.length ?? 0;
+          console.log(`snapshot uploaded (${sessionCount} sessions)`);
+          json(response, 200, {
+            ok: true,
+            userId: account.id,
+            snapshotPath: result.snapshotPath
+          });
+          return;
+        } catch (error) {
+          badRequest(response, error.message);
+          return;
+        }
+      }
+
+      const account = readAuthenticator
+        ? await readAuthenticator(requestToken)
+        : requestToken === token
+          ? { id: 'remote-user', email: null }
+          : null;
+      if (!account) {
+        unauthorized(response, request);
+        return;
+      }
+
+      let snapshot;
+      try {
+        snapshot = loadSnapshotForAccount
+          ? await loadSnapshotForAccount(account)
+          : await loadSnapshot();
+      } catch {
+        snapshot = { sessions: [], programs: [], activeProgramId: null };
+      }
+      const result = executeReadCommand(snapshot, route.command, route.options);
+      if (!result.ok) {
+        if (result.error.startsWith('Session not found')) {
+          notFound(response, result.error);
+          return;
+        }
+
+        badRequest(response, result.error);
+        return;
+      }
+
+      json(response, 200, result.payload);
+    } catch (error) {
+      internalError(response, error);
+    }
+  };
+}