# 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](https://m7.org/downloads/m7-identity/browser-direct/0.1.0/m7-identity-browser-direct-0.1.0.zip),
its [SHA-256 sidecar](https://m7.org/downloads/m7-identity/browser-direct/0.1.0/m7-identity-browser-direct-0.1.0.zip.sha256),
and its [manifest](https://m7.org/downloads/m7-identity/browser-direct/0.1.0/m7-identity-browser-direct-0.1.0.zip.manifest.json).
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):

```sh
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.