runline 0.28.1 → 0.30.0

package/dist/credentials/transport.js

@@ -0,0 +1,283 @@
+import { randomUUID } from "node:crypto";
+import { Check } from "typebox/value";
+import { AuthError } from "../auth/errors.js";
+import { acquireOAuth2ClientToken, acquireOAuth2JwtToken, refreshOAuth2Token, } from "../auth/oauth2.js";
+import { sendResource } from "./http.js";
+import { headerName, resourceUrl } from "./policy.js";
+import { OAuthGrantSchema, validateCredential, } from "./registry.js";
+function boundSnapshot(binding, method, snapshot) {
+    if (snapshot.name !== binding.identity.name ||
+        snapshot.plugin !== binding.identity.plugin)
+        throw new AuthError("binding_changed");
+    validateCredential(method, snapshot.config);
+    return structuredClone(snapshot.config);
+}
+function grantFrom(method, config) {
+    const auth = method.authentication;
+    if (auth.kind !== "oauth2")
+        throw new AuthError("invalid_definition");
+    const grant = config[auth.grantField];
+    if (grant === undefined)
+        return undefined;
+    if (!Check(OAuthGrantSchema, grant))
+        throw new AuthError("invalid_credentials");
+    const result = grant;
+    if (result.tokens.tokenType !== undefined &&
+        result.tokens.tokenType.toLowerCase() !== "bearer")
+        throw new AuthError("unsupported_operation");
+    return result;
+}
+function pinBinding(selection) {
+    return {
+        ...selection,
+        identity: { ...selection.identity },
+        application: structuredClone(selection.application),
+        jwtIdentity: structuredClone(selection.jwtIdentity),
+        connection: {
+            read: selection.connection.read.bind(selection.connection),
+            update: selection.connection.update.bind(selection.connection),
+        },
+    };
+}
+function fresh(grant) {
+    return (!!grant?.tokens.accessToken &&
+        (grant.tokens.expiresAt === undefined ||
+            grant.tokens.expiresAt > Date.now() + 60_000));
+}
+function secret(value) {
+    if (typeof value !== "string" ||
+        !value ||
+        [...value].some((char) => char.charCodeAt(0) <= 32 || char.charCodeAt(0) > 126))
+        throw new AuthError("invalid_credentials");
+    return value;
+}
+/**
+ * Trusted-host primitive, not a workspace sandbox. Callers authorize a binding on
+ * every invocation. Handles own lifecycle fencing; no second lock or token cache.
+ */
+export class CredentialTransport {
+    registry;
+    options;
+    constructor(registry, options) {
+        this.registry = registry;
+        this.options = {
+            fetch: options.fetch,
+            timeoutMs: options.timeoutMs ?? 20_000,
+            maxResponseBytes: options.maxResponseBytes ?? 8 * 1024 * 1024,
+            maxRequestBytes: options.maxRequestBytes ?? 1024 * 1024,
+        };
+        if (typeof this.options.fetch !== "function" ||
+            !Number.isInteger(this.options.timeoutMs) ||
+            this.options.timeoutMs <= 0 ||
+            this.options.timeoutMs > 120_000 ||
+            !Number.isSafeInteger(this.options.maxResponseBytes) ||
+            this.options.maxResponseBytes <= 0 ||
+            this.options.maxResponseBytes > 64 * 1024 * 1024 ||
+            !Number.isSafeInteger(this.options.maxRequestBytes) ||
+            this.options.maxRequestBytes <= 0 ||
+            this.options.maxRequestBytes > 64 * 1024 * 1024)
+            throw new AuthError("invalid_definition");
+    }
+    async read(binding, method) {
+        let snapshot;
+        try {
+            snapshot = await binding.connection.read();
+        }
+        catch {
+            throw new AuthError("credential_store_failed");
+        }
+        return boundSnapshot(binding, method, snapshot);
+    }
+    async renew(binding, method, observedRevision, rejected = false) {
+        const auth = method.authentication;
+        if (auth.kind !== "oauth2")
+            throw new AuthError("invalid_definition");
+        let callbackError;
+        let committed;
+        try {
+            committed = await binding.connection.update(async (current) => {
+                try {
+                    validateCredential(method, current);
+                    const previous = grantFrom(method, current);
+                    if ((fresh(previous) && !rejected) ||
+                        (previous &&
+                            previous.revision !== observedRevision &&
+                            previous.tokens.accessToken &&
+                            (previous.tokens.expiresAt === undefined ||
+                                previous.tokens.expiresAt > Date.now())))
+                        return;
+                    const options = {
+                        fetch: this.options.fetch,
+                        timeoutMs: this.options.timeoutMs,
+                    };
+                    const jwtIdentity = binding.jwtIdentity;
+                    if (auth.renewal === "jwtBearer" && !jwtIdentity)
+                        throw new AuthError("invalid_credentials");
+                    const tokens = auth.renewal === "refresh"
+                        ? await refreshOAuth2Token(auth.definition, {
+                            application: binding.application,
+                            tokens: previous?.tokens ?? {},
+                            scopes: auth.scopes,
+                        }, options)
+                        : auth.renewal === "jwtBearer" && jwtIdentity
+                            ? await acquireOAuth2JwtToken(auth.definition, {
+                                identity: jwtIdentity,
+                                scopes: auth.scopes ?? [],
+                            }, options)
+                            : await acquireOAuth2ClientToken(auth.definition, {
+                                application: binding.application ?? { clientId: "" },
+                                scopes: auth.scopes,
+                            }, options);
+                    const patch = {
+                        [auth.grantField]: { tokens, revision: randomUUID() },
+                    };
+                    const next = { ...current, ...patch };
+                    validateCredential(method, next);
+                    grantFrom(method, next);
+                    secret(tokens.accessToken);
+                    return patch;
+                }
+                catch (error) {
+                    callbackError = error;
+                    throw error;
+                }
+            });
+        }
+        catch (error) {
+            if (error === callbackError && error instanceof AuthError)
+                throw error;
+            throw new AuthError("credential_store_failed");
+        }
+        const grant = grantFrom(method, boundSnapshot(binding, method, committed));
+        if (!grant)
+            throw new AuthError("invalid_credentials");
+        return grant;
+    }
+    async request(selection, input) {
+        // Pin authority, routing, headers, registration, and replayable bytes before IO.
+        const binding = pinBinding(selection);
+        const method = this.registry.select(binding.type, binding.method);
+        const target = Object.hasOwn(method.targets, input.target)
+            ? method.targets[input.target]
+            : undefined;
+        if (!target)
+            throw new AuthError("request_not_allowed");
+        const url = resourceUrl(target, input.path);
+        const verb = input.method ?? "GET";
+        if (!target.methods.includes(verb) ||
+            (input.retry !== undefined && input.retry !== "never"))
+            throw new AuthError("request_not_allowed");
+        for (const name of url.searchParams.keys()) {
+            if ([
+                "access_token",
+                "refresh_token",
+                "client_secret",
+                "api_key",
+                "authorization",
+            ].includes(name.toLowerCase()))
+                throw new AuthError("request_not_allowed");
+        }
+        const auth = method.authentication;
+        const authHeader = auth.kind === "apiKey" ? headerName(auth.header) : "authorization";
+        let headers;
+        let body;
+        try {
+            headers = new Headers();
+            const allowed = new Set([
+                "accept",
+                "content-type",
+                ...(target.allowedHeaders ?? []).map((name) => name.toLowerCase()),
+            ]);
+            for (const [name, value] of Object.entries(input.headers ?? {})) {
+                const normalized = headerName(name);
+                if (!allowed.has(normalized) ||
+                    normalized === authHeader ||
+                    normalized === "authorization" ||
+                    normalized === target.idempotency?.header.toLowerCase() ||
+                    typeof value !== "string")
+                    throw new Error();
+                headers.set(normalized, value);
+            }
+            if (input.body !== undefined) {
+                if (verb === "GET" ||
+                    verb === "HEAD" ||
+                    (typeof input.body !== "string" &&
+                        !(input.body instanceof Uint8Array)))
+                    throw new Error();
+                const size = typeof input.body === "string"
+                    ? Buffer.byteLength(input.body)
+                    : input.body.byteLength;
+                if (size > this.options.maxRequestBytes)
+                    throw new Error();
+                body = Buffer.from(input.body);
+            }
+            if (input.idempotencyKey !== undefined) {
+                if (!target.idempotency?.methods.includes(verb))
+                    throw new Error();
+                headers.set(target.idempotency.header, secret(input.idempotencyKey));
+            }
+        }
+        catch {
+            throw new AuthError("request_not_allowed");
+        }
+        const replay = input.retry !== "never" &&
+            (verb === "GET" || verb === "HEAD" || input.idempotencyKey !== undefined);
+        let { token, grant } = await this.authorize(binding, method);
+        const send = async (value) => {
+            const signed = new Headers(headers);
+            signed.set(authHeader, auth.kind === "apiKey" ? value : `Bearer ${value}`);
+            return sendResource(url.toString(), verb, signed, body, {
+                ...this.options,
+                resumableUpload: target.resumableUpload,
+            });
+        };
+        const first = await send(token);
+        if (auth.kind !== "oauth2" ||
+            !grant ||
+            !replay ||
+            first.status !== (auth.rejectionStatus ?? 401))
+            return first;
+        // Exactly one replay, only after durable renewal (or a newer committed revision).
+        grant = await this.renew(binding, method, grant.revision, true);
+        return send(secret(grant.tokens.accessToken));
+    }
+    /** Only a declared read-only probe runs. Results never contain provider text or secrets. */
+    async probe(binding) {
+        const probe = this.registry.select(binding.type, binding.method).probe;
+        if (!probe)
+            return { outcome: "unverified" };
+        try {
+            const response = await this.request(binding, probe);
+            return {
+                outcome: probe.acceptedStatuses.includes(response.status)
+                    ? "accepted"
+                    : [401, 403].includes(response.status)
+                        ? "rejected"
+                        : "unverified",
+                status: response.status,
+            };
+        }
+        catch (error) {
+            return {
+                outcome: error instanceof AuthError && error.code === "reconnect_required"
+                    ? "rejected"
+                    : "unverified",
+            };
+        }
+    }
+    /** Trusted-host compatibility primitive. Never expose raw tokens through a broker. */
+    async accessToken(selection) {
+        const binding = pinBinding(selection);
+        return (await this.authorize(binding, this.registry.select(binding.type, binding.method))).token;
+    }
+    async authorize(binding, method) {
+        const config = await this.read(binding, method);
+        const auth = method.authentication;
+        if (auth.kind !== "oauth2")
+            return { token: secret(config[auth.field]) };
+        let grant = grantFrom(method, config);
+        if (!fresh(grant))
+            grant = await this.renew(binding, method, grant?.revision);
+        return { token: secret(grant?.tokens.accessToken), grant };
+    }
+}

