@baseworks/auth 0.2.5 → 1.0.2

package/dist/hono.d.ts

@@ -5,17 +5,24 @@ interface ServiceAuthUser {
     userId: string;
     orgId?: string;
     role?: string;
-    tokenType: 'user' | 'service';
+    email?: string;
+    tokenType: 'user' | 'service' | 'assistant';
 }
 declare module 'hono' {
     interface ContextVariableMap {
         auth: ServiceAuthUser;
     }
 }
+/** Tests change the environment between cases. */
+declare function resetAuthVerifier(): void;
 /**
- * Hono middleware — verifies HS256 JWT from Authorization: Bearer header.
- * Reads JWT_SECRET from process.env.
- * Sets c.var.auth on success.
+ * Hono middleware — verifies the realm's identity token from
+ * `Authorization: Bearer` and sets `c.var.auth`.
+ *
+ * ES256 verified against the realm's published JWKS, plus HS256 while a legacy
+ * secret is configured. The shared secret is a migration door: any service
+ * holding it can also MINT tokens, including one claiming to be another user,
+ * so it should be removed once the realm issues ES256 everywhere.
  */
 declare function requireAuth(c: Context, next: Next): Promise<void | (Response & hono.TypedResponse<{
     error: string;
@@ -23,4 +30,4 @@ declare function requireAuth(c: Context, next: Next): Promise<void | (Response &
     error: string;
 }, 500, "json">)>;
 
-export { type ServiceAuthUser, requireAuth };
+export { type ServiceAuthUser, requireAuth, resetAuthVerifier };

package/dist/hono.js

@@ -1,24 +1,52 @@
 import {
-  verifyHs256Jwt
-} from "./chunk-OD5XLL3O.js";
+  verifier
+} from "./chunk-3XJIAYEG.js";
 
 // src/hono.ts
+function fromEnv(env) {
+  const jwksUri = env["AUTH_JWKS_URI"];
+  const legacy = env["JWT_SECRET"];
+  if (!jwksUri && !legacy) {
+    return { error: "neither AUTH_JWKS_URI nor JWT_SECRET is configured" };
+  }
+  return verifier({
+    ...jwksUri ? { jwksUri } : {},
+    ...env["AUTH_ISSUER"] ? { issuer: env["AUTH_ISSUER"] } : {},
+    ...env["AUTH_AUDIENCE"] ? { audience: env["AUTH_AUDIENCE"] } : {},
+    ...legacy ? { legacyHs256Secret: legacy } : {}
+  });
+}
+var cachedVerifier;
+function resetAuthVerifier() {
+  cachedVerifier = void 0;
+}
+function claimsToUser(claims) {
+  const type = claims.type;
+  return {
+    userId: String(claims.sub ?? ""),
+    orgId: claims["org_id"],
+    role: claims["role"],
+    email: claims["email"],
+    // Anything unrecognised is treated as a user token: `service` and
+    // `assistant` open doors a plain user token must not, so they are named
+    // explicitly and everything else falls to the least privileged reading.
+    tokenType: type === "service" ? "service" : type === "assistant" ? "assistant" : "user"
+  };
+}
 async function requireAuth(c, next) {
   const header = c.req.header("Authorization");
   if (!header?.startsWith("Bearer ")) return c.json({ error: "Unauthorized" }, 401);
-  const token = header.slice(7);
-  const secret = process.env["JWT_SECRET"];
-  if (!secret) return c.json({ error: "JWT_SECRET not configured" }, 500);
-  const claims = verifyHs256Jwt(token, secret);
+  cachedVerifier ??= fromEnv(process.env);
+  if (typeof cachedVerifier !== "function") {
+    console.error(`[auth] ${cachedVerifier.error}`);
+    return c.json({ error: "auth is not configured" }, 500);
+  }
+  const claims = await cachedVerifier(header.slice(7));
   if (!claims) return c.json({ error: "Unauthorized" }, 401);
-  c.set("auth", {
-    userId: String(claims["sub"] ?? ""),
-    orgId: claims["org_id"],
-    role: claims["role"],
-    tokenType: claims["type"] === "service" ? "service" : "user"
-  });
+  c.set("auth", claimsToUser(claims));
   return next();
 }
 export {
-  requireAuth
+  requireAuth,
+  resetAuthVerifier
 };

package/dist/identity.d.ts

