@moewolf/moe-icons-cli 0.0.1

package/LICENSE

@@ -0,0 +1,15 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,32 @@
+# moeicons
+
+Public CLI for the Moeicons icon library. Installs icon style groups into your
+project, manages login/tokens, generates React/Vue proxy components, and exposes
+an MCP server for AI clients.
+
+## Commands
+
+```text
+moeicons                    interactive guided flow (free / pro / login)
+moeicons install [group]    install an icon group
+moeicons login              browser login (PKCE)
+moeicons logout             clear local session
+moeicons account            show account/tier info
+moeicons groups             list available icon groups
+ moeicons generate           generate target-specific project files
+moeicons mcp                start the MCP stdio server
+ npm install -g @moewolf/moe-icons-cli
+ moeicons --version          show version
+moeicons --help             show help
+```
+
+## Security
+
+- Tokens are stored in the OS keychain where available.
+- API keys are never logged or written in plaintext.
+- Installation is transactional: failures never corrupt an existing project.
+- Downloads verify SHA-256 and never shell out to `unzip`/`tar`.
+
+## Status
+
+Scaffold in progress (Phase 5 of the Moeicons development plan).

package/bin/moeicons.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+import { main } from "../dist/cli.js";
+
+const runtime = {
+  cwd: () => process.cwd(),
+  stdout: (text) => process.stdout.write(text),
+  stderr: (text) => process.stderr.write(text),
+  env: process.env,
+  isTTY: () => Boolean(process.stdin.isTTY && process.stdout.isTTY),
+};
+
+main(process.argv.slice(2), runtime).then(
+  (code) => {
+    process.exitCode = code;
+  },
+  (error) => {
+    process.stderr.write(`fatal: ${String(error)}\n`);
+    process.exitCode = 5;
+  },
+);

package/dist/api/client.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Typed backend client. Fixed configured base URL, timeout/abort, auth
+ * injection, JSON/content-type/size validation, request ID capture, and retry
+ * for GET/idempotent calls with capped backoff.
+ */
+export interface ApiConfig {
+    readonly baseUrl: string;
+    readonly timeoutMs?: number;
+    readonly maxBodyBytes?: number;
+}
+export interface RequestJsonOptions {
+    readonly method?: "GET" | "POST" | "PUT" | "DELETE";
+    readonly auth?: string;
+    readonly authHeader?: string;
+    readonly body?: unknown;
+    readonly signal?: AbortSignal;
+    readonly retries?: number;
+    readonly requestId?: string;
+}
+export interface ApiResult<T> {
+    readonly status: number;
+    readonly data: T;
+    readonly requestId: string;
+}
+/**
+ * Perform a JSON request against the fixed base URL. Retries GET/idempotent
+ * calls with capped exponential backoff on 5xx and network errors.
+ */
+export declare function requestJson<T>(config: ApiConfig, path: string, options?: RequestJsonOptions): Promise<ApiResult<T>>;
+export interface ApiKeyEntitlement {
+    readonly valid: boolean;
+    readonly tier: "free" | "pro" | "ent";
+    readonly accountId: string;
+}
+/**
+ * Verify an API key. Trim once, never log, send via the configured header,
+ * map 401/403/429/5xx distinctly. No persistent storage by default.
+ */
+export declare function verifyApiKey(config: ApiConfig, key: string, options?: {
+    verifyPath?: string;
+    signal?: AbortSignal;
+}): Promise<ApiKeyEntitlement>;

package/dist/api/client.js

