@velajs/storage 0.2.0

package/dist/drivers/s3/s3.driver.js

@@ -0,0 +1,404 @@
+import { byteLengthOf } from "../../internal/body.js";
+import { createStoredFile } from "../../internal/stored-file.js";
+import { StorageError } from "../../storage.error.js";
+import { S3Client } from "./s3-client.js";
+import { escapeXml, tagBlocks, tagText } from "./xml.js";
+const encoder = new TextEncoder();
+const DEFAULT_EXPIRES = 3600;
+const DEFAULT_PART_SIZE = 5 * 1024 * 1024;
+function stripQuotes(s) {
+    return s ? s.replace(/^"|"$/g, '') : undefined;
+}
+function parseDate(s) {
+    if (!s) return undefined;
+    const t = Date.parse(s);
+    return Number.isFinite(t) ? t : undefined;
+}
+function formatRange(range) {
+    return `bytes=${range.start}-${range.end ?? ''}`;
+}
+function metaFromHeaders(headers) {
+    const meta = {};
+    headers.forEach((value, key)=>{
+        if (key.startsWith('x-amz-meta-')) meta[key.slice('x-amz-meta-'.length)] = value;
+    });
+    return Object.keys(meta).length ? meta : undefined;
+}
+function joinPublic(base, key) {
+    const enc = key.split('/').map(encodeURIComponent).join('/');
+    return `${base.replace(/\/$/, '')}/${enc}`;
+}
+/** Map an S3 `<Code>` (and/or HTTP status) to our error taxonomy. */ function mapS3Code(code, status) {
+    switch(code){
+        case 'NoSuchKey':
+        case 'NoSuchUpload':
+        case 'NoSuchBucket':
+            return 'NotFound';
+        case 'AccessDenied':
+        case 'InvalidAccessKeyId':
+        case 'SignatureDoesNotMatch':
+        case 'AllAccessDisabled':
+            return 'AccessDenied';
+        case 'SlowDown':
+        case 'RequestTimeout':
+            return 'RateLimited';
+        default:
+            break;
+    }
+    if (status === 404) return 'NotFound';
+    if (status === 403 || status === 401) return 'AccessDenied';
+    if (status === 409) return 'Conflict';
+    if (status === 429) return 'RateLimited';
+    if (status >= 500) return 'Provider';
+    if (status >= 400) return 'InvalidRequest';
+    return 'Provider'; // e.g. a 200 response carrying an <Error> body
+}
+function toError(status, code, message, key) {
+    const mapped = mapS3Code(code, status);
+    const retryable = mapped === 'Provider' || mapped === 'RateLimited' || mapped === 'Timeout' || mapped === 'Network';
+    return new StorageError(mapped, message ?? code ?? `S3 error${key ? ` (${key})` : ''}`, {
+        status: status >= 400 ? status : undefined,
+        retryable
+    });
+}
+async function s3Error(res, key) {
+    let code;
+    let message;
+    try {
+        const body = await res.text();
+        code = tagText(body, 'Code');
+        message = tagText(body, 'Message');
+    } catch  {
+    /* ignore body read errors */ }
+    return toError(res.status, code, message, key);
+}
+function parseErrorBody(status, body, key) {
+    return toError(status, tagText(body, 'Code'), tagText(body, 'Message'), key);
+}
+/** Add `duplex: 'half'` when streaming a request body (required by fetch). */ function withDuplex(init, body) {
+    if (body instanceof ReadableStream) {
+        return {
+            ...init,
+            duplex: 'half'
+        };
+    }
+    return init;
+}
+/** S3 / S3-compatible driver signed with aws4fetch (edge-safe). */ export function s3Driver(options) {
+    const client = new S3Client(options);
+    const expires = options.defaultUrlExpiresIn ?? DEFAULT_EXPIRES;
+    function uploadHeaders(opts, unsignedPayload) {
+        const h = new Headers();
+        if (unsignedPayload) h.set('x-amz-content-sha256', 'UNSIGNED-PAYLOAD');
+        if (opts?.contentType) h.set('content-type', opts.contentType);
+        if (opts?.cacheControl) h.set('cache-control', opts.cacheControl);
+        if (opts?.metadata) for (const [k, v] of Object.entries(opts.metadata))h.set(`x-amz-meta-${k}`, v);
+        return h;
+    }
+    function multipartHandle(key, uploadId, createOpts) {
+        return {
+            key,
+            uploadId,
+            async uploadPart (partNumber, part, o) {
+                const url = client.objectUrl(key, {
+                    partNumber: String(partNumber),
+                    uploadId
+                });
+                const res = await client.send(url, withDuplex({
+                    method: 'PUT',
+                    headers: new Headers({
+                        'x-amz-content-sha256': 'UNSIGNED-PAYLOAD'
+                    }),
+                    body: part,
+                    signal: o?.signal
+                }, part));
+                if (!res.ok) throw await s3Error(res, key);
+                const etag = res.headers.get('etag');
+                if (!etag) throw new StorageError('Provider', `missing ETag for part ${partNumber}`);
+                return {
+                    partNumber,
+                    etag
+                };
+            },
+            async complete (parts, o) {
+                const xml = '<?xml version="1.0" encoding="UTF-8"?><CompleteMultipartUpload>' + [
+                    ...parts
+                ].sort((a, b)=>a.partNumber - b.partNumber).map((p)=>`<Part><PartNumber>${p.partNumber}</PartNumber><ETag>${escapeXml(p.etag)}</ETag></Part>`).join('') + '</CompleteMultipartUpload>';
+                const res = await client.send(client.objectUrl(key, {
+                    uploadId
+                }), {
+                    method: 'POST',
+                    headers: new Headers({
+                        'content-type': 'application/xml'
+                    }),
+                    body: encoder.encode(xml),
+                    signal: o?.signal
+                });
+                const body = await res.text();
+                if (!res.ok || body.includes('<Error')) throw parseErrorBody(res.status, body, key);
+                return {
+                    key,
+                    size: 0,
+                    contentType: createOpts?.contentType ?? 'application/octet-stream',
+                    etag: stripQuotes(tagText(body, 'ETag'))
+                };
+            },
+            async abort (o) {
+                const res = await client.send(client.objectUrl(key, {
+                    uploadId
+                }), {
+                    method: 'DELETE',
+                    signal: o?.signal
+                });
+                if (!res.ok && res.status !== 404) throw await s3Error(res, key);
+            },
+            async listParts (o) {
+                const res = await client.send(client.objectUrl(key, {
+                    uploadId
+                }), {
+                    method: 'GET',
+                    signal: o?.signal
+                });
+                const xml = await res.text();
+                if (!res.ok) throw parseErrorBody(res.status, xml, key);
+                return tagBlocks(xml, 'Part').map((b)=>({
+                        partNumber: Number(tagText(b, 'PartNumber') ?? 0),
+                        etag: stripQuotes(tagText(b, 'ETag')) ?? '',
+                        size: Number(tagText(b, 'Size') ?? 0)
+                    }));
+            }
+        };
+    }
+    const signedMultipart = {
+        async create (key, o) {
+            const res = await client.send(client.objectUrl(key, {
+                uploads: ''
+            }), {
+                method: 'POST',
+                headers: uploadHeaders({
+                    contentType: o.contentType,
+                    metadata: o.metadata
+                }, false)
+            });
+            const xml = await res.text();
+            if (!res.ok) throw parseErrorBody(res.status, xml, key);
+            const uploadId = tagText(xml, 'UploadId');
+            if (!uploadId) throw new StorageError('Parse', 'missing UploadId');
+            return {
+                uploadId,
+                partSize: o.partSize ?? DEFAULT_PART_SIZE
+            };
+        },
+        async signPart (key, uploadId, partNumber, o) {
+            const url = await client.presign(key, 'PUT', o?.expiresIn ?? expires, {
+                partNumber: String(partNumber),
+                uploadId
+            });
+            return {
+                url
+            };
+        },
+        complete (key, uploadId, parts) {
+            return multipartHandle(key, uploadId).complete(parts);
+        },
+        abort (key, uploadId) {
+            return multipartHandle(key, uploadId).abort();
+        }
+    };
+    return {
+        name: options.name ?? 's3',
+        raw: client,
+        supportsRange: true,
+        supportsDelimiter: true,
+        supportsMetadata: true,
+        supportsCacheControl: true,
+        supportsServerSideCopy: true,
+        reportsUploadProgress: false,
+        signedUrl: {
+            supported: true,
+            upload: true
+        },
+        async upload (key, body, opts) {
+            const size = byteLengthOf(body) ?? 0;
+            const res = await client.send(client.objectUrl(key), withDuplex({
+                method: 'PUT',
+                headers: uploadHeaders(opts, true),
+                body: body,
+                signal: opts?.signal
+            }, body));
+            if (!res.ok) throw await s3Error(res, key);
+            return {
+                key,
+                size,
+                contentType: opts?.contentType ?? 'application/octet-stream',
+                etag: stripQuotes(res.headers.get('etag')),
+                lastModified: parseDate(res.headers.get('last-modified'))
+            };
+        },
+        async download (key, opts) {
+            const headers = new Headers();
+            if (opts?.range) headers.set('Range', formatRange(opts.range));
+            const res = await client.send(client.objectUrl(key), {
+                method: 'GET',
+                headers,
+                signal: opts?.signal
+            });
+            if (!res.ok || !res.body) {
+                if (res.status === 404) throw new StorageError('NotFound', `not found: ${key}`, {
+                    status: 404
+                });
+                throw await s3Error(res, key);
+            }
+            return createStoredFile({
+                key,
+                size: Number(res.headers.get('content-length') ?? 0),
+                type: res.headers.get('content-type') ?? 'application/octet-stream',
+                etag: stripQuotes(res.headers.get('etag')),
+                lastModified: parseDate(res.headers.get('last-modified')),
+                metadata: metaFromHeaders(res.headers)
+            }, {
+                kind: 'stream',
+                stream: res.body
+            });
+        },
+        async head (key, opts) {
+            const res = await client.send(client.objectUrl(key), {
+                method: 'HEAD',
+                signal: opts?.signal
+            });
+            if (!res.ok) {
+                if (res.status === 404) throw new StorageError('NotFound', `not found: ${key}`, {
+                    status: 404
+                });
+                throw await s3Error(res, key);
+            }
+            return createStoredFile({
+                key,
+                size: Number(res.headers.get('content-length') ?? 0),
+                type: res.headers.get('content-type') ?? 'application/octet-stream',
+                etag: stripQuotes(res.headers.get('etag')),
+                lastModified: parseDate(res.headers.get('last-modified')),
+                metadata: metaFromHeaders(res.headers)
+            }, {
+                kind: 'lazy',
+                fetch: ()=>client.send(client.objectUrl(key), {
+                        method: 'GET'
+                    })
+            });
+        },
+        async exists (key, opts) {
+            const res = await client.send(client.objectUrl(key), {
+                method: 'HEAD',
+                signal: opts?.signal
+            });
+            if (res.status === 404) return false;
+            if (!res.ok) throw await s3Error(res, key);
+            return true;
+        },
+        async delete (key, opts) {
+            const res = await client.send(client.objectUrl(key), {
+                method: 'DELETE',
+                signal: opts?.signal
+            });
+            if (!res.ok && res.status !== 404) throw await s3Error(res, key);
+        },
+        async copy (from, to, opts) {
+            const source = `/${client.bucket}/${from.split('/').map(encodeURIComponent).join('/')}`;
+            const res = await client.send(client.objectUrl(to), {
+                method: 'PUT',
+                headers: new Headers({
+                    'x-amz-copy-source': source
+                }),
+                signal: opts?.signal
+            });
+            const body = await res.text();
+            if (!res.ok || body.includes('<Error')) throw parseErrorBody(res.status, body, to);
+        },
+        async list (opts) {
+            const query = {
+                'list-type': '2'
+            };
+            if (opts?.prefix) query.prefix = opts.prefix;
+            if (opts?.delimiter) query.delimiter = opts.delimiter;
+            if (opts?.cursor) query['continuation-token'] = opts.cursor;
+            if (opts?.limit) query['max-keys'] = String(opts.limit);
+            const res = await client.send(client.objectUrl('', query), {
+                method: 'GET',
+                signal: opts?.signal
+            });
+            const xml = await res.text();
+            if (!res.ok) throw parseErrorBody(res.status, xml);
+            const items = tagBlocks(xml, 'Contents').map((b)=>{
+                const k = tagText(b, 'Key') ?? '';
+                return createStoredFile({
+                    key: k,
+                    size: Number(tagText(b, 'Size') ?? 0),
+                    type: 'application/octet-stream',
+                    etag: stripQuotes(tagText(b, 'ETag')),
+                    lastModified: parseDate(tagText(b, 'LastModified'))
+                }, {
+                    kind: 'lazy',
+                    fetch: ()=>client.send(client.objectUrl(k), {
+                            method: 'GET'
+                        })
+                });
+            });
+            const prefixes = tagBlocks(xml, 'CommonPrefixes').map((b)=>tagText(b, 'Prefix')).filter((p)=>!!p);
+            const cursor = tagText(xml, 'IsTruncated') === 'true' ? tagText(xml, 'NextContinuationToken') : undefined;
+            return {
+                items,
+                prefixes: prefixes.length ? prefixes : undefined,
+                cursor
+            };
+        },
+        async url (key, opts) {
+            const forceSign = !!opts?.responseContentDisposition;
+            if (options.publicBaseUrl && !forceSign) return joinPublic(options.publicBaseUrl, key);
+            const query = opts?.responseContentDisposition ? {
+                'response-content-disposition': opts.responseContentDisposition
+            } : undefined;
+            return client.presign(key, 'GET', opts?.expiresIn ?? expires, query);
+        },
+        async signedUploadUrl (key, opts) {
+            if (opts.maxSize != null || opts.minSize != null) {
+                const { url, fields } = await client.signPostPolicy(key, {
+                    expiresIn: opts.expiresIn,
+                    contentType: opts.contentType,
+                    maxSize: opts.maxSize,
+                    minSize: opts.minSize
+                });
+                return {
+                    method: 'POST',
+                    url,
+                    fields
+                };
+            }
+            const url = await client.presign(key, 'PUT', opts.expiresIn);
+            return {
+                method: 'PUT',
+                url,
+                headers: opts.contentType ? {
+                    'content-type': opts.contentType
+                } : undefined
+            };
+        },
+        async createMultipartUpload (key, opts) {
+            const res = await client.send(client.objectUrl(key, {
+                uploads: ''
+            }), {
+                method: 'POST',
+                headers: uploadHeaders(opts, false),
+                signal: opts?.signal
+            });
+            const xml = await res.text();
+            if (!res.ok) throw parseErrorBody(res.status, xml, key);
+            const uploadId = tagText(xml, 'UploadId');
+            if (!uploadId) throw new StorageError('Parse', 'missing UploadId');
+            return multipartHandle(key, uploadId, opts);
+        },
+        resumeMultipartUpload (key, uploadId) {
+            return multipartHandle(key, uploadId);
+        },
+        signedMultipart
+    };
+}

