@digimuza/saas-core 0.0.2

package/dist/storage/index.js

@@ -0,0 +1,89 @@
+/**
+ * Public storage surface: `@digimuza/saas-core/storage`. Server-only.
+ *
+ * Object storage behind an adapter, with tenant scoping that cannot be bypassed.
+ *
+ * There is deliberately **no database table**. An object is referenced by key from
+ * whichever product table owns it, so the core does not impose a file model —
+ * a table would have to guess at metadata, ownership and lifecycle that only the
+ * product knows.
+ *
+ * ## Setup
+ *
+ * ```ts
+ * import { storage } from "@digimuza/saas-core/storage";
+ * ```
+ *
+ * Or build your own — a different store, or a fake in tests:
+ *
+ * ```ts
+ * import { createStorageService, createMemoryStorageProvider } from "@digimuza/saas-core/storage";
+ *
+ * const storage = createStorageService({ provider: createMemoryStorageProvider() });
+ * ```
+ *
+ * ## Everything goes through a workspace
+ *
+ * ```ts
+ * const files = storage.forWorkspace(context);
+ *
+ * await files.upload({ path: "avatars/me.png", body, contentType: "image/png" });
+ * const url = await files.getUrl("avatars/me.png");
+ * await files.delete("avatars/me.png");
+ * ```
+ *
+ * `forWorkspace` takes a verified `WorkspaceContext`, and the scoped API takes
+ * *paths* rather than keys — so `workspaces/<id>/` is applied in one place and a
+ * caller has no way to address another tenant's objects. Store `files.keyFor(path)`
+ * in your own tables, and pass it back through `urlForKey`, which re-checks
+ * ownership.
+ *
+ * ## Direct browser uploads
+ *
+ * ```ts
+ * const uploadUrl = await files.createUploadUrl("imports/data.csv", {
+ *   contentType: "text/csv",
+ *   expiresInSeconds: 600,
+ * });
+ * ```
+ *
+ * Hand that to the browser and let it `PUT` the bytes. Proxying uploads through
+ * the application means a request that holds a server for the whole transfer, and
+ * a body limit on every platform in the path.
+ */
+import { config } from "../config/index.js";
+import { createS3Provider } from "./s3.js";
+import { createStorageService } from "./service.js";
+export { assertKeyBelongsTo, assertObjectPath, isValidObjectPath, MAX_OBJECT_KEY_LENGTH, parseWorkspaceObjectKey, WORKSPACE_PREFIX, workspaceObjectKey, } from "./keys.js";
+export { bodyBytes, createMemoryStorageProvider, } from "./memory.js";
+export { createS3Provider, objectDigest } from "./s3.js";
+export { assertObjectExists, createStorageService, MAX_SIGNED_URL_SECONDS, } from "./service.js";
+export { encodeObjectPath, presign, signingKey, uriEncode, } from "./sigv4.js";
+/** An S3-compatible provider built from the `storage` configuration section. */
+export function createConfiguredStorageProvider() {
+    const storage = config.storage;
+    return createS3Provider({
+        bucket: storage.bucket,
+        region: storage.region,
+        credentials: {
+            accessKeyId: storage.accessKeyId,
+            secretAccessKey: storage.secretAccessKey,
+        },
+        ...(storage.endpoint !== undefined ? { endpoint: storage.endpoint } : {}),
+        ...(storage.publicUrl !== undefined ? { publicBaseUrl: storage.publicUrl } : {}),
+    });
+}
+let configuredProvider;
+/**
+ * Default service, bound to configuration.
+ *
+ * The provider is a getter, so the `storage` configuration section resolves on
+ * first use — importing this module does not require credentials.
+ */
+export const storage = createStorageService({
+    get provider() {
+        configuredProvider ??= createConfiguredStorageProvider();
+        return configuredProvider;
+    },
+});
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/storage/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAuB,MAAM,cAAc,CAAC;AAGzE,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,SAAS,EACT,2BAA2B,GAI5B,MAAM,aAAa,CAAC;AAarB,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAA0B,MAAM,SAAS,CAAC;AAEjF,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,sBAAsB,GAOvB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,gBAAgB,EAChB,OAAO,EACP,UAAU,EACV,SAAS,GAIV,MAAM,YAAY,CAAC;AAEpB,gFAAgF;AAChF,MAAM,UAAU,+BAA+B;IAC7C,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAE/B,OAAO,gBAAgB,CAAC;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,WAAW,EAAE;YACX,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,eAAe,EAAE,OAAO,CAAC,eAAe;SACzC;QACD,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACzE,GAAG,CAAC,OAAO,CAAC,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACjF,CAAC,CAAC;AACL,CAAC;AAED,IAAI,kBAA+C,CAAC;AAEpD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,OAAO,GAAmB,oBAAoB,CAAC;IAC1D,IAAI,QAAQ;QACV,kBAAkB,KAAK,+BAA+B,EAAE,CAAC;QACzD,OAAO,kBAAkB,CAAC;IAC5B,CAAC;CACF,CAAC,CAAC"}

