@intentius/chant-lexicon-aws 0.124.30 → 0.124.32

package/dist/agentcore/trace-render.js

@@ -0,0 +1,359 @@
+/**
+ * Render an AgentCore session history as dogwood replay-trace text (#1685).
+ *
+ * This module is pure: normalized events in, text out, no transport and no
+ * filesystem. It exists separately from `./trace-fetch.ts` for two reasons.
+ * The Bedrock AgentCore observability surface is in preview and moving, so the
+ * thing most likely to be rewritten is the fetch, and the grammar it renders
+ * into is the thing least likely to move. And the line grammar has two traps in
+ * it that are worth testing byte-for-byte without a mock HTTP stack in the way.
+ *
+ * ## The grammar
+ *
+ * From the #1657 verification (§6, read from
+ * `dogwood-language/src/interpreter/log_parse.rs` at the pinned SHA
+ * `5063bcc2d6d6cf5024d1b0498e6cc8ef52cbcf0c`), one event per line:
+ *
+ * ```
+ * @<timestamp> [scope(principal: <uid>, resource: <uid>)]
+ *              [entities(<uid>: { <attrs> } [in [<uid>, …]], …)]
+ *              [request_context(<group>: { … }, …)]
+ *              <Ns>::Action::"<Name>"::<kind>(<field>: <value>, …)
+ * ```
+ *
+ * The three envelopes are optional and must appear in that order; the trailing
+ * group is the logged record. Blank lines are skipped and there is no comment
+ * syntax, so a `//` inside a value survives.
+ *
+ * ## The two traps
+ *
+ * 1. **`request_context(…)` and the logged record are different bags.** The
+ *    Cedar request is built from the first, temporal predicates match against
+ *    the second, and a field supplied to only one weakens either the Cedar
+ *    check or the temporal check while the replay still exits 0 with a verdict
+ *    that looks authoritative. So every payload group an event carries is
+ *    written to *both*, always — there is no per-event opt-out here, because an
+ *    AgentCore history has no way to express "this field is deliberately
+ *    Cedar-invisible". A decision-kind event with no payload at all is a
+ *    refusal, not a shrug: see {@link renderAgentCoreTrace}.
+ * 2. **Actions must be fully qualified.** `AgentCore::Action::"Transfer"`,
+ *    never `Transfer` — a short name leaves the temporal predicate unmatched
+ *    while Cedar still authorizes. A bare tool name from the history is
+ *    qualified here; an already-qualified one is validated and passed through.
+ *
+ * ## Decoupling
+ *
+ * Nothing here imports the cedar lexicon, and the cedar lexicon imports nothing
+ * from here. The contract between them is the text. The value and event types
+ * below are deliberately shaped so an object built here is *structurally*
+ * assignable to the cedar side's `TraceValue`/`TraceEvent` for anyone who wants
+ * that, but neither package depends on the other to get it, and the rendering
+ * is implemented twice on purpose. Where a choice was free — the space inside
+ * `{ … }`, the `, ` between fields, the order of the record's own injections —
+ * it matches `lexicons/cedar/src/dogwood/trace.ts` byte for byte, so a trace
+ * fetched from AWS and a trace built by hand look the same to a reader and to
+ * the parser.
+ */
+/**
+ * Which objects are *really* tagged values.
+ *
+ * Identity, not shape. A tagged value renders as surface text — an `entity`
+ * becomes a bare uid, a `raw` becomes its `text` verbatim — so if membership
+ * were decided by a `traceValue` key, any agent that wrote
+ * `{"traceValue": "raw", "text": "…"}` into a payload could inject arbitrary
+ * unescaped text into both bags of the trace: a forged `callerPrincipal`, an
+ * unbalanced paren, a whole extra field. The payloads this module reads are
+ * written by the agent under observation, which is the last party that should
+ * get to decide what its own trace says. So only the three constructors below
+ * confer the tag, and {@link renderValue} refuses a record that merely looks
+ * tagged rather than rendering it either way.
+ */
+const TAGGED = new WeakSet();
+function tag(value) {
+    TAGGED.add(value);
+    return value;
+}
+/** `Ns::Type::"id"`, `Ns::Action::"Name"` — a fully qualified uid. */
+const QUALIFIED_UID = /^[A-Za-z_][A-Za-z0-9_]*(::[A-Za-z_][A-Za-z0-9_]*)+::"[^"]*"$/;
+/** A bare field, group, namespace or event-kind name. */
+const IDENT = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/**
+ * A history that cannot become an honest trace.
+ *
+ * Thrown rather than worked around. Every case this covers is one where the
+ * alternative is a trace that replays green and proves less than it looks like
+ * it proves, which is the failure mode the whole module is arranged against.
+ */
+export class AgentCoreTraceError extends Error {
+    constructor(message, 
+    /** 0-based position in the event list, when one event is to blame. */
+    index) {
+        super(message);
+        this.index = index;
+        this.name = "AgentCoreTraceError";
+    }
+}
+function assertUid(value, what, index) {
+    if (!QUALIFIED_UID.test(value)) {
+        throw new AgentCoreTraceError(`agentcore trace: ${what} must be fully qualified, like Ns::Type::"id" — got "${value}"`, index);
+    }
+    return value;
+}
+function assertIdent(value, what, index) {
+    if (!IDENT.test(value)) {
+        throw new AgentCoreTraceError(`agentcore trace: ${what} must be an identifier — got "${value}"`, index);
+    }
+    return value;
+}
+/** `Ns::Type::"id"`. Validated at construction, so a short name cannot slip through. */
+export function agentCoreEntityRef(uid) {
+    return tag({ traceValue: "entity", uid: assertUid(uid, "an entity reference") });
+}
+/**
+ * A Cedar decimal, written as it should appear (`"1.50"`).
+ *
+ * `context` names the field it came from when there is one, so a payload that
+ * cannot be represented says *where* rather than only *what*.
+ */
+export function agentCoreDecimal(text, context) {
+    if (!/^-?\d+\.\d+$/.test(text)) {
+        const where = context ? ` at ${context}` : "";
+        throw new AgentCoreTraceError(`agentcore trace: a decimal looks like "1.50" — got "${text}"${where}`);
+    }
+    return tag({ traceValue: "decimal", text });
+}
+/** Surface text, rendered verbatim. For values this module has no shape for. */
+export function agentCoreRaw(text) {
+    return tag({ traceValue: "raw", text });
+}
+function isTagged(value) {
+    return typeof value === "object" && value !== null && TAGGED.has(value);
+}
+/** The five escapes a Cedar string literal needs. Mirrors the cedar lexicon's. */
+function escapeString(value) {
+    return value
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t");
+}
+/** Render one value in the Cedar surface form the trace parser reads. */
+export function renderValue(value) {
+    if (typeof value === "string")
+        return `"${escapeString(value)}"`;
+    if (typeof value === "boolean")
+        return value ? "true" : "false";
+    if (typeof value === "number") {
+        if (!Number.isInteger(value)) {
+            throw new AgentCoreTraceError(`agentcore trace: ${String(value)} is not an integer — a decimal must be written with agentCoreDecimal("1.50") so its scale survives`);
+        }
+        // Beyond 2^53 a JS number has already lost the digits an i64 would keep,
+        // and `String(1e21)` is `"1e+21"`, which is not a Cedar integer literal at
+        // all. Either way the trace would carry a number that is not the number the
+        // agent saw.
+        if (!Number.isSafeInteger(value)) {
+            throw new AgentCoreTraceError(`agentcore trace: ${String(value)} is outside the range a JS number represents exactly, so the trace would carry a different number than the history did — carry it as a string`);
+        }
+        return String(value);
+    }
+    if (Array.isArray(value))
+        return `[${value.map(renderValue).join(", ")}]`;
+    if (isTagged(value))
+        return value.traceValue === "entity" ? value.uid : value.text;
+    if ("traceValue" in value) {
+        // See TAGGED. Rendering it as a record would be a lie about what the agent
+        // wrote; rendering it as a tagged value would let the agent write its own
+        // trace. Neither is on offer.
+        throw new AgentCoreTraceError(`agentcore trace: a payload carries a "traceValue" field, which is the marker this module uses for entity refs, decimals and raw surface text. ` +
+            "Rendering it either way would let the observed agent decide what its own trace says, so it is refused — rename the field at the source, " +
+            "or build the value with agentCoreEntityRef/agentCoreDecimal/agentCoreRaw.");
+    }
+    return renderFields(value);
+}
+/** `{ a: 1, b: "x" }` — a record body, braces included. */
+export function renderFields(fields) {
+    const parts = Object.entries(fields).map(([key, value]) => `${assertIdent(key, "a trace field name")}: ${renderValue(value)}`);
+    return `{ ${parts.join(", ")} }`;
+}
+const DEFAULTS = {
+    namespace: "AgentCore",
+    principalType: "Actor",
+    resourceType: "Runtime",
+    origin: "epoch-seconds",
+    decisionKinds: ["request"],
+};
+/** A payload group name → the field on the normalized event. Order is the render order. */
+const GROUPS = ["input", "output", "error", "attributes"];
+function payloadGroups(event) {
+    const out = {};
+    for (const group of GROUPS) {
+        const fields = event[group];
+        if (fields && Object.keys(fields).length > 0)
+            out[group] = fields;
+    }
+    return out;
+}
+/**
+ * `Ns::Action::"Name"` from a bare tool name, or a qualified action validated.
+ *
+ * The fully-qualified requirement is the second §6 trap: a short name leaves
+ * every temporal predicate unmatched while Cedar still authorizes, so the
+ * replay is green and blind.
+ */
+export function qualifyAction(action, namespace, index) {
+    if (action.includes("::"))
+        return assertUid(action, "a trace action", index);
+    if (action.length === 0 || action.includes('"')) {
+        throw new AgentCoreTraceError(`agentcore trace: a bare action name cannot be empty or contain a quote — got "${action}"`, index);
+    }
+    return `${assertIdent(namespace, "a namespace", index)}::Action::"${action}"`;
+}
+/** `Ns::Type::"id"` from a bare id, or a qualified uid validated. */
+export function qualifyUid(id, namespace, type, what, index) {
+    if (id.includes("::"))
+        return assertUid(id, what, index);
+    if (id.length === 0 || id.includes('"')) {
+        throw new AgentCoreTraceError(`agentcore trace: ${what} cannot be empty or contain a quote — got "${id}"`, index);
+    }
+    return `${assertIdent(namespace, "a namespace", index)}::${assertIdent(type, "an entity type", index)}::"${id}"`;
+}
+/**
+ * Order the history the way the interpreter reads it.
+ *
+ * dogwood accumulates history in *file* order, so an out-of-order line changes
+ * what a temporal window sees. A fetch that pages backwards (CloudWatch Logs
+ * hands out the newest first) would otherwise produce a trace whose windows are
+ * quietly wrong, so ordering is settled here rather than being a caller's
+ * problem. Ties keep their original relative order.
+ */
+function sortByTime(events) {
+    return events.map((event, index) => ({ event, index }))
+        .sort((a, b) => a.event.timeMs - b.event.timeMs || a.index - b.index)
+        .map(({ event }) => event);
+}
+function assertWellFormed(event, index) {
+    if (typeof event.timeMs !== "number" || !Number.isFinite(event.timeMs)) {
+        throw new AgentCoreTraceError(`agentcore trace: event ${index} has no usable timestamp (${String(event.timeMs)}) — a trace timepoint is an i64 and there is no honest default for a missing one`, index);
+    }
+    for (const [field, value] of [
+        ["sessionId", event.sessionId],
+        ["eventId", event.eventId],
+        ["actor", event.actor],
+        ["target", event.target],
+        ["action", event.action],
+        ["kind", event.kind],
+    ]) {
+        if (typeof value !== "string" || value.length === 0) {
+            throw new AgentCoreTraceError(`agentcore trace: event ${index} has no ${field} — the history is malformed, and a trace with a guessed ${field} replays green while proving nothing`, index);
+        }
+    }
+}
+/**
+ * The weakening checks, applied to a normalized history.
+ *
+ * Everything here is something that makes a replay *weaker* rather than
+ * something that makes it fail, which is exactly the class a green replay run
+ * hides. Structural malformation throws instead: see {@link AgentCoreTraceError}.
+ */
+export function auditAgentCoreEvents(events, options = {}) {
+    const decisionKinds = new Set(options.decisionKinds ?? DEFAULTS.decisionKinds);
+    const issues = [];
+    const seen = new Set();
+    sortByTime(events).forEach((event, index) => {
+        assertWellFormed(event, index);
+        const at = { index, timeMs: event.timeMs };
+        if (decisionKinds.has(event.kind) && Object.keys(payloadGroups(event)).length === 0) {
+            issues.push({
+                ...at,
+                kind: "no-request-context",
+                message: `${event.action}::${event.kind} carries no input, output, error or attributes, so its request_context envelope would be empty and every context.* test in a policy silently misses`,
+            });
+        }
+        const key = `${event.sessionId}${event.eventId}`;
+        if (seen.has(key)) {
+            issues.push({
+                ...at,
+                kind: "duplicate-event-id",
+                message: `session ${event.sessionId} reports eventId "${event.eventId}" twice, so requestId no longer identifies a decision point and an expectation written against one addresses both`,
+            });
+        }
+        seen.add(key);
+    });
+    return issues;
+}
+/**
+ * Resolve one normalized event into the envelopes and the logged record.
+ *
+ * Both bags get every payload group; the record additionally gets the event
+ * schema's own injections (`callerPrincipal`, `callerResource`, `sessionId`,
+ * `requestId`), which are never part of the Cedar request. Field order matches
+ * the §6 example line: groups first, then the injections.
+ */
+export function toTraceLine(event, timestamp, options = {}, index) {
+    const namespace = options.namespace ?? DEFAULTS.namespace;
+    const principal = qualifyUid(event.actor, namespace, options.principalType ?? DEFAULTS.principalType, "an actor", index);
+    const resource = qualifyUid(event.target, namespace, options.resourceType ?? DEFAULTS.resourceType, "a target", index);
+    const groups = payloadGroups(event);
+    return {
+        timestamp,
+        action: qualifyAction(event.action, namespace, index),
+        kind: assertIdent(event.kind, "an event kind", index),
+        scope: { principal, resource },
+        requestContext: groups,
+        record: {
+            ...groups,
+            callerPrincipal: agentCoreEntityRef(principal),
+            callerResource: agentCoreEntityRef(resource),
+            sessionId: event.sessionId,
+            requestId: event.eventId,
+        },
+    };
+}
+/** One line as the trace parser reads it. Never ends in a newline. */
+export function renderTraceLine(line) {
+    if (!Number.isSafeInteger(line.timestamp)) {
+        throw new AgentCoreTraceError(`agentcore trace: a timepoint is an i64 — got ${String(line.timestamp)}`);
+    }
+    const parts = [`@${line.timestamp}`];
+    parts.push(`scope(principal: ${line.scope.principal}, resource: ${line.scope.resource})`);
+    const context = Object.entries(line.requestContext).map(([group, value]) => `${assertIdent(group, "a request-context group")}: ${renderValue(value)}`);
+    if (context.length > 0)
+        parts.push(`request_context(${context.join(", ")})`);
+    const record = Object.entries(line.record).map(([key, value]) => `${assertIdent(key, "a trace field name")}: ${renderValue(value)}`);
+    parts.push(`${line.action}::${line.kind}(${record.join(", ")})`);
+    return parts.join(" ");
+}
+/**
+ * Render a normalized AgentCore history as dogwood trace text.
+ *
+ * The inversion of the §6 traps: every payload group lands in both bags, every
+ * action comes out fully qualified, the history is ordered the way the
+ * interpreter reads it, and a history that would produce a weakened trace
+ * throws instead. Naming a kind in `allow` is how a caller says the weakening
+ * is the point — the alternative was a trace that replays green and proves
+ * less than it looks like it proves.
+ */
+export function renderAgentCoreTrace(events, options = {}) {
+    const sorted = sortByTime(events);
+    // The audit runs `assertWellFormed` over the same sorted list, so a
+    // structurally broken history throws here before anything is rendered.
+    const issues = auditAgentCoreEvents(sorted, options);
+    const allow = new Set(options.allow ?? []);
+    const blocking = issues.filter((issue) => !allow.has(issue.kind));
+    if (blocking.length > 0) {
+        const detail = blocking.map((i) => `  [${i.kind}] event ${i.index}: ${i.message}`).join("\n");
+        const kinds = [...new Set(blocking.map((i) => `"${i.kind}"`))].join(", ");
+        throw new AgentCoreTraceError(`agentcore trace: this history would weaken its own replay rather than fail it:\n${detail}\n` +
+            `Fix the history, or pass { allow: [${kinds}] } to say the weakening is the point.`);
+    }
+    const origin = options.origin ?? DEFAULTS.origin;
+    const base = origin === "relative-seconds" && sorted.length > 0 ? (sorted[0]?.timeMs ?? 0) : 0;
+    const lines = sorted.map((event, index) => toTraceLine(event, Math.floor((event.timeMs - base) / 1000), options, index));
+    // An empty history renders as empty text, not as a bare newline: dogwood
+    // skips blank lines, so the two replay identically, and "" is the honest
+    // answer to "what did this session do". Whether an empty trace is worth
+    // replaying is the caller's call — see `trace-fetch.ts`'s `requireEvents`.
+    const text = lines.length > 0 ? lines.map(renderTraceLine).join("\n") + "\n" : "";
+    return { text, lines, issues };
+}

