runline 0.33.0 → 0.34.0

package/dist/credentials/registry.js

@@ -2,8 +2,8 @@ import * as t from "typebox";
 import { Check } from "typebox/value";
 import { AuthError } from "../auth/errors.js";
 import { validateOAuth2ExchangePolicy } from "../auth/oauth2.js";
-import { oauthEndpoint, providerParameters } from "../auth/token.js";
-import { HTTP_METHODS, headerName, resourceUrl, targetBase } from "./policy.js";
+import { oauthEndpoint, providerHeaders, providerParameters, } from "../auth/token.js";
+import { bounded, HTTP_METHODS, headerName, injectedHeaders, injectedParams, injectedPointers, placementsFor, refuseCredentialParams, resourceUrl, TARGET_RESPONSE_LIMIT_BYTES, TARGET_TIMEOUT_LIMIT_MS, TRANSPORT_HEADERS, targetBase, targetOf, } from "./policy.js";
 /** Normalized grant storage; application registration remains host-owned. */
 export const OAuthTokensSchema = t.Object({
     accessToken: t.String({ minLength: 1 }),
@@ -13,6 +13,18 @@ export const OAuthTokensSchema = t.Object({
     tokenType: t.Optional(t.String({ minLength: 1 })),
     metadata: t.Optional(t.Record(t.String(), t.String())),
 }, { additionalProperties: false });
+/**
+ * Stored shape of a static secret: exactly its named parts, each a string,
+ * the `optional` ones allowed to be absent. A Basic part may be empty (a
+ * key as the username with no password, or the reverse); the transport
+ * refuses an empty part anywhere else.
+ */
+export function staticSecretSchema(parts, optional = []) {
+    return t.Object(Object.fromEntries(parts.map((part) => [
+        part,
+        optional.includes(part) ? t.Optional(t.String()) : t.String(),
+    ])), { additionalProperties: false });
+}
 export const OAuthGrantSchema = t.Object({
     tokens: t.Partial(OAuthTokensSchema),
     revision: t.String({ minLength: 1 }),
@@ -21,6 +33,109 @@ function identifier(value) {
     if (typeof value !== "string" || !/^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(value))
         throw new AuthError("invalid_definition");
 }
+/**
+ * A static secret's parts and placements agree with each other, with the
+ * stored shape and with the method's targets: the stored field holds
+ * exactly the declared parts, each a string, required unless optional;
+ * every placement names a declared part and only declared targets; every
+ * part is placed; and on each target at least one placement signs, no
+ * header, query parameter or JSON pointer is claimed twice, and at most
+ * one part takes the one path position.
+ */
+function validateStatic(auth, stored, targets) {
+    const parts = auth.parts;
+    if (!Array.isArray(parts) ||
+        !parts.length ||
+        new Set(parts).size !== parts.length ||
+        !Array.isArray(auth.placements) ||
+        !auth.placements.length)
+        throw new AuthError("invalid_definition");
+    for (const part of parts)
+        identifier(part);
+    const optional = auth.optionalParts ?? [];
+    if (!Array.isArray(optional) ||
+        new Set(optional).size !== optional.length ||
+        optional.some((part) => !parts.includes(part)))
+        throw new AuthError("invalid_definition");
+    const shape = stored;
+    if (shape?.type !== "object" ||
+        shape.additionalProperties !== false ||
+        !shape.properties ||
+        Object.keys(shape.properties).sort().join() !== [...parts].sort().join() ||
+        Object.values(shape.properties).some((part) => part.type !== "string") ||
+        [...(shape.required ?? [])].sort().join() !==
+            parts
+                .filter((part) => !optional.includes(part))
+                .sort()
+                .join())
+        throw new AuthError("invalid_definition");
+    const used = new Set();
+    const place = (part) => {
+        if (typeof part !== "string" || !parts.includes(part))
+            throw new AuthError("invalid_definition");
+        used.add(part);
+    };
+    for (const placement of auth.placements) {
+        if (placement.targets !== undefined &&
+            (!Array.isArray(placement.targets) ||
+                !placement.targets.length ||
+                placement.targets.some((target) => !targets.includes(target))))
+            throw new AuthError("invalid_definition");
+        if (placement.in === "header" || placement.in === "jwt") {
+            place(placement.part);
+            headerName(placement.name);
+            if (placement.prefix !== undefined &&
+                (typeof placement.prefix !== "string" ||
+                    !/^[\x21-\x7e][\x20-\x7e]{0,31}$/.test(placement.prefix)))
+                throw new AuthError("invalid_definition");
+            if (placement.in === "jwt" &&
+                (typeof placement.audience !== "string" ||
+                    !/^[\x21-\x7e]{1,64}$/.test(placement.audience)))
+                throw new AuthError("invalid_definition");
+        }
+        else if (placement.in === "querySignature") {
+            place(placement.part);
+            headerName(placement.name);
+        }
+        else if (placement.in === "jsonPointer") {
+            place(placement.part);
+            if (typeof placement.pointer !== "string" ||
+                !/^(\/[A-Za-z0-9_.-]+)+$/.test(placement.pointer))
+                throw new AuthError("invalid_definition");
+        }
+        else if (placement.in === "query" || placement.in === "body") {
+            place(placement.part);
+            identifier(placement.name);
+        }
+        else if (placement.in === "path") {
+            place(placement.part);
+            if (placement.prefix !== undefined &&
+                (typeof placement.prefix !== "string" ||
+                    !/^[A-Za-z0-9._~-]{1,32}$/.test(placement.prefix)))
+                throw new AuthError("invalid_definition");
+        }
+        else if (placement.in === "basic") {
+            place(placement.username);
+            place(placement.password);
+        }
+        else
+            throw new AuthError("invalid_definition");
+    }
+    if (used.size !== parts.length)
+        throw new AuthError("invalid_definition");
+    for (const target of targets) {
+        const placed = placementsFor(auth, target);
+        const headers = injectedHeaders(auth, target);
+        const params = injectedParams(auth, target).map((name) => name.toLowerCase());
+        const pointers = injectedPointers(auth, target);
+        if (!placed.length ||
+            new Set(headers).size !== headers.length ||
+            new Set(params).size !== params.length ||
+            new Set(pointers).size !== pointers.length ||
+            placed.filter((placement) => placement.in === "path").length > 1)
+            throw new AuthError("invalid_definition");
+    }
+}
 function validateMethod(method) {
     const schema = method.schema;
     if (schema.type !== "object" ||
@@ -28,18 +143,23 @@ function validateMethod(method) {
         !schema.properties)
         throw new AuthError("invalid_definition");
     const auth = method.authentication;
-    const field = auth.kind === "oauth2" ? auth.grantField : auth.field;
-    identifier(field);
-    if (!Object.hasOwn(schema.properties, field))
-        throw new AuthError("invalid_definition");
-    let injected = "authorization";
-    if (auth.kind === "apiKey")
-        injected = headerName(auth.header);
+    if (auth.kind === "none") {
+        // Nothing is stored for a method that signs nothing.
+        if (Object.keys(schema.properties).length)
+            throw new AuthError("invalid_definition");
+    }
+    else {
+        identifier(auth.field);
+        if (!Object.hasOwn(schema.properties, auth.field))
+            throw new AuthError("invalid_definition");
+    }
+    if (auth.kind === "static")
+        validateStatic(auth, schema.properties[auth.field], Object.keys(method.targets ?? {}));
     else if (auth.kind === "oauth2") {
         identifier(auth.definition.id);
         identifier(auth.definition.provider);
         validateOAuth2ExchangePolicy(auth.definition.exchange);
-        if (!["refresh", "clientCredentials", "jwtBearer"].includes(auth.renewal) ||
+        if (!["refresh", "clientCredentials", "jwtBearer", "password"].includes(auth.renewal) ||
             !auth.definition[auth.renewal])
             throw new AuthError("invalid_definition");
         if (auth.rejectionStatus !== undefined &&
@@ -58,17 +178,31 @@ function validateMethod(method) {
             oauthEndpoint(auth.definition.authorization.url);
             providerParameters(auth.definition.authorization.parameters);
         }
+        const fields = Object.values(auth.definition.password?.fields ?? {});
+        for (const name of fields) {
+            identifier(name);
+            providerParameters({ [name]: "" });
+        }
+        if (new Set(fields).size !== fields.length)
+            throw new AuthError("invalid_definition");
         for (const operation of [
             "exchange",
             "refresh",
             "clientCredentials",
             "jwtBearer",
+            "password",
         ]) {
             const endpoint = auth.definition[operation];
             if (!endpoint)
                 continue;
             oauthEndpoint(endpoint.url);
             providerParameters(endpoint.parameters);
+            providerHeaders(endpoint.headers);
+            if ((endpoint.refreshTokenBearer !== undefined &&
+                typeof endpoint.refreshTokenBearer !== "boolean") ||
+                (endpoint.refreshTokenBearer &&
+                    ["client_id_basic", "client_secret_basic"].includes(endpoint.clientAuthentication)))
+                throw new AuthError("invalid_definition");
             if (![
                 "none",
                 "client_id",
@@ -81,25 +215,49 @@ function validateMethod(method) {
                 throw new AuthError("invalid_definition");
         }
     }
-    else if (auth.kind !== "bearer")
+    else if (auth.kind !== "none")
         throw new AuthError("invalid_definition");
     if (!Object.keys(method.targets).length)
         throw new AuthError("invalid_definition");
     for (const [name, target] of Object.entries(method.targets)) {
         identifier(name);
+        const injected = injectedHeaders(auth, name);
         targetBase(target);
         if (!Array.isArray(target.methods) ||
             !target.methods.length ||
             target.methods.some((m) => !HTTP_METHODS.includes(m)))
             throw new AuthError("invalid_definition");
-        if (target.allowedHeaders !== undefined &&
-            !Array.isArray(target.allowedHeaders))
+        if ((target.allowedHeaders !== undefined &&
+            !Array.isArray(target.allowedHeaders)) ||
+            (target.timeoutMs !== undefined &&
+                !bounded(target.timeoutMs, TARGET_TIMEOUT_LIMIT_MS)) ||
+            (target.maxResponseBytes !== undefined &&
+                !bounded(target.maxResponseBytes, TARGET_RESPONSE_LIMIT_BYTES)) ||
+            (target.encodedSlashes !== undefined &&
+                typeof target.encodedSlashes !== "boolean"))
             throw new AuthError("invalid_definition");
-        for (const name of target.allowedHeaders ?? []) {
-            const header = headerName(name);
-            if (header === injected || header === "authorization")
+        for (const allowed of target.allowedHeaders ?? []) {
+            const header = headerName(allowed);
+            if (injected.includes(header) || TRANSPORT_HEADERS.includes(header))
                 throw new AuthError("invalid_definition");
         }
+        // A socket URL carries only query parameters: no header, body or
+        // bearer can sign it, and nothing is sent through it by the transport.
+        if (target.socket !== undefined &&
+            (target.socket !== true ||
+                auth.kind === "oauth2" ||
+                target.allowedHeaders !== undefined ||
+                target.idempotency !== undefined ||
+                target.resumableUpload !== undefined ||
+                (auth.kind === "static" &&
+                    placementsFor(auth, name).some((placement) => placement.in !== "query"))))
+            throw new AuthError("invalid_definition");
+        // A path part is inserted into the request URL alone; a Destination on
+        // the same target would name a resource outside the signed position.
+        if (auth.kind === "static" &&
+            (target.methods.includes("COPY") || target.methods.includes("MOVE")) &&
+            placementsFor(auth, name).some((placement) => placement.in === "path"))
+            throw new AuthError("invalid_definition");
         if (target.resumableUpload !== undefined &&
             (typeof target.resumableUpload !== "boolean" ||
                 !target.methods.includes("PUT") ||
@@ -107,8 +265,8 @@ function validateMethod(method) {
             throw new AuthError("invalid_definition");
         if (target.idempotency) {
             const header = headerName(target.idempotency.header);
-            if (header === injected ||
-                header === "authorization" ||
+            if (injected.includes(header) ||
+                TRANSPORT_HEADERS.includes(header) ||
                 !target.idempotency.methods.length ||
                 target.idempotency.methods.some((m) => !target.methods.includes(m) || m === "GET" || m === "HEAD"))
                 throw new AuthError("invalid_definition");
@@ -116,16 +274,15 @@ function validateMethod(method) {
     }
     if (method.probe) {
         const probe = method.probe;
-        const target = Object.hasOwn(method.targets, probe.target)
-            ? method.targets[probe.target]
-            : undefined;
+        const target = targetOf(method, probe.target);
         if (!target ||
+            target.socket ||
             !["GET", "HEAD"].includes(probe.method) ||
             !target.methods.includes(probe.method) ||
             !probe.acceptedStatuses.length ||
             probe.acceptedStatuses.some((status) => !Number.isInteger(status) || status < 200 || status > 299))
             throw new AuthError("invalid_definition");
-        resourceUrl(target, probe.path);
+        refuseCredentialParams(resourceUrl(target, probe.path), injectedParams(auth, probe.target));
     }
 }
 /** No implicit defaults, provider inference, executable expressions, or replacement. */

package/dist/credentials/transport.d.ts

@@ -7,17 +7,58 @@ export interface AuthenticatedRequest {
     headers?: Record<string, string>;
     /** Buffered, copied before the first await. Streams and FormData are not accepted. */
     body?: string | Uint8Array;
+    /**
+     * COPY and MOVE only, and required there: where the resource goes, a
+     * path beneath the same target checked as `path` is, sent as the
+     * absolute Destination header. Callers never set that header.
+     */
+    destination?: string;
     /** Enables write replay only with a provider-declared idempotency contract. */
     idempotencyKey?: string;
     /** Disable even otherwise-safe replay for a particular request. */
     retry?: "never";
 }
+/** A socket target, and the path and query beneath it to connect to. */
+export interface SocketRequest {
+    target: string;
+    path: string;
+}
+/**
+ * Authenticated requests and probes for one connection, on behalf of one
+ * action call, signed by whoever holds its credentials. A host that keeps
+ * credentials outside the process running actions supplies one per call;
+ * the plugin never sees the token it is signed with.
+ */
+export interface CredentialBroker {
+    request(input: AuthenticatedRequest): Promise<Response>;
+    probe(): Promise<CredentialProbeResult>;
+    /**
+     * A URL the plugin may open for a socket target. The local signer
+     * returns the signed URL itself; a host keeping the credential returns
+     * a relay it controls. A broker without it serves no sockets.
+     */
+    socketUrl?(input: SocketRequest): Promise<string>;
+}
+/** The action call a host builds a broker for. `context` is the per-run
+ *  context the embedder passed to `execute()`: host authority, never
+ *  action input. */
+export interface CredentialBrokerCall {
+    plugin: string;
+    action: string;
+    context?: unknown;
+}
 export interface CredentialTransportOptions {
     /** Mandatory trusted transport: enforce DNS/IP egress policy for token AND API requests. */
     fetch: typeof globalThis.fetch;
+    /** Deadline for token requests and for targets that declare none. */
     timeoutMs?: number;
+    /** Response ceiling for targets that declare none. */
     maxResponseBytes?: number;
     maxRequestBytes?: number;
+    /** The longest deadline a target may declare. */
+    maxTargetTimeoutMs?: number;
+    /** The largest response ceiling a target may declare. */
+    maxTargetResponseBytes?: number;
 }
 /**
  * Trusted-host primitive, not a workspace sandbox. Callers authorize a binding on
@@ -29,10 +70,15 @@ export declare class CredentialTransport {
     constructor(registry: CredentialRegistry, options: CredentialTransportOptions);
     private read;
     private renew;
+    /** New tokens by the method's declared renewal, from what the binding supplies. */
+    private issue;
     request(selection: CredentialBinding, input: AuthenticatedRequest): Promise<Response>;
+    /**
+     * A socket target's URL, signed by its query placements, for a host's
+     * relay or the local signer to open. Nothing is sent.
+     */
+    socketUrl(selection: CredentialBinding, input: SocketRequest): Promise<string>;
     /** Only a declared read-only probe runs. Results never contain provider text or secrets. */
     probe(binding: CredentialBinding): Promise<CredentialProbeResult>;
-    /** Trusted-host compatibility primitive. Never expose raw tokens through a broker. */
-    accessToken(selection: CredentialBinding): Promise<string>;
     private authorize;
 }