runline 0.29.0 → 0.30.0

package/dist/credentials/http.js

@@ -0,0 +1,109 @@
+import { AuthError } from "../auth/errors.js";
+/** Internal send primitive. Callers validate destination policy before reaching it. */
+export async function sendResource(url, method, headers, body, options) {
+    const controller = new AbortController();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            controller.abort();
+            reject(new AuthError("transport_failed"));
+        }, options.timeoutMs);
+    });
+    const work = async () => {
+        const response = await options.fetch(url, {
+            method,
+            headers,
+            body: body === undefined ? undefined : Buffer.from(body),
+            redirect: "error",
+            credentials: "omit",
+            signal: controller.signal,
+        });
+        if (controller.signal.aborted ||
+            response.redirected ||
+            (response.status >= 300 &&
+                response.status < 400 &&
+                !(options.resumableUpload &&
+                    method === "PUT" &&
+                    headers.has("content-range") &&
+                    response.status === 308 &&
+                    !response.headers.has("location")))) {
+            void response.body?.cancel().catch(() => { });
+            throw new AuthError("transport_failed");
+        }
+        const reader = response.body?.getReader();
+        const cancel = () => {
+            void reader?.cancel().catch(() => { });
+        };
+        controller.signal.addEventListener("abort", cancel, { once: true });
+        const chunks = [];
+        let size = 0;
+        try {
+            if (reader)
+                while (true) {
+                    const { done, value } = await reader.read();
+                    if (done)
+                        break;
+                    size += value.byteLength;
+                    if (size > options.maxResponseBytes) {
+                        void reader.cancel().catch(() => { });
+                        throw new AuthError("response_too_large");
+                    }
+                    if (value.byteLength)
+                        chunks.push(value);
+                }
+        }
+        finally {
+            controller.signal.removeEventListener("abort", cancel);
+            reader?.releaseLock();
+        }
+        const responseHeaders = new Headers(response.headers);
+        // Fetch supplies decoded bytes, not the original wire representation.
+        responseHeaders.delete("content-encoding");
+        responseHeaders.delete("content-length");
+        responseHeaders.delete("set-cookie");
+        return new Response(method === "HEAD" || [204, 205, 304].includes(response.status)
+            ? null
+            : Buffer.concat(chunks), { status: response.status, headers: responseHeaders });
+    };
+    try {
+        return await Promise.race([work(), timeout]);
+    }
+    catch (error) {
+        if (error instanceof AuthError && error.code === "response_too_large")
+            throw error;
+        throw new AuthError("transport_failed");
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Fetch a provider-issued preauthenticated URL without bearer tokens or cookies.
+ * Hosts approve exact origins and enforce DNS/IP egress through their fetch hook.
+ * The signed URL is itself secret: errors never include it. No redirects or retries.
+ */
+export async function downloadResource(value, options) {
+    let url;
+    try {
+        url = new URL(value);
+        if (url.protocol !== "https:" ||
+            url.username ||
+            url.password ||
+            url.hash ||
+            !options.allowedOrigins.includes(url.origin))
+            throw new Error();
+    }
+    catch {
+        throw new AuthError("request_not_allowed");
+    }
+    const maxResponseBytes = options.maxResponseBytes ?? 64 * 1024 * 1024;
+    if (!Number.isSafeInteger(maxResponseBytes) ||
+        maxResponseBytes <= 0 ||
+        maxResponseBytes > 64 * 1024 * 1024)
+        throw new AuthError("invalid_definition");
+    return sendResource(url.toString(), "GET", new Headers(), undefined, {
+        fetch: options.fetch,
+        timeoutMs: 20_000,
+        maxResponseBytes,
+    });
+}

package/dist/credentials/policy.d.ts

@@ -0,0 +1,5 @@
+import type { CredentialTarget, HttpMethod } from "./types.js";
+export declare const HTTP_METHODS: readonly HttpMethod[];
+export declare function headerName(name: string): string;
+export declare function targetBase(target: CredentialTarget): URL;
+export declare function resourceUrl(target: CredentialTarget, path: string): URL;

package/dist/credentials/policy.js

@@ -0,0 +1,92 @@
+import { AuthError } from "../auth/errors.js";
+export const HTTP_METHODS = [
+    "GET",
+    "HEAD",
+    "POST",
+    "PUT",
+    "PATCH",
+    "DELETE",
+];
+export function headerName(name) {
+    if (typeof name !== "string" || !/^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/.test(name))
+        throw new AuthError("invalid_definition");
+    const lower = name.toLowerCase();
+    if ([
+        "host",
+        "cookie",
+        "set-cookie",
+        "content-length",
+        "connection",
+        "transfer-encoding",
+        "proxy-authorization",
+        "proxy-connection",
+        "upgrade",
+        "te",
+        "trailer",
+    ].includes(lower) ||
+        lower.startsWith("sec-") ||
+        lower.startsWith("proxy-"))
+        throw new AuthError("invalid_definition");
+    return lower;
+}
+export function targetBase(target) {
+    try {
+        const url = new URL(target.baseUrl);
+        if (url.protocol !== "https:" ||
+            url.username ||
+            url.password ||
+            url.search ||
+            url.hash ||
+            !url.pathname.endsWith("/"))
+            throw new Error();
+        safePath(url.pathname);
+        // Reject normalization rather than silently widening a configured boundary.
+        if (url.href !== target.baseUrl)
+            throw new Error();
+        return url;
+    }
+    catch {
+        throw new AuthError("invalid_definition");
+    }
+}
+function controls(value) {
+    return [...value].some((char) => char.charCodeAt(0) <= 32 || char.charCodeAt(0) === 127);
+}
+function safePath(path) {
+    // 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) ||
+            [...decoded].some((char) => char.charCodeAt(0) < 32 || char.charCodeAt(0) === 127))
+            throw new Error();
+    }
+}
+export function resourceUrl(target, path) {
+    const base = targetBase(target);
+    try {
+        if (typeof path !== "string" ||
+            path.startsWith("/") ||
+            path.includes("#") ||
+            /^[a-z][a-z0-9+.-]*:/i.test(path) ||
+            path.includes("\\") ||
+            controls(path))
+            throw new Error();
+        safePath(path.split("?")[0]);
+        const url = new URL(path, base);
+        if (url.origin !== base.origin ||
+            !url.pathname.startsWith(base.pathname) ||
+            url.username ||
+            url.password ||
+            url.hash)
+            throw new Error();
+        return url;
+    }
+    catch {
+        throw new AuthError("request_not_allowed");
+    }
+}