package/dist/credentials/types.d.ts

@@ -0,0 +1,80 @@
+import type { TSchema } from "typebox";
+import type { OAuth2Definition, OAuthApplication, OAuthJwtIdentity, OAuthTokens } from "../auth/types.js";
+import type { ConnectionHandle } from "../connections/types.js";
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** Host-approved resource boundary. No wildcards, templates, or agent-selected origins. */
+export interface CredentialTarget {
+    /** HTTPS URL ending in /. Requests stay beneath this exact origin and path. */
+    baseUrl: string;
+    methods: HttpMethod[];
+    /** Additional caller-set headers beyond Accept and Content-Type. Auth is reserved. */
+    allowedHeaders?: string[];
+    /** Google-style PUT upload acknowledgements: allow 308 only without Location. */
+    resumableUpload?: boolean;
+    /** Declare only when the provider guarantees deduplication for these methods. */
+    idempotency?: {
+        header: string;
+        methods: HttpMethod[];
+    };
+}
+export type CredentialAuthentication = {
+    kind: "apiKey";
+    field: string;
+    header: string;
+} | {
+    kind: "bearer";
+    field: string;
+} | {
+    kind: "oauth2";
+    /** Top-level config field containing a revisioned OAuthGrant. */
+    grantField: string;
+    definition: OAuth2Definition;
+    /** Explicit renewal strategy, never inferred from available secrets. */
+    renewal: "refresh" | "clientCredentials" | "jwtBearer";
+    scopes?: string[];
+    /** Defaults to 401. A 403 must be explicitly documented by the provider. */
+    rejectionStatus?: 401 | 403;
+};
+export interface CredentialProbe {
+    target: string;
+    /** Fixed relative path, including any fixed query. No expressions or callbacks. */
+    path: string;
+    method: "GET" | "HEAD";
+    /** Only these 2xx responses count as accepted; this does not prove identity. */
+    acceptedStatuses: number[];
+}
+export interface CredentialMethod {
+    /** Strict object schema for this method's credential config, not action input. */
+    schema: TSchema;
+    authentication: CredentialAuthentication;
+    targets: Record<string, CredentialTarget>;
+    probe?: CredentialProbe;
+}
+/** Registered by trusted hosts; method names describe provider-specific choices. */
+export interface CredentialType {
+    id: string;
+    methods: Record<string, CredentialMethod>;
+}
+/** Host-authorized selection. Never derive this binding from action input. */
+export interface CredentialBinding {
+    type: string;
+    method: string;
+    connection: ConnectionHandle;
+    /** Expected identity of every read and committed update. */
+    identity: {
+        name: string;
+        plugin: string;
+    };
+    application?: OAuthApplication;
+    jwtIdentity?: OAuthJwtIdentity;
+}
+/** Revision changes on every issuance, even when the provider repeats the token value. */
+export interface OAuthGrant {
+    /** Setup may seed only a refresh token; issuance always supplies an access token. */
+    tokens: Partial<OAuthTokens>;
+    revision: string;
+}
+export type CredentialProbeResult = {
+    outcome: "accepted" | "rejected" | "unverified";
+    status?: number;
+};

