mcp-yoto 0.1.0

package/LICENSE

@@ -0,0 +1,23 @@
+MIT License
+
+Copyright (c) 2026 Dan Pillay
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Portions originally derived from bperkinspdx/yoto-mcp-server, Copyright (c) 2025 bperkinspdx, MIT License.

package/README.md

@@ -0,0 +1,86 @@
+# mcp-yoto
+
+MCP server for Yoto — connect your Yoto library (cards, tracks, pixel-art icons, family
+players) to Claude, Cursor, VS Code, and other MCP clients that run tools locally.
+
+This is the local, command-line connector. It runs on your own machine and signs in
+directly with Yoto — nothing about your account passes through anyone else's server.
+(A remote, paste-one-link connector for claude.ai / ChatGPT is on the way; see the
+[project README](https://github.com/danpillay87/mcp-yoto#readme) for the full story and
+current status.)
+
+## Install
+
+**Claude Code:**
+
+```
+claude mcp add yoto -- npx -y mcp-yoto
+```
+
+**Cursor:** click to install — this link is a base64-encoded copy of
+`{"command":"npx","args":["-y","mcp-yoto"]}`:
+
+[![Add to Cursor](https://img.shields.io/badge/Cursor-Add_yoto-000000)](cursor://anysphere.cursor-deeplink/mcp/install?name=yoto&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIm1jcC15b3RvIl19)
+
+**VS Code:**
+
+[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_yoto-0098FF)](vscode:mcp/install?%7B%22name%22%3A%22yoto%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22mcp-yoto%22%5D%7D)
+
+**Any other MCP client:** run `npx -y mcp-yoto` as a stdio server. There's nothing to
+configure beyond that — no API key, no account, no config file to hand-edit.
+
+## Sign in
+
+After adding the server, sign in once from a terminal:
+
+```
+npx mcp-yoto login
+```
+
+This opens your browser to **Yoto's own sign-in page**. Approve it there, then close the
+tab — you're done. Your AI client can now list your cards, add tracks, and so on by
+calling the `yoto_*` tools.
+
+Your Yoto credential is stored in your OS keychain (Windows Credential Manager, macOS
+Keychain, or the Linux Secret Service) when one is available, or in a plain file
+otherwise. Run `npx mcp-yoto status` any time to see which, and whether you're signed in.
+
+To disconnect: `npx mcp-yoto logout`.
+
+## Environment variables
+
+| Variable | Default | What it does |
+|---|---|---|
+| `YOTO_CLIENT_ID` | (the shared public dev-app id) | Use your own registered Yoto dev app instead. |
+| `YOTO_REDIRECT_PORT` | `8791` | Loopback port used during sign-in. Must match the redirect URI registered at Yoto — only change this if you've registered your own app on a different port. |
+| `YOTO_NO_BROWSER` | unset | Set to `1` to print the sign-in URL instead of opening a browser automatically (useful over SSH). |
+| `LOG_LEVEL` | `info` | `debug` \| `info` \| `warn` \| `error`. Everything goes to stderr — stdout is reserved for the MCP protocol itself. |
+| `MCP_YOTO_ICON_BASE` | GitHub-hosted icon set | Serve tool icons from somewhere else. |
+
+## Troubleshooting
+
+**"Port 8791 is already in use."** Something else is already listening on the loopback
+port sign-in needs. Close it, or set `YOTO_REDIRECT_PORT` to a free port — but only if
+you've also registered a matching redirect URI on your own Yoto dev app; the shared
+public client is fixed to 8791.
+
+**"System keychain unavailable — falling back to a local file."** Your OS has no
+usable keychain right now (common on a headless Linux box with no Secret Service
+running). This isn't fatal: your credential is written to a plain file instead, scoped
+to your user profile. `npx mcp-yoto status` always tells you which store is in use.
+
+**"Your Yoto session has expired." / a tool asks you to `yoto_sign_in`.** Your stored
+refresh token has been rejected by Yoto (it may have been revoked from your Yoto account
+settings, or simply expired). Run `npx mcp-yoto login` again.
+
+## What this connects to
+
+14 tools, all `yoto_*` — cards, tracks, icons, and read-only device status. Never asks
+for `family:devices:control` or `family:devices:manage`, so this stays eligible for
+Yoto's Verified listing. Full tool table, architecture, and privacy details:
+[github.com/danpillay87/mcp-yoto](https://github.com/danpillay87/mcp-yoto#readme).
+
+## License
+
+MIT — see [LICENSE](LICENSE). Originally derived from
+[bperkinspdx/yoto-mcp-server](https://github.com/bperkinspdx/yoto-mcp-server) (MIT).

package/bin/mcp-yoto.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { main } from "../dist/main.js";
+
+await main();

package/dist/auth/adapter.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The CLI's `AuthAdapter` (see @mcp-yoto/core's auth.ts): PKCE + loopback +
+ * OS keychain, wired together into the shape packages/core's tools expect.
+ * apps/worker implements the same interface completely differently (it
+ * never signs in locally at all -- see the plan's "remote mode" notes);
+ * neither app ever sees the other's implementation.
+ */
+import { type AuthAdapter, type Logger, type SignInResult } from "@mcp-yoto/core";
+import type { CliConfig } from "../config.js";
+import { type TokenStore } from "./token-store.js";
+export interface CreateCliAuthAdapterOptions {
+    config: CliConfig;
+    logger: Logger;
+    /** Injected for tests. */
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+}
+/** The `AuthAdapter` plus the underlying store, so `main.ts`'s `status`/`logout` subcommands can report its kind directly. */
+export interface CliAuthAdapter extends AuthAdapter {
+    readonly tokenStore: TokenStore;
+    /**
+     * Widens the base `AuthAdapter.signIn` opts with a CLI-only hook: called
+     * synchronously with the authorize URL as soon as it's built, before the
+     * loopback callback is ever awaited -- so a caller (main.ts's `login`
+     * command) can print it immediately instead of waiting for sign-in to
+     * finish. Optional and additive; the `yoto_sign_in` tool path never sets it.
+     */
+    signIn?(opts?: {
+        openBrowser?: boolean;
+        onAuthorizeUrl?: (url: string) => void;
+    }): Promise<SignInResult>;
+}
+export declare function createCliAuthAdapter(options: CreateCliAuthAdapterOptions): Promise<CliAuthAdapter>;

package/dist/auth/adapter.js

@@ -0,0 +1,131 @@
+/**
+ * The CLI's `AuthAdapter` (see @mcp-yoto/core's auth.ts): PKCE + loopback +
+ * OS keychain, wired together into the shape packages/core's tools expect.
+ * apps/worker implements the same interface completely differently (it
+ * never signs in locally at all -- see the plan's "remote mode" notes);
+ * neither app ever sees the other's implementation.
+ */
+import { YOTO_SCOPES, YotoError, } from "@mcp-yoto/core";
+import { awaitLoopbackCallback, LoopbackError } from "./loopback.js";
+import { openInBrowser } from "./open-browser.js";
+import { createPkcePair, createState } from "./pkce.js";
+import { decodeJwtExpMs, Session } from "./session.js";
+import { postTokenRequest } from "./token-exchange.js";
+import { createTokenStore } from "./token-store.js";
+function redirectUri(port) {
+    return `http://127.0.0.1:${port}/callback`;
+}
+function loopbackErrorToYotoError(error) {
+    if (error instanceof LoopbackError) {
+        if (error.code === "PORT_IN_USE") {
+            return new YotoError(error.message, { code: "PORT_IN_USE", hint: error.hint, cause: error });
+        }
+        if (error.code === "AUTH_TIMEOUT") {
+            return new YotoError(error.message, { code: "VALIDATION", hint: error.hint, cause: error });
+        }
+        return new YotoError(error.message, { code: "UPSTREAM_ERROR", hint: error.hint, cause: error });
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return new YotoError(message, { code: "UPSTREAM_ERROR", cause: error });
+}
+export async function createCliAuthAdapter(options) {
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const now = options.now ?? (() => Date.now());
+    const tokenStore = await createTokenStore({
+        account: options.config.clientId,
+        logger: options.logger,
+        fileOverride: options.config.tokenFileOverride,
+    });
+    const session = new Session({
+        config: { clientId: options.config.clientId, authBase: options.config.authBase },
+        tokenStore,
+        fetchImpl,
+        now,
+    });
+    async function signIn(opts) {
+        const { verifier, challenge } = createPkcePair();
+        const state = createState();
+        const port = options.config.redirectPort;
+        const authorizeUrl = new URL(`${options.config.authBase}/authorize`);
+        authorizeUrl.searchParams.set("audience", options.config.audience);
+        authorizeUrl.searchParams.set("scope", YOTO_SCOPES.join(" "));
+        authorizeUrl.searchParams.set("response_type", "code");
+        authorizeUrl.searchParams.set("client_id", options.config.clientId);
+        authorizeUrl.searchParams.set("code_challenge", challenge);
+        authorizeUrl.searchParams.set("code_challenge_method", "S256");
+        authorizeUrl.searchParams.set("redirect_uri", redirectUri(port));
+        authorizeUrl.searchParams.set("state", state);
+        const url = authorizeUrl.toString();
+        // Hand the URL to the caller synchronously, before anything below is
+        // awaited -- so a caller who wants to print it (main.ts's `login`
+        // command) can do so immediately, rather than waiting for the loopback
+        // callback to land. The URL carries only a PKCE challenge and a state
+        // nonce, both single-use and non-secret -- safe to print/log.
+        opts?.onAuthorizeUrl?.(url);
+        // Bind the loopback server BEFORE opening the browser -- a busy port
+        // must fail loud, not send the user to a callback URL nothing is
+        // listening on.
+        const callbackPromise = awaitLoopbackCallback({ port, expectedState: state });
+        const shouldOpenBrowser = (opts?.openBrowser ?? true) && !options.config.noBrowser;
+        if (shouldOpenBrowser)
+            openInBrowser(url);
+        let code;
+        try {
+            ({ code } = await callbackPromise);
+        }
+        catch (error) {
+            throw loopbackErrorToYotoError(error);
+        }
+        const result = await postTokenRequest(fetchImpl, `${options.config.authBase}/oauth/token`, {
+            grant_type: "authorization_code",
+            client_id: options.config.clientId,
+            code,
+            code_verifier: verifier,
+            redirect_uri: redirectUri(port),
+        });
+        if (!result.ok) {
+            throw new YotoError(`Yoto rejected the sign-in code (HTTP ${result.status}${result.error?.error ? `: ${result.error.error}` : ""}).`, { code: "UPSTREAM_ERROR", status: result.status });
+        }
+        await tokenStore.save({
+            accessToken: result.data.access_token,
+            refreshToken: result.data.refresh_token,
+            expiresAt: result.data.expires_in !== undefined ? now() + result.data.expires_in * 1000 : undefined,
+            scope: result.data.scope ?? YOTO_SCOPES.join(" "),
+        });
+        // ALWAYS return the URL, even after opening the browser automatically --
+        // if the browser didn't actually open (headless box, no default handler
+        // registered), the caller still has something to paste.
+        return { url, message: "Signed in to Yoto." };
+    }
+    async function signOut() {
+        await tokenStore.clear();
+    }
+    return {
+        mode: "cli",
+        tokenStore,
+        async getAccessToken() {
+            return session.getAccessToken();
+        },
+        async status() {
+            const stored = await tokenStore.load();
+            if (!stored) {
+                return {
+                    signedIn: false,
+                    mode: "cli",
+                    tokenStore: tokenStore.kind,
+                    hint: "Run yoto_sign_in to connect your Yoto account.",
+                };
+            }
+            const expiresAt = decodeJwtExpMs(stored.accessToken) ?? stored.expiresAt;
+            return {
+                signedIn: true,
+                mode: "cli",
+                tokenStore: tokenStore.kind,
+                expiresAt,
+                scopes: stored.scope ? stored.scope.split(" ") : undefined,
+            };
+        },
+        signIn,
+        signOut,
+    };
+}

package/dist/auth/loopback.d.ts

@@ -0,0 +1,28 @@
+/** Distinguishes the two CLI-only failure shapes from the shared `YotoErrorCode` union in packages/core. */
+export type LoopbackErrorCode = "PORT_IN_USE" | "AUTH_TIMEOUT" | "CALLBACK_ERROR";
+export declare class LoopbackError extends Error {
+    readonly code: LoopbackErrorCode;
+    readonly hint: string | undefined;
+    constructor(message: string, code: LoopbackErrorCode, hint?: string);
+}
+export interface LoopbackOptions {
+    port: number;
+    expectedState: string;
+    /** How long to wait for the callback before giving up. Default 300_000ms (300s). */
+    timeoutMs?: number;
+    /** Injected timer functions, for deterministic tests with fake timers. */
+    setTimeoutImpl?: typeof setTimeout;
+    clearTimeoutImpl?: typeof clearTimeout;
+}
+export interface LoopbackResult {
+    code: string;
+}
+/**
+ * Waits for the single OAuth callback this sign-in attempt expects.
+ *
+ * Binds the port before returning, so a caller can `await` this and only
+ * then open the browser / print the sign-in URL, confident the redirect has
+ * somewhere to land. Every exit path (success, state mismatch, upstream
+ * `error=`, bind failure, timeout) closes the server exactly once.
+ */
+export declare function awaitLoopbackCallback(options: LoopbackOptions): Promise<LoopbackResult>;

package/dist/auth/loopback.js

@@ -0,0 +1,103 @@
+/**
+ * The CLI's one-shot loopback HTTP server: binds `127.0.0.1:<port>` FIRST
+ * (so a busy port fails loud and fast, before the browser even opens),
+ * waits for exactly one `/callback` request carrying `state` + `code`, and
+ * always closes the server afterwards -- on success, on a state mismatch,
+ * on an upstream error, or on timeout.
+ */
+import { createServer } from "node:http";
+export class LoopbackError extends Error {
+    code;
+    hint;
+    constructor(message, code, hint) {
+        super(message);
+        this.name = "LoopbackError";
+        this.code = code;
+        this.hint = hint;
+    }
+}
+const SUCCESS_HTML = '<!doctype html><html><head><meta charset="utf-8"><title>Signed in to Yoto</title></head>' +
+    '<body style="font-family:system-ui,sans-serif;padding:3rem;max-width:32rem;margin:0 auto">' +
+    "<h1>You're signed in — you can close this tab.</h1>" +
+    "<p>Head back to your AI client -- mcp-yoto is ready.</p></body></html>";
+function failureHtml(message) {
+    return ('<!doctype html><html><head><meta charset="utf-8"><title>Sign-in failed</title></head>' +
+        '<body style="font-family:system-ui,sans-serif;padding:3rem;max-width:32rem;margin:0 auto">' +
+        "<h1>Sign-in failed</h1>" +
+        `<p>${escapeHtml(message)}</p></body></html>`);
+}
+const HTML_ESCAPES = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (ch) => HTML_ESCAPES[ch] ?? ch);
+}
+function sendHtml(res, status, body) {
+    res.writeHead(status, { "Content-Type": "text/html; charset=utf-8" });
+    res.end(body);
+}
+/**
+ * Waits for the single OAuth callback this sign-in attempt expects.
+ *
+ * Binds the port before returning, so a caller can `await` this and only
+ * then open the browser / print the sign-in URL, confident the redirect has
+ * somewhere to land. Every exit path (success, state mismatch, upstream
+ * `error=`, bind failure, timeout) closes the server exactly once.
+ */
+export function awaitLoopbackCallback(options) {
+    const timeoutMs = options.timeoutMs ?? 300_000;
+    const setTimeoutImpl = options.setTimeoutImpl ?? setTimeout;
+    const clearTimeoutImpl = options.clearTimeoutImpl ?? clearTimeout;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let timer;
+        const server = createServer(handleRequest);
+        function finish(action) {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeoutImpl(timer);
+            server.close();
+            action();
+        }
+        function handleRequest(req, res) {
+            const url = new URL(req.url ?? "/", `http://127.0.0.1:${options.port}`);
+            if (url.pathname !== "/callback") {
+                res.writeHead(404).end();
+                return;
+            }
+            const upstreamError = url.searchParams.get("error");
+            if (upstreamError) {
+                sendHtml(res, 200, failureHtml(`Yoto returned an error: ${upstreamError}`));
+                finish(() => reject(new LoopbackError(`Yoto returned an error during sign-in: ${upstreamError}`, "CALLBACK_ERROR")));
+                return;
+            }
+            const code = url.searchParams.get("code");
+            const state = url.searchParams.get("state");
+            if (!code || state !== options.expectedState) {
+                sendHtml(res, 400, failureHtml("This sign-in link is stale or was tampered with."));
+                finish(() => reject(new LoopbackError("Sign-in callback state did not match -- stale or invalid attempt.", "CALLBACK_ERROR", "Run yoto_sign_in again.")));
+                return;
+            }
+            sendHtml(res, 200, SUCCESS_HTML);
+            finish(() => resolve({ code }));
+        }
+        server.once("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                finish(() => reject(new LoopbackError(`Port ${options.port} is already in use.`, "PORT_IN_USE", "Set YOTO_REDIRECT_PORT to a free port that's also registered at Yoto, or close whatever's using it.")));
+                return;
+            }
+            finish(() => reject(new LoopbackError(err.message, "CALLBACK_ERROR")));
+        });
+        server.listen(options.port, "127.0.0.1", () => {
+            timer = setTimeoutImpl(() => {
+                finish(() => reject(new LoopbackError("Timed out waiting for the Yoto sign-in callback.", "AUTH_TIMEOUT", "Run yoto_sign_in again.")));
+            }, timeoutMs);
+        });
+    });
+}

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

