nebula-ai-core 0.1.0

package/src/migration/option3-crypto.ts

@@ -0,0 +1,127 @@
+import { createCipheriv, createDecipheriv, hkdfSync, randomBytes } from 'node:crypto'
+import { secp256k1 } from '@noble/curves/secp256k1.js'
+import { type Hex, bytesToHex, hexToBytes } from 'viem'
+
+/**
+ * Phase 6.6 Option 3: TEE → TEE migration ECIES.
+ *
+ * The local gateway (which holds the plaintext agent privkey in its RAM)
+ * encrypts the privkey to the sandbox container's bootstrap pubkey. The CLI
+ * only ever relays ciphertext — the operator's laptop never sees the
+ * plaintext during a Local → Sandbox migration.
+ *
+ * Wire shape (envelope, base64-of):
+ *   ephPubKey(33 bytes, compressed) || iv(12) || tag(16) || ct(N)
+ *
+ * Encryption:
+ *   1. Generate ephemeral secp256k1 keypair (ekPriv, ekPub).
+ *   2. Compute shared = ECDH(ekPriv, recipientPub) — uncompressed 64-byte point's
+ *      x-coordinate (32 bytes).
+ *   3. Derive 32-byte AEAD key via HKDF-SHA256(shared, salt=ekPub, info='nebula-option3-v1').
+ *   4. AES-256-GCM(key, iv, plaintext).
+ *
+ * Decryption:
+ *   1. Recompute shared = ECDH(recipientPriv, ekPub).
+ *   2. Same HKDF derivation.
+ *   3. AES-256-GCM decrypt.
+ *
+ * Where this is wired:
+ *   - `POST /migration/encrypt-to`  on the local gateway: takes a container
+ *      bootstrap pubkey + operator-signed migration request, returns the
+ *      envelope here. Sandbox harness Phase 11 lands the gateway endpoint.
+ *   - `POST /bootstrap/provision` on the sandbox container: receives the
+ *      envelope and decrypts inside its sealed memory. Phase 11 lands the
+ *      container endpoint.
+ *
+ * MVP caveat: in unsealed sandbox mode the local gateway can't
+ * cryptographically verify the container's bootstrap pubkey, so a network
+ * MITM could substitute a pubkey it controls and harvest the plaintext.
+ * Sealed sandbox mode (Phase 11 stretch) closes the gap via TDX attestation;
+ * the gateway verifies the attestation report before encrypting.
+ */
+const HKDF_INFO = Buffer.from('nebula-option3-v1', 'utf8')
+
+export interface Option3Envelope {
+  /** Ephemeral compressed secp256k1 pubkey (33 bytes), hex-encoded. */
+  ephPubkeyHex: Hex
+  /** Random 12-byte IV, hex-encoded. */
+  ivHex: Hex
+  /** AES-GCM 16-byte auth tag, hex-encoded. */
+  tagHex: Hex
+  /** AES-GCM ciphertext, hex-encoded. */
+  ciphertextHex: Hex
+}
+
+/**
+ * Encrypt a plaintext payload to the container's bootstrap pubkey.
+ *
+ * @param recipientPubkey 33-byte compressed or 65-byte uncompressed secp256k1 pubkey hex.
+ * @param plaintext bytes to encrypt (typically the agent privkey, 32 bytes).
+ */
+export function encryptToPubkey(opts: {
+  recipientPubkey: Hex
+  plaintext: Uint8Array
+}): Option3Envelope {
+  const recipientPubBytes = hexToBytes(opts.recipientPubkey)
+  if (recipientPubBytes.length !== 33 && recipientPubBytes.length !== 65) {
+    throw new Error(
+      `Invalid recipient pubkey length: ${recipientPubBytes.length} (expected 33 or 65 bytes)`,
+    )
+  }
+
+  const eph = secp256k1.keygen()
+  const ekPriv = eph.secretKey
+  const ekPubCompressed = secp256k1.getPublicKey(ekPriv, true)
+
+  const shared = secp256k1.getSharedSecret(ekPriv, recipientPubBytes, true)
+  const ikm = Buffer.from(shared.subarray(1)) // strip 0x02/0x03 sign byte → 32-byte x-coord
+  const aeadKey = Buffer.from(hkdfSync('sha256', ikm, Buffer.from(ekPubCompressed), HKDF_INFO, 32))
+
+  const iv = randomBytes(12)
+  const cipher = createCipheriv('aes-256-gcm', aeadKey, iv)
+  const ct = Buffer.concat([cipher.update(opts.plaintext), cipher.final()])
+  const tag = cipher.getAuthTag()
+
+  return {
+    ephPubkeyHex: bytesToHex(ekPubCompressed),
+    ivHex: bytesToHex(new Uint8Array(iv)),
+    tagHex: bytesToHex(new Uint8Array(tag)),
+    ciphertextHex: bytesToHex(new Uint8Array(ct)),
+  }
+}
+
+export function decryptWithPrivkey(opts: {
+  recipientPrivkey: Hex
+  envelope: Option3Envelope
+}): Uint8Array {
+  const ekPubBytes = hexToBytes(opts.envelope.ephPubkeyHex)
+  const recipientPrivBytes = hexToBytes(opts.recipientPrivkey)
+
+  const shared = secp256k1.getSharedSecret(recipientPrivBytes, ekPubBytes, true)
+  const ikm = Buffer.from(shared.subarray(1))
+  const aeadKey = Buffer.from(hkdfSync('sha256', ikm, Buffer.from(ekPubBytes), HKDF_INFO, 32))
+
+  const iv = hexToBytes(opts.envelope.ivHex)
+  const tag = hexToBytes(opts.envelope.tagHex)
+  const ct = hexToBytes(opts.envelope.ciphertextHex)
+
+  const decipher = createDecipheriv('aes-256-gcm', aeadKey, iv)
+  decipher.setAuthTag(Buffer.from(tag))
+  return new Uint8Array(Buffer.concat([decipher.update(ct), decipher.final()]))
+}
+
+/** Convenience: derive a fresh container bootstrap keypair (used by sandbox harness). */
+export function generateBootstrapKeypair(): {
+  privkeyHex: Hex
+  pubkeyHexCompressed: Hex
+  pubkeyHexUncompressed: Hex
+} {
+  const { secretKey } = secp256k1.keygen()
+  const pubC = secp256k1.getPublicKey(secretKey, true)
+  const pubU = secp256k1.getPublicKey(secretKey, false)
+  return {
+    privkeyHex: bytesToHex(secretKey),
+    pubkeyHexCompressed: bytesToHex(pubC),
+    pubkeyHexUncompressed: bytesToHex(pubU),
+  }
+}

