openship 0.1.0 → 0.1.1

package/apps/api/src/config/env.ts

@@ -11,15 +11,45 @@ const envSchema = z.object({
   PORT: z.coerce.number().default(4000),
 
   /* ---------- Mode ---------- */
-  CLOUD_MODE: z.coerce.boolean().default(false),
+  CLOUD_MODE: z
+    .enum(["true", "false", "1", "0", ""])
+    .default("false")
+    .transform((v) => v === "true" || v === "1"),
+  /**
+   * Deployment mode — determines the runtime + infrastructure combination:
+   *   - "docker"  (default) → Docker runtime + Traefik routing/SSL (self-hosted)
+   *   - "bare"              → Process runtime + Traefik routing/SSL (self-hosted)
+   *   - "cloud"             → Oblien cloud API for everything (auto-set when CLOUD_MODE=true)
+   *   - "desktop"           → Bare runtime, no routing/SSL (desktop app)
+   */
+  DEPLOY_MODE: z.enum(["docker", "bare", "cloud", "desktop"]).default("docker"),
 
   /* ---------- Database ---------- */
-  DATABASE_URL: z.string().default("file:./dev.db"),
+  DATABASE_URL: z.string().default(""),
 
-  /* ---------- Auth ---------- */
-  JWT_SECRET: z.string().default("change-me-in-production"),
-  JWT_EXPIRES_IN: z.string().default("15m"),
-  JWT_REFRESH_EXPIRES_IN: z.string().default("7d"),
+  /* ---------- Auth (Better Auth) ---------- */
+  BETTER_AUTH_SECRET: z.string().default("change-me-in-production"),
+  BETTER_AUTH_URL: z.string().default("http://localhost:4000"),
+  TRUSTED_ORIGINS: z.string().optional(),
+
+  /* ---------- OAuth Providers ---------- */
+  GITHUB_CLIENT_ID: z.string().optional(),
+  GITHUB_CLIENT_SECRET: z.string().optional(),
+  GOOGLE_CLIENT_ID: z.string().optional(),
+  GOOGLE_CLIENT_SECRET: z.string().optional(),
+
+  /* ---------- GitHub Auth Strategy ---------- */
+  /**
+   * Controls how the API authenticates with GitHub:
+   *   - "auto"  (default) → inferred from DEPLOY_MODE / CLOUD_MODE
+   *   - "app"             → GitHub App installation tokens (cloud)
+   *   - "oauth"           → Better Auth OAuth flow only (self-hosted with OAuth)
+   *   - "cli"             → `gh auth login` token from the machine (local/desktop)
+   *   - "token"           → static GITHUB_TOKEN env var (CI, scripts)
+   */
+  GITHUB_AUTH_MODE: z.enum(["auto", "app", "oauth", "cli", "token"]).default("auto"),
+  /** Static GitHub personal access token — used when GITHUB_AUTH_MODE="token" */
+  GITHUB_TOKEN: z.string().optional(),
 
   /* ---------- Redis ---------- */
   REDIS_URL: z.string().default("redis://localhost:6379"),
@@ -28,12 +58,56 @@ const envSchema = z.object({
   STRIPE_SECRET_KEY: z.string().optional(),
   STRIPE_WEBHOOK_SECRET: z.string().optional(),
 
-  /* ---------- Git Providers ---------- */
+  /* ---------- Git Webhooks ---------- */
   GITHUB_APP_ID: z.string().optional(),
+  GITHUB_APP_SLUG: z.string().optional(),
   GITHUB_PRIVATE_KEY: z.string().optional(),
   GITHUB_WEBHOOK_SECRET: z.string().optional(),
+
+  /* ---------- Email (SMTP) ---------- */
+  SMTP_HOST: z.string().optional(),
+  SMTP_PORT: z.coerce.number().optional(),
+  SMTP_USER: z.string().optional(),
+  SMTP_PASS: z.string().optional(),
+  SMTP_FROM: z.string().default("Openship <noreply@openship.dev>"),
+
+  /* ---------- Dashboard ---------- */
+  DASHBOARD_URL: z.string().default("http://localhost:3001"),
+
+  /* ---------- Network (self-hosted) ---------- */
+  /** Public IP of the server — used for A record instructions in self-hosted mode. */
+  SERVER_IP: z.string().optional(),
+
+  /* ---------- Oblien Cloud ---------- */
+  OBLIEN_CLIENT_ID: z.string().optional(),
+  OBLIEN_CLIENT_SECRET: z.string().optional(),
+
+  /** Openship Cloud API URL — used by local instances to fetch namespace tokens */
+  OPENSHIP_CLOUD_URL: z.string().default("https://api.openship.io"),
+
+  /** Openship Cloud dashboard URL — used for external auth redirect (desktop + cloud connect) */
+  OPENSHIP_CLOUD_DASHBOARD_URL: z.string().default("https://app.openship.io"),
+
+  /* ---------- Screenshots (optional) ---------- */
+  SCREENSHOT_SERVICE_URL: z.string().optional(),
+  CDN_UPLOAD_URL: z.string().optional(),
+
+  /* ---------- Internal (Electron ↔ API) ---------- */
+  /** Shared secret for Electron → API calls (set by desktop app on startup) */
+  INTERNAL_TOKEN: z.string().optional(),
+
+  /** Enables verbose timing logs for SSH/system checks and environment detection */
+  SYSTEM_DEBUG_LOGS: z
+    .enum(["true", "false", "1", "0", ""])
+    .default("")
+    .transform((v) => v === "true" || v === "1"),
 });
 
 export type Env = z.infer<typeof envSchema>;
 
 export const env = envSchema.parse(process.env);
+
+/** Parsed trusted origins — single source of truth for CORS + Better Auth */
+export const trustedOrigins = env.TRUSTED_ORIGINS
+  ? env.TRUSTED_ORIGINS.split(",")
+  : ["http://localhost:3000", "http://localhost:3001"];

package/apps/api/src/lib/auth-mode.ts

@@ -0,0 +1,42 @@
+/**
+ * Cached auth-mode reader for desktop mode.
+ *
+ * Auth mode is written once during onboarding and rarely changes.
+ * Caching avoids a DB hit on every request through authMiddleware.
+ *
+ * The cache is cleared by setup.controller after any write so that
+ * re-onboarding (dev reset) picks up the new value immediately.
+ */
+
+import { env } from "../config/env";
+
+let cached: string | null = null;
+
+/**
+ * Returns the current auth mode for this instance.
+ *
+ *   "none"  → zero-auth desktop (auto-provisioned local user)
+ *   "cloud" → cloud-authenticated desktop (Openship Cloud session)
+ *   "local" → standard Better Auth (self-hosted VPS / SaaS)
+ */
+export async function getAuthMode(): Promise<"none" | "cloud" | "local"> {
+  // Non-desktop always uses local Better Auth
+  if (env.DEPLOY_MODE !== "desktop") return "local";
+
+  if (cached !== null) return cached as "none" | "cloud" | "local";
+
+  try {
+    const { repos } = await import("@repo/db");
+    const settings = await repos.instanceSettings.get();
+    cached = settings?.authMode ?? "none";
+  } catch {
+    cached = "none";
+  }
+
+  return cached as "none" | "cloud" | "local";
+}
+
+/** Clear the cached value — called after setup.controller writes. */
+export function clearAuthModeCache() {
+  cached = null;
+}

package/apps/api/src/lib/auth.ts

@@ -0,0 +1,105 @@
+import { betterAuth, type User } from "better-auth";
+import { drizzleAdapter } from "better-auth/adapters/drizzle";
+import { db, schema } from "@repo/db";
+import { env, trustedOrigins } from "../config/env";
+import { sendMail, smtpEnabled } from "./mail";
+import { resetPasswordEmail, verifyEmailTemplate } from "./email-templates";
+
+/**
+ * Better Auth — handles registration, login, OAuth, sessions, tokens.
+ *
+ * Browser clients (dashboard) use httpOnly session cookies.
+ * API clients (CLI, external) use Bearer tokens via the session token.
+ *
+ * Routes are mounted at /api/auth/* in app.ts.
+ */
+export const auth = betterAuth({
+  basePath: "/api/auth",
+  baseURL: env.BETTER_AUTH_URL,
+
+  database: drizzleAdapter(db, {
+    provider: "pg",
+    schema: {
+      user: schema.user,
+      session: schema.session,
+      account: schema.account,
+      verification: schema.verification,
+    },
+  }),
+
+  /* ---------- Email + Password ---------- */
+  emailAndPassword: {
+    enabled: true,
+    minPasswordLength: 8,
+    maxPasswordLength: 128,
+
+    /* Password reset — only functional when SMTP is configured */
+    sendResetPassword: smtpEnabled
+      ? async ({ user, url }: { user: User; url: string; token: string }) => {
+          const email = resetPasswordEmail(user, url);
+          await sendMail({ to: user.email, ...email });
+        }
+      : undefined,
+
+    /* Email verification — only functional when SMTP is configured */
+    requireEmailVerification: smtpEnabled,
+    sendVerificationEmail: smtpEnabled
+      ? async ({ user, url }: { user: User; url: string; token: string }) => {
+          const email = verifyEmailTemplate(user, url);
+          await sendMail({ to: user.email, ...email });
+        }
+      : undefined,
+  },
+
+  /* ---------- OAuth Providers ---------- */
+  socialProviders: {
+    ...(env.GITHUB_CLIENT_ID && env.GITHUB_CLIENT_SECRET
+      ? {
+          github: {
+            clientId: env.GITHUB_CLIENT_ID,
+            clientSecret: env.GITHUB_CLIENT_SECRET,
+          },
+        }
+      : {}),
+    ...(env.GOOGLE_CLIENT_ID && env.GOOGLE_CLIENT_SECRET
+      ? {
+          google: {
+            clientId: env.GOOGLE_CLIENT_ID,
+            clientSecret: env.GOOGLE_CLIENT_SECRET,
+          },
+        }
+      : {}),
+  },
+
+  /* ---------- Session ---------- */
+  session: {
+    expiresIn: 60 * 60 * 24 * 30, // 30 days
+    updateAge: 60 * 60,            // refresh session every hour
+    cookieCache: {
+      enabled: true,
+      maxAge: 60 * 60 * 24,        // cache session in cookie for 24h (avoids DB hit)
+    },
+  },
+
+  /* ---------- Custom fields on user ---------- */
+  user: {
+    additionalFields: {
+      role: {
+        type: "string",
+        defaultValue: "user",
+        input: false,
+      },
+      autoProvisioned: {
+        type: "boolean",
+        defaultValue: false,
+        input: false,
+      },
+    },
+  },
+
+  /* ---------- Security ---------- */
+  secret: env.BETTER_AUTH_SECRET,
+  trustedOrigins,
+});
+
+export type Auth = typeof auth;

package/apps/api/src/lib/cache.ts

@@ -0,0 +1,128 @@
+/**
+ * TtlCache — generic in-memory cache with automatic TTL expiration.
+ *
+ * Entries are lazily evicted on read and periodically swept via a
+ * background timer (default: every 60 s). Supports per-key TTL,
+ * prefix-based invalidation, and a hard size cap.
+ *
+ * Usage:
+ *   const cache = new TtlCache<string>({ maxSize: 1000, sweepIntervalMs: 60_000 });
+ *   cache.set("key", "value", 300);   // 300 seconds TTL
+ *   cache.get("key");                  // "value" | null
+ *   cache.invalidateByPrefix("user:"); // remove all keys starting with "user:"
+ */
+
+interface CacheEntry<T> {
+  value: T;
+  expiresAt: number;
+}
+
+export interface TtlCacheOptions {
+  /** Maximum number of entries before oldest are evicted (default: 5000). */
+  maxSize?: number;
+  /** Interval in ms for the background sweep timer (default: 60000). 0 = disabled. */
+  sweepIntervalMs?: number;
+}
+
+export class TtlCache<T> {
+  private readonly store = new Map<string, CacheEntry<T>>();
+  private readonly maxSize: number;
+  private sweepTimer: ReturnType<typeof setInterval> | null = null;
+
+  constructor(opts: TtlCacheOptions = {}) {
+    this.maxSize = opts.maxSize ?? 5_000;
+    const sweepMs = opts.sweepIntervalMs ?? 60_000;
+
+    if (sweepMs > 0) {
+      this.sweepTimer = setInterval(() => this.sweep(), sweepMs);
+      /* Allow the process to exit even if the timer is running */
+      if (this.sweepTimer && typeof this.sweepTimer === "object" && "unref" in this.sweepTimer) {
+        this.sweepTimer.unref();
+      }
+    }
+  }
+
+  /** Get a value, returning null if missing or expired. */
+  get(key: string): T | null {
+    const entry = this.store.get(key);
+    if (!entry) return null;
+    if (Date.now() > entry.expiresAt) {
+      this.store.delete(key);
+      return null;
+    }
+    return entry.value;
+  }
+
+  /** Set a value with a TTL in seconds. */
+  set(key: string, value: T, ttlSeconds: number): void {
+    if (this.store.size >= this.maxSize) {
+      this.sweep();
+    }
+    this.store.set(key, {
+      value,
+      expiresAt: Date.now() + ttlSeconds * 1_000,
+    });
+  }
+
+  /** Check if a key exists and is not expired. */
+  has(key: string): boolean {
+    return this.get(key) !== null;
+  }
+
+  /** Delete a specific key. */
+  delete(key: string): void {
+    this.store.delete(key);
+  }
+
+  /** Invalidate all keys that start with the given prefix. */
+  invalidateByPrefix(prefix: string): void {
+    for (const key of this.store.keys()) {
+      if (key.startsWith(prefix)) this.store.delete(key);
+    }
+  }
+
+  /** Invalidate all keys that contain the given substring. */
+  invalidateBySubstring(sub: string): void {
+    for (const key of this.store.keys()) {
+      if (key.includes(sub)) this.store.delete(key);
+    }
+  }
+
+  /** Remove all expired entries. */
+  sweep(): void {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (now > entry.expiresAt) this.store.delete(key);
+    }
+  }
+
+  /** Clear all entries. */
+  clear(): void {
+    this.store.clear();
+  }
+
+  /** Current number of entries (including possibly expired). */
+  get size(): number {
+    return this.store.size;
+  }
+
+  /** Iterate over all non-expired values. */
+  *values(): IterableIterator<T> {
+    const now = Date.now();
+    for (const [key, entry] of this.store) {
+      if (now > entry.expiresAt) {
+        this.store.delete(key);
+      } else {
+        yield entry.value;
+      }
+    }
+  }
+
+  /** Stop the background sweep timer (for graceful shutdown / tests). */
+  dispose(): void {
+    if (this.sweepTimer) {
+      clearInterval(this.sweepTimer);
+      this.sweepTimer = null;
+    }
+  }
+}

package/apps/api/src/lib/cloud-auth-proxy.ts

@@ -0,0 +1,310 @@
+/**
+ * Cloud auth proxy — shared utilities for Openship Cloud authentication.
+ *
+ * Used by:
+ *   - Desktop mode: cloud-callback exchanges a one-time code for a local session
+ *   - Self-hosted settings: connect-callback stores cloud token for deploys
+ *   - Cloud mode (SaaS): desktop-handoff generates one-time codes
+ *
+ * All external auth happens on app.openship.io — this module only handles
+ * the local side (mirroring users, creating sessions, managing codes).
+ */
+
+import { randomUUID, randomBytes, createHash, timingSafeEqual } from "node:crypto";
+import { db, schema, repos, eq } from "@repo/db";
+import { encrypt } from "./encryption";
+import { env } from "../config/env";
+
+export interface CloudUser {
+  id: string;
+  name: string;
+  email: string;
+  emailVerified: boolean;
+  image?: string | null;
+}
+
+/**
+ * Ensure a local user record exists that mirrors the cloud user.
+ *
+ * Uses the cloud user's email as the unique key. If the user already
+ * exists locally (from a previous login), updates their info.
+ * Returns the local user ID.
+ */
+async function mirrorCloudUser(cloudUser: CloudUser): Promise<string> {
+  const existing = await repos.user.findByEmail(cloudUser.email);
+
+  if (existing) {
+    // Update name/image if changed
+    await db
+      .update(schema.user)
+      .set({
+        name: cloudUser.name,
+        image: cloudUser.image,
+        emailVerified: true,
+      })
+      .where(eq(schema.user.email, cloudUser.email));
+    return existing.id;
+  }
+
+  // Create new local user — use a deterministic ID so cloud user maps 1:1
+  const id = cloudUser.id;
+  await db.insert(schema.user).values({
+    id,
+    name: cloudUser.name,
+    email: cloudUser.email,
+    emailVerified: true,
+    role: "admin",
+    autoProvisioned: false,
+  });
+
+  return id;
+}
+
+/**
+ * Store the cloud session token (encrypted) for later cloud API calls.
+ */
+async function storeCloudSession(userId: string, cloudSessionToken: string): Promise<void> {
+  const encrypted = encrypt(cloudSessionToken);
+  const settings = await repos.settings.findByUser(userId);
+  if (settings) {
+    await repos.settings.update(userId, { cloudSessionToken: encrypted });
+  } else {
+    await repos.settings.upsert({
+      id: randomUUID(),
+      userId,
+      cloudSessionToken: encrypted,
+    });
+  }
+}
+
+/**
+ * Create a local Better Auth session directly in the DB.
+ *
+ * This is used for desktop/cloud-proxy auth where we don't have a local password.
+ * The session is created for the mirrored user so that `auth.api.getSession()`
+ * recognizes it from the cookie.
+ *
+ * Returns the session token (to be set as a cookie).
+ */
+async function createLocalSession(
+  userId: string,
+  ipAddress?: string,
+  userAgent?: string,
+): Promise<{ token: string; expiresAt: Date }> {
+  const token = randomBytes(32).toString("hex");
+  const expiresAt = new Date(Date.now() + 30 * 24 * 60 * 60 * 1000); // 30 days
+
+  await db.insert(schema.session).values({
+    id: randomUUID(),
+    token,
+    userId,
+    expiresAt,
+    ipAddress: ipAddress ?? null,
+    userAgent: userAgent ?? null,
+  });
+
+  return { token, expiresAt };
+}
+
+// ─── One-time handoff codes (cloud-side generates, desktop-side consumes) ────
+
+/**
+ * In-memory store for one-time handoff codes.
+ * Code → { user, sessionToken, expiresAt }
+ *
+ * Used by CLOUD_MODE instances to hold auth data between the
+ * auth completion and the desktop/local instance's code exchange.
+ */
+const handoffCodes = new Map<string, { user: CloudUser; sessionToken: string; codeChallenge: string | null; expiresAt: number }>();
+
+let lastPurge = 0;
+function purgeExpiredCodes() {
+  const now = Date.now();
+  if (now - lastPurge < 60_000) return;
+  lastPurge = now;
+  for (const [code, data] of handoffCodes) {
+    if (data.expiresAt < now) handoffCodes.delete(code);
+  }
+}
+
+/**
+ * Generate a one-time code that holds the auth result.
+ * Called on the CLOUD instance after authentication completes.
+ * The code is valid for 60 seconds and can only be used once.
+ *
+ * @param codeChallenge — PKCE S256 challenge (base64url). When provided,
+ *   the corresponding code_verifier must be presented at exchange time.
+ */
+async function generateHandoffCode(user: CloudUser, sessionToken: string, codeChallenge?: string): Promise<string> {
+  purgeExpiredCodes();
+  const code = randomBytes(32).toString("hex");
+  handoffCodes.set(code, {
+    user,
+    sessionToken,
+    codeChallenge: codeChallenge ?? null,
+    expiresAt: Date.now() + 60_000,
+  });
+  return code;
+}
+
+/**
+ * Exchange a one-time code for the auth result.
+ * Called on the CLOUD instance by the desktop/local callback.
+ *
+ * If a code_challenge was stored, the caller must provide the matching
+ * code_verifier (PKCE S256). Returns null on mismatch.
+ */
+function exchangeHandoffCode(code: string, codeVerifier?: string): { user: CloudUser; sessionToken: string } | null {
+  purgeExpiredCodes();
+  const data = handoffCodes.get(code);
+  if (!data || data.expiresAt < Date.now()) {
+    handoffCodes.delete(code);
+    return null;
+  }
+
+  // PKCE verification — if a challenge was stored, verifier is mandatory
+  if (data.codeChallenge) {
+    if (!codeVerifier) {
+      return null; // verifier required but not provided
+    }
+    const computed = createHash("sha256").update(codeVerifier).digest("base64url");
+    if (computed !== data.codeChallenge) {
+      return null; // PKCE mismatch
+    }
+  }
+
+  handoffCodes.delete(code); // one-time use
+  return { user: data.user, sessionToken: data.sessionToken };
+}
+
+/**
+ * Exchange a one-time code with the Openship Cloud API.
+ * Shared by desktop cloud-callback and self-hosted connect-callback.
+ *
+ * @param codeVerifier — PKCE code_verifier (plain). Required when the
+ *   authorization was initiated with a code_challenge.
+ */
+async function exchangeCodeWithCloud(code: string, codeVerifier?: string): Promise<{ user: CloudUser; sessionToken: string } | null> {
+  const res = await fetch(`${env.OPENSHIP_CLOUD_URL}/api/cloud/exchange-code`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code, code_verifier: codeVerifier }),
+  });
+  if (!res.ok) return null;
+  const { data } = (await res.json()) as {
+    data: { user: CloudUser; sessionToken: string };
+  };
+  return data;
+}
+
+// ─── Desktop auth nonce relay (single-user, in-memory) ──────────────────────
+
+/**
+ * When Electron starts cloud auth, it registers a nonce.
+ * After the system browser completes /cloud-callback, the session token
+ * is stored against that nonce. Electron polls to pick it up.
+ */
+let pendingNonce: { value: string; state: string; codeVerifier: string; registeredAt: number } | null = null;
+let resolvedAuth: { nonce: string; claimCode: string } | null = null;
+let pendingClaim: { code: string; token: string; expiresAt: number; createdAt: number } | null = null;
+/** Nonce value preserved after validateDesktopState consumes pendingNonce, used by pollDesktopAuth */
+let activeNonce: string | null = null;
+
+const NONCE_TTL = 5 * 60 * 1000; // 5 minutes
+
+function registerDesktopNonce(nonce: string, state: string, codeVerifier: string): void {
+  pendingNonce = { value: nonce, state, codeVerifier, registeredAt: Date.now() };
+  resolvedAuth = null;
+  pendingClaim = null;
+  activeNonce = nonce;
+}
+
+/**
+ * Store the session result so Electron can pick it up via polling.
+ *
+ * The nonce value needed for polling was saved at registerDesktopNonce time.
+ * validateDesktopState already consumed pendingNonce, so we accept the
+ * nonce value explicitly.
+ */
+function resolveDesktopAuth(nonce: string, token: string, expiresAt: Date): void {
+  const claimCode = randomBytes(16).toString("hex");
+  resolvedAuth = { nonce, claimCode };
+  pendingClaim = { code: claimCode, token, expiresAt: expiresAt.getTime(), createdAt: Date.now() };
+}
+
+/**
+ * Validate the state parameter returned from the cloud and retrieve
+ * the stored code_verifier for PKCE.
+ *
+ * Returns the code_verifier and nonce if state matches, null otherwise.
+ * Consumes the nonce atomically — prevents replay attacks.
+ */
+function validateDesktopState(state: string): { codeVerifier: string; nonce: string } | null {
+  if (!pendingNonce) return null;
+  if (Date.now() - pendingNonce.registeredAt > NONCE_TTL) {
+    pendingNonce = null;
+    return null;
+  }
+  // Timing-safe comparison for state
+  const expected = Buffer.from(pendingNonce.state);
+  const actual = Buffer.from(state);
+  if (expected.length !== actual.length) {
+    pendingNonce = null;
+    return null;
+  }
+  if (!timingSafeEqual(expected, actual)) {
+    pendingNonce = null;
+    return null;
+  }
+  const result = { codeVerifier: pendingNonce.codeVerifier, nonce: pendingNonce.value };
+  pendingNonce = null; // consume — one-time use
+  return result;
+}
+
+function pollDesktopAuth(nonce: string): { status: "pending" | "resolved" | "expired"; claimCode?: string } {
+  if (resolvedAuth && resolvedAuth.nonce === nonce) {
+    const result = { status: "resolved" as const, claimCode: resolvedAuth.claimCode };
+    resolvedAuth = null; // one-time read
+    activeNonce = null;
+    return result;
+  }
+  if (pendingNonce && pendingNonce.value === nonce) {
+    if (Date.now() - pendingNonce.registeredAt > NONCE_TTL) {
+      pendingNonce = null;
+      activeNonce = null;
+      return { status: "expired" };
+    }
+    return { status: "pending" };
+  }
+  // Between validateDesktopState (consumes pendingNonce) and resolveDesktopAuth
+  // (sets resolvedAuth), both are null. activeNonce keeps "pending" during this window.
+  if (activeNonce === nonce) {
+    return { status: "pending" };
+  }
+  return { status: "expired" };
+}
+
+function exchangeDesktopClaim(code: string): { token: string; expiresAt: Date } | null {
+  if (!pendingClaim || pendingClaim.code !== code) return null;
+  if (Date.now() - pendingClaim.createdAt > 60_000) {
+    pendingClaim = null;
+    return null;
+  }
+  const result = { token: pendingClaim.token, expiresAt: new Date(pendingClaim.expiresAt) };
+  pendingClaim = null; // one-time use
+  return result;
+}
+
+export {
+  mirrorCloudUser,
+  storeCloudSession,
+  createLocalSession,
+  generateHandoffCode,
+  exchangeHandoffCode,
+  exchangeCodeWithCloud,
+  registerDesktopNonce,
+  resolveDesktopAuth,
+  validateDesktopState,
+  pollDesktopAuth,
+  exchangeDesktopClaim,
+};