@roster-lock/shared 0.1.0

package/src/match-lock-file/match-config/version-1/usage/validate-select/index.ts

@@ -0,0 +1,98 @@
+import {
+  RosterLockV1Config, PlayerId, PieceType, SelectedPiece, FinalSelection, UserInput
+} from "@roster-lock/types";
+
+
+import { handleGameControlledSelection } from "./selection-types/game-controlled";
+import { handlePreselectedSelection } from "./selection-types/preselected";
+import { handleNormalSelection } from "./selection-types/normal";
+import { ScriptStarter } from "@roster-lock/types";
+
+import { RunUntrustedError } from "./constants";
+import { handleValidationResult } from "./handle-validation";
+
+export async function runSelection(
+  config: RosterLockV1Config,
+  gameControlledSelections: Record<PieceType, Array<SelectedPiece> | Record<PlayerId, Array<SelectedPiece>>>,
+  userInputs: Record<PlayerId, UserInput>,
+  runScript: (input: ScriptStarter)=>Promise<any>
+){
+  const users: Array<string> = [];
+  const seeds: Array<string> = [];
+  const allSelections: Record<PlayerId, Record<PieceType, Array<SelectedPiece>>> = {};
+  // userInputs is built by each party independently (e.g. from concurrent
+  // per-player decryption), so its key-insertion order isn't guaranteed to
+  // match across parties. Sort by playerId so the merge script's RNG seed
+  // (derived from `seeds`) is deterministic regardless of insertion order -
+  // otherwise two parties can compute different "random" tie-breaks for the
+  // same selection and disagree on the final result.
+  const sortedPlayerIds = Object.keys(userInputs).sort();
+  for(const playerId of sortedPlayerIds){
+    const { randomSeed, userSelection } = userInputs[playerId];
+    users.push(playerId);
+    seeds.push(randomSeed);
+    allSelections[playerId] = userSelection;
+  }
+
+  const finalSelection: FinalSelection = {};
+  await Promise.all(Object.entries(config.engine.pieceDefinitions).map(async ([
+    pieceType, pieceConfig
+  ])=>{
+    // Skip on demand pieces
+    if(pieceConfig.selectionStrategy === "on demand") return;
+    if(pieceConfig.selectionStrategy === "mandatory"){
+      if(!config.rosters[pieceType]){
+        throw new Error(`Missing roster for mandatory piece ${pieceType}`);
+      }
+      return;
+    }
+
+    const selectionConfig = config.selection.piece[pieceType];
+    if(!selectionConfig){
+      throw new Error(`Missing selection config for ${pieceType}`);
+    }
+    if(selectionConfig.type === "game-controlled"){
+      finalSelection[pieceType] = await handleGameControlledSelection(
+        config, users, pieceType, gameControlledSelections
+      );
+      return;
+    }
+    if(selectionConfig.type === "preselected"){
+      finalSelection[pieceType] = await handlePreselectedSelection(
+        config, users, pieceType, selectionConfig
+      );
+      return;
+    }
+    if(selectionConfig.type === "normal"){
+      finalSelection[pieceType] = await handleNormalSelection(
+        config, seeds, users, pieceType, selectionConfig, allSelections, runScript
+      );
+      return;
+    }
+    throw new Error(`Unknown Selection Type ${(selectionConfig as any).type}`);
+  }));
+
+  if(!config.selection.globalValidation) return finalSelection;
+
+  const strippedSelection: Record<PieceType, Array<SelectedPiece> | Record<PlayerId, Array<SelectedPiece>>> = {};
+  for(const [k,v] of Object.entries(finalSelection)){
+    strippedSelection[k] = v.value;
+  }
+
+  await Promise.all(config.selection.globalValidation.map(async (script)=>{
+    return handleValidationResult(script, runScript({
+      config,
+      randomSeeds: seeds,
+      purpose: {
+        type: "global-validation",
+        users,
+        pieceTypes: Object.keys(config.engine.pieceDefinitions),
+        input: strippedSelection,
+      },
+      entryScript: script,
+    }));
+  }));
+
+  return finalSelection;
+}
+