@@ -0,0 +1,95 @@
+import { JWK, JSONWebKeySet } from 'jose';
+
+/**
+ * Realm identity tokens: minting, publication and verification.
+ *
+ * One realm has one issuer — its auth-service — and one signing key pair. Every
+ * other service in the realm (org, iam, billing, pay, and each product API)
+ * verifies with the PUBLIC key it fetches from `/.well-known/jwks.json`, and
+ * therefore cannot mint anything.
+ *
+ * That asymmetry is the whole point. With a shared HMAC secret, every service
+ * holding it can also *issue* tokens — including one that claims to be another
+ * user. This is not theoretical: a product API was found minting
+ * `{ sub: <some other user>, type: 'user' }` to write a membership on that
+ * user's behalf. Under ES256 that is impossible by construction: the private
+ * key never leaves auth-service.
+ *
+ * Claims: `iss`, `aud`, `sub`, `iat`, `exp`, `jti`, `type`. Org and role are
+ * deliberately absent — membership changes while a token lives, so a token that
+ * carries a role goes stale and lies. Consumers ask the org service instead.
+ *
+ * HS256 stays available during migration; see `verifier()` below.
+ */
+
+declare const IDENTITY_ALG = "ES256";
+/** `human` signs in; `service` is a service acting as itself; `assistant` is a narrowed token. */
+type IdentityType = 'human' | 'service' | 'assistant';
+interface IdentityClaims {
+    sub: string;
+    type: IdentityType;
+    iss?: string;
+    aud?: string;
+    exp?: number;
+    iat?: number;
+    jti?: string;
+    /** Narrowed tokens carry the org they are scoped to; identity tokens do not. */
+    org_id?: string;
+    scope?: string;
+    [key: string]: unknown;
+}
+interface SigningKey {
+    privateKey: CryptoKey;
+    /** Published in the JWKS and in every token header, so verifiers pick the right key. */
+    kid: string;
+    publicJwk: JWK;
+}
+/** Load the signing key pair from a PKCS#8 private key. */
+declare function loadSigningKey(privateKeyPem: string, kid?: string): Promise<SigningKey>;
+/** Load a public key (SPKI PEM) for publication only — a retired key during rotation. */
+declare function loadPublicKey(publicKeyPem: string, kid?: string): Promise<JWK>;
+/**
+ * The document served at `/.well-known/jwks.json`.
+ *
+ * Rotation works by publishing both keys for longer than a token lives: add the
+ * new key, sign with it, keep the old one listed until every token signed by it
+ * has expired, then drop it.
+ */
+declare function jwks(signing: SigningKey, retired?: JWK[]): JSONWebKeySet;
+interface MintOptions {
+    issuer: string;
+    audience: string;
+    expiresInSeconds: number;
+}
+declare function mint(key: SigningKey, claims: IdentityClaims, opts: MintOptions): Promise<string>;
+interface VerifierOptions {
+    /** Where to fetch the realm's public keys. jose caches and refetches on an unknown `kid`. */
+    jwksUri?: string;
+    /** A fixed key set instead of a URL — for tests, or a service that ships with the realm. */
+    jwks?: JSONWebKeySet;
+    issuer?: string;
+    audience?: string;
+    /**
+     * Accept HS256 tokens signed with this shared secret, in addition to ES256.
+     *
+     * Migration only. While it is set, any holder of the secret can still mint
+     * tokens for this realm — including tokens impersonating a user — so it must
+     * be removed once every issuer has moved to ES256.
+     */
+    legacyHs256Secret?: string;
+}
+interface Verifier {
+    (token: string): Promise<IdentityClaims | null>;
+}
+/**
+ * Build a verifier for the realm.
+ *
+ * Returns `null` rather than throwing on every rejection: a caller answering an
+ * HTTP request wants one 401 path, not a taxonomy of crypto errors. Reasons
+ * worth acting on (an unreachable JWKS, say) surface through `onError`.
+ */
+declare function verifier(opts: VerifierOptions & {
+    onError?: (err: unknown) => void;
+}): Verifier;
+
+export { IDENTITY_ALG, type IdentityClaims, type IdentityType, type MintOptions, type SigningKey, type Verifier, type VerifierOptions, jwks, loadPublicKey, loadSigningKey, mint, verifier };

package/dist/identity.js

