@pitcher/cli-scripts 2.21.0 → 3.0.1

package/dist/src/core/http.js

@@ -1,40 +1,49 @@
 import axios from 'axios';
-import { resolveBaseUrl } from './baseUrl.js';
-import { authHeaders, credentialOf } from './credential.js';
 import { createCliError, isCliError } from './errors.js';
-export function makeClient(baseUrl, cred, opts = {}) {
-    return axios.create({
-        ...opts,
+import { authHeaders, resolveRequestTarget } from './target.js';
+/**
+ * A static credential sets its header once, exactly as before. A function source (a `p login` session) is
+ * awaited PER REQUEST by an interceptor, so a long-running client (`dev-sync watch`) picks up a refreshed
+ * token and every builder stays synchronous.
+ */
+export function makeClient(baseUrl, source, opts = {}) {
+    const { headers, ...rest } = opts;
+    const client = axios.create({
+        ...rest,
         baseURL: baseUrl,
         headers: {
             accept: 'application/json',
-            ...authHeaders(cred),
+            ...headers,
+            ...(typeof source === 'function' ? {} : authHeaders(source)),
         },
     });
+    if (typeof source === 'function') {
+        client.interceptors.request.use(async (config) => {
+            for (const [name, value] of Object.entries(authHeaders(await source())))
+                config.headers.set(name, value);
+            return config;
+        });
+    }
+    return client;
 }
 /** Resolve auth + base URL into a client, or use an injected one (tests). */
 export function clientFor(opts, deps = {}) {
-    return deps.client ?? makeClient(resolveBaseUrl({ org: opts.org, url: opts.url }), credentialOf(opts));
+    if (deps.client)
+        return deps.client;
+    const target = resolveRequestTarget(opts);
+    return makeClient(target.baseUrl, target.source);
 }
 export const CLICKHOUSE_API_BASE_URL = 'https://clickhouse.pitcher.com';
 /**
- * Client for the clickhouse-api analytics service (PIT-7647). The service lives
- * on ONE host for every env/region; `x-original-domain` (the same `--org`/`--url`
- * resolution as Django calls) is what routes the request to the right core for
- * key validation + tenant scoping, so the usual flags select test vs prod.
+ * Client for the clickhouse-api analytics service (PIT-7647). The service lives on ONE host for every
+ * env/region; `x-original-domain` routes the request to the right core for key/token validation and tenant
+ * scoping. It is the TARGET's host, so a session call is scoped to the session's org, never a default.
  */
 export function clickhouseClientFor(opts, deps = {}) {
     if (deps.client)
         return deps.client;
-    const originalDomain = new URL(resolveBaseUrl({ org: opts.org, url: opts.url })).hostname;
-    return axios.create({
-        baseURL: CLICKHOUSE_API_BASE_URL,
-        headers: {
-            accept: 'application/json',
-            ...authHeaders(credentialOf(opts)),
-            'x-original-domain': originalDomain,
-        },
-    });
+    const target = resolveRequestTarget(opts);
+    return makeClient(CLICKHOUSE_API_BASE_URL, target.source, { headers: { 'x-original-domain': target.host } });
 }
 /** Max number of `details` entries folded into a message before it is summarised. */
 const MAX_DETAIL_PARTS = 3;
@@ -127,7 +136,10 @@ function truncateDetails(text, max) {
     const points = [...text];
     if (points.length <= max)
         return text;
-    return `${points.slice(0, max - 1).join('').trimEnd()}\u2026`;
+    return `${points
+        .slice(0, max - 1)
+        .join('')
+        .trimEnd()}\u2026`;
 }
 /**
  * Flatten a `details` value into one capped, de-duplicated line.

package/dist/src/core/kpiTypes.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Every `p analytics kpi --type` value clickhouse-api implements. A literal copy: this package is published to
+ * npm and cannot import `clickhouse-api` (`src/lib/kpi-types.ts`, the source of truth). There is no aggregate
+ * `all` type. Drift guard: `test/commands/analyticsKpiTypes.test.ts` reads the clickhouse-api file and fails on
+ * any difference.
+ */
+export declare const KPI_TYPES: readonly ["total-canvases-created", "total-saved-canvases", "total-content-files", "total-templates", "total-sections", "total-members", "avg-file-duration", "avg-canvas-duration", "total-active-users", "total-files", "total-presentation-views", "sharing-kpis"];
+export type KpiType = (typeof KPI_TYPES)[number];
+export declare function isKpiType(value: string): value is KpiType;

package/dist/src/core/kpiTypes.js

@@ -0,0 +1,23 @@
+/**
+ * Every `p analytics kpi --type` value clickhouse-api implements. A literal copy: this package is published to
+ * npm and cannot import `clickhouse-api` (`src/lib/kpi-types.ts`, the source of truth). There is no aggregate
+ * `all` type. Drift guard: `test/commands/analyticsKpiTypes.test.ts` reads the clickhouse-api file and fails on
+ * any difference.
+ */
+export const KPI_TYPES = [
+    'total-canvases-created',
+    'total-saved-canvases',
+    'total-content-files',
+    'total-templates',
+    'total-sections',
+    'total-members',
+    'avg-file-duration',
+    'avg-canvas-duration',
+    'total-active-users',
+    'total-files',
+    'total-presentation-views',
+    'sharing-kpis',
+];
+export function isKpiType(value) {
+    return KPI_TYPES.includes(value);
+}

package/dist/src/core/ld.d.ts

@@ -1,5 +1,6 @@
 import { type AxiosInstance } from 'axios';
 import { type CommonOpts } from './http.js';
+import { type RequestTarget } from './target.js';
 import { type CliError } from './errors.js';
 export interface LdCommonOpts extends CommonOpts {
     instanceId?: string;
@@ -38,7 +39,7 @@ export declare function pickTruthy<T extends object>(opts: T, keys: readonly (ke
  * `app_metadata->>'name' = 'ld-app'` and `instance_id = $2`, `type = 'app'`, not deleted)
  * over a credential the CLI actually holds.
  */
-export declare function resolveLdBaseUrl(opts: LdCommonOpts, deps?: LdDeps, env?: NodeJS.ProcessEnv): Promise<string>;
+export declare function resolveLdBaseUrl(opts: LdCommonOpts, deps?: LdDeps, env?: NodeJS.ProcessEnv, target?: RequestTarget): Promise<string>;
 /** Max cached L&D tokens (one per distinct Pitcher token × L&D base). Oldest-used evicted first. */
 export declare const LD_TOKEN_CACHE_MAX = 500;
 /** Test-only: reset the L&D token-exchange cache between cases. */
@@ -60,7 +61,7 @@ export declare function createLdAuthHttp(): AxiosInstance;
  * useless once that expires, and its own lifetime is env-configurable (`JWT_EXPIRES_IN`), so neither
  * is assumed. A token whose TTL cannot be read, or is already ≤ 0, is used once and not cached.
  */
-export declare function exchangeLdToken(ldBase: string, pitcherToken: string, deps: LdDeps, env: NodeJS.ProcessEnv): Promise<string>;
+export declare function exchangeLdToken(ldBase: string, pitcherToken: string, deps: LdDeps, env: NodeJS.ProcessEnv, loopbackAllowed?: boolean): Promise<string>;
 /**
  * Build (or inject, in tests) an axios client pointed at the resolved L&D Lambda base.
  * API key → sent as-is (`x-api-key`). Bearer → exchanged for an L&D JWT first (the Lambda does not

package/dist/src/core/ld.js

@@ -1,8 +1,7 @@
 import axios from 'axios';
 import { createHash } from 'crypto';
-import { credentialOf } from './credential.js';
-import { clientFor, makeClient, toCliError } from './http.js';
-import { resolveBaseUrl } from './baseUrl.js';
+import { makeClient, toCliError } from './http.js';
+import { credentialFrom, resolveRequestTarget } from './target.js';
 import { createCliError } from './errors.js';
 import { MAX_PAGE_SIZE } from './pagination.js';
 const LD_APP_NAME = 'ld-app';
@@ -67,11 +66,18 @@ export function ldAllowedHosts(env = process.env) {
     }
     return hosts;
 }
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '[::1]']);
 /**
  * Fail CLOSED unless `url` is safe to receive a bearer token. The message names the host, never the
  * token. Called at resolution AND immediately before the exchange POST (defence in depth).
+ *
+ * D-13: `loopbackAllowed` additionally accepts a local L&D at `http://127.0.0.1|localhost|[::1]:<explicit port>`.
+ * It is true ONLY on the CLI session path AND when the URL came from the person's own explicit override
+ * (`--ld-url` / `NG_LD_API_URL`), never from instance metadata or the cache: `api_base_url` is
+ * instance-admin-writable, so an admin setting it to `http://localhost:<port>` must not make every signed-in
+ * user POST their token to whatever listens there. The hosted server never sets it.
  */
-function assertBearerLdBase(url, env) {
+function assertBearerLdBase(url, env, loopbackAllowed = false) {
     let parsed;
     try {
         parsed = new URL(url);
@@ -79,6 +85,8 @@ function assertBearerLdBase(url, env) {
     catch {
         throw createCliError('VALIDATION', 'LD_HOST_NOT_ALLOWED: the L&D base URL is not a valid URL');
     }
+    if (loopbackAllowed && parsed.protocol === 'http:' && LOOPBACK_HOSTS.has(parsed.hostname) && parsed.port)
+        return;
     if (parsed.protocol !== 'https:') {
         throw createCliError('VALIDATION', `LD_HOST_NOT_ALLOWED: the L&D base URL must be https (got ${parsed.protocol})`);
     }
@@ -227,27 +235,39 @@ async function fetchLdAppMetadata(platform, instanceId) {
  * `app_metadata->>'name' = 'ld-app'` and `instance_id = $2`, `type = 'app'`, not deleted)
  * over a credential the CLI actually holds.
  */
-export async function resolveLdBaseUrl(opts, deps = {}, env = process.env) {
-    const url = await resolveLdBaseUrlUnchecked(opts, deps, env);
-    // Every source (flag, env, instance metadata, fallback, cache) is checked, on every call.
-    if (opts.credential?.kind === 'bearer')
-        assertBearerLdBase(url, env);
-    return url;
+export async function resolveLdBaseUrl(opts, deps = {}, env = process.env, target = resolveRequestTarget(opts, env)) {
+    return (await resolveLdBase(opts, deps, env, target)).url;
+}
+/** The resolved base plus whether a bearer may go to a loopback URL (session path + explicit override only). */
+async function resolveLdBase(opts, deps, env, target) {
+    const { url, fromOverride } = await resolveLdBaseUrlUnchecked(opts, deps, env, target);
+    const loopbackAllowed = target.via === 'session' && fromOverride;
+    // Every source (flag, env, instance metadata, fallback, cache) is checked, on every call. Keyed on the
+    // TARGET, not `opts.credential`: a session's bearer is resolved by the target and never arrives as opts.
+    if (sendsBearer(target))
+        assertBearerLdBase(url, env, loopbackAllowed);
+    return { url, loopbackAllowed };
+}
+/** A bearer leaves this process: the hosted explicit bearer, or a `p login` session (always a bearer). */
+function sendsBearer(target) {
+    if (target.via === 'session')
+        return true;
+    return target.via === 'explicit' && typeof target.source !== 'function' && target.source.kind === 'bearer';
 }
-async function resolveLdBaseUrlUnchecked(opts, deps, env) {
+async function resolveLdBaseUrlUnchecked(opts, deps, env, target) {
     const override = opts.ldUrl?.trim() || env.NG_LD_API_URL?.trim();
     if (override)
-        return trimUrl(override, opts.ldUrl ? '--ld-url' : 'NG_LD_API_URL');
+        return { url: trimUrl(override, opts.ldUrl ? '--ld-url' : 'NG_LD_API_URL'), fromOverride: true };
     if (!opts.instanceId) {
         throw createCliError('VALIDATION', '--instance-id is required to resolve the L&D API URL (or set NG_LD_API_URL)');
     }
-    // `--url` outranks `--org` in resolveBaseUrl (baseUrl.ts), so keying on org alone lets two
-    // different platform hosts collide on one cached L&D URL within a single process.
-    const cacheKey = `${opts.url ?? opts.org ?? 'dev'}:${opts.instanceId}`;
+    // Keyed on the resolved platform origin, so two hosts (an --org, a --url, a session) never share a
+    // cached L&D URL within one process.
+    const cacheKey = `${target.baseUrl}:${opts.instanceId}`;
     const cached = baseUrlCache.get(cacheKey);
     if (cached && cached.expiresAt > Date.now())
-        return cached.url;
-    const platform = deps.platformClient ?? clientFor(opts);
+        return { url: cached.url, fromOverride: false };
+    const platform = deps.platformClient ?? makeClient(target.baseUrl, target.source);
     const metadata = await fetchLdAppMetadata(platform, opts.instanceId);
     if (!metadata) {
         throw createCliError('NOT_FOUND', 'ld-app is not configured in this instance (not installed). Set --ld-url or NG_LD_API_URL.');
@@ -260,7 +280,7 @@ async function resolveLdBaseUrlUnchecked(opts, deps, env) {
         url = trimUrl(apiBaseUrl.trim(), `ld-app config (metadata.api_base_url on instance ${opts.instanceId})`);
     }
     else {
-        const platformOrigin = resolveBaseUrl({ org: opts.org, url: opts.url });
+        const platformOrigin = target.baseUrl;
         if (platformOrigin !== LD_FALLBACK_PLATFORM_ORIGIN) {
             throw createCliError('NOT_FOUND', `ld-app has no api_base_url configured on this instance, and the built-in default only serves ` +
                 `${LD_FALLBACK_PLATFORM_ORIGIN} (this run targets ${platformOrigin}). Set metadata.api_base_url ` +
@@ -269,7 +289,7 @@ async function resolveLdBaseUrlUnchecked(opts, deps, env) {
         url = LD_FALLBACK_BASE_URL;
     }
     baseUrlCache.set(cacheKey, { url, expiresAt: Date.now() + LD_BASE_URL_TTL_MS });
-    return url;
+    return { url, fromOverride: false };
 }
 /** Max cached L&D tokens (one per distinct Pitcher token × L&D base). Oldest-used evicted first. */
 export const LD_TOKEN_CACHE_MAX = 500;
@@ -318,9 +338,9 @@ export function createLdAuthHttp() {
  * useless once that expires, and its own lifetime is env-configurable (`JWT_EXPIRES_IN`), so neither
  * is assumed. A token whose TTL cannot be read, or is already ≤ 0, is used once and not cached.
  */
-export async function exchangeLdToken(ldBase, pitcherToken, deps, env) {
+export async function exchangeLdToken(ldBase, pitcherToken, deps, env, loopbackAllowed = false) {
     // Re-checked at the point the token leaves, independent of how `ldBase` was obtained.
-    assertBearerLdBase(ldBase, env);
+    assertBearerLdBase(ldBase, env, loopbackAllowed);
     const key = `${createHash('sha256').update(pitcherToken).digest('hex')}|${ldBase}`;
     const hit = ldTokenCache.get(key);
     if (hit) {
@@ -367,12 +387,13 @@ export async function exchangeLdToken(ldBase, pitcherToken, deps, env) {
 export async function ldClientFor(opts, deps = {}, env = process.env) {
     if (deps.ldClient)
         return deps.ldClient;
-    const base = await resolveLdBaseUrl(opts, deps, env);
-    const cred = credentialOf(opts);
+    const target = resolveRequestTarget(opts, env);
+    const { url: base, loopbackAllowed } = await resolveLdBase(opts, deps, env, target);
+    const cred = await credentialFrom(target.source);
     if (cred.kind === 'apiKey')
         return makeClient(base, cred);
     // No redirects for a bearer either: the L&D JWT embeds the user's Pitcher token.
-    const ldToken = await exchangeLdToken(base, cred.token, deps, env);
+    const ldToken = await exchangeLdToken(base, cred.token, deps, env, loopbackAllowed);
     return makeClient(base, { kind: 'bearer', token: ldToken }, { maxRedirects: 0 });
 }
 /**

package/dist/src/core/pitcherAuth.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Pitcher login primitives shared by `p login` (this package) and the hosted MCP server (`mcp-server`, which
+ * imports them through the `@pitcher/cli-scripts/auth` export): the org-domain allowlist, org-config discovery,
+ * and the Auth0 authorize URL + token/refresh/revoke grants. No JWT verification here (that needs `jose`,
+ * which stays in mcp-server): the CLI only decodes, every backend verifies.
+ *
+ * Global `fetch`, `URLSearchParams` and `AbortSignal.timeout` only, so the published CLI gains no dependency.
+ */
+/**
+ * The Pitcher domain a user types. Ruling (a): only `<org>.my.pitcher.com`. The allowlist runs BEFORE any
+ * outbound fetch, so the field can never aim a request anywhere else.
+ */
+export declare const DOMAIN_RULING_MESSAGE = "Only <org>.my.pitcher.com addresses are supported for now \u2014 use your Pitcher web address, e.g. acme.my.pitcher.com";
+export type DomainResult = {
+    ok: true;
+    domain: string;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function normalizeDomain(input: unknown): DomainResult;
+/** `acme.my.pitcher.com` → `acme` (only call on a normalized domain). */
+export declare function orgSubdomain(domain: string): string;
+/**
+ * Auth0 Native "Pitcher MCP" app per tenant, keyed by the org-config `auth0.domain` (the CUSTOM domain). Public
+ * client ids (no secret). ⛔ Two sources, on purpose: the hosted server reads its own `AUTH0_CLIENT_IDS` Fly
+ * secret (`mcp-server/src/config.ts`) so a tenant can be enabled there without a CLI release; keep the entries
+ * in step when a tenant is added.
+ */
+export declare const AUTH0_NATIVE_CLIENT_IDS: Readonly<Record<string, string>>;
+export interface OrgConfig {
+    /** The Auth0 CUSTOM domain (`auth0.test-eu.pitcher.com`) — the key into the client-id maps. */
+    auth0Domain: string;
+    audience: string;
+    /** Auth0 organization id (`org_…`). Nullable upstream: null = "no MCP login configured". */
+    organization: string | null;
+    /** `'test' | 'production'`. OPTIONAL upstream: treat unknown as production. */
+    environment?: string;
+}
+export interface Auth0Tokens {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+}
+export interface UpstreamError extends Error {
+    isUpstreamError: true;
+    /** `grant` = Auth0 said invalid_grant (the client must re-auth); `upstream` = anything else. */
+    kind: 'grant' | 'upstream';
+}
+export declare function createUpstreamError(kind: UpstreamError['kind'], message: string): UpstreamError;
+export declare function isUpstreamError(e: unknown): e is UpstreamError;
+export type FetchFn = typeof globalThis.fetch;
+export interface HttpOpts {
+    fetch?: FetchFn;
+    /** Per request; default 5 s. */
+    timeoutMs?: number;
+}
+export declare function issuerFor(auth0Domain: string): string;
+export declare function buildAuthorizeUrl(p: {
+    auth0Domain: string;
+    clientId: string;
+    redirectUri: string;
+    organization: string;
+    audience: string;
+    state: string;
+    codeChallenge: string;
+}): string;
+/** null = the domain is not a Pitcher org (4xx / no auth0 block). Throws an UpstreamError on network/5xx. */
+export declare function fetchOrgConfig(domain: string, opts?: HttpOpts): Promise<OrgConfig | null>;
+export declare function exchangeCode(p: {
+    auth0Domain: string;
+    clientId: string;
+    code: string;
+    verifier: string;
+    redirectUri: string;
+}, opts?: HttpOpts): Promise<Auth0Tokens>;
+export declare function refresh(p: {
+    auth0Domain: string;
+    clientId: string;
+    refreshToken: string;
+}, opts?: HttpOpts): Promise<Auth0Tokens>;
+export declare function revoke(p: {
+    auth0Domain: string;
+    clientId: string;
+    token: string;
+}, opts?: HttpOpts): Promise<void>;

package/dist/src/core/pitcherAuth.js

@@ -0,0 +1,143 @@
+/**
+ * Pitcher login primitives shared by `p login` (this package) and the hosted MCP server (`mcp-server`, which
+ * imports them through the `@pitcher/cli-scripts/auth` export): the org-domain allowlist, org-config discovery,
+ * and the Auth0 authorize URL + token/refresh/revoke grants. No JWT verification here (that needs `jose`,
+ * which stays in mcp-server): the CLI only decodes, every backend verifies.
+ *
+ * Global `fetch`, `URLSearchParams` and `AbortSignal.timeout` only, so the published CLI gains no dependency.
+ */
+/**
+ * The Pitcher domain a user types. Ruling (a): only `<org>.my.pitcher.com`. The allowlist runs BEFORE any
+ * outbound fetch, so the field can never aim a request anywhere else.
+ */
+export const DOMAIN_RULING_MESSAGE = 'Only <org>.my.pitcher.com addresses are supported for now — use your Pitcher web address, e.g. acme.my.pitcher.com';
+const ALLOWED_DOMAIN = /^[a-z0-9-]+\.my\.pitcher\.com$/;
+export function normalizeDomain(input) {
+    if (typeof input !== 'string')
+        return { ok: false, error: DOMAIN_RULING_MESSAGE };
+    let d = input.trim().toLowerCase();
+    d = d.replace(/^https?:\/\//, '');
+    d = d.split(/[/?#]/, 1)[0] ?? '';
+    if (d.endsWith('.'))
+        d = d.slice(0, -1);
+    return ALLOWED_DOMAIN.test(d) ? { ok: true, domain: d } : { ok: false, error: DOMAIN_RULING_MESSAGE };
+}
+/** `acme.my.pitcher.com` → `acme` (only call on a normalized domain). */
+export function orgSubdomain(domain) {
+    return domain.slice(0, domain.indexOf('.'));
+}
+/**
+ * Auth0 Native "Pitcher MCP" app per tenant, keyed by the org-config `auth0.domain` (the CUSTOM domain). Public
+ * client ids (no secret). ⛔ Two sources, on purpose: the hosted server reads its own `AUTH0_CLIENT_IDS` Fly
+ * secret (`mcp-server/src/config.ts`) so a tenant can be enabled there without a CLI release; keep the entries
+ * in step when a tenant is added.
+ */
+export const AUTH0_NATIVE_CLIENT_IDS = {
+    'auth0.test-eu.pitcher.com': 'EvXiukSFA9LmxkoMyGfGrX6tk5eZdJFu',
+    'auth0.eu.pitcher.com': 'cJpAajaha7dWc2mnGy3GZSMBm3kzX370',
+};
+export function createUpstreamError(kind, message) {
+    return Object.assign(new Error(message), { isUpstreamError: true, kind });
+}
+export function isUpstreamError(e) {
+    return e instanceof Error && e.isUpstreamError === true;
+}
+export function issuerFor(auth0Domain) {
+    return `https://${auth0Domain}/`;
+}
+export function buildAuthorizeUrl(p) {
+    const u = new URL(`https://${p.auth0Domain}/authorize`);
+    u.search = new URLSearchParams({
+        response_type: 'code',
+        client_id: p.clientId,
+        redirect_uri: p.redirectUri,
+        organization: p.organization,
+        audience: p.audience,
+        scope: 'openid profile email offline_access',
+        code_challenge: p.codeChallenge,
+        code_challenge_method: 'S256',
+        state: p.state,
+    }).toString();
+    return u.href;
+}
+/** null = the domain is not a Pitcher org (4xx / no auth0 block). Throws an UpstreamError on network/5xx. */
+export async function fetchOrgConfig(domain, opts = {}) {
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    const url = `https://${domain}/core/api/org-config?org_subdomain=${encodeURIComponent(orgSubdomain(domain))}`;
+    let res;
+    try {
+        res = await doFetch(url, {
+            headers: { accept: 'application/json' },
+            // The allowlisted host is the only host we will talk to — never follow it elsewhere.
+            redirect: 'error',
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 5000),
+        });
+    }
+    catch {
+        throw createUpstreamError('upstream', 'org-config unreachable');
+    }
+    if (res.status >= 500)
+        throw createUpstreamError('upstream', `org-config returned ${res.status}`);
+    if (res.status !== 200)
+        return null;
+    const json = await res.json().catch(() => null);
+    const a = json?.auth0;
+    if (!a || typeof a.domain !== 'string' || typeof a.audience !== 'string')
+        return null;
+    return {
+        auth0Domain: a.domain,
+        audience: a.audience,
+        organization: typeof a.organization === 'string' && a.organization ? a.organization : null,
+        environment: typeof json.environment === 'string' ? json.environment : undefined,
+    };
+}
+async function postJson(url, body, opts) {
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    let res;
+    try {
+        res = await doFetch(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json', accept: 'application/json' },
+            body: JSON.stringify(body),
+            // Codes, PKCE verifiers and refresh tokens must never be re-sent to a redirect target.
+            redirect: 'error',
+            signal: AbortSignal.timeout(opts.timeoutMs ?? 5000),
+        });
+    }
+    catch {
+        throw createUpstreamError('upstream', 'Auth0 unreachable');
+    }
+    const json = await res.json().catch(() => ({}));
+    return { status: res.status, json };
+}
+async function tokenGrant(auth0Domain, body, opts) {
+    const { status, json } = await postJson(`https://${auth0Domain}/oauth/token`, body, opts);
+    if (status === 200 && typeof json?.access_token === 'string') {
+        return {
+            access_token: json.access_token,
+            refresh_token: typeof json.refresh_token === 'string' ? json.refresh_token : undefined,
+            expires_in: typeof json.expires_in === 'number' ? json.expires_in : undefined,
+        };
+    }
+    if ((status === 400 || status === 403) && json?.error === 'invalid_grant') {
+        throw createUpstreamError('grant', 'Auth0 rejected the grant');
+    }
+    throw createUpstreamError('upstream', `Auth0 token endpoint returned ${status}`);
+}
+export function exchangeCode(p, opts = {}) {
+    return tokenGrant(p.auth0Domain, {
+        grant_type: 'authorization_code',
+        client_id: p.clientId,
+        code: p.code,
+        code_verifier: p.verifier,
+        redirect_uri: p.redirectUri,
+    }, opts);
+}
+export function refresh(p, opts = {}) {
+    return tokenGrant(p.auth0Domain, { grant_type: 'refresh_token', client_id: p.clientId, refresh_token: p.refreshToken }, opts);
+}
+export async function revoke(p, opts = {}) {
+    const { status } = await postJson(`https://${p.auth0Domain}/oauth/revoke`, { client_id: p.clientId, token: p.token }, opts);
+    if (status !== 200)
+        throw createUpstreamError('upstream', `Auth0 revoke returned ${status}`);
+}

package/dist/src/core/session.d.ts

@@ -0,0 +1,90 @@
+import type { Credential } from './credential.js';
+import { type Auth0Tokens } from './pitcherAuth.js';
+/**
+ * `p login` sessions, ONE PER ORG DOMAIN (OD-3): `${XDG_CONFIG_HOME:-~/.config}/pitcher/sessions/<domain>.json`
+ * (`PITCHER_CONFIG_DIR` replaces `…/pitcher`, for tests). Files are `0600` in `0700` directories, written
+ * atomically (temp file + rename), and refused on read when group/other can access them (ssh's rule).
+ *
+ * Refresh tokens ROTATE with a 30 s reuse window: a second use of the same RT outside it trips Auth0's reuse
+ * detection, which also kills the user's SSO session. So a refresh runs under a per-domain lock AND writes
+ * only if the file still holds the RT it sent (compare-and-write). Correctness rests on the compare-and-write;
+ * the lock only avoids most duplicate refreshes.
+ */
+export interface SessionV1 {
+    version: 1;
+    /** acme.my.pitcher.com, equals the file name */
+    domain: string;
+    /** org-config 'test' | 'production'; OPTIONAL upstream, so unknown means production */
+    environment?: string;
+    /** org-config auth0.domain (the custom domain), the key into AUTH0_NATIVE_CLIENT_IDS */
+    auth0Domain: string;
+    clientId: string;
+    audience: string;
+    /** org_…; every refreshed access token must carry the same org_id */
+    organization: string;
+    sub: string;
+    email?: string;
+    accessToken: string;
+    /** epoch seconds, from the access token's `exp` (not `expires_in`) */
+    accessTokenExpiresAt: number;
+    refreshToken: string;
+    updatedAt: number;
+}
+type Env = NodeJS.ProcessEnv;
+export declare function configRoot(env?: Env): string;
+export declare function sessionsDir(env?: Env): string;
+/** Only call with a normalized domain (the allowlist makes it a safe file name). */
+export declare function sessionPath(domain: string, env?: Env): string;
+/** Sorted. Inclusion match on the file name, so stray files (temp, lock, .DS_Store) are never sessions. */
+export declare function listSessionDomains(env?: Env): string[];
+/** null = no file. AUTH on too-open permissions, bad JSON, an unknown version, or a domain ≠ the file name. */
+export declare function readSession(domain: string, env?: Env): SessionV1 | null;
+/** Atomic replace of ONE domain's session; other domains are untouched. The caller holds the domain lock. */
+export declare function writeSession(domain: string, s: SessionV1, env?: Env): void;
+/** The caller holds the domain lock. */
+export declare function deleteSession(domain: string, env?: Env): void;
+/**
+ * The ONE domain picker every session consumer uses: `--domain` (or `logout`'s positional) → `PITCHER_DOMAIN`
+ * → the single existing session. Never "most recent wins": a silent pick could send a prod write to the
+ * wrong org, so two or more sessions with nothing explicit is a VALIDATION error.
+ */
+export declare function selectDomain(opts: {
+    domain?: string;
+}, env?: Env): string;
+/**
+ * Break a lock that was observed stale with content `observed`, without the unlink race: MOVE it aside
+ * (only one waiter can move a given inode), then compare what was moved. Our stale lock → drop it. Someone
+ * else's fresh lock (created after we looked) → put it back with `link`, which fails harmlessly if an even
+ * newer lock exists. Exported for the tests.
+ */
+export declare function breakStaleLock(lock: string, observed: string, waiterToken: string): void;
+export interface LockOpts {
+    now?: () => number;
+    timeoutMs?: number;
+    staleMs?: number;
+    retryMs?: number;
+}
+/** Serialise `fn` per domain across processes (`<domain>.json.lock`, `wx`). AUTH after 10 s of waiting. */
+export declare function withDomainLock<T>(domain: string, fn: () => Promise<T> | T, env?: Env, opts?: LockOpts): Promise<T>;
+/** Decode (NOT verify) a JWT payload. The CLI is not a security boundary here: every backend verifies. */
+export declare function decodeJwtPayload(token: string): Record<string, unknown> | null;
+export interface SessionCredentialOpts {
+    /** epoch ms */
+    now?: () => number;
+    auth0?: {
+        refresh: (p: {
+            auth0Domain: string;
+            clientId: string;
+            refreshToken: string;
+        }) => Promise<Auth0Tokens>;
+    };
+    env?: Env;
+    lock?: LockOpts;
+}
+/**
+ * The session's bearer, refreshed when it is within 120 s of expiry. A refresh runs under the domain lock:
+ * re-read (another process may have refreshed), refresh, re-check `org_id`, then compare-and-write the
+ * rotated RT BEFORE returning the access token.
+ */
+export declare function sessionCredential(domain: string, opts?: SessionCredentialOpts): Promise<Credential>;
+export {};