1 | // Type definitions for aws4 1.11
|
2 | // Project: https://github.com/mhart/aws4
|
3 | // Definitions by: Andrew Crites <https://github.com/ajcrites>
|
4 | // Alexandre Szymocha <https://github.com/Aksamyt>
|
5 | // Definitions: https://github.com/DefinitelyTyped/DefinitelyTyped
|
6 | // Minimum TypeScript Version: 3.9
|
7 |
|
8 | /// <reference types="node" />
|
9 |
|
10 | import { OutgoingHttpHeaders, RequestOptions } from 'http';
|
11 |
|
12 | export interface Request extends RequestOptions {
|
13 | /** Defaults to {@link RequestSigner.createHost}() if possible. */
|
14 | host?: string;
|
15 | /** Equivalent to {@link host} */
|
16 | hostname?: string;
|
17 | /** Defaults to `"GET"`, or `"POST"` if there is a {@link body}. */
|
18 | method?: string;
|
19 | /** Defaults to `/`. */
|
20 | path?: string;
|
21 | /** Defaults to `""`. */
|
22 | body?: string;
|
23 | /** Defaults to {@link RequestSigner.matchHost}()[0], or `""`. */
|
24 | service?: string;
|
25 | /** Defaults to {@link RequestSigner.matchHost}()[1], or `"us-east-1"`. */
|
26 | region?: string;
|
27 | /** To sign the query instead of adding an Authorization header, defaults to false. */
|
28 | signQuery?: boolean;
|
29 | /**
|
30 | * Some headers have a default value:
|
31 | * - `Host`: Defaults to {@link hostname}, {@link host}, or
|
32 | * {@link RequestSigner.createHost}()
|
33 | * - `Content-Type`: defaults to
|
34 | * `"application/x-www-form-urlencoded; charset=utf-8"`
|
35 | * if there is a {@link body}
|
36 | * - `Date`: used to calculate the signature date if given, defaults to
|
37 | * `new Date()`
|
38 | */
|
39 | headers?: OutgoingHttpHeaders;
|
40 | /** If true, signing the Request won’t mutate the headers. */
|
41 | doNotModifyHeaders?: boolean;
|
42 | /** If true, {@link path} won’t be encoded in the signature. */
|
43 | doNotEncodePath?: boolean;
|
44 | }
|
45 |
|
46 | export interface Credentials {
|
47 | /** Equivalent to the env vars `AWS_ACCESS_KEY_ID` and `AWS_ACCESS_KEY`. */
|
48 | accessKeyId?: string;
|
49 | /** Equivalent to the env vars `AWS_SECRET_ACCESS_KEY` and `AWS_SECRET_KEY`. */
|
50 | secretAccessKey?: string;
|
51 | /** Equivalent to the env var `AWS_SESSION_TOKEN`. */
|
52 | sessionToken?: string;
|
53 | }
|
54 |
|
55 | export class RequestSigner {
|
56 | constructor(requestOptions: string | Request, credentials?: Credentials);
|
57 |
|
58 | request: Request;
|
59 | credentials: Credentials;
|
60 | service: string;
|
61 | region: string;
|
62 |
|
63 | /**
|
64 | * `true` if {`"codecommit"` and { request}.method
service} is |
65 | * is `"GIT"`.
|
66 | */
|
67 | isCodeCommitGit: boolean;
|
68 |
|
69 | /**
|
70 | * Set by:
|
71 | * - {@link prepareRequest}
|
72 | * - {@link sign}
|
73 | * - {@link canonicalString}
|
74 | * - {@link parsePath}
|
75 | */
|
76 | parsedPath?: {
|
77 | path: string;
|
78 | query: Record<string, string | string[]>;
|
79 | };
|
80 |
|
81 | /**
|
82 | * Used as a cache by {@link getDateTime} and {@link getDate}.
|
83 | * Setting it will shortcut those functions.
|
84 | *
|
85 | * Set by:
|
86 | * - {@link prepareRequest}
|
87 | * - {@link getDateTime}
|
88 | * - {@link sign}
|
89 | */
|
90 | datetime?: string;
|
91 |
|
92 | /**
|
93 | * Extract the service code and region code from a Host name.
|
94 | * @returns two element string tuple with values [service, region].
|
95 | */
|
96 | matchHost(host: string): [string, string];
|
97 |
|
98 | /**
|
99 | * https://docs.aws.amazon.com/general/latest/gr/rande.html
|
100 | */
|
101 | isSingleRegion(): boolean;
|
102 |
|
103 | /**
|
104 | * Compute the Host name from the {@link service} and the {@link region}.
|
105 | */
|
106 | createHost(): string;
|
107 |
|
108 | /**
|
109 | * Generate the Authorization header value.
|
110 | */
|
111 | authHeader(): string;
|
112 |
|
113 | /**
|
114 | * Generate a string representation of {@link request}.headers:
|
115 | * - one header per line, formatted as `<key>:<value>`
|
116 | * - lines are sorted.
|
117 | * - `<key>` is in lowercase and is trimmed.
|
118 | * - `<value>` is trimmed, and contiguous whitespaces are reduced to a
|
119 | * single space character ` `.
|
120 | *
|
121 | * These headers are filtered out:
|
122 | * - `authorization`
|
123 | * - `connection`
|
124 | * - `x-amzn-trace-id`
|
125 | * - `user-agent`
|
126 | * - `expect`
|
127 | * - `presigned-expires`
|
128 | * - `range`
|
129 | */
|
130 | canonicalHeaders(): string;
|
131 |
|
132 | /**
|
133 | * Generates a list of the header names of {@link request}.headers separated
|
134 | * by `;`.
|
135 | *
|
136 | * These headers are filtered out:
|
137 | * - `authorization`
|
138 | * - `connection`
|
139 | * - `x-amzn-trace-id`
|
140 | * - `user-agent`
|
141 | * - `expect`
|
142 | * - `presigned-expires`
|
143 | * - `range`
|
144 | */
|
145 | signedHeaders(): string;
|
146 |
|
147 | /**
|
148 | * Generate the “credential scope” part of the signature.
|
149 | */
|
150 | credentialString(): string;
|
151 |
|
152 | /**
|
153 | * Extract credentials from the environment, if found.
|
154 | */
|
155 | defaultCredentials(): Credentials;
|
156 |
|
157 | /**
|
158 | * Parse {@link request}.path and store the results in {@link parsedPath}.
|
159 | */
|
160 | parsePath(): void;
|
161 |
|
162 | /**
|
163 | * **Will throw if {@link parsedPath} is undefined!**
|
164 | *
|
165 | * Rebuild the path from {@link parsedPath}.
|
166 | */
|
167 | formatPath(): string;
|
168 |
|
169 | /**
|
170 | * Sign the Request. The Request is returned for convenience.
|
171 | */
|
172 | sign(): Request;
|
173 |
|
174 | /**
|
175 | * Calls {@link parsePath}.
|
176 | * Prepare the Request by setting the required headers,
|
177 | * or query parameters if {@link request}.signQuery is true.
|
178 | */
|
179 | prepareRequest(): void;
|
180 |
|
181 | /**
|
182 | * If {@link datetime} is set, it is returned without further processing.
|
183 | *
|
184 | * Else, parse the `Date` header from {@link request}.headers,
|
185 | * or get the current date, and format it as (ISO 8601):
|
186 | * ```
|
187 | * YYYYMMDDThhmmssZ
|
188 | * ```
|
189 | * If {@link isCodeCommitGit} is `true`, then the trailing `Z` is removed.
|
190 | *
|
191 | * The result is stored to {@link datetime} before being returned.
|
192 | */
|
193 | getDateTime(): string;
|
194 |
|
195 | /**
|
196 | * If {@link datetime} is set, its first 8 characters are returned.
|
197 | *
|
198 | * Else, call {@link getDateTime} and return the first 8 characters.
|
199 | */
|
200 | getDate(): string;
|
201 |
|
202 | /**
|
203 | * Generate a string representation of the Request.
|
204 | * https://docs.aws.amazon.com/general/latest/gr/sigv4-create-canonical-request.html
|
205 | */
|
206 | canonicalString(): string;
|
207 |
|
208 | /**
|
209 | * Compute the Request HMAC signature.
|
210 | */
|
211 | signature(): string;
|
212 |
|
213 | /**
|
214 | * Generate the raw data to be signed.
|
215 | * https://docs.aws.amazon.com/general/latest/gr/sigv4-create-string-to-sign.html
|
216 | */
|
217 | stringToSign(): string;
|
218 | }
|
219 |
|
220 | /**
|
221 | * Calculates and populates any necessary AWS headers and/or request options on
|
222 | * `requestOptions`. Returns `requestOptions` as a convenience for chaining.
|
223 | */
|
224 | export function sign(requestOptions: string | Request, credentials?: Credentials): Request;
|