@agentmatrix.pro/browser-sdk 0.1.0-rc.1 → 0.1.0-rc.2

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.1.0-rc.2
+
+_Release prepared 2026-10-30 for the official npm `next` channel._
+
+Requires Platform `0.160.0`. The matching API contract is deployed in AgentMatrix
+`release-2026-10-30.3`; Guest/profile/Worker enablement and real takeover
+qualification remain pending. This package stays a prerelease.
+
+- Support backend owner-bound API keys for get/acquire/release without UserJWT or CSRF (Platform 0.160.0).
+- Add one-use `BrowserViewer.takeAccess()` and `createBrowserViewer()` for authenticated backend-to-frontend capability transfer; keep API keys off the frontend.
+- Preserve Workspace authentication, single-attempt transport, explicit handback, and unknown-result readback.
+
 ## 0.1.0-rc.1
 
 First AgentMatrix browser SDK prerelease, prepared for the official npm `next`

package/README.md

@@ -1,77 +1,136 @@
 # AgentMatrix browser control
 
-Human-authorized control of an existing Agent browser. The `0.1.0-rc.1`
-prerelease targets the `next` channel for integration work:
+Owner-authorized control of an existing Agent browser. Applications can use an
+owner-bound data-plane API key on their backend; users do not need a separate
+AgentMatrix login. Existing Workspace JWT + selected key ID + CSRF calls remain
+supported.
+
+This source targets **Platform 0.160.0**. The API-key path and capability transfer
+are introduced in `@agentmatrix.pro/browser-sdk@0.1.0-rc.2`; the earlier
+`0.1.0-rc.1` does not include them. Install that exact prerelease for integration:
 
 ```bash
-npm install @agentmatrix.pro/browser-sdk@0.1.0-rc.1
+npm install @agentmatrix.pro/browser-sdk@0.1.0-rc.2
 ```
 
-It requires Platform `0.159.1` with browser control enabled and the calling
-Workspace origin explicitly allowed by its Preview owner. Real Identity/Guest
-enablement qualification remains pending; installing this package does not
-enable browser control on the server.
+The deployment must enable browser control and approve the frontend's exact
+parent origin in both Guest and Preview configuration. Installing the SDK does
+not enable the server feature or exit Q0. This remains a prerelease while real
+Identity/Guest enablement qualification is pending.
+
+## Backend with an API key
 
-This package uses the current signed-in user's JWT, selected tenant/namespace and
-owned API-key **ID**, plus the Gateway's existing CSRF cookie/header pair. It does
-not accept an API key as human authorization, sign users in, refresh credentials,
-create browsers or establish cross-origin cookie/CORS policy.
+Keep the key on your server. It must belong to the Session owner, include
+`session.full`, and permit the selected namespace. Tenant and owner are derived
+from the verified key; do not supply a JWT, tenant ID, key ID or CSRF token.
 
 ```ts
 import { BrowserControlClient } from "@agentmatrix.pro/browser-sdk";
 
 const control = new BrowserControlClient({ baseURL: gatewayOrigin });
-// Take a fresh snapshot from your application's authenticated user/scope owner.
-const context = { userJWT, tenantId, namespaceId, apiKeyId, sessionId, csrfToken };
+const context = { apiKey: serverSecret, sessionId, namespaceId: "default" };
 const current = await control.get(context);
+// In your endpoint, authorize the application's own user for this Session first.
+// Only continue for an explicit takeover action. Persist/reuse its operation ID.
 if (current.data.allowed_actions.includes("acquire") && current.data.control_id) {
   const result = await control.acquire(context, {
-    operation_id: crypto.randomUUID(), // one new explicit user action
+    operation_id: operationId,
     expected_control_id: current.data.control_id,
     expected_revision: current.data.revision,
   });
-  if (result.viewer) {
-    result.viewer.attach(iframe);
-    // Keep this handle in memory. Its deadline is result.viewer.expiresAt.
-  }
+  const response = {
+    data: result.data,
+    viewer_access: result.viewer?.takeAccess(),
+  };
+  // Return response only to that authenticated user over HTTPS, Cache-Control: no-store.
+  // It contains a short-lived secret: never log, cache or persist it.
 }
 ```
 
