Merge pull request #5 from macropygia/feature/provenance-publish

Update docs

Author: macropygia

.github/workflows/checks-pr.yml

@@ -9,11 +9,10 @@ on:
       - 'biome.json'
       - 'package.json'
       - 'tsconfig.json'
-      - '!**/.github/**'
-      - '!**/.vscode/**'
-      - '!**/examples/**'
       - '!**/*.config.ts'
-      - '!./build.ts'
+      - '!**/.*/**'
+      - '!**/__*__/**'
+      - '**/__test__/**'
   pull_request:
     branches:
       - main

.github/workflows/docs.yml

@@ -3,6 +3,10 @@ name: Deploy Docs
 on:
   workflow_dispatch:
 
+defaults:
+  run:
+    shell: bash
+
 jobs:
   deploy_docs:
     permissions:

.github/workflows/publish-dry-run.yml

@@ -7,9 +7,6 @@ defaults:
   run:
     shell: bash
 
-permissions:
-  contents: write
-
 jobs:
   publish_dry_run:
     runs-on: ubuntu-latest

.github/workflows/publish.yml

@@ -14,6 +14,8 @@ permissions:
 jobs:
   publish:
     runs-on: ubuntu-latest
+    permissions:
+      id-token: write
     steps:
       - uses: actions/checkout@v4
 
@@ -39,7 +41,7 @@ jobs:
         with:
           node-version: 20
           registry-url: "https://registry.npmjs.org"
-      - run: npm publish --access public
+      - run: npm publish --provenance --access public
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 

.github/workflows/release-drafter-pr.yml

@@ -10,9 +10,6 @@ defaults:
   run:
     shell: bash
 
-permissions:
-  contents: read
-
 jobs:
   update_release_draft:
     permissions:

.github/workflows/release-drafter-sync-manual.yml

@@ -7,9 +7,6 @@ defaults:
   run:
     shell: bash
 
-permissions:
-  contents: read
-
 jobs:
   update_release_draft_and_version_sync:
     env:

.github/workflows/release-drafter-sync-push.yml

@@ -9,9 +9,6 @@ defaults:
   run:
     shell: bash
 
-permissions:
-  contents: read
-
 jobs:
   update_release_draft_and_version_sync:
     env:

README.ja.md

@@ -6,7 +6,7 @@
 
 - **このパッケージは不安定版です**
   - パッチリリースを含め予告なく破壊的変更が行われる場合があります
