@coffre/db 0.14.4 → 0.15.0

package/dist/migrations/postgres/0047_cutover_finish.sql

@@ -0,0 +1,268 @@
+-- 0.15's cutover from 0.14, finished (docs/design/0.15-plan.md, "As built: PR 9b"; formal/Migration015.tla). It adds a column 0.14 never writes, a trigger, and replaces three functions only 0.15's vault calls.
+--
+-- Once the cutover is there, 0.14's code writes nothing (OldWritesRefused, OldWritesBeforeAnchor). An isolate of 0.14 may still serve after 0.15 cut over: its uses go on, its writes would leave rows no change of 0.15's seals, `stale` to every use (the plan's "late 0.14 write"). Each entry a writer under 0.15's log appends carries `log015`, which no MAC covers and 0.14 never sets; the trigger refuses an allowed entry without it, but a read's, a use's or the log's own (`audit.*`: its beats, checkpoints, findings and the losses an Owner accepts; the alarms), once the cutover's change is in `log_changes`. The append fails, and with it the transaction that wrote its rows: the old isolate answers an error, and its client asks again of 0.15. Every 0.14 append holds 0.14's head, which the cutover holds to its commit, so an append either commits before the cutover or sees it. Sign-ins are refused too (`sign_in`, `token.exchange`, `device.approve`): a credential 0.14 makes after the cutover is one 0.15 never sealed. Before the cutover it costs a 0.14 write one probe of `log_changes_object_idx`; a 0.15 entry passes it by its WHEN. An owner who drops the trigger lets a late write land, its object `stale`; a row put back over it is still refused by the use's probe of 0.14's newest access entry (UsesSeeOldWrites).
+ALTER TABLE "audit_log" ADD COLUMN "log015" boolean;
+--> statement-breakpoint
+CREATE FUNCTION log_refuse_old_write() RETURNS trigger
+    LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp SET jit = off AS $$
+BEGIN
+    IF EXISTS (SELECT 1 FROM public.log_changes c WHERE c.object = public.log_object('log', 'cutover')) THEN
+        RAISE EXCEPTION '0.15''s log is cut over from 0.14: 0.14''s % is refused, as every write of 0.14''s after it (an isolate of the earlier release still serving: ask again)', NEW.action
+            USING ERRCODE = 'object_not_in_prerequisite_state';
+    END IF;
+    RETURN NEW;
+END
+$$;
+--> statement-breakpoint
+REVOKE ALL ON FUNCTION log_refuse_old_write() FROM PUBLIC;
+--> statement-breakpoint
+CREATE TRIGGER audit_log_refuse_old BEFORE INSERT ON audit_log FOR EACH ROW
+    WHEN (NEW.decision = 'allow' AND NEW.log015 IS NULL AND NEW.action NOT LIKE 'audit.%' AND NEW.action NOT IN (
+        'credential.use', 'token.use', 'secret.read', 'secret.use', 'secret.list', 'secret.history', 'secret.version', 'missing.list', 'personal.list',
+        'roles.list', 'roles.preview', 'mcp.read', 'mcp.view', 'key.check', 'key.intent', 'workload.alert', 'vault.tampered'
+    ))
+    EXECUTE FUNCTION log_refuse_old_write();
+--> statement-breakpoint
+-- A revoke as 0034 made it (its comment says how), but for 0.14's head, taken first (EntryLessHead, Migration015EntryLess): it writes no 0.14 entry, and 0.14's use of the credential, on an isolate still serving, checks its row under the head, then commits. Without the head, the revoke commits and answers between the two, and that use goes on. So: 0.14's head, the row, the fence, as the app's writes take them (AppHeadFirst). Until 0.16 removes 0.14's path.
+CREATE OR REPLACE FUNCTION revoke_credential(
+    p_request text, p_at bigint, p_actor text, p_payload text, p_mac bytea, p_seal_from bytea, p_seal bytea,
+    p_id uuid, p_mac_from bytea, p_auth_mac bytea, p_revoked_at bigint, p_revoked_by text,
+    p_policy boolean, p_policy_seq bigint, p_protected uuid[], p_slugs text[]
+) RETURNS json
+    LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp SET jit = off SET lock_timeout = '1s' AS $$
+DECLARE
+    n bigint;
+    target uuid := public.log_object('credential', p_id::text);
+BEGIN
+    IF p_seal_from IS NULL OR p_seal IS NULL THEN
+        RAISE EXCEPTION 'the vault revokes a credential the log holds, from its seal' USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+    PERFORM 1 FROM public.audit_chain_head WHERE only_row FOR UPDATE;
+    PERFORM 1 FROM public.credentials c
+     WHERE c.id = p_id AND c.revoked_at IS NULL AND c.auth_mac = p_mac_from AND c.seal IS NOT DISTINCT FROM p_seal_from
+       FOR UPDATE;
+    IF NOT FOUND THEN RETURN json_build_object('state', 'moved'); END IF;
+    PERFORM pg_advisory_xact_lock(1668244070, 0);
+    -- ChangeChecksSeal: a row the log sealed once, put back since, is not its newest change's.
+    IF p_seal_from IS DISTINCT FROM (SELECT c.seal FROM public.log_changes c WHERE c.object = target ORDER BY c.number DESC LIMIT 1) THEN
+        RETURN json_build_object('state', 'stale');
+    END IF;
+    IF p_policy AND (
+        (SELECT a.seq FROM public.audit_log a WHERE a.author = 'vault' AND a.action = 'policy.change' AND a.decision = 'allow' ORDER BY a.seq DESC LIMIT 1)
+            IS DISTINCT FROM p_policy_seq
+        -- Each protected environment's slug as it stands, none once it or its project is deleted (a tombstone), as `policyNow` reads them.
+        OR EXISTS (
+            SELECT 1 FROM unnest(p_protected, p_slugs) AS p(id, slug)
+             WHERE (SELECT e.slug FROM public.environments e JOIN public.projects q ON q.id = e.project_id
+                     WHERE e.id = p.id AND strpos(e.slug, '~') = 0 AND strpos(q.slug, '~') = 0) IS DISTINCT FROM p.slug
+        )
+    ) THEN
+        RETURN json_build_object('state', 'policy');
+    END IF;
+    UPDATE public.credentials
+       SET revoked_at = timestamptz 'epoch' + p_revoked_at * interval '1 millisecond', revoked_by = p_revoked_by, auth_mac = p_auth_mac, seal = p_seal
+     WHERE id = p_id;
+    INSERT INTO public.log_changes (number, at, request_id, object, actor, payload, seal, mac)
+        VALUES (nextval('public.log_number'), p_at, p_request, target, p_actor, p_payload, p_seal, p_mac)
+        RETURNING number INTO n;
+    RETURN json_build_object('number', n::text);
+END
+$$;
+--> statement-breakpoint
+-- A change of bindings as 0040 made it (its comment says how), but for 0.14's head when it ends any, for the revokes it writes with no 0.14 entry, as `revoke_credential` above: after the members' rows (0.14's vault takes a member's row before the head) and before any row of the app's (the credential it came in on, the bindings, their credentials), as 0.14's app takes the head before its rows. A bind that ends nothing takes none.
+CREATE OR REPLACE FUNCTION change_bindings(
+    p_at bigint, p_actor text,
+    p_make boolean, p_principal text, p_generation integer, p_principal_seq bigint, p_actor_generation integer, p_actor_seq bigint,
+    p_via uuid, p_via_seal bytea, p_via_end bigint, p_connection uuid, p_connection_generation integer,
+    p_policy_seq bigint, p_protected uuid[], p_slugs text[], p_app_key text, p_max integer,
+    p_live uuid[], p_read_keys uuid[], p_read_names text[],
+    p_id uuid, p_auth_mac bytea, p_profile text, p_issuer text, p_jwks_uri text, p_jwks text, p_claims text, p_scope text, p_policy text, p_origin text,
+    p_label text, p_created_by text, p_created_at bigint, p_seal bytea,
+    p_ends uuid[], p_end_mac_from bytea[], p_end_seal_from bytea[], p_end_auth_mac bytea[], p_end_seal bytea[],
+    p_creds uuid[], p_cred_binding uuid[], p_cred_mac_from bytea[], p_cred_seal_from bytea[], p_cred_auth_mac bytea[], p_cred_seal bytea[],
+    p_revoked_at bigint, p_revoked_by text,
+    p_change_request text[], p_change_object uuid[], p_change_payload text[], p_change_seal bytea[], p_change_mac bytea[]
+) RETURNS json
+    LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp SET jit = off SET lock_timeout = '1s' AS $$
+DECLARE
+    n bigint;
+    -- A value, not `clock_timestamp()` in a predicate: volatile there, it bounds no index.
+    now_ts timestamptz := clock_timestamp();
+    ended timestamptz := timestamptz 'epoch' + p_revoked_at * interval '1 millisecond';
+BEGIN
+    IF p_make = (p_id IS NULL) OR (NOT p_make AND cardinality(p_ends) = 0) OR cardinality(p_creds) <> cardinality(p_cred_binding)
+       OR p_make = (p_live IS NULL) OR cardinality(p_read_keys) <> cardinality(p_read_names)
+       OR cardinality(p_change_request) <> (CASE WHEN p_make THEN 1 ELSE 0 END) + (SELECT count(*) FROM unnest(p_end_seal) AS s WHERE s IS NOT NULL)
+                                          + (SELECT count(*) FROM unnest(p_cred_seal) AS s WHERE s IS NOT NULL) THEN
+        RAISE EXCEPTION 'a change of bindings makes one, ends some, or both, with a change for each object' USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+    IF p_make THEN
+        -- IssuerLocked, IssuerCAS, as `issue_token`, by principal: the account's row first (`token:` sorts before `user:`),
+        -- its update lock, so that two binds of it take turns over its count of bindings (a sign-in through one of its
+        -- bindings waits for the statement too); then the maker's, shared. Then both compared.
+        IF p_principal >= p_actor THEN RAISE EXCEPTION 'a binding is a service account''s, made by a person' USING ERRCODE = 'invalid_parameter_value'; END IF;
+        PERFORM 1 FROM public.vault_members m WHERE m.principal = p_principal FOR NO KEY UPDATE;
+        PERFORM 1 FROM public.vault_members m WHERE m.principal = p_actor FOR SHARE;
+        -- 0.14's head, when it ends any, after the members' rows and before any row of the app's (row, head, issue lock, fence).
+        IF cardinality(p_ends) > 0 THEN PERFORM 1 FROM public.audit_chain_head WHERE only_row FOR UPDATE; END IF;
+        IF NOT EXISTS (SELECT 1 FROM public.vault_members m WHERE m.principal = p_actor AND m.status = 'active' AND m.generation = p_actor_generation AND m.access_seq = p_actor_seq)
+           OR NOT EXISTS (SELECT 1 FROM public.vault_members m WHERE m.principal = p_principal AND m.status = 'active' AND m.generation = p_generation AND m.access_seq = p_principal_seq) THEN
+            RETURN json_build_object('state', 'moved');
+        END IF;
+        IF p_via IS NOT NULL THEN
+            PERFORM 1 FROM public.credentials c WHERE c.id = p_via FOR SHARE;
+            IF NOT EXISTS (SELECT 1 FROM public.credentials c
+                            WHERE c.id = p_via AND c.principal = p_actor AND c.revoked_at IS NULL AND c.seal = p_via_seal
+                              AND floor(extract(epoch FROM least(c.expires_at, coalesce(c.not_after, c.expires_at))) * 1000)::bigint = p_via_end)
+               -- The clock once the locks are had, not when the statement began: one that ended while it waited has ended.
+               OR p_via_end <= (extract(epoch FROM clock_timestamp()) * 1000)::bigint
+               OR p_via_seal IS DISTINCT FROM (SELECT c.seal FROM public.log_changes c WHERE c.object = public.log_object('credential', p_via::text) ORDER BY c.number DESC LIMIT 1) THEN
+                RETURN json_build_object('state', 'ended');
+            END IF;
+        END IF;
+        -- The MCP connection it came through, still connected at the caller's generation (as `credentialStill`): shared,
+        -- so a disconnect waits for this, or is seen (review r3).
+        IF p_connection IS NOT NULL THEN
+            PERFORM 1 FROM public.mcp_connections k WHERE k.id = p_connection AND k.revoked_at IS NULL AND k.generation = p_connection_generation FOR SHARE;
+            IF NOT FOUND THEN RETURN json_build_object('state', 'ended'); END IF;
+        END IF;
+        -- An id the log holds already is no binding to make, even once its row is gone: its object stands (review r3).
+        IF EXISTS (SELECT 1 FROM public.log_changes l WHERE l.object = public.log_object('binding', p_id::text)) THEN
+            RETURN json_build_object('state', 'stale');
+        END IF;
+    END IF;
+    -- An unbind alone: 0.14's head first, as above.
+    IF NOT p_make THEN PERFORM 1 FROM public.audit_chain_head WHERE only_row FOR UPDATE; END IF;
+    -- The bindings it ends, then the credentials they issued: each row locked, by id, then held to its MAC and seal as
+    -- read. Every live credential they issued must be named, so one that a sign-in made meanwhile is read again (`moved`),
+    -- never left live.
+    PERFORM 1 FROM public.service_bindings b WHERE b.id = ANY(p_ends) ORDER BY b.id FOR UPDATE;
+    IF (SELECT count(*) FROM unnest(p_ends, p_end_mac_from, p_end_seal_from) AS e(id, mac, seal)
+          JOIN public.service_bindings b ON b.id = e.id AND b.principal = p_principal AND b.revoked_at IS NULL AND b.auth_mac = e.mac AND b.seal IS NOT DISTINCT FROM e.seal)
+       <> cardinality(p_ends) THEN
+        RETURN json_build_object('state', 'moved');
+    END IF;
+    -- A credential 0.14 made, or one written around the vault, has no seal: ended with its binding all the same, its row
+    -- revoked with no change, the log holding no object of it.
+    PERFORM 1 FROM public.credentials c WHERE c.id = ANY(p_creds) ORDER BY c.id FOR UPDATE;
+    IF (SELECT count(*) FROM unnest(p_creds, p_cred_binding, p_cred_mac_from, p_cred_seal_from) AS x(id, binding, mac, seal)
+          JOIN public.credentials c ON c.id = x.id AND x.binding = ANY(p_ends) AND c.created_by = 'binding:' || x.binding::text
+                                   AND c.revoked_at IS NULL AND c.auth_mac = x.mac AND c.seal IS NOT DISTINCT FROM x.seal)
+       <> cardinality(p_creds)
+       OR EXISTS (SELECT 1 FROM unnest(p_ends) AS e(id) JOIN public.credentials c
+                    ON c.principal = p_principal AND c.created_by = 'binding:' || e.id::text AND c.revoked_at IS NULL AND c.expires_at > now_ts
+                   WHERE NOT (c.id = ANY(p_creds))) THEN
+        RETURN json_build_object('state', 'moved');
+    END IF;
+    IF p_make THEN
+        -- The account's live bindings as the app read them, which it weighed this one beside (an issuer's keys moved, the
+        -- bindings it replaces): another made or ended since is read again. Under the account's row's lock, which every
+        -- bind takes, so two binds take turns. At most `p_max`, those it ends left out.
+        IF ARRAY(SELECT b.id FROM public.service_bindings b WHERE b.principal = p_principal AND b.generation = p_generation AND b.revoked_at IS NULL ORDER BY b.id)
+           IS DISTINCT FROM ARRAY(SELECT l FROM unnest(p_live) AS l ORDER BY l) THEN
+            RETURN json_build_object('state', 'moved');
+        END IF;
+        IF cardinality(p_live) - (SELECT count(*) FROM unnest(p_live) AS l WHERE l = ANY(p_ends)) >= p_max THEN
+            RETURN json_build_object('state', 'full');
+        END IF;
+    END IF;
+    -- IssuePolicyHeld: the issue lock, shared; then, under it, the policy and the slugs this change was weighed on, and the numbers.
+    PERFORM pg_advisory_xact_lock_shared(1668244070, 1);
+    IF (SELECT a.seq FROM public.audit_log a WHERE a.author = 'vault' AND a.action = 'policy.change' AND a.decision = 'allow' ORDER BY a.seq DESC LIMIT 1)
+            IS DISTINCT FROM p_policy_seq
+        OR EXISTS (
+            SELECT 1 FROM unnest(p_protected, p_slugs) AS p(id, slug)
+             WHERE (SELECT e.slug FROM public.environments e JOIN public.projects q ON q.id = e.project_id
+                     WHERE e.id = p.id AND strpos(e.slug, '~') = 0 AND strpos(q.slug, '~') = 0) IS DISTINCT FROM p.slug
+        ) THEN
+        RETURN json_build_object('state', 'policy');
+    END IF;
+    IF EXISTS (SELECT 1 FROM public.audit_log a WHERE a.author = 'app' AND a.subject_principal = p_app_key AND a.action IN ('key.reseal', 'key.rotate')) THEN
+        RETURN json_build_object('state', 'retired');
+    END IF;
+    -- What it ends is a use's input: the fence exclusive (RevokeTakesFence), after the issue lock (PolicyIssueFirst), for
+    -- the statement's work only. A bind that ends nothing takes none.
+    IF cardinality(p_ends) > 0 THEN PERFORM pg_advisory_xact_lock(1668244070, 0); END IF;
+    -- The keys a binding it makes reads, by the names they were asked by: still those names (a rename meanwhile names
+    -- another). Compared, not locked (a key's writer takes the fence before its row: a share lock here, held into the
+    -- fence, would be a cycle; review r3), and once the fence is had, which a rename takes too: one that committed while
+    -- this waited is seen (review r4). With no fence, one that commits after this is a rename after the bind.
+    IF p_make AND (SELECT count(*) FROM unnest(p_read_keys, p_read_names) AS r(id, name) JOIN public.secrets x ON x.id = r.id AND x.key = r.name) <> cardinality(p_read_keys) THEN
+        RETURN json_build_object('state', 'moved');
+    END IF;
+    -- ChangeChecksSeal: each row it ends is its object's newest change's; one put back is stale. A row with no seal is one
+    -- the log never held, or none at all once a seal it had was cleared around the vault: that one is stale too, so the
+    -- log's binding is never ended with no change of it (review r2).
+    IF EXISTS (SELECT 1 FROM unnest(p_ends, p_end_seal_from) AS e(id, seal)
+                WHERE e.seal IS DISTINCT FROM (SELECT l.seal FROM public.log_changes l WHERE l.object = public.log_object('binding', e.id::text) ORDER BY l.number DESC LIMIT 1))
+       OR EXISTS (SELECT 1 FROM unnest(p_creds, p_cred_seal_from) AS x(id, seal)
+                WHERE x.seal IS DISTINCT FROM (SELECT l.seal FROM public.log_changes l WHERE l.object = public.log_object('credential', x.id::text) ORDER BY l.number DESC LIMIT 1)) THEN
+        RETURN json_build_object('state', 'stale');
+    END IF;
+    IF p_make THEN
+        -- Again, now that no lock is left to wait for: a make of the same id that committed meanwhile, its row deleted since,
+        -- is seen; one not yet committed holds the id's key, which this insert then waits for and fails on (review r4).
+        IF EXISTS (SELECT 1 FROM public.log_changes l WHERE l.object = public.log_object('binding', p_id::text)) THEN
+            RETURN json_build_object('state', 'stale');
+        END IF;
+        INSERT INTO public.service_bindings (id, auth_mac, principal, generation, profile, issuer, jwks_uri, jwks, claims, scope, policy, origin, label, created_by, created_at, seal)
+            VALUES (p_id, p_auth_mac, p_principal, p_generation, p_profile, p_issuer, p_jwks_uri, p_jwks, p_claims, p_scope, p_policy, p_origin, p_label, p_created_by,
+                    timestamptz 'epoch' + p_created_at * interval '1 millisecond', p_seal);
+    END IF;
+    UPDATE public.service_bindings b SET revoked_at = ended, revoked_by = p_revoked_by, auth_mac = e.mac, seal = e.seal
+      FROM unnest(p_ends, p_end_auth_mac, p_end_seal) AS e(id, mac, seal) WHERE b.id = e.id;
+    UPDATE public.credentials c SET revoked_at = ended, revoked_by = p_revoked_by, auth_mac = x.mac, seal = x.seal
+      FROM unnest(p_creds, p_cred_auth_mac, p_cred_seal) AS x(id, mac, seal) WHERE c.id = x.id;
+    -- Each object's change, numbered in the order named: the binding made, those ended, their credentials.
+    FOR i IN 1 .. cardinality(p_change_request) LOOP
+        INSERT INTO public.log_changes (number, at, request_id, object, actor, payload, seal, mac)
+            VALUES (nextval('public.log_number'), p_at, p_change_request[i], p_change_object[i], p_actor, p_change_payload[i], p_change_seal[i], p_change_mac[i])
+            RETURNING number INTO n;
+    END LOOP;
+    -- Only rows the log never held, ended: no change, nothing to seal.
+    RETURN json_build_object('number', coalesce(n::text, '0'));
+END
+$$;
+--> statement-breakpoint
+-- A binding's genesis as 0041 made it, but for its scope, held to the object too (PR 9a's review, P3): a row whose scope moved past the cutover's read, under its locks, is not sealed (`moved`: the cutover reads again), rather than sealed to an object every use of it then refuses. A scope is canonical JSON in its object and any JSON in its row: compared as jsonb. One the vault cannot read as a scope is no binding's of 0.14 (`planCutover`), never sealed.
+CREATE OR REPLACE FUNCTION seal_binding(p_id uuid, p_request text, p_at bigint, p_actor text, p_payload text, p_seal bytea, p_mac bytea) RETURNS bigint
+    LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp SET jit = off AS $$
+DECLARE
+    op jsonb := p_payload::jsonb;
+    target uuid := public.log_object('binding', p_id::text);
+    n bigint;
+    done integer;
+BEGIN
+    IF op ->> 'op' IS DISTINCT FROM 'genesis' OR op #>> '{ref,kind}' IS DISTINCT FROM 'binding' OR op #>> '{ref,id}' IS DISTINCT FROM p_id::text
+       OR op #>> '{value,kind}' IS DISTINCT FROM 'binding' OR op #>> '{value,id}' IS DISTINCT FROM p_id::text OR op #>> '{value,origin}' IS NULL OR p_seal IS NULL THEN
+        RAISE EXCEPTION 'not a binding''s genesis: %', p_payload USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+    PERFORM 1 FROM public.audit_chain_head WHERE only_row FOR UPDATE;
+    PERFORM pg_advisory_xact_lock(1668244070, 0);
+    SELECT c.number INTO n FROM public.log_changes c WHERE c.request_id = p_request;
+    IF FOUND THEN
+        IF NOT EXISTS (SELECT 1 FROM public.log_changes c WHERE c.request_id = p_request AND c.object = target AND c.payload = p_payload AND c.seal = p_seal) THEN
+            RAISE EXCEPTION 'request % names another change', p_request USING ERRCODE = 'unique_violation';
+        END IF;
+        RETURN n;
+    END IF;
+    IF EXISTS (SELECT 1 FROM public.log_changes c WHERE c.object = public.log_object('log', 'cutover')) THEN
+        RAISE EXCEPTION 'the log is cut over from 0.14 already: a binding is the vault''s to make' USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+    IF EXISTS (SELECT 1 FROM public.log_changes c WHERE c.object = target) THEN
+        RETURN NULL;
+    END IF;
+    UPDATE public.service_bindings b SET seal = p_seal, origin = op #>> '{value,origin}'
+     WHERE b.id = p_id AND b.seal IS NULL AND b.revoked_at IS NULL AND b.origin IS NULL
+       AND b.principal = op #>> '{value,principal}' AND b.generation = (op #>> '{value,generation}')::integer
+       AND b.profile = op #>> '{value,profile}' AND b.issuer = op #>> '{value,issuer}' AND b.jwks_uri = op #>> '{value,jwksUri}'
+       AND b.claims = op #>> '{value,claims}' AND b.policy IS NOT DISTINCT FROM op #>> '{value,policy}'
+       AND (CASE WHEN b.scope IS NULL THEN 'null'::jsonb WHEN pg_input_is_valid(b.scope, 'jsonb') THEN b.scope::jsonb END) = op #> '{value,scope}';
+    GET DIAGNOSTICS done = ROW_COUNT;
+    IF done = 0 THEN RETURN NULL; END IF;
+    INSERT INTO public.log_changes (number, at, request_id, object, actor, payload, seal, mac)
+        VALUES (nextval('public.log_number'), p_at, p_request, target, p_actor, p_payload, p_seal, p_mac)
+        RETURNING number INTO n;
+    RETURN n;
+END
+$$;

