@standchat/cli 0.0.0-stage → 0.1.1

package/dist/config.js

@@ -0,0 +1,444 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { lstat, mkdir, open, readdir, rename, rm } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { isAbsolute, join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { CliError, isObject, usage } from './errors.js';
+import { safeUrl, sleep } from './transport.js';
+import { validateDpopPrivateJwk } from './dpop.js';
+const DEFAULT_PROFILE = { apiUrl: 'https://api.stand.chat', issuer: 'https://auth.stand.chat/realms/stand' };
+export function configHome(env = process.env) {
+    const root = env.STAND_CONFIG_HOME ?? join(env.XDG_CONFIG_HOME ?? join(homedir(), '.config'), 'stand');
+    if (!isAbsolute(root))
+        usage('STAND_CONFIG_HOME and XDG_CONFIG_HOME must be absolute paths. Project configuration is never loaded.');
+    return root;
+}
+export function profileName(value) {
+    if (!/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(value))
+        usage('Profile names use 1–64 letters, numbers, underscores, or hyphens.');
+    return value;
+}
+async function assertPrivate(path, directory) {
+    const stat = await lstat(path);
+    if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile())) {
+        throw new CliError('UNSAFE_CONFIG', 'Configuration and credential paths must be regular files/directories, not symbolic links.', 4);
+    }
+    if (process.platform !== 'win32' && ((stat.mode & 0o077) !== 0 || (process.getuid && stat.uid !== process.getuid()))) {
+        throw new CliError('UNSAFE_CONFIG', 'Configuration/credential storage is not private to your user. Use mode 700 for its directory and 600 for files.', 4);
+    }
+}
+export async function privateDirectory(path) {
+    await mkdir(path, { recursive: true, mode: 0o700 });
+    await assertPrivate(path, true);
+}
+export async function readPrivateJson(path) {
+    try {
+        await assertPrivate(path, false);
+        const file = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+        try {
+            const stat = await file.stat();
+            if (!stat.isFile() || stat.size > 128 * 1024 || (process.platform !== 'win32' && (stat.mode & 0o077) !== 0)) {
+                throw new CliError('UNSAFE_CONFIG', 'Invalid credential/config file type, size, or permissions.', 4);
+            }
+            try {
+                return JSON.parse(await file.readFile('utf8'));
+            }
+            catch {
+                throw new CliError('CONFIG_INVALID', 'Configuration or credential file is invalid JSON.', 4);
+            }
+        }
+        finally {
+            await file.close();
+        }
+    }
+    catch (error) {
+        if (isObject(error) && error.code === 'ENOENT')
+            return undefined;
+        throw error;
+    }
+}
+export async function writePrivateJson(path, data) {
+    try {
+        await assertPrivate(path, false);
+    }
+    catch (error) {
+        if (!isObject(error) || error.code !== 'ENOENT')
+            throw error;
+    }
+    const temporary = `${path}.${randomUUID()}.tmp`;
+    try {
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(`${JSON.stringify(data, null, 2)}\n`);
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, path);
+    }
+    finally {
+        await rm(temporary, { force: true });
+    }
+}
+async function withPrivateFileLock(root, path, resource, fn, signal) {
+    const busyCode = resource === 'credential' ? 'CREDENTIAL_BUSY' : 'CONFIG_BUSY';
+    const title = resource === 'credential' ? 'Credential' : 'Configuration';
+    const cancelled = () => { if (signal?.aborted)
+        throw new CliError('CANCELLED', 'Operation cancelled.', 130); };
+    cancelled();
+    await privateDirectory(root);
+    const queue = `${path}.queue`;
+    await privateDirectory(queue);
+    const id = `${process.pid}-${randomUUID()}.json`;
+    const claim = join(queue, id);
+    const deadline = performance.now() + 120_000;
+    const wait = async () => {
+        cancelled();
+        if (performance.now() >= deadline)
+            throw new CliError(busyCode, `Another command owns this ${resource}, or its ownership cannot be verified. Retry after it finishes. Queue: ${queue}. Repair this directory only after verifying no Stand CLI process is running; never remove a live process’s lock.`, 4);
+        await sleep(50, signal);
+    };
+    const dead = (pid) => {
+        try {
+            process.kill(pid, 0);
+            return false;
+        }
+        catch (error) {
+            return isObject(error) && error.code === 'ESRCH';
+        }
+    };
+    const claims = async () => {
+        const active = [];
+        for (const name of await readdir(queue)) {
+            if (!/^\d+-[0-9a-f-]{36}\.json$/.test(name))
+                continue;
+            const file = join(queue, name);
+            const value = await readPrivateJson(file);
+            if (value === undefined)
+                continue;
+            if (!isObject(value) || !Number.isSafeInteger(value.pid) || Number(value.pid) <= 0
+                || name.split('-')[0] !== String(value.pid) || !Number.isSafeInteger(value.ticket) || Number(value.ticket) < 0) {
+                throw new CliError(busyCode, `${title} lock ownership is invalid. Queue: ${queue}. Verify no Stand CLI process is running before repairing these files.`, 4);
+            }
+            if (dead(Number(value.pid))) {
+                // Names are unique and never reused. A competing cleanup cannot delete
+                // another process's replacement claim as it could with a fixed lock path.
+                await rm(file, { force: true });
+            }
+            else
+                active.push({ id: name, ticket: Number(value.ticket) });
+        }
+        return active;
+    };
+    // Each attempt owns a unique claim for its whole lifetime, so stale cleanup
+    // never unlinks a new owner's claim. Publish choosing=0 atomically before
+    // inspecting peers; arrivals then observe us or wait for our ticket. The
+    // bakery queue is the only lock: there is no reusable PID-file pathname.
+    try {
+        await writePrivateJson(claim, { pid: process.pid, ticket: 0 });
+        const ticket = Math.max(0, ...(await claims()).map(peer => peer.ticket)) + 1;
+        if (!Number.isSafeInteger(ticket))
+            throw new CliError(busyCode, `${title} lock ticket limit reached.`, 4);
+        await writePrivateJson(claim, { pid: process.pid, ticket });
+        while ((await claims()).some(peer => peer.id !== id
+            && (peer.ticket === 0 || peer.ticket < ticket || (peer.ticket === ticket && peer.id < id))))
+            await wait();
+        cancelled();
+        return await fn();
+    }
+    finally {
+        await rm(claim, { force: true });
+    }
+}
+export class ConfigStore {
+    root;
+    constructor(root = configHome()) {
+        this.root = root;
+        if (!isAbsolute(root))
+            usage('Configuration directory must be absolute. Project-local configuration is never loaded.');
+    }
+    async read() {
+        // No directory creation for read-only commands. Still reject unsafe existing roots.
+        try {
+            await assertPrivate(this.root, true);
+        }
+        catch (error) {
+            if (isObject(error) && error.code === 'ENOENT')
+                return { version: 1, profiles: {} };
+            throw error;
+        }
+        const data = await readPrivateJson(join(this.root, 'config.json'));
+        if (data === undefined)
+            return { version: 1, profiles: {} };
+        if (!isObject(data) || data.version !== 1 || !isObject(data.profiles))
+            throw new CliError('CONFIG_INVALID', 'Unsupported configuration format.', 2);
+        const profiles = Object.create(null);
+        for (const [name, raw] of Object.entries(data.profiles)) {
+            if (!isObject(raw) || typeof raw.apiUrl !== 'string' || typeof raw.issuer !== 'string')
+                throw new CliError('CONFIG_INVALID', 'Invalid profile.', 2);
+            if (raw.credentialStore !== undefined && raw.credentialStore !== 'keychain' && raw.credentialStore !== 'file')
+                throw new CliError('CONFIG_INVALID', 'Invalid credential store.', 2);
+            profiles[profileName(name)] = {
+                apiUrl: safeUrl(raw.apiUrl).origin,
+                issuer: safeUrl(raw.issuer, 'issuer').href.replace(/\/$/, ''),
+                credentialStore: raw.credentialStore,
+            };
+        }
+        return { version: 1, profiles };
+    }
+    async profile(name, env = process.env) {
+        const config = await this.read();
+        const saved = config.profiles[profileName(name)] ?? (name === 'default' ? DEFAULT_PROFILE : undefined);
+        if (!saved)
+            throw new CliError('PROFILE_NOT_FOUND', 'Profile does not exist. Run stand config set --profile NAME --api-url URL --issuer URL.', 2);
+        return {
+            ...saved,
+            apiUrl: safeUrl(env.STAND_API_URL ?? saved.apiUrl).origin,
+            issuer: safeUrl(env.STAND_ISSUER ?? saved.issuer, 'issuer').href.replace(/\/$/, ''),
+        };
+    }
+    // Every mutation of the shared file must derive its result after acquiring
+    // this global lock. A per-profile lock cannot protect the other profile rows.
+    async update(name, change, signal) {
+        const selected = profileName(name);
+        return withPrivateFileLock(this.root, join(this.root, 'config.json.lock'), 'configuration', async () => {
+            const config = await this.read();
+            const profile = change(config.profiles[selected]);
+            config.profiles[selected] = profile;
+            await writePrivateJson(join(this.root, 'config.json'), config);
+            return profile;
+        }, signal);
+    }
+    async save(name, profile, signal) {
+        await this.update(name, () => profile, signal);
+    }
+}
+const run = (command, args, input) => new Promise(resolve => {
+    const child = spawn(command, args, { stdio: ['pipe', 'pipe', 'pipe'] });
+    let output = '';
+    let diagnostic = '';
+    const timeout = setTimeout(() => child.kill(), 30_000);
+    child.stdout.on('data', chunk => { output += String(chunk); if (output.length > 128 * 1024)
+        child.kill(); });
+    child.stderr.on('data', chunk => { diagnostic += String(chunk); if (diagnostic.length > 128 * 1024)
+        child.kill(); });
+    child.on('error', () => { clearTimeout(timeout); resolve({ code: -1, stdout: '', stderr: 'Credential-store command unavailable' }); });
+    child.on('close', code => { clearTimeout(timeout); resolve({ code: code ?? -1, stdout: output, stderr: diagnostic }); });
+    child.stdin.on('error', () => { });
+    child.stdin.end(input);
+});
+export function keychainCommandQuote(value) {
+    if (/[\x00-\x1f\x7f]/.test(value))
+        throw new CliError('CREDENTIAL_INVALID', 'Credential contains unsupported control characters.', 4);
+    return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+}
+export class CredentialVault {
+    root;
+    name;
+    profile;
+    runner;
+    platform;
+    trackLocation;
+    key;
+    constructor(root, name, profile, runner = run, platform = process.platform, trackLocation = true) {
+        this.root = root;
+        this.name = name;
+        this.profile = profile;
+        this.runner = runner;
+        this.platform = platform;
+        this.trackLocation = trackLocation;
+        this.key = createHash('sha256').update(JSON.stringify([name, profile.apiUrl, profile.issuer, 'stand-cli'])).digest('hex');
+    }
+    async store() {
+        if (this.profile.credentialStore === 'file') {
+            if (this.platform === 'win32')
+                throw new CliError('CREDENTIAL_STORE_UNAVAILABLE', 'File credentials require POSIX permissions. On Windows, use the CLI inside WSL with a supported Linux credential store.', 4);
+            return 'file';
+        }
+        if (this.platform === 'darwin')
+            return 'keychain';
+        if (this.platform === 'linux')
+            return 'keychain';
+        throw new CliError('CREDENTIAL_STORE_UNAVAILABLE', 'No supported OS keychain is available. Explicitly select --credential-store file on a trusted POSIX machine, or use the CLI inside WSL with a supported Linux credential store.', 4);
+    }
+    validate(value) {
+        if (!isObject(value) || value.version !== 1 || value.apiUrl !== this.profile.apiUrl || value.issuer !== this.profile.issuer
+            || value.clientId !== 'stand-cli' || typeof value.accessToken !== 'string' || !value.accessToken || /\s/.test(value.accessToken)
+            || (value.refreshToken !== undefined && typeof value.refreshToken !== 'string')
+            || (value.expiresAt !== undefined && (typeof value.expiresAt !== 'number' || !Number.isFinite(value.expiresAt)))
+            || (value.scopes !== undefined && typeof value.scopes !== 'string')) {
+            throw new CliError('CREDENTIAL_INVALID', 'Stored credential does not match the selected API, issuer, and client.', 4);
+        }
+        if (value.dpopPrivateJwk !== undefined)
+            validateDpopPrivateJwk(value.dpopPrivateJwk);
+        return value;
+    }
+    locationDirectory() {
+        return join(this.root, 'credential-locations', createHash('sha256').update(this.name).digest('hex'));
+    }
+    async locationPath() {
+        return join(this.locationDirectory(), `${this.key}-${await this.store()}.json`);
+    }
+    async rememberLocation() {
+        if (!this.trackLocation)
+            return;
+        await privateDirectory(this.root);
+        await privateDirectory(join(this.root, 'credential-locations'));
+        await privateDirectory(this.locationDirectory());
+        // Persist the non-secret recovery address before the secret, so interruption
+        // cannot orphan a credential after switching endpoint or storage backend.
+        await writePrivateJson(await this.locationPath(), { version: 1, apiUrl: this.profile.apiUrl,
+            issuer: this.profile.issuer, credentialStore: await this.store() });
+    }
+    async locations() {
+        const directory = this.locationDirectory();
+        try {
+            await assertPrivate(directory, true);
+        }
+        catch (error) {
+            if (isObject(error) && error.code === 'ENOENT')
+                return [this];
+            throw error;
+        }
+        const entries = await readdir(directory);
+        if (entries.length > 128)
+            throw new CliError('CONFIG_INVALID', 'Too many saved credential locations for this profile.', 4);
+        const vaults = [];
+        for (const entry of entries) {
+            if (!/^[a-f0-9]{64}-(?:file|keychain)\.json$/.test(entry))
+                continue;
+            const value = await readPrivateJson(join(directory, entry));
+            if (value === undefined)
+                continue;
+            if (!isObject(value) || value.version !== 1 || typeof value.apiUrl !== 'string' || typeof value.issuer !== 'string'
+                || !['file', 'keychain'].includes(String(value.credentialStore))) {
+                throw new CliError('CONFIG_INVALID', 'Invalid saved credential location.', 4);
+            }
+            const profile = { apiUrl: safeUrl(value.apiUrl).origin,
+                issuer: safeUrl(value.issuer, 'issuer').href.replace(/\/$/, ''), credentialStore: value.credentialStore };
+            const vault = new CredentialVault(this.root, this.name, profile, this.runner, this.platform);
+            if (join(directory, entry) !== await vault.locationPath())
+                throw new CliError('CONFIG_INVALID', 'Credential location does not match its identifier.', 4);
+            vaults.push(vault);
+        }
+        // The selected target may predate location tracking while another target
+        // was recorded later. Always include it, without visiting the same store twice.
+        const selectedPath = await this.locationPath();
+        if (!(await Promise.all(vaults.map(vault => vault.locationPath()))).includes(selectedPath))
+            vaults.push(this);
+        return vaults;
+    }
+    get profileName() { return this.name; }
+    get target() { return { ...this.profile }; }
+    /** Exercise read/write/delete before requesting browser consent; never overwrite a saved credential. */
+    async preflight() {
+        const probe = new CredentialVault(this.root, `${this.name}-probe-${randomUUID()}`, this.profile, this.runner, this.platform, false);
+        const marker = `storage-probe-${randomUUID()}`;
+        try {
+            await probe.save({ version: 1, apiUrl: this.profile.apiUrl, issuer: this.profile.issuer, clientId: 'stand-cli', accessToken: marker });
+            if ((await probe.load())?.accessToken !== marker)
+                throw new CliError('CREDENTIAL_STORE_UNAVAILABLE', 'Credential storage failed its read-back check. No browser authorization was requested.', 4);
+        }
+        finally {
+            await probe.delete();
+        }
+    }
+    async loadRaw() {
+        const store = await this.store();
+        if (store === 'file') {
+            const dir = join(this.root, 'credentials');
+            try {
+                await assertPrivate(dir, true);
+            }
+            catch (error) {
+                if (isObject(error) && error.code === 'ENOENT')
+                    return undefined;
+                throw error;
+            }
+            const raw = await readPrivateJson(join(dir, `${this.key}.json`));
+            return raw;
+        }
+        const result = this.platform === 'darwin'
+            ? await this.runner('/usr/bin/security', ['find-generic-password', '-s', 'chat.stand.cli', '-a', this.key, '-w'])
+            : await this.runner('secret-tool', ['lookup', 'service', 'chat.stand.cli', 'account', this.key]);
+        if (result.code !== 0) {
+            // macOS errSecItemNotFound (44); secret-tool uses 1 for no matching item.
+            if (result.code === (this.platform === 'darwin' ? 44 : 1)
+                && (this.platform === 'darwin' || !result.stderr?.trim()))
+                return undefined;
+            throw new CliError('CREDENTIAL_STORE_UNAVAILABLE', 'Cannot read the OS keychain. Unlock it and retry.', 4);
+        }
+        // Keep deletion verification independent of credential parsing: malformed
+        // entries must still be removable with --local-only.
+        return result.stdout;
+    }
+    async load() {
+        const raw = await this.loadRaw();
+        if (raw === undefined)
+            return undefined;
+        if (typeof raw !== 'string')
+            return this.validate(raw);
+        try {
+            return this.validate(JSON.parse(raw));
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            throw new CliError('CREDENTIAL_INVALID', 'Keychain credential is invalid.', 4);
+        }
+    }
+    async save(credential) {
+        this.validate(credential);
+        const store = await this.store();
+        if (store === 'file') {
+            await privateDirectory(this.root);
+            const dir = join(this.root, 'credentials');
+            await privateDirectory(dir);
+            await this.rememberLocation();
+            await writePrivateJson(join(dir, `${this.key}.json`), credential);
+            return;
+        }
+        const json = JSON.stringify(credential);
+        // Secrets go through stdin, never process arguments or a shell.
+        const command = this.platform === 'darwin'
+            ? `add-generic-password -U -s chat.stand.cli -a ${this.key} -w ${keychainCommandQuote(json)}\n` : undefined;
+        // security -i uses a 4096-byte line buffer. Never let a truncated line
+        // overwrite the prior entry or interpret its remainder as another command.
+        if (command && Buffer.byteLength(command, 'utf8') > 4095) {
+            throw new CliError('CREDENTIAL_TOO_LARGE', 'This credential exceeds the macOS keychain input limit. The existing entry was not changed. Select --credential-store file on a trusted POSIX machine and sign in again.', 4);
+        }
+        await this.rememberLocation();
+        const result = this.platform === 'darwin'
+            ? await this.runner('/usr/bin/security', ['-i'], command)
+            : await this.runner('secret-tool', ['store', '--label=Stand Chat CLI', 'service', 'chat.stand.cli', 'account', this.key], json);
+        if (result.code !== 0)
+            throw new CliError('CREDENTIAL_STORE_UNAVAILABLE', 'Could not save the credential in the OS keychain. No file fallback was used.', 4);
+        const stored = await this.load();
+        if (stored?.accessToken !== credential.accessToken || stored?.refreshToken !== credential.refreshToken
+            || JSON.stringify(stored?.dpopPrivateJwk) !== JSON.stringify(credential.dpopPrivateJwk)) {
+            throw new CliError('CREDENTIAL_STORE_UNAVAILABLE', 'Could not verify the credential saved in the OS keychain. No file fallback was used.', 4);
+        }
+    }
+    async delete() {
+        if (await this.store() === 'file') {
+            await rm(join(this.root, 'credentials', `${this.key}.json`), { force: true });
+        }
+        else {
+            const result = this.platform === 'darwin'
+                ? await this.runner('/usr/bin/security', ['delete-generic-password', '-s', 'chat.stand.cli', '-a', this.key])
+                : await this.runner('secret-tool', ['clear', 'service', 'chat.stand.cli', 'account', this.key]);
+            if ((result.code !== 0 && result.code !== (this.platform === 'darwin' ? 44 : 1))
+                || (this.platform === 'linux' && Boolean(result.stderr?.trim())))
+                throw new CliError('CREDENTIAL_STORE_UNAVAILABLE', 'Could not remove the credential from the OS keychain. Unlock it and retry.', 4);
+        }
+        if (await this.loadRaw() !== undefined)
+            throw new CliError('CREDENTIAL_STORE_UNAVAILABLE', 'Credential removal could not be verified. The saved credential may still exist.', 4);
+        if (this.trackLocation)
+            await rm(await this.locationPath(), { force: true });
+    }
+    async locked(fn, signal) {
+        return withPrivateFileLock(this.root, join(this.root, `credential-${this.key}.lock`), 'credential', fn, signal);
+    }
+}