package/dist/drivers/s3/s3.types.d.ts

@@ -0,0 +1,28 @@
+export interface S3Credentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+export interface S3DriverOptions {
+    /**
+     * Service endpoint. Examples:
+     * - AWS:        `https://s3.us-east-1.amazonaws.com`
+     * - R2:         `https://<accountId>.r2.cloudflarestorage.com`
+     * - MinIO:      `http://localhost:9000`
+     */
+    endpoint: string;
+    /** AWS region (`auto` for R2). */
+    region: string;
+    bucket: string;
+    credentials: S3Credentials;
+    /** Path-style addressing (`endpoint/bucket/key`). Required by MinIO/R2/most non-AWS. */
+    forcePathStyle?: boolean;
+    /** CDN/public origin; when set, `url()` returns a permanent link unless signing is forced. */
+    publicBaseUrl?: string;
+    /** Default `expiresIn` (seconds) for presigned URLs. Default 3600. */
+    defaultUrlExpiresIn?: number;
+    /** Override the fetch implementation (tests). */
+    fetch?: typeof fetch;
+    /** Friendly driver name (defaults to `s3`). */
+    name?: string;
+}

package/dist/drivers/s3/s3.types.js

@@ -0,0 +1 @@
+export { };

package/dist/drivers/s3/xml.d.ts

