runline 0.33.0 → 0.35.0

package/dist/plugins/_shared/credentials.js

@@ -0,0 +1,416 @@
+import { AuthError, OAuthGrantSchema, staticSecretSchema, } from "runline";
+import * as t from "typebox";
+import { credentialBroker } from "./credentialAdapter.js";
+/**
+ * The plugin side of the credential broker, shared by every plugin: one
+ * declaration factory for static keys, one stored grant shape for OAuth
+ * methods, one way to turn public config into an HTTPS target, one
+ * request path.
+ */
+/**
+ * The stored shape of an OAuth method: one optional revisioned grant in the
+ * `grant` field, absent until the first issuance.
+ */
+export const grantSchema = t.Object({ grant: t.Optional(OAuthGrantSchema) }, { additionalProperties: false });
+/** The parts and placements a shorthand, or the general form, declares. */
+function placementsOf(auth) {
+    if (auth.kind === "static") {
+        const { kind: _, ...declared } = auth;
+        return declared;
+    }
+    if (auth.kind === "basic")
+        return {
+            parts: ["username", "password"],
+            placements: [{ in: "basic", username: "username", password: "password" }],
+        };
+    const placement = auth.kind === "bearer"
+        ? {
+            in: "header",
+            part: "secret",
+            name: "Authorization",
+            prefix: "Bearer ",
+        }
+        : auth.kind === "queryKey"
+            ? { in: "query", part: "secret", name: auth.param }
+            : {
+                in: "header",
+                part: "secret",
+                name: auth.header,
+                ...(auth.prefix === undefined ? {} : { prefix: auth.prefix }),
+            };
+    return { parts: ["secret"], placements: [placement] };
+}
+/**
+ * A static-key plugin's declaration. The secret lives in one structured
+ * `credential` field — `{ secret }`, `{ username, password }` for basic, or
+ * the general form's named parts — and the method is named for the auth
+ * kind, so every static declaration has the same shape. A host stores the
+ * structured field; the CLI's flat fields are named by `local`.
+ */
+export function staticCredential(spec) {
+    const field = "credential";
+    const { parts, optionalParts, placements } = placementsOf(spec.auth);
+    if (Object.keys(spec.local).sort().join() !== [...parts].sort().join())
+        throw new AuthError("invalid_definition");
+    const localSecret = Object.fromEntries(Object.entries(spec.local).map(([key, source]) => [
+        key,
+        typeof source === "string" ? { field: source } : source,
+    ]));
+    const fields = Object.values(localSecret).flatMap((source) => ("concat" in source ? source.concat : [source]).flatMap((part) => "field" in part ? [part.field] : []));
+    return (config) => {
+        const targets = typeof spec.targets === "function" ? spec.targets(config) : spec.targets;
+        const signed = !spec.optional ||
+            config.authenticated === true ||
+            fields.every((name) => typeof config[name] === "string" && config[name]);
+        return {
+            type: {
+                id: spec.id,
+                methods: {
+                    [spec.auth.kind]: {
+                        schema: t.Object({ [field]: staticSecretSchema(parts, optionalParts) }, { additionalProperties: false }),
+                        authentication: {
+                            kind: "static",
+                            field,
+                            parts,
+                            ...(optionalParts ? { optionalParts } : {}),
+                            placements,
+                        },
+                        targets,
+                        ...(spec.probe ? { probe: spec.probe } : {}),
+                    },
+                    ...(spec.optional
+                        ? {
+                            none: {
+                                schema: t.Object({}, { additionalProperties: false }),
+                                authentication: { kind: "none" },
+                                targets: spec.optional === true ? targets : spec.optional.targets,
+                            },
+                        }
+                        : {}),
+                },
+            },
+            ...(signed
+                ? { method: spec.auth.kind, localSecret }
+                : { method: "none" }),
+        };
+    };
+}
+/**
+ * An HTTPS base URL from public config, with `path` appended beneath it.
+ * Anything else — plain HTTP, embedded credentials, a query or fragment —
+ * is invalid_credentials: the connection cannot be signed as configured.
+ */
+export function httpsBase(value, path) {
+    try {
+        if (typeof value !== "string")
+            throw new Error();
+        const url = new URL(value);
+        if (url.protocol !== "https:" ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            value.includes("?") ||
+            value.includes("#"))
+            throw new Error();
+        const base = url.pathname.endsWith("/") ? url.pathname : `${url.pathname}/`;
+        return `${url.origin}${base}${path}`;
+    }
+    catch {
+        throw new AuthError("invalid_credentials");
+    }
+}
+/** One DNS label from public config, for `https://{label}.provider.com/` hosts. */
+export function hostLabel(value) {
+    if (typeof value !== "string" ||
+        !/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/i.test(value))
+        throw new AuthError("invalid_credentials");
+    return value;
+}
+/**
+ * One of a config field's documented values — a region, an environment,
+ * a hosting mode — or `fallback` when the field is absent. Anything else
+ * is invalid_credentials, never mapped to a default: a mistyped value
+ * would otherwise send the credential to another host.
+ */
+export function configChoice(value, choices, fallback) {
+    if (value === undefined || value === null)
+        return fallback;
+    if (typeof value !== "string" ||
+        !choices.includes(value))
+        throw new AuthError("invalid_credentials");
+    return value;
+}
+/**
+ * A boolean config field, as a boolean or the string a CLI or environment
+ * variable gives (`"true"`, `"false"`); false when absent. Anything else
+ * is invalid_credentials, as for `configChoice`: a mistyped sandbox or
+ * SSL flag must not read as false and reach the live host.
+ */
+export function configFlag(value) {
+    if (typeof value === "boolean")
+        return value;
+    return configChoice(value, ["true", "false"], "false") === "true";
+}
+/**
+ * An ID or name as exactly one path segment, the one encoder every plugin
+ * uses. A value that is not one segment is refused rather than encoded: an
+ * empty value would address the parent collection (`items/`), a dot segment
+ * a sibling, and a separator more than one segment.
+ */
+export function pathSegment(value) {
+    const raw = value === undefined || value === null ? "" : String(value);
+    if (!raw || raw === "." || raw === ".." || /[/\\]/.test(raw))
+        throw new AuthError("request_not_allowed");
+    return encodeURIComponent(raw);
+}
+/**
+ * A slash-separated name the API addresses as a sub-path — a model's
+ * `owner/name`, a file path, a nested job — each segment by `pathSegment`,
+ * its slashes kept.
+ */
+export function pathSegments(value) {
+    return String(value ?? "")
+        .split("/")
+        .map(pathSegment)
+        .join("/");
+}
+/**
+ * A slashed name as exactly one segment, its slashes encoded
+ * (`@scope/pkg` → `%40scope%2Fpkg`), for a target that declares
+ * `encodedSlashes`. An empty or dot piece, or a backslash, is refused.
+ */
+export function slashEncodedSegment(value) {
+    return pathSegments(value).replaceAll("/", "%2F");
+}
+/** Parameters as `a=1&b=2`: arrays repeat the key; null and undefined are skipped. */
+function encodeParams(params) {
+    const encoded = new URLSearchParams();
+    for (const [key, value] of Object.entries(params)) {
+        if (value === undefined || value === null)
+            continue;
+        for (const entry of Array.isArray(value) ? value : [value])
+            encoded.append(key, String(entry));
+    }
+    return encoded.toString();
+}
+function withQuery(path, query) {
+    if (!query)
+        return path;
+    const encoded = encodeParams(query);
+    if (!encoded)
+        return path;
+    return `${path}${path.includes("?") ? "&" : "?"}${encoded}`;
+}
+/** The one authenticated request path: the host's broker, else the local signer. */
+export function credentialRequest(ctx, declaration, call) {
+    const body = call.json !== undefined
+        ? { type: "application/json", body: JSON.stringify(call.json) }
+        : call.form !== undefined
+            ? {
+                type: "application/x-www-form-urlencoded",
+                body: encodeParams(call.form),
+            }
+            : undefined;
+    const payload = body?.body ?? call.body;
+    return credentialBroker(ctx, declaration).request({
+        target: call.target,
+        path: withQuery(call.path, call.query),
+        method: call.method ?? "GET",
+        headers: {
+            Accept: "application/json",
+            ...(body ? { "Content-Type": body.type } : {}),
+            ...call.headers,
+        },
+        ...(payload !== undefined ? { body: payload } : {}),
+        ...(call.destination !== undefined
+            ? { destination: call.destination }
+            : {}),
+        ...(call.idempotencyKey !== undefined
+            ? { idempotencyKey: call.idempotencyKey }
+            : {}),
+    });
+}
+/**
+ * A step that writes a grant into the connection — an owner login run
+ * against the provider — happens only where the grant lives: this process,
+ * signing with its own connection. Under a host that keeps the grant, setup
+ * is the host's, and the step refuses before any request.
+ */
+export function refuseUnderHost(ctx) {
+    if (ctx.credentials)
+        throw new AuthError("unsupported_operation");
+}
+/**
+ * A socket target's URL for this connection, from the broker: signed by
+ * the local signer, or a relay the host controls. A broker that serves no
+ * sockets refuses as unsupported_operation.
+ */
+export async function credentialSocketUrl(ctx, declaration, call) {
+    const broker = credentialBroker(ctx, declaration);
+    if (!broker.socketUrl)
+        throw new AuthError("unsupported_operation");
+    return broker.socketUrl({
+        target: call.target,
+        path: withQuery(call.path, call.query),
+    });
+}
+/**
+ * A provider error identifier worth handing back — an error code, a field
+ * path — as a plain name. Anything else is not a name and is dropped, so
+ * the code and field slots of a failure never carry free text.
+ */
+export function errorIdentifier(value) {
+    return typeof value === "string" && /^[\w.$:-]{1,100}$/.test(value)
+        ? value
+        : undefined;
+}
+/**
+ * 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`. 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}`]
+        .filter(Boolean)
+        .join(", ");
+    const inner = [status === undefined ? "" : `HTTP ${status}`, identifiers]
+        .filter(Boolean)
+        .join(" ");
+    return `${plugin}: request failed${inner ? ` (${inner})` : ""}`;
+}
+/** A code or field path as a plain identifier, numbers included. */
+function identifierOf(value) {
+    return errorIdentifier(typeof value === "number" ? String(value) : value);
+}
+/**
+ * A successful response whose answer reports failure — Slack's `ok: false`,
+ * an OCS status, a GraphQL `errors` entry — by the provider's code, the
+ * field at fault and its message. The answer is 2xx data the plugin
+ * already holds, so the message stays for the caller to act on, reduced
+ * to one line of at most 300 characters.
+ */
+export function answerFailed(plugin, detail) {
+    const head = failureMessage(plugin, undefined, {
+        code: identifierOf(detail.code),
+        param: identifierOf(detail.param),
+    });
+    const text = typeof detail.message === "string"
+        ? detail.message.replace(/[\u0000-\u001f\u007f\s]+/g, " ").trim()
+        : "";
+    const line = text.length > 300 ? `${text.slice(0, 300)}…` : text;
+    return new Error(line ? `${head}: ${line}` : head);
+}
+/** A GraphQL answer's `errors`, read by `answerFailed` from the first entry. */
+export function graphqlFailed(plugin, errors) {
+    const first = (Array.isArray(errors) ? errors[0] : undefined);
+    return answerFailed(plugin, {
+        code: first?.extensions?.code,
+        param: Array.isArray(first?.path) ? first.path.join(".") : undefined,
+        message: first?.message,
+    });
+}
+/** A failed request, reported by status alone. */
+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);
+    if (!response.ok)
+        throw requestFailed(plugin, response.status);
+    return response;
+}
+/**
+ * A successful response's JSON. `T` is the caller's statement of the
+ * answer's shape, unchecked, as for any parsed JSON; without one it is
+ * `unknown`. An empty answer is `EmptyAnswer`, so a caller whose endpoint
+ * can answer empty includes it in `T`. Every JSON request path reads its
+ * answer here, so they cannot disagree about empty or malformed bodies.
+ */
+export async function jsonAnswer(response) {
+    const empty = { success: true };
+    if (response.status === 204)
+        return empty;
+    const text = await response.text();
+    if (!text)
+        return empty;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new AuthError("invalid_response");
+    }
+}
+/**
+ * A successful response's JSON when its Content-Type says JSON; any other
+ * body — a text "OK", nothing at all — is an acknowledgement,
+ * `EmptyAnswer`. For APIs whose writes answer without JSON.
+ */
+export async function jsonOrAcknowledged(response) {
+    return (response.headers.get("content-type") ?? "").includes("application/json")
+        ? jsonAnswer(response)
+        : { success: true };
+}
+/** A JSON request that must succeed; its answer is read by `jsonAnswer`. */
+export async function credentialJson(ctx, declaration, plugin, call) {
+    return jsonAnswer(await credentialOk(ctx, declaration, plugin, call));
+}
+/**
+ * A next-page URL the API returned, as a path beneath the declared target
+ * it will be signed for. Anything outside that target's exact origin and
+ * path prefix is refused rather than followed with the credential attached.
+ */
+export function pathWithin(ctx, declaration, target, value) {
+    const { type, method } = declaration(ctx.connection.config);
+    const targets = type.methods[method]?.targets ?? {};
+    if (!Object.hasOwn(targets, target))
+        throw new AuthError("request_not_allowed");
+    try {
+        const base = new URL(targets[target].baseUrl);
+        const url = new URL(value);
+        if (url.origin !== base.origin ||
+            url.username ||
+            url.password ||
+            url.hash ||
+            !url.pathname.startsWith(base.pathname))
+            throw new Error();
+        return `${url.pathname.slice(base.pathname.length)}${url.search}`;
+    }
+    catch {
+        throw new AuthError("request_not_allowed");
+    }
+}
+/** FormData as the buffered bytes the transport accepts, with its boundary. */
+export async function multipartBody(form) {
+    const response = new Response(form);
+    const contentType = response.headers.get("content-type");
+    if (!contentType)
+        throw new AuthError("request_not_allowed");
+    return { body: new Uint8Array(await response.arrayBuffer()), contentType };
+}

