@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.
- 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
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
import { describe, test } from 'vitest';
|
|
6
|
+
|
|
7
|
+
import { encodeObjectKey, formatTimestamps, presignUrl, sha256Hex, signRequest, uriEncode } from './sigv4.ts';
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* Credentials and timestamp from the published AWS SigV4 examples. The expected signatures below are
|
|
11
|
+
* AWS's own — they are what makes these tests evidence that the implementation is correct, rather
|
|
12
|
+
* than merely self-consistent.
|
|
13
|
+
*/
|
|
14
|
+
const CREDENTIALS = {
|
|
15
|
+
accessKeyId: 'AKIAIOSFODNN7EXAMPLE',
|
|
16
|
+
secretAccessKey: 'wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
|
|
17
|
+
region: 'us-east-1',
|
|
18
|
+
};
|
|
19
|
+
|
|
20
|
+
const DATE = new Date('2013-05-24T00:00:00Z');
|
|
21
|
+
|
|
22
|
+
describe('sigv4', () => {
|
|
23
|
+
test('formats both timestamp forms', ({ expect }) => {
|
|
24
|
+
expect(formatTimestamps(DATE)).toEqual({ amzDate: '20130524T000000Z', dateStamp: '20130524' });
|
|
25
|
+
});
|
|
26
|
+
|
|
27
|
+
test('hashes the empty payload to the documented digest', async ({ expect }) => {
|
|
28
|
+
expect(await sha256Hex('')).toBe('e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855');
|
|
29
|
+
});
|
|
30
|
+
|
|
31
|
+
test('escapes the characters encodeURIComponent leaves alone', ({ expect }) => {
|
|
32
|
+
expect(uriEncode("a!b'c(d)e*f")).toBe('a%21b%27c%28d%29e%2Af');
|
|
33
|
+
expect(uriEncode('a b/c')).toBe('a%20b%2Fc');
|
|
34
|
+
});
|
|
35
|
+
|
|
36
|
+
test('keeps path separators while escaping each segment', ({ expect }) => {
|
|
37
|
+
expect(encodeObjectKey('space id/a b.png')).toBe('space%20id/a%20b.png');
|
|
38
|
+
});
|
|
39
|
+
|
|
40
|
+
// https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-header-based-auth.html — GET Object.
|
|
41
|
+
test('matches the AWS GET Object header-auth vector', async ({ expect }) => {
|
|
42
|
+
const headers = await signRequest({
|
|
43
|
+
method: 'GET',
|
|
44
|
+
url: new URL('https://examplebucket.s3.amazonaws.com/test.txt'),
|
|
45
|
+
headers: { range: 'bytes=0-9' },
|
|
46
|
+
credentials: CREDENTIALS,
|
|
47
|
+
date: DATE,
|
|
48
|
+
});
|
|
49
|
+
|
|
50
|
+
expect(headers.Authorization).toBe(
|
|
51
|
+
'AWS4-HMAC-SHA256 Credential=AKIAIOSFODNN7EXAMPLE/20130524/us-east-1/s3/aws4_request, ' +
|
|
52
|
+
'SignedHeaders=host;range;x-amz-content-sha256;x-amz-date, ' +
|
|
53
|
+
'Signature=f0e8bdb87c964420e857bd35b5d6ed310bd44f0170aba48dd91039c6036bdb41',
|
|
54
|
+
);
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
// https://docs.aws.amazon.com/AmazonS3/latest/API/sigv4-query-string-auth.html
|
|
58
|
+
test('matches the AWS presigned-URL vector', async ({ expect }) => {
|
|
59
|
+
const url = await presignUrl({
|
|
60
|
+
url: new URL('https://examplebucket.s3.amazonaws.com/test.txt'),
|
|
61
|
+
expiresIn: 86400,
|
|
62
|
+
credentials: CREDENTIALS,
|
|
63
|
+
date: DATE,
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
expect(new URL(url).searchParams.get('X-Amz-Signature')).toBe(
|
|
67
|
+
'aeeed9bbccd4d02ee5c0109b86d86835f995330da4c265957d157751f604d404',
|
|
68
|
+
);
|
|
69
|
+
});
|
|
70
|
+
|
|
71
|
+
test('presigned url carries every parameter the verifier needs', async ({ expect }) => {
|
|
72
|
+
const url = new URL(
|
|
73
|
+
await presignUrl({
|
|
74
|
+
url: new URL('https://media.abc.r2.cloudflarestorage.com/space/hash'),
|
|
75
|
+
expiresIn: 900,
|
|
76
|
+
credentials: { ...CREDENTIALS, region: 'auto' },
|
|
77
|
+
date: DATE,
|
|
78
|
+
}),
|
|
79
|
+
);
|
|
80
|
+
|
|
81
|
+
expect(url.searchParams.get('X-Amz-Algorithm')).toBe('AWS4-HMAC-SHA256');
|
|
82
|
+
expect(url.searchParams.get('X-Amz-Credential')).toBe('AKIAIOSFODNN7EXAMPLE/20130524/auto/s3/aws4_request');
|
|
83
|
+
expect(url.searchParams.get('X-Amz-Expires')).toBe('900');
|
|
84
|
+
expect(url.searchParams.get('X-Amz-SignedHeaders')).toBe('host');
|
|
85
|
+
expect(url.searchParams.get('X-Amz-Signature')).toMatch(/^[0-9a-f]{64}$/);
|
|
86
|
+
});
|
|
87
|
+
|
|
88
|
+
test('a different key produces a different signature', async ({ expect }) => {
|
|
89
|
+
const sign = (secretAccessKey: string) =>
|
|
90
|
+
signRequest({
|
|
91
|
+
method: 'GET',
|
|
92
|
+
url: new URL('https://examplebucket.s3.amazonaws.com/test.txt'),
|
|
93
|
+
credentials: { ...CREDENTIALS, secretAccessKey },
|
|
94
|
+
date: DATE,
|
|
95
|
+
});
|
|
96
|
+
|
|
97
|
+
expect((await sign('one')).Authorization).not.toBe((await sign('two')).Authorization);
|
|
98
|
+
});
|
|
99
|
+
});
|
package/src/s3/sigv4.ts
ADDED
|
@@ -0,0 +1,203 @@
|
|
|
1
|
+
//
|
|
2
|
+
// Copyright 2026 DXOS.org
|
|
3
|
+
//
|
|
4
|
+
|
|
5
|
+
/**
|
|
6
|
+
* AWS Signature Version 4 for S3-compatible endpoints, over WebCrypto.
|
|
7
|
+
*
|
|
8
|
+
* Hand-rolled rather than taken from `@aws-sdk/*`: the SDK's signer pulls in a credential-provider
|
|
9
|
+
* chain, a region resolver and a Node crypto shim, none of which apply to a browser holding one
|
|
10
|
+
* static key pair — and it is two orders of magnitude larger than the ~150 lines the algorithm needs.
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
const ALGORITHM = 'AWS4-HMAC-SHA256';
|
|
14
|
+
const SERVICE = 's3';
|
|
15
|
+
const TERMINATOR = 'aws4_request';
|
|
16
|
+
|
|
17
|
+
/** Payload hash S3 accepts in place of a real digest when the body is not signed (presigned URLs). */
|
|
18
|
+
export const UNSIGNED_PAYLOAD = 'UNSIGNED-PAYLOAD';
|
|
19
|
+
|
|
20
|
+
/** SHA-256 of the empty string; the payload hash for every request with no body. */
|
|
21
|
+
export const EMPTY_PAYLOAD_HASH = 'e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855';
|
|
22
|
+
|
|
23
|
+
const encoder = new TextEncoder();
|
|
24
|
+
|
|
25
|
+
const toHex = (bytes: Uint8Array): string =>
|
|
26
|
+
Array.from(bytes)
|
|
27
|
+
.map((byte) => byte.toString(16).padStart(2, '0'))
|
|
28
|
+
.join('');
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* Narrows a view to one backed by a plain `ArrayBuffer`. `Uint8Array` is generic over
|
|
32
|
+
* `ArrayBufferLike`, which includes `SharedArrayBuffer`; WebCrypto and `fetch` accept only the
|
|
33
|
+
* former. The common case aliases the existing buffer, so this costs nothing but a wrapper.
|
|
34
|
+
*/
|
|
35
|
+
export const toArrayBufferView = (data: Uint8Array): Uint8Array<ArrayBuffer> =>
|
|
36
|
+
data.buffer instanceof ArrayBuffer
|
|
37
|
+
? new Uint8Array(data.buffer, data.byteOffset, data.byteLength)
|
|
38
|
+
: new Uint8Array(data);
|
|
39
|
+
|
|
40
|
+
export const sha256Hex = async (data: Uint8Array | string): Promise<string> => {
|
|
41
|
+
const bytes = typeof data === 'string' ? encoder.encode(data) : toArrayBufferView(data);
|
|
42
|
+
return toHex(new Uint8Array(await crypto.subtle.digest('SHA-256', bytes)));
|
|
43
|
+
};
|
|
44
|
+
|
|
45
|
+
const hmac = async (key: Uint8Array<ArrayBuffer>, message: string): Promise<Uint8Array<ArrayBuffer>> => {
|
|
46
|
+
const cryptoKey = await crypto.subtle.importKey('raw', key, { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
|
|
47
|
+
return new Uint8Array(await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(message)));
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* RFC 3986 percent-encoding. `encodeURIComponent` leaves `!'()*` unescaped, which AWS treats as a
|
|
52
|
+
* signature mismatch rather than an equivalent encoding.
|
|
53
|
+
*/
|
|
54
|
+
export const uriEncode = (value: string): string =>
|
|
55
|
+
encodeURIComponent(value).replace(/[!'()*]/g, (char) => `%${char.charCodeAt(0).toString(16).toUpperCase()}`);
|
|
56
|
+
|
|
57
|
+
/** Encodes an object key for the canonical URI: every segment escaped, the separating slashes kept. */
|
|
58
|
+
export const encodeObjectKey = (key: string): string => key.split('/').map(uriEncode).join('/');
|
|
59
|
+
|
|
60
|
+
/** `20260826T143000Z` and `20260826` — the two timestamp forms SigV4 uses. */
|
|
61
|
+
export const formatTimestamps = (date: Date): { amzDate: string; dateStamp: string } => {
|
|
62
|
+
const amzDate = date.toISOString().replace(/[:-]|\.\d{3}/g, '');
|
|
63
|
+
return { amzDate, dateStamp: amzDate.slice(0, 8) };
|
|
64
|
+
};
|
|
65
|
+
|
|
66
|
+
const canonicalQuery = (params: URLSearchParams): string =>
|
|
67
|
+
[...params.entries()]
|
|
68
|
+
.map(([key, value]) => [uriEncode(key), uriEncode(value)] as const)
|
|
69
|
+
// Sort on the encoded forms: AWS orders by byte value after encoding, not before.
|
|
70
|
+
.sort(([leftKey, leftValue], [rightKey, rightValue]) =>
|
|
71
|
+
leftKey === rightKey ? (leftValue < rightValue ? -1 : 1) : leftKey < rightKey ? -1 : 1,
|
|
72
|
+
)
|
|
73
|
+
.map(([key, value]) => `${key}=${value}`)
|
|
74
|
+
.join('&');
|
|
75
|
+
|
|
76
|
+
const canonicalHeaders = (headers: Record<string, string>) => {
|
|
77
|
+
const normalized = Object.entries(headers)
|
|
78
|
+
.map(([name, value]) => [name.toLowerCase(), value.trim().replace(/\s+/g, ' ')] as const)
|
|
79
|
+
.sort(([left], [right]) => (left < right ? -1 : 1));
|
|
80
|
+
|
|
81
|
+
return {
|
|
82
|
+
canonical: normalized.map(([name, value]) => `${name}:${value}\n`).join(''),
|
|
83
|
+
signed: normalized.map(([name]) => name).join(';'),
|
|
84
|
+
};
|
|
85
|
+
};
|
|
86
|
+
|
|
87
|
+
export type SigningCredentials = {
|
|
88
|
+
accessKeyId: string;
|
|
89
|
+
secretAccessKey: string;
|
|
90
|
+
region: string;
|
|
91
|
+
};
|
|
92
|
+
|
|
93
|
+
const signingKey = async (
|
|
94
|
+
{ secretAccessKey, region }: SigningCredentials,
|
|
95
|
+
dateStamp: string,
|
|
96
|
+
): Promise<Uint8Array<ArrayBuffer>> => {
|
|
97
|
+
const dateKey = await hmac(encoder.encode(`AWS4${secretAccessKey}`), dateStamp);
|
|
98
|
+
const regionKey = await hmac(dateKey, region);
|
|
99
|
+
const serviceKey = await hmac(regionKey, SERVICE);
|
|
100
|
+
return hmac(serviceKey, TERMINATOR);
|
|
101
|
+
};
|
|
102
|
+
|
|
103
|
+
const sign = async (
|
|
104
|
+
credentials: SigningCredentials,
|
|
105
|
+
dateStamp: string,
|
|
106
|
+
amzDate: string,
|
|
107
|
+
canonicalRequest: string,
|
|
108
|
+
): Promise<{ signature: string; scope: string }> => {
|
|
109
|
+
const scope = `${dateStamp}/${credentials.region}/${SERVICE}/${TERMINATOR}`;
|
|
110
|
+
const stringToSign = [ALGORITHM, amzDate, scope, await sha256Hex(canonicalRequest)].join('\n');
|
|
111
|
+
const signature = toHex(await hmac(await signingKey(credentials, dateStamp), stringToSign));
|
|
112
|
+
return { signature, scope };
|
|
113
|
+
};
|
|
114
|
+
|
|
115
|
+
export type SignRequestOptions = {
|
|
116
|
+
method: string;
|
|
117
|
+
url: URL;
|
|
118
|
+
headers?: Record<string, string>;
|
|
119
|
+
/** Hex SHA-256 of the body, or {@link UNSIGNED_PAYLOAD}. Defaults to the empty-body digest. */
|
|
120
|
+
payloadHash?: string;
|
|
121
|
+
credentials: SigningCredentials;
|
|
122
|
+
date: Date;
|
|
123
|
+
};
|
|
124
|
+
|
|
125
|
+
/**
|
|
126
|
+
* Signs a request with an `Authorization` header. Returns the headers to send — the caller's
|
|
127
|
+
* `headers` plus `host`, `x-amz-date`, `x-amz-content-sha256` and `Authorization`.
|
|
128
|
+
*/
|
|
129
|
+
export const signRequest = async ({
|
|
130
|
+
method,
|
|
131
|
+
url,
|
|
132
|
+
headers = {},
|
|
133
|
+
payloadHash = EMPTY_PAYLOAD_HASH,
|
|
134
|
+
credentials,
|
|
135
|
+
date,
|
|
136
|
+
}: SignRequestOptions): Promise<Record<string, string>> => {
|
|
137
|
+
const { amzDate, dateStamp } = formatTimestamps(date);
|
|
138
|
+
const signedHeaderSet: Record<string, string> = {
|
|
139
|
+
...headers,
|
|
140
|
+
'host': url.host,
|
|
141
|
+
'x-amz-date': amzDate,
|
|
142
|
+
'x-amz-content-sha256': payloadHash,
|
|
143
|
+
};
|
|
144
|
+
|
|
145
|
+
const { canonical, signed } = canonicalHeaders(signedHeaderSet);
|
|
146
|
+
const canonicalRequest = [
|
|
147
|
+
method,
|
|
148
|
+
encodeObjectKey(decodeURIComponent(url.pathname)),
|
|
149
|
+
canonicalQuery(url.searchParams),
|
|
150
|
+
canonical,
|
|
151
|
+
signed,
|
|
152
|
+
payloadHash,
|
|
153
|
+
].join('\n');
|
|
154
|
+
|
|
155
|
+
const { signature, scope } = await sign(credentials, dateStamp, amzDate, canonicalRequest);
|
|
156
|
+
return {
|
|
157
|
+
...signedHeaderSet,
|
|
158
|
+
Authorization: `${ALGORITHM} Credential=${credentials.accessKeyId}/${scope}, SignedHeaders=${signed}, Signature=${signature}`,
|
|
159
|
+
};
|
|
160
|
+
};
|
|
161
|
+
|
|
162
|
+
export type PresignOptions = {
|
|
163
|
+
method?: string;
|
|
164
|
+
url: URL;
|
|
165
|
+
expiresIn: number;
|
|
166
|
+
credentials: SigningCredentials;
|
|
167
|
+
date: Date;
|
|
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
|
+
export const presignUrl = async ({
|
|
175
|
+
method = 'GET',
|
|
176
|
+
url,
|
|
177
|
+
expiresIn,
|
|
178
|
+
credentials,
|
|
179
|
+
date,
|
|
180
|
+
}: PresignOptions): Promise<string> => {
|
|
181
|
+
const { amzDate, dateStamp } = formatTimestamps(date);
|
|
182
|
+
const scope = `${dateStamp}/${credentials.region}/${SERVICE}/${TERMINATOR}`;
|
|
183
|
+
|
|
184
|
+
const signedUrl = new URL(url.toString());
|
|
185
|
+
signedUrl.searchParams.set('X-Amz-Algorithm', ALGORITHM);
|
|
186
|
+
signedUrl.searchParams.set('X-Amz-Credential', `${credentials.accessKeyId}/${scope}`);
|
|
187
|
+
signedUrl.searchParams.set('X-Amz-Date', amzDate);
|
|
188
|
+
signedUrl.searchParams.set('X-Amz-Expires', String(expiresIn));
|
|
189
|
+
signedUrl.searchParams.set('X-Amz-SignedHeaders', 'host');
|
|
190
|
+
|
|
191
|
+
const canonicalRequest = [
|
|
192
|
+
method,
|
|
193
|
+
encodeObjectKey(decodeURIComponent(signedUrl.pathname)),
|
|
194
|
+
canonicalQuery(signedUrl.searchParams),
|
|
195
|
+
`host:${signedUrl.host}\n`,
|
|
196
|
+
'host',
|
|
197
|
+
UNSIGNED_PAYLOAD,
|
|
198
|
+
].join('\n');
|
|
199
|
+
|
|
200
|
+
const { signature } = await sign(credentials, dateStamp, amzDate, canonicalRequest);
|
|
201
|
+
signedUrl.searchParams.set('X-Amz-Signature', signature);
|
|
202
|
+
return signedUrl.toString();
|
|
203
|
+
};
|