package/dist/credentials/registry.d.ts

@@ -0,0 +1,31 @@
+import * as t from "typebox";
+import type { CredentialMethod, CredentialType } from "./types.js";
+/** Normalized grant storage; application registration remains host-owned. */
+export declare const OAuthTokensSchema: t.TObject<{
+    accessToken: t.TString;
+    refreshToken: t.TOptional<t.TString>;
+    expiresAt: t.TOptional<t.TInteger>;
+    scope: t.TOptional<t.TString>;
+    tokenType: t.TOptional<t.TString>;
+    metadata: t.TOptional<t.TRecord<"^.*$", t.TString>>;
+}>;
+export declare const OAuthGrantSchema: t.TObject<{
+    tokens: t.TObject<{
+        accessToken: t.TOptional<t.TString>;
+        refreshToken: t.TOptional<t.TString>;
+        expiresAt: t.TOptional<t.TInteger>;
+        scope: t.TOptional<t.TString>;
+        tokenType: t.TOptional<t.TString>;
+        metadata: t.TOptional<t.TRecord<"^.*$", t.TString>>;
+    }>;
+    revision: t.TString;
+}>;
+/** No implicit defaults, provider inference, executable expressions, or replacement. */
+export declare class CredentialRegistry {
+    private readonly types;
+    register(definition: CredentialType): void;
+    select(type: string, method: string): CredentialMethod;
+    list(): CredentialType[];
+}
+/** Validation never formats schema errors containing credential values. */
+export declare function validateCredential(method: CredentialMethod, config: unknown): asserts config is Record<string, unknown>;

package/dist/credentials/registry.js

