@baseworks/auth 0.2.7 → 1.0.2

package/README.md

@@ -1,31 +1,251 @@
 # @baseworks/auth
 
-Authentication utilities for the baseworks monorepo. Uses subpath imports so each environment only pulls in what it needs.
+Identity for a baseworks realm: verifying tokens, issuing them, and the sign-in
+commands a CLI needs.
 
-## Subpath Imports
+A **realm** is one deployment of the plane — one auth-service, one signing key
+pair, and the services that trust it. A token issued in a realm is accepted by
+every service in it and by no other.
+
+```
+npm i @baseworks/auth
+```
+
+Subpath imports, so a Worker or a browser bundle never pulls in Node-only code.
+The task-oriented guide is below; a per-file reference follows it.
+
+---
+
+## I have a service that needs to verify tokens
+
+The common case, and usually one line:
+
+```ts
+import { requireAuth } from '@baseworks/auth/hono'
+
+app.use('*', requireAuth)
+app.get('/things', (c) => {
+  const { userId, tokenType } = c.get('auth')
+  …
+})
+```
+
+Configured entirely from the environment, so the code above never changes:
+
+| Variable | Meaning |
+|---|---|
+| `AUTH_JWKS_URI` | `https://auth.example.com/.well-known/jwks.json` |
+| `AUTH_ISSUER` | Expected `iss`. Unset means "do not check" |
+| `AUTH_AUDIENCE` | Expected `aud`. Unset means "do not check" |
+| `JWT_SECRET` | Legacy HS256 secret, accepted alongside ES256 while set |
+
+Set both `AUTH_JWKS_URI` and `JWT_SECRET` during a migration and both kinds of
+token are accepted. With only `JWT_SECRET`, behaviour is exactly what it was
+before JWKS existed — so a service can be upgraded before the realm has keys.
+
+**Set `AUTH_ISSUER` and `AUTH_AUDIENCE` in production.** Without them, a token
+from any realm whose key set you happen to fetch will verify.
+
+A service with neither a JWKS URI nor a secret answers **500, not 401**: a
+misconfigured service must not look like a rejected caller, or whoever is paged
+goes looking at the user's credentials.
+
+Not using Hono? Build the verifier directly:
+
+```ts
+import { verifier } from '@baseworks/auth/identity'
+
+const verify = verifier({
+  jwksUri:  process.env.AUTH_JWKS_URI,
+  issuer:   process.env.AUTH_ISSUER,
+  audience: process.env.AUTH_AUDIENCE,
+})
+
+const claims = await verify(token)   // null when the token is not acceptable
+```
+
+Build it **once per process**. It owns the JWKS cache; rebuilding per request
+refetches the key set every time and puts auth-service on the critical path of
+every request in the realm.
+
+`verify` returns `null` instead of throwing, so a request handler has one 401
+path rather than a taxonomy of crypto errors. Pass `onError` to log the reason.
+
+### What is in a token
+
+```
+iss  aud  sub  iat  exp  jti   type: human | service | assistant
+```
+
+**No organisation, no role.** Membership changes while a token lives, so a token
+carrying a role goes stale and lies. Ask the org service and cache the answer for
+a minute; that is the only way it can be current.
+
+`type` matters for authorisation: `service` and `assistant` open doors a plain
+user token must not. `requireAuth` maps anything unrecognised to `user`, the
+least privileged reading.
+
+---
+
+## I am the issuer
+
+Only auth-service does this. The private key never leaves it, which is exactly
+why every other service can be trusted with the public half and nothing else.
+
+```ts
+import { loadSigningKey, jwks, mint } from '@baseworks/auth/identity'
+
+const key = await loadSigningKey(process.env.AUTH_SIGNING_KEY!)
+
+app.get('/.well-known/jwks.json', (c) => c.json(jwks(key)))
+
+const token = await mint(key, { sub: userId, type: 'human' }, {
+  issuer: 'https://auth.example.com',
+  audience: 'example-realm',
+  expiresInSeconds: 86400,
+})
+```
+
+`loadSigningKey` takes a PKCS#8 PEM **or base64 of one**, because environment
+variables, Kubernetes Secrets and CI variables all mangle the newlines a PEM
+needs. The key id is the RFC 7638 thumbprint of the key itself, so it is
+identical everywhere and never needs configuring.
+
+`jwks(key, retired)` publishes retired public keys alongside the current one.
+That is how rotation works: publish both for longer than a token lives, sign with
+the new key, drop the old one when its tokens have expired.
+
+---
+
+## I am building a CLI
+
+```ts
+import { addAuthCommands } from '@baseworks/auth/cli'
+
+addAuthCommands(program, {
+  cliName: 'mycli',
+  authBase: () => 'https://auth.example.com',
+  onToken:  (token) => config.patch({ token }),
+  onLogout: () => config.patch({ token: undefined }),
+  getToken: () => config.load().token,
+  tokenOrigin: () => config.writePath,
+  statusRows: () => [['url', apiBase()]],
+  nextSteps: 'mycli whoami',
+})
+```
+
+The user gets three commands:
+
+```
+mycli login          sign in through the browser
+mycli logout         forget the saved token
+mycli auth status    who am I, and how long is this token good for
+```
+
+```
+$ mycli auth status
+  url         https://example.com
+  user        01a05840-b6aa-7421-80d7-6eb192551584
+  token type  human
+  expires     2026-09-13 14:33 UTC (in 23h 57m)
+  token from  /Users/me/.mycli/config.toml
+```
+
+Storage stays yours — this module never touches the filesystem. Pass `getToken`
+and `auth status` appears; leave it out and it does not. `logout` warns when a
+token is still reachable afterwards, which is what happens when an environment
+variable outranks the config file.
+
+Use [`@baseworks/config`](../baseworks-config) for the file, with
+`scope: 'global'`: it writes `0600` under `~/.<app>/`. A project-local config
+sits inside a working tree, and a token there gets committed.
+
+### Driving the flow yourself
+
+```ts
+import { startCliAuth, pollCliAuth } from '@baseworks/auth/cli-auth'
+
+const start = await startCliAuth(base)
+console.log(`Approve at: ${start.url}`)
+const { token } = await pollCliAuth(base, start.state, {
+  timeoutMs: start.expiresIn * 1000,
+})
+```
+
+**Poll until exactly `expiresIn`, no sooner.** A shorter client timeout reports
+failure while the link still works — the default used to be five minutes against
+a ten-minute handle, which produced exactly that bug.
+
+---
+
+## Migrating off a shared HMAC secret
+
+A shared secret does not merely let a service *check* tokens, it lets that
+service **issue** them — including a token claiming to be another user. Not
+hypothetical: a product API in this plane was minting
+`{ sub: <another user>, type: 'user' }` to act on that user's behalf.
+
+Each step is safe on its own; the power actually goes away at step 5.
+
+1. Deploy auth-service **without** a signing key. It keeps issuing HS256.
+2. Upgrade verifiers to this version and give them `AUTH_JWKS_URI`. Both
+   algorithms are accepted now.
+3. Give auth-service `AUTH_SIGNING_KEY`. New tokens are ES256; existing ones keep
+   verifying until they expire.
+4. Move anything that was *minting* onto `POST /service-token` (a service acting
+   as itself) or `POST /exchange` (a narrowed copy of the caller's own token).
+   There is deliberately no replacement for minting as an arbitrary user — grant
+   the service the permission instead.
+5. Remove `JWT_SECRET` everywhere.
+
+---
+
+## Subpaths
 
 | Import | Runtime | Contents |
-|--------|---------|----------|
-| `@baseworks/auth` | Any | token helpers, verifyHs256Jwt, verifyOidcToken, pkce, cli-auth, url-helpers |
-| `@baseworks/auth/jwt` | Node.js | HS256 JWT verification |
-| `@baseworks/auth/hono` | Node.js + Hono | `requireAuth` middleware |
-| `@baseworks/auth/oidc` | Workers / Node / Browser | OIDC token verification via JWKS |
-| `@baseworks/auth/oidc-human` | Any | OIDC → DB user resolver factory |
-| `@baseworks/auth/pkce` | Workers / Node / Browser | PKCE generation + OIDC auth URL builder |
-| `@baseworks/auth/token` | Workers / Node / Browser | hashToken, looksLikeJwt, stripBearer |
-| `@baseworks/auth/cli-auth` | Node.js CLI | Browser-based polling auth flow |
-| `@baseworks/auth/session` | Next.js (Server) | OIDC cookie session, token exchange, refresh |
-| `@baseworks/auth/edge` | Next.js (Edge/Server) | Pomerium JWT assertions + cookie fallback |
-| `@baseworks/auth/url-helpers` | Next.js | Auth/account public URL builders |
+|---|---|---|
+| `@baseworks/auth/identity` | Node | **Realm tokens: `mint`, `jwks`, `verifier`** |
+| `@baseworks/auth/hono` | Node + Hono | `requireAuth` middleware |
+| `@baseworks/auth/cli` | Node CLI | `login` / `logout` / `auth status` commands |
+| `@baseworks/auth/cli-auth` | Node CLI | The device flow, without the commands |
+| `@baseworks/auth/jwt` | Node | HS256 sign/verify, `parseJwtPayload`. Legacy |
+| `@baseworks/auth/oidc` | Any | OIDC token verification via JWKS |
+| `@baseworks/auth/oidc-human` | Any | OIDC → user resolver factory |
+| `@baseworks/auth/pkce` | Any | PKCE generation, OIDC auth URL builder |
+| `@baseworks/auth/token` | Any | `hashToken`, `looksLikeJwt`, `stripBearer` |
+
+`hono` is an optional peer dependency: only `@baseworks/auth/hono` pulls it in.
+
+There is no browser-session subpath. Up to 0.3 the package carried a Next.js
+sign-in (`session`, `edge`, `url-helpers`); it trusted an unsigned cookie and an
+unverified id_token, and nothing used it. Signing a person in is auth-service's
+job — an app sends the browser to `/v1/auth/login` and reads `/v1/auth/session`.
+
+## Known gaps
+
+- **No revocation.** A token is valid until it expires. Every token carries a
+  `jti`, so a deny list can be added without a format change — but none exists.
+- **`@baseworks/auth/jwt` still exports `signHs256Jwt`.** That is the shared
+  secret era. Reach for `identity`; this stays only until the last consumer has
+  migrated.
+
+## Development
+
+```
+pnpm test        # vitest
+pnpm build       # tsup
+pnpm typecheck
+```
 
 ---
 
-## File Reference
+# Per-file reference
+
 
 ### `jwt.ts` → `@baseworks/auth/jwt`
 **Runtime:** Node.js — uses `node:crypto`
 
-HS256 JWT verification. Used by Flect services (`org-service`, `account-service`) to verify service-to-service JWTs signed with `JWT_SECRET`.
+HS256 sign and verify, plus `parseJwtPayload`. **Legacy** — the shared-secret era. New code uses `@baseworks/auth/identity`; this remains until the last consumer migrates.
 
 ```ts
 import { verifyHs256Jwt } from '@baseworks/auth/jwt'
@@ -39,7 +259,7 @@ const claims = verifyHs256Jwt(token, process.env.JWT_SECRET)
 ### `hono.ts` → `@baseworks/auth/hono`
 **Runtime:** Node.js + Hono — peer dep: `hono`
 
-Hono middleware. Reads `Authorization: Bearer <token>`, verifies with `jwt.ts`, sets `c.var.auth` (typed as `ServiceAuthUser`).
+Hono middleware. Reads `Authorization: Bearer <token>`, verifies against the realm JWKS (and the legacy secret while one is set), sets `c.var.auth` (typed as `ServiceAuthUser`).
 
 ```ts
 import { requireAuth } from '@baseworks/auth/hono'
@@ -137,71 +357,12 @@ const { token } = await pollCliAuth('https://api.flect.run', state)
 
 ---
 
-### `session.ts` → `@baseworks/auth/session`
-**Runtime:** Next.js (Server Components, Route Handlers) — dep: `next`
-
-Full OIDC PKCE session management for Next.js. Handles cookie set/clear, authorization code exchange, and token refresh. Uses `@baseworks/core` for base64url encoding and `pkce.ts` for PKCE generation.
-
-```ts
-import {
-  buildAuthorizationRedirect,
-  handleAuthorizationCallback,
-  getSessionFromCookies,
-  getServerAccessToken,
-  buildLogoutResponse,
-} from '@baseworks/auth/session'
-```
-
-Reads env vars: `OIDC_ISSUER`, `OIDC_CLIENT_ID`, `OIDC_CLIENT_SECRET` (optional).
-
----
-
-### `edge.ts` → `@baseworks/auth/edge`
-**Runtime:** Next.js (Middleware, Server Components) — dep: `next`
-
-Reads the session from two sources in priority order: **Pomerium JWT assertion headers** (`x-pomerium-jwt-assertion`) first, then **OIDC cookie** fallback. Returns an `EdgeSession`.
-
-```ts
-import { getEdgeSession } from '@baseworks/auth/edge'
-
-const session = await getEdgeSession()
-// session.provider: 'pomerium' | 'cookie' | 'anonymous'
-```
-
----
-
-### `url-helpers.ts` → `@baseworks/auth/url-helpers`
-**Runtime:** Next.js — dep: none
-
-Reads Next.js env vars and exposes URL builder functions.
-
-```ts
-import { buildAuthLoginUrl, buildAuthLogoutUrl } from '@baseworks/auth/url-helpers'
-
-const loginUrl  = buildAuthLoginUrl('/dashboard')
-const logoutUrl = buildAuthLogoutUrl('/')
-```
-
-Env vars read: `NEXT_PUBLIC_AUTH_URL`, `NEXT_PUBLIC_ACCOUNT_URL`, `APP_PUBLIC_URL`, `NEXT_PUBLIC_SITE_URL`.
-
----
-
-### `_internal.ts` — not exported
-Shared internal helpers. Not part of the public API.
-
-- `parseJwtPayload(token)` — splits a JWT and decodes the payload using `@baseworks/core/codec`. Used by `session.ts` and `edge.ts`.
-
----
-
 ## Internal Dependencies
 
 ```
 @baseworks/core/codec
   └── base64urlEncode / base64urlDecodeString
-        ├── pkce.ts        (PKCE verifier/challenge generation)
-        ├── session.ts     (cookie encode/decode)
-        └── _internal.ts  (parseJwtPayload)
-                └── edge.ts
+        └── pkce.ts        (PKCE verifier/challenge generation)
 ```
 
 ## When to Use What
@@ -210,7 +371,13 @@ Shared internal helpers. Not part of the public API.
 Service-to-service JWT verification (Hono/Node)
   └─ @baseworks/auth/hono         →  requireAuth middleware
 
-Raw HS256 JWT verify
+Mint a realm token / publish a JWKS (auth-service only)
+  └─ @baseworks/auth/identity     →  mint / jwks / loadSigningKey
+
+Verify without Hono
+  └─ @baseworks/auth/identity     →  verifier
+
+Raw HS256 JWT verify (legacy)
   └─ @baseworks/auth/jwt          →  verifyHs256Jwt
 
 User OIDC token verification (Workers/Node)
@@ -222,12 +389,10 @@ OIDC token + DB user sync in one step
 API key hashing / Bearer header parsing
   └─ @baseworks/auth/token        →  hashToken / stripBearer
 
-Next.js OIDC login / callback / logout
-  └─ @baseworks/auth/session      →  buildAuthorizationRedirect / handleAuthorizationCallback
-
-Who is this user in Next.js Middleware?
-  └─ @baseworks/auth/edge         →  getEdgeSession
+Sign a person in from a web app
+  └─ not this package             →  redirect to auth-service /v1/auth/login
 
 CLI browser auth
-  └─ @baseworks/auth/cli-auth     →  startCliAuth / pollCliAuth
+  └─ @baseworks/auth/cli          →  login / logout / auth status commands
+  └─ @baseworks/auth/cli-auth     →  startCliAuth / pollCliAuth (raw flow)
 ```

package/dist/chunk-3XJIAYEG.js

@@ -0,0 +1,88 @@
+// src/identity.ts
+import {
+  SignJWT,
+  jwtVerify,
+  exportJWK,
+  importPKCS8,
+  importSPKI,
+  calculateJwkThumbprint,
+  createLocalJWKSet,
+  createRemoteJWKSet
+} from "jose";
+var IDENTITY_ALG = "ES256";
+function toPem(raw, label) {
+  const value = raw.trim();
+  if (value.includes("-----BEGIN")) return value.replace(/\\n/g, "\n");
+  const decoded = Buffer.from(value, "base64").toString("utf8");
+  if (decoded.includes("-----BEGIN")) return decoded.trim();
+  throw new Error(`not a ${label} key: expected PEM, or base64 of PEM`);
+}
+async function jwkOf(key, kid) {
+  const jwk = await exportJWK(key);
+  jwk.alg = IDENTITY_ALG;
+  jwk.use = "sig";
+  jwk.kid = kid ?? await calculateJwkThumbprint(jwk);
+  return jwk;
+}
+async function loadSigningKey(privateKeyPem, kid) {
+  const pem = toPem(privateKeyPem, "PRIVATE");
+  const privateKey = await importPKCS8(pem, IDENTITY_ALG, { extractable: true });
+  const publicJwk = await jwkOf(privateKey, kid);
+  delete publicJwk.d;
+  return { privateKey, kid: publicJwk.kid, publicJwk };
+}
+async function loadPublicKey(publicKeyPem, kid) {
+  const key = await importSPKI(toPem(publicKeyPem, "PUBLIC"), IDENTITY_ALG, { extractable: true });
+  return jwkOf(key, kid);
+}
+function jwks(signing, retired = []) {
+  return { keys: [signing.publicJwk, ...retired] };
+}
+async function mint(key, claims, opts) {
+  const { sub, type, ...rest } = claims;
+  return new SignJWT({ type, ...rest }).setProtectedHeader({ alg: IDENTITY_ALG, kid: key.kid }).setSubject(sub).setIssuer(opts.issuer).setAudience(opts.audience).setIssuedAt().setJti(crypto.randomUUID()).setExpirationTime(`${opts.expiresInSeconds}s`).sign(key.privateKey);
+}
+function verifier(opts) {
+  if (!opts.jwksUri && !opts.jwks && !opts.legacyHs256Secret) {
+    throw new Error("verifier needs jwksUri, jwks, or legacyHs256Secret");
+  }
+  const keys = opts.jwks ? createLocalJWKSet(opts.jwks) : opts.jwksUri ? createRemoteJWKSet(new URL(opts.jwksUri)) : void 0;
+  const legacy = opts.legacyHs256Secret ? new TextEncoder().encode(opts.legacyHs256Secret) : void 0;
+  const expectations = {
+    ...opts.issuer ? { issuer: opts.issuer } : {},
+    ...opts.audience ? { audience: opts.audience } : {}
+  };
+  return async (token) => {
+    if (keys) {
+      try {
+        const { payload } = await jwtVerify(token, keys, {
+          ...expectations,
+          algorithms: [IDENTITY_ALG]
+        });
+        return payload;
+      } catch (err) {
+        if (!legacy) {
+          opts.onError?.(err);
+          return null;
+        }
+      }
+    }
+    if (!legacy) return null;
+    try {
+      const { payload } = await jwtVerify(token, legacy, { algorithms: ["HS256"] });
+      return payload;
+    } catch (err) {
+      opts.onError?.(err);
+      return null;
+    }
+  };
+}
+
+export {
+  IDENTITY_ALG,
+  loadSigningKey,
+  loadPublicKey,
+  jwks,
+  mint,
+  verifier
+};

package/dist/{chunk-C4V5LCFA.js → chunk-GXDYEKX7.js}

@@ -18,7 +18,7 @@ async function startCliAuth(apiBase) {
 }
 async function pollCliAuth(apiBase, state, opts = {}) {
   const intervalMs = opts.intervalMs ?? 2e3;
-  const timeoutMs = opts.timeoutMs ?? 3e5;
+  const timeoutMs = opts.timeoutMs ?? 6e5;
   const base = apiBase.replace(/\/+$/, "");
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
@@ -32,10 +32,10 @@ async function pollCliAuth(apiBase, state, opts = {}) {
       return { token: data.token };
     }
     if (data.status === "expired") {
-      throw new Error("Auth session expired \u2014 run login again");
+      throw new Error("the sign-in was not approved in time \u2014 run login again");
     }
   }
-  throw new Error("Auth timed out \u2014 run login again");
+  throw new Error("no approval received in time \u2014 run login again");
 }
 function sleep(ms) {
   return new Promise((resolve) => setTimeout(resolve, ms));

package/dist/cli-auth.d.ts

@@ -17,7 +17,13 @@ interface CliAuthResult {
 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;
 }
 /**

package/dist/cli-auth.js

@@ -1,7 +1,7 @@
 import {
   pollCliAuth,
   startCliAuth
-} from "./chunk-C4V5LCFA.js";
+} from "./chunk-GXDYEKX7.js";
 export {
   pollCliAuth,
   startCliAuth

package/dist/cli.d.ts

@@ -10,7 +10,21 @@ interface AuthCliDeps {
     onLogout?: () => void | Promise<void>;
     /** Open the browser automatically (default true). */
     openBrowser?: boolean;
+    /**
+     * Read the saved identity token. Providing it registers `<cli> auth status`,
+     * and lets `logout` warn when a token is still reachable afterwards — an
+     * environment variable that outranks the config file, typically.
+     */
+    getToken?: () => string | undefined;
+    /** Where the token came from, for display: a config path, or an env var name. */
+    tokenOrigin?: () => string | undefined;
+    /** Extra rows for `auth status`, e.g. the API base URL the app will call. */
+    statusRows?: () => [string, string][];
+    /** One-line hint printed after a successful login. */
+    nextSteps?: string;
 }
+/** `<cli> auth` and `<cli> auth status` — what the saved token says, no network. */
+declare function buildAuthCommand(deps: AuthCliDeps): Command;
 declare function addAuthCommands(program: Command, deps: AuthCliDeps): void;
 
-export { type AuthCliDeps, addAuthCommands };
+export { type AuthCliDeps, addAuthCommands, buildAuthCommand };

package/dist/cli.js

@@ -1,12 +1,16 @@
 import {
   pollCliAuth,
   startCliAuth
-} from "./chunk-C4V5LCFA.js";
+} from "./chunk-GXDYEKX7.js";
+import {
+  parseJwtPayload
+} from "./chunk-OD5XLL3O.js";
 
 // src/cli.ts
 import { spawn } from "child_process";
 import { Command } from "commander";
 import { clr, kv, success, warn, fatal } from "@baseworks/cli/display";
+import { fmtRelative } from "@baseworks/cli/fmt";
 function resolveBase(b) {
   return (typeof b === "function" ? b() : b).replace(/\/+$/, "");
 }
@@ -18,15 +22,37 @@ function openInBrowser(url) {
   } catch {
   }
 }
-function jwtSub(token) {
-  try {
-    const seg = token.split(".")[1];
-    if (!seg) return void 0;
-    const json = Buffer.from(seg.replace(/-/g, "+").replace(/_/g, "/"), "base64").toString("utf8");
-    return JSON.parse(json).sub;
-  } catch {
-    return void 0;
-  }
+function claimsOf(token) {
+  return parseJwtPayload(token) ?? {};
+}
+function expiryLine(claims) {
+  if (!claims.exp) return "unknown";
+  const at = new Date(claims.exp * 1e3).toISOString().replace("T", " ").slice(0, 16);
+  return `${at} UTC (${fmtRelative(claims.exp)})`;
+}
+function buildAuthCommand(deps) {
+  const cli = deps.cliName ?? "cli";
+  const status = () => {
+    const token = deps.getToken?.();
+    if (!token) fatal(`not signed in \u2014 run \`${cli} login\``);
+    const claims = claimsOf(token);
+    const rows = [...deps.statusRows?.() ?? []];
+    rows.push(["user", claims.sub ?? "unknown"]);
+    rows.push(["token type", claims.type ?? "unknown"]);
+    if (claims.iss) rows.push(["issuer", claims.iss]);
+    rows.push(["expires", expiryLine(claims)]);
+    const origin = deps.tokenOrigin?.();
+    if (origin) rows.push(["token from", origin]);
+    kv(rows);
+    if (claims.exp && claims.exp * 1e3 <= Date.now()) {
+      console.log("");
+      fatal(`the token has expired \u2014 run \`${cli} login\``);
+    }
+    console.log("");
+  };
+  const cmd = new Command("auth").description("Show the current sign-in (alias: auth status)").action(status);
+  cmd.addCommand(new Command("status").description("Show the current sign-in").action(status));
+  return cmd;
 }
 function addAuthCommands(program, deps) {
   const cli = deps.cliName ?? "cli";
@@ -40,12 +66,17 @@ function addAuthCommands(program, deps) {
   ${clr.cyan}${start.url}${clr.reset}
 `);
       if (deps.openBrowser !== false && opts.open !== false) openInBrowser(start.url);
-      const { token } = await pollCliAuth(base, start.state).catch((e) => fatal(e.message));
+      const minutes = Math.max(1, Math.round(start.expiresIn / 60));
+      console.log(`  ${clr.dim}Waiting for approval \u2014 the link is valid for ${minutes}m\u2026${clr.reset}`);
+      const { token } = await pollCliAuth(base, start.state, { timeoutMs: start.expiresIn * 1e3 }).catch((e) => fatal(e.message));
       await deps.onToken(token);
-      const sub = jwtSub(token);
+      const claims = claimsOf(token);
       success("Logged in.");
-      if (sub) kv([["user id", sub]]);
-      console.log(`  ${clr.dim}Next: ${cli} use  \xB7  ${cli} orgs${clr.reset}
+      const rows = [];
+      if (claims.sub) rows.push(["user", claims.sub]);
+      if (claims.exp) rows.push(["expires", expiryLine(claims)]);
+      if (rows.length) kv(rows);
+      console.log(`  ${clr.dim}Next: ${deps.nextSteps ?? `${cli} use  \xB7  ${cli} orgs`}${clr.reset}
 `);
     })
   );
@@ -54,9 +85,20 @@ function addAuthCommands(program, deps) {
       if (deps.onLogout) await deps.onLogout();
       else warn("No logout handler configured.");
       success("Logged out.");
+      const leftover = deps.getToken?.();
+      if (leftover) {
+        const origin = deps.tokenOrigin?.();
+        warn(`A token is still in effect${origin ? ` (${origin})` : ""} and takes precedence.`);
+      }
+      console.log(
+        `  ${clr.dim}The token stays valid on the server until it expires; there is no server-side revocation.${clr.reset}
+`
+      );
     })
   );
+  if (deps.getToken) program.addCommand(buildAuthCommand(deps));
 }
 export {
-  addAuthCommands
+  addAuthCommands,
+  buildAuthCommand
 };