@remixmate/cli 0.1.2 → 0.9.1

package/README.md

@@ -38,6 +38,52 @@ Codex does not load `SKILL.md` natively. Tell Codex about the CLI in your system
 
 See the full intro page (Claude Code / Codex setup, env vars, end-to-end workflow examples) at the project homepage.
 
+## Authentication
+
+The recommended way to authenticate (for humans installing the CLI) is a browser
+device-login — no token pasting required:
+
+```bash
+remixmate login     # opens your browser to approve, then stores credentials securely
+remixmate whoami    # show the current identity (never prints the token)
+remixmate logout    # remove stored credentials from this machine
+```
+
+`login` uses the OAuth 2.0 Device Authorization Grant (RFC 8628): the CLI shows a
+device code, you approve it in a browser that is already signed in to the web app, and
+the CLI receives and stores your credential in the OS keychain (or a `0600` file at
+`~/.config/remixmate/credentials.json`). It only runs in an interactive terminal.
+
+For CI and agent-embedded hosts (ab-agent / Claude Code), keep using the `PRIV_TOKEN`
+environment variable. Credential resolution precedence is:
+
+```
+--token flag  >  PRIV_TOKEN env var  >  stored credential (from `remixmate login`)
+```
+
+When `PRIV_TOKEN` is set, `login` is skipped and the device flow is never auto-triggered.
+
+### Automatic browser authorization (local hosts)
+
+When a skill that needs a credential is invoked from a **local third-party host**
+(Claude Code / Codex / a terminal) and none of `--token` / `PRIV_TOKEN` / the stored
+credential yields a token, the CLI automatically runs the device flow once: it opens
+your browser, prints the verification URL + code, waits a short window, and on approval
+stores the credential — so every later call resolves silently.
+
+This only fires on a **browser-capable local desktop**. It never fires when `PRIV_TOKEN`
+is injected (cloud hosts) or in **headless** environments (CI / no GUI / no `DISPLAY`),
+which keep the existing fail-fast behavior. Controls:
+
+```
+REMIXMATE_NO_BROWSER_AUTH=1     # force-disable auto auth (always fail-fast)
+REMIXMATE_AUTH_WAIT_SECONDS=25  # short-wait window (default 25s); on timeout it
+                                # tells you to authorize and re-run, never blocks forever
+```
+
+> Security: if you previously pasted your `PRIV_TOKEN` into a chat box or shell history,
+> rotate it after switching to `remixmate login`.
+
 ## Environment
 
 Most skills authenticate against ab-api with a `PRIV_TOKEN`. Without a valid token (and network access to ab-api) the template / media-generation skills are unavailable — the code is open-source, but the generation capabilities are hosted on the ab-api service. Copy `.env.example` to `.env` and source it before running:

package/README.zh-CN.md

@@ -38,6 +38,28 @@ Codex 不会原生加载 `SKILL.md`。在系统提示里告诉 Codex 这个 CLI
 
 完整介绍页（Claude Code / Codex 配置、环境变量、端到端工作流示例）见项目主页。
 
+## 认证
+
+推荐方式（人类用户）：浏览器设备登录，无需手动粘贴 token：
+
+```bash
+remixmate login     # 在浏览器确认授权，凭证安全保存到本机
+remixmate whoami    # 查看当前身份（绝不打印 token）
+remixmate logout    # 从本机移除已存储的凭证
+```
+
+`login` 使用 OAuth 2.0 设备授权流程（RFC 8628）：CLI 显示设备码，你在已登录 Web 的浏览器中确认，CLI 随后取回凭证并保存到系统钥匙串（或 `~/.config/remixmate/credentials.json`，权限 `0600`）。仅在交互式终端中可用。
+
+CI 与 agent 宿主（ab-agent / Claude Code）继续使用 `PRIV_TOKEN` 环境变量。凭证解析优先级：
+
+```
+--token 参数  >  PRIV_TOKEN 环境变量  >  本地已存凭证（remixmate login 写入）
+```
+
+设置了 `PRIV_TOKEN` 时，`login` 会跳过，且任何命令都不会自动触发设备登录流程。
+
+> 安全提示：若你此前曾把 `PRIV_TOKEN` 粘贴到聊天框或写进 shell 历史，切换到 `remixmate login` 后建议轮换该 token。
+
 ## 环境
 
 多数技能通过 `PRIV_TOKEN` 向 ab-api 鉴权。没有有效 token（以及访问 ab-api 的网络）时，模板 / 媒体生成类技能不可用——代码是开源的，但生成能力托管在 ab-api 服务上。运行前把 `.env.example` 拷为 `.env` 并 source：