@@ -0,0 +1,16 @@
+import {
+  IDENTITY_ALG,
+  jwks,
+  loadPublicKey,
+  loadSigningKey,
+  mint,
+  verifier
+} from "./chunk-3XJIAYEG.js";
+export {
+  IDENTITY_ALG,
+  jwks,
+  loadPublicKey,
+  loadSigningKey,
+  mint,
+  verifier
+};

package/dist/index.d.ts

@@ -4,4 +4,3 @@ export { OidcAuthUrlConfig, PkceChallenge, buildOidcAuthUrl, generatePkce } from
 export { CliAuthResult, CliAuthStart, PollOptions, pollCliAuth, startCliAuth } from './cli-auth.js';
 export { hashToken, looksLikeJwt, stripBearer } from './token.js';
 export { JwtClaims, signHs256Jwt, verifyHs256Jwt } from './jwt.js';
-export { buildAccountProfileUrl, buildAuthLoginUrl, buildAuthLogoutUrl, buildPublicUrl, getAccountPublicUrl, getAppBasePath, getAuthPublicUrl, getPublicSiteUrl, normalizeUrlLike } from './url-helpers.js';

package/dist/index.js

@@ -4,49 +4,29 @@ import {
 import {
   verifyOidcToken
 } from "./chunk-BL74TFCV.js";
+import {
+  buildOidcAuthUrl,
+  generatePkce
+} from "./chunk-34E5PYNA.js";
 import {
   pollCliAuth,
   startCliAuth
-} from "./chunk-C4V5LCFA.js";
+} from "./chunk-GXDYEKX7.js";
 import {
   hashToken,
   looksLikeJwt,
   stripBearer
 } from "./chunk-VBIQJKUU.js";
-import {
-  buildAccountProfileUrl,
-  buildAuthLoginUrl,
-  buildAuthLogoutUrl,
-  buildPublicUrl,
-  getAccountPublicUrl,
-  getAppBasePath,
-  getAuthPublicUrl,
-  getPublicSiteUrl,
-  normalizeUrlLike
-} from "./chunk-3NJASEF4.js";
 import {
   signHs256Jwt,
   verifyHs256Jwt
 } from "./chunk-OD5XLL3O.js";
-import {
-  buildOidcAuthUrl,
-  generatePkce
-} from "./chunk-34E5PYNA.js";
 export {
-  buildAccountProfileUrl,
-  buildAuthLoginUrl,
-  buildAuthLogoutUrl,
   buildOidcAuthUrl,
-  buildPublicUrl,
   createOidcHumanResolver,
   generatePkce,
-  getAccountPublicUrl,
-  getAppBasePath,
-  getAuthPublicUrl,
-  getPublicSiteUrl,
   hashToken,
   looksLikeJwt,
-  normalizeUrlLike,
   pollCliAuth,
   signHs256Jwt,
   startCliAuth,

package/dist/jwt.d.ts

@@ -6,6 +6,7 @@ interface JwtClaims {
     iat?: number;
     org_id?: string;
     role?: string;
+    email?: string;
     type?: string;
     [key: string]: unknown;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@baseworks/auth",
-  "version": "0.2.5",
+  "version": "1.0.2",
   "type": "module",
   "exports": {
     ".": "./dist/index.js",
@@ -10,43 +10,39 @@
     "./cli-auth": "./dist/cli-auth.js",
     "./cli": "./dist/cli.js",
     "./token": "./dist/token.js",
-    "./session": "./dist/session.js",
-    "./url-helpers": "./dist/url-helpers.js",
-    "./edge": "./dist/edge.js",
     "./jwt": "./dist/jwt.js",
+    "./identity": "./dist/identity.js",
     "./hono": "./dist/hono.js"
   },
   "files": [
     "dist",
     "src"
   ],
-  "scripts": {
-    "build": "tsup",
-    "typecheck": "tsc --noEmit"
-  },
   "dependencies": {
     "@baseworks/core": "^0.2.1",
-    "jose": "^6.2.3"
+    "@baseworks/cli": "^0.2.1",
+    "jose": "^6.2.3",
+    "commander": "^15.0.0"
   },
   "peerDependencies": {
-    "hono": ">=4.0.0",
-    "next": ">=15.0.0"
+    "hono": ">=4.0.0"
   },
   "peerDependenciesMeta": {
-    "next": {
-      "optional": true
-    },
     "hono": {
       "optional": true
     }
   },
   "devDependencies": {
-    "@baseworks/cli": "workspace:*",
-    "@baseworks/tsconfig": "workspace:*",
     "@types/node": "^26.0.1",
-    "commander": "^15.0.0",
     "hono": "^4.12.27",
     "tsup": "^8.5.1",
-    "typescript": "^5.6.0"
+    "typescript": "^5.6.0",
+    "vitest": "^4.1.9",
+    "@baseworks/tsconfig": "0.1.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
   }
-}
+}

