@starkeep/storage-s3 0.4.0 → 0.5.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/dist/index.cjs CHANGED
@@ -337,6 +337,62 @@ var S3ObjectStorageAdapter = class {
337
337
  ...signableHeaders.size > 0 ? { signableHeaders, unhoistableHeaders: new Set(signableHeaders) } : {}
338
338
  });
339
339
  }
340
+ /**
341
+ * Start a multipart upload whose every part must carry a SHA-256.
342
+ *
343
+ * Storage class and tags belong to the upload, not to its parts, so they are
344
+ * fixed here, by the signer, and no part's PUT can change them.
345
+ */
346
+ async createMultipartUpload(key, options) {
347
+ const response = await this.getClient().send(
348
+ new import_client_s3.CreateMultipartUploadCommand({
349
+ Bucket: this.options.bucketName,
350
+ Key: this.resolveKey(key),
351
+ ChecksumAlgorithm: "SHA256",
352
+ ...options?.contentType ? { ContentType: options.contentType } : {},
353
+ ...options?.storageClass ? { StorageClass: options.storageClass } : {},
354
+ ...options?.tagging ? { Tagging: encodeTagging(options.tagging) } : {}
355
+ })
356
+ );
357
+ if (!response.UploadId) throw new Error(`CreateMultipartUpload ${key} returned no upload id`);
358
+ return response.UploadId;
359
+ }
360
+ /**
361
+ * Presign one part's PUT with its SHA-256 bound into the signature as a
362
+ * header, exactly as {@link getSignedPutUrl} binds a whole object's. S3 then
363
+ * refuses a part whose bytes hash to anything else.
364
+ */
365
+ async getSignedUploadPartUrl(key, uploadId, partNumber, options) {
366
+ const command = new import_client_s3.UploadPartCommand({
367
+ Bucket: this.options.bucketName,
368
+ Key: this.resolveKey(key),
369
+ UploadId: uploadId,
370
+ PartNumber: partNumber,
371
+ ChecksumSHA256: options.checksumSha256
372
+ });
373
+ const pinned = /* @__PURE__ */ new Set(["x-amz-checksum-sha256"]);
374
+ return (0, import_s3_request_presigner.getSignedUrl)(this.getClient(), command, {
375
+ expiresIn: options.expiresIn ?? 3600,
376
+ signableHeaders: pinned,
377
+ unhoistableHeaders: new Set(pinned)
378
+ });
379
+ }
380
+ async completeMultipartUpload(key, uploadId, parts) {
381
+ await this.getClient().send(
382
+ new import_client_s3.CompleteMultipartUploadCommand({
383
+ Bucket: this.options.bucketName,
384
+ Key: this.resolveKey(key),
385
+ UploadId: uploadId,
386
+ MultipartUpload: {
387
+ Parts: parts.map((p) => ({
388
+ PartNumber: p.partNumber,
389
+ ETag: p.etag,
390
+ ChecksumSHA256: p.checksumSha256
391
+ }))
392
+ }
393
+ })
394
+ );
395
+ }
340
396
  };
