Installation & Setup

このコンテンツはまだ日本語訳がありません。

Installation

npm install @authrim/core

Or with other package managers:

pnpm add @authrim/core
yarn add @authrim/core

Provider Architecture

@authrim/core is platform-agnostic. It requires three provider implementations to interface with the runtime environment:

Provider	Interface	Purpose
`crypto`	`CryptoProvider`	Random bytes, SHA-256, PKCE code challenge generation
`storage`	`AuthrimStorage`	Persistent key-value storage for tokens, state, and nonce
`http`	`HttpClient`	HTTP requests to the authorization server

Implementing Providers

CryptoProvider

import type { CryptoProvider } from '@authrim/core';

const cryptoProvider: CryptoProvider = {
  async randomBytes(length: number): Promise<Uint8Array> {
    return crypto.getRandomValues(new Uint8Array(length));
  },

  async sha256(data: string): Promise<Uint8Array> {
    const encoder = new TextEncoder();
    const buffer = await crypto.subtle.digest('SHA-256', encoder.encode(data));
    return new Uint8Array(buffer);
  },

  async generateCodeVerifier(): Promise<string> {
    const bytes = crypto.getRandomValues(new Uint8Array(32));
    return base64urlEncode(bytes);
  },

  async generateCodeChallenge(verifier: string): Promise<string> {
    const encoder = new TextEncoder();
    const digest = await crypto.subtle.digest('SHA-256', encoder.encode(verifier));
    return base64urlEncode(new Uint8Array(digest));
  },
};

AuthrimStorage

import type { AuthrimStorage } from '@authrim/core';

// Example: localStorage-based implementation
const storageProvider: AuthrimStorage = {
  async get(key: string): Promise<string | null> {
    return localStorage.getItem(key);
  },

  async set(key: string, value: string): Promise<void> {
    localStorage.setItem(key, value);
  },

  async remove(key: string): Promise<void> {
    localStorage.removeItem(key);
  },

  // Optional methods
  async getAll(): Promise<Record<string, string>> {
    const result: Record<string, string> = {};
    for (let i = 0; i < localStorage.length; i++) {
      const key = localStorage.key(i);
      if (key) result[key] = localStorage.getItem(key) ?? '';
    }
    return result;
  },

  async clear(): Promise<void> {
    localStorage.clear();
  },
};

HttpClient

import type { HttpClient, HttpOptions, HttpResponse } from '@authrim/core';

const httpClient: HttpClient = {
  async fetch<T = unknown>(url: string, options?: HttpOptions): Promise<HttpResponse<T>> {
    const response = await globalThis.fetch(url, {
      method: options?.method ?? 'GET',
      headers: options?.headers,
      body: options?.body,
      signal: options?.signal,
    });

    const data = await response.json() as T;

    // Collect response headers
    const headers: Record<string, string> = {};
    response.headers.forEach((value, key) => {
      headers[key] = value;
    });

    return {
      status: response.status,
      statusText: response.statusText,
      headers,
      data,
      ok: response.ok,
    };
  },
};

Client Initialization

Create the client using createAuthrimClient():

import { createAuthrimClient } from '@authrim/core';

const client = await createAuthrimClient({
  // Required
  issuer: 'https://auth.example.com',
  clientId: 'my-client-id',
  crypto: cryptoProvider,
  storage: storageProvider,
  http: httpClient,

  // Optional
  redirectUri: 'https://myapp.com/callback',
  scopes: ['openid', 'profile', 'email'],
  dpop: {
    tokenRequests: true,
    algorithm: 'ES256',
  },
});

The factory initializes storage, state, token, event, logout, and helper clients. OIDC Discovery is fetched lazily by operations that need it, such as discover(), buildAuthorizationUrl(), token exchange, and logout.

Minimal Setup Example

A complete minimal example:

import { createAuthrimClient } from '@authrim/core';
import type { CryptoProvider, AuthrimStorage, HttpClient } from '@authrim/core';

// 1. Implement providers (see sections above)
const crypto: CryptoProvider = { /* ... */ };
const storage: AuthrimStorage = { /* ... */ };
const http: HttpClient = { /* ... */ };

// 2. Create the client
const client = await createAuthrimClient({
  issuer: 'https://auth.example.com',
  clientId: 'my-app',
  crypto,
  storage,
  http,
});

// 3. Start authentication
const { url } = await client.buildAuthorizationUrl({
  redirectUri: 'https://myapp.com/callback',
});

// Redirect the user to `url`

Configuration Options

For the full list of configuration options, see Configuration Reference.

Next Steps

Authorization Code Flow — Implement the login flow
Provider Interfaces — Detailed provider interface specifications
Configuration Reference — All configuration options