package/src/match-lock-file/match-config/version-1/usage/validate-select/selection-types/game-controlled.ts

@@ -0,0 +1,49 @@
+import {
+  RosterLockV1Config, FinalSelection, PieceType, SelectedPiece, PlayerId
+} from "@roster-lock/types";
+import { ensurePiecesAreInRoster } from "../ensure-pieces-are-in-roster";
+
+
+export async function handleGameControlledSelection(
+  config: RosterLockV1Config,
+  users: Array<PlayerId>,
+  pieceType: PieceType,
+  gameControlledSelections: Record<PieceType, Array<SelectedPiece> | Record<PlayerId, Array<SelectedPiece>>>,
+): Promise<FinalSelection[PieceType]>{
+  const pieceDefinition = config.engine.pieceDefinitions[pieceType];
+  if(!pieceDefinition){
+    throw new Error(`Missing piece config for ${pieceType}`);
+  }
+  if(pieceDefinition.selectionStrategy === "mandatory"){
+    throw new Error(`Mandatory piece ${pieceType} cannot be game controlled`);
+  }
+  if(pieceDefinition.selectionStrategy === "on demand"){
+    throw new Error(`On demand piece ${pieceType} cannot be game controlled`);
+  }
+
+  const pieceSelections = gameControlledSelections[pieceType];
+  if(!pieceSelections){
+    throw new Error(`Missing selections for ${pieceType}`);
+  }
+
+  if(pieceDefinition.selectionStrategy === "shared"){
+    if(!Array.isArray(pieceSelections)){
+      throw new Error(`Expected Array for Shared Selection`);
+    }
+    ensurePiecesAreInRoster(config, pieceType, pieceSelections);
+    return { type: "shared", value: pieceSelections };
+  }
+
+
+  if(Array.isArray(pieceSelections) || pieceSelections === null){
+    throw new Error(`Expected Record for Personal Selection`);
+  }
+
+  for(const userId of users){
+    if(!pieceSelections[userId]){
+      throw new Error(`Missing selection for ${userId}`);
+    }
+    ensurePiecesAreInRoster(config, pieceType, pieceSelections[userId]);
+  }
+  return { type: "personal", value: pieceSelections };
+}

package/src/match-lock-file/match-config/version-1/usage/validate-select/selection-types/normal/cast-result.ts

@@ -0,0 +1,39 @@
+import { SelectedPiece, PlayerId } from "@roster-lock/types";
+import Ajv from "ajv";
+import { SelectedPieceSchema, SelectedPieceSchemaDef } from "../../../../shared/SelectedPiece";
+
+const ajv = new Ajv({ allErrors: true, strict: true, allowUnionTypes: true });
+
+ajv.addSchema({
+  $id: "SelectedPiece",
+  ...SelectedPieceSchemaDef,
+  ...SelectedPieceSchema,
+});
+
+const validateShared = ajv.compile<Array<SelectedPiece>>({
+  type: "array",
+  items: { $ref: "SelectedPiece" },
+});
+
+const validatePersonal = ajv.compile<Record<PlayerId, Array<SelectedPiece>>>({
+  type: "object",
+  required: [],
+  additionalProperties: {
+    type: "array",
+    items: { $ref: "SelectedPiece" },
+  },
+});
+
+export function castSharedResult(value: unknown): Array<SelectedPiece> {
+  if (!validateShared(value)) {
+    throw validateShared.errors;
+  }
+  return value;
+}
+
+export function castPersonalResult(value: unknown): Record<PlayerId, Array<SelectedPiece>> {
+  if (!validatePersonal(value)) {
+    throw validatePersonal.errors;
+  }
+  return value;
+}

package/src/match-lock-file/match-config/version-1/usage/validate-select/selection-types/normal/include-mandatory-require.ts