341
397
  function availabilityOf(storageClass, archiveStatus, restore) {
342
398
  const archivedTier = storageClass === "GLACIER" || storageClass === "DEEP_ARCHIVE" ? storageClass : archiveStatus === "ARCHIVE_ACCESS" || archiveStatus === "DEEP_ARCHIVE_ACCESS" ? archiveStatus : null;
@@ -1 +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 PutObjectTaggingCommand,\n RestoreObjectCommand,\n} from \"@aws-sdk/client-s3\";\nimport type { PutObjectCommandInput } from \"@aws-sdk/client-s3\";\nimport { getSignedUrl as awsGetSignedUrl } from \"@aws-sdk/s3-request-presigner\";\nimport { createHash } from \"node:crypto\";\nimport { createReadStream, createWriteStream } from \"node:fs\";\nimport { mkdtemp, rm } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { Readable } from \"node:stream\";\nimport { pipeline } from \"node:stream/promises\";\nimport type { ObjectStorageAdapter } from \"@starkeep/storage-adapter\";\nimport type {\n ByteRange,\n PutOptions,\n GetResult,\n ListOptions,\n ListResult,\n ObjectAvailability,\n ObjectFacts,\n PutStreamOptions,\n SignedUrlOptions,\n SignedPutUrlOptions,\n} from \"@starkeep/storage-adapter\";\nimport type { S3ObjectStorageAdapterOptions } from \"./types.js\";\n\n/**\n * The largest object one PutObject request may carry.\n *\n * Every object this adapter writes goes up in one request, because only a\n * single-request upload can carry a whole-object SHA-256. S3 stores a\n * multipart upload's SHA-256 as a composite over the parts, suffixed\n * `-<partCount>`, which is not the object's hash; full-object checksums for\n * multipart exist only for the CRC algorithms. Without a whole-object SHA-256\n * no node can prove the cloud holds a file, so \"Free up space\" could never\n * free it. The presigned uploads devices use are single requests too, so this\n * is already the largest file the system can hold.\n */\nexport const MAX_SINGLE_PUT_BYTES = 5 * 1024 ** 3;\n\nfunction sha256Base64(data: Uint8Array): string {\n return createHash(\"sha256\").update(data).digest(\"base64\");\n}\n\nfunction hexToBase64(hex: string): string {\n return Buffer.from(hex, \"hex\").toString(\"base64\");\n}\n\nfunction tooLarge(key: string, bytes: number): Error {\n return new Error(\n `${key} is ${bytes} bytes; S3 takes at most ${MAX_SINGLE_PUT_BYTES} in one request, ` +\n \"and only a single-request upload carries a whole-object SHA-256\",\n );\n}\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(new HeadBucketCommand({ Bucket: this.options.bucketName }));\n return true;\n } catch {\n return false;\n }\n }\n\n async put(key: string, data: Buffer | Uint8Array, options?: PutOptions): Promise<void> {\n const resolvedKey = this.resolveKey(key);\n const contentType = options?.contentType;\n\n if (data.byteLength > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, data.byteLength);\n await this.getClient().send(\n new PutObjectCommand({\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n Body: data,\n ...(contentType ? { ContentType: contentType } : {}),\n ...(options?.metadata ? { Metadata: options.metadata } : {}),\n // Always a whole-object SHA-256: the caller's, or one computed here\n // from the bytes in hand. S3 rejects a body that doesn't match rather\n // than storing it, so a 200 means \"S3 confirmed these bytes\", and\n // `stat()` reports a checksum a node can prove a replica against.\n ChecksumSHA256: options?.checksumSha256 ?? sha256Base64(data),\n }),\n );\n }\n\n async getStream(key: string, range?: ByteRange): Promise<ReadableStream<Uint8Array> | null> {\n try {\n const response = await this.getClient().send(\n new GetObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n // S3's Range header is inclusive at both ends and an absent end means\n // \"to the last byte\" — the same shape as ByteRange, so this is a\n // formatting change and not a semantic one.\n ...(range ? { Range: `bytes=${range.start}-${range.end ?? \"\"}` } : {}),\n }),\n );\n if (!response.Body) return null;\n // The SDK hands back a Node Readable in this runtime; the adapter\n // contract is a web ReadableStream so the same interface is\n // implementable on React Native and in a browser. `transformToWebStream`\n // is the SDK's own conversion, so no bytes are buffered here.\n return (\n response.Body as { transformToWebStream(): ReadableStream<Uint8Array> }\n ).transformToWebStream();\n } catch (error: unknown) {\n if (isMissingOrForbidden(error)) return null;\n throw error;\n }\n }\n\n async putStream(\n key: string,\n body: ReadableStream<Uint8Array>,\n options?: PutStreamOptions,\n ): Promise<void> {\n const resolvedKey = this.resolveKey(key);\n const base: PutObjectCommandInput = {\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n ...(options?.contentType ? { ContentType: options.contentType } : {}),\n ...(options?.metadata ? { Metadata: options.metadata } : {}),\n };\n\n // A known length streams straight through in one request. With the\n // expected hash, S3 checks the whole object against it; without one, the\n // SDK computes a SHA-256 as the bytes pass and S3 stores it as a\n // whole-object checksum.\n if (options?.sizeBytes !== undefined) {\n if (options.sizeBytes > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, options.sizeBytes);\n await this.getClient().send(\n new PutObjectCommand({\n ...base,\n Body: Readable.fromWeb(body as Parameters<typeof Readable.fromWeb>[0]),\n ContentLength: options.sizeBytes,\n ...(options.expectedSha256Hex\n ? { ChecksumSHA256: hexToBase64(options.expectedSha256Hex) }\n : { ChecksumAlgorithm: \"SHA256\" as const }),\n }),\n );\n return;\n }\n\n // An unknown length cannot be one request, so the bytes spool to a\n // temporary file while they hash, and go up from there with both.\n const dir = await mkdtemp(join(tmpdir(), \"starkeep-s3-put-\"));\n const path = join(dir, \"body\");\n try {\n const hash = createHash(\"sha256\");\n let bytes = 0;\n await pipeline(\n Readable.fromWeb(body as Parameters<typeof Readable.fromWeb>[0]),\n async function* (source: AsyncIterable<Uint8Array>) {\n for await (const chunk of source) {\n hash.update(chunk);\n bytes += chunk.byteLength;\n if (bytes > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, bytes);\n yield chunk;\n }\n },\n createWriteStream(path),\n );\n const digest = hash.digest();\n if (options?.expectedSha256Hex && digest.toString(\"hex\") !== options.expectedSha256Hex) {\n throw new Error(\n `${key}: the streamed bytes hash to ${digest.toString(\"hex\")}, not ${options.expectedSha256Hex}`,\n );\n }\n await this.getClient().send(\n new PutObjectCommand({\n ...base,\n Body: createReadStream(path),\n ContentLength: bytes,\n ChecksumSHA256: digest.toString(\"base64\"),\n }),\n );\n } finally {\n await rm(dir, { recursive: true, force: true });\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 data-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 stat(key: string): Promise<ObjectFacts | null> {\n let response;\n try {\n response = await this.getClient().send(\n new HeadObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n // Without this S3 omits the stored checksum from the response even\n // when the object has one.\n ChecksumMode: \"ENABLED\",\n }),\n );\n } catch (error: unknown) {\n // Same 403-means-404 caveat as has(); see the comment there.\n if (isMissingOrForbidden(error)) return null;\n throw error;\n }\n\n // S3 omits StorageClass entirely for STANDARD.\n const storageClass = response.StorageClass ?? \"STANDARD\";\n return {\n sizeBytes: response.ContentLength ?? 0,\n checksumSha256: response.ChecksumSHA256 ?? null,\n storageClass,\n availability: availabilityOf(\n storageClass,\n response.ArchiveStatus ?? null,\n response.Restore ?? null,\n ),\n ...(response.ContentType ? { contentType: response.ContentType } : {}),\n ...(response.Metadata ? { metadata: response.Metadata } : {}),\n };\n }\n\n async setTags(key: string, tags: Record<string, string>): Promise<void> {\n await this.getClient().send(\n new PutObjectTaggingCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n Tagging: {\n TagSet: Object.entries(tags).map(([Key, Value]) => ({ Key, Value })),\n },\n }),\n );\n }\n\n async restoreObject(\n key: string,\n options: { tier: string; days: number },\n ): Promise<\"started\" | \"already-in-progress\"> {\n try {\n await this.getClient().send(\n new RestoreObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n RestoreRequest: {\n Days: options.days,\n GlacierJobParameters: { Tier: options.tier as \"Standard\" | \"Bulk\" | \"Expedited\" },\n },\n }),\n );\n return \"started\";\n } catch (error: unknown) {\n // S3 reports an in-flight restore as an error, not a success. Treating it\n // as a failure would make the ordinary case of two clients asking at once\n // look broken, and would tempt a caller into retrying — which cannot help\n // and costs another request.\n if ((error as Error)?.name === \"RestoreAlreadyInProgress\") {\n return \"already-in-progress\";\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((object) => (object.Key ?? \"\").slice(prefixOffset));\n\n return {\n keys,\n nextCursor: response.NextContinuationToken ?? null,\n hasMore: response.IsTruncated ?? false,\n };\n }\n\n async getSignedUrl(key: string, options?: SignedUrlOptions): 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(key: string, options?: SignedPutUrlOptions): 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 // Binds the permitted body into the signature: the holder of this URL\n // may write these exact bytes to this key and nothing else. S3 rejects a\n // mismatched body rather than storing it, so \"200\" becomes a statement\n // about the bytes and not just about the request.\n ...(options?.checksumSha256 ? { ChecksumSHA256: options.checksumSha256 } : {}),\n ...(options?.storageClass\n ? { StorageClass: options.storageClass as PutObjectCommandInput[\"StorageClass\"] }\n : {}),\n ...(options?.tagging ? { Tagging: encodeTagging(options.tagging) } : {}),\n });\n\n // An unsigned header is one the uploader can simply drop: it would upload\n // unverified bytes, into whichever storage class it liked, tagged however\n // it liked. Signing them makes sending the exact values mandatory.\n //\n // `signableHeaders` alone does NOT achieve that. The S3 presigner's default\n // is to *hoist* every `x-amz-*` header into the query string, which leaves\n // `SignedHeaders=host` — and a client that then sends the values as headers\n // (which is what \"signed header\" asks of it) gets a 403 from S3:\n //\n // AccessDenied: There were headers present in the request which were not\n // signed — x-amz-checksum-sha256, x-amz-storage-class\n //\n // `unhoistableHeaders` is what keeps them in the signature as headers. It\n // has to name the same set: hoisting wins otherwise, and the failure lands\n // on the uploader as an access error about permissions it does hold.\n const signableHeaders = new Set<string>();\n if (options?.checksumSha256) signableHeaders.add(\"x-amz-checksum-sha256\");\n if (options?.storageClass) signableHeaders.add(\"x-amz-storage-class\");\n if (options?.tagging) signableHeaders.add(\"x-amz-tagging\");\n\n return awsGetSignedUrl(this.getClient(), command, {\n expiresIn: expiresInSeconds,\n ...(signableHeaders.size > 0\n ? { signableHeaders, unhoistableHeaders: new Set(signableHeaders) }\n : {}),\n });\n }\n}\n\n/**\n * Map HEAD's storage-class / archive-status / restore triple onto whether the\n * bytes can be read right now.\n *\n * The three inputs disagree in a way that matters: an Intelligent-Tiering\n * object reports `StorageClass: INTELLIGENT_TIERING` whether or not it has sunk\n * into an async archive tier — only `ArchiveStatus` says which. Reading storage\n * class alone would call a DEEP_ARCHIVE_ACCESS object instantly readable.\n *\n * (Our bucket must never enable I-T's async tiers, so `ArchiveStatus` should\n * always be absent in practice. It is handled anyway because \"should\" is doing\n * a lot of work there, and the failure mode of ignoring it is a read that hangs\n * for 12 hours.)\n */\nfunction availabilityOf(\n storageClass: string,\n archiveStatus: string | null,\n restore: string | null,\n): ObjectAvailability {\n const archivedTier =\n storageClass === \"GLACIER\" || storageClass === \"DEEP_ARCHIVE\"\n ? storageClass\n : archiveStatus === \"ARCHIVE_ACCESS\" || archiveStatus === \"DEEP_ARCHIVE_ACCESS\"\n ? archiveStatus\n : null;\n if (!archivedTier) return { state: \"instant\" };\n\n // Restore header forms:\n // ongoing-request=\"true\" → restore in flight\n // ongoing-request=\"false\", expiry-date=\"<http-date>\" → temporarily readable\n // (absent) → not restored\n if (restore) {\n if (/ongoing-request=\"true\"/.test(restore)) {\n return { state: \"restoring\", readyAt: null };\n }\n if (/ongoing-request=\"false\"/.test(restore)) {\n // A restored copy exists and is readable until its expiry. Callers that\n // care when it lapses read `storageClass`; for \"can I read it now\" the\n // answer is simply yes.\n return { state: \"instant\" };\n }\n }\n\n return {\n state: \"archived\",\n tier: archivedTier,\n // Standard-tier retrieval, which is what the restore flow requests. Bulk is\n // cheaper by hundredths of a cent and slower by a day and a half, so it is\n // only used for batch restores.\n expectedLatencyHours:\n archivedTier === \"DEEP_ARCHIVE\" || archivedTier === \"DEEP_ARCHIVE_ACCESS\" ? 12 : 5,\n };\n}\n\n/**\n * S3 takes object tags as a URL-encoded query string, not JSON.\n *\n * Encoded here rather than by callers because the keys involved contain a\n * colon (`starkeep:intent`), which survives naive concatenation and then fails\n * signature validation in a way that reports only \"SignatureDoesNotMatch\".\n */\nfunction encodeTagging(tags: Record<string, string>): string {\n return Object.entries(tags)\n .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)\n .join(\"&\");\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":["import_promises","awsGetSignedUrl"]}
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 PutObjectTaggingCommand,\n RestoreObjectCommand,\n CreateMultipartUploadCommand,\n UploadPartCommand,\n CompleteMultipartUploadCommand,\n} from \"@aws-sdk/client-s3\";\nimport type { PutObjectCommandInput } from \"@aws-sdk/client-s3\";\nimport { getSignedUrl as awsGetSignedUrl } from \"@aws-sdk/s3-request-presigner\";\nimport { createHash } from \"node:crypto\";\nimport { createReadStream, createWriteStream } from \"node:fs\";\nimport { mkdtemp, rm } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { Readable } from \"node:stream\";\nimport { pipeline } from \"node:stream/promises\";\nimport type { ObjectStorageAdapter } from \"@starkeep/storage-adapter\";\nimport type {\n ByteRange,\n PutOptions,\n GetResult,\n ListOptions,\n ListResult,\n ObjectAvailability,\n ObjectFacts,\n PutStreamOptions,\n SignedUrlOptions,\n SignedPutUrlOptions,\n MultipartUploadOptions,\n CompletedPart,\n} from \"@starkeep/storage-adapter\";\nimport type { S3ObjectStorageAdapterOptions } from \"./types.js\";\n\n/**\n * The largest object one PutObject request may carry.\n *\n * Every object this adapter writes itself goes up in one request, so the store\n * keeps a whole-object SHA-256 for it. A device sending a large file goes\n * through the presigned multipart trio below instead, in fixed 16 MiB parts,\n * and S3 stores a composite checksum over the parts. A node proves that\n * composite by recomputing it from its own copy (see `multipart.ts` in\n * storage-adapter), so both kinds of object can be freed.\n */\nexport const MAX_SINGLE_PUT_BYTES = 5 * 1024 ** 3;\n\nfunction sha256Base64(data: Uint8Array): string {\n return createHash(\"sha256\").update(data).digest(\"base64\");\n}\n\nfunction hexToBase64(hex: string): string {\n return Buffer.from(hex, \"hex\").toString(\"base64\");\n}\n\nfunction tooLarge(key: string, bytes: number): Error {\n return new Error(\n `${key} is ${bytes} bytes; S3 takes at most ${MAX_SINGLE_PUT_BYTES} in one request, ` +\n \"and only a single-request upload carries a whole-object SHA-256\",\n );\n}\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(new HeadBucketCommand({ Bucket: this.options.bucketName }));\n return true;\n } catch {\n return false;\n }\n }\n\n async put(key: string, data: Buffer | Uint8Array, options?: PutOptions): Promise<void> {\n const resolvedKey = this.resolveKey(key);\n const contentType = options?.contentType;\n\n if (data.byteLength > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, data.byteLength);\n await this.getClient().send(\n new PutObjectCommand({\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n Body: data,\n ...(contentType ? { ContentType: contentType } : {}),\n ...(options?.metadata ? { Metadata: options.metadata } : {}),\n // Always a whole-object SHA-256: the caller's, or one computed here\n // from the bytes in hand. S3 rejects a body that doesn't match rather\n // than storing it, so a 200 means \"S3 confirmed these bytes\", and\n // `stat()` reports a checksum a node can prove a replica against.\n ChecksumSHA256: options?.checksumSha256 ?? sha256Base64(data),\n }),\n );\n }\n\n async getStream(key: string, range?: ByteRange): Promise<ReadableStream<Uint8Array> | null> {\n try {\n const response = await this.getClient().send(\n new GetObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n // S3's Range header is inclusive at both ends and an absent end means\n // \"to the last byte\" — the same shape as ByteRange, so this is a\n // formatting change and not a semantic one.\n ...(range ? { Range: `bytes=${range.start}-${range.end ?? \"\"}` } : {}),\n }),\n );\n if (!response.Body) return null;\n // The SDK hands back a Node Readable in this runtime; the adapter\n // contract is a web ReadableStream so the same interface is\n // implementable on React Native and in a browser. `transformToWebStream`\n // is the SDK's own conversion, so no bytes are buffered here.\n return (\n response.Body as { transformToWebStream(): ReadableStream<Uint8Array> }\n ).transformToWebStream();\n } catch (error: unknown) {\n if (isMissingOrForbidden(error)) return null;\n throw error;\n }\n }\n\n async putStream(\n key: string,\n body: ReadableStream<Uint8Array>,\n options?: PutStreamOptions,\n ): Promise<void> {\n const resolvedKey = this.resolveKey(key);\n const base: PutObjectCommandInput = {\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n ...(options?.contentType ? { ContentType: options.contentType } : {}),\n ...(options?.metadata ? { Metadata: options.metadata } : {}),\n };\n\n // A known length streams straight through in one request. With the\n // expected hash, S3 checks the whole object against it; without one, the\n // SDK computes a SHA-256 as the bytes pass and S3 stores it as a\n // whole-object checksum.\n if (options?.sizeBytes !== undefined) {\n if (options.sizeBytes > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, options.sizeBytes);\n await this.getClient().send(\n new PutObjectCommand({\n ...base,\n Body: Readable.fromWeb(body as Parameters<typeof Readable.fromWeb>[0]),\n ContentLength: options.sizeBytes,\n ...(options.expectedSha256Hex\n ? { ChecksumSHA256: hexToBase64(options.expectedSha256Hex) }\n : { ChecksumAlgorithm: \"SHA256\" as const }),\n }),\n );\n return;\n }\n\n // An unknown length cannot be one request, so the bytes spool to a\n // temporary file while they hash, and go up from there with both.\n const dir = await mkdtemp(join(tmpdir(), \"starkeep-s3-put-\"));\n const path = join(dir, \"body\");\n try {\n const hash = createHash(\"sha256\");\n let bytes = 0;\n await pipeline(\n Readable.fromWeb(body as Parameters<typeof Readable.fromWeb>[0]),\n async function* (source: AsyncIterable<Uint8Array>) {\n for await (const chunk of source) {\n hash.update(chunk);\n bytes += chunk.byteLength;\n if (bytes > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, bytes);\n yield chunk;\n }\n },\n createWriteStream(path),\n );\n const digest = hash.digest();\n if (options?.expectedSha256Hex && digest.toString(\"hex\") !== options.expectedSha256Hex) {\n throw new Error(\n `${key}: the streamed bytes hash to ${digest.toString(\"hex\")}, not ${options.expectedSha256Hex}`,\n );\n }\n await this.getClient().send(\n new PutObjectCommand({\n ...base,\n Body: createReadStream(path),\n ContentLength: bytes,\n ChecksumSHA256: digest.toString(\"base64\"),\n }),\n );\n } finally {\n await rm(dir, { recursive: true, force: true });\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 data-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 stat(key: string): Promise<ObjectFacts | null> {\n let response;\n try {\n response = await this.getClient().send(\n new HeadObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n // Without this S3 omits the stored checksum from the response even\n // when the object has one.\n ChecksumMode: \"ENABLED\",\n }),\n );\n } catch (error: unknown) {\n // Same 403-means-404 caveat as has(); see the comment there.\n if (isMissingOrForbidden(error)) return null;\n throw error;\n }\n\n // S3 omits StorageClass entirely for STANDARD.\n const storageClass = response.StorageClass ?? \"STANDARD\";\n return {\n sizeBytes: response.ContentLength ?? 0,\n checksumSha256: response.ChecksumSHA256 ?? null,\n storageClass,\n availability: availabilityOf(\n storageClass,\n response.ArchiveStatus ?? null,\n response.Restore ?? null,\n ),\n ...(response.ContentType ? { contentType: response.ContentType } : {}),\n ...(response.Metadata ? { metadata: response.Metadata } : {}),\n };\n }\n\n async setTags(key: string, tags: Record<string, string>): Promise<void> {\n await this.getClient().send(\n new PutObjectTaggingCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n Tagging: {\n TagSet: Object.entries(tags).map(([Key, Value]) => ({ Key, Value })),\n },\n }),\n );\n }\n\n async restoreObject(\n key: string,\n options: { tier: string; days: number },\n ): Promise<\"started\" | \"already-in-progress\"> {\n try {\n await this.getClient().send(\n new RestoreObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n RestoreRequest: {\n Days: options.days,\n GlacierJobParameters: { Tier: options.tier as \"Standard\" | \"Bulk\" | \"Expedited\" },\n },\n }),\n );\n return \"started\";\n } catch (error: unknown) {\n // S3 reports an in-flight restore as an error, not a success. Treating it\n // as a failure would make the ordinary case of two clients asking at once\n // look broken, and would tempt a caller into retrying — which cannot help\n // and costs another request.\n if ((error as Error)?.name === \"RestoreAlreadyInProgress\") {\n return \"already-in-progress\";\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((object) => (object.Key ?? \"\").slice(prefixOffset));\n\n return {\n keys,\n nextCursor: response.NextContinuationToken ?? null,\n hasMore: response.IsTruncated ?? false,\n };\n }\n\n async getSignedUrl(key: string, options?: SignedUrlOptions): 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(key: string, options?: SignedPutUrlOptions): 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 // Binds the permitted body into the signature: the holder of this URL\n // may write these exact bytes to this key and nothing else. S3 rejects a\n // mismatched body rather than storing it, so \"200\" becomes a statement\n // about the bytes and not just about the request.\n ...(options?.checksumSha256 ? { ChecksumSHA256: options.checksumSha256 } : {}),\n ...(options?.storageClass\n ? { StorageClass: options.storageClass as PutObjectCommandInput[\"StorageClass\"] }\n : {}),\n ...(options?.tagging ? { Tagging: encodeTagging(options.tagging) } : {}),\n });\n\n // An unsigned header is one the uploader can simply drop: it would upload\n // unverified bytes, into whichever storage class it liked, tagged however\n // it liked. Signing them makes sending the exact values mandatory.\n //\n // `signableHeaders` alone does NOT achieve that. The S3 presigner's default\n // is to *hoist* every `x-amz-*` header into the query string, which leaves\n // `SignedHeaders=host` — and a client that then sends the values as headers\n // (which is what \"signed header\" asks of it) gets a 403 from S3:\n //\n // AccessDenied: There were headers present in the request which were not\n // signed — x-amz-checksum-sha256, x-amz-storage-class\n //\n // `unhoistableHeaders` is what keeps them in the signature as headers. It\n // has to name the same set: hoisting wins otherwise, and the failure lands\n // on the uploader as an access error about permissions it does hold.\n const signableHeaders = new Set<string>();\n if (options?.checksumSha256) signableHeaders.add(\"x-amz-checksum-sha256\");\n if (options?.storageClass) signableHeaders.add(\"x-amz-storage-class\");\n if (options?.tagging) signableHeaders.add(\"x-amz-tagging\");\n\n return awsGetSignedUrl(this.getClient(), command, {\n expiresIn: expiresInSeconds,\n ...(signableHeaders.size > 0\n ? { signableHeaders, unhoistableHeaders: new Set(signableHeaders) }\n : {}),\n });\n }\n\n /**\n * Start a multipart upload whose every part must carry a SHA-256.\n *\n * Storage class and tags belong to the upload, not to its parts, so they are\n * fixed here, by the signer, and no part's PUT can change them.\n */\n async createMultipartUpload(key: string, options?: MultipartUploadOptions): Promise<string> {\n const response = await this.getClient().send(\n new CreateMultipartUploadCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n ChecksumAlgorithm: \"SHA256\",\n ...(options?.contentType ? { ContentType: options.contentType } : {}),\n ...(options?.storageClass\n ? { StorageClass: options.storageClass as PutObjectCommandInput[\"StorageClass\"] }\n : {}),\n ...(options?.tagging ? { Tagging: encodeTagging(options.tagging) } : {}),\n }),\n );\n if (!response.UploadId) throw new Error(`CreateMultipartUpload ${key} returned no upload id`);\n return response.UploadId;\n }\n\n /**\n * Presign one part's PUT with its SHA-256 bound into the signature as a\n * header, exactly as {@link getSignedPutUrl} binds a whole object's. S3 then\n * refuses a part whose bytes hash to anything else.\n */\n async getSignedUploadPartUrl(\n key: string,\n uploadId: string,\n partNumber: number,\n options: { readonly checksumSha256: string; readonly expiresIn?: number },\n ): Promise<string> {\n const command = new UploadPartCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n UploadId: uploadId,\n PartNumber: partNumber,\n ChecksumSHA256: options.checksumSha256,\n });\n const pinned = new Set([\"x-amz-checksum-sha256\"]);\n return awsGetSignedUrl(this.getClient(), command, {\n expiresIn: options.expiresIn ?? 3600,\n signableHeaders: pinned,\n unhoistableHeaders: new Set(pinned),\n });\n }\n\n async completeMultipartUpload(\n key: string,\n uploadId: string,\n parts: readonly CompletedPart[],\n ): Promise<void> {\n await this.getClient().send(\n new CompleteMultipartUploadCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n UploadId: uploadId,\n MultipartUpload: {\n Parts: parts.map((p) => ({\n PartNumber: p.partNumber,\n ETag: p.etag,\n ChecksumSHA256: p.checksumSha256,\n })),\n },\n }),\n );\n }\n}\n\n/**\n * Map HEAD's storage-class / archive-status / restore triple onto whether the\n * bytes can be read right now.\n *\n * The three inputs disagree in a way that matters: an Intelligent-Tiering\n * object reports `StorageClass: INTELLIGENT_TIERING` whether or not it has sunk\n * into an async archive tier — only `ArchiveStatus` says which. Reading storage\n * class alone would call a DEEP_ARCHIVE_ACCESS object instantly readable.\n *\n * (Our bucket must never enable I-T's async tiers, so `ArchiveStatus` should\n * always be absent in practice. It is handled anyway because \"should\" is doing\n * a lot of work there, and the failure mode of ignoring it is a read that hangs\n * for 12 hours.)\n */\nfunction availabilityOf(\n storageClass: string,\n archiveStatus: string | null,\n restore: string | null,\n): ObjectAvailability {\n const archivedTier =\n storageClass === \"GLACIER\" || storageClass === \"DEEP_ARCHIVE\"\n ? storageClass\n : archiveStatus === \"ARCHIVE_ACCESS\" || archiveStatus === \"DEEP_ARCHIVE_ACCESS\"\n ? archiveStatus\n : null;\n if (!archivedTier) return { state: \"instant\" };\n\n // Restore header forms:\n // ongoing-request=\"true\" → restore in flight\n // ongoing-request=\"false\", expiry-date=\"<http-date>\" → temporarily readable\n // (absent) → not restored\n if (restore) {\n if (/ongoing-request=\"true\"/.test(restore)) {\n return { state: \"restoring\", readyAt: null };\n }\n if (/ongoing-request=\"false\"/.test(restore)) {\n // A restored copy exists and is readable until its expiry. Callers that\n // care when it lapses read `storageClass`; for \"can I read it now\" the\n // answer is simply yes.\n return { state: \"instant\" };\n }\n }\n\n return {\n state: \"archived\",\n tier: archivedTier,\n // Standard-tier retrieval, which is what the restore flow requests. Bulk is\n // cheaper by hundredths of a cent and slower by a day and a half, so it is\n // only used for batch restores.\n expectedLatencyHours:\n archivedTier === \"DEEP_ARCHIVE\" || archivedTier === \"DEEP_ARCHIVE_ACCESS\" ? 12 : 5,\n };\n}\n\n/**\n * S3 takes object tags as a URL-encoded query string, not JSON.\n *\n * Encoded here rather than by callers because the keys involved contain a\n * colon (`starkeep:intent`), which survives naive concatenation and then fails\n * signature validation in a way that reports only \"SignatureDoesNotMatch\".\n */\nfunction encodeTagging(tags: Record<string, string>): string {\n return Object.entries(tags)\n .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)\n .join(\"&\");\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":["import_promises","awsGetSignedUrl"]}
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { ObjectStorageAdapter, PutOptions, ByteRange, PutStreamOptions, GetResult, ObjectFacts, ListOptions, ListResult, SignedUrlOptions, SignedPutUrlOptions } from '@starkeep/storage-adapter';
1
+ import { ObjectStorageAdapter, PutOptions, ByteRange, PutStreamOptions, GetResult, ObjectFacts, ListOptions, ListResult, SignedUrlOptions, SignedPutUrlOptions, MultipartUploadOptions, CompletedPart } from '@starkeep/storage-adapter';
2
2
 
