@dxos/blob 0.11.1 → 0.13.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.
Files changed (58) hide show
  1. package/README.md +13 -4
  2. package/dist/lib/chunk-ni-uri.mjs +103 -0
  3. package/dist/lib/chunk-ni-uri.mjs.map +1 -0
  4. package/dist/lib/hosted.mjs +55 -0
  5. package/dist/lib/hosted.mjs.map +1 -0
  6. package/dist/lib/index.mjs +2 -0
  7. package/dist/lib/s3.mjs +515 -0
  8. package/dist/lib/s3.mjs.map +1 -0
  9. package/dist/types/src/backend.d.ts +31 -0
  10. package/dist/types/src/backend.d.ts.map +1 -1
  11. package/dist/types/src/hosted/blob-backend.d.ts +21 -0
  12. package/dist/types/src/hosted/blob-backend.d.ts.map +1 -0
  13. package/dist/types/src/hosted/blob-backend.test.d.ts +2 -0
  14. package/dist/types/src/hosted/blob-backend.test.d.ts.map +1 -0
  15. package/dist/types/src/hosted/index.d.ts +2 -0
  16. package/dist/types/src/hosted/index.d.ts.map +1 -0
  17. package/dist/types/src/index.d.ts +2 -1
  18. package/dist/types/src/index.d.ts.map +1 -1
  19. package/dist/types/src/ni-uri.d.ts +51 -0
  20. package/dist/types/src/ni-uri.d.ts.map +1 -0
  21. package/dist/types/src/ni-uri.test.d.ts +2 -0
  22. package/dist/types/src/ni-uri.test.d.ts.map +1 -0
  23. package/dist/types/src/s3/blob-backend.d.ts +38 -0
  24. package/dist/types/src/s3/blob-backend.d.ts.map +1 -0
  25. package/dist/types/src/s3/constants.d.ts +17 -0
  26. package/dist/types/src/s3/constants.d.ts.map +1 -0
  27. package/dist/types/src/s3/index.d.ts +6 -0
  28. package/dist/types/src/s3/index.d.ts.map +1 -0
  29. package/dist/types/src/s3/s3-client.d.ts +93 -0
  30. package/dist/types/src/s3/s3-client.d.ts.map +1 -0
  31. package/dist/types/src/s3/s3-client.test.d.ts +2 -0
  32. package/dist/types/src/s3/s3-client.test.d.ts.map +1 -0
  33. package/dist/types/src/s3/s3-uri.d.ts +44 -0
  34. package/dist/types/src/s3/s3-uri.d.ts.map +1 -0
  35. package/dist/types/src/s3/s3-uri.test.d.ts +2 -0
  36. package/dist/types/src/s3/s3-uri.test.d.ts.map +1 -0
  37. package/dist/types/src/s3/sigv4.d.ts +55 -0
  38. package/dist/types/src/s3/sigv4.d.ts.map +1 -0
  39. package/dist/types/src/s3/sigv4.test.d.ts +2 -0
  40. package/dist/types/src/s3/sigv4.test.d.ts.map +1 -0
  41. package/dist/types/tsconfig.tsbuildinfo +1 -1
  42. package/package.json +14 -2
  43. package/src/backend.ts +23 -0
  44. package/src/hosted/blob-backend.test.ts +113 -0
  45. package/src/hosted/blob-backend.ts +67 -0
  46. package/src/hosted/index.ts +5 -0
  47. package/src/index.ts +2 -1
  48. package/src/ni-uri.test.ts +31 -0
  49. package/src/ni-uri.ts +136 -0
  50. package/src/s3/blob-backend.ts +75 -0
  51. package/src/s3/constants.ts +24 -0
  52. package/src/s3/index.ts +13 -0
  53. package/src/s3/s3-client.test.ts +145 -0
  54. package/src/s3/s3-client.ts +331 -0
  55. package/src/s3/s3-uri.test.ts +81 -0
  56. package/src/s3/s3-uri.ts +93 -0
  57. package/src/s3/sigv4.test.ts +99 -0
  58. package/src/s3/sigv4.ts +203 -0
