@intentius/chant-lexicon-aws 0.124.52 → 0.124.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (108) hide show
  1. package/dist/api/credential-chain.d.ts +3 -3
  2. package/dist/api/credential-chain.d.ts.map +1 -1
  3. package/dist/api/credential-chain.js +2 -2
  4. package/dist/api/read-client.d.ts +2 -2
  5. package/dist/api/read-client.d.ts.map +1 -1
  6. package/dist/api/read-client.js +2 -2
  7. package/dist/api/{sigv4.d.ts → signing.d.ts} +14 -34
  8. package/dist/api/signing.d.ts.map +1 -0
  9. package/dist/api/signing.js +95 -0
  10. package/dist/codegen/generate-lexicon.d.ts +2 -0
  11. package/dist/codegen/generate-lexicon.d.ts.map +1 -1
  12. package/dist/codegen/generate-lexicon.js +1 -0
  13. package/dist/components/__tests__/mock-cloud-executor.d.ts +4 -0
  14. package/dist/components/__tests__/mock-cloud-executor.d.ts.map +1 -1
  15. package/dist/components/__tests__/mock-cloud-executor.js +18 -1
  16. package/dist/components/apply.d.ts +46 -2
  17. package/dist/components/apply.d.ts.map +1 -1
  18. package/dist/components/apply.js +266 -30
  19. package/dist/components/cfn-adopt-run.d.ts +37 -0
  20. package/dist/components/cfn-adopt-run.d.ts.map +1 -0
  21. package/dist/components/cfn-adopt-run.js +104 -0
  22. package/dist/components/cfn-adopt.d.ts +99 -0
  23. package/dist/components/cfn-adopt.d.ts.map +1 -0
  24. package/dist/components/cfn-adopt.js +278 -0
  25. package/dist/components/cfn-imports.d.ts +84 -0
  26. package/dist/components/cfn-imports.d.ts.map +1 -0
  27. package/dist/components/cfn-imports.js +239 -0
  28. package/dist/components/cloud-executor.d.ts +38 -2
  29. package/dist/components/cloud-executor.d.ts.map +1 -1
  30. package/dist/components/cloud-executor.js +84 -2
  31. package/dist/health.js +1 -1
  32. package/dist/importable.d.ts +30 -0
  33. package/dist/importable.d.ts.map +1 -0
  34. package/dist/importable.js +72 -0
  35. package/dist/index-identity.d.ts +19 -0
  36. package/dist/index-identity.d.ts.map +1 -0
  37. package/dist/index-identity.js +79 -0
  38. package/dist/index-import.d.ts +25 -0
  39. package/dist/index-import.d.ts.map +1 -0
  40. package/dist/index-import.js +132 -0
  41. package/dist/index.d.ts +1 -1
  42. package/dist/index.d.ts.map +1 -1
  43. package/dist/index.js +1 -1
  44. package/dist/integrity.json +4 -4
  45. package/dist/listed-types.d.ts +11 -0
  46. package/dist/listed-types.d.ts.map +1 -0
  47. package/dist/listed-types.js +52 -0
  48. package/dist/manifest.json +1 -1
  49. package/dist/meta.json +13206 -1237
  50. package/dist/plugin.d.ts.map +1 -1
  51. package/dist/plugin.js +12 -3
  52. package/dist/reference-catalog.d.ts.map +1 -1
  53. package/dist/reference-catalog.js +62 -20
  54. package/dist/skills/chant-aws-carve-terraform.md +21 -14
  55. package/dist/spec/fetch.d.ts +5 -0
  56. package/dist/spec/fetch.d.ts.map +1 -1
  57. package/dist/spec/parse.d.ts +8 -0
  58. package/dist/spec/parse.d.ts.map +1 -1
  59. package/dist/spec/parse.js +3 -0
  60. package/package.json +2 -2
  61. package/src/api/credential-chain.ts +3 -3
  62. package/src/api/read-client.test.ts +2 -2
  63. package/src/api/read-client.ts +3 -3
  64. package/src/api/{sigv4.test.ts → signing.test.ts} +84 -96
  65. package/src/api/signing.ts +130 -0
  66. package/src/codegen/generate-lexicon.ts +3 -0
  67. package/src/components/__tests__/mock-cloud-executor.ts +20 -1
  68. package/src/components/apply.ts +288 -30
  69. package/src/components/cfn-adopt-run.test.ts +227 -0
  70. package/src/components/cfn-adopt-run.ts +141 -0
  71. package/src/components/cfn-adopt.test.ts +284 -0
  72. package/src/components/cfn-adopt.ts +340 -0
  73. package/src/components/cfn-exports-in-use.test.ts +146 -0
  74. package/src/components/cfn-imports-preview.test.ts +178 -0
  75. package/src/components/cfn-imports-three-stacks.test.ts +107 -0
  76. package/src/components/cfn-imports.test.ts +213 -0
  77. package/src/components/cfn-imports.ts +246 -0
  78. package/src/components/cfn-plan-shape-conformance.test.ts +83 -0
  79. package/src/components/cloud-executor.ts +127 -5
  80. package/src/components/demo-composed-stacks-floci.e2e.test.ts +235 -0
  81. package/src/derived-edges.test.ts +142 -0
  82. package/src/generated/lexicon-aws.json +13206 -1237
  83. package/src/health.ts +1 -1
  84. package/src/importable.test.ts +86 -0
  85. package/src/importable.ts +83 -0
  86. package/src/index-identity.test.ts +134 -0
  87. package/src/index-identity.ts +98 -0
  88. package/src/index-import.test.ts +257 -0
  89. package/src/index-import.ts +158 -0
  90. package/src/index-search.test.ts +87 -0
  91. package/src/index.ts +1 -1
  92. package/src/listed-types.test.ts +97 -0
  93. package/src/listed-types.ts +56 -0
  94. package/src/plugin.ts +13 -3
  95. package/src/reference-catalog.ts +63 -20
  96. package/src/skills/chant-aws-carve-terraform.md +21 -14
  97. package/src/spec/fetch.ts +5 -0
  98. package/src/spec/parse.test.ts +15 -0
  99. package/src/spec/parse.ts +12 -0
  100. package/src/testdata/indexed/identity.listing.json +65 -0
  101. package/src/testdata/indexed/import.listing.json +126 -0
  102. package/src/testdata/indexed/listing.json +69 -0
  103. package/src/testdata/indexed/topology.listing.json +350 -0
  104. package/src/testdata/three-cloud/dns.graph.json +336 -0
  105. package/src/three-cloud-parity.test.ts +49 -0
  106. package/dist/api/sigv4.d.ts.map +0 -1
  107. package/dist/api/sigv4.js +0 -185
  108. package/src/api/sigv4.ts +0 -243
