@dooc-dev/dooc 0.0.0-stage → 0.0.1

package/dist/plugins/runtime.js

@@ -0,0 +1,339 @@
+import { createHash, randomBytes } from "node:crypto";
+import { validatePluginActionRequest, validatePluginActions, validatePluginActionValues, } from "./actions.js";
+import { fetchPluginJson, httpsUrl, isPluginError, PluginError, parseOAuthToken, validatePlugins, } from "./oauth.js";
+import { parsePluginUrl, validatePluginView } from "./view.js";
+const nonce = () => randomBytes(32).toString("base64url");
+const expired = () => new PluginError(401, "Connect this plugin again");
+const expiry = (token) => token.expires_in === undefined ? Infinity : Date.now() + token.expires_in * 1000;
+export const createPluginRuntime = (definitions, transport) => {
+    const plugins = new Map(validatePlugins(definitions).map((plugin) => [plugin.id, plugin]));
+    // shortcut: sessions and tokens live in memory for eight hours; add an OS credential store for persistent login.
+    const sessions = new Map();
+    const sessionFor = (id) => {
+        const session = sessions.get(id);
+        if (!session || session.expires <= Date.now()) {
+            sessions.delete(id);
+            throw expired();
+        }
+        return session;
+    };
+    const pluginFor = (id) => {
+        const plugin = plugins.get(id);
+        if (!plugin)
+            throw new PluginError(404, "Plugin is not configured");
+        return plugin;
+    };
+    const exchange = async (plugin, fields) => {
+        const { oauth } = plugin;
+        const body = new URLSearchParams({ ...fields, client_id: oauth.clientId });
+        if (oauth.clientSecret)
+            body.set("client_secret", oauth.clientSecret);
+        const result = await fetchPluginJson(oauth.tokenUrl, {
+            method: "POST",
+            body,
+            headers: { accept: "application/json" },
+        }, true, transport);
+        if (!result ||
+            typeof result !== "object" ||
+            "error" in result ||
+            ("ok" in result && result.ok === false)) {
+            if (result &&
+                typeof result === "object" &&
+                "error" in result &&
+                result.error === "invalid_grant")
+                throw expired();
+            throw new PluginError(502, "OAuth exchange failed");
+        }
+        try {
+            return parseOAuthToken(oauth.parseToken ? oauth.parseToken(result) : result);
+        }
+        catch {
+            throw new PluginError(502, "Invalid OAuth token response");
+        }
+    };
+    const context = (plugin, accessToken, write = false, check = () => { }) => ({
+        request: async (source, init) => {
+            check();
+            if (plugins.get(plugin.id) !== plugin)
+                throw expired();
+            const url = httpsUrl(source);
+            if (!plugin.apiOrigins.includes(url.origin))
+                throw new PluginError(400, "Plugin API origin is not allowed");
+            if (init?.method !== undefined &&
+                !(write ? ["GET", "POST", "PUT", "PATCH", "DELETE"] : ["GET", "POST"]).includes(init.method))
+                throw new PluginError(400, "Invalid plugin request method");
+            return fetchPluginJson(url.href, {
+                method: init?.method ?? "GET",
+                headers: {
+                    authorization: `Bearer ${accessToken}`,
+                    accept: "application/json",
+                    ...(init?.body === undefined ? {} : { "content-type": "application/json" }),
+                },
+                ...(init?.body === undefined ? {} : { body: JSON.stringify(init.body) }),
+            }, false, transport);
+        },
+    });
+    const assertCurrent = (id, pluginId, connection) => {
+        if (sessionFor(id).connections.get(pluginId) !== connection)
+            throw expired();
+    };
+    const unregister = (pluginId) => {
+        plugins.delete(pluginId);
+        for (const session of sessions.values()) {
+            session.connections.delete(pluginId);
+            session.attempts.delete(pluginId);
+        }
+    };
+    const access = async (id, pluginId, source, run) => {
+        let url;
+        try {
+            url = parsePluginUrl(source);
+        }
+        catch {
+            throw new PluginError(400, "Invalid service URL");
+        }
+        const session = sessionFor(id);
+        const plugin = pluginFor(pluginId);
+        if (!plugin.matches(url))
+            throw new PluginError(400, "URL is not supported by this plugin");
+        const connection = session.connections.get(pluginId);
+        if (!connection)
+            throw expired();
+        try {
+            if (connection.expires <= Date.now() + 30_000) {
+                const refreshToken = connection.token.refresh_token;
+                if (!refreshToken)
+                    throw expired();
+                connection.refreshing ??= (async () => {
+                    try {
+                        const token = await exchange(plugin, {
+                            grant_type: "refresh_token",
+                            refresh_token: refreshToken,
+                        });
+                        assertCurrent(id, pluginId, connection);
+                        connection.token = {
+                            ...token,
+                            refresh_token: token.refresh_token ?? refreshToken,
+                            scope: token.scope ?? connection.token.scope,
+                        };
+                        connection.expires = expiry(token);
+                    }
+                    finally {
+                        connection.refreshing = undefined;
+                    }
+                })();
+                await connection.refreshing;
+            }
+            assertCurrent(id, pluginId, connection);
+            const result = await run(plugin, url, connection);
+            assertCurrent(id, pluginId, connection);
+            return result;
+        }
+        catch (error) {
+            if (isPluginError(error) &&
+                error.status === 401 &&
+                session.connections.get(pluginId) === connection)
+                session.connections.delete(pluginId);
+            throw error;
+        }
+    };
+    return {
+        resolve(source) {
+            let url;
+            try {
+                url = parsePluginUrl(source);
+            }
+            catch {
+                throw new PluginError(400, "Invalid service URL");
+            }
+            return [...plugins.values()].find((plugin) => plugin.matches(url))?.id;
+        },
+        register(plugin) {
+            validatePlugins([plugin]);
+            unregister(plugin.id);
+            plugins.set(plugin.id, { ...plugin });
+        },
+        unregister,
+        createSession() {
+            for (const [id, session] of sessions)
+                if (session.expires <= Date.now())
+                    sessions.delete(id);
+            if (sessions.size >= 128)
+                throw new PluginError(503, "Too many plugin sessions");
+            const id = nonce();
+            sessions.set(id, {
+                expires: Date.now() + 8 * 60 * 60 * 1000,
+                connections: new Map(),
+                attempts: new Map(),
+            });
+            return id;
+        },
+        hasSession(id) {
+            try {
+                sessionFor(id);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+        connect(id, pluginId, redirectUri) {
+            const session = sessionFor(id);
+            const plugin = pluginFor(pluginId);
+            const redirect = new URL(redirectUri);
+            if (redirect.protocol !== "http:" ||
+                !["localhost", "127.0.0.1", "[::1]"].includes(redirect.hostname) ||
+                redirect.username ||
+                redirect.password ||
+                redirect.search ||
+                redirect.hash ||
+                redirect.pathname !== `/api/plugins/callback/${pluginId}`)
+                throw new PluginError(400, "OAuth callback must use the local viewer");
+            const attempt = {
+                state: nonce(),
+                verifier: nonce(),
+                redirectUri,
+                expires: Date.now() + 10 * 60 * 1000,
+            };
+            session.connections.delete(pluginId);
+            session.attempts.set(pluginId, attempt);
+            const url = new URL(plugin.oauth.authorizationUrl);
+            for (const [key, value] of Object.entries(plugin.oauth.authorizationParams ?? {}))
+                url.searchParams.set(key, value);
+            url.searchParams.set(plugin.oauth.scopeParameter ?? "scope", plugin.oauth.scopes.join(plugin.oauth.scopeSeparator ?? " "));
+            for (const [key, value] of Object.entries({
+                client_id: plugin.oauth.clientId,
+                redirect_uri: redirectUri,
+                response_type: "code",
+                state: attempt.state,
+                code_challenge: createHash("sha256").update(attempt.verifier).digest("base64url"),
+                code_challenge_method: "S256",
+            }))
+                url.searchParams.set(key, value);
+            return url.href;
+        },
+        async callback(id, pluginId, redirectUri, params) {
+            const session = sessionFor(id);
+            const plugin = pluginFor(pluginId);
+            const attempt = session.attempts.get(pluginId);
+            if (!attempt?.state ||
+                attempt.expires <= Date.now() ||
+                attempt.redirectUri !== redirectUri ||
+                params.getAll("state").length !== 1 ||
+                params.get("state") !== attempt.state)
+                throw new PluginError(400, "Invalid or expired OAuth state");
+            // Consume the state before exchanging a code so callbacks cannot be replayed.
+            attempt.state = "";
+            const code = params.get("code");
+            if (params.has("error") || !code || params.getAll("code").length !== 1)
+                throw new PluginError(400, "OAuth authorization was not completed");
+            const token = await exchange(plugin, {
+                grant_type: "authorization_code",
+                code,
+                redirect_uri: redirectUri,
+                code_verifier: attempt.verifier,
+            });
+            const expires = expiry(token);
+            const user = await plugin.identifyUser(context(plugin, token.access_token));
+            if (!user ||
+                typeof user.id !== "string" ||
+                !user.id ||
+                typeof user.name !== "string" ||
+                !user.name ||
+                user.id.length > 512 ||
+                user.name.length > 512)
+                throw new PluginError(502, "Plugin could not identify the authorized user");
+            if (sessionFor(id).attempts.get(pluginId) !== attempt)
+                throw expired();
+            session.attempts.delete(pluginId);
+            session.connections.set(pluginId, {
+                token,
+                expires,
+                user: { id: user.id, name: user.name },
+            });
+        },
+        disconnect(id, pluginId) {
+            const session = sessionFor(id);
+            session.connections.delete(pluginId);
+            session.attempts.delete(pluginId);
+        },
+        read(id, pluginId, source) {
+            return access(id, pluginId, source, async (plugin, url, connection) => ({
+                user: connection.user,
+                view: validatePluginView(await plugin.read(url, {
+                    ...context(plugin, connection.token.access_token, false, () => assertCurrent(id, pluginId, connection)),
+                    user: { ...connection.user },
+                })),
+            }));
+        },
+        actions(id, pluginId, source) {
+            return access(id, pluginId, source, async (plugin, url, connection) => ({
+                user: connection.user,
+                actions: validatePluginActions(plugin.actions && plugin.act
+                    ? await plugin.actions(url, {
+                        ...context(plugin, connection.token.access_token, false, () => assertCurrent(id, pluginId, connection)),
+                        user: { ...connection.user },
+                    })
+                    : []),
+            }));
+        },
+        act(id, pluginId, source, input, requestId) {
+            const operation = validatePluginActionRequest(input);
+            if (typeof requestId !== "string" || !/^[a-zA-Z0-9-]{16,80}$/.test(requestId))
+                throw new PluginError(400, "Invalid operation ID");
+            return access(id, pluginId, source, async (plugin, url, connection) => {
+                const { actions: listActions, act } = plugin;
+                if (!listActions || !act)
+                    throw new PluginError(403, "Plugin operations are not supported");
+                const fingerprint = createHash("sha256")
+                    .update(JSON.stringify([url.href, operation]))
+                    .digest("hex");
+                connection.operations ??= new Map();
+                const requests = connection.operations;
+                let request = requests.get(requestId);
+                if (request && request.fingerprint !== fingerprint)
+                    throw new PluginError(409, "Operation ID was already used for another request");
+                if (!request) {
+                    // shortcut: retain 128 operation results per connection; use durable idempotency for longer sessions.
+                    if (requests.size >= 128)
+                        throw new PluginError(429, "Reconnect before performing more operations");
+                    const previous = connection.writing;
+                    const promise = (async () => {
+                        try {
+                            await previous;
+                        }
+                        catch {
+                            // A failed operation must not block later writes.
+                        }
+                        const check = () => assertCurrent(id, pluginId, connection);
+                        check();
+                        const user = { ...connection.user };
+                        const actions = validatePluginActions(await listActions.call(plugin, url, {
+                            ...context(plugin, connection.token.access_token, false, check),
+                            user,
+                        }));
+                        const action = actions.find((a) => a.id === operation.id);
+                        if (!action)
+                            throw new PluginError(403, "Operation is not available for this user and URL");
+                        validatePluginActionValues(action, operation);
+                        check();
+                        const result = await act.call(plugin, url, {
+                            ...context(plugin, connection.token.access_token, true, check),
+                            user,
+                        }, operation);
+                        if (!result ||
+                            typeof result.message !== "string" ||
+                            result.message.length > 4000 ||
+                            (result.deleted !== undefined && typeof result.deleted !== "boolean"))
+                            throw new PluginError(502, "Invalid plugin operation result");
+                        return result;
+                    })();
+                    connection.writing = promise;
+                    request = { fingerprint, promise };
+                    requests.set(requestId, request);
+                }
+                return { user: connection.user, result: await request.promise };
+            });
+        },
+    };
+};

package/dist/plugins/types.d.ts

@@ -0,0 +1,56 @@
+/** OAuth credentials belong in environment variables, never in document source. */
+export interface PluginOAuth {
+    authorizationUrl: string;
+    tokenUrl: string;
+    clientId: string;
+    clientSecret?: string;
+    scopes: readonly string[];
+    /** Provider-specific user authorization parameters, such as actor=user. */
+    authorizationParams?: Readonly<Record<string, string>>;
+    scopeParameter?: string;
+    scopeSeparator?: string;
+    /** Normalize provider responses; select the user token and reject bot/app tokens. */
+    parseToken?: (response: unknown) => OAuthToken;
+}
+export interface OAuthToken {
+    access_token: string;
+    refresh_token?: string;
+    expires_in?: number;
+    scope?: string | string[];
+}
+export interface PluginUser {
+    /** Include the tenant/workspace in the ID if user IDs are not globally unique. */
+    id: string;
+    name: string;
+}
+export interface PluginContext {
+    /** Authenticated JSON requests to apiOrigins only; credentials never reach the browser. */
+    request: (url: string, init?: {
+        method?: "GET" | "POST";
+        body?: unknown;
+    }) => Promise<unknown>;
+}
+export type { PluginContent, PluginView } from "./view.js";
+import type { PluginAction, PluginActionContext, PluginActionRequest, PluginActionResult } from "./actions.js";
+import type { PluginView } from "./view.js";
+/** Trusted server code injected into the viewer, independently of document configuration. */
+export interface DataPlugin {
+    id: string;
+    /** Match a service URL without fetching it; unmatched embeds remain ordinary links. */
+    matches: (url: URL) => boolean;
+    oauth: PluginOAuth;
+    /** Exact HTTPS origins; API requests and their redirects cannot leave these origins. */
+    apiOrigins: readonly string[];
+    /** Resolve the token's actual user; reject application identities and provider errors. */
+    identifyUser: (context: PluginContext) => Promise<PluginUser>;
+    /** Fetch the matched URL's data using read operations and reject provider-level API errors. */
+    read: (url: URL, context: PluginContext & {
+        user: PluginUser;
+    }) => Promise<PluginView>;
+    /** Resolve operations available to the current user without performing writes. */
+    actions?: (url: URL, context: PluginContext & {
+        user: PluginUser;
+    }) => Promise<PluginAction[]>;
+    /** Recheck provider permissions and resource versions before changing remote data. */
+    act?: (url: URL, context: PluginActionContext, request: PluginActionRequest) => Promise<PluginActionResult>;
+}

package/dist/plugins/types.js

@@ -0,0 +1 @@
+export {};

package/dist/plugins/view.d.ts

@@ -0,0 +1,29 @@
+import { type PluginBlockContent } from "./blocks.js";
+export type PluginContent = PluginBlockContent | {
+    format: "html";
+    html: string;
+    height?: number | "auto";
+} | {
+    format: "json";
+    preset: "card";
+    title: string;
+    text: string;
+} | {
+    format: "json";
+    preset: "list";
+    items: string[];
+} | {
+    format: "json";
+    preset: "table";
+    headers: string[];
+    rows: (string | number | boolean | null)[][];
+} | {
+    format: "json";
+    preset: "code";
+    value: unknown;
+};
+export type PluginView = PluginContent & {
+    collapsed?: PluginContent;
+};
+export declare const validatePluginView: (input: unknown) => PluginView;
+export declare const parsePluginUrl: (input: unknown) => URL;

package/dist/plugins/view.js

@@ -0,0 +1,60 @@
+import { validPluginBlocks } from "./blocks.js";
+const validContent = (view) => {
+    let valid = false;
+    if (view && typeof view === "object") {
+        if (view.format === "blocks")
+            return validPluginBlocks(view);
+        if (view.format === "html")
+            valid =
+                typeof view.html === "string" &&
+                    (view.height === undefined ||
+                        view.height === "auto" ||
+                        (Number.isInteger(view.height) && view.height >= 32 && view.height <= 1200));
+        if (view.format === "json") {
+            switch (view.preset) {
+                case "card":
+                    valid = typeof view.title === "string" && typeof view.text === "string";
+                    break;
+                case "list":
+                    valid =
+                        Array.isArray(view.items) &&
+                            view.items.every((item) => typeof item === "string");
+                    break;
+                case "table":
+                    valid =
+                        Array.isArray(view.headers) &&
+                            view.headers.every((h) => typeof h === "string") &&
+                            Array.isArray(view.rows) &&
+                            view.rows.every((row) => Array.isArray(row) &&
+                                row.length === view.headers.length &&
+                                row.every((cell) => cell === null ||
+                                    ["string", "boolean"].includes(typeof cell) ||
+                                    (typeof cell === "number" && Number.isFinite(cell))));
+                    break;
+                case "code":
+                    valid = view.value !== undefined;
+                    break;
+            }
+        }
+    }
+    return valid;
+};
+export const validatePluginView = (input) => {
+    const encoded = JSON.stringify(input);
+    if (typeof encoded !== "string")
+        throw new Error("Invalid plugin view");
+    if (new TextEncoder().encode(encoded).length > 2 * 1024 * 1024)
+        throw new Error("Plugin view is too large");
+    const view = JSON.parse(encoded);
+    if (!validContent(view) || (view.collapsed !== undefined && !validContent(view.collapsed)))
+        throw new Error("Invalid plugin view");
+    return view;
+};
+export const parsePluginUrl = (input) => {
+    if (typeof input !== "string" || input.length > 4096 || /[\s\\]/.test(input))
+        throw new Error("Expected a service URL");
+    const url = new URL(input);
+    if (!/^https?:$/.test(url.protocol) || url.username || url.password)
+        throw new Error("Expected an HTTP(S) URL without credentials");
+    return url;
+};