Owner-scoping the run stores — a code-level reading (PR #348, closes #215)

Overview

Two endpoints — POST /api/run-save and POST /api/run-draft — take a run's UUID straight from the request body and hand it to a store that upserts on the run_id primary key, stamping the caller as owner. The Supabase service key bypasses row-level security, so the run id was the only thing the database checked. A leaked run id (server logs, x-run-id telemetry, a shared device) let any player overwrite another's saved run — hijacking the public /r/:token that still pointed at it — or wipe their resume draft.

The fix splits every write into a first-writer INSERT and an owner-scoped UPDATE, so an existing row is only ever overwritten by the subject who owns it. A different subject is refused with a typed error the API maps to a clean 403. Below: the guard, both stores, the edge, and the tests that only the fix passes.

Why the database won't catch this

The stores connect with the service (secret) key, and these tables carry no RLS policy — server-only by design. That's a deliberate choice, but it means there is no database-level owner check behind the app. A new typed error names the condition the store now guards against, so the API layer can tell a forbidden action apart from a real fault.

server/utils/run-ownership.ts · 18 lines

server/utils/run-ownership.ts18 lines · TypeScript

1/**
* Raised when a run write targets a run owned by a DIFFERENT subject — the cross-subject
* overwrite guard (#215). The store rejects the write and never touches the owner's row;
* the API layer maps it to a 403 (a forbidden action, not a server fault).
*
* Why this guard has to exist: both run stores (snapshots + drafts) key their durable row
* on the run id ALONE, and they write with the Supabase service key, which bypasses RLS.
* So the row-id is the only thing the database checks — without an owner check in the app,
* a leaked run id would let any subject overwrite another player's saved run (hijacking the
* public share URL that still points at it) or wipe their resume draft. This error is how a
* store signals "that run isn't yours" so the write is refused, fail-safe.
*/
13export class RunOwnershipError extends Error {
constructor(runId: string) {
  super(`run ${runId} is owned by another subject`);
  this.name = "RunOwnershipError";
}
18}

The snapshot store: insert-if-new, else owner-scoped update

The in-memory adapter used to reassign existing.subject = subject outright — the hijack in one line. It now refuses a mismatched owner (lines 185–186). The Supabase adapter can't read-then-write safely, so it does the same guard race-safely in two statements: a first-writer INSERT (ON CONFLICT DO NOTHING) claims an unseen id; if the row already exists, an UPDATE scoped to run_id and user_id handles it — matching zero rows for anyone but the owner.

server/utils/run-snapshot-store.ts · 603 lines

server/utils/run-snapshot-store.ts603 lines · TypeScript

⋯ 177 lines hidden (lines 1–177)1/**
* The run-snapshot store — where a finished run becomes a durable, owned record.
* POST /api/run-save writes the snapshot here keyed by the run id; the "your runs"
* routes (GET /api/runs, GET /api/runs/:id) read it back, scoped to the account
* subject so a player only ever sees their own runs.
*
* Two adapters behind one port, chosen by config — the repo's env-degradation idiom
* (cf. runStore, balanceStore):
*   - in-memory (default): no external dependency, so `npm run dev` and the unit
*     tests need nothing. History doesn't outlive the process, but the round-trip is
*     real, which is what the save -> list -> load test exercises.
*   - Supabase: used when SUPABASE_URL + SUPABASE_SECRET_KEY are configured. Writes
*     the `run_snapshots` row (and stamps the owner onto the billing `runs` row) via
*     the service (secret) key, which bypasses RLS — the table has no public policy,
*     so it is server-only.
*
* Ownership is by SUBJECT (the Supabase user id, falling back to the device id) — the
* same string balances/runs key on. Reads filter by it, so a non-owned run id reads
* as absent (the route turns that into a 404, never leaking another subject's run).
*/
21import { randomUUID } from "node:crypto";
22import { createClient, type SupabaseClient } from "@supabase/supabase-js";
23import { supabaseConfig } from "./supabase";
24import { RunOwnershipError } from "./run-ownership";
25import { migrateSnapshot } from "~/utils/run-snapshot";
26import type {
RunSnapshot,
RunSummary,
PublicRun,
ShareState,
RemixCredit,
32} from "~/utils/run-snapshot";
33 
34/** Save-time extras the snapshot blob itself doesn't carry. */
35export interface SaveRunOptions {
/** When this run is a replay (issue #89), the SOURCE run's share token — resolved
 *  server-side to the parent's stable run id and stamped as the lineage pointer. The
 *  client only ever holds the public token (the run id is never exposed to it). */
derivedFromToken?: string | null;
40}
41 
42export interface RunSnapshotStore {
/** Persist (or overwrite) the finished run's snapshot, owned by `subject`. */
saveRun(
  subject: string,
  snapshot: RunSnapshot,
  opts?: SaveRunOptions,
): Promise<void>;
/** A subject's saved runs, newest first (the list projection). */
listRuns(subject: string): Promise<RunSummary[]>;
/** Total shared runs (share_token set) across all accounts — the viral top of
 *  funnel. A global operator dashboard read. */
sharedRunCount(): Promise<number>;
/** One saved run by id, only if `subject` owns it; null otherwise. */
getRun(subject: string, runId: string): Promise<RunSnapshot | null>;
/**
 * Make an owned run public (issue #88): mint a share token if it has none (reuse it
 * if already shared, so the URL is stable), set the attribution name, and return the
 * live share state. Null when `subject` doesn't own the run (reads as absent).
 *
 * `name` is the account's GENERATED username when the owner opts into attribution, or
 * null for anonymous (issue #117). It is server-resolved — never client-typed — so the
 * old self-chosen-handle abuse surface is gone; the store just persists the string it's
 * handed.
 */
shareRun(
  subject: string,
  runId: string,
  name: string | null,
): Promise<ShareState | null>;
/**
 * Re-stamp the attribution name on every one of `subject`'s ALREADY-attributed shares
 * (issue #117). Called after a reroll so a player's public handle stays consistent
 * across all their shared runs — the username is an account property, so changing it
 * follows everywhere it appears. Anonymous shares (name null) are left untouched.
 */
syncAttributedShares(subject: string, username: string): Promise<void>;
/** Revoke an owned run's share (clear token + name). Idempotent; a no-op otherwise. */
unshareRun(subject: string, runId: string): Promise<void>;
/** The owner's view of a run's share status; null when `subject` doesn't own it. */
getShareState(subject: string, runId: string): Promise<ShareState | null>;
/** Resolve a public share token to its sanitized projection; null when unknown. */
getPublicRun(token: string): Promise<PublicRun | null>;
/** Resolve a share token to its run's OWNER subject — server-internal only (the
 *  referral attribution key, issue #96). Never crosses to a client; the public
 *  projection above is the only thing a viewer ever sees. Null when the token is
 *  unknown / revoked. */
ownerSubjectByToken(token: string): Promise<string | null>;
89}
90 
91/** Project a snapshot down to the list row. */
92function toSummary(snapshot: RunSnapshot, createdAt: string): RunSummary {
return {
  runId: snapshot.runId,
  status: snapshot.status,
  title: snapshot.objective.title,
  progress: snapshot.objectiveProgress,
  createdAt,
};
100}
101 
102/**
* Project a stored snapshot down to its PUBLIC, shareable form. The snapshot blob is
* already identity-free (the owner lives only in the row's `user_id` column, never in
* the data), so the sanitization here is deliberate-and-explicit: blank the run id (the
* share token is the only handle a public viewer gets) and surface only the opt-in
* display name. This is the boundary the public endpoint serves — never the raw row.
*/
109export function toPublicRun(
snapshot: RunSnapshot,
name: string | null,
remixedFrom: RemixCredit | null = null,
113): PublicRun {
const trimmed = name?.trim();
// Normalize the stored blob to the current shape (an older snapshot may predate a
// field, e.g. v2's peakProgress) before it crosses to the public viewer.
const run = migrateSnapshot(snapshot);
return {
  run: { ...run, runId: "" },
  attribution: trimmed ? trimmed : null,
  remixedFrom,
};
123}
124 
125/**
* Build the one-hop "remixed from" credit (issue #89) from the PARENT run's live fields.
* Only public, opt-in data crosses: the parent's display name (anonymous if blank/unset),
* its objective title, and its current share token (for an optional backlink, null when
* the parent is no longer shared). Never the parent's run id, owner, or device.
*/
131function toRemixCredit(
parent: {
  title: string;
  shareName: string | null;
  shareToken: string | null;
} | null,
137): RemixCredit | null {
if (!parent) return null;
const name = parent.shareName?.trim();
return {
  attribution: name ? name : null,
  objectiveTitle: parent.title,
  sourceToken: parent.shareToken ?? null,
};
145}
146 
147/** Dev/test default — keeps the round-trip real (save -> list -> load) without any
*  external dependency. Not durable across process restarts; the Supabase adapter is
*  the one that actually preserves history. */
150export class InMemoryRunSnapshotStore implements RunSnapshotStore {
private readonly runs: Array<{
  subject: string;
  snapshot: RunSnapshot;
  createdAt: string;
  shareToken: string | null;
  shareName: string | null;
  derivedFromRunId: string | null;
}> = [];
159 
/** Resolve a source share token to the parent's stable run id (issue #89), guarding
 *  self-derivation. Returns null for an unknown token or no token. */
private resolveDerivedRunId(
  token: string | null | undefined,
  selfRunId: string,
): string | null {
  if (!token) return null;
  const parent = this.runs.find((r) => r.shareToken === token);
  return parent && parent.snapshot.runId !== selfRunId
    ? parent.snapshot.runId
    : null;
}
172 
async saveRun(
  subject: string,
  snapshot: RunSnapshot,
  opts?: SaveRunOptions,
): Promise<void> {
  const createdAt = new Date().toISOString();
  const existing = this.runs.find((r) => r.snapshot.runId === snapshot.runId);
  if (existing) {
    // Snapshots are immutable, but the save fires again once the epilogue lands — the
    // OWNER overwrites in place (keep the original position/createdAt, and any share
    // already minted for this run). Owner-scoped (#215): a DIFFERENT subject holding
    // this run id is refused, never allowed to reassign or overwrite another's run.
    if (existing.subject !== subject)
      throw new RunOwnershipError(snapshot.runId);
    existing.snapshot = snapshot;
    // Stamp the pointer only on a SUCCESSFUL resolve, and never overwrite one
    // already set with null: it's stable once stamped, so a later un-share (the
    // token stops resolving) leaves the lineage intact — only the walked credit
    // goes anonymous (see getPublicRun).
    const resolved = this.resolveDerivedRunId(
      opts?.derivedFromToken,
      snapshot.runId,
    );
⋯ 136 lines hidden (lines 196–331)196      if (resolved) existing.derivedFromRunId = resolved;
    return;
  }
  this.runs.push({
    subject,
    snapshot,
    createdAt,
    shareToken: null,
    shareName: null,
    derivedFromRunId: this.resolveDerivedRunId(
      opts?.derivedFromToken,
      snapshot.runId,
    ),
  });
}
211 
async sharedRunCount(): Promise<number> {
  return this.runs.filter((r) => r.shareToken != null).length;
}
215 
async listRuns(subject: string): Promise<RunSummary[]> {
  return this.runs
    .filter((r) => r.subject === subject)
    .map((r) => toSummary(r.snapshot, r.createdAt))
    .reverse();
}
222 
async getRun(subject: string, runId: string): Promise<RunSnapshot | null> {
  const found = this.runs.find(
    (r) => r.snapshot.runId === runId && r.subject === subject,
  );
  return found ? migrateSnapshot(found.snapshot) : null;
}
229 
async shareRun(
  subject: string,
  runId: string,
  name: string | null,
): Promise<ShareState | null> {
  const found = this.runs.find(
    (r) => r.snapshot.runId === runId && r.subject === subject,
  );
  if (!found) return null;
  found.shareToken = found.shareToken ?? randomUUID();
  found.shareName = name;
  return { token: found.shareToken, name: found.shareName };
}
243 
async syncAttributedShares(subject: string, username: string): Promise<void> {
  for (const run of this.runs) {
    // Only the subject's already-attributed shares (a name set); anonymous ones
    // (null) stay anonymous — a reroll never opts a private share into attribution.
    if (run.subject === subject && run.shareName !== null)
      run.shareName = username;
  }
}
252 
async unshareRun(subject: string, runId: string): Promise<void> {
  const found = this.runs.find(
    (r) => r.snapshot.runId === runId && r.subject === subject,
  );
  if (!found) return;
  found.shareToken = null;
  found.shareName = null;
}
261 
async getShareState(
  subject: string,
  runId: string,
): Promise<ShareState | null> {
  const found = this.runs.find(
    (r) => r.snapshot.runId === runId && r.subject === subject,
  );
  return found ? { token: found.shareToken, name: found.shareName } : null;
}
271 
async getPublicRun(token: string): Promise<PublicRun | null> {
  const found = this.runs.find((r) => r.shareToken === token);
  if (!found) return null;
  // Walk one hop to the parent's LIVE row for the "remixed from" credit (issue #89),
  // so the source's current opt-in (name / still-shared) is what surfaces.
  const parent = found.derivedFromRunId
    ? (this.runs.find((r) => r.snapshot.runId === found.derivedFromRunId) ??
      null)
    : null;
  const remixedFrom = toRemixCredit(
    parent
      ? {
          title: parent.snapshot.objective.title,
          shareName: parent.shareName,
          shareToken: parent.shareToken,
        }
      : null,
  );
  return toPublicRun(found.snapshot, found.shareName, remixedFrom);
}
292 
async ownerSubjectByToken(token: string): Promise<string | null> {
  const found = this.runs.find((r) => r.shareToken === token);
  return found ? found.subject : null;
}
297}
298 
299/** Records each saved run as a `run_snapshots` row via the service (secret) key,
*  which bypasses RLS — the table has no public policy, so it is server-only. */
301export class SupabaseRunSnapshotStore implements RunSnapshotStore {
constructor(private readonly client: SupabaseClient) {}
303 
async saveRun(
  subject: string,
  snapshot: RunSnapshot,
  opts?: SaveRunOptions,
): Promise<void> {
  const row: Record<string, unknown> = {
    run_id: snapshot.runId,
    user_id: subject,
    version: snapshot.version,
    status: snapshot.status,
    title: snapshot.objective.title,
    progress: snapshot.objectiveProgress,
    data: snapshot,
  };
  // Stamp the lineage pointer ONLY for a replay (issue #89): resolve the source's
  // public share token to the parent's STABLE run id (a token can be revoked / re-
  // minted; the id can't), guarding self-derivation. The column is set only on a
  // SUCCESSFUL resolve and is NEVER written as null — so an ordinary run carries no
  // pointer, and a replay whose source un-shares before the run ends keeps the pointer
  // an earlier save stamped (the credit then walks to an anonymized parent).
  if (opts?.derivedFromToken) {
    const parentId = await this.resolveDerivedRunId(opts.derivedFromToken);
    if (parentId && parentId !== snapshot.runId)
      row.derived_from_run_id = parentId;
  }
329 
  // Owner-scoped write (#215). The row is keyed on the run id ALONE and the service key
  // bypasses RLS, so a bare upsert would let any subject holding a leaked run id
  // overwrite another player's snapshot — reassigning its owner and hijacking the public
  // share URL that still points at it. Split the upsert into two guarded halves.
  //
  // First-writer INSERT (ON CONFLICT DO NOTHING): claims an unseen run id. A returned
  // row means we created it — nothing to guard, we own it.
  const inserted = await this.client
    .from("run_snapshots")
    .upsert(row, { onConflict: "run_id", ignoreDuplicates: true })
    .select("run_id");
  if (inserted.error)
    throw new Error(`run_snapshots insert failed: ${inserted.error.message}`);
343 
  if (!inserted.data?.length) {
    // The run id already exists — overwrite it ONLY if this subject owns it (the
    // legitimate post-epilogue re-save). Scoped to run_id + user_id, so a DIFFERENT
    // subject matches no row: the write is refused and the owner's snapshot is left
    // untouched. The SET carries the mutable snapshot columns only — never user_id /
    // run_id (the identity) and never share_token / share_name, so a re-save preserves
    // the live share exactly as before.
    const update: Record<string, unknown> = {
      version: snapshot.version,
      status: snapshot.status,
      title: snapshot.objective.title,
      progress: snapshot.objectiveProgress,
      data: snapshot,
    };
    if (row.derived_from_run_id)
      update.derived_from_run_id = row.derived_from_run_id;
    const { data, error } = await this.client
      .from("run_snapshots")
      .update(update)
      .eq("run_id", snapshot.runId)
      .eq("user_id", subject)
      .select("run_id");
    if (error)
      throw new Error(`run_snapshots update failed: ${error.message}`);
    if (!data?.length) throw new RunOwnershipError(snapshot.runId);
  }
370 
  // Stamp the owner onto the billing run row too (it otherwise carries only device_id),
  // FIRST-WRITER only (`user_id IS NULL`) so it becomes a durable audit fact rather than
  // a write-only field a later save could flip. Only ever reached by the legitimate
  // owner — the snapshot write above already refused any cross-subject caller.
  const owned = await this.client
    .from("runs")
    .update({ user_id: subject })
    .eq("id", snapshot.runId)
    .is("user_id", null);
  if (owned.error)
⋯ 223 lines hidden (lines 381–603)381      throw new Error(`runs owner update failed: ${owned.error.message}`);
}
383 
async sharedRunCount(): Promise<number> {
  // Head-count of shared runs (share_token set) — service-key read, all accounts.
  const { count, error } = await this.client
    .from("run_snapshots")
    .select("*", { count: "exact", head: true })
    .not("share_token", "is", null);
  if (error) throw new Error(`shared run count failed: ${error.message}`);
  return count ?? 0;
}
393 
/** Resolve a source share token to the parent's stable run id (issue #89); null when
 *  the token is unknown / revoked. */
private async resolveDerivedRunId(token: string): Promise<string | null> {
  const { data, error } = await this.client
    .from("run_snapshots")
    .select("run_id")
    .eq("share_token", token)
    .maybeSingle();
  if (error)
    throw new Error(`run_snapshots lineage resolve failed: ${error.message}`);
  return (data?.run_id as string | null) ?? null;
}
406 
/** Walk one hop to the parent's LIVE row for the "remixed from" credit (issue #89) —
 *  its current title, opt-in name, and share token. Null when there's no parent (not
 *  a replay) or the parent has since been deleted. */
private async resolveRemixCredit(
  parentRunId: string | null,
): Promise<RemixCredit | null> {
  if (!parentRunId) return null;
  const { data, error } = await this.client
    .from("run_snapshots")
    .select("title, share_name, share_token")
    .eq("run_id", parentRunId)
    .maybeSingle();
  if (error)
    throw new Error(`run_snapshots remix credit failed: ${error.message}`);
  if (!data) return null;
  return toRemixCredit({
    title: data.title as string,
    shareName: (data.share_name as string | null) ?? null,
    shareToken: (data.share_token as string | null) ?? null,
  });
}
428 
async listRuns(subject: string): Promise<RunSummary[]> {
  const { data, error } = await this.client
    .from("run_snapshots")
    .select("run_id, status, title, progress, created_at")
    .eq("user_id", subject)
    .order("created_at", { ascending: false });
  if (error) throw new Error(`run_snapshots list failed: ${error.message}`);
  return (
    (data ?? []) as Array<{
      run_id: string;
      status: RunSnapshot["status"];
      title: string;
      progress: number;
      created_at: string;
    }>
  ).map((row) => ({
    runId: row.run_id,
    status: row.status,
    title: row.title,
    progress: row.progress,
    createdAt: row.created_at,
  }));
}
452 
async getRun(subject: string, runId: string): Promise<RunSnapshot | null> {
  const { data, error } = await this.client
    .from("run_snapshots")
    .select("data")
    .eq("run_id", runId)
    .eq("user_id", subject)
    .maybeSingle();
  if (error) throw new Error(`run_snapshots get failed: ${error.message}`);
  // Normalize an older stored blob (e.g. a v1 row predating v2's peakProgress) so a
  // saved-run view always reads a current-shape snapshot.
  return data?.data ? migrateSnapshot(data.data as RunSnapshot) : null;
}
465 
async shareRun(
  subject: string,
  runId: string,
  name: string | null,
): Promise<ShareState | null> {
  // Mint a token ONLY if the owned run has none yet, in one row-atomic UPDATE (the
  // `share_token IS NULL` guard). Two concurrent shares can't both mint — the second
  // sees the first's token and matches no row — so re-sharing keeps one stable URL
  // and never trips the unique constraint. (A wasted uuid when already shared is
  // harmless: the guard excludes the row, so it's never written.)
  const minted = await this.client
    .from("run_snapshots")
    .update({ share_token: randomUUID() })
    .eq("run_id", runId)
    .eq("user_id", subject)
    .is("share_token", null);
  if (minted.error)
    throw new Error(
      `run_snapshots share mint failed: ${minted.error.message}`,
    );
486 
  // Set the name and read back the live token (the freshly-minted one, or a token
  // from a prior share). Scoped to the owner, so a run the subject doesn't own
  // matches no row and reads as absent (null) — never shared on their behalf.
  const { data, error } = await this.client
    .from("run_snapshots")
    .update({ share_name: name })
    .eq("run_id", runId)
    .eq("user_id", subject)
    .select("share_token, share_name")
    .maybeSingle();
  if (error) throw new Error(`run_snapshots share failed: ${error.message}`);
  if (!data) return null;
  return {
    token: data.share_token as string,
    name: (data.share_name as string | null) ?? null,
  };
}
504 
async syncAttributedShares(subject: string, username: string): Promise<void> {
  // One row-set UPDATE: re-stamp every attributed share this subject owns. The
  // `share_name IS NOT NULL` filter leaves anonymous shares untouched, so a reroll
  // never converts a private share into an attributed one.
  const { error } = await this.client
    .from("run_snapshots")
    .update({ share_name: username })
    .eq("user_id", subject)
    .not("share_name", "is", null);
  if (error)
    throw new Error(
      `run_snapshots attribution sync failed: ${error.message}`,
    );
}
519 
async unshareRun(subject: string, runId: string): Promise<void> {
  const { error } = await this.client
    .from("run_snapshots")
    .update({ share_token: null, share_name: null })
    .eq("run_id", runId)
    .eq("user_id", subject);
  if (error)
    throw new Error(`run_snapshots unshare failed: ${error.message}`);
}
529 
async getShareState(
  subject: string,
  runId: string,
): Promise<ShareState | null> {
  const { data, error } = await this.client
    .from("run_snapshots")
    .select("share_token, share_name")
    .eq("run_id", runId)
    .eq("user_id", subject)
    .maybeSingle();
  if (error)
    throw new Error(`run_snapshots share state failed: ${error.message}`);
  if (!data) return null;
  return {
    token: (data.share_token as string | null) ?? null,
    name: (data.share_name as string | null) ?? null,
  };
}
548 
async getPublicRun(token: string): Promise<PublicRun | null> {
  // Looked up by the share token ALONE — no owner filter — because the public page
  // has no subject. The token is the capability; an unknown/revoked token misses.
  const { data, error } = await this.client
    .from("run_snapshots")
    .select("data, share_name, derived_from_run_id")
    .eq("share_token", token)
    .maybeSingle();
  if (error)
    throw new Error(`run_snapshots public get failed: ${error.message}`);
  if (!data) return null;
  const remixedFrom = await this.resolveRemixCredit(
    (data.derived_from_run_id as string | null) ?? null,
  );
  return toPublicRun(
    data.data as RunSnapshot,
    (data.share_name as string | null) ?? null,
    remixedFrom,
  );
}
569 
async ownerSubjectByToken(token: string): Promise<string | null> {
  // The owner subject lives only in the row's user_id — read it by token alone
  // (no owner filter; the public page has no subject), for referral attribution.
  const { data, error } = await this.client
    .from("run_snapshots")
    .select("user_id")
    .eq("share_token", token)
    .maybeSingle();
  if (error)
    throw new Error(`run_snapshots owner resolve failed: ${error.message}`);
  return (data?.user_id as string | null) ?? null;
}
582}
583 
584let cached: RunSnapshotStore | null = null;
585 
586/** The configured run-snapshot store (memoized — reuses one Supabase client). */
587export function runSnapshotStore(): RunSnapshotStore {
if (cached) return cached;
const cfg = supabaseConfig();
cached = cfg
  ? new SupabaseRunSnapshotStore(
      createClient(cfg.url, cfg.secretKey, {
        auth: { persistSession: false },
      }),
    )
  : new InMemoryRunSnapshotStore();
return cached;
598}
599 
600/** Test seam: clear the memoized store so the next call re-reads config. */
601export function resetRunSnapshotStore(): void {
cached = null;
603}

The draft store: the same guard

run_drafts is the per-turn autosave, keyed on run_id the same way. Same two halves: first-writer INSERT, then an owner-scoped UPDATE for the returning autosave. A different subject matches no row and is refused — their draft can be neither overwritten nor wiped.

server/utils/run-draft-store.ts · 172 lines

server/utils/run-draft-store.ts172 lines · TypeScript

⋯ 50 lines hidden (lines 1–50)1/**
* The run-draft store — where an IN-PROGRESS run is parked so a refresh or a crash
* can't lose it (#152). POST /api/run-draft upserts the draft here keyed by the run
* id; GET /api/run-draft reads back the subject's latest in-progress draft to resume;
* DELETE /api/run-draft clears it (also cleared on terminal save). The terminal,
* immutable record lives in the separate run-snapshot store — a draft is the live,
* overwritten mirror, never the saved run.
*
* Two adapters behind one port, chosen by config — the repo's env-degradation idiom
* (cf. runSnapshotStore, runStore):
*   - in-memory (default): no external dependency, so `npm run dev` and the unit tests
*     need nothing. Drafts don't outlive the process, but the round-trip (save -> read
*     latest -> delete) is real, which is what the resume path rests on.
*   - Supabase: used when SUPABASE_URL + SUPABASE_SECRET_KEY are configured. Upserts
*     the `run_drafts` row via the service (secret) key, which bypasses RLS — the table
*     has no public policy, so it is server-only.
*
* Ownership is by SUBJECT (the Supabase user id, falling back to the device id) — the
* same string balances/runs/snapshots key on. Reads filter by it, so a player only
* ever resumes their OWN run. A sign-in lands on a fresh or returning account (a
* DIFFERENT subject; see utils/sign-in.ts), so an anonymous draft does not follow
* into it — the trade utils/sign-in.ts records as acceptable.
*/
24import { createClient, type SupabaseClient } from "@supabase/supabase-js";
25import { supabaseConfig } from "./supabase";
26import { RunOwnershipError } from "./run-ownership";
27import { migrateDraft, type RunDraft } from "~/utils/run-snapshot";
28 
29export interface RunDraftStore {
/** Persist (or overwrite) the in-progress draft, owned by `subject`, keyed by run id. */
saveDraft(subject: string, draft: RunDraft): Promise<void>;
/** The subject's most-recently-updated draft, or null when they have none. A
 *  player has a single active run (starting one spends a credit), so "latest"
 *  is the one to resume. */
getLatestDraft(subject: string): Promise<RunDraft | null>;
/** Drop a draft the subject owns. Idempotent; a no-op when absent / not theirs. */
deleteDraft(subject: string, runId: string): Promise<void>;
38}
39 
40/** Dev/test default — keeps the round-trip real without any external dependency. A
*  monotonic tick orders "latest" deterministically (clock ties can't reorder it). */
42export class InMemoryRunDraftStore implements RunDraftStore {
private tick = 0;
private readonly drafts: Array<{
  subject: string;
  runId: string;
  draft: RunDraft;
  updatedAt: number;
}> = [];
50 
async saveDraft(subject: string, draft: RunDraft): Promise<void> {
  const updatedAt = ++this.tick;
  const existing = this.drafts.find((d) => d.runId === draft.runId);
  if (existing) {
    // Owner-scoped overwrite (#215): the owner re-autosaves in place each turn; a
    // DIFFERENT subject holding this run id is refused, never allowed to overwrite or
    // wipe another player's resume draft.
    if (existing.subject !== subject)
      throw new RunOwnershipError(draft.runId);
    existing.draft = draft;
    existing.updatedAt = updatedAt;
    return;
  }
  this.drafts.push({ subject, runId: draft.runId, draft, updatedAt });
⋯ 23 lines hidden (lines 65–87)65  }
66 
async getLatestDraft(subject: string): Promise<RunDraft | null> {
  const owned = this.drafts.filter((d) => d.subject === subject);
  if (!owned.length) return null;
  return migrateDraft(
    owned.reduce((a, b) => (b.updatedAt > a.updatedAt ? b : a)).draft,
  );
}
74 
async deleteDraft(subject: string, runId: string): Promise<void> {
  const i = this.drafts.findIndex(
    (d) => d.runId === runId && d.subject === subject,
  );
  if (i >= 0) this.drafts.splice(i, 1);
}
81}
82 
83/** Records each draft as a `run_drafts` row via the service (secret) key, which
*  bypasses RLS — the table has no public policy, so it is server-only. */
85export class SupabaseRunDraftStore implements RunDraftStore {
constructor(private readonly client: SupabaseClient) {}
87 
async saveDraft(subject: string, draft: RunDraft): Promise<void> {
  // Owner-scoped write (#215). run_drafts is keyed on the run id ALONE and the service
  // key bypasses RLS, so a bare upsert would let any subject holding a leaked run id
  // overwrite — or wipe — another player's resume draft. Split the upsert into two
  // guarded halves. `updated_at` is stamped explicitly on both (a column default fires
  // only on insert, not on the update half) so "latest" stays accurate across the run.
  //
  // First-writer INSERT (ON CONFLICT DO NOTHING): claims an unseen run id. A returned
  // row means we created it.
  const row = {
    run_id: draft.runId,
    user_id: subject,
    version: draft.version,
    data: draft,
    updated_at: new Date().toISOString(),
  };
  const inserted = await this.client
    .from("run_drafts")
    .upsert(row, { onConflict: "run_id", ignoreDuplicates: true })
    .select("run_id");
  if (inserted.error)
    throw new Error(`run_drafts insert failed: ${inserted.error.message}`);
  if (inserted.data?.length) return;
111 
  // The run id already exists — overwrite ONLY if this subject owns it (the per-turn
  // autosave). Scoped to run_id + user_id, so a DIFFERENT subject matches no row: the
  // write is refused and the owner's draft left untouched.
  const { data, error } = await this.client
    .from("run_drafts")
    .update({
      version: draft.version,
      data: draft,
      updated_at: new Date().toISOString(),
    })
    .eq("run_id", draft.runId)
    .eq("user_id", subject)
    .select("run_id");
  if (error) throw new Error(`run_drafts update failed: ${error.message}`);
  if (!data?.length) throw new RunOwnershipError(draft.runId);
}
⋯ 45 lines hidden (lines 128–172)128 
async getLatestDraft(subject: string): Promise<RunDraft | null> {
  const { data, error } = await this.client
    .from("run_drafts")
    .select("data")
    .eq("user_id", subject)
    .order("updated_at", { ascending: false })
    .limit(1)
    .maybeSingle();
  if (error) throw new Error(`run_drafts get failed: ${error.message}`);
  // Drop a draft from a bygone RUN_DRAFT_VERSION rather than rehydrate an old shape
  // as if current — the read-side check the write-side stamp always implied (#257).
  return data?.data ? migrateDraft(data.data as RunDraft) : null;
}
142 
async deleteDraft(subject: string, runId: string): Promise<void> {
  const { error } = await this.client
    .from("run_drafts")
    .delete()
    .eq("run_id", runId)
    .eq("user_id", subject);
  if (error) throw new Error(`run_drafts delete failed: ${error.message}`);
}
151}
152 
153let cached: RunDraftStore | null = null;
154 
155/** The configured run-draft store (memoized — reuses one Supabase client). */
156export function runDraftStore(): RunDraftStore {
if (cached) return cached;
const cfg = supabaseConfig();
cached = cfg
  ? new SupabaseRunDraftStore(
      createClient(cfg.url, cfg.secretKey, {
        auth: { persistSession: false },
      }),
    )
  : new InMemoryRunDraftStore();
return cached;
167}
168 
169/** Test seam: clear the memoized store so the next call re-reads config. */
170export function resetRunDraftStore(): void {
cached = null;
172}

A clean 403 at the edge

The store throws RunOwnershipError; the endpoint maps it to a 403 (a forbidden action, not a server fault) and lets every other error keep its 500. run-draft.post.ts carries the identical branch.

server/api/run-save.post.ts · 68 lines

server/api/run-save.post.ts68 lines · TypeScript

⋯ 39 lines hidden (lines 1–39)1/**
* POST /api/run-save — persist a finished run's snapshot, owned by the account
* subject. The client posts the end-of-run snapshot on victory/defeat; the server
* validates it, then stores it keyed by the run id so it survives reload and seeds
* the read-only "your runs" view.
*
* Best-effort by design: the client fires this without blocking the end screen, so a
* failure here degrades history, never the game. A degraded run (a non-uuid local id,
* never recorded server-side) has nothing to own — it's accepted as a no-op.
*/
11import { sanitizeSnapshot } from "~/server/utils/run-snapshot";
12import { runSnapshotStore } from "~/server/utils/run-snapshot-store";
13import { RunOwnershipError } from "~/server/utils/run-ownership";
14import { balanceStore } from "~/server/utils/balance-store";
15import { currentSubject } from "~/server/utils/auth";
16import { isUuid } from "~/server/utils/uuid";
17 
18export default defineEventHandler(async (event) => {
if (getMethod(event) !== "POST") {
  throw createError({ statusCode: 405, statusMessage: "Method Not Allowed" });
}
const body = await readBody(event);
const snapshot = sanitizeSnapshot(body);
if (!snapshot) {
  throw createError({
    statusCode: 400,
    statusMessage: "Bad Request: invalid run snapshot",
  });
}
// A degraded (non-uuid local) run was never recorded server-side — nothing to own.
if (!isUuid(snapshot.runId)) {
  return { saved: false, degraded: true };
}
// Replay lineage (issue #89): a sibling field, NOT part of the snapshot blob — the
// source run's public share token, which the server resolves to the parent's stable
// run id. uuid-gated so a malformed value is simply ignored (lineage is best-effort).
const rawToken =
  typeof body?.remixedFromToken === "string" ? body.remixedFromToken : "";
const derivedFromToken = isUuid(rawToken) ? rawToken : undefined;
const subject = await currentSubject(event);
try {
  await runSnapshotStore().saveRun(subject, snapshot, { derivedFromToken });
} catch (error) {
  // A save aimed at a run owned by another subject (#215): refuse cleanly — the owner's
  // snapshot is untouched. It's a forbidden action, not a server fault, so 403 not 500.
  if (error instanceof RunOwnershipError) {
    throw createError({
      statusCode: 403,
      statusMessage: "Forbidden: run owned by another subject",
    });
  }
  console.error("Failed to save run snapshot:", error);
  throw createError({
    statusCode: 500,
    statusMessage: "Internal Server Error",
  });
}
// Mark the billing run ended so a finished (victory/defeat — sanitizeSnapshot enforces
// it) run can't take further turns even with budget to spare (#212). Best-effort +
// owner-scoped: a failure here just leaves the turn/aux caps as the backstop, and never
⋯ 8 lines hidden (lines 61–68)61  // fails the best-effort history save.
try {
  await balanceStore().endRun(subject, snapshot.runId);
} catch (error) {
  console.error("Failed to mark run ended:", error);
}
return { saved: true };
68});

What only the fix passes

Each adapter gets three discriminating tests: a different subject can't overwrite another's run (and the owner's snapshot, list membership, and public share all still serve the original); the owner's re-save still lands; a first-writer insert works for a brand-new run. The in-memory hijack-rejection test is the clearest read — it asserts the victim's data survives.

tests/unit/server/utils/run-snapshot-store.spec.ts · 974 lines

tests/unit/server/utils/run-snapshot-store.spec.ts974 lines · TypeScript

⋯ 171 lines hidden (lines 1–171)1import { describe, it, expect, afterEach } from "vitest";
2import {
InMemoryRunSnapshotStore,
SupabaseRunSnapshotStore,
runSnapshotStore,
resetRunSnapshotStore,
toPublicRun,
8} from "../../../../server/utils/run-snapshot-store";
9import {
RUN_SNAPSHOT_VERSION,
type RunSnapshot,
12} from "../../../../utils/run-snapshot";
13import { RunOwnershipError } from "../../../../server/utils/run-ownership";
14import { DiceOutcome } from "../../../../utils/dice";
15import { isUuid } from "../../../../server/utils/uuid";
16 
17/**
* The run-snapshot store turns a finished run into a durable, owned record. Two
* things matter: the round-trip is faithful (save -> list -> load returns the exact
* versioned snapshot, scoped to its owner), and the factory picks the adapter by
* config — in-memory unless Supabase is wired, which keeps dev + tests dependency-free.
*/
23const SUBJECT = "user-abc";
24const OTHER = "user-xyz";
25 
26function makeSnapshot(runId: string, title = "Save the Library"): RunSnapshot {
return {
  version: RUN_SNAPSHOT_VERSION,
  runId,
  status: "victory",
  objective: {
    title,
    description: "Keep the scrolls from the fire.",
    era: "Antiquity",
    icon: "📜",
  },
  objectiveProgress: 100,
  peakProgress: 100,
  messagesUsed: 3,
  totalMessages: 5,
  bestRoll: { diceRoll: 19, diceOutcome: DiceOutcome.CRITICAL_SUCCESS },
  worstRoll: { diceRoll: 4, diceOutcome: DiceOutcome.FAILURE },
  efficiency: {
    messagesSaved: 2,
    messagesUsed: 3,
    efficiencyPercentage: 40,
    efficiencyRating: "Great",
    isEarlyVictory: true,
  },
  dispatches: [
    { text: "Hide the scrolls.", figure: "Hypatia", era: "Antiquity" },
  ],
  timeline: [
    {
      id: "evt-1",
      figureName: "Hypatia",
      era: "Antiquity",
      headline: "The scrolls are hidden",
      detail: "A copy survives the blaze.",
      diceRoll: 19,
      diceOutcome: DiceOutcome.CRITICAL_SUCCESS,
      progressChange: 60,
      valence: "positive",
    },
  ],
  chronicle: {
    title: "The Library Stands",
    paragraphs: ["It did not burn.", "The knowledge endured."],
  },
};
71}
72 
73const RUN_A = "11111111-1111-4111-8111-111111111111";
74const RUN_B = "22222222-2222-4222-8222-222222222222";
75 
76describe("run-snapshot store", () => {
afterEach(() => {
  resetRunSnapshotStore();
  delete process.env.SUPABASE_URL;
  delete process.env.SUPABASE_SECRET_KEY;
});
82 
// The acceptance round-trip: a saved run lists for its owner and loads back intact,
// version and all — the durable record the whole feature rests on.
it("InMemoryRunSnapshotStore round-trips save -> list -> load", async () => {
  const store = new InMemoryRunSnapshotStore();
  const snap = makeSnapshot(RUN_A);
  await store.saveRun(SUBJECT, snap);
89 
  const list = await store.listRuns(SUBJECT);
  expect(list).toEqual([
    {
      runId: RUN_A,
      status: "victory",
      title: "Save the Library",
      progress: 100,
      createdAt: expect.any(String),
    },
  ]);
100 
  const loaded = await store.getRun(SUBJECT, RUN_A);
  expect(loaded).toEqual(snap);
  expect(loaded?.version).toBe(RUN_SNAPSHOT_VERSION);
});
105 
// A v1 blob as it sits in storage from before #151: peakProgress was live-session-only,
// so the persisted record has none (and version 1). A read must normalize it to the
// current shape, defaulting peak to the final progress (peak == final → "no peak shown"),
// so a pre-existing saved/shared run renders exactly as it did before the field existed.
function legacyV1(runId: string): RunSnapshot {
  const blob: Record<string, unknown> = {
    ...makeSnapshot(runId),
    version: 1,
    status: "defeat",
    objectiveProgress: 40,
    efficiency: null,
  };
  delete blob.peakProgress;
  return blob as unknown as RunSnapshot;
}
121 
it("getRun migrates a v1 snapshot, defaulting its peak to the final progress", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, legacyV1(RUN_A));
  const loaded = await store.getRun(SUBJECT, RUN_A);
  expect(loaded?.version).toBe(RUN_SNAPSHOT_VERSION);
  expect(loaded?.peakProgress).toBe(40);
});
129 
it("getPublicRun migrates a v1 snapshot the same way (the public read path)", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, legacyV1(RUN_A));
  const state = await store.shareRun(SUBJECT, RUN_A, null);
  const pub = await store.getPublicRun(state!.token!);
  expect(pub?.run.version).toBe(RUN_SNAPSHOT_VERSION);
  expect(pub?.run.peakProgress).toBe(40);
});
138 
it("lists a subject's runs newest first", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A, "First"));
  await store.saveRun(SUBJECT, makeSnapshot(RUN_B, "Second"));
  const list = await store.listRuns(SUBJECT);
  expect(list.map((r) => r.title)).toEqual(["Second", "First"]);
});
146 
it("scopes reads to the owner — another subject sees nothing", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
  expect(await store.listRuns(OTHER)).toEqual([]);
  expect(await store.getRun(OTHER, RUN_A)).toBeNull();
});
153 
it("overwrites in place on re-save (the post-epilogue second save)", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
  const withEpilogue = makeSnapshot(RUN_A);
  withEpilogue.chronicle = {
    title: "The final telling",
    paragraphs: ["Now complete."],
  };
  await store.saveRun(SUBJECT, withEpilogue);
163 
  expect(await store.listRuns(SUBJECT)).toHaveLength(1);
  expect((await store.getRun(SUBJECT, RUN_A))?.chronicle?.title).toBe(
    "The final telling",
  );
});
169 
// The ownership guard (#215): a leaked run id must NOT let another subject overwrite an
// owned run. The owner keeps their snapshot, their list membership, and their live share.
it("refuses another subject overwriting an owned run — the owner's data survives (#215)", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A, "Owner's run"));
  const { token } = (await store.shareRun(SUBJECT, RUN_A, "Cleo"))!;
