runline 0.33.0 → 0.35.0

package/dist/credentials/transport.js

@@ -1,9 +1,9 @@
-import { randomUUID } from "node:crypto";
+import { createHmac, randomUUID } from "node:crypto";
 import { Check } from "typebox/value";
 import { AuthError } from "../auth/errors.js";
-import { acquireOAuth2ClientToken, acquireOAuth2JwtToken, refreshOAuth2Token, } from "../auth/oauth2.js";
+import { acquireOAuth2ClientToken, acquireOAuth2JwtToken, acquireOAuth2PasswordToken, refreshOAuth2Token, } from "../auth/oauth2.js";
 import { sendResource } from "./http.js";
-import { headerName, resourceUrl } from "./policy.js";
+import { bodyFields, bodyFormat, bounded, headerName, injectedFields, injectedHeaders, injectedParams, injectedPointers, placementsFor, pointerSlot, refuseCredentialParams, resourceUrl, TARGET_RESPONSE_LIMIT_BYTES, TARGET_TIMEOUT_LIMIT_MS, TRANSPORT_HEADERS, targetBase, targetOf, } from "./policy.js";
 import { OAuthGrantSchema, validateCredential, } from "./registry.js";
 function boundSnapshot(binding, method, snapshot) {
     if (snapshot.name !== binding.identity.name ||
@@ -16,7 +16,7 @@ function grantFrom(method, config) {
     const auth = method.authentication;
     if (auth.kind !== "oauth2")
         throw new AuthError("invalid_definition");
-    const grant = config[auth.grantField];
+    const grant = config[auth.field];
     if (grant === undefined)
         return undefined;
     if (!Check(OAuthGrantSchema, grant))
@@ -33,6 +33,7 @@ function pinBinding(selection) {
         identity: { ...selection.identity },
         application: structuredClone(selection.application),
         jwtIdentity: structuredClone(selection.jwtIdentity),
+        resourceOwner: structuredClone(selection.resourceOwner),
         connection: {
             read: selection.connection.read.bind(selection.connection),
             update: selection.connection.update.bind(selection.connection),
@@ -51,6 +52,142 @@ function secret(value) {
         throw new AuthError("invalid_credentials");
     return value;
 }
+/**
+ * A part sent whole as a header value, such as `Bearer <token>`: printable
+ * ASCII whose interior spaces are part of the value, with no control
+ * character and no space at either end.
+ */
+function headerValue(value) {
+    if (typeof value !== "string" ||
+        !value ||
+        value !== value.trim() ||
+        [...value].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) > 126))
+        throw new AuthError("invalid_credentials");
+    return value;
+}
+/**
+ * RFC 7617 user-pass. A colon in the username, or any byte outside printable
+ * ASCII, would make the header ambiguous or encoding-dependent.
+ */
+function basicCredentials(username, password) {
+    if ((!username && !password) ||
+        username.includes(":") ||
+        [...username, ...password].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) > 126))
+        throw new AuthError("invalid_credentials");
+    return Buffer.from(`${username}:${password}`).toString("base64");
+}
+/**
+ * A secret as one path segment: `/`, `\`, `?`, `#` and dot segments are
+ * refused rather than encoded; `:` and `@`, which RFC 3986 allows in a
+ * segment, stay literal (Telegram's `bot<id>:<token>`).
+ */
+function pathPart(value) {
+    if (value === "." || value === ".." || /[/\\?#]/.test(value))
+        throw new AuthError("invalid_credentials");
+    return encodeURIComponent(value).replace(/%3A/gi, ":").replace(/%40/gi, "@");
+}
+/**
+ * Mints HS256 JWTs from a `<key id>:<hex secret>` key for `audience`,
+ * each issued when minted and valid five minutes. Any other key shape is
+ * refused here, before any IO.
+ */
+function hs256Jwt(key, audience) {
+    const match = /^([A-Za-z0-9]+):((?:[0-9a-f]{2})+)$/i.exec(key);
+    if (!match)
+        throw new AuthError("invalid_credentials");
+    const secret = Buffer.from(match[2], "hex");
+    const encode = (value) => Buffer.from(JSON.stringify(value)).toString("base64url");
+    const header = encode({ alg: "HS256", typ: "JWT", kid: match[1] });
+    return () => {
+        const iat = Math.floor(Date.now() / 1000);
+        const unsigned = `${header}.${encode({ iat, exp: iat + 300, aud: audience })}`;
+        const signature = createHmac("sha256", secret)
+            .update(unsigned)
+            .digest("base64url");
+        return `${unsigned}.${signature}`;
+    };
+}
+function bearer(token) {
+    return ({ headers }) => headers.set("authorization", `Bearer ${token}`);
+}
+/**
+ * Adds a field to a JSON-object or form body, whose shape was checked
+ * before any IO; with no body, to the query.
+ */
+function addField(request, name, value) {
+    if (!request.body) {
+        request.url.searchParams.append(name, value);
+        return;
+    }
+    const text = request.body.toString();
+    if (bodyFormat(request.headers) === "form") {
+        const form = new URLSearchParams(text);
+        form.append(name, value);
+        request.body = Buffer.from(form.toString());
+    }
+    else {
+        request.body = Buffer.from(JSON.stringify({ ...JSON.parse(text), [name]: value }));
+    }
+}
+/**
+ * A static secret's signer for one target, every part it places checked
+ * before any IO. `parts` has passed the method's schema, which the
+ * registry pins to exactly the declared parts, each a string; an optional
+ * part the connection lacks refuses the targets that place it. A query
+ * signature runs last, over the query every other placement has written.
+ */
+function placeStatic(auth, parts, target) {
+    const part = (name) => {
+        const value = parts[name];
+        if (value === undefined)
+            throw new AuthError("invalid_credentials");
+        return value;
+    };
+    const ordered = placementsFor(auth, target).sort((a, b) => Number(a.in === "querySignature") - Number(b.in === "querySignature"));
+    const steps = ordered.map((placement) => {
+        if (placement.in === "basic") {
+            const value = basicCredentials(part(placement.username), part(placement.password));
+            return ({ headers }) => headers.set("authorization", `Basic ${value}`);
+        }
+        const value = placement.in === "header"
+            ? headerValue(part(placement.part))
+            : secret(part(placement.part));
+        if (placement.in === "query")
+            return ({ url }) => url.searchParams.append(placement.name, value);
+        if (placement.in === "body")
+            return (request) => addField(request, placement.name, value);
+        if (placement.in === "jsonPointer")
+            return (request) => {
+                const json = JSON.parse(String(request.body));
+                const slot = pointerSlot(json, placement.pointer);
+                if (!slot)
+                    throw new AuthError("request_not_allowed");
+                slot.holder[slot.key] = value;
+                request.body = Buffer.from(JSON.stringify(json));
+            };
+        if (placement.in === "path") {
+            const segment = `${placement.prefix ?? ""}${pathPart(value)}`;
+            return ({ url, base }) => {
+                const rest = url.pathname.slice(base.length);
+                url.pathname = `${base}${segment}${rest ? `/${rest}` : ""}`;
+            };
+        }
+        const name = headerName(placement.name);
+        if (placement.in === "jwt") {
+            const mint = hs256Jwt(value, placement.audience);
+            return ({ headers }) => headers.set(name, `${placement.prefix ?? ""}${mint()}`);
+        }
+        if (placement.in === "querySignature")
+            return ({ url, headers }) => headers.set(name, createHmac("sha256", value)
+                .update(url.search.slice(1))
+                .digest("base64"));
+        return ({ headers }) => headers.set(name, `${placement.prefix ?? ""}${value}`);
+    });
+    return (request) => {
+        for (const step of steps)
+            step(request);
+    };
+}
 /**
  * Trusted-host primitive, not a workspace sandbox. Callers authorize a binding on
  * every invocation. Handles own lifecycle fencing; no second lock or token cache.
@@ -65,17 +202,15 @@ export class CredentialTransport {
             timeoutMs: options.timeoutMs ?? 20_000,
             maxResponseBytes: options.maxResponseBytes ?? 8 * 1024 * 1024,
             maxRequestBytes: options.maxRequestBytes ?? 1024 * 1024,
+            maxTargetTimeoutMs: options.maxTargetTimeoutMs ?? 10 * 60_000,
+            maxTargetResponseBytes: options.maxTargetResponseBytes ?? 256 * 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)
+            !bounded(this.options.timeoutMs, 120_000) ||
+            !bounded(this.options.maxResponseBytes, 64 * 1024 * 1024) ||
+            !bounded(this.options.maxRequestBytes, 64 * 1024 * 1024) ||
+            !bounded(this.options.maxTargetTimeoutMs, TARGET_TIMEOUT_LIMIT_MS) ||
+            !bounded(this.options.maxTargetResponseBytes, TARGET_RESPONSE_LIMIT_BYTES))
             throw new AuthError("invalid_definition");
     }
     async read(binding, method) {
@@ -106,30 +241,9 @@ export class CredentialTransport {
                             (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 tokens = await this.issue(auth, binding, previous);
                     const patch = {
-                        [auth.grantField]: { tokens, revision: randomUUID() },
+                        [auth.field]: { tokens, revision: randomUUID() },
                     };
                     const next = { ...current, ...patch };
                     validateCredential(method, next);
@@ -153,32 +267,43 @@ export class CredentialTransport {
             throw new AuthError("invalid_credentials");
         return grant;
     }
+    /** New tokens by the method's declared renewal, from what the binding supplies. */
+    issue(auth, binding, previous) {
+        const options = {
+            fetch: this.options.fetch,
+            timeoutMs: this.options.timeoutMs,
+        };
+        const { definition, scopes } = auth;
+        const { application, jwtIdentity, resourceOwner } = binding;
+        if (auth.renewal === "refresh")
+            return refreshOAuth2Token(definition, { application, tokens: previous?.tokens ?? {}, scopes }, options);
+        if (auth.renewal === "jwtBearer") {
+            if (!jwtIdentity)
+                throw new AuthError("invalid_credentials");
+            return acquireOAuth2JwtToken(definition, { identity: jwtIdentity, scopes: scopes ?? [] }, options);
+        }
+        if (auth.renewal === "password") {
+            if (!resourceOwner)
+                throw new AuthError("invalid_credentials");
+            return acquireOAuth2PasswordToken(definition, { owner: resourceOwner, application, scopes }, options);
+        }
+        return acquireOAuth2ClientToken(definition, { application: application ?? { clientId: "" }, scopes }, options);
+    }
     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)
+        const target = targetOf(method, input.target);
+        if (!target || target.socket)
             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";
+        refuseCredentialParams(url, injectedParams(auth, input.target));
+        const reserved = injectedHeaders(auth, input.target);
         let headers;
         let body;
         try {
@@ -191,13 +316,23 @@ export class CredentialTransport {
             for (const [name, value] of Object.entries(input.headers ?? {})) {
                 const normalized = headerName(name);
                 if (!allowed.has(normalized) ||
-                    normalized === authHeader ||
-                    normalized === "authorization" ||
+                    reserved.includes(normalized) ||
+                    TRANSPORT_HEADERS.includes(normalized) ||
                     normalized === target.idempotency?.header.toLowerCase() ||
                     typeof value !== "string")
                     throw new Error();
                 headers.set(normalized, value);
             }
+            const copies = verb === "COPY" || verb === "MOVE";
+            if (copies !== (input.destination !== undefined))
+                throw new Error();
+            if (input.destination !== undefined) {
+                if (typeof input.destination !== "string" ||
+                    !input.destination ||
+                    input.destination.includes("?"))
+                    throw new Error();
+                headers.set("destination", resourceUrl(target, input.destination).toString());
+            }
             if (input.body !== undefined) {
                 if (verb === "GET" ||
                     verb === "HEAD" ||
@@ -210,6 +345,21 @@ export class CredentialTransport {
                 if (size > this.options.maxRequestBytes)
                     throw new Error();
                 body = Buffer.from(input.body);
+                const fields = injectedFields(auth, input.target).map((name) => name.toLowerCase());
+                if (fields.length &&
+                    bodyFields(headers, body).some((name) => fields.includes(name.toLowerCase())))
+                    throw new Error();
+            }
+            const pointers = injectedPointers(auth, input.target);
+            if (pointers.length) {
+                if (!body || bodyFormat(headers) !== "json")
+                    throw new Error();
+                const json = JSON.parse(body.toString());
+                for (const pointer of pointers) {
+                    const slot = pointerSlot(json, pointer);
+                    if (!slot || slot.holder[slot.key] !== null)
+                        throw new Error();
+                }
             }
             if (input.idempotencyKey !== undefined) {
                 if (!target.idempotency?.methods.includes(verb))
@@ -222,16 +372,24 @@ export class CredentialTransport {
         }
         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,
+        const base = targetBase(target).pathname;
+        let { sign, grant } = await this.authorize(binding, method, input.target);
+        const send = async (signer) => {
+            const outgoing = {
+                headers: new Headers(headers),
+                url: new URL(url),
+                body,
+                base,
+            };
+            signer(outgoing);
+            return sendResource(outgoing.url.toString(), verb, outgoing.headers, outgoing.body, {
+                fetch: this.options.fetch,
+                timeoutMs: Math.min(target.timeoutMs ?? this.options.timeoutMs, this.options.maxTargetTimeoutMs),
+                maxResponseBytes: Math.min(target.maxResponseBytes ?? this.options.maxResponseBytes, this.options.maxTargetResponseBytes),
                 resumableUpload: target.resumableUpload,
             });
         };
-        const first = await send(token);
+        const first = await send(sign);
         if (auth.kind !== "oauth2" ||
             !grant ||
             !replay ||
@@ -239,7 +397,28 @@ export class CredentialTransport {
             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));
+        return send(bearer(secret(grant.tokens.accessToken)));
+    }
+    /**
+     * A socket target's URL, signed by its query placements, for a host's
+     * relay or the local signer to open. Nothing is sent.
+     */
+    async socketUrl(selection, input) {
+        const binding = pinBinding(selection);
+        const method = this.registry.select(binding.type, binding.method);
+        const target = targetOf(method, input.target);
+        if (!target?.socket)
+            throw new AuthError("request_not_allowed");
+        const url = resourceUrl(target, input.path);
+        refuseCredentialParams(url, injectedParams(method.authentication, input.target));
+        const { sign } = await this.authorize(binding, method, input.target);
+        const outgoing = {
+            headers: new Headers(),
+            url,
+            base: targetBase(target).pathname,
+        };
+        sign(outgoing);
+        return outgoing.url.toString();
     }
     /** Only a declared read-only probe runs. Results never contain provider text or secrets. */
     async probe(binding) {
@@ -265,19 +444,18 @@ export class CredentialTransport {
             };
         }
     }
-    /** 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) {
+    async authorize(binding, method, target) {
         const config = await this.read(binding, method);
         const auth = method.authentication;
-        if (auth.kind !== "oauth2")
-            return { token: secret(config[auth.field]) };
+        if (auth.kind === "none")
+            return { sign: () => { } };
+        if (auth.kind === "static")
+            return {
+                sign: placeStatic(auth, config[auth.field], target),
+            };
         let grant = grantFrom(method, config);
         if (!fresh(grant))
             grant = await this.renew(binding, method, grant?.revision);
-        return { token: secret(grant?.tokens.accessToken), grant };
+        return { sign: bearer(secret(grant?.tokens.accessToken)), grant };
     }
 }

package/dist/credentials/types.d.ts

@@ -1,14 +1,31 @@
 import type { TSchema } from "typebox";
-import type { OAuth2Definition, OAuthApplication, OAuthJwtIdentity, OAuthTokens } from "../auth/types.js";
+import type { OAuth2Definition, OAuthApplication, OAuthJwtIdentity, OAuthResourceOwner, OAuthTokens } from "../auth/types.js";
 import type { ConnectionHandle } from "../connections/types.js";
-export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE";
+/** HTTP methods, and the WebDAV methods a file API needs (RFC 4918). */
+export type HttpMethod = "GET" | "HEAD" | "POST" | "PUT" | "PATCH" | "DELETE" | "MKCOL" | "COPY" | "MOVE";
 /** 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. */
+    /**
+     * HTTPS URL ending in /, or wss:// for a socket target. Requests stay
+     * beneath this exact origin and path.
+     */
     baseUrl: string;
+    /**
+     * A WebSocket endpoint (a browser's CDP socket): the transport signs its
+     * URL with the method's query placements for the plugin to open, and
+     * sends no request to it.
+     */
+    socket?: boolean;
     methods: HttpMethod[];
     /** Additional caller-set headers beyond Accept and Content-Type. Auth is reserved. */
     allowedHeaders?: string[];
+    /**
+     * The provider addresses one resource by a slashed name inside one
+     * segment, encoded (`group%2Fproject`, `@scope%2Fpkg`). Each piece
+     * between the decoded slashes must still be non-empty and not a dot
+     * segment.
+     */
+    encodedSlashes?: boolean;
     /** Google-style PUT upload acknowledgements: allow 308 only without Location. */
     resumableUpload?: boolean;
     /** Declare only when the provider guarantees deduplication for these methods. */
@@ -16,22 +33,135 @@ export interface CredentialTarget {
         header: string;
         methods: HttpMethod[];
     };
+    /**
+     * Deadline for requests to this target when the provider holds them open
+     * longer than the transport default (synchronous extraction, long polls).
+     * Capped by the host's `maxTargetTimeoutMs`.
+     */
+    timeoutMs?: number;
+    /**
+     * Response ceiling for this target when its answers are larger than the
+     * transport default (audio, documents). Capped by the host's
+     * `maxTargetResponseBytes`.
+     */
+    maxResponseBytes?: number;
 }
+/**
+ * Where the transport puts a static secret's parts. Every name it sets is
+ * reserved: a caller may never supply that header, query parameter or
+ * body field.
+ */
+export type SecretPlacement = ({
+    in: "header";
+    part: string;
+    name: string;
+    /** Fixed scheme before the secret, e.g. "Bearer ", "SSWS " or "Bot ". */
+    prefix?: string;
+} | {
+    in: "query";
+    part: string;
+    name: string;
+}
+/**
+ * A top-level field of a JSON-object or form body; in the query when
+ * the request carries no body.
+ */
+ | {
+    in: "body";
+    part: string;
+    name: string;
+}
+/**
+ * A position deeper in a JSON body, by RFC 6901 pointer (Odoo's
+ * `/params/args/2`); the request carries null there for the transport
+ * to fill.
+ */
+ | {
+    in: "jsonPointer";
+    part: string;
+    pointer: string;
+}
+/**
+ * The first path segment beneath the target's base, as `<prefix><part>`:
+ * Telegram's `bot<token>`, an account ID before its resources.
+ */
+ | {
+    in: "path";
+    part: string;
+    prefix?: string;
+}
+/** HTTP Basic in Authorization, from two parts; either may be empty. */
+ | {
+    in: "basic";
+    username: string;
+    password: string;
+}
+/**
+ * An HS256 JWT signed per request from a `<key id>:<hex secret>` part
+ * (Ghost's Admin API key) for `audience`, valid five minutes, sent as
+ * `<name>: <prefix><token>`.
+ */
+ | {
+    in: "jwt";
+    part: string;
+    name: string;
+    prefix?: string;
+    audience: string;
+}
+/**
+ * An HMAC-SHA256 of the request's query string as sent, keyed by the
+ * part, base64 in header `name` (Unleashed); computed after every other
+ * placement, so it signs what goes out.
+ */
+ | {
+    in: "querySignature";
+    part: string;
+    name: string;
+}) & {
+    /**
+     * The targets this placement signs; every target when absent. Two
+     * credentials in one connection, each for its own API, are two parts
+     * scoped to their own targets.
+     */
+    targets?: string[];
+};
+/**
+ * How a request is signed. `field` names the one top-level config field
+ * holding the secret: for `static`, a record of the named `parts`
+ * (`staticSecretSchema(parts)`), each sent through its placements; for
+ * `oauth2`, a revisioned OAuthGrant. `none` signs nothing: the method of a
+ * connection that holds no optional credential, still pinned to its
+ * targets.
+ */
 export type CredentialAuthentication = {
-    kind: "apiKey";
-    field: string;
-    header: string;
+    kind: "none";
 } | {
-    kind: "bearer";
+    kind: "static";
     field: string;
+    parts: string[];
+    /**
+     * Parts a connection may lack; a request to a target that places a
+     * missing part is refused as invalid_credentials.
+     */
+    optionalParts?: string[];
+    placements: SecretPlacement[];
 } | {
     kind: "oauth2";
-    /** Top-level config field containing a revisioned OAuthGrant. */
-    grantField: string;
+    field: string;
     definition: OAuth2Definition;
     /** Explicit renewal strategy, never inferred from available secrets. */
-    renewal: "refresh" | "clientCredentials" | "jwtBearer";
+    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;
 };
@@ -55,6 +185,42 @@ export interface CredentialType {
     id: string;
     methods: Record<string, CredentialMethod>;
 }
+/**
+ * What a connection signs with: the credential type and method, and the
+ * OAuth application, JWT identity and resource owner its config supplies.
+ * Derived from the connection's config alone — never from action input.
+ */
+export interface CredentialSelection {
+    type: CredentialType;
+    method: string;
+    application?: OAuthApplication;
+    jwtIdentity?: OAuthJwtIdentity;
+    resourceOwner?: OAuthResourceOwner;
+    /**
+     * How a process signing with its own flat connection config (the CLI)
+     * assembles a static secret: each of its parts, from a named config
+     * field, a fixed value, or the two joined in order
+     * (`{email}/token`). Names and fixed values only, never a secret. Hosts
+     * that store the structured field ignore it.
+     */
+    localSecret?: Record<string, LocalSecretSource>;
+}
+export type LocalSecretPart = {
+    field: string;
+} | {
+    value: string;
+};
+export type LocalSecretSource = LocalSecretPart | {
+    concat: LocalSecretPart[];
+};
+/**
+ * A plugin's statement of how a connection's config becomes its
+ * selection. Pure: no IO, no action input. Whoever holds the config signs
+ * from it — the plugin's own process, or a host brokering for it, which
+ * reads the declaration from the plugin it loaded itself. Throws
+ * `invalid_credentials` for a config it cannot sign with.
+ */
+export type CredentialDeclaration = (config: Readonly<Record<string, unknown>>) => CredentialSelection;
 /** Host-authorized selection. Never derive this binding from action input. */
 export interface CredentialBinding {
     type: string;
@@ -67,6 +233,7 @@ export interface CredentialBinding {
     };
     application?: OAuthApplication;
     jwtIdentity?: OAuthJwtIdentity;
+    resourceOwner?: OAuthResourceOwner;
 }
 /** Revision changes on every issuance, even when the provider repeats the token value. */
 export interface OAuthGrant {