flipstream 0.4.0

package/dist/commands/workspaces/list.js

@@ -0,0 +1,87 @@
+import { Flags } from '@oclif/core';
+import { createAuthedAdminClient } from '../../lib/api/admin-client.js';
+import { mapDataError } from '../../lib/api/errors.js';
+import { drainPages, normalizeList } from '../../lib/api/list.js';
+import { projectWorkspace } from '../../lib/api/projections.js';
+import { refresh } from '../../lib/auth/refresh.js';
+import { BaseCommand } from '../../lib/command/base.js';
+import { paginationFlags } from '../../lib/command/flags.js';
+import { AuthRequiredError } from '../../lib/errors.js';
+import { renderTable } from '../../lib/output/table.js';
+import { createStore } from '../../lib/store/index.js';
+const COUNT_CONCURRENCY = 5;
+export default class WorkspacesList extends BaseCommand {
+    static aliases = ['ws:list'];
+    static description = 'List the workspaces (the Flipstream business entity, "Client" in the admin API) in your organization. ' +
+        'Account-scoped server-side (the CLI sends no org id). Targets the OAuth/admin host (whereas `query` targets ' +
+        'the data host).';
+    static examples = [
+        '<%= config.bin %> workspaces list',
+        '<%= config.bin %> ws list --json',
+        '<%= config.bin %> ws list --all',
+        '<%= config.bin %> ws list --q acme --limit 10',
+    ];
+    static flags = {
+        ...paginationFlags,
+        'with-connection-counts': Flags.boolean({
+            description: 'Add connection_count per workspace (opt-in: one extra request each, N+1).',
+        }),
+    };
+    static summary = "List your organization's workspaces.";
+    async run() {
+        // The admin host == the OAuth issuer (creds live here); --host overrides both.
+        const host = this.resolvedHost();
+        const store = createStore();
+        if (!store.load(host))
+            throw AuthRequiredError.notLoggedIn();
+        const client = createAuthedAdminClient({
+            accessTokenIfFresh: (authHost) => store.accessTokenIfFresh(authHost),
+            authHost: host,
+            host,
+            refresh: (authHost) => refresh(authHost, { store, timeoutMs: this.flags.timeout }),
+            timeoutMs: this.flags.timeout,
+        });
+        const fetchPage = async (page) => {
+            try {
+                const raw = await client.get('/clients', {
+                    query: { limit: page.limit, offset: page.offset, q: this.flags.q, sort: this.flags.sort },
+                });
+                return normalizeList(raw);
+            }
+            catch (error) {
+                throw mapDataError(error);
+            }
+        };
+        const start = { limit: this.flags.limit, offset: this.flags.offset };
+        const envelope = this.flags.all ? await drainPages(fetchPage, start) : await fetchPage(start);
+        const projected = { count: envelope.count, records: envelope.records.map((record) => projectWorkspace(record)) };
+        if (this.flags['with-connection-counts'])
+            await this.addConnectionCounts(client, projected.records);
+        return this.respondList(projected, (records) => {
+            const columns = [
+                { key: 'name', name: 'Name' },
+                { key: 'id', name: 'ID' },
+            ];
+            if (this.flags['with-connection-counts'])
+                columns.push({ key: 'connection_count', name: 'Conns' });
+            renderTable(records, columns, 'No workspaces.');
+        });
+    }
+    // E7-R0: opt-in N+1 — fetch each workspace's connection count with bounded
+    // concurrency. Best-effort: a failed count is null, never failing the list.
+    async addConnectionCounts(client, records) {
+        for (let i = 0; i < records.length; i += COUNT_CONCURRENCY) {
+            const chunk = records.slice(i, i + COUNT_CONCURRENCY);
+            // eslint-disable-next-line no-await-in-loop -- bounded concurrency: one chunk at a time
+            await Promise.all(chunk.map(async (workspace) => {
+                try {
+                    const conns = normalizeList(await client.get(`/clients/${String(workspace.id)}/connections`, { query: { limit: 1 } }));
+                    workspace.connection_count = conns.count;
+                }
+                catch {
+                    workspace.connection_count = null;
+                }
+            }));
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/index.js

@@ -0,0 +1 @@
+export { run } from '@oclif/core';

package/dist/lib/api/admin-client.d.ts

@@ -0,0 +1,19 @@
+import { type RefreshDeps } from './retry.js';
+export interface AdminGetOptions {
+    query?: Record<string, boolean | number | string | undefined>;
+    timeoutMs?: number;
+}
+export interface AdminClient {
+    get(path: string, options?: AdminGetOptions): Promise<unknown>;
+}
+export interface AdminClientOptions {
+    getToken: () => null | Promise<null | string> | string;
+    host?: string;
+    timeoutMs?: number;
+}
+export declare function createAdminClient(options: AdminClientOptions): AdminClient;
+export interface AuthedAdminClientDeps extends RefreshDeps {
+    host?: string;
+    timeoutMs?: number;
+}
+export declare function createAuthedAdminClient(deps: AuthedAdminClientDeps): AdminClient;

package/dist/lib/api/admin-client.js

@@ -0,0 +1,44 @@
+import { ADMIN_HOST } from '../config/constants.js';
+import { requestJson } from './http.js';
+import { withFreshToken } from './retry.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+function rstrip(host) {
+    return host.replace(/\/+$/, '');
+}
+// Transport-only client to the ADMIN origin (today the same origin as the AUTH
+// issuer — the stored bearer is accepted). GET with a path + query params; built
+// on the shared requestJson core. No entity knowledge.
+export function createAdminClient(options) {
+    const base = rstrip(options.host ?? ADMIN_HOST);
+    const defaultTimeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return {
+        async get(path, getOptions = {}) {
+            const token = await options.getToken();
+            return requestJson({
+                method: 'GET',
+                query: getOptions.query,
+                timeoutMs: getOptions.timeoutMs ?? defaultTimeout,
+                token,
+                url: `${base}${path}`,
+            });
+        },
+    };
+}
+// The authed admin client: the SAME withFreshToken 401->refresh->retry-once
+// wrapper (E7-0a) around an admin GET. Refresh targets the AUTH issuer (== admin
+// host here). This is what commands use.
+export function createAuthedAdminClient(deps) {
+    const base = rstrip(deps.host ?? ADMIN_HOST);
+    const defaultTimeout = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return {
+        get(path, getOptions = {}) {
+            return withFreshToken(deps, (token) => requestJson({
+                method: 'GET',
+                query: getOptions.query,
+                timeoutMs: getOptions.timeoutMs ?? defaultTimeout,
+                token,
+                url: `${base}${path}`,
+            }));
+        },
+    };
+}

package/dist/lib/api/client.d.ts

@@ -0,0 +1,13 @@
+export interface DataClientOptions {
+    getToken: () => null | Promise<null | string> | string;
+    host?: string;
+    queryPath?: string;
+    timeoutMs?: number;
+}
+export interface PostQueryOptions {
+    timeoutMs?: number;
+}
+export interface DataClient {
+    postQuery(body: unknown, options?: PostQueryOptions): Promise<unknown>;
+}
+export declare function createDataClient(options: DataClientOptions): DataClient;

package/dist/lib/api/client.js

@@ -0,0 +1,21 @@
+import { DATA_HOST } from '../config/constants.js';
+import { requestJson } from './http.js';
+const DEFAULT_QUERY_PATH = '/query';
+const DEFAULT_TIMEOUT_MS = 30_000;
+function rstrip(host) {
+    return host.replace(/\/+$/, '');
+}
+// Transport-only client to the DATA origin (distinct from the AUTH issuer). It
+// attaches the bearer (in-process only), sends the OPAQUE body verbatim, and
+// returns the parsed JSON on 2xx. It interprets NO query semantics. Built on the
+// shared requestJson core; refresh/retry (E4-2) and error mapping (E4-3) wrap it.
+export function createDataClient(options) {
+    const url = `${rstrip(options.host ?? DATA_HOST)}${options.queryPath ?? DEFAULT_QUERY_PATH}`;
+    const defaultTimeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    return {
+        async postQuery(body, callOptions = {}) {
+            const token = await options.getToken();
+            return requestJson({ body, method: 'POST', timeoutMs: callOptions.timeoutMs ?? defaultTimeout, token, url });
+        },
+    };
+}

package/dist/lib/api/connections.d.ts

@@ -0,0 +1,14 @@
+import { type AdminClient } from './admin-client.js';
+export interface ConnectionsQuery {
+    all?: boolean;
+    limit: number;
+    offset: number;
+    q?: string;
+    sort?: string;
+    workspace?: string;
+}
+export declare function fetchConnections(client: AdminClient, query: ConnectionsQuery): Promise<{
+    count: number;
+    records: Array<Record<string, unknown>>;
+}>;
+export declare function resolveWorkspaceNames(client: AdminClient, records: Array<Record<string, unknown>>): Promise<void>;

package/dist/lib/api/connections.js

@@ -0,0 +1,44 @@
+import { mapDataError } from './errors.js';
+import { drainPages, normalizeList } from './list.js';
+import { projectConnection } from './projections.js';
+// Fetch + project connections (org-wide or per-workspace), draining pages when
+// requested. Errors are mapped to the E3 model.
+export async function fetchConnections(client, query) {
+    const path = query.workspace ? `/clients/${query.workspace}/connections` : '/connections';
+    const fetchPage = async (page) => {
+        try {
+            return normalizeList(await client.get(path, { query: { limit: page.limit, offset: page.offset, q: query.q, sort: query.sort } }));
+        }
+        catch (error) {
+            throw mapDataError(error);
+        }
+    };
+    const start = { limit: query.limit, offset: query.offset };
+    const envelope = query.all ? await drainPages(fetchPage, start) : await fetchPage(start);
+    return { count: envelope.count, records: envelope.records.map((record) => projectConnection(record)) };
+}
+// Fill `client_name` for connections that lack it (the API didn't nest the
+// client): one drained workspace lookup, keyed by id. Skipped when all already
+// have it; best-effort (leaves names unresolved rather than failing the list).
+export async function resolveWorkspaceNames(client, records) {
+    const missing = records.some((record) => record.client_name === undefined && record.client_id !== undefined);
+    if (!missing)
+        return;
+    const names = new Map();
+    try {
+        const workspaces = await drainPages(async (page) => normalizeList(await client.get('/clients', { query: { limit: page.limit, offset: page.offset } })), { limit: 100, offset: 0 });
+        for (const workspace of workspaces.records) {
+            const ws = workspace;
+            if (ws.id)
+                names.set(ws.id, ws.name ?? '');
+        }
+    }
+    catch {
+        return;
+    }
+    for (const record of records) {
+        if (record.client_name === undefined && typeof record.client_id === 'string') {
+            record.client_name = names.get(record.client_id) ?? null;
+        }
+    }
+}

package/dist/lib/api/errors.d.ts

@@ -0,0 +1,7 @@
+import { CliError } from '../errors.js';
+export declare function parseDataErrorMessage(status: number, bodyText: string): {
+    error?: string;
+    message: string;
+};
+export declare function notFoundError(): CliError;
+export declare function mapDataError(error: unknown): CliError;

package/dist/lib/api/errors.js

@@ -0,0 +1,68 @@
+import { AuthFailedError, CliError, DataHttpError, NetworkError } from '../errors.js';
+import { ExitCode } from '../exit-codes.js';
+import { redact } from '../output/redact.js';
+const DETAIL_MAX = 500;
+// Parse an error body into a useful message. RFC 6749 {error, error_description}
+// (the OAuth/auth path) becomes '<error>: <desc>'. The DATA host instead returns
+// a {detail} body (e.g. FastAPI 422 validation) — surface it (truncated) as
+// 'HTTP <status>: <detail>' so an agent can fix its query rather than seeing a
+// bare status. A non-JSON / fieldless body degrades to 'HTTP <status>'. The
+// message is redacted so a malicious/echoing body cannot smuggle a token in.
+export function parseDataErrorMessage(status, bodyText) {
+    let providerError;
+    let raw = `HTTP ${status}`;
+    try {
+        const parsed = JSON.parse(bodyText);
+        if (parsed.error) {
+            providerError = parsed.error;
+            raw = parsed.error_description ? `${parsed.error}: ${parsed.error_description}` : parsed.error;
+        }
+        else if (parsed.detail !== undefined) {
+            const detail = typeof parsed.detail === 'string' ? parsed.detail : JSON.stringify(parsed.detail);
+            raw = `HTTP ${status}: ${detail.slice(0, DETAIL_MAX)}`;
+        }
+    }
+    catch {
+        // Not JSON — keep the 'HTTP <status>' fallback.
+    }
+    return { error: providerError, message: redact(raw) };
+}
+// The collapsed, existence-safe 404/foreign-id error (exit 1, stable 'not_found'
+// code). Shared by the 404 mapper branch and the by-id commands, which also
+// collapse a 403-on-a-foreign-id to this to avoid leaking existence.
+export function notFoundError() {
+    return new CliError('Resource not found or not in your organization.', 'not_found', ExitCode.GENERIC);
+}
+// Map a DataClient/retry failure onto the E3 error model with a deterministic exit
+// code (AuthRequired->4, AuthFailed->5, Network->7, Timeout->8). Network, Timeout
+// and AuthRequired (session_expired) pass through unchanged; a DataHttpError is
+// classified by provider error + status. The audience-mismatch case
+// (invalid_target) is surfaced explicitly as a re-bind-required auth error, never
+// a generic 500. Tokens never reach the message (redacted in parseDataErrorMessage).
+export function mapDataError(error) {
+    if (error instanceof DataHttpError) {
+        const { error: providerError, message } = parseDataErrorMessage(error.status, error.bodyText);
+        if (providerError === 'invalid_target') {
+            return new AuthFailedError(`invalid_target: re-bind required — ${message}`, 'invalid_target');
+        }
+        if (error.status === 403) {
+            // Fixed message (NOT the upstream body) — stable agent guidance, no leak.
+            return new AuthFailedError('Your role cannot perform this action.', 'role_forbidden');
+        }
+        if (error.status === 401) {
+            return new AuthFailedError(message, 'data_auth_failed');
+        }
+        if (error.status === 404)
+            return notFoundError();
+        if (error.status >= 500) {
+            return new NetworkError(message, 'data_upstream_error');
+        }
+        return new CliError(message, providerError ?? 'data_request_failed', ExitCode.GENERIC);
+    }
+    // Network/Timeout/AuthRequired (and any other CliError) are already typed.
+    if (error instanceof CliError)
+        return error;
+    if (error instanceof Error)
+        return new NetworkError(`Data request failed: ${redact(error.message)}`);
+    return new NetworkError('Data request failed');
+}

package/dist/lib/api/http.d.ts

@@ -0,0 +1,9 @@
+export interface JsonRequest {
+    body?: unknown;
+    method: string;
+    query?: Record<string, boolean | number | string | undefined>;
+    timeoutMs?: number;
+    token?: null | string;
+    url: string;
+}
+export declare function requestJson(req: JsonRequest): Promise<unknown>;

package/dist/lib/api/http.js

@@ -0,0 +1,55 @@
+import { DataHttpError, NetworkError, TimeoutError } from '../errors.js';
+const DEFAULT_TIMEOUT_MS = 30_000;
+function withQuery(url, query) {
+    if (!query)
+        return url;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        if (value !== undefined)
+            params.set(key, String(value));
+    }
+    const qs = params.toString();
+    return qs ? `${url}?${qs}` : url;
+}
+// The single shared request core for first-party API calls (data + admin). Sends
+// JSON, attaches the bearer in-process only, and aborts on timeout. Returns the
+// parsed JSON on 2xx (raw text if the body is not JSON); throws
+// DataHttpError(status, body) on non-2xx, TimeoutError on abort, NetworkError on a
+// transport failure. It carries NO entity/query semantics — method, url, body and
+// query are entirely the caller's.
+export async function requestJson(req) {
+    const timeoutMs = req.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const headers = { accept: 'application/json' };
+    if (req.body !== undefined)
+        headers['content-type'] = 'application/json';
+    if (req.token)
+        headers.authorization = `Bearer ${req.token}`;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetch(withQuery(req.url, req.query), {
+            body: req.body === undefined ? undefined : JSON.stringify(req.body),
+            headers,
+            method: req.method,
+            signal: controller.signal,
+        });
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new TimeoutError(`Request timed out after ${timeoutMs}ms`);
+        throw new NetworkError(`Request failed: ${error.message}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    const text = await response.text();
+    if (response.status < 200 || response.status >= 300)
+        throw new DataHttpError(response.status, text);
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/lib/api/ids.d.ts

@@ -0,0 +1 @@
+export declare function assertUuid(id: string, label?: string): void;

package/dist/lib/api/ids.js

@@ -0,0 +1,8 @@
+import { UsageError } from '../errors.js';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// Validate a UUID-shaped id BEFORE any request (a malformed id is a usage error,
+// exit 2, with no round trip). Used by the by-id admin commands.
+export function assertUuid(id, label = 'id') {
+    if (!UUID_RE.test(id))
+        throw new UsageError(`Invalid ${label} — expected a UUID.`);
+}

package/dist/lib/api/list.d.ts

@@ -0,0 +1,12 @@
+export interface ListEnvelope<T = unknown> {
+    count: number;
+    records: T[];
+}
+export declare function normalizeList(raw: unknown): ListEnvelope;
+export declare function drainPages(fetchPage: (page: {
+    limit: number;
+    offset: number;
+}) => Promise<ListEnvelope>, start: {
+    limit: number;
+    offset: number;
+}): Promise<ListEnvelope>;

package/dist/lib/api/list.js

@@ -0,0 +1,31 @@
+import { UsageError } from '../errors.js';
+// Normalize the admin list endpoints' TWO response shapes into one envelope:
+// a bare array -> {count: length, records}; {count, records} -> passthrough.
+// Anything else is a deterministic typed error (never a thrown raw object).
+export function normalizeList(raw) {
+    if (Array.isArray(raw))
+        return { count: raw.length, records: raw };
+    if (raw && typeof raw === 'object' && Array.isArray(raw.records)) {
+        const obj = raw;
+        return { count: typeof obj.count === 'number' ? obj.count : obj.records.length, records: obj.records };
+    }
+    throw new UsageError('Unexpected list response shape from the admin API.', 'unexpected_list_shape');
+}
+// Drain pages until a short final page (or `count` reached), concatenating
+// records. Issues no extra empty request. `fetchPage` returns a normalized
+// envelope for a given offset/limit.
+export async function drainPages(fetchPage, start) {
+    const records = [];
+    let { offset } = start;
+    let count = 0;
+    for (;;) {
+        // eslint-disable-next-line no-await-in-loop -- pages are inherently sequential
+        const page = await fetchPage({ limit: start.limit, offset });
+        count = page.count;
+        records.push(...page.records);
+        if (page.records.length < start.limit || records.length >= count)
+            break;
+        offset += start.limit;
+    }
+    return { count, records };
+}

package/dist/lib/api/projections.d.ts

@@ -0,0 +1,2 @@
+export declare function projectWorkspace(raw: unknown): Record<string, unknown>;
+export declare function projectConnection(raw: unknown): Record<string, unknown>;

package/dist/lib/api/projections.js

@@ -0,0 +1,34 @@
+import { redact } from '../output/redact.js';
+const WORKSPACE_CORE = ['organization_id', 'slug', 'business_type', 'client_main_goal', 'created_on'];
+const CONNECTION_CORE = ['name', 'client_id', 'type', 'active', 'backfill', 'data_refresh_status', 'created_on'];
+// Project a raw admin Client into a stable "workspace" shape: id + name + present
+// core fields + owner_email (from the nested owner) + a redacted `raw` passthrough
+// so it survives schema drift. Adds/invents no fields.
+export function projectWorkspace(raw) {
+    const client = (raw ?? {});
+    const out = { id: client.id, name: client.name };
+    for (const key of WORKSPACE_CORE)
+        if (client[key] !== undefined)
+            out[key] = client[key];
+    const owner = client.owner;
+    if (owner?.email)
+        out.owner_email = owner.email;
+    out.raw = redact(raw);
+    return out;
+}
+// Project a raw Connection into a stable shape: id + present source metadata + a
+// redacted `raw` (so secret_id/secret/parameters are masked by E7-0b).
+export function projectConnection(raw) {
+    const conn = (raw ?? {});
+    const out = { id: conn.id };
+    for (const key of CONNECTION_CORE)
+        if (conn[key] !== undefined)
+            out[key] = conn[key];
+    // Surface the owning workspace's name from a nested `client` when present (the
+    // command resolves it from a workspace lookup otherwise).
+    const client = conn.client;
+    if (client?.name)
+        out.client_name = client.name;
+    out.raw = redact(raw);
+    return out;
+}

package/dist/lib/api/retry.d.ts

@@ -0,0 +1,13 @@
+import { type DataClient } from './client.js';
+export interface RefreshDeps {
+    accessTokenIfFresh: (authHost: string) => null | string;
+    authHost: string;
+    refresh: (authHost: string) => Promise<null | string>;
+}
+export declare function withFreshToken<T>(deps: RefreshDeps, fn: (token: string) => Promise<T>): Promise<T>;
+export interface AuthedDataClientDeps extends RefreshDeps {
+    host?: string;
+    queryPath?: string;
+    timeoutMs?: number;
+}
+export declare function createAuthedDataClient(deps: AuthedDataClientDeps): DataClient;

package/dist/lib/api/retry.js

@@ -0,0 +1,37 @@
+import { DATA_HOST } from '../config/constants.js';
+import { AuthRequiredError, DataHttpError } from '../errors.js';
+import { requestJson } from './http.js';
+// The single authoritative 401 -> refresh -> retry-once wrapper, METHOD-AGNOSTIC:
+// it runs `fn(token)` for ANY request (GET or POST). It proactively silent-
+// refreshes when the cached token is stale, and on a 401 (DataHttpError) it
+// refreshes EXACTLY once and retries EXACTLY once. A null refresh surfaces a typed
+// session_expired (exit 4). Non-401 errors (403/5xx/network/timeout) are never
+// retried; a second consecutive 401 propagates. Refresh always targets authHost.
+export async function withFreshToken(deps, fn) {
+    let token = deps.accessTokenIfFresh(deps.authHost) ?? (await deps.refresh(deps.authHost));
+    if (!token)
+        throw AuthRequiredError.sessionExpired();
+    try {
+        return await fn(token);
+    }
+    catch (error) {
+        if (!(error instanceof DataHttpError) || error.status !== 401)
+            throw error;
+        token = await deps.refresh(deps.authHost);
+        if (!token)
+            throw AuthRequiredError.sessionExpired();
+        return fn(token);
+    }
+}
+// The authed DATA client: withFreshToken wrapped around a POST of the opaque body
+// to the data host's /query. (The admin client, E7-1a, wraps GETs with the same
+// withFreshToken — one refresh/retry implementation for both.)
+export function createAuthedDataClient(deps) {
+    const url = `${(deps.host ?? DATA_HOST).replace(/\/+$/, '')}${deps.queryPath ?? '/query'}`;
+    const defaultTimeout = deps.timeoutMs ?? 30_000;
+    return {
+        postQuery(body, callOptions = {}) {
+            return withFreshToken(deps, (token) => requestJson({ body, method: 'POST', timeoutMs: callOptions.timeoutMs ?? defaultTimeout, token, url }));
+        },
+    };
+}

package/dist/lib/auth/claims.d.ts

@@ -0,0 +1,3 @@
+import type { TokenStore } from '../store/index.js';
+export declare function decodeJwtClaimsUnverified(accessToken: string): null | Record<string, unknown>;
+export declare function tokenClaims(host: string, store: TokenStore): null | Record<string, unknown>;

package/dist/lib/auth/claims.js

@@ -0,0 +1,20 @@
+// Decode (WITHOUT verifying the signature) a JWT payload — DISPLAY ONLY.
+// MUST NOT be used for any authorization / request-gating decision (the CLI is a
+// thin client; the server validates tokens). A convention test guards this.
+export function decodeJwtClaimsUnverified(accessToken) {
+    const parts = accessToken.split('.');
+    if (parts.length < 2)
+        return null;
+    try {
+        const padded = parts[1] + '='.repeat((4 - (parts[1].length % 4)) % 4);
+        return JSON.parse(Buffer.from(padded, 'base64url').toString('utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+// Decoded claims of the stored access token for `host` (display only), or null.
+export function tokenClaims(host, store) {
+    const creds = store.load(host);
+    return creds ? decodeJwtClaimsUnverified(creds.accessToken) : null;
+}

package/dist/lib/auth/discovery.d.ts

@@ -0,0 +1,13 @@
+export { DiscoveryError } from '../errors.js';
+export interface Metadata {
+    authorizationEndpoint: string;
+    issParameterSupported?: boolean;
+    issuer: string;
+    registrationEndpoint: string;
+    revocationEndpoint: string;
+    tokenEndpoint: string;
+}
+export declare function metadataFromDoc(host: string, doc: Record<string, unknown>): Metadata;
+export declare function fetchMetadata(host: string, options?: {
+    timeoutMs?: number;
+}): Promise<Metadata>;

package/dist/lib/auth/discovery.js

@@ -0,0 +1,62 @@
+import { DiscoveryError } from '../errors.js';
+export { DiscoveryError } from '../errors.js';
+function rstrip(host) {
+    return host.replace(/\/+$/, '');
+}
+function asString(value, fallback) {
+    return typeof value === 'string' && value.length > 0 ? value : fallback;
+}
+// Build Metadata from a discovery doc with per-field fallback to the conventional
+// /oauth/* paths. Rejects only when code_challenge_methods_supported is PRESENT
+// and lacks S256 (the real v0.0.61 doc omits it — skip-on-absent).
+export function metadataFromDoc(host, doc) {
+    const methods = doc.code_challenge_methods_supported;
+    if (Array.isArray(methods) && !methods.includes('S256')) {
+        throw new DiscoveryError('Server does not advertise PKCE S256 support');
+    }
+    const base = rstrip(host);
+    const iss = doc.authorization_response_iss_parameter_supported;
+    return {
+        authorizationEndpoint: asString(doc.authorization_endpoint, `${base}/oauth/authorize`),
+        issParameterSupported: typeof iss === 'boolean' ? iss : undefined,
+        issuer: asString(doc.issuer, base),
+        registrationEndpoint: asString(doc.registration_endpoint, `${base}/oauth/register`),
+        revocationEndpoint: asString(doc.revocation_endpoint, `${base}/oauth/revoke`),
+        tokenEndpoint: asString(doc.token_endpoint, `${base}/oauth/token`),
+    };
+}
+// Fetch the RFC 8414 discovery document and resolve Metadata. On 404 falls back
+// to the full conventional doc; surfaces typed DiscoveryError for 5xx, non-JSON,
+// timeout, and unreachable host.
+export async function fetchMetadata(host, options = {}) {
+    const base = rstrip(host);
+    const url = `${base}/.well-known/oauth-authorization-server`;
+    const timeoutMs = options.timeoutMs ?? 10_000;
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    let response;
+    try {
+        response = await fetch(url, { headers: { accept: 'application/json' }, signal: controller.signal });
+    }
+    catch (error) {
+        const reason = controller.signal.aborted ? `timed out after ${timeoutMs}ms` : error.message;
+        throw new DiscoveryError(`Could not reach ${base}: ${reason}`);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    if (response.status === 404) {
+        return metadataFromDoc(base, {});
+    }
+    if (!response.ok) {
+        throw new DiscoveryError(`Discovery failed: HTTP ${response.status}`);
+    }
+    let doc;
+    try {
+        doc = (await response.json());
+    }
+    catch {
+        throw new DiscoveryError('Discovery document is not valid JSON');
+    }
+    return metadataFromDoc(base, doc);
+}