176 
  await expect(
    store.saveRun(OTHER, makeSnapshot(RUN_A, "Hijacked")),
  ).rejects.toBeInstanceOf(RunOwnershipError);
180 
  // The owner's snapshot, list, and public share all still serve the ORIGINAL content.
  expect((await store.getRun(SUBJECT, RUN_A))?.objective.title).toBe(
    "Owner's run",
  );
  expect((await store.listRuns(SUBJECT)).map((r) => r.title)).toEqual([
    "Owner's run",
  ]);
  expect((await store.getPublicRun(token!))?.run.objective.title).toBe(
    "Owner's run",
  );
  // ...and the attacker owns nothing.
  expect(await store.listRuns(OTHER)).toEqual([]);
});
194 
// The durable path, first write: a brand-new run id is claimed by the first-writer INSERT
// (ON CONFLICT DO NOTHING, keyed on run_id), and the billing-row owner stamp is guarded
⋯ 65 lines hidden (lines 197–261)197  // FIRST-WRITER (`user_id IS NULL`) so it can never flip an already-set owner.
it("SupabaseRunSnapshotStore first-writer INSERTs a new run and stamps the billing owner", async () => {
  const calls: unknown[][] = [];
  const snap = makeSnapshot(RUN_A);
  const client = fakeWriteClient(
    [
      { data: [{ run_id: RUN_A }], error: null }, // insert claimed the new run id
      { error: null }, // billing-row owner stamp
    ],
    calls,
  );
  const store = new SupabaseRunSnapshotStore(client as never);
  await store.saveRun(SUBJECT, snap);
210 
  expect(calls).toContainEqual([
    "upsert",
    {
      run_id: RUN_A,
      user_id: SUBJECT,
      version: RUN_SNAPSHOT_VERSION,
      status: "victory",
      title: "Save the Library",
      progress: 100,
      data: snap,
    },
    { onConflict: "run_id", ignoreDuplicates: true },
  ]);
  // The billing-row stamp is scoped to the id AND guarded by `user_id IS NULL`.
  expect(calls).toContainEqual(["from", "runs"]);
  expect(calls).toContainEqual(["update", { user_id: SUBJECT }]);
  expect(calls).toContainEqual(["eq", "id", RUN_A]);
  expect(calls).toContainEqual(["is", "user_id", null]);
});
230 
// The durable path, re-save: the OWNER overwrites an existing run in place (the post-
// epilogue second save) via an owner-scoped UPDATE whose SET never touches the share
// columns — so a live share survives the re-save.
it("SupabaseRunSnapshotStore lets the owner re-save an existing run, owner-scoped, share preserved", async () => {
  const calls: unknown[][] = [];
  const client = fakeWriteClient(
    [
      { data: [], error: null }, // insert: run id already exists (conflict, no row)
      { data: [{ run_id: RUN_A }], error: null }, // owner-scoped update matches
      { error: null }, // billing stamp (no-op: already owned)
    ],
    calls,
  );
  const store = new SupabaseRunSnapshotStore(client as never);
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
246 
  const update = calls.find(
    (c) => c[0] === "update" && !!(c[1] as Record<string, unknown>).data,
  );
  expect(update).toBeTruthy();
  expect(update![1]).not.toHaveProperty("share_token");
  expect(update![1]).not.toHaveProperty("share_name");
  expect(update![1]).not.toHaveProperty("user_id");
  // Scoped to BOTH the run id and the owner — the crux of the guard.
  expect(calls).toContainEqual(["eq", "run_id", RUN_A]);
  expect(calls).toContainEqual(["eq", "user_id", SUBJECT]);
});
258 
// The guard on the durable path: the run id exists but is owned by someone else, so the
// owner-scoped UPDATE matches no row → RunOwnershipError, and the billing row is never
// reached (no cross-subject stamp).
it("SupabaseRunSnapshotStore refuses a cross-subject overwrite (#215)", async () => {
  const calls: unknown[][] = [];
  const client = fakeWriteClient(
    [
      { data: [], error: null }, // insert: conflict, nothing inserted
      { data: [], error: null }, // owner-scoped update: no row for THIS subject
    ],
    calls,
  );
  const store = new SupabaseRunSnapshotStore(client as never);
  await expect(
    store.saveRun(OTHER, makeSnapshot(RUN_A)),
  ).rejects.toBeInstanceOf(RunOwnershipError);
  // The overwrite was scoped to the caller's OWN subject (so it matched nothing)...
  expect(calls).toContainEqual(["eq", "run_id", RUN_A]);
  expect(calls).toContainEqual(["eq", "user_id", OTHER]);
  // ...and it never fell through to touch the billing `runs` row.
  expect(calls).not.toContainEqual(["from", "runs"]);
});
281 
⋯ 693 lines hidden (lines 282–974)282  it("SupabaseRunSnapshotStore throws when the snapshot insert errors", async () => {
  const store = new SupabaseRunSnapshotStore(
    fakeWriteClient([{ error: { message: "boom" } }], []) as never,
  );
  await expect(store.saveRun(SUBJECT, makeSnapshot(RUN_A))).rejects.toThrow(
    /run_snapshots insert failed: boom/,
  );
});
290 
it("SupabaseRunSnapshotStore lists by subject, newest first, mapping rows", async () => {
  const calls: unknown[][] = [];
  const builder = {
    select: (cols: string) => {
      calls.push(["select", cols]);
      return builder;
    },
    eq: (col: string, val: unknown) => {
      calls.push(["eq", col, val]);
      return builder;
    },
    order: async (col: string, opts: unknown) => {
      calls.push(["order", col, opts]);
      return {
        data: [
          {
            run_id: RUN_A,
            status: "defeat",
            title: "A run",
            progress: 80,
            created_at: "2026-06-17T00:00:00Z",
          },
        ],
        error: null,
      };
    },
  };
  const client = {
    from: (t: string) => {
      calls.push(["from", t]);
      return builder;
    },
  };
  const store = new SupabaseRunSnapshotStore(client as never);
  const list = await store.listRuns(SUBJECT);
326 
  expect(list).toEqual([
    {
      runId: RUN_A,
      status: "defeat",
      title: "A run",
      progress: 80,
      createdAt: "2026-06-17T00:00:00Z",
    },
  ]);
  expect(calls).toEqual(
    expect.arrayContaining([
      ["from", "run_snapshots"],
      ["eq", "user_id", SUBJECT],
      ["order", "created_at", { ascending: false }],
    ]),
  );
});
344 
it("SupabaseRunSnapshotStore loads one run filtered by id AND owner", async () => {
  const calls: unknown[][] = [];
  const snap = makeSnapshot(RUN_A);
  const builder = {
    select: (cols: string) => {
      calls.push(["select", cols]);
      return builder;
    },
    eq: (col: string, val: unknown) => {
      calls.push(["eq", col, val]);
      return builder;
    },
    maybeSingle: async () => {
      calls.push(["maybeSingle"]);
      return { data: { data: snap }, error: null };
    },
  };
  const client = {
    from: (t: string) => {
      calls.push(["from", t]);
      return builder;
    },
  };
  const store = new SupabaseRunSnapshotStore(client as never);
  const loaded = await store.getRun(SUBJECT, RUN_A);
370 
  expect(loaded).toEqual(snap);
  expect(calls).toEqual(
    expect.arrayContaining([
      ["eq", "run_id", RUN_A],
      ["eq", "user_id", SUBJECT],
      ["maybeSingle"],
    ]),
  );
});
380 
it("getRun returns null when the row is absent (non-owned reads as missing)", async () => {
  const builder = {
    select: () => builder,
    eq: () => builder,
    maybeSingle: async () => ({ data: null, error: null }),
  };
  const store = new SupabaseRunSnapshotStore({
    from: () => builder,
  } as never);
  expect(await store.getRun(OTHER, RUN_A)).toBeNull();
});
392 
it("defaults to the in-memory store when Supabase is unconfigured", () => {
  resetRunSnapshotStore();
  expect(runSnapshotStore()).toBeInstanceOf(InMemoryRunSnapshotStore);
});
397 
it("uses the Supabase store when URL + secret key are both configured", () => {
  process.env.SUPABASE_URL = "https://example.supabase.co";
  process.env.SUPABASE_SECRET_KEY = "sb_secret_test";
  resetRunSnapshotStore();
  expect(runSnapshotStore()).toBeInstanceOf(SupabaseRunSnapshotStore);
});
404});
405 
406/**
* Sharing a run (issue #88): a private saved run becomes a PUBLIC, read-only projection
* at an unguessable token, opt-in and revocable. Two things must hold: the public
* projection leaks NO owner identity (no subject, no run id), and the share/un-share flow
* is owner-scoped and reversible. The fake Supabase client records the query shapes so the
* security-critical ones are pinned — above all that the public lookup is by token ALONE.
*/
413describe("run-snapshot store — sharing (issue #88)", () => {
afterEach(() => {
  resetRunSnapshotStore();
  delete process.env.SUPABASE_URL;
  delete process.env.SUPABASE_SECRET_KEY;
});
419 
// --- The public projection: the sanitization boundary ---
it("toPublicRun keeps the game record but strips the run id and owner identity", () => {
  const snap = makeSnapshot(RUN_A);
  const pub = toPublicRun(snap, null);
  // The token is the only handle — the run id is redacted.
  expect(pub.run.runId).toBe("");
  expect(pub.attribution).toBeNull();
  // No owning subject and no run id anywhere in the public payload.
  const json = JSON.stringify(pub);
  expect(json).not.toContain(SUBJECT);
  expect(json).not.toContain(RUN_A);
  // The game record itself is intact (verdict, objective, ledger, epilogue).
  expect(pub.run.status).toBe("victory");
  expect(pub.run.objective.title).toBe("Save the Library");
  expect(pub.run.timeline).toHaveLength(1);
  expect(pub.run.chronicle?.title).toBe("The Library Stands");
});
437 
it("toPublicRun trims a display name and nulls a blank one", () => {
  expect(toPublicRun(makeSnapshot(RUN_A), "  Cleo  ").attribution).toBe(
    "Cleo",
  );
  expect(toPublicRun(makeSnapshot(RUN_A), "   ").attribution).toBeNull();
  expect(toPublicRun(makeSnapshot(RUN_A), null).attribution).toBeNull();
});
445 
// --- InMemory share / un-share flow (the round-trip the feature rests on) ---
it("shares an owned run and resolves its token to the public projection", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
450 
  const state = await store.shareRun(SUBJECT, RUN_A, "Cleo");
  expect(state).not.toBeNull();
  expect(isUuid(state!.token!)).toBe(true);
  expect(state!.name).toBe("Cleo");
455 
  const pub = await store.getPublicRun(state!.token!);
  expect(pub?.attribution).toBe("Cleo");
  expect(pub?.run.runId).toBe("");
  expect(pub?.run.objective.title).toBe("Save the Library");
});
461 
it("share is owner-scoped — another subject can neither share nor see state", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
  expect(await store.shareRun(OTHER, RUN_A, null)).toBeNull();
  expect(await store.getShareState(OTHER, RUN_A)).toBeNull();
});
468 
it("re-sharing keeps the same token (stable URL) and updates the name", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
  const first = await store.shareRun(SUBJECT, RUN_A, null);
  const second = await store.shareRun(SUBJECT, RUN_A, "Cleo");
  expect(second!.token).toBe(first!.token);
  expect(second!.name).toBe("Cleo");
  expect((await store.getShareState(SUBJECT, RUN_A))!.name).toBe("Cleo");
});
478 
it("un-sharing revokes the token — the public link goes dead", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
  const { token } = (await store.shareRun(SUBJECT, RUN_A, "Cleo"))!;
  await store.unshareRun(SUBJECT, RUN_A);
  expect(await store.getPublicRun(token!)).toBeNull();
  expect((await store.getShareState(SUBJECT, RUN_A))!.token).toBeNull();
});
487 
it("getShareState: token null until shared; null for a run the subject lacks", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
  expect(await store.getShareState(SUBJECT, RUN_A)).toEqual({
    token: null,
    name: null,
  });
  expect(await store.getShareState(SUBJECT, RUN_B)).toBeNull();
});
497 
it("getPublicRun returns null for an unknown token", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
  expect(
    await store.getPublicRun("11111111-2222-4333-8444-555555555555"),
  ).toBeNull();
});
505 
it("a post-epilogue re-save preserves the share (the link survives, gains the epilogue)", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
  const { token } = (await store.shareRun(SUBJECT, RUN_A, "Cleo"))!;
  const withEpilogue = makeSnapshot(RUN_A);
  withEpilogue.chronicle = {
    title: "The final telling",
    paragraphs: ["Now complete."],
  };
  await store.saveRun(SUBJECT, withEpilogue);
516 
  const pub = await store.getPublicRun(token!);
  expect(pub?.run.chronicle?.title).toBe("The final telling");
  expect(pub?.attribution).toBe("Cleo");
});
521 
// --- Supabase query shapes (the durable path's security-critical filters) ---
it("Supabase shareRun mints (only when absent), sets the name, and is owner-scoped", async () => {
  const calls: unknown[][] = [];
  const client = {
    from: () =>
      fakeChain(
        { data: { share_token: "tok-1", share_name: "Cleo" }, error: null },
        calls,
      ),
  };
  const store = new SupabaseRunSnapshotStore(client as never);
533 
  const state = await store.shareRun(SUBJECT, RUN_A, "Cleo");
  expect(state).toEqual({ token: "tok-1", name: "Cleo" });
  // The mint is row-atomic and guarded by `share_token IS NULL` — it mints only when
  // absent, so a re-share keeps the stable URL and concurrent shares can't both mint.
  expect(calls).toContainEqual(["is", "share_token", null]);
  const mint = calls.find(
    (c) =>
      c[0] === "update" && !!(c[1] as Record<string, unknown>)?.share_token,
  );
  expect(isUuid((mint![1] as { share_token: string }).share_token)).toBe(
    true,
  );
  // The name is set and every write is scoped to BOTH the run id and the owner.
  expect(calls).toContainEqual(["update", { share_name: "Cleo" }]);
  expect(calls).toEqual(
    expect.arrayContaining([
      ["eq", "run_id", RUN_A],
      ["eq", "user_id", SUBJECT],
    ]),
  );
});
555 
it("Supabase shareRun returns null when the subject does not own the run", async () => {
  const client = { from: () => fakeChain({ data: null, error: null }, []) };
  const store = new SupabaseRunSnapshotStore(client as never);
  expect(await store.shareRun(OTHER, RUN_A, null)).toBeNull();
});
561 
it("Supabase getPublicRun looks up by the token ALONE — never the owner", async () => {
  const calls: unknown[][] = [];
  const snap = makeSnapshot(RUN_A);
  const client = {
    from: () =>
      fakeChain(
        { data: { data: snap, share_name: "Cleo" }, error: null },
        calls,
      ),
  };
  const store = new SupabaseRunSnapshotStore(client as never);
573 
  const pub = await store.getPublicRun("tok-1");
  expect(pub?.run.runId).toBe("");
  expect(pub?.attribution).toBe("Cleo");
  expect(calls).toContainEqual(["eq", "share_token", "tok-1"]);
  // Security: the public read must NOT filter by user_id (the page has no subject).
  expect(calls.some((c) => c[0] === "eq" && c[1] === "user_id")).toBe(false);
});
581 
it("Supabase unshareRun nulls the token + name for the owned run", async () => {
  const calls: unknown[][] = [];
  const client = {
    from: () => fakeChain({ data: null, error: null }, calls),
  };
  const store = new SupabaseRunSnapshotStore(client as never);
  await store.unshareRun(SUBJECT, RUN_A);
  expect(calls).toContainEqual([
    "update",
    { share_token: null, share_name: null },
  ]);
  expect(calls).toEqual(
    expect.arrayContaining([
      ["eq", "run_id", RUN_A],
      ["eq", "user_id", SUBJECT],
    ]),
  );
});
600});
601 
602/**
* Attribution sync (issue #117): the username is an ACCOUNT property, so a reroll has to
* follow everywhere the handle appears in public. syncAttributedShares re-stamps every one
* of a subject's ALREADY-attributed shares with the new handle — and leaves anonymous
* shares anonymous (a reroll never opts a private share into attribution) and other
* subjects untouched.
*/
609describe("run-snapshot store — attribution sync (issue #117)", () => {
const RUN_C = "33333333-3333-4333-8333-333333333333";
611 
afterEach(() => {
  resetRunSnapshotStore();
  delete process.env.SUPABASE_URL;
  delete process.env.SUPABASE_SECRET_KEY;
});
617 
it("re-stamps the subject's attributed shares, leaving anonymous + other subjects alone", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
  await store.saveRun(SUBJECT, makeSnapshot(RUN_B));
  await store.saveRun(OTHER, makeSnapshot(RUN_C));
  await store.shareRun(SUBJECT, RUN_A, "Old Handle"); // attributed
  await store.shareRun(SUBJECT, RUN_B, null); // anonymous
  await store.shareRun(OTHER, RUN_C, "Other Handle"); // a different account, attributed
626 
  await store.syncAttributedShares(SUBJECT, "New Handle");
628 
  expect((await store.getShareState(SUBJECT, RUN_A))!.name).toBe(
    "New Handle",
  ); // re-stamped
  expect((await store.getShareState(SUBJECT, RUN_B))!.name).toBeNull(); // stayed anonymous
  expect((await store.getShareState(OTHER, RUN_C))!.name).toBe(
    "Other Handle",
  ); // untouched
});
637 
it("Supabase syncAttributedShares updates only attributed rows, owner-scoped", async () => {
  const calls: unknown[][] = [];
  const client = {
    from: () => fakeChain({ data: null, error: null }, calls),
  };
  const store = new SupabaseRunSnapshotStore(client as never);
644 
  await store.syncAttributedShares(SUBJECT, "New Handle");
  expect(calls).toContainEqual(["update", { share_name: "New Handle" }]);
  expect(calls).toContainEqual(["eq", "user_id", SUBJECT]);
  // `share_name IS NOT NULL` — anonymous shares are never re-stamped.
  expect(calls).toContainEqual(["not", "share_name", "is", null]);
  // And never scoped to a single run id — it's the subject's whole attributed set.
  expect(calls.some((c) => c[0] === "eq" && c[1] === "run_id")).toBe(false);
});
653});
654 
655/**
* Replay lineage (issue #89): a replayed run is stamped with a pointer back to the run it
* was seeded from, and the "remixed from" credit is WALKED one hop at read time — so it
* always reflects the source's CURRENT opt-in (a later un-share drops the name + backlink),
* and never copies identity into the child. These pin: the pointer round-trips, the credit
* honors privacy, and the durable path resolves a token to the parent's stable run id.
*/
662describe("run-snapshot store — replay lineage (issue #89)", () => {
afterEach(() => {
  resetRunSnapshotStore();
  delete process.env.SUPABASE_URL;
  delete process.env.SUPABASE_SECRET_KEY;
});
668 
// The core round-trip: a child seeded from a shared source carries the credit, walked
// from the SOURCE's live row — its name, its objective title, and a backlink token.
it("a replay stamps the pointer; getPublicRun walks one hop to the source credit", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A, "Save the Library"));
  const source = await store.shareRun(SUBJECT, RUN_A, "Cleo");
675 
  await store.saveRun(OTHER, makeSnapshot(RUN_B, "A remix"), {
    derivedFromToken: source!.token!,
  });
  const child = await store.shareRun(OTHER, RUN_B, "Remixer");
680 
  const pub = await store.getPublicRun(child!.token!);
  expect(pub?.remixedFrom).toEqual({
    attribution: "Cleo",
    objectiveTitle: "Save the Library",
    sourceToken: source!.token,
  });
  // The credit carries no parent run id and no owning subject — only public, opt-in data.
  const json = JSON.stringify(pub?.remixedFrom);
  expect(json).not.toContain(RUN_A);
  expect(json).not.toContain(SUBJECT);
});
692 
it("an anonymous source is credited anonymously (no name invented or leaked)", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A, "Save the Library"));
  const source = await store.shareRun(SUBJECT, RUN_A, null); // shared, but no display name
  await store.saveRun(OTHER, makeSnapshot(RUN_B), {
    derivedFromToken: source!.token!,
  });
  const child = await store.shareRun(OTHER, RUN_B, null);
