runline 0.34.0 → 0.35.0

package/dist/core/engine.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 import { Worker } from "node:worker_threads";
 import { MemoryConnectionProvider } from "../connections/memory.js";
-import { formatValidationError, helpInputs, isTypedInputSchema, normalizeActionInput, validateTypedInput, } from "../plugin/schema.js";
+import { dropUndefined, formatValidationError, helpInputs, isTypedInputSchema, normalizeActionInput, validateTypedInput, } from "../plugin/schema.js";
 import { notifyObserver } from "../utils/observer.js";
 /**
  * How many bodies one worker may run before it is retired.
@@ -609,6 +609,14 @@ const { FerroSearch } = require(${JSON.stringify(ferrosearchPath)});
 // The host's own validator, for actions.check on typed schemas.
 const { Check: __schemaCheck, Errors: __schemaErrors } = require(${JSON.stringify(typeboxValuePath)});
 
+// The host's own normalizeActionInput, by its source, so a check sees the
+// arguments exactly as validation and execute do. The closure keeps the
+// helper names it calls out of the scope plugin globals are declared in.
+const __normalizeActionInput = (() => {
+${dropUndefined.toString()}
+return ${normalizeActionInput.toString()};
+})();
+
 const __help = ${JSON.stringify(helpData)};
 
 const __makeProxy = (path = []) => new Proxy(() => undefined, {
@@ -783,14 +791,10 @@ const __actionsApi = {
       return { ok: false, error: 'Unknown action: ' + path, suggestions: near };
     }
     const signature = __formatSignature(hit.plugin, hit.entry);
-    if (hit.entry.schema) {
-      // Mirror the host's normalizeActionInput: a check with no args is
-      // a call with an empty argument set; anything else — null, a
-      // scalar — is validated as given, exactly as execute would.
-      return __checkTyped(hit.entry, args === undefined ? {} : args, signature);
-    }
+    const input = __normalizeActionInput(args);
+    if (hit.entry.schema) return __checkTyped(hit.entry, input, signature);
     const inputs = hit.entry.inputs || {};
-    const provided = args && typeof args === 'object' ? args : {};
+    const provided = input && typeof input === 'object' ? input : {};
     const missing = [];
     const unknown = [];
     const typeErrors = [];

package/dist/credentials/registry.js

@@ -165,6 +165,11 @@ function validateMethod(method) {
         if (auth.rejectionStatus !== undefined &&
             ![401, 403].includes(auth.rejectionStatus))
             throw new AuthError("invalid_definition");
+        if (auth.grant !== undefined) {
+            identifier(auth.grant);
+            if (auth.renewal !== "refresh")
+                throw new AuthError("invalid_definition");
+        }
         if (auth.scopes &&
             (!Array.isArray(auth.scopes) ||
                 auth.scopes.some((scope) => typeof scope !== "string" || !scope)))

package/dist/credentials/types.d.ts

@@ -152,6 +152,16 @@ export type CredentialAuthentication = {
     /** Explicit renewal strategy, never inferred from available secrets. */
     renewal: "refresh" | "clientCredentials" | "jwtBearer" | "password";
     scopes?: string[];
+    /**
+     * The grant a refresh-renewed token belongs to, shared by every
+     * plugin declaring the same id. Its access tokens depend on the
+     * grant's client and token endpoint, not on the plugin that asked:
+     * the provider answers a refresh with every scope the grant holds
+     * (Google requests none; Microsoft returns every scope consented for
+     * the resource). One cached token then serves each of its plugins.
+     * Only with `renewal: "refresh"`.
+     */
+    grant?: string;
     /** Defaults to 401. A 403 must be explicitly documented by the provider. */
     rejectionStatus?: 401 | 403;
 };

package/dist/index.d.ts

@@ -23,6 +23,7 @@ export type { InstalledPlugin, PluginSource } from "./plugin/installer.js";
 export { installPlugin, listInstalled, parsePluginSource, removePlugin, } from "./plugin/installer.js";
 export { discoverPlugins, loadAllPlugins, loadPluginFromPath, loadPluginsFromConfig, } from "./plugin/loader.js";
 export { PluginRegistry, registry } from "./plugin/registry.js";
