@rebasepro/server 0.23.0 → 0.24.1-canary.g19596ef

package/dist/storage/LocalStorageController.d.ts

@@ -1,7 +1,7 @@
 /**
  * Local filesystem storage controller
  */
-import { StorageController, LocalStorageConfig } from "./types.js";
+import { StorageController, LocalStorageConfig, type StoredObjectInfo, type StoredObjectRange, type PutObjectOptions, type StoredObjectStream } from "./types.js";
 import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult } from "@rebasepro/types";
 /**
  * Bucket used when a call names none.
@@ -10,6 +10,22 @@ import { UploadFileProps, UploadFileResult, DownloadConfig, StorageListResult }
  * bare key lives.
  */
 export declare const DEFAULT_BUCKET = "default";
+/**
+ * Refuse a key that names one of local storage's own files rather than an
+ * object: the metadata beside an object, or a write in progress.
+ *
+ * Both live in the object namespace, beside the objects they serve. A key that
+ * names one used to be stored like any other, and so overwrote another
+ * object's metadata: uploading `a.png.metadata.json` changed the content type
+ * `a.png` is served with — the authorize hook asked about the one key while
+ * the other changed — and the uploader's own file vanished from listings and
+ * went with `a.png` when that was deleted. Read, it served the metadata.
+ *
+ * Local only: S3 and GCS keep metadata on the object, so every key there is
+ * an object. A 400, at every operation, because every one resolves its path
+ * through `getFullPath`.
+ */
+export declare function refuseLocalReservedKey(key: string): void;
 /**
  * Local filesystem storage implementation
  * Stores files in a directory structure: {basePath}/{bucket}/{path}
@@ -17,8 +33,26 @@ export declare const DEFAULT_BUCKET = "default";
 export declare class LocalStorageController implements StorageController {
     private config;
     private basePath;
+    /**
+     * Folder entries read by a listing's first page, for its continuation
+     * pages. Keyed by the folder's absolute path (bucket included). Not
+     * caller-scoped, because the entries are not: every caller of this method
+     * gets the same names, and the routes authorize the prefix before calling
+     * it. Insertion-ordered, so the first key is the oldest.
+     */
+    private readonly listingSnapshots;
     constructor(config: LocalStorageConfig);
     getType(): "local";
+    /**
+     * Whether the file system under the storage root folds case — macOS and
+     * Windows by default — so `Avatar.png` and `avatar.png` are one file here
+     * and two on S3, GCS or a Linux disk.
+     *
+     * Read by writing a probe file and asking for it in the other case. The
+     * root is created if it is not there yet; the probe is removed. `false`
+     * when the root cannot be written: nothing is known.
+     */
+    isCaseInsensitive(): Promise<boolean>;
     /**
      * The bucket directories that exist under the storage root, plus `default`.
      *
@@ -63,19 +97,52 @@ export declare class LocalStorageController implements StorageController {
      * depend on it having run.
      */
     private getFullPath;
+    /** See {@link StorageController.maxFileSize}. */
+    maxFileSize(): number;
     /**
      * Validate file before upload
      */
     private validateFile;
