@nixxie-cms/storage 1.0.1

package/src/LocalStorage.ts

@@ -0,0 +1,99 @@
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, readdir, rm, stat, writeFile } from 'node:fs/promises'
+import { dirname, join, posix, relative, resolve, sep } from 'node:path'
+import type {
+  NixxiePutOptions,
+  NixxieSignedUrlOptions,
+  NixxieStorageService,
+  NixxieStoredFile,
+} from '@nixxie-cms/core'
+import type { LocalStorageConfig } from './types'
+
+/**
+ * Filesystem-backed storage. Good for development and single-node deployments.
+ * `signedUrl()` falls back to the plain public URL since the local disk cannot sign.
+ */
+export class LocalStorage implements NixxieStorageService {
+  private baseDir: string
+  private baseUrl: string
+
+  constructor(config: LocalStorageConfig) {
+    this.baseDir = config.baseDir ?? '.nixxie-storage'
+    this.baseUrl = (config.baseUrl ?? '/files').replace(/\/$/, '')
+  }
+
+  private path(key: string): string {
+    // 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: string,
+    data: Buffer | Uint8Array | string,
+    options?: NixxiePutOptions
+  ): Promise<NixxieStoredFile> {
+    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?.contentType,
+    }
+  }
+
+  async get(key: string): Promise<Buffer | undefined> {
+    const filePath = this.path(key)
+    if (!existsSync(filePath)) return undefined
+    return readFile(filePath)
+  }
+
+  async delete(key: string): Promise<void> {
+    await rm(this.path(key), { force: true })
+  }
+
+  async has(key: string): Promise<boolean> {
+    try {
+      await stat(this.path(key))
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  url(key: string): string {
+    return `${this.baseUrl}/${key.split(sep).join('/')}`
+  }
+
+  async signedUrl(key: string, _options?: NixxieSignedUrlOptions): Promise<string> {
+    return this.url(key)
+  }
+
+  async list(prefix = ''): Promise<string[]> {
+    const root = this.baseDir
+    const out: string[] = []
+    const walk = async (dir: string) => {
+      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))
+  }
+}

package/src/S3Storage.ts

@@ -0,0 +1,138 @@
+import type {
+  NixxiePutOptions,
+  NixxieSignedUrlOptions,
+  NixxieStorageService,
+  NixxieStoredFile,
+} from '@nixxie-cms/core'
+import type { S3StorageConfig } from './types'
+
+type S3Module = typeof import('@aws-sdk/client-s3')
+type PresignerModule = typeof import('@aws-sdk/s3-request-presigner')
+
+function loadS3(): { s3: S3Module; presigner: PresignerModule } {
+  try {
+    return {
+      s3: require('@aws-sdk/client-s3') as S3Module,
+      presigner: require('@aws-sdk/s3-request-presigner') as PresignerModule,
+    }
+  } 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. */
+export class S3Storage implements NixxieStorageService {
+  private config: S3StorageConfig
+  private prefix: string
+  private client: InstanceType<S3Module['S3Client']>
+  private s3: S3Module
+  private presigner: PresignerModule
+
+  constructor(config: S3StorageConfig) {
+    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,
+    })
+  }
+
+  private k(key: string): string {
+    return `${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.client.send(
+      new this.s3.PutObjectCommand({
+        Bucket: this.config.bucket,
+        Key: this.k(key),
+        Body: body,
+        ContentType: options?.contentType,
+        ACL: options?.public ? 'public-read' : undefined,
+        Metadata: options?.metadata,
+      })
+    )
+    return { key, url: this.url(key), size: body.byteLength, contentType: options?.contentType }
+  }
+
+  async get(key: string): Promise<Buffer | undefined> {
+    try {
+      const res = await this.client.send(
+        new this.s3.GetObjectCommand({ Bucket: this.config.bucket, Key: this.k(key) })
+      )
+      const bytes = await res.Body?.transformToByteArray()
+      return bytes ? Buffer.from(bytes) : undefined
+    } catch (err: any) {
+      if (err?.name === 'NoSuchKey' || err?.$metadata?.httpStatusCode === 404) return undefined
+      throw err
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    await this.client.send(
+      new this.s3.DeleteObjectCommand({ Bucket: this.config.bucket, Key: this.k(key) })
+    )
+  }
+
+  async has(key: string): Promise<boolean> {
+    try {
+      await this.client.send(
+        new this.s3.HeadObjectCommand({ Bucket: this.config.bucket, Key: this.k(key) })
+      )
+      return true
+    } catch {
+      return false
+    }
+  }
+
+  url(key: string): string {
+    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 ?? 'us-east-1'}.amazonaws.com`
+    return `${host}/${this.k(key)}`
+  }
+
+  async signedUrl(key: string, options?: NixxieSignedUrlOptions): Promise<string> {
+    const command =
+      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 as any, command as any, {
+      expiresIn: options?.expiresIn ?? 900,
+    })
+  }
+
+  async list(prefix = ''): Promise<string[]> {
+    const res = await this.client.send(
+      new this.s3.ListObjectsV2Command({
+        Bucket: this.config.bucket,
+        Prefix: this.k(prefix),
+      })
+    )
+    return (res.Contents ?? [])
+      .map(o => o.Key ?? '')
+      .map(k => (this.prefix && k.startsWith(this.prefix) ? k.slice(this.prefix.length) : k))
+      .filter(Boolean)
+  }
+}

