@aiquants/auth-react-router 0.13.1 → 0.14.0

package/src/admin/server.ts

@@ -1,6 +1,16 @@
-import type { AuthAllowlistEntry, AuthDirectoryMembershipMode, AuthDirectoryStatus, AuthGroup, AuthGroupMember, AuthUser } from "@aiquants/auth-core"
+/**
+ * @module admin/server
+ * @description The loader, action and store contract of the user administration route.
+ * ユーザー管理ルートの loader・action と、その記憶域の契約。
+ *
+ * 権限は intent ごとに要求する CRUD 種別へ写し (`INTENT_ACCESS`)、拒否は画面を落とさず
+ * その操作だけの失敗として返す。上流の候補一覧はこのプロセスから引かず、同期ジョブが書いた
+ * ものを読むだけである。
+ */
+import type { AuthAllowlistEntry, AuthDirectoryCatalogGroup, AuthDirectoryCatalogSnapshot, AuthDirectoryMembershipMode, AuthDirectoryStatus, AuthGroup, AuthGroupMember, AuthUser } from "@aiquants/auth-core"
 import { data } from "react-router"
-import { type PartialUserAdminLabels, resolveUserAdminLabels } from "./labels"
+import { fill as fillLabel } from "./format"
+import { type PartialUserAdminLabels, resolveUserAdminLabels, type UserAdminLabels } from "./labels"
 
 /**
  * Server store interface for managing users, groups, memberships, and allowlists.
@@ -41,19 +51,32 @@ export type UserAdminStore = {
      *
      * リンク後、そのグループの名称と所属は上流が所有する。ロール割当はローカルのままである。
      */
-    linkDirectoryGroup: (groupId: number, data: { provider: string; externalKey: string; membershipMode: AuthDirectoryMembershipMode }) => Promise<void>
+    linkDirectoryGroup: (groupId: number, data: { provider: string; externalId: string; externalKey: string; membershipMode: AuthDirectoryMembershipMode }) => Promise<void>
+    /**
+     * Creates a local group and links it to an upstream group as one indivisible step.
+     * ローカルグループの作成と上流への連携を、分割不可能な 1 手として行う処理。
+     *
+     * ⚠️ **途中で失敗したら何も残してはならない。** 作成だけが成功すると、運用者には「連携に
+     * 失敗した」ではなく「知らないグループが増えた」と見える。実装は 1 つのトランザクションで
+     * 行うこと (作成 → 連携の順に別々の書込を並べると、この不可分性は成立しない)。
+     */
+    createLinkedGroup: (data: { groupKey: string; name: string; description?: string; provider: string; externalId: string; externalKey: string; membershipMode: AuthDirectoryMembershipMode }) => Promise<AuthGroup>
     /** Stops following the upstream, keeping the memberships already projected. 連携の解除。 */
     unlinkDirectoryGroup: (groupId: number) => Promise<void>
     /** Pauses or resumes synchronization for one group. 1 グループの同期を停止・再開する処理。 */
     setDirectorySyncEnabled: (groupId: number, isSyncEnabled: boolean) => Promise<void>
     /**
-     * Queues a synchronization request. 同期要求をキューへ積む処理。
+     * Queues a "sync now" request. 「今すぐ同期」の要求を積む処理。
      *
-     * 上流へ到達できるのは同期ジョブだけなので、web からは要求を残すことしかできない。
+     * ⚠️ 戻り値を `void` にしてはならない。同じ範囲の要求が既に待っているとき、積み増さないのは
+     * 正しい (押した数だけ上流への全件走査が並ぶ) が、それを成功と区別せずに返すと、押しても
+     * 反応しない画面ができる — しかも詰まった 1 行が以後の押下すべてを飲み込む。
      *
-     * @param groupId `null` requests every linked group of the tenant. `null` はテナント全件。
+     * @param groupId Target group, or `null` for the whole tenant. 対象グループ (`null` でテナント全件)。
+     * @param actor Who asked, for the audit record. 要求した主体 (監査記録用)。
+     * @returns Whether it was queued or already waiting. 積んだか、既に待っていたか。
      */
-    requestDirectorySync: (groupId: number | null) => Promise<void>
+    requestDirectorySync: (groupId: number | null, actor: string) => Promise<UserAdminSyncRequestOutcome>
     /** Health of the synchronization, for the header warning. 同期の健全性 (警告表示用)。 */
     getDirectoryStatus: () => Promise<AuthDirectoryStatus>
 }
