@twin.org/blob-storage-connector-aws-s3 0.0.2-next.3 → 0.0.2-next.5

package/README.md

@@ -13,7 +13,7 @@ npm install @twin.org/blob-storage-connector-aws-s3
 The tests developed are functional tests and need an instance of AWS S3 up and running. To run AWS S3 locally using local stack:
 
 ```shell
-docker run -p 4566:4566 -p 4510-4559:4510-4559 --name twin-blob-aws-s3 -d localstack/localstack -e AWS_DEFAULT_REGION='eu-central-1' -e AWS_ACCESS_KEY_ID='test' -e AWS_SECRET_ACCESS_KEY='test' -e SERVICE='S3'
+docker run -p 4566:4566 --name twin-blob-aws-s3 -d localstack/localstack -e AWS_DEFAULT_REGION='eu-central-1' -e AWS_ACCESS_KEY_ID='test' -e AWS_SECRET_ACCESS_KEY='test' -e SERVICE='S3'
 ```
 
 Afterwards you can run the tests as follows:

package/dist/cjs/index.cjs

@@ -18,7 +18,7 @@ class S3BlobStorageConnector {
     /**
      * Runtime name for the class.
      */
-    CLASS_NAME = "S3BlobStorageConnector";
+    static CLASS_NAME = "S3BlobStorageConnector";
     /**
      * The configuration for the connector.
      * @internal
@@ -34,20 +34,25 @@ class S3BlobStorageConnector {
      * @param options The options for the connector.
      */
     constructor(options) {
-        core.Guards.object(this.CLASS_NAME, "options", options);
-        core.Guards.object(this.CLASS_NAME, "options.config", options.config);
-        core.Guards.stringValue(this.CLASS_NAME, "options.config.region", options.config.region);
-        core.Guards.stringValue(this.CLASS_NAME, "options.config.bucketName", options.config.bucketName);
-        core.Guards.stringValue(this.CLASS_NAME, "options.config.accessKeyId", options.config.accessKeyId);
-        core.Guards.stringValue(this.CLASS_NAME, "options.config.secretAccessKey", options.config.secretAccessKey);
+        core.Guards.object(S3BlobStorageConnector.CLASS_NAME, "options", options);
+        core.Guards.object(S3BlobStorageConnector.CLASS_NAME, "options.config", options.config);
+        core.Guards.stringValue(S3BlobStorageConnector.CLASS_NAME, "options.config.region", options.config.region);
+        core.Guards.stringValue(S3BlobStorageConnector.CLASS_NAME, "options.config.bucketName", options.config.bucketName);
+        options.config.authMode ??= "credentials";
+        let credentials;
+        if (options.config.authMode === "credentials") {
+            core.Guards.stringValue(S3BlobStorageConnector.CLASS_NAME, "options.config.accessKeyId", options.config.accessKeyId);
+            core.Guards.stringValue(S3BlobStorageConnector.CLASS_NAME, "options.config.secretAccessKey", options.config.secretAccessKey);
+            credentials = {
+                accessKeyId: options.config.accessKeyId,
+                secretAccessKey: options.config.secretAccessKey
+            };
+        }
         this._config = options.config;
         this._s3Client = new clientS3.S3Client({
             region: this._config.region,
             endpoint: this._config.endpoint,
-            credentials: {
-                accessKeyId: this._config.accessKeyId,
-                secretAccessKey: this._config.secretAccessKey
-            },
+            credentials,
             forcePathStyle: true
         });
     }
@@ -61,7 +66,7 @@ class S3BlobStorageConnector {
         try {
             await nodeLogging?.log({
                 level: "info",
-                source: this.CLASS_NAME,
+                source: S3BlobStorageConnector.CLASS_NAME,
                 message: "bucketCreating",
                 data: {
                     bucket: this._config.bucketName
@@ -73,7 +78,7 @@ class S3BlobStorageConnector {
             if (bucketExists) {
                 await nodeLogging?.log({
                     level: "info",
-                    source: this.CLASS_NAME,
+                    source: S3BlobStorageConnector.CLASS_NAME,
                     message: "bucketExists",
                     data: {
                         bucket: this._config.bucketName
@@ -84,7 +89,7 @@ class S3BlobStorageConnector {
                 await this._s3Client.send(new clientS3.CreateBucketCommand({ Bucket: this._config.bucketName }));
                 await nodeLogging?.log({
                     level: "info",
-                    source: this.CLASS_NAME,
+                    source: S3BlobStorageConnector.CLASS_NAME,
                     message: "bucketCreated",
                     data: {
                         bucket: this._config.bucketName
@@ -95,7 +100,7 @@ class S3BlobStorageConnector {
         catch (err) {
             await nodeLogging?.log({
                 level: "error",
-                source: this.CLASS_NAME,
+                source: S3BlobStorageConnector.CLASS_NAME,
                 message: "bucketCreateFailed",
                 data: {
                     bucket: this._config.bucketName
@@ -112,7 +117,7 @@ class S3BlobStorageConnector {
      * @returns The id of the stored blob in urn format.
      */
     async set(blob) {
-        core.Guards.uint8Array(this.CLASS_NAME, "blob", blob);
+        core.Guards.uint8Array(S3BlobStorageConnector.CLASS_NAME, "blob", blob);
         try {
             const id = core.Converter.bytesToHex(crypto.Sha256.sum256(blob));
             const command = new clientS3.PutObjectCommand({
@@ -124,7 +129,7 @@ class S3BlobStorageConnector {
             return `blob:${new core.Urn(S3BlobStorageConnector.NAMESPACE, id).toString()}`;
         }
         catch (err) {
-            throw new core.GeneralError(this.CLASS_NAME, "setBlobFailed", undefined, err);
+            throw new core.GeneralError(S3BlobStorageConnector.CLASS_NAME, "setBlobFailed", undefined, err);
         }
     }
     /**
@@ -133,10 +138,10 @@ class S3BlobStorageConnector {
      * @returns The data for the blob if it can be found or undefined.
      */
     async get(id) {
-        core.Urn.guard(this.CLASS_NAME, "id", id);
+        core.Urn.guard(S3BlobStorageConnector.CLASS_NAME, "id", id);
         const urnParsed = core.Urn.fromValidString(id);
         if (urnParsed.namespaceMethod() !== S3BlobStorageConnector.NAMESPACE) {
-            throw new core.GeneralError(this.CLASS_NAME, "namespaceMismatch", {
+            throw new core.GeneralError(S3BlobStorageConnector.CLASS_NAME, "namespaceMismatch", {
                 namespace: S3BlobStorageConnector.NAMESPACE,
                 id
             });
@@ -152,7 +157,12 @@ class S3BlobStorageConnector {
                 return new Uint8Array(await response.Body.transformToByteArray());
             }
         }
-        catch { }
+        catch (err) {
+            throw new core.GeneralError(S3BlobStorageConnector.CLASS_NAME, "getBlobFailed", {
+                id,
+                namespace: S3BlobStorageConnector.NAMESPACE
+            }, err);
+        }
     }
     /**
      * Remove the blob.
@@ -160,10 +170,10 @@ class S3BlobStorageConnector {
      * @returns True if the blob was found.
      */
     async remove(id) {
-        core.Urn.guard(this.CLASS_NAME, "id", id);
+        core.Urn.guard(S3BlobStorageConnector.CLASS_NAME, "id", id);
         const urnParsed = core.Urn.fromValidString(id);
         if (urnParsed.namespaceMethod() !== S3BlobStorageConnector.NAMESPACE) {
-            throw new core.GeneralError(this.CLASS_NAME, "namespaceMismatch", {
+            throw new core.GeneralError(S3BlobStorageConnector.CLASS_NAME, "namespaceMismatch", {
                 namespace: S3BlobStorageConnector.NAMESPACE,
                 id
             });
@@ -191,7 +201,7 @@ class S3BlobStorageConnector {
             return true;
         }
         catch (err) {
-            throw new core.GeneralError(this.CLASS_NAME, "removeBlobFailed", { id }, err);
+            throw new core.GeneralError(S3BlobStorageConnector.CLASS_NAME, "removeBlobFailed", { id }, err);
         }
     }
 }

package/dist/esm/index.mjs

@@ -16,7 +16,7 @@ class S3BlobStorageConnector {
     /**
      * Runtime name for the class.
      */
-    CLASS_NAME = "S3BlobStorageConnector";
+    static CLASS_NAME = "S3BlobStorageConnector";
     /**
      * The configuration for the connector.
      * @internal
@@ -32,20 +32,25 @@ class S3BlobStorageConnector {
      * @param options The options for the connector.
      */
     constructor(options) {
-        Guards.object(this.CLASS_NAME, "options", options);
-        Guards.object(this.CLASS_NAME, "options.config", options.config);
-        Guards.stringValue(this.CLASS_NAME, "options.config.region", options.config.region);
-        Guards.stringValue(this.CLASS_NAME, "options.config.bucketName", options.config.bucketName);
-        Guards.stringValue(this.CLASS_NAME, "options.config.accessKeyId", options.config.accessKeyId);
-        Guards.stringValue(this.CLASS_NAME, "options.config.secretAccessKey", options.config.secretAccessKey);
+        Guards.object(S3BlobStorageConnector.CLASS_NAME, "options", options);
+        Guards.object(S3BlobStorageConnector.CLASS_NAME, "options.config", options.config);
+        Guards.stringValue(S3BlobStorageConnector.CLASS_NAME, "options.config.region", options.config.region);
+        Guards.stringValue(S3BlobStorageConnector.CLASS_NAME, "options.config.bucketName", options.config.bucketName);
+        options.config.authMode ??= "credentials";
+        let credentials;
+        if (options.config.authMode === "credentials") {
+            Guards.stringValue(S3BlobStorageConnector.CLASS_NAME, "options.config.accessKeyId", options.config.accessKeyId);
+            Guards.stringValue(S3BlobStorageConnector.CLASS_NAME, "options.config.secretAccessKey", options.config.secretAccessKey);
+            credentials = {
+                accessKeyId: options.config.accessKeyId,
+                secretAccessKey: options.config.secretAccessKey
+            };
+        }
         this._config = options.config;
         this._s3Client = new S3Client({
             region: this._config.region,
             endpoint: this._config.endpoint,
-            credentials: {
-                accessKeyId: this._config.accessKeyId,
-                secretAccessKey: this._config.secretAccessKey
-            },
+            credentials,
             forcePathStyle: true
         });
     }
@@ -59,7 +64,7 @@ class S3BlobStorageConnector {
         try {
             await nodeLogging?.log({
                 level: "info",
-                source: this.CLASS_NAME,
+                source: S3BlobStorageConnector.CLASS_NAME,
                 message: "bucketCreating",
                 data: {
                     bucket: this._config.bucketName
@@ -71,7 +76,7 @@ class S3BlobStorageConnector {
             if (bucketExists) {
                 await nodeLogging?.log({
                     level: "info",
-                    source: this.CLASS_NAME,
+                    source: S3BlobStorageConnector.CLASS_NAME,
                     message: "bucketExists",
                     data: {
                         bucket: this._config.bucketName
@@ -82,7 +87,7 @@ class S3BlobStorageConnector {
                 await this._s3Client.send(new CreateBucketCommand({ Bucket: this._config.bucketName }));
                 await nodeLogging?.log({
                     level: "info",
-                    source: this.CLASS_NAME,
+                    source: S3BlobStorageConnector.CLASS_NAME,
                     message: "bucketCreated",
                     data: {
                         bucket: this._config.bucketName
@@ -93,7 +98,7 @@ class S3BlobStorageConnector {
         catch (err) {
             await nodeLogging?.log({
                 level: "error",
-                source: this.CLASS_NAME,
+                source: S3BlobStorageConnector.CLASS_NAME,
                 message: "bucketCreateFailed",
                 data: {
                     bucket: this._config.bucketName
@@ -110,7 +115,7 @@ class S3BlobStorageConnector {
      * @returns The id of the stored blob in urn format.
      */
     async set(blob) {
-        Guards.uint8Array(this.CLASS_NAME, "blob", blob);
+        Guards.uint8Array(S3BlobStorageConnector.CLASS_NAME, "blob", blob);
         try {
             const id = Converter.bytesToHex(Sha256.sum256(blob));
             const command = new PutObjectCommand({
@@ -122,7 +127,7 @@ class S3BlobStorageConnector {
             return `blob:${new Urn(S3BlobStorageConnector.NAMESPACE, id).toString()}`;
         }
         catch (err) {
-            throw new GeneralError(this.CLASS_NAME, "setBlobFailed", undefined, err);
+            throw new GeneralError(S3BlobStorageConnector.CLASS_NAME, "setBlobFailed", undefined, err);
         }
     }
     /**
@@ -131,10 +136,10 @@ class S3BlobStorageConnector {
      * @returns The data for the blob if it can be found or undefined.
      */
     async get(id) {
-        Urn.guard(this.CLASS_NAME, "id", id);
+        Urn.guard(S3BlobStorageConnector.CLASS_NAME, "id", id);
         const urnParsed = Urn.fromValidString(id);
         if (urnParsed.namespaceMethod() !== S3BlobStorageConnector.NAMESPACE) {
-            throw new GeneralError(this.CLASS_NAME, "namespaceMismatch", {
+            throw new GeneralError(S3BlobStorageConnector.CLASS_NAME, "namespaceMismatch", {
                 namespace: S3BlobStorageConnector.NAMESPACE,
                 id
             });
@@ -150,7 +155,12 @@ class S3BlobStorageConnector {
                 return new Uint8Array(await response.Body.transformToByteArray());
             }
         }
-        catch { }
+        catch (err) {
+            throw new GeneralError(S3BlobStorageConnector.CLASS_NAME, "getBlobFailed", {
+                id,
+                namespace: S3BlobStorageConnector.NAMESPACE
+            }, err);
+        }
     }
     /**
      * Remove the blob.
@@ -158,10 +168,10 @@ class S3BlobStorageConnector {
      * @returns True if the blob was found.
      */
     async remove(id) {
-        Urn.guard(this.CLASS_NAME, "id", id);
+        Urn.guard(S3BlobStorageConnector.CLASS_NAME, "id", id);
         const urnParsed = Urn.fromValidString(id);
         if (urnParsed.namespaceMethod() !== S3BlobStorageConnector.NAMESPACE) {
-            throw new GeneralError(this.CLASS_NAME, "namespaceMismatch", {
+            throw new GeneralError(S3BlobStorageConnector.CLASS_NAME, "namespaceMismatch", {
                 namespace: S3BlobStorageConnector.NAMESPACE,
                 id
             });
@@ -189,7 +199,7 @@ class S3BlobStorageConnector {
             return true;
         }
         catch (err) {
-            throw new GeneralError(this.CLASS_NAME, "removeBlobFailed", { id }, err);
+            throw new GeneralError(S3BlobStorageConnector.CLASS_NAME, "removeBlobFailed", { id }, err);
         }
     }
 }

package/dist/types/models/IS3BlobStorageConnectorConfig.d.ts

@@ -10,14 +10,21 @@ export interface IS3BlobStorageConnectorConfig {
      * The S3 bucket name.
      */
     bucketName: string;
+    /**
+     * The authentication mode.
+     * - "credentials": Use access key ID and secret access key.
+     * - "pod": Use IAM role attached to the pod (e.g., in EKS).
+     * @default credentials
+     */
+    authMode?: "credentials" | "pod";
     /**
      * The AWS access key ID.
      */
-    accessKeyId: string;
+    accessKeyId?: string;
     /**
      * The AWS secret access key.
      */
-    secretAccessKey: string;
+    secretAccessKey?: string;
     /**
      * Optional endpoint for S3-compatible storage (e.g., MinIO).
      */

package/dist/types/s3BlobStorageConnector.d.ts

@@ -12,7 +12,7 @@ export declare class S3BlobStorageConnector implements IBlobStorageConnector {
     /**
      * Runtime name for the class.
      */
-    readonly CLASS_NAME: string;
+    static readonly CLASS_NAME: string;
     /**
      * Create a new instance of S3BlobStorageConnector.
      * @param options The options for the connector.

package/docs/changelog.md

@@ -1,5 +1,33 @@
 # @twin.org/blob-storage-connector-aws-s3 - Changelog
 
+## [0.0.2-next.5](https://github.com/twinfoundation/blob-storage/compare/blob-storage-connector-aws-s3-v0.0.2-next.4...blob-storage-connector-aws-s3-v0.0.2-next.5) (2025-10-09)
+
+
+### Features
+
+* add validate-locales ([f20fcec](https://github.com/twinfoundation/blob-storage/commit/f20fceced91e39a0c9edb770b2e43ce944c92f3c))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/blob-storage-models bumped from 0.0.2-next.4 to 0.0.2-next.5
+
+## [0.0.2-next.4](https://github.com/twinfoundation/blob-storage/compare/blob-storage-connector-aws-s3-v0.0.2-next.3...blob-storage-connector-aws-s3-v0.0.2-next.4) (2025-10-02)
+
+
+### Features
+
+* add AWS pod authentication mode ([c34b11c](https://github.com/twinfoundation/blob-storage/commit/c34b11cb32d3310a9e59840341a2b0b4221bc780))
+
+
+### Dependencies
+
+* The following workspace dependencies were updated
+  * dependencies
+    * @twin.org/blob-storage-models bumped from 0.0.2-next.3 to 0.0.2-next.4
+
 ## [0.0.2-next.3](https://github.com/twinfoundation/blob-storage/compare/blob-storage-connector-aws-s3-v0.0.2-next.2...blob-storage-connector-aws-s3-v0.0.2-next.3) (2025-08-29)
 
 

package/docs/reference/classes/S3BlobStorageConnector.md

@@ -39,14 +39,10 @@ The namespace for the items.
 
 ### CLASS\_NAME
 
-> `readonly` **CLASS\_NAME**: `string`
+> `readonly` `static` **CLASS\_NAME**: `string`
 
 Runtime name for the class.
 
-#### Implementation of
-
-`IBlobStorageConnector.CLASS_NAME`
-
 ## Methods
 
 ### bootstrap()

package/docs/reference/interfaces/IS3BlobStorageConnectorConfig.md

@@ -20,17 +20,33 @@ The S3 bucket name.
 
 ***
 
-### accessKeyId
+### authMode?
 
-> **accessKeyId**: `string`
+> `optional` **authMode**: `"credentials"` \| `"pod"`
+
+The authentication mode.
+- "credentials": Use access key ID and secret access key.
+- "pod": Use IAM role attached to the pod (e.g., in EKS).
+
+#### Default
+
+```ts
+credentials
+```
+
+***
+
+### accessKeyId?
+
+> `optional` **accessKeyId**: `string`
 
 The AWS access key ID.
 
 ***
 
-### secretAccessKey
+### secretAccessKey?
 
-> **secretAccessKey**: `string`
+> `optional` **secretAccessKey**: `string`
 
 The AWS secret access key.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@twin.org/blob-storage-connector-aws-s3",
-	"version": "0.0.2-next.3",
+	"version": "0.0.2-next.5",
 	"description": "Blob Storage connector implementation using AWS S3",
 	"repository": {
 		"type": "git",
@@ -14,8 +14,8 @@
 		"node": ">=20.0.0"
 	},
 	"dependencies": {
-		"@aws-sdk/client-s3": "3.878.0",
-		"@twin.org/blob-storage-models": "0.0.2-next.3",
+		"@aws-sdk/client-s3": "3.906.0",
+		"@twin.org/blob-storage-models": "0.0.2-next.5",
 		"@twin.org/core": "next",
 		"@twin.org/crypto": "next",
 		"@twin.org/logging-models": "next",
@@ -38,5 +38,24 @@
 		"dist/types",
 		"locales",
 		"docs"
-	]
+	],
+	"keywords": [
+		"twin",
+		"trade",
+		"iota",
+		"framework",
+		"blockchain",
+		"blob-storage",
+		"blob",
+		"storage",
+		"files",
+		"binary",
+		"connector",
+		"adapter",
+		"integration"
+	],
+	"bugs": {
+		"url": "git+https://github.com/twinfoundation/blob-storage/issues"
+	},
+	"homepage": "https://twindev.org"
 }