nebula-treasury 0.1.0

package/src/util/github-releases.ts

@@ -0,0 +1,79 @@
+// GitHub Releases API helpers. Unauthenticated (60 req/hr per IP) which is
+// plenty for the upgrade hot path: one resolveLatestRelease + zero-or-one
+// checkTagExists per invocation. Pin `--ref vX.Y.Z` to skip the API entirely.
+export interface GitHubRelease {
+  tagName: string
+  publishedAt: string
+  htmlUrl: string
+}
+
+export interface GitHubFetchOpts {
+  /** Override fetch (mainly for tests). Defaults to global `fetch`. */
+  fetchImpl?: typeof fetch
+  /** Per-call timeout. Defaults to 10s. */
+  timeoutMs?: number
+}
+
+/**
+ * Parse `https://github.com/owner/repo.git`, `https://github.com/owner/repo`,
+ * or `git@github.com:owner/repo.git` into `{owner, repo}`. Throws on shapes
+ * the regex doesn't recognize.
+ */
+export function parseGitHubRepoUrl(url: string): { owner: string; repo: string } {
+  const match = url.match(/github\.com[:/]([^/]+)\/([^/.]+)/)
+  if (!match || !match[1] || !match[2]) throw new Error(`cannot parse GitHub repo URL: ${url}`)
+  return { owner: match[1], repo: match[2] }
+}
+
+/**
+ * Resolve the most recent published GitHub release for a repo. Skips drafts
+ * and pre-releases (that's what GitHub's `/releases/latest` endpoint returns
+ * by default). Throws on 404 (no published release) or non-200.
+ */
+export async function resolveLatestRelease(
+  repoUrl: string,
+  opts: GitHubFetchOpts = {},
+): Promise<GitHubRelease> {
+  const { owner, repo } = parseGitHubRepoUrl(repoUrl)
+  const fetchImpl = opts.fetchImpl ?? fetch
+  const timeoutMs = opts.timeoutMs ?? 10_000
+  const r = await fetchImpl(`https://api.github.com/repos/${owner}/${repo}/releases/latest`, {
+    headers: { Accept: 'application/vnd.github+json' },
+    signal: AbortSignal.timeout(timeoutMs),
+  })
+  if (r.status === 404) {
+    throw new Error(`no published releases found for ${owner}/${repo}`)
+  }
+  if (!r.ok) {
+    throw new Error(`GitHub API ${r.status} for ${owner}/${repo}/releases/latest`)
+  }
+  const data = (await r.json()) as { tag_name: string; published_at: string; html_url: string }
+  return { tagName: data.tag_name, publishedAt: data.published_at, htmlUrl: data.html_url }
+}
+
+/**
+ * Probe whether a tag exists on the remote. Returns `false` on 404 (the
+ * conventional "tag not found" signal), `true` on 200, throws on other
+ * errors so callers can surface "API down" vs "tag missing" distinctly.
+ */
+export async function checkTagExists(
+  repoUrl: string,
+  tag: string,
+  opts: GitHubFetchOpts = {},
+): Promise<boolean> {
+  const { owner, repo } = parseGitHubRepoUrl(repoUrl)
+  const fetchImpl = opts.fetchImpl ?? fetch
+  const timeoutMs = opts.timeoutMs ?? 10_000
+  const r = await fetchImpl(
+    `https://api.github.com/repos/${owner}/${repo}/git/refs/tags/${encodeURIComponent(tag)}`,
+    {
+      headers: { Accept: 'application/vnd.github+json' },
+      signal: AbortSignal.timeout(timeoutMs),
+    },
+  )
+  if (r.status === 404) return false
+  if (!r.ok) {
+    throw new Error(`GitHub API ${r.status} for ${owner}/${repo}/git/refs/tags/${tag}`)
+  }
+  return true
+}

package/src/util/profile-key.ts

@@ -0,0 +1,25 @@
+/**
+ * Local accessor for the cached PROFILE scope key.
+ *
+ * Wraps `getSessionKey(agentId, OPERATOR_BLOB_SCOPES.PROFILE)` with the
+ * hex-encoding the gateway handoff envelopes expect. Used by `nebula upgrade`
+ * (both `--reprovision` + in-place) to ship the cached key to the new sandbox
+ * daemon so it boots with `slots.profile` ready to anchor instead of
+ * `{ status: 'skipped', reason: 'no-profile-key' }`.
+ *
+ * Returns undefined when the operator session is absent / expired / missing
+ * the PROFILE scope (pre-v0.23.1 agents). Callers should surface a one-line
+ * note in that case so the operator knows to refresh the session before the
+ * next upgrade.
+ */
+
+import { OPERATOR_BLOB_SCOPES, getSessionKey } from 'nebula-ai-core'
+
+export function loadProfileScopeKeyHex(agentId: string): `0x${string}` | undefined {
+  try {
+    const buf = getSessionKey(agentId, OPERATOR_BLOB_SCOPES.PROFILE)
+    return buf ? (`0x${buf.toString('hex')}` as `0x${string}`) : undefined
+  } catch {
+    return undefined
+  }
+}

