feat: add foreground upload-only diagnostics

PRIVACY.md

@@ -77,8 +77,10 @@ file or vault path, file content, or diagnostic check identifier.
 
 The published helper 2.0.2 contains an optional local runtime for the
 authenticated diagnostics protocol. Publication or installation alone does not
-activate it, and the currently released app does not call it. The runtime starts
-only when an operator separately
+activate it, and the currently released app does not call it. Unreleased app
+source contains the separately user-initiated upload-only flow described below;
+it still cannot activate an unconfigured helper. The runtime starts only when
+an operator separately
 supplies both a read-only diagnostics configuration and a writable private state
 directory; otherwise it creates no listener, credential, mapping, namespace, or
 artifact.
@@ -132,8 +134,9 @@ path, mount alias, operation value, or artifact name. It creates no diagnostics
 telemetry, crash annotation, support-bundle export, Cloud Relay/APNs/StoreKit
 call, discovery request, trust adoption, share, rescan, or Syncthing
 configuration/ignore change. No response has been accepted after a fresh local
-apply on an iPhone; product upload, download, and roundtrip evidence remain
-unset.
+apply on an iPhone. The unreleased app source can set only upload evidence after
+an exact pinned helper attestation; controlled download and roundtrip evidence
+remain unset.
 
 Before the supported installer creates the namespace, the app must send a valid
 signed enablement and the local operator must choose an exact existing Syncthing
@@ -229,6 +232,46 @@ conflicts, history, or tombstones. Lost-key recovery deliberately requires new
 pairing and a separate operator revocation of the surviving old authorization.
 See [app capability, pairing, and namespace readiness](docs/app-capability-pairing-namespace-readiness.md).
 
+### Explicit Foreground Upload Check (Unreleased Source)
+
+After separate pairing, capability negotiation, app consent, operator namespace
+creation, and helper-countersigned authorization, the unreleased app source
+offers a distinct foreground upload check. It starts only after a new user tap
+and confirmation. Opening Settings, upgrading or launching the app, checking
+capability, ordinary synchronization, Relay/APNs activity, or background
+execution never starts it.
+
+The app revalidates the exact existing settled `sendreceive` folder, one
+designated connected and unpaused peer, current engine generation, authenticated
+namespace, expanded Syncthing ignore behavior, and an empty operation slot. It
+does not discover, add, share, pause, reconfigure, trust, or create any
+Syncthing folder, peer, namespace, or ignore rule. If any precondition fails,
+no operation artifact is created.
+
+For one accepted start, the app generates a random operation identifier, two
+random nonces, and exactly 256 random request bytes in memory. It exclusively
+creates one app-signed request in the already authorized visible namespace,
+rescans only the selected folder, and sends one app-signed query byte-for-byte
+on at most eight bounded polls to the fixed TLS-1.3/SPKI-pinned helper endpoint.
+Only the exact paired-helper signature and complete Decision 024 binding for
+that active request/query can set the separate in-memory `upload observed`
+field. HTTP status, reachability, request creation, rescan, timestamps, index or
+idle state, and a synchronized attestation copy cannot set it. Download and
+roundtrip fields remain false and cannot be inferred from upload.
+
+The active operation, request/query bytes, random values, digests, poll state,
+and evidence are not persisted in preferences, Keychain, logs, telemetry,
+crash reports, support bundles, Relay, APNs, StoreKit, or pairing records.
+Leaving the view, cancellation, refresh, app/engine restart, target or
+credential change, timeout, or conflict ends the operation, and a late response
+cannot upgrade it. The request and helper attestation are synchronized opaque
+files and may remain in live folders, peers, backups, versions, conflict copies,
+remote history, deletion records, or tombstones. Expiry, app rollback, or live
+cleanup does not promise removal of those retained copies; they never regain
+validity or become evidence.
+
+See [M5 foreground upload-only readiness](docs/m5-upload-attestation-readiness.md).
+
 ### Data Security
 
 - APNs device tokens are encrypted at rest (AES-256-GCM)

docs/app-capability-pairing-namespace-readiness.md

@@ -4,7 +4,10 @@
 plane is implemented and locally verified. It is not an App Store release or a
 transfer milestone. The published helper baseline is `notify-v2.0.2`; the app
 change remains unreleased until its own PR and later release gates complete.
-Upload, download, and roundtrip evidence are all unset.
+This document records the M3 control-plane boundary. The later unreleased M5
+source adds only the explicit foreground upload leg documented in
+[M5 foreground upload-only readiness](m5-upload-attestation-readiness.md);
+download and roundtrip remain unset.
 
 ## User-controlled scope
 
@@ -53,10 +56,12 @@ cookies, cache, compression, query, or fragment, fixed CBOR media types and
 body limits, and mutually authenticated application signatures. Network
 errors become `capability unavailable`; authenticated protocol, tuple, or
 mandatory-flag mismatches become `unsupported`. Neither state falls back to a