package/dist/auth/auth-lock.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Cross-process file lock for the auto device-login flow.
+ *
+ * When several skill processes start without a token at the same time, only one
+ * should drive the Device Flow (= open one browser). The rest wait for the
+ * winner to write the credential, then read it. This lock coordinates that.
+ *
+ * The lock file lives next to the credential store, contains only non-secret
+ * metadata, and self-heals: a lock left behind by a crashed process is reclaimed
+ * once it is older than `staleMs` (Requirement 3.1/3.4/3.5).
+ */
+export interface LockHandle {
+    release(): Promise<void>;
+}
+/**
+ * Try to acquire the auth lock for `apiBaseUrl`.
+ *   - Returns a handle when acquired.
+ *   - Returns null when another live process holds it.
+ *   - Reclaims a stale lock (older than `staleMs`) and retries once.
+ */
+export declare function acquireLock(apiBaseUrl: string, staleMs: number): Promise<LockHandle | null>;
+/**
+ * Poll the credential store until a usable credential for `apiBaseUrl` appears
+ * or `timeoutMs` elapses. Used by processes that did NOT win the lock.
+ */
+export declare function waitForCredential(apiBaseUrl: string, timeoutMs: number): Promise<boolean>;

package/dist/auth/auth-lock.js

@@ -0,0 +1,100 @@
+/**
+ * Cross-process file lock for the auto device-login flow.
+ *
+ * When several skill processes start without a token at the same time, only one
+ * should drive the Device Flow (= open one browser). The rest wait for the
+ * winner to write the credential, then read it. This lock coordinates that.
+ *
+ * The lock file lives next to the credential store, contains only non-secret
+ * metadata, and self-heals: a lock left behind by a crashed process is reclaimed
+ * once it is older than `staleMs` (Requirement 3.1/3.4/3.5).
+ */
+import { createHash } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import { join } from 'node:path';
+import { CRED_DIR, getCredential } from './credential-store.js';
+/** Stable short hash so different apiBaseUrls never block each other. */
+function lockPathFor(apiBaseUrl) {
+    const hash = createHash('sha256').update(apiBaseUrl).digest('hex').slice(0, 12);
+    return join(CRED_DIR, `auth-${hash}.lock`);
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+async function writeLockFile(lockPath) {
+    const payload = { pid: process.pid, createdAt: Date.now() };
+    // `wx` fails if the file already exists → atomic acquire.
+    await fs.writeFile(lockPath, JSON.stringify(payload), { flag: 'wx', mode: 0o600 });
+}
+/** Best-effort removal; never throws. */
+async function safeUnlink(lockPath) {
+    try {
+        await fs.unlink(lockPath);
+    }
+    catch {
+        // already gone / not ours — nothing to do
+    }
+}
+/**
+ * Try to acquire the auth lock for `apiBaseUrl`.
+ *   - Returns a handle when acquired.
+ *   - Returns null when another live process holds it.
+ *   - Reclaims a stale lock (older than `staleMs`) and retries once.
+ */
+export async function acquireLock(apiBaseUrl, staleMs) {
+    await fs.mkdir(CRED_DIR, { recursive: true, mode: 0o700 });
+    const lockPath = lockPathFor(apiBaseUrl);
+    try {
+        await writeLockFile(lockPath);
+        return makeHandle(lockPath);
+    }
+    catch {
+        // Lock exists — decide whether it is stale.
+    }
+    let stale = false;
+    try {
+        const stat = await fs.stat(lockPath);
+        stale = Date.now() - stat.mtimeMs > staleMs;
+    }
+    catch {
+        // Disappeared between the failed create and the stat → treat as free.
+        stale = true;
+    }
+    if (!stale)
+        return null;
+    // Reclaim the stale lock and retry exactly once.
+    await safeUnlink(lockPath);
+    try {
+        await writeLockFile(lockPath);
+        return makeHandle(lockPath);
+    }
+    catch {
+        // Someone else won the race after we cleared it.
+        return null;
+    }
+}
+function makeHandle(lockPath) {
+    let released = false;
+    return {
+        async release() {
+            if (released)
+                return;
+            released = true;
+            await safeUnlink(lockPath);
+        },
+    };
+}
+/**
+ * Poll the credential store until a usable credential for `apiBaseUrl` appears
+ * or `timeoutMs` elapses. Used by processes that did NOT win the lock.
+ */
+export async function waitForCredential(apiBaseUrl, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const intervalMs = 1_000;
+    while (Date.now() < deadline) {
+        const cred = await getCredential(apiBaseUrl);
+        if (cred && cred.privToken.trim())
+            return true;
+        await sleep(intervalMs);
+    }
+    const cred = await getCredential(apiBaseUrl);
+    return !!(cred && cred.privToken.trim());
+}

package/dist/auth/auto-login.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Automatic Device Flow orchestration triggered when a skill call finds no
+ * token. Only ever invoked AFTER resolvePrivToken() has confirmed all three
+ * sources (flag / env / credential store) are empty, so the env-injected
+ * (cloud) path never reaches this module — guaranteeing zero regression there.
+ *
+ * Flow (see design.md):
+ *   canAutoAuth gate → acquire lock
+ *     ├─ won  : runDeviceFlow(short wait) → on approval re-read the store
+ *     └─ lost : wait for whoever holds the lock to write a credential
+ *
+ * Always bounded by `maxWaitMs` so it can never block a host tool call forever.
+ */
+import { type ResolvedToken } from './resolve.js';
+/**
+ * Attempt to obtain a token via automatic browser authorization. Returns the
+ * resolved token on success, or null when auto auth is not applicable / did not
+ * complete in time (callers then fail fast with NOT_AUTHENTICATED_HINT).
+ */
+export declare function attemptAutoLogin(apiBaseUrl: string): Promise<ResolvedToken | null>;

package/dist/auth/auto-login.js

@@ -0,0 +1,66 @@
+/**
+ * Automatic Device Flow orchestration triggered when a skill call finds no
+ * token. Only ever invoked AFTER resolvePrivToken() has confirmed all three
+ * sources (flag / env / credential store) are empty, so the env-injected
+ * (cloud) path never reaches this module — guaranteeing zero regression there.
+ *
+ * Flow (see design.md):
+ *   canAutoAuth gate → acquire lock
+ *     ├─ won  : runDeviceFlow(short wait) → on approval re-read the store
+ *     └─ lost : wait for whoever holds the lock to write a credential
+ *
+ * Always bounded by `maxWaitMs` so it can never block a host tool call forever.
+ */
+import { resolvePrivToken } from './resolve.js';
+import { canAutoAuth } from './environment.js';
+import { acquireLock, waitForCredential } from './auth-lock.js';
+import { runDeviceFlow } from './device-flow-runner.js';
+const DEFAULT_WAIT_MS = 25_000;
+/** Extra slack on top of the wait window before a held lock is considered stale. */
+const STALE_SLACK_MS = 10_000;
+/** Resolve the short-wait window from env, falling back to the default. */
+function waitMs() {
+    const raw = Number(process.env.REMIXMATE_AUTH_WAIT_SECONDS);
+    return Number.isFinite(raw) && raw > 0 ? raw * 1000 : DEFAULT_WAIT_MS;
+}
+/**
+ * Attempt to obtain a token via automatic browser authorization. Returns the
+ * resolved token on success, or null when auto auth is not applicable / did not
+ * complete in time (callers then fail fast with NOT_AUTHENTICATED_HINT).
+ */
+export async function attemptAutoLogin(apiBaseUrl) {
+    if (!canAutoAuth())
+        return null;
+    const max = waitMs();
+    const lock = await acquireLock(apiBaseUrl, max + STALE_SLACK_MS);
+    if (!lock) {
+        // Another process is driving the Device Flow — wait for its credential.
+        process.stderr.write('ℹ️  另一个进程正在授权，等待其完成…\n');
+        const ok = await waitForCredential(apiBaseUrl, max);
+        return ok ? resolvePrivToken({ apiBaseUrl }) : null;
+    }
+    try {
+        const outcome = await runDeviceFlow(apiBaseUrl, { maxWaitMs: max });
+        switch (outcome.status) {
+            case 'approved':
+                process.stderr.write(`✅ 授权成功：${outcome.userLabel ?? ''}\n`);
+                return resolvePrivToken({ apiBaseUrl });
+            case 'timeout':
+                process.stderr.write('⏳ 已打开授权页但未在等待窗口内完成。请在浏览器完成授权后重跑同一命令。\n');
+                return null;
+            case 'denied':
+                process.stderr.write('❌ 授权被拒绝。\n');
+                return null;
+            case 'expired':
+                process.stderr.write('❌ 设备码已过期，请重跑命令重新授权。\n');
+                return null;
+            case 'error':
+            default:
+                process.stderr.write(`❌ 自动授权失败：${'message' in outcome ? outcome.message : '未知错误'}\n`);
+                return null;
+        }
+    }
+    finally {
+        await lock.release();
+    }
+}

package/dist/auth/commands.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `remixmate login | logout | whoami` command implementations.
+ *
+ * Security: the PrivToken value is never printed. Identity is shown by label only.
+ * Env/CI behavior: when PRIV_TOKEN is set, `login` does not start the device flow.
+ */
+/** Dispatch an auth verb. Returns a process exit code. */
+export declare function runAuthCommand(verb: string, rest: string[]): Promise<number>;

package/dist/auth/commands.js

@@ -0,0 +1,130 @@
+/**
+ * `remixmate login | logout | whoami` command implementations.
+ *
+ * Security: the PrivToken value is never printed. Identity is shown by label only.
+ * Env/CI behavior: when PRIV_TOKEN is set, `login` does not start the device flow.
+ */
+import { parseArgv } from '../argv.js';
+import { resolveApiBaseUrl } from '../http.js';
+import { getCredential, removeCredential } from './credential-store.js';
+import { resolvePrivToken } from './resolve.js';
+import { runDeviceFlow } from './device-flow-runner.js';
+async function login(apiBaseUrl) {
+    // Env token short-circuits the device flow (CI / agent-embedded hosts).
+    if ((process.env.PRIV_TOKEN ?? '').trim()) {
+        process.stdout.write('ℹ️  PRIV_TOKEN 环境变量已设置，CLI 将直接使用它，无需登录。\n');
+        return 0;
+    }
+    // Device flow requires an interactive terminal.
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        process.stderr.write('❌ remixmate login 需要交互式终端；在 CI/无终端环境请改用 PRIV_TOKEN 环境变量。\n');
+        return 1;
+    }
+    // Already authenticated for this backend?
+    const existing = await getCredential(apiBaseUrl);
+    if (existing) {
+        process.stdout.write(`✅ 已登录（${existing.userLabel ?? 'unknown'}）。如需切换账号请先运行 remixmate logout。\n`);
+        return 0;
+    }
+    // Interactive login uses the device code's full lifetime (no short-wait cap)
+    // and routes progress to stdout. Shared orchestration handles persistence.
+    const outcome = await runDeviceFlow(apiBaseUrl, {
+        write: (msg) => process.stdout.write(msg),
+    });
+    switch (outcome.status) {
+        case 'approved':
+            process.stdout.write(`\n✅ 登录成功：${outcome.userLabel ?? ''}\n`);
+            process.stdout.write('🔒 安全提示：若你此前曾把 PrivToken 粘贴到聊天框或写进 shell 历史，建议在控制台轮换该 token。\n');
+            return 0;
+        case 'denied':
+            process.stderr.write('❌ 授权被拒绝。\n');
+            return 1;
+        case 'error':
+            process.stderr.write(`❌ 登录失败：${outcome.message}\n`);
+            return 1;
+        case 'timeout':
+        case 'expired':
+        default:
+            process.stderr.write('❌ 设备码已过期或无效，请重新运行 remixmate login。\n');
+            return 1;
+    }
+}
+async function logout(apiBaseUrl) {
+    const res = await removeCredential(apiBaseUrl);
+    const localNote = 'ℹ️  logout 仅清除本地凭证，不会在服务端吊销 PrivToken；如需服务端失效请轮换 token。\n';
+    if (!res.removedFile && !res.removedKeychain && !res.fileError && !res.keychainError) {
+        process.stdout.write('ℹ️  未找到已存储的凭证。\n');
+        return 0;
+    }
+    // Partial failure: keychain removed but file not cleared (Req 8.4), or vice versa.
+    if (res.fileError || res.keychainError) {
+        const which = res.fileError ? '本地文件' : '系统钥匙串';
+        process.stderr.write(`⚠️  凭证未完全清除：${which}清除失败（${res.fileError ?? res.keychainError}）。\n`);
+        process.stdout.write(localNote);
+        return 1;
+    }
+    process.stdout.write('✅ 已清除本地存储的凭证。\n');
+    process.stdout.write(localNote);
+    return 0;
+}
+/** Probe token validity against an existing authenticated endpoint (10s timeout). */
+async function verifyToken(apiBaseUrl, token) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), 10_000);
+    try {
+        const resp = await fetch(`${apiBaseUrl}/remotionTemplate/registry`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', 'X-Priv-Token': token },
+            body: '{}',
+            signal: controller.signal,
+        });
+        const parsed = JSON.parse(await resp.text());
+        if (parsed.code === 0)
+            return 'valid';
+        if (parsed.code === 401)
+            return 'invalid';
+        return 'invalid';
+    }
+    catch {
+        return 'unreachable';
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function whoami(apiBaseUrl, flagToken) {
+    const resolved = await resolvePrivToken({ flag: flagToken, apiBaseUrl });
+    if (!resolved) {
+        process.stderr.write('❌ 未登录。运行 remixmate login，或设置 PRIV_TOKEN 环境变量。\n');
+        return 1;
+    }
+    const verdict = await verifyToken(apiBaseUrl, resolved.privToken);
+    if (verdict === 'unreachable') {
+        process.stderr.write('❌ 无法验证身份：后端不可达或超时（本地凭证未改动）。\n');
+        return 1;
+    }
+    if (verdict === 'invalid') {
+        process.stderr.write(`❌ 凭证无效或已被吊销。来源：${resolved.source}\n`);
+        return 1;
+    }
+    const label = resolved.userLabel ?? '(已认证)';
+    process.stdout.write(`已认证：${label}\n来源：${resolved.source}\n`);
+    return 0;
+}
+/** Dispatch an auth verb. Returns a process exit code. */
+export async function runAuthCommand(verb, rest) {
+    const args = parseArgv(rest);
+    const apiBaseUrl = resolveApiBaseUrl(args.api_base_url);
+    const flagToken = args.token;
+    switch (verb) {
+        case 'login':
+            return login(apiBaseUrl);
+        case 'logout':
+            return logout(apiBaseUrl);
+        case 'whoami':
+            return whoami(apiBaseUrl, flagToken);
+        default:
+            process.stderr.write(`❌ unknown auth command: ${verb}\n`);
+            return 2;
+    }
+}

package/dist/auth/credential-store.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Local credential store for the remixmate CLI.
+ *
+ * Design (see .kiro/specs/cli-device-login/design.md):
+ *   - File store at ~/.config/remixmate/credentials.json (mode 0600) is the
+ *     REQUIRED, always-present implementation. Entries are keyed by API base
+ *     URL so multiple accounts / backends coexist without overwriting.
+ *   - The OS keychain is an OPTIONAL enhancement loaded via dynamic import().
+ *     When a keychain module is available we keep the secret PrivToken there
+ *     and store only non-secret metadata (+ a location marker) in the file.
+ *     When it is absent or fails at runtime, the PrivToken is stored in the
+ *     file instead. Either way the PrivToken value is never logged.
+ *
+ * No new runtime dependency is added: keychain support activates only if a
+ * compatible module (`keytar`) is already importable in the host environment.
+ */
+export declare const CRED_DIR: string;
+export declare const CRED_FILE: string;
+/** A resolved credential as seen by callers (token always populated). */
+export interface StoredCredential {
+    privToken: string;
+    userLabel?: string;
+    createdAt: number;
+}
+/** Result of a remove, so callers (logout) can report partial failures. */
+export interface RemoveResult {
+    removedFile: boolean;
+    removedKeychain: boolean;
+    keychainError?: string;
+    fileError?: string;
+}
+/**
+ * Persist a credential for `apiBaseUrl`. Prefers the keychain for the secret;
+ * falls back to the file on absence or runtime failure. Returns whether the
+ * keychain was used so callers can surface "keychain unavailable, used file".
+ */
+export declare function setCredential(apiBaseUrl: string, cred: StoredCredential): Promise<{
+    usedKeychain: boolean;
+    keychainError?: string;
+}>;
+/** Read a credential for `apiBaseUrl`, or null when none is stored. */
+export declare function getCredential(apiBaseUrl: string): Promise<StoredCredential | null>;
+/** Remove a credential from both stores; reports per-store outcome. */
+export declare function removeCredential(apiBaseUrl: string): Promise<RemoveResult>;

package/dist/auth/credential-store.js

@@ -0,0 +1,126 @@
+/**
+ * Local credential store for the remixmate CLI.
+ *
+ * Design (see .kiro/specs/cli-device-login/design.md):
+ *   - File store at ~/.config/remixmate/credentials.json (mode 0600) is the
+ *     REQUIRED, always-present implementation. Entries are keyed by API base
+ *     URL so multiple accounts / backends coexist without overwriting.
+ *   - The OS keychain is an OPTIONAL enhancement loaded via dynamic import().
+ *     When a keychain module is available we keep the secret PrivToken there
+ *     and store only non-secret metadata (+ a location marker) in the file.
+ *     When it is absent or fails at runtime, the PrivToken is stored in the
+ *     file instead. Either way the PrivToken value is never logged.
+ *
+ * No new runtime dependency is added: keychain support activates only if a
+ * compatible module (`keytar`) is already importable in the host environment.
+ */
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promises as fs } from 'node:fs';
+export const CRED_DIR = join(homedir(), '.config', 'remixmate');
+export const CRED_FILE = join(CRED_DIR, 'credentials.json');
+const KEYCHAIN_SERVICE = 'remixmate-cli';
+let keychainProbe;
+/** Lazily attempt to load an optional keychain module; cache the (null) result. */
+async function loadKeychain() {
+    if (keychainProbe === undefined) {
+        keychainProbe = import('keytar')
+            .then((m) => (m.default ?? m))
+            .catch(() => null);
+    }
+    return keychainProbe;
+}
+async function readFileStore() {
+    try {
+        const raw = await fs.readFile(CRED_FILE, 'utf8');
+        const parsed = JSON.parse(raw);
+        if (parsed && parsed.version === 1 && parsed.credentials) {
+            return { version: 1, credentials: parsed.credentials };
+        }
+    }
+    catch {
+        // Missing or unreadable/corrupt file → treat as empty store.
+    }
+    return { version: 1, credentials: {} };
+}
+async function writeFileStore(store) {
+    await fs.mkdir(CRED_DIR, { recursive: true, mode: 0o700 });
+    // Write with 0600 from the start, then chmod defensively in case the file
+    // pre-existed with looser permissions.
+    await fs.writeFile(CRED_FILE, JSON.stringify(store, null, 2), { mode: 0o600 });
+    await fs.chmod(CRED_FILE, 0o600);
+}
+/**
+ * Persist a credential for `apiBaseUrl`. Prefers the keychain for the secret;
+ * falls back to the file on absence or runtime failure. Returns whether the
+ * keychain was used so callers can surface "keychain unavailable, used file".
+ */
+export async function setCredential(apiBaseUrl, cred) {
+    const store = await readFileStore();
+    const entry = {
+        userLabel: cred.userLabel,
+        createdAt: cred.createdAt,
+        secret: 'file',
+        privToken: cred.privToken,
+    };
+    const keychain = await loadKeychain();
+    let usedKeychain = false;
+    let keychainError;
+    if (keychain) {
+        try {
+            await keychain.setPassword(KEYCHAIN_SERVICE, apiBaseUrl, cred.privToken);
+            usedKeychain = true;
+            entry.secret = 'keychain';
+            delete entry.privToken; // keep the secret out of the file
+        }
+        catch (err) {
+            keychainError = err.message;
+        }
+    }
+    store.credentials[apiBaseUrl] = entry;
+    await writeFileStore(store);
+    return { usedKeychain, keychainError };
+}
+/** Read a credential for `apiBaseUrl`, or null when none is stored. */
+export async function getCredential(apiBaseUrl) {
+    const store = await readFileStore();
+    const entry = store.credentials[apiBaseUrl];
+    if (!entry)
+        return null;
+    let privToken = entry.privToken;
+    if (entry.secret === 'keychain') {
+        const keychain = await loadKeychain();
+        const secret = keychain ? await keychain.getPassword(KEYCHAIN_SERVICE, apiBaseUrl) : null;
+        if (!secret)
+            return null; // secret expected in keychain but unavailable
+        privToken = secret;
+    }
+    if (!privToken)
+        return null;
+    return { privToken, userLabel: entry.userLabel, createdAt: entry.createdAt };
+}
+/** Remove a credential from both stores; reports per-store outcome. */
+export async function removeCredential(apiBaseUrl) {
+    const result = { removedFile: false, removedKeychain: false };
+    const keychain = await loadKeychain();
+    if (keychain) {
+        try {
+            result.removedKeychain = await keychain.deletePassword(KEYCHAIN_SERVICE, apiBaseUrl);
+        }
+        catch (err) {
+            result.keychainError = err.message;
+        }
+    }
+    const store = await readFileStore();
+    if (store.credentials[apiBaseUrl]) {
+        delete store.credentials[apiBaseUrl];
+        try {
+            await writeFileStore(store);
+            result.removedFile = true;
+        }
+        catch (err) {
+            result.fileError = err.message;
+        }
+    }
+    return result;
+}