package/dist/credentials/types.js

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

package/dist/index.d.ts

@@ -1,10 +1,22 @@
+export { AuthError, type AuthErrorCode } from "./auth/errors.js";
+export { acquireOAuth2ClientToken, acquireOAuth2JwtToken, 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 { 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";
+export { FileConnectionProvider } from "./connections/file.js";
+export { MemoryConnectionProvider } from "./connections/memory.js";
+export type { ConnectionHandle, ConnectionPatch, ConnectionProvider, ConnectionRequest, ConnectionUpdate, ConnectionUpdater, } from "./connections/types.js";
 export type { ActionInvocation, EngineHooks, EngineOptions, ExecuteResult, } from "./core/engine.js";
 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, 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 { CredentialTransport } from "./credentials/transport.js";
+export type { CredentialAuthentication, CredentialBinding, CredentialMethod, CredentialProbe, CredentialProbeResult, CredentialTarget, CredentialType, HttpMethod, OAuthGrant, } 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";

package/dist/index.js

@@ -1,7 +1,15 @@
+export { AuthError } from "./auth/errors.js";
+export { acquireOAuth2ClientToken, acquireOAuth2JwtToken, 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";
+export { FileConnectionProvider } from "./connections/file.js";
+export { MemoryConnectionProvider } from "./connections/memory.js";
 export { ExecutionEngine } from "./core/engine.js";
 export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_URI, runOAuth, } from "./core/oauth.js";
+export { downloadResource } from "./credentials/http.js";
+export { CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, 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";

package/dist/plugin/types.d.ts

@@ -1,4 +1,6 @@
 import type { TSchema } from "typebox";
+import type { OAuth2Definition } from "../auth/types.js";
+import type { ConnectionUpdate } from "../connections/types.js";
 export interface InputField {
     type: "string" | "number" | "boolean" | "object" | "array";
     description?: string;
@@ -64,18 +66,15 @@ export interface ActionContext {
         error(msg: string): void;
     };
     /**
-     * Merge a partial config patch into the current connection,
-     * persisting it atomically to `.runline/config.json`.
+     * Persist a shallow config patch through the host's connection provider.
+     * For token refresh, pass an async updater: it receives freshly read config
+     * under update ownership, so the provider coordinates the whole refresh.
+     * Return undefined to reuse a token refreshed by another caller.
      *
-     * Intended for plugins that refresh credentials at runtime
-     * (OAuth access tokens, rotating API keys). The write is
-     * guarded by a file lock, so concurrent `runline exec`
-     * processes refreshing the same connection won't race.
-     *
-     * In-memory `ctx.connection.config` is also mutated so the
-     * rest of the current action sees the new values.
+     * This action's snapshot changes only after a successful store update.
+     * A patch alone serializes the write, not any preceding network request.
      */
-    updateConnection(patch: Record<string, unknown>): Promise<void>;
+    updateConnection(change: ConnectionUpdate): Promise<void>;
 }
 /**
  * OAuth2 authorization-code configuration declared by a plugin.
@@ -84,19 +83,32 @@ export interface ActionContext {
  * of `clientId`, `clientSecret`, `refreshToken`, `accessToken`,
  * and `accessTokenExpiresAt` into the plugin's connection.
  */
-export interface OAuthConfig {
-    /** Authorization endpoint, e.g. https://accounts.google.com/o/oauth2/v2/auth */
+export type OAuthConfig = OAuthSetupOptions & ({
+    /** One provider definition supplies every endpoint and protocol policy. */
+    protocol: OAuth2Definition;
+    authUrl?: never;
+    tokenUrl?: never;
+    authParams?: never;
+} | {
+    /** Flat declarations use body-secret authentication at the adapter boundary. */
+    protocol?: never;
     authUrl: string;
-    /** Token endpoint, e.g. https://oauth2.googleapis.com/token */
     tokenUrl: string;
+    authParams?: Record<string, string>;
+});
+interface OAuthSetupOptions {
     /** Scopes to request on the consent screen. */
     scopes: string[];
     /**
-     * Extra query parameters on the auth URL. Used for provider-
-     * specific knobs like Google's `access_type=offline` and
-     * `prompt=consent` (both required to get a refresh token back).
+     * Provider-fixed loopback callback (`http://localhost:<port>/<path>`),
+     * replacing Runline's default `http://127.0.0.1:47823/callback`. Use only
+     * when the provider validates redirects against a URI it published.
      */
-    authParams?: Record<string, string>;
+    redirectUri?: string;
+    /** Public client: PKCE protects the exchange and no client secret is collected or sent. */
+    publicClient?: boolean;
+    /** Provider-published client identifier used when the user supplies none. */
+    defaultClientId?: string;
     /**
      * Printed by `runline auth <plugin>` before credentials are
      * requested. Each array entry is a line. The token
@@ -119,3 +131,4 @@ export interface PluginDef {
     /** @internal */
     initHooks?: Array<(config: Record<string, unknown>) => void>;
 }
+export {};

package/dist/plugins/_shared/credentialAdapter.js

@@ -0,0 +1,88 @@
+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)]))
+        .digest("hex");
+    const expected = fingerprint(ctx.connection.config);
+    const project = (current) => {
+        if (fingerprint(current) !== expected)
+            throw new AuthError("binding_changed");
+        const compatible = current.authTokenBinding === undefined ||
+            current.authTokenBinding === expected;
+        const tokens = {
+            ...(compatible && current.accessToken !== undefined
+                ? { accessToken: current.accessToken }
+                : {}),
+            ...(current.refreshToken !== undefined
+                ? { refreshToken: current.refreshToken }
+                : {}),
+            ...(compatible && current.accessTokenExpiresAt !== undefined
+                ? { expiresAt: current.accessTokenExpiresAt }
+                : {}),
+            ...(compatible && current.authTokenScope !== undefined
+                ? { scope: current.authTokenScope }
+                : {}),
+            ...(compatible && current.authTokenType !== undefined
+                ? { tokenType: current.authTokenType }
+                : {}),
+        };
+        if (!Object.keys(tokens).length)
+            return {};
+        const revision = typeof current.authTokenRevision === "string" && compatible
+            ? current.authTokenRevision
+            : createHash("sha256").update(JSON.stringify(tokens)).digest("hex");
+        return { grant: { tokens, revision } };
+    };
+    const snapshot = () => ({
+        ...identity,
+        config: project(ctx.connection.config),
+    });
+    const binding = {
+        type: definition.id,
+        method,
+        identity,
+        application: {
+            clientId: ctx.connection.config.clientId,
+            clientSecret: ctx.connection.config.clientSecret,
+        },
+        connection: {
+            async read() {
+                return snapshot();
+            },
+            async update(change) {
+                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;
+                    if (!grant?.tokens.accessToken)
+                        throw new AuthError("invalid_credentials");
+                    return {
+                        accessToken: grant.tokens.accessToken,
+                        accessTokenExpiresAt: grant.tokens.expiresAt,
+                        refreshToken: grant.tokens.refreshToken ?? current.refreshToken,
+                        authTokenScope: grant.tokens.scope,
+                        authTokenType: grant.tokens.tokenType,
+                        authTokenRevision: grant.revision,
+                        authTokenBinding: expected,
+                    };
+                });
+                return snapshot();
+            },
+        },
+    };
+    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.
+    const transport = new CredentialTransport(registry, {
+        fetch: globalThis.fetch,
+        maxRequestBytes: 64 * 1024 * 1024,
+        maxResponseBytes: 64 * 1024 * 1024,
+    });
+    return { binding, transport };
+}