@pi-chamber/web 0.1.8

package/server/index.js

@@ -0,0 +1,206 @@
+import 'reflect-metadata';
+import compression from 'compression';
+import express from 'express';
+import fs from 'node:fs';
+import http from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { createClientPairingRuntime } from './lib/client-auth/pairing.js';
+import { createRemoteClientAuthRuntime } from './lib/client-auth/remote-clients.js';
+import { resolvePiChamberDataDir } from './lib/pichamber-data-dir.js';
+import { registerPiRuntimeRoutes } from './lib/pi/routes.js';
+import { registerWorkspaceIntegrations } from './lib/workspace/host.js';
+import { createPiSessionDaemonSupervisor } from './lib/pi/session-daemon/supervisor.js';
+import {
+  getUnauthenticatedLanErrorMessage,
+  isNetworkExposedBindHost,
+  isUnsafeUnauthenticatedLanAllowed,
+} from './lib/security/bind-host.js';
+import { applyUiCorsHeaders } from './lib/server/cors.js';
+import { createPairingTransportResolvers } from './lib/server/lan-addresses.js';
+import { parseServeCliOptions } from './lib/server/cli-options.js';
+import { runCliEntryIfMain } from './lib/server/cli-entry-runtime.js';
+import {
+  registerAuthAndAccessRoutes,
+  registerCommonRequestMiddleware,
+  registerServerStatusRoutes,
+} from './lib/server/core-routes.js';
+import { createTunnelAuth } from './lib/server/tunnel-auth.js';
+import { createUiAuth } from './lib/ui-auth/ui-auth.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DEFAULT_PORT = 3000;
+const PICHAMBER_DATA_DIR = resolvePiChamberDataDir();
+const PICHAMBER_VERSION = (() => {
+  try {
+    return JSON.parse(fs.readFileSync(path.resolve(__dirname, '..', 'package.json'), 'utf8')).version || 'unknown';
+  } catch {
+    return 'unknown';
+  }
+})();
+
+let activeController = null;
+let signalsAttached = false;
+
+const isEnvFlagEnabled = (value) => value === true || value === 1 || (typeof value === 'string' && ['1', 'true'].includes(value.trim().toLowerCase()));
+
+const resolveDistPath = () => {
+  const configured = typeof process.env.PICHAMBER_DIST_DIR === 'string' ? process.env.PICHAMBER_DIST_DIR.trim() : '';
+  return configured ? path.resolve(configured) : path.join(__dirname, '..', 'dist');
+};
+
+const registerStaticRoutes = (app, { apiOnly }) => {
+  if (apiOnly) {
+    app.get(/^(?!\/api|\/auth|\/health).*/, (_req, res) => res.status(200).type('text/plain').send('PiChamber API-only server is running.'));
+    return;
+  }
+  const distPath = resolveDistPath();
+  if (!fs.existsSync(distPath)) {
+    app.get(/.*/, (_req, res) => res.status(404).send('Static files not found. Please build the application first.'));
+    return;
+  }
+  app.use(express.static(distPath, {
+    setHeaders(res, filePath) {
+      if (filePath.endsWith(`${path.sep}sw.js`)) res.setHeader('Cache-Control', 'no-store');
+    },
+  }));
+  app.get(/^(?!\/api|\/auth|\/health|.*\.(js|css|svg|png|jpg|jpeg|gif|ico|woff|woff2|ttf|eot|map)).*$/, (_req, res) => {
+    res.sendFile(path.join(distPath, 'index.html'));
+  });
+};
+
+const listen = (server, port, host) => new Promise((resolve, reject) => {
+  const onError = (error) => { server.off('listening', onListening); reject(error); };
+  const onListening = () => { server.off('error', onError); resolve(); };
+  server.once('error', onError);
+  server.once('listening', onListening);
+  server.listen(port, host);
+});
+
+const close = (server) => new Promise((resolve, reject) => {
+  server.close((error) => error ? reject(error) : resolve());
+});
+
+export async function gracefulShutdown({ exitProcess = false } = {}) {
+  const controller = activeController;
+  if (!controller) return;
+  await controller.stop({ exitProcess });
+}
+
+export async function startWebUiServer(options = {}) {
+  const port = Number.isInteger(options.port) && options.port >= 0 ? options.port : DEFAULT_PORT;
+  const host = typeof options.host === 'string' && options.host.trim() ? options.host.trim() : (process.env.PICHAMBER_HOST || process.env.PICHAMBER_HOST || '127.0.0.1');
+  const uiPassword = typeof options.uiPassword === 'string' ? options.uiPassword : (process.env.PICHAMBER_UI_PASSWORD || process.env.PICHAMBER_UI_PASSWORD || null);
+  if (isNetworkExposedBindHost(host) && !uiPassword?.trim() && !isUnsafeUnauthenticatedLanAllowed(process.env)) {
+    throw new Error(getUnauthenticatedLanErrorMessage(host));
+  }
+  const apiOnly = options.apiOnly === true || isEnvFlagEnabled(process.env.PICHAMBER_API_ONLY ?? process.env.PICHAMBER_API_ONLY);
+  const app = express();
+  const server = http.createServer(app);
+  const pairingTransports = createPairingTransportResolvers({
+    getPort: () => {
+      const address = server.address();
+      return typeof address === 'object' && address ? address.port : null;
+    },
+    bindHost: host,
+  });
+  const serverStartedAt = new Date().toISOString();
+  const dataPath = (name) => path.join(PICHAMBER_DATA_DIR, name);
+  const remoteClientAuthRuntime = createRemoteClientAuthRuntime({ fsPromises: fs.promises, path, crypto: await import('node:crypto'), storePath: dataPath('remote-clients.json') });
+  const clientPairingRuntime = createClientPairingRuntime({ fsPromises: fs.promises, path, crypto: await import('node:crypto'), storePath: dataPath('client-pairing-sessions.json'), remoteClientAuthRuntime });
+  const tunnelAuthController = createTunnelAuth();
+  const uiAuthController = createUiAuth({ password: uiPassword, readSettingsFromDiskMigrated: async () => ({}) , clientAuthController: remoteClientAuthRuntime });
+  const piSessionDaemonRuntime = createPiSessionDaemonSupervisor({ dataDir: PICHAMBER_DATA_DIR });
+  let stopped = false;
+
+  app.set('trust proxy', true);
+  app.use((_req, res, next) => { res.setHeader('X-Robots-Tag', 'noindex, nofollow'); next(); });
+  app.get('/robots.txt', (_req, res) => res.type('text/plain').send('User-agent: *\nDisallow: /\n'));
+  app.use((req, res, next) => {
+    if (applyUiCorsHeaders(req, res)) return res.status(204).end();
+    next();
+  });
+  app.use(compression({ filter: (req, res) => req.path === '/api/pi/events' || req.headers.accept?.includes('text/event-stream') ? false : compression.filter(req, res) }));
+
+  registerServerStatusRoutes(app, {
+    express,
+    process,
+    pichamberVersion: PICHAMBER_VERSION,
+    runtimeName: process.env.PICHAMBER_RUNTIME || 'web',
+    serverStartedAt,
+    gracefulShutdown,
+    getHealthSnapshot: () => ({ pi: { state: 'ready' }, apiOnly }),
+    getServerPort: () => {
+      const address = server.address();
+      return typeof address === 'object' && address ? address.port : null;
+    },
+    getTunnelUrl: () => null,
+    getServerId: async () => null,
+    tunnelAuthController,
+    uiAuthController,
+  });
+  registerCommonRequestMiddleware(app, { express, verboseRequestLogs: isEnvFlagEnabled(process.env.PICHAMBER_VERBOSE_REQUEST_LOGS) });
+  registerAuthAndAccessRoutes(app, {
+    express,
+    tunnelAuthController,
+    uiAuthController,
+    remoteClientAuthRuntime,
+    clientPairingRuntime,
+    readSettingsFromDiskMigrated: async () => ({}),
+    normalizeTunnelSessionTtlMs: () => 8 * 60 * 60 * 1000,
+    getPairingTransports: () => pairingTransports.getPairingTransports(),
+    getDirectCandidateUrls: () => pairingTransports.getDirectCandidateUrls(),
+    getServerId: async () => null,
+    getServerLabel: () => os.hostname() || 'PiChamber',
+  });
+  registerPiRuntimeRoutes(app, { getPiSessionDaemonRuntime: () => piSessionDaemonRuntime });
+  registerWorkspaceIntegrations({ app, server, express, uiAuthController });
+  registerStaticRoutes(app, { apiOnly });
+
+  await listen(server, port, host);
+  const resolvedPort = typeof server.address() === 'object' && server.address() ? server.address().port : null;
+  if (typeof resolvedPort === 'number') process.send?.({ type: 'pichamber:ready', port: resolvedPort });
+  await piSessionDaemonRuntime.start().catch((error) => console.warn(`[PiSessionDaemon] unavailable: ${error?.code ?? 'DAEMON_UNAVAILABLE'}`));
+  const controller = {
+    expressApp: app,
+    httpServer: server,
+    getPort: () => {
+      const address = server.address();
+      return typeof address === 'object' && address ? address.port : null;
+    },
+    getTunnelUrl: () => null,
+    getQuitRiskStatus: () => ({ tunnel: { active: false } }),
+    isReady: () => !stopped,
+    stop: async ({ exitProcess = false } = {}) => {
+      if (stopped) return;
+      stopped = true;
+      if (activeController === controller) activeController = null;
+      await Promise.allSettled([piSessionDaemonRuntime.stop(), close(server)]);
+      uiAuthController.dispose?.();
+      if (exitProcess) process.exit(0);
+    },
+  };
+  activeController = controller;
+  if (options.attachSignals !== false && !signalsAttached) {
+    signalsAttached = true;
+    for (const signal of ['SIGINT', 'SIGTERM']) process.once(signal, () => { void controller.stop({ exitProcess: options.exitOnShutdown === true }); });
+  }
+  console.log(`PiChamber listening on http://${host}:${controller.getPort()}`);
+  return controller;
+}
+
+runCliEntryIfMain({
+  process,
+  currentFilename: __filename,
+  parseServeCliOptions,
+  defaultPort: DEFAULT_PORT,
+  cloudflareProvider: 'cloudflare',
+  managedLocalMode: 'managed-local',
+  setExitOnShutdown: () => {},
+  startServer: startWebUiServer,
+});
+
+export const parseArgs = (argv = []) => parseServeCliOptions({ argv, env: process.env, defaultPort: DEFAULT_PORT, cloudflareProvider: 'cloudflare', managedLocalMode: 'managed-local' });

