Companion to website PR 0 (chore(server): freeze the URL surface with a
generated route manifest).
BACKEND_DESIGN.md gains § 4.0, naming the two generated artifacts that are
actually authoritative about the API and what each is authoritative *for*: the
manifest records which URLs exist (introspection-derived, reality), the Swagger
spec records what they mean (annotation-derived, intent). The prose tables in
§ 4 are orientation and can drift; those two files cannot. Also documents
routes.guards.json as a review aid that is explicitly not a contract.
API_V2_PLAN.md marks PR 0 shipped and records its two deviations. The optional
unauthenticated-status snapshot was tried and dropped exactly as that section
allowed — against the dead-port mariadb pool the tests use it sits on the acquire
timeout rather than failing fast — replaced by a deterministic assertion that
every /admin/** and /player/** route still carries requireAuth.
routes.guards.json is committed and staleness-checked even though a diff in it
is not a contract change, because an ungenerated review aid rots into a
misleading one.
The sequencing section is corrected: PR 0 now runs before the CSP pair. The CSP
report-only PR must stand up a POST /api/csp-report collector for `report-to` to
target, which is a new URL under /api/**; landing it first would have left PR 0
generating 200 routes against a 199-route baseline, destroying its own acceptance
test. With PR 0 first, the collector appears as a reviewed, deliberate +1 in the
manifest — the mechanism working as intended.
api-route-inventory.json is unchanged, which is the point: the generator
reproduced it byte-for-byte on first run.
Co-Authored-By: Claude <noreply@anthropic.com>
The API v2 plan is revised down to the work that is actually justified: a CSP
hardening pass and an in-place domain split of the monolithic route wiring.
- Auth merge (httpOnly cookies -> bearer + rotating refresh for every client) is
removed and re-filed as deferred behind trigger conditions. httpOnly+SameSite
is the stronger model, session.service.js already unifies cookie and bearer,
the SSO/PKCE transaction cookies survive any merge, and it dragged the admin
SSE fetch/ReadableStream rewrite along as a dependency for no user-visible
payoff. A revival must first spec refresh-token reuse detection and a rollback
procedure.
- No parallel /api/v2. The URL surface is already grouped by capability, so each
new router file mounts at the prefix it already owns and every URL stays
byte-identical. No dual mount, no per-route migration, no v1 retirement; the
SPA, Discord bot, and Android app are all untouched. API_V2_SKELETON.md is
marked superseded (kept as the recipe if a versioned API is ever forced).
- The /api/mobile facade and app-version floor are deferred with the revival note
that it starts as a one-line alias mount, not ~70 hand-written delegates. The
M11 milestone is dropped from android/PLAN.md.
- Adds PR 0: a generated route manifest, so "every URL is unchanged" is proved by
a zero-line diff rather than asserted in review. The baseline
api-route-inventory.json (199 API routes + 2 internal) is committed here and is
what PR 0's generator must reproduce byte-for-byte.
- Split sequenced as five grouped PRs; CSP fixed to report-only first, then
enforce (the old plan contradicted itself), with the verified delta being just
form-action 'self' and frame-ancestors 'none'.
Co-Authored-By: Claude <noreply@anthropic.com>
Expand the API v2 plan to account for consumers beyond the browser and
insulate the Android app from version churn before the v2 work begins.
- Inventory the three v1 API consumers (browser, Android app, Discord bot)
and map the cross-component contracts (site<->link, site<->mobile).
- Fix two concrete plan bugs: the public shard SSE stream must stay
anonymous (logged-out browsers and the app's ShardStreamClient send no
auth header), and the useShardFeed fetch-rewrite is admin-stream-only.
- Add "Phase 0 - the mobile facade": a version-agnostic /api/mobile
namespace (a thin BFF delegating to current controllers behind pinned
wire shapes), landed before v2 so the auth merge never touches the app.
- Note link/ is essentially out of scope (no PROTOCOL_VERSION bump), with
the admin-stream allowlist split as the only shared seam.
- Resequence PRs (Phase 0 first) and gate v1 retirement on the pre-facade
app fleet aging out via an app-version floor, not the web client.
- Add M11 to docs/android/PLAN.md: migrate the app to /api/mobile + ship
the app-version floor, cross-referenced with the website plan's Phase 0.
Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Companion doc to API_V2_PLAN.md describing PR 1: stand up router/v2/ empty but
wired next to a frozen /api/v1, with a trivial GET /api/v2/version to make the
mount testable and no behavior change. Includes the file tree, the api.router.js
/ v2.router.js wiring, empty capability-router stubs, and acceptance criteria.
Adds a forward link from the plan's PR-1 line to the skeleton doc.
Co-Authored-By: Claude <noreply@anthropic.com>
Plan for website API v2, sequenced in two phases behind a parallel /api/v2:
- Phase 1: retire httpOnly session cookies; unify web + mobile on the existing
bearer access + rotating/revocable refresh model. Separates removable session
cookies from the SSO/email transaction cookies that must stay. SSE moves to
fetch-based streaming with Authorization: Bearer.
- Phase 1b: tighten the shipped CSP for the now-JS-held token (add form-action
'self', frame-ancestors 'none'); self-host fonts + Trusted Types as follow-ups.
- Phase 2: break the monolithic route wiring (admin.routes.js, ~100 routes) into
one router per business capability so the URL predicts the file.
Co-Authored-By: Claude <noreply@anthropic.com>
Add auto-generated project-tree snapshots for the website, link, and
Android-app repos under docs/<repo>/PROJECT_TREE.md, and link them from
the README (adding a previously-missing android/ section). These files
are maintained going forward by the sync-project-tree CI workflow in each
source repo, which opens a PR here whenever the tracked layout changes.
Co-Authored-By: Claude <noreply@anthropic.com>
Post-#26 the JaCoCo→Sonar wiring is live and coverage measures 16.4% on new
code — under the 50% gate. Add COVERAGE_PLAN.md: a bucketed analysis of the
gap (ViewModels 0.1%/1153 lines is the dominant lever; DTOs, repositories,
core utils next) and a phased plan — Phase 0 broadens coverage exclusions to
drop non-unit-testable UI/framework code, Phases 1–4 test DTOs, ViewModels,
repositories, and core. Includes a MainDispatcherRule harness + VM test
pattern and per-phase coverage projections (Phase 2 clears the gate at ~65%).
Cross-linked from PLAN.md §12.1.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Add §12.1 documenting the Android-app SonarQube setup: the coverage gate
failed at 0% because the source-only scan received no JaCoCo report (a
reporting gap, not a testing gap). Records the JaCoCo wiring (jacoco plugin +
report task, sonar.coverage.jacoco.xmlReportPaths, pure-UI coverage
exclusions, a Gradle step in sonarqube.yml) and the 2026-07-22 triage:
3 smells fixed in code, 12 marked Won't Fix (snake_case DTO fields that
mirror the wire contract; idiomatic Compose/nav complexity).
Pairs with RunicGateway/Android-app chore/sonar-coverage-and-cleanup.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
Record the "can't turn off the last notification" class of bug in PLAN.md §11:
the PUT /auth/me/notifications/subscriptions validator requires `streams`, so an
empty set must serialize as {"streams":[]} not {}. kotlinx.serialization drops a
property equal to its default (encodeDefaults=false), so a request DTO field
defaulting to emptyList() gets omitted when empty and the server rejects it 400.
Generalized to any "replace the full set" PUT/POST whose empty value equals a DTO
default. Documents the fix in Android-app fix/notifications-empty-subscriptions.
Co-Authored-By: Claude <noreply@anthropic.com>
Match the website change: the ntfy relay is reached through the public
reverse proxy, which runs outside the compose network and can only reach
a service via a published host port. Update the "no published host port /
internal-only publisher" claims in android/PLAN.md (§11 + §13) and
website/BACKEND_DESIGN.md to describe the published NTFY_HOST_PORT
(default 2586 -> ntfy:80), and note that both devices and the backend
publisher reach ntfy on the public origin.
Co-Authored-By: Claude <noreply@anthropic.com>
Record that the whole /player/* router sits behind requireAuth only (not
requireRole('player')): staff are a superset of players, every handler is
self-scoped to the caller, and staff reach the identical handlers under
/admin/shard/*. This is why a staff account with linked characters gets
its "My characters" and personal notification streams on the mobile
client. Matches the code change in RunicGateway/website.
Co-Authored-By: Claude <noreply@anthropic.com>
Supplements the five curated highlights (docs#34) with the remaining
distinct frames from the same live smoke-test session, in flow order:
home/connected, signed-out + signed-in drawers, login + empty 2FA step,
account overview, recovery-codes pre-generate, and the untrust-all to
empty-list to TOTP-required-again sequence. Extends the screenshots
README with a walkthrough table.
Excludes the raws superseded by the five highlights and pure automation
artifacts (soft-keyboard popups, mid-transition spinners, duplicate Home
landings) that do not represent a distinct app state.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
docs(android): add trusted-devices/MFA live smoke-test screenshots
Live end-to-end smoke test of the Android trusted-device + recovery-code
feature (app PR RunicGateway/Android-app#23) against the local server +
MariaDB on an API 36 emulator. Adds android/screenshots/ with five
captures (login trust step, account Security section, Trusted Devices,
recovery-codes show-once, recovery-code login) and a README documenting
the verified flows — including that trust survives logout (password-only
re-login skipped TOTP) and untrust-all clears the local token.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
@
docs(android): record trusted-devices app implementation in PLAN §4.1.1
Marks §4.1.1 implemented (app PR RunicGateway/Android-app
feature/trusted-devices-mfa) and captures two deliberate design
decisions from the build:
- The trust token DELIBERATELY SURVIVES logout (native analogue of the
rg_trust cookie): it is only consulted at a fresh login, so clearing
it on logout would make the feature a no-op. Kept in a separate,
username-scoped encrypted store; cleared only on Settings→Server
switch, untrust-all, or server-side revocation. Supersedes the earlier
handoff note.
- The login-time trust cap is surfaced + resolved on the Trusted Devices
screen rather than a blocking login modal, since native login already
issued the session.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01NgyHnrNa8WwG3doxvxjuCr
@
Add TRUSTED_DEVICES_MFA.md (the approved design/implementation plan) and fold
the feature into BACKEND_DESIGN §3 (trusted_devices + recovery_codes schema),
§4 (login/totp trust+recovery, /auth/me/trusted-devices*, recovery-codes*,
admin trusted-device + /mfa/reset routes), and §6 (trusted-device security
model + audit actions). Note the app-side trust/recovery flow in android PLAN §4.
Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Add docs/website/ARCHITECTURE.md (canonical copy of the website architecture
Mermaid diagram, with fuller notes) and embed the same diagram in the
website-README mirror. Mirrors the diagram added to the website repo README.
Co-Authored-By: Claude <noreply@anthropic.com>
Record the M10 plan and correct the admin-scope contract:
- §1: narrow the app's exclusion list. The operational admin subset is now
IN scope for staff (moderation, support queue, dashboard/site-mode, content =
news posts + wiki cats/tags). Only the hero/CMS block editor, Discord-bot
config, uo-link config, and OAuth-provider setup remain excluded.
- §6.4: self-service stays role-agnostic under /auth/me/*, but the operational
admin subset now calls /api/v1/admin/** directly, gated by a STAFF/ADMIN menu
access level; bearer is accepted and role re-checked every request.
- §9: add milestone M10 covering the SSO discovery/reachability fixes (native
buttons, no website fallback, encrypted pending PKCE, scrollable drawer, dev
stub IdP) and the staff-operations screens.
Co-Authored-By: Claude <noreply@anthropic.com>
Document the test plan for the bot/ workspace — the last of the three website
npm workspaces without a suite (server + client landed in website PR #86).
Records the shared node --test conventions (no jest/vitest/jsdom; DB pool at a
dead port; Discord objects hand-faked) and maps the meaningful bot behavior to
lock: the normalize/duration/spam pure logic, the invite/site-api/internal-key
single-collaborator units, the messageFilter pipeline (bypass-first decision
order + fixed-duration mute + best-effort recording), and the models with real
shaping logic. Includes the CI + SonarQube coverage wiring to mirror PR #86 and
a suggested phasing.
Co-Authored-By: Claude <noreply@anthropic.com>
Record that the app's HTTPS-only-in-release / HTTP-in-debug rule (ServerUrl,
allowInsecureHttp = BuildConfig.DEBUG) is backed at the platform socket layer
by an explicit network security config: main/release forbids all cleartext, a
debug override re-permits cleartext to loopback only. Matches the fix in
RunicGateway/Android-app (fix/manifest-cleartext-traffic).
Co-Authored-By: Claude <noreply@anthropic.com>
Adds docs/ci/SONARQUBE.md covering the non-blocking push-to-main scan
wired into website, link, and Android-app: server URL, per-repo project
keys/sources, the SONAR_TOKEN secret + SONAR_HOST_URL variable, and how
to onboard a new repo.
Co-Authored-By: Claude <noreply@anthropic.com>
