@intentius/chant-lexicon-aws 0.124.30 → 0.124.32

package/dist/api/read-client.js

@@ -0,0 +1,458 @@
+/**
+ * The native AWS read transport (#1206) — the read half of what
+ * `op/activities/aws-apply.ts` already does for writes.
+ *
+ * Every AWS observer shelled `aws …` once per entity, serially, and parsed
+ * stderr to find out what went wrong (#1085). The applier does not: `awsApply`
+ * speaks the CloudFormation Query protocol over `fetch`, honours an endpoint
+ * override, and is injectable for tests. This module is that same transport
+ * pointed at the two APIs the read path needs:
+ *
+ *   - **CloudFormation Query** (form-encoded POST, XML back) — the stack reads
+ *     `describeResources` and the deep pass both start from.
+ *   - **Cloud Control** (AWS JSON 1.0, `X-Amz-Target: CloudApiService.*`) — the
+ *     property-level reads (#1015).
+ *
+ * Both take the endpoint the same way the applier does, so `chant emulator` /
+ * behold `--local` keep working by construction rather than by each observer
+ * remembering to inject `--endpoint-url`.
+ *
+ * ## Signing
+ *
+ * Requests are signed with SigV4 (#1686) when credentials resolve — see
+ * `./sigv4.ts`, which holds the implementation so that cedar's AVP client can
+ * adopt the same one rather than growing a second. With none injected, they
+ * resolve through the AWS CLI's chain (`./credential-chain.ts`, the one
+ * `chant lifecycle whoami` walks) once per process, by
+ * {@link withChainCredentials} (#3958). Two cases stay unsigned, and both are
+ * deliberate:
+ *
+ *   - **No credentials.** The caller's existing no-credentials path is
+ *     untouched: the request still goes out carrying only the credential scope
+ *     of {@link regionScope}, which is what the emulator lanes have always
+ *     sent.
+ *   - **An endpoint override.** Floci does not verify signatures, and signing
+ *     against it would mean every local lane suddenly needs credentials to read
+ *     what it just deployed. `signEndpointOverride` opts back in for an
+ *     override that *is* real AWS — a VPC endpoint, a signing proxy.
+ *
+ * What counts as an override is one rule, {@link resolveEndpointOverride}: the
+ * `endpoint` option, else the ambient `AWS_ENDPOINT_URL_<SERVICE>` the AWS SDK
+ * honours per service, else `AWS_ENDPOINT_URL` (#1694). Cedar's AVP client
+ * (`lexicons/cedar/src/avp/client.ts`) applies the same rule; it restates it
+ * rather than importing it, because cedar does not depend on this lexicon and
+ * a lexicon build compiles against the published core, so a helper hoisted
+ * into core would not be visible to either until the next core release.
+ */
+import { homedir } from "node:os";
+import { transportCredentials } from "./credential-chain.js";
+import { resolveCredentials, signRequest } from "./sigv4.js";
+const DEFAULT_REGION = "us-east-1";
+const CFN_API_VERSION = "2010-05-15";
+const CLOUD_CONTROL_TARGET_PREFIX = "CloudApiService";
+const defaultHttp = async (url, init, signal) => {
+    const res = await fetch(url, { method: "POST", headers: init.headers, body: init.body, signal });
+    return { status: res.status, text: await res.text() };
+};
+/** A failed read, carrying enough to classify it without parsing prose. */
+export class AwsReadError extends Error {
+    constructor(message, status, 
+    /** The API's own error code (`ValidationError`, `UnsupportedOperation`, …) when it sent one. */
+    code) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "AwsReadError";
+    }
+}
+/**
+ * The SDK's per-service endpoint variable for a signing-service name:
+ * `AWS_ENDPOINT_URL_<SERVICE ID>`, the service id upper-cased with every
+ * non-alphanumeric run replaced by `_`. The SDK keys that by the service id of
+ * its model, which is the signing name for every service here except Cloud
+ * Control (`cloudcontrolapi` signs, `CloudControl` is the id).
+ */
+const ENV_SERVICE_ID = { cloudcontrolapi: "cloudcontrol" };
+/** The name of the service-specific endpoint variable the AWS SDK reads for `service`. */
+export function serviceEndpointEnvVar(service) {
+    const id = ENV_SERVICE_ID[service] ?? service;
+    return `AWS_ENDPOINT_URL_${id.toUpperCase().replace(/[^A-Z0-9]+/g, "_")}`;
+}
+/**
+ * The one rule for what an endpoint override is (#1694): the `endpoint` option
+ * when given, else the service-specific `AWS_ENDPOINT_URL_<SERVICE>`, else the
+ * ambient `AWS_ENDPOINT_URL` — the same precedence the AWS SDK applies. The
+ * result is the target the request goes to and, through {@link requestHeaders},
+ * the fact that decides whether it is signed. Returns `undefined` for real AWS.
+ */
+export function resolveEndpointOverride(service, endpoint, env = process.env) {
+    return endpoint || env[serviceEndpointEnvVar(service)] || env.AWS_ENDPOINT_URL || undefined;
+}
+/**
+ * `options` with its endpoint settled by {@link resolveEndpointOverride}, so
+ * the URL builder and the signing decision read the same answer.
+ */
+export function withEndpointOverride(service, options) {
+    const endpoint = resolveEndpointOverride(service, options.endpoint, options.env ?? process.env);
+    return endpoint ? { ...options, endpoint } : options;
+}
+/** Service host for `service`, honouring an endpoint override. */
+export function serviceUrl(service, endpoint, region = DEFAULT_REGION) {
+    return `${(endpoint ?? `https://${service}.${region}.amazonaws.com`).replace(/\/$/, "")}/`;
+}
+/**
+ * How the request says which region it is for.
+ *
+ * Against real AWS the region is the hostname, which is why `serviceUrl` takes
+ * it. Against an endpoint override there is only one host for every region, so
+ * the hostname carries nothing and the region has to travel in the request —
+ * and every emulator reads it where a real SDK puts it, in the credential scope
+ * of the `Authorization` header.
+ *
+ * Without this, a stack observed with `region: "us-west-1"` was read against
+ * whatever region the emulator defaults to. The result is not an error: the
+ * stack genuinely does not exist in us-east-1, so `describeResources` returned
+ * an empty observation and the snapshot recorded the region as holding nothing.
+ * A three-region estate snapshotted as one region and nothing said so.
+ *
+ * This is NOT SigV4. The signature is a placeholder and real AWS rejects it. It
+ * is what an unsigned request still has to carry so an emulator learns the
+ * region, and it is only ever sent when no credentials resolved — the moment
+ * they do, {@link requestHeaders} sends a real signature instead.
+ */
+function regionScope(service, region, env) {
+    if (!region)
+        return {};
+    const day = new Date().toISOString().slice(0, 10).replace(/-/g, "");
+    const key = env.AWS_ACCESS_KEY_ID || "chant";
+    return {
+        authorization: `AWS4-HMAC-SHA256 Credential=${key}/${day}/${region}/${service}/aws4_request, ` +
+            "SignedHeaders=host, Signature=unsigned",
+    };
+}
+/**
+ * The headers one request goes out with — signed when there is something to
+ * sign with and the target is real AWS, scope-only otherwise.
+ *
+ * Signing needs a region even when the caller named none, because the scope
+ * string has a slot for one; it borrows the same `us-east-1` default that
+ * {@link serviceUrl} already used to build the host, so the signature agrees
+ * with the endpoint it is sent to.
+ *
+ * Exported because this decision — sign, or carry the scope and no signature —
+ * belongs to the lexicon's read transport rather than to any one API on it.
+ * `agentcore/trace-fetch.ts` reads `bedrock-agentcore` through the same seam,
+ * and a second copy of this would be a second place for the emulator carve-out
+ * to drift.
+ *
+ * Callers pass options already settled by {@link withEndpointOverride}, so an
+ * override the environment named is skipped exactly like one the option did.
+ */
+export function requestHeaders(service, url, body, base, options) {
+    const env = options.env ?? process.env;
+    const credentials = resolveCredentials(options.credentials, env);
+    const signable = credentials && (!options.endpoint || options.signEndpointOverride === true);
+    if (!signable)
+        return { ...base, ...regionScope(service, options.region, env) };
+    return signRequest({
+        method: "POST",
+        url,
+        headers: base,
+        body,
+        service,
+        region: options.region ?? DEFAULT_REGION,
+        credentials,
+        ...(options.now ? { now: options.now } : {}),
+    });
+}
+/**
+ * `options` with literal credentials from the AWS CLI's credential chain
+ * (#3958), when the caller injected none and the request will be signed.
+ *
+ * Every request function awaits this after {@link withEndpointOverride} and
+ * before {@link requestHeaders}, whose seam is synchronous. The chain is not
+ * walked against an endpoint override that is not signed: an emulator read
+ * should not start an SSO refresh or a `credential_process`, the same rule
+ * whoami follows. When nothing resolves the options come back unchanged and
+ * the request goes out unsigned, as it did before.
+ *
+ * An injected `env` without `HOME`, `USERPROFILE`, `AWS_CONFIG_FILE` or
+ * `AWS_SHARED_CREDENTIALS_FILE` names no shared files, so only its keys are
+ * read; the process's own `~/.aws` is not consulted behind it.
+ */
+export async function withChainCredentials(options) {
+    if (options.credentials)
+        return options;
+    if (options.endpoint && options.signEndpointOverride !== true)
+        return options;
+    const env = options.env ?? process.env;
+    const home = env.HOME || env.USERPROFILE;
+    if (options.env && options.env !== process.env && !home && !env.AWS_CONFIG_FILE && !env.AWS_SHARED_CREDENTIALS_FILE) {
+        return options;
+    }
+    const credentials = await transportCredentials({
+        env,
+        home: home || homedir(),
+        sts: { ...(options.http ? { http: options.http } : {}), env },
+    });
+    return credentials ? { ...options, credentials } : options;
+}
+/* ── CloudFormation Query ─────────────────────────────────────────────────── */
+/**
+ * The `<Tag>text</Tag>` pairs of one XML fragment, as a flat record. Repeated
+ * tags keep the first occurrence, which is what a `<member>` body wants —
+ * nested lists inside a member are not modelled, because nothing the read path
+ * needs from `DescribeStackResources` / `DescribeStacks` is nested that deep.
+ */
+export function xmlLeaves(fragment) {
+    const out = {};
+    for (const m of fragment.matchAll(/<([A-Za-z0-9]+)>([^<]*)<\/\1>/g)) {
+        const [, tag, value] = m;
+        if (tag && !(tag in out))
+            out[tag] = decodeXmlEntities(value ?? "");
+    }
+    return out;
+}
+/** The five predefined XML entities. Query responses carry them in ARNs and policy text. */
+function decodeXmlEntities(value) {
+    return value
+        .replace(/&lt;/g, "<")
+        .replace(/&gt;/g, ">")
+        .replace(/&quot;/g, '"')
+        .replace(/&apos;/g, "'")
+        .replace(/&amp;/g, "&");
+}
+/**
+ * Every `<member>…</member>` under `listTag`, each flattened by
+ * {@link xmlLeaves}. The Query protocol renders a list as repeated `<member>`
+ * elements, and `xmlField` in the applier deliberately does not handle them —
+ * it was written for scalar status fields.
+ */
+export function xmlMembers(xml, listTag) {
+    const list = xml.match(new RegExp(`<${listTag}>([\\s\\S]*?)</${listTag}>`))?.[1];
+    if (!list)
+        return [];
+    return [...list.matchAll(/<member>([\s\S]*?)<\/member>/g)].map((m) => xmlLeaves(m[1] ?? ""));
+}
+/** `<Error><Code>…</Code><Message>…</Message></Error>`, when the response carries one. */
+export function xmlError(xml) {
+    if (!/<Error>/.test(xml))
+        return undefined;
+    const leaves = xmlLeaves(xml.match(/<Error>([\s\S]*?)<\/Error>/)?.[1] ?? "");
+    return { code: leaves.Code, message: leaves.Message };
+}
+/**
+ * One CloudFormation Query call. Returns the raw XML; throws
+ * {@link AwsReadError} for a non-2xx or an `<Error>` body, so a caller
+ * classifies a typed failure instead of matching on stderr.
+ */
+export async function cfnQuery(action, params, options = {}) {
+    options = await withChainCredentials(withEndpointOverride("cloudformation", options));
+    const http = options.http ?? defaultHttp;
+    const url = serviceUrl("cloudformation", options.endpoint, options.region);
+    const body = new URLSearchParams({ Action: action, Version: CFN_API_VERSION, ...params }).toString();
+    const res = await http(url, {
+        headers: requestHeaders("cloudformation", url, body, { "content-type": "application/x-www-form-urlencoded" }, options),
+        body,
+    }, options.signal);
+    const err = xmlError(res.text);
+    if (err || res.status >= 400) {
+        throw new AwsReadError(err?.message ?? `${action} failed with HTTP ${res.status}`, res.status, err?.code);
+    }
+    return res.text;
+}
+/** `DescribeStackResources` for one stack, mapped off the Query XML. */
+export async function describeStackResources(stackName, options = {}) {
+    const xml = await cfnQuery("DescribeStackResources", { StackName: stackName }, options);
+    return xmlMembers(xml, "StackResources").map((m) => ({
+        logicalId: m.LogicalResourceId ?? "",
+        type: m.ResourceType ?? "",
+        ...(m.PhysicalResourceId ? { physicalId: m.PhysicalResourceId } : {}),
+        ...(m.ResourceStatus ? { status: m.ResourceStatus } : {}),
+        ...(m.Timestamp ? { timestamp: m.Timestamp } : {}),
+    }));
+}
+/**
+ * `DescribeStacks` for one stack, outputs and tags off the same response. The
+ * two ride together because they come from one call: reading the ownership
+ * marker on the observation path (#1998) costs no extra round trip.
+ */
+export async function describeStackDetail(stackName, options = {}) {
+    const xml = await cfnQuery("DescribeStacks", { StackName: stackName }, options);
+    const outputs = {};
+    for (const m of xmlMembers(xml, "Outputs")) {
+        if (m.OutputKey)
+            outputs[m.OutputKey] = m.OutputValue ?? "";
+    }
+    const tags = {};
+    for (const m of xmlMembers(xml, "Tags")) {
+        if (m.Key)
+            tags[m.Key] = m.Value ?? "";
+    }
+    return { outputs, tags };
+}
+/** `DescribeStacks` outputs for one stack, as `key → value`. */
+export async function describeStackOutputs(stackName, options = {}) {
+    return (await describeStackDetail(stackName, options)).outputs;
+}
+/* ── STS ──────────────────────────────────────────────────────────────────── */
+const STS_API_VERSION = "2011-06-15";
+/**
+ * `sts:GetCallerIdentity` — who these credentials are, per the service itself
+ * (#1982). Query protocol like CloudFormation, so it rides the same transport,
+ * the same endpoint-override rule and the same signing decision as every other
+ * read, which is what keeps `chant lifecycle whoami` and `describeResources`
+ * from resolving different targets.
+ *
+ * The response carries an ARN, an account and a `UserId`. Only the first two
+ * are returned: `UserId` adds nothing a principal ARN does not already say,
+ * and the narrower the surface, the fewer ways a credential reaches a report.
+ */
+export async function getCallerIdentity(options = {}) {
+    options = await withChainCredentials(withEndpointOverride("sts", options));
+    const http = options.http ?? defaultHttp;
+    const url = serviceUrl("sts", options.endpoint, options.region);
+    const body = new URLSearchParams({ Action: "GetCallerIdentity", Version: STS_API_VERSION }).toString();
+    const res = await http(url, {
+        headers: requestHeaders("sts", url, body, { "content-type": "application/x-www-form-urlencoded" }, options),
+        body,
+    }, options.signal);
+    const err = xmlError(res.text);
+    if (err || res.status >= 400) {
+        throw new AwsReadError(err?.message ?? `GetCallerIdentity failed with HTTP ${res.status}`, res.status, err?.code);
+    }
+    const leaves = xmlLeaves(res.text);
+    return { arn: leaves.Arn ?? "", account: leaves.Account ?? "" };
+}
+/**
+ * `sts:AssumeRole` — the call behind a shared-config profile with `role_arn`
+ * (#3954). Signed with the source credentials the caller passes in
+ * `options.credentials`, on the same Query transport as
+ * {@link getCallerIdentity}. The response is credential material, so it goes
+ * back to the caller and never into an error message.
+ */
+export async function assumeRole(params, options = {}) {
+    options = await withChainCredentials(withEndpointOverride("sts", options));
+    const http = options.http ?? defaultHttp;
+    const url = serviceUrl("sts", options.endpoint, options.region);
+    const body = new URLSearchParams({
+        Action: "AssumeRole",
+        Version: STS_API_VERSION,
+        RoleArn: params.roleArn,
+        RoleSessionName: params.sessionName,
+        ...(params.externalId ? { ExternalId: params.externalId } : {}),
+        ...(params.durationSeconds ? { DurationSeconds: String(params.durationSeconds) } : {}),
+    }).toString();
+    const res = await http(url, {
+        headers: requestHeaders("sts", url, body, { "content-type": "application/x-www-form-urlencoded" }, options),
+        body,
+    }, options.signal);
+    const err = xmlError(res.text);
+    if (err || res.status >= 400) {
+        throw new AwsReadError(err?.message ?? `AssumeRole failed with HTTP ${res.status}`, res.status, err?.code);
+    }
+    const leaves = xmlLeaves(res.text.match(/<Credentials>([\s\S]*?)<\/Credentials>/)?.[1] ?? "");
+    if (!leaves.AccessKeyId || !leaves.SecretAccessKey || !leaves.SessionToken) {
+        throw new AwsReadError("AssumeRole answered without credentials", res.status);
+    }
+    return {
+        accessKeyId: leaves.AccessKeyId,
+        secretAccessKey: leaves.SecretAccessKey,
+        sessionToken: leaves.SessionToken,
+        ...(leaves.Expiration ? { expiration: leaves.Expiration } : {}),
+    };
+}
+/**
+ * One Cloud Control call (AWS JSON 1.0). Throws {@link AwsReadError} carrying
+ * the service's `__type` so `UnsupportedOperation` — what Floci answers for
+ * `GetResource` — stays distinguishable from a credential or a genuine miss.
+ */
+async function cloudControl(operation, payload, options = {}) {
+    options = await withChainCredentials(withEndpointOverride("cloudcontrolapi", options));
+    const http = options.http ?? defaultHttp;
+    const url = serviceUrl("cloudcontrolapi", options.endpoint, options.region);
+    const payloadJson = JSON.stringify(payload);
+    const res = await http(url, {
+        headers: requestHeaders("cloudcontrolapi", url, payloadJson, {
+            "content-type": "application/x-amz-json-1.0",
+            "x-amz-target": `${CLOUD_CONTROL_TARGET_PREFIX}.${operation}`,
+        }, options),
+        body: payloadJson,
+    }, options.signal);
+    let parsed;
+    try {
+        parsed = JSON.parse(res.text);
+    }
+    catch {
+        throw new AwsReadError(`unparseable ${operation} response`, res.status);
+    }
+    const body = isRecord(parsed) ? parsed : {};
+    const type = typeof body.__type === "string" ? body.__type.split("#").pop() : undefined;
+    if (type || res.status >= 400) {
+        const message = typeof body.message === "string" ? body.message : `${operation} failed with HTTP ${res.status}`;
+        throw new AwsReadError(message, res.status, type);
+    }
+    return body;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * Cloud Control returns a resource model as a JSON *string* inside the
+ * envelope, so every description unwraps twice. Returns null when either level
+ * does not parse to an object — an unparseable body is a failed read, not an
+ * empty resource.
+ */
+export function parseResourceDescription(raw) {
+    if (!isRecord(raw))
+        return null;
+    const properties = typeof raw.Properties === "string" ? safeParseObject(raw.Properties) : undefined;
+    if (!properties)
+        return null;
+    return {
+        identifier: typeof raw.Identifier === "string" ? raw.Identifier : "",
+        properties,
+    };
+}
+function safeParseObject(text) {
+    try {
+        const parsed = JSON.parse(text);
+        return isRecord(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `GetResource` — the full live model for one identifier. */
+export async function getResource(typeName, identifier, options = {}) {
+    const body = await cloudControl("GetResource", { TypeName: typeName, Identifier: identifier }, options);
+    return parseResourceDescription(body.ResourceDescription);
+}
+/**
+ * `ListResources` — every live resource of one type, paginated to exhaustion.
+ *
+ * `resourceModel` is Cloud Control's `ResourceModel`: the scope a child-typed
+ * listing requires (`{ RoleName }` for `AWS::IAM::RolePolicy`,
+ * `{ TopicArn }` for `AWS::SNS::Subscription`). The API takes it as a JSON
+ * *string*, the same double encoding `GetResource` answers with; this takes
+ * the object and encodes it so no caller repeats that detail.
+ */
+export async function listResources(typeName, options = {}, resourceModel) {
+    const out = [];
+    let nextToken;
+    do {
+        const body = await cloudControl("ListResources", {
+            TypeName: typeName,
+            ...(resourceModel ? { ResourceModel: JSON.stringify(resourceModel) } : {}),
+            ...(nextToken ? { NextToken: nextToken } : {}),
+        }, options);
+        const descriptions = Array.isArray(body.ResourceDescriptions) ? body.ResourceDescriptions : [];
+        for (const d of descriptions) {
+            const parsed = parseResourceDescription(d);
+            if (parsed)
+                out.push(parsed);
+        }
+        nextToken = typeof body.NextToken === "string" && body.NextToken.length > 0 ? body.NextToken : undefined;
+    } while (nextToken);
+    return out;
+}

package/dist/api/sigv4.d.ts

@@ -25,10 +25,10 @@ export type AwsCredentialSource = AwsCredentials | AwsCredentialResolver;
  * environment — a key id with no secret — is absent rather than a signature
  * that cannot verify.
  *
- * Deliberately not implemented: the profile file, IMDS, and the container
- * credential endpoints. Each is a separate transport with its own failure and
- * caching story; a caller that has those can resolve them itself and pass the
- * result in, which is what the resolver seam is for.
+ * The shared profile files are resolved asynchronously by
+ * `./credential-chain.ts`, and the read transport passes its answer in as
+ * literal credentials (#3958), so this function stays synchronous. Not
+ * implemented anywhere: IMDS and the container credential endpoints.
  */
 export declare function resolveCredentials(source?: AwsCredentialSource, env?: Record<string, string | undefined>): AwsCredentials | undefined;
 /** One request to sign. `headers` are the caller's; the signer adds its own. */

package/dist/api/sigv4.js

@@ -0,0 +1,185 @@
+/**
+ * AWS Signature Version 4, for the shared read transport (#1686).
+ *
+ * Two modules asked for this by name before it existed: `./read-client.ts` and
+ * cedar's `lexicons/cedar/src/avp/client.ts` both send a placeholder
+ * `Signature=unsigned` `Authorization` header that carries a credential scope
+ * and nothing else, and both say in prose that the real thing belongs here
+ * once rather than twice. Nothing else in the repo signs an AWS request — the
+ * appliers (`op/activities/aws-apply.ts`) are unsigned too, which is why the
+ * native paths have been emulator-scoped.
+ *
+ * ## No dependency
+ *
+ * SigV4 is four HMACs and two SHA-256s. `node:crypto` has both, so signing
+ * costs nothing in the dependency tree — which matters here, because the whole
+ * reason these transports are hand-written is to keep `@aws-sdk/*` and its
+ * thirty-odd transitive packages out of a lexicon.
+ *
+ * ## What is signed, and what is not
+ *
+ * Header signing only. Query-string (presigned-URL) signing has no caller: the
+ * read paths POST to a service endpoint, they do not hand out URLs.
+ *
+ * `host` is signed but never emitted. `fetch` computes `Host` from the URL and
+ * forbids overriding it, so the signer derives the same value from the URL it
+ * was given. A transport that rewrites the URL underneath the signer — a proxy
+ * that keeps the original `Host`, say — would invalidate the signature; the
+ * injectable-HTTP seam is for tests and emulators, not for URL rewriting.
+ */
+import { createHash, createHmac } from "node:crypto";
+const ALGORITHM = "AWS4-HMAC-SHA256";
+const TERMINATOR = "aws4_request";
+/** SHA-256 of the empty string — the payload hash of every bodyless request. */
+export const EMPTY_PAYLOAD_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
+/**
+ * Headers that must not be signed even when a caller sets them: `authorization`
+ * is the output, and the others are rewritten in transit by proxies and agents,
+ * so signing them produces intermittent 403s rather than security.
+ */
+const UNSIGNABLE = new Set(["authorization", "connection", "expect", "user-agent", "x-amzn-trace-id"]);
+/**
+ * Credentials for a request: explicit → environment → absent.
+ *
+ * A resolver function is authoritative — if one is injected and it declines,
+ * the environment is not consulted behind its back, because the point of
+ * injecting one is to control the answer. Literal credentials are likewise
+ * final. Only the no-source case falls through to `AWS_ACCESS_KEY_ID` /
+ * `AWS_SECRET_ACCESS_KEY` (plus `AWS_SESSION_TOKEN` when set), and a half-set
+ * environment — a key id with no secret — is absent rather than a signature
+ * that cannot verify.
+ *
+ * The shared profile files are resolved asynchronously by
+ * `./credential-chain.ts`, and the read transport passes its answer in as
+ * literal credentials (#3958), so this function stays synchronous. Not
+ * implemented anywhere: IMDS and the container credential endpoints.
+ */
+export function resolveCredentials(source, env = process.env) {
+    if (typeof source === "function")
+        return source();
+    if (source)
+        return source;
+    const accessKeyId = env.AWS_ACCESS_KEY_ID;
+    const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
+    if (!accessKeyId || !secretAccessKey)
+        return undefined;
+    return {
+        accessKeyId,
+        secretAccessKey,
+        ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}),
+    };
+}
+/** `YYYYMMDDTHHMMSSZ` — the `X-Amz-Date` format, which is ISO-8601 basic. */
+export function amzDate(date) {
+    return date.toISOString().replace(/[:-]|\.\d{3}/g, "");
+}
+/** Lowercase hex SHA-256. */
+export function sha256Hex(payload) {
+    return createHash("sha256").update(payload, "utf8").digest("hex");
+}
+function hmac(key, data) {
+    return createHmac("sha256", key).update(data, "utf8").digest();
+}
+/**
+ * The signing key: four chained HMACs from the secret, so the key on the wire
+ * is scoped to one day, one region and one service rather than being the
+ * account secret itself.
+ */
+export function signingKey(secretAccessKey, day, region, service) {
+    const dateKey = hmac(`AWS4${secretAccessKey}`, day);
+    const regionKey = hmac(dateKey, region);
+    const serviceKey = hmac(regionKey, service);
+    return hmac(serviceKey, TERMINATOR);
+}
+/**
+ * RFC 3986 percent-encoding. `encodeURIComponent` leaves `!'()*` alone and AWS
+ * does not, which is the difference between a signature that verifies and one
+ * that does not for any path or parameter containing them.
+ */
+function encodeRfc3986(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+/**
+ * The canonical path.
+ *
+ * Every caller of this module POSTs to `/`, so the one place implementations
+ * genuinely diverge — S3 signs the path once-encoded, every other service signs
+ * it twice-encoded — never arises. Segments are encoded once; a future caller
+ * with a real path on a non-S3 service is the moment to revisit that.
+ */
+function canonicalPath(pathname) {
+    if (!pathname || pathname === "/")
+        return "/";
+    return pathname.split("/").map(encodeRfc3986).join("/");
+}
+/** Query parameters sorted by name, then by value, each side encoded. */
+function canonicalQuery(search) {
+    const pairs = [];
+    search.forEach((value, name) => pairs.push([encodeRfc3986(name), encodeRfc3986(value)]));
+    pairs.sort((a, b) => (a[0] === b[0] ? (a[1] < b[1] ? -1 : a[1] > b[1] ? 1 : 0) : a[0] < b[0] ? -1 : 1));
+    return pairs.map(([name, value]) => `${name}=${value}`).join("&");
+}
+/**
+ * Header names lowercased, values trimmed with internal whitespace runs
+ * collapsed, sorted by name. Returns the canonical block and the `;`-joined
+ * signed-header list that has to agree with it exactly.
+ */
+export function canonicalHeaders(headers) {
+    const entries = Object.entries(headers)
+        .map(([name, value]) => [name.toLowerCase().trim(), value.trim().replace(/\s+/g, " ")])
+        .filter(([name]) => !UNSIGNABLE.has(name))
+        .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    return {
+        canonical: entries.map(([name, value]) => `${name}:${value}\n`).join(""),
+        signed: entries.map(([name]) => name).join(";"),
+    };
+}
+/** The canonical request, verbatim as it is hashed into the string to sign. */
+export function canonicalRequest(method, url, headers, payloadHash) {
+    const { canonical: headerBlock, signed } = canonicalHeaders(headers);
+    return {
+        canonical: [
+            method.toUpperCase(),
+            canonicalPath(url.pathname),
+            canonicalQuery(url.searchParams),
+            headerBlock,
+            signed,
+            payloadHash,
+        ].join("\n"),
+        signed,
+    };
+}
+/** The string to sign: algorithm, timestamp, scope, hashed canonical request. */
+export function stringToSign(timestamp, scope, canonical) {
+    return [ALGORITHM, timestamp, scope, sha256Hex(canonical)].join("\n");
+}
+/**
+ * The caller's headers plus everything SigV4 adds: `x-amz-date`,
+ * `x-amz-content-sha256`, `x-amz-security-token` when the credentials are
+ * temporary, and the `Authorization` header itself.
+ *
+ * `host` is signed (AWS requires it) but not returned — see the module header.
+ */
+export function signRequest(request) {
+    const url = new URL(request.url);
+    const timestamp = amzDate(request.now ?? new Date());
+    const day = timestamp.slice(0, 8);
+    const payloadHash = request.body.length === 0 ? EMPTY_PAYLOAD_SHA256 : sha256Hex(request.body);
+    const signable = {
+        ...request.headers,
+        host: url.host,
+        "x-amz-date": timestamp,
+        "x-amz-content-sha256": payloadHash,
+        ...(request.credentials.sessionToken ? { "x-amz-security-token": request.credentials.sessionToken } : {}),
+    };
+    const { canonical, signed } = canonicalRequest(request.method, url, signable, payloadHash);
+    const scope = `${day}/${request.region}/${request.service}/${TERMINATOR}`;
+    const key = signingKey(request.credentials.secretAccessKey, day, request.region, request.service);
+    const signature = hmac(key, stringToSign(timestamp, scope, canonical)).toString("hex");
+    const { host: _host, ...emitted } = signable;
+    return {
+        ...emitted,
+        authorization: `${ALGORITHM} Credential=${request.credentials.accessKeyId}/${scope}, ` +
+            `SignedHeaders=${signed}, Signature=${signature}`,
+    };
+}