runline 0.33.0 → 0.35.0

package/dist/auth/oauth2.d.ts

@@ -1,4 +1,4 @@
-import type { OAuth2Definition, OAuthApplication, OAuthAuthorizationOptions, OAuthCodeOptions, OAuthJwtIdentity, OAuthRuntimeOptions, OAuthTokens } from "./types.js";
+import type { OAuth2Definition, OAuthApplication, OAuthAuthorizationOptions, OAuthCodeOptions, OAuthJwtIdentity, OAuthResourceOwner, OAuthRuntimeOptions, OAuthTokens } from "./types.js";
 /** Shared by definition registration and both setup primitives; no truthy coercion. */
 export declare function validateOAuth2ExchangePolicy(endpoint: OAuth2Definition["exchange"]): void;
 /** Redirect registration and state custody belong to the host's setup lifecycle. */
@@ -15,6 +15,12 @@ export declare function acquireOAuth2JwtToken(definition: OAuth2Definition, inpu
     identity: OAuthJwtIdentity;
     scopes: string[];
 }, options?: OAuthRuntimeOptions): Promise<OAuthTokens>;
+/** Resource-owner password grant, the owner's fields under the endpoint's own names. */
+export declare function acquireOAuth2PasswordToken(definition: OAuth2Definition, input: {
+    owner: OAuthResourceOwner;
+    application?: OAuthApplication;
+    scopes?: string[];
+}, options?: OAuthRuntimeOptions): Promise<OAuthTokens>;
 export declare function acquireOAuth2ClientToken(definition: OAuth2Definition, input: {
     application: OAuthApplication;
     scopes?: string[];

package/dist/auth/oauth2.js

@@ -52,6 +52,7 @@ async function operate(definition, operation, application, parameters, options)
             refresh: "refresh_token",
             clientCredentials: "client_credentials",
             jwtBearer: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+            password: "password",
         };
         const tokens = await requestOAuth2Token(configured, { ...parameters, grant_type: standard[operation] }, application, options);
         notifyObserver(options.onEvent, { ...event, outcome: "issued" });
@@ -149,6 +150,15 @@ export async function acquireOAuth2JwtToken(definition, input, options = {}) {
     }
     return operate(definition, "jwtBearer", undefined, { assertion }, { ...options, now: () => now });
 }
+/** Resource-owner password grant, the owner's fields under the endpoint's own names. */
+export async function acquireOAuth2PasswordToken(definition, input, options = {}) {
+    const names = definition.password?.fields ?? {};
+    return operate(definition, "password", input.application, {
+        [names.username ?? "username"]: required(input.owner.username),
+        [names.password ?? "password"]: required(input.owner.password),
+        ...(input.scopes?.length ? { scope: input.scopes.join(" ") } : {}),
+    }, options);
+}
 export async function acquireOAuth2ClientToken(definition, input, options = {}) {
     return operate(definition, "clientCredentials", input.application, input.scopes?.length ? { scope: input.scopes.join(" ") } : {}, options);
 }

package/dist/auth/token.d.ts

@@ -1,5 +1,6 @@
 import type { OAuth2TokenEndpoint, OAuthApplication, OAuthRuntimeOptions, OAuthTokens } from "./types.js";
 export declare function providerParameters(parameters?: Record<string, string>): Record<string, string>;
+export declare function providerHeaders(headers?: Record<string, string>): Record<string, string>;
 export declare function oauthEndpoint(value: string): URL;
 /** Only normalized grant fields survive decoding; arbitrary response metadata is discarded. */
 export declare function decodeOAuthTokens(input: unknown, mapping?: OAuth2TokenEndpoint["response"], now?: number): OAuthTokens;

package/dist/auth/token.js