package/dist/plugins/_shared/googleAuth.js

@@ -1,29 +1,68 @@
 import { AuthError, downloadResource, } from "runline";
-import { credentialRuntime } from "./credentialAdapter.js";
-import { googleCredentialType, googleIdentity, googleMethod, googleResources, } from "./googleCredentials.js";
-/** Explicit storage adapter: the registry owns token protocols and renewal. */
-export function googleRuntime(ctx, pluginName, scopes) {
-    const config = ctx.connection.config;
-    const method = googleMethod(config);
-    const runtime = credentialRuntime(ctx, googleCredentialType(scopes, pluginName), method, (current) => {
-        const cfg = current;
-        return [
-            pluginName,
-            scopes,
-            googleMethod(cfg),
-            ...(method === "serviceAccount"
-                ? [googleIdentity(cfg)]
-                : [cfg.clientId, cfg.clientSecret]),
-        ];
-    });
-    if (method === "serviceAccount")
-        runtime.binding.jwtIdentity = googleIdentity(config);
-    return runtime;
-}
-/** Trusted-runtime token compatibility only; resource consumers use googleResponse. */
-export async function googleAccessToken(ctx, pluginName, scopes) {
-    const { binding, transport } = googleRuntime(ctx, pluginName, scopes);
-    return transport.accessToken(binding);
+import { credentialBroker } from "./credentialAdapter.js";
+import { jsonAnswer, requestFailed } from "./credentials.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) {
@@ -45,8 +84,7 @@ export async function googleResponse(ctx, plugin, scopes, url, init = {}, query)
         }
         path = `${separator < 0 ? path : path.slice(0, separator)}?${params}`;
     }