+export { connectionFields } from "./plugin/schema.js";
 export type { ActionAccess, ActionContext, ActionDef, ConnectionConfig, ConnectionSchema, ConnectionSchemaField, InputField, InputSchema, LegacyConnectionSchema, OAuthConfig, PluginDef, } from "./plugin/types.js";
 export type { RunlineExecuteOptions, RunlineOptions } from "./sdk.js";
 export { Runline } from "./sdk.js";

package/dist/index.js

@@ -14,5 +14,6 @@ export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugi
 export { installPlugin, listInstalled, parsePluginSource, removePlugin, } from "./plugin/installer.js";
 export { discoverPlugins, loadAllPlugins, loadPluginFromPath, loadPluginsFromConfig, } from "./plugin/loader.js";
 export { PluginRegistry, registry } from "./plugin/registry.js";
+export { connectionFields } from "./plugin/schema.js";
 export { Runline } from "./sdk.js";
 export { commandExists, syncExec } from "./utils/cli.js";

package/dist/plugin/schema.d.ts

@@ -16,13 +16,25 @@ export declare function connectionFields(schema: ConnectionSchema | undefined):
 export declare function helpInputs(schema: InputSchema | undefined): Record<string, HelpInput>;
 export declare function validateLegacyInput(schema: LegacyInputSchema, input: unknown): ValidationResult;
 /**
- * A call written with no arguments is a call with an empty argument set.
+ * A value as JSON would carry it: plain-object keys whose value is
+ * `undefined` are dropped, at every depth. JSON has no `undefined`, and a
+ * schema's `required` counts a present key as given, so `{ name: undefined }`
+ * would otherwise satisfy a rule that needs a name. Arrays keep their
+ * length; other objects (a Buffer, a Date) pass through untouched.
  *
+ * Self-contained, because the worker's `actions.check` runs this same
+ * source: preflight and execution cannot disagree about what was passed.
+ */
+export declare function dropUndefined(value: unknown): unknown;
+/**
+ * An action's arguments as validation and `execute` see them.
+ *
+ * A call written with no arguments is a call with an empty argument set:
  * `linear.user.me()` supplies no argument, so object validation needs an
  * empty object to accept no-input actions and name missing required fields.
- *
- * Only `undefined` is normalized: an explicit `null` or `42` is an
- * argument, and a wrong one.
+ * An explicit `null` or `42` is an argument, and a wrong one. Keys holding
+ * `undefined` are absent, by `dropUndefined`. The worker's `actions.check`
+ * runs this source too, so it may call nothing but `dropUndefined`.
  */
 export declare function normalizeActionInput(input: unknown): unknown;
 export declare function validateTypedInput(schema: TypedInputSchema, rawInput: unknown): ValidationResult;

package/dist/plugin/schema.js