@@ -0,0 +1,44 @@
+import { RosterLockV1Config, PieceType, SelectedPiece } from "@roster-lock/types";
+
+export function includeMandatoryRequire(
+  config: RosterLockV1Config,
+  pieceType: PieceType,
+  selection: SelectedPiece
+){
+  const pieceDef = config.engine.pieceDefinitions[pieceType];
+  const piece = config.rosters[pieceType].find(p=>p.id === selection.id);
+  if(!piece){
+    throw new Error(`Piece ${selection.id} does not exist`);
+  }
+
+  for(const requirePieceType of pieceDef.requires){
+    const requiredPieceConfig = piece.requiredPieces[requirePieceType];
+    if(!requiredPieceConfig){
+      throw new Error(`Piece ${selection.id} is missing required piece type ${requirePieceType}`);
+    }
+    const requiredSelection = (()=>{
+      const found = selection.required[requirePieceType];
+      if(found) return found;
+      const newSelection: Array<SelectedPiece> = [];
+      selection.required[requirePieceType] = newSelection;
+      return newSelection;
+    })();
+    if(!requiredPieceConfig.selectable){
+      for(const selected of requiredSelection){
+        if(!requiredPieceConfig.expected.includes(selected.id)){
+          throw new Error(`Piece ${selection.id} requires ${selected.id} but it is not selectable`);
+        }
+      }
+    }
+    for(const requiredPieceId of requiredPieceConfig.expected){
+      const piece = requiredSelection.find(p=>p.id === requiredPieceId);
+      if(piece){
+        includeMandatoryRequire(config, requirePieceType, piece);
+        continue;
+      }
+      const newPiece = { id: requiredPieceId, required: {} };
+      includeMandatoryRequire(config, requirePieceType, newPiece);
+      requiredSelection.push(newPiece);
+    }
+  }
+}

package/src/match-lock-file/match-config/version-1/usage/validate-select/selection-types/normal/index.ts

@@ -0,0 +1,101 @@
+import {
+  RosterLockV1Config, SelectionNormalConfig, PieceType, SelectedPiece, PlayerId, FinalSelection
+} from "@roster-lock/types";
+import { ensurePiecesAreInRoster } from "../../ensure-pieces-are-in-roster";
+import { ScriptStarter } from "@roster-lock/types";
+
+import { validateUserSelection } from "./validate-user-selection";
+import { handleValidationResult } from "../../handle-validation";
+
+import { castSharedResult, castPersonalResult } from "./cast-result";
+
+export async function handleNormalSelection(
+  config: RosterLockV1Config,
+  randomSeeds: string[],
+  users: Array<PlayerId>,
+  pieceType: PieceType,
+  selectionConfig: SelectionNormalConfig,
+  allSelections: Record<PlayerId, Record<PieceType, Array<SelectedPiece>>>,
+  runScript: (input: ScriptStarter)=>Promise<any>
+): Promise<FinalSelection[PieceType]>{
+  const pieceConfig = config.engine.pieceDefinitions[pieceType];
+  if(!pieceConfig){
+    throw new Error(`Missing piece config for ${pieceType}`);
+  }
+  if(pieceConfig.selectionStrategy === "mandatory"){
+    throw new Error(`Mandatory piece ${pieceType} cannot be normal`);
+  }
+  if(pieceConfig.selectionStrategy === "on demand"){
+    throw new Error(`On demand piece ${pieceType} cannot be normal`);
+  }
+  await Promise.all(users.map(async (userId)=>{
+    const userSelections = allSelections[userId][pieceType];
+    if(!userSelections){
+      throw new Error(`Missing selections for ${pieceType}`);
+    }
+    await validateUserSelection(
+      config, pieceType, userSelections, selectionConfig, 
+    );
+    if(!selectionConfig.validation?.customValidation.length){
+      return;
+    }
+
+    await Promise.all(selectionConfig.validation.customValidation.map(async (script)=>(
+      handleValidationResult(script, runScript({
+        config,
+        randomSeeds,
+        purpose: {
+          type: "piece-user-validation",
+          pieceType,
+          userId,
+          input: userSelections,
+        },
+        entryScript: script
+      }))
+    )));
+  }));
+
+  if(pieceConfig.selectionStrategy === "shared" && !selectionConfig.mergeAlgorithm){
+    throw new Error(`Shared piece ${pieceType} is missing merge algorithm`);
+  }
+
+  const usersSelections: Record<PlayerId, Array<SelectedPiece>> = {};
+  for(const userId of users){
+    usersSelections[userId] = allSelections[userId][pieceType];
+  }
+  // If there is no merge algorithm, we just use the users selections which have been validated
+  if(!selectionConfig.mergeAlgorithm){
+    return { type: "personal", value: usersSelections };
+  }
+
+  const rawResult = await runScript({
+    config,
+    randomSeeds,
+    purpose: {
+      type: "piece-merge",
+      pieceType,
+      users,
+      input: usersSelections,
+    },
+    entryScript: selectionConfig.mergeAlgorithm
+  });
+
+  if(pieceConfig.selectionStrategy === "shared"){
+    const mergedSelection = castSharedResult(rawResult);
+    ensurePiecesAreInRoster(config, pieceType, mergedSelection);
+    return { type: "shared", value: mergedSelection };
+  }
+
+  if(pieceConfig.selectionStrategy === "personal"){
+    const mergedSelection = castPersonalResult(rawResult);
+    for(const userId of users){
+      if(!mergedSelection[userId]){
+        throw new Error(`Missing selection for ${userId}`);
+      }
+      ensurePiecesAreInRoster(config, pieceType, mergedSelection[userId]);
+    }
+    return { type: "personal", value: mergedSelection };
+  }
+
+  throw new Error("Invalid Selection Strategy: " + pieceConfig.selectionStrategy);
+}

