@tangle-network/tcloud 0.4.2 → 0.4.3

package/dist/attestation.cjs

@@ -0,0 +1,46 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/attestation.ts
+var attestation_exports = {};
+__export(attestation_exports, {
+  assertAttestation: () => import_tcloud_attestation.assertAttestation,
+  createSevSnpHardwareVerifier: () => import_tcloud_attestation.createSevSnpHardwareVerifier,
+  createTdxHardwareVerifier: () => import_tcloud_attestation.createTdxHardwareVerifier,
+  normalizeTeeType: () => import_tcloud_attestation.normalizeTeeType,
+  parseAttestation: () => import_tcloud_attestation.parseAttestation,
+  parseSevSnpReport: () => import_tcloud_attestation.parseSevSnpReport,
+  toHex: () => import_tcloud_attestation.toHex,
+  verifyAttestation: () => import_tcloud_attestation.verifyAttestation,
+  verifyAttestationAsync: () => import_tcloud_attestation.verifyAttestationAsync
+});
+module.exports = __toCommonJS(attestation_exports);
+var import_tcloud_attestation = require("@tangle-network/tcloud-attestation");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  assertAttestation,
+  createSevSnpHardwareVerifier,
+  createTdxHardwareVerifier,
+  normalizeTeeType,
+  parseAttestation,
+  parseSevSnpReport,
+  toHex,
+  verifyAttestation,
+  verifyAttestationAsync
+});

package/dist/attestation.d.cts

@@ -0,0 +1 @@
+export { AsyncAttestationPolicy, AsyncHardwareVerifier, AttestationPolicy, AttestationVerificationResult, HardwareVerifier, HardwareVerifierResult, ParsedAttestation, SevSnpReport, SevSnpVerifierOptions, TeeType, assertAttestation, createSevSnpHardwareVerifier, createTdxHardwareVerifier, normalizeTeeType, parseAttestation, parseSevSnpReport, toHex, verifyAttestation, verifyAttestationAsync } from '@tangle-network/tcloud-attestation';

package/dist/attestation.d.ts

@@ -0,0 +1 @@
+export { AsyncAttestationPolicy, AsyncHardwareVerifier, AttestationPolicy, AttestationVerificationResult, HardwareVerifier, HardwareVerifierResult, ParsedAttestation, SevSnpReport, SevSnpVerifierOptions, TeeType, assertAttestation, createSevSnpHardwareVerifier, createTdxHardwareVerifier, normalizeTeeType, parseAttestation, parseSevSnpReport, toHex, verifyAttestation, verifyAttestationAsync } from '@tangle-network/tcloud-attestation';

package/dist/attestation.js

@@ -0,0 +1,23 @@
+// src/attestation.ts
+import {
+  assertAttestation,
+  createSevSnpHardwareVerifier,
+  createTdxHardwareVerifier,
+  normalizeTeeType,
+  parseSevSnpReport,
+  parseAttestation,
+  toHex,
+  verifyAttestation,
+  verifyAttestationAsync
+} from "@tangle-network/tcloud-attestation";
+export {
+  assertAttestation,
+  createSevSnpHardwareVerifier,
+  createTdxHardwareVerifier,
+  normalizeTeeType,
+  parseAttestation,
+  parseSevSnpReport,
+  toHex,
+  verifyAttestation,
+  verifyAttestationAsync
+};

package/dist/{chunk-A7AEPV2G.js → chunk-4ZUVGKVH.js}

@@ -1,6 +1,6 @@
 import {
   TCloudClient
-} from "./chunk-B22AH4JH.js";
+} from "./chunk-M5K3EFNP.js";
 
 // src/shielded.ts
 import { privateKeyToAccount } from "viem/accounts";

package/dist/chunk-DBIT227N.js

