mcp-yoto 0.1.0

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

@@ -0,0 +1,27 @@
+/**
+ * Thin wrapper around Yoto's `POST /oauth/token` endpoint, shared by both
+ * legs that call it: the authorization-code exchange (adapter.ts, once per
+ * sign-in) and the refresh-token grant (session.ts, on every access-token
+ * renewal). Kept deliberately dumb -- it does not interpret the response,
+ * just forwards it -- so the two callers can apply their own (different)
+ * error handling.
+ */
+export interface TokenResponse {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    scope?: string;
+}
+export interface TokenErrorBody {
+    error?: string;
+    error_description?: string;
+}
+export type TokenResult = {
+    ok: true;
+    data: TokenResponse;
+} | {
+    ok: false;
+    status: number;
+    error?: TokenErrorBody;
+};
+export declare function postTokenRequest(fetchImpl: typeof fetch, tokenUrl: string, params: Record<string, string>): Promise<TokenResult>;

package/dist/auth/token-exchange.js

@@ -0,0 +1,26 @@
+/**
+ * Thin wrapper around Yoto's `POST /oauth/token` endpoint, shared by both
+ * legs that call it: the authorization-code exchange (adapter.ts, once per
+ * sign-in) and the refresh-token grant (session.ts, on every access-token
+ * renewal). Kept deliberately dumb -- it does not interpret the response,
+ * just forwards it -- so the two callers can apply their own (different)
+ * error handling.
+ */
+export async function postTokenRequest(fetchImpl, tokenUrl, params) {
+    const response = await fetchImpl(tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams(params),
+    });
+    if (response.ok) {
+        return { ok: true, data: (await response.json()) };
+    }
+    let error;
+    try {
+        error = (await response.json());
+    }
+    catch {
+        // Non-JSON error body -- leave `error` undefined, callers fall back to the status code alone.
+    }
+    return { ok: false, status: response.status, error };
+}

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