@@ -0,0 +1,145 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { afterEach, describe, test, vi } from 'vitest';
6
+
7
+ import { getObject, headObject, probeAccess } from './s3-client.ts';
8
+
9
+ const URI = { host: 'bucket.account.r2.cloudflarestorage.com', key: 'SPACE/hash' };
10
+ const CREDENTIALS = { accessKeyId: 'AKIA', secretAccessKey: 'secret' };
11
+
12
+ const respondWith = (status: number) => {
13
+ const fetchMock = vi.fn(async () => new Response(status === 200 ? new Uint8Array([1, 2, 3]) : '', { status }));
14
+ vi.stubGlobal('fetch', fetchMock);
15
+ return fetchMock;
16
+ };
17
+
18
+ describe('s3 client read semantics', () => {
19
+ afterEach(() => {
20
+ vi.unstubAllGlobals();
21
+ });
22
+
23
+ test('a signed read treats 404 and 403 as a miss', async ({ expect }) => {
24
+ for (const status of [404, 403]) {
25
+ respondWith(status);
26
+ await expect(getObject({ uri: URI, credentials: CREDENTIALS })).resolves.toBeUndefined();
27
+ await expect(headObject({ uri: URI, credentials: CREDENTIALS })).resolves.toBe(false);
28
+ }
29
+ });
30
+
31
+ test('a signed read raises anything else, so a real fault is not hidden', async ({ expect }) => {
32
+ for (const status of [400, 429, 500]) {
33
+ respondWith(status);
34
+ await expect(getObject({ uri: URI, credentials: CREDENTIALS })).rejects.toThrow(/S3 request failed/);
35
+ }
36
+ });
37
+
38
+ // R2 answers an unauthenticated request to a private bucket with 400 InvalidArgument rather than
39
+ // the 403 AWS returns. Verified against a live bucket; a 404/403-only rule made the public-bucket
40
+ // fallback throw instead of reporting a miss.
41
+ test('an unsigned read treats any client error as not-publicly-readable', async ({ expect }) => {
42
+ for (const status of [400, 401, 403, 404]) {
43
+ respondWith(status);
44
+ await expect(getObject({ uri: URI })).resolves.toBeUndefined();
45
+ await expect(headObject({ uri: URI })).resolves.toBe(false);
46
+ }
47
+ });
48
+
49
+ test('an unsigned read still raises a server error', async ({ expect }) => {
50
+ respondWith(503);
51
+ await expect(getObject({ uri: URI })).rejects.toThrow(/S3 request failed/);
52
+ });
53
+
54
+ // A rejection during the body read that is NOT our timeout must pass through unchanged, rather
55
+ // than being relabelled. The timeout half of that branch has no test: driving it needs the real
56
+ // S3_TIMEOUT_MS deadline to elapse, and a fake-timer version did not reliably intercept the
57
+ // already-scheduled timer. Left untested rather than covered by something slow and flaky.
58
+ test('a non-timeout body-read failure is not relabelled', async ({ expect }) => {
59
+ vi.stubGlobal(
60
+ 'fetch',
61
+ vi.fn(async () => {
62
+ const body = new ReadableStream({
63
+ start: (controller) => controller.error(new Error('connection reset')),
64
+ });
65
+ return new Response(body, { status: 200 });
66
+ }),
67
+ );
68
+ await expect(getObject({ uri: URI, credentials: CREDENTIALS })).rejects.toThrow(/connection reset/);
69
+ });
70
+
71
+ test('a successful read returns the bytes', async ({ expect }) => {
72
+ respondWith(200);
73
+ await expect(getObject({ uri: URI, credentials: CREDENTIALS })).resolves.toEqual(new Uint8Array([1, 2, 3]));
74
+ await expect(headObject({ uri: URI, credentials: CREDENTIALS })).resolves.toBe(true);
75
+ });
76
+ });
77
+
78
+ /** The probe's messages are what the connection UI shows, so they are the behaviour under test. */
79
+ describe('probeAccess diagnosis', () => {
80
+ afterEach(() => {
81
+ vi.unstubAllGlobals();
82
+ });
83
+
84
+ const respondWithCode = (status: number, code?: string) => {
85
+ vi.stubGlobal(
86
+ 'fetch',
87
+ vi.fn(async () => new Response(code ? `<Error><Code>${code}</Code></Error>` : '', { status })),
88
+ );
89
+ };
90
+
91
+ test('a missing probe key means the signature was accepted', async ({ expect }) => {
92
+ respondWithCode(404);
93
+ await expect(probeAccess({ uri: URI, credentials: CREDENTIALS })).resolves.toBeUndefined();
94
+ });
95
+
96
+ test('names a wrong access key id', async ({ expect }) => {
97
+ respondWithCode(403, 'InvalidAccessKeyId');
98
+ await expect(probeAccess({ uri: URI, credentials: CREDENTIALS })).rejects.toThrow('Unknown access key ID.');
99
+ });
100
+
101
+ test('names a wrong secret rather than blaming the key id', async ({ expect }) => {
102
+ respondWithCode(403, 'SignatureDoesNotMatch');
103
+ await expect(probeAccess({ uri: URI, credentials: CREDENTIALS })).rejects.toThrow('Wrong secret access key.');
104
+ });
105
+
106
+ test('distinguishes a valid key without permission', async ({ expect }) => {
107
+ respondWithCode(403, 'AccessDenied');
108
+ await expect(probeAccess({ uri: URI, credentials: CREDENTIALS })).rejects.toThrow('Key not permitted on "bucket".');
109
+ });
110
+
111
+ test('names a bad bucket, which is the likeliest typo', async ({ expect }) => {
112
+ respondWithCode(400, 'InvalidBucketName');
113
+ await expect(probeAccess({ uri: URI, credentials: CREDENTIALS })).rejects.toThrow('No such bucket: "bucket".');
114
+ });
115
+
116
+ // The case that actually bit: a blocked CORS preflight rejects `fetch` itself, so there is no
117
+ // status to read and the recommendation has to come from the error we synthesise.
118
+ test('a blocked request recommends the CORS policy', async ({ expect }) => {
119
+ vi.stubGlobal(
120
+ 'fetch',
121
+ vi.fn(async () => {
122
+ throw new TypeError('Failed to fetch');
123
+ }),
124
+ );
125
+ await expect(probeAccess({ uri: URI, credentials: CREDENTIALS })).rejects.toThrow(
126
+ /^Blocked by CORS: the bucket must allow .* for GET, HEAD and PUT\.$/,
127
+ );
128
+ });
129
+
130
+ // These render as a one-line status, so length is part of the contract rather than a nicety.
131
+ test('every diagnosis stays short enough to read at a glance', async ({ expect }) => {
132
+ for (const [status, code] of [
133
+ [403, 'InvalidAccessKeyId'],
134
+ [403, 'SignatureDoesNotMatch'],
135
+ [403, 'AccessDenied'],
136
+ [400, 'InvalidBucketName'],
137
+ ] as const) {
138
+ respondWithCode(status, code);
139
+ await probeAccess({ uri: URI, credentials: CREDENTIALS }).then(
140
+ () => expect.fail(`expected ${code} to be reported as a failure`),
141
+ (error) => expect(error.message.length).toBeLessThanOrEqual(60),
142
+ );
143
+ }
144
+ });
145
+ });
@@ -0,0 +1,331 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { PRESIGN_EXPIRY_SECONDS, S3_TIMEOUT_MS } from './constants.ts';
6
+ import { type S3Uri, regionFromHost, toHttpsUrl } from './s3-uri.ts';
7
+ import { type SigningCredentials, presignUrl, signRequest, toArrayBufferView } from './sigv4.ts';
8
+
9
+ /**
10
+ * The key pair for one bucket. `undefined` wherever a caller has no credential for the endpoint —
11
+ * every read path then falls through to an unsigned request, which succeeds on a public bucket and
12
+ * 403s on a private one. That is the intended behavior: rendering a shared object must not require
13
+ * the viewer to hold the writer's keys.
14
+ */
15
+ export type S3Credentials = {
16
+ accessKeyId: string;
17
+ secretAccessKey: string;
18
+ };
19
+
20
+ const toSigningCredentials = (credentials: S3Credentials, host: string): SigningCredentials => ({
21
+ ...credentials,
22
+ region: regionFromHost(host),
23
+ });
24
+
25
+ /** Rejects rather than resolving `undefined`: a transport failure is not a missing object. */
26
+ export class S3RequestError extends Error {
27
+ constructor(
28
+ readonly status: number,
29
+ readonly statusText: string,
30
+ readonly body: string,
31
+ ) {
32
+ super(`S3 request failed: ${status} ${statusText}${body ? ` — ${body}` : ''}`);
33
+ this.name = 'S3RequestError';
34
+ }
35
+ }
36
+
37
+ /** The page's own origin, which is what a bucket CORS policy has to name. */
38
+ const currentOrigin = (): string =>
39
+ typeof globalThis.location?.origin === 'string' ? globalThis.location.origin : 'this origin';
40
+
41
+ /**
42
+ * A request the browser refused to send, or whose response it refused to expose. Almost always a
43
+ * missing bucket CORS policy: `fetch` reports that as an opaque `TypeError` and confines the real
44
+ * reason to the devtools console, so a blocked preflight would otherwise reach the user as
45
+ * "Failed to fetch".
46
+ *
47
+ * The message names the origin and the methods only. The required headers are in the README and in
48
+ * `details` — a status line has to be readable at a glance, and nobody writes a CORS policy from
49
+ * memory of a sentence anyway.
50
+ */
51
+ export class S3NetworkError extends Error {
52
+ /** The full policy requirement, for logs and docs rather than the status line. */
53
+ readonly details: string;
54
+
55
+ constructor(
56
+ readonly host: string,
57
+ override readonly cause: unknown,
58
+ ) {
59
+ super(`Blocked by CORS: the bucket must allow ${currentOrigin()} for GET, HEAD and PUT.`);
60
+ this.name = 'S3NetworkError';
61
+ this.details =
62
+ `${host} must allow origin ${currentOrigin()} for GET, HEAD and PUT, with the ` +
63
+ 'authorization, content-type, x-amz-content-sha256 and x-amz-date headers.';
64
+ }
65
+ }
66
+
67
+ /**
68
+ * The request exceeded its deadline. Distinct from {@link S3NetworkError} because the remedies have
69
+ * nothing in common — a timeout says the endpoint is slow or unreachable, not that a bucket policy
70
+ * is wrong, and conflating them sends the user to edit configuration that is already correct.
71
+ */
72
+ export class S3TimeoutError extends Error {
73
+ constructor(
74
+ readonly host: string,
75
+ readonly timeoutMs: number,
76
+ ) {
77
+ super(`${host} did not respond within ${Math.round(timeoutMs / 1000)}s.`);
78
+ this.name = 'S3TimeoutError';
79
+ }
80
+ }
81
+
82
+ /** The S3 `<Code>` from an error body, which says far more than the HTTP status alone. */
83
+ const errorCode = (body: string): string | undefined => /<Code>([^<]+)<\/Code>/.exec(body)?.[1];
84
+
85
+ /**
86
+ * Checks that the credential can address the bucket, and explains it when it cannot.
87
+ *
88
+ * Distinct from `headObject`, which deliberately reports 403 and 404 alike as "not there" — correct
89
+ * when reading a blob, useless for a connection test, where telling a rejected key from an absent
90
+ * object is the entire point. Probes a key that should not exist: 404 proves the signature was
91
+ * accepted, and every other outcome names what to fix.
92
+ */
93
+ export const probeAccess = async ({ uri, credentials }: { uri: S3Uri; credentials: S3Credentials }): Promise<void> => {
94
+ const url = toHttpsUrl(uri);
95
+ const headers = await signRequest({
96
+ method: 'HEAD',
97
+ url,
98
+ credentials: toSigningCredentials(credentials, uri.host),
99
+ date: new Date(),
100
+ });
101
+
102
+ // HEAD returns no body, so a failure is re-issued as GET purely to read the S3 error code.
103
+ const { response, done } = await request(url, { method: 'HEAD', headers });
104
+ done();
105
+ if (response.ok || response.status === 404) {
106
+ return;
107
+ }
108
+
109
+ const getHeaders = await signRequest({
110
+ method: 'GET',
111
+ url,
112
+ credentials: toSigningCredentials(credentials, uri.host),
113
+ date: new Date(),
114
+ });
115
+ const body = await request(url, { method: 'GET', headers: getHeaders })
116
+ .then(async ({ response: errorResponse, done: doneReadingError, read }) => {
117
+ try {
118
+ return await read(() => errorResponse.text());
119
+ } finally {
120
+ doneReadingError();
121
+ }
122
+ })
123
+ .catch(() => '');
124
+
125
+ // Kept to one short clause each: this renders as a status line, and the endpoint and key id are
126
+ // already on screen beside it as connection metadata, so repeating them here is noise.
127
+ const bucket = uri.host.split('.')[0];
128
+ switch (errorCode(body) ?? String(response.status)) {
129
+ case 'InvalidAccessKeyId':
130
+ throw new Error('Unknown access key ID.');
131
+ case 'SignatureDoesNotMatch':
132
+ throw new Error('Wrong secret access key.');
133
+ case 'AccessDenied':
134
+ throw new Error(`Key not permitted on "${bucket}".`);
135
+ case 'NoSuchBucket':
136
+ case 'InvalidBucketName':
137
+ throw new Error(`No such bucket: "${bucket}".`);
138
+ default:
139
+ throw new S3RequestError(response.status, response.statusText, body);
140
+ }
141
+ };
142
+
143
+ type TimedRequest = {
144
+ response: Response;
145
+ /** Cancels the deadline; call once the body has been consumed. */
146
+ done: () => void;
147
+ /** Runs a body read under the same timeout classification as the header phase. */
148
+ read: <T>(consume: () => Promise<T>) => Promise<T>;
149
+ };
150
+
151
+ /**
152
+ * A timed request whose deadline covers the body as well as the headers.
153
+ *
154
+ * The signal stays attached to the response body after `fetch` resolves, so the timeout has to be
155
+ * cancelled once the body is fully read — otherwise a large object that takes longer than
156
+ * {@link S3_TIMEOUT_MS} to transfer is aborted mid-read, after the caller already has a `Response`
157
+ * in hand. Callers signal completion by calling the returned `done`.
158
+ */
159
+ const request = async (input: URL, init: RequestInit & { headers?: Record<string, string> }): Promise<TimedRequest> => {
160
+ const controller = new AbortController();
161
+ let timedOut = false;
162
+ const timeout = setTimeout(() => {
163
+ timedOut = true;
164
+ controller.abort();
165
+ }, S3_TIMEOUT_MS);
166
+ try {
167
+ const response = await fetch(input, { ...init, signal: controller.signal });
168
+ return {
169
+ response,
170
+ done: () => clearTimeout(timeout),
171
+ // Body reads happen after `fetch` resolves, so an abort during one lands outside this
172
+ // try/catch and would surface as a native `AbortError`. Route them through here to get the
173
+ // same classification the header phase gets.
174
+ read: async <T>(consume: () => Promise<T>): Promise<T> => {
175
+ try {
176
+ return await consume();
177
+ } catch (cause) {
178
+ throw timedOut ? new S3TimeoutError(input.host, S3_TIMEOUT_MS) : cause;
179
+ }
180
+ },
181
+ };
182
+ } catch (cause) {
183
+ clearTimeout(timeout);
184
+ // A slow endpoint must not be reported as a CORS problem: `S3NetworkError` tells the user to fix
185
+ // a bucket policy, which for a timeout is advice about something that is already correct.
186
+ if (timedOut) {
187
+ throw new S3TimeoutError(input.host, S3_TIMEOUT_MS);
188
+ }
189
+ throw new S3NetworkError(input.host, cause);
190
+ }
191
+ };
192
+
193
+ export type PutOptions = {
194
+ uri: S3Uri;
195
+ data: Uint8Array;
196
+ contentType?: string;
197
+ /** Hex SHA-256 of `data`, already computed by the blob manager. */
198
+ contentHash: string;
199
+ credentials: S3Credentials;
200
+ now?: () => Date;
201
+ };
202
+
203
+ export const putObject = async ({
204
+ uri,
205
+ data,
206
+ contentType,
207
+ contentHash,
208
+ credentials,
209
+ now = () => new Date(),
210
+ }: PutOptions): Promise<void> => {
211
+ const url = toHttpsUrl(uri);
212
+ const headers = await signRequest({
213
+ method: 'PUT',
214
+ url,
215
+ // `content-length` is deliberately absent: it is a forbidden header name, so the browser sets it
216
+ // itself and strips ours — signing it would guarantee a mismatch the server reports as a bad
217
+ // signature rather than a missing header.
218
+ headers: contentType ? { 'content-type': contentType } : {},
219
+ payloadHash: contentHash,
220
+ credentials: toSigningCredentials(credentials, uri.host),
221
+ date: now(),
222
+ });
223
+
224
+ const { response, done, read } = await request(url, { method: 'PUT', headers, body: toArrayBufferView(data) });
225
+ try {
226
+ if (!response.ok) {
227
+ throw new S3RequestError(response.status, response.statusText, await read(() => response.text()).catch(() => ''));
228
+ }
229
+ } finally {
230
+ done();
231
+ }
232
+ };
233
+
234
+ export type ReadOptions = {
235
+ uri: S3Uri;
236
+ /** Omitted for an unsigned read against a public bucket. */
237
+ credentials?: S3Credentials;
238
+ now?: () => Date;
239
+ };
240
+
241
+ const readRequest = async (
242
+ method: 'GET' | 'HEAD',
243
+ { uri, credentials, now = () => new Date() }: ReadOptions,
244
+ ): Promise<TimedRequest> => {
245
+ const url = toHttpsUrl(uri);
246
+ const headers = credentials
247
+ ? await signRequest({
248
+ method,
249
+ url,
250
+ credentials: toSigningCredentials(credentials, uri.host),
251
+ date: now(),
252
+ })
253
+ : undefined;
254
+
255
+ return request(url, { method, headers });
256
+ };
257
+
258
+ /**
259
+ * Whether a failed read should be reported as "not there" rather than raised.
260
+ *
261
+ * A signed read is authoritative, so only 404 and 403 are misses and anything else is a fault worth
262
+ * surfacing. An unsigned read is speculative — it is a guess that the bucket is public — so any
263
+ * client error just means "not publicly readable". The distinction is load-bearing: R2 answers an
264
+ * unauthenticated request to a private bucket with `400 InvalidArgument`, not the 403 that AWS
265
+ * returns, so a 404/403-only rule turns the public-bucket fallback into a thrown error.
266
+ */
267
+ const isMiss = (status: number, signed: boolean): boolean =>
268
+ signed ? status === 404 || status === 403 : status >= 400 && status < 500;
269
+
270
+ /**
271
+ * Reads an object's bytes.
272
+ *
273
+ * Resolves `undefined` when the object is absent, or is not readable with the credentials in hand —
274
+ * see {@link isMiss} for which statuses count. Rejects on a transport failure or an unexpected
275
+ * status, since neither is evidence the object is missing.
276
+ */
277
+ export const getObject = async (options: ReadOptions): Promise<Uint8Array | undefined> => {
278
+ const { response, done, read } = await readRequest('GET', options);
279
+ try {
280
+ if (!response.ok) {
281
+ if (isMiss(response.status, !!options.credentials)) {
282
+ return undefined;
283
+ }
284
+ throw new S3RequestError(response.status, response.statusText, await read(() => response.text()).catch(() => ''));
285
+ }
286
+
287
+ return new Uint8Array(await read(() => response.arrayBuffer()));
288
+ } finally {
289
+ done();
290
+ }
291
+ };
292
+
293
+ /**
294
+ * Whether an object exists and is readable with the credentials in hand. Same miss semantics as
295
+ * {@link getObject}, and the same rejection on anything that is not evidence of absence.
296
+ */
297
+ export const headObject = async (options: ReadOptions): Promise<boolean> => {
298
+ const { response, done, read } = await readRequest('HEAD', options);
299
+ if (!response.ok) {
300
+ try {
301
+ if (isMiss(response.status, !!options.credentials)) {
302
+ return false;
303
+ }
304
+ throw new S3RequestError(response.status, response.statusText, await read(() => response.text()).catch(() => ''));
305
+ } finally {
306
+ done();
307
+ }
308
+ }
309
+ done();
310
+
311
+ return true;
312
+ };
313
+
314
+ /**
315
+ * A URL an `<img>`/`<video>` can load directly. Presigned when a credential is available; the plain
316
+ * public URL otherwise, which is correct for a public bucket and simply fails to load for a private
317
+ * one — the same outcome as returning nothing, without suppressing the browser's own diagnostics.
318
+ */
319
+ export const getObjectUrl = async ({ uri, credentials, now = () => new Date() }: ReadOptions): Promise<string> => {
320
+ const url = toHttpsUrl(uri);
321
+ if (!credentials) {
322
+ return url.toString();
323
+ }
324
+
325
+ return presignUrl({
326
+ url,
327
+ expiresIn: PRESIGN_EXPIRY_SECONDS,
328
+ credentials: toSigningCredentials(credentials, uri.host),
329
+ date: now(),
330
+ });
331
+ };
@@ -0,0 +1,81 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { describe, test } from 'vitest';
6
+
7
+ import { DEFAULT_REGION } from './constants.ts';
8
+ import { formatUri, objectKey, parseUri, regionFromHost, toHttpsUrl } from './s3-uri.ts';
9
+
10
+ describe('s3 uri', () => {
11
+ test('round-trips through format and parse', ({ expect }) => {
12
+ const uri = { host: 'media.abc123.r2.cloudflarestorage.com', key: 'SPACEID/deadbeef' };
13
+ expect(parseUri(formatUri(uri))).toEqual(uri);
14
+ });
15
+
16
+ test('keeps slashes in a nested key', ({ expect }) => {
17
+ expect(parseUri('s3://host/a/b/c')).toEqual({ host: 'host', key: 'a/b/c' });
18
+ });
19
+
20
+ test('rejects a uri belonging to another backend', ({ expect }) => {
21
+ expect(parseUri('wnfs://host/key')).toBeUndefined();
22
+ expect(parseUri('ni:///sha-256;abc')).toBeUndefined();
23
+ expect(parseUri('s3://host-with-no-key')).toBeUndefined();
24
+ });
25
+
26
+ test('builds an https url with each segment escaped', ({ expect }) => {
27
+ expect(toHttpsUrl({ host: 'bucket.example.com', key: 'a b/c+d' }).toString()).toBe(
28
+ 'https://bucket.example.com/a%20b/c%2Bd',
29
+ );
30
+ });
31
+
32
+ test('reads the signing region out of an AWS hostname', ({ expect }) => {
33
+ expect(regionFromHost('media.s3.eu-west-1.amazonaws.com')).toBe('eu-west-1');
34
+ expect(regionFromHost('s3.us-east-2.amazonaws.com')).toBe('us-east-2');
35
+ });
36
+
37
+ // The legacy global endpoint carries no region but routes to us-east-1; signing it `auto` fails
38
+ // with SignatureDoesNotMatch, which names nothing useful.
39
+ test('signs the legacy global endpoint as us-east-1', ({ expect }) => {
40
+ expect(regionFromHost('media.s3.amazonaws.com')).toBe('us-east-1');
41
+ expect(regionFromHost('s3.amazonaws.com')).toBe('us-east-1');
42
+ });
43
+
44
+ // WHATWG URL parsing resolves these away — and decodes %2E first, so encoding cannot save them.
45
+ // Reading the wrong object silently is worse than refusing to address it.
46
+ test('refuses a key with a relative path segment', ({ expect }) => {
47
+ expect(() => toHttpsUrl({ host: 'bucket.example.com', key: './file' })).toThrow(/relative path segment/);
48
+ expect(() => toHttpsUrl({ host: 'bucket.example.com', key: 'folder/../file' })).toThrow(/relative path segment/);
49
+ });
50
+
51
+ // A blob URI is replicated data, so on a headless host its endpoint is attacker-influenced input
52
+ // to a server-side fetch — and the unsigned read path needs no credential to reach one.
53
+ test('refuses a private or loopback endpoint', ({ expect }) => {
54
+ for (const host of ['127.0.0.1', 'localhost', '169.254.169.254', '10.0.0.1', '192.168.1.1', '[::1]']) {
55
+ expect(() => toHttpsUrl({ host, key: 'a/b' }), host).toThrow(/private or loopback host/);
56
+ }
57
+ });
58
+
59
+ // Userinfo makes the authority lie: everything before the `@` is credentials, so a string check
60
+ // on the leading text sees an allowed bucket while the request goes to the address after it.
61
+ test('refuses an authority carrying userinfo', ({ expect }) => {
62
+ expect(() => toHttpsUrl({ host: 'bucket.s3.amazonaws.com:443@169.254.169.254', key: 'a/b' })).toThrow(
63
+ /userinfo|private or loopback/,
64
+ );
65
+ expect(() => toHttpsUrl({ host: 'user:pass@127.0.0.1', key: 'a/b' })).toThrow(/userinfo|private or loopback/);
66
+ });
67
+
68
+ test('a dot inside a segment is untouched', ({ expect }) => {
69
+ expect(toHttpsUrl({ host: 'bucket.example.com', key: 'a/file.png' }).pathname).toBe('/a/file.png');
70
+ expect(toHttpsUrl({ host: 'bucket.example.com', key: 'a/...b' }).pathname).toBe('/a/...b');
71
+ });
72
+
73
+ test('falls back to the default region for endpoints that encode none', ({ expect }) => {
74
+ expect(regionFromHost('media.abc123.r2.cloudflarestorage.com')).toBe(DEFAULT_REGION);
75
+ expect(regionFromHost('minio.internal:9000')).toBe(DEFAULT_REGION);
76
+ });
77
+
78
+ test('scopes the object key by space', ({ expect }) => {
79
+ expect(objectKey({ spaceId: 'SPACEID', contentHash: 'deadbeef' })).toBe('SPACEID/deadbeef');
80
+ });
81
+ });
@@ -0,0 +1,93 @@
1
+ //
2
+ // Copyright 2026 DXOS.org
3
+ //
4
+
5
+ import { isBlockedHost } from '@dxos/util';
6
+
7
+ import { DEFAULT_REGION, S3_SCHEME } from './constants.ts';
8
+
9
+ /**
10
+ * A stored blob's address: `s3://<host>/<key>`, where `host` is the virtual-hosted-style bucket
11
+ * endpoint (`media.<account>.r2.cloudflarestorage.com`, `media.s3.eu-west-1.amazonaws.com`).
12
+ *
13
+ * The host carries the bucket, so it is also the `AccessToken.source` the credential is filed
14
+ * under — one connection per bucket, resolved without a side table mapping URIs to configuration.
15
+ */
16
+ export type S3Uri = {
17
+ host: string;
18
+ key: string;
19
+ };
20
+
21
+ export const formatUri = ({ host, key }: S3Uri): string => `${S3_SCHEME}://${host}/${key}`;
22
+
23
+ /** Returns `undefined` for anything that is not one of this backend's URIs. */
24
+ export const parseUri = (uri: string): S3Uri | undefined => {
25
+ const match = /^s3:\/\/([^/]+)\/(.+)$/.exec(uri);
26
+ if (!match) {
27
+ return undefined;
28
+ }
29
+
30
+ const [, host, key] = match;
31
+ return { host, key };
32
+ };
33
+
34
+ /**
35
+ * The HTTPS URL the object is served from. Public buckets resolve this without a signature.
36
+ *
37
+ * Rejects `.` and `..` segments rather than trying to carry them. WHATWG URL parsing resolves them
38
+ * away, and percent-encoding does not help — it decodes `%2E` and normalizes anyway — so such a key
39
+ * would silently be requested at a different path than the one it was stored under. Nothing this
40
+ * package writes produces one (`objectKey` is a space id and a hex digest), so a key that reaches
41
+ * here with a dot segment is a corrupted or hand-authored URI, and failing is better than reading
42
+ * the wrong object.
43
+ */
44
+ export const toHttpsUrl = ({ host, key }: S3Uri): URL => {
45
+ const segments = key.split('/');
46
+ if (segments.some((segment) => segment === '.' || segment === '..')) {
47
+ throw new Error(`Refusing to address an S3 key with a relative path segment: ${key}`);
48
+ }
49
+
50
+ const url = new URL(`https://${host}/${segments.map((segment) => encodeURIComponent(segment)).join('/')}`);
51
+
52
+ // Userinfo makes the authority lie: in `bucket.s3.amazonaws.com:443@169.254.169.254` everything
53
+ // before the `@` is credentials, and the request goes to the address after it. Refuse it outright
54
+ // rather than try to read past it — no legitimate bucket endpoint carries any.
55
+ if (url.username !== '' || url.password !== '') {
56
+ throw new Error(`Refusing to address an S3 endpoint carrying userinfo: ${host}`);
57
+ }
58
+
59
+ // Checked against the *parsed* hostname, which is what `fetch` will actually connect to. The host
60
+ // comes from a stored `Blob` URI — replicated data, so on a headless host it is attacker-influenced
61
+ // input to a server-side fetch. A browser is bounded by CORS; EDGE's function runtime is not, and
62
+ // the unsigned read path needs no credential to reach an internal address.
63
+ if (isBlockedHost(url.hostname)) {
64
+ throw new Error(`Refusing to address an S3 endpoint on a private or loopback host: ${url.hostname}`);
65
+ }
66
+
67
+ return url;
68
+ };
69
+
70
+ /**
71
+ * SigV4 signing region for an endpoint. AWS encodes it in the hostname; R2 and most self-hosted
72
+ * S3 implementations do not, and take {@link DEFAULT_REGION}.
73
+ *
74
+ * The legacy global endpoint (`bucket.s3.amazonaws.com`, no region segment) is the exception: it
75
+ * routes to us-east-1 and must be signed for that region, since signing it `auto` yields
76
+ * `SignatureDoesNotMatch` rather than anything that names the real problem.
77
+ */
78
+ export const regionFromHost = (host: string): string => {
79
+ if (/(?:^|\.)s3\.amazonaws\.com$/.test(host)) {
80
+ return 'us-east-1';
81
+ }
82
+
83
+ const match = /(?:^|\.)s3[.-]([a-z0-9-]+)\.amazonaws\.com$/.exec(host);
84
+ return match ? match[1] : DEFAULT_REGION;
85
+ };
86
+
87
+ /**
88
+ * Object key for a blob. Content-addressed by the digest the blob manager already computed, under a
89
+ * space-scoped prefix so one bucket can serve many spaces and a listing stays navigable. The
90
+ * original filename is deliberately not in the path — it is not unique, and ECHO holds it.
91
+ */
92
+ export const objectKey = ({ spaceId, contentHash }: { spaceId: string; contentHash: string }): string =>
93
+ `${spaceId}/${contentHash}`;