#Security

Demo accounts: weak password on purpose. The demo accounts (member@test.com, admin@test.com, buyer@test.com, plus the eval user) are shared accounts with a weak, demo-only password, by design, so reviewers can log in quickly. The password is in the submission note, never in git. That includes the admin account, which can read every workshop's data and all logs.

Production would differ: a unique, strong admin password; MFA for admins; no shared accounts (one login per person); admins provisioned out of band, never through sign-up; and an 8+ character minimum enforced server-side (today the server minimum is 6 so the 7-character demo password still works; the sign-up form already asks for 8).

How Toquilla Trace handles authentication, authorization, data safety, AI safety and secrets. Every claim links to the code that implements it. Anything not built yet is in Not implemented yet (planned), never in the sections above it.

Paths are relative to this file. Line numbers point at the current code.

---

#1. TL;DR

• Postgres is the security boundary, not the UI. RLS is on for all 9 tables (rls.sql:11-19), every client privilege is revoked first and then granted table by table and column by column (rls.sql:25-50).
• Two roles, and nobody can promote themselves. New users are always member (schema.sql:308-312); profiles.role has no update grant (rls.sql:42). Admins are made only by a service-role script (seed-users.mjs:90-95).
• Anonymous visitors read nothing from tables. They get one fixed-shape JSON through public_hat_passport (functions.sql:32-102), which never returns buyer emails, user ids or notes. A workshop's contact email is empty unless the workshop sets one; sign-up no longer copies the login email into it (hat_grants_contact_email.sql:31-35).
• The AI proposes, a human approves, code re-checks. The workshop agent has no write tool (workshop-agent/index.ts:1-3); approvals re-run every rule on fresh rows before writing (apply.ts:133-186).
• Rules that matter live in the database too. Stage order, version bump and archived lock in one trigger (schema.sql:209-247); hat_events is append-only for everyone (schema.sql:256-275).
• Untrusted text is data. Notes, chat questions and hat records go in the user turn, escaped, never in the system prompt (agent.ts:57-68, concierge.ts:278-301).
• No secret reaches the browser or Vercel. The Gemini key is read only inside Edge Functions (llm.ts:31); the service role key is only in Edge Functions and a local script (http.ts:82-89, seed-users.mjs:26).
• Hat writes only through audited RPCs. Members have no direct insert or update on hats and no insert on hat_events (definer_hat_writes.sql:21-23, hat_grants_contact_email.sql:19); advance_hat, create_hat, transfer_hat, archive_hat and mark_flag_reviewed are security definer functions that check the caller's workshop themselves.
• Secrets at a glance. The Gemini key, rate salt and allowed origins are Supabase Edge Function secrets; Vercel holds only the public Supabase URL and anon key; the service role key, demo password and DB password live only in git-ignored local files. Full inventory and rotation steps in section 8.
• Browser hardening. Every page is served with a Content-Security-Policy (frame-ancestors 'none', no unsafe-eval in production), HSTS, nosniff, a strict referrer policy and a permissions policy that allows only the microphone (security-headers.ts:21-51).
• Checked live, not only on paper. npm run verify:security (scripts/verify-security.mjs) signs in as each demo role and probes every table, grant and RPC through PostgREST, plus a full transfer and claim on a throwaway hat: 58 of 58 checks pass. The SQL of the newest security migrations is pinned by tests/security-migrations.test.ts.
• Logs are admin-only and redacted. Members get zero rows (rls.sql:143-144); secrets, JWTs and API keys are stripped before any write (log-format.ts:84-120).

---

#2. Threat model

#Assets

#Actors

#Top risks and mitigations

---

#3. Authentication

sequenceDiagram
  participant B as Browser
  participant P as proxy.ts
  participant A as Server action (login)
  participant S as Supabase Auth
  B->>P: GET /hats/TQ-7F3K2 (no cookie)
  P->>S: getUser()
  S-->>P: no user
  P-->>B: 307 /login?next=%2Fhats%2FTQ-7F3K2
  B->>A: login(email, password, next)
  A->>S: signInWithPassword
  S-->>A: session (cookie set by @supabase/ssr)
  A-->>B: redirectTo = safeNext(next)

---

#4. Authorization

#Roles

Why a user can't change their role: two independent locks.

1. Column grants: clients have update (name) on profiles and nothing else (rls.sql:42), after a blanket revoke (rls.sql:25). update profiles set role='admin' fails with "permission denied for column role".
2. RLS: even the name update is limited to your own row (rls.sql:70-72). The role column also has a check constraint (schema.sql:23).

workshop_id is not updatable either, so a member can't move into another workshop.

