runline 0.33.0 → 0.35.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { AuthError, type AuthErrorCode } from "./auth/errors.js";
-export { acquireOAuth2ClientToken, acquireOAuth2JwtToken, buildOAuth2AuthorizationUrl, exchangeOAuth2Code, refreshOAuth2Token, } from "./auth/oauth2.js";
+export { acquireOAuth2ClientToken, acquireOAuth2JwtToken, acquireOAuth2PasswordToken, buildOAuth2AuthorizationUrl, exchangeOAuth2Code, refreshOAuth2Token, } from "./auth/oauth2.js";
 export { decodeOAuthTokens, requestOAuth2Token } from "./auth/token.js";
-export type { OAuth2Definition, OAuth2TokenEndpoint, OAuthApplication, OAuthAuthorizationOptions, OAuthCodeOptions, OAuthEvent, OAuthJwtIdentity, OAuthOperation, OAuthRuntimeOptions, } from "./auth/types.js";
+export type { OAuth2Definition, OAuth2TokenEndpoint, OAuthApplication, OAuthAuthorizationOptions, OAuthCodeOptions, OAuthEvent, OAuthJwtIdentity, OAuthOperation, OAuthResourceOwner, OAuthRuntimeOptions, } from "./auth/types.js";
 export { addConnection, findConfigDir, getConnection, loadConfig, removeConnection, saveConfig, updateConnectionConfig, } from "./config/loader.js";
 export type { RunlineConfig } from "./config/types.js";
 export { DEFAULT_CONFIG } from "./config/types.js";
@@ -13,16 +13,17 @@ export { ExecutionEngine } from "./core/engine.js";
 export type { BuildAuthUrlOptions, ExchangeCodeOptions, OAuthTokens, PKCEPair, RunOAuthOptions, } from "./core/oauth.js";
 export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_URI, oauthCallback, runOAuth, } from "./core/oauth.js";
 export { downloadResource } from "./credentials/http.js";
-export { CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, validateCredential, } from "./credentials/registry.js";
-export type { AuthenticatedRequest, CredentialTransportOptions, } from "./credentials/transport.js";
+export { CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.js";
+export type { AuthenticatedRequest, CredentialBroker, CredentialBrokerCall, CredentialTransportOptions, SocketRequest, } from "./credentials/transport.js";
 export { CredentialTransport } from "./credentials/transport.js";
-export type { CredentialAuthentication, CredentialBinding, CredentialMethod, CredentialProbe, CredentialProbeResult, CredentialTarget, CredentialType, HttpMethod, OAuthGrant, } from "./credentials/types.js";
+export type { CredentialAuthentication, CredentialBinding, CredentialDeclaration, CredentialMethod, CredentialProbe, CredentialProbeResult, CredentialSelection, CredentialTarget, CredentialType, HttpMethod, LocalSecretPart, LocalSecretSource, OAuthGrant, SecretPlacement, } from "./credentials/types.js";
 export type { ActionDefinition, PluginFunction, RunlinePluginAPI, } from "./plugin/api.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.js";
 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

@@ -1,5 +1,5 @@
 export { AuthError } from "./auth/errors.js";
-export { acquireOAuth2ClientToken, acquireOAuth2JwtToken, buildOAuth2AuthorizationUrl, exchangeOAuth2Code, refreshOAuth2Token, } from "./auth/oauth2.js";
+export { acquireOAuth2ClientToken, acquireOAuth2JwtToken, acquireOAuth2PasswordToken, buildOAuth2AuthorizationUrl, exchangeOAuth2Code, refreshOAuth2Token, } from "./auth/oauth2.js";
 export { decodeOAuthTokens, requestOAuth2Token } from "./auth/token.js";
 export { addConnection, findConfigDir, getConnection, loadConfig, removeConnection, saveConfig, updateConnectionConfig, } from "./config/loader.js";
 export { DEFAULT_CONFIG } from "./config/types.js";
@@ -8,11 +8,12 @@ export { MemoryConnectionProvider } from "./connections/memory.js";
 export { ExecutionEngine } from "./core/engine.js";
 export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_URI, oauthCallback, runOAuth, } from "./core/oauth.js";
 export { downloadResource } from "./credentials/http.js";
