bare-operating-system/packages/bare-os-booter/lib/p2p/bare-os-peer-system-seed.js

/**
 * Peer-assisted seeding: booted booters may mirror MBR + seed RPC snapshots for
 * cold joiners when {@link peerSystemSeedEnvEnabled} (default **on**; opt out with
 * **`BARE_OS_PEER_SYSTEM_SEED=0`**, **`false`**, **`no`**, or **`off`**).
 */

import b4a from 'b4a'
import {
  BARE_OS_KERNEL_CAPABILITY_WIRE_VERSION,
  BARE_OS_KERNEL_CAPABILITY_WORDS_JSON_KEY,
  BARE_OS_KERNEL_FEATURES_STOCK_WORD_PRIMARY,
  BARE_OS_KERNEL_FEATURE_BITS_DOC,
  BARE_OS_PROTOCOL_PACKAGE_VERSION,
  PROTOCOL_NAME,
  getKernelCapabilityWords
} from 'bare-os-protocol'
import { buildStockKernelCapabilityWords } from '../security/bare-os-capability-registry.js'

/**
 * Whether peer system seeding may run (default **enabled** when unset).
 * @param {Record<string, string | undefined> | null | undefined} env
 * @returns {boolean}
 */
export function peerSystemSeedEnvEnabled(env) {
  const v = String(env?.BARE_OS_PEER_SYSTEM_SEED ?? '')
    .trim()
    .toLowerCase()
  if (v === '0' || v === 'false' || v === 'no' || v === 'off') return false
  if (v === '1' || v === 'true' || v === 'yes' || v === 'on') return true
  const p = String(env?.BARE_OS_ZERO_TRUST_PROFILE || '')
    .trim()
    .toLowerCase()
  if (p === 'strict' || p === 'security') return false
  return true
}

/**
 * Operator explicitly set **`BARE_OS_PEER_SYSTEM_SEED`** to an affirmative token
 * (**`1`**, **`true`**, **`yes`**). Used for host diagnostics when eligibility fails.
 * @param {Record<string, string | undefined> | null | undefined} env
 */
export function peerSystemSeedExplicitAffirmative(env) {
  const v = String(env?.BARE_OS_PEER_SYSTEM_SEED ?? '')
    .trim()
    .toLowerCase()
  return v === '1' || v === 'true' || v === 'yes'
}

/**
 * @param {import('./swarm-disk.js').SwarmDisk} disk
 * @returns {Record<string, unknown | null>}
 */
/**
 * After a successful swarm boot, fill {@link import('./swarm-disk.js').SwarmDisk#seedCapabilityInfo}
 * with stock kernel capability words when the publisher handshake was skipped, failed, or returned
 * no words — so {@link computePeerSystemSeedEligibility} can pass and more nodes mirror **block 0**.
 *
 * Opt out with **`BARE_OS_PEER_SEED_SYNTHETIC_CAPABILITIES`** **`0`** / **`false`** / **`no`** / **`off`**.
 *
 * **`imageTipId`** on the synthetic object (for tip gates and cold joiners) is taken from, in order:
 * **`BARE_OS_SEED_IMAGE_TIP_ID`**, **`BARE_OS_PEER_SEED_ADVERTISE_IMAGE_TIP_ID`**, **`BARE_OS_PEER_SEED_IMAGE_TIP_ID`**,
 * then any **`imageTipId`** on a partial non-error capability object.
 *
 * @param {import('./swarm-disk.js').SwarmDisk} disk
 * @param {Record<string, string | undefined> | null | undefined} env
 */