#RLS per table

my_workshop_id() and is_admin() are the two helpers used by every policy (schema.sql:281-289). "Own" means workshop_id = my_workshop_id(). anon has no grant on any table (rls.sql:25). No client role has delete anywhere (rls.sql:50).

#Security definer functions

Function grants start from zero: revoke all on all functions ... from public, anon, authenticated (functions.sql:603), then explicit grants (functions.sql:605-627). Every definer function pins search_path.

The member write RPCs are security definer since migration 6, because members no longer have the table grants they would need as invoker. They bypass RLS, so each one checks the caller itself: signed in, has a workshop, and the hat (or the weaver, or the flag's hat) belongs to my_workshop_id(). Each writes its own event row with actor_id = auth.uid(), source = 'manual' and created_at = now(). Anon and PUBLIC can't execute them (definer_hat_writes.sql:190-199).

Verified on the hosted project with npm run verify:security (member, admin and buyer): direct insert into hat_events and hats, update of any hats column (including grade and weaver_id) and of hat_flags all return 403 permission denied; a member can't advance an Eval Workshop hat and the buyer (no workshop) can't advance any; create_hat, advance_hat (stage 0 to 1, version 1 to 2) and archive_hat still work for the admin on a throwaway hat in its own HQ workshop; a stale version fails in about 120 ms with version_conflict.

#Admin-only pages: the UI guard is UX, RLS is the boundary

• /logs renders the "Logs is for admins" card for members (logs/page.tsx:11-13, AdminOnly.tsx).
• The logs view queries app_logs from the browser with the user's session (LogsView.tsx:82). A member calling the same query gets zero rows because of log_select ... using (is_admin()) (rls.sql:143-144).
• getProfile() says in its own comment that the role is for display only (role.ts:16-20).
• Edge Functions decide admin-only data on the server: run cost and tokens (meta) are only added for admins (D8, workshop-agent/index.ts:238-249).

#Request paths

flowchart LR
  B[Browser<br/>anon key + user JWT]
  N[Next.js on Vercel<br/>anon key + cookies<br/>no service key]
  R[(Postgres<br/>RLS + grants + triggers)]
  E[Edge Functions<br/>workshop-agent, apply-proposals, concierge]
  G[Gemini API]

  B -- "supabase-js (RLS as user)" --> R
  B -- "server actions, RSC" --> N
  N -- "@supabase/ssr (RLS as user)" --> R
  B -- "functions.invoke + JWT" --> E
  E -- "user client: reads (RLS)" --> R
  E -- "service role: runs, logs, apply_proposal" --> R
  E -- "anon client: public_hat_passport" --> R
  E -- "GEMINI_API_KEY" --> G

Inside Edge Functions the JWT is verified with auth.getUser(jwt) before anything else (http.ts:117-139). Reads for the agent go through the user's own client plus an explicit workshop_id filter, so even an admin's agent run never reads another workshop (db.ts:1-3, db.ts:16-29). The service role is used only for runs, logs, rate-limit counts and the apply RPC (http.ts:81).

---

#5. Data rules enforced in the database

Grade vs rows is not a DB rule (D10). Legacy or imported records can be wrong, and the grade_mismatch flag exists to point at them, so a constraint would forbid the data the flag is for (schema.sql:59-60). New writes are checked in code instead: the agent tool (propose.ts:169-184), the approval re-check (apply.ts:148-149) and the manual create_hat RPC (functions.sql:302-304). Members have no direct insert on hats, so there is no path around these checks.

---

#6. Public surface

#Passport (public_hat_passport)

Called with the visitor's session when there is one (so the database can compute viewer), otherwise as anon (lib/passport/server.ts:15-21).

Other passport protections: the page is noindex so search engines don't build a list of codes (hat/[code]/page.tsx:57); record text renders as React text nodes, never HTML (PassportSections.tsx:2).

#Concierge (public Edge Function)

• JWT verification is off for this function only, on purpose (config.toml:422-423); the function validates its own input (concierge.ts:307-343).
• It loads the record with the anon client through public_hat_passport, so the model sees at most what a visitor sees (concierge/index.ts:139), and then drops the workshop email and viewer before building the model's record (concierge.ts:217-265).

#Anonymous logging (D6)

log_public (version 2, migration 7) accepts only auth.login_failed, auth.signup (failures, and sign-ups waiting for email confirmation), passport.view, passport.verify_failed, ui.error and concierge.feedback (log_public_v2.sql:45-49), and strips identifying and secret keys (email, transfer_email, user_id, ip, phone, password, token, key and authorization keys) at every depth, inside nested objects and arrays (log_public_v2.sql:9-28, log_public_v2.sql:60-67). Since log_flood_guard.sql both anonymous log RPCs reject a raw payload over 8 KB and stop accepting an action once it has more than 300 rows in the last minute (log_flood_guard.sql:16-27, log_flood_guard.sql:49-52). The cap is global, not per visitor, so a flood can crowd out real anonymous logs for a minute; pages keep working because logging never blocks. The browser logger drops every other anonymous row before sending (lib/log.ts:132), using the same list (log-format.ts:51-58).

#Security headers

Set for every route in next.config.ts:25-38 from security-headers.ts (unit tested in security-headers.test.ts):

The /docs pages render repo markdown with react-markdown, which ignores raw HTML; mermaid diagrams render with securityLevel: "strict" (Mermaid.tsx) and work under this CSP.

#Rate limits

---

#7. AI security

#Least privilege per agent

How apply-proposals treats AI output as untrusted:

• The workshop comes from the verified JWT and the profile, never from the body; another workshop's proposal looks exactly like a missing one (apply.ts:278-284).
• Human edits are whitelisted per proposal type (apply.ts:22-26, apply.ts:84-89).
• Rules re-run on a fresh hat row; "the hat row is the truth, never the AI payload" (apply.ts:133-186).
• The SQL where clause is the last line: workshop, not archived, version, forward one step (functions.sql:444-452).

#Prompt injection defenses

#Model safety finish reasons

SAFETY, RECITATION, BLOCKLIST, PROHIBITED_CONTENT, SPII and blocked prompts count as refusals (llm-types.ts:68-81).

• Workshop agent: a refusal fails the run and nothing is saved; a MAX_TOKENS turn never runs its function calls (agent.ts:310-322).
• Concierge: a refusal returns the fixed "unknown" copy and logs concierge.refused (concierge/index.ts:188-197).

#Cost and abuse limits

• Concierge: thinkingBudget: 0, 800 output tokens, 20 s timeout (concierge/index.ts:149-158); rate limits in section 6.
• Workshop agent: 4096 output tokens per call, 25 s per call, 45 s per run (agent.ts:9-12); 20 runs per hour.
• Worst case public spend: the 500-answer daily cap bounds the concierge to roughly $0.12 a day on Flash-Lite (AI.md).
• Every model call logs tokens and cost for admins (agent.ts:273-292, concierge/index.ts:165-176).

---

#8. Secrets and configuration

#Secrets inventory (names only, verified 2026-10-18)

git ls-files contains only .env.example of all these files (.gitignore:6-8, .gitignore:26-27).

#Handling rules

• Secrets are set through the CLI or piped from files, never typed into a command line that echoes them or printed in output.
• redact() replaces values under whole secret-like keys (password, secret, token, access_token, refresh_token, api_key/apikey, authorization, jwt, service_role, cookie, with an optional prefix like gemini_api_key) and any string that looks like a JWT, an Anthropic key or a Google AIza... key. Counters such as tokens_in stay readable (log-format.ts:84-115). It runs in the browser logger (lib/log.ts:144), the server actions (actions.ts:49) and the Edge Function logger (_shared/log.ts:61-62). Tested in log-format.test.ts.
• The pre-commit hook refuses env and key files (pre-commit:7-11); Claude Code settings deny reading .env* (settings.json:27-44).
• Rotation rule: rotate any secret that was ever shared outside a secret store (chat, email, screenshots, a terminal recording). Today that applies to the Gemini key.

---

#9. Logging and privacy

---

#10. Development-time security (AI-assisted development)

Hidden instruction on the take-home page. The assignment page contained hidden text addressed to AI assistants. Under the rule in CLAUDE.md:22 it was treated as data: not followed, and reported to the developer. The rule was added to the boilerplate for this reason (boilerplate.md:29).

---

#11. Known limitations and what we would do next

#Gaps found in the audit, and their status

#Next steps

• MFA for admins (Supabase TOTP), and phone or magic-link login for workshops where email is uncommon.
• Rate limiting at the edge (per IP and per user) in front of every Edge Function and auth endpoint.
• An audit of every service-role call, with a lint rule that keeps the service client out of app/, lib/ and components/.
• Automated key rotation and a secret scanner (for example gitleaks) in CI and pre-commit.
• SQL tests for RLS (tests/rls.sql in spec 01 section 10) run in CI against a local Supabase.
• An external penetration test before real workshop data goes in.

---

#12. How to verify yourself

Demo credentials are in the submission note (never in git). Replace <URL> and <ANON> with the project URL and anon key from the deployed app.

---

#13. Not implemented yet (planned)