# V9-004 authenticated mobile sync

Date: 2026-07-27

## Repository result

The Metis Expo client now has an authenticated transport from its durable
offline queue to the existing Metis xAPI endpoint:

1. `/api/auth/login` verifies credentials;
2. `/api/auth/me` binds the local session to the verified learner UUID;
3. `/api/auth/refresh` rotates an expired or server-rejected access token; and
4. `/api/xapi/statements` receives the queued event UUID as the immutable xAPI
   statement ID.

Native access and refresh tokens are stored as one versioned Expo SecureStore
record. Passwords are never persisted. Web export uses a volatile in-memory
session when SecureStore is unavailable rather than moving refresh credentials
into general browser storage. Remote API origins must use HTTPS; plain HTTP is
accepted only for loopback development.

Concurrent access-token refreshes are coalesced. A 401 response triggers one
rotated-token retry. Expired refresh credentials are deleted, network failure
retains the verified offline principal, and sign-out racing an in-flight refresh
cannot resurrect the session.

## Learner attribution boundary

Offline snapshot schema version 2 binds every new event to the verified learner
UUID before persistence. Signed-out actions do not create progress. A device
cannot append another learner's work behind an account-bound queue, and the
server independently rejects a student statement naming another learner.

Version-1 queue entries have no trustworthy owner. They are migrated to secure
statement UUIDs but remain ownerless and undispatched. The signed-in learner
must use the visible **Link saved progress** action before those entries are
bound and flushed. A failed claim checkpoint or a learner mismatch leaves the
queue intact.

Server conflicts, authorization failures, network failures, and local
acknowledgement failures retain the event and its original identity. The UI
distinguishes sign-in/ownership requirements and statement conflicts without
claiming successful synchronization.

## Automated verification

- `pnpm --dir apps/metis/mobile test --runInBand`: 5 suites, 35 tests passed.
- `pnpm --dir apps/metis/mobile lint`: passed.
- `pnpm --dir apps/metis/mobile typecheck`: passed.
- `pnpm exec vitest run libs/shared/config/src/expo.spec.ts --pool=forks --maxWorkers=1`:
  2 API-origin validation tests passed.
- `PYTHONPATH=src pytest -q tests/test_xapi_api_contract.py`: 5 tests passed,
  including acceptance of the exact mobile statement shape and rejection of a
  different learner ID.
- Ruff check and format verification for the changed API contract test: passed.
- `pnpm metis:contracts:check`: canonical OpenAPI and generated TypeScript
  freshness passed.
- All three Metis Maestro YAML flows parsed successfully.
- `pnpm --dir apps/metis/mobile build`: Expo web export passed with 1,274
  modules. Generated native prebuild directories were removed because this app
  does not track them.

## Rendered QA and device boundary

A Playwright Chromium equivalent was used because the interactive skill's
required `js_repl` tool is unavailable in this session. At 390×844 light and
320×700 dark mobile viewports it verified:

- visible signed-out account, sync, and Resume context;
- masked password input and local invalid-credential feedback;
- signed-out learner-action denial;
- no horizontal overflow or clipped account controls; and
- one-line bundle revision and pending-count status after correcting a narrow
  layout wrap found during the first pass.

The checked-in Android airplane-mode flow now signs in a dedicated learner,
optionally links legacy progress, records and restores an offline event, then
requires the pending count to return to zero after reconnect. It was not
executed in this increment: `METIS_E2E_EMAIL` and `METIS_E2E_PASSWORD` are not
provisioned on this host, and the prior software-emulated API 35 device remains
an invalid infrastructure target. No credential or live delivery result is
claimed.

## Honest boundary

This closes repository wiring for secure session lifecycle, account-bound queue
ownership, xAPI request construction, and authenticated retry behavior. It does
not prove a production learner login, deployed statement, live database
conflict, stable device reconnection pass, mastery merge, or packaged release.
Those operational proofs and the remaining localization, embodiment,
game-bridge, and payout surfaces keep the composite V9-004 checkbox open.