-`get`, `acquire` and `release` make one HTTP attempt each. They do not retry,
-refresh authentication, generate IDs or poll. Read defaults to a 15-second total
-deadline; mutations default to 200 seconds to cover the server's drain budget.
-Per-call `{ signal, timeoutMs }` bounds headers and the complete response body.
-An injected `fetch` must also make one attempt without hidden refresh/retry.
-
-On explicit handback, first call `viewer.stopInput()`. Read a fresh status, then
-call `release(context, { operation_id, expected_control_id, expected_revision,
-lease_id })` using that observation. Retain the iframe while the response is
-202 or state remains revoking: it must receive the Guest's real clear challenge.
-After confirmed Agent handback, call `viewer.dispose()`. When allowed actions
-contain `release`, offer an explicit **Continue handback** action using the latest
-observation and a new user intent. Do not automatically change IDs or resend.
-
-`BrowserControlError` contains only a code, optional HTTP status and bounded
-reason. A lost/aborted/timed-out response after dispatch has `replyUnproven: true`;
-read status before offering another action. A known refusal does not clear any
-earlier responsibility. Neither HTTP 202, expiry, iframe closure nor native
-browser closure proves handback. Replay responses never reconstruct a viewer.
-
-`BrowserViewer` is a TypeScript interface for a returned handle, not a runtime
-constructor. Obtain it from a fresh `acquire` response; do not use `new` or
-`instanceof`. Calling `stopInput()` before attachment permanently prevents that
-handle from attaching.
-
-The viewer helper permits the embedded page's forms, validates both message
-source and exact origin, and burns its token after one delivery. Expiry stops
-input and hides the frame while leaving its cleanup connection alive. Call
-`stopInput()` on stale/unknown status and before handback. On user/tenant/Session
-changes, cancel outstanding calls, discard late replies, and dispose the old
-viewer; the server retains any unresolved responsibility. Never log tokens,
-Preview URLs, page data or form input; do not store a viewer in persistent state.
-Grant serialization/Node inspection is redacted, but application memory and the
-authorized iframe are intentionally within the trusted user's boundary.
-
-Ordinary API-key users can only query status through
-`AgentMatrix.sessions.browserControl.get(sessionId)` in the data-plane package.
-No API-key method acquires human control.
+Omitting `namespaceId` uses the deployment's ordinary API-key default namespace.
+The SDK sends only Bearer authentication, the contract version and the optional
+namespace, with `credentials: omit`. It never exchanges the key for a user JWT.
+A key authorizes its owner, not arbitrary users of your application: your backend
+must enforce its own Session access checks before returning a viewer capability.
+
+## Frontend with the transferred capability
+
+```ts
+import { createBrowserViewer } from "@agentmatrix.pro/browser-sdk";
+
+// Received from your authenticated backend; never contains the API key.
+const viewer = createBrowserViewer(response.viewer_access);
+viewer.attach(iframe); // once, on a deployment-approved parent origin
+// Keep viewer and the original control_id in memory for handback.
+```
+
+`takeAccess()` consumes an unused handle once and returns `{ url, token,
+expires_at }`. The returned object intentionally contains secrets; ordinary
+handle serialization and Node inspection remain redacted. After transfer, the
+original handle can neither attach nor export again. `createBrowserViewer`
+validates and copies that capability; it does not mint, renew, reacquire or prove
+server authorization. Do not duplicate it for multiple clients or put it in a
+URL, log, localStorage, sessionStorage or persistent application state.
+
+The helper binds both message source and exact viewer origin, delivers the token
+once, and keeps it out of the iframe URL. The Preview URL itself is sensitive.
+Grant expiry stops input and hides the frame while leaving the cleanup connection
+alive. Use `viewer.expiresAt`, together with the latest lease, for local input
+expiry. On unknown/stale state, also call `stopInput()`.
+
+## Existing Workspace authentication
+
+Workspace applications can continue to call the same client directly with their
+current authenticated user/scope context:
+
+```ts
+const context = { userJWT, tenantId, namespaceId, apiKeyId, sessionId, csrfToken };
+const current = await control.get(context);
+// acquire/release use the same intent fields as the backend API-key example.
+```
+
+This selects the Workspace routes with `credentials: include`. The key **ID** is
+not a key secret; mutations require the existing matching CSRF cookie/header.
+The SDK does not sign users in, refresh credentials, select tenants/keys, create
+browsers or configure CORS/cookies. Mixing API-key and JWT context fields is
+rejected before transport.
+
+## Handback and failed replies
+
+On explicit handback, first call `viewer.stopInput()` on the frontend. Keep the
+iframe mounted. Your backend reads a fresh status for the **original control_id**
+and calls `release(context, { operation_id, expected_control_id,
+expected_revision, lease_id })` using that observation. If the control changed,
+discard the old intent rather than switching it to another browser.
+
+A `202` or `revoking` state retains responsibility: the iframe must receive the
+Guest's real clear challenge. After confirmed Agent handback, call
+`viewer.dispose()`. When `allowed_actions` includes `release`, offer an explicit
+**Continue handback** action using a fresh observation and a new user intent.
+Do not automatically change operation IDs or resend mutations. A replay never
+reconstructs a viewer; `takeAccess()` cannot recover a lost response.
+
+Each `get`, `acquire` or `release` makes one HTTP attempt, with no implicit retry,
+authentication refresh, polling or generated operation ID. Defaults are a
+15-second read and 200-second mutation total deadline; per-call
+`{ signal, timeoutMs }` includes headers and the complete body. An injected
+`fetch` must also avoid hidden retries. A proxy in your application must allow
+this mutation budget.
+
+`BrowserControlError` exposes only a bounded code, optional status and reason.
+After dispatch, a lost, timed-out or cancelled reply has `replyUnproven: true`:
+read state before offering another action. A refusal cannot clear earlier debt.
+The legacy reason `browser_control_human_required` also covers insufficient
+API-key owner/scope/current authority; it does not require an API-key caller to log in.
+HTTP 202, expiry, iframe closure and native browser closure do not prove handback.
+
+`BrowserViewer` is a TypeScript interface, with no runtime constructor or
+`instanceof` value. `stopInput()` before attachment permanently prevents that
+handle from attaching or transferring. `dispose()` is local teardown, not server
+cleanup proof. On user, tenant or Session changes, cancel calls, discard late
+replies and dispose the old viewer; the server retains unresolved responsibility.
+
+The root data-plane SDK still provides the convenient read-only
+`AgentMatrix.sessions.browserControl.get(sessionId)`. Use this separate browser package
+for API-key or Workspace control and iframe handling; Tenant Management grants
+no browser control.