package/server/lib/client-auth/pairing.js

@@ -0,0 +1,308 @@
+const STORE_VERSION = 1;
+const PAIRING_ID_PREFIX = 'pair_';
+const SECRET_BYTES = 32;
+const FINGERPRINT_BYTES = 4;
+const DEFAULT_TTL_MS = 10 * 60 * 1000;
+const MAX_LABEL_LENGTH = 80;
+const VALID_CLIENT_KINDS = new Set(['mobile', 'desktop']);
+const GENERIC_REDEEM_ERROR = 'Invalid or expired pairing session';
+
+const normalizeOptionalString = (value) => {
+  if (typeof value !== 'string') return null;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+// Placeholder shown in the pending-devices list when the operator did not type a
+// name. It is a DISPLAY default only — the stored label stays null so redeem can
+// fall back to the device's own reported name instead of this placeholder.
+const PAIRING_LABEL_PLACEHOLDER = 'Pair new device';
+
+// The operator's typed device label, capped. Returns null when unset so callers
+// can distinguish "no name given" from a real name.
+const normalizeStoredLabel = (value) => {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized) return null;
+  return normalized.length > MAX_LABEL_LENGTH ? normalized.slice(0, MAX_LABEL_LENGTH) : normalized;
+};
+
+const normalizeTimestamp = (value) => {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized) return null;
+  const time = Date.parse(normalized);
+  return Number.isFinite(time) ? new Date(time).toISOString() : null;
+};
+
+const normalizeClientKind = (value) => {
+  const normalized = normalizeOptionalString(value);
+  return normalized && VALID_CLIENT_KINDS.has(normalized) ? normalized : null;
+};
+
+const normalizeAllowedClientKinds = (value) => {
+  if (!Array.isArray(value)) return ['mobile', 'desktop'];
+  const kinds = value.map(normalizeClientKind).filter(Boolean);
+  return kinds.length > 0 ? Array.from(new Set(kinds)) : ['mobile', 'desktop'];
+};
+
+const safeJsonParse = (raw) => {
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+};
+
+const constantTimeEqual = (left, right, crypto) => {
+  if (typeof left !== 'string' || typeof right !== 'string') return false;
+  const leftBuffer = Buffer.from(left, 'hex');
+  const rightBuffer = Buffer.from(right, 'hex');
+  if (leftBuffer.length !== rightBuffer.length) return false;
+  return crypto.timingSafeEqual(leftBuffer, rightBuffer);
+};
+
+const publicSession = (session) => ({
+  id: session.id,
+  createdAt: session.createdAt,
+  expiresAt: session.expiresAt,
+  usedAt: session.usedAt,
+  cancelledAt: session.cancelledAt,
+  clientId: session.clientId,
+  label: session.label || PAIRING_LABEL_PLACEHOLDER,
+  fingerprint: session.fingerprint,
+  allowedClientKinds: session.allowedClientKinds,
+  createdByClientId: session.createdByClientId,
+  usesRelay: session.usesRelay === true,
+});
+
+// A pending session is one that can still be redeemed: not used, not cancelled,
+// not expired.
+const isPendingSession = (session) => !session.usedAt
+  && !session.cancelledAt
+  && Number.isFinite(Date.parse(session.expiresAt))
+  && Date.parse(session.expiresAt) > Date.now();
+
+const redeemError = () => {
+  const error = new Error(GENERIC_REDEEM_ERROR);
+  error.statusCode = 400;
+  return error;
+};
+
+export const createClientPairingRuntime = ({
+  fsPromises,
+  path,
+  crypto,
+  storePath,
+  remoteClientAuthRuntime,
+  ttlMs = DEFAULT_TTL_MS,
+} = {}) => {
+  if (!fsPromises || !path || !crypto || !storePath || !remoteClientAuthRuntime) {
+    throw new Error('createClientPairingRuntime requires fsPromises, path, crypto, storePath, and remoteClientAuthRuntime');
+  }
+
+  const nowIso = () => new Date().toISOString();
+  const hashSecret = (secret) => crypto.createHash('sha256').update(secret).digest('hex');
+  const generateId = () => `${PAIRING_ID_PREFIX}${crypto.randomBytes(12).toString('hex')}`;
+  const generateSecret = () => crypto.randomBytes(SECRET_BYTES).toString('base64url');
+  const generateFingerprint = () => crypto.randomBytes(FINGERPRINT_BYTES).toString('hex').toUpperCase().replace(/^(.{4})(.{4})$/, '$1-$2');
+  let storeMutationQueue = Promise.resolve();
+
+  const withStoreMutation = async (fn) => {
+    const previous = storeMutationQueue;
+    let release;
+    storeMutationQueue = new Promise((resolve) => {
+      release = resolve;
+    });
+    await previous;
+    try {
+      return await fn();
+    } finally {
+      release();
+    }
+  };
+
+  const normalizeStore = (payload) => ({
+    version: STORE_VERSION,
+    sessions: Array.isArray(payload?.sessions)
+      ? payload.sessions
+        .filter((session) => session && typeof session === 'object')
+        .map((session) => ({
+          id: typeof session.id === 'string' ? session.id : generateId(),
+          secretHash: typeof session.secretHash === 'string' ? session.secretHash : '',
+          createdAt: typeof session.createdAt === 'string' ? session.createdAt : nowIso(),
+          expiresAt: normalizeTimestamp(session.expiresAt) || new Date(Date.now() + ttlMs).toISOString(),
+          usedAt: normalizeTimestamp(session.usedAt),
+          cancelledAt: normalizeTimestamp(session.cancelledAt),
+          clientId: normalizeOptionalString(session.clientId),
+          label: normalizeStoredLabel(session.label),
+          fingerprint: normalizeOptionalString(session.fingerprint) || generateFingerprint(),
+          allowedClientKinds: normalizeAllowedClientKinds(session.allowedClientKinds),
+          createdByClientId: normalizeOptionalString(session.createdByClientId),
+          usesRelay: session.usesRelay === true,
+        }))
+        .filter((session) => session.secretHash.length > 0)
+      : [],
+  });
+
+  const readStore = async () => {
+    try {
+      const raw = await fsPromises.readFile(storePath, 'utf8');
+      return normalizeStore(safeJsonParse(raw));
+    } catch (error) {
+      if (error?.code === 'ENOENT') return normalizeStore(null);
+      throw error;
+    }
+  };
+
+  const writeStore = async (store) => {
+    await fsPromises.mkdir(path.dirname(storePath), { recursive: true, mode: 0o700 });
+    await fsPromises.writeFile(storePath, JSON.stringify(normalizeStore(store), null, 2), { mode: 0o600 });
+    if (typeof fsPromises.chmod === 'function') {
+      await fsPromises.chmod(storePath, 0o600).catch(() => {});
+    }
+  };
+
+  const sweepExpiredSessionsFromStore = (store) => {
+    const now = Date.now();
+    const cutoff = now - ttlMs;
+    store.sessions = store.sessions.filter((session) => {
+      const usedAt = Date.parse(session.usedAt || '');
+      const cancelledAt = Date.parse(session.cancelledAt || '');
+      const inactiveAt = Number.isFinite(usedAt) ? usedAt : cancelledAt;
+      if (Number.isFinite(inactiveAt)) return inactiveAt >= cutoff;
+      // Never used or cancelled: drop once the session itself has expired —
+      // it can no longer be redeemed and would otherwise sit in the store forever.
+      const expiresAt = Date.parse(session.expiresAt || '');
+      return !Number.isFinite(expiresAt) || expiresAt > now;
+    });
+  };
+
+  const createPairingSession = async ({ label, allowedClientKinds, createdByClientId, usesRelay } = {}) => {
+    return withStoreMutation(async () => {
+      const store = await readStore();
+      sweepExpiredSessionsFromStore(store);
+      const secret = generateSecret();
+      const session = {
+        id: generateId(),
+        secretHash: hashSecret(secret),
+        createdAt: nowIso(),
+        expiresAt: new Date(Date.now() + ttlMs).toISOString(),
+        usedAt: null,
+        cancelledAt: null,
+        clientId: null,
+        label: normalizeStoredLabel(label),
+        fingerprint: generateFingerprint(),
+        allowedClientKinds: normalizeAllowedClientKinds(allowedClientKinds),
+        createdByClientId: normalizeOptionalString(createdByClientId),
+        usesRelay: usesRelay === true,
+      };
+      store.sessions.push(session);
+      await writeStore(store);
+      return { pairing: { ...publicSession(session), secret } };
+    });
+  };
+
+  // Sessions that can still be redeemed (link created, device not yet connected).
+  const listPendingSessions = async () => withStoreMutation(async () => {
+    const store = await readStore();
+    return store.sessions.filter(isPendingSession).map(publicSession);
+  });
+
+  // Relay-transport demand from pairing: any still-redeemable relay session.
+  const hasActiveRelaySession = async () => withStoreMutation(async () => {
+    const store = await readStore();
+    return store.sessions.some((session) => session.usesRelay === true && isPendingSession(session));
+  });
+
+  const getPairingSession = async (id) => {
+    const normalizedId = normalizeOptionalString(id);
+    if (!normalizedId) return null;
+    return withStoreMutation(async () => {
+      const store = await readStore();
+      const session = store.sessions.find((entry) => entry.id === normalizedId);
+      return session ? publicSession(session) : null;
+    });
+  };
+
+  const cancelPairingSession = async (id) => {
+    const normalizedId = normalizeOptionalString(id);
+    if (!normalizedId) return { cancelled: false };
+    return withStoreMutation(async () => {
+      const store = await readStore();
+      const session = store.sessions.find((entry) => entry.id === normalizedId);
+      if (!session) return { cancelled: false };
+      if (!session.cancelledAt) session.cancelledAt = nowIso();
+      await writeStore(store);
+      return { cancelled: true, pairing: publicSession(session) };
+    });
+  };
+
+  const redeemPairingSession = async ({
+    pairingId,
+    secret,
+    clientLabel,
+    clientKind,
+    deviceName,
+    devicePlatform,
+    deviceModel,
+    appVersion,
+    dedupeKey,
+  } = {}) => {
+    const normalizedId = normalizeOptionalString(pairingId);
+    const normalizedSecret = normalizeOptionalString(secret);
+    const normalizedKind = normalizeClientKind(clientKind) || 'mobile';
+    if (!normalizedId || !normalizedSecret) throw redeemError();
+
+    return withStoreMutation(async () => {
+      const store = await readStore();
+      const session = store.sessions.find((entry) => entry.id === normalizedId);
+      if (!session) throw redeemError();
+      if (session.cancelledAt || session.usedAt) throw redeemError();
+      if (Date.parse(session.expiresAt) <= Date.now()) throw redeemError();
+      if (!session.allowedClientKinds.includes(normalizedKind)) throw redeemError();
+      if (!constantTimeEqual(session.secretHash, hashSecret(normalizedSecret), crypto)) throw redeemError();
+
+      // The operator's typed pairing label is THIS server's name for the device
+      // (shown in the device list). It wins over the device's self-reported
+      // label; fall back to that only when no pairing label was set.
+      const label = normalizeOptionalString(session.label)
+        || normalizeOptionalString(clientLabel)
+        || normalizeOptionalString(deviceName)
+        || 'Remote client';
+      const result = await remoteClientAuthRuntime.createClient({
+        label,
+        clientKind: normalizedKind,
+        dedupeKey: normalizeOptionalString(dedupeKey) || `pairing:${session.id}`,
+        authMethod: 'pairing',
+        pairingId: session.id,
+        deviceName,
+        devicePlatform,
+        deviceModel,
+        appVersion,
+        usesRelay: session.usesRelay === true,
+      });
+      session.usedAt = nowIso();
+      session.clientId = result.client?.id || null;
+      await writeStore(store);
+      return { pairing: publicSession(session), client: result.client, token: result.token };
+    });
+  };
+
+  const sweepExpiredSessions = async () => withStoreMutation(async () => {
+    const store = await readStore();
+    const before = store.sessions.length;
+    sweepExpiredSessionsFromStore(store);
+    const purged = before - store.sessions.length;
+    if (purged > 0) await writeStore(store);
+    return { purged };
+  });
+
+  return {
+    createPairingSession,
+    getPairingSession,
+    listPendingSessions,
+    hasActiveRelaySession,
+    cancelPairingSession,
+    redeemPairingSession,
+    sweepExpiredSessions,
+  };
+};

