runline 0.37.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,14 +4,39 @@ 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>;
+export interface PresignedRequestOptions {
+    /** Exact origins the URL may be on; anything else is refused. */
+    allowedOrigins: string[];
+    fetch: typeof globalThis.fetch;
+    method?: "GET" | "PUT" | "DELETE";
+    /** Request headers; credentials and cookies are never among them. */
+    headers?: Record<string, string>;
+    body?: Uint8Array;
+    maxResponseBytes?: number;
+}
 /**
- * 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.
+ * One request to a provider-issued preauthenticated URL — a signed
+ * download, an upload session — 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 declare function presignedRequest(value: string, options: PresignedRequestOptions): Promise<Response>;
+/** A GET of a provider-issued preauthenticated URL; see presignedRequest. */
 export declare function downloadResource(value: string, options: {
     allowedOrigins: string[];
     fetch: typeof globalThis.fetch;

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");
@@ -78,11 +80,19 @@ export async function sendResource(url, method, headers, body, options) {
     }
 }
 /**
- * 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.
+ * Headers a presigned request never sends: the URL is its only authority,
+ * so no credential or cookie rides along, and Destination belongs to the
+ * credential transport's COPY and MOVE.
  */
-export async function downloadResource(value, options) {
+const PRESIGNED_REFUSED_HEADERS = ["authorization", "cookie", "destination"];
+/**
+ * One request to a provider-issued preauthenticated URL — a signed
+ * download, an upload session — 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 presignedRequest(value, options) {
     let url;
     try {
         url = new URL(value);
@@ -101,9 +111,23 @@ export async function downloadResource(value, options) {
         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,
-    });
+    const method = options.method ?? "GET";
+    const headers = new Headers();
+    try {
+        for (const [name, value] of Object.entries(options.headers ?? {})) {
+            if (PRESIGNED_REFUSED_HEADERS.includes(name.toLowerCase()))
+                throw new Error();
+            headers.set(name, value);
+        }
+        if (options.body !== undefined && method !== "PUT")
+            throw new Error();
+    }
+    catch {
+        throw new AuthError("request_not_allowed");
+    }
+    return sendResource(url.toString(), method, headers, options.body === undefined ? undefined : Buffer.from(options.body), { fetch: options.fetch, timeoutMs: 20_000, maxResponseBytes });
+}
+/** A GET of a provider-issued preauthenticated URL; see presignedRequest. */
+export function downloadResource(value, options) {
+    return presignedRequest(value, options);
 }

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. */