@@ -0,0 +1,171 @@
+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";
+/** Normalized grant storage; application registration remains host-owned. */
+export const OAuthTokensSchema = t.Object({
+    accessToken: t.String({ minLength: 1 }),
+    refreshToken: t.Optional(t.String({ minLength: 1 })),
+    expiresAt: t.Optional(t.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER })),
+    scope: t.Optional(t.String()),
+    tokenType: t.Optional(t.String({ minLength: 1 })),
+    metadata: t.Optional(t.Record(t.String(), t.String())),
+}, { additionalProperties: false });
+export const OAuthGrantSchema = t.Object({
+    tokens: t.Partial(OAuthTokensSchema),
+    revision: t.String({ minLength: 1 }),
+}, { additionalProperties: false });
+function identifier(value) {
+    if (typeof value !== "string" || !/^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(value))
+        throw new AuthError("invalid_definition");
+}
+function validateMethod(method) {
+    const schema = method.schema;
+    if (schema.type !== "object" ||
+        schema.additionalProperties !== false ||
+        !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);
+    else if (auth.kind === "oauth2") {
+        identifier(auth.definition.id);
+        identifier(auth.definition.provider);
+        validateOAuth2ExchangePolicy(auth.definition.exchange);
+        if (!["refresh", "clientCredentials", "jwtBearer"].includes(auth.renewal) ||
+            !auth.definition[auth.renewal])
+            throw new AuthError("invalid_definition");
+        if (auth.rejectionStatus !== undefined &&
+            ![401, 403].includes(auth.rejectionStatus))
+            throw new AuthError("invalid_definition");
+        if (auth.scopes &&
+            (!Array.isArray(auth.scopes) ||
+                auth.scopes.some((scope) => typeof scope !== "string" || !scope)))
+            throw new AuthError("invalid_definition");
+        if (auth.renewal === "jwtBearer" &&
+            (!auth.scopes?.length ||
+                auth.definition.jwtBearer?.clientAuthentication !== "none" ||
+                auth.definition.jwtBearer?.grantType !== undefined))
+            throw new AuthError("invalid_definition");
+        if (auth.definition.authorization) {
+            oauthEndpoint(auth.definition.authorization.url);
+            providerParameters(auth.definition.authorization.parameters);
+        }
+        for (const operation of [
+            "exchange",
+            "refresh",
+            "clientCredentials",
+            "jwtBearer",
+        ]) {
+            const endpoint = auth.definition[operation];
+            if (!endpoint)
+                continue;
+            oauthEndpoint(endpoint.url);
+            providerParameters(endpoint.parameters);
+            if (![
+                "none",
+                "client_id",
+                "client_id_basic",
+                "client_secret_basic",
+                "client_secret_post",
+            ].includes(endpoint.clientAuthentication) ||
+                (endpoint.encoding !== undefined &&
+                    !["form", "json"].includes(endpoint.encoding)))
+                throw new AuthError("invalid_definition");
+        }
+    }
+    else if (auth.kind !== "bearer")
+        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);
+        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))
+            throw new AuthError("invalid_definition");
+        for (const name of target.allowedHeaders ?? []) {
+            const header = headerName(name);
+            if (header === injected || header === "authorization")
+                throw new AuthError("invalid_definition");
+        }
+        if (target.resumableUpload !== undefined &&
+            (typeof target.resumableUpload !== "boolean" ||
+                !target.methods.includes("PUT") ||
+                !target.allowedHeaders?.some((name) => name.toLowerCase() === "content-range")))
+            throw new AuthError("invalid_definition");
+        if (target.idempotency) {
+            const header = headerName(target.idempotency.header);
+            if (header === injected ||
+                header === "authorization" ||
+                !target.idempotency.methods.length ||
+                target.idempotency.methods.some((m) => !target.methods.includes(m) || m === "GET" || m === "HEAD"))
+                throw new AuthError("invalid_definition");
+        }
+    }
+    if (method.probe) {
+        const probe = method.probe;
+        const target = Object.hasOwn(method.targets, probe.target)
+            ? method.targets[probe.target]
+            : undefined;
+        if (!target ||
+            !["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);
+    }
+}
+/** No implicit defaults, provider inference, executable expressions, or replacement. */
+export class CredentialRegistry {
+    types = new Map();
+    register(definition) {
+        let copy;
+        try {
+            copy = structuredClone(definition);
+            identifier(copy.id);
+            if (this.types.has(copy.id) || !Object.keys(copy.methods).length)
+                throw new Error();
+            for (const [name, method] of Object.entries(copy.methods)) {
+                identifier(name);
+                validateMethod(method);
+            }
+        }
+        catch {
+            throw new AuthError("invalid_definition");
+        }
+        this.types.set(copy.id, copy);
+    }
+    select(type, method) {
+        const definition = this.types.get(type);
+        if (!definition || !Object.hasOwn(definition.methods, method))
+            throw new AuthError("invalid_definition");
+        return structuredClone(definition.methods[method]);
+    }
+    list() {
+        return structuredClone([...this.types.values()]);
+    }
+}
+/** Validation never formats schema errors containing credential values. */
+export function validateCredential(method, config) {
+    try {
+        if (Check(method.schema, config))
+            return;
+    }
+    catch {
+        throw new AuthError("invalid_definition");
+    }
+    throw new AuthError("invalid_credentials");
+}

package/dist/credentials/transport.d.ts

@@ -0,0 +1,38 @@
+import { type CredentialRegistry } from "./registry.js";
+import type { CredentialBinding, CredentialProbeResult, HttpMethod } from "./types.js";
+export interface AuthenticatedRequest {
+    target: string;
+    path: string;
+    method?: HttpMethod;
+    headers?: Record<string, string>;
+    /** Buffered, copied before the first await. Streams and FormData are not accepted. */
+    body?: string | Uint8Array;
+    /** Enables write replay only with a provider-declared idempotency contract. */
+    idempotencyKey?: string;
+    /** Disable even otherwise-safe replay for a particular request. */
+    retry?: "never";
+}
+export interface CredentialTransportOptions {
+    /** Mandatory trusted transport: enforce DNS/IP egress policy for token AND API requests. */
+    fetch: typeof globalThis.fetch;
+    timeoutMs?: number;
+    maxResponseBytes?: number;
+    maxRequestBytes?: number;
+}
+/**
+ * Trusted-host primitive, not a workspace sandbox. Callers authorize a binding on
+ * every invocation. Handles own lifecycle fencing; no second lock or token cache.
+ */
+export declare class CredentialTransport {
+    private readonly registry;
+    private readonly options;
+    constructor(registry: CredentialRegistry, options: CredentialTransportOptions);
+    private read;
+    private renew;
+    request(selection: CredentialBinding, input: AuthenticatedRequest): Promise<Response>;
+    /** 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;
+}