package/src/operator/index.ts

@@ -0,0 +1,9 @@
+export type { OperatorSigner } from './signer'
+export { KeychainOperatorSigner } from './keychain'
+export { KeystoreFileOperatorSigner } from './keystore-file'
+export { RawPrivkeyOperatorSigner } from './raw-privkey'
+export {
+  WalletConnectOperatorSigner,
+  NEBULA_WC_PROJECT_ID,
+} from './walletconnect'
+export type { WalletConnectOperatorSignerOptions } from './walletconnect'

package/src/operator/keychain.ts

@@ -0,0 +1,53 @@
+import { spawnSync } from 'node:child_process'
+import type { Hex } from 'viem'
+import { PrivkeyOperatorSigner } from './privkey-base'
+
+/** Safe subset of characters allowed in a keychain service name. Rejects
+ *  shell metacharacters so user-supplied service names can never inject.
+ */
+const SERVICE_NAME_RE = /^[a-zA-Z0-9._-]{1,128}$/
+
+/**
+ * Loads the operator privkey from the macOS Keychain under a service name.
+ *
+ * First-class operator wallet source on macOS. Same trust model as a password
+ * manager: the key is encrypted at rest by the OS, unlocked by the user's
+ * login password, accessible to the process the user is running. Keychain
+ * entries can optionally be gated by Touch ID via the biometric helper
+ * (shipped as a separate Swift binary, see Phase 6.5b).
+ *
+ * Linux and Windows equivalents (libsecret, Credential Manager) are post-MVP.
+ * For now non-macOS users pick one of the other OperatorSigner implementations
+ * (WalletConnect, keystore file, raw privkey).
+ *
+ * Service name is user-chosen: we default to `nebula.operator` but the caller
+ * can pass any string. Existing dev setups may use `dev.deployer` etc.
+ */
+export class KeychainOperatorSigner extends PrivkeyOperatorSigner {
+  readonly source: string
+
+  constructor(private readonly keychainService: string = 'dev.deployer') {
+    super()
+    if (!SERVICE_NAME_RE.test(keychainService)) {
+      throw new Error(
+        `Invalid keychain service name. Allowed: alphanumerics, dot, underscore, hyphen (max 128). Got: ${keychainService}`,
+      )
+    }
+    this.source = `keychain:${keychainService}`
+  }
+
+  protected async loadPrivkey(): Promise<Hex> {
+    const result = spawnSync(
+      'security',
+      ['find-generic-password', '-s', this.keychainService, '-w'],
+      { encoding: 'utf8' },
+    )
+    if (result.status !== 0) {
+      throw new Error(
+        `security find-generic-password failed for service '${this.keychainService}': ${result.stderr?.trim() || `exit ${result.status}`}`,
+      )
+    }
+    const raw = result.stdout.trim()
+    return (raw.startsWith('0x') ? raw : `0x${raw}`) as Hex
+  }
+}

