@starkeep/storage-s3 0.1.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/LICENSE +21 -0
- package/README.md +61 -0
- package/dist/index.cjs +199 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +43 -0
- package/dist/index.d.ts +43 -0
- package/dist/index.js +180 -0
- package/dist/index.js.map +1 -0
- package/package.json +47 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Aaron Koller, Pedro Pinto, Craig Schroeder
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
# @starkeep/storage-s3
|
|
2
|
+
|
|
3
|
+
Amazon S3 implementation of `ObjectStorageAdapter`. Supports multipart uploads for large objects and pre-signed URL generation.
|
|
4
|
+
|
|
5
|
+
## Installation
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pnpm add @starkeep/storage-s3
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Usage
|
|
12
|
+
|
|
13
|
+
```typescript
|
|
14
|
+
import { S3ObjectStorageAdapter } from "@starkeep/storage-s3";
|
|
15
|
+
|
|
16
|
+
const objectStorage = new S3ObjectStorageAdapter({
|
|
17
|
+
bucketName: "my-starkeep-bucket",
|
|
18
|
+
region: "us-east-1",
|
|
19
|
+
keyPrefix: "user-123/", // optional prefix for all keys
|
|
20
|
+
credentials: { // optional, falls back to default AWS credential chain
|
|
21
|
+
accessKeyId: "AKIA...",
|
|
22
|
+
secretAccessKey: "...",
|
|
23
|
+
},
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
await objectStorage.init();
|
|
27
|
+
|
|
28
|
+
// Store an object (automatically uses multipart upload for files > 5 MB)
|
|
29
|
+
await objectStorage.put("photos/sunset.jpg", imageBuffer, {
|
|
30
|
+
contentType: "image/jpeg",
|
|
31
|
+
metadata: { uploadedBy: "user-123" },
|
|
32
|
+
});
|
|
33
|
+
|
|
34
|
+
// Retrieve an object
|
|
35
|
+
const result = await objectStorage.get("photos/sunset.jpg");
|
|
36
|
+
|
|
37
|
+
// Generate a pre-signed URL (default expiry: 1 hour)
|
|
38
|
+
const signedUrl = await objectStorage.getSignedUrl("photos/sunset.jpg", {
|
|
39
|
+
expiresIn: 3600,
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
// List objects by prefix with pagination
|
|
43
|
+
const listing = await objectStorage.list("photos/", { limit: 100 });
|
|
44
|
+
|
|
45
|
+
await objectStorage.close();
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## API
|
|
49
|
+
|
|
50
|
+
| Export | Description |
|
|
51
|
+
|---|---|
|
|
52
|
+
| `S3ObjectStorageAdapter` | Class implementing `ObjectStorageAdapter` for Amazon S3 |
|
|
53
|
+
| `S3ObjectStorageAdapterOptions` | Options: `bucketName`, `region`, optional `keyPrefix` and `credentials` |
|
|
54
|
+
|
|
55
|
+
The S3 client is created lazily on first use. Files larger than 5 MB are uploaded via the AWS SDK multipart `Upload` utility automatically.
|
|
56
|
+
|
|
57
|
+
## Testing
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
pnpm --filter @starkeep/storage-s3 test
|
|
61
|
+
```
|
package/dist/index.cjs
ADDED
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __defProp = Object.defineProperty;
|
|
3
|
+
var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
|
|
4
|
+
var __getOwnPropNames = Object.getOwnPropertyNames;
|
|
5
|
+
var __hasOwnProp = Object.prototype.hasOwnProperty;
|
|
6
|
+
var __export = (target, all) => {
|
|
7
|
+
for (var name in all)
|
|
8
|
+
__defProp(target, name, { get: all[name], enumerable: true });
|
|
9
|
+
};
|
|
10
|
+
var __copyProps = (to, from, except, desc) => {
|
|
11
|
+
if (from && typeof from === "object" || typeof from === "function") {
|
|
12
|
+
for (let key of __getOwnPropNames(from))
|
|
13
|
+
if (!__hasOwnProp.call(to, key) && key !== except)
|
|
14
|
+
__defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
|
|
15
|
+
}
|
|
16
|
+
return to;
|
|
17
|
+
};
|
|
18
|
+
var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
|
|
19
|
+
|
|
20
|
+
// src/index.ts
|
|
21
|
+
var index_exports = {};
|
|
22
|
+
__export(index_exports, {
|
|
23
|
+
S3ObjectStorageAdapter: () => S3ObjectStorageAdapter
|
|
24
|
+
});
|
|
25
|
+
module.exports = __toCommonJS(index_exports);
|
|
26
|
+
|
|
27
|
+
// src/adapter.ts
|
|
28
|
+
var import_client_s3 = require("@aws-sdk/client-s3");
|
|
29
|
+
var import_s3_request_presigner = require("@aws-sdk/s3-request-presigner");
|
|
30
|
+
var import_lib_storage = require("@aws-sdk/lib-storage");
|
|
31
|
+
var MULTIPART_THRESHOLD_BYTES = 5 * 1024 * 1024;
|
|
32
|
+
var S3ObjectStorageAdapter = class {
|
|
33
|
+
options;
|
|
34
|
+
client = null;
|
|
35
|
+
constructor(options) {
|
|
36
|
+
this.options = options;
|
|
37
|
+
}
|
|
38
|
+
getClient() {
|
|
39
|
+
if (!this.client) {
|
|
40
|
+
this.client = new import_client_s3.S3Client({
|
|
41
|
+
region: this.options.region,
|
|
42
|
+
// When credentialProvider is set, pass it directly to the AWS SDK.
|
|
43
|
+
// The SDK calls it before each signed request, so STS credentials
|
|
44
|
+
// (e.g. from a Cognito Identity Pool) are always fresh.
|
|
45
|
+
credentials: this.options.credentialProvider ? this.options.credentialProvider : this.options.credentials
|
|
46
|
+
});
|
|
47
|
+
}
|
|
48
|
+
return this.client;
|
|
49
|
+
}
|
|
50
|
+
resolveKey(key) {
|
|
51
|
+
return `${this.options.keyPrefix ?? ""}${key}`;
|
|
52
|
+
}
|
|
53
|
+
async init() {
|
|
54
|
+
}
|
|
55
|
+
async close() {
|
|
56
|
+
if (this.client) {
|
|
57
|
+
this.client.destroy();
|
|
58
|
+
this.client = null;
|
|
59
|
+
}
|
|
60
|
+
}
|
|
61
|
+
async healthCheck() {
|
|
62
|
+
try {
|
|
63
|
+
await this.getClient().send(
|
|
64
|
+
new import_client_s3.HeadBucketCommand({ Bucket: this.options.bucketName })
|
|
65
|
+
);
|
|
66
|
+
return true;
|
|
67
|
+
} catch {
|
|
68
|
+
return false;
|
|
69
|
+
}
|
|
70
|
+
}
|
|
71
|
+
async put(key, data, options) {
|
|
72
|
+
const resolvedKey = this.resolveKey(key);
|
|
73
|
+
const contentType = options?.contentType;
|
|
74
|
+
if (data.byteLength > MULTIPART_THRESHOLD_BYTES) {
|
|
75
|
+
const upload = new import_lib_storage.Upload({
|
|
76
|
+
client: this.getClient(),
|
|
77
|
+
params: {
|
|
78
|
+
Bucket: this.options.bucketName,
|
|
79
|
+
Key: resolvedKey,
|
|
80
|
+
Body: data,
|
|
81
|
+
...contentType ? { ContentType: contentType } : {}
|
|
82
|
+
}
|
|
83
|
+
});
|
|
84
|
+
await upload.done();
|
|
85
|
+
} else {
|
|
86
|
+
await this.getClient().send(
|
|
87
|
+
new import_client_s3.PutObjectCommand({
|
|
88
|
+
Bucket: this.options.bucketName,
|
|
89
|
+
Key: resolvedKey,
|
|
90
|
+
Body: data,
|
|
91
|
+
...contentType ? { ContentType: contentType } : {}
|
|
92
|
+
})
|
|
93
|
+
);
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
async get(key) {
|
|
97
|
+
try {
|
|
98
|
+
const response = await this.getClient().send(
|
|
99
|
+
new import_client_s3.GetObjectCommand({
|
|
100
|
+
Bucket: this.options.bucketName,
|
|
101
|
+
Key: this.resolveKey(key)
|
|
102
|
+
})
|
|
103
|
+
);
|
|
104
|
+
if (!response.Body) {
|
|
105
|
+
return null;
|
|
106
|
+
}
|
|
107
|
+
const byteArray = await response.Body.transformToByteArray();
|
|
108
|
+
const buffer = Buffer.from(byteArray);
|
|
109
|
+
return {
|
|
110
|
+
data: buffer,
|
|
111
|
+
contentType: response.ContentType,
|
|
112
|
+
size: buffer.length
|
|
113
|
+
};
|
|
114
|
+
} catch (error) {
|
|
115
|
+
if (isMissingOrForbidden(error)) {
|
|
116
|
+
return null;
|
|
117
|
+
}
|
|
118
|
+
throw error;
|
|
119
|
+
}
|
|
120
|
+
}
|
|
121
|
+
async has(key) {
|
|
122
|
+
try {
|
|
123
|
+
await this.getClient().send(
|
|
124
|
+
new import_client_s3.HeadObjectCommand({
|
|
125
|
+
Bucket: this.options.bucketName,
|
|
126
|
+
Key: this.resolveKey(key)
|
|
127
|
+
})
|
|
128
|
+
);
|
|
129
|
+
return true;
|
|
130
|
+
} catch (error) {
|
|
131
|
+
if (isMissingOrForbidden(error)) {
|
|
132
|
+
return false;
|
|
133
|
+
}
|
|
134
|
+
throw error;
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
async delete(key) {
|
|
138
|
+
await this.getClient().send(
|
|
139
|
+
new import_client_s3.DeleteObjectCommand({
|
|
140
|
+
Bucket: this.options.bucketName,
|
|
141
|
+
Key: this.resolveKey(key)
|
|
142
|
+
})
|
|
143
|
+
);
|
|
144
|
+
}
|
|
145
|
+
async list(prefix, options) {
|
|
146
|
+
const resolvedPrefix = this.resolveKey(prefix);
|
|
147
|
+
const prefixOffset = (this.options.keyPrefix ?? "").length;
|
|
148
|
+
const response = await this.getClient().send(
|
|
149
|
+
new import_client_s3.ListObjectsV2Command({
|
|
150
|
+
Bucket: this.options.bucketName,
|
|
151
|
+
Prefix: resolvedPrefix,
|
|
152
|
+
MaxKeys: options?.limit,
|
|
153
|
+
ContinuationToken: options?.cursor ?? void 0
|
|
154
|
+
})
|
|
155
|
+
);
|
|
156
|
+
const keys = (response.Contents ?? []).map(
|
|
157
|
+
(object) => (object.Key ?? "").slice(prefixOffset)
|
|
158
|
+
);
|
|
159
|
+
return {
|
|
160
|
+
keys,
|
|
161
|
+
nextCursor: response.NextContinuationToken ?? null,
|
|
162
|
+
hasMore: response.IsTruncated ?? false
|
|
163
|
+
};
|
|
164
|
+
}
|
|
165
|
+
async getSignedUrl(key, options) {
|
|
166
|
+
const expiresInSeconds = options?.expiresIn ?? 3600;
|
|
167
|
+
const command = new import_client_s3.GetObjectCommand({
|
|
168
|
+
Bucket: this.options.bucketName,
|
|
169
|
+
Key: this.resolveKey(key)
|
|
170
|
+
});
|
|
171
|
+
return (0, import_s3_request_presigner.getSignedUrl)(this.getClient(), command, {
|
|
172
|
+
expiresIn: expiresInSeconds
|
|
173
|
+
});
|
|
174
|
+
}
|
|
175
|
+
async getSignedPutUrl(key, options) {
|
|
176
|
+
const expiresInSeconds = options?.expiresIn ?? 3600;
|
|
177
|
+
const command = new import_client_s3.PutObjectCommand({
|
|
178
|
+
Bucket: this.options.bucketName,
|
|
179
|
+
Key: this.resolveKey(key),
|
|
180
|
+
...options?.contentType ? { ContentType: options.contentType } : {}
|
|
181
|
+
});
|
|
182
|
+
return (0, import_s3_request_presigner.getSignedUrl)(this.getClient(), command, {
|
|
183
|
+
expiresIn: expiresInSeconds
|
|
184
|
+
});
|
|
185
|
+
}
|
|
186
|
+
};
|
|
187
|
+
function isMissingOrForbidden(error) {
|
|
188
|
+
if (!(error instanceof Error)) return false;
|
|
189
|
+
const name = error.name;
|
|
190
|
+
if (name === "NoSuchKey" || name === "NotFound") return true;
|
|
191
|
+
if (name === "Forbidden" || name === "AccessDenied") return true;
|
|
192
|
+
const status = error.$metadata?.httpStatusCode;
|
|
193
|
+
return status === 404 || status === 403;
|
|
194
|
+
}
|
|
195
|
+
// Annotate the CommonJS export names for ESM import in node:
|
|
196
|
+
0 && (module.exports = {
|
|
197
|
+
S3ObjectStorageAdapter
|
|
198
|
+
});
|
|
199
|
+
//# sourceMappingURL=index.cjs.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/index.ts","../src/adapter.ts"],"sourcesContent":["export { S3ObjectStorageAdapter } from \"./adapter.js\";\nexport type { S3ObjectStorageAdapterOptions } from \"./types.js\";\n","import {\n S3Client,\n PutObjectCommand,\n GetObjectCommand,\n DeleteObjectCommand,\n ListObjectsV2Command,\n HeadBucketCommand,\n HeadObjectCommand,\n} from \"@aws-sdk/client-s3\";\nimport { getSignedUrl as awsGetSignedUrl } from \"@aws-sdk/s3-request-presigner\";\nimport { Upload } from \"@aws-sdk/lib-storage\";\nimport type { ObjectStorageAdapter } from \"@starkeep/storage-adapter\";\nimport type {\n PutOptions,\n GetResult,\n ListOptions,\n ListResult,\n SignedUrlOptions,\n SignedPutUrlOptions,\n} from \"@starkeep/storage-adapter\";\nimport type { S3ObjectStorageAdapterOptions } from \"./types.js\";\n\nconst MULTIPART_THRESHOLD_BYTES = 5 * 1024 * 1024;\n\nexport class S3ObjectStorageAdapter implements ObjectStorageAdapter {\n private readonly options: S3ObjectStorageAdapterOptions;\n private client: S3Client | null = null;\n\n constructor(options: S3ObjectStorageAdapterOptions) {\n this.options = options;\n }\n\n private getClient(): S3Client {\n if (!this.client) {\n this.client = new S3Client({\n region: this.options.region,\n // When credentialProvider is set, pass it directly to the AWS SDK.\n // The SDK calls it before each signed request, so STS credentials\n // (e.g. from a Cognito Identity Pool) are always fresh.\n credentials: this.options.credentialProvider\n ? this.options.credentialProvider\n : this.options.credentials,\n });\n }\n return this.client;\n }\n\n private resolveKey(key: string): string {\n return `${this.options.keyPrefix ?? \"\"}${key}`;\n }\n\n async init(): Promise<void> {\n // No-op: S3 client is created lazily on first use\n }\n\n async close(): Promise<void> {\n if (this.client) {\n this.client.destroy();\n this.client = null;\n }\n }\n\n async healthCheck(): Promise<boolean> {\n try {\n await this.getClient().send(\n new HeadBucketCommand({ Bucket: this.options.bucketName }),\n );\n return true;\n } catch {\n return false;\n }\n }\n\n async put(\n key: string,\n data: Buffer | Uint8Array,\n options?: PutOptions,\n ): Promise<void> {\n const resolvedKey = this.resolveKey(key);\n const contentType = options?.contentType;\n\n if (data.byteLength > MULTIPART_THRESHOLD_BYTES) {\n const upload = new Upload({\n client: this.getClient(),\n params: {\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n Body: data,\n ...(contentType ? { ContentType: contentType } : {}),\n },\n });\n await upload.done();\n } else {\n await this.getClient().send(\n new PutObjectCommand({\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n Body: data,\n ...(contentType ? { ContentType: contentType } : {}),\n }),\n );\n }\n }\n\n async get(key: string): Promise<GetResult | null> {\n try {\n const response = await this.getClient().send(\n new GetObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n }),\n );\n\n if (!response.Body) {\n return null;\n }\n\n const byteArray = await response.Body.transformToByteArray();\n const buffer = Buffer.from(byteArray);\n\n return {\n data: buffer,\n contentType: response.ContentType,\n size: buffer.length,\n };\n } catch (error: unknown) {\n if (isMissingOrForbidden(error)) {\n return null;\n }\n throw error;\n }\n }\n\n async has(key: string): Promise<boolean> {\n try {\n await this.getClient().send(\n new HeadObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n }),\n );\n return true;\n } catch (error: unknown) {\n if (isMissingOrForbidden(error)) {\n // S3 returns 403 (Forbidden) instead of 404 to callers without\n // s3:ListBucket on the prefix — see the per-app permissions boundary\n // in roles-and-permissions.md, which intentionally withholds ListBucket\n // on shared/*. The two cases are indistinguishable from the SDK, so\n // treat both as \"not present\". A genuine permission problem will\n // surface clearly on the subsequent put/get of the same key.\n return false;\n }\n throw error;\n }\n }\n\n async delete(key: string): Promise<void> {\n await this.getClient().send(\n new DeleteObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n }),\n );\n }\n\n async list(prefix: string, options?: ListOptions): Promise<ListResult> {\n const resolvedPrefix = this.resolveKey(prefix);\n const prefixOffset = (this.options.keyPrefix ?? \"\").length;\n\n const response = await this.getClient().send(\n new ListObjectsV2Command({\n Bucket: this.options.bucketName,\n Prefix: resolvedPrefix,\n MaxKeys: options?.limit,\n ContinuationToken: options?.cursor ?? undefined,\n }),\n );\n\n const keys = (response.Contents ?? []).map(\n (object) => (object.Key ?? \"\").slice(prefixOffset),\n );\n\n return {\n keys,\n nextCursor: response.NextContinuationToken ?? null,\n hasMore: response.IsTruncated ?? false,\n };\n }\n\n async getSignedUrl(\n key: string,\n options?: SignedUrlOptions,\n ): Promise<string> {\n const expiresInSeconds = options?.expiresIn ?? 3600;\n const command = new GetObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n });\n\n return awsGetSignedUrl(this.getClient(), command, {\n expiresIn: expiresInSeconds,\n });\n }\n\n async getSignedPutUrl(\n key: string,\n options?: SignedPutUrlOptions,\n ): Promise<string> {\n const expiresInSeconds = options?.expiresIn ?? 3600;\n const command = new PutObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n ...(options?.contentType ? { ContentType: options.contentType } : {}),\n });\n\n return awsGetSignedUrl(this.getClient(), command, {\n expiresIn: expiresInSeconds,\n });\n }\n}\n\nfunction isMissingOrForbidden(error: unknown): boolean {\n if (!(error instanceof Error)) return false;\n const name = error.name;\n if (name === \"NoSuchKey\" || name === \"NotFound\") return true;\n if (name === \"Forbidden\" || name === \"AccessDenied\") return true;\n const status = (error as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode;\n return status === 404 || status === 403;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACAA,uBAQO;AACP,kCAAgD;AAChD,yBAAuB;AAYvB,IAAM,4BAA4B,IAAI,OAAO;AAEtC,IAAM,yBAAN,MAA6D;AAAA,EACjD;AAAA,EACT,SAA0B;AAAA,EAElC,YAAY,SAAwC;AAClD,SAAK,UAAU;AAAA,EACjB;AAAA,EAEQ,YAAsB;AAC5B,QAAI,CAAC,KAAK,QAAQ;AAChB,WAAK,SAAS,IAAI,0BAAS;AAAA,QACzB,QAAQ,KAAK,QAAQ;AAAA;AAAA;AAAA;AAAA,QAIrB,aAAa,KAAK,QAAQ,qBACtB,KAAK,QAAQ,qBACb,KAAK,QAAQ;AAAA,MACnB,CAAC;AAAA,IACH;AACA,WAAO,KAAK;AAAA,EACd;AAAA,EAEQ,WAAW,KAAqB;AACtC,WAAO,GAAG,KAAK,QAAQ,aAAa,EAAE,GAAG,GAAG;AAAA,EAC9C;AAAA,EAEA,MAAM,OAAsB;AAAA,EAE5B;AAAA,EAEA,MAAM,QAAuB;AAC3B,QAAI,KAAK,QAAQ;AACf,WAAK,OAAO,QAAQ;AACpB,WAAK,SAAS;AAAA,IAChB;AAAA,EACF;AAAA,EAEA,MAAM,cAAgC;AACpC,QAAI;AACF,YAAM,KAAK,UAAU,EAAE;AAAA,QACrB,IAAI,mCAAkB,EAAE,QAAQ,KAAK,QAAQ,WAAW,CAAC;AAAA,MAC3D;AACA,aAAO;AAAA,IACT,QAAQ;AACN,aAAO;AAAA,IACT;AAAA,EACF;AAAA,EAEA,MAAM,IACJ,KACA,MACA,SACe;AACf,UAAM,cAAc,KAAK,WAAW,GAAG;AACvC,UAAM,cAAc,SAAS;AAE7B,QAAI,KAAK,aAAa,2BAA2B;AAC/C,YAAM,SAAS,IAAI,0BAAO;AAAA,QACxB,QAAQ,KAAK,UAAU;AAAA,QACvB,QAAQ;AAAA,UACN,QAAQ,KAAK,QAAQ;AAAA,UACrB,KAAK;AAAA,UACL,MAAM;AAAA,UACN,GAAI,cAAc,EAAE,aAAa,YAAY,IAAI,CAAC;AAAA,QACpD;AAAA,MACF,CAAC;AACD,YAAM,OAAO,KAAK;AAAA,IACpB,OAAO;AACL,YAAM,KAAK,UAAU,EAAE;AAAA,QACrB,IAAI,kCAAiB;AAAA,UACnB,QAAQ,KAAK,QAAQ;AAAA,UACrB,KAAK;AAAA,UACL,MAAM;AAAA,UACN,GAAI,cAAc,EAAE,aAAa,YAAY,IAAI,CAAC;AAAA,QACpD,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AAAA,EAEA,MAAM,IAAI,KAAwC;AAChD,QAAI;AACF,YAAM,WAAW,MAAM,KAAK,UAAU,EAAE;AAAA,QACtC,IAAI,kCAAiB;AAAA,UACnB,QAAQ,KAAK,QAAQ;AAAA,UACrB,KAAK,KAAK,WAAW,GAAG;AAAA,QAC1B,CAAC;AAAA,MACH;AAEA,UAAI,CAAC,SAAS,MAAM;AAClB,eAAO;AAAA,MACT;AAEA,YAAM,YAAY,MAAM,SAAS,KAAK,qBAAqB;AAC3D,YAAM,SAAS,OAAO,KAAK,SAAS;AAEpC,aAAO;AAAA,QACL,MAAM;AAAA,QACN,aAAa,SAAS;AAAA,QACtB,MAAM,OAAO;AAAA,MACf;AAAA,IACF,SAAS,OAAgB;AACvB,UAAI,qBAAqB,KAAK,GAAG;AAC/B,eAAO;AAAA,MACT;AACA,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEA,MAAM,IAAI,KAA+B;AACvC,QAAI;AACF,YAAM,KAAK,UAAU,EAAE;AAAA,QACrB,IAAI,mCAAkB;AAAA,UACpB,QAAQ,KAAK,QAAQ;AAAA,UACrB,KAAK,KAAK,WAAW,GAAG;AAAA,QAC1B,CAAC;AAAA,MACH;AACA,aAAO;AAAA,IACT,SAAS,OAAgB;AACvB,UAAI,qBAAqB,KAAK,GAAG;AAO/B,eAAO;AAAA,MACT;AACA,YAAM;AAAA,IACR;AAAA,EACF;AAAA,EAEA,MAAM,OAAO,KAA4B;AACvC,UAAM,KAAK,UAAU,EAAE;AAAA,MACrB,IAAI,qCAAoB;AAAA,QACtB,QAAQ,KAAK,QAAQ;AAAA,QACrB,KAAK,KAAK,WAAW,GAAG;AAAA,MAC1B,CAAC;AAAA,IACH;AAAA,EACF;AAAA,EAEA,MAAM,KAAK,QAAgB,SAA4C;AACrE,UAAM,iBAAiB,KAAK,WAAW,MAAM;AAC7C,UAAM,gBAAgB,KAAK,QAAQ,aAAa,IAAI;AAEpD,UAAM,WAAW,MAAM,KAAK,UAAU,EAAE;AAAA,MACtC,IAAI,sCAAqB;AAAA,QACvB,QAAQ,KAAK,QAAQ;AAAA,QACrB,QAAQ;AAAA,QACR,SAAS,SAAS;AAAA,QAClB,mBAAmB,SAAS,UAAU;AAAA,MACxC,CAAC;AAAA,IACH;AAEA,UAAM,QAAQ,SAAS,YAAY,CAAC,GAAG;AAAA,MACrC,CAAC,YAAY,OAAO,OAAO,IAAI,MAAM,YAAY;AAAA,IACnD;AAEA,WAAO;AAAA,MACL;AAAA,MACA,YAAY,SAAS,yBAAyB;AAAA,MAC9C,SAAS,SAAS,eAAe;AAAA,IACnC;AAAA,EACF;AAAA,EAEA,MAAM,aACJ,KACA,SACiB;AACjB,UAAM,mBAAmB,SAAS,aAAa;AAC/C,UAAM,UAAU,IAAI,kCAAiB;AAAA,MACnC,QAAQ,KAAK,QAAQ;AAAA,MACrB,KAAK,KAAK,WAAW,GAAG;AAAA,IAC1B,CAAC;AAED,eAAO,4BAAAA,cAAgB,KAAK,UAAU,GAAG,SAAS;AAAA,MAChD,WAAW;AAAA,IACb,CAAC;AAAA,EACH;AAAA,EAEA,MAAM,gBACJ,KACA,SACiB;AACjB,UAAM,mBAAmB,SAAS,aAAa;AAC/C,UAAM,UAAU,IAAI,kCAAiB;AAAA,MACnC,QAAQ,KAAK,QAAQ;AAAA,MACrB,KAAK,KAAK,WAAW,GAAG;AAAA,MACxB,GAAI,SAAS,cAAc,EAAE,aAAa,QAAQ,YAAY,IAAI,CAAC;AAAA,IACrE,CAAC;AAED,eAAO,4BAAAA,cAAgB,KAAK,UAAU,GAAG,SAAS;AAAA,MAChD,WAAW;AAAA,IACb,CAAC;AAAA,EACH;AACF;AAEA,SAAS,qBAAqB,OAAyB;AACrD,MAAI,EAAE,iBAAiB,OAAQ,QAAO;AACtC,QAAM,OAAO,MAAM;AACnB,MAAI,SAAS,eAAe,SAAS,WAAY,QAAO;AACxD,MAAI,SAAS,eAAe,SAAS,eAAgB,QAAO;AAC5D,QAAM,SAAU,MAAsD,WAAW;AACjF,SAAO,WAAW,OAAO,WAAW;AACtC;","names":["awsGetSignedUrl"]}
|
package/dist/index.d.cts
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { ObjectStorageAdapter, PutOptions, GetResult, ListOptions, ListResult, SignedUrlOptions, SignedPutUrlOptions } from '@starkeep/storage-adapter';
|
|
2
|
+
|
|
3
|
+
interface S3Credentials {
|
|
4
|
+
readonly accessKeyId: string;
|
|
5
|
+
readonly secretAccessKey: string;
|
|
6
|
+
readonly sessionToken?: string;
|
|
7
|
+
}
|
|
8
|
+
interface S3ObjectStorageAdapterOptions {
|
|
9
|
+
readonly bucketName: string;
|
|
10
|
+
readonly region: string;
|
|
11
|
+
readonly keyPrefix?: string;
|
|
12
|
+
/**
|
|
13
|
+
* Static credentials. Use this for long-lived access keys.
|
|
14
|
+
* For short-lived STS credentials that rotate, use `credentialProvider` instead.
|
|
15
|
+
*/
|
|
16
|
+
readonly credentials?: S3Credentials;
|
|
17
|
+
/**
|
|
18
|
+
* Dynamic credential provider. Called before each S3Client instantiation
|
|
19
|
+
* so that rotating STS credentials (e.g. from a Cognito Identity Pool) are
|
|
20
|
+
* always fresh. Takes precedence over `credentials` when both are provided.
|
|
21
|
+
*/
|
|
22
|
+
readonly credentialProvider?: () => Promise<S3Credentials>;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
declare class S3ObjectStorageAdapter implements ObjectStorageAdapter {
|
|
26
|
+
private readonly options;
|
|
27
|
+
private client;
|
|
28
|
+
constructor(options: S3ObjectStorageAdapterOptions);
|
|
29
|
+
private getClient;
|
|
30
|
+
private resolveKey;
|
|
31
|
+
init(): Promise<void>;
|
|
32
|
+
close(): Promise<void>;
|
|
33
|
+
healthCheck(): Promise<boolean>;
|
|
34
|
+
put(key: string, data: Buffer | Uint8Array, options?: PutOptions): Promise<void>;
|
|
35
|
+
get(key: string): Promise<GetResult | null>;
|
|
36
|
+
has(key: string): Promise<boolean>;
|
|
37
|
+
delete(key: string): Promise<void>;
|
|
38
|
+
list(prefix: string, options?: ListOptions): Promise<ListResult>;
|
|
39
|
+
getSignedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
|
|
40
|
+
getSignedPutUrl(key: string, options?: SignedPutUrlOptions): Promise<string>;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export { S3ObjectStorageAdapter, type S3ObjectStorageAdapterOptions };
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
import { ObjectStorageAdapter, PutOptions, GetResult, ListOptions, ListResult, SignedUrlOptions, SignedPutUrlOptions } from '@starkeep/storage-adapter';
|
|
2
|
+
|
|
3
|
+
interface S3Credentials {
|
|
4
|
+
readonly accessKeyId: string;
|
|
5
|
+
readonly secretAccessKey: string;
|
|
6
|
+
readonly sessionToken?: string;
|
|
7
|
+
}
|
|
8
|
+
interface S3ObjectStorageAdapterOptions {
|
|
9
|
+
readonly bucketName: string;
|
|
10
|
+
readonly region: string;
|
|
11
|
+
readonly keyPrefix?: string;
|
|
12
|
+
/**
|
|
13
|
+
* Static credentials. Use this for long-lived access keys.
|
|
14
|
+
* For short-lived STS credentials that rotate, use `credentialProvider` instead.
|
|
15
|
+
*/
|
|
16
|
+
readonly credentials?: S3Credentials;
|
|
17
|
+
/**
|
|
18
|
+
* Dynamic credential provider. Called before each S3Client instantiation
|
|
19
|
+
* so that rotating STS credentials (e.g. from a Cognito Identity Pool) are
|
|
20
|
+
* always fresh. Takes precedence over `credentials` when both are provided.
|
|
21
|
+
*/
|
|
22
|
+
readonly credentialProvider?: () => Promise<S3Credentials>;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
declare class S3ObjectStorageAdapter implements ObjectStorageAdapter {
|
|
26
|
+
private readonly options;
|
|
27
|
+
private client;
|
|
28
|
+
constructor(options: S3ObjectStorageAdapterOptions);
|
|
29
|
+
private getClient;
|
|
30
|
+
private resolveKey;
|
|
31
|
+
init(): Promise<void>;
|
|
32
|
+
close(): Promise<void>;
|
|
33
|
+
healthCheck(): Promise<boolean>;
|
|
34
|
+
put(key: string, data: Buffer | Uint8Array, options?: PutOptions): Promise<void>;
|
|
35
|
+
get(key: string): Promise<GetResult | null>;
|
|
36
|
+
has(key: string): Promise<boolean>;
|
|
37
|
+
delete(key: string): Promise<void>;
|
|
38
|
+
list(prefix: string, options?: ListOptions): Promise<ListResult>;
|
|
39
|
+
getSignedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
|
|
40
|
+
getSignedPutUrl(key: string, options?: SignedPutUrlOptions): Promise<string>;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
export { S3ObjectStorageAdapter, type S3ObjectStorageAdapterOptions };
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
// src/adapter.ts
|
|
2
|
+
import {
|
|
3
|
+
S3Client,
|
|
4
|
+
PutObjectCommand,
|
|
5
|
+
GetObjectCommand,
|
|
6
|
+
DeleteObjectCommand,
|
|
7
|
+
ListObjectsV2Command,
|
|
8
|
+
HeadBucketCommand,
|
|
9
|
+
HeadObjectCommand
|
|
10
|
+
} from "@aws-sdk/client-s3";
|
|
11
|
+
import { getSignedUrl as awsGetSignedUrl } from "@aws-sdk/s3-request-presigner";
|
|
12
|
+
import { Upload } from "@aws-sdk/lib-storage";
|
|
13
|
+
var MULTIPART_THRESHOLD_BYTES = 5 * 1024 * 1024;
|
|
14
|
+
var S3ObjectStorageAdapter = class {
|
|
15
|
+
options;
|
|
16
|
+
client = null;
|
|
17
|
+
constructor(options) {
|
|
18
|
+
this.options = options;
|
|
19
|
+
}
|
|
20
|
+
getClient() {
|
|
21
|
+
if (!this.client) {
|
|
22
|
+
this.client = new S3Client({
|
|
23
|
+
region: this.options.region,
|
|
24
|
+
// When credentialProvider is set, pass it directly to the AWS SDK.
|
|
25
|
+
// The SDK calls it before each signed request, so STS credentials
|
|
26
|
+
// (e.g. from a Cognito Identity Pool) are always fresh.
|
|
27
|
+
credentials: this.options.credentialProvider ? this.options.credentialProvider : this.options.credentials
|
|
28
|
+
});
|
|
29
|
+
}
|
|
30
|
+
return this.client;
|
|
31
|
+
}
|
|
32
|
+
resolveKey(key) {
|
|
33
|
+
return `${this.options.keyPrefix ?? ""}${key}`;
|
|
34
|
+
}
|
|
35
|
+
async init() {
|
|
36
|
+
}
|
|
37
|
+
async close() {
|
|
38
|
+
if (this.client) {
|
|
39
|
+
this.client.destroy();
|
|
40
|
+
this.client = null;
|
|
41
|
+
}
|
|
42
|
+
}
|
|
43
|
+
async healthCheck() {
|
|
44
|
+
try {
|
|
45
|
+
await this.getClient().send(
|
|
46
|
+
new HeadBucketCommand({ Bucket: this.options.bucketName })
|
|
47
|
+
);
|
|
48
|
+
return true;
|
|
49
|
+
} catch {
|
|
50
|
+
return false;
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
async put(key, data, options) {
|
|
54
|
+
const resolvedKey = this.resolveKey(key);
|
|
55
|
+
const contentType = options?.contentType;
|
|
56
|
+
if (data.byteLength > MULTIPART_THRESHOLD_BYTES) {
|
|
57
|
+
const upload = new Upload({
|
|
58
|
+
client: this.getClient(),
|
|
59
|
+
params: {
|
|
60
|
+
Bucket: this.options.bucketName,
|
|
61
|
+
Key: resolvedKey,
|
|
62
|
+
Body: data,
|
|
63
|
+
...contentType ? { ContentType: contentType } : {}
|
|
64
|
+
}
|
|
65
|
+
});
|
|
66
|
+
await upload.done();
|
|
67
|
+
} else {
|
|
68
|
+
await this.getClient().send(
|
|
69
|
+
new PutObjectCommand({
|
|
70
|
+
Bucket: this.options.bucketName,
|
|
71
|
+
Key: resolvedKey,
|
|
72
|
+
Body: data,
|
|
73
|
+
...contentType ? { ContentType: contentType } : {}
|
|
74
|
+
})
|
|
75
|
+
);
|
|
76
|
+
}
|
|
77
|
+
}
|
|
78
|
+
async get(key) {
|
|
79
|
+
try {
|
|
80
|
+
const response = await this.getClient().send(
|
|
81
|
+
new GetObjectCommand({
|
|
82
|
+
Bucket: this.options.bucketName,
|
|
83
|
+
Key: this.resolveKey(key)
|
|
84
|
+
})
|
|
85
|
+
);
|
|
86
|
+
if (!response.Body) {
|
|
87
|
+
return null;
|
|
88
|
+
}
|
|
89
|
+
const byteArray = await response.Body.transformToByteArray();
|
|
90
|
+
const buffer = Buffer.from(byteArray);
|
|
91
|
+
return {
|
|
92
|
+
data: buffer,
|
|
93
|
+
contentType: response.ContentType,
|
|
94
|
+
size: buffer.length
|
|
95
|
+
};
|
|
96
|
+
} catch (error) {
|
|
97
|
+
if (isMissingOrForbidden(error)) {
|
|
98
|
+
return null;
|
|
99
|
+
}
|
|
100
|
+
throw error;
|
|
101
|
+
}
|
|
102
|
+
}
|
|
103
|
+
async has(key) {
|
|
104
|
+
try {
|
|
105
|
+
await this.getClient().send(
|
|
106
|
+
new HeadObjectCommand({
|
|
107
|
+
Bucket: this.options.bucketName,
|
|
108
|
+
Key: this.resolveKey(key)
|
|
109
|
+
})
|
|
110
|
+
);
|
|
111
|
+
return true;
|
|
112
|
+
} catch (error) {
|
|
113
|
+
if (isMissingOrForbidden(error)) {
|
|
114
|
+
return false;
|
|
115
|
+
}
|
|
116
|
+
throw error;
|
|
117
|
+
}
|
|
118
|
+
}
|
|
119
|
+
async delete(key) {
|
|
120
|
+
await this.getClient().send(
|
|
121
|
+
new DeleteObjectCommand({
|
|
122
|
+
Bucket: this.options.bucketName,
|
|
123
|
+
Key: this.resolveKey(key)
|
|
124
|
+
})
|
|
125
|
+
);
|
|
126
|
+
}
|
|
127
|
+
async list(prefix, options) {
|
|
128
|
+
const resolvedPrefix = this.resolveKey(prefix);
|
|
129
|
+
const prefixOffset = (this.options.keyPrefix ?? "").length;
|
|
130
|
+
const response = await this.getClient().send(
|
|
131
|
+
new ListObjectsV2Command({
|
|
132
|
+
Bucket: this.options.bucketName,
|
|
133
|
+
Prefix: resolvedPrefix,
|
|
134
|
+
MaxKeys: options?.limit,
|
|
135
|
+
ContinuationToken: options?.cursor ?? void 0
|
|
136
|
+
})
|
|
137
|
+
);
|
|
138
|
+
const keys = (response.Contents ?? []).map(
|
|
139
|
+
(object) => (object.Key ?? "").slice(prefixOffset)
|
|
140
|
+
);
|
|
141
|
+
return {
|
|
142
|
+
keys,
|
|
143
|
+
nextCursor: response.NextContinuationToken ?? null,
|
|
144
|
+
hasMore: response.IsTruncated ?? false
|
|
145
|
+
};
|
|
146
|
+
}
|
|
147
|
+
async getSignedUrl(key, options) {
|
|
148
|
+
const expiresInSeconds = options?.expiresIn ?? 3600;
|
|
149
|
+
const command = new GetObjectCommand({
|
|
150
|
+
Bucket: this.options.bucketName,
|
|
151
|
+
Key: this.resolveKey(key)
|
|
152
|
+
});
|
|
153
|
+
return awsGetSignedUrl(this.getClient(), command, {
|
|
154
|
+
expiresIn: expiresInSeconds
|
|
155
|
+
});
|
|
156
|
+
}
|
|
157
|
+
async getSignedPutUrl(key, options) {
|
|
158
|
+
const expiresInSeconds = options?.expiresIn ?? 3600;
|
|
159
|
+
const command = new PutObjectCommand({
|
|
160
|
+
Bucket: this.options.bucketName,
|
|
161
|
+
Key: this.resolveKey(key),
|
|
162
|
+
...options?.contentType ? { ContentType: options.contentType } : {}
|
|
163
|
+
});
|
|
164
|
+
return awsGetSignedUrl(this.getClient(), command, {
|
|
165
|
+
expiresIn: expiresInSeconds
|
|
166
|
+
});
|
|
167
|
+
}
|
|
168
|
+
};
|
|
169
|
+
function isMissingOrForbidden(error) {
|
|
170
|
+
if (!(error instanceof Error)) return false;
|
|
171
|
+
const name = error.name;
|
|
172
|
+
if (name === "NoSuchKey" || name === "NotFound") return true;
|
|
173
|
+
if (name === "Forbidden" || name === "AccessDenied") return true;
|
|
174
|
+
const status = error.$metadata?.httpStatusCode;
|
|
175
|
+
return status === 404 || status === 403;
|
|
176
|
+
}
|
|
177
|
+
export {
|
|
178
|
+
S3ObjectStorageAdapter
|
|
179
|
+
};
|
|
180
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"sources":["../src/adapter.ts"],"sourcesContent":["import {\n S3Client,\n PutObjectCommand,\n GetObjectCommand,\n DeleteObjectCommand,\n ListObjectsV2Command,\n HeadBucketCommand,\n HeadObjectCommand,\n} from \"@aws-sdk/client-s3\";\nimport { getSignedUrl as awsGetSignedUrl } from \"@aws-sdk/s3-request-presigner\";\nimport { Upload } from \"@aws-sdk/lib-storage\";\nimport type { ObjectStorageAdapter } from \"@starkeep/storage-adapter\";\nimport type {\n PutOptions,\n GetResult,\n ListOptions,\n ListResult,\n SignedUrlOptions,\n SignedPutUrlOptions,\n} from \"@starkeep/storage-adapter\";\nimport type { S3ObjectStorageAdapterOptions } from \"./types.js\";\n\nconst MULTIPART_THRESHOLD_BYTES = 5 * 1024 * 1024;\n\nexport class S3ObjectStorageAdapter implements ObjectStorageAdapter {\n private readonly options: S3ObjectStorageAdapterOptions;\n private client: S3Client | null = null;\n\n constructor(options: S3ObjectStorageAdapterOptions) {\n this.options = options;\n }\n\n private getClient(): S3Client {\n if (!this.client) {\n this.client = new S3Client({\n region: this.options.region,\n // When credentialProvider is set, pass it directly to the AWS SDK.\n // The SDK calls it before each signed request, so STS credentials\n // (e.g. from a Cognito Identity Pool) are always fresh.\n credentials: this.options.credentialProvider\n ? this.options.credentialProvider\n : this.options.credentials,\n });\n }\n return this.client;\n }\n\n private resolveKey(key: string): string {\n return `${this.options.keyPrefix ?? \"\"}${key}`;\n }\n\n async init(): Promise<void> {\n // No-op: S3 client is created lazily on first use\n }\n\n async close(): Promise<void> {\n if (this.client) {\n this.client.destroy();\n this.client = null;\n }\n }\n\n async healthCheck(): Promise<boolean> {\n try {\n await this.getClient().send(\n new HeadBucketCommand({ Bucket: this.options.bucketName }),\n );\n return true;\n } catch {\n return false;\n }\n }\n\n async put(\n key: string,\n data: Buffer | Uint8Array,\n options?: PutOptions,\n ): Promise<void> {\n const resolvedKey = this.resolveKey(key);\n const contentType = options?.contentType;\n\n if (data.byteLength > MULTIPART_THRESHOLD_BYTES) {\n const upload = new Upload({\n client: this.getClient(),\n params: {\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n Body: data,\n ...(contentType ? { ContentType: contentType } : {}),\n },\n });\n await upload.done();\n } else {\n await this.getClient().send(\n new PutObjectCommand({\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n Body: data,\n ...(contentType ? { ContentType: contentType } : {}),\n }),\n );\n }\n }\n\n async get(key: string): Promise<GetResult | null> {\n try {\n const response = await this.getClient().send(\n new GetObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n }),\n );\n\n if (!response.Body) {\n return null;\n }\n\n const byteArray = await response.Body.transformToByteArray();\n const buffer = Buffer.from(byteArray);\n\n return {\n data: buffer,\n contentType: response.ContentType,\n size: buffer.length,\n };\n } catch (error: unknown) {\n if (isMissingOrForbidden(error)) {\n return null;\n }\n throw error;\n }\n }\n\n async has(key: string): Promise<boolean> {\n try {\n await this.getClient().send(\n new HeadObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n }),\n );\n return true;\n } catch (error: unknown) {\n if (isMissingOrForbidden(error)) {\n // S3 returns 403 (Forbidden) instead of 404 to callers without\n // s3:ListBucket on the prefix — see the per-app permissions boundary\n // in roles-and-permissions.md, which intentionally withholds ListBucket\n // on shared/*. The two cases are indistinguishable from the SDK, so\n // treat both as \"not present\". A genuine permission problem will\n // surface clearly on the subsequent put/get of the same key.\n return false;\n }\n throw error;\n }\n }\n\n async delete(key: string): Promise<void> {\n await this.getClient().send(\n new DeleteObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n }),\n );\n }\n\n async list(prefix: string, options?: ListOptions): Promise<ListResult> {\n const resolvedPrefix = this.resolveKey(prefix);\n const prefixOffset = (this.options.keyPrefix ?? \"\").length;\n\n const response = await this.getClient().send(\n new ListObjectsV2Command({\n Bucket: this.options.bucketName,\n Prefix: resolvedPrefix,\n MaxKeys: options?.limit,\n ContinuationToken: options?.cursor ?? undefined,\n }),\n );\n\n const keys = (response.Contents ?? []).map(\n (object) => (object.Key ?? \"\").slice(prefixOffset),\n );\n\n return {\n keys,\n nextCursor: response.NextContinuationToken ?? null,\n hasMore: response.IsTruncated ?? false,\n };\n }\n\n async getSignedUrl(\n key: string,\n options?: SignedUrlOptions,\n ): Promise<string> {\n const expiresInSeconds = options?.expiresIn ?? 3600;\n const command = new GetObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n });\n\n return awsGetSignedUrl(this.getClient(), command, {\n expiresIn: expiresInSeconds,\n });\n }\n\n async getSignedPutUrl(\n key: string,\n options?: SignedPutUrlOptions,\n ): Promise<string> {\n const expiresInSeconds = options?.expiresIn ?? 3600;\n const command = new PutObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n ...(options?.contentType ? { ContentType: options.contentType } : {}),\n });\n\n return awsGetSignedUrl(this.getClient(), command, {\n expiresIn: expiresInSeconds,\n });\n }\n}\n\nfunction isMissingOrForbidden(error: unknown): boolean {\n if (!(error instanceof Error)) return false;\n const name = error.name;\n if (name === \"NoSuchKey\" || name === \"NotFound\") return true;\n if (name === \"Forbidden\" || name === \"AccessDenied\") return true;\n const status = (error as { $metadata?: { httpStatusCode?: number } }).$metadata?.httpStatusCode;\n return status === 404 || status === 403;\n}\n"],"mappings":"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","names":[]}
|
package/package.json
ADDED
|
@@ -0,0 +1,47 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@starkeep/storage-s3",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"license": "MIT",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./dist/index.cjs",
|
|
7
|
+
"module": "./dist/index.js",
|
|
8
|
+
"types": "./dist/index.d.ts",
|
|
9
|
+
"exports": {
|
|
10
|
+
".": {
|
|
11
|
+
"types": "./dist/index.d.ts",
|
|
12
|
+
"import": "./dist/index.js",
|
|
13
|
+
"require": "./dist/index.cjs"
|
|
14
|
+
}
|
|
15
|
+
},
|
|
16
|
+
"files": [
|
|
17
|
+
"dist",
|
|
18
|
+
"README.md"
|
|
19
|
+
],
|
|
20
|
+
"publishConfig": {
|
|
21
|
+
"access": "public"
|
|
22
|
+
},
|
|
23
|
+
"repository": {
|
|
24
|
+
"type": "git",
|
|
25
|
+
"url": "git+https://github.com/starkeep-dev/starkeep-core.git",
|
|
26
|
+
"directory": "packages/storage-s3"
|
|
27
|
+
},
|
|
28
|
+
"homepage": "https://github.com/starkeep-dev/starkeep-core/tree/main/packages/storage-s3",
|
|
29
|
+
"dependencies": {
|
|
30
|
+
"@aws-sdk/client-s3": "^3.700.0",
|
|
31
|
+
"@aws-sdk/s3-request-presigner": "^3.700.0",
|
|
32
|
+
"@aws-sdk/lib-storage": "^3.700.0",
|
|
33
|
+
"@starkeep/storage-adapter": "0.1.0"
|
|
34
|
+
},
|
|
35
|
+
"devDependencies": {
|
|
36
|
+
"@types/node": "^25.4.0",
|
|
37
|
+
"tsup": "^8.0.0",
|
|
38
|
+
"typescript": "^5.7.0",
|
|
39
|
+
"vitest": "^3.0.0"
|
|
40
|
+
},
|
|
41
|
+
"scripts": {
|
|
42
|
+
"build": "tsup",
|
|
43
|
+
"test": "vitest run",
|
|
44
|
+
"typecheck": "tsc --noEmit",
|
|
45
|
+
"lint": "eslint src/"
|
|
46
|
+
}
|
|
47
|
+
}
|