package/server/lib/client-auth/pairing.test.js

@@ -0,0 +1,142 @@
+import { describe, it, expect, vi } from 'vitest';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+
+import { createClientPairingRuntime } from './pairing.js';
+
+const makeRuntime = async (options = {}) => {
+  const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'pichamber-pairing-test-'));
+  const createdClients = [];
+  const remoteClientAuthRuntime = options.remoteClientAuthRuntime || {
+    createClient: vi.fn(async (input) => {
+      const client = {
+        id: `client-${createdClients.length + 1}`,
+        label: input.label,
+        clientKind: input.clientKind,
+        authMethod: input.authMethod,
+        pairingId: input.pairingId,
+        deviceName: input.deviceName ?? null,
+      };
+      createdClients.push(client);
+      return { client, token: `token-${createdClients.length}` };
+    }),
+  };
+  const runtime = createClientPairingRuntime({
+    fsPromises: fs,
+    path,
+    crypto,
+    storePath: path.join(dir, 'pairing.json'),
+    remoteClientAuthRuntime,
+    ttlMs: options.ttlMs ?? 10 * 60 * 1000,
+  });
+  return { dir, runtime, remoteClientAuthRuntime, createdClients };
+};
+
+describe('client auth pairing runtime', () => {
+  it('redeems a pairing session once and propagates client metadata', async () => {
+    const { runtime, remoteClientAuthRuntime } = await makeRuntime();
+    const created = await runtime.createPairingSession({ allowedClientKinds: ['mobile'] });
+
+    const result = await runtime.redeemPairingSession({
+      pairingId: created.pairing.id,
+      secret: created.pairing.secret,
+      clientLabel: 'Iryna iPhone',
+      clientKind: 'mobile',
+      deviceName: 'Iryna iPhone',
+      dedupeKey: 'device-key',
+    });
+
+    expect(result.token).toBe('token-1');
+    expect(result.client).toMatchObject({
+      label: 'Iryna iPhone',
+      clientKind: 'mobile',
+      authMethod: 'pairing',
+      pairingId: created.pairing.id,
+      deviceName: 'Iryna iPhone',
+    });
+    expect(remoteClientAuthRuntime.createClient).toHaveBeenCalledWith(expect.objectContaining({
+      authMethod: 'pairing',
+      pairingId: created.pairing.id,
+      clientKind: 'mobile',
+      dedupeKey: 'device-key',
+    }));
+
+    await expect(runtime.redeemPairingSession({
+      pairingId: created.pairing.id,
+      secret: created.pairing.secret,
+      clientKind: 'mobile',
+    })).rejects.toThrow('Invalid or expired pairing session');
+  });
+
+  it('rejects expired, cancelled, wrong-secret, and disallowed-kind redemption', async () => {
+    const { runtime: expiredRuntime } = await makeRuntime({ ttlMs: -1000 });
+    const expired = await expiredRuntime.createPairingSession();
+    await expect(expiredRuntime.redeemPairingSession({
+      pairingId: expired.pairing.id,
+      secret: expired.pairing.secret,
+      clientKind: 'mobile',
+    })).rejects.toThrow('Invalid or expired pairing session');
+
+    const { runtime } = await makeRuntime();
+    const cancelled = await runtime.createPairingSession();
+    await runtime.cancelPairingSession(cancelled.pairing.id);
+    await expect(runtime.redeemPairingSession({
+      pairingId: cancelled.pairing.id,
+      secret: cancelled.pairing.secret,
+      clientKind: 'mobile',
+    })).rejects.toThrow('Invalid or expired pairing session');
+
+    const wrongSecret = await runtime.createPairingSession();
+    await expect(runtime.redeemPairingSession({
+      pairingId: wrongSecret.pairing.id,
+      secret: 'wrong',
+      clientKind: 'mobile',
+    })).rejects.toThrow('Invalid or expired pairing session');
+
+    const desktopOnly = await runtime.createPairingSession({ allowedClientKinds: ['desktop'] });
+    await expect(runtime.redeemPairingSession({
+      pairingId: desktopOnly.pairing.id,
+      secret: desktopOnly.pairing.secret,
+      clientKind: 'mobile',
+    })).rejects.toThrow('Invalid or expired pairing session');
+  });
+
+  it('does not consume the pairing session if client issuance fails', async () => {
+    const createClient = vi.fn()
+      .mockRejectedValueOnce(new Error('disk failed'))
+      .mockResolvedValueOnce({ client: { id: 'client-1' }, token: 'token-1' });
+    const { runtime } = await makeRuntime({ remoteClientAuthRuntime: { createClient } });
+    const created = await runtime.createPairingSession();
+
+    await expect(runtime.redeemPairingSession({
+      pairingId: created.pairing.id,
+      secret: created.pairing.secret,
+      clientKind: 'mobile',
+    })).rejects.toThrow('disk failed');
+
+    await expect(runtime.redeemPairingSession({
+      pairingId: created.pairing.id,
+      secret: created.pairing.secret,
+      clientKind: 'mobile',
+    })).resolves.toMatchObject({ token: 'token-1' });
+    expect(createClient).toHaveBeenLastCalledWith(expect.objectContaining({
+      dedupeKey: `pairing:${created.pairing.id}`,
+    }));
+  });
+
+  it('sweeps expired never-used sessions from the store on the next create', async () => {
+    const { dir, runtime } = await makeRuntime({ ttlMs: -1000 });
+    // Immediately expired (negative TTL), never used or cancelled.
+    const expired = await runtime.createPairingSession({ label: 'stale' });
+
+    // The next create sweeps the store; only the fresh session should remain.
+    const storePath = path.join(dir, 'pairing.json');
+    await runtime.createPairingSession({ label: 'fresh' });
+    const store = JSON.parse(await fs.readFile(storePath, 'utf8'));
+    const ids = store.sessions.map((session) => session.id);
+    expect(ids).not.toContain(expired.pairing.id);
+    expect(ids).toHaveLength(1);
+  });
+});