@c9up/ream 0.1.3

package/dist/storage/S3Driver.js

@@ -0,0 +1,135 @@
+/**
+ * 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';
+/**
+ * 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) {
+    return key
+        .split('/')
+        .map((segment) => encodeURIComponent(segment).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`))
+        .join('/');
+}
+export class S3Driver {
+    #config;
+    #endpoint;
+    constructor(config) {
+        this.#config = config;
+        this.#endpoint = config.endpoint ?? `https://s3.${config.region ?? 'us-east-1'}.amazonaws.com`;
+    }
+    async put(filePath, content) {
+        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 });
+        if (!res.ok) {
+            throw new Error(`S3 PUT failed (${res.status}): ${await res.text()}`);
+        }
+    }
+    async get(filePath) {
+        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) {
+        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) {
+        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) {
+        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, key, body) {
+        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 = {
+            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;
+    }
+}
+//# sourceMappingURL=S3Driver.js.map

package/dist/storage/S3Driver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"S3Driver.js","sourceRoot":"","sources":["../../src/storage/S3Driver.ts"],"names":[],"mappings":"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"}

package/dist/storage/StaticMiddleware.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 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[];
+}
+export declare class StaticMiddleware {
+    #private;
+    constructor(config: StaticConfig);
+    handle(ctx: HttpContext, next: () => Promise<void>): Promise<void>;
+}
+//# sourceMappingURL=StaticMiddleware.d.ts.map

package/dist/storage/StaticMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StaticMiddleware.d.ts","sourceRoot":"","sources":["../../src/storage/StaticMiddleware.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAA;AAEzD,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,IAAI,EAAE,MAAM,CAAA;IACZ,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACtB;AAsDD,qBAAa,gBAAgB;;gBAMf,MAAM,EAAE,YAAY;IAO1B,MAAM,CAAC,GAAG,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC;CAyFzE"}

package/dist/storage/StaticMiddleware.js

@@ -0,0 +1,153 @@
+/**
+ * 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';
+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 = {
+    '.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;
+    #prefix;
+    #maxAge;
+    #extensions;
+    constructor(config) {
+        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, next) {
+        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) {
+        // 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;
+        let realRoot;
+        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) };
+    }
+}
+//# sourceMappingURL=StaticMiddleware.js.map

package/dist/storage/StaticMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StaticMiddleware.js","sourceRoot":"","sources":["../../src/storage/StaticMiddleware.ts"],"names":[],"mappings":"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"}

package/dist/storage/StaticProvider.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `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 { StaticMiddleware } from './StaticMiddleware.js';
+export interface StaticProviderOptions {
+    /** Override the `StaticMiddleware` instance — used by tests. */
+    middleware?: StaticMiddleware;
+}
+export declare class StaticProvider extends Provider {
+    #private;
+    constructor(app: AppContext, options?: StaticProviderOptions);
+    boot(): Promise<void>;
+}
+//# sourceMappingURL=StaticProvider.d.ts.map

package/dist/storage/StaticProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StaticProvider.d.ts","sourceRoot":"","sources":["../../src/storage/StaticProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAA;AAChD,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC,OAAO,EAAqB,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAE3E,MAAM,WAAW,qBAAqB;IACpC,gEAAgE;IAChE,UAAU,CAAC,EAAE,gBAAgB,CAAA;CAC9B;AAED,qBAAa,cAAe,SAAQ,QAAQ;;gBAG9B,GAAG,EAAE,UAAU,EAAE,OAAO,GAAE,qBAA0B;IAKjD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAOrC"}

package/dist/storage/StaticProvider.js