-- [TypeDoc](https://macropygia.github.io/elysia-openid-client/)
+- Links: [GitHub](https://github.com/macropygia/elysia-openid-client) / [npm](https://www.npmjs.com/package/elysia-openid-client) / [TypeDoc](https://macropygia.github.io/elysia-openid-client/)
 
 ## 仕様・制限事項
 
@@ -38,23 +38,26 @@ import Elysia from "elysia";
 import { OidcClient } from "elysia-openid-client";
 
 const rp = await OidcClient.create({
-  baseUrl: "https://app.example.com",
-  issuerUrl: "https://issuer.example.com",
+  baseUrl: "https://app.example.com", // RPのURL
+  issuerUrl: "https://issuer.example.com", // OPのURL
   clientMetadata: {
     client_id: "client-id",
     client_secret: "client-secret",
   },
 });
-const endpoints = rp.getEndpoints();
-const hook = rp.getAuthHook();
+const endpoints = rp.getEndpoints(); // エンドポイントプラグイン
+const hook = rp.getAuthHook(); // フックプラグイン
 
-console.log(rp.issuerMetadata);
+console.log(rp.issuerMetadata); // OPのメタデータを表示
 
 new Elysia()
-  .use(endpoints)
-  .guard((app) =>
+  .use(endpoints) // エンドポイントを挿入
+  .guard((app) => // この内側が要認証エリア
     app
-      .use(hook)
+      .use(hook) // 認証・認可用のonBeforeHandleフックを挿入
+      .onBeforeHandle(({ sessionStatus, sessionClaims }) => {
+        // ユーザー名・メール・グループ等による認可処理
+      })
       .get("/", ({ sessionStatus }) => sessionStatus ? "Logged in" : "Restricted")
       .get("/status", ({ sessionStatus }) => sessionStatus)
       .get("/claims", ({ sessionClaims }) => sessionClaims),
@@ -64,7 +67,7 @@ new Elysia()
   .listen(80);
 ```
 
-- [その他のサンプル](https://github.com/macropygia/elysia-openid-client/tree/main/examples)
+- [その他のサンプル](https://github.com/macropygia/elysia-openid-client/tree/main/__examples__)
 
 ## 設定
 
@@ -105,29 +108,87 @@ const rp = await OidcClient.create(options);
 - [OIDCClientLogger](https://macropygia.github.io/elysia-openid-client/interfaces/types.OIDCClientLogger.html)
   - 本文書の `ロガー` の項を参照
 - `ClientMetadata`
-  - `openid-client` の [型定義](https://github.com/panva/node-openid-client/blob/main/types/index.d.ts)
+  - `openid-client` の [`ClientMetadata` の型定義](https://github.com/panva/node-openid-client/blob/main/types/index.d.ts)
   - および `OpenID Connect Dynamic Client Registration 1.0` の [Client Metadata](https://openid.net/specs/openid-connect-registration-1_0.html#ClientMetadata) の章を参照
 - `AuthorizationParameters`
-  - `openid-client` の [型定義](https://github.com/panva/node-openid-client/blob/main/types/index.d.ts)
+  - `openid-client` の [`AuthorizationParameters` の型定義](https://github.com/panva/node-openid-client/blob/main/types/index.d.ts)
   - および `OpenID Connect Core 1.0` の [Authentication Request](https://openid.net/specs/openid-connect-core-1_0.html#AuthRequest) の章を参照
 
+## エンドポイント
+
+- ElysiaJSプラグインとしてのメタデータ
+  - 名称: `elysia-openid-client-endpoints`
+  - [シード](https://elysiajs.com/essential/plugin#plugin-deduplication): `settings.pluginSeed` 、未指定なら `issuerUrl`
+- 参照: [openid-client API Documentation - Client](https://github.com/panva/node-openid-client/blob/main/docs/README.md#client)
+
+### 内訳
+
+- Login (GET: `/auth/login` )
+  - `openid-client` の `client.authorizationUrl` を呼び出す
+  - OPの認証エンドポイントにリダイレクトする
+- Callback (GET: `/auth/callback` )
+  - `openid-client` の `client.callbackParams` と `client.callback` を呼び出す
+  - OPからリダイレクトされた後、ログイン完了ページにリダイレクトする
+- Logout (GET: `/auth/logout` )
+  - `openid-client` の `client.endSessionUrl` を呼び出す
+  - OPのログアウトエンドポイントにリダイレクトする
+- UserInfo (ALL: `/auth/userinfo` )
+  - `openid-client` の `client.userinfo` を呼び出す
+  - レスポンス（ユーザー情報）をそのまま返す
+- Introspect  (ALL: `/auth/introspect` )
+  - `openid-client` の `client.introspect` を呼び出す
+  - レスポンスをそのまま返す
+- Refresh (ALL: `/auth/refresh` )
+  - `openid-client` の `client.refresh` を呼び出す
+  - ID Tokenに含まれるクレームを返す
+- Resource (GET: `/auth/resource?url=<resource-url>`)
+  - `openid-client` の `client.requestResource` を呼び出す
+  - リソースプロバイダーからのレスポンスを返す
+- Revoke (ALL: `/auth/revoke` )
+  - `openid-client` の `client.revoke` を呼び出す
+  - `204` を返す
+- Status (ALL: `/auth/status` )
+  - 内部データベースからセッションステータスを取得する
+  - OPにはアクセスしない
+- Claims (ALL: `/auth/claims` )
+  - ID Tokenに含まれるクレームを取得する
+  - OPにはアクセスしない
+
+## フック
+
+`onBeforeHandle` フックでCookieを元にセッションが有効かどうかを判断し、 [`resolve` フック](https://elysiajs.com/life-cycle/before-handle.html#resolve)から `sessionStatus` と `sessionClaims` を返す。
+
+- セッションが有効な場合
+  - `sessionStatus` : セッションステータス
+    - 参照: [OIDCClientSessionStatus](https://macropygia.github.io/elysia-openid-client/interfaces/types.OIDCClientSessionStatus.html)
+  - `sessionClaims` : ID Token Claims
+    - 参照: [`IdTokenClaims` type definition](https://github.com/panva/node-openid-client/blob/main/types/index.d.ts) of `openid-client`.
+    - 参照: `OpenID Connect Core 1.0` の [Claims](https://openid.net/specs/openid-connect-core-1_0.html#Claims) 及び [IDToken](https://openid.net/specs/openid-connect-core-1_0.html#IDToken) の章
+- セッションが無効な場合
+  - `loginRedirectUrl` にリダイレクト
+  - `disableRedirect` が `true` の場合は `sessionStatus` , `sessionClaims` 共に `null` になる
+- ElysiaJSプラグインとしてのメタデータ
+  - 名称: `elysia-openid-client-auth-hook`
+  - [シード](https://elysiajs.com/essential/plugin#plugin-deduplication): `settings.pluginSeed` 、未指定なら `issuerUrl`
+- 参照: [AuthHookOptions](https://macropygia.github.io/elysia-openid-client/interfaces/types.AuthHookOptions.html)
+
 ## データアダプター
 
 セッション情報の保存方法を定義したもの。
 
 ```typescript
-const client = await OidcClient.create({
+const rp = await OidcClient.create({
   //...
-  dataAdapter: <data-adapter>,
+  dataAdapter: OIDCClientDataAdapter,
   //...
 })
 ```
 
 - 本パッケージにはSQLite/LokiJS/Lowdb/Redisを使用したデータアダプターが含まれる
 - カスタムデータアダプターを作成可能
-  - 参照: [OIDCClientDataAdapter](https://macropygia.github.io/elysia-openid-client/interfaces/types.OIDCClientDataAdapter.html)
 - 既定ではSQLiteのインメモリーモードが使用される
 - 複数のOPを使用する場合は一つのデータアダプターを共有する
+- 参照: [OIDCClientDataAdapter](https://macropygia.github.io/elysia-openid-client/interfaces/types.OIDCClientDataAdapter.html)
 
 ### SQLite
 
@@ -215,7 +276,7 @@ export class MyDataAdapter implements OIDCClientDataAdapter {
 
 // app.ts
 import { MyDataAdapter } from 'path/to/MyDataAdapter';
-const client = await OidcClient.create({
+const rp = await OidcClient.create({
   //...
   dataAdapter: new MyDataAdapter(),
   //...
@@ -227,9 +288,9 @@ const client = await OidcClient.create({
 ロガーを定義する。
 
 ```typescript
-const client = await OidcClient.create({
+const rp = await OidcClient.create({
   //...
-  logger: <logger>,
+  logger: OIDCClientLogger | null,
   //...
 })
 ```
@@ -238,6 +299,7 @@ const client = await OidcClient.create({
   - 変換すれば任意のロガーを使用可能
 - 省略すると `consoleLogger("info")` を使用する
 - `null` に設定するとログを出力しない
+- 参照: [OIDCClientLogger](https://macropygia.github.io/elysia-openid-client/interfaces/types.OIDCClientLogger.html)
 
 ### ログレベルポリシー
 
@@ -257,16 +319,17 @@ const client = await OidcClient.create({
 
 ### pinoの使用
 
+直接[pino](https://getpino.io/)を割り当てられる
+
 ```bash
 bun add pino
 ```
 
 ```typescript
 import pino from "pino";
-const logger = pino();
-const client = await OidcClient.create({
+const rp = await OidcClient.create({
   //...
-  logger,
+  logger: pino(),
   //...
 })
 ```
@@ -277,8 +340,8 @@ const client = await OidcClient.create({
 
 ```typescript
 import { consoleLogger } from "elysia-openid-client/loggers/consoleLogger";
-const minimumLogLevel = "debug";
-const client = await OidcClient.create({
+const minimumLogLevel = "debug"; // pinoと同様
+const rp = await OidcClient.create({
   //...
   logger: consoleLogger(minimumLogLevel),
   //...
@@ -287,68 +350,8 @@ const client = await OidcClient.create({
 
 ### カスタムロガー
 
-`consoleLogger` の実装を参照のこと。
-
-## エンドポイント
-
-- Login (GET: `/auth/login` )
-  - `openid-client` の `client.authorizationUrl` を呼び出す
-  - OPの認証エンドポイントにリダイレクトする
-- Callback (GET: `/auth/callback` )
-  - `openid-client` の `client.callbackParams` と `client.callback` を呼び出す
-  - OPからリダイレクトされた後、ログイン完了ページにリダイレクトする
-- Logout (GET: `/auth/logout` )
-  - `openid-client` の `client.endSessionUrl` を呼び出す
-  - OPのログアウトエンドポイントにリダイレクトする
-- UserInfo (ALL: `/auth/userinfo` )
-  - `openid-client` の `client.userinfo` を呼び出す
-  - レスポンス（ユーザー情報）をそのまま返す
-- Introspect  (ALL: `/auth/introspect` )
-  - `openid-client` の `client.introspect` を呼び出す
-  - レスポンスをそのまま返す
-- Refresh (ALL: `/auth/refresh` )
-  - `openid-client` の `client.refresh` を呼び出す
-  - ID Tokenに含まれるクレームを返す
-- Resouce (GET: `/auth/resource?url=<resource-url>`)
-  - `openid-client` の `client.requestResource` を呼び出す
-  - リソースプロバイダーからのレスポンスを返す
-- Revoke (ALL: `/auth/revoke` )
-  - `openid-client` の `client.revoke` を呼び出す
-  - `204` を返す
-- Status (ALL: `/auth/status` )
-  - 内部データベースからセッションステータスを取得する
-  - OPにはアクセスしない
-- Claims (ALL: `/auth/claims` )
-  - ID Tokenに含まれるクレームを取得する
-  - OPにはアクセスしない
-
-## フック
-
-`onBeforeHook` フックでCookieを元にセッションが有効かどうかを判断し、 [`resolve` フック](https://elysiajs.com/life-cycle/before-handle.html#resolve)から `sessionStatus` と `sessionClaims` を返す。
-
-- セッションが有効な場合
-  - `sessionStatus` : セッションステータス
-  - `sessionClaims` : ID Token Claims
-- セッションが無効な場合
-  - `loginRedirectUrl` にリダイレクト
-  - `disableRedirect` が `false` の場合は `sessionStatus` , `sessionClaims` 共に `null`
-- 設定
-  - [AuthHookOptions](https://macropygia.github.io/elysia-openid-client/interfaces/types.AuthHookOptions.html).
-
-```typescript
-const rp = await OidcClient.create(clientOptions);
-
-const hookOptions: AuthHookOptions = {
-  scope: "scoped",
-  loginRedirectUrl: "/auth/login",
-  disableRedirect: false,
-  autoRefresh: true,
-}
-
-const hook = rp.getAuthHook(hookOptions);
-```
+[OIDCClientLogger](https://macropygia.github.io/elysia-openid-client/interfaces/types.OIDCClientLogger.html)の型定義と `consoleLogger` の実装を参照のこと。
 
 ## Contributing
 
-本リポジトリに提供するコードを `GitHub Copilot` で生成する場合、必ず `Suggestions matching public code` オプションを `Block` に設定すること。
-同様のオプションが存在する類似のサービスを使用する場合も同様。
+本リポジトリに提供するコードを `GitHub Copilot` で生成する場合、必ず `Suggestions matching public code` オプションを `Block` に設定すること。同様のオプションが存在する類似のサービスを使用する場合も同様。