@@ -0,0 +1,105 @@
+import { CliError } from "../errors/index.js";
+/**
+ * Perform a JSON request against the fixed base URL. Retries GET/idempotent
+ * calls with capped exponential backoff on 5xx and network errors.
+ */
+export async function requestJson(config, path, options = {}) {
+    const method = options.method ?? "GET";
+    const retries = options.retries ?? 0;
+    const timeoutMs = config.timeoutMs ?? 10_000;
+    const requestId = options.requestId ??
+        `req-${Math.random().toString(36).slice(2, 10)}`;
+    const attempt = async () => {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        const externalSignal = options.signal;
+        const abortHandler = () => controller.abort();
+        externalSignal?.addEventListener("abort", abortHandler, { once: true });
+        const headers = {
+            "content-type": "application/json",
+            "x-request-id": requestId,
+        };
+        if (options.auth) {
+            headers[options.authHeader ?? "authorization"] = options.auth;
+        }
+        try {
+            const response = await fetch(`${config.baseUrl.replace(/\/$/, "")}${path}`, {
+                method,
+                headers,
+                ...(options.body !== undefined ? { body: JSON.stringify(options.body) } : {}),
+                signal: controller.signal,
+            });
+            const text = await response.text();
+            if (text.length > (config.maxBodyBytes ?? 5 * 1024 * 1024)) {
+                throw new CliError("VALIDATION_ERROR", "response body exceeds size limit");
+            }
+            let data = null;
+            if (text.length > 0) {
+                try {
+                    data = JSON.parse(text);
+                }
+                catch {
+                    throw new CliError("VALIDATION_ERROR", "response is not valid JSON");
+                }
+            }
+            if (response.status === 401)
+                throw new CliError("AUTH_ERROR", "unauthorized");
+            if (response.status === 403)
+                throw new CliError("FORBIDDEN", "forbidden");
+            if (response.status === 429) {
+                throw new CliError("NETWORK_ERROR", "rate limited");
+            }
+            if (response.status >= 500 && retries > 0) {
+                throw new RetryableStatus(response.status);
+            }
+            if (response.status >= 400) {
+                throw new CliError("NETWORK_ERROR", `request failed with ${response.status}`);
+            }
+            return { status: response.status, data: data, requestId };
+        }
+        finally {
+            clearTimeout(timer);
+            externalSignal?.removeEventListener("abort", abortHandler);
+        }
+    };
+    let lastError;
+    for (let i = 0; i <= retries; i += 1) {
+        try {
+            return await attempt();
+        }
+        catch (error) {
+            if (error instanceof CliError)
+                throw error;
+            if (error instanceof RetryableStatus && i < retries) {
+                const backoff = Math.min(500 * 2 ** i, 4000);
+                await new Promise((resolve) => setTimeout(resolve, backoff));
+                continue;
+            }
+            lastError = error;
+        }
+    }
+    throw lastError;
+}
+class RetryableStatus extends Error {
+    status;
+    constructor(status) {
+        super(`retryable status ${status}`);
+        this.status = status;
+    }
+}
+/**
+ * Verify an API key. Trim once, never log, send via the configured header,
+ * map 401/403/429/5xx distinctly. No persistent storage by default.
+ */
+export async function verifyApiKey(config, key, options = {}) {
+    const trimmed = key.trim();
+    if (trimmed.length === 0) {
+        throw new CliError("VALIDATION_ERROR", "API key must not be empty");
+    }
+    const result = await requestJson(config, options.verifyPath ?? "/v1/apikey/verify", {
+        method: "POST",
+        body: { key: trimmed },
+        ...(options.signal ? { signal: options.signal } : {}),
+    });
+    return result.data;
+}

package/dist/auth/callback.d.ts

@@ -0,0 +1,37 @@
+import { type Server } from "node:http";
+/**
+ * Loopback callback server for OAuth Authorization Code + PKCE. Binds loopback
+ * only, serves one successful callback, cleans up on timeout/abort.
+ */
+export interface CallbackServerOptions {
+    readonly host?: string;
+    readonly port?: number;
+    readonly path: string;
+    readonly timeoutMs?: number;
+    readonly signal?: AbortSignal;
+}
+export interface CallbackResult {
+    readonly code: string;
+    readonly state: string;
+}
+export type CallbackOutcome = {
+    readonly ok: true;
+    readonly value: CallbackResult;
+} | {
+    readonly ok: false;
+    readonly code: "TIMEOUT" | "ABORTED" | "SERVER_ERROR" | "BAD_CALLBACK";
+    readonly message: string;
+};
+export interface ActiveCallbackServer {
+    readonly server: Server;
+    /** The port the server is bound to (for building the redirect URL). */
+    readonly port: number;
+    /** Resolves when the single allowed callback arrives (or timeout/abort). */
+    readonly outcome: Promise<CallbackOutcome>;
+    readonly stop: () => void;
+}
+/**
+ * Start a loopback callback server. The caller must build the authorization
+ * URL with the returned port, then await `outcome`.
+ */
+export declare function startLoopbackCallbackServer(options: CallbackServerOptions): ActiveCallbackServer;

