A free, open-source, self-hosted place to write a novel.
Fablewright docs security.md
18 kB · 304 lines
Markdown
at main

Security model #

This document describes what a Fablewright instance stores, who can read it, and where the trust boundaries are. It is for an operator, a reviewer, or a writer who wants to know what the server can see. It is not a promise that the software has no bugs. Report a vulnerability through the security policy.

The short version #

Fablewright does not use end-to-end encryption. The person who runs the server can read the database, uploads, and backups. The app has no analytics or telemetry. The proofreader runs in the browser. Read aloud uses the browser's speech engine. An online voice can send the scene to the browser's speech service.

If the words must stay secret from the server operator, do not put them on that instance. Fablewright does not provide that protection.

What the instance holds #

Data Where it lives Notes
Accounts user, account, session, passkey tables Email, display name, password hash, session rows and passkey public keys.
Manuscripts project, book, part, chapter, scene tables The prose, titles, planning fields and word counts.
Notes and images note, note_type, note_image, uploads/ Note text, templates, image facts, display WebP and optional original.
Plot and links storyline, plot_card, plot_card_note, scene_note Storylines, cards and note links.
History scene_snapshot, item_version, project_checkpoint Automatic and hand-saved versions, note and card versions, project versions.
Goals writing_day, writing_goal Daily counts and the goal for one writer in one project.
Sharing project_member, project_invitation, project_share, scene_feedback Roles, invitations, hashed secret links with a scope, and feedback.
Imports import_report, uploads/imports/ The file a writer handed over and the report of what arrived.
Drills restore-drills.ndjson One JSON line per restore drill, beside the database.
Backups backups/ Database, signing secret, uploads and a manifest.

Session records can contain client IP addresses and user-agent strings. Passkey private keys do not live on the instance. A preserved import source can contain comments, tracked changes, image metadata, or other material that the converted manuscript omits. Keep it as private as the source document.

The database is SQLite. It is not encrypted at rest by the app. The uploads are ordinary files. A backup is a copy of both, and it is not encrypted either.

The server operator #

The operator with shell access can read every table and every upload. The app's admin role manages accounts, the instance name, sign-up and recovery history. It does not grant access to another writer's project. Project access comes from the project_member row.

A person who can read the backup can read the same data. Protect the data directory and backup copies with the same care as the manuscripts themselves.

The admin console can reset another account's password. That is an account recovery power, not a guarantee that an admin cannot obtain access indirectly. Choose an operator and admins you trust. Admin actions have no audit log.

Transport and origin #

  • Serve the app over HTTPS. A passkey needs HTTPS or localhost. A secret link in a plain HTTP request is visible on the network.
  • Set ORIGIN to the public address when the instance has one. The entry point uses it to answer SvelteKit's origin check on form POSTs, and better-auth uses it for absolute URLs.
  • Set TRUST_PROXY=1 only when every request arrives through a proxy that overwrites X-Forwarded-For and X-Forwarded-Proto. With this on and no such proxy, a client that can reach the app directly chooses its own scheme and its own throttle bucket.
  • Leave ORIGIN empty and TRUST_PROXY=0 for a direct install. The entry point then writes the socket address into X-Forwarded-For before anything reads it, so a header the client sent is discarded.

ORIGIN fixes the public origin, but it does not identify the client behind a proxy. server.js resolves the address once, from the socket under TRUST_PROXY=0 and from the trusted proxy chain under TRUST_PROXY=1, then writes that single value into X-Forwarded-For. adapter-node reads it as the client address and better-auth reads the same header, so neither can be given a fabricated address. Restrict the app port to the proxy. Merely setting ORIGIN does not make a publicly reachable forwarded-address header trustworthy.

server.js exists because adapter-node guesses https for a request without a proxy header. Without the entry point, a plain HTTP install fails the origin check and every form POST is rejected.

Authentication #

  • Passwords are hashed by better-auth. The command line writes the same scrypt hash the sign-in form reads.
  • A password must be at least 10 characters.
  • A password change ends every other session. A password reset ends every session on the account.
  • A session token never reaches a page. The account page lists when and where a session started, not the token.
  • A passkey stores a public key. The private key stays on the device. Adding a passkey needs a session made in the last day.
  • The sign-in, sign-up, forgot-password and reset-password forms are throttled in the process. A restart clears the counts. See the operations guide for the numbers.
  • The browser reaches better-auth only for a passkey ceremony, the reset link from a mail, and a read of the caller's own session. Every other path under /api/auth answers 404, because each one duplicates a form action without its throttle. A caller cannot skip the counters by calling better-auth directly.
  • The app does not verify that an email address belongs to the person who typed it. Password reset trusts the mail relay to deliver to the right mailbox.