3
3
  interface S3Credentials {
4
4
  readonly accessKeyId: string;
@@ -46,6 +46,23 @@ declare class S3ObjectStorageAdapter implements ObjectStorageAdapter {
46
46
  list(prefix: string, options?: ListOptions): Promise<ListResult>;
47
47
  getSignedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
48
48
  getSignedPutUrl(key: string, options?: SignedPutUrlOptions): Promise<string>;
49
+ /**
50
+ * Start a multipart upload whose every part must carry a SHA-256.
51
+ *
52
+ * Storage class and tags belong to the upload, not to its parts, so they are
53
+ * fixed here, by the signer, and no part's PUT can change them.
54
+ */
55
+ createMultipartUpload(key: string, options?: MultipartUploadOptions): Promise<string>;
56
+ /**
57
+ * Presign one part's PUT with its SHA-256 bound into the signature as a
58
+ * header, exactly as {@link getSignedPutUrl} binds a whole object's. S3 then
59
+ * refuses a part whose bytes hash to anything else.
60
+ */
61
+ getSignedUploadPartUrl(key: string, uploadId: string, partNumber: number, options: {
62
+ readonly checksumSha256: string;
63
+ readonly expiresIn?: number;
64
+ }): Promise<string>;
65
+ completeMultipartUpload(key: string, uploadId: string, parts: readonly CompletedPart[]): Promise<void>;
49
66
  }
50
67
 
51
68
  export { S3ObjectStorageAdapter, type S3ObjectStorageAdapterOptions };
package/dist/index.d.ts CHANGED
@@ -1,4 +1,4 @@
1
- import { ObjectStorageAdapter, PutOptions, ByteRange, PutStreamOptions, GetResult, ObjectFacts, ListOptions, ListResult, SignedUrlOptions, SignedPutUrlOptions } from '@starkeep/storage-adapter';
1
+ import { ObjectStorageAdapter, PutOptions, ByteRange, PutStreamOptions, GetResult, ObjectFacts, ListOptions, ListResult, SignedUrlOptions, SignedPutUrlOptions, MultipartUploadOptions, CompletedPart } from '@starkeep/storage-adapter';
2
2
 
3
3
  interface S3Credentials {
4
4
  readonly accessKeyId: string;
@@ -46,6 +46,23 @@ declare class S3ObjectStorageAdapter implements ObjectStorageAdapter {
46
46
  list(prefix: string, options?: ListOptions): Promise<ListResult>;
47
47
  getSignedUrl(key: string, options?: SignedUrlOptions): Promise<string>;
48
48
  getSignedPutUrl(key: string, options?: SignedPutUrlOptions): Promise<string>;
49
+ /**
50
+ * Start a multipart upload whose every part must carry a SHA-256.
51
+ *
52
+ * Storage class and tags belong to the upload, not to its parts, so they are
53
+ * fixed here, by the signer, and no part's PUT can change them.
54
+ */
55
+ createMultipartUpload(key: string, options?: MultipartUploadOptions): Promise<string>;
56
+ /**
57
+ * Presign one part's PUT with its SHA-256 bound into the signature as a
58
+ * header, exactly as {@link getSignedPutUrl} binds a whole object's. S3 then
59
+ * refuses a part whose bytes hash to anything else.
60
+ */
61
+ getSignedUploadPartUrl(key: string, uploadId: string, partNumber: number, options: {
62
+ readonly checksumSha256: string;
63
+ readonly expiresIn?: number;
64
+ }): Promise<string>;
65
+ completeMultipartUpload(key: string, uploadId: string, parts: readonly CompletedPart[]): Promise<void>;
49
66
  }
50
67
 
51
68
  export { S3ObjectStorageAdapter, type S3ObjectStorageAdapterOptions };
package/dist/index.js CHANGED
@@ -8,7 +8,10 @@ import {
8
8
  HeadBucketCommand,
9
9
  HeadObjectCommand,
10
10
  PutObjectTaggingCommand,
11
- RestoreObjectCommand
11
+ RestoreObjectCommand,
12
+ CreateMultipartUploadCommand,
13
+ UploadPartCommand,
14
+ CompleteMultipartUploadCommand
12
15
  } from "@aws-sdk/client-s3";
13
16
  import { getSignedUrl as awsGetSignedUrl } from "@aws-sdk/s3-request-presigner";
14
17
  import { createHash } from "crypto";
@@ -321,6 +324,62 @@ var S3ObjectStorageAdapter = class {
321
324
  ...signableHeaders.size > 0 ? { signableHeaders, unhoistableHeaders: new Set(signableHeaders) } : {}
322
325
  });
323
326
  }
