@sigid/client

Framework-agnostic TypeScript client for SigID authentication.

Installation

npm install @sigid/client
# or
pnpm add @sigid/client
# or
yarn add @sigid/client

Quick Start

For browser-hosted OAuth login, keep PKCE, state, callback parsing, and hosted logout inside the SDK:

import { createSigIdClient } from "@sigid/client";

// SPA defaults: redirectUri = current page; surface OAuth storage.
const client = createSigIdClient({
  baseURL: "https://auth.example.com",
  oauth: {
    clientId: "public-client-id",
    scopes: ["openid", "profile", "email"],
  },
});

await client.login({ returnTo: "/dashboard" });
const session = await client.handleCallback();

Dedicated callback route:

const client = createSigIdClient({
  baseURL: "https://auth.example.com",
  oauth: {
    clientId: "public-client-id",
    redirectUri: `${window.location.origin}/oauth/callback`,
    scopes: ["openid", "profile", "email"],
  },
});

const session = await client.handleCallback();

On a logout button or explicit user action:

await client.logout();

The lower-level createAuthorizationUrl(), exchangeCode(), and oauthSignOut() methods remain available when an integration needs explicit protocol control. For browser logout, logout() is the golden path: it clears local SDK state and uses the hosted end-session form POST flow so the raw ID token is not placed in a browser-visible URL query string.

Hosted Auth Only

Human sign-in uses hosted OAuth. Browser applications should use login(), handleCallback(), and logout() instead of collecting credentials or one-time codes in application JavaScript.

Configuration

import { SigIdClient } from "@sigid/client";

const client = new SigIdClient({
  // Required: Base URL of your SigID server
  baseURL: "https://auth.example.com",

  // Optional: Base path for auth endpoints (default: "/api/v1/identity")
  basePath: "/api/v1/identity",

  // Optional: Enable cross-tab session sync (default: true)
  broadcastSession: true,

  // Optional: Refresh session on window focus (default: true)
  refetchOnFocus: true,

  // Optional: Refresh session when coming online (default: true)
  refetchOnOnline: true,

  // Optional: Polling interval in ms (default: 0 = disabled)
  refetchInterval: 60000, // 1 minute

  // Optional: Custom headers
  headers: {
    "X-Custom-Header": "value",
  },
});

OAuth/OIDC Extensions

Browser PKCE configuration supports RAR authorizationDetails, OIDC claims, and acrValues for step-up requests. Device-code token polling uses the standard /oauth/token endpoint.

Set oauth.dpop: true to bind hosted OAuth token exchange, refresh, API requests, and /userinfo calls to an in-memory ES256 DPoP key. When the token endpoint requires nonces, the client retries a use_dpop_nonce challenge once with the returned DPoP-Nonce value and stores successful nonce rotations for later token endpoint calls.

const client = new SigIdClient({
  baseURL: "https://auth.example.com",
  oauth: {
    clientId: "app-client",
    redirectUri: "https://app.example.com/callback",
    scopes: ["openid", "offline_access"],
    dpop: true,
  },
});

Resource servers that call validateAccessToken() must pass the request DPoP proof when accepting tokens with cnf.jkt. The replayCheck callback must atomically record proof jti values in shared storage and return true only for first use.

Use createAuthorizationHeaders() when calling application resource APIs. It returns Authorization: Bearer ... by default, or Authorization: DPoP ... plus a fresh DPoP proof when oauth.dpop is enabled.

const headers = await client.createAuthorizationHeaders({
  method: "GET",
  url: "https://app.example.com/api/projects",
});

The client also exposes discovery helpers for protocol-aware integrations:

const discovery = await client.getDiscovery();
const jwks = await client.getJwks();
const resource = await client.getProtectedResourceMetadata();

Server-side JavaScript callers can use registerDynamicClient() and readDynamicClient() for RFC 7591/7592 dynamic client registration. Browser hosted-login flows should use login(), handleCallback(), and logout(). Lower-level callers can still use createAuthorizationUrl(), exchangeCode(), oauthSignOut(), endSession(), and createEndSessionUrl() when they need explicit protocol control.