package/src/__tests__/identity.test.ts

@@ -0,0 +1,238 @@
+import { describe, expect, it } from 'vitest'
+import { exportPKCS8, exportSPKI, generateKeyPair } from 'jose'
+import { jwks, loadPublicKey, loadSigningKey, mint, verifier } from '../identity.js'
+
+const ISS = 'https://auth.example.test'
+const AUD = 'example-realm'
+
+async function freshKey() {
+  const { privateKey, publicKey } = await generateKeyPair('ES256', { extractable: true })
+  return { pkcs8: await exportPKCS8(privateKey), spki: await exportSPKI(publicKey) }
+}
+
+describe('identity tokens', () => {
+  it('mints and verifies a token against the published JWKS', async () => {
+    const { pkcs8 } = await freshKey()
+    const key = await loadSigningKey(pkcs8)
+    const token = await mint(key, { sub: 'usr_1', type: 'human' }, {
+      issuer: ISS, audience: AUD, expiresInSeconds: 60,
+    })
+
+    const verify = verifier({ jwks: jwks(key), issuer: ISS, audience: AUD })
+    const claims = await verify(token)
+
+    expect(claims?.sub).toBe('usr_1')
+    expect(claims?.type).toBe('human')
+    expect(claims?.iss).toBe(ISS)
+    expect(claims?.aud).toBe(AUD)
+    expect(claims?.jti).toBeTruthy()
+  })
+
+  it('never publishes the private half', async () => {
+    const { pkcs8 } = await freshKey()
+    const key = await loadSigningKey(pkcs8)
+    const published = JSON.stringify(jwks(key))
+
+    expect(published).not.toContain('"d"')
+    expect(key.publicJwk.kid).toBeTruthy()
+    expect(key.publicJwk.alg).toBe('ES256')
+  })
+
+  it('rejects a token signed by another realm', async () => {
+    const mine = await loadSigningKey((await freshKey()).pkcs8)
+    const theirs = await loadSigningKey((await freshKey()).pkcs8)
+
+    const token = await mint(theirs, { sub: 'usr_1', type: 'human' }, {
+      issuer: ISS, audience: AUD, expiresInSeconds: 60,
+    })
+
+    expect(await verifier({ jwks: jwks(mine), issuer: ISS, audience: AUD })(token)).toBeNull()
+  })
+
+  it('rejects a wrong audience and a wrong issuer', async () => {
+    const key = await loadSigningKey((await freshKey()).pkcs8)
+    const token = await mint(key, { sub: 'usr_1', type: 'human' }, {
+      issuer: ISS, audience: 'other-realm', expiresInSeconds: 60,
+    })
+
+    expect(await verifier({ jwks: jwks(key), issuer: ISS, audience: AUD })(token)).toBeNull()
+    expect(await verifier({ jwks: jwks(key), issuer: 'https://elsewhere.test', audience: 'other-realm' })(token)).toBeNull()
+  })
+
+  it('rejects an expired token', async () => {
+    const key = await loadSigningKey((await freshKey()).pkcs8)
+    const token = await mint(key, { sub: 'usr_1', type: 'human' }, {
+      issuer: ISS, audience: AUD, expiresInSeconds: -1,
+    })
+    expect(await verifier({ jwks: jwks(key), issuer: ISS, audience: AUD })(token)).toBeNull()
+  })
+
+  it('keeps a retired key verifiable while it is still published', async () => {
+    const old = await loadSigningKey((await freshKey()).pkcs8)
+    const oldSpki = (await freshKey()).spki // ayri bir anahtar: yayinlanmamis olan
+    const current = await loadSigningKey((await freshKey()).pkcs8)
+
+    const tokenFromOld = await mint(old, { sub: 'usr_1', type: 'human' }, {
+      issuer: ISS, audience: AUD, expiresInSeconds: 60,
+    })
+
+    const withOld = verifier({ jwks: jwks(current, [old.publicJwk]), issuer: ISS, audience: AUD })
+    expect((await withOld(tokenFromOld))?.sub).toBe('usr_1')
+
+    // Yayindan dusunce ayni token artik gecmez.
+    const withoutOld = verifier({ jwks: jwks(current), issuer: ISS, audience: AUD })
+    expect(await withoutOld(tokenFromOld)).toBeNull()
+
+    // Emeklilikte yalniz public anahtar elde olur; PEM'den de yuklenebilmeli.
+    expect((await loadPublicKey(oldSpki)).kid).toBeTruthy()
+  })
+
+  it('accepts base64-wrapped PEM, because env vars eat newlines', async () => {
+    const { pkcs8 } = await freshKey()
+    const key = await loadSigningKey(Buffer.from(pkcs8).toString('base64'))
+    const token = await mint(key, { sub: 'usr_1', type: 'human' }, {
+      issuer: ISS, audience: AUD, expiresInSeconds: 60,
+    })
+    expect((await verifier({ jwks: jwks(key), issuer: ISS, audience: AUD })(token))?.sub).toBe('usr_1')
+  })
+})
+
+describe('HS256 migration mode', () => {
+  const secret = 'test-secret-32-chars-long-enough!'
+
+  it('accepts both an ES256 token and a legacy HS256 one', async () => {
+    const { signHs256Jwt } = await import('../jwt.js')
+    const key = await loadSigningKey((await freshKey()).pkcs8)
+    const verify = verifier({ jwks: jwks(key), issuer: ISS, audience: AUD, legacyHs256Secret: secret })
+
+    const modern = await mint(key, { sub: 'usr_1', type: 'human' }, {
+      issuer: ISS, audience: AUD, expiresInSeconds: 60,
+    })
+    const legacy = signHs256Jwt({ sub: 'usr_2', type: 'human' }, secret, 60)
+
+    expect((await verify(modern))?.sub).toBe('usr_1')
+    expect((await verify(legacy))?.sub).toBe('usr_2')
+  })
+
+  it('rejects a legacy token once the secret is withdrawn', async () => {
+    const { signHs256Jwt } = await import('../jwt.js')
+    const key = await loadSigningKey((await freshKey()).pkcs8)
+    const legacy = signHs256Jwt({ sub: 'usr_2', type: 'human' }, secret, 60)
+
+    expect(await verifier({ jwks: jwks(key), issuer: ISS, audience: AUD })(legacy)).toBeNull()
+  })
+})
+
+describe('hono middleware', () => {
+  const secret = 'test-secret-32-chars-long-enough!'
+
+  async function run(env: Record<string, string | undefined>, token?: string) {
+    const { requireAuth, resetAuthVerifier } = await import('../hono.js')
+    for (const [k, v] of Object.entries(env)) {
+      if (v === undefined) delete process.env[k]
+      else process.env[k] = v
+    }
+    resetAuthVerifier()
+
+    const { Hono } = await import('hono')
+    const app = new Hono()
+    app.use('*', requireAuth)
+    app.get('/', (c) => c.json(c.get('auth')))
+    return app.request('/', token ? { headers: { Authorization: `Bearer ${token}` } } : {})
+  }
+
+  it('answers 500, not 401, when nothing is configured', async () => {
+    const res = await run({ AUTH_JWKS_URI: undefined, JWT_SECRET: undefined }, 'whatever')
+    expect(res.status).toBe(500)
+  })
+
+  it('rejects a missing header', async () => {
+    expect((await run({ JWT_SECRET: secret })).status).toBe(401)
+  })
+
+  it('accepts a legacy HS256 token and classifies the token type', async () => {
+    const { signHs256Jwt } = await import('../jwt.js')
+    const res = await run(
+      { AUTH_JWKS_URI: undefined, JWT_SECRET: secret },
+      signHs256Jwt({ sub: 'usr_1', type: 'service' }, secret, 60),
+    )
+    expect(res.status).toBe(200)
+    expect(await res.json()).toMatchObject({ userId: 'usr_1', tokenType: 'service' })
+  })
+
+  it('treats an unknown token type as a plain user token', async () => {
+    const { signHs256Jwt } = await import('../jwt.js')
+    const res = await run(
+      { AUTH_JWKS_URI: undefined, JWT_SECRET: secret },
+      signHs256Jwt({ sub: 'usr_1', type: 'something-new' }, secret, 60),
+    )
+    expect(await res.json()).toMatchObject({ tokenType: 'user' })
+  })
+
+  it('rejects a token signed with a different secret', async () => {
+    const { signHs256Jwt } = await import('../jwt.js')
+    const res = await run(
+      { AUTH_JWKS_URI: undefined, JWT_SECRET: secret },
+      signHs256Jwt({ sub: 'usr_1', type: 'human' }, 'a-completely-different-secret!!', 60),
+    )
+    expect(res.status).toBe(401)
+  })
+})
+
+describe('remote JWKS — the production path', () => {
+  it('fetches the key set over HTTP and verifies a token against it', async () => {
+    const { createServer } = await import('node:http')
+    const { exportPKCS8, generateKeyPair } = await import('jose')
+
+    const { privateKey } = await generateKeyPair('ES256', { extractable: true })
+    const key = await loadSigningKey(await exportPKCS8(privateKey))
+
+    let served = 0
+    const server = createServer((_req, res) => {
+      served += 1
+      res.writeHead(200, { 'content-type': 'application/json' })
+      res.end(JSON.stringify(jwks(key)))
+    })
+    await new Promise<void>((resolve) => server.listen(0, '127.0.0.1', resolve))
+    const { port } = server.address() as { port: number }
+
+    try {
+      const verify = verifier({
+        jwksUri: `http://127.0.0.1:${port}/.well-known/jwks.json`,
+        issuer: ISS,
+        audience: AUD,
+      })
+
+      const token = await mint(key, { sub: 'usr_1', type: 'human' }, {
+        issuer: ISS, audience: AUD, expiresInSeconds: 60,
+      })
+
+      expect((await verify(token))?.sub).toBe('usr_1')
+      // Second call must come from cache: a fetch per request would put the
+      // auth service on the critical path of every request in the realm.
+      expect((await verify(token))?.sub).toBe('usr_1')
+      expect(served).toBe(1)
+    } finally {
+      await new Promise<void>((resolve) => server.close(() => resolve()))
+    }
+  })
+
+  it('returns null instead of throwing when the key set is unreachable', async () => {
+    const key = await loadSigningKey((await freshKey()).pkcs8)
+    const token = await mint(key, { sub: 'usr_1', type: 'human' }, {
+      issuer: ISS, audience: AUD, expiresInSeconds: 60,
+    })
+
+    let seen: unknown
+    // Port 1 is reserved and never listening.
+    const verify = verifier({
+      jwksUri: 'http://127.0.0.1:1/jwks.json',
+      issuer: ISS,
+      audience: AUD,
+      onError: (err) => { seen = err },
+    })
+
+    expect(await verify(token)).toBeNull()
+    expect(seen).toBeTruthy()
+  })
+})