package/dist/ambient.js

@@ -0,0 +1,148 @@
+/**
+ * Resources that are simply *there* (#1278).
+ *
+ * `describeResources` answers "what do I manage" and `observeDependencies`
+ * answers "what do I rely on". Both resolve outward from the declared estate,
+ * so neither can see a resource nothing points at — and "which of my security
+ * groups are unused" is precisely a question about resources nothing points at.
+ *
+ * A state file cannot answer this at all: it knows what it created, and an
+ * unused resource is by definition not something it created and attached. A
+ * lexicon that can enumerate a kind can.
+ *
+ * Bounded by the kinds the project declares. A project managing security groups
+ * is asked about security groups, not about the account.
+ */
+import { applyAwsEndpointArgv } from "./components/cloud-executor.js";
+/** Enumerable kinds, and how to list them. Extending this is the way to widen. */
+const ENUMERABLE = {
+    "AWS::EC2::SecurityGroup": {
+        argv: ["ec2", "describe-security-groups"],
+        key: "SecurityGroups",
+        id: "GroupId",
+        name: "GroupName",
+    },
+    // The account's default VPC is the archetype: nothing declares it, nothing
+    // in the declared estate points at it, and "which instances are outside a
+    // default VPC" cannot be answered without it.
+    "AWS::EC2::VPC": {
+        argv: ["ec2", "describe-vpcs"],
+        key: "Vpcs",
+        id: "VpcId",
+    },
+    // Nobody writes a network interface: EC2 creates one per instance. But the
+    // ENI is where a security group is actually attached, so "which of my
+    // security groups are unused" is an ENI question and cannot be answered
+    // without them. Asked exactly that, an agent queried
+    // `kind:EC2::NetworkInterface`, got nothing, and rebuilt the attachment map
+    // by hand from twenty-nine raw provider calls.
+    "AWS::EC2::NetworkInterface": {
+        argv: ["ec2", "describe-network-interfaces"],
+        key: "NetworkInterfaces",
+        id: "NetworkInterfaceId",
+    },
+    // A subnet holding nothing is the same shape as an unused security group, and
+    // it was reachable by neither of the other paths. Both resolve outward from
+    // what is declared, so a subnet gets recorded only when something in it does —
+    // and the empty ones are exactly what "which of my subnets are empty" asks
+    // for.
+    //
+    // Found by measuring a snapshot rather than by reading the code: an estate
+    // with seven subnets recorded five, and the two it dropped were the two with
+    // nothing in them. The default VPC's subnets are the archetype again — nothing
+    // declares them, and the only one ever recorded was the one that happened to
+    // hold an instance.
+    "AWS::EC2::Subnet": {
+        argv: ["ec2", "describe-subnets"],
+        key: "Subnets",
+        id: "SubnetId",
+    },
+};
+/**
+ * Kinds a declared kind implies, though nobody writes them.
+ *
+ * The scan is bounded by what the project declares — a project managing
+ * security groups is asked about security groups, not about the account. That
+ * bound is right, and it excluded exactly the resource that answers the
+ * question: EC2 creates a network interface per instance, and the ENI is where
+ * a security group is actually attached. So an estate full of instances had no
+ * ENIs recorded, and "which of my security groups are unused" — definitionally
+ * an ENI question — could not be answered from the snapshot at all.
+ *
+ * Declaring an instance is declaring its network interface. This widens the
+ * bound by implication rather than abandoning it: still nothing about the
+ * account at large.
+ */
+const IMPLIED = {
+    "AWS::EC2::Instance": ["AWS::EC2::NetworkInterface"],
+};
+/** The requested kinds, plus the ones they imply. */
+export function withImplied(kinds) {
+    return [...new Set(kinds.flatMap((k) => [k, ...(IMPLIED[k] ?? [])]))];
+}
+/** The kinds this reader can enumerate. Declared so a caller can mention
+ * `--ambient` without paying for a scan to discover it is relevant. */
+export const AMBIENT_KINDS = Object.keys(ENUMERABLE);
+/** True when this lexicon can enumerate the kind, so a caller can say what it skipped. */
+export function canEnumerate(kind) {
+    return kind in ENUMERABLE;
+}
+/**
+ * List resources of the declared kinds that exist in the account but are
+ * neither managed nor already observed.
+ *
+ * Attachment is deliberately NOT decided here. Whether a security group is
+ * "unused" is a graph question — does anything reference it — and the graph
+ * answers it once the group is a node. Deciding it in the reader would put a
+ * conclusion in the observation, which is the mistake `liveInternetFacing` made
+ * and #1271 undid.
+ */
+export async function observeAwsAmbient(options) {
+    const kinds = withImplied(options.kinds).filter(canEnumerate);
+    if (kinds.length === 0)
+        return {};
+    const { getRuntime } = await import("@intentius/chant/runtime-adapter");
+    const rt = getRuntime();
+    const regionArgs = options.region ? ["--region", options.region] : [];
+    // Physical ids already accounted for, so a managed resource is never also
+    // reported as ambient.
+    const known = new Set(Object.values(options.observed)
+        .map((m) => m.physicalId)
+        .filter((id) => typeof id === "string"));
+    const ambient = {};
+    for (const kind of kinds) {
+        const spec = ENUMERABLE[kind];
+        try {
+            const result = await rt.spawn(applyAwsEndpointArgv(["aws", ...spec.argv, ...regionArgs, "--output", "json"], process.env.AWS_ENDPOINT_URL));
+            if (result.exitCode !== 0)
+                continue;
+            const rows = (JSON.parse(result.stdout)[spec.key] ?? []);
+            for (const row of rows) {
+                const id = row[spec.id];
+                if (typeof id !== "string" || known.has(id))
+                    continue;
+                ambient[id] = {
+                    type: kind,
+                    status: "OBSERVED",
+                    physicalId: id,
+                    // The whole payload, so the graph can decide what "unused" means
+                    // rather than the reader pre-deciding it.
+                    attributes: row,
+                    ownership: "foreign",
+                    ambient: true,
+                };
+            }
+        }
+        catch {
+            // Best-effort per kind: one unreadable kind does not sink the others, and
+            // the managed observation is already complete without any of this.
+            continue;
+        }
+    }
+    // Same stamps the managed path applies, so one query shape works across both
+    // (#1279). Defaults matter most here: a default VPC or security group is
+    // ambient by definition — nobody declared it.
+    const { stampRegion } = await import("./properties.js");
+    const { stampProviderDefaults } = await import("./defaults.js");
+    return stampProviderDefaults(stampRegion(ambient, options.region));
+}