The first account on an instance becomes the admin, and claiming the instance closes sign-up. The admin can open sign-up again on Instance or create accounts by hand. Keep at least one admin who can sign in.

Restrict access until you claim a new instance. There is no separate bootstrap token. An empty instance, including one emptied through the account-deletion tool, is claimable by the next person who signs up.

A password reset does not revoke passkeys. If an account is compromised, disable it, reset its password, and review its passkeys before restoring ordinary access. Passkeys remain bound to their domain if the server moves. A different domain requires new credentials.

Access #

  • Every project page, action and API route goes through src/lib/server/access.ts. The role comes from project_member: owner and co_author write, reader reads, and every refusal is a 404 "No such …".
  • A bare id in a form or query string is not trusted. A snapshot, note, card or scene function takes the project as its first argument and checks the id inside it.
  • The owner manages sharing and deletion. A co-author writes, plans, exports and uses recovery. A reader reads, uses the outline and comments, and cannot open the editing workspace. Search returns only the documents the caller could open, so a reader's search reaches the manuscript and never the planning notes.
  • A secret link is a bearer token. Anyone who holds it gets the permission and scope it carries until it expires or is revoked. The server hashes the secret with SHA-256 and stores only that hash.
  • The first request carries the secret in the query string. The server exchanges it for an HttpOnly, SameSite=Lax cookie scoped to /s/<id>, and redirects to the clean address. The cookie is Secure on HTTPS.
  • Shared responses send cache-control: private, no-store, referrer-policy: no-referrer and x-robots-tag: noindex, nofollow.
  • A proxy or access log that records the full URL can record the secret before the app removes it. Configure the proxy and the log to omit query strings for /s/ requests.

Do not treat a guest name or link label as verified identity. A link can be forwarded, and anyone with an editing link can change scene prose. Revocation blocks future requests, not copies or prose already on screen. Members can see all project feedback. Guests see feedback associated with their own link.

Account invitations require acceptance by an existing account and expire after 30 days. The app does not deliver invitations or links by email. The sharing guide lists permissions, expiry choices, and the current-manuscript scope.

Content handling #

  • The editor stores TipTap JSON. The read-through renders it through src/lib/server/prose-html.ts, which escapes every character and handles only the nodes and marks the editor produces. It is not a general HTML renderer.
  • A link address is checked by safeHref, which strips control characters before it reads the scheme. javascript: and data: links are refused. The editor and the read-through share the rule.
  • A note image is decoded by sharp, re-encoded to WebP and stored under a UUID. The response type comes from the file's magic bytes, never from the database column. A file that names no image type is downloaded, not displayed. Every image response carries content-security-policy: sandbox.
  • Import reads the zip central directory itself, expands only manuscript.json, stops at the declared size, and verifies the CRC. Project image entries are read separately with limits. Word import reads selected XML entries and reports known conversion losses.
  • The app does not execute an imported file. It parses the file and keeps a copy for the writer to download.
  • The app does not run an antivirus scan. Treat an imported file from an untrusted source as untrusted.

The display copy of a note image drops EXIF and GPS metadata. A preserved original keeps the uploaded bytes, including metadata. Project archives can carry those originals. Do not distribute one without considering what its images disclose.

Import accepts files up to 100 MiB, and note images up to 10 MiB and 64 million pixels. These are per-file limits, not account quotas. A proxy can impose smaller request limits. The entry point also caps a body by route: 101 MiB for an import, 12 MiB for a route that carries a document, and 2 MiB for anything else, refused before any code reads it. No app setting limits a writer's total stored data.

Backups and data at rest #

A full backup copies the database, uploads, and auth-secret file when present. It does not capture an environment-supplied BETTER_AUTH_SECRET. Protect that value separately. A backup includes account credentials and session data, so treat it as sensitive as the live instance. The app does not encrypt it.

A --database-only backup and a Cloudron snapshot hold no uploads. They are for a deployment that copies the rest of the data directory itself, or for the Cloudron backup hook. Do not treat one as a full backup.

  • Keep the data directory readable only by the user that runs the app.
  • Copy backups off the machine, and protect the copy.
  • Do not put a backup in a public object store or a public repository.
  • Delete a pre-restore database when the restored instance is confirmed. It holds the old data.
  • A restore drill restores into a temporary directory, never over the live database, and records its result beside the database.