package/dist/auth/device-flow-runner.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared Device Flow orchestration used by BOTH `remixmate login` (interactive,
+ * full device-code lifetime) and the automatic browser auth that kicks in when
+ * a skill call finds no token (bounded by a short wait window).
+ *
+ * Centralizing the request → open browser → poll → persist sequence keeps the
+ * two entry points byte-for-byte consistent (Requirement 4.1/4.2) and means the
+ * credential written by auto-login is indistinguishable from `login`'s.
+ *
+ * Security: the PrivToken value is NEVER written to the provided sink.
+ */
+export interface DeviceFlowOptions {
+    /**
+     * Upper bound on how long to poll for approval. When omitted the device
+     * code's own `expiresIn` is the only bound (used by interactive `login`).
+     * When set (auto-login), a stop caused by this window is reported as
+     * `'timeout'` rather than `'expired'`.
+     */
+    maxWaitMs?: number;
+    /** Where human-facing progress text goes. Defaults to stderr. */
+    write?: (msg: string) => void;
+    /** Client label sent with the device-code request. */
+    clientLabel?: string;
+}
+export type DeviceFlowOutcome = {
+    status: 'approved';
+    userLabel?: string;
+} | {
+    status: 'timeout';
+} | {
+    status: 'denied';
+} | {
+    status: 'expired';
+} | {
+    status: 'error';
+    message: string;
+};
+/**
+ * Run one full Device Flow against `apiBaseUrl`. On approval the PrivToken is
+ * persisted via setCredential (keychain or file, same as `login`) and only the
+ * non-secret outcome is returned.
+ */
+export declare function runDeviceFlow(apiBaseUrl: string, opts?: DeviceFlowOptions): Promise<DeviceFlowOutcome>;