@@ -187,16 +187,39 @@ export function validateLegacyInput(schema, input) {
     return validationResult({ missing, unknown, typeErrors });
 }
 /**
- * A call written with no arguments is a call with an empty argument set.
+ * A value as JSON would carry it: plain-object keys whose value is
+ * `undefined` are dropped, at every depth. JSON has no `undefined`, and a
+ * schema's `required` counts a present key as given, so `{ name: undefined }`
+ * would otherwise satisfy a rule that needs a name. Arrays keep their
+ * length; other objects (a Buffer, a Date) pass through untouched.
  *
+ * Self-contained, because the worker's `actions.check` runs this same
+ * source: preflight and execution cannot disagree about what was passed.
+ */
+export function dropUndefined(value) {
+    if (Array.isArray(value))
+        return value.map((entry) => dropUndefined(entry));
+    if (value === null || typeof value !== "object")
+        return value;
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null)
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .filter(([, entry]) => entry !== undefined)
+        .map(([key, entry]) => [key, dropUndefined(entry)]));
+}
+/**
+ * An action's arguments as validation and `execute` see them.
+ *
+ * A call written with no arguments is a call with an empty argument set:
  * `linear.user.me()` supplies no argument, so object validation needs an
  * empty object to accept no-input actions and name missing required fields.
- *
- * Only `undefined` is normalized: an explicit `null` or `42` is an
- * argument, and a wrong one.
+ * An explicit `null` or `42` is an argument, and a wrong one. Keys holding
+ * `undefined` are absent, by `dropUndefined`. The worker's `actions.check`
+ * runs this source too, so it may call nothing but `dropUndefined`.
  */
 export function normalizeActionInput(input) {
-    return input === undefined ? {} : input;
+    return input === undefined ? {} : dropUndefined(input);
 }
 export function validateTypedInput(schema, rawInput) {
     const input = normalizeActionInput(rawInput);

package/dist/plugin/types.d.ts

@@ -108,6 +108,14 @@ export type OAuthConfig = OAuthSetupOptions & ({
 interface OAuthSetupOptions {
     /** Scopes to request on the consent screen. */
     scopes: string[];
+    /**
+     * The grant this plugin's consent belongs to, shared by every plugin
+     * declaring the same id (`google`, `microsoft`): one provider, one OAuth
+     * client, one person's consent. A host may hold one connection for the
+     * whole grant and ask for the union of its plugins' scopes. The plugin's
+     * credential declares the same id, so its tokens are the grant's.
+     */
+    grant?: string;
     /**
      * Provider-fixed loopback callback (`http://localhost:<port>/<path>`),
      * replacing Runline's default `http://127.0.0.1:47823/callback`. Use only

package/dist/plugins/_shared/base64.js

@@ -0,0 +1,30 @@
+import * as t from "typebox";
+/**
+ * Caller-supplied base64 in the standard padded alphabet: whitespace
+ * dropped, base64url's `-` and `_` mapped to `+` and `/`, padding
+ * restored. So a gmail.message.getAttachment result (base64url, unpadded)
+ * and a googleDrive download (standard) are equally accepted. Undefined
+ * when the value is not base64: a character outside both alphabets,
+ * padding anywhere but the end, or a length no encoding produces.
+ *
+ * Flat character-class patterns only: values run to many megabytes.
+ */
+export function standardBase64(value) {
+    const compact = value.replace(/\s+/g, "").replace(/={1,2}$/, "");
+    if (!/^[A-Za-z0-9+/_-]*$/.test(compact) || compact.length % 4 === 1)
+        return undefined;
+    const standard = compact.replace(/-/g, "+").replace(/_/g, "/");
+    return standard.padEnd(Math.ceil(standard.length / 4) * 4, "=");
+}
+/**
+ * A googleDrive.file.download result, accepted wherever attachment bytes
+ * are: exactly its fields, so the result passes through unedited while
+ * anything else is still refused. Its `name` and `mimeType` stand in for
+ * an attachment's own when those are left out.
+ */
+export const DownloadedFile = t.Object({
+    contentBase64: t.String(),
+    name: t.Optional(t.String()),
+    mimeType: t.Optional(t.String()),
+    size: t.Optional(t.Integer({ minimum: 0 })),
+}, { additionalProperties: false });

package/dist/plugins/_shared/credentialAdapter.js

@@ -16,10 +16,30 @@ export function credentialBroker(ctx, declaration) {
         socketUrl: (input) => transport.socketUrl(binding, input),
     };
 }
-/** Everything a stored token was issued under. A config whose selection
- *  hashes differently can no longer use tokens issued for this one. */
+/**
+ * Everything a stored token was issued under. A config whose selection
+ * hashes differently can no longer use tokens issued for this one. A
+ * token of a declared grant was issued under the grant — its method,
+ * client and token endpoint (Microsoft's names the tenant) — not the
+ * plugin that asked, so every plugin of the grant hashes alike and shares
+ * it; any other token is the whole selection's, scopes and targets included.
+ */
 function authorityOf(selection) {
-    return createHash("sha256").update(JSON.stringify(selection)).digest("hex");
+    const { type, method, application } = selection;
+    const auth = Object.hasOwn(type.methods, method)
+        ? type.methods[method].authentication
+        : undefined;
+    const issuedUnder = auth?.kind === "oauth2" && auth.grant !== undefined
+        ? {
+            grant: auth.grant,
+            method,
+            application,
+            endpoint: auth.definition.refresh,
+        }
+        : selection;
+    return createHash("sha256")
+        .update(JSON.stringify(issuedUnder))
+        .digest("hex");
 }
 /**
  * A static secret's structured shape, from the flat fields and fixed values

package/dist/plugins/_shared/credentials.js

@@ -226,6 +226,9 @@ export function credentialRequest(ctx, declaration, call) {
         ...(call.destination !== undefined
             ? { destination: call.destination }
             : {}),
+        ...(call.idempotencyKey !== undefined
+            ? { idempotencyKey: call.idempotencyKey }
+            : {}),
     });
 }
 /**
@@ -265,8 +268,8 @@ export function errorIdentifier(value) {
 /**
  * How a failed request reads: its HTTP status when the status is the
  * failure, and the identifiers a provider returns for correcting the call
- * — its error `code` and the offending `param`. A failed response's body
- * is never read into it: that is where a provider may echo the credential.
+ * — its error `code` and the offending `param`. No free text from a failed
+ * response reaches it: that is where a provider may echo the credential.
  */
 export function failureMessage(plugin, status, detail = {}) {
     const identifiers = [detail.code, detail.param && `param: ${detail.param}`]
@@ -312,6 +315,30 @@ export function graphqlFailed(plugin, errors) {
 export function requestFailed(plugin, status) {
     return new Error(failureMessage(plugin, status));
 }
+/**
+ * A failed response by its status and the identifiers its error envelope
+ * names. `read` picks the code and param out of the parsed JSON body, in
+ * the provider's own shape; only what `errorIdentifier` accepts is kept,
+ * so a provider's messages never reach the error. A body that is not JSON
+ * reports the status alone. The status rides on the error for callers
+ * that branch on it.
+ */
+export async function responseFailed(plugin, response, read) {
+    let envelope = {};
+    try {
+        envelope = read(JSON.parse(await response.text()));
+    }
+    catch {
+        envelope = {};
+    }
+    const params = (Array.isArray(envelope.param) ? envelope.param : [envelope.param])
+        .map(identifierOf)
+        .filter((param) => param !== undefined);
+    return Object.assign(new Error(failureMessage(plugin, response.status, {
+        code: identifierOf(envelope.code),
+        param: params.length ? params.join(", ") : undefined,
+    })), { status: response.status });
+}
 /** A request that must succeed, for callers that read the Response itself (headers, text, bytes). */
 export async function credentialOk(ctx, declaration, plugin, call) {
     const response = await credentialRequest(ctx, declaration, call);

package/dist/plugins/_shared/googleAuth.js

@@ -1,8 +1,69 @@
 import { AuthError, downloadResource, } from "runline";
 import { credentialBroker } from "./credentialAdapter.js";
 import { jsonAnswer, requestFailed } from "./credentials.js";
-import { googleCredential, googleResources } from "./googleCredentials.js";
+import { GOOGLE_GRANT, GOOGLE_TOKEN_URL, googleCredential, googleResources, googleServices, } from "./googleCredentials.js";
 export { googleCredential } from "./googleCredentials.js";
+/**
+ * A Google plugin's OAuth declaration: Google's endpoints, the offline
+ * consent that returns a refresh token (without `access_type=offline` and
+ * `prompt=consent` a repeat login omits it), the grant every Google plugin
+ * shares, and setup steps that enable the APIs its targets call and name
+ * its client variables (`env`: `GMAIL` → `GMAIL_CLIENT_ID`).
+ */
+export function googleOAuth(plugin, scopes, env) {
+    return {
+        grant: GOOGLE_GRANT,
+        authUrl: "https://accounts.google.com/o/oauth2/v2/auth",
+        tokenUrl: GOOGLE_TOKEN_URL,
+        scopes,
+        authParams: { access_type: "offline", prompt: "consent" },
+        setupHelp: [
+            "You need a Google Cloud OAuth client. Takes ~5 minutes, one time;",
+            "the same client serves every Google plugin.",
+            "Do the steps in order — skipping step 4 causes a 403 when you log in.",
+            "",
+            "1. Create a Google Cloud project (or pick an existing one):",
+            "     https://console.cloud.google.com/projectcreate",
+            "   Make sure the project is selected in the top navigation dropdown.",
+            "",
+            "2. Enable the APIs this plugin calls (click 'Enable' on each):",
+            ...googleServices(plugin).map((service) => `     https://console.cloud.google.com/apis/library/${service}`),
+            "",
+            "3. Configure the OAuth consent screen (first time only):",
+            "     https://console.cloud.google.com/apis/credentials/consent",
+            "   Click 'Get started' and fill in:",
+            "     • App name: runline (or whatever)",
+            "     • User support email: your email",
+            "     • Audience: External",
+            "     • Developer contact: your email",
+            "   You can skip the Scopes screen — runline declares scopes at auth time.",
+            "",
+            "4. Add yourself as a test user (required — External apps in Testing mode",
+            "   only allow authentication from addresses on this list):",
+            "     https://console.cloud.google.com/auth/audience",
+            "   Under 'Test users', click '+ Add users' and enter the Google address",
+            "   you'll use to log in. Consent and refresh tokens expire every 7 days",
+            "   while the app is in Testing mode.",
+            "",
+            "5. Create the OAuth client:",
+            "     https://console.cloud.google.com/apis/credentials",
+            "     • + Create credentials → OAuth client ID",
+            "     • Application type: Web application",
+            "     • Name: runline (or whatever)",
+            "     • Authorized redirect URIs → + Add URI:",
+            "         {{redirectUri}}",
+            "     • Click Create, then copy the Client ID and Client Secret from the",
+            "       dialog — the secret is only shown once.",
+            "",
+            "6. Paste them below (or re-run with --client-id / --client-secret,",
+            `   or export ${env}_CLIENT_ID and ${env}_CLIENT_SECRET).`,
+            "",
+            "During login you'll see a 'Google hasn't verified this app' warning.",
+            "Click 'Advanced → Go to runline (unsafe)' to continue — this is",
+            "expected for apps in Testing mode.",
+        ],
+    };
+}
 /** Translate builtin absolute URLs at one boundary; validate the raw path before URL normalization. */
 export async function googleResponse(ctx, plugin, scopes, url, init = {}, query) {
     const resources = googleResources(plugin);

package/dist/plugins/_shared/googleCredentials.js

@@ -1,5 +1,12 @@
 import { AuthError, } from "runline";
 import { grantSchema } from "./credentials.js";
+/** The grant every Google plugin's consent belongs to. */
+export const GOOGLE_GRANT = "google";
+/**
+ * Google's fixed token endpoint: a JSON credential's token_uri never
+ * selects egress.
+ */
+export const GOOGLE_TOKEN_URL = "https://oauth2.googleapis.com/token";
 /** Only legacy storage infers a method; host bindings always select it explicitly. */
 export function googleMethod(cfg) {
     if (cfg.authMethod !== undefined) {
@@ -51,6 +58,19 @@ const API_BASES = {
     calendar: "https://www.googleapis.com/calendar/v3/",
     gmail: "https://gmail.googleapis.com/gmail/v1/users/me/",
 };
+/** The Cloud Console service each API base belongs to, to enable it by. */
+const API_SERVICES = {
+    drive: "drive.googleapis.com",
+    upload: "drive.googleapis.com",
+    docs: "docs.googleapis.com",
+    sheets: "sheets.googleapis.com",
+    slides: "slides.googleapis.com",
+    script: "script.googleapis.com",
+    tasks: "tasks.googleapis.com",
+    people: "people.googleapis.com",
+    calendar: "calendar-json.googleapis.com",
+    gmail: "gmail.googleapis.com",
+};
 const PLUGIN_TARGETS = {
     googleDrive: ["drive", "upload", "docs"],
     googleDocs: ["docs", "drive"],
@@ -62,11 +82,19 @@ const PLUGIN_TARGETS = {
     googleCalendar: ["calendar"],
     gmail: ["gmail"],
 };
-/** Builtin routing policy, never derived from action input or a returned URL. */
-export function googleResources(plugin) {
+/** The API bases a builtin Google plugin calls; any other name is refused. */
+function targetNames(plugin) {
     if (!Object.hasOwn(PLUGIN_TARGETS, plugin))
         throw new AuthError("request_not_allowed");
-    const names = PLUGIN_TARGETS[plugin];
+    return PLUGIN_TARGETS[plugin];
+}
+/** The Cloud Console services a plugin calls, each to be enabled once. */
+export function googleServices(plugin) {
+    return [...new Set(targetNames(plugin).map((name) => API_SERVICES[name]))];
+}
+/** Builtin routing policy, never derived from action input or a returned URL. */
+export function googleResources(plugin) {
+    const names = targetNames(plugin);
     const targets = Object.fromEntries(names.map((name) => [
         name,
         {
@@ -134,9 +162,7 @@ export function googleCredential(plugin, scopes) {
         };
     };
 }
-/** Fixed vendor endpoints; a JSON credential's token_uri can never select egress. */
 export function googleCredentialType(scopes, plugin) {
-    const url = "https://oauth2.googleapis.com/token";
     const { targets, probe } = googleResources(plugin);
     return {
         id: "google.oauth",
@@ -147,10 +173,14 @@ export function googleCredentialType(scopes, plugin) {
                     kind: "oauth2",
                     field: "grant",
                     renewal: "refresh",
+                    grant: GOOGLE_GRANT,
                     definition: {
                         id: "google.oauth",
                         provider: "google",
-                        refresh: { url, clientAuthentication: "client_secret_post" },
+                        refresh: {
+                            url: GOOGLE_TOKEN_URL,
+                            clientAuthentication: "client_secret_post",
+                        },
                     },
                 },
                 targets,
@@ -168,7 +198,10 @@ export function googleCredentialType(scopes, plugin) {
                             definition: {
                                 id: "google.serviceAccount",
                                 provider: "google",
-                                jwtBearer: { url, clientAuthentication: "none" },
+                                jwtBearer: {
+                                    url: GOOGLE_TOKEN_URL,
+                                    clientAuthentication: "none",
+                                },
                             },
                         },
                         targets,

package/dist/plugins/_shared/localFile.js

@@ -0,0 +1,40 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+/**
+ * A file on the runline host that an action input names — an attachment,
+ * an upload, an image to edit — read as one bounded buffer. It must be a
+ * regular file: the nonblocking open lets fstat refuse a FIFO or device
+ * without waiting on a writer. The size is checked before allocation and
+ * the bytes are read through the same handle, so a file swapped or grown
+ * between the check and the read cannot slip past the bound.
+ */
+export async function readLocalFile(path, options) {
+    const { subject } = options;
+    let file;
+    try {
+        file = await open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    }
+    catch (error) {
+        const code = error.code;
+        throw new Error(`${subject} is unreadable${typeof code === "string" ? ` (${code})` : ""}`);
+    }
+    try {
+        const stat = await file.stat();
+        if (!stat.isFile())
+            throw new Error(`${subject} must be a regular file`);
+        if (stat.size > options.maxBytes)
+            throw new Error(options.oversize);
+        const bytes = Buffer.alloc(stat.size);
+        let offset = 0;
+        while (offset < bytes.length) {
+            const { bytesRead } = await file.read(bytes, offset, bytes.length - offset, offset);
+            if (!bytesRead)
+                throw new Error(`${subject} changed while reading`);
+            offset += bytesRead;
+        }
+        return bytes;
+    }
+    finally {
+        await file.close();
+    }
+}

package/dist/plugins/_shared/mediaFile.js

@@ -9,9 +9,10 @@
  * available (same pattern as googleDrive/googleSlides).
  */
 import { randomUUID } from "node:crypto";
-import { readFileSync, writeFileSync } from "node:fs";
+import { writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { basename, extname, join } from "node:path";
+import { readLocalFile } from "./localFile.js";
 const MIME_EXT = {
     "image/png": "png",
     "image/jpeg": "jpg",
@@ -66,23 +67,22 @@ const EXT_MIME = {
     webp: "image/webp",
     gif: "image/gif",
 };
+/** Larger than any provider accepts inline; a data URI past it only fails remotely. */
+const MAX_IMAGE_BYTES = 50 * 1024 * 1024;
 /**
  * Read a local image for an `image.edit` call: bytes + base64 + mime
- * (from the extension) + a `data:` URI for JSON APIs. Throws with the
- * plugin's name when the file can't be read so errors point at the
- * right tool.
+ * (from the extension) + a `data:` URI for JSON APIs. Errors carry the
+ * plugin's name so they point at the right tool.
  */
-export function readImageInput(imagePath, pluginName) {
+export async function readImageInput(imagePath, pluginName) {
     if (typeof imagePath !== "string" || imagePath.trim().length === 0) {
         throw new Error(`${pluginName}: imagePath is required`);
     }
-    let bytes;
-    try {
-        bytes = readFileSync(imagePath);
-    }
-    catch (err) {
-        throw new Error(`${pluginName}: cannot read image at ${imagePath} — ${err instanceof Error ? err.message : String(err)}`);
-    }
+    const bytes = await readLocalFile(imagePath, {
+        subject: `${pluginName}: imagePath`,
+        maxBytes: MAX_IMAGE_BYTES,
+        oversize: `${pluginName}: imagePath exceeds ${MAX_IMAGE_BYTES / (1024 * 1024)} MiB`,
+    });
     const ext = extname(imagePath).slice(1).toLowerCase();
     const mimeType = EXT_MIME[ext] ?? "image/png";
     const base64 = bytes.toString("base64");

package/dist/plugins/_shared/microsoftAuth.js

@@ -1,7 +1,7 @@
 import { AuthError, downloadResource, } from "runline";
 import { credentialBroker } from "./credentialAdapter.js";
 import { jsonAnswer, requestFailed } from "./credentials.js";
-import { microsoftCredential, microsoftUserBase, } from "./microsoftCredentials.js";
+import { MICROSOFT_GRANT, microsoftCredential, microsoftEndpoint, microsoftUserBase, } from "./microsoftCredentials.js";
 export { microsoftCredential, microsoftDriveBase, } from "./microsoftCredentials.js";
 export function userBase(ctx) {
     return microsoftUserBase(ctx.connection.config);
@@ -59,8 +59,23 @@ export async function microsoftDownload(value) {
         fetch: globalThis.fetch,
     });
 }
-/** Setup help shown by the OAuth wizard for all Microsoft plugins. */
-export function microsoftSetupHelp(apiName) {
+/**
+ * A Microsoft Graph plugin's OAuth declaration: the multi-tenant endpoints,
+ * `offline_access` for a refresh token, the grant every Graph plugin
+ * shares, and setup steps naming the Graph permissions it needs
+ * (`permissions`, e.g. "Calendars.Read").
+ */
+export function microsoftOAuth(scopes, permissions) {
+    return {
+        grant: MICROSOFT_GRANT,
+        authUrl: microsoftEndpoint("common", "authorize"),
+        tokenUrl: microsoftEndpoint("common", "token"),
+        scopes: [...scopes, "offline_access"],
+        setupHelp: setupHelp(permissions),
+    };
+}
+/** The OAuth wizard's steps for a Microsoft plugin. */
+function setupHelp(permissions) {
     return [
         `You need a Microsoft Entra (Azure AD) app registration. One-time, ~5 minutes.`,
         "",
@@ -69,7 +84,7 @@ export function microsoftSetupHelp(apiName) {
         "2. Add a Web redirect URI (Authentication → Add platform → Web):",
         "     {{redirectUri}}",
         "3. Certificates & secrets → New client secret → copy the VALUE (not the Secret ID).",
-        `4. API permissions → Add → Microsoft Graph → Delegated → add the ${apiName} scopes,`,
+        `4. API permissions → Add → Microsoft Graph → Delegated → add the ${permissions} scopes,`,
         "   then 'Grant admin consent'.",
         "5. Paste the Application (client) ID and the client secret VALUE below.",
     ];

package/dist/plugins/_shared/microsoftCredentials.js

@@ -1,5 +1,13 @@
 import { AuthError, } from "runline";
 import { grantSchema, pathSegment } from "./credentials.js";
+/** The grant every Microsoft Graph plugin's delegated consent belongs to. */
+export const MICROSOFT_GRANT = "microsoft";
+/** A tenant's OAuth endpoint on the Microsoft identity platform. */
+export function microsoftEndpoint(tenant, leg) {
+    if (!/^[a-zA-Z0-9.-]+$/.test(tenant))
+        throw new AuthError("invalid_credentials");
+    return `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/${leg}`;
+}
 /** Compatibility inference is confined to legacy configs without an explicit method. */
 export function microsoftMethod(cfg) {
     if (cfg.authMethod !== undefined) {
@@ -50,11 +58,8 @@ export function microsoftCredential(plugin, scopes) {
 }
 /** Scope-appropriate probes never require User.Read merely to check mail/calendar/files. */
 export function microsoftCredentialType(cfg, plugin, scopes) {
-    const tenant = cfg.tenantId || "common";
-    if (!/^[a-zA-Z0-9.-]+$/.test(tenant))
-        throw new AuthError("invalid_credentials");
     const endpoint = {
-        url: `https://login.microsoftonline.com/${tenant}/oauth2/v2.0/token`,
+        url: microsoftEndpoint(cfg.tenantId || "common", "token"),
         clientAuthentication: "client_secret_post",
     };
     const methods = Object.fromEntries(["delegated", "appOnly"].map((method) => {
@@ -85,9 +90,9 @@ export function microsoftCredentialType(cfg, plugin, scopes) {
                 authentication: {
                     kind: "oauth2",
                     field: "grant",
-                    renewal: method === "delegated"
-                        ? "refresh"
-                        : "clientCredentials",
+                    ...(method === "delegated"
+                        ? { renewal: "refresh", grant: MICROSOFT_GRANT }
+                        : { renewal: "clientCredentials" }),
                     definition: {
                         id: "microsoft.oauth",
                         provider: "microsoft",