@@ -0,0 +1,49 @@
1
+ /**
2
+ * #4535: on example-three-cloud's dns member, the aws catalog draws the one
3
+ * edge behold's matcher (behold src/value-match.ts) drew there: the gcp
4
+ * latency record is a CNAME to the gcp origin record, by name. The three
5
+ * records sharing `www.three-cloud.example.` make that name ambiguous, and
6
+ * none of them is referenced by it.
7
+ */
8
+ import { readFileSync } from "node:fs";
9
+ import { join } from "node:path";
10
+ import { describe, expect, it } from "vitest";
11
+ import type { IRNode } from "@intentius/chant/graph-ir";
12
+ import { reconstructIndexedEdges } from "@intentius/chant/graph-refs";
13
+ import { awsReferenceCatalog } from "./reference-catalog";
14
+
15
+ const graph = JSON.parse(readFileSync(join(import.meta.dirname, "testdata", "three-cloud", "dns.graph.json"), "utf-8")) as {
16
+ nodes: IRNode[];
17
+ edges: Array<{ from: string; to: string }>;
18
+ };
19
+
20
+ describe("example-three-cloud's dns member (parity with behold's matcher)", () => {
21
+ const out = reconstructIndexedEdges(graph.nodes, [{ lexicon: "aws", catalog: awsReferenceCatalog }], () => ({ account: "declared" }));
22
+ const declared = new Set(graph.edges.map((e) => `${e.from}->${e.to}`));
23
+
24
+ it("draws the CNAME edge the matcher drew, and none the declaration lacks besides", () => {
25
+ expect(out.edges.filter((e) => !declared.has(`${e.from}->${e.to}`)).map((e) => `${e.from} -> ${e.to} (${e.rule})`)).toEqual([
26
+ "dns/gcpRecord -> dns/gcpOrigin (aws:AWS::Route53::RecordSet:ResourceRecords[])",
27
+ ]);
28
+ });
29
+
30
+ it("leaves nothing ambiguous or dangling", () => {
31
+ expect(out.ambiguous).toEqual([]);
32
+ expect(out.dangling).toEqual([]);
33
+ });
34
+ });
35
+
36
+ describe("record and bucket identities (#4535)", () => {
37
+ it("does not report a record value outside the estate as dangling", () => {
38
+ const nodes: IRNode[] = [
39
+ { id: "r", kind: "AWS::Route53::RecordSet", lexicon: "aws", attrs: { Name: "www.example.", Type: "CNAME", ResourceRecords: ["elsewhere.example.net."] } },
40
+ ];
41
+ const out = reconstructIndexedEdges(nodes, [{ lexicon: "aws", catalog: awsReferenceCatalog }], () => ({ account: "declared" }));
42
+ expect(out.edges).toEqual([]);
43
+ expect(out.dangling).toEqual([]);
44
+ });
45
+
46
+ it("names a bucket by its BucketName", () => {
47
+ expect(awsReferenceCatalog.identities).toContainEqual({ kind: "AWS::S3::Bucket", ids: ["BucketName"] });
48
+ });
49
+ });
@@ -1 +0,0 @@
1
- {"version":3,"file":"sigv4.d.ts","sourceRoot":"","sources":["../../src/api/sigv4.ts"],"names":[],"mappings":"AAkCA,gFAAgF;AAChF,eAAO,MAAM,oBAAoB,qEAAqE,CAAC;AASvG,qFAAqF;AACrF,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,cAAc,GAAG,SAAS,CAAC;AAErE,yDAAyD;AACzD,MAAM,MAAM,mBAAmB,GAAG,cAAc,GAAG,qBAAqB,CAAC;AAEzE;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,CAAC,EAAE,mBAAmB,EAC5B,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,cAAc,GAAG,SAAS,CAW5B;AAED,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,mGAAmG;IACnG,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,cAAc,CAAC;IAC5B,uDAAuD;IACvD,GAAG,CAAC,EAAE,IAAI,CAAC;CACZ;AAED,6EAA6E;AAC7E,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE1C;AAED,6BAA6B;AAC7B,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAMD;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAKxG;AAmCD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CASvG;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC/B,WAAW,EAAE,MAAM,GAClB;IAAE,SAAS,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAavC;AAED,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAExF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CA0BzE"}
package/dist/api/sigv4.js DELETED
@@ -1,185 +0,0 @@
1
- /**
2
- * AWS Signature Version 4, for the shared read transport (#1686).
3
- *
4
- * Two modules asked for this by name before it existed: `./read-client.ts` and
5
- * cedar's `lexicons/cedar/src/avp/client.ts` both send a placeholder
6
- * `Signature=unsigned` `Authorization` header that carries a credential scope
7
- * and nothing else, and both say in prose that the real thing belongs here
8
- * once rather than twice. Nothing else in the repo signs an AWS request — the
9
- * appliers (`op/activities/aws-apply.ts`) are unsigned too, which is why the
10
- * native paths have been emulator-scoped.
11
- *
12
- * ## No dependency
13
- *
14
- * SigV4 is four HMACs and two SHA-256s. `node:crypto` has both, so signing
15
- * costs nothing in the dependency tree — which matters here, because the whole
16
- * reason these transports are hand-written is to keep `@aws-sdk/*` and its
17
- * thirty-odd transitive packages out of a lexicon.
18
- *
19
- * ## What is signed, and what is not
20
- *
21
- * Header signing only. Query-string (presigned-URL) signing has no caller: the
22
- * read paths POST to a service endpoint, they do not hand out URLs.
23
- *
24
- * `host` is signed but never emitted. `fetch` computes `Host` from the URL and
25
- * forbids overriding it, so the signer derives the same value from the URL it
26
- * was given. A transport that rewrites the URL underneath the signer — a proxy
27
- * that keeps the original `Host`, say — would invalidate the signature; the
28
- * injectable-HTTP seam is for tests and emulators, not for URL rewriting.
29
- */
30
- import { createHash, createHmac } from "node:crypto";
31
- const ALGORITHM = "AWS4-HMAC-SHA256";
32
- const TERMINATOR = "aws4_request";
33
- /** SHA-256 of the empty string — the payload hash of every bodyless request. */
34
- export const EMPTY_PAYLOAD_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
35
- /**
36
- * Headers that must not be signed even when a caller sets them: `authorization`
37
- * is the output, and the others are rewritten in transit by proxies and agents,
38
- * so signing them produces intermittent 403s rather than security.
39
- */
40
- const UNSIGNABLE = new Set(["authorization", "connection", "expect", "user-agent", "x-amzn-trace-id"]);
41
- /**
42
- * Credentials for a request: explicit → environment → absent.
43
- *
44
- * A resolver function is authoritative — if one is injected and it declines,
45
- * the environment is not consulted behind its back, because the point of
46
- * injecting one is to control the answer. Literal credentials are likewise
47
- * final. Only the no-source case falls through to `AWS_ACCESS_KEY_ID` /
48
- * `AWS_SECRET_ACCESS_KEY` (plus `AWS_SESSION_TOKEN` when set), and a half-set
49
- * environment — a key id with no secret — is absent rather than a signature
50
- * that cannot verify.
51
- *
52
- * The shared profile files are resolved asynchronously by
53
- * `./credential-chain.ts`, and the read transport passes its answer in as
54
- * literal credentials (#3958), so this function stays synchronous. Not
55
- * implemented anywhere: IMDS and the container credential endpoints.
56
- */
57
- export function resolveCredentials(source, env = process.env) {
58
- if (typeof source === "function")
59
- return source();
60
- if (source)
61
- return source;
62
- const accessKeyId = env.AWS_ACCESS_KEY_ID;
63
- const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
64
- if (!accessKeyId || !secretAccessKey)
65
- return undefined;
66
- return {
67
- accessKeyId,
68
- secretAccessKey,
69
- ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}),
70
- };
71
- }
72
- /** `YYYYMMDDTHHMMSSZ` — the `X-Amz-Date` format, which is ISO-8601 basic. */
73
- export function amzDate(date) {
74
- return date.toISOString().replace(/[:-]|\.\d{3}/g, "");
75
- }
76
- /** Lowercase hex SHA-256. */
77
- export function sha256Hex(payload) {
78
- return createHash("sha256").update(payload, "utf8").digest("hex");
79
- }
80
- function hmac(key, data) {
81
- return createHmac("sha256", key).update(data, "utf8").digest();
82
- }
83
- /**
84
- * The signing key: four chained HMACs from the secret, so the key on the wire
85
- * is scoped to one day, one region and one service rather than being the
86
- * account secret itself.
87
- */
88
- export function signingKey(secretAccessKey, day, region, service) {
89
- const dateKey = hmac(`AWS4${secretAccessKey}`, day);
90
- const regionKey = hmac(dateKey, region);
91
- const serviceKey = hmac(regionKey, service);
92
- return hmac(serviceKey, TERMINATOR);
93
- }
94
- /**
95
- * RFC 3986 percent-encoding. `encodeURIComponent` leaves `!'()*` alone and AWS
96
- * does not, which is the difference between a signature that verifies and one
97
- * that does not for any path or parameter containing them.
98
- */
99
- function encodeRfc3986(value) {
100
- return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
101
- }
102
- /**
103
- * The canonical path.
104
- *
105
- * Every caller of this module POSTs to `/`, so the one place implementations
106
- * genuinely diverge — S3 signs the path once-encoded, every other service signs
107
- * it twice-encoded — never arises. Segments are encoded once; a future caller
108
- * with a real path on a non-S3 service is the moment to revisit that.
109
- */
110
- function canonicalPath(pathname) {
111
- if (!pathname || pathname === "/")
112
- return "/";
113
- return pathname.split("/").map(encodeRfc3986).join("/");
114
- }
115
- /** Query parameters sorted by name, then by value, each side encoded. */
116
- function canonicalQuery(search) {
117
- const pairs = [];
118
- search.forEach((value, name) => pairs.push([encodeRfc3986(name), encodeRfc3986(value)]));
119
- 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));
120
- return pairs.map(([name, value]) => `${name}=${value}`).join("&");
121
- }
122
- /**
123
- * Header names lowercased, values trimmed with internal whitespace runs
124
- * collapsed, sorted by name. Returns the canonical block and the `;`-joined
125
- * signed-header list that has to agree with it exactly.
126
- */
127
- export function canonicalHeaders(headers) {
128
- const entries = Object.entries(headers)
129
- .map(([name, value]) => [name.toLowerCase().trim(), value.trim().replace(/\s+/g, " ")])
130
- .filter(([name]) => !UNSIGNABLE.has(name))
131
- .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
132
- return {
133
- canonical: entries.map(([name, value]) => `${name}:${value}\n`).join(""),
134
- signed: entries.map(([name]) => name).join(";"),
135
- };
136
- }
137
- /** The canonical request, verbatim as it is hashed into the string to sign. */
138
- export function canonicalRequest(method, url, headers, payloadHash) {
139
- const { canonical: headerBlock, signed } = canonicalHeaders(headers);
140
- return {
141
- canonical: [
142
- method.toUpperCase(),
143
- canonicalPath(url.pathname),
144
- canonicalQuery(url.searchParams),
145
- headerBlock,
146
- signed,
147
- payloadHash,
148
- ].join("\n"),
149
- signed,
150
- };
151
- }
152
- /** The string to sign: algorithm, timestamp, scope, hashed canonical request. */
153
- export function stringToSign(timestamp, scope, canonical) {
154
- return [ALGORITHM, timestamp, scope, sha256Hex(canonical)].join("\n");
155
- }
156
- /**
157
- * The caller's headers plus everything SigV4 adds: `x-amz-date`,
158
- * `x-amz-content-sha256`, `x-amz-security-token` when the credentials are
159
- * temporary, and the `Authorization` header itself.
160
- *
161
- * `host` is signed (AWS requires it) but not returned — see the module header.
162
- */
163
- export function signRequest(request) {
164
- const url = new URL(request.url);
165
- const timestamp = amzDate(request.now ?? new Date());
166
- const day = timestamp.slice(0, 8);
167
- const payloadHash = request.body.length === 0 ? EMPTY_PAYLOAD_SHA256 : sha256Hex(request.body);
168
- const signable = {
169
- ...request.headers,
170
- host: url.host,
171
- "x-amz-date": timestamp,
172
- "x-amz-content-sha256": payloadHash,
173
- ...(request.credentials.sessionToken ? { "x-amz-security-token": request.credentials.sessionToken } : {}),
174
- };
175
- const { canonical, signed } = canonicalRequest(request.method, url, signable, payloadHash);
176
- const scope = `${day}/${request.region}/${request.service}/${TERMINATOR}`;
177
- const key = signingKey(request.credentials.secretAccessKey, day, request.region, request.service);
178
- const signature = hmac(key, stringToSign(timestamp, scope, canonical)).toString("hex");
179
- const { host: _host, ...emitted } = signable;
180
- return {
181
- ...emitted,
182
- authorization: `${ALGORITHM} Credential=${request.credentials.accessKeyId}/${scope}, ` +
183
- `SignedHeaders=${signed}, Signature=${signature}`,
184
- };
185
- }
package/src/api/sigv4.ts DELETED
@@ -1,243 +0,0 @@
1
- /**
2
- * AWS Signature Version 4, for the shared read transport (#1686).
3
- *
4
- * Two modules asked for this by name before it existed: `./read-client.ts` and
5
- * cedar's `lexicons/cedar/src/avp/client.ts` both send a placeholder
6
- * `Signature=unsigned` `Authorization` header that carries a credential scope
7
- * and nothing else, and both say in prose that the real thing belongs here
8
- * once rather than twice. Nothing else in the repo signs an AWS request — the
9
- * appliers (`op/activities/aws-apply.ts`) are unsigned too, which is why the
10
- * native paths have been emulator-scoped.
11
- *
12
- * ## No dependency
13
- *
14
- * SigV4 is four HMACs and two SHA-256s. `node:crypto` has both, so signing
15
- * costs nothing in the dependency tree — which matters here, because the whole
16
- * reason these transports are hand-written is to keep `@aws-sdk/*` and its
17
- * thirty-odd transitive packages out of a lexicon.
18
- *
19
- * ## What is signed, and what is not
20
- *
21
- * Header signing only. Query-string (presigned-URL) signing has no caller: the
22
- * read paths POST to a service endpoint, they do not hand out URLs.
23
- *
24
- * `host` is signed but never emitted. `fetch` computes `Host` from the URL and
25
- * forbids overriding it, so the signer derives the same value from the URL it
26
- * was given. A transport that rewrites the URL underneath the signer — a proxy
27
- * that keeps the original `Host`, say — would invalidate the signature; the
28
- * injectable-HTTP seam is for tests and emulators, not for URL rewriting.
29
- */
30
- import { createHash, createHmac } from "node:crypto";
31
-
32
- const ALGORITHM = "AWS4-HMAC-SHA256";
33
- const TERMINATOR = "aws4_request";
34
-
35
- /** SHA-256 of the empty string — the payload hash of every bodyless request. */
36
- export const EMPTY_PAYLOAD_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
37
-
38
- /**
39
- * Headers that must not be signed even when a caller sets them: `authorization`
40
- * is the output, and the others are rewritten in transit by proxies and agents,
41
- * so signing them produces intermittent 403s rather than security.
42
- */
43
- const UNSIGNABLE = new Set(["authorization", "connection", "expect", "user-agent", "x-amzn-trace-id"]);
44
-
45
- /** A resolved credential set. `sessionToken` is present for STS/role credentials. */
46
- export interface AwsCredentials {
47
- accessKeyId: string;
48
- secretAccessKey: string;
49
- sessionToken?: string;
50
- }
51
-
52
- /**
53
- * The credential injection seam: a function the caller supplies to decide, by
54
- * whatever means it likes, what to sign with. Returning `undefined` means "this
55
- * process has no credentials" and is respected as an answer, not overridden.
56
- */
57
- export type AwsCredentialResolver = () => AwsCredentials | undefined;
58
-
59
- /** Either literal credentials or a resolver for them. */
60
- export type AwsCredentialSource = AwsCredentials | AwsCredentialResolver;
61
-
62
- /**
63
- * Credentials for a request: explicit → environment → absent.
64
- *
65
- * A resolver function is authoritative — if one is injected and it declines,
66
- * the environment is not consulted behind its back, because the point of
67
- * injecting one is to control the answer. Literal credentials are likewise
68
- * final. Only the no-source case falls through to `AWS_ACCESS_KEY_ID` /
69
- * `AWS_SECRET_ACCESS_KEY` (plus `AWS_SESSION_TOKEN` when set), and a half-set
70
- * environment — a key id with no secret — is absent rather than a signature
71
- * that cannot verify.
72
- *
73
- * The shared profile files are resolved asynchronously by
74
- * `./credential-chain.ts`, and the read transport passes its answer in as
75
- * literal credentials (#3958), so this function stays synchronous. Not
76
- * implemented anywhere: IMDS and the container credential endpoints.
77
- */
78
- export function resolveCredentials(
79
- source?: AwsCredentialSource,
80
- env: Record<string, string | undefined> = process.env,
81
- ): AwsCredentials | undefined {
82
- if (typeof source === "function") return source();
83
- if (source) return source;
84
- const accessKeyId = env.AWS_ACCESS_KEY_ID;
85
- const secretAccessKey = env.AWS_SECRET_ACCESS_KEY;
86
- if (!accessKeyId || !secretAccessKey) return undefined;
87
- return {
88
- accessKeyId,
89
- secretAccessKey,
90
- ...(env.AWS_SESSION_TOKEN ? { sessionToken: env.AWS_SESSION_TOKEN } : {}),
91
- };
92
- }
93
-
94
- /** One request to sign. `headers` are the caller's; the signer adds its own. */
95
- export interface SigV4Request {
96
- method: string;
97
- /** Absolute URL. Its host is signed and its path/query are canonicalized. */
98
- url: string;
99
- headers: Record<string, string>;
100
- body: string;
101
- /** Service name as it appears in the credential scope (`cloudformation`, `cloudcontrolapi`, …). */
102
- service: string;
103
- region: string;
104
- credentials: AwsCredentials;
105
- /** Signing clock. Injected by tests; otherwise now. */
106
- now?: Date;
107
- }
108
-
109
- /** `YYYYMMDDTHHMMSSZ` — the `X-Amz-Date` format, which is ISO-8601 basic. */
110
- export function amzDate(date: Date): string {
111
- return date.toISOString().replace(/[:-]|\.\d{3}/g, "");
112
- }
113
-
114
- /** Lowercase hex SHA-256. */
115
- export function sha256Hex(payload: string): string {
116
- return createHash("sha256").update(payload, "utf8").digest("hex");
117
- }
118
-
119
- function hmac(key: Buffer | string, data: string): Buffer {
120
- return createHmac("sha256", key).update(data, "utf8").digest();
121
- }
122
-
123
- /**
124
- * The signing key: four chained HMACs from the secret, so the key on the wire
125
- * is scoped to one day, one region and one service rather than being the
126
- * account secret itself.
127
- */
128
- export function signingKey(secretAccessKey: string, day: string, region: string, service: string): Buffer {
129
- const dateKey = hmac(`AWS4${secretAccessKey}`, day);
130
- const regionKey = hmac(dateKey, region);
131
- const serviceKey = hmac(regionKey, service);
132
- return hmac(serviceKey, TERMINATOR);
133
- }
134
-
135
- /**
136
- * RFC 3986 percent-encoding. `encodeURIComponent` leaves `!'()*` alone and AWS
137
- * does not, which is the difference between a signature that verifies and one
138
- * that does not for any path or parameter containing them.
139
- */
140
- function encodeRfc3986(value: string): string {
141
- return encodeURIComponent(value).replace(
142
- /[!'()*]/g,
143
- (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
144
- );
145
- }
146
-
147
- /**
148
- * The canonical path.
149
- *
150
- * Every caller of this module POSTs to `/`, so the one place implementations
151
- * genuinely diverge — S3 signs the path once-encoded, every other service signs
152
- * it twice-encoded — never arises. Segments are encoded once; a future caller
153
- * with a real path on a non-S3 service is the moment to revisit that.
154
- */
155
- function canonicalPath(pathname: string): string {
156
- if (!pathname || pathname === "/") return "/";
157
- return pathname.split("/").map(encodeRfc3986).join("/");
158
- }
159
-
160
- /** Query parameters sorted by name, then by value, each side encoded. */
161
- function canonicalQuery(search: URLSearchParams): string {
162
- const pairs: Array<[string, string]> = [];
163
- search.forEach((value, name) => pairs.push([encodeRfc3986(name), encodeRfc3986(value)]));
164
- 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));
165
- return pairs.map(([name, value]) => `${name}=${value}`).join("&");
166
- }
167
-
168
- /**
169
- * Header names lowercased, values trimmed with internal whitespace runs
170
- * collapsed, sorted by name. Returns the canonical block and the `;`-joined
171
- * signed-header list that has to agree with it exactly.
172
- */
173
- export function canonicalHeaders(headers: Record<string, string>): { canonical: string; signed: string } {
174
- const entries = Object.entries(headers)
175
- .map(([name, value]) => [name.toLowerCase().trim(), value.trim().replace(/\s+/g, " ")] as const)
176
- .filter(([name]) => !UNSIGNABLE.has(name))
177
- .sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
178
- return {
179
- canonical: entries.map(([name, value]) => `${name}:${value}\n`).join(""),
180
- signed: entries.map(([name]) => name).join(";"),
181
- };
182
- }
183
-
184
- /** The canonical request, verbatim as it is hashed into the string to sign. */
185
- export function canonicalRequest(
186
- method: string,
187
- url: URL,
188
- headers: Record<string, string>,
189
- payloadHash: string,
190
- ): { canonical: string; signed: string } {
191
- const { canonical: headerBlock, signed } = canonicalHeaders(headers);
192
- return {
193
- canonical: [
194
- method.toUpperCase(),
195
- canonicalPath(url.pathname),
196
- canonicalQuery(url.searchParams),
197
- headerBlock,
198
- signed,
199
- payloadHash,
200
- ].join("\n"),
201
- signed,
202
- };
203
- }
204
-
205
- /** The string to sign: algorithm, timestamp, scope, hashed canonical request. */
206
- export function stringToSign(timestamp: string, scope: string, canonical: string): string {
207
- return [ALGORITHM, timestamp, scope, sha256Hex(canonical)].join("\n");
208
- }
209
-
210
- /**
211
- * The caller's headers plus everything SigV4 adds: `x-amz-date`,
212
- * `x-amz-content-sha256`, `x-amz-security-token` when the credentials are
213
- * temporary, and the `Authorization` header itself.
214
- *
215
- * `host` is signed (AWS requires it) but not returned — see the module header.
216
- */
217
- export function signRequest(request: SigV4Request): Record<string, string> {
218
- const url = new URL(request.url);
219
- const timestamp = amzDate(request.now ?? new Date());
220
- const day = timestamp.slice(0, 8);
221
- const payloadHash = request.body.length === 0 ? EMPTY_PAYLOAD_SHA256 : sha256Hex(request.body);
222
-
223
- const signable: Record<string, string> = {
224
- ...request.headers,
225
- host: url.host,
226
- "x-amz-date": timestamp,
227
- "x-amz-content-sha256": payloadHash,
228
- ...(request.credentials.sessionToken ? { "x-amz-security-token": request.credentials.sessionToken } : {}),
229
- };
230
-
231
- const { canonical, signed } = canonicalRequest(request.method, url, signable, payloadHash);
232
- const scope = `${day}/${request.region}/${request.service}/${TERMINATOR}`;
233
- const key = signingKey(request.credentials.secretAccessKey, day, request.region, request.service);
234
- const signature = hmac(key, stringToSign(timestamp, scope, canonical)).toString("hex");
235
-
236
- const { host: _host, ...emitted } = signable;
237
- return {
238
- ...emitted,
239
- authorization:
240
- `${ALGORITHM} Credential=${request.credentials.accessKeyId}/${scope}, ` +
241
- `SignedHeaders=${signed}, Signature=${signature}`,
242
- };
243
- }