@velajs/storage 0.2.0

package/dist/drivers/r2/index.d.ts

@@ -0,0 +1,11 @@
+import type { StorageDriver } from '../../storage.types';
+import type { R2BucketLike, R2DriverOptions } from './r2.types';
+export type { R2BucketLike, R2DriverOptions, R2ObjectLike, R2ObjectBodyLike, R2MultipartUploadLike, } from './r2.types';
+/**
+ * Cloudflare R2 driver — native binding mode only. Zero third-party deps
+ * (no aws4fetch), fully edge-native I/O with no egress fees.
+ *
+ * It cannot presign (`signedUploadUrl` throws; `url()` needs `publicBaseUrl`).
+ * For presigned URLs use `@velajs/storage/drivers/r2-http` (HTTP or hybrid mode).
+ */
+export declare function r2Driver(options: R2DriverOptions): StorageDriver<R2BucketLike>;

package/dist/drivers/r2/index.js

@@ -0,0 +1,166 @@
+import { createStoredFile } from "../../internal/stored-file.js";
+import { StorageError } from "../../storage.error.js";
+function joinPublic(base, key) {
+    const enc = key.split('/').map(encodeURIComponent).join('/');
+    return `${base.replace(/\/$/, '')}/${enc}`;
+}
+function metaOf(obj) {
+    return {
+        key: obj.key,
+        size: obj.size,
+        type: obj.httpMetadata?.contentType ?? 'application/octet-stream',
+        etag: obj.etag,
+        lastModified: obj.uploaded instanceof Date ? obj.uploaded.getTime() : undefined,
+        metadata: obj.customMetadata
+    };
+}
+/**
+ * Cloudflare R2 driver — native binding mode only. Zero third-party deps
+ * (no aws4fetch), fully edge-native I/O with no egress fees.
+ *
+ * It cannot presign (`signedUploadUrl` throws; `url()` needs `publicBaseUrl`).
+ * For presigned URLs use `@velajs/storage/drivers/r2-http` (HTTP or hybrid mode).
+ */ export function r2Driver(options) {
+    const bucket = options.bucket;
+    const mustGet = async (key)=>{
+        const obj = await bucket.get(key);
+        if (!obj) throw new StorageError('NotFound', `not found: ${key}`);
+        return obj;
+    };
+    return {
+        name: options.name ?? 'r2',
+        raw: bucket,
+        supportsRange: true,
+        supportsDelimiter: true,
+        supportsMetadata: true,
+        supportsCacheControl: true,
+        supportsServerSideCopy: false,
+        reportsUploadProgress: false,
+        signedUrl: {
+            supported: !!options.publicBaseUrl,
+            upload: false
+        },
+        async upload (key, body, opts) {
+            const obj = await bucket.put(key, body, {
+                httpMetadata: {
+                    contentType: opts?.contentType,
+                    cacheControl: opts?.cacheControl
+                },
+                customMetadata: opts?.metadata
+            });
+            if (!obj) throw new StorageError('Provider', `put failed: ${key}`);
+            return {
+                key,
+                size: obj.size,
+                contentType: opts?.contentType ?? 'application/octet-stream',
+                etag: obj.etag,
+                lastModified: obj.uploaded instanceof Date ? obj.uploaded.getTime() : undefined
+            };
+        },
+        async download (key, opts) {
+            const range = opts?.range ? {
+                offset: opts.range.start,
+                length: opts.range.end != null ? opts.range.end - opts.range.start + 1 : undefined
+            } : undefined;
+            const obj = await bucket.get(key, range ? {
+                range
+            } : undefined);
+            if (!obj) throw new StorageError('NotFound', `not found: ${key}`);
+            const meta = metaOf(obj);
+            const size = range ? range.length ?? obj.size - range.offset : obj.size;
+            return createStoredFile({
+                ...meta,
+                size
+            }, {
+                kind: 'stream',
+                stream: obj.body
+            });
+        },
+        async head (key) {
+            const obj = await bucket.head(key);
+            if (!obj) throw new StorageError('NotFound', `not found: ${key}`);
+            return createStoredFile(metaOf(obj), {
+                kind: 'lazy',
+                fetch: async ()=>new Response((await mustGet(key)).body)
+            });
+        },
+        async exists (key) {
+            return await bucket.head(key) != null;
+        },
+        async delete (key) {
+            await bucket.delete(key);
+        },
+        async deleteMany (keys) {
+            await bucket.delete(keys);
+            return {
+                deleted: keys
+            };
+        },
+        async copy (from, to) {
+            const src = await bucket.get(from);
+            if (!src) throw new StorageError('NotFound', `not found: ${from}`);
+            await bucket.put(to, src.body, {
+                httpMetadata: src.httpMetadata,
+                customMetadata: src.customMetadata
+            });
+        },
+        async list (opts) {
+            const res = await bucket.list({
+                prefix: opts?.prefix,
+                cursor: opts?.cursor,
+                limit: opts?.limit,
+                delimiter: opts?.delimiter
+            });
+            return {
+                items: res.objects.map((obj)=>createStoredFile(metaOf(obj), {
+                        kind: 'lazy',
+                        fetch: async ()=>new Response((await mustGet(obj.key)).body)
+                    })),
+                prefixes: res.delimitedPrefixes.length ? res.delimitedPrefixes : undefined,
+                cursor: res.truncated ? res.cursor : undefined
+            };
+        },
+        async url (key, _opts) {
+            if (options.publicBaseUrl) return joinPublic(options.publicBaseUrl, key);
+            throw new StorageError('Unsupported', 'r2 binding: url() needs publicBaseUrl (or use the r2-http/hybrid driver to presign)');
+        },
+        async signedUploadUrl () {
+            throw new StorageError('Unsupported', 'r2 binding cannot presign uploads; use the r2-http or r2-hybrid driver');
+        },
+        async createMultipartUpload (key, opts) {
+            const mpu = await bucket.createMultipartUpload(key, {
+                httpMetadata: {
+                    contentType: opts?.contentType,
+                    cacheControl: opts?.cacheControl
+                },
+                customMetadata: opts?.metadata
+            });
+            return {
+                key,
+                uploadId: mpu.uploadId,
+                async uploadPart (partNumber, part, _o) {
+                    const up = await mpu.uploadPart(partNumber, part);
+                    return {
+                        partNumber: up.partNumber,
+                        etag: up.etag
+                    };
+                },
+                async complete (parts) {
+                    const obj = await mpu.complete(parts.map((p)=>({
+                            partNumber: p.partNumber,
+                            etag: p.etag
+                        })));
+                    return {
+                        key,
+                        size: obj.size,
+                        contentType: opts?.contentType ?? 'application/octet-stream',
+                        etag: obj.etag
+                    };
+                },
+                async abort () {
+                    await mpu.abort();
+                }
+            };
+        }
+    };
+}

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