The database's SHA-256 digest appears in the backup manifest. Uploads have file counts and byte totals, not individual digests. A passing verification or drill does not prove every uploaded byte is unchanged. A drill also does not test an actual password or browser sign-in. The operations guide defines the checks and their limits.

Restoring a backup restores its account and project-access state. Previously revoked sessions, memberships, or secret links can become usable again if the backup still contains them and they remain valid. Review access after a restore.

Browser copies #

The editor can keep unsaved prose in browser storage. Planning fields and feedback drafts can also remain there. Other scripts running on the same origin and someone with access to the browser profile can read local storage. It is not encrypted manuscript storage.

Server backups do not include browser drafts. Clearing site data or using a different profile or address can make them unavailable. On a shared computer, use a separate browser profile and keep downloaded drafts private. Do not assume signing out securely erases every browser copy.

The app's save checks prevent a stale editor from silently replacing a newer scene revision. They do not merge concurrent edits or turn browser storage into an offline project copy.

Deletion and retention #

Deleting manuscript structure or a project normally moves it to recovery or trash. Permanent project deletion removes its database rows and retained history. Upload files remain until prune-uploads removes unreferenced files.

History retention defaults to 365 days with per-item minimums. Scene versions saved by hand and project versions saved by hand do not expire automatically. An operator can explicitly prune them. The recovery guide explains the writer-facing policy.

Account deletion is immediate in the live database, but it does not erase old backups, downloaded archives, proxy logs, or copies held by other people. Deleted rows can also remain in SQLite's unused pages until the file is rewritten. The app does not promise forensic erasure or a universal retention deadline.

Project archives include deleted work, retained history, feedback, and author names. Use Word, EPUB, PDF, or a reading link when a reviewer needs only live prose. The import and export guide lists archive contents.

Logging and privacy #

Startup and failure logs can identify the build, origin, migration, health probe, import, or mail failure. Password-reset links appear when mail is unavailable. The app does not intentionally log manuscript prose. Logs can still contain email addresses, file names, and reset links, so treat them as sensitive.

The app has no analytics, no telemetry and no third-party script. Fonts are served by the instance. The proofreader is downloaded from the instance and runs in a Web Worker. The page does not send the manuscript to another service for it.

For read aloud, Fablewright sends no manuscript to its server and stores no audio. The browser's own speech engine reads the selected scene. A voice the browser reports as online can send the scene to the browser's speech service. A voice reported as on this device is intended to stay local, but Fablewright cannot guarantee how the browser or voice handles it. If the browser reports no on-device voice for the page language, the first use asks before an online voice is used. Choosing an online voice in the picker also gives consent.

Hardening checklist #

  1. Serve the app over HTTPS.
  2. Set ORIGIN to the public address. Set TRUST_PROXY=1 only behind a proxy that overwrites the forwarding headers.
  3. Set a strong BETTER_AUTH_SECRET in a bare Node install. Keep it with the data.
  4. Use a TLS mail relay. SMTP_SECURE=true uses TLS immediately. The default can negotiate STARTTLS but does not require it.
  5. Leave sign-up closed on Instance unless writers need to register themselves.
  6. Give each writer their own account. Do not share one login.
  7. Keep the data directory and the backups private.
  8. Keep a second admin, and disable an account instead of deleting it when the problem is access.
  9. Review members and secret links on the Sharing page. Revoke what is no longer needed.
  10. Poll /api/health and watch free disk space.
  11. Run prune-uploads after permanent deletions, and prune-history when the history grows beyond the window.
  12. Patch the host, Node and the dependencies. Read CHANGELOG.md before an upgrade, and take a backup first.

Known limits #

  • No end-to-end encryption. The operator can read the data.
  • No email verification. The address is a label, and a reset trusts the mailbox.
  • The sign-in throttle lives in one process. A restart clears it, and two app processes do not share it.
  • No audit log of admin actions.
  • No per-writer storage quota. Import accepts files up to 100 MB and keeps a copy, and a note image is capped at 10 MB.
  • A secret link is a bearer token. It can be limited to one part of a project, but not to one person.
  • A passkey is bound to one domain. An alias domain keeps password sign-in.
  • A backup is unencrypted.
  • Account deletion is immediate and cannot be undone.
  • The app admin does not get access to every project. The server operator does.

Report a vulnerability #

Do not open a public issue for a security problem. Send the report to admin@doubledecimal.com, with the version and commit, the deployment, the steps to reproduce and the impact. The security policy has the details.