package/dist/auth/callback.js

@@ -0,0 +1,72 @@
+import { createServer } from "node:http";
+import { parse } from "node:url";
+const LOOPBACK = "127.0.0.1";
+/**
+ * Start a loopback callback server. The caller must build the authorization
+ * URL with the returned port, then await `outcome`.
+ */
+export function startLoopbackCallbackServer(options) {
+    const host = options.host ?? LOOPBACK;
+    const path = options.path.startsWith("/") ? options.path : `/${options.path}`;
+    const timeoutMs = options.timeoutMs ?? 120_000;
+    let stopCalled = false;
+    let resolveOutcome = () => undefined;
+    const outcome = new Promise((resolve) => {
+        resolveOutcome = resolve;
+    });
+    let boundPort = options.port ?? 0;
+    let timer;
+    const server = createServer((req, res) => {
+        const url = parse(req.url ?? "/", true);
+        if (url.pathname !== path) {
+            res.writeHead(404, { "Content-Type": "text/plain" });
+            res.end("Not found");
+            return;
+        }
+        const code = typeof url.query.code === "string" ? url.query.code : undefined;
+        const state = typeof url.query.state === "string" ? url.query.state : undefined;
+        if (!code || !state) {
+            res.writeHead(400, { "Content-Type": "text/plain" });
+            res.end("Missing code or state");
+            // a malformed callback is not the success callback; do not resolve yet
+            return;
+        }
+        res.writeHead(200, { "Content-Type": "text/html" });
+        res.end("<html><body><h1>Login successful</h1><p>You can close this tab and return to the terminal.</p></body></html>");
+        stop();
+        resolveOutcome({ ok: true, value: { code, state } });
+    });
+    server.on("error", (error) => {
+        stop();
+        resolveOutcome({
+            ok: false,
+            code: "SERVER_ERROR",
+            message: error.message,
+        });
+    });
+    server.listen(options.port ?? 0, host, () => {
+        const address = server.address();
+        if (typeof address === "object" && address !== null) {
+            boundPort = address.port;
+        }
+        timer = setTimeout(() => {
+            stop();
+            resolveOutcome({ ok: false, code: "TIMEOUT", message: "login timed out" });
+        }, timeoutMs);
+    });
+    const stop = () => {
+        if (stopCalled)
+            return;
+        stopCalled = true;
+        if (timer)
+            clearTimeout(timer);
+        options.signal?.removeEventListener("abort", abortHandler);
+        server.close();
+    };
+    const abortHandler = () => {
+        stop();
+        resolveOutcome({ ok: false, code: "ABORTED", message: "login aborted" });
+    };
+    options.signal?.addEventListener("abort", abortHandler, { once: true });
+    return { server, port: boundPort, outcome, stop };
+}

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

@@ -0,0 +1,29 @@
+import type { StoredSession, TokenStore } from './token-store.js';
+export interface DeviceLoginConfig {
+    readonly apiBaseUrl: string;
+    readonly websiteOrigin: string;
+    readonly auth0Issuer: string;
+    readonly auth0ClientId: string;
+}
+export interface DeviceLoginDependencies {
+    readonly request: <T>(path: string, options: {
+        method: 'GET' | 'POST' | 'DELETE';
+        auth?: string;
+        body?: unknown;
+        signal?: AbortSignal;
+    }) => Promise<{
+        status: number;
+        data: T;
+    }>;
+    readonly openBrowser: (url: string) => Promise<void>;
+    readonly sleep: (milliseconds: number, signal?: AbortSignal) => Promise<void>;
+    readonly tokenStore: TokenStore;
+    readonly now: () => number;
+}
+export declare function loginWithDeviceSession(config: DeviceLoginConfig, deps: DeviceLoginDependencies, signal?: AbortSignal): Promise<StoredSession>;
+export declare function refreshAuth0Session(config: DeviceLoginConfig, session: StoredSession, deps: {
+    fetch: typeof fetch;
+    tokenStore: TokenStore;
+    now: () => number;
+    signal?: AbortSignal;
+}): Promise<StoredSession>;

package/dist/auth/device-login.js