@@ -0,0 +1,324 @@
+// src/sandbox.ts
+import { Sandbox } from "@tangle-network/sandbox";
+import { createHash, randomBytes } from "crypto";
+import {
+  normalizeTeeType,
+  verifyAttestationAsync
+} from "@tangle-network/tcloud-attestation";
+var DEFAULT_SANDBOX_URL = "https://sandbox.tangle.tools";
+var TCloudSandbox = class {
+  client;
+  apiKey;
+  baseUrl;
+  timeoutMs;
+  constructor(config) {
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl ?? DEFAULT_SANDBOX_URL).replace(/\/+$/, "");
+    this.timeoutMs = config.timeoutMs;
+    this.client = new Sandbox({
+      apiKey: this.apiKey,
+      baseUrl: this.baseUrl,
+      timeoutMs: config.timeoutMs
+    });
+  }
+  async create(options) {
+    const effectiveVerify = shouldVerifyAttestation(options);
+    const attestationPolicy = buildAttestationPolicy(options);
+    const createOptions = buildSandboxCreateOptions({
+      ...options,
+      verify: effectiveVerify
+    });
+    const sandbox = await this.client.create(createOptions);
+    this.attachTeeApiFallbacks(sandbox);
+    let attestation = attestationFromMetadata(sandbox.metadata);
+    if ((effectiveVerify || createOptions.confidential?.attestationNonce) && !attestation) {
+      const getTeeAttestation = sandbox.getTeeAttestation;
+      if (typeof getTeeAttestation !== "function") {
+        throw new Error("Installed @tangle-network/sandbox does not expose TEE attestation fetching");
+      }
+      attestation = (await getTeeAttestation.call(
+        sandbox,
+        createOptions.confidential?.attestationNonce ? { attestationNonce: createOptions.confidential.attestationNonce } : void 0
+      )).attestation;
+    }
+    if (effectiveVerify && !attestation) {
+      throw new Error("TEE attestation verification requested but no evidence was returned");
+    }
+    const verification = effectiveVerify ? await verifyAttestationAsync(attestation, {
+      ...attestationPolicy,
+      expectedNonce: createOptions.confidential?.attestationNonce
+    }) : void 0;
+    if (verification && !verification.valid) {
+      throw new Error(`TEE attestation verification failed: ${verification.errors.join("; ")}`);
+    }
+    return {
+      sandbox,
+      attestation,
+      verification,
+      attestationNonce: createOptions.confidential?.attestationNonce,
+      attestationStatus: {
+        requested: Boolean(options.tee),
+        evidenceReturned: Boolean(attestation),
+        verified: Boolean(verification?.valid),
+        nonceBound: Boolean(createOptions.confidential?.attestationNonce && verification?.valid),
+        errors: verification?.errors ?? []
+      }
+    };
+  }
+  attachTeeApiFallbacks(sandbox) {
+    if (typeof sandbox !== "object" || sandbox === null) return;
+    const target = sandbox;
+    if (typeof target.id !== "string" || target.id.length === 0) return;
+    if (typeof target.getTeeAttestation !== "function") {
+      target.getTeeAttestation = (options) => this.fetchTeeAttestation(target.id, options?.attestationNonce);
+    }
+    if (typeof target.getTeePublicKey !== "function") {
+      target.getTeePublicKey = () => this.fetchTeePublicKey(target.id);
+    }
+  }
+  async fetchTeeAttestation(sandboxId, attestationNonce) {
+    const response = await this.fetchSandboxApi(
+      `/v1/sandboxes/${encodeURIComponent(sandboxId)}/tee/attestation`,
+      {
+        method: attestationNonce ? "POST" : "GET",
+        body: attestationNonce ? JSON.stringify({ attestation_nonce: attestationNonce }) : void 0
+      }
+    );
+    const data = await response.json();
+    if (attestationNonce && !data.attestationNonce) {
+      data.attestationNonce = attestationNonce;
+    }
+    return data;
+  }
+  async fetchTeePublicKey(sandboxId) {
+    const response = await this.fetchSandboxApi(
+      `/v1/sandboxes/${encodeURIComponent(sandboxId)}/tee/public-key`,
+      { method: "GET" }
+    );
+    return response.json();
+  }
+  async fetchSandboxApi(path, options) {
+    const headers = new Headers(options.headers);
+    headers.set("Authorization", `Bearer ${this.apiKey}`);
+    if (options.body && !headers.has("Content-Type")) {
+      headers.set("Content-Type", "application/json");
+    }
+    const response = await fetch(`${this.baseUrl}${path}`, {
+      ...options,
+      headers,
+      signal: options.signal ?? (this.timeoutMs ? AbortSignal.timeout(this.timeoutMs) : void 0)
+    });
+    if (!response.ok) {
+      const body = await response.text();
+      throw new Error(`Sandbox API ${path} failed with HTTP ${response.status}: ${body}`);
+    }
+    return response;
+  }
+};
+function createTeeAttestationChallenge(context) {
+  const randomHex = generateAttestationNonce(32);
+  if (context == null) {
+    return { nonce: randomHex, randomHex };
+  }
+  const contextHashHex = createHash("sha256").update(typeof context === "string" ? Buffer.from(context) : Buffer.from(context)).digest("hex");
+  return {
+    nonce: `${randomHex}${contextHashHex}`,
+    randomHex,
+    contextHashHex
+  };
+}
+function startTeeAttestationHeartbeat(sandbox, options = {}) {
+  const getTeeAttestation = sandbox?.getTeeAttestation;
+  if (typeof getTeeAttestation !== "function") {
+    throw new Error("Sandbox does not expose TEE attestation fetching");
+  }
+  const intervalMs = options.intervalMs ?? 6e4;
+  const sessionId = options.sessionId ?? generateAttestationNonce(16);
+  const policy = options.tee ? buildAttestationPolicy({ tee: options.tee, attestationPolicy: options.attestationPolicy }) : options.attestationPolicy ?? {};
+  let stopped = false;
+  let failures = 0;
+  let sequence = 0;
+  let latest;
+  let timer;
+  let resolveDone;
+  const done = new Promise((resolve) => {
+    resolveDone = resolve;
+  });
+  const stop = () => {
+    if (stopped) return;
+    stopped = true;
+    if (timer) clearTimeout(timer);
+    resolveDone?.();
+  };
+  const ping = async (context) => {
+    if (stopped || options.signal?.aborted) {
+      throw new Error("TEE attestation heartbeat is stopped");
+    }
+    const nextSequence = sequence + 1;
+    const boundContext = context ?? `${sessionId}:${nextSequence}`;
+    const challenge = createTeeAttestationChallenge(boundContext);
+    const response = await getTeeAttestation.call(sandbox, {
+      attestationNonce: challenge.nonce
+    });
+    const attestation = response?.attestation;
+    if (!attestation) {
+      throw new Error("TEE attestation heartbeat returned no evidence");
+    }
+    const verification = await verifyAttestationAsync(attestation, {
+      ...policy,
+      expectedNonce: challenge.nonce
+    });
+    if (!verification.valid) {
+      throw new Error(`TEE attestation heartbeat verification failed: ${verification.errors.join("; ")}`);
+    }
+    const sample = {
+      sequence: nextSequence,
+      nonce: challenge.nonce,
+      context: boundContext,
+      attestation,
+      verification,
+      checkedAt: /* @__PURE__ */ new Date()
+    };
+    sequence = nextSequence;
+    latest = sample;
+    options.onSuccess?.(sample);
+    return sample;
+  };
+  const schedule = () => {
+    if (stopped || options.signal?.aborted) {
+      stop();
+      return;
+    }
+    timer = setTimeout(() => {
+      void loop();
+    }, intervalMs);
+  };
+  const loop = async () => {
+    try {
+      await ping();
+      schedule();
+    } catch (error) {
+      failures += 1;
+      options.onFailure?.(error);
+      if (options.continueOnFailure) {
+        schedule();
+      } else {
+        stop();
+      }
+    }
+  };
+  options.signal?.addEventListener("abort", stop, { once: true });
+  if (options.immediate === false) {
+    schedule();
+  } else {
+    void loop();
+  }
+  return {
+    stop,
+    ping,
+    get stopped() {
+      return stopped;
+    },
+    get failures() {
+      return failures;
+    },
+    get latest() {
+      return latest;
+    },
+    done
+  };
+}
+function buildSandboxCreateOptions(options) {
+  if (!options.tee && (options.sealed || options.attestationNonce || options.verify)) {
+    throw new Error("TEE options require a tee value");
+  }
+  const shouldGenerateNonce = options.attestationNonce === "auto" || shouldVerifyAttestation(options) && !options.attestationNonce;
+  const attestationNonce = shouldGenerateNonce ? generateAttestationNonce() : options.attestationNonce;
+  if (attestationNonce) {
+    validateAttestationNonce(attestationNonce);
+  }
+  return {
+    name: options.name,
+    environment: options.environment ?? options.image,
+    sshEnabled: options.ssh || void 0,
+    git: options.gitUrl ? {
+      url: options.gitUrl,
+      ref: options.gitRef
+    } : void 0,
+    resources: options.cpu || options.memoryMb || options.diskGb ? {
+      cpuCores: options.cpu,
+      memoryMB: options.memoryMb,
+      diskGB: options.diskGb
+    } : void 0,
+    backend: options.backend ? { type: options.backend } : void 0,
+    confidential: options.tee ? {
+      tee: options.tee,
+      sealed: options.sealed || void 0,
+      attestationNonce,
+      attestationRefresh: Boolean(attestationNonce)
+    } : void 0
+  };
+}
+function shouldVerifyAttestation(options) {
+  return Boolean(options.tee || options.verify);
+}
+function buildAttestationPolicy(options) {
+  if (!options.tee || options.tee === "any") return options.attestationPolicy ?? {};
+  const requestedTypes = acceptedAttestationTypesForTee(options.tee);
+  const acceptedTeeTypes = options.attestationPolicy?.acceptedTeeTypes;
+  if (acceptedTeeTypes?.length && !acceptedTeeTypes.some((type) => requestedTypes.includes(type))) {
+    throw new Error(
+      `TEE attestation policy does not accept requested TEE type ${options.tee}`
+    );
+  }
+  return {
+    ...options.attestationPolicy,
+    acceptedTeeTypes: acceptedTeeTypes?.length ? acceptedTeeTypes.filter((type) => requestedTypes.includes(type)) : requestedTypes
+  };
+}
+function acceptedAttestationTypesForTee(tee) {
+  switch (tee) {
+    case "phala-dstack":
+      return ["tdx", "phala-dstack"];
+    case "gcp":
+      return ["tdx", "sev-snp", "gcp"];
+    case "azure":
+      return ["sev-snp", "azure"];
+    default:
+      return [normalizeTeeType(tee)];
+  }
+}
+function validateAttestationNonce(value) {
+  const normalized = value.trim().toLowerCase().replace(/^0x/, "");
+  if (!/^[0-9a-f]+$/.test(normalized)) {
+    throw new Error("attestation nonce must be hex");
+  }
+  if (normalized.length % 2 !== 0) {
+    throw new Error("attestation nonce must have even hex length");
+  }
+  const bytes = normalized.length / 2;
+  if (bytes < 32 || bytes > 64) {
+    throw new Error(`attestation nonce must be 32-64 bytes, got ${bytes}`);
+  }
+}
+function generateAttestationNonce(bytes = 32) {
+  return Array.from(randomBytes(bytes)).map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function attestationFromMetadata(metadata) {
+  const raw = metadata?.teeAttestationJson;
+  if (typeof raw !== "string" || raw.trim() === "") return void 0;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+}
+
+export {
+  TCloudSandbox,
+  createTeeAttestationChallenge,
+  startTeeAttestationHeartbeat,
+  buildSandboxCreateOptions,
+  shouldVerifyAttestation,
+  generateAttestationNonce
+};

package/dist/{chunk-B22AH4JH.js → chunk-M5K3EFNP.js}

@@ -10,6 +10,8 @@ var PrivateRouter = class {
   usage = /* @__PURE__ */ new Map();
   currentIndex = 0;
   totalRequests = 0;
+  /** Slug of the most-recently-selected operator. Populated on each selectOperator() hit. */
+  _lastSelectedSlug = null;
   constructor(config = {}) {
     this.config = {
       strategy: config.strategy || "round-robin",
@@ -155,6 +157,11 @@ var PrivateRouter = class {
       requestCount: (existing?.requestCount || 0) + 1,
       lastUsedAt: Date.now()
     });
+    this._lastSelectedSlug = op.slug;
+  }
+  /** Slug of the most-recently-selected operator (null before the first call). */
+  get lastSelectedSlug() {
+    return this._lastSelectedSlug;
   }
   getLastUsedOperator() {
     let latest = null;
@@ -212,6 +219,7 @@ var PrivateRouter = class {
 };
 
 // src/client.ts
+var ROTATING_MARKER = "__tcloudRotating";
 var DEFAULT_BASE_URL = "https://router.tangle.tools/v1";
 var SDK_VERSION = "0.4.0";
 async function proxiedFetch(privacy, url, init, streaming) {
@@ -309,6 +317,54 @@ var TCloudClient = class _TCloudClient {
     const baseURL = opts.url.replace(/\/+$/, "") + "/v1";
     return new _TCloudClient({ ...opts.config ?? {}, apiKey: opts.bearer, baseURL });
   }
+  /**
+   * Build a client that rotates which operator serves each call. Mirrors
+   * {@link TCloudClient.shielded} in shape: returns a standard `TCloudClient`
+   * that behaves identically for the OpenAI-compatible surface but
+   * dispatches each chat/completions/embeddings request through a
+   * {@link PrivateRouter} — different operator per call per the chosen
+   * strategy.
+   *
+   * ```ts
+   * const tcloud = TCloudClient.rotating({
+   *   apiKey: process.env.TCLOUD_API_KEY,
+   *   routing: { strategy: 'min-exposure' },
+   * })
+   * await tcloud.ask('hello')
+   * tcloud.getRotationStats() // { callsByOperator: { ... }, currentOperator: '…' }
+   * ```
+   *
+   * Rotation is meaningful only for stateless calls. Sandbox-harness
+   * sessions bind to a single operator for the lifetime of the session;
+   * `rotating()` clients refuse to dispatch them — see {@link bridge}.
+   */
+  static rotating(config = {}) {
+    const routing = config.routing ?? {};
+    const strategy = routing.strategy ?? "min-exposure";
+    const { routing: _omit, ...base } = config;
+    const client = new _TCloudClient(base);
+    const router = new PrivateRouter({
+      strategy,
+      minOperators: routing.minOperators ?? 1,
+      maxRequestsPerOperator: routing.maxRequestsPerOperator,
+      excludeOperators: routing.excludeOperators,
+      preferRegions: routing.preferRegions
+    });
+    if (routing.pool && routing.pool.length > 0) {
+      router.setOperators(routing.pool);
+      client._cachedOperators = routing.pool;
+      client._operatorsCachedAt = Date.now();
+    }
+    ;
+    client.privateRouter = router;
+    Object.defineProperty(client, ROTATING_MARKER, {
+      value: true,
+      enumerable: false,
+      configurable: false,
+      writable: false
+    });
+    return client;
+  }
   constructor(config = {}) {
     this.baseURL = (config.baseURL || DEFAULT_BASE_URL).replace(/\/$/, "");
     this.platformURL = (config.platformURL || DEFAULT_PLATFORM_URL).replace(/\/$/, "");
@@ -624,10 +680,38 @@ var TCloudClient = class _TCloudClient {
    *
    * Sessions persist across process restarts — use the same `resume` id
    * to land on the same CLI conversation (context intact, no replay tax).
+   *
+   * Guard: clients built via {@link TCloudClient.rotating} cannot dispatch
+   * sandbox-harness sessions (rotation rotates per call; a sandbox session
+   * binds to one operator). Attempting `bridge({ harness: 'sandbox' })` on
+   * a rotating client throws.
    */
   bridge(cfg) {
+    if (cfg.harness === "sandbox" && this[ROTATING_MARKER] === true) {
+      throw new Error(
+        "TCloudClient.rotating() cannot dispatch sandbox-harness sessions.\nSandbox sessions bind to a single operator; rotation is meaningful only for\nstateless calls. Use TCloudClient.shielded() + AgentProfile.confidential.tee\nfor privacy-preserving sandbox execution instead."
+      );
+    }
     return new BridgeSession(this, cfg);
   }
+  /**
+   * Rotation stats — populated only on clients created via
+   * {@link TCloudClient.rotating}. Non-rotating clients return an empty
+   * counter and `currentOperator: null`.
+   */
+  getRotationStats() {
+    if (!this.privateRouter) {
+      return { callsByOperator: {}, currentOperator: null };
+    }
+    const callsByOperator = {};
+    for (const row of this.privateRouter.getStats().operatorBreakdown) {
+      callsByOperator[row.slug] = row.requests;
+    }
+    return {
+      callsByOperator,
+      currentOperator: this.privateRouter.lastSelectedSlug
+    };
+  }
   /** Convenience: send a single message and get the text response */
   async ask(message, modelOrOptions) {
     const options = typeof modelOrOptions === "string" ? { model: modelOrOptions } : modelOrOptions;
@@ -1129,6 +1213,8 @@ var BridgeSession = class _BridgeSession {
     this.client = client;
     this.cfg = cfg;
   }
+  client;
+  cfg;
   /** Full chat completion (non-streaming). */
   async chat(options) {
     return this.client.chat({ ...options, bridge: this.cfg });
@@ -1198,6 +1284,7 @@ var TCloudError = class extends Error {
     this.status = status;
     this.name = "TCloudError";
   }
+  status;
 };
 
 export {

package/dist/{chunk-577KIKFA.js → chunk-MB4VK4MM.js}

@@ -1,12 +1,23 @@
 import {
   createShieldedClient,
   generateWallet
-} from "./chunk-A7AEPV2G.js";
+} from "./chunk-4ZUVGKVH.js";
 import {
   TCloudClient
-} from "./chunk-B22AH4JH.js";
+} from "./chunk-M5K3EFNP.js";
 
 // src/index.ts
+import {
+  assertAttestation,
+  createSevSnpHardwareVerifier,
+  createTdxHardwareVerifier,
+  normalizeTeeType,
+  parseAttestation,
+  parseSevSnpReport,
+  toHex,
+  verifyAttestation,
+  verifyAttestationAsync
+} from "@tangle-network/tcloud-attestation";
 var TCloud = class _TCloud extends TCloudClient {
   constructor(config) {
     super(config);
@@ -35,6 +46,21 @@ var TCloud = class _TCloud extends TCloudClient {
   static shielded(config) {
     return createShieldedClient(config);
   }
+  /**
+   * Create a client that rotates operators per call.
+   * See {@link TCloudClient.rotating} for semantics.
+   *
+   * ```ts
+   * const client = TCloud.rotating({
+   *   apiKey: process.env.TCLOUD_API_KEY,
+   *   routing: { strategy: 'min-exposure' },
+   * })
+   * const stats = client.getRotationStats()
+   * ```
+   */
+  static rotating(config) {
+    return TCloudClient.rotating(config);
+  }
   /**
    * Generate a new ephemeral wallet (without creating a client).
    *
@@ -47,5 +73,14 @@ var TCloud = class _TCloud extends TCloudClient {
 };
 
 export {
-  TCloud
+  TCloud,
+  assertAttestation,
+  createSevSnpHardwareVerifier,
+  createTdxHardwareVerifier,
+  normalizeTeeType,
+  parseAttestation,
+  parseSevSnpReport,
+  toHex,
+  verifyAttestation,
+  verifyAttestationAsync
 };