package/dist/migrations/postgres/0048_use_batch.sql

@@ -0,0 +1,59 @@
+-- B2 (T167): a request's several keys in one statement, where each had a call of its own (docs/design/0.15-plan.md,
+-- "As built: T167"; formal/Batching.tla). Each key's use is `use_credential`'s, by ids, as 0046 has it, made in the
+-- request's order in this one transaction: the same reads, the same entry, the same row, so that every guarantee of a
+-- use holds for each key, and the batch adds only what Batching.tla holds of several uses together.
+--
+-- - One fence span: the fence (shared) is taken by the first key's use and kept to the commit, so no change is numbered
+--   among the batch's entries, and every key is decided on the same changes.
+-- - One principal's lock, its strongest first (`p_lock`, StrongestFirst): a batch whose keys take the principal's lock
+--   (the vault's second call, its keys decided) takes it exclusive, after the fence, before its first key. Each key's
+--   use then takes it again as it needs, which its own transaction already holds. Shared for one key then exclusive for
+--   the next, two batches of one principal's would each wait for the other (Postgres ends one after deadlock_timeout).
+-- - Each key counts the cap's set as its own statements read it, the batch's earlier keys included (CountsOwnBatch):
+--   inside the transaction, each sees what the ones before it wrote.
+-- - Nothing else: a key that would take the lock in a first call (`p_decided` false) answers `decide` and writes and
+--   locks nothing, as alone; whether there is a second call is the vault's, once it has every key's rows
+--   (AllDecidedFirst).
+--
+-- Its answer is a JSON array of `use_credential`'s answers, in the request's order. Any key's raise (past the deadline
+-- by Postgres's clock, a lock not had within the hot login's lock_timeout, a replayed request id) rolls the whole batch
+-- back: nothing of it is written.
+CREATE FUNCTION use_batch(
+    p_credential uuid, p_secrets uuid[], p_requests bigint[], p_at bigint, p_purpose smallint, p_places uuid[], p_macs bytea[], p_deadline bigint,
+    p_covers bigint[], p_cover_ats bigint[], p_cover_requests bigint[], p_knowns bigint[], p_known_macs bytea[], p_cap_counts integer[], p_cap_windows bigint[],
+    p_decided boolean[], p_way smallint, p_principal text, p_lock text
+) RETURNS json
+    LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp SET bytea_output = 'hex' SET jit = off AS $$
+DECLARE
+    n integer := coalesce(cardinality(p_secrets), 0);
+    answers json[] := '{}';
+BEGIN
+    IF n = 0
+       OR cardinality(p_requests) IS DISTINCT FROM n OR cardinality(p_places) IS DISTINCT FROM n OR cardinality(p_macs) IS DISTINCT FROM n
+       OR cardinality(p_covers) IS DISTINCT FROM n OR cardinality(p_cover_ats) IS DISTINCT FROM n OR cardinality(p_cover_requests) IS DISTINCT FROM n
+       OR cardinality(p_knowns) IS DISTINCT FROM n OR cardinality(p_known_macs) IS DISTINCT FROM n
+       OR cardinality(p_cap_counts) IS DISTINCT FROM n OR cardinality(p_cap_windows) IS DISTINCT FROM n OR cardinality(p_decided) IS DISTINCT FROM n THEN
+        RAISE EXCEPTION 'a batch names a key at least, and each of its lists one entry a key' USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+    IF p_lock IS NOT NULL THEN
+        -- The fence first, as every use takes it, then the principal's lock, exclusive, before any key (StrongestFirst).
+        PERFORM pg_advisory_xact_lock_shared(1668244070, 0);
+        PERFORM pg_advisory_xact_lock(1668244066, hashtext(p_lock));
+    END IF;
+    FOR k IN 1 .. n LOOP
+        answers := answers || public.use_credential(
+            p_credential, p_secrets[k], p_requests[k], p_at, p_purpose, p_places[k], p_macs[k], p_deadline,
+            p_covers[k], p_cover_ats[k], p_cover_requests[k], p_knowns[k], p_known_macs[k], p_cap_counts[k], p_cap_windows[k],
+            NULL, NULL, NULL, NULL,
+            coalesce(p_decided[k], false),
+            false, NULL, NULL, NULL, NULL,
+            p_way, p_principal
+        );
+    END LOOP;
+    RETURN array_to_json(answers);
+END
+$$;
+--> statement-breakpoint
+REVOKE ALL ON FUNCTION use_batch(uuid, uuid[], bigint[], bigint, smallint, uuid[], bytea[], bigint, bigint[], bigint[], bigint[], bigint[], bytea[], integer[], bigint[], boolean[], smallint, text, text) FROM PUBLIC;
+--> statement-breakpoint
+GRANT EXECUTE ON FUNCTION use_batch(uuid, uuid[], bigint[], bigint, smallint, uuid[], bytea[], bigint, bigint[], bigint[], bigint[], bigint[], bytea[], integer[], bigint[], boolean[], smallint, text, text) TO coffre_vault;