package/src/operator/keystore-file.ts

@@ -0,0 +1,33 @@
+import { readFile } from 'node:fs/promises'
+import { Wallet as EthersWallet } from 'ethers'
+import type { Hex } from 'viem'
+import { PrivkeyOperatorSigner } from './privkey-base'
+
+/**
+ * Operator source backed by a standard geth-format encrypted JSON keystore.
+ * Portable across machines, no network dependency, no OS-specific keystore.
+ *
+ * Caller is responsible for prompting the user for the passphrase; the signer
+ * just decrypts lazily on first use and caches the privkey in memory.
+ */
+export class KeystoreFileOperatorSigner extends PrivkeyOperatorSigner {
+  readonly source: string
+
+  constructor(
+    private readonly opts: {
+      /** Absolute path to the encrypted JSON keystore (geth format). */
+      path: string
+      /** Pre-collected passphrase. CLI prompts; core decrypts. */
+      passphrase: string
+    },
+  ) {
+    super()
+    this.source = `keystore:${opts.path}`
+  }
+
+  protected async loadPrivkey(): Promise<Hex> {
+    const json = await readFile(this.opts.path, 'utf8')
+    const wallet = await EthersWallet.fromEncryptedJson(json, this.opts.passphrase)
+    return wallet.privateKey as Hex
+  }
+}

package/src/operator/privkey-base.ts

@@ -0,0 +1,60 @@
+import {
+  http,
+  type Address,
+  type Chain,
+  type Hex,
+  type PublicClient,
+  type WalletClient,
+  createPublicClient,
+} from 'viem'
+import { type PrivateKeyAccount, privateKeyToAccount } from 'viem/accounts'
+import { makeViemClients, mantleChain } from '../chain'
+import { NETWORK_RPC, type NebulaNetwork } from '../config'
+import type { OperatorSigner } from './signer'
+
+/**
+ * Shared base for privkey-backed operator sources. Subclasses only need to
+ * implement `loadPrivkey()` — everything else (viem account/wallet/public
+ * clients, caching) is identical across keychain / keystore-file / raw
+ * privkey, and that shared plumbing lives here.
+ *
+ * WalletConnect does NOT extend this base: its signing happens on a paired
+ * phone, there's no local privkey, so it has its own custom `walletClient`.
+ */
+export abstract class PrivkeyOperatorSigner implements OperatorSigner {
+  abstract readonly source: string
+  private cachedPrivkey: Hex | null = null
+  private cachedAccount: PrivateKeyAccount | null = null
+
+  /** Subclass hook: yield a 32-byte hex privkey. Caller invoked at most once. */
+  protected abstract loadPrivkey(): Promise<Hex>
+
+  protected async getPrivkey(): Promise<Hex> {
+    if (!this.cachedPrivkey) this.cachedPrivkey = await this.loadPrivkey()
+    return this.cachedPrivkey
+  }
+
+  async account(): Promise<PrivateKeyAccount> {
+    if (!this.cachedAccount) this.cachedAccount = privateKeyToAccount(await this.getPrivkey())
+    return this.cachedAccount
+  }
+
+  async address(): Promise<Address> {
+    return (await this.account()).address
+  }
+
+  async walletClient(network: NebulaNetwork): Promise<WalletClient> {
+    return makeViemClients({ network, privkeyHex: await this.getPrivkey() }).walletClient
+  }
+
+  async publicClient(network: NebulaNetwork): Promise<PublicClient> {
+    return createPublicClient({
+      transport: http(NETWORK_RPC[network]),
+      chain: mantleChain(network),
+    })
+  }
+
+  chain(network: NebulaNetwork): Chain {
+    return mantleChain(network)
+  }
+}