@@ -0,0 +1 @@
+export declare function openInBrowser(url: string): void;

package/dist/auth/open-browser.js

@@ -0,0 +1,43 @@
+/**
+ * Best-effort cross-platform "open this URL in the default browser". Never
+ * throws: the sign-in URL is always returned/printed alongside this call
+ * too (see adapter.ts), so a headless box or a missing `xdg-open` degrades
+ * to "copy this link" rather than a hard failure.
+ */
+import { spawn } from "node:child_process";
+export function openInBrowser(url) {
+    try {
+        let child;
+        if (process.platform === "win32") {
+            // NOT `cmd /c start`: cmd.exe parses the command line itself, and it
+            // treats every unquoted `&` as a command separator -- an OAuth
+            // authorize URL is full of `&`-joined query params, so `cmd start`
+            // silently truncated the URL at the first `&` (client_id,
+            // redirect_uri, code_challenge, state all dropped) and Yoto's sign-in
+            // page rendered with no way to authenticate. `rundll32.exe
+            // url.dll,FileProtocolHandler <url>` hands the URL to the shell's own
+            // protocol handler with no cmd/shell parsing involved, so the URL
+            // reaches Edge byte-for-byte.
+            child = spawn("rundll32.exe", ["url.dll,FileProtocolHandler", url], {
+                shell: false,
+                detached: true,
+                stdio: "ignore",
+            });
+        }
+        else if (process.platform === "darwin") {
+            child = spawn("open", [url], { shell: false, detached: true, stdio: "ignore" });
+        }
+        else {
+            child = spawn("xdg-open", [url], { shell: false, detached: true, stdio: "ignore" });
+        }
+        // A missing binary (e.g. no xdg-open on a headless box) emits an async
+        // `error` event rather than throwing -- swallow it the same way as the
+        // synchronous catch below, since the URL is already on stderr for the
+        // user to click (see login's stderr contract in adapter.ts).
+        child.on("error", () => { });
+        child.unref();
+    }
+    catch {
+        // Best-effort only.
+    }
+}

