Browser SDK

@graypass/browser collects permitted derived evidence and handles supported browser challenge ceremonies. Your backend requests authorization and receives the Assurance Profile; the browser receives collection status and coverage. The documented core package version is 1.0.1.

Install and start

Download the browser core archive and verify it against the checksum manifest before installing. See the installation instructions.

Shell

npm install --ignore-scripts ./graypass-browser-core-1.0.1.tgz

For a bundled application, import the package. For a script-tag integration, serve the package's dist/graypass.min.js from your own application origin. Keep third-party notices when redistributing packaged assets. The core archive contains the observation and challenge runtime with its TypeScript definitions. Install the separate compatible assets in Optional camera when using the camera controller.

TypeScript

import { GrayPass } from '@graypass/browser';

const observer = await GrayPass.observe({
  token: clientToken,
  subject: subjectId,
  endpoint: 'https://app.graypass.org',
  purpose: 'observe',
  onEvidence: (ack) => renderCoverage(ack.coverage),
  onError: (error) => showEvidenceTransportError(error),
});

clientToken and subjectId come from your authenticated backend. The backend must create the token for the signed-in account's subject and the registered page origin. Your application supplies the rendering and error UI functions.

Observe options

Option	Behavior
`token`	Required short-lived subject-bound browser credential
`subject`	Required GrayPass subject ID associated with that token
`endpoint`	API base; default `https://api.graypass.org`; configure explicitly for your environment
`purpose`	`enroll` or `observe`; defaults to `observe`
`windowMs`	Evidence window interval; default 5000 milliseconds
`timeoutMs`	Per-network-attempt timeout including body reading; default 10000 milliseconds
`refreshToken`	Async callback returning a replacement token after HTTP 401; the request is retried once
`onEvidence`	Receives accepted, neutral, or rejected acknowledgement and coverage
`onStatus`	Receives updated collection status
`onError`	Receives transport or shutdown errors
`researchConsent`	Requests consent-bound research behavior; server-side consent requirements still apply
`debug`	Local console diagnostics, off by default
`eyeTracking`	Optional camera controller, started through an explicit user gesture

Enable the research flag after completing the separate consent workflow in Privacy.

Observer methods

Member	Purpose and important behavior
`session`	Session ID to associate with the backend's authenticated action request
`flush()`	Submit the current window; returns an acknowledgement or null when no useful frame is available
`status()`	Retrieve coverage, accepted windows, active seconds, modalities, freshness, limitations, and enrollment readiness
`challengeDetails(id)`	Retrieve public challenge display details, including action information and resource/context digests
`completeChallenge(id, options)`	Perform explicit passkey confirmation or a permitted labeled sandbox simulation
`cancelChallenge(id)`	Cancel an outstanding challenge
`registerPasskey(grant)`	Register using the one-time grant string issued by the authenticated backend
`enableMotion()`	Request permitted device-motion collection from an explicit application interaction
`stop()`	Stop collectors, finish supported session shutdown, and release observer resources

An evidence acknowledgement has status, reason_codes, coverage, evidence_windows, active_seconds, modalities_present, and enrollment_ready. Coverage values are none, sparse, partial, and sufficient. Use these fields to display collection progress; request action authorization through your backend.

Challenge flow

For passkeys, completeChallenge requires a confirm(details) callback that returns a boolean or promise. Display details.display alongside the immutable pending intent supplied by your authenticated backend, and obtain explicit consent before the ceremony. The GrayPass display contains resource/context digests. Present them with the exact destination and meaningful intent fields saved by the backend for that pending request. See the confirmation example. The returned browser receipt identifies the resulting authorization. Send it to your backend, which fetches and verifies the result against its original pending request.

For sandbox-only simulation, use { method: 'sandbox_confirm' } when the returned challenge offers it and the policy permits it. This method uses your application's confirmation UI before completion; the confirm callback belongs to the passkey path. Fetch challengeDetails(id), display the backend’s saved intent with a simulation label, and obtain confirmation before completing it. Keep cancellation as a non-executing path.

Collection and privacy boundaries

The SDK reads transient local key timing, pointer/touch movement, scroll and focus behavior, and supported motion samples to derive summaries. It does not transmit typed characters, clipboard contents, form values, screen contents, raw pointer paths, or raw motion streams through this evidence flow. Optional camera processing keeps images and geometry local and transmits only supported coarse summaries.

Evidence signatures enforce session integrity and replay checks. Protect the evidence-producing page, extensions, and device using the controls in Endpoint security.

Teardown and errors

Stop observation when the authenticated account changes, the session ends, the subject is revoked or deleted, or the application component unmounts. If a camera tracker is shared, explicitly stop or dispose it as well; the shared controller has its own lifecycle.

Display collection status and actionable retry guidance. Complete enrollment when the server reports readiness; refresh credentials or start a new session as the response requires. The Quickstart provides a runnable installation and lifecycle example.