Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

feat(device-link): 扩展远程插件原设置页通信契约

nana1e58e2575f7e
diff --git a/packages/device-link/src/__tests__/pluginSettings.test.ts b/packages/device-link/src/__tests__/pluginSettings.test.ts
new file mode 100644
index 0000000000..7a5b7e57bf
--- /dev/null
+++ b/packages/device-link/src/__tests__/pluginSettings.test.ts
@@ -0,0 +1,93 @@
+import { describe, expect, it } from "vitest";
+import { parsePluginOauthRequest } from "../pluginOauth.js";
+import {
+ parsePluginSettingsRequest,
+ type PluginSettingsCommand,
+} from "../pluginSettings.js";
+
+const request = (command: unknown) => ({
+ op: "settings",
+ id: "page-1",
+ command,
+});
+describe("sealed original settings commands", () => {
+ it.each<PluginSettingsCommand>([
+ { kind: "fetch", path: "/kv", method: "GET" },
+ {
+ kind: "fetch",
+ path: "/secrets/key",
+ method: "PUT",
+ body: '{"value":"fixture"}',
+ },
+ { kind: "asset", path: "settings.html", offset: 0 },
+ { kind: "subscribe", channels: ["one", "two:settings"] },
+ { kind: "unsubscribe", channel: "one" },
+ { kind: "post", channel: "one", data: { type: "status" } },
+ { kind: "poll", after: 0 },
+ { kind: "confirm", requestId: "confirm-1", accepted: true },
+ {
+ kind: "answer-directory",
+ requestId: "directory-1",
+ path: "/target/folder",
+ },
+ { kind: "authorize", path: "/oauth/account/connect" },
+ { kind: "authorization-result", requestId: "authorization-1" },
+ { kind: "close" },
+ ])("parses the settings envelope for $kind", (command) => {
+ expect(parsePluginSettingsRequest(request(command))).toEqual(
+ request(command),
+ );
+ expect(parsePluginOauthRequest(request(command))).toEqual(request(command));
+ });
+ it("bounds UTF-8 request bodies and serialized channel data before dispatch", () => {
+ const command = {
+ kind: "fetch",
+ path: "/kv",
+ method: "PUT",
+ body: "é".repeat(32_768),
+ };
+ expect(parsePluginSettingsRequest(request(command))).not.toBeNull();
+ expect(
+ parsePluginSettingsRequest(
+ request({ ...command, body: command.body + "x" }),
+ ),
+ ).toBeNull();
+ expect(
+ parsePluginSettingsRequest(
+ request({ kind: "post", channel: "one", data: "x".repeat(49_152) }),
+ ),
+ ).toBeNull();
+ });
+ it.each([
+ { kind: "fetch", path: "/kv", method: "PATCH" },
+ { kind: "fetch", path: "/kv", method: "GET", token: "unexpected" },
+ { kind: "asset", path: "settings.html", offset: -1 },
+ {
+ kind: "subscribe",
+ channels: Array.from({ length: 17 }, (_, index) => "channel-" + index),
+ },
+ { kind: "post", channel: "unsafe/channel", data: {} },
+ { kind: "poll", after: Number.MAX_SAFE_INTEGER + 1 },
+ { kind: "confirm", requestId: "confirm-1", accepted: "yes" },
+ { kind: "answer-directory", requestId: "directory-1", path: 42 },
+ { kind: "authorization-result", requestId: "../elsewhere" },
+ { kind: "close", path: "/kv" },
+ { kind: "unknown" },
+ ])("rejects malformed or ambiguous $kind commands", (command) => {
+ expect(parsePluginSettingsRequest(request(command))).toBeNull();
+ });
+ it("rejects foreign envelope fields and page identities", () => {
+ expect(
+ parsePluginSettingsRequest({
+ ...request({ kind: "close" }),
+ id: "p".repeat(129),
+ }),
+ ).toBeNull();
+ expect(
+ parsePluginSettingsRequest({
+ ...request({ kind: "close" }),
+ token: "unexpected",
+ }),
+ ).toBeNull();
+ });
+});
diff --git a/packages/device-link/src/index.ts b/packages/device-link/src/index.ts
index 888464433d..b0206d5b9f 100644
--- a/packages/device-link/src/index.ts
+++ b/packages/device-link/src/index.ts
@@ -48,13 +48,14 @@ export * from "./providerShareEnvelope.js";
export * from "./providerGroup.js";
export * from "./modelFavorites.js";
export * from "./sessionListTransport.js";
-export * from './sessionMessageReuse.js';
+export * from "./sessionMessageReuse.js";
export * from "./clipboardSync.js";
export * from "./clipboardSyncFailure.js";
export * from "./clipboardTransfer.js";
export * from "./pluginOauth.js";
+export * from "./pluginSettings.js";
export * from "./pluginAuthorization.js";
export * from "./pluginSecretSubmission.js";
export * from "./pluginConnectionSubmission.js";
@@ -66,4 +67,4 @@ export * from "./taskMigration.js";
export * from "./remoteAgent.js";
export * from "./orcaRemoteWorker.js";
export * from "./companionCloud.js";
-export * from './pluginPages.js';
+export * from "./pluginPages.js";
diff --git a/packages/device-link/src/pluginOauth.ts b/packages/device-link/src/pluginOauth.ts
index c081befa7b..ec89827767 100644
--- a/packages/device-link/src/pluginOauth.ts
+++ b/packages/device-link/src/pluginOauth.ts
@@ -1,18 +1,30 @@
-/** Host-to-Host OAuth control only. Never expose its replies to a Renderer. */
+import {
+ parsePluginSettingsRequest,
+ type PluginSettingsRequest,
+} from "./pluginSettings.js";
+
+/** Host-to-Host encrypted control only. Never expose its envelope replies to a Renderer. */
export const PLUGIN_OAUTH_CHANNEL = "device-link:plugin-oauth:v3";
export const PLUGIN_OAUTH_LOCAL_CHANNEL = "plugin-oauth:assist";
export const PLUGIN_OAUTH_TTL_MS = 5 * 60_000;
/**
- * Sealed JSON body limits. A Host offer may carry one 代输入 step screenshot;
- * what the owner device sends back stays as small as before.
+ * Sealed JSON limits: offers may contain one 代输入 screenshot; callbacks may
+ * contain a settings request body. Each inner operation retains its own limits.
*/
-export const PLUGIN_OAUTH_SEALED_MAX_BYTES = { offer: 480_000, callback: 32_000 } as const;
+export const PLUGIN_OAUTH_SEALED_MAX_BYTES = {
+ offer: 480_000,
+ callback: 144_000,
+} as const;
/** A well-formed base64url box for a direction: IV (12) + body + tag (16). */
-export function isPluginOauthBox(direction: "offer" | "callback", box: unknown): box is string {
+export function isPluginOauthBox(
+ direction: "offer" | "callback",
+ box: unknown,
+): box is string {
return (
typeof box === "string" &&
box.length >= 40 &&
- box.length <= Math.ceil(((PLUGIN_OAUTH_SEALED_MAX_BYTES[direction] + 28) * 4) / 3) &&
+ box.length <=
+ Math.ceil(((PLUGIN_OAUTH_SEALED_MAX_BYTES[direction] + 28) * 4) / 3) &&
/^[A-Za-z0-9_-]+$/.test(box)
);
}
@@ -24,6 +36,7 @@ export interface PluginOauthAction {
}
export type PluginOauthRequest =
+ | PluginSettingsRequest
| { op: "capabilities" }
| ({
op: "start";
@@ -69,9 +82,13 @@ export function oauthId(v: unknown): v is string {
return typeof v === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(v);
}
export function oauthGhostId(value: unknown): value is string {
- return oauthId(value) ||
+ return (
+ oauthId(value) ||
(typeof value === "string" &&
- /^_ns__[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?__[a-z0-9][a-z0-9-]{0,31}$/.test(value));
+ /^_ns__[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?__[a-z0-9][a-z0-9-]{0,31}$/.test(
+ value,
+ ))
+ );
}
export function parsePluginOauthAction(
value: unknown,
@@ -98,6 +115,7 @@ export function parsePluginOauthRequest(
value: unknown,
): PluginOauthRequest | null {
if (!record(value)) return null;
+ if (value.op === "settings") return parsePluginSettingsRequest(value);
if (value.op === "capabilities" && exact(value, ["op"]))
return { op: value.op };
if (
diff --git a/packages/device-link/src/pluginSettings.ts b/packages/device-link/src/pluginSettings.ts
new file mode 100644
index 0000000000..d42bb413ba
--- /dev/null
+++ b/packages/device-link/src/pluginSettings.ts
@@ -0,0 +1,131 @@
+export const PLUGIN_SETTINGS_ACTION = "settings-page";
+const oauthId = (value: unknown): value is string =>
+ typeof value === "string" && /^[a-zA-Z0-9_-]{1,128}$/.test(value);
+export type PluginSettingsCommand =
+ | { kind: "fetch"; path: string; method: string; body?: string }
+ | { kind: "asset"; path: string; offset: number }
+ | { kind: "subscribe"; channels: string[] }
+ | { kind: "unsubscribe"; channel: string }
+ | { kind: "post"; channel: string; data: unknown }
+ | { kind: "poll"; after: number }
+ | { kind: "confirm"; requestId: string; accepted: boolean }
+ | { kind: "answer-directory"; requestId: string; path: string | null }
+ | { kind: "authorize"; path: string; body?: string }
+ | { kind: "authorization-result"; requestId: string }
+ | { kind: "close" };
+
+/** Only accepted inside a signed, encrypted v3 exchange bound to a settings-page lease. */
+export interface PluginSettingsRequest {
+ op: "settings";
+ id: string;
+ command: PluginSettingsCommand;
+}
+
+export function parsePluginSettingsRequest(
+ raw: unknown,
+): PluginSettingsRequest | null {
+ if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+ const v = raw as Record<string, unknown>;
+ if (
+ Object.keys(v).length !== 3 ||
+ v.op !== "settings" ||
+ !oauthId(v.id) ||
+ !v.command ||
+ typeof v.command !== "object" ||
+ Array.isArray(v.command)
+ )
+ return null;
+ const c = v.command as Record<string, unknown>;
+ const exact = (keys: string[]) =>
+ Object.keys(c).length === keys.length &&
+ keys.every((k) => Object.hasOwn(c, k));
+ const path = (p: unknown): p is string =>
+ typeof p === "string" &&
+ p.length > 0 &&
+ p.length <= 2048 &&
+ !/[\x00-\x1f]/.test(p);
+ const body =
+ c.body === undefined ||
+ (typeof c.body === "string" &&
+ new TextEncoder().encode(c.body).length <= 65_536);
+ const channel = (name: unknown): name is string =>
+ typeof name === "string" &&
+ /^[a-zA-Z0-9][a-zA-Z0-9._:-]{0,127}$/.test(name);
+ let valid = false;
+ switch (c.kind) {
+ case "fetch":
+ valid =
+ exact([
+ "kind",
+ "path",
+ "method",
+ ...(c.body === undefined ? [] : ["body"]),
+ ]) &&
+ path(c.path) &&
+ ["GET", "PUT", "POST", "DELETE"].includes(c.method as string) &&
+ body;
+ break;
+ case "asset":
+ valid =
+ exact(["kind", "path", "offset"]) &&
+ path(c.path) &&
+ Number.isSafeInteger(c.offset) &&
+ (c.offset as number) >= 0;
+ break;
+ case "subscribe":
+ valid =
+ exact(["kind", "channels"]) &&
+ Array.isArray(c.channels) &&
+ c.channels.length <= 16 &&
+ c.channels.every(channel);
+ break;
+ case "post":
+ try {
+ valid =
+ exact(["kind", "channel", "data"]) &&
+ channel(c.channel) &&
+ new TextEncoder().encode(JSON.stringify(c.data)).length <= 49_152;
+ } catch {
+ return null;
+ }
+ break;
+ case "unsubscribe":
+ valid = exact(["kind", "channel"]) && channel(c.channel);
+ break;
+ case "poll":
+ valid =
+ exact(["kind", "after"]) &&
+ Number.isSafeInteger(c.after) &&
+ (c.after as number) >= 0;
+ break;
+ case "confirm":
+ valid =
+ exact(["kind", "requestId", "accepted"]) &&
+ oauthId(c.requestId) &&
+ typeof c.accepted === "boolean";
+ break;
+ case "answer-directory":
+ valid =
+ exact(["kind", "requestId", "path"]) &&
+ oauthId(c.requestId) &&
+ (c.path === null ||
+ (typeof c.path === "string" &&
+ c.path.length > 0 &&
+ c.path.length <= 4096 &&
+ !/[\x00-\x1f]/.test(c.path)));
+ break;
+ case "authorize":
+ valid =
+ exact(["kind", "path", ...(c.body === undefined ? [] : ["body"])]) &&
+ path(c.path) &&
+ body;
+ break;
+ case "authorization-result":
+ valid = exact(["kind", "requestId"]) && oauthId(c.requestId);
+ break;
+ case "close":
+ valid = exact(["kind"]);
+ break;
+ }
+ return valid ? (v as unknown as PluginSettingsRequest) : null;
+}