package/dist/auth/pkce.d.ts

@@ -0,0 +1,10 @@
+/** RFC 7636 S256 `code_challenge` for a given `code_verifier`. Exported standalone for tests. */
+export declare function codeChallengeFromVerifier(verifier: string): string;
+export interface PkcePair {
+    verifier: string;
+    challenge: string;
+}
+/** A fresh PKCE pair: a 32-byte random verifier (well within RFC 7636's 43-128 char range), S256 challenge. */
+export declare function createPkcePair(): PkcePair;
+/** A single-use value correlating the loopback callback with the request that started it. */
+export declare function createState(): string;

package/dist/auth/pkce.js

@@ -0,0 +1,19 @@
+/**
+ * PKCE (RFC 7636) helpers for the CLI's loopback sign-in flow. Node-only
+ * (`node:crypto`) -- apps/cli is allowed node: imports, unlike
+ * packages/core, which stays fetch + WebCrypto only.
+ */
+import { createHash, randomBytes } from "node:crypto";
+/** RFC 7636 S256 `code_challenge` for a given `code_verifier`. Exported standalone for tests. */
+export function codeChallengeFromVerifier(verifier) {
+    return createHash("sha256").update(verifier).digest("base64url");
+}
+/** A fresh PKCE pair: a 32-byte random verifier (well within RFC 7636's 43-128 char range), S256 challenge. */
+export function createPkcePair() {
+    const verifier = randomBytes(32).toString("base64url");
+    return { verifier, challenge: codeChallengeFromVerifier(verifier) };
+}
+/** A single-use value correlating the loopback callback with the request that started it. */
+export function createState() {
+    return randomBytes(16).toString("base64url");
+}