export function maybeSynthesizePeerSeedCapabilityInfo(disk, env) {
  const p = String(env?.BARE_OS_ZERO_TRUST_PROFILE || '')
    .trim()
    .toLowerCase()
  if (p === 'strict' || p === 'security') return
  const off = String(env?.BARE_OS_PEER_SEED_SYNTHETIC_CAPABILITIES ?? '')
    .trim()
    .toLowerCase()
  if (off === '0' || off === 'false' || off === 'no' || off === 'off') return

  const mbr = disk?.bootMbr512
  if (!mbr || !(mbr instanceof Uint8Array) || mbr.length !== 512) return

  const cap = disk.seedCapabilityInfo
  const hasUsableWords =
    cap &&
    typeof cap === 'object' &&
    !('error' in cap && cap.error) &&
    getKernelCapabilityWords(cap)
  if (hasUsableWords) return

  const words = buildStockKernelCapabilityWords(
    BARE_OS_KERNEL_FEATURES_STOCK_WORD_PRIMARY
  )

  const partial =
    cap && typeof cap === 'object' && !('error' in cap && cap.error)
      ? /** @type {Record<string, unknown>} */ (cap)
      : null
  const fromPartial =
    partial && typeof partial.imageTipId === 'string'
      ? String(partial.imageTipId).trim()
      : ''

  const tip =
    String(env?.BARE_OS_SEED_IMAGE_TIP_ID ?? '').trim() ||
    String(env?.BARE_OS_PEER_SEED_ADVERTISE_IMAGE_TIP_ID ?? '').trim() ||
    String(env?.BARE_OS_PEER_SEED_IMAGE_TIP_ID ?? '').trim() ||
    fromPartial

  const base = partial
    ? {
        ...partial,
        [BARE_OS_KERNEL_CAPABILITY_WORDS_JSON_KEY]: words
      }
    : {
        doc: BARE_OS_KERNEL_FEATURE_BITS_DOC,
        featureBitsDoc: BARE_OS_KERNEL_FEATURE_BITS_DOC,
        [BARE_OS_KERNEL_CAPABILITY_WORDS_JSON_KEY]: words,
        kernelCapabilityWireVersion: BARE_OS_KERNEL_CAPABILITY_WIRE_VERSION,
        protocolPackageVersion: BARE_OS_PROTOCOL_PACKAGE_VERSION,
        protocol: PROTOCOL_NAME,
        role: 'seeder',
        note:
          'Synthetic capabilities: stock kernelCapabilityWords after successful swarm boot (publisher snapshot missing or incomplete).'
      }

  if (typeof base.doc !== 'string')
    base.doc = BARE_OS_KERNEL_FEATURE_BITS_DOC
  if (typeof base.featureBitsDoc !== 'string') {
    base.featureBitsDoc =
      typeof base.doc === 'string' ? base.doc : BARE_OS_KERNEL_FEATURE_BITS_DOC
  }
  if (typeof base.kernelCapabilityWireVersion !== 'number') {
    base.kernelCapabilityWireVersion = BARE_OS_KERNEL_CAPABILITY_WIRE_VERSION
  }
  if (typeof base.protocolPackageVersion !== 'string') {
    base.protocolPackageVersion = BARE_OS_PROTOCOL_PACKAGE_VERSION
  }
  if (typeof base.protocol !== 'string') base.protocol = PROTOCOL_NAME
  if (typeof base.role !== 'string') base.role = 'seeder'

  delete base.error

  if (tip) base.imageTipId = tip
  else delete base.imageTipId

  disk.seedCapabilityInfo = /** @type {Record<string, unknown>} */ (base)
}

