@gpzhang2001/sharpkit-proxy 0.2.1

package/src/client.ts

@@ -0,0 +1,436 @@
+/**
+ * Caido HTTP/GraphQL client — TS port of the CLIENT half of strix
+ * tools/proxy/caido_api.py against the HOST-side published endpoint (global
+ * fetch + Bearer token from the sandbox session's bootstrap). Documents are
+ * trimmed, schema-valid subsets of the caido_sdk_client generated operations
+ * (Requests/Request/ReplayEntry/StartReplayTask/sitemap trio). The replay
+ * flow adapts the SDK's subscription wait into bounded polling of the entry
+ * (finished when a response or an error appears; 30s strix dispatch budget).
+ * @module @gpzhang2001/sharpkit-proxy/client
+ */
+
+import { Buffer } from 'node:buffer'
+import { buildRawRequest, fullUrlFromComponents, applyModifications, parseRawRequest, parseRawResponse, type RawResponseParts } from './replay.ts'
+
+/** Which half of a captured exchange to surface (strix RequestPart). */
+export type RequestPart = 'request' | 'response'
+
+/** Sort keys accepted by list_requests (strix SortBy). */
+export type SortBy = 'timestamp' | 'host' | 'method' | 'path' | 'status_code' | 'response_time' | 'response_size' | 'source'
+
+/** strix `_REQ_FIELD_MAP` resolved to Caido's RequestResponseOrderBy enums. */
+const SORT_ENUMS: Record<SortBy, string> = {
+  timestamp: 'CREATED_AT',
+  host: 'HOST',
+  method: 'METHOD',
+  path: 'PATH',
+  source: 'SOURCE',
+  status_code: 'RESP_STATUS_CODE',
+  response_time: 'RESP_ROUNDTRIP_TIME',
+  response_size: 'RESP_LENGTH',
+}
+
+/** The one Caido port the sandbox publishes (protocol constant). */
+export const CAIDO_PORT = 48080
+
+/** Compact Requests query (subset of the SDK's generated document). */
+const REQUESTS_DOC = `query Requests($first: Int, $after: String, $filter: HTTPQLInput, $order: RequestResponseOrderInput, $scopeId: ID, $includeRequestRaw: Boolean!, $includeResponseRaw: Boolean!) {
+  requests(first: $first, after: $after, filter: $filter, order: $order, scopeId: $scopeId) {
+    edges { cursor node {
+      id host port method path query isTls createdAt
+      raw @include(if: $includeRequestRaw)
+      response { id statusCode roundtripTime length createdAt raw @include(if: $includeResponseRaw) }
+    } }
+    pageInfo { hasNextPage hasPreviousPage startCursor endCursor }
+  }
+}`
+
+/** Compact Request query (both raws always requested — SDK parity note). */
+const REQUEST_DOC = `query Request($id: ID!, $includeRequestRaw: Boolean!, $includeResponseRaw: Boolean!) {
+  request(id: $id) {
+    id host port method path query isTls createdAt
+    raw @include(if: $includeRequestRaw)
+    response { id statusCode roundtripTime length createdAt raw @include(if: $includeResponseRaw) }
+  }
+}`
+
+/** Empty replay session create (avoids the double history row the raw-create seeds). */
+const CREATE_REPLAY_SESSION_DOC = `mutation CreateReplaySession($input: CreateReplaySessionInput!) {
+  createReplaySession(input: $input) { session { id } error { __typename } }
+}`
+
+/** Replay dispatch (strix `replay_send_raw` via the SDK's StartReplayTask). */
+const START_REPLAY_TASK_DOC = `mutation StartReplayTask($sessionId: ID!, $input: StartReplayTaskInput!) {
+  startReplayTask(sessionId: $sessionId, input: $input) { error { __typename } task { id replayEntry { id } } }
+}`
+
+/** Replay entry poll — finished when request.response or error appears. */
+const REPLAY_ENTRY_DOC = `query ReplayEntry($id: ID!, $includeReplayRaw: Boolean!, $includeRequestRaw: Boolean!, $includeResponseRaw: Boolean!) {
+  replayEntry(id: $id) {
+    id error
+    request { id method path response { id statusCode length roundtripTime raw @include(if: $includeResponseRaw) } }
+  }
+}`
+
+/** Scope management (strix caido_api.py scope_* via the SDK's ScopeFull set). */
+const SCOPES_DOC = `query Scopes { scopes { id name allowlist denylist indexed } }`
+
+const SCOPE_DOC = `query Scope($id: ID!) { scope(id: $id) { id name allowlist denylist indexed } }`
+
+const CREATE_SCOPE_DOC = `mutation CreateScope($input: CreateScopeInput!) { createScope(input: $input) { error { __typename } scope { id name allowlist denylist indexed } } }`
+
+const UPDATE_SCOPE_DOC = `mutation UpdateScope($id: ID!, $input: UpdateScopeInput!) { updateScope(id: $id, input: $input) { error { __typename } scope { id name allowlist denylist indexed } } }`
+
+const DELETE_SCOPE_DOC = `mutation DeleteScope($id: ID!) { deleteScope(id: $id) { deletedId } }`
+
+/** Sitemap queries (verbatim field sets from strix caido_api.py:555-592). */
+const SITEMAP_ROOTS_DOC = `query GetSitemapRoots($scopeId: ID) {
+  sitemapRootEntries(scopeId: $scopeId) {
+    edges { node {
+      id kind label hasDescendants
+      metadata { ... on SitemapEntryMetadataDomain { isTls port } }
+      request { method path response { statusCode } }
+    } }
+    count { value }
+  }
+}`
+
+const SITEMAP_DESCENDANTS_DOC = `query GetSitemapDescendants($parentId: ID!, $depth: SitemapDescendantsDepth!) {
+  sitemapDescendantEntries(parentId: $parentId, depth: $depth) {
+    edges { node {
+      id kind label hasDescendants
+      request { method path response { statusCode } }
+    } }
+    count { value }
+  }
+}`
+
+const SITEMAP_ENTRY_DOC = `query GetSitemapEntry($id: ID!) {
+  sitemapEntry(id: $id) {
+    id kind label hasDescendants
+    metadata { ... on SitemapEntryMetadataDomain { isTls port } }
+    request { method path response { statusCode length roundtripTime } }
+    requests(first: 30, order: {by: CREATED_AT, ordering: DESC}) {
+      edges { node { method path response { statusCode length } } }
+      count { value }
+    }
+  }
+}`
+
+/** Fetch contract (global fetch shape) for the GraphQL endpoint. */
+export interface CaidoFetchFn {
+  (url: string, init: { readonly method: 'POST'; readonly headers: Readonly<Record<string, string>>; readonly body: string; readonly signal: AbortSignal }): Promise<{ readonly status: number; readonly text: () => Promise<string> }>
+}
+
+/** One captured request entry projected for the model (strix shape). */
+export interface RequestListEntry {
+  readonly cursor: string
+  readonly request: {
+    readonly id: string
+    readonly host: string
+    readonly port: number
+    readonly method: string
+    readonly path: string
+    readonly query: string | null
+    readonly tls: boolean
+    readonly createdAt: string
+  }
+  readonly response: { readonly id: string; readonly statusCode: number | null; readonly length: number | null; readonly createdAt: string | null } | null
+}
+
+/** PageInfo projection (strix page_info). */
+export interface CaidoPageInfo {
+  readonly hasNextPage: boolean
+  readonly hasPreviousPage: boolean
+  readonly startCursor: string | null
+  readonly endCursor: string | null
+}
+
+/** The raw halves of one stored request. */
+export interface StoredRequest {
+  readonly id: string
+  readonly host: string
+  readonly port: number
+  readonly method: string
+  readonly tls: boolean
+  readonly requestRaw: string | null
+  readonly responseRaw: string | null
+}
+
+/** Replay outcome (strix `_format_replay_tool_result` inputs). */
+export interface ReplayOutcome {
+  readonly sessionId: string
+  readonly status: string
+  readonly elapsedMs: number
+  readonly error?: string
+  readonly response: RawResponseParts | null
+}
+
+/** Endpoint coordinates handed over by the sandbox session's bootstrap. */
+export interface CaidoClientOptions {
+  readonly baseUrl: string
+  readonly token: string
+  readonly fetchFn?: CaidoFetchFn
+}
+
+/** Minimal GraphQL POST with bearer auth and error normalization. */
+async function graphql<T>(
+  options: CaidoClientOptions,
+  doc: string,
+  variables: Record<string, unknown>,
+  signal: AbortSignal,
+): Promise<T> {
+  const fetchFn = options.fetchFn ?? fetch
+  const response = await fetchFn(`${options.baseUrl}/graphql`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${options.token}` },
+    body: JSON.stringify({ query: doc, variables }),
+    signal,
+  })
+  const text = await response.text()
+  if (response.status !== 200) throw new Error(`caido graphql HTTP ${response.status}: ${text.slice(0, 200)}`)
+  let payload: unknown
+  try {
+    payload = JSON.parse(text)
+  } catch (error) {
+    throw new Error(`caido graphql unparseable response: ${String(error)}`)
+  }
+  const record = payload as { readonly data?: unknown; readonly errors?: unknown }
+  if (record.errors !== undefined && record.errors !== null) {
+    throw new Error(`caido graphql errors: ${JSON.stringify(record.errors).slice(0, 300)}`)
+  }
+  if (typeof record.data !== 'object' || record.data === null) {
+    throw new Error('caido graphql carried no data')
+  }
+  return record.data as T
+}
+
+/** Project one raw requests-connection edge (strix list_requests mapping). */
+function projectEdge(edge: unknown): RequestListEntry {
+  const node = (edge as { node: Record<string, unknown> }).node
+  const response = node.response as Record<string, unknown> | null
+  return {
+    cursor: String((edge as { cursor: unknown }).cursor),
+    request: {
+      id: String(node.id),
+      host: String(node.host),
+      port: Number(node.port),
+      method: String(node.method),
+      path: String(node.path),
+      query: node.query === null || node.query === undefined ? null : String(node.query),
+      tls: node.isTls === true,
+      createdAt: new Date(Number(node.createdAt)).toISOString(),
+    },
+    response: response === null || response === undefined ? null : {
+      id: String(response.id),
+      statusCode: response.statusCode === null || response.statusCode === undefined ? null : Number(response.statusCode),
+      length: response.length === null || response.length === undefined ? null : Number(response.length),
+      createdAt: response.createdAt === null || response.createdAt === undefined ? null : new Date(Number(response.createdAt)).toISOString(),
+    },
+  }
+}
+
+/**
+ * The Caido client: five operations behind the five proxy tools. All methods
+ * take an AbortSignal (tool exec.signal parity).
+ */
+export class CaidoClient {
+  private readonly options: CaidoClientOptions
+
+  constructor(options: CaidoClientOptions) {
+    this.options = options
+  }
+
+  /** List captured requests with HTTPQL filter/cursor/sort/scope (strix list_requests_with_client). */
+  async listRequests(options: {
+    readonly httpqlFilter?: string | undefined
+    readonly first?: number | undefined
+    readonly after?: string | undefined
+    readonly sortBy?: SortBy | undefined
+    readonly sortOrder?: 'asc' | 'desc' | undefined
+    readonly scopeId?: string | undefined
+  }, signal: AbortSignal): Promise<{ readonly entries: RequestListEntry[]; readonly pageInfo: CaidoPageInfo }> {
+    const data = await graphql<{ requests: { edges: unknown[]; pageInfo: Record<string, unknown> } }>(
+      this.options,
+      REQUESTS_DOC,
+      {
+        first: options.first ?? 50,
+        ...(options.after !== undefined && options.after !== '' ? { after: options.after } : {}),
+        ...(options.httpqlFilter !== undefined && options.httpqlFilter !== '' ? { filter: { code: options.httpqlFilter } } : {}),
+        order: { by: SORT_ENUMS[options.sortBy ?? 'timestamp'], ordering: (options.sortOrder ?? 'desc') === 'asc' ? 'ASC' : 'DESC' },
+        ...(options.scopeId !== undefined && options.scopeId !== '' ? { scopeId: options.scopeId } : {}),
+        includeRequestRaw: false,
+        includeResponseRaw: false,
+      },
+      signal,
+    )
+    return {
+      entries: data.requests.edges.map(projectEdge),
+      pageInfo: {
+        hasNextPage: data.requests.pageInfo.hasNextPage === true,
+        hasPreviousPage: data.requests.pageInfo.hasPreviousPage === true,
+        startCursor: data.requests.pageInfo.startCursor === null || data.requests.pageInfo.startCursor === undefined ? null : String(data.requests.pageInfo.startCursor),
+        endCursor: data.requests.pageInfo.endCursor === null || data.requests.pageInfo.endCursor === undefined ? null : String(data.requests.pageInfo.endCursor),
+      },
+    }
+  }
+
+  /** Fetch one request with both raw halves (strix get_request_with_client parity: always request both). */
+  async getRequest(requestId: string, signal: AbortSignal): Promise<StoredRequest | null> {
+    const data = await graphql<{ request: Record<string, unknown> | null }>(
+      this.options,
+      REQUEST_DOC,
+      { id: requestId, includeRequestRaw: true, includeResponseRaw: true },
+      signal,
+    )
+    const request = data.request
+    if (request === null || request === undefined) return null
+    return {
+      id: String(request.id),
+      host: String(request.host),
+      port: Number(request.port),
+      method: String(request.method),
+      tls: request.isTls === true,
+      requestRaw: request.raw === null || request.raw === undefined ? null : Buffer.from(String(request.raw), 'base64').toString('utf8'),
+      responseRaw: (request.response as Record<string, unknown> | null | undefined)?.raw === null
+        || (request.response as Record<string, unknown> | null | undefined)?.raw === undefined
+        ? null
+        : Buffer.from(String((request.response as Record<string, unknown>).raw), 'base64').toString('utf8'),
+    }
+  }
+
+  /**
+   * Replay one stored request with optional field patches (strix
+   * `repeat_request` + `replay_send_raw`): fetch raw → parse → patch →
+   * rebuild → create empty session → startReplayTask → poll the entry.
+   * @param requestId - the stored request id.
+   * @param modifications - patch dict (url/params/headers/body/cookies).
+   * @param budget - total dispatch deadline (strix 30s) + poll interval.
+   */
+  async replayRequest(
+    requestId: string,
+    modifications: Readonly<Record<string, unknown>> | undefined,
+    signal: AbortSignal,
+    budget: { readonly dispatchTimeoutMs: number; readonly pollIntervalMs: number },
+  ): Promise<ReplayOutcome | null> {
+    const stored = await this.getRequest(requestId, signal)
+    if (stored === null || stored.requestRaw === null) return null
+    const components = parseRawRequest(stored.requestRaw)
+    const fullUrl = fullUrlFromComponents({ host: stored.host, tls: stored.tls }, components, modifications ?? {})
+    const modified = applyModifications(components, modifications ?? {}, fullUrl)
+    const built = buildRawRequest(modified)
+
+    const session = await graphql<{ createReplaySession: { session: { id: string } | null; error: unknown } }>(
+      this.options,
+      CREATE_REPLAY_SESSION_DOC,
+      { input: {} },
+      signal,
+    )
+    const createdSession = session.createReplaySession.session
+    if (createdSession === null || createdSession === undefined) throw new Error('createReplaySession returned no session')
+
+    const started = Date.now()
+    const start = await graphql<{ startReplayTask: { error: unknown; task: { id: string; replayEntry: { id: string } | null } | null } }>(
+      this.options,
+      START_REPLAY_TASK_DOC,
+      {
+        sessionId: createdSession.id,
+        input: {
+          connection: { host: built.connection.host, port: built.connection.port, isTLS: built.connection.tls, SNI: null },
+          raw: Buffer.from(built.raw).toString('base64'),
+          settings: { connectionClose: false, updateContentLength: true, placeholders: [] },
+        },
+      },
+      signal,
+    )
+    const task = start.startReplayTask.task
+    if (start.startReplayTask.error !== null && start.startReplayTask.error !== undefined) {
+      throw new Error(`startReplayTask failed: ${JSON.stringify(start.startReplayTask.error).slice(0, 200)}`)
+    }
+    if (task === null || task === undefined || task.replayEntry === null || task.replayEntry === undefined) {
+      throw new Error('startReplayTask returned no task/entry')
+    }
+
+    // Bounded poll (SDK waits on a subscription; polling keeps us HTTP-only).
+    for (;;) {
+      const entry = await graphql<{ replayEntry: Record<string, unknown> | null }>(
+        this.options,
+        REPLAY_ENTRY_DOC,
+        { id: task.replayEntry.id, includeReplayRaw: false, includeRequestRaw: false, includeResponseRaw: true },
+        signal,
+      )
+      const node = entry.replayEntry
+      if (node !== null && node !== undefined) {
+        const errorText = node.error === null || node.error === undefined ? undefined : String(node.error)
+        const request = node.request as { response?: Record<string, unknown> | null } | null | undefined
+        const responseNode = request?.response ?? null
+        if (responseNode !== null && responseNode !== undefined) {
+          const rawBase64 = responseNode.raw
+          const rawBytes = rawBase64 === null || rawBase64 === undefined ? null : Buffer.from(String(rawBase64), 'base64')
+          return {
+            sessionId: createdSession.id,
+            status: 'DONE',
+            elapsedMs: Date.now() - started,
+            ...(errorText !== undefined ? { error: errorText } : {}),
+            response: parseRawResponse(rawBytes),
+          }
+        }
+        if (errorText !== undefined) {
+          return { sessionId: createdSession.id, status: 'ERROR', elapsedMs: Date.now() - started, error: errorText, response: null }
+        }
+      }
+      if (Date.now() - started > budget.dispatchTimeoutMs) {
+        return {
+          sessionId: createdSession.id,
+          status: 'ERROR',
+          elapsedMs: Date.now() - started,
+          error: `Caido replay dispatch did not complete within ${String(Math.round(budget.dispatchTimeoutMs / 1000))}s — the target may be unroutable from the sandbox, or Caido's outbound HTTP client is stalled; check the target host/port and retry`,
+          response: null,
+        }
+      }
+      await new Promise(resolve => setTimeout(resolve, budget.pollIntervalMs))
+    }
+  }
+
+  /** Sitemap roots or descendants (strix list_sitemap_with_client). */
+  async listSitemap(options: {
+    readonly scopeId?: string | undefined
+    readonly parentId?: string | undefined
+    readonly depth?: 'DIRECT' | 'ALL' | undefined
+  }, signal: AbortSignal): Promise<unknown> {
+    if (options.parentId !== undefined && options.parentId !== '') {
+      return graphql(this.options, SITEMAP_DESCENDANTS_DOC, { parentId: options.parentId, depth: options.depth ?? 'DIRECT' }, signal)
+    }
+    return graphql(this.options, SITEMAP_ROOTS_DOC, options.scopeId !== undefined && options.scopeId !== '' ? { scopeId: options.scopeId } : {}, signal)
+  }
+
+  /** One sitemap entry with its 30 most recent requests (strix view_sitemap_entry_with_client). */
+  async viewSitemapEntry(entryId: string, signal: AbortSignal): Promise<unknown> {
+    return graphql(this.options, SITEMAP_ENTRY_DOC, { id: entryId }, signal)
+  }
+
+  /** All Caido scopes (strix scope_list). */
+  async scopeList(signal: AbortSignal): Promise<unknown> {
+    return graphql(this.options, SCOPES_DOC, {}, signal)
+  }
+
+  /** One scope by id (strix scope_get). */
+  async scopeGet(scopeId: string, signal: AbortSignal): Promise<unknown> {
+    return graphql(this.options, SCOPE_DOC, { id: scopeId }, signal)
+  }
+
+  /** Create a scope; empty lists allow-all/deny-none (strix scope_create). */
+  async scopeCreate(name: string, allowlist: string[], denylist: string[], signal: AbortSignal): Promise<unknown> {
+    return graphql(this.options, CREATE_SCOPE_DOC, { input: { name, allowlist, denylist } }, signal)
+  }
+
+  /** Update a scope; allow/deny lists FULLY REPLACE the previous values (strix parity). */
+  async scopeUpdate(scopeId: string, name: string, allowlist: string[], denylist: string[], signal: AbortSignal): Promise<unknown> {
+    return graphql(this.options, UPDATE_SCOPE_DOC, { id: scopeId, input: { name, allowlist, denylist } }, signal)
+  }
+
+  /** Delete a scope (strix scope_delete). */
+  async scopeDelete(scopeId: string, signal: AbortSignal): Promise<unknown> {
+    return graphql(this.options, DELETE_SCOPE_DOC, { id: scopeId }, signal)
+  }
+}