package/src/operator/raw-privkey.ts

@@ -0,0 +1,39 @@
+import type { Hex } from 'viem'
+import { PrivkeyOperatorSigner } from './privkey-base'
+
+/**
+ * Operator source backed by a raw private key supplied as a hex string.
+ *
+ * CLI layer collects the hex (stdin prompt, `--privkey` flag, or
+ * `NEBULA_OPERATOR_PRIVKEY` env var) and passes it in. The signer just wraps.
+ * Intended for CI/scripting and for users who prefer no-on-disk secrets.
+ *
+ * The hex may be passed with or without the `0x` prefix; the signer normalizes.
+ */
+export class RawPrivkeyOperatorSigner extends PrivkeyOperatorSigner {
+  readonly source: string
+  private readonly privkeyHex: Hex
+
+  constructor(opts: {
+    /** Raw private key hex, with or without `0x` prefix. */
+    privkey: string
+    /**
+     * Optional label for logs (e.g. `"env:NEBULA_OPERATOR_PRIVKEY"` or
+     * `"stdin"`). Defaults to `"raw-privkey"` which tells the user nothing.
+     */
+    sourceLabel?: string
+  }) {
+    super()
+    const raw = opts.privkey.trim()
+    const withPrefix = raw.startsWith('0x') ? raw : `0x${raw}`
+    if (!/^0x[0-9a-fA-F]{64}$/.test(withPrefix)) {
+      throw new Error('RawPrivkeyOperatorSigner: privkey must be 32 bytes hex (with or without 0x)')
+    }
+    this.privkeyHex = withPrefix as Hex
+    this.source = opts.sourceLabel ? `raw-privkey:${opts.sourceLabel}` : 'raw-privkey'
+  }
+
+  protected async loadPrivkey(): Promise<Hex> {
+    return this.privkeyHex
+  }
+}

package/src/operator/signer.ts

@@ -0,0 +1,46 @@
+import type { Address, Chain, PublicClient, WalletClient } from 'viem'
+import type { LocalAccount } from 'viem/accounts'
+import type { NebulaNetwork } from '../config'
+
+/**
+ * The operator is the human (or organization) behind an nebula agent. Per
+ * project-nebula.md section 22.1, the operator's wallet is what OWNS the
+ * ERC-7857 iNFT. A separate agent EOA (generated by `nebula init`) is a
+ * pay-for-infra key that the operator approves via `setApprovalForAll`.
+ *
+ * Operator signing material can come from many sources. First-class sources:
+ * - WalletConnect v2 (QR pair to any WC-compatible mobile wallet)
+ * - OS keychain (macOS Keychain, later libsecret and Credential Manager)
+ * - Encrypted keystore file (geth-format JSON)
+ * - Raw private key (CLI/scripting, env var, or stdin prompt)
+ *
+ * This interface is the abstraction a caller uses without caring which source
+ * is behind it. All four implementations satisfy the same contract, so init
+ * flow, topup flow, and future governance flows can pick at runtime.
+ */
+export interface OperatorSigner {
+  /** Source label for logs + UI ("keychain:<service>", "walletconnect:<peer>", "keystore:<path>", ...). */
+  readonly source: string
+  /** Operator's on-chain address. Becomes the iNFT owner. */
+  address(): Promise<Address>
+  /**
+   * viem LocalAccount for composing with wallet clients. For privkey-based
+   * sources (keychain, keystore file, raw) this is a `PrivateKeyAccount`. For
+   * WalletConnect it's a custom local account whose sign methods delegate to
+   * the paired mobile wallet over the WC relay. Keeping the return type as
+   * `LocalAccount` (not the broader `Account`) guarantees `signTypedData` is
+   * reachable, which Phase 6.6 needs for the sign-derived-key keystore.
+   */
+  account(): Promise<LocalAccount>
+  /** A wallet client bound to `network` that signs from the operator's address. */
+  walletClient(network: NebulaNetwork): Promise<WalletClient>
+  /** A public client for the same network (reads only). */
+  publicClient(network: NebulaNetwork): Promise<PublicClient>
+  /** Chain metadata as viem Chain, per network. */
+  chain(network: NebulaNetwork): Chain
+  /**
+   * Optional teardown. WalletConnect uses this to close the session cleanly;
+   * privkey-based sources have nothing to release. Safe to call unconditionally.
+   */
+  close?(): Promise<void>
+}