@velajs/storage 0.2.0

package/dist/middleware/versioning.js

@@ -0,0 +1,89 @@
+import { StorageError } from "../storage.error.js";
+import { passthrough } from "./wrap.js";
+export const VERSIONED = Symbol.for('vela.storage.versioned');
+/**
+ * Keeps prior versions on overwrite via key-suffixing (no external manifest →
+ * no read-modify-write race). Snapshots are cheap when the base driver
+ * `supportsServerSideCopy`. Direct presigned uploads bypass snapshotting, so
+ * `signedUploadUrl` throws. Reach `listVersions`/`restore`/`deleteVersion` via
+ * {@link unwrapVersioning}.
+ */ export function versioning(opts = {}) {
+    const prefix = opts.prefix ?? '.vela-versions/';
+    let seq = 0;
+    const vid = opts.versionId ?? (()=>`${Date.now().toString(36)}-${(seq++).toString(36)}`);
+    const vkey = (key, id)=>`${prefix}${key}/${id}`;
+    const isVersion = (key)=>key.startsWith(prefix);
+    const listVersions = async (inner, key)=>{
+        const res = await inner.list({
+            prefix: `${prefix}${key}/`
+        });
+        return res.items.map((item)=>({
+                versionId: item.key.slice(item.key.lastIndexOf('/') + 1),
+                key: item.key,
+                size: item.size,
+                lastModified: item.lastModified
+            }));
+    };
+    const snapshot = async (inner, key)=>{
+        if (!await inner.exists(key)) return;
+        const id = vid();
+        if (inner.supportsServerSideCopy) {
+            await inner.copy(key, vkey(key, id));
+        } else {
+            const current = await inner.download(key);
+            await inner.upload(vkey(key, id), current.stream(), {
+                contentType: current.type
+            });
+        }
+        if (opts.maxVersions) {
+            const versions = (await listVersions(inner, key)).sort((a, b)=>a.versionId < b.versionId ? -1 : 1);
+            for (const v of versions.slice(0, Math.max(0, versions.length - opts.maxVersions))){
+                await inner.delete(v.key);
+            }
+        }
+    };
+    return (inner)=>{
+        const driver = passthrough(inner, {
+            async upload (k, b, o) {
+                await snapshot(inner, k);
+                return inner.upload(k, b, o);
+            },
+            async copy (f, t, o) {
+                await snapshot(inner, t);
+                return inner.copy(f, t, o);
+            },
+            async delete (k, o) {
+                if (opts.onDelete !== 'purge') await snapshot(inner, k);
+                await inner.delete(k, o);
+                if (opts.onDelete === 'purge') {
+                    for (const v of (await listVersions(inner, k)))await inner.delete(v.key);
+                }
+            },
+            list: opts.hideFromList === false ? undefined : async (o)=>{
+                const res = await inner.list(o);
+                return {
+                    items: res.items.filter((i)=>!isVersion(i.key)),
+                    prefixes: res.prefixes?.filter((p)=>!isVersion(p)),
+                    cursor: res.cursor
+                };
+            },
+            signedUploadUrl () {
+                throw new StorageError('Unsupported', 'versioning: direct uploads bypass snapshots');
+            }
+        });
+        const versioned = {
+            listVersions: (key)=>listVersions(inner, key),
+            async restore (key, versionId) {
+                await snapshot(inner, key);
+                await inner.copy(vkey(key, versionId), key);
+            },
+            deleteVersion: (key, versionId)=>inner.delete(vkey(key, versionId))
+        };
+        return Object.assign(driver, {
+            [VERSIONED]: versioned
+        });
+    };
+}
+/** Retrieve the {@link Versioned} surface from a versioning-wrapped driver (or `undefined`). */ export function unwrapVersioning(driver) {
+    return driver[VERSIONED];
+}

package/dist/middleware/wrap.d.ts

@@ -0,0 +1,11 @@
+import type { StorageDriver } from '../storage.types';
+/** A driver middleware: wraps a driver, returns a driver. */
+export type Middleware = (inner: StorageDriver) => StorageDriver;
+/**
+ * Build a driver that delegates to `inner`, applying `over` overrides and
+ * omitting the methods in `omit`. Explicit delegation (not spread) keeps
+ * class-based drivers' `this`. Optional methods are forwarded only when the
+ * inner driver has them (so `presence == capability` is preserved), unless
+ * omitted (e.g. a body-transforming middleware suppresses multipart/presign).
+ */
+export declare function passthrough(inner: StorageDriver, over?: Partial<StorageDriver>, omit?: ReadonlyArray<keyof StorageDriver>): StorageDriver;

