security: define a non-persistent production demo principal

[tiankaima]

Goal

Provide a production demo experience without a normal demo login entry and without creating demo User, Account, Session, enrollment, todo, or other business rows in PostgreSQL.

This is a security/product RFC before broad implementation.

Proposed boundary

• Enter through an explicit /demo bootstrap/direct link protected by rate limits and a kill switch; obscurity is not an authorization control.
• Mint a server-signed, short-lived DemoPrincipal that is not a Better Auth DB session and does not impersonate a user ID.
• Render deterministic fixture/read projections; demo courses/subscriptions/todos are not database rows.
• Intercept an allowlisted set of mutable commands before Prisma, R2, OAuth, webhooks, or public side effects. Return simulated: true rather than pretending persistence succeeded.
• Persist only privacy-safe structured audit events: allowlisted action/operation/tool, request ID, timestamp, and opaque demo-session hash. Never log bodies, tokens, or PII.
• Explicitly prohibit admin, OAuth client/consent/token, account linking/deletion, uploads, public comments/descriptions/homework, calendar feeds, and webhooks in v1.

Required decisions

• entrypoint and session TTL;
• read fixtures and mutable allowlist;
• whether short-lived simulated state is signed-cookie overlay or an isolated TTL store;
• audit sink, retention, alerting, and abuse limits;
• consistent simulated semantics for UI, REST/GraphQL, and MCP.

Draft PR target

After the RFC decisions, open a draft vertical slice covering principal + /demo + fixtures + central command gate for one feature and negative side-effect tests. Keep it draft until the threat model is accepted.

Acceptance criteria

• Demo requests cause zero business writes to DB/R2/OAuth/external systems; audit is the only allowed durable effect.
• No real user/FK/session exists and a cookie/email cannot be forged into demo mode.
• Simulated writes are visibly and machine-readably marked.
• Normal/authenticated/admin behavior is unchanged.
• Logs contain no sensitive values; kill switch and rate limits are tested.

[tiankaima]

2026-07-22 complete demo boundary (draft-only, production disabled)

The requested web login and API authorization can coexist with the original non-persistent requirement if demo identity is a separate authentication realm, not a Better Auth database user.

Identity and entry

• /demo is a real, explicit sign-in page available only when DEMO_MODE_ENABLED=true; the default and production configuration remain false and expose no navigation/login entry.
• Successful bootstrap mints a server-signed, short-lived demo session cookie. It contains an opaque session ID, issued/expiry times and kind=demo, never a real userId.
• API clients exchange that active demo session for a short-lived bearer token with a distinct audience/token kind and a strict demo scope allowlist. It must never be accepted as an OAuth/Better Auth access token. GraphQL and MCP use the same principal/scope representation after verification.

Data model

• No User, Session, Account, enrollment, todo, OAuth grant/token or other business row is created. Reads come from versioned deterministic fixtures.
• Optional temporary interaction state is a signed-cookie overlay with a small size/action cap in the first slice; if multi-device/state volume is later required, move only that ephemeral overlay to TTL KV. Do not use PostgreSQL business tables.
• The fixture version is embedded in the demo token/session so deployments can invalidate old state deterministically.

Mutation contract

• A central command gate runs after authentication/scope checks and before Prisma, R2, OAuth, webhooks or external adapters.
• Only explicitly allowlisted demo commands are simulated. Responses always include machine-readable simulated: true; REST uses a response field/header, GraphQL uses payload metadata/extensions, and MCP structured content carries the same marker.
• Non-allowlisted actions fail closed with a stable demo_operation_forbidden error. V1 excludes admin, user/OAuth management, uploads, public collaborative writes, account operations, calendar feed tokens and webhooks.
• “Immutable” means zero durable business/external effects, not silently returning normal success.

Audit and abuse controls

• The only durable effect is a privacy-safe audit event: allowlisted operation, result, request ID, timestamp, fixture version and keyed hash of the demo session. No request body, token, cookie, email, IP or fixture content.
• Add bootstrap/token rate limits, short TTL, audience separation, key rotation, per-session action caps and a global kill switch.

Draft PR acceptance

The first draft vertical slice should cover /demo, cookie principal, one fixture-backed read, one simulated Todo mutation, one demo API token, and negative tests proving zero Prisma/R2/OAuth/external calls. It stays draft and disabled in every checked-in production environment until the threat model and UX are accepted.

[tiankaima]

Alignment: keep scoped to draft PR #595. Recommend ephemeral session-only demo principal with read-only catalog access, no persistence, explicit env gate — document matrix before implementation.