# 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](../SECURITY.md). ## 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/`, 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](sharing.md) 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](operations.md#prove-that-a-restore-works) 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](recovery.md) 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](import-export.md) 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 , with the version and commit, the deployment, the steps to reproduce and the impact. [The security policy](../SECURITY.md) has the details.