@nixxie-cms/storage 1.0.1

package/dist/nixxie-cms-storage.esm.js

@@ -0,0 +1,391 @@
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile, readFile, rm, stat, readdir } from 'node:fs/promises';
+import { resolve, sep, dirname, join, relative, posix } from 'node:path';
+
+function loadAzure() {
+  try {
+    return require('@azure/storage-blob');
+  } catch {
+    throw new Error('@azure/storage-blob is required for the Azure driver. Run: npm install @azure/storage-blob');
+  }
+}
+
+/** Azure Blob Storage backend. */
+class AzureStorage {
+  constructor(config) {
+    this.config = config;
+    this.prefix = config.prefix ? config.prefix.replace(/\/$/, '') + '/' : '';
+    const {
+      BlobServiceClient
+    } = loadAzure();
+    const service = BlobServiceClient.fromConnectionString(config.connectionString);
+    this.container = service.getContainerClient(config.container);
+  }
+  blob(key) {
+    return this.container.getBlockBlobClient(`${this.prefix}${key}`);
+  }
+  async put(key, data, options) {
+    const body = typeof data === 'string' ? Buffer.from(data) : Buffer.from(data);
+    await this.blob(key).uploadData(body, {
+      blobHTTPHeaders: options !== null && options !== void 0 && options.contentType ? {
+        blobContentType: options.contentType
+      } : undefined,
+      metadata: options === null || options === void 0 ? void 0 : options.metadata
+    });
+    return {
+      key,
+      url: this.url(key),
+      size: body.byteLength,
+      contentType: options === null || options === void 0 ? void 0 : options.contentType
+    };
+  }
+  async get(key) {
+    try {
+      return await this.blob(key).downloadToBuffer();
+    } catch (err) {
+      if ((err === null || err === void 0 ? void 0 : err.statusCode) === 404) return undefined;
+      throw err;
+    }
+  }
+  async delete(key) {
+    await this.blob(key).deleteIfExists();
+  }
+  async has(key) {
+    return Boolean(await this.blob(key).exists());
+  }
+  url(key) {
+    if (this.config.publicBaseUrl) return `${this.config.publicBaseUrl.replace(/\/$/, '')}/${this.prefix}${key}`;
+    return this.blob(key).url;
+  }
+  async signedUrl(key, options) {
+    var _credential, _options$expiresIn;
+    const {
+      BlobSASPermissions,
+      generateBlobSASQueryParameters
+    } = loadAzure();
+    const blob = this.blob(key);
+    const credential = (_credential = this.container.credential) !== null && _credential !== void 0 ? _credential : blob.credential;
+    const expiresOn = new Date(Date.now() + ((_options$expiresIn = options === null || options === void 0 ? void 0 : options.expiresIn) !== null && _options$expiresIn !== void 0 ? _options$expiresIn : 900) * 1000);
+    const permissions = BlobSASPermissions.parse((options === null || options === void 0 ? void 0 : options.operation) === 'put' ? 'cw' : 'r');
+    try {
+      const sas = generateBlobSASQueryParameters({
+        containerName: this.config.container,
+        blobName: `${this.prefix}${key}`,
+        permissions,
+        expiresOn
+      }, credential).toString();
+      return `${blob.url}?${sas}`;
+    } catch {
+      // Falls back to the plain URL when SAS generation is unavailable (e.g. token credential).
+      return blob.url;
+    }
+  }
+  async list(prefix = '') {
+    const out = [];
+    for await (const item of this.container.listBlobsFlat({
+      prefix: `${this.prefix}${prefix}`
+    })) {
+      const name = item.name;
+      out.push(this.prefix && name.startsWith(this.prefix) ? name.slice(this.prefix.length) : name);
+    }
+    return out;
+  }
+}
+
+function loadGcs() {
+  try {
+    return require('@google-cloud/storage');
+  } catch {
+    throw new Error('@google-cloud/storage is required for the GCS driver. Run: npm install @google-cloud/storage');
+  }
+}
+
+/** Google Cloud Storage backend. */
+class GcsStorage {
+  constructor(config) {
+    this.config = config;
+    this.prefix = config.prefix ? config.prefix.replace(/\/$/, '') + '/' : '';
+    const {
+      Storage
+    } = loadGcs();
+    const client = new Storage({
+      projectId: config.projectId,
+      keyFilename: config.keyFilename
+    });
+    this.bucket = client.bucket(config.bucket);
+  }
+  file(key) {
+    return this.bucket.file(`${this.prefix}${key}`);
+  }
+  async put(key, data, options) {
+    const body = typeof data === 'string' ? Buffer.from(data) : Buffer.from(data);
+    const file = this.file(key);
+    await file.save(body, {
+      contentType: options === null || options === void 0 ? void 0 : options.contentType,
+      metadata: options !== null && options !== void 0 && options.metadata ? {
+        metadata: options.metadata
+      } : undefined
+    });
+    if (options !== null && options !== void 0 && options.public) await file.makePublic();
+    return {
+      key,
+      url: this.url(key),
+      size: body.byteLength,
+      contentType: options === null || options === void 0 ? void 0 : options.contentType
+    };
+  }
+  async get(key) {
+    try {
+      const [contents] = await this.file(key).download();
+      return contents;
+    } catch (err) {
+      if ((err === null || err === void 0 ? void 0 : err.code) === 404) return undefined;
+      throw err;
+    }
+  }
+  async delete(key) {
+    await this.file(key).delete({
+      ignoreNotFound: true
+    });
+  }
+  async has(key) {
+    const [exists] = await this.file(key).exists();
+    return Boolean(exists);
+  }
+  url(key) {
+    if (this.config.publicBaseUrl) return `${this.config.publicBaseUrl.replace(/\/$/, '')}/${this.prefix}${key}`;
+    return `https://storage.googleapis.com/${this.config.bucket}/${this.prefix}${key}`;
+  }
+  async signedUrl(key, options) {
+    var _options$expiresIn;
+    const [url] = await this.file(key).getSignedUrl({
+      action: (options === null || options === void 0 ? void 0 : options.operation) === 'put' ? 'write' : 'read',
+      expires: Date.now() + ((_options$expiresIn = options === null || options === void 0 ? void 0 : options.expiresIn) !== null && _options$expiresIn !== void 0 ? _options$expiresIn : 900) * 1000,
+      contentType: (options === null || options === void 0 ? void 0 : options.operation) === 'put' ? options === null || options === void 0 ? void 0 : options.contentType : undefined
+    });
+    return url;
+  }
+  async list(prefix = '') {
+    const [files] = await this.bucket.getFiles({
+      prefix: `${this.prefix}${prefix}`
+    });
+    return files.map(f => f.name).map(k => this.prefix && k.startsWith(this.prefix) ? k.slice(this.prefix.length) : k);
+  }
+}
+
+/**
+ * Filesystem-backed storage. Good for development and single-node deployments.
+ * `signedUrl()` falls back to the plain public URL since the local disk cannot sign.
+ */
+class LocalStorage {
+  constructor(config) {
+    var _config$baseDir, _config$baseUrl;
+    this.baseDir = (_config$baseDir = config.baseDir) !== null && _config$baseDir !== void 0 ? _config$baseDir : '.nixxie-storage';
+    this.baseUrl = ((_config$baseUrl = config.baseUrl) !== null && _config$baseUrl !== void 0 ? _config$baseUrl : '/files').replace(/\/$/, '');
+  }
+  path(key) {
+    // Confine resolved paths to baseDir so keys like "../../etc/passwd" (or absolute paths)
+    // cannot escape the storage root.
+    const root = resolve(this.baseDir);
+    const full = resolve(root, key);
+    if (full !== root && !full.startsWith(root + sep)) {
+      throw new Error(`Invalid storage key (path traversal detected): ${key}`);
+    }
+    return full;
+  }
+  async put(key, data, options) {
+    const filePath = this.path(key);
+    await mkdir(dirname(filePath), {
+      recursive: true
+    });
+    const buffer = typeof data === 'string' ? Buffer.from(data) : Buffer.from(data);
+    await writeFile(filePath, buffer);
+    return {
+      key,
+      url: this.url(key),
+      size: buffer.byteLength,
+      contentType: options === null || options === void 0 ? void 0 : options.contentType
+    };
+  }
+  async get(key) {
+    const filePath = this.path(key);
+    if (!existsSync(filePath)) return undefined;
+    return readFile(filePath);
+  }
+  async delete(key) {
+    await rm(this.path(key), {
+      force: true
+    });
+  }
+  async has(key) {
+    try {
+      await stat(this.path(key));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  url(key) {
+    return `${this.baseUrl}/${key.split(sep).join('/')}`;
+  }
+  async signedUrl(key, _options) {
+    return this.url(key);
+  }
+  async list(prefix = '') {
+    const root = this.baseDir;
+    const out = [];
+    const walk = async dir => {
+      let entries;
+      try {
+        entries = await readdir(dir, {
+          withFileTypes: true
+        });
+      } catch {
+        return;
+      }
+      for (const entry of entries) {
+        const full = join(dir, entry.name);
+        if (entry.isDirectory()) await walk(full);else out.push(relative(root, full).split(sep).join(posix.sep));
+      }
+    };
+    await walk(root);
+    return out.filter(k => k.startsWith(prefix));
+  }
+}
+
+function loadS3() {
+  try {
+    return {
+      s3: require('@aws-sdk/client-s3'),
+      presigner: require('@aws-sdk/s3-request-presigner')
+    };
+  } catch {
+    throw new Error('@aws-sdk/client-s3 and @aws-sdk/s3-request-presigner are required for the S3 driver. Run: npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner');
+  }
+}
+
+/** AWS S3 (and S3-compatible: R2, MinIO, Spaces) storage backend. */
+class S3Storage {
+  constructor(config) {
+    this.config = config;
+    this.prefix = config.prefix ? config.prefix.replace(/\/$/, '') + '/' : '';
+    const {
+      s3,
+      presigner
+    } = loadS3();
+    this.s3 = s3;
+    this.presigner = presigner;
+    this.client = new s3.S3Client({
+      region: config.region,
+      endpoint: config.endpoint,
+      forcePathStyle: config.forcePathStyle,
+      credentials: config.accessKeyId && config.secretAccessKey ? {
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey
+      } : undefined
+    });
+  }
+  k(key) {
+    return `${this.prefix}${key}`;
+  }
+  async put(key, data, options) {
+    const body = typeof data === 'string' ? Buffer.from(data) : Buffer.from(data);
+    await this.client.send(new this.s3.PutObjectCommand({
+      Bucket: this.config.bucket,
+      Key: this.k(key),
+      Body: body,
+      ContentType: options === null || options === void 0 ? void 0 : options.contentType,
+      ACL: options !== null && options !== void 0 && options.public ? 'public-read' : undefined,
+      Metadata: options === null || options === void 0 ? void 0 : options.metadata
+    }));
+    return {
+      key,
+      url: this.url(key),
+      size: body.byteLength,
+      contentType: options === null || options === void 0 ? void 0 : options.contentType
+    };
+  }
+  async get(key) {
+    try {
+      var _res$Body;
+      const res = await this.client.send(new this.s3.GetObjectCommand({
+        Bucket: this.config.bucket,
+        Key: this.k(key)
+      }));
+      const bytes = await ((_res$Body = res.Body) === null || _res$Body === void 0 ? void 0 : _res$Body.transformToByteArray());
+      return bytes ? Buffer.from(bytes) : undefined;
+    } catch (err) {
+      var _err$$metadata;
+      if ((err === null || err === void 0 ? void 0 : err.name) === 'NoSuchKey' || (err === null || err === void 0 || (_err$$metadata = err.$metadata) === null || _err$$metadata === void 0 ? void 0 : _err$$metadata.httpStatusCode) === 404) return undefined;
+      throw err;
+    }
+  }
+  async delete(key) {
+    await this.client.send(new this.s3.DeleteObjectCommand({
+      Bucket: this.config.bucket,
+      Key: this.k(key)
+    }));
+  }
+  async has(key) {
+    try {
+      await this.client.send(new this.s3.HeadObjectCommand({
+        Bucket: this.config.bucket,
+        Key: this.k(key)
+      }));
+      return true;
+    } catch {
+      return false;
+    }
+  }
+  url(key) {
+    var _this$config$region;
+    if (this.config.publicBaseUrl) return `${this.config.publicBaseUrl.replace(/\/$/, '')}/${this.k(key)}`;
+    const host = this.config.endpoint ? `${this.config.endpoint.replace(/\/$/, '')}/${this.config.bucket}` : `https://${this.config.bucket}.s3.${(_this$config$region = this.config.region) !== null && _this$config$region !== void 0 ? _this$config$region : 'us-east-1'}.amazonaws.com`;
+    return `${host}/${this.k(key)}`;
+  }
+  async signedUrl(key, options) {
+    var _options$expiresIn;
+    const command = (options === null || options === void 0 ? void 0 : options.operation) === 'put' ? new this.s3.PutObjectCommand({
+      Bucket: this.config.bucket,
+      Key: this.k(key),
+      ContentType: options.contentType
+    }) : new this.s3.GetObjectCommand({
+      Bucket: this.config.bucket,
+      Key: this.k(key)
+    });
+    return this.presigner.getSignedUrl(this.client, command, {
+      expiresIn: (_options$expiresIn = options === null || options === void 0 ? void 0 : options.expiresIn) !== null && _options$expiresIn !== void 0 ? _options$expiresIn : 900
+    });
+  }
+  async list(prefix = '') {
+    var _res$Contents;
+    const res = await this.client.send(new this.s3.ListObjectsV2Command({
+      Bucket: this.config.bucket,
+      Prefix: this.k(prefix)
+    }));
+    return ((_res$Contents = res.Contents) !== null && _res$Contents !== void 0 ? _res$Contents : []).map(o => {
+      var _o$Key;
+      return (_o$Key = o.Key) !== null && _o$Key !== void 0 ? _o$Key : '';
+    }).map(k => this.prefix && k.startsWith(this.prefix) ? k.slice(this.prefix.length) : k).filter(Boolean);
+  }
+}
+
+function createStorage(config) {
+  switch (config.driver) {
+    case 'local':
+      return new LocalStorage(config);
+    case 's3':
+      return new S3Storage(config);
+    case 'gcs':
+      return new GcsStorage(config);
+    case 'azure':
+      return new AzureStorage(config);
+    default:
+      {
+        const exhaustive = config;
+        throw new Error(`Unknown storage driver: ${exhaustive.driver}`);
+      }
+  }
+}
+
+export { AzureStorage, GcsStorage, LocalStorage, S3Storage, createStorage };

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nixxie-cms/storage",
+  "version": "1.0.1",
+  "license": "MIT",
+  "main": "dist/nixxie-cms-storage.cjs.js",
+  "module": "dist/nixxie-cms-storage.esm.js",
+  "exports": {
+    ".": {
+      "types": "./dist/nixxie-cms-storage.cjs.js",
+      "module": "./dist/nixxie-cms-storage.esm.js",
+      "default": "./dist/nixxie-cms-storage.cjs.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@babel/runtime": "^7.24.7"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "^3.1037.0",
+    "@aws-sdk/s3-request-presigner": "^3.1037.0",
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "peerDependencies": {
+    "@nixxie-cms/core": "^1.0.1"
+  },
+  "optionalDependencies": {
+    "@aws-sdk/client-s3": "^3.1037.0",
+    "@aws-sdk/s3-request-presigner": "^3.1037.0"
+  },
+  "preconstruct": {
+    "entrypoints": [
+      "index.ts"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nixxiecms/nixxie/tree/main/packages/storage"
+  }
+}

package/src/AzureStorage.ts

@@ -0,0 +1,104 @@
+import type {
+  NixxiePutOptions,
+  NixxieSignedUrlOptions,
+  NixxieStorageService,
+  NixxieStoredFile,
+} from '@nixxie-cms/core'
+import type { AzureStorageConfig } from './types'
+
+function loadAzure(): any {
+  try {
+    return require('@azure/storage-blob')
+  } catch {
+    throw new Error(
+      '@azure/storage-blob is required for the Azure driver. Run: npm install @azure/storage-blob'
+    )
+  }
+}
+
+/** Azure Blob Storage backend. */
+export class AzureStorage implements NixxieStorageService {
+  private config: AzureStorageConfig
+  private prefix: string
+  private container: any
+
+  constructor(config: AzureStorageConfig) {
+    this.config = config
+    this.prefix = config.prefix ? config.prefix.replace(/\/$/, '') + '/' : ''
+    const { BlobServiceClient } = loadAzure()
+    const service = BlobServiceClient.fromConnectionString(config.connectionString)
+    this.container = service.getContainerClient(config.container)
+  }
+
+  private blob(key: string): any {
+    return this.container.getBlockBlobClient(`${this.prefix}${key}`)
+  }
+
+  async put(
+    key: string,
+    data: Buffer | Uint8Array | string,
+    options?: NixxiePutOptions
+  ): Promise<NixxieStoredFile> {
+    const body = typeof data === 'string' ? Buffer.from(data) : Buffer.from(data)
+    await this.blob(key).uploadData(body, {
+      blobHTTPHeaders: options?.contentType ? { blobContentType: options.contentType } : undefined,
+      metadata: options?.metadata,
+    })
+    return { key, url: this.url(key), size: body.byteLength, contentType: options?.contentType }
+  }
+
+  async get(key: string): Promise<Buffer | undefined> {
+    try {
+      return (await this.blob(key).downloadToBuffer()) as Buffer
+    } catch (err: any) {
+      if (err?.statusCode === 404) return undefined
+      throw err
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.blob(key).deleteIfExists()
+  }
+
+  async has(key: string): Promise<boolean> {
+    return Boolean(await this.blob(key).exists())
+  }
+
+  url(key: string): string {
+    if (this.config.publicBaseUrl)
+      return `${this.config.publicBaseUrl.replace(/\/$/, '')}/${this.prefix}${key}`
+    return this.blob(key).url as string
+  }
+
+  async signedUrl(key: string, options?: NixxieSignedUrlOptions): Promise<string> {
+    const { BlobSASPermissions, generateBlobSASQueryParameters } = loadAzure()
+    const blob = this.blob(key)
+    const credential = (this.container as any).credential ?? blob.credential
+    const expiresOn = new Date(Date.now() + (options?.expiresIn ?? 900) * 1000)
+    const permissions = BlobSASPermissions.parse(options?.operation === 'put' ? 'cw' : 'r')
+    try {
+      const sas = generateBlobSASQueryParameters(
+        {
+          containerName: this.config.container,
+          blobName: `${this.prefix}${key}`,
+          permissions,
+          expiresOn,
+        },
+        credential
+      ).toString()
+      return `${blob.url}?${sas}`
+    } catch {
+      // Falls back to the plain URL when SAS generation is unavailable (e.g. token credential).
+      return blob.url as string
+    }
+  }
+
+  async list(prefix = ''): Promise<string[]> {
+    const out: string[] = []
+    for await (const item of this.container.listBlobsFlat({ prefix: `${this.prefix}${prefix}` })) {
+      const name = item.name as string
+      out.push(this.prefix && name.startsWith(this.prefix) ? name.slice(this.prefix.length) : name)
+    }
+    return out
+  }
+}

package/src/GcsStorage.ts

@@ -0,0 +1,92 @@
+import type {
+  NixxiePutOptions,
+  NixxieSignedUrlOptions,
+  NixxieStorageService,
+  NixxieStoredFile,
+} from '@nixxie-cms/core'
+import type { GcsStorageConfig } from './types'
+
+function loadGcs(): any {
+  try {
+    return require('@google-cloud/storage')
+  } catch {
+    throw new Error(
+      '@google-cloud/storage is required for the GCS driver. Run: npm install @google-cloud/storage'
+    )
+  }
+}
+
+/** Google Cloud Storage backend. */
+export class GcsStorage implements NixxieStorageService {
+  private config: GcsStorageConfig
+  private prefix: string
+  private bucket: any
+
+  constructor(config: GcsStorageConfig) {
+    this.config = config
+    this.prefix = config.prefix ? config.prefix.replace(/\/$/, '') + '/' : ''
+    const { Storage } = loadGcs()
+    const client = new Storage({ projectId: config.projectId, keyFilename: config.keyFilename })
+    this.bucket = client.bucket(config.bucket)
+  }
+
+  private file(key: string): any {
+    return this.bucket.file(`${this.prefix}${key}`)
+  }
+
+  async put(
+    key: string,
+    data: Buffer | Uint8Array | string,
+    options?: NixxiePutOptions
+  ): Promise<NixxieStoredFile> {
+    const body = typeof data === 'string' ? Buffer.from(data) : Buffer.from(data)
+    const file = this.file(key)
+    await file.save(body, {
+      contentType: options?.contentType,
+      metadata: options?.metadata ? { metadata: options.metadata } : undefined,
+    })
+    if (options?.public) await file.makePublic()
+    return { key, url: this.url(key), size: body.byteLength, contentType: options?.contentType }
+  }
+
+  async get(key: string): Promise<Buffer | undefined> {
+    try {
+      const [contents] = await this.file(key).download()
+      return contents as Buffer
+    } catch (err: any) {
+      if (err?.code === 404) return undefined
+      throw err
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.file(key).delete({ ignoreNotFound: true })
+  }
+
+  async has(key: string): Promise<boolean> {
+    const [exists] = await this.file(key).exists()
+    return Boolean(exists)
+  }
+
+  url(key: string): string {
+    if (this.config.publicBaseUrl)
+      return `${this.config.publicBaseUrl.replace(/\/$/, '')}/${this.prefix}${key}`
+    return `https://storage.googleapis.com/${this.config.bucket}/${this.prefix}${key}`
+  }
+
+  async signedUrl(key: string, options?: NixxieSignedUrlOptions): Promise<string> {
+    const [url] = await this.file(key).getSignedUrl({
+      action: options?.operation === 'put' ? 'write' : 'read',
+      expires: Date.now() + (options?.expiresIn ?? 900) * 1000,
+      contentType: options?.operation === 'put' ? options?.contentType : undefined,
+    })
+    return url as string
+  }
+
+  async list(prefix = ''): Promise<string[]> {
+    const [files] = await this.bucket.getFiles({ prefix: `${this.prefix}${prefix}` })
+    return files
+      .map((f: any) => f.name as string)
+      .map((k: string) => (this.prefix && k.startsWith(this.prefix) ? k.slice(this.prefix.length) : k))
+  }
+}