runline 0.38.0 → 0.39.0

package/dist/credentials/broker.js

@@ -78,11 +78,26 @@ function joinedPart(current, source) {
     }
     return joined;
 }
+/** An issued credential as stored flat: stamped with the authority it was issued under. */
+function stamped(issued, expected) {
+    return { ...issued, binding: expected };
+}
+/**
+ * A flat issued credential without its stamp, when it was issued under
+ * `expected`; undefined for one issued under any other selection, which is
+ * never used.
+ */
+function issuedUnder(stored, expected) {
+    if (!stored || typeof stored !== "object")
+        return undefined;
+    const { binding, ...issued } = stored;
+    return binding === expected ? issued : undefined;
+}
 /**
  * How an issued credential is stored flat: an OAuth grant as its token
- * fields, a role session as `awsSession`, each stamped with the authority
- * (`expected`) it was issued under. Only those two are ever renewed and
- * written back.
+ * fields, a role session as `awsSession`, a cookie jar as `cookieSession`,
+ * each stamped with the authority (`expected`) it was issued under. Only
+ * those three are ever renewed and written back.
  */
 function writeBack(auth, expected) {
     if (auth.kind === "awsSigV4" && auth.assumeRole) {
@@ -91,9 +106,16 @@ function writeBack(auth, expected) {
             const session = patch[sessionField];
             if (!session?.sessionToken)
                 throw new AuthError("invalid_credentials");
-            return { awsSession: { ...session, binding: expected } };
+            return { awsSession: stamped(session, expected) };
         };
     }
+    if (auth.kind === "cookie")
+        return (patch) => {
+            const session = patch[auth.field];
+            if (!session?.revision)
+                throw new AuthError("invalid_credentials");
+            return { cookieSession: stamped(session, expected) };
+        };
     if (auth.kind !== "oauth2")
         throw new AuthError("invalid_definition");
     return (patch, current) => {
@@ -136,23 +158,17 @@ function localSigner(ctx, declaration) {
             const key = selection.awsProfile
                 ? await awsProfileKey(selection.awsProfile)
                 : staticSecret(current, selection.localSecret, ["sessionToken"]);
-            const cached = current.awsSession;
+            const session = issuedUnder(current.awsSession, expected);
             const sessionField = auth.assumeRole?.sessionField;
             return {
                 ...(key ? { [auth.field]: key } : {}),
-                ...(sessionField && cached?.binding === expected
-                    ? {
-                        [sessionField]: {
-                            accessKeyId: cached.accessKeyId,
-                            secretAccessKey: cached.secretAccessKey,
-                            sessionToken: cached.sessionToken,
-                            expiresAt: cached.expiresAt,
-                            revision: cached.revision,
-                        },
-                    }
-                    : {}),
+                ...(sessionField && session ? { [sessionField]: session } : {}),
             };
         }
+        if (auth.kind === "cookie") {
+            const session = issuedUnder(current.cookieSession, expected);
+            return session ? { [auth.field]: session } : {};
+        }
         const compatible = current.authTokenBinding === undefined ||
             current.authTokenBinding === expected;
         const tokens = {

package/dist/credentials/cookies.d.ts

@@ -0,0 +1,33 @@
+import type { StoredCookie } from "./types.js";
+/**
+ * A cookie jar for one connection, after RFC 6265 §5: what a `Set-Cookie`
+ * stores, replaces or deletes, and which cookies a request carries. Pure:
+ * the transport decides which responses reach it (only its targets') and
+ * persists what it answers.
+ */
+/** The most cookies a jar keeps; the oldest go first beyond it. */
+export declare const MAX_COOKIES = 64;
+/** A cookie name: an RFC 7230 token. */
+export declare function isCookieName(name: unknown): name is string;
+/**
+ * One `Set-Cookie` from a response to `url`: the cookie it stores, with
+ * `expired` when it deletes (Max-Age ≤ 0, or an Expires in the past).
+ * Undefined for one a jar ignores: no name, a value or name it cannot
+ * send back, an oversized one, or a Domain the host does not match.
+ */
+export declare function parseSetCookie(header: string, url: URL, now: number): {
+    cookie: StoredCookie;
+    expired: boolean;
+} | undefined;
+/** The cookies still alive at `now`. */
+export declare function liveCookies(cookies: readonly StoredCookie[], now: number): StoredCookie[];
+/**
+ * The jar after a response to `url` set `headers`: each cookie replaces
+ * the one of the same name, domain and path, a deletion removes it, and
+ * expired cookies are dropped. At most `MAX_COOKIES`, newest kept.
+ */
+export declare function applySetCookies(cookies: readonly StoredCookie[], headers: readonly string[], url: URL, now: number): StoredCookie[];
+/** The Cookie header for a request to `url`, or undefined when none match. */
+export declare function cookieHeader(cookies: readonly StoredCookie[], url: URL, now: number): string | undefined;
+/** The value of cookie `name` a request to `url` would carry. */
+export declare function cookieFor(cookies: readonly StoredCookie[], name: string, url: URL, now: number): string | undefined;

package/dist/credentials/cookies.js

@@ -0,0 +1,151 @@
+import { isIP } from "node:net";
+/**
+ * A cookie jar for one connection, after RFC 6265 §5: what a `Set-Cookie`
+ * stores, replaces or deletes, and which cookies a request carries. Pure:
+ * the transport decides which responses reach it (only its targets') and
+ * persists what it answers.
+ */
+/** The most cookies a jar keeps; the oldest go first beyond it. */
+export const MAX_COOKIES = 64;
+/** The largest name plus value a cookie may have (RFC 6265 §6.1's floor). */
+const MAX_COOKIE_BYTES = 4096;
+const TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+/** A cookie name: an RFC 7230 token. */
+export function isCookieName(name) {
+    return typeof name === "string" && TOKEN.test(name);
+}
+/** A value safe to send back in a Cookie header: printable ASCII without `;`. */
+function cookieValue(value) {
+    return /^[\x20-\x3a\x3c-\x7e]*$/.test(value);
+}
+function domainMatch(host, domain) {
+    return host === domain || (host.endsWith(`.${domain}`) && !isIP(host));
+}
+/** RFC 6265 §5.1.4: the directory of the request path. */
+function defaultPath(pathname) {
+    if (!pathname.startsWith("/"))
+        return "/";
+    const last = pathname.lastIndexOf("/");
+    return last <= 0 ? "/" : pathname.slice(0, last);
+}
+function pathMatch(requestPath, cookiePath) {
+    return (requestPath === cookiePath ||
+        (requestPath.startsWith(cookiePath) &&
+            (cookiePath.endsWith("/") || requestPath[cookiePath.length] === "/")));
+}
+/**
+ * One `Set-Cookie` from a response to `url`: the cookie it stores, with
+ * `expired` when it deletes (Max-Age ≤ 0, or an Expires in the past).
+ * Undefined for one a jar ignores: no name, a value or name it cannot
+ * send back, an oversized one, or a Domain the host does not match.
+ */
+export function parseSetCookie(header, url, now) {
+    const [pair, ...attributes] = header.split(";");
+    const equals = pair.indexOf("=");
+    if (equals < 0)
+        return undefined;
+    const name = pair.slice(0, equals).trim();
+    const value = pair.slice(equals + 1).trim();
+    if (!isCookieName(name) ||
+        !cookieValue(value) ||
+        name.length + value.length > MAX_COOKIE_BYTES)
+        return undefined;
+    const host = url.hostname.toLowerCase();
+    let domain;
+    let path;
+    let maxAge;
+    let expires;
+    let secure = false;
+    let httpOnly = false;
+    for (const attribute of attributes) {
+        const at = attribute.indexOf("=");
+        const key = (at < 0 ? attribute : attribute.slice(0, at))
+            .trim()
+            .toLowerCase();
+        const raw = at < 0 ? "" : attribute.slice(at + 1).trim();
+        if (key === "max-age" && /^-?\d+$/.test(raw))
+            maxAge = Number(raw);
+        else if (key === "expires") {
+            const parsed = Date.parse(raw);
+            if (Number.isFinite(parsed))
+                expires = parsed;
+        }
+        else if (key === "domain" && raw) {
+            domain = raw.replace(/^\./, "").toLowerCase();
+        }
+        else if (key === "path")
+            path = raw.startsWith("/") ? raw : undefined;
+        else if (key === "secure")
+            secure = true;
+        else if (key === "httponly")
+            httpOnly = true;
+    }
+    // A Domain the host does not match is refused, and so is a bare
+    // top-level label. A wider Domain still reaches only the method's own
+    // targets: the jar signs nothing else.
+    if (domain !== undefined &&
+        (!domainMatch(host, domain) || (domain !== host && !domain.includes("."))))
+        return undefined;
+    const until = maxAge !== undefined ? now + maxAge * 1000 : expires;
+    const expiresAt = until === undefined
+        ? undefined
+        : Math.min(Math.max(0, until), Number.MAX_SAFE_INTEGER);
+    const cookie = {
+        name,
+        value,
+        domain: domain ?? host,
+        hostOnly: domain === undefined,
+        path: path ?? defaultPath(url.pathname),
+        secure,
+        httpOnly,
+        ...(expiresAt !== undefined ? { expiresAt } : {}),
+    };
+    return { cookie, expired: expiresAt !== undefined && expiresAt <= now };
+}
+/** The cookies still alive at `now`. */
+export function liveCookies(cookies, now) {
+    return cookies.filter((cookie) => cookie.expiresAt === undefined || cookie.expiresAt > now);
+}
+/**
+ * The jar after a response to `url` set `headers`: each cookie replaces
+ * the one of the same name, domain and path, a deletion removes it, and
+ * expired cookies are dropped. At most `MAX_COOKIES`, newest kept.
+ */
+export function applySetCookies(cookies, headers, url, now) {
+    let jar = liveCookies(cookies, now);
+    for (const header of headers) {
+        const parsed = parseSetCookie(header, url, now);
+        if (!parsed)
+            continue;
+        const { cookie, expired } = parsed;
+        jar = jar.filter((kept) => kept.name !== cookie.name ||
+            kept.domain !== cookie.domain ||
+            kept.path !== cookie.path);
+        if (!expired)
+            jar.push(cookie);
+    }
+    return jar.slice(-MAX_COOKIES);
+}
+/** The cookies a request to `url` carries, longest path first. */
+function matching(cookies, url, now) {
+    const host = url.hostname.toLowerCase();
+    return liveCookies(cookies, now)
+        .filter((cookie) => (cookie.hostOnly
+        ? host === cookie.domain
+        : domainMatch(host, cookie.domain)) &&
+        pathMatch(url.pathname, cookie.path) &&
+        (!cookie.secure || url.protocol === "https:"))
+        .sort((a, b) => b.path.length - a.path.length);
+}
+/** The Cookie header for a request to `url`, or undefined when none match. */
+export function cookieHeader(cookies, url, now) {
+    const sent = matching(cookies, url, now);
+    return sent.length
+        ? sent.map((cookie) => `${cookie.name}=${cookie.value}`).join("; ")
+        : undefined;
+}
+/** The value of cookie `name` a request to `url` would carry. */
+export function cookieFor(cookies, name, url, now) {
+    return matching(cookies, url, now).find((cookie) => cookie.name === name)
+        ?.value;
+}

package/dist/credentials/http.d.ts

@@ -4,6 +4,17 @@ export interface ResourceOptions {
     timeoutMs: number;
     maxResponseBytes: number;
     resumableUpload?: boolean;
+    /**
+     * The 3xx that come back as they are, Location and all, judged by their
+     * Location; nothing is followed. Without it, or when it refuses, a 3xx
+     * fails as transport_failed, bar a resumable upload's 308.
+     */
+    redirect?: (location: string | null) => boolean;
+    /**
+     * Receives the response's `Set-Cookie` values before they are stripped:
+     * the only way a cookie leaves this function, and never to a caller.
+     */
+    setCookie?: (values: string[]) => void;
 }
 /** Internal send primitive. Callers validate destination policy before reaching it. */
 export declare function sendResource(url: string, method: HttpMethod, headers: Headers, body: Buffer | undefined, options: ResourceOptions): Promise<Response>;

package/dist/credentials/http.js

@@ -14,7 +14,7 @@ export async function sendResource(url, method, headers, body, options) {
             method,
             headers,
             body: body === undefined ? undefined : Buffer.from(body),
-            redirect: "error",
+            redirect: options.redirect ? "manual" : "error",
             credentials: "omit",
             signal: controller.signal,
         });
@@ -22,6 +22,7 @@ export async function sendResource(url, method, headers, body, options) {
             response.redirected ||
             (response.status >= 300 &&
                 response.status < 400 &&
+                !options.redirect?.(response.headers.get("location")) &&
                 !(options.resumableUpload &&
                     method === "PUT" &&
                     headers.has("content-range") &&
@@ -56,6 +57,7 @@ export async function sendResource(url, method, headers, body, options) {
             controller.signal.removeEventListener("abort", cancel);
             reader?.releaseLock();
         }
+        options.setCookie?.(response.headers.getSetCookie());
         const responseHeaders = new Headers(response.headers);
         // Fetch supplies decoded bytes, not the original wire representation.
         responseHeaders.delete("content-encoding");

package/dist/credentials/plugin.d.ts

@@ -1,8 +1,8 @@
 /**
  * The plugin side of the credential broker, public to every plugin —
  * bundled or custom: 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.
+ * shape each for OAuth and cookie methods, one way to turn public config
+ * into an HTTPS target, one request path.
  */
 import * as t from "typebox";
 import type { ActionContext } from "../plugin/types.js";
@@ -24,6 +24,25 @@ export declare const grantSchema: t.TObject<{
         revision: t.TString;
     }>>;
 }>;
+/**
+ * The stored shape of a cookie method: one optional cookie jar in the
+ * `session` field, absent until the first login.
+ */
+export declare const cookieSessionSchema: t.TObject<{
+    session: t.TOptional<t.TObject<{
+        cookies: t.TArray<t.TObject<{
+            name: t.TString;
+            value: t.TString;
+            domain: t.TString;
+            hostOnly: t.TBoolean;
+            path: t.TString;
+            secure: t.TBoolean;
+            httpOnly: t.TBoolean;
+            expiresAt: t.TOptional<t.TInteger>;
+        }>>;
+        revision: t.TString;
+    }>>;
+}>;
 /**
  * A flat config field, a fixed value such as Freshdesk's "X" password, or
  * the two joined in order, such as Zendesk's `{email}/token` username.

package/dist/credentials/plugin.js

@@ -1,18 +1,23 @@
 /**
  * The plugin side of the credential broker, public to every plugin —
  * bundled or custom: 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.
+ * shape each for OAuth and cookie methods, one way to turn public config
+ * into an HTTPS target, one request path.
  */
 import * as t from "typebox";
 import { AuthError } from "../auth/errors.js";
 import { brokerFor } from "./broker.js";
-import { OAuthGrantSchema, staticSecretSchema } from "./registry.js";
+import { CookieSessionSchema, OAuthGrantSchema, staticSecretSchema, } from "./registry.js";
 /**
  * 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 stored shape of a cookie method: one optional cookie jar in the
+ * `session` field, absent until the first login.
+ */
+export const cookieSessionSchema = t.Object({ session: t.Optional(CookieSessionSchema) }, { additionalProperties: false });
 /** The parts and placements a shorthand, or the general form, declares. */
 function placementsOf(auth) {
     if (auth.kind === "static") {

package/dist/credentials/policy.js

@@ -119,6 +119,8 @@ export function injectedHeaders(auth, target) {
         return ["authorization"];
     if (auth.kind === "awsSigV4")
         return [...SIGV4_HEADERS];
+    if (auth.kind === "cookie")
+        return auth.csrf ? [headerName(auth.csrf.header)] : [];
     return placementsFor(auth, target).flatMap((placement) => placement.in === "header" ||
         placement.in === "jwt" ||
         placement.in === "querySignature"

package/dist/credentials/registry.d.ts

@@ -43,6 +43,31 @@ export declare const AwsSessionSchema: t.TObject<{
     expiresAt: t.TInteger;
     revision: t.TString;
 }>;
+/** Stored shape of one cookie in a session's jar. */
+export declare const StoredCookieSchema: t.TObject<{
+    name: t.TString;
+    value: t.TString;
+    domain: t.TString;
+    hostOnly: t.TBoolean;
+    path: t.TString;
+    secure: t.TBoolean;
+    httpOnly: t.TBoolean;
+    expiresAt: t.TOptional<t.TInteger>;
+}>;
+/** Stored shape of a cookie session: its jar and the login it came from. */
+export declare const CookieSessionSchema: t.TObject<{
+    cookies: t.TArray<t.TObject<{
+        name: t.TString;
+        value: t.TString;
+        domain: t.TString;
+        hostOnly: t.TBoolean;
+        path: t.TString;
+        secure: t.TBoolean;
+        httpOnly: t.TBoolean;
+        expiresAt: t.TOptional<t.TInteger>;
+    }>>;
+    revision: t.TString;
+}>;
 /** No implicit defaults, provider inference, executable expressions, or replacement. */
 export declare class CredentialRegistry {
     private readonly types;

package/dist/credentials/registry.js

@@ -4,6 +4,7 @@ import { AuthError } from "../auth/errors.js";
 import { validateOAuth2ExchangePolicy } from "../auth/oauth2.js";
 import { oauthEndpoint, providerHeaders, providerParameters, } from "../auth/token.js";
 import { isAwsScope } from "./aws.js";
+import { isCookieName, MAX_COOKIES } from "./cookies.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({
@@ -44,6 +45,22 @@ export const AwsSessionSchema = t.Object({
     expiresAt: t.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
     revision: t.String({ minLength: 1 }),
 }, { additionalProperties: false });
+/** Stored shape of one cookie in a session's jar. */
+export const StoredCookieSchema = t.Object({
+    name: t.String({ minLength: 1 }),
+    value: t.String(),
+    domain: t.String({ minLength: 1 }),
+    hostOnly: t.Boolean(),
+    path: t.String({ minLength: 1 }),
+    secure: t.Boolean(),
+    httpOnly: t.Boolean(),
+    expiresAt: t.Optional(t.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER })),
+}, { additionalProperties: false });
+/** Stored shape of a cookie session: its jar and the login it came from. */
+export const CookieSessionSchema = t.Object({
+    cookies: t.Array(StoredCookieSchema, { maxItems: MAX_COOKIES }),
+    revision: t.String({ minLength: 1 }),
+}, { additionalProperties: false });
 /** Whether two strict object schemas store the same fields, alike required. */
 function sameShape(actual, expected) {
     const shape = actual;
@@ -77,6 +94,70 @@ function identifier(value) {
     if (typeof value !== "string" || !/^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(value))
         throw new AuthError("invalid_definition");
 }
+/** A login form's field name, brackets allowed (Rails' `user[email]`). */
+function formField(value) {
+    if (typeof value !== "string" || !/^[A-Za-z_][\w.[\]-]{0,99}$/.test(value))
+        throw new AuthError("invalid_definition");
+    return value;
+}
+/** The longest body marker a rejection may declare. */
+const MAX_MARKER_LENGTH = 128;
+/**
+ * A cookie method stores an optional jar in its field, logs in on one of
+ * its own targets with a POST (and a GET, with a preflight), and declares
+ * at least one rejection signal; every path is checked as a request path
+ * beneath the login target is.
+ */
+function validateCookie(auth, method) {
+    const schema = method.schema;
+    if (!sameShape(schema.properties?.[auth.field], CookieSessionSchema) ||
+        schema.required?.includes(auth.field))
+        throw new AuthError("invalid_definition");
+    const { login, rejection, csrf } = auth;
+    const target = login && targetOf(method, login.target);
+    if (!target ||
+        target.socket ||
+        !target.methods.includes("POST") ||
+        (login.preflight !== undefined && !target.methods.includes("GET")) ||
+        !["form", "json"].includes(login.encoding))
+        throw new AuthError("invalid_definition");
+    resourceUrl(target, login.path);
+    if (login.preflight !== undefined)
+        resourceUrl(target, login.preflight);
+    const names = [
+        formField(login.fields?.username ?? "username"),
+        formField(login.fields?.password ?? "password"),
+    ];
+    for (const [name, value] of Object.entries(login.parameters ?? {})) {
+        names.push(formField(name));
+        if (typeof value !== "string" || !/^[\x20-\x7e]{0,1024}$/.test(value))
+            throw new AuthError("invalid_definition");
+    }
+    if (new Set(names).size !== names.length)
+        throw new AuthError("invalid_definition");
+    const { statuses, loginPaths, marker } = rejection ?? {};
+    if (!rejection ||
+        (statuses !== undefined &&
+            (!Array.isArray(statuses) ||
+                !statuses.length ||
+                statuses.some((status) => !Number.isInteger(status) || status < 400 || status > 499))) ||
+        (loginPaths !== undefined &&
+            (!Array.isArray(loginPaths) || !loginPaths.length)) ||
+        (marker !== undefined &&
+            (typeof marker !== "string" ||
+                marker.length > MAX_MARKER_LENGTH ||
+                !/^[\x20-\x7e]+$/.test(marker))) ||
+        (statuses === undefined && loginPaths === undefined && marker === undefined))
+        throw new AuthError("invalid_definition");
+    for (const path of loginPaths ?? [])
+        resourceUrl(target, path);
+    if (csrf !== undefined) {
+        if (!isCookieName(csrf.cookie))
+            throw new AuthError("invalid_definition");
+        if (TRANSPORT_HEADERS.includes(headerName(csrf.header)))
+            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
@@ -201,6 +282,8 @@ function validateMethod(method) {
         validateStatic(auth, schema.properties[auth.field], Object.keys(method.targets ?? {}));
     else if (auth.kind === "awsSigV4")
         validateAwsSigV4(auth, schema);
+    else if (auth.kind === "cookie")
+        validateCookie(auth, method);
     else if (auth.kind === "oauth2") {
         identifier(auth.definition.id);
         identifier(auth.definition.provider);
@@ -304,6 +387,7 @@ function validateMethod(method) {
             (target.socket !== true ||
                 auth.kind === "oauth2" ||
                 auth.kind === "awsSigV4" ||
+                auth.kind === "cookie" ||
                 target.allowedHeaders !== undefined ||
                 target.idempotency !== undefined ||
                 target.resumableUpload !== undefined ||

package/dist/credentials/transport.d.ts

@@ -77,6 +77,30 @@ export declare class CredentialTransport {
      */
     private commitIssued;
     private renew;
+    /**
+     * A cookie session logged in under the connection's update ownership, so
+     * parallel calls on an expired session log in once: one another caller
+     * committed meanwhile is kept. With `rejected`, the jar sent at
+     * `observedRevision` was refused and only a newer login is kept.
+     */
+    private loginSession;
+    /**
+     * The declared login: a preflight GET when declared, then the owner's
+     * POST, both carrying the jar and absorbing what they set. The jar is
+     * merged into, never replaced, so a device-trust cookie survives. A
+     * login refused by status is `provider_rejected` with it; one the app
+     * answers with a rejection signal, or that leaves no cookie, is
+     * `reconnect_required`. The password goes in this one request only.
+     */
+    private logIn;
+    /**
+     * What a response of the session sent at `revision` set, merged into the
+     * stored jar: a rotated, added or deleted cookie. Only while the jar is
+     * still that login's, so a stale response never undoes a newer login.
+     * Best effort: a store that fails leaves the response standing, and the
+     * session is renewed when it is next rejected.
+     */
+    private absorb;
     /** A role session for the binding's `awsRole`, assumed with the stored key. */
     private renewAwsSession;
     /** New tokens by the method's declared renewal, from what the binding supplies. */

package/dist/credentials/transport.js

@@ -3,9 +3,10 @@ import { Check } from "typebox/value";
 import { AuthError } from "../auth/errors.js";
 import { acquireOAuth2ClientToken, acquireOAuth2JwtToken, acquireOAuth2PasswordToken, refreshOAuth2Token, } from "../auth/oauth2.js";
 import { assumeAwsRole, awsAccessKey } from "./aws.js";
+import { applySetCookies, cookieFor, cookieHeader, liveCookies, } from "./cookies.js";
 import { sendResource } from "./http.js";
 import { bodyFields, bodyFormat, bounded, headerName, injectedFields, injectedHeaders, injectedParams, injectedPointers, placementsFor, pointerSlot, refuseCredentialParams, resourceUrl, secret, TARGET_RESPONSE_LIMIT_BYTES, TARGET_TIMEOUT_LIMIT_MS, TRANSPORT_HEADERS, targetBase, targetOf, } from "./policy.js";
-import { OAuthGrantSchema, validateCredential, } from "./registry.js";
+import { CookieSessionSchema, OAuthGrantSchema, validateCredential, } from "./registry.js";
 import { canonicalQuery, signSigV4 } from "./sigv4.js";
 function boundSnapshot(binding, method, snapshot) {
     if (snapshot.name !== binding.identity.name ||
@@ -29,6 +30,67 @@ function grantFrom(method, config) {
         throw new AuthError("unsupported_operation");
     return result;
 }
+function cookieSessionFrom(auth, config) {
+    const session = config[auth.field];
+    if (session === undefined)
+        return undefined;
+    if (!Check(CookieSessionSchema, session))
+        throw new AuthError("invalid_credentials");
+    return session;
+}
+/** Methods that change state, on which a CSRF header is sent. */
+function unsafe(method) {
+    return method !== "GET" && method !== "HEAD";
+}
+/** Signs with the jar's cookies for the request's URL, and the CSRF header on an unsafe one. */
+function cookieSigner(auth, cookies) {
+    return ({ method, headers, url }) => {
+        const now = Date.now();
+        const cookie = cookieHeader(cookies, url, now);
+        if (cookie)
+            headers.set("cookie", cookie);
+        if (auth.csrf && unsafe(method)) {
+            const token = cookieFor(cookies, auth.csrf.cookie, url, now);
+            if (token)
+                headers.set(headerName(auth.csrf.header), token);
+        }
+    };
+}
+/** Whether a Location, read against the request's `url`, falls beneath a declared login path. */
+function toLogin(auth, loginTarget, location, url) {
+    if (!location || !auth.rejection.loginPaths)
+        return false;
+    let next;
+    try {
+        next = new URL(location, url);
+    }
+    catch {
+        return false;
+    }
+    return auth.rejection.loginPaths.some((path) => {
+        const login = resourceUrl(loginTarget, path);
+        return (next.origin === login.origin && next.pathname.startsWith(login.pathname));
+    });
+}
+/**
+ * How a response shows a cookie session was rejected, by the method's
+ * declared signals: its status, a redirect to a login path, or a body
+ * marker on an HTML answer. Null when it shows none.
+ */
+async function sessionRejection(auth, loginTarget, response, url) {
+    const { statuses, marker } = auth.rejection;
+    if (statuses?.includes(response.status))
+        return "status";
+    if (toLogin(auth, loginTarget, response.headers.get("location"), url))
+        return "redirect";
+    if (marker &&
+        response.status >= 200 &&
+        response.status < 300 &&
+        (response.headers.get("content-type") ?? "").includes("text/html") &&
+        (await response.clone().text()).includes(marker))
+        return "marker";
+    return null;
+}
 function pinBinding(selection) {
     return {
         ...selection,
@@ -313,6 +375,118 @@ export class CredentialTransport {
             },
         });
     }
+    /**
+     * A cookie session logged in under the connection's update ownership, so
+     * parallel calls on an expired session log in once: one another caller
+     * committed meanwhile is kept. With `rejected`, the jar sent at
+     * `observedRevision` was refused and only a newer login is kept.
+     */
+    loginSession(binding, method, observedRevision, rejected = false) {
+        const auth = method.authentication;
+        if (auth.kind !== "cookie")
+            throw new AuthError("invalid_definition");
+        return this.commitIssued(binding, method, {
+            field: auth.field,
+            read: (config) => cookieSessionFrom(auth, config),
+            usable: (previous) => !!previous &&
+                liveCookies(previous.cookies, Date.now()).length > 0 &&
+                (!rejected || previous.revision !== observedRevision),
+            issue: (previous) => this.logIn(auth, method, binding, previous),
+        });
+    }
+    /**
+     * The declared login: a preflight GET when declared, then the owner's
+     * POST, both carrying the jar and absorbing what they set. The jar is
+     * merged into, never replaced, so a device-trust cookie survives. A
+     * login refused by status is `provider_rejected` with it; one the app
+     * answers with a rejection signal, or that leaves no cookie, is
+     * `reconnect_required`. The password goes in this one request only.
+     */
+    async logIn(auth, method, binding, previous) {
+        const owner = binding.resourceOwner;
+        if (!owner?.username || !owner.password)
+            throw new AuthError("invalid_credentials");
+        const { login } = auth;
+        const target = targetOf(method, login.target);
+        if (!target)
+            throw new AuthError("invalid_definition");
+        let cookies = liveCookies(previous?.cookies ?? [], Date.now());
+        const exchange = async (path, verb, body) => {
+            const url = resourceUrl(target, path);
+            const headers = new Headers({ accept: "*/*" });
+            if (body)
+                headers.set("content-type", body.type);
+            const sign = cookieSigner(auth, cookies);
+            sign({ method: verb, headers, url, base: targetBase(target).pathname });
+            let set = [];
+            const response = await sendResource(url.toString(), verb, headers, body?.bytes, {
+                fetch: this.options.fetch,
+                timeoutMs: this.options.timeoutMs,
+                maxResponseBytes: this.options.maxResponseBytes,
+                redirect: () => true,
+                setCookie: (values) => {
+                    set = values;
+                },
+            });
+            cookies = applySetCookies(cookies, set, url, Date.now());
+            return { response, url };
+        };
+        if (login.preflight !== undefined) {
+            const { response } = await exchange(login.preflight, "GET");
+            if (response.status >= 400)
+                throw new AuthError("provider_rejected", response.status);
+        }
+        const fields = {
+            ...login.parameters,
+            [login.fields?.username ?? "username"]: owner.username,
+            [login.fields?.password ?? "password"]: owner.password,
+        };
+        const body = login.encoding === "json"
+            ? {
+                type: "application/json",
+                bytes: Buffer.from(JSON.stringify(fields)),
+            }
+            : {
+                type: "application/x-www-form-urlencoded",
+                bytes: Buffer.from(new URLSearchParams(fields).toString()),
+            };
+        const { response, url } = await exchange(login.path, "POST", body);
+        if (response.status >= 400)
+            throw new AuthError("provider_rejected", response.status);
+        if ((await sessionRejection(auth, target, response, url)) ||
+            !liveCookies(cookies, Date.now()).length)
+            throw new AuthError("reconnect_required");
+        return { cookies, revision: randomUUID() };
+    }
+    /**
+     * What a response of the session sent at `revision` set, merged into the
+     * stored jar: a rotated, added or deleted cookie. Only while the jar is
+     * still that login's, so a stale response never undoes a newer login.
+     * Best effort: a store that fails leaves the response standing, and the
+     * session is renewed when it is next rejected.
+     */
+    async absorb(binding, method, revision, values, url) {
+        const auth = method.authentication;
+        if (auth.kind !== "cookie" || !values.length)
+            return;
+        try {
+            await binding.connection.update(async (current) => {
+                validateCredential(method, current);
+                const stored = cookieSessionFrom(auth, current);
+                if (stored?.revision !== revision)
+                    return undefined;
+                return {
+                    [auth.field]: {
+                        cookies: applySetCookies(stored.cookies, values, url, Date.now()),
+                        revision,
+                    },
+                };
+            });
+        }
+        catch {
+            // The response stands; the jar catches up at the next rejection.
+        }
+    }
     /** A role session for the binding's `awsRole`, assumed with the stored key. */
     renewAwsSession(binding, method, observedRevision) {
         const auth = method.authentication;
@@ -442,9 +616,17 @@ export class CredentialTransport {
         }
         const replay = input.retry !== "never" &&
             (verb === "GET" || verb === "HEAD" || input.idempotencyKey !== undefined);
+        // A rejected credential is dead whether or not this request may be sent
+        // again, so it is renewed either way and the next call signs with the
+        // renewal. Only a replayable request is sent again, exactly once; any
+        // other is answered with its rejection.
+        const afterRejection = async (rejection, renew, resend) => {
+            const renewed = await renew();
+            return replay ? resend(renewed) : rejection;
+        };
         const base = targetBase(target).pathname;
-        let { sign, grant } = await this.authorize(binding, method, input.target);
-        const send = async (signer) => {
+        const { sign, grant, session } = await this.authorize(binding, method, input.target);
+        const send = async (signer, cookies) => {
             const outgoing = {
                 method: verb,
                 headers: new Headers(headers),
@@ -458,17 +640,43 @@ export class CredentialTransport {
                 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,
+                ...cookies,
             });
         };
+        if (auth.kind === "cookie" && session) {
+            const loginTarget = targetOf(method, auth.login.target);
+            if (!loginTarget)
+                throw new AuthError("invalid_definition");
+            const attempt = async (current) => {
+                let set = [];
+                const response = await send(cookieSigner(auth, current.cookies), {
+                    redirect: (location) => toLogin(auth, loginTarget, location, url),
+                    setCookie: (values) => {
+                        set = values;
+                    },
+                });
+                await this.absorb(binding, method, current.revision, set, url);
+                const rejection = await sessionRejection(auth, loginTarget, response, url);
+                // A rejection by redirect or marker reads as the 401 it means; one
+                // by status keeps the app's own answer.
+                return {
+                    rejection,
+                    response: rejection === "redirect" || rejection === "marker"
+                        ? new Response(null, { status: 401 })
+                        : response,
+                };
+            };
+            const first = await attempt(session);
+            if (!first.rejection)
+                return first.response;
+            return afterRejection(first.response, () => this.loginSession(binding, method, session.revision, true), async (renewed) => (await attempt(renewed)).response);
+        }
         const first = await send(sign);
         if (auth.kind !== "oauth2" ||
             !grant ||
-            !replay ||
             first.status !== (auth.rejectionStatus ?? 401))
             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(bearer(secret(grant.tokens.accessToken)));
+        return afterRejection(first, () => this.renew(binding, method, grant.revision, true), (renewed) => send(bearer(secret(renewed.tokens.accessToken))));
     }
     /**
      * A socket target's URL, signed by its query placements, for a host's
@@ -521,6 +729,13 @@ export class CredentialTransport {
         const auth = method.authentication;
         if (auth.kind === "none")
             return { sign: () => { } };
+        if (auth.kind === "cookie") {
+            const stored = cookieSessionFrom(auth, config);
+            const session = stored && liveCookies(stored.cookies, Date.now()).length
+                ? stored
+                : await this.loginSession(binding, method, stored?.revision);
+            return { sign: cookieSigner(auth, session.cookies), session };
+        }
         if (auth.kind === "awsSigV4") {
             const scope = targetOf(method, target)?.aws;
             if (!scope)

package/dist/credentials/types.d.ts

@@ -139,7 +139,8 @@ export type SecretPlacement = ({
  * 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; for `awsSigV4`, an AWS access key.
+ * `oauth2`, a revisioned OAuthGrant; for `awsSigV4`, an AWS access key;
+ * for `cookie`, a revisioned `CookieSession` jar.
  * `none` signs nothing: the method of a connection that holds no optional
  * credential, still pinned to its targets.
  */
@@ -190,7 +191,79 @@ export type CredentialAuthentication = {
     assumeRole?: {
         sessionField: string;
     };
+} | {
+    /**
+     * A web app's cookie session. The transport logs in with the
+     * binding's `resourceOwner` as `login` declares, keeps every cookie
+     * the method's targets set in a jar in `field` (`CookieSessionSchema`),
+     * sends each only where RFC 6265 matches it, and logs in again when a
+     * response shows the session was rejected. The plugin never sees the
+     * password, the jar, or a `Set-Cookie`.
+     */
+    kind: "cookie";
+    field: string;
+    login: CookieLogin;
+    rejection: CookieRejection;
+    /**
+     * Cookie-based CSRF (Django's `csrftoken`, `XSRF-TOKEN`): the named
+     * cookie's value is copied into `header` on every unsafe request, the
+     * login included. The header is reserved: callers never set it.
+     */
+    csrf?: {
+        cookie: string;
+        header: string;
+    };
 };
+/**
+ * How the transport logs in: an optional preflight GET (a CSRF cookie, a
+ * session to log into), then one POST of the owner's username and password
+ * under the app's own field names, beside fixed `parameters`. Both go to
+ * `target` and carry the jar, so a device-trust cookie rides along.
+ */
+export interface CookieLogin {
+    target: string;
+    /** Relative to the target's base, as a request path is. */
+    path: string;
+    encoding: "form" | "json";
+    /** The app's names for the owner's fields; `username` and `password` when absent. */
+    fields?: {
+        username?: string;
+        password?: string;
+    };
+    /** Fixed extra fields, such as `remember: "1"`. Never a secret. */
+    parameters?: Record<string, string>;
+    /** A path on `target` to GET before the POST. */
+    preflight?: string;
+}
+/**
+ * What a rejected session looks like, at least one of: a status; a 3xx
+ * whose Location falls under one of `loginPaths` (relative to the login
+ * target, as `login.path` is); or a 2xx HTML answer containing `marker`.
+ */
+export interface CookieRejection {
+    /** 4xx statuses, such as 401, 403, Laravel's 419 or IIS's 440. */
+    statuses?: number[];
+    loginPaths?: string[];
+    marker?: string;
+}
+/** One cookie in a session's jar, as RFC 6265 stores it. */
+export interface StoredCookie {
+    name: string;
+    value: string;
+    /** Lowercased: the exact host when `hostOnly`, else the Domain attribute. */
+    domain: string;
+    hostOnly: boolean;
+    path: string;
+    secure: boolean;
+    httpOnly: boolean;
+    /** Milliseconds since epoch; absent for a session cookie, kept until replaced. */
+    expiresAt?: number;
+}
+/** A cookie jar as stored. `revision` changes on every login, never on a rotated cookie. */
+export interface CookieSession {
+    cookies: StoredCookie[];
+    revision: string;
+}
 export interface CredentialProbe {
     target: string;
     /** Fixed relative path, including any fixed query. No expressions or callbacks. */

package/dist/index.d.ts

@@ -18,11 +18,11 @@ export { awsCredential, awsFailed, awsJson, awsList, awsQuery, awsTarget, } from
 export { brokerFor } from "./credentials/broker.js";
 export { downloadResource, type PresignedRequestOptions, presignedRequest, } from "./credentials/http.js";
 export type { CredentialCall, EmptyAnswer, ErrorEnvelope, StaticCredentialSpec, } from "./credentials/plugin.js";
-export { answerFailed, configChoice, configFlag, credentialJson, credentialOk, credentialRequest, credentialSocketUrl, errorIdentifier, failureMessage, grantSchema, graphqlFailed, hostLabel, httpsBase, jsonAnswer, jsonOrAcknowledged, multipartBody, pathSegment, pathSegments, pathWithin, refuseUnderHost, requestFailed, responseFailed, slashEncodedSegment, staticCredential, } from "./credentials/plugin.js";
-export { AwsAccessKeySchema, AwsSessionSchema, CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.js";
+export { answerFailed, configChoice, configFlag, cookieSessionSchema, credentialJson, credentialOk, credentialRequest, credentialSocketUrl, errorIdentifier, failureMessage, grantSchema, graphqlFailed, hostLabel, httpsBase, jsonAnswer, jsonOrAcknowledged, multipartBody, pathSegment, pathSegments, pathWithin, refuseUnderHost, requestFailed, responseFailed, slashEncodedSegment, staticCredential, } from "./credentials/plugin.js";
+export { AwsAccessKeySchema, AwsSessionSchema, CookieSessionSchema, CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, StoredCookieSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.js";
 export type { AuthenticatedRequest, CredentialBroker, CredentialBrokerCall, CredentialTransportOptions, SocketRequest, } from "./credentials/transport.js";
 export { CredentialTransport } from "./credentials/transport.js";
-export type { AwsAccessKey, AwsRole, AwsScope, AwsSession, CredentialAuthentication, CredentialBinding, CredentialDeclaration, CredentialMethod, CredentialProbe, CredentialProbeResult, CredentialSelection, CredentialTarget, CredentialType, HttpMethod, LocalSecretPart, LocalSecretSource, OAuthGrant, SecretPlacement, } from "./credentials/types.js";
+export type { AwsAccessKey, AwsRole, AwsScope, AwsSession, CookieLogin, CookieRejection, CookieSession, CredentialAuthentication, CredentialBinding, CredentialDeclaration, CredentialMethod, CredentialProbe, CredentialProbeResult, CredentialSelection, CredentialTarget, CredentialType, HttpMethod, LocalSecretPart, LocalSecretSource, OAuthGrant, SecretPlacement, StoredCookie, } from "./credentials/types.js";
 export type { ActionDefinition, PluginFunction, RunlinePluginAPI, } from "./plugin/api.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.js";
 export type { InstalledPlugin, PluginSource } from "./plugin/installer.js";

package/dist/index.js

@@ -11,8 +11,8 @@ export { awsEndpoint, awsRegion, parseAwsXml } from "./credentials/aws.js";
 export { awsCredential, awsFailed, awsJson, awsList, awsQuery, awsTarget, } from "./credentials/aws-plugin.js";
 export { brokerFor } from "./credentials/broker.js";
 export { downloadResource, presignedRequest, } from "./credentials/http.js";
-export { answerFailed, configChoice, configFlag, credentialJson, credentialOk, credentialRequest, credentialSocketUrl, errorIdentifier, failureMessage, grantSchema, graphqlFailed, hostLabel, httpsBase, jsonAnswer, jsonOrAcknowledged, multipartBody, pathSegment, pathSegments, pathWithin, refuseUnderHost, requestFailed, responseFailed, slashEncodedSegment, staticCredential, } from "./credentials/plugin.js";
-export { AwsAccessKeySchema, AwsSessionSchema, CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.js";
+export { answerFailed, configChoice, configFlag, cookieSessionSchema, credentialJson, credentialOk, credentialRequest, credentialSocketUrl, errorIdentifier, failureMessage, grantSchema, graphqlFailed, hostLabel, httpsBase, jsonAnswer, jsonOrAcknowledged, multipartBody, pathSegment, pathSegments, pathWithin, refuseUnderHost, requestFailed, responseFailed, slashEncodedSegment, staticCredential, } from "./credentials/plugin.js";
+export { AwsAccessKeySchema, AwsSessionSchema, CookieSessionSchema, CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, StoredCookieSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.js";
 export { CredentialTransport } from "./credentials/transport.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.js";
 export { installPlugin, listInstalled, parsePluginSource, removePlugin, } from "./plugin/installer.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runline",
-  "version": "0.38.0",
+  "version": "0.39.0",
   "description": "Code mode for agents — turn any API or command into a callable action",
   "type": "module",
   "main": "dist/index.js",