Authoritative project documentation
Identity, Offline, and Deployment Research Spike
Status
Architecture decision evidence complete on 2026-07-15. Abuse, performance, and recovery measurements remain release gates and are recorded by automated tests and the MVP evidence report.
Questions
- Can a family use secure accounts without an external identity service?
- How can the PWA retain useful offline work without storing reusable browser bearer tokens?
- What installer shape provides a friendly React experience and a safe local executor?
Identity Findings
OWASP currently prefers Argon2id, then scrypt, and specifies PBKDF2-HMAC-SHA-256 at 600,000 iterations when PBKDF2 is used. Cloudflare Workers and current browsers provide Web Crypto PBKDF2, giving both server profiles the same audited primitive. UAT found that the deployed Workers Web Crypto implementation rejects iteration counts above 100,000, independent of the configured CPU allowance. The MVP records that portable work factor in each hash and uses long-password support, generic errors, throttling, recovery controls, and organization isolation as compensating controls. Moving to a stronger portable memory-hard construction remains an explicit post-MVP security task rather than an undocumented per-profile divergence.
OWASP session guidance and browser security guidance support opaque server-side sessions in Secure, HttpOnly, SameSite cookies rather than reusable authentication tokens in local storage. Same-origin PWA/API hosting removes normal cross-origin complexity. Offline writes continue in IndexedDB under the last authorized local workspace, but reconnect requires a live session before push/pull. Local cached data is protected primarily by the device account and storage controls; the UI warns that signing out does not securely erase every OS/browser copy unless the user also clears local data.
A mandatory Keycloak, authentik, ZITADEL, or commercial identity account would add an entire service or third-party dependency for a family. OIDC remains valuable for organizations and is kept as an optional relying-party adapter after MVP.
Primary sources checked 2026-07-15:
- OWASP Password Storage Cheat Sheet
- OWASP Session Management Cheat Sheet
- OWASP CSRF Prevention Cheat Sheet
- MDN secure cookie configuration
- Cloudflare Web Crypto
- NIST SP 800-63B-4
Offline Findings
An offline-capable app needs three distinct layers:
- a cached, versioned application shell;
- an IndexedDB replica and mutation/media outbox; and
- an explicit sync protocol with idempotency, versions, cursors, tombstones, and conflicts.
Service-worker update activation must wait until in-progress UI work is durably in IndexedDB. A client with pending operations can update only when its local schema and sync contract remain compatible; otherwise it keeps the old worker and explains the required recovery/export path.
Scout Bee Findings
| Option | Result |
|---|---|
| Browser-only installer | Cannot safely perform local/SSH deployment; rejected |
| PowerShell-only scripts | Useful operator fallback but not the requested cross-platform React guide; retained as support tooling only |
| Electron/Tauri-style desktop shell | Good UI but larger runtime or extra toolchain/signing complexity for the MVP executor; deferred |
| Go loopback executor with embedded React UI | Single binary, explicit privilege boundary, easy SSH/process control, auditable deployment-plan contract; selected |
Scout does not become a new deployment engine. It applies the same versioned release bundles, Wrangler configuration, Compose files, migrations, backup tools, and health checks that operators can use directly.
Security Abuse Cases
- Cross-organization identifiers must return no protected object or media.
- Replayed sync operations must return their prior result without a duplicate.
- Concurrent edits must not silently overwrite treatment or inspection data.
- Stolen database rows must not reveal passwords, session tokens, or recovery codes.
- Untrusted plan values must not become shell text or escape approved directories.
- Diagnostics and exported plans must never include credentials.
- No-auth configuration must fail on non-loopback bindings.
- Public HTTP, missing production secrets, weak/default secrets, and untrusted release artifacts must fail closed.
Decision
Adopt ADR 0010 and ADR 0011. Optional OIDC, passkeys, native-client PKCE, public links, and provider-specific VM provisioning remain compatible post-MVP work.