@akira-tl/forgerelay 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.6.1] - 2026-08-28
+
+### Added
+
+- Added Workspace Relay: register a remote ForgeRelay with `forgerelay auth`, then open a remote Workspace through the existing MCP surface with `open_workspace(..., relay="<alias>")`; direct targets and system-SSH-routed targets share the same authentication and MCP protocol.
+- Added CLI remote authentication with hidden owner-token input, explicit `--token`, and SSH-assisted `--ssh-auth`; `-J` accepts one final SSH target or a full comma-separated jump route while the remote service target remains one independent `host:port`/URL value.
+- Added remote routing for Workspace reads and mutations, Bash/process lifecycle and durable output, optional capabilities, Skills, Hooks, and Host Activity snapshot/detail/output queries while keeping execution facts owned by the execution ForgeRelay.
+- Added restart-safe remote identity and Workspace routing: stable remote instance IDs survive alias/target changes, access tokens refresh through the existing token store, SSH tunnels are rebuilt on fresh random loopback ports, and relayed Workspace IDs remain stable across Gateway restarts.
+
+### Changed
+
+- Activity Panel bootstrap can reconstruct Workspace presentation from the execution instance across independent MCP connections, allowing relayed Host Turns and App-only Activity queries to follow the execution Workspace without requiring one long-lived transport session.
+- ForgeRelay authentication and relayed-Workspace route files now use lock-protected read/modify/write updates with atomic replacement so concurrent CLI/server sessions do not overwrite each other.
+
+### Security
+
+- Remote targets, SSH routes, temporary tunnel ports, owner tokens, access tokens, refresh tokens, and execution-side Workspace IDs stay out of the model-facing relay contract; the Host sees the configured relay alias and Gateway `rws_...` identity instead.
+- SSH-assisted authentication retrieves the remote owner token only into the initiating process, then reuses the normal CLI token exchange; runtime forwarding binds loopback only, and failed direct/SSH/remote operations never silently fall back to a local or different remote Workspace.
+
 ## [0.6.0] - 2026-08-27
 
 ### Added

package/README.md

@@ -158,7 +158,7 @@ You can rebase and verify inside the worktree, then retry the close.
 
 Hook 是 ForgeRelay 的自动生命周期规则。首选方式是一个 Hook 一个文件：全局放在 `~/.forgerelay/hooks/<hook-name>.json`，项目放在 `<repo>/.forgerelay/hooks/<hook-name>.json`。文件名就是 Hook 名，方便直接从目录看出每条规则的用途；全局与项目规则组合执行，不需要额外批准。
 
-例如项目里的 `.forgerelay/hooks/release-tag-local-ci.json` 可以要求稳定版本 tag push 前先完成本地发布检查：
+例如项目里的 `.forgerelay/hooks/release-tag-gate.json` 可以在稳定版本 tag push 前执行轻量发布门禁：
 
 ```json
 {
@@ -173,7 +173,7 @@ Hook 是 ForgeRelay 的自动生命周期规则。首选方式是一个 Hook 一
 }
 ```
 
-耗时的 `npm run release:verify` 应先在已提交的 release-ready HEAD 上运行，它会写入绑定 HEAD/package version 的本地 release proof。命中 `BeforeTool` 后，Hook 只快速验证该 proof、clean working tree（含 untracked）与 tag 指向；成功才继续原始 `git push`，失败则直接阻断。这样发布 gate 不依赖一个持续数分钟的 MCP 请求。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
+命中 `BeforeTool` 后，Hook 只快速验证 clean working tree（含 untracked）、tag 与 package version 一致，以及本地 tag 指向当前 HEAD；成功才继续原始 `git push`，失败则直接阻断。Hook 不运行、也不要求本地 CI。tag 推送后由 GitHub Actions 的 Linux/macOS/Windows 矩阵执行权威验证，全部通过后才进入发布。`npm run release:verify` 仅作为可选的本地云端复现工具。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
 
 旧的 inline `hooks` 和聚合 `hooks.json` 仍兼容；新配置建议都用独立 `hooks/*.json` 文件。
 
@@ -293,18 +293,15 @@ npm run release:check
 npm run release:patch
 npm run release:minor
 npm run release:major
