@voyantjs/storage 0.19.0

package/README.md

@@ -0,0 +1,46 @@
+# @voyantjs/storage
+
+Storage provider abstraction for Voyant. `StorageProvider` interface plus providers for local (in-memory), Cloudflare R2, and S3-compatible (AWS SigV4 via Web Crypto — works in Cloudflare Workers).
+
+## Install
+
+```bash
+pnpm add @voyantjs/storage
+```
+
+## Usage
+
+```typescript
+import { createStorageService } from "@voyantjs/storage"
+import { s3Provider } from "@voyantjs/storage/providers/s3"
+
+const storage = createStorageService(
+  s3Provider({
+    region: "us-east-1",
+    bucket: "my-bucket",
+    accessKeyId: env.AWS_ACCESS_KEY_ID,
+    secretAccessKey: env.AWS_SECRET_ACCESS_KEY,
+  }),
+)
+
+await storage.upload({ key: "files/x.pdf", body: buffer })
+const url = await storage.signedUrl({ key: "files/x.pdf", expiresIn: 300 })
+```
+
+The S3 provider supports `forcePathStyle` and a custom `endpoint` for S3-compatible services (Wasabi, MinIO, etc.). SigV4 signing is verified against AWS canonical test vectors.
+
+## Exports
+
+| Entry | Description |
+| --- | --- |
+| `.` | Barrel re-exports |
+| `./types` | `StorageProvider` interface |
+| `./service` | `createStorageService` |
+| `./providers/local` | In-memory provider |
+| `./providers/r2` | Cloudflare R2 binding provider |
+| `./providers/s3` | S3 provider with SigV4 |
+| `./lib/sigv4` | `signRequest`, `presignUrl` primitives |
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export type { PresignUrlInput, SignedRequestHeaders, SignRequestInput, SigV4Context, SigV4Credentials, } from "./lib/sigv4.js";
+export { presignUrl, signRequest } from "./lib/sigv4.js";
+export type { LocalStorageOptions } from "./providers/local.js";
+export { createLocalStorageProvider } from "./providers/local.js";
+export type { R2BucketLike, R2ObjectLike, R2ProviderOptions, R2PutOptionsLike, } from "./providers/r2.js";
+export { createR2Provider } from "./providers/r2.js";
+export type { S3Fetch, S3ProviderOptions } from "./providers/s3.js";
+export { createS3Provider } from "./providers/s3.js";
+export type { StorageService } from "./service.js";
+export { createStorageService, StorageError } from "./service.js";
+export type { StorageObject, StorageProvider, StorageUploadBody, UploadOptions, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,eAAe,EACf,oBAAoB,EACpB,gBAAgB,EAChB,YAAY,EACZ,gBAAgB,GACjB,MAAM,gBAAgB,CAAA;AACvB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAA;AACxD,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAA;AAC/D,OAAO,EAAE,0BAA0B,EAAE,MAAM,sBAAsB,CAAA;AACjE,YAAY,EACV,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,GACjB,MAAM,mBAAmB,CAAA;AAC1B,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,YAAY,EAAE,OAAO,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAA;AACnE,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAA;AACpD,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAClD,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAA;AACjE,YAAY,EACV,aAAa,EACb,eAAe,EACf,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAA"}

package/dist/index.js

@@ -0,0 +1,5 @@
+export { presignUrl, signRequest } from "./lib/sigv4.js";
+export { createLocalStorageProvider } from "./providers/local.js";
+export { createR2Provider } from "./providers/r2.js";
+export { createS3Provider } from "./providers/s3.js";
+export { createStorageService, StorageError } from "./service.js";

package/dist/lib/sigv4.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Minimal AWS SigV4 signing implementation using Web Crypto. Works in
+ * Cloudflare Workers, modern Node, Deno, and browsers.
+ *
+ * Supports two use cases needed by the S3 storage provider:
+ * - `signRequest`: attach an `Authorization` header for a direct request
+ * - `presignUrl`: produce a time-limited URL via query-string signing
+ *
+ * Reference:
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv_create-signed-request.html
+ */
+export interface SigV4Credentials {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+}
+export interface SigV4Context {
+    credentials: SigV4Credentials;
+    region: string;
+    service: string;
+}
+export interface SignRequestInput extends SigV4Context {
+    method: string;
+    url: string;
+    headers?: Record<string, string>;
+    body?: Uint8Array;
+    /** Override "now" (milliseconds since epoch). Useful for tests. */
+    now?: number;
+}
+export interface SignedRequestHeaders {
+    headers: Record<string, string>;
+}
+export interface PresignUrlInput extends SigV4Context {
+    method: string;
+    url: string;
+    expiresIn: number;
+    /** Extra signed headers beyond the default `host`. */
+    headers?: Record<string, string>;
+    /** Override "now" (milliseconds since epoch). Useful for tests. */
+    now?: number;
+}
+/**
+ * Sign a request and return the `Authorization` (and related) headers.
+ */
+export declare function signRequest(input: SignRequestInput): Promise<SignedRequestHeaders>;
+/**
+ * Produce a presigned URL (query-string signing) for the given method.
+ */
+export declare function presignUrl(input: PresignUrlInput): Promise<string>;
+//# sourceMappingURL=sigv4.d.ts.map

package/dist/lib/sigv4.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sigv4.d.ts","sourceRoot":"","sources":["../../src/lib/sigv4.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,eAAe,EAAE,MAAM,CAAA;IACvB,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,EAAE,gBAAgB,CAAA;IAC7B,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,gBAAiB,SAAQ,YAAY;IACpD,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,IAAI,CAAC,EAAE,UAAU,CAAA;IACjB,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,eAAgB,SAAQ,YAAY;IACnD,MAAM,EAAE,MAAM,CAAA;IACd,GAAG,EAAE,MAAM,CAAA;IACX,SAAS,EAAE,MAAM,CAAA;IACjB,sDAAsD;IACtD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;GAEG;AACH,wBAAsB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAqDxF;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,KAAK,EAAE,eAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAgDxE"}

package/dist/lib/sigv4.js

@@ -0,0 +1,165 @@
+/**
+ * Minimal AWS SigV4 signing implementation using Web Crypto. Works in
+ * Cloudflare Workers, modern Node, Deno, and browsers.
+ *
+ * Supports two use cases needed by the S3 storage provider:
+ * - `signRequest`: attach an `Authorization` header for a direct request
+ * - `presignUrl`: produce a time-limited URL via query-string signing
+ *
+ * Reference:
+ * https://docs.aws.amazon.com/IAM/latest/UserGuide/reference_sigv_create-signed-request.html
+ */
+const encoder = new TextEncoder();
+/**
+ * Sign a request and return the `Authorization` (and related) headers.
+ */
+export async function signRequest(input) {
+    const { amzDate, dateStamp } = datesFromNow(input.now);
+    const url = new URL(input.url);
+    const bodyBytes = input.body ?? new Uint8Array();
+    const payloadHash = await hexHash(bodyBytes);
+    const baseHeaders = {
+        ...(input.headers ?? {}),
+        host: url.host,
+        "x-amz-date": amzDate,
+        "x-amz-content-sha256": payloadHash,
+    };
+    if (input.credentials.sessionToken) {
+        baseHeaders["x-amz-security-token"] = input.credentials.sessionToken;
+    }
+    const canonicalQuery = canonicalQueryString(url);
+    const { canonicalHeaders, signedHeaders } = canonicalizeHeaders(baseHeaders);
+    const canonicalRequest = [
+        input.method.toUpperCase(),
+        canonicalUri(url.pathname),
+        canonicalQuery,
+        canonicalHeaders,
+        signedHeaders,
+        payloadHash,
+    ].join("\n");
+    const scope = `${dateStamp}/${input.region}/${input.service}/aws4_request`;
+    const stringToSign = [
+        "AWS4-HMAC-SHA256",
+        amzDate,
+        scope,
+        await hexHash(encoder.encode(canonicalRequest)),
+    ].join("\n");
+    const signingKey = await deriveSigningKey(input.credentials.secretAccessKey, dateStamp, input.region, input.service);
+    const signature = hex(await hmac(signingKey, stringToSign));
+    const authHeader = `AWS4-HMAC-SHA256 Credential=${input.credentials.accessKeyId}/${scope}` +
+        `, SignedHeaders=${signedHeaders}, Signature=${signature}`;
+    return {
+        headers: {
+            ...baseHeaders,
+            Authorization: authHeader,
+        },
+    };
+}
+/**
+ * Produce a presigned URL (query-string signing) for the given method.
+ */
+export async function presignUrl(input) {
+    const { amzDate, dateStamp } = datesFromNow(input.now);
+    const url = new URL(input.url);
+    const scope = `${dateStamp}/${input.region}/${input.service}/aws4_request`;
+    const headers = {
+        ...(input.headers ?? {}),
+        host: url.host,
+    };
+    const { canonicalHeaders, signedHeaders } = canonicalizeHeaders(headers);
+    const params = new URLSearchParams(url.searchParams);
+    params.set("X-Amz-Algorithm", "AWS4-HMAC-SHA256");
+    params.set("X-Amz-Credential", `${input.credentials.accessKeyId}/${scope}`);
+    params.set("X-Amz-Date", amzDate);
+    params.set("X-Amz-Expires", String(input.expiresIn));
+    params.set("X-Amz-SignedHeaders", signedHeaders);
+    if (input.credentials.sessionToken) {
+        params.set("X-Amz-Security-Token", input.credentials.sessionToken);
+    }
+    url.search = params.toString();
+    const canonicalRequest = [
+        input.method.toUpperCase(),
+        canonicalUri(url.pathname),
+        canonicalQueryString(url),
+        canonicalHeaders,
+        signedHeaders,
+        "UNSIGNED-PAYLOAD",
+    ].join("\n");
+    const stringToSign = [
+        "AWS4-HMAC-SHA256",
+        amzDate,
+        scope,
+        await hexHash(encoder.encode(canonicalRequest)),
+    ].join("\n");
+    const signingKey = await deriveSigningKey(input.credentials.secretAccessKey, dateStamp, input.region, input.service);
+    const signature = hex(await hmac(signingKey, stringToSign));
+    params.set("X-Amz-Signature", signature);
+    url.search = params.toString();
+    return url.toString();
+}
+// --- helpers --- //
+function datesFromNow(nowMs) {
+    const d = new Date(nowMs ?? Date.now());
+    const iso = d.toISOString().replace(/[:-]|\.\d{3}/g, "");
+    // iso is like "20251005T223045Z"
+    return { amzDate: iso, dateStamp: iso.slice(0, 8) };
+}
+function canonicalUri(path) {
+    // S3 keys should be path-encoded but preserve "/"
+    if (!path)
+        return "/";
+    return path
+        .split("/")
+        .map((segment) => encodeRfc3986(segment))
+        .join("/");
+}
+function canonicalQueryString(url) {
+    const pairs = [];
+    for (const [key, value] of url.searchParams.entries()) {
+        pairs.push([encodeRfc3986(key), encodeRfc3986(value)]);
+    }
+    pairs.sort((a, b) => (a[0] === b[0] ? (a[1] < b[1] ? -1 : 1) : a[0] < b[0] ? -1 : 1));
+    return pairs.map(([k, v]) => `${k}=${v}`).join("&");
+}
+function canonicalizeHeaders(headers) {
+    const entries = Object.entries(headers)
+        .map(([k, v]) => [k.toLowerCase(), v.trim().replace(/\s+/g, " ")])
+        .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const canonicalHeaders = `${entries.map(([k, v]) => `${k}:${v}`).join("\n")}\n`;
+    const signedHeaders = entries.map(([k]) => k).join(";");
+    return { canonicalHeaders, signedHeaders };
+}
+function encodeRfc3986(value) {
+    return encodeURIComponent(value).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`);
+}
+async function hexHash(data) {
+    const copy = new Uint8Array(data.byteLength);
+    copy.set(data);
+    const digest = await crypto.subtle.digest("SHA-256", copy);
+    return hex(digest);
+}
+async function hmac(key, data) {
+    const source = key instanceof Uint8Array ? key : new Uint8Array(key);
+    const keyBytes = new Uint8Array(source.byteLength);
+    keyBytes.set(source);
+    const cryptoKey = await crypto.subtle.importKey("raw", keyBytes, { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+    const payloadSource = encoder.encode(data);
+    const payload = new Uint8Array(payloadSource.byteLength);
+    payload.set(payloadSource);
+    return crypto.subtle.sign("HMAC", cryptoKey, payload);
+}
+async function deriveSigningKey(secret, dateStamp, region, service) {
+    const kDate = await hmac(encoder.encode(`AWS4${secret}`), dateStamp);
+    const kRegion = await hmac(kDate, region);
+    const kService = await hmac(kRegion, service);
+    const kSigning = await hmac(kService, "aws4_request");
+    return kSigning;
+}
+function hex(buffer) {
+    const bytes = new Uint8Array(buffer);
+    let out = "";
+    for (const b of bytes) {
+        out += b.toString(16).padStart(2, "0");
+    }
+    return out;
+}

package/dist/providers/local.d.ts

@@ -0,0 +1,26 @@
+import type { StorageProvider } from "../types.js";
+/**
+ * Options for {@link createLocalStorageProvider}.
+ */
+export interface LocalStorageOptions {
+    /** Provider name (defaults to `"local"`). */
+    name?: string;
+    /**
+     * Base URL used to construct the string returned from `signedUrl` and
+     * `upload`. Defaults to `"local://"`. The final URL is `${baseUrl}${key}`.
+     */
+    baseUrl?: string;
+    /**
+     * Function used to mint random keys when `UploadOptions.key` is not
+     * provided. Defaults to `crypto.randomUUID()` via the global `crypto`.
+     */
+    generateKey?: () => string;
+}
+/**
+ * Create an in-memory storage provider. Useful for unit tests and for
+ * locally running workflows without touching remote storage. Data is
+ * kept in a `Map` held inside the closure and is lost when the process
+ * exits.
+ */
+export declare function createLocalStorageProvider(options?: LocalStorageOptions): StorageProvider;
+//# sourceMappingURL=local.d.ts.map

package/dist/providers/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/providers/local.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,eAAe,EAAoC,MAAM,aAAa,CAAA;AAEnG;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,6CAA6C;IAC7C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;CAC3B;AAQD;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,OAAO,GAAE,mBAAwB,GAAG,eAAe,CAwC7F"}

package/dist/providers/local.js

@@ -0,0 +1,54 @@
+/**
+ * Create an in-memory storage provider. Useful for unit tests and for
+ * locally running workflows without touching remote storage. Data is
+ * kept in a `Map` held inside the closure and is lost when the process
+ * exits.
+ */
+export function createLocalStorageProvider(options = {}) {
+    const name = options.name ?? "local";
+    const baseUrl = options.baseUrl ?? "local://";
+    const generateKey = options.generateKey ??
+        (() => {
+            const g = globalThis;
+            return g.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        });
+    const store = new Map();
+    async function upload(body, opts = {}) {
+        const key = opts.key ?? generateKey();
+        const bytes = await toBytes(body);
+        const record = { bytes };
+        if (opts.contentType !== undefined)
+            record.contentType = opts.contentType;
+        if (opts.metadata !== undefined)
+            record.metadata = opts.metadata;
+        store.set(key, record);
+        return { key, url: `${baseUrl}${key}` };
+    }
+    return {
+        name,
+        upload,
+        async delete(key) {
+            store.delete(key);
+        },
+        async signedUrl(key) {
+            return `${baseUrl}${key}`;
+        },
+        async get(key) {
+            const record = store.get(key);
+            if (!record)
+                return null;
+            // Copy into a fresh ArrayBuffer so downstream mutation can't corrupt the store.
+            const copy = new Uint8Array(record.bytes.byteLength);
+            copy.set(record.bytes);
+            return copy.buffer;
+        },
+    };
+}
+async function toBytes(body) {
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    const buffer = await body.arrayBuffer();
+    return new Uint8Array(buffer);
+}

package/dist/providers/r2.d.ts

@@ -0,0 +1,52 @@
+import type { StorageProvider } from "../types.js";
+/**
+ * Subset of the Cloudflare Workers `R2Bucket` binding we depend on. Kept
+ * as a minimal structural type so this package does not need a runtime
+ * dependency on `@cloudflare/workers-types`.
+ */
+export interface R2BucketLike {
+    put(key: string, value: ArrayBuffer | ArrayBufferView | Blob | string | ReadableStream | null, options?: R2PutOptionsLike): Promise<unknown>;
+    delete(key: string | string[]): Promise<void>;
+    get(key: string): Promise<R2ObjectLike | null>;
+}
+export interface R2PutOptionsLike {
+    httpMetadata?: {
+        contentType?: string;
+    };
+    customMetadata?: Record<string, string>;
+}
+export interface R2ObjectLike {
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/**
+ * Options for {@link createR2Provider}.
+ */
+export interface R2ProviderOptions {
+    /** Cloudflare R2 bucket binding (from `env.BUCKET_NAME`). */
+    bucket: R2BucketLike;
+    /**
+     * Base URL used to construct public object URLs. Typical values:
+     * - a public R2 custom domain: `https://cdn.example.com/`
+     * - a Worker route that proxies to the binding: `https://api.example.com/assets/`
+     */
+    publicBaseUrl?: string;
+    /**
+     * Signer invoked by `signedUrl`. Cloudflare R2 bindings do not produce
+     * signed URLs directly; templates pass a custom signer that either:
+     *   - returns a short-lived Worker route URL, or
+     *   - calls R2's S3-compatible API with SigV4 credentials.
+     * When omitted, `signedUrl` returns `${publicBaseUrl}${key}`.
+     */
+    signer?: (key: string, expiresIn: number) => Promise<string> | string;
+    /** Provider name (defaults to `"r2"`). */
+    name?: string;
+    /** Custom key generator; defaults to `crypto.randomUUID()`. */
+    generateKey?: () => string;
+}
+/**
+ * Create a Cloudflare R2 storage provider bound to an R2 bucket binding.
+ * The R2 binding handles authentication transparently at the Worker
+ * runtime boundary, so no credentials are required at this layer.
+ */
+export declare function createR2Provider(options: R2ProviderOptions): StorageProvider;
+//# sourceMappingURL=r2.d.ts.map

package/dist/providers/r2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"r2.d.ts","sourceRoot":"","sources":["../../src/providers/r2.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAiB,eAAe,EAAoC,MAAM,aAAa,CAAA;AAEnG;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,GAAG,CACD,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,WAAW,GAAG,eAAe,GAAG,IAAI,GAAG,MAAM,GAAG,cAAc,GAAG,IAAI,EAC5E,OAAO,CAAC,EAAE,gBAAgB,GACzB,OAAO,CAAC,OAAO,CAAC,CAAA;IACnB,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAC7C,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAA;CAC/C;AAED,MAAM,WAAW,gBAAgB;IAC/B,YAAY,CAAC,EAAE;QAAE,WAAW,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;IACvC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACxC;AAED,MAAM,WAAW,YAAY;IAC3B,WAAW,IAAI,OAAO,CAAC,WAAW,CAAC,CAAA;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,6DAA6D;IAC7D,MAAM,EAAE,YAAY,CAAA;IACpB;;;;OAIG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAA;IACrE,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,CAuC5E"}

package/dist/providers/r2.js

@@ -0,0 +1,51 @@
+/**
+ * Create a Cloudflare R2 storage provider bound to an R2 bucket binding.
+ * The R2 binding handles authentication transparently at the Worker
+ * runtime boundary, so no credentials are required at this layer.
+ */
+export function createR2Provider(options) {
+    const name = options.name ?? "r2";
+    const publicBaseUrl = options.publicBaseUrl ?? "";
+    const generateKey = options.generateKey ??
+        (() => {
+            const g = globalThis;
+            return g.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        });
+    async function upload(body, opts = {}) {
+        const key = opts.key ?? generateKey();
+        const putOptions = {};
+        if (opts.contentType !== undefined) {
+            putOptions.httpMetadata = { contentType: opts.contentType };
+        }
+        if (opts.metadata !== undefined) {
+            putOptions.customMetadata = opts.metadata;
+        }
+        await options.bucket.put(key, await toPutBody(body), putOptions);
+        return { key, url: publicBaseUrl ? `${publicBaseUrl}${key}` : "" };
+    }
+    return {
+        name,
+        upload,
+        async delete(key) {
+            await options.bucket.delete(key);
+        },
+        async signedUrl(key, expiresIn) {
+            if (options.signer)
+                return options.signer(key, expiresIn);
+            return publicBaseUrl ? `${publicBaseUrl}${key}` : key;
+        },
+        async get(key) {
+            const obj = await options.bucket.get(key);
+            if (!obj)
+                return null;
+            return obj.arrayBuffer();
+        },
+    };
+}
+async function toPutBody(body) {
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return body;
+    return body;
+}

package/dist/providers/s3.d.ts

@@ -0,0 +1,57 @@
+import type { StorageProvider } from "../types.js";
+/**
+ * Fetch shape used by the S3 provider. Matches the global `fetch` and
+ * Cloudflare Workers `fetch`. Tests can stub this.
+ */
+export type S3Fetch = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: Uint8Array;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    arrayBuffer: () => Promise<ArrayBuffer>;
+    text: () => Promise<string>;
+}>;
+/**
+ * Options for {@link createS3Provider}.
+ */
+export interface S3ProviderOptions {
+    /** AWS access key id. */
+    accessKeyId: string;
+    /** AWS secret access key. */
+    secretAccessKey: string;
+    /** Optional session token for temporary credentials. */
+    sessionToken?: string;
+    /** S3 region (e.g. `"us-east-1"`). */
+    region: string;
+    /** S3 bucket name. */
+    bucket: string;
+    /**
+     * Endpoint URL override. Defaults to the public AWS S3 endpoint for the
+     * region (`https://s3.<region>.amazonaws.com`). Set this for S3-compatible
+     * services (MinIO, Backblaze B2, DigitalOcean Spaces, Wasabi, R2 S3 API).
+     */
+    endpoint?: string;
+    /**
+     * When `true`, put the bucket in the URL path rather than the hostname
+     * subdomain. Defaults to `true` to stay compatible with the widest set
+     * of S3-compatible services. Set to `false` to use
+     * `https://<bucket>.s3.<region>.amazonaws.com` virtual-hosted style.
+     */
+    forcePathStyle?: boolean;
+    /** Base URL used for the public `url` field returned from `upload`. */
+    publicBaseUrl?: string;
+    /** Override `fetch` (e.g. in tests). Defaults to global `fetch`. */
+    fetch?: S3Fetch;
+    /** Provider name (defaults to `"s3"`). */
+    name?: string;
+    /** Custom key generator; defaults to `crypto.randomUUID()`. */
+    generateKey?: () => string;
+}
+/**
+ * Create an S3 / S3-compatible storage provider. Uses Web Crypto to sign
+ * requests with AWS SigV4, so no AWS SDK dependency is required.
+ */
+export declare function createS3Provider(options: S3ProviderOptions): StorageProvider;
+//# sourceMappingURL=s3.d.ts.map