-weaker success. Only the four fixed M3 pairing, capability, namespace-
-enablement, and namespace-authorization paths are accepted. A successful
-capability response can authorize the next explicit control step only through
-its exact signed expiry; it is invalidated on restart, error, or credential
+weaker success. M3 accepts only its four fixed pairing, capability,
+namespace-enablement, and namespace-authorization paths. The separate M5
+source additionally permits only the fixed Decision 024 attestation path; it
+does not permit response-authorization or cleanup calls. A successful
+capability response can authorize the next explicit action only through its
+exact signed expiry; it is invalidated on restart, error, or credential
 transition.
 
 Every persisted pending D022/D023 operation also carries an app-local
@@ -116,7 +121,7 @@ The diagnostics contract is additive. Trigger v1 and Relay v1 are unchanged.
 | M3-capable app | Helper 2.0.2, diagnostics unset | Any Relay v1 | `Capability unavailable`; Trigger v1 remains unchanged. |
 | M3-capable app | Helper 2.0.2, enabled but unpaired | Any Relay v1 | Explicit QR pairing is offered; no trust or namespace is inherited. |
 | M3-capable app | Helper 2.0.2, paired but namespace absent | Any Relay v1 | Authenticated capability can succeed; upload, download, and roundtrip remain unset. |
-| M3-capable app | Helper 2.0.2, explicitly namespace-authorized | Existing or new Relay v1 | D022/D023 control plane active; no transfer artifact exists in this milestone. |
+| M3-capable app | Helper 2.0.2, explicitly namespace-authorized | Existing or new Relay v1 | D022/D023 control plane active; the M3 control plane itself creates no transfer artifact (the unreleased M5 source adds only the explicit foreground upload leg). |
 | App downgrade | Helper 2.0.2 | Any Relay v1 | Old app ignores the additive records; helper stays dormant for it; credentials and namespace copies are retained. |
 | App re-upgrade | Helper 2.0.2 | Any Relay v1 | Read-only reconstruction, fresh capability, and current namespace authorization are required; no operation resumes. |
 
@@ -133,7 +138,7 @@ explicit pairing state machine. This is control-plane evidence only.
 | Authenticated capability | Implemented in production app source; cross-language vectors and a deterministic pinned-transport harness pass. Real-device/helper deployment evidence remains unset. |
 | Pairing | Explicit, fingerprint-confirmed, scoped, restart-safe D022 state machine. |
 | Namespace | Explicit app request plus separate operator creation and helper-countersigned D023 authorization. |
-| Upload | Unset; no request artifact is created by this milestone. |
+| Upload | Unset at this M3 boundary; the M3 control plane creates no request artifact. The unreleased M5 source adds only the explicit foreground upload leg (see the M5 readiness document). |
 | Download | Unset; no response artifact or fresh `ItemFinished` baseline exists. |
 | Roundtrip | Unset; no same-chain directional evidence exists. |
 | Cleanup | No app cleanup runtime in this milestone; helper foundation remains evidence-orthogonal. |

docs/architecture.md

@@ -46,18 +46,18 @@ succeeded” flag:
 | Silent push received locally | This iPhone, unattributed | The iOS remote-notification delegate |
 | Background sync started | This iPhone, unattributed | Entry into the silent-push sync path |
 | Local data progress observed | Background run, or one eligible server/folder check | A fresh, successful incoming file application (`ItemFinished`) |
-| Upload confirmed | Server/folder/check correlation | Not available with the current helper |
-| Download confirmed | Server/folder/check correlation | Not available as a controlled directional proof with the current helper |
-| Full roundtrip confirmed | One matching upload-then-download correlation | Not available with the current helper |
+| Upload observed | Exact app/helper/homeserver/folder/operation correlation | Only an explicit foreground check in unreleased M5 app source can accept the exact paired-helper attestation for its active request/query. |
+| Download observed | Exact controlled response correlation | Not implemented in the app; a helper response or synchronized file alone cannot set it. |
+| Full roundtrip confirmed | One matching upload-then-download correlation | Not implemented; it requires the later controlled download from the same active chain. |
 
 None automatically implies the next. Relay reachability is not a trigger;
 trigger observation is not APNs delivery; push receipt is not background start;
 engine reachability, scans, index updates, `idle`, and 100% completion are not
 local data progress. A successful incoming file application proves that this
 iPhone applied a file change, but not that network bytes moved, which peer
-supplied every block, or that the check caused the change. Upload and controlled
-download therefore remain independent and unset, so a full roundtrip cannot be
-derived.
+supplied every block, or that the check caused the change. Upload is a separate,
+explicitly initiated Decision 024 field in unreleased source. Controlled download
+remains independent and unset, so a full roundtrip cannot be derived.
 
 Server snapshots contain only entitlement, provisioning, backend, and
 per-homeserver Relay observation. The v1 push contains no homeserver/folder