@@ -0,0 +1,69 @@
+import type { Logger } from "@mcp-yoto/core";
+export interface StoredTokens {
+    accessToken: string;
+    refreshToken?: string;
+    /** Unix milliseconds. Belt-and-braces alongside the JWT's own `exp` claim -- see session.ts. */
+    expiresAt?: number;
+    /** Space-separated scopes Yoto actually granted. */
+    scope?: string;
+}
+export interface TokenStore {
+    readonly kind: "keychain" | "file";
+    load(): Promise<StoredTokens | undefined>;
+    save(tokens: StoredTokens): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * OS keychain-backed store (Windows Credential Manager / macOS Keychain /
+ * Secret Service on Linux) via `@napi-rs/keyring`.
+ *
+ * Imports the native module dynamically and lazily -- it's an
+ * `optionalDependency` (see apps/cli/package.json), so a platform with no
+ * prebuilt binding must still be able to `npm install` and run; the failure
+ * surfaces here, at first use, and `createTokenStore()` catches it.
+ */
+export declare class KeyringStore implements TokenStore {
+    private readonly account;
+    readonly kind: "keychain";
+    constructor(account: string);
+    private entry;
+    load(): Promise<StoredTokens | undefined>;
+    save(tokens: StoredTokens): Promise<void>;
+    clear(): Promise<void>;
+}
+/** `~/.config/mcp-yoto/tokens.json`, or on Windows `%APPDATA%\mcp-yoto\tokens.json`. */
+export declare function defaultTokenFilePath(): string;
+/**
+ * Plain-file fallback: crash-safe temp+rename writes with a `.last-good`
+ * backup (ported from the old yoto-mcp-server's config store), 0600
+ * permissions on POSIX (Windows ACLs already scope the file to the current
+ * user's profile), and BOM-tolerant reads (a PowerShell-written file often
+ * carries a UTF-8 BOM, which breaks a naive `JSON.parse`).
+ */
+export declare class FileStore implements TokenStore {
+    readonly kind: "file";
+    private readonly filePath;
+    constructor(filePath?: string);
+    load(): Promise<StoredTokens | undefined>;
+    private readFrom;
+    save(tokens: StoredTokens): Promise<void>;
+    clear(): Promise<void>;
+}
+export interface CreateTokenStoreOptions {
+    /** Keychain account name -- the client id, per the plan's "service mcp-yoto, account = client id". */
+    account: string;
+    logger: Logger;
+    /** Forces a `FileStore` at this exact path, skipping the keychain entirely. See config.ts's `tokenFileOverride`. */
+    fileOverride?: string;
+}
+/**
+ * Picks the token store for this run: the OS keychain when it works, a
+ * plain file (with one loud stderr warning, surfaced again in
+ * `yoto_status`) when it doesn't.
+ *
+ * The probe is `load()` itself: on a fresh machine with nothing stored yet,
+ * `getPassword()` resolves to `undefined` rather than throwing (see
+ * @napi-rs/keyring's own contract), so an empty-but-working keychain is
+ * correctly told apart from a broken one.
+ */
+export declare function createTokenStore(options: CreateTokenStoreOptions): Promise<TokenStore>;

package/dist/auth/token-store.js

@@ -0,0 +1,151 @@
+/**
+ * Where the CLI's Yoto credential lives at rest: the OS keychain by
+ * preference (`KeyringStore`, via `@napi-rs/keyring`), falling back to a
+ * plain file (`FileStore`) when the keychain is unusable (no native
+ * binding for this platform, a headless box with no keyring daemon, a
+ * locked session). `createTokenStore()` is the one entry point that makes
+ * that choice; everything else in this file is a plain, directly testable
+ * `TokenStore` implementation.
+ */
+import { chmod, copyFile, mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+const SERVICE = "mcp-yoto";
+/**
+ * OS keychain-backed store (Windows Credential Manager / macOS Keychain /
+ * Secret Service on Linux) via `@napi-rs/keyring`.
+ *
+ * Imports the native module dynamically and lazily -- it's an
+ * `optionalDependency` (see apps/cli/package.json), so a platform with no
+ * prebuilt binding must still be able to `npm install` and run; the failure
+ * surfaces here, at first use, and `createTokenStore()` catches it.
+ */
+export class KeyringStore {
+    account;
+    kind = "keychain";
+    constructor(account) {
+        this.account = account;
+    }
+    async entry() {
+        const { AsyncEntry } = await import("@napi-rs/keyring");
+        return new AsyncEntry(SERVICE, this.account);
+    }
+    async load() {
+        const entry = await this.entry();
+        const raw = await entry.getPassword();
+        if (!raw)
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async save(tokens) {
+        const entry = await this.entry();
+        await entry.setPassword(JSON.stringify(tokens));
+    }
+    async clear() {
+        const entry = await this.entry();
+        await entry.deletePassword();
+    }
+}
+/** `~/.config/mcp-yoto/tokens.json`, or on Windows `%APPDATA%\mcp-yoto\tokens.json`. */
+export function defaultTokenFilePath() {
+    if (process.platform === "win32") {
+        const appData = process.env.APPDATA || join(homedir(), "AppData", "Roaming");
+        return join(appData, "mcp-yoto", "tokens.json");
+    }
+    return join(homedir(), ".config", "mcp-yoto", "tokens.json");
+}
+/**
+ * Plain-file fallback: crash-safe temp+rename writes with a `.last-good`
+ * backup (ported from the old yoto-mcp-server's config store), 0600
+ * permissions on POSIX (Windows ACLs already scope the file to the current
+ * user's profile), and BOM-tolerant reads (a PowerShell-written file often
+ * carries a UTF-8 BOM, which breaks a naive `JSON.parse`).
+ */
+export class FileStore {
+    kind = "file";
+    filePath;
+    constructor(filePath = defaultTokenFilePath()) {
+        this.filePath = filePath;
+    }
+    async load() {
+        const primary = await this.readFrom(this.filePath);
+        if (primary)
+            return primary;
+        // The main file is missing or corrupt (e.g. a crash mid-write left a
+        // truncated .tmp that never got renamed, or a partial write slipped
+        // through) -- recover from the last file we know was ever written cleanly.
+        return this.readFrom(`${this.filePath}.last-good`);
+    }
+    async readFrom(path) {
+        let raw;
+        try {
+            raw = await readFile(path, "utf-8");
+        }
+        catch {
+            return undefined;
+        }
+        const stripped = raw.replace(/^/, "");
+        try {
+            return JSON.parse(stripped);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async save(tokens) {
+        await mkdir(dirname(this.filePath), { recursive: true });
+        try {
+            await copyFile(this.filePath, `${this.filePath}.last-good`);
+        }
+        catch {
+            // No existing file yet -- this is the first sign-in.
+        }
+        const tmp = `${this.filePath}.tmp`;
+        await writeFile(tmp, JSON.stringify(tokens, null, 2), "utf-8");
+        await rename(tmp, this.filePath);
+        if (process.platform !== "win32") {
+            await chmod(this.filePath, 0o600);
+        }
+    }
+    async clear() {
+        for (const path of [this.filePath, `${this.filePath}.last-good`, `${this.filePath}.tmp`]) {
+            try {
+                await rm(path);
+            }
+            catch {
+                // Already gone -- clearing an already-signed-out store is not an error.
+            }
+        }
+    }
+}
+/**
+ * Picks the token store for this run: the OS keychain when it works, a
+ * plain file (with one loud stderr warning, surfaced again in
+ * `yoto_status`) when it doesn't.
+ *
+ * The probe is `load()` itself: on a fresh machine with nothing stored yet,
+ * `getPassword()` resolves to `undefined` rather than throwing (see
+ * @napi-rs/keyring's own contract), so an empty-but-working keychain is
+ * correctly told apart from a broken one.
+ */
+export async function createTokenStore(options) {
+    if (options.fileOverride) {
+        return new FileStore(options.fileOverride);
+    }
+    try {
+        const keyring = new KeyringStore(options.account);
+        await keyring.load();
+        return keyring;
+    }
+    catch (error) {
+        const filePath = defaultTokenFilePath();
+        options.logger.warn(`System keychain unavailable -- falling back to a local file at ${filePath} ` +
+            "(0600 permissions on macOS/Linux; scoped to your Windows user profile).", { error: error instanceof Error ? error.message : String(error) });
+        return new FileStore(filePath);
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Yoto's public PKCE client for the CLI's existing dev app -- safe to ship
+ * in source (no client secret; PKCE is the confidentiality mechanism).
+ * Overridable via YOTO_CLIENT_ID for anyone running their own registered
+ * Yoto dev app.
+ */
+export declare const DEFAULT_CLIENT_ID = "xl4YsMpHEMnn7ubVhsRu8NhBwfUFPf8J";
+export declare const YOTO_AUTH_BASE = "https://login.yotoplay.com";
+export declare const AUDIENCE = "https://api.yotoplay.com";
+export declare const DEFAULT_REDIRECT_PORT = 8791;
+export declare const DEFAULT_ICON_BASE_URL = "https://raw.githubusercontent.com/danpillay87/mcp-yoto/main/apps/worker/public/icons";
+export type LogLevel = "debug" | "info" | "warn" | "error";
+export interface CliConfig {
+    clientId: string;
+    authBase: string;
+    audience: string;
+    /** Loopback port for PKCE sign-in. Must match the redirect URI registered at Yoto. */
+    redirectPort: number;
+    /** True when YOTO_NO_BROWSER is set -- print the sign-in URL instead of opening a browser. */
+    noBrowser: boolean;
+    logLevel: LogLevel;
+    iconBaseUrl: string;
+    /** Space-joined scopes this connection ever requests. Never devices:control/manage. */
+    scope: string;
+    /**
+     * Advanced/testing override: forces the token store to a plain file at this
+     * path, skipping the OS keychain entirely. Used by the stdio-purity test to
+     * sandbox credential storage in a temp directory without touching a real
+     * keychain or `~/.config/mcp-yoto`. Not documented as a normal user-facing
+     * knob (see README's env var table), but harmless to set by hand too.
+     */
+    tokenFileOverride?: string;
+}
+/** Reads and validates configuration from `env` (defaults to `process.env`). */
+export declare function loadConfig(env?: NodeJS.ProcessEnv): CliConfig;

package/dist/config.js

@@ -0,0 +1,51 @@
+/**
+ * Configuration for the `npx mcp-yoto` CLI, read from `process.env`.
+ *
+ * This is the ONE place in apps/cli that touches `process.env` directly --
+ * every other module takes an explicit value (a `CliConfig`, a clock, a
+ * `fetchImpl`) so it stays trivially testable without mutating globals.
+ *
+ * Mirrors apps/worker's config.ts decisions (same Yoto auth base, same
+ * scope list) but is CLI-only: no KV, no OAuthProvider, no `Env` binding.
+ */
+import { YOTO_SCOPES } from "@mcp-yoto/core";
+/**
+ * Yoto's public PKCE client for the CLI's existing dev app -- safe to ship
+ * in source (no client secret; PKCE is the confidentiality mechanism).
+ * Overridable via YOTO_CLIENT_ID for anyone running their own registered
+ * Yoto dev app.
+ */
+export const DEFAULT_CLIENT_ID = "xl4YsMpHEMnn7ubVhsRu8NhBwfUFPf8J";
+export const YOTO_AUTH_BASE = "https://login.yotoplay.com";
+export const AUDIENCE = "https://api.yotoplay.com";
+export const DEFAULT_REDIRECT_PORT = 8791;
+export const DEFAULT_ICON_BASE_URL = "https://raw.githubusercontent.com/danpillay87/mcp-yoto/main/apps/worker/public/icons";
+function parsePort(raw, fallback) {
+    if (!raw)
+        return fallback;
+    const parsed = Number(raw);
+    if (!Number.isInteger(parsed) || parsed <= 0 || parsed > 65535) {
+        throw new Error(`YOTO_REDIRECT_PORT must be an integer between 1 and 65535, got ${JSON.stringify(raw)}.`);
+    }
+    return parsed;
+}
+function parseLogLevel(raw) {
+    return raw === "debug" || raw === "warn" || raw === "error" ? raw : "info";
+}
+function parseBoolFlag(raw) {
+    return raw === "1" || raw?.toLowerCase() === "true";
+}
+/** Reads and validates configuration from `env` (defaults to `process.env`). */
+export function loadConfig(env = process.env) {
+    return {
+        clientId: env.YOTO_CLIENT_ID || DEFAULT_CLIENT_ID,
+        authBase: YOTO_AUTH_BASE,
+        audience: AUDIENCE,
+        redirectPort: parsePort(env.YOTO_REDIRECT_PORT, DEFAULT_REDIRECT_PORT),
+        noBrowser: parseBoolFlag(env.YOTO_NO_BROWSER),
+        logLevel: parseLogLevel(env.LOG_LEVEL),
+        iconBaseUrl: env.MCP_YOTO_ICON_BASE || DEFAULT_ICON_BASE_URL,
+        scope: YOTO_SCOPES.join(" "),
+        tokenFileOverride: env.MCP_YOTO_TOKEN_FILE || undefined,
+    };
+}

package/dist/main.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `npx mcp-yoto` entrypoint (invoked via bin/mcp-yoto.mjs).
+ *
+ * stdout is reserved for JSON-RPC frames when running as an MCP server
+ * (the default, no-subcommand mode) -- every diagnostic goes to stderr.
+ * `status` is the one deliberate exception: it prints its `AuthStatus` JSON
+ * to stdout, because it's meant to be piped/parsed by a human or script
+ * checking sign-in state, not read by an MCP client. See test/stdio-purity.test.ts.
+ */
+import { DEFAULT_CLIENT_ID } from "./config.js";
+export { DEFAULT_CLIENT_ID };
+export declare function main(argv?: string[]): Promise<void>;