Use endSession() for protocol-aware RP-initiated logout calls that need to send id_token_hint; it sends the hint in a POST body. Do not stringify, render, log, or store the raw ID token when preparing that request.

createEndSessionUrl() is a URL builder only. It does not read the in-memory OAuth ID token and does not include id_token_hint by default, even when idTokenHint is supplied. Only set unsafeIncludeIdTokenHintInUrl: true when a protocol-aware integration explicitly accepts that URLs are commonly logged, rendered, synced, cached, and stored in browser history. Browser logout buttons should keep using logout().

Wallet Signing Contract

SigID smart-account validators treat their bytes32 message as an already computed digest. For ERC-4337 UserOps this is the canonical EntryPoint userOpHash.

Ed25519 and P-256 wallet integrations must sign those 32 bytes directly as the message. Do not sign the original UserOperation, and do not hash userOpHash again before signing.

import {
  SIGID_WALLET_KEY_TYPES,
  SIGID_WALLET_SIGNATURE_DIGEST_BYTE_LENGTH,
  SIGID_WALLET_SIGNATURE_MESSAGE_KIND,
  type SigIdWalletSignatureInput,
} from "@sigid/client";

const input: SigIdWalletSignatureInput = {
  keyType: "ed25519",
  messageKind: SIGID_WALLET_SIGNATURE_MESSAGE_KIND,
  messageDigest: userOpHashBytes, // exactly 32 bytes
};

if (input.messageDigest.byteLength !== SIGID_WALLET_SIGNATURE_DIGEST_BYTE_LENGTH) {
  throw new Error("SigID wallet signatures require a 32-byte digest");
}

const keyType = SIGID_WALLET_KEY_TYPES[input.keyType];

Session Management

// Get current session
const session = await client.getSession();

// Bypass the client cache
const freshSession = await client.refreshSession();

// Server-side request headers can be forwarded without touching the client cache
const serverSession = await client.getSession({ headers: request.headers });

// List all sessions
const sessions = await client.listSessions();

// Revoke a specific session
await client.revokeSession("session-id");

// Revoke all other sessions
await client.revokeOtherSessions();

// Remove the active account from this browser's account stack
await client.removeAccount(session.user.id);

Event Handling

// Listen for session changes
const unsubscribe = client.on("session-change", (event) => {
  console.log("Session changed:", event.data);
});

// Listen for sign in
client.on("sign-in", (event) => {
  console.log("User signed in:", event.data.user);
});

// Listen for sign out
client.on("sign-out", () => {
  console.log("User signed out");
});

// Clean up
unsubscribe();

Storage Adapters

import {
  SigIdClient,
  LocalStorageAdapter,
  MemoryStorageAdapter,
  SessionStorageAdapter,
} from "@sigid/client";

// SessionStorage (default in browsers; non-secret state only)
const client = new SigIdClient({
  baseURL: "https://auth.example.com",
  storage: new SessionStorageAdapter(),
});

// LocalStorage
const client = new SigIdClient({
  baseURL: "https://auth.example.com",
  storage: new LocalStorageAdapter(),
});

// Memory (session only, lost on refresh)
const client = new SigIdClient({
  baseURL: "https://auth.example.com",
  storage: new MemoryStorageAdapter(),
});

// OAuth access, refresh, and ID tokens are always held in memory only.

SSR Support

The client automatically detects SSR environments and uses a no-op storage adapter. You can also explicitly use the NoopStorageAdapter:

import { SigIdClient, NoopStorageAdapter } from "@sigid/client";

const client = new SigIdClient({
  baseURL: "https://auth.example.com",
  storage: new NoopStorageAdapter(),
});

TypeScript

Full TypeScript support with exported types:

import type {
  User,
  Session,
  SessionResponse,
  SigIdError,
} from "@sigid/client";

License

MIT