@bnbagent/deploy-provider-bnb 0.3.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@bnbagent/deploy-provider-bnb",
+  "version": "0.3.0",
+  "type": "module",
+  "description": "BNB Chain trial-platform provider for @bnbagent/deploy — deploys agents to the managed free-trial runtime (bnbagent-api) over plain HTTPS: GitHub device-flow login, zip artifact upload, deploy + poll. No cloud credentials of your own.",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@bnbagent/deploy-core": "*"
+  },
+  "devDependencies": {
+    "@bnbagent/deploy-core": "^0.3.0",
+    "@types/bun": "^1.3.0",
+    "typescript": "^5.7.0"
+  }
+}

package/src/api-types.ts

@@ -0,0 +1,147 @@
+/**
+ * The bnbagent-api response shapes this provider depends on — the SINGLE place
+ * the cross-repo contract is written down in code.
+ *
+ * ★ Source of truth: bnbagent-api `docs/client-integration.md` (pinned against
+ *   commit 59cde52, 2026-06-29). There is no shared package or OpenAPI client
+ *   yet, so drift is only caught here: when the platform changes a field, update
+ *   this file (and ideally: the platform starts publishing these types — see
+ *   docs/integration-bnbagent-api.md).
+ *
+ * Extension note: the platform may later deploy to backends other than AWS
+ * (e.g. Azure). This client is coupled to the PLATFORM contract, not to the
+ * backend — the one backend-shaped assumption is the artifact target
+ * architecture, which the platform advertises (see `platform` on the image
+ * artifact response) rather than this client hardcoding it.
+ */
+
+/** POST /v1/auth/device/start */
+export interface DeviceStart {
+  device_code: string;
+  user_code: string;
+  verification_uri: string;
+  expires_in: number;
+  interval: number;
+}
+
+/** POST /v1/auth/device/poll (200) · POST /v1/auth/refresh (200) */
+export interface TokenPair {
+  access_token: string;
+  refresh_token: string;
+  token_type: string;
+  expires_in: number;
+}
+
+/** POST /v1/auth/device/poll (202 pending) */
+export interface DevicePending {
+  status: "authorization_pending" | "slow_down";
+}
+
+/** POST /v1/artifacts/zip (201) */
+export interface ZipArtifactCreated {
+  artifactId: string;
+  uploadUrl: string;
+  method: "PUT";
+}
+
+/** POST /v1/artifacts/image (201) — brokered private repo + short-lived push credential. */
+export interface ImageArtifactCreated {
+  artifactId: string;
+  /** Full repo ref WITHOUT a tag (e.g. `<acct>.dkr.ecr.<region>.amazonaws.com/x/y`). */
+  repository: string;
+  username: string;
+  /** Registry auth token — stdin-only, never argv, never logged. */
+  password: string;
+  registry: string;
+  /** The runtime's image platform (e.g. "linux/arm64") — authoritative, advertised per-artifact. */
+  platform: string;
+  expiresAt: string;
+}
+
+/** POST /v1/agents/:slug/invoke-clients (201) — client_secret is shown ONCE. */
+export interface InvokeClientCreated {
+  client_id: string;
+  client_secret: string;
+  token_url: string;
+  scope: string; // "invoke:<agentId>"
+}
+
+/** GET /v1/agents/:slug/invoke-clients */
+export interface InvokeClientList {
+  clients: Array<{
+    id: string;
+    clientId: string;
+    label: string | null;
+    revokedAt: string | null;
+    createdAt: string;
+  }>;
+}
+
+/** POST /v1/tokens (201) — `token` (bnbk_…) is shown ONCE. */
+export interface ApiTokenCreated {
+  id: string;
+  token: string;
+  prefix: string;
+  scope: string;
+  expires_at: string | null;
+}
+
+/** GET /v1/tokens */
+export interface ApiTokenList {
+  tokens: Array<{ id: string; prefix?: string; scope?: string; created_at?: string; expires_at?: string | null }>;
+}
+
+/** POST /v1/agents/:slug/deployments (202) */
+export interface DeploymentAccepted {
+  deployment_id: string;
+  agent_id: string;
+  protocol: string;
+  status_url: string;
+  invoke_url: string | null;
+}
+
+/** GET /v1/deployments/:id */
+export interface DeploymentStatus {
+  id: string;
+  agent_id: string;
+  agent_slug: string;
+  protocol: string;
+  state: "queued" | "deploying" | "ready" | "failed" | string;
+  invoke_url: string | null;
+  issues?: Array<string | { level?: string; code?: string; message?: string }>;
+}
+
+/** GET /v1/agents/:slug */
+export interface AgentInfo {
+  /** Current production API field. */
+  id?: string;
+  /** Additive snake_case alias returned by newer API versions. */
+  agent_id?: string;
+  slug: string;
+  state: "provisioning" | "ready" | "updating" | "reclaiming" | "deleted" | "failed" | string;
+  protocol: string | null;
+  invoke_url: string | null;
+}
+
+export const agentIdOf = (agent: AgentInfo): string | undefined => agent.agent_id ?? agent.id;
+
+/** GET /v1/account */
+export interface AccountInfo {
+  tenant_id: string;
+  github_user_id: number | string | null;
+  login: string | null;
+  agents: number;
+}
+
+/** GET /v1/account/trial */
+export interface TrialStatus {
+  case: "available" | "active" | "expired";
+  started_at?: string;
+  expires_at?: string;
+  remaining_seconds?: number;
+}
+
+/** GET /v1/campaign (public) */
+export interface CampaignStatus {
+  campaign_active: boolean;
+}

