README

aice-auth — Browser JS / TypeScript SDK

Browser TypeScript client SDK for the aice-auth specification. Talks to an aice-auth issuer’s /auth/login, /auth/refresh, and /auth/logout endpoints, and persists the resulting token bundle in browser storage.

This package is published to npm as @aice-lab/auth-js.

Install

npm install @aice-lab/auth-js

The package targets modern evergreen browsers (last two versions of Chrome, Firefox, Safari, and Edge). It uses the platform fetch and sessionStorage APIs directly — no runtime dependencies.

Quickstart

import { AiceAuthClient } from '@aice-lab/auth-js';

const client = new AiceAuthClient({ issuerBaseUrl: 'https://id.example.com' });

const tokens = await client.login({
  handleType: 'email',
  handle: 'alice@example.org',
  credential: 'correct-horse-battery-staple',
});

console.log(tokens.access_token);

After login succeeds, the client persists the token bundle in sessionStorage and exposes:

• client.getAccessToken() — current access token (or null).
• client.refresh() — rotate the refresh token and replace the stored bundle.
• client.logout() — call the issuer’s logout endpoint and clear storage.

If sessionStorage is unavailable (for example, during server-side rendering), the client transparently falls back to an in-memory store so construction never throws.

Passwordless email sign-in

Passkey-first, with email as an alternate. The user enters an email; the issuer emails a one-time magic link and the SDK returns a short passphrase to show on the originating screen. Opening the link lands on your callback page, where the user confirms the passphrase (type the one missing word) — unless the device is already trusted, in which case the challenge is skipped.

// 1. On the sign-in screen — start the flow and show the passphrase.
const { passphrase } = await client.startEmailAuth(
  'alice@example.org',
  'https://admin.example.org/auth/callback', // must be in the tenant's allowed_return_urls
);
showOnScreen(passphrase); // e.g. "river-stone-cloud-fox-apple"

// 2. On the callback page (the magic link lands here with ?challenge=…):
const resolved = await client.resolveEmailChallenge();
if (resolved.status === 'ok') {
  // trusted device — signed in, bundle persisted. Redirect into the app.
} else {
  // render 5 slots; resolved.visibleParts fills all but resolved.blankIndex,
  // which is an input the user fills from the passphrase on their first screen.
  const answer = await promptForMissingPart(resolved.blankIndex, resolved.visibleParts);
  const result = await client.answerEmailChallenge(answer);
  if (result.status === 'ok') {
    // signed in. Redirect into the app.
  } else if (result.status === 'profile_required') {
    // new user — collect a profile, then finish registration:
    await client.completeEmailRegistration(result.registrationId, {
      fullName: 'Alice Rahman',
      preferredLocale: 'en', // 'en' | 'bn-BD'
    });
  } else {
    // 'failed' — wrong/expired; send the user back to start over.
  }
}

The issuer’s long-lived device-trust token is persisted in localStorage (via the default LocalStorageDeviceTrustStore) so a known device skips the challenge next time; pass deviceTrustStore to override.

Status

The rest of the surface lands as the spec’s conformance categories are wired up.

License

Source: FSL-1.1-Apache-2.0 (see LICENSE and LICENSE.FAQ.md).

Documentation

Full documentation: https://auth.aice-lab.org

Contributing

See CONTRIBUTING.md. All commits require DCO sign-off.

Reporting security issues

See SECURITY.md. Do not open public issues for vulnerabilities.

This is a snapshot generated from GitLab. For the live README, see the project page.