701 
  const pub = await store.getPublicRun(child!.token!);
  expect(pub?.remixedFrom).toEqual({
    attribution: null,
    objectiveTitle: "Save the Library",
    sourceToken: source!.token,
  });
});
709 
// Privacy carries forward: it's a POINTER, not a copy — revoking the source's share
// drops the credit back to anonymous and removes the backlink, even on existing replays.
it("un-sharing the source anonymizes the credit and drops the backlink", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A, "Save the Library"));
  const source = await store.shareRun(SUBJECT, RUN_A, "Cleo");
  await store.saveRun(OTHER, makeSnapshot(RUN_B), {
    derivedFromToken: source!.token!,
  });
  const child = await store.shareRun(OTHER, RUN_B, null);
720 
  await store.unshareRun(SUBJECT, RUN_A); // the source stops sharing
722 
  const pub = await store.getPublicRun(child!.token!);
  expect(pub?.remixedFrom).toEqual({
    attribution: null,
    objectiveTitle: "Save the Library",
    sourceToken: null,
  });
});
730 
it("an original (non-replay) run has no credit", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
  const { token } = (await store.shareRun(SUBJECT, RUN_A, "Cleo"))!;
  expect((await store.getPublicRun(token!))?.remixedFrom).toBeNull();
});
737 
it("a post-epilogue re-save WITHOUT the token preserves the stamped pointer", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A, "Save the Library"));
  const source = await store.shareRun(SUBJECT, RUN_A, "Cleo");
  await store.saveRun(OTHER, makeSnapshot(RUN_B), {
    derivedFromToken: source!.token!,
  });
  // The epilogue re-save fires without the lineage token; it must not erase it.
  await store.saveRun(OTHER, makeSnapshot(RUN_B));
  const child = await store.shareRun(OTHER, RUN_B, null);
