@csbc-dev/auth0

@csbc-dev/auth0 is a headless authentication component for the wc-bindable ecosystem.

It is not a visual UI widget. It is an I/O node that connects Auth0 authentication to reactive state:

• <auth0-config>: fetches public boot config (domain, clientId, audience, remoteUrl) from a JSON endpoint and exposes it as bindable state
• <auth0-gate> input / command surface: domain, client-id, trigger, login/logout/token/connect commands
• <auth0-gate> output state surface: authenticated, user, loading, error (+ connected in remote mode)

Authentication state can be expressed declaratively in HTML, without writing OAuth flows, token management, or login/logout glue code in your UI layer.

@csbc-dev/auth0 follows the CSBC (Core/Shell Bindable Component) architecture:

• Core (AuthCore) handles Auth0 SDK interaction, token management, and auth state
• Shells (<auth0-config>, <auth0-gate>, <auth0-session>) connect config, auth state, and remote readiness to the DOM
• frameworks and binding systems consume it through wc-bindable-protocol

@csbc-dev/auth0 spans two CSBC shapes. In local mode it is the Case A shape: the Core itself is browser-anchored because the Auth0 SPA SDK and redirect callback flow require browser globals. In remote mode the element becomes a thin browser-side gatekeeper for authenticated access to server-side Cores, typically paired with <auth0-session>.

Two deployment modes

<auth0-gate> supports two distinct modes. They share the same element and the same bindable surface, but they differ in where the access token lives and what application code can do with it.

Local mode — README-LOCAL.md

Auth0 runs in the browser. Your application reads the token from the element to attach Authorization: Bearer headers to outbound HTTP requests.

• authEl.token returns the current access token.
• await authEl.getToken() returns a fresh token.
• Token is still omitted from the wcBindable surface (not reachable via data-wcs / bind()).

Selected when no mode attribute is set and remote-url is either absent or the empty string "", or explicitly via mode="local". This is the default.

Remote mode — README-REMOTE.md · SPEC-REMOTE.md

<auth0-gate> acts as a gatekeeper to server-side Cores over an authenticated WebSocket. The token is sent only at the WebSocket handshake and during in-band auth:refresh. Application code does not see the token.

• authEl.token returns null.
• authEl.getToken() throws.
• authEl.getTokenExpiry() returns the exp claim for refresh scheduling without exposing token material.
• connected is added to the wcBindable surface (WebSocket transport state).

Selected by mode="remote", or implicitly by setting remote-url to a non-empty value. An empty remote-url="" is treated as unset (see "Empty vs unset remote-url" in README-REMOTE.md), so dynamic bindings that initially resolve to an empty string do not flip the element into remote mode prematurely. mode="remote" overrides this and forces remote mode even when remote-url is empty.

Paired with <auth0-session target="auth" core="app-core">, which owns the three-stage readiness sequence (authenticated → connected → initial sync) and exposes a single ready signal for data-wcs. Core declarations are looked up via registerCoreDeclaration("app-core", decl) at bootstrap.

Install

npm install @csbc-dev/auth0 @auth0/auth0-spa-js

Remote deployments additionally need @wc-bindable/remote.

Developing this package from source: the in-tree package.json pins @wc-bindable/remote as a file: reference to a sibling checkout (../../wc-bindable-protocol/wc-bindable-protocol/packages/remote). Clone the monorepo at that path before npm install if you are working on the package itself. Released artifacts on npm resolve @wc-bindable/remote from the registry; the file: pin is rewritten to a semver range as part of the release procedure (see .claude/skills/release/SKILL.md).

Which doc should I read?

| If you… | Read | |---------|------| | Call fetch('/api/...') from browser JS with a Bearer token | README-LOCAL.md | | Connect to a WebSocket backend that constructs server-side Cores after auth | README-REMOTE.md | | Need the full remote protocol / server handler / error codes / threat model | SPEC-REMOTE.md | | Need to serve Auth0 tenant values from the backend at boot | docs/patterns/server-config-discovery.md |

Error contract (at a glance)

• Auth0 SDK failures (initialize / login / logout / getToken) do not reject — they publish to error / auth0-gate:error and clear loading. Bind the state; do not try / catch these.
• WebSocket I/O failures in remote mode (connect / reconnect / refreshToken) do reject. Wrap these calls, or use <auth0-session> which surfaces failures through its own state.
• Precondition violations (missing domain / client-id, getToken() in remote mode, etc.) throw synchronously.

See README-LOCAL.md §Error contract and README-REMOTE.md §Error contract for details.