@baseworks/auth 0.2.0

package/dist/edge.d.ts

@@ -0,0 +1,17 @@
+import { OidcSession } from './session.js';
+import 'next/server';
+
+type EdgeAuthProvider = "anonymous" | "cookie" | "pomerium";
+type EdgeSession = OidcSession & {
+    groups?: string[];
+    provider: EdgeAuthProvider;
+    rawClaims?: Record<string, unknown>;
+    role?: string;
+    username?: string;
+};
+declare function getEdgeSession(): Promise<EdgeSession>;
+declare function getPomeriumAuthenticateUrl(redirectTo: string, origin?: string): string | null;
+declare function handleEdgeLogin(request: Request): void;
+declare function getPomeriumSignOutUrl(redirectTo: string, origin?: string): string | null;
+
+export { type EdgeAuthProvider, type EdgeSession, getEdgeSession, getPomeriumAuthenticateUrl, getPomeriumSignOutUrl, handleEdgeLogin };

package/dist/edge.js

@@ -0,0 +1,155 @@
+import {
+  getSessionFromCookies
+} from "./chunk-VUB4GTMI.js";
+import {
+  buildPublicUrl,
+  normalizeUrlLike
+} from "./chunk-3NJASEF4.js";
+
+// src/edge.ts
+import { headers } from "next/headers";
+import { redirect } from "next/navigation";
+function firstHeader(headerStore, names) {
+  for (const name of names) {
+    const value = headerStore.get(name);
+    if (value) return value;
+  }
+  return void 0;
+}
+function decodeBase64Url(value) {
+  const normalized = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = normalized.padEnd(normalized.length + (4 - normalized.length % 4) % 4, "=");
+  return Buffer.from(padded, "base64").toString("utf8");
+}
+function parseJwtPayload(token) {
+  try {
+    const [, payload] = token.split(".");
+    if (!payload) return null;
+    return JSON.parse(decodeBase64Url(payload));
+  } catch {
+    return null;
+  }
+}
+function stringClaim(claims, keys) {
+  for (const key of keys) {
+    const value = claims[key];
+    if (typeof value === "string" && value.trim()) return value;
+    if (Array.isArray(value)) {
+      const first = value.find((item) => typeof item === "string" && item.trim());
+      if (first) return first;
+    }
+  }
+  return void 0;
+}
+function parseHeaderClaim(value) {
+  if (!value) return void 0;
+  try {
+    const parsed = JSON.parse(value);
+    if (typeof parsed === "string" && parsed.trim()) return parsed;
+    if (Array.isArray(parsed)) {
+      const first = parsed.find((item) => typeof item === "string" && item.trim());
+      if (first) return first;
+    }
+  } catch {
+  }
+  return value.trim() || void 0;
+}
+function stringHeaderClaim(headerStore, names) {
+  for (const name of names) {
+    const value = parseHeaderClaim(headerStore.get(name) ?? void 0);
+    if (value) return value;
+  }
+  return void 0;
+}
+function stringArrayClaim(claims, keys) {
+  for (const key of keys) {
+    const value = claims[key];
+    if (typeof value === "string" && value.trim()) return [value];
+    if (Array.isArray(value)) {
+      const strings = value.filter((item) => typeof item === "string" && item.trim().length > 0);
+      if (strings.length) return strings;
+    }
+  }
+  return void 0;
+}
+function stringArrayHeaderClaim(headerStore, names) {
+  for (const name of names) {
+    const raw = headerStore.get(name);
+    if (!raw) continue;
+    try {
+      const parsed = JSON.parse(raw);
+      if (typeof parsed === "string" && parsed.trim()) return [parsed];
+      if (Array.isArray(parsed)) {
+        const strings = parsed.filter((item) => typeof item === "string" && item.trim().length > 0);
+        if (strings.length) return strings;
+      }
+    } catch {
+      const values = raw.split(",").map((v) => v.trim()).filter(Boolean);
+      if (values.length) return values;
+    }
+  }
+  return void 0;
+}
+function parsePomeriumSession(headerStore) {
+  const assertion = firstHeader(headerStore, ["x-pomerium-jwt-assertion", "x-pomerium-jwt"]);
+  const claims = assertion ? parseJwtPayload(assertion) : {};
+  const email = stringHeaderClaim(headerStore, ["x-pomerium-claim-email", "x-forwarded-email"]) ?? stringClaim(claims ?? {}, ["email"]);
+  const subject = stringHeaderClaim(headerStore, ["x-pomerium-claim-sub", "x-pomerium-claim-user", "x-user-id"]) ?? stringClaim(claims ?? {}, ["sub", "user", "id"]);
+  const name = stringHeaderClaim(headerStore, ["x-pomerium-claim-name", "x-forwarded-user"]) ?? stringClaim(claims ?? {}, ["name", "preferred_username"]);
+  const pictureUrl = stringHeaderClaim(headerStore, ["x-pomerium-claim-picture"]) ?? stringClaim(claims ?? {}, ["picture"]);
+  const username = stringHeaderClaim(headerStore, ["x-pomerium-claim-username", "x-pomerium-claim-preferred-username"]) ?? stringClaim(claims ?? {}, ["username", "preferred_username", "user"]);
+  const groups = stringArrayHeaderClaim(headerStore, ["x-pomerium-claim-groups", "x-pomerium-claim-roles"]) ?? stringArrayClaim(claims ?? {}, ["groups", "roles"]);
+  const role = stringHeaderClaim(headerStore, ["x-pomerium-claim-role"]) ?? stringClaim(claims ?? {}, ["role"]);
+  if (!email && !subject && !name) return null;
+  return {
+    email,
+    expiresAt: Number.MAX_SAFE_INTEGER,
+    groups,
+    isAuthenticated: true,
+    name,
+    pictureUrl,
+    provider: "pomerium",
+    rawClaims: claims ?? void 0,
+    role,
+    subject: subject ?? email,
+    username
+  };
+}
+async function getEdgeSession() {
+  const headerStore = await headers();
+  const pomerium = parsePomeriumSession(headerStore);
+  if (pomerium) return pomerium;
+  const cookieSession = await getSessionFromCookies();
+  if (cookieSession.isAuthenticated) {
+    return { ...cookieSession, provider: "cookie" };
+  }
+  return { expiresAt: 0, isAuthenticated: false, provider: "anonymous" };
+}
+function getPomeriumAuthenticateUrl(redirectTo, origin) {
+  const appUrl = origin ?? process.env.APP_PUBLIC_URL ?? process.env.NEXT_PUBLIC_SITE_URL;
+  if (!appUrl) return null;
+  const url = new URL(
+    process.env.POMERIUM_LOGIN_PATH ?? "/auth/edge/login",
+    `${normalizeUrlLike(appUrl)}/`
+  );
+  url.searchParams.set("pomerium_redirect_uri", buildPublicUrl(redirectTo, origin));
+  return url.toString();
+}
+function handleEdgeLogin(request) {
+  const url = new URL(request.url);
+  const redirectTo = url.searchParams.get("pomerium_redirect_uri") ?? "/";
+  redirect(redirectTo);
+}
+function getPomeriumSignOutUrl(redirectTo, origin) {
+  const authUrl = process.env.POMERIUM_AUTHENTICATE_URL ?? process.env.POMERIUM_AUTH_URL ?? origin;
+  if (!authUrl) return null;
+  const url = new URL("/.pomerium/sign_out", `${normalizeUrlLike(authUrl)}/`);
+  url.searchParams.set("pomerium_redirect_uri", buildPublicUrl(redirectTo, origin));
+  return url.toString();
+}
+export {
+  getEdgeSession,
+  getPomeriumAuthenticateUrl,
+  getPomeriumSignOutUrl,
+  handleEdgeLogin
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { OidcClaims, OidcIdentity, OidcVerifyConfig, verifyOidcToken } from './oidc.js';
+export { OidcHumanResolverConfig, createOidcHumanResolver } from './oidc-human.js';
+export { OidcAuthUrlConfig, PkceChallenge, buildOidcAuthUrl, generatePkce } from './pkce.js';
+export { CliAuthResult, CliAuthStart, PollOptions, pollCliAuth, startCliAuth } from './cli-auth.js';
+export { hashToken, looksLikeJwt, stripBearer } from './token.js';
+export { buildAccountProfileUrl, buildAuthLoginUrl, buildAuthLogoutUrl, buildPublicUrl, getAccountPublicUrl, getAppBasePath, getAuthPublicUrl, getPublicSiteUrl, normalizeUrlLike } from './url-helpers.js';
+export { ZitadelClaims, ZitadelConfig, ZitadelIdentity, verifyZitadelToken } from './zitadel.js';

package/dist/index.js

@@ -0,0 +1,54 @@
+import {
+  verifyZitadelToken
+} from "./chunk-BMPRMOI7.js";
+import {
+  createOidcHumanResolver
+} from "./chunk-6TUNNS2B.js";
+import {
+  verifyOidcToken
+} from "./chunk-BL74TFCV.js";
+import {
+  buildOidcAuthUrl,
+  generatePkce
+} from "./chunk-M7EACPIB.js";
+import {
+  pollCliAuth,
+  startCliAuth
+} from "./chunk-C4V5LCFA.js";
+import {
+  hashToken,
+  looksLikeJwt,
+  stripBearer
+} from "./chunk-VBIQJKUU.js";
+import {
+  buildAccountProfileUrl,
+  buildAuthLoginUrl,
+  buildAuthLogoutUrl,
+  buildPublicUrl,
+  getAccountPublicUrl,
+  getAppBasePath,
+  getAuthPublicUrl,
+  getPublicSiteUrl,
+  normalizeUrlLike
+} from "./chunk-3NJASEF4.js";
+export {
+  buildAccountProfileUrl,
+  buildAuthLoginUrl,
+  buildAuthLogoutUrl,
+  buildOidcAuthUrl,
+  buildPublicUrl,
+  createOidcHumanResolver,
+  generatePkce,
+  getAccountPublicUrl,
+  getAppBasePath,
+  getAuthPublicUrl,
+  getPublicSiteUrl,
+  hashToken,
+  looksLikeJwt,
+  normalizeUrlLike,
+  pollCliAuth,
+  startCliAuth,
+  stripBearer,
+  verifyOidcToken,
+  verifyZitadelToken
+};

package/dist/oidc-human.d.ts

@@ -0,0 +1,41 @@
+import { OidcIdentity } from './oidc.js';
+
+/**
+ * Shared OIDC → HumanContext resolver.
+ *
+ * Handles: JWT detection, issuer check, signature verification.
+ * DB lookup / user creation is delegated to `findOrCreate` — kept app-specific.
+ *
+ * Usage:
+ *   const resolve = createOidcHumanResolver({
+ *     issuer:       env.OIDC_ISSUER,
+ *     audience:     env.OIDC_AUDIENCE,
+ *     findOrCreate: async (identity) => { /* DB upsert *\/ },
+ *   })
+ *   const ctx = await resolve(bearerToken)
+ */
+
+interface OidcHumanResolverConfig<T> {
+    /** OIDC issuer URL — e.g. https://nesskey.com */
+    issuer: string;
+    /** Optional audience restriction */
+    audience?: string;
+    /**
+     * Called after successful OIDC verification.
+     * Return the app's HumanContext or null to reject.
+     * Responsible for DB lookup / upsert.
+     * rawToken is passed so implementations can call userinfo if needed.
+     */
+    findOrCreate: (identity: OidcIdentity, rawToken: string) => Promise<T | null>;
+}
+/**
+ * Returns a resolver function `(token: string) => Promise<T | null>`.
+ * Call it with a raw Bearer token (JWT form). Returns null if:
+ *   - token is not a JWT
+ *   - issuer doesn't match
+ *   - signature invalid / expired
+ *   - findOrCreate returns null
+ */
+declare function createOidcHumanResolver<T>(config: OidcHumanResolverConfig<T>): (token: string) => Promise<T | null>;
+
+export { type OidcHumanResolverConfig, OidcIdentity, createOidcHumanResolver };

package/dist/oidc-human.js

@@ -0,0 +1,7 @@
+import {
+  createOidcHumanResolver
+} from "./chunk-6TUNNS2B.js";
+import "./chunk-BL74TFCV.js";
+export {
+  createOidcHumanResolver
+};

package/dist/oidc.d.ts

@@ -0,0 +1,29 @@
+interface OidcVerifyConfig {
+    issuer: string;
+    audience?: string;
+}
+interface OidcClaims {
+    sub: string;
+    email?: string;
+    preferred_username?: string;
+    name?: string;
+    picture?: string;
+    exp?: number;
+    iss?: string;
+    aud?: string | string[];
+}
+interface OidcIdentity {
+    subject: string;
+    issuer: string;
+    email: string;
+    name: string;
+    picture?: string;
+}
+/**
+ * Verify an OIDC JWT and return the normalised identity.
+ * Uses JWKS from `{issuer}/oauth/v2/keys` (Zitadel-compatible endpoint).
+ * Returns null on any verification failure — never throws to the caller.
+ */
+declare function verifyOidcToken(token: string, config: OidcVerifyConfig): Promise<OidcIdentity | null>;
+
+export { type OidcClaims, type OidcIdentity, type OidcVerifyConfig, verifyOidcToken };

package/dist/oidc.js

@@ -0,0 +1,6 @@
+import {
+  verifyOidcToken
+} from "./chunk-BL74TFCV.js";
+export {
+  verifyOidcToken
+};

package/dist/pkce.d.ts

@@ -0,0 +1,35 @@
+/**
+ * PKCE (Proof Key for Code Exchange) utilities — RFC 7636.
+ * Runtime-agnostic: Workers, Node 20+, browser (Web Crypto API).
+ */
+interface PkceChallenge {
+    verifier: string;
+    challenge: string;
+    method: 'S256';
+}
+interface OidcAuthUrlConfig {
+    /** OIDC issuer base URL, e.g. "https://nesskey.com" */
+    issuer: string;
+    clientId: string;
+    redirectUri: string;
+    /** Defaults to ["openid", "email", "profile"] */
+    scopes?: string[];
+    state?: string;
+    challenge: string;
+    /**
+     * OIDC prompt parameter.
+     * - "select_account" → show account chooser even if session exists (recommended for web apps)
+     * - "login"          → force re-authentication every time
+     * - "none"           → silent auth, error if no session
+     */
+    prompt?: 'select_account' | 'login' | 'none' | 'consent';
+}
+/** Generate a PKCE code_verifier + S256 code_challenge pair. */
+declare function generatePkce(): Promise<PkceChallenge>;
+/**
+ * Build an OIDC authorization URL with PKCE.
+ * Compatible with any OIDC provider (Zitadel, Auth0, Keycloak, etc.).
+ */
+declare function buildOidcAuthUrl(config: OidcAuthUrlConfig): string;
+
+export { type OidcAuthUrlConfig, type PkceChallenge, buildOidcAuthUrl, generatePkce };

package/dist/pkce.js

@@ -0,0 +1,8 @@
+import {
+  buildOidcAuthUrl,
+  generatePkce
+} from "./chunk-M7EACPIB.js";
+export {
+  buildOidcAuthUrl,
+  generatePkce
+};

package/dist/session.d.ts

@@ -0,0 +1,42 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+type OidcSession = {
+    audience?: string | string[];
+    email?: string;
+    expiresAt: number;
+    isAuthenticated: boolean;
+    issuer?: string;
+    name?: string;
+    pictureUrl?: string;
+    subject?: string;
+    tokenIdentifier?: string;
+};
+declare const oidcCookies: {
+    readonly codeVerifier: "oidc_code_verifier";
+    readonly state: "oidc_state";
+    readonly nonce: "oidc_nonce";
+    readonly returnTo: "oidc_return_to";
+    readonly idToken: "oidc_id_token";
+    readonly accessToken: "oidc_access_token";
+    readonly refreshToken: "oidc_refresh_token";
+    readonly expiresAt: "oidc_expires_at";
+    readonly session: "oidc_session";
+};
+declare function buildAuthorizationRedirect(request: NextRequest): Promise<NextResponse<unknown>>;
+declare function handleAuthorizationCallback(request: NextRequest): Promise<NextResponse<unknown>>;
+declare function getSessionFromCookies(): Promise<OidcSession>;
+declare function getServerIdToken(): Promise<string | null>;
+declare function hasServerOidcSession(): Promise<boolean>;
+declare function getServerAccessToken(): Promise<string | null>;
+declare function buildSessionResponse(_request?: NextRequest): Promise<NextResponse<{
+    expiresAt: number;
+    isAuthenticated: false;
+}> | NextResponse<OidcSession>>;
+declare function buildTokenResponse(request: NextRequest): Promise<NextResponse<{
+    token: null;
+}> | NextResponse<{
+    token: string;
+}>>;
+declare function buildLogoutResponse(request: NextRequest): Promise<NextResponse<unknown>>;
+
+export { type OidcSession, buildAuthorizationRedirect, buildLogoutResponse, buildSessionResponse, buildTokenResponse, getServerAccessToken, getServerIdToken, getSessionFromCookies, handleAuthorizationCallback, hasServerOidcSession, oidcCookies };

package/dist/session.js

@@ -0,0 +1,25 @@
+import {
+  buildAuthorizationRedirect,
+  buildLogoutResponse,
+  buildSessionResponse,
+  buildTokenResponse,
+  getServerAccessToken,
+  getServerIdToken,
+  getSessionFromCookies,
+  handleAuthorizationCallback,
+  hasServerOidcSession,
+  oidcCookies
+} from "./chunk-VUB4GTMI.js";
+import "./chunk-3NJASEF4.js";
+export {
+  buildAuthorizationRedirect,
+  buildLogoutResponse,
+  buildSessionResponse,
+  buildTokenResponse,
+  getServerAccessToken,
+  getServerIdToken,
+  getSessionFromCookies,
+  handleAuthorizationCallback,
+  hasServerOidcSession,
+  oidcCookies
+};

package/dist/token.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Token hashing utilities — no libsodium dependency, Web Crypto only.
+ * Runtime-agnostic: Workers, Node 20+, browser.
+ */
+/** HMAC-SHA-256 hash with optional pepper. Use for API key storage at rest. */
+declare function hashToken(token: string, pepper?: string): Promise<string>;
+declare function looksLikeJwt(token: string): boolean;
+declare function stripBearer(header: string | null | undefined): string | null;
+
+export { hashToken, looksLikeJwt, stripBearer };

package/dist/token.js

@@ -0,0 +1,10 @@
+import {
+  hashToken,
+  looksLikeJwt,
+  stripBearer
+} from "./chunk-VBIQJKUU.js";
+export {
+  hashToken,
+  looksLikeJwt,
+  stripBearer
+};

package/dist/url-helpers.d.ts

@@ -0,0 +1,11 @@
+declare function normalizeUrlLike(value: string): string;
+declare function getAuthPublicUrl(): string;
+declare function getAccountPublicUrl(): string;
+declare function getAppBasePath(defaultPath?: string): string;
+declare function getPublicSiteUrl(): string;
+declare function buildPublicUrl(pathOrUrl: string, fallbackOrigin?: string): string;
+declare function buildAuthLoginUrl(redirectTo: string, origin?: string): string;
+declare function buildAuthLogoutUrl(redirectTo: string, origin?: string): string;
+declare function buildAccountProfileUrl(): string;
+
+export { buildAccountProfileUrl, buildAuthLoginUrl, buildAuthLogoutUrl, buildPublicUrl, getAccountPublicUrl, getAppBasePath, getAuthPublicUrl, getPublicSiteUrl, normalizeUrlLike };

package/dist/url-helpers.js

@@ -0,0 +1,22 @@
+import {
+  buildAccountProfileUrl,
+  buildAuthLoginUrl,
+  buildAuthLogoutUrl,
+  buildPublicUrl,
+  getAccountPublicUrl,
+  getAppBasePath,
+  getAuthPublicUrl,
+  getPublicSiteUrl,
+  normalizeUrlLike
+} from "./chunk-3NJASEF4.js";
+export {
+  buildAccountProfileUrl,
+  buildAuthLoginUrl,
+  buildAuthLogoutUrl,
+  buildPublicUrl,
+  getAccountPublicUrl,
+  getAppBasePath,
+  getAuthPublicUrl,
+  getPublicSiteUrl,
+  normalizeUrlLike
+};

package/dist/zitadel.d.ts

@@ -0,0 +1,28 @@
+interface ZitadelConfig {
+    issuer: string;
+    audience?: string;
+}
+interface ZitadelClaims {
+    sub: string;
+    email?: string;
+    preferred_username?: string;
+    name?: string;
+    picture?: string;
+    exp?: number;
+    iss?: string;
+    aud?: string | string[];
+}
+interface ZitadelIdentity {
+    subject: string;
+    issuer: string;
+    email: string;
+    name: string;
+    picture?: string;
+}
+/**
+ * Verify a Zitadel JWT and return the identity.
+ * Returns null on any verification failure — never throws to the caller.
+ */
+declare function verifyZitadelToken(token: string, config: ZitadelConfig): Promise<ZitadelIdentity | null>;
+
+export { type ZitadelClaims, type ZitadelConfig, type ZitadelIdentity, verifyZitadelToken };

package/dist/zitadel.js

@@ -0,0 +1,6 @@
+import {
+  verifyZitadelToken
+} from "./chunk-BMPRMOI7.js";
+export {
+  verifyZitadelToken
+};

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@baseworks/auth",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js",
+    "./oidc": "./dist/oidc.js",
+    "./oidc-human": "./dist/oidc-human.js",
+    "./pkce": "./dist/pkce.js",
+    "./cli-auth": "./dist/cli-auth.js",
+    "./token": "./dist/token.js",
+    "./session": "./dist/session.js",
+    "./url-helpers": "./dist/url-helpers.js",
+    "./edge": "./dist/edge.js",
+    "./zitadel": "./dist/zitadel.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@baseworks/core": "^0.2.0",
+    "jose": "^6.2.3"
+  },
+  "peerDependencies": {
+    "next": ">=15.0.0"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@baseworks/tsconfig": "workspace:*",
+    "@types/node": "^26.0.1",
+    "tsup": "^8.5.1",
+    "typescript": "^5.6.0"
+  }
+}