-    const { binding, transport } = googleRuntime(ctx, plugin, scopes);
-    return transport.request(binding, {
+    return credentialBroker(ctx, googleCredential(plugin, scopes)).request({
         target,
         path,
         method: (init.method ?? "GET"),
@@ -54,6 +92,7 @@ export async function googleResponse(ctx, plugin, scopes, url, init = {}, query)
         body: init.body,
     });
 }
+/** A Google JSON request that must succeed; its answer is read by `jsonAnswer`. */
 export async function googleJsonRequest(ctx, plugin, scopes, method, url, body, query) {
     const response = await googleResponse(ctx, plugin, scopes, url, {
         method,
@@ -64,20 +103,11 @@ export async function googleJsonRequest(ctx, plugin, scopes, method, url, body,
         body: body === undefined ? undefined : JSON.stringify(body),
     }, query);
     if (!response.ok)
-        throw new Error(`${plugin}: request failed (HTTP ${response.status})`);
-    if (response.status === 204)
-        return { success: true };
-    const text = await response.text();
-    try {
-        return text ? JSON.parse(text) : { success: true };
-    }
-    catch {
-        throw new AuthError("invalid_response");
-    }
+        throw requestFailed(plugin, response.status);
+    return jsonAnswer(response);
 }
 export async function googleProbe(ctx, plugin, scopes) {
-    const { binding, transport } = googleRuntime(ctx, plugin, scopes);
-    return transport.probe(binding);
+    return credentialBroker(ctx, googleCredential(plugin, scopes)).probe();
 }
 /** Only Google-issued thumbnail hosts; never attach credentials to signed URLs. */
 export async function googleDownload(value) {