@glydi/passkey-core

Framework-agnostic Passkeys/WebAuthn Web Component. Tiny, Shadow-DOM-isolated, themeable via CSS Parts.

Install

Glide is not yet published to npm. Install from a packed tarball or via pnpm link.

Tarball (recommended):

{
  "dependencies": {
    "@glydi/passkey-core": "file:../glide/dist-packs/glydi-passkey-core-0.1.0.tgz"
  },
  "pnpm": {
    "overrides": {
      "@glydi/passkey-core": "file:../glide/dist-packs/glydi-passkey-core-0.1.0.tgz"
    }
  }
}

The pnpm.overrides entry is required so pnpm never tries to fetch the package from the npm registry. See docs/DISTRIBUTION.md for full tarball and pnpm link instructions, including how to produce the tarballs.

Forthcoming: npm install @glydi/passkey-core will be the public form once the package is published. It is not yet available on npm.

Minimal Usage

Import the ./define subpath to register the <biometric-auth-button> custom element, then drop the element into your HTML:

<script type="module">
  import "@glydi/passkey-core/define"; <!-- registers <biometric-auth-button> -->
</script>

<biometric-auth-button mode="auto" label="Sign in with passkey"></biometric-auth-button>

<script type="module">
  const el = document.querySelector("biometric-auth-button");
  el.addEventListener("glide:success", (e) => console.log("user", e.detail.user));
  el.addEventListener("glide:error", (e) => console.warn(e.detail.code));
</script>

SSR warning: The ./define subpath calls customElements.define() — a browser API that does not exist in Node.js or Next.js server runtime. Only import @glydi/passkey-core/define in browser/client-side code. Framework adapters (React, Vue, Svelte) do this safely via dynamic import() inside useEffect/onMount/onMounted.

API

Package exports

This package has two entry points:

| Subpath | Description | |---------|-------------| | @glydi/passkey-core | Side-effect-free. Exports the class and utilities. Safe in SSR. | | @glydi/passkey-core/define | Side-effectful. Imports and immediately calls defineBiometricAuthButton(). Browser-only. |

Key exports

BiometricAuthButton — the custom element class (HTMLElement subclass). Use this if you need a reference to the class itself (e.g. to extend it or inspect its type).

defineBiometricAuthButton(tagName?) — idempotently registers the element under tagName (defaults to "biometric-auth-button"). Safe to call multiple times. Use this instead of the ./define subpath when you want explicit control over when registration happens.

TAG_NAME — the string "biometric-auth-button".

startConditionalUI(options) — starts passkey autofill (conditional mediation) for a login page that has an <input autocomplete="username webauthn">. Returns a ConditionalUIHandle with a started promise and an abort() method. Types: ConditionalUIOptions, ConditionalUIHandle.

base64urlToBuffer(str) / bufferToBase64url(buf) — base64url codec exported for consumers doing custom WebAuthn flows.

DEFAULT_ENDPOINTS — the canonical API endpoint paths:

const DEFAULT_ENDPOINTS: GlideEndpoints = {
  registerBegin:      "/api/passkey/register-begin",
  registerFinish:     "/api/passkey/register-finish",
  authenticateBegin:  "/api/passkey/authenticate-begin",
  authenticateFinish: "/api/passkey/authenticate-finish",
};

Re-exported types

AuthMode, AuthPhase, GlideUser, AuthResult, GlideError, GlideEndpoints, GlideRunConfig, GlideEventMap

<biometric-auth-button> element

HTML attributes:

| Attribute | Type | Description | |-----------|------|-------------| | mode | "auto" \| "signin" \| "signup" | Auth mode. Default "auto". | | username | string | Username hint for registration/conditional UI. | | label | string | Button label text. | | disabled | boolean attr | Disables the button. | | prime | boolean attr | Show a pre-prompt explainer before the OS biometric sheet. | | prime-title | string | Title for the priming panel. | | prime-body | string | Body text for the priming panel. | | prime-continue | string | Continue button label in the priming panel. | | prime-cancel | string | Cancel button label in the priming panel. | | fallback-href | string | URL of a recovery page (e.g. magic-link). Shown on unsupported/error. | | fallback-label | string | Label for the fallback link. | | register-begin | string | Override endpoint for registerBegin. | | register-finish | string | Override endpoint for registerFinish. | | authenticate-begin | string | Override endpoint for authenticateBegin. | | authenticate-finish | string | Override endpoint for authenticateFinish. |

Valid mode values are "auto", "signin", and "signup" only. Using "register" or "authenticate" is invalid and will silently no-op.

JS properties (not settable as attributes):

• endpoints: Partial<GlideEndpoints> — override one or more endpoint paths.
• fetchOptions: RequestInit — merged into every fetch call (e.g. custom headers).
• phase: AuthPhase — current phase, reflected (read-only).

Phase values: "idle" | "priming" | "unsupported" | "loading" | "authenticating" | "success" | "error"

Events (all bubbles + composed, cross the shadow boundary):

| Event | Detail type | Description | |-------|-------------|-------------| | glide:success | AuthResult ({ user: GlideUser, accessToken?: string }) | Auth succeeded. | | glide:error | GlideError ({ code, message, cause? }) | Auth failed. | | glide:phasechange | { phase: AuthPhase } | Phase transitioned. |

Error codes: "unsupported" | "aborted" | "no_credentials" | "network" | "server_rejected" | "unknown"

CSS Shadow Parts (::part()): button, icon, label, spinner, error, prime, prime-title, prime-body, prime-continue, prime-cancel, fallback

Links

• Root README — architecture overview and styling API
• Quickstart — full Next.js App Router integration walkthrough
• Distribution guide — tarball and pnpm link install details