package/dist/auth/session.d.ts

@@ -0,0 +1,37 @@
+import type { TokenStore } from "./token-store.js";
+export interface SessionConfig {
+    clientId: string;
+    authBase: string;
+}
+export interface SessionOptions {
+    config: SessionConfig;
+    tokenStore: TokenStore;
+    /** Injected for tests; defaults to `globalThis.fetch`. */
+    fetchImpl?: typeof fetch;
+    /** Injected clock, for deterministic early-refresh tests. Defaults to `Date.now`. */
+    now?: () => number;
+}
+/** Reads the `exp` claim (ms since epoch) out of a JWT's payload, unverified -- we trust it because Yoto issued it to us. */
+export declare function decodeJwtExpMs(token: string): number | undefined;
+/**
+ * Manages the CLI's single Yoto session (there is only ever one -- no
+ * multi-account support in this pass). One `Session` instance is created
+ * per process and shared by every tool call via the `AuthAdapter`.
+ */
+export declare class Session {
+    private readonly config;
+    private readonly tokenStore;
+    private readonly fetchImpl;
+    private readonly now;
+    private inFlightRefresh;
+    constructor(options: SessionOptions);
+    /**
+     * Returns a live access token, refreshing first if the current one is
+     * within 10 minutes of expiry (or the store carries no readable expiry
+     * at all, which fails safe by treating it as due for refresh).
+     */
+    getAccessToken(): Promise<string>;
+    /** Single-flight: concurrent callers share the one in-flight refresh instead of each starting their own. */
+    private refresh;
+    private doRefresh;
+}

