runline 0.34.0 → 0.36.0

package/dist/credentials/broker.js

@@ -0,0 +1,222 @@
+import { createHash } from "node:crypto";
+import { AuthError } from "../auth/errors.js";
+import { CredentialRegistry } from "./registry.js";
+import { CredentialTransport } from "./transport.js";
+/**
+ * Where one action call's authenticated requests go: the host's broker
+ * when it supplies one — the credentials then live with the host, and no
+ * local signer is built — else this process signs with its own
+ * connection, from the plugin's declaration. Plugin-side: the host-side
+ * `credentialBroker` option is what supplies `ctx.credentials`.
+ */
+export function brokerFor(ctx, declaration) {
+    if (ctx.credentials)
+        return ctx.credentials;
+    const { binding, transport } = localSigner(ctx, declaration);
+    return {
+        request: (input) => transport.request(binding, input),
+        probe: () => transport.probe(binding),
+        socketUrl: (input) => transport.socketUrl(binding, input),
+    };
+}
+/**
+ * Everything a stored token was issued under. A config whose selection
+ * hashes differently cannot use tokens issued for this one. A
+ * token of a declared grant was issued under the grant — its method,
+ * client and token endpoint (Microsoft's names the tenant) — not the
+ * plugin that asked, so every plugin of the grant hashes alike and shares
+ * it; any other token is the whole selection's, scopes and targets included.
+ */
+function authorityOf(selection) {
+    const { type, method, application } = selection;
+    const auth = Object.hasOwn(type.methods, method)
+        ? type.methods[method].authentication
+        : undefined;
+    const issuedUnder = auth?.kind === "oauth2" && auth.grant !== undefined
+        ? {
+            grant: auth.grant,
+            method,
+            application,
+            endpoint: auth.definition.refresh,
+        }
+        : selection;
+    return createHash("sha256").update(JSON.stringify(issuedUnder)).digest("hex");
+}
+/**
+ * A stored secret's structured shape (a static secret's parts, or an AWS
+ * access key) from the flat fields and fixed values the declaration
+ * names, joined in order where a part concatenates them. Absent when a
+ * required part's field is missing, so the transport refuses it as
+ * invalid_credentials before any IO; a missing optional part is left out.
+ */
+function staticSecret(current, sources, optional) {
+    if (!sources)
+        return undefined;
+    const secret = {};
+    for (const [key, source] of Object.entries(sources)) {
+        const joined = joinedPart(current, source);
+        if (joined !== undefined)
+            secret[key] = joined;
+        else if (!optional.includes(key))
+            return undefined;
+    }
+    return secret;
+}
+/**
+ * One part of a static secret: its field or fixed value, or the pieces it
+ * concatenates joined in order. Absent when any field it reads is missing
+ * or not a string.
+ */
+function joinedPart(current, source) {
+    let joined = "";
+    for (const part of "concat" in source ? source.concat : [source]) {
+        const value = "value" in part ? part.value : current[part.field];
+        if (typeof value !== "string")
+            return undefined;
+        joined += value;
+    }
+    return joined;
+}
+/**
+ * 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.
+ */
+function writeBack(auth, expected) {
+    if (auth.kind === "awsSigV4" && auth.assumeRole) {
+        const { sessionField } = auth.assumeRole;
+        return (patch) => {
+            const session = patch[sessionField];
+            if (!session?.sessionToken)
+                throw new AuthError("invalid_credentials");
+            return { awsSession: { ...session, binding: expected } };
+        };
+    }
+    if (auth.kind !== "oauth2")
+        throw new AuthError("invalid_definition");
+    return (patch, current) => {
+        const grant = patch[auth.field];
+        if (!grant?.tokens.accessToken)
+            throw new AuthError("invalid_credentials");
+        return {
+            accessToken: grant.tokens.accessToken,
+            accessTokenExpiresAt: grant.tokens.expiresAt,
+            refreshToken: grant.tokens.refreshToken ?? current.refreshToken,
+            authTokenScope: grant.tokens.scope,
+            authTokenType: grant.tokens.tokenType,
+            authTokenRevision: grant.revision,
+            authTokenBinding: expected,
+        };
+    };
+}
+/**
+ * This process signing with its own connection. Flat CLI/env storage is a
+ * projection, not a second token cache or refresh engine.
+ */
+function localSigner(ctx, declaration) {
+    const selection = declaration(ctx.connection.config);
+    const { type: definition, method } = selection;
+    if (!Object.hasOwn(definition.methods, method))
+        throw new AuthError("invalid_definition");
+    const auth = definition.methods[method].authentication;
+    const identity = { name: ctx.connection.name, plugin: ctx.connection.plugin };
+    const expected = authorityOf(selection);
+    const project = (current) => {
+        if (authorityOf(declaration(current)) !== expected)
+            throw new AuthError("binding_changed");
+        if (auth.kind === "none")
+            return {};
+        if (auth.kind === "static") {
+            const secret = staticSecret(current, selection.localSecret, auth.optionalParts ?? []);
+            return secret ? { [auth.field]: secret } : {};
+        }
+        if (auth.kind === "awsSigV4") {
+            const key = staticSecret(current, selection.localSecret, [
+                "sessionToken",
+            ]);
+            const cached = current.awsSession;
+            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,
+                        },
+                    }
+                    : {}),
+            };
+        }
+        const compatible = current.authTokenBinding === undefined ||
+            current.authTokenBinding === expected;
+        const tokens = {
+            ...(compatible && current.accessToken !== undefined
+                ? { accessToken: current.accessToken }
+                : {}),
+            ...(current.refreshToken !== undefined
+                ? { refreshToken: current.refreshToken }
+                : {}),
+            ...(compatible && current.accessTokenExpiresAt !== undefined
+                ? { expiresAt: current.accessTokenExpiresAt }
+                : {}),
+            ...(compatible && current.authTokenScope !== undefined
+                ? { scope: current.authTokenScope }
+                : {}),
+            ...(compatible && current.authTokenType !== undefined
+                ? { tokenType: current.authTokenType }
+                : {}),
+        };
+        if (!Object.keys(tokens).length)
+            return {};
+        const revision = typeof current.authTokenRevision === "string" && compatible
+            ? current.authTokenRevision
+            : createHash("sha256").update(JSON.stringify(tokens)).digest("hex");
+        return { [auth.field]: { tokens, revision } };
+    };
+    const snapshot = () => ({
+        ...identity,
+        config: project(ctx.connection.config),
+    });
+    const binding = {
+        type: definition.id,
+        method,
+        identity,
+        application: selection.application,
+        ...(selection.jwtIdentity ? { jwtIdentity: selection.jwtIdentity } : {}),
+        ...(selection.resourceOwner
+            ? { resourceOwner: selection.resourceOwner }
+            : {}),
+        ...(selection.awsRole ? { awsRole: selection.awsRole } : {}),
+        connection: {
+            async read() {
+                return snapshot();
+            },
+            async update(change) {
+                const flatten = writeBack(auth, expected);
+                await ctx.updateConnection(async (current) => {
+                    const projected = project(current);
+                    const patch = typeof change === "function" ? await change(projected) : change;
+                    return patch ? flatten(patch, current) : undefined;
+                });
+                return snapshot();
+            },
+        },
+    };
+    const registry = new CredentialRegistry();
+    registry.register(definition);
+    // The widest defaults the transport allows, so an undeclared slow call
+    // (image generation, exports) is bounded rather than cut short; targets
+    // that declare their own deadline or ceiling get it up to the host caps.
+    const transport = new CredentialTransport(registry, {
+        fetch: globalThis.fetch,
+        timeoutMs: 120_000,
+        maxRequestBytes: 64 * 1024 * 1024,
+        maxResponseBytes: 64 * 1024 * 1024,
+    });
+    return { binding, transport };
+}

