@headless-lms/adapter-storage-s3 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mdwt
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+# @headless-lms/adapter-storage-s3
+
+AWS S3 implementation of the `ObjectStorage` port from `@headless-lms/core/types`.
+The bucket is private and must already exist; access is via short-lived presigned
+URLs only. Also works against S3-compatible stores via `endpoint` + `forcePathStyle`.
+
+The adapter reads no environment itself — the installation's `config.ts` parses
+env into an `S3StorageConfig` and injects the constructed adapter:
+
+```ts
+import { S3StorageAdapter } from "@headless-lms/adapter-storage-s3";
+
+const container = await createContainer(config, {
+  adapters: { storage: new S3StorageAdapter(storageConfig) },
+});
+```
+
+Omit `accessKeyId`/`secretAccessKey` to use the default AWS credential chain
+(IAM role, env vars, shared profile).
+
+## Bucket setup
+
+The adapter never creates buckets — bucket creation needs `s3:CreateBucket`
+permissions and region constraints the app credentials should not have. Create
+the bucket once (console, CLI, or IaC); everything the app does is object-level.
+
+1. Create a bucket and keep Block Public Access on (the default). No bucket
+   policy is needed — access is via presigned URLs only.
+2. Grant the app credentials `s3:PutObject`, `s3:GetObject`, `s3:HeadObject`,
+   and `s3:DeleteObject` on `arn:aws:s3:::your-bucket/*`. Either an IAM user
+   with access keys, or an IAM role when running on AWS (then omit the keys).
+3. Add a CORS rule — browsers upload directly to the presigned URL:
+
+   ```json
+   [
+     {
+       "AllowedOrigins": ["https://your-app.com"],
+       "AllowedMethods": ["PUT", "GET"],
+       "AllowedHeaders": ["Content-Type"],
+       "MaxAgeSeconds": 3000
+     }
+   ]
+   ```
+
+4. Set `STORAGE_REGION`, `STORAGE_BUCKET`, and optionally the keys. Leave
+   `STORAGE_ENDPOINT` and `STORAGE_FORCE_PATH_STYLE` unset for real AWS.
+
+## Path style
+
+S3 has two URL formats: virtual-hosted style (`https://bucket.s3.amazonaws.com/key`,
+the AWS default) and path style (`https://s3.amazonaws.com/bucket/key`).
+S3-compatible stores typically run on one hostname with no per-bucket DNS, so
+the bucket name cannot be a subdomain — they need path style. Set
+`STORAGE_FORCE_PATH_STYLE=true` only in that case.
+
+## Environment variables (reference installation)
+
+| Variable                   | Required | Maps to                 | Notes                                 |
+| -------------------------- | -------- | ----------------------- | ------------------------------------- |
+| `STORAGE_REGION`           | yes      | `region`                |                                       |
+| `STORAGE_BUCKET`           | yes      | `bucket`                | Must exist; kept private.             |
+| `STORAGE_ACCESS_KEY`       | no       | `accessKeyId`           | Omit for the default credential chain.|
+| `STORAGE_SECRET_KEY`       | no       | `secretAccessKey`       | Omit for the default credential chain.|
+| `STORAGE_ENDPOINT`         | no       | `endpoint`              | Full URL, for S3-compatible stores.   |
+| `STORAGE_FORCE_PATH_STYLE` | no       | `forcePathStyle`        | `"true"` / `"false"`.                 |
+| `STORAGE_UPLOAD_EXPIRY`    | no       | `uploadExpirySeconds`   | Default 300.                          |
+| `STORAGE_DOWNLOAD_EXPIRY`  | no       | `downloadExpirySeconds` | Default 86400.                        |

package/dist/index.d.ts