export function buildPeerSeedSnapshots(disk) {
  return {
    replication_status: disk.seedReplicationStatus ?? null,
    manifest_hints: disk.seedManifestHints ?? null,
    peer_health: disk.seedPeerHealth ?? null,
    staging_slot: disk.seedStagingSlot ?? null,
    replication_queue: disk.seedReplicationQueue ?? null,
    capability_attestation: disk.seedCapabilityAttestation ?? null,
    mbr_layout: disk.seedMbrLayout ?? null,
    snapshot_hints: disk.seedSnapshotHints ?? null,
    peer_firewall_stats: disk.seedPeerFirewallStats ?? null,
    replication_plan: disk.seedReplicationPlan ?? null,
    dht_bootstrap_hint: disk.seedDhtBootstrapHint ?? null,
    snapshot_chain: disk.seedSnapshotChain ?? null,
    mirror_compaction_hint: disk.seedMirrorCompactionHint ?? null,
    updater_state: disk.seedUpdaterState ?? null,
    blind_peer_topology_v2: disk.seedBlindPeerTopologyV2 ?? null,
    compact_ping: disk.seedCompactPing ?? null,
    corestore_stats: disk.seedCorestoreStats ?? null,
    snapshot_manifest_slice: disk.seedSnapshotManifestSlice ?? null,
    mirror_drive_hint_v2: disk.seedMirrorDriveHintV2 ?? null,
    hrpc_registry_summary: disk.seedHrpcRegistrySummary ?? null,
    protomux_capability_ad: disk.seedProtomuxCapabilityAd ?? null,
    dht_address_book: disk.seedDhtAddressBook ?? null,
    replication_throttle_hint: disk.seedReplicationThrottleHint ?? null,
    bundlebee_stage: disk.seedBundlebeeStage ?? null,
    http_dht_proxy_hint: disk.seedHttpDhtProxyHint ?? null,
    protomux_rpc_pool_hint: disk.seedProtomuxRpcPoolHint ?? null,
    hyperblob_store_hint: disk.seedHyperblobStoreHint ?? null,
    signing_request_queue_hint: disk.seedSigningRequestQueueHint ?? null,
    core_storage_layout_hint: disk.seedCoreStorageLayoutHint ?? null,
    mirror_drive_compaction_v3: disk.seedMirrorDriveCompactionV3 ?? null,
    bundlebee_cli_stage: disk.seedBundlebeeCliStage ?? null,
    ready_guard_v2: disk.seedReadyGuardV2 ?? null,
    blind_relay_circuit_hint: disk.seedBlindRelayCircuitHint ?? null,
    http_dht_proxy_routes: disk.seedHttpDhtProxyRoutes ?? null
  }
}

/**
 * @param {{
 *   disk: import('./swarm-disk.js').SwarmDisk
 *   systemRevision: Readonly<{ currentId?: string; pendingId?: string; slot?: string }> | null | undefined
 *   env: Record<string, string | undefined> | null | undefined
 * }} args
 * @returns {{ ok: true } | { ok: false, reason: string }}
 */
export function computePeerSystemSeedEligibility(args) {
  const { disk, systemRevision, env } = args
  if (!peerSystemSeedEnvEnabled(env)) {
    return { ok: false, reason: 'env_disabled' }
  }
  const cap = disk.seedCapabilityInfo
  if (!cap || typeof cap !== 'object') {
    return { ok: false, reason: 'no_seed_capability_info' }
  }
  if ('error' in cap && cap.error) {
    return { ok: false, reason: 'seed_capability_error' }
  }
  if (cap.role === 'offline-lkg') {
    return { ok: false, reason: 'offline_lkg' }
  }
  const words = getKernelCapabilityWords(cap)
  if (!words) {
    return { ok: false, reason: 'no_kernel_capability_words' }
  }
  const mbr = disk.bootMbr512
  if (!mbr || !(mbr instanceof Uint8Array) || mbr.length !== 512) {
    return { ok: false, reason: 'no_boot_mbr' }
  }
  const drive = disk.drive
  if (!drive || typeof drive.id === 'undefined') {
    return { ok: false, reason: 'no_system_drive' }
  }
  const primaryHex = Array.isArray(disk.mbrKeysHex) ? disk.mbrKeysHex[0] : ''
  const idHex = b4a.toString(drive.id, 'hex').toLowerCase()
  if (!primaryHex || idHex !== String(primaryHex).toLowerCase()) {
    return { ok: false, reason: 'drive_key_not_mbr_primary' }
  }

  const wantTip = String(env?.BARE_OS_PEER_SEED_IMAGE_TIP_ID ?? '').trim()
  if (wantTip) {
    const got = String(
      /** @type {Record<string, unknown>} */ (cap).imageTipId ?? ''
    ).trim()
    if (got !== wantTip) {
      return { ok: false, reason: 'image_tip_mismatch' }
    }
  }

  const wantRev = String(env?.BARE_OS_PEER_SEED_REQUIRE_REVISION_ID ?? '').trim()
  if (wantRev) {
    const cur = String(systemRevision?.currentId ?? '').trim()
    if (cur !== wantRev) {
      return { ok: false, reason: 'system_revision_mismatch' }
    }
  }

  return { ok: true }
}