-npm run release:verify
 ```
 
-Daily branch pushes do not run cloud CI. When preparing a release, commit the
-release-ready tree and run the full local release verification on that clean HEAD.
-`release:verify` includes a focused parity pass in an isolated Node 22.19.0 environment
-with its own `npm ci`, matching the cloud CI runtime for native addons and high-risk
-LSP lifecycle tests, then writes the local proof consumed by the tag-push Hook. Pushing a matching
-`vX.Y.Z` tag to `Akira-TL/forgerelay` is the only cloud CI and publish trigger:
-GitHub Actions runs the reusable multi-platform CI, then publishes
-`@akira-tl/forgerelay` and creates the matching GitHub Release only after CI
-succeeds.
+Daily branch pushes do not run cloud CI. Commit the release-ready tree, push it to
+`main`, then push the matching `vX.Y.Z` tag. That tag is the only cloud CI and publish
+trigger: GitHub Actions runs the reusable Linux/macOS/Windows verification matrix,
+then publishes `@akira-tl/forgerelay` and creates the matching GitHub Release only
+after all platforms succeed. `npm run release:verify` remains available only when a
+cloud failure needs local reproduction against the pinned Node runtime; it is not a
+release prerequisite.
 
 See [Versioning and Release Management](docs/versioning.md) for the bootstrap and
 Trusted Publishing setup.

package/dist/activity/mcp-query-tools.js

@@ -42,7 +42,7 @@ const snapshotOutputSchema = {
     activities: z.array(activitySummarySchema),
     [ACTIVITY_PANEL_WORKSPACE_META_KEY]: z.record(z.string(), z.unknown()).optional(),
 };
-export function registerActivityQueryTools(server, queries, connectionScopeId, panelMeta = {}, panelDefaultExpanded = false, logging, workspacePanelState) {
+export function registerActivityQueryTools(server, queries, connectionScopeId, panelMeta = {}, panelDefaultExpanded = false, logging, workspacePanelState, relay) {
     const panelUi = typeof panelMeta.ui === "object" && panelMeta.ui !== null
         ? panelMeta.ui
         : {};
@@ -69,7 +69,23 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         if (!workspace) {
             throw new Error(`No Workspace presentation is available for ${workspaceId}. Call open_workspace for that workspace before activity_panel.`);
         }
-        const snapshot = queries.beginTurn(hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId), workspaceId);
+        const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const relayed = await relay?.panel(workspaceId, conversationScopeId);
+        if (relayed) {
+            return {
+                ...relayed,
+                _meta: {
+                    ...(relayed._meta ?? {}),
+                    [ACTIVITY_PANEL_DEFAULT_EXPANDED_META_KEY]: panelDefaultExpanded,
+                    [ACTIVITY_PANEL_WORKSPACE_META_KEY]: workspace,
+                },
+                structuredContent: {
+                    ...(relayed.structuredContent ?? {}),
+                    [ACTIVITY_PANEL_WORKSPACE_META_KEY]: workspace,
+                },
+            };
+        }
+        const snapshot = queries.beginTurn(conversationScopeId, workspaceId);
         if (logging) {
             logEvent(logging, "debug", "activity_panel_call", {
                 turnId: snapshot.turnId,
@@ -108,6 +124,27 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         annotations: READ_ONLY_ANNOTATIONS,
     }, async ({ turnId, workspaceId, knownRevision }, extra) => {
         const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const relayed = await relay?.snapshot({ turnId, workspaceId, knownRevision }, conversationScopeId);
+        if (relayed) {
+            const workspace = workspaceId ? workspacePanelState?.(workspaceId) : undefined;
+            if (workspaceId && !workspace) {
+                throw new Error(`No Workspace presentation is available for ${workspaceId}.`);
+            }
+            return workspace
+                ? {
+                    ...relayed,
+                    _meta: {
+                        ...(relayed._meta ?? {}),
+                        [ACTIVITY_PANEL_DEFAULT_EXPANDED_META_KEY]: panelDefaultExpanded,
+                        [ACTIVITY_PANEL_WORKSPACE_META_KEY]: workspace,
+                    },
+                    structuredContent: {
+                        ...(relayed.structuredContent ?? {}),
+                        [ACTIVITY_PANEL_WORKSPACE_META_KEY]: workspace,
+                    },
+                }
+                : relayed;
+        }
         const resolvedTurnId = turnId ?? queries.currentTurnId(conversationScopeId, workspaceId);
         if (!resolvedTurnId) {
             throw new Error("Activity snapshot bootstrap could not resolve the current Host Turn from conversation and workspace metadata.");
@@ -162,6 +199,10 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         _meta: { ui: { visibility: ["app"] } },
         annotations: READ_ONLY_ANNOTATIONS,
     }, async ({ turnId, activityId }, extra) => {
+        const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const relayed = await relay?.detail(turnId, activityId, conversationScopeId);
+        if (relayed)
+            return relayed;
         const detail = queries.detail(turnId, activityId);
         if (logging) {
             logEvent(logging, "debug", "activity_detail_call", {
@@ -201,6 +242,10 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         _meta: { ui: { visibility: ["app"] } },
         annotations: READ_ONLY_ANNOTATIONS,
     }, async ({ turnId, outputId }, extra) => {
+        const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const relayed = await relay?.output(turnId, outputId, conversationScopeId);
+        if (relayed)
+            return relayed;
         const output = queries.bashOutput(turnId, outputId);
         if (logging) {
             logEvent(logging, "debug", "activity_output_call", {

package/dist/cli.js

@@ -18,10 +18,12 @@ import { isLocalAgentProvider, loadLocalAgentProfiles, } from "./local-agent-pro
 import { assertLocalAgentProviderAvailable, formatLocalAgentProviderAvailabilitySummary, } from "./local-agent-availability.js";
 import { formatAvailableLocalAgentTargets, parseLocalAgentRunArgs, resolveLocalAgentTarget, } from "./local-agent-targets.js";
 import { createLocalAgentStore } from "./local-agent-store.js";
-import { generateOwnerToken, loadDevspaceFiles, resolveSubagentsFlag, writeDevspaceAuth, writeDevspaceConfig, } from "./user-config.js";
+import { ensureForgeRelayInstanceId, generateInstanceId, generateOwnerToken, loadDevspaceFiles, removeForgeRelayRemote, renameForgeRelayRemote, resolveSubagentsFlag, writeDevspaceAuth, writeDevspaceConfig, writeForgeRelayRemote, } from "./user-config.js";
 import { expandHomePath } from "./roots.js";
 import { shutdownHttpServer } from "./server-shutdown.js";
 import { publicEndpointUrl } from "./oauth/public-url.js";
+import { authenticateRemote, defaultRemoteAlias, isRemoteMcpUnauthorized, normalizeRemoteServiceTarget, refreshRemoteAuthentication, verifyRemoteMcp, } from "./remote-auth.js";
+import { defaultSshRouteAlias, parseSshRoute, readRemoteOwnerToken, withRemoteServiceEndpoint, } from "./remote-transport.js";
 const require = createRequire(import.meta.url);
 const SUPPORTED_NODE_RANGE = ">=20.12 <27";
 async function main(argv) {
@@ -48,6 +50,9 @@ async function main(argv) {
         case "agents":
             await runAgentsCommand(args);
             return;
+        case "auth":
+            await runAuthCommand(args);
+            return;
         case "help":
             printHelp();
             return;
@@ -59,7 +64,7 @@ async function main(argv) {
 function normalizeCommand(command) {
     if (!command || command === "serve" || command === "start")
         return "serve";
-    if (command === "init" || command === "doctor" || command === "config" || command === "hooks" || command === "agents")
+    if (command === "init" || command === "doctor" || command === "config" || command === "hooks" || command === "agents" || command === "auth")
         return command;
     if (command === "help" || command === "--help" || command === "-h")
         return "help";
@@ -69,10 +74,14 @@ function normalizeCommand(command) {
 }
 async function ensureConfigured() {
     const files = loadDevspaceFiles();
-    if (files.configExists && files.authExists)
+    if (files.configExists && files.authExists) {
+        ensureForgeRelayInstanceId();
         return;
-    if (process.env.FORGERELAY_OAUTH_OWNER_TOKEN ?? process.env.DEVSPACE_OAUTH_OWNER_TOKEN)
+    }
+    if (process.env.FORGERELAY_OAUTH_OWNER_TOKEN ?? process.env.DEVSPACE_OAUTH_OWNER_TOKEN) {
+        ensureForgeRelayInstanceId();
         return;
+    }
     if (!input.isTTY || !output.isTTY) {
         throw new Error([
             "ForgeRelay is not configured and this terminal is non-interactive.",
@@ -143,7 +152,9 @@ async function runInit({ force }) {
             subagents: resolveSubagentsFlag(files.config),
         };
         const auth = {
+            ...files.auth,
             ownerToken: files.auth.ownerToken ?? generateOwnerToken(),
+            instanceId: files.auth.instanceId ?? generateInstanceId(),
         };
         const configPath = writeDevspaceConfig(config);
         const authPath = writeDevspaceAuth(auth);
@@ -214,6 +225,166 @@ async function serve() {
     process.once("SIGINT", handleShutdown);
     process.once("SIGTERM", handleShutdown);
 }
+function parseAuthCommandArgs(args) {
+    let target;
+    let alias;
+    let ownerToken;
+    let sshRoute;
+    let sshAuth = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--alias") {
+            alias = args[++index];
+            if (!alias)
+                throw new Error("Missing value for --alias.");
+            continue;
+        }
+        if (arg === "--token") {
+            ownerToken = args[++index];
+            if (!ownerToken)
+                throw new Error("Missing value for --token.");
+            continue;
+        }
+        if (arg === "-J") {
+            const route = args[++index];
+            if (!route)
+                throw new Error("Missing value for -J.");
+            sshRoute = parseSshRoute(route);
+            continue;
+        }
+        if (arg === "--ssh-auth") {
+            sshAuth = true;
+            continue;
+        }
+        if (arg.startsWith("-"))
+            throw new Error(`Unknown auth option: ${arg}`);
+        if (target)
+            throw new Error(`Unexpected auth argument: ${arg}`);
+        target = arg;
+    }
+    if (!target)
+        throw new Error("Missing remote service target.");
+    if (sshAuth && !sshRoute)
+        throw new Error("--ssh-auth requires -J <ssh-route>.");
+    if (sshAuth && ownerToken)
+        throw new Error("--ssh-auth and --token cannot be used together.");
+    return { target, alias, ownerToken, sshRoute, sshAuth };
+}
+async function resolveAuthOwnerToken(ownerToken) {
+    if (ownerToken)
+        return ownerToken;
+    if (!input.isTTY || !output.isTTY) {
+        throw new Error("Missing owner token. Pass --token, use --ssh-auth with -J, or run in an interactive terminal.");
+    }
+    const result = await prompts.password({
+        message: "Remote ForgeRelay owner token",
+        validate: (value) => value?.trim() ? undefined : "Enter the remote owner token.",
+    });
+    if (prompts.isCancel(result))
+        throw new Error("Remote authentication cancelled.");
+    return String(result);
+}
+function localOwnerToken() {
+    const token = process.env.FORGERELAY_OAUTH_OWNER_TOKEN
+        ?? process.env.DEVSPACE_OAUTH_OWNER_TOKEN
+        ?? loadDevspaceFiles().auth.ownerToken;
+    if (!token)
+        throw new Error("ForgeRelay owner token is not configured on this machine.");
+    return token;
+}
+async function runAuthCommand(args) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === "__owner-token") {
+        if (rest.length > 0)
+            throw new Error("Internal owner-token command does not accept arguments.");
+        process.stdout.write(`${localOwnerToken()}\n`);
+        return;
+    }
+    if (subcommand === "list") {
+        if (rest.length > 0)
+            throw new Error("forgerelay auth list does not accept additional arguments.");
+        const remotes = loadDevspaceFiles().auth.remotes ?? {};
+        if (Object.keys(remotes).length === 0) {
+            console.log("No remote ForgeRelay instances registered.");
+            return;
+        }
+        for (const [alias, remote] of Object.entries(remotes).sort(([left], [right]) => left.localeCompare(right))) {
+            console.log(`${alias}\t${remote.target}\t${remote.instanceId}`);
+        }
+        return;
+    }
+    if (subcommand === "rename") {
+        const [fromAlias, toAlias, ...extra] = rest;
+        if (!fromAlias || !toAlias || extra.length > 0) {
+            throw new Error("Usage: forgerelay auth rename <old-alias> <new-alias>");
+        }
+        renameForgeRelayRemote(fromAlias, toAlias);
+        console.log(`Renamed remote ${fromAlias} to ${toAlias}.`);
+        return;
+    }
+    if (subcommand === "remove") {
+        const [alias, ...extra] = rest;
+        if (!alias || extra.length > 0)
+            throw new Error("Usage: forgerelay auth remove <alias>");
+        removeForgeRelayRemote(alias);
+        console.log(`Removed remote ${alias}.`);
+        return;
+    }
+    if (subcommand === "test") {
+        const [alias, ...extra] = rest;
+        if (!alias || extra.length > 0)
+            throw new Error("Usage: forgerelay auth test <alias>");
+        const files = loadDevspaceFiles();
+        const storedRemote = files.auth.remotes?.[alias];
+        if (!storedRemote)
+            throw new Error(`Unknown remote alias: ${alias}`);
+        let remote = storedRemote;
+        await withRemoteServiceEndpoint(remote.target, remote.sshRoute, async (endpoint) => {
+            let refreshed = false;
+            if (remote.accessTokenExpiresAt <= Math.floor(Date.now() / 1000)) {
+                remote = await refreshRemoteAuthentication(remote, endpoint);
+                writeForgeRelayRemote(alias, remote);
+                refreshed = true;
+            }
+            try {
+                await verifyRemoteMcp(remote, endpoint);
+            }
+            catch (error) {
+                if (refreshed || !isRemoteMcpUnauthorized(error))
+                    throw error;
+                remote = await refreshRemoteAuthentication(remote, endpoint);
+                writeForgeRelayRemote(alias, remote);
+                await verifyRemoteMcp(remote, endpoint);
+            }
+        });
+        console.log(`${alias}\tok\t${remote.instanceId}`);
+        return;
+    }
+    const parsed = parseAuthCommandArgs(args);
+    const target = normalizeRemoteServiceTarget(parsed.target);
+    const authenticated = await withRemoteServiceEndpoint(target, parsed.sshRoute, async (endpoint) => {
+        const ownerToken = parsed.sshAuth
+            ? await readRemoteOwnerToken(parsed.sshRoute ?? [])
+            : await resolveAuthOwnerToken(parsed.ownerToken);
+        return authenticateRemote(endpoint, ownerToken);
+    });
+    const remote = {
+        ...authenticated,
+        target,
+        ...(parsed.sshRoute ? { sshRoute: parsed.sshRoute } : {}),
+    };
+    const files = loadDevspaceFiles();
+    const existingAlias = Object.entries(files.auth.remotes ?? {}).find(([, record]) => record.instanceId === remote.instanceId)?.[0];
+    const defaultAlias = parsed.sshRoute
+        ? defaultSshRouteAlias(parsed.sshRoute)
+        : defaultRemoteAlias(remote.target);
+    const alias = parsed.alias?.trim() || existingAlias || defaultAlias;
+    if (!files.auth.instanceId) {
+        ensureForgeRelayInstanceId();
+    }
+    writeForgeRelayRemote(alias, remote);
+    console.log(`Authenticated remote ${alias} (${remote.instanceId}).`);
+}
 async function runDoctor() {
     const files = loadDevspaceFiles();
     console.log(`Config dir: ${files.dir}`);
@@ -282,6 +453,12 @@ function printHelp() {
         "  forgerelay agents ls       List subagent sessions",
         "  forgerelay agents run <profile-or-provider-or-id> [--model <model>] <prompt>",
         "  forgerelay agents show <id>",
+        "  forgerelay auth <target> [--alias <name>] [--token <owner-token>]",
+        "  forgerelay auth -J <ssh-route> <target> [--alias <name>] [--token <owner-token>|--ssh-auth]",
+        "  forgerelay auth list",
+        "  forgerelay auth test <alias>",
+        "  forgerelay auth rename <old-alias> <new-alias>",
+        "  forgerelay auth remove <alias>",
         "  forgerelay -v, --version   Print the installed version",
         "",
         "For temporary tunnels:",

package/dist/config.js

@@ -3,7 +3,7 @@ import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { expandHomePath } from "./roots.js";
 import { mergeHookConfigs, parseHookConfig } from "./hooks.js";
-import { forgerelayAgentsDir, forgerelaySkillsDir, loadForgeRelayFiles, } from "./user-config.js";
+import { forgerelayAgentsDir, forgerelaySkillsDir, generateInstanceId, loadForgeRelayFiles, } from "./user-config.js";
 const DEFAULT_OAUTH_ACCESS_TOKEN_TTL_SECONDS = 60 * 60;
 const DEFAULT_OAUTH_REFRESH_TOKEN_TTL_SECONDS = 30 * 24 * 60 * 60;
 const DEFAULT_ARTIFACT_MAX_FILE_BYTES = 100 * 1024 * 1024;
@@ -211,6 +211,7 @@ function resolvePublicDeployment(env, fileConfig, host, port) {
 }
 export function loadConfig(env = process.env) {
     const files = loadForgeRelayFiles(env);
+    const instanceId = files.auth.instanceId?.trim() || generateInstanceId();
     const host = env.HOST ?? files.config.host ?? "127.0.0.1";
     const port = parsePort(env.PORT ?? files.config.port);
     const publicDeployment = resolvePublicDeployment(env, files.config, host, port);
@@ -224,6 +225,8 @@ export function loadConfig(env = process.env) {
         ...(files.config.allowedHosts ?? []),
     ];
     return {
+        instanceId,
+        configDir: files.dir,
         host,
         port,
         oauth: parseOAuthConfig(env, files.auth.ownerToken),

package/dist/oauth/router.js

@@ -7,7 +7,7 @@ import { revocationHandler } from "@modelcontextprotocol/sdk/server/auth/handler
 import { metadataHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/metadata.js";
 import { oauthAuthorizationServerMetadataPath, publicEndpointUrl, } from "./public-url.js";
 export function createForgeRelayAuthRouter(options) {
-    const { provider, issuerUrl, resourceServerUrl, scopesSupported, resourceName } = options;
+    const { provider, cliAuthenticationProvider, instanceId, issuerUrl, resourceServerUrl, scopesSupported, resourceName, } = options;
     const authorizationEndpoint = publicEndpointUrl(issuerUrl, "authorize");
     const tokenEndpoint = publicEndpointUrl(issuerUrl, "token");
     const registrationEndpoint = provider.clientsStore.registerClient
@@ -35,6 +35,26 @@ export function createForgeRelayAuthRouter(options) {
         resource_name: resourceName,
     };
     const router = express.Router();
+    if (cliAuthenticationProvider) {
+        router.post("/auth/cli", express.json({ limit: "4kb" }), (req, res) => {
+            const ownerToken = typeof req.body?.owner_token === "string" ? req.body.owner_token : undefined;
+            const refreshToken = typeof req.body?.refresh_token === "string" ? req.body.refresh_token : undefined;
+            if ((ownerToken ? 1 : 0) + (refreshToken ? 1 : 0) !== 1) {
+                res.status(400).json({ error: "invalid_request" });
+                return;
+            }
+            const tokens = ownerToken
+                ? cliAuthenticationProvider.issueCliTokens(ownerToken)
+                : cliAuthenticationProvider.exchangeCliRefreshToken(refreshToken);
+            if (!tokens) {
+                res.status(401).json({ error: "invalid_grant" });
+                return;
+            }
+            res.setHeader("Cache-Control", "no-store");
+            res.setHeader("Pragma", "no-cache");
+            res.status(200).json({ ...tokens, ...(instanceId ? { instance_id: instanceId } : {}) });
+        });
+    }
     router.use("/authorize", authorizationHandler({ provider }));
     router.use("/token", tokenHandler({ provider }));
     if (provider.clientsStore.registerClient) {

package/dist/oauth-provider.js

@@ -3,6 +3,7 @@ import { AccessDeniedError, InvalidGrantError, InvalidRequestError, InvalidToken
 import { checkResourceAllowed, resourceUrlFromServerUrl } from "@modelcontextprotocol/sdk/shared/auth-utils.js";
 import { SqliteOAuthClientsStore, SqliteOAuthStore } from "./oauth-store.js";
 const CODE_TTL_MS = 5 * 60 * 1000;
+const CLI_CLIENT_ID = "forgerelay-cli";
 function randomToken() {
     return randomBytes(32).toString("base64url");
 }
@@ -85,6 +86,15 @@ export class SingleUserOAuthProvider {
         this.config = config;
         this.resourceServerUrl = resourceUrlFromServerUrl(resourceServerUrl);
         this.oauthStore = new SqliteOAuthStore(stateDir);
+        this.oauthStore.ensureClient({
+            client_id: CLI_CLIENT_ID,
+            client_id_issued_at: Math.floor(Date.now() / 1000),
+            client_name: "ForgeRelay CLI",
+            redirect_uris: [],
+            token_endpoint_auth_method: "none",
+            grant_types: ["refresh_token"],
+            response_types: [],
+        });
         this.clientsStore = new SqliteOAuthClientsStore(this.oauthStore, config.allowedRedirectHosts);
     }
     async authorize(client, params, res) {
@@ -145,11 +155,10 @@ export class SingleUserOAuthProvider {
         return this.issueTokens(client.client_id, record.params.scopes ?? this.config.scopes, record.params.resource);
     }
     async exchangeRefreshToken(client, refreshToken, scopes, resource) {
-        const refreshTokenHash = hashToken(refreshToken);
-        const record = this.oauthStore.getRefreshToken(refreshTokenHash);
-        if (!record || record.clientId !== client.client_id || record.expiresAt < Math.floor(Date.now() / 1000)) {
+        const refresh = this.validRefreshToken(refreshToken, client.client_id);
+        if (!refresh)
             throw new InvalidGrantError("Invalid refresh token");
-        }
+        const { refreshTokenHash, record } = refresh;
         if (resource && !checkResourceAllowed({ requestedResource: resource, configuredResource: this.resourceServerUrl })) {
             throw new InvalidGrantError("Invalid resource");
         }
@@ -159,6 +168,17 @@ export class SingleUserOAuthProvider {
         }
         return this.issueTokens(client.client_id, requestedScopes, resource ?? (record.resource ? new URL(record.resource) : undefined), refreshTokenHash);
     }
+    issueCliTokens(ownerToken) {
+        if (!safeEquals(ownerToken, this.config.ownerToken))
+            return undefined;
+        return this.issueTokens(CLI_CLIENT_ID, this.config.scopes, this.resourceServerUrl);
+    }
+    exchangeCliRefreshToken(refreshToken) {
+        const refresh = this.validRefreshToken(refreshToken, CLI_CLIENT_ID);
+        if (!refresh)
+            return undefined;
+        return this.issueTokens(CLI_CLIENT_ID, refresh.record.scopes, refresh.record.resource ? new URL(refresh.record.resource) : this.resourceServerUrl, refresh.refreshTokenHash);
+    }
     async verifyAccessToken(token) {
         const record = this.oauthStore.getAccessToken(hashToken(token));
         if (!record || record.expiresAt < Math.floor(Date.now() / 1000)) {
@@ -181,6 +201,14 @@ export class SingleUserOAuthProvider {
         this.codes.clear();
         this.oauthStore.close();
     }
+    validRefreshToken(refreshToken, clientId) {
+        const refreshTokenHash = hashToken(refreshToken);
+        const record = this.oauthStore.getRefreshToken(refreshTokenHash);
+        if (!record || record.clientId !== clientId || record.expiresAt < Math.floor(Date.now() / 1000)) {
+            return undefined;
+        }
+        return { refreshTokenHash, record };
+    }
     pruneExpiredAuthorizationCodes(nowMs = Date.now()) {
         for (const [code, record] of this.codes) {
             if (record.expiresAtMs < nowMs)

package/dist/oauth-store.js

@@ -25,6 +25,15 @@ export class SqliteOAuthStore {
             .get(clientId);
         return row ? JSON.parse(row.client_json) : undefined;
     }
+    ensureClient(client) {
+        const existing = this.getClient(client.client_id);
+        if (existing)
+            return existing;
+        this.database.sqlite
+            .prepare("insert into oauth_clients (client_id, client_json, issued_at) values (?, ?, ?)")
+            .run(client.client_id, JSON.stringify(client), client.client_id_issued_at);
+        return client;
+    }
     registerClient(client, allowedRedirectHosts) {
         if (!client.redirect_uris.every((uri) => redirectHostAllowed(String(uri), allowedRedirectHosts))) {
             throw new InvalidRequestError("Client redirect_uri is not allowed for this ForgeRelay server");

package/dist/remote-auth.js

@@ -0,0 +1,110 @@
+import { readFileSync } from "node:fs";
+import { UnauthorizedError } from "@modelcontextprotocol/sdk/client/auth.js";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport, StreamableHTTPError, } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { publicEndpointUrl } from "./oauth/public-url.js";
+const REMOTE_AUTH_TIMEOUT_MS = 15_000;
+const packageVersion = readForgeRelayVersion();
+export function normalizeRemoteServiceTarget(value) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error("Missing remote service target.");
+    const url = new URL(trimmed.includes("://") ? trimmed : `http://${trimmed}`);
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error(`Unsupported remote service protocol: ${url.protocol}`);
+    }
+    if (url.username || url.password) {
+        throw new Error("Remote service target must not contain credentials.");
+    }
+    if (url.search || url.hash) {
+        throw new Error("Remote service target must not contain a query or fragment.");
+    }
+    url.pathname = url.pathname.replace(/\/+$/, "");
+    return url.toString().replace(/\/$/, "");
+}
+export function defaultRemoteAlias(target) {
+    const hostname = new URL(target).hostname;
+    return hostname.replace(/^\[|\]$/g, "");
+}
+export async function authenticateRemote(targetInput, ownerToken) {
+    const target = normalizeRemoteServiceTarget(targetInput);
+    return exchangeCliCredential(target, { owner_token: ownerToken });
+}
+export async function refreshRemoteAuthentication(remote, endpointInput = remote.target) {
+    const refreshed = await exchangeCliCredential(normalizeRemoteServiceTarget(endpointInput), { refresh_token: remote.refreshToken });
+    if (refreshed.instanceId !== remote.instanceId) {
+        throw new Error(`Remote instance changed from ${remote.instanceId} to ${refreshed.instanceId}; refusing to update stored credentials.`);
+    }
+    return {
+        ...remote,
+        accessToken: refreshed.accessToken,
+        refreshToken: refreshed.refreshToken,
+        accessTokenExpiresAt: refreshed.accessTokenExpiresAt,
+        scope: refreshed.scope,
+    };
+}
+export function isRemoteMcpUnauthorized(error) {
+    return error instanceof UnauthorizedError ||
+        (error instanceof StreamableHTTPError && error.code === 401);
+}
+export async function withRemoteMcpClient(remote, endpointInput, operation) {
+    const endpoint = normalizeRemoteServiceTarget(endpointInput);
+    const client = new Client({ name: "forgerelay-cli", version: packageVersion });
+    const transport = new StreamableHTTPClientTransport(publicEndpointUrl(endpoint, "mcp"), {
+        requestInit: {
+            headers: { Authorization: `Bearer ${remote.accessToken}` },
+        },
+    });
+    try {
+        await client.connect(transport);
+        return await operation(client);
+    }
+    finally {
+        await client.close().catch(() => undefined);
+    }
+}
+export async function verifyRemoteMcp(remote, endpointInput = remote.target) {
+    await withRemoteMcpClient(remote, endpointInput, async () => undefined);
+}
+async function exchangeCliCredential(target, credential) {
+    const response = await fetch(publicEndpointUrl(target, "auth/cli"), {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(credential),
+        signal: AbortSignal.timeout(REMOTE_AUTH_TIMEOUT_MS),
+    });
+    if (!response.ok) {
+        let reason = response.statusText || `HTTP ${response.status}`;
+        try {
+            const body = await response.json();
+            if (typeof body.error === "string" && body.error)
+                reason = body.error;
+        }
+        catch {
+            // Keep the status-derived error without exposing the submitted secret.
+        }
+        throw new Error(`Remote authentication failed: ${reason}`);
+    }
+    const body = await response.json();
+    if (typeof body.instance_id !== "string" || !body.instance_id.trim()) {
+        throw new Error("Remote authentication response did not include an instance id.");
+    }
+    if (typeof body.access_token !== "string" || typeof body.refresh_token !== "string") {
+        throw new Error("Remote authentication response did not include the required tokens.");
+    }
+    return {
+        instanceId: body.instance_id,
+        target,
+        accessToken: body.access_token,
+        refreshToken: body.refresh_token,
+        accessTokenExpiresAt: Math.floor(Date.now() / 1000) + (body.expires_in ?? 0),
+        ...(body.scope ? { scope: body.scope } : {}),
+    };
+}
+function readForgeRelayVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+    if (typeof packageJson.version !== "string" || packageJson.version.length === 0) {
+        throw new Error("Unable to read ForgeRelay package version.");
+    }
+    return packageJson.version;
+}