s3mini 0.3.0 → 0.4.0

package/src/S3.ts

@@ -27,7 +27,7 @@ import * as U from './utils.js';
  * // Delete a file
  * await s3.deleteObject('example.txt');
  */
-class s3mini {
+class S3mini {
   /**
    * Creates an instance of the S3 class.
    *
@@ -260,8 +260,17 @@ class s3mini {
     headers[C.HEADER_AMZ_CONTENT_SHA256] = C.UNSIGNED_PAYLOAD; // body ? U.hash(body) : C.UNSIGNED_PAYLOAD;
     headers[C.HEADER_AMZ_DATE] = fullDatetime;
     headers[C.HEADER_HOST] = url.host;
-    const canonicalHeaders = this._buildCanonicalHeaders(headers);
-    const signedHeaders = Object.keys(headers)
+    // sort headers alphabetically by key
+    const ignoredHeaders = ['authorization', 'content-length', 'content-type', 'user-agent'];
+    let headersForSigning = Object.fromEntries(
+      Object.entries(headers).filter(([key]) => !ignoredHeaders.includes(key.toLowerCase())),
+    );
+
+    headersForSigning = Object.fromEntries(
+      Object.entries(headersForSigning).sort(([keyA], [keyB]) => keyA.localeCompare(keyB)),
+    );
+    const canonicalHeaders = this._buildCanonicalHeaders(headersForSigning);
+    const signedHeaders = Object.keys(headersForSigning)
       .map(key => key.toLowerCase())
       .sort()
       .join(';');
@@ -277,7 +286,6 @@ class s3mini {
   private _buildCanonicalHeaders(headers: Record<string, string | number>): string {
     return Object.entries(headers)
       .map(([key, value]) => `${key.toLowerCase()}:${String(value).trim()}`)
-      .sort()
       .join('\n');
   }
 
@@ -288,14 +296,15 @@ class s3mini {
     canonicalHeaders: string,
     signedHeaders: string,
   ): string {
-    return [
+    const parts = [
       method,
       url.pathname,
       this._buildCanonicalQueryString(query),
-      `${canonicalHeaders}\n`,
+      canonicalHeaders + '\n', // Canonical headers end with extra newline
       signedHeaders,
       C.UNSIGNED_PAYLOAD,
-    ].join('\n');
+    ];
+    return parts.join('\n');
   }
 
   private _buildCredentialScope(shortDatetime: string): string {
@@ -332,9 +341,9 @@ class s3mini {
       tolerated = [], // [200, 404] etc.
       withQuery = false, // append query string to signed URL
     }: {
-      query?: Record<string, unknown>;
+      query?: Record<string, unknown> | undefined;
       body?: string | Buffer | undefined;
-      headers?: Record<string, string | number | undefined>;
+      headers?: Record<string, string | number | undefined> | IT.SSECHeaders | undefined;
       tolerated?: number[] | undefined;
       withQuery?: boolean | undefined;
     } = {},
@@ -343,14 +352,10 @@ class s3mini {
     if (!['GET', 'HEAD', 'PUT', 'POST', 'DELETE'].includes(method)) {
       throw new Error(`${C.ERROR_PREFIX}Unsupported HTTP method ${method as string}`);
     }
-    if (key) {
-      this._checkKey(key); // allow '' for bucket‑level
-    }
 
     const { filteredOpts, conditionalHeaders } = ['GET', 'HEAD'].includes(method)
       ? this._filterIfHeaders(query)
       : { filteredOpts: query, conditionalHeaders: {} };
-
     const baseHeaders: Record<string, string | number> = {
       [C.HEADER_AMZ_CONTENT_SHA256]: C.UNSIGNED_PAYLOAD,
       // ...(['GET', 'HEAD'].includes(method) ? { [C.HEADER_CONTENT_TYPE]: C.JSON_CONTENT_TYPE } : {}),
@@ -475,7 +480,7 @@ class s3mini {
    * @param {string} [prefix=''] - The prefix to filter objects by.
    * @param {number} [maxKeys] - The maximum number of keys to return. If not provided, all keys will be returned.
    * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
-   * @returns {Promise<object[] | null>} A promise that resolves to an array of objects or null if the bucket is empty.
+   * @returns {Promise<IT.ListObject[] | null>} A promise that resolves to an array of objects or null if the bucket is empty.
    * @example
    * // List all objects
    * const objects = await s3.listObjects();
@@ -489,7 +494,7 @@ class s3mini {
     maxKeys?: number,
     // method: IT.HttpMethod = 'GET', // 'GET' or 'HEAD'
     opts: Record<string, unknown> = {},
-  ): Promise<object[] | null> {
+  ): Promise<IT.ListObject[] | null> {
     this._checkDelimiter(delimiter);
     this._checkPrefix(prefix);
     this._checkOpts(opts);
@@ -499,7 +504,7 @@ class s3mini {
     const unlimited = !(maxKeys && maxKeys > 0);
     let remaining = unlimited ? Infinity : maxKeys;
     let token: string | undefined;
-    const all: object[] = [];
+    const all: IT.ListObject[] = [];
 
     do {
       const batchSize = Math.min(remaining, 1000); // S3 ceiling
@@ -542,7 +547,7 @@ class s3mini {
       const contents = out.Contents || out.contents; // S3 v2 vs v1
       if (contents) {
         const batch = Array.isArray(contents) ? contents : [contents];
-        all.push(...(batch as object[]));
+        all.push(...(batch as IT.ListObject[]));
         if (!unlimited) {
           remaining -= batch.length;
         }
@@ -607,11 +612,21 @@ class s3mini {
    * Get an object from the S3-compatible service.
    * This method sends a request to retrieve the specified object from the S3-compatible service.
    * @param {string} key - The key of the object to retrieve.
-   * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+   * @param {Record<string, unknown>} [opts] - Additional options for the request.
+   * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
    * @returns A promise that resolves to the object data (string) or null if not found.
    */
-  public async getObject(key: string, opts: Record<string, unknown> = {}): Promise<string | null> {
-    const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+  public async getObject(
+    key: string,
+    opts: Record<string, unknown> = {},
+    ssecHeaders?: IT.SSECHeaders,
+  ): Promise<string | null> {
+    // if ssecHeaders is set, add it to headers
+    const res = await this._signedRequest('GET', key, {
+      query: opts, // use opts.query if it exists, otherwise use an empty object
+      tolerated: [200, 404, 412, 304],
+      headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+    });
     if ([404, 412, 304].includes(res.status)) {
       return null;
     }
@@ -623,10 +638,19 @@ class s3mini {
    * This method sends a request to retrieve the specified object and returns the full response.
    * @param {string} key - The key of the object to retrieve.
    * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+   * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
    * @returns A promise that resolves to the Response object or null if not found.
    */
-  public async getObjectResponse(key: string, opts: Record<string, unknown> = {}): Promise<Response | null> {
-    const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+  public async getObjectResponse(
+    key: string,
+    opts: Record<string, unknown> = {},
+    ssecHeaders?: IT.SSECHeaders,
+  ): Promise<Response | null> {
+    const res = await this._signedRequest('GET', key, {
+      query: opts,
+      tolerated: [200, 404, 412, 304],
+      headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+    });
     if ([404, 412, 304].includes(res.status)) {
       return null;
     }
@@ -638,10 +662,19 @@ class s3mini {
    * This method sends a request to retrieve the specified object and returns it as an ArrayBuffer.
    * @param {string} key - The key of the object to retrieve.
    * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+   * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
    * @returns A promise that resolves to the object data as an ArrayBuffer or null if not found.
    */
-  public async getObjectArrayBuffer(key: string, opts: Record<string, unknown> = {}): Promise<ArrayBuffer | null> {
-    const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+  public async getObjectArrayBuffer(
+    key: string,
+    opts: Record<string, unknown> = {},
+    ssecHeaders?: IT.SSECHeaders,
+  ): Promise<ArrayBuffer | null> {
+    const res = await this._signedRequest('GET', key, {
+      query: opts,
+      tolerated: [200, 404, 412, 304],
+      headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+    });
     if ([404, 412, 304].includes(res.status)) {
       return null;
     }
@@ -653,10 +686,19 @@ class s3mini {
    * This method sends a request to retrieve the specified object and returns it as JSON.
    * @param {string} key - The key of the object to retrieve.
    * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+   * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
    * @returns A promise that resolves to the object data as JSON or null if not found.
    */
-  public async getObjectJSON<T = unknown>(key: string, opts: Record<string, unknown> = {}): Promise<T | null> {
-    const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+  public async getObjectJSON<T = unknown>(
+    key: string,
+    opts: Record<string, unknown> = {},
+    ssecHeaders?: IT.SSECHeaders,
+  ): Promise<T | null> {
+    const res = await this._signedRequest('GET', key, {
+      query: opts,
+      tolerated: [200, 404, 412, 304],
+      headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+    });
     if ([404, 412, 304].includes(res.status)) {
       return null;
     }
@@ -668,14 +710,20 @@ class s3mini {
    * This method sends a request to retrieve the specified object and its ETag.
    * @param {string} key - The key of the object to retrieve.
    * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+   * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
    * @returns A promise that resolves to an object containing the ETag and the object data as an ArrayBuffer or null if not found.
    */
   public async getObjectWithETag(
     key: string,
     opts: Record<string, unknown> = {},
+    ssecHeaders?: IT.SSECHeaders,
   ): Promise<{ etag: string | null; data: ArrayBuffer | null }> {
     try {
-      const res = await this._signedRequest('GET', key, { query: opts, tolerated: [200, 404, 412, 304] });
+      const res = await this._signedRequest('GET', key, {
+        query: opts,
+        tolerated: [200, 404, 412, 304],
+        headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+      });
 
       if ([404, 412, 304].includes(res.status)) {
         return { etag: null, data: null };
@@ -700,6 +748,7 @@ class s3mini {
    * @param {number} [rangeFrom=0] - The starting byte for the range (if not whole file).
    * @param {number} [rangeTo=this.requestSizeInBytes] - The ending byte for the range (if not whole file).
    * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+   * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
    * @returns A promise that resolves to the Response object.
    */
   public async getObjectRaw(
@@ -708,12 +757,13 @@ class s3mini {
     rangeFrom = 0,
     rangeTo = this.requestSizeInBytes,
     opts: Record<string, unknown> = {},
+    ssecHeaders?: IT.SSECHeaders,
   ): Promise<Response> {
     const rangeHdr: Record<string, string | number> = wholeFile ? {} : { range: `bytes=${rangeFrom}-${rangeTo - 1}` };
 
     return this._signedRequest('GET', key, {
       query: { ...opts },
-      headers: rangeHdr,
+      headers: { ...rangeHdr, ...ssecHeaders },
       withQuery: true, // keep ?query=string behaviour
     });
   }
@@ -725,9 +775,11 @@ class s3mini {
    * @returns A promise that resolves to the content length of the object in bytes, or 0 if not found.
    * @throws {Error} If the content length header is not found in the response.
    */
-  public async getContentLength(key: string): Promise<number> {
+  public async getContentLength(key: string, ssecHeaders?: IT.SSECHeaders): Promise<number> {
     try {
-      const res = await this._signedRequest('HEAD', key);
+      const res = await this._signedRequest('HEAD', key, {
+        headers: ssecHeaders ? { ...ssecHeaders } : undefined,
+      });
       const len = res.headers.get(C.HEADER_CONTENT_LENGTH);
       return len ? +len : 0;
     } catch (err) {
@@ -762,6 +814,7 @@ class s3mini {
    * Retrieves the ETag of an object without downloading its content.
    * @param {string} key - The key of the object to retrieve the ETag for.
    * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+   * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
    * @returns {Promise<string | null>} A promise that resolves to the ETag value or null if the object is not found.
    * @throws {Error} If the ETag header is not found in the response.
    * @example
@@ -770,16 +823,25 @@ class s3mini {
    *   console.log(`File ETag: ${etag}`);
    * }
    */
-  public async getEtag(key: string, opts: Record<string, unknown> = {}): Promise<string | null> {
+  public async getEtag(
+    key: string,
+    opts: Record<string, unknown> = {},
+    ssecHeaders?: IT.SSECHeaders,
+  ): Promise<string | null> {
     const res = await this._signedRequest('HEAD', key, {
       query: opts,
-      tolerated: [200, 404],
+      tolerated: [200, 304, 404, 412],
+      headers: ssecHeaders ? { ...ssecHeaders } : undefined,
     });
 
     if (res.status === 404) {
       return null;
     }
 
+    if (res.status === 412 || res.status === 304) {
+      return null; // ETag mismatch
+    }
+
     const etag = res.headers.get(C.HEADER_ETAG);
     if (!etag) {
       throw new Error(`${C.ERROR_PREFIX}ETag not found in response headers`);
@@ -793,6 +855,7 @@ class s3mini {
    * @param {string} key - The key/path where the object will be stored.
    * @param {string | Buffer} data - The data to upload (string or Buffer).
    * @param {string} [fileType='application/octet-stream'] - The MIME type of the file.
+   * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
    * @returns {Promise<Response>} A promise that resolves to the Response object from the upload request.
    * @throws {TypeError} If data is not a string or Buffer.
    * @example
@@ -807,6 +870,7 @@ class s3mini {
     key: string,
     data: string | Buffer,
     fileType: string = C.DEFAULT_STREAM_CONTENT_TYPE,
+    ssecHeaders?: IT.SSECHeaders,
   ): Promise<Response> {
     if (!(data instanceof Buffer || typeof data === 'string')) {
       throw new TypeError(C.ERROR_DATA_BUFFER_REQUIRED);
@@ -816,6 +880,7 @@ class s3mini {
       headers: {
         [C.HEADER_CONTENT_LENGTH]: typeof data === 'string' ? Buffer.byteLength(data) : data.length,
         [C.HEADER_CONTENT_TYPE]: fileType,
+        ...ssecHeaders,
       },
       tolerated: [200],
     });
@@ -825,6 +890,7 @@ class s3mini {
    * Initiates a multipart upload and returns the upload ID.
    * @param {string} key - The key/path where the object will be stored.
    * @param {string} [fileType='application/octet-stream'] - The MIME type of the file.
+   * @param {IT.SSECHeaders?} [ssecHeaders] - Server-Side Encryption headers, if any.
    * @returns {Promise<string>} A promise that resolves to the upload ID for the multipart upload.
    * @throws {TypeError} If key is invalid or fileType is not a string.
    * @throws {Error} If the multipart upload fails to initialize.
@@ -832,13 +898,17 @@ class s3mini {
    * const uploadId = await s3.getMultipartUploadId('large-file.zip', 'application/zip');
    * console.log(`Started multipart upload: ${uploadId}`);
    */
-  public async getMultipartUploadId(key: string, fileType: string = C.DEFAULT_STREAM_CONTENT_TYPE): Promise<string> {
+  public async getMultipartUploadId(
+    key: string,
+    fileType: string = C.DEFAULT_STREAM_CONTENT_TYPE,
+    ssecHeaders?: IT.SSECHeaders,
+  ): Promise<string> {
     this._checkKey(key);
     if (typeof fileType !== 'string') {
       throw new TypeError(`${C.ERROR_PREFIX}fileType must be a string`);
     }
     const query = { uploads: '' };
-    const headers = { [C.HEADER_CONTENT_TYPE]: fileType };
+    const headers = { [C.HEADER_CONTENT_TYPE]: fileType, ...ssecHeaders };
 
     const res = await this._signedRequest('POST', key, {
       query,
@@ -883,6 +953,7 @@ class s3mini {
    * @param {Buffer | string} data - The data for this part.
    * @param {number} partNumber - The part number (must be between 1 and 10,000).
    * @param {Record<string, unknown>} [opts={}] - Additional options for the request.
+   * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
    * @returns {Promise<IT.UploadPart>} A promise that resolves to an object containing the partNumber and etag.
    * @throws {TypeError} If any parameter is invalid.
    * @example
@@ -900,6 +971,7 @@ class s3mini {
     data: Buffer | string,
     partNumber: number,
     opts: Record<string, unknown> = {},
+    ssecHeaders?: IT.SSECHeaders,
   ): Promise<IT.UploadPart> {
     this._validateUploadPartParams(key, uploadId, data, partNumber, opts);
 
@@ -907,7 +979,10 @@ class s3mini {
     const res = await this._signedRequest('PUT', key, {
       query,
       body: data,
-      headers: { [C.HEADER_CONTENT_LENGTH]: typeof data === 'string' ? Buffer.byteLength(data) : data.length },
+      headers: {
+        [C.HEADER_CONTENT_LENGTH]: typeof data === 'string' ? Buffer.byteLength(data) : data.length,
+        ...ssecHeaders,
+      },
     });
 
     return { partNumber, etag: U.sanitizeETag(res.headers.get('etag') || '') };
@@ -978,6 +1053,7 @@ class s3mini {
    * Aborts a multipart upload and removes all uploaded parts.
    * @param {string} key - The key of the object being uploaded.
    * @param {string} uploadId - The upload ID to abort.
+   * @param {IT.SSECHeaders} [ssecHeaders] - Server-Side Encryption headers, if any.
    * @returns {Promise<object>} A promise that resolves to an object containing the abort status and details.
    * @throws {TypeError} If key or uploadId is invalid.
    * @throws {Error} If the abort operation fails.
@@ -989,14 +1065,14 @@ class s3mini {
    *   console.error('Failed to abort upload:', error);
    * }
    */
-  public async abortMultipartUpload(key: string, uploadId: string): Promise<object> {
+  public async abortMultipartUpload(key: string, uploadId: string, ssecHeaders?: IT.SSECHeaders): Promise<object> {
     this._checkKey(key);
     if (!uploadId) {
       throw new TypeError(C.ERROR_UPLOAD_ID_REQUIRED);
     }
 
     const query = { uploadId };
-    const headers = { [C.HEADER_CONTENT_TYPE]: C.XML_CONTENT_TYPE };
+    const headers = { [C.HEADER_CONTENT_TYPE]: C.XML_CONTENT_TYPE, ...(ssecHeaders ? { ...ssecHeaders } : {}) };
 
     const res = await this._signedRequest('DELETE', key, {
       query,
@@ -1192,5 +1268,10 @@ class s3mini {
   }
 }
 
-export { s3mini };
-export default s3mini;
+/**
+ * @deprecated Use `S3mini` instead.
+ */
+const s3mini = S3mini;
+
+export { S3mini, s3mini };
+export default S3mini;

package/src/consts.ts

@@ -15,9 +15,9 @@ export const DEFAULT_REQUEST_SIZE_IN_BYTES = 8 * 1024 * 1024;
 export const HEADER_AMZ_CONTENT_SHA256 = 'x-amz-content-sha256';
 export const HEADER_AMZ_DATE = 'x-amz-date';
 export const HEADER_HOST = 'host';
-export const HEADER_AUTHORIZATION = 'Authorization';
-export const HEADER_CONTENT_TYPE = 'Content-Type';
-export const HEADER_CONTENT_LENGTH = 'Content-Length';
+export const HEADER_AUTHORIZATION = 'authorization';
+export const HEADER_CONTENT_TYPE = 'content-type';
+export const HEADER_CONTENT_LENGTH = 'content-length';
 export const HEADER_ETAG = 'etag';
 export const HEADER_LAST_MODIFIED = 'last-modified';
 

package/src/index.ts

@@ -1,11 +1,11 @@
 'use strict';
 
-import { s3mini } from './S3.js';
+import { S3mini, s3mini } from './S3.js';
 import { sanitizeETag, runInBatches } from './utils.js';
 
 // Export the S3 class as default export and named export
-export { s3mini, sanitizeETag, runInBatches };
-export default s3mini;
+export { S3mini, s3mini, sanitizeETag, runInBatches };
+export default S3mini;
 
 // Re-export types
 export type {

package/src/types.ts

@@ -8,6 +8,12 @@ export interface S3Config {
   logger?: Logger;
 }
 
+export interface SSECHeaders {
+  'x-amz-server-side-encryption-customer-algorithm': string;
+  'x-amz-server-side-encryption-customer-key': string;
+  'x-amz-server-side-encryption-customer-key-md5': string;
+}
+
 export interface Crypto {
   createHmac: (
     algorithm: string,
@@ -33,6 +39,14 @@ export interface UploadPart {
   etag: string;
 }
 
+export interface ListObject {
+  Key: string;
+  Size: number;
+  LastModified: Date;
+  ETag: string;
+  StorageClass: string;
+}
+
 export interface CompleteMultipartUploadResult {
   location: string;
   bucket: string;

package/src/utils.ts

@@ -1,5 +1,4 @@
 'use strict';
-
 import type { Crypto, XmlValue, XmlMap, ListBucketResponse, ErrorWithCode } from './types.js';
 declare const crypto: Crypto;