Plan: Worker portal household/person address editor (#983)

New module services/canopy-web/src/api/address.rs (private mod address; in api/mod.rs, SPDX first line) holds the form structs, the typed body-builder, the parse/membership helpers, and the add/edit handlers.

Authorization — gate program scope AND household membership (J4 / IDOR). deny_unless_in_scope(&worker, &form.program, &form.household_id) (fact_editor.rs:21) only checks the worker’s program scope over the household; it does not check that form.person_id belongs to form.household_id, and claim_address verifies only fact-ownership-on-correction, never household membership. So a scoped worker could post an address onto an arbitrary person_id by tampering the hidden field. Add a membership check: after the scope gate, read the household bundle (GET /v1/households/{id}/full → HouseholdFull; the render path reads it anyway) and return error_response(StatusCode::FORBIDDEN, …) unless full.members.iter().any(|m| m.person.id == person_id) (MemberFull.person: Person, batch.rs:29). This is the security control the plan adds; the identical pre-existing gap in the income/expense/asset handlers is routed to a security follow-up (Scope).

Typed body, not json! (leads the B3a story). Build a typed AddressClaimRequest and post ::<AddressClaimRequest, ClaimResponse> — 0 new serde_json::Value literals. (The income/expense editors post ::<Value, Value> with json!, justified by a now-stale "canopy-web has no contracts-persons dep" comment, income.rs:91-92; canopy-web does depend on canopy-contracts-persons, Cargo.toml:38.) Exact imports — canopy-web depends on canopy-contracts-persons but not canopy-contracts-facts, so pull provenance types through the persons re-export:

use std::str::FromStr;                                            // for AddressType::from_str
use canopy_contracts_persons::addresses::{AddressClaimRequest, AddressFactValue, AddressType};
use canopy_contracts_persons::batch::HouseholdFull;              // membership check + render
use canopy_contracts_persons::claims::ClaimResponse;            // NOT top-level re-exported
use canopy_contracts_persons::{Author, VerificationSource};     // re-exports (lib.rs:37-39)

Body-builder (extract to keep the handler ≤100 LOC, B2). worker_sub = worker.worker_id. Use the ctor Author::worker(worker_sub) — not Author::Worker { sub: worker_sub.to_owned() }: Author::Worker.sub is a KeycloakSub(pub String) newtype (canopy_contracts_facts::lib.rs:68), so a bare String is a type error; impl From<&str> for KeycloakSub (:90) lets the ctor take the &str.

fn address_claim_body(
    worker_sub: &str,
    value: AddressFactValue,
    valid_from: NaiveDate,
    valid_to: Option<NaiveDate>,
    fact_id: Option<Uuid>,
) -> AddressClaimRequest {
    AddressClaimRequest {
        value,
        source: VerificationSource::SelfAttestation,
        author: Author::worker(worker_sub),
        origin: Some("worker_portal".to_owned()),
        valid_from,
        valid_to,
        fact_id,
    }
}

Handler shape — copy income.rs:117-174, swapping the body type and adding the membership gate. Extractors AuthenticatedWorker + WritePermission + Extension<Arc<ServiceClients>> + Extension<ServiceTokenSource> + Form<..>, then:

Form structs AddAddressForm / EditAddressForm (#[derive(Deserialize)], axum::extract::Form), mirroring AddIncomeForm:30/EditIncomeForm:50. Fields: household_id: HouseholdId, person_id: PersonId (typed newtypes — they deserialize from the form string and are used in the path/membership check), program, address_type: String, line_1, line_2: Option<String>, city, state, zip, county_fips: Option<String>, effective_date, target_section: Option<String> (="address"). EditAddressForm also carries address_id (→ fact_id) and end_date: Option<String> (→ valid_to, the unedited carrier, mirroring the income edit’s income_claim_body(…​, Some(&form.income_id)) at income.rs:192-203). Parse address_type via AddressType::from_str, effective_date/end_date via NaiveDate::parse_from_str, address_id via Uuid::parse_str — each mapping errors to error_response (no unwrap/expect; declaring address_type as the enum directly would yield a generic Form-rejection 4xx, bypassing the tested error path).

Move semantics — single-fact valid-time correction (owner-ratified). add = fact_id: None. edit/move = fact_id: Some(address_id) = a valid-time correction: the store re-tiles the open window into [old_from, effective_date) (prior value) + [effective_date, ∞) (new value) — exactly a move (services/canopy-persons/src/store/address_versions.rs:276-323; fact_id is the stable identity that survives corrections, :401-402). Uniform with the income/expense editors; no close/DELETE. (A distinct-fact model for a genuine relocation was considered and rejected as inconsistent with every other fact edit; follow-up issue if separate lineages are ever wanted.)

Redacted addresses render read-only. Address.line_1 is Option<String> — None when the street was crypto-shredded (addresses.rs:78, redacted == true). The editor must not let a worker overwrite a shredded street with blank: when address.redacted, render the row read-only (coarse locality only + a "street redacted" note, no edit form). Adding a new address is always allowed. Only non-redacted rows get an edit form.

Render home — deserialize the public /full contract (NOT the private local view). async fn render_address_tab(clients, household_id, program, csrf_token) → String (private, in case_detail/sections/address.rs — see the as-built note) reads GET /v1/households/{id}/full into the public HouseholdFull (member type MemberFull, which carries addresses: Vec<Address>, batch.rs:44; the persons builder populates it, services/canopy-persons/src/store/batch.rs:63,102), iterates members, and renders TabAddressTemplate (also in the section module). Do NOT import case_detail.rs’s `HouseholdFullView/MemberView — they are module-private (:2240,2222) and MemberView has no addresses field; the Household tab reads addresses via a separate per-person call. The tiny name/row/badge helpers are reimplemented locally over the typed enums (ClaimStatus/Author accessors). Using the public contract keeps case_detail.rs out of the render path (B1) while compiling. The handler’s Authorization membership check makes its own HouseholdFull fetch.

Section identifiers — three distinct slugs (mirror expenses exactly).

Composition registration — its OWN full-width row (do not skip; do not share expenses' row). Case-detail sections are explicitly listed per jurisdiction in rulesets/{default,georgia}/composition/case_detail.toml, one section per row at span = 12 (full width); the loader rejects a row exceeding 12 columns, so two span-12 sections cannot share a row. The current maximum is case-detail-renewals-section at row = 19 (:134-136). Add a item = "case-detail-address-section" with row = 20, span = 12 (its own new row — NOT expenses' row 13) to both files. Omitting this = the tab never renders → the dispatch_fetch arm is unreachable → the PRG lands on determination and the e2e gotoWorkerCaseSection('address') times out.

Plugin.toml [data] endpoints are literal URL strings, not Rust consts. endpoints = ["/v1/persons/{person_id}/addresses"] (mirror expenses/Plugin.toml).

B1 — route modules >500 LOC (locked 18). As built: api/address.rs = handlers + forms + helpers + handler tests (~490 LOC, under 500); the render half lives in the section module (off B1) — see the as-built note. case_detail.rs is touched only by the one-line ALLOWED_FOCUS_SECTIONS entry + its assertion (already over 500, stays counted) → B1 count unchanged (18). Verified: cargo xtask quality-budgets reports B1 = 18 (LOCKED).

B2 — fns >100 LOC (locked 122). Handlers ≤100 (the shared author_address_claim ~55, each handler ~30); render_address_tab ~40. Verified LOCKED (actual 118).

B3a — literal serde_json::Value in src (locked 745). Typed body adds 0 — but note the B3a regex matches the literal token serde_json::Value even inside comments/doc-comments: an early doc-comment mentioning it tripped +1, reworded to "untyped JSON literals". Verified LOCKED (745).

B5 — .unwrap_or_default() in src (locked 301). The render Option<String>→String conversions are centralized through one opt helper (a single unwrap_or_default), and that +1 is offset in the same MR by converting a silent unwrap_or_default in auth/mod.rs (token-error body read) into a logged fallback (coding-conventions: no silent failure). Verified LOCKED (301, net 0 — offset, lock not raised, per the "offset, don’t raise" directive).

SPDX first line; module doc mirroring income.rs:1-15.

Imports per Design (incl. use std::str::FromStr;, HouseholdFull).

AddAddressForm/EditAddressForm (typed HouseholdId/PersonId) + address_claim_body (typed, Author::worker, parse-with-error_response).

add_address (fact_id: None) and edit_address (fact_id: Some(parse address_id), end_date → valid_to) following the income.rs:117-174 flow plus the household-membership 403 gate (Authorization).

pub(crate) render_address_tab — deserialize /full into the public HouseholdFull, iterate members, skip/read-only redacted rows, build rows, render TabAddressTemplate.

pub(crate) mod address; beside the sibling mod income; decls in api/mod.rs:28-32.

Register .route("/actions/address/add", post(address::add_address)) + .route("/actions/address/edit", post(address::edit_address)) next to income/expense (api/mod.rs:193-204).

Section plugin mirroring expenses.rs: #[canopy_plugin(slug = "case-detail-address", manifest = "src/case_detail/sections/address/Plugin.toml")], DISPLAY_NAME = "Address", pub async fn fetch(…​) → use crate::api::address::render_address_tab; → render_address_tab(…​).await → finalize_section_html(…​).

Plugin.toml mirroring expenses/Plugin.toml: [plugin.exports] case_sections = ["case-detail-address-section"]; [case_sections.case-detail-address-section]; [data] source = "canopy-persons" endpoints = ["/v1/persons/{person_id}/addresses"]; [permissions]; [i18n].

sections.rs: mod-list (:47-71), a dispatch_fetch arm keyed on the section id "case-detail-address-section" (:282), and assert_registered (:405-429).

Composition: add item = "case-detail-address-section" with row = 20, span = 12 to both rulesets/default/composition/case_detail.toml and rulesets/georgia/composition/case_detail.toml.

case_detail.rs: add "address" to ALLOWED_FOCUS_SECTIONS (:325), bump the length assertion 21→22 (:4353), fix its comment (:4348-4352).

Mirror tab_expenses.html:54-127: native <details>/<summary>, <form action="/actions/address/{add|edit}" method="post"> (plain POST → 303 PRG).

CSRF: hidden _csrf = {{ csrf_token }} (threaded SectionContext.csrf_token → section fetch → render_address_tab → template).

Hidden household_id/program/person_id/target_section (=address).

Render AddressFactValue fields: address_type <select> (residential/mailing), line_1 (required), line_2, city, state (2-char), zip, county_fips, effective_date. Edit carries hidden address_id + end_date.

Redacted rows render read-only (coarse locality + "street redacted" note, no edit form).

Each row carries data-address-row, data-address-id="{fact_id}", and data-address-person-id="{person_id}" so the e2e can target a specific person’s edit form unambiguously (multiple add/edit forms exist per member).

address_claim_body builds the expected AddressClaimRequest — assert once per address_type variant (residential and mailing).

Scope-deny: worker outside the form’s program → deny_unless_in_scope → 403.

Membership-deny: a person_id not in the household’s /full members → 403 (the Authorization control).

PRG: success → Redirect to …focus_section=address&notice=eligibility-changed; error → the error_response 422 fragment (both args escaped).

No parsing newtype is introduced → proptest N/A (note it).

The SnapCaseBuilder seeds no address (given/snap.ts authors only income + expense + membership), so editing requires a baseline first. Add a seedAddress(householdId, personId, {…}) given-lib fn (a POST …/addresses/claims add, fact_id: None, mirroring the income/expense given writers at snap.ts:289,343), OR have STEP 3a add-then-edit — either way the journey exercises the edit/correction path (the fact_id flow), not just add.

changeAddressViaUi(page, { householdId, program, personId, …​address }, onBeforeSubmit?) mirroring addExpenseViaUi (helpers.ts:646-680): gotoWorkerCaseSection(page, { householdId, program, section: 'address' }) → open the person’s edit <details> via [data-address-person-id="${personId}"] (not the ambiguous input[name=person_id]) → fill → PRG wait (Promise.all([ page.waitForURL(/focus_section=address/), submit.click() ])). Carry onBeforeSubmit(page) for the walkthrough shot(…​).

Insert STEP 3a between STEP 3 (baseline determination) and STEP 4 (rent step, spec.ts:136): seedAddress (baseline) then changeAddressViaUi (the move), capture step-03a-address-changed.png. (3a sorts after 3, before 4 — no renumber of STEP 4–6.) The rent step stays. Oracle = read-back of the entered address (relational), per spec.ts:22-40.

Rewrite the spec-header honest-scope bullet (spec.ts:44-47) and the stale STEP 4 inline comment (spec.ts:141, "There is no in-UI address editor").

Walkthrough: rewrite the [NOTE] honest-scope block (:37-49) — drop "no household-address editor yet (#983)"; state the move is now recorded through the editor, the rent increase remaining the shelter-cost driver. Keep the deduction-recompute + derived-monotonic-oracle nuances. Insert a 03a step row (between 03 and 04) with ; drop "there is no in-UI address editor" from row 04’s Action cell (:101). Every image: needs a committed PNG.

walkthroughs/index.adoc: drop the "separate gap, #983" aside if present.

snap.toml: refresh the comment naming #983 as the missing editor (~:729-743) — the row stays Covered [Journey]; keep the scenario id snap.change.address-change-shelter-cascade (:719) and the describe binding (:746) verbatim. No walkthrough_blocked_by, no new binding.

CHANGELOG.adoc == Unreleased / === Added: the worker address editor (routes + typed /claims authoring + membership gate), the journey step, the walkthrough flip.

services.adoc: the new canopy-web capability. No new persons endpoint.

Worker case-detail page + caseworker guide: the new action.

Security (#996, filed): household-membership IDOR check on the existing income/expense/asset editors (same gap this plan fixes for address) — and/or membership enforcement in canopy-persons claim_*.

Feature (#891, pre-existing): address in the fact change-history tab (FactResourceKind::Address + history query + web tab) — already tracked; related to #983.

Deferred affordance (#997, filed): in-UI address remove/close (DELETE …/claims/{fact_id}).