@@ -0,0 +1,67 @@
+export type R2PutValue = ReadableStream | ArrayBuffer | ArrayBufferView | string | Blob | null;
+export interface R2HttpMetadataLike {
+    contentType?: string;
+    cacheControl?: string;
+}
+export interface R2PutOptionsLike {
+    httpMetadata?: R2HttpMetadataLike;
+    customMetadata?: Record<string, string>;
+}
+export interface R2GetOptionsLike {
+    range?: {
+        offset?: number;
+        length?: number;
+        suffix?: number;
+    };
+}
+export interface R2ListOptionsLike {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+    delimiter?: string;
+}
+export interface R2ObjectLike {
+    key: string;
+    size: number;
+    etag: string;
+    uploaded: Date;
+    httpMetadata?: R2HttpMetadataLike;
+    customMetadata?: Record<string, string>;
+}
+export interface R2ObjectBodyLike extends R2ObjectLike {
+    body: ReadableStream;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+export interface R2ListResultLike {
+    objects: R2ObjectLike[];
+    truncated: boolean;
+    cursor?: string;
+    delimitedPrefixes: string[];
+}
+export interface R2UploadedPartLike {
+    partNumber: number;
+    etag: string;
+}
+export interface R2MultipartUploadLike {
+    readonly uploadId: string;
+    uploadPart(partNumber: number, value: R2PutValue): Promise<R2UploadedPartLike>;
+    complete(parts: R2UploadedPartLike[]): Promise<R2ObjectLike>;
+    abort(): Promise<void>;
+}
+export interface R2BucketLike {
+    put(key: string, value: R2PutValue, options?: R2PutOptionsLike): Promise<R2ObjectLike | null>;
+    get(key: string, options?: R2GetOptionsLike): Promise<R2ObjectBodyLike | null>;
+    head(key: string): Promise<R2ObjectLike | null>;
+    delete(keys: string | string[]): Promise<void>;
+    list(options?: R2ListOptionsLike): Promise<R2ListResultLike>;
+    createMultipartUpload(key: string, options?: R2PutOptionsLike): Promise<R2MultipartUploadLike>;
+    resumeMultipartUpload?(key: string, uploadId: string): R2MultipartUploadLike;
+}
+export interface R2DriverOptions {
+    /** The Workers `R2Bucket` binding (e.g. `env.MY_BUCKET` or `R2Service.bucket`). */
+    bucket: R2BucketLike;
+    /** Public origin (r2.dev subdomain / custom domain) so `url()` can return a link. */
+    publicBaseUrl?: string;
+    /** Friendly driver name (defaults to `r2`). */
+    name?: string;
+}

package/dist/drivers/r2/r2.types.js

@@ -0,0 +1,5 @@
+// Structural subset of the Cloudflare `R2Bucket` binding — only the members we
+// call. Declaring it structurally (instead of importing @cloudflare/workers-types)
+// keeps workers-types an optional peer; a real `R2Bucket` (and
+// `@velajs/cloudflare`'s `R2Service.bucket`) is structurally assignable.
+export { };

package/dist/drivers/r2-http/index.d.ts

@@ -0,0 +1,33 @@
+import type { StorageDriver } from '../../storage.types';
+import type { R2BucketLike } from '../r2/r2.types';
+export interface R2HttpOptions {
+    /** Cloudflare account ID — the default endpoint is derived from it. */
+    accountId: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    bucket: string;
+    /** Override the endpoint (jurisdiction-specific R2 URLs). */
+    endpoint?: string;
+    region?: string;
+    publicBaseUrl?: string;
+    defaultUrlExpiresIn?: number;
+    fetch?: typeof fetch;
+}
+/**
+ * R2 over the S3-compatible HTTP API (aws4fetch). All I/O goes over HTTP and
+ * presigning works. Prefer the native binding driver (`../r2`) for I/O when
+ * running inside a Worker; use this from Node/other runtimes, or use
+ * {@link r2HybridDriver} to combine binding I/O with HTTP presigning.
+ */
+export declare function r2HttpDriver(o: R2HttpOptions): StorageDriver;
+export interface R2HybridOptions extends R2HttpOptions {
+    /** The Workers `R2Bucket` binding used for reads/writes (no egress). */
+    binding: R2BucketLike;
+}
+/**
+ * Hybrid R2 driver: reads/writes go through the native binding (intra-Worker,
+ * no egress), while `url()` / `signedUploadUrl()` / `signedMultipart` /
+ * server-side `copy()` use the S3 HTTP signer. The best of both for Workers
+ * that need browser-facing presigned URLs.
+ */
+export declare function r2HybridDriver(o: R2HybridOptions): StorageDriver;

package/dist/drivers/r2-http/index.js

@@ -0,0 +1,52 @@
+import { r2Driver } from "../r2/index.js";
+import { s3Driver } from "../s3/index.js";
+function endpointFor(o) {
+    return o.endpoint ?? `https://${o.accountId}.r2.cloudflarestorage.com`;
+}
+/**
+ * R2 over the S3-compatible HTTP API (aws4fetch). All I/O goes over HTTP and
+ * presigning works. Prefer the native binding driver (`../r2`) for I/O when
+ * running inside a Worker; use this from Node/other runtimes, or use
+ * {@link r2HybridDriver} to combine binding I/O with HTTP presigning.
+ */ export function r2HttpDriver(o) {
+    return s3Driver({
+        endpoint: endpointFor(o),
+        region: o.region ?? 'auto',
+        bucket: o.bucket,
+        forcePathStyle: true,
+        credentials: {
+            accessKeyId: o.accessKeyId,
+            secretAccessKey: o.secretAccessKey
+        },
+        publicBaseUrl: o.publicBaseUrl,
+        defaultUrlExpiresIn: o.defaultUrlExpiresIn,
+        fetch: o.fetch,
+        name: 'r2-http'
+    });
+}
+/**
+ * Hybrid R2 driver: reads/writes go through the native binding (intra-Worker,
+ * no egress), while `url()` / `signedUploadUrl()` / `signedMultipart` /
+ * server-side `copy()` use the S3 HTTP signer. The best of both for Workers
+ * that need browser-facing presigned URLs.
+ */ export function r2HybridDriver(o) {
+    const binding = r2Driver({
+        bucket: o.binding,
+        publicBaseUrl: o.publicBaseUrl,
+        name: 'r2-hybrid'
+    });
+    const http = r2HttpDriver(o);
+    return {
+        ...binding,
+        name: 'r2-hybrid',
+        supportsServerSideCopy: true,
+        signedUrl: {
+            supported: true,
+            upload: true
+        },
+        url: (key, opts)=>http.url(key, opts),
+        signedUploadUrl: (key, opts)=>http.signedUploadUrl(key, opts),
+        signedMultipart: http.signedMultipart,
+        copy: (from, to, opts)=>http.copy(from, to, opts)
+    };
+}

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

@@ -0,0 +1,5 @@
+export { s3Driver } from './s3.driver';
+export { S3Client } from './s3-client';
+export type { PostPolicyOptions } from './s3-client';
+export type { S3DriverOptions, S3Credentials } from './s3.types';
+export { escapeXml, unescapeXml, tagText, tagBlocks } from './xml';

package/dist/drivers/s3/index.js

@@ -0,0 +1,3 @@
+export { s3Driver } from "./s3.driver.js";
+export { S3Client } from "./s3-client.js";
+export { escapeXml, unescapeXml, tagText, tagBlocks } from "./xml.js";

package/dist/drivers/s3/s3-client.d.ts

@@ -0,0 +1,33 @@
+import type { S3DriverOptions } from './s3.types';
+export interface PostPolicyOptions {
+    expiresIn: number;
+    contentType?: string;
+    maxSize?: number;
+    minSize?: number;
+}
+/**
+ * Thin wrapper over aws4fetch: builds addressed URLs, sends SigV4-signed
+ * requests, and mints presigned GET/PUT URLs + presigned-POST policies.
+ * The single place S3 signing happens.
+ */
+export declare class S3Client {
+    #private;
+    constructor(cfg: S3DriverOptions);
+    get bucket(): string;
+    objectUrl(key: string, query?: Record<string, string>): URL;
+    /** The bucket-root URL used as the presigned-POST target. */
+    postUrl(): string;
+    /** Send a SigV4-signed request. */
+    send(url: URL, init: RequestInit): Promise<Response>;
+    /** Presign a GET or PUT URL via query signing (unsigned payload). */
+    presign(key: string, method: 'GET' | 'PUT', expiresIn: number, query?: Record<string, string>): Promise<string>;
+    /**
+     * Presigned POST policy — enforces `content-length-range` server-side.
+     * aws4fetch only signs requests, so the policy HMAC chain is hand-rolled
+     * on Web Crypto (edge-safe).
+     */
+    signPostPolicy(key: string, opts: PostPolicyOptions): Promise<{
+        url: string;
+        fields: Record<string, string>;
+    }>;
+}

package/dist/drivers/s3/s3-client.js

@@ -0,0 +1,154 @@
+import { AwsClient } from "aws4fetch";
+import { utf8ToBase64 } from "../../base64.js";
+// --- Web-Crypto SigV4 helpers (used only for the POST-policy path; the
+// request-signing path is aws4fetch). No node:crypto, no Buffer. ---
+const encoder = new TextEncoder();
+async function hmac(key, data) {
+    const cryptoKey = await crypto.subtle.importKey('raw', key, {
+        name: 'HMAC',
+        hash: 'SHA-256'
+    }, false, [
+        'sign'
+    ]);
+    const sig = await crypto.subtle.sign('HMAC', cryptoKey, encoder.encode(data));
+    return new Uint8Array(sig);
+}
+function hex(bytes) {
+    let out = '';
+    for (const b of bytes)out += b.toString(16).padStart(2, '0');
+    return out;
+}
+async function sigV4SigningKey(secret, dateStamp, region, service = 's3') {
+    const kDate = await hmac(encoder.encode(`AWS4${secret}`), dateStamp);
+    const kRegion = await hmac(kDate, region);
+    const kService = await hmac(kRegion, service);
+    return hmac(kService, 'aws4_request');
+}
+function amzDates() {
+    const amzDate = new Date().toISOString().replace(/[:-]|\.\d{3}/g, '');
+    return {
+        amzDate,
+        dateStamp: amzDate.slice(0, 8)
+    };
+}
+/**
+ * Thin wrapper over aws4fetch: builds addressed URLs, sends SigV4-signed
+ * requests, and mints presigned GET/PUT URLs + presigned-POST policies.
+ * The single place S3 signing happens.
+ */ export class S3Client {
+    #aws;
+    #cfg;
+    #fetch;
+    constructor(cfg){
+        this.#cfg = cfg;
+        this.#fetch = cfg.fetch ?? fetch;
+        this.#aws = new AwsClient({
+            accessKeyId: cfg.credentials.accessKeyId,
+            secretAccessKey: cfg.credentials.secretAccessKey,
+            sessionToken: cfg.credentials.sessionToken,
+            region: cfg.region,
+            service: 's3'
+        });
+    }
+    get bucket() {
+        return this.#cfg.bucket;
+    }
+    /** Encode each key segment but keep `/` separators. */ #encodeKey(key) {
+        return key.split('/').map(encodeURIComponent).join('/');
+    }
+    objectUrl(key, query) {
+        const enc = this.#encodeKey(key);
+        const u = new URL(this.#cfg.endpoint);
+        if (this.#cfg.forcePathStyle) {
+            u.pathname = `/${this.#cfg.bucket}${enc ? `/${enc}` : ''}`;
+        } else {
+            u.hostname = `${this.#cfg.bucket}.${u.hostname}`;
+            u.pathname = `/${enc}`;
+        }
+        if (query) for (const [k, v] of Object.entries(query))u.searchParams.set(k, v);
+        return u;
+    }
+    /** The bucket-root URL used as the presigned-POST target. */ postUrl() {
+        const u = new URL(this.#cfg.endpoint);
+        if (this.#cfg.forcePathStyle) u.pathname = `/${this.#cfg.bucket}`;
+        else u.hostname = `${this.#cfg.bucket}.${u.hostname}`;
+        return u.toString();
+    }
+    /** Send a SigV4-signed request. */ async send(url, init) {
+        const signed = await this.#aws.sign(url.toString(), init);
+        return this.#fetch(signed);
+    }
+    /** Presign a GET or PUT URL via query signing (unsigned payload). */ async presign(key, method, expiresIn, query) {
+        const url = this.objectUrl(key, {
+            ...query,
+            'X-Amz-Expires': String(expiresIn)
+        });
+        const signed = await this.#aws.sign(url.toString(), {
+            method,
+            aws: {
+                signQuery: true
+            }
+        });
+        return signed.url;
+    }
+    /**
+   * Presigned POST policy — enforces `content-length-range` server-side.
+   * aws4fetch only signs requests, so the policy HMAC chain is hand-rolled
+   * on Web Crypto (edge-safe).
+   */ async signPostPolicy(key, opts) {
+        const { amzDate, dateStamp } = amzDates();
+        const { accessKeyId, secretAccessKey, sessionToken } = this.#cfg.credentials;
+        const credential = `${accessKeyId}/${dateStamp}/${this.#cfg.region}/s3/aws4_request`;
+        const expiration = new Date(Date.now() + opts.expiresIn * 1000).toISOString();
+        const conditions = [
+            {
+                bucket: this.#cfg.bucket
+            },
+            {
+                key
+            },
+            {
+                'x-amz-algorithm': 'AWS4-HMAC-SHA256'
+            },
+            {
+                'x-amz-credential': credential
+            },
+            {
+                'x-amz-date': amzDate
+            }
+        ];
+        if (sessionToken) conditions.push({
+            'x-amz-security-token': sessionToken
+        });
+        if (opts.contentType) conditions.push({
+            'content-type': opts.contentType
+        });
+        if (opts.maxSize != null || opts.minSize != null) {
+            conditions.push([
+                'content-length-range',
+                opts.minSize ?? 0,
+                opts.maxSize ?? opts.minSize ?? 0
+            ]);
+        }
+        const policyB64 = utf8ToBase64(JSON.stringify({
+            expiration,
+            conditions
+        }));
+        const signingKey = await sigV4SigningKey(secretAccessKey, dateStamp, this.#cfg.region);
+        const signature = hex(await hmac(signingKey, policyB64));
+        const fields = {
+            key,
+            'x-amz-algorithm': 'AWS4-HMAC-SHA256',
+            'x-amz-credential': credential,
+            'x-amz-date': amzDate,
+            policy: policyB64,
+            'x-amz-signature': signature
+        };
+        if (sessionToken) fields['x-amz-security-token'] = sessionToken;
+        if (opts.contentType) fields['content-type'] = opts.contentType;
+        return {
+            url: this.postUrl(),
+            fields
+        };
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { StorageDriver } from '../../storage.types';
+import type { S3DriverOptions } from './s3.types';
+/** S3 / S3-compatible driver signed with aws4fetch (edge-safe). */
+export declare function s3Driver(options: S3DriverOptions): StorageDriver;