@@ -0,0 +1,31 @@
+/**
+ * `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 { Provider } from '../Provider.js';
+import { StaticMiddleware } from './StaticMiddleware.js';
+export class StaticProvider extends Provider {
+    #override;
+    constructor(app, options = {}) {
+        super(app);
+        this.#override = options.middleware;
+    }
+    async boot() {
+        const config = this.app.config.get('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.use([(ctx, next) => middleware.handle(ctx, next)]);
+    }
+}
+//# sourceMappingURL=StaticProvider.js.map

package/dist/storage/StaticProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StaticProvider.js","sourceRoot":"","sources":["../../src/storage/StaticProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAA;AAEzC,OAAO,EAAqB,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAO3E,MAAM,OAAO,cAAe,SAAQ,QAAQ;IACjC,SAAS,CAAmB;IAErC,YAAY,GAAe,EAAE,UAAiC,EAAE;QAC9D,KAAK,CAAC,GAAG,CAAC,CAAA;QACV,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,UAAU,CAAA;IACrC,CAAC;IAEQ,KAAK,CAAC,IAAI;QACjB,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,GAAG,CAAe,QAAQ,CAAC,CAAA;QAC1D,MAAM,UAAU,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;QAC9F,IAAI,CAAC,UAAU;YAAE,OAAM,CAAC,2BAA2B;QACnD,MAAM,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,IAAI,CAAS,QAAQ,CAAC,CAAA;QACxD,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,CAAC,UAAU,CAAC,MAAM,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC,CAAA;IAC3D,CAAC;CACF"}

package/dist/storage/StorageManager.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Storage — file storage abstraction with driver pattern.
+ *
+ * @implements MISS-24
+ */
+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 declare class LocalDriver implements StorageDriver {
+    #private;
+    constructor(root: string);
+    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 declare class StorageManager {
+    #private;
+    constructor(driver: 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;
+}
+//# sourceMappingURL=StorageManager.d.ts.map

package/dist/storage/StorageManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageManager.d.ts","sourceRoot":"","sources":["../../src/storage/StorageManager.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAsDH,MAAM,WAAW,aAAa;IAC5B,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC9D,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAA;IAC7C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAC1C,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAAA;CAC9B;AAED,qBAAa,WAAY,YAAW,aAAa;;gBAGnC,IAAI,EAAE,MAAM;IAOlB,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAS9D,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAM7C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO1C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAYhD,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAG9B;AAED,qBAAa,cAAc;;gBAGb,MAAM,EAAE,aAAa;IAIjC,GAAG,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI9D,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAI7C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAI1C,GAAG,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;CAG9B"}

package/dist/storage/StorageManager.js

@@ -0,0 +1,120 @@
+/**
+ * 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, filePath) {
+    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) {
+    let current = full;
+    while (!fs.existsSync(current)) {
+        const parent = path.dirname(current);
+        if (parent === current)
+            return current;
+        current = parent;
+    }
+    return current;
+}
+export class LocalDriver {
+    #root;
+    constructor(root) {
+        this.#root = root;
+        if (!fs.existsSync(root)) {
+            fs.mkdirSync(root, { recursive: true });
+        }
+    }
+    async put(filePath, content) {
+        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) {
+        const full = assertWithinRoot(this.#root, filePath);
+        if (!fs.existsSync(full))
+            return null;
+        return fs.readFileSync(full);
+    }
+    async delete(filePath) {
+        const full = assertWithinRoot(this.#root, filePath);
+        if (!fs.existsSync(full))
+            return false;
+        fs.unlinkSync(full);
+        return true;
+    }
+    async exists(filePath) {
+        let full;
+        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) {
+        return `/storage/${filePath}`;
+    }
+}
+export class StorageManager {
+    #driver;
+    constructor(driver) {
+        this.#driver = driver;
+    }
+    put(filePath, content) {
+        return this.#driver.put(filePath, content);
+    }
+    get(filePath) {
+        return this.#driver.get(filePath);
+    }
+    delete(filePath) {
+        return this.#driver.delete(filePath);
+    }
+    exists(filePath) {
+        return this.#driver.exists(filePath);
+    }
+    url(filePath) {
+        return this.#driver.url(filePath);
+    }
+}
+//# sourceMappingURL=StorageManager.js.map

package/dist/storage/StorageManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"StorageManager.js","sourceRoot":"","sources":["../../src/storage/StorageManager.ts"],"names":[],"mappings":"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"}

package/dist/testing/RequestBuilder.d.ts

@@ -0,0 +1,67 @@
+import type { TestResponse } from './TestClient.js';
+/**
+ * Fluent HTTP request builder with assertion methods.
+ *
+ *   await client
+ *     .fluent('GET', '/api/users/42')
+ *     .withAuth(user)
+ *     .expectStatus(200)
+ *     .expectJson({ id: 42 })
+ *
+ * The builder chains: setters return `this`, assertion methods send the
+ * request on first call (memoised) and return a `Promise<this>` so further
+ * assertions can be awaited or chained via `await`.
+ */
+export interface AuthSubject {
+    /** String or numeric user id — used by `withAuth` / `asUser` to sign the session. */
+    id: string | number;
+    /** Optional custom headers added to the request (e.g. tenant markers). */
+    extraHeaders?: Record<string, string>;
+}
+export interface AuthStrategy {
+    /** Compute the headers Warden expects for this user (Bearer token / session cookie / ...). */
+    headersFor(subject: AuthSubject): Record<string, string> | Promise<Record<string, string>>;
+    /** Compute cookies for session-based strategies. */
+    cookiesFor?(subject: AuthSubject): Record<string, string> | Promise<Record<string, string>>;
+}
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+/**
+ * Internal low-level sender — matches what the TestClient exposes.
+ * Accepting it as an injected callable keeps RequestBuilder framework-agnostic.
+ */
+export type HttpSender = (method: HttpMethod, path: string, init: {
+    headers: Record<string, string>;
+    body: Buffer;
+}) => Promise<TestResponse>;
+export declare class RequestBuilder {
+    #private;
+    constructor(sender: HttpSender, method: HttpMethod, path: string, authStrategy?: AuthStrategy | null);
+    headers(map: Record<string, string>): this;
+    header(name: string, value: string): this;
+    json(data: unknown): this;
+    body(data: Buffer | string, contentType?: string): this;
+    form(data: Record<string, string>): this;
+    cookies(map: Record<string, string>): this;
+    cookie(name: string, value: string): this;
+    /**
+     * Attach auth for a user. Uses the strategy passed to `client`'s `auth`
+     * option — Warden's session/JWT/API-key strategy decides the header/cookie
+     * shape. Without a strategy, throws at send time.
+     */
+    withAuth(subject: AuthSubject): this;
+    /** Shortcut for `withAuth({ id: userId })` — user is identified by id only. */
+    asUser(userId: string | number): this;
+    /** Fire the request (once) and return the raw response. Idempotent. */
+    send(): Promise<TestResponse>;
+    expectStatus(code: number): Promise<this>;
+    expectHeader(name: string, value: string | RegExp): Promise<this>;
+    expectCookie(name: string, value?: string | RegExp): Promise<this>;
+    expectJson(expected: unknown): Promise<this>;
+}
+/**
+ * Partial deep-match. For objects, every key in `expected` must match in
+ * `actual`. For arrays, every element in `expected` must match SOMEWHERE in
+ * `actual` (order-independent). Primitives compared by strict equality.
+ */
+export declare function partialMatch(actual: unknown, expected: unknown): boolean;
+//# sourceMappingURL=RequestBuilder.d.ts.map

package/dist/testing/RequestBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestBuilder.d.ts","sourceRoot":"","sources":["../../src/testing/RequestBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAA;AAEnD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,WAAW;IAC1B,qFAAqF;IACrF,EAAE,EAAE,MAAM,GAAG,MAAM,CAAA;IACnB,0EAA0E;IAC1E,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACtC;AAED,MAAM,WAAW,YAAY;IAC3B,8FAA8F;IAC9F,UAAU,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IAC1F,oDAAoD;IACpD,UAAU,CAAC,CAAC,OAAO,EAAE,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CAC5F;AAUD,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAA;AAEpE;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE;IACJ,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,IAAI,EAAE,MAAM,CAAA;CACb,KACE,OAAO,CAAC,YAAY,CAAC,CAAA;AAE1B,qBAAa,cAAc;;gBAYvB,MAAM,EAAE,UAAU,EAClB,MAAM,EAAE,UAAU,EAClB,IAAI,EAAE,MAAM,EACZ,YAAY,GAAE,YAAY,GAAG,IAAW;IAQ1C,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAO1C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKzC,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAMzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI;IAMvD,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IASxC,OAAO,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAK1C,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAKzC;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAKpC,+EAA+E;IAC/E,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAKrC,uEAAuE;IACvE,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC;IAKvB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAUzC,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAkBjE,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAuBlE,UAAU,CAAC,QAAQ,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC;CAoDnD;AAWD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,OAAO,GAAG,OAAO,CAcxE"}