@marktiderman/genesis-supabase 0.2.0 → 0.3.1

package/functions/tests/genesis-apple-revoke_test.ts

@@ -0,0 +1,81 @@
+// Deno test for the genesis-apple-revoke function's handler, in the runtime it
+// deploys to (WebCrypto, fetch, Request). Apple and the database are faked.
+//   deno test functions/tests/genesis-apple-revoke_test.ts
+import { handle, type DueRevocation, type HandlerDeps } from "../genesis-apple-revoke/handler.ts";
+import { decodeJwtPayload } from "../genesis-apple-revoke/apple.ts";
+
+function assertEquals(actual: unknown, expected: unknown, message = "") {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a !== e) throw new Error(`${message} expected ${e}, got ${a}`);
+}
+
+const pair = await crypto.subtle.generateKey({ name: "ECDSA", namedCurve: "P-256" }, true, ["sign", "verify"]);
+const der = new Uint8Array(await crypto.subtle.exportKey("pkcs8", pair.privateKey));
+const pem = `-----BEGIN PRIVATE KEY-----\n${btoa(String.fromCharCode(...der))}\n-----END PRIVATE KEY-----`;
+const env: Record<string, string> = { APPLE_TEAM_ID: "TEAM123456", APPLE_KEY_ID: "KEY1234567", APPLE_PRIVATE_KEY: pem, APPLE_CLIENT_IDS: "com.example.app" };
+const b64 = (o: unknown) => btoa(JSON.stringify(o)).replace(/=+$/, "").replace(/\+/g, "-").replace(/\//g, "_");
+
+function deps(queue: DueRevocation[], forms: Record<string, string>[]): HandlerDeps & { saved: unknown[][]; done: number[] } {
+  const saved: unknown[][] = [];
+  const done: number[] = [];
+  return {
+    saved,
+    done,
+    env: (n) => env[n],
+    fetch: (async (url: string | URL | Request, init?: RequestInit) => {
+      const form = Object.fromEntries(new URLSearchParams(String(init?.body)));
+      forms.push({ url: String(url), ...form });
+      if (String(url).endsWith("/auth/token")) {
+        const id_token = `${b64({ alg: "RS256" })}.${b64({ iss: "https://appleid.apple.com", aud: "com.example.app", sub: "apple-sub" })}.sig`;
+        return new Response(JSON.stringify({ refresh_token: "rt", id_token }), { status: 200 });
+      }
+      return new Response(null, { status: 200 });
+    }) as typeof fetch,
+    getUser: async (t) => (t === "access" ? { id: "user-1", appleUserIds: ["apple-sub"] } : null),
+    store: {
+      save: async (...args) => {
+        saved.push(args);
+        return "stored";
+      },
+      claim: async () => queue.splice(0),
+      done: async (id) => void done.push(id),
+      failed: async () => "retry" as const,
+    },
+    log: () => {},
+  };
+}
+
+const post = (body: unknown, token?: string) =>
+  new Request("http://localhost/functions/v1/genesis-apple-revoke", { method: "POST", headers: token ? { authorization: `Bearer ${token}` } : {}, body: JSON.stringify(body) });
+
+Deno.test("store exchanges the code with a signed client secret and saves the token", async () => {
+  const forms: Record<string, string>[] = [];
+  const d = deps([], forms);
+  const res = await handle(post({ action: "store", code: "code-1" }, "access"), d);
+  assertEquals(res.status, 200);
+  assertEquals(await res.json(), { ok: true });
+  assertEquals(d.saved, [["user-1", "com.example.app", "rt"]]);
+  const secret = forms[0]!.client_secret!;
+  const [h, p, s] = secret.split(".");
+  const ok = await crypto.subtle.verify(
+    { name: "ECDSA", hash: "SHA-256" },
+    pair.publicKey,
+    Uint8Array.from(atob(s!.replace(/-/g, "+").replace(/_/g, "/")), (c) => c.charCodeAt(0)),
+    new TextEncoder().encode(`${h}.${p}`),
+  );
+  assertEquals(ok, true, "client secret signature");
+  assertEquals(decodeJwtPayload(secret)?.sub, "com.example.app");
+});
+
+Deno.test("revoke works through the queue with no caller", async () => {
+  const forms: Record<string, string>[] = [];
+  const d = deps([{ id: 9, client_id: "com.example.app", refresh_token: "queued-rt", attempts: 1 }], forms);
+  const res = await handle(post({ action: "revoke" }), d);
+  assertEquals(res.status, 200);
+  // First the proof (the token is live with these secrets), then the revocation.
+  assertEquals(forms[0]!.grant_type, "refresh_token");
+  assertEquals(forms[1]!.url, "https://appleid.apple.com/auth/revoke");
+  assertEquals(forms[1]!.token_type_hint, "refresh_token");
+  assertEquals(d.done, [9]);
+});

package/functions/tests/genesis-push-send_test.ts

@@ -0,0 +1,53 @@
+// Deno test for the genesis-push-send function's handler, in the runtime it
+// deploys to (WebCrypto, fetch, Request, AbortSignal.timeout). Expo and the
+// database are faked.
+//   deno test functions/tests/genesis-push-send_test.ts
+import { handle, type HandlerDeps, type TicketRow } from "../genesis-push-send/handler.ts";
+
+function assertEquals(actual: unknown, expected: unknown, message = "") {
+  const a = JSON.stringify(actual);
+  const e = JSON.stringify(expected);
+  if (a !== e) throw new Error(`${message} expected ${e}, got ${a}`);
+}
+
+const secret = "x".repeat(32);
+const user = "00000000-0000-4000-8000-000000000001";
+
+function deps(sentBodies: unknown[], tickets: TicketRow[]): HandlerDeps {
+  return {
+    env: (n) => ({ GENESIS_PUSH_SECRET: secret })[n],
+    fetch: (async (_url: string | URL | Request, init?: RequestInit) => {
+      const body = JSON.parse(String(init?.body)) as unknown[];
+      sentBodies.push(body);
+      return new Response(JSON.stringify({ data: body.map((_, i) => ({ status: "ok", id: `t${i}` })) }), { status: 200 });
+    }) as typeof fetch,
+    store: {
+      targets: async () => [{ device_id: "d1", token: "ExponentPushToken[abc]", platform: "ios", hide_previews: true }],
+      status: async () => ({ deliver: true, reason: "ok", quiet_until: null }),
+      recordTickets: async (rows) => void tickets.push(...rows),
+      forgetDevices: async () => {},
+      claimReceipts: async () => [],
+      settleReceipts: async () => {},
+    },
+    log: () => {},
+  };
+}
+
+Deno.test("sends with hidden previews and records the ticket", async () => {
+  const sent: unknown[] = [];
+  const tickets: TicketRow[] = [];
+  const req = new Request("http://localhost", {
+    method: "POST",
+    headers: { authorization: `Bearer ${secret}` },
+    body: JSON.stringify({ action: "send", messages: [{ userId: user, category: "messages", title: "Private title", body: "Private body", url: "/messages/1" }] }),
+  });
+  const res = await handle(req, deps(sent, tickets));
+  assertEquals(res.status, 200);
+  assertEquals(sent, [[{ to: "ExponentPushToken[abc]", title: "New notification", data: { category: "messages", url: "/messages/1" }, sound: "default", channelId: "messages", priority: "high" }]]);
+  assertEquals(tickets, [{ user_id: user, device_id: "d1", category: "messages", ticket_id: "t0", status: "sent" }]);
+});
+
+Deno.test("refuses a caller without the secret", async () => {
+  const res = await handle(new Request("http://localhost", { method: "POST", headers: { authorization: "Bearer nope" }, body: "{}" }), deps([], []));
+  assertEquals(res.status, 401);
+});

package/migrations/0003_genesis_apple_token_revocation.sql

@@ -0,0 +1,205 @@
+-- Genesis Sign in with Apple token revocation: where Apple's refresh tokens live,
+-- and the queue that revokes them when an account is deleted.
+--
+-- App Store Review Guideline 5.1.1(v): an app that offers Sign in with Apple
+-- revokes the person's Apple tokens (https://appleid.apple.com/auth/revoke)
+-- when they delete their account. Supabase doesn't: a native id-token sign-in
+-- never hands Supabase an Apple refresh token, and Auth doesn't keep the
+-- provider tokens it does see. So the app sends the sign-in's authorization
+-- code to the `genesis-apple-revoke` Edge Function (shipped beside this file
+-- in @marktiderman/genesis-supabase), which exchanges it for a refresh token
+-- and keeps it here; deleting the login queues it, and the function revokes it.
+--
+-- Use: copy this file into your app's `supabase/migrations/` under a new
+-- timestamped name, and the function folder into `supabase/functions/`.
+-- Never edit it once applied; change it with a new migration. It stands
+-- alone (it doesn't need 0001), and covers every way a login is deleted:
+-- delete_my_account, the dashboard, and the admin API.
+--
+-- Who can see a token: nobody but this file's functions. The tables are in
+-- `private` (not exposed through the Data API) with row level security on, no
+-- policies and every table privilege revoked from anon and authenticated. The
+-- Edge Function reaches them only through the four `public` functions below,
+-- executable by service_role alone (granted and revoked by name).
+--
+-- Not encrypted in the column: an Apple refresh token is useless without a
+-- client secret signed with your .p8 key, which lives in the function's
+-- secrets, not the database; encrypting it with a key from those same secrets
+-- would add a secret without closing a gap.
+--
+-- Failure policy: deletion never waits for Apple. The delete trigger moves
+-- the person's tokens into `private.genesis_apple_revocations` in the same
+-- transaction as the delete (so a refused delete queues nothing, and a
+-- committed one can't lose its token), and the function revokes them after:
+-- straight away when the app asks, then on a schedule, with backoff (five
+-- minutes, doubling, at most a day apart). A revoked token's row is deleted.
+-- After 30 failed attempts (about four weeks) the token is dropped and the
+-- row kept, with `last_error` starting `gave_up`, as the record that it
+-- wasn't revoked. A deleted login that signed in with Apple but has no stored
+-- token (the store step failed, or it predates this) leaves a row with no
+-- token and `last_error` starting `no_token`. Any row still here is one to
+-- look at.
+--
+-- Verify: the pgTAP test beside this file (`tests/0003_genesis_apple_token_revocation.test.sql`).
+
+create schema if not exists private;
+
+-- One refresh token per login and client id (bundle id or Services ID): each
+-- sign-in replaces the last.
+create table private.genesis_apple_tokens (
+  user_id uuid not null references auth.users (id) on delete cascade,
+  client_id text not null check (client_id ~ '^[A-Za-z0-9][A-Za-z0-9.-]{0,254}$'),
+  refresh_token text not null check (length(refresh_token) between 1 and 4096),
+  updated_at timestamptz not null default now(),
+  primary key (user_id, client_id)
+);
+
+-- Tokens of deleted logins, until Apple confirms the revocation. `user_id` has
+-- no foreign key: the login is gone. A row without a token is a record (no
+-- token was ever stored, or the retries gave up), never handed out.
+create table private.genesis_apple_revocations (
+  id bigint generated always as identity primary key,
+  user_id uuid not null,
+  client_id text,
+  refresh_token text,
+  queued_at timestamptz not null default now(),
+  attempts integer not null default 0,
+  next_attempt_at timestamptz not null default now(),
+  last_error text,
+  check (refresh_token is null or client_id is not null)
+);
+create index genesis_apple_revocations_due on private.genesis_apple_revocations (next_attempt_at) where refresh_token is not null;
+
+alter table private.genesis_apple_tokens enable row level security;
+alter table private.genesis_apple_revocations enable row level security;
+revoke all on table private.genesis_apple_tokens from public, anon, authenticated;
+revoke all on table private.genesis_apple_revocations from public, anon, authenticated;
+
+comment on table private.genesis_apple_tokens is
+  'Sign in with Apple refresh tokens, server-only; written by genesis-apple-revoke. Genesis account block.';
+comment on table private.genesis_apple_revocations is
+  'Apple refresh tokens of deleted logins, until /auth/revoke succeeds; rows without a token are records to look at. Genesis account block.';
+
+-- Deleting a login (any way) queues its Apple tokens before the cascade
+-- removes them, or records that an Apple login had none to queue.
+create function private.genesis_apple_queue_revocation()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+begin
+  insert into private.genesis_apple_revocations (user_id, client_id, refresh_token)
+  select t.user_id, t.client_id, t.refresh_token
+  from private.genesis_apple_tokens t
+  where t.user_id = old.id;
+  if not found and exists (select 1 from auth.identities i where i.user_id = old.id and i.provider = 'apple') then
+    insert into private.genesis_apple_revocations (user_id, last_error)
+    values (old.id, 'no_token: signed in with Apple, but no refresh token was stored, so none was revoked');
+  end if;
+  return old;
+end;
+$$;
+
+create trigger genesis_apple_queue_revocation
+  before delete on auth.users
+  for each row execute function private.genesis_apple_queue_revocation();
+
+-- Keeps the refresh token from a sign-in. If the login is already gone (it was
+-- deleted while the code was being exchanged), the token goes straight to the
+-- queue instead, so it is still revoked. Returns 'stored' or 'queued'.
+create function public.genesis_apple_token_save(p_user_id uuid, p_client_id text, p_refresh_token text)
+returns text
+language plpgsql
+security definer
+set search_path = ''
+as $$
+begin
+  insert into private.genesis_apple_tokens as t (user_id, client_id, refresh_token)
+  values (p_user_id, p_client_id, p_refresh_token)
+  on conflict (user_id, client_id) do update
+    set refresh_token = excluded.refresh_token, updated_at = now();
+  return 'stored';
+exception
+  when foreign_key_violation then
+    insert into private.genesis_apple_revocations (user_id, client_id, refresh_token)
+    values (p_user_id, p_client_id, p_refresh_token);
+    return 'queued';
+  when check_violation then
+    -- Raised afresh so the error (and the server log) never carries the failing row, token and all.
+    raise exception 'genesis_apple_token_save: malformed client id or token' using errcode = '23514';
+end;
+$$;
+
+-- Hands out up to p_limit due revocations and pushes each one's next attempt
+-- back (5 minutes, doubling per attempt, at most a day): the lease outlasts a
+-- batch, so a function that dies mid-batch retries later and two runs never
+-- take the same row.
+create function public.genesis_apple_revocations_claim(p_limit integer default 20)
+returns table (id bigint, client_id text, refresh_token text, attempts integer)
+language sql
+security definer
+set search_path = ''
+as $$
+  update private.genesis_apple_revocations r
+  set attempts = r.attempts + 1,
+      next_attempt_at = now() + least(interval '5 minutes' * power(2, least(r.attempts, 20)), interval '1 day')
+  where r.id in (
+    select q.id from private.genesis_apple_revocations q
+    where q.refresh_token is not null and q.next_attempt_at <= now()
+    order by q.next_attempt_at
+    limit greatest(1, least(coalesce(p_limit, 20), 100))
+    for update skip locked
+  )
+  returning r.id, r.client_id, r.refresh_token, r.attempts;
+$$;
+
+-- Apple confirmed (or the token was already dead): forget the token.
+create function public.genesis_apple_revocation_done(p_id bigint)
+returns void
+language sql
+security definer
+set search_path = ''
+as $$
+  delete from private.genesis_apple_revocations where id = p_id and refresh_token is not null;
+$$;
+
+-- Apple refused or didn't answer: keep the row for its next attempt, with why.
+-- After the 30th attempt, drop the token and keep the row as the record.
+-- Returns 'retry' or 'gave_up'.
+create function public.genesis_apple_revocation_failed(p_id bigint, p_error text)
+returns text
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  tries integer;
+begin
+  update private.genesis_apple_revocations
+  set last_error = left(coalesce(p_error, ''), 200)
+  where id = p_id and refresh_token is not null
+  returning attempts into tries;
+  if tries >= 30 then
+    update private.genesis_apple_revocations
+    set refresh_token = null, last_error = left('gave_up after ' || tries || ' attempts: ' || coalesce(p_error, ''), 200)
+    where id = p_id;
+    return 'gave_up';
+  end if;
+  return 'retry';
+end;
+$$;
+
+-- Privileges by name. Supabase's default privileges grant execute on a new
+-- public function to anon and authenticated, so each is revoked here; a later
+-- blanket `grant … on all functions` would hand them back, so such a grant
+-- must exclude them.
+revoke execute on function private.genesis_apple_queue_revocation() from public, anon, authenticated;
+revoke execute on function public.genesis_apple_token_save(uuid, text, text) from public, anon, authenticated;
+revoke execute on function public.genesis_apple_revocations_claim(integer) from public, anon, authenticated;
+revoke execute on function public.genesis_apple_revocation_done(bigint) from public, anon, authenticated;
+revoke execute on function public.genesis_apple_revocation_failed(bigint, text) from public, anon, authenticated;
+grant execute on function public.genesis_apple_token_save(uuid, text, text) to service_role;
+grant execute on function public.genesis_apple_revocations_claim(integer) to service_role;
+grant execute on function public.genesis_apple_revocation_done(bigint) to service_role;
+grant execute on function public.genesis_apple_revocation_failed(bigint, text) to service_role;

package/migrations/0004_genesis_tenant_features.sql

@@ -0,0 +1,333 @@
+-- Genesis tenant features: public.tenant_features and public.set_tenant_feature()
+--
+-- Per-tenant on/off switches for shipped features: a tenant's admins turn a
+-- feature off (or back on) for their tenant, with a reason, and every change
+-- is kept (who, when, why) in public.tenant_feature_changes. A feature with no
+-- row is on. The client half is `tenantFeatures(client, tenantId)` and
+-- `setTenantFeature(client, …)` in @marktiderman/genesis-supabase.
+--
+-- What a switch is for: exposure (hiding a tab, a nav entry, a screen), never
+-- authorization. Paid access is an entitlement, and who may see a row is RLS;
+-- a gate in SQL can read `private.tenant_feature_on(tenant, feature)`.
+--
+-- "Tenant" is whatever your app groups people by (a team, an organization, a
+-- workspace) and is keyed by a uuid. This file names no table of yours:
+--
+--   The app hook: `private.genesis_tenant_admin(tenant uuid, person uuid) returns boolean`
+--   decides who may change a tenant's features. Without it nobody can (set_tenant_feature
+--   raises 42501 with a hint), so a fresh install fails closed. Optionally,
+--   `private.genesis_tenant_member(tenant uuid, person uuid) returns boolean` decides who
+--   may read which features are off (admins always may). Both run with this
+--   file's (the owner's) rights, so they read your membership table whatever its RLS:
+--
+--   create function private.genesis_tenant_admin(tenant uuid, person uuid) returns boolean
+--   language sql stable set search_path = '' as $$
+--     select exists (select 1 from public.memberships m
+--                    where m.team_id = tenant and m.user_id = person and m.role in ('owner', 'admin'))
+--   $$;
+--   revoke execute on function private.genesis_tenant_admin(uuid, uuid) from public, anon, authenticated;
+--
+-- Your tenant table: add the foreign key yourself in a later migration, so a
+-- deleted tenant takes its switches and their history with it (a delete that
+-- cascades from elsewhere isn't recorded, so it never refuses the tenant's deletion):
+--
+--   alter table public.tenant_features add foreign key (tenant_id) references public.teams (id) on delete cascade;
+--   alter table public.tenant_feature_changes add foreign key (tenant_id) references public.teams (id) on delete cascade;
+--
+-- Feature ids are the registry's FeatureIds (`features.ts`), checked here for
+-- their shape only. If you mirror the registry into a table, add a foreign key.
+--
+-- Access: everything goes through the functions below (security definer,
+-- each asking the hook). The tables have row level security on, no policies
+-- and no grants to anon or authenticated. The service role (a server job, a
+-- platform admin's tool) may write the switches directly, and its writes are
+-- recorded too, with no person.
+--
+-- Use: copy this file into your app's `supabase/migrations/` under a new
+-- timestamped name. Never edit it once applied; change it with a new migration.
+-- It stands alone (it doesn't need 0001 to 0003).
+--
+-- Verify: the pgTAP test beside this file (`tests/0004_genesis_tenant_features.test.sql`).
+
+create schema if not exists private;
+
+create table public.tenant_features (
+  tenant_id uuid not null,
+  feature_id text not null
+    constraint tenant_features_feature_id_format check (feature_id ~ '^[a-z][a-z0-9]*([-_.][a-z0-9]+)*$' and char_length(feature_id) <= 100),
+  enabled boolean not null,
+  reason text not null
+    constraint tenant_features_reason_length check (char_length(btrim(reason)) between 1 and 500),
+  updated_by uuid references auth.users (id) on delete set null,
+  updated_at timestamptz not null default now(),
+  primary key (tenant_id, feature_id)
+);
+
+comment on table public.tenant_features is
+  'Per-tenant feature switches (a missing row is on), with the latest reason. Written through set_tenant_feature or by the service role. Genesis tenant features.';
+
+-- Every change, kept: who (the signed-in person, or none for the service role
+-- or a migration), with which role, when, and why. A row is never edited.
+create table public.tenant_feature_changes (
+  id bigint generated always as identity primary key,
+  tenant_id uuid not null,
+  feature_id text not null,
+  -- null when the switch row was deleted (back to the default: on).
+  enabled boolean,
+  reason text,
+  changed_by uuid references auth.users (id) on delete set null,
+  changed_role text not null,
+  changed_at timestamptz not null default now()
+);
+
+create index tenant_feature_changes_tenant on public.tenant_feature_changes (tenant_id, changed_at desc);
+
+comment on table public.tenant_feature_changes is
+  'History of public.tenant_features: who changed which switch, when and why. Written only by its trigger. Genesis tenant features.';
+
+-- The hooks, asked with the signed-in person. Missing hook, nobody signed in,
+-- or a null answer: false.
+create or replace function private.genesis_is_tenant_admin(tenant uuid)
+returns boolean
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+declare
+  me uuid := auth.uid();
+begin
+  if me is null or tenant is null or to_regprocedure('private.genesis_tenant_admin(uuid,uuid)') is null then
+    return false;
+  end if;
+  return coalesce(private.genesis_tenant_admin(tenant, me), false);
+end;
+$$;
+
+create or replace function private.genesis_is_tenant_member(tenant uuid)
+returns boolean
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+declare
+  me uuid := auth.uid();
+begin
+  if me is null or tenant is null then
+    return false;
+  end if;
+  -- Two statements: an expression naming a missing function fails even behind `and`.
+  if to_regprocedure('private.genesis_tenant_member(uuid,uuid)') is not null then
+    if coalesce(private.genesis_tenant_member(tenant, me), false) then
+      return true;
+    end if;
+  end if;
+  return private.genesis_is_tenant_admin(tenant);
+end;
+$$;
+
+-- For SQL gates (a policy, a function): is this feature on for this tenant?
+-- Reads every row whatever the caller's RLS. A feature with no row is on.
+create or replace function private.tenant_feature_on(tenant uuid, feature text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select not exists (
+    select 1 from public.tenant_features f
+    where f.tenant_id = tenant and f.feature_id = feature and not f.enabled
+  )
+$$;
+
+create or replace function public.set_tenant_feature(tenant uuid, feature text, enabled boolean, reason text)
+returns void
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  me uuid := auth.uid();
+  why text := btrim(coalesce(reason, ''));
+begin
+  if me is null then
+    raise exception 'set_tenant_feature: not signed in' using errcode = '42501';
+  end if;
+  if tenant is null or feature is null or enabled is null then
+    raise exception 'set_tenant_feature: tenant, feature and enabled are required' using errcode = '22004';
+  end if;
+  if to_regprocedure('private.genesis_tenant_admin(uuid,uuid)') is null then
+    raise exception 'set_tenant_feature: nobody may change tenant features yet'
+      using errcode = '42501', hint = 'Create private.genesis_tenant_admin(uuid, uuid) (see migration 0004_genesis_tenant_features).';
+  end if;
+  if not private.genesis_is_tenant_admin(tenant) then
+    raise exception 'set_tenant_feature: only the tenant''s admins can change its features' using errcode = '42501';
+  end if;
+  if why = '' or char_length(why) > 500 then
+    raise exception 'set_tenant_feature: say why, in at most 500 characters' using errcode = '22023';
+  end if;
+  insert into public.tenant_features as f (tenant_id, feature_id, enabled, reason, updated_by, updated_at)
+  values (tenant, feature, enabled, why, me, now())
+  on conflict (tenant_id, feature_id) do update
+    set enabled = excluded.enabled, reason = excluded.reason, updated_by = excluded.updated_by, updated_at = excluded.updated_at
+    -- Saving the same switch and reason again changes nothing, not even who and when.
+    where (f.enabled, f.reason) is distinct from (excluded.enabled, excluded.reason);
+end;
+$$;
+
+comment on function public.set_tenant_feature(uuid, text, boolean, text) is
+  'Turns a feature on or off for a tenant, with a reason. Only the tenant''s admins (private.genesis_tenant_admin). Genesis tenant features.';
+
+-- The ids turned off for a tenant, for its members (and admins) to hide them.
+create or replace function public.tenant_features_off(tenant uuid)
+returns setof text
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+begin
+  if not private.genesis_is_tenant_member(tenant) then
+    raise exception 'tenant_features_off: only the tenant''s members can read its features' using errcode = '42501';
+  end if;
+  return query
+    select f.feature_id from public.tenant_features f
+    where f.tenant_id = tenant and not f.enabled
+    order by f.feature_id;
+end;
+$$;
+
+comment on function public.tenant_features_off(uuid) is
+  'The feature ids a tenant has turned off. For its members. Genesis tenant features.';
+
+-- Every switch a tenant has set, with the latest reason, who and when: for its admins' Settings screen.
+create or replace function public.tenant_feature_settings(tenant uuid)
+returns table (feature_id text, enabled boolean, reason text, updated_by uuid, updated_at timestamptz)
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+begin
+  if not private.genesis_is_tenant_admin(tenant) then
+    raise exception 'tenant_feature_settings: only the tenant''s admins can read its switches' using errcode = '42501';
+  end if;
+  return query
+    select f.feature_id, f.enabled, f.reason, f.updated_by, f.updated_at from public.tenant_features f
+    where f.tenant_id = tenant
+    order by f.feature_id;
+end;
+$$;
+
+comment on function public.tenant_feature_settings(uuid) is
+  'A tenant''s feature switches with their reasons. For its admins. Genesis tenant features.';
+
+-- A tenant's history of changes, newest first, at most `max_rows` (1 to 1000).
+create or replace function public.tenant_feature_history(tenant uuid, max_rows integer default 100)
+returns table (feature_id text, enabled boolean, reason text, changed_by uuid, changed_role text, changed_at timestamptz)
+language plpgsql
+stable
+security definer
+set search_path = ''
+as $$
+begin
+  if not private.genesis_is_tenant_admin(tenant) then
+    raise exception 'tenant_feature_history: only the tenant''s admins can read its history' using errcode = '42501';
+  end if;
+  return query
+    select c.feature_id, c.enabled, c.reason, c.changed_by, c.changed_role, c.changed_at from public.tenant_feature_changes c
+    where c.tenant_id = tenant
+    order by c.changed_at desc, c.id desc
+    limit greatest(1, least(coalesce(max_rows, 100), 1000));
+end;
+$$;
+
+comment on function public.tenant_feature_history(uuid, integer) is
+  'Who changed a tenant''s feature switches, when and why, newest first. For its admins. Genesis tenant features.';
+
+create or replace function private.genesis_record_tenant_feature_change()
+returns trigger
+language plpgsql
+security definer
+set search_path = ''
+as $$
+declare
+  claims jsonb := coalesce(nullif(current_setting('request.jwt.claims', true), '')::jsonb, '{}'::jsonb);
+begin
+  -- Only a change of the switch or its reason is history. This skips the
+  -- `on delete set null` of updated_by when a person is deleted, which would
+  -- otherwise record the deleted person as the actor and refuse their deletion.
+  if tg_op = 'UPDATE' and new.enabled is not distinct from old.enabled and new.reason is not distinct from old.reason
+     and new.tenant_id = old.tenant_id and new.feature_id = old.feature_id then
+    return null;
+  end if;
+  if tg_op = 'DELETE' then
+    begin
+      insert into public.tenant_feature_changes (tenant_id, feature_id, enabled, reason, changed_by, changed_role)
+      values (old.tenant_id, old.feature_id, null, null, (select u.id from auth.users u where u.id = auth.uid()),
+              coalesce(nullif(claims ->> 'role', ''), 'database'));
+    exception when foreign_key_violation then
+      -- The delete cascades from the tenant's own (your foreign key, or a person whose
+      -- tenant goes with them): the tenant is gone, so there is nothing to record, and
+      -- recording it would refuse the tenant's or the person's deletion.
+      null;
+    end;
+    return null;
+  end if;
+  insert into public.tenant_feature_changes (tenant_id, feature_id, enabled, reason, changed_by, changed_role)
+  values (
+    new.tenant_id,
+    new.feature_id,
+    new.enabled,
+    new.reason,
+    -- Only a login that still exists: one being deleted in this statement is no one.
+    (select u.id from auth.users u where u.id = auth.uid()),
+    coalesce(nullif(claims ->> 'role', ''), 'database')
+  );
+  return null;
+end;
+$$;
+
+create trigger genesis_record_change
+  after insert or update or delete on public.tenant_features
+  for each row execute function private.genesis_record_tenant_feature_change();
+
+-- Row level security on, with no policies: anon and authenticated reach the
+-- tables only through the functions above, even if a later grant lets them try.
+alter table public.tenant_features enable row level security;
+alter table public.tenant_feature_changes enable row level security;
+
+-- Privileges by name. Supabase's default privileges give anon and
+-- authenticated everything on a new public table and function, and Postgres
+-- gives every function to public: take them back, then grant what's needed.
+revoke all on table public.tenant_features from public, anon, authenticated;
+revoke all on table public.tenant_feature_changes from public, anon, authenticated;
+-- No truncate (it would skip the history trigger), references or trigger for the service role.
+revoke all on table public.tenant_features from service_role;
+grant select, insert, update, delete on table public.tenant_features to service_role;
+revoke all on sequence public.tenant_feature_changes_id_seq from public, anon, authenticated;
+-- The history is the trigger's: the service role may read and purge it, never write it.
+revoke all on table public.tenant_feature_changes from service_role;
+grant select, delete on table public.tenant_feature_changes to service_role;
+
+revoke execute on function public.set_tenant_feature(uuid, text, boolean, text) from public, anon;
+grant execute on function public.set_tenant_feature(uuid, text, boolean, text) to authenticated;
+revoke execute on function public.tenant_features_off(uuid) from public, anon;
+grant execute on function public.tenant_features_off(uuid) to authenticated;
+revoke execute on function public.tenant_feature_settings(uuid) from public, anon;
+grant execute on function public.tenant_feature_settings(uuid) to authenticated;
+revoke execute on function public.tenant_feature_history(uuid, integer) from public, anon;
+grant execute on function public.tenant_feature_history(uuid, integer) to authenticated;
+
+-- Only the functions above call these.
+revoke execute on function private.genesis_is_tenant_admin(uuid) from public, anon, authenticated;
+revoke execute on function private.genesis_is_tenant_member(uuid) from public, anon, authenticated;
+revoke execute on function private.genesis_record_tenant_feature_change() from public, anon, authenticated;
+-- For gates in your own SQL, called from security definer functions (owned
+-- by the migration's role, so they need no grant). It answers for any tenant,
+-- without the member check: grant it to authenticated (with usage on schema
+-- private) only if you mean every signed-in person to be able to ask.
+revoke execute on function private.tenant_feature_on(uuid, text) from public, anon, authenticated;
+grant execute on function private.tenant_feature_on(uuid, text) to service_role;