@@ -0,0 +1,6 @@
+export declare function unescapeXml(s: string): string;
+export declare function escapeXml(s: string): string;
+/** First `<tag>…</tag>` inner text (entity-decoded), or `undefined`. */
+export declare function tagText(xml: string, tag: string): string | undefined;
+/** All `<tag>…</tag>` inner blocks (raw, not decoded — for nested extraction). */
+export declare function tagBlocks(xml: string, tag: string): string[];

package/dist/drivers/s3/xml.js

@@ -0,0 +1,52 @@
+// Dependency-free, edge-safe S3 XML helpers. Workers has no `DOMParser` and
+// the AWS XML parser is banned, so we extract from S3's fixed, shallow,
+// documented response shapes (ListBucketResult, Initiate/CompleteMultipartUpload,
+// Error, ...) with anchored, ReDoS-free regexes. We never parse untrusted XML.
+const ENTITIES = {
+    amp: '&',
+    lt: '<',
+    gt: '>',
+    quot: '"',
+    apos: "'"
+};
+export function unescapeXml(s) {
+    return s.replace(/&(#x?[0-9a-fA-F]+|amp|lt|gt|quot|apos);/g, (_m, e)=>{
+        if (e[0] === '#') {
+            const code = e[1] === 'x' ? Number.parseInt(e.slice(2), 16) : Number.parseInt(e.slice(1), 10);
+            return Number.isFinite(code) ? String.fromCodePoint(code) : _m;
+        }
+        return ENTITIES[e] ?? _m;
+    });
+}
+export function escapeXml(s) {
+    return s.replace(/[&<>"']/g, (c)=>{
+        switch(c){
+            case '&':
+                return '&amp;';
+            case '<':
+                return '&lt;';
+            case '>':
+                return '&gt;';
+            case '"':
+                return '&quot;';
+            default:
+                return '&apos;';
+        }
+    });
+}
+// Each pattern uses a single non-greedy `[\s\S]*?` bounded by a literal close
+// tag → linear time, no nested quantifiers, no catastrophic backtracking.
+function tagPattern(tag) {
+    return `<${tag}(?:\\s[^>]*)?>([\\s\\S]*?)</${tag}>`;
+}
+/** First `<tag>…</tag>` inner text (entity-decoded), or `undefined`. */ export function tagText(xml, tag) {
+    const m = new RegExp(tagPattern(tag)).exec(xml);
+    return m ? unescapeXml(m[1]) : undefined;
+}
+/** All `<tag>…</tag>` inner blocks (raw, not decoded — for nested extraction). */ export function tagBlocks(xml, tag) {
+    const re = new RegExp(tagPattern(tag), 'g');
+    const out = [];
+    let m;
+    while((m = re.exec(xml)) !== null)out.push(m[1]);
+    return out;
+}