@@ -0,0 +1,74 @@
+import { createLoginState, createPkcePair } from './pkce.js';
+import { CliError } from '../errors/index.js';
+function assertBrowserUrl(value, expectedOrigin) {
+    const url = new URL(value);
+    if (url.origin !== new URL(expectedOrigin).origin || url.pathname !== '/cli-login') {
+        throw new CliError('AUTH_ERROR', 'backend returned an untrusted login URL');
+    }
+}
+export async function loginWithDeviceSession(config, deps, signal) {
+    const pkce = createPkcePair();
+    const state = createLoginState();
+    const created = await deps.request('/v1/cli-login-sessions', {
+        method: 'POST', body: { codeChallenge: pkce.challenge, clientNonce: state.nonce, state: state.state }, ...(signal ? { signal } : {}),
+    });
+    assertBrowserUrl(created.data.browserUrl, config.websiteOrigin);
+    if (!Number.isSafeInteger(created.data.intervalSeconds) || created.data.intervalSeconds < 1 || created.data.intervalSeconds > 60) {
+        throw new CliError('AUTH_ERROR', 'backend returned an invalid polling interval');
+    }
+    await deps.openBrowser(created.data.browserUrl);
+    const auth = `Bearer ${created.data.pollingToken}`;
+    const sessionPath = `/v1/cli-login-sessions/${encodeURIComponent(created.data.loginId)}`;
+    try {
+        while (deps.now() < Date.parse(created.data.expiresAt)) {
+            if (signal?.aborted)
+                throw new CliError('CANCELLED', 'login cancelled');
+            const polled = await deps.request(sessionPath, { method: 'GET', auth, ...(signal ? { signal } : {}) });
+            if (polled.status === 200 && polled.data.status === 'complete' && polled.data.exchangeCode) {
+                const exchanged = await deps.request(`${sessionPath}/exchange`, {
+                    method: 'POST', auth,
+                    body: { exchangeCode: polled.data.exchangeCode, clientNonce: state.nonce, codeVerifier: pkce.verifier },
+                    ...(signal ? { signal } : {}),
+                });
+                const stored = {
+                    accountId: exchanged.data.accountId,
+                    accessToken: exchanged.data.accessToken,
+                    refreshToken: exchanged.data.refreshToken,
+                    expiresAt: deps.now() + exchanged.data.expiresIn * 1000,
+                    scope: 'openid profile email offline_access',
+                    storedAt: deps.now(),
+                };
+                deps.tokenStore.set(stored);
+                return stored;
+            }
+            await deps.sleep(created.data.intervalSeconds * 1000, signal);
+        }
+        throw new CliError('AUTH_ERROR', 'login session expired');
+    }
+    catch (error) {
+        try {
+            await deps.request(sessionPath, { method: 'DELETE', auth });
+        }
+        catch { /* best effort */ }
+        throw error;
+    }
+}
+export async function refreshAuth0Session(config, session, deps) {
+    const response = await deps.fetch(`${config.auth0Issuer.replace(/\/$/, '')}/oauth/token`, {
+        method: 'POST', headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ grant_type: 'refresh_token', client_id: config.auth0ClientId, refresh_token: session.refreshToken }),
+        ...(deps.signal ? { signal: deps.signal } : {}),
+    });
+    const body = await response.json();
+    if (!response.ok || typeof body.access_token !== 'string')
+        throw new CliError('AUTH_ERROR', 'Auth0 refresh failed');
+    const updated = {
+        ...session,
+        accessToken: body.access_token,
+        refreshToken: typeof body.refresh_token === 'string' ? body.refresh_token : session.refreshToken,
+        expiresAt: deps.now() + (typeof body.expires_in === 'number' ? body.expires_in : 3600) * 1000,
+        storedAt: deps.now(),
+    };
+    deps.tokenStore.set(updated);
+    return updated;
+}

package/dist/auth/login.d.ts

