@novacraft-engineering/mailbox 0.4.3 → 0.4.4

package/.env.example

@@ -39,10 +39,12 @@ MAIL_SEATS=[{"email":"info@example.com","address":"info@example.com","name":"Exa
 MAIL_ADDRESS_ALIASES={}
 
 # ─── Store ──────────────────────────────────────────────────────────────────
-# Local SQLite on a mounted volume (recommended):
-TURSO_DATABASE_URL=file:/data/mail.sqlite
-TURSO_AUTH_TOKEN=
-# Falls back to Cloudflare D1 when TURSO_DATABASE_URL is unset.
+# Any SQLite/libSQL database. A file: URL is local SQLite on a mounted volume
+# (simplest, and what a single box wants); a libsql:// URL is a hosted one
+# (Turso or your own sqld) and needs the token below.
+DATABASE_URL=file:/data/mail.sqlite
+DATABASE_AUTH_TOKEN=
+# Optional alternative: Cloudflare D1, used only when DATABASE_URL is unset.
 CLOUDFLARE_ACCOUNT_ID=
 CLOUDFLARE_D1_TOKEN=
 D1_DATABASE_ID=
@@ -52,7 +54,7 @@ D1_DATABASE_ID=
 MAIL_SESSION_SECRET=
 
 # ─── Sending ────────────────────────────────────────────────────────────────
-# ses | resend | brevo
+# Pick one: ses | resend | brevo. Fill in only that provider's keys.
 MAIL_PROVIDER=ses
 SES_ACCESS_KEY_ID=
 SES_SECRET_ACCESS_KEY=
@@ -64,11 +66,15 @@ RESEND_WEBHOOK_SECRET=
 # nothing — pointing this at an address this app receives would loop.
 MAIL_FORWARD_TO=
 
-# ─── Attachments (S3-compatible, e.g. Cloudflare R2) ────────────────────────
-R2_S3_ENDPOINT=
-R2_BUCKET=
-R2_ACCESS_KEY_ID=
-R2_SECRET_ACCESS_KEY=
+# ─── Attachments ────────────────────────────────────────────────────────────
+# Any S3-compatible bucket: AWS S3, Cloudflare R2, Backblaze B2, MinIO, Wasabi.
+S3_ENDPOINT=
+S3_BUCKET=
+S3_ACCESS_KEY_ID=
+S3_SECRET_ACCESS_KEY=
+# Region: real one for AWS, anything for R2 (defaults to "auto").
+S3_REGION=
+# Only if you import an mbox with --store blob (Vercel Blob).
 BLOB_READ_WRITE_TOKEN=
 
 # ─── Optional extras ────────────────────────────────────────────────────────

package/README.md

@@ -1,80 +1,85 @@
-<img src=".github/banner.png" alt="mailbox by Novacraft" width="100%">
+<img src=".github/banner.png" alt="Mailbox" width="100%">
 
 # Mailbox
 
-A shared webmail app: one codebase, one deployment per mailbox. Inbox and
-threads, a rich composer with signatures and templates, attachments on
-S3-compatible storage, sharing links, full-text search, web push, PWA install,
-multi-accessor accounts with roles, and password reset.
+A shared webmail app you host yourself. One codebase, one deployment per
+mailbox. Inbox and threads, a composer with signatures and templates,
+attachments on S3-compatible storage, sharing links, full-text search, web
+push, PWA install, accounts with roles, and password reset.
 
-Every tenant-specific value — name, domain, colours, signature copy, artwork —
+Everything specific to you — name, domain, colours, signature copy, artwork —
 lives in configuration. Nothing in this repository names or pictures any one
 business, and nothing added to it should.
 
-## Deploying — read this first
+## Running your own
 
-**Never deploy, and never `git push`, unless the person you are working with asks
-for it in that same request.** This is a standing rule for every agent and every
-session. A granted deploy covers that one deploy only; it is not permission for
-the next one.
+1. Copy `.env.example` and fill it in.
+2. Put three images on the volume at `BRAND_ASSET_DIR`. See
+   [public/brand/README.md](public/brand/README.md) for the sizes.
+3. Point `DATABASE_URL` at a SQLite file on a mounted volume.
+4. Deploy it anywhere that runs Next.js. The schema is created on first boot
+   and migrates itself forward, so there is no migration step to run.
 
-Here, pushing *is* deploying — for one tenant. A GitHub webhook on this repository
-points at the Coolify that serves production, so a push to `master` auto-deploys the
-**Novacraft** mailbox. The second tenant is deliberately not wired: it shares this
-repository and branch, but Coolify checks the webhook signature against each
-application's own secret, so it is skipped and still needs a manual deploy from Coolify.
-Finish the work, commit locally, leave it unpushed, and say plainly that it is
-waiting.
-
-## Standing up a new mailbox
-
-1. Copy `.env.example` and fill it in. Nothing is hardcoded to a tenant.
-2. Put three images on the volume at `BRAND_ASSET_DIR` — see `public/brand/README.md`.
-3. Point `TURSO_DATABASE_URL` at a SQLite file on a mounted volume.
-4. Deploy. The schema is created on first boot and migrates itself forward.
+It is a plain Next.js app, so Vercel, Coolify, Docker on a VPS, Fly, Render and
+Railway all work. Nothing in the code assumes a particular host.
 
 ## Trying it locally
 
 Outside production the app seeds one account for you — `test@<MAIL_ADDRESS_DOMAIN>`,
-an admin whose password is the address itself — so a fresh checkout can be signed
-into without configuring seats. It is never seeded when `NODE_ENV=production`.
+an admin whose password is the address itself — so a fresh checkout can be
+signed into without configuring seats. It is never seeded when
+`NODE_ENV=production`.
 
-`node --experimental-strip-types scripts/seed-dev.mjs` then fills that mailbox with
-enough traffic to exercise the list, search, paging and attachments. Create the schema
-first by starting the app once, or by calling `ensureMailSchema()`.
+`node --experimental-strip-types scripts/seed-dev.mjs` then fills that mailbox
+with enough traffic to exercise the list, search, paging and attachments.
+Create the schema first by starting the app once, or by calling
+`ensureMailSchema()`.
 
 The attachments are real files, not records: a PDF, a photo, a short video, a
-spreadsheet and a Word document, generated on the spot and uploaded once. Pictures and
-video need `ffmpeg` and the document needs `zip`; whatever is missing is skipped. With
-no bucket configured the seed still runs and writes the records alone, as it always
-did.
+spreadsheet and a Word document, generated on the spot and uploaded once.
+Pictures and video need `ffmpeg` and the document needs `zip`; whatever is
+missing is skipped. With no bucket configured the seed still runs and writes
+the records alone.
 
 ## Configuration
 
-`lib/brand.ts` is the single server-side source of tenant identity — name,
-domain, signature copy, colours, seats, aliases. `lib/brand.client.ts` is the
-browser half, read from `NEXT_PUBLIC_*` and inlined at build time, so a rebuild
-is required to change client-visible branding.
+`lib/brand.ts` is the server-side source of identity — name, domain, signature
+copy, colours, seats, aliases. `lib/brand.client.ts` is the browser half, read
+from `NEXT_PUBLIC_*` and inlined at build time, so changing anything the
+browser shows means a rebuild.
 
-Seats are JSON in `MAIL_SEATS` and seed on first boot only; afterwards accounts
-are managed in the app. `MAIL_ADDRESS_ALIASES` redirects delivery for a seat
-whose mail someone else now reads.
+Seats are JSON in `MAIL_SEATS` and seed on first boot only; after that you
+manage accounts in the app. `MAIL_ADDRESS_ALIASES` redirects delivery for a
+seat whose mail someone else now reads.
 
 ## Storage
 
-`TURSO_DATABASE_URL` takes precedence; without it the app falls back to
-Cloudflare D1, so moving between the two needs no coordinated redeploy. A
-`file:` URL uses local SQLite, which is what a single box wants.
+`DATABASE_URL` is any SQLite or libSQL database. A `file:` URL is local SQLite
+on a mounted volume, which is what a single box wants. A `libsql://` URL points
+at a hosted one — Turso, or your own `sqld` — and takes `DATABASE_AUTH_TOKEN`.
+
+If you would rather not run a database at all, leave `DATABASE_URL` unset and
+fill in the Cloudflare D1 variables instead; the app falls back to D1 over its
+REST API. Either way the queries are the same SQLite, so you can move between
+them without a coordinated redeploy.
 
-Attachments go to any S3-compatible bucket via the `R2_*` variables.
+Attachments go to any S3-compatible bucket through the `S3_*` variables: AWS
+S3, Cloudflare R2, Backblaze B2, MinIO, Wasabi. The older `R2_*` names still
+work if you already set them.
 
 ## Sending
 
-`MAIL_PROVIDER` selects `ses`, `resend` or `brevo` behind one seam. SES is
-signed in-process; no SDK.
+`MAIL_PROVIDER` picks `ses`, `resend` or `brevo` behind one seam, so switching
+providers is an environment change rather than a code change. SES is signed
+in-process, with no SDK. Adding a fourth provider means one send function and one case in
+`lib/mail-provider.ts`.
 
 ## Tests
 
 ```
 npx tsx --test lib/*.test.ts
 ```
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/lib/mailbox.ts

@@ -60,8 +60,8 @@ export type StashItem = {
 const MAX_INBOX = 500
 const MAX_EVENTS = 150
 
-/** Turso once it is configured, D1 until then, so the switch needs no redeploy dance. */
-const tursoConfigured = () => Boolean(process.env.TURSO_DATABASE_URL)
+/** SQLite/libSQL once it is configured, D1 until then, so the switch needs no redeploy dance. */
+const tursoConfigured = () => Boolean(process.env.DATABASE_URL ?? process.env.TURSO_DATABASE_URL)
 
 function db() {
   return tursoConfigured() ? turso() : d1()

package/lib/r2.ts

@@ -15,17 +15,17 @@ import { createHash, createHmac } from 'node:crypto'
 
 const SERVICE = 's3'
 // R2 ignores the region but SigV4 requires one in the scope; AWS S3 needs the real one.
-const REGION = process.env.R2_REGION ?? process.env.S3_REGION ?? 'auto'
+const REGION = process.env.S3_REGION ?? process.env.R2_REGION ?? 'auto'
 
 type Config = { endpoint: string; bucket: string; accessKeyId: string; secretAccessKey: string }
 
 function config(): Config {
-  const endpoint = process.env.R2_S3_ENDPOINT
-  const bucket = process.env.R2_BUCKET
-  const accessKeyId = process.env.R2_ACCESS_KEY_ID
-  const secretAccessKey = process.env.R2_SECRET_ACCESS_KEY
+  const endpoint = process.env.S3_ENDPOINT ?? process.env.R2_S3_ENDPOINT
+  const bucket = process.env.S3_BUCKET ?? process.env.R2_BUCKET
+  const accessKeyId = process.env.S3_ACCESS_KEY_ID ?? process.env.R2_ACCESS_KEY_ID
+  const secretAccessKey = process.env.S3_SECRET_ACCESS_KEY ?? process.env.R2_SECRET_ACCESS_KEY
   if (!endpoint || !bucket || !accessKeyId || !secretAccessKey) {
-    throw new Error('R2_S3_ENDPOINT, R2_BUCKET, R2_ACCESS_KEY_ID and R2_SECRET_ACCESS_KEY must be configured')
+    throw new Error('S3_ENDPOINT, S3_BUCKET, S3_ACCESS_KEY_ID and S3_SECRET_ACCESS_KEY must be configured')
   }
   return { endpoint: endpoint.replace(/\/+$/, ''), bucket, accessKeyId, secretAccessKey }
 }

package/lib/turso.ts

@@ -15,9 +15,9 @@ let cached: Client | null = null
 
 function client(): Client {
   if (cached) return cached
-  const url = process.env.TURSO_DATABASE_URL
-  const authToken = process.env.TURSO_AUTH_TOKEN
-  if (!url) throw new Error('TURSO_DATABASE_URL must be configured')
+  const url = process.env.DATABASE_URL ?? process.env.TURSO_DATABASE_URL
+  const authToken = process.env.DATABASE_AUTH_TOKEN ?? process.env.TURSO_AUTH_TOKEN
+  if (!url) throw new Error('DATABASE_URL must be configured')
   // Embedded replicas and file: URLs need no token; a remote libsql:// URL does.
   cached = createClient({ url, ...(authToken ? { authToken } : {}) })
   return cached

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@novacraft-engineering/mailbox",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "A shared webmail app: one codebase, one deployment per mailbox. Threads, a rich composer with signatures, attachments on S3-compatible storage, sharing links, full-text search, web push and PWA install.",
   "keywords": [
     "webmail",

package/public/brand/README.md

@@ -1,9 +1,5 @@
 # Brand assets
 
-> **Never deploy or `git push` unless asked for it in that request.** Pushing
-> `master` auto-deploys the Novacraft mailbox. See the deploying section in the
-> root [README](../README.md).
-
 **No tenant's artwork belongs in this repository.** Each mailbox keeps its own
 images on its mounted volume, in the directory named by `BRAND_ASSET_DIR`
 (default `/data/brand`), and the app serves them from `/brand/<file>`.

package/scripts/backfill-content-ids.mjs

@@ -20,7 +20,7 @@ const args = process.argv.slice(2)
 const at = args.indexOf('--batch')
 const BATCH = at === -1 ? 40 : Number(args[at + 1])
 
-const db = createClient({ url: process.env.TURSO_DATABASE_URL, authToken: process.env.TURSO_AUTH_TOKEN })
+const db = createClient({ url: process.env.DATABASE_URL ?? process.env.TURSO_DATABASE_URL, authToken: process.env.DATABASE_AUTH_TOKEN ?? process.env.TURSO_AUTH_TOKEN })
 const apiKey = process.env.RESEND_API_KEY
 
 async function retry(work) {

package/scripts/backfill-list-columns.mjs

@@ -24,8 +24,8 @@ const at = args.indexOf('--batch')
 const BATCH = at === -1 ? 500 : Number(args[at + 1])
 
 const db = createClient({
-  url: process.env.TURSO_DATABASE_URL,
-  authToken: process.env.TURSO_AUTH_TOKEN,
+  url: process.env.DATABASE_URL ?? process.env.TURSO_DATABASE_URL,
+  authToken: process.env.DATABASE_AUTH_TOKEN ?? process.env.TURSO_AUTH_TOKEN,
 })
 
 const UPDATE = `UPDATE mail_inbox SET

package/scripts/offload-bodies.mjs

@@ -24,8 +24,8 @@ const at = args.indexOf('--batch')
 const BATCH = at === -1 ? 40 : Number(args[at + 1])
 
 const db = createClient({
-  url: process.env.TURSO_DATABASE_URL,
-  authToken: process.env.TURSO_AUTH_TOKEN,
+  url: process.env.DATABASE_URL ?? process.env.TURSO_DATABASE_URL,
+  authToken: process.env.DATABASE_AUTH_TOKEN ?? process.env.TURSO_AUTH_TOKEN,
 })
 
 /** Ids are ours, but these go into string-interpolated SQL: anything unexpected is left alone. */

package/scripts/seed-dev.mjs

@@ -20,8 +20,8 @@ for (const line of readFileSync(new URL('../.env.local', import.meta.url), 'utf8
 }
 
 const db = createClient({
-  url: process.env.TURSO_DATABASE_URL,
-  authToken: process.env.TURSO_AUTH_TOKEN,
+  url: process.env.DATABASE_URL ?? process.env.TURSO_DATABASE_URL,
+  authToken: process.env.DATABASE_AUTH_TOKEN ?? process.env.TURSO_AUTH_TOKEN,
 })
 
 const DEV_ADDRESS = 'test@example.com'
@@ -103,7 +103,7 @@ async function main() {
   // so opening an attachment in the seeded mailbox opens something. Without a bucket
   // configured the records are written on their own, as they always were.
   const { buildSamples, buildHeavySamples } = await import('./sample-files.mjs')
-  const bucketReady = Boolean(process.env.R2_BUCKET && process.env.R2_ACCESS_KEY_ID && process.env.R2_S3_ENDPOINT)
+  const bucketReady = Boolean((process.env.S3_BUCKET ?? process.env.R2_BUCKET) && (process.env.S3_ACCESS_KEY_ID ?? process.env.R2_ACCESS_KEY_ID) && (process.env.S3_ENDPOINT ?? process.env.R2_S3_ENDPOINT))
   let smallFiles = []
   let heavyFiles = []
   if (bucketReady) {

package/tools/README.md

@@ -1,9 +1,5 @@
 # Tools
 
-> **Never deploy or `git push` unless asked for it in that request.** Pushing
-> `master` auto-deploys the Novacraft mailbox. See the deploying section in the
-> root [README](../README.md).
-
 | File | What it does |
 |---|---|
 | `import-mbox.py` | Import an mbox into a mailbox. Bodies and metadata first, attachments second. |

package/tools/db-backup.py

@@ -33,7 +33,7 @@ def load_env(path):
 
 
 def query(sql, args=None, attempts=9):
-    host = os.environ['TURSO_DATABASE_URL'].replace('libsql://', 'https://').rstrip('/')
+    host = (os.environ.get('DATABASE_URL') or os.environ['TURSO_DATABASE_URL']).replace('libsql://', 'https://').rstrip('/')
     stmt = {'sql': sql}
     if args:
         stmt['args'] = [{'type': 'text', 'value': str(a)} for a in args]
@@ -42,7 +42,7 @@ def query(sql, args=None, attempts=9):
     for attempt in range(attempts):
         try:
             request = urllib.request.Request(host + '/v2/pipeline', body, {
-                'Authorization': 'Bearer ' + os.environ['TURSO_AUTH_TOKEN'],
+                'Authorization': 'Bearer ' + (os.environ.get('DATABASE_AUTH_TOKEN') or os.environ['TURSO_AUTH_TOKEN']),
                 'Content-Type': 'application/json'})
             with urllib.request.urlopen(request, timeout=180) as response:
                 payload = json.load(response)

package/tools/import-mbox.py

@@ -260,8 +260,8 @@ class S3Store:
         self.endpoint = (env('S3_ENDPOINT') or env('R2_S3_ENDPOINT') or '').rstrip('/')
         self.bucket = env('S3_BUCKET') or env('R2_BUCKET') or ''
         self.region = env('S3_REGION') or env('R2_REGION') or 'auto'
-        self.access_key = env('AWS_ACCESS_KEY_ID') or env('R2_ACCESS_KEY_ID') or ''
-        self.secret_key = env('AWS_SECRET_ACCESS_KEY') or env('R2_SECRET_ACCESS_KEY') or ''
+        self.access_key = env('S3_ACCESS_KEY_ID') or env('AWS_ACCESS_KEY_ID') or env('R2_ACCESS_KEY_ID') or ''
+        self.secret_key = env('S3_SECRET_ACCESS_KEY') or env('AWS_SECRET_ACCESS_KEY') or env('R2_SECRET_ACCESS_KEY') or ''
 
     def configured(self):
         return all([self.endpoint, self.bucket, self.access_key, self.secret_key])
@@ -471,10 +471,10 @@ def main():
     if args.max_mbps:
         UPLOAD_BUDGET.__init__(args.max_mbps)
         print(f'upload cap: {args.max_mbps} Mbit/s', flush=True)
-    url, db_token = os.environ.get('TURSO_DATABASE_URL'), os.environ.get('TURSO_AUTH_TOKEN')
+    url, db_token = (os.environ.get('DATABASE_URL') or os.environ.get('TURSO_DATABASE_URL')), (os.environ.get('DATABASE_AUTH_TOKEN') or os.environ.get('TURSO_AUTH_TOKEN'))
     blob_token = None if args.skip_attachments else (os.environ.get('BLOB_READ_WRITE_TOKEN') if STORE == 'blob' else 's3')
     if not args.dry_run and not (url and (db_token or url.startswith('file:'))):
-        sys.exit('TURSO_DATABASE_URL and TURSO_AUTH_TOKEN must be set')
+        sys.exit('DATABASE_URL and DATABASE_AUTH_TOKEN must be set')
     kinds = {kind.strip() for kind in args.kinds.split(',') if kind.strip()}
     if not args.dry_run and not args.skip_attachments and not blob_token:
         print('BLOB_READ_WRITE_TOKEN unset: attachments will be metadata only', flush=True)