Heimdall/src/store/schema.ts
Meta Vens 7be541467d Schema check: a key is a unique index on its columns, primary or not
The store's ON CONFLICT clauses and the foreign keys need a unique,
non-partial index on exactly the key's columns; whether it is the primary
key changes nothing a request does. Requiring the primary flag added a
refusal no failing request motivated, so it is dropped.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-30 17:16:21 +02:00

220 lines
7.9 KiB
TypeScript

export const CREATE_SCHEMA_SQL = `
-- Runtime app registration (POST /v1/apps) minted a client_secret_hash that
-- nothing ever verified, and the registered_apps table it fed was
-- unreachable dead code even after that writer was deleted: every HTTP route
-- already enumerates the four built-in app slugs in its own JSON schema, so a
-- registered row could never be resolved from a request (R21.3). Drop the
-- table on any store built before this schema too.
DROP TABLE IF EXISTS registered_apps;
CREATE TABLE IF NOT EXISTS accounts (
id TEXT PRIMARY KEY,
created_at TIMESTAMPTZ NOT NULL,
last_seen_at TIMESTAMPTZ NOT NULL,
display_name TEXT,
primary_email TEXT
);
CREATE TABLE IF NOT EXISTS linked_identities (
id TEXT PRIMARY KEY,
account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
provider TEXT NOT NULL,
provider_user_id TEXT NOT NULL,
username TEXT,
display_name TEXT,
primary_email TEXT,
access_token_encrypted TEXT,
refresh_token_encrypted TEXT,
token_expires_at TIMESTAMPTZ,
scopes TEXT NOT NULL DEFAULT '',
profile_json JSONB NOT NULL DEFAULT '{}'::jsonb,
created_at TIMESTAMPTZ NOT NULL,
updated_at TIMESTAMPTZ NOT NULL,
UNIQUE(provider, provider_user_id)
);
CREATE INDEX IF NOT EXISTS linked_identities_account_id_idx
ON linked_identities(account_id);
CREATE TABLE IF NOT EXISTS sessions (
id TEXT PRIMARY KEY,
account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
app_slug TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL,
last_seen_at TIMESTAMPTZ NOT NULL,
expires_at TIMESTAMPTZ NOT NULL,
claims_json JSONB NOT NULL,
access_revision INTEGER NOT NULL
);
CREATE INDEX IF NOT EXISTS sessions_account_id_idx
ON sessions(account_id);
CREATE TABLE IF NOT EXISTS auth_attempts (
handle TEXT PRIMARY KEY,
app_slug TEXT NOT NULL,
provider TEXT NOT NULL,
mode TEXT NOT NULL,
return_to TEXT NOT NULL,
status TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL,
expires_at TIMESTAMPTZ NOT NULL,
completed_at TIMESTAMPTZ,
consumed_at TIMESTAMPTZ,
denial_code TEXT
);
CREATE INDEX IF NOT EXISTS auth_attempts_lookup_idx
ON auth_attempts(app_slug, expires_at, status);
CREATE TABLE IF NOT EXISTS private_command_receipts (
app_slug TEXT NOT NULL,
idempotency_key TEXT NOT NULL,
request_fingerprint TEXT NOT NULL,
status TEXT NOT NULL,
content_schema TEXT NOT NULL,
envelope_base64 TEXT NOT NULL,
created_at TIMESTAMPTZ NOT NULL,
expires_at TIMESTAMPTZ NOT NULL,
PRIMARY KEY (app_slug, idempotency_key)
);
CREATE INDEX IF NOT EXISTS private_command_receipts_expiry_idx
ON private_command_receipts(expires_at);
CREATE TABLE IF NOT EXISTS auth_completions (
code TEXT PRIMARY KEY,
app_slug TEXT NOT NULL,
provider TEXT NOT NULL,
mode TEXT NOT NULL,
account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
session_id TEXT NOT NULL REFERENCES sessions(id) ON DELETE CASCADE,
return_to TEXT NOT NULL,
payload_json JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL,
expires_at TIMESTAMPTZ NOT NULL,
consumed_at TIMESTAMPTZ
);
CREATE INDEX IF NOT EXISTS auth_completions_lookup_idx
ON auth_completions(app_slug, expires_at, consumed_at);
-- Correlation handle for the browser_completion handoff. Before the
-- caller-identity cut, the completion code itself was the caller-chosen
-- attemptId (an unauthenticated account-takeover primitive); the code is now
-- always minted by the store, and attempt_id lets the private command plane
-- redeem the completion it created without ever needing the code.
ALTER TABLE auth_completions ADD COLUMN IF NOT EXISTS attempt_id TEXT;
-- One attempt handle may bind at most one unconsumed completion (R21.1): a
-- second completion for the same handle would let the by-attempt UPDATE in
-- consumeAuthCompletionByAttempt match more than one row, silently consuming
-- and discarding all but the one it returns. The predicate is partial rather
-- than a plain UNIQUE(app_slug, attempt_id) because a NULL attempt_id (no
-- correlation handle) and a *consumed*, already-settled completion must not
-- collide with a later one.
DROP INDEX IF EXISTS auth_completions_attempt_idx;
CREATE UNIQUE INDEX IF NOT EXISTS auth_completions_attempt_unconsumed_unique_idx
ON auth_completions(app_slug, attempt_id)
WHERE attempt_id IS NOT NULL AND consumed_at IS NULL;
CREATE TABLE IF NOT EXISTS capability_grants (
id TEXT PRIMARY KEY,
account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
scope_type TEXT NOT NULL,
scope_id TEXT,
capability TEXT NOT NULL,
source TEXT NOT NULL,
status TEXT NOT NULL,
expires_at TIMESTAMPTZ,
note TEXT,
created_at TIMESTAMPTZ NOT NULL,
updated_at TIMESTAMPTZ NOT NULL
);
CREATE INDEX IF NOT EXISTS capability_grants_lookup_idx
ON capability_grants(account_id, scope_type, scope_id, status);
CREATE TABLE IF NOT EXISTS entitlement_snapshots (
id TEXT PRIMARY KEY,
account_id TEXT NOT NULL REFERENCES accounts(id) ON DELETE CASCADE,
provider TEXT NOT NULL,
scope TEXT NOT NULL,
evaluated_at TIMESTAMPTZ NOT NULL,
is_allowed BOOLEAN NOT NULL,
reason_code TEXT NOT NULL,
reason_detail TEXT,
raw_summary_json JSONB NOT NULL,
UNIQUE(account_id, provider, scope)
);
CREATE TABLE IF NOT EXISTS audit_events (
id TEXT PRIMARY KEY,
account_id TEXT,
session_id TEXT,
app_slug TEXT,
event_type TEXT NOT NULL,
event_payload_json JSONB NOT NULL,
created_at TIMESTAMPTZ NOT NULL
);
CREATE INDEX IF NOT EXISTS audit_events_lookup_idx
ON audit_events(account_id, session_id, app_slug, created_at);
`;
const schemaText = CREATE_SCHEMA_SQL.replace(/\r\n/g, "\n");
const createdTables = [...schemaText.matchAll(/^CREATE TABLE IF NOT EXISTS (\w+) \(\n([\s\S]*?)\n\);/gm)].map((match) => ({
table: match[1]!,
lines: match[2]!.split("\n").map((line) => line.trim().replace(/,$/, "")),
}));
/** The sorted, comma-separated columns of a `PRIMARY KEY (a, b)` or `UNIQUE(a, b)` line. */
function keyColumns(line: string, keyword: "PRIMARY KEY" | "UNIQUE"): string | undefined {
const match = new RegExp(`^${keyword}\\s*\\(([^)]*)\\)`).exec(line);
return match ? match[1]!.split(",").map((column) => column.trim()).sort().join(",") : undefined;
}
/*
* What every start must find before it serves, read from the SQL above so the
* two cannot drift. A start that applies the schema checks as well, because
* CREATE ... IF NOT EXISTS leaves a damaged table as it is.
*/
/** Every table and index the schema creates. */
export const REQUIRED_RELATIONS = [
...schemaText.matchAll(/^CREATE (?:UNIQUE )?(?:TABLE|INDEX) IF NOT EXISTS (\w+)/gm),
].map((match) => match[1]!);
/** Every table the schema creates. The store reads and writes each one. */
export const REQUIRED_TABLES = createdTables.map(({ table }) => table);
/** What the store does to its tables: it reads, inserts and updates, and never deletes. */
export const REQUIRED_TABLE_PRIVILEGES = ["SELECT", "INSERT", "UPDATE"];
/** Every column a created table declares, and every column the schema adds to an existing table. */
export const REQUIRED_COLUMNS = [
...createdTables.flatMap(({ table, lines }) =>
lines
.filter((line) => !/^(?:PRIMARY KEY|UNIQUE)\b/.test(line))
.map((line) => ({ table, column: /^(\w+)/.exec(line)![1]! }))
),
...[...schemaText.matchAll(/^ALTER TABLE (\w+) ADD COLUMN IF NOT EXISTS (\w+)/gm)].map((match) => ({
table: match[1]!,
column: match[2]!,
})),
];
/**
* Every primary key and unique constraint a created table declares, by its
* sorted columns. Each must stand as a unique, non-partial index on exactly
* those columns: the store's ON CONFLICT clauses and the foreign keys need
* nothing more, and without it every such write fails.
*/
export const REQUIRED_KEYS = createdTables.flatMap(({ table, lines }) =>
lines.flatMap((line) => {
const columns =
/^(\w+) .*\bPRIMARY KEY\b/.exec(line)?.[1] ?? keyColumns(line, "PRIMARY KEY") ?? keyColumns(line, "UNIQUE");
return columns ? [{ table, columns }] : [];
})
);