@heroku/heroku-fetch 0.2.6 → 0.4.0
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.
- package/README.md +30 -12
- package/dist/client/index.d.ts +3 -2
- package/dist/client/index.js +7 -8
- package/dist/client/service-configurations.d.ts +8 -0
- package/dist/client/service-configurations.js +78 -12
- package/dist/redact.d.ts +2 -2
- package/dist/redact.js +9 -14
- package/dist/types.d.ts +2 -6
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -55,18 +55,39 @@ const dataClient = new HerokuApiClient({
|
|
|
55
55
|
token: 'your_token',
|
|
56
56
|
});
|
|
57
57
|
|
|
58
|
-
//
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
58
|
+
// The data client's host comes from HEROKU_DATA_HOST, then
|
|
59
|
+
// HEROKU_POSTGRESQL_HOST, then https://api.data.heroku.com. A bare hostname
|
|
60
|
+
// gets https://. An explicit baseUrl takes precedence.
|
|
61
|
+
//
|
|
62
|
+
// Every environment-configured service host must use heroku.com, herokai.com,
|
|
63
|
+
// herokuspace.com, herokudev.com, or the loopback hosts localhost, 127.0.0.1
|
|
64
|
+
// and [::1]. Remote hosts require HTTPS; HTTP is allowed only for loopback.
|
|
65
|
+
// This applies to HEROKU_DATA_HOST, HEROKU_POSTGRESQL_HOST,
|
|
66
|
+
// HEROKU_METRICS_HOST, HEROKU_NOTIFICATIONS_HOST, HEROKU_PARTICLEBOARD_URL
|
|
67
|
+
// and HEROKU_REPOSITORIES_HOST.
|
|
68
|
+
// Configured URLs are reduced to their origin; user information, non-root
|
|
69
|
+
// paths, queries and fragments are rejected. Explicit baseUrl values remain
|
|
70
|
+
// the caller's responsibility. In particular, *.herokuapp.com is not trusted
|
|
71
|
+
// for environment-configured hosts; internal staging setups should use an
|
|
72
|
+
// approved Heroku-owned hostname instead.
|
|
73
|
+
|
|
74
|
+
// Metrics. The host comes from HEROKU_METRICS_HOST, then
|
|
75
|
+
// api.metrics.heroku.com. An explicit baseUrl takes precedence.
|
|
76
|
+
const metricsClient = new HerokuApiClient({
|
|
77
|
+
service: 'metrics',
|
|
62
78
|
token: 'your_token',
|
|
63
79
|
});
|
|
64
80
|
|
|
65
|
-
//
|
|
66
|
-
//
|
|
67
|
-
//
|
|
81
|
+
// Notifications (telex) and repositories (kolkrabbi). Their hosts come from
|
|
82
|
+
// HEROKU_NOTIFICATIONS_HOST / HEROKU_REPOSITORIES_HOST, then telex.heroku.com /
|
|
83
|
+
// kolkrabbi.heroku.com. Neither sends a default Accept header.
|
|
84
|
+
const notificationsClient = new HerokuApiClient({
|
|
85
|
+
service: 'notifications',
|
|
86
|
+
token: 'your_token',
|
|
87
|
+
});
|
|
68
88
|
|
|
69
|
-
// Particleboard
|
|
89
|
+
// Particleboard. The host comes from HEROKU_PARTICLEBOARD_URL, then
|
|
90
|
+
// particleboard.heroku.com. An explicit baseUrl takes precedence.
|
|
70
91
|
const particleboardClient = new HerokuApiClient({
|
|
71
92
|
service: 'particleboard',
|
|
72
93
|
token: 'your_token',
|
|
@@ -355,7 +376,7 @@ localStorage.debug = 'heroku-fetch:*';
|
|
|
355
376
|
```typescript
|
|
356
377
|
interface HerokuApiClientOptions {
|
|
357
378
|
/** Heroku service type */
|
|
358
|
-
service?: 'platform' | 'data' | 'particleboard' | 'custom';
|
|
379
|
+
service?: 'platform' | 'data' | 'metrics' | 'notifications' | 'particleboard' | 'repositories' | 'custom';
|
|
359
380
|
|
|
360
381
|
/** Static bearer token or function to retrieve token */
|
|
361
382
|
token?: string | (() => string | Promise<string>);
|
|
@@ -368,9 +389,6 @@ interface HerokuApiClientOptions {
|
|
|
368
389
|
/** Custom base URL (required for 'custom' service) */
|
|
369
390
|
baseUrl?: string;
|
|
370
391
|
|
|
371
|
-
/** Service region (e.g., 'eu', 'us') */
|
|
372
|
-
region?: string;
|
|
373
|
-
|
|
374
392
|
/** Request timeout in milliseconds (default: 30000) */
|
|
375
393
|
timeout?: number;
|
|
376
394
|
|
package/dist/client/index.d.ts
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Heroku API Client
|
|
3
3
|
*
|
|
4
4
|
* Main client class for making HTTP requests to Heroku APIs.
|
|
5
|
-
* Supports multiple services (platform, data, particleboard), authentication,
|
|
5
|
+
* Supports multiple services (platform, data, metrics, notifications, particleboard, repositories), authentication,
|
|
6
6
|
* two-factor authentication, and comprehensive error handling.
|
|
7
7
|
*/
|
|
8
8
|
import type { HerokuApiClientOptions, RequestOptions } from '../types.js';
|
|
@@ -95,7 +95,8 @@ export declare class HerokuApiClient {
|
|
|
95
95
|
*
|
|
96
96
|
* Replaying a non-idempotent write this way is safe for Heroku's front-door
|
|
97
97
|
* auth, which rejects a 401 before the server executes the request. It is not
|
|
98
|
-
* universally safe: a
|
|
98
|
+
* universally safe: a host other than platform (`data`, `metrics`,
|
|
99
|
+
* `notifications`, `particleboard`, `repositories`, `custom`) that returns a
|
|
99
100
|
* downstream or proxied 401 *after* side effects have begun would see the
|
|
100
101
|
* write run twice. Opt such a request out with `reauthorize: false`.
|
|
101
102
|
*/
|
package/dist/client/index.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
* Heroku API Client
|
|
3
3
|
*
|
|
4
4
|
* Main client class for making HTTP requests to Heroku APIs.
|
|
5
|
-
* Supports multiple services (platform, data, particleboard), authentication,
|
|
5
|
+
* Supports multiple services (platform, data, metrics, notifications, particleboard, repositories), authentication,
|
|
6
6
|
* two-factor authentication, and comprehensive error handling.
|
|
7
7
|
*/
|
|
8
8
|
import { getDefaultFetch, getDefaultTokenProvider, getDefaultTwoFactorOptions, getUserAgentComment, } from '@heroku/heroku-fetch/client/environment-defaults.js';
|
|
@@ -53,14 +53,12 @@ export class HerokuApiClient {
|
|
|
53
53
|
}
|
|
54
54
|
// Determine base URL
|
|
55
55
|
const serviceConfig = SERVICE_CONFIGS[this.options.service];
|
|
56
|
-
let baseUrl = options.baseUrl || serviceConfig.baseUrl;
|
|
57
56
|
if (this.options.service === 'custom' && !options.baseUrl) {
|
|
58
57
|
throw new Error('baseUrl is required when service is "custom"');
|
|
59
58
|
}
|
|
60
|
-
//
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
}
|
|
59
|
+
// `||` keeps the service default unread when baseUrl is set: its getter
|
|
60
|
+
// validates the host env vars, and an unused one mustn't fail the client.
|
|
61
|
+
const baseUrl = options.baseUrl || serviceConfig.baseUrl;
|
|
64
62
|
debugAuth('Initializing client for service: %s, baseUrl: %s', this.options.service, baseUrl);
|
|
65
63
|
// Stash the ky options; the actual ky instance is built lazily so
|
|
66
64
|
// we can await getDefaultFetch() (Node loads undici dynamically for
|
|
@@ -166,7 +164,7 @@ export class HerokuApiClient {
|
|
|
166
164
|
}
|
|
167
165
|
// Only these are re-read on each request, so changing them takes effect.
|
|
168
166
|
// hooks, headers, the Accept default, the 2FA handler, and the
|
|
169
|
-
// service
|
|
167
|
+
// service base URL are baked into the cached ky instance at
|
|
170
168
|
// construction, so mutating them here would silently no-op — reject rather
|
|
171
169
|
// than lie about the change landing. `reauthorize` IS read per request (so a
|
|
172
170
|
// mutation would land), but is deliberately kept construction-only: it's an
|
|
@@ -295,7 +293,8 @@ export class HerokuApiClient {
|
|
|
295
293
|
*
|
|
296
294
|
* Replaying a non-idempotent write this way is safe for Heroku's front-door
|
|
297
295
|
* auth, which rejects a 401 before the server executes the request. It is not
|
|
298
|
-
* universally safe: a
|
|
296
|
+
* universally safe: a host other than platform (`data`, `metrics`,
|
|
297
|
+
* `notifications`, `particleboard`, `repositories`, `custom`) that returns a
|
|
299
298
|
* downstream or proxied 401 *after* side effects have begun would see the
|
|
300
299
|
* write run twice. Opt such a request out with `reauthorize: false`.
|
|
301
300
|
*/
|
|
@@ -1,2 +1,10 @@
|
|
|
1
1
|
import type { HerokuService, ServiceConfig } from '../types.js';
|
|
2
|
+
/**
|
|
3
|
+
* Per-service defaults. Services whose host can be overridden by an environment
|
|
4
|
+
* variable use a `baseUrl` getter, so the variable is read when each client is
|
|
5
|
+
* built, not at import. `data` honors `HEROKU_DATA_HOST`, then
|
|
6
|
+
* `HEROKU_POSTGRESQL_HOST`, the variables the Heroku CLI has long used for the
|
|
7
|
+
* data API. `notifications` and `repositories` set no Accept default,
|
|
8
|
+
* matching what those hosts have always been sent.
|
|
9
|
+
*/
|
|
2
10
|
export declare const SERVICE_CONFIGS: Record<HerokuService, ServiceConfig>;
|
|
@@ -1,17 +1,66 @@
|
|
|
1
1
|
const HEROKU_V3_ACCEPT = 'application/vnd.heroku+json; version=3';
|
|
2
|
+
const LOOPBACK_HOSTNAMES = new Set(['127.0.0.1', '[::1]', 'localhost']);
|
|
3
|
+
const TRUSTED_HEROKU_DOMAINS = ['heroku.com', 'herokai.com', 'herokuspace.com', 'herokudev.com'];
|
|
2
4
|
/**
|
|
3
|
-
* The
|
|
4
|
-
*
|
|
5
|
-
*
|
|
6
|
-
*
|
|
5
|
+
* The base URL from the first of `variables` that is set, else `fallback`.
|
|
6
|
+
* Values are trimmed, and blank ones are skipped. A bare hostname gets `https://`;
|
|
7
|
+
* a value with an `http://` or `https://` scheme is parsed as given.
|
|
8
|
+
* `process` and `process.env` are guarded for browser builds.
|
|
9
|
+
*
|
|
10
|
+
* Hostnames must be in an approved Heroku domain or loopback. Plain `http://` is
|
|
11
|
+
* allowed only for loopback hosts (local development), so the client's bearer
|
|
12
|
+
* token is never sent unencrypted to a remote host. Errors name the variable but
|
|
13
|
+
* never echo its value.
|
|
7
14
|
*/
|
|
8
|
-
function
|
|
15
|
+
function envBaseUrl(variables, fallback) {
|
|
9
16
|
const env = typeof process === 'undefined' ? undefined : process.env;
|
|
10
|
-
const
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
17
|
+
for (const variable of variables) {
|
|
18
|
+
const value = env?.[variable]?.trim();
|
|
19
|
+
if (!value)
|
|
20
|
+
continue;
|
|
21
|
+
return validatedEnvBaseUrl(variable, value);
|
|
22
|
+
}
|
|
23
|
+
return fallback;
|
|
14
24
|
}
|
|
25
|
+
function validatedEnvBaseUrl(variable, value) {
|
|
26
|
+
const explicitScheme = /^[a-z][a-z\d+.-]*:\/\//i.test(value);
|
|
27
|
+
const candidate = explicitScheme ? value : `https://${value}`;
|
|
28
|
+
let url;
|
|
29
|
+
try {
|
|
30
|
+
url = new URL(candidate);
|
|
31
|
+
}
|
|
32
|
+
catch {
|
|
33
|
+
throw new Error(`${variable} must be a valid Heroku service URL`);
|
|
34
|
+
}
|
|
35
|
+
if (url.protocol !== 'http:' && url.protocol !== 'https:') {
|
|
36
|
+
throw new Error(`${variable} must use http:// or https://`);
|
|
37
|
+
}
|
|
38
|
+
// URL.username/password omit an empty `@`, so also check the input for that
|
|
39
|
+
// delimiter before accepting the parsed URL.
|
|
40
|
+
if (url.username || url.password || candidate.includes('@')) {
|
|
41
|
+
throw new Error(`${variable} must not include user information`);
|
|
42
|
+
}
|
|
43
|
+
if (url.pathname !== '/' || url.search || url.hash || candidate.includes('?') || candidate.includes('#')) {
|
|
44
|
+
throw new Error(`${variable} must not include a path, query, or fragment`);
|
|
45
|
+
}
|
|
46
|
+
const loopback = LOOPBACK_HOSTNAMES.has(url.hostname);
|
|
47
|
+
if (url.protocol === 'http:' && !loopback) {
|
|
48
|
+
throw new Error(`${variable} must use https:// unless it points at localhost`);
|
|
49
|
+
}
|
|
50
|
+
const approvedDomain = TRUSTED_HEROKU_DOMAINS.some(domain => url.hostname === domain || url.hostname.endsWith(`.${domain}`));
|
|
51
|
+
if (!loopback && !approvedDomain) {
|
|
52
|
+
throw new Error(`${variable} must use a heroku.com, herokai.com, herokuspace.com, or herokudev.com host`);
|
|
53
|
+
}
|
|
54
|
+
return url.origin;
|
|
55
|
+
}
|
|
56
|
+
/**
|
|
57
|
+
* Per-service defaults. Services whose host can be overridden by an environment
|
|
58
|
+
* variable use a `baseUrl` getter, so the variable is read when each client is
|
|
59
|
+
* built, not at import. `data` honors `HEROKU_DATA_HOST`, then
|
|
60
|
+
* `HEROKU_POSTGRESQL_HOST`, the variables the Heroku CLI has long used for the
|
|
61
|
+
* data API. `notifications` and `repositories` set no Accept default,
|
|
62
|
+
* matching what those hosts have always been sent.
|
|
63
|
+
*/
|
|
15
64
|
export const SERVICE_CONFIGS = {
|
|
16
65
|
custom: {
|
|
17
66
|
// Must be provided by user; no Accept default — the URL may be
|
|
@@ -20,18 +69,35 @@ export const SERVICE_CONFIGS = {
|
|
|
20
69
|
baseUrl: '',
|
|
21
70
|
},
|
|
22
71
|
data: {
|
|
23
|
-
// A getter so the environment is read when each client is built, not at import.
|
|
24
72
|
get baseUrl() {
|
|
25
|
-
return
|
|
73
|
+
return envBaseUrl(['HEROKU_DATA_HOST', 'HEROKU_POSTGRESQL_HOST'], 'https://api.data.heroku.com');
|
|
74
|
+
},
|
|
75
|
+
defaultAccept: HEROKU_V3_ACCEPT,
|
|
76
|
+
},
|
|
77
|
+
metrics: {
|
|
78
|
+
get baseUrl() {
|
|
79
|
+
return envBaseUrl(['HEROKU_METRICS_HOST'], 'https://api.metrics.heroku.com');
|
|
26
80
|
},
|
|
27
81
|
defaultAccept: HEROKU_V3_ACCEPT,
|
|
28
82
|
},
|
|
83
|
+
notifications: {
|
|
84
|
+
get baseUrl() {
|
|
85
|
+
return envBaseUrl(['HEROKU_NOTIFICATIONS_HOST'], 'https://telex.heroku.com');
|
|
86
|
+
},
|
|
87
|
+
},
|
|
29
88
|
particleboard: {
|
|
30
|
-
baseUrl
|
|
89
|
+
get baseUrl() {
|
|
90
|
+
return envBaseUrl(['HEROKU_PARTICLEBOARD_URL'], 'https://particleboard.heroku.com');
|
|
91
|
+
},
|
|
31
92
|
defaultAccept: HEROKU_V3_ACCEPT,
|
|
32
93
|
},
|
|
33
94
|
platform: {
|
|
34
95
|
baseUrl: 'https://api.heroku.com',
|
|
35
96
|
defaultAccept: HEROKU_V3_ACCEPT,
|
|
36
97
|
},
|
|
98
|
+
repositories: {
|
|
99
|
+
get baseUrl() {
|
|
100
|
+
return envBaseUrl(['HEROKU_REPOSITORIES_HOST'], 'https://kolkrabbi.heroku.com');
|
|
101
|
+
},
|
|
102
|
+
},
|
|
37
103
|
};
|
package/dist/redact.d.ts
CHANGED
|
@@ -7,8 +7,8 @@
|
|
|
7
7
|
/**
|
|
8
8
|
* Scrub a value for debug logging. Handles `Error`, `Headers`, plain objects,
|
|
9
9
|
* and primitives (passed through unchanged — a top-level string is not
|
|
10
|
-
* pattern-scrubbed; `
|
|
11
|
-
* scrubbed object/Error). Fail-closed: any failure returns `'[unscrubbable]'`
|
|
10
|
+
* pattern-scrubbed; `CREDENTIAL_PATTERNS` only apply to strings nested inside
|
|
11
|
+
* a scrubbed object/Error). Fail-closed: any failure returns `'[unscrubbable]'`
|
|
12
12
|
* rather than risking the raw value. `depth` is internal, for `cause`
|
|
13
13
|
* recursion.
|
|
14
14
|
*/
|
package/dist/redact.js
CHANGED
|
@@ -17,16 +17,6 @@ const EXTRA_FIELDS = [
|
|
|
17
17
|
'otp',
|
|
18
18
|
'sso',
|
|
19
19
|
];
|
|
20
|
-
/**
|
|
21
|
-
* Redact inline `Bearer`/`Basic` credentials in string leaf values reached
|
|
22
|
-
* while scrubbing an object or Error (e.g. an error message). Bare UUIDs/JWTs
|
|
23
|
-
* are intentionally not matched — they're indistinguishable from benign
|
|
24
|
-
* resource IDs. Note these patterns don't apply to a top-level string passed
|
|
25
|
-
* straight to `scrubForLog`.
|
|
26
|
-
*/
|
|
27
|
-
const VALUE_PATTERNS = [
|
|
28
|
-
/\b(?:Bearer|Basic)\s+[\w.~+/=-]+/gi,
|
|
29
|
-
];
|
|
30
20
|
/** Cap on `error.cause` recursion depth; guards against cyclic chains. */
|
|
31
21
|
const MAX_CAUSE_DEPTH = 8;
|
|
32
22
|
let scrubberPromise;
|
|
@@ -34,13 +24,18 @@ let scrubberPromise;
|
|
|
34
24
|
async function getScrubber() {
|
|
35
25
|
if (!scrubberPromise) {
|
|
36
26
|
scrubberPromise = (async () => {
|
|
37
|
-
const [{ Scrubber }, { HEROKU_FIELDS }] = await Promise.all([
|
|
27
|
+
const [{ Scrubber }, { HEROKU_FIELDS }, { CREDENTIAL_PATTERNS }] = await Promise.all([
|
|
38
28
|
import('@heroku/js-blanket/core/scrubber'),
|
|
39
29
|
import('@heroku/js-blanket/core/presets'),
|
|
30
|
+
import('@heroku/js-blanket/core/patterns'),
|
|
40
31
|
]);
|
|
32
|
+
// CREDENTIAL_PATTERNS redact credentials in string values reached while
|
|
33
|
+
// scrubbing an object or Error, such as an error message: Heroku API
|
|
34
|
+
// tokens, Authorization values, Bearer/Basic credentials, URL passwords
|
|
35
|
+
// and PEM private keys. Each keeps its context (`Bearer [REDACTED]`).
|
|
41
36
|
return new Scrubber({
|
|
42
37
|
fields: [...HEROKU_FIELDS, ...EXTRA_FIELDS],
|
|
43
|
-
patterns:
|
|
38
|
+
patterns: CREDENTIAL_PATTERNS,
|
|
44
39
|
replacement: REPLACEMENT,
|
|
45
40
|
});
|
|
46
41
|
})();
|
|
@@ -122,8 +117,8 @@ async function scrubError(error, depth) {
|
|
|
122
117
|
/**
|
|
123
118
|
* Scrub a value for debug logging. Handles `Error`, `Headers`, plain objects,
|
|
124
119
|
* and primitives (passed through unchanged — a top-level string is not
|
|
125
|
-
* pattern-scrubbed; `
|
|
126
|
-
* scrubbed object/Error). Fail-closed: any failure returns `'[unscrubbable]'`
|
|
120
|
+
* pattern-scrubbed; `CREDENTIAL_PATTERNS` only apply to strings nested inside
|
|
121
|
+
* a scrubbed object/Error). Fail-closed: any failure returns `'[unscrubbable]'`
|
|
127
122
|
* rather than risking the raw value. `depth` is internal, for `cause`
|
|
128
123
|
* recursion.
|
|
129
124
|
*/
|
package/dist/types.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export type HerokuService = 'custom' | 'data' | 'particleboard' | 'platform';
|
|
1
|
+
export type HerokuService = 'custom' | 'data' | 'metrics' | 'notifications' | 'particleboard' | 'platform' | 'repositories';
|
|
2
2
|
/**
|
|
3
3
|
* A `beforeRequest` hook: runs after the client's built-ins have prepared the
|
|
4
4
|
* `Request` and may inspect or mutate it, or return a replacement `Request`/
|
|
@@ -95,8 +95,6 @@ export interface ServiceConfig {
|
|
|
95
95
|
* type.
|
|
96
96
|
*/
|
|
97
97
|
defaultAccept?: string;
|
|
98
|
-
/** Default region (if applicable) */
|
|
99
|
-
region?: string;
|
|
100
98
|
}
|
|
101
99
|
/**
|
|
102
100
|
* Identifies the consumer in the `User-Agent` header: a product `name` and
|
|
@@ -182,9 +180,7 @@ export interface HerokuApiClientOptions {
|
|
|
182
180
|
reauthorize?: (context: {
|
|
183
181
|
signal?: AbortSignal;
|
|
184
182
|
}) => Promise<void> | void;
|
|
185
|
-
/**
|
|
186
|
-
region?: string;
|
|
187
|
-
/** Heroku service type (platform, data, particleboard, custom) */
|
|
183
|
+
/** Heroku service type (platform, data, metrics, notifications, particleboard, repositories, custom) */
|
|
188
184
|
service?: HerokuService;
|
|
189
185
|
/**
|
|
190
186
|
* Default `AbortSignal` applied to every request this client makes: when it
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@heroku/heroku-fetch",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
4
4
|
"description": "A JavaScript/TypeScript API client for Heroku APIs",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -50,7 +50,7 @@
|
|
|
50
50
|
},
|
|
51
51
|
"homepage": "https://github.com/heroku/heroku-fetch#readme",
|
|
52
52
|
"dependencies": {
|
|
53
|
-
"@heroku/js-blanket": "^1.
|
|
53
|
+
"@heroku/js-blanket": "^1.4.0",
|
|
54
54
|
"debug": "^4.3.4",
|
|
55
55
|
"ky": "^2.2.0",
|
|
56
56
|
"undici": "^8.11.2"
|