@elixpo/lixblogs-cli 1.1.2

package/src/auth/AuthProvider.js

@@ -0,0 +1,90 @@
+/**
+ * AuthProvider — the single interface every auth implementation must satisfy.
+ *
+ * No CLI or API code should ever call a provider-specific method directly.
+ * Everything goes through this interface, so swapping MockAuthProvider for
+ * the real ElixpoAuthProvider (once accounts.elixpo.com confirms device-flow
+ * support) requires no changes to calling code.
+ *
+ * See: elixpo/blogs.elixpo#137 for the full requirements this interface
+ * exists to satisfy.
+ */
+
+/**
+ * @typedef {Object} DeviceCodeResponse
+ * @property {string} deviceCode - Opaque code the client polls with.
+ * @property {string} userCode - Short code the user enters at verificationUri.
+ * @property {string} verificationUri - URL the user visits to approve login.
+ * @property {string} [verificationUriComplete] - Approval URL with user code pre-filled.
+ * @property {number} expiresInSeconds - How long the device code is valid for.
+ * @property {number} pollIntervalSeconds - Minimum seconds between poll attempts.
+ */
+
+/**
+ * @typedef {Object} TokenResponse
+ * @property {string} accessToken
+ * @property {string} refreshToken
+ * @property {number} expiresInSeconds
+ * @property {string[]} scopes - Scopes actually granted (may be a subset of requested).
+ */
+
+/**
+ * @typedef {"pending"|"approved"|"denied"|"expired"|"slow_down"} PollStatus
+ */
+
+/**
+ * @typedef {Object} PollResult
+ * @property {PollStatus} status
+ * @property {TokenResponse} [token] - Present only when status === "approved".
+ * @property {number} [pollIntervalIncreaseSeconds] - Present only when
+ *   status === "slow_down". Caller must add this to its current polling
+ *   interval before the next poll (RFC 8628 §3.5 behavior).
+ */
+
+export class AuthProvider {
+  /**
+   * Identifies which implementation this is. Used by the production safety
+   * gate to refuse anything but the approved provider in production.
+   * @returns {string} e.g. "mock" | "elixpo"
+   */
+  get providerId() {
+    throw new Error("AuthProvider.providerId must be implemented by subclass");
+  }
+
+  /**
+   * Start a device authorization request.
+   * @param {{ scopes: string[] }} params
+   * @returns {Promise<DeviceCodeResponse>}
+   */
+  async requestDeviceCode(_params) {
+    throw new Error("AuthProvider.requestDeviceCode must be implemented by subclass");
+  }
+
+  /**
+   * Poll for whether the user has approved/denied the device code yet.
+   * Callers are responsible for respecting pollIntervalSeconds between calls.
+   * @param {{ deviceCode: string }} params
+   * @returns {Promise<PollResult>}
+   */
+  async pollDeviceCode(_params) {
+    throw new Error("AuthProvider.pollDeviceCode must be implemented by subclass");
+  }
+
+  /**
+   * Exchange a refresh token for a new access token.
+   * @param {{ refreshToken: string, scopes?: string[] }} params
+   * @returns {Promise<TokenResponse>}
+   */
+  async refresh(_params) {
+    throw new Error("AuthProvider.refresh must be implemented by subclass");
+  }
+
+  /**
+   * Revoke a token (access or refresh). Must not throw if already revoked.
+   * @param {{ token: string }} params
+   * @returns {Promise<void>}
+   */
+  async revoke(_params) {
+    throw new Error("AuthProvider.revoke must be implemented by subclass");
+  }
+}

package/src/auth/AuthenticatedClient.js

