@rebasepro/server 0.22.0 → 0.24.0

package/dist/storage/GCSStorageController.d.ts

@@ -6,7 +6,7 @@
  * import cost or need it installed.
  */
 import { StorageController, GCSStorageConfig } from "./types.js";
-import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
+import { UploadFileProps, UploadFileResult, DownloadConfig, DownloadMetadata, StorageListResult } from "@rebasepro/types";
 /**
  * Google Cloud Storage implementation of `StorageController`.
  *
@@ -25,6 +25,16 @@ export declare class GCSStorageController implements StorageController {
      */
     knownBuckets(): string[];
     putObject({ file, key, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
+    /**
+     * Read the object's metadata and nothing else — no signing.
+     *
+     * Signing needs a private key. With `keyFilename` or `credentials` the
+     * client has one; on Cloud Run, GKE or GCE it has only the metadata
+     * server's token, and falls back to the IAM Credentials `signBlob` API,
+     * which the runtime account may call on itself only when it holds
+     * `iam.serviceAccounts.signBlob` there. That is not a default grant.
+     */
+    getMetadata(key: string, bucket?: string): Promise<DownloadMetadata | null>;
     getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
     getObject(key: string, bucket?: string): Promise<File | null>;
     deleteObject(key: string, bucket?: string): Promise<void>;
@@ -33,6 +43,8 @@ export declare class GCSStorageController implements StorageController {
         maxResults?: number;
         pageToken?: string;
     }): Promise<StorageListResult>;
+    /** See {@link StorageController.maxFileSize}. */
+    maxFileSize(): number;
     /**
      * Validate file before upload
      */

package/dist/storage/LocalStorageController.d.ts

@@ -63,6 +63,8 @@ export declare class LocalStorageController implements StorageController {
      * depend on it having run.
      */
     private getFullPath;
+    /** See {@link StorageController.maxFileSize}. */
+    maxFileSize(): number;
     /**
      * Validate file before upload
      */

package/dist/storage/S3StorageController.d.ts

@@ -24,6 +24,8 @@ export declare class S3StorageController implements StorageController {
      * can reach — and a mistyped one came back as "file not found".
      */
     knownBuckets(): string[];
+    /** See {@link StorageController.maxFileSize}. */
+    maxFileSize(): number;
     /**
      * Validate file before upload
      */

package/dist/storage/index.d.ts

@@ -21,8 +21,8 @@ export * from "./storage-registry.js";
 export { parseTransformOptions, transformImage, isTransformableImage, TransformCache } from "./image-transform.js";
 export type { ImageTransformOptions } from "./image-transform.js";
 export { TusHandler } from "./tus-handler.js";
-export { createUploadConstraintResolver, assertUploadWithinPropertyLimits, isAcceptedFile, readUploadPropertyContext, UPLOAD_COLLECTION_FIELD, UPLOAD_PROPERTY_FIELD } from "./property-limits.js";
-export type { UploadConstraints, ResolveUploadConstraints } from "./property-limits.js";
+export { createUploadConstraintResolver, createUploadPathResolver, assertUploadWithinPropertyLimits, assertUploadWithinPathLimits, isAcceptedFile, readUploadPropertyContext, UPLOAD_COLLECTION_FIELD, UPLOAD_PROPERTY_FIELD } from "./property-limits.js";
+export type { UploadConstraints, ResolveUploadConstraints, ResolveUploadPathConstraints } from "./property-limits.js";
 import { BackendStorageConfig, StorageController } from "./types.js";
 /**
  * Create a storage controller from a config object.

package/dist/storage/keys.d.ts

@@ -157,3 +157,15 @@ export declare function canonicalStorageBucket(rawBucket: string | undefined | n
 export declare function listingPrefix(rawPrefix: string): string | undefined;
 /** @see listingPrefix */
 export declare function folderKey(rawPrefix: string): string;
+/**
+ * A listing asked for paging a controller cannot honour: a page size below one,
+ * or a page token it never issued.
+ *
+ * Refused rather than coerced. A page size of 0 answered an empty page whose
+ * next token was the one it had been handed, so `while (pageToken)` never
+ * ended; a token of `-1` read before the first entry and crashed. The route
+ * turns this into a 400.
+ */
+export declare class InvalidListOptionsError extends Error {
+    constructor(message: string);
+}

package/dist/storage/property-limits.d.ts

@@ -12,12 +12,14 @@ import type { CollectionConfig } from "@rebasepro/types";
  * executable in the avatar bucket, and the config that said otherwise was never
  * consulted.
  *
- * The limits are per *property*, so enforcing them needs to know which property
- * a request is for. Uploads carry that as context (a form field on `POST
- * /upload`, `Upload-Metadata` on the resumable path); when it is absent the
- * global cap is still the ceiling, exactly as before. That is the honest
- * fallback: an upload that names no property has no property limit to check,
- * and refusing every context-less upload would break every existing client.
+ * The limits are per *property*, and the server finds the property two ways.
+ * By where the file lands: a property's `storagePath` is where its files go, so
+ * every upload into it meets the property's limits (`createUploadPathResolver`)
+ * — the panel never named its property, and a direct caller need not. And by
+ * name, when the upload carries context (a form field on `POST /upload`,
+ * `Upload-Metadata` on the resumable path), which covers a property whose
+ * `storagePath` is a function. A key no property claims, uploaded with no
+ * context, meets the source's own limit alone.
  */
 /** What a property says a file may be. */
 export interface UploadConstraints {
@@ -39,6 +41,39 @@ export type ResolveUploadConstraints = (collectionSlug: string, propertyPath: st
  * to choose.
  */
 export declare function createUploadConstraintResolver(collections: readonly CollectionConfig[]): ResolveUploadConstraints;
+/**
+ * The limits of every property whose storage path a key falls in.
+ *
+ * @param storageId the source the upload is written to, canonical.
+ * @param key the canonical key the upload is written to.
+ */
+export type ResolveUploadPathConstraints = (storageId: string, key: string) => UploadConstraints[];
+/**
+ * The storage-path rules of the collections this backend serves.
+ *
+ * A property's `maxSize` and `acceptedFiles` used to be checked only when an
+ * upload named the property — which the panel never did, and a direct caller
+ * simply does not — so the limits the docs called "enforced by the server"
+ * held for nobody. A property's `storagePath` is where its files go, so it is
+ * also where its limits hold: every upload into that path, through any door,
+ * meets them.
+ *
+ * A path computed by a function cannot be read without running it, and has no
+ * rule; neither has a property that declares no limits.
+ */
+export declare function createUploadPathResolver(collections: readonly CollectionConfig[]): ResolveUploadPathConstraints;
+/**
+ * Refuse an upload that no property claiming its path would accept.
+ *
+ * Several properties may share a path; the file is for one of them, so it is
+ * enough that one accepts it. When none does, the first one's refusal is the
+ * answer, naming its property.
+ */
+export declare function assertUploadWithinPathLimits(constraints: readonly UploadConstraints[], file: {
+    size?: number;
+    type?: string;
+    name?: string;
+}): void;
 /** Is this file one the property accepts? */
 export declare function isAcceptedFile(accepted: readonly string[] | undefined, contentType: string | undefined, fileName: string | undefined): boolean;
 /**

package/dist/storage/rendition-cache.d.ts

@@ -7,7 +7,17 @@ import type { StorageController } from "./types.js";
  * write down once, in the documentation, for every deployment.
  */
 export declare const RENDITION_PREFIX = "_rebase/renditions/";
-/** True for a key that names the reserved rendition space. */
+/**
+ * True for a key that names the reserved rendition space — the prefix itself,
+ * or anything under it.
+ *
+ * Compared case-folded and with `\` read as a separator, because that is how
+ * the filesystem under a local bucket reads it: on macOS and Windows
+ * `_REBASE/Renditions/x.webp` is a file in the directory `_rebase/renditions/`
+ * names, and on Windows so is `_rebase\renditions\x.webp`. A check that only
+ * knew the one spelling refused the key and accepted the same file. NFKC
+ * folds the compatibility spellings (`ſ` for `s`) the filesystem folds too.
+ */
 export declare function isRenditionKey(key: string): boolean;
 export interface RenditionCacheConfig {
     /** Off unless set. See the module comment for why. */

package/dist/storage/request-keys.d.ts

@@ -0,0 +1,82 @@
+/**
+ * The checks a caller-supplied key, bucket and storage source go through
+ * before any storage door acts on them, as HTTP answers.
+ *
+ * Shared by the REST routes and the resumable (TUS) handler, which parses its
+ * own `Upload-Metadata` and so cannot lean on the routes. Each door spelling
+ * these on its own is how one of them came to canonicalize a key without
+ * refusing the reserved rendition prefix — which made TUS the way to write the
+ * bytes a later transform serves. One module both doors import keeps every
+ * write path's idea of an acceptable key and bucket the same.
+ */
+import { ApiError } from "../api/errors.js";
+import { type RequestedStorageObject } from "./requested-object.js";
+import type { StorageController } from "./types.js";
+/**
+ * Canonicalize a caller-supplied storage key, answering 400 when it names
+ * something other than what it says.
+ *
+ * The single place a request's key becomes canonical. Every door runs its key
+ * through this before anything else touches it, so the authorize hook, the
+ * storage controller and the minted download token are all looking at the same
+ * string — which is the only thing that makes the hook's answer meaningful.
+ * See `keys.ts` for why an unacceptable key is refused rather than repaired.
+ */
+export declare function canonicalKeyOrBadRequest(key: string): string;
+/**
+ * The object a `/file/*`, `/metadata/*` or `DELETE /file/*` request's wildcard
+ * path names, answering 400 when it names none.
+ *
+ * Derived by {@link requestedStorageObject}, the function `publicObjectAuth`
+ * and `fileTokenAuth` derive it with, so the key the route acts on is the key
+ * they decided about.
+ */
+export declare function requestedObjectOrBadRequest(wildcard: string): RequestedStorageObject;
+/**
+ * {@link requestedObjectOrBadRequest} for a path that is already text rather
+ * than a URL path — the folder route's JSON body.
+ */
+export declare function objectOfPathOrBadRequest(path: string): RequestedStorageObject;
+/**
+ * Canonicalize a caller-supplied bucket name, answering 400 when it is not one.
+ *
+ * The bucket's counterpart to {@link canonicalKeyOrBadRequest}, and it exists
+ * for the same reason: the value routes a write, so it has to be checked where
+ * it enters rather than where it is used. Applied at every entry point a bucket
+ * has — the upload route's multipart body, the folder route's JSON body, the
+ * `?bucket=` query, and the TUS `Upload-Metadata` header.
+ */
+export declare function canonicalBucketOrBadRequest(bucket: string | undefined | null): string | undefined;
+/**
+ * The bucket a read or a listing may use, or a refusal naming what is served.
+ *
+ * Only checked against a controller that says what it serves
+ * ({@link StorageController.knownBuckets}); a custom implementation that does
+ * not is handed whatever the caller wrote.
+ */
+export declare function servedBucketOrRefuse(bucket: string | undefined, controller: StorageController, sources: string[]): string | undefined;
+/**
+ * The bucket a write may use, or a refusal naming what is served.
+ *
+ * On local storage a write may bring a bucket into existence:
+ * `putObject({ bucket: "media" })` creates `<root>/media`, which is deliberate,
+ * so only the *shape* of the name is checked there (by
+ * {@link canonicalBucketOrBadRequest}, inside the storage root). That reasoning
+ * is local's alone. An object store's bucket is not created by a write — the
+ * name goes to the provider as given — so on every other controller a write is
+ * held to the same list a read is, or `bucket=prod-db-backups` on an upload
+ * writes into any bucket the deployment's credentials reach.
+ */
+export declare function writableBucketOrRefuse(bucket: string | undefined, controller: StorageController, sources: string[]): string | undefined;
+/**
+ * A request that names no storage source, on a deployment with no default one.
+ *
+ * Reachable on purpose: production drops a `local` default rather than
+ * crash-looping, and keeps the named buckets that are bound. Those keep
+ * serving; only a request that names none has nowhere to go. 501 rather than
+ * 503 for the reason the no-storage stub gives — this is permanent until the
+ * project names a default, and the client's offline queue retries 503 forever.
+ *
+ * @param sources the storage sources this deployment does serve.
+ */
+export declare function noDefaultStorageSourceError(sources: string[]): ApiError;

package/dist/storage/requested-object.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Which object a storage request's URL path names.
+ *
+ * Three parties read the path of a `GET /file/*`, `GET /metadata/*` or
+ * `DELETE /file/*`: the route, which serves or deletes an object;
+ * `publicObjectAuth`, which lets an anonymous caller through when that object
+ * is public; and `fileTokenAuth`, which compares it with the path a download
+ * token grants. A decision is only about the object acted on if it is made on
+ * the same key, so all three derive it here — the wildcard, the decoding, the
+ * bucket segment and the canonical key — and none of them spells a step of its
+ * own.
+ *
+ * They used to. `publicObjectAuth` judged the raw path with a check that strips
+ * everything up to a `://`, while the route canonicalized it, folding `//` to
+ * `/`: `GET /file/notes://public/secret.txt` was public to the one and served
+ * the private key `notes:/public/secret.txt` from the other, with the authorize
+ * hook never asked.
+ *
+ * Nothing here parses a scheme. A request path is a key, optionally behind the
+ * one bucket segment the routes recognise; a `://` in it is a `:` followed by
+ * an empty segment, and canonicalization folds the empty segment away.
+ */
+/** The object a request path names. */
+export interface RequestedStorageObject {
+    /** The bucket. Always `"default"`: the only bucket a request path can name. */
+    bucket: string;
+    /** The canonical key — the one the hook is asked about and the controller acts on. */
+    key: string;
+}
+/**
+ * The wildcard part of a storage route's path, still percent-encoded.
+ *
+ * Hono's `c.req.param('*')` does not work reliably in sub-routers mounted
+ * via `app.route(prefix, subRouter)`. Instead it is derived from the
+ * fully-resolved `c.req.path` and `c.req.routePath`.
+ *
+ * For a route `/metadata/*` mounted at `/api/storage`, a request to
+ * `/api/storage/metadata/default/file.jpg` yields routePath
+ * `/api/storage/metadata/*`. The prefix (everything before `/*`) is stripped,
+ * plus one character for the trailing `/`, to obtain `default/file.jpg`.
+ */
+export declare function storageRequestWildcard(c: {
+    req: {
+        path: string;
+        routePath: string;
+    };
+}): string;
+/**
+ * The object a decoded path names: a key, behind an optional `default/` bucket
+ * segment (matched case-insensitively). Throws {@link InvalidStorageKeyError}
+ * when the key cannot be canonicalized.
+ *
+ * For a path that is already text — the folder route's JSON body. A URL path
+ * goes through {@link requestedStorageObject}, which decodes it first.
+ */
+export declare function storageObjectOfPath(decodedPath: string): RequestedStorageObject;
+/**
+ * The object a request's wildcard path names, or {@link InvalidStorageKeyError}.
+ *
+ * The wildcard arrives as Hono leaves it — `decodeURI`d, with the reserved
+ * characters (`/`, `:`, `%25` among them) still escaped — so one
+ * `decodeURIComponent` yields the path the client encoded. A `%` that does not
+ * begin an escape names no key, and is refused like any other key that cannot be
+ * canonicalized rather than thrown as a `URIError`.
+ */
+export declare function requestedStorageObject(wildcard: string): RequestedStorageObject;
+/**
+ * {@link requestedStorageObject}, or `null` when the path names no object.
+ *
+ * For the middleware, which must fail closed without an exception: a path that
+ * names no object is neither public nor covered by any download token, and the
+ * route answers it with a 400 of its own.
+ */
+export declare function tryRequestedStorageObject(wildcard: string): RequestedStorageObject | null;

package/dist/storage/routes.d.ts

@@ -10,20 +10,35 @@ import { Hono } from "hono";
 import { StorageController, type StorageAuthorize, type StorageAuthorizeData } from "./types.js";
 import { type StorageRegistry } from "./storage-registry.js";
 import { type StorageSourceDefinition, type AuthAdapter } from "@rebasepro/types";
-import { type ResolveUploadConstraints } from "./property-limits.js";
+import { type ResolveUploadConstraints, type ResolveUploadPathConstraints } from "./property-limits.js";
 import { HonoEnv } from "../api/types.js";
 import { type StorageTrigger } from "./triggers.js";
 import { type RenditionCacheConfig } from "./rendition-cache.js";
+/**
+ * The policy every SVG response carries.
+ *
+ * An SVG embedded with `<img>` never runs script. Opened directly — a link, a
+ * new tab, an `<iframe>` — it is a document on the API origin, and its
+ * `<script>` would run there, next to the refresh cookie. `sandbox` gives that
+ * document an opaque origin with scripts disabled, and `default-src 'none'`
+ * stops it loading anything; `style-src 'unsafe-inline'` keeps the inline
+ * styles most SVGs are drawn with. It is what GitHub serves user content
+ * under. Serving SVG as a download instead made every SVG logo a broken
+ * thumbnail in the panel.
+ */
+export declare const SVG_CONTENT_SECURITY_POLICY = "default-src 'none'; style-src 'unsafe-inline'; sandbox";
 /**
  * Decide what to actually serve for a stored content type.
  *
- * Returns the type to send and whether to force a download. The check is an
+ * Returns the type to send, whether to force a download, and the
+ * `Content-Security-Policy` the response must carry, if any. The check is an
  * allowlist rather than a blocklist of dangerous types: the set of types a
  * browser will execute grows, and the set we want to render inline does not.
  */
 export declare function resolveServedContentType(storedContentType: string): {
     contentType: string;
     attachment: boolean;
+    contentSecurityPolicy?: string;
 };
 export interface StorageRoutesConfig {
     /**
@@ -73,6 +88,13 @@ export interface StorageRoutesConfig {
      * to the global cap exactly as before.
      */
     uploadConstraints?: ResolveUploadConstraints;
+    /**
+     * The limits of the properties whose `storagePath` an upload's key falls
+     * in, by source and key — see `createUploadPathResolver`. Applied to every
+     * upload, whether or not it names a property, so a property's limits hold
+     * for every file written where its files go.
+     */
+    uploadPathConstraints?: ResolveUploadPathConstraints;
     /**
      * When provided, storage routes delegate auth to this adapter instead
      * of the built-in JWT module. This mirrors how data routes use
@@ -105,25 +127,21 @@ export interface StorageRoutesConfig {
      * Run something when an object lands, or when one goes. See `triggers.ts`.
      */
     triggers?: StorageTrigger[];
+    /**
+     * How long the download token `/metadata` mints for a private object stays
+     * valid, in seconds. {@link DEFAULT_DOWNLOAD_TOKEN_TTL_SECONDS} unless set;
+     * at most {@link MAX_DOWNLOAD_TOKEN_TTL_SECONDS}.
+     */
+    downloadTokenTtlSeconds?: number;
 }
+/** Five minutes: long enough to render a page of thumbnails, short enough to be worthless in a log. */
+export declare const DEFAULT_DOWNLOAD_TOKEN_TTL_SECONDS = 300;
 /**
- * Extract the wildcard portion of a route path from the full request path.
- *
- * Hono's `c.req.param('*')` does not work reliably in sub-routers mounted
- * via `app.route(prefix, subRouter)`. Instead we derive the wildcard value
- * from the fully-resolved `c.req.path` and `c.req.routePath`.
- *
- * For a route `/metadata/*` mounted at `/api/storage`, a request to
- * `/api/storage/metadata/default/file.jpg` yields routePath
- * `/api/storage/metadata/*`.  We strip the prefix (everything before `/*`)
- * plus one character for the trailing `/` to obtain `default/file.jpg`.
+ * A week. The token travels in a URL — into access logs, Referer headers and
+ * browser history — so a lifetime past this is a permanent link to a private
+ * file. A file that must be linked forever belongs under the public prefix.
  */
-export declare function extractWildcardPath(c: {
-    req: {
-        path: string;
-        routePath: string;
-    };
-}): string;
+export declare const MAX_DOWNLOAD_TOKEN_TTL_SECONDS: number;
 /**
  * Create storage REST API routes
  */

package/dist/storage/tus-handler.d.ts

@@ -10,7 +10,7 @@
 import type { Context } from "hono";
 import type { StorageController } from "./types.js";
 import { type StorageRegistry } from "./storage-registry.js";
-import { type ResolveUploadConstraints } from "./property-limits.js";
+import { type ResolveUploadConstraints, type ResolveUploadPathConstraints } from "./property-limits.js";
 /**
  * TUS resumable upload handler.
  *
@@ -65,6 +65,12 @@ export declare class TusHandler {
      * accept is refused before the first chunk rather than after the last.
      */
     private uploadConstraints?;
+    /**
+     * The limits of the properties whose storage path the upload's key
+     * falls in — checked whether or not the upload names a property, as
+     * `POST /upload` checks them.
+     */
+    private uploadPathConstraints?;
     private uploads;
     private tusDir;
     private cleanupTimer?;
@@ -123,7 +129,13 @@ export declare class TusHandler {
      * and the metadata's content type, so a file the property will not
      * accept is refused before the first chunk rather than after the last.
      */
-    uploadConstraints?: ResolveUploadConstraints | undefined);
+    uploadConstraints?: ResolveUploadConstraints | undefined, 
+    /**
+     * The limits of the properties whose storage path the upload's key
+     * falls in — checked whether or not the upload names a property, as
+     * `POST /upload` checks them.
+     */
+    uploadPathConstraints?: ResolveUploadPathConstraints | undefined);
     /** Ensure the temp directory exists. */
     private ensureDir;
     /** Start periodic cleanup of stale uploads. */
@@ -136,8 +148,21 @@ export declare class TusHandler {
      * Format: `key base64value,key2 base64value2`
      */
     private parseMetadata;
-    /** `OPTIONS /tus` — TUS capability discovery. */
-    options(): Response;
+    /** The controller an upload to this storage source is written to. */
+    private targetFor;
+    /**
+     * The largest upload this source takes: the source's own limit, under the
+     * deployment's and the protocol ceiling. One function for what `OPTIONS`
+     * advertises and what `create` enforces, which used to be 5 GB and 50 MB.
+     */
+    private limitFor;
+    /**
+     * `OPTIONS /tus` — TUS capability discovery.
+     *
+     * `Tus-Max-Size` is the limit `create` holds this source to, for the source
+     * named by `?storageId` (the default one otherwise).
+     */
+    options(c?: Context): Response;
     /** `POST /tus` — Create a new upload. */
     create(c: Context): Promise<Response>;
     /**
@@ -162,7 +187,7 @@ export declare class TusHandler {
     private ownedUpload;
     /** `HEAD /tus/:id` — Query upload progress. */
     head(c: Context, id: string): Response;
-    /** `PATCH /tus/:id` — Append data to an upload. */
+    /** `PATCH /tus/:id` — Write one chunk of an upload, at its offset. */
     patch(c: Context, id: string): Promise<Response>;
     /** `DELETE /tus/:id` — Cancel and remove an upload. */
     delete(c: Context, id: string): Promise<Response>;

package/dist/storage/types.d.ts

@@ -1,7 +1,7 @@
 /**
  * Storage configuration and types for Rebase backend
  */
-import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
+import { UploadFileProps, UploadFileResult, DownloadConfig, DownloadMetadata, StorageListResult } from "@rebasepro/types";
 /**
  * Local filesystem storage configuration
  */
@@ -23,6 +23,14 @@ export interface LocalStorageConfig {
      * production, where an unbound object store stays unbound.
      */
     standsInFor?: string;
+    /**
+     * Set when nothing chose this backend: no `STORAGE_TYPE` and no declared
+     * engine, so local disk is only the default a source falls back to.
+     * Production drops a local backend either way. This only decides how that
+     * is reported: an implicit default being dropped means the project uses no
+     * storage, which is not a misconfiguration.
+     */
+    implicit?: boolean;
 }
 /**
  * S3-compatible storage configuration (works with AWS S3 and MinIO)
@@ -100,6 +108,22 @@ export interface StorageController {
      * Get a download URL (signed URL equivalent) for an object
      */
     getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
+    /**
+     * Describe an object — size, type, custom metadata — without producing a
+     * URL for it, or `null` when there is no such object.
+     *
+     * `GET /metadata/*` wants only this: the client builds its own `/file/*`
+     * URL and spends the download token the route mints. Asking
+     * `getSignedUrl` for it made every metadata read sign a URL nobody used,
+     * and on GCS signing is not free — without a key file the client asks the
+     * IAM Credentials API to sign, which needs `iam.serviceAccounts.signBlob`
+     * on the runtime account itself. Cloud Run does not grant that, so every
+     * private object answered 500 there.
+     *
+     * A controller that does not implement this keeps the old behaviour: the
+     * route falls back to `getSignedUrl` and reads its `metadata`.
+     */
+    getMetadata?(key: string, bucket?: string): Promise<DownloadMetadata | null>;
     /**
      * Get object as a File
      */
@@ -143,6 +167,17 @@ export interface StorageController {
      * when the caller names none, and each provider maps it to its own.
      */
     knownBuckets?(): string[];
+    /**
+     * The largest file this controller accepts, in bytes.
+     *
+     * Every door that takes a file reads it, so the number a client is told is
+     * the number it is held to: the upload route checks it before anything is
+     * stored, the resumable route checks it at creation — before the first
+     * chunk rather than after the last — and advertises it as `Tus-Max-Size`,
+     * and the server's upload body limit is the largest of them. A controller
+     * that does not implement this is held to the deployment-wide limit alone.
+     */
+    maxFileSize?(): number;
 }
 /**
  * Default maximum file size (50MB)

package/dist/types-BfKcm9do.js.map

@@ -1 +1 @@
-{"version":3,"file":"types-BfKcm9do.js","names":[],"sources":["../src/storage/types.ts"],"sourcesContent":["/**\n * Storage configuration and types for Rebase backend\n */\n\nimport { StorageSource, UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult, StorageReference } from \"@rebasepro/types\";\n\n/**\n * Local filesystem storage configuration\n */\nexport interface LocalStorageConfig {\n    type: \"local\";\n    /** Base directory for file storage (e.g., './uploads') */\n    basePath: string;\n    /** Maximum file size in bytes (default: 50MB) */\n    maxFileSize?: number;\n    /** Allowed MIME types (if not set, all types allowed) */\n    allowedMimeTypes?: string[];\n    /** Base URL for generating download URLs (default: auto-detected from request) */\n    baseUrl?: string;\n    /**\n     * Set when this local backend stands in for an object store the source\n     * declared and nothing bound — `bucket(\"media\", { engine: \"s3\" })` with no\n     * `S3_BUCKET__MEDIA` in a development process. Names the engine it stands\n     * in for, so boot can say so and `rebase status` can show it. Never set in\n     * production, where an unbound object store stays unbound.\n     */\n    standsInFor?: string;\n}\n\n/**\n * S3-compatible storage configuration (works with AWS S3 and MinIO)\n */\nexport interface S3StorageConfig {\n    type: \"s3\";\n    /** S3 bucket name */\n    bucket: string;\n    /** AWS region (e.g., 'us-east-1') */\n    region?: string;\n    /** Custom endpoint URL (required for MinIO, Cloudflare R2, Hetzner Object Storage) */\n    endpoint?: string;\n    /** AWS access key ID */\n    accessKeyId: string;\n    /** AWS secret access key */\n    secretAccessKey: string;\n    /** Use path-style URLs (required for MinIO) */\n    forcePathStyle?: boolean;\n    /** Maximum file size in bytes (default: 50MB) */\n    maxFileSize?: number;\n    /** Allowed MIME types (if not set, all types allowed) */\n    allowedMimeTypes?: string[];\n    /** URL expiration time in seconds for signed URLs (default: 3600) */\n    signedUrlExpiration?: number;\n}\n\n/**\n * Google Cloud Storage configuration (works with GCS and Firebase Storage)\n */\nexport interface GCSStorageConfig {\n    type: \"gcs\";\n    /** GCS bucket name (e.g. \"my-project.appspot.com\" for Firebase Storage) */\n    bucket: string;\n    /** GCP project ID (optional, auto-detected from credentials) */\n    projectId?: string;\n    /** Path to service account JSON key file */\n    keyFilename?: string;\n    /** Service account credentials object (alternative to keyFilename) */\n    credentials?: { client_email: string; private_key: string; project_id?: string };\n    /** Maximum file size in bytes (default: 50MB) */\n    maxFileSize?: number;\n    /** Allowed MIME types */\n    allowedMimeTypes?: string[];\n    /** Signed URL expiration in seconds (default: 3600) */\n    signedUrlExpiration?: number;\n}\n\n/**\n * Storage configuration — local filesystem, S3-compatible, or Google Cloud Storage.\n *\n * **Built-in providers:**\n * - `local` — Zero-config filesystem storage. Great for dev and single-server deployments (Hetzner, bare metal).\n * - `s3` — Any S3-compatible provider. AWS S3, Cloudflare R2, MinIO, Hetzner Object Storage,\n *           Backblaze B2, DigitalOcean Spaces, and even GCS (via its S3-compatible interoperability API).\n * - `gcs` — Native Google Cloud Storage / Firebase Storage via `@google-cloud/storage`.\n *\n * **Custom providers:**\n * For other cloud storage (Azure Blob, etc.), implement the `StorageController`\n * interface and pass the instance directly to the `storage` config.\n */\nexport type BackendStorageConfig = LocalStorageConfig | S3StorageConfig | GCSStorageConfig;\n\n/** What a storage request is trying to do to an object. */\nexport type {\n    StorageOperation,\n    StorageAuthorizeUser,\n    StorageAuthorizeContext,\n    StorageAuthorizeData,\n    StorageAuthorize\n} from \"@rebasepro/types\";\n\n/**\n * Storage controller interface for backend implementations\n */\nexport interface StorageController {\n    /**\n     * Upload an object\n     */\n    putObject(props: UploadFileProps): Promise<UploadFileResult>;\n\n    /**\n     * Get a download URL (signed URL equivalent) for an object\n     */\n    getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;\n\n    /**\n     * Get object as a File\n     */\n    getObject(key: string, bucket?: string): Promise<File | null>;\n\n    /**\n     * Delete an object\n     */\n    deleteObject(key: string, bucket?: string): Promise<void>;\n\n    /**\n     * List objects in a prefix\n     */\n    listObjects(prefix: string, options?: {\n        bucket?: string;\n        maxResults?: number;\n        pageToken?: string;\n    }): Promise<StorageListResult>;\n\n    /**\n     * Get the storage provider identifier.\n     *\n     * Built-in values are `'local'` and `'s3'`. Custom implementations\n     * should return their own identifier (e.g. `'gcs'`, `'azure'`).\n     */\n    getType(): string;\n\n    /**\n     * The buckets this controller serves, if it knows.\n     *\n     * The `bucket` a request may name is not a free-text field: on S3 and GCS it\n     * goes straight to the provider, so an unvalidated one addresses *any*\n     * bucket the deployment's credentials can reach, and locally it names a\n     * directory the framework would create on demand. Either way, a caller who\n     * mistypes it gets \"file not found\" — the same answer as a missing object —\n     * with nothing to say the bucket was the problem.\n     *\n     * So a controller that knows its buckets says so, and the routes refuse\n     * anything else with `UNKNOWN_STORAGE_SOURCE` naming what is served. A\n     * controller that does not implement this keeps the old behaviour and is\n     * handed whatever the caller wrote — a custom implementation may address\n     * buckets this framework has no way to enumerate.\n     *\n     * `\"default\"` is always among them: it is the logical name every route uses\n     * when the caller names none, and each provider maps it to its own.\n     */\n    knownBuckets?(): string[];\n}\n\n/**\n * Default maximum file size (50MB)\n */\nexport const DEFAULT_MAX_FILE_SIZE = 50 * 1024 * 1024;\n\n/**\n * Common image MIME types\n */\nexport const IMAGE_MIME_TYPES = [\n    \"image/jpeg\",\n    \"image/png\",\n    \"image/gif\",\n    \"image/webp\",\n    \"image/svg+xml\",\n    \"image/bmp\",\n    \"image/tiff\"\n];\n\n/**\n * Common document MIME types\n */\nexport const DOCUMENT_MIME_TYPES = [\n    \"application/pdf\",\n    \"application/msword\",\n    \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n    \"application/vnd.ms-excel\",\n    \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n    \"application/vnd.ms-powerpoint\",\n    \"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n    \"text/plain\",\n    \"text/csv\"\n];\n"],"mappings":";;;;;;;;AAqKA,IAAa,wBAAwB,KAAK,OAAO;;;;AAKjD,IAAa,mBAAmB;CAC5B;CACA;CACA;CACA;CACA;CACA;CACA;AACJ;;;;AAKA,IAAa,sBAAsB;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACJ"}
+{"version":3,"file":"types-BfKcm9do.js","names":[],"sources":["../src/storage/types.ts"],"sourcesContent":["/**\n * Storage configuration and types for Rebase backend\n */\n\nimport { StorageSource, UploadFileProps, UploadFileResult, DownloadConfig, DownloadMetadata, StorageListResult, StorageReference } from \"@rebasepro/types\";\n\n/**\n * Local filesystem storage configuration\n */\nexport interface LocalStorageConfig {\n    type: \"local\";\n    /** Base directory for file storage (e.g., './uploads') */\n    basePath: string;\n    /** Maximum file size in bytes (default: 50MB) */\n    maxFileSize?: number;\n    /** Allowed MIME types (if not set, all types allowed) */\n    allowedMimeTypes?: string[];\n    /** Base URL for generating download URLs (default: auto-detected from request) */\n    baseUrl?: string;\n    /**\n     * Set when this local backend stands in for an object store the source\n     * declared and nothing bound — `bucket(\"media\", { engine: \"s3\" })` with no\n     * `S3_BUCKET__MEDIA` in a development process. Names the engine it stands\n     * in for, so boot can say so and `rebase status` can show it. Never set in\n     * production, where an unbound object store stays unbound.\n     */\n    standsInFor?: string;\n    /**\n     * Set when nothing chose this backend: no `STORAGE_TYPE` and no declared\n     * engine, so local disk is only the default a source falls back to.\n     * Production drops a local backend either way. This only decides how that\n     * is reported: an implicit default being dropped means the project uses no\n     * storage, which is not a misconfiguration.\n     */\n    implicit?: boolean;\n}\n\n/**\n * S3-compatible storage configuration (works with AWS S3 and MinIO)\n */\nexport interface S3StorageConfig {\n    type: \"s3\";\n    /** S3 bucket name */\n    bucket: string;\n    /** AWS region (e.g., 'us-east-1') */\n    region?: string;\n    /** Custom endpoint URL (required for MinIO, Cloudflare R2, Hetzner Object Storage) */\n    endpoint?: string;\n    /** AWS access key ID */\n    accessKeyId: string;\n    /** AWS secret access key */\n    secretAccessKey: string;\n    /** Use path-style URLs (required for MinIO) */\n    forcePathStyle?: boolean;\n    /** Maximum file size in bytes (default: 50MB) */\n    maxFileSize?: number;\n    /** Allowed MIME types (if not set, all types allowed) */\n    allowedMimeTypes?: string[];\n    /** URL expiration time in seconds for signed URLs (default: 3600) */\n    signedUrlExpiration?: number;\n}\n\n/**\n * Google Cloud Storage configuration (works with GCS and Firebase Storage)\n */\nexport interface GCSStorageConfig {\n    type: \"gcs\";\n    /** GCS bucket name (e.g. \"my-project.appspot.com\" for Firebase Storage) */\n    bucket: string;\n    /** GCP project ID (optional, auto-detected from credentials) */\n    projectId?: string;\n    /** Path to service account JSON key file */\n    keyFilename?: string;\n    /** Service account credentials object (alternative to keyFilename) */\n    credentials?: { client_email: string; private_key: string; project_id?: string };\n    /** Maximum file size in bytes (default: 50MB) */\n    maxFileSize?: number;\n    /** Allowed MIME types */\n    allowedMimeTypes?: string[];\n    /** Signed URL expiration in seconds (default: 3600) */\n    signedUrlExpiration?: number;\n}\n\n/**\n * Storage configuration — local filesystem, S3-compatible, or Google Cloud Storage.\n *\n * **Built-in providers:**\n * - `local` — Zero-config filesystem storage. Great for dev and single-server deployments (Hetzner, bare metal).\n * - `s3` — Any S3-compatible provider. AWS S3, Cloudflare R2, MinIO, Hetzner Object Storage,\n *           Backblaze B2, DigitalOcean Spaces, and even GCS (via its S3-compatible interoperability API).\n * - `gcs` — Native Google Cloud Storage / Firebase Storage via `@google-cloud/storage`.\n *\n * **Custom providers:**\n * For other cloud storage (Azure Blob, etc.), implement the `StorageController`\n * interface and pass the instance directly to the `storage` config.\n */\nexport type BackendStorageConfig = LocalStorageConfig | S3StorageConfig | GCSStorageConfig;\n\n/** What a storage request is trying to do to an object. */\nexport type {\n    StorageOperation,\n    StorageAuthorizeUser,\n    StorageAuthorizeContext,\n    StorageAuthorizeData,\n    StorageAuthorize\n} from \"@rebasepro/types\";\n\n/**\n * Storage controller interface for backend implementations\n */\nexport interface StorageController {\n    /**\n     * Upload an object\n     */\n    putObject(props: UploadFileProps): Promise<UploadFileResult>;\n\n    /**\n     * Get a download URL (signed URL equivalent) for an object\n     */\n    getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;\n\n    /**\n     * Describe an object — size, type, custom metadata — without producing a\n     * URL for it, or `null` when there is no such object.\n     *\n     * `GET /metadata/*` wants only this: the client builds its own `/file/*`\n     * URL and spends the download token the route mints. Asking\n     * `getSignedUrl` for it made every metadata read sign a URL nobody used,\n     * and on GCS signing is not free — without a key file the client asks the\n     * IAM Credentials API to sign, which needs `iam.serviceAccounts.signBlob`\n     * on the runtime account itself. Cloud Run does not grant that, so every\n     * private object answered 500 there.\n     *\n     * A controller that does not implement this keeps the old behaviour: the\n     * route falls back to `getSignedUrl` and reads its `metadata`.\n     */\n    getMetadata?(key: string, bucket?: string): Promise<DownloadMetadata | null>;\n\n    /**\n     * Get object as a File\n     */\n    getObject(key: string, bucket?: string): Promise<File | null>;\n\n    /**\n     * Delete an object\n     */\n    deleteObject(key: string, bucket?: string): Promise<void>;\n\n    /**\n     * List objects in a prefix\n     */\n    listObjects(prefix: string, options?: {\n        bucket?: string;\n        maxResults?: number;\n        pageToken?: string;\n    }): Promise<StorageListResult>;\n\n    /**\n     * Get the storage provider identifier.\n     *\n     * Built-in values are `'local'` and `'s3'`. Custom implementations\n     * should return their own identifier (e.g. `'gcs'`, `'azure'`).\n     */\n    getType(): string;\n\n    /**\n     * The buckets this controller serves, if it knows.\n     *\n     * The `bucket` a request may name is not a free-text field: on S3 and GCS it\n     * goes straight to the provider, so an unvalidated one addresses *any*\n     * bucket the deployment's credentials can reach, and locally it names a\n     * directory the framework would create on demand. Either way, a caller who\n     * mistypes it gets \"file not found\" — the same answer as a missing object —\n     * with nothing to say the bucket was the problem.\n     *\n     * So a controller that knows its buckets says so, and the routes refuse\n     * anything else with `UNKNOWN_STORAGE_SOURCE` naming what is served. A\n     * controller that does not implement this keeps the old behaviour and is\n     * handed whatever the caller wrote — a custom implementation may address\n     * buckets this framework has no way to enumerate.\n     *\n     * `\"default\"` is always among them: it is the logical name every route uses\n     * when the caller names none, and each provider maps it to its own.\n     */\n    knownBuckets?(): string[];\n\n    /**\n     * The largest file this controller accepts, in bytes.\n     *\n     * Every door that takes a file reads it, so the number a client is told is\n     * the number it is held to: the upload route checks it before anything is\n     * stored, the resumable route checks it at creation — before the first\n     * chunk rather than after the last — and advertises it as `Tus-Max-Size`,\n     * and the server's upload body limit is the largest of them. A controller\n     * that does not implement this is held to the deployment-wide limit alone.\n     */\n    maxFileSize?(): number;\n}\n\n/**\n * Default maximum file size (50MB)\n */\nexport const DEFAULT_MAX_FILE_SIZE = 50 * 1024 * 1024;\n\n/**\n * Common image MIME types\n */\nexport const IMAGE_MIME_TYPES = [\n    \"image/jpeg\",\n    \"image/png\",\n    \"image/gif\",\n    \"image/webp\",\n    \"image/svg+xml\",\n    \"image/bmp\",\n    \"image/tiff\"\n];\n\n/**\n * Common document MIME types\n */\nexport const DOCUMENT_MIME_TYPES = [\n    \"application/pdf\",\n    \"application/msword\",\n    \"application/vnd.openxmlformats-officedocument.wordprocessingml.document\",\n    \"application/vnd.ms-excel\",\n    \"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet\",\n    \"application/vnd.ms-powerpoint\",\n    \"application/vnd.openxmlformats-officedocument.presentationml.presentation\",\n    \"text/plain\",\n    \"text/csv\"\n];\n"],"mappings":";;;;;;;;AA0MA,IAAa,wBAAwB,KAAK,OAAO;;;;AAKjD,IAAa,mBAAmB;CAC5B;CACA;CACA;CACA;CACA;CACA;CACA;AACJ;;;;AAKA,IAAa,sBAAsB;CAC/B;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;AACJ"}

package/dist/utils/logger.d.ts

@@ -50,6 +50,18 @@ export declare function rawQueryLoggingEnabled(): boolean;
  * before persisting and then logs the result.
  */
 export declare function redactSensitiveText(text: string): string;
+/**
+ * `JSON.stringify`, with the redaction a structured field gets.
+ *
+ * For a value that has to go *into the message*. Once an object is a string,
+ * `emit` can only strip `Failed query:` spans out of it: a sensitive key would
+ * pass, and so would the `query` and `params` own-properties `DrizzleQueryError`
+ * carries beside its message, which `JSON.stringify` copies and the message
+ * redaction never sees. Unlike the structured walk this honours `toJSON`, since
+ * the result is read as text. Never throws: a value that cannot be stringified
+ * is a marker, not a failed log line.
+ */
+export declare function stringifyForLog(value: unknown): string | undefined;
 /**
  * Something that wants a copy of every line this logger writes.
  *