@c9up/ream 0.1.7 → 0.1.8

package/src/storage/S3Driver.ts

@@ -1,171 +0,0 @@
-/**
- * S3Driver — S3-compatible cloud storage (AWS S3, Cloudflare R2, MinIO).
- *
- * Uses fetch API — no external SDK dependency.
- * Implements the StorageDriver interface.
- *
- * @implements MISS-24
- */
-
-import { createHash, createHmac } from 'node:crypto'
-import type { StorageDriver } from './StorageManager.js'
-
-/**
- * URI-encode an S3 object key for use in BOTH the request URL and the
- * SigV4 canonical path. Each `/`-delimited segment is percent-encoded
- * (so the slashes that delimit the key hierarchy survive), which means
- * spaces, `#`, `?`, `%` and non-ASCII bytes can't slip the requested
- * path away from the signed path — the classic "key with a space gets
- * a SignatureDoesNotMatch / 403, or `?`/`#` truncates the path" bug.
- *
- * S3 expects the canonical URI encoded ONCE (unlike the generic SigV4
- * double-encode), and `encodeURIComponent` already escapes the RFC 3986
- * sub-delims AWS cares about. We additionally escape `!`, `'`, `(`,
- * `)`, `*` which `encodeURIComponent` leaves untouched but AWS expects
- * percent-encoded.
- */
-function encodeS3Key(key: string): string {
-  return key
-    .split('/')
-    .map((segment) =>
-      encodeURIComponent(segment).replace(
-        /[!'()*]/g,
-        (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`,
-      ),
-    )
-    .join('/')
-}
-
-export interface S3Config {
-  bucket: string
-  region?: string
-  endpoint?: string
-  accessKeyId: string
-  secretAccessKey: string
-  publicUrl?: string
-}
-
-export class S3Driver implements StorageDriver {
-  #config: S3Config
-  #endpoint: string
-
-  constructor(config: S3Config) {
-    this.#config = config
-    this.#endpoint = config.endpoint ?? `https://s3.${config.region ?? 'us-east-1'}.amazonaws.com`
-  }
-
-  async put(filePath: string, content: Buffer | string): Promise<void> {
-    const body = typeof content === 'string' ? Buffer.from(content) : content
-    const key = encodeS3Key(filePath)
-    const url = `${this.#endpoint}/${this.#config.bucket}/${key}`
-    const headers = this.#signRequest('PUT', key, body)
-
-    const res = await fetch(url, { method: 'PUT', headers, body: body as unknown as BodyInit })
-    if (!res.ok) {
-      throw new Error(`S3 PUT failed (${res.status}): ${await res.text()}`)
-    }
-  }
-
-  async get(filePath: string): Promise<Buffer | null> {
-    const key = encodeS3Key(filePath)
-    const url = `${this.#endpoint}/${this.#config.bucket}/${key}`
-    const headers = this.#signRequest('GET', key)
-
-    const res = await fetch(url, { method: 'GET', headers })
-    if (res.status === 404) return null
-    if (!res.ok) throw new Error(`S3 GET failed (${res.status})`)
-
-    const arrayBuffer = await res.arrayBuffer()
-    return Buffer.from(arrayBuffer)
-  }
-
-  async delete(filePath: string): Promise<boolean> {
-    const key = encodeS3Key(filePath)
-    const url = `${this.#endpoint}/${this.#config.bucket}/${key}`
-    const headers = this.#signRequest('DELETE', key)
-
-    const res = await fetch(url, { method: 'DELETE', headers })
-    return res.ok || res.status === 204
-  }
-
-  async exists(filePath: string): Promise<boolean> {
-    const key = encodeS3Key(filePath)
-    const url = `${this.#endpoint}/${this.#config.bucket}/${key}`
-    const headers = this.#signRequest('HEAD', key)
-
-    const res = await fetch(url, { method: 'HEAD', headers })
-    return res.ok
-  }
-
-  url(filePath: string): string {
-    const key = encodeS3Key(filePath)
-    if (this.#config.publicUrl) {
-      return `${this.#config.publicUrl}/${key}`
-    }
-    return `${this.#endpoint}/${this.#config.bucket}/${key}`
-  }
-
-  /**
-   * Sign a request with AWS Signature V4 (simplified).
-   * For production, consider using @aws-sdk/signature-v4 for full compliance.
-   */
-  #signRequest(method: string, key: string, body?: Buffer): Record<string, string> {
-    const now = new Date()
-    const dateStamp = `${now.toISOString().replace(/[-:]/g, '').split('.')[0]}Z`
-    const shortDate = dateStamp.slice(0, 8)
-    const region = this.#config.region ?? 'us-east-1'
-    const service = 's3'
-
-    const payloadHash = createHash('sha256')
-      .update(body ?? '')
-      .digest('hex')
-
-    const headers: Record<string, string> = {
-      host: new URL(this.#endpoint).host,
-      'x-amz-date': dateStamp,
-      'x-amz-content-sha256': payloadHash,
-    }
-
-    if (body) {
-      headers['content-length'] = String(body.length)
-    }
-
-    // Canonical request
-    const signedHeaders = Object.keys(headers).sort().join(';')
-    const canonicalHeaders = Object.keys(headers)
-      .sort()
-      .map((k) => `${k}:${headers[k]}\n`)
-      .join('')
-    const canonicalRequest = [
-      method,
-      `/${this.#config.bucket}/${key}`,
-      '',
-      canonicalHeaders,
-      signedHeaders,
-      payloadHash,
-    ].join('\n')
-
-    // String to sign
-    const scope = `${shortDate}/${region}/${service}/aws4_request`
-    const stringToSign = [
-      'AWS4-HMAC-SHA256',
-      dateStamp,
-      scope,
-      createHash('sha256').update(canonicalRequest).digest('hex'),
-    ].join('\n')
-
-    // Signing key
-    const kDate = createHmac('sha256', `AWS4${this.#config.secretAccessKey}`)
-      .update(shortDate)
-      .digest()
-    const kRegion = createHmac('sha256', kDate).update(region).digest()
-    const kService = createHmac('sha256', kRegion).update(service).digest()
-    const kSigning = createHmac('sha256', kService).update('aws4_request').digest()
-
-    const signature = createHmac('sha256', kSigning).update(stringToSign).digest('hex')
-
-    headers.authorization = `AWS4-HMAC-SHA256 Credential=${this.#config.accessKeyId}/${scope}, SignedHeaders=${signedHeaders}, Signature=${signature}`
-
-    return headers
-  }
-}

package/src/storage/StorageManager.ts

@@ -1,142 +0,0 @@
-/**
- * Storage — file storage abstraction with driver pattern.
- *
- * @implements MISS-24
- */
-
-import * as fs from 'node:fs'
-import * as path from 'node:path'
-
-/**
- * Resolve `filePath` against `root` and reject any result that escapes
- * the storage root. Without this guard a user-controlled path like
- * `../secrets.env` would let put/get/delete/exists touch arbitrary
- * files outside the configured storage root.
- *
- * The lexical check (`path.resolve` + `startsWith`) catches the
- * `../` / absolute-path class. The realpath re-check catches the
- * symlink-escape class: a symlink planted under the root (or anywhere
- * else on the resolved path's chain) that points outside the root
- * would pass the lexical gate but be caught here.
- *
- * We canonicalize the longest existing ancestor of `full` — `realpath`
- * itself throws ENOENT on a target that doesn't exist yet (the `put`
- * happy-path for new files). Symlinks anywhere ABOVE the leaf are
- * still dereferenced, which is the only escape vector that matters:
- * the driver creates the leaf itself, so no symlink can pre-exist
- * there.
- */
-function assertWithinRoot(root: string, filePath: string): string {
-  const full = path.resolve(root, filePath)
-  const rootAbs = path.resolve(root)
-  if (full !== rootAbs && !full.startsWith(rootAbs + path.sep)) {
-    throw new Error(`[ream-storage] path '${filePath}' escapes the storage root (E_PATH_TRAVERSAL)`)
-  }
-  const canonicalRoot = fs.existsSync(rootAbs) ? fs.realpathSync(rootAbs) : rootAbs
-  const ancestor = longestExistingAncestor(full)
-  const canonicalAncestor = ancestor === full ? fs.realpathSync(full) : fs.realpathSync(ancestor)
-  // Re-attach the not-yet-existing leaf to the canonicalized ancestor.
-  const canonicalFull = canonicalAncestor + full.slice(ancestor.length)
-  if (canonicalFull !== canonicalRoot && !canonicalFull.startsWith(canonicalRoot + path.sep)) {
-    throw new Error(
-      `[ream-storage] path '${filePath}' escapes the storage root via a symlink (E_PATH_TRAVERSAL)`,
-    )
-  }
-  return full
-}
-
-/** Walk up `full` until we find a path that exists on disk. */
-function longestExistingAncestor(full: string): string {
-  let current = full
-  while (!fs.existsSync(current)) {
-    const parent = path.dirname(current)
-    if (parent === current) return current
-    current = parent
-  }
-  return current
-}
-
-export interface StorageDriver {
-  put(filePath: string, content: Buffer | string): Promise<void>
-  get(filePath: string): Promise<Buffer | null>
-  delete(filePath: string): Promise<boolean>
-  exists(filePath: string): Promise<boolean>
-  url(filePath: string): string
-}
-
-export class LocalDriver implements StorageDriver {
-  #root: string
-
-  constructor(root: string) {
-    this.#root = root
-    if (!fs.existsSync(root)) {
-      fs.mkdirSync(root, { recursive: true })
-    }
-  }
-
-  async put(filePath: string, content: Buffer | string): Promise<void> {
-    const full = assertWithinRoot(this.#root, filePath)
-    const dir = path.dirname(full)
-    if (!fs.existsSync(dir)) {
-      fs.mkdirSync(dir, { recursive: true })
-    }
-    fs.writeFileSync(full, content)
-  }
-
-  async get(filePath: string): Promise<Buffer | null> {
-    const full = assertWithinRoot(this.#root, filePath)
-    if (!fs.existsSync(full)) return null
-    return fs.readFileSync(full)
-  }
-
-  async delete(filePath: string): Promise<boolean> {
-    const full = assertWithinRoot(this.#root, filePath)
-    if (!fs.existsSync(full)) return false
-    fs.unlinkSync(full)
-    return true
-  }
-
-  async exists(filePath: string): Promise<boolean> {
-    let full: string
-    try {
-      full = assertWithinRoot(this.#root, filePath)
-    } catch {
-      // exists() must NOT leak existence of out-of-root paths via the
-      // thrown error — quietly report "no" for any traversal attempt.
-      return false
-    }
-    return fs.existsSync(full)
-  }
-
-  url(filePath: string): string {
-    return `/storage/${filePath}`
-  }
-}
-
-export class StorageManager {
-  #driver: StorageDriver
-
-  constructor(driver: StorageDriver) {
-    this.#driver = driver
-  }
-
-  put(filePath: string, content: Buffer | string): Promise<void> {
-    return this.#driver.put(filePath, content)
-  }
-
-  get(filePath: string): Promise<Buffer | null> {
-    return this.#driver.get(filePath)
-  }
-
-  delete(filePath: string): Promise<boolean> {
-    return this.#driver.delete(filePath)
-  }
-
-  exists(filePath: string): Promise<boolean> {
-    return this.#driver.exists(filePath)
-  }
-
-  url(filePath: string): string {
-    return this.#driver.url(filePath)
-  }
-}