748 
  expect(
    (await store.getPublicRun(child!.token!))?.remixedFrom?.attribution,
  ).toBe("Cleo");
});
753 
// The pointer is STABLE once stamped: a source un-sharing mid-run must not erase the
// lineage (only the walked credit anonymizes). Guards the null-clobber regression.
it("a stamped pointer survives the source un-sharing mid-run (re-save never nulls it)", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A, "Save the Library"));
  const source = await store.shareRun(SUBJECT, RUN_A, "Cleo");
  // First save stamps the pointer while the source is shared...
  await store.saveRun(OTHER, makeSnapshot(RUN_B), {
    derivedFromToken: source!.token!,
  });
  // ...the source then un-shares, so the token no longer resolves...
  await store.unshareRun(SUBJECT, RUN_A);
  // ...and the epilogue re-save (still carrying the now-dead token) must NOT erase it.
  await store.saveRun(OTHER, makeSnapshot(RUN_B), {
    derivedFromToken: source!.token!,
  });
  const child = await store.shareRun(OTHER, RUN_B, null);
771 
  expect((await store.getPublicRun(child!.token!))?.remixedFrom).toEqual({
    attribution: null,
    objectiveTitle: "Save the Library",
    sourceToken: null,
  });
});
778 
it("self-derivation is ignored (a run can never be its own parent)", async () => {
  const store = new InMemoryRunSnapshotStore();
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A));
  const { token } = (await store.shareRun(SUBJECT, RUN_A, "Cleo"))!;
  // Re-save the same run pointing at its OWN token — the guard nulls it out.
  await store.saveRun(SUBJECT, makeSnapshot(RUN_A), {
    derivedFromToken: token!,
  });
  expect((await store.getPublicRun(token!))?.remixedFrom).toBeNull();
});
789 
// Durable path: the token is resolved to the parent's STABLE run id (never trusting a
// client-supplied id) and stamped on the first-writer INSERT row.
it("Supabase saveRun resolves the source token to a stable parent id and stamps it", async () => {
  const PARENT = "33333333-3333-4333-8333-333333333333";
  const TOKEN = "44444444-4444-4444-8444-444444444444";
  const calls: unknown[][] = [];
  const client = fakeWriteClient(
    [
      { data: { run_id: PARENT }, error: null }, // lineage resolve
      { data: [{ run_id: RUN_B }], error: null }, // first-writer insert
      { error: null }, // billing stamp
    ],
    calls,
  );
  const store = new SupabaseRunSnapshotStore(client as never);
  await store.saveRun(OTHER, makeSnapshot(RUN_B), {
    derivedFromToken: TOKEN,
  });
808 
  expect(calls).toContainEqual(["eq", "share_token", TOKEN]);
  const upsert = calls.find((c) => c[0] === "upsert") as [
    string,
    Record<string, unknown>,
    unknown,
  ];
  expect(upsert[1].derived_from_run_id).toBe(PARENT);
});
817 
it("Supabase saveRun never writes a null pointer (omits the column when the token misses)", async () => {
  const calls: unknown[][] = [];
  const client = fakeWriteClient(
    [
      { data: null, error: null }, // lineage resolve: the token resolves to nothing
      { data: [{ run_id: RUN_B }], error: null }, // first-writer insert
      { error: null }, // billing stamp
    ],
    calls,
  );
  const store = new SupabaseRunSnapshotStore(client as never);
  await store.saveRun(OTHER, makeSnapshot(RUN_B), {
    derivedFromToken: "44444444-4444-4444-8444-444444444444",
  });
832 
  const upsert = calls.find((c) => c[0] === "upsert") as [
    string,
    Record<string, unknown>,
    unknown,
  ];
  // Never null — a missing resolve leaves the column out so a prior pointer survives.
  expect(upsert[1]).not.toHaveProperty("derived_from_run_id");
});
841 
it("Supabase getPublicRun walks one hop for the credit, filtered by run id never owner", async () => {
  const results = [
    {
      data: {
        data: makeSnapshot(RUN_B),
        share_name: "Remixer",
        derived_from_run_id: RUN_A,
      },
      error: null,
    }, // child
    {
      data: {
        title: "Save the Library",
        share_name: "Cleo",
        share_token: "parent-tok",
      },
      error: null,
    }, // parent
  ];
  const calls: unknown[][] = [];
  const builder: Record<string, unknown> = {
    select: (c: string) => {
      calls.push(["select", c]);
      return builder;
    },
    eq: (c: string, v: unknown) => {
      calls.push(["eq", c, v]);
      return builder;
    },
    maybeSingle: async () => results.shift(),
  };
  const store = new SupabaseRunSnapshotStore({
    from: () => builder,
  } as never);
876 
  const pub = await store.getPublicRun("child-tok");
  expect(pub?.run.runId).toBe(""); // still sanitized
  expect(pub?.remixedFrom).toEqual({
    attribution: "Cleo",
    objectiveTitle: "Save the Library",
    sourceToken: "parent-tok",
  });
  // The second hop resolves by the parent RUN ID; the public read never filters by owner.
  expect(calls).toContainEqual(["eq", "run_id", RUN_A]);
  expect(calls.some((c) => c[0] === "eq" && c[1] === "user_id")).toBe(false);
});
888});
889 
890/**
* A chainable, awaitable fake of the Supabase query builder. `select`/`update`/`eq` record
* their args and return the same builder (so chains of any length work); `maybeSingle` and
* awaiting the chain both resolve to `result`. One `result` serves a method that both reads
* (via .data) and writes (via .error), which is exactly shareRun's read-then-update shape.
*/
896function fakeChain(
result: { data?: unknown; error: unknown },
calls: unknown[][],
899) {
const builder: Record<string, unknown> = {
  select: (c: string) => {
    calls.push(["select", c]);
    return builder;
  },
  update: (row: unknown) => {
    calls.push(["update", row]);
    return builder;
  },
  eq: (c: string, v: unknown) => {
    calls.push(["eq", c, v]);
    return builder;
  },
  is: (c: string, v: unknown) => {
    calls.push(["is", c, v]);
    return builder;
  },
  not: (c: string, op: string, v: unknown) => {
    calls.push(["not", c, op, v]);
    return builder;
  },
  maybeSingle: async () => {
    calls.push(["maybeSingle"]);
    return result;
  },
  then: (onF: (v: typeof result) => unknown, onR?: (e: unknown) => unknown) =>
    Promise.resolve(result).then(onF, onR),
};
return builder;
929}
930 
931/**
* A write-path fake: like fakeChain, but it hands back a QUEUE of results — one per awaited
* statement, consumed in call order. The owner-scoped saveRun runs up to four statements
* (lineage resolve, first-writer insert, owner-scoped update, billing stamp), each needing
* its own {data,error}; a single fixed result can't express "insert conflicts, THEN the
* owner-update matches / misses". Records every builder call so a test can pin the
* security-critical filters (`eq user_id`, the first-writer `is user_id null`).
*/
939function fakeWriteClient(
results: Array<{ data?: unknown; error?: unknown }>,
calls: unknown[][],
942) {
const builder: Record<string, unknown> = {
  upsert: (row: unknown, opts: unknown) => {
    calls.push(["upsert", row, opts]);
    return builder;
  },
  update: (row: unknown) => {
    calls.push(["update", row]);
    return builder;
  },
  select: (c: string) => {
    calls.push(["select", c]);
    return builder;
  },
  eq: (c: string, v: unknown) => {
    calls.push(["eq", c, v]);
    return builder;
  },
  is: (c: string, v: unknown) => {
    calls.push(["is", c, v]);
    return builder;
  },
  maybeSingle: async () => results.shift(),
  then: (onF: (v: unknown) => unknown, onR?: (e: unknown) => unknown) =>
    Promise.resolve(results.shift()).then(onF, onR),
};
return {
  from: (t: string) => {
    calls.push(["from", t]);
    return builder;
  },
};
974}