package/dist/api/credential-chain.d.ts

@@ -8,7 +8,9 @@
  * than keys: `AWS_PROFILE=dev` with an SSO session came back as "no identity
  * is configured" while `aws sts get-caller-identity` answered. This module is
  * the asynchronous half: it resolves what the CLI would sign with and hands
- * back literal credentials plus a label for where they came from.
+ * back literal credentials plus a label for where they came from. The read
+ * transport uses the same walk through {@link transportCredentials} (#3958),
+ * so whoami and `describeResources` sign as the same principal.
  *
  * There is still no `@aws-sdk/*` here, for the reason the read transport gives:
  * a lexicon keeps that tree out. The chain is small enough to state.
@@ -16,8 +18,7 @@
  * ## Order
  *
  *  1. `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY` (+ `AWS_SESSION_TOKEN`).
- *     They win over `AWS_PROFILE`, as they do in the AWS CLI, and as they do
- *     in chant's own read transport, which signs with nothing else. (The JS
+ *     They win over `AWS_PROFILE`, as they do in the AWS CLI. (The JS
  *     SDK v3 skips the environment when `AWS_PROFILE` is set; the CLI does
  *     not, and the CLI is what an operator checks whoami against.) When both
  *     are set, the label says the profile was not used.
@@ -86,6 +87,8 @@ export interface ResolvedChainCredentials {
     source: string;
     /** The profile that resolved them, when one did. */
     profile?: string;
+    /** When the credentials stop working, for role, SSO and `credential_process` credentials that say so. */
+    expiration?: Date;
 }
 export interface UnresolvedChainCredentials {
     reason: "no-credentials" | "read-failed";
@@ -110,5 +113,29 @@ export declare function parseIni(text: string): Record<string, Section>;
  * and their source, or a typed refusal that says what to do about it.
  */
 export declare function resolveCredentialChain(options?: CredentialChainOptions): Promise<CredentialChainResult>;
+/** Cached credentials are re-resolved this long before they expire. */
+export declare const TRANSPORT_REFRESH_MARGIN_MS: number;
+/**
+ * How long "nothing resolves" is kept before the chain is walked again, so a
+ * long-running process picks up an `aws sso login` done after it started.
+ */
+export declare const TRANSPORT_UNRESOLVED_TTL_MS: number;
+/** Forget every cached walk. For tests, and for a process that changed its profile. */
+export declare function resetTransportCredentials(): void;
+/**
+ * What the native read transport signs with when the caller injected nothing:
+ * the same chain whoami walks, so `lifecycle diff --live` signs as the
+ * principal whoami reports. The signing seam (`AwsCredentialResolver` in
+ * ./sigv4.ts) is synchronous and the chain is not, so the transport awaits
+ * this once before a request and passes the literal credentials in.
+ *
+ * Environment keys answer directly, as in the chain. Otherwise the walk is
+ * cached per process, keyed by the profile and the shared-file locations, and
+ * walked again within {@link TRANSPORT_REFRESH_MARGIN_MS} of the expiry the
+ * role, SSO or `credential_process` answer carried. A refusal or a failure is
+ * `undefined`, which leaves the request unsigned exactly as before; it is kept
+ * for {@link TRANSPORT_UNRESOLVED_TTL_MS}.
+ */
+export declare function transportCredentials(options?: CredentialChainOptions): Promise<AwsCredentials | undefined>;
 export {};
 //# sourceMappingURL=credential-chain.d.ts.map

package/dist/api/credential-chain.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"credential-chain.d.ts","sourceRoot":"","sources":["../../src/api/credential-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAOH,OAAO,EAA4B,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KAC7E,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE/C,mEAAmE;AACnE,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEnE,MAAM,WAAW,sBAAsB;IACrC,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAChD,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,uBAAuB,CAAC;IACrC,sFAAsF;IACtF,GAAG,CAAC,EAAE,oBAAoB,CAAC;IAC3B,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,cAAc,CAAC;IAC5B,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,gBAAgB,GAAG,aAAa,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,EAAE,wBAAwB,CAAA;CAAE,GACtC;IAAE,UAAU,EAAE,0BAA0B,CAAA;CAAE,CAAC;AAE/C,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEtC;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsB9D;AAgFD;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAyCjH"}
+{"version":3,"file":"credential-chain.d.ts","sourceRoot":"","sources":["../../src/api/credential-chain.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiDG;AAOH,OAAO,EAA4B,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACpF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,8EAA8E;AAC9E,MAAM,MAAM,mBAAmB,GAAG,CAChC,GAAG,EAAE,MAAM,EACX,IAAI,EAAE;IAAE,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAA;CAAE,KAC7E,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAE/C,mEAAmE;AACnE,MAAM,MAAM,uBAAuB,GAAG,CACpC,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEnE,MAAM,WAAW,sBAAsB;IACrC,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,oFAAoF;IACpF,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IAChD,sFAAsF;IACtF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,IAAI,CAAC,EAAE,mBAAmB,CAAC;IAC3B,+DAA+D;IAC/D,UAAU,CAAC,EAAE,uBAAuB,CAAC;IACrC,sFAAsF;IACtF,GAAG,CAAC,EAAE,oBAAoB,CAAC;IAC3B,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,cAAc,CAAC;IAC5B,6FAA6F;IAC7F,MAAM,EAAE,MAAM,CAAC;IACf,oDAAoD;IACpD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yGAAyG;IACzG,UAAU,CAAC,EAAE,IAAI,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,gBAAgB,GAAG,aAAa,CAAC;IACzC,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,QAAQ,EAAE,wBAAwB,CAAA;CAAE,GACtC;IAAE,UAAU,EAAE,0BAA0B,CAAA;CAAE,CAAC;AAE/C,KAAK,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAgBtC;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAsB9D;AAgFD;;;GAGG;AACH,wBAAsB,sBAAsB,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAyCjH;AAqSD,uEAAuE;AACvE,eAAO,MAAM,2BAA2B,QAAa,CAAC;AAEtD;;;GAGG;AACH,eAAO,MAAM,2BAA2B,QAAa,CAAC;AAetD,uFAAuF;AACvF,wBAAgB,yBAAyB,IAAI,IAAI,CAEhD;AAiBD;;;;;;;;;;;;;GAaG;AACH,wBAAsB,oBAAoB,CAAC,OAAO,GAAE,sBAA2B,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC,CAoBpH"}