@aiquants/auth-react-router 0.13.1 → 0.14.1

package/README.md

@@ -90,6 +90,62 @@ export default () => <AuthUserAdminAppView />
 - Store errors (e.g. "cannot remove the last administrator") are returned as `{ ok: false, error }` and rendered by the views; guard rejections propagate untouched.
 - Labels default to **English** (`defaultUserAdminLabels`); inject `jaUserAdminLabels` or a partial override via `resolveUserAdminLabels`.
 
+### Upstream group catalog (optional port)
+
+The groups and directory tabs let the operator **pick** an upstream group instead of spelling its address. Wire the optional
+`directoryCatalog` port to enable it; omit it and both surfaces fall back to typing the address by hand.
+
+```ts
+createUserAdminApp({
+    store: myUserAdminStore,
+    guards: { ... },
+    // `observedAt` is required. It is `null` only when the upstream has NEVER been observed —
+    // which is not the same as "observed, and the answer was empty".
+    directoryCatalog: {
+        listGroups: async (request) => {
+            const { groups, observedAt } = await myCatalogReader.read(request)
+            return { groups, observedAt }
+        },
+    },
+})
+```
+
+The list is usually a **copy** written by a separate process that holds the upstream credential, not a live read.
+That is why the port must report when the upstream was observed: a list with no timestamp reads as "the directory right
+now", and the operator picks a group that no longer exists. `observedAt: null` is rendered as `unavailable /
+neverObserved` rather than as an empty list, so a deployment whose synchronization has never run is never mistaken for a
+domain with no groups.
+
+- **The catalog is a convenience read, never a gate.** A failure is reported to the view as
+  `{ kind: "unavailable", reason }` — the tab still opens, and manual entry stays available. It is fetched only for the two
+  segments that render a picker, and only for the intents that create a link.
+- **`reason` is a classification, not the upstream's text** (`denied` / `rateLimited` / `upstreamError` /
+  `neverObserved` / `unknown`; the first three are derived from a numeric `status` when the thrown value carries one,
+  `neverObserved` from a `null` observation time). The original error goes to `console.error` only: an upstream message
+  can carry the service-account address, the impersonated subject, internal URLs, or a credential fragment, and holding
+  read access to this page is not a reason to be shown any of them.
+- **The same rule governs store errors.** An exception's own text reaches the operator only when the store declares it
+  operator-facing — by throwing `UserAdminOperatorError`, or by setting `operatorFacing: true` on the error (for hosts
+  that cannot extend this package's class). Everything else is reported as a generic sentence and logged: a driver
+  exception carries the schema, table, constraint and the offending values.
+- **The provider is taken from `getDirectoryStatus()`, never from the form**, and the link intents are refused outright
+  when the directory is not enabled. The absence of a control in the UI is not a constraint.
+- **`observedAt` and `isStale` are decided on the server.** Judging staleness in the browser lets a client whose clock
+  runs behind suppress the warning, and desynchronizes server and client rendering.
+- **A host that overrides `labels` wholesale must supply `groupsView.catalogFailures`** (five keys) alongside the rest;
+  `resolveUserAdminLabels` fills anything omitted from a partial override.
+- **Listing the catalog requires the same verbs as creating a link** (`update` + `create` + `delete`), not `read`. It
+  enumerates another organization's department structure and headcounts; a principal who cannot link has no use for it.
+  A denial is turned into "no picker", never into a failed page.
+- **The action re-checks what the picker offered.** A key the catalog does not list is refused server-side (case and
+  surrounding whitespace are treated as equal), because the picker's `disabled` rows are a UI promise, not a constraint.
+  When no catalog is wired — or the upstream is unreachable — the check is skipped rather than turned into a refusal:
+  refusing there would make linking impossible in exactly the deployments that must type the address by hand.
+- **An upstream group already linked to another local group is refused**, so its membership cannot be projected onto two
+  groups (double-counted members, both sets of roles granted).
+- `createLinkedGroup` creates the group and links it in **one** intent, and therefore requires the union of the verbs both
+  halves need (`create` + `update` + `delete`). Splitting it in two would leave a state where only one half succeeded.
+
 Styling: this package has **no hand-written component CSS** (the `GoogleForm` classes are plain Tailwind utilities), so it ships **no components-only artifact** — only a standalone build. Two consumption modes, never mixed:
 
 - **Tailwind v4 host** — add `@source "../node_modules/@aiquants/auth-react-router/src/**/*.{ts,tsx}";` (monorepo: `../../../../packages/auth-react-router/src/**/*.{ts,tsx}`) so the `GoogleForm` classes are generated in the host's own canonical build; `src` ships in the published package.
@@ -101,6 +157,23 @@ Styling: this package has **no hand-written component CSS** (the `GoogleForm` cl
 
 Never mix the two: importing the standalone utility CSS next to a host Tailwind build duplicates same-named utilities, and base/variant cascade winners flip versus the single-build canonical order.
 
+The admin surface renders `@aiquants/select-box`, whose own stylesheet is **not** part of either artifact above. Import it in
+the host, or the group picker's dropdown renders unstyled:
+
+```css
+@import "@aiquants/select-box/styles/select-box.css";
+```
+
+Its transitive peers (`@aiquants/fuzzy-search`, `@aiquants/virtualscroll`) are declared here as well, so a host that
+installs this package is told what the picker needs rather than discovering it as a runtime resolution failure.
+
+All three are **required** peers, not optional. `src/admin/views.tsx` imports `@aiquants/select-box` at the top level and
+`./admin` re-exports it, so the specifier survives into `dist/admin.mjs`: a host without it does not get a degraded
+picker, it gets `ERR_MODULE_NOT_FOUND` for the whole admin surface — including the groups and allowlist tabs, which have
+nothing to do with the picker. Marking them optional would suppress the install warning that is the only thing standing
+between a consumer and that failure. Note also that `@aiquants/select-box` pins React 19, which is stricter than this
+package's own `react: ">=18"`; a host that mounts `/admin` must satisfy the stricter one.
+
 ## Behavior Contract
 
 - **Session cookie byte compatibility**: `__session` (httpOnly/lax/30d), key `"user"`, value = `{ id, displayName, name, emails, accessToken, refreshToken?, expirationDateMs?, provider, role? }` — never `photo`/`_json`/`photos`. Changing this invalidates all live 30-day sessions.

package/dist/admin.d.mts

@@ -1,5 +1,5 @@
 import * as react_router from 'react-router';
-import { AuthUser, AuthGroup, AuthGroupMember, AuthAllowlistEntry, AuthDirectoryMembershipMode, AuthDirectoryStatus } from '@aiquants/auth-core';
+import { AuthUser, AuthGroup, AuthGroupMember, AuthAllowlistEntry, AuthDirectoryMembershipMode, AuthDirectoryStatus, AuthDirectoryCatalogSnapshot, AuthDirectoryCatalogGroup } from '@aiquants/auth-core';
 import React__default from 'react';
 
 /**
@@ -48,6 +48,32 @@ type UserAdminLabels = {
     };
     /** アクションが拒否・失敗したときの文言。 */
     errors: {
+        /** 一覧に無い上流キーを指定した。`{key}` に受け取った値。 */
+        unknownUpstream: string;
+        /** その上流グループは既に別のローカルグループへ連携している。`{key}` / `{group}`。 */
+        alreadyLinked: string;
+        /** ディレクトリ未設定の配備で連携を求められたときの説明。 */
+        directoryDisabled: string;
+        /** 必須欄が欠けている、または読めない値だったことの説明。 */
+        invalidField: string;
+        /**
+         * Shown for an intent this screen does not perform. この画面が行わない intent への文言。
+         *
+         * ⚠️ 受け取った値を含めない。認可より手前で返るため、認証を通っていない相手にも届く。
+         */
+        unknownIntent: string;
+        /**
+         * Operator-facing names for the form fields. 欄の、操作者に見える名前。
+         *
+         * ⚠️ `invalidField` の `{field}` に **通信上のキー** を差し込まない。日本語の文の中に
+         * `membershipMode` のような識別子が現れ、画面のどの欄を指すのか操作者には判らない。
+         * 表に無い欄はキーのまま出す (出さないより、判りにくくても出すほうがよい)。
+         */
+        fieldNames: Record<string, string>;
+        /** 許可リストの種別が既定の 2 値でなかったことの説明。 */
+        invalidAllowlistType: string;
+        /** 想定外の失敗 (原文はサーバーのログにだけ残す)。 */
+        unexpected: string;
         /**
          * Shown when the actor lacks permission for the attempted operation.
          * 操作の権限が無いときに出す文言。
@@ -56,6 +82,13 @@ type UserAdminLabels = {
          * 拒否理由といった内部の語彙が、権限を持たない相手にそのまま渡る。
          */
         forbidden: string;
+        /**
+         * Shown when the request body exceeds the ceiling. 本文が上限を越えたときの文言。
+         *
+         * この画面が送るのは短い文字列だけなので、越えるのは誤操作か攻撃である。どちらにも
+         * 同じ文言を返す (どこで弾かれたかを細かく教えない)。
+         */
+        requestTooLarge: string;
     };
     /** シェル (タブ枠) の見出し。 */
     heading: string;
@@ -64,6 +97,8 @@ type UserAdminLabels = {
         label: string;
         canWrite: string;
         canRead: string;
+        /** 削除だけを持つ主体の表示 (読み書きが無いことを「権限なし」と描かない)。 */
+        canDelete: string;
         none: string;
         /** 未結線・取得失敗・付与ゼロのいずれも「不明」であり、許可ではない。 */
         unknown: string;
@@ -77,6 +112,8 @@ type UserAdminLabels = {
     };
     usersView: {
         title: string;
+        /** 並べ替えの読み上げ名。`{column}` は列名。 */
+        sortBy: string;
         searchPlaceholder: string;
         /** 検索欄の読み上げ名。プレースホルダは入力すると消えるため名前にならない。 */
         searchLabel: string;
@@ -93,12 +130,65 @@ type UserAdminLabels = {
         activateAria: string;
         deactivateAria: string;
         /** 無効化はサインインを止める。確認を取る。 */
+        /** 検索で 0 件になったときの文言 (「登録が無い」と区別する)。 */
+        emptyFiltered: string;
+        /** 一覧の絞り込み結果を読み上げるための文言。 */
+        listSummary: string;
+        /** 昇順で並べ替え中の列の読み上げ名。 */
+        sortedAscending: string;
+        /** 降順で並べ替え中の列の読み上げ名。 */
+        sortedDescending: string;
         confirmDeactivate: string;
         empty: string;
     };
     groupsView: {
         /** 検索語に一致しないときの説明。空状態と混ぜると「消えた」と誤読される。 */
         emptyFiltered: string;
+        /** 作成方法の切替。ローカルに作るか、上流のグループから作るか。 */
+        /** 作成方法を選ぶ操作群の読み上げ名。 */
+        createModeLabel: string;
+        createModeLocal: string;
+        createModeUpstream: string;
+        /** 上流グループを選ぶ欄。 */
+        pickUpstream: string;
+        pickUpstreamPlaceholder: string;
+        /** 選択肢 1 件の副題。`{count}` はメンバー数。 */
+        upstreamOptionMembers: string;
+        /** すでに連携済みの選択肢に付ける表示。 */
+        upstreamAlreadyLinked: string;
+        /** 候補一覧が引けなかったときの説明。`{reason}` に理由。 */
+        /** 候補は引けたが、この配備の連携プロバイダ名が決まっていないことの説明。 */
+        providerUnset: string;
+        /** 候補を選ぶまで作成できないことの説明 (押せないボタンの理由)。 */
+        pickUpstreamFirst: string;
+        /**
+         * Shown when every upstream group is already linked. 上流のすべてが連携済みのときの文言。
+         *
+         * ⚠️ この場面で「先に選べ」と言ってはならない。従いようのない指示になる。
+         */
+        allUpstreamLinked: string;
+        /** 上流を読めたが 1 件も無かったことの説明。 */
+        catalogEmpty: string;
+        catalogUnavailable: string;
+        /** 上流へ届かないときの案内 (作成対話向け — この対話にアドレス欄は無い)。 */
+        catalogUnavailableHere: string;
+        /** 候補一覧をいつ観測したか。 */
+        catalogObservedAt: string;
+        /** 観測が配備の許す鮮度を越えている旨。 */
+        catalogStale: string;
+        /** 候補一覧を引けなかった理由の文言 (上流の例外文は使わない)。 */
+        catalogFailures: {
+            denied: string;
+            rateLimited: string;
+            upstreamError: string;
+            neverObserved: string;
+            unknown: string;
+        };
+        /** 上流から作る場合の説明 (何が起きるかを先に伝える)。 */
+        createUpstreamNotice: string;
+        /** グループのメンバー面へ移動する操作。 */
+        openMembers: string;
+        openMembersAria: string;
         title: string;
         searchPlaceholder: string;
         searchLabel: string;
@@ -110,6 +200,8 @@ type UserAdminLabels = {
         /** 所属人数。`{count}` を人数へ置換する。 */
         memberCountTemplate: string;
         confirmDelete: string;
+        /** 連携付きで作る前の確認。`{group}` / `{upstream}`。委譲は元に戻しづらい。 */
+        confirmCreateLinked: string;
         /** 行ごとの読み上げ名。`{group}` をグループ名へ置換する。 */
         editGroupAria: string;
         deleteGroupAria: string;
@@ -120,8 +212,25 @@ type UserAdminLabels = {
     };
     groupMembersView: {
         title: string;
+        /** 利用者の絞り込み。数百人の一覧を目で追わせない。 */
+        searchLabel: string;
+        searchPlaceholder: string;
+        /** 所属している人だけに絞る切替。`{count}` は該当数。 */
+        onlyMembers: string;
+        /** 絞り込み結果が空のときの説明。 */
+        emptyFiltered: string;
+        /** 一覧の要約。`{shown}` / `{total}` / `{members}`。 */
+        summary: string;
         selectGroup: string;
         selectPrompt: string;
+        /** グループが 1 つも無い配備での説明 (「選べ」は従えない指示になる)。 */
+        noGroups: string;
+        /** 所属だけに絞った結果 0 件になったときの説明。 */
+        emptyNoMembers: string;
+        /** 利用者が 1 人も登録されていない配備での説明。 */
+        noUsers: string;
+        /** 深いリンクが指すグループが見つからず、代替を出していることの説明。 */
+        deepLinkMissed: string;
         actionAdd: string;
         actionRemove: string;
         /** 行ごとの読み上げ名。`{user}` を利用者名へ置換する。 */
@@ -169,6 +278,8 @@ type UserAdminLabels = {
         syncEnabled: string;
         syncNow: string;
         syncQueued: string;
+        /** 同じ範囲の要求が既に待っていて、積まれなかったことの説明。 */
+        syncAlreadyPending: string;
         /** 同期が滞っていることの警告。停止はセキュリティ事象である。 */
         staleWarning: string;
         disabledWarning: string;
@@ -186,6 +297,8 @@ type UserAdminLabels = {
         pendingTemplate: string;
         /** 連携先が 1 つも残っていないときの説明。 */
         nothingToLink: string;
+        /** グループが 1 つも無い配備での説明 (「全部が連携済み」と区別する)。 */
+        noGroupsToLink: string;
         /** 未結線の配備で操作を出さない理由。 */
         notWiredNotice: string;
         /** 行ごとの読み上げ名。`{group}` をグループ名へ置換する。 */
@@ -204,9 +317,21 @@ type UserAdminLabels = {
         empty: string;
         /** 連携するグループを選ぶ欄。 */
         selectGroup: string;
+        /** 選択欄が自前で持つ文言。渡さないと英語のまま出る。 */
+        /** 選択欄の入力の手引き。 */
+        pickUpstreamPlaceholder: string;
+        pickerNoOptions: string;
+        pickerClear: string;
+        pickerToggle: string;
+        /** 選択中の値の読み上げ。`{value}`。 */
+        pickerSelected: string;
+        /** 候補件数の読み上げ。`{count}`。 */
+        pickerAvailable: string;
         /** 上流グループのアドレス入力。 */
         externalKeyPlaceholder: string;
         /** 連携解除の確認。台帳と許可設定が消える。 */
+        /** 連携を作る前の確認 (元へ戻すには連携解除という別の操作が要る)。 */
+        confirmLink: string;
         confirmUnlink: string;
         /** 同期の一時停止・再開。 */
         pause: string;
@@ -303,21 +428,43 @@ type UserAdminStore = {
      */
     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>;
 };
@@ -332,10 +479,44 @@ declare function createInMemoryUserAdminStore(initial?: {
     allowlist?: AuthAllowlistEntry[];
 }): UserAdminStore;
 /**
- * The CRUD verb an operation performs. Deliberately a plain string union so this package stays
- * independent of any particular authorization library.
- * 操作が行う CRUD 種別。特定の認可ライブラリに依存しないよう素の文字列 union で表現する。
+ * Normalizes an upstream key for comparison. 上流キーを比較用に正規化する処理。
+ *
+ * 前後の空白と大文字小文字を同一視する。**画面と実装で正規化がずれると**、選択欄は「未連携」と
+ * 見なすキーをサーバーが「連携済み」と見なす、といった食い違いが生まれる。1 か所に置く。
+ *
+ * @param key Raw upstream key. 生の上流キー。
+ * @returns The comparable form. 比較可能な形。
  */
+declare function normalizeUpstreamKey(key: string): string;
+/**
+ * An error whose own text is meant for the operator to read.
+ * 文面を **運用者に読ませるつもりで** 投げるエラー。
+ *
+ * ⚠️ ストアの例外文をそのまま画面へ返してはならない。ドライバの例外はスキーマ名・表名・制約名・
+ * 衝突した値・接続先をそのまま含み、それが閲覧権限しか持たない主体の画面に出る。一方で
+ * 「最後の管理者は外せません」のような業務上の拒否理由は、読めなければ操作そのものが行き詰まる。
+ * 両者は文面からは区別できないので、**投げる側が宣言する**。宣言の無い例外は一般的な文言になる。
+ *
+ * ホストのストアは、この class を継承しても `operatorFacing: true` を持たせてもよい
+ * (別パッケージのエラー型を継承できない事情に配慮した二経路である)。
+ */
+declare class UserAdminOperatorError extends Error {
+    /** 運用者向けであることの印。継承できない場合はこの属性だけでもよい。 */
+    readonly operatorFacing = true;
+    constructor(message: string);
+}
+/**
+ * An input problem the operator can fix, carrying a label key instead of a sentence.
+ * 運用者が直せる入力の問題。文ではなく **ラベルのキー** を運ぶ。
+ *
+ * ⚠️ メッセージを実装側で組むと、既定 (英語) の配備に日本語が出る。文言はラベルに集約し、
+ * ここでは「どの文言か」と差し替え値だけを運ぶ。
+ */
+declare class UserAdminInputError extends Error {
+    readonly labelKey: keyof UserAdminLabels["errors"];
+    readonly values: Record<string, string | number>;
+    constructor(labelKey: keyof UserAdminLabels["errors"], values?: Record<string, string | number>);
+}
 /**
  * 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
@@ -345,6 +526,11 @@ declare function createInMemoryUserAdminStore(initial?: {
 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 で表現する。
+ */
 type UserAdminAccess = "read" | "create" | "update" | "delete";
 /**
  * Access guard the user-admin surface is mounted behind. Deny by throwing
@@ -377,6 +563,83 @@ type UserAdminGuards = {
         error: unknown;
     }) => void;
 };
+/**
+ * Every intent the permission table knows. 権限表が知っている intent すべて。
+ *
+ * ⚠️ 消費側の網羅性検査のために公開する。検査側が intent を手書きで並べる形しか無いと、
+ * 実装に intent が増えても表は勝手には伸びず、**最も権限の重い新しい intent** だけが
+ * 無検査で通る状態が静かに生まれる。突き合わせる相手を実装側から提供する。
+ *
+ * @returns Intent names, in declaration order. 宣言順の intent 名。
+ */
+declare function userAdminIntents(): string[];
+/**
+ * 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. 要求する種別 (未知なら空)。
+ */
+declare function userAdminAccessFor(intent: string): readonly UserAdminAccess[];
+/**
+ * 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` などを既にここから受け取っている。
+ */
+type UserAdminCatalogGroup = AuthDirectoryCatalogGroup;
+/**
+ * The upstream catalog as the loader hands it to the views. loader がビューへ渡す上流の候補一覧。
+ *
+ * ⚠️ **これは利便性のための読み取りである。** 上流へ届かなくても画面は開かなければならない
+ * (グループ一覧や許可リストの閲覧は、選択欄の可否とは無関係である)。したがって失敗は
+ * `reason` として **描画可能な状態** に変換し、例外にしない。認可やサインイン判定のように
+ * 「判らないなら拒否」であるべき経路とは、意図的に扱いを変えている。
+ */
+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` は **一度も観測していない** ことを意味する (空の答えではない)。
+ */
+type UserAdminCatalogSnapshot = AuthDirectoryCatalogSnapshot;
+/**
+ * What a "sync now" request did. 「今すぐ同期」の要求が行ったこと。
+ *
+ * `already-pending` は失敗ではない — 同じ範囲の要求が既に待っている。ただし **成功でもない**:
+ * 何も積まれていないので、待っている行が誰にも拾われなければ何も起きない。
+ */
+type UserAdminSyncRequestOutcome = "queued" | "already-pending";
+/**
+ * Why the upstream catalog could not be listed, classified for display.
+ * 上流の候補一覧を引けなかった理由を、表示のために分類したもの。
+ *
+ * ⚠️ **上流の例外文をそのまま画面へ出してはならない。** サービスアカウントのアドレス、借用先、
+ * 内部 URL、資格情報の断片が混じり得る。管理面を開けるだけの主体に、それらを読ませる理由は無い。
+ * 原文は `console.error` へ出し、画面にはこの分類に対応する自前の文言を出す。
+ */
+type UserAdminCatalogFailure = "denied" | "rateLimited" | "upstreamError" | "neverObserved" | "unknown";
 /**
  * Neutral per-resource permission summary the admin shell renders in its header badge.
  * 管理シェルのヘッダーバッジが描画する、リソース単位の中立な権限サマリ。
@@ -399,6 +662,26 @@ 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
@@ -431,6 +714,7 @@ declare function createUserAdminApp(config: UserAdminAppConfig): {
         allowlist: AuthAllowlistEntry[];
         directoryStatus: AuthDirectoryStatus;
         myPermissions: Record<string, UserAdminPermission | undefined> | null;
+        catalog: UserAdminCatalog;
         labels: UserAdminLabels;
     }>;
     action: ({ request }: RouteArgs) => Promise<react_router.UNSAFE_DataWithResponseInit<{
@@ -438,7 +722,10 @@ declare function createUserAdminApp(config: UserAdminAppConfig): {
         error: string;
     }> | {
         ok: boolean;
-        error?: undefined;
+        syncRequest?: undefined;
+    } | {
+        ok: boolean;
+        syncRequest: UserAdminSyncRequestOutcome;
     } | {
         ok: boolean;
         error: string;
@@ -458,6 +745,15 @@ type UserAdminShellProps = {
  */
 declare function UserAdminShell({ children, renderHeader }: UserAdminShellProps): React__default.JSX.Element;
 
+/**
+ * @module admin/views
+ * @description The five tab views of the user administration screen.
+ * ユーザー管理画面を構成する 5 つのタブビュー。
+ *
+ * 一覧・検索・所属・許可リスト・ディレクトリ連携を描く。データはすべて loader から渡され、
+ * 書き込みはビュー唯一の fetcher (`useSubmitThen`) を通す。
+ */
+
 type UserAdminLoaderData = {
     segment: string;
     users: AuthUser[];
@@ -465,6 +761,8 @@ type UserAdminLoaderData = {
     groupMembers: AuthGroupMember[];
     allowlist: AuthAllowlistEntry[];
     directoryStatus: AuthDirectoryStatus;
+    /** 上流の候補一覧。選択欄を出す面でのみ `ready` になる。 */
+    catalog: UserAdminCatalog;
     labels?: UserAdminLabels;
 };
 declare function UsersView(): React__default.JSX.Element;
@@ -499,4 +797,4 @@ type AuthUserAdminAppViewProps = UserAdminShellProps;
  */
 declare function AuthUserAdminAppView({ renderHeader }?: AuthUserAdminAppViewProps): React__default.JSX.Element;
 
-export { AllowlistView, AuthUserAdminAppView, type AuthUserAdminAppViewProps, DirectoryView, GroupMembersView, GroupsView, type PartialUserAdminLabels, type UserAdminAccess, type UserAdminAppConfig, type UserAdminGuards, type UserAdminLabels, type UserAdminLoaderData, type UserAdminPermission, UserAdminShell, type UserAdminShellProps, type UserAdminStore, UsersView, createInMemoryUserAdminStore, createUserAdminApp, defaultUserAdminLabels, jaUserAdminLabels, resolveUserAdminLabels };
+export { AllowlistView, AuthUserAdminAppView, type AuthUserAdminAppViewProps, DirectoryView, GroupMembersView, GroupsView, type PartialUserAdminLabels, type UserAdminAccess, type UserAdminAppConfig, type UserAdminCatalog, type UserAdminCatalogFailure, type UserAdminCatalogGroup, type UserAdminCatalogSnapshot, type UserAdminGuards, UserAdminInputError, type UserAdminLabels, type UserAdminLoaderData, UserAdminOperatorError, type UserAdminPermission, UserAdminShell, type UserAdminShellProps, type UserAdminStore, type UserAdminSyncRequestOutcome, UsersView, createInMemoryUserAdminStore, createUserAdminApp, defaultUserAdminLabels, jaUserAdminLabels, normalizeUpstreamKey, resolveUserAdminLabels, userAdminAccessFor, userAdminIntents };