Legal — Behavior

State machine

Legal documents have no draft state in this codebase — every row inserted is considered live as of published_at. The “state” the user cares about is a derived per-user view:

user × document_type ─┬─ no row in legal_consents (or row with revoked_at != null)
                      │      → requiresReconsent = true; access blocked if type ∈ required set
                      │
                      ├─ row exists for latest (type, locale) document; revoked_at = null
                      │      → isCurrentVersion = true; access allowed
                      │
                      └─ row exists for an older version of the same type; latest not yet accepted
                             → requiresReconsent = true; show "Documents updated — please re-accept"

The selection of “latest” is deterministic: selectDistinctOn(type, ORDER BY published_at DESC, id ASC). The id ASC tiebreaker ensures repeatable picks if two versions land at the same published_at.

Invariants

Golden paths

New user signup (owner_onboarding context)

1. Clerk sign-up completes.
2. The onboarding setup sheet’s terms section renders <LegalAcceptanceForm context="owner_onboarding" standalone={false} />. The form reports its all-boxes-ticked state to the sheet through onAcceptedChange(accepted) on every change, including the initial unticked one, so unticking un-accepts and a consent restored from the sheet’s local persistence is never trusted.
3. Component fetches GET /legal/documents?locale=he → list of latest docs per type.
4. User ticks the platform Terms of Use box. There is no Accept button in embedded mode; the sheet’s single submit button sends the consent together with the rest of the setup.
5. POST /legal/consents with { types: OWNER_LEGAL_DOC_TYPES, context: 'owner_onboarding' }.
6. Service resolves the current document IDs in the requested locale (default he), skips current active evidence already recorded in the applicable scope, and inserts the rest with IP + UA. Evidence references the exact document/version/locale accepted; previous versions remain unchanged.

Returning user, TOS updated to v2

1. App entry → GET /legal/consents/status?organizationId=… → returns per-type rows including server-computed isRequired, resolved organizationId, and requiresReconsent.
2. Only rows with both isRequired and requiresReconsent are missing required acceptance. Router / middleware redirects to the reconsent prompt for that set.
3. User accepts → POST /legal/consents with the missing required types, context: 'reconsent', locale, and organization context when applicable.
4. New legal_consents row inserted; prior row stays as historical evidence of v1 acceptance.

Member joins through a join link (member_onboarding context)

• PublicJoinInfo.requiredLegalDocumentTypes is resolved by the server. Privacy policy, fitness acknowledgement and member_terms are always present on the identity step, before the invitation leaves for Clerk. The member UI lists and links those documents under one required legal checkbox; neither the health acknowledgement nor member_terms is a second checkbox or a later confirmation step. Platform terms_of_use is the owner contract and never appears in the member-join agreement.
• A server-resolved plan paymentLinkUrl or active external provider additionally requires external_payment_acknowledgement. It remains a separate explicit required acknowledgement.
• Public invitation requests and authenticated direct acceptance re-resolve requirements before creating the invitation/membership. The transport retains explicit booleans for server validation, but the member terms boolean mirrors the unified required legal choice rather than a second user decision.
• Analytics consent is separately optional and unchecked. Its disclosure names analytics and session replay; declining never blocks membership and cannot satisfy any legal document.
• Consent is recorded against current exact localized document IDs with member_onboarding context, IP, UA, timestamp and target organization. External evidence is organization-scoped; other types remain platform-level.
• /users/me?organizationId=… and consent-status resolve the selected organization consistently: valid explicit organization first, then membership role priority. Status returns organizationId and isRequired, so clients do not reconstruct requirements.
• Active-member backstop always includes current member terms but never external acknowledgement. Pending-only onboarding may add external acknowledgement.
• Staff can create or invite members without validating or recording member acceptance. No consent evidence is synthesized. The member accepts missing required documents through the existing /accept-terms gate at first login; member invitations remain pending until required consent is recorded.
• A signed-in user with no membership at all is never sent to /accept-terms: owner onboarding and the member join form collect their respective first consent, while admins and coaches have no required platform terms yet. The gate applies once a role with requirements exists.

Optional mobile analytics and session replay

• PostHog remains unconstructed until persisted or newly submitted analytics consent is true. The checkbox defaults unchecked.
• The disclosure explicitly states that product analytics and session replay may record screen interactions to improve the app.
• Replay config is fail-private and explicit: maskAllTextInputs=true, maskAllImages=true, maskAllSandboxedViews=true, captureLog=false, and captureNetworkTelemetry=false.
• Sensitive screens can additionally use PostHogMaskView / maskFromReplay; global masking remains the baseline, not an optional per-screen convention.

Edge cases

Side effects

No events emitted today. Audit trail relies on the row itself.

Permissions