Subpath deployment — authorized extension

The upstream application assumes a domain root. For a deployment at /mail:

  NEXT_PUBLIC_BASE_PATH=/mail
  APP_URL=https://example.com/mail

Set both before npm run build. NEXT_PUBLIC_BASE_PATH is a Next.js build-time
setting; changing it requires rebuilding. Leave it empty for the original root
behavior. Next Link and router calls retain their original paths. Native links,
fetches, manifest icons, provider callbacks, archive URLs, and direct redirects
use lib/app-path.js. Better Auth and MCP restore the public path before matching
routes or verifying proof-of-possession requests.

Proxy all /mail requests intact to npm start. Preserve Host and forward the
original HTTPS scheme. The included deployment gateway also maps RFC discovery:

  /.well-known/oauth-protected-resource/mail/mcp
    -> /mail/.well-known/oauth-protected-resource/mcp
  /.well-known/oauth-authorization-server/mail
    -> /mail/.well-known/oauth-authorization-server

OAuth's machine API must be reachable without a browser-only challenge. The app
still enforces its allowlist, sessions, PKCE, tokens, permissions and rate limits.
Keep webhook/job signatures enabled in production.

SOURCE_URL optionally points the existing Source code footer link to a download
of this modified release. Keep the upstream README, LICENSE, attribution, lockfile,
and all source files in that archive. The default link remains the upstream repo.

Storage configuration without application changes

The existing S3 client honors AWS_ENDPOINT_URL_S3 through the installed AWS SDK.
An R2 connection uses that account's S3 endpoint and IMAGES_S3_REGION=auto, plus
the original IMAGES_S3_BUCKET, IMAGES_S3_ACCESS_KEY_ID, IMAGES_S3_SECRET_ACCESS_KEY
and IMAGES_CDN_URL variables. No dependency is replaced or upgraded.

This deployment uses the existing private R2 bucket, because its stored credentials
cannot create a new bucket. Each upload retains the original account-specific
accounts/<id>/images/<randomized-name> namespace. The gateway's public /mail/images
route accepts GET/HEAD only and serves an object only when the dedicated MailCheap
database contains its matching public upload record. It never lists the bucket or
serves arbitrary keys. Existing private backup objects remain private. Images have
one-day public cache lifetimes; deletion can remain cached for that period.

The gateway is separate deployment infrastructure. The application continues to
use its original upload action, validation, image library and S3 SDK. Include the
gateway source alongside the app when distributing the modified deployment.

The app, its private MongoDB and gateway are separate supervised processes. Back
up the database and its signing secrets together: changing the secrets breaks
previous email links. Keep production QStash credentials separate from local
development credentials. See docs/resend.txt for the provider extension.
