@le-space/core 0.1.0

package/index.js

@@ -0,0 +1,1636 @@
+// src/constants.ts
+var DEFAULT_ALEPH_CHANNEL = "TEST";
+
+// src/manifests.ts
+var ITEM_HASH_RE = /^[a-fA-F0-9]{64}$/;
+var DEFAULT_ALEPH_API_HOST = "https://api2.aleph.im";
+var DEFAULT_IPFS_GATEWAY_BASE_URL = "https://ipfs.aleph.cloud/ipfs/";
+function isValidDateString(value) {
+  return value.trim().length > 0 && !Number.isNaN(new Date(value).getTime());
+}
+function validateRootfsManifest(manifest) {
+  const errors = [];
+  if (!manifest) {
+    return { manifest, valid: false, errors: ["Rootfs manifest is missing."] };
+  }
+  if (!manifest.version || !manifest.version.trim()) {
+    errors.push("Rootfs manifest version is missing.");
+  }
+  if (manifest.rootfsInstallStrategy != null && manifest.rootfsInstallStrategy !== "thin" && manifest.rootfsInstallStrategy !== "prebaked") {
+    errors.push('Rootfs install strategy must be "thin" or "prebaked" when provided.');
+  }
+  if (manifest.requiresBootstrapNetwork != null && typeof manifest.requiresBootstrapNetwork !== "boolean") {
+    errors.push("Rootfs bootstrap network flag must be a boolean when provided.");
+  }
+  if (manifest.bootstrapSummary != null && (typeof manifest.bootstrapSummary !== "string" || !manifest.bootstrapSummary.trim())) {
+    errors.push("Rootfs bootstrap summary must be non-empty when provided.");
+  }
+  if (manifest.requiredPortForwards != null) {
+    if (!Array.isArray(manifest.requiredPortForwards)) {
+      errors.push("Rootfs required port forwards must be an array when provided.");
+    } else {
+      manifest.requiredPortForwards.forEach((entry, index) => {
+        if (!entry || typeof entry !== "object") {
+          errors.push(`Rootfs required port forward #${index + 1} must be an object.`);
+          return;
+        }
+        if (!Number.isInteger(entry.port) || entry.port < 1 || entry.port > 65535) {
+          errors.push(`Rootfs required port forward #${index + 1} must use a TCP/UDP port between 1 and 65535.`);
+        }
+        if (entry.tcp !== true && entry.udp !== true) {
+          errors.push(`Rootfs required port forward #${index + 1} must enable TCP or UDP.`);
+        }
+        if (entry.purpose != null && (typeof entry.purpose !== "string" || !entry.purpose.trim())) {
+          errors.push(`Rootfs required port forward #${index + 1} purpose must be non-empty when provided.`);
+        }
+      });
+    }
+  }
+  if (manifest.rootfsItemHash != null && !ITEM_HASH_RE.test(manifest.rootfsItemHash)) {
+    errors.push("Rootfs ItemHash must be a 64 character hex value when provided.");
+  }
+  if (manifest.rootfsCid != null && (typeof manifest.rootfsCid !== "string" || !manifest.rootfsCid.trim())) {
+    errors.push("Rootfs CID must be a non-empty string when provided.");
+  }
+  if (!Number.isInteger(manifest.rootfsSizeMiB) || manifest.rootfsSizeMiB <= 0) {
+    errors.push("Rootfs size must be a positive MiB integer.");
+  }
+  if (manifest.rootfsSourceSizeBytes != null && (!Number.isInteger(manifest.rootfsSourceSizeBytes) || manifest.rootfsSourceSizeBytes <= 0)) {
+    errors.push("Rootfs source size must be a positive byte integer when provided.");
+  }
+  if (!isValidDateString(manifest.createdAt)) {
+    errors.push("Rootfs creation date is missing or invalid.");
+  }
+  return { manifest, valid: errors.length === 0, errors };
+}
+function normalizeStatus(status) {
+  if (typeof status !== "string") return "unknown";
+  const normalized = status.toLowerCase();
+  if (normalized === "processed" || normalized === "pending" || normalized === "rejected") {
+    return normalized;
+  }
+  return "unknown";
+}
+function parseCidFromPayload(payload) {
+  const firstMessage = Array.isArray(payload.messages) && payload.messages[0] && typeof payload.messages[0] === "object" ? payload.messages[0] : null;
+  const directContent = firstMessage?.content && typeof firstMessage.content === "object" ? firstMessage.content : null;
+  if (typeof directContent?.item_hash === "string") {
+    return directContent.item_hash;
+  }
+  if (typeof firstMessage?.item_content === "string") {
+    try {
+      const itemContent = JSON.parse(firstMessage.item_content);
+      if (typeof itemContent.item_hash === "string") {
+        return itemContent.item_hash;
+      }
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+function parseRejectionReason(payload) {
+  const errorCode = typeof payload.error_code === "number" ? payload.error_code : null;
+  const details = payload.details && typeof payload.details === "object" ? payload.details : null;
+  const rawErrors = Array.isArray(details?.errors) ? details.errors : [];
+  const firstError = rawErrors[0] && typeof rawErrors[0] === "object" ? rawErrors[0] : null;
+  if (firstError) {
+    const accountBalance = Number(firstError.account_balance);
+    const requiredBalance = Number(firstError.required_balance);
+    if (Number.isFinite(accountBalance) && Number.isFinite(requiredBalance)) {
+      const shortfall = requiredBalance - accountBalance;
+      return {
+        rejectionErrorCode: errorCode,
+        rejectionReason: shortfall > 0 ? `Rejected by Aleph for insufficient hold balance: ${accountBalance.toFixed(3)} available, ${requiredBalance.toFixed(3)} required, ${shortfall.toFixed(3)} short.` : `Rejected by Aleph for insufficient hold balance: ${accountBalance.toFixed(3)} available, ${requiredBalance.toFixed(3)} required.`
+      };
+    }
+  }
+  return {
+    rejectionErrorCode: errorCode,
+    rejectionReason: errorCode != null ? `Rejected by Aleph (error code ${errorCode}).` : null
+  };
+}
+async function verifyRootfsExists(itemHash, options) {
+  if (!ITEM_HASH_RE.test(itemHash)) return false;
+  const apiHost = options.apiHost ?? DEFAULT_ALEPH_API_HOST;
+  const response = await options.fetch(`${apiHost}/api/v0/messages/${itemHash}`, {
+    method: "GET",
+    cache: "no-cache"
+  });
+  if (response.status === 404) return false;
+  if (!response.ok) throw new Error(`Rootfs lookup failed: ${response.status}`);
+  const payload = await response.json();
+  const firstMessage = Array.isArray(payload.messages) ? payload.messages[0] : void 0;
+  const type = String(payload.type || payload.message?.type || firstMessage?.type || "").toUpperCase();
+  return type === "STORE";
+}
+async function probeRootfsGateway(cid, options) {
+  const gatewayUrl = new URL(cid, options.gatewayBaseUrl ?? DEFAULT_IPFS_GATEWAY_BASE_URL).toString();
+  try {
+    const response = await options.fetch(gatewayUrl, { method: "HEAD", cache: "no-store" });
+    return {
+      gatewayUrl,
+      gatewayStatus: response.ok ? "reachable" : "error",
+      gatewayError: response.ok ? null : `Gateway responded with ${response.status}.`
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      gatewayUrl,
+      gatewayStatus: message.includes("timed out") ? "timeout" : "unavailable",
+      gatewayError: message
+    };
+  }
+}
+async function resolveRootfsReference(itemHash, options) {
+  if (!ITEM_HASH_RE.test(itemHash)) return null;
+  const apiHost = options.apiHost ?? DEFAULT_ALEPH_API_HOST;
+  const response = await options.fetch(`${apiHost}/api/v0/messages/${itemHash}`, {
+    method: "GET",
+    cache: "no-cache"
+  });
+  if (response.status === 404) return null;
+  if (!response.ok) throw new Error(`Rootfs lookup failed: ${response.status}`);
+  const payload = await response.json();
+  const firstMessage = Array.isArray(payload.messages) && payload.messages[0] && typeof payload.messages[0] === "object" ? payload.messages[0] : null;
+  const messageObject = payload.message && typeof payload.message === "object" ? payload.message : null;
+  const cid = parseCidFromPayload(payload);
+  const rejection = normalizeStatus(payload.status) === "rejected" ? parseRejectionReason(payload) : { rejectionErrorCode: null, rejectionReason: null };
+  const gateway = cid ? await probeRootfsGateway(cid, {
+    gatewayBaseUrl: options.gatewayBaseUrl,
+    fetch: options.fetch
+  }) : { gatewayUrl: null, gatewayStatus: "unknown", gatewayError: null };
+  return {
+    itemHash,
+    messageStatus: normalizeStatus(payload.status),
+    messageType: String(payload.type || messageObject?.type || firstMessage?.type || "").toUpperCase() || null,
+    cid,
+    receptionTime: typeof payload.reception_time === "string" ? payload.reception_time : null,
+    rejectionErrorCode: rejection.rejectionErrorCode,
+    rejectionReason: rejection.rejectionReason,
+    gatewayUrl: gateway.gatewayUrl,
+    gatewayStatus: gateway.gatewayStatus,
+    gatewayError: gateway.gatewayError
+  };
+}
+
+// src/crns.ts
+var DEFAULT_CRN_LIST_URL = "https://crns-list.aleph.sh/crns.json";
+var DEFAULT_COUNTRY_LOOKUP_BASE_URL = "https://api.country.is";
+var DEFAULT_DNS_RESOLVE_URL = "https://dns.google/resolve";
+function asString(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function normalizeCountryCode(value) {
+  const normalized = asString(value)?.toUpperCase() ?? null;
+  return normalized && /^[A-Z]{2}$/.test(normalized) ? normalized : null;
+}
+function lookupHost(address) {
+  try {
+    return new URL(address ?? "").hostname.trim().toLowerCase();
+  } catch {
+    return String(address ?? "").trim().toLowerCase().replace(/^https?:\/\//, "").replace(/:\d+$/, "");
+  }
+}
+function isIpAddress(host) {
+  return /^\d{1,3}(?:\.\d{1,3}){3}$/.test(host) || host.includes(":");
+}
+function countryNameFromCode(value) {
+  if (!value) return null;
+  try {
+    const displayNames = new Intl.DisplayNames(["en"], { type: "region" });
+    return displayNames.of(value) ?? value;
+  } catch {
+    return value;
+  }
+}
+function compatibleCrns(crns, excludedHashes = []) {
+  const excluded = new Set(excludedHashes.filter(Boolean));
+  return [...crns].filter((crn) => {
+    if (!crn?.hash || excluded.has(crn.hash)) return false;
+    if (crn.qemu_support === false) return false;
+    if (crn.system_usage?.active === false) return false;
+    return true;
+  });
+}
+function scoreSortedCrns(crns) {
+  return [...crns].sort((left, right) => {
+    const rightScore = typeof right.score === "number" ? right.score : Number(right.score ?? Number.NEGATIVE_INFINITY);
+    const leftScore = typeof left.score === "number" ? left.score : Number(left.score ?? Number.NEGATIVE_INFINITY);
+    if (rightScore !== leftScore) return rightScore - leftScore;
+    const leftName = (left.name || left.address || left.hash).toLowerCase();
+    const rightName = (right.name || right.address || right.hash).toLowerCase();
+    return leftName.localeCompare(rightName);
+  });
+}
+async function resolveHostIp(host, options) {
+  if (!host) return null;
+  if (isIpAddress(host)) return host;
+  for (const type of ["A", "AAAA"]) {
+    const url = new URL(options.dnsResolveUrl ?? DEFAULT_DNS_RESOLVE_URL);
+    url.searchParams.set("name", host);
+    url.searchParams.set("type", type);
+    url.searchParams.set("edns_client_subnet", "0.0.0.0/0");
+    const response = await options.fetch(url.toString(), {
+      cache: "no-cache"
+    });
+    if (!response.ok) continue;
+    const payload = await response.json();
+    const record = Array.isArray(payload?.Answer) ? payload.Answer.find((entry) => typeof entry?.data === "string" && entry.data.trim()) : null;
+    if (typeof record?.data === "string" && record.data.trim()) {
+      return record.data.trim();
+    }
+  }
+  return null;
+}
+async function lookupIpLocation(ip, options) {
+  const url = new URL(`${options.countryLookupBaseUrl ?? DEFAULT_COUNTRY_LOOKUP_BASE_URL}/${encodeURIComponent(ip)}`);
+  url.searchParams.set("fields", "city,subdivision");
+  const response = await options.fetch(url.toString(), {
+    cache: "no-cache"
+  });
+  if (!response.ok) {
+    return {
+      resolved_ip: ip,
+      city: null,
+      region: null,
+      country: null,
+      country_code: null,
+      geo_source: null
+    };
+  }
+  const payload = await response.json();
+  const countryCode = normalizeCountryCode(payload?.country);
+  return {
+    resolved_ip: asString(payload?.ip) ?? ip,
+    city: asString(payload?.city),
+    region: asString(payload?.subdivision),
+    country: countryNameFromCode(countryCode),
+    country_code: countryCode,
+    geo_source: "country.is"
+  };
+}
+async function fetchCrns(options) {
+  const requestUrl = new URL(options.url ?? DEFAULT_CRN_LIST_URL);
+  requestUrl.searchParams.set("filter_inactive", "true");
+  const response = await options.fetch(requestUrl.toString(), {
+    cache: "no-cache"
+  });
+  if (!response.ok) {
+    throw new Error(`CRN list request failed: ${response.status}`);
+  }
+  const payload = await response.json();
+  return Array.isArray(payload?.crns) ? payload.crns : [];
+}
+async function enrichCrnsWithGeo(crns, options) {
+  return Promise.all(
+    crns.map(async (crn) => {
+      if (crn.city || crn.region || crn.country || crn.country_code) {
+        return crn;
+      }
+      try {
+        const host = lookupHost(crn.address);
+        const ip = await resolveHostIp(host, {
+          fetch: options.fetch,
+          dnsResolveUrl: options.dnsResolveUrl
+        });
+        if (!ip) return crn;
+        return {
+          ...crn,
+          ...await lookupIpLocation(ip, {
+            fetch: options.fetch,
+            countryLookupBaseUrl: options.countryLookupBaseUrl
+          })
+        };
+      } catch {
+        return crn;
+      }
+    })
+  );
+}
+async function listGeocodedCrns(options) {
+  const sortedCrns = scoreSortedCrns(compatibleCrns(await fetchCrns({
+    url: options.url,
+    fetch: options.fetch
+  })));
+  const geocodedCrns = await enrichCrnsWithGeo(
+    sortedCrns.slice(0, Math.max(1, Number(options.limit) || 30)),
+    options
+  );
+  return geocodedCrns.filter((crn) => Boolean(crn.city || crn.region || crn.country || crn.country_code)).sort((left, right) => {
+    const leftLabel = `${left.country ?? ""}/${left.region ?? ""}/${left.city ?? ""}/${left.name ?? left.hash}`.toLowerCase();
+    const rightLabel = `${right.country ?? ""}/${right.region ?? ""}/${right.city ?? ""}/${right.name ?? right.hash}`.toLowerCase();
+    return leftLabel.localeCompare(rightLabel);
+  });
+}
+async function rankCandidateCrns(crns, options) {
+  const preferredCountryCode = normalizeCountryCode(options.preferredCountryCode);
+  const geoLimit = Math.max(1, Number(options.geoLimit) || 30);
+  const sortedCrns = scoreSortedCrns(compatibleCrns(crns, options.excludedHashes));
+  if (!preferredCountryCode || sortedCrns.length === 0) {
+    return sortedCrns;
+  }
+  const enrichedTopCrns = await enrichCrnsWithGeo(sortedCrns.slice(0, geoLimit), options);
+  const mergedByHash = new Map(enrichedTopCrns.map((crn) => [crn.hash, crn]));
+  const mergedCrns = sortedCrns.map((crn) => mergedByHash.get(crn.hash) ?? crn);
+  const originalIndex = new Map(mergedCrns.map((crn, index) => [crn.hash, index]));
+  return [...mergedCrns].sort((left, right) => {
+    const leftPreferred = normalizeCountryCode(left.country_code) === preferredCountryCode ? 1 : 0;
+    const rightPreferred = normalizeCountryCode(right.country_code) === preferredCountryCode ? 1 : 0;
+    if (leftPreferred !== rightPreferred) {
+      return rightPreferred - leftPreferred;
+    }
+    return (originalIndex.get(left.hash) ?? Number.MAX_SAFE_INTEGER) - (originalIndex.get(right.hash) ?? Number.MAX_SAFE_INTEGER);
+  });
+}
+async function selectPreferredCrn(crns, options) {
+  return (await rankCandidateCrns(crns, options))[0] ?? null;
+}
+
+// src/port-forwarding.ts
+var DEFAULT_INSTANCE_PORT_FORWARDS = [
+  { port: 22, tcp: true, udp: false, purpose: "SSH" }
+];
+function normalizeRequestedPort(entry) {
+  return {
+    port: entry.port,
+    tcp: entry.tcp === true,
+    udp: entry.udp === true,
+    purpose: entry.purpose?.trim() || void 0
+  };
+}
+function normalizePortFlags(value) {
+  if (!value || typeof value !== "object") return null;
+  const candidate = value;
+  return {
+    tcp: candidate.tcp === true,
+    udp: candidate.udp === true
+  };
+}
+function normalizeExistingPortForwardEntry(entry) {
+  if (!entry?.ports || typeof entry.ports !== "object") return {};
+  return Object.fromEntries(
+    Object.entries(entry.ports).map(([port, flags]) => [port, normalizePortFlags(flags)]).filter((item) => item[1] != null)
+  );
+}
+function requestedPortFlags(portForwards) {
+  return Object.fromEntries(
+    portForwards.map((entry) => [
+      String(entry.port),
+      {
+        tcp: entry.tcp === true,
+        udp: entry.udp === true
+      }
+    ])
+  );
+}
+function mergePortFlagMaps(existing, requested) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const [port, flags] of Object.entries(existing)) {
+    merged.set(port, {
+      tcp: flags.tcp === true,
+      udp: flags.udp === true
+    });
+  }
+  for (const [port, flags] of Object.entries(requested)) {
+    const current = merged.get(port);
+    merged.set(port, {
+      tcp: current?.tcp === true || flags.tcp === true,
+      udp: current?.udp === true || flags.udp === true
+    });
+  }
+  return Object.fromEntries([...merged.entries()].sort((left, right) => Number(left[0]) - Number(right[0])));
+}
+function mergeRequiredPortForwards(...groups) {
+  const merged = /* @__PURE__ */ new Map();
+  for (const group of groups) {
+    for (const entry of group ?? []) {
+      const normalized = normalizeRequestedPort(entry);
+      const current = merged.get(normalized.port);
+      merged.set(normalized.port, {
+        port: normalized.port,
+        tcp: current?.tcp === true || normalized.tcp === true,
+        udp: current?.udp === true || normalized.udp === true,
+        purpose: current?.purpose ?? normalized.purpose
+      });
+    }
+  }
+  return [...merged.values()].sort((left, right) => left.port - right.port);
+}
+function requiredInstancePortForwards(manifest) {
+  return mergeRequiredPortForwards(DEFAULT_INSTANCE_PORT_FORWARDS, manifest?.requiredPortForwards);
+}
+function portForwardLabel(entry) {
+  const protocols = [entry.tcp === true ? "TCP" : null, entry.udp === true ? "UDP" : null].filter((value) => Boolean(value)).join("/");
+  return `${entry.port}/${protocols}`;
+}
+async function fetchPortForwardAggregate(address, options) {
+  const requestUrl = new URL(`/api/v0/aggregates/${address}.json`, options.apiHost ?? DEFAULT_ALEPH_API_HOST);
+  requestUrl.searchParams.set("keys", "port-forwarding");
+  const response = await options.fetch(requestUrl.toString(), { cache: "no-cache" });
+  if (response.status === 404) return {};
+  if (!response.ok) {
+    throw new Error(`Port-forward aggregate request failed: ${response.status}`);
+  }
+  const payload = await response.json();
+  const aggregate = payload.data?.["port-forwarding"];
+  if (!aggregate || typeof aggregate !== "object" || Array.isArray(aggregate)) return {};
+  return aggregate;
+}
+
+// src/aleph-normalizers.ts
+function asString2(value) {
+  return typeof value === "string" && value.trim() ? value : null;
+}
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function normalizeMessageStatus(status) {
+  if (typeof status !== "string") return "unknown";
+  const normalized = status.toLowerCase();
+  if (normalized === "processed" || normalized === "pending" || normalized === "rejected") {
+    return normalized;
+  }
+  return "unknown";
+}
+function normalizeProxyUrl(value) {
+  const stringValue = asString2(value);
+  if (!stringValue) return null;
+  if (/^https?:\/\//i.test(stringValue)) return stringValue;
+  return `https://${stringValue}`;
+}
+function messageTypeFromEnvelope(payload) {
+  if (!payload) return null;
+  const type = payload.type ?? payload.message?.type ?? (Array.isArray(payload.messages) ? payload.messages[0]?.type : void 0);
+  return typeof type === "string" ? type.toUpperCase() : null;
+}
+function extractReferenceHashes(details) {
+  if (!details || typeof details !== "object" || !("errors" in details)) return [];
+  const errors = details.errors;
+  if (!Array.isArray(errors)) return [];
+  return errors.filter((value) => typeof value === "string");
+}
+function describeRejectedDeployment(payload, references, rootfsRef) {
+  const errorCode = typeof payload.error_code === "number" ? payload.error_code : null;
+  const pendingReferences = references.filter((reference) => reference.status === "pending");
+  const missingReferences = references.filter((reference) => reference.status === "missing");
+  const rootfsReference = references.find((reference) => reference.itemHash === rootfsRef);
+  if (rootfsReference?.status === "pending") {
+    return `Aleph rejected this deployment because the referenced rootfs STORE message ${rootfsReference.itemHash} is still pending and cannot yet be used by an instance. Wait for that STORE message to process, then deploy again.`;
+  }
+  if (pendingReferences.length > 0) {
+    return `Aleph rejected this deployment because referenced message(s) are still pending: ${pendingReferences.map((reference) => reference.itemHash).join(", ")}.`;
+  }
+  if (missingReferences.length > 0) {
+    return `Aleph rejected this deployment because referenced message(s) were not found on Aleph: ${missingReferences.map((reference) => reference.itemHash).join(", ")}.`;
+  }
+  const referencedHashes = extractReferenceHashes(payload.details);
+  if (referencedHashes.length > 0) {
+    return `Aleph rejected this deployment${errorCode ? ` (error ${errorCode})` : ""}. Referenced message(s): ${referencedHashes.join(", ")}.`;
+  }
+  return `Aleph rejected this deployment${errorCode ? ` (error ${errorCode})` : ""}.`;
+}
+function extractProxyUrl(item, networking) {
+  const networkingCandidates = [
+    networking?.proxy_url,
+    networking?.proxyUrl,
+    networking?.web_access_url,
+    networking?.webAccessUrl,
+    networking?.proxy_hostname,
+    networking?.proxyHostname,
+    networking?.domain,
+    networking?.hostname
+  ];
+  for (const candidate of networkingCandidates) {
+    const normalized = normalizeProxyUrl(candidate);
+    if (normalized) return normalized;
+  }
+  const webAccessCandidates = [item.web_access, item.webAccess];
+  for (const entry of webAccessCandidates) {
+    const normalized = normalizeProxyUrl(entry?.url) ?? normalizeProxyUrl(entry?.proxy_url) ?? normalizeProxyUrl(entry?.hostname) ?? normalizeProxyUrl(entry?.domain);
+    if (normalized) return normalized;
+  }
+  return null;
+}
+function normalizeExecution(item, crnUrl) {
+  const networking = item.networking ?? null;
+  const mappedPorts = networking && "mapped_ports" in networking && networking.mapped_ports && typeof networking.mapped_ports === "object" ? Object.fromEntries(
+    Object.entries(networking.mapped_ports).map(([port, mapping]) => [
+      port,
+      {
+        host: asNumber(mapping?.host) ?? void 0,
+        tcp: typeof mapping?.tcp === "boolean" ? mapping.tcp : void 0,
+        udp: typeof mapping?.udp === "boolean" ? mapping.udp : void 0
+      }
+    ])
+  ) : void 0;
+  if (networking && ("host_ipv4" in networking || "ipv6_ip" in networking || "ipv4_network" in networking)) {
+    const v2Item = item;
+    return {
+      crnUrl,
+      version: "v2",
+      running: typeof v2Item.running === "boolean" ? v2Item.running : void 0,
+      networking: {
+        ipv4_network: asString2(networking.ipv4_network),
+        host_ipv4: asString2(networking.host_ipv4),
+        ipv6_network: asString2(networking.ipv6_network),
+        ipv6_ip: asString2(networking.ipv6_ip),
+        ipv4_ip: asString2(networking.ipv4_ip),
+        proxy_url: extractProxyUrl(v2Item, networking),
+        mapped_ports: mappedPorts
+      },
+      status: v2Item.status ? {
+        defined_at: asString2(v2Item.status.defined_at),
+        preparing_at: asString2(v2Item.status.preparing_at),
+        prepared_at: asString2(v2Item.status.prepared_at),
+        starting_at: asString2(v2Item.status.starting_at),
+        started_at: asString2(v2Item.status.started_at),
+        stopping_at: asString2(v2Item.status.stopping_at),
+        stopped_at: asString2(v2Item.status.stopped_at)
+      } : null
+    };
+  }
+  return {
+    crnUrl,
+    version: "v1",
+    networking: {
+      ipv4: networking && "ipv4" in networking ? asString2(networking.ipv4) : null,
+      ipv6: networking && "ipv6" in networking ? asString2(networking.ipv6) : null
+    },
+    status: null
+  };
+}
+
+// src/deployment-inspection.ts
+function insufficientBalanceMessage(details) {
+  const firstError = details && Array.isArray(details.errors) && details.errors[0] && typeof details.errors[0] === "object" ? details.errors[0] : null;
+  const accountBalance = firstError?.account_balance;
+  const requiredBalance = firstError?.required_balance;
+  if (accountBalance != null && requiredBalance != null) {
+    return `insufficient Aleph balance: account has ${accountBalance}, required is ${requiredBalance}`;
+  }
+  return null;
+}
+async function fetchMessageEnvelope(itemHash, options) {
+  const response = await options.fetch(`${options.apiHost ?? DEFAULT_ALEPH_API_HOST}/api/v0/messages/${itemHash}`, {
+    cache: "no-cache"
+  });
+  if (response.status === 404) return null;
+  if (!response.ok) throw new Error(`Message lookup failed: ${response.status}`);
+  return await response.json();
+}
+async function inspectMessageResult(itemHash, options) {
+  const label = options.label ?? "Message";
+  const payload = await fetchMessageEnvelope(itemHash, options);
+  if (!payload) {
+    return {
+      status: "unknown",
+      errorCode: null,
+      details: null,
+      rejectionReason: `${label} ${itemHash} was not found on Aleph.`
+    };
+  }
+  const status = normalizeMessageStatus(payload.status);
+  const errorCode = typeof payload.error_code === "number" ? payload.error_code : null;
+  const details = payload.details && typeof payload.details === "object" ? payload.details : null;
+  let rejectionReason = null;
+  if (status === "rejected") {
+    const balanceMessage = errorCode === 5 ? insufficientBalanceMessage(details) : null;
+    rejectionReason = balanceMessage ? `${label} ${itemHash} was rejected by Aleph due to ${balanceMessage}.` : `${label} ${itemHash} was rejected by Aleph${errorCode ? ` (error ${errorCode})` : ""}.`;
+  }
+  return {
+    status,
+    errorCode,
+    details,
+    rejectionReason
+  };
+}
+async function fetchReference(itemHash, options) {
+  const payload = await fetchMessageEnvelope(itemHash, options);
+  if (!payload) {
+    return {
+      itemHash,
+      status: "missing",
+      type: null
+    };
+  }
+  return {
+    itemHash,
+    status: normalizeMessageStatus(payload.status),
+    type: messageTypeFromEnvelope(payload)
+  };
+}
+async function inspectDeploymentResult(itemHash, options) {
+  const payload = await fetchMessageEnvelope(itemHash, options);
+  if (!payload) {
+    return {
+      status: "unknown",
+      errorCode: null,
+      details: null,
+      rejectionReason: `Deployment message ${itemHash} was not found on Aleph.`,
+      references: []
+    };
+  }
+  const relatedHashes = new Set(options.rootfsRef ? [options.rootfsRef] : []);
+  for (const referenceHash of extractReferenceHashes(payload.details)) {
+    relatedHashes.add(referenceHash);
+  }
+  const references = await Promise.all(
+    Array.from(relatedHashes).map((hash) => fetchReference(hash, options))
+  );
+  const status = normalizeMessageStatus(payload.status);
+  const errorCode = typeof payload.error_code === "number" ? payload.error_code : null;
+  const details = payload.details && typeof payload.details === "object" ? payload.details : null;
+  return {
+    status,
+    errorCode,
+    details,
+    rejectionReason: status === "rejected" ? describeRejectedDeployment(payload, references, options.rootfsRef) : null,
+    references
+  };
+}
+async function waitForDeploymentResult(itemHash, options) {
+  const attempts = Math.max(1, Number(options.attempts ?? 15));
+  const delayMs = Math.max(0, Number(options.delayMs ?? 2e3));
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let lastResult = await inspectDeploymentResult(itemHash, options);
+  for (let attempt = 1; attempt < attempts; attempt += 1) {
+    if (lastResult.status === "processed" || lastResult.status === "rejected") {
+      return lastResult;
+    }
+    await sleep(delayMs);
+    lastResult = await inspectDeploymentResult(itemHash, options);
+  }
+  return lastResult;
+}
+
+// src/broadcast.ts
+function signaturePayload(message) {
+  return [message.chain, message.sender, message.type, message.item_hash].join("\n");
+}
+async function signAlephMessage(unsignedMessage, signer) {
+  const signature = await signer(unsignedMessage.sender, signaturePayload(unsignedMessage));
+  return {
+    ...unsignedMessage,
+    signature: signature.startsWith("0x") ? signature : `0x${signature}`
+  };
+}
+function normalizeBroadcastStatus(httpStatus, responseStatus) {
+  if (httpStatus === 202) return "pending";
+  return normalizeMessageStatus(responseStatus);
+}
+function isInvalidMessageFormatResponse(response, payload) {
+  if (response.status !== 422) return false;
+  const details = payload?.details;
+  if (typeof details === "string" && details.includes("InvalidMessageFormat")) return true;
+  if (details && typeof details === "object") {
+    const detailMessage = details.message;
+    if (typeof detailMessage === "string" && detailMessage.includes("InvalidMessageFormat")) return true;
+  }
+  return false;
+}
+function isRetryableBroadcastFailure(response, payload) {
+  if (response.status >= 500) return true;
+  const publicationStatus = payload?.publication_status?.status;
+  if (typeof publicationStatus === "string" && publicationStatus.toLowerCase() === "error") {
+    return true;
+  }
+  return false;
+}
+async function postBroadcastPayload(body, options) {
+  const rawResponse = await options.fetch(`${options.apiHost ?? DEFAULT_ALEPH_API_HOST}/api/v0/messages`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body)
+  });
+  const response = await rawResponse.json().catch(() => ({}));
+  return {
+    response,
+    httpStatus: rawResponse.status
+  };
+}
+async function broadcastAlephMessage(message, options) {
+  const attempts = [
+    { sync: options.sync ?? false, message },
+    { ...message, sync: options.sync ?? false },
+    { ...message }
+  ];
+  for (let index = 0; index < attempts.length; index += 1) {
+    const result = await postBroadcastPayload(attempts[index], {
+      apiHost: options.apiHost,
+      fetch: options.fetch
+    });
+    if (result.httpStatus === 202 || normalizeBroadcastStatus(result.httpStatus, result.response?.message_status) !== "unknown" || result.httpStatus >= 200 && result.httpStatus < 300) {
+      return result;
+    }
+    const canRetry = index < attempts.length - 1 && (isInvalidMessageFormatResponse({ status: result.httpStatus }, result.response) || isRetryableBroadcastFailure({ status: result.httpStatus }, result.response));
+    if (!canRetry) {
+      throw new Error(`Broadcast failed: ${result.httpStatus} ${JSON.stringify(result.response ?? {})}`);
+    }
+  }
+  throw new Error("Broadcast failed: no compatible request format was accepted");
+}
+
+// src/forget.ts
+function asOptionalReason(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+async function createUnsignedForgetMessage(args) {
+  const content = {
+    address: args.sender,
+    time: args.now ?? Date.now() / 1e3,
+    hashes: [...new Set((args.hashes ?? []).filter(Boolean))],
+    aggregates: [...new Set((args.aggregates ?? []).filter(Boolean))],
+    reason: asOptionalReason(args.reason)
+  };
+  if (content.hashes.length === 0 && content.aggregates.length === 0) {
+    throw new Error("FORGET message requires at least one hash or aggregate key.");
+  }
+  const itemContent = JSON.stringify(content);
+  const itemHash = await args.hasher(itemContent);
+  return {
+    sender: args.sender,
+    chain: "ETH",
+    type: "FORGET",
+    item_hash: itemHash,
+    item_type: "inline",
+    item_content: itemContent,
+    time: args.now ?? Date.now() / 1e3,
+    channel: args.channel ?? DEFAULT_ALEPH_CHANNEL
+  };
+}
+async function forgetAlephMessages(args) {
+  const unsignedMessage = await createUnsignedForgetMessage({
+    sender: args.sender,
+    hashes: args.hashes,
+    aggregates: args.aggregates,
+    reason: args.reason,
+    hasher: args.hasher,
+    channel: args.channel,
+    now: args.now
+  });
+  const message = await signAlephMessage(unsignedMessage, args.signer);
+  const { response, httpStatus } = await broadcastAlephMessage(message, {
+    apiHost: args.apiHost,
+    sync: args.sync,
+    fetch: args.fetch
+  });
+  return {
+    sender: args.sender,
+    itemHash: message.item_hash,
+    response,
+    httpStatus,
+    status: normalizeBroadcastStatus(httpStatus, response?.message_status)
+  };
+}
+async function cleanupFailedDeployment(args) {
+  try {
+    return await forgetAlephMessages({
+      sender: args.sender,
+      hashes: [args.instanceItemHash],
+      reason: args.reason ?? "Discard failed deployment attempt",
+      signer: args.signer,
+      hasher: args.hasher,
+      fetch: args.fetch,
+      channel: args.channel,
+      apiHost: args.apiHost
+    });
+  } catch (error) {
+    return {
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+// src/retention.ts
+var SUCCESSFUL_DEPLOYMENTS_AGGREGATE_KEY = "uc-go-peer-successful-deployments";
+function asString3(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function normalizeRetentionRecord(record) {
+  if (!record || typeof record !== "object" || Array.isArray(record)) return null;
+  const candidate = record;
+  const instanceItemHash = asString3(candidate.instance_item_hash);
+  if (!instanceItemHash) return null;
+  return {
+    instance_item_hash: instanceItemHash,
+    rootfs_item_hash: asString3(candidate.rootfs_item_hash) ?? "",
+    site_item_hash: asString3(candidate.site_item_hash) ?? "",
+    rootfs_cid: asString3(candidate.rootfs_cid) ?? "",
+    site_url: asString3(candidate.site_url) ?? "",
+    relay_peer_id: asString3(candidate.relay_peer_id) ?? "",
+    rootfs_version: asString3(candidate.rootfs_version) ?? "",
+    deployed_at: asString3(candidate.deployed_at) ?? (/* @__PURE__ */ new Date()).toISOString(),
+    vm_name: asString3(candidate.vm_name) ?? ""
+  };
+}
+function normalizeRetentionLedger(value) {
+  if (Array.isArray(value)) {
+    return value.map(normalizeRetentionRecord).filter((entry) => entry != null);
+  }
+  if (value && typeof value === "object" && Array.isArray(value.deployments)) {
+    return value.deployments.map(normalizeRetentionRecord).filter((entry) => entry != null);
+  }
+  return [];
+}
+function retentionRecordId(record) {
+  return [record.instance_item_hash, record.rootfs_item_hash, record.site_item_hash].join(":");
+}
+function hashesFromRetentionRecord(record) {
+  return [record.instance_item_hash, record.rootfs_item_hash, record.site_item_hash].filter(Boolean);
+}
+async function fetchAggregateKey(args) {
+  const requestUrl = new URL(`/api/v0/aggregates/${args.address}.json`, args.apiHost ?? "https://api2.aleph.im");
+  requestUrl.searchParams.set("keys", args.key);
+  const response = await args.fetch(requestUrl.toString(), { cache: "no-cache" });
+  if (response.status === 404) return {};
+  if (!response.ok) {
+    throw new Error(`Aggregate request failed for key ${args.key}: ${response.status}`);
+  }
+  const payload = await response.json();
+  return payload?.data?.[args.key] ?? {};
+}
+async function createUnsignedAggregateMessage(args) {
+  const itemContent = JSON.stringify(args.content);
+  const itemHash = await args.hasher(itemContent);
+  return {
+    sender: args.sender,
+    chain: "ETH",
+    type: "AGGREGATE",
+    item_hash: itemHash,
+    item_type: "inline",
+    item_content: itemContent,
+    time: args.now ?? Date.now() / 1e3,
+    channel: args.channel ?? DEFAULT_ALEPH_CHANNEL
+  };
+}
+async function publishAggregateKey(args) {
+  const aggregateContent = {
+    address: args.sender,
+    key: args.key,
+    content: args.content,
+    time: args.now ?? Date.now() / 1e3
+  };
+  const unsignedMessage = await createUnsignedAggregateMessage({
+    sender: args.sender,
+    content: aggregateContent,
+    hasher: args.hasher,
+    channel: args.channel,
+    now: args.now
+  });
+  const message = await signAlephMessage(unsignedMessage, args.signer);
+  const { response, httpStatus } = await broadcastAlephMessage(message, {
+    apiHost: args.apiHost,
+    sync: true,
+    fetch: args.fetch
+  });
+  return {
+    itemHash: message.item_hash,
+    status: normalizeBroadcastStatus(httpStatus, response?.message_status),
+    response,
+    httpStatus
+  };
+}
+async function retainSuccessfulDeployments(args) {
+  const keepCount = Math.max(0, Number.parseInt(String(args.keepCount ?? 0), 10) || 0);
+  const aggregateKey = asString3(args.aggregateKey) ?? SUCCESSFUL_DEPLOYMENTS_AGGREGATE_KEY;
+  const currentRecord = normalizeRetentionRecord(args.currentRecord);
+  if (!currentRecord) {
+    throw new Error("retainSuccessfulDeployments requires a current deployment record with instance_item_hash.");
+  }
+  const existingValue = await fetchAggregateKey({
+    address: args.sender,
+    key: aggregateKey,
+    fetch: args.fetch,
+    apiHost: args.apiHost
+  });
+  const existingRecords = normalizeRetentionLedger(existingValue);
+  const mergedRecords = [currentRecord, ...existingRecords];
+  const uniqueRecords = [];
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const record of mergedRecords) {
+    const id = retentionRecordId(record);
+    if (seenIds.has(id)) continue;
+    seenIds.add(id);
+    uniqueRecords.push(record);
+  }
+  const retainedRecords = keepCount > 0 ? uniqueRecords.slice(0, keepCount) : [];
+  const prunedRecords = keepCount > 0 ? uniqueRecords.slice(keepCount) : uniqueRecords;
+  const retainedHashes = new Set(retainedRecords.flatMap(hashesFromRetentionRecord));
+  const extraForgetHashes = [...new Set((args.extraForgetHashes ?? []).filter(Boolean))];
+  const forgetHashes = [.../* @__PURE__ */ new Set([...prunedRecords.flatMap(hashesFromRetentionRecord), ...extraForgetHashes])].filter(
+    (hash) => !retainedHashes.has(hash)
+  );
+  const aggregateContent = {
+    keep: keepCount,
+    updated_at: (/* @__PURE__ */ new Date()).toISOString(),
+    deployments: retainedRecords
+  };
+  const aggregatePublication = await publishAggregateKey({
+    sender: args.sender,
+    key: aggregateKey,
+    content: aggregateContent,
+    signer: args.signer,
+    hasher: args.hasher,
+    fetch: args.fetch,
+    channel: args.channel,
+    apiHost: args.apiHost,
+    now: args.now
+  });
+  let forgetResult = null;
+  if (forgetHashes.length > 0) {
+    forgetResult = await forgetAlephMessages({
+      sender: args.sender,
+      hashes: forgetHashes,
+      reason: args.reason ?? `Prune successful deployments beyond retention limit ${keepCount}`,
+      signer: args.signer,
+      hasher: args.hasher,
+      fetch: args.fetch,
+      channel: args.channel,
+      apiHost: args.apiHost,
+      now: args.now
+    });
+  }
+  return {
+    sender: args.sender,
+    aggregateKey,
+    keepCount,
+    aggregatePublication,
+    retainedRecords,
+    prunedRecords,
+    forgetHashes,
+    forgetResult
+  };
+}
+
+// src/aggregate-publication.ts
+function createPortForwardAggregateContent(args) {
+  const existingPorts = normalizeExistingPortForwardEntry(args.existingAggregate?.[args.instanceItemHash]);
+  const mergedPorts = mergePortFlagMaps(existingPorts, requestedPortFlags(args.requestedPorts));
+  return {
+    address: args.sender,
+    key: "port-forwarding",
+    content: {
+      [args.instanceItemHash]: {
+        ports: mergedPorts
+      }
+    },
+    time: args.now ?? Date.now() / 1e3
+  };
+}
+async function createUnsignedAggregateMessage2(args) {
+  const itemContent = JSON.stringify(args.content);
+  const itemHash = await args.hasher(itemContent);
+  return {
+    sender: args.sender,
+    chain: "ETH",
+    type: "AGGREGATE",
+    item_hash: itemHash,
+    item_type: "inline",
+    item_content: itemContent,
+    time: args.now ?? Date.now() / 1e3,
+    channel: args.channel ?? DEFAULT_ALEPH_CHANNEL
+  };
+}
+async function ensureInstancePortForwards(args) {
+  const requestedPorts = requiredInstancePortForwards(args.manifest);
+  const aggregate = await fetchPortForwardAggregate(args.sender, {
+    apiHost: args.apiHost,
+    fetch: args.fetch
+  });
+  const content = createPortForwardAggregateContent({
+    sender: args.sender,
+    instanceItemHash: args.instanceItemHash,
+    requestedPorts,
+    existingAggregate: aggregate
+  });
+  const unsignedMessage = await createUnsignedAggregateMessage2({
+    sender: args.sender,
+    content,
+    hasher: args.hasher,
+    channel: args.channel
+  });
+  const message = await signAlephMessage(unsignedMessage, args.signer);
+  const { response, httpStatus } = await broadcastAlephMessage(message, {
+    apiHost: args.apiHost,
+    sync: args.sync,
+    fetch: args.fetch
+  });
+  const aggregateStatus = normalizeBroadcastStatus(httpStatus, response.message_status);
+  if (aggregateStatus === "rejected") {
+    throw new Error(`Port-forward aggregate was rejected by Aleph: ${JSON.stringify(response.details ?? response)}`);
+  }
+  return {
+    aggregateItemHash: message.item_hash,
+    aggregateStatus,
+    requestedPorts
+  };
+}
+
+// src/instance-deployment.ts
+var SSH_PUBLIC_KEY_PATTERN = /^(ssh-rsa|ssh-ed25519|ecdsa-sha2-nistp256|ecdsa-sha2-nistp384|ecdsa-sha2-nistp521|sk-ssh-ed25519@openssh\.com|sk-ecdsa-sha2-nistp256@openssh\.com)\s+[A-Za-z0-9+/]+={0,3}(?:\s+.+)?$/;
+function normalizeSshPublicKey(value) {
+  return value.split(/\r?\n/g).map((line) => line.trim()).filter(Boolean).join(" ").replace(/\s+/g, " ").trim();
+}
+function isValidSshPublicKey(value) {
+  return SSH_PUBLIC_KEY_PATTERN.test(normalizeSshPublicKey(value));
+}
+function createReleaseMetadata(name, rootfsVersion, deployer = "shared-aleph-tooling") {
+  return {
+    name,
+    rootfs_version: rootfsVersion,
+    deployer
+  };
+}
+function createInstanceContent(args) {
+  const sshKey = normalizeSshPublicKey(args.sshPublicKey);
+  if (!sshKey) {
+    throw new Error("An SSH public key is required.");
+  }
+  if (!isValidSshPublicKey(sshKey)) {
+    throw new Error("SSH public key must be a single valid .pub line.");
+  }
+  if (!args.rootfsItemHash || !/^[a-fA-F0-9]{64}$/.test(args.rootfsItemHash)) {
+    throw new Error("rootfsItemHash must be a 64-character Aleph item hash.");
+  }
+  return {
+    address: args.address,
+    time: args.now ?? Date.now() / 1e3,
+    allow_amend: false,
+    metadata: createReleaseMetadata(args.name.trim(), args.rootfsVersion ?? "custom-rootfs", args.deployer),
+    authorized_keys: [sshKey],
+    environment: {
+      internet: true,
+      aleph_api: true,
+      hypervisor: "qemu",
+      reproducible: false,
+      shared_cache: false
+    },
+    resources: {
+      vcpus: Number(args.vcpus),
+      memory: Number(args.memoryMiB),
+      seconds: Number(args.seconds ?? 30)
+    },
+    payment: {
+      type: "credit"
+    },
+    requirements: args.crnHash ? {
+      node: {
+        node_hash: args.crnHash
+      }
+    } : void 0,
+    volumes: [],
+    rootfs: {
+      parent: {
+        ref: args.rootfsItemHash,
+        use_latest: true
+      },
+      persistence: "host",
+      size_mib: Number(args.rootfsSizeMiB)
+    }
+  };
+}
+async function createUnsignedInstanceMessage(args) {
+  const itemContent = JSON.stringify(args.content);
+  const itemHash = await args.hasher(itemContent);
+  return {
+    sender: args.sender,
+    chain: "ETH",
+    type: "INSTANCE",
+    item_hash: itemHash,
+    item_type: "inline",
+    item_content: itemContent,
+    time: args.now ?? Date.now() / 1e3,
+    channel: args.channel ?? DEFAULT_ALEPH_CHANNEL
+  };
+}
+async function deployInstance(args) {
+  const unsignedMessage = await createUnsignedInstanceMessage({
+    sender: args.sender,
+    content: args.content,
+    hasher: args.hasher,
+    channel: args.channel,
+    now: args.now
+  });
+  const signature = await args.signer(unsignedMessage.sender, [unsignedMessage.chain, unsignedMessage.sender, unsignedMessage.type, unsignedMessage.item_hash].join("\n"));
+  const message = {
+    ...unsignedMessage,
+    signature: signature.startsWith("0x") ? signature : `0x${signature}`
+  };
+  const { response, httpStatus } = await broadcastAlephMessage(message, {
+    apiHost: args.apiHost,
+    sync: args.sync,
+    fetch: args.fetch
+  });
+  const status = httpStatus === 202 ? "pending" : typeof response.message_status === "string" ? response.message_status : "unknown";
+  return {
+    itemHash: message.item_hash,
+    httpStatus,
+    status,
+    message,
+    response,
+    rejectionReason: status === "rejected" ? String(response.details ?? "Aleph rejected this deployment.") : null
+  };
+}
+
+// src/runtime.ts
+var DEFAULT_SCHEDULER_ALLOCATION_URL = "https://scheduler.api.aleph.cloud/api/v0/allocation";
+var DEFAULT_TWO_N_SIX_HASH_URL = "https://api.2n6.me/api/hash";
+function asString4(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function asNumber2(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function findCrnByHash(crns, crnHash) {
+  return crns.find((crn) => crn.hash === crnHash) ?? null;
+}
+async function fetchSchedulerAllocation(itemHash, options) {
+  const response = await options.fetch(
+    `${options.schedulerAllocationUrl ?? DEFAULT_SCHEDULER_ALLOCATION_URL}/${itemHash}`,
+    { cache: "no-cache" }
+  );
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    throw new Error(`Scheduler allocation request failed: ${response.status}`);
+  }
+  const payload = await response.json();
+  const node = payload?.node;
+  return {
+    source: "scheduler",
+    crnHash: asString4(node?.node_id),
+    crnUrl: asString4(node?.url),
+    node: node ? {
+      node_id: asString4(node.node_id) ?? void 0,
+      url: asString4(node.url) ?? void 0,
+      ipv6: asString4(node.ipv6),
+      supports_ipv6: typeof node.supports_ipv6 === "boolean" ? node.supports_ipv6 : void 0
+    } : null,
+    vmIpv6: asString4(payload?.vm_ipv6),
+    period: payload?.period ? {
+      start_timestamp: asString4(payload.period.start_timestamp) ?? void 0,
+      duration_seconds: asNumber2(payload.period.duration_seconds) ?? void 0
+    } : null
+  };
+}
+async function fetch2n6WebAccessUrl(itemHash, options) {
+  const response = await options.fetch(
+    `${options.twoN6HashUrl ?? DEFAULT_TWO_N_SIX_HASH_URL}/${itemHash}`,
+    { cache: "no-cache" }
+  );
+  if (!response.ok) return null;
+  const payload = await response.json();
+  return {
+    url: normalizeProxyUrl(payload?.url ?? payload?.subdomain),
+    active: typeof payload?.active === "boolean" ? payload.active : null,
+    subdomain: asString4(payload?.subdomain)
+  };
+}
+async function fetchCrnExecutionMap(crnUrl, options) {
+  const normalizedCrnUrl = String(crnUrl).replace(/\/+$/, "");
+  for (const [version, suffix] of [
+    ["v2", "/v2/about/executions/list"],
+    ["v1", "/about/executions/list"]
+  ]) {
+    const requestUrl = `${normalizedCrnUrl}${suffix}`;
+    const response = await options.fetch(requestUrl, {
+      cache: "no-cache"
+    });
+    if (response.ok) {
+      const payload = await response.json();
+      return {
+        version,
+        payload: payload && typeof payload === "object" ? payload : null,
+        requestUrl
+      };
+    }
+    if (response.status !== 404) {
+      return {
+        version,
+        payload: null,
+        requestUrl
+      };
+    }
+  }
+  return {
+    version: "v2",
+    payload: null,
+    requestUrl: `${normalizedCrnUrl}/v2/about/executions/list`
+  };
+}
+function describeRuntimeAvailability(runtime) {
+  const execution = runtime.execution ?? null;
+  const mappedPorts = runtime.mappedPorts ?? {};
+  const hostIpv4 = runtime.hostIpv4 ?? null;
+  const proxyUrl = runtime.proxyUrl ?? null;
+  const schedulerSource = runtime.allocation?.source ?? null;
+  const webAccessActive = runtime.webAccess?.active ?? null;
+  const mappedPortCount = Object.keys(mappedPorts).length;
+  if (hostIpv4 && mappedPortCount > 0) {
+    return {
+      state: "ready",
+      reason: null,
+      schedulerSource,
+      executionSeen: Boolean(execution),
+      webAccessActive,
+      mappedPortCount,
+      proxyUrl
+    };
+  }
+  if (!execution && proxyUrl && webAccessActive === false) {
+    return {
+      state: "proxy-reserved-inactive",
+      reason: "Aleph reserved a proxy URL for the VM, but it is still inactive and the selected CRN has not exposed execution networking yet.",
+      schedulerSource,
+      executionSeen: false,
+      webAccessActive,
+      mappedPortCount,
+      proxyUrl
+    };
+  }
+  if (!execution && schedulerSource === "manual") {
+    return {
+      state: "crn-execution-missing",
+      reason: "The deployment is pinned to a specific CRN, but that CRN is not exposing this VM in its execution list yet.",
+      schedulerSource,
+      executionSeen: false,
+      webAccessActive,
+      mappedPortCount,
+      proxyUrl
+    };
+  }
+  if (execution && !hostIpv4) {
+    return {
+      state: "execution-missing-host-ipv4",
+      reason: "The CRN exposed an execution record, but it does not include a public host IPv4 yet.",
+      schedulerSource,
+      executionSeen: true,
+      webAccessActive,
+      mappedPortCount,
+      proxyUrl
+    };
+  }
+  if (execution && mappedPortCount === 0) {
+    return {
+      state: "execution-missing-port-mappings",
+      reason: "The CRN exposed an execution record, but mapped ports are still empty.",
+      schedulerSource,
+      executionSeen: true,
+      webAccessActive,
+      mappedPortCount,
+      proxyUrl
+    };
+  }
+  return {
+    state: "runtime-pending",
+    reason: "Aleph has not exposed enough runtime networking details yet.",
+    schedulerSource,
+    executionSeen: Boolean(execution),
+    webAccessActive,
+    mappedPortCount,
+    proxyUrl
+  };
+}
+async function fetchVmRuntime(args) {
+  const crns = args.crns ?? await fetchCrns({
+    url: args.crnListUrl ?? DEFAULT_CRN_LIST_URL,
+    fetch: args.fetch
+  });
+  const schedulerAllocation = await fetchSchedulerAllocation(args.itemHash, {
+    fetch: args.fetch,
+    schedulerAllocationUrl: args.schedulerAllocationUrl
+  }).catch(() => null);
+  const selectedCrn = args.crnHash ? findCrnByHash(crns, args.crnHash) : null;
+  const allocation = schedulerAllocation ?? (selectedCrn ? {
+    source: "manual",
+    crnHash: selectedCrn.hash,
+    crnUrl: selectedCrn.address,
+    node: { url: selectedCrn.address },
+    vmIpv6: null,
+    period: null
+  } : null);
+  const webAccess = await fetch2n6WebAccessUrl(args.itemHash, {
+    fetch: args.fetch,
+    twoN6HashUrl: args.twoN6HashUrl
+  }).catch(() => null);
+  const webAccessUrl = webAccess?.url ?? null;
+  let execution = null;
+  let executionLookupBlocked = false;
+  if (allocation?.crnUrl) {
+    const executionLookup = await fetchCrnExecutionMap(allocation.crnUrl, {
+      fetch: args.fetch
+    });
+    const executionPayload = executionLookup.payload?.[args.itemHash];
+    if (executionPayload && typeof executionPayload === "object") {
+      execution = normalizeExecution(executionPayload, allocation.crnUrl);
+      if (!execution.networking.proxy_url && webAccessUrl) {
+        execution.networking.proxy_url = webAccessUrl;
+      }
+    } else if (executionLookup.payload == null) {
+      executionLookupBlocked = true;
+    }
+  }
+  const hostIpv4 = execution?.networking?.host_ipv4 ?? execution?.networking?.ipv4 ?? null;
+  const ipv6 = execution?.networking?.ipv6_ip ?? execution?.networking?.ipv6 ?? allocation?.vmIpv6 ?? null;
+  const mappedPorts = execution?.networking?.mapped_ports ?? {};
+  const sshPort = mappedPorts?.["22"]?.host ?? null;
+  const proxyUrl = execution?.networking?.proxy_url ?? webAccessUrl ?? null;
+  const diagnostics = describeRuntimeAvailability({
+    allocation,
+    execution,
+    webAccess,
+    hostIpv4,
+    ipv6,
+    proxyUrl,
+    mappedPorts
+  });
+  return {
+    allocation,
+    execution,
+    webAccess,
+    webAccessUrl,
+    hostIpv4,
+    ipv6,
+    proxyUrl,
+    mappedPorts,
+    diagnostics,
+    sshCommand: hostIpv4 && sshPort ? `ssh root@${hostIpv4} -p ${sshPort}` : ipv6 ? `ssh root@${ipv6}` : null,
+    selectedCrn,
+    executionLookupBlocked
+  };
+}
+async function waitForVmRuntime(args) {
+  const attempts = Math.max(1, Number(args.attempts ?? 20));
+  const delayMs = Math.max(0, Number(args.delayMs ?? 4e3));
+  const sleep = args.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let lastRuntime = await fetchVmRuntime(args);
+  for (let attempt = 0; attempt < attempts - 1; attempt += 1) {
+    if (lastRuntime.hostIpv4 && Object.keys(lastRuntime.mappedPorts ?? {}).length > 0) {
+      return lastRuntime;
+    }
+    await sleep(delayMs);
+    lastRuntime = await fetchVmRuntime(args);
+  }
+  if (lastRuntime.diagnostics) {
+    lastRuntime.diagnostics.timedOut = true;
+  }
+  return lastRuntime;
+}
+
+// src/guest.ts
+function proxyHostnameFromUrl(value) {
+  try {
+    return value ? new URL(value).hostname : null;
+  } catch {
+    return null;
+  }
+}
+async function defaultHttpProbe(fetch, url, timeoutMs = 1e4) {
+  try {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const response = await fetch(url, {
+      method: "GET",
+      redirect: "follow",
+      signal: controller.signal
+    });
+    clearTimeout(timeout);
+    return {
+      ok: response.ok,
+      status: response.status,
+      url: response.url
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function notifyCrnAllocation(args) {
+  const normalizedCrnUrl = typeof args.crnUrl === "string" ? args.crnUrl.trim().replace(/\/+$/, "") : "";
+  if (!normalizedCrnUrl) {
+    return {
+      status: "skipped",
+      reason: "No CRN URL available for allocation notification."
+    };
+  }
+  try {
+    const response = await args.fetch(`${normalizedCrnUrl}/control/allocation/notify`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json"
+      },
+      body: JSON.stringify({ instance: args.itemHash })
+    });
+    const payload = await response.json().catch(() => null);
+    if (!response.ok) {
+      return {
+        status: "unconfirmed",
+        reason: `CRN allocation notify returned ${response.status}.`,
+        payload
+      };
+    }
+    return {
+      status: "confirmed",
+      payload
+    };
+  } catch (error) {
+    return {
+      status: "unconfirmed",
+      reason: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+async function waitForSetupEndpoint(args) {
+  const attempts = Math.max(1, Number(args.attempts ?? 15));
+  const delayMs = Math.max(0, Number(args.delayMs ?? 4e3));
+  const sleep = args.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const url = `http://${args.hostIpv4}:${args.setupPort}/health`;
+  let result = await defaultHttpProbe(args.fetch, url, Number(args.httpTimeoutMs ?? 1e4));
+  for (let attempt = 1; attempt < attempts; attempt += 1) {
+    if (result.ok) return result;
+    await sleep(delayMs);
+    result = await defaultHttpProbe(args.fetch, url, Number(args.httpTimeoutMs ?? 1e4));
+  }
+  return result;
+}
+async function configureUcGoPeer(args) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), Number(args.timeoutMs ?? 18e4));
+  const payload = {
+    public_ipv4: args.hostIpv4,
+    public_ipv6: args.publicIpv6 ?? void 0,
+    proxy_url: args.proxyUrl ?? void 0,
+    tcp_port: args.tcpPort ?? void 0,
+    ws_port: args.wsPort ?? void 0,
+    udp_port: args.udpPort ?? void 0,
+    quic_port: args.quicPort ?? void 0,
+    webrtc_port: args.webrtcPort ?? void 0
+  };
+  try {
+    const response = await args.fetch(`http://${args.hostIpv4}:${args.setupPort}/configure`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json"
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal
+    });
+    const responsePayload = await response.json().catch(() => null);
+    if (!response.ok) {
+      throw new Error(
+        `Relay setup request failed: ${response.status} ${typeof responsePayload === "string" ? responsePayload : JSON.stringify(responsePayload ?? {})}`
+      );
+    }
+    return responsePayload;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+async function fetchUcGoPeerMetadata(args) {
+  const attempts = Math.max(1, Number(args.attempts ?? 60));
+  const delayMs = Math.max(0, Number(args.delayMs ?? 3e3));
+  const sleep = args.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  let lastPayload = null;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), Number(args.timeoutMs ?? 18e4));
+    try {
+      const response = await args.fetch(`http://${args.hostIpv4}:${args.setupPort}/metadata`, {
+        signal: controller.signal
+      });
+      const payload = await response.json().catch(() => null);
+      lastPayload = payload;
+      if (response.ok && payload && typeof payload === "object" && payload.status === "ready") {
+        return payload;
+      }
+      if (response.status >= 500) {
+        throw new Error(
+          `Relay metadata request failed: ${response.status} ${typeof payload === "string" ? payload : JSON.stringify(payload ?? {})}`
+        );
+      }
+    } finally {
+      clearTimeout(timeout);
+    }
+    if (attempt < attempts - 1) {
+      await sleep(delayMs);
+    }
+  }
+  throw new Error(
+    `Relay metadata did not become ready after ${attempts} attempts: ${typeof lastPayload === "string" ? lastPayload : JSON.stringify(lastPayload ?? {})}`
+  );
+}
+async function verifyUcGoPeerReachability(args) {
+  const checks = {};
+  const mappedPorts = args.mappedPorts ?? {};
+  const hostIpv4 = args.hostIpv4;
+  const skippedInternalPorts = new Set((args.skipInternalPorts ?? ["80"]).map((value) => String(value)));
+  const httpProbe = args.httpProbe ?? ((url, timeoutMs) => defaultHttpProbe(args.fetch, url, timeoutMs));
+  if (hostIpv4) {
+    for (const [internalPort, mapping] of Object.entries(mappedPorts)) {
+      if (skippedInternalPorts.has(String(internalPort))) continue;
+      if (mapping?.tcp === true && mapping?.host) {
+        checks[`tcp:${internalPort}`] = {
+          host: hostIpv4,
+          port: mapping.host,
+          ...await args.tcpProbe(hostIpv4, mapping.host, Number(args.tcpTimeoutMs ?? 5e3))
+        };
+      } else if (mapping?.udp === true && mapping?.host) {
+        checks[`udp:${internalPort}`] = {
+          host: hostIpv4,
+          port: mapping.host,
+          ok: null,
+          note: "UDP mapping published; CI does not perform an application-level UDP handshake probe."
+        };
+      }
+    }
+  }
+  if (args.proxyUrl && args.verifyProxyHttp !== false) {
+    checks["https:proxy"] = await httpProbe(args.proxyUrl, Number(args.httpTimeoutMs ?? 1e4));
+  }
+  const proxyHostname = proxyHostnameFromUrl(args.proxyUrl);
+  if (proxyHostname) {
+    checks["tcp:proxy-443"] = await args.tcpProbe(proxyHostname, 443, Number(args.tcpTimeoutMs ?? 5e3));
+  }
+  const failedChecks = Object.entries(checks).filter(([, value]) => value?.ok === false);
+  return {
+    ok: failedChecks.length === 0,
+    checks
+  };
+}
+export {
+  DEFAULT_ALEPH_API_HOST,
+  DEFAULT_ALEPH_CHANNEL,
+  DEFAULT_COUNTRY_LOOKUP_BASE_URL,
+  DEFAULT_CRN_LIST_URL,
+  DEFAULT_DNS_RESOLVE_URL,
+  DEFAULT_INSTANCE_PORT_FORWARDS,
+  DEFAULT_IPFS_GATEWAY_BASE_URL,
+  DEFAULT_SCHEDULER_ALLOCATION_URL,
+  DEFAULT_TWO_N_SIX_HASH_URL,
+  ITEM_HASH_RE,
+  SSH_PUBLIC_KEY_PATTERN,
+  SUCCESSFUL_DEPLOYMENTS_AGGREGATE_KEY,
+  broadcastAlephMessage,
+  cleanupFailedDeployment,
+  configureUcGoPeer,
+  createInstanceContent,
+  createPortForwardAggregateContent,
+  createReleaseMetadata,
+  createUnsignedAggregateMessage2 as createUnsignedAggregateMessage,
+  createUnsignedForgetMessage,
+  createUnsignedInstanceMessage,
+  deployInstance,
+  describeRejectedDeployment,
+  describeRuntimeAvailability,
+  enrichCrnsWithGeo,
+  ensureInstancePortForwards,
+  extractProxyUrl,
+  extractReferenceHashes,
+  fetch2n6WebAccessUrl,
+  fetchAggregateKey,
+  fetchCrnExecutionMap,
+  fetchCrns,
+  fetchMessageEnvelope,
+  fetchPortForwardAggregate,
+  fetchSchedulerAllocation,
+  fetchUcGoPeerMetadata,
+  fetchVmRuntime,
+  findCrnByHash,
+  forgetAlephMessages,
+  inspectDeploymentResult,
+  inspectMessageResult,
+  isInvalidMessageFormatResponse,
+  isRetryableBroadcastFailure,
+  isValidSshPublicKey,
+  listGeocodedCrns,
+  mergePortFlagMaps,
+  mergeRequiredPortForwards,
+  messageTypeFromEnvelope,
+  normalizeBroadcastStatus,
+  normalizeExecution,
+  normalizeExistingPortForwardEntry,
+  normalizeMessageStatus,
+  normalizeProxyUrl,
+  normalizeSshPublicKey,
+  notifyCrnAllocation,
+  portForwardLabel,
+  postBroadcastPayload,
+  probeRootfsGateway,
+  publishAggregateKey,
+  rankCandidateCrns,
+  requestedPortFlags,
+  requiredInstancePortForwards,
+  resolveRootfsReference,
+  retainSuccessfulDeployments,
+  selectPreferredCrn,
+  signAlephMessage,
+  signaturePayload,
+  validateRootfsManifest,
+  verifyRootfsExists,
+  verifyUcGoPeerReachability,
+  waitForDeploymentResult,
+  waitForSetupEndpoint,
+  waitForVmRuntime
+};