package/dist/middleware/wrap.js

@@ -0,0 +1,46 @@
+/**
+ * Build a driver that delegates to `inner`, applying `over` overrides and
+ * omitting the methods in `omit`. Explicit delegation (not spread) keeps
+ * class-based drivers' `this`. Optional methods are forwarded only when the
+ * inner driver has them (so `presence == capability` is preserved), unless
+ * omitted (e.g. a body-transforming middleware suppresses multipart/presign).
+ */ export function passthrough(inner, over = {}, omit = []) {
+    const omitted = new Set(omit);
+    const has = (k)=>!omitted.has(k);
+    const d = {
+        name: over.name ?? inner.name,
+        raw: inner.raw,
+        reportsUploadProgress: over.reportsUploadProgress ?? inner.reportsUploadProgress,
+        supportsRange: over.supportsRange ?? inner.supportsRange,
+        supportsDelimiter: over.supportsDelimiter ?? inner.supportsDelimiter,
+        supportsMetadata: over.supportsMetadata ?? inner.supportsMetadata,
+        supportsCacheControl: over.supportsCacheControl ?? inner.supportsCacheControl,
+        supportsServerSideCopy: over.supportsServerSideCopy ?? inner.supportsServerSideCopy,
+        signedUrl: over.signedUrl ?? inner.signedUrl,
+        upload: over.upload ?? ((k, b, o)=>inner.upload(k, b, o)),
+        download: over.download ?? ((k, o)=>inner.download(k, o)),
+        head: over.head ?? ((k, o)=>inner.head(k, o)),
+        exists: over.exists ?? ((k, o)=>inner.exists(k, o)),
+        delete: over.delete ?? ((k, o)=>inner.delete(k, o)),
+        copy: over.copy ?? ((f, t, o)=>inner.copy(f, t, o)),
+        list: over.list ?? ((o)=>inner.list(o)),
+        url: over.url ?? ((k, o)=>inner.url(k, o)),
+        signedUploadUrl: over.signedUploadUrl ?? ((k, o)=>inner.signedUploadUrl(k, o))
+    };
+    if (has('deleteMany') && (over.deleteMany || inner.deleteMany)) {
+        d.deleteMany = over.deleteMany ?? ((ks, o)=>inner.deleteMany(ks, o));
+    }
+    if (has('move') && (over.move || inner.move)) {
+        d.move = over.move ?? ((f, t, o)=>inner.move(f, t, o));
+    }
+    if (has('createMultipartUpload') && (over.createMultipartUpload || inner.createMultipartUpload)) {
+        d.createMultipartUpload = over.createMultipartUpload ?? ((k, o)=>inner.createMultipartUpload(k, o));
+    }
+    if (has('resumeMultipartUpload') && (over.resumeMultipartUpload || inner.resumeMultipartUpload)) {
+        d.resumeMultipartUpload = over.resumeMultipartUpload ?? ((k, u)=>inner.resumeMultipartUpload(k, u));
+    }
+    if (has('signedMultipart') && (over.signedMultipart || inner.signedMultipart)) {
+        d.signedMultipart = over.signedMultipart ?? inner.signedMultipart;
+    }
+    return d;
+}

package/dist/object-key.d.ts

@@ -0,0 +1,17 @@
+/**
+ * True when `key` is a safe object key:
+ * - non-empty, not longer than 1024 bytes (S3's limit)
+ * - no leading `/`
+ * - no `.` / `..` path segments (traversal)
+ * - no control characters
+ * - no backslashes (Windows-style separators)
+ */
+export declare function isSafeKey(key: string): boolean;
+/** Return `key` if safe, else throw `StorageError('InvalidKey')`. */
+export declare function sanitizeKey(key: string): string;
+/** Normalize a prefix: drop leading/trailing slashes, collapse to '' when empty. */
+export declare function normalizePrefix(prefix: string | undefined): string;
+/** Join a normalized prefix and a key with a single '/'. */
+export declare function joinKey(prefix: string, key: string): string;
+/** Strip a normalized prefix from a stored key (for surfacing to callers). */
+export declare function stripPrefix(prefix: string, key: string): string;

