@cjhyy/code-shell-server 0.9.26 → 0.9.27

package/dist/links/browser-handoff.d.ts

@@ -0,0 +1,16 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { LinkAuthorization } from "@cjhyy/code-shell-link";
+interface Binding {
+    check(): Promise<void>;
+    complete(callbackUrl: string): Promise<LinkAuthorization>;
+    cancel(): Promise<unknown>;
+}
+/** An external browser carries only OAuth state. The original Host keeps its owner and PKCE. */
+export declare function createLinkBrowserHandoff(now?: () => number): {
+    close(): void;
+    create(job: LinkAuthorization, binding: Binding, origin: string): {
+        launchUrl: string;
+    };
+    handle(req: IncomingMessage, res: ServerResponse): Promise<boolean>;
+};
+export {};

package/dist/links/browser-handoff.js

@@ -0,0 +1,150 @@
+import { randomBytes } from "node:crypto";
+/** An external browser carries only OAuth state. The original Host keeps its owner and PKCE. */
+export function createLinkBrowserHandoff(now = Date.now) {
+    const tickets = new Map();
+    const states = new Map();
+    let closed = false;
+    const forget = (attempt) => {
+        tickets.delete(attempt.ticket);
+        states.delete(attempt.state);
+    };
+    const prune = () => {
+        for (const attempt of states.values())
+            if (attempt.expiresAt <= now())
+                forget(attempt);
+    };
+    const headers = { "Cache-Control": "no-store", "Referrer-Policy": "no-referrer" };
+    const result = (res) => {
+        res.writeHead(303, { ...headers, Location: "/link/authorization-result" });
+        res.end();
+    };
+    return {
+        close() {
+            closed = true;
+            tickets.clear();
+            states.clear();
+        },
+        create(job, binding, origin) {
+            prune();
+            const redirect = job.step?.kind === "redirect" ? job.step : job.redirect;
+            if (closed || job.state !== "pending" || !redirect || states.size >= 128)
+                throw new Error("Browser authorization is unavailable");
+            const authorization = new URL(redirect.authorizationUrl);
+            const callback = new URL(authorization.searchParams.get("redirect_uri") ?? "");
+            const state = authorization.searchParams.get("state");
+            const expiresAt = Math.min(Date.parse(redirect.expiresAt), now() + 600_000);
+            if (!state ||
+                !/^[A-Za-z0-9_-]{32,128}$/.test(state) ||
+                authorization.username ||
+                authorization.password ||
+                authorization.hash ||
+                authorization.pathname !== "/oauth/authorize" ||
+                (authorization.protocol !== "https:" &&
+                    !(authorization.protocol === "http:" &&
+                        ["localhost", "127.0.0.1", "[::1]"].includes(authorization.hostname))) ||
+                authorization.searchParams.getAll("state").length !== 1 ||
+                authorization.searchParams.getAll("redirect_uri").length !== 1 ||
+                authorization.searchParams.get("redirect_uri") !== callback.href ||
+                callback.origin !== origin ||
+                callback.pathname !== "/link/callback" ||
+                callback.search ||
+                callback.hash ||
+                callback.username ||
+                callback.password ||
+                !Number.isFinite(expiresAt) ||
+                expiresAt <= now() ||
+                states.has(state))
+                throw new Error("Invalid browser authorization");
+            const ticket = randomBytes(32).toString("base64url");
+            const attempt = {
+                ticket,
+                state,
+                authorizationUrl: authorization.href,
+                callback,
+                expiresAt,
+                launched: false,
+                completing: false,
+                binding,
+            };
+            tickets.set(ticket, attempt);
+            states.set(state, attempt);
+            return { launchUrl: `${callback.origin}/link/authorize?ticket=${ticket}` };
+        },
+        async handle(req, res) {
+            const url = new URL(req.url ?? "/", "http://localhost");
+            if (!["/link/authorize", "/link/callback", "/link/authorization-result"].includes(url.pathname))
+                return false;
+            if (req.method !== "GET")
+                return false;
+            prune();
+            if (url.pathname === "/link/authorization-result") {
+                res.writeHead(200, {
+                    ...headers,
+                    "Content-Type": "text/html; charset=utf-8",
+                    "Content-Security-Policy": "default-src 'none'; frame-ancestors 'none'",
+                    "X-Content-Type-Options": "nosniff",
+                });
+                res.end('<!doctype html><html lang="zh"><meta charset="utf-8"><title>Link 授权</title><main><h1>Link 授权</h1><p>授权已处理。请返回原工作台查看连接结果；可以关闭此页面。</p></main></html>');
+                return true;
+            }
+            if (url.pathname === "/link/authorize") {
+                const ticket = url.searchParams.get("ticket");
+                const attempt = ticket && tickets.get(ticket);
+                if (!attempt || closed || url.searchParams.size !== 1) {
+                    res.writeHead(410, headers).end("Authorization expired. Return to the workbench.");
+                    return true;
+                }
+                tickets.delete(attempt.ticket);
+                try {
+                    await attempt.binding.check();
+                    if (closed || states.get(attempt.state) !== attempt || attempt.expiresAt <= now())
+                        throw new Error("Authorization expired");
+                    attempt.launched = true;
+                    res.writeHead(303, { ...headers, Location: attempt.authorizationUrl });
+                    res.end();
+                }
+                catch {
+                    forget(attempt);
+                    result(res);
+                }
+                return true;
+            }
+            const state = url.searchParams.get("state");
+            const attempt = state && states.get(state);
+            // Unregistered callbacks belong to the existing same-browser flow.
+            if (!attempt)
+                return false;
+            if (closed ||
+                !attempt.launched ||
+                attempt.completing ||
+                url.searchParams.getAll("state").length !== 1 ||
+                url.searchParams.has("code") === url.searchParams.has("error") ||
+                url.searchParams.getAll("code").length > 1 ||
+                url.searchParams.getAll("error").length > 1) {
+                res.writeHead(400, headers).end("Invalid authorization callback.");
+                return true;
+            }
+            attempt.completing = true;
+            try {
+                await attempt.binding.check();
+                if (closed || states.get(attempt.state) !== attempt || attempt.expiresAt <= now())
+                    throw new Error("Authorization expired");
+                if (url.searchParams.has("error"))
+                    await attempt.binding.cancel();
+                else {
+                    const callback = new URL(attempt.callback);
+                    callback.search = url.search;
+                    await attempt.binding.complete(callback.href);
+                }
+            }
+            catch {
+                // A token exchange is never replayed. The original owner's polling reconciles the result.
+            }
+            finally {
+                forget(attempt);
+            }
+            result(res);
+            return true;
+        },
+    };
+}