-export { CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, validateCredential, } from "./credentials/registry.js";
+export { CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.js";
 export { CredentialTransport } from "./credentials/transport.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.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 { Runline } from "./sdk.js";
 export { commandExists, syncExec } from "./utils/cli.js";

package/dist/plugin/api.d.ts

@@ -1,3 +1,4 @@
+import type { CredentialDeclaration } from "../credentials/types.js";
 import type { ActionAccess, ActionDef, ConnectionSchema, InputSchema, OAuthConfig, PluginDef } from "./types.js";
 export interface ActionDefinition {
     access?: ActionAccess;
@@ -16,6 +17,12 @@ export interface RunlinePluginAPI {
      * with refreshable tokens.
      */
     setOAuth(oauth: OAuthConfig): void;
+    /**
+     * Declare how a connection's config becomes what this plugin's requests
+     * are signed with, so a host brokering for it can sign from the plugin
+     * it loaded rather than from anything the plugin's process sends.
+     */
+    setCredential(declaration: CredentialDeclaration): void;
     onInit(fn: (config: Record<string, unknown>) => void): void;
     log: {
         info(msg: string): void;

package/dist/plugin/api.js

@@ -4,6 +4,7 @@ export function createPluginAPI(pluginId) {
     const actions = [];
     let connectionConfigSchema;
     let oauth;
+    let credential;
     const initHooks = [];
     const api = {
         setName(n) {
@@ -24,6 +25,9 @@ export function createPluginAPI(pluginId) {
         setOAuth(cfg) {
             oauth = { ...cfg };
         },
+        setCredential(declaration) {
+            credential = declaration;
+        },
         onInit(fn) {
             initHooks.push(fn);
         },
@@ -49,6 +53,9 @@ export function createPluginAPI(pluginId) {
         if (oauth) {
             plugin.oauth = oauth;
         }
+        if (credential) {
+            plugin.credential = credential;
+        }
         if (initHooks.length > 0) {
             plugin.initHooks = initHooks;
         }

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

@@ -1,6 +1,8 @@
 import type { TSchema } from "typebox";
 import type { OAuth2Definition } from "../auth/types.js";
 import type { ConnectionUpdate } from "../connections/types.js";
+import type { CredentialBroker } from "../credentials/transport.js";
+import type { CredentialDeclaration } from "../credentials/types.js";
 export interface InputField {
     type: "string" | "number" | "boolean" | "object" | "array";
     description?: string;
@@ -60,6 +62,13 @@ export interface ActionContext {
      * engine). Absent when the embedder passed none.
      */
     context?: unknown;
+    /**
+     * Authenticated requests signed by the host, present when the embedder
+     * holds this connection's credentials elsewhere and the plugin declares
+     * its credential. A plugin given one sends through it and signs nothing
+     * itself: its connection config then carries public settings only.
+     */
+    credentials?: CredentialBroker;
     log: {
         info(msg: string): void;
         warn(msg: string): void;
@@ -99,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
@@ -128,6 +145,9 @@ export interface PluginDef {
     connectionConfigSchema?: ConnectionSchema;
     /** OAuth2 config for `runline auth <plugin>`. */
     oauth?: OAuthConfig;
+    /** How a connection's config becomes what its requests are signed with;
+     *  present on plugins whose requests go through the credential registry. */
+    credential?: CredentialDeclaration;
     /** @internal */
     initHooks?: Array<(config: Record<string, unknown>) => void>;
 }

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

@@ -1,15 +1,93 @@
 import { createHash } from "node:crypto";
 import { AuthError, CredentialRegistry, CredentialTransport, } from "runline";
-/** Flat CLI/env storage is a projection, not a second token cache or refresh engine. */
-export function credentialRuntime(ctx, definition, method, authority) {
-    const identity = { name: ctx.connection.name, plugin: ctx.connection.plugin };
-    const fingerprint = (config) => createHash("sha256")
-        .update(JSON.stringify([definition.id, method, authority(config)]))
+/**
+ * Where one action call's authenticated requests go: the host's broker
+ * when it supplies one — the credentials then live with the host, and no
+ * local signer is built — else this process signs with its own
+ * connection, from the plugin's declaration.
+ */
+export function credentialBroker(ctx, declaration) {
+    if (ctx.credentials)
+        return ctx.credentials;
+    const { binding, transport } = localSigner(ctx, declaration);
+    return {
+        request: (input) => transport.request(binding, input),
+        probe: () => transport.probe(binding),
+        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. 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) {
+    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");
-    const expected = fingerprint(ctx.connection.config);
+}
+/**
+ * A static secret's structured shape, from the flat fields and fixed values
+ * the declaration names, joined in order where a part concatenates them.
+ * Absent when a required part's field is missing, so the transport refuses
+ * it as invalid_credentials before any IO; a missing optional part is left
+ * out, refusing only the targets that place it.
+ */
+function staticSecret(current, sources, optional) {
+    if (!sources)
+        return undefined;
+    const secret = {};
+    sources: for (const [key, source] of Object.entries(sources)) {
+        let joined = "";
+        for (const part of "concat" in source ? source.concat : [source]) {
+            const value = "value" in part ? part.value : current[part.field];
+            if (typeof value !== "string") {
+                if (optional.includes(key))
+                    continue sources;
+                return undefined;
+            }
+            joined += value;
+        }
+        secret[key] = joined;
+    }
+    return secret;
+}
+/**
+ * This process signing with its own connection. Flat CLI/env storage is a
+ * projection, not a second token cache or refresh engine.
+ */
+function localSigner(ctx, declaration) {
+    const selection = declaration(ctx.connection.config);
+    const { type: definition, method } = selection;
+    if (!Object.hasOwn(definition.methods, method))
+        throw new AuthError("invalid_definition");
+    const auth = definition.methods[method].authentication;
+    const identity = { name: ctx.connection.name, plugin: ctx.connection.plugin };
+    const expected = authorityOf(selection);
     const project = (current) => {
-        if (fingerprint(current) !== expected)
+        if (authorityOf(declaration(current)) !== expected)
             throw new AuthError("binding_changed");
+        if (auth.kind === "none")
+            return {};
+        if (auth.kind === "static") {
+            const secret = staticSecret(current, selection.localSecret, auth.optionalParts ?? []);
+            return secret ? { [auth.field]: secret } : {};
+        }
         const compatible = current.authTokenBinding === undefined ||
             current.authTokenBinding === expected;
         const tokens = {
@@ -34,7 +112,7 @@ export function credentialRuntime(ctx, definition, method, authority) {
         const revision = typeof current.authTokenRevision === "string" && compatible
             ? current.authTokenRevision
             : createHash("sha256").update(JSON.stringify(tokens)).digest("hex");
-        return { grant: { tokens, revision } };
+        return { [auth.field]: { tokens, revision } };
     };
     const snapshot = () => ({
         ...identity,
@@ -44,21 +122,25 @@ export function credentialRuntime(ctx, definition, method, authority) {
         type: definition.id,
         method,
         identity,
-        application: {
-            clientId: ctx.connection.config.clientId,
-            clientSecret: ctx.connection.config.clientSecret,
-        },
+        application: selection.application,
+        ...(selection.jwtIdentity ? { jwtIdentity: selection.jwtIdentity } : {}),
+        ...(selection.resourceOwner
+            ? { resourceOwner: selection.resourceOwner }
+            : {}),
         connection: {
             async read() {
                 return snapshot();
             },
             async update(change) {
+                // Only an OAuth grant is ever renewed and written back.
+                if (auth.kind !== "oauth2")
+                    throw new AuthError("invalid_definition");
                 await ctx.updateConnection(async (current) => {
                     const projected = project(current);
                     const patch = typeof change === "function" ? await change(projected) : change;
                     if (!patch)
                         return;
-                    const grant = patch.grant;
+                    const grant = patch[auth.field];
                     if (!grant?.tokens.accessToken)
                         throw new AuthError("invalid_credentials");
                     return {
@@ -77,10 +159,12 @@ export function credentialRuntime(ctx, definition, method, authority) {
     };
     const registry = new CredentialRegistry();
     registry.register(definition);
-    // Builtins run in the caller's trusted runtime. Vex must supply its privileged
-    // egress transport via the broker rather than execute these plugins server-side.
+    // The widest defaults the transport allows, so an undeclared slow call
+    // (image generation, exports) is bounded rather than cut short; targets
+    // that declare their own deadline or ceiling get it up to the host caps.
     const transport = new CredentialTransport(registry, {
         fetch: globalThis.fetch,
+        timeoutMs: 120_000,
         maxRequestBytes: 64 * 1024 * 1024,
         maxResponseBytes: 64 * 1024 * 1024,
     });