package/dist/migrations/postgres/0049_reads.sql

@@ -0,0 +1,171 @@
+-- The audit pages list 0.15's reads from a sealed projection of its uses (T166; docs/design/0.15-plan.md, "As built: T166"; formal/Reads.tla). With 0.15's log a read writes no 0.14 `secret.read` entry: its use, the slim row of R53, is the record, which names neither whose read it was nor where, and whose MAC cannot cover the number the sequence gives it. So the vault's projector, apart from the checkpointer, writes a row of `log_reads` for each use a signed pair seals: its account, its key's place, the fork it was read in, through a reference the source and its place, and the version read, every one from the sealed objects at the use's number, under a MAC of the vault's over all of it, the number included. The audit pages list them on the whole log, and by member (`log_reads_principal_idx`); a key's or an environment's page lists none in 0.15 (D160). `log_reads_cursor` says how far the projector has gone; the pages say so when it is behind. Nothing of this is on a use's path. Additive: the previous release reads nothing here.
+--> statement-breakpoint
+CREATE TABLE "log_reads" (
+	"number" bigint NOT NULL,
+	"at" bigint NOT NULL,
+	"credential" uuid NOT NULL,
+	"purpose" smallint NOT NULL,
+	"principal" text NOT NULL,
+	"secret" uuid NOT NULL,
+	"environment" uuid NOT NULL,
+	"project" uuid NOT NULL,
+	"place" uuid,
+	"source" uuid,
+	"source_environment" uuid,
+	"source_project" uuid,
+	"version" uuid,
+	"mac" "bytea" NOT NULL,
+	CONSTRAINT "log_reads_mac_check" CHECK (octet_length("log_reads"."mac") = 16)
+) PARTITION BY RANGE ("at");
+--> statement-breakpoint
+CREATE TABLE "log_read_days" (
+	"principal" text NOT NULL,
+	"day" integer NOT NULL,
+	CONSTRAINT "log_read_days_pkey" PRIMARY KEY("principal","day")
+);
+--> statement-breakpoint
+CREATE TABLE "log_reads_cursor" (
+	"only_row" boolean PRIMARY KEY DEFAULT true NOT NULL,
+	"through" bigint NOT NULL,
+	"pair" bigint NOT NULL,
+	"at" bigint NOT NULL,
+	"mac" "bytea",
+	CONSTRAINT "log_reads_cursor_only_row_check" CHECK ("log_reads_cursor"."only_row"),
+	CONSTRAINT "log_reads_cursor_mac_check" CHECK ("log_reads_cursor"."mac" IS NULL OR octet_length("log_reads_cursor"."mac") = 16)
+);
+--> statement-breakpoint
+-- A use's projection once, by its time and number (a unique index of a partitioned table holds its partition key).
+CREATE UNIQUE INDEX "log_reads_number_idx" ON "log_reads" USING btree ("at","number");--> statement-breakpoint
+-- A member's reads, within a day: `log_read_days` says which days hold any, so that a page of theirs reads those days
+-- alone, never a probe of each day since (an index of a partitioned table is each day's; review r6: a member's page
+-- read 26 buffers, then 125 with 100 newer days of others' reads).
+CREATE INDEX "log_reads_principal_idx" ON "log_reads" USING btree ("principal","at","number");--> statement-breakpoint
+INSERT INTO "log_reads_cursor" ("only_row", "through", "pair", "at") VALUES (true, 0, 0, 0);--> statement-breakpoint
+-- A day of reads, made as make_day makes one of uses, and beside it.
+CREATE FUNCTION make_reads_day(p_day date) RETURNS text
+    LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp SET jit = off AS $$
+DECLARE
+    lo bigint := (p_day - date '1970-01-01')::bigint * 86400000;
+    parent text;
+    name text;
+BEGIN
+    FOREACH parent IN ARRAY ARRAY['log_reads'] LOOP
+        name := parent || '_' || to_char(p_day, 'YYYYMMDD');
+        IF to_regclass('public.' || quote_ident(name)) IS NOT NULL THEN
+            IF NOT EXISTS (
+                SELECT 1 FROM pg_inherits i JOIN pg_class c ON c.oid = i.inhrelid
+                 WHERE i.inhparent = to_regclass('public.' || parent) AND c.oid = to_regclass('public.' || quote_ident(name))
+                   AND pg_get_expr(c.relpartbound, c.oid) = format('FOR VALUES FROM (%L) TO (%L)', lo, lo + 86400000)
+            ) THEN
+                RAISE EXCEPTION '% exists, and is not the % of %', name, parent, p_day;
+            END IF;
+            CONTINUE;
+        END IF;
+        BEGIN
+            EXECUTE format('CREATE TABLE public.%I PARTITION OF public.%I FOR VALUES FROM (%s) TO (%s)', name, parent, lo, lo + 86400000);
+            -- pg_dump reads each partition as a table of its own.
+            EXECUTE format('GRANT SELECT ON public.%I TO coffre_backup', name);
+        EXCEPTION WHEN duplicate_table THEN
+            -- Another call made it meanwhile, and committed.
+            NULL;
+        END;
+    END LOOP;
+    RETURN to_char(p_day, 'YYYYMMDD');
+END
+$$;--> statement-breakpoint
+-- A day of reads dropped, once its uses are gone from the log (retention detached their day): what is projected of them
+-- goes with them, before the uses' partition is dropped, so that the day is still found (by its uses' table) until both
+-- are gone, and a drop that gave up is tried again (review r10). While the uses' day is the log's, nothing: 'kept'.
+CREATE FUNCTION drop_reads_day(p_day date) RETURNS text
+    LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp SET jit = off SET lock_timeout = '100ms' AS $$
+DECLARE
+    parent text;
+    name text;
+BEGIN
+    IF EXISTS (SELECT 1 FROM pg_inherits i WHERE i.inhparent = to_regclass('public.log_uses')
+                  AND i.inhrelid = to_regclass('public.' || quote_ident('log_uses_' || to_char(p_day, 'YYYYMMDD')))) THEN
+        RETURN 'kept';
+    END IF;
+    FOREACH parent IN ARRAY ARRAY['log_reads'] LOOP
+        name := parent || '_' || to_char(p_day, 'YYYYMMDD');
+        IF to_regclass('public.' || quote_ident(name)) IS NOT NULL THEN
+            IF NOT EXISTS (SELECT 1 FROM pg_inherits i WHERE i.inhrelid = to_regclass('public.' || quote_ident(name)) AND i.inhparent = to_regclass('public.' || parent)) THEN
+                RAISE EXCEPTION '% is not a day of %', name, parent;
+            END IF;
+            EXECUTE format('DROP TABLE public.%I', name);
+        END IF;
+    END LOOP;
+    DELETE FROM public.log_read_days WHERE day = p_day - date '1970-01-01';
+    RETURN 'dropped';
+END
+$$;--> statement-breakpoint
+-- The projector's write: reads, each once (by its time and number), the projector's row put back over any other at its number (a row planted ahead would otherwise make it skip one: formal/Reads.tla, ReplaceOnConflict; two projectors write the same bytes), each member's days of them (`log_read_days`), and the cursor moved on to `p_through`, never back, with the signed pair at or below it whose floor the next read takes (`p_pair`) and its MAC (CursorMac), in one call, after the rows (IdempotentByNumber, CursorAfterRows). One projector's call at a time, the lock taken before any statement reads. None past the newest signed pair's number (ProjectSealedOnly): the projector holds the pair's signatures itself before it asks.
+-- Only from where the chunk started (`p_from`, FromChecked): a projector another overtook, whose reads retention may since have dropped with their day, writes nothing, nor makes their day again: whether it wrote (review r11: 600 retired reads came back). The days its reads need, made here, once it may write.
+CREATE FUNCTION project_reads(p_reads jsonb, p_from bigint, p_through bigint, p_pair bigint, p_at bigint, p_mac bytea) RETURNS boolean
+    LANGUAGE plpgsql SECURITY DEFINER SET search_path = pg_catalog, pg_temp SET jit = off AS $$
+DECLARE
+    sealed bigint;
+    stands bigint;
+BEGIN
+    PERFORM pg_advisory_xact_lock(1668244070, 166);
+    sealed := (SELECT max(k.upto) FROM public.log_checkpoints k);
+    IF sealed IS NULL OR p_through > sealed THEN
+        RAISE EXCEPTION 'reads through % are past the newest pair, %', p_through, sealed USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+    -- The cursor is the migration's one row: gone, nothing is projected, and the pages say so (review r6).
+    stands := (SELECT c.through FROM public.log_reads_cursor c WHERE c.only_row);
+    IF stands IS NULL THEN
+        RAISE EXCEPTION 'the reads cursor is gone' USING ERRCODE = 'data_corrupted';
+    END IF;
+    IF stands <> p_from THEN
+        RETURN false;
+    END IF;
+    IF EXISTS (SELECT 1 FROM jsonb_array_elements(p_reads) r WHERE (r ->> 'number')::bigint > p_through) THEN
+        RAISE EXCEPTION 'a read past % is no read it projects', p_through USING ERRCODE = 'invalid_parameter_value';
+    END IF;
+    -- Each read's day there to hold it: uses of a log older than the days made ahead (review r4).
+    PERFORM public.make_reads_day(d) FROM (SELECT DISTINCT date '1970-01-01' + ((x ->> 'at')::bigint / 86400000)::integer AS d FROM jsonb_array_elements(p_reads) x) days
+      WHERE to_regclass('public.' || quote_ident('log_reads_' || to_char(d, 'YYYYMMDD'))) IS NULL;
+    INSERT INTO public.log_reads (number, at, credential, purpose, principal, secret, environment, project, place, source, source_environment, source_project, version, mac)
+    SELECT (x ->> 'number')::bigint, (x ->> 'at')::bigint, (x ->> 'credential')::uuid, (x ->> 'purpose')::smallint, x ->> 'principal', (x ->> 'secret')::uuid,
+           (x ->> 'environment')::uuid, (x ->> 'project')::uuid, (x ->> 'place')::uuid, (x ->> 'source')::uuid, (x ->> 'sourceEnvironment')::uuid,
+           (x ->> 'sourceProject')::uuid, (x ->> 'version')::uuid, decode(x ->> 'mac', 'hex')
+      FROM jsonb_array_elements(p_reads) x
+    ON CONFLICT (at, number) DO UPDATE SET credential = excluded.credential, purpose = excluded.purpose, principal = excluded.principal, secret = excluded.secret,
+        environment = excluded.environment, project = excluded.project, place = excluded.place, source = excluded.source, source_environment = excluded.source_environment,
+        source_project = excluded.source_project, version = excluded.version, mac = excluded.mac;
+    INSERT INTO public.log_read_days (principal, day)
+    SELECT DISTINCT x ->> 'principal', ((x ->> 'at')::bigint / 86400000)::integer FROM jsonb_array_elements(p_reads) x
+    ON CONFLICT DO NOTHING;
+    UPDATE public.log_reads_cursor SET through = p_through, pair = p_pair, at = p_at, mac = p_mac WHERE only_row AND through < p_through;
+    RETURN true;
+END
+$$;--> statement-breakpoint
+-- A member's reads, newest first, below a point, at most `p_take`: their days that hold any, newest first, each day's index read in order until the page is full. However many days the log holds, a page reads its member's days and no other (review r6); weighing the empty days made ahead, the planner would otherwise read a busy member's day whole and sort it (measured, T166).
+CREATE FUNCTION log_reads_by(p_principal text, p_at bigint, p_number bigint, p_take integer)
+    RETURNS TABLE (at bigint, number bigint)
+    LANGUAGE plpgsql STABLE SET search_path = pg_catalog, pg_temp SET jit = off SET enable_sort = off SET enable_bitmapscan = off AS $$
+DECLARE
+    d integer;
+    left_over integer := p_take;
+    found_now integer;
+BEGIN
+    FOR d IN SELECT k.day FROM public.log_read_days k WHERE k.principal = p_principal AND k.day <= LEAST(p_at / 86400000, 2147483647) ORDER BY k.day DESC LOOP
+        RETURN QUERY SELECT r.at, r.number FROM public.log_reads r
+         WHERE r.principal = p_principal AND r.at >= d::bigint * 86400000 AND r.at < (d::bigint + 1) * 86400000 AND (r.at, r.number) < (p_at, p_number)
+         ORDER BY r.at DESC, r.number DESC LIMIT left_over;
+        GET DIAGNOSTICS found_now = ROW_COUNT;
+        left_over := left_over - found_now;
+        EXIT WHEN left_over <= 0;
+    END LOOP;
+END
+$$;--> statement-breakpoint
+REVOKE ALL ON FUNCTION make_reads_day(date), drop_reads_day(date), project_reads(jsonb, bigint, bigint, bigint, bigint, bytea),
+    log_reads_by(text, bigint, bigint, integer) FROM PUBLIC;--> statement-breakpoint
+GRANT EXECUTE ON FUNCTION make_reads_day(date), drop_reads_day(date), project_reads(jsonb, bigint, bigint, bigint, bigint, bytea) TO coffre_vault;--> statement-breakpoint
+GRANT EXECUTE ON FUNCTION log_reads_by(text, bigint, bigint, integer) TO coffre_app;--> statement-breakpoint
+GRANT SELECT ON log_reads, log_read_days, log_reads_cursor TO coffre_vault, coffre_app, coffre_backup;--> statement-breakpoint
+-- The pairs' places and times, for the pages to say how far behind the projection is: public, as the notes are.
+GRANT SELECT ON log_checkpoints TO coffre_app;--> statement-breakpoint
+-- Today's, yesterday's and the next three days, as 0035 made the uses' (the projector makes more as it goes).
+SELECT make_reads_day((now() AT TIME ZONE 'UTC')::date + d) FROM generate_series(-1, 3) AS d;