package/dist/links/http.d.ts

@@ -1,7 +1,9 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import { type LinkServiceOptions } from "./service.js";
-import type { LinkConnectionInput, LinkOperationContext, TokenConnectionInput } from "./types.js";
+import type { LinkAuthorizationResponse, LinkConnectionInput, LinkOperationContext, TokenConnectionInput } from "./types.js";
 export interface LinkHttpOptions extends LinkServiceOptions {
+    /** Project gateways own the public callback; private runtimes must not advertise it themselves. */
+    browserHandoff?: boolean;
     ownerId: (request: IncomingMessage) => Promise<string | undefined>;
     isAuthorized: (request: IncomingMessage) => Promise<boolean>;
 }
@@ -23,6 +25,9 @@ export declare function createLinkHttp(options: LinkHttpOptions): {
         rename: (context: LinkOperationContext, id: string, label: string, expectedRevision: string) => Promise<import("@cjhyy/code-shell-link").MaskedLinkConnection>;
         disconnect: (context: LinkOperationContext, id: string, expectedRevision: string) => Promise<void>;
         startDeviceAuth: (context: LinkOperationContext, input: LinkConnectionInput) => Promise<import("@cjhyy/code-shell-link").LinkAuthorization>;
+        startAuthorization: (context: LinkOperationContext, input: LinkConnectionInput, rawAuthModeId: unknown) => Promise<import("@cjhyy/code-shell-link").LinkAuthorization>;
+        respondAuthorization: (context: LinkOperationContext, id: string, response: LinkAuthorizationResponse) => Promise<import("@cjhyy/code-shell-link").LinkAuthorization>;
+        refreshRemoteCatalog: (context: LinkOperationContext) => Promise<void>;
         startRemoteAuth: (context: LinkOperationContext, input: LinkConnectionInput) => Promise<import("@cjhyy/code-shell-link").LinkAuthorization>;
         completeRemoteAuth: (context: LinkOperationContext, id: string, callbackUrl: string) => Promise<import("@cjhyy/code-shell-link").LinkAuthorization>;
         retryRemoteCleanup: () => Promise<void>;
@@ -31,7 +36,8 @@ export declare function createLinkHttp(options: LinkHttpOptions): {
         cancelOwner: (ownerId: string) => void;
         close: () => void;
     };
-    close: () => void;
+    close: () => Promise<void>;
     cancelOwner: (ownerId: string) => void;
+    handlePublic: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
     handle(request: IncomingMessage, response: ServerResponse): Promise<boolean>;
 };

