@volcengine/ark-runtime 1.0.0

package/src/config.ts

@@ -0,0 +1,68 @@
+import type { AxiosInstance } from "axios";
+
+export const defaultBaseURL = "https://ark.cn-beijing.volces.com/api/v3";
+export const defaultRegion = "cn-beijing";
+export const defaultEmptyMessagesLimit = 300;
+export const defaultRetryTimes = 2;
+export const defaultTimeoutMs = 10 * 60 * 1000; // 10 min
+export const defaultBatchMaxParallel = 3000;
+
+export const resourceTypeEndpoint = "endpoint";
+export const resourceTypeBot = "bot";
+export const resourceTypePresetEndpoint = "presetendpoint";
+
+export interface ClientConfig {
+  /** API key for authentication (mutually exclusive with ak/sk) */
+  apiKey?: string;
+  /** Access key for AK/SK authentication */
+  ak?: string;
+  /** Secret key for AK/SK authentication */
+  sk?: string;
+  /** Region, defaults to "cn-beijing" */
+  region?: string;
+  /** Base URL for the API, defaults to "https://ark.cn-beijing.volces.com/api/v3" */
+  baseURL?: string;
+  /** Custom axios instance */
+  httpClient?: AxiosInstance;
+  /** Max number of empty SSE messages before error, defaults to 300 */
+  emptyMessagesLimit?: number;
+  /** Number of retry attempts, defaults to 2 */
+  retryTimes?: number;
+  /** Request timeout in milliseconds, defaults to 600000 (10 min) */
+  timeout?: number;
+  /** Max parallel batch requests, defaults to 3000 */
+  batchMaxParallel?: number;
+}
+
+export interface ResolvedConfig {
+  apiKey: string;
+  ak: string;
+  sk: string;
+  region: string;
+  baseURL: string;
+  httpClient?: AxiosInstance;
+  emptyMessagesLimit: number;
+  retryTimes: number;
+  timeout: number;
+  batchMaxParallel: number;
+}
+
+export function resolveConfig(config: ClientConfig): ResolvedConfig {
+  let baseURL = config.baseURL ?? process.env.ARK_BASE_URL ?? defaultBaseURL;
+  if (baseURL.endsWith("/")) {
+    baseURL = baseURL.slice(0, -1);
+  }
+
+  return {
+    apiKey: config.apiKey ?? process.env.ARK_API_KEY ?? "",
+    ak: config.ak ?? "",
+    sk: config.sk ?? "",
+    region: config.region ?? defaultRegion,
+    baseURL,
+    httpClient: config.httpClient,
+    emptyMessagesLimit: config.emptyMessagesLimit ?? defaultEmptyMessagesLimit,
+    retryTimes: config.retryTimes ?? defaultRetryTimes,
+    timeout: config.timeout ?? defaultTimeoutMs,
+    batchMaxParallel: config.batchMaxParallel ?? defaultBatchMaxParallel,
+  };
+}

package/src/encryption/encrypt-chat.ts

