@dxos/blob 0.11.1 → 0.14.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 +13 -4
- package/dist/lib/chunk-ni-uri.mjs +103 -0
- package/dist/lib/chunk-ni-uri.mjs.map +1 -0
- package/dist/lib/hosted.mjs +55 -0
- package/dist/lib/hosted.mjs.map +1 -0
- package/dist/lib/index.mjs +2 -0
- package/dist/lib/s3.mjs +515 -0
- package/dist/lib/s3.mjs.map +1 -0
- package/dist/types/src/backend.d.ts +31 -0
- package/dist/types/src/backend.d.ts.map +1 -1
- package/dist/types/src/hosted/blob-backend.d.ts +21 -0
- package/dist/types/src/hosted/blob-backend.d.ts.map +1 -0
- package/dist/types/src/hosted/blob-backend.test.d.ts +2 -0
- package/dist/types/src/hosted/blob-backend.test.d.ts.map +1 -0
- package/dist/types/src/hosted/index.d.ts +2 -0
- package/dist/types/src/hosted/index.d.ts.map +1 -0
- package/dist/types/src/index.d.ts +2 -1
- package/dist/types/src/index.d.ts.map +1 -1
- package/dist/types/src/ni-uri.d.ts +51 -0
- package/dist/types/src/ni-uri.d.ts.map +1 -0
- package/dist/types/src/ni-uri.test.d.ts +2 -0
- package/dist/types/src/ni-uri.test.d.ts.map +1 -0
- package/dist/types/src/s3/blob-backend.d.ts +38 -0
- package/dist/types/src/s3/blob-backend.d.ts.map +1 -0
- package/dist/types/src/s3/constants.d.ts +17 -0
- package/dist/types/src/s3/constants.d.ts.map +1 -0
- package/dist/types/src/s3/index.d.ts +6 -0
- package/dist/types/src/s3/index.d.ts.map +1 -0
- package/dist/types/src/s3/s3-client.d.ts +93 -0
- package/dist/types/src/s3/s3-client.d.ts.map +1 -0
- package/dist/types/src/s3/s3-client.test.d.ts +2 -0
- package/dist/types/src/s3/s3-client.test.d.ts.map +1 -0
- package/dist/types/src/s3/s3-uri.d.ts +44 -0
- package/dist/types/src/s3/s3-uri.d.ts.map +1 -0
- package/dist/types/src/s3/s3-uri.test.d.ts +2 -0
- package/dist/types/src/s3/s3-uri.test.d.ts.map +1 -0
- package/dist/types/src/s3/sigv4.d.ts +55 -0
- package/dist/types/src/s3/sigv4.d.ts.map +1 -0
- package/dist/types/src/s3/sigv4.test.d.ts +2 -0
- package/dist/types/src/s3/sigv4.test.d.ts.map +1 -0
- package/dist/types/tsconfig.tsbuildinfo +1 -1
- package/package.json +14 -2
- package/src/backend.ts +23 -0
- package/src/hosted/blob-backend.test.ts +113 -0
- package/src/hosted/blob-backend.ts +67 -0
- package/src/hosted/index.ts +5 -0
- package/src/index.ts +2 -1
- package/src/ni-uri.test.ts +31 -0
- package/src/ni-uri.ts +136 -0
- package/src/s3/blob-backend.ts +75 -0
- package/src/s3/constants.ts +24 -0
- package/src/s3/index.ts +13 -0
- package/src/s3/s3-client.test.ts +145 -0
- package/src/s3/s3-client.ts +331 -0
- package/src/s3/s3-uri.test.ts +81 -0
- package/src/s3/s3-uri.ts +93 -0
- package/src/s3/sigv4.test.ts +99 -0
- package/src/s3/sigv4.ts +203 -0
package/dist/lib/s3.mjs
ADDED
|
@@ -0,0 +1,515 @@
|
|
|
1
|
+
import { invariant } from "@dxos/invariant";
|
|
2
|
+
import { isBlockedHost } from "@dxos/util";
|
|
3
|
+
//#region src/s3/constants.ts
|
|
4
|
+
/**
|
|
5
|
+
* Name this backend registers under on the ECHO Hypergraph, and the value `Blob.fromBytes`'s
|
|
6
|
+
* `storage` option takes when it is selected.
|
|
7
|
+
*/
|
|
8
|
+
var S3_BACKEND = "s3";
|
|
9
|
+
/** URI scheme this backend resolves at read time. */
|
|
10
|
+
var S3_SCHEME = "s3";
|
|
11
|
+
/**
|
|
12
|
+
* Signing region for endpoints that do not encode one. R2 ignores the region but SigV4 still
|
|
13
|
+
* requires a value in the credential scope, and `auto` is what Cloudflare documents.
|
|
14
|
+
*/
|
|
15
|
+
var DEFAULT_REGION = "auto";
|
|
16
|
+
/** Lifetime of a presigned GET URL. Long enough to render a large asset, short enough to not be a handout. */
|
|
17
|
+
var PRESIGN_EXPIRY_SECONDS = 900;
|
|
18
|
+
/** Abort a bucket request after this many ms so a hung call cannot wedge an upload or a render. */
|
|
19
|
+
var S3_TIMEOUT_MS = 6e4;
|
|
20
|
+
//#endregion
|
|
21
|
+
//#region src/s3/s3-uri.ts
|
|
22
|
+
var formatUri = ({ host, key }) => `s3://${host}/${key}`;
|
|
23
|
+
/** Returns `undefined` for anything that is not one of this backend's URIs. */
|
|
24
|
+
var parseUri = (uri) => {
|
|
25
|
+
const match = /^s3:\/\/([^/]+)\/(.+)$/.exec(uri);
|
|
26
|
+
if (!match) return;
|
|
27
|
+
const [, host, key] = match;
|
|
28
|
+
return {
|
|
29
|
+
host,
|
|
30
|
+
key
|
|
31
|
+
};
|
|
32
|
+
};
|
|
33
|
+
/**
|
|
34
|
+
* The HTTPS URL the object is served from. Public buckets resolve this without a signature.
|
|
35
|
+
*
|
|
36
|
+
* Rejects `.` and `..` segments rather than trying to carry them. WHATWG URL parsing resolves them
|
|
37
|
+
* away, and percent-encoding does not help — it decodes `%2E` and normalizes anyway — so such a key
|
|
38
|
+
* would silently be requested at a different path than the one it was stored under. Nothing this
|
|
39
|
+
* package writes produces one (`objectKey` is a space id and a hex digest), so a key that reaches
|
|
40
|
+
* here with a dot segment is a corrupted or hand-authored URI, and failing is better than reading
|
|
41
|
+
* the wrong object.
|
|
42
|
+
*/
|
|
43
|
+
var toHttpsUrl = ({ host, key }) => {
|
|
44
|
+
const segments = key.split("/");
|
|
45
|
+
if (segments.some((segment) => segment === "." || segment === "..")) throw new Error(`Refusing to address an S3 key with a relative path segment: ${key}`);
|
|
46
|
+
const url = new URL(`https://${host}/${segments.map((segment) => encodeURIComponent(segment)).join("/")}`);
|
|
47
|
+
if (url.username !== "" || url.password !== "") throw new Error(`Refusing to address an S3 endpoint carrying userinfo: ${host}`);
|
|
48
|
+
if (isBlockedHost(url.hostname)) throw new Error(`Refusing to address an S3 endpoint on a private or loopback host: ${url.hostname}`);
|
|
49
|
+
return url;
|
|
50
|
+
};
|
|
51
|
+
/**
|
|
52
|
+
* SigV4 signing region for an endpoint. AWS encodes it in the hostname; R2 and most self-hosted
|
|
53
|
+
* S3 implementations do not, and take {@link DEFAULT_REGION}.
|
|
54
|
+
*
|
|
55
|
+
* The legacy global endpoint (`bucket.s3.amazonaws.com`, no region segment) is the exception: it
|
|
56
|
+
* routes to us-east-1 and must be signed for that region, since signing it `auto` yields
|
|
57
|
+
* `SignatureDoesNotMatch` rather than anything that names the real problem.
|
|
58
|
+
*/
|
|
59
|
+
var regionFromHost = (host) => {
|
|
60
|
+
if (/(?:^|\.)s3\.amazonaws\.com$/.test(host)) return "us-east-1";
|
|
61
|
+
const match = /(?:^|\.)s3[.-]([a-z0-9-]+)\.amazonaws\.com$/.exec(host);
|
|
62
|
+
return match ? match[1] : DEFAULT_REGION;
|
|
63
|
+
};
|
|
64
|
+
/**
|
|
65
|
+
* Object key for a blob. Content-addressed by the digest the blob manager already computed, under a
|
|
66
|
+
* space-scoped prefix so one bucket can serve many spaces and a listing stays navigable. The
|
|
67
|
+
* original filename is deliberately not in the path — it is not unique, and ECHO holds it.
|
|
68
|
+
*/
|
|
69
|
+
var objectKey = ({ spaceId, contentHash }) => `${spaceId}/${contentHash}`;
|
|
70
|
+
//#endregion
|
|
71
|
+
//#region src/s3/sigv4.ts
|
|
72
|
+
/**
|
|
73
|
+
* AWS Signature Version 4 for S3-compatible endpoints, over WebCrypto.
|
|
74
|
+
*
|
|
75
|
+
* Hand-rolled rather than taken from `@aws-sdk/*`: the SDK's signer pulls in a credential-provider
|
|
76
|
+
* chain, a region resolver and a Node crypto shim, none of which apply to a browser holding one
|
|
77
|
+
* static key pair — and it is two orders of magnitude larger than the ~150 lines the algorithm needs.
|
|
78
|
+
*/
|
|
79
|
+
var ALGORITHM = "AWS4-HMAC-SHA256";
|
|
80
|
+
var SERVICE = "s3";
|
|
81
|
+
var TERMINATOR = "aws4_request";
|
|
82
|
+
/** Payload hash S3 accepts in place of a real digest when the body is not signed (presigned URLs). */
|
|
83
|
+
var UNSIGNED_PAYLOAD = "UNSIGNED-PAYLOAD";
|
|
84
|
+
/** SHA-256 of the empty string; the payload hash for every request with no body. */
|
|
85
|
+
var EMPTY_PAYLOAD_HASH = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855";
|
|
86
|
+
var encoder = new TextEncoder();
|
|
87
|
+
var toHex = (bytes) => Array.from(bytes).map((byte) => byte.toString(16).padStart(2, "0")).join("");
|
|
88
|
+
/**
|
|
89
|
+
* Narrows a view to one backed by a plain `ArrayBuffer`. `Uint8Array` is generic over
|
|
90
|
+
* `ArrayBufferLike`, which includes `SharedArrayBuffer`; WebCrypto and `fetch` accept only the
|
|
91
|
+
* former. The common case aliases the existing buffer, so this costs nothing but a wrapper.
|
|
92
|
+
*/
|
|
93
|
+
var toArrayBufferView = (data) => data.buffer instanceof ArrayBuffer ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : new Uint8Array(data);
|
|
94
|
+
var sha256Hex = async (data) => {
|
|
95
|
+
const bytes = typeof data === "string" ? encoder.encode(data) : toArrayBufferView(data);
|
|
96
|
+
return toHex(new Uint8Array(await crypto.subtle.digest("SHA-256", bytes)));
|
|
97
|
+
};
|
|
98
|
+
var hmac = async (key, message) => {
|
|
99
|
+
const cryptoKey = await crypto.subtle.importKey("raw", key, {
|
|
100
|
+
name: "HMAC",
|
|
101
|
+
hash: "SHA-256"
|
|
102
|
+
}, false, ["sign"]);
|
|
103
|
+
return new Uint8Array(await crypto.subtle.sign("HMAC", cryptoKey, encoder.encode(message)));
|
|
104
|
+
};
|
|
105
|
+
/**
|
|
106
|
+
* RFC 3986 percent-encoding. `encodeURIComponent` leaves `!'()*` unescaped, which AWS treats as a
|
|
107
|
+
* signature mismatch rather than an equivalent encoding.
|
|
108
|
+
*/
|
|
109
|
+
var uriEncode = (value) => encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
|
|
110
|
+
/** Encodes an object key for the canonical URI: every segment escaped, the separating slashes kept. */
|
|
111
|
+
var encodeObjectKey = (key) => key.split("/").map(uriEncode).join("/");
|
|
112
|
+
/** `20260826T143000Z` and `20260826` — the two timestamp forms SigV4 uses. */
|
|
113
|
+
var formatTimestamps = (date) => {
|
|
114
|
+
const amzDate = date.toISOString().replace(/[:-]|\.\d{3}/g, "");
|
|
115
|
+
return {
|
|
116
|
+
amzDate,
|
|
117
|
+
dateStamp: amzDate.slice(0, 8)
|
|
118
|
+
};
|
|
119
|
+
};
|
|
120
|
+
var canonicalQuery = (params) => [...params.entries()].map(([key, value]) => [uriEncode(key), uriEncode(value)]).sort(([leftKey, leftValue], [rightKey, rightValue]) => leftKey === rightKey ? leftValue < rightValue ? -1 : 1 : leftKey < rightKey ? -1 : 1).map(([key, value]) => `${key}=${value}`).join("&");
|
|
121
|
+
var canonicalHeaders = (headers) => {
|
|
122
|
+
const normalized = Object.entries(headers).map(([name, value]) => [name.toLowerCase(), value.trim().replace(/\s+/g, " ")]).sort(([left], [right]) => left < right ? -1 : 1);
|
|
123
|
+
return {
|
|
124
|
+
canonical: normalized.map(([name, value]) => `${name}:${value}\n`).join(""),
|
|
125
|
+
signed: normalized.map(([name]) => name).join(";")
|
|
126
|
+
};
|
|
127
|
+
};
|
|
128
|
+
var signingKey = async ({ secretAccessKey, region }, dateStamp) => {
|
|
129
|
+
return hmac(await hmac(await hmac(await hmac(encoder.encode(`AWS4${secretAccessKey}`), dateStamp), region), SERVICE), TERMINATOR);
|
|
130
|
+
};
|
|
131
|
+
var sign = async (credentials, dateStamp, amzDate, canonicalRequest) => {
|
|
132
|
+
const scope = `${dateStamp}/${credentials.region}/${SERVICE}/${TERMINATOR}`;
|
|
133
|
+
const stringToSign = [
|
|
134
|
+
ALGORITHM,
|
|
135
|
+
amzDate,
|
|
136
|
+
scope,
|
|
137
|
+
await sha256Hex(canonicalRequest)
|
|
138
|
+
].join("\n");
|
|
139
|
+
return {
|
|
140
|
+
signature: toHex(await hmac(await signingKey(credentials, dateStamp), stringToSign)),
|
|
141
|
+
scope
|
|
142
|
+
};
|
|
143
|
+
};
|
|
144
|
+
/**
|
|
145
|
+
* Signs a request with an `Authorization` header. Returns the headers to send — the caller's
|
|
146
|
+
* `headers` plus `host`, `x-amz-date`, `x-amz-content-sha256` and `Authorization`.
|
|
147
|
+
*/
|
|
148
|
+
var signRequest = async ({ method, url, headers = {}, payloadHash = EMPTY_PAYLOAD_HASH, credentials, date }) => {
|
|
149
|
+
const { amzDate, dateStamp } = formatTimestamps(date);
|
|
150
|
+
const signedHeaderSet = {
|
|
151
|
+
...headers,
|
|
152
|
+
"host": url.host,
|
|
153
|
+
"x-amz-date": amzDate,
|
|
154
|
+
"x-amz-content-sha256": payloadHash
|
|
155
|
+
};
|
|
156
|
+
const { canonical, signed } = canonicalHeaders(signedHeaderSet);
|
|
157
|
+
const { signature, scope } = await sign(credentials, dateStamp, amzDate, [
|
|
158
|
+
method,
|
|
159
|
+
encodeObjectKey(decodeURIComponent(url.pathname)),
|
|
160
|
+
canonicalQuery(url.searchParams),
|
|
161
|
+
canonical,
|
|
162
|
+
signed,
|
|
163
|
+
payloadHash
|
|
164
|
+
].join("\n"));
|
|
165
|
+
return {
|
|
166
|
+
...signedHeaderSet,
|
|
167
|
+
Authorization: `${ALGORITHM} Credential=${credentials.accessKeyId}/${scope}, SignedHeaders=${signed}, Signature=${signature}`
|
|
168
|
+
};
|
|
169
|
+
};
|
|
170
|
+
/**
|
|
171
|
+
* Produces a URL carrying its own authorization in the query string, so it can be handed to an
|
|
172
|
+
* `<img>` or `<video>` element that cannot send an `Authorization` header.
|
|
173
|
+
*/
|
|
174
|
+
var presignUrl = async ({ method = "GET", url, expiresIn, credentials, date }) => {
|
|
175
|
+
const { amzDate, dateStamp } = formatTimestamps(date);
|
|
176
|
+
const scope = `${dateStamp}/${credentials.region}/${SERVICE}/${TERMINATOR}`;
|
|
177
|
+
const signedUrl = new URL(url.toString());
|
|
178
|
+
signedUrl.searchParams.set("X-Amz-Algorithm", ALGORITHM);
|
|
179
|
+
signedUrl.searchParams.set("X-Amz-Credential", `${credentials.accessKeyId}/${scope}`);
|
|
180
|
+
signedUrl.searchParams.set("X-Amz-Date", amzDate);
|
|
181
|
+
signedUrl.searchParams.set("X-Amz-Expires", String(expiresIn));
|
|
182
|
+
signedUrl.searchParams.set("X-Amz-SignedHeaders", "host");
|
|
183
|
+
const { signature } = await sign(credentials, dateStamp, amzDate, [
|
|
184
|
+
method,
|
|
185
|
+
encodeObjectKey(decodeURIComponent(signedUrl.pathname)),
|
|
186
|
+
canonicalQuery(signedUrl.searchParams),
|
|
187
|
+
`host:${signedUrl.host}\n`,
|
|
188
|
+
"host",
|
|
189
|
+
UNSIGNED_PAYLOAD
|
|
190
|
+
].join("\n"));
|
|
191
|
+
signedUrl.searchParams.set("X-Amz-Signature", signature);
|
|
192
|
+
return signedUrl.toString();
|
|
193
|
+
};
|
|
194
|
+
//#endregion
|
|
195
|
+
//#region src/s3/s3-client.ts
|
|
196
|
+
var toSigningCredentials = (credentials, host) => ({
|
|
197
|
+
...credentials,
|
|
198
|
+
region: regionFromHost(host)
|
|
199
|
+
});
|
|
200
|
+
/** Rejects rather than resolving `undefined`: a transport failure is not a missing object. */
|
|
201
|
+
var S3RequestError = class extends Error {
|
|
202
|
+
status;
|
|
203
|
+
statusText;
|
|
204
|
+
body;
|
|
205
|
+
constructor(status, statusText, body) {
|
|
206
|
+
super(`S3 request failed: ${status} ${statusText}${body ? ` — ${body}` : ""}`);
|
|
207
|
+
this.status = status;
|
|
208
|
+
this.statusText = statusText;
|
|
209
|
+
this.body = body;
|
|
210
|
+
this.name = "S3RequestError";
|
|
211
|
+
}
|
|
212
|
+
};
|
|
213
|
+
/** The page's own origin, which is what a bucket CORS policy has to name. */
|
|
214
|
+
var currentOrigin = () => typeof globalThis.location?.origin === "string" ? globalThis.location.origin : "this origin";
|
|
215
|
+
/**
|
|
216
|
+
* A request the browser refused to send, or whose response it refused to expose. Almost always a
|
|
217
|
+
* missing bucket CORS policy: `fetch` reports that as an opaque `TypeError` and confines the real
|
|
218
|
+
* reason to the devtools console, so a blocked preflight would otherwise reach the user as
|
|
219
|
+
* "Failed to fetch".
|
|
220
|
+
*
|
|
221
|
+
* The message names the origin and the methods only. The required headers are in the README and in
|
|
222
|
+
* `details` — a status line has to be readable at a glance, and nobody writes a CORS policy from
|
|
223
|
+
* memory of a sentence anyway.
|
|
224
|
+
*/
|
|
225
|
+
var S3NetworkError = class extends Error {
|
|
226
|
+
host;
|
|
227
|
+
cause;
|
|
228
|
+
/** The full policy requirement, for logs and docs rather than the status line. */
|
|
229
|
+
details;
|
|
230
|
+
constructor(host, cause) {
|
|
231
|
+
super(`Blocked by CORS: the bucket must allow ${currentOrigin()} for GET, HEAD and PUT.`);
|
|
232
|
+
this.host = host;
|
|
233
|
+
this.cause = cause;
|
|
234
|
+
this.name = "S3NetworkError";
|
|
235
|
+
this.details = `${host} must allow origin ${currentOrigin()} for GET, HEAD and PUT, with the authorization, content-type, x-amz-content-sha256 and x-amz-date headers.`;
|
|
236
|
+
}
|
|
237
|
+
};
|
|
238
|
+
/**
|
|
239
|
+
* The request exceeded its deadline. Distinct from {@link S3NetworkError} because the remedies have
|
|
240
|
+
* nothing in common — a timeout says the endpoint is slow or unreachable, not that a bucket policy
|
|
241
|
+
* is wrong, and conflating them sends the user to edit configuration that is already correct.
|
|
242
|
+
*/
|
|
243
|
+
var S3TimeoutError = class extends Error {
|
|
244
|
+
host;
|
|
245
|
+
timeoutMs;
|
|
246
|
+
constructor(host, timeoutMs) {
|
|
247
|
+
super(`${host} did not respond within ${Math.round(timeoutMs / 1e3)}s.`);
|
|
248
|
+
this.host = host;
|
|
249
|
+
this.timeoutMs = timeoutMs;
|
|
250
|
+
this.name = "S3TimeoutError";
|
|
251
|
+
}
|
|
252
|
+
};
|
|
253
|
+
/** The S3 `<Code>` from an error body, which says far more than the HTTP status alone. */
|
|
254
|
+
var errorCode = (body) => /<Code>([^<]+)<\/Code>/.exec(body)?.[1];
|
|
255
|
+
/**
|
|
256
|
+
* Checks that the credential can address the bucket, and explains it when it cannot.
|
|
257
|
+
*
|
|
258
|
+
* Distinct from `headObject`, which deliberately reports 403 and 404 alike as "not there" — correct
|
|
259
|
+
* when reading a blob, useless for a connection test, where telling a rejected key from an absent
|
|
260
|
+
* object is the entire point. Probes a key that should not exist: 404 proves the signature was
|
|
261
|
+
* accepted, and every other outcome names what to fix.
|
|
262
|
+
*/
|
|
263
|
+
var probeAccess = async ({ uri, credentials }) => {
|
|
264
|
+
const url = toHttpsUrl(uri);
|
|
265
|
+
const { response, done } = await request(url, {
|
|
266
|
+
method: "HEAD",
|
|
267
|
+
headers: await signRequest({
|
|
268
|
+
method: "HEAD",
|
|
269
|
+
url,
|
|
270
|
+
credentials: toSigningCredentials(credentials, uri.host),
|
|
271
|
+
date: /* @__PURE__ */ new Date()
|
|
272
|
+
})
|
|
273
|
+
});
|
|
274
|
+
done();
|
|
275
|
+
if (response.ok || response.status === 404) return;
|
|
276
|
+
const body = await request(url, {
|
|
277
|
+
method: "GET",
|
|
278
|
+
headers: await signRequest({
|
|
279
|
+
method: "GET",
|
|
280
|
+
url,
|
|
281
|
+
credentials: toSigningCredentials(credentials, uri.host),
|
|
282
|
+
date: /* @__PURE__ */ new Date()
|
|
283
|
+
})
|
|
284
|
+
}).then(async ({ response: errorResponse, done: doneReadingError, read }) => {
|
|
285
|
+
try {
|
|
286
|
+
return await read(() => errorResponse.text());
|
|
287
|
+
} finally {
|
|
288
|
+
doneReadingError();
|
|
289
|
+
}
|
|
290
|
+
}).catch(() => "");
|
|
291
|
+
const bucket = uri.host.split(".")[0];
|
|
292
|
+
switch (errorCode(body) ?? String(response.status)) {
|
|
293
|
+
case "InvalidAccessKeyId": throw new Error("Unknown access key ID.");
|
|
294
|
+
case "SignatureDoesNotMatch": throw new Error("Wrong secret access key.");
|
|
295
|
+
case "AccessDenied": throw new Error(`Key not permitted on "${bucket}".`);
|
|
296
|
+
case "NoSuchBucket":
|
|
297
|
+
case "InvalidBucketName": throw new Error(`No such bucket: "${bucket}".`);
|
|
298
|
+
default: throw new S3RequestError(response.status, response.statusText, body);
|
|
299
|
+
}
|
|
300
|
+
};
|
|
301
|
+
/**
|
|
302
|
+
* A timed request whose deadline covers the body as well as the headers.
|
|
303
|
+
*
|
|
304
|
+
* The signal stays attached to the response body after `fetch` resolves, so the timeout has to be
|
|
305
|
+
* cancelled once the body is fully read — otherwise a large object that takes longer than
|
|
306
|
+
* {@link S3_TIMEOUT_MS} to transfer is aborted mid-read, after the caller already has a `Response`
|
|
307
|
+
* in hand. Callers signal completion by calling the returned `done`.
|
|
308
|
+
*/
|
|
309
|
+
var request = async (input, init) => {
|
|
310
|
+
const controller = new AbortController();
|
|
311
|
+
let timedOut = false;
|
|
312
|
+
const timeout = setTimeout(() => {
|
|
313
|
+
timedOut = true;
|
|
314
|
+
controller.abort();
|
|
315
|
+
}, S3_TIMEOUT_MS);
|
|
316
|
+
try {
|
|
317
|
+
return {
|
|
318
|
+
response: await fetch(input, {
|
|
319
|
+
...init,
|
|
320
|
+
signal: controller.signal
|
|
321
|
+
}),
|
|
322
|
+
done: () => clearTimeout(timeout),
|
|
323
|
+
read: async (consume) => {
|
|
324
|
+
try {
|
|
325
|
+
return await consume();
|
|
326
|
+
} catch (cause) {
|
|
327
|
+
throw timedOut ? new S3TimeoutError(input.host, S3_TIMEOUT_MS) : cause;
|
|
328
|
+
}
|
|
329
|
+
}
|
|
330
|
+
};
|
|
331
|
+
} catch (cause) {
|
|
332
|
+
clearTimeout(timeout);
|
|
333
|
+
if (timedOut) throw new S3TimeoutError(input.host, S3_TIMEOUT_MS);
|
|
334
|
+
throw new S3NetworkError(input.host, cause);
|
|
335
|
+
}
|
|
336
|
+
};
|
|
337
|
+
var putObject = async ({ uri, data, contentType, contentHash, credentials, now = () => /* @__PURE__ */ new Date() }) => {
|
|
338
|
+
const url = toHttpsUrl(uri);
|
|
339
|
+
const { response, done, read } = await request(url, {
|
|
340
|
+
method: "PUT",
|
|
341
|
+
headers: await signRequest({
|
|
342
|
+
method: "PUT",
|
|
343
|
+
url,
|
|
344
|
+
headers: contentType ? { "content-type": contentType } : {},
|
|
345
|
+
payloadHash: contentHash,
|
|
346
|
+
credentials: toSigningCredentials(credentials, uri.host),
|
|
347
|
+
date: now()
|
|
348
|
+
}),
|
|
349
|
+
body: toArrayBufferView(data)
|
|
350
|
+
});
|
|
351
|
+
try {
|
|
352
|
+
if (!response.ok) throw new S3RequestError(response.status, response.statusText, await read(() => response.text()).catch(() => ""));
|
|
353
|
+
} finally {
|
|
354
|
+
done();
|
|
355
|
+
}
|
|
356
|
+
};
|
|
357
|
+
var readRequest = async (method, { uri, credentials, now = () => /* @__PURE__ */ new Date() }) => {
|
|
358
|
+
const url = toHttpsUrl(uri);
|
|
359
|
+
return request(url, {
|
|
360
|
+
method,
|
|
361
|
+
headers: credentials ? await signRequest({
|
|
362
|
+
method,
|
|
363
|
+
url,
|
|
364
|
+
credentials: toSigningCredentials(credentials, uri.host),
|
|
365
|
+
date: now()
|
|
366
|
+
}) : void 0
|
|
367
|
+
});
|
|
368
|
+
};
|
|
369
|
+
/**
|
|
370
|
+
* Whether a failed read should be reported as "not there" rather than raised.
|
|
371
|
+
*
|
|
372
|
+
* A signed read is authoritative, so only 404 and 403 are misses and anything else is a fault worth
|
|
373
|
+
* surfacing. An unsigned read is speculative — it is a guess that the bucket is public — so any
|
|
374
|
+
* client error just means "not publicly readable". The distinction is load-bearing: R2 answers an
|
|
375
|
+
* unauthenticated request to a private bucket with `400 InvalidArgument`, not the 403 that AWS
|
|
376
|
+
* returns, so a 404/403-only rule turns the public-bucket fallback into a thrown error.
|
|
377
|
+
*/
|
|
378
|
+
var isMiss = (status, signed) => signed ? status === 404 || status === 403 : status >= 400 && status < 500;
|
|
379
|
+
/**
|
|
380
|
+
* Reads an object's bytes.
|
|
381
|
+
*
|
|
382
|
+
* Resolves `undefined` when the object is absent, or is not readable with the credentials in hand —
|
|
383
|
+
* see {@link isMiss} for which statuses count. Rejects on a transport failure or an unexpected
|
|
384
|
+
* status, since neither is evidence the object is missing.
|
|
385
|
+
*/
|
|
386
|
+
var getObject = async (options) => {
|
|
387
|
+
const { response, done, read } = await readRequest("GET", options);
|
|
388
|
+
try {
|
|
389
|
+
if (!response.ok) {
|
|
390
|
+
if (isMiss(response.status, !!options.credentials)) return;
|
|
391
|
+
throw new S3RequestError(response.status, response.statusText, await read(() => response.text()).catch(() => ""));
|
|
392
|
+
}
|
|
393
|
+
return new Uint8Array(await read(() => response.arrayBuffer()));
|
|
394
|
+
} finally {
|
|
395
|
+
done();
|
|
396
|
+
}
|
|
397
|
+
};
|
|
398
|
+
/**
|
|
399
|
+
* Whether an object exists and is readable with the credentials in hand. Same miss semantics as
|
|
400
|
+
* {@link getObject}, and the same rejection on anything that is not evidence of absence.
|
|
401
|
+
*/
|
|
402
|
+
var headObject = async (options) => {
|
|
403
|
+
const { response, done, read } = await readRequest("HEAD", options);
|
|
404
|
+
if (!response.ok) try {
|
|
405
|
+
if (isMiss(response.status, !!options.credentials)) return false;
|
|
406
|
+
throw new S3RequestError(response.status, response.statusText, await read(() => response.text()).catch(() => ""));
|
|
407
|
+
} finally {
|
|
408
|
+
done();
|
|
409
|
+
}
|
|
410
|
+
done();
|
|
411
|
+
return true;
|
|
412
|
+
};
|
|
413
|
+
/**
|
|
414
|
+
* A URL an `<img>`/`<video>` can load directly. Presigned when a credential is available; the plain
|
|
415
|
+
* public URL otherwise, which is correct for a public bucket and simply fails to load for a private
|
|
416
|
+
* one — the same outcome as returning nothing, without suppressing the browser's own diagnostics.
|
|
417
|
+
*/
|
|
418
|
+
var getObjectUrl = async ({ uri, credentials, now = () => /* @__PURE__ */ new Date() }) => {
|
|
419
|
+
const url = toHttpsUrl(uri);
|
|
420
|
+
if (!credentials) return url.toString();
|
|
421
|
+
return presignUrl({
|
|
422
|
+
url,
|
|
423
|
+
expiresIn: 900,
|
|
424
|
+
credentials: toSigningCredentials(credentials, uri.host),
|
|
425
|
+
date: now()
|
|
426
|
+
});
|
|
427
|
+
};
|
|
428
|
+
//#endregion
|
|
429
|
+
//#region src/s3/blob-backend.ts
|
|
430
|
+
var __dxlog_file = "/__w/dxos/dxos/packages/core/echo/blob/src/s3/blob-backend.ts";
|
|
431
|
+
/**
|
|
432
|
+
* Blob backend storing bytes in an S3-compatible bucket, addressed by `s3://<host>/<key>` URIs.
|
|
433
|
+
*
|
|
434
|
+
* Reads are attempted unsigned when the space holds no credential for the endpoint, so a public
|
|
435
|
+
* bucket renders for a viewer who was never given the writer's keys. Writes always require one.
|
|
436
|
+
*
|
|
437
|
+
* The bucket must allow the app's origin in its CORS policy for `PUT` and for any programmatic
|
|
438
|
+
* read; rendering does not need it, since a presigned URL in an `<img>` is not CORS-gated. In a
|
|
439
|
+
* headless host CORS does not apply at all.
|
|
440
|
+
*/
|
|
441
|
+
var createS3BlobBackend = ({ resolveCredentials, resolveWriteEndpoint }) => {
|
|
442
|
+
const resolve = (uri) => {
|
|
443
|
+
const parsed = parseUri(uri);
|
|
444
|
+
invariant(parsed, `not an s3 uri: ${uri}`, {
|
|
445
|
+
"~LogMeta": "~LogMeta",
|
|
446
|
+
F: __dxlog_file,
|
|
447
|
+
L: 44,
|
|
448
|
+
S: void 0,
|
|
449
|
+
A: ["parsed", "`not an s3 uri: ${uri}`"]
|
|
450
|
+
});
|
|
451
|
+
return parsed;
|
|
452
|
+
};
|
|
453
|
+
return {
|
|
454
|
+
schemes: ["s3"],
|
|
455
|
+
put: async ({ spaceId, data, contentType, contentHash }) => {
|
|
456
|
+
const endpoint = await resolveWriteEndpoint(spaceId);
|
|
457
|
+
invariant(endpoint, "no S3 connection in this space; connect a bucket before uploading", {
|
|
458
|
+
"~LogMeta": "~LogMeta",
|
|
459
|
+
F: __dxlog_file,
|
|
460
|
+
L: 53,
|
|
461
|
+
S: void 0,
|
|
462
|
+
A: ["endpoint", "'no S3 connection in this space; connect a bucket before uploading'"]
|
|
463
|
+
});
|
|
464
|
+
const uri = {
|
|
465
|
+
host: endpoint.host,
|
|
466
|
+
key: objectKey({
|
|
467
|
+
spaceId,
|
|
468
|
+
contentHash
|
|
469
|
+
})
|
|
470
|
+
};
|
|
471
|
+
await putObject({
|
|
472
|
+
uri,
|
|
473
|
+
data,
|
|
474
|
+
contentType,
|
|
475
|
+
contentHash,
|
|
476
|
+
credentials: endpoint.credentials
|
|
477
|
+
});
|
|
478
|
+
return { uri: formatUri(uri) };
|
|
479
|
+
},
|
|
480
|
+
get: async ({ spaceId, uri }) => {
|
|
481
|
+
const parsed = resolve(uri);
|
|
482
|
+
return getObject({
|
|
483
|
+
uri: parsed,
|
|
484
|
+
credentials: await resolveCredentials({
|
|
485
|
+
spaceId,
|
|
486
|
+
host: parsed.host
|
|
487
|
+
})
|
|
488
|
+
});
|
|
489
|
+
},
|
|
490
|
+
has: async ({ spaceId, uri }) => {
|
|
491
|
+
const parsed = resolve(uri);
|
|
492
|
+
return headObject({
|
|
493
|
+
uri: parsed,
|
|
494
|
+
credentials: await resolveCredentials({
|
|
495
|
+
spaceId,
|
|
496
|
+
host: parsed.host
|
|
497
|
+
})
|
|
498
|
+
});
|
|
499
|
+
},
|
|
500
|
+
getUrl: async ({ spaceId, uri }) => {
|
|
501
|
+
const parsed = resolve(uri);
|
|
502
|
+
return getObjectUrl({
|
|
503
|
+
uri: parsed,
|
|
504
|
+
credentials: await resolveCredentials({
|
|
505
|
+
spaceId,
|
|
506
|
+
host: parsed.host
|
|
507
|
+
})
|
|
508
|
+
});
|
|
509
|
+
}
|
|
510
|
+
};
|
|
511
|
+
};
|
|
512
|
+
//#endregion
|
|
513
|
+
export { DEFAULT_REGION, EMPTY_PAYLOAD_HASH, PRESIGN_EXPIRY_SECONDS, S3NetworkError, S3RequestError, S3TimeoutError, S3_BACKEND, S3_SCHEME, S3_TIMEOUT_MS, UNSIGNED_PAYLOAD, createS3BlobBackend, encodeObjectKey, formatTimestamps, formatUri, getObject, getObjectUrl, headObject, objectKey, parseUri, presignUrl, probeAccess, putObject, regionFromHost, sha256Hex, signRequest, toArrayBufferView, toHttpsUrl, uriEncode };
|
|
514
|
+
|
|
515
|
+
//# sourceMappingURL=s3.mjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"s3.mjs","names":[],"sources":["../../src/s3/constants.ts","../../src/s3/s3-uri.ts","../../src/s3/sigv4.ts","../../src/s3/s3-client.ts","../../src/s3/blob-backend.ts"],"sourcesContent":["//\n// Copyright 2026 DXOS.org\n//\n\n/**\n * Name this backend registers under on the ECHO Hypergraph, and the value `Blob.fromBytes`'s\n * `storage` option takes when it is selected.\n */\nexport const S3_BACKEND = 's3';\n\n/** URI scheme this backend resolves at read time. */\nexport const S3_SCHEME = 's3';\n\n/**\n * Signing region for endpoints that do not encode one. R2 ignores the region but SigV4 still\n * requires a value in the credential scope, and `auto` is what Cloudflare documents.\n */\nexport const DEFAULT_REGION = 'auto';\n\n/** Lifetime of a presigned GET URL. Long enough to render a large asset, short enough to not be a handout. */\nexport const PRESIGN_EXPIRY_SECONDS = 15 * 60;\n\n/** Abort a bucket request after this many ms so a hung call cannot wedge an upload or a render. */\nexport const S3_TIMEOUT_MS = 60_000;\n","//\n// Copyright 2026 DXOS.org\n//\n\nimport { isBlockedHost } from '@dxos/util';\n\nimport { DEFAULT_REGION, S3_SCHEME } from './constants.ts';\n\n/**\n * A stored blob's address: `s3://<host>/<key>`, where `host` is the virtual-hosted-style bucket\n * endpoint (`media.<account>.r2.cloudflarestorage.com`, `media.s3.eu-west-1.amazonaws.com`).\n *\n * The host carries the bucket, so it is also the `AccessToken.source` the credential is filed\n * under — one connection per bucket, resolved without a side table mapping URIs to configuration.\n */\nexport type S3Uri = {\n host: string;\n key: string;\n};\n\nexport const formatUri = ({ host, key }: S3Uri): string => `${S3_SCHEME}://${host}/${key}`;\n\n/** Returns `undefined` for anything that is not one of this backend's URIs. */\nexport const parseUri = (uri: string): S3Uri | undefined => {\n const match = /^s3:\\/\\/([^/]+)\\/(.+)$/.exec(uri);\n if (!match) {\n return undefined;\n }\n\n const [, host, key] = match;\n return { host, key };\n};\n\n/**\n * The HTTPS URL the object is served from. Public buckets resolve this without a signature.\n *\n * Rejects `.` and `..` segments rather than trying to carry them. WHATWG URL parsing resolves them\n * away, and percent-encoding does not help — it decodes `%2E` and normalizes anyway — so such a key\n * would silently be requested at a different path than the one it was stored under. Nothing this\n * package writes produces one (`objectKey` is a space id and a hex digest), so a key that reaches\n * here with a dot segment is a corrupted or hand-authored URI, and failing is better than reading\n * the wrong object.\n */\nexport const toHttpsUrl = ({ host, key }: S3Uri): URL => {\n const segments = key.split('/');\n if (segments.some((segment) => segment === '.' || segment === '..')) {\n throw new Error(`Refusing to address an S3 key with a relative path segment: ${key}`);\n }\n\n const url = new URL(`https://${host}/${segments.map((segment) => encodeURIComponent(segment)).join('/')}`);\n\n // Userinfo makes the authority lie: in `bucket.s3.amazonaws.com:443@169.254.169.254` everything\n // before the `@` is credentials, and the request goes to the address after it. Refuse it outright\n // rather than try to read past it — no legitimate bucket endpoint carries any.\n if (url.username !== '' || url.password !== '') {\n throw new Error(`Refusing to address an S3 endpoint carrying userinfo: ${host}`);\n }\n\n // Checked against the *parsed* hostname, which is what `fetch` will actually connect to. The host\n // comes from a stored `Blob` URI — replicated data, so on a headless host it is attacker-influenced\n // input to a server-side fetch. A browser is bounded by CORS; EDGE's function runtime is not, and\n // the unsigned read path needs no credential to reach an internal address.\n if (isBlockedHost(url.hostname)) {\n throw new Error(`Refusing to address an S3 endpoint on a private or loopback host: ${url.hostname}`);\n }\n\n return url;\n};\n\n/**\n * SigV4 signing region for an endpoint. AWS encodes it in the hostname; R2 and most self-hosted\n * S3 implementations do not, and take {@link DEFAULT_REGION}.\n *\n * The legacy global endpoint (`bucket.s3.amazonaws.com`, no region segment) is the exception: it\n * routes to us-east-1 and must be signed for that region, since signing it `auto` yields\n * `SignatureDoesNotMatch` rather than anything that names the real problem.\n */\nexport const regionFromHost = (host: string): string => {\n if (/(?:^|\\.)s3\\.amazonaws\\.com$/.test(host)) {\n return 'us-east-1';\n }\n\n const match = /(?:^|\\.)s3[.-]([a-z0-9-]+)\\.amazonaws\\.com$/.exec(host);\n return match ? match[1] : DEFAULT_REGION;\n};\n\n/**\n * Object key for a blob. Content-addressed by the digest the blob manager already computed, under a\n * space-scoped prefix so one bucket can serve many spaces and a listing stays navigable. The\n * original filename is deliberately not in the path — it is not unique, and ECHO holds it.\n */\nexport const objectKey = ({ spaceId, contentHash }: { spaceId: string; contentHash: string }): string =>\n `${spaceId}/${contentHash}`;\n","//\n// Copyright 2026 DXOS.org\n//\n\n/**\n * AWS Signature Version 4 for S3-compatible endpoints, over WebCrypto.\n *\n * Hand-rolled rather than taken from `@aws-sdk/*`: the SDK's signer pulls in a credential-provider\n * chain, a region resolver and a Node crypto shim, none of which apply to a browser holding one\n * static key pair — and it is two orders of magnitude larger than the ~150 lines the algorithm needs.\n */\n\nconst ALGORITHM = 'AWS4-HMAC-SHA256';\nconst SERVICE = 's3';\nconst TERMINATOR = 'aws4_request';\n\n/** Payload hash S3 accepts in place of a real digest when the body is not signed (presigned URLs). */\nexport const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';\n\n/** SHA-256 of the empty string; the payload hash for every request with no body. */\nexport const EMPTY_PAYLOAD_HASH = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';\n\nconst encoder = new TextEncoder();\n\nconst toHex = (bytes: Uint8Array): string =>\n Array.from(bytes)\n .map((byte) => byte.toString(16).padStart(2, '0'))\n .join('');\n\n/**\n * Narrows a view to one backed by a plain `ArrayBuffer`. `Uint8Array` is generic over\n * `ArrayBufferLike`, which includes `SharedArrayBuffer`; WebCrypto and `fetch` accept only the\n * former. The common case aliases the existing buffer, so this costs nothing but a wrapper.\n */\nexport const toArrayBufferView = (data: Uint8Array): Uint8Array<ArrayBuffer> =>\n data.buffer instanceof ArrayBuffer\n ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)\n : new Uint8Array(data);\n\nexport const sha256Hex = async (data: Uint8Array | string): Promise<string> => {\n const bytes = typeof data === 'string' ? encoder.encode(data) : toArrayBufferView(data);\n return toHex(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)));\n};\n\nconst hmac = async (key: Uint8Array<ArrayBuffer>, message: string): Promise<Uint8Array<ArrayBuffer>> => {\n const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);\n return new Uint8Array(await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(message)));\n};\n\n/**\n * RFC 3986 percent-encoding. `encodeURIComponent` leaves `!'()*` unescaped, which AWS treats as a\n * signature mismatch rather than an equivalent encoding.\n */\nexport const uriEncode = (value: string): string =>\n encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);\n\n/** Encodes an object key for the canonical URI: every segment escaped, the separating slashes kept. */\nexport const encodeObjectKey = (key: string): string => key.split('/').map(uriEncode).join('/');\n\n/** `20260826T143000Z` and `20260826` — the two timestamp forms SigV4 uses. */\nexport const formatTimestamps = (date: Date): { amzDate: string; dateStamp: string } => {\n const amzDate = date.toISOString().replace(/[:-]|\\.\\d{3}/g, '');\n return { amzDate, dateStamp: amzDate.slice(0, 8) };\n};\n\nconst canonicalQuery = (params: URLSearchParams): string =>\n [...params.entries()]\n .map(([key, value]) => [uriEncode(key), uriEncode(value)] as const)\n // Sort on the encoded forms: AWS orders by byte value after encoding, not before.\n .sort(([leftKey, leftValue], [rightKey, rightValue]) =>\n leftKey === rightKey ? (leftValue < rightValue ? -1 : 1) : leftKey < rightKey ? -1 : 1,\n )\n .map(([key, value]) => `${key}=${value}`)\n .join('&');\n\nconst canonicalHeaders = (headers: Record<string, string>) => {\n const normalized = Object.entries(headers)\n .map(([name, value]) => [name.toLowerCase(), value.trim().replace(/\\s+/g, ' ')] as const)\n .sort(([left], [right]) => (left < right ? -1 : 1));\n\n return {\n canonical: normalized.map(([name, value]) => `${name}:${value}\\n`).join(''),\n signed: normalized.map(([name]) => name).join(';'),\n };\n};\n\nexport type SigningCredentials = {\n accessKeyId: string;\n secretAccessKey: string;\n region: string;\n};\n\nconst signingKey = async (\n { secretAccessKey, region }: SigningCredentials,\n dateStamp: string,\n): Promise<Uint8Array<ArrayBuffer>> => {\n const dateKey = await hmac(encoder.encode(`AWS4${secretAccessKey}`), dateStamp);\n const regionKey = await hmac(dateKey, region);\n const serviceKey = await hmac(regionKey, SERVICE);\n return hmac(serviceKey, TERMINATOR);\n};\n\nconst sign = async (\n credentials: SigningCredentials,\n dateStamp: string,\n amzDate: string,\n canonicalRequest: string,\n): Promise<{ signature: string; scope: string }> => {\n const scope = `${dateStamp}/${credentials.region}/${SERVICE}/${TERMINATOR}`;\n const stringToSign = [ALGORITHM, amzDate, scope, await sha256Hex(canonicalRequest)].join('\\n');\n const signature = toHex(await hmac(await signingKey(credentials, dateStamp), stringToSign));\n return { signature, scope };\n};\n\nexport type SignRequestOptions = {\n method: string;\n url: URL;\n headers?: Record<string, string>;\n /** Hex SHA-256 of the body, or {@link UNSIGNED_PAYLOAD}. Defaults to the empty-body digest. */\n payloadHash?: string;\n credentials: SigningCredentials;\n date: Date;\n};\n\n/**\n * Signs a request with an `Authorization` header. Returns the headers to send — the caller's\n * `headers` plus `host`, `x-amz-date`, `x-amz-content-sha256` and `Authorization`.\n */\nexport const signRequest = async ({\n method,\n url,\n headers = {},\n payloadHash = EMPTY_PAYLOAD_HASH,\n credentials,\n date,\n}: SignRequestOptions): Promise<Record<string, string>> => {\n const { amzDate, dateStamp } = formatTimestamps(date);\n const signedHeaderSet: Record<string, string> = {\n ...headers,\n 'host': url.host,\n 'x-amz-date': amzDate,\n 'x-amz-content-sha256': payloadHash,\n };\n\n const { canonical, signed } = canonicalHeaders(signedHeaderSet);\n const canonicalRequest = [\n method,\n encodeObjectKey(decodeURIComponent(url.pathname)),\n canonicalQuery(url.searchParams),\n canonical,\n signed,\n payloadHash,\n ].join('\\n');\n\n const { signature, scope } = await sign(credentials, dateStamp, amzDate, canonicalRequest);\n return {\n ...signedHeaderSet,\n Authorization: `${ALGORITHM} Credential=${credentials.accessKeyId}/${scope}, SignedHeaders=${signed}, Signature=${signature}`,\n };\n};\n\nexport type PresignOptions = {\n method?: string;\n url: URL;\n expiresIn: number;\n credentials: SigningCredentials;\n date: Date;\n};\n\n/**\n * Produces a URL carrying its own authorization in the query string, so it can be handed to an\n * `<img>` or `<video>` element that cannot send an `Authorization` header.\n */\nexport const presignUrl = async ({\n method = 'GET',\n url,\n expiresIn,\n credentials,\n date,\n}: PresignOptions): Promise<string> => {\n const { amzDate, dateStamp } = formatTimestamps(date);\n const scope = `${dateStamp}/${credentials.region}/${SERVICE}/${TERMINATOR}`;\n\n const signedUrl = new URL(url.toString());\n signedUrl.searchParams.set('X-Amz-Algorithm', ALGORITHM);\n signedUrl.searchParams.set('X-Amz-Credential', `${credentials.accessKeyId}/${scope}`);\n signedUrl.searchParams.set('X-Amz-Date', amzDate);\n signedUrl.searchParams.set('X-Amz-Expires', String(expiresIn));\n signedUrl.searchParams.set('X-Amz-SignedHeaders', 'host');\n\n const canonicalRequest = [\n method,\n encodeObjectKey(decodeURIComponent(signedUrl.pathname)),\n canonicalQuery(signedUrl.searchParams),\n `host:${signedUrl.host}\\n`,\n 'host',\n UNSIGNED_PAYLOAD,\n ].join('\\n');\n\n const { signature } = await sign(credentials, dateStamp, amzDate, canonicalRequest);\n signedUrl.searchParams.set('X-Amz-Signature', signature);\n return signedUrl.toString();\n};\n","//\n// Copyright 2026 DXOS.org\n//\n\nimport { PRESIGN_EXPIRY_SECONDS, S3_TIMEOUT_MS } from './constants.ts';\nimport { type S3Uri, regionFromHost, toHttpsUrl } from './s3-uri.ts';\nimport { type SigningCredentials, presignUrl, signRequest, toArrayBufferView } from './sigv4.ts';\n\n/**\n * The key pair for one bucket. `undefined` wherever a caller has no credential for the endpoint —\n * every read path then falls through to an unsigned request, which succeeds on a public bucket and\n * 403s on a private one. That is the intended behavior: rendering a shared object must not require\n * the viewer to hold the writer's keys.\n */\nexport type S3Credentials = {\n accessKeyId: string;\n secretAccessKey: string;\n};\n\nconst toSigningCredentials = (credentials: S3Credentials, host: string): SigningCredentials => ({\n ...credentials,\n region: regionFromHost(host),\n});\n\n/** Rejects rather than resolving `undefined`: a transport failure is not a missing object. */\nexport class S3RequestError extends Error {\n constructor(\n readonly status: number,\n readonly statusText: string,\n readonly body: string,\n ) {\n super(`S3 request failed: ${status} ${statusText}${body ? ` — ${body}` : ''}`);\n this.name = 'S3RequestError';\n }\n}\n\n/** The page's own origin, which is what a bucket CORS policy has to name. */\nconst currentOrigin = (): string =>\n typeof globalThis.location?.origin === 'string' ? globalThis.location.origin : 'this origin';\n\n/**\n * A request the browser refused to send, or whose response it refused to expose. Almost always a\n * missing bucket CORS policy: `fetch` reports that as an opaque `TypeError` and confines the real\n * reason to the devtools console, so a blocked preflight would otherwise reach the user as\n * \"Failed to fetch\".\n *\n * The message names the origin and the methods only. The required headers are in the README and in\n * `details` — a status line has to be readable at a glance, and nobody writes a CORS policy from\n * memory of a sentence anyway.\n */\nexport class S3NetworkError extends Error {\n /** The full policy requirement, for logs and docs rather than the status line. */\n readonly details: string;\n\n constructor(\n readonly host: string,\n override readonly cause: unknown,\n ) {\n super(`Blocked by CORS: the bucket must allow ${currentOrigin()} for GET, HEAD and PUT.`);\n this.name = 'S3NetworkError';\n this.details =\n `${host} must allow origin ${currentOrigin()} for GET, HEAD and PUT, with the ` +\n 'authorization, content-type, x-amz-content-sha256 and x-amz-date headers.';\n }\n}\n\n/**\n * The request exceeded its deadline. Distinct from {@link S3NetworkError} because the remedies have\n * nothing in common — a timeout says the endpoint is slow or unreachable, not that a bucket policy\n * is wrong, and conflating them sends the user to edit configuration that is already correct.\n */\nexport class S3TimeoutError extends Error {\n constructor(\n readonly host: string,\n readonly timeoutMs: number,\n ) {\n super(`${host} did not respond within ${Math.round(timeoutMs / 1000)}s.`);\n this.name = 'S3TimeoutError';\n }\n}\n\n/** The S3 `<Code>` from an error body, which says far more than the HTTP status alone. */\nconst errorCode = (body: string): string | undefined => /<Code>([^<]+)<\\/Code>/.exec(body)?.[1];\n\n/**\n * Checks that the credential can address the bucket, and explains it when it cannot.\n *\n * Distinct from `headObject`, which deliberately reports 403 and 404 alike as \"not there\" — correct\n * when reading a blob, useless for a connection test, where telling a rejected key from an absent\n * object is the entire point. Probes a key that should not exist: 404 proves the signature was\n * accepted, and every other outcome names what to fix.\n */\nexport const probeAccess = async ({ uri, credentials }: { uri: S3Uri; credentials: S3Credentials }): Promise<void> => {\n const url = toHttpsUrl(uri);\n const headers = await signRequest({\n method: 'HEAD',\n url,\n credentials: toSigningCredentials(credentials, uri.host),\n date: new Date(),\n });\n\n // HEAD returns no body, so a failure is re-issued as GET purely to read the S3 error code.\n const { response, done } = await request(url, { method: 'HEAD', headers });\n done();\n if (response.ok || response.status === 404) {\n return;\n }\n\n const getHeaders = await signRequest({\n method: 'GET',\n url,\n credentials: toSigningCredentials(credentials, uri.host),\n date: new Date(),\n });\n const body = await request(url, { method: 'GET', headers: getHeaders })\n .then(async ({ response: errorResponse, done: doneReadingError, read }) => {\n try {\n return await read(() => errorResponse.text());\n } finally {\n doneReadingError();\n }\n })\n .catch(() => '');\n\n // Kept to one short clause each: this renders as a status line, and the endpoint and key id are\n // already on screen beside it as connection metadata, so repeating them here is noise.\n const bucket = uri.host.split('.')[0];\n switch (errorCode(body) ?? String(response.status)) {\n case 'InvalidAccessKeyId':\n throw new Error('Unknown access key ID.');\n case 'SignatureDoesNotMatch':\n throw new Error('Wrong secret access key.');\n case 'AccessDenied':\n throw new Error(`Key not permitted on \"${bucket}\".`);\n case 'NoSuchBucket':\n case 'InvalidBucketName':\n throw new Error(`No such bucket: \"${bucket}\".`);\n default:\n throw new S3RequestError(response.status, response.statusText, body);\n }\n};\n\ntype TimedRequest = {\n response: Response;\n /** Cancels the deadline; call once the body has been consumed. */\n done: () => void;\n /** Runs a body read under the same timeout classification as the header phase. */\n read: <T>(consume: () => Promise<T>) => Promise<T>;\n};\n\n/**\n * A timed request whose deadline covers the body as well as the headers.\n *\n * The signal stays attached to the response body after `fetch` resolves, so the timeout has to be\n * cancelled once the body is fully read — otherwise a large object that takes longer than\n * {@link S3_TIMEOUT_MS} to transfer is aborted mid-read, after the caller already has a `Response`\n * in hand. Callers signal completion by calling the returned `done`.\n */\nconst request = async (input: URL, init: RequestInit & { headers?: Record<string, string> }): Promise<TimedRequest> => {\n const controller = new AbortController();\n let timedOut = false;\n const timeout = setTimeout(() => {\n timedOut = true;\n controller.abort();\n }, S3_TIMEOUT_MS);\n try {\n const response = await fetch(input, { ...init, signal: controller.signal });\n return {\n response,\n done: () => clearTimeout(timeout),\n // Body reads happen after `fetch` resolves, so an abort during one lands outside this\n // try/catch and would surface as a native `AbortError`. Route them through here to get the\n // same classification the header phase gets.\n read: async <T>(consume: () => Promise<T>): Promise<T> => {\n try {\n return await consume();\n } catch (cause) {\n throw timedOut ? new S3TimeoutError(input.host, S3_TIMEOUT_MS) : cause;\n }\n },\n };\n } catch (cause) {\n clearTimeout(timeout);\n // A slow endpoint must not be reported as a CORS problem: `S3NetworkError` tells the user to fix\n // a bucket policy, which for a timeout is advice about something that is already correct.\n if (timedOut) {\n throw new S3TimeoutError(input.host, S3_TIMEOUT_MS);\n }\n throw new S3NetworkError(input.host, cause);\n }\n};\n\nexport type PutOptions = {\n uri: S3Uri;\n data: Uint8Array;\n contentType?: string;\n /** Hex SHA-256 of `data`, already computed by the blob manager. */\n contentHash: string;\n credentials: S3Credentials;\n now?: () => Date;\n};\n\nexport const putObject = async ({\n uri,\n data,\n contentType,\n contentHash,\n credentials,\n now = () => new Date(),\n}: PutOptions): Promise<void> => {\n const url = toHttpsUrl(uri);\n const headers = await signRequest({\n method: 'PUT',\n url,\n // `content-length` is deliberately absent: it is a forbidden header name, so the browser sets it\n // itself and strips ours — signing it would guarantee a mismatch the server reports as a bad\n // signature rather than a missing header.\n headers: contentType ? { 'content-type': contentType } : {},\n payloadHash: contentHash,\n credentials: toSigningCredentials(credentials, uri.host),\n date: now(),\n });\n\n const { response, done, read } = await request(url, { method: 'PUT', headers, body: toArrayBufferView(data) });\n try {\n if (!response.ok) {\n throw new S3RequestError(response.status, response.statusText, await read(() => response.text()).catch(() => ''));\n }\n } finally {\n done();\n }\n};\n\nexport type ReadOptions = {\n uri: S3Uri;\n /** Omitted for an unsigned read against a public bucket. */\n credentials?: S3Credentials;\n now?: () => Date;\n};\n\nconst readRequest = async (\n method: 'GET' | 'HEAD',\n { uri, credentials, now = () => new Date() }: ReadOptions,\n): Promise<TimedRequest> => {\n const url = toHttpsUrl(uri);\n const headers = credentials\n ? await signRequest({\n method,\n url,\n credentials: toSigningCredentials(credentials, uri.host),\n date: now(),\n })\n : undefined;\n\n return request(url, { method, headers });\n};\n\n/**\n * Whether a failed read should be reported as \"not there\" rather than raised.\n *\n * A signed read is authoritative, so only 404 and 403 are misses and anything else is a fault worth\n * surfacing. An unsigned read is speculative — it is a guess that the bucket is public — so any\n * client error just means \"not publicly readable\". The distinction is load-bearing: R2 answers an\n * unauthenticated request to a private bucket with `400 InvalidArgument`, not the 403 that AWS\n * returns, so a 404/403-only rule turns the public-bucket fallback into a thrown error.\n */\nconst isMiss = (status: number, signed: boolean): boolean =>\n signed ? status === 404 || status === 403 : status >= 400 && status < 500;\n\n/**\n * Reads an object's bytes.\n *\n * Resolves `undefined` when the object is absent, or is not readable with the credentials in hand —\n * see {@link isMiss} for which statuses count. Rejects on a transport failure or an unexpected\n * status, since neither is evidence the object is missing.\n */\nexport const getObject = async (options: ReadOptions): Promise<Uint8Array | undefined> => {\n const { response, done, read } = await readRequest('GET', options);\n try {\n if (!response.ok) {\n if (isMiss(response.status, !!options.credentials)) {\n return undefined;\n }\n throw new S3RequestError(response.status, response.statusText, await read(() => response.text()).catch(() => ''));\n }\n\n return new Uint8Array(await read(() => response.arrayBuffer()));\n } finally {\n done();\n }\n};\n\n/**\n * Whether an object exists and is readable with the credentials in hand. Same miss semantics as\n * {@link getObject}, and the same rejection on anything that is not evidence of absence.\n */\nexport const headObject = async (options: ReadOptions): Promise<boolean> => {\n const { response, done, read } = await readRequest('HEAD', options);\n if (!response.ok) {\n try {\n if (isMiss(response.status, !!options.credentials)) {\n return false;\n }\n throw new S3RequestError(response.status, response.statusText, await read(() => response.text()).catch(() => ''));\n } finally {\n done();\n }\n }\n done();\n\n return true;\n};\n\n/**\n * A URL an `<img>`/`<video>` can load directly. Presigned when a credential is available; the plain\n * public URL otherwise, which is correct for a public bucket and simply fails to load for a private\n * one — the same outcome as returning nothing, without suppressing the browser's own diagnostics.\n */\nexport const getObjectUrl = async ({ uri, credentials, now = () => new Date() }: ReadOptions): Promise<string> => {\n const url = toHttpsUrl(uri);\n if (!credentials) {\n return url.toString();\n }\n\n return presignUrl({\n url,\n expiresIn: PRESIGN_EXPIRY_SECONDS,\n credentials: toSigningCredentials(credentials, uri.host),\n date: now(),\n });\n};\n","//\n// Copyright 2026 DXOS.org\n//\n\nimport { invariant } from '@dxos/invariant';\nimport { type SpaceId } from '@dxos/keys';\n\nimport { type BlobBackend } from '../backend.ts';\nimport { S3_SCHEME } from './constants.ts';\nimport { type S3Credentials, getObject, getObjectUrl, headObject, putObject } from './s3-client.ts';\nimport { formatUri, objectKey, parseUri } from './s3-uri.ts';\n\n/**\n * How the host answers the two questions this backend cannot answer itself.\n *\n * Both are supplied rather than derived because they need a space's database, and the hosts that\n * should be able to reach a bucket disagree about how to get one: the browser has a `Client`, while\n * EDGE's `operation-service` has only `Database.Service`. Keeping both out of this package is what\n * makes the backend registrable anywhere.\n */\nexport type S3Host = {\n /** The key pair for a bucket endpoint, or `undefined` to attempt an unsigned (public) read. */\n resolveCredentials: (request: { spaceId: SpaceId; host: string }) => Promise<S3Credentials | undefined>;\n /**\n * The bucket a space writes to. Reads take their endpoint from the URI, so this exists only for\n * `put` — `BlobPutRequest` carries no endpoint of its own.\n */\n resolveWriteEndpoint: (spaceId: SpaceId) => Promise<{ host: string; credentials: S3Credentials } | undefined>;\n};\n\n/**\n * Blob backend storing bytes in an S3-compatible bucket, addressed by `s3://<host>/<key>` URIs.\n *\n * Reads are attempted unsigned when the space holds no credential for the endpoint, so a public\n * bucket renders for a viewer who was never given the writer's keys. Writes always require one.\n *\n * The bucket must allow the app's origin in its CORS policy for `PUT` and for any programmatic\n * read; rendering does not need it, since a presigned URL in an `<img>` is not CORS-gated. In a\n * headless host CORS does not apply at all.\n */\nexport const createS3BlobBackend = ({ resolveCredentials, resolveWriteEndpoint }: S3Host): BlobBackend => {\n const resolve = (uri: string) => {\n const parsed = parseUri(uri);\n invariant(parsed, `not an s3 uri: ${uri}`);\n return parsed;\n };\n\n return {\n schemes: [S3_SCHEME],\n\n put: async ({ spaceId, data, contentType, contentHash }) => {\n const endpoint = await resolveWriteEndpoint(spaceId);\n invariant(endpoint, 'no S3 connection in this space; connect a bucket before uploading');\n\n const uri = { host: endpoint.host, key: objectKey({ spaceId, contentHash }) };\n await putObject({ uri, data, contentType, contentHash, credentials: endpoint.credentials });\n return { uri: formatUri(uri) };\n },\n\n get: async ({ spaceId, uri }) => {\n const parsed = resolve(uri);\n return getObject({ uri: parsed, credentials: await resolveCredentials({ spaceId, host: parsed.host }) });\n },\n\n has: async ({ spaceId, uri }) => {\n const parsed = resolve(uri);\n return headObject({ uri: parsed, credentials: await resolveCredentials({ spaceId, host: parsed.host }) });\n },\n\n getUrl: async ({ spaceId, uri }) => {\n const parsed = resolve(uri);\n return getObjectUrl({ uri: parsed, credentials: await resolveCredentials({ spaceId, host: parsed.host }) });\n },\n };\n};\n"],"mappings":"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"}
|
|
@@ -33,6 +33,18 @@ export interface BlobTransport {
|
|
|
33
33
|
/** `undefined` means the key was not found. */
|
|
34
34
|
get(key: string): Promise<Uint8Array | undefined>;
|
|
35
35
|
has(key: string): Promise<boolean>;
|
|
36
|
+
/**
|
|
37
|
+
* Admits bytes already staged by a direct upload, returning the key they landed under.
|
|
38
|
+
*
|
|
39
|
+
* Optional because it is meaningful only for a hosted store: the bytes are moved server-side and
|
|
40
|
+
* never reach this process, which is the entire reason the path exists — the uploader was an
|
|
41
|
+
* agent's shell, and routing the file back through the client to hash it would undo the saving.
|
|
42
|
+
*/
|
|
43
|
+
finalizeUpload?(uploadId: string): Promise<{
|
|
44
|
+
key: string;
|
|
45
|
+
size: number;
|
|
46
|
+
contentType?: string;
|
|
47
|
+
}>;
|
|
36
48
|
}
|
|
37
49
|
/**
|
|
38
50
|
* Implemented by pluggable blob storage backends and registered on the Hypergraph via
|
|
@@ -62,5 +74,24 @@ export interface BlobBackend {
|
|
|
62
74
|
uri: string;
|
|
63
75
|
contentType?: string;
|
|
64
76
|
}): Promise<string | undefined>;
|
|
77
|
+
/**
|
|
78
|
+
* Turns a completed direct upload into a stored blob, returning its URI and what the store
|
|
79
|
+
* actually received.
|
|
80
|
+
*
|
|
81
|
+
* The size and content type come back from the store rather than from the caller because the
|
|
82
|
+
* caller never saw the bytes: a direct upload is written by a third party (an agent's `curl`), so
|
|
83
|
+
* the only honest source for what landed is whatever received it.
|
|
84
|
+
*
|
|
85
|
+
* Implemented only by backends with a direct-upload path; `undefined` on the others, which is how
|
|
86
|
+
* the manager tells "this backend cannot adopt uploads" from "the upload failed".
|
|
87
|
+
*/
|
|
88
|
+
adoptUpload?(request: {
|
|
89
|
+
spaceId: SpaceId;
|
|
90
|
+
uploadId: string;
|
|
91
|
+
}): Promise<{
|
|
92
|
+
uri: string;
|
|
93
|
+
size: number;
|
|
94
|
+
contentType?: string;
|
|
95
|
+
}>;
|
|
65
96
|
}
|
|
66
97
|
//# sourceMappingURL=backend.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/backend.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uGAAuG;IACvG,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtF,+CAA+C;IAC/C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAClD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;
|
|
1
|
+
{"version":3,"file":"backend.d.ts","sourceRoot":"","sources":["../../../src/backend.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,EAAE,UAAU,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uGAAuG;IACvG,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAa;IAC5B,+FAA+F;IAC/F,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,GAAG,CAAC;IACtB,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtF,+CAA+C;IAC/C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAClD,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACnC;;;;;;OAMG;IACH,cAAc,CAAC,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CACjG;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW;IAC1B,sDAAsD;IACtD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC,CAAC;IACvD,4FAA4F;IAC5F,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IACjF,GAAG,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAClE,MAAM,CAAC,CAAC,OAAO,EAAE;QAAE,OAAO,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IACvG;;;;;;;;;;OAUG;IACH,WAAW,CAAC,CAAC,OAAO,EAAE;QACpB,OAAO,EAAE,OAAO,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;KAClB,GAAG,OAAO,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAClE"}
|