package/dist/links/http.js

@@ -1,3 +1,4 @@
+import { createLinkBrowserHandoff } from "./browser-handoff.js";
 import { createLinkService, LinkServiceError, publicLinkError, } from "./service.js";
 const ROOT = "/api/v1/links";
 const MAX_BODY_BYTES = 32 * 1024;
@@ -46,6 +47,7 @@ function fields(input, allowed) {
 /** Host authenticates and validates Origin first; writes independently recheck the same owner. */
 export function createLinkHttp(options) {
     const service = createLinkService(options);
+    const browser = createLinkBrowserHandoff(options.now);
     async function context(request, abandoned) {
         const ownerId = await options.ownerId(request);
         if (!ownerId || !(await options.isAuthorized(request)))
@@ -59,8 +61,12 @@ export function createLinkHttp(options) {
     }
     return {
         service,
-        close: service.close,
+        close: async () => {
+            browser.close();
+            await service.close();
+        },
         cancelOwner: service.cancelOwner,
+        handlePublic: browser.handle,
         async handle(request, response) {
             const url = new URL(request.url ?? "/", "http://localhost");
             if (url.pathname !== ROOT && !url.pathname.startsWith(ROOT + "/"))
@@ -75,14 +81,67 @@ export function createLinkHttp(options) {
                 const owner = await context(request, () => abandoned || request.aborted);
                 const method = request.method;
                 let result;
-                if (url.pathname === ROOT && method === "GET")
-                    result = service.snapshot();
+                if (url.pathname === ROOT && method === "GET") {
+                    await service.refreshRemoteCatalog(owner);
+                    const snapshot = service.snapshot();
+                    const configured = options.remoteLink?.();
+                    result = {
+                        ...snapshot,
+                        capabilities: {
+                            ...snapshot.capabilities,
+                            ...(options.browserHandoff !== false &&
+                                configured &&
+                                new URL(configured.redirectUri).pathname === "/link/callback"
+                                ? { browserHandoff: 1 }
+                                : {}),
+                        },
+                    };
+                }
                 else {
                     const cli = /^\/api\/v1\/links\/providers\/([^/]+)\/cli$/.exec(url.pathname);
                     const connection = /^\/api\/v1\/links\/connections\/([^/]+)$/.exec(url.pathname);
                     const remoteComplete = /^\/api\/v1\/links\/authorizations\/([^/]+)\/complete$/.exec(url.pathname);
+                    const handoff = /^\/api\/v1\/links\/authorizations\/([^/]+)\/browser$/.exec(url.pathname);
                     const authorization = /^\/api\/v1\/links\/authorizations\/([^/]+)$/.exec(url.pathname);
-                    if (remoteComplete && method === "POST") {
+                    const respond = /^\/api\/v1\/links\/authorizations\/([^/]+)\/responses$/.exec(url.pathname);
+                    if (url.pathname === ROOT + "/authorizations" && method === "POST") {
+                        const input = await body(request);
+                        fields(input, [
+                            "providerId",
+                            "methodId",
+                            "label",
+                            "connectionId",
+                            "expectedRevision",
+                            "authModeId",
+                        ]);
+                        result = await service.startAuthorization(owner, input, input.authModeId);
+                    }
+                    else if (handoff && method === "POST") {
+                        fields(await body(request), []);
+                        const id = decodeURIComponent(handoff[1]);
+                        const check = async () => {
+                            const job = await service.authorization(owner, id);
+                            if (job.state !== "pending")
+                                throw new LinkServiceError(409, "conflict");
+                            return job;
+                        };
+                        const configured = options.remoteLink?.();
+                        if (!configured)
+                            throw new LinkServiceError(503, "unavailable");
+                        result = browser.create(await check(), {
+                            check: async () => {
+                                await check();
+                            },
+                            complete: (callbackUrl) => service.completeRemoteAuth(owner, id, callbackUrl),
+                            cancel: () => service.cancelAuthorization(owner, id),
+                        }, new URL(configured.redirectUri).origin);
+                    }
+                    else if (respond && method === "POST") {
+                        const input = await body(request);
+                        fields(input, ["stepId", "operation", "input"]);
+                        result = await service.respondAuthorization(owner, decodeURIComponent(respond[1]), input);
+                    }
+                    else if (remoteComplete && method === "POST") {
                         const input = await body(request);
                         fields(input, ["callbackUrl"]);
                         result = await service.completeRemoteAuth(owner, decodeURIComponent(remoteComplete[1]), input.callbackUrl);

package/dist/links/remote-catalog.d.ts

@@ -0,0 +1,94 @@
+import { type RemoteLinkConfiguration } from "@cjhyy/code-shell-core";
+import { type RemoteLinkProviderId } from "@cjhyy/code-shell-core";
+/** The Host's compiled executors own authority, never remotely supplied presentation metadata. */
+export declare const REMOTE_LINK_ADAPTERS: ({
+    methodId: string;
+    authModeId: string;
+    scopes: string[];
+    id: "github";
+    name: "GitHub";
+    group: "repositories";
+    actions: readonly ["list_repositories", "get_readme", "get_file", "list_issues", "get_issue", "list_pull_requests", "get_pull_request", "create_issue", "get_repository", "get_starred", "set_starred"];
+} | {
+    methodId: string;
+    authModeId: string;
+    scopes: string[];
+    id: "gitlab";
+    name: "GitLab";
+    group: "projects";
+    actions: readonly ["list_projects", "list_issues"];
+} | {
+    methodId: string;
+    authModeId: string;
+    scopes: string[];
+    id: "sentry";
+    name: "Sentry";
+    group: "organizations";
+    actions: readonly ["list_organizations", "list_projects"];
+} | {
+    methodId: string;
+    authModeId: string;
+    scopes: string[];
+    id: "vercel";
+    name: "Vercel";
+    group: "projects";
+    actions: readonly ["list_projects", "list_deployments"];
+} | {
+    methodId: string;
+    authModeId: string;
+    scopes: string[];
+    id: "slack";
+    name: "Slack";
+    group: "channels";
+    actions: readonly ["list_channels", "get_channel_history"];
+} | {
+    methodId: string;
+    authModeId: string;
+    scopes: string[];
+    id: "notion";
+    name: "Notion";
+    group: "pages";
+    actions: readonly ["search", "get_page"];
+} | {
+    methodId: string;
+    authModeId: string;
+    scopes: string[];
+    id: "linear";
+    name: "Linear";
+    group: "teams";
+    actions: readonly ["list_issues", "list_teams"];
+} | {
+    methodId: string;
+    authModeId: string;
+    scopes: string[];
+    id: "todoist";
+    name: "Todoist";
+    group: "projects";
+    actions: readonly ["list_projects", "list_tasks"];
+} | {
+    methodId: string;
+    authModeId: string;
+    scopes: string[];
+    id: "airtable";
+    name: "Airtable";
+    group: "bases";
+    actions: readonly ["list_bases", "list_tables"];
+} | {
+    methodId: string;
+    authModeId: string;
+    scopes: string[];
+    id: "figma";
+    name: "Figma";
+    group: "files";
+    actions: readonly ["get_file", "get_comments"];
+})[];
+export type RemoteProviderId = RemoteLinkProviderId;
+export interface RemoteProviderCapabilities {
+    id: RemoteProviderId;
+    actions: string[];
+    scopes: string[];
+}
+export declare const LEGACY_REMOTE_PROVIDERS: RemoteProviderCapabilities[];
+export declare function readRemoteProviderCatalog(configuration: RemoteLinkConfiguration): Promise<RemoteProviderId[]>;
+/** A legacy v1 service has no catalog. Its one already-reviewed adapter remains compatible. */
+export declare function readRemoteProviderCapabilities(configuration: RemoteLinkConfiguration): Promise<RemoteProviderCapabilities[]>;

package/dist/links/remote-catalog.js

@@ -0,0 +1,90 @@
+import { beginRemoteLinkAuthorization } from "@cjhyy/code-shell-core";
+import { REMOTE_LINK_PROVIDER_ADAPTERS, LEGACY_GITHUB_ACTIONS, } from "@cjhyy/code-shell-core";
+/** The Host's compiled executors own authority, never remotely supplied presentation metadata. */
+export const REMOTE_LINK_ADAPTERS = REMOTE_LINK_PROVIDER_ADAPTERS.map((adapter) => ({
+    ...adapter,
+    methodId: "remote-link",
+    authModeId: "remote-link",
+    scopes: adapter.actions.map((action) => `${adapter.id}:${action}`),
+}));
+export const LEGACY_REMOTE_PROVIDERS = [
+    {
+        id: "github",
+        actions: [...LEGACY_GITHUB_ACTIONS],
+        scopes: LEGACY_GITHUB_ACTIONS.map((action) => `github:${action}`),
+    },
+];
+export async function readRemoteProviderCatalog(configuration) {
+    return (await readRemoteProviderCapabilities(configuration)).map((provider) => provider.id);
+}
+/** A legacy v1 service has no catalog. Its one already-reviewed adapter remains compatible. */
+export async function readRemoteProviderCapabilities(configuration) {
+    const issuer = beginRemoteLinkAuthorization(configuration).configuration.issuer;
+    const response = await fetch(new URL("/api/v1/links/providers", issuer), {
+        redirect: "error",
+        signal: AbortSignal.timeout(5_000),
+        headers: { Accept: "application/json" },
+    });
+    if ([404, 501].includes(response.status)) {
+        await response.body?.cancel();
+        return structuredClone(LEGACY_REMOTE_PROVIDERS);
+    }
+    if (!response.ok || !response.body) {
+        await response.body?.cancel();
+        throw new Error("Link catalog unavailable");
+    }
+    const reader = response.body.getReader();
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 32_768) {
+                await reader.cancel();
+                return [];
+            }
+            chunks.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    let catalog;
+    try {
+        catalog = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+    }
+    catch {
+        return [];
+    }
+    if (catalog?.version !== 1 || !Array.isArray(catalog.providers) || catalog.providers.length > 32)
+        return [];
+    return REMOTE_LINK_ADAPTERS.flatMap((adapter) => {
+        const matches = catalog.providers.filter((item) => item?.id === adapter.id);
+        if (matches.length !== 1)
+            return [];
+        const provider = matches[0];
+        const actions = provider.actions;
+        const scopes = provider.scopes;
+        if (!Array.isArray(actions) ||
+            !actions.length ||
+            actions.length > adapter.actions.length ||
+            new Set(actions).size !== actions.length ||
+            actions.some((action) => !adapter.actions.includes(action)) ||
+            !Array.isArray(scopes) ||
+            scopes.length !== actions.length ||
+            new Set(scopes).size !== scopes.length ||
+            actions.some((action) => !scopes.includes(`${adapter.id}:${action}`)))
+            return [];
+        if (!Array.isArray(provider.methods) ||
+            !provider.methods.some((method) => method?.id === adapter.methodId &&
+                method.authKind === "oauth" &&
+                method.defaultAuthModeId === "browser" &&
+                Array.isArray(method.authModes) &&
+                method.authModes.some((mode) => mode?.id === "browser" && mode.kind === "redirect")))
+            return [];
+        return [{ id: adapter.id, actions: [...actions], scopes: [...scopes] }];
+    });
+}

package/dist/links/service.d.ts

@@ -1,6 +1,7 @@
 import { CredentialStore, type RemoteLinkConfiguration, connectCliLink, getCliLinkStatus, validateLocalLinkToken, type LocalLinkValidationResult } from "@cjhyy/code-shell-core";
+import { readRemoteProviderCatalog } from "./remote-catalog.js";
 import { LinkDeviceOAuthBroker, type LocalBrowserAuthToken } from "./device-oauth.js";
-import type { LinkAuthorization, LinkConnectionInput, LinkErrorCode, LinkOperationContext, LinkSnapshot, MaskedLinkConnection, TokenConnectionInput } from "./types.js";
+import type { LinkAuthorization, LinkAuthorizationResponse, LinkConnectionInput, LinkErrorCode, LinkOperationContext, LinkSnapshot, MaskedLinkConnection, TokenConnectionInput } from "./types.js";
 export declare class LinkServiceError extends Error {
     readonly status: number;
     readonly code: LinkErrorCode;
@@ -20,6 +21,9 @@ export interface LinkServiceOptions {
     cliStatus?: typeof getCliLinkStatus;
     bindCli?: typeof connectCliLink;
     createDeviceBroker?: () => LinkDeviceOAuthBroker;
+    readRemoteCatalog?: typeof readRemoteProviderCatalog;
+    /** Native Host only; remote browser callers may bind existing Host sessions but cannot start login. */
+    allowCliLogin?: boolean;
 }
 /** Trusted host adapter input; deliberately absent from the HTTP API. */
 export type ValidatedLinkAuthentication = {
@@ -48,6 +52,9 @@ export declare function createLinkService(options?: LinkServiceOptions): {
     rename: (context: LinkOperationContext, id: string, label: string, expectedRevision: string) => Promise<MaskedLinkConnection>;
     disconnect: (context: LinkOperationContext, id: string, expectedRevision: string) => Promise<void>;
     startDeviceAuth: (context: LinkOperationContext, input: LinkConnectionInput) => Promise<LinkAuthorization>;
+    startAuthorization: (context: LinkOperationContext, input: LinkConnectionInput, rawAuthModeId: unknown) => Promise<LinkAuthorization>;
+    respondAuthorization: (context: LinkOperationContext, id: string, response: LinkAuthorizationResponse) => Promise<LinkAuthorization>;
+    refreshRemoteCatalog: (context: LinkOperationContext) => Promise<void>;
     startRemoteAuth: (context: LinkOperationContext, input: LinkConnectionInput) => Promise<LinkAuthorization>;
     completeRemoteAuth: (context: LinkOperationContext, id: string, callbackUrl: string) => Promise<LinkAuthorization>;
     retryRemoteCleanup: () => Promise<void>;