package/dist/credentials/plugin.d.ts

@@ -0,0 +1,255 @@
+/**
+ * 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.
+ */
+import * as t from "typebox";
+import type { ActionContext } from "../plugin/types.js";
+import type { CredentialDeclaration, CredentialProbe, CredentialTarget, HttpMethod, LocalSecretPart, SecretPlacement } from "./types.js";
+/**
+ * The stored shape of an OAuth method: one optional revisioned grant in the
+ * `grant` field, absent until the first issuance.
+ */
+export declare const grantSchema: t.TObject<{
+    grant: t.TOptional<t.TObject<{
+        tokens: t.TObject<{
+            accessToken: t.TOptional<t.TString>;
+            refreshToken: t.TOptional<t.TString>;
+            expiresAt: t.TOptional<t.TInteger>;
+            scope: t.TOptional<t.TString>;
+            tokenType: t.TOptional<t.TString>;
+            metadata: t.TOptional<t.TRecord<"^.*$", t.TString>>;
+        }>;
+        revision: t.TString;
+    }>>;
+}>;
+/**
+ * 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.
+ */
+type LocalSource = string | {
+    value: string;
+} | {
+    concat: LocalSecretPart[];
+};
+/**
+ * How the secret is placed: a shorthand for a common single-secret case,
+ * or the general form of named parts and their placements. The kind names
+ * the method, so a stored selection keeps its method name.
+ */
+type StaticAuth = {
+    kind: "bearer";
+} | {
+    kind: "apiKey";
+    header: string;
+    prefix?: string;
+} | {
+    kind: "queryKey";
+    param: string;
+} | {
+    kind: "basic";
+} | {
+    kind: "static";
+    parts: string[];
+    optionalParts?: string[];
+    placements: SecretPlacement[];
+};
+export interface StaticCredentialSpec {
+    /** Credential type id; one per provider, shared by its plugins. */
+    id: string;
+    auth: StaticAuth;
+    /**
+     * Where a CLI connection keeps each part: `secret` for the single-secret
+     * shorthands, `username` and `password` for basic, and one entry per
+     * part for the general form.
+     */
+    local: Record<string, LocalSource>;
+    /** Fixed targets, or targets built from public config (hosts, account paths). */
+    targets: Record<string, CredentialTarget> | ((config: Readonly<Record<string, unknown>>) => Record<string, CredentialTarget>);
+    probe?: CredentialProbe;
+    /**
+     * The credential is optional: a connection signs when it holds the flat
+     * secret fields (the CLI) or says `authenticated: true` in its public
+     * config (a host that stores the credential), and otherwise sends its
+     * requests unsigned through a `none` method — held to the same targets,
+     * or to targets of its own where the provider serves unsigned requests
+     * elsewhere.
+     */
+    optional?: true | {
+        targets: Record<string, CredentialTarget>;
+    };
+}
+/**
+ * A static-key plugin's declaration. The secret lives in one structured
+ * `credential` field — `{ secret }`, `{ username, password }` for basic, or
+ * the general form's named parts — and the method is named for the auth
+ * kind, so every static declaration has the same shape. A host stores the
+ * structured field; the CLI's flat fields are named by `local`.
+ */
+export declare function staticCredential(spec: StaticCredentialSpec): CredentialDeclaration;
+/**
+ * An HTTPS base URL from public config, with `path` appended beneath it.
+ * Anything else — plain HTTP, embedded credentials, a query or fragment —
+ * is invalid_credentials: the connection cannot be signed as configured.
+ */
+export declare function httpsBase(value: unknown, path: string): string;
+/** One DNS label from public config, for `https://{label}.provider.com/` hosts. */
+export declare function hostLabel(value: unknown): string;
+/**
+ * One of a config field's documented values — a region, an environment,
+ * a hosting mode — or `fallback` when the field is absent. Anything else
+ * is invalid_credentials, never mapped to a default: a mistyped value
+ * would otherwise send the credential to another host.
+ */
+export declare function configChoice<const C extends string>(value: unknown, choices: readonly C[], fallback: C): C;
+/**
+ * A boolean config field, as a boolean or the string a CLI or environment
+ * variable gives (`"true"`, `"false"`); false when absent. Anything else
+ * is invalid_credentials, as for `configChoice`: a mistyped sandbox or
+ * SSL flag must not read as false and reach the live host.
+ */
+export declare function configFlag(value: unknown): boolean;
+/**
+ * An ID or name as exactly one path segment, the one encoder every plugin
+ * uses. A value that is not one segment is refused rather than encoded: an
+ * empty value would address the parent collection (`items/`), a dot segment
+ * a sibling, and a separator more than one segment.
+ */
+export declare function pathSegment(value: unknown): string;
+/**
+ * A slash-separated name the API addresses as a sub-path — a model's
+ * `owner/name`, a file path, a nested job — each segment by `pathSegment`,
+ * its slashes kept.
+ */
+export declare function pathSegments(value: unknown): string;
+/**
+ * A slashed name as exactly one segment, its slashes encoded
+ * (`@scope/pkg` → `%40scope%2Fpkg`), for a target that declares
+ * `encodedSlashes`. An empty or dot piece, or a backslash, is refused.
+ */
+export declare function slashEncodedSegment(value: unknown): string;
+export interface CredentialCall {
+    target: string;
+    /** Relative to the target's base URL; may carry its own query. */
+    path: string;
+    method?: HttpMethod;
+    /** Appended to the path's query. Arrays repeat the key; null and undefined are skipped. */
+    query?: Record<string, unknown>;
+    /** Serialized as the JSON body, with a JSON Content-Type. */
+    json?: unknown;
+    /** Serialized as a form body, by the query's rules, with a form Content-Type. */
+    form?: Record<string, unknown>;
+    body?: string | Uint8Array;
+    headers?: Record<string, string>;
+    /** COPY and MOVE: the destination path beneath the same target. */
+    destination?: string;
+    /**
+     * The provider's deduplication key, for a target that declares
+     * `idempotency`: the transport sets the declared header itself and
+     * refuses the request on any other target or method.
+     */
+    idempotencyKey?: string;
+}
+/** The one authenticated request path: the host's broker, else the local signer. */
+export declare function credentialRequest(ctx: ActionContext, declaration: CredentialDeclaration, call: CredentialCall): Promise<Response>;
+/**
+ * A step that writes a grant into the connection — an owner login run
+ * against the provider — happens only where the grant lives: this process,
+ * signing with its own connection. Under a host that keeps the grant, setup
+ * is the host's, and the step refuses before any request.
+ */
+export declare function refuseUnderHost(ctx: ActionContext): void;
+/**
+ * A socket target's URL for this connection, from the broker: signed by
+ * the local signer, or a relay the host controls. A broker that serves no
+ * sockets refuses as unsupported_operation.
+ */
+export declare function credentialSocketUrl(ctx: ActionContext, declaration: CredentialDeclaration, call: {
+    target: string;
+    path: string;
+    query?: Record<string, unknown>;
+}): Promise<string>;
+/**
+ * A provider error identifier worth handing back — an error code, a field
+ * path — as a plain name. Anything else is not a name and is dropped, so
+ * the code and field slots of a failure never carry free text.
+ */
+export declare function errorIdentifier(value: unknown): string | undefined;
+/**
+ * How a failed request reads: its HTTP status when the status is the
+ * failure, and the identifiers a provider returns for correcting the call
+ * — its error `code` and the offending `param`. No free text from a failed
+ * response reaches it: that is where a provider may echo the credential.
+ */
+export declare function failureMessage(plugin: string, status: number | undefined, detail?: {
+    code?: string;
+    param?: string;
+}): string;
+/**
+ * A successful response whose answer reports failure — Slack's `ok: false`,
+ * an OCS status, a GraphQL `errors` entry — by the provider's code, the
+ * field at fault and its message. The answer is 2xx data the plugin
+ * already holds, so the message stays for the caller to act on, reduced
+ * to one line of at most 300 characters.
+ */
+export declare function answerFailed(plugin: string, detail: {
+    code?: unknown;
+    param?: unknown;
+    message?: unknown;
+}): Error;
+/** A GraphQL answer's `errors`, read by `answerFailed` from the first entry. */
+export declare function graphqlFailed(plugin: string, errors: unknown): Error;
+/** A failed request, reported by status alone. */
+export declare function requestFailed(plugin: string, status: number): Error;
+/** What a provider's error envelope names, before it is reduced to identifiers. */
+export interface ErrorEnvelope {
+    code?: unknown;
+    /** One field path, or several (joined in order). */
+    param?: unknown;
+}
+/**
+ * A failed response by its status and the identifiers its error envelope
+ * names. `read` picks the code and param out of the parsed JSON body, in
+ * the provider's own shape; only what `errorIdentifier` accepts is kept,
+ * so a provider's messages never reach the error. A body that is not JSON
+ * reports the status alone. The status rides on the error for callers
+ * that branch on it.
+ */
+export declare function responseFailed(plugin: string, response: Response, read: (body: unknown) => ErrorEnvelope): Promise<Error & {
+    status: number;
+}>;
+/** A request that must succeed, for callers that read the Response itself (headers, text, bytes). */
+export declare function credentialOk(ctx: ActionContext, declaration: CredentialDeclaration, plugin: string, call: CredentialCall): Promise<Response>;
+/** What a JSON request answers for an empty (or 204) response. */
+export type EmptyAnswer = {
+    success: true;
+};
+/**
+ * A successful response's JSON. `T` is the caller's statement of the
+ * answer's shape, unchecked, as for any parsed JSON; without one it is
+ * `unknown`. An empty answer is `EmptyAnswer`, so a caller whose endpoint
+ * can answer empty includes it in `T`. Every JSON request path reads its
+ * answer here, so they cannot disagree about empty or malformed bodies.
+ */
+export declare function jsonAnswer<T = unknown>(response: Response): Promise<T>;
+/**
+ * A successful response's JSON when its Content-Type says JSON; any other
+ * body — a text "OK", nothing at all — is an acknowledgement,
+ * `EmptyAnswer`. For APIs whose writes answer without JSON.
+ */
+export declare function jsonOrAcknowledged<T = unknown>(response: Response): Promise<T | EmptyAnswer>;
+/** A JSON request that must succeed; its answer is read by `jsonAnswer`. */
+export declare function credentialJson<T = unknown>(ctx: ActionContext, declaration: CredentialDeclaration, plugin: string, call: CredentialCall): Promise<T>;
+/**
+ * A next-page URL the API returned, as a path beneath the declared target
+ * it will be signed for. Anything outside that target's exact origin and
+ * path prefix is refused rather than followed with the credential attached.
+ */
+export declare function pathWithin(ctx: ActionContext, declaration: CredentialDeclaration, target: string, value: string): string;
+/** FormData as the buffered bytes the transport accepts, with its boundary. */
+export declare function multipartBody(form: FormData): Promise<{
+    body: Uint8Array<ArrayBuffer>;
+    contentType: string;
+}>;
+export {};