@@ -0,0 +1,146 @@
+import { aesGcmEncryptBase64, aesGcmDecryptBase64 } from "./key-agreement";
+import type {
+  ChatCompletionRequest,
+  ChatCompletionResponse,
+  ChatCompletionStreamResponse,
+  ChatCompletionMessage,
+  ChatCompletionMessageContentPart,
+} from "../types/chat-completion";
+
+const AES_KEY_SIZE = 32;
+const AES_NONCE_SIZE = 12;
+
+type TextTransformer = (text: string) => string;
+
+function encryptURL(urlString: string, fn: TextTransformer): string {
+  try {
+    const parsed = new URL(urlString);
+    if (["https:", "http:", "file:", "ftp:"].includes(parsed.protocol)) {
+      // URLs with these protocols are not encrypted
+      return urlString;
+    }
+  } catch {
+    // Not a valid URL with protocol — check for data: scheme
+  }
+  if (urlString.startsWith("data:")) {
+    return fn(urlString);
+  }
+  return urlString;
+}
+
+function processMessageContent(
+  content: string | ChatCompletionMessageContentPart[] | undefined | null,
+  fn: TextTransformer,
+): string | ChatCompletionMessageContentPart[] | undefined | null {
+  if (content == null) return content;
+
+  if (typeof content === "string") {
+    return fn(content);
+  }
+
+  // Array of content parts
+  for (const part of content) {
+    if (part.type === "text" && part.text) {
+      part.text = fn(part.text);
+    }
+    if (part.type === "image_url" && part.image_url?.url) {
+      part.image_url.url = encryptURL(part.image_url.url, fn);
+    }
+  }
+  return content;
+}
+
+/**
+ * Deep-copy a chat completion request (JSON round-trip).
+ */
+export function deepCopyRequest(
+  request: ChatCompletionRequest,
+): ChatCompletionRequest {
+  return JSON.parse(JSON.stringify(request));
+}
+
+/**
+ * Encrypt all text content in a chat completion request.
+ * Modifies the request in place.
+ * Matches Go's `EncryptChatRequest`.
+ */
+export function encryptChatRequest(
+  keyNonce: Buffer,
+  request: ChatCompletionRequest,
+): void {
+  if (keyNonce.length !== AES_KEY_SIZE + AES_NONCE_SIZE) {
+    throw new Error(
+      `keyNonce must be ${AES_KEY_SIZE + AES_NONCE_SIZE} bytes, got ${keyNonce.length}`,
+    );
+  }
+  const key = keyNonce.subarray(0, AES_KEY_SIZE);
+  const nonce = keyNonce.subarray(AES_KEY_SIZE);
+  const fn: TextTransformer = (text) =>
+    aesGcmEncryptBase64(key, nonce, text);
+
+  for (const msg of request.messages ?? []) {
+    if (msg.content != null) {
+      (msg as ChatCompletionMessage).content = processMessageContent(
+        msg.content as string | ChatCompletionMessageContentPart[],
+        fn,
+      ) as typeof msg.content;
+    }
+  }
+}
+
+/**
+ * Decrypt all text content in a chat completion response.
+ * Modifies the response in place.
+ * Matches Go's `DecryptChatResponse`.
+ */
+export function decryptChatResponse(
+  keyNonce: Buffer,
+  response: ChatCompletionResponse,
+): void {
+  if (keyNonce.length !== AES_KEY_SIZE + AES_NONCE_SIZE) {
+    throw new Error(
+      `keyNonce must be ${AES_KEY_SIZE + AES_NONCE_SIZE} bytes, got ${keyNonce.length}`,
+    );
+  }
+  const key = keyNonce.subarray(0, AES_KEY_SIZE);
+  const nonce = keyNonce.subarray(AES_KEY_SIZE);
+  const fn: TextTransformer = (text) =>
+    aesGcmDecryptBase64(key, nonce, text);
+
+  for (const choice of response.choices ?? []) {
+    if (choice.finish_reason === "content_filter") continue;
+    if (choice.message?.content != null) {
+      choice.message.content = processMessageContent(
+        choice.message.content as string | ChatCompletionMessageContentPart[],
+        fn,
+      ) as typeof choice.message.content;
+    }
+  }
+}
+
+/**
+ * Decrypt delta content in a streaming chat completion chunk.
+ * Modifies the response in place.
+ * Matches Go's `DecryptChatStreamResponse`.
+ */
+export function decryptChatStreamResponse(
+  keyNonce: Buffer,
+  response: ChatCompletionStreamResponse,
+): void {
+  if (keyNonce.length !== AES_KEY_SIZE + AES_NONCE_SIZE) {
+    throw new Error(
+      `keyNonce must be ${AES_KEY_SIZE + AES_NONCE_SIZE} bytes, got ${keyNonce.length}`,
+    );
+  }
+  const key = keyNonce.subarray(0, AES_KEY_SIZE);
+  const nonce = keyNonce.subarray(AES_KEY_SIZE);
+  const fn: TextTransformer = (text) =>
+    aesGcmDecryptBase64(key, nonce, text);
+
+  for (const choice of response.choices ?? []) {
+    if (choice.finish_reason === "content_filter") continue;
+    if (choice.delta?.content && typeof choice.delta.content === "string") {
+      choice.delta.content = fn(choice.delta.content);
+    }
+  }
+}

package/src/encryption/index.ts

@@ -0,0 +1,21 @@
+export {
+  KeyAgreementClient,
+  E2eeClient,
+  aesGcmEncrypt,
+  aesGcmDecrypt,
+  aesGcmEncryptBase64,
+  aesGcmDecryptBase64,
+  getCertInfo,
+  checkIsModeAICC,
+  loadLocalCertificate,
+  saveToLocalCertificate,
+} from "./key-agreement";
+
+export type { EncryptInfo } from "./key-agreement";
+
+export {
+  encryptChatRequest,
+  decryptChatResponse,
+  decryptChatStreamResponse,
+  deepCopyRequest,
+} from "./encrypt-chat";

package/src/encryption/key-agreement.ts