package/src/util/ref-resolver.ts

@@ -0,0 +1,55 @@
+import { type GitHubFetchOpts, resolveLatestRelease } from './github-releases'
+
+/** Canonical nebula repo. Override via {@link ResolveNebulaRefOpts.repoUrl}. */
+export const NEBULA_REPO_URL = 'https://github.com/rstfulzz/nebula.git'
+
+/** Magic ref keyword that triggers GitHub `releases/latest` resolution. */
+export const LATEST_KEYWORD = 'latest'
+
+export interface ResolvedRef {
+  ref: string
+  /** True if `ref` looks like `vX.Y.Z`. Drives pre/post-flight version verification. */
+  isTag: boolean
+  /** True if user said `latest` and we resolved via API — caller skips pre-flight (already source of truth). */
+  resolvedFromLatest: boolean
+}
+
+export interface ResolveNebulaRefOpts extends GitHubFetchOpts {
+  repoUrl?: string
+  /** Test seam. Defaults to `process.env`. */
+  env?: Record<string, string | undefined>
+}
+
+const TAG_RE = /^v\d+\.\d+\.\d+/
+
+/**
+ * Resolve user ref. Priority: rawRef → NEBULA_BOOTSTRAP_REF env → `latest`.
+ * Tag-shaped refs pass through. Branch / SHA refs return isTag=false (no
+ * version verification possible).
+ */
+export async function resolveNebulaRef(
+  rawRef: string | undefined,
+  opts: ResolveNebulaRefOpts = {},
+): Promise<ResolvedRef> {
+  const env = opts.env ?? process.env
+  const arg = rawRef ?? env.NEBULA_BOOTSTRAP_REF ?? LATEST_KEYWORD
+
+  if (arg === LATEST_KEYWORD) {
+    const release = await resolveLatestRelease(opts.repoUrl ?? NEBULA_REPO_URL, opts)
+    return { ref: release.tagName, isTag: true, resolvedFromLatest: true }
+  }
+  if (TAG_RE.test(arg)) {
+    return { ref: arg, isTag: true, resolvedFromLatest: false }
+  }
+  return { ref: arg, isTag: false, resolvedFromLatest: false }
+}
+
+/** Pretty form of a ResolvedRef for prompts and outros. Adds `(resolved from latest)` suffix when applicable. */
+export function formatResolvedRef(resolved: ResolvedRef): string {
+  return resolved.resolvedFromLatest ? `${resolved.ref} (resolved from latest)` : resolved.ref
+}
+
+/** Expected `package.json` version for a ResolvedRef, or null when no strict expectation (branch / SHA). */
+export function expectedVersionFromRef(resolved: ResolvedRef): string | null {
+  return resolved.isTag ? resolved.ref.replace(/^v/, '') : null
+}

package/src/util/silence-console.ts

@@ -0,0 +1,40 @@
+/**
+ * Run `fn` with `console.log/info/warn/error/debug` swapped for no-ops so they
+ * cannot interleave with clack's in-place spinner re-render. Originals are
+ * restored even if `fn` throws.
+ *
+ * Why: Mantle Storage SDK and Mantle Compute broker SDK both `console.log` directly
+ * during their work (selected nodes, upload progress, broker tx hashes, etc).
+ * When a clack spinner is running, every leaked log line pushes the spinner
+ * down and the next animation frame draws a new spinner row, creating the
+ * "100x stacked spinner" visual we saw on the WC init test. Suppressing these
+ * during the spinner-active phases keeps the wizard output clean.
+ *
+ * Note: `chat.tsx` does its own process-lifetime console redirect to a chat
+ * log file. That cannot use this helper because its lifetime is the whole
+ * session, not a scoped wrap. Keep the two pathways separate.
+ */
+export async function withSilencedConsole<T>(fn: () => Promise<T>): Promise<T> {
+  const orig = {
+    log: console.log,
+    info: console.info,
+    warn: console.warn,
+    error: console.error,
+    debug: console.debug,
+  }
+  const noop = (() => {}) as (...args: unknown[]) => void
+  console.log = noop as typeof console.log
+  console.info = noop as typeof console.info
+  console.warn = noop as typeof console.warn
+  console.error = noop as typeof console.error
+  console.debug = noop as typeof console.debug
+  try {
+    return await fn()
+  } finally {
+    console.log = orig.log
+    console.info = orig.info
+    console.warn = orig.warn
+    console.error = orig.error
+    console.debug = orig.debug
+  }
+}