327
+ /**
328
+ * Start a multipart upload whose every part must carry a SHA-256.
329
+ *
330
+ * Storage class and tags belong to the upload, not to its parts, so they are
331
+ * fixed here, by the signer, and no part's PUT can change them.
332
+ */
333
+ async createMultipartUpload(key, options) {
334
+ const response = await this.getClient().send(
335
+ new CreateMultipartUploadCommand({
336
+ Bucket: this.options.bucketName,
337
+ Key: this.resolveKey(key),
338
+ ChecksumAlgorithm: "SHA256",
339
+ ...options?.contentType ? { ContentType: options.contentType } : {},
340
+ ...options?.storageClass ? { StorageClass: options.storageClass } : {},
341
+ ...options?.tagging ? { Tagging: encodeTagging(options.tagging) } : {}
342
+ })
343
+ );
344
+ if (!response.UploadId) throw new Error(`CreateMultipartUpload ${key} returned no upload id`);
345
+ return response.UploadId;
346
+ }
347
+ /**
348
+ * Presign one part's PUT with its SHA-256 bound into the signature as a
349
+ * header, exactly as {@link getSignedPutUrl} binds a whole object's. S3 then
350
+ * refuses a part whose bytes hash to anything else.
351
+ */
352
+ async getSignedUploadPartUrl(key, uploadId, partNumber, options) {
353
+ const command = new UploadPartCommand({
354
+ Bucket: this.options.bucketName,
355
+ Key: this.resolveKey(key),
356
+ UploadId: uploadId,
357
+ PartNumber: partNumber,
358
+ ChecksumSHA256: options.checksumSha256
359
+ });
360
+ const pinned = /* @__PURE__ */ new Set(["x-amz-checksum-sha256"]);
361
+ return awsGetSignedUrl(this.getClient(), command, {
362
+ expiresIn: options.expiresIn ?? 3600,
363
+ signableHeaders: pinned,
364
+ unhoistableHeaders: new Set(pinned)
365
+ });
366
+ }
367
+ async completeMultipartUpload(key, uploadId, parts) {
368
+ await this.getClient().send(
369
+ new CompleteMultipartUploadCommand({
370
+ Bucket: this.options.bucketName,
371
+ Key: this.resolveKey(key),
372
+ UploadId: uploadId,
373
+ MultipartUpload: {
374
+ Parts: parts.map((p) => ({
375
+ PartNumber: p.partNumber,
376
+ ETag: p.etag,
377
+ ChecksumSHA256: p.checksumSha256
378
+ }))
379
+ }
380
+ })
381
+ );
382
+ }
324
383
  };