@@ -97,13 +120,13 @@ export function createInMemoryUserAdminStore(initial?: { users?: AuthUser[]; gro
         },
         async updateUser(id, data) {
             const idx = users.findIndex((u) => u.id === id)
-            if (idx === -1) throw new Error(`User not found: ${id}`)
+            if (idx === -1) throw new UserAdminOperatorError(`User not found: ${id}`)
             users[idx] = { ...users[idx], displayName: data.displayName, email: data.email }
             return users[idx]
         },
         async toggleUserActive(id, isActive) {
             const idx = users.findIndex((u) => u.id === id)
-            if (idx === -1) throw new Error(`User not found: ${id}`)
+            if (idx === -1) throw new UserAdminOperatorError(`User not found: ${id}`)
             users[idx] = { ...users[idx], isActive }
             return users[idx]
         },
@@ -125,7 +148,7 @@ export function createInMemoryUserAdminStore(initial?: { users?: AuthUser[]; gro
         },
         async updateGroup(id, data) {
             const idx = groups.findIndex((g) => g.id === id)
-            if (idx === -1) throw new Error(`Group not found: ${id}`)
+            if (idx === -1) throw new UserAdminOperatorError(`Group not found: ${id}`)
             groups[idx] = { ...groups[idx], name: data.name, description: data.description }
             return groups[idx]
         },
@@ -176,23 +199,26 @@ export function createInMemoryUserAdminStore(initial?: { users?: AuthUser[]; gro
         // 連携面は「結線されていない配備」を表現する形で応答する
         async addAllowlistGroup(groupId, description) {
             const group = groups.find((g) => g.id === groupId)
-            if (!group) throw new Error(`Group not found: ${groupId}`)
+            if (!group) throw new UserAdminOperatorError(`Group not found: ${groupId}`)
             allowlist = [...allowlist, { id: Math.max(...allowlist.map((a) => a.id), 0) + 1, type: "group", groupId, groupKey: group.groupKey, groupName: group.name, description, owner: { kind: "tenant", tenantId: "default" }, readOnly: false }]
         },
         async removeAllowlistGroup(id) {
             allowlist = allowlist.filter((a) => !(a.type === "group" && a.id === id))
         },
         async linkDirectoryGroup() {
-            throw new Error("This in-memory store has no upstream directory; inject a real store to link groups.")
+            throw new UserAdminOperatorError("This in-memory store has no upstream directory; inject a real store to link groups.")
+        },
+        async createLinkedGroup() {
+            throw new UserAdminOperatorError("This in-memory store has no upstream directory; inject a real store to create a linked group.")
         },
         async unlinkDirectoryGroup() {
-            throw new Error("This in-memory store has no upstream directory; inject a real store to unlink groups.")
+            throw new UserAdminOperatorError("This in-memory store has no upstream directory; inject a real store to unlink groups.")
         },
         async setDirectorySyncEnabled() {
-            throw new Error("This in-memory store has no upstream directory; inject a real store to pause synchronization.")
+            throw new UserAdminOperatorError("This in-memory store has no upstream directory; inject a real store to pause synchronization.")
         },
         async requestDirectorySync() {
-            throw new Error("This in-memory store has no upstream directory; inject a real store to request a sync.")
+            throw new UserAdminOperatorError("This in-memory store has no upstream directory; inject a real store to request a sync.")
         },
         async getDirectoryStatus() {
             return { isEnabled: false, provider: "", linkedGroupCount: 0, isStale: false, pausedGroupCount: 0, stalenessThresholdSec: 0, erroredGroupIds: [], pendingRequestCount: 0 }
@@ -200,6 +226,127 @@ export function createInMemoryUserAdminStore(initial?: { users?: AuthUser[]; gro
     }
 }
 
+/**
+ * Decides whether an observation is overdue. 観測が期限超過かどうかを決める処理。
+ *
+ * 上限が正の数でなければ **判定しない** のではなく、既定の上限で判定する。0 や `NaN` で
+ * 「決して古くならない」に倒すと、環境変数の打ち間違いが警告そのものを黙って無効化する。
+ *
+ * @param observedAt When the upstream was observed. 上流を観測した時刻。
+ * @param thresholdSec Deployment's staleness bound in seconds. 配備の陳腐化上限 (秒)。
+ * @returns True when the observation is overdue. 期限超過なら true。
+ */
+function isStaleObservation(observedAt: Date, thresholdSec: number): boolean {
+    const bound = Number.isFinite(thresholdSec) && thresholdSec > 0 ? thresholdSec : DEFAULT_STALENESS_SEC
+    return (Date.now() - observedAt.getTime()) / 1000 > bound
+}
+
+/** 配備が上限を示さなかったときに使う既定 (秒)。判定を無効化するより、既定で判定する。 */
+/**
+ * Largest action body this screen ever needs. この画面の操作が要する本文の上限。
+ *
+ * ⚠️ intent は本文の中にあるため、ガードより先に本文を読む以外の選択肢が無い。この画面が送るのは
+ * 短い文字列だけなので、64 KiB は通常の操作すべてに対して桁で余裕がある。上限そのものより、
+ * **認証を通っていない要求が積み上げられる量を定数で抑える** ことが目的である。
+ */
+const MAX_ACTION_BODY_BYTES = 64 * 1024
+
+const DEFAULT_STALENESS_SEC = 5400
+
+/**
+ * Loads the upstream catalog, turning any failure into a renderable state.
+ * 上流の候補一覧を読み、あらゆる失敗を **描画可能な状態** へ変える処理。
+ *
+ * ⚠️ ここで例外を通すと、上流が落ちているだけでユーザー管理面が丸ごと開かなくなる。候補一覧は
+ * 選択欄を出すための利便であり、グループの閲覧や許可リストの管理はそれと無関係に成立する。
+ * 「判らないなら拒否」を貫くべき認可・サインイン判定とは、意図的に扱いを分けている。
+ *
+ * @param port The injected catalog port, if any. 注入された候補一覧ポート (無い場合あり)。
+ * @param needed False for segments that never show a picker. 選択欄を出さない面では false。
+ * @param request The incoming request, for per-request credentials. リクエスト (資格情報の解決用)。
+ * @param thresholdSec Deployment's staleness bound in seconds. 配備の陳腐化上限 (秒)。
+ * @returns A state the views can render without further checks. ビューがそのまま描ける状態。
+ */
+async function loadCatalog(port: { listGroups: (request: Request) => Promise<UserAdminCatalogSnapshot> } | undefined, needed: boolean, request: Request, thresholdSec: number): Promise<UserAdminCatalog> {
+    if (!port) return { kind: "not-wired" }
+    if (!needed) return { kind: "not-wired" }
+    try {
+        const { groups, observedAt } = await port.listGroups(request)
+        // ⚠️ 一度も観測していない一覧を `ready` で返してはならない。0 件の答えとして描かれ、
+        // 運用者には「上流にグループが無い」と読める — 実際には同期が一度も走っていないだけである
+        if (observedAt === null || !Number.isFinite(observedAt.getTime())) return { kind: "unavailable", reason: "neverObserved" }
+        // ⚠️ 陳腐化の判定は **サーバーで** 行う。ブラウザの時計で判定すると、遅れている端末では
+        // 経過が負になり「古い」という警告が出なくなる — 安全側の警告が、利用者側の入力で
+        // 消える形になる。水和のずれも同時に無くなる
+        return { kind: "ready", groups, observedAt: observedAt.toISOString(), isStale: isStaleObservation(observedAt, thresholdSec) }
+    } catch (error) {
+        // 原文はサーバー側のログにだけ残す。画面へ運ぶのは分類だけである
+        console.error("[@aiquants/auth-react-router] directoryCatalog.listGroups failed; the picker falls back to manual entry:", error)
+        return { kind: "unavailable", reason: classifyCatalogFailure(error) }
+    }
+}
+
+/**
+ * Normalizes an upstream key for comparison. 上流キーを比較用に正規化する処理。
+ *
+ * 前後の空白と大文字小文字を同一視する。**画面と実装で正規化がずれると**、選択欄は「未連携」と
+ * 見なすキーをサーバーが「連携済み」と見なす、といった食い違いが生まれる。1 か所に置く。
+ *
+ * @param key Raw upstream key. 生の上流キー。
+ * @returns The comparable form. 比較可能な形。
+ */
+export function normalizeUpstreamKey(key: string): string {
+    return key.trim().toLowerCase()
+}
+
+/**
+ * An error whose own text is meant for the operator to read.
+ * 文面を **運用者に読ませるつもりで** 投げるエラー。
+ *
+ * ⚠️ ストアの例外文をそのまま画面へ返してはならない。ドライバの例外はスキーマ名・表名・制約名・
+ * 衝突した値・接続先をそのまま含み、それが閲覧権限しか持たない主体の画面に出る。一方で
+ * 「最後の管理者は外せません」のような業務上の拒否理由は、読めなければ操作そのものが行き詰まる。
+ * 両者は文面からは区別できないので、**投げる側が宣言する**。宣言の無い例外は一般的な文言になる。
+ *
+ * ホストのストアは、この class を継承しても `operatorFacing: true` を持たせてもよい
+ * (別パッケージのエラー型を継承できない事情に配慮した二経路である)。
+ */
+export class UserAdminOperatorError extends Error {
+    /** 運用者向けであることの印。継承できない場合はこの属性だけでもよい。 */
+    readonly operatorFacing = true
+    constructor(message: string) {
+        super(message)
+        this.name = "UserAdminOperatorError"
+    }
+}
+
+/**
+ * Decides whether an error's own text may reach the operator. 例外文を運用者へ見せてよいか判定する処理。
+ *
+ * @param error The thrown value. 投げられた値。
+ * @returns True when the store declared it operator-facing. ストアが運用者向けと宣言していれば true。
+ */
+function isOperatorFacing(error: unknown): error is Error {
+    return error instanceof UserAdminOperatorError || (typeof error === "object" && error !== null && (error as { operatorFacing?: unknown }).operatorFacing === true && error instanceof Error)
+}
+
+/**
+ * An input problem the operator can fix, carrying a label key instead of a sentence.
+ * 運用者が直せる入力の問題。文ではなく **ラベルのキー** を運ぶ。
+ *
+ * ⚠️ メッセージを実装側で組むと、既定 (英語) の配備に日本語が出る。文言はラベルに集約し、
+ * ここでは「どの文言か」と差し替え値だけを運ぶ。
+ */
+export class UserAdminInputError extends Error {
+    constructor(
+        readonly labelKey: keyof UserAdminLabels["errors"],
+        readonly values: Record<string, string | number> = {},
+    ) {
+        super(labelKey)
+        this.name = "UserAdminInputError"
+    }
+}
+
 /**
  * Tells a per-operation authorization denial apart from any other failure, without importing an authz library.
  * 認可ライブラリを import せずに、操作単位の認可拒否を他の失敗と見分ける判定。
@@ -230,7 +377,8 @@ function isForbidden(error: unknown): boolean {
 function requireAllowlistType(formData: FormData): "email" | "domain" {
     const raw = String(formData.get("type") ?? "")
     if (raw === "email" || raw === "domain") return raw
-    throw new Error(`type は "email" または "domain" のいずれかで指定してください (受け取った値: ${JSON.stringify(raw)})`)
+    // 受け取った値は反射しない。運用者が直せるのは「どの欄が不正か」までである
+    throw new UserAdminInputError("invalidAllowlistType")
 }
 
 /** 表示するタブ。未知の値は先頭のタブへ寄せる。 */
@@ -257,11 +405,6 @@ function segmentFromPathname(pathname: string): (typeof SEGMENTS)[number] {
     return (SEGMENTS as readonly string[]).includes(last) ? (last as (typeof SEGMENTS)[number]) : "users"
 }
 
-/**
- * The CRUD verb an operation performs. Deliberately a plain string union so this package stays
- * independent of any particular authorization library.
- * 操作が行う CRUD 種別。特定の認可ライブラリに依存しないよう素の文字列 union で表現する。
- */
 /**
  * The only route-args field this module reads. React Router's full `LoaderFunctionArgs` satisfies it, so
  * route wiring is unchanged — but declaring the minimum keeps callers (and tests) from fabricating fields
@@ -270,6 +413,11 @@ function segmentFromPathname(pathname: string): (typeof SEGMENTS)[number] {
  */
 type RouteArgs = { request: Request }
 
+/**
+ * The CRUD verb an operation performs. Deliberately a plain string union so this package stays
+ * independent of any particular authorization library.
+ * 操作が行う CRUD 種別。特定の認可ライブラリに依存しないよう素の文字列 union で表現する。
+ */
 export type UserAdminAccess = "read" | "create" | "update" | "delete"
 
 /**
@@ -320,6 +468,8 @@ const INTENT_ACCESS = new Map<string, readonly UserAdminAccess[]>([
     // 連携の開始は、以後の所属の **追加と削除の両方** を上流へ委ねる行為である。所属を足せる
     // だけの主体が「足すことも消すこともできる仕掛け」を据えられてはならない。属性変更でもある
     // ため update も要る
+    // 作成と連携を 1 手で行う。要求する権限は両者の合併である (どちらか一方で通してはならない)
+    ["createLinkedGroup", ["create", "update", "delete"]],
     ["linkDirectoryGroup", ["update", "create", "delete"]],
     // 解除は台帳とグループ単位のサインイン許可を **消す**。属性を戻すだけではないので、
     // 削除権限を持たない主体には許さない
@@ -328,7 +478,107 @@ const INTENT_ACCESS = new Map<string, readonly UserAdminAccess[]>([
     // 書き込みを伴わないが update を要求する。読取権限だけの主体が上流問い合わせを誘発できると、
     // レート制限を外部から枯渇させられる
     ["requestDirectorySync", ["update"]],
+    // 上流の候補一覧は書込みではないが、**外部組織の部門構成と規模** を列挙する。読取権限だけの
+    // 主体に見せる理由は無く、連携を作れない主体には選択欄そのものが無意味である。要求する権限は
+    // 連携を作る intent と同じにする (どれか 1 つで通せば、その 1 つで一覧が読める)
+    ["catalog", ["update", "create", "delete"]],
 ])
+
+/**
+ * Every intent the permission table knows. 権限表が知っている intent すべて。
+ *
+ * ⚠️ 消費側の網羅性検査のために公開する。検査側が intent を手書きで並べる形しか無いと、
+ * 実装に intent が増えても表は勝手には伸びず、**最も権限の重い新しい intent** だけが
+ * 無検査で通る状態が静かに生まれる。突き合わせる相手を実装側から提供する。
+ *
+ * @returns Intent names, in declaration order. 宣言順の intent 名。
+ */
+export function userAdminIntents(): string[] {
+    return [...INTENT_ACCESS.keys()]
+}
+
+/**
+ * The CRUD verbs one intent requires. 1 つの intent が要求する CRUD 種別。
+ *
+ * ⚠️ 消費側が権限表を検査できるようにするために公開する。表そのものは公開しない — 書き換え
+ * 可能な参照を渡すと、検査の対象が実行時に差し替えられる形になる。
+ *
+ * @param intent - Intent name. intent 名。
+ * @returns The required verbs, or an empty list for an unknown intent. 要求する種別 (未知なら空)。
+ */
+export function userAdminAccessFor(intent: string): readonly UserAdminAccess[] {
+    return INTENT_ACCESS.get(intent) ?? []
+}
+/**
+ * One upstream group as the picker shows it. 選択欄に出す上流グループ 1 件。
+ *
+ * ⚠️ **別名ではなく `@aiquants/auth-core` の型そのものである。** この形は上流アダプタ・永続化層・
+ * 管理 UI の 3 層を通る。層ごとに「同じ意味の別の型」を宣言すると、構造的部分型のせいでどの境界も
+ * 通ってしまい、上流へ足した欄が途中で黙って捨てられる (実測: 別々に宣言していた間は、必須欄を
+ * 足しても読み手側の境界で `tsc --strict` が 0 を返した)。欄の集合は `auth-core` の型テストが固定
+ * しているので、足すときは 3 層すべての受け渡しを見直すことになる。
+ *
+ * 特定のディレクトリ実装 (Google 等) の型は依然として import しない — `auth-core` は上流に依存
+ * しない語彙のパッケージであり、`AuthDirectoryStatus` などを既にここから受け取っている。
+ */
+export type UserAdminCatalogGroup = AuthDirectoryCatalogGroup
+
+/**
+ * The upstream catalog as the loader hands it to the views. loader がビューへ渡す上流の候補一覧。
+ *
+ * ⚠️ **これは利便性のための読み取りである。** 上流へ届かなくても画面は開かなければならない
+ * (グループ一覧や許可リストの閲覧は、選択欄の可否とは無関係である)。したがって失敗は
+ * `reason` として **描画可能な状態** に変換し、例外にしない。認可やサインイン判定のように
+ * 「判らないなら拒否」であるべき経路とは、意図的に扱いを変えている。
+ */
+export type UserAdminCatalog = { kind: "ready"; groups: UserAdminCatalogGroup[]; observedAt: string; isStale: boolean } | { kind: "unavailable"; reason: UserAdminCatalogFailure } | { kind: "not-wired" }
+
+/**
+ * What the catalog port answers: the groups, and when the upstream was actually observed.
+ * 候補一覧ポートの答え。グループと、上流を実際に観測した時刻。
+ *
+ * ⚠️ `observedAt` は省略できない。この一覧は上流を直に叩いた結果とは限らず、資格情報を持つ別の
+ * プロセスが書いた写しであることが多い。時刻を伴わない一覧は「上流の現在」と区別できず、運用者は
+ * 既に消えたグループを選ぶ。`null` は **一度も観測していない** ことを意味する (空の答えではない)。
+ */
+export type UserAdminCatalogSnapshot = AuthDirectoryCatalogSnapshot
+
+/**
+ * What a "sync now" request did. 「今すぐ同期」の要求が行ったこと。
+ *
+ * `already-pending` は失敗ではない — 同じ範囲の要求が既に待っている。ただし **成功でもない**:
+ * 何も積まれていないので、待っている行が誰にも拾われなければ何も起きない。
+ */
+export type UserAdminSyncRequestOutcome = "queued" | "already-pending"
+
+/**
+ * Why the upstream catalog could not be listed, classified for display.
+ * 上流の候補一覧を引けなかった理由を、表示のために分類したもの。
+ *
+ * ⚠️ **上流の例外文をそのまま画面へ出してはならない。** サービスアカウントのアドレス、借用先、
+ * 内部 URL、資格情報の断片が混じり得る。管理面を開けるだけの主体に、それらを読ませる理由は無い。
+ * 原文は `console.error` へ出し、画面にはこの分類に対応する自前の文言を出す。
+ */
+export type UserAdminCatalogFailure = "denied" | "rateLimited" | "upstreamError" | "neverObserved" | "unknown"
+
+/**
+ * Classifies a catalog failure without quoting the upstream. 上流を引用せずに失敗を分類する処理。
+ *
+ * 上流アダプタの型に依存しないよう、`status` という数値プロパティの有無だけで判定する。
+ * 判別できないものは `unknown` へ倒す (推測した分類を出すより、判らないと言う方が正しい)。
+ *
+ * @param error The thrown value. 投げられた値。
+ * @returns The display classification. 表示用の分類。
+ */
+function classifyCatalogFailure(error: unknown): UserAdminCatalogFailure {
+    const status = typeof error === "object" && error !== null && "status" in error ? (error as { status: unknown }).status : undefined
+    if (typeof status !== "number") return "unknown"
+    if (status === 401 || status === 403) return "denied"
+    if (status === 429) return "rateLimited"
+    if (status >= 500) return "upstreamError"
+    return "unknown"
+}
+
 /**
  * Neutral per-resource permission summary the admin shell renders in its header badge.
  * 管理シェルのヘッダーバッジが描画する、リソース単位の中立な権限サマリ。
@@ -352,6 +602,26 @@ export type UserAdminAppConfig = {
      * 必須。省略を許すとユーザー名簿と全更新操作が無防備に露出するため、型で強制する。
      */
     guards: UserAdminGuards
+    /**
+     * Names who is acting, for audit columns. 監査列に残す「誰が」を解決する処理。
+     *
+     * ⚠️ 省略すると、要求を積んだ主体が記録されない。同期要求の表は「誰がいつ何を要求し、結果が
+     * どうだったか」を残すために在り、その `requested_by` が定数だと、乱発を疑ったときに誰の
+     * ものか判らない — 乱発こそがこの intent に `update` を要求した理由である。
+     */
+    resolveActor?: (request: Request) => Promise<string> | string
+    /**
+     * Lists the upstream groups the operator may link to. 連携先の候補を列挙するポート。
+     *
+     * 任意である。注入しない配備では選択欄を出さず、上流キーの手入力に留まる — 上流へ問い合わせる
+     * 資格情報を web 側へ置かない構成を選べるようにするためである (同期ジョブだけが鍵を持つ形)。
+     *
+     * ⚠️ **失敗しても画面を落としてはならない。** 例外は loader が捕まえて
+     * `{ kind: "unavailable" }` へ写す。ここが落ちると、グループ一覧すら開けなくなる。
+     */
+    directoryCatalog?: {
+        listGroups: (request: Request) => Promise<UserAdminCatalogSnapshot>
+    }
     /**
      * Per-request self-permission lookup for the header annotation. Resolving to a map of
      * {@link UserAdminPermission} shows the badge; rejecting shows an explicit "unknown" badge — never a
@@ -381,7 +651,7 @@ function requireId(formData: FormData, field: string): number {
     const n = Number(raw)
     // NaN / 小数 / 0 以下は不正な ID として弾く (Number(null) === 0 の取り違えも防ぐ)
     if (raw === null || String(raw).trim() === "" || !Number.isInteger(n) || n <= 0) {
-        throw new Error(`Invalid or missing "${field}"`)
+        throw new UserAdminInputError("invalidField", { field })
     }
     return n
 }
@@ -394,7 +664,7 @@ function requireId(formData: FormData, field: string): number {
  */
 function requireText(formData: FormData, field: string): string {
     const value = String(formData.get(field) ?? "").trim()
-    if (value === "") throw new Error(`Invalid or missing "${field}"`)
+    if (value === "") throw new UserAdminInputError("invalidField", { field })
     return value
 }
 
@@ -407,7 +677,7 @@ function requireText(formData: FormData, field: string): string {
  */
 function requireBoolean(formData: FormData, field: string): boolean {
     const raw = String(formData.get(field) ?? "")
-    if (raw !== "true" && raw !== "false") throw new Error(`Invalid or missing "${field}"`)
+    if (raw !== "true" && raw !== "false") throw new UserAdminInputError("invalidField", { field })
     return raw === "true"
 }
 
@@ -421,7 +691,7 @@ function requireBoolean(formData: FormData, field: string): boolean {
  */
 function requireMembershipMode(formData: FormData): AuthDirectoryMembershipMode {
     const raw = String(formData.get("membershipMode") ?? "")
-    if (raw !== "direct" && raw !== "transitive") throw new Error('Invalid or missing "membershipMode"')
+    if (raw !== "direct" && raw !== "transitive") throw new UserAdminInputError("invalidField", { field: "membershipMode" })
     return raw
 }
 
@@ -440,11 +710,63 @@ function optionalText(formData: FormData, field: string): string | undefined {
 export function createUserAdminApp(config: UserAdminAppConfig) {
     const labels = resolveUserAdminLabels(config.labels)
 
+    /**
+     * Names who is acting. 「誰が」を解決する処理。
+     *
+     * 解決できない配備では固定値を残す (記録そのものを落とすより、判らないと記録する方がよい)。
+     *
+     * @param request The incoming request. 受け取ったリクエスト。
+     * @returns The actor label. 監査に残す主体。
+     */
+    async function actorOf(request: Request): Promise<string> {
+        if (!config.resolveActor) return "user-admin"
+        try {
+            return (await config.resolveActor(request)) || "user-admin"
+        } catch (error) {
+            console.error("[@aiquants/auth-react-router] resolveActor failed; recording the request as an unnamed actor:", error)
+            return "user-admin"
+        }
+    }
+
+    /**
+     * Decides whether this request may list the upstream catalog. 候補一覧を引いてよいかを決める処理。
+     *
+     * ⚠️ 候補一覧は外部組織の部門構成を列挙する。`read` で通すと、閲覧権限だけの主体がそれを
+     * 読めてしまう。ここでは **連携を作る intent と同じ権限** を要求し、拒否は「見せない」へ写す。
+     * 認可以外の理由 (ガードの内部エラー) でも見せない側へ倒す — 利便のための読み取りであり、
+     * 判らないときに見せる理由が無い。
+     *
+     * @param request - The incoming request. 受け取ったリクエスト。
+     * @returns True when the catalog may be fetched. 候補一覧を引いてよいなら true。
+     */
+    async function mayReadCatalog(request: Request): Promise<boolean> {
+        if (!config.directoryCatalog) return false
+        const actions = INTENT_ACCESS.get("catalog")
+        // ⚠️ 要求すべき権限が引けなければ **見せない**。空配列で回すと 0 回の検査で `true` を
+        // 返すことになり、認可の補助が fail-open な方向へ倒れる
+        if (actions === undefined || actions.length === 0) return false
+        try {
+            for (const action of actions) await config.guards.requireAccess(request, { action, intent: "catalog" })
+            return true
+        } catch (error) {
+            // 拒否は握り潰さず監査へ流す。ここだけ記録が抜けると、「誰が何を見られなかったか」
+            // という問いに答えられない範囲が生まれる
+            try {
+                config.guards.onDenied?.({ intent: "catalog", actions, error })
+            } catch (hookError) {
+                console.error("[@aiquants/auth-react-router] onDenied threw; the denial itself still stands:", hookError)
+            }
+            return false
+        }
+    }
+
     async function loader({ request }: RouteArgs) {
         // 読取ガード: 拒否は throw されるためここで処理が打ち切られる
         await config.guards.requireAccess(request, { action: "read", intent: "loader" })
         const segment = segmentFromPathname(new URL(request.url).pathname)
 
+        // 候補一覧は **必要な面だけ** で引く。全画面で引くと、上流への往復が毎回の描画に乗る
+        const needsCatalog = (segment === "groups" || segment === "directory") && (await mayReadCatalog(request))
         const [users, groups, groupMembers, allowlist, directoryStatus, myPermissions] = await Promise.all([
             config.store.listUsers(),
             config.store.listGroups(),
@@ -459,6 +781,8 @@ export function createUserAdminApp(config: UserAdminAppConfig) {
                   })
                 : Promise.resolve(null),
         ])
+        // 陳腐化の上限は配備の状態から取る。候補一覧の取得はこの後 (上限を知ってから) 行う
+        const catalog = await loadCatalog(config.directoryCatalog, needsCatalog, request, directoryStatus.stalenessThresholdSec)
 
         return {
             resourceLabels: config.resourceLabels,
@@ -469,11 +793,21 @@ export function createUserAdminApp(config: UserAdminAppConfig) {
             allowlist,
             directoryStatus,
             myPermissions,
+            catalog,
             labels,
         }
     }
 
     async function action({ request }: RouteArgs) {
+        // ⚠️ 本文を読む前に大きさで断る。intent は本文の中にあるので、ガードより先に読む以外の
+        // 選択肢が無い — つまり **認証を通っていない要求でも本文が積まれる**。この画面が送るのは
+        // 短い文字列だけなので、上限を先に見るだけで、その積み上がりを定数で抑えられる。
+        // 送出側が長さを申告しない場合 (chunked) はここでは分からない。前段のリバースプロキシの
+        // 本文上限が最終的な砦であり、この検査はその代わりではなく **手前の安い一段** である
+        const declaredLength = Number(request.headers.get("content-length") ?? Number.NaN)
+        if (Number.isFinite(declaredLength) && declaredLength > MAX_ACTION_BODY_BYTES) {
+            return data({ ok: false, error: labels.errors.requestTooLarge }, { status: 413 })
+        }
         // intent の判定に FormData が要るため、ここでだけ本文を先に読む。
         // 未知 intent は「何も実行しない」ため、ガード前に読んでも権限判断には影響しない。
         const formData = await request.formData()
@@ -482,7 +816,10 @@ export function createUserAdminApp(config: UserAdminAppConfig) {
         // 未知 intent はストアへ到達しない (ガードも走らせず 400 相当を返す)。
         // Map 参照のためプロトタイプ継承キー ("constructor" 等) を拾わない。
         const access = INTENT_ACCESS.get(intent)
-        if (!access) return { ok: false, error: `Unknown intent: ${intent}` }
+        // ⚠️ 受け取った値を応答へ echo しない。ここは認可より **手前** なので、認証を通っていない
+        // POST でも到達する — echo すると、攻撃者が選んだ文字列を 200 で返す原始的な道具になり、
+        // 管理面への探りが 2xx の列に紛れる。状態も 400 にして、成功の集計から外す
+        if (!access) return data({ ok: false, error: labels.errors.unknownIntent }, { status: 400 })
 
         /** 403 かどうか。Response でも素の例外でも `status` は共通語彙である。 */
         const isDenied = (error: unknown) => isForbidden(error)
@@ -512,7 +849,7 @@ export function createUserAdminApp(config: UserAdminAppConfig) {
         }
 
         try {
-            return await dispatch(intent, formData)
+            return await dispatch(intent, formData, request)
         } catch (error) {
             // ガードの後 (ストアの中) で投げられた拒否も同じ扱いにする。ここを素通りさせると、
             // 拒否理由がそのまま利用者へ渡り、しかも HTTP は 200 になって監視から消える
@@ -520,12 +857,131 @@ export function createUserAdminApp(config: UserAdminAppConfig) {
             // ガード拒否 (Response/redirect) はそのまま伝播させる。ストア由来の業務エラーだけ
             // {ok:false,error} に写して UI へ届ける (ロックアウト理由・重複パターン等)
             if (error instanceof Response) throw error
-            return { ok: false, error: error instanceof Error ? error.message : String(error) }
+            // 実装側で文を組まず、ラベルから引く (既定は英語の配備に日本語が出るのを避ける)
+            if (error instanceof UserAdminInputError) {
+                // ⚠️ `{field}` には **操作者が画面で見ている名前** を差し込む。通信上のキーを
+                // そのまま出すと、日本語の文の中に `membershipMode` のような識別子が現れ、
+                // どの欄のことなのか読み手には判らない。表に無い欄はキーのまま出す
+                const raw = error.values.field
+                const values = typeof raw === "string" ? { ...error.values, field: labels.errors.fieldNames[raw] ?? raw } : error.values
+                const template = labels.errors[error.labelKey]
+                return { ok: false, error: fillLabel(typeof template === "string" ? template : String(error.labelKey), values) }
+            }
+            // ⚠️ 例外文をそのまま返してよいのは、ストアが **運用者向けと宣言した** ものだけである。
+            // ドライバの例外は一意制約名・表名・衝突した値・接続先をそのまま含み、それが閲覧権限
+            // しか持たない主体の画面へ出る。原文は必ずサーバーのログへ残す
+            console.error(`[@aiquants/auth-react-router] intent "${intent}" failed:`, error)
+            return { ok: false, error: isOperatorFacing(error) ? error.message : labels.errors.unexpected }
+        }
+    }
+
+    /**
+     * Resolves the stable upstream id for a chosen key. 選ばれたキーに対応する安定 ID を決める処理。
+     *
+     * ⚠️ 正準キーは安定 ID である。アドレスは上流で改名され得るため、それだけを保存すると、改名
+     * された瞬間にリンクが上流を見失う。一覧が引けているならそこから引く (画面の送信値を信用
+     * しない)。引けていない配備 (手入力しか手段が無い) では送信値を使い、無ければアドレスを
+     * そのまま置く — 同期が最初に成功した時点で、上流の本当の ID へ自動的に書き戻される。
+     *
+     * @param formData The submitted form. 送信されたフォーム。
+     * @param externalKey The chosen upstream key. 選ばれた上流キー。
+     * @param catalog The catalog resolved for this request. この要求で解決済みの候補一覧。
+     * @returns The upstream id to persist. 保存する上流 ID。
+     */
+    function resolveExternalId(formData: FormData, externalKey: string, catalog: UserAdminCatalog): string {
+        const submitted = String(formData.get("externalId") ?? "").trim()
+        if (catalog.kind === "ready") {
+            // ⚠️ 送られてきた安定 ID が候補一覧に在るなら、それを優先する。アドレスは一意とは
+            // 限らない (別名行、改名の途中、別ドメインの同名) ため、アドレスで引き当てると
+            // 選択欄で 2 件目を選んだ利用者に 1 件目を結び付けることになる。取り消せない委譲を
+            // 取り違えたまま確定させないため、識別子が在るときは識別子で決める
+            if (submitted !== "" && catalog.groups.some((g) => g.externalId === submitted)) return submitted
+            const wanted = normalizeUpstreamKey(externalKey)
+            const match = catalog.groups.find((g) => normalizeUpstreamKey(g.externalKey) === wanted)
+            if (match) return match.externalId
+        }
+        return submitted === "" ? externalKey : submitted
+    }
+
+    /**
+     * Refuses the link intents when this deployment has no directory. ディレクトリ未設定の配備で連携を拒否する処理。
+     *
+     * ⚠️ 画面は連携の欄そのものを出さないが、それは **UI だけの約束** である。組み立てた POST は
+     * 通ってしまい、`provider` が空、あるいは配備と食い違う行が残る。そういう行は同期側が
+     * 「別プロバイダ」として恒久的に無視するため、**連携済みに見えて永久に同期されない** グループが
+     * できる。加えて供給元は送られてきた値ではなく配備の状態から取る — 唯一の源はここである。
+     *
+     * @returns The deployment's provider key. この配備の供給元キー。
+     * @throws {UserAdminInputError} When the directory is not configured. ディレクトリ未設定の場合。
+     */
+    function requireDirectoryEnabled(status: AuthDirectoryStatus): string {
+        const provider = status.provider.trim()
+        // ⚠️ 前後の空白を落として返す。落とさずに保存すると、同期側の `!==` 比較が恒久的に
+        // 「別プロバイダ」と判定し、連携済みに見えて永久に同期されないグループができる
+        if (!status.isEnabled || provider === "") throw new UserAdminInputError("directoryDisabled")
+        return provider
+    }
+
+    /**
+     * Refuses an upstream group that is already linked to another local group.
+     * 既に別のローカルグループへ連携している上流グループを拒否する処理。
+     *
+     * 画面は連携済みの選択肢を選べなくしているが、それは **UI だけの約束** である。二重に連携すると
+     * 同じ上流の所属が 2 つのグループへ投影され、メンバーが二重に数えられ、両方のロールが配られる。
+     *
+     * @param externalKey The upstream key about to be linked. 連携しようとしている上流キー。
+     * @throws {UserAdminInputError} When it is already linked. 既に連携している場合。
+     */
+    async function assertNotAlreadyLinked(externalId: string, externalKey: string): Promise<void> {
+        // ⚠️ 突合の第一キーは **安定 ID** である。アドレスで比べると、上流でグループが改名された
+        // 直後 (旧アドレスは別名として残る) に、まだ再同期していないリンクとは一致せず、同じ上流
+        // グループが 2 つのローカルグループへ投影される。DB の一意制約は ID 側に張ってあるため、
+        // アドレスだけで検査すると制約も後ろ盾にならない
+        const wantedId = normalizeUpstreamKey(externalId)
+        const wantedKey = normalizeUpstreamKey(externalKey)
+        const groups = await config.store.listGroups()
+        const clash = groups.find((g) => g.externalLink !== undefined && (normalizeUpstreamKey(g.externalLink.externalId) === wantedId || normalizeUpstreamKey(g.externalLink.externalKey) === wantedKey))
+        if (clash) throw new UserAdminInputError("alreadyLinked", { key: externalKey, group: clash.name })
+    }
+
+    /**
+     * Refuses an upstream key the catalog does not list. 候補一覧に無い上流キーを拒否する処理。
+     *
+     * 候補一覧を注入していない配備では検査できない。**検査できないことを黙って通す** のは
+     * 望ましくないが、ここで拒否すると手入力しか手段が無い配備で連携が一切作れなくなる。
+     * 「一覧が在るなら一覧に従う」という条件付きの検査であることを、意図として明示しておく。
+     *
+     * @param externalKey The key the operator chose or typed. 選択または入力された上流キー。
+     * @param catalog The catalog already resolved for this request. この要求で解決済みの候補一覧。
+     * @throws {UserAdminInputError} When a catalog exists and does not list the key. 一覧が在り、そこに無い場合。
+     */
+    function assertKnownUpstream(externalId: string, externalKey: string, catalog: UserAdminCatalog): void {
+        // 一覧が引けていないときは検査しない。**ここで拒否すると、上流が落ちている間は連携が
+        // 一切作れなくなる** — しかも画面は「アドレスを手入力してください」と案内している。
+        // 検査は綴り違いを早く知らせるためのものであり、可用性を落としてよい理由にはならない
+        if (catalog.kind !== "ready") return
+        const wantedId = normalizeUpstreamKey(externalId)
+        const wantedKey = normalizeUpstreamKey(externalKey)
+        // ⚠️ 2 欄が **同じ 1 件を指していること** まで確かめる。片方だけ照合すると、一覧に在る
+        // アドレスと、別のグループの安定 ID を組み合わせた送信が通ってしまう
+        if (!catalog.groups.some((g) => normalizeUpstreamKey(g.externalId) === wantedId && normalizeUpstreamKey(g.externalKey) === wantedKey)) {
+            throw new UserAdminInputError("unknownUpstream", { key: externalKey })
         }
     }
 
     /** intent ごとの実処理。認可・入力検証を通過した後にのみ呼ばれる。 */
-    async function dispatch(intent: string, formData: FormData) {
+    async function dispatch(intent: string, formData: FormData, request: Request) {
+        // 候補一覧は **必要な intent に入ってから** 読む。先に読むと、上流と無関係な操作
+        // (利用者の作成、許可リストの編集) にまで上流への往復が乗る
+        // 配備の状態はこの送信で 1 度だけ読む。`requireDirectoryEnabled` が読んだものを使い回す —
+        // 読み直すと 1 回の連携作成で 4 往復になり、しかも `provider` と鮮度上限が別の瞬間の
+        // スナップショットから来ることになる
+        let cachedStatus: AuthDirectoryStatus | null = null
+        const status = async () => {
+            cachedStatus ??= await config.store.getDirectoryStatus()
+            return cachedStatus
+        }
+        const catalog = async () => loadCatalog(config.directoryCatalog, true, request, (await status()).stalenessThresholdSec)
         if (intent === "createUser") {
             await config.store.createUser({ displayName: requireText(formData, "displayName"), email: requireText(formData, "email") })
             return { ok: true }
@@ -539,7 +995,7 @@ export function createUserAdminApp(config: UserAdminAppConfig) {
         if (intent === "toggleUserActive") {
             // 破壊側 (無効化) を既定にしない。明示的な "true"/"false" 以外は不正入力として弾く。
             const rawActive = String(formData.get("isActive") ?? "")
-            if (rawActive !== "true" && rawActive !== "false") throw new Error('Invalid or missing "isActive"')
+            if (rawActive !== "true" && rawActive !== "false") throw new UserAdminInputError("invalidField", { field: "isActive" })
             await config.store.toggleUserActive(requireId(formData, "userId"), rawActive === "true")
             return { ok: true }
         }
@@ -583,10 +1039,39 @@ export function createUserAdminApp(config: UserAdminAppConfig) {
             await config.store.removeAllowlistGroup(requireId(formData, "entryId"))
             return { ok: true }
         }
+        if (intent === "createLinkedGroup") {
+            const externalKey = requireText(formData, "externalKey")
+            const provider = requireDirectoryEnabled(await status())
+            // 一覧はこの送信で 1 度だけ読む。安定 ID の解決と存在検査で 2 度読むと、その分だけ
+            // 上流への往復が増える
+            const resolved = await catalog()
+            const externalId = resolveExternalId(formData, externalKey, resolved)
+            await assertNotAlreadyLinked(externalId, externalKey)
+            // 候補一覧が在るなら、選択肢に無いキーは受け付けない。手入力の綴り違いは「10 分後に
+            // 赤いバナー」ではなく、その場で分かるべきである
+            assertKnownUpstream(externalId, externalKey, resolved)
+            await config.store.createLinkedGroup({
+                groupKey: requireText(formData, "groupKey"),
+                name: requireText(formData, "name"),
+                description: optionalText(formData, "description"),
+                provider,
+                externalId,
+                externalKey,
+                membershipMode: requireMembershipMode(formData),
+            })
+            return { ok: true }
+        }
         if (intent === "linkDirectoryGroup") {
+            const externalKey = requireText(formData, "externalKey")
+            const provider = requireDirectoryEnabled(await status())
+            const resolved = await catalog()
+            const externalId = resolveExternalId(formData, externalKey, resolved)
+            await assertNotAlreadyLinked(externalId, externalKey)
+            assertKnownUpstream(externalId, externalKey, resolved)
             await config.store.linkDirectoryGroup(requireId(formData, "groupId"), {
-                provider: requireText(formData, "provider"),
-                externalKey: requireText(formData, "externalKey"),
+                provider,
+                externalId,
+                externalKey,
                 membershipMode: requireMembershipMode(formData),
             })
             return { ok: true }
@@ -601,8 +1086,10 @@ export function createUserAdminApp(config: UserAdminAppConfig) {
         }
         if (intent === "requestDirectorySync") {
             const raw = String(formData.get("groupId") ?? "").trim()
-            await config.store.requestDirectorySync(raw === "" ? null : requireId(formData, "groupId"))
-            return { ok: true }
+            const outcome = await config.store.requestDirectorySync(raw === "" ? null : requireId(formData, "groupId"), await actorOf(request))
+            // ⚠️ 何が起きたかを画面へ返す。`{ ok: true }` だけを返すと、積まれなかったことが
+            // 成功と見分けられず、押しても反応しない画面になる
+            return { ok: true, syncRequest: outcome }
         }
         if (intent === "removeAllowlistEntry") {
             await config.store.removeAllowlistEntry(requireId(formData, "entryId"))
@@ -610,7 +1097,10 @@ export function createUserAdminApp(config: UserAdminAppConfig) {
         }
 
         // INTENT_ACCESS を通過した intent は上のいずれかで処理済み (到達しない安全網)
-        return { ok: false, error: `Unknown intent: ${intent}` }
+        // 権限表を通ったのに分岐が無い intent は、表と実装の食い違いである (`catalog` のような
+        // 読み取り専用キーが POST で来た場合を含む)。利用者へ値は返さず、ログにだけ残す
+        console.error(`[@aiquants/auth-react-router] intent "${intent}" is in the permission table but has no handler`)
+        return data({ ok: false, error: labels.errors.unknownIntent }, { status: 400 })
     }
 
     return { loader, action }