package/src/cli-auth.ts

@@ -20,7 +20,13 @@ export interface CliAuthResult {
 export interface PollOptions {
   /** ms between polls (default: 2000) */
   intervalMs?: number;
-  /** ms before giving up (default: 300_000 = 5 min) */
+  /**
+   * ms before giving up (default: 600_000 = 10 min).
+   *
+   * Prefer passing `start.expiresIn * 1000` so the CLI stops at the same moment
+   * the server drops the state; a shorter timeout reports a client-side
+   * giving-up while the link is in fact still good.
+   */
   timeoutMs?:  number;
 }
 
@@ -64,7 +70,7 @@ export async function pollCliAuth(
   opts:    PollOptions = {},
 ): Promise<CliAuthResult> {
   const intervalMs = opts.intervalMs ?? 2_000;
-  const timeoutMs  = opts.timeoutMs  ?? 300_000;
+  const timeoutMs  = opts.timeoutMs  ?? 600_000;
   const base       = apiBase.replace(/\/+$/, '');
   const deadline   = Date.now() + timeoutMs;
 
@@ -86,14 +92,17 @@ export async function pollCliAuth(
       return { token: data.token };
     }
 
+    // The server answers 'expired' both for a state whose TTL ran out and for
+    // one it never had; from here the two are the same thing — nobody approved
+    // in time.
     if (data.status === 'expired') {
-      throw new Error('Auth session expired — run login again');
+      throw new Error('the sign-in was not approved in time — run login again');
     }
 
     // status === "pending" → continue polling
   }
 
-  throw new Error('Auth timed out — run login again');
+  throw new Error('no approval received in time — run login again');
 }
 
 // ─── helpers ────────────────────────────────────────────────────────────────