package/dist/providers/s3.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/providers/s3.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAiB,eAAe,EAAoC,MAAM,aAAa,CAAA;AAEnG;;;GAGG;AACH,MAAM,MAAM,OAAO,GAAG,CACpB,KAAK,EAAE,MAAM,EACb,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAA;IACd,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC/B,IAAI,CAAC,EAAE,UAAU,CAAA;CAClB,KACE,OAAO,CAAC;IACX,EAAE,EAAE,OAAO,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,WAAW,EAAE,MAAM,OAAO,CAAC,WAAW,CAAC,CAAA;IACvC,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAA;CAC5B,CAAC,CAAA;AAEF;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAChC,yBAAyB;IACzB,WAAW,EAAE,MAAM,CAAA;IACnB,6BAA6B;IAC7B,eAAe,EAAE,MAAM,CAAA;IACvB,wDAAwD;IACxD,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,sCAAsC;IACtC,MAAM,EAAE,MAAM,CAAA;IACd,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB;;;;;OAKG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,uEAAuE;IACvE,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,oEAAoE;IACpE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,MAAM,CAAA;CAC3B;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,CAsH5E"}

package/dist/providers/s3.js

@@ -0,0 +1,138 @@
+import { presignUrl, signRequest } from "../lib/sigv4.js";
+/**
+ * Create an S3 / S3-compatible storage provider. Uses Web Crypto to sign
+ * requests with AWS SigV4, so no AWS SDK dependency is required.
+ */
+export function createS3Provider(options) {
+    const name = options.name ?? "s3";
+    const forcePathStyle = options.forcePathStyle ?? true;
+    const endpoint = options.endpoint ??
+        (forcePathStyle
+            ? `https://s3.${options.region}.amazonaws.com`
+            : `https://${options.bucket}.s3.${options.region}.amazonaws.com`);
+    const publicBaseUrl = options.publicBaseUrl ?? "";
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    const credentials = {
+        accessKeyId: options.accessKeyId,
+        secretAccessKey: options.secretAccessKey,
+    };
+    if (options.sessionToken !== undefined)
+        credentials.sessionToken = options.sessionToken;
+    const generateKey = options.generateKey ??
+        (() => {
+            const g = globalThis;
+            return g.crypto?.randomUUID?.() ?? `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+        });
+    function buildUrl(key) {
+        if (forcePathStyle) {
+            return `${endpoint}/${encodeURIComponent(options.bucket)}/${encodeKey(key)}`;
+        }
+        return `${endpoint}/${encodeKey(key)}`;
+    }
+    async function upload(body, opts = {}) {
+        if (!fetchImpl)
+            throw new Error("S3 provider requires a fetch implementation");
+        const key = opts.key ?? generateKey();
+        const bytes = await toBytes(body);
+        const url = buildUrl(key);
+        const headers = {};
+        if (opts.contentType)
+            headers["content-type"] = opts.contentType;
+        if (opts.metadata) {
+            for (const [k, v] of Object.entries(opts.metadata)) {
+                headers[`x-amz-meta-${k.toLowerCase()}`] = v;
+            }
+        }
+        const signed = await signRequest({
+            method: "PUT",
+            url,
+            headers,
+            body: bytes,
+            credentials,
+            region: options.region,
+            service: "s3",
+        });
+        const response = await fetchImpl(url, {
+            method: "PUT",
+            headers: signed.headers,
+            body: bytes,
+        });
+        if (!response.ok) {
+            const text = await response.text().catch(() => "");
+            throw new Error(`S3 upload failed (${response.status}): ${text}`);
+        }
+        return { key, url: publicBaseUrl ? `${publicBaseUrl}${key}` : "" };
+    }
+    return {
+        name,
+        upload,
+        async delete(key) {
+            if (!fetchImpl)
+                throw new Error("S3 provider requires a fetch implementation");
+            const url = buildUrl(key);
+            const signed = await signRequest({
+                method: "DELETE",
+                url,
+                credentials,
+                region: options.region,
+                service: "s3",
+            });
+            const response = await fetchImpl(url, {
+                method: "DELETE",
+                headers: signed.headers,
+            });
+            // S3 returns 204 on successful delete, 404 on missing — treat both as success.
+            if (!response.ok && response.status !== 404) {
+                const text = await response.text().catch(() => "");
+                throw new Error(`S3 delete failed (${response.status}): ${text}`);
+            }
+        },
+        async signedUrl(key, expiresIn) {
+            return presignUrl({
+                method: "GET",
+                url: buildUrl(key),
+                expiresIn,
+                credentials,
+                region: options.region,
+                service: "s3",
+            });
+        },
+        async get(key) {
+            if (!fetchImpl)
+                throw new Error("S3 provider requires a fetch implementation");
+            const url = buildUrl(key);
+            const signed = await signRequest({
+                method: "GET",
+                url,
+                credentials,
+                region: options.region,
+                service: "s3",
+            });
+            const response = await fetchImpl(url, {
+                method: "GET",
+                headers: signed.headers,
+            });
+            if (response.status === 404)
+                return null;
+            if (!response.ok) {
+                const text = await response.text().catch(() => "");
+                throw new Error(`S3 get failed (${response.status}): ${text}`);
+            }
+            return response.arrayBuffer();
+        },
+    };
+}
+function encodeKey(key) {
+    return key
+        .split("/")
+        .map((segment) => encodeURIComponent(segment).replace(/[!'()*]/g, (c) => `%${c.charCodeAt(0).toString(16).toUpperCase()}`))
+        .join("/");
+}
+async function toBytes(body) {
+    if (body instanceof Uint8Array)
+        return body;
+    if (body instanceof ArrayBuffer)
+        return new Uint8Array(body);
+    const buffer = await body.arrayBuffer();
+    return new Uint8Array(buffer);
+}

package/dist/service.d.ts

@@ -0,0 +1,21 @@
+import type { StorageProvider } from "./types.js";
+/**
+ * Thrown when a storage operation cannot find the requested provider.
+ */
+export declare class StorageError extends Error {
+    constructor(message: string);
+}
+/**
+ * Convenience wrapper exposing a single provider. Most deployments use
+ * exactly one storage backend at a time; for those cases the service is
+ * just a named wrapper.
+ */
+export interface StorageService extends StorageProvider {
+    /** The wrapped provider. */
+    readonly provider: StorageProvider;
+}
+/**
+ * Create a storage service that delegates all calls to the given provider.
+ */
+export declare function createStorageService(provider: StorageProvider): StorageService;
+//# sourceMappingURL=service.d.ts.map

package/dist/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../src/service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD;;GAEG;AACH,qBAAa,YAAa,SAAQ,KAAK;gBACzB,OAAO,EAAE,MAAM;CAI5B;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAe,SAAQ,eAAe;IACrD,4BAA4B;IAC5B,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;CACnC;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,eAAe,GAAG,cAAc,CAS9E"}

package/dist/service.js

@@ -0,0 +1,22 @@
+/**
+ * Thrown when a storage operation cannot find the requested provider.
+ */
+export class StorageError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "StorageError";
+    }
+}
+/**
+ * Create a storage service that delegates all calls to the given provider.
+ */
+export function createStorageService(provider) {
+    return {
+        provider,
+        name: provider.name,
+        upload: provider.upload.bind(provider),
+        delete: provider.delete.bind(provider),
+        signedUrl: provider.signedUrl.bind(provider),
+        get: provider.get.bind(provider),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Accepted body shapes for uploads. Providers normalize to `Uint8Array`
+ * or pass through to their native API.
+ */
+export type StorageUploadBody = ArrayBuffer | Uint8Array | Blob;
+/**
+ * Options controlling an upload.
+ */
+export interface UploadOptions {
+    /**
+     * Override the object key. When omitted, providers generate a random
+     * key (typically `${randomUUID()}` — UUID v4 where available).
+     */
+    key?: string;
+    /** MIME content type (e.g. `"image/png"`). */
+    contentType?: string;
+    /** Custom metadata; persisted by providers that support it (R2, S3). */
+    metadata?: Record<string, string>;
+}
+/**
+ * Result of a successful upload.
+ */
+export interface StorageObject {
+    /** Object key inside the bucket/store. */
+    key: string;
+    /**
+     * Public URL for the object when the provider exposes one. Empty string
+     * when the object is private and can only be accessed via `signedUrl`.
+     */
+    url: string;
+}
+/**
+ * Pluggable object storage provider.
+ *
+ * Built-in implementations:
+ * - `local` — in-memory, for dev and tests
+ * - `r2`    — Cloudflare R2 via the workers binding
+ * - `s3`    — Amazon S3 / S3-compatible via SigV4
+ */
+export interface StorageProvider {
+    /** Unique provider name (e.g. `"r2"`, `"s3"`, `"local"`). */
+    readonly name: string;
+    /** Upload an object. */
+    upload(body: StorageUploadBody, options?: UploadOptions): Promise<StorageObject>;
+    /** Delete an object by key. No-op if the key does not exist. */
+    delete(key: string): Promise<void>;
+    /**
+     * Produce a time-limited URL that grants GET access to the object.
+     * `expiresIn` is in seconds.
+     */
+    signedUrl(key: string, expiresIn: number): Promise<string>;
+    /**
+     * Fetch an object's bytes. Returns `null` when the object is absent.
+     */
+    get(key: string): Promise<ArrayBuffer | null>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,UAAU,GAAG,IAAI,CAAA;AAE/D;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAClC;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,0CAA0C;IAC1C,GAAG,EAAE,MAAM,CAAA;IACX;;;OAGG;IACH,GAAG,EAAE,MAAM,CAAA;CACZ;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,wBAAwB;IACxB,MAAM,CAAC,IAAI,EAAE,iBAAiB,EAAE,OAAO,CAAC,EAAE,aAAa,GAAG,OAAO,CAAC,aAAa,CAAC,CAAA;IAChF,gEAAgE;IAChE,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAClC;;;OAGG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAC1D;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAAA;CAC9C"}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@voyantjs/storage",
+  "version": "0.19.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts",
+    "./types": "./src/types.ts",
+    "./service": "./src/service.ts",
+    "./providers/local": "./src/providers/local.ts",
+    "./providers/r2": "./src/providers/r2.ts",
+    "./providers/s3": "./src/providers/s3.ts",
+    "./lib/sigv4": "./src/lib/sigv4.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "prepack": "pnpm run build"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./types": {
+        "types": "./dist/types.d.ts",
+        "import": "./dist/types.js",
+        "default": "./dist/types.js"
+      },
+      "./service": {
+        "types": "./dist/service.d.ts",
+        "import": "./dist/service.js",
+        "default": "./dist/service.js"
+      },
+      "./providers/local": {
+        "types": "./dist/providers/local.d.ts",
+        "import": "./dist/providers/local.js",
+        "default": "./dist/providers/local.js"
+      },
+      "./providers/r2": {
+        "types": "./dist/providers/r2.d.ts",
+        "import": "./dist/providers/r2.js",
+        "default": "./dist/providers/r2.js"
+      },
+      "./providers/s3": {
+        "types": "./dist/providers/s3.d.ts",
+        "import": "./dist/providers/s3.js",
+        "default": "./dist/providers/s3.js"
+      },
+      "./lib/sigv4": {
+        "types": "./dist/lib/sigv4.d.ts",
+        "import": "./dist/lib/sigv4.js",
+        "default": "./dist/lib/sigv4.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@voyantjs/voyant-typescript-config": "workspace:*",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyantjs/voyant.git",
+    "directory": "packages/storage"
+  }
+}