@auraindustry/aurajs 0.0.6 → 0.1.0

package/src/package-integrity.mjs

@@ -0,0 +1,586 @@
+import { createHash, createPrivateKey, createPublicKey, generateKeyPairSync, sign, verify } from 'node:crypto';
+import { chmodSync, existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+export const PACKAGE_INTEGRITY_SCHEMA = 'aurajs.package-integrity.v1';
+export const PACKAGE_INTEGRITY_MANIFEST_PATH = 'aura.package-integrity.json';
+export const PACKAGE_INTEGRITY_SIGNATURE_PATH = 'aura.package-integrity.sig';
+export const PACKAGE_INTEGRITY_PUBLISH_FILES = [
+  PACKAGE_INTEGRITY_MANIFEST_PATH,
+  PACKAGE_INTEGRITY_SIGNATURE_PATH,
+];
+export const PACKAGE_INTEGRITY_PRIVATE_KEY_PATH = join('.aura', 'publish', 'package-signing-key.pem');
+export const PACKAGE_INTEGRITY_PUBLIC_KEY_PATH = join('.aura', 'publish', 'package-signing-key.pub.pem');
+export const PACKAGE_INTEGRITY_TRUST_STORE_PATH = join('published-game-signers.json');
+
+export class PackageIntegrityError extends Error {
+  constructor(reasonCode, message, details = {}) {
+    super(message);
+    this.name = 'PackageIntegrityError';
+    this.reasonCode = typeof reasonCode === 'string' && reasonCode.length > 0
+      ? reasonCode
+      : 'package_integrity_failed';
+    this.details = details && typeof details === 'object' ? details : {};
+  }
+}
+
+function normalizeRelativePath(pathLike) {
+  return String(pathLike || '')
+    .trim()
+    .replace(/^[.][\\/]/, '')
+    .replaceAll('\\', '/');
+}
+
+function normalizeString(value) {
+  return typeof value === 'string' && value.trim().length > 0
+    ? value.trim()
+    : null;
+}
+
+function sha256Buffer(buffer) {
+  return createHash('sha256').update(buffer).digest('hex');
+}
+
+function sortKeysDeep(value) {
+  if (Array.isArray(value)) {
+    return value.map((entry) => sortKeysDeep(entry));
+  }
+  if (!value || typeof value !== 'object') {
+    return value;
+  }
+
+  const sorted = {};
+  for (const key of Object.keys(value).sort()) {
+    sorted[key] = sortKeysDeep(value[key]);
+  }
+  return sorted;
+}
+
+function stableSerialize(value, pretty = false) {
+  return JSON.stringify(sortKeysDeep(value), null, pretty ? 2 : 0);
+}
+
+function readJsonFile(path) {
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new PackageIntegrityError(
+      'package_integrity_json_invalid',
+      `Failed to parse ${path}: ${error.message}`,
+      { path },
+    );
+  }
+}
+
+function listHashedPackageFiles(root, current = root, acc = []) {
+  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 PackageIntegrityError(
+        'package_integrity_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 buffer = readFileSync(fullPath);
+    acc.push({
+      path: relativePath,
+      size: buffer.length,
+      sha256: sha256Buffer(buffer),
+    });
+  }
+
+  acc.sort((left, right) => left.path.localeCompare(right.path));
+  return acc;
+}
+
+function normalizeBinMap(projectPackage) {
+  if (typeof projectPackage?.bin === 'string' && projectPackage.bin.trim().length > 0) {
+    return {
+      [projectPackage.name?.split('/').pop() || 'game']: normalizeRelativePath(projectPackage.bin),
+    };
+  }
+
+  const normalized = {};
+  for (const key of Object.keys(projectPackage?.bin || {}).sort()) {
+    const value = projectPackage.bin[key];
+    if (typeof value !== 'string' || value.trim().length === 0) {
+      continue;
+    }
+    normalized[key] = normalizeRelativePath(value);
+  }
+  return normalized;
+}
+
+function normalizeAuthoredMetadata(packageRoot) {
+  const configPath = resolve(packageRoot, 'aura.config.json');
+  if (!existsSync(configPath)) {
+    return {
+      identity: null,
+      window: null,
+    };
+  }
+
+  const config = readJsonFile(configPath);
+  const iconPath = normalizeString(config?.identity?.icon);
+  const normalizedIconPath = iconPath ? normalizeRelativePath(iconPath) : null;
+  const iconAbsolutePath = normalizedIconPath ? resolve(packageRoot, normalizedIconPath) : null;
+  const iconStats = iconAbsolutePath && existsSync(iconAbsolutePath) && lstatSync(iconAbsolutePath).isFile()
+    ? readFileSync(iconAbsolutePath)
+    : null;
+
+  return {
+    identity: {
+      name: normalizeString(config?.identity?.name),
+      version: normalizeString(config?.identity?.version),
+      executable: normalizeString(config?.identity?.executable),
+      icon: normalizedIconPath,
+      iconAsset: {
+        path: normalizedIconPath,
+        exists: Boolean(iconStats),
+        size: iconStats ? iconStats.length : null,
+        sha256: iconStats ? sha256Buffer(iconStats) : null,
+      },
+    },
+    window: {
+      title: normalizeString(config?.window?.title),
+    },
+  };
+}
+
+function normalizeBuildMetadata(buildMetadata = {}) {
+  const buildRoot = buildMetadata?.buildRoot ? resolve(buildMetadata.buildRoot) : null;
+  const iconOutputPath = normalizeString(buildMetadata?.icon?.outputPath);
+  const normalizedIconOutputPath = iconOutputPath ? normalizeRelativePath(iconOutputPath) : null;
+  const iconOutputAbsolutePath = buildRoot && normalizedIconOutputPath
+    ? resolve(buildRoot, normalizedIconOutputPath)
+    : null;
+  const iconOutputBytes = iconOutputAbsolutePath && existsSync(iconOutputAbsolutePath) && lstatSync(iconOutputAbsolutePath).isFile()
+    ? readFileSync(iconOutputAbsolutePath)
+    : null;
+
+  return {
+    buildTarget: normalizeString(buildMetadata?.buildTarget),
+    identity: {
+      name: normalizeString(buildMetadata?.identity?.name),
+      version: normalizeString(buildMetadata?.identity?.version),
+      windowTitle: normalizeString(buildMetadata?.identity?.windowTitle),
+      executableBaseName: normalizeString(buildMetadata?.identity?.executableBaseName),
+      executableFileName: normalizeString(buildMetadata?.identity?.executableFileName),
+    },
+    icon: {
+      configuredPath: normalizeString(buildMetadata?.icon?.configuredPath),
+      discoveredPath: normalizeString(buildMetadata?.icon?.discoveredPath),
+      resolvedPath: normalizeString(buildMetadata?.icon?.resolvedPath),
+      outputPath: normalizedIconOutputPath,
+      outputSha256: iconOutputBytes ? sha256Buffer(iconOutputBytes) : null,
+      status: normalizeString(buildMetadata?.icon?.status),
+      reasonCode: normalizeString(buildMetadata?.icon?.reasonCode),
+    },
+  };
+}
+
+function buildManifestBody({ packageRoot, projectPackage, buildMetadata = null, signer }) {
+  const resolvedPackage = projectPackage || readJsonFile(resolve(packageRoot, 'package.json'));
+  return {
+    schema: PACKAGE_INTEGRITY_SCHEMA,
+    package: {
+      name: normalizeString(resolvedPackage?.name),
+      version: normalizeString(resolvedPackage?.version),
+      description: normalizeString(resolvedPackage?.description),
+      type: normalizeString(resolvedPackage?.type),
+      aurajsVersion: normalizeString(resolvedPackage?.dependencies?.['@auraindustry/aurajs']),
+      bin: normalizeBinMap(resolvedPackage),
+    },
+    publishedMetadata: {
+      authored: normalizeAuthoredMetadata(packageRoot),
+      build: normalizeBuildMetadata(buildMetadata),
+    },
+    signer: {
+      algorithm: 'ed25519',
+      publicKeyPem: signer.publicKeyPem,
+      fingerprint: signer.fingerprint,
+    },
+    files: listHashedPackageFiles(packageRoot),
+  };
+}
+
+function ensureSignerKeyPair(projectRoot) {
+  const privateKeyPath = resolve(projectRoot, PACKAGE_INTEGRITY_PRIVATE_KEY_PATH);
+  const publicKeyPath = resolve(projectRoot, PACKAGE_INTEGRITY_PUBLIC_KEY_PATH);
+
+  if (!existsSync(privateKeyPath)) {
+    mkdirSync(dirname(privateKeyPath), { recursive: true });
+    const generated = generateKeyPairSync('ed25519', {
+      privateKeyEncoding: {
+        format: 'pem',
+        type: 'pkcs8',
+      },
+      publicKeyEncoding: {
+        format: 'pem',
+        type: 'spki',
+      },
+    });
+    writeFileSync(privateKeyPath, generated.privateKey, 'utf8');
+    writeFileSync(publicKeyPath, generated.publicKey, 'utf8');
+    if (process.platform !== 'win32') {
+      chmodSync(privateKeyPath, 0o600);
+    }
+  } else if (!existsSync(publicKeyPath)) {
+    const privateKeyPem = readFileSync(privateKeyPath, 'utf8');
+    const derivedPublicKey = createPublicKey(createPrivateKey(privateKeyPem))
+      .export({ format: 'pem', type: 'spki' })
+      .toString();
+    writeFileSync(publicKeyPath, derivedPublicKey, 'utf8');
+  }
+
+  const privateKeyPem = readFileSync(privateKeyPath, 'utf8');
+  const publicKeyPem = readFileSync(publicKeyPath, 'utf8');
+  const fingerprint = sha256Buffer(
+    createPublicKey(publicKeyPem).export({ format: 'der', type: 'spki' }),
+  );
+
+  return {
+    privateKeyPath,
+    publicKeyPath,
+    privateKeyPem,
+    publicKeyPem,
+    fingerprint,
+  };
+}
+
+function readManifestAndSignature(packageRoot) {
+  const manifestPath = resolve(packageRoot, PACKAGE_INTEGRITY_MANIFEST_PATH);
+  const signaturePath = resolve(packageRoot, PACKAGE_INTEGRITY_SIGNATURE_PATH);
+  if (!existsSync(manifestPath) || !existsSync(signaturePath)) {
+    throw new PackageIntegrityError(
+      'package_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 (!signature) {
+    throw new PackageIntegrityError(
+      'package_integrity_signature_missing',
+      `${PACKAGE_INTEGRITY_SIGNATURE_PATH} is empty.`,
+      { signaturePath },
+    );
+  }
+
+  return {
+    manifestPath,
+    signaturePath,
+    manifest,
+    signature,
+  };
+}
+
+function assertManifestSignature(manifest, signature) {
+  if (manifest?.schema !== PACKAGE_INTEGRITY_SCHEMA) {
+    throw new PackageIntegrityError(
+      'package_integrity_schema_invalid',
+      `Expected ${PACKAGE_INTEGRITY_SCHEMA}, found ${manifest?.schema || '<missing>'}.`,
+      {
+        schema: manifest?.schema || null,
+      },
+    );
+  }
+
+  const publicKeyPem = normalizeString(manifest?.signer?.publicKeyPem);
+  const signerFingerprint = normalizeString(manifest?.signer?.fingerprint);
+  if (!publicKeyPem || !signerFingerprint) {
+    throw new PackageIntegrityError(
+      'package_integrity_signer_missing',
+      'Package integrity manifest is missing signer metadata.',
+      {},
+    );
+  }
+
+  const actualFingerprint = sha256Buffer(
+    createPublicKey(publicKeyPem).export({ format: 'der', type: 'spki' }),
+  );
+  if (actualFingerprint !== signerFingerprint) {
+    throw new PackageIntegrityError(
+      'package_integrity_signer_fingerprint_mismatch',
+      'Package integrity signer fingerprint does not match the embedded public key.',
+      {
+        expectedFingerprint: signerFingerprint,
+        actualFingerprint,
+      },
+    );
+  }
+
+  const ok = verify(
+    null,
+    Buffer.from(stableSerialize(manifest)),
+    publicKeyPem,
+    Buffer.from(signature, 'base64'),
+  );
+  if (!ok) {
+    throw new PackageIntegrityError(
+      'package_integrity_signature_invalid',
+      'Package integrity signature verification failed.',
+      {
+        fingerprint: signerFingerprint,
+      },
+    );
+  }
+
+  return {
+    publicKeyPem,
+    fingerprint: signerFingerprint,
+  };
+}
+
+function loadTrustStore(trustRoot) {
+  if (!trustRoot) {
+    return {
+      storePath: null,
+      entries: {},
+    };
+  }
+
+  const storePath = resolve(trustRoot, PACKAGE_INTEGRITY_TRUST_STORE_PATH);
+  if (!existsSync(storePath)) {
+    return {
+      storePath,
+      entries: {},
+    };
+  }
+
+  try {
+    return {
+      storePath,
+      entries: JSON.parse(readFileSync(storePath, 'utf8')) || {},
+    };
+  } catch (error) {
+    throw new PackageIntegrityError(
+      'package_integrity_trust_store_invalid',
+      `Failed to parse signer trust store at ${storePath}: ${error.message}`,
+      {
+        storePath,
+      },
+    );
+  }
+}
+
+function updateTrustStore({ trustRoot, packageName, signerFingerprint, packageVersion }) {
+  if (!trustRoot) {
+    return {
+      status: 'unchecked',
+      storePath: null,
+    };
+  }
+
+  const { storePath, entries } = loadTrustStore(trustRoot);
+  const existing = entries[packageName] || null;
+  if (existing?.signerFingerprint && existing.signerFingerprint !== signerFingerprint) {
+    throw new PackageIntegrityError(
+      'package_integrity_signer_changed',
+      `Published game signer changed for ${packageName}: expected ${existing.signerFingerprint}, got ${signerFingerprint}.`,
+      {
+        packageName,
+        packageVersion,
+        expectedFingerprint: existing.signerFingerprint,
+        actualFingerprint: signerFingerprint,
+        storePath,
+      },
+    );
+  }
+
+  const now = new Date().toISOString();
+  const next = {
+    ...entries,
+    [packageName]: {
+      signerFingerprint,
+      firstSeenAt: existing?.firstSeenAt || now,
+      lastSeenAt: now,
+      lastVersion: packageVersion || null,
+    },
+  };
+  mkdirSync(dirname(storePath), { recursive: true });
+  writeFileSync(storePath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+
+  return {
+    status: existing ? 'trusted' : 'trusted_first_use',
+    storePath,
+  };
+}
+
+function assertFileInventory(manifestFiles, packageRoot) {
+  const actualFiles = listHashedPackageFiles(packageRoot);
+  const expectedByPath = new Map((manifestFiles || []).map((entry) => [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 PackageIntegrityError(
+      'package_integrity_file_mismatch',
+      'Published game package contents do not match the signed integrity manifest.',
+      {
+        missing,
+        extra,
+        mismatched,
+      },
+    );
+  }
+
+  return actualFiles;
+}
+
+function assertManifestMetadataMatchesInstalledPackage(manifest, packageRoot) {
+  const projectPackage = readJsonFile(resolve(packageRoot, 'package.json'));
+  const actualPackageMetadata = {
+    name: normalizeString(projectPackage?.name),
+    version: normalizeString(projectPackage?.version),
+    description: normalizeString(projectPackage?.description),
+    type: normalizeString(projectPackage?.type),
+    aurajsVersion: normalizeString(projectPackage?.dependencies?.['@auraindustry/aurajs']),
+    bin: normalizeBinMap(projectPackage),
+  };
+
+  if (stableSerialize(actualPackageMetadata) !== stableSerialize(manifest?.package || {})) {
+    throw new PackageIntegrityError(
+      'package_integrity_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?.authored || {})) {
+    throw new PackageIntegrityError(
+      'package_integrity_authored_metadata_mismatch',
+      'Installed authored game metadata does not match the signed integrity manifest.',
+      {
+        expected: manifest?.publishedMetadata?.authored || null,
+        actual: actualAuthoredMetadata,
+      },
+    );
+  }
+}
+
+export function writeSignedPackageIntegrityArtifacts({
+  packageRoot,
+  signerProjectRoot = packageRoot,
+  buildMetadata = null,
+  projectPackage = null,
+} = {}) {
+  const resolvedPackageRoot = resolve(packageRoot || process.cwd());
+  const signer = ensureSignerKeyPair(resolve(signerProjectRoot || resolvedPackageRoot));
+  const manifest = buildManifestBody({
+    packageRoot: resolvedPackageRoot,
+    projectPackage,
+    buildMetadata,
+    signer,
+  });
+  const signature = sign(
+    null,
+    Buffer.from(stableSerialize(manifest)),
+    signer.privateKeyPem,
+  ).toString('base64');
+
+  const manifestPath = resolve(resolvedPackageRoot, PACKAGE_INTEGRITY_MANIFEST_PATH);
+  const signaturePath = resolve(resolvedPackageRoot, PACKAGE_INTEGRITY_SIGNATURE_PATH);
+  writeFileSync(manifestPath, `${stableSerialize(manifest, true)}\n`, 'utf8');
+  writeFileSync(signaturePath, `${signature}\n`, 'utf8');
+
+  return {
+    manifestPath,
+    signaturePath,
+    schema: manifest.schema,
+    packageName: manifest.package.name,
+    packageVersion: manifest.package.version,
+    fileCount: manifest.files.length,
+    signerFingerprint: signer.fingerprint,
+    publishedMetadata: manifest.publishedMetadata,
+  };
+}
+
+export function verifySignedPackageIntegrity({
+  packageRoot,
+  expectedPackageName = null,
+  trustRoot = null,
+} = {}) {
+  const resolvedPackageRoot = resolve(packageRoot || process.cwd());
+  const { manifestPath, signaturePath, manifest, signature } = readManifestAndSignature(resolvedPackageRoot);
+  const signer = assertManifestSignature(manifest, signature);
+  if (expectedPackageName && normalizeString(manifest?.package?.name) !== normalizeString(expectedPackageName)) {
+    throw new PackageIntegrityError(
+      'package_integrity_package_name_mismatch',
+      `Expected published package ${expectedPackageName}, found ${manifest?.package?.name || '<missing>'}.`,
+      {
+        expectedPackageName,
+        actualPackageName: manifest?.package?.name || null,
+      },
+    );
+  }
+
+  assertFileInventory(manifest?.files, resolvedPackageRoot);
+  assertManifestMetadataMatchesInstalledPackage(manifest, resolvedPackageRoot);
+  const trust = updateTrustStore({
+    trustRoot,
+    packageName: manifest.package.name,
+    packageVersion: manifest.package.version,
+    signerFingerprint: signer.fingerprint,
+  });
+
+  return {
+    reasonCode: 'package_integrity_ok',
+    manifestPath,
+    signaturePath,
+    packageName: manifest.package.name,
+    packageVersion: manifest.package.version,
+    signerFingerprint: signer.fingerprint,
+    trust,
+    fileCount: Array.isArray(manifest?.files) ? manifest.files.length : 0,
+    publishedMetadata: manifest.publishedMetadata || null,
+  };
+}