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'],
});

The factory function performs OIDC Discovery automatically and returns a fully initialized AuthrimClient instance.

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