integration.provider-web-access

@lssm-tech/integration.provider-web-access

Governed provider adapters for Bright Data, Massive, Browserbase, Serper, Linkup, Tavily, direct fetch, Reworkd, Firecrawl, Apify, and Oxylabs.

Support matrix

All normalized operations are also bound to the ContractSpec operation registry for local MCP projection. A missing vendor-native surface is recorded as unsupported instead of being simulated.

Usage

import { createWebAccessAdapters } from "@lssm-tech/integration.provider-web-access";

const adapters = createWebAccessAdapters({
  tavily: {
    secretReference: "vault://tenant/tavily",
    secretProvider,
    budgetPort,
    telemetryPort,
  },
});

const result = await adapters.tavily?.execute("search.execute", {
  provider: "tavily",
  tenantId: "tenant-1",
  connectionId: "tavily-primary",
  policyMode: "governed",
  authorization: { decision: "allow", evidenceRefs: ["approval-1"] },
  payload: { query: "ContractSpec", transport: "rest" },
});

Set payload.transport to "rest" to use the direct HTTP client. Omit it to use the official SDK where one exists. Linkup and Browserbase x402 execution requires an injected X402PaymentPort; the package never owns wallet keys. When a request supplies budget, the adapter also requires an injected WebAccessBudgetPort so request and monetary reservations are atomic rather than process-local counters.

Stagehand v4 browser automation

BrowserbaseAdapter.automation implements the provider-neutral act, observe, and extract contract over sessions created or synchronized by that adapter. Each call reconnects to the existing Browserbase sessionId with browserbase.connect, creates Stagehand through Stagehand.create, then closes Stagehand before disconnecting the attached browser. Disconnecting never releases the server session; session.close remains the explicit owner of release, so a Browserbase session created with keepAlive remains reconnectable.

import {
  BrowserbaseAdapter,
  createStagehandTools,
} from "@lssm-tech/integration.provider-web-access";

const browserbase = new BrowserbaseAdapter({
  secretReference: "vault://tenant/browserbase",
  secretProvider,
});

const tools = createStagehandTools(browserbase.automation, {
  tenantId: "tenant-1",
  connectionId: "browserbase-primary",
  correlationId: crypto.randomUUID(),
  authorization: { decision: "allow", evidenceRefs: ["approval-1"] },
});
// Pass `tools` directly to `new ToolLoopAgent({ model, tools })` from ai@7.

The stable tool names are browserbase_browser_act, browserbase_browser_observe, and browserbase_browser_extract. Act requires AI SDK approval; observe and extract are read/cost-bearing and execute without consequential approval. Inputs use Zod v4 inputSchema and the AI SDK 7 tool API. Browserbase credentials are resolved only through SecretProvider; no tool or operation accepts a raw API key. Optional pageId targets the public Stagehand v4 Page.pageId value and returns WEB_ACCESS_INVALID_PAGE_ID when it is unknown. The runtime requires Node 22.18 or newer, matching Stagehand v4.

Safety and secret handling

Credentials are always resolved through SecretProvider. Browser, MCP, and proxy connection secrets are represented by opaque handles and are never serialized into contracts, logs, telemetry, or fixtures.

Managed deployments use SecretBackedOpaqueHandleStore with a narrowly scoped secret-reference prefix. CDP connection material is stored only as a bounded, expiring secret payload; callers receive the reference, never its value. Cross-prefix reads fail closed, expired handles are deleted before returning, and production compositions must not rely on the in-memory conformance store.

All network execution applies the non-bypassable public-network safety policy. The default policy mode is governed; provider-pass-through and public-only retain the same SSRF and secret-protection baseline. Governed mode requires an unexpired allow decision with at least one evidence reference. Authenticated provider adapters reject public-only. Direct fetch is credential-free and permits public-only, while retaining the same SSRF, redirect, sensitive-header, timeout, and body-size controls.

Direct fetch rejects non-success responses by default. Evidence workflows may explicitly accept only HTTP 404 and 410; those bounded statuses return content-addressable response data for revalidation or closure proof. Other status overrides, duplicates, and arbitrary accepted-error lists fail closed.

Native MCP and CDP connectors validate descriptors against immutable provider-owned endpoint/command manifests before connecting. Local MCP process arguments and remote MCP query/header credentials exist only for the connection lifetime, and normalized failures redact API keys and tokens.

REST retries are bounded and limited to idempotent requests. Target and redirect validation blocks embedded credentials, loopback, private, link-local, and metadata networks. Webhook bodies, SSE streams, and provider responses have configurable size limits.

Verification

Deterministic fixtures cover every advertised operation plus REST/SDK parity, polling, cancellation, retries, normalized errors, SSE framing, webhook ingress, CDP cleanup, proxy encoding, SSRF defenses, and MCP credential redaction. bun run live:plan prints the canonical 132-row live qualification plan. Fifty-three supported or account-gated rows declare an executable probe mode, exact operation/evidence references, and required environment; seventy-nine unsupported rows remain non-executable with a reason. REST/SDK, x402, webhook callbacks, CDP sessions, research SSE, hosted/local native MCP, OSINT MCP, and every proxy protocol are separate proof rows.

bun run test:live requires WEB_ACCESS_LIVE_CONFIRM=YES, executes eleven REST smoke probes, and verifies the complete receipt set named by WEB_ACCESS_LIVE_RECEIPT_PATH against WEB_ACCESS_LIVE_RELEASE_SHA. Every supported/account-gated row must be passed with request/response digests and evidence; unsupported rows must remain unsupported. Missing, duplicate, blocked, failed, unknown, evidence-free, or stale-SHA receipts fail the command. The command cannot promote eleven REST calls into full provider qualification. Receipt JSON is parsed as untrusted input with bounded fields, and a narrowed copy of the capability plan cannot be substituted for the canonical matrix.

Specialized probes additionally declare their required callback URL, browser, research, native MCP, OSINT MCP, x402, or safe proxy-target inputs in the plan. runWebAccessLiveQualification accepts a credential-owning probe executor and produces redacted, cancellation-aware receipts for the complete plan. The package never accepts raw secrets or payment keys inside receipt JSON.

See @lssm-tech/lib.contracts-integrations/integrations/web-access for the public contracts, same-file WebAccessOperationsDocBlock, provider inventory, and pinned claim-level capability ledger. The operator matrix and provider-selection guidance are published at /docs/integrations/web-access.