Browser-direct JavaScript SDK

The browser-direct SDK lets a tenant application manage M7 Identity sessions from its own browser page. BrowserDirectClient handles endpoint requests, session state and DPoP. The example components supply optional Active Tags jobs, M7 UI dialogs and page markup. The host can use the plain JavaScript client, select individual components, or include the complete page.

Status: Browser Direct/JS 0.1.0 is a tagged ZIP release with checksum and manifest sidecars. The archive passes clean-extraction and regression checks. The owner reports all flows working on HenryGoss.com on 2026-09-25; the exact deployed server revisions were not independently attested. The npm package remains private. The SDK owns the reusable source; the HenryGoss /bd-at/ page is the installed integration site. This guide covers a separate flow from the Web/PHP backend-for-frontend and Active Tags sign-in packages.

Download the ZIP

Download the 0.1.0 ZIP, its SHA-256 sidecar, and its manifest. Verify the checksum before extraction. The ZIP includes the independent examples, complete integration page, SDK modules and optional frontend vendors.

Choose a tool

The SDK ZIP and source checkout contain these examples below examples/ (packages/browser-direct/examples/ in the SDK repository):

Tool Example directory What it demonstrates
Login, signup and logout login/standard/ Password, remembered accounts, federated popup, email code and magic link, recovery, two-factor or recovery-code continuation, pending confirmation, registration and current-account logout. Login, signup and logout are separately includable components.
Account settings account/standard/ Profile, password setup/change/removal, two-factor settings, emails, linked identities and sessions/devices. Its sandbox includes login only to obtain a session.
Token status token-status/standard/ Session refresh, logout and local cleanup, plus token and request diagnostics. Its sandbox includes login only to obtain a session.
All tools together integration/standard/ One host-owned client, the loading modal, session pill and the independent login, logout, signup, token-status and account components on one page.

Each standard example has an index.php visual preview and a local README.md. The component folders contain the reusable PHP, CSS and JavaScript. Keep Active Tags declarations in the markup and let the host provide one client at AT.ctx.browserDirect.client. PHP includes fragments and emits escaped public settings; the JavaScript jobs own interaction and request pipelines.

Prepare an application

  1. Use an application registration that permits browser-direct authentication for the intended tenant and origin. Register the exact HTTPS callback URL on the same origin as the page. Provider sign-in and account linking use that callback; enabled actions still depend on application and tenant policy.
  2. Verify the versioned ZIP against its .sha256 sidecar, extract it, then serve the selected SDK modules and their matching vendor files together. The browser client needs client.js, browser-direct.js, browser-direct-session.js, browser-adapter.js, dpop.js, jwt.js and vendor/m7-js-dpop/. Preserve their relative layout. Active Tags (active-tags.js plus vendor/active-tags/) and M7 UI (ui.js plus vendor/m7-js-lib-ui/) are separate optional artifact groups. The supplied components use both; the core client uses neither.
  3. Serve the chosen components and set their asset paths to the URLs where they are installed. For the complete example, the registered callback is examples/login/standard/login/login-callback.html on that HTTPS origin. Copy its callback files with login, signup or provider linking.
  4. Supply public M7_CLIENT_ID, M7_BROWSER_DIRECT_ENDPOINT and M7_BROWSER_DIRECT_CALLBACK_URI to the example host. Optional settings are M7_SCOPE, comma-separated M7_BROWSER_DIRECT_PROVIDERS and M7_EXAMPLE_BRAND. The host constructs one BrowserDirectClient, awaits loadSession(), and supplies it through AT.ctx.browserDirect.client.

The complete example's index.php shows the literal component includes; bootstrap.js installs Active Tags and M7 UI once; sandbox.js creates the client and handles the components' session and open-dialog events. It passes a host-owned loading modal to the client for renewal of an expired saved session. The SDK classes do not render HTML or open dialogs.

To inspect the extracted ZIP locally, run this from its top-level directory (or packages/browser-direct in the SDK checkout):

php -S 127.0.0.1:8785 -t .

Open http://127.0.0.1:8785/examples/integration/standard/. This is a visual preview: credential actions remain disabled until the example runs on the registered HTTPS origin with public configuration. A local preview does not establish live authentication acceptance; the owner-reported HenryGoss run is the live integration evidence for this release.

Session and security boundaries

Browser-direct requires DPoP. BrowserDirectClient manages proofs and the browser-bound session; callers do not supply a client secret or manually manage private signing keys. The browser adapter uses site-wide cookies, per-tab session storage and an IndexedDB signing key. A host backend that accepts an access token must still validate the token and required proof for its own resource routes. The registered callback, application policy and same-origin checks remain part of the integration.

The provider popup communicates with the original page over a state-bound, same-origin BroadcastChannel. The original client retains PKCE, DPoP and session ownership; tokens and private key material are not sent to the popup. The account-link callback follows the same ownership boundary. Blocked or stalled popups present a retry path without automatically redirecting the host page.

Token status is a diagnostic component. Its Token tab deliberately shows the current access token while selected and clears that display on leaving the tab or closing the modal. Decoded JWT fields are for inspection only; decoding does not verify a signature or claims. The Debug tab limits request records to method, action, status, duration and normalized error code. Restrict access to the Token tab according to your application's needs.

Checks and troubleshooting

Run npm test from packages/browser-direct for the core, component callback and dependency checks. php -l examples/integration/standard/index.php checks the complete page's PHP syntax. The included fixtures simulate browser flows; they do not use a real identity provider or establish production deployment.

If controls remain disabled, first verify the registered HTTPS origin, public client ID, endpoint and exact callback URL. If a configured action still fails, check the application's browser-direct permissions, tenant policy and any provider or mail-delivery configuration needed by that action. Keep the original tab open during a popup or email-link continuation. A missing or expired access token can be renewed from a saved bound session; without one, the host must present sign-in.