runline 0.35.0 → 0.36.0

package/dist/credentials/registry.js

@@ -3,6 +3,7 @@ import { Check } from "typebox/value";
 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 { 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({
@@ -29,6 +30,49 @@ export const OAuthGrantSchema = t.Object({
     tokens: t.Partial(OAuthTokensSchema),
     revision: t.String({ minLength: 1 }),
 }, { additionalProperties: false });
+/** Stored shape of an AWS access key; a session's carries its token. */
+export const AwsAccessKeySchema = t.Object({
+    accessKeyId: t.String({ minLength: 1 }),
+    secretAccessKey: t.String({ minLength: 1 }),
+    sessionToken: t.Optional(t.String({ minLength: 1 })),
+}, { additionalProperties: false });
+/** Stored shape of an assumed role's session. */
+export const AwsSessionSchema = t.Object({
+    accessKeyId: t.String({ minLength: 1 }),
+    secretAccessKey: t.String({ minLength: 1 }),
+    sessionToken: t.String({ minLength: 1 }),
+    expiresAt: t.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER }),
+    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;
+    const describe = (schema) => JSON.stringify([
+        schema.type,
+        schema.additionalProperties,
+        Object.entries(schema.properties ?? {})
+            .map(([name, field]) => [name, field.type])
+            .sort(),
+        [...(schema.required ?? [])].sort(),
+    ]);
+    return !!shape && describe(shape) === describe(expected);
+}
+/**
+ * A SigV4 method stores exactly an access key in its field and, when it
+ * assumes a role, an optional session in a field of its own.
+ */
+function validateAwsSigV4(auth, schema) {
+    if (!sameShape(schema.properties?.[auth.field], AwsAccessKeySchema))
+        throw new AuthError("invalid_definition");
+    if (auth.assumeRole === undefined)
+        return;
+    const session = auth.assumeRole.sessionField;
+    identifier(session);
+    if (session === auth.field ||
+        !sameShape(schema.properties?.[session], AwsSessionSchema) ||
+        schema.required?.includes(session))
+        throw new AuthError("invalid_definition");
+}
 function identifier(value) {
     if (typeof value !== "string" || !/^[a-zA-Z][a-zA-Z0-9_.-]*$/.test(value))
         throw new AuthError("invalid_definition");
@@ -155,6 +199,8 @@ function validateMethod(method) {
     }
     if (auth.kind === "static")
         validateStatic(auth, schema.properties[auth.field], Object.keys(method.targets ?? {}));
+    else if (auth.kind === "awsSigV4")
+        validateAwsSigV4(auth, schema);
     else if (auth.kind === "oauth2") {
         identifier(auth.definition.id);
         identifier(auth.definition.provider);
@@ -228,6 +274,11 @@ function validateMethod(method) {
         identifier(name);
         const injected = injectedHeaders(auth, name);
         targetBase(target);
+        // A SigV4 target names what it is signed for; no other target may.
+        if (auth.kind === "awsSigV4"
+            ? !isAwsScope(target.aws)
+            : target.aws !== undefined)
+            throw new AuthError("invalid_definition");
         if (!Array.isArray(target.methods) ||
             !target.methods.length ||
             target.methods.some((m) => !HTTP_METHODS.includes(m)))
@@ -246,11 +297,13 @@ function validateMethod(method) {
             if (injected.includes(header) || TRANSPORT_HEADERS.includes(header))
                 throw new AuthError("invalid_definition");
         }
-        // A socket URL carries only query parameters: no header, body or
-        // bearer can sign it, and nothing is sent through it by the transport.
+        // A socket URL carries only query parameters: no header, body,
+        // bearer or request signature can sign it, and nothing is sent
+        // through it by the transport.
         if (target.socket !== undefined &&
             (target.socket !== true ||
                 auth.kind === "oauth2" ||
+                auth.kind === "awsSigV4" ||
                 target.allowedHeaders !== undefined ||
                 target.idempotency !== undefined ||
                 target.resumableUpload !== undefined ||

package/dist/credentials/sigv4.d.ts

@@ -0,0 +1,47 @@
+import type { AwsAccessKey, AwsScope } from "./types.js";
+/**
+ * AWS Signature Version 4, header form. Pure: no IO, no clock — the
+ * caller supplies the signing time, so the canonical request is exactly
+ * reproducible and checked against AWS's published test suite.
+ */
+export interface SigV4Request {
+    method: string;
+    host: string;
+    /** The path exactly as it goes on the wire. */
+    path: string;
+    /** The query's parameters, decoded, in any order. */
+    query: Iterable<[key: string, value: string]>;
+    /**
+     * Every header the request carries besides Host, in order. A name may
+     * repeat; its values are signed joined by commas, as sent.
+     */
+    headers: Array<[name: string, value: string]>;
+    body?: Uint8Array;
+}
+/** The headers SigV4 adds to a request: each one is the signer's alone. */
+export declare const SIGV4_HEADERS: readonly ["authorization", "x-amz-date", "x-amz-security-token", "x-amz-content-sha256"];
+/** The query parameters of a presigned URL; a signed request carries none. */
+export declare const SIGV4_QUERY_PARAMETERS: readonly ["X-Amz-Algorithm", "X-Amz-Credential", "X-Amz-Date", "X-Amz-Expires", "X-Amz-Security-Token", "X-Amz-SignedHeaders", "X-Amz-Signature"];
+/**
+ * Parameters re-encoded and sorted by key, then value: the query SigV4
+ * signs, and the unambiguous one to send.
+ */
+export declare function canonicalQuery(query: Iterable<[string, string]>): string;
+/** `20150830T123600Z`: the signing time, to the second, in UTC. */
+export declare function amzDate(at: Date): string;
+/**
+ * The canonical request SigV4 signs, with the headers the signer adds
+ * to it: `x-amz-date`, the session's `x-amz-security-token`, and for S3
+ * the payload hash it requires. Host and every header given are signed.
+ */
+export declare function canonicalSigV4Request(request: SigV4Request, key: AwsAccessKey, scope: AwsScope, at: Date): {
+    canonicalRequest: string;
+    signed: string;
+    added: Record<string, string>;
+};
+/**
+ * The headers that sign `request` with `key` for `scope` at `at`: the
+ * added headers of `canonicalSigV4Request` and `authorization`. The
+ * request must then go out with exactly the headers it was signed with.
+ */
+export declare function signSigV4(request: SigV4Request, key: AwsAccessKey, scope: AwsScope, at: Date): Record<string, string>;

package/dist/credentials/sigv4.js

@@ -0,0 +1,145 @@
+import { createHash, createHmac } from "node:crypto";
+/** The headers SigV4 adds to a request: each one is the signer's alone. */
+export const SIGV4_HEADERS = [
+    "authorization",
+    "x-amz-date",
+    "x-amz-security-token",
+    "x-amz-content-sha256",
+];
+/** The query parameters of a presigned URL; a signed request carries none. */
+export const SIGV4_QUERY_PARAMETERS = [
+    "X-Amz-Algorithm",
+    "X-Amz-Credential",
+    "X-Amz-Date",
+    "X-Amz-Expires",
+    "X-Amz-Security-Token",
+    "X-Amz-SignedHeaders",
+    "X-Amz-Signature",
+];
+const ALGORITHM = "AWS4-HMAC-SHA256";
+/** RFC 3986 percent-encoding of UTF-8 bytes; unreserved characters stay. */
+function uriEncode(value, keepSlash) {
+    let out = "";
+    for (const byte of Buffer.from(value, "utf8")) {
+        const char = String.fromCharCode(byte);
+        out +=
+            /[A-Za-z0-9\-._~]/.test(char) || (keepSlash && char === "/")
+                ? char
+                : `%${byte.toString(16).toUpperCase().padStart(2, "0")}`;
+    }
+    return out;
+}
+/**
+ * A path as RFC 3986 normalizes it: dot segments resolved, empty segments
+ * dropped, a trailing slash kept.
+ */
+function normalizePath(path) {
+    const segments = [];
+    for (const segment of path.split("/")) {
+        if (segment === "..")
+            segments.pop();
+        else if (segment && segment !== ".")
+            segments.push(segment);
+    }
+    const normalized = `/${segments.join("/")}`;
+    return path.endsWith("/") && segments.length ? `${normalized}/` : normalized;
+}
+/**
+ * The path as sent, normalized and encoded once more: what every service
+ * but S3 signs. S3 signs the path exactly as sent.
+ */
+function canonicalUri(path, service) {
+    return service === "s3" ? path || "/" : uriEncode(normalizePath(path), true);
+}
+/**
+ * Parameters re-encoded and sorted by key, then value: the query SigV4
+ * signs, and the unambiguous one to send.
+ */
+export function canonicalQuery(query) {
+    return [...query]
+        .map(([key, value]) => [uriEncode(key, false), uriEncode(value, false)])
+        .sort(([ak, av], [bk, bv]) => ak < bk ? -1 : ak > bk ? 1 : av < bv ? -1 : av > bv ? 1 : 0)
+        .map(([key, value]) => `${key}=${value}`)
+        .join("&");
+}
+/** Header values trimmed, inner whitespace runs collapsed, repeats joined. */
+function canonicalHeaders(headers) {
+    const values = new Map();
+    for (const [name, value] of headers) {
+        const key = name.toLowerCase();
+        const list = values.get(key) ?? [];
+        list.push(value.trim().replace(/\s+/g, " "));
+        values.set(key, list);
+    }
+    const names = [...values.keys()].sort();
+    return {
+        canonical: names
+            .map((name) => `${name}:${values.get(name)?.join(",")}\n`)
+            .join(""),
+        signed: names.join(";"),
+    };
+}
+function sha256Hex(data) {
+    return createHash("sha256").update(data).digest("hex");
+}
+function hmac(key, data) {
+    return createHmac("sha256", key).update(data).digest();
+}
+/** `20150830T123600Z`: the signing time, to the second, in UTC. */
+export function amzDate(at) {
+    return at
+        .toISOString()
+        .replace(/[-:]/g, "")
+        .replace(/\.\d{3}/, "");
+}
+/**
+ * The canonical request SigV4 signs, with the headers the signer adds
+ * to it: `x-amz-date`, the session's `x-amz-security-token`, and for S3
+ * the payload hash it requires. Host and every header given are signed.
+ */
+export function canonicalSigV4Request(request, key, scope, at) {
+    const payloadHash = sha256Hex(request.body ?? new Uint8Array());
+    const added = {
+        "x-amz-date": amzDate(at),
+        ...(key.sessionToken ? { "x-amz-security-token": key.sessionToken } : {}),
+        ...(scope.service === "s3" ? { "x-amz-content-sha256": payloadHash } : {}),
+    };
+    const { canonical, signed } = canonicalHeaders([
+        ["host", request.host],
+        ...request.headers,
+        ...Object.entries(added),
+    ]);
+    const canonicalRequest = [
+        request.method,
+        canonicalUri(request.path, scope.service),
+        canonicalQuery(request.query),
+        canonical,
+        signed,
+        payloadHash,
+    ].join("\n");
+    return { canonicalRequest, signed, added };
+}
+/**
+ * The headers that sign `request` with `key` for `scope` at `at`: the
+ * added headers of `canonicalSigV4Request` and `authorization`. The
+ * request must then go out with exactly the headers it was signed with.
+ */
+export function signSigV4(request, key, scope, at) {
+    const { canonicalRequest, signed, added } = canonicalSigV4Request(request, key, scope, at);
+    const date = added["x-amz-date"];
+    const credentialScope = `${date.slice(0, 8)}/${scope.region}/${scope.service}/aws4_request`;
+    const stringToSign = [
+        ALGORITHM,
+        date,
+        credentialScope,
+        sha256Hex(canonicalRequest),
+    ].join("\n");
+    const signingKey = hmac(hmac(hmac(hmac(`AWS4${key.secretAccessKey}`, date.slice(0, 8)), scope.region), scope.service), "aws4_request");
+    const signature = createHmac("sha256", signingKey)
+        .update(stringToSign)
+        .digest("hex");
+    return {
+        ...added,
+        authorization: `${ALGORITHM} Credential=${key.accessKeyId}/${credentialScope}, SignedHeaders=${signed}, Signature=${signature}`,
+    };
+}

package/dist/credentials/transport.d.ts

@@ -69,7 +69,16 @@ export declare class CredentialTransport {
     private readonly options;
     constructor(registry: CredentialRegistry, options: CredentialTransportOptions);
     private read;
+    /**
+     * Issue a short-lived credential into `field` under the connection's
+     * update ownership. A credential another caller committed meanwhile is
+     * `usable` and kept; otherwise one is issued, validated as stored, and
+     * committed. Answers what the committed connection holds.
+     */
+    private commitIssued;
     private renew;
+    /** 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. */
     private issue;
     request(selection: CredentialBinding, input: AuthenticatedRequest): Promise<Response>;

package/dist/credentials/transport.js

@@ -2,9 +2,11 @@ import { createHmac, randomUUID } from "node:crypto";
 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 { sendResource } from "./http.js";
-import { bodyFields, bodyFormat, bounded, headerName, injectedFields, injectedHeaders, injectedParams, injectedPointers, placementsFor, pointerSlot, refuseCredentialParams, resourceUrl, TARGET_RESPONSE_LIMIT_BYTES, TARGET_TIMEOUT_LIMIT_MS, TRANSPORT_HEADERS, targetBase, targetOf, } from "./policy.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 { canonicalQuery, signSigV4 } from "./sigv4.js";
 function boundSnapshot(binding, method, snapshot) {
     if (snapshot.name !== binding.identity.name ||
         snapshot.plugin !== binding.identity.plugin)
@@ -34,6 +36,7 @@ function pinBinding(selection) {
         application: structuredClone(selection.application),
         jwtIdentity: structuredClone(selection.jwtIdentity),
         resourceOwner: structuredClone(selection.resourceOwner),
+        awsRole: structuredClone(selection.awsRole),
         connection: {
             read: selection.connection.read.bind(selection.connection),
             update: selection.connection.update.bind(selection.connection),
@@ -45,13 +48,6 @@ function fresh(grant) {
         (grant.tokens.expiresAt === undefined ||
             grant.tokens.expiresAt > Date.now() + 60_000));
 }
-function secret(value) {
-    if (typeof value !== "string" ||
-        !value ||
-        [...value].some((char) => char.charCodeAt(0) <= 32 || char.charCodeAt(0) > 126))
-        throw new AuthError("invalid_credentials");
-    return value;
-}
 /**
  * A part sent whole as a header value, such as `Bearer <token>`: printable
  * ASCII whose interior spaces are part of the value, with no control
@@ -76,6 +72,36 @@ function basicCredentials(username, password) {
         throw new AuthError("invalid_credentials");
     return Buffer.from(`${username}:${password}`).toString("base64");
 }
+/** Renewal leaves a role session this long before it expires. */
+const AWS_SESSION_MARGIN_MS = 5 * 60_000;
+function awsSessionFrom(auth, config) {
+    const field = auth.assumeRole?.sessionField;
+    return field === undefined ? undefined : config[field];
+}
+function awsSessionFresh(session) {
+    return !!session && session.expiresAt > Date.now() + AWS_SESSION_MARGIN_MS;
+}
+/**
+ * Signs with AWS SigV4 for `scope`, at the moment of sending, with a key
+ * checked before any IO. The query goes out in the canonical encoding it
+ * was signed in, so AWS decodes exactly the parameters that were signed.
+ */
+function sigV4(stored, scope) {
+    const key = awsAccessKey(stored);
+    return ({ method, headers, url, body }) => {
+        url.search = canonicalQuery(url.searchParams);
+        const added = signSigV4({
+            method,
+            host: url.host,
+            path: url.pathname,
+            query: url.searchParams,
+            headers: [...headers],
+            body,
+        }, key, scope, new Date());
+        for (const [name, value] of Object.entries(added))
+            headers.set(name, value);
+    };
+}
 /**
  * A secret as one path segment: `/`, `\`, `?`, `#` and dot segments are
  * refused rather than encoded; `:` and `@`, which RFC 3986 allows in a
@@ -223,32 +249,28 @@ export class CredentialTransport {
         }
         return boundSnapshot(binding, method, snapshot);
     }
-    async renew(binding, method, observedRevision, rejected = false) {
-        const auth = method.authentication;
-        if (auth.kind !== "oauth2")
-            throw new AuthError("invalid_definition");
+    /**
+     * Issue a short-lived credential into `field` under the connection's
+     * update ownership. A credential another caller committed meanwhile is
+     * `usable` and kept; otherwise one is issued, validated as stored, and
+     * committed. Answers what the committed connection holds.
+     */
+    async commitIssued(binding, method, renewal) {
         let callbackError;
         let committed;
         try {
             committed = await binding.connection.update(async (current) => {
                 try {
                     validateCredential(method, current);
-                    const previous = grantFrom(method, current);
-                    if ((fresh(previous) && !rejected) ||
-                        (previous &&
-                            previous.revision !== observedRevision &&
-                            previous.tokens.accessToken &&
-                            (previous.tokens.expiresAt === undefined ||
-                                previous.tokens.expiresAt > Date.now())))
+                    const previous = renewal.read(current);
+                    if (renewal.usable(previous))
                         return;
-                    const tokens = await this.issue(auth, binding, previous);
                     const patch = {
-                        [auth.field]: { tokens, revision: randomUUID() },
+                        [renewal.field]: await renewal.issue(previous, current),
                     };
                     const next = { ...current, ...patch };
                     validateCredential(method, next);
-                    grantFrom(method, next);
-                    secret(tokens.accessToken);
+                    renewal.read(next);
                     return patch;
                 }
                 catch (error) {
@@ -262,10 +284,54 @@ export class CredentialTransport {
                 throw error;
             throw new AuthError("credential_store_failed");
         }
-        const grant = grantFrom(method, boundSnapshot(binding, method, committed));
-        if (!grant)
+        const issued = renewal.read(boundSnapshot(binding, method, committed));
+        if (issued === undefined)
+            throw new AuthError("invalid_credentials");
+        return issued;
+    }
+    renew(binding, method, observedRevision, rejected = false) {
+        const auth = method.authentication;
+        if (auth.kind !== "oauth2")
+            throw new AuthError("invalid_definition");
+        return this.commitIssued(binding, method, {
+            field: auth.field,
+            read: (config) => grantFrom(method, config),
+            usable: (previous) => (fresh(previous) && !rejected) ||
+                (!!previous &&
+                    previous.revision !== observedRevision &&
+                    !!previous.tokens.accessToken &&
+                    (previous.tokens.expiresAt === undefined ||
+                        previous.tokens.expiresAt > Date.now())),
+            issue: async (previous) => {
+                const tokens = await this.issue(auth, binding, previous);
+                secret(tokens.accessToken);
+                return { tokens, revision: randomUUID() };
+            },
+        });
+    }
+    /** A role session for the binding's `awsRole`, assumed with the stored key. */
+    renewAwsSession(binding, method, observedRevision) {
+        const auth = method.authentication;
+        if (auth.kind !== "awsSigV4" || !auth.assumeRole)
+            throw new AuthError("invalid_definition");
+        const role = binding.awsRole;
+        if (!role)
             throw new AuthError("invalid_credentials");
-        return grant;
+        return this.commitIssued(binding, method, {
+            field: auth.assumeRole.sessionField,
+            read: (config) => awsSessionFrom(auth, config),
+            usable: (previous) => awsSessionFresh(previous) ||
+                (!!previous &&
+                    previous.revision !== observedRevision &&
+                    previous.expiresAt > Date.now()),
+            issue: async (_previous, config) => ({
+                ...(await assumeAwsRole(awsAccessKey(config[auth.field]), role, {
+                    fetch: this.options.fetch,
+                    timeoutMs: this.options.timeoutMs,
+                })),
+                revision: randomUUID(),
+            }),
+        });
     }
     /** New tokens by the method's declared renewal, from what the binding supplies. */
     issue(auth, binding, previous) {
@@ -376,6 +442,7 @@ export class CredentialTransport {
         let { sign, grant } = await this.authorize(binding, method, input.target);
         const send = async (signer) => {
             const outgoing = {
+                method: verb,
                 headers: new Headers(headers),
                 url: new URL(url),
                 body,
@@ -413,6 +480,7 @@ export class CredentialTransport {
         refuseCredentialParams(url, injectedParams(method.authentication, input.target));
         const { sign } = await this.authorize(binding, method, input.target);
         const outgoing = {
+            method: "GET",
             headers: new Headers(),
             url,
             base: targetBase(target).pathname,
@@ -449,6 +517,18 @@ export class CredentialTransport {
         const auth = method.authentication;
         if (auth.kind === "none")
             return { sign: () => { } };
+        if (auth.kind === "awsSigV4") {
+            const scope = targetOf(method, target)?.aws;
+            if (!scope)
+                throw new AuthError("invalid_definition");
+            if (!auth.assumeRole)
+                return { sign: sigV4(config[auth.field], scope) };
+            const stored = awsSessionFrom(auth, config);
+            const session = stored && awsSessionFresh(stored)
+                ? stored
+                : await this.renewAwsSession(binding, method, stored?.revision);
+            return { sign: sigV4(session, scope) };
+        }
         if (auth.kind === "static")
             return {
                 sign: placeStatic(auth, config[auth.field], target),

package/dist/credentials/types.d.ts

@@ -45,6 +45,16 @@ export interface CredentialTarget {
      * `maxTargetResponseBytes`.
      */
     maxResponseBytes?: number;
+    /**
+     * The AWS service and region a SigV4 method signs this target's requests
+     * for. Every target of an `awsSigV4` method has one; no other target may.
+     */
+    aws?: AwsScope;
+}
+/** The service and region a SigV4 signature is scoped to. */
+export interface AwsScope {
+    service: string;
+    region: string;
 }
 /**
  * Where the transport puts a static secret's parts. Every name it sets is
@@ -129,9 +139,9 @@ 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. `none` signs nothing: the method of a
- * connection that holds no optional credential, still pinned to its
- * targets.
+ * `oauth2`, a revisioned OAuthGrant; for `awsSigV4`, an AWS access key.
+ * `none` signs nothing: the method of a connection that holds no optional
+ * credential, still pinned to its targets.
  */
 export type CredentialAuthentication = {
     kind: "none";
@@ -164,6 +174,22 @@ export type CredentialAuthentication = {
     grant?: string;
     /** Defaults to 401. A 403 must be explicitly documented by the provider. */
     rejectionStatus?: 401 | 403;
+} | {
+    /**
+     * AWS Signature Version 4 with the access key in `field`
+     * (`AwsAccessKeySchema`): a long-lived key, or a session's, with its
+     * token.
+     */
+    kind: "awsSigV4";
+    field: string;
+    /**
+     * Sign with role sessions instead: the key in `field` assumes the
+     * binding's `awsRole` through STS, and the session, renewed before it
+     * expires, is held in `sessionField` (`AwsSessionSchema`).
+     */
+    assumeRole?: {
+        sessionField: string;
+    };
 };
 export interface CredentialProbe {
     target: string;
@@ -187,7 +213,8 @@ export interface CredentialType {
 }
 /**
  * What a connection signs with: the credential type and method, and the
- * OAuth application, JWT identity and resource owner its config supplies.
+ * OAuth application, JWT identity, resource owner and AWS role its config
+ * supplies.
  * Derived from the connection's config alone — never from action input.
  */
 export interface CredentialSelection {
@@ -196,6 +223,8 @@ export interface CredentialSelection {
     application?: OAuthApplication;
     jwtIdentity?: OAuthJwtIdentity;
     resourceOwner?: OAuthResourceOwner;
+    /** The role an `assumeRole` method's sessions are issued for. */
+    awsRole?: AwsRole;
     /**
      * How a process signing with its own flat connection config (the CLI)
      * assembles a static secret: each of its parts, from a named config
@@ -234,6 +263,36 @@ export interface CredentialBinding {
     application?: OAuthApplication;
     jwtIdentity?: OAuthJwtIdentity;
     resourceOwner?: OAuthResourceOwner;
+    awsRole?: AwsRole;
+}
+/**
+ * An IAM role and how its sessions are requested: from the connection's
+ * public config, never from action input.
+ */
+export interface AwsRole {
+    roleArn: string;
+    /** Names the session in CloudTrail; 2-64 of `[\w+=,.@-]`. */
+    sessionName: string;
+    /** The role trust policy's `sts:ExternalId`, when it requires one. */
+    externalId?: string;
+    /** 900 to 43200 seconds, within the role's maximum. STS defaults to 3600. */
+    durationSeconds?: number;
+    /** The region of the STS endpoint the session is requested from. */
+    region: string;
+}
+/** An AWS access key: long-lived, or a session's when it carries a token. */
+export interface AwsAccessKey {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+/** A role session as stored: its key, when it expires, and its issuance. */
+export interface AwsSession extends AwsAccessKey {
+    sessionToken: string;
+    /** Milliseconds since epoch. */
+    expiresAt: number;
+    /** Changes on every issuance. */
+    revision: string;
 }
 /** Revision changes on every issuance, even when the provider repeats the token value. */
 export interface OAuthGrant {

package/dist/index.d.ts

@@ -12,11 +12,17 @@ export type { ActionInvocation, EngineHooks, EngineOptions, ExecuteResult, } fro
 export { ExecutionEngine } from "./core/engine.js";
 export type { BuildAuthUrlOptions, ExchangeCodeOptions, OAuthTokens, PKCEPair, RunOAuthOptions, } from "./core/oauth.js";
 export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_URI, oauthCallback, runOAuth, } from "./core/oauth.js";
+export { awsEndpoint, awsRegion, parseAwsXml } from "./credentials/aws.js";
+export type { AwsCredentialSpec } from "./credentials/aws-plugin.js";
+export { awsCredential, awsFailed, awsJson, awsList, awsQuery, awsTarget, } from "./credentials/aws-plugin.js";
+export { brokerFor } from "./credentials/broker.js";
 export { downloadResource } from "./credentials/http.js";
-export { CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.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 type { AuthenticatedRequest, CredentialBroker, CredentialBrokerCall, CredentialTransportOptions, SocketRequest, } from "./credentials/transport.js";
 export { CredentialTransport } from "./credentials/transport.js";
-export type { CredentialAuthentication, CredentialBinding, CredentialDeclaration, CredentialMethod, CredentialProbe, CredentialProbeResult, CredentialSelection, CredentialTarget, CredentialType, HttpMethod, LocalSecretPart, LocalSecretSource, OAuthGrant, SecretPlacement, } from "./credentials/types.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 { 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

@@ -7,8 +7,12 @@ export { FileConnectionProvider } from "./connections/file.js";
 export { MemoryConnectionProvider } from "./connections/memory.js";
 export { ExecutionEngine } from "./core/engine.js";
 export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_URI, oauthCallback, runOAuth, } from "./core/oauth.js";
+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 } from "./credentials/http.js";
-export { CredentialRegistry, OAuthGrantSchema, OAuthTokensSchema, staticSecretSchema, validateCredential, } from "./credentials/registry.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 { CredentialTransport } from "./credentials/transport.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.js";
 export { installPlugin, listInstalled, parsePluginSource, removePlugin, } from "./plugin/installer.js";