package/src/index.ts

@@ -0,0 +1,39 @@
+import type { StorageConfig } from './types'
+import { AzureStorage } from './AzureStorage'
+import { GcsStorage } from './GcsStorage'
+import { LocalStorage } from './LocalStorage'
+import { S3Storage } from './S3Storage'
+
+export function createStorage(
+  config: StorageConfig
+): LocalStorage | S3Storage | GcsStorage | AzureStorage {
+  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: never = config
+      throw new Error(`Unknown storage driver: ${(exhaustive as any).driver}`)
+    }
+  }
+}
+
+export { LocalStorage, S3Storage, GcsStorage, AzureStorage }
+export type {
+  StorageConfig,
+  LocalStorageConfig,
+  S3StorageConfig,
+  GcsStorageConfig,
+  AzureStorageConfig,
+} from './types'
+export type {
+  NixxieStorageService,
+  NixxieStoredFile,
+  NixxiePutOptions,
+  NixxieSignedUrlOptions,
+} from '@nixxie-cms/core'

package/src/types.ts

@@ -0,0 +1,68 @@
+import type {
+  NixxiePutOptions,
+  NixxieSignedUrlOptions,
+  NixxieStorageService,
+  NixxieStoredFile,
+} from '@nixxie-cms/core'
+
+export type { NixxiePutOptions, NixxieSignedUrlOptions, NixxieStorageService, NixxieStoredFile }
+
+export type LocalStorageConfig = {
+  driver: 'local'
+  /** Directory on disk where files are written. Default: '.nixxie-storage' */
+  baseDir?: string
+  /** Public URL prefix that maps to `baseDir`, e.g. 'http://localhost:3000/files'. Default: '/files' */
+  baseUrl?: string
+}
+
+export type S3StorageConfig = {
+  driver: 's3'
+  /** Target bucket name. */
+  bucket: string
+  /** AWS region. */
+  region?: string
+  /** Access key id — falls back to the AWS SDK default credential chain when omitted. */
+  accessKeyId?: string
+  /** Secret access key. */
+  secretAccessKey?: string
+  /** Custom endpoint (for S3-compatible services like R2, MinIO, Spaces). */
+  endpoint?: string
+  /** Force path-style addressing (required by most S3-compatible services). */
+  forcePathStyle?: boolean
+  /** Key prefix applied to every object. */
+  prefix?: string
+  /** Public base URL used by `url()` when objects are public / served via CDN. */
+  publicBaseUrl?: string
+}
+
+export type GcsStorageConfig = {
+  driver: 'gcs'
+  /** Target bucket name. */
+  bucket: string
+  /** GCP project id. */
+  projectId?: string
+  /** Path to a service-account key file. */
+  keyFilename?: string
+  /** Key prefix applied to every object. */
+  prefix?: string
+  /** Public base URL used by `url()`. */
+  publicBaseUrl?: string
+}
+
+export type AzureStorageConfig = {
+  driver: 'azure'
+  /** Blob container name. */
+  container: string
+  /** Full connection string for the storage account. */
+  connectionString: string
+  /** Key prefix applied to every blob. */
+  prefix?: string
+  /** Public base URL used by `url()`. */
+  publicBaseUrl?: string
+}
+
+export type StorageConfig =
+  | LocalStorageConfig
+  | S3StorageConfig
+  | GcsStorageConfig
+  | AzureStorageConfig