omp-figma-remote-auth 0.1.1

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 DianP
+Copyright (c) 2026 omp-figma-remote-auth contributors
+
+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.

package/README.md

@@ -0,0 +1,109 @@
+# omp-figma-remote-auth
+
+[简体中文](README.zh-CN.md)
+
+An unofficial [Oh My Pi (OMP)](https://github.com/can1357/oh-my-pi) plugin for authenticating with the official Figma Remote MCP server at `https://mcp.figma.com/mcp`. It configures the `figma` server and performs browser OAuth login; OMP provides native MCP transport, tool discovery, and token refresh. This project is not affiliated with or endorsed by Figma or OpenAI.
+
+## Requirements
+
+- OMP **18.1.17 is the currently verified version**. Use 18.1.17+; compatibility with future releases is not guaranteed.
+- Git, a Figma account with access to the intended files, and a browser on the same machine as OMP for the local OAuth callback. Figma Desktop is not required.
+- Zero runtime package dependencies. No `pi-mcp-adapter`, `npm install`, or build step is needed. Development tests require Node.js 22.6.0+ and npm.
+
+## Install and connect
+
+Run this command in your **terminal (CLI)** to install from npm:
+
+```sh
+omp install omp-figma-remote-auth
+```
+
+Restart OMP, or enter `/reload-plugins` in an existing OMP session. No source checkout or separate `npm install -g` is required.
+
+To develop the plugin or install from source instead:
+
+```sh
+git clone https://github.com/picasuo/omp-figma-remote-auth.git
+omp plugin link ./omp-figma-remote-auth
+```
+
+For a source installation, keep the cloned directory in place: OMP links to it. Restart OMP or run `/reload-plugins` after linking.
+
+The following are **slash commands inside OMP's interactive interface (TUI)**, not shell commands. Start OMP with `omp` if needed, then run:
+
+```text
+/figma-remote-auth setup
+/figma-remote-auth login
+```
+
+`setup` configures the server without logging in. It is optional here because `login` runs setup automatically.
+
+Open the displayed authorization URL manually in a browser on the same machine. With the default settings, Figma's consent page shows **Codex** as the application name; see the authentication explanation below. Approve access, keep OMP running for the callback to `http://127.0.0.1:<port>/callback`, and return to OMP to confirm that authorization was saved. The browser receiving the code alone does not confirm that token exchange succeeded.
+
+After OMP confirms success, run these TUI commands:
+
+```text
+/mcp reload
+/mcp test figma
+```
+
+You can then ask OMP to use Figma tools with a Figma file or node URL you can access.
+
+## Commands
+
+All commands in this table run in the OMP TUI.
+
+| Command | Purpose |
+| --- | --- |
+| `/figma-remote-auth help` | Show usage; also the default with no subcommand. |
+| `/figma-remote-auth setup` | Add or merge the native `figma` HTTP MCP configuration. |
+| `/figma-remote-auth login` | Run setup, dynamically register a client, and display the browser authorization link. |
+| `/figma-remote-auth status` | Check local configuration, credential presence/expiry, and any active operation; this is not a live connection test. |
+| `/figma-remote-auth logout` | Delete only this plugin's credential for the active profile; keep the MCP configuration. |
+| `/figma-remote-auth cancel` | Cancel the pending authorization and close its callback listener. |
+
+`login` accepts `--client-name` (default `Codex`, 1–128 printable characters, not blank) and `--port` (default `0`, which lets the OS choose an available port; valid range 0–65535). For example:
+
+```text
+/figma-remote-auth login --client-name Codex --port 19876
+```
+
+Quote names containing spaces. A different client name may be rejected by Figma. Login times out after 10 minutes; `cancel` or exiting OMP also stops the wait. Run `/mcp reload` after setup, login, or logout so OMP picks up the change.
+
+## Authentication, profiles, and limits
+
+Each login sends `client_name: Codex` by default to Figma's dynamic client registration endpoint and receives a **new `client_id`**. It then uses the OAuth authorization code flow with PKCE S256 and state validation. It does not reuse or steal an existing Codex client ID, secret, or account token. The display name does not make this an official Codex integration. This is a compatibility workaround for Figma's client acceptance policy; Figma may change registration rules or endpoints and stop accepting it. See Figma's [client access policy](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/#which-mcp-clients-are-supported).
+
+Setup writes to the **active OMP agent directory's `mcp.json`** (normally `~/.omp/agent/mcp.json`). With `omp --profile <name>`, perform setup, login, status, and logout in that same profile. Credential IDs are derived from the active agent directory and Figma endpoint, so authentication is not automatically shared between profiles. The plugin does not write project-local MCP configuration.
+
+Access/refresh tokens and client registration data are saved through **OMP's native AuthStorage**. The `mcp.json` entry contains the server URL, transport type, and an OAuth `credentialId` reference, not the tokens. OMP handles subsequent token refresh.
+
+Figma's [official rate limits and access documentation](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/) currently gives Starter users **up to 20 calls per month for tools that read data from Figma**, with some tools exempt. Limits depend on plan and seat, can change, and do not replace file permissions. This plugin does not increase or bypass quotas.
+
+## Troubleshooting
+
+- **Unknown slash command:** check `omp plugin list` in the terminal, then restart OMP or run `/reload-plugins`. Use `/figma-remote-auth ...` in the TUI; there is no `omp figma-remote-auth` CLI command. `/mcp ...` commands also belong in the TUI.
+- **Existing configuration conflict:** setup refuses to overwrite a conflicting `mcpServers.figma` entry. Back up the active agent directory's `mcp.json`, then inspect that entry for a different URL/type, an `Authorization` header, another `auth` source, or old transport/token options such as `command`, `args`, `env`, or `oauth`. If migrating, remove or rename the obsolete entry after reviewing it, then rerun setup/login. Preserve unrelated servers. Also check project MCP configurations if OMP still resolves a different `figma` server. A credential ownership conflict requires resolving the other authentication source; the plugin will not overwrite it.
+- **Browser callback fails or login stalls:** keep the browser and OMP on the same machine; a browser on your laptop cannot directly reach a remote SSH/container loopback listener. Check local port access, cancel the attempt, and retry with `--port 0` or an available fixed port. A failed login may leave setup in place without a saved credential.
+- **Authentication still fails:** run `/figma-remote-auth status`, log in again with `/figma-remote-auth login`, then `/mcp reload` and `/mcp test figma`. OMP's `/mcp reauth figma` is its own generic OAuth flow; it does **not** invoke this plugin's login or its client-name registration behavior.
+- **Permission or quota errors:** check the authorized Figma account, file access, plan, and seat against the official limits above; logging in again does not add quota.
+
+## Logout and uninstall
+
+Installing or linking the plugin does not log you in. Uninstalling it does not automatically clear credentials or remove the `figma` MCP configuration.
+
+For credential cleanup, run `/figma-remote-auth logout` and `/mcp reload` in each profile you authorized **before uninstalling**. Logout deletes the local credential only; it does **not revoke the server-side authorization at Figma**. To revoke that authorization, remove the corresponding app authorization in your Figma account settings.
+
+Uninstall from the terminal:
+
+```sh
+omp plugin uninstall omp-figma-remote-auth
+```
+
+Restart OMP or run `/reload-plugins`. If you also want to remove the server, delete only its `mcpServers.figma` entry from the relevant `mcp.json` and run `/mcp reload`. You can delete the clone after unlinking/uninstalling it. If already uninstalled, link it again to use logout in the original profile.
+
+## Development and credits
+
+From the repository directory, run `npm test`. Tests use Node's built-in test runner and need no `npm install`. `npm publish` runs the tests through `prepublishOnly` and publishes to the official npm registry. The package's `files` allowlist includes only the runtime source, documentation, and license.
+
+[MIT licensed](LICENSE), with copyright notices for DianP and the omp-figma-remote-auth contributors. Adapted for OMP from [DianP/pi-figma-remote-auth](https://github.com/DianP/pi-figma-remote-auth). Thanks also to [sdaoudi/mcp-auth-helper](https://github.com/sdaoudi/mcp-auth-helper), which the original project referenced for the authentication approach.

package/README.zh-CN.md

@@ -0,0 +1,109 @@
+# omp-figma-remote-auth
+
+[English](README.md)
+
+用于登录 Figma 官方远程 MCP 服务 `https://mcp.figma.com/mcp` 的非官方 [Oh My Pi（OMP）](https://github.com/can1357/oh-my-pi) 插件。它配置 `figma` 服务并完成浏览器 OAuth 登录，由 OMP 原生负责 MCP 传输、工具发现和令牌刷新。本项目与 Figma、OpenAI 无隶属关系，也未获其官方背书。
+
+## 使用要求
+
+- **OMP 18.1.17 是目前验证过的版本**。建议使用 18.1.17+，但不保证未来版本兼容。
+- Git、拥有目标文件访问权限的 Figma 账号，以及与 OMP 运行在同一台机器上的浏览器，用于接收本地 OAuth 回调。无需 Figma 桌面客户端。
+- 零运行时包依赖，无需 `pi-mcp-adapter`、`npm install` 或构建。开发测试需要 Node.js 22.6.0+ 和 npm。
+
+## 安装与连接
+
+在**终端（CLI）**中执行以下命令，从 npm 安装：
+
+```sh
+omp install omp-figma-remote-auth
+```
+
+重启 OMP，或在已有 OMP 会话中输入 `/reload-plugins`。无需克隆源码，也无需额外执行 `npm install -g`。
+
+如需开发插件或从源码安装：
+
+```sh
+git clone https://github.com/picasuo/omp-figma-remote-auth.git
+omp plugin link ./omp-figma-remote-auth
+```
+
+源码安装需要保留克隆目录的位置，OMP 会链接到该目录。链接后重启 OMP 或运行 `/reload-plugins`。
+
+以下是 **OMP 交互界面（TUI）中的斜杠命令**，不能直接在 shell 中运行。需要时先用 `omp` 启动 OMP，然后执行：
+
+```text
+/figma-remote-auth setup
+/figma-remote-auth login
+```
+
+`setup` 只配置服务，不登录。此处可以省略，因为 `login` 会自动执行 setup。
+
+在同一台机器的浏览器中手动打开输出的授权链接。默认设置下，Figma 授权页显示的应用名称是 **Codex**，原因见下方认证机制说明。确认授权并保持 OMP 运行，浏览器会回调 `http://127.0.0.1:<port>/callback`。返回 OMP 确认凭据已保存；浏览器收到授权码并不代表令牌交换已经成功。
+
+OMP 提示成功后，在 TUI 中执行：
+
+```text
+/mcp reload
+/mcp test figma
+```
+
+随后可向 OMP 提供自己有权限访问的 Figma 文件或节点链接，让它使用 Figma 工具。
+
+## 命令
+
+下表所有命令均在 OMP TUI 中执行。
+
+| 命令 | 用途 |
+| --- | --- |
+| `/figma-remote-auth help` | 查看帮助；不带子命令时也会显示帮助。 |
+| `/figma-remote-auth setup` | 添加或合并原生 `figma` HTTP MCP 配置。 |
+| `/figma-remote-auth login` | 自动 setup、动态注册客户端，并显示浏览器授权链接。 |
+| `/figma-remote-auth status` | 检查本地配置、凭据是否存在及到期时间、当前操作状态；不进行实际连接测试。 |
+| `/figma-remote-auth logout` | 仅删除当前 profile 中属于本插件的凭据，保留 MCP 配置。 |
+| `/figma-remote-auth cancel` | 取消正在等待的授权，关闭回调监听。 |
+
+`login` 支持 `--client-name`（默认 `Codex`，1–128 个可打印字符，不能全为空白）与 `--port`（默认 `0`，由操作系统选择可用端口；有效范围为 0–65535）。例如：
+
+```text
+/figma-remote-auth login --client-name Codex --port 19876
+```
+
+含空格的名称需加引号。Figma 可能拒绝其他客户端名称。登录会在 10 分钟后超时；执行 `cancel` 或退出 OMP 也会结束等待。setup、login 或 logout 后均应运行 `/mcp reload`，使 OMP 加载变更。
+
+## 认证机制、profile 与限额
+
+每次登录默认向 Figma 动态客户端注册端点发送 `client_name: Codex`，获取一个**新的 `client_id`**，再通过带 PKCE S256 和 state 校验的 OAuth 授权码流程登录。插件不会复用或偷用已有 Codex 的客户端 ID、密钥或账号令牌。显示名称也不代表这是官方 Codex 集成。这是针对 Figma 客户端准入策略的兼容方案；Figma 可能修改注册规则或端点，使其失效。参见 Figma 的[客户端访问策略](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/#which-mcp-clients-are-supported)。
+
+Setup 写入**当前 OMP agent 目录下的 `mcp.json`**（通常为 `~/.omp/agent/mcp.json`）。使用 `omp --profile <name>` 时，应在同一个 profile 中执行 setup、login、status 和 logout。凭据 ID 根据当前 agent 目录和 Figma 端点生成，因此各 profile 不会自动共享登录状态。插件不写入项目级 MCP 配置。
+
+访问令牌、刷新令牌及客户端注册信息通过 **OMP 原生 AuthStorage** 保存。`mcp.json` 中仅保存服务 URL、传输类型和 OAuth `credentialId` 引用，不保存令牌。后续令牌刷新由 OMP 处理。
+
+Figma 的[官方限额与访问说明](https://developers.figma.com/docs/figma-mcp-server/rate-limits-access/)目前规定：Starter 用户对**从 Figma 读取数据的工具，每月最多调用 20 次**，部分工具不计入该限额。额度取决于套餐和席位，可能变更，且不替代文件访问权限。本插件不会增加或绕过额度。
+
+## 常见问题
+
+- **找不到斜杠命令：**在终端用 `omp plugin list` 检查插件，再重启 OMP 或运行 `/reload-plugins`。`/figma-remote-auth ...` 应在 TUI 中输入，不存在 `omp figma-remote-auth` CLI 命令。`/mcp ...` 同样属于 TUI 命令。
+- **已有配置冲突：**setup 不会覆盖有冲突的 `mcpServers.figma`。先备份当前 agent 目录的 `mcp.json`，检查该条目是否存在不同的 URL/type、`Authorization` 请求头、其他 `auth` 来源，或 `command`、`args`、`env`、`oauth` 等旧传输或令牌选项。迁移时，确认后删除或重命名旧条目，再执行 setup/login，保留其他服务。如果 OMP 仍加载了另一个 `figma` 服务，还需检查项目级 MCP 配置。若提示凭据归属冲突，应先解决其他认证来源的占用，插件不会覆盖它。
+- **浏览器回调失败或一直等待：**浏览器和 OMP 应运行在同一台机器上；笔记本浏览器无法直接连接远程 SSH 主机或容器的回环监听。检查本地端口访问，取消当前操作后用 `--port 0` 或一个可用的固定端口重试。登录失败后，setup 配置可能已写入，但凭据尚未保存。
+- **仍然认证失败：**运行 `/figma-remote-auth status`，用 `/figma-remote-auth login` 重新登录，然后执行 `/mcp reload` 与 `/mcp test figma`。OMP 的 `/mcp reauth figma` 走其自身通用 OAuth 流程，**不会调用本插件的 login，也不会使用本插件的客户端名称注册逻辑**。
+- **权限或额度错误：**检查授权的 Figma 账号、文件权限、套餐和席位，并参照上方官方限额；重新登录不会增加额度。
+
+## 退出登录与卸载
+
+安装或链接插件不会自动登录；卸载插件也不会自动清除凭据或删除 `figma` MCP 配置。
+
+如需清理凭据，请在**卸载前**进入每个曾授权的 profile，执行 `/figma-remote-auth logout` 和 `/mcp reload`。Logout 仅删除本地凭据，**不会撤销 Figma 服务器端授权**。如需撤销，请在 Figma 账号设置中移除对应应用的授权。
+
+在终端执行卸载：
+
+```sh
+omp plugin uninstall omp-figma-remote-auth
+```
+
+重启 OMP 或运行 `/reload-plugins`。如需同时删除服务，仅从对应的 `mcp.json` 中删除 `mcpServers.figma` 条目，再运行 `/mcp reload`。解除链接或卸载后可以删除克隆目录。如果已经卸载，可重新链接插件，再进入原 profile 执行 logout。
+
+## 开发与致谢
+
+在仓库目录执行 `npm test`。测试使用 Node 内置测试运行器，无需 `npm install`。`npm publish` 会通过 `prepublishOnly` 运行测试，并发布到 npm 官方仓库。包的 `files` 白名单仅包含运行源码、文档和许可证。
+
+本项目采用 [MIT 许可证](LICENSE)，保留 DianP 与 omp-figma-remote-auth contributors 的版权声明。由 [DianP/pi-figma-remote-auth](https://github.com/DianP/pi-figma-remote-auth) 适配到 OMP。同时感谢 [sdaoudi/mcp-auth-helper](https://github.com/sdaoudi/mcp-auth-helper)，原项目曾参考其认证思路。

package/index.ts

@@ -0,0 +1,120 @@
+import { COMMAND_NAME, FIGMA_URL, UserError, formatError, helpText, parseArgs } from "./src/args.ts";
+import { configStatus, setupConfig } from "./src/config.ts";
+import { runOAuthFlow } from "./src/oauth.ts";
+import type { FlowOptions, OAuthGrant } from "./src/oauth.ts";
+import { credentialIdFor, credentialStatus, logout, ownedCredential, saveCredential } from "./src/storage.ts";
+import type { AuthStorage } from "./src/storage.ts";
+
+/** Minimal structural interface; OMP supplies all runtime services, no SDK dependency. */
+export interface CommandContext {
+  signal?: AbortSignal;
+  modelRegistry: { authStorage: AuthStorage };
+  ui: {
+    notify(message: string, level: "info" | "error"): void;
+    setStatus?(key: string, message: string | undefined): void;
+  };
+}
+export interface ExtensionAPI {
+  pi: { getAgentDir(): string };
+  registerCommand(name: string, command: {
+    description: string;
+    handler(args: string, ctx: CommandContext): Promise<void>;
+  }): void;
+  on(event: "session_shutdown", handler: () => void | Promise<void>): void;
+}
+export interface Dependencies {
+  runOAuth?: (options: FlowOptions) => Promise<OAuthGrant>;
+}
+// One active mutation across extension instances in this process, including during a reload.
+let active: { controller: AbortController; done: Promise<void> } | undefined;
+
+export default function figmaRemoteAuthExtension(pi: ExtensionAPI): void {
+  registerExtension(pi);
+}
+export function registerExtension(pi: ExtensionAPI, dependencies: Dependencies = {}): void {
+  let shuttingDown = false;
+  pi.on("session_shutdown", async () => {
+    shuttingDown = true;
+    const pending = active;
+    pending?.controller.abort();
+    await pending?.done;
+  });
+  pi.registerCommand(COMMAND_NAME, {
+    description: "Authenticate official Figma Remote MCP using OMP native transport and refresh",
+    handler: async (args, ctx) => {
+      let finish: (() => void) | undefined;
+      let cancel: (() => void) | undefined;
+      let operation: typeof active;
+      try {
+        const command = parseArgs(args);
+        if (command.kind === "help") { ctx.ui.notify(helpText(), "info"); return; }
+        if (command.kind === "cancel") {
+          const pending = active;
+          pending?.controller.abort();
+          await pending?.done;
+          ctx.ui.notify(pending ? "Figma authorization cancelled." : "No Figma authorization is running.", "info");
+          return;
+        }
+        if (shuttingDown) throw new UserError("OMP is shutting down; authentication is unavailable.");
+        const agentDir = pi.pi.getAgentDir();
+        const credentialId = credentialIdFor(agentDir);
+        const storage = ctx.modelRegistry.authStorage;
+        if (command.kind === "status") {
+          const config = configStatus(agentDir, credentialId);
+          ctx.ui.notify([
+            `Figma Remote MCP: ${FIGMA_URL}`,
+            `Config: ${config.configured ? "configured" : "setup required"}.`,
+            credentialStatus(storage, credentialId),
+            `Authorization: ${active ? "operation in progress" : "idle"}.`,
+          ].join("\n"), "info");
+          return;
+        }
+        if (active) throw new UserError("A Figma authentication operation is already running. Cancel it before starting another.");
+        const controller = new AbortController();
+        const done = new Promise<void>(resolve => { finish = resolve; });
+        operation = { controller, done };
+        active = operation;
+        cancel = () => controller.abort();
+        ctx.signal?.addEventListener("abort", cancel, { once: true });
+        if (ctx.signal?.aborted) cancel();
+        if (controller.signal.aborted) throw new UserError("Figma authorization cancelled.");
+        if (command.kind === "logout") {
+          const removed = await logout(storage, credentialId);
+          ctx.ui.notify(`${removed ? "Removed this plugin's Figma credential." : "No credential owned by this plugin was found."} Run /mcp reload.`, "info");
+          return;
+        }
+        // Protect credential ownership before setup changes the configured auth source.
+        ownedCredential(storage, credentialId);
+        setupConfig(agentDir, credentialId);
+        if (command.kind === "setup") {
+          ctx.ui.notify("Figma MCP configured. Use /figma-remote-auth login to authorize, then run /mcp reload.", "info");
+          return;
+        }
+        ctx.ui.setStatus?.(COMMAND_NAME, "Waiting for Figma authorization");
+        const grant = await (dependencies.runOAuth ?? runOAuthFlow)({
+          clientName: command.clientName, port: command.port, signal: controller.signal,
+          onAuthorizationUrl: (url) => {
+            ctx.ui.notify(`Open this URL in your browser to authorize Figma:\n${url}\n\nReturn to OMP when finished. Use /figma-remote-auth cancel to stop waiting.`, "info");
+          },
+        });
+        if (controller.signal.aborted) throw new UserError("Figma authorization cancelled.");
+        // Recheck config and ownership after the browser wait before persisting credentials.
+        const config = configStatus(agentDir, credentialId);
+        if (!config.configured) throw new UserError("Figma configuration changed during authorization; credentials were not saved.");
+        await saveCredential(storage, credentialId, grant);
+        ctx.ui.notify("Figma authorization saved. Run /mcp reload.", "info");
+      } catch (error) {
+        ctx.ui.notify(formatError(error), "error");
+      } finally {
+        if (cancel) ctx.signal?.removeEventListener("abort", cancel);
+        if (operation) {
+          operation.controller.abort();
+          if (active === operation) active = undefined;
+          // Resolve first: UI failures must never strand session_shutdown waiting for cleanup.
+          finish?.();
+          ctx.ui.setStatus?.(COMMAND_NAME, undefined);
+        }
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "omp-figma-remote-auth",
+  "version": "0.1.1",
+  "description": "OAuth helper for Figma remote MCP using OMP native transport",
+  "type": "module",
+  "license": "MIT",
+  "author": "picasuo",
+  "contributors": [
+    "DianP (original Pi extension)"
+  ],
+  "homepage": "https://github.com/picasuo/omp-figma-remote-auth#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/picasuo/omp-figma-remote-auth.git"
+  },
+  "bugs": {
+    "url": "https://github.com/picasuo/omp-figma-remote-auth/issues"
+  },
+  "keywords": [
+    "omp",
+    "omp-package",
+    "oh-my-pi",
+    "figma",
+    "mcp",
+    "oauth",
+    "remote-mcp"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "main": "./index.ts",
+  "exports": "./index.ts",
+  "files": [
+    "index.ts",
+    "src",
+    "LICENSE",
+    "README.md",
+    "README.zh-CN.md"
+  ],
+  "omp": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test test/*.test.ts",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=22.6.0"
+  }
+}

package/src/args.ts

@@ -0,0 +1,108 @@
+export const SERVER_NAME = "figma";
+export const FIGMA_URL = "https://mcp.figma.com/mcp";
+export const COMMAND_NAME = "figma-remote-auth";
+
+/** Only errors authored by this extension are safe to show to the user. */
+export class UserError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "FigmaRemoteAuthError";
+  }
+}
+
+export function formatError(error: unknown): string {
+  return error instanceof UserError
+    ? error.message
+    : "Figma authentication failed. No credentials were included in this error.";
+}
+
+export type Command =
+  | { kind: "help" | "setup" | "status" | "logout" | "cancel" }
+  | { kind: "login"; clientName: string; port: number };
+
+/** Small shell-style tokenizer; no expansion, execution, or environment access. */
+function tokenize(input: string): string[] {
+  const words: string[] = [];
+  let value = "";
+  let quote: string | undefined;
+  let started = false;
+  let escaped = false;
+  for (const char of input) {
+    if (escaped) {
+      value += char;
+      escaped = false;
+      started = true;
+    } else if (char === "\\" && quote !== "'") {
+      escaped = true;
+      started = true;
+    } else if (quote) {
+      if (char === quote) quote = undefined;
+      else value += char;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+      started = true;
+    } else if (/\s/u.test(char)) {
+      if (started) words.push(value);
+      value = "";
+      started = false;
+    } else {
+      value += char;
+      started = true;
+    }
+  }
+  if (quote || escaped) throw new UserError("Unclosed quote or escape in arguments.");
+  if (started) words.push(value);
+  return words;
+}
+
+export function parseArgs(input: string): Command {
+  const [kind = "help", ...args] = tokenize(input);
+  if (kind !== "login") {
+    if (!["help", "setup", "status", "logout", "cancel"].includes(kind) || args.length) {
+      throw new UserError("Invalid command or arguments. Use /figma-remote-auth help.");
+    }
+    return { kind: kind as "help" | "setup" | "status" | "logout" | "cancel" };
+  }
+  let clientName = "Codex";
+  let port = 0;
+  const seen = new Set<string>();
+  for (let i = 0; i < args.length; i += 2) {
+    const key = args[i];
+    const value = args[i + 1];
+    if (!key || !["--client-name", "--port"].includes(key) || seen.has(key)) {
+      throw new UserError("Unknown or duplicate login option. Use /figma-remote-auth help.");
+    }
+    if (value === undefined || value.startsWith("--")) {
+      throw new UserError("Login option requires a value.");
+    }
+    seen.add(key);
+    if (key === "--client-name") {
+      if (!value.trim() || value.length > 128 || /[\x00-\x1f\x7f]/u.test(value)) {
+        throw new UserError("Client name must contain 1–128 printable characters.");
+      }
+      clientName = value;
+    } else {
+      if (!/^\d{1,5}$/u.test(value) || Number(value) > 65535) {
+        throw new UserError("Port must be an integer from 0 to 65535; 0 chooses a random port.");
+      }
+      port = Number(value);
+    }
+  }
+  return { kind: "login", clientName, port };
+}
+
+export function helpText(): string {
+  return [
+    "/figma-remote-auth help",
+    "/figma-remote-auth setup",
+    "/figma-remote-auth login [--client-name Codex] [--port 0]",
+    "/figma-remote-auth status",
+    "/figma-remote-auth logout",
+    "/figma-remote-auth cancel",
+    "",
+    `Server: ${SERVER_NAME} (${FIGMA_URL})`,
+    "Setup uses the active OMP agent directory's mcp.json.",
+    "Login displays a link for you to open manually. Use /figma-remote-auth cancel or exit OMP to stop waiting.",
+    "OMP handles MCP transport and token refresh. After setup, login, or logout, run /mcp reload.",
+  ].join("\n");
+}

package/src/config.ts

@@ -0,0 +1,122 @@
+import { constants, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { FIGMA_URL, UserError } from "./args.ts";
+
+type JsonObject = Record<string, unknown>;
+function record(value: unknown): value is JsonObject {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+export interface ConfigState { configured: boolean; path: string }
+
+/** Newly created private directories use 0700; normal ancestor links (macOS /tmp) are allowed. */
+function privateDirectory(path: string): void {
+  mkdirSync(path, { recursive: true, mode: 0o700 });
+  const info = lstatSync(path);
+  if (!info.isDirectory() || info.isSymbolicLink()) {
+    throw new UserError("OMP config directory must be a real directory, not a symlink.");
+  }
+}
+function readConfig(path: string): { raw?: string; config: JsonObject } {
+  let fd: number | undefined;
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    const raw = readFileSync(fd, "utf8");
+    let config: unknown;
+    try { config = JSON.parse(raw); }
+    catch { throw new UserError("OMP mcp.json must contain valid JSON; it was not changed."); }
+    if (!record(config)) throw new UserError("OMP mcp.json must contain a JSON object.");
+    return { raw, config };
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { config: {} };
+    if (error instanceof UserError) throw error;
+    throw new UserError("Unable to read OMP mcp.json safely; it was not changed.");
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+}
+
+/** Validate before mutation, preserving all unrelated JSON fields and servers. */
+export function mergeConfig(config: JsonObject, credentialId: string): JsonObject {
+  const servers = config.mcpServers;
+  if (servers !== undefined && !record(servers)) {
+    throw new UserError("mcpServers must be an object; mcp.json was not changed.");
+  }
+  const entries = servers ?? {};
+  const existing = entries.figma;
+  if (Object.hasOwn(entries, "figma")) {
+    if (!record(existing) || existing.url !== FIGMA_URL || existing.type !== "http") {
+      throw new UserError("Existing figma endpoint/type conflicts with official Figma HTTP MCP; mcp.json was not changed.");
+    }
+    if (existing.headers !== undefined) {
+      if (!record(existing.headers) || Object.keys(existing.headers).some(key => key.toLowerCase() === "authorization")) {
+        throw new UserError("Existing figma headers conflict with OAuth; mcp.json was not changed.");
+      }
+    }
+    if (Object.hasOwn(existing, "auth")) {
+      const auth = existing.auth;
+      if (!record(auth) || auth.type !== "oauth" || auth.credentialId !== credentialId ||
+          Object.keys(auth).some(key => !["type", "credentialId"].includes(key))) {
+        throw new UserError("Existing figma auth belongs to another source or has conflicting options; mcp.json was not changed.");
+      }
+    }
+    // Do not silently combine a URL transport with alternate endpoint/credential settings.
+    if (["endpoint", "command", "args", "env", "apiKey", "token", "bearerToken", "oauth"].some(key => Object.hasOwn(existing, key))) {
+      throw new UserError("Existing figma transport or credential options conflict; mcp.json was not changed.");
+    }
+  }
+  return {
+    ...config,
+    mcpServers: {
+      ...entries,
+      figma: { ...(record(existing) ? existing : {}), type: "http", url: FIGMA_URL, auth: { type: "oauth", credentialId } },
+    },
+  };
+}
+
+export function configStatus(agentDir: string, credentialId: string): ConfigState {
+  const path = join(agentDir, "mcp.json");
+  const { config } = readConfig(path);
+  mergeConfig(config, credentialId); // Status reports conflicts without revealing values.
+  const servers = record(config.mcpServers) ? config.mcpServers : {};
+  const figma = record(servers.figma) ? servers.figma : {};
+  const auth = record(figma.auth) ? figma.auth : {};
+  return { configured: auth.credentialId === credentialId, path };
+}
+
+/** Synchronous lock/read/merge/rename keeps local operations in one uninterrupted turn. */
+export function setupConfig(agentDir: string, credentialId: string): string {
+  privateDirectory(agentDir);
+  const path = join(agentDir, "mcp.json");
+  const lockPath = join(agentDir, ".figma-remote-auth-config.lock");
+  let lock: number;
+  try { lock = openSync(lockPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600); }
+  catch { throw new UserError("Figma config is locked by another operation. If OMP crashed, remove .figma-remote-auth-config.lock after verifying no login is active."); }
+  let temporary: string | undefined;
+  let file: number | undefined;
+  try {
+    const { raw, config } = readConfig(path);
+    const merged = mergeConfig(config, credentialId);
+    if (JSON.stringify(config) === JSON.stringify(merged)) return path;
+    temporary = join(agentDir, `.mcp.json.${randomBytes(16).toString("hex")}.tmp`);
+    file = openSync(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, 0o600);
+    writeFileSync(file, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
+    fsyncSync(file);
+    closeSync(file);
+    file = undefined;
+    if (readConfig(path).raw !== raw) throw new UserError("mcp.json changed during setup; retry the command.");
+    renameSync(temporary, path);
+    temporary = undefined;
+    const directory = openSync(agentDir, constants.O_RDONLY);
+    try { fsyncSync(directory); } finally { closeSync(directory); }
+    return path;
+  } catch (error) {
+    if (error instanceof UserError) throw error;
+    throw new UserError("Unable to write OMP mcp.json atomically.");
+  } finally {
+    if (file !== undefined) closeSync(file);
+    if (temporary && existsSync(temporary)) unlinkSync(temporary);
+    closeSync(lock);
+    unlinkSync(lockPath);
+  }
+}

package/src/oauth.ts

@@ -0,0 +1,324 @@
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { createServer } from "node:http";
+import type { Server } from "node:http";
+import { UserError } from "./args.ts";
+
+export const DISCOVERY_URL = "https://mcp.figma.com/.well-known/oauth-authorization-server";
+export const ENDPOINTS = Object.freeze({
+  issuer: "https://api.figma.com",
+  authorizationUrl: "https://www.figma.com/oauth/mcp",
+  tokenUrl: "https://api.figma.com/v1/oauth/token",
+  registrationUrl: "https://api.figma.com/v1/oauth/mcp/register",
+});
+export const CALLBACK_PATH = "/callback";
+export const AUTH_TIMEOUT_MS = 10 * 60 * 1000;
+export type FetchLike = (url: string, init: RequestInit) => Promise<Response>;
+
+export interface RegisteredClient {
+  clientId: string;
+  clientSecret?: string;
+  clientIdIssuedAt?: number;
+  clientSecretExpiresAt?: number;
+}
+export interface OAuthGrant extends RegisteredClient {
+  access: string;
+  refresh: string;
+  /** OMP consumes absolute milliseconds, not Unix seconds. */
+  expires: number;
+  tokenUrl: string;
+  authorizationUrl: string;
+  scope?: string;
+}
+export interface FlowOptions {
+  clientName: string;
+  port: number;
+  signal?: AbortSignal;
+  onAuthorizationUrl: (url: string, callbackUrl: string) => void | Promise<void>;
+  /** Test seams only. No CLI option can change the remote URLs. */
+  fetch?: FetchLike;
+  timeoutMs?: number;
+  now?: () => number;
+}
+
+const OAUTH_ERRORS: Record<string, true> = {
+  invalid_request: true, invalid_client: true, invalid_grant: true,
+  unauthorized_client: true, unsupported_grant_type: true, invalid_scope: true,
+  access_denied: true, unsupported_response_type: true, server_error: true,
+  temporarily_unavailable: true, invalid_redirect_uri: true,
+  invalid_client_metadata: true, invalid_token: true, insufficient_scope: true,
+};
+function oauthError(value: unknown): string {
+  return typeof value === "string" && Object.hasOwn(OAUTH_ERRORS, value)
+    ? value : "oauth_error";
+}
+export function objectValue(value: unknown): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new UserError("Invalid OAuth JSON response.");
+  }
+  return value as Record<string, unknown>;
+}
+function stringValue(value: unknown, field: string): string {
+  if (typeof value !== "string" || !value.trim() || value.length > 65536 || /[\x00-\x1f\x7f]/u.test(value)) {
+    throw new UserError(`Invalid OAuth field: ${field}.`);
+  }
+  return value;
+}
+function optionalString(value: unknown, field: string): string | undefined {
+  return value === undefined ? undefined : stringValue(value, field);
+}
+function optionalTimestamp(value: unknown, field: string): number | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value < 0) {
+    throw new UserError(`Invalid OAuth field: ${field}.`);
+  }
+  return value;
+}
+function aborted(signal: AbortSignal): void {
+  if (signal.aborted) throw signal.reason instanceof UserError
+    ? signal.reason : new UserError("Figma authorization cancelled.");
+}
+/** Also bounds test/injected fetch implementations that ignore AbortSignal. */
+async function abortable<T>(operation: Promise<T>, signal: AbortSignal): Promise<T> {
+  let onAbort!: () => void;
+  const cancelled = new Promise<never>((_, reject) => {
+    onAbort = () => reject(signal.reason instanceof UserError
+      ? signal.reason : new UserError("Figma authorization cancelled."));
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) onAbort();
+  });
+  try {
+    return await Promise.race([operation, cancelled]);
+  } finally {
+    signal.removeEventListener("abort", onAbort);
+  }
+}
+
+async function fetchJson(
+  fetcher: FetchLike, url: string, init: RequestInit, signal: AbortSignal,
+): Promise<Record<string, unknown>> {
+  aborted(signal);
+  let response: Response;
+  try {
+    response = await abortable(fetcher(url, { ...init, signal, redirect: "error" }), signal);
+  } catch {
+    aborted(signal);
+    throw new UserError("OAuth network request failed (redirects are disabled).");
+  }
+  let body: unknown;
+  try {
+    body = await abortable(response.json(), signal);
+  } catch {
+    aborted(signal);
+    throw new UserError(`OAuth HTTP ${response.status}: invalid JSON response.`);
+  }
+  const data = objectValue(body);
+  if (!response.ok || data.error !== undefined) {
+    throw new UserError(`OAuth HTTP ${response.status}${data.error === undefined ? "" : `: ${oauthError(data.error)}`}.`);
+  }
+  return data;
+}
+
+export async function discoverEndpoints(fetcher: FetchLike, signal: AbortSignal): Promise<typeof ENDPOINTS> {
+  const data = await fetchJson(fetcher, DISCOVERY_URL, {}, signal);
+  if (data.issuer !== ENDPOINTS.issuer ||
+      data.authorization_endpoint !== ENDPOINTS.authorizationUrl ||
+      data.token_endpoint !== ENDPOINTS.tokenUrl ||
+      data.registration_endpoint !== ENDPOINTS.registrationUrl ||
+      !Array.isArray(data.code_challenge_methods_supported) ||
+      !data.code_challenge_methods_supported.includes("S256")) {
+    throw new UserError("Figma OAuth discovery contains an untrusted endpoint or does not support S256.");
+  }
+  return ENDPOINTS;
+}
+export async function registerClient(
+  fetcher: FetchLike, redirectUri: string, clientName: string, signal: AbortSignal,
+): Promise<RegisteredClient> {
+  const data = await fetchJson(fetcher, ENDPOINTS.registrationUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      redirect_uris: [redirectUri],
+      client_name: clientName,
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      token_endpoint_auth_method: "none",
+    }),
+  }, signal);
+  return {
+    clientId: stringValue(data.client_id, "client_id"),
+    clientSecret: optionalString(data.client_secret, "client_secret"),
+    clientIdIssuedAt: optionalTimestamp(data.client_id_issued_at, "client_id_issued_at"),
+    clientSecretExpiresAt: optionalTimestamp(data.client_secret_expires_at, "client_secret_expires_at"),
+  };
+}
+export function generatePkce(): { verifier: string; challenge: string } {
+  const verifier = randomBytes(32).toString("base64url");
+  return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") };
+}
+export function parseTokens(data: Record<string, unknown>, now: number): Pick<OAuthGrant, "access" | "refresh" | "expires" | "scope"> {
+  const access = stringValue(data.access_token, "access_token");
+  const refresh = stringValue(data.refresh_token, "refresh_token (required for OMP refresh)");
+  if (typeof data.token_type !== "string" || data.token_type.toLowerCase() !== "bearer") {
+    throw new UserError("OAuth token_type must be Bearer.");
+  }
+  const duration = typeof data.expires_in === "string" && /^\d+$/u.test(data.expires_in)
+    ? Number(data.expires_in) : data.expires_in;
+  if (typeof duration !== "number" || !Number.isSafeInteger(duration) || duration <= 0 ||
+      !Number.isSafeInteger(now) || now < 0 ||
+      !Number.isSafeInteger(now + duration * 1000) || now + duration * 1000 > 8.64e15) {
+    throw new UserError("OAuth expires_in must be a positive, safely representable duration.");
+  }
+  return { access, refresh, expires: now + duration * 1000, scope: optionalString(data.scope, "scope") };
+}
+export async function exchangeCode(
+  fetcher: FetchLike, client: RegisteredClient, redirectUri: string,
+  code: string, verifier: string, signal: AbortSignal, now: () => number = Date.now,
+): Promise<OAuthGrant> {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code", code, redirect_uri: redirectUri,
+    client_id: client.clientId, code_verifier: verifier,
+  });
+  if (client.clientSecret) body.set("client_secret", client.clientSecret);
+  const data = await fetchJson(fetcher, ENDPOINTS.tokenUrl, {
+    method: "POST", headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  }, signal);
+  return { ...client, ...parseTokens(data, now()), tokenUrl: ENDPOINTS.tokenUrl, authorizationUrl: ENDPOINTS.authorizationUrl };
+}
+
+export interface CallbackListener {
+  callbackUrl: string;
+  result: Promise<string>;
+  close: () => Promise<void>;
+}
+export async function listenForCallback(port: number, state: string, signal: AbortSignal): Promise<CallbackListener> {
+  aborted(signal);
+  let resolveCode!: (code: string) => void;
+  let rejectCode!: (error: unknown) => void;
+  let settled = false;
+  let closing: Promise<void> | undefined;
+  const result = new Promise<string>((resolve, reject) => { resolveCode = resolve; rejectCode = reject; });
+  // Discovery/DCR can fail before the caller awaits result. Observe rejection immediately.
+  void result.catch(() => {});
+  const fail = (error: UserError) => {
+    if (!settled) { settled = true; rejectCode(error); }
+  };
+  let server: Server;
+  const close = (): Promise<void> => {
+    if (closing) return closing;
+    signal.removeEventListener("abort", onAbort);
+    fail(new UserError("Figma authorization cancelled."));
+    closing = new Promise<void>((resolve) => {
+      server.close(() => resolve());
+      server.closeAllConnections();
+    });
+    return closing;
+  };
+  const onAbort = () => {
+    fail(signal.reason instanceof UserError ? signal.reason : new UserError("Figma authorization cancelled."));
+    void close();
+  };
+  server = createServer((req, res) => {
+    const reply = (status: number, text: string) => {
+      res.writeHead(status, {
+        "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store",
+        "Referrer-Policy": "no-referrer", "Connection": "close",
+        "Content-Security-Policy": "default-src 'none'",
+      });
+      res.end(text);
+    };
+    if (settled) { reply(410, "Authorization already completed."); return; }
+    if (req.method !== "GET") { reply(405, "GET required."); return; }
+    if (!req.url?.startsWith("/") || req.url.startsWith("//")) { reply(400, "Bad callback."); return; }
+    let url: URL;
+    try { url = new URL(req.url, "http://127.0.0.1"); }
+    catch { reply(400, "Bad callback."); return; }
+    if (url.pathname !== CALLBACK_PATH) { reply(404, "Not found."); return; }
+    const states = url.searchParams.getAll("state");
+    const received = Buffer.from(states[0] ?? "");
+    const expected = Buffer.from(state);
+    if (states.length !== 1 || received.length !== expected.length || !timingSafeEqual(received, expected)) {
+      reply(400, "Invalid OAuth state."); return;
+    }
+    // Validate state before processing errors: unrelated requests cannot abort login.
+    const errors = url.searchParams.getAll("error");
+    const codes = url.searchParams.getAll("code");
+    const issuers = url.searchParams.getAll("iss");
+    if (issuers.length > 1 || (issuers.length === 1 && issuers[0] !== ENDPOINTS.issuer)) {
+      reply(400, "Invalid OAuth issuer."); return;
+    }
+    if (errors.length === 1 && codes.length === 0) {
+      reply(400, "Authorization was not granted. Return to OMP.");
+      fail(new UserError(`OAuth callback: ${oauthError(errors[0])}.`));
+      return;
+    }
+    if (errors.length || codes.length !== 1 || !codes[0] || codes[0].length > 65536 || /[\x00-\x1f\x7f]/u.test(codes[0])) {
+      reply(400, "Invalid OAuth callback."); return;
+    }
+    settled = true;
+    reply(200, "Authorization code received. Return to OMP to confirm token exchange completed.");
+    resolveCode(codes[0]);
+  });
+  server.requestTimeout = 10_000;
+  server.headersTimeout = 10_000;
+  server.on("error", () => {
+    fail(new UserError("OAuth callback listener failed."));
+    void close();
+  });
+  // Await bind before installing abort cleanup; an abort during bind is checked immediately after.
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const bindError = () => reject(new UserError("Unable to bind OAuth callback to 127.0.0.1."));
+      server.once("error", bindError);
+      server.listen(port, "127.0.0.1", () => { server.off("error", bindError); resolve(); });
+    });
+    const address = server.address();
+    if (!address || typeof address === "string") throw new UserError("OAuth callback listener has no port.");
+    signal.addEventListener("abort", onAbort, { once: true });
+    if (signal.aborted) { onAbort(); aborted(signal); }
+    return { callbackUrl: `http://127.0.0.1:${address.port}${CALLBACK_PATH}`, result, close };
+  } catch (error) {
+    await close();
+    throw error;
+  }
+}
+
+export async function runOAuthFlow(options: FlowOptions): Promise<OAuthGrant> {
+  const controller = new AbortController();
+  const cancel = () => controller.abort(new UserError("Figma authorization cancelled."));
+  const timeoutMs = options.timeoutMs ?? AUTH_TIMEOUT_MS;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs <= 0 || timeoutMs > 2_147_483_647) {
+    throw new UserError("Invalid OAuth timeout.");
+  }
+  const timer = setTimeout(() => controller.abort(new UserError("Figma authorization timed out.")), timeoutMs);
+  options.signal?.addEventListener("abort", cancel, { once: true });
+  if (options.signal?.aborted) cancel();
+  const fetcher = options.fetch ?? ((url, init) => fetch(url, init));
+  let listener: CallbackListener | undefined;
+  try {
+    aborted(controller.signal);
+    const { verifier, challenge } = generatePkce();
+    const state = randomBytes(32).toString("base64url");
+    listener = await listenForCallback(options.port, state, controller.signal);
+    await discoverEndpoints(fetcher, controller.signal);
+    const client = await registerClient(fetcher, listener.callbackUrl, options.clientName, controller.signal);
+    const url = new URL(ENDPOINTS.authorizationUrl);
+    url.search = new URLSearchParams({
+      response_type: "code", client_id: client.clientId, redirect_uri: listener.callbackUrl,
+      code_challenge: challenge, code_challenge_method: "S256", state,
+    }).toString();
+    aborted(controller.signal);
+    await abortable(Promise.resolve(options.onAuthorizationUrl(url.href, listener.callbackUrl)), controller.signal);
+    const code = await listener.result;
+    aborted(controller.signal);
+    const grant = await exchangeCode(fetcher, client, listener.callbackUrl, code, verifier, controller.signal, options.now);
+    aborted(controller.signal);
+    return grant;
+  } finally {
+    clearTimeout(timer);
+    options.signal?.removeEventListener("abort", cancel);
+    // Cancel in-flight fetches as well as the listener on every exit path.
+    controller.abort(new UserError("Figma authorization cancelled."));
+    await listener?.close();
+  }
+}

