@fabrika/app 0.9.0-cloudflare.1 → 0.9.0-cloudflare.3
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/package.json +9 -9
- package/skill/SKILL.md +21 -17
- package/skill/references/app-setup.md +42 -11
- package/skill/references/endpoint.md +29 -22
- package/skill/references/errors.md +32 -31
- package/skill/references/jobs.md +22 -3
- package/skill/references/tests.md +29 -1
- package/src/build.ts +6 -1
- package/src/bun.ts +168 -5
- package/src/cloudflare/application.ts +546 -76
- package/src/cloudflare/bindings.ts +26 -5
- package/src/cloudflare/export.ts +621 -0
- package/src/cloudflare/import.ts +1097 -0
- package/src/cloudflare/maintenance.ts +518 -0
- package/src/cloudflare/names.ts +6 -0
- package/src/cloudflare/ops.ts +147 -18
- package/src/cloudflare/restore.ts +167 -0
- package/src/cloudflare/tracker.ts +192 -0
- package/src/cloudflare.ts +3 -2
- package/src/contract/artifact-schema.ts +13 -2
- package/src/contract/build.ts +38 -11
- package/src/contract/context.ts +26 -9
- package/src/contract/defaults.ts +22 -2
- package/src/contract/define.ts +1 -1
- package/src/contract/group.ts +10 -1
- package/src/contract/kit.ts +2 -1
- package/src/disk-assets.ts +8 -3
- package/src/files/kinds.ts +54 -24
- package/src/implement/anonymous.ts +1 -10
- package/src/implement/boot.ts +30 -12
- package/src/implement/capability.ts +3 -0
- package/src/implement/dispatch.ts +175 -37
- package/src/implement/egress.ts +367 -8
- package/src/implement/invocation.ts +60 -19
- package/src/implement/workload.ts +18 -3
- package/src/jobs/runner.ts +646 -98
- package/src/spa-fallback.ts +12 -0
- package/src/testing/endpoint-access.ts +135 -23
- package/src/testing/isolation.ts +8 -1
- package/src/testing/kit.ts +60 -0
- package/types/src/build.d.ts +1 -1
- package/types/src/bun.d.ts +34 -1
- package/types/src/cloudflare/application.d.ts +36 -5
- package/types/src/cloudflare/bindings.d.ts +6 -0
- package/types/src/cloudflare/export.d.ts +16 -0
- package/types/src/cloudflare/import.d.ts +58 -0
- package/types/src/cloudflare/maintenance.d.ts +117 -0
- package/types/src/cloudflare/names.d.ts +5 -0
- package/types/src/cloudflare/ops.d.ts +39 -4
- package/types/src/cloudflare/restore.d.ts +9 -0
- package/types/src/cloudflare/tracker.d.ts +29 -0
- package/types/src/cloudflare.d.ts +2 -1
- package/types/src/contract/artifact-schema.d.ts +2 -0
- package/types/src/contract/context.d.ts +24 -9
- package/types/src/contract/defaults.d.ts +19 -1
- package/types/src/contract/define.d.ts +1 -1
- package/types/src/contract/group.d.ts +9 -1
- package/types/src/contract/kit.d.ts +2 -2
- package/types/src/disk-assets.d.ts +4 -1
- package/types/src/files/kinds.d.ts +17 -6
- package/types/src/implement/anonymous.d.ts +0 -4
- package/types/src/implement/boot.d.ts +17 -0
- package/types/src/implement/capability.d.ts +2 -0
- package/types/src/implement/dispatch.d.ts +33 -1
- package/types/src/implement/egress.d.ts +36 -1
- package/types/src/implement/invocation.d.ts +20 -10
- package/types/src/implement/workload.d.ts +5 -0
- package/types/src/jobs/runner.d.ts +63 -2
- package/types/src/spa-fallback.d.ts +2 -0
- package/types/src/testing/endpoint-access.d.ts +25 -1
- package/types/src/testing/isolation.d.ts +1 -1
- package/types/src/testing/kit.d.ts +16 -0
package/src/implement/egress.ts
CHANGED
|
@@ -1,23 +1,107 @@
|
|
|
1
|
-
// `egress`: while a site's handler runs, the global `fetch` reaches only the HTTPS origins the site declares
|
|
2
|
-
//
|
|
3
|
-
//
|
|
4
|
-
//
|
|
1
|
+
// `egress`: while a site's handler runs, the global `fetch` reaches only the HTTPS origins the site declares, or, for a
|
|
2
|
+
// cron job that declares `egress: 'public'`, only public hosts (ADR-0071). It stops a mistake and makes a bypass
|
|
3
|
+
// conspicuous; it is not a sandbox (ADR-0012 §8): code that kept the `fetch` it found before boot, or opens its own
|
|
4
|
+
// sockets, escapes it. The framework's own facilities (mail, connectors, IAM, the object store) run outside the site's
|
|
5
|
+
// scope, under their own declarations.
|
|
5
6
|
|
|
7
|
+
import {
|
|
8
|
+
type DeclaredEgress,
|
|
9
|
+
FABRIKA_EGRESS_REFUSED_HOSTS,
|
|
10
|
+
isPublicAddress,
|
|
11
|
+
normalizedHost,
|
|
12
|
+
PUBLIC_EGRESS,
|
|
13
|
+
publicEgressRefusal,
|
|
14
|
+
} from '@fabrika/auth-core'
|
|
6
15
|
import { AsyncLocalStorage } from 'node:async_hooks'
|
|
7
16
|
import { CapabilityRefusedError } from './capability'
|
|
8
17
|
|
|
18
|
+
/** The addresses a host name resolves to, where the runtime exposes resolution: Bun's `node:dns`, never a Worker. */
|
|
19
|
+
export type HostResolver = (hostname: string) => Promise<readonly string[]>
|
|
20
|
+
|
|
21
|
+
/** What public egress refuses beyond what a URL alone shows (`publicEgressRefusal`). */
|
|
22
|
+
export interface PublicEgressRules {
|
|
23
|
+
/** The installation's own hosts, normalized: every host a framework variable names, and `FABRIKA_EGRESS_REFUSED_HOSTS`. */
|
|
24
|
+
readonly refusedHosts: ReadonlySet<string>
|
|
25
|
+
/** Resolves each hop's host before it is sent, so a public name of a private address is refused; `null` on Cloudflare. */
|
|
26
|
+
readonly resolve: HostResolver | null
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** What one site's `fetch` reaches: its declared origins, or the rules of public egress. */
|
|
30
|
+
export type SiteEgress = readonly string[] | PublicEgressRules
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* The bounds of one request under public egress, the redirects it follows included. The handler's own signal still
|
|
34
|
+
* aborts it sooner (`ctx.signal`, an `AbortSignal.timeout` of its own).
|
|
35
|
+
*/
|
|
36
|
+
export const PUBLIC_EGRESS_LIMITS = {
|
|
37
|
+
/** One request, its redirects and the reading of its body included: the abort also stops a body still streaming. */
|
|
38
|
+
timeoutMs: 60_000,
|
|
39
|
+
/** One response's body as the handler reads it; a larger one is refused, by its `Content-Length` or while it streams. */
|
|
40
|
+
maxResponseBytes: 16 * 1024 * 1024,
|
|
41
|
+
/** The redirects one request follows when its `redirect` mode is `follow`, each hop checked again. */
|
|
42
|
+
maxRedirects: 10,
|
|
43
|
+
} as const
|
|
44
|
+
|
|
9
45
|
interface EgressScope {
|
|
10
46
|
/** The site, as a refusal names it. */
|
|
11
47
|
readonly site: string
|
|
12
48
|
readonly origins: ReadonlySet<string>
|
|
49
|
+
/** Public egress: `null` for a site that declares origins, or none. */
|
|
50
|
+
readonly open: PublicEgressRules | null
|
|
13
51
|
}
|
|
14
52
|
|
|
15
53
|
const scope = new AsyncLocalStorage<EgressScope>()
|
|
16
54
|
const guards = new WeakSet<object>()
|
|
17
55
|
|
|
18
56
|
/** Runs a site's handler: every `fetch` it starts reaches only `egress`. */
|
|
19
|
-
export function runAsSite<T>(site: string, egress:
|
|
20
|
-
return
|
|
57
|
+
export function runAsSite<T>(site: string, egress: SiteEgress, work: () => Promise<T>): Promise<T> {
|
|
58
|
+
return isOrigins(egress)
|
|
59
|
+
? scope.run({ site, origins: new Set(egress), open: null }, work)
|
|
60
|
+
: scope.run({ site, origins: new Set(), open: egress }, work)
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
/**
|
|
64
|
+
* The egress a site runs with: its declared origins, or `rules` for `'public'`. Only a cron job's runner holds rules; a
|
|
65
|
+
* site run without them reaches nothing, though the build lets no other site declare `'public'`.
|
|
66
|
+
*/
|
|
67
|
+
export function siteEgress(declared: DeclaredEgress, rules: PublicEgressRules | null): SiteEgress {
|
|
68
|
+
return declared === PUBLIC_EGRESS ? (rules ?? []) : declared
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function isOrigins(egress: SiteEgress): egress is readonly string[] {
|
|
72
|
+
return Array.isArray(egress)
|
|
73
|
+
}
|
|
74
|
+
|
|
75
|
+
/**
|
|
76
|
+
* The rules of public egress in one environment: the hosts its framework variables name (IAM, Operations, its own
|
|
77
|
+
* origin, the platform's receivers, the object store), the installation hosts Control hands it, and the resolver the
|
|
78
|
+
* runtime adapter supplies.
|
|
79
|
+
*/
|
|
80
|
+
export function publicEgressRules(framework: Readonly<Record<string, string>>, resolve: HostResolver | null): PublicEgressRules {
|
|
81
|
+
const hosts = new Set<string>()
|
|
82
|
+
for (const [name, value] of Object.entries(framework)) {
|
|
83
|
+
if (name === FABRIKA_EGRESS_REFUSED_HOSTS) {
|
|
84
|
+
for (const host of value.split(',')) {
|
|
85
|
+
const normalized = normalizedHost(host.trim())
|
|
86
|
+
if (normalized !== '') hosts.add(normalized)
|
|
87
|
+
}
|
|
88
|
+
continue
|
|
89
|
+
}
|
|
90
|
+
const host = urlHost(value)
|
|
91
|
+
if (host !== null) hosts.add(host)
|
|
92
|
+
}
|
|
93
|
+
return { refusedHosts: hosts, resolve }
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/** The host of a framework variable's value when it is an http(s) URL, such as an origin or a DSN; `null` otherwise. */
|
|
97
|
+
function urlHost(value: string): string | null {
|
|
98
|
+
const text = value.trim()
|
|
99
|
+
if (!/^https?:\/\//i.test(text)) return null
|
|
100
|
+
try {
|
|
101
|
+
return normalizedHost(new URL(text).hostname)
|
|
102
|
+
} catch {
|
|
103
|
+
return null
|
|
104
|
+
}
|
|
21
105
|
}
|
|
22
106
|
|
|
23
107
|
/**
|
|
@@ -41,6 +125,8 @@ export function platformCall<T>(work: () => T): T {
|
|
|
41
125
|
return scope.exit(work)
|
|
42
126
|
}
|
|
43
127
|
|
|
128
|
+
type Fetch = (input: string, init: RequestInit) => Promise<Response>
|
|
129
|
+
|
|
44
130
|
/**
|
|
45
131
|
* Wraps the global `fetch` in the guard, once: a `fetch` that is already a guard stays. A test that replaces `fetch`
|
|
46
132
|
* after boot replaces the guard with it.
|
|
@@ -50,15 +136,20 @@ export function installEgressGuard(): void {
|
|
|
50
136
|
if (guards.has(current)) {
|
|
51
137
|
return
|
|
52
138
|
}
|
|
139
|
+
const send: Fetch = (input, init) => current(input, init)
|
|
53
140
|
const guarded = Object.assign(
|
|
54
141
|
(input: string | URL | Request, init?: RequestInit): Promise<Response> => {
|
|
55
142
|
const running = scope.getStore()
|
|
56
143
|
if (running === undefined) {
|
|
57
144
|
return current(input, init)
|
|
58
145
|
}
|
|
146
|
+
if (running.open !== null) {
|
|
147
|
+
return publicFetch(send, running.site, running.open, input, init)
|
|
148
|
+
}
|
|
59
149
|
const origin = originOf(input)
|
|
60
150
|
if (origin !== null && running.origins.has(origin)) {
|
|
61
|
-
|
|
151
|
+
// Only the standard fields: a runtime's own (Bun's `unix`, `proxy`, `tls`) would send the request elsewhere.
|
|
152
|
+
return current(input, standardInit(init))
|
|
62
153
|
}
|
|
63
154
|
return Promise.reject(
|
|
64
155
|
new CapabilityRefusedError(
|
|
@@ -69,12 +160,47 @@ export function installEgressGuard(): void {
|
|
|
69
160
|
),
|
|
70
161
|
)
|
|
71
162
|
},
|
|
72
|
-
{
|
|
163
|
+
{
|
|
164
|
+
// Inside a site's scope a preconnect reaches only a declared origin; public egress, which cannot check a hop
|
|
165
|
+
// before it connects, refuses every one.
|
|
166
|
+
preconnect: (...args: Parameters<typeof current.preconnect>): void => {
|
|
167
|
+
const running = scope.getStore()
|
|
168
|
+
if (running !== undefined) {
|
|
169
|
+
const origin = originOf(args[0])
|
|
170
|
+
if (running.open !== null || origin === null || !running.origins.has(origin)) {
|
|
171
|
+
throw new CapabilityRefusedError(
|
|
172
|
+
running.open === null ? 'undeclared_egress' : 'refused_egress',
|
|
173
|
+
`${running.site} preconnects to ${origin ?? 'a URL that is not absolute'}, which its egress does not reach`,
|
|
174
|
+
)
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
if (typeof current.preconnect === 'function') current.preconnect(...args)
|
|
178
|
+
},
|
|
179
|
+
},
|
|
73
180
|
)
|
|
74
181
|
guards.add(guarded)
|
|
75
182
|
globalThis.fetch = guarded
|
|
76
183
|
}
|
|
77
184
|
|
|
185
|
+
/** `init` with the fields of the Fetch standard only. */
|
|
186
|
+
function standardInit(init: RequestInit | undefined): RequestInit | undefined {
|
|
187
|
+
if (init === undefined) return undefined
|
|
188
|
+
return {
|
|
189
|
+
...(init.method === undefined ? {} : { method: init.method }),
|
|
190
|
+
...(init.headers === undefined ? {} : { headers: init.headers }),
|
|
191
|
+
...(init.body === undefined ? {} : { body: init.body }),
|
|
192
|
+
...(init.redirect === undefined ? {} : { redirect: init.redirect }),
|
|
193
|
+
...(init.signal === undefined ? {} : { signal: init.signal }),
|
|
194
|
+
...(init.keepalive === undefined ? {} : { keepalive: init.keepalive }),
|
|
195
|
+
...(init.integrity === undefined ? {} : { integrity: init.integrity }),
|
|
196
|
+
...(init.referrer === undefined ? {} : { referrer: init.referrer }),
|
|
197
|
+
...(init.referrerPolicy === undefined ? {} : { referrerPolicy: init.referrerPolicy }),
|
|
198
|
+
...(init.cache === undefined ? {} : { cache: init.cache }),
|
|
199
|
+
...(init.credentials === undefined ? {} : { credentials: init.credentials }),
|
|
200
|
+
...(init.mode === undefined ? {} : { mode: init.mode }),
|
|
201
|
+
}
|
|
202
|
+
}
|
|
203
|
+
|
|
78
204
|
function originOf(input: string | URL | Request): string | null {
|
|
79
205
|
try {
|
|
80
206
|
return new URL(typeof input === 'string' ? input : input instanceof URL ? input.href : input.url).origin
|
|
@@ -82,3 +208,236 @@ function originOf(input: string | URL | Request): string | null {
|
|
|
82
208
|
return null
|
|
83
209
|
}
|
|
84
210
|
}
|
|
211
|
+
|
|
212
|
+
const REDIRECTS: ReadonlySet<number> = new Set([301, 302, 303, 307, 308])
|
|
213
|
+
/** The headers a redirect that turns a request into a `GET` drops with its body (Fetch, "HTTP-redirect fetch"). */
|
|
214
|
+
const BODY_HEADERS = ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location']
|
|
215
|
+
/**
|
|
216
|
+
* The request headers public egress never sends, on any hop: the Fetch standard's forbidden request headers (`Host`
|
|
217
|
+
* among them, which would route a request for a public name to another site at the same address), the forwarding
|
|
218
|
+
* headers a proxy trusts, and the platform's own `X-Fabrika-*`.
|
|
219
|
+
*/
|
|
220
|
+
const FORBIDDEN_HEADERS = [
|
|
221
|
+
'accept-charset',
|
|
222
|
+
'accept-encoding',
|
|
223
|
+
'access-control-request-headers',
|
|
224
|
+
'access-control-request-method',
|
|
225
|
+
'connection',
|
|
226
|
+
'content-length',
|
|
227
|
+
'cookie2',
|
|
228
|
+
'date',
|
|
229
|
+
'dnt',
|
|
230
|
+
'expect',
|
|
231
|
+
'forwarded',
|
|
232
|
+
'host',
|
|
233
|
+
'keep-alive',
|
|
234
|
+
'origin',
|
|
235
|
+
'referer',
|
|
236
|
+
'set-cookie',
|
|
237
|
+
'te',
|
|
238
|
+
'trailer',
|
|
239
|
+
'transfer-encoding',
|
|
240
|
+
'upgrade',
|
|
241
|
+
'via',
|
|
242
|
+
'x-http-method',
|
|
243
|
+
'x-http-method-override',
|
|
244
|
+
'x-method-override',
|
|
245
|
+
'x-real-ip',
|
|
246
|
+
]
|
|
247
|
+
const FORBIDDEN_HEADER_PREFIXES = ['proxy-', 'sec-', 'x-forwarded-', 'x-fabrika-']
|
|
248
|
+
|
|
249
|
+
function withoutForbiddenHeaders(headers: Headers): Headers {
|
|
250
|
+
for (const name of [...headers.keys()]) {
|
|
251
|
+
if (FORBIDDEN_HEADERS.includes(name) || FORBIDDEN_HEADER_PREFIXES.some((prefix) => name.startsWith(prefix))) {
|
|
252
|
+
headers.delete(name)
|
|
253
|
+
}
|
|
254
|
+
}
|
|
255
|
+
return headers
|
|
256
|
+
}
|
|
257
|
+
|
|
258
|
+
/** The credentials a redirect to another origin drops. */
|
|
259
|
+
const CREDENTIAL_HEADERS = ['authorization', 'proxy-authorization', 'cookie']
|
|
260
|
+
|
|
261
|
+
/**
|
|
262
|
+
* One request under public egress. Every hop is sent with `redirect: 'manual'`, so the runtime follows no redirect the
|
|
263
|
+
* guard has not checked: the caller's `follow` is done here, at most `maxRedirects` hops, each host checked again;
|
|
264
|
+
* `manual` hands the caller the redirect, whose next `fetch` passes the guard again; `error` refuses one. The request
|
|
265
|
+
* is bounded in time and its answer's body in size.
|
|
266
|
+
*/
|
|
267
|
+
async function publicFetch(
|
|
268
|
+
send: Fetch,
|
|
269
|
+
site: string,
|
|
270
|
+
rules: PublicEgressRules,
|
|
271
|
+
input: string | URL | Request,
|
|
272
|
+
init?: RequestInit,
|
|
273
|
+
): Promise<Response> {
|
|
274
|
+
const request = new Request(input, init)
|
|
275
|
+
// A timer the guard clears once the body is read, not `AbortSignal.timeout`: on workerd an uncleared timer keeps the
|
|
276
|
+
// Durable Object awake until it fires.
|
|
277
|
+
const deadline = new AbortController()
|
|
278
|
+
const timer = setTimeout(() => deadline.abort(new DOMException('public egress request timed out', 'TimeoutError')), PUBLIC_EGRESS_LIMITS.timeoutMs)
|
|
279
|
+
const done = (): void => clearTimeout(timer)
|
|
280
|
+
try {
|
|
281
|
+
return await follow(send, site, rules, request, AbortSignal.any([request.signal, deadline.signal]), done)
|
|
282
|
+
} catch (error) {
|
|
283
|
+
done()
|
|
284
|
+
throw error
|
|
285
|
+
}
|
|
286
|
+
}
|
|
287
|
+
|
|
288
|
+
/** The hops of one request; `done` clears its deadline once its last answer's body is read. */
|
|
289
|
+
async function follow(
|
|
290
|
+
send: Fetch,
|
|
291
|
+
site: string,
|
|
292
|
+
rules: PublicEgressRules,
|
|
293
|
+
request: Request,
|
|
294
|
+
signal: AbortSignal,
|
|
295
|
+
done: () => void,
|
|
296
|
+
): Promise<Response> {
|
|
297
|
+
const mode = request.redirect
|
|
298
|
+
let url = new URL(request.url)
|
|
299
|
+
let method = request.method
|
|
300
|
+
const headers = withoutForbiddenHeaders(new Headers(request.headers))
|
|
301
|
+
// Read once, so that a 307 or a 308 sends it again.
|
|
302
|
+
let body: ArrayBuffer | null = request.body === null ? null : await untilAborted(signal, request.arrayBuffer())
|
|
303
|
+
for (let hop = 0;; hop++) {
|
|
304
|
+
await admit(site, rules, url, signal)
|
|
305
|
+
const response = await send(url.href, { method, headers: new Headers(headers), body, redirect: 'manual', signal })
|
|
306
|
+
const location = REDIRECTS.has(response.status) ? response.headers.get('location') : null
|
|
307
|
+
if (location === null || mode === 'manual') {
|
|
308
|
+
return await capped(site, response, url, hop > 0, signal, done)
|
|
309
|
+
}
|
|
310
|
+
await response.body?.cancel()
|
|
311
|
+
if (mode === 'error') {
|
|
312
|
+
throw new TypeError(`${site}: ${url.origin} redirects, and the request's redirect mode is 'error'`)
|
|
313
|
+
}
|
|
314
|
+
if (hop >= PUBLIC_EGRESS_LIMITS.maxRedirects) {
|
|
315
|
+
throw new TypeError(`${site}: more than ${PUBLIC_EGRESS_LIMITS.maxRedirects} redirects, the last from ${url.origin}`)
|
|
316
|
+
}
|
|
317
|
+
const next = new URL(location, url)
|
|
318
|
+
const toGet = (response.status === 303 && method !== 'GET' && method !== 'HEAD')
|
|
319
|
+
|| ((response.status === 301 || response.status === 302) && method === 'POST')
|
|
320
|
+
if (toGet) {
|
|
321
|
+
method = 'GET'
|
|
322
|
+
body = null
|
|
323
|
+
for (const name of BODY_HEADERS) headers.delete(name)
|
|
324
|
+
}
|
|
325
|
+
if (next.origin !== url.origin) {
|
|
326
|
+
for (const name of CREDENTIAL_HEADERS) headers.delete(name)
|
|
327
|
+
}
|
|
328
|
+
url = next
|
|
329
|
+
}
|
|
330
|
+
}
|
|
331
|
+
|
|
332
|
+
/** Refuses a hop public egress does not reach: by the URL, by the installation's hosts, by what its name resolves to. */
|
|
333
|
+
async function admit(site: string, rules: PublicEgressRules, url: URL, signal: AbortSignal): Promise<void> {
|
|
334
|
+
const refusal = publicEgressRefusal(url, rules.refusedHosts)
|
|
335
|
+
if (refusal !== null) {
|
|
336
|
+
throw new CapabilityRefusedError('refused_egress', `${site} calls ${url.origin}, which public egress refuses: ${refusal}`)
|
|
337
|
+
}
|
|
338
|
+
const resolve = rules.resolve
|
|
339
|
+
if (resolve === null) {
|
|
340
|
+
return
|
|
341
|
+
}
|
|
342
|
+
const host = normalizedHost(url.hostname)
|
|
343
|
+
const addresses = await untilAborted(signal, platformCall(() => resolve(host)))
|
|
344
|
+
const internal = addresses.find((address) => !isPublicAddress(address))
|
|
345
|
+
if (addresses.length === 0 || internal !== undefined) {
|
|
346
|
+
throw new CapabilityRefusedError(
|
|
347
|
+
'refused_egress',
|
|
348
|
+
`${site} calls ${url.origin}, which public egress refuses: ${
|
|
349
|
+
internal === undefined ? `${host} resolves to no address` : `${host} resolves to ${internal}, which is not a public address`
|
|
350
|
+
}`,
|
|
351
|
+
)
|
|
352
|
+
}
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
/**
|
|
356
|
+
* `response` with its body bounded by `maxResponseBytes`, and the URL and redirect flag of the request it answers,
|
|
357
|
+
* which a response the guard builds would otherwise lose.
|
|
358
|
+
*/
|
|
359
|
+
async function capped(
|
|
360
|
+
site: string,
|
|
361
|
+
response: Response,
|
|
362
|
+
url: URL,
|
|
363
|
+
redirected: boolean,
|
|
364
|
+
signal: AbortSignal,
|
|
365
|
+
done: () => void,
|
|
366
|
+
): Promise<Response> {
|
|
367
|
+
const max = PUBLIC_EGRESS_LIMITS.maxResponseBytes
|
|
368
|
+
const tooLarge = () =>
|
|
369
|
+
new CapabilityRefusedError(
|
|
370
|
+
'oversized_egress',
|
|
371
|
+
`${site}: ${url.origin} answers more than ${max} bytes, the most public egress reads of one response`,
|
|
372
|
+
)
|
|
373
|
+
const declared = Number(response.headers.get('content-length') ?? '0')
|
|
374
|
+
if (Number.isFinite(declared) && declared > max) {
|
|
375
|
+
await response.body?.cancel()
|
|
376
|
+
throw tooLarge()
|
|
377
|
+
}
|
|
378
|
+
if (response.body === null || response.status < 200 || response.status > 599) {
|
|
379
|
+
done()
|
|
380
|
+
return withRequestUrl(response, url, redirected)
|
|
381
|
+
}
|
|
382
|
+
const reader = response.body.getReader()
|
|
383
|
+
let seen = 0
|
|
384
|
+
const bound = new ReadableStream<Uint8Array>({
|
|
385
|
+
async pull(controller) {
|
|
386
|
+
const read = await untilAborted(signal, reader.read()).catch(async (error: unknown) => {
|
|
387
|
+
done()
|
|
388
|
+
await reader.cancel(error).catch(() => undefined)
|
|
389
|
+
throw error
|
|
390
|
+
})
|
|
391
|
+
if (read.done) {
|
|
392
|
+
done()
|
|
393
|
+
controller.close()
|
|
394
|
+
return
|
|
395
|
+
}
|
|
396
|
+
seen += read.value.byteLength
|
|
397
|
+
if (seen > max) {
|
|
398
|
+
done()
|
|
399
|
+
await reader.cancel()
|
|
400
|
+
controller.error(tooLarge())
|
|
401
|
+
return
|
|
402
|
+
}
|
|
403
|
+
controller.enqueue(read.value)
|
|
404
|
+
},
|
|
405
|
+
async cancel(reason) {
|
|
406
|
+
done()
|
|
407
|
+
await reader.cancel(reason)
|
|
408
|
+
},
|
|
409
|
+
})
|
|
410
|
+
const answer = new Response(bound, {
|
|
411
|
+
status: response.status,
|
|
412
|
+
statusText: response.statusText,
|
|
413
|
+
headers: response.headers,
|
|
414
|
+
})
|
|
415
|
+
return withRequestUrl(answer, url, redirected)
|
|
416
|
+
}
|
|
417
|
+
|
|
418
|
+
/**
|
|
419
|
+
* `work`, or the signal's reason once it aborts, whichever comes first: a stage the runtime does not abort by the
|
|
420
|
+
* signal (a resolver, a body read) still ends at the deadline. The work itself is left to settle unobserved.
|
|
421
|
+
*/
|
|
422
|
+
async function untilAborted<T>(signal: AbortSignal, work: Promise<T>): Promise<T> {
|
|
423
|
+
signal.throwIfAborted()
|
|
424
|
+
let abort = (): void => {}
|
|
425
|
+
const aborted = new Promise<never>((_resolve, reject) => {
|
|
426
|
+
abort = () => reject(signal.reason)
|
|
427
|
+
})
|
|
428
|
+
signal.addEventListener('abort', abort, { once: true })
|
|
429
|
+
try {
|
|
430
|
+
return await Promise.race([work, aborted])
|
|
431
|
+
} finally {
|
|
432
|
+
signal.removeEventListener('abort', abort)
|
|
433
|
+
}
|
|
434
|
+
}
|
|
435
|
+
|
|
436
|
+
function withRequestUrl(response: Response, url: URL, redirected: boolean): Response {
|
|
437
|
+
try {
|
|
438
|
+
Object.defineProperties(response, { url: { value: url.href }, redirected: { value: redirected } })
|
|
439
|
+
} catch {
|
|
440
|
+
// A runtime whose responses refuse own properties keeps its own `url`; the body bound holds either way.
|
|
441
|
+
}
|
|
442
|
+
return response
|
|
443
|
+
}
|
|
@@ -3,13 +3,14 @@
|
|
|
3
3
|
// commits it after the handler returned and its output passed validation, and rolls it back otherwise. Every handle
|
|
4
4
|
// is bound to the invocation: called from another request, another `boot`, or after it ended, it refuses.
|
|
5
5
|
|
|
6
|
-
import { type ContractArtifact, JOB_MAILERS, type JobMailer } from '@fabrika/auth-core'
|
|
6
|
+
import { type ContractArtifact, type DeclaredEgress, JOB_MAILERS, type JobMailer, PUBLIC_EGRESS } from '@fabrika/auth-core'
|
|
7
7
|
import {
|
|
8
8
|
type DataAccess,
|
|
9
9
|
type DataHandles,
|
|
10
10
|
type DataSite,
|
|
11
11
|
type FileBinding,
|
|
12
12
|
type InvocationTransaction,
|
|
13
|
+
type NewWake,
|
|
13
14
|
type QueryRefusal,
|
|
14
15
|
QueryRefusedError,
|
|
15
16
|
type Session,
|
|
@@ -34,8 +35,8 @@ export interface SiteDeclaration {
|
|
|
34
35
|
readonly binds: string | null
|
|
35
36
|
/** The token purposes `ctx.tokens.sign` may sign. */
|
|
36
37
|
readonly signs: readonly string[]
|
|
37
|
-
/** The HTTPS origins the global `fetch` reaches while the site's handler runs. */
|
|
38
|
-
readonly egress:
|
|
38
|
+
/** The HTTPS origins the global `fetch` reaches while the site's handler runs, or `'public'`: every public host (a cron job). */
|
|
39
|
+
readonly egress: DeclaredEgress
|
|
39
40
|
}
|
|
40
41
|
|
|
41
42
|
/** A public procedure's reach: the texts the verified signed tokens of its request carry, which name the rows it changes. */
|
|
@@ -166,10 +167,11 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
|
|
|
166
167
|
problems.push(`${where}: signs is not a list of token purposes`)
|
|
167
168
|
}
|
|
168
169
|
const egressField = ownField(declared, 'egress')
|
|
169
|
-
const
|
|
170
|
-
if (egressField !== undefined && (!Array.isArray(egressField) ||
|
|
171
|
-
problems.push(`${where}: egress is not a list of origins`)
|
|
170
|
+
const origins = Array.isArray(egressField) ? egressField.filter((origin): origin is string => typeof origin === 'string') : []
|
|
171
|
+
if (egressField !== undefined && egressField !== PUBLIC_EGRESS && (!Array.isArray(egressField) || origins.length !== egressField.length)) {
|
|
172
|
+
problems.push(`${where}: egress is not a list of origins or '${PUBLIC_EGRESS}'`)
|
|
172
173
|
}
|
|
174
|
+
const egress: DeclaredEgress = egressField === PUBLIC_EGRESS ? PUBLIC_EGRESS : Object.freeze([...new Set(origins)].sort())
|
|
173
175
|
return Object.freeze({
|
|
174
176
|
sql: sql === 'read' || sql === 'write' ? sql : null,
|
|
175
177
|
unscoped: Object.freeze(unscoped),
|
|
@@ -179,7 +181,7 @@ export function parseDeclaration(where: string, declared: unknown, kind: DataKin
|
|
|
179
181
|
kicks: Object.freeze([...new Set(kicks)].sort()),
|
|
180
182
|
binds: typeof binds === 'string' ? binds : null,
|
|
181
183
|
signs: Object.freeze([...new Set(signs)].sort()),
|
|
182
|
-
egress
|
|
184
|
+
egress,
|
|
183
185
|
})
|
|
184
186
|
}
|
|
185
187
|
|
|
@@ -224,7 +226,7 @@ export function approvedReach(site: string, artifact: ContractArtifact): SiteDec
|
|
|
224
226
|
kicks: Object.freeze([...(reach.kicks ?? [])]),
|
|
225
227
|
binds: reach.binds ?? null,
|
|
226
228
|
signs: Object.freeze([...(reach.signs ?? [])]),
|
|
227
|
-
egress: Object.freeze([...(reach.egress ?? [])]),
|
|
229
|
+
egress: reach.egress === PUBLIC_EGRESS ? PUBLIC_EGRESS : Object.freeze([...(reach.egress ?? [])]),
|
|
228
230
|
})
|
|
229
231
|
}
|
|
230
232
|
|
|
@@ -243,7 +245,7 @@ function describeDeclaration(declaration: SiteDeclaration): string {
|
|
|
243
245
|
...(declaration.kicks.length === 0 ? {} : { kicks: declaration.kicks }),
|
|
244
246
|
...(declaration.binds === null ? {} : { binds: declaration.binds }),
|
|
245
247
|
...(declaration.signs.length === 0 ? {} : { signs: declaration.signs }),
|
|
246
|
-
...(declaration.egress.length === 0 ? {} : { egress: declaration.egress }),
|
|
248
|
+
...(declaration.egress !== PUBLIC_EGRESS && declaration.egress.length === 0 ? {} : { egress: declaration.egress }),
|
|
247
249
|
})
|
|
248
250
|
}
|
|
249
251
|
|
|
@@ -466,22 +468,61 @@ export function jobSql(frame: RequestFrame, data: DataAccess, mode: SqlMode, ses
|
|
|
466
468
|
return data.sql({ mode, check: boundTo(frame, ended, 'tx.sql'), session: async () => session, fail: () => session.fail() })
|
|
467
469
|
}
|
|
468
470
|
|
|
471
|
+
/** The kicks of one invocation, as `ctx.kick` recorded them. */
|
|
472
|
+
export interface KickRecorder {
|
|
473
|
+
readonly kick: (job: string, options?: unknown) => void
|
|
474
|
+
/** The jobs kicked without `at`, each once: what the dispatcher starts after the commit. */
|
|
475
|
+
readonly kicked: () => readonly string[]
|
|
476
|
+
/** Whether the invocation kicked anything, now or for later. */
|
|
477
|
+
readonly recorded: () => boolean
|
|
478
|
+
/**
|
|
479
|
+
* Every kick's wake, one per job and due second (`kick:<job>:<due second>`); a kick without `at` is due at `now`. The
|
|
480
|
+
* site writes them in its transaction, so a rollback leaves none.
|
|
481
|
+
*/
|
|
482
|
+
readonly wakes: (now: Date) => readonly NewWake[]
|
|
483
|
+
}
|
|
484
|
+
|
|
485
|
+
/** A kick's due time: `undefined` for one without options; anything but `{ at: <valid Date> }` is refused. */
|
|
486
|
+
function kickAt(site: string, options: unknown): Date | undefined {
|
|
487
|
+
if (options === undefined) {
|
|
488
|
+
return undefined
|
|
489
|
+
}
|
|
490
|
+
const keys = isPlainObject(options) ? Object.keys(options) : null
|
|
491
|
+
const at: unknown = isPlainObject(options) ? ownField(options, 'at') : undefined
|
|
492
|
+
if (keys === null || keys.length !== 1 || keys[0] !== 'at' || !(at instanceof Date) || Number.isNaN(at.getTime())) {
|
|
493
|
+
throw new QueryRefusedError('invalid_argument', `${site}: ctx.kick takes a job and optionally { at: <Date> }; a kick carries nothing else`)
|
|
494
|
+
}
|
|
495
|
+
return new Date(at.getTime())
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
const kickKey = (job: string, due: Date): string => `kick:${job}:${Math.floor(due.getTime() / 1_000)}`
|
|
499
|
+
|
|
469
500
|
/**
|
|
470
|
-
* `ctx.kick` of one invocation: it names only a declared job, and records it; the
|
|
471
|
-
* after the commit, and nothing on a rollback.
|
|
501
|
+
* `ctx.kick` of one invocation: it names only a declared job, and records it; the site writes each kick's wake in its
|
|
502
|
+
* transaction, and the dispatcher starts each job kicked without `at` once, after the commit, and nothing on a rollback.
|
|
472
503
|
*/
|
|
473
|
-
export function kickRecorder(
|
|
474
|
-
|
|
475
|
-
declared: readonly string[],
|
|
476
|
-
): { readonly kick: (job: string) => void; readonly kicked: () => readonly string[] } {
|
|
477
|
-
const kicked = new Set<string>()
|
|
504
|
+
export function kickRecorder(site: string, declared: readonly string[]): KickRecorder {
|
|
505
|
+
const kicks: { readonly job: string; readonly at: Date | undefined }[] = []
|
|
478
506
|
return {
|
|
479
|
-
kick: (job: string) => {
|
|
507
|
+
kick: (job: string, options?: unknown) => {
|
|
480
508
|
if (!declared.includes(job)) {
|
|
481
509
|
throw new CapabilityRefusedError('undeclared_kick', `${site} does not declare kicks: ['${String(job)}']`)
|
|
482
510
|
}
|
|
483
|
-
|
|
511
|
+
kicks.push({ job, at: kickAt(site, options) })
|
|
512
|
+
},
|
|
513
|
+
kicked: () => [...new Set(kicks.filter((kick) => kick.at === undefined).map((kick) => kick.job))],
|
|
514
|
+
recorded: () => kicks.length > 0,
|
|
515
|
+
wakes: (now: Date) => {
|
|
516
|
+
const wakes = new Map<string, NewWake>()
|
|
517
|
+
for (const { job, at } of kicks) {
|
|
518
|
+
const dueAt = at ?? now
|
|
519
|
+
const dedupe = kickKey(job, dueAt)
|
|
520
|
+
const kept = wakes.get(dedupe)
|
|
521
|
+
if (kept === undefined || dueAt < kept.dueAt) {
|
|
522
|
+
wakes.set(dedupe, { job, reason: 'kick', dueAt, dedupe })
|
|
523
|
+
}
|
|
524
|
+
}
|
|
525
|
+
return [...wakes.values()]
|
|
484
526
|
},
|
|
485
|
-
kicked: () => [...kicked],
|
|
486
527
|
}
|
|
487
528
|
}
|
|
@@ -102,12 +102,27 @@ export class WorkloadCredential {
|
|
|
102
102
|
if (cached !== null && cached.exp - Math.floor(Date.now() / 1000) > TOKEN_REFRESH_SKEW_SECONDS) {
|
|
103
103
|
return Promise.resolve({ ok: true, perms: cached.perms, token: cached.token })
|
|
104
104
|
}
|
|
105
|
-
this.#pending
|
|
106
|
-
|
|
107
|
-
|
|
105
|
+
if (this.#pending === null) {
|
|
106
|
+
const pending: Promise<WorkloadAuthority> = this.#exchange().finally(() => {
|
|
107
|
+
if (this.#pending === pending) {
|
|
108
|
+
this.#pending = null
|
|
109
|
+
}
|
|
110
|
+
})
|
|
111
|
+
this.#pending = pending
|
|
112
|
+
}
|
|
108
113
|
return this.#pending
|
|
109
114
|
}
|
|
110
115
|
|
|
116
|
+
/**
|
|
117
|
+
* The caller stopped waiting for `pending`, an answer of `authority()` (its attempt timed out or was stopped): the
|
|
118
|
+
* next call exchanges afresh instead of waiting on an exchange that may never answer.
|
|
119
|
+
*/
|
|
120
|
+
abandon(pending: Promise<WorkloadAuthority>): void {
|
|
121
|
+
if (this.#pending === pending) {
|
|
122
|
+
this.#pending = null
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
|
|
111
126
|
async #exchange(): Promise<WorkloadAuthority> {
|
|
112
127
|
const { kind, name, key, audience, source, verifier } = this.#options
|
|
113
128
|
let minted: MintFromKeyResult
|