package/src/match-lock-file/match-config/version-1/usage/validate-select/selection-types/normal/validate-user-selection.ts

@@ -0,0 +1,51 @@
+import { RosterLockV1Config, SelectionNormalConfig, PieceType, PieceId, SelectedPiece } from "@roster-lock/types";
+import { ensurePiecesAreInRoster } from "../../ensure-pieces-are-in-roster";
+
+
+export async function validateUserSelection(
+  config: RosterLockV1Config,
+  pieceType: PieceType,
+  userSelections: Array<SelectedPiece>,
+  selectionConfig: SelectionNormalConfig,
+){
+
+  ensurePiecesAreInRoster(config, pieceType, userSelections);
+
+  if(!selectionConfig.validation) return;
+
+  validateCount(selectionConfig.validation.count, userSelections);
+  const banList = selectionConfig.validation.banList || [];
+  const viewed = new Set<PieceId>();
+  for(const piece of userSelections){
+    if(banList.includes(piece.id)){
+      throw new Error(`Banned piece ${piece.id} selected for ${pieceType}`);
+    }
+    if(selectionConfig.validation.unique){
+      if(viewed.has(piece.id)){
+        throw new Error(`Duplicate piece ${piece.id} selected for ${pieceType}`);
+      }
+      viewed.add(piece.id);
+    }
+  }
+}
+
+function validateCount(
+  countConfig: NonNullable<SelectionNormalConfig["validation"]>["count"],
+  userSelections: Array<SelectedPiece>
+){
+  if(!Array.isArray(countConfig)){
+    if(countConfig === "*") return;
+    if(userSelections.length !== countConfig){
+      throw new Error(`Expected ${countConfig} pieces, got ${userSelections.length}`);
+    }
+    return;
+  }
+  const [min, max] = countConfig;
+  if(userSelections.length < min){
+    throw new Error(`Expected at least ${min} pieces, got ${userSelections.length}`);
+  }
+  if(max === "*") return;
+  if(userSelections.length > max){
+    throw new Error(`Expected at most ${max} pieces, got ${userSelections.length}`);
+  }
+}