@@ -0,0 +1,34 @@
+import { Logger, ObjectStorage, PresignDownloadInput, PresignedUpload, StoredObjectInfo } from "@headless-lms/core/types";
+//#region src/index.d.ts
+interface S3StorageConfig {
+  region: string;
+  bucket: string;
+  /** Omit both keys to use the default AWS credential chain (IAM role, env, profile). */
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  /** Custom endpoint for S3-compatible stores. */
+  endpoint?: string;
+  /** Required by most S3-compatible stores when `endpoint` is set. */
+  forcePathStyle?: boolean;
+  uploadExpirySeconds: number;
+  downloadExpirySeconds: number;
+}
+declare class S3StorageAdapter implements ObjectStorage {
+  private readonly logger?;
+  private readonly client;
+  private readonly bucket;
+  private readonly uploadExpiry;
+  private readonly downloadExpiry;
+  constructor(config: S3StorageConfig, logger?: Logger | undefined);
+  presignUpload(input: {
+    key: string;
+    contentType?: string;
+    expiresInSeconds?: number;
+  }): Promise<PresignedUpload>;
+  presignDownload(input: PresignDownloadInput): Promise<string>;
+  stat(key: string): Promise<StoredObjectInfo | null>;
+  remove(key: string): Promise<void>;
+}
+//#endregion
+export { S3StorageAdapter, S3StorageConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,80 @@
+import { DeleteObjectCommand, GetObjectCommand, HeadObjectCommand, PutObjectCommand, S3Client } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+//#region src/index.ts
+var S3StorageAdapter = class {
+	logger;
+	client;
+	bucket;
+	uploadExpiry;
+	downloadExpiry;
+	constructor(config, logger) {
+		this.logger = logger;
+		this.client = new S3Client({
+			region: config.region,
+			...config.endpoint ? { endpoint: config.endpoint } : {},
+			...config.forcePathStyle !== void 0 ? { forcePathStyle: config.forcePathStyle } : {},
+			...config.accessKeyId && config.secretAccessKey ? { credentials: {
+				accessKeyId: config.accessKeyId,
+				secretAccessKey: config.secretAccessKey
+			} } : {}
+		});
+		this.bucket = config.bucket;
+		this.uploadExpiry = config.uploadExpirySeconds;
+		this.downloadExpiry = config.downloadExpirySeconds;
+	}
+	async presignUpload(input) {
+		const expiresInSeconds = input.expiresInSeconds ?? this.uploadExpiry;
+		const command = new PutObjectCommand({
+			Bucket: this.bucket,
+			Key: input.key,
+			...input.contentType ? { ContentType: input.contentType } : {}
+		});
+		return {
+			url: await getSignedUrl(this.client, command, { expiresIn: expiresInSeconds }),
+			method: "PUT",
+			key: input.key,
+			expiresInSeconds,
+			headers: input.contentType ? { "Content-Type": input.contentType } : {}
+		};
+	}
+	async presignDownload(input) {
+		const expiresInSeconds = input.expiresInSeconds ?? this.downloadExpiry;
+		const command = new GetObjectCommand({
+			Bucket: this.bucket,
+			Key: input.key,
+			...input.downloadFilename ? { ResponseContentDisposition: `attachment; filename="${input.downloadFilename.replace(/"/g, "")}"` } : {}
+		});
+		return getSignedUrl(this.client, command, { expiresIn: expiresInSeconds });
+	}
+	async stat(key) {
+		try {
+			const s = await this.client.send(new HeadObjectCommand({
+				Bucket: this.bucket,
+				Key: key
+			}));
+			return {
+				key,
+				size: s.ContentLength ?? 0,
+				...s.ContentType ? { contentType: s.ContentType } : {},
+				...s.LastModified ? { lastModified: s.LastModified.toISOString() } : {}
+			};
+		} catch (err) {
+			if (isNotFound(err)) return null;
+			throw err;
+		}
+	}
+	async remove(key) {
+		await this.client.send(new DeleteObjectCommand({
+			Bucket: this.bucket,
+			Key: key
+		}));
+	}
+};
+function isNotFound(err) {
+	const e = err;
+	return e?.name === "NotFound" || e?.name === "NoSuchKey" || e?.$metadata?.httpStatusCode === 404;
+}
+//#endregion
+export { S3StorageAdapter };
+
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["// AWS S3 implementation of the ObjectStorage port. Private bucket; access via\n// short-lived presigned URLs only. The bucket must already exist.\nimport {\n  DeleteObjectCommand,\n  GetObjectCommand,\n  HeadObjectCommand,\n  PutObjectCommand,\n  S3Client,\n} from \"@aws-sdk/client-s3\";\nimport { getSignedUrl } from \"@aws-sdk/s3-request-presigner\";\nimport type {\n  Logger,\n  ObjectStorage,\n  PresignDownloadInput,\n  PresignedUpload,\n  StoredObjectInfo,\n} from \"@headless-lms/core/types\";\n\nexport interface S3StorageConfig {\n  region: string;\n  bucket: string;\n  /** Omit both keys to use the default AWS credential chain (IAM role, env, profile). */\n  accessKeyId?: string;\n  secretAccessKey?: string;\n  /** Custom endpoint for S3-compatible stores. */\n  endpoint?: string;\n  /** Required by most S3-compatible stores when `endpoint` is set. */\n  forcePathStyle?: boolean;\n  uploadExpirySeconds: number;\n  downloadExpirySeconds: number;\n}\n\nexport class S3StorageAdapter implements ObjectStorage {\n  private readonly client: S3Client;\n  private readonly bucket: string;\n  private readonly uploadExpiry: number;\n  private readonly downloadExpiry: number;\n\n  constructor(\n    config: S3StorageConfig,\n    private readonly logger?: Logger,\n  ) {\n    this.client = new S3Client({\n      region: config.region,\n      ...(config.endpoint ? { endpoint: config.endpoint } : {}),\n      ...(config.forcePathStyle !== undefined ? { forcePathStyle: config.forcePathStyle } : {}),\n      ...(config.accessKeyId && config.secretAccessKey\n        ? {\n            credentials: {\n              accessKeyId: config.accessKeyId,\n              secretAccessKey: config.secretAccessKey,\n            },\n          }\n        : {}),\n    });\n    this.bucket = config.bucket;\n    this.uploadExpiry = config.uploadExpirySeconds;\n    this.downloadExpiry = config.downloadExpirySeconds;\n  }\n\n  async presignUpload(input: {\n    key: string;\n    contentType?: string;\n    expiresInSeconds?: number;\n  }): Promise<PresignedUpload> {\n    const expiresInSeconds = input.expiresInSeconds ?? this.uploadExpiry;\n    const command = new PutObjectCommand({\n      Bucket: this.bucket,\n      Key: input.key,\n      ...(input.contentType ? { ContentType: input.contentType } : {}),\n    });\n    const url = await getSignedUrl(this.client, command, { expiresIn: expiresInSeconds });\n    return {\n      url,\n      method: \"PUT\",\n      key: input.key,\n      expiresInSeconds,\n      headers: input.contentType ? { \"Content-Type\": input.contentType } : {},\n    };\n  }\n\n  async presignDownload(input: PresignDownloadInput): Promise<string> {\n    const expiresInSeconds = input.expiresInSeconds ?? this.downloadExpiry;\n    const command = new GetObjectCommand({\n      Bucket: this.bucket,\n      Key: input.key,\n      ...(input.downloadFilename\n        ? {\n            ResponseContentDisposition: `attachment; filename=\"${input.downloadFilename.replace(/\"/g, \"\")}\"`,\n          }\n        : {}),\n    });\n    return getSignedUrl(this.client, command, { expiresIn: expiresInSeconds });\n  }\n\n  async stat(key: string): Promise<StoredObjectInfo | null> {\n    try {\n      const s = await this.client.send(\n        new HeadObjectCommand({ Bucket: this.bucket, Key: key }),\n      );\n      return {\n        key,\n        size: s.ContentLength ?? 0,\n        ...(s.ContentType ? { contentType: s.ContentType } : {}),\n        ...(s.LastModified ? { lastModified: s.LastModified.toISOString() } : {}),\n      };\n    } catch (err) {\n      if (isNotFound(err)) {\n        return null;\n      }\n      throw err;\n    }\n  }\n\n  async remove(key: string): Promise<void> {\n    await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: key }));\n  }\n}\n\nfunction isNotFound(err: unknown): boolean {\n  const e = err as { name?: string; $metadata?: { httpStatusCode?: number } };\n  return e?.name === \"NotFound\" || e?.name === \"NoSuchKey\" || e?.$metadata?.httpStatusCode === 404;\n}\n"],"mappings":";;;AAgCA,IAAa,mBAAb,MAAuD;CAQlC;CAPnB;CACA;CACA;CACA;CAEA,YACE,QACA,QACA;EADiB,KAAA,SAAA;EAEjB,KAAK,SAAS,IAAI,SAAS;GACzB,QAAQ,OAAO;GACf,GAAI,OAAO,WAAW,EAAE,UAAU,OAAO,SAAS,IAAI,CAAC;GACvD,GAAI,OAAO,mBAAmB,KAAA,IAAY,EAAE,gBAAgB,OAAO,eAAe,IAAI,CAAC;GACvF,GAAI,OAAO,eAAe,OAAO,kBAC7B,EACE,aAAa;IACX,aAAa,OAAO;IACpB,iBAAiB,OAAO;GAC1B,EACF,IACA,CAAC;EACP,CAAC;EACD,KAAK,SAAS,OAAO;EACrB,KAAK,eAAe,OAAO;EAC3B,KAAK,iBAAiB,OAAO;CAC/B;CAEA,MAAM,cAAc,OAIS;EAC3B,MAAM,mBAAmB,MAAM,oBAAoB,KAAK;EACxD,MAAM,UAAU,IAAI,iBAAiB;GACnC,QAAQ,KAAK;GACb,KAAK,MAAM;GACX,GAAI,MAAM,cAAc,EAAE,aAAa,MAAM,YAAY,IAAI,CAAC;EAChE,CAAC;EAED,OAAO;GACL,KAAA,MAFgB,aAAa,KAAK,QAAQ,SAAS,EAAE,WAAW,iBAAiB,CAAC;GAGlF,QAAQ;GACR,KAAK,MAAM;GACX;GACA,SAAS,MAAM,cAAc,EAAE,gBAAgB,MAAM,YAAY,IAAI,CAAC;EACxE;CACF;CAEA,MAAM,gBAAgB,OAA8C;EAClE,MAAM,mBAAmB,MAAM,oBAAoB,KAAK;EACxD,MAAM,UAAU,IAAI,iBAAiB;GACnC,QAAQ,KAAK;GACb,KAAK,MAAM;GACX,GAAI,MAAM,mBACN,EACE,4BAA4B,yBAAyB,MAAM,iBAAiB,QAAQ,MAAM,EAAE,EAAE,GAChG,IACA,CAAC;EACP,CAAC;EACD,OAAO,aAAa,KAAK,QAAQ,SAAS,EAAE,WAAW,iBAAiB,CAAC;CAC3E;CAEA,MAAM,KAAK,KAA+C;EACxD,IAAI;GACF,MAAM,IAAI,MAAM,KAAK,OAAO,KAC1B,IAAI,kBAAkB;IAAE,QAAQ,KAAK;IAAQ,KAAK;GAAI,CAAC,CACzD;GACA,OAAO;IACL;IACA,MAAM,EAAE,iBAAiB;IACzB,GAAI,EAAE,cAAc,EAAE,aAAa,EAAE,YAAY,IAAI,CAAC;IACtD,GAAI,EAAE,eAAe,EAAE,cAAc,EAAE,aAAa,YAAY,EAAE,IAAI,CAAC;GACzE;EACF,SAAS,KAAK;GACZ,IAAI,WAAW,GAAG,GAChB,OAAO;GAET,MAAM;EACR;CACF;CAEA,MAAM,OAAO,KAA4B;EACvC,MAAM,KAAK,OAAO,KAAK,IAAI,oBAAoB;GAAE,QAAQ,KAAK;GAAQ,KAAK;EAAI,CAAC,CAAC;CACnF;AACF;AAEA,SAAS,WAAW,KAAuB;CACzC,MAAM,IAAI;CACV,OAAO,GAAG,SAAS,cAAc,GAAG,SAAS,eAAe,GAAG,WAAW,mBAAmB;AAC/F"}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@headless-lms/adapter-storage-s3",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.712.0",
+    "@aws-sdk/s3-request-presigner": "^3.712.0",
+    "@headless-lms/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsdown": "^0.22.9",
+    "typescript": "^5.7.2"
+  },
+  "description": "AWS S3 storage adapter for the headless LMS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mdwt/headless-lms.git",
+    "directory": "adapters/storage-s3"
+  },
+  "homepage": "https://github.com/mdwt/headless-lms#readme",
+  "bugs": {
+    "url": "https://github.com/mdwt/headless-lms/issues"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit"
+  }
+}