@uniba-commons/auth

認証・認可サービス (@uniba-commons/auth) のクライアント SDK。

インストール

npm install @uniba-commons/auth

セットアップ

import { createAuth } from "@uniba-commons/auth";

const auth = createAuth({
  apiUrl: process.env.AUTH_API_URL, // 管理者から取得した auth API の URL
});

API ドキュメントは GET <apiUrl>/docs で参照できます。

使い方

Magic Link ログイン

// 1. Magic Link メール送信
await auth.sendMagicLink({
  email: "[email protected]",
  redirectUrl: "https://app.example.com/auth/callback",
});

// 2. コールバックページで Magic Link の token を受け取り、JWT を取得
// Magic Link のコールバック URL に含まれる ?token= を渡す
// 例: https://app.example.com/auth/callback?token=xxx
const { jwt } = await auth.authenticate({
  token: new URL(location.href).searchParams.get("token")!,
});

// JWT の保存・管理はアプリ側で行う
// 例: localStorage.setItem('auth_jwt', jwt)

セッション更新

JWT は短命（5分）。長期セッションは定期的に refresh する。

const { jwt: newJwt } = await auth.refresh({ jwt });

ユーザ情報・権限取得

const user = await auth.getMe({ jwt });
// {
//   id: 'xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx',
//   email: '[email protected]',
//   permissions: [{ id: 'garage:access', description: 'garage アプリへのアクセス' }],
// }

権限チェック

import { can } from "@uniba-commons/auth";

if (can(user, "garage:access")) {
  // ガレージにアクセスできる
}

API リファレンス

エラーハンドリング

各メソッドは API がエラーレスポンスを返した場合に Error を throw する。error.message に API のエラーメッセージが入る。

try {
  await auth.sendMagicLink({ email, redirectUrl });
} catch (e) {
  console.error(e.message); // 'invalid email address' など
}

createAuth(options)

SDK インスタンスを作成する。

| オプション | 型 | 説明 | | ---------- | -------- | --------------------- | | apiUrl | string | auth API のベース URL |

auth.sendMagicLink({ email, redirectUrl })

Magic Link メールを送信する。redirectUrl は Magic Link をクリックしたときのコールバック先 URL。この URL に ?token=xxx が付いた状態でリダイレクトされる。

auth.authenticate({ token })

Magic Link の token を JWT に交換する。

戻り値: { jwt: string }

auth.refresh({ jwt })

JWT を更新する。

戻り値: { jwt: string }

auth.getMe({ jwt })

ログイン中のユーザ情報と権限を取得する。

戻り値:

{
  id: string;
  email: string;
  permissions: {
    id: string;
    description: string;
  }
  [];
}

can(user, permission)

ユーザが指定の permission を持つか確認する。

can(user, "garage:access"); // boolean