-    putObject({ file, key, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
+    putObject({ file, key, metadata, bucket }: UploadFileProps, options?: PutObjectOptions): Promise<UploadFileResult>;
     getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
     getObject(key: string, bucket?: string): Promise<File | null>;
+    /** The file a read of `key` addresses — `getObject`'s resolution, `local://` URLs included. */
+    private readPath;
+    /** See {@link StorageController.statObject}. A `stat` and the metadata sidecar; the file is not read. */
+    statObject(key: string, bucket?: string): Promise<StoredObjectInfo | null>;
+    /**
+     * See {@link StorageController.getObjectStream}. The file — or only the
+     * requested range of it — read from disk a chunk at a time, opened on the
+     * first read.
+     */
+    getObjectStream(key: string, options?: {
+        bucket?: string;
+        range?: StoredObjectRange;
+    }): Promise<StoredObjectStream | null>;
     deleteObject(key: string, bucket?: string): Promise<void>;
     listObjects(prefix: string, options?: {
         bucket?: string;
         maxResults?: number;
         pageToken?: string;
     }): Promise<StorageListResult>;
+    /**
+     * A folder's entries for a listing page.
+     *
+     * A page token is an index into these entries, and every continuation
+     * page used to read the whole folder again to find its place: a folder of
+     * n entries listed in pages of p cost n/p full reads. A first page reads
+     * the folder and, when there is a next page, keeps the read; a
+     * continuation page indexes into it while all of these hold:
+     *
+     *  - the folder's mtime is the one read with it. Adding, removing or
+     *    renaming an entry changes it, which is the invalidation;
+     *  - it is under {@link LISTING_SNAPSHOT_TTL_MS} old;
+     *  - the folder had not changed in the {@link LISTING_SNAPSHOT_RACY_MS}
+     *    before the read. Otherwise it is not kept at all.
+     *
+     * A first page always reads the folder as it is.
+     */
+    private listingEntries;
     /**
      * Get the absolute filesystem path for serving files
      * Used by the storage routes to serve files directly

package/dist/storage/S3StorageController.d.ts

@@ -1,8 +1,8 @@
 /**
  * S3-compatible storage controller (works with AWS S3 and MinIO)
  */
-import { S3StorageConfig, StorageController } from "./types.js";
-import { DownloadConfig, StorageListResult, UploadFileProps, UploadFileResult } from "@rebasepro/types";
+import { S3StorageConfig, StorageController, type StoredObjectInfo, type StoredObjectRange, type PutObjectOptions, type StoredObjectStream } from "./types.js";
+import { DownloadConfig, DownloadMetadata, StorageListResult, UploadFileProps, UploadFileResult } from "@rebasepro/types";
 /**
  * S3-compatible storage implementation
  * Works with AWS S3 and MinIO (with forcePathStyle option)
@@ -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
      */
@@ -32,13 +34,47 @@ export declare class S3StorageController implements StorageController {
      * Get the bucket name - either from parameter or config
      */
     private getBucket;
-    putObject({ file, key, metadata, bucket }: UploadFileProps): Promise<UploadFileResult>;
+    putObject({ file, key, metadata, bucket }: UploadFileProps, options?: PutObjectOptions): Promise<UploadFileResult>;
+    /**
+     * Upload a large file in parts, one part in memory at a time.
+     *
+     * Reading the whole file into one buffer held it twice over (the
+     * `arrayBuffer()`, then the SDK's view and the multipart parser's copy
+     * before it), and `PutObject` stops at 5 GB regardless. A slice of a
+     * `File` reads only that range — from disk, for the disk-backed files TUS
+     * and backups hand over — so memory is one part whatever the file's size.
+     * A failure aborts the upload: no partial object appears at the key, and
+     * no orphaned parts are kept (and billed).
+     */
+    private putMultipart;
     /**
      * Flatten nested metadata to string values (S3 requirement)
      */
     private flattenMetadata;
     getSignedUrl(key: string, bucket?: string): Promise<DownloadConfig>;
     getObject(key: string, bucket?: string): Promise<File | null>;
+    /**
+     * The bucket and key a call addresses: an `s3://` or `gs://` URL names its
+     * own bucket, anything else is a key in the given (or configured) bucket.
+     */
+    private resolveLocation;
+    /**
+     * See {@link StorageController.getMetadata}. One `HeadObject`. Without it,
+     * `GET /metadata/*` fell back to `getSignedUrl`, which signed a URL per
+     * call — ~134 µs of CPU — only for the route to throw it away.
+     */
+    getMetadata(key: string, bucket?: string): Promise<DownloadMetadata | null>;
+    /** See {@link StorageController.statObject}. One `HeadObject`; no body is read. */
+    statObject(key: string, bucket?: string): Promise<StoredObjectInfo | null>;
+    /**
+     * See {@link StorageController.getObjectStream}. One `GetObject`, with a
+     * `Range` when one is asked for, so only those bytes leave the bucket; the
+     * body is handed on as it arrives rather than collected first.
+     */
+    getObjectStream(key: string, options?: {
+        bucket?: string;
+        range?: StoredObjectRange;
+    }): Promise<StoredObjectStream | null>;
     deleteObject(key: string, bucket?: string): Promise<void>;
     listObjects(prefix: string, options?: {
         bucket?: string;

package/dist/storage/image-transform.d.ts

@@ -5,6 +5,16 @@
  * adjustment using the `sharp` library. Results are cached in an LRU
  * in-memory cache to avoid redundant processing.
  */
+/**
+ * Raised by {@link transformImage} when `sharp` is not installed. The storage
+ * routes never reach it: they ask {@link imageTransformsAvailable} first and
+ * serve the original.
+ */
+export declare class ImageTransformUnavailableError extends Error {
+    constructor();
+}
+/** Whether this process can transform images — whether `sharp` loads. */
+export declare function imageTransformsAvailable(): Promise<boolean>;
 /** Options that can be specified via query parameters. */
 export interface ImageTransformOptions {
     width?: number;
@@ -70,6 +80,11 @@ export declare const DECODABLE_FORMATS: Set<string>;
 export declare class UntransformableImageError extends Error {
     constructor(message: string);
 }
+/**
+ * The content type a transform with these options produces: its `format`, or
+ * WebP when it names none, as {@link transformImage} encodes it.
+ */
+export declare function transformContentType(options: ImageTransformOptions): string;
 /** Check whether a content type is a transformable image. */
 export declare function isTransformableImage(contentType: string): boolean;
 /**

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/maintenance-routes.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `/admin/storage` — the routes behind `rebase storage orphans` and
+ * `rebase storage move`. Admin-only; the caller mounts them behind the admin
+ * gate (`database:read` to read, `database:write` to delete or move).
+ *
+ *   GET    /orphans?storageId=&olderThanHours=   objects no row names
+ *   DELETE /orphans?storageId=&olderThanHours=   delete them, found again first
+ *   POST   /move  { from, to, prefix?, cursor?, limit?, deleteSource? }
+ */
+import { Hono } from "hono";
+import type { CollectionConfig, DataDriver } from "@rebasepro/types";
+import type { HonoEnv } from "../api/types.js";
+import type { StorageController } from "./types.js";
+import type { StorageRegistry } from "./storage-registry.js";
+export interface StorageMaintenanceRoutesConfig {
+    registry?: StorageRegistry;
+    controller?: StorageController;
+    /** The collections whose rows are read for references, read per request. */
+    collections: () => readonly CollectionConfig[];
+    /** The unscoped driver serving a collection: every row, whoever wrote it. */
+    driverFor: (collection: CollectionConfig) => DataDriver | undefined;
+}
+export declare function createStorageMaintenanceRoutes(config: StorageMaintenanceRoutesConfig): Hono<HonoEnv>;

package/dist/storage/maintenance.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Storage maintenance: the objects a source holds that no row names
+ * (`rebase storage orphans`), and copying a folder of objects from one source
+ * to another (`rebase storage move`).
+ *
+ * Nothing deletes a stored file when its field is cleared, its file replaced or
+ * its row deleted — two rows may hold one key, so the panel cannot know a file
+ * is unused. What can know is a scan of every row against every object, which
+ * is what this is. It errs one way only: a string anywhere in any row that
+ * could name an object keeps that object, whichever source it is in and
+ * whichever property holds it. A file is reported only when nothing points at
+ * it at all.
+ */
+import type { CollectionConfig, DataDriver } from "@rebasepro/types";
+import type { StorageController } from "./types.js";
+/** One stored object, as a listing describes it. */
+export interface StoredObjectEntry {
+    key: string;
+    size?: number;
+    /** ISO 8601, when the source's listing says. */
+    updated?: string;
+}
+/** A request this module cannot act on: a bad cursor, a source that is not served. */
+export declare class InvalidMaintenanceRequestError extends Error {
+}
+/**
+ * The objects under a folder of a source, folder by folder, at most `limit` at
+ * a time. Hand the returned `cursor` back for the next ones; none means the
+ * walk is done. The internal `_rebase/` folder is not walked.
+ */
+export declare function walkObjects(controller: StorageController, options?: {
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+}): Promise<{
+    objects: StoredObjectEntry[];
+    cursor?: string;
+}>;
+/**
+ * The keys one stored string could name an object by.
+ *
+ * A file field stores a bare key, a `local://`, `s3://` or `gs://` URL with the
+ * bucket, or — with `storeUrl` — a download URL; text stores
+ * `rebase-storage:` references, and from before those, download URLs. Each
+ * spelling yields the key it names, and a key under a leading `default/` is
+ * also read without it, as the routes read it.
+ */
+export declare function keysNamedBy(value: string): string[];
+/** A collection whose rows could not be read, and why. */
+export interface UnscannedCollection {
+    collection: string;
+    reason: string;
+}
+/**
+ * Remove from `keys` every key some row names.
+ *
+ * Every row of every collection is read — soft-deleted rows too, since a
+ * restore brings their files back — a page at a time, through the driver that
+ * serves the collection. What is left in `keys` afterwards is named by no row.
+ * A collection that could not be read is returned, and its rows count for
+ * nothing: a caller must not treat what is left as unused when any is.
+ */
+export declare function removeReferencedKeys(keys: Set<string>, collections: readonly CollectionConfig[], driverFor: (collection: CollectionConfig) => DataDriver | undefined, options?: {
+    pageSize?: number;
+}): Promise<{
+    scanned: string[];
+    unscanned: UnscannedCollection[];
+}>;
+/** What `findOrphans` found. */
+export interface OrphanReport {
+    /** Objects in the source, internal ones aside. */
+    objects: number;
+    /** Objects no row names and older than the grace period. */
+    orphans: StoredObjectEntry[];
+    /**
+     * Objects no row names but too new to call unused — an upload whose row
+     * has not been saved yet looks exactly like this — or of unknown age.
+     */
+    recent: number;
+    scanned: string[];
+    unscanned: UnscannedCollection[];
+}
+/**
+ * The objects of one source that no row names.
+ *
+ * @param olderThanMs an object written less long ago than this is not called
+ *        an orphan: the admin panel uploads a file before the row that names it
+ *        is saved. One whose age the listing does not say is not either.
+ */
+export declare function findOrphans(options: {
+    controller: StorageController;
+    collections: readonly CollectionConfig[];
+    driverFor: (collection: CollectionConfig) => DataDriver | undefined;
+    olderThanMs: number;
+    now?: number;
+}): Promise<OrphanReport>;
+/** What happened to one object in a move. */
+export interface MovedObject {
+    key: string;
+    outcome: "copied" | "exists" | "failed";
+    /** Whether the source's copy was deleted afterwards. */
+    deleted?: boolean;
+    error?: string;
+}
+/**
+ * Copy the objects under a folder of one source into another, under the same
+ * keys, `limit` objects per call. Hand the returned `cursor` back for the next
+ * ones; none means the folder is done.
+ *
+ * A key the target already holds at the same size is left alone, so a move
+ * that stopped half-way is resumed by running it again. With `deleteSource`,
+ * the source's copy is deleted once the target holds one of the same size.
+ * The copy is the server's own write: the target's upload limits, which say
+ * what a user may upload, do not apply to a file already accepted once.
+ */
+export declare function moveObjects(options: {
+    from: StorageController;
+    to: StorageController;
+    prefix?: string;
+    cursor?: string;
+    limit?: number;
+    deleteSource?: boolean;
+}): Promise<{
+    moved: MovedObject[];
+    cursor?: 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

@@ -28,8 +28,15 @@ export interface DurableRendition {
     contentType: string;
 }
 export interface DurableRenditionCache {
-    /** The stored rendition for this cache key, or null. Never throws. */
-    get(controller: StorageController, cacheKey: string, bucket: string | undefined): Promise<DurableRendition | null>;
+    /**
+     * The stored rendition for this cache key, or null. Never throws.
+     *
+     * `contentType` is the type the transform produces
+     * (`transformContentType(options)`). The cache key carries the options,
+     * format included, so a key only ever holds a rendition of that type, and
+     * one read of that one object key answers the question.
+     */
+    get(controller: StorageController, cacheKey: string, bucket: string | undefined, contentType: string): Promise<DurableRendition | null>;
     /** Store a rendition. Never throws: a failed write is a slower cache. */
     put(controller: StorageController, cacheKey: string, bucket: string | undefined, rendition: DurableRendition): Promise<void>;
 }
@@ -43,13 +50,4 @@ export interface DurableRenditionCache {
  * is available to anyone auditing the prefix and to nothing on the hot path.
  */
 export declare function renditionKey(cacheKey: string, contentType: string): string;
-/**
- * A rendition's key when reading, where the content type is not yet known.
- *
- * Reads try the known extensions rather than storing an index: four `getObject`
- * calls at worst is still one round trip in the common case — the first
- * candidate is the format the request asked for — and an index is a second
- * thing to keep consistent with the objects it describes.
- */
-export declare function renditionKeyCandidates(cacheKey: string, preferred?: string): string[];
 export declare function createDurableRenditionCache(): DurableRenditionCache;

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

@@ -10,6 +10,7 @@
  * 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
@@ -22,6 +23,20 @@ import type { StorageController } from "./types.js";
  * 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.
  *

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

@@ -0,0 +1,30 @@
+/**
+ * The two principals a storage read can be granted without a user: the reader
+ * of a declared-public object, and the bearer of a download token.
+ *
+ * `checkAuthorized` does not ask the `storageAuthorize` hook about either — the
+ * public prefix and the token are the authorization. That skip used to be
+ * decided on the principal's `uid` string (`"public"`, `"download-token"`), so
+ * any identity carrying that uid skipped the hook: a custom `AuthAdapter` whose
+ * `verifyRequest` returns `{ uid: "public" }` for a guest could then upload,
+ * delete and list anywhere, with the hook never asked.
+ *
+ * Each principal is now one object, set only by the middleware that granted
+ * it (`publicObjectAuth`, `fileTokenAuth`) and recognised by identity. An
+ * adapter builds a new object per request, so it can name the uid but never be
+ * the grant.
+ */
+/** The principal `publicObjectAuth` grants an anonymous read of a public object. */
+export declare const PUBLIC_OBJECT_PRINCIPAL: {
+    readonly uid: string;
+    readonly roles: string[];
+};
+/** The principal `fileTokenAuth` grants a read covered by a valid download token. */
+export declare const DOWNLOAD_TOKEN_PRINCIPAL: {
+    readonly uid: string;
+    readonly roles: string[];
+};
+/** Whether `user` is the grant `publicObjectAuth` made — the object, not the uid. */
+export declare function isPublicObjectGrant(user: unknown): boolean;
+/** Whether `user` is the grant `fileTokenAuth` made — the object, not the uid. */
+export declare function isDownloadTokenGrant(user: unknown): boolean;

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;