@xera-ai/core 0.4.4 → 0.8.0

package/dist/src/index.js

@@ -113,7 +113,10 @@ var ClassificationEnum = z2.enum([
   "SELECTOR_DRIFT",
   "FLAKY",
   "TEST_BUG",
-  "TEST_OUTDATED"
+  "TEST_OUTDATED",
+  "CONTRACT_DRIFT",
+  "RATE_LIMITED",
+  "AUTH_EXPIRED"
 ]);
 var ResultEnum = z2.enum(["PASS", "FAIL"]);
 var ConfidenceEnum = z2.enum(["low", "medium", "high"]);
@@ -297,6 +300,32 @@ var WebSchema = z4.object({
   message: "defaultEnv must exist in baseUrl map",
   path: ["defaultEnv"]
 });
+var HttpAuthRoleSchema = z4.object({
+  tokenEnv: z4.string().optional(),
+  userEnv: z4.string().optional(),
+  passEnv: z4.string().optional(),
+  tokenUrl: z4.string().url().optional(),
+  clientIdEnv: z4.string().optional(),
+  clientSecretEnv: z4.string().optional(),
+  scope: z4.string().optional()
+});
+var HttpAuthSchema = z4.object({
+  strategy: z4.enum(["bearer", "apiKey", "basic", "oauth-cc", "custom", "none"]).default("none"),
+  ttl: z4.string().default("8h"),
+  refreshBuffer: z4.string().default("30m"),
+  roles: z4.record(z4.string(), HttpAuthRoleSchema).default({})
+});
+var HttpSchema = z4.object({
+  baseUrl: z4.record(z4.string(), z4.string().url()).refine((m) => Object.keys(m).length > 0, {
+    message: "baseUrl must have at least one environment"
+  }),
+  defaultEnv: z4.string(),
+  spec: z4.string().optional(),
+  auth: HttpAuthSchema.prefault({})
+}).refine((h) => h.baseUrl[h.defaultEnv] !== undefined, {
+  message: "defaultEnv must exist in baseUrl map",
+  path: ["defaultEnv"]
+});
 var JiraSchema = z4.object({
   baseUrl: z4.string().url(),
   projectKeys: z4.array(z4.string().min(1)).min(1),
@@ -332,11 +361,17 @@ var RunSchema = z4.object({
 }).prefault({});
 var XeraConfigSchema = z4.object({
   jira: JiraSchema,
-  web: WebSchema,
+  web: WebSchema.optional(),
+  http: HttpSchema.optional(),
   ai: AISchema,
   reporting: ReportingSchema,
   run: RunSchema.prefault({}),
-  adapters: z4.array(z4.string().min(1)).min(1).default(["web"])
+  adapters: z4.array(z4.enum(["web", "http"])).min(1).default(["web"])
+}).refine((c) => c.web !== undefined || c.http !== undefined, {
+  message: "At least one of `web` or `http` must be configured"
+}).refine((c) => c.adapters.every((a) => (a === "web" ? c.web : c.http) !== undefined), {
+  message: "Every adapter in `adapters` must have a corresponding config block",
+  path: ["adapters"]
 });
 
 // src/config/load.ts
@@ -585,7 +620,66 @@ class NdjsonLogger {
 `).map((line) => JSON.parse(line));
   }
 }
-
+// src/scrub/rules.ts
+var SENSITIVE_HEADERS = [
+  "authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "x-auth-token",
+  "x-csrf-token",
+  "proxy-authorization"
+];
+var SENSITIVE_BODY_KEYS = [
+  /password/i,
+  /passwd/i,
+  /token/i,
+  /secret/i,
+  /api[-_]?key/i,
+  /access[-_]?key/i,
+  /private[-_]?key/i,
+  /authorization/i,
+  /credit[-_]?card/i,
+  /card[-_]?number/i,
+  /cvv/i
+];
+var JWT_RE = /\beyJ[A-Za-z0-9_-]{7,}\.[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{5,}\b/;
+var CREDIT_CARD_RE = /\b(?:\d{4}[-\s]?){3}\d{4}\b/;
+var EMAIL_RE = /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}\b/;
+var PHONE_RE = /(?:\+?\d[\d\s().-]{6,}\d)/;
+var JWT_RE_G = new RegExp(JWT_RE.source, "g");
+var CREDIT_CARD_RE_G = new RegExp(CREDIT_CARD_RE.source, "g");
+var EMAIL_RE_G = new RegExp(EMAIL_RE.source, "g");
+var PHONE_RE_G = new RegExp(PHONE_RE.source, "g");
+var REDACTED = "[REDACTED]";
+function scrubHeaders(headers) {
+  const out = {};
+  for (const [k, v] of Object.entries(headers)) {
+    out[k] = SENSITIVE_HEADERS.includes(k.toLowerCase()) ? REDACTED : v;
+  }
+  return out;
+}
+function scrubBodyJson(body) {
+  if (Array.isArray(body))
+    return body.map(scrubBodyJson);
+  if (body && typeof body === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(body)) {
+      if (SENSITIVE_BODY_KEYS.some((re) => re.test(k))) {
+        out[k] = REDACTED;
+      } else {
+        out[k] = scrubBodyJson(v);
+      }
+    }
+    return out;
+  }
+  if (typeof body === "string")
+    return scrubFreeText(body);
+  return body;
+}
+function scrubFreeText(s) {
+  return s.replace(JWT_RE_G, REDACTED).replace(CREDIT_CARD_RE_G, REDACTED).replace(EMAIL_RE_G, REDACTED).replace(PHONE_RE_G, REDACTED);
+}
 // src/index.ts
 var VERSION2 = "0.1.0";
 export {
@@ -594,6 +688,9 @@ export {
   writeAuthState,
   withRetry,
   updateMeta,
+  scrubHeaders,
+  scrubFreeText,
+  scrubBodyJson,
   resolveAuthKey,
   resolveArtifactPaths,
   releaseLock,
@@ -621,9 +718,17 @@ export {
   XeraConfigSchema,
   VERSION2 as VERSION,
   StatusJsonSchema,
+  SENSITIVE_HEADERS,
+  SENSITIVE_BODY_KEYS,
+  PHONE_RE_G,
+  PHONE_RE,
   NdjsonLogger,
   MetaJsonSchema,
+  JWT_RE,
   HistoryEntrySchema,
+  EMAIL_RE_G,
+  EMAIL_RE,
+  CREDIT_CARD_RE,
   AuthStateEntrySchema,
   AUTH_KEY_ENV
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xera-ai/core",
-  "version": "0.4.4",
+  "version": "0.8.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,12 +25,14 @@
     "bin"
   ],
   "scripts": {
-    "build": "bun build ./src/index.ts ./bin/internal.ts --outdir ./dist --target bun --external @playwright/test --external @xera-ai/web --external zod",
-    "typecheck": "tsc --noEmit"
+    "build": "bun build ./src/index.ts ./bin/internal.ts --outdir ./dist --target bun --external @playwright/test --external @xera-ai/web --external @xera-ai/http --external zod",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build"
   },
   "dependencies": {
     "zod": "4.4.3",
-    "@xera-ai/web": "^0.2.0",
+    "@xera-ai/web": "^0.8.0",
+    "@xera-ai/http": "^0.8.0",
     "@playwright/test": "1.60.0",
     "fflate": "0.8.3",
     "yaml": "2.9.0"

package/src/artifact/status.ts

@@ -9,6 +9,9 @@ const ClassificationEnum = z.enum([
   'FLAKY',
   'TEST_BUG',
   'TEST_OUTDATED',
+  'CONTRACT_DRIFT',
+  'RATE_LIMITED',
+  'AUTH_EXPIRED',
 ]);
 const ResultEnum = z.enum(['PASS', 'FAIL']);
 const ConfidenceEnum = z.enum(['low', 'medium', 'high']);

package/src/bin-internal/auth-setup.ts

@@ -0,0 +1,116 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { loadConfig } from '../config/load';
+
+interface AuthSetupOpts {
+  role?: string;
+  shape: 'web' | 'http' | 'all';
+}
+
+function parseOpts(argv: string[]): AuthSetupOpts {
+  const opts: AuthSetupOpts = { shape: 'all' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    const next = argv[i + 1];
+    if (a === '--role' && next) {
+      opts.role = next;
+      i++;
+    } else if (a === '--shape' && next) {
+      if (next === 'web' || next === 'http' || next === 'all') opts.shape = next;
+      i++;
+    }
+  }
+  return opts;
+}
+
+export async function authSetupCmd(argv: string[]): Promise<number> {
+  const opts = parseOpts(argv);
+  const cwd = process.cwd();
+  const config = await loadConfig(cwd);
+
+  const authSetupScript = join(cwd, 'shared', 'auth-setup.ts');
+  if (!existsSync(authSetupScript)) {
+    console.error(
+      `[xera:auth-setup] auth-setup.ts not found at ${authSetupScript}. Run 'bunx @xera-ai/cli init' first.`,
+    );
+    return 1;
+  }
+
+  const mod = (await import(pathToFileURL(authSetupScript).href)) as {
+    web?: unknown;
+    http?: unknown;
+  };
+
+  let exitCode = 0;
+
+  // Web roles
+  if (
+    (opts.shape === 'all' || opts.shape === 'web') &&
+    config.web &&
+    typeof mod.web === 'function'
+  ) {
+    const { runAuthSetup } = await import('@xera-ai/web');
+    const { chromium } = await import('@playwright/test');
+    const browser = await chromium.launch();
+    try {
+      for (const [roleName, roleCreds] of Object.entries(config.web.auth.roles)) {
+        if (opts.role && roleName !== opts.role) continue;
+        const email = process.env[roleCreds.envEmail];
+        const password = process.env[roleCreds.envPassword];
+        if (!email || !password) {
+          console.error(
+            `[xera:auth-setup] missing env vars ${roleCreds.envEmail} / ${roleCreds.envPassword} for role '${roleName}'`,
+          );
+          exitCode = 1;
+          continue;
+        }
+        try {
+          await runAuthSetup({
+            role: roleName,
+            creds: { email, password },
+            setupScriptPath: authSetupScript,
+            authDir: join(cwd, '.xera', '.auth'),
+            browser,
+          });
+          console.log(`[xera:auth-setup] ✓ ${roleName}.json (web)`);
+        } catch (e) {
+          console.error(`[xera:auth-setup] ✗ web/${roleName}: ${(e as Error).message}`);
+          exitCode = 1;
+        }
+      }
+    } finally {
+      await browser.close();
+    }
+  }
+
+  // Http roles
+  if (
+    (opts.shape === 'all' || opts.shape === 'http') &&
+    config.http &&
+    typeof mod.http === 'function'
+  ) {
+    // The auth-setup.ts template reads config via globalThis; set it for the user's function.
+    (globalThis as Record<string, unknown>).__XERA_HTTP_CONFIG__ = config.http;
+
+    const { runHttpAuthSetup } = await import('@xera-ai/http');
+    for (const roleName of Object.keys(config.http.auth.roles)) {
+      if (opts.role && roleName !== opts.role) continue;
+      try {
+        await runHttpAuthSetup({
+          authDir: join(cwd, '.xera', '.auth'),
+          role: roleName,
+          config: config.http,
+          setupFn: mod.http as Parameters<typeof runHttpAuthSetup>[0]['setupFn'],
+          creds: { email: '', password: '' },
+        });
+        console.log(`[xera:auth-setup] ✓ http/${roleName}.json`);
+      } catch (e) {
+        console.error(`[xera:auth-setup] ✗ http/${roleName}: ${(e as Error).message}`);
+        exitCode = 1;
+      }
+    }
+  }
+
+  return exitCode;
+}

package/src/bin-internal/exec.ts

@@ -2,6 +2,7 @@ import { existsSync, mkdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { chromium } from '@playwright/test';
 import { runAuthSetup, runPlaywright, stagePlaywrightState } from '@xera-ai/web';
+import { readMeta } from '../artifact/meta';
 import { generateRunId, resolveArtifactPaths } from '../artifact/paths';
 import { needsRefresh } from '../auth/refresh';
 import { readAuthState } from '../auth/state';
@@ -42,16 +43,48 @@ export async function execCmd(argv: string[]): Promise<number> {
 
   const t0 = Date.now();
   try {
+    const meta = readMeta(paths.metaPath);
+    const adapter = meta?.adapter ?? 'web';
+
+    if (adapter === 'http') {
+      if (!config.http) {
+        throw new Error('http adapter requires http config block');
+      }
+      const env = process.env['XERA_ENV'] ?? config.http.defaultEnv;
+      const { HttpAdapter } = await import('@xera-ai/http');
+      const result = await HttpAdapter.execute({
+        ticketDir: paths.ticketDir,
+        config,
+        runId,
+        env,
+      });
+      log.log({
+        step: 'exec.complete',
+        runId,
+        outcome: result.outcome,
+        elapsedMs: Date.now() - t0,
+      });
+      console.log(`[xera:exec] runId=${runId} outcome=${result.outcome}`);
+      // Exit 3 means "test failed" (expected vs infra error); lock released in finally
+      return result.outcome === 'PASS' ? 0 : 3;
+    }
+
+    // adapter === 'web' — existing path below unchanged
+    if (!config.web) {
+      throw new Error('web adapter requires web config block');
+    }
+    const webConfig = config.web;
+
     // Auth refresh per role declared in xera.config.ts
-    if (config.web.auth.strategy === 'storageState' && config.web.auth.setupScript) {
+    if (webConfig.auth.strategy === 'storageState' && webConfig.auth.setupScript) {
       const browser = await chromium.launch();
       try {
-        for (const [roleName, roleCreds] of Object.entries(config.web.auth.roles)) {
+        for (const [roleName, roleCreds] of Object.entries(webConfig.auth.roles)) {
           const entry = readAuthState(paths.authDir, roleName);
           if (
             needsRefresh(entry, {
-              ttl: config.web.auth.ttl,
-              refreshBuffer: config.web.auth.refreshBuffer,
+              ttl: webConfig.auth.ttl,
+              refreshBuffer: webConfig.auth.refreshBuffer,
             })
           ) {
             const email = process.env[roleCreds.envEmail];
@@ -65,7 +98,7 @@ export async function execCmd(argv: string[]): Promise<number> {
             await runAuthSetup({
               role: roleName,
               creds: { email, password },
-              setupScriptPath: join(cwd, config.web.auth.setupScript),
+              setupScriptPath: join(cwd, webConfig.auth.setupScript),
               authDir: paths.authDir,
               browser,
             });
@@ -80,8 +113,8 @@ export async function execCmd(argv: string[]): Promise<number> {
     // Stage Playwright storageState files at predictable paths
     // (.xera/.auth/.cache/<role>.json) — generated spec.ts references these
     // via test.use({ storageState }) when an authenticated session is needed.
-    if (config.web.auth.strategy === 'storageState') {
-      for (const roleName of Object.keys(config.web.auth.roles)) {
+    if (webConfig.auth.strategy === 'storageState') {
+      for (const roleName of Object.keys(webConfig.auth.roles)) {
         if (readAuthState(paths.authDir, roleName)) {
           stagePlaywrightState(paths.authDir, roleName);
         }
@@ -101,8 +134,8 @@ export async function execCmd(argv: string[]): Promise<number> {
     const runDir = paths.runPath(runId).runDir;
     mkdirSync(runDir, { recursive: true });
 
-    const envName = process.env.XERA_ENV ?? config.web.defaultEnv;
-    const baseURL = config.web.baseUrl[envName] ?? config.web.baseUrl[config.web.defaultEnv]!;
+    const envName = process.env.XERA_ENV ?? webConfig.defaultEnv;
+    const baseURL = webConfig.baseUrl[envName] ?? webConfig.baseUrl[webConfig.defaultEnv]!;
 
     const reportJsonPath = join(runDir, 'report.json');
 

package/src/bin-internal/graph-record.ts

@@ -261,6 +261,9 @@ export async function graphRecordCmd(argv: string[]): Promise<number> {
         'FLAKY',
         'PASS',
         'TEST_OUTDATED',
+        'CONTRACT_DRIFT',
+        'RATE_LIMITED',
+        'AUTH_EXPIRED',
       ];
       if (!validClass.includes(from) || !validClass.includes(to)) {
         console.error(

package/src/bin-internal/index.ts

@@ -1,3 +1,4 @@
+import { authSetupCmd } from './auth-setup';
 import { disputesCmd } from './disputes';
 import { doctorCmd } from './doctor';
 import { evalDeterministicCmd } from './eval-deterministic';
@@ -25,6 +26,7 @@ import { validateFeatureCmd } from './validate-feature';
 import { verifyPromptsCmd } from './verify-prompts';
 
 const COMMANDS: Record<string, (argv: string[]) => Promise<number>> = {
+  'auth-setup': authSetupCmd,
   disputes: disputesCmd,
   doctor: doctorCmd,
   'eval-deterministic': evalDeterministicCmd,

package/src/bin-internal/normalize.ts

@@ -1,6 +1,6 @@
 import { existsSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
-import { normalizeRun } from '@xera-ai/web';
+import { readMeta } from '../artifact/meta';
 import { resolveArtifactPaths } from '../artifact/paths';
 
 export async function normalizeCmd(argv: string[]): Promise<number> {
@@ -26,6 +26,18 @@ export async function normalizeCmd(argv: string[]): Promise<number> {
     console.error(`[xera:normalize] runs/${runId} missing`);
     return 1;
   }
+
+  const meta = readMeta(paths.metaPath);
+  const adapter = meta?.adapter ?? 'web';
+
+  if (adapter === 'http') {
+    const { normalizeHttpRun } = await import('@xera-ai/http');
+    await normalizeHttpRun({ runId, runDir });
+    console.log(`[xera:normalize] wrote normalized.json (http)`);
+    return 0;
+  }
+
+  const { normalizeRun } = await import('@xera-ai/web');
   const r = await normalizeRun({ runId, runDir });
   console.log(
     `[xera:normalize] wrote normalized.json (scrubbed_fields_count=${r.scrubbed_fields_count})`,

package/src/bin-internal/report.ts

@@ -1,8 +1,14 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { readMeta } from '../artifact/meta';
 import { resolveArtifactPaths } from '../artifact/paths';
+import { readAuthState } from '../auth/state';
 import { aggregateScenarios } from '../classifier/aggregate';
+import { type AuthFileSummary, classifyAuthExpired } from '../classifier/auth-expired';
+import { classifyContractDrift } from '../classifier/contract-drift';
+import { classifyRateLimited } from '../classifier/rate-limited';
 import type { ScenarioClassification } from '../classifier/types';
+import { loadConfig } from '../config/load';
 import type { OutdatedDecision } from '../graph/classify';
 import { enhanceClassification } from '../graph/classify';
 import { deriveSnapshot, loadAllEvents } from '../graph/store';
@@ -22,10 +28,96 @@ export async function reportCmd(argv: string[]): Promise<number> {
     console.error('[xera:report] usage: report <TICKET> --input=<classifier-output.json>');
     return 1;
   }
-  const paths = resolveArtifactPaths(process.cwd(), ticket);
+  const cwd = process.cwd();
+  const paths = resolveArtifactPaths(cwd, ticket);
   const input = JSON.parse(readFileSync(inputArg.slice('--input='.length), 'utf8')) as ReportInput;
 
-  const aggregated = aggregateScenarios(input.scenarios);
+  // v0.7: apply deterministic HTTP classifier rules before aggregation.
+  // When adapter === 'http', scan normalized.json http.calls for rate-limit,
+  // auth-expired, and contract-drift signals and override failing scenario classes.
+  interface HttpRuleOverride {
+    class: ScenarioClassification['class'];
+    rationale: string;
+  }
+  let httpRuleOverride: HttpRuleOverride | null = null;
+
+  const meta = readMeta(paths.metaPath);
+  if (meta?.adapter === 'http') {
+    const config = await loadConfig(cwd);
+    if (config.http) {
+      const normalizedPath = join(paths.ticketDir, 'runs', input.runId, 'normalized.json');
+      if (existsSync(normalizedPath)) {
+        const norm = JSON.parse(readFileSync(normalizedPath, 'utf8')) as {
+          http?: {
+            calls?: Array<{ method: string; url: string; status: number; respBody?: unknown }>;
+          };
+        };
+        const calls = norm.http?.calls ?? [];
+
+        // RATE_LIMITED
+        const rate = classifyRateLimited({ calls });
+        if (rate) httpRuleOverride = rate;
+
+        // AUTH_EXPIRED — needs auth files
+        if (!httpRuleOverride) {
+          const authFiles: Record<string, AuthFileSummary> = {};
+          const httpAuthDir = join(cwd, '.xera', '.auth', 'http');
+          for (const role of Object.keys(config.http.auth.roles)) {
+            const entry = readAuthState(httpAuthDir, role);
+            if (entry) {
+              const p = entry.payload as {
+                token: string;
+                type: 'bearer' | 'apiKey' | 'basic' | 'cookie';
+              };
+              if (typeof p.token === 'string' && typeof p.type === 'string') {
+                authFiles[role] = {
+                  token: p.token,
+                  type: p.type as AuthFileSummary['type'],
+                  expires_at: entry.expires_at,
+                };
+              }
+            }
+          }
+          const authExp = classifyAuthExpired({ calls, authFiles });
+          if (authExp) httpRuleOverride = authExp;
+        }
+
+        // CONTRACT_DRIFT — needs openapi
+        if (!httpRuleOverride && config.http.spec) {
+          const { loadOpenApi } = await import('@xera-ai/http');
+          const openapi = await loadOpenApi(config.http.spec);
+          if (openapi) {
+            const drift = classifyContractDrift({
+              calls: calls.map((c) => ({
+                method: c.method,
+                url: c.url,
+                status: c.status,
+                respBody: c.respBody,
+              })),
+              openapi,
+            });
+            if (drift) httpRuleOverride = drift;
+          }
+        }
+      }
+    }
+  }
+
+  // Apply override: if a deterministic rule fired, stamp every FAIL scenario with it.
+  const scenariosForAggregation: ScenarioClassification[] = httpRuleOverride
+    ? input.scenarios.map((s) =>
+        s.outcome === 'FAIL'
+          ? {
+              ...s,
+              class: httpRuleOverride.class,
+              rationale: httpRuleOverride.rationale,
+              confidence: 'high' as const,
+            }
+          : s,
+      )
+    : input.scenarios;
+
+  const aggregated = aggregateScenarios(scenariosForAggregation);
 
   // v0.6.1: TEST_OUTDATED enhancement.
   // The /xera-report skill writes outdated-decisions.json BEFORE invoking this subcommand,

package/src/bin-internal/verify-prompts.ts

@@ -8,7 +8,8 @@ export interface CheckResult {
 
 const IN_SCOPE_PROMPTS = [
   'feature-from-story.md',
-  'script-from-feature.md',
+  'script-from-feature-web.md',
+  'script-from-feature-http.md',
   'heal-locator.md',
   'extract-areas.md',
   'similarity-match.md',

package/src/classifier/aggregate.ts

@@ -2,6 +2,9 @@ import type { ClassifyOutput, Confidence, ScenarioClassification } from './types
 
 const CLASS_PRIORITY: Array<ClassifyOutput['overall']> = [
   'REAL_BUG',
+  'CONTRACT_DRIFT',
+  'AUTH_EXPIRED',
+  'RATE_LIMITED',
   'TEST_OUTDATED',
   'TEST_BUG',
   'SELECTOR_DRIFT',

package/src/classifier/auth-expired.ts

@@ -0,0 +1,44 @@
+import type { ClassifyResult, HttpCallSummary } from './rate-limited';
+
+export interface AuthFileSummary {
+  token: string;
+  type: 'bearer' | 'apiKey' | 'basic' | 'cookie';
+  expires_at: string;
+}
+
+export interface ClassifyAuthExpiredInput {
+  calls: readonly HttpCallSummary[];
+  authFiles: Record<string, AuthFileSummary>;
+}
+
+function jwtExpPast(jwt: string, now: number): boolean {
+  const parts = jwt.split('.');
+  if (parts.length !== 3) return false;
+  try {
+    const payloadB64 = parts[1];
+    if (!payloadB64) return false;
+    const payload = JSON.parse(Buffer.from(payloadB64, 'base64url').toString('utf8')) as {
+      exp?: number;
+    };
+    return typeof payload.exp === 'number' && payload.exp * 1000 < now;
+  } catch {
+    return false;
+  }
+}
+
+export function classifyAuthExpired(input: ClassifyAuthExpiredInput): ClassifyResult | null {
+  const has401 = input.calls.some((c) => c.status === 401);
+  if (!has401) return null;
+  const now = Date.now();
+  for (const [role, entry] of Object.entries(input.authFiles)) {
+    const fileExpired = new Date(entry.expires_at).getTime() < now;
+    const jwtExpired = entry.type === 'bearer' && jwtExpPast(entry.token, now);
+    if (fileExpired || jwtExpired) {
+      return {
+        class: 'AUTH_EXPIRED',
+        rationale: `HTTP 401 captured; auth file for role '${role}' is past expiry. Run: bun run xera:auth-setup --role ${role}`,
+      };
+    }
+  }
+  return null;
+}