@@ -1,3 +1,4 @@
+import { headerName } from "../credentials/policy.js";
 import { AuthError } from "./errors.js";
 const MAX_RESPONSE_BYTES = 1024 * 1024;
 const protectedParameters = new Set([
@@ -22,6 +23,15 @@ export function providerParameters(parameters = {}) {
     }
     return { ...parameters };
 }
+/** Headers a token request owns; provider headers cannot replace them. */
+const protocolHeaders = new Set(["authorization", "accept", "content-type"]);
+export function providerHeaders(headers = {}) {
+    for (const [name, value] of Object.entries(headers)) {
+        if (protocolHeaders.has(headerName(name)) || typeof value !== "string")
+            throw new AuthError("invalid_definition");
+    }
+    return { ...headers };
+}
 export function oauthEndpoint(value) {
     try {
         const url = new URL(value);
@@ -148,7 +158,10 @@ export async function requestOAuth2Token(endpoint, parameters, application, opti
             throw new AuthError("invalid_definition");
         fields.grant_type = endpoint.grantType;
     }
-    const headers = { Accept: "application/json" };
+    const headers = {
+        ...providerHeaders(endpoint.headers),
+        Accept: "application/json",
+    };
     if (endpoint.clientAuthentication !== "none") {
         if (!application ||
             typeof application.clientId !== "string" ||
@@ -180,6 +193,11 @@ export async function requestOAuth2Token(endpoint, parameters, application, opti
                 throw new AuthError("invalid_definition");
         }
     }
+    if (endpoint.refreshTokenBearer) {
+        if (headers.Authorization || !fields.refresh_token)
+            throw new AuthError("invalid_definition");
+        headers.Authorization = `Bearer ${fields.refresh_token}`;
+    }
     if (endpoint.encoding !== undefined &&
         endpoint.encoding !== "form" &&
         endpoint.encoding !== "json") {

package/dist/auth/types.d.ts

@@ -14,6 +14,14 @@ export interface OAuth2Definition {
     refresh?: OAuth2TokenEndpoint;
     clientCredentials?: OAuth2TokenEndpoint;
     jwtBearer?: OAuth2TokenEndpoint;
+    /** Resource-owner password grant (RFC 6749 §4.3). */
+    password?: OAuth2TokenEndpoint & {
+        /** The provider's names for the owner's fields; `username` and `password` when absent. */
+        fields?: {
+            username?: string;
+            password?: string;
+        };
+    };
 }
 /** Each operation can use a different endpoint, encoding, and client authentication. */
 export interface OAuth2TokenEndpoint {
@@ -25,6 +33,14 @@ export interface OAuth2TokenEndpoint {
     grantType?: string | null;
     /** Provider-specific fields; cannot replace protocol-owned parameters. */
     parameters?: Record<string, string>;
+    /**
+     * Fixed provider headers (a mobile app's client version, a device id
+     * from public config); cannot claim Authorization, Accept or
+     * Content-Type.
+     */
+    headers?: Record<string, string>;
+    /** Also send the refresh token as the request's bearer, as some mobile APIs require. */
+    refreshTokenBearer?: boolean;
     response?: {
         /** Path to a token object inside a provider envelope. No expression evaluation. */
         path?: string[];
@@ -52,13 +68,18 @@ export interface OAuthTokens {
     /** Only fields explicitly selected by the definition's response mapping. */
     metadata?: Record<string, string>;
 }
+/** Host-selected resource owner for a password grant. Never accepted from resource/action input. */
+export interface OAuthResourceOwner {
+    username: string;
+    password: string;
+}
 /** Host-selected signing identity. Never accepted from resource/action input. */
 export interface OAuthJwtIdentity {
     issuer: string;
     privateKey: string;
     subject?: string;
 }
-export type OAuthOperation = "exchange" | "refresh" | "clientCredentials" | "jwtBearer";
+export type OAuthOperation = "exchange" | "refresh" | "clientCredentials" | "jwtBearer" | "password";
 /** Protocol events report issuance, never durability. They contain no credential data. */
 export interface OAuthEvent {
     definition: string;

package/dist/core/engine.d.ts

@@ -1,5 +1,6 @@
 import type { RunlineConfig } from "../config/types.js";
 import type { ConnectionProvider } from "../connections/types.js";
+import type { CredentialBroker, CredentialBrokerCall } from "../credentials/transport.js";
 import type { PluginRegistry } from "../plugin/registry.js";
 export interface ExecuteResult {
     result: unknown;
@@ -34,6 +35,12 @@ export interface ActionInvocation {
 export interface EngineHooks {
     /** Host-owned resolution and persistence. Defaults to process-local memory. */
     connectionProvider?: ConnectionProvider;
+    /**
+     * Host-signed requests: built per action call of a plugin that declares
+     * its credential, and handed to the action as `ctx.credentials`. Absent,
+     * plugins sign with their own connection.
+     */
+    credentialBroker?: (call: CredentialBrokerCall) => CredentialBroker;
     /**
      * Observer for every action invocation. Must not throw — but if it
      * does, the engine swallows it: observability never breaks a run.

package/dist/core/engine.js

@@ -2,7 +2,7 @@ import { randomUUID } from "node:crypto";
 import { createRequire } from "node:module";
 import { Worker } from "node:worker_threads";
 import { MemoryConnectionProvider } from "../connections/memory.js";
-import { formatValidationError, helpInputs, isTypedInputSchema, normalizeActionInput, validateTypedInput, } from "../plugin/schema.js";
+import { dropUndefined, formatValidationError, helpInputs, isTypedInputSchema, normalizeActionInput, validateTypedInput, } from "../plugin/schema.js";
 import { notifyObserver } from "../utils/observer.js";
 /**
  * How many bodies one worker may run before it is retired.
@@ -363,6 +363,15 @@ export class ExecutionEngine {
         const ctx = {
             connection,
             context,
+            ...(this.hooks.credentialBroker && plugin.credential
+                ? {
+                    credentials: this.hooks.credentialBroker({
+                        plugin: plugin.name,
+                        action: action.name,
+                        context,
+                    }),
+                }
+                : {}),
             log: {
                 info: (msg) => console.log(`[${plugin.name}] ${msg}`),
                 warn: (msg) => console.warn(`[${plugin.name}] ${msg}`),
@@ -600,6 +609,14 @@ const { FerroSearch } = require(${JSON.stringify(ferrosearchPath)});
 // The host's own validator, for actions.check on typed schemas.
 const { Check: __schemaCheck, Errors: __schemaErrors } = require(${JSON.stringify(typeboxValuePath)});
 
+// The host's own normalizeActionInput, by its source, so a check sees the
+// arguments exactly as validation and execute do. The closure keeps the
+// helper names it calls out of the scope plugin globals are declared in.
+const __normalizeActionInput = (() => {
+${dropUndefined.toString()}
+return ${normalizeActionInput.toString()};
+})();
+
 const __help = ${JSON.stringify(helpData)};
 
 const __makeProxy = (path = []) => new Proxy(() => undefined, {
@@ -774,14 +791,10 @@ const __actionsApi = {
       return { ok: false, error: 'Unknown action: ' + path, suggestions: near };
     }
     const signature = __formatSignature(hit.plugin, hit.entry);
-    if (hit.entry.schema) {
-      // Mirror the host's normalizeActionInput: a check with no args is
-      // a call with an empty argument set; anything else — null, a
-      // scalar — is validated as given, exactly as execute would.
-      return __checkTyped(hit.entry, args === undefined ? {} : args, signature);
-    }
+    const input = __normalizeActionInput(args);
+    if (hit.entry.schema) return __checkTyped(hit.entry, input, signature);
     const inputs = hit.entry.inputs || {};
-    const provided = args && typeof args === 'object' ? args : {};
+    const provided = input && typeof input === 'object' ? input : {};
     const missing = [];
     const unknown = [];
     const typeErrors = [];

package/dist/credentials/policy.d.ts

@@ -1,5 +1,57 @@
-import type { CredentialTarget, HttpMethod } from "./types.js";
+import type { CredentialAuthentication, CredentialMethod, CredentialTarget, HttpMethod, SecretPlacement } from "./types.js";
 export declare const HTTP_METHODS: readonly HttpMethod[];
+/**
+ * Headers only the transport sets, whatever the method signs with: the
+ * credential in Authorization, and a COPY or MOVE Destination held to its
+ * target. No caller, allowed header or idempotency header may claim them.
+ */
+export declare const TRANSPORT_HEADERS: readonly string[];
+/** The most any target may declare, and any host may allow, per request. */
+export declare const TARGET_TIMEOUT_LIMIT_MS: number;
+export declare const TARGET_RESPONSE_LIMIT_BYTES: number;
+/** A positive integer no larger than `limit`. */
+export declare function bounded(value: unknown, limit: number): boolean;
 export declare function headerName(name: string): string;
+/** A method's target by name, own properties only. */
+export declare function targetOf(method: CredentialMethod, name: string): CredentialTarget | undefined;
 export declare function targetBase(target: CredentialTarget): URL;
+/** The static placements that sign requests to `target`. */
+export declare function placementsFor(auth: Extract<CredentialAuthentication, {
+    kind: "static";
+}>, target: string): SecretPlacement[];
+/** Headers a method's authentication sets on `target`, lowercased; callers never set them. */
+export declare function injectedHeaders(auth: CredentialAuthentication, target: string): string[];
+/**
+ * Query parameters a method's authentication sets on `target`, a body
+ * part's included (it reaches the query when a request has no body);
+ * callers never set them.
+ */
+export declare function injectedParams(auth: CredentialAuthentication, target: string): string[];
+/** Body fields a method's authentication sets on `target`; callers never set them. */
+export declare function injectedFields(auth: CredentialAuthentication, target: string): string[];
+/** JSON pointers a method's authentication fills on `target`; callers leave null at each. */
+export declare function injectedPointers(auth: CredentialAuthentication, target: string): string[];
+/**
+ * The container and key a JSON pointer names in a parsed JSON value, or
+ * undefined when any step does not resolve: a missing key, an array index
+ * out of range, or a scalar in the way.
+ */
+export declare function pointerSlot(value: unknown, pointer: string): {
+    holder: Record<string, unknown>;
+    key: string;
+} | undefined;
+/** A request body the transport can add a field to, by its Content-Type. */
+export declare function bodyFormat(headers: Headers): "json" | "form" | undefined;
+/**
+ * The top-level field names of a JSON-object or form body. Anything else —
+ * no recognized Content-Type, malformed JSON, a JSON value that is not an
+ * object — cannot carry a body part and is refused.
+ */
+export declare function bodyFields(headers: Headers, body: Uint8Array): string[];
+/**
+ * Query parameters only the transport may set: common credential names,
+ * and the method's own placed query parameters. Compared
+ * case-insensitively, since providers differ in how they match names.
+ */
+export declare function refuseCredentialParams(url: URL, declared: readonly string[]): void;
 export declare function resourceUrl(target: CredentialTarget, path: string): URL;

package/dist/credentials/policy.js

@@ -6,7 +6,28 @@ export const HTTP_METHODS = [
     "PUT",
     "PATCH",
     "DELETE",
+    "MKCOL",
+    "COPY",
+    "MOVE",
 ];
+/**
+ * Headers only the transport sets, whatever the method signs with: the
+ * credential in Authorization, and a COPY or MOVE Destination held to its
+ * target. No caller, allowed header or idempotency header may claim them.
+ */
+export const TRANSPORT_HEADERS = [
+    "authorization",
+    "destination",
+];
+/** The most any target may declare, and any host may allow, per request. */
+export const TARGET_TIMEOUT_LIMIT_MS = 60 * 60_000;
+export const TARGET_RESPONSE_LIMIT_BYTES = 1024 * 1024 * 1024;
+/** A positive integer no larger than `limit`. */
+export function bounded(value, limit) {
+    return (Number.isSafeInteger(value) &&
+        value > 0 &&
+        value <= limit);
+}
 export function headerName(name) {
     if (typeof name !== "string" || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name))
         throw new AuthError("invalid_definition");
@@ -29,10 +50,14 @@ export function headerName(name) {
         throw new AuthError("invalid_definition");
     return lower;
 }
+/** A method's target by name, own properties only. */
+export function targetOf(method, name) {
+    return Object.hasOwn(method.targets, name) ? method.targets[name] : undefined;
+}
 export function targetBase(target) {
     try {
         const url = new URL(target.baseUrl);
-        if (url.protocol !== "https:" ||
+        if (url.protocol !== (target.socket === true ? "wss:" : "https:") ||
             url.username ||
             url.password ||
             url.search ||
@@ -52,20 +77,135 @@ export function targetBase(target) {
 function controls(value) {
     return [...value].some((char) => char.charCodeAt(0) <= 32 || char.charCodeAt(0) === 127);
 }
-function safePath(path) {
+function safePath(path, encodedSlashes = false) {
     // Reject ambiguous encodings and segments before URL normalization. Query values
     // are separate data; encoded URLs in query parameters are not destinations.
     if (/[\\\s]/.test(path) || controls(path))
         throw new Error();
     for (const segment of path.split("/")) {
         const decoded = decodeURIComponent(segment);
-        if (decoded === "." ||
-            decoded === ".." ||
-            /[%/\\]/.test(decoded) ||
+        // An opted-in target's segment may hold encoded slashes, but no piece
+        // of it may be empty or a dot segment once decoded.
+        const pieces = encodedSlashes ? decoded.split("/") : [decoded];
+        if ((pieces.length > 1 && pieces.some((piece) => !piece)) ||
+            pieces.some((piece) => piece === "." || piece === "..") ||
+            (encodedSlashes ? /[%\\]/ : /[%/\\]/).test(decoded) ||
             [...decoded].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127))
             throw new Error();
     }
 }
+/** The static placements that sign requests to `target`. */
+export function placementsFor(auth, target) {
+    return auth.placements.filter((placement) => !placement.targets || placement.targets.includes(target));
+}
+/** Headers a method's authentication sets on `target`, lowercased; callers never set them. */
+export function injectedHeaders(auth, target) {
+    if (auth.kind === "none")
+        return [];
+    if (auth.kind === "oauth2")
+        return ["authorization"];
+    return placementsFor(auth, target).flatMap((placement) => placement.in === "header" ||
+        placement.in === "jwt" ||
+        placement.in === "querySignature"
+        ? [headerName(placement.name)]
+        : placement.in === "basic"
+            ? ["authorization"]
+            : []);
+}
+/**
+ * Query parameters a method's authentication sets on `target`, a body
+ * part's included (it reaches the query when a request has no body);
+ * callers never set them.
+ */
+export function injectedParams(auth, target) {
+    if (auth.kind !== "static")
+        return [];
+    return placementsFor(auth, target).flatMap((placement) => placement.in === "query" || placement.in === "body" ? [placement.name] : []);
+}
+/** Body fields a method's authentication sets on `target`; callers never set them. */
+export function injectedFields(auth, target) {
+    if (auth.kind !== "static")
+        return [];
+    return placementsFor(auth, target).flatMap((placement) => placement.in === "body" ? [placement.name] : []);
+}
+/** JSON pointers a method's authentication fills on `target`; callers leave null at each. */
+export function injectedPointers(auth, target) {
+    if (auth.kind !== "static")
+        return [];
+    return placementsFor(auth, target).flatMap((placement) => placement.in === "jsonPointer" ? [placement.pointer] : []);
+}
+/**
+ * The container and key a JSON pointer names in a parsed JSON value, or
+ * undefined when any step does not resolve: a missing key, an array index
+ * out of range, or a scalar in the way.
+ */
+export function pointerSlot(value, pointer) {
+    const steps = pointer.slice(1).split("/");
+    let current = value;
+    for (const [index, step] of steps.entries()) {
+        if (!current ||
+            typeof current !== "object" ||
+            (Array.isArray(current) &&
+                (!/^\d+$/.test(step) || Number(step) >= current.length)) ||
+            !Object.hasOwn(current, step))
+            return undefined;
+        const holder = current;
+        if (index === steps.length - 1)
+            return { holder, key: step };
+        current = holder[step];
+    }
+    return undefined;
+}
+/** A request body the transport can add a field to, by its Content-Type. */
+export function bodyFormat(headers) {
+    const type = headers.get("content-type")?.split(";")[0].trim().toLowerCase();
+    return type === "application/json"
+        ? "json"
+        : type === "application/x-www-form-urlencoded"
+            ? "form"
+            : undefined;
+}
+/**
+ * The top-level field names of a JSON-object or form body. Anything else —
+ * no recognized Content-Type, malformed JSON, a JSON value that is not an
+ * object — cannot carry a body part and is refused.
+ */
+export function bodyFields(headers, body) {
+    const text = Buffer.from(body).toString();
+    const format = bodyFormat(headers);
+    if (format === "form")
+        return [...new URLSearchParams(text).keys()];
+    if (format === "json") {
+        let value;
+        try {
+            value = JSON.parse(text);
+        }
+        catch {
+            throw new AuthError("request_not_allowed");
+        }
+        if (value && typeof value === "object" && !Array.isArray(value))
+            return Object.keys(value);
+    }
+    throw new AuthError("request_not_allowed");
+}
+/**
+ * Query parameters only the transport may set: common credential names,
+ * and the method's own placed query parameters. Compared
+ * case-insensitively, since providers differ in how they match names.
+ */
+export function refuseCredentialParams(url, declared) {
+    const reserved = [
+        "access_token",
+        "refresh_token",
+        "client_secret",
+        "api_key",
+        "authorization",
+        ...declared.map((name) => name.toLowerCase()),
+    ];
+    for (const name of url.searchParams.keys())
+        if (reserved.includes(name.toLowerCase()))
+            throw new AuthError("request_not_allowed");
+}
 export function resourceUrl(target, path) {
     const base = targetBase(target);
     try {
@@ -76,7 +216,7 @@ export function resourceUrl(target, path) {
             path.includes("\\") ||
             controls(path))
             throw new Error();
-        safePath(path.split("?")[0]);
+        safePath(path.split("?")[0], target.encodedSlashes === true);
         const url = new URL(path, base);
         if (url.origin !== base.origin ||
             !url.pathname.startsWith(base.pathname) ||

package/dist/credentials/registry.d.ts

@@ -9,6 +9,15 @@ export declare const OAuthTokensSchema: t.TObject<{
     tokenType: t.TOptional<t.TString>;
     metadata: t.TOptional<t.TRecord<"^.*$", t.TString>>;
 }>;
+/**
+ * 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 declare function staticSecretSchema(parts: readonly string[], optional?: readonly string[]): t.TObject<{
+    [k: string]: t.TString;
+}>;
 export declare const OAuthGrantSchema: t.TObject<{
     tokens: t.TObject<{
         accessToken: t.TOptional<t.TString>;