@@ -0,0 +1,116 @@
+import { AuthProviderError } from "./ElixpoAuthProvider.js";
+
+const DEFAULT_REFRESH_SKEW_MS = 60_000;
+const storeLocks = new WeakMap();
+
+function profileLocks(credentialStore) {
+  let locks = storeLocks.get(credentialStore);
+  if (!locks) {
+    locks = new Map();
+    storeLocks.set(credentialStore, locks);
+  }
+  return locks;
+}
+
+export class LoginRequiredError extends Error {
+  constructor(profileId) {
+    super(`Profile "${profileId}" needs to log in again.`);
+    this.name = "LoginRequiredError";
+    this.code = "login_required";
+  }
+}
+
+export class AuthenticatedClient {
+  constructor({
+    provider,
+    credentialStore,
+    profileId,
+    apiBaseUrl = "https://blogs.elixpo.com",
+    fetchImpl = globalThis.fetch,
+    refreshSkewMs = DEFAULT_REFRESH_SKEW_MS,
+  }) {
+    this.provider = provider;
+    this.credentialStore = credentialStore;
+    this.profileId = profileId;
+    this.apiBaseUrl = new URL(apiBaseUrl);
+    this.fetchImpl = fetchImpl;
+    this.refreshSkewMs = refreshSkewMs;
+  }
+
+  async _refresh(credentials, { force = false } = {}) {
+    const locks = profileLocks(this.credentialStore);
+    const existing = locks.get(this.profileId);
+    if (existing) return existing;
+
+    const operation = (async () => {
+      const latest = (await this.credentialStore.get(this.profileId)) || credentials;
+      if (!force && latest.expiresAt - Date.now() > this.refreshSkewMs) return latest;
+      try {
+        const token = await this.provider.refresh({
+          refreshToken: latest.refreshToken,
+          scopes: latest.scopes,
+        });
+        const rotated = {
+          accessToken: token.accessToken,
+          refreshToken: token.refreshToken,
+          expiresAt: Date.now() + token.expiresInSeconds * 1000,
+          scopes: token.scopes,
+        };
+        await this.credentialStore.set(this.profileId, rotated);
+        return rotated;
+      } catch (error) {
+        if (error instanceof AuthProviderError && error.requiresLogin) {
+          await this.credentialStore.delete(this.profileId);
+          throw new LoginRequiredError(this.profileId);
+        }
+        throw error;
+      }
+    })();
+
+    locks.set(this.profileId, operation);
+    try {
+      return await operation;
+    } finally {
+      if (locks.get(this.profileId) === operation) locks.delete(this.profileId);
+    }
+  }
+
+  async credentials({ forceRefresh = false } = {}) {
+    const stored = await this.credentialStore.get(this.profileId);
+    if (!stored) throw new LoginRequiredError(this.profileId);
+    if (forceRefresh || stored.expiresAt - Date.now() <= this.refreshSkewMs) {
+      return this._refresh(stored, { force: forceRefresh });
+    }
+    return stored;
+  }
+
+  async request(url, options = {}) {
+    const target = new URL(url, this.apiBaseUrl);
+    if (target.origin !== this.apiBaseUrl.origin || !target.pathname.startsWith("/api/v1/")) {
+      throw new Error("Authenticated CLI requests are restricted to the configured LixBlogs /api/v1 resource server.");
+    }
+    let credentials = await this.credentials();
+    const send = () => this.fetchImpl(target.toString(), {
+      ...options,
+      headers: { ...options.headers, authorization: `Bearer ${credentials.accessToken}` },
+    });
+    let response = await send();
+    if (response.status === 401) {
+      credentials = await this.credentials({ forceRefresh: true });
+      response = await send();
+    }
+    return response;
+  }
+
+  async requireScopes(required) {
+    const credentials = await this.credentials();
+    const missing = required.filter((scope) => !credentials.scopes.includes(scope));
+    if (missing.length) {
+      const error = new Error(`Login again with the required scope${missing.length > 1 ? 's' : ''}: ${missing.join(', ')}`);
+      error.name = 'InsufficientScopeError';
+      error.code = 'insufficient_scope';
+      error.missingScopes = missing;
+      throw error;
+    }
+  }
+}

package/src/auth/ElixpoAuthProvider.js

