@0account/web

@0account/web

Browser-native OAuth2/OIDC authentication widget for 0account.
Drop in a <zero-account> element — it handles PKCE, QR code, SSE polling, and redirects.

---

Install

npm install @0account/web

Or via CDN (no build step):

<script type="module" src="https://unpkg.com/@0account/web/dist/0account-web.js"></script>

---

Quickstart — Widget

The widget covers the full auth flow for you. Add the element, listen for one event.

<zero-account
  app-id="YOUR_APP_ID"
  redirect-uri="https://yourapp.com/callback"
  finalize-uri="https://yourapp.com/api/auth/finalize"
  scope="openid profile email"
  with-button
></zero-account>

import "@0account/web";

document.querySelector("zero-account")
  .addEventListener("0account-authenticated", (e) => {
    // Code exchange was handled by finalize-uri — you're done.
    console.log("logged in", e.detail);
  });

Your finalize-uri backend receives { code, code_verifier, state, nonce, redirect_uri } as JSON.
Exchange the code with 0account's /oauth/token endpoint there.

Automatic redirect after login (OIDC flow)

Add mode="redirect" and the widget navigates to redirect-uri automatically:

<zero-account
  app-id="YOUR_APP_ID"
  redirect-uri="https://yourapp.com/callback"
  finalize-uri="https://yourapp.com/api/auth/finalize"
  mode="redirect"
  with-button
></zero-account>

The callback URL includes the auth code as a query param and the session token in the hash:

https://yourapp.com/callback?code=…&state=…#za_session_token=…

---

Attributes

---

Events

All events fire on the <zero-account> element with bubbles: true, composed: true.

0account-error reasons

In the default widget flow an expired session is not reported as an error: the widget quietly mints a fresh one so the user can simply tap again.

Dispatch 0account-trigger-open / 0account-trigger-close on document to open/close the widget from anywhere:

document.dispatchEvent(new Event("0account-trigger-open"));

---

Retrieve session data after redirect

In mode="redirect", the callback page needs the PKCE verifier to exchange the code.
Read it with ZeroAccount.getSessionData() — this clears the value from sessionStorage on first call.

import { ZeroAccount } from "@0account/web";

const params = new URLSearchParams(location.search);
const code = params.get("code");
const data = ZeroAccount.getSessionData("YOUR_APP_ID"); // { verifier, nonce }

// Exchange the code on your backend
await fetch("/api/auth/finalize", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    code,
    code_verifier: data.verifier,
    state: params.get("state"),
    nonce: data.nonce,
    redirect_uri: "https://yourapp.com/callback",
  }),
});

---

Cross-subdomain session handoff

When redirecting a user to a different subdomain that also has the <zero-account> widget, include the session token in the URL hash — the widget reads and clears it automatically:

window.location.href = `https://app2.yoursite.com/dashboard#za_session_token=${encodeURIComponent(sessionToken)}`;

---

TypeScript

All types are included. Key exports:

import {
  ZeroAccount,          // Custom Element class
  ZeroAccountEvents,    // Event name constants
} from "@0account/web";

---

License

MIT