package/dist/index.d.ts

@@ -123,6 +123,8 @@ type components = {
         };
     };
     parameters: {
+        /** @example ssn_01HX... */
+        SessionId: string;
         /** @description Tenant selected in the User Dashboard resource URL. Identity verifies that the authenticated user has an active membership in this tenant before forwarding to canonical data-plane APIs. */
         WorkspaceTenantId: string;
         /** @example default */
@@ -145,6 +147,10 @@ type components = {
     pathItems: never;
 };
 
+/** Sensitive short-lived capability. Deliver only to your authenticated frontend; never log or store it. */
+type BrowserViewerAccess = components["schemas"]["BrowserViewerAccess"];
+/** Import a capability delivered by your own trusted backend, without exposing its API key. */
+declare function createBrowserViewer(access: BrowserViewerAccess): BrowserViewer;
 /** Structural DOM types keep Node clients importable without a DOM global or shim. */
 interface BrowserViewerMessage {
     source: unknown;
@@ -173,6 +179,8 @@ interface BrowserViewerFrame {
 /** Acquired handle only; no public constructor or runtime BrowserViewer export. */
 interface BrowserViewer {
     readonly expiresAt: string;
+    /** Consume once for an authenticated backend-to-frontend response. The returned value contains secrets. */
+    takeAccess(): BrowserViewerAccess;
     /** Attach once, before the iframe loads. */
     attach(frame: BrowserViewerFrame): void;
     /** Stop local input while retaining the iframe for the Guest's actual clear ACK. */
@@ -201,6 +209,17 @@ interface BrowserControlMutationContext extends BrowserControlContext {
     /** Must match the browser's ariadra_csrf_token cookie on the Gateway origin. */
     csrfToken: string;
 }
+/** Server-side API-key context. Never pass this credential to a user browser. */
+interface BrowserControlAPIKeyContext {
+    apiKey: string;
+    sessionId: string;
+    /** Omission uses the key's default namespace routing. */
+    namespaceId?: string;
+    userJWT?: never;
+    tenantId?: never;
+    apiKeyId?: never;
+    csrfToken?: never;
+}
 interface BrowserControlRequestOptions {
     signal?: AbortSignal;
     /** Total budget including the complete response body. Defaults to 15s read / 200s mutation. */
@@ -223,13 +242,13 @@ interface BrowserControlClientOptions {
     fetch?: typeof globalThis.fetch;
 }
 
-/** Thin user-authorized client. No cached context, automatic reads, retries, grants or operation IDs. */
+/** Owner-authorized client. No cached context, automatic reads, retries, grants or operation IDs. */
 declare class BrowserControlClient {
     #private;
     constructor(options: BrowserControlClientOptions);
-    get(context: BrowserControlContext, options?: BrowserControlRequestOptions): Promise<BrowserControlResult>;
-    acquire(context: BrowserControlMutationContext, intent: AcquireBrowserControlRequest, options?: BrowserControlRequestOptions): Promise<BrowserControlAcquisition>;
-    release(context: BrowserControlMutationContext, intent: ReleaseBrowserControlRequest, options?: BrowserControlRequestOptions): Promise<BrowserControlResult>;
+    get(context: BrowserControlContext | BrowserControlAPIKeyContext, options?: BrowserControlRequestOptions): Promise<BrowserControlResult>;
+    acquire(context: BrowserControlMutationContext | BrowserControlAPIKeyContext, intent: AcquireBrowserControlRequest, options?: BrowserControlRequestOptions): Promise<BrowserControlAcquisition>;
+    release(context: BrowserControlMutationContext | BrowserControlAPIKeyContext, intent: ReleaseBrowserControlRequest, options?: BrowserControlRequestOptions): Promise<BrowserControlResult>;
 }
 
 type BrowserControlFailure = "invalid_input" | "aborted" | "timeout" | "transport_unproven" | "response_unproven" | "refused";
@@ -246,8 +265,8 @@ declare class BrowserControlError extends Error {
     constructor(code: BrowserControlFailure, replyUnproven: boolean, status?: number | undefined, reason?: BrowserControlErrorReason | undefined);
 }
 
-declare const CONTRACT_VERSION = "0.159.1";
+declare const CONTRACT_VERSION = "0.160.0";
 
-declare const BROWSER_SDK_VERSION = "0.1.0-rc.1";
+declare const BROWSER_SDK_VERSION = "0.1.0-rc.2";
 
-export { type AcquireBrowserControlRequest, BROWSER_SDK_VERSION, type BrowserControlAcquisition, type BrowserControlAction, BrowserControlClient, type BrowserControlClientOptions, type BrowserControlContext, BrowserControlError, type BrowserControlErrorReason, type BrowserControlFailure, type BrowserControlMutationContext, type BrowserControlReason, type BrowserControlRequestOptions, type BrowserControlResult, type BrowserControlState, type BrowserControlStatus, type BrowserViewer, type BrowserViewerFrame, type BrowserViewerMessage, type BrowserViewerWindow, CONTRACT_VERSION, type ReleaseBrowserControlRequest };
+export { type AcquireBrowserControlRequest, BROWSER_SDK_VERSION, type BrowserControlAPIKeyContext, type BrowserControlAcquisition, type BrowserControlAction, BrowserControlClient, type BrowserControlClientOptions, type BrowserControlContext, BrowserControlError, type BrowserControlErrorReason, type BrowserControlFailure, type BrowserControlMutationContext, type BrowserControlReason, type BrowserControlRequestOptions, type BrowserControlResult, type BrowserControlState, type BrowserControlStatus, type BrowserViewer, type BrowserViewerAccess, type BrowserViewerFrame, type BrowserViewerMessage, type BrowserViewerWindow, CONTRACT_VERSION, type ReleaseBrowserControlRequest, createBrowserViewer };

package/dist/index.js

@@ -15,7 +15,7 @@ var BrowserControlError = class extends Error {
 };
 
 // ../../packages/browser-sdk/src/generated/contract-version.ts
-var CONTRACT_VERSION = "0.159.1";
+var CONTRACT_VERSION = "0.160.0";
 
 // ../../packages/browser-sdk/src/validation.ts
 var identifier = /^[a-zA-Z0-9][a-zA-Z0-9._-]{0,127}$/;
@@ -55,10 +55,27 @@ function secret(v, max) {
   return typeof v === "string" && v.length > 0 && v.length <= max && /^[\x21-\x7e]+$/.test(v);
 }
 function contextPath(c, mutation) {
+  if (record(c) && "apiKey" in c) {
+    if (!keys(c, ["apiKey", "sessionId", "namespaceId"]) || !secret(c.apiKey, 8192) || !id(c.sessionId) || c.namespaceId !== void 0 && (typeof c.namespaceId !== "string" || c.namespaceId.length > 63 || !/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(c.namespaceId)))
+      invalidInput();
+    return `/v1/sessions/${encodeURIComponent(c.sessionId)}/browser-control`;
+  }
   if (!record(c) || !secret(c.userJWT, 8192) || typeof c.tenantId !== "string" || !/^tnt_[0-9A-HJKMNP-TV-Z]{26}$/.test(c.tenantId) || typeof c.apiKeyId !== "string" || !/^ak_[0-9A-HJKMNP-TV-Z]{26}$/.test(c.apiKeyId) || typeof c.namespaceId !== "string" || c.namespaceId.length > 63 || !/^[a-z0-9]([-a-z0-9]*[a-z0-9])?$/.test(c.namespaceId) || !id(c.sessionId) || mutation && !secret(c.csrfToken, 8192))
     invalidInput();
   return `/v1/users/me/resources/t/${encodeURIComponent(c.tenantId)}/n/${encodeURIComponent(c.namespaceId)}/sessions/${encodeURIComponent(c.sessionId)}/browser-control`;
 }
+function validateViewerAccess(value) {
+  if (!record(value) || !keys(value, ["url", "token", "expires_at"]) || typeof value.url !== "string" || value.url.length > 8192 || typeof value.token !== "string" || !/^[a-f0-9]{64}$/.test(value.token) || !date(value.expires_at) || Date.parse(value.expires_at) <= Date.now())
+    invalidInput();
+  try {
+    const url = new URL(value.url);
+    if (!safeURL(url) || url.hash || decodeURIComponent(value.url).includes(value.token))
+      invalidInput();
+  } catch {
+    invalidInput();
+  }
+  return { url: value.url, token: value.token, expires_at: value.expires_at };
+}
 function validateIntent(value, release) {
   if (!record(value) || !keys(value, [
     "operation_id",
@@ -143,6 +160,9 @@ function safeURL(url) {
 }
 
 // ../../packages/browser-sdk/src/viewer.ts
+function createBrowserViewer(access) {
+  return new BrowserViewerHandle(validateViewerAccess(access));
+}
 var BrowserViewerHandle = class {
   expiresAt;
   #url;
@@ -157,6 +177,19 @@ var BrowserViewerHandle = class {
     this.#url = access.url;
     this.#token = access.token;
   }
+  takeAccess() {
+    if (this.#used || !this.#token || Date.parse(this.expiresAt) <= Date.now())
+      throw new BrowserControlError("invalid_input", false);
+    const access = {
+      url: this.#url,
+      token: this.#token,
+      expires_at: this.expiresAt
+    };
+    this.#used = true;
+    this.#url = "";
+    this.#token = void 0;
+    return access;
+  }
   /** Attach once, before the iframe loads. Use the exact Workspace origin approved by the deployment. */
   attach(frame) {
     if (this.#used || !frame.ownerDocument.defaultView || Date.parse(this.expiresAt) <= Date.now()) {
@@ -265,20 +298,25 @@ var BrowserControlClient = class {
     if (options.signal?.aborted)
       throw new BrowserControlError("aborted", false);
     const sessionId = context.sessionId;
+    const apiKey = "apiKey" in context;
     const headers = new Headers({
       accept: "application/json",
-      authorization: `Bearer ${context.userJWT}`,
-      "x-ariadra-api-version": CONTRACT_VERSION,
-      "x-ariadra-current-tenant-id": context.tenantId,
-      "x-ariadra-namespace-id": context.namespaceId,
-      "x-ariadra-dashboard-api-key-id": context.apiKeyId
+      authorization: `Bearer ${apiKey ? context.apiKey : context.userJWT}`,
+      "x-ariadra-api-version": CONTRACT_VERSION
     });
+    if (context.namespaceId !== void 0)
+      headers.set("x-ariadra-namespace-id", context.namespaceId);
+    if (!apiKey) {
+      headers.set("x-ariadra-current-tenant-id", context.tenantId);
+      headers.set("x-ariadra-dashboard-api-key-id", context.apiKeyId);
+    }
     if (mutation) {
       headers.set("content-type", "application/json");
-      headers.set(
-        "x-csrf-token",
-        context.csrfToken
-      );
+      if (!apiKey)
+        headers.set(
+          "x-csrf-token",
+          context.csrfToken
+        );
     }
     const body = frozenIntent ? JSON.stringify(frozenIntent) : void 0;
     const expectedControl = frozenIntent?.expected_control_id;
@@ -306,7 +344,7 @@ var BrowserControlClient = class {
           headers,
           ...body === void 0 ? {} : { body },
           cache: "no-store",
-          credentials: "include",
+          credentials: apiKey ? "omit" : "include",
           redirect: "error",
           signal: controller.signal
         };
@@ -399,6 +437,6 @@ async function readBody(response, signal) {
 }
 
 // src/version.ts
-var BROWSER_SDK_VERSION = "0.1.0-rc.1";
+var BROWSER_SDK_VERSION = "0.1.0-rc.2";
 
-export { BROWSER_SDK_VERSION, BrowserControlClient, BrowserControlError, CONTRACT_VERSION };
+export { BROWSER_SDK_VERSION, BrowserControlClient, BrowserControlError, CONTRACT_VERSION, createBrowserViewer };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentmatrix.pro/browser-sdk",
-  "version": "0.1.0-rc.1",
+  "version": "0.1.0-rc.2",
   "description": "Human-authorized browser control client for AgentMatrix.",
   "homepage": "https://agentmatrix.pro",
   "license": "Apache-2.0",