@@ -0,0 +1,281 @@
+import { AuthProvider } from "./AuthProvider.js";
+
+const DEVICE_GRANT = "urn:ietf:params:oauth:grant-type:device_code";
+const SUPPORTED_CONTRACT_MAJOR = 1;
+const DEFAULT_TIMEOUT_MS = 15_000;
+
+const SAFE_ERROR_MESSAGES = {
+  access_denied: "Login was denied.",
+  authorization_pending: "Login is awaiting approval.",
+  expired_token: "The device authorization expired. Start login again.",
+  invalid_client: "The LixBlogs CLI client is not registered for this environment.",
+  invalid_grant: "This session is no longer valid. Log in again.",
+  invalid_request: "Accounts rejected the authentication request.",
+  invalid_scope: "The requested LixBlogs permissions are not available for this client.",
+  server_error: "Accounts could not complete authentication. Try again later.",
+  slow_down: "Accounts requested slower polling.",
+  temporarily_unavailable: "Accounts is temporarily unavailable. Try again later.",
+};
+
+export class AuthProviderError extends Error {
+  constructor(code, { status = 0, requiresLogin = false } = {}) {
+    super(SAFE_ERROR_MESSAGES[code] || "Authentication failed.");
+    this.name = "AuthProviderError";
+    this.code = code || "authentication_failed";
+    this.status = status;
+    this.requiresLogin = requiresLogin;
+  }
+}
+
+export class CompatibilityError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "CompatibilityError";
+    this.code = "incompatible_accounts_contract";
+  }
+}
+
+function versionParts(value) {
+  return String(value || "0.0.0")
+    .split(".")
+    .slice(0, 3)
+    .map((part) => Number.parseInt(part, 10) || 0);
+}
+
+function versionAtLeast(current, minimum) {
+  const left = versionParts(current);
+  const right = versionParts(minimum);
+  for (let index = 0; index < 3; index += 1) {
+    if (left[index] !== right[index]) return left[index] > right[index];
+  }
+  return true;
+}
+
+function normalizeBaseUrl(value) {
+  const url = new URL(value);
+  url.pathname = url.pathname.replace(/\/$/, "");
+  url.search = "";
+  url.hash = "";
+  if (url.protocol !== "https:" && url.hostname !== "localhost" && url.hostname !== "127.0.0.1") {
+    throw new CompatibilityError("Accounts must use HTTPS outside local development.");
+  }
+  return url.toString().replace(/\/$/, "");
+}
+
+async function responseJson(response) {
+  try {
+    return await response.json();
+  } catch {
+    throw new AuthProviderError("server_error", { status: response.status });
+  }
+}
+
+function oauthError(payload, response) {
+  const code = typeof payload?.error === "string" ? payload.error : "server_error";
+  return new AuthProviderError(code, {
+    status: response.status,
+    requiresLogin: code === "invalid_grant" || code === "access_denied" || code === "expired_token",
+  });
+}
+
+function tokenResponse(payload, response) {
+  if (!response.ok) throw oauthError(payload, response);
+  if (
+    typeof payload?.access_token !== "string" ||
+    typeof payload?.refresh_token !== "string" ||
+    !Number.isFinite(Number(payload?.expires_in))
+  ) {
+    throw new AuthProviderError("server_error", { status: response.status });
+  }
+  return {
+    accessToken: payload.access_token,
+    refreshToken: payload.refresh_token,
+    expiresInSeconds: Number(payload.expires_in),
+    scopes: typeof payload.scope === "string" ? payload.scope.split(/\s+/).filter(Boolean) : [],
+  };
+}
+
+export class ElixpoAuthProvider extends AuthProvider {
+  constructor({
+    accountsBaseUrl = "https://accounts.elixpo.com",
+    clientId = "lixblogs-cli-prod",
+    audience = "blogs.elixpo.com",
+    cliVersion = "1.1.0",
+    fetchImpl = globalThis.fetch,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+  } = {}) {
+    super();
+    if (typeof fetchImpl !== "function") throw new TypeError("A fetch implementation is required.");
+    this.accountsBaseUrl = normalizeBaseUrl(accountsBaseUrl);
+    this.clientId = clientId;
+    this.audience = audience;
+    this.cliVersion = cliVersion;
+    this.fetchImpl = fetchImpl;
+    this.timeoutMs = timeoutMs;
+    this._metadata = null;
+    this._discoveryPromise = null;
+  }
+
+  get providerId() {
+    return "elixpo";
+  }
+
+  async _fetch(url, options = {}) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await this.fetchImpl(url, {
+        ...options,
+        signal: options.signal || controller.signal,
+        headers: { accept: "application/json", ...options.headers },
+      });
+    } catch {
+      throw new AuthProviderError("temporarily_unavailable");
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
+  async discover({ scopes = [] } = {}) {
+    if (!this._metadata) {
+      if (!this._discoveryPromise) this._discoveryPromise = this._loadDiscovery();
+      try {
+        this._metadata = await this._discoveryPromise;
+      } finally {
+        this._discoveryPromise = null;
+      }
+    }
+
+    const unsupported = scopes.filter((scope) => !this._metadata.scopes_supported.includes(scope));
+    if (unsupported.length) throw new AuthProviderError("invalid_scope");
+    return this._metadata;
+  }
+
+  async _loadDiscovery() {
+    const response = await this._fetch(`${this.accountsBaseUrl}/.well-known/oauth-authorization-server`);
+    const metadata = await responseJson(response);
+    if (!response.ok) throw new AuthProviderError("temporarily_unavailable", { status: response.status });
+
+    const contractMajor = versionParts(metadata.elixpo_contract_version)[0];
+    if (contractMajor !== SUPPORTED_CONTRACT_MAJOR) {
+      throw new CompatibilityError("Accounts uses an unsupported device-flow contract version.");
+    }
+    if (!versionAtLeast(this.cliVersion, metadata.elixpo_min_compatible_cli_version)) {
+      throw new CompatibilityError(
+        `This CLI is too old for Accounts. Upgrade to version ${metadata.elixpo_min_compatible_cli_version} or newer.`,
+      );
+    }
+    if (!Array.isArray(metadata.grant_types_supported) || !metadata.grant_types_supported.includes(DEVICE_GRANT)) {
+      throw new CompatibilityError("Accounts does not advertise OAuth device authorization.");
+    }
+
+    const requiredEndpoints = [
+      "device_authorization_endpoint",
+      "token_endpoint",
+      "revocation_endpoint",
+    ];
+    for (const field of requiredEndpoints) {
+      if (typeof metadata[field] !== "string") {
+        throw new CompatibilityError(`Accounts discovery is missing ${field}.`);
+      }
+      const endpoint = new URL(metadata[field]);
+      const accounts = new URL(this.accountsBaseUrl);
+      if (endpoint.origin !== accounts.origin) {
+        throw new CompatibilityError(`Accounts discovery returned an untrusted ${field}.`);
+      }
+    }
+
+    return {
+      ...metadata,
+      scopes_supported: Array.isArray(metadata.scopes_supported) ? metadata.scopes_supported : [],
+    };
+  }
+
+  async requestDeviceCode({ scopes }) {
+    const metadata = await this.discover({ scopes });
+    const response = await this._fetch(metadata.device_authorization_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        client_id: this.clientId,
+        scope: scopes.join(" "),
+        audience: this.audience,
+      }),
+    });
+    const payload = await responseJson(response);
+    if (!response.ok) throw oauthError(payload, response);
+    if (
+      typeof payload.device_code !== "string" ||
+      typeof payload.user_code !== "string" ||
+      typeof payload.verification_uri !== "string"
+    ) {
+      throw new AuthProviderError("server_error", { status: response.status });
+    }
+    return {
+      deviceCode: payload.device_code,
+      userCode: payload.user_code,
+      verificationUri: payload.verification_uri,
+      verificationUriComplete: payload.verification_uri_complete || payload.verification_uri,
+      expiresInSeconds: Number(payload.expires_in) || 600,
+      pollIntervalSeconds: Number(payload.interval) || 5,
+    };
+  }
+
+  async pollDeviceCode({ deviceCode }) {
+    const metadata = await this.discover();
+    const body = new URLSearchParams({
+      grant_type: DEVICE_GRANT,
+      device_code: deviceCode,
+      client_id: this.clientId,
+    });
+    const response = await this._fetch(metadata.token_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body,
+    });
+    const payload = await responseJson(response);
+    if (response.ok) return { status: "approved", token: tokenResponse(payload, response) };
+    if (payload?.error === "authorization_pending") return { status: "pending" };
+    if (payload?.error === "slow_down") {
+      const polling = metadata.elixpo_device_flow_polling || {};
+      const increase = Math.max(
+        5,
+        Number(polling.slow_down_interval_seconds || 10) - Number(polling.interval_seconds || 5),
+      );
+      return { status: "slow_down", pollIntervalIncreaseSeconds: increase };
+    }
+    if (payload?.error === "access_denied") return { status: "denied" };
+    if (payload?.error === "expired_token") return { status: "expired" };
+    throw oauthError(payload, response);
+  }
+
+  async refresh({ refreshToken, scopes }) {
+    const metadata = await this.discover({ scopes: scopes || [] });
+    const body = new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      client_id: this.clientId,
+    });
+    if (scopes?.length) body.set("scope", scopes.join(" "));
+    const response = await this._fetch(metadata.token_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body,
+    });
+    const payload = await responseJson(response);
+    return tokenResponse(payload, response);
+  }
+
+  async revoke({ token }) {
+    const metadata = await this.discover();
+    const response = await this._fetch(metadata.revocation_endpoint, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body: new URLSearchParams({ token, client_id: this.clientId }),
+    });
+    if (!response.ok) {
+      const payload = await responseJson(response);
+      throw oauthError(payload, response);
+    }
+  }
+}