package/dist/object-key.js

@@ -0,0 +1,42 @@
+import { StorageError } from "./storage.error.js";
+// Object-key hygiene shared by the facade (prefix scoping) and the HTTP
+// controller (post-authorize re-sanitization). The rules block the classic
+// traversal / injection footguns without being so strict that legitimate
+// keys (nested "folders", dots, spaces) are rejected.
+// Control characters: C0 range (0x00-0x1F) plus DEL (0x7F).
+const CONTROL_CHARS = /[\u0000-\u001f\u007f]/;
+/**
+ * True when `key` is a safe object key:
+ * - non-empty, not longer than 1024 bytes (S3's limit)
+ * - no leading `/`
+ * - no `.` / `..` path segments (traversal)
+ * - no control characters
+ * - no backslashes (Windows-style separators)
+ */ export function isSafeKey(key) {
+    if (typeof key !== 'string' || key.length === 0 || key.length > 1024) return false;
+    if (key.startsWith('/')) return false;
+    if (key.includes('\\')) return false;
+    if (CONTROL_CHARS.test(key)) return false;
+    for (const segment of key.split('/')){
+        if (segment === '.' || segment === '..') return false;
+    }
+    return true;
+}
+/** Return `key` if safe, else throw `StorageError('InvalidKey')`. */ export function sanitizeKey(key) {
+    if (!isSafeKey(key)) {
+        throw new StorageError('InvalidKey', `unsafe object key: ${JSON.stringify(key)}`);
+    }
+    return key;
+}
+/** Normalize a prefix: drop leading/trailing slashes, collapse to '' when empty. */ export function normalizePrefix(prefix) {
+    if (!prefix) return '';
+    return prefix.replace(/^\/+/, '').replace(/\/+$/, '');
+}
+/** Join a normalized prefix and a key with a single '/'. */ export function joinKey(prefix, key) {
+    return prefix ? `${prefix}/${key}` : key;
+}
+/** Strip a normalized prefix from a stored key (for surfacing to callers). */ export function stripPrefix(prefix, key) {
+    if (!prefix) return key;
+    const withSlash = `${prefix}/`;
+    return key.startsWith(withSlash) ? key.slice(withSlash.length) : key;
+}

package/dist/storage.controller.d.ts

@@ -0,0 +1,21 @@
+import { type Token, type Type } from '@velajs/vela';
+import type { StorageService } from './storage.service';
+import type { StorageAuthorizer } from './http/authorizer.types';
+export interface ResolvedHttpOptions {
+    driverName: string;
+    authorize?: StorageAuthorizer;
+    defaultPolicy: 'deny' | 'allow';
+    download: 'redirect' | 'proxy';
+    defaultExpiresIn: number;
+    maxExpiresIn: number;
+    maxUploadSize?: number;
+    maxListLimit: number;
+    deleteConcurrency: number;
+}
+/**
+ * Build a vela controller exposing presigned/multipart upload + download
+ * endpoints for one bucket. Factory-decorated (like better-auth's catch-all)
+ * so `basePath` bakes in at decoration time. Consumes the {@link StorageService}
+ * facade so gating/retry/prefix apply uniformly on the HTTP path.
+ */
+export declare function createStorageController(basePath: string, serviceToken: Token<StorageService>, http: ResolvedHttpOptions): Type;

package/dist/storage.controller.js