package/dist/storage/keys.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Object key validation and tenant scoping.
+ *
+ * This is the security surface of the module. Object keys are paths, and a caller
+ * that can put `../` into one can read out of its own prefix and into another
+ * tenant's — a cross-tenant read with no database involved and nothing in an audit
+ * log. So keys are validated before they are ever concatenated with a prefix,
+ * never after.
+ */
+/** S3 caps a key at 1024 bytes; the same limit is a sane ceiling everywhere. */
+export declare const MAX_OBJECT_KEY_LENGTH = 1024;
+/** Prefix every workspace-scoped object lives under. */
+export declare const WORKSPACE_PREFIX = "workspaces";
+/**
+ * Validate a caller-supplied object path.
+ *
+ * Rejects rather than sanitises. Silently rewriting `../secret` to `secret` would
+ * store the object somewhere the caller did not ask for, and a caller who meant
+ * to traverse deserves an error rather than a surprise.
+ */
+export declare function assertObjectPath(path: string): void;
+/** True when {@link assertObjectPath} would accept the path. */
+export declare function isValidObjectPath(path: string): boolean;
+/**
+ * Build the fully-qualified key for a workspace-scoped object.
+ *
+ * The workspace id is checked as a UUID rather than trusted, because it is the
+ * only thing separating one tenant's objects from another's. A caller passing a
+ * malformed id would otherwise create a prefix that could collide.
+ */
+export declare function workspaceObjectKey(workspaceId: string, path: string): string;
+/**
+ * Recover the workspace id and path from a scoped key.
+ *
+ * Returns `undefined` for anything that is not one, so a caller can tell a scoped
+ * key from an unscoped one rather than guessing.
+ */
+export declare function parseWorkspaceObjectKey(key: string): {
+    workspaceId: string;
+    path: string;
+} | undefined;
+/**
+ * Assert a key belongs to a workspace.
+ *
+ * The check that turns a stored key back into something safe to act on: a key
+ * read from a product table might have been written before a bug was fixed, or by
+ * a different tenant entirely.
+ */
+export declare function assertKeyBelongsTo(workspaceId: string, key: string): void;
+//# sourceMappingURL=keys.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"keys.d.ts","sourceRoot":"","sources":["../../src/storage/keys.ts"],"names":[],"mappings":"AAEA;;;;;;;;GAQG;AAEH,gFAAgF;AAChF,eAAO,MAAM,qBAAqB,OAAO,CAAC;AAE1C,wDAAwD;AACxD,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAO7C;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CA6CnD;AAED,gEAAgE;AAChE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAOvD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAO5E;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,GACV;IAAE,WAAW,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAanD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAOzE"}

package/dist/storage/keys.js