package/dist/{plugins/_shared/credentials.js → credentials/plugin.js}

@@ -1,12 +1,13 @@
-import { AuthError, OAuthGrantSchema, staticSecretSchema, } from "runline";
-import * as t from "typebox";
-import { credentialBroker } from "./credentialAdapter.js";
 /**
- * The plugin side of the credential broker, shared by every plugin: 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.
+ * 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.
  */
+import * as t from "typebox";
+import { AuthError } from "../auth/errors.js";
+import { brokerFor } from "./broker.js";
+import { 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.
@@ -213,7 +214,7 @@ export function credentialRequest(ctx, declaration, call) {
             }
             : undefined;
     const payload = body?.body ?? call.body;
-    return credentialBroker(ctx, declaration).request({
+    return brokerFor(ctx, declaration).request({
         target: call.target,
         path: withQuery(call.path, call.query),
         method: call.method ?? "GET",
@@ -226,6 +227,9 @@ export function credentialRequest(ctx, declaration, call) {
         ...(call.destination !== undefined
             ? { destination: call.destination }
             : {}),
+        ...(call.idempotencyKey !== undefined
+            ? { idempotencyKey: call.idempotencyKey }
+            : {}),
     });
 }
 /**
@@ -244,7 +248,7 @@ export function refuseUnderHost(ctx) {
  * sockets refuses as unsupported_operation.
  */
 export async function credentialSocketUrl(ctx, declaration, call) {
-    const broker = credentialBroker(ctx, declaration);
+    const broker = brokerFor(ctx, declaration);
     if (!broker.socketUrl)
         throw new AuthError("unsupported_operation");
     return broker.socketUrl({
@@ -265,8 +269,8 @@ export function errorIdentifier(value) {
 /**
  * How a failed request reads: its HTTP status when the status is the
  * failure, and the identifiers a provider returns for correcting the call
- * — its error `code` and the offending `param`. A failed response's body
- * is never read into it: that is where a provider may echo the credential.
+ * — its error `code` and the offending `param`. No free text from a failed
+ * response reaches it: that is where a provider may echo the credential.
  */
 export function failureMessage(plugin, status, detail = {}) {
     const identifiers = [detail.code, detail.param && `param: ${detail.param}`]
@@ -294,7 +298,7 @@ export function answerFailed(plugin, detail) {
         param: identifierOf(detail.param),
     });
     const text = typeof detail.message === "string"
-        ? detail.message.replace(/[\u0000-\u001f\u007f\s]+/g, " ").trim()
+        ? detail.message.replace(/[\p{Cc}\s]+/gu, " ").trim()
         : "";
     const line = text.length > 300 ? `${text.slice(0, 300)}…` : text;
     return new Error(line ? `${head}: ${line}` : head);
@@ -312,6 +316,30 @@ export function graphqlFailed(plugin, errors) {
 export function requestFailed(plugin, status) {
     return new Error(failureMessage(plugin, status));
 }
+/**
+ * A failed response by its status and the identifiers its error envelope
+ * names. `read` picks the code and param out of the parsed JSON body, in
+ * the provider's own shape; only what `errorIdentifier` accepts is kept,
+ * so a provider's messages never reach the error. A body that is not JSON
+ * reports the status alone. The status rides on the error for callers
+ * that branch on it.
+ */
+export async function responseFailed(plugin, response, read) {
+    let envelope = {};
+    try {
+        envelope = read(JSON.parse(await response.text()));
+    }
+    catch {
+        envelope = {};
+    }
+    const params = (Array.isArray(envelope.param) ? envelope.param : [envelope.param])
+        .map(identifierOf)
+        .filter((param) => param !== undefined);
+    return Object.assign(new Error(failureMessage(plugin, response.status, {
+        code: identifierOf(envelope.code),
+        param: params.length ? params.join(", ") : undefined,
+    })), { status: response.status });
+}
 /** A request that must succeed, for callers that read the Response itself (headers, text, bytes). */
 export async function credentialOk(ctx, declaration, plugin, call) {
     const response = await credentialRequest(ctx, declaration, call);

package/dist/credentials/policy.d.ts

@@ -9,6 +9,12 @@ export declare const TRANSPORT_HEADERS: readonly string[];
 /** The most any target may declare, and any host may allow, per request. */
 export declare const TARGET_TIMEOUT_LIMIT_MS: number;
 export declare const TARGET_RESPONSE_LIMIT_BYTES: number;
+/**
+ * A secret sent exactly as it is (a token in a header, a key in a query,
+ * a signature's credential): printable ASCII with no whitespace. Anything
+ * else is refused as invalid_credentials before it reaches a request.
+ */
+export declare function secret(value: unknown): string;
 /** A positive integer no larger than `limit`. */
 export declare function bounded(value: unknown, limit: number): boolean;
 export declare function headerName(name: string): string;
@@ -22,9 +28,11 @@ export declare function placementsFor(auth: Extract<CredentialAuthentication, {
 /** Headers a method's authentication sets on `target`, lowercased; callers never set them. */
 export declare function injectedHeaders(auth: CredentialAuthentication, target: string): string[];
 /**
- * Query parameters a method's authentication sets on `target`, a body
- * part's included (it reaches the query when a request has no body);
- * callers never set them.
+ * Query parameters a method's authentication owns on `target`, so callers
+ * never set them: the parameters a static method places, a body part's
+ * included (it reaches the query when a request has no body), and for
+ * SigV4 those of a presigned URL, which a header-signed request never
+ * carries.
  */
 export declare function injectedParams(auth: CredentialAuthentication, target: string): string[];
 /** Body fields a method's authentication sets on `target`; callers never set them. */

package/dist/credentials/policy.js

@@ -1,4 +1,5 @@
 import { AuthError } from "../auth/errors.js";
+import { SIGV4_HEADERS, SIGV4_QUERY_PARAMETERS } from "./sigv4.js";
 export const HTTP_METHODS = [
     "GET",
     "HEAD",
@@ -22,6 +23,18 @@ export const TRANSPORT_HEADERS = [
 /** The most any target may declare, and any host may allow, per request. */
 export const TARGET_TIMEOUT_LIMIT_MS = 60 * 60_000;
 export const TARGET_RESPONSE_LIMIT_BYTES = 1024 * 1024 * 1024;
+/**
+ * A secret sent exactly as it is (a token in a header, a key in a query,
+ * a signature's credential): printable ASCII with no whitespace. Anything
+ * else is refused as invalid_credentials before it reaches a request.
+ */
+export 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 positive integer no larger than `limit`. */
 export function bounded(value, limit) {
     return (Number.isSafeInteger(value) &&
@@ -104,6 +117,8 @@ export function injectedHeaders(auth, target) {
         return [];
     if (auth.kind === "oauth2")
         return ["authorization"];
+    if (auth.kind === "awsSigV4")
+        return [...SIGV4_HEADERS];
     return placementsFor(auth, target).flatMap((placement) => placement.in === "header" ||
         placement.in === "jwt" ||
         placement.in === "querySignature"
@@ -113,11 +128,15 @@ export function injectedHeaders(auth, target) {
             : []);
 }
 /**
- * Query parameters a method's authentication sets on `target`, a body
- * part's included (it reaches the query when a request has no body);
- * callers never set them.
+ * Query parameters a method's authentication owns on `target`, so callers
+ * never set them: the parameters a static method places, a body part's
+ * included (it reaches the query when a request has no body), and for
+ * SigV4 those of a presigned URL, which a header-signed request never
+ * carries.
  */
 export function injectedParams(auth, target) {
+    if (auth.kind === "awsSigV4")
+        return [...SIGV4_QUERY_PARAMETERS];
     if (auth.kind !== "static")
         return [];
     return placementsFor(auth, target).flatMap((placement) => placement.in === "query" || placement.in === "body" ? [placement.name] : []);

package/dist/credentials/registry.d.ts

@@ -29,6 +29,20 @@ export declare const OAuthGrantSchema: t.TObject<{
     }>;
     revision: t.TString;
 }>;
+/** Stored shape of an AWS access key; a session's carries its token. */
+export declare const AwsAccessKeySchema: t.TObject<{
+    accessKeyId: t.TString;
+    secretAccessKey: t.TString;
+    sessionToken: t.TOptional<t.TString>;
+}>;
+/** Stored shape of an assumed role's session. */
+export declare const AwsSessionSchema: t.TObject<{
+    accessKeyId: t.TString;
+    secretAccessKey: t.TString;
+    sessionToken: t.TString;
+    expiresAt: t.TInteger;
+    revision: t.TString;
+}>;
 /** No implicit defaults, provider inference, executable expressions, or replacement. */
 export declare class CredentialRegistry {
     private readonly types;