Modes: host-side ruleset checks, trust boundary and Wikipedia-load notes (review on #6)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-11-16 23:04:58 -05:00
co-authored by Claude Opus 5.5
parent a2c2166bcc
commit 670508a4dc
3 changed files with 58 additions and 2 deletions
+27 -1
View File
@@ -145,6 +145,28 @@ for how they could become rewards without trusting the host's word.
| Request body | the node's 68 KB JSON limit |
| Wikipedia lookups (`trending`) | background only: one page per 3 s, at most 256 queued, never per request |
### Mode validation
A mode is rejected at node startup, never handed to the engine half-checked, if:
- it fails the mode schema (section 1), or
- the merged ruleset fails the engine's strict `parseRuleset`, or
- it fails the host-side checks in `server/game/engine-binding.ts`: `distinctStats` requires
`topicCount` 3; every `revealSchedule` turn ≤ `turns`; `energyByTurn` has an entry per turn;
`turns × turnSeconds ≤ 240`; `powerByCost` has 7 entries; or
- its deck policy can't produce legal decks (starter decks illegal under its rules, or a draft
pool smaller than 2 × `deckSize`).
### Wikipedia load (`verifyStats`)
Our Wikipedia egress is shared and rate-limited, so tonight the host makes **no Wikipedia
requests in any request or match path**:
- Hosted decks are loaners (starter or drafted), so there are no owned-card stats to verify,
and `verifyStats` never triggers a fetch.
- When owned decks arrive, verification must use the DESIGN §1.10 immutable cache keyed by
`(pageId, revisionId, snapshotMonth)`, with `check: 'unchecked'` and `uncheckedCostCap` as the
normal path when the cache is cold, not a per-card fetch.
- `trending` reads only the background-warmed trend cache (see "Not yet").
### Cheating
- **The client is never trusted.** Each action must deep-equal one of the engine's
@@ -166,7 +188,11 @@ for how they could become rewards without trusting the host's word.
### What a malicious host can and can't do
A host runs its own matches, so it is **trusted for the matches it hosts**, and only those.
**Hosted PvP trusts the host.** The host holds both players' hidden plans (hands and queued plays)
and relays them; it decides the seed; and it would be the one to mark card stats as checked or
unchecked (DESIGN §1.10). Nothing tonight lets players verify a match *while* it's being played.
So a host is **trusted for the matches it hosts**, and only those. Play on hosts you trust, and
treat leaderboards on any other host as that host's claims.
A malicious host **can**:
- lie about its stats, its matches hosted and its leaderboards;
+17 -1
View File
@@ -17,9 +17,25 @@ export function previewPool(rules: Ruleset, seed: string, size: number): GameCar
return pool;
}
/**
* The engine's strict parseRuleset, plus host-side checks that keep a hosted mode playable
* (requested in review on #6). Anything that fails is rejected at startup, never passed on.
*/
export function parseModeRuleset(value: unknown): Ruleset {
const rules = parseRuleset(value);
const problems: string[] = [];
if (rules.distinctStats && rules.topicCount !== 3) problems.push('distinctStats requires topicCount 3');
if (rules.revealSchedule.some(turn => turn > rules.turns)) problems.push('every revealSchedule turn must be ≤ turns');
if (rules.energyByTurn.length < rules.turns) problems.push('energyByTurn needs one entry per turn');
if (rules.turns * rules.turnSeconds > 240) problems.push('turns × turnSeconds must be ≤ 240');
if (rules.powerByCost.length !== 7) problems.push('powerByCost needs 7 entries');
if (problems.length) throw new Error(`Invalid mode rules: ${problems.join('; ')}`);
return rules;
}
export const engineBinding: EnginePort<Ruleset, GameCard, MatchState, Action> = {
defaultRuleset: DEFAULT_RULESET,
parseRuleset,
parseRuleset: parseModeRuleset,
deckSize: rules => rules.deckSize,
starterDeck: (_rules, seed) => starterDeck(seed),
previewPool,
+14
View File
@@ -189,3 +189,17 @@ test('modes api: turn timer applies the engine timeout action; AFK forfeits are
assert.ok(rec.actions.some(x => (x.action as any).type === 'timeout'));
assert.equal(replay(rec.rules as any, rec.decks as any, rec.seed, rec.actions.map(x => x.action) as any).result?.winner, 1);
});
test('modes api: mode rules are checked beyond the engine schema and rejected, not passed on', async () => {
const { parseModeRuleset } = await import('../server/game/engine-binding.ts');
const bad = [
{ turns: 2, energyByTurn: [1, 2] }, // revealSchedule [1,2,3] has a turn > 2
{ distinctStats: true, topicCount: 2, revealSchedule: [1, 2] },
{ turns: 12, turnSeconds: 25, energyByTurn: Array(12).fill(3), revealSchedule: [1, 2, 3] },
{ powerByCost: [0, 1, 2] },
{ mulligan: true },
{ keywordParams: { notAKeyword: { amount: 1 } } },
];
for (const rules of bad) assert.throws(() => resolveRuleset(DEFAULT_RULESET, rules as any, parseModeRuleset), JSON.stringify(rules));
assert.doesNotThrow(() => resolveRuleset(DEFAULT_RULESET, {}, parseModeRuleset));
});