@secondlayer/shared 8.0.0 → 10.0.0

package/dist/src/runtime/index.js

@@ -337,7 +337,11 @@ var KNOWN = new Set([
   "SUBGRAPH_INDEX_API_URL",
   "SBTC_DECODER_ENABLED",
   "POX4_DECODER_ENABLED",
-  "BNS_DECODER_ENABLED"
+  "BNS_DECODER_ENABLED",
+  "ARCHIVE_DIR",
+  "ARCHIVE_PUBLIC_DIR",
+  "SECONDLAYER_ALLOW_UNDERSIZED",
+  "SECONDLAYER_SYNC_START_HEIGHT"
 ]);
 var OWN_PREFIXES = [
   "SECONDLAYER_",
@@ -499,6 +503,14 @@ function actionFor(plane, state) {
   return "inspect logs";
 }
 // src/runtime/backup.ts
+import {
+  createCipheriv,
+  createDecipheriv,
+  randomBytes,
+  scryptSync,
+  timingSafeEqual
+} from "node:crypto";
+var BACKUP_MANIFEST_VERSION = 1;
 var BACKUP_PARTS = [
   "db",
   "config",
@@ -506,55 +518,209 @@ var BACKUP_PARTS = [
   "handlers",
   "scope"
 ];
+var CANARY_PLAINTEXT = "secondlayer-secrets-key-canary-v1";
+var IV_LEN = 12;
+var TAG_LEN = 16;
+var SALT_LEN = 16;
+var SCRYPT_COST = 2 ** 15;
+var SCRYPT_MAXMEM = 64 * 1024 * 1024;
+var SCRYPT_OPTS = { N: SCRYPT_COST, maxmem: SCRYPT_MAXMEM };
 function planBackup(input) {
-  if (!input.encryptedKeys) {
+  if (input.fromHeight < 0) {
+    return { ok: false, reason: "scope from_height must be >= 0" };
+  }
+  if (input.toHeight !== null && input.toHeight !== undefined && input.toHeight < input.fromHeight) {
+    return { ok: false, reason: "scope to_height is below from_height" };
+  }
+  if (input.includeSecrets && !input.secretsEncrypted) {
     return {
       ok: false,
-      manifest: emptyManifest(input),
-      reason: "keys must be encrypted"
+      reason: "refusing to write plaintext secrets; supply a passphrase or pass the explicit plaintext override"
     };
   }
-  if (input.fromHeight < 0) {
+  if (input.includeSecrets && !input.canary) {
     return {
       ok: false,
-      manifest: emptyManifest(input),
-      reason: "scope from_height must be >= 0"
+      reason: "secrets bundle requires a key canary so a restore can prove the key matches"
     };
   }
+  const parts = input.includeSecrets ? [...BACKUP_PARTS] : BACKUP_PARTS.filter((p) => p !== "keys");
   return {
     ok: true,
     manifest: {
-      created_at: input.now ?? "1970-01-01T00:00:00.000Z",
+      schema_version: BACKUP_MANIFEST_VERSION,
+      created_at: input.now ?? new Date().toISOString(),
       network: input.network,
-      parts: [...BACKUP_PARTS],
-      encrypted: true,
+      parts,
+      encrypted: input.secretsEncrypted,
       scope: {
         from_height: input.fromHeight,
         to_height: input.toHeight ?? null
-      }
-    },
-    reason: "dry-run backup bundle"
+      },
+      db: null,
+      secrets: null
+    }
   };
 }
-function restoreBackup(plan, opts) {
-  if (!plan.ok)
-    return { ok: false, reason: plan.reason };
-  if (!opts?.apply)
-    return { ok: true, applied: false, deep_green: false };
+function secretsKeyBuffer(hexKey) {
+  const key = Buffer.from(hexKey.trim(), "hex");
+  if (key.length !== 32) {
+    throw new Error("SECONDLAYER_SECRETS_KEY must be 32 bytes hex");
+  }
+  return key;
+}
+function sealKeyCanary(secretsKeyHex) {
+  const key = secretsKeyBuffer(secretsKeyHex);
+  const iv = randomBytes(IV_LEN);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(CANARY_PLAINTEXT, "utf8"),
+    cipher.final()
+  ]);
+  return Buffer.concat([iv, cipher.getAuthTag(), ciphertext]).toString("base64");
+}
+function keyMatchesCanary(canaryBase64, secretsKeyHex) {
+  try {
+    const key = secretsKeyBuffer(secretsKeyHex);
+    const envelope = Buffer.from(canaryBase64, "base64");
+    const iv = envelope.subarray(0, IV_LEN);
+    const tag = envelope.subarray(IV_LEN, IV_LEN + TAG_LEN);
+    const ciphertext = envelope.subarray(IV_LEN + TAG_LEN);
+    const decipher = createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(tag);
+    const plaintext = Buffer.concat([
+      decipher.update(ciphertext),
+      decipher.final()
+    ]);
+    const expected = Buffer.from(CANARY_PLAINTEXT, "utf8");
+    return plaintext.length === expected.length && timingSafeEqual(plaintext, expected);
+  } catch {
+    return false;
+  }
+}
+function encryptBundle(plaintext, passphrase) {
+  if (!passphrase)
+    throw new Error("passphrase is required");
+  const salt = randomBytes(SALT_LEN);
+  const key = scryptSync(passphrase, salt, 32, SCRYPT_OPTS);
+  const iv = randomBytes(IV_LEN);
+  const cipher = createCipheriv("aes-256-gcm", key, iv);
+  const ciphertext = Buffer.concat([
+    cipher.update(plaintext, "utf8"),
+    cipher.final()
+  ]);
+  return Buffer.concat([salt, iv, cipher.getAuthTag(), ciphertext]);
+}
+function decryptBundle(envelope, passphrase) {
+  const salt = envelope.subarray(0, SALT_LEN);
+  const iv = envelope.subarray(SALT_LEN, SALT_LEN + IV_LEN);
+  const tag = envelope.subarray(SALT_LEN + IV_LEN, SALT_LEN + IV_LEN + TAG_LEN);
+  const ciphertext = envelope.subarray(SALT_LEN + IV_LEN + TAG_LEN);
+  const key = scryptSync(passphrase, salt, 32, SCRYPT_OPTS);
+  const decipher = createDecipheriv("aes-256-gcm", key, iv);
+  decipher.setAuthTag(tag);
+  return decipher.update(ciphertext).toString("utf8") + decipher.final("utf8");
+}
+function precheckRestore(input) {
+  if (input.manifest.schema_version !== BACKUP_MANIFEST_VERSION) {
+    return {
+      ok: false,
+      fatal: true,
+      reason: `bundle schema_version ${input.manifest.schema_version} is not supported (expected ${BACKUP_MANIFEST_VERSION})`
+    };
+  }
+  if (input.manifest.network !== input.targetNetwork) {
+    return {
+      ok: false,
+      fatal: true,
+      reason: `bundle is ${input.manifest.network}; this instance is ${input.targetNetwork}`
+    };
+  }
+  if (!input.targetIsEmpty && !input.force) {
+    return {
+      ok: false,
+      fatal: false,
+      reason: "target database already holds chain data; restoring would overwrite it"
+    };
+  }
+  const secrets = input.manifest.secrets;
+  if (secrets) {
+    if (!input.secretsKeyHex) {
+      return {
+        ok: false,
+        fatal: false,
+        reason: "bundle carries encrypted columns but no secrets key was supplied; restoring now would leave them unreadable"
+      };
+    }
+    if (!keyMatchesCanary(secrets.canary, input.secretsKeyHex)) {
+      return {
+        ok: false,
+        fatal: true,
+        reason: "the supplied SECONDLAYER_SECRETS_KEY does not match the one this backup was taken with; encrypted columns would be permanently unreadable"
+      };
+    }
+  }
+  return { ok: true };
+}
+// src/runtime/uninstall.ts
+var REMOVABLE = ["containers", "networks", "handler-cache"];
+var PRESERVED = ["index", "chainstate", "secrets", "backups"];
+function planUninstall(input) {
+  const preserves = [
+    {
+      what: "index",
+      detail: "the Postgres volume — rebuildable from the archive, but slow"
+    },
+    {
+      what: "chainstate",
+      detail: "bundled node data, if any — re-syncable"
+    },
+    {
+      what: "secrets",
+      detail: `${input.dataDir} and .env.local — NOT recoverable if lost`
+    },
+    { what: "backups", detail: "any bundles already written" }
+  ];
+  if (!input.purge) {
+    return {
+      ok: true,
+      warnings: [],
+      plan: {
+        removes: [...REMOVABLE],
+        preserves,
+        destroys: [],
+        purge: false
+      }
+    };
+  }
+  if (!input.confirmed) {
+    return {
+      ok: false,
+      reason: "purge destroys the index and every volume; re-run with the explicit confirmation flag"
+    };
+  }
+  if (input.secretsPresent && !input.keysBackedUp) {
+    return {
+      ok: false,
+      reason: "refusing to purge: this instance holds keys with no backup bundle. Run `secondlayer backup` first — the index can be rebuilt from the archive, the keys cannot."
+    };
+  }
   return {
     ok: true,
-    applied: true,
-    deep_green: opts.deepVerify !== false
+    warnings: [
+      "purge removes the index; a rebuild from the archive takes hours"
+    ],
+    plan: {
+      removes: [...REMOVABLE],
+      preserves: preserves.filter((p) => p.what === "secrets"),
+      destroys: ["postgres_data", "subgraphs_data"],
+      purge: true
+    }
   };
 }
-function emptyManifest(input) {
-  return {
-    created_at: input.now ?? "1970-01-01T00:00:00.000Z",
-    network: input.network,
-    parts: [],
-    encrypted: false,
-    scope: { from_height: input.fromHeight, to_height: input.toHeight ?? null }
-  };
+function uninstallCommand(plan, composeFile) {
+  const base = ["compose", "-f", composeFile, "down", "--remove-orphans"];
+  return plan.purge ? [...base, "-v"] : base;
 }
 // src/runtime/upgrade.ts
 var UPGRADE_STEPS = [
@@ -634,29 +800,133 @@ function applyUpgrade(plan, opts) {
   return { ok: true, applied: true, reason: "upgrade applied" };
 }
 // src/runtime/guardrails.ts
+var MEASURED_DISK = {
+  diskGbPer100kBlocks: 3,
+  diskGbPer100kBlocksDecoded: 6
+};
 var FLOORS = {
   appRamMb: 4096,
   fullRamMb: 98304,
+  mainnetAppDiskGb: 600,
   appDiskGb: 80,
+  mainnetFullDiskGb: 2500,
   fullDiskGb: 1500,
   postgresMaxConnections: 50
 };
-function preflightResources(snap, mode) {
+function diskFloorGb(mode, network) {
+  if (mode === "full") {
+    return network === "mainnet" ? FLOORS.mainnetFullDiskGb : FLOORS.fullDiskGb;
+  }
+  return network === "mainnet" ? FLOORS.mainnetAppDiskGb : FLOORS.appDiskGb;
+}
+function preflightResources(snap, mode, network = "mainnet") {
   const errors = [];
   const ramFloor = mode === "full" ? FLOORS.fullRamMb : FLOORS.appRamMb;
-  const diskFloor = mode === "full" ? FLOORS.fullDiskGb : FLOORS.appDiskGb;
-  if (snap.ramMb < ramFloor) {
+  const diskFloor = diskFloorGb(mode, network);
+  if (snap.ramMb !== undefined && snap.ramMb < ramFloor) {
     errors.push(`RAM ${snap.ramMb}MB below ${ramFloor}MB for NODE_MODE=${mode}`);
   }
-  if (snap.diskGb < diskFloor) {
-    errors.push(`disk ${snap.diskGb}GB below ${diskFloor}GB for NODE_MODE=${mode}`);
+  if (snap.diskGb !== undefined && snap.diskGb < diskFloor) {
+    errors.push(`disk ${snap.diskGb}GB below ${diskFloor}GB for NODE_MODE=${mode} on ${network}`);
   }
-  if (snap.postgresMaxConnections < FLOORS.postgresMaxConnections) {
+  if (snap.postgresMaxConnections !== undefined && snap.postgresMaxConnections < FLOORS.postgresMaxConnections) {
     errors.push(`Postgres max_connections ${snap.postgresMaxConnections} below ${FLOORS.postgresMaxConnections}`);
   }
   if (errors.length > 0)
     return { ok: false, errors };
-  return { ok: true, estimates: { diskGbPer100kBlocks: 1 } };
+  return { ok: true, estimates: MEASURED_DISK };
+}
+// src/runtime/resources.ts
+import { statfs } from "node:fs/promises";
+import { totalmem } from "node:os";
+var BYTES_PER_MB = 1024 * 1024;
+var BYTES_PER_GB = 1024 * 1024 * 1024;
+async function measureRamMb() {
+  try {
+    const total = totalmem();
+    return total > 0 ? Math.floor(total / BYTES_PER_MB) : null;
+  } catch {
+    return null;
+  }
+}
+async function measureDiskGb(path) {
+  try {
+    const stats = await statfs(path);
+    const totalBytes = Number(stats.blocks) * Number(stats.bsize);
+    return totalBytes > 0 ? Math.floor(totalBytes / BYTES_PER_GB) : null;
+  } catch {
+    return null;
+  }
+}
+async function measurePostgresMaxConnections(query) {
+  try {
+    const rows = await query("SHOW max_connections");
+    const raw = rows[0]?.max_connections;
+    const value = Number(raw);
+    return Number.isFinite(value) && value > 0 ? value : null;
+  } catch {
+    return null;
+  }
+}
+async function measureResources(input) {
+  const unknown = [];
+  const snapshot = {};
+  const ramMb = await measureRamMb();
+  if (ramMb === null)
+    unknown.push("RAM");
+  else
+    snapshot.ramMb = ramMb;
+  const diskGb = await measureDiskGb(input.dataDir);
+  if (diskGb === null)
+    unknown.push(`disk (${input.dataDir} unreadable)`);
+  else
+    snapshot.diskGb = diskGb;
+  if (input.query) {
+    const conns = await measurePostgresMaxConnections(input.query);
+    if (conns === null)
+      unknown.push("Postgres max_connections");
+    else
+      snapshot.postgresMaxConnections = conns;
+  } else {
+    unknown.push("Postgres max_connections (no database handle)");
+  }
+  return { snapshot, unknown };
+}
+
+// src/runtime/preflight.ts
+var UNDERSIZED_OVERRIDE = "SECONDLAYER_ALLOW_UNDERSIZED";
+function isOverridden(env) {
+  return env[UNDERSIZED_OVERRIDE]?.trim().toLowerCase() === "true";
+}
+function decidePreflight(input) {
+  const env = input.env ?? {};
+  const result = preflightResources(input.measured.snapshot, input.mode, input.network);
+  const messages = [];
+  if (input.measured.unknown.length > 0) {
+    messages.push(`resource preflight could not measure: ${input.measured.unknown.join(", ")}`);
+  }
+  if (result.ok) {
+    return { action: messages.length > 0 ? "warn" : "pass", messages };
+  }
+  messages.push(...result.errors);
+  if (isOverridden(env)) {
+    messages.push(`${UNDERSIZED_OVERRIDE}=true — starting anyway. This box is below the documented floor; expect to run out of disk as history accumulates.`);
+    return { action: "warn", messages };
+  }
+  messages.push(`Refusing to start. Resize the box, or set ${UNDERSIZED_OVERRIDE}=true to proceed at your own risk. Sizing guidance: https://www.secondlayer.tools/docs/self-host#guardrails`);
+  return { action: "refuse", messages };
+}
+async function runPreflight(input) {
+  const measured = await measureResources({
+    dataDir: input.dataDir,
+    query: input.query
+  });
+  return decidePreflight({
+    measured,
+    mode: input.mode,
+    network: input.network,
+    env: input.env
+  });
 }
 // src/runtime/commands.ts
 var MODULE_COMMANDS = {
@@ -676,16 +946,26 @@ function commandFor(id) {
   return MODULE_COMMANDS[id];
 }
 export {
-  restoreBackup,
+  uninstallCommand,
+  sealKeyCanary,
+  runPreflight,
   reportRuntimeStatus,
   preflightResources,
+  precheckRestore,
   planUpgrade,
+  planUninstall,
   planBackup,
   parseRuntimeConfig,
   migrateEmbedded,
+  measureResources,
+  keyMatchesCanary,
   isolateHandler,
   isModuleId,
+  encryptBundle,
   emptyHealth,
+  diskFloorGb,
+  decryptBundle,
+  decidePreflight,
   createSupervisor,
   createMemoryModule,
   createMemoryMigrationRunner,
@@ -693,10 +973,13 @@ export {
   applyUpgrade,
   actionFor,
   UPGRADE_STEPS,
+  UNDERSIZED_OVERRIDE,
   STATUS_PLANES,
   SECRET_KEYS,
   REQUIRED_KEYS,
+  REMOVABLE,
   PUBLISHER_PROFILE,
+  PRESERVED,
   OPTIONAL_KEYS,
   NODE_MODES,
   NETWORKS,
@@ -710,8 +993,9 @@ export {
   ISOLATION_FAULTS,
   FLOORS,
   DEFAULT_PROFILE,
-  BACKUP_PARTS
+  BACKUP_PARTS,
+  BACKUP_MANIFEST_VERSION
 };
 
-//# debugId=0C264B17247A3CFD64756E2164756E21
+//# debugId=57C29D3188B4875364756E2164756E21
 //# sourceMappingURL=index.js.map