package/dist/contract.js

@@ -0,0 +1,37 @@
+import { readFileSync } from 'node:fs';
+import { isObject } from './errors.js';
+export const BUNDLED_SCHEMA = JSON.parse(readFileSync(new URL('./openapi.json', import.meta.url), 'utf8'));
+export const DELEGATED_SCOPES = (() => {
+    const paths = isObject(BUNDLED_SCHEMA) && isObject(BUNDLED_SCHEMA.paths) ? BUNDLED_SCHEMA.paths : {};
+    const scopes = new Set();
+    for (const item of Object.values(paths)) {
+        if (!isObject(item))
+            continue;
+        for (const operation of Object.values(item)) {
+            if (isObject(operation) && typeof operation['x-required-scope'] === 'string') {
+                scopes.add(operation['x-required-scope']);
+            }
+        }
+    }
+    return [...scopes].sort();
+})();
+/** Inspect the bundled public operation without trusting a server error body. */
+export function publicOperation(path, method) {
+    const paths = isObject(BUNDLED_SCHEMA) && isObject(BUNDLED_SCHEMA.paths) ? BUNDLED_SCHEMA.paths : {};
+    const segments = path.split('?')[0].split('/');
+    for (const [pattern, item] of Object.entries(paths)) {
+        if (!isObject(item))
+            continue;
+        const parts = pattern.split('/');
+        if (parts.length !== segments.length || !parts.every((part, index) => /^\{[^}]+\}$/.test(part) || part === segments[index]))
+            continue;
+        const operation = item[method.toLowerCase()];
+        if (isObject(operation))
+            return operation;
+    }
+    return undefined;
+}
+export function operationScope(path, method) {
+    const operation = publicOperation(path, method);
+    return typeof operation?.['x-required-scope'] === 'string' ? operation['x-required-scope'] : undefined;
+}

