Web Auth

Understand magic-link login, fail-closed auth config, and the current cookie session model.

Auth inputs

Browser login uses magic links instead of a shared password.

The public /login page accepts an email address. The Worker only sends a sign-in link when the submitted address exactly matches the configured FORWARDING_ADDRESS after trimming and lowercasing. The email is sent from INTERNAL_SENDER_EMAIL and optional INTERNAL_SENDER_NAME, not from any customer inbox identity.

Public responses stay generic. A non-matching or malformed email receives the same “check your email if authorized” response as a matching address, so the page does not reveal the configured forwarding address.

Required production configuration

Set this non-secret Wrangler var in production-like deployments:

AUTH_REQUIRED=true

AUTH_REQUIRED means authentication must be configured and enforced. It is not password-specific.

With password login removed, browser auth is configured when all magic-link dependencies are available:

AUTH_COOKIE_SECRET secret
FORWARDING_ADDRESS var
INTERNAL_SENDER_EMAIL var
EMAIL binding

When AUTH_REQUIRED=true and any dependency is missing, the app fails closed: /app and protected cookie-auth JSON routes stay protected, while /login shows a generic setup/unavailable message.

For local development, omitting AUTH_REQUIRED and auth dependencies keeps the app unlocked.

Secrets

Use Wrangler secrets for sensitive values:

wrangler secret put AUTH_COOKIE_SECRET --config wrangler.jsonc
wrangler secret put API_TOKEN --config wrangler.jsonc

AUTH_COOKIE_SECRET signs both browser session cookies and magic-link tokens. Rotating it invalidates active browser sessions and outstanding magic links.

API_TOKEN is separate and only applies to bearer-protected /api/* machine routes.

When login succeeds, the server issues a cookie named cloudflare_inbox_session.

Current behavior:

HttpOnly
SameSite=Lax
Path=/
Max-Age=30 days
Secure when the request is HTTPS

Validation model

This alpha app does not store sessions in a database.

Instead, it computes the expected cookie value from AUTH_COOKIE_SECRET. Magic-link tokens are also stateless HMAC-signed values with a short expiry and a recipient scope tied to the configured forwarding address.

Protected surfaces

The shared cookie is checked on:

/app
/send
/inbox-settings
/thread-read
/thread-archive
/thread-unarchive

The /blob route remains public for now so emailed attachment fallback links still work outside the logged-in browser session.

Magic-link URLs

Magic-link URLs use the current request origin for now. This keeps the single-tenant deployment simple for the current Worker and future simple-inbox.dev custom domain.

Future SaaS/product features may need a configured public origin for webhooks, custom-domain tenant routing, or link generation outside a browser request.

When to harden it later

Move beyond this model when you need one of these:

per-user sessions
session revocation without rotating the global secret
attachment privacy on emailed /blob links
audit trails tied to individual operators

On this page