npm - @masonitestudios/spartanauth-widgets - Versions diffs - 1.2.1 → 1.4.0 - Mend

@masonitestudios/spartanauth-widgets 1.2.1 → 1.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (4) hide show

package/README.md CHANGED Viewed

@@ -1,222 +1,234 @@
-# SpartanAuth Widgets
-A collection of drop-in web components for authentication, built with [SolidJS](https://www.solidjs.com/) and packaged as custom elements using [`solid-element`](https://github.com/solidjs/solid/tree/main/packages/solid-element). These widgets connect to a [SpartanAuth](https://www.spartanauth.com) backend and can be embedded in any modern web application regardless of framework.
-## Widgets
-| Custom Element | Description |
-|---|---|
-| `<spartan-login>` | Full login form supporting password, WebAuthn (passkeys), OTP/MFA, self-sign-up, and password reset flows |
-| `<spartan-invite>` | Invitation completion form — lets invited users set their password using a one-time code |
-| `<spartan-account-settings>` | Authenticated account settings panel for managing passkeys and MFA registrations (email & SMS) |
-## Installation
-```bash
-npm install @masonitestudios/spartanauth-widgets
-```
-Then import the library in your project (this registers all three custom elements):
-```js
-import '@masonitestudios/spartanauth-widgets';
-```
-The library exposes both UMD (`dist/sa-widgets.umd.js`) and ES module (`dist/sa-widgets.mjs`) builds.
-## Usage
-### Login Widget
-```html
-<spartan-login
-  domain="https://auth.yourdomain.com"
-  sector="your-sector-id"
-  start-mode="password"
-  locale="en"
-  redirect="/app"
-  styles="">
-</spartan-login>
-```
-**Attributes:**
-| Attribute | Default | Description |
-|---|---|---|
-| `domain` | `http://127.0.0.1:11000` | SpartanAuth API base URL |
-| `sector` | *(admin sector)* | Sector ID for your application |
-| `start-mode` | `password` | Initial login mode — `password` or `webauthn` |
-| `locale` | `en` | UI language (`en`, `fr`, `es`, `ja`) |
-| `redirect` | `""` | URL to navigate to after successful login |
-| `styles` | `""` | Custom CSS injected into the widget's shadow DOM |
-**Features:**
-- Password and WebAuthn (passkey) login
-- MFA / OTP challenge flow (email & SMS) with automatic registration picker when multiple methods are enrolled
-- Self-service sign-up (when enabled on the sector)
-- Password reset via emailed code
-- Emits a `spartan-login` CustomEvent on success with `{ token, transactionID }` in `event.detail`
-- Stores the JWT in `localStorage` under `spartan-token`
-**Custom loading overlay (slot):**
-During any loading state (form submission, social login, OAuth callback) an overlay covers the entire widget. You can inject your own loading animation using the named `loading` slot:
-```html
-<spartan-login domain="..." sector="...">
-  <div slot="loading" style="display:flex;align-items:center;gap:8px;">
-    <my-spinner></my-spinner>
-    <span>Signing in…</span>
-  </div>
-</spartan-login>
-```
-The overlay container itself can be styled from outside the shadow DOM via the CSS part `loading-overlay`:
-```css
-spartan-login::part(loading-overlay) {
-  background: rgba(0, 0, 0, 0.4);
-  border-radius: 4px;
-}
-```
-When no slot content is provided the overlay shows a plain "Loading…" text so existing integrations continue to work without any changes.
-> **OAuth callback note:** After a successful social login (OAuth code exchange) the widget stays in its loading state — rather than flashing back to the login form — so the host application has time to handle the `spartan-login` event and remove the element. If the element is not removed within 5 seconds the widget automatically returns to the login form as a fallback.
-### Invite Widget
-```html
-<spartan-invite
-  domain="https://auth.yourdomain.com"
-  sector="your-sector-id"
-  sub="user-sub-from-invite"
-  email="user@example.com"
-  locale="en"
-  redirect="/login">
-</spartan-invite>
-```
-**Attributes:**
-| Attribute | Default | Description |
-|---|---|---|
-| `domain` | `http://127.0.0.1:11000` | SpartanAuth API base URL |
-| `sector` | *(admin sector)* | Sector ID |
-| `sub` | `""` | User ID from the invitation (falls back to `?sub=` URL query param) |
-| `email` | `""` | Invited user's email (displayed as context) |
-| `locale` | `en` | UI language |
-| `redirect` | `""` | URL to navigate to after successful registration |
-| `styles` | `""` | Custom CSS injected into the widget's shadow DOM |
-The widget can also read the OTP code from the URL hash (e.g. `#invite?otp=ABC123`), making it easy to build one-click invite links.
-**Events:** Emits a `spartan-invite-complete` CustomEvent on success with `{ sub, success }` in `event.detail`.
-### Account Settings Widget
-```html
-<spartan-account-settings
-  domain="https://auth.yourdomain.com"
-  sector="your-sector-id"
-  locale="en"
-  redirect="/"
-  show-web-authn="true"
-  redirect-on-unauthenticated="true">
-</spartan-account-settings>
-```
-**Attributes:**
-| Attribute | Default | Description |
-|---|---|---|
-| `domain` | `http://127.0.0.1:11000` | SpartanAuth API base URL |
-| `sector` | *(admin sector)* | Sector ID |
-| `locale` | `en` | UI language |
-| `redirect` | `/` | Redirect target (used when user is not authenticated) |
-| `show-web-authn` | `true` | Show the passkey management section |
-| `redirect-on-unauthenticated` | `true` | Automatically redirect unauthenticated users |
-| `styles` | `""` | Custom CSS injected into the widget's shadow DOM |
-**Features:**
-- List, add, and remove WebAuthn passkeys
-- List, add, validate, and remove MFA registrations (email & SMS OTP)
-- MFA verification modal with one-time code input
-- Reads the JWT from `localStorage` (`spartan-token`) for authenticated API calls
-## Styling
-All widgets render inside Shadow DOM. To override internal styles, pass a CSS string via the `styles` attribute:
-```html
-<spartan-login styles=".login-frame button { background-color: #00f000; }"></spartan-login>
-```
-## Internationalization
-The widgets ship with translations for **English**, **French**, **Spanish**, and **Japanese** (`en`, `fr`, `es`, `ja`). Set the `locale` attribute to switch languages.
-## Project Structure
-```
-library/           → Widget library (publishable package)
-  src/
-    components/
-      login-widget.tsx          → <spartan-login>
-      invite-widget.tsx         → <spartan-invite>
-      auth-settings.tsx         → <spartan-account-settings>
-      spartanToken.ts           → JWT helpers (localStorage)
-      banana.ts                 → i18n setup (banana-i18n)
-    i18n/                       → Translation files (en, fr, es, ja)
-    App.tsx                     → Registers all widgets
-    index.tsx                   → Library entry point
-  vite.config.ts                → Vite library build config
-example/basic-app/ → Example app demonstrating all three widgets
-  index.html                    → Login & invite page
-  app.html                      → Protected page with account settings
-mockup/            → Static HTML/CSS mockups for design reference
-```
-## Development
-### Prerequisites
-- Node.js
-- npm (or pnpm / yarn)
-### Library
-```bash
-cd library
-npm install
-npm run build
-```
-The build outputs to `library/dist/` as both UMD and ESM formats.
-### Example App
-```bash
-cd example/basic-app
-npm install
-npm start
-```
-Opens at [http://localhost:5173](http://localhost:5173). The example links to the library via a local file reference, so build the library first.
-## Key Dependencies
-| Package | Purpose |
-|---|---|
-| [solid-js](https://www.solidjs.com/) | Reactive UI framework |
-| [solid-element](https://github.com/solidjs/solid/tree/main/packages/solid-element) | Custom element wrapper for Solid components |
-| [@github/webauthn-json](https://github.com/nicbarker/webauthn-json) | WebAuthn browser API helpers |
-| [banana-i18n](https://github.com/nicbarker/banana-i18n) | MediaWiki-style i18n |
-| [jwt-decode](https://github.com/nicbarker/jwt-decode) | JWT decoding for token expiry checks |
-| [Vite](https://vitejs.dev/) | Build tool & dev server |
-## License
-[Apache 2.0](LICENSE)
+# SpartanAuth Widgets
+A collection of drop-in web components for authentication, built with [SolidJS](https://www.solidjs.com/) and packaged as custom elements using [`solid-element`](https://github.com/solidjs/solid/tree/main/packages/solid-element). These widgets connect to a [SpartanAuth](https://www.spartanauth.com) backend and can be embedded in any modern web application regardless of framework.
+## Widgets
+| Custom Element | Description |
+|---|---|
+| `<spartan-login>` | Full login form supporting password, WebAuthn (passkeys), email OTP, authenticator-app (TOTP) codes, self-sign-up, password reset, and a breached-password reset prompt |
+| `<spartan-invite>` | Invitation completion form — lets invited users set their password using a one-time code |
+| `<spartan-account-settings>` | Authenticated account settings panel for passwords, passkeys, email MFA, and authenticator apps |
+## Installation
+```bash
+npm install @masonitestudios/spartanauth-widgets
+```
+Then import the library in your project (this registers all three custom elements):
+```js
+import '@masonitestudios/spartanauth-widgets';
+```
+The library exposes both UMD (`dist/sa-widgets.umd.js`) and ES module (`dist/sa-widgets.mjs`) builds.
+## Usage
+### Login Widget
+```html
+<spartan-login
+  domain="https://auth.yourdomain.com"
+  sector="your-sector-id"
+  start-mode="password"
+  locale="en"
+  redirect="/app"
+  styles="">
+</spartan-login>
+```
+**Attributes:**
+| Attribute | Default | Description |
+|---|---|---|
+| `domain` | `http://127.0.0.1:11000` | SpartanAuth API base URL |
+| `sector` | *(admin sector)* | Sector ID for your application |
+| `start-mode` | `password` | Initial login mode — `password` or `webauthn` |
+| `locale` | `en` | UI language (`en`, `fr`, `es`, `ja`) |
+| `redirect` | `""` | URL to navigate to after successful login |
+| `styles` | `""` | Custom CSS injected into the widget's shadow DOM |
+**Features:**
+- Password and WebAuthn (passkey) login
+- MFA / OTP challenge flow (email) with a method picker when more than one second factor is enrolled
+- Authenticator-app (TOTP) codes and one-time recovery codes
+- Authenticator enrollment during sign-in when the sector requires MFA and the user has no second factor yet
+- Self-service sign-up (when enabled on the sector)
+- Password reset via emailed code
+- When a sector requires a reset for a password already known to be breached, sign-in stops on that screen and emails a reset code. The widget does not store a session or continue to another factor
+- Reset, invite, and sign-up show the server's breach and "could not check" messages instead of treating every rejection as a bad code or a generic failure
+- Emits a `spartan-login` CustomEvent on success with `{ token, transactionID }` in `event.detail`
+- Stores the JWT in `localStorage` under `spartan-token`
+**Custom loading overlay (slot):**
+During any loading state (form submission, social login, OAuth callback) an overlay covers the entire widget. You can inject your own loading animation using the named `loading` slot:
+```html
+<spartan-login domain="..." sector="...">
+  <div slot="loading" style="display:flex;align-items:center;gap:8px;">
+    <my-spinner></my-spinner>
+    <span>Signing in…</span>
+  </div>
+</spartan-login>
+```
+The overlay container itself can be styled from outside the shadow DOM via the CSS part `loading-overlay`:
+```css
+spartan-login::part(loading-overlay) {
+  background: rgba(0, 0, 0, 0.4);
+  border-radius: 4px;
+}
+```
+When no slot content is provided the overlay shows a plain "Loading…" text so existing integrations continue to work without any changes.
+> **OAuth callback note:** After a successful social login (OAuth code exchange) the widget stays in its loading state — rather than flashing back to the login form — so the host application has time to handle the `spartan-login` event and remove the element. If the element is not removed within 5 seconds the widget automatically returns to the login form as a fallback.
+### Invite Widget
+```html
+<spartan-invite
+  domain="https://auth.yourdomain.com"
+  sector="your-sector-id"
+  sub="user-sub-from-invite"
+  email="user@example.com"
+  locale="en"
+  redirect="/login">
+</spartan-invite>
+```
+**Attributes:**
+| Attribute | Default | Description |
+|---|---|---|
+| `domain` | `http://127.0.0.1:11000` | SpartanAuth API base URL |
+| `sector` | *(admin sector)* | Sector ID |
+| `sub` | `""` | User ID from the invitation (falls back to `?sub=` URL query param) |
+| `email` | `""` | Invited user's email (displayed as context) |
+| `locale` | `en` | UI language |
+| `redirect` | `""` | URL to navigate to after successful registration |
+| `styles` | `""` | Custom CSS injected into the widget's shadow DOM |
+The widget can also read the OTP code from the URL hash (e.g. `#invite?otp=ABC123`), making it easy to build one-click invite links.
+**Events:** Emits a `spartan-invite-complete` CustomEvent on success with `{ sub, success }` in `event.detail`.
+### Account Settings Widget
+```html
+<spartan-account-settings
+  domain="https://auth.yourdomain.com"
+  sector="your-sector-id"
+  locale="en"
+  redirect="/"
+  show-web-authn="true"
+  show-totp="true"
+  show-skeleton="true"
+  redirect-on-unauthenticated="true">
+</spartan-account-settings>
+```
+**Attributes:**
+| Attribute | Default | Description |
+|---|---|---|
+| `domain` | `http://127.0.0.1:11000` | SpartanAuth API base URL |
+| `sector` | *(admin sector)* | Sector ID |
+| `locale` | `en` | UI language |
+| `redirect` | `/` | Redirect target (used when user is not authenticated) |
+| `show-web-authn` | `true` | Show the passkey management section |
+| `show-totp` | `true` | Show the authenticator-app section |
+| `show-skeleton` | `false` | Show a placeholder until the first settings load finishes, then paint the sections once |
+| `redirect-on-unauthenticated` | `true` | Automatically redirect unauthenticated users |
+| `styles` | `""` | Custom CSS injected into the widget's shadow DOM |
+**Features:**
+- Change the signed-in password. When that password is in a known breach, the panel shows a warning and can email a reset code
+- List, add, and remove WebAuthn passkeys
+- List, add, validate, and remove MFA registrations (email & SMS OTP)
+- List, add, and remove authenticator apps. Setup shows a QR code and the shared secret once, then the one-time recovery codes the first time the user enrolls
+- MFA verification modal with one-time code input
+- Reads the JWT from `localStorage` (`spartan-token`) for authenticated API calls
+## Styling
+All widgets render inside Shadow DOM. To override internal styles, pass a CSS string via the `styles` attribute:
+```html
+<spartan-login styles=".login-frame button { background-color: #00f000; }"></spartan-login>
+```
+The settings placeholder uses `.skeleton-line`, `.skeleton-block`, and `.skeleton-row`. Those classes do not share the table or button rules. Recolor the shimmer with `--skeleton-base` and `--skeleton-shine` if the defaults do not match the page.
+## Internationalization
+The widgets ship with translations for **English**, **French**, **Spanish**, and **Japanese** (`en`, `fr`, `es`, `ja`). Set the `locale` attribute to switch languages.
+## Project Structure
+```
+library/           → Widget library (publishable package)
+  src/
+    components/
+      login-widget.tsx          → <spartan-login>
+      invite-widget.tsx         → <spartan-invite>
+      auth-settings.tsx         → <spartan-account-settings>
+      spartanToken.ts           → JWT helpers (localStorage)
+      banana.ts                 → i18n setup (banana-i18n)
+    i18n/                       → Translation files (en, fr, es, ja)
+    App.tsx                     → Registers all widgets
+    index.tsx                   → Library entry point
+  vite.config.ts                → Vite library build config
+example/basic-app/ → Example app demonstrating all three widgets
+  index.html                    → Login & invite page
+  app.html                      → Protected page with account settings
+mockup/            → Static HTML/CSS mockups for design reference
+```
+## Development
+### Prerequisites
+- Node.js
+- npm (or pnpm / yarn)
+### Library
+```bash
+cd library
+npm install
+npm run build
+```
+The build outputs to `library/dist/` as both UMD and ESM formats.
+### Example App
+```bash
+cd example/basic-app
+npm install
+npm start
+```
+Opens at [http://localhost:5173](http://localhost:5173). The example links to the library via a local file reference, so build the library first.
+## Key Dependencies
+| Package | Purpose |
+|---|---|
+| [solid-js](https://www.solidjs.com/) | Reactive UI framework |
+| [solid-element](https://github.com/solidjs/solid/tree/main/packages/solid-element) | Custom element wrapper for Solid components |
+| [@github/webauthn-json](https://github.com/nicbarker/webauthn-json) | WebAuthn browser API helpers |
+| [banana-i18n](https://github.com/nicbarker/banana-i18n) | MediaWiki-style i18n |
+| [jwt-decode](https://github.com/nicbarker/jwt-decode) | JWT decoding for token expiry checks |
+| [Vite](https://vitejs.dev/) | Build tool & dev server |
+## License
+[Apache 2.0](LICENSE)