@@ -0,0 +1,41 @@
+import { type PkcePair, type LoginState } from "./pkce.js";
+/**
+ * OAuth 2.0 Authorization Code + PKCE login flow. Never accepts issuer from the
+ * callback; validates state; exchanges code; stores token only after all
+ * checks; closes the callback server in finally.
+ */
+export interface AuthConfig {
+    readonly issuer: string;
+    readonly clientId: string;
+    readonly audience: string;
+    readonly redirectPath: string;
+    readonly scope: string;
+}
+/** Build the authorization URL from configured values; never from the callback. */
+export declare function buildAuthorizationUrl(config: AuthConfig, attempt: {
+    port: number;
+    pkce: PkcePair;
+    state: LoginState;
+}): string;
+export interface TokenResponse {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly expiresIn: number;
+    readonly scope: string;
+}
+/** POST the authorization code and runtime-validate the token response. */
+export declare function exchangeAuthorizationCode(config: AuthConfig, code: string, verifier: string, deps: {
+    fetchJson: (url: string, body: unknown) => Promise<unknown>;
+}): Promise<TokenResponse>;
+export interface LoginDeps {
+    readonly openBrowser: (url: string) => Promise<void>;
+    readonly fetchJson: (url: string, body: unknown) => Promise<unknown>;
+    readonly signal?: AbortSignal;
+}
+/**
+ * Start the callback server before opening the browser; validate state then
+ * exchange; store token only after all checks; close server in finally.
+ */
+export declare function loginWithBrowser(config: AuthConfig, deps: LoginDeps): Promise<TokenResponse>;
+/** SHA-256 hex of an API key for redaction/audit (never store the raw key). */
+export declare function hashApiKey(key: string): string;

package/dist/auth/login.js

@@ -0,0 +1,85 @@
+import { createHash } from "node:crypto";
+import { startLoopbackCallbackServer } from "./callback.js";
+import { createPkcePair, createLoginState } from "./pkce.js";
+import { CliError } from "../errors/index.js";
+/** Build the authorization URL from configured values; never from the callback. */
+export function buildAuthorizationUrl(config, attempt) {
+    const params = new URLSearchParams({
+        client_id: config.clientId,
+        response_type: "code",
+        redirect_uri: `http://127.0.0.1:${attempt.port}${config.redirectPath}`,
+        scope: config.scope,
+        audience: config.audience,
+        code_challenge: attempt.pkce.challenge,
+        code_challenge_method: "S256",
+        state: attempt.state.state,
+        nonce: attempt.state.nonce,
+    });
+    return `${config.issuer.replace(/\/$/, "")}/authorize?${params.toString()}`;
+}
+/** POST the authorization code and runtime-validate the token response. */
+export async function exchangeAuthorizationCode(config, code, verifier, deps) {
+    const raw = await deps.fetchJson(`${config.issuer.replace(/\/$/, "")}/oauth/token`, {
+        grant_type: "authorization_code",
+        client_id: config.clientId,
+        code,
+        redirect_uri: "",
+        code_verifier: verifier,
+    });
+    if (typeof raw !== "object" || raw === null) {
+        throw new CliError("AUTH_ERROR", "invalid token response");
+    }
+    const record = raw;
+    if (typeof record.access_token !== "string" || record.access_token.length === 0) {
+        throw new CliError("AUTH_ERROR", "token response missing access_token");
+    }
+    return {
+        accessToken: record.access_token,
+        refreshToken: typeof record.refresh_token === "string" ? record.refresh_token : "",
+        expiresIn: typeof record.expires_in === "number" ? record.expires_in : 3600,
+        scope: typeof record.scope === "string" ? record.scope : "",
+    };
+}
+/**
+ * Start the callback server before opening the browser; validate state then
+ * exchange; store token only after all checks; close server in finally.
+ */
+export async function loginWithBrowser(config, deps) {
+    const active = startLoopbackCallbackServer({
+        host: "127.0.0.1",
+        port: 0,
+        path: config.redirectPath,
+        timeoutMs: 120_000,
+        ...(deps.signal ? { signal: deps.signal } : {}),
+    });
+    try {
+        const pkce = createPkcePair();
+        const loginState = createLoginState();
+        const url = buildAuthorizationUrl(config, { port: active.port, pkce, state: loginState });
+        let browserOpened = false;
+        try {
+            await deps.openBrowser(url);
+            browserOpened = true;
+        }
+        catch {
+            // browser-open failure is surfaced below regardless of browserOpened
+            throw new CliError("AUTH_ERROR", "failed to open the browser; please open the URL manually");
+        }
+        void browserOpened;
+        const callback = await active.outcome;
+        if (!callback.ok) {
+            throw new CliError(callback.code === "TIMEOUT" ? "NETWORK_ERROR" : "AUTH_ERROR", callback.message);
+        }
+        if (callback.value.state !== loginState.state) {
+            throw new CliError("AUTH_ERROR", "state mismatch in callback; possible CSRF");
+        }
+        return await exchangeAuthorizationCode(config, callback.value.code, pkce.verifier, deps);
+    }
+    finally {
+        active.stop();
+    }
+}
+/** SHA-256 hex of an API key for redaction/audit (never store the raw key). */
+export function hashApiKey(key) {
+    return createHash("sha256").update(key).digest("hex");
+}