package/src/artifact.ts

@@ -0,0 +1,121 @@
+/**
+ * Ship a zip artifact to the trial platform:
+ * create → PUT bytes (auth-gated blob endpoint) → complete (sha256 integrity).
+ *
+ * The dist directory is zipped VERBATIM (vendored deps included — the managed
+ * runtime never installs), mirroring provider-aws/zip.ts; a ready .zip is
+ * uploaded as-is. Caps: 250 MB compressed (platform + AgentCore hard limit).
+ */
+import { existsSync } from "node:fs";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { basename, join, resolve } from "node:path";
+import type { Context, DeploymentSpec } from "@bnbagent/deploy-core";
+import { assertNoEscapingSymlinks } from "@bnbagent/deploy-core";
+import { authedRequest } from "./client.ts";
+import type { ZipArtifactCreated } from "./api-types.ts";
+
+const ZIP_LIMIT_BYTES = 250 * 1024 * 1024;
+
+export class TrialZipError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TrialZipError";
+  }
+}
+
+export interface ShippedZip {
+  artifactId: string;
+  /** sha256 of the uploaded bytes — the deploy idempotency key's content half. */
+  checksum: string;
+}
+
+/** Build the zip bytes, upload them, and return the verified artifact id + checksum. */
+export async function shipZipArtifact(spec: DeploymentSpec, ctx: Context): Promise<ShippedZip> {
+  const projectDir = resolve(ctx.baseDir, spec.path ?? ".");
+  const distAbs = resolve(projectDir, spec.dist!);
+  if (!existsSync(distAbs)) {
+    throw new TrialZipError(
+      `deploy.dist not found: ${distAbs}\n` +
+        `  \`deploy\` only deploys — build first (Python: \`bnbagent-deploy pack\`; ` +
+        `Node: your build script), then re-run deploy.`,
+    );
+  }
+
+  const staging = await mkdtemp(join(tmpdir(), "bnbagent-bnb-zip-"));
+  try {
+    let zipFile: string;
+    if (distAbs.endsWith(".zip")) {
+      zipFile = distAbs;
+      ctx.logger.step(`Using prebuilt archive ${spec.dist}`);
+      // Recorded exemption: a ready .zip is uploaded AS-IS — the env-file /
+      // escaping-symlink hygiene checks only run when WE build the archive.
+      ctx.logger.warn("Prebuilt archive: bundle hygiene checks (env files, symlinks) are skipped — it ships as-is.");
+    } else {
+      if (spec.entrypoint && !existsSync(join(distAbs, spec.entrypoint))) {
+        throw new TrialZipError(
+          `deploy.entrypoint "${spec.entrypoint}" not found inside deploy.dist (${distAbs}). ` +
+            `Rebuild, or fix the entrypoint path.`,
+        );
+      }
+      ctx.logger.step(`Packaging ${spec.dist} as-is (entry: ${spec.entrypoint})…`);
+      zipFile = join(staging, "bundle.zip");
+      // `zip` dereferences symlinks — a link escaping the dist tree would ship
+      // its target's content to the third-party platform. Reject before zipping.
+      try {
+        await assertNoEscapingSymlinks(distAbs);
+      } catch (e) {
+        throw new TrialZipError((e as Error).message);
+      }
+      await zipDir(distAbs, zipFile, spec.secrets?.envFile && basename(spec.secrets.envFile));
+    }
+
+    const bytes = new Uint8Array(await Bun.file(zipFile).arrayBuffer());
+    if (bytes.byteLength > ZIP_LIMIT_BYTES) {
+      throw new TrialZipError(
+        `The code package is ${(bytes.byteLength / 1024 / 1024).toFixed(0)}MB — the trial platform ` +
+          `caps zip deploys at 250MB compressed.`,
+      );
+    }
+    const checksum = new Bun.CryptoHasher("sha256").update(bytes).digest("hex");
+
+    ctx.logger.info(`Uploading bundle (${(bytes.byteLength / 1024).toFixed(0)} KB) → trial platform…`);
+    const created: ZipArtifactCreated = await authedRequest(ctx, "POST", "/v1/artifacts/zip", { json: {} });
+    // Tens-of-MB body — the default 30s request timeout is too tight for it.
+    await authedRequest(ctx, "PUT", created.uploadUrl, { bytes, timeoutMs: 300_000 });
+    await authedRequest(ctx, "POST", `/v1/artifacts/${created.artifactId}/complete`, {
+      json: { checksum },
+    });
+    ctx.logger.debug(`[bnb] artifact ${created.artifactId} verified (sha256 ${checksum.slice(0, 12)}…)`);
+    return { artifactId: created.artifactId, checksum };
+  } finally {
+    await rm(staging, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Zip a directory's contents at the archive root. Beyond OS/VCS cruft, this
+ * EXCLUDES env files (`.env*`, plus a custom secrets.envFile basename like
+ * "prod.env") and the emitted cognito CDK dir — a stray secret in dist must
+ * never be uploaded to the third-party trial platform. (Secrets travel via
+ * the deploy request's `secrets` field, not the bundle.)
+ */
+async function zipDir(dir: string, outFile: string, envFileBase?: string | false): Promise<void> {
+  const excludes = [
+    ".git/*", "*/.DS_Store", ".DS_Store", ".bnbagent*",
+    "*/__pycache__/*", "__pycache__/*", "*.pyc",
+    ".env*", "*/.env*",
+    ...(envFileBase ? [envFileBase, `*/${envFileBase}`] : []),
+    "cognito-cdk/*",
+  ];
+  const proc = Bun.spawn(["zip", "-r", "-q", "-X", outFile, ".", "-x", ...excludes], {
+    cwd: dir,
+    stdout: "ignore",
+    stderr: "pipe",
+  });
+  const code = await proc.exited;
+  if (code !== 0) {
+    const err = await new Response(proc.stderr).text();
+    throw new TrialZipError(`zip failed (exit ${code}): ${err.trim() || "is the 'zip' command installed?"}`);
+  }
+}

package/src/client.ts

@@ -0,0 +1,258 @@
+/**
+ * Minimal HTTP client for bnbagent-api (docs/client-integration.md in that repo):
+ * bearer injection, one 401→refresh→retry pass (single-use rotating refresh
+ * tokens — the new pair is persisted BEFORE the retry), 429/5xx backoff, and
+ * the platform's uniform error envelope {error:{code,message,request_id}}.
+ *
+ * ★ Never logs request bodies (deploy bodies carry secret values).
+ */
+import type { Context } from "@bnbagent/deploy-core";
+import { loadSession, saveSession, withSessionLock, type Session } from "./session.ts";
+
+/**
+ * Where the trial platform lives: [bnb] apiUrl → BNBAGENT_API_URL. There is
+ * deliberately NO default — a published CLI silently talking to localhost is a
+ * footgun; local platform dev sets BNBAGENT_API_URL=http://localhost:3000.
+ */
+export function apiUrl(ctx: Context): string {
+  const fromSpec = ctx.overrides?.bnb?.apiUrl;
+  const url = (typeof fromSpec === "string" && fromSpec) || process.env.BNBAGENT_API_URL;
+  if (!url) {
+    throw new BnbApiError(
+      0,
+      "config.api_url_missing",
+      "The trial platform endpoint is not configured. Set `[bnb] apiUrl = \"https://…\"` in " +
+        "agent-deploy.toml (or the BNBAGENT_API_URL env var; local platform dev: http://localhost:3000).",
+    );
+  }
+  const clean = url.replace(/\/+$/, "");
+  // Guard against sending session tokens over cleartext to a non-loopback host.
+  if (clean.startsWith("http://") && !/^http:\/\/(localhost|127\.0\.0\.1|\[::1\])(:|\/|$)/.test(clean)) {
+    throw new BnbApiError(
+      0,
+      "config.insecure_api_url",
+      `Refusing to use a non-HTTPS trial API endpoint (${clean}) — session tokens and secrets ` +
+        `would cross the network in cleartext. Use https:// (http:// is allowed only for localhost).`,
+    );
+  }
+  return clean;
+}
+
+/**
+ * Automation/CI bearer: a platform API token (`bnbk_…`, minted with
+ * `bnbagent-deploy token --new`) via BNBAGENT_API_TOKEN. When set it REPLACES
+ * the session entirely — no device flow, no refresh, no session file.
+ */
+export function envApiToken(): string | undefined {
+  const t = process.env.BNBAGENT_API_TOKEN?.trim();
+  return t || undefined;
+}
+
+/** Same-origin test — the bearer is attached to absolute URLs only when they match the platform base. */
+export function sameOrigin(base: string, url: string): boolean {
+  try {
+    return new URL(url).origin === new URL(base).origin;
+  } catch {
+    return false;
+  }
+}
+
+export class BnbApiError extends Error {
+  readonly code: string;
+  readonly status: number;
+  readonly requestId?: string;
+  constructor(status: number, code: string, message: string, requestId?: string) {
+    super(message);
+    this.name = "BnbApiError";
+    this.status = status;
+    this.code = code;
+    this.requestId = requestId;
+  }
+}
+
+interface RequestOptions {
+  /** Raw body bytes (zip upload); `json` wins when both are set. */
+  bytes?: Uint8Array;
+  json?: unknown;
+  headers?: Record<string, string>;
+  /** Return the raw text instead of parsing JSON. */
+  text?: boolean;
+  /** Per-request timeout; default 30s (artifact uploads pass a longer one). */
+  timeoutMs?: number;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+const RETRYABLE = new Set([429, 502, 503, 504]);
+
+/** Unauthenticated request (device flow, /v1/campaign). */
+export async function publicRequest(
+  base: string,
+  method: string,
+  path: string,
+  opts: RequestOptions = {},
+): Promise<any> {
+  return send(base, method, path, undefined, opts);
+}
+
+/**
+ * Authenticated request. Loads the session, attaches the bearer, and on a 401
+ * refreshes ONCE (persisting the rotated pair first) before retrying.
+ */
+export async function authedRequest(
+  ctx: Context,
+  method: string,
+  path: string,
+  opts: RequestOptions = {},
+): Promise<any> {
+  const base = apiUrl(ctx);
+  // CI/automation path: a bnbk_ API token wins over the interactive session.
+  const apiToken = envApiToken();
+  if (apiToken) {
+    try {
+      return await send(base, method, path, apiToken, opts, base);
+    } catch (e) {
+      if (e instanceof BnbApiError && e.status === 401) {
+        throw new BnbApiError(
+          401,
+          "auth.token_invalid",
+          "BNBAGENT_API_TOKEN was rejected (revoked/expired?) — mint a new one: `bnbagent-deploy token --new` (while signed in).",
+        );
+      }
+      throw e;
+    }
+  }
+  let session = await loadSession();
+  if (!session) {
+    throw new BnbApiError(
+      401,
+      "auth.signed_out",
+      "Not signed in — run `bnbagent-deploy login` first (CI: set BNBAGENT_API_TOKEN).",
+    );
+  }
+  // Host-bind the token: never send a session minted against platform A to a
+  // different [bnb] apiUrl (a malicious agent-deploy.toml could otherwise
+  // exfiltrate the bearer + single-use refresh token to an attacker host).
+  if (session.apiUrl && !sameOrigin(session.apiUrl, base)) {
+    throw new BnbApiError(
+      401,
+      "auth.host_mismatch",
+      `Your session was minted against ${session.apiUrl}, but this command targets ${base}. ` +
+        `Refusing to send credentials cross-host — run \`bnbagent-deploy login\` against ${base}.`,
+    );
+  }
+  try {
+    return await send(base, method, path, session.access_token, opts, base);
+  } catch (e) {
+    if (!(e instanceof BnbApiError) || e.status !== 401) throw e;
+    session = await refreshSession(base, session);
+    return send(base, method, path, session.access_token, opts, base);
+  }
+}
+
+/** Exchange the single-use refresh token; persist the rotated pair immediately. */
+async function refreshSession(base: string, session: Session): Promise<Session> {
+  return withSessionLock(async () => {
+    const fresh = await loadSession();
+    if (!fresh || !sameOrigin(fresh.apiUrl, base)) {
+      throw new BnbApiError(401, "auth.expired", "Session expired — run `bnbagent-deploy login` again.");
+    }
+    if (fresh.refresh_token !== session.refresh_token) {
+      return fresh;
+    }
+    let res: any;
+    try {
+      res = await send(base, "POST", "/v1/auth/refresh", undefined, {
+        json: { refresh_token: fresh.refresh_token },
+      });
+    } catch (e) {
+      const detail = e instanceof BnbApiError ? ` (${e.code})` : "";
+      throw new BnbApiError(
+        401,
+        "auth.expired",
+        `Session expired${detail} — run \`bnbagent-deploy login\` again.`,
+      );
+    }
+    const next: Session = { apiUrl: base, access_token: res.access_token, refresh_token: res.refresh_token };
+    await saveSession(next);
+    return next;
+  });
+}
+
+async function send(
+  base: string,
+  method: string,
+  path: string,
+  bearer: string | undefined,
+  opts: RequestOptions,
+  /** When set, a bearer is attached to an absolute `path` only if it is same-origin. */
+  bearerOrigin?: string,
+): Promise<any> {
+  const url = path.startsWith("http") ? path : `${base}${path}`;
+  const headers: Record<string, string> = { ...(opts.headers ?? {}) };
+  // For a relative path the origin is `base`; for an absolute URL (uploadUrl,
+  // status_url) attach the bearer ONLY when it matches the platform origin.
+  const attachBearer = bearer && (!path.startsWith("http") || sameOrigin(bearerOrigin ?? base, url));
+  if (attachBearer) headers.authorization = `Bearer ${bearer}`;
+  let body: string | Uint8Array | undefined;
+  if (opts.json !== undefined) {
+    headers["content-type"] = "application/json";
+    body = JSON.stringify(opts.json);
+  } else if (opts.bytes) {
+    headers["content-type"] ??= "application/zip";
+    body = opts.bytes;
+  }
+
+  const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+  for (let attempt = 1; ; attempt++) {
+    let res: Response;
+    try {
+      res = await fetch(url, { method, headers, body, signal: AbortSignal.timeout(timeoutMs) });
+    } catch (e) {
+      if ((e as Error).name === "TimeoutError") {
+        throw new BnbApiError(
+          0,
+          "network.timeout",
+          `Request to the trial platform timed out after ${timeoutMs / 1000}s (${method} ${path}).`,
+        );
+      }
+      throw new BnbApiError(
+        0,
+        "network.unreachable",
+        `Cannot reach the trial platform at ${base}: ${(e as Error).message}\n` +
+          `  Set the API endpoint via BNBAGENT_API_URL or an [bnb] apiUrl entry in agent-deploy.toml.`,
+      );
+    }
+    // Retry transient statuses only for methods that are safe to replay: GET and
+    // POSTs that carry an Idempotency-Key (deployments). A bare non-idempotent
+    // POST (invoke, artifact create) must NOT be silently re-sent.
+    const idempotent = method === "GET" || method === "DELETE" || "idempotency-key" in headers;
+    if (RETRYABLE.has(res.status) && idempotent && attempt < 3) {
+      await Bun.sleep(attempt * 2000);
+      continue;
+    }
+    if (!res.ok) {
+      let code = `http.${res.status}`;
+      let message = res.statusText || `HTTP ${res.status}`;
+      let requestId: string | undefined;
+      try {
+        const env = (await res.json()) as {
+          error?: string | { code?: string; message?: string; request_id?: string };
+        };
+        if (typeof env.error === "string") {
+          // Device-flow terminal errors use a flat { error: "expired_token" } (OAuth shape).
+          code = env.error;
+          message = env.error.replace(/_/g, " ");
+        } else if (env.error) {
+          code = env.error.code ?? code;
+          message = env.error.message ?? message;
+          requestId = env.error.request_id;
+        }
+      } catch {
+        /* non-JSON error body — keep the status text */
+      }
+      throw new BnbApiError(res.status, code, message, requestId);
+    }
+    return opts.text ? res.text() : res.status === 204 ? undefined : res.json();
+  }
+}