auramaxx 0.1.1 → 0.1.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "auramaxx",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "AuraJS CLI for creating, playing, and publishing JavaScript-first games.",
   "keywords": [
     "aurajs",
@@ -26,8 +26,11 @@
     "src/lib/startBannerQuotes.ts",
     "src/server/cli/commands/onboard.ts",
     "src/server/cli/commands/create.ts",
+    "src/server/cli/commands/fork.ts",
+    "src/server/cli/commands/make.ts",
     "src/server/cli/commands/play.ts",
     "src/server/cli/commands/publish.ts",
+    "src/server/cli/lib/published-game-integrity.ts",
     "src/server/cli/lib/prompt.ts",
     "src/server/cli/lib/theme.ts"
   ],

package/src/server/cli/commands/fork.ts

@@ -0,0 +1,81 @@
+import { execFileSync } from 'child_process';
+import { rmSync } from 'fs';
+import { pathToFileURL } from 'url';
+
+import { printBanner, printSection, paint, ANSI } from '../lib/theme';
+import {
+  buildPublishedGameLaunchEnv,
+  installVerifiedGamePackage,
+  parseArgs,
+  resolveGameBin,
+  resolvePackageName,
+} from './play';
+
+export interface ForkCommandPlan {
+  help: boolean;
+  name: string | null;
+  gameArgs: string[];
+  gameBin: string | null;
+  packageName: string | null;
+  forwardedArgs: string[];
+}
+
+export function buildForkPlan(argv: string[]): ForkCommandPlan {
+  const parsed = parseArgs(argv);
+  return {
+    ...parsed,
+    gameBin: parsed.name ? resolveGameBin(parsed.name) : null,
+    packageName: parsed.name ? resolvePackageName(parsed.name) : null,
+    forwardedArgs: ['fork', ...parsed.gameArgs],
+  };
+}
+
+export async function main(argv: string[] = process.argv.slice(2)) {
+  const plan = buildForkPlan(argv);
+
+  if (plan.help || !plan.name) {
+    printBanner('FORK');
+    console.log(`  ${paint('Usage:', ANSI.bold)} auramaxx fork <game> [destination|wrapper fork options]`);
+    console.log('');
+    console.log(`  ${paint('Examples:', ANSI.dim)}`);
+    console.log('    auramaxx fork aurasu');
+    console.log('    auramaxx fork aurasu ./aurasu-local');
+    console.log('    auramaxx fork @auraindustry/chess-dev-cli@1.2.3 --dest ./chess-local');
+    console.log('');
+    console.log(`  ${paint('Runs:', ANSI.dim)} verified signed temporary install -> local game wrapper fork`);
+    console.log('');
+    if (!plan.name && !plan.help) {
+      console.error('  Missing game name.');
+      process.exit(1);
+    }
+    return;
+  }
+
+  printBanner(plan.name.toUpperCase());
+  printSection(plan.name, 'Forking editable package into local project...');
+
+  let install: Awaited<ReturnType<typeof installVerifiedGamePackage>> | null = null;
+  try {
+    install = await installVerifiedGamePackage(plan);
+    const env = buildPublishedGameLaunchEnv(process.env);
+    execFileSync(process.execPath, [install.binAbsolutePath, ...plan.forwardedArgs], {
+      stdio: 'inherit',
+      cwd: install.packageRoot,
+      env,
+    });
+  } finally {
+    if (install?.installRoot) {
+      rmSync(install.installRoot, { recursive: true, force: true });
+    }
+  }
+}
+
+if (import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    const status = (err as { status?: number; exitCode?: number })?.status
+      ?? (err as { status?: number; exitCode?: number })?.exitCode
+      ?? 1;
+    process.exit(Number.isInteger(status) ? status : 1);
+  });
+}

package/src/server/cli/commands/make.ts