@@ -0,0 +1,270 @@
+import * as crypto from "crypto";
+import * as fs from "fs";
+import * as path from "path";
+import * as os from "os";
+
+const AES_KEY_SIZE = 32;
+const AES_NONCE_SIZE = 12;
+
+export interface EncryptInfo {
+  version?: string;
+  ring_id?: string;
+  key_id?: string;
+  expire_time: number;
+}
+
+const CIPHER_VERSION_AICC_V01 = "AICCv01";
+
+/**
+ * Key agreement client using ECIES (P-256 / prime256v1).
+ * Ports the Go `KeyAgreementClient` from `pkg/encryption/kaMgr.go`.
+ */
+export class KeyAgreementClient {
+  private serverPublicKey: crypto.KeyObject;
+
+  constructor(pemCert: string) {
+    const x509 = new crypto.X509Certificate(pemCert);
+    this.serverPublicKey = x509.publicKey;
+  }
+
+  /**
+   * Generate ephemeral ECIES key pair and derive shared secret.
+   * Returns [keyNonce (AES key + nonce), sessionToken (base64)].
+   */
+  generateECIESKeyPair(): [Buffer, string] {
+    // Generate ephemeral EC key pair on prime256v1
+    const ecdh = crypto.createECDH("prime256v1");
+    ecdh.generateKeys();
+
+    // Get server public key in uncompressed format
+    const serverPubKeyDer = this.serverPublicKey.export({
+      type: "spki",
+      format: "der",
+    });
+    // Extract raw public key from SPKI DER
+    const serverPubKey = extractRawPublicKeyFromSPKI(serverPubKeyDer);
+
+    // Compute shared secret (ECDH)
+    const sharedSecret = ecdh.computeSecret(serverPubKey);
+
+    // Derive key material via HKDF (SHA-256, no salt, no info)
+    const keyMaterial = hkdfExpand(sharedSecret, AES_KEY_SIZE + AES_NONCE_SIZE);
+
+    // Session token is the uncompressed ephemeral public key, base64-encoded
+    const sessionToken = ecdh.getPublicKey("base64");
+
+    return [keyMaterial, sessionToken];
+  }
+}
+
+/**
+ * Extract raw public key bytes from SPKI DER encoding for EC keys.
+ * The uncompressed point is at the end of the SPKI structure.
+ */
+function extractRawPublicKeyFromSPKI(spkiDer: Buffer): Buffer {
+  // For P-256 uncompressed, the public key is 65 bytes (0x04 || X || Y)
+  // SPKI adds algorithm identifiers at the beginning
+  // The bitstring containing the public key is the last part
+  // For P-256 SPKI: the raw key starts at byte 26 (total = 91 bytes)
+  const uncompressedKeyLen = 65;
+  if (spkiDer.length >= uncompressedKeyLen) {
+    return spkiDer.subarray(spkiDer.length - uncompressedKeyLen);
+  }
+  return spkiDer;
+}
+
+/**
+ * HKDF extract + expand (SHA-256) with no salt and no info.
+ * Matches Go's `deriveKeyBasic`.
+ *
+ * The Go code uses ECDHMarshalBinary which is just the X coordinate of the shared point.
+ * However, Node's ECDH.computeSecret already returns the X coordinate by default.
+ */
+function hkdfExpand(ikm: Buffer, length: number): Buffer {
+  // Use Node.js built-in hkdfSync (available since Node 15+)
+  const derivedKey = crypto.hkdfSync(
+    "sha256",
+    ikm,
+    Buffer.alloc(0), // no salt → use all-zero salt internally
+    Buffer.alloc(0), // no info
+    length,
+  );
+  return Buffer.from(derivedKey);
+}
+
+/**
+ * AES-256-GCM encryption.
+ */
+export function aesGcmEncrypt(
+  key: Buffer,
+  nonce: Buffer,
+  plaintext: Buffer,
+): Buffer {
+  const cipher = crypto.createCipheriv("aes-256-gcm", key, nonce);
+  const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  return Buffer.concat([encrypted, tag]);
+}
+
+/**
+ * AES-256-GCM decryption.
+ */
+export function aesGcmDecrypt(
+  key: Buffer,
+  nonce: Buffer,
+  ciphertext: Buffer,
+): Buffer {
+  const tagLength = 16;
+  const encrypted = ciphertext.subarray(0, ciphertext.length - tagLength);
+  const tag = ciphertext.subarray(ciphertext.length - tagLength);
+  const decipher = crypto.createDecipheriv("aes-256-gcm", key, nonce);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(encrypted), decipher.final()]);
+}
+
+/**
+ * Encrypt plaintext string → base64 ciphertext using AES-GCM.
+ */
+export function aesGcmEncryptBase64(
+  key: Buffer,
+  nonce: Buffer,
+  plaintext: string,
+): string {
+  const encrypted = aesGcmEncrypt(key, nonce, Buffer.from(plaintext, "utf-8"));
+  return encrypted.toString("base64");
+}
+
+/**
+ * Decrypt base64 ciphertext → plaintext string using AES-GCM.
+ */
+export function aesGcmDecryptBase64(
+  key: Buffer,
+  nonce: Buffer,
+  ciphertext: string,
+): string {
+  const cipherBuf = Buffer.from(ciphertext, "base64");
+  const decrypted = aesGcmDecrypt(key, nonce, cipherBuf);
+  return decrypted.toString("utf-8");
+}
+
+/**
+ * Extract ring ID, key ID, and expiry from a PEM certificate.
+ * Matches Go's `GetCertInfo`.
+ */
+export function getCertInfo(
+  certPem: string,
+): { ringId: string; keyId: string; expireTime: number } {
+  try {
+    const x509 = new crypto.X509Certificate(certPem);
+    const altNames = x509.subjectAltName ?? "";
+    // Parse DNS:ring.xxx, DNS:key.yyy from subject alt names
+    const dnsNames: string[] = [];
+    for (const part of altNames.split(",")) {
+      const trimmed = part.trim();
+      if (trimmed.startsWith("DNS:")) {
+        dnsNames.push(trimmed.substring(4));
+      }
+    }
+    const expireTime = Math.floor(new Date(x509.validTo).getTime() / 1000);
+    if (
+      dnsNames.length > 1 &&
+      dnsNames[0].startsWith("ring.") &&
+      dnsNames[1].startsWith("key.")
+    ) {
+      return {
+        ringId: dnsNames[0].substring(5),
+        keyId: dnsNames[1].substring(4),
+        expireTime,
+      };
+    }
+    return { ringId: "", keyId: "", expireTime };
+  } catch {
+    return { ringId: "", keyId: "", expireTime: 0 };
+  }
+}
+
+/**
+ * Check if AICC encryption mode is enabled via environment variable.
+ */
+export function checkIsModeAICC(): boolean {
+  return process.env.VOLC_ARK_ENCRYPTION === "AICC";
+}
+
+/**
+ * Load locally cached certificate for a model.
+ * Matches Go's `LoadLocalCertificate`.
+ */
+export function loadLocalCertificate(model: string): string | null {
+  if (!model || /[/\\:..]/.test(model)) return null;
+  const dir = path.join(os.homedir(), ".ark", "certificates");
+  const certPath = path.join(dir, `${model}.pem`);
+  try {
+    const stat = fs.statSync(certPath);
+    const age = Date.now() - stat.mtimeMs;
+    if (age > 14 * 24 * 60 * 60 * 1000) {
+      fs.unlinkSync(certPath);
+      return null;
+    }
+    const certPem = fs.readFileSync(certPath, "utf-8");
+    const { ringId, keyId } = getCertInfo(certPem);
+    const aiccEnabled = checkIsModeAICC();
+    if ((ringId === "" || keyId === "") && !aiccEnabled) return certPem;
+    if (ringId !== "" && keyId !== "" && aiccEnabled) return certPem;
+    fs.unlinkSync(certPath);
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Save certificate PEM to local cache.
+ * Matches Go's `SaveToLocalCertificate`.
+ */
+export function saveToLocalCertificate(
+  model: string,
+  certPem: string,
+): void {
+  if (!model || /[/\\:..]/.test(model)) return;
+  const dir = path.join(os.homedir(), ".ark", "certificates");
+  fs.mkdirSync(dir, { recursive: true });
+  const certPath = path.join(dir, `${model}.pem`);
+  fs.writeFileSync(certPath, certPem, "utf-8");
+}
+
+/**
+ * E2EE client — manages certificate + key agreement + encrypt info.
+ * Matches Go's `E2eeClient`.
+ */
+export class E2eeClient {
+  private certificate: string;
+  private cipher: KeyAgreementClient;
+  private info: EncryptInfo;
+  readonly isAICC: boolean;
+
+  constructor(certificate: string) {
+    this.certificate = certificate;
+    this.cipher = new KeyAgreementClient(certificate);
+    const { ringId, keyId, expireTime } = getCertInfo(certificate);
+    this.info = { expire_time: expireTime };
+    this.isAICC = false;
+    if (ringId && keyId) {
+      this.info.version = CIPHER_VERSION_AICC_V01;
+      this.info.ring_id = ringId;
+      this.info.key_id = keyId;
+      this.isAICC = true;
+    }
+  }
+
+  generateECIESKeyPair(): [Buffer, string] {
+    return this.cipher.generateECIESKeyPair();
+  }
+
+  getEncryptInfo(): string {
+    return JSON.stringify(this.info);
+  }
+
+  getExpireTime(): number {
+    return this.info.expire_time;
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+export { ArkRuntimeClient } from "./client";
+export type { ClientConfig } from "./config";
+export * from "./types";
+export * from "./utils/retry";
+export * from "./utils/sse-decoder";
+export * from "./utils/stream-reader";
+export * from "./utils/breaker";
+export * from "./utils/breaker-provider";
+export * from "./utils/request-id";
+export * from "./encryption";

package/src/types/ark.d.ts

@@ -0,0 +1,9 @@
+declare module "@volcengine/ark" {
+  export class ARKClient {
+    constructor(opts: any);
+    send<T = any>(command: any): Promise<T>;
+  }
+  export class GetApiKeyCommand {
+    constructor(opts: any);
+  }
+}

package/src/types/bot.ts

@@ -0,0 +1,127 @@
+import type { Usage, HttpHeaders } from "./common";
+import type {
+  ChatCompletionMessage,
+  ChatCompletionChoice,
+  ChatCompletionStreamChoice,
+  Tool,
+  ToolChoice,
+  StreamOptions,
+  ResponseFormat,
+  Thinking,
+} from "./chat-completion";
+
+export interface BotChatCompletionRequest {
+  bot_id?: string;
+  model: string;
+  messages: ChatCompletionMessage[];
+  max_tokens?: number;
+  temperature?: number;
+  top_p?: number;
+  stream?: boolean;
+  stop?: string[];
+  frequency_penalty?: number;
+  logit_bias?: Record<string, number>;
+  logprobs?: boolean;
+  top_logprobs?: number;
+  user?: string;
+  function_call?: unknown;
+  tools?: Tool[];
+  tool_choice?: string | ToolChoice;
+  stream_options?: StreamOptions;
+  presence_penalty?: number;
+  repetition_penalty?: number;
+  n?: number;
+  response_format?: ResponseFormat;
+  thinking?: Thinking;
+  metadata?: Record<string, unknown>;
+}
+
+export interface BotActionUsage {
+  name: string;
+  prompt_tokens?: string;
+  completion_tokens?: number;
+  total_tokens?: number;
+  search_count?: number;
+  action_name?: string;
+  count?: number;
+}
+
+export interface BotModelUsage extends Usage {
+  name: string;
+}
+
+export interface BotToolDetail {
+  name: string;
+  input: unknown;
+  output: unknown;
+  created_at: number;
+  completed_at: number;
+}
+
+export interface BotActionDetail {
+  name: string;
+  count: number;
+  tool_details?: BotToolDetail[];
+}
+
+export interface BotUsage {
+  model_usage?: BotModelUsage[];
+  action_usage?: BotActionUsage[];
+  action_details?: BotActionDetail[];
+}
+
+export interface BotCoverImage {
+  url?: string;
+  width?: number;
+  height?: number;
+}
+
+export interface BotChatResultReference {
+  url?: string;
+  logo_url?: string;
+  mobile_url?: string;
+  site_name?: string;
+  title?: string;
+  cover_image?: BotCoverImage;
+  summary?: string;
+  publish_time?: string;
+  collection_name?: string;
+  project?: string;
+  doc_id?: string;
+  doc_name?: string;
+  doc_type?: string;
+  doc_title?: string;
+  chunk_id?: string;
+  chunk_title?: string;
+  page_nums?: string;
+  origin_text_token_len?: number;
+  file_name?: string;
+  extra?: Record<string, unknown>;
+}
+
+export interface BotChatCompletionResponse {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  service_tier?: string;
+  choices: ChatCompletionChoice[];
+  usage: Usage;
+  metadata?: Record<string, unknown>;
+  bot_usage?: BotUsage;
+  references?: BotChatResultReference[];
+  headers?: HttpHeaders;
+}
+
+export interface BotChatCompletionStreamResponse {
+  id: string;
+  object: string;
+  created: number;
+  model: string;
+  service_tier?: string;
+  choices: ChatCompletionStreamChoice[];
+  usage?: Usage;
+  metadata?: Record<string, unknown>;
+  bot_usage?: BotUsage;
+  references?: BotChatResultReference[];
+}