Skip to content
Trazum

Accounts

Documentation / Web setup · Deployment · Privacy

Signing in is off by default. With nothing configured, Trazum's web app is what it has always been: you paste a prompt, it answers, and it remembers nothing about you. Nothing in this document is required to run it.

Enable accounts for the saved prompt library and share links. GitHub sign-in, sessions and database-backed storage are optional deployment features. Shared organisation budgets should not be inferred from the presence of accounts; use the documented CLI policies and gateway for budget decisions.


Turning it on#

Three environment variables, a fourth that says who may sign in, and a fifth if you want the sign-in to survive a restart.

VariableRequiredWhat it is
TRAZUM_GITHUB_CLIENT_IDyesFrom your GitHub OAuth app
TRAZUM_GITHUB_CLIENT_SECRETyesFrom the same place. Never sent to the browser
TRAZUM_PUBLIC_URLyesThis deployment's own origin, e.g. https://trazum.example
TRAZUM_DATABASE_URLnoAny Postgres. Without it, sessions live in memory
TRAZUM_DATABASE_SSLnoverify-full (default for remote hosts), require, prefer, allow, disable
TRAZUM_DATABASE_POOLnoConnections per instance. Default 4
TRAZUM_ALLOWED_USERSone of these twoGitHub logins or numeric ids, comma-separated, who may sign in. Admins are always allowed
TRAZUM_OPEN_SIGNUPone of these two1 lets any GitHub account sign in. Anything else is closed
TRAZUM_ADMINSnoWho may see the deployment overview. Empty means nobody, and the page does not exist
TRAZUM_SESSION_IDLE_MINUTESnoMinutes without a request before a session ends. Default 1440 (a day); from 5 to the lifetime
TRAZUM_SESSION_MAX_HOURSnoHours after sign-in before a session ends, however much it is used. Default 720 (thirty days), the most allowed

Sign-in is closed until you say who may use it. With none of TRAZUM_ALLOWED_USERS, TRAZUM_ADMINS or TRAZUM_OPEN_SIGNUP=1 set, the sign-in button answers 503 and names these variables, before GitHub is asked anything. An account not on the list gets 403 at the callback and no row is written. The list is checked on every sign-in, so removing somebody takes effect the next time they sign in. Until 2.4.2 any GitHub account could sign in to a deployment with accounts on, which made a team's prompt library a free prompt store for anyone who found it, up to the per-account caps and at the operator's database bill. Prefer numeric ids: a login can be renamed and claimed by somebody else, exactly as the TRAZUM_ADMINS section below explains.

1. Register a GitHub OAuth app#

https://github.com/settings/developers → New OAuth App.

  • Homepage URL — your TRAZUM_PUBLIC_URL
  • Authorization callback URL — TRAZUM_PUBLIC_URL + /api/auth/github/callback

Trazum asks for the read:user scope and nothing else: the profile, no repositories, no email addresses, no organisation membership, no write access anywhere. If the consent screen offers more than that, it is not this app.

2. Point it at a database (optional, but read this)#

psql "$TRAZUM_DATABASE_URL" -f apps/web/db/001_accounts.sql
psql "$TRAZUM_DATABASE_URL" -f apps/web/db/002_prompts.sql
psql "$TRAZUM_DATABASE_URL" -f apps/web/db/003_shares.sql
psql "$TRAZUM_DATABASE_URL" -f apps/web/db/004_rate_limits.sql

Apply the four migrations in order. Without the fourth, everything works and the sign-in, session and library limits are counted by each instance on its own; the server says so once in its log. They are idempotent and support Postgres: Supabase, Neon, RDS, or a container on your laptop.

Without TRAZUM_DATABASE_URL, sessions are held in memory. That is a real deployment and not a broken one — a single container that you restart rarely is fine — but the consequences are worth being explicit about:

  • A restart signs everybody out.
  • On a platform that runs more than one instance (Vercel, Lambda, anything that scales), the same browser is signed in against one instance and signed out against the next, apparently at random.