@@ -0,0 +1,90 @@
+import { execFileSync } from 'child_process';
+import { existsSync } from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { printBanner, paint, ANSI } from '../lib/theme';
+
+const COMMAND_DIR = path.dirname(fileURLToPath(import.meta.url));
+const LOCAL_AURAJS_CLI = path.resolve(
+  COMMAND_DIR,
+  '../../../../../packages/aurascript/src/cli/src/cli.mjs',
+);
+
+function parseArgs(argv: string[]) {
+  for (const arg of argv) {
+    if (arg === '--help' || arg === '-h') {
+      return { help: true, passthrough: [] as string[] };
+    }
+  }
+  return {
+    help: false,
+    passthrough: [...argv],
+  };
+}
+
+function resolveInvocationCwd(): string {
+  const forwardedCwd = process.env.AURA_INVOKE_CWD;
+  if (forwardedCwd && path.isAbsolute(forwardedCwd)) {
+    return forwardedCwd;
+  }
+
+  const shellPwd = process.env.PWD;
+  if (shellPwd && path.isAbsolute(shellPwd)) {
+    return shellPwd;
+  }
+  return process.cwd();
+}
+
+async function main() {
+  const parsed = parseArgs(process.argv.slice(2));
+
+  if (parsed.help) {
+    printBanner('MAKE');
+    console.log(`  ${paint('Usage:', ANSI.bold)} auramaxx make [kind] [name] [--role <custom|enemy|pickup|player|world>]`);
+    console.log('');
+    console.log('  Public wrapper around AuraJS project file generation.');
+    console.log('  Run it from inside an AuraJS game project.');
+    console.log(`  ${paint('Examples:', ANSI.dim)}`);
+    console.log('    auramaxx make');
+    console.log('    auramaxx make scene Scene1');
+    console.log('    auramaxx make ui-screen PauseMenu');
+    console.log('    auramaxx make prefab EnemyShip --role enemy');
+    console.log('    auramaxx make list');
+    console.log('');
+    console.log('  When no arguments are passed in a TTY, AuraJS opens an interactive make flow.');
+    console.log('');
+    return;
+  }
+
+  const invocationCwd = resolveInvocationCwd();
+  const auraArgs = ['make', ...parsed.passthrough];
+
+  try {
+    if (existsSync(LOCAL_AURAJS_CLI)) {
+      execFileSync(process.execPath, [LOCAL_AURAJS_CLI, ...auraArgs], {
+        cwd: invocationCwd,
+        stdio: 'inherit',
+        env: process.env,
+      });
+    } else {
+      execFileSync(
+        'npm',
+        ['exec', '--yes', '--package', '@auraindustry/aurajs', '--', 'aura', ...auraArgs],
+        {
+          cwd: invocationCwd,
+          stdio: 'inherit',
+          env: process.env,
+        },
+      );
+    }
+  } catch (error: unknown) {
+    const status = (error as { status?: number }).status;
+    if (status) process.exit(status);
+    throw error;
+  }
+}
+
+main().catch((err) => {
+  console.error(err instanceof Error ? err.message : String(err));
+  process.exit(1);
+});

package/src/server/cli/commands/play.ts

@@ -3,7 +3,9 @@ import { existsSync, mkdtempSync, readFileSync, rmSync } from 'fs';
 import { homedir, tmpdir } from 'os';
 import { join, resolve } from 'path';
 import { pathToFileURL } from 'url';