package/dist/dpop.js

@@ -0,0 +1,63 @@
+import { createECDH, createHash, createPrivateKey, generateKeyPairSync, randomUUID, sign } from 'node:crypto';
+import { CliError, isObject } from './errors.js';
+function bindingRequired() {
+    throw new CliError('AUTH_BINDING_REQUIRED', 'The saved session or issuer does not support the required refresh-token binding. Run stand auth login again. No unbound refresh was attempted.', 4);
+}
+export function validateDpopPrivateJwk(value) {
+    if (!isObject(value) || value.kty !== 'EC' || value.crv !== 'P-256'
+        || ![value.x, value.y, value.d].every(component => typeof component === 'string' && /^[A-Za-z0-9_-]{43}$/.test(component))) {
+        return bindingRequired();
+    }
+    const key = { kty: 'EC', crv: 'P-256', x: value.x, y: value.y, d: value.d };
+    try {
+        // Validate canonical 32-byte coordinates and that the public point belongs
+        // to this private scalar before persisting or signing with a restored key.
+        for (const component of [key.x, key.y, key.d]) {
+            if (Buffer.from(component, 'base64url').toString('base64url') !== component)
+                return bindingRequired();
+        }
+        const curve = createECDH('prime256v1');
+        curve.setPrivateKey(Buffer.from(key.d, 'base64url'));
+        const point = curve.getPublicKey();
+        if (point.subarray(1, 33).toString('base64url') !== key.x || point.subarray(33).toString('base64url') !== key.y)
+            return bindingRequired();
+        return key;
+    }
+    catch {
+        return bindingRequired();
+    }
+}
+export function generateDpopPrivateJwk() {
+    return validateDpopPrivateJwk(generateKeyPairSync('ec', { namedCurve: 'prime256v1' }).privateKey.export({ format: 'jwk' }));
+}
+export function dpopThumbprint(key) {
+    // RFC 7638 uses only the required public members, in lexicographic order.
+    return createHash('sha256').update(JSON.stringify({ crv: key.crv, kty: key.kty, x: key.x, y: key.y })).digest('base64url');
+}
+export function createDpopProof(value, endpoint, nonce) {
+    const key = validateDpopPrivateJwk(value);
+    const url = new URL(endpoint);
+    if (url.search || url.hash)
+        throw new CliError('OIDC_METADATA', 'DPoP endpoints must not contain a query or fragment.', 4);
+    const header = { typ: 'dpop+jwt', alg: 'ES256', jwk: { kty: key.kty, crv: key.crv, x: key.x, y: key.y } };
+    const claims = { htu: endpoint, htm: 'POST', iat: Math.floor(Date.now() / 1000), jti: randomUUID(), ...(nonce === undefined ? {} : { nonce }) };
+    const signingInput = `${Buffer.from(JSON.stringify(header)).toString('base64url')}.${Buffer.from(JSON.stringify(claims)).toString('base64url')}`;
+    const signature = sign('sha256', Buffer.from(signingInput), { key: createPrivateKey({ key: { ...key }, format: 'jwk' }), dsaEncoding: 'ieee-p1363' });
+    return `${signingInput}.${signature.toString('base64url')}`;
+}
+export function assertRefreshBinding(token, key) {
+    // This is a compatibility assertion on a token received from the authenticated
+    // issuer endpoint, not JWT signature verification or an authorization decision.
+    // The API and identity provider remain responsible for validating their tokens.
+    try {
+        const parts = token.split('.');
+        if (parts.length !== 3 || parts.some(part => !part || !/^[A-Za-z0-9_-]+$/.test(part)))
+            return bindingRequired();
+        const claims = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));
+        if (!isObject(claims) || !isObject(claims.cnf) || claims.cnf.jkt !== dpopThumbprint(key))
+            return bindingRequired();
+    }
+    catch {
+        return bindingRequired();
+    }
+}

package/dist/errors.js

@@ -0,0 +1,30 @@
+export class CliError extends Error {
+    code;
+    exitCode;
+    status;
+    retryAfter;
+    reconciliation;
+    constructor(code, message, exitCode = 1, status, retryAfter, reconciliation) {
+        super(message);
+        this.code = code;
+        this.exitCode = exitCode;
+        this.status = status;
+        this.retryAfter = retryAfter;
+        this.reconciliation = reconciliation;
+        this.name = 'CliError';
+    }
+}
+export function usage(message) {
+    throw new CliError('USAGE', message, 2);
+}
+export function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+// API strings are untrusted terminal content, including user-authored names.
+export function terminalText(value) {
+    return value.replace(/[\x00-\x1f\x7f-\x9f\u202a-\u202e\u2066-\u2069]/g, '');
+}
+// JSON remains lossless and parseable while controls cannot affect a terminal.
+export function terminalJson(value, pretty = false) {
+    return JSON.stringify(value, null, pretty ? 2 : undefined).replace(/[\u007f-\u009f\u202a-\u202e\u2066-\u2069]/g, character => `\\u${character.charCodeAt(0).toString(16).padStart(4, '0')}`);
+}