package/dist/http/authorizer.types.d.ts

@@ -0,0 +1,59 @@
+import type { Context } from 'hono';
+/**
+ * The typed action a request wants to perform. The authorizer receives this
+ * and can deny, allow, or allow-with-overrides (rewriting the effective key /
+ * prefix / limits) — the load-bearing IDOR / cross-tenant guard.
+ */
+export type StorageAction = {
+    type: 'sign-upload';
+    key: string;
+    contentType?: string;
+    size?: number;
+} | {
+    type: 'multipart-create';
+    key: string;
+    contentType?: string;
+} | {
+    type: 'multipart-sign-part';
+    key: string;
+    uploadId: string;
+    partNumber: number;
+} | {
+    type: 'multipart-complete';
+    key: string;
+    uploadId: string;
+} | {
+    type: 'multipart-abort';
+    key: string;
+    uploadId: string;
+} | {
+    type: 'download';
+    key: string;
+} | {
+    type: 'head';
+    key: string;
+} | {
+    type: 'list';
+    prefix?: string;
+} | {
+    type: 'delete';
+    keys: string[];
+};
+export interface StorageAuthContext {
+    /** The raw Web `Request` (edge-safe). */
+    req: Request;
+    /** The Hono context — `c.env` (bindings/secrets), `c.get('user')` from an upstream guard. */
+    ctx: Context;
+    /** The bucket name this controller is bound to. */
+    driver: string;
+}
+/** Return this to ALLOW with server-side modifications. */
+export interface StorageAuthResult {
+    key?: string;
+    keys?: string[];
+    prefix?: string;
+    maxSize?: number;
+    expiresIn?: number;
+    metadata?: Record<string, string>;
+}
+export type StorageAuthorizer = (action: StorageAction, context: StorageAuthContext) => boolean | StorageAuthResult | Promise<boolean | StorageAuthResult>;

