@ciphyrshq/sdk 2.6.0

package/src/client.js

@@ -0,0 +1,973 @@
+import {
+  CiphyrsError,
+  CiphyrsAuthError,
+  CiphyrsPermissionError,
+  CiphyrsNotFoundError,
+  CiphyrsRateLimitError,
+  CiphyrsTimeoutError,
+  CiphyrsJobTimeoutError,
+} from './errors.js';
+
+const DEFAULT_BASE_URL = 'https://www.ciphyrs.com';
+const DASH_BASE_URL    = 'https://www.ciphyrs.com';
+
+const RETRYABLE_STATUSES = new Set([429, 500, 502, 503, 504]);
+const MAX_RETRIES = 3;
+const BASE_DELAY_MS = 500;
+
+// ── Internal HTTP helper with auto-retry ────────────────────────────────────────
+async function request(url, { method = 'GET', headers = {}, body, timeout = 10_000, maxRetries = MAX_RETRIES } = {}) {
+  let lastErr;
+
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    let res;
+    try {
+      res = await fetch(url, {
+        method,
+        signal:  AbortSignal.timeout(timeout),
+        headers: { 'Content-Type': 'application/json', ...headers },
+        body:    body !== undefined ? JSON.stringify(body) : undefined,
+      });
+    } catch (err) {
+      if (err.name === 'TimeoutError' || err.name === 'AbortError') {
+        lastErr = new CiphyrsTimeoutError();
+        if (attempt < maxRetries) { await sleep(backoff(attempt)); continue; }
+        throw lastErr;
+      }
+      lastErr = new CiphyrsError(err.message);
+      if (attempt < maxRetries) { await sleep(backoff(attempt)); continue; }
+      throw lastErr;
+    }
+
+    const data = await res.json().catch(() => ({ error: res.statusText }));
+
+    if (!res.ok) {
+      const msg = data?.error || `Request failed (${res.status})`;
+
+      // Retry on transient errors
+      if (RETRYABLE_STATUSES.has(res.status) && attempt < maxRetries) {
+        const retryAfter = res.headers.get('retry-after');
+        const delay = retryAfter ? parseInt(retryAfter) * 1000 : backoff(attempt);
+        await sleep(delay);
+        continue;
+      }
+
+      if (res.status === 401) throw new CiphyrsAuthError(msg);
+      if (res.status === 403) throw new CiphyrsPermissionError(msg);
+      if (res.status === 404) throw new CiphyrsNotFoundError(msg);
+      if (res.status === 429) throw new CiphyrsRateLimitError(msg, { retryAfter: res.headers.get('retry-after') });
+      throw new CiphyrsError(msg, { status: res.status });
+    }
+
+    return data;
+  }
+
+  throw lastErr || new CiphyrsError('Request failed after retries');
+}
+
+function backoff(attempt) {
+  return BASE_DELAY_MS * Math.pow(2, attempt) + Math.random() * 200;
+}
+
+function sleep(ms) {
+  return new Promise(r => setTimeout(r, ms));
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ScanResource — mask / restore / async jobs
+// Used by: developers integrating Ciphyrs into their LLM pipelines
+// ─────────────────────────────────────────────────────────────────────────────
+class ScanResource {
+  #headers; #base; #timeout;
+
+  constructor(headers, base, timeout) {
+    this.#headers = headers;
+    this.#base    = base;
+    this.#timeout = timeout;
+  }
+
+  /**
+   * Mask PII in text synchronously.
+   * Returns the masked text + a sessionId to pass to restore() later.
+   */
+  async mask(text, {
+    sessionId, entities, source = 'PROMPT',
+    surface = 'sdk', llmProvider,
+  } = {}) {
+    const d = await request(`${this.#base}/v1/scan/mask`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { text, session_id: sessionId, entities, source, surface, llm_provider: llmProvider },
+    });
+    return {
+      maskedText:    d.masked_text,
+      sessionId:     d.session_id,
+      entitiesFound: d.entities_found,
+      entitySummary: d.entity_summary,
+    };
+  }
+
+  /**
+   * Submit a mask job asynchronously — returns a jobId immediately (202).
+   * Poll getJob() or use waitForJob() to retrieve the result.
+   */
+  async maskAsync(text, {
+    sessionId, entities, source = 'PROMPT',
+    surface = 'sdk', llmProvider, webhookUrl,
+  } = {}) {
+    const d = await request(`${this.#base}/v1/scan/mask/async`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: {
+        text, session_id: sessionId, entities, source, surface,
+        llm_provider: llmProvider, webhook_url: webhookUrl,
+      },
+    });
+    return { jobId: d.job_id, sessionId: d.session_id, status: d.status };
+  }
+
+  /** Poll for an async job result. */
+  async getJob(jobId) {
+    const d = await request(`${this.#base}/v1/scan/jobs/${encodeURIComponent(jobId)}`, {
+      headers: this.#headers, timeout: this.#timeout,
+    });
+    return {
+      jobId:         d.job_id,
+      status:        d.status,         // 'queued' | 'processing' | 'done' | 'failed'
+      sessionId:     d.session_id,
+      maskedText:    d.masked_text,
+      entitiesFound: d.entities_found,
+      entitySummary: d.entity_summary,
+      latencyMs:     d.latency_ms,
+      error:         d.error,
+    };
+  }
+
+  /**
+   * Wait for an async job to finish, polling automatically.
+   * Throws CiphyrsJobTimeoutError if it doesn't complete within timeoutMs.
+   */
+  async waitForJob(jobId, { pollIntervalMs = 500, timeoutMs = 60_000 } = {}) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const job = await this.getJob(jobId);
+      if (job.status === 'done' || job.status === 'failed') return job;
+      await new Promise(r => setTimeout(r, pollIntervalMs));
+    }
+    throw new CiphyrsJobTimeoutError(jobId, timeoutMs);
+  }
+
+  /**
+   * Restore original PII values from a masked text using the session vault.
+   * @param {string} maskedText — The masked text containing placeholder tokens.
+   * @param {string} sessionId  — The session ID from the original mask call.
+   * @param {object} [opts]
+   * @param {boolean} [opts.purge=false] — Delete tokens from vault after restore.
+   */
+  async restore(maskedText, sessionId, { purge = false } = {}) {
+    const d = await request(`${this.#base}/v1/scan/restore`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { text: maskedText, session_id: sessionId, purge },
+    });
+    return { restoredText: d.restored_text, tokensRestored: d.tokens_restored, purged: d.purged };
+  }
+
+  /**
+   * High-level wrapper for the mask → LLM call → restore round-trip.
+   *
+   * The #1 bug we see in customer integrations is "I called mask() and
+   * sent the masked text to my LLM, but my user is seeing [PERSON_1] in
+   * the response" — they forgot the restore() step. protect() makes this
+   * impossible to get wrong.
+   *
+   * @param {string} userInput  — Raw text from your end-user.
+   * @param {(masked: string, ctx: { sessionId: string, entitiesFound: any[] }) => Promise<string>} llmCall
+   *        Async function that calls your LLM with the masked text and
+   *        returns the LLM's response (a string).
+   * @param {object} [opts]
+   * @param {string}  [opts.sessionId]   — Reuse a vault session across calls.
+   * @param {string[]}[opts.entities]    — Entity types to mask (defaults to all).
+   * @param {string}  [opts.source='PROMPT']
+   * @param {string}  [opts.surface='sdk']
+   * @param {string}  [opts.llmProvider]
+   * @param {boolean} [opts.purge=true]  — Flush vault entries after restore.
+   *                                       Defaults to true (data minimisation);
+   *                                       set false to keep the session alive
+   *                                       for follow-up turns in a conversation.
+   * @returns {Promise<{
+   *   output: string,            // Unmasked LLM response (return THIS to the user)
+   *   maskedInput: string,       // What the LLM actually saw (audit)
+   *   maskedOutput: string,      // What the LLM returned, before unmask (audit)
+   *   sessionId: string,         // Vault session id
+   *   entitiesFound: any[],      // PII entities masked in the input
+   *   tokensRestored: number     // How many placeholders were unmasked in the output
+   * }>}
+   *
+   * @example
+   *   const result = await client.scan.protect(
+   *     userMessage,
+   *     async (masked) => {
+   *       const r = await openai.chat.completions.create({
+   *         model: 'gpt-4o',
+   *         messages: [{ role: 'user', content: masked }],
+   *       });
+   *       return r.choices[0].message.content;
+   *     }
+   *   );
+   *   res.send(result.output);  // → "Hello John, ..." not "Hello [PERSON_1], ..."
+   */
+  async protect(userInput, llmCall, opts = {}) {
+    if (typeof userInput !== 'string') {
+      throw new TypeError('protect: userInput must be a string');
+    }
+    if (typeof llmCall !== 'function') {
+      throw new TypeError('protect: llmCall must be an async function (masked, ctx) => Promise<string>');
+    }
+    const { purge = true, ...maskOpts } = opts;
+
+    // 1. Mask
+    const m = await this.mask(userInput, maskOpts);
+
+    // 2. Call the customer's LLM with the masked text
+    let llmResponse;
+    try {
+      llmResponse = await llmCall(m.maskedText, {
+        sessionId: m.sessionId,
+        entitiesFound: m.entitiesFound,
+      });
+    } catch (err) {
+      // Customer's LLM failed — flush the vault so we don't leak the session
+      this.restore('', m.sessionId, { purge: true }).catch(() => {});
+      throw err;
+    }
+    if (typeof llmResponse !== 'string') {
+      throw new TypeError(
+        'protect: llmCall must return a string (the LLM response). ' +
+        'Got ' + typeof llmResponse + '. Extract the text field from your provider response object first.'
+      );
+    }
+
+    // 3. Restore — and purge by default
+    const r = await this.restore(llmResponse, m.sessionId, { purge });
+
+    return {
+      output:         r.restoredText,
+      maskedInput:    m.maskedText,
+      maskedOutput:   llmResponse,
+      sessionId:      m.sessionId,
+      entitiesFound:  m.entitiesFound,
+      tokensRestored: r.tokensRestored,
+    };
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// GuardResource — V58 inline allow/block decision for agent runtime
+// ─────────────────────────────────────────────────────────────────────────────
+//
+// The "Datadog APM auto-instrument" equivalent for security: customers wrap
+// their LLM calls with check() and it returns allow / block / review in
+// <50ms. The whole V58 pitch lives here.
+class GuardResource {
+  #headers; #base; #timeout;
+  constructor(headers, base, timeout) {
+    this.#headers = headers; this.#base = base; this.#timeout = timeout;
+  }
+
+  /**
+   * Synchronous attack check. Returns { decision, detections, ... }.
+   *
+   * @param {object} params
+   * @param {string} [params.input]   — Text from your end-user.
+   * @param {string} [params.output]  — Optional: agent's output (output-side checks).
+   * @param {string} [params.agentName]
+   * @param {string} [params.traceId]
+   * @param {string} [params.spanId]
+   * @param {string} [params.sessionId]
+   * @param {string} [params.userId]  — Hashed before storage; never raw.
+   * @param {string} [params.operationName]
+   * @param {string} [params.policyOverride] — block_attacks | block_critical | review | observe
+   *
+   * @example
+   *   const guard = await client.guard.check({
+   *     input: userMessage,
+   *     agentName: 'support-bot',
+   *     userId: req.user.id,
+   *   });
+   *   if (guard.decision === 'block') return res.status(400).send({ error: guard.reason });
+   *   const llmReply = await openai.chat.completions.create({ ... });
+   */
+  async check({
+    input, output, agentName, traceId, spanId, sessionId,
+    userId, operationName, policyOverride,
+  } = {}) {
+    return request(`${this.#base}/v1/guard/check`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: {
+        input, output,
+        agent_name: agentName,
+        trace_id: traceId,
+        span_id: spanId,
+        session_id: sessionId,
+        user_id: userId,
+        operation_name: operationName,
+        policy_override: policyOverride,
+      },
+    });
+  }
+
+  /**
+   * One-shot wrapper: check input, if allowed call your LLM, then check
+   * output, then return. Matches the protect() pattern but for blocking.
+   *
+   * @example
+   *   const result = await client.guard.wrap(userMessage, async (input) => {
+   *     return await openai.chat.completions.create({...}).choices[0].message.content;
+   *   });
+   *   if (result.blocked) return res.status(400).send({ error: result.reason });
+   *   res.send(result.output);
+   */
+  async wrap(userInput, llmCall, opts = {}) {
+    if (typeof llmCall !== 'function') {
+      throw new TypeError('guard.wrap: llmCall must be a function');
+    }
+    // 1. Pre-check input
+    const inGuard = await this.check({ ...opts, input: userInput });
+    if (inGuard.decision === 'block') {
+      return { blocked: true, reason: inGuard.reason, decision: inGuard.decision,
+        detections: inGuard.detections, decision_id: inGuard.decision_id };
+    }
+    // 2. Call the customer's LLM
+    const llmResponse = await llmCall(userInput);
+    if (typeof llmResponse !== 'string') {
+      throw new TypeError('guard.wrap: llmCall must return a string');
+    }
+    // 3. Post-check output
+    const outGuard = await this.check({ ...opts, input: userInput, output: llmResponse });
+    if (outGuard.decision === 'block') {
+      return { blocked: true, reason: outGuard.reason, decision: outGuard.decision,
+        detections: outGuard.detections, decision_id: outGuard.decision_id,
+        output: null };   // never leak the blocked output
+    }
+    return { blocked: false, output: llmResponse, decision: outGuard.decision,
+      detections: outGuard.detections, decision_id: outGuard.decision_id };
+  }
+
+  async getPolicy() {
+    return request(`${this.#base}/v1/guard/policy`, { headers: this.#headers, timeout: this.#timeout });
+  }
+  async setPolicy(policyMode) {
+    return request(`${this.#base}/v1/guard/policy`, {
+      method: 'PUT', headers: this.#headers, timeout: this.#timeout,
+      body: { policy_mode: policyMode },
+    });
+  }
+  async decisions({ limit, decision } = {}) {
+    const q = new URLSearchParams();
+    if (limit) q.set('limit', String(limit));
+    if (decision) q.set('decision', decision);
+    const qs = q.toString() ? `?${q.toString()}` : '';
+    return request(`${this.#base}/v1/guard/decisions${qs}`, { headers: this.#headers, timeout: this.#timeout });
+  }
+  async stats({ days = 7 } = {}) {
+    return request(`${this.#base}/v1/guard/stats?days=${days}`, { headers: this.#headers, timeout: this.#timeout });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// SecurityResource — V55-V59 detections, rules, canaries, intel, marketplace
+// ─────────────────────────────────────────────────────────────────────────────
+class SecurityResource {
+  #headers; #base; #timeout;
+  constructor(headers, base, timeout) {
+    this.#headers = headers; this.#base = base; this.#timeout = timeout;
+  }
+
+  // ── Detections (V55) ──────────────────────────────────────────────
+  async listDetections(params = {}) {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) if (v != null) q.set(k, String(v));
+    const qs = q.toString() ? `?${q.toString()}` : '';
+    return request(`${this.#base}/v1/security/detections${qs}`, { headers: this.#headers, timeout: this.#timeout });
+  }
+  async detectionSummary({ days = 30 } = {}) {
+    return request(`${this.#base}/v1/security/detections/summary?days=${days}`, { headers: this.#headers, timeout: this.#timeout });
+  }
+  async detectionTimeseries({ days = 7 } = {}) {
+    return request(`${this.#base}/v1/security/detections/timeseries?days=${days}`, { headers: this.#headers, timeout: this.#timeout });
+  }
+  async detectionsByTrace(traceId) {
+    return request(`${this.#base}/v1/security/detections/by-trace/${encodeURIComponent(traceId)}`,
+      { headers: this.#headers, timeout: this.#timeout });
+  }
+  async detectionContext(detectionId) {
+    return request(`${this.#base}/v1/security/detections/${encodeURIComponent(detectionId)}/context`,
+      { headers: this.#headers, timeout: this.#timeout });
+  }
+  async setDetectionStatus(id, status, note) {
+    return request(`${this.#base}/v1/security/detections/${encodeURIComponent(id)}/disposition`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { status, note },
+    });
+  }
+
+  // ── Custom rules (V56) ────────────────────────────────────────────
+  async listRules() {
+    return request(`${this.#base}/v1/security/rules`, { headers: this.#headers, timeout: this.#timeout });
+  }
+  async createRule(rule) {
+    return request(`${this.#base}/v1/security/rules`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout, body: rule,
+    });
+  }
+  async updateRule(id, rule) {
+    return request(`${this.#base}/v1/security/rules/${encodeURIComponent(id)}`, {
+      method: 'PATCH', headers: this.#headers, timeout: this.#timeout, body: rule,
+    });
+  }
+  async deleteRule(id) {
+    return request(`${this.#base}/v1/security/rules/${encodeURIComponent(id)}`, {
+      method: 'DELETE', headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  // ── Canaries (V59) ─────────────────────────────────────────────────
+  async listCanaries() {
+    return request(`${this.#base}/v1/security/canaries`, { headers: this.#headers, timeout: this.#timeout });
+  }
+  async createCanary(canary) {
+    return request(`${this.#base}/v1/security/canaries`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout, body: canary,
+    });
+  }
+  async deleteCanary(id) {
+    return request(`${this.#base}/v1/security/canaries/${encodeURIComponent(id)}`, {
+      method: 'DELETE', headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  // ── Threat intel (V59) ─────────────────────────────────────────────
+  async listIntelFeeds() {
+    return request(`${this.#base}/v1/security/threat-intel`, { headers: this.#headers, timeout: this.#timeout });
+  }
+  async refreshIntelFeed(id) {
+    return request(`${this.#base}/v1/security/threat-intel/${encodeURIComponent(id)}/refresh`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  // ── Marketplace (V59) ──────────────────────────────────────────────
+  async marketplaceList(params = {}) {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(params)) if (v != null) q.set(k, String(v));
+    const qs = q.toString() ? `?${q.toString()}` : '';
+    return request(`${this.#base}/v1/security/marketplace${qs}`, { headers: this.#headers, timeout: this.#timeout });
+  }
+  async marketplaceInstall(id) {
+    return request(`${this.#base}/v1/security/marketplace/${encodeURIComponent(id)}/install`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  // ── Benchmark (V59) ────────────────────────────────────────────────
+  async runBenchmark(target = 'classifier') {
+    return request(`${this.#base}/v1/security/benchmark/run`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { target },
+    });
+  }
+  async benchmarkRuns() {
+    return request(`${this.#base}/v1/security/benchmark/runs`, { headers: this.#headers, timeout: this.#timeout });
+  }
+
+  // ── SIEM targets (V58) ─────────────────────────────────────────────
+  async listSiemTargets() {
+    return request(`${this.#base}/v1/security/siem`, { headers: this.#headers, timeout: this.#timeout });
+  }
+  async createSiemTarget(target) {
+    return request(`${this.#base}/v1/security/siem`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout, body: target,
+    });
+  }
+  async testSiemTarget(id) {
+    return request(`${this.#base}/v1/security/siem/${encodeURIComponent(id)}/test`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  // ── Replay (V57) ───────────────────────────────────────────────────
+  async listReplayJobs() {
+    return request(`${this.#base}/v1/security/replay`, { headers: this.#headers, timeout: this.#timeout });
+  }
+  async createReplayJob(body) {
+    return request(`${this.#base}/v1/security/replay`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout, body,
+    });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// ReportsResource — V54 PDF + share
+// ─────────────────────────────────────────────────────────────────────────────
+class ReportsResource {
+  #headers; #base; #timeout;
+  constructor(headers, base, timeout) {
+    this.#headers = headers; this.#base = base; this.#timeout = timeout;
+  }
+
+  /**
+   * Generate a date-range prod report.
+   * @returns {Promise<{ report: { id, title, ... } }>}
+   */
+  async generateProd({
+    title, rangeStart, rangeEnd, sections, format = 'pdf',
+  } = {}) {
+    return request(`${this.#base}/v1/reports/prod`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: {
+        title,
+        range_start: rangeStart instanceof Date ? rangeStart.toISOString() : rangeStart,
+        range_end:   rangeEnd   instanceof Date ? rangeEnd.toISOString()   : rangeEnd,
+        sections, format,
+      },
+    });
+  }
+
+  async listProd() {
+    return request(`${this.#base}/v1/reports/prod`, { headers: this.#headers, timeout: this.#timeout });
+  }
+
+  /**
+   * Download a prod report PDF as a Blob (browser) or Buffer (Node).
+   * @returns {Promise<Blob|Buffer>}
+   */
+  async downloadProdPdf(reportId) {
+    const url = `${this.#base}/v1/reports/prod/${encodeURIComponent(reportId)}/pdf`;
+    const res = await fetch(url, { headers: this.#headers });
+    if (!res.ok) throw new Error(`Download failed: HTTP ${res.status}`);
+    if (typeof Blob !== 'undefined' && res.body) return res.blob();
+    return Buffer.from(await res.arrayBuffer());
+  }
+
+  /**
+   * Download a test-run PDF report (V54 — the security/perf test results).
+   */
+  async downloadTestRunPdf(runId) {
+    const url = `${this.#base}/v1/reports/test-runs/${encodeURIComponent(runId)}/pdf`;
+    const res = await fetch(url, { headers: this.#headers });
+    if (!res.ok) throw new Error(`Download failed: HTTP ${res.status}`);
+    if (typeof Blob !== 'undefined' && res.body) return res.blob();
+    return Buffer.from(await res.arrayBuffer());
+  }
+
+  /**
+   * Mint a public share link (no auth required to download).
+   * @returns {Promise<{ share_token, share_expires_at, share_url_path }>}
+   */
+  async share(reportId, ttlDays = 7) {
+    return request(`${this.#base}/v1/reports/prod/${encodeURIComponent(reportId)}/share`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { ttl_days: ttlDays },
+    });
+  }
+
+  async archive(reportId) {
+    return request(`${this.#base}/v1/reports/prod/${encodeURIComponent(reportId)}`, {
+      method: 'DELETE', headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// AuthResource — registration, login, API key management
+// ─────────────────────────────────────────────────────────────────────────────
+class AuthResource {
+  #headers; #base; #timeout;
+
+  constructor(headers, base, timeout) {
+    this.#headers = headers;
+    this.#base    = base;
+    this.#timeout = timeout;
+  }
+
+  /** Register a new account. Returns the JWT token and first API key. */
+  async register(email, password, companyName) {
+    return request(`${this.#base}/v1/auth/register`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { email, password, company_name: companyName },
+    });
+  }
+
+  /** Log in to an existing account. Returns a JWT token. */
+  async login(email, password) {
+    return request(`${this.#base}/v1/auth/login`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { email, password },
+    });
+  }
+
+  /** Create a new API key (requires JWT auth, owner/admin only). */
+  async createApiKey({ name, scopes = ['scan'] } = {}) {
+    return request(`${this.#base}/v1/auth/api-keys`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { name, scopes },
+    });
+  }
+
+  /** List all API keys for the current tenant. */
+  async listApiKeys() {
+    return request(`${this.#base}/v1/auth/api-keys`, {
+      headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  /** Revoke an API key by ID (owner/admin only). */
+  async revokeApiKey(id) {
+    return request(`${this.#base}/v1/auth/api-keys/${encodeURIComponent(id)}`, {
+      method: 'DELETE', headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// MetricsResource — dashboard analytics (requires JWT auth)
+// ─────────────────────────────────────────────────────────────────────────────
+class MetricsResource {
+  #headers; #dash; #timeout;
+
+  constructor(headers, dash, timeout) {
+    this.#headers = headers;
+    this.#dash    = dash;
+    this.#timeout = timeout;
+  }
+
+  #get(path, params) {
+    const url = new URL(`${this.#dash}/metrics${path}`);
+    if (params) Object.entries(params).forEach(([k, v]) => v != null && url.searchParams.set(k, v));
+    return request(url.toString(), { headers: this.#headers, timeout: this.#timeout });
+  }
+
+  /** Overall scan statistics (total events, PII masked, comparisons vs prev period). */
+  summary()                             { return this.#get('/summary'); }
+
+  /** Daily aggregate timeseries. range: '7d' | '30d' | '90d' */
+  timeseries({ range = '30d' } = {})   { return this.#get('/timeseries', { range }); }
+
+  /** Top 20 entity types detected (last 30 days). */
+  byEntity()                            { return this.#get('/by-entity'); }
+
+  /** Detection counts grouped by surface (vscode, browser, mcp, api, sdk). */
+  bySurface()                           { return this.#get('/by-surface'); }
+
+  /** Detection counts grouped by source (PROMPT, PASTE, RAG, TOOL_RESULT, AGENT_MEMORY). */
+  bySource()                            { return this.#get('/by-source'); }
+
+  /** Activity breakdown per API key / developer. */
+  byDeveloper()                         { return this.#get('/by-developer'); }
+
+  /** Recent detection events (paginated). */
+  recentEvents({ limit = 50, offset = 0 } = {}) {
+    return this.#get('/recent-events', { limit, offset });
+  }
+
+  /** Single event detail by ID. */
+  eventDetail(eventId) { return this.#get(`/events/${encodeURIComponent(eventId)}`); }
+
+  /** Detection counts grouped by API key (last 30 days). */
+  byApiKey()                            { return this.#get('/by-api-key'); }
+
+  /** Latency percentiles (p50/p95/p99) per day (last 30 days). */
+  latencyPercentiles()                  { return this.#get('/latency-percentiles'); }
+
+  /** Scan counts by day-of-week and hour — heatmap data (last 30 days). */
+  peakHours()                           { return this.#get('/peak-hours'); }
+
+  /** Compliance report for a date range — suitable for GDPR / DPDP export. */
+  complianceReport({ from, to } = {})   { return this.#get('/compliance-report', { from, to }); }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TenantResource — profile and team management (requires JWT auth)
+// ─────────────────────────────────────────────────────────────────────────────
+class TenantResource {
+  #headers; #dash; #timeout;
+
+  constructor(headers, dash, timeout) {
+    this.#headers = headers;
+    this.#dash    = dash;
+    this.#timeout = timeout;
+  }
+
+  /** Get tenant profile (name, plan, seats, status, settings). */
+  profile() {
+    return request(`${this.#dash}/profile`, {
+      headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  /** List team members (owner/admin only). */
+  members() {
+    return request(`${this.#dash}/members`, {
+      headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  /** Invite a user to the tenant (owner/admin only). */
+  invite(email, role = 'member') {
+    return request(`${this.#dash}/members/invite`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { email, role },
+    });
+  }
+
+  /** Update tenant-level settings (custom entities, webhook URL, etc.). */
+  updateSettings(settings) {
+    return request(`${this.#dash}/settings`, {
+      method: 'PATCH', headers: this.#headers, timeout: this.#timeout,
+      body: settings,
+    });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// TraceResource — AgentTrace observability & security
+// ─────────────────────────────────────────────────────────────────────────────
+class TraceResource {
+  #headers; #base; #timeout;
+
+  constructor(headers, base, timeout) {
+    this.#headers = headers;
+    this.#base    = base;
+    this.#timeout = timeout;
+  }
+
+  /** Ingest a single trace with its spans. */
+  async ingest(project, trace, spans) {
+    return request(`${this.#base}/v1/trace/ingest`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { project, trace, spans },
+    });
+  }
+
+  /** Ingest multiple traces in a single request. */
+  async ingestBatch(traces) {
+    return request(`${this.#base}/v1/trace/ingest/batch`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { traces },
+    });
+  }
+
+  /** Append spans to an existing trace. */
+  async appendSpans(traceId, spans) {
+    return request(`${this.#base}/v1/trace/spans`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { trace_id: traceId, spans },
+    });
+  }
+
+  /** List traces with optional filters. */
+  async list({ status, projectId, hasPii, limit, offset } = {}) {
+    const url = new URL(`${this.#base}/v1/trace/`);
+    if (status != null)    url.searchParams.set('status', status);
+    if (projectId != null) url.searchParams.set('project_id', projectId);
+    if (hasPii != null)    url.searchParams.set('has_pii', hasPii);
+    if (limit != null)     url.searchParams.set('limit', limit);
+    if (offset != null)    url.searchParams.set('offset', offset);
+    return request(url.toString(), { headers: this.#headers, timeout: this.#timeout });
+  }
+
+  /** Get a single trace by ID. */
+  async get(traceId) {
+    return request(`${this.#base}/v1/trace/${encodeURIComponent(traceId)}`, {
+      headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  /** Get raw trace data (unprocessed spans/events). */
+  async getRaw(traceId) {
+    return request(`${this.#base}/v1/trace/${encodeURIComponent(traceId)}/raw`, {
+      headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  /** Update trace metadata. */
+  async update(traceId, updates) {
+    return request(`${this.#base}/v1/trace/${encodeURIComponent(traceId)}`, {
+      method: 'PATCH', headers: this.#headers, timeout: this.#timeout,
+      body: updates,
+    });
+  }
+
+  /** List traced projects. */
+  async listProjects({ limit, offset } = {}) {
+    const url = new URL(`${this.#base}/v1/trace/projects`);
+    if (limit != null)  url.searchParams.set('limit', limit);
+    if (offset != null) url.searchParams.set('offset', offset);
+    return request(url.toString(), { headers: this.#headers, timeout: this.#timeout });
+  }
+
+  /** Create a new traced project. */
+  async createProject(name, opts = {}) {
+    return request(`${this.#base}/v1/trace/projects`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: { name, ...opts },
+    });
+  }
+
+  /** Get a traced project by ID. */
+  async getProject(id) {
+    return request(`${this.#base}/v1/trace/projects/${encodeURIComponent(id)}`, {
+      headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  /** List discovered agents. */
+  async listAgents({ projectId, limit, offset } = {}) {
+    const url = new URL(`${this.#base}/v1/trace/agents`);
+    if (projectId != null) url.searchParams.set('project_id', projectId);
+    if (limit != null)     url.searchParams.set('limit', limit);
+    if (offset != null)    url.searchParams.set('offset', offset);
+    return request(url.toString(), { headers: this.#headers, timeout: this.#timeout });
+  }
+
+  /** Get a single agent by ID. */
+  async getAgent(id) {
+    return request(`${this.#base}/v1/trace/agents/${encodeURIComponent(id)}`, {
+      headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  /** Update an agent's role and description. */
+  async updateAgentRole(id, role, description) {
+    return request(`${this.#base}/v1/trace/agents/${encodeURIComponent(id)}/role`, {
+      method: 'PATCH', headers: this.#headers, timeout: this.#timeout,
+      body: { role, description },
+    });
+  }
+
+  /** List security events with optional filters. */
+  async listSecurityEvents({ severity, status, projectId, limit, offset } = {}) {
+    const url = new URL(`${this.#base}/v1/trace/security/events`);
+    if (severity != null)  url.searchParams.set('severity', severity);
+    if (status != null)    url.searchParams.set('status', status);
+    if (projectId != null) url.searchParams.set('project_id', projectId);
+    if (limit != null)     url.searchParams.set('limit', limit);
+    if (offset != null)    url.searchParams.set('offset', offset);
+    return request(url.toString(), { headers: this.#headers, timeout: this.#timeout });
+  }
+
+  /** Get security events summary/aggregation. */
+  async getSecuritySummary({ projectId, range } = {}) {
+    const url = new URL(`${this.#base}/v1/trace/security/events/summary`);
+    if (projectId != null) url.searchParams.set('project_id', projectId);
+    if (range != null)     url.searchParams.set('range', range);
+    return request(url.toString(), { headers: this.#headers, timeout: this.#timeout });
+  }
+
+  /** Resolve a security event by ID. */
+  async resolveSecurityEvent(id, note) {
+    return request(`${this.#base}/v1/trace/security/events/${encodeURIComponent(id)}/resolve`, {
+      method: 'PATCH', headers: this.#headers, timeout: this.#timeout,
+      body: { note },
+    });
+  }
+
+  /** List security rules. */
+  async listRules() {
+    return request(`${this.#base}/v1/trace/security/rules`, {
+      headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  /** Create a security rule. */
+  async createRule(rule) {
+    return request(`${this.#base}/v1/trace/security/rules`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: rule,
+    });
+  }
+
+  /** List security webhooks. */
+  async listWebhooks() {
+    return request(`${this.#base}/v1/trace/security/webhooks`, {
+      headers: this.#headers, timeout: this.#timeout,
+    });
+  }
+
+  /** Create a security webhook. */
+  async createWebhook(webhook) {
+    return request(`${this.#base}/v1/trace/security/webhooks`, {
+      method: 'POST', headers: this.#headers, timeout: this.#timeout,
+      body: webhook,
+    });
+  }
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// CiphyrsClient — main entry point
+// ─────────────────────────────────────────────────────────────────────────────
+export class CiphyrsClient {
+  /**
+   * @param {object} opts
+   * @param {string}  opts.apiKey    — API key (cyp_live_...) for server-side use
+   * @param {string}  [opts.token]   — JWT token for dashboard/management endpoints
+   * @param {string}  [opts.baseUrl] — Override gateway URL (VPC / on-prem deployments)
+   * @param {string}  [opts.dashUrl] — Override dashboard API URL
+   * @param {number}  [opts.timeout] — Request timeout in ms (default: 10000)
+   */
+  constructor({ apiKey, token, baseUrl = DEFAULT_BASE_URL, dashUrl = DASH_BASE_URL, timeout = 10_000 } = {}) {
+    if (!apiKey && !token) throw new Error('CiphyrsClient: provide apiKey (server-side) or token (dashboard)');
+
+    const headers = {
+      ...(apiKey ? { 'x-api-key': apiKey }                   : {}),
+      ...(token  ? { 'Authorization': `Bearer ${token}` }    : {}),
+    };
+
+    /** @internal Base URL for API requests (used by tracer / eval-runner) */
+    this._baseUrl = baseUrl.replace(/\/$/, '');
+    /** @internal Default headers (used by tracer / eval-runner) */
+    this._headers = headers;
+    /** @internal Default timeout */
+    this._timeout = timeout;
+
+    this.scan     = new ScanResource(headers, this._baseUrl, timeout);
+    this.auth     = new AuthResource(headers, this._baseUrl, timeout);
+    this.metrics  = new MetricsResource(headers, dashUrl.replace(/\/$/, ''), timeout);
+    this.tenant   = new TenantResource(headers, dashUrl.replace(/\/$/, ''), timeout);
+    this.trace    = new TraceResource(headers, this._baseUrl, timeout);
+    // V54-V59 — security platform resources
+    this.guard    = new GuardResource(headers, this._baseUrl, timeout);
+    this.security = new SecurityResource(headers, this._baseUrl, timeout);
+    this.reports  = new ReportsResource(headers, this._baseUrl, timeout);
+  }
+
+  /**
+   * @internal — Make an authenticated HTTP request.
+   * Used by CiphyrsTracer and EvalRunner for endpoints not covered by resource classes.
+   */
+  async _request(url, opts = {}) {
+    return request(url, {
+      ...opts,
+      headers: { ...this._headers, ...opts.headers },
+      timeout: opts.timeout ?? this._timeout,
+    });
+  }
+
+  // ── Top-level shortcuts for the most common operations ──────────────────────
+
+  /** Shortcut for client.scan.mask() */
+  mask(text, opts)              { return this.scan.mask(text, opts); }
+
+  /** Shortcut for client.scan.restore() */
+  restore(maskedText, sessionId, opts) { return this.scan.restore(maskedText, sessionId, opts); }
+
+  /** Shortcut for client.scan.protect() — mask → LLM call → restore round-trip */
+  protect(userInput, llmCall, opts) { return this.scan.protect(userInput, llmCall, opts); }
+
+  /** Shortcut for client.scan.maskAsync() */
+  maskAsync(text, opts)         { return this.scan.maskAsync(text, opts); }
+
+  /** Shortcut for client.scan.waitForJob() */
+  waitForJob(jobId, opts)       { return this.scan.waitForJob(jobId, opts); }
+
+  /** Shortcut for client.auth.createApiKey() */
+  createKey(opts)               { return this.auth.createApiKey(opts); }
+}