package/src/auth/MockAuthProvider.js

@@ -0,0 +1,170 @@
+import { AuthProvider } from "./AuthProvider.js";
+
+/**
+ * MockAuthProvider — deterministic, in-memory device-flow simulation for
+ * development and tests. Never talks to a real server.
+ *
+ * Per maintainer direction: this exists so CLI/UI work isn't blocked while
+ * accounts.elixpo.com's device-flow support has no confirmed ETA. This must
+ * never be reachable in a production configuration — see
+ * assertNotProduction() in productionGate.js, which every provider
+ * constructor call should be routed through at the call site.
+ *
+ * States simulated (mirroring "Device login, refresh, logout, revocation,
+ * expiry, denial, and polling errors are tested" from #135's acceptance
+ * criteria):
+ *   - approved (successful login)
+ *   - pending (still polling)
+ *   - denied
+ *   - expired
+ *   - invalid/unknown device code
+ *   - slow_down (RFC 8628 §3.5 style rate-limit signal)
+ *   - refresh success / refresh failure
+ *   - revoke
+ *
+ * Scenario selection is deterministic and driven by the deviceCode's prefix,
+ * not randomness — so tests are reproducible. See SCENARIO_PREFIX below.
+ *
+ * --- Open questions from elixpo/blogs.elixpo#137, resolved by implementer ---
+ * - Mock states: slow_down added (see above), matching RFC 8628 rather than
+ *   inventing a bespoke rate-limit shape, so the real ElixpoAuthProvider can
+ *   follow the same contract later.
+ * - Polling/backoff: on slow_down, caller must increase its poll interval by
+ *   SLOW_DOWN_INTERVAL_INCREASE_SECONDS before polling again. No other
+ *   backoff logic in the mock itself — backoff is the CLI's responsibility,
+ *   not the provider's.
+ * Flagged for the maintainer to override if a different behavior is wanted.
+ */
+
+const SCENARIO_PREFIX = {
+  APPROVE_IMMEDIATELY: "mock-approve-",
+  PENDING_THEN_APPROVE: "mock-pending-then-approve-",
+  DENY: "mock-deny-",
+  EXPIRE: "mock-expire-",
+  SLOW_DOWN_THEN_APPROVE: "mock-slow-down-then-approve-",
+};
+
+// Mirrors RFC 8628 §3.5: on slow_down, the client must increase its polling
+// interval by this many seconds. Real ElixpoAuthProvider should follow the
+// same contract so CLI polling logic doesn't need a provider-specific branch.
+const SLOW_DOWN_INTERVAL_INCREASE_SECONDS = 5;
+
+let counter = 0;
+function nextId(prefix) {
+  counter += 1;
+  return `${prefix}${counter}`;
+}
+
+export class MockAuthProvider extends AuthProvider {
+  constructor() {
+    super();
+    /** @type {Map<string, { scenario: string, pollCount: number, createdAt: number, scopes: string[] }>} */
+    this._devicesCodes = new Map();
+    /** @type {Set<string>} revoked tokens */
+    this._revoked = new Set();
+    /** @type {Set<string>} tokens that will fail on next refresh (for testing refresh failure) */
+    this._refreshWillFail = new Set();
+  }
+
+  get providerId() {
+    return "mock";
+  }
+
+  /**
+   * @param {{ scopes: string[], scenario?: keyof typeof SCENARIO_PREFIX }} params
+   *   `scenario` lets tests/dev deterministically choose which path this
+   *   device code will take. Defaults to APPROVE_IMMEDIATELY.
+   */
+  async requestDeviceCode({ scopes, scenario = "APPROVE_IMMEDIATELY" }) {
+    const prefix = SCENARIO_PREFIX[scenario] ?? SCENARIO_PREFIX.APPROVE_IMMEDIATELY;
+    const deviceCode = nextId(prefix);
+    const userCode = deviceCode.slice(-6).toUpperCase();
+
+    this._devicesCodes.set(deviceCode, {
+      scenario,
+      pollCount: 0,
+      createdAt: Date.now(),
+      scopes: [...scopes],
+    });
+
+    return {
+      deviceCode,
+      userCode,
+      verificationUri: "https://mock.lixblogs.local/device",
+      verificationUriComplete: `https://mock.lixblogs.local/device?user_code=${encodeURIComponent(userCode)}`,
+      expiresInSeconds: scenario === "EXPIRE" ? 1 : 600,
+      pollIntervalSeconds: 1,
+    };
+  }
+
+  async pollDeviceCode({ deviceCode }) {
+    const record = this._devicesCodes.get(deviceCode);
+
+    if (!record) {
+      // Unknown/invalid code — distinct from "expired": this code never existed.
+      return { status: "denied" };
+    }
+
+    if (record.scenario === "EXPIRE") {
+      return { status: "expired" };
+    }
+
+    if (record.scenario === "DENY") {
+      return { status: "denied" };
+    }
+
+    if (record.scenario === "PENDING_THEN_APPROVE") {
+      record.pollCount += 1;
+      if (record.pollCount < 2) {
+        return { status: "pending" };
+      }
+      // fall through to approve on the 2nd+ poll
+    }
+
+    if (record.scenario === "SLOW_DOWN_THEN_APPROVE") {
+      record.pollCount += 1;
+      if (record.pollCount < 2) {
+        return {
+          status: "slow_down",
+          pollIntervalIncreaseSeconds: SLOW_DOWN_INTERVAL_INCREASE_SECONDS,
+        };
+      }
+      // fall through to approve on the 2nd+ poll
+    }
+
+    return {
+      status: "approved",
+      token: {
+        accessToken: `mock-access-${deviceCode}`,
+        refreshToken: `mock-refresh-${deviceCode}`,
+        expiresInSeconds: 3600,
+        scopes: record.scopes,
+      },
+    };
+  }
+
+  async refresh({ refreshToken, scopes = [] }) {
+    if (this._revoked.has(refreshToken)) {
+      throw new Error("refresh token has been revoked");
+    }
+    if (this._refreshWillFail.has(refreshToken)) {
+      throw new Error("mock refresh failure (test-injected)");
+    }
+    return {
+      accessToken: `mock-access-refreshed-${refreshToken}`,
+      refreshToken,
+      expiresInSeconds: 3600,
+      scopes,
+    };
+  }
+
+  async revoke({ token }) {
+    // Must not throw if already revoked — revocation is idempotent.
+    this._revoked.add(token);
+  }
+
+  /** Test helper: force the next refresh() call for this token to fail. */
+  _simulateRefreshFailureFor(refreshToken) {
+    this._refreshWillFail.add(refreshToken);
+  }
+}