package/src/storage.ts

@@ -0,0 +1,57 @@
+import { createHash } from "node:crypto";
+import { FIGMA_URL, UserError } from "./args.ts";
+import { ENDPOINTS } from "./oauth.ts";
+import type { OAuthGrant } from "./oauth.ts";
+
+export const OWNER = "omp-figma-remote-auth/v1";
+export interface Credential extends OAuthGrant {
+  type: "oauth";
+  figmaRemoteAuthOwner: string;
+  figmaRemoteAuthCredentialId: string;
+}
+/** The public AuthStorage contract exposed through ctx.modelRegistry.authStorage. */
+export interface AuthStorage {
+  get(provider: string): unknown;
+  set(provider: string, credential: Credential): Promise<void>;
+  remove(provider: string): Promise<void>;
+}
+export function credentialIdFor(agentDir: string): string {
+  return `mcp_oauth_omp_figma_${createHash("sha256").update(`${agentDir}\n${FIGMA_URL}`).digest("hex").slice(0, 24)}`;
+}
+export function ownedCredential(storage: AuthStorage, credentialId: string): Credential | undefined {
+  const value = storage.get(credentialId);
+  if (value === undefined || value === null) return undefined;
+  if (typeof value !== "object" || Array.isArray(value) ||
+      (value as Partial<Credential>).type !== "oauth" ||
+      (value as Partial<Credential>).figmaRemoteAuthOwner !== OWNER ||
+      (value as Partial<Credential>).figmaRemoteAuthCredentialId !== credentialId) {
+    throw new UserError("The Figma credential ID is occupied by another authentication source. It was not changed.");
+  }
+  return value as Credential;
+}
+export async function saveCredential(storage: AuthStorage, credentialId: string, grant: OAuthGrant): Promise<void> {
+  ownedCredential(storage, credentialId);
+  // Defense in depth at the persistence boundary, even for callers other than the OAuth runner.
+  if (!grant.access || !grant.refresh || !grant.clientId ||
+      !Number.isSafeInteger(grant.expires) || grant.expires <= 0 || grant.expires > 8.64e15 ||
+      grant.tokenUrl !== ENDPOINTS.tokenUrl || grant.authorizationUrl !== ENDPOINTS.authorizationUrl) {
+    throw new UserError("Invalid Figma OAuth credential; nothing was saved.");
+  }
+  await storage.set(credentialId, {
+    ...grant, type: "oauth", figmaRemoteAuthOwner: OWNER, figmaRemoteAuthCredentialId: credentialId,
+  });
+}
+export async function logout(storage: AuthStorage, credentialId: string): Promise<boolean> {
+  if (!ownedCredential(storage, credentialId)) return false;
+  await storage.remove(credentialId);
+  return true;
+}
+export function credentialStatus(storage: AuthStorage, credentialId: string, now = Date.now()): string {
+  const credential = ownedCredential(storage, credentialId);
+  if (!credential) return "Credential: not logged in.";
+  const expiry = credential.expires;
+  if (!Number.isSafeInteger(expiry) || expiry <= 0 || expiry > 8.64e15) {
+    return "Credential: present, but expiration metadata is invalid; log in again.";
+  }
+  return `Credential: present; ${expiry > now ? "access token expires" : "access token expired"} ${new Date(expiry).toISOString()}. OMP handles refresh.`;
+}