@@ -67,7 +67,7 @@ check can scope fresh local evidence to one folder and its sole configured peer.
 
 #### Manual synchronization-path check
 
-Relay Diagnostics exposes the only entry point. An explicit tap takes a current
+Relay Diagnostics exposes the passive-check entry point. An explicit tap takes a current
 subscription-local event cursor, nanosecond production-time boundary, and engine
 generation, then observes at most five times with 2/4/8/12-second delays. Results
 are kept in memory per unique server/folder pair. Only an unpaused `sendreceive`
@@ -86,20 +86,42 @@ background sync.
 
 Ignore rules, missing paths, an event-buffer overflow, or a runtime folder error
 can prevent an observation and therefore end conservatively as incomplete; they
-never create a false success. A controlled upload/download roundtrip needs a
-separately designed, additive, capability-negotiated helper contract and a
-demonstrably safe app-owned diagnostics namespace. Relay v1 is unchanged by this
-milestone.
+never create a false success. It remains separate from the explicit upload-only
+operation below and cannot populate that operation's evidence. Controlled
+download and roundtrip require their later Decision 024 milestones. Relay v1 is
+unchanged.
 
-#### Opt-in correlated-roundtrip helper runtime — no app evidence yet
+#### Opt-in correlated-roundtrip helper runtime — foreground upload only
 
 [Decisions 021–024](decisions/021-capability-negotiated-helper-contract-for-correlated-roundtrip-proof.md)
 define the proof and rollout boundaries. Helper 2.0.2 is published and its
 immutable digest plus upgrade, downgrade, and forward-recovery path are
 verified. The source tree now also contains the unreleased app-side explicit
 capability, pairing, credential-lifecycle, and namespace-authorization control
-plane. VaultSync 2.0 remains NO-GO; product upload, controlled download, and
-causal roundtrip evidence are all unset.
+plane plus the explicit M5 foreground upload operation. Product upload is
+implemented only to the exact signed-attestation boundary and remains
+unreleased; controlled download and causal roundtrip are unset. VaultSync 2.0
+remains NO-GO.
+
+One upload operation begins only after a user tap and a second localized
+confirmation. The app rechecks the exact current capability, pairing and
+namespace authorization, settled `sendreceive` folder, one designated connected
+unpaused peer, engine generation, path overlap, Syncthing ignore behavior, and
+empty operation slot. It never discovers or configures a peer, share, folder,
+namespace, trust decision, or ignore. A failed preflight creates nothing.
+
+The app generates a fresh operation ID, two nonces, and exactly 256 random
+request bytes in memory; signs Decision 024 types 3 and 4; exclusively creates
+the exact request beneath the already authorized installation; and rescans only
+the selected folder. It sends one byte-identical signed query on the fixed eight
+poll schedule. Only an exact type-5 response from the TLS-pinned paired helper,
+with every key, epoch, binding, operation, digest, nonce, signature, and clock
+gate valid for the still-active tuple, sets `upload observed`. HTTP status,
+request creation, rescan, index/idle/completion state, timestamps, and a
+synchronized attestation copy cannot do so. Cancellation, view exit, refresh,
+app/engine restart, target or credential change, timeout, and conflict are
+terminal; late responses never upgrade them. Download and roundtrip remain
+immutable false in this milestone.
 
 The runtime is gated by an operator-authored read-only configuration plus a
 separate writable state directory. If either is absent, existing helpers retain
@@ -192,16 +214,19 @@ namespace, mappings, backups, versions, conflict copies, and tombstones; an old
 helper yields capability unavailable and never a weaker success.
 
 The helper can reconstruct an exact authorized runtime session and process the
-existing D024 foundations, but signatures establish only authorship and causal
+existing D024 foundations. The unreleased M5 app can use only its capability and
+upload-attestation paths, but signatures establish only authorship and causal
 bindings—not transport route, exact network bytes, direct peer, block
 provenance, future delivery, or global sync health. No response has passed a
 fresh post-authorization iPhone cursor/nanosecond/generation/`ItemFinished`
 baseline. Cleanup remains evidence-orthogonal. Helper-first publication,
-production rollout, rollback, and then separate app milestones remain mandatory.
+production rollout, rollback, the M5 real-device/PR gate, and the later download
+and roundtrip app milestones remain mandatory.
 See [helper runtime and packaging readiness](helper-runtime-packaging-readiness.md).
 The app-side scope, compatibility, persistence, consent, and rollback boundaries
 are documented in
-[app capability, pairing, and namespace readiness](app-capability-pairing-namespace-readiness.md).
+[app capability, pairing, and namespace readiness](app-capability-pairing-namespace-readiness.md)
+and [M5 foreground upload-only readiness](m5-upload-attestation-readiness.md).
 
 ### Connection paths & iOS network privacy