package/dist/http/authorizer.types.js

@@ -0,0 +1 @@
+export { };

package/dist/http/http-helpers.d.ts

@@ -0,0 +1,22 @@
+import type { StorageErrorCode } from '../storage.error';
+import type { ByteRange, StoredFile } from '../storage.types';
+import type { StorageWireErrorCode } from './protocol.types';
+/** Map a core error code to (wire code, HTTP status). */
+export declare function mapError(code: StorageErrorCode): {
+    wire: StorageWireErrorCode;
+    status: number;
+};
+export declare function serializeStored(file: StoredFile): {
+    key: string;
+    name: string;
+    size: number;
+    type: string;
+    lastModified: number | undefined;
+    etag: string | undefined;
+    metadata: Record<string, string> | undefined;
+};
+export declare function clampExpiry(requested: number | undefined, def: number, max: number): number;
+/** Parse an HTTP `Range` header (single range) into a {@link ByteRange}. */
+export declare function parseRange(header: string | undefined | null): ByteRange | undefined;
+/** Content-Disposition header — defaults to `attachment` (anti stored-XSS). */
+export declare function dispositionHeader(disposition: string | undefined, name: string): string;

package/dist/http/http-helpers.js

@@ -0,0 +1,80 @@
+/** Map a core error code to (wire code, HTTP status). */ export function mapError(code) {
+    switch(code){
+        case 'NotFound':
+            return {
+                wire: 'not_found',
+                status: 404
+            };
+        case 'AccessDenied':
+        case 'ReadOnly':
+            return {
+                wire: 'forbidden',
+                status: 403
+            };
+        case 'Unsupported':
+            return {
+                wire: 'capability_unsupported',
+                status: 400
+            };
+        case 'InvalidKey':
+            return {
+                wire: 'invalid_key',
+                status: 400
+            };
+        case 'InvalidRequest':
+        case 'Aborted':
+            return {
+                wire: 'invalid_request',
+                status: 400
+            };
+        case 'Conflict':
+            return {
+                wire: 'conflict',
+                status: 409
+            };
+        case 'RateLimited':
+            return {
+                wire: 'rate_limited',
+                status: 429
+            };
+        case 'Timeout':
+            return {
+                wire: 'upstream_error',
+                status: 504
+            };
+        default:
+            return {
+                wire: 'upstream_error',
+                status: 502
+            };
+    }
+}
+export function serializeStored(file) {
+    return {
+        key: file.key,
+        name: file.name,
+        size: file.size,
+        type: file.type,
+        lastModified: file.lastModified,
+        etag: file.etag,
+        metadata: file.metadata
+    };
+}
+export function clampExpiry(requested, def, max) {
+    return Math.min(requested ?? def, max);
+}
+/** Parse an HTTP `Range` header (single range) into a {@link ByteRange}. */ export function parseRange(header) {
+    if (!header) return undefined;
+    const m = /^bytes=(\d+)-(\d*)$/.exec(header.trim());
+    if (!m) return undefined;
+    const start = Number(m[1]);
+    const end = m[2] === '' ? undefined : Number(m[2]);
+    return {
+        start,
+        end
+    };
+}
+/** Content-Disposition header — defaults to `attachment` (anti stored-XSS). */ export function dispositionHeader(disposition, name) {
+    const filename = `filename*=UTF-8''${encodeURIComponent(name)}`;
+    return disposition === 'inline' ? `inline; ${filename}` : `attachment; ${filename}`;
+}