package/src/match-lock-file/match-config/version-1/usage/validate-select/selection-types/preselected.ts

@@ -0,0 +1,36 @@
+import {
+  RosterLockV1Config, SelectionPreselectedConfig,
+  FinalSelection, PieceType, SelectedPiece, PlayerId
+} from "@roster-lock/types";
+import { ensurePiecesAreInRoster } from "../ensure-pieces-are-in-roster";
+
+
+export async function handlePreselectedSelection(
+  config: RosterLockV1Config,
+  users: Array<PlayerId>,
+  pieceType: PieceType,
+  selectionConfig: SelectionPreselectedConfig,
+): Promise<FinalSelection[PieceType]>{
+  const pieceDefinition = config.engine.pieceDefinitions[pieceType];
+  if(!pieceDefinition){
+    throw new Error(`Missing piece config for ${pieceType}`);
+  }
+  if(pieceDefinition.selectionStrategy === "mandatory"){
+    throw new Error(`Mandatory piece ${pieceType} cannot be game controlled`);
+  }
+  if(pieceDefinition.selectionStrategy === "on demand"){
+    throw new Error(`On demand piece ${pieceType} cannot be game controlled`);
+  }
+
+  ensurePiecesAreInRoster(config, pieceType, selectionConfig.pieces);
+
+  if(pieceDefinition.selectionStrategy === "shared"){
+    return { type: "shared", value: selectionConfig.pieces };
+  }
+
+  const userSelections: Record<PlayerId, Array<SelectedPiece>> = {};
+  for(const userId of users){
+    userSelections[userId] = selectionConfig.pieces;
+  }
+  return { type: "personal", value: userSelections };
+}

package/src/match-lock-file/util-types/json-schema/JSONSchemaCaster.ts

@@ -0,0 +1,52 @@
+
+
+import { Ajv, ErrorObject, JSONSchemaType } from "ajv";
+import { AJVKeywordDefinition } from "./defineKeyword";
+
+function returnTrue(){ return true; }
+function createAJVInstance<T>(
+  engineSchema: JSONSchemaType<T>,
+  engineKeywords: Array<AJVKeywordDefinition>,
+  validate: boolean = true
+){
+  const ajv = new Ajv({ allErrors: true, strict: true, allowUnionTypes: true });
+  for(const keyword of engineKeywords){
+    ajv.addKeyword({
+      keyword: keyword.keyword,
+      errors: true,
+      schema: true,
+      type: keyword.type,
+      validate: !validate ? returnTrue : keyword.validate,
+    });
+  }
+  return ajv.compile(engineSchema);
+}
+
+type SafeValue<T> = (
+  | { valid: true, value: T }
+  | { valid: false, error: Array<ErrorObject> }
+);
+
+export class JSONSchemaCaster<T> {
+  constructor(
+    private schema: JSONSchemaType<T>,
+    private keywords: Array<AJVKeywordDefinition>,
+  ){}
+
+  safeCast(input: unknown, validate: boolean = true): SafeValue<T> {
+    try {
+      return { valid: true, value: this.cast(input, validate) };
+    }catch(e){
+      return { valid: false, error: e as Array<ErrorObject> };
+    }
+  }
+
+  cast(input: unknown, validate: boolean = true) {
+    const schemaValidator = createAJVInstance(this.schema, this.keywords, validate);
+    if(!schemaValidator(input)){
+      if(!schemaValidator.errors) throw new Error("Validation failed with no information");
+      throw schemaValidator.errors;
+    }
+    return input as T;
+  }
+}

package/src/match-lock-file/util-types/json-schema/checkVersion.ts

@@ -0,0 +1,9 @@
+
+export function checkConfigVersion(value: unknown){
+  if(typeof value !== "object") return null;
+  if(value === null) return null;
+  if(Array.isArray(value)) return null;
+  if(!("rosterlockVersion" in value)) return null;
+  if(typeof value.rosterlockVersion !== "number") return null;
+  return value.rosterlockVersion;
+}

