@c9up/ream 0.1.3

package/src/session/drivers/MemoryDriver.ts

@@ -0,0 +1,29 @@
+import type { SessionDriver } from '../Session.js'
+
+export class MemoryDriver implements SessionDriver {
+  private store: Map<string, { data: Record<string, unknown>; expiresAt: number }> = new Map()
+
+  async read(sessionId: string): Promise<Record<string, unknown>> {
+    const entry = this.store.get(sessionId)
+    if (!entry || entry.expiresAt < Date.now()) {
+      this.store.delete(sessionId)
+      return {}
+    }
+    return { ...entry.data }
+  }
+
+  async write(sessionId: string, data: Record<string, unknown>, ttl: number): Promise<void> {
+    this.store.set(sessionId, { data, expiresAt: Date.now() + ttl * 1000 })
+  }
+
+  async destroy(sessionId: string): Promise<void> {
+    this.store.delete(sessionId)
+  }
+
+  async touch(sessionId: string, ttl: number): Promise<void> {
+    const entry = this.store.get(sessionId)
+    if (entry) {
+      entry.expiresAt = Date.now() + ttl * 1000
+    }
+  }
+}

package/src/storage/S3Driver.ts

@@ -0,0 +1,171 @@
+/**
+ * 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/StaticMiddleware.ts

@@ -0,0 +1,182 @@
+/**
+ * Static file serving middleware.
+ *
+ * Serves files from a directory with cache headers and ETag support.
+ *
+ * Usage:
+ *   server.use(new StaticMiddleware({ root: 'public' }))
+ *
+ * @implements MISS-25
+ */
+
+import { createHash } from 'node:crypto'
+import * as fs from 'node:fs'
+import * as path from 'node:path'
+import type { HttpContext } from '../http/HttpContext.js'
+
+export interface StaticConfig {
+  /** Root directory to serve files from. */
+  root: string
+  /** URL prefix (default: /static). */
+  prefix?: string
+  /** Max-age for Cache-Control header in seconds (default: 86400 = 1 day). */
+  maxAge?: number
+  /** File extensions to serve (default: common web assets). */
+  extensions?: string[]
+}
+
+const DEFAULT_EXTENSIONS = [
+  '.html',
+  '.css',
+  '.js',
+  '.json',
+  '.xml',
+  '.txt',
+  '.png',
+  '.jpg',
+  '.jpeg',
+  '.gif',
+  '.svg',
+  '.ico',
+  '.webp',
+  '.woff',
+  '.woff2',
+  '.ttf',
+  '.eot',
+  '.mp4',
+  '.webm',
+  '.mp3',
+  '.ogg',
+  '.pdf',
+  '.zip',
+]
+
+const MIME_TYPES: Record<string, string> = {
+  '.html': 'text/html',
+  '.css': 'text/css',
+  '.js': 'application/javascript',
+  '.json': 'application/json',
+  '.xml': 'application/xml',
+  '.txt': 'text/plain',
+  '.png': 'image/png',
+  '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.ico': 'image/x-icon',
+  '.webp': 'image/webp',
+  '.woff': 'font/woff',
+  '.woff2': 'font/woff2',
+  '.ttf': 'font/ttf',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.mp4': 'video/mp4',
+  '.webm': 'video/webm',
+  '.mp3': 'audio/mpeg',
+  '.ogg': 'audio/ogg',
+  '.pdf': 'application/pdf',
+  '.zip': 'application/zip',
+}
+
+export class StaticMiddleware {
+  #root: string
+  #prefix: string
+  #maxAge: number
+  #extensions: Set<string>
+
+  constructor(config: StaticConfig) {
+    this.#root = path.resolve(config.root)
+    this.#prefix = config.prefix ?? '/static'
+    this.#maxAge = config.maxAge ?? 86400
+    this.#extensions = new Set(config.extensions ?? DEFAULT_EXTENSIONS)
+  }
+
+  async handle(ctx: HttpContext, next: () => Promise<void>): Promise<void> {
+    if (ctx.request.method() !== 'GET' && ctx.request.method() !== 'HEAD') {
+      return next()
+    }
+
+    const resolved = this.#resolveServableFile(ctx.request.path())
+    if (!resolved) return next()
+    const { realFilePath, ext, stat } = resolved
+
+    const etag = createHash('md5').update(`${stat.size}-${stat.mtimeMs}`).digest('hex')
+
+    // ETag check — 304 Not Modified
+    const ifNoneMatch = ctx.request.header('if-none-match')
+    if (ifNoneMatch === etag) {
+      ctx.response.status(304)
+      return
+    }
+
+    const mime = MIME_TYPES[ext] ?? 'application/octet-stream'
+    ctx.response.header('Content-Type', mime)
+    ctx.response.header('Content-Length', String(stat.size))
+    ctx.response.header('Cache-Control', `public, max-age=${this.#maxAge}`)
+    ctx.response.header('ETag', etag)
+
+    if (ctx.request.method() === 'HEAD') {
+      ctx.response.status(200)
+      return
+    }
+
+    // Send the raw Buffer — `content.toString()` would interpret PNG /
+    // PDF / ZIP bytes as UTF-8 and replace any byte the encoding can't
+    // round-trip (anything in the surrogate range, plus invalid
+    // sequences) with U+FFFD.
+    const content = fs.readFileSync(realFilePath)
+    ctx.response.status(200).sendBuffer(content)
+  }
+
+  /**
+   * Resolve a request path to a real, in-root, existing file, or `null` when it
+   * is not servable (wrong prefix/extension, outside the root, missing, or a
+   * symlink escaping the root). Returning `null` tells `handle` to call `next()`.
+   */
+  #resolveServableFile(
+    reqPath: string,
+  ): { realFilePath: string; ext: string; stat: fs.Stats } | null {
+    // Match only when the prefix is followed by `/` or end-of-path —
+    // otherwise `/staticx/foo.js` would be intercepted when the configured
+    // prefix is `/static`, hijacking unrelated routes.
+    if (!(reqPath === this.#prefix || reqPath.startsWith(`${this.#prefix}/`))) {
+      return null
+    }
+
+    // Strip prefix and resolve file path
+    const relativePath = reqPath.slice(this.#prefix.length) || '/index.html'
+    const ext = path.extname(relativePath).toLowerCase()
+    if (!this.#extensions.has(ext)) return null
+
+    const filePath = path.resolve(this.#root, relativePath.replace(/^\//, ''))
+
+    // Two containment checks. The first uses `path.sep` to reject sibling
+    // directories with a shared prefix (`/var/www-static-secret` slipping
+    // past a guard for `/var/www-static`). The second resolves symlinks
+    // via realpathSync so a symlink planted inside the root cannot point
+    // outside it. We do realpath AFTER the lexical check so a non-existent
+    // path returns `next()` rather than throwing.
+    const rootWithSep = this.#root.endsWith(path.sep) ? this.#root : this.#root + path.sep
+    if (filePath !== this.#root && !filePath.startsWith(rootWithSep)) {
+      return null
+    }
+
+    if (!fs.existsSync(filePath) || !fs.statSync(filePath).isFile()) {
+      return null
+    }
+
+    let realFilePath: string
+    let realRoot: string
+    try {
+      realFilePath = fs.realpathSync(filePath)
+      realRoot = fs.realpathSync(this.#root)
+    } catch {
+      return null
+    }
+    const realRootWithSep = realRoot.endsWith(path.sep) ? realRoot : realRoot + path.sep
+    if (realFilePath !== realRoot && !realFilePath.startsWith(realRootWithSep)) {
+      return null
+    }
+
+    return { realFilePath, ext, stat: fs.statSync(realFilePath) }
+  }
+}

package/src/storage/StaticProvider.ts

@@ -0,0 +1,40 @@
+/**
+ * `StaticProvider` — serves static files from a directory.
+ *
+ * Opt-in: does nothing unless `config.static.root` is set (or a middleware is
+ * injected for tests). When configured, `boot()` mounts a global
+ * `StaticMiddleware` (path-traversal + symlink-escape guarded) that serves
+ * matching requests and falls through (`next()`) otherwise.
+ *
+ *   // config/static.ts
+ *   export default { root: 'public', prefix: '/static' }
+ *
+ * @implements MISS-25
+ */
+
+import type { AppContext } from '../Provider.js'
+import { Provider } from '../Provider.js'
+import type { Server } from '../server/Server.js'
+import { type StaticConfig, StaticMiddleware } from './StaticMiddleware.js'
+
+export interface StaticProviderOptions {
+  /** Override the `StaticMiddleware` instance — used by tests. */
+  middleware?: StaticMiddleware
+}
+
+export class StaticProvider extends Provider {
+  readonly #override?: StaticMiddleware
+
+  constructor(app: AppContext, options: StaticProviderOptions = {}) {
+    super(app)
+    this.#override = options.middleware
+  }
+
+  override async boot(): Promise<void> {
+    const config = this.app.config.get<StaticConfig>('static')
+    const middleware = this.#override ?? (config?.root ? new StaticMiddleware(config) : undefined)
+    if (!middleware) return // not configured — opt-out
+    const server = this.app.container.make<Server>('server')
+    server.use([(ctx, next) => middleware.handle(ctx, next)])
+  }
+}

package/src/storage/StorageManager.ts

@@ -0,0 +1,142 @@
+/**
+ * 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)
+  }
+}