Cobrowse

@investec/plugins-cobrowse wraps the Cobrowse.io Web SDK behind a small, lazy-loaded lifecycle. It deliberately does not accept Investec cookies, access tokens, capabilities, AuthResponse data, or Invsy state.

Package

Warning: The platform owns installation of released plugin versions. Consumer applications use the approved Invsy Cobrowse surface and must not install this package directly. See Plugin change governance for the platform-only default that applies to every plugin in this repository.

npm install --save @investec/plugins-cobrowse

The platform owns installation of released plugin versions. Consumer applications use the approved Invsy Cobrowse surface and must not install this package directly.

Parent shell controller

The authenticated shell supplies the licence and policy. The plugin controller owns SDK lifecycle, session codes, iframe bridge orchestration, and shared session state:

import { CobrowsePlatformController } from '@investec/plugins-cobrowse';

const cobrowse = new CobrowsePlatformController({
  license: import.meta.env.VITE_COBROWSE_LICENSE_KEY,
  isEnabled: () => featureToggleEnabled,
  isAuthorized: () => loggedIn && permittedClientType,
  getFrames: () => Array.from(document.querySelectorAll('web-core iframe')),
  getTrustedOrigins: () => approvedFeatureOrigins,
  isApprovedOrigin: isApprovedInvestecOrigin,
  getCustomData: () => ({ user_id: authenticatedZetaId }),
  parentConfiguration: {
    registration: false,
    privateByDefault: true,
    unredactedViews: ['#sideloadCenter', '#cobrowseSessionDialog'],
  },
});

const code = await cobrowse.createSessionCode();

Generate the code only after the authenticated customer chooses to start a session. The plugin follows the Web SDK order of client(), start(), then createSessionCode(). Six-digit codes expire after approximately 20 minutes, and the SDK must not be used as a platform keep-alive.

The plugin does not import platform environment variables, authentication state, feature state, or routing. Those values are passed through callbacks so the package remains independent of the host platform implementation.

allowIFrameStart is available for standalone integrations that intentionally run inside an iframe. allowHeadless exists only to support automated plugin verification and must remain disabled in production platform configuration.

customData is passed to Cobrowse before startup so permitted identifiers can be searched in the agent dashboard. Investec Online supplies only the authenticated Zeta ID as user_id. Never send an authentication token, cookie, capability payload, ID number, bank account number, email address, or another unnecessary customer attribute.

Cross-origin feature frame

Cobrowse requires its SDK in both sides of a cross-document iframe. The child does not receive or configure the licence. On Investec Online this bootstrap is owned by the shared Invsy SDK and activated by the platform shell; consumer applications must not duplicate this lifecycle code. The equivalent internal configuration is:

const bridge = new InvestecCobrowse();

bridge.configure({
  mode: 'child',
  trustedOrigins: [approvedParentOrigin],
  registration: false,
  privateByDefault: false,
});

await bridge.start();

Only origins that have passed the shared platform's Investec-host validation may be trusted. Do not use an arbitrary document.referrer origin without validation.

Redaction contract

The parent shell is private by default:

• body is redacted before the SDK starts;
• only elements explicitly reviewed and marked [data-cobrowse-visible] are visible;
• consumers may add narrow unredaction selectors for reviewed, non-sensitive UI;
• the plugin's baseline input, balance, account-number, IBAN, [data-cobrowse-redacted], and [data-cobrowse-private] selectors remain redacted even inside an allowed application surface.

Consumer frames and the standalone plugins demo use block-list mode. Existing content remains visible while the baseline selectors and explicit privacy markers remain redacted.

Anything unredacted must be reviewed for PII, balances, account/card/IBAN numbers, transactions, notifications, documents, QR codes, and authentication data. Dynamic overlays and portal-rendered DOM are part of the same review.

Session and auth boundary

• Start only from a valid authenticated platform state.
• End and stop on logout, invalid session, or transition into an excluded journey.
• Never start on login, MFA, password, security-question, or recovery screens.
• Supply only the approved Zeta ID as Cobrowse user_id; never derive an identifier from rcv_ias, another cookie, or a capability payload.
• Starting Cobrowse cannot elevate a PIN session, call the session service, or extend bank-session inactivity.

Licence configuration

The Web SDK licence is build-time browser configuration. Inject it through the consumer's environment-specific deployment configuration as VITE_COBROWSE_LICENSE_KEY; do not store it in Wrangler session variables, cookies, local storage, capabilities, or source-controlled production values.

Extension boundary

The plugin owns SDK loading, lifecycle, session-code creation, event state, iframe bridge orchestration, protocol constants, and redaction configuration. The shell owns authentication eligibility, the licence, approved-origin discovery, presentation, and analytics. Invsy owns the child bootstrap, dynamic DOM privacy helpers, and parent-delegated session controls.

Ordinary consumers do not implement Cobrowse startup or shutdown. An approved dedicated Cobrowse application may call invsy.cobrowse.startSession(), endSession(), getSessionState(), and onSessionStateChange(); these methods delegate to the parent and never receive the licence. Static reviewed DOM can use data-cobrowse-visible; dynamic content can use the narrow Invsy privacy helpers where declarative markup is not possible.

Extend the shared plugin

Cobrowse is security- and privacy-sensitive. The Web Platform team must approve all package changes before implementation.

Change	Location
SDK lifecycle or redaction defaults	cobrowse/src/lib/cobrowse.ts
Authenticated-shell policy adapter and iframe orchestration	cobrowse/src/lib/platform-controller.ts
Cross-frame message identifiers and payloads	cobrowse/src/lib/protocol.ts
Child runtime behaviour	cobrowse/src/browser/child-runtime.js
Public API	cobrowse/src/index.ts

Do not add trusted origins, unredacted selectors, custom customer data, protocol messages, vendor configuration, or lifecycle behaviour without privacy, security, and platform review. Consumer applications should normally use the approved Invsy Cobrowse contract rather than import this package.

Related pages

• Plugin change governance
• Plugin overview
• Extension patterns
• Livechat