package/src/match-lock-file/util-types/json-schema/defineKeyword.ts

@@ -0,0 +1,50 @@
+import { SchemaValidateFunction } from "ajv";
+import { SafeKeyword } from "./safe-keyword";
+import { JSONSchemaType } from "./schema-types";
+
+export type AJVKeywordDefinition<K extends string = string> = {
+  keyword: SafeKeyword<K>,
+  type: JSONSchemaType,
+  validate: SchemaValidateFunction
+};
+
+export function defineKeyword<T, K extends string>(
+  definition: {
+    keyword: SafeKeyword<K>,
+    type: JSONSchemaType,
+    validate: (v: any, engine: T, path: string)=>unknown
+  }
+): AJVKeywordDefinition<K>{
+  return {
+    ...definition, validate: wrapValidator<T>(definition.keyword, definition.validate)
+  };
+}
+
+function wrapValidator<T>(
+  keyword: string,
+  validator: (v: any, engine: T, path: string)=>unknown
+): SchemaValidateFunction {
+  const wrapped: SchemaValidateFunction = function(
+    _schema,
+    value: any,
+    _parentSchema,
+    dataCxt,
+  ){
+    if(!dataCxt) return true;
+    try {
+      validator(value, dataCxt.rootData as T, dataCxt.instancePath);
+      return true;
+    }catch(e: any){
+      wrapped.errors = [{
+        instancePath: dataCxt.instancePath,
+        schemaPath: "",
+        keyword: keyword,
+        message: e.message,
+        params: {}
+      }];
+      return false;
+    }
+  };
+  return wrapped;
+}
+

package/src/match-lock-file/util-types/json-schema/index.ts

@@ -0,0 +1,4 @@
+export * from "./safe-keyword";
+export * from "./schema-types";
+export * from "./defineKeyword";
+export * from "./JSONSchemaCaster";

package/src/match-lock-file/util-types/json-schema/safe-keyword.ts

@@ -0,0 +1,27 @@
+// List of JSON Schema reserved keywords
+type JSONSchemaReservedKeywords = 
+  | "type" | "properties" | "required" | "additionalProperties"
+  | "items" | "prefixItems" | "contains" | "minItems" | "maxItems"
+  | "uniqueItems" | "minContains" | "maxContains"
+  | "minimum" | "maximum" | "exclusiveMinimum" | "exclusiveMaximum"
+  | "multipleOf"
+  | "minLength" | "maxLength" | "pattern" | "format"
+  | "minProperties" | "maxProperties" | "patternProperties"
+  | "dependentRequired" | "dependentSchemas"
+  | "enum" | "const"
+  | "allOf" | "anyOf" | "oneOf" | "not"
+  | "if" | "then" | "else"
+  | "$ref" | "$defs" | "$id" | "$schema" | "$comment"
+  | "$anchor" | "$dynamicRef" | "$dynamicAnchor" | "$vocabulary"
+  | "title" | "description" | "default" | "deprecated"
+  | "readOnly" | "writeOnly" | "examples"
+  | "contentMediaType" | "contentEncoding" | "contentSchema";
+
+// Combine all checks
+export type SafeKeyword<T extends string> = (
+  T extends "" ? "❌ Keyword cannot be an empty string" :
+  T extends `${string} ${string}` ? "❌ Keyword cannot contain whitespace" :
+  T extends JSONSchemaReservedKeywords ? `❌ Cannot use reserved JSON Schema keyword "${T}". Use a custom prefix like "_${T}" instead.` :
+  T
+);
+

package/src/match-lock-file/util-types/json-schema/schema-types.ts

@@ -0,0 +1,5 @@
+
+export type JSONSchemaType = (
+  | "null" | "boolean" | "integer" |  "number" | "string" | "object" | "array"
+  | ("string" | "number" | "boolean" | "object" | "integer" | "null" | "array")[]
+)