package/src/util/telegram-secrets.ts

@@ -0,0 +1,218 @@
+/**
+ * Local persistence for telegram bot secrets, encrypted via the operator's
+ * sign-derived AEAD key (scope `OPERATOR_BLOB_SCOPES.TELEGRAM`).
+ *
+ * On-disk file: `~/.nebula/agents/<id>/telegram-secrets.encrypted`
+ *
+ *   {
+ *     version: 2,
+ *     scope: 'nebula-telegram-v1',
+ *     blob: <base64(iv|tag|ciphertext)>,
+ *   }
+ *
+ * Plaintext shape inside the blob:
+ *
+ *   {
+ *     botToken: string,         // from @BotFather
+ *     botUsername?: string,     // cached at setup-time getMe
+ *     botId?: number,           // cached at setup-time getMe
+ *     allowedUserIds: number[],
+ *   }
+ */
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import {
+  OPERATOR_BLOB_SCOPES,
+  type OperatorEncryptedBlob,
+  type OperatorSigner,
+  agentPaths,
+  decodeOperatorBlobBytes,
+  decryptOperatorBlob,
+  encodeOperatorBlobBytes,
+  encryptOperatorBlob,
+} from 'nebula-ai-core'
+import type { Address } from 'viem'
+
+export interface TelegramSecretsPlaintext {
+  botToken: string
+  botUsername?: string
+  botId?: number
+  allowedUserIds: number[]
+}
+
+/**
+ * Subset of `TelegramSecretsPlaintext` that the CLI ships into the harness
+ * provision envelope on init / upgrade / resume. The harness doesn't need
+ * the operator-side metadata (`botUsername`, `botId`); it only needs the
+ * token + allowlist + optional pairing list. Centralising this as a named
+ * type avoids drift between the four CLI handoff sites that previously
+ * inlined the literal shape (init wizard, upgrade, resume, the
+ * `HandoffAgentToGateway` + `ResumeArchivedSandbox` interfaces).
+ */
+export interface TelegramHandoffSecrets {
+  botToken: string
+  allowedUserIds: number[]
+  pairingApproved?: number[]
+}
+
+export function telegramSecretsPath(agentId: string): string {
+  return join(agentPaths.agent(agentId).dir, 'telegram-secrets.encrypted')
+}
+
+export function telegramSecretsExist(agentId: string): boolean {
+  return existsSync(telegramSecretsPath(agentId))
+}
+
+export async function loadTelegramSecrets(opts: {
+  signer: OperatorSigner
+  agentAddress: Address
+  agentId: string
+}): Promise<TelegramSecretsPlaintext | null> {
+  const path = telegramSecretsPath(opts.agentId)
+  if (!existsSync(path)) return null
+  const fileBytes = await readFile(path)
+  const blob: OperatorEncryptedBlob = decodeOperatorBlobBytes(new Uint8Array(fileBytes))
+  const ptBytes = await decryptOperatorBlob({
+    signer: opts.signer,
+    scope: OPERATOR_BLOB_SCOPES.TELEGRAM,
+    agentAddress: opts.agentAddress,
+    blob,
+  })
+  const parsed = JSON.parse(new TextDecoder().decode(ptBytes)) as TelegramSecretsPlaintext
+  if (typeof parsed.botToken !== 'string' || !Array.isArray(parsed.allowedUserIds)) {
+    throw new Error('telegram-secrets: malformed plaintext (missing botToken or allowedUserIds)')
+  }
+  return parsed
+}
+
+/**
+ * Load + project telegram secrets into the shape the gateway provision envelope
+ * expects. Used by every sandbox-handoff flow that ships TG (init/upgrade/
+ * resume/deploy/chat-sandbox auto-resume); centralises the try/decrypt/swallow
+ * pattern so future TG-secret schema changes touch one place.
+ *
+ * Errors are non-fatal: TG is opt-in. Failure fires `onNotice` (so the operator
+ * sees the reason in the spinner) and returns undefined.
+ *
+ * `chat.tsx` keeps its own loader because it needs the full plaintext (including
+ * `botUsername` for the unlock spinner UX).
+ */
+export async function loadTelegramHandoffSecrets(opts: {
+  signer: OperatorSigner
+  agentAddress: Address
+  agentId: string
+  onNotice?: (msg: string) => void
+}): Promise<TelegramHandoffSecrets | undefined> {
+  const agentId = opts.agentId
+  try {
+    const tg = await loadTelegramSecrets({
+      signer: opts.signer,
+      agentAddress: opts.agentAddress,
+      agentId,
+    })
+    if (!tg) return undefined
+    return { botToken: tg.botToken, allowedUserIds: tg.allowedUserIds }
+  } catch (err) {
+    opts.onNotice?.(`telegram secrets read failed: ${(err as Error).message.slice(0, 120)}`)
+    return undefined
+  }
+}
+
+export async function saveTelegramSecrets(opts: {
+  signer: OperatorSigner
+  agentAddress: Address
+  agentId: string
+  plaintext: TelegramSecretsPlaintext
+  /**
+   * v0.24.3: pre-derived TELEGRAM scope key (32 bytes). The init wizard
+   * derives this once and passes it both here AND into `.operator-session`,
+   * so encryptOperatorBlob skips the redundant sign it would otherwise make.
+   * Threads through to encryptOperatorBlob; see that helper for fallback.
+   */
+  precomputedKey?: Buffer
+}): Promise<void> {
+  const path = telegramSecretsPath(opts.agentId)
+  await mkdir(dirname(path), { recursive: true })
+  const ptBytes = new TextEncoder().encode(JSON.stringify(opts.plaintext))
+  const blob = await encryptOperatorBlob({
+    signer: opts.signer,
+    scope: OPERATOR_BLOB_SCOPES.TELEGRAM,
+    agentAddress: opts.agentAddress,
+    plaintext: ptBytes,
+    precomputedKey: opts.precomputedKey,
+  })
+  await writeFile(path, encodeOperatorBlobBytes(blob))
+}
+
+export async function removeTelegramSecrets(agentId: string): Promise<boolean> {
+  const path = telegramSecretsPath(agentId)
+  if (!existsSync(path)) return false
+  await rm(path, { force: true })
+  return true
+}
+
+const BOT_TOKEN_RE = /^\d{6,15}:[A-Za-z0-9_-]{30,}$/
+
+export function looksLikeBotToken(s: string): boolean {
+  return BOT_TOKEN_RE.test(s.trim())
+}
+
+export interface ValidatedBotInfo {
+  id: number
+  username: string
+  firstName: string
+}
+
+/**
+ * Telegram Bot API getMe — cheap, free, no message side-effect. Used by
+ * `nebula telegram setup` to validate the token before persisting it AND by
+ * `nebula telegram status` to confirm the stored token still works.
+ *
+ * Throws on non-200 / `ok: false` with a clean error message; caller wraps
+ * the throw in a clack spinner.stop().
+ */
+export async function fetchBotInfo(
+  botToken: string,
+  opts?: { signal?: AbortSignal },
+): Promise<ValidatedBotInfo> {
+  const url = `https://api.telegram.org/bot${encodeURIComponent(botToken)}/getMe`
+  const res = await fetch(url, { signal: opts?.signal })
+  if (!res.ok) {
+    throw new Error(`getMe HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`)
+  }
+  const body = (await res.json()) as {
+    ok: boolean
+    description?: string
+    result?: { id: number; username?: string; first_name?: string }
+  }
+  if (!body.ok || !body.result) {
+    throw new Error(`getMe rejected: ${body.description ?? 'unknown error'}`)
+  }
+  if (!body.result.username) throw new Error('bot has no username; create one in @BotFather')
+  return {
+    id: body.result.id,
+    username: body.result.username,
+    firstName: body.result.first_name ?? body.result.username,
+  }
+}
+
+export function parseAllowedUserIds(
+  input: string,
+): { ok: true; ids: number[] } | { ok: false; reason: string } {
+  const trimmed = input.trim()
+  if (trimmed.length === 0) return { ok: true, ids: [] }
+  const parts = trimmed
+    .split(/[,\s]+/)
+    .map(p => p.trim())
+    .filter(p => p.length > 0)
+  const ids: number[] = []
+  for (const p of parts) {
+    if (!/^\d+$/.test(p)) return { ok: false, reason: `not a numeric id: "${p}"` }
+    const n = Number(p)
+    if (!Number.isFinite(n) || n <= 0) return { ok: false, reason: `not a positive id: "${p}"` }
+    ids.push(n)
+  }
+  // Dedupe, preserve first-seen order.
+  return { ok: true, ids: [...new Set(ids)] }
+}