@@ -0,0 +1,120 @@
+import { InvalidInputError } from "../errors.js";
+/**
+ * Object key validation and tenant scoping.
+ *
+ * This is the security surface of the module. Object keys are paths, and a caller
+ * that can put `../` into one can read out of its own prefix and into another
+ * tenant's — a cross-tenant read with no database involved and nothing in an audit
+ * log. So keys are validated before they are ever concatenated with a prefix,
+ * never after.
+ */
+/** S3 caps a key at 1024 bytes; the same limit is a sane ceiling everywhere. */
+export const MAX_OBJECT_KEY_LENGTH = 1024;
+/** Prefix every workspace-scoped object lives under. */
+export const WORKSPACE_PREFIX = "workspaces";
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+/** Control characters, including NUL. Built from escapes, never literals. */
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/;
+/**
+ * Validate a caller-supplied object path.
+ *
+ * Rejects rather than sanitises. Silently rewriting `../secret` to `secret` would
+ * store the object somewhere the caller did not ask for, and a caller who meant
+ * to traverse deserves an error rather than a surprise.
+ */
+export function assertObjectPath(path) {
+    if (typeof path !== "string" || path.length === 0) {
+        throw new InvalidInputError("An object path is required.");
+    }
+    if (Buffer.byteLength(path, "utf8") > MAX_OBJECT_KEY_LENGTH) {
+        throw new InvalidInputError(`An object path may not exceed ${MAX_OBJECT_KEY_LENGTH} bytes.`);
+    }
+    // A leading slash makes the key absolute and defeats prefixing entirely.
+    if (path.startsWith("/")) {
+        throw new InvalidInputError("An object path must be relative.");
+    }
+    // Backslashes are path separators on some receivers and data on others.
+    if (path.includes("\\")) {
+        throw new InvalidInputError("An object path may not contain a backslash.");
+    }
+    /**
+     * A NUL can truncate a key inside a C-based backend, so `a<NUL>../b` might be
+     * stored as `a` — traversal smuggled past a naive segment check.
+     */
+    if (CONTROL_CHARACTERS.test(path)) {
+        throw new InvalidInputError("An object path may not contain control characters.");
+    }
+    for (const segment of path.split("/")) {
+        if (segment.length === 0) {
+            // `a//b` and a trailing slash both produce an empty segment.
+            throw new InvalidInputError("An object path may not contain an empty segment.");
+        }
+        if (segment === "." || segment === "..") {
+            throw new InvalidInputError("An object path may not contain relative segments.");
+        }
+        if (segment !== segment.trim()) {
+            /**
+             * Leading or trailing whitespace is legal in S3 but invisible in every UI,
+             * which makes two objects that look identical impossible to tell apart.
+             */
+            throw new InvalidInputError("An object path segment may not be padded with whitespace.");
+        }
+    }
+}
+/** True when {@link assertObjectPath} would accept the path. */
+export function isValidObjectPath(path) {
+    try {
+        assertObjectPath(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Build the fully-qualified key for a workspace-scoped object.
+ *
+ * The workspace id is checked as a UUID rather than trusted, because it is the
+ * only thing separating one tenant's objects from another's. A caller passing a
+ * malformed id would otherwise create a prefix that could collide.
+ */
+export function workspaceObjectKey(workspaceId, path) {
+    if (!UUID.test(workspaceId)) {
+        throw new InvalidInputError("A workspace id must be a UUID.");
+    }
+    assertObjectPath(path);
+    return `${WORKSPACE_PREFIX}/${workspaceId}/${path}`;
+}
+/**
+ * Recover the workspace id and path from a scoped key.
+ *
+ * Returns `undefined` for anything that is not one, so a caller can tell a scoped
+ * key from an unscoped one rather than guessing.
+ */
+export function parseWorkspaceObjectKey(key) {
+    const parts = key.split("/");
+    if (parts.length < 3 || parts[0] !== WORKSPACE_PREFIX) {
+        return undefined;
+    }
+    const workspaceId = parts[1];
+    if (!UUID.test(workspaceId)) {
+        return undefined;
+    }
+    const path = parts.slice(2).join("/");
+    return isValidObjectPath(path) ? { workspaceId, path } : undefined;
+}
+/**
+ * Assert a key belongs to a workspace.
+ *
+ * The check that turns a stored key back into something safe to act on: a key
+ * read from a product table might have been written before a bug was fixed, or by
+ * a different tenant entirely.
+ */
+export function assertKeyBelongsTo(workspaceId, key) {
+    const parsed = parseWorkspaceObjectKey(key);
+    if (parsed === undefined || parsed.workspaceId.toLowerCase() !== workspaceId.toLowerCase()) {
+        // Deliberately does not say which case failed.
+        throw new InvalidInputError("Object key does not belong to this workspace.");
+    }
+}
+//# sourceMappingURL=keys.js.map

package/dist/storage/keys.js.map

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

package/dist/storage/memory.d.ts

@@ -0,0 +1,32 @@
+import type { ObjectBody, StorageProvider } from "./provider.ts";
+export interface MemoryObject {
+    readonly key: string;
+    readonly body: Uint8Array;
+    readonly contentType?: string;
+    readonly cacheControl?: string;
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+export interface MemoryStorageProvider extends StorageProvider {
+    readonly objects: Map<string, MemoryObject>;
+    /** Decode a stored object as text, for assertions. */
+    text(key: string): string | undefined;
+    /** Every key under a prefix. Useful for asserting tenant scoping. */
+    keysUnder(prefix: string): string[];
+    clear(): void;
+}
+export interface MemoryStorageOptions {
+    /** Returned by `publicUrl`. Omit to model a private bucket. */
+    readonly publicBaseUrl?: string;
+}
+/**
+ * An in-memory object store.
+ *
+ * For tests, and for a local development loop that should not need credentials.
+ * Signed URLs are synthesised — they carry an expiry and a signature-shaped token
+ * so a test can assert on them, but nothing verifies them. Do not mistake this for
+ * a store.
+ */
+export declare function createMemoryStorageProvider(options?: MemoryStorageOptions): MemoryStorageProvider;
+/** Bytes of a body, for assertions that do not care about encoding. */
+export declare function bodyBytes(body: ObjectBody): Uint8Array;
+//# sourceMappingURL=memory.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/storage/memory.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EAIV,eAAe,EAEhB,MAAM,eAAe,CAAC;AAEvB,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,qBAAsB,SAAQ,eAAe;IAC5D,QAAQ,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;IAC5C,sDAAsD;IACtD,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IACtC,qEAAqE;IACrE,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IACpC,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,oBAAoB;IACnC,+DAA+D;IAC/D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,GAAE,oBAAyB,GACjC,qBAAqB,CAkGvB;AAED,uEAAuE;AACvE,wBAAgB,SAAS,CAAC,IAAI,EAAE,UAAU,GAAG,UAAU,CAEtD"}

package/dist/storage/memory.js

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+/**
+ * An in-memory object store.
+ *
+ * For tests, and for a local development loop that should not need credentials.
+ * Signed URLs are synthesised — they carry an expiry and a signature-shaped token
+ * so a test can assert on them, but nothing verifies them. Do not mistake this for
+ * a store.
+ */
+export function createMemoryStorageProvider(options = {}) {
+    const objects = new Map();
+    function fakeToken(key, method, expiresAt) {
+        return createHash("sha256").update(`${method}:${key}:${expiresAt}`).digest("hex").slice(0, 32);
+    }
+    function signed(key, method, expiresInSeconds, extra = "") {
+        const expiresAt = Date.now() + expiresInSeconds * 1000;
+        return (`memory://objects/${encodeURIComponent(key)}` +
+            `?method=${method}&expires=${expiresAt}&signature=${fakeToken(key, method, expiresAt)}${extra}`);
+    }
+    return {
+        name: "memory",
+        objects,
+        async put(input) {
+            const body = typeof input.body === "string" ? new TextEncoder().encode(input.body) : input.body;
+            objects.set(input.key, {
+                key: input.key,
+                body,
+                ...(input.contentType !== undefined ? { contentType: input.contentType } : {}),
+                ...(input.cacheControl !== undefined ? { cacheControl: input.cacheControl } : {}),
+                ...(input.metadata !== undefined ? { metadata: input.metadata } : {}),
+            });
+            return {
+                key: input.key,
+                size: body.byteLength,
+                etag: createHash("md5").update(body).digest("hex"),
+            };
+        },
+        async delete(key) {
+            objects.delete(key);
+        },
+        async exists(key) {
+            return objects.has(key);
+        },
+        async stat(key) {
+            const object = objects.get(key);
+            if (object === undefined) {
+                return undefined;
+            }
+            return {
+                size: object.body.byteLength,
+                ...(object.contentType !== undefined ? { contentType: object.contentType } : {}),
+                etag: createHash("md5").update(object.body).digest("hex"),
+            };
+        },
+        publicUrl(key) {
+            return options.publicBaseUrl === undefined
+                ? undefined
+                : `${options.publicBaseUrl.replace(/\/+$/, "")}/${key}`;
+        },
+        async signedDownloadUrl(input) {
+            return signed(input.key, "GET", input.expiresInSeconds, input.downloadFilename === undefined
+                ? ""
+                : `&filename=${encodeURIComponent(input.downloadFilename)}`);
+        },
+        async signedUploadUrl(input) {
+            return signed(input.key, "PUT", input.expiresInSeconds, input.contentType === undefined ? "" : `&type=${encodeURIComponent(input.contentType)}`);
+        },
+        text(key) {
+            const object = objects.get(key);
+            return object === undefined ? undefined : new TextDecoder().decode(object.body);
+        },
+        keysUnder(prefix) {
+            return [...objects.keys()].filter((key) => key.startsWith(prefix)).sort();
+        },
+        clear() {
+            objects.clear();
+        },
+    };
+}
+/** Bytes of a body, for assertions that do not care about encoding. */
+export function bodyBytes(body) {
+    return typeof body === "string" ? new TextEncoder().encode(body) : body;
+}
+//# sourceMappingURL=memory.js.map

package/dist/storage/memory.js.map

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

package/dist/storage/provider.d.ts

@@ -0,0 +1,93 @@
+/** Bytes this package will accept for an upload. */
+export type ObjectBody = Uint8Array | string;
+export interface PutObjectInput {
+    /** Fully-qualified key. Already validated and scoped by the service. */
+    readonly key: string;
+    readonly body: ObjectBody;
+    readonly contentType?: string;
+    /** `Cache-Control` for the stored object. */
+    readonly cacheControl?: string;
+    /** Provider metadata, where supported. Never put a secret here. */
+    readonly metadata?: Readonly<Record<string, string>>;
+}
+export interface StoredObject {
+    readonly key: string;
+    readonly size: number;
+    /** Provider entity tag, when it returns one. */
+    readonly etag?: string;
+}
+export interface SignedUrlInput {
+    readonly key: string;
+    readonly expiresInSeconds: number;
+}
+export interface SignedDownloadInput extends SignedUrlInput {
+    /**
+     * Forces a download with this filename.
+     *
+     * Also the safe way to serve user-uploaded content: `attachment` stops a
+     * browser rendering an uploaded HTML or SVG file in your origin, which is
+     * stored XSS.
+     */
+    readonly downloadFilename?: string;
+}
+export interface SignedUploadInput extends SignedUrlInput {
+    /**
+     * Signed into the URL, so the client must send exactly this `Content-Type`.
+     *
+     * Worth setting: without it a client can upload anything and declare it
+     * anything.
+     */
+    readonly contentType?: string;
+}
+/**
+ * The seam between the core and an object store.
+ *
+ * Six methods. Everything above this interface is provider-independent, so moving
+ * from S3 to R2 to a local disk is an adapter rather than a migration — and
+ * nothing in product code has to know which one is in use.
+ *
+ * Implementations do **no** key validation or tenant scoping. Both happen once, in
+ * the service, before a key reaches here; a provider that also checked would give
+ * the rule two homes and one of them would drift.
+ */
+/** What a store can tell us about an object without downloading it. */
+export interface ObjectStat {
+    readonly size: number;
+    readonly contentType?: string;
+    readonly etag?: string;
+}
+export interface StorageProvider {
+    readonly name: string;
+    put(input: PutObjectInput): Promise<StoredObject>;
+    delete(key: string): Promise<void>;
+    exists(key: string): Promise<boolean>;
+    /**
+     * Object metadata, or `undefined` when there is none.
+     *
+     * Optional, because not every conceivable store can answer it — but it is what
+     * makes a direct browser upload trustworthy. A presigned `PUT` cannot enforce a
+     * size, so the only way to know what a client actually sent is to ask
+     * afterwards. Without this, a client declaring 1 KB and uploading 5 GB goes
+     * unnoticed.
+     */
+    stat?(key: string): Promise<ObjectStat | undefined>;
+    /**
+     * A permanently public URL, or `undefined` when the store is private.
+     *
+     * Callers must handle `undefined` rather than assume a URL: a private bucket is
+     * the correct default for user uploads, and only a deployment with a public CDN
+     * origin can answer this.
+     */
+    publicUrl(key: string): string | undefined;
+    /** A time-limited URL for reading a private object. */
+    signedDownloadUrl(input: SignedDownloadInput): Promise<string>;
+    /**
+     * A time-limited URL the browser can `PUT` to directly.
+     *
+     * The reason this interface exists in the shape it does: proxying uploads
+     * through the application means a request that holds a server for the length of
+     * the transfer, and a body limit on every platform in the path.
+     */
+    signedUploadUrl(input: SignedUploadInput): Promise<string>;
+}
+//# sourceMappingURL=provider.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/storage/provider.ts"],"names":[],"mappings":"AAAA,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,UAAU,GAAG,MAAM,CAAC;AAE7C,MAAM,WAAW,cAAc;IAC7B,wEAAwE;IACxE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6CAA6C;IAC7C,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACtD;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,gDAAgD;IAChD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;CACnC;AAED,MAAM,WAAW,mBAAoB,SAAQ,cAAc;IACzD;;;;;;OAMG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;CACpC;AAED,MAAM,WAAW,iBAAkB,SAAQ,cAAc;IACvD;;;;;OAKG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;;;GAUG;AACH,uEAAuE;AACvE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,GAAG,CAAC,KAAK,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;IAClD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACnC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEtC;;;;;;;;OAQG;IACH,IAAI,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,SAAS,CAAC,CAAC;IAEpD;;;;;;OAMG;IACH,SAAS,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;IAE3C,uDAAuD;IACvD,iBAAiB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAE/D;;;;;;OAMG;IACH,eAAe,CAAC,KAAK,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC5D"}

package/dist/storage/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/storage/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/storage/provider.ts"],"names":[],"mappings":""}

package/dist/storage/s3.d.ts

@@ -0,0 +1,34 @@
+import type { ObjectBody, StorageProvider } from "./provider.ts";
+import { type SigV4Credentials } from "./sigv4.ts";
+export interface S3ProviderOptions {
+    readonly bucket: string;
+    readonly region: string;
+    readonly credentials: SigV4Credentials;
+    /**
+     * Custom endpoint for an S3-compatible store — R2, MinIO, Backblaze, Supabase.
+     * Omit for AWS.
+     */
+    readonly endpoint?: string;
+    /**
+     * Put the bucket in the path rather than the host.
+     *
+     * Required by MinIO and most self-hosted stores, which cannot do wildcard
+     * subdomains. Defaults to true when an endpoint is given, false for AWS.
+     */
+    readonly forcePathStyle?: boolean;
+    /** CDN or public origin, when the bucket is publicly readable. */
+    readonly publicBaseUrl?: string;
+    readonly fetchImpl?: typeof fetch;
+    readonly now?: () => Date;
+}
+/**
+ * S3 and S3-compatible object storage.
+ *
+ * Uses SigV4 presigned URLs for reads and browser uploads, and a signed `PUT`
+ * over `fetch` for server-side writes. No AWS SDK: see `sigv4.ts` for why, and
+ * note that the signing itself is verified against AWS's published test vector.
+ */
+export declare function createS3Provider(options: S3ProviderOptions): StorageProvider;
+/** Content hash, for deduplicating or naming objects by content. */
+export declare function objectDigest(body: ObjectBody): string;
+//# sourceMappingURL=s3.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"s3.d.ts","sourceRoot":"","sources":["../../src/storage/s3.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,UAAU,EAKV,eAAe,EAEhB,MAAM,eAAe,CAAC;AACvB,OAAO,EAA6B,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAE9E,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,CAAC,EAAE,OAAO,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B;AAMD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,iBAAiB,GAAG,eAAe,CA8L5E;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,IAAI,EAAE,UAAU,GAAG,MAAM,CAErD"}