docs: Phase 4a auth + security proper-fix spec & plan#174
Merged
Conversation
Captures the architectural-fix design surfaced by /quality:qa Phase 1 (dev-QA) against sipher.sip-protocol.org devnet beta on 2026-05-06. Spec (586 lines) — 11 locked decisions D1-D11: - D1: proper-fix over hotfix (architectural patterns FE X-1, BE X-1/X-2/X-4) - D2: 2 PRs in sipher (FE AuthSync + BE auth surface), reviewable in parallel - D3: AuthSync provider as single source of truth for wallet ↔ JWT ↔ store - D4: 24h JWT TTL + /api/auth/refresh + global 401 interceptor - D5: SIWS-then-signMessage fallback (unblocks Jupiter / OKX / older wallets) - D6: desktop wallet pill dropdown (plain Tailwind/Phosphor, no Radix dep) - D7: /pay/:id/confirm fail-closed with fallback RPC + retry - D8: ESLint rule banning direct process.env.SOLANA_NETWORK reads - D9: SENTINEL_MODE default flips from 'yolo' to 'advisory' - D10: centralized ephemeral state module (Redis-backed-with-fallback) - D11: Solscan link wiring deferred to UI revamp Plan (4,137 lines) — 40 tasks across Phases A-E: - Phase A (PR 1): 18 tasks A0-A18 — FE AuthSync + dropdown + JWT lifecycle - Phase B (PR 2): 19 tasks B0-B19 — BE auth surface hardening - Phase C: integration verification + /quality:qa re-run - Phase D: launch event (X thread #1 publish, Steave DM, gate check) - Phase E (optional): error envelope unification + structured logging Trigger: /quality:qa Phase 1 surfaced 13 high-priority bugs (6 FE + 7 BE) plus 14 next-refactor + 12 polish + 7 architectural patterns. X thread #1 launch HELD pending this fix per CLAUDE.md priors (quality > urgency). Devnet beta soak is >=3 days minimum anyway, so fix slip does not push out the mainnet timeline. Predecessor: docs/superpowers/specs/2026-05-05-phase4-split-devnet-beta-mainnet-design.md
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Captures the architectural fix design surfaced by
/quality:qaPhase 1 (dev-QA) against sipher.sip-protocol.org devnet beta on 2026-05-06./api/auth/refresh+ 401 interceptor), SIWS-then-signMessage fallback, BE auth surface hardening, ephemeral state centralization, and SENTINEL safe-default.Why
/quality:qaPhase 1 surfaced 13 high-priority bugs (6 frontend + 7 backend) plus 14 next-refactor + 12 polish + 7 architectural patterns. The bugs are not 13 independent issues — they are symptoms of architectural gaps:let)process.env.SOLANA_NETWORKdrift (13 backend files leak it)/pay/:id/confirmreturns{valid:true}on RPC error)Patching the symptoms individually leaves the patterns alive. Proper-fix takes ~1.5 extra days vs. hotfix (~3 days vs. ~1.5) but eliminates same-class regressions and provides a foundation for the Phase 4b mainnet launch without inheriting devnet-beta debt.
Trade-off
Launch slips from "tonight" to ~2026-05-09/10. X thread #1 has not been published yet; no external commitment. Devnet beta soak is >=3 days minimum anyway, so the slip does not push out the mainnet timeline.
Test plan
This PR is docs-only; no code changes. Reviewer focus:
[TBD]items)Predecessors
docs/superpowers/specs/2026-05-05-phase4-split-devnet-beta-mainnet-design.mddocs/superpowers/plans/2026-05-05-phase4-split-devnet-beta-mainnet.md~/Documents/secret/claude-strategy/sip-protocol/sipher/session-handoff-2026-05-06-d.md