@standchat/cli 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,102 @@
-# Temporary Holding Version
+# Stand Chat CLI
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line access for installing and managing Stand Chat. The CLI covers the 109 published API operations, with named commands for common workflows and `stand api` for every published operation. Requires Node.js 22+ on macOS, Linux or WSL; native Windows is unsupported. Hosted/local MCP and WordPress are outside this release.
+
+## Installation and browser handoff
+
+After the release is publicly published:
+
+```sh
+npm install --global @standchat/cli@0.1.1
+stand auth login --setup --json
+stand setup status --json
+```
+
+`auth login` emits a `device_authorization` event on stderr with a trusted verification URL and a separate public user code. Keep the command running while the human opens the URL, signs up or signs in, accepts terms and approves access. Do not ask the human to paste access tokens, cookies or refresh tokens into the conversation. Browser approval never permits the agent to invent identity details or accept terms for the human.
+
+`setup status` performs reads only. If it reports `browser_onboarding_required`, the human must open the indicated dashboard using the same account and complete the existing profile/organization onboarding form. Run `setup status` again afterward. A ready result means configuration may begin; it does not mean that a widget or chat has been verified. Disabled membership and unreadable account data fail closed. For a custom environment, provide its verified dashboard origin with `--app-url`; no dashboard address is guessed from an arbitrary API hostname.
+
+The setup preset requests `openid offline_access` and eight business permissions: `profile:read org:read sites:read sites:write standins:read standins:write knowledge:read knowledge:write`. Broader management permissions are available through explicit `--scopes`. Existing profile edits require `profile:write`; organization renaming additionally requires `org:write`. Initial profile and organization creation remain browser onboarding steps. Normal login defaults to read-only identity, organization and Site access; subsequent login preserves selectable previously granted permissions. Session lifetime follows the identity provider's existing limits. A refresh token is bound to a private proof key and is never printed.
+
+macOS uses Keychain by default. Linux uses the OS secret service when available. On a host without a usable OS keychain, including typical WSL environments, explicitly choose `--credential-store file` during login; there is no silent fallback. File credentials are private to the user and never loaded from the project. Use `stand auth logout` to revoke refresh access and remove local credentials; `--local-only` removes local credentials without revocation when remote access is unavailable.
+
+## Complete installation
+
+Follow the public [agent installation guide](https://stand.chat/guide/ai-setup.md). Inspect schemas before creating configuration:
+
+```sh
+stand commands --json
+stand schema createStandin
+stand sites list --json
+stand standins list --json
+stand knowledge list --json
+stand org plan --json
+stand org usage --json
+```
+
+Inspect existing resources and record their public IDs in your installation notes. Reuse a matching authorized Site where appropriate. Create a Site and a complete, initially disabled Stand-in only when needed. Only existing backend operations are used; this release has no configuration revisions or automatic multi-resource transaction.
+
+```sh
+stand sites create --domain example.com --name 'Example' --yes --json
+stand standins create --body-file standin.json --yes --json
+stand knowledge create --body-file knowledge.json --yes --json
+stand knowledge crawl KNOWLEDGE_BASE_ID --body-file crawl.json --yes --json
+stand knowledge tasks KNOWLEDGE_BASE_ID --json
+stand knowledge documents KNOWLEDGE_BASE_ID --json
+stand standins knowledge get STANDIN_ID --json
+stand standins knowledge set STANDIN_ID --body-file attachments.json --yes --json
+stand standins set-enabled STANDIN_ID --enabled true --yes --json
+stand standins status --json
+```
+
+Use only approved public website content, or approved project content within the existing instruction limits. Free Base-plan installation must work without paid uploads or sitemap features. Do not crawl localhost or private addresses. Check task completion and ingested documents before claiming that knowledge is ready. Attachment writes replace the complete list: read existing attachments and preserve those the user has not authorized removing.
+
+The account-wide switch is separate from each Stand-in's enablement. `stand standins master --enabled true --yes --json` affects existing enabled Stand-ins as well. Inspect them and obtain approval for that shared effect on an existing account. Site and existing Stand-in configuration updates are supported through `stand sites update` and `stand standins update`. Read the current resource and its request schema first: some settings and collections are complete replacements, and concurrent writes have no conditional revision protection.
+
+Install the exact snippet returned by the Site API once, using the website framework's supported mechanism and preserving its consent and Content Security Policy. Never put CLI credentials in the website, browser code or repository. Publish through the project's normal authorized workflow. Open the deployed page on its configured domain, verify the widget, send a real visitor message and confirm a real answer grounded in the approved content. A script load, Site match, mocked response or committed snippet does not establish a working chat. Without deployment access, report the remaining step explicitly.
+
+## Manage an existing account
+
+Follow the [public API and CLI guide](https://stand.chat/guide/api-cli.md). The 19 business scopes cover profile, Sites, organization, sessions, team reads, digests, Stand-ins, knowledge, integrations, analytics and feedback. Each operation declares its required scope in `stand schema OPERATION_ID`. Scope consent never bypasses ownership, active membership or plan limits. Request only permissions needed for the user's approved work:
+
+```sh
+stand auth login --scopes 'profile:read profile:write' --json
+stand schema updateRepProfile --json
+stand api PUT /v1/reps/profile --body-file profile.json --yes --json
+stand sites get SITE_ID --json
+stand sites update SITE_ID --body-file site.json --yes --json
+stand standins update STANDIN_ID --body-file standin.json --yes --json
+```
+
+Account deletion, subscription/payment management, team-member mutations, initial account bootstrap and JavaScript experimentation opt-in are excluded. An owner must enable experimentation in the dashboard before an authorized client can edit scripts. API calls cannot enable either `advancedBehaviorEnabled` or `allowStandAdminBehavior`; a request that tries to enable them fails before other Site changes are saved. Read the current Site and preserve unrelated behavior. Supplying legacy `embedOptions` replaces behavior rules and resets experimentation consent.
+
+Multipart operations accept their documented form fields. Uploads retain existing plan and size limits:
+
+```sh
+stand api POST /v1/knowledge-bases/KNOWLEDGE_BASE_ID/uploads \
+  --form-file file=/absolute/path/approved-document.pdf --yes --json
+stand api GET /v1/knowledge-bases/KNOWLEDGE_BASE_ID/tasks \
+  --query-param view=inspection --query-param limit=20 --json
+```
+
+Explicit knowledge inspection returns bounded metadata pages; follow `nextCursor` as `after` with the same filters. The ordinary knowledge list commands preserve existing full list responses. Inspect completed ingestion and documents before using newly uploaded knowledge.
+
+History export streams JSON to a new private file and validates the entire result before making it available. It never overwrites an existing file:
+
+```sh
+stand history export --scope myself --output /absolute/path/history.json --json
+```
+
+History supports the documented query, date, Site, type, contact and label filters. Export defaults to 600 seconds and 100 MiB; `--timeout SECONDS` and `--max-bytes BYTES` can raise those bounds to at most 3,600 seconds and 1 GiB. The package uses `stream-json` for bounded-memory export validation. Conversations are private data: do not commit export files to a website repository.
+
+## Automation and recovery
+
+Output is JSON when stdout is not a terminal; `--json` makes this explicit. Diagnostics go to stderr. Mutation commands require `--yes` without a terminal. These confirmations do not replace the user's authorization for the requested action. Input JSON uses `--body-file FILE` or `--body-file -`. `stand api METHOD /v1/path` supports only operations in the bundled public OpenAPI; it cannot access unpublished routes or bypass account permissions. `--query-param key=value` adds a query parameter. Tokens are never accepted as command arguments or URL parameters.
+
+GET requests retry a bounded number of transient HTTP failures. Writes never retry automatically. A timeout, lost response, cancellation after dispatch or server failure may leave a completed write: read the relevant list/resource, reconcile with recorded public IDs and approved content, and stop when the result remains uncertain. Do not create another resource merely because its earlier response was lost. Re-running setup must inspect saved progress and the installed snippet before creating or changing anything.
+
+`STAND_CONFIG_HOME` must be an absolute private configuration location. `STAND_PROFILE` selects a saved profile. `STAND_API_URL` and `STAND_ISSUER` override endpoints for one invocation without rewriting saved targets. Credentials are bound to the selected API and issuer. `STAND_ACCESS_TOKEN` supports automation with an existing authorized token and requires `STAND_TOKEN_API_URL` to match its authorized API origin; it is never printed or saved by the CLI. Request timeouts default to 30 seconds and are bounded at 120 seconds. Exits: `0` success, `1` API error, `2` usage, `3` schema not found, `4` authentication/permission, `5` network/invalid response, `130` cancellation.
+
+## Release validation
+
+From the monorepo, run `pnpm --filter @standchat/cli test`. `node cli/scripts/prepare-release.mjs --output /absolute/empty/directory` builds and retains a checksummed npm tarball plus an isolated candidate installer. Candidate installation and synthetic tests do not establish public distribution or production readiness. The release gate requires the exact tarball's public npm integrity, a clean public installation, fresh Codex and Claude Code journeys with real signup and visitor chat, and normal deployment/rollback validation. No publication occurs during build or test.

package/dist/auth.js

@@ -0,0 +1,319 @@
+import { CliError, isObject, usage } from './errors.js';
+import { createHash, randomBytes } from 'node:crypto';
+import { fetchText, issuerEndpoint, safeUrl, sleep } from './transport.js';
+import { DELEGATED_SCOPES } from './contract.js';
+import { assertRefreshBinding, createDpopProof, dpopThumbprint, generateDpopPrivateJwk } from './dpop.js';
+export const DEFAULT_SCOPES = ['openid', 'offline_access', 'profile:read', 'sites:read', 'org:read'];
+export const SETUP_SCOPES = ['openid', 'offline_access', 'profile:read', 'sites:read', 'sites:write', 'standins:read', 'standins:write', 'knowledge:read', 'knowledge:write', 'org:read'];
+export const ALLOWED_SCOPES = ['openid', 'offline_access', ...DELEGATED_SCOPES];
+function jsonObject(text) {
+    try {
+        const value = JSON.parse(text);
+        if (isObject(value))
+            return value;
+    }
+    catch { /* Intentionally do not include the response. */ }
+    throw new CliError('OIDC_RESPONSE', 'The identity provider returned an invalid response.', 4);
+}
+export function requestedScopes(value) {
+    const scopes = value === undefined ? DEFAULT_SCOPES : value.split(/[ ,]+/).filter(Boolean);
+    if (!scopes.length || scopes.some(scope => !ALLOWED_SCOPES.includes(scope)))
+        usage(`Supported scopes: ${ALLOWED_SCOPES.join(' ')}.`);
+    return [...new Set(['openid', 'offline_access', ...scopes])].join(' ');
+}
+/** Re-login reuses selectable permissions, not issuer-added default claims. */
+export async function scopesForLogin(vault, explicit) {
+    if (explicit !== undefined)
+        return requestedScopes(explicit);
+    let previous;
+    try {
+        previous = await vault.load();
+    }
+    catch (error) {
+        // A fresh login can replace malformed credentials after storage preflight.
+        // Locked/unavailable keychains, unsafe files and I/O failures must still stop.
+        if (!(error instanceof CliError) || !['CREDENTIAL_INVALID', 'CONFIG_INVALID'].includes(error.code))
+            throw error;
+    }
+    const selectable = previous?.scopes?.split(/\s+/).filter(scope => ALLOWED_SCOPES.includes(scope));
+    return requestedScopes(selectable?.length ? selectable.join(' ') : undefined);
+}
+export async function discover(profile, signal) {
+    const issuer = safeUrl(profile.issuer, 'issuer').href.replace(/\/$/, '');
+    const { response, text } = await fetchText(`${issuer}/.well-known/openid-configuration`, { signal }, 15_000, 256 * 1024);
+    if (!response.ok)
+        throw new CliError('OIDC_DISCOVERY', 'Could not load discovery for the configured issuer.', 4, response.status);
+    const data = jsonObject(text);
+    if (data.issuer !== issuer)
+        throw new CliError('OIDC_ISSUER_MISMATCH', 'Discovery issuer does not exactly match the configured issuer.', 4);
+    return {
+        issuer,
+        device_authorization_endpoint: issuerEndpoint(issuer, data.device_authorization_endpoint),
+        token_endpoint: issuerEndpoint(issuer, data.token_endpoint),
+        ...(data.revocation_endpoint === undefined ? {} : { revocation_endpoint: issuerEndpoint(issuer, data.revocation_endpoint) }),
+    };
+}
+async function form(endpoint, fields, signal, proof) {
+    const { response, text } = await fetchText(endpoint, {
+        method: 'POST',
+        headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded', ...(proof ? { DPoP: proof } : {}) },
+        body: new URLSearchParams(fields), signal,
+    }, 15_000, 128 * 1024);
+    return { status: response.status, data: text ? jsonObject(text) : {}, nonce: response.headers.get('DPoP-Nonce') };
+}
+// Scope nonce state to one endpoint and one login/refresh/revocation operation.
+// Retry only an explicit RFC 9449 nonce challenge, once, with a fresh proof.
+class DpopRequest {
+    endpoint;
+    key;
+    nonce;
+    constructor(endpoint, key) {
+        this.endpoint = endpoint;
+        this.key = key;
+    }
+    async post(fields, signal) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            const result = await form(this.endpoint, fields, signal, createDpopProof(this.key, this.endpoint, this.nonce));
+            if (result.nonce !== null) {
+                if (!/^[\x21-\x7e]{1,1024}$/.test(result.nonce))
+                    throw new CliError('OIDC_RESPONSE', 'Identity provider returned an invalid DPoP nonce.', 4);
+                this.nonce = result.nonce;
+            }
+            if (result.status !== 400 || result.data.error !== 'use_dpop_nonce')
+                return result;
+            if (!result.nonce || attempt !== 0)
+                throw new CliError('AUTH_DPOP_NONCE', 'Identity provider could not complete the proof challenge. Run stand auth login again.', 4);
+        }
+        throw new CliError('AUTH_DPOP_NONCE', 'Identity provider could not complete the proof challenge.', 4);
+    }
+}
+function tokenResponse(data) {
+    if (typeof data.access_token !== 'string' || !data.access_token || /\s/.test(data.access_token)
+        || typeof data.expires_in !== 'number' || !Number.isFinite(data.expires_in) || data.expires_in <= 0
+        || data.token_type !== 'Bearer'
+        || (data.refresh_token !== undefined && (typeof data.refresh_token !== 'string' || /\s/.test(data.refresh_token)))
+        || (data.scope !== undefined && typeof data.scope !== 'string')) {
+        throw new CliError('OIDC_RESPONSE', 'Identity provider returned an invalid token response.', 4);
+    }
+    return data;
+}
+function credential(profile, token, key, scopes) {
+    if (!token.refresh_token)
+        throw new CliError('AUTH_BINDING_REQUIRED', 'Identity provider did not return a bound refresh token. Run stand auth login again after the issuer supports this client.', 4);
+    assertRefreshBinding(token.refresh_token, key);
+    return {
+        version: 1, apiUrl: profile.apiUrl, issuer: profile.issuer, clientId: 'stand-cli',
+        accessToken: token.access_token, refreshToken: token.refresh_token, dpopPrivateJwk: key,
+        expiresAt: Date.now() + token.expires_in * 1000,
+        scopes: token.scope ?? scopes,
+    };
+}
+export async function deviceLogin(profile, scopes, hooks, signal) {
+    const metadata = await discover(profile, signal);
+    // Keycloak applies the client's S256 policy to device grants as well. The
+    // verifier stays in this process and is never stored or shown to the user.
+    const verifier = randomBytes(32).toString('base64url');
+    const challenge = createHash('sha256').update(verifier).digest('base64url');
+    const started = await form(metadata.device_authorization_endpoint, {
+        client_id: 'stand-cli', scope: scopes, code_challenge_method: 'S256', code_challenge: challenge,
+    }, signal);
+    if (started.status < 200 || started.status >= 300)
+        throw new CliError('DEVICE_AUTH_UNAVAILABLE', 'Device login is unavailable for stand-cli on this issuer. Verify the client has been deployed and approved.', 4, started.status);
+    const data = started.data;
+    if (typeof data.device_code !== 'string' || !data.device_code || typeof data.user_code !== 'string'
+        || !/^[A-Za-z0-9 -]{1,64}$/.test(data.user_code)
+        || typeof data.expires_in !== 'number' || !Number.isFinite(data.expires_in) || data.expires_in <= 0 || data.expires_in > 3600
+        || (data.interval !== undefined && (typeof data.interval !== 'number' || !Number.isFinite(data.interval) || data.interval < 1 || data.interval > 600))) {
+        throw new CliError('OIDC_RESPONSE', 'Identity provider returned invalid device login instructions.', 4);
+    }
+    // Show the plain verification URL and separate code; do not print device_code or token-bearing URLs.
+    const verificationUri = issuerEndpoint(profile.issuer, data.verification_uri);
+    hooks.display({ verificationUri, userCode: data.user_code, expiresIn: data.expires_in });
+    const key = generateDpopPrivateJwk();
+    const tokenRequest = new DpopRequest(metadata.token_endpoint, key);
+    const now = hooks.now ?? Date.now;
+    const wait = hooks.wait ?? sleep;
+    const expires = now() + data.expires_in * 1000;
+    let interval = typeof data.interval === 'number' ? data.interval * 1000 : 5000;
+    while (now() + interval < expires) {
+        await wait(interval, signal);
+        if (signal?.aborted)
+            throw new CliError('CANCELLED', 'Login cancelled.', 130);
+        let result;
+        try {
+            result = await tokenRequest.post({ client_id: 'stand-cli', device_code: data.device_code, code_verifier: verifier, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }, signal);
+        }
+        catch (error) {
+            // Never reduce the provider's interval or accumulated slow_down delay.
+            // The device expiry bounds exponential backoff and prevents further polls.
+            if (error instanceof CliError && error.code === 'TIMEOUT') {
+                interval *= 2;
+                continue;
+            }
+            throw error;
+        }
+        if (result.status >= 200 && result.status < 300)
+            return credential(profile, tokenResponse(result.data), key, scopes);
+        switch (result.data.error) {
+            case 'authorization_pending': break;
+            case 'slow_down':
+                interval += 5000;
+                break;
+            case 'access_denied': throw new CliError('AUTH_DENIED', 'Device login was denied.', 4);
+            case 'expired_token': throw new CliError('AUTH_EXPIRED', 'Device login expired. Run stand auth login again.', 4);
+            default: throw new CliError('AUTH_FAILED', 'Device login failed. Verify the client and requested scopes with the operator.', 4, result.status);
+        }
+    }
+    throw new CliError('AUTH_EXPIRED', 'Device login expired. Run stand auth login again.', 4);
+}
+export function checkCancelled(signal) {
+    if (signal?.aborted)
+        throw new CliError('CANCELLED', 'Operation cancelled. No further request was sent.', 130);
+}
+export function combineSignals(...signals) {
+    const present = signals.filter((signal) => signal !== undefined);
+    // Node>=22 supports the public API; the pinned TS DOM declaration predates it.
+    return present.length ? AbortSignal.any(present) : undefined;
+}
+function selectableBusinessScopes(value) {
+    if (typeof value !== 'string' || value.length > 8192)
+        throw new CliError('CREDENTIAL_INVALID', 'The CLI permission metadata is invalid.', 4);
+    return [...new Set(value.split(/\s+/).filter(scope => scope.includes(':') && ALLOWED_SCOPES.includes(scope)))];
+}
+function accessClaims(token, issuer) {
+    // DENY-ONLY compatibility/switch guard. The API, not this decoded payload,
+    // verifies the signature and grants authorization for the selected token.
+    try {
+        const parts = token.split('.');
+        if (token.length > 16384 || parts.length !== 3 || parts.some(part => !/^[A-Za-z0-9_-]+$/.test(part)))
+            throw Error();
+        const claims = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        if (!isObject(claims) || typeof claims.sub !== 'string' || !claims.sub.trim() || claims.sub.length > 255
+            || claims.iss !== issuer || claims.azp !== 'stand-cli' || claims.typ !== 'Bearer'
+            || !(claims.aud === 'stand-api' || (Array.isArray(claims.aud) && claims.aud.includes('stand-api')))
+            || typeof claims.exp !== 'number' || !Number.isFinite(claims.exp) || typeof claims.scope !== 'string')
+            throw Error();
+        return { sub: claims.sub, exp: claims.exp, scope: claims.scope };
+    }
+    catch {
+        throw new CliError('CREDENTIAL_INVALID', 'The saved CLI access token cannot be used by local MCP. Sign in outside MCP.', 4);
+    }
+}
+export class AuthSession {
+    profile;
+    vault;
+    env;
+    signal;
+    constructor(profile, vault, env = process.env, signal) {
+        this.profile = profile;
+        this.vault = vault;
+        this.env = env;
+        this.signal = signal;
+    }
+    environmentToken() {
+        const token = this.env.STAND_ACCESS_TOKEN;
+        if (token === undefined)
+            return undefined;
+        if (!token || /\s/.test(token))
+            throw new CliError('CREDENTIAL_INVALID', 'STAND_ACCESS_TOKEN must contain a nonempty token without whitespace.', 4);
+        if (!this.env.STAND_TOKEN_API_URL || safeUrl(this.env.STAND_TOKEN_API_URL).origin !== this.profile.apiUrl) {
+            throw new CliError('TOKEN_ORIGIN_REQUIRED', 'Set STAND_TOKEN_API_URL to the exact API origin authorized for STAND_ACCESS_TOKEN. It must match the selected profile.', 4);
+        }
+        return token;
+    }
+    async accessToken(signal = this.signal) {
+        const provided = this.environmentToken();
+        if (provided)
+            return provided;
+        return (await this.savedCredential(signal)).accessToken;
+    }
+    // The normal CLI still supports keychains/access-only credentials. This new
+    // local-MCP boundary deliberately requires a saved proof-bound FILE session.
+    async boundCredential(signal, expected) {
+        if (this.env.STAND_ACCESS_TOKEN !== undefined || this.profile.credentialStore !== 'file' || process.platform === 'win32') {
+            throw new CliError('MCP_FILE_LOGIN_REQUIRED', 'Local MCP requires an explicit file-store CLI login on a trusted POSIX machine. Sign in outside MCP with the intended scopes, the same --profile, and --credential-store file.', 4);
+        }
+        const combined = combineSignals(this.signal, signal);
+        const guard = (saved) => {
+            if (!saved.refreshToken || !saved.dpopPrivateJwk || !Number.isFinite(saved.expiresAt))
+                throw new CliError('AUTH_BINDING_REQUIRED', 'A saved proof-bound CLI login is required. Sign in outside MCP.', 4);
+            assertRefreshBinding(saved.refreshToken, saved.dpopPrivateJwk);
+            const claims = accessClaims(saved.accessToken, this.profile.issuer);
+            if (expected && (expected.keyThumbprint !== dpopThumbprint(saved.dpopPrivateJwk) || expected.subject !== claims.sub)) {
+                throw new CliError('MCP_SESSION_CHANGED', 'The saved CLI identity or login changed. Stop this MCP server and reconnect explicitly.', 4);
+            }
+        };
+        const saved = await this.savedCredential(combined, guard);
+        checkCancelled(combined);
+        const claims = accessClaims(saved.accessToken, this.profile.issuer);
+        if (claims.exp * 1000 <= Date.now())
+            throw new CliError('AUTH_EXPIRED', 'The CLI access token has expired. Sign in outside MCP.', 4);
+        const granted = selectableBusinessScopes(saved.scopes);
+        const actual = selectableBusinessScopes(claims.scope);
+        return { accessToken: saved.accessToken, subject: claims.sub, keyThumbprint: dpopThumbprint(saved.dpopPrivateJwk),
+            scopes: actual.filter(scope => granted.includes(scope)) };
+    }
+    async savedCredential(signal, guard) {
+        checkCancelled(signal);
+        return this.vault.locked(async () => {
+            checkCancelled(signal);
+            const saved = await this.vault.load();
+            checkCancelled(signal);
+            if (!saved)
+                throw new CliError('AUTH_REQUIRED', 'No credential exists for this profile and API. Run stand auth login.', 4);
+            if (saved.refreshToken && !saved.dpopPrivateJwk)
+                throw new CliError('AUTH_BINDING_REQUIRED', 'This session predates refresh-token binding. Run stand auth login again. No unbound refresh was attempted.', 4);
+            if (saved.refreshToken && saved.dpopPrivateJwk)
+                assertRefreshBinding(saved.refreshToken, saved.dpopPrivateJwk);
+            guard?.(saved);
+            const expiry = guard ? Math.min(saved.expiresAt, accessClaims(saved.accessToken, this.profile.issuer).exp * 1000) : saved.expiresAt;
+            if (expiry === undefined || expiry > Date.now() + 30_000)
+                return saved;
+            if (!saved.refreshToken)
+                throw new CliError('AUTH_EXPIRED', 'The stored token has expired. Run stand auth login.', 4);
+            const metadata = await discover(this.profile, signal);
+            const result = await new DpopRequest(metadata.token_endpoint, saved.dpopPrivateJwk).post({ client_id: 'stand-cli', grant_type: 'refresh_token', refresh_token: saved.refreshToken }, signal);
+            if (result.status < 200 || result.status >= 300)
+                throw new CliError('AUTH_EXPIRED', 'The session cannot be refreshed. Run stand auth login. Existing access was not retried.', 4, result.status);
+            const response = tokenResponse(result.data);
+            response.refresh_token ??= saved.refreshToken;
+            const refreshed = credential(this.profile, response, saved.dpopPrivateJwk, saved.scopes);
+            guard?.(refreshed);
+            // Once a rotated token was received, finish its atomic save even if the
+            // caller cancelled. Keep the lock until save completes, then deny dispatch.
+            await this.vault.save(refreshed);
+            checkCancelled(signal);
+            return refreshed;
+        }, signal);
+    }
+    async loginHint(requiredScope) {
+        const saved = this.environmentToken() ? undefined : await this.vault.load();
+        const scopes = [...new Set([...(saved?.scopes?.split(/\s+/).filter(scope => ALLOWED_SCOPES.includes(scope)) ?? DEFAULT_SCOPES),
+                ...(requiredScope && ALLOWED_SCOPES.includes(requiredScope) ? [requiredScope] : [])])];
+        return `Run stand auth login --profile ${this.vault.profileName} --scopes '${scopes.join(' ')}'.`;
+    }
+    async logout(localOnly = false) {
+        let revoked = false;
+        // Each saved endpoint/store has a non-secret recovery record. Configuration
+        // edits and temporary URL overrides must not strand older live credentials.
+        for (const vault of await this.vault.locations()) {
+            await vault.locked(async () => {
+                const saved = localOnly ? undefined : await vault.load();
+                if (saved?.refreshToken && !localOnly) {
+                    const metadata = await discover(vault.target, this.signal);
+                    if (!metadata.revocation_endpoint)
+                        throw new CliError('REVOCATION_UNAVAILABLE', 'Issuer has no revocation endpoint. Use --local-only to explicitly remove only local credentials.', 4);
+                    if (!saved.dpopPrivateJwk)
+                        throw new CliError('AUTH_BINDING_REQUIRED', 'This session predates refresh-token binding. Use --local-only to remove only local credentials.', 4);
+                    assertRefreshBinding(saved.refreshToken, saved.dpopPrivateJwk);
+                    const result = await new DpopRequest(metadata.revocation_endpoint, saved.dpopPrivateJwk).post({ client_id: 'stand-cli', token: saved.refreshToken, token_type_hint: 'refresh_token' }, this.signal);
+                    if (result.status < 200 || result.status >= 300)
+                        throw new CliError('REVOCATION_FAILED', 'Token revocation failed. Retry, or use --local-only to explicitly remove only local credentials.', 4, result.status);
+                    revoked = true;
+                }
+                await vault.delete();
+            }, this.signal);
+        }
+        return { localCredentialRemoved: true, refreshTokenRevoked: revoked };
+    }
+}