package/src/auth/productionGate.js

@@ -0,0 +1,44 @@
+/**
+ * Production safety gate.
+ *
+ * Maintainer's explicit requirement (verbatim):
+ *   "Production login must remain explicitly unavailable until the real
+ *   issuer, polling, refresh, scope, and revocation contract is approved —
+ *   no copied cookies or fallback credentials."
+ *
+ * This must fail loudly and immediately — not silently degrade, not warn
+ * and continue. Every call site that constructs an AuthProvider must route
+ * through assertProviderAllowed() first.
+ *
+ * Accounts now publishes the approved RFC 8628 contract, so production is
+ * enabled only for ElixpoAuthProvider. The deterministic mock remains usable
+ * in explicit development/test environments and can never cross this gate.
+ */
+
+const APPROVED_PRODUCTION_PROVIDER_ID = "elixpo";
+
+export class ProductionAuthGateError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ProductionAuthGateError";
+  }
+}
+
+/**
+ * @param {{ providerId: string, environment: string }} params
+ *   `environment` should come from explicit config, not inferred/guessed.
+ */
+export function assertProviderAllowed({ providerId, environment }) {
+  const isProduction = environment === "production";
+
+  if (!isProduction) {
+    return; // any provider (including mock) is fine outside production
+  }
+
+  if (providerId !== APPROVED_PRODUCTION_PROVIDER_ID) {
+    throw new ProductionAuthGateError(
+      `Provider "${providerId}" is not approved for production. ` +
+        `Only "${APPROVED_PRODUCTION_PROVIDER_ID}" may be used in production.`
+    );
+  }
+}