package/dist/auth/session.js

@@ -0,0 +1,120 @@
+/**
+ * Turns a `TokenStore` into a live access token: reads the JWT's own `exp`
+ * claim and trusts it over whatever `expiresAt` was persisted (ported from
+ * the old yoto-mcp-server, which found a stored placeholder `expiresAt`
+ * making a perfectly live token look dead), refreshes 10 minutes early so a
+ * rejected refresh never leaves the caller with zero working credential,
+ * and collapses concurrent callers onto one in-flight refresh so three
+ * simultaneous tool calls never race Yoto's rotating refresh token against
+ * itself.
+ */
+import { YotoError } from "@mcp-yoto/core";
+import { postTokenRequest } from "./token-exchange.js";
+const REFRESH_SKEW_MS = 10 * 60 * 1000;
+/** Reads the `exp` claim (ms since epoch) out of a JWT's payload, unverified -- we trust it because Yoto issued it to us. */
+export function decodeJwtExpMs(token) {
+    const parts = token.split(".");
+    if (parts.length !== 3)
+        return undefined;
+    try {
+        const payloadJson = Buffer.from(parts[1] ?? "", "base64url").toString("utf-8");
+        const payload = JSON.parse(payloadJson);
+        return typeof payload.exp === "number" ? payload.exp * 1000 : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Manages the CLI's single Yoto session (there is only ever one -- no
+ * multi-account support in this pass). One `Session` instance is created
+ * per process and shared by every tool call via the `AuthAdapter`.
+ */
+export class Session {
+    config;
+    tokenStore;
+    fetchImpl;
+    now;
+    inFlightRefresh;
+    constructor(options) {
+        this.config = options.config;
+        this.tokenStore = options.tokenStore;
+        this.fetchImpl = options.fetchImpl ?? globalThis.fetch;
+        this.now = options.now ?? (() => Date.now());
+    }
+    /**
+     * Returns a live access token, refreshing first if the current one is
+     * within 10 minutes of expiry (or the store carries no readable expiry
+     * at all, which fails safe by treating it as due for refresh).
+     */
+    async getAccessToken() {
+        const stored = await this.tokenStore.load();
+        if (!stored) {
+            throw new YotoError("Not signed in to Yoto.", {
+                code: "NOT_AUTHENTICATED",
+                hint: "Run yoto_sign_in.",
+            });
+        }
+        const expiresAt = decodeJwtExpMs(stored.accessToken) ?? stored.expiresAt;
+        const now = this.now();
+        if (expiresAt !== undefined && expiresAt - REFRESH_SKEW_MS > now) {
+            return stored.accessToken;
+        }
+        if (!stored.refreshToken) {
+            // No refresh token on file: a live-but-soon-expiring token is still
+            // usable, but once it's actually dead there is nothing left to try.
+            if (expiresAt !== undefined && expiresAt > now)
+                return stored.accessToken;
+            throw new YotoError("Your Yoto session has expired.", {
+                code: "AUTH_EXPIRED",
+                hint: "Run yoto_sign_in.",
+            });
+        }
+        return this.refresh(stored.refreshToken);
+    }
+    /** Single-flight: concurrent callers share the one in-flight refresh instead of each starting their own. */
+    refresh(refreshToken) {
+        if (!this.inFlightRefresh) {
+            this.inFlightRefresh = this.doRefresh(refreshToken).finally(() => {
+                this.inFlightRefresh = undefined;
+            });
+        }
+        return this.inFlightRefresh;
+    }
+    async doRefresh(refreshToken) {
+        const result = await postTokenRequest(this.fetchImpl, `${this.config.authBase}/oauth/token`, {
+            grant_type: "refresh_token",
+            refresh_token: refreshToken,
+            client_id: this.config.clientId,
+        });
+        if (!result.ok) {
+            if (result.error?.error === "invalid_grant") {
+                // Yoto has already invalidated this refresh token server-side (it's
+                // rotating) -- there is nothing to retry. Clear the local store so
+                // yoto_status reports "not signed in" rather than a token we know is dead.
+                await this.tokenStore.clear();
+                throw new YotoError("Yoto rejected the stored refresh token.", {
+                    code: "AUTH_EXPIRED",
+                    hint: "Run yoto_sign_in.",
+                });
+            }
+            throw new YotoError(`Yoto token refresh failed (HTTP ${result.status}).`, {
+                code: "UPSTREAM_ERROR",
+                retryable: true,
+                status: result.status,
+            });
+        }
+        const data = result.data;
+        const newTokens = {
+            accessToken: data.access_token,
+            refreshToken: data.refresh_token ?? refreshToken,
+            expiresAt: data.expires_in !== undefined ? this.now() + data.expires_in * 1000 : undefined,
+            scope: data.scope,
+        };
+        // Persist BEFORE returning: if the process dies right after this call,
+        // the rotating refresh token Yoto just invalidated server-side must not
+        // be lost along with it -- the new one has to be on disk first.
+        await this.tokenStore.save(newTokens);
+        return newTokens.accessToken;
+    }
+}