77 Commits

Author	SHA1	Message	Date
wtclaude	9bc0bf5a3d	feat(events): conditions, phase advancement and the diagnosis panel (Phase 5) ... A phase used to advance on one fact - every step terminal. It can now also carry an advance CONDITION: `{ after: '30m' }` or `{ on: '<triggerId>', where: <conditions>, count: n }`, reusing `engagement/conditions.js` unchanged. The phase's real deliverable is the diagnosis panel: "why didn't phase 3 start?" answered in the condition builder's own words, with the tally, the elapsed time and the last related firing whether or not it counted. `POST /admin/events/runs/:runId/advance` arrives beside it. It has been absent since Phase 3 for want of a meaning; a phase with a gate can wait on a boss that will never spawn, and that is the one state "force it anyway" names. One new table, `event_run_phase_gates`. The emit path writes the tally at the moment a firing happens - a gate waiting on three spawns counts things that occur between two ticks, and a tally held in a process's memory is one a restart silently zeroes - and the runner's tick reads it. A gate that never opens is HELD, with no automatic advance and no authored timeout (org lead, 2026-09-02). What the engine owes instead is visibility: `EVENT_PHASE_STALL_MS` takes the run's health to `stalled`, and `setHealth` is now escalation-only so a later retry cannot demote it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T6t8mrAWhZU5vnyYgZTMtL	2026-09-02 22:11:20 -05:00
wtclaude	6e73660b52	feat(events): schedule, recurrence and the calendar (Phase 4) ... The four closed recurrence shapes computed in the definition's own IANA zone, a fourteen-day materialisation horizon with projections beyond it, series as a managed thing, and the admin calendar that replaces the plugin this feature exists to replace. An event now happens on its own. No schema change: Phase 1 built every column this needed. - events/recurrence.js is the ONE place an occurrence is computed, so the runner's expansion and the calendar's forecast cannot disagree. No date library added — Node ships the tzdata one would vendor, behind Intl. - The runner's materialise leg is now two halves: expand, then sweep. The window starts at `now - grace`, so an occurrence nobody could have seen is never invented retroactively; the horizon is what makes the missed sweep mean anything for a recurrence. - Publishing is the schedule switch and archiving turns it off, and publishing re-pins every occurrence that has not started. - A projection is never drawn over an instant a run occupies, so a cancelled occurrence does not reappear as a forecast. 54 new tests, incl. the DST fixture set the plan asked for and three new statements proved against a real MariaDB. Suite 1768/1711/56 skipped/1 fail (pre-existing CRLF). Walked end to end on the local review stack. Docs: RunicGateway/docs#PENDING Co-Authored-By: Claude <noreply@anthropic.com>	2026-09-02 16:10:16 -05:00
wtclaude	7b570c8ea1	feat(events): the minimal admin surface (Phase 3) ... Three screens, an Events nav group and the six live run controls Phase 1 left absent on purpose because nothing was in flight. An admin can now author, publish, start and watch an event that announces things and cues a human; a moderator can stop one that is going wrong. Six controls, not eight. `advance` is absent because a phase today advances when its steps go terminal — the per-step skip already does that — and Phase 5 is what gives a phase an advance condition. Cancel takes `{ reason }`, not `{ cleanup }`, until Phase 8's ledger exists. Every control is a compare-and-set on the status it may act from, so a console rendered thirty seconds ago cannot act on a run that has moved. Fixes a defect in the Phase 2 runner: `advanceRun` drained up to EVENT_STEPS_PER_TICK steps while only checking the run's status at the top of the tick, so a pause pressed mid-batch did nothing for up to 24 more steps. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T6t8mrAWhZU5vnyYgZTMtL	2026-09-02 08:39:35 -05:00
wtclaude	8e03497eb3	feat(events): schema, CRUD and the core action registry (Phase 1) ... EVENTS_PLAN.md Phase 1. Six of the nine core tables — the ones that do not depend on the module contract — plus definitions CRUD, publish, archive, and the action registry with core as its first registrant. **Nothing dispatches.** There is no runner until Phase 2, so a run row is created and stays `scheduled`. That is this phase's correct answer and the surface renders it verbatim rather than hiding it. Schema (`db/schema.sql`, append-only): event_series, event_definitions, event_versions, event_runs, event_run_steps, event_run_log. The four that need a writer — event_action_settings, event_run_budget, event_run_resources, event_run_participants — arrive with the phases that give them one. Registry (`modules/registries.js` + `config/coreEventActions.js`): registerEventActions staging and commit, with its own id namespace, the closed risk and reversibility sets, revert() required iff and only iff reversible: 'ledger', a bounded budgetMs and a param shape whose every entry needs a type and an example. perform/revert/cost are stripped from everything the catalog serves. Core declares core.announce, core.wait and core.cue through the same staging area a module will use. It is reachable ONLY by registerCore(): loader.js builds its own api facade and has no method that delegates here, so no module can call it and MODULE_API_VERSION is untouched. Phase 7 adds the facade and the bump. Surface (13 routes under /api/v1/admin/events): Reads staff-wide; publish, archive and run creation admin-only from this phase per EVENTS.md §N2, even though the switchboard they will consult does not exist yet — a button that is admin-only later and open now is a gate nobody notices was missing. The live run controls and `verify` are absent rather than stubbed, because nothing is in flight yet. Four things the build settled, all recorded in docs: - event_definitions gained a `spec` column. A draft's working copy cannot be an event_versions row: that table is immutable and a run pins one. - The spec validator must accept its own output. It added `actionVersion` and `dormant` and then refused them as unknown keys, which would have made the second save of any definition — and publish's re-validation — impossible. A test caught it; both are now accepted and recomputed. - A param's `example` is required, optional params included, matching registerEventTriggers. It is the authoring form's placeholder. - Two routes the §API-surface table did not name: GET /admin/events/:id and GET /admin/events/series. Core's three perform() bodies answer { ok: false, retry: false } rather than { ok: true }: `ok: true` on an action that did nothing is a recorded world change that did not occur, which is the exact mistake §F's failure default exists to prevent. `conditions.checkLiteral` is exported and reused for step-param type checking — one switch over the six types, so "is this a datetime" has one answer. Verified: 44 new tests, whole server suite, `npm run check:modules`, routes manifest and swagger regenerated (the manifest diff is +13 routes, zero moved). Docs: RunicGateway/docs#209 Co-Authored-By: Claude <noreply@anthropic.com>	2026-09-01 23:29:07 -05:00
wtclaude	5779d15150	feat(engagement): retention — three sweeps and one recorded refusal ... ENGAGEMENT.md Phase 14, the last phase of the workstream. Four engagement tables grew on every fire and nothing had ever deleted from any of them. Three of them now have a horizon, swept nightly by one worker (utils/engagementRetentionPrune.js — setInterval + unref + stop(), batched 1000 x 50, each table's failure caught on its own so a lock timeout on one does not leave the other two unbounded): engagement_sends 180 days engagement_sends_retain_days (7-3650) engagement_cooldowns 30 days engagement_cooldowns_retain_days (2-3650) engagement_outbox 30 days engagement_outbox_retain_days (2-3650) The fourth, engagement_suppressions, does not expire, and that is the recorded decision rather than an omission: a suppression is a standing decision, and ageing out a hard bounce re-mails an address that already bounced. The way out stays deliberate, and is now reachable per row. Six decisions were settled by the org lead before any code. Two of them widened the phase past what was offered: * the send-log horizon is admin-configurable, so retention got a SCREEN (Admin -> Engagement -> Retention) where team_activity and user_notifications keep theirs in invisible settings rows. The send-log horizon changes what an operator-facing page is able to show, so it has to be visible; the other two came with it, because "what does this deployment keep" is one question. * the suppression purge, which cost a Phase 9 decision. The list deliberately stripped address_hash from every row, so the only way out was a window.prompt asking the operator to retype an address the screen has never shown them. The row had no handle at all. The hash is now returned: this route is admin-only and an admin can already suppress and unsuppress any address they can name, so it grants no capability they lack. GET /sends still strips its own. The outbox sweep is TERMINAL-ONLY and that is a correctness rule: a scheduled row is a send this deployment still intends to make (delay_seconds can put one a day out) and a sending row may be mid-flight. One shipped defect had to be fixed for the sweep to be a bound at all. reclaimStale returned every stale sending row to scheduled, and MAX_ATTEMPTS is consulted only on a graceful retry outcome — so a send that killed the process mid-flight cycled sending -> scheduled -> sending forever, never terminal, therefore never eligible for any sweep. It now fails an exhausted row BEFORE reclaiming the rest; the order is the fix. Two indexes (idx_engo_sweep, idx_engs_sweep): every existing index on those tables has created_at in second position, which serves a per-rule window and is useless to a whole-table horizon. Proved twice: engagementRetentionSql.test.js against a real MariaDB (7 tests, incl. the acceptance case and the wrong reclaim order run deliberately), and the live stack, where a 90-day-old cancelled row was swept and a 90-day-old scheduled row survived. Co-Authored-By: Claude <noreply@anthropic.com>	2026-09-01 15:40:53 -05:00
wtclaude	c208543044	feat(engagement): deliverability — suppression, bounces and the verification gate ... ENGAGEMENT.md Phase 9, closing gap G16. Two mechanisms decide that somebody in a rule's audience does not get the mail, and they sit at deliberately different points in the pipeline. `engagement_suppressions` is checked at DELIVERY: an outbox row can sit through a rule's `delay_seconds` grace window and an address can bounce inside it, so the only correct check is the one taken immediately before the transport call — which is also what produces the `status='suppressed'` row with no transport call at all. The Phase 1b verification gate is applied at ENQUEUE, through a new optional `registerDeliveryChannel({ eligible })` that only `email` declares. Filtering the shared audience would have silenced the wrong sink: a rule spanning email and in-app must still put an item in an unverified user's inbox. The excluded counts reach `summary.ineligible` and the admin reach preview, which until now reported an audience size that was never the number of people who would be mailed. `bounceClassify.js` is the only thing that may write a `bounce` row, and it is deliberately NOT `mailer.PERMANENT_CODES`. That set answers "is retrying pointless?" and contains EAUTH and 554 — an auth failure and a relay-wide policy refusal, neither of which is a fact about the recipient. Reusing it would mean one stale SMTP password suppressing every address the worker touched, silently. The classifier reads the RFC 3463 enhanced status first, falls back to a phrase match only past a veto list and only for 550/551/553, and does not suppress anything it is unsure about. Scope is engagement rules only: resets, invites, verification and the contact form still attempt, matching the posture passwordReset.controller.js already stated. Found on the live rig, against a real MariaDB and a real SMTP conversation: a hard bounce was being recorded as `failed`, so the Send Log's "Bounced" filter — a status `engagement_sends` has carried since §4.5 — matched nothing and always would have. It is now its own outcome; the outbox row stays `failed`, since that ENUM has no `bounced` and a bounced row is one that finished unsuccessfully. `address_masked` is this phase's one addition to §4.5's DDL. A hash-only table cannot be operated — an operator cannot tell three typos from a whole domain refusing mail — and the domain survives while the local part is destroyed, so the column can never be read back as an address book. - schema: `engagement_suppressions` (+ `address_masked`, `created_by`) - `GET/POST/DELETE /api/v1/admin/engagement/suppressions`, and Admin → Engagement → Suppressions, the only way out of the list - `sendNotification` returns `smtp: { code, responseCode, response }` - 26 new tests; swagger, routes manifest and guards regenerated Docs: RunicGateway/docs#191. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-31 10:47:34 -05:00
wtclaude	24a3cd85b3	feat(engagement): the in-app channel, core and web (engagement Phase 7) ... ENGAGEMENT.md Phase 7. `user_notifications`, the in-app DeliveryChannel, the four inbox routes, and the web surface — plus the two pieces earlier phases assigned here that Phase 7's own acceptance line omits. Four decisions settled by the org lead before any code: 1. `inapp` defaults to `instant` — the only channel that does. Push wakes a device somebody is holding and email leaves the building, so both are asked for; an inbox item is a row on a page the user chose to open. Left `off` the channel ships dead. 2. The phase takes push's `deliver` (§2603) and the web per-channel preferences screen (Phase 3's as-built), neither of which its own bullets mention. 3. The inbox takes `/auth/me/notifications` and `/account/notifications`; the preferences screen moves to `…/settings`. The plain word belongs to the content, which is what the bell opens. 4. `ctx.inbox.push` honours the user's in-app preference when `triggerId` names a registered trigger, and writes when it does not. Server - `user_notifications` + `model/userNotifications/`. The dedupe UNIQUE is scoped to the USER, narrower than the outbox's `(rule, user, channel)`: an inbox has no channel dimension, so two rows for one event would be one item shown twice. - `engagement/inappChannel.js` — renders by block ROLE (first heading → title, first button → url, the rest → body) and inserts. `pushChannel.js` — a content-free `{stream, ref}` tickle whose ref deep-links the inbox row. - `engine.liveChannels` orders `inapp` first (`CHANNEL_ORDER`) so that ref resolves on the first sweep. An ordering, not a dependency. - `templates.renderInappByKey` + `resolveTemplate` extracted from `renderByKey`, so both channels take the same fallback chain. - `inapp.event` seed → seedVersion 2: it named `body`/`url`, which nothing supplies. Renamed to the structural vocabulary the projection fills in. - `utils/userNotificationsPrune.js` — nightly, READ items only, horizon in `settings.user_notifications_retain_days` (default 90). - `GET /auth/me/notifications`, `…/unread-count`, `POST …/:id/read`, `POST …/read-all`. Swagger + route manifest + four component schemas. Web - `NotificationBell` in all three headers, polling its badge once a minute and pausing while the tab is hidden. `PlayerInbox` at `/account/notifications`. - The preferences screen becomes a channel matrix over `/auth/me/notifications/channels` — a strict superset of the push-only stream list it replaces. The two legacy endpoints are untouched, so the shipped Android app keeps its wire shape. - Staff get the same two screens at `/admin/notifications…`: `RequirePlayer` keeps them out of `/account`, so without this the inbox was unreachable for every non-player account. `lib/notificationPaths.js` is the one mapping. Verified: 28 new server tests (5 of them against a real MariaDB, for the three index/statement properties that are a server contract rather than a reading of this code) + 3 client. Server suite green, client 327 green. A live rig walked the whole path: two rules on one event produced three outbox rows and exactly one inbox item, the tickle carried `ref: notification:2`, and the retention sweep dropped an aged read row while keeping an equally aged unread one. Docs: RunicGateway/docs#TBD, RunicGateway/runicgateway.com#TBD Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-31 02:07:10 -05:00
wtclaude	065bec7ad8	feat(engagement): the email channel on the engine, and the Teams migration (engagement Phase 6) ... Email becomes a DeliveryChannel driven by rules, and the Team pipeline stops being its own thing. `teamNotify.forumPost` now emits an event; a rule decides who is mailed, through which template, and how often at most. One walk goes forum write -> events.emit -> rule -> outbox -> worker -> email channel -> template -> SMTP. Seven decisions settled by the org lead before any code: - email only moves; the push tickle and the Discord bridge stay direct calls - the EVENT carries its access-checked audience, and `members` resolves to it - the four Team rules are seeded DISABLED, with an admin banner and a note - team_notification_prefs stays, read by the engine as a scoped preference - the payload wins and a structural projection fills the gaps - the digest keeps computing at send time; only its state generalizes - an unsubscribe token turns off the channel it names, and nothing else Three defects found while building it: - `email.button` never absolutized its href, while image and itemList both did. Every rule-driven CTA would have been a dead relative link, because a trigger's url variables are validated site-relative by construction. - Phase 4a enqueued digest-mode recipients for a drain that Phase 6 decided not to build. An outbox row snapshots the payload and so has none of the three properties the digest design exists for, including the security one. - the digest's send-log row carried no address_hash while the instant row beside it did, which would have made half the mail uncorrelatable in Phase 9. Also: engagement_digest_state + a replay-safe backfill, engagement_outbox.scope_key, a v2 unsubscribe token that still verifies v1 forever, and the canonical /public/engagement/unsubscribe pair with the old /public/teams path kept permanently — mail is not editable once sent. Verified with 1464 server tests, 324 client tests, and a live rig (MariaDB + Mailpit + a real Team) covering the instant mail, the digest, the generic template, a pre-migration unsubscribe link and the backfill's replay-safety. Docs: RunicGateway/docs#TBD Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-29 20:11:54 -05:00
wtclaude	3f90070566	feat(engagement): the template editor, the trigger catalog and the send log (engagement Phase 5b) ... Phase 5a gave templates a table, a renderer and nine seeded rows; nothing could change one. This is the screen that lets an operator change one without being able to break the mail the system depends on — plus the two screens Q4 promised Phase 5: Triggers (read-only, from the registries) and the Send Log, which closes G15. The shape follows from one fact: a mail body is rendered by the SERVER, so the preview is too, and framed rather than redrawn in React. A client-side renderer would be a second implementation of the one artifact that matters, agreeing with the send path on the day it was written and drifting from the first Outlook fix on. Settled with the org lead before any code: a shipped default is edited IN PLACE (`protected` blocks deletion and nothing else, `customized = 1` keeps the edit); duplicate is the only way to a new template; `renderByKey` now requires `published`; a test send is logged under a synthetic `core.admin.test-send`; and a template a rule points at refuses deletion with a 409 naming the rules. Three things the plan did not know, found by building it: - The undeclared-variable check cannot be a token scan. `email.itemList.variable` holds a BARE name, so a digest pointed at `itmes` would have saved clean and arrived empty. Blocks now declare `variables(props)`; the editor makes that field a select over the trigger's list variables so the typo is unavailable. - A duplicate that drops `seed_key` loses its variable palette, so duplicating `notify.event` would have been refused for the tokens it was copied with — the one action §4.6.2 offers, refusing itself. The copy inherits it; `customized` is what the seeder actually reads. - `validateEmailBlocks` returns `{ valid, errors }`, not an array, and the first version tested it with `.length` — so block validation never ran at all. Also fixes a Phase 4a defect the live walk found, with the org lead's approval: a rule's template key was checked against a pattern with no dot in it, so no rule could name any template that exists — §4.6.2's whole duplicate-and-point-a-rule-at-it workflow was unreachable. Both models now read one pattern. Verified against the running stack: real multipart mail into a mailpit catcher including an unsaved draft, the draft/published arms both ways through the real mailer path, every refusal, and the end-to-end duplicate → rule → 409 walk. Server 1428 tests green, client 324. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-29 18:13:57 -05:00
wtclaude	4b45eddb5d	feat(engagement): Admin - Engagement - Rules and Audiences (engagement Phase 4b) ... The admin surface over the Phase 4a engine: two screens, twelve routes and the reach preview. Nothing in the engine changed; what changed is that an operator can now reach it. Four decisions settled by the org lead before any code: - segments get their OWN nav entry, "Audiences", not a tab of the rules screen - the on/off switch is its own PATCH route, not a full PUT - the reach preview is a count only, on demand - a rule can be hard-deleted; the send log survives it The switch is the one with real content in it. A PUT re-validates against the registries as they are NOW, so the rules a re-validating toggle cannot switch off are exactly the three an operator most wants stopped: a rule whose module was uninstalled, one naming a channel that is gone, and one whose trigger has since narrowed its ceiling under a saved audience. PATCH .../enabled writes one column and always works. Switching ON unvalidated is safe because the engine re-checks the ceiling at send time. The preview calls the engine's own resolver rather than a second query that agrees with it today, and answers a count and nothing else - the resolver's output for a module-declared segment is a set of players derived from game data. It reports `capped` at the 5000-row bound (the count is a floor, not a total), `reason` for an `owner` audience (which resolves per event and has no advance answer), and `permitted` so the editor cannot show a healthy number beside a save the server will refuse. Two defects found by walking it against a live server, both in Phase 4a's code: 1. A rule pointing at a DORMANT segment read as healthy. listAnnotated asked only whether the segment ROW existed. The other shape of the same failure is a segment sitting exactly where it was whose every audience belongs to an uninstalled module: same outcome, nothing deleted. Uninstalling a module under an enabled rule produced a rule the screen showed as on and firing. The expression walk now lives in engagement/segments.js as `missingAudiences` and both lists ask it. 2. "1 rule still use this segment" - the delete refusal pluralised the noun and not the verb, in the sentence an operator reads when told no. Also: a rule's trigger is now a stated rule rather than an omission in the UPDATE statement (its cooldowns, queued sends and history are all about one trigger id); a condition tree the editor cannot render is shown read-only rather than flattened, because flattening changes which events fire the rule; and literals are coerced client-side to the type the trigger declared, with anything that does not parse passed through unchanged so the server's refusal names the variable. Tests: 21 new server tests (test/engagementAdmin.test.js) and 25 client ones (client/test/engagementRules.test.js), all green. The single failure in the server suite (`the committed manifest matches the declarations in the tree`) is the known Windows CRLF artifact and fails identically on clean edge. Companion docs PR: docs#184. - [x] AI-assisted: written with Claude Code (Opus) Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-29 12:10:04 -05:00
wtclaude	b13ffd584f	feat(notifications): per-channel preferences and the delivery-channel registry (engagement Phase 3) ... `notification_subscriptions` answers one question — which streams a user wants PUSHED — because that is the only question the shipped Android client can ask. This adds the general one: which subscribable ids, on which channel, in which mode. The old table becomes the push projection of the new one and keeps its exact wire shape, so the shipped APK needs no update and no delivery path is touched. What lands: - `engagement/channels.js` — `registerDeliveryChannel` (ENGAGEMENT.md §3.1), the declarative half only: id, label, `carriesContent`, `defaultMode`, `supportsDigest`. `addressFor`/`render`/`deliver` wait for Phases 6 and 7, for the reason `transports/index.js` deferred this file at all. `coreChannels.js` declares push / email / inapp through the subsystem's one door. - `notification_channel_prefs` + a replay-safe `INSERT IGNORE … SELECT` backfill, copying the `announce_jobs → announce_job_legs` precedent. - `GET · PUT /auth/me/notifications/channels`. The PUT is SPARSE — only the `(id, channel)` pairs named are written — deliberately unlike the two whole-set PUTs beside it. `off` is a mode rather than an omission, so this endpoint has no empty-array case and the kotlinx DTO gotcha cannot arise here. Three decisions the org lead settled before any code, and one corrects the phase's own acceptance criterion: push's `defaultMode` is `off`, not `instant`. The plan borrowed "push is opt-OUT" from `team_notification_prefs`, where no row does mean notified — but stream subscriptions have never worked that way, so `instant` would have projected the whole catalog into the legacy GET for every existing user and switched every toggle on in the shipped app after an upgrade nobody asked for. A test pins the legacy GET at `{streams:[]}` for a fresh user. One thing not named by the phase, and it is a G24 consequence rather than scope creep: a trigger ceilinged at `staff` can never reach a non-staff user, so offering the toggle would be offering a dead control AND disclosing the event exists — `uo.cheat.detected` would otherwise appear in every player's screen the moment Phase 11 declared it. Filtered from the catalog and gated on write. That gave the `staff` label its first consumer, now written down as `ceilings.STAFF_CEILING_ROLES` (the admin tier's three, deliberately not `teamGrants.STAFF_ROLES`, which answers a different question). 15 new tests; swagger, route manifest and guards regenerated. No web or app surface — those are Phases 7 and 8, where a preference governs something visible. Refs: docs/website/ENGAGEMENT.md Phase 3, §3.1, §4.5 Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-29 07:08:17 -05:00
wtclaude	563199a096	feat(modules): event triggers, audiences and the ceiling lattice (engagement Phase 2) ... The contract half of the engagement system: a module (and core) can DECLARE an event with a payload contract and fire it. Nothing delivers yet — `emit` validates, logs and stops, and Phase 4 replaces that log line with the engine. `api.registerEventTriggers` and `api.registerAudiences` ride the existing stage()/apply() validate-then-commit discipline, so a registrant that throws halfway leaves nothing behind. `ctx.events.emit` is fire-and-forget and binds the owner from the calling module — a module fires its own triggers and no one else's. `ctx.inbox.push` is present and throws until Phase 7, the shape 1.6.0 settled on for a member that arrives a phase late. MODULE_API_VERSION 1.7.0 on both halves. Additions only; module-uo's `coreApi: "^1.3.0"` still resolves. Three design decisions, approved by the org lead before any code: ONE NAMESPACE for trigger ids and notification-stream ids (ENGAGEMENT.md §7.2, against the recommendation in the text). A trigger is a payload contract attached to an id that may also carry a subscription toggle, so an id has exactly one owner across both facets, checked in both directions. Core's five trigger ids ARE its five stream ids, so the same-owner upgrade case is exercised on every boot rather than only by a module. It keeps notification_channel_prefs single-keyed in Phase 3, where two namespaces would have forced a `kind` discriminator into its primary key. Two knock-on effects appeared only once it was implemented. The id grammar had to be RELAXED to admit `_` inside a segment — §4.3's own worked example is `uo.house.idoc_warning`, and two grammars over one namespace would mean an id legal as a trigger and illegal as the stream it is the same event as. And the seven grandfathered `uo.*` ids had to share their legacy allowlist with triggers, because under one namespace `idoc.warning` is a single id. The push catalog is untouched either way: allStreams() still serves the stream facet only, so the shipped Android client sees exactly what it saw before. THE CEILING LATTICE (G24), which the plan named everywhere and defined nowhere. It is containment, not size: everyone ⊃ authenticated ⊃ {subscribers, members, staff, owner}, with the four leaves mutually incomparable. The flat total order the plan's wording invites would let a `staff`-ceilinged trigger be given an `owner` audience — a rule that mails cheat detection to the player it detected. Fewer people is not less exposure. Two incomparable ceilings have no meet at all, so a composition is refused rather than guessed; union-widens is the intuitive implementation and it is the wrong one. `kind: 'event' | 'scheduled'` is declarable now and no evaluator exists (§7.1 Q6). Registration accepts `scheduled` and emit refuses to fire one, so `kind` means something from the moment it can be written rather than from the moment it is honoured. Also: `GET /admin/engagement/{triggers,audiences}`, served from the registries rather than a table so an uninstalled module simply stops appearing; `npm run engagement:manifest` plus its CI `--check`, the twin of the route manifest, because renaming a variable breaks stored templates silently, at send time, in mail someone already received. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-29 06:40:28 -05:00
wtclaude	fbb4b0bd91	feat(auth): unique, changeable, verifiable email addresses (engagement Phase 1b) ... Makes `users.email` unique, de-duplicates the addresses an upgrade will find, and builds the self-service change-and-verify flow that did not exist. The uniqueness index is on a generated `email_norm AS (LOWER(email)) STORED` column under `utf8mb4_bin`, NOT on `email` under a `_ci` collation as the plan specified. Every case-insensitive collation this server offers is also accent-insensitive: `josé@x.com` and `jose@x.com` compare equal, and those are two different mailboxes. The plan's index would have refused the second address forever and the de-duplication would have nulled a legitimate account's. A requested address is STAGED in `email_pending` and only a tokened link installs it, so a typo cannot silently redirect account-recovery mail. `isDuplicateUsername()` now distinguishes the two indexes. All five call sites branch on it; each answers differently on purpose, because a public form, an IdP callback, a half-completed invite and an admin screen do not owe the same person the same amount of truth. SSO reads the IdP's actual `email_verified`/`verified` claim instead of inferring verification from an address merely being present. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-29 01:53:50 -05:00
wtclaude	6e61146678	refactor(api): collapse /admin/account and /player/account onto /auth/me/account ... Self-service account security had three URL surfaces onto one controller. All three mounted the same `admin/account.controller.js` handlers; each of the three router files carried a header comment apologising for the arrangement. `/auth/me/account` was already a strict superset, which settles which to keep: /admin/account 6 routes noindex, isLoggedIn, staffOnly /player/account 8 routes noindex, requireAuth /auth/me/account 10 routes noindex, requireAuth Neither of the deleted surfaces carried recovery codes, and /admin/account carried no username or password change at all — so client.js already called /auth/me/account/recovery-codes/* for two operations on a screen it otherwise served from /admin/account. The split was leaking before this change. Gating is equivalent where it overlapped: /player and /auth/me apply identical `noindex, requireAuth`, and `staffOnly` on /admin/account was strictly narrower while buying nothing, since every handler is self-scoped to req.user.id. There is no CSRF layer to differ. - 14 routes deleted, 0 added, no handler changed. - account.controller.js moves router/v1/admin/ -> router/v1/auth/, beside the one router that still reaches it. - Web client: 14 call sites move onto a root-level api.myAccount / api.changeUsername / ... group, matching the /auth/me methods already there. - Android app: no change. MeApi.kt was already 100% /auth/me/account/*. - Two swagger tags, `Admin · Account` and `Player`, were declared only by the deleted routes and go with them. The orphaned `AccountStatus` schema goes too; `PlayerAccount` is re-described as the any-role /auth/me/account shape (the name is kept so existing $refs resolve). Breaking to the published OpenAPI surface, accepted deliberately: both consumers are in this org, and deprecate-then-delete would leave the next phase deciding whether to add routes to surfaces already marked for removal. Verification: routes.manifest.json shows exactly 14 deletions and 0 additions. The OpenAPI spec loses the same 14 paths with zero surviving path definitions changed; its large textual diff is pure reordering, because removing the first-mounted router shifts every later path. 1203 server tests, 288 client tests, 53 bot tests green; check:modules, check:hosts and routes:manifest --check all pass. Design of record: docs/website/ENGAGEMENT.md Phase 1a. This lands ahead of engagement Phase 1b, which adds a self-service email field — written once here rather than three times. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-29 00:49:25 -05:00
Claude	c4ab8b9b9d	docs(email): SMTP setup, the three postures, and the upgrade note ... The operator-facing half of engagement Phase 1. README's stack table and security section, plus both .env.example files, all pointed at the removed Connect Gmail flow. The env comments now name the three supported postures rather than one provider — a relay as the recommendation, smtp.gmail.com:587 with an app password as the shortest migration, an unauthenticated local MTA as the third — and point at docs/website/UPGRADE_NOTES.md for the deployment this actually happens to. The OpenAPI spec is regenerated: two routes gone, three annotations rewritten, and the dashboard's new warnings[] documented. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-28 20:54:04 -05:00
wtclaude	61abb3ec89	feat(teams): phase 9 — one voice channel per Team, granted by a role ... TEAMS.md §7.3. Each qualifying Team gets a Discord voice channel of its own and a role that opens it, kept in step by a reconciler that rides the Team reconcile it already depends on. Access is a per-Team ROLE, always. §7.3 designed per-member overwrites with escalation to a role above ~90 members; the org lead settled on roles always (2026-08-18), which deletes `voice_overwrite_max`, the escalation and the `mode` column — and moves the ceiling. Overwrites are capped per channel, so the old shape's limit was "how big can one Team be"; roles are capped per guild at 250, so the new one is "how many Teams can have voice at all". That is a limit an operator must be told about before they hit it, so the panel reports it and the pass refuses the create rather than letting Discord do it. Three things §7.3 named that this codebase does not have, all settled by asking the operator because nothing in the data model can answer: - "the staff role" — there is no staff-role concept anywhere. Now a list of role ids the admin designates; empty is a normal answer, since guild administrators bypass overwrites and what is really missing is a way to let NON-admin staff in. - the parent category — §7.3 said the bot creates it and gave the id nowhere to live (`team_integrations.team_id` is NOT NULL). The bot creates it and the server stores the id in settings. - whether the bot can act at all — nothing has ever checked. The operator invites the bot by hand and no invite URL with a permission integer exists in the tree, so a deployment can be one unticked box from every call failing. A preflight is now a PRECONDITION to enabling (422), not a per-Team error discovered afterwards. Two more, decided rather than asked: - the threshold counts every active member, not linked ones. §7.3 wrote `voice_min_linked_members`; the operator is judging whether a Team is real, and link state answers a different question. - hidden Teams are never provisioned. A channel name is a game-sourced string published outside the site, which is exactly §2.8's concern — reservedNames.js already names "and eventually a Discord channel name" as a surface it protects — so the screen that suppresses a Team's page suppresses its channel, and a Team that becomes hidden takes the grace window. Turning voice OFF tears nothing down: the pass suspends in both directions and the panel offers per-row removal. A checkbox must not delete structure in somebody's guild. Fixes a phase 8 defect that blocks this phase's own artifact: `npm run swagger` has been unable to run on `edge` at all. `param('teamId').custom((v) => ... || /^[0-9]+$/.test(v))` makes swagger-autogen's parser run away — a regex literal followed directly by `.test(`. Hoisted to a const, as modules.router.js already does. Underneath it, `teams.router.js` sits exactly at that parser's per-file limit: at twenty `teamsRouter.*` statements it dies, at nineteen it generates, and one more statement of ANY shape tips it — an unannotated route does, and so does a bare `use`. So the voice routes are their own router file mounted from `admin/index.js`, and teams.router.js keeps its nineteen. Also breaks a require cycle this phase would have introduced: teamSync -> teamVoiceSync -> teams.model -> teamSync left `teams.model` holding the reconciler's exports object as it stood mid-load — the empty one, since `module.exports = {…}` replaces rather than fills. The symptom is not in the new code: it is `teamSync.intervalSeconds is not a function` thrown out of `syncStatus()`, the freshness banner on every public Team page. Tests: 1160 server (+40), 53 bot (+21), 284 client (+21). Swagger, routes manifest and guards regenerated; the guard shape of the four new routes is byte-identical to the existing admin-only ones. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-18 23:49:28 -05:00
wtclaude	11b4368b57	feat(teams): phase 8 — the notifications bridge, and the gate §7.2 could not check ... The same Team event as §6, delivered a third time: push, email, and now a Discord channel the operator configured. Not a second pipeline — teamNotify.js already computed the recipient set once, so the bridge is a sink beside the two that were there. The design's gate has no data source. §7.2 bridges an event only if "its visibility is public, or its destination channel is configured for a members-only Team context". The four team.* streams carry no visibility; forum threads have no public/members column because a forum is members-only by construction; and core cannot see a Discord channel's permissions. So §7.2's own example config names exactly the two events that are never public. The gate is therefore an attributed operator acknowledgement, in the shape teams_forum_uploads_ack already uses. It is a precondition — 422, not a quiet drop at delivery — it is re-asked at delivery as well as at the save, and changing the channel clears it, because an acknowledgement is about a destination and cannot survive the destination changing underneath it. The design's DDL cannot hold its own default row: MariaDB coerces every PRIMARY KEY column to NOT NULL, so `team_id NULL` — the deployment-wide default every override overrides — is unrepresentable. Proved on a real MariaDB (error 1048). Replaced with a surrogate id, a generated team_key AS IFNULL(team_id, 0) in the unique key, and the foreign key the original had no room for. One-shot, not queued: "identical to announce and mod-reverse" names two different reliability models, and a Team notification is the moment it describes. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-18 20:25:30 -05:00
wtclaude	2a56cbf22a	feat(teams): fire the four events, and the routes that configure them ... The roster sync tickles at most ONCE per stream per run, not once per member: a tickle is content-free, so five people joining in one sweep is five identical notifications and one piece of information. Suppressed on a Team's FIRST roster, the same condition the activity feed uses and the half where it matters more — importing a 155-member guild would otherwise wake every one of their phones. Forum notifications fire from the CONTROLLER, not from the forum model. That file takes an already-resolved access decision and reads no membership table by design; the fan-out reads both to compute its recipients, so calling it from inside would make the forum model transitively depend on exactly what its header says it must not touch. The model returns a `notify` key the controller destructures out before the response, so the API's answer to "did my post save" is unchanged. `pageUrlTemplate` joins the team provider — the one thing phase 6 found that the design of record had not anticipated. Phase 3 left core with no Team page and therefore no way to LINK to one, so a notification email could name a Team and not take you to it. It is data rather than a callback: a function would put a module hook on the mail path to produce a string that never varies. Relative paths only, and protocol-relative is refused with absolute. The unsubscribe endpoint is the only write in the public tier and the only route with no `siteMode` — the reader is in their mail client, and the mail went out before the site went into maintenance. POST always answers 200, valid token or forged: distinguishing them would be an oracle for which (user, Team) pairs exist. GET redirects and acts on nothing, so a mail client's link scanner cannot mute Teams nobody asked to leave. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-18 14:34:54 -05:00
wtclaude	fff14848f1	feat(moderation): member-raised abuse reports, to site staff only ... TEAMS.md §5.6. **Core has had no user-facing report flow of any kind** — the `moderation`, `mod_notes` and `appeals` tables are all either staff-initiated or Discord-sanction-shaped, and nothing anywhere let a member say "this is a problem". That was survivable while every piece of content on the site came from staff; phase 5 lets players write to each other, so it stops being. The gap has a specific shape: leaders moderate their own Team's forum, and a Team's leaders are exactly the people who will not report their own Team. So the whole point of this queue is a path that routes AROUND a Team's own leadership. Org lead settled it on 2026-08-18: **reports are site administration only** — there is no leader-facing view of this queue, not even a read-only one scoped to their own Team. §5.6's "a leader may also see and act on reports for their own Team" is not implemented and is not deferred. `content_reports` is deliberately generic — `target_type` is a VARCHAR so a wiki page or a news comment becomes a value rather than a table — and the queue is mounted beside appeals under /admin/moderation rather than under Teams, because a staffer working a queue should have one place to work. **§5.6's literal unique key has a defect and this does not copy it.** Written as (target_type, target_id, reporter_user_id, status) it makes CLOSED rows collide with each other too: reporter reports a post, staff dismiss it, the behaviour recurs, they report again — and the second dismissal is an UPDATE into a tuple that already exists, so working the queue starts throwing duplicate-key errors on the first repeat reporter. The key is on a generated `open_marker` instead, the same trick `team_forum_grants.active_marker` uses: 1 while open, NULL once closed, and NULLs are distinct — which is what §5.6's prose asks for, "one open report per (target, reporter)". Two other departures from the doc, both small and both flagged in the docs PR: `handled_note`, because a queue whose resolution reason lives only in an activity_log line is one where the next staffer to see a repeat report cannot find out why the last was dismissed; and a CASCADE on `team_id`, so a deleted Team does not leave a queue full of reports about content that no longer exists. Also here: a report is filed against a target the model verifies really belongs to the Team the request came through, or the queue's per-Team filter would quietly be lying; the queue resolves every row's target in three batched reads rather than N+1, which is §5.6's fourth rule (uploader, size and sniffed type without hunting) actually paying for §5.5.4's attribution table; a target that has since been hard-deleted comes back null and the report still lists, because "somebody reported this and by the time we looked it was gone" is a fact a moderator needs; and every transition writes activity_log, `dismissed` included — a queue where acting is audited and declining to act is not is one where the cheapest way to make a report vanish leaves no trace. `teams_forum_edit_window_minutes` gains its range validation on the admin settings PUT and is seeded at 15, so the value on the settings screen is the value in force. Route manifest and OpenAPI regenerated: 6 operations added, 0 lost. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-18 12:51:42 -05:00
wtclaude	57286594e7	test(teams): the four acceptance criteria, and regenerate the API artifacts ... Four tests are named "acceptance" and are Phase 4's criteria verbatim. Each names a property the code around it can lose without any screen looking different: 1. A granted, unlinked account reads the forum, is absent from the member rows, and is still refused external-platform eligibility. The membership projection is asserted byte-identical across a grant, which is what "non-contamination" means in practice. 2. With the switch off every forum route 404s AND nothing is read or written on the way there — a guard that 404s after loading the thread is one that still bumped a counter. 3. The stored HTML is byte-identical between `disabled` and `remote`; only the rendered output differs. That is the property the renderer-owned design exists to give, and it is what makes flipping the policy back a no-op rather than a migration. 4. Selecting `uploads` without a matching acknowledgement is refused server-side, with the admin checkbox bypassed. Plus the ones that are not criteria but are the same kind of claim: an author cannot smuggle an <img> or its attributes through in any mode, http and non-image URLs stay plain links, a leader cannot revoke a staff-issued grant, a demoted account stops protecting the grants it made, moderation records which authority was exercised, and a RIFF container that is not WebP is not accepted as one. Twelve new routes in the manifest, all annotated and in the OpenAPI spec. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-18 07:24:24 -05:00
wtclaude	5d9d10b245	refactor(teams)!: Teams is a contract, not a surface — invert the slots ... Org lead's correction, and it changes what this phase ships. TEAMS.md §3.1 and §3.5 put four public pages and three nav rows in core. They should never have been core's. **Teams is the platform primitive that the API contract exposes; the module builds the pages on top of it.** module-uo builds guilds; the Rust module that comes next builds clans. Core does not own the word for a Team, so a core page under a noun core invented would have sat beside module-uo's existing /uo/guilds saying the same thing in the wrong vocabulary. Removed: /teams, /teams/:slug, /teams/:slug/roster, /player/teams, the public and portal nav rows, the `teams` feature flag and the core feature provider that answered it. /admin/teams stays — an operator inspecting the primitive is looking at the primitive. Kept, and unchanged: the tables, the reconciler, the access resolver, the activity feed, the retention prune, the whole public/player/admin API, optionalAuth and the roster projection. That is the contract, and it is what this phase was actually for. **So the extension slots invert, which is a new direction in MODULE_API §3.7.** `team.overview` and `team.member.row` assumed core rendered the page. In their place `registry.declareModuleSlot(id, name)` lets a MODULE declare a place on its own page and core fill it. Core fills `uo.guild.detail` with the Team activity feed — the one part of that page core cannot hand over, because only core can resolve whether the viewer is inside the Team and the public/members split is a security boundary. Three things about the inverted direction are load-bearing: - the name is namespaced under the declaring module and that is enforced, not conventional: it is the only thing keeping two modules off one name; - core's fills are applied at MOUNT rather than eagerly. Core's bundle evaluates before every module chunk, so when core registers a fill the slot does not exist yet — filling eagerly would silently do nothing; - a fill for a slot nobody declared is a no-op, never an error. The declaring module is simply not installed, which is the ordinary case. That is the opposite of §3.7, where an unknown slot throws, and the asymmetry is real: there, core declares first, so an unknown name is always a typo. `Slot` becomes the eighth member of the shared UI kit, so a module renders the place with core's own error boundary. It matters more here than anywhere else in the kit: the thing being contained is core's content failing inside the module's page. `GET /public/teams/by-external/:moduleId/:externalId` is added because a module names a Team in its own vocabulary and core keys the feed by slug. The module id is matched rather than trusted — an external id is unique only within a module. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-17 20:58:07 -05:00
wtclaude	203ce9c654	chore(teams): regenerate the OpenAPI spec and the route manifests ... `npm run swagger` + `npm run routes:manifest` for the one added route, `GET /api/v1/public/teams/:slug/activity`, and for `optionalAuth` joining `/teams/:slug/members`. The guards manifest names `optionalAuth` on both, which is the point of that file: a reviewer can see that two public routes now read the caller's identity without reading the routers. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-17 20:16:04 -05:00
wtclaude	03631d7d40	feat(teams): the roster's audience projection, and optionalAuth to resolve it ... TEAMS.md §3.3, as the eighth member of MODULE_API 1.6.0 — amended in place per the org lead, on the rule Protocol 4 was given in phase 2: a contract owes a bump only once it has landed on `main`. Two questions meet on the roster and they belong to different owners. WHICH ROWS a viewer may see is the module's, because the audience rungs and their configuration live there and core does not know what a rung is. WHAT A ROW LOOKS LIKE stays core's. So `projectRoster` answers with member KEYS, not rows. §3.3 said rows, and rows would let a module widen what is published — handing back a `userId` core had withheld — leaving core's field guarantee resting on every module's good behaviour. Core asks which rows and re-normalises the answer through its own public shape, so a module can narrow and cannot widen. "The module declines" needed splitting before it could be implemented. No module at all and a module whose rungs could not be consulted are opposite situations: the first withholds nothing and must serve the roster whole, the second must serve none of it. The refusal carries `projects`, and only `projects: true` fails closed. Without the split, bare core serves an empty roster on every Team page. This is also the first public route whose CONTENT depends on identity, which needed a middleware core did not have. `attachSession` only decodes a token, so a banned account, a password change or a logout would have kept working against the private half of a feed until the JWT expired. `optionalAuth` runs requireAuth's full database re-validation and, on any failure, continues ANONYMOUSLY rather than rejecting — a caller whose session is no longer good sees the public view, which is what they are entitled to. `GET /public/teams/:slug/activity` lands here for the same reason: §2.11's route table had no activity endpoint though §4.3 describes a filtered feed. Paged, with the visibility resolved from the session and never from a parameter. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-17 20:15:36 -05:00
wtclaude	cf2666e5bc	feat(teams): the Team read API, the moderation routes, and Admin -> Teams ... The eighteen routes of docs/website/TEAMS.md §2.11, their OpenAPI annotations, and the staff screen that drives them. Two rules shape the read model. Hidden means absent from every public surface -- the index, the lookup and the roster alike, and a hidden Team 404s indistinguishably from one that does not exist, because "absent" includes not confirming it is there. And staleness is surfaced rather than silent: every public payload carries { configured, stale, lastSyncAt }, so a page can say how recently the projection was confirmed instead of presenting stale data as current. The public roster withholds both the member key and the user id -- one is a game-internal identifier, the other names a site account. `linked` answers the only question a public page has without publishing which account. The module's per-audience field projection is phase 3's; this is a conservative core one. The §2.9 gate is enforced per REQUEST, not per route. A moderator may call all eighteen; three of them mean something different when they do, and the server decides from the role it re-validates on every request rather than from a token claim. The client has no "file as request" argument to get wrong. Found by booting the real server against the real database, and not by any test: **the index and the by-slug lookup disagreed about what exists.** listPublic was keyed on a registered team provider while findBySlug is not, so with no module installed `/teams` returned an empty list while `/teams/:slug/members` served a full roster -- the index denying a Team that direct URLs answered for in full. The rows are core's and they outlive the module that filled them: an uninstalled module leaves a projection that is unmaintained, not one that stopped existing, and `configured: false` is how a client learns that. The read side no longer takes the provider into account at all. There is now a test named for the property. Also verified live: the public routes answer anonymously, an unknown and a hidden slug both 404, the player and admin tiers 401 an anonymous caller, a seeded roster projects correctly, and the reconciler logs that it is staying idle with no provider registered rather than failing a boot. Process obligations, all done: #swagger.* annotations on every route, `npm run swagger` regenerated (18 paths in the spec, no dangling $refs, and the schemas they reference added), `npm run routes:manifest` regenerated -- additions only, 184 public routes -- and BACKEND_DESIGN.md updated across the schema section and all three tier tables. Admin -> Teams follows the ModulesAdmin precedent: everything that decides what a row SAYS lives in lib/teamAdmin.js, which is plain JS with tests, and the view renders it. That split earns itself here specifically -- the screen's job is to make "the shard has no Teams" and "core has not been able to ask for two hours" impossible to confuse, and those two produce the same empty table. The four freshness states are named and tested for exactly that reason, and the last provider error is shown verbatim rather than paraphrased. The button labels follow the caller's role: a moderator sees "Request publish", so the pending result is not a surprise. Hiding is offered to everyone with no gate, matching the server. Server 894 passed, client 206 passed, client build clean. 17 route tests, 20 client display tests. Refs docs/website/TEAMS.md §2.11, Part 12 phase 2 Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-17 15:27:02 -05:00
wtclaude	b30e82cde2	feat(modules): install, uninstall, purge and restart (phase 4, slice 1) ... The consumer half of a release module-uo's CI has been publishing since phase 3 closed. Before this, core had the installed_modules provenance columns and no code that could ever fill them: nothing fetched, verified, unpacked, removed or purged anything, and there was no admin route at all. Adds modules/archive.js, modules/install.js, schema.runPurge(), lifecycle.stop(), loader.stopHook(), and /api/v1/admin/modules with eight routes. 797 server tests (+76), manifest 158 -> 166 + 2 internal, OpenAPI gains 8 operations and loses nothing. Reject, never sanitise ---------------------- The download is the easy part: an https-only allowlist re-checked on every redirect hop, a declared sha256 compared against the bytes that arrived, and a byte cap. Unpacking is where the archive chooses the filenames, and core writes into a directory bind-mounted from the host, so an escape is not confined to the container. archive.js inspects the whole archive before a byte is unpacked and refuses absolute and drive-absolute paths, `..` segments, NUL bytes, backslashes, anything that is not a regular file or a directory, more than one top-level entry, and anything over the entry or byte caps. Refusing symlinks and hardlinks outright is what keeps this off the majority of node-tar's published advisories rather than depending on the library to contain them. That two-pass shape is load-bearing, and it was measured rather than assumed: extracting an archive whose fourth member escapes upward throws under node-tar 7.5.22 -- and leaves the first three members on disk. The loader scans that directory at require time on the next boot, so a half-unpacked module is a module. Everything therefore happens in a scratch directory that is removed on any failure, and the move into place is the last step. `tar` is pinned to ^7.5.22 rather than the ^6 that installs by default: 6.x is flagged critical, and reading the advisory list is what the file's header now says out loud -- almost all of it is hardlink or symlink traversal and PAX header interpretation differentials, which is exactly this feature's threat model. Two things the plan had wrong ----------------------------- The bundle's top-level directory is `module-uo-<version>`, not the module id -- so "the top-level name must equal the id" was checked against nothing real. The extractor strips that level instead, because its name belongs to whoever published the bundle and the directory it lands in is core's. What is checked instead is the unpacked module.json: a manifest promising `uo` and delivering something else is refused rather than installed under the name it promised. And purge cannot be a follow-up action (decision 5): purge.sql lives inside the directory uninstall deletes. It is offered in the uninstall flow and as a standalone action on a still-installed module, and the standalone one refuses unless the module is already disabled -- dropping tables under something that is still serving leaves it answering out of a world that no longer exists. Disable now means stopped ------------------------- lifecycle.stop() dispatches that one module's onShutdown before flipping the guard, so a module an operator switches off actually releases its sockets and closes its streams instead of merely becoming unreachable. The hook runs first and the state moves after it, because while onShutdown runs the module is still `started` and that is the only state in which its routes and the world it is tearing down agree. A hook that throws does not stop the disable -- the opposite of the boot path's rule, and deliberately. Enable is not its mirror and there is no start(id) beside it. There is no onBoot re-dispatch and the hooks were never promised re-entrant, so enable moves the row and the restart route starts it. A test pins that enable does not touch the loader, because "fixing" it is a one-line change that would put a module with closed sockets back on the nav. Restart raises SIGTERM against its own process rather than calling the shutdown path directly, so server.js's handler stays the one graceful-shutdown path and this route cannot drift from it. The allowlist bootstraps from MODULE_SOURCE_HOSTS into a settings row and is admin-managed after that (decision 6); seedDefault is INSERT IGNORE, so changing the variable on an existing deployment is a no-op by design. An empty list forbids every install rather than allowing every host -- the safe direction for a value someone might blank by accident. Verified against the real v0.3.0 release ---------------------------------------- Not a fixture: fetched the published install manifest over the real Gitea host and its redirect chain, verified the sha256, inspected and unpacked the 252,517-byte artifact to 82 files, and then booted core against the result -- the module registered its five mounts, seven streams and eight capabilities and resolved its client chunk, with no scratch directory left behind. Two defects this slice's own tooling caught, both of which had already been written down as classes: - the controller destructured runPurge at require time, capturing the function rather than the module, which made the one dependency whose ORDER matters the one that could not be substituted; - two swagger annotations carried an apostrophe inside a quoted string, dropped silently by swagger-autogen before slice 5 taught it to fail loudly. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-12 03:09:45 -05:00
wtclaude	adff20be7b	feat(modules): merge module OpenAPI fragments into /api/docs.json (phase 3, slice 5) ... Core's half of the slice that closes phase 3. Two things: the request-time fragment merge core has owed since phase 1, and the last of core's UO copy. **The merge (MODULE_API.md §6.1a).** `swagger-output.json` is core's own routes and cannot be anything else — it is generated on a developer's machine and committed, so it must come out the same regardless of what they had checked out, and a module arrives on a volume long after the image was built. Module routes therefore reach the document at request time, from the `swagger-fragment.json` each module ships: `swagger/docsSpec.js` merges the fragments of STARTED modules over the committed spec, cached on a new loader state version and rebuilt when a module's state moves. Until now neither half existed. `swagger/mergeSpec.js` named the request-time caller in its header and that caller was never written, so the 72 routes module-uo serves were in no OpenAPI spec at all — core's standing rule ("never ship a route that isn't in the spec") broken by the extraction rather than by a route. Core wins every key collision, `swagger-output.json` is never mutated (it is a require()d JSON module — one in-place merge would be permanent AND cumulative), and a fragment that is missing or unreadable costs that module its paths and nothing else. The Swagger UI is now built per request for the same reason the JSON is: bound once at require time it would show core's routes for the life of the process while /api/docs.json showed the merged set. **The last of core's UO copy** (slice 4 deferred it; §5.2's check reads code, not prose, so none of this was caught): - 31 UO schemas and 4 UO tags in `swagger/swagger.js`, describing routes core has not served since slice 1 — 578 lines. They moved to module-uo, namespaced `Uo…`, and arrive back through the merge on an instance that installs it. - `info.description` said "a private Ultima Online shard". - README.md's 48 UO mentions, including the architecture diagram and the whole `## Shard integration (uo-link)` section, now `## Modules`. - `TOWNCRIER_DURATION_SEC` and `UOLINK_*` in the two `.env.example`s: read by the module, not by core, and documented in the module's README instead. **Two dropped annotations, and the reason nobody knew.** swagger-autogen reports an annotation it cannot parse and then prints Success in green, having skipped it. `npm run swagger` now captures its diagnostics and fails — which immediately found `POST /api/v1/admin/invites` and `POST /api/v1/auth/invite/:token/accept` documented with an EMPTY request body, both since the day they were written. Fixing the tag list also cleared five tags used by routes but never declared (`Admin · Email`, `Admin · Invites`, `Admin · Moderation`, `Admin · Pages`, `Auth · Me`) — the same defect class, in the other direction. - 646 server tests (+9), 157 client tests unchanged - routes.manifest.json unchanged (158 public + 2 internal); check:modules clean - swagger-output.json: 128 paths, 69 schemas, 0 orphan tags, 0 orphan schemas - verified against a real boot with module-uo installed: 197 merged paths (128 core + 69 module), all four module tags, 31 Uo schemas, no dangling $refs, /api/docs renders the module's operations with zero console errors Refs: docs/website/MODULE_API.md §2.8, §6.1a; MODULE_SYSTEM.md §2.7.1 Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 22:57:37 -05:00
wtclaude	f7d27f7a06	refactor(client): delete the UO client half (phase 3, slice 3) ... 35 files and 5,332 lines out — twelve public pages, seven admin views, two player views, eight components, the two `data/` leaves and the three `lib/` ones, plus the two tests that came with them. §2.7.1's estimate of 51 files / ~3,700 lines was measured differently and is corrected in the docs PR. The seams core keeps, each smaller than what it replaced: Nine rows leave the public header and six leave the admin sidebar, and both lists are now free of `feature` gates and of `IconShard`. `moduleTitle` already handled a module page's heading, so the six TITLES entries and the `/admin/characters` branch of `sectionTitle` simply go. `/player` had `PlayerCharacters` as its index — a UO page — and rather than name a replacement or invent a landing screen it now resolves to the first row of the portal nav this viewer can reach (`firstDestinationFor`, beside `allowedPathsFor` and reading the BASE nav for the same reason: an override is presentation and where everybody lands is behaviour). With the module installed that is still Characters, so a player's first screen after signing in does not change. Deliberately generic and deliberately not in the portal layout — the admin index is the same question with a hardcoded answer, and if the two logged-in areas ever become one this is what serves both. `game_account_signup` goes with the rest of core's UO prose: the mode list, the derived public flag, the validation and a Site Settings field whose help text named Bridge.cfg. The row itself is untouched and module-uo reads it through ctx.settings — the data stays, the semantics move. KNOWN BREAK, accepted by the org lead: the shipped Android app reads `gameAccountSignup` off `/public/settings` (PublicDto.kt:80). The field has a `= false` default so nothing crashes; the app silently stops offering game-account creation until it reads the module's `/public/shard/features` instead. Out of scope here, recorded in the Android plan, and it lands well before this workstream's cutover reaches `main`. 620 server + 161 client tests. Manifest 158 public + 2 internal, unchanged; routes.guards unchanged. The OpenAPI spec loses exactly one property, and only because it was hand-written in swagger.js — regeneration alone would have left the spec documenting a field core no longer returns. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 18:39:55 -05:00
wtclaude	39d731d87a	refactor(modules)!: move the UO server half out to module-uo ... 40 files, ~9,674 lines, 27 of 68 tables. Core no longer contains anything that knows what a shard is. BREAKING for a deployment only in the sense that the module must be installed for these URLs to answer -- no URL moved. routes.manifest.json goes 228 -> 158 public routes here, and the 70 that left reappear byte-identical when the module is loaded: verified by generating the manifest against core+module and diffing it against the pre-extraction file. Zero missing, zero added, and routes.guards identical across all 228, so no auth gate moved either. The five tier mounts are gone from public/admin/player index.js and are still served: the loader mounts them onto the same routers after every core mount. That ordering is also what keeps the prefixes unclaimable -- the collision check asks the live router what core owns, so a second module claiming /shard is rejected against the mounts actually present rather than against a list. server.js loses its eight UO call sites to the module's onBoot/onShutdown. schema.sql loses its 27 shard_*/uo_link_* statements; the two that FK into users are why the fragment replays AFTER core's schema, and no core table ever referenced a module table, which is what makes core still able to boot alone. Verified against a running server with the module installed: it loads, mounts five prefixes, replays 35 statements, warms up and reaches `started`; public shard and atlas routes answer 200 with real data (800 creatures, 6,455 spawners), admin and player answer 401 from core's tier gates, and the extension slot answers at /admin/users/:id/shard/*. Core's own SPA renders the shard and atlas pages unchanged against the module-served API, with no console errors and no CSP reports. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-11 12:08:03 -05:00
wtclaude	291c30f6ff	feat(modules): publish the installed-module list at /api/v1/public/modules ... Phase 2, PR 6 of docs/website/MODULE_SYSTEM.md 2.7 — the first module-system URL a client can see. The SPA and the Android app feature-detect against the capabilities a module declares; the shape is settled in MODULE_API.md 2.9. Four decisions, and what is absent from the payload is most of the design: * started modules only. A module that is disabled or failed to load is ABSENT, exactly as 4.4 already leaves its routes and its nav absent, so a client renders a site without that capability rather than advertising one that 503s. * no state, failure_stage or failure_reason. Where a module broke belongs to the admin Modules screen, and the reason is an exception string from inside core — not anonymous-visitor business. * no client chunk URL. htmlShell injects a script tag per started module (3.1.3), so the browser is handed the tag rather than a URL to fetch. This endpoint feature-detects; it does not load. MODULE_SYSTEM 2.6 step 4 is amended to match (API 6.7). * no siteMode gate and no database — the same class as /public/status and /public/version, so a client can still feature-detect during maintenance. It is a capability router of its own rather than a fifth singleton in site.router.js, and that is load-bearing: the loader's prefix-collision probe reads the live tier stack and skips root-mounted layers, because a use('/', ...) matches every path. A route inside the root-mounted site router would be invisible to it — mounting use('/modules', ...) is what makes "no module may claim /modules" a rule the loader enforces. 910 tests pass (+9, every one on the boundary — what must NOT appear). routes.manifest.json gains exactly the one route and routes.guards.json records it with an empty gates list, which is itself the assertion that it is ungated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-10 22:03:22 -05:00
wtclaude	6195c76d61	feat(modules): the three de-entanglement registries, with core as the registrant ... Phase 2 PR 4 of docs/website/MODULE_SYSTEM.md §2.7. Adds server/src/modules/registries.js and moves core's own notification streams, announce leg and users-detail routes behind it, so the three seams §1.8 and §1.9 named are exercised on every boot before any module depends on them. Registering is validate-then-commit per registrant: the loader stages what a module claims and the second pass commits it, so a module that throws halfway through register() — or fails checkDeclared after it — leaves nothing behind. That is the registry-side twin of PR 2's second-pass mount rule. Four decisions, all the recommended option: - announce legs became a child table. `announce_job_legs` replaces the towncrier_*/discord_* column groups, so the leg set is data: core registers `discord`, module-uo will register `towncrier`, and a module cannot ALTER a core table to add its own. Backfill is guarded on information_schema (a SELECT of a dropped column is a parse error, not a runtime one) and the columns go with DROP COLUMN IF EXISTS. Verified against the live dev DB: three legacy jobs migrated faithfully, three replays, no duplicates. - `mapEvent` dropped from registerNotificationStreams. §1.8 already inverts the push path so a module owns fromShardEvent and calls core's publish() with a stream id it resolved; a second mapping mechanism was a leftover. The public safety filter, the kinds it reads and the streams it protects now live in one file and move together. - core registers through the same staging area a module uses, via an explicit registries.registerCore() in app.js before modules.load(). - core's six /admin/users/:id/shard/* paths now go through the `admin.users.detail` slot, and getUser moved back to admin.controller.js. Found on the way, and the reason two build tools changed: - scripts/routeManifest.js could not decode a parameterised mount. Its unwinder expected `(?:([^\/]+?))`; express 4.22 emits `(?:\/([^/]+?))` with the separator inside the group. The branch had never run. It threw rather than guessing, which is what it is for. - swagger-autogen cannot follow a route into an extension slot — the slot's router is created by declareSlot() and filled later, so there is no literal mount for a static parse. Regenerating deleted 407 lines and printed `Swagger-autogen: Success`, the spike's exact failure (MODULE_API.md §7.4). swagger/slotSpecs.js generates a fragment per filled slot and re-roots it at the prefix the router actually hangs at in the live app — read from the express stack via routeManifest's own mountPath, so the manifest and the spec cannot disagree. swagger/mergeSpec.js is the merge helper core owes for module fragments anyway (§6.1a), proved here against core's own slot first. 884 tests pass (856 before). routes.manifest.json is unchanged at 229 routes. The OpenAPI spec diff is two lines of intent: the retry endpoint's summary, and its `leg` no longer being a fixed enum. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-10 17:47:59 -05:00
wtclaude	b517d7b2df	feat(theming): dropdown sections and added links in the public header ... Phase 10 of docs/website/THEMING_AND_NAV.md, asked for before the edge -> main cutover. An admin can now create dropdown sections in the public header, organise the coded entries into them, and add links of their own. This deliberately amends §7, which said the override layer "cannot introduce a `to` that is not already in the hardcoded NAV array". That stays true of every CODED entry; an admin may now also add a link, restricted to a same-origin path — no scheme, no protocol-relative //host. A link carries no gate of its own and needs none: the page behind it enforces its own access, so an added link advertises a route and never grants one. The invariant is kept structurally rather than by vigilance. Coded entries live in an `items` map whose keys must be routes the base array declares, so that map cannot invent a route; everything that CAN name an arbitrary path lives in `links`, which is the one place the path rule is applied — on both the write and the read path. nav_public therefore grew a { items, sections, links } wrapper. A bare map still reads as the items map, and a nav with no sections still stores one, so this changed nothing for a nav that does not use it. Free to do now because nothing has shipped; after the cutover it would have needed a migration. The Public tab gets its own editor. A public section is an entry in the top-level order that the admin created and can drag among the pills, unlike the admin sidebar's four coded sections, where only membership moves — that is a tree rather than a list of groups. Deleting a section returns its entries to the top level rather than removing them, which is the one destructive act this screen could otherwise commit. The dropdown opens on click and never on hover, and its trigger is not a link: a hover menu is unusable on touch, and a trigger that navigates means tapping to open takes you somewhere instead. Escape closes and returns focus, an outside press closes, navigating closes, and Arrow Up/Down walk the items. pruneNav applies the shard-feature gate inside a section and drops one it leaves empty, so a dropdown never opens onto nothing. Also fixes a bug this surfaced in the phase 6-8 code: the save path judged "does this route still exist?" against the palette — the base array already filtered to what the editing admin can see — so on the public header a feature-gated row's override could never be carried through and would have been silently reset. Membership is now judged against the full coded nav while the rows still come from the palette. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-08 00:42:19 -05:00
wtclaude	32a3ff104a	feat(theming): wire the three navs and add the admin nav builder ... Phases 6-8 of docs/website/THEMING_AND_NAV.md. The public header, the admin sidebar and the player portal now read their override row, and /admin/navigation writes them: rename, reorder by drag, hide, and — on the admin sidebar — move a row into another existing section. The merge always runs BEFORE the role and shard-feature filters in the layouts, which are unchanged and remain the boundary. An override is presentation: it cannot introduce a route, cannot touch a `roles` or `feature` gate, and a stored `hidden: false` on a gated item shows nobody anything. The design scoped these phases as client work, but the server had no way to store a nav row: updateSettings validates and stringifies theme_visual and brand_assets and lets everything else through, so a nav object would have been written as "[object Object]" and read as absent for ever. utils/navOverrides.js mirrors utils/brandAssets.js — strict on write with the offending key named, forgiving on read. It validates shape only; whether a `to` exists is settled client-side at merge time, because the base NAV arrays are client constants and a server-side copy would be a second source of truth that drifts. The nav editor cannot be hidden — its own toggle is disabled, the write path drops `hidden` on that one `to`, and AdminLayout strips it again before merging, which also covers a row edited straight in the database. Orders are written only when the sequence actually differs from the code's, and the comparison is restricted to the rows the editing admin can see, so renaming one item does not pin the position of every other one and a role- or feature-gated item missing from their palette is not mistaken for a reorder. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-08 00:02:33 -05:00
wtclaude	847cfd2d2b	feat(theming): brand-asset overrides and a cached, settings-aware HTML shell ... Phase 5 of docs/website/THEMING_AND_NAV.md: uploaded logo/hero/favicon overrides on top of the BRAND_* env defaults, delivered through an HTML shell that is no longer built once at boot. - utils/htmlShell.js owns the shell lifecycle: rendered lazily, cached per process, invalidated on a brand_assets/theme_visual write with a 5-minute TTL so other workers converge. A settings-read failure renders the env-only shell and caches that, so a DB outage is not a failing query per page view, and with no rows the output is byte-identical to what app.js served before. - POST /admin/settings/brand-asset/:slot uploads one asset and writes the row in the same call, so an upload never leaves an unreferenced file. It reuses the shared multer allowlist and only tightens it per slot: favicons are PNG-only and capped at 512 KB, logos at 1 MB, heroes at 8 MB. Refused files are unlinked before the response. - utils/brandAssets.js constrains a stored asset to a same-origin path under /uploads, /brand or /assets — these are the only settings values written straight into the page as a URL. Strict on write, forgiving on read. - The shell also carries the resolved theme as a <style id="theme-boot"> block, removing the first-paint flash phases 3-4 deferred; SiteContext drops that block once a successful settings fetch has been applied. - BrandLogo renders beside the MoonDot on all six shells and renders nothing when no logo is set, which is the shipped default. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-07 20:09:56 -05:00
wtclaude	3d6b2e23a7	feat(theming): server-resolved theme engine and admin appearance UI ... Phases 3-4 of docs/website/THEMING_AND_NAV.md. Three presets, the curated font shortlist, and /admin/appearance to drive them. The design put the presets in theme.css as [data-theme] blocks. That does not work: SiteContext writes --accent as an inline style on <html>, which beats any attribute-selector block, so a preset's accent would have been painted over by BRAND_ACCENT_COLOR while getPublic().brand.accent -- the value the Android app themes itself from -- reported the other one. Presets now live in server/src/config/themePresets.js. themeResolve.js layers :root <- preset <- custom per field into a token map, getPublic() returns it as `theme`, and the client writes it onto <html>. One authority for the merge, and brand.accent is by construction the accent the site paints. theme.css's :root is untouched, so an instance with no row gets no theme block and renders as today. Also: presets carry the full 15-token palette (eight would have left Fantasy with blue-grey borders); the option catalog is served from GET /settings/theme/options so the form cannot offer what the server rejects; validation is strict on write and forgiving on read; and the Discord bot now fetches the effective accent instead of its boot-time env copy. Fixes a Phase 0 bug in passing: settings/nav.controller.js imported the logger factory rather than calling it, so a DB fault would have thrown a TypeError inside the catch instead of returning 500. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-07 19:16:23 -05:00
wtclaude	ec0036ce6d	feat(theming): settings-store, nav merge util and radius tokens ... Phases 0-2 of docs/website/THEMING_AND_NAV.md. Groundwork only: no admin UI, no consumer wiring, and an instance that never touches the new settings keys renders exactly as it does today. Phase 0 - settings store: - settingsDb.remove() and DELETE /api/v1/admin/settings/:key, the "reset to default" primitive. Defaults for these keys live in BRAND_* env, theme.css and the hardcoded NAV arrays, so reset has to delete the row rather than store a copy of the default. Allowlisted to the five theming/nav keys plus hero_layout_draft, admin-only, idempotent. - GET /api/v1/settings/nav behind requireAuth with no role gate. AdminLayout renders for editors and moderators and PlayerPortalLayout for players, and none of them can read GET /admin/settings, so without this their nav override would silently never apply. - A fifth router group for it: /public is anonymous, /admin/settings is adminOnly, /player is self-scoped data. This is configuration that needs a login. - parseJsonSetting() in utils/settingsJson.js. settings.value is TEXT, so every JSON key arrives as a string; malformed or wrong-shaped reads as absent, never as an error and never half-applied. - theme_visual / brand_assets / nav_public join PUBLIC_KEYS; nav_admin and nav_player deliberately do not. Phase 1 - client/src/lib/navOverrides.js, the pure merge util. Presentation only: it can set label/order/hidden and (grouped navs) group, and nothing else. It cannot introduce a `to`, cannot touch roles/feature, and hidden:false cannot un-hide anything - the existing filters run afterward, unchanged, and remain the boundary. Phase 2 - promoted 23 border-radius literals in theme.css to four tokens at today's values (14x8px, 4x999px, 4x10px, 1x12px). The 7px/6px editor chrome and the two 50% circles stay literal. --shadow-card and --panel-grad were already tokens. Tests: 16 new server tests, 20 new client tests. The route-manifest guard now also asserts /settings/** sits behind requireAuth. Swagger and both route artifacts regenerated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-08-07 18:15:29 -05:00
wtclaude	8771a1cf6c	feat(shard): the player-vendor marketplace ... Protocol 3.0 §8, the website half. Ingests vendor.listing / vendor.listing.remove into shard_vendors + shard_vendor_items, serves a searchable public API over them, and ships /site/market and /site/market/vendors/:serial. Three things the pages have to say out loud, all consequences of how the data is gathered: - The prices are NOT live. The shard sweeps vendors round-robin, so a shop can be a full cycle behind. The banner is driven by the OLDEST vendor row, not the newest — the one stale shop is the one that wastes somebody's trip. - A shop can be truncated. `total` exceeding `count` means the shop holds more than the shard publishes per frame; the vendor page says "showing 250 of 3,104" rather than presenting a partial shop as complete. - An item may have no name. On a shard with no cliloc table the honest render is the item id, never an invented label. ## The pre-wired visibility rules, re-checked Part A pre-wired market.ownerName and market.location before the frame existed, and the sibling rule it pre-wired for leaderboards (`characterName`) turned out to be INERT because projectValue matches literal JSON keys. Both market rules were checked against the real frame this time: - `ownerName` is a real key. Kept. - `location` is a real key ONLY because the frame nests it. Flat map/x/y/region would have made the rule match nothing — the same failure, one part later. It is nested on the wire and on the read model so one rule hides the facet, the coordinates, the region and the house together; five flat keys would be five rules that drift apart. - `ownerSerial` was ADDED. An admin who hides the owner's name and leaves a serial that the leaderboards and guild boards resolve back to that same name has not hidden anything. Tests assert all three bite, on the stored read model AND on the raw frame — the market's SSE stream is off by default but an admin can turn it on, and a rule that worked on only one path is exactly the leak §3.6.1 records. ## Notable - **No payload column on shard_vendors**, unlike shard_points_boards next door. The board's top-N is a fixed-size list read whole; here the items ARE the searchable rows, so they are normalized and nothing is left worth duplicating. - **display_name is denormalized at ingest** (literal name preferred over the cliloc — a player set it, so it is more specific). Resolving at query time would put the cliloc table on the hot path and make search-by-name impossible. Because the shard's diff sweep will not re-send an unchanged shop just because the site learned what its items are called, a cliloc import now triggers a bulk re-resolution — 50 ms per thousand rows, never throws. - **updated_at is written explicitly** on every upsert. MariaDB does not fire ON UPDATE CURRENT_TIMESTAMP when every column is written back unchanged, and a shop re-published identically is still freshly confirmed — without this the staleness banner would age a perfectly current shop forever. - **LIKE wildcards in `q` are escaped.** `%` and `_` are LIKE metacharacters, not SQL ones, so parameterization does not neutralize them: `?q=%` would otherwise match every listing on the shard. - **Rate-limited** (60/min/IP), the only limited public read. Every other public GET is an indexed lookup of bounded size; this is a LIKE scan plus a COUNT over the largest shard_* table, anonymous by default. - Reconnect backfill pages /market, bounded by MARKET_SNAPSHOT_MAX = 5000 and stopping on a short page as well as on `total`, so a concurrent sweep shrinking the index cannot spin the walk. ## How it was tested 673 server tests pass (27 new). Client builds clean; swagger-output.json, routes.manifest.json and routes.guards.json regenerated. Verified full-stack against the live MariaDB and a real shard, not only units: - 27 real vendors / 1,040 listings swept off the ServUO tree, through the Rust sidecar, into the site — names resolving through the cliloc table ("longsword", "katana"), real facets and regions in the filters. - `?q=sword` 682, `?q=%` and `?q=_` **0** (the escape), map/region/price/sort filters, paging, and the vendor detail route. - Visibility live: fields gated to staff vanish for an anonymous caller while shopName and price survive; audience=player 403s; enabled=0 404s; and /shard/features correctly drops `market` so the nav hides it. - Re-publishing a shop smaller leaves no orphan items; an identical re-publish moves updated_at. - The limiter fires (38x200 then 32x429 on a 70-request burst). Not covered by an automated test: the two React pages are presentational and this repo's client suite covers pure-logic modules only. They were driven against the live API above, but not rendered in a DOM harness. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-29 09:51:50 -05:00
wtclaude	bda031566a	feat(shard): read clilocs from a source SET so shard items get names ... Shards edit items and add new ones, and those carry cliloc ids no stock client table has. Reading exactly one converted file meant an operator had to re-export 5 MB every time they added one item — friction enough that the table would simply go stale, which is the failure the spawn atlas was redesigned to avoid in the first place. So this mirrors spawnAtlasSource.readSources(): a BASE (the converted client table) plus every operator-maintained overlay under `custom/`, all re-read on every boot and hash-gated as a SET. Later sources win, so an overlay both adds ids the client never had and overrides stock ones the shard re-purposed. Adding, editing or removing any overlay counts as drift. `custom/` is the one convention here that is ours rather than the shard's, and deliberately so: ServUO has no server-side notion of a custom cliloc — they live in the patched client a shard distributes, and nothing in the tree declares them. There is nothing to discover. (An operator who does patch their client cliloc needs no overlay: convert the patched file and the edits are in the base.) Scale, measured on the live shard: its script tree references 16,434 cliloc ids and only 37 are absent from stock — tens against a 67k base, which is why this is an overlay and not a second table. The set brings back a hazard a single file did not have, and it gets the atlas's answer. A corrupt source fails the parse loudly, but a source that has VANISHED parses perfectly and imports a table quietly missing everything it contributed — an unmounted volume is indistinguishable from a deliberate deletion. So it is staged, not applied (`needsReview`), reported by both the import and status(), and accepted with `{approve:true}`. That is a flag rather than the atlas's approve/reject pair because the atlas stores a pending decision SO THAT approving re-parses; here nothing is stored, so re-reading at approval time is automatic. Also reports a per-source breakdown (entries/added/overrode) on import and in status, which is how an operator confirms an overlay took effect — "overrode: 0" on a file meant to re-label stock items says it did not. Two bugs this surfaced, both found by running a shard-style overlay rather than by another stock-table fixture: - displayText tidied punctuation unconditionally, so a custom "Runic Gateway Sigil (v2)" rendered as "(v2". Stripping leftover brackets is right after a placeholder is removed and wrong otherwise — the same condition the `%` rule already had. - CANDIDATE_NAMES did not include `clilocs.plain`, which is the exact filename CLILOCS.md and the export tool's README tell operators to write. Pointing at the directory they were told to create failed with NO_FILE. Verified end to end against the live MariaDB and a real server boot: base-only import, overlay adding one id and overriding another (per-source breakdown correct), unchanged set as a no-op, an edited overlay re-importing and withdrawing its override, a vanished overlay refused with the table intact, status reporting missingSources, approve applying it, and a file-path configuration still finding overlays beside it. All three resolve correctly through the running server: shard-added, overridden and stock. 646 server tests pass (16 new in clilocSource.test.js, 3 new in clilocParse.test.js); swagger, routes.manifest.json and routes.guards.json regenerated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-29 06:46:12 -05:00
wtclaude	b61a4d6721	feat(shard): resolve cliloc names for items and reward titles ... Protocol 3.0 §8.6 (docs/link/v3.md), the dependency order 5 was sequenced behind. Items on the wire carry a LabelNumber, not a name — the bridge has always sent it (char.profile.equipment.cliloc, reward titles as a cliloc number in string form, and one per marketplace listing) but the site had no table to resolve it against, so a character sheet could only render `id 1023721` where the game renders "quarter staff". The number was never the missing piece. The table was. Sourced from a file the operator converts once from their own client, at a path from the `cliloc_client_path` setting falling back to UO_CLIENT_PATH. Nothing client-derived is committed: UO's strings are EA's, exactly as the creature sprites are. A shard with nothing configured is fully supported — names render as ids, as they did before. The conversion step is not avoidable, and that is the substantive finding here: every current client ships its cliloc files COMPRESSED (first DWORD's high byte 0x8E, the Mythic container), and ServUO's own bundled Ultima.StringList cannot read that either — so VendorSearch.GetItemName is already inert on such a shard and the plugin could not supply names instead. v3.md's original "read the client's Cliloc.enu" recommendation was therefore not implementable as written, and its committed db/data/clilocs.json artifact also predates the Part C corrections (no committed derived snapshots, nothing EA-derived shipped). Replaced with the spawn-atlas pattern: parse on boot from an operator-configured path, hash-gated, output gitignored. - utils/clilocParse.js — pure parsers, fs-free so the suite runs in CI. Accepts the plain binary layout and delimited text, sniffed by header rather than extension. Rejects a compressed file BY NAME: without that check the plain parser reads it as ~19k records of negative ids and 60 KB "strings" before dying mid-file, and the resulting error names the wrong problem. displayText() drops the ~1_val~ arguments the bridge never sends. - utils/clilocSource.js — the fs layer. hashSource reports `compressed` so the admin panel can flag an unconverted file WITHOUT parsing 5 MB per poll; otherwise pointing at a client directory reports a healthy file with pending drift ("ready to import") and the operator only finds out on failure. - model/shardClilocs — refresh/status/lookup. All-or-nothing replace (DELETE, not TRUNCATE — TRUNCATE is DDL in MariaDB and implicitly commits). Batched server-side resolution behind a capped cache; never throws, because a cliloc lookup is decoration on a character sheet. - Deliberately NO staged-approval flow, unlike the atlas: the atlas escalates facet loss because a half-copied tree and a real map change are indistinguishable from inside the process, whereas a partial cliloc copy makes the parser fail on a truncated record. The ambiguity the atlas must escalate is one this parser simply detects. - No public route. The table is never served AS a table: 67k rows would dwarf any page using them, and the Android client consumes the same resolved JSON. Two parser bugs found by building it, both now covered by tests: trimming a text line before splitting ate the trailing separator on empty-text entries and silently dropped 55,994 of 123,490 while still reporting success; and Number('') is 0, not NaN, so a line starting with a separator imported as a bogus cliloc 0. Verified against the real client table (123,490 entries) and the live MariaDB: import 663 ms, hash-gated boot no-op 14 ms, cold resolve 4.2 ms / warm 0.015 ms. Binary and TSV imports converge on the same 67,496 rows with identical keys (blank entries — half the table — are dropped at import). A file truncated to half its length is refused with TRUNCATED and leaves the previous table serving. Boot logs verified for both the import and the compressed-file warning; neither blocks startup. All three admin routes exercised over HTTP with a real session. 629 server tests pass; client builds clean; swagger, routes.manifest.json and routes.guards.json regenerated. Not covered by an automated test: the character sheet renders resolved names in presentational React with no DOM test harness in this repo, and was not rendered against a live linked-player profile — that needs a logged-in player with a linked game account and a shard answering a profile RPC. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-29 04:21:38 -05:00
wtclaude	26094459ae	feat(shard): ingest points.board and publish the leaderboards ... Protocol 3.0 §7 (docs/link/v3.md). The shard publishes ~25 points/loyalty leaderboards — Queen's Loyalty, Void Pool, the nine city loyalties, Clean Up Britannia — and the site renders them, plus each character's own standings on their sheet. Server - shard_points_boards: one row per system, keyed by the shard's PointsType name. The top-N list stays inside `payload` — a fixed-size list read whole, exactly like shard_governors.candidates. Normalizing into an entries table buys nothing until something needs a per-character reverse lookup, and a character's own standings already ride inside char.profile. - shardIngest routes points.board to upsertPointsBoard and deliberately does NOT log it: this is board state like guild.update, and the shard emits a frame every time anyone's score moves a top ten. - uoLinkSocket backfills /points through snapshot() with ingestEach rather than a replace*: there is no points.remove and the system set is fixed, so upserting IS the reconciliation, and a system the operator later excludes keeps its last-known board rather than vanishing. - GET /public/shard/points and /points/:system behind requireFeature('leaderboards'), both projected per §3.6.1. :system is constrained to an identifier before any query runs; 404 for a system never published, distinct from a published board nobody has scored in (200, empty top). The leaderboards field rule now keys on `name`, not `characterName` Part A pre-wired FEATURES.leaderboards.fields = { characterName: ... }, but projectValue matches on the LITERAL JSON key and the wire key is `name`. As written the rule was inert: an admin tightening character names would have got no enforcement and no error — precisely the failure §3.6.1 records for the flattened `ownerAcct` spelling. Fixed, with a test that fails if it is renamed back, and the admin panel's FIELD_LABEL carries the meaning instead. Client - routes/public/Leaderboards.jsx at /site/leaderboards. A points.board frame describes ONE system, so live frames merge over the fetched set by system key rather than replacing it wholesale the way the ruleset does. Filter matches board name, system key, or any ranked player — the last is what makes it useful ("where do I appear?"). - A "Loyalty & Points" section in CharacterSheet.jsx, one edit serving both PlayerCharacter and AdminCharacter. - Both treat maxPoints: 0 as UNCAPPED and both fall back to humanising the system key when nameString is null. Neither is defensive padding: on a real shard uncapped and cliloc-only names are the majority case. Verified end to end against the local MariaDB, the Rust sidecar, and the real ServUO shard: backfill from /points, live SSE delivery (a board absent from the initial fetch appearing without a reload, and an existing one updating in place), REST reflecting the overwrite, and the gate at every rung — 200 by default with names, names stripped but points kept at fieldRules name=staff, 403 plus dropped from /features at audience=staff, 404 when disabled. Page rendered clean, no console errors beyond the pre-existing React Router v7 warnings. 605 server tests pass; routes.manifest.json, routes.guards.json and the OpenAPI spec regenerated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-28 21:04:44 -05:00
wtclaude	7c769ea8fd	feat(atlas): serve the spawn atlas and give operators a panel for it ... Protocol 3.0 order 3 (Part C), second of two website PRs. #112 built the data pipeline; this makes it reachable — six public routes, five admin ones, two public pages and an admin panel. Still website-only: no plugin, no sidecar, no new event kinds, no wire change. The API sits at /api/v1/public/atlas, not under /public/shard. Nothing here touches the sidecar, so the pages stay complete while the shard is down, and a /shard prefix would imply a dependency the atlas does not have. Unlike /shard/* it IS site-mode gated, like /posts and /wiki: a bestiary is site content. Every route carries requireFeature('atlas') and projects its response. The atlas feature declares no sensitive fields, so the projection is a no-op today — the call is there because v3.md 3.6.1's rule is that the FIRST field needing a gate should be covered by construction rather than by a retrofit. Two bugs the UI surfaced, both fixed here: Respawn delays were stored in the wrong unit, sometimes. XmlSpawner writes MinDelay/MaxDelay in minutes and switches to seconds only when a delay does not divide into whole minutes, flagging it per record with DelayInSec. A `5` means five minutes on one spawner and five seconds on the next, both plausible, and the pipeline stored the raw number. 170 of 6,455 stock spawners are second flagged. The parser normalises to seconds; the API and UI carry seconds. That exposed the hash gate as a trap. "Has the tree changed?" is the wrong question on its own: an install whose maps never change would have kept serving the old readings forever, because the only thing compared was the tree. PARSER_VERSION is now stored beside the source hashes and a mismatch counts as drift, so any future parse correction lands on the next boot. Also renamed the detail route's spawn-point array to `spawners` — it was `points`, which is the COUNT on the search route, so one key meant a number in one place and an array in the other. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01U7CBg11prhLimL9iHSX1bP	2026-07-28 19:51:22 -05:00
wtclaude	61d6bfaca2	feat(shard): ingest world.ruleset and publish it at /site/rules ... Protocol 3.0 §5 (docs/link/v3.md). The shard publishes its own ruleset — expansion, which optional systems are on, skill/stat caps, account and house limits, champion scroll rules, the save/restart schedule — and the site renders it, so the rules page cannot drift from how the shard actually plays. Server - shard_ruleset: a singleton table (id = 1) holding the whole frame in `payload`, with `rev` and `expansion` hoisted. Nothing is normalized out: the frame is a flat description of config read as one page, and splitting it into columns would mean a schema change every time the shard grows a block. - shardIngest routes world.ruleset to setRuleset and deliberately does NOT log it — the shard re-emits the whole ruleset on every sidecar connect, so logging would append a duplicate row per reconnect, and server.hello already marks each of those. - uoLinkSocket backfills GET /ruleset explicitly rather than via snapshot(), which asserts an array; this covers the order where the sidecar was already up and holding the ruleset when we reconnected. - GET /public/shard/ruleset behind requireFeature('ruleset') and projected, per §3.6.1's rule that a shard read which doesn't project is a bug. `null` means the shard has never published one — a real answer, distinct from a published ruleset, and the page says so. Client - routes/public/Rules.jsx at /site/rules, live via world.ruleset (a frame is a complete ruleset, not a delta, so the newest one wins outright). Caps are rendered from tenths — 7000 is 700.0, and showing the raw number would mislead. A systems key this build doesn't know still renders, humanised, so a newer plugin can't go invisible against an older client. - Nav entry gated on the `ruleset` feature, so it hides rather than 403s. Verified end to end against the local MariaDB and a sidecar fed by a fake shard: backfill snapshot, live SSE delivery of a changed ruleset, REST reflecting the overwrite, an empty /feed (not logged), and the gate — 200 by default, 403 at audience=staff (and dropped from /features so nav hides it), 404 when disabled. Page rendered clean at all breakpoints checked, no console errors. 497 server tests pass; routes.manifest.json, routes.guards.json and the OpenAPI spec regenerated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-28 14:35:24 -05:00
wtclaude	f30ea66fce	fix(shard): enforce visibility on the REST reads that bypassed it ... Protocol 3.0 Part A follow-up, found by the live five-rung smoke test. Part A implemented the visibility framework correctly on the SSE path and on /guilds + /governors, but the remaining public REST reads never called into it. The result was that one event was projected live and served verbatim from history: * GET /public/shard/feed returned the stored payload as-is, so actor.acct and actor.webId were readable ANONYMOUSLY for every logged kind - player.death, player.murdered, mob.killed, quest.complete, skill.gain, fame/karma.change, mob.login/logout, guild.join. Broader than the guild-leader leak Part A set out to close, since it covers every player rather than board holders. * GET /public/shard/idoc returned ownerAcct - the house owner's game account - to anonymous callers. * The `houses` field rules (owner/price -> staff) were dead config: neither getIdoc nor getHouses projected, so an admin could set them in the panel and nothing happened. * /feed filtered on PUBLIC_KINDS, a module-load constant derived from the compiled DEFAULTS, so live audience changes did not reach it. With `guilds` moved to staff, /guilds 403'd while /feed happily served guild.join to anonymous. Four fixes, all at the root rather than per-route: 1. Rule 1 now matches a field's MEANING, not one spelling. The wire nests actors (leader.acct) but the read models flatten them (shapeHouse -> ownerAcct, shapeGuild -> leaderWebId), and an exact-key check missed every flattened one. isLockedField() locks a key that is or ends in acct/webId, case-insensitively, so it fails closed for shapes not yet written. The admin PUT rejects those spellings too - `ownerAcct` is no longer configurable. 2. visibleKinds(level, config) resolves readable kinds from the LIVE config; getFeed uses it and projects each row against its own kind's feature. Deliberately independent of the `stream` flag, which governs SSE fan-out only - so market history stays readable with its firehose off. This makes the set a superset of PUBLIC_KINDS by exactly the two vendor kinds. 3. getIdoc/getHouses/getChamps/getPresence project, so every shard surface honours the same config. 4. shardEvents.db.list treats an EMPTY kinds array as "serve nothing". It previously fell through to the unfiltered query, so a fully-gated config would have dumped the whole event log, staff audit included. Also fixes a bug introduced while wiring this up: projectValue recursed into any object, so a Date column came back as {}. It now walks arrays and plain objects only. The unit tests used JSON fixtures and could not have caught it - the live /idoc read did. Verified live against MariaDB + a stub sidecar, all five rungs: 13 routes x 5 rungs, defaults reproducing pre-v3 access exactly, zero acct/webId below admin on any read, unmapped kinds (staff.command, cheat.detect, login.attempt) reaching only admin on SSE, and audience / enabled / stream changes taking effect live on an already-open stream. Tests: 487 server (+9). Swagger regenerated; route manifest unchanged. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-28 10:49:55 -05:00
wtclaude	f3450686e0	feat(shard): admin-configurable visibility for every shard surface ... Protocol 3.0 Part A. Replaces the static PUBLIC_KINDS allowlist - which was the entire public/admin boundary - with per-feature, per-field audience control an admin owns from Admin -> Shard Visibility. Closes a live leak. BridgeJson.Actor() writes acct and webId; shapeGuild() returned the stored payload verbatim; GET /api/v1/public/shard/guilds is anonymous. Guild leaders' game account names and website user ids were readable by anyone, and the same path existed for governors. Both are now projected. The ladder is anonymous < logged_in < player < staff < admin, each rung implying the ones below. Staff satisfy `player` without a linked account (as /player/* already does); `editor` is a content role and gets no shard privilege, since mapping it to staff would silently widen what editors see. Two invariants are code, not configuration, and both reject rather than silently ignore: 1. acct/webId are admin-only always - not configurable, discarded on read as well as rejected on write. 2. A kind absent from KIND_FEATURE never reaches anyone below admin. Fail closed, so a shard emitting a new event degrades to staff-only rather than to public. Enforcement is three points over one config: requireFeature() on routes (404 disabled, 403 out-of-rung) plus field projection; per-connection filtering on SSE, where a subscriber's rung is resolved once at subscribe time and frozen so a long-open stream cannot gain privilege; and /public/shard/features so the SPA hides links it cannot follow. PUBLIC_KINDS still exists and is still exported (/feed filtering, notificationStreams) but is now derived from the kind map, so the two can no longer drift. Defaults reproduce pre-3.0 behavior exactly - a test pins the derived set against the old allowlist. Also fixes an SSE resource leak found while testing: a client dropped because its write threw was removed from the bucket but its keepalive interval was never cleared, firing forever on a dead socket. Both paths now go through one drop(). Tests: 478 server (33 new across shardVisibility + shardBroadcast), 43 client. Route manifest and OpenAPI spec regenerated. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-28 10:04:48 -05:00
wtclaude	620781b7bc	feat(auth): honor and establish trusted devices on the SSO login paths ... "Trust this device" did nothing for anyone who signs in with Google or Discord. sso.controller went straight from needsTotp(user) to staging a pending-TOTP challenge and never consulted resolveTrustedDevice, so an SSO user was asked for a code on EVERY sign-in no matter how many times they had ticked the box — and POST /auth/sso/totp accepted only `code`, so that step could not establish a trust either. The password paths (web + native) were unaffected and already worked; this closes the gap for SSO, on the website AND in the Android app. Server: - finishLogin and finishMobileLogin now run the same trusted-device check as auth.controller.login, via one shared helper: honor a trust that belongs to THIS user, stamp last_used_at, log auth.login.trusted_device. A store error falls through to the challenge — fail closed to asking for the code. - POST /auth/sso/totp gains optional trustDevice + deviceName, sets the rg_trust cookie, and mirrors the password path's { trustLimitReached, devices } response at the cap (the sign-in still completes). Recovery codes stay password-only. Android coverage, without leaking a secret into a URL: - The app opens SSO in a Custom Tab, which shares the system browser's cookie jar, so the rg_trust cookie set on that TOTP form is presented back on the next app sign-in. That alone makes native SSO skip the code. Passing the app's token into the start URL was rejected — it would put a 256-bit secret in query strings, Referer headers and access logs. - To also cover the app's NATIVE password login, ticking the box sets mobile_auth_sessions.trust_device (a boolean; never the token), and /auth/mobile/sso/exchange mints a platform:'mobile' trust and returns { trustToken }. Minting there keeps the raw token on an authenticated app→server call, out of the deep link and out of the bridge row. Best-effort: at the cap the response just omits it rather than failing a good sign-in. Client: the trust checkbox is no longer hidden on the SSO second step, on both the admin and player login screens. On the mobile bridge the deep-link redirect takes priority over the cap prompt — the sign-in succeeded and the link is single-use, so stalling there would strand the app. Tests: 8 new cases in server/test/ssoTrustedDevice.test.js (verified to fail against the pre-fix controller). Full suites green — server 445, client 43 — and routes.manifest.json is a zero-line diff: no URL moved, only +2 handlers on /auth/sso/totp in routes.guards.json for the two new validators. Swagger regenerated. Verified live against the running server and real MariaDB: the TOTP step issues rg_trust and persists the row, a subsequent SSO callback carrying it skips the code, and an invalid trust is still challenged. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-28 01:01:12 -05:00
wtclaude	1a61cd1638	build(swagger): normalize and sort generated OpenAPI path keys ... Prepares the committed spec for the admin router domain split (docs/website/API_V2_PLAN.md § Phase 2) by post-processing swagger-autogen's output in swagger/swagger.js. No route, handler or annotation changes. Trailing slashes are stripped from path keys. swagger-autogen builds a path by string-concatenating the mount prefix with the route argument, so a capability router mounted at /users whose collection route is router.get('/') documents as /api/v1/admin/users/ — advertising a URL no client calls while dropping the one the SPA, the Android app and the Discord bot all do. Express is indifferent (non-strict routing treats the two as one route, and routes.manifest.json records the canonical slash-less form), but the published spec is a contract. The split creates one of these per capability router, so it is fixed once here rather than by contorting the route declarations in every router file. Path keys are also sorted. The generator emits them in router-traversal order, so moving a route between files rewrites most of this ~5k-line committed artifact even when the API is provably unchanged, burying the one line a reviewer needs to see. OpenAPI attaches no meaning to path order, and scripts/routeManifest.js already sorts for the same reason. Verified inert: the regenerated spec is byte-for-byte the sorted form of the previously committed one — same 198 operations, zero added or removed, and no trailing-slash keys (there were none to strip yet; the guard is for the split). A collision after normalization throws rather than silently dropping an operation. Server tests green (434/434). Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-27 15:49:31 -05:00
wtclaude	9b74999610	feat(security): soak the tightened CSP on report-only, with a same-origin sink ... Phase 1 of docs/website/API_V2_PLAN.md. The tightened policy ships on Content-Security-Policy-Report-Only alongside the unchanged enforced one for a release; a follow-up PR flips it after the soak comes back clean. The plan expected a two-directive delta. It is one. `form-action 'self'` was described as absent because it is not in the directives object in app.js — but the middleware runs with `useDefaults: true` and helmet's defaults already supply it, so the header served in production has carried it all along. Caught by capturing the live header from the running app instead of reading the config. It is now written out explicitly in config/csp.js regardless: a security directive should not depend on a third-party library's default surviving its next major version. The enforced header's contents do not change at all, and a test pins it verbatim. So the whole behavioural delta is `frame-ancestors 'self'` -> `'none'`. That is still the directive most worth soaking: a frame-ancestors report is generated by the browser of whoever framed the site, which is the only way to find out that something legitimately embeds us before an enforcing policy breaks it. The policies move to config/csp.js, with the report-only one derived by spread from the enforced one so the two cannot drift and the object reads as a diff. `report-to` needs somewhere to point, so this adds POST /api/csp-report -- same-origin on purpose, since reports describe attacks against this site and should not go to a third-party collector. It is mounted outside /api/v1 next to /api/health: the browser learns the path from the policy header, never from a client build, so it is not versioned client contract. It is necessarily unauthenticated -- browsers send reports with no session, and gating it would silence exactly the anonymous visitors worth hearing about -- so it is bounded on every axis: * both wire formats, since report-uri (Firefox/Safari) sends hyphenated keys in application/csp-report and report-to (Chrome) sends camelCase envelopes in application/reports+json; handling one silently drops half the browsers, * report-to also needs the Reporting-Endpoints response header or it is inert, * 16 KB body cap, per-IP rate limit, fixed field allowlist, every logged field truncated (script-sample is attacker-influenced and can carry a whole inline script), * always 204, even for malformed input: a 4xx would reach the global error handler, which logs the offending body -- turning an open endpoint into a log-flood primitive. Nothing is persisted; reports go to the `csp` log tag. routes.manifest.json moves 199 -> 200, which is the freeze from PR 0 working as designed: the one new URL is visible as a reviewed +1 rather than slipping through. Swagger regenerated to match. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-27 15:19:26 -05:00
wtclaude	14dfc122ba	fix(player): open the player self-service surface to staff ... Staff are a superset of players — every player ability plus their staff tools on top — but the /player/* group ran requireRole('player'), so a signed-in admin/editor/moderator got 403 on their own linked game accounts (e.g. GET /player/shard/accounts). On the Android client this hid "My characters" and greyed the personal notification streams for staff accounts, even when they had linked characters. Drop the role gate: the group is now requireAuth-only. Every handler is already self-scoped to the caller by req.user.id (with the pre-existing isAdmin bypass still letting a genuine admin read any character), so this only ever widens access to the caller's OWN data. Staff also reach the identical self-scoped handlers under /admin/shard/* (same controller). - player.routes.js: requireRole('player') -> requireAuth; corrected the five stale "Player role required" 403 descriptions and regenerated swagger-output.json. - New test/playerRouteAccess.test.js mounts the router and asserts player/admin/editor/moderator all reach the handler, anon still 401s, and a disabled account still 403s. Suite: 420 pass. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-22 02:17:29 -05:00
wtclaude	60ebacff2c	feat(auth): trusted devices, recovery codes, and admin MFA management ... Add opt-in "Trust this device" so a browser/app skips the TOTP step (never the password) for 30 days, single-use bcrypt recovery codes as a 2FA-lockout fallback, and admin trusted-device/MFA-reset management — backend, web UI, OpenAPI spec, and tests. - Schema: trusted_devices (sha256 token hash, looked up by unique index) and recovery_codes (bcrypt, single-use). Both additive/idempotent. - Session service: trust-token mint/hash/resolve + cap helpers; new rg_trust httpOnly cookie (survives logout, revoked on untrust/password change/reset/ TOTP disable). JWTs stay stateless — trust is a server-side row, not a claim. - Web + mobile login accept a trusted-device token / recovery code; login/totp gains trustDevice + recoveryCode. Cap of 10/user with NO silent pruning — an over-cap trust returns 409/trustLimitReached and the client prompts to revoke. - Self-service /auth/me/trusted-devices* + recovery-codes*; admin /admin/users/:id/trusted-devices* + /mfa/reset. All actions audit-logged. - Client: "Trust this device" + recovery-code login options, one-time recovery code display, Trusted Devices + Recovery Codes account panels, a TOTP-styled revoke-to-continue cap modal, and admin per-user security controls. - OpenAPI regenerated; 33 new server tests (all suites green). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>	2026-07-21 23:38:48 -05:00
wtclaude	e3dd5358b6	feat(auth): Active Devices — view/revoke mobile sessions ... Adds the self-service device-session surface the mobile-SSO spec requires, on top of the existing mobile_refresh_tokens store. - Schema: device_name + last_used_at columns on mobile_refresh_tokens (nullable, additive via the ALTER section; seeded to now on insert). With single-use rotation each login/refresh inserts a fresh row, so the active row's timestamp is the session's last activity, and the label is carried forward on refresh. - Model: listActiveForUser (one row per live device, no token hash) + revokeByIdForUser (ownership-scoped, idempotent). - GET /auth/me/sessions + DELETE /auth/me/sessions/:id (role-agnostic, behind requireAuth). Named distinctly from /auth/me/devices (push endpoints). - device_name is an optional field on /auth/mobile/login and /auth/mobile/sso/exchange so the app can label a device. - Client: an "Active Devices" panel on the player account page (list + sign a device out), plus the PlayerLogin change to honor the mobile SSO bridge's { redirect } deep link on a 2FA completion. - Swagger DeviceSession schema + regenerated spec; 3 controller tests. Full server suite green (274); client builds. Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-20 17:01:47 -05:00
wtclaude	61f4591a6b	feat(auth): native SSO authorization bridge for the Android app ... Add a Mobile SSO Authorization Bridge so the native app can "Sign in with Google/Discord" without shipping any OAuth secret. It EXTENDS the existing /auth/sso/* redirect flow (same PKCE-vs-IdP, link-only + opt-in provisioning, TOTP gate) and terminates in the existing mobile bearer tokens — not a parallel auth path. - Schema: mobile_auth_sessions + mobile_auth_codes (short-lived, self-pruning; authorization code stored hash-only, PKCE challenge is a hash by construction). - GET /auth/mobile/sso/start: validate provider enabled + redirect_uri by EXACT allowlist match (never prefix), seed a bridge session, reuse the SSO redirect tagged mode:'mobile' (new redirectToIdp helper extracted from beginFlow). - SSO callback + finishSsoTotp gain a mode:'mobile' branch: mint a single-use, hashed, PKCE-bound code and redirect to the fixed app callback (code + echoed state, never a token) instead of setting a cookie. 2FA keeps full parity via the existing web TOTP form (now carrying the bridge session). - POST /auth/mobile/sso/exchange: verify Layer-B PKCE (before burning the code), single-use consume, then issue the SAME pair as /auth/mobile/login. - Discovery reuses GET /auth/providers; refresh/logout reuse /auth/mobile/*. - Rate limits: /start per-IP+provider, /exchange per-IP. Boot-time + opportunistic prune of both tables (no cron, mirrors revoked_sessions). - Redirect allowlist is MOBILE_AUTH_REDIRECT_URIS (default the one fixed runicgateway://auth/callback); App Link URIs can be appended per shard later. - Swagger regenerated; 39 tests (model single-use/gating + full controller matrix: bad/expired/reused code, PKCE mismatch, disabled provider, redirect allowlist, TOTP-through-bridge). Full suite green (271). Refs docs/website/BACKEND_DESIGN.md, docs/android/PLAN.md §9 (M9). Co-Authored-By: Claude <noreply@anthropic.com>	2026-07-20 16:55:06 -05:00