@useupup/server 3.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Devino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,322 @@
+# @useupup/server
+
+Server-mode endpoints for [upup](https://github.com/DevinoSolutions/upup): S3/MinIO
+presign + proxy upload, drive-token exchange (Google Drive / OneDrive /
+Dropbox / Box), and an HMAC-signed upload-token trust model so the client
+never asserts the object key or S3 `uploadId` it's writing to.
+
+`createUpupHandler(config)` returns a framework-agnostic `(req: Request) =>
+Promise<Response>`. Thin adapters wire it into Express, Fastify, Hono, and
+Next.js (`@useupup/server/express`, `/fastify`, `/hono`, `/next`).
+
+## Install
+
+```sh
+npm install @useupup/server
+```
+
+## Minimal config
+
+```ts
+import { createUpupHandler } from '@useupup/server'
+
+const handler = createUpupHandler({
+    storage: {
+        type: 'aws',
+        bucket: 'my-bucket',
+        region: 'us-east-1',
+        // accessKeyId/secretAccessKey — omit to use the environment's default
+        // AWS credential chain. Set `endpoint` (+ optionally `forcePathStyle`)
+        // for MinIO / R2 / DigitalOcean Spaces / any S3-compatible provider.
+    },
+    uploadTokenSecret: process.env.UPUP_UPLOAD_TOKEN_SECRET,
+})
+```
+
+By default, `POST /presign` and `POST /multipart/init` reject anonymous
+callers with `403 AUTH_REQUIRED` unless you configure `auth`, `getUserId`, or
+opt in explicitly:
+
+```ts
+createUpupHandler({ /* ... */, allowAnonymousUploads: true })
+```
+
+`allowAnonymousUploads` collapses every caller into one shared anonymous
+namespace — fine for demos and upstream-auth deployments (tus/companion-style,
+where authentication happens before the request reaches this handler), never
+for multi-tenant production.
+
+### `uploadTokenSecret` is REQUIRED — and must match across every instance
+
+`createUpupHandler` throws at construction time if `uploadTokenSecret` is
+missing or under 16 characters. This secret HMAC-signs the stateless upload
+token issued at multipart-init and re-verified on every sign-part / complete
+/ abort / resume call — it is what binds the client-supplied token to the
+server-chosen object key and S3 `uploadId` so a client can never assert
+either on the way back.
+
+**It must be byte-for-byte identical on every server instance / worker /
+lambda that can see the same upload.** A rolling redeploy that generates a
+fresh secret per instance (or a mismatched secret between regions/canaries)
+means requests routed to a different instance than the one that issued the
+token fail multipart uploads with `403 bad_signature` — indistinguishable
+from a real forgery unless you know to check this. Generate one secret and
+inject it as a shared config value (env var / secret manager), e.g.:
+
+```sh
+openssl rand -hex 32
+```
+
+See [`/health`](#health) below for a way to detect this drift across a fleet
+without comparing the secret value directly.
+
+#### Token semantics: TTL & replay
+
+An upload token is issued at `/multipart/init`, re-verified on every
+`/multipart/sign-part`, `/multipart/complete`, and `/multipart/abort` call, and
+re-issued by `/multipart/resume`. It carries no nonce — expiry is the only
+freshness check:
+
+- **TTL.** `exp` is set to `now + DEFAULT_UPLOAD_TOKEN_TTL_SECONDS` (3600s / 1
+  hour) at init. Once `exp` passes, sign-part / complete / abort reject it with
+  `403 {code: 'expired'}`.
+- **Refresh.** `/multipart/resume` is the one route that accepts an expired
+  token, because exchanging it for a fresh one is its purpose — an upload can
+  outlive an hour. The replacement re-signs the same `k`/`u`/`uid`/`smin`/`smax`
+  with a new `exp`, so nothing about what the token authorizes changes.
+- **Resume window.** The relaxed expiry is re-bounded by
+  `multipartResumeWindowSeconds` (default 86400 / 24h), measured from `iat` —
+  the ORIGINAL init, carried forward unchanged on every re-issue, so a chain of
+  resumes cannot extend it. Past the window, resume answers
+  `403 {code: 'expired'}`. Tokens minted before `iat` existed fall back to
+  `exp - TTL`. Set the knob to `0` to remove the route entirely; a negative or
+  fractional value throws `UpupConfigError` at construction.
+  **The trade:** a leaked token is usable for the window rather than an hour,
+  but only to continue the same upload, to the same key, inside the same signed
+  size envelope, still owner-bound whenever `getUserId` is set.
+- **Replay window.** Within that hour, the _same_ token may be sent to
+  sign-part/complete/abort **any number of times** — this is by design, not a
+  bug: a client legitimately re-signs a part after a network retry, or drives
+  a multi-part upload with many sequential sign-part calls, all against one
+  init-issued token. `handler-extended.test.ts`'s `F-107` suite pins this
+  accepted property at the HTTP boundary.
+- **What replay is bounded by.** A replayed token can only re-drive parts
+  within the S3 `uploadId` it was issued for, and only within the `smin`/`smax`
+  byte envelope signed at init (enforced at `/multipart/complete` — see
+  [Error codes](#error-codes)). When `getUserId` is configured, replay is
+  further bound to the uid that owned the token at init — a different
+  authenticated user replaying a leaked token gets `403 AUTH_DENIED` (see
+  `allowAnonymousUploads` below and the F-106 uid-binding tests).
+- **No single-use / nonce enforcement, by design.** This token model is
+  intentionally stateless — there is no consumed-nonce tracking, so a token is
+  valid for every call until `exp`, not just the first. If your deployment
+  needs single-use tokens, back the token verification with a nonce/jti store
+  in your `TokenStore` implementation (not provided out of the box).
+
+## Cross-reload resume — one thing you must configure
+
+`POST /multipart/resume` lets a client re-attach to an upload a page reload,
+tab close, or crash left in flight. It takes `{ token }` and nothing else, and
+answers `{ key, token, parts }` — the parts the provider already holds, each
+with its byte size, plus a freshly-signed token. The `uploadId` is never sent
+by the client and never returned.
+
+```ts
+createUpupHandler({
+    // ...storage, uploadTokenSecret
+    multipartResumeWindowSeconds: 86400, // default; 0 removes the route
+})
+```
+
+**Because upup's client keeps resume on by default, an interrupted multipart
+upload is no longer aborted server-side — its parts are kept so the next
+attempt can continue from them.** Parts nobody ever resumes are not cleaned up
+by this package, and S3 bills for them.
+
+Configure an `AbortIncompleteMultipartUpload` lifecycle rule on the bucket with
+a 1–7 day expiry. Every S3-compatible provider supports it, MinIO included.
+This is the one piece of operational setup the feature asks of you.
+
+## Error codes
+
+Every non-2xx JSON response body is `{ error: <generic human message>, code:
+<machine code> }`. The human message is safe to log/display as-is; the
+`code` is the stable value to branch on (retry logic, alerting, i18n
+mapping). The real exception detail (name/message/stack) is **never** sent
+to the client — it goes only to the [`onError`](#onerror--the-logging-seam) seam.
+
+| `code`                | Where it comes from                                                                                | Typical cause                                                                                                                                                           |
+| --------------------- | -------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `PRESIGN_FAILED`      | `POST /presign` 500                                                                                | Storage provider rejected the presign call                                                                                                                              |
+| `STORAGE_ERROR`       | multipart init/sign-part/complete/abort/resume 500, drive list/transfer 500, uncaught router error | S3/MinIO call failed, or an unhandled exception anywhere in routing                                                                                                     |
+| `NOT_FOUND`           | `POST /multipart/resume`, 404                                                                      | The provider no longer holds that multipart upload — completed, aborted, or reaped by a lifecycle rule. A 4xx on purpose: the client drops its session and starts fresh |
+| `BAD_REQUEST`         | any route, 400                                                                                     | Empty body, malformed JSON, or invalid file metadata (missing/wrong-typed `name`/`type`/`size`)                                                                         |
+| `AUTH_REQUIRED`       | `POST /presign`, `POST /multipart/init`, 403                                                       | Neither `auth`, `getUserId`, nor `allowAnonymousUploads` is configured — anonymous uploads are rejected by default                                                      |
+| `AUTH_DENIED`         | multipart sign-part/complete/abort/resume, 403                                                     | The resolved caller (via `getUserId`) doesn't match the uid the upload token was issued to                                                                              |
+| `AUTH_PROVIDER_ERROR` | OAuth token exchange, 502                                                                          | The provider's token endpoint rejected the code/refresh-token exchange                                                                                                  |
+| `AUTH_EXPIRED`        | drive token refresh failure (internal)                                                             | Refresh token dead/revoked — forces a clean re-auth                                                                                                                     |
+
+Upload-token verification failures (multipart sign-part/complete/abort/resume)
+are a separate, narrower vocabulary — always `403` — because they describe the
+token itself, not a storage/auth outcome:
+
+| Token `code`    | Meaning                                                                                              |
+| --------------- | ---------------------------------------------------------------------------------------------------- |
+| `malformed`     | Token isn't the expected `body.signature` shape, or its payload is missing required fields           |
+| `bad_signature` | Token is well-shaped but the HMAC signature doesn't verify (wrong/rotated secret, or tampering)      |
+| `expired`       | Token's `exp` claim is in the past — or, on `/multipart/resume` alone, the resume window has elapsed |
+
+On the client, `@useupup/core`'s upload strategies read these bodies and
+construct typed errors (`UpupStorageError` / `UpupAuthError`) carrying the
+same `.code`, and `errorCodeToMessageKey()` maps a code to an i18n catalog
+key for display.
+
+## `onError` — the logging seam
+
+```ts
+createUpupHandler({
+    // ...
+    onError(event) {
+        // event: { route, method, status, code, message, requestId?,
+        //          error?: { name, message, stack? } }
+        myLogger.error('upup-server', event)
+    },
+})
+```
+
+Called on every error path (500s, invalid upload tokens, OAuth/token-exchange
+failures, health-check storage failures). **Guaranteed never to receive**
+request bodies, tokens, `uploadTokenSecret`, S3 credentials, signatures, or
+`Authorization` headers — only a static route string, the HTTP method,
+status, machine `code`, a generic message, and the caught error's
+`name`/`message`/`stack`.
+
+If you don't supply `onError`, the default logs one structured line via
+`console.error('[upup:server]', JSON.stringify(event))` — so error visibility
+is on by default, not something you have to wire up before your first
+incident. Override it to ship events to Datadog/Sentry/your own sink, or
+supply a no-op to silence it.
+
+## Lifecycle hooks
+
+```ts
+createUpupHandler({
+    // ...
+    hooks: {
+        onBeforeUpload: async (file, req) => true, // reject by returning false
+        onFileUploaded: async (file, req) => {
+            /* one file completed */
+        },
+        onUploadComplete: async (files, req) => {
+            /* a request's file(s) completed */
+        },
+    },
+})
+```
+
+**Which hook fires on which upload path — read this before wiring alerting or
+webhooks on top of these:**
+
+- **`onFileUploaded`** fires once per file on both server-side-completion
+  paths: `POST /multipart/complete` (server has just finished the S3
+  multipart upload) and the drive **transfer** path,
+  `POST /files/:provider/transfer` (server has just finished streaming a
+  cloud-drive file into S3). Both are genuinely server-side completions — the
+  server can see the finished object.
+- **`onUploadComplete`** fires only on `POST /multipart/complete`, and always
+  with a **single-element array** — the server completes one file per
+  request and has no cross-file batching concept. If you need a true "all the
+  user's files are done" signal, use the client-side `onUploadComplete` prop
+  in `@useupup/core`/the UI packages instead, which does see the whole batch.
+- **Client-direct presigned-PUT uploads bypass the server entirely** (`POST
+/presign` only hands the client a URL; the browser then PUTs straight to
+  S3), so **no server-side hook fires for that path at all** — the server
+  never observes completion. If you need server-visibility into presigned
+  uploads, use the client-side `onUploadComplete` prop, or point
+  `processingEndpoint` at an SSE route so the client tells your server when
+  it's done.
+- On the multipart-complete path, the hook's `file.type` is always `''` —
+  the declared MIME type is not retained server-side once the multipart
+  upload completes.
+
+## `/health`
+
+```sh
+curl https://your-app.example.com/api/upup/health
+```
+
+```json
+{ "status": "ok", "checks": { "config": "ok", "storage": "ok" } }
+```
+
+Unauthenticated (checked **before** `config.auth`, so uptime/deploy probes
+work without credentials) and always responds `200` — it's liveness-friendly;
+the `status`/`checks` fields carry the actual health signal rather than the
+HTTP status code, so an orchestrator doesn't restart a container over a
+transient S3 blip. `checks.config` is `'ok'` when `storage.bucket`,
+`storage.region`, and a valid-length `uploadTokenSecret` are all present;
+`checks.storage` is a cheap `HeadBucketCommand` probe (no object
+listing/transfer), TTL-cached for 30 seconds so repeated polling doesn't
+hammer the real provider. A storage-check failure also fires the `onError`
+seam.
+
+### Spotting cross-instance secret drift
+
+Opt in to a fingerprint of `uploadTokenSecret` (never the secret itself):
+
+```ts
+createUpupHandler({ /* ... */, health: { exposeSecretFingerprint: true } })
+```
+
+```json
+{ "status": "ok", "checks": { ... }, "uploadTokenFingerprint": "a1b2c3d4" }
+```
+
+`uploadTokenFingerprint` is the first 8 hex characters of
+`SHA-256(uploadTokenSecret)` — a 32-bit, non-reversible fingerprint over a
+≥128-bit secret. Curl `/health` on each instance behind your load balancer;
+if the fingerprints differ, some instances are running with a different
+secret than others (the exact rolling-redeploy hazard described above), and
+you'll see `bad_signature` errors that look like forgery but aren't.
+Consider network-ACLing this route if you'd rather not expose even the
+fingerprint publicly.
+
+## `TokenStore` — bring your own in production
+
+```ts
+import { InMemoryTokenStore } from '@useupup/server'
+```
+
+**`InMemoryTokenStore` is DEV-ONLY.** It is a zero-dependency reference
+implementation useful for local development, demos, and quick prototypes —
+and unsuitable for production for three reasons:
+
+1. **Lost on restart.** All OAuth drive tokens and pending OAuth state
+   evaporate the moment the process restarts or redeploys.
+2. **Not shared across workers.** Each process/worker/lambda has its own
+   independent `Map`; a request handled by a different instance than the one
+   that stored the token sees it as missing (a spurious re-auth prompt).
+3. **Grows unbounded.** Nothing evicts stale entries beyond their own TTL
+   expiry logic — there is no capacity bound.
+
+Ship a `TokenStore` backed by Redis, Cloudflare KV, or your own
+database/table for any real deployment. The interface is intentionally
+narrow (`get`/`set`/`delete`, string-keyed, optional TTL) to match common KV
+stores directly:
+
+```ts
+export interface TokenStore {
+    get(key: string): Promise<string | null>
+    set(key: string, value: string, ttlSeconds?: number): Promise<void>
+    delete(key: string): Promise<void>
+}
+```
+
+## Links
+
+- [Documentation](https://useupup.com/docs/)
+- [Source & monorepo](https://github.com/DevinoSolutions/upup)
+
+## License
+
+MIT

package/dist/config-3b434689.d.cts

@@ -0,0 +1,297 @@
+import { PresignedUrlResponse, MultipartInitResponse, MultipartSignPartResponse, StorageProvider, UpupCorsConfig } from '@useupup/core';
+
+type UpupServerErrorEvent = {
+    route: string;
+    method: string;
+    status: number;
+    code: string;
+    message: string;
+    requestId?: string | undefined;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string | undefined;
+    };
+};
+type UpupServerLogger = (event: UpupServerErrorEvent) => void;
+
+/**
+ * Free-form routing hints the CLIENT sends alongside a file's name/type/size,
+ * as the `metadata` field of a `/presign`, `/multipart/init`, or drive-transfer
+ * body. upup neither interprets nor validates it — it is carried through to
+ * `keyStrategy` and the storage resolver verbatim.
+ *
+ * It is ATTACKER-CONTROLLED. Treat it as you would a query parameter: switch on
+ * it against a fixed allow-list, never let it name a bucket, a path prefix, or
+ * a credential directly.
+ */
+type UpupClientMetadata = Record<string, unknown>;
+/** Context passed to a custom keyStrategy. */
+interface KeyStrategyContext {
+    /** Resolved userId, or null when anonymous. */
+    userId: string | null;
+    fileName: string;
+    contentType: string;
+    size: number;
+    /** The client's `metadata` field, if it sent one. Untrusted — see
+     *  {@link UpupClientMetadata}. */
+    metadata?: UpupClientMetadata;
+    /** The originating request, past every auth and policy check. */
+    req: Request;
+}
+/** Which of the three presign-side responses `onPresignResponse` is rewriting. */
+type PresignResponsePhase = 'presign' | 'multipart-init' | 'multipart-sign-part';
+interface PresignResponseContext {
+    /** The originating request, already past every auth and policy check. */
+    req: Request;
+    phase: PresignResponsePhase;
+    /** The server-chosen object key. Present on all three phases — on
+     *  `multipart-sign-part` it comes from the VERIFIED token, not the client. */
+    key: string;
+    /** The client-declared file (name/type/size). Absent on
+     *  `multipart-sign-part`, which sees only a token and a part number. */
+    file?: FileMetadata;
+    /** The client's `metadata` field, if it sent one. Untrusted — see
+     *  {@link UpupClientMetadata}. Absent on `multipart-sign-part`. */
+    metadata?: UpupClientMetadata;
+    /** Resolved userId, or null for an anonymous (server-namespaced) upload. */
+    userId: string | null;
+}
+/** What the hook receives — narrow it on `ctx.phase`, or with `'uploadUrl' in response`. */
+type PresignResponseBody = PresignedUrlResponse | (MultipartInitResponse & {
+    token: string;
+}) | MultipartSignPartResponse;
+/** What the hook may return: the same shapes, plus any extra fields you want
+ *  to add for your client. */
+type PresignResponseRewrite = PresignResponseBody & Record<string, unknown>;
+type OnPresignResponse = (response: PresignResponseBody, ctx: PresignResponseContext) => PresignResponseRewrite | void | Promise<PresignResponseRewrite | void>;
+/** One bucket's worth of S3 / S3-compatible connection settings. */
+interface UpupStorageConfig {
+    /**
+     * An S3 / S3-compatible provider label. @useupup/server only speaks the S3
+     * API (buildS3ClientConfig always builds an @aws-sdk/client-s3 client) —
+     * set `endpoint` for any non-AWS backend (MinIO/R2/DO Spaces/etc). A
+     * provider with no S3-compatible surface (currently `StorageProvider.Azure`
+     * — see @useupup/core's NON_S3_STORAGE_PROVIDERS) is rejected by
+     * createUpupHandler at construct time.
+     */
+    type: StorageProvider | string;
+    bucket: string;
+    region: string;
+    accessKeyId?: string;
+    secretAccessKey?: string;
+    /** S3-compatible endpoint (MinIO / Cloudflare R2 / DO Spaces / on-prem). Omit for AWS S3. */
+    endpoint?: string;
+    /** Path-style addressing. Defaults to true when `endpoint` is set (required by MinIO).
+     *  Only applies when `endpoint` is set; ignored for native AWS S3. */
+    forcePathStyle?: boolean;
+    [key: string]: unknown;
+}
+/** Which operation is asking for a storage config. */
+type StorageResolverPhase = 'presign' | 'multipart-init' | 'multipart-sign-part' | 'multipart-complete' | 'multipart-abort' | 'multipart-resume' | 'drive-transfer';
+interface StorageResolverContext {
+    /** The originating request, past every auth and policy check. */
+    req: Request;
+    phase: StorageResolverPhase;
+    /** Resolved userId, or null for an anonymous (server-namespaced) upload. */
+    userId: string | null;
+    /** The client's `metadata` field, if it sent one. Untrusted — see
+     *  {@link UpupClientMetadata}. Absent on the multipart continuation
+     *  phases, which carry only a token. */
+    metadata?: UpupClientMetadata;
+    fileName?: string;
+    contentType?: string;
+    size?: number;
+    /**
+     * Set on `multipart-sign-part` / `-complete` / `-abort` / `-resume` ONLY:
+     * the opaque
+     * identity of the storage this upload's `init` resolved, carried inside the
+     * HMAC-signed upload token. Return the SAME storage for it — the server
+     * re-derives the identity of whatever you return and answers `403
+     * AUTH_DENIED` if it does not match, so a continuation can never be
+     * steered to a different bucket than the one it started in.
+     */
+    storageId?: string;
+}
+type UpupStorageResolver = (ctx: StorageResolverContext) => UpupStorageConfig | Promise<UpupStorageConfig>;
+type UpupServerConfig = {
+    /**
+     * One static bucket, or a resolver called per request to pick one — three
+     * buckets by upload class, a tenant's own bucket, a quarantine bucket for
+     * unscanned files. A resolver is validated at RESOLVE time (a bad config
+     * fails that request with a 500), not at construct time like the static
+     * form.
+     */
+    storage: UpupStorageConfig | UpupStorageResolver;
+    providers?: {
+        googleDrive?: {
+            clientId: string;
+            clientSecret: string;
+        };
+        dropbox?: {
+            appKey: string;
+            appSecret: string;
+        };
+        oneDrive?: {
+            clientId: string;
+            clientSecret: string;
+            tenantId?: string;
+        };
+        box?: {
+            clientId: string;
+            clientSecret: string;
+        };
+    };
+    tokenStore?: TokenStore;
+    /**
+     * Identify the authenticated user for OAuth + tokenStore scoping.
+     * Return null if the request has no authenticated user (OAuth will 401).
+     * If omitted, falls back to a singleton 'default' user — fine for demos,
+     * unsuitable for multi-tenant production.
+     */
+    getUserId?: (req: Request) => Promise<string | null>;
+    /**
+     * HMAC secret for stateless upload tokens (multipart key/uploadId binding).
+     * REQUIRED. Stable, high-entropy, >=16 chars, shared across all instances.
+     * `createUpupHandler` throws if missing or too short.
+     */
+    uploadTokenSecret?: string;
+    /**
+     * Override object-key generation. Default namespaces by userId:
+     * `<userId|anon>/<uuid>/<sanitized-filename>`. The client never chooses the key.
+     */
+    keyStrategy?: (ctx: KeyStrategyContext) => string;
+    /**
+     * TTL, in SECONDS, for the signed GET download URLs this server hands back
+     * (`downloadUrl` on the presign / multipart-complete / drive-transfer
+     * responses, and `getDownloadUrl`'s result). Defaults to 3 days. Lower it
+     * for gated content — a 15-minute link is `900`. This is the download half
+     * only; the upload URL's own 1-hour expiry is unaffected.
+     */
+    downloadUrlExpiresIn?: number;
+    /**
+     * Permit drive providers / tokenStore WITHOUT a getUserId resolver, collapsing
+     * every caller into one shared anonymous namespace. Demos only — never in
+     * multi-tenant production. Default false -> createUpupHandler throws.
+     */
+    allowAnonymous?: boolean;
+    /**
+     * Permit `/presign` + `/multipart/init` with no `auth` and no `getUserId`
+     * resolver — uploads run under the shared anonymous namespace. Demos /
+     * upstream-auth deployments (tus/companion-style, where auth is handled
+     * before the request reaches this handler) only. Default false -> those
+     * routes return 403 AUTH_REQUIRED.
+     */
+    allowAnonymousUploads?: boolean;
+    /**
+     * onFileUploaded/onUploadComplete fire on server-side-completion paths only
+     * (multipart-complete, drive transfer) -- direct presigned-PUT uploads never
+     * reach the server on completion, so no hook fires for them. See the
+     * README's "Lifecycle hooks" section for the full per-path breakdown.
+     */
+    hooks?: {
+        /**
+         * Admission gate. Return `false` to reject with a generic
+         * `403 Upload rejected`; THROW an `UpupError` to reject with that
+         * error's own message and code in the 403 body (a quota check can say
+         * "Storage limit exceeded — upgrade to keep uploading"). Any other
+         * throw stays a generic 500 — internal error text never reaches the
+         * client.
+         */
+        onBeforeUpload?: (file: FileMetadata, req: Request) => Promise<boolean>;
+        onFileUploaded?: (file: UploadedFile, req: Request) => Promise<void>;
+        onUploadComplete?: (files: UploadedFile[], req: Request) => Promise<void>;
+        /**
+         * Last look at a presign-side response body before it is sent, for
+         * deployments where the storage endpoint is not browser-reachable
+         * (a same-origin proxy route, a docker-internal MinIO hostname, a
+         * VPC-only endpoint). Return an object to REPLACE the payload; return
+         * nothing to leave it as-is.
+         *
+         * Fires on exactly three responses, identified by `ctx.phase`:
+         * `POST /presign` (`presign`), `POST /multipart/init`
+         * (`multipart-init`, token already issued), and
+         * `POST /multipart/sign-part` (`multipart-sign-part`).
+         *
+         * It runs AFTER every auth, policy, and token check and cannot bypass
+         * any of them — a request that would 401/403 never reaches the hook.
+         * Rewriting `uploadUrl` changes where the browser sends bytes, so the
+         * URL you substitute must land at the same object.
+         */
+        onPresignResponse?: OnPresignResponse;
+    };
+    /**
+     * How long after its ORIGINAL `/multipart/init` an upload may still be
+     * resumed via `POST /multipart/resume`, in seconds. Default 86400 (24h),
+     * matching the client's localStorage session TTL. Set `0` to disable the
+     * route entirely (it then 404s like any unknown path) — the cost of the
+     * route is that a leaked token stays usable for this window, though only to
+     * continue the SAME upload, to the SAME key, inside the SAME signed size
+     * envelope, and still owner-bound whenever `getUserId` is configured.
+     * Resuming re-issues a token with a fresh 1h expiry but carries the original
+     * issue time forward, so rolling resumes can never extend this window.
+     */
+    multipartResumeWindowSeconds?: number;
+    auth?: (req: Request) => Promise<boolean>;
+    maxFileSize?: number;
+    allowedTypes?: string[];
+    cors?: UpupCorsConfig;
+    /**
+     * Called on every error path (500s, invalid upload tokens, OAuth/token-exchange
+     * failures, health-check storage failures). Never receives secrets, tokens,
+     * request bodies, or Authorization headers — only a route/method/status/code/
+     * message plus the caught error's name/message/stack. Default: logs a
+     * structured line via console.error.
+     */
+    onError?: UpupServerLogger;
+    /** Options for the built-in GET /health route. */
+    health?: {
+        /**
+         * Expose the first 8 hex chars of SHA-256(uploadTokenSecret) on /health so
+         * operators can spot cross-instance secret drift without revealing the
+         * secret itself. Default: false.
+         */
+        exposeSecretFingerprint?: boolean;
+    };
+};
+/**
+ * Key-value store the server uses for OAuth state + drive access tokens.
+ * Interface matches Redis / Cloudflare KV / any string-keyed KV.
+ * Consumers implement this against their own persistence layer.
+ */
+interface TokenStore {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string, ttlSeconds?: number): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** Drive OAuth tokens we persist after a successful /auth/:provider/cb. */
+interface DriveTokens {
+    accessToken: string;
+    expiresAt?: number | undefined;
+    scope?: string | undefined;
+    tokenType?: string | undefined;
+    refreshToken?: string | undefined;
+}
+/** Short-lived OAuth state map, keyed by the random state param. */
+interface OAuthState {
+    userId: string;
+    provider: string;
+    returnTo?: string | undefined;
+}
+interface FileMetadata {
+    name: string;
+    size: number;
+    type: string;
+    /** Free-form routing hints from the client. Untrusted — see
+     *  {@link UpupClientMetadata}. */
+    metadata?: UpupClientMetadata;
+}
+interface UploadedFile {
+    key: string;
+    name: string;
+    size: number;
+    type: string;
+    url: string;
+}
+
+export type { DriveTokens as D, FileMetadata as F, KeyStrategyContext as K, OAuthState as O, PresignResponsePhase as P, StorageResolverPhase as S, TokenStore as T, UpupServerConfig as U, UpupStorageConfig as a, UploadedFile as b, PresignResponseContext as c, PresignResponseBody as d, PresignResponseRewrite as e, OnPresignResponse as f, UpupClientMetadata as g, UpupStorageResolver as h, StorageResolverContext as i };