Trazum says so rather than letting you find out: /api/auth/session reports ephemeralSessions: true, and the account menu at the foot of the sidebar says "temporary session" above the sentence explaining what that costs you.

3. Start it#

TRAZUM_GITHUB_CLIENT_ID=Iv1.xxxx \
TRAZUM_GITHUB_CLIENT_SECRET=xxxx \
TRAZUM_PUBLIC_URL=https://trazum.example \
TRAZUM_DATABASE_URL=postgres://... \
npm --prefix apps/web start

Misconfiguration does not crash the app. Any missing or invalid variable turns sign-in off, the sidebar renders no button, and /api/auth/* answers 503 with the name of the variable to set — so the failure is readable by the person who can fix it.


The prompt library#

Signed in, a Library tab appears. It holds prompts you saved and every version of each.

RouteWhat it does
GET /api/promptsYour library. A preview per prompt, not the whole text
POST /api/promptsSave the current prompt as version 1
GET /api/prompts/:idOne prompt and its whole history
POST /api/prompts/:idSave the current text as the next version
PATCH /api/prompts/:idRename
DELETE /api/prompts/:idRemove it and every version

Four things about it that are decisions rather than defaults:

History is append-only. Saving over a prompt writes a new row; nothing ever updates one. A history you can edit is not a history, and the question the feature exists to answer — what did we change, and did it get more expensive? — is unanswerable the moment a row can be rewritten.

Saving unedited text saves nothing, and says so. The response is 200 with saved: false, not an error and not a duplicate row. Pressing Save twice is a reasonable thing to do; putting two identical versions in a history whose only job is showing what moved is not.

Token counts are recomputed on read, never stored. The history is a chart of how a prompt's cost moved. Priced with the estimator of the day each version was saved, that line moves when the estimator changes and the prompts did not. Recomputing every version with today's is the only way two are comparable.

Somebody else's prompt is 404, not 403. A 403 confirms the id exists, which turns the route into an oracle for enumerating other people's libraries. There is nothing a legitimate caller can do with the distinction, because they were never getting in either way. The store enforces it in the query — every method takes an owner id and puts it in the where clause, and there is no lookup that takes an id without one, so the mistake cannot be written.

Ceilings#

Refused, never trimmed. Pruning the oldest version to make room would quietly delete the record the prompt was kept for.

LimitValue
Prompts per account200
Versions per prompt500
Prompt text100,000 characters
Name120 characters
Note500 characters
Requests per minute per address60

On the Compare tab, signed in, Create share link publishes a comparison at /c/<token> — readable by anyone holding the URL, with no sign-in.

That is a genuinely different security model from everything else here, and the page says so before the button rather than after: a share link publishes both prompts to anyone who has the URL. The warning is above the control, always visible, and not behind a dialog — a dialog on click is a thing people dismiss; a sentence above the button is a thing they read while deciding.

RouteWho
POST /api/sharesSigned in, same-origin
GET /api/sharesSigned in — your links, previews only, never the prompts
DELETE /api/shares/:tokenSigned in, and only the link's owner
GET /c/:tokenAnyone with the token

The token is the secret. 32 bytes from the CSPRNG, the same generator that mints session cookies. It is stored in the clear, unlike a session token, and the asymmetry is deliberate: hashing a session token means a leaked table is a list of hashes rather than a list of live logins, whereas hashing this one would protect nothing, because the row it points at is the secret.

Links expire. Thirty days by default; 7, 90 or never if you ask. A link that never expires is a permanent publication made by somebody thinking about the next ten minutes, so never exists and has to be chosen.

Reading a link writes nothing. No view counter, no last-seen timestamp. An unauthenticated request that can cause a write is a lever, and "how many people opened this" is not worth being one.

It is kept out of search twice. The page declares noindex in its metadata and robots.txt disallows /c/. Two defences that fail differently: one stops the fetch, the other stops the indexing of a fetch that happened anyway. Neither is a security control — anyone with the URL can read it, which is the feature — both are about the URL not spreading on its own. The page also sends no-referrer, because the token is in the path and any outbound navigation would otherwise put the whole capability in someone else's access log.

Nothing derived is stored. A share holds the two prompts and the settings; the comparison is recomputed on every view, so a link opened next year is priced by next year's rules rather than by a snapshot that quietly stopped being true. The settings are canonicalised on write from a whitelist of known keys — they are replayed into the core on every future view, by a reader who did not choose them and cannot see them.

The README badge#

Every share link doubles as a badge at /badge/<token>.svg:

[![Trazum](https://trazum.example/badge/<token>.svg)](https://trazum.example/c/<token>)

It shows the token change and is recomputed on every load, so it follows the prompts rather than freezing a number from the day it was made. Same capability as the link — revoking the link revokes the badge, because there is only one thing to revoke.

Four properties worth knowing:

  • It always answers 200. An unknown, expired or malformed token renders the same neutral "unavailable" badge. A non-2xx makes GitHub's image proxy show a broken image, which tells every reader of the README something is wrong without saying what — and the three cases must be indistinguishable anyway.
  • The document is inert. No script, no foreignObject, no external font, image or stylesheet. It is served with nosniff and default-src 'none'; sandbox, because an SVG from your own origin is a page when navigated to rather than embedded.
  • No prompt text ever reaches it. The message is assembled from numbers. It is XML-escaped regardless, because "no untrusted text gets here" is a property one commit can break.
  • It is cached (five minutes, public), unlike the page behind the same token. Safe because the token is in the URL, and necessary because a README badge is fetched by every reader of the page.

Limits: 100 links per account, refused rather than evicted.


The deployment overview#

/admin, for accounts named in TRAZUM_ADMINS. Unset by default, and unset means the page does not exist — not "exists and refuses". A signed-in account that is not on the list gets the same 404 as one asking about a deployment with no admins at all, because a 403 would confirm that a dashboard is here and that they are outside it.

There is no organisation model in Trazum and this is the decision not to invent one: a self-hosted instance is the team. The alternative was reading GitHub organisation membership, which means asking for the read:org scope on every sign-in so that some deployments can skip an environment variable. Sign-in asks for read:user and nothing else, and keeping that true is worth more.

# By GitHub username — convenient
TRAZUM_ADMINS=octocat,monalisa

# By GitHub numeric id — safer, see below
TRAZUM_ADMINS=583231,1024025

Prefer ids. A GitHub login is renameable and, once released, reusable, so an admin list naming octocat grants the overview to whoever holds that name today. A numeric id cannot be transferred. Logins are still accepted because they are what an operator actually knows — the dashboard says on screen when it let you in on the strength of one. (Usernames may also be entirely digits, so a list entry of 1001 is read as an id and will not admit the account whose username is 1001.)

It is not a spend report, and it says so#

Trazum has never seen a bill, an API call or a token counter. It reads prompt text and measures it. A dashboard headed "spend" would be printing a number nobody can reconcile against an invoice.

So the headline is input tokens, which is a property of a prompt alone and needs no assumption about how often anyone calls it, and the second figure is how many of those the rules would remove — measured by running the rules, the same standard trazum rank is held to. There is no score. Every number on the page can be reproduced by running trazum on the same prompt.

What it shows about other people#

Counts, prompt names and account logins. Never the text of anybody's prompt. An admin is an operator, not an auditor of what their colleagues wrote, and "which prompt is expensive" is answerable from a name. The text reaches the overview layer only long enough to be counted and is never serialised to a browser.

One overview reads at most 500 prompts. When a deployment has more, the page says so with both numbers rather than reporting a total that quietly covers part of it.


What it does with your data#

ThingWhere it goes
Your GitHub numeric id, login, display name, avatar URLStored, refreshed on each sign-in
GitHub's access tokenNever stored. Exchanged, used once to read the profile above, dropped
Your session tokenSent to your browser as a cookie. Stored here only as its SHA-256
Your email addressNever requested. read:user does not include it
Your addressNever stored. To count requests across instances, a keyed hash of it (trazum_rate_limits) lives for one minute; the key is derived from the GitHub client secret, which the database does not hold
What you sign in, sign out, export, delete, share and revoke, each time you read your saved prompts or your share links, any request the app refuses for what it sent, and any session cookie that no longer opens anythingOne line per event on the server's standard output, with the account's internal id and never its login, a token, an address or any prompt text (lib/security-log.ts). A read is recorded as which kind (the list, one prompt, your links), never which prompt or what it says. A refused request is recorded by its reason (not JSON, would not parse, a value the route will not take) and never by the answer, which quotes what was sent. Kept for as long as the operator's platform keeps logs

Trazum cannot act on your GitHub account, because it does not keep the means to.

You can see where you are signed in, and end any of it. Your sessions in the account menu lists every live session the account has: when it started, when it was last used (to within a few minutes), and which one is this device. Selecting another ends it. Nothing tells one device from another beyond those times, because telling them apart would mean keeping a browser's user agent or its address, and this app keeps neither. Sign out everywhere ends them all.

Ending another session, or all of them, needs a sign-in in the last fifteen minutes. Otherwise the menu asks you to sign in again, which goes through GitHub and comes straight back. That is OWASP ASVS 3.3.4's re-authentication, and it is what stops somebody holding only a copy of your cookie from signing you out of your other devices: their session is older than fifteen minutes and cannot become younger. Signing in again from a browser replaces that browser's session rather than adding one.

You can take it with you, and you can remove it. The account menu's Download my data returns everything the account holds as one JSON file (GET /api/account): the profile above, every saved prompt with every version and note, and every live share link with the text it publishes. Sessions are not in it, because only a hash of each token is stored and it opens nothing. Delete account removes all of the same, immediately; links you sent stop working.


The security decisions, and why#

Written down because a reader should be able to audit them without reading the code, and because several of them look like details until they are wrong.

The callback URL is built from TRAZUM_PUBLIC_URL, never from a request header. Host and X-Forwarded-Host are supplied by the client. A redirect URI built from one lets an attacker send a victim to /api/auth/github with Host: evil.example and receive the authorisation code themselves. That is why the variable is mandatory rather than convenient.

The state nonce is checked before the code is exchanged. Without that check, an attacker completes their own authorisation and hands the resulting callback URL to a victim, silently signing the victim into the attacker's account — after which everything the victim saves is in a library the attacker can read. The order matters as much as the check: verifying state after the exchange passes every functional test and defends against nothing.

Session cookies use the __Host- prefix over HTTPS. The browser refuses a __Host- cookie unless it is Secure, Path=/ and carries no Domain, which means a subdomain — or anything that manages to speak plain HTTP to the host — cannot overwrite your session. It is the only defence here that does not depend on Trazum's own code being right.

Sessions are opaque random tokens, not signed claims. 256 bits from the CSPRNG, meaningless except that a row with their hash exists. Revoking one is a DELETE, which is a property a JWT does not have.

Only the hash is stored. A dump of trazum_sessions is a list of SHA-256 hashes, not a list of usable cookies.

A session ends after a day without use, and thirty days after sign-in whatever happens. Two clocks, and whichever runs out first wins. The lifetime is what OWASP ASVS 4.0.3 V3.3.2 accepts at level 1, and it is also the ceiling: no setting makes a session longer. The idle window is the one that matters on a computer somebody walked away from, and a day is a judgement: dead by the next morning, while signing in again costs one click because GitHub remembers having approved Trazum. For ASVS level 2 set TRAZUM_SESSION_MAX_HOURS=12 and TRAZUM_SESSION_IDLE_MINUTES=30.

How it is kept, because the obvious way is a write on every request: the session's end is stored, and a request that finds the session moves it one idle window on, never past the lifetime. It is rewritten only once it has fallen five minutes behind (a tenth of the window, if that is shorter), so a session in use costs at most one write every five minutes, and the price is paid in the safe direction: a session can end up to five minutes early, never late. A stored end further away than one idle window can only have been written under a longer window, so that session ends at its next use rather than being trusted: how long it sat unused is not known. That is what happens to every session issued before idle timeouts existed, and to the sessions a lower setting no longer allows.

Sign-out deletes the row before clearing the cookie. The other order leaves a live session in the database whose token the browser has just forgotten — invisible, unrevokable through the UI, and valid until its idle window runs out: a day, by default.

?next= cannot leave the origin. Anything that is not a same-origin path is replaced with /, including //evil.example, /\evil.example (browsers normalise that backslash) and anything containing a control character (browsers strip tab, newline and carriage return from URLs before parsing, so the string you filtered is not the destination reached).

Plain HTTP is refused outside localhost. A session cookie over HTTP is readable by anyone on the path, on every request. There is no configuration that makes it safe, so there is no flag to allow it.

Row level security is enabled on both tables, with no policies. This is aimed at Supabase and anything else that puts a REST layer in front of public: no policy means no row matches, so the anonymous key can read nothing. Trazum connects as the table owner, and owners are exempt. Note that the schema uses ENABLE and not FORCE — FORCE applies the policies to the owner too and, with no policies, locks Trazum out of its own tables. The stricter-looking word is the one that takes the site down.

Database TLS is verified by default. verify-full for any non-loopback host. If your provider needs something looser, TRAZUM_DATABASE_SSL is how you say so — deliberately an explicit choice, so that running unverified is something you did rather than something Trazum did for you.


What is not covered#

Stated because the gap between "tested" and "proven" is where this sort of thing goes wrong.

  • The Postgres driver runs against a real PostgreSQL in CI, since November 2026. apps/web/test/store-contract.test.mjs applies every migration in db/ to an empty database and checks the same contract against it and against the memory driver: users, sessions and their expiry, prompts and versions, share links, the admin census, account deletion and the shared request counters. Its first run found two bugs the recorded-SQL tests could not see, both fixed: deleting an account that had ever saved a prompt failed on a foreign key, and share settings were stored as a JSON string, so a shared link replayed defaults. Neither fix needs a migration. Run it yourself with TRAZUM_TEST_DATABASE_URL=postgres://… node --test apps/web/test/store-contract.test.mjs against an empty database; it drops and recreates the public schema.
  • Rate limits are per address, and per instance unless the deployment can share them. With accounts and a database, the sign-in, session and library limits are counted in trazum_rate_limits, so thirty sign-in attempts a minute means thirty across every instance. The anonymous tool routes stay per instance on purpose: they protect the CPU of the instance that runs them. Either way the key is an address, so a script is stopped and a botnet, with an address per request, is not; behind a corporate NAT the budget is the office's rather than yours.
  • Security events go to standard output and nowhere else. How long they are kept, who can read them and what raises an alert is the platform's configuration, which this repository cannot see or set.
  • The idle window counts requests, not attention. A tab left open sends nothing, so it keeps no session alive; reloading the page, or a browser restoring its tabs, is a request and does. There is no warning before a session ends: the next request finds it over, and the account menu offers sign-in again.
  • GitHub is the only provider. The store keys on (provider, provider_id) so a second one is additive, but SSO through anything else is not written.
  • A revoked link is gone, but a copy taken while it was live is not. This is what "publish" means; there is no recall.
  • The overview is deployment-wide, not per team. One instance, one group of people. Two teams sharing a deployment share an overview.
  • The library is per person, not per team. Every prompt has one owner and there is no way to share one. The author_id column on a version exists so that becomes a migration rather than a rewrite, and today it is always the owner.
  • One mutant in the prompt library survives, and is documented on the line that survives it. The memory driver's version sweep on delete cannot be observed through the store's interface: the prompt is already gone and ids are UUIDs, so nothing will ever ask for the orphaned versions again. What it costs is memory, which no assertion in the suite can see.