325
384
  function availabilityOf(storageClass, archiveStatus, restore) {
326
385
  const archivedTier = storageClass === "GLACIER" || storageClass === "DEEP_ARCHIVE" ? storageClass : archiveStatus === "ARCHIVE_ACCESS" || archiveStatus === "DEEP_ARCHIVE_ACCESS" ? archiveStatus : null;
package/dist/index.js.map CHANGED
@@ -1 +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 PutObjectTaggingCommand,\n RestoreObjectCommand,\n} from \"@aws-sdk/client-s3\";\nimport type { PutObjectCommandInput } from \"@aws-sdk/client-s3\";\nimport { getSignedUrl as awsGetSignedUrl } from \"@aws-sdk/s3-request-presigner\";\nimport { createHash } from \"node:crypto\";\nimport { createReadStream, createWriteStream } from \"node:fs\";\nimport { mkdtemp, rm } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { Readable } from \"node:stream\";\nimport { pipeline } from \"node:stream/promises\";\nimport type { ObjectStorageAdapter } from \"@starkeep/storage-adapter\";\nimport type {\n ByteRange,\n PutOptions,\n GetResult,\n ListOptions,\n ListResult,\n ObjectAvailability,\n ObjectFacts,\n PutStreamOptions,\n SignedUrlOptions,\n SignedPutUrlOptions,\n} from \"@starkeep/storage-adapter\";\nimport type { S3ObjectStorageAdapterOptions } from \"./types.js\";\n\n/**\n * The largest object one PutObject request may carry.\n *\n * Every object this adapter writes goes up in one request, because only a\n * single-request upload can carry a whole-object SHA-256. S3 stores a\n * multipart upload's SHA-256 as a composite over the parts, suffixed\n * `-<partCount>`, which is not the object's hash; full-object checksums for\n * multipart exist only for the CRC algorithms. Without a whole-object SHA-256\n * no node can prove the cloud holds a file, so \"Free up space\" could never\n * free it. The presigned uploads devices use are single requests too, so this\n * is already the largest file the system can hold.\n */\nexport const MAX_SINGLE_PUT_BYTES = 5 * 1024 ** 3;\n\nfunction sha256Base64(data: Uint8Array): string {\n return createHash(\"sha256\").update(data).digest(\"base64\");\n}\n\nfunction hexToBase64(hex: string): string {\n return Buffer.from(hex, \"hex\").toString(\"base64\");\n}\n\nfunction tooLarge(key: string, bytes: number): Error {\n return new Error(\n `${key} is ${bytes} bytes; S3 takes at most ${MAX_SINGLE_PUT_BYTES} in one request, ` +\n \"and only a single-request upload carries a whole-object SHA-256\",\n );\n}\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(new HeadBucketCommand({ Bucket: this.options.bucketName }));\n return true;\n } catch {\n return false;\n }\n }\n\n async put(key: string, data: Buffer | Uint8Array, options?: PutOptions): Promise<void> {\n const resolvedKey = this.resolveKey(key);\n const contentType = options?.contentType;\n\n if (data.byteLength > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, data.byteLength);\n await this.getClient().send(\n new PutObjectCommand({\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n Body: data,\n ...(contentType ? { ContentType: contentType } : {}),\n ...(options?.metadata ? { Metadata: options.metadata } : {}),\n // Always a whole-object SHA-256: the caller's, or one computed here\n // from the bytes in hand. S3 rejects a body that doesn't match rather\n // than storing it, so a 200 means \"S3 confirmed these bytes\", and\n // `stat()` reports a checksum a node can prove a replica against.\n ChecksumSHA256: options?.checksumSha256 ?? sha256Base64(data),\n }),\n );\n }\n\n async getStream(key: string, range?: ByteRange): Promise<ReadableStream<Uint8Array> | null> {\n try {\n const response = await this.getClient().send(\n new GetObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n // S3's Range header is inclusive at both ends and an absent end means\n // \"to the last byte\" — the same shape as ByteRange, so this is a\n // formatting change and not a semantic one.\n ...(range ? { Range: `bytes=${range.start}-${range.end ?? \"\"}` } : {}),\n }),\n );\n if (!response.Body) return null;\n // The SDK hands back a Node Readable in this runtime; the adapter\n // contract is a web ReadableStream so the same interface is\n // implementable on React Native and in a browser. `transformToWebStream`\n // is the SDK's own conversion, so no bytes are buffered here.\n return (\n response.Body as { transformToWebStream(): ReadableStream<Uint8Array> }\n ).transformToWebStream();\n } catch (error: unknown) {\n if (isMissingOrForbidden(error)) return null;\n throw error;\n }\n }\n\n async putStream(\n key: string,\n body: ReadableStream<Uint8Array>,\n options?: PutStreamOptions,\n ): Promise<void> {\n const resolvedKey = this.resolveKey(key);\n const base: PutObjectCommandInput = {\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n ...(options?.contentType ? { ContentType: options.contentType } : {}),\n ...(options?.metadata ? { Metadata: options.metadata } : {}),\n };\n\n // A known length streams straight through in one request. With the\n // expected hash, S3 checks the whole object against it; without one, the\n // SDK computes a SHA-256 as the bytes pass and S3 stores it as a\n // whole-object checksum.\n if (options?.sizeBytes !== undefined) {\n if (options.sizeBytes > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, options.sizeBytes);\n await this.getClient().send(\n new PutObjectCommand({\n ...base,\n Body: Readable.fromWeb(body as Parameters<typeof Readable.fromWeb>[0]),\n ContentLength: options.sizeBytes,\n ...(options.expectedSha256Hex\n ? { ChecksumSHA256: hexToBase64(options.expectedSha256Hex) }\n : { ChecksumAlgorithm: \"SHA256\" as const }),\n }),\n );\n return;\n }\n\n // An unknown length cannot be one request, so the bytes spool to a\n // temporary file while they hash, and go up from there with both.\n const dir = await mkdtemp(join(tmpdir(), \"starkeep-s3-put-\"));\n const path = join(dir, \"body\");\n try {\n const hash = createHash(\"sha256\");\n let bytes = 0;\n await pipeline(\n Readable.fromWeb(body as Parameters<typeof Readable.fromWeb>[0]),\n async function* (source: AsyncIterable<Uint8Array>) {\n for await (const chunk of source) {\n hash.update(chunk);\n bytes += chunk.byteLength;\n if (bytes > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, bytes);\n yield chunk;\n }\n },\n createWriteStream(path),\n );\n const digest = hash.digest();\n if (options?.expectedSha256Hex && digest.toString(\"hex\") !== options.expectedSha256Hex) {\n throw new Error(\n `${key}: the streamed bytes hash to ${digest.toString(\"hex\")}, not ${options.expectedSha256Hex}`,\n );\n }\n await this.getClient().send(\n new PutObjectCommand({\n ...base,\n Body: createReadStream(path),\n ContentLength: bytes,\n ChecksumSHA256: digest.toString(\"base64\"),\n }),\n );\n } finally {\n await rm(dir, { recursive: true, force: true });\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 data-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 stat(key: string): Promise<ObjectFacts | null> {\n let response;\n try {\n response = await this.getClient().send(\n new HeadObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n // Without this S3 omits the stored checksum from the response even\n // when the object has one.\n ChecksumMode: \"ENABLED\",\n }),\n );\n } catch (error: unknown) {\n // Same 403-means-404 caveat as has(); see the comment there.\n if (isMissingOrForbidden(error)) return null;\n throw error;\n }\n\n // S3 omits StorageClass entirely for STANDARD.\n const storageClass = response.StorageClass ?? \"STANDARD\";\n return {\n sizeBytes: response.ContentLength ?? 0,\n checksumSha256: response.ChecksumSHA256 ?? null,\n storageClass,\n availability: availabilityOf(\n storageClass,\n response.ArchiveStatus ?? null,\n response.Restore ?? null,\n ),\n ...(response.ContentType ? { contentType: response.ContentType } : {}),\n ...(response.Metadata ? { metadata: response.Metadata } : {}),\n };\n }\n\n async setTags(key: string, tags: Record<string, string>): Promise<void> {\n await this.getClient().send(\n new PutObjectTaggingCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n Tagging: {\n TagSet: Object.entries(tags).map(([Key, Value]) => ({ Key, Value })),\n },\n }),\n );\n }\n\n async restoreObject(\n key: string,\n options: { tier: string; days: number },\n ): Promise<\"started\" | \"already-in-progress\"> {\n try {\n await this.getClient().send(\n new RestoreObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n RestoreRequest: {\n Days: options.days,\n GlacierJobParameters: { Tier: options.tier as \"Standard\" | \"Bulk\" | \"Expedited\" },\n },\n }),\n );\n return \"started\";\n } catch (error: unknown) {\n // S3 reports an in-flight restore as an error, not a success. Treating it\n // as a failure would make the ordinary case of two clients asking at once\n // look broken, and would tempt a caller into retrying — which cannot help\n // and costs another request.\n if ((error as Error)?.name === \"RestoreAlreadyInProgress\") {\n return \"already-in-progress\";\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((object) => (object.Key ?? \"\").slice(prefixOffset));\n\n return {\n keys,\n nextCursor: response.NextContinuationToken ?? null,\n hasMore: response.IsTruncated ?? false,\n };\n }\n\n async getSignedUrl(key: string, options?: SignedUrlOptions): 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(key: string, options?: SignedPutUrlOptions): 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 // Binds the permitted body into the signature: the holder of this URL\n // may write these exact bytes to this key and nothing else. S3 rejects a\n // mismatched body rather than storing it, so \"200\" becomes a statement\n // about the bytes and not just about the request.\n ...(options?.checksumSha256 ? { ChecksumSHA256: options.checksumSha256 } : {}),\n ...(options?.storageClass\n ? { StorageClass: options.storageClass as PutObjectCommandInput[\"StorageClass\"] }\n : {}),\n ...(options?.tagging ? { Tagging: encodeTagging(options.tagging) } : {}),\n });\n\n // An unsigned header is one the uploader can simply drop: it would upload\n // unverified bytes, into whichever storage class it liked, tagged however\n // it liked. Signing them makes sending the exact values mandatory.\n //\n // `signableHeaders` alone does NOT achieve that. The S3 presigner's default\n // is to *hoist* every `x-amz-*` header into the query string, which leaves\n // `SignedHeaders=host` — and a client that then sends the values as headers\n // (which is what \"signed header\" asks of it) gets a 403 from S3:\n //\n // AccessDenied: There were headers present in the request which were not\n // signed — x-amz-checksum-sha256, x-amz-storage-class\n //\n // `unhoistableHeaders` is what keeps them in the signature as headers. It\n // has to name the same set: hoisting wins otherwise, and the failure lands\n // on the uploader as an access error about permissions it does hold.\n const signableHeaders = new Set<string>();\n if (options?.checksumSha256) signableHeaders.add(\"x-amz-checksum-sha256\");\n if (options?.storageClass) signableHeaders.add(\"x-amz-storage-class\");\n if (options?.tagging) signableHeaders.add(\"x-amz-tagging\");\n\n return awsGetSignedUrl(this.getClient(), command, {\n expiresIn: expiresInSeconds,\n ...(signableHeaders.size > 0\n ? { signableHeaders, unhoistableHeaders: new Set(signableHeaders) }\n : {}),\n });\n }\n}\n\n/**\n * Map HEAD's storage-class / archive-status / restore triple onto whether the\n * bytes can be read right now.\n *\n * The three inputs disagree in a way that matters: an Intelligent-Tiering\n * object reports `StorageClass: INTELLIGENT_TIERING` whether or not it has sunk\n * into an async archive tier — only `ArchiveStatus` says which. Reading storage\n * class alone would call a DEEP_ARCHIVE_ACCESS object instantly readable.\n *\n * (Our bucket must never enable I-T's async tiers, so `ArchiveStatus` should\n * always be absent in practice. It is handled anyway because \"should\" is doing\n * a lot of work there, and the failure mode of ignoring it is a read that hangs\n * for 12 hours.)\n */\nfunction availabilityOf(\n storageClass: string,\n archiveStatus: string | null,\n restore: string | null,\n): ObjectAvailability {\n const archivedTier =\n storageClass === \"GLACIER\" || storageClass === \"DEEP_ARCHIVE\"\n ? storageClass\n : archiveStatus === \"ARCHIVE_ACCESS\" || archiveStatus === \"DEEP_ARCHIVE_ACCESS\"\n ? archiveStatus\n : null;\n if (!archivedTier) return { state: \"instant\" };\n\n // Restore header forms:\n // ongoing-request=\"true\" → restore in flight\n // ongoing-request=\"false\", expiry-date=\"<http-date>\" → temporarily readable\n // (absent) → not restored\n if (restore) {\n if (/ongoing-request=\"true\"/.test(restore)) {\n return { state: \"restoring\", readyAt: null };\n }\n if (/ongoing-request=\"false\"/.test(restore)) {\n // A restored copy exists and is readable until its expiry. Callers that\n // care when it lapses read `storageClass`; for \"can I read it now\" the\n // answer is simply yes.\n return { state: \"instant\" };\n }\n }\n\n return {\n state: \"archived\",\n tier: archivedTier,\n // Standard-tier retrieval, which is what the restore flow requests. Bulk is\n // cheaper by hundredths of a cent and slower by a day and a half, so it is\n // only used for batch restores.\n expectedLatencyHours:\n archivedTier === \"DEEP_ARCHIVE\" || archivedTier === \"DEEP_ARCHIVE_ACCESS\" ? 12 : 5,\n };\n}\n\n/**\n * S3 takes object tags as a URL-encoded query string, not JSON.\n *\n * Encoded here rather than by callers because the keys involved contain a\n * colon (`starkeep:intent`), which survives naive concatenation and then fails\n * signature validation in a way that reports only \"SignatureDoesNotMatch\".\n */\nfunction encodeTagging(tags: Record<string, string>): string {\n return Object.entries(tags)\n .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)\n .join(\"&\");\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":[]}
1
+ {"version":3,"sources":["../src/adapter.ts"],"sourcesContent":["import {\n S3Client,\n PutObjectCommand,\n GetObjectCommand,\n DeleteObjectCommand,\n ListObjectsV2Command,\n HeadBucketCommand,\n HeadObjectCommand,\n PutObjectTaggingCommand,\n RestoreObjectCommand,\n CreateMultipartUploadCommand,\n UploadPartCommand,\n CompleteMultipartUploadCommand,\n} from \"@aws-sdk/client-s3\";\nimport type { PutObjectCommandInput } from \"@aws-sdk/client-s3\";\nimport { getSignedUrl as awsGetSignedUrl } from \"@aws-sdk/s3-request-presigner\";\nimport { createHash } from \"node:crypto\";\nimport { createReadStream, createWriteStream } from \"node:fs\";\nimport { mkdtemp, rm } from \"node:fs/promises\";\nimport { tmpdir } from \"node:os\";\nimport { join } from \"node:path\";\nimport { Readable } from \"node:stream\";\nimport { pipeline } from \"node:stream/promises\";\nimport type { ObjectStorageAdapter } from \"@starkeep/storage-adapter\";\nimport type {\n ByteRange,\n PutOptions,\n GetResult,\n ListOptions,\n ListResult,\n ObjectAvailability,\n ObjectFacts,\n PutStreamOptions,\n SignedUrlOptions,\n SignedPutUrlOptions,\n MultipartUploadOptions,\n CompletedPart,\n} from \"@starkeep/storage-adapter\";\nimport type { S3ObjectStorageAdapterOptions } from \"./types.js\";\n\n/**\n * The largest object one PutObject request may carry.\n *\n * Every object this adapter writes itself goes up in one request, so the store\n * keeps a whole-object SHA-256 for it. A device sending a large file goes\n * through the presigned multipart trio below instead, in fixed 16 MiB parts,\n * and S3 stores a composite checksum over the parts. A node proves that\n * composite by recomputing it from its own copy (see `multipart.ts` in\n * storage-adapter), so both kinds of object can be freed.\n */\nexport const MAX_SINGLE_PUT_BYTES = 5 * 1024 ** 3;\n\nfunction sha256Base64(data: Uint8Array): string {\n return createHash(\"sha256\").update(data).digest(\"base64\");\n}\n\nfunction hexToBase64(hex: string): string {\n return Buffer.from(hex, \"hex\").toString(\"base64\");\n}\n\nfunction tooLarge(key: string, bytes: number): Error {\n return new Error(\n `${key} is ${bytes} bytes; S3 takes at most ${MAX_SINGLE_PUT_BYTES} in one request, ` +\n \"and only a single-request upload carries a whole-object SHA-256\",\n );\n}\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(new HeadBucketCommand({ Bucket: this.options.bucketName }));\n return true;\n } catch {\n return false;\n }\n }\n\n async put(key: string, data: Buffer | Uint8Array, options?: PutOptions): Promise<void> {\n const resolvedKey = this.resolveKey(key);\n const contentType = options?.contentType;\n\n if (data.byteLength > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, data.byteLength);\n await this.getClient().send(\n new PutObjectCommand({\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n Body: data,\n ...(contentType ? { ContentType: contentType } : {}),\n ...(options?.metadata ? { Metadata: options.metadata } : {}),\n // Always a whole-object SHA-256: the caller's, or one computed here\n // from the bytes in hand. S3 rejects a body that doesn't match rather\n // than storing it, so a 200 means \"S3 confirmed these bytes\", and\n // `stat()` reports a checksum a node can prove a replica against.\n ChecksumSHA256: options?.checksumSha256 ?? sha256Base64(data),\n }),\n );\n }\n\n async getStream(key: string, range?: ByteRange): Promise<ReadableStream<Uint8Array> | null> {\n try {\n const response = await this.getClient().send(\n new GetObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n // S3's Range header is inclusive at both ends and an absent end means\n // \"to the last byte\" — the same shape as ByteRange, so this is a\n // formatting change and not a semantic one.\n ...(range ? { Range: `bytes=${range.start}-${range.end ?? \"\"}` } : {}),\n }),\n );\n if (!response.Body) return null;\n // The SDK hands back a Node Readable in this runtime; the adapter\n // contract is a web ReadableStream so the same interface is\n // implementable on React Native and in a browser. `transformToWebStream`\n // is the SDK's own conversion, so no bytes are buffered here.\n return (\n response.Body as { transformToWebStream(): ReadableStream<Uint8Array> }\n ).transformToWebStream();\n } catch (error: unknown) {\n if (isMissingOrForbidden(error)) return null;\n throw error;\n }\n }\n\n async putStream(\n key: string,\n body: ReadableStream<Uint8Array>,\n options?: PutStreamOptions,\n ): Promise<void> {\n const resolvedKey = this.resolveKey(key);\n const base: PutObjectCommandInput = {\n Bucket: this.options.bucketName,\n Key: resolvedKey,\n ...(options?.contentType ? { ContentType: options.contentType } : {}),\n ...(options?.metadata ? { Metadata: options.metadata } : {}),\n };\n\n // A known length streams straight through in one request. With the\n // expected hash, S3 checks the whole object against it; without one, the\n // SDK computes a SHA-256 as the bytes pass and S3 stores it as a\n // whole-object checksum.\n if (options?.sizeBytes !== undefined) {\n if (options.sizeBytes > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, options.sizeBytes);\n await this.getClient().send(\n new PutObjectCommand({\n ...base,\n Body: Readable.fromWeb(body as Parameters<typeof Readable.fromWeb>[0]),\n ContentLength: options.sizeBytes,\n ...(options.expectedSha256Hex\n ? { ChecksumSHA256: hexToBase64(options.expectedSha256Hex) }\n : { ChecksumAlgorithm: \"SHA256\" as const }),\n }),\n );\n return;\n }\n\n // An unknown length cannot be one request, so the bytes spool to a\n // temporary file while they hash, and go up from there with both.\n const dir = await mkdtemp(join(tmpdir(), \"starkeep-s3-put-\"));\n const path = join(dir, \"body\");\n try {\n const hash = createHash(\"sha256\");\n let bytes = 0;\n await pipeline(\n Readable.fromWeb(body as Parameters<typeof Readable.fromWeb>[0]),\n async function* (source: AsyncIterable<Uint8Array>) {\n for await (const chunk of source) {\n hash.update(chunk);\n bytes += chunk.byteLength;\n if (bytes > MAX_SINGLE_PUT_BYTES) throw tooLarge(key, bytes);\n yield chunk;\n }\n },\n createWriteStream(path),\n );\n const digest = hash.digest();\n if (options?.expectedSha256Hex && digest.toString(\"hex\") !== options.expectedSha256Hex) {\n throw new Error(\n `${key}: the streamed bytes hash to ${digest.toString(\"hex\")}, not ${options.expectedSha256Hex}`,\n );\n }\n await this.getClient().send(\n new PutObjectCommand({\n ...base,\n Body: createReadStream(path),\n ContentLength: bytes,\n ChecksumSHA256: digest.toString(\"base64\"),\n }),\n );\n } finally {\n await rm(dir, { recursive: true, force: true });\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 data-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 stat(key: string): Promise<ObjectFacts | null> {\n let response;\n try {\n response = await this.getClient().send(\n new HeadObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n // Without this S3 omits the stored checksum from the response even\n // when the object has one.\n ChecksumMode: \"ENABLED\",\n }),\n );\n } catch (error: unknown) {\n // Same 403-means-404 caveat as has(); see the comment there.\n if (isMissingOrForbidden(error)) return null;\n throw error;\n }\n\n // S3 omits StorageClass entirely for STANDARD.\n const storageClass = response.StorageClass ?? \"STANDARD\";\n return {\n sizeBytes: response.ContentLength ?? 0,\n checksumSha256: response.ChecksumSHA256 ?? null,\n storageClass,\n availability: availabilityOf(\n storageClass,\n response.ArchiveStatus ?? null,\n response.Restore ?? null,\n ),\n ...(response.ContentType ? { contentType: response.ContentType } : {}),\n ...(response.Metadata ? { metadata: response.Metadata } : {}),\n };\n }\n\n async setTags(key: string, tags: Record<string, string>): Promise<void> {\n await this.getClient().send(\n new PutObjectTaggingCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n Tagging: {\n TagSet: Object.entries(tags).map(([Key, Value]) => ({ Key, Value })),\n },\n }),\n );\n }\n\n async restoreObject(\n key: string,\n options: { tier: string; days: number },\n ): Promise<\"started\" | \"already-in-progress\"> {\n try {\n await this.getClient().send(\n new RestoreObjectCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n RestoreRequest: {\n Days: options.days,\n GlacierJobParameters: { Tier: options.tier as \"Standard\" | \"Bulk\" | \"Expedited\" },\n },\n }),\n );\n return \"started\";\n } catch (error: unknown) {\n // S3 reports an in-flight restore as an error, not a success. Treating it\n // as a failure would make the ordinary case of two clients asking at once\n // look broken, and would tempt a caller into retrying — which cannot help\n // and costs another request.\n if ((error as Error)?.name === \"RestoreAlreadyInProgress\") {\n return \"already-in-progress\";\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((object) => (object.Key ?? \"\").slice(prefixOffset));\n\n return {\n keys,\n nextCursor: response.NextContinuationToken ?? null,\n hasMore: response.IsTruncated ?? false,\n };\n }\n\n async getSignedUrl(key: string, options?: SignedUrlOptions): 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(key: string, options?: SignedPutUrlOptions): 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 // Binds the permitted body into the signature: the holder of this URL\n // may write these exact bytes to this key and nothing else. S3 rejects a\n // mismatched body rather than storing it, so \"200\" becomes a statement\n // about the bytes and not just about the request.\n ...(options?.checksumSha256 ? { ChecksumSHA256: options.checksumSha256 } : {}),\n ...(options?.storageClass\n ? { StorageClass: options.storageClass as PutObjectCommandInput[\"StorageClass\"] }\n : {}),\n ...(options?.tagging ? { Tagging: encodeTagging(options.tagging) } : {}),\n });\n\n // An unsigned header is one the uploader can simply drop: it would upload\n // unverified bytes, into whichever storage class it liked, tagged however\n // it liked. Signing them makes sending the exact values mandatory.\n //\n // `signableHeaders` alone does NOT achieve that. The S3 presigner's default\n // is to *hoist* every `x-amz-*` header into the query string, which leaves\n // `SignedHeaders=host` — and a client that then sends the values as headers\n // (which is what \"signed header\" asks of it) gets a 403 from S3:\n //\n // AccessDenied: There were headers present in the request which were not\n // signed — x-amz-checksum-sha256, x-amz-storage-class\n //\n // `unhoistableHeaders` is what keeps them in the signature as headers. It\n // has to name the same set: hoisting wins otherwise, and the failure lands\n // on the uploader as an access error about permissions it does hold.\n const signableHeaders = new Set<string>();\n if (options?.checksumSha256) signableHeaders.add(\"x-amz-checksum-sha256\");\n if (options?.storageClass) signableHeaders.add(\"x-amz-storage-class\");\n if (options?.tagging) signableHeaders.add(\"x-amz-tagging\");\n\n return awsGetSignedUrl(this.getClient(), command, {\n expiresIn: expiresInSeconds,\n ...(signableHeaders.size > 0\n ? { signableHeaders, unhoistableHeaders: new Set(signableHeaders) }\n : {}),\n });\n }\n\n /**\n * Start a multipart upload whose every part must carry a SHA-256.\n *\n * Storage class and tags belong to the upload, not to its parts, so they are\n * fixed here, by the signer, and no part's PUT can change them.\n */\n async createMultipartUpload(key: string, options?: MultipartUploadOptions): Promise<string> {\n const response = await this.getClient().send(\n new CreateMultipartUploadCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n ChecksumAlgorithm: \"SHA256\",\n ...(options?.contentType ? { ContentType: options.contentType } : {}),\n ...(options?.storageClass\n ? { StorageClass: options.storageClass as PutObjectCommandInput[\"StorageClass\"] }\n : {}),\n ...(options?.tagging ? { Tagging: encodeTagging(options.tagging) } : {}),\n }),\n );\n if (!response.UploadId) throw new Error(`CreateMultipartUpload ${key} returned no upload id`);\n return response.UploadId;\n }\n\n /**\n * Presign one part's PUT with its SHA-256 bound into the signature as a\n * header, exactly as {@link getSignedPutUrl} binds a whole object's. S3 then\n * refuses a part whose bytes hash to anything else.\n */\n async getSignedUploadPartUrl(\n key: string,\n uploadId: string,\n partNumber: number,\n options: { readonly checksumSha256: string; readonly expiresIn?: number },\n ): Promise<string> {\n const command = new UploadPartCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n UploadId: uploadId,\n PartNumber: partNumber,\n ChecksumSHA256: options.checksumSha256,\n });\n const pinned = new Set([\"x-amz-checksum-sha256\"]);\n return awsGetSignedUrl(this.getClient(), command, {\n expiresIn: options.expiresIn ?? 3600,\n signableHeaders: pinned,\n unhoistableHeaders: new Set(pinned),\n });\n }\n\n async completeMultipartUpload(\n key: string,\n uploadId: string,\n parts: readonly CompletedPart[],\n ): Promise<void> {\n await this.getClient().send(\n new CompleteMultipartUploadCommand({\n Bucket: this.options.bucketName,\n Key: this.resolveKey(key),\n UploadId: uploadId,\n MultipartUpload: {\n Parts: parts.map((p) => ({\n PartNumber: p.partNumber,\n ETag: p.etag,\n ChecksumSHA256: p.checksumSha256,\n })),\n },\n }),\n );\n }\n}\n\n/**\n * Map HEAD's storage-class / archive-status / restore triple onto whether the\n * bytes can be read right now.\n *\n * The three inputs disagree in a way that matters: an Intelligent-Tiering\n * object reports `StorageClass: INTELLIGENT_TIERING` whether or not it has sunk\n * into an async archive tier — only `ArchiveStatus` says which. Reading storage\n * class alone would call a DEEP_ARCHIVE_ACCESS object instantly readable.\n *\n * (Our bucket must never enable I-T's async tiers, so `ArchiveStatus` should\n * always be absent in practice. It is handled anyway because \"should\" is doing\n * a lot of work there, and the failure mode of ignoring it is a read that hangs\n * for 12 hours.)\n */\nfunction availabilityOf(\n storageClass: string,\n archiveStatus: string | null,\n restore: string | null,\n): ObjectAvailability {\n const archivedTier =\n storageClass === \"GLACIER\" || storageClass === \"DEEP_ARCHIVE\"\n ? storageClass\n : archiveStatus === \"ARCHIVE_ACCESS\" || archiveStatus === \"DEEP_ARCHIVE_ACCESS\"\n ? archiveStatus\n : null;\n if (!archivedTier) return { state: \"instant\" };\n\n // Restore header forms:\n // ongoing-request=\"true\" → restore in flight\n // ongoing-request=\"false\", expiry-date=\"<http-date>\" → temporarily readable\n // (absent) → not restored\n if (restore) {\n if (/ongoing-request=\"true\"/.test(restore)) {\n return { state: \"restoring\", readyAt: null };\n }\n if (/ongoing-request=\"false\"/.test(restore)) {\n // A restored copy exists and is readable until its expiry. Callers that\n // care when it lapses read `storageClass`; for \"can I read it now\" the\n // answer is simply yes.\n return { state: \"instant\" };\n }\n }\n\n return {\n state: \"archived\",\n tier: archivedTier,\n // Standard-tier retrieval, which is what the restore flow requests. Bulk is\n // cheaper by hundredths of a cent and slower by a day and a half, so it is\n // only used for batch restores.\n expectedLatencyHours:\n archivedTier === \"DEEP_ARCHIVE\" || archivedTier === \"DEEP_ARCHIVE_ACCESS\" ? 12 : 5,\n };\n}\n\n/**\n * S3 takes object tags as a URL-encoded query string, not JSON.\n *\n * Encoded here rather than by callers because the keys involved contain a\n * colon (`starkeep:intent`), which survives naive concatenation and then fails\n * signature validation in a way that reports only \"SignatureDoesNotMatch\".\n */\nfunction encodeTagging(tags: Record<string, string>): string {\n return Object.entries(tags)\n .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)\n .join(\"&\");\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 CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@starkeep/storage-s3",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -29,7 +29,7 @@
29
29
  "dependencies": {
30
30
  "@aws-sdk/client-s3": "^3.700.0",
31
31
  "@aws-sdk/s3-request-presigner": "^3.700.0",
32
- "@starkeep/storage-adapter": "0.5.0"
32
+ "@starkeep/storage-adapter": "0.6.0"
33
33
  },
34
34
  "devDependencies": {
35
35
  "@types/node": "^25.4.0",