@@ -0,0 +1,380 @@
+function _ts_decorate(decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for(var i = decorators.length - 1; i >= 0; i--)if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+function _ts_metadata(k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+function _ts_param(paramIndex, decorator) {
+    return function(target, key) {
+        decorator(target, key, paramIndex);
+    };
+}
+import { Controller, Get, Inject, Injectable, Post, Req } from "@velajs/vela";
+import { sanitizeKey } from "./object-key.js";
+import { StorageError } from "./storage.error.js";
+import { clampExpiry, dispositionHeader, mapError, parseRange, serializeStored } from "./http/http-helpers.js";
+/**
+ * Build a vela controller exposing presigned/multipart upload + download
+ * endpoints for one bucket. Factory-decorated (like better-auth's catch-all)
+ * so `basePath` bakes in at decoration time. Consumes the {@link StorageService}
+ * facade so gating/retry/prefix apply uniformly on the HTTP path.
+ */ export function createStorageController(basePath, serviceToken, http) {
+    let StorageController = class StorageController {
+        svc;
+        constructor(svc){
+            this.svc = svc;
+        }
+        get storage() {
+            return this.svc.storage;
+        }
+        async authorize(c, action) {
+            if (!http.authorize) {
+                if (http.defaultPolicy === 'allow') return {};
+                throw new StorageError('AccessDenied', 'storage: no authorizer configured (default deny)');
+            }
+            const res = await http.authorize(action, {
+                req: c.req.raw,
+                ctx: c,
+                driver: http.driverName
+            });
+            if (res === false) throw new StorageError('AccessDenied', 'not allowed');
+            if (res === true) return {};
+            return res;
+        }
+        fail(c, e) {
+            const err = e instanceof StorageError ? e : StorageError.wrap(e);
+            const { wire, status } = mapError(err.code);
+            return c.json({
+                error: {
+                    code: wire,
+                    message: err.message
+                }
+            }, status);
+        }
+        async signUpload(c) {
+            try {
+                const b = await c.req.json();
+                const ov = await this.authorize(c, {
+                    type: 'sign-upload',
+                    key: b.key,
+                    contentType: b.contentType,
+                    size: b.size
+                });
+                const key = sanitizeKey(ov.key ?? b.key);
+                const upload = await this.storage.signedUploadUrl(key, {
+                    expiresIn: clampExpiry(ov.expiresIn ?? b.expiresIn, http.defaultExpiresIn, http.maxExpiresIn),
+                    contentType: b.contentType,
+                    maxSize: ov.maxSize ?? http.maxUploadSize
+                });
+                return c.json({
+                    key,
+                    upload
+                });
+            } catch (e) {
+                return this.fail(c, e);
+            }
+        }
+        async multipartCreate(c) {
+            try {
+                const b = await c.req.json();
+                const ov = await this.authorize(c, {
+                    type: 'multipart-create',
+                    key: b.key,
+                    contentType: b.contentType
+                });
+                const key = sanitizeKey(ov.key ?? b.key);
+                const sm = this.storage.signedMultipart;
+                if (!sm) throw new StorageError('Unsupported', 'presigned multipart not supported');
+                const created = await sm.create(key, {
+                    contentType: b.contentType,
+                    metadata: ov.metadata ?? b.metadata,
+                    partSize: b.partSize
+                });
+                return c.json({
+                    key,
+                    uploadId: created.uploadId,
+                    partSize: created.partSize
+                });
+            } catch (e) {
+                return this.fail(c, e);
+            }
+        }
+        async multipartSignPart(c) {
+            try {
+                const b = await c.req.json();
+                const ov = await this.authorize(c, {
+                    type: 'multipart-sign-part',
+                    key: b.key,
+                    uploadId: b.uploadId,
+                    partNumber: b.partNumber
+                });
+                const key = sanitizeKey(ov.key ?? b.key);
+                const sm = this.storage.signedMultipart;
+                if (!sm) throw new StorageError('Unsupported', 'presigned multipart not supported');
+                const part = await sm.signPart(key, b.uploadId, b.partNumber, {
+                    expiresIn: clampExpiry(ov.expiresIn, http.defaultExpiresIn, http.maxExpiresIn)
+                });
+                return c.json({
+                    partNumber: b.partNumber,
+                    method: 'PUT',
+                    url: part.url,
+                    headers: part.headers
+                });
+            } catch (e) {
+                return this.fail(c, e);
+            }
+        }
+        async multipartComplete(c) {
+            try {
+                const b = await c.req.json();
+                const ov = await this.authorize(c, {
+                    type: 'multipart-complete',
+                    key: b.key,
+                    uploadId: b.uploadId
+                });
+                const key = sanitizeKey(ov.key ?? b.key);
+                const sm = this.storage.signedMultipart;
+                if (!sm) throw new StorageError('Unsupported', 'presigned multipart not supported');
+                return c.json(await sm.complete(key, b.uploadId, b.parts));
+            } catch (e) {
+                return this.fail(c, e);
+            }
+        }
+        async multipartAbort(c) {
+            try {
+                const b = await c.req.json();
+                const ov = await this.authorize(c, {
+                    type: 'multipart-abort',
+                    key: b.key,
+                    uploadId: b.uploadId
+                });
+                const key = sanitizeKey(ov.key ?? b.key);
+                const sm = this.storage.signedMultipart;
+                if (!sm) throw new StorageError('Unsupported', 'presigned multipart not supported');
+                await sm.abort(key, b.uploadId);
+                return c.json({
+                    ok: true
+                });
+            } catch (e) {
+                return this.fail(c, e);
+            }
+        }
+        async list(c) {
+            try {
+                const prefix = c.req.query('prefix');
+                const ov = await this.authorize(c, {
+                    type: 'list',
+                    prefix
+                });
+                const limit = c.req.query('limit');
+                const res = await this.storage.list({
+                    prefix: ov.prefix ?? prefix,
+                    cursor: c.req.query('cursor'),
+                    delimiter: c.req.query('delimiter'),
+                    limit: limit ? Math.min(Number(limit), http.maxListLimit) : undefined
+                });
+                return c.json({
+                    items: res.items.map(serializeStored),
+                    prefixes: res.prefixes,
+                    cursor: res.cursor
+                });
+            } catch (e) {
+                return this.fail(c, e);
+            }
+        }
+        async head(c) {
+            try {
+                const key = sanitizeKey(c.req.query('key') ?? '');
+                const ov = await this.authorize(c, {
+                    type: 'head',
+                    key
+                });
+                const file = await this.storage.head(sanitizeKey(ov.key ?? key));
+                return c.json(serializeStored(file));
+            } catch (e) {
+                return this.fail(c, e);
+            }
+        }
+        async delete(c) {
+            try {
+                const b = await c.req.json();
+                const keys = b.keys.map((k)=>sanitizeKey(k));
+                const ov = await this.authorize(c, {
+                    type: 'delete',
+                    keys
+                });
+                const effective = (ov.keys ?? keys).map((k)=>sanitizeKey(k));
+                return c.json(await this.storage.delete(effective, {
+                    concurrency: http.deleteConcurrency
+                }));
+            } catch (e) {
+                return this.fail(c, e);
+            }
+        }
+        async download(c) {
+            try {
+                const key = sanitizeKey(c.req.query('key') ?? '');
+                const disp = c.req.query('disposition');
+                const ov = await this.authorize(c, {
+                    type: 'download',
+                    key
+                });
+                const ekey = sanitizeKey(ov.key ?? key);
+                const name = ekey.slice(ekey.lastIndexOf('/') + 1);
+                if (http.download === 'redirect' && this.storage.capabilities.signedUrl.supported) {
+                    const url = await this.storage.url(ekey, {
+                        expiresIn: clampExpiry(ov.expiresIn, http.defaultExpiresIn, http.maxExpiresIn),
+                        responseContentDisposition: dispositionHeader(disp, name)
+                    });
+                    return c.redirect(url, 302);
+                }
+                const range = parseRange(c.req.header('range'));
+                const file = await this.storage.download(ekey, range ? {
+                    range
+                } : undefined);
+                const headers = new Headers({
+                    'content-type': file.type,
+                    'content-length': String(file.size),
+                    'content-disposition': dispositionHeader(disp, file.name)
+                });
+                if (file.etag) headers.set('etag', file.etag);
+                if (range) {
+                    headers.set('content-range', `bytes ${range.start}-${range.start + file.size - 1}/*`);
+                    return new Response(file.stream(), {
+                        status: 206,
+                        headers
+                    });
+                }
+                return new Response(file.stream(), {
+                    status: 200,
+                    headers
+                });
+            } catch (e) {
+                return this.fail(c, e);
+            }
+        }
+        async signDownload(c) {
+            try {
+                const b = await c.req.json();
+                const ov = await this.authorize(c, {
+                    type: 'download',
+                    key: b.key
+                });
+                const key = sanitizeKey(ov.key ?? b.key);
+                const expiresIn = clampExpiry(ov.expiresIn ?? b.expiresIn, http.defaultExpiresIn, http.maxExpiresIn);
+                const url = await this.storage.url(key, {
+                    expiresIn
+                });
+                return c.json({
+                    url,
+                    expiresAt: Date.now() + expiresIn * 1000
+                });
+            } catch (e) {
+                return this.fail(c, e);
+            }
+        }
+    };
+    _ts_decorate([
+        Post('/sign-upload'),
+        _ts_param(0, Req()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Context === "undefined" ? Object : Context
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], StorageController.prototype, "signUpload", null);
+    _ts_decorate([
+        Post('/multipart/create'),
+        _ts_param(0, Req()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Context === "undefined" ? Object : Context
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], StorageController.prototype, "multipartCreate", null);
+    _ts_decorate([
+        Post('/multipart/sign-part'),
+        _ts_param(0, Req()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Context === "undefined" ? Object : Context
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], StorageController.prototype, "multipartSignPart", null);
+    _ts_decorate([
+        Post('/multipart/complete'),
+        _ts_param(0, Req()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Context === "undefined" ? Object : Context
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], StorageController.prototype, "multipartComplete", null);
+    _ts_decorate([
+        Post('/multipart/abort'),
+        _ts_param(0, Req()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Context === "undefined" ? Object : Context
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], StorageController.prototype, "multipartAbort", null);
+    _ts_decorate([
+        Get('/list'),
+        _ts_param(0, Req()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Context === "undefined" ? Object : Context
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], StorageController.prototype, "list", null);
+    _ts_decorate([
+        Get('/head'),
+        _ts_param(0, Req()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Context === "undefined" ? Object : Context
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], StorageController.prototype, "head", null);
+    _ts_decorate([
+        Post('/delete'),
+        _ts_param(0, Req()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Context === "undefined" ? Object : Context
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], StorageController.prototype, "delete", null);
+    _ts_decorate([
+        Get('/download'),
+        _ts_param(0, Req()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Context === "undefined" ? Object : Context
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], StorageController.prototype, "download", null);
+    _ts_decorate([
+        Post('/sign-download'),
+        _ts_param(0, Req()),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof Context === "undefined" ? Object : Context
+        ]),
+        _ts_metadata("design:returntype", Promise)
+    ], StorageController.prototype, "signDownload", null);
+    StorageController = _ts_decorate([
+        Controller(basePath),
+        Injectable(),
+        _ts_param(0, Inject(serviceToken)),
+        _ts_metadata("design:type", Function),
+        _ts_metadata("design:paramtypes", [
+            typeof StorageService === "undefined" ? Object : StorageService
+        ])
+    ], StorageController);
+    return StorageController;
+}

package/dist/storage.error.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The single error taxonomy for `@velajs/storage`. Every driver maps its
+ * provider/transport failures onto a {@link StorageErrorCode}; the facade's
+ * capability gates throw `Unsupported`; the retry loop keys off
+ * {@link StorageError.retryable}; and the HTTP controller maps codes to
+ * status via its own `codeToHttp()` table.
+ */
+export type StorageErrorCode = 'NotFound' | 'AccessDenied' | 'Unsupported' | 'ReadOnly' | 'InvalidKey' | 'InvalidRequest' | 'Conflict' | 'RateLimited' | 'Network' | 'Timeout' | 'Aborted' | 'Provider' | 'Parse';
+export interface StorageErrorOptions {
+    cause?: unknown;
+    /** Underlying HTTP status, when the failure came from a transport response. */
+    status?: number;
+    /** Override the default retryability implied by {@link StorageErrorCode}. */
+    retryable?: boolean;
+}
+export declare class StorageError extends Error {
+    name: string;
+    readonly code: StorageErrorCode;
+    readonly retryable: boolean;
+    readonly status: number | undefined;
+    constructor(code: StorageErrorCode, message: string, options?: StorageErrorOptions);
+    /** Wrap an arbitrary thrown value as a `StorageError` (idempotent). */
+    static wrap(e: unknown): StorageError;
+    /** Map a transport status code to a `StorageError` (5xx/429 retryable). */
+    static fromStatus(status: number, message: string, cause?: unknown): StorageError;
+}
+/** True for `AbortError`-shaped values (DOMException or `{ name: 'AbortError' }`). */
+export declare function isAbort(e: unknown): boolean;