@dudousxd/nestjs-media-dashboard 0.16.2 → 0.18.0

package/dist/server/index.d.cts

@@ -1,86 +1,132 @@
-import { DynamicModule, InjectionToken, OptionalFactoryDependency, Type, CanActivate, Provider, ModuleMetadata } from '@nestjs/common';
+import { HttpException, ExecutionContext, Type, ExceptionFilter, ArgumentsHost, CanActivate, Logger, DynamicModule, InjectionToken, OptionalFactoryDependency, Provider, ModuleMetadata, StreamableFile } from '@nestjs/common';
+import { HttpAdapterHost, ModuleRef } from '@nestjs/core';
 import { Readable } from 'node:stream';
-import { StorageManager, MediaStore, UploadSessionStore, ReadRangeOptions } from '@dudousxd/nestjs-media-core';
+import { MediaStore, UploadSessionStore, MultipartDrivers } from '@dudousxd/nestjs-media-core';
+import { Storage, ServeFileOptions } from '@nestjs/storage';
 
-/** The session user a host `login`/`session` hook returns to mint a cookie. */
-interface ConsoleSessionUser {
-    id: string;
-    name?: string;
-    roles?: string[];
+type ConsoleAuthorizeResult = boolean | {
+    allowed: true;
+} | {
+    allowed: false;
+    reason?: 'unauthenticated' | 'forbidden';
+} | {
+    redirectTo: string;
+};
+/** Class form: an `@Injectable()` provider (constructor injection works). */
+interface ConsoleAuthorizer {
+    authorize(context: ExecutionContext): ConsoleAuthorizeResult | Promise<ConsoleAuthorizeResult>;
+}
+type ConsoleAuthorizerClass = Type<ConsoleAuthorizer>;
+/** `@nestjs/authorization` policy check: `policy[ability](user)`. */
+interface ConsolePolicyCheck {
+    policy: Type<unknown>;
+    ability: string;
+}
+type ConsoleAuthorize = ((context: ExecutionContext) => ConsoleAuthorizeResult | Promise<ConsoleAuthorizeResult>) | ConsoleAuthorizerClass | (() => Promise<{
+    default: ConsoleAuthorizerClass;
+}>) | ConsolePolicyCheck | string;
+type ConsoleDecision = {
+    allowed: true;
+} | {
+    allowed: false;
+    reason: 'unauthenticated' | 'forbidden';
+    redirectTo?: string;
+};
+/** The provider `@dudousxd/nestjs-authz`'s `AuthzModule` registers to resolve gate names. */
+declare const CONSOLE_GATE: symbol;
+/** What `@dudousxd/nestjs-authz` provides under {@link CONSOLE_GATE}. */
+interface ConsoleGate {
+    allows(name: string, context: ExecutionContext): Promise<ConsoleAuthorizeResult>;
+}
+/** What a resolved `authorize` is: called once per request, never throws. */
+type ConsoleDecide = (context: ExecutionContext) => Promise<ConsoleDecision>;
+/** The one boot warning for a console with no `authorize`. Same wording in every Aviary console. */
+declare const CONSOLE_AUTHORIZE_MISSING_WARNING: string;
+/** Turns any {@link ConsoleAuthorizeResult} into a {@link ConsoleDecision}. */
+declare function normalizeConsoleResult(result: unknown): ConsoleDecision;
+/**
+ * Resolves `authorize` into one function the guard calls per request. Configuration mistakes (a gate
+ * name without nestjs-authz, a policy without @nestjs/authorization and its module) throw here, so
+ * call it at boot. The returned function never throws: an error is a `forbidden`.
+ *
+ * `authorize` omitted: open outside production, `forbidden` for every request in production, and one
+ * warning logged (unless `warnIfMissing: false`).
+ */
+declare function resolveConsoleAuthorize(authorize: ConsoleAuthorize | undefined, moduleRef: ModuleRef, options?: {
+    logger?: Logger;
+    warnIfMissing?: boolean;
+    registration?: string;
+}): Promise<ConsoleDecide>;
+/**
+ * Allows a request carrying `Authorization: Bearer <token>` (compared timing-safe); anything else
+ * is `unauthenticated`. Header only: no query string, no custom header. Throws when `token` is
+ * empty, so a missing env var fails at config time instead of opening the console.
+ */
+declare function authorizeByToken(options: {
+    token: string | undefined;
+}): ConsoleAuthorize;
+/** DI token of the resolved {@link ConsoleDecide} the guard runs. */
+declare const CONSOLE_AUTHORIZE_DECIDE: symbol;
+/** Marks a controller as serving pages: a denied `GET` that accepts HTML gets a page, not JSON. */
+declare const CONSOLE_PAGE_METADATA = "@dudousxd/nestjs-media-dashboard:console-page";
+declare const ConsolePage: () => ClassDecorator;
+/**
+ * The denial the guard throws. An `HttpException` with the JSON body, so it still answers correctly
+ * where {@link ConsoleAuthorizeFilter} is not applied; the filter adds the page answers.
+ */
+declare class ConsoleAccessDenied extends HttpException {
+    readonly decision: Extract<ConsoleDecision, {
+        allowed: false;
+    }>;
+    /** Whether the denied request was a page navigation (answered with a redirect or a page). */
+    readonly page: boolean;
+    constructor(decision: Extract<ConsoleDecision, {
+        allowed: false;
+    }>, 
+    /** Whether the denied request was a page navigation (answered with a redirect or a page). */
+    page?: boolean);
 }
-
-/** Host hook for Mode A — validates the host's own auth on the raw request. */
-type SessionHook = (request: unknown) => Promise<ConsoleSessionUser | null> | ConsoleSessionUser | null;
-/** Host hook for Mode B — validates submitted credentials from the built-in login screen. */
-type LoginHook = (username: string, password: string) => Promise<ConsoleSessionUser | null> | ConsoleSessionUser | null;
 /**
- * Re-checks a LIVE session when the cookie is slid forward. Runs at most once per `ttl/2` per
- * session, so a DB round-trip here is cheap. Return `false` to revoke (the cookie is cleared and
- * the request denied). Distinct from `session`: that hook reads the host's auth off a fresh
- * request, which a console XHR does not carry — this one receives the already-minted session.
+ * Runs the console's `authorize` on every request to a console controller. The dashboard applies it
+ * (after your `decorators`, so your authentication guards set `request.user` first); on controllers
+ * you mount yourself (`routes: false`) apply {@link UseConsoleAuthorize}.
  */
-type RevalidateHook = (session: ConsoleSessionUser) => Promise<boolean> | boolean;
-/** What `unauthenticatedPage` receives. An object (not positional args) so fields can be added later. */
-interface UnauthenticatedPageContext {
-    /**
-     * The platform-native request — Express' `Request`, Fastify's `FastifyRequest`. Typed `unknown`
-     * for the same reason `SessionHook`'s is: this package refuses to depend on either platform.
-     */
-    request: unknown;
-    /**
-     * The platform-native response. The hook OWNS it: it must write AND end it. If it returns without
-     * writing, the console falls back to serving its own SPA (whose auth screen then renders).
-     */
-    response: unknown;
-    /** Where this console is mounted (e.g. `/media`) — useful for a "back to the console" link. */
-    basePath: string;
+declare class ConsoleAuthorizeGuard implements CanActivate {
+    private readonly decide;
+    constructor(decide: ConsoleDecide);
+    canActivate(context: ExecutionContext): Promise<boolean>;
 }
 /**
- * Host-owned page for an unauthenticated navigation to the console SPA.
- *
- * Without it, an unauthenticated visitor gets the SPA shell, which then renders the built-in auth
- * screen: a generic "open this console from your application" card, generic because the library
- * cannot know who hosts it. This hook replaces that with the host's own page — and, because it is
- * decided BEFORE the shell is served, it also stops the bundle from loading for a visitor who has
- * no session at all.
- *
- * Only consulted under Mode-A-only. With `login` configured the SPA's own login form IS the way in,
- * so gating the shell would lock Mode B hosts out of their own console.
- *
- * Fail-closed by construction: it only ever runs when the request has no valid session. A hook that
- * throws, or returns without writing, falls back to serving the SPA — it cannot let anyone in,
- * because every data route stays behind `MediaConsoleGuard` regardless.
+ * Answers a console denial: JSON for API calls; for a page navigation a 302 to `redirectTo`, an
+ * "Access denied" page (403) or a "Sign in required" page (401).
  */
-type UnauthenticatedPageHook = (context: UnauthenticatedPageContext) => void | Promise<void>;
-/** Author-facing `auth` option on `MediaDashboardModule.forRoot`. Mirrors telescope's dashboardAuth. */
-interface ConsoleAuthOptions {
-    /** REQUIRED HMAC-SHA256 signing key. Missing/empty => boot error (fail closed). */
-    secret: string;
-    /** Cookie TTL as a duration string (`'8h'`, `'30m'`, `'7d'`). Default `'8h'`. */
-    ttl?: string;
-    /** Mode A: validate the host's own auth on the raw request. */
-    session?: SessionHook;
-    /** Mode B: validate credentials from the built-in login screen. */
-    login?: LoginHook;
-    /** Re-checks the session on sliding renewal. Not a mode — it cannot mint a session on its own. */
-    revalidate?: RevalidateHook;
-    /** Renders the host's own page for an unauthenticated navigation, in place of serving the SPA and
-     *  letting its built-in auth screen render; see `UnauthenticatedPageHook`. Mode-A-only. */
-    unauthenticatedPage?: UnauthenticatedPageHook;
+declare class ConsoleAuthorizeFilter implements ExceptionFilter {
+    private readonly adapterHost;
+    constructor(adapterHost: HttpAdapterHost);
+    catch(exception: ConsoleAccessDenied, host: ArgumentsHost): void;
 }
+/**
+ * The guard and its filter as one class decorator, for a console you mount yourself
+ * (`routes: false`). List it ABOVE your authentication guards, so it runs after them.
+ */
+declare const UseConsoleAuthorize: () => ClassDecorator & MethodDecorator;
 
+/**
+ * What a disk can do, computed by the server from the `@nestjs/storage` disk and its multipart
+ * side-car (`MediaDiskCapabilities` in `-core`).
+ */
 interface DiskCapabilities {
+    /** `signedUrl()` works (S3, or a local disk with `signedUrls`). */
     presign: boolean;
+    /** A multipart side-car is configured for the disk. */
     multipart: boolean;
+    /** The disk has a `publicUrl`. */
     publicUrls: boolean;
     list: boolean;
     /**
-     * Can the disk serve a byte range without transferring the whole object (a ranged `object/raw`)?
-     *
-     * Optional HERE, unlike the required `ranged` on the driver's own `DriverCapabilities`, because
-     * this is a WIRE shape: the console bundle can be served by a host still running an older server
-     * build that never emits the field. `undefined` means "this server didn't say", which a caller
-     * should treat as "don't count on it" — not as `false`.
+     * Can the disk serve a byte range (a ranged `object/raw`)? Every `@nestjs/storage` disk can, so
+     * current servers always send `true`. Optional because this is a WIRE shape: an older server may
+     * not emit it, and `undefined` means "don't count on it", not `false`.
      */
     ranged?: boolean;
 }
@@ -287,12 +333,12 @@ interface MediaDashboardOptions {
     /**
      * Where the JSON API is mounted (what the SPA fetches). Default `<basePath>/api`. Set it under
      * your app's `/api` prefix — e.g. `/api/media/console` — so the API inherits the app's
-     * auth/proxy rules while the UI stays at `basePath`.
+     * proxy rules while the UI stays at `basePath`.
      */
     apiBasePath?: string;
     /**
      * Enable the destructive endpoints (delete object/record, copy/move, abort upload). Default
-     * `false` — the read API is always available. Front the mount with your own guard either way.
+     * `false` — the read API is always available.
      */
     actions?: boolean;
     /**
@@ -306,56 +352,87 @@ interface MediaDashboardOptions {
      */
     objectUrls?: ObjectUrlStrategy;
     /**
-     * Gate the console (SPA + API) behind a built-in session-cookie login, telescope-style. Omit to
-     * leave the console open (front it with your own guard). When set, the SPA renders a login screen
-     * until a valid cookie exists; supply a `login(username, password)` and/or `session(request)`
-     * hook that returns a session user (or `null` to deny), and optionally a `revalidate(session)`
-     * hook that re-checks the user when the cookie is slid forward — see {@link ConsoleAuthOptions}.
+     * Extra `imports` merged into the dashboard's dynamic module — the DI resolution path for the
+     * dependencies of a guard passed through {@link decorators} (e.g. `UseGuards(AuthenticationGuard)`),
+     * or any other provider the controllers need reachable.
+     */
+    imports?: DynamicModule['imports'];
+    /**
+     * Host-supplied context about a disk object, rendered in the console's preview — see
+     * {@link ObjectInsightProvider}. The console can only describe a file as storage sees it; this is
+     * how it learns what the file *means* to your app. Omit for no annotation (the default).
+     *
+     * Use `forRootAsync`'s `useObjectInsights` when a provider needs injected services.
      */
-    auth?: ConsoleAuthOptions;
+    objectInsights?: ObjectInsightProvider[];
     /**
-     * Guard classes (or already-instantiated `CanActivate`s) fronting BOTH the page/asset controller
-     * (`MediaDashboardUiController` — a plain REPLACE, since it ships with no guard of its own) and
-     * the read/action JSON API controllers (APPENDED to their own built-in `MediaConsoleGuard`
-     * session-cookie gate — a request must pass BOTH). Deliberately NOT applied to the auth
-     * controller that MINTS that session cookie — see `MediaConsoleApiModule`'s own `guards` doc.
+     * Who may use the console: decided on EVERY console request (the page, its assets and the JSON
+     * API) by a guard that runs after your `decorators`, so your authentication guards set
+     * `request.user` first. Five forms:
      *
-     * These two surfaces (page vs. API) live in the same package here, unlike a split dashboard —
-     * but they're still SEPARATE controllers on separate host modules, so `guards` is stamped onto
-     * each independently by this one option.
+     * ```ts
+     * authorize: (ctx) => ctx.switchToHttp().getRequest().user?.isAdmin === true,
+     * authorize: ConsoleAccess,                              // @Injectable() implements ConsoleAuthorizer
+     * authorize: () => import('./console-access.js'),        // lazy, default export
+     * authorize: { policy: ConsolePolicy, ability: 'view' }, // @nestjs/authorization policy
+     * authorize: 'console.media',                            // a gate from @dudousxd/nestjs-authz
+     * ```
      *
-     * Full-page navigations to `basePath` carry only cookies, never an `Authorization` header — a
-     * guard passed here must be able to authenticate from a cookie (see the "Securing the console"
-     * guide) or it will 401 every browser visit to the console, even an already-logged-in admin's.
+     * Answer `true`/`{ allowed: true }` to allow, `false`/`{ allowed: false }` for 403,
+     * `{ allowed: false, reason: 'unauthenticated' }` for 401, or `{ redirectTo: '/login' }` to send a
+     * page navigation there (API calls get 401 with `redirectTo`). A throw is a 403.
      *
-     * `guards` and `auth` (the built-in cookie login) are independent and compose: with both set, a
-     * request must pass the host guard AND (when a route carries `MediaConsoleGuard`) present a valid
-     * built-in session cookie too. Configure one, the other, or both.
+     * Omitted: open outside production; in production every request answers 403, and one warning is
+     * logged at boot.
      *
-     * A guard's own DEPENDENCIES resolve from this option's `imports` (see {@link imports}) — the
-     * dashboard module has no application context of its own to pull them from otherwise.
+     * This is the console's access. It is not `MediaModule`'s `authorize(user, action, subject)` hook,
+     * which governs the product upload routes.
      */
-    guards?: Array<Type<CanActivate> | CanActivate>;
+    authorize?: ConsoleAuthorize;
     /**
-     * Extra `imports` merged into the dashboard's dynamic module — the DI resolution path for a class
-     * passed to {@link guards} (or any other provider the controllers need reachable). Typically the
-     * host's own auth module, e.g. `imports: [AuthModule]` alongside `guards: [SessionGuard]`.
+     * Class decorators applied to EVERY controller the console mounts — the page/asset controller
+     * and the read and action APIs — e.g.
+     * `[UseGuards(AuthenticationGuard), Can(MediaPolicy, 'console')]` with the first-party
+     * `@nestjs/authentication` / `@nestjs/authorization`. Default: none.
+     *
+     * Every console controller is marked `@Can.Anyone()`-open (`'authorization:can-anyone'`) so
+     * `@nestjs/authorization`'s deny-by-default global guard doesn't refuse the console; a `Can(...)`
+     * passed here is still checked (the guard treats `can-anyone` as open only when no requirement is
+     * declared).
+     *
+     * `decorators` don't decide access on their own: use them for authentication, throttling and the
+     * like, and {@link authorize} for who may use the console.
+     *
+     * Full-page navigations to `basePath` carry only cookies, never an `Authorization` header — a
+     * guard here must be able to authenticate the page from a cookie, or every browser visit 401s.
+     *
+     * Each registration decorates fresh subclasses of the controllers, so one registration's
+     * decorators never reach another.
      */
-    imports?: DynamicModule['imports'];
+    decorators?: ClassDecorator[];
     /**
-     * Host-supplied context about a disk object, rendered in the console's preview — see
-     * {@link ObjectInsightProvider}. The console can only describe a file as storage sees it; this is
-     * how it learns what the file *means* to your app. Omit for no annotation (the default).
+     * `false` mounts NO controller — no page, no JSON API — while every provider still works and is
+     * exported (`MediaConsoleService`, the resolved paths), so you serve
+     * the console from controllers of your own by extending the exported controller classes. Apply
+     * `UseConsoleAuthorize()` to them, ABOVE your authentication guard (class decorators apply
+     * bottom-up, so authentication runs first), so {@link authorize} still decides access. Keep
+     * `basePath`/`apiBasePath` equal to where you mount them: the SPA reads both.
      *
-     * Use `forRootAsync`'s `useObjectInsights` when a provider needs injected services.
+     * ```ts
+     * @UseConsoleAuthorize()
+     * @UseGuards(AuthGuard)
+     * @Controller('media/api')
+     * export class ConsoleApiController extends MediaConsoleReadController {}
+     * ```
+     *
+     * Default `true`.
      */
-    objectInsights?: ObjectInsightProvider[];
+    routes?: boolean;
 }
 /**
- * Async variant of {@link MediaDashboardOptions}. The mount paths + `actions` stay static (the
- * router needs them at module-definition time), but `auth` is built by an injected factory — so
- * the `login`/`session` hooks can reach your DB/services (e.g. an EntityManager to validate an
- * admin). Returning `undefined` from the factory leaves the console open.
+ * Async variant of {@link MediaDashboardOptions}. The mount paths, `actions` and `decorators` stay
+ * static (the router needs them at module-definition time); the `objectInsights` providers are
+ * built by an injected factory, so they can reach your repositories and services.
  */
 interface MediaDashboardAsyncOptions {
     basePath?: string;
@@ -364,110 +441,83 @@ interface MediaDashboardAsyncOptions {
     /** See {@link MediaDashboardOptions.objectUrls}. Static like the mount paths and `actions` —
      *  it is read at module-definition time, not per request. */
     objectUrls?: ObjectUrlStrategy;
-    /** Modules exporting the providers `inject` needs, or a guard class's own dependencies (omit
-     *  when they're global). Shared with {@link guards}. */
+    /** Modules exporting the providers `inject` needs, or a decorator guard's own dependencies (omit
+     *  when they're global). */
     imports?: DynamicModule['imports'];
-    /** Providers injected into `useAuth`, in order. */
+    /** Providers injected into `useObjectInsights`, in order. */
     inject?: Array<InjectionToken | OptionalFactoryDependency>;
-    /** Build the `auth` config from injected deps (or `undefined` to leave the console open). */
-    useAuth: (...deps: any[]) => ConsoleAuthOptions | undefined | Promise<ConsoleAuthOptions | undefined>;
-    /**
-     * Guard classes (or instances) fronting the console — see {@link MediaDashboardOptions.guards}.
-     * Passed here directly (not resolved via `useAuth`'s factory) because guard stamping happens at
-     * module-build time, synchronously — the SAME constraint as `basePath`/`apiBasePath` above. A
-     * class guard's own dependencies resolve from `imports` above (shared with `useAuth`'s `inject`).
-     */
-    guards?: Array<Type<CanActivate> | CanActivate>;
     /**
      * Build the {@link MediaDashboardOptions.objectInsights} providers from injected deps — the usual
      * case, since a provider that says anything interesting needs a repository or a service.
      */
     useObjectInsights?: (...deps: any[]) => ObjectInsightProvider[] | Promise<ObjectInsightProvider[]>;
     /**
-     * Providers injected into `useObjectInsights`, in order. Defaults to {@link inject} — its own
-     * list because the insight providers rarely want the same dependencies the auth hooks do, and
-     * sharing one list would force every host to inject the union of both.
+     * See {@link MediaDashboardOptions.decorators}. Static (not built by a factory): the decorators
+     * shape the routes when the module is built.
      */
-    injectObjectInsights?: Array<InjectionToken | OptionalFactoryDependency>;
+    decorators?: ClassDecorator[];
+    /** See {@link MediaDashboardOptions.authorize}. Static, like `decorators`. */
+    authorize?: ConsoleAuthorize;
+    /** See {@link MediaDashboardOptions.routes}. Static, like `decorators`. */
+    routes?: boolean;
 }
 /**
  * Mounts the /media console: the bundled React SPA at `basePath` and its JSON API at `apiBasePath`
  * (default `<basePath>/api`). Import via `MediaDashboardModule.forRoot(...)` (or `forRootAsync` when
- * the `auth` hooks need injected services) alongside `MediaModule` (global), so it resolves the
- * storage/store/upload tokens. Exclude the UI/API paths from any global `/api` prefix.
+ * the `objectInsights` providers need injected services) alongside `MediaModule` (global), so it
+ * resolves the storage/store/upload tokens. Exclude the UI/API paths from any global `/api` prefix.
  *
- * Front it with your own auth via `guards` (+ `imports` for their dependencies) — see
- * {@link MediaDashboardOptions.guards} — instead of, or alongside, the built-in `auth` cookie login.
+ * Decide who may use it with {@link MediaDashboardOptions.authorize}; without it the console is open
+ * outside production and answers 403 to everything in production.
  */
 declare class MediaDashboardModule {
     static forRoot(options?: MediaDashboardOptions): DynamicModule;
-    static forRootAsync(options: MediaDashboardAsyncOptions): DynamicModule;
-    /** Shared wiring: static routing + the API module, with `auth` supplied by the given provider. */
+    static forRootAsync(options?: MediaDashboardAsyncOptions): DynamicModule;
+    /** Shared wiring: static routing + the API module, with the insights from the given provider. */
     private static build;
 }
 
-interface ApiModuleOptions {
+interface MediaConsoleApiModuleOptions {
     actions: boolean;
-    /** Cookie `Path` — the JSON API base — so the session cookie rides every console API request. */
-    cookiePath: string;
-    /** Provider for `MEDIA_CONSOLE_AUTH` — a `useValue` (forRoot) or a `useFactory` (forRootAsync). */
-    authProvider: Provider;
     /** Provider for `MEDIA_CONSOLE_OBJECT_INSIGHTS` — the host's object-annotation providers.
      *  Omitted binds the empty list, which is the no-op the console renders nothing for. */
     insightsProvider?: Provider;
     /** Resolved object-URL strategy + the API mount it builds proxy URLs against. */
     objectUrls: ObjectUrlConfig;
-    /** Extra imports the auth factory's `inject` deps (or a guard class's own deps) live in. */
+    /** Extra imports the insights factory's `inject` deps (or a decorator's guards' deps) live in. */
     imports?: ModuleMetadata['imports'];
     /**
-     * Guard classes (or instances) fronting the read + action controllers — APPENDED to their own
-     * built-in `MediaConsoleGuard` (session-cookie) gate, so a request must pass BOTH. Deliberately
-     * NOT applied to `MediaConsoleAuthController`: it MINTS the session cookie the built-in gate (and
-     * any host guard reusing that same cookie) checks for, so it can't be made to require the very
-     * auth it grants — mirrors `@dudousxd/nestjs-telescope`'s own auth controller staying outside its
-     * `stampGuards` call.
+     * Who may use the console API — see `MediaDashboardOptions.authorize`. Omitted: open outside
+     * production, every request answers 403 in production, and one warning is logged at boot.
+     */
+    authorize?: ConsoleAuthorize;
+    /** The registration named in the boot warning when `authorize` is omitted. Default
+     *  `'MediaConsoleApiModule.register()'`. */
+    moduleName?: string;
+    /**
+     * Class decorators applied to EVERY controller this module mounts (read, actions) — see
+     * `MediaDashboardOptions.decorators`. Each call decorates fresh subclasses, never the shared
+     * classes, so decorators never leak from one registration into the next.
      */
-    guards?: Array<Type<CanActivate> | CanActivate>;
+    decorators?: ClassDecorator[];
+    /**
+     * `false` registers no controller, only the providers (exported), for a host that mounts the
+     * controllers itself — see `MediaDashboardOptions.routes`. Default `true`.
+     */
+    routes?: boolean;
 }
 /**
- * Holds the console's JSON API: the read controller (always), the actions controller (only when
- * `actions: true`), and the auth controller (always — it mints the session the guard checks, so it
- * is never itself guarded). The read/action controllers carry `MediaConsoleGuard`, a no-op unless
- * the host configured `auth`, plus any host `guards` (see {@link ApiModuleOptions.guards}) — both
- * gates must pass.
+ * Holds the console's JSON API: the read controller (always) and the actions controller (only when
+ * `actions: true`). Who reaches them is decided by `authorize` (`ConsoleAuthorizeGuard`).
  */
 declare class MediaConsoleApiModule {
-    static register(options: ApiModuleOptions): DynamicModule;
+    static register(options: MediaConsoleApiModuleOptions): DynamicModule;
 }
 
 /**
- * A range as the CLIENT asked for it, before the object's size is known.
- *
- * Either an absolute {@link ReadRangeOptions}, or HTTP's suffix form (`Range: bytes=-500`, "the last
- * 500 bytes") — which cannot be made absolute without the size, and the size is `stat`'s to give.
- * Resolving it here rather than in the controller saves a second `stat` on the request path.
- */
-type RequestedReadRange = ReadRangeOptions | {
-    suffixLength: number;
-};
-/** What {@link MediaConsoleService.objectStream} hands the controller. `range` is present only when
- *  a range was requested AND satisfied, already absolute and clamped to the object — so the
- *  controller can write `Content-Range`/`Content-Length` without re-deriving anything. */
-interface ObjectStreamResult {
-    stream: Readable;
-    contentType: string;
-    /** Total size of the OBJECT, not of the slice — the `/<size>` in `Content-Range`. */
-    size: number;
-    /** Absolute inclusive bounds actually being streamed. Absent on a full-body read. */
-    range?: {
-        start: number;
-        end: number;
-    };
-}
-/**
- * Read + action logic behind the console's JSON API. Resolves the three by-value media tokens
- * with `@Optional()` so a host without a `MediaStore`/upload store still boots — every method
- * degrades to an empty shape instead of throwing when its capability is absent.
+ * Read + action logic behind the console's JSON API, on the disks of `@nestjs/storage` (`Storage`).
+ * Resolves the store, upload store and multipart side-cars with `@Optional()` so a host without
+ * them still boots — every method degrades to an empty shape instead of throwing.
  */
 declare class MediaConsoleService {
     private readonly storage;
@@ -476,16 +526,25 @@ declare class MediaConsoleService {
     private readonly actionsEnabled;
     private readonly insightProviders;
     private readonly objectUrls;
-    constructor(storage: StorageManager | null, store: MediaStore | null, uploads: UploadSessionStore | null, actionsEnabled: boolean | null, insightProviders?: ObjectInsightProvider[] | null, objectUrls?: ObjectUrlConfig | null);
+    /** `MediaModuleOptions.multipart`: native folder listing and the multipart badge. */
+    private readonly multipart;
+    constructor(storage: Storage | null, store: MediaStore | null, uploads: UploadSessionStore | null, actionsEnabled: boolean | null, insightProviders?: ObjectInsightProvider[] | null, objectUrls?: ObjectUrlConfig | null, 
+    /** `MediaModuleOptions.multipart`: native folder listing and the multipart badge. */
+    multipart?: MultipartDrivers | null);
+    private readonly logger;
     /**
      * The URL to report for an object's bytes, under the host's {@link ObjectUrlStrategy}. `auto`
-     * prefers a presigned URL straight to the store; `proxy` routes through this server, for a host
-     * whose browser cannot reach the store at all.
+     * prefers the disk's public URL, then a signed one (S3 presigns; a local disk signs with
+     * `signedUrls`), and falls back to this server's own route for a disk that can do neither.
+     * `proxy` always routes through this server.
      */
     private objectUrl;
-    private readonly logger;
     private diskOrThrow;
-    listDisks(): DiskListResponse;
+    listDisks(): Promise<DiskListResponse>;
+    /**
+     * One folder level. `StorageDisk.list()` is flat; a disk whose multipart side-car lists with a
+     * delimiter (S3) asks the store for folders, any other disk folds its flat listing.
+     */
     listObjects(disk: string, options: {
         prefix?: string;
         cursor?: string;
@@ -493,76 +552,55 @@ declare class MediaConsoleService {
     }): Promise<ObjectListResponse>;
     objectDetail(disk: string, key: string): Promise<ObjectDetailResponse>;
     /**
-     * What the HOST knows about this object, from every registered provider.
-     *
-     * Its own call rather than a field on `objectDetail`, for the same reason the RAG index-status
-     * endpoint is separate from its document listing: `objectDetail` is on the path of every preview
-     * and every navigation, and providers reach into host databases. Folding them in would put a host
-     * query on reads that only wanted a presigned URL.
-     *
-     * Failures are contained per provider. A provider that throws is logged and dropped, and the
-     * others still render — annotation must never be able to stop an admin opening a file, and one
-     * host lookup being down says nothing about the rest.
-     *
-     * Providers run concurrently: they are independent host lookups, and running them in series would
-     * make the panel as slow as their sum for no gain.
+     * What the HOST knows about this object, from every registered provider. Its own call rather
+     * than a field on `objectDetail`, so host lookups stay off the preview path. A provider that
+     * throws is logged and dropped; providers run concurrently.
      */
     objectInsights(disk: string, key: string): Promise<ObjectInsightsResponse>;
     /**
-     * The object's raw byte stream plus the metadata the controller needs to serve it inline. Used by
-     * the console's same-origin preview proxy so text/PDF render in the browser instead of downloading
-     * (and so a CORS-locked bucket is still previewable).
-     *
-     * With `range`, only that slice — which is what makes previewing a multi-hundred-MB object (a
-     * SQLite database read a page at a time) possible at all. The range is resolved HERE, not in the
-     * driver, because it has to be checked against the object's size and the `stat` for that is
-     * already on this path: the suffix form is made absolute, an overrunning `end` is clamped to the
-     * last byte, and anything genuinely unsatisfiable becomes a {@link RangeNotSatisfiableException}
-     * (HTTP 416) instead of a surprise empty body.
-     *
-     * A driver that reports `ranged: false` REFUSES a range request rather than quietly returning the
-     * whole object: the caller asked for 64 KB out of 400 MB, and silently answering with all 400 MB
-     * — which the caller would then read as if it were the slice — is the exact failure the `ranged`
-     * capability exists to make impossible.
+     * Streams an object as the response through `@nestjs/storage`'s `serveFile()`: a single `Range`
+     * gets a 206 with `Content-Range` (how a SQLite/ZIP/Parquet preview reads a few KB out of a huge
+     * object), `If-None-Match` a 304, a range past the end a 416, a missing file a 404. `inline`
+     * applies only to types that can't run script in this origin; others download.
+     */
+    serveObject(disk: string, key: string, options: ServeFileOptions): Promise<StreamableFile | undefined>;
+    /**
+     * Writes an object from a byte stream (a browser upload), streamed onto the disk: S3Disk turns a
+     * body of unknown length into a multipart upload itself, so nothing is buffered here. With the
+     * request's `Content-Length`, a body that ends short fails and nothing is written.
+     */
+    putObject(disk: string, key: string, body: Readable, contentType?: string, contentLength?: number): Promise<void>;
+    /**
+     * Creates a folder: a zero-byte `<prefix>/.keep` file (hidden from listings), since
+     * `@nestjs/storage` keys can't end with `/`. Listings show the folder because a key lives in it.
      */
-    objectStream(disk: string, key: string, range?: RequestedReadRange): Promise<ObjectStreamResult>;
-    /** Writes an object from a byte stream (a browser upload). The caller supplies the full key
-     *  (prefix + filename); an unknown disk 404s via {@link diskOrThrow}. Actions-gated.
-     *
-     *  The request stream is buffered before the write: S3's PutObject needs a known Content-Length,
-     *  which a raw request stream doesn't carry, so passing the stream straight through fails. Bounded
-     *  at {@link MAX_UPLOAD_BYTES} so a runaway upload can't exhaust the pod's heap — larger files
-     *  belong on the resumable upload path, not this console convenience upload. */
-    putObject(disk: string, key: string, body: Readable, contentType?: string): Promise<void>;
-    /** Creates a "folder" — a zero-byte marker object at `<prefix>/`, which S3-style listing surfaces
-     *  as a navigable folder. Normalizes to exactly one trailing slash; rejects an empty prefix. */
     createFolder(disk: string, prefix: string): Promise<void>;
     deleteObject(disk: string, key: string): Promise<void>;
-    /** Recursively deletes a "folder": every object under `<prefix>/` (nested included) plus the
-     *  zero-byte marker itself. Passes an empty delimiter so the driver lists keys FLAT — the default
-     *  `/` delimiter would group nested keys into CommonPrefixes and the sweep would miss them, only
-     *  deleting direct children. Paginates until the disk reports no more. The marker's own key equals
-     *  the sweep prefix, which `list` filters out (Key === Prefix), so it's deleted explicitly at the
-     *  end. Actions-gated. */
+    /**
+     * Recursively deletes a folder: every file under `<prefix>/`, nested included (its `.keep`
+     * too), a batch of keys per `delete()`. A legacy `prefix/` marker object written by another tool
+     * can't be addressed through `@nestjs/storage`; it is skipped.
+     */
     deleteFolder(disk: string, prefix: string): Promise<void>;
     copyObject(fromDisk: string, from: string, toDisk: string, to: string): Promise<void>;
     moveObject(fromDisk: string, from: string, toDisk: string, to: string): Promise<void>;
-    /** Copies or moves a single object, on the same disk or across disks. Same-disk uses the driver's
-     *  native `copy`/`move` (server-side, no bytes through the pod). Cross-disk has no driver primitive,
-     *  so the object is streamed through the pod (get→put, buffered), preserving its content type and
-     *  bounded at {@link MAX_CROSS_DISK_BYTES}; a `move` then deletes the source. */
+    /**
+     * Copies or moves one object. Same disk: the disk's own `copy`/`move` (server-side on S3, a
+     * rename on a local disk). Across disks: the source's body streams into the destination's
+     * `put()` (no size limit, nothing buffered), keeping its content type, cache control,
+     * disposition and metadata; a `move` then deletes the source.
+     */
     private transferKey;
-    /** Moves a whole "folder" (every object under `<from>/`, nested included) to `<to>/`, on the same
-     *  disk or across disks, preserving each key's path relative to the source. */
+    /** Moves a whole folder (every file under `<from>/`, nested included) to `<to>/`. */
     moveFolder(fromDisk: string, from: string, toDisk: string, to: string): Promise<void>;
-    /** Copies a whole "folder" (every object under `<from>/`, nested included) to `<to>/`, same disk or
-     *  across disks, preserving each key's path relative to the source. */
+    /** Copies a whole folder (every file under `<from>/`, nested included) to `<to>/`. */
     copyFolder(fromDisk: string, from: string, toDisk: string, to: string): Promise<void>;
-    /** Shared engine for {@link moveFolder}/{@link copyFolder}. Same flat-listing sweep as
-     *  {@link deleteFolder}; each key is relocated via {@link transferKey} (so cross-disk transfers work
-     *  transparently). On the SAME disk, rejects a destination inside the source (which would recurse
-     *  forever); across disks that constraint doesn't apply. The destination folder marker is written,
-     *  and for a move the source marker is removed, so both listings stay consistent. Actions-gated. */
+    /**
+     * Shared engine for {@link moveFolder}/{@link copyFolder}: a flat sweep of the source, each key
+     * relocated via {@link transferKey}, keeping its path relative to the folder (an empty folder's
+     * `.keep` goes along). On the SAME disk, a destination inside the source is refused (it would
+     * recurse forever).
+     */
     private transferFolder;
     listUploads(filter: {
         disk?: string;
@@ -589,11 +627,96 @@ declare class MediaConsoleService {
     topology(): Topology;
 }
 
+/**
+ * Serves the bundled /media console SPA at the configured base (+ hashed assets at `<base>/assets`).
+ * The path comes from `RouterModule` (set by `MediaDashboardModule.forRoot({ basePath })`), so the
+ * controller routes are relative.
+ */
+declare class MediaDashboardUiController {
+    private readonly basePath;
+    private readonly apiBasePath;
+    private readonly dir;
+    constructor(basePath: string, apiBasePath: string);
+    index(): string;
+    asset(file: string): StreamableFile;
+}
+
+/**
+ * Read-only JSON API for the /media console. Bare `@Controller()` — the path prefix is applied by
+ * `RouterModule` (set in `MediaDashboardModule.forRoot({ apiBasePath })`). Always mounted.
+ */
+declare class MediaConsoleReadController {
+    private readonly service;
+    constructor(service: MediaConsoleService);
+    disks(): Promise<DiskListResponse>;
+    objects(disk: string, prefix?: string, cursor?: string, limit?: string): Promise<ObjectListResponse>;
+    object(disk: string, key: string): Promise<ObjectDetailResponse>;
+    /** What the host knows about this object, from its registered `objectInsights` providers. Empty
+     *  when none are registered — the console renders nothing for an empty list. */
+    objectInsights(disk: string, key: string): Promise<ObjectInsightsResponse>;
+    /**
+     * Streams the object's bytes from the same origin (`serveFile()`), so the SPA can render previews
+     * past CORS: `inline` for types that can't run script here (images, PDF, audio, video, plain
+     * text), `attachment` for the rest — the text previews read the body with `fetch`, which doesn't
+     * care. A single `Range` gets a 206, which is how SQLite/ZIP/Parquet previews read a few KB out
+     * of a multi-hundred-MB object.
+     */
+    objectRaw(disk: string, key: string, req: unknown, res: unknown): Promise<StreamableFile | undefined>;
+    /**
+     * The same bytes as `/raw`, but as a SAVE: `Content-Disposition: attachment` with the object's
+     * own name. Same-origin and unconditional, so it works where the browser can't reach the store.
+     */
+    objectDownload(disk: string, key: string, req: unknown, res: unknown): Promise<StreamableFile | undefined>;
+    uploads(disk?: string, prefix?: string): Promise<UploadListResponse>;
+    upload(id: string): Promise<UploadDetailResponse>;
+    collections(): Promise<CollectionsResponse>;
+    library(collection?: string, disk?: string, cursor?: string, limit?: string): Promise<LibraryListResponse>;
+    libraryRecord(id: string): Promise<LibraryDetailResponse>;
+    topology(): Topology;
+}
+
+interface CopyMoveBody {
+    from: string;
+    to: string;
+    /** Destination disk for a cross-disk copy/move. Omitted → same disk as the source (`:disk`). */
+    toDisk?: string;
+}
+interface CreateFolderBody {
+    prefix: string;
+}
+/**
+ * Destructive JSON API for the /media console. Only registered when the host opts in with
+ * `MediaDashboardModule.forRoot({ actions: true })` (default off). Bare `@Controller()` — the path
+ * prefix comes from `RouterModule`, sharing the API base with the read controller.
+ */
+declare class MediaConsoleActionsController {
+    private readonly service;
+    constructor(service: MediaConsoleService);
+    deleteObject(disk: string, key: string): Promise<void>;
+    copyObject(disk: string, body: CopyMoveBody): Promise<void>;
+    moveObject(disk: string, body: CopyMoveBody): Promise<void>;
+    moveFolder(disk: string, body: CopyMoveBody): Promise<void>;
+    copyFolder(disk: string, body: CopyMoveBody): Promise<void>;
+    /**
+     * Uploads a file to `key` on the disk. The body is the raw bytes sent as `application/octet-stream`
+     * so the host's JSON/urlencoded body parsers never consume the stream; the real MIME rides as the
+     * `type` query param and becomes the stored object's Content-Type. `@Req()` is the request stream,
+     * streamed onto the disk (no size cap, nothing buffered).
+     */
+    uploadObject(disk: string, key: string, request: Readable & {
+        headers?: Record<string, string | string[] | undefined>;
+    }, type?: string): Promise<void>;
+    createFolder(disk: string, body: CreateFolderBody): Promise<void>;
+    deleteFolder(disk: string, prefix: string): Promise<void>;
+    abortUpload(id: string): Promise<void>;
+    deleteLibraryRecord(id: string): Promise<void>;
+}
+
 /** The configured `MediaStore` (or `null`), provided by `MediaModule`. */
 declare const MEDIA_STORE: symbol;
 /** The configured `UploadSessionStore` (or `null`), provided by `MediaModule`. */
 declare const MEDIA_UPLOAD_SESSIONS: symbol;
-/** The `StorageManager` (alias of `MediaModule`'s internal `MEDIA_STORAGE` token). */
-declare const MEDIA_STORAGE_SHARED: symbol;
+/** The multipart side-cars by disk name (`MediaModuleOptions.multipart`), provided by `MediaModule`. */
+declare const MEDIA_MULTIPART: symbol;
 
-export { type CollectionInfo, type CollectionsResponse, type ConsoleAuthOptions, type ConsoleSessionUser, type DiskCapabilities, type DiskInfo, type DiskListResponse, type LibraryDetailResponse, type LibraryListResponse, type LibraryRecord, type LibraryVariant, type LoginHook, MEDIA_STORAGE_SHARED, MEDIA_STORE, MEDIA_UPLOAD_SESSIONS, MediaConsoleApiModule, MediaConsoleService, type MediaDashboardAsyncOptions, MediaDashboardModule, type MediaDashboardOptions, type ObjectDetailResponse, type ObjectEntry, type ObjectFolder, type ObjectInsight, type ObjectInsightContext, type ObjectInsightFact, type ObjectInsightLink, type ObjectInsightProvider, type ObjectInsightsResponse, type ObjectListResponse, type ObjectUrlConfig, type ObjectUrlStrategy, type SessionHook, type Topology, type UploadDetailResponse, type UploadInfo, type UploadListResponse, type UploadPart };
+export { CONSOLE_AUTHORIZE_DECIDE, CONSOLE_AUTHORIZE_MISSING_WARNING, CONSOLE_GATE, CONSOLE_PAGE_METADATA, type CollectionInfo, type CollectionsResponse, ConsoleAccessDenied, type ConsoleAuthorize, ConsoleAuthorizeFilter, ConsoleAuthorizeGuard, type ConsoleAuthorizeResult, type ConsoleAuthorizer, type ConsoleAuthorizerClass, type ConsoleDecide, type ConsoleDecision, type ConsoleGate, ConsolePage, type ConsolePolicyCheck, type DiskCapabilities, type DiskInfo, type DiskListResponse, type LibraryDetailResponse, type LibraryListResponse, type LibraryRecord, type LibraryVariant, MEDIA_MULTIPART, MEDIA_STORE, MEDIA_UPLOAD_SESSIONS, MediaConsoleActionsController, MediaConsoleApiModule, type MediaConsoleApiModuleOptions, MediaConsoleReadController, MediaConsoleService, type MediaDashboardAsyncOptions, MediaDashboardModule, type MediaDashboardOptions, MediaDashboardUiController, type ObjectDetailResponse, type ObjectEntry, type ObjectFolder, type ObjectInsight, type ObjectInsightContext, type ObjectInsightFact, type ObjectInsightLink, type ObjectInsightProvider, type ObjectInsightsResponse, type ObjectListResponse, type ObjectUrlConfig, type ObjectUrlStrategy, type Topology, type UploadDetailResponse, type UploadInfo, type UploadListResponse, type UploadPart, UseConsoleAuthorize, authorizeByToken, normalizeConsoleResult, resolveConsoleAuthorize };