Repository navigation
Contracts
Mostly built. This is the contract decided in ADRs 0034, 0035, 0036, 0037 and 0052. Built: a schema per app, the environment Spotcraft sets, migrations from the image's label, the health check, the user pool with guests, analytics, mail, static sites and the local stack. Not yet: signing in and turning a guest into a user, and spotkit on npm.
Everything an app gets from Spotcraft, and everything Spotcraft expects from it. An app that
follows this page runs anywhere that provides the same values: a Supabase project, say, has the
same auth.users to point at.
One per deployable folder, next to its package.json or Dockerfile:
{ "name": "lifts-api", "migrate": "pnpm db:migrate" }-
nameis the app's slug: lowercase letters, digits and dashes. It names the app's schema and role (app_<slug>, with dashes as underscores) and its subdomain. It is the app's identity: renaming means a new app. -
migrateis optional.spotcraft devruns it on your machine after creating the schema. On the server, the image's label does that job (below).
Spotcraft sets these for every container app. The app's own env can't override them.
| Variable | Value |
|---|---|
PORT |
The port to listen on. |
PUBLIC_URL |
The app's public address, e.g. https://librelifts.app. |
APP_NAME |
The slug. |
APP_RELEASE |
The image tag that is running. |
APP_SECRET |
32 random bytes, base64, for the app's own signing. Stable across deploys. |
DATABASE_URL |
The instance database, as the app's role. |
DATABASE_SCHEMA |
The app's schema, app_<slug>. |
AUTH_URL |
The user pool, through the app's domain: <PUBLIC_URL>/_spotcraft/auth. |
AUTH_ISSUER |
The iss every token from the pool carries. |
AUTH_JWKS_URL |
The pool's public keys. |
SMTP_URL |
The instance's mail relay, as the app: smtp://<slug>:<token>@mail:2525. |
MAIL_FROM |
The instance's sender, noreply@<apps domain>, shared by every app. |
LEGAL_FACTS |
The instance's legal facts, as JSON (below). |
Locally, spotcraft dev writes the same names to .env, pointing at the repository's own stack
(the CLI).
One Postgres database per instance, apps, laid out like a Supabase project:
| Schema | Owner | The app may |
|---|---|---|
app_<slug> |
the app's role | do anything: it is the app's own |
auth |
the user pool | read auth.users (id, is_anonymous, created_at, updated_at) and point foreign keys at its id
|
| other apps' | their roles | nothing |
- The app's role has its schema as its
search_path, so unqualified names (Drizzle'spgTable) land there. - It can't create schemas or extensions. Ask for an extension to be added to the instance.
- At most 20 connections, and statements stop after 30 seconds.
With Drizzle, put the app's tables in its schema by name, and keep the pool's users table in a
file of its own that the config doesn't list, so drizzle-kit only references it:
// src/db/auth.ts: the pool's table, referenced, never migrated by the app.
import { pgSchema, uuid } from 'drizzle-orm/pg-core'
export const users = pgSchema('auth').table('users', { id: uuid('id').primaryKey() })// src/db/schema.ts: the app's tables.
import { pgSchema, text, uuid } from 'drizzle-orm/pg-core'
import { users } from './auth.ts'
// The app's schema, app_<slug>: the same name on the server and locally. Not exported, so
// drizzle-kit doesn't try to create it.
const app = pgSchema('app_lifts')
export const workouts = app.table('workouts', {
id: uuid('id').primaryKey().defaultRandom(),
userId: uuid('user_id')
.notNull()
.references(() => users.id, { onDelete: 'cascade' }),
name: text('name').notNull(),
})A plain pgTable would work for queries, but drizzle-kit writes "public"."<table>" into the
foreign keys between the app's own tables, and an app can't use public.
In drizzle.config.ts, list only the app's tables:
export default defineConfig({
dialect: 'postgresql',
schema: './src/db/schema.ts',
out: './drizzle',
})Drizzle's migrate() and drizzle-kit migrate can't apply the files on Spotcraft: they first
run CREATE SCHEMA IF NOT EXISTS for their journal, and Postgres checks the right to create
schemas before it notices that the schema exists. Apply them with a few lines instead, in
Drizzle's own journal table, so drizzle-kit keeps working as before:
// src/db/migrate.ts: `node src/db/migrate.ts`, or the image's migrate label.
import { readMigrationFiles } from 'drizzle-orm/migrator'
import pg from 'pg'
const schema = process.env.DATABASE_SCHEMA ?? 'app_lifts'
const journal = `${pg.escapeIdentifier(schema)}.__drizzle_migrations`
const client = new pg.Client({ connectionString: process.env.DATABASE_URL })
await client.connect()
try {
await client.query('BEGIN')
await client.query('SELECT pg_advisory_xact_lock(1)')
await client.query(
`CREATE TABLE IF NOT EXISTS ${journal} (id serial PRIMARY KEY, hash text NOT NULL, created_at bigint)`,
)
const { rows } = await client.query(`SELECT max(created_at) AS last FROM ${journal}`)
const last = Number(rows[0].last ?? 0)
for (const migration of readMigrationFiles({ migrationsFolder: './drizzle' })) {
if (migration.folderMillis <= last) continue
for (const statement of migration.sql) await client.query(statement)
await client.query(`INSERT INTO ${journal} (hash, created_at) VALUES ($1, $2)`, [
migration.hash,
migration.folderMillis,
])
}
await client.query('COMMIT')
} catch (error) {
await client.query('ROLLBACK')
throw error
} finally {
await client.end()
}The server runs them, before the new version starts:
LABEL dev.spotcraft.migrate='["node", "dist/migrate.js"]'
# in a distroless image, where node isn't on the PATH:
LABEL dev.spotcraft.migrate='["/nodejs/bin/node", "dist/migrate.js"]'- The label is a JSON array: the command and its arguments, run without a shell. It replaces the image's entrypoint and command.
- It runs once per deploy, in a container from the new image, with the app's env and limits. Exit 0 to go on; anything else fails the deploy, and the running version keeps serving. It has 5 minutes.
- The running version is still up while it runs, so migrations only add: new tables, new nullable columns. Renames and drops need two releases.
- Without the label, nothing runs; the app may migrate itself when it starts.
/_spotcraft/* on every app domain belongs to the platform:
| Path | What |
|---|---|
/_spotcraft/auth/* |
The user pool (Better Auth's API). |
/_spotcraft/s.js |
The analytics script (Umami's tracker). |
/_spotcraft/e |
Where analytics events go (Umami's collect endpoint). |
/_spotcraft/config.json |
The app's analytics settings, for clients that send their own events. |
/_spotcraft/legal.json |
The instance's legal facts, the same as LEGAL_FACTS. |
/_spotcraft/webhook is kept for calls from the platform to the app.
Spotcraft adds headers to an app's responses, and nothing to their content (ADR 0012, ADR 0043):
-
always:
Strict-Transport-Security(a year, with subdomains),X-Content-Type-Options: nosniffandReferrer-Policy: strict-origin-when-cross-origin. TheServerheader is removed, and responses are compressed (zstd, gzip); -
only when the app sends none of its own:
X-Frame-Options: DENY, aPermissions-Policythat turns off camera, microphone, geolocation, payment and USB, andCross-Origin-Opener-Policy: same-origin. The app's own value wins.
The Content-Security-Policy is the app's. Until the analytics script stops being added to
pages (ADR 0043, in opt-out mode), that is the one
change to an app's HTML.
Users come from the instance's pool. Today they are all guests. This contract is Spotcraft's own
(ADR 0049): Spotpass
implements it, and its tests (the pool contract) check each part, so another pool can prove it
fits the same way.
HTTP, under AUTH_URL (<PUBLIC_URL>/_spotcraft/auth), same origin, with a first-party
session cookie:
| Call | What |
|---|---|
POST /sign-in/anonymous |
Makes a guest and starts a session: { "user": { "id", "isAnonymous": true } }, plus the cookie and a set-auth-token header for clients without cookies. 429 when an address makes too many. |
GET /get-session |
The signed-in user and session, or null. |
GET /token |
{ "token": "<JWT>" } for the session, from its cookie or Authorization: Bearer <session token>. 401 without one. |
GET /jwks |
The public keys tokens are signed with. |
GET /export |
Everything the pool holds about the signed-in user, as JSON, without tokens or hashes. 401 without a session. |
POST /delete-anonymous-user |
Deletes the signed-in guest, and with them their rows in every app. The session ends. |
Better Auth's client, with its anonymous plugin, speaks these calls, so it works with Spotpass as it is. That's a convenience: the table above is the contract.
- In the browser, the app's page makes these calls on its own origin.
-
Without the app's domain (an Expo app, a site not on Spotcraft yet), clients call
https://auth.<instance domain>/mainand sendAuthorization: Bearer <token>. -
On the server, the app asks the pool for a JWT for the session, or takes the bearer token,
and checks it:
- signed by a key from
AUTH_JWKS_URL(EdDSA); -
issequalsAUTH_ISSUER; - not expired.
- signed by a key from
-
Claims:
sub(the user id, a UUID, the same asauth.users.id),is_anonymous,iss,iat,exp. Tokens last 15 minutes.GET <AUTH_URL>/tokenreturns one for the session or bearer token it is sent. -
App data points at the user with a foreign key,
on delete cascadeoron delete set null. Deleting a user deletes their rows in every app. A key that blocks the delete is a bug. -
Deleting and exporting (ADR 0043):
- a guest deletes themselves with
POST <AUTH_URL>/delete-anonymous-user(same origin, with their session). Their rows in every app go with them, so an app needs no delete code; -
GET <AUTH_URL>/exportanswers what the pool holds about the signed-in user, as JSON. The app exports its own rows, and offers both.
- a guest deletes themselves with
- What the pool keeps: expired sessions are deleted daily; a session's IP address and user agent are cleared after 30 days unused; guests unused for 180 days are deleted. Deleted users' ids are kept 30 days, as long as backups, so a restore can delete them again.
- Logs: Spotcraft keeps no access logs. An app that logs a client's IP address keeps it no longer than 30 days, and says so in its privacy page.
Who runs the instance and what it does with personal data, as data
(ADR 0043), for an app's privacy policy and legal notice.
The owner sets their details once on the dashboard's Settings page; nothing goes into the app's
repository. A server reads LEGAL_FACTS; a client without one reads
<app URL>/_spotcraft/legal.json.
{
"version": 1,
"updated": "2026-11-21",
"controller": {
"name": "…",
"address": ["…", "…"],
"email": "privacy@…",
"authority": { "name": "…", "url": "https://…" }
},
"processing": [
{
"id": "hosting",
"basis": "contract",
"retentionDays": null,
"processor": { "name": "Hetzner Online GmbH", "country": "DE" }
},
{
"id": "edge",
"basis": "legitimate-interests",
"retentionDays": null,
"processor": { "name": "Cloudflare, Inc.", "country": "US" },
"transfer": { "country": "US", "basis": "dpf" }
},
{ "id": "accounts", "basis": "contract", "retentionDays": 180 },
{ "id": "sessions", "basis": "legitimate-interests", "retentionDays": 30 }
]
}-
updatedis when any fact last changed: the policy's "last changed" date. -
controlleris null until the owner fills in their details. -
processinglists only what the instance does. Eachidsays what data and why:hosting(everything the app stores and serves),edge(requests pass through Cloudflare),accounts(the pool's accounts and their data in apps),sessions(IP address and user agent, against abuse),backups(nightly copies),email(the mail the app sends, through the instance's provider) andanalytics(counts without cookies or ids). The words for them, translated, come with Spotstrap. -
basisis the GDPR Art. 6(1) legal basis:contract,legitimate-interestsorconsent.retentionDayscounts from last use, or forbackupsandanalyticsfrom when the backup or event was made; null when it isn't limited.processor.countryis a two-letter code,EU, or null when unknown.transfer.basisdpfis the EU–US Data Privacy Framework. - When the owner's details change, every site serves the new facts at once, and every app is
deployed again to get the new
LEGAL_FACTS. When the instance changes (backups turned on, another edge),legal.jsonfollows when the agent starts, andLEGAL_FACTSwith each app's next deploy. - The app writes, in its own page, what it stores itself.
- Outside Spotcraft, set
LEGAL_FACTSyourself, and serve the same JSON at that path.
Spotcraft counts how each app is used with Spotless, its tracker and collect endpoint, and Umami behind it to store and report the numbers (ADR 0038, ADR 0050). The contract below is Spotcraft's own: another store, or another collector, can stand in. Nothing goes to an outside service, and nothing collected holds an id, personal data or a cookie.
How visits are counted is the instance's choice (ANALYTICS_MODE,
ADR 0043), because consent rules differ between EU
countries:
-
opt-out, the default: the app loads the tracker, and offers a switch that turns it off. -
opt-in: the app asks the visitor first, and loads the tracker only after they agree. -
server: nothing runs in the browser, ands.jsandeanswer 404. Only requests and accounts are counted.
Events are kept ANALYTICS_DAYS, 395 by default, then deleted.
Spotcraft adds nothing to an app's pages. A web app that counts visits loads the tracker itself, the same in every mode:
-
Page views:
analytics()from@kodentuzo/spotkit/clientreadsconfig.jsonand adds<script defer src="/_spotcraft/s.js"></script>when the mode and the visitor allow it. The tracker counts a page view on load and on each history navigation. A CSP ofscript-src 'self'allows it. Spotstrap's analytics blocks are the switch (opt-out) and the prompt (opt-in). -
Events:
spotless.track(name, data)in the page, or spotkit'strack(). -
The visitor's opt-out: while
localStorage["spotless.disabled"]is"1", the tracker sends nothing. For one release it also honours Umami'sumami.disabled, and offerswindow.umami.track.
What needs no change to the app:
- Requests: requests, errors and latency per app, from Caddy.
- Accounts: new and active pool accounts per app, from the host each session was made or renewed on.
Clients without pages (Expo, Electron) use @kodentuzo/spotkit/client, or do the same by
hand:
-
GET <app URL>/_spotcraft/config.jsonanswers{ "analytics": { "enabled": true, "mode": "opt-out" } }. Withenabled: false, send nothing. Withmode: "opt-in", send nothing until the user agrees. (It also carrieswebsiteId, Umami's, for one more release; don't rely on it.) -
Screens and events go to
POST <app URL>/_spotcraft/eas JSON, with a User-Agent that names the platform. It answers 202:{ "type": "pageview", "path": "/levels?page=2", "referrer": "https://example.com/", "title": "Levels", "screen": "1280x800", "language": "en-GB" } { "type": "event", "path": "/play", "name": "solve", "data": { "level": 3 } }typeandpathare required, and an event needs aname(50 characters at most).dataholds up to 20 keys of strings (200 characters at most), numbers or booleans. Keys that could identify someone (id,userId,email,phone,tokenand the like) are refused with 400, as is a body over 8 KB. -
Requests to the pool may carry
Spotcraft-Client: <platform>/<version>, such asios/1.4.0: lowercase letters and dashes, a slash, then up to 32 characters of letters, digits and.+-. The pool keeps it on the session to count platforms and versions; anything else is ignored. -
A native app shows an opt-out, and sends nothing once it's off.
Analytics on or off is a setting per app, on by default. Off removes the script and makes
config.json say enabled: false. Use it for an app with a nonce-only CSP, or one that mustn't
count.
-
Health: a
HEALTHCHECKin the image. Without one, Spotcraft asks forGET /healthuntil it answers 2xx; a 404 counts too (the app answers, without that route). It waits 120 seconds. - Stop: finish within 30 seconds of SIGTERM.
-
Logs: to stdout, ideally JSON lines with
level,msgandtime.
A site that is only files gets the same contract on its domain, without a server of its own (ADR 0052). The guide is Static sites.
What a site ships: an image with its built files in /site, and nothing else.
FROM scratch
COPY dist /siteCI builds it for linux/amd64 and linux/arm64, pushes it, and calls the deploy hook with its
tag, like any app (Deploy from CI).
What Spotcraft runs: its own static server, Caddy from Spotcraft's image, with the site's files mounted read-only. The server's code is Spotcraft's, never the site's, and moves to each new Spotcraft version by itself. It:
- serves files with compression,
index.htmlfor a folder, and.htmlwithout the extension (/aboutservesabout.html); - caches assets with a content hash in their name (
app.3f9a1c2b.js) for a year, as immutable; - answers a path the site doesn't have with its fallback, the site's one setting:
-
404(the default): its404.html, with status 404; -
spa: itsindex.html, for an app that routes in the browser.
-
What a site gets, the same as an app:
- HTTPS at
<name>.<apps domain>, or its own domain withwww; - the headers. A site can't send headers of its own, so its CSP goes in a
<meta http-equiv="Content-Security-Policy">tag. A<meta>CSP can't setframe-ancestors; the platform'sX-Frame-Options: DENYkeeps the site out of frames instead; - the paths:
/_spotcraft/legal.json, analytics (config.json,s.js,e) and the user pool at/_spotcraft/auth/*. So spotkit'slegal(),analytics(),exportMe()anddeleteMe()all work from the browser.
What it doesn't get: environment variables, a schema, mail, migrations, or checks of tokens on a server. It has no process of its own.
Removal test: the /site folder runs on any static host. To keep its accounts and legal
pages there, serve the same /_spotcraft/* paths and a user pool yourself.
Published from docs/. Edit the files there; changes here are overwritten.