-import { printBanner, printSection, paint, ANSI, createProgressDisplay } from '../lib/theme';
+import { printBanner, printSection, paint, ANSI, createProgressDisplay, printComplete } from '../lib/theme';
+import { promptSelect } from '../lib/prompt';
+import { PublishedGameIntegrityError } from '../lib/published-game-integrity';
 import {
   assertPublishedGameBinIntegrity,
   buildPublishedGameLaunchEnv,
@@ -108,6 +110,31 @@ function resolveNpmCommand(): string {
   return process.platform === 'win32' ? 'npm.cmd' : 'npm';
 }
 
+function resolveAuramaxxCommand(): string {
+  return process.platform === 'win32' ? 'auramaxx.cmd' : 'auramaxx';
+}
+
+function resolveInstalledGlobalAuramaxxVersion(): string | null {
+  try {
+    const root = execFileSync(resolveNpmCommand(), ['root', '-g'], {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      encoding: 'utf8',
+      timeout: 30000,
+    }).trim();
+    if (!root) {
+      return null;
+    }
+    const packageJsonPath = join(root, 'auramaxx', 'package.json');
+    if (!existsSync(packageJsonPath)) {
+      return null;
+    }
+    const pkg = JSON.parse(readFileSync(packageJsonPath, 'utf8')) as { version?: unknown };
+    return typeof pkg.version === 'string' && pkg.version.trim().length > 0 ? pkg.version.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
 function normalizeRelativePath(pathLike: string): string {
   return String(pathLike || '')
     .trim()
@@ -180,6 +207,63 @@ function formatInstallError(error: unknown, packageSpec: string): Error {
   return new Error(`Refusing to run ${packageSpec}: ${message}`);
 }
 
+function isUnsupportedAurajsWrapperError(error: unknown): error is PublishedGameIntegrityError {
+  return error instanceof PublishedGameIntegrityError
+    && error.reasonCode === 'published_game_aurajs_version_unsupported';
+}
+
+async function promptUpgradeAuramaxx(expectedAurajsVersion: string): Promise<boolean> {
+  console.log('');
+  console.log(`  ${paint('AuraMaxx update required', ANSI.bold)}`);
+  console.log(`  ${paint(`This game uses @auraindustry/aurajs ${expectedAurajsVersion}.`, ANSI.dim)}`);
+  console.log(`  ${paint('Your installed AuraMaxx does not recognize that play wrapper yet.', ANSI.dim)}`);
+  console.log('');
+
+  const choice = await promptSelect(
+    '  Update AuraMaxx now?',
+    [
+      { value: 'update', label: 'Yes, update and retry', aliases: ['y', 'yes', '1'] },
+      { value: 'cancel', label: 'No, cancel', aliases: ['n', 'no', '2'] },
+    ],
+    'update',
+  );
+
+  return choice === 'update';
+}
+
+function installLatestAuramaxx(): void {
+  console.log('');
+  console.log(`  ${paint('Reinstalling latest AuraMaxx...', ANSI.bold)}`);
+  console.log('');
+  try {
+    execFileSync(resolveNpmCommand(), ['uninstall', '-g', 'auramaxx'], {
+      stdio: 'inherit',
+      timeout: 120000,
+    });
+  } catch {
+    // Ignore missing-package uninstall failures and continue with a clean install.
+  }
+  execFileSync(resolveNpmCommand(), ['install', '-g', 'auramaxx@latest', '--foreground-scripts'], {
+    stdio: 'inherit',
+    timeout: 180000,
+  });
+
+  const installedVersion = resolveInstalledGlobalAuramaxxVersion();
+  if (installedVersion) {
+    console.log('');
+    console.log(`  ${paint(`Installed AuraMaxx ${installedVersion}`, ANSI.dim)}`);
+  }
+}
+
+function relaunchWithUpdatedAuramaxx(argv: string[]): never {
+  printComplete('AuraMaxx updated. Relaunching play...');
+  execFileSync(resolveAuramaxxCommand(), ['play', ...argv], {
+    stdio: 'inherit',
+    env: process.env,
+  });
+  process.exit(0);
+}
+
 export async function installVerifiedGamePackage(
   plan: PlayCommandPlan,
   {
@@ -250,6 +334,9 @@ export async function installVerifiedGamePackage(
     };
   } catch (error: unknown) {
     rmSync(installRoot, { recursive: true, force: true });
+    if (error instanceof PublishedGameIntegrityError) {
+      throw error;
+    }
     throw formatInstallError(error, plan.name);
   }
 }
@@ -327,7 +414,36 @@ export async function main(argv: string[] = process.argv.slice(2)) {
   }
 }
 if (import.meta.url === pathToFileURL(process.argv[1]).href) {
-  main().catch((err) => {
+  const cliArgv = process.argv.slice(2);
+  main(cliArgv).catch((err) => {
+    if (isUnsupportedAurajsWrapperError(err)) {
+      const expectedAurajsVersion = String(err.details.expectedAurajsVersion || '').trim() || '<unknown>';
+      (async () => {
+        const shouldUpdate = await promptUpgradeAuramaxx(expectedAurajsVersion);
+        if (!shouldUpdate) {
+          console.error(err.message);
+          process.exit(1);
+        }
+
+        try {
+          installLatestAuramaxx();
+          relaunchWithUpdatedAuramaxx(cliArgv);
+        } catch (updateError) {
+          console.error('');
+          console.error(
+            updateError instanceof Error
+              ? updateError.message
+              : String(updateError),
+          );
+          console.error('  Manual fallback: npm uninstall -g auramaxx && npm install -g auramaxx@latest');
+          process.exit(1);
+        }
+      })().catch((promptError) => {
+        console.error(promptError instanceof Error ? promptError.message : String(promptError));
+        process.exit(1);
+      });
+      return;
+    }
     console.error(err instanceof Error ? err.message : String(err));
     const status = (err as { status?: number; exitCode?: number })?.status
       ?? (err as { status?: number; exitCode?: number })?.exitCode

package/src/server/cli/lib/published-game-integrity.ts

@@ -0,0 +1,572 @@
+import { createHash, createPublicKey, verify } from 'crypto';
+import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'fs';
+import { dirname, join, relative, resolve } from 'path';
+
+const PACKAGE_INTEGRITY_SCHEMA = 'aurajs.package-integrity.v1';
+const PACKAGE_INTEGRITY_MANIFEST_PATH = 'aura.package-integrity.json';
+const PACKAGE_INTEGRITY_SIGNATURE_PATH = 'aura.package-integrity.sig';
+const PACKAGE_SIGNER_TRUST_STORE_PATH = 'published-game-signers.json';
+const EXACT_SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const PLAY_WRAPPER_REQUIRED_MARKERS = [
+  '#!/usr/bin/env node',
+  'const fallbackAuraPackage =',
+  "const MINIMAL_COMMANDS = ['dev', 'join', 'play', 'fork', 'publish', 'session'];",
+  "const ALL_COMMANDS = ['dev', 'join', 'play', 'fork', 'publish', 'session', 'state', 'inspect', 'action'];",
+  "args: ['exec', '--yes', '--package', fallbackAuraPackage, '--', 'aura', ...commandArgs]",
+] as const;
+
+export class PublishedGameIntegrityError extends Error {
+  reasonCode: string;
+  details: Record<string, unknown>;
+
+  constructor(reasonCode: string, message: string, details: Record<string, unknown> = {}) {
+    super(message);
+    this.name = 'PublishedGameIntegrityError';
+    this.reasonCode = reasonCode;
+    this.details = details;
+  }
+}
+
+function normalizeRelativePath(pathLike: string): string {
+  return String(pathLike || '')
+    .trim()
+    .replace(/^[.][\\/]/, '')
+    .replaceAll('\\', '/');
+}
+
+function normalizeText(value: string): string {
+  return String(value || '').replace(/\r\n?/g, '\n');
+}
+
+function normalizeString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0
+    ? value.trim()
+    : null;
+}
+
+function sha256Buffer(buffer: Buffer): string {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function sha256Text(value: string): string {
+  return sha256Buffer(Buffer.from(normalizeText(value), 'utf8'));
+}
+
+function readJsonFile(path: string): Record<string, unknown> {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8')) as Record<string, unknown>;
+  } catch (error) {
+    throw new PublishedGameIntegrityError(
+      'published_game_json_invalid',
+      `Failed to parse JSON at ${path}: ${error instanceof Error ? error.message : String(error)}`,
+      { path },
+    );
+  }
+}
+
+function listRelativeFiles(root: string, current = root, acc: string[] = []): string[] {
+  for (const entry of readdirSync(current, { withFileTypes: true })) {
+    const fullPath = join(current, entry.name);
+    if (entry.isDirectory()) {
+      listRelativeFiles(root, fullPath, acc);
+      continue;
+    }
+    if (entry.isFile()) {
+      acc.push(normalizeRelativePath(relative(root, fullPath)));
+    }
+  }
+  return acc;
+}
+
+function listHashedPackageFiles(root: string, current = root, acc: Array<{ path: string; size: number; sha256: string }> = []) {
+  for (const entry of readdirSync(current, { withFileTypes: true })) {
+    const fullPath = join(current, entry.name);
+    const relativePath = normalizeRelativePath(relative(root, fullPath));
+
+    if (relativePath === PACKAGE_INTEGRITY_MANIFEST_PATH || relativePath === PACKAGE_INTEGRITY_SIGNATURE_PATH) {
+      continue;
+    }
+    if (entry.isSymbolicLink()) {
+      throw new PublishedGameIntegrityError(
+        'published_game_symlink_not_allowed',
+        `Published game package may not contain symlinks: ${relativePath}`,
+        { path: relativePath },
+      );
+    }
+    if (entry.isDirectory()) {
+      listHashedPackageFiles(root, fullPath, acc);
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const bytes = readFileSync(fullPath);
+    acc.push({
+      path: relativePath,
+      size: bytes.length,
+      sha256: sha256Buffer(bytes),
+    });
+  }
+
+  acc.sort((left, right) => left.path.localeCompare(right.path));
+  return acc;
+}
+
+function sortKeysDeep(value: unknown): unknown {
+  if (Array.isArray(value)) {
+    return value.map((entry) => sortKeysDeep(entry));
+  }
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  const sorted: Record<string, unknown> = {};
+  for (const key of Object.keys(value as Record<string, unknown>).sort()) {
+    sorted[key] = sortKeysDeep((value as Record<string, unknown>)[key]);
+  }
+  return sorted;
+}
+
+function stableSerialize(value: unknown): string {
+  return JSON.stringify(sortKeysDeep(value));
+}
+
+function normalizeBinMap(projectPackage: Record<string, unknown>): Record<string, string> {
+  if (typeof projectPackage?.bin === 'string' && projectPackage.bin.trim().length > 0) {
+    return {
+      [String(projectPackage?.name || 'game').split('/').pop() || 'game']: normalizeRelativePath(projectPackage.bin),
+    };
+  }
+
+  const normalized: Record<string, string> = {};
+  for (const key of Object.keys((projectPackage?.bin || {}) as Record<string, unknown>).sort()) {
+    const value = (projectPackage.bin as Record<string, unknown>)[key];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+      continue;
+    }
+    normalized[key] = normalizeRelativePath(value);
+  }
+  return normalized;
+}
+
+function resolveProjectBinEntries(projectPackage: Record<string, unknown>, packageName: string | null) {
+  const normalizedPackageName = normalizeString(packageName) || normalizeString(projectPackage?.name) || 'game';
+  if (typeof projectPackage?.bin === 'string' && projectPackage.bin.trim().length > 0) {
+    return [{
+      name: normalizedPackageName.split('/').pop() || normalizedPackageName,
+      relativePath: normalizeRelativePath(projectPackage.bin),
+    }];
+  }
+
+  return Object.entries((projectPackage?.bin || {}) as Record<string, unknown>)
+    .filter(([, value]) => typeof value === 'string' && value.trim().length > 0)
+    .map(([name, value]) => ({
+      name,
+      relativePath: normalizeRelativePath(String(value)),
+    }));
+}
+
+function assertPlayWrapperContract(relativePath: string, wrapperText: string): { markers: string[] } {
+  const normalized = normalizeText(wrapperText);
+  const missingMarkers = PLAY_WRAPPER_REQUIRED_MARKERS.filter((marker) => !normalized.includes(marker));
+  if (missingMarkers.length > 0) {
+    throw new PublishedGameIntegrityError(
+      'published_game_bin_wrapper_contract_invalid',
+      `Bin target "${relativePath}" does not satisfy the AuraJS play wrapper contract.`,
+      {
+        relativePath,
+        missingMarkers,
+      },
+    );
+  }
+
+  return {
+    markers: [...PLAY_WRAPPER_REQUIRED_MARKERS],
+  };
+}
+
+function normalizeAuthoredMetadata(packageRoot: string) {
+  const configPath = resolve(packageRoot, 'aura.config.json');
+  if (!existsSync(configPath)) {
+    return {
+      identity: null,
+      window: null,
+    };
+  }
+
+  const config = readJsonFile(configPath);
+  const iconPath = normalizeString((config.identity as Record<string, unknown> | undefined)?.icon);
+  const normalizedIconPath = iconPath ? normalizeRelativePath(iconPath) : null;
+  const iconAbsolutePath = normalizedIconPath ? resolve(packageRoot, normalizedIconPath) : null;
+  const iconBytes = iconAbsolutePath && existsSync(iconAbsolutePath) && lstatSync(iconAbsolutePath).isFile()
+    ? readFileSync(iconAbsolutePath)
+    : null;
+
+  return {
+    identity: {
+      name: normalizeString((config.identity as Record<string, unknown> | undefined)?.name),
+      version: normalizeString((config.identity as Record<string, unknown> | undefined)?.version),
+      executable: normalizeString((config.identity as Record<string, unknown> | undefined)?.executable),
+      icon: normalizedIconPath,
+      iconAsset: {
+        path: normalizedIconPath,
+        exists: Boolean(iconBytes),
+        size: iconBytes ? iconBytes.length : null,
+        sha256: iconBytes ? sha256Buffer(iconBytes) : null,
+      },
+    },
+    window: {
+      title: normalizeString((config.window as Record<string, unknown> | undefined)?.title),
+    },
+  };
+}
+
+function updateSignerTrustStore(trustRoot: string | null, packageName: string, packageVersion: string | null, signerFingerprint: string) {
+  if (!trustRoot) {
+    return {
+      status: 'unchecked',
+      storePath: null,
+    };
+  }
+
+  const storePath = resolve(trustRoot, PACKAGE_SIGNER_TRUST_STORE_PATH);
+  const existingEntries = existsSync(storePath) ? readJsonFile(storePath) : {};
+  const existing = (existingEntries[packageName] as Record<string, unknown> | undefined) || null;
+  const existingFingerprint = normalizeString(existing?.signerFingerprint);
+  if (existingFingerprint && existingFingerprint !== signerFingerprint) {
+    throw new PublishedGameIntegrityError(
+      'published_game_signer_changed',
+      `Published game signer changed for ${packageName}: expected ${existingFingerprint}, got ${signerFingerprint}.`,
+      {
+        packageName,
+        packageVersion,
+        expectedFingerprint: existingFingerprint,
+        actualFingerprint: signerFingerprint,
+        storePath,
+      },
+    );
+  }
+
+  const now = new Date().toISOString();
+  const nextEntries = {
+    ...existingEntries,
+    [packageName]: {
+      signerFingerprint,
+      firstSeenAt: existing?.firstSeenAt || now,
+      lastSeenAt: now,
+      lastVersion: packageVersion,
+    },
+  };
+
+  mkdirSync(dirname(storePath), { recursive: true });
+  writeFileSync(storePath, `${JSON.stringify(nextEntries, null, 2)}\n`, 'utf8');
+
+  return {
+    status: existing ? 'trusted' : 'trusted_first_use',
+    storePath,
+  };
+}
+
+export function buildPublishedGameLaunchEnv(
+  source: NodeJS.ProcessEnv,
+  explicit: Record<string, string> = {},
+): NodeJS.ProcessEnv {
+  return {
+    ...(source || {}),
+    ...explicit,
+  };
+}
+
+export function assertPublishedGameBinIntegrity(input: {
+  packageRoot: string;
+  projectPackage?: Record<string, unknown> | null;
+  packageName?: string | null;
+  expectedAurajsVersion?: string | null;
+}) {
+  const packageRoot = resolve(input.packageRoot);
+  const packageJsonPath = resolve(packageRoot, 'package.json');
+  if (!existsSync(packageJsonPath)) {
+    throw new PublishedGameIntegrityError(
+      'published_game_package_json_missing',
+      `Could not read installed package metadata at ${packageJsonPath}.`,
+      { packageJsonPath },
+    );
+  }
+
+  const projectPackage = input.projectPackage || readJsonFile(packageJsonPath);
+  const packageName = normalizeString(input.packageName) || normalizeString(projectPackage?.name);
+  const dependencySpec = normalizeString((projectPackage.dependencies as Record<string, unknown> | undefined)?.['@auraindustry/aurajs']);
+  if (!dependencySpec) {
+    throw new PublishedGameIntegrityError(
+      'published_game_aurajs_dependency_missing',
+      'Published AuraJS games must depend on @auraindustry/aurajs.',
+      { packageJsonPath },
+    );
+  }
+  if (!EXACT_SEMVER_PATTERN.test(dependencySpec)) {
+    throw new PublishedGameIntegrityError(
+      'published_game_aurajs_dependency_unpinned',
+      'Published AuraJS games must pin @auraindustry/aurajs to an exact version.',
+      { dependencySpec, packageJsonPath },
+    );
+  }
+  if (normalizeString(input.expectedAurajsVersion) && dependencySpec !== input.expectedAurajsVersion) {
+    throw new PublishedGameIntegrityError(
+      'published_game_aurajs_dependency_version_mismatch',
+      `Expected @auraindustry/aurajs version ${input.expectedAurajsVersion}, found ${dependencySpec}.`,
+      {
+        dependencySpec,
+        expectedAurajsVersion: input.expectedAurajsVersion,
+        packageJsonPath,
+      },
+    );
+  }
+
+  const binEntries = resolveProjectBinEntries(projectPackage, packageName);
+  if (binEntries.length === 0) {
+    throw new PublishedGameIntegrityError(
+      'published_game_bin_missing',
+      'Published AuraJS games must declare a generated wrapper entrypoint in package.json -> bin.',
+      { packageJsonPath },
+    );
+  }
+
+  for (const entry of binEntries) {
+    if (!entry.relativePath.startsWith('bin/')) {
+      throw new PublishedGameIntegrityError(
+        'published_game_bin_path_outside_bin_dir',
+        `Bin target "${entry.relativePath}" must live under bin/.`,
+        { entry },
+      );
+    }
+  }
+
+  const binDir = resolve(packageRoot, 'bin');
+  if (!existsSync(binDir)) {
+    throw new PublishedGameIntegrityError(
+      'published_game_bin_dir_missing',
+      'Published AuraJS games must include a bin/ directory.',
+      { binDir },
+    );
+  }
+
+  const actualBinFiles = listRelativeFiles(binDir).map((entry) => normalizeRelativePath(join('bin', entry)));
+  const declaredBinPaths = [...new Set(binEntries.map((entry) => entry.relativePath))];
+  const declaredBinSet = new Set(declaredBinPaths);
+  const unexpectedFiles = actualBinFiles.filter((entry) => !declaredBinSet.has(entry));
+  if (unexpectedFiles.length > 0) {
+    throw new PublishedGameIntegrityError(
+      'published_game_bin_unexpected_file',
+      `Published AuraJS games may not ship extra bin/ files: ${unexpectedFiles.join(', ')}`,
+      {
+        declaredBinPaths,
+        unexpectedFiles,
+      },
+    );
+  }
+
+  const verifiedFiles = [];
+  for (const relativePath of declaredBinPaths) {
+    const absolutePath = resolve(packageRoot, relativePath);
+    if (!existsSync(absolutePath)) {
+      throw new PublishedGameIntegrityError(
+        'published_game_bin_target_missing',
+        `Published game bin target "${relativePath}" is missing from the installed package.`,
+        { relativePath, absolutePath },
+      );
+    }
+
+    const wrapperText = readFileSync(absolutePath, 'utf8');
+    const contract = assertPlayWrapperContract(relativePath, wrapperText);
+
+    verifiedFiles.push({
+      relativePath,
+      absolutePath,
+      hash: sha256Text(wrapperText),
+      contractMarkers: contract.markers,
+    });
+  }
+
+  return {
+    reasonCode: 'published_game_bin_integrity_ok',
+    packageName,
+    aurajsDependency: {
+      spec: dependencySpec,
+      wrapperContract: 'aurajs.play-wrapper.v1',
+    },
+    bin: {
+      entries: binEntries,
+      declaredFiles: declaredBinPaths,
+      actualFiles: actualBinFiles,
+      verifiedFiles,
+    },
+  };
+}
+
+export function verifyPublishedGamePackageIntegrity(input: {
+  packageRoot: string;
+  expectedPackageName?: string | null;
+  trustRoot?: string | null;
+}) {
+  const packageRoot = resolve(input.packageRoot);
+  const manifestPath = resolve(packageRoot, PACKAGE_INTEGRITY_MANIFEST_PATH);
+  const signaturePath = resolve(packageRoot, PACKAGE_INTEGRITY_SIGNATURE_PATH);
+  if (!existsSync(manifestPath) || !existsSync(signaturePath)) {
+    throw new PublishedGameIntegrityError(
+      'published_game_integrity_artifacts_missing',
+      `Published game package must include ${PACKAGE_INTEGRITY_MANIFEST_PATH} and ${PACKAGE_INTEGRITY_SIGNATURE_PATH}.`,
+      { manifestPath, signaturePath },
+    );
+  }
+
+  const manifest = readJsonFile(manifestPath);
+  const signature = String(readFileSync(signaturePath, 'utf8') || '').trim();
+  if (normalizeString(manifest?.schema) !== PACKAGE_INTEGRITY_SCHEMA) {
+    throw new PublishedGameIntegrityError(
+      'published_game_integrity_schema_invalid',
+      `Expected ${PACKAGE_INTEGRITY_SCHEMA}, found ${manifest?.schema || '<missing>'}.`,
+      { schema: manifest?.schema || null },
+    );
+  }
+  if (!signature) {
+    throw new PublishedGameIntegrityError(
+      'published_game_integrity_signature_missing',
+      `${PACKAGE_INTEGRITY_SIGNATURE_PATH} is empty.`,
+      { signaturePath },
+    );
+  }
+
+  const publicKeyPem = normalizeString((manifest.signer as Record<string, unknown> | undefined)?.publicKeyPem);
+  const signerFingerprint = normalizeString((manifest.signer as Record<string, unknown> | undefined)?.fingerprint);
+  if (!publicKeyPem || !signerFingerprint) {
+    throw new PublishedGameIntegrityError(
+      'published_game_signer_missing',
+      'Package integrity manifest is missing signer metadata.',
+      {},
+    );
+  }
+
+  const actualFingerprint = sha256Buffer(
+    createPublicKey(publicKeyPem).export({ format: 'der', type: 'spki' }) as Buffer,
+  );
+  if (actualFingerprint !== signerFingerprint) {
+    throw new PublishedGameIntegrityError(
+      'published_game_signer_fingerprint_mismatch',
+      'Package integrity signer fingerprint does not match the embedded public key.',
+      {
+        expectedFingerprint: signerFingerprint,
+        actualFingerprint,
+      },
+    );
+  }
+
+  const signatureOk = verify(
+    null,
+    Buffer.from(stableSerialize(manifest)),
+    publicKeyPem,
+    Buffer.from(signature, 'base64'),
+  );
+  if (!signatureOk) {
+    throw new PublishedGameIntegrityError(
+      'published_game_integrity_signature_invalid',
+      'Package integrity signature verification failed.',
+      { signerFingerprint },
+    );
+  }
+
+  if (normalizeString(input.expectedPackageName) && normalizeString((manifest.package as Record<string, unknown> | undefined)?.name) !== input.expectedPackageName) {
+    throw new PublishedGameIntegrityError(
+      'published_game_package_name_mismatch',
+      `Expected published package ${input.expectedPackageName}, found ${(manifest.package as Record<string, unknown> | undefined)?.name || '<missing>'}.`,
+      {
+        expectedPackageName: input.expectedPackageName,
+        actualPackageName: (manifest.package as Record<string, unknown> | undefined)?.name || null,
+      },
+    );
+  }
+
+  const actualFiles = listHashedPackageFiles(packageRoot);
+  const expectedFiles = Array.isArray(manifest.files) ? manifest.files as Array<Record<string, unknown>> : [];
+  const expectedByPath = new Map(expectedFiles.map((entry) => [normalizeRelativePath(String(entry.path || '')), entry]));
+  const actualByPath = new Map(actualFiles.map((entry) => [entry.path, entry]));
+  const missing = [];
+  const mismatched = [];
+  for (const [path, expected] of expectedByPath) {
+    const actual = actualByPath.get(path);
+    if (!actual) {
+      missing.push(path);
+      continue;
+    }
+    if (actual.sha256 !== expected.sha256 || actual.size !== expected.size) {
+      mismatched.push({
+        path,
+        expected,
+        actual,
+      });
+    }
+  }
+  const extra = actualFiles.filter((entry) => !expectedByPath.has(entry.path)).map((entry) => entry.path);
+  if (missing.length > 0 || mismatched.length > 0 || extra.length > 0) {
+    throw new PublishedGameIntegrityError(
+      'published_game_file_mismatch',
+      'Published game package contents do not match the signed integrity manifest.',
+      {
+        missing,
+        extra,
+        mismatched,
+      },
+    );
+  }
+
+  const packageJson = readJsonFile(resolve(packageRoot, 'package.json'));
+  const actualPackageMetadata = {
+    name: normalizeString(packageJson?.name),
+    version: normalizeString(packageJson?.version),
+    description: normalizeString(packageJson?.description),
+    type: normalizeString(packageJson?.type),
+    aurajsVersion: normalizeString((packageJson.dependencies as Record<string, unknown> | undefined)?.['@auraindustry/aurajs']),
+    bin: normalizeBinMap(packageJson),
+  };
+  if (stableSerialize(actualPackageMetadata) !== stableSerialize(manifest.package || {})) {
+    throw new PublishedGameIntegrityError(
+      'published_game_package_metadata_mismatch',
+      'Installed package.json metadata does not match the signed integrity manifest.',
+      {
+        expected: manifest.package || null,
+        actual: actualPackageMetadata,
+      },
+    );
+  }
+
+  const actualAuthoredMetadata = normalizeAuthoredMetadata(packageRoot);
+  if (stableSerialize(actualAuthoredMetadata) !== stableSerialize((manifest.publishedMetadata as Record<string, unknown> | undefined)?.authored || {})) {
+    throw new PublishedGameIntegrityError(
+      'published_game_authored_metadata_mismatch',
+      'Installed authored game metadata does not match the signed integrity manifest.',
+      {
+        expected: (manifest.publishedMetadata as Record<string, unknown> | undefined)?.authored || null,
+        actual: actualAuthoredMetadata,
+      },
+    );
+  }
+
+  const trust = updateSignerTrustStore(
+    normalizeString(input.trustRoot),
+    normalizeString(actualPackageMetadata.name) || '<unknown>',
+    normalizeString(actualPackageMetadata.version),
+    signerFingerprint,
+  );
+
+  return {
+    reasonCode: 'published_game_package_integrity_ok',
+    manifestPath,
+    signaturePath,
+    packageName: actualPackageMetadata.name,
+    packageVersion: actualPackageMetadata.version,
+    signerFingerprint,
+    trust,
+    fileCount: expectedFiles.length,
+    publishedMetadata: manifest.publishedMetadata || null,
+  };
+}