# Keystone Identity UI Components

Reusable native Web Components providing turnkey zero-knowledge authentication, hardware Passkey/WebAuthn onboarding, device delegation, and identity management for ibgib client applications.

---

## 🚀 Overview & Quickstart

Downstream ibgib client applications do not need to build custom authentication screens, passkey genesis modals, or device management dialogs. All Keystone identity UI is encapsulated here as native Custom Elements.

### 1. Registering Components

During client bootstrap (typically in `bootstrap.mts`), register the identity component suite:

```typescript
import { registerStandardIdentityComponents } from '@ibgib/web-gib/dist/ui/component/identity/index.mjs';

// Inside your bootstrap sequence:
await registerStandardIdentityComponents();
```

This registers all seven custom elements with the browser's `customElements` registry and the internal ibgib component service.

### 2. Embedding in HTML / Templates

```html
<!-- Top Header: Displays current user badge, avatar, and quick login/logout actions -->
<header class="app-header">
    <h1>My IbGib App</h1>
    <ibgib-identity-header></ibgib-identity-header>
</header>

<!-- Identity Section / Modal: Complete identity manager view -->
<section id="identity-section" class="hidden">
    <ibgib-identity-manager></ibgib-identity-manager>
</section>
```

---

## 🧩 Component Suite Reference

| Custom Element Tag | Class Meta | Description |
|---|---|---|
| `<ibgib-identity-header>` | `IdentityHeaderComponentMeta` | Compact top-bar badge. Shows active identity name, deterministic color badge, sync status, and triggers login / switch modals. |
| `<ibgib-identity-manager>` | `IdentityManagerComponentMeta` | Full identity dashboard. Lists active identities, delegates, passkeys, and account settings. |
| `<ibgib-keystone-creator>` | `KeystoneCreatorComponentMeta` | Multi-tab genesis wizard supporting Passkeys (WebAuthn), Master Passwords, and SSO onboarding. |
| `<ibgib-keystone-details>` | `KeystoneDetailsComponentMeta` | Deep-dive security inspection card showing challenge pools, algorithm parameters, and audit verification proofs. |
| `<ibgib-add-device>` | `AddDeviceComponentMeta` | Device delegation modal. Generates pairing QR codes or symmetric delegates to authorize secondary phones or laptops. |
| `<ibgib-remove-device>` | `RemoveDeviceComponentMeta` | Revocation modal to securely sever device delegate keys and emit revocation frames. |
| `<ibgib-keystone-scrubber>` | `KeystoneScrubberComponentMeta` | Security utility component to scrub sensitive memory and credentials on logout. |

---

## ⚡ Events & State Integration

The identity components communicate via standard DOM custom events dispatched through the application window / event bus:

* `EVENT_IBGIB_IDENTITY_REQUEST_CHANGE` (`'ibgib-identity-request-change'`): Request to open the identity switcher or creator.
* `EVENT_IBGIB_IDENTITY_CHANGED` (`'ibgib-identity-changed'`): Emitted when a new keystone identity is set as active.
* `EVENT_IBGIB_IDENTITY_UPDATE_AVAILABLE` (`'ibgib-identity-update-available'`): Notifies that an upstream keystone frame has evolved (e.g. new delegate added).

### Sync Service Integration
These components automatically integrate with `KeystoneSyncService` when available to coordinate remote custodian co-signing and multi-device synchronization over WebSockets.

---

## 🎨 Styling & Glassmorphism

All components use native Shadow DOM (or scoped custom element styles) and inherit CSS variables from the application theme:
* `--ibgib-surface`: Card and dialog background color.
* `--ibgib-primary`: Action buttons and active state indicators.
* Dark-mode glassmorphic styling is applied by default, compatible with `apps/space-gib/src/client/style.css`.