package/src/cli-auth.ts

@@ -0,0 +1,103 @@
+/**
+ * CLI authentication helpers — PKCE polling flow.
+ * Used by any CLI tool that authenticates via an orbseal-compatible API.
+ *
+ * Flow:
+ *   1. startCliAuth()  → get state + URL to show user
+ *   2. pollCliAuth()   → long-poll until user completes browser auth
+ */
+
+export interface CliAuthStart {
+  state:     string;
+  url:       string;
+  expiresIn: number;   // seconds
+}
+
+export interface CliAuthResult {
+  token: string;
+}
+
+export interface PollOptions {
+  /** ms between polls (default: 2000) */
+  intervalMs?: number;
+  /** ms before giving up (default: 300_000 = 5 min) */
+  timeoutMs?:  number;
+}
+
+/**
+ * Call the API to initiate CLI login.
+ * Returns the state handle and the URL the user should open.
+ */
+export async function startCliAuth(apiBase: string): Promise<CliAuthStart> {
+  const url = `${apiBase.replace(/\/+$/, '')}/v1/auth/start`;
+  const res = await fetch(url);
+
+  if (!res.ok) {
+    const text = await res.text().catch(() => res.statusText);
+    throw new Error(`Auth start failed (${res.status}): ${text}`);
+  }
+
+  const data = await res.json() as {
+    state?:      string;
+    url?:        string;
+    expires_in?: number;
+  };
+
+  if (!data.state || !data.url) {
+    throw new Error('Invalid response from auth/start');
+  }
+
+  return {
+    state:     data.state,
+    url:       data.url,
+    expiresIn: data.expires_in ?? 600,
+  };
+}
+
+/**
+ * Poll the API until the user completes browser auth.
+ * Resolves with the token when done, rejects on timeout or error.
+ */
+export async function pollCliAuth(
+  apiBase: string,
+  state:   string,
+  opts:    PollOptions = {},
+): Promise<CliAuthResult> {
+  const intervalMs = opts.intervalMs ?? 2_000;
+  const timeoutMs  = opts.timeoutMs  ?? 300_000;
+  const base       = apiBase.replace(/\/+$/, '');
+  const deadline   = Date.now() + timeoutMs;
+
+  while (Date.now() < deadline) {
+    await sleep(intervalMs);
+
+    const res = await fetch(`${base}/v1/auth/poll/${state}`);
+
+    if (!res.ok) {
+      throw new Error(`Poll failed (${res.status})`);
+    }
+
+    const data = await res.json() as {
+      status?: string;
+      token?:  string;
+    };
+
+    if (data.status === 'done' && data.token) {
+      return { token: data.token };
+    }
+
+    if (data.status === 'expired') {
+      throw new Error('Auth session expired — run login again');
+    }
+
+    // status === "pending" → continue polling
+  }
+
+  throw new Error('Auth timed out — run login again');
+}
+
+// ─── helpers ────────────────────────────────────────────────────────────────
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}