package/dist/auth/open-browser.d.ts

@@ -0,0 +1,2 @@
+/** Open a trusted URL without invoking a shell. */
+export declare function openBrowser(url: string): Promise<void>;

package/dist/auth/open-browser.js

@@ -0,0 +1,15 @@
+import { spawn } from "node:child_process";
+import { CliError } from "../errors/index.js";
+/** Open a trusted URL without invoking a shell. */
+export function openBrowser(url) {
+    const parsed = new URL(url);
+    if (parsed.protocol !== "https:" && !(parsed.protocol === "http:" && parsed.hostname === "localhost")) {
+        return Promise.reject(new CliError("AUTH_ERROR", "refusing to open an untrusted browser URL"));
+    }
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "explorer.exe" : "xdg-open";
+    return new Promise((resolve, reject) => {
+        const child = spawn(command, [parsed.toString()], { detached: true, stdio: "ignore" });
+        child.once("error", () => reject(new CliError("AUTH_ERROR", "failed to open the browser")));
+        child.once("spawn", () => { child.unref(); resolve(); });
+    });
+}

package/dist/auth/pkce.d.ts

@@ -0,0 +1,17 @@
+/**
+ * PKCE: cryptographically random verifier and S256 challenge.
+ */
+export interface PkcePair {
+    readonly verifier: string;
+    readonly challenge: string;
+}
+/**
+ * Create a PKCE pair: 43-128 char verifier and S256 challenge.
+ */
+export declare function createPkcePair(): PkcePair;
+/** Login state (state + nonce) for a single active attempt. */
+export interface LoginState {
+    readonly state: string;
+    readonly nonce: string;
+}
+export declare function createLoginState(): LoginState;

package/dist/auth/pkce.js

@@ -0,0 +1,20 @@
+import { randomBytes, createHash } from "node:crypto";
+/** RFC 7636-compatible base64url without padding. */
+function base64Url(input) {
+    return Buffer.from(input).toString("base64url").replace(/=+$/, "");
+}
+/**
+ * Create a PKCE pair: 43-128 char verifier and S256 challenge.
+ */
+export function createPkcePair() {
+    const verifierBytes = randomBytes(32); // 43 base64url chars
+    const verifier = base64Url(verifierBytes);
+    const challenge = base64Url(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+export function createLoginState() {
+    return {
+        state: base64Url(randomBytes(24)),
+        nonce: base64Url(randomBytes(24)),
+    };
+}

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

@@ -0,0 +1,38 @@
+import { execFileSync } from "node:child_process";
+/**
+ * TokenStore: interface with OS keychain preferred, documented fallback with
+ * mode 0600. Stores refresh token + metadata; never logs tokens.
+ */
+export interface StoredSession {
+    readonly accountId: string;
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly expiresAt: number;
+    readonly scope: string;
+    readonly storedAt: number;
+}
+export interface TokenStore {
+    get(accountId: string): StoredSession | undefined;
+    getActive(): StoredSession | undefined;
+    set(session: StoredSession): void;
+    delete(accountId: string): void;
+    clear(): void;
+}
+/**
+ * File-backed fallback store (mode 0600). Used only when no OS keychain is
+ * available and the owner approves the fallback. Never logs token values.
+ */
+export declare function createFileTokenStore(options?: {
+    rootDir?: string;
+}): TokenStore;
+/** Use the native credential store when the platform provides a supported CLI. */
+export declare function createSystemTokenStore(options?: {
+    platform?: NodeJS.Platform;
+    execFile?: typeof execFileSync;
+}): TokenStore | undefined;
+/** Redact a session for logging: never expose tokens. */
+export declare function redactSession(session: StoredSession): {
+    accountId: string;
+    scope: string;
+    expiresAt: number;
+};