engine: harden vault settings freshness against suppression and cold-device replay

[FSM1]

The vault settings load (#870, PR #903) reports why it fell back to defaults — DefaultsReason::{Suppressed, RolledBack, TimedOut, Unreadable} — but nothing acts on any of them yet, and the freshness bound on a cold device is weaker than the rest of the resolve plane's.

Surfaced by the /security-review and /crypto-privacy-review gates on PR #903. None of these is exploitable for plaintext disclosure — the record is HPKE-sealed and only the login-secret holder can sign at its name — but each lets an adversary who controls the record plane revert a member's explicit configuration.

The residuals

1. A degraded load still applies the hosted-pinning default. A member who chose PinMode::External ("never put my bytes in CipherBox's store") gets Hosted any time the record is withheld or its head block is unreachable. Suppressed names that case but there is no last-known-good settings copy to prefer instead, and no policy for what a host should do when it sees it. Wanted: cache the last gate-passing settings behind the existing SnapshotCache-shaped durable store and prefer them over VaultSettings::default(), so suppression degrades to stale but chosen rather than reverted.

2. A fresh device accepts an arbitrarily old settings record. Rollback defence is the per-name sequence floor, which is device-local. A new install has no floor, so any owner-signed record the network serves is admitted — including one captured before the member rotated a BYO access_token, which the engine would then present as a bearer credential to an endpoint they stopped trusting. Two bounds are available:

• EOL. IpnsRecord::verify checks the signature chain only; verified.validity is available and net/eol.rs::is_expired exists but has one caller (net/liveness.rs). Checking it on this resolve bounds replay to the 90-day EOL window. Deliberately not done in engine: publish and resolve the vault settings record #870 because no resolve path checks EOL today and special-casing one record would be inconsistent — so the decision is "check it everywhere, or here with a stated reason", and it belongs with this issue rather than that slice.
• A body revision. The seal binds [domain, v, structTag, ownerTag] — no name, no sequence, no time — so every settings record the owner ever wrote opens forever. A monotonic revision inside the sealed body, with the highest seen persisted per account rather than per device, survives a fresh floor store and is the only bound that does.

3. A same-sequence fork stays admissible forever. publish mints floor + 1 and the floor advances only behind a confirmed publish, so an Unconfirmed publish followed by a retry yields two distinct owner-signed records at the same sequence. The load admits >= floor with no byte comparison, so a chosen-record adversary picks which one every device sees, permanently. The body revision in (2) disambiguates this; the outer sequence cannot.

Scope

• Durable last-known-good settings, and a stated host policy for Suppressed / RolledBack.
• The EOL decision for the resolve plane, applied consistently.
• A monotonic revision in the settings body (a SETTINGS_RECORD_V bump or a body-schema addition, plus its KAT vectors).
• Tests: a withheld record must not downgrade External to Hosted; a fresh device must refuse a record below the account's highest known revision; an expired EOL is not authoritative.

Gate: Engine Tests (plus Core KATs if the body schema changes).

Split

Decomposed by the scoping pass in this issue's comment thread. This issue is now an umbrella; the work lands in its slices.

• engine: prefer last-known-good vault settings over defaults on a degraded load #928 — prefer last-known-good vault settings over defaults on a degraded load (residual 1). Safe to start immediately.
• engine: check EOL on the vault settings resolve #929 — check EOL on the vault settings resolve (narrows residual 2). After engine: prefer last-known-good vault settings over defaults on a degraded load #928.
• engine: decide the cold-device freshness anchor for the vault settings record #930 — decide the cold-device freshness anchor (a decision, no code). After engine: check EOL on the vault settings resolve #929.
• engine: mint an attempt-scoped monotonic revision in the vault settings body #931 — attempt-scoped monotonic body revision (residual 3). Only under engine: decide the cold-device freshness anchor for the vault settings record #930's options (ii) or (iii).

Two corrections the scoping pass established, against this issue's original framing:

• A body revision is not "the only bound that survives a fresh floor store" — there is no per-account durable store in the engine at all, so EOL is the only bound that survives a fresh device.
• The revision costs no SETTINGS_RECORD_V bump and no KAT regeneration: crates/core treats the settings body as opaque (crates/core/src/seal/settings_record.rs:21).

Depends on

• engine: publish and resolve the vault settings record #870 — the vault settings publish/resolve slice this umbrella hardens; landed in PR feat(engine): publish and resolve the vault settings record #903, so the umbrella and its first child (engine: prefer last-known-good vault settings over defaults on a degraded load #928) are unblocked. Internally the children are a chain: engine: prefer last-known-good vault settings over defaults on a degraded load #928 -> engine: check EOL on the vault settings resolve #929 -> engine: decide the cold-device freshness anchor for the vault settings record #930 -> engine: mint an attempt-scoped monotonic revision in the vault settings body #931.

Blocks

• engine: wire the pin-provider layer across all three modes #871 — it is the first code to dispatch on PinMode, so the silent External -> Hosted downgrade under a withheld record becomes reachable there. Only the durable last-known-good slice is a hard prerequisite.

Part of #655

[FSM1]

Scoping pass — recommendation

Read-only investigation against main at 436685afd. Headline: this issue's three residuals are not one slice, and the premise that a persisted body revision is "the only bound that survives a fresh floor store" is inverted. EOL is the only bound that survives a fresh device; a persisted revision does not, because the engine has no per-account durable store. Details below, then a four-way split.

Finding 0 — the whole settings plane has no production consumer yet

load_settings (crates/engine/src/settings.rs:214) and publish_settings (crates/engine/src/settings.rs:142) are called only from crates/engine/tests/vault_settings.rs:173, :496, :571, :626. crates/engine/src/facade.rs calls neither; no crates/wasm binding exposes them; no TS references them. PinMode (crates/engine/src/content/provider.rs:22) has no match anywhere in the repo — its only references are the definition, two re-exports (crates/engine/src/content/mod.rs:30, crates/engine/src/lib.rs:54), the encode/decode mapping in crates/engine/src/settings.rs:388 and :419-421, and tests.

So residual 1's harm — External silently downgrading to Hosted — does not exist today and becomes real the moment #871 writes the first PinMode dispatch. That is the sharpest ordering fact in this issue and it drives the split.

The EOL question

There is exactly one EOL consult in production code across ~20 resolve paths.

Path	file:line	Checks EOL?
fanout_get_verify (shared record-plane verify)	crates/engine/src/net/fanout.rs:91	No — validity is decoded into VerifiedRecord and dropped
resolve / resolve_gated / resolve_and_hold	crates/engine/src/net/resolve.rs:137, :175, :303	No
RecordPointerFetch::fetch (vault pointer)	crates/engine/src/net/pointer_fetch.rs:35	No
cold_start	crates/engine/src/sync/boot.rs:231	No — doc at boot.rs:161 asserts it reads no clock
resolve_settings	crates/engine/src/settings.rs:257	No
fetch_head_block (root, child, settings)	crates/engine/src/net/adopter.rs:347	No
RootAdopter::adopt / ChildAdopter::adopt	crates/engine/src/net/adopter.rs:140, crates/engine/src/net/child.rs:194	No
adoption gate adopt / adopt_deferred	crates/engine/src/gate/adoption.rs:638, :419	No — verified.validity is never read
accept_share	crates/engine/src/grants/accept.rs:479	No
drain refresh / load-child / observed-sequence	crates/engine/src/sync/drain.rs:666, :701, :1164	No
publish confirm-by-re-resolve	crates/engine/src/net/publish.rs:208	No
facade resolve tick / child read	crates/engine/src/facade.rs:1505, :2175	No
revival (recovery endpoint)	crates/engine/src/net/revival.rs:70-73	No — and deliberately must not
eol_republish	crates/engine/src/net/liveness.rs:193	Yes, needs_renewal only

is_expired (crates/engine/src/net/eol.rs:55) has zero production callers; its only call sites are its own unit tests (eol.rs:253, :258, :263, :271) and one assertion in crates/engine/tests/net.rs:1078.

Recommendation: do not make EOL a fail-closed stage on the shared resolve plane. Scope the rejection to the settings resolve, with the reason stated in blueprint/engine.md.

Reasons, in order of weight.

1. Everywhere-as-a-rejection is a read regression, not a hardening. blueprint/engine.md:133-136 makes a >EOL lapse an availability event recovered by revival, and revival requires a signer. A grantee resolving a dormant owner's scope root holds no signing key, so a gate-level EOL rejection turns "owner offline 90 days" into a hard read failure for every recipient. Nothing in the corpus asks for that.
2. The settings record is the one resolve where the reader is always the signer. settings_name and the seal key are both pure functions of the login secret (crates/engine/src/settings.rs:229-230), so an expired settings record is always recoverable by the party that just refused it — republish. That asymmetry is the stated reason the issue asks for, and it does not generalise to any other record family.
3. The settings record is the one resolve whose degraded outcome silently applies a different policy rather than showing stale data. Every other resolve degrades to stale bytes the user can see; this one degrades to a placement decision the user did not make.
4. Blast radius of the everywhere option, quantified. Neither fanout_get_verify, resolve_gated, the Adopter::adopt trait (crates/engine/src/net/resolve.rs:42), nor gate::adopt* takes a Scheduler or a UnixMillis. Threading one touches 4 shared signatures, 2 adopter impls, ~16 call sites, breaks the documented no-clock invariant at crates/engine/src/sync/boot.rs:161, and requires a seventh gate stage — which means editing GateStage (crates/engine/src/gate/adoption.rs:43-56), the exactly-six assertion at crates/engine/src/gate/adoption.rs:659, and RejectionReason (crates/engine/src/gate/adoption.rs:92).

Test-fixture blast radius for the everywhere option is smaller than it looks but non-zero: engine tests run on VirtualScheduler starting at UnixMillis(0) (crates/engine/src/testkit/fakes/scheduler.rs:83-85) while fixtures hardcode absolute strings — 2027-01-01T00:00:00Z at crates/engine/tests/adoption_gate.rs:46 and crates/engine/tests/grants_mailbox.rs:45, 2099-01-01T00:00:00Z elsewhere — so nothing expires under the virtual clock. The one suite that would change shape is multi_day_eol_timeline_publish_renew_lapse_revive (crates/engine/tests/net.rs:1007), which advances past EOL at :1043/:1076 and then revives manually.

Note a real tension in the corpus worth resolving in the same edit: crates/engine/src/net/eol.rs:8-11 frames EOL as a liveness signal only, while blueprint/engine.md:146 and blueprint/core.md:263 both say the verify chain extracts EOL "for the gate's comparators". Either way this issue must land a blueprint sentence; make it say liveness-plus-settings, and say why.

Clock seam: no new one is needed. load_settings already takes scheduler: &Sch (crates/engine/src/settings.rs:219, bound at :227); resolve_settings (crates/engine/src/settings.rs:237) does not. Threading now: UnixMillis into that one private function is the entire wiring cost. eol::is_expired already fails closed on an unparseable timestamp (crates/engine/src/net/eol.rs:55-57).

Does EOL close residuals 2 and 3?

Neither, fully — and the split matters.

Residual 2, partially. EOL converts "arbitrarily old" into "at most 90 days old". That is a real narrowing and it is exactly the bound every other record in the system nominally has, so it is the consistency answer rather than a special favour. It does not close the motivating scenario: a BYO access_token rotated last week is still inside the window, so the pre-rotation record is still admitted.

Residual 3, not at all. A same-sequence fork is two records minted seconds apart; both are equally fresh and both pass any EOL test. The issue is right about this.

One correction to the issue's framing of residual 2: settings is not weaker than the rest of the resolve plane on cold-device freshness. FloorStore is empty on a fresh install in both namespaces (crates/engine/src/seams/floor_store.rs:74-78), so the adoption gate's sequence and epoch floors are equally absent for the vault root, every child, and every granted scope root. The gate's extra stages (crates/engine/src/gate/adoption.rs:441-546) authenticate the author, not the freshness. Cold-start replay exposure is a universal property of the resolve plane; settings inherits it rather than introducing it.

Is the body revision necessary?

The issue says a revision "persisted per account rather than per device ... survives a fresh floor store and is the only bound that does". There is no per-account durable store to persist it in. SeamTypes/SeamSet (crates/engine/src/seams/mod.rs:79-120) name nine seams; the four durable ones — FloorStore, SnapshotCache, StagingStore, CredentialStore — are all device-local (web: one IndexedDB per browser profile, packages/client/src/worker/browserSeams.ts:45, :52; desktop: one directory per install, crates/desktop-seams/src/snapshot_cache.rs:27). Account separation today is emergent from login-secret-derived key bytes, not from the store.

So the accurate statement is the reverse of the issue's: EOL is the only bound that works on a genuinely fresh device, because it is the only stateless one. A revision is the only bound that works inside the EOL window and against a fork — but only on a device that has already seen a higher one, which a fresh device by definition has not.

Two further constraints if a revision is adopted.

• It must advance before the PUT, not behind the confirm. publish_settings advances its floor only on PublishOutcome::Published (crates/engine/src/settings.rs:201-206), and publish mints floor + 1 (crates/engine/src/net/publish.rs:177). A revision derived from that same confirm-gated floor re-mints the same value on the retry, so the two forks would carry identical revisions and nothing is disambiguated. Only an attempt-scoped, durably-advanced counter separates them.
• The wire cost is far lower than the issue assumes. No SETTINGS_RECORD_V bump and no KAT regeneration are required. Core treats the body as opaque (crates/core/src/seal/settings_record.rs:21-22); the KAT manifest pins only structTag, v, hpkeMode and hpkeInfo (asserted at crates/core/tests/kat_manifest.rs:3640-3646), and the two accept vectors' body fields are arbitrary hex that decodes to JSON, not the engine's det-CBOR body. The engine body schema is entirely unpinned by KAT: adding a key means editing BODY_KEYS (crates/engine/src/settings.rs:410) and letting reject_unknown_keys (crates/engine/src/settings.rs:475) do the rest. Greenfield, so no compat arm. Consequence: crates/core is untouched and no Core KATs gate is needed.

There is also a partial, zero-wire-change close for residual 3 on the publishing device: fanout_get_verify keeps best only on verified.sequence > *seq (crates/engine/src/net/fanout.rs:107-112), so a tie is first-endpoint-wins and adversary-orderable, whereas publish already does the exact byte comparison at equal sequence (crates/engine/src/net/publish.rs:215-221). Persisting the writer's own last-attempted record bytes lets its own devices prefer their own fork deterministically. Other devices of the account, and any fresh device, still cannot tell — that residue is what a revision buys.

Can residual 1 land alone?

Yes, confirmed, and it is the only part that is unblocked.

SnapshotCache exists as a first-class seam (crates/engine/src/seams/snapshot_cache.rs:18), is durable on both hosts (crates/desktop-seams/src/snapshot_cache.rs:27; packages/client/src/seams/snapshotCache.ts:22-30), and resolve_gated already runs the exact cache-first pattern this needs at crates/engine/src/net/resolve.rs:186-202. resolve_settings uses it nowhere — it goes straight from the floor read to fanout_get_verify (crates/engine/src/settings.rs:257).

Three implementation notes.

• Cache the head-block ciphertext, not just the record bytes. Suppression breaks at fetch_head_block (crates/engine/src/settings.rs:272), so caching only the record leaves the same hole. The settings head block is HPKE-sealed, so it satisfies the seam's ciphertext-only-at-rest contract (crates/engine/src/seams/snapshot_cache.rs:7-13) as-is.
• No zeroize change. The cached value is ciphertext; plaintext still appears only inside open_settings_record → decode_settings_body, which is already the terminal owner and zeroizes on every exit including errors (crates/engine/src/settings.rs:402). Nothing new borrows a caller-owned buffer.
• No new decode-side rejection, so rule 8 imposes nothing new here: an LKG read runs the identical version gate, AAD and open path as a network read because it goes through the same open_settings_record (crates/core/src/seal/settings_record.rs:110).

SettingsLoad (crates/engine/src/settings.rs:124-129) needs a third variant — Stale { settings, reason } — so a host can distinguish stale-but-chosen from reverted.

Separately, and independent of any store: the host policy itself is the actual security fix, and it is a handful of lines. A degraded settings load must never widen placement. With no LKG available, Suppressed / RolledBack / TimedOut should fail placement closed (refuse the hosted upload) rather than resolve to PinMode::Hosted. That policy has to be written down whether or not the cache lands, and it is a constraint on #871 more than on this issue.

Proposed split

Four slices, in dependency order.

Slice A — degraded-load policy plus durable last-known-good settings. Closes residual 1.

• SettingsLoad::Stale { settings, reason }; cache the gate-passing head-block ciphertext under a settings key in SnapshotCache; prefer it over defaults on Suppressed / TimedOut / Unreadable / FloorUnreadable.
• State in blueprint/engine.md that a degraded settings load never widens placement, and that with no LKG the placement decision fails closed.
• Files: crates/engine/src/settings.rs, crates/engine/tests/vault_settings.rs, blueprint/engine.md.
• Gate: Engine Tests. No crates/core change, no Core KATs.
• Safe to start immediately. Nothing blocks it and no open PR touches these files.

Slice B — EOL on the settings resolve, with the reason stated. Narrows residual 2.

• Thread now: UnixMillis from the existing scheduler into resolve_settings; refuse an expired record with a new DefaultsReason::Expired, degrading through Slice A's LKG path.
• Record the scoping decision and its rationale in blueprint/engine.md, and reconcile the crates/engine/src/net/eol.rs:8-11 framing with blueprint/engine.md:146.
• Rule 8: the reader's new rejection needs no new encode guard, because the invariant is unrepresentable on the encode side — eol_from(now) is now + 90 days from the injected clock (crates/engine/src/net/publish.rs:182, crates/engine/src/net/eol.rs:40), so publish_settings structurally cannot mint an already-expired record. Same shape as RetentionPolicy::KeepLatest(NonZeroU64). Say this in the PR body rather than adding a guard, and cover it with a test that hand-mints a past EOL and asserts the reader's verdict.
• Files: crates/engine/src/settings.rs, crates/engine/tests/vault_settings.rs, blueprint/engine.md.
• Gate: Engine Tests. Sequence after A — same file, and B's degradation arm wants A's Stale variant.

Slice C0 — the cold-device anchor decision. No code.

• Pick one: (i) accept EOL as the only cold-device bound and close residual 2's remainder with a stated reason; (ii) chain the settings head CID into the vault pointer or root the cold device already gates, which requires reordering cold start since settings currently reads before any vault resolve; (iii) an API-held monotonic counter, which contradicts blueprint/engine.md:129-130 ("no client resolve path ever touches the API's record cache").
• Maintainer decision. Slice D exists only under (ii) or (iii).

Slice D — attempt-scoped monotonic body revision. Closes residual 3, and residual 2 within the EOL window.

• Gated on C0. A key added to BODY_KEYS (crates/engine/src/settings.rs:410), minted from a durable counter advanced before the PUT.
• Rule 8 does apply here: if the reader rejects a revision below the high-water, the encoder must return Err — release-active, never debug_assert! — when asked to mint a non-monotonic revision, with a test that fires in a release build.
• If the counter needs a FloorNamespace::Revision (crates/engine/src/seams/floor_store.rs:74), that is a seam change reaching crates/desktop-seams/src/floor_store.rs, packages/client/src/seams/floorStore.ts:20, crates/wasm/src/seams_bridge.rs and the conformance kit. Reusing the Sequence namespace under a suffixed key avoids that at the cost of a keying convention; worth deciding inside the slice.
• Files: crates/engine/src/settings.rs, crates/engine/tests/vault_settings.rs, plus seam files only under the new-namespace option.
• Gate: Engine Tests. Core KATs is not required unless C0 lands on bumping SETTINGS_RECORD_V, which nothing in the analysis above needs.

Interaction with #871

Slice A must land before #871, and #871 should carry a depends-on edge to it.

Issue #871 writes the first match on PinMode and is therefore the change that makes residual 1 exploitable. Today PinMode is inert (Finding 0), so shipping #871 against the current load semantics ships the External → Hosted downgrade on day one. Slice A gives #871 a SettingsLoad::Stale to dispatch on and a written policy for the no-LKG case, so #871 does not have to invent suppression policy while it is also wiring three placement legs. Slices B, C0 and D are independent of #871 in either direction.

File overlap: both touch crates/engine/src/settings.rs (#871 reads pin_mode and byo at crates/engine/src/settings.rs:51-56). Ordering resolves it.

Interaction with #905

Overlap is real but narrow, and avoidable.

• validate_endpoint (crates/engine/src/content/provider.rs:128) is called by the settings encode path at crates/engine/src/settings.rs:159 and again on decode. engine: settle the BYO endpoint transport and address-range policy #905 changes that function and may add a distinct test_connection verdict, so a signature or verdict-set change lands on a settings.rs call site. Keep Slice A and Slice B clear of validate_endpoint — neither needs it — and this stays a rebase, not a conflict.
• Documentation is the sharper collision. engine: settle the BYO endpoint transport and address-range policy #905 edits the content-plane section of blueprint/engine.md (the pin-provider bullet at blueprint/engine.md:499-504). Slice A's and Slice B's blueprint sentences belong in the record-plane / resolve area (blueprint/engine.md:112-160), not the content plane. Writing them there avoids the collision entirely.

File-collision check

• No open PR touches crates/engine/src/settings.rs, crates/engine/src/net/eol.rs, or crates/engine/tests/vault_settings.rs. Slices A and B are clear of fix: retire every uploaded content block on abandonment #923, feat: report upload progress on the op that drives it #925, test(engine): assert a deep create is adoptable by a second device #922 and feat: harvest the v1 login UI and rewire it to the facade #911.
• blueprint/engine.md is contended by fix: retire every uploaded content block on abandonment #923 and by the engine: settle the BYO endpoint transport and address-range policy #905 agent. Section-level de-confliction as above.
• crates/engine/src/content/provider.rs is touched by no open PR, but the engine: settle the BYO endpoint transport and address-range policy #905 agent is working it uncommitted. No proposed slice needs to edit it.
• core: give callers a way to wipe secret-bearing UnknownFields and Map values #902 in crates/core: no KAT collision, but a source-level one. core: give callers a way to wipe secret-bearing UnknownFields and Map values #902 proposes making Map::insert #[must_use] or zeroize-on-replace. crates/engine/src/settings.rs:25 imports core's Map and calls insert at :363, :367, :374, :375, :379, :386. Slice D adds another insert call, so land D after core: give callers a way to wipe secret-bearing UnknownFields and Map values #902 or expect a mechanical rebase. Slices A and B add none.
• KAT catalog: no proposed slice regenerates a vector. crates/core/kat/manifest.json's settingsRecord section stays byte-identical under a body-schema addition, per the analysis above.
• web: the snapshot seam has no way to ask for the vault root, so apps/web seeds a hardcoded anchor #900 is confined to crates/wasm/src/host.rs plus the TS chain and apps/web; no overlap.

Summary

• Start Slice A now. It is unblocked, wire-free, crates/core-free, collision-free, and it is a hard prerequisite for engine: wire the pin-provider layer across all three modes #871.
• Recommend EOL scoped to the settings resolve with a stated reason, not applied across the resolve plane — the everywhere option is a grantee-lockout regression, not a hardening.
• The body revision is not needed for residual 2 and cannot be made to work on a fresh device with today's seams; it is the only thing that closes residual 3, and only if minted per attempt. Its wire cost is one body key with no version bump and no KAT churn — much cheaper than this issue currently assumes.
• Residuals 2 and 3 collapse into one unanswered design question: what per-account freshness anchor exists. That is Slice C0, and it is a decision, not an implementation.