@aiquants/authz-react-router 0.6.0 → 0.7.1

package/README.md

@@ -33,7 +33,7 @@ This walkthrough takes a React Router v7 app from nothing to a permission-guarde
 
 ```ts
 // app/services/authz/config.ts
-import { defineAuthzSchema, getEffectivePermissions } from "@aiquants/authz-drizzle"
+import { defineAuthzSchema, getEffectivePermissionsMany, listResourceKeys } from "@aiquants/authz-drizzle"
 import { createAuthz } from "@aiquants/authz-react-router"
 import { db } from "~/db.server"            // your drizzle handle
 import { Users } from "~/models/Users"      // your user table (has numeric id)
@@ -45,8 +45,10 @@ const authz = createAuthz({
   appKey: "myapp",
   // request → your user id (or null → checked against "@anonymous" permissions)
   resolveUserId: async (request) => (await getSessionUser(request))?.id ?? null,
-  // load + merge this user's grants for one (app, resource)
-  getEffectivePermissions: (args) => getEffectivePermissions(db, authzTables, args),
+  // load + merge this user's grants for MANY resources in one round-trip
+  getEffectivePermissions: (args) => getEffectivePermissionsMany(db, authzTables, args),
+  // optional: lets `getMyPermissions(request)` report on every registered resource
+  listResourceKeys: () => listResourceKeys(db, authzTables, "myapp"),
 })
 
 export const { requirePermission, getMyPermissions } = authz
@@ -54,25 +56,31 @@ export const { requirePermission, getMyPermissions } = authz
 
 > If your DB pool can be cold at the first request (serverless / lazy connect), have `resolveUserId` and `getEffectivePermissions` await a connection-ready guard first — otherwise a cold-start DB error can surface as a misleading 403 instead of a 500.
 
-**Step 2 — guard a loader/action and apply scope.** On allow you get `{ userId, scope }`, so you can both authorize *and* narrow the data.
+**Step 2 — guard a loader/action, apply scope, and render the badge.** On allow you get `{ userId, scope, permission }` from a **single** evaluation, so you can authorize, narrow the data, *and* tell the user what they may do — without asking the database a second time.
 
 ```ts
 // app/routes/report.tsx
-import { applyRowScope, maskColumns } from "@aiquants/authz-drizzle"
+import { buildRowScopeWhere, maskColumns } from "@aiquants/authz-drizzle"
 import { requirePermission } from "~/services/authz/config"
 import { db } from "~/db.server"
 import { Report } from "~/models/Report"
 
 export async function loader({ request }: { request: Request }) {
-  const { scope } = await requirePermission(request, { resourceKey: "report", action: "read" })
+  const { scope, permission } = await requirePermission(request, { resourceKey: "report", action: "read" })
   // map the scope's logical field names → real columns (per endpoint; the core layer doesn't know your table)
   const columnMap = { dept: Report.dept, amount: Report.amount }
-  const rows = await applyRowScope(db.select().from(Report), scope.rowScope, columnMap)
-  return { rows: maskColumns(rows, scope.columnScope) }   // deny disallowed columns before returning
+  const where = buildRowScopeWhere(scope.rowScope, columnMap)   // undefined = all rows; 1=0 = no rows
+  const rows = await (where ? db.select().from(Report).where(where) : db.select().from(Report))
+  return { rows: maskColumns(rows, scope.columnScope), permission }   // deny disallowed columns before returning
 }
 // denied → AuthzDeniedError (throw a 403 Response in your error boundary, or pass options.failureRedirect)
 ```
 
+> **Guarding a sub-resource endpoint? Use `requirePermission`, not a hand-rolled check.** Reading a boolean off a
+> permission map and throwing your own 403 duplicates the decision — and a typo in the field name reads as `undefined`,
+> i.e. a silent denial. `requirePermission` is the only thing that decides access; `getMyPermissions` exists to *display*
+> permissions, not to enforce them.
+
 **Step 3 — register the resource + grant.** Insert a `TMResource('myapp','report')` and a `TDRolePermission` for the role(s) that should see it. Either run SQL, or build a tiny admin screen with the CRUD helpers (see the host app's admin guide). Example grant: "role `viewer` may `read` report, rows where dept ∈ {A}, hiding the amount column":
 
 ```sql
@@ -85,20 +93,35 @@ FROM dbo_authz.TMRole r JOIN dbo_authz.TMResource res ON res.app_key='myapp' AND
 WHERE r.role_key='viewer';
 ```
 
-**Step 4 — show the user their permission (optional).** Feed `getMyPermissions` into a loader and render the indicator.
+**Step 4 — show the user their permissions.** For the page's own resource, the badge data already came back from
+`requirePermission` (Step 2). `getMyPermissions` is for the *other* resources a screen wants to describe:
+
+```ts
+// several named resources — one round-trip, and the returned keys are typed from the argument,
+// so `myPermissions.reprot` is a compile error rather than an `undefined` at runtime
+const myPermissions = await getMyPermissions(request, { resourceKeys: ["report", "report_comment"] })
+
+// from a defineResources registry, keeping the keys literal-typed
+const fromRegistry = await getMyPermissions(request, { resourceKeys: resourceKeysOf(REPORT_RESOURCES) })
+
+// or every resource registered for the app (needs the `listResourceKeys` port)
+const all = await getMyPermissions(request)
+```
 
 ```tsx
-// loader: const myPermissions = await getMyPermissions(request, { resourceKeys: ["report"] })
 import { MyPermissionIndicator, MyPermissionStatus } from "@aiquants/authz-react-router"
 
 // 1. Single indicator badge group
 <MyPermissionIndicator permission={myPermissions.report} resourceName="Monthly Report" />
 
-// 2. Full "Your Permissions" status bar component for any page header/toolbar
+// 2. Full "your permissions" status bar component for any page header/toolbar
 <MyPermissionStatus permission={myPermissions.report} resourceName="Monthly Report" />
-// → "Your Permissions: [Read ○][Write △][Delete ×]" with tooltip "Target Resource: Monthly Report (report)"
+// → "あなたの権限: [閲覧 ○][編集 △][削除 ×]" with the tooltip "対象リソース: Monthly Report (report)"
 ```
 
+> ⚠️ Unlike the admin shell's `labels`, these two components ship **Japanese** defaults (`"あなたの権限"`, `"閲覧"` /
+> `"編集"` / `"削除"`, `"部分制限"`, and the `対象リソース: …` tooltip). Pass `prefixLabel` and `labels` to localize them.
+
 ## Scope cheat-sheet (§3.2)
 
 The JSON you put in `row_scope` / `column_scope` (full contract in `@aiquants/authz-core`):
@@ -114,19 +137,60 @@ Multiple roles **union** (wider wins): rows OR'd (any `NULL` ⇒ all rows); colu
 
 ## API
 
-- `createAuthz({ appKey, resolveUserId, resolveGroupIds?, getEffectivePermissions, onDeny? })` → `{ requirePermission, getMyPermissions, requireAndGetPermission }`.
+- `createAuthz({ appKey, resolveUserId, resolveGroupIds?, getEffectivePermissions, listResourceKeys?, onDeny? })` → `{ requirePermission, getMyPermissions }`.
+- `getEffectivePermissions({ userId, groupIds?, appKey, resourceKeys })` → `Record<resourceKey, EffectivePermission | null>`. **One call, many resources** — pair it with `getEffectivePermissionsMany` from `@aiquants/authz-drizzle` and N resources cost one round-trip. Keys the port omits are treated as "no permission" (fail-close).
+- `listResourceKeys(request)` → every resource key registered for the app. Optional; configuring it is what makes the no-argument `getMyPermissions(request)` legal. Without it that call throws `AuthzUsageError` naming both remedies instead of guessing.
 - `resolveGroupIds(request)` → the acting user's group ids. Forwarded automatically to `getEffectivePermissions` by both `requirePermission` and `getMyPermissions`, so group-granted roles count toward effective permissions. Returning `null`/`undefined` (or omitting the port) sends no `groupIds` at all.
   ⚠️ Without this port, roles assigned to groups in the admin UI have **no runtime effect** — the store writes succeed and the UI looks correct, so the failure is silent. Cover the wiring with a test.
-- `requirePermission(request, {resourceKey, action}, options?)` → `{ userId, scope }` on allow (so loaders apply row WHERE / column mask — not just 403). Denies throw `AuthzDeniedError` (403), or `throw redirect(options.failureRedirect)` when set.
-- `requireAndGetPermission(request, {resourceKey, action}, options?)` → `{ userId, scope, permission }`. Atomically performs guard and fetches matching UI `PermissionView` to prevent page-resource mismatches.
-- `defineResources({ ... })` → Type-safe centralized resource registry helper for resource keys and display names.
-- `getMyPermissions(request, {resourceKeys})` → `Record<resourceKey, PermissionView>` for the UI.
+- `requirePermission(request, {resourceKey, action}, options?)` → `{ userId, scope, permission }` on allow: the scope for row WHERE / column mask, **and** the `PermissionView` derived from the very same evaluation (no second lookup, so the guard and the badge can never disagree). Denies throw `AuthzDeniedError` (403), or `throw redirect(options.failureRedirect)` when set. A malformed query (blank `resourceKey`, unknown `action`, or the derived `"write"`) throws `AuthzUsageError` before anything is loaded — a mistake surfaces as a 500 you can read, never as a mysterious 403.
+- `getMyPermissions(request, {resourceKeys})` → `Record<K, PermissionView>` where `K` is the literal union of the keys you passed, so an unrequested key is a **compile error** rather than a runtime `undefined`. `getMyPermissions(request)` reports on every registered resource (requires `listResourceKeys`). Duplicate keys collapse; an empty list asks the database nothing.
+  ⚠️ The no-argument form's result **keys are your app's resource inventory**. Every value is still evaluated fail-closed (an unauthenticated caller gets all-false views), but do not hand the whole map to an unauthenticated client if the resource names themselves are sensitive — name the resources you actually render instead.
+- `AuthzUsageError` — thrown for API misuse (missing/ill-typed arguments, missing port). Deliberately distinct from `AuthzDeniedError`: misuse must not masquerade as a denial.
+- `defineResources({ ... })` → Type-safe centralized resource registry helper for resource keys and display names. Keys stay **literal-typed**.
+- `resourceKeysOf(registry)` → the registry's resource keys as a literal union array. Use it instead of `Object.keys(registry)`, which both widens to `string[]` (losing the key check on the permission map) and returns *property names* — wrong for entries that set an explicit `key`.
 - `toPermissionView(resourceKey, perm)` → serializable view (loader → client).
-- `usePermission(view)` → ○△× display states (`readState`/`writeState`/`deleteState`); pure, safe in render.
+- `usePermission(view)` → the same `can*` booleans plus ○△× display states (`readState`/`writeState`/`deleteState`); pure, safe in render.
 - `<MyPermissionIndicator permission={view} resourceName="Documents" expectedResourceKey="documents" />` → read / write(create∪update) / delete as ○△×. `read` is △ when row/column-restricted; `write` is ○ only when both create & update are held, △ when one. Hover shows resource name & key tooltip. Automatically flags mismatches if `permission.resourceKey !== expectedResourceKey`.
 - `<MyPermissionStatus permission={view} resourceName="Documents" expectedResourceKey="documents" prefixLabel="Your Permissions" />` → Reusable status component combining prefix label and permission indicator badges for any application page.
 - `<MyPermissionGroupStatus items={[{ resourceName: "Primary Resource", permission: primaryView }, { resourceName: "Sub Resource", permission: subView, level: 1 }]} variant="pills" | "popover" size="xs" labels={{ fullWrite: "Writable", readOnly: "Read-only" }} />` → Multi-resource permission widget for pages with multiple distinct resource scopes. Supports inline status tags (`variant="pills"`), single-button popover cards (`variant="popover"`), hierarchical tree indentation via `level` / `children`, and fully customizable status label mappings (`labels`).
 
+## One vocabulary, one decision
+
+Two rules make the whole surface predictable, and both exist because their absence produced real production bugs:
+
+1. **Every permission boolean is `can*`, everywhere.** `PermissionView` and `usePermission()` expose the *same*
+   `canRead` / `canCreate` / `canUpdate` / `canDelete` / `canWrite` names. Previously the view said `read` while the hook
+   said `canRead`, so reading `view.canRead` yielded `undefined` — falsy, therefore a **silent denial** that looked like
+   an authorization bug. A verb-shaped field is also undestructurable (`const { delete } = view` is a syntax error).
+2. **The guard decides once.** `requirePermission` returns the UI view built from the permission it just evaluated, so
+   there is no second query that could return a different answer. (The old `requireAndGetPermission` claimed to be
+   atomic but issued two independent lookups; it is gone — `requirePermission` always returns `permission`.)
+
+### Migrating from 0.6.x
+
+| Before | Now |
+| --- | --- |
+| `permissionView.read` / `.create` / `.update` / `.delete` / `.write` | `.canRead` / `.canCreate` / `.canUpdate` / `.canDelete` / `.canWrite` |
+| `requireAndGetPermission(request, query)` | `requirePermission(request, query)` — it already returns `permission` |
+| `getEffectivePermissions: (args) => …(args.resourceKey)` (one resource) | `getEffectivePermissions: (args) => …(args.resourceKeys)` returning a record (many resources) |
+| `createAuthzAdminApp({ …, getMyPermissions })` | port removed — the admin shell reads its badge off the guard |
+| `createAuthzAdminApp({ requirePermission })` resolving to `{ userId }` | must now resolve to `{ userId, permission }` — pass `createAuthz`'s `requirePermission` directly, or add `permission` to a hand-rolled guard |
+| `usePermission(view)` → `{ canRead, canWrite, canDelete, …States }` | adds `canCreate` / `canUpdate`, so it is a superset of the view's booleans |
+| `expectedResourceKey?: string` on the indicator components | now `NoInfer<K>` — bound to the permission's own key, so a mismatch is a compile error (0.6.x code that deliberately passed a different key stops compiling) |
+| `createAuthzAdminServer(...).loadMyPermissions` | removed — `layoutGuard` returns `{ userId, myPermissions }` from the guard it already runs |
+| `getMyPermissions(request, { resourceKeys: someStringArray })` → total map | values are now `PermissionView \| undefined` whenever the keys are not literals (a runtime-built list cannot promise which keys exist). Pass literals or `resourceKeysOf(registry)` to keep the total map, or add the presence check |
+| `getMyPermissions(request)` → `TypeError` | configure `listResourceKeys`, or pass `{ resourceKeys }` — otherwise a named `AuthzUsageError` |
+
+**Requirements.** TypeScript ≥ 5.4 to consume the emitted `.d.ts` (the indicator props use the built-in `NoInfer`), and
+an ES2022 runtime for `Object.hasOwn` (Node ≥ 16.9 — the package already declares `engines.node >= 18` — and any
+browser from 2022 on).
+
+> `AuthzUsageError` is a **programmer** error, so it travels like any other thrown error: React Router hands the
+> boundary a sanitized error outside development, and the actionable message lands in your **server log**. Read it
+> there — the browser will only show the generic 500 body.
+
+`readPartial` and `actions` keep their names (they are not booleans about an action).
+
 ## Admin UI tabs
 
 The splat-mounted admin app (`createAuthzAdminApp`) serves `roles`, `resources`, `role_permissions`, `user_roles`, plus:

package/dist/index.d.mts

@@ -2,10 +2,36 @@ import * as react_router from 'react-router';
 import * as react from 'react';
 import { ReactNode, CSSProperties } from 'react';
 import * as _aiquants_authz_core from '@aiquants/authz-core';
-import { EffectivePermission, DenyInfo, AuthzAction, GuardResult, AuthzGrant, AuthzUser, AuthzRole, AuthzResource, AuthzAssignment, AuthzGroupRoleAssignment, AuthzGroupSummary, AuthzAdminStore } from '@aiquants/authz-core';
+import { EffectivePermission, DenyInfo, AuthzAction, MergedScope, AuthzGrant, AuthzUser, AuthzRole, AuthzResource, AuthzAssignment, AuthzGroupRoleAssignment, AuthzGroupSummary, AuthzAdminStore } from '@aiquants/authz-core';
+
+/**
+ * React Router (v7) adapter: binds `appKey` + the DI ports and exposes the loader/action authorization API.
+ * React Router (v7) 向けアダプタ。`appKey` と DI ポートを束ね、loader/action 用の認可 API を公開するモジュール。
+ *
+ * 設計上の中心的な不変条件は **判定は 1 回だけ** ということ。ガード (`requirePermission`) と
+ * UI 表示用の権限ビューは同一の実効権限から導出されるため、「画面は開けるのに一覧では false」
+ * という乖離が構造的に起こり得ない。
+ */
 
 type Awaitable<T> = T | Promise<T>;
 type AuthzUserId = string | number;
+/**
+ * Thrown when the API itself is called incorrectly (bad arguments, missing port) — a programmer error,
+ * never an authorization decision. It is deliberately NOT an `AuthzDeniedError`: a misuse must surface as a
+ * loud 500, not as a silent 403 that looks like a permission problem.
+ * API の使い方が誤っている場合に送出される例外。認可拒否 (403) とは明確に区別されるプログラマ向けエラー。
+ */
+declare class AuthzUsageError extends Error {
+    constructor(message: string);
+}
+/** Arguments handed to the {@link AuthzConfig.getEffectivePermissions} port. 実効権限ポートへ渡す引数。 */
+type EffectivePermissionsQuery = {
+    userId: AuthzUserId | null;
+    groupIds?: (string | number)[];
+    appKey: string;
+    /** Always a de-duplicated, non-empty list — the port may load them all in one round-trip. Read-only: the adapter reports on exactly these keys. */
+    resourceKeys: readonly string[];
+};
 type AuthzConfig = {
     /** Stable app identifier (e.g. "quants"). Bound into every permission query. */
     appKey: string;
@@ -13,13 +39,18 @@ type AuthzConfig = {
     resolveUserId: (request: Request) => Awaitable<AuthzUserId | null | undefined>;
     /** Optionally resolve acting user's group IDs from the request or session. */
     resolveGroupIds?: (request: Request) => Awaitable<(string | number)[] | null | undefined>;
-    /** Load effective permissions for (user, app, resource) — typically via @aiquants/authz-drizzle. */
-    getEffectivePermissions: (args: {
-        userId: AuthzUserId | null;
-        groupIds?: (string | number)[];
-        appKey: string;
-        resourceKey: string;
-    }) => Awaitable<EffectivePermission | null | undefined>;
+    /**
+     * Load effective permissions for (user, app, resources) — **one call, many resources** (typically
+     * `getEffectivePermissionsMany` from `@aiquants/authz-drizzle`). A key with no grants may be omitted or
+     * mapped to `null`; both mean "no permission" (fail-close).
+     */
+    getEffectivePermissions: (args: EffectivePermissionsQuery) => Awaitable<Record<string, EffectivePermission | null | undefined> | null | undefined>;
+    /**
+     * Optional: every resource key registered for this app (typically `listResourceKeys` from
+     * `@aiquants/authz-drizzle`). Configuring it is what makes `getMyPermissions(request)` — with no resource
+     * list — legal; without it that call throws {@link AuthzUsageError} instead of guessing.
+     */
+    listResourceKeys?: (request: Request) => Awaitable<readonly string[] | null | undefined>;
     /** Default deny handler. If omitted, denies throw AuthzDeniedError (403). */
     onDeny?: (info: DenyInfo) => void;
 };
@@ -27,41 +58,82 @@ type RequirePermissionOptions = {
     /** When set, denials `throw redirect(failureRedirect)` instead of throwing 403. */
     failureRedirect?: string;
 };
-/** Serializable per-resource permission summary for UI (loader → component). */
-type PermissionView = {
-    resourceKey: string;
-    read: boolean;
-    create: boolean;
-    update: boolean;
-    delete: boolean;
+/**
+ * Serializable per-resource permission summary for UI (loader → component).
+ * UI 向けの直列化可能なリソース単位権限サマリ (loader からコンポーネントへ受け渡す形)。
+ *
+ * 真偽値は `can` 接頭辞で統一されている。`delete` のような素の動詞名は分割代入できず
+ * (`const { delete } = view` は構文エラー)、フックの戻り値との二重語彙も生むため採用しない。
+ */
+type PermissionView<K extends string = string> = {
+    resourceKey: K;
+    canRead: boolean;
+    canCreate: boolean;
+    canUpdate: boolean;
+    canDelete: boolean;
     /** create ∪ update */
-    write: boolean;
+    canWrite: boolean;
     /** read granted but row and/or column restricted (→ △ partial). */
     readPartial: boolean;
     actions: AuthzAction[];
 };
-/** Map an EffectivePermission to a serializable {@link PermissionView}. */
-declare function toPermissionView(resourceKey: string, perm: EffectivePermission | null | undefined): PermissionView;
+/** Result of a successful {@link createAuthz} guard. ガード成功時の戻り値。 */
+type RequirePermissionResult<K extends string = string> = {
+    userId: AuthzUserId | null;
+    /** Effective row/column scope for the guarded action — apply as WHERE / column mask. */
+    scope: MergedScope;
+    /** UI view derived from the **same** evaluation as the guard decision (no second lookup). */
+    permission: PermissionView<K>;
+};
+/**
+ * Permission views keyed by the exact resource keys that were requested.
+ * 要求したキーで型付けした権限ビュー群。
+ *
+ * リテラルのキーを渡した場合だけ「そのキーは必ず存在する」形になる。`string[]` のようにキーが実行時に
+ * しか分からない場合は `| undefined` を含む索引型へ落ち、存在チェックを強制する (総和型の索引を
+ * 名乗ると、要求していないキーが型の上では必ず存在することになり、元の不具合と同じ罠に戻る)。
+ *
+ * ⚠️ キーは配列の **要素型** から導かれる。`flag ? ["a"] : ["b"]` のように要素型が合併になる式では、
+ * 実行時に片方しか無くても型の上では両方が存在する扱いになる。リテラル配列を直接渡すか
+ * `resourceKeysOf(registry)` を使うこと。
+ * ⚠️ 戻り値を `Record<string, …>` 型の変数へ代入すると、その文脈から `K` が `string` へ広がり
+ * 索引型 (値は `| undefined`) に落ちる。リテラルキーの保証が要る箇所では代入先を広げないこと。
+ * ⚠️ 戻り値は素のオブジェクト。要求していない `toString` などのキーを読むと `Object.prototype` の
+ * メンバが返る (索引型の `| undefined` とは一致しない)。要求したキーだけを読むこと。
+ */
+type PermissionViewMap<K extends string> = string extends K ? Record<string, PermissionView | undefined> : {
+    [P in K]: PermissionView<P>;
+};
+/**
+ * Map an EffectivePermission to a serializable {@link PermissionView}.
+ * 実効権限を直列化可能な {@link PermissionView} へ変換する処理。
+ *
+ * @returns The UI-facing permission summary (all-false when `perm` is absent). UI 表示用の権限サマリ。
+ */
+declare function toPermissionView<K extends string>(resourceKey: K, perm: EffectivePermission | null | undefined): PermissionView<K>;
 /**
  * React Router adapter. Binds `appKey` and the DI deps, exposing:
- *  - `requirePermission(request, {resourceKey, action}, options?)` → `{ userId, scope }` on allow
- *    (apply row WHERE / column mask with the returned scope); denies throw 403 or redirect.
- *  - `getMyPermissions(request, {resourceKeys})` → `Record<resourceKey, PermissionView>` for the UI.
+ *  - `requirePermission(request, {resourceKey, action}, options?)` → `{ userId, scope, permission }` on allow
+ *    (apply row WHERE / column mask with `scope`; render `permission` in the UI); denies throw 403 or redirect.
+ *  - `getMyPermissions(request, {resourceKeys})` → `Record<resourceKey, PermissionView>` for the UI,
+ *    or `getMyPermissions(request)` for every registered resource when `listResourceKeys` is configured.
+ * `appKey` と DI ポートを束ね、ガードと自己権限取得の 2 面だけを公開するファクトリ。
+ *
+ * @returns The bound `requirePermission` / `getMyPermissions` pair. 結線済みの認可 API 一式。
  */
 declare function createAuthz(config: AuthzConfig): {
-    requirePermission: (request: Request, query: {
-        resourceKey: string;
+    requirePermission: <K extends string>(request: Request, query: {
+        resourceKey: K;
         action: AuthzAction;
-    }, options?: RequirePermissionOptions) => Promise<GuardResult<AuthzUserId>>;
-    getMyPermissions: (request: Request, query: {
-        resourceKeys: string[];
-    }) => Promise<Record<string, PermissionView>>;
-    requireAndGetPermission: (request: Request, query: {
-        resourceKey: string;
-        action: AuthzAction;
-    }, options?: RequirePermissionOptions) => Promise<GuardResult<AuthzUserId> & {
-        permission: PermissionView;
-    }>;
+    }, options?: RequirePermissionOptions) => Promise<RequirePermissionResult<K>>;
+    getMyPermissions: {
+        <K extends string>(request: Request, options: {
+            resourceKeys: readonly K[];
+        }): Promise<PermissionViewMap<K>>;
+        (request: Request, options?: {
+            resourceKeys?: readonly string[];
+        }): Promise<Record<string, PermissionView | undefined>>;
+    };
 };
 
 /** Authz admin UI strings (i18n). Defaults are English; override per-section via `createAuthzAdminRoutes(..., { labels })`. */
@@ -182,7 +254,7 @@ type WithLabels = {
     labels: AuthzAdminLabels;
 };
 type AuthzLayoutData = WithLabels & {
-    myPermissions: Record<string, PermissionView>;
+    myPermissions: Record<string, PermissionView | undefined>;
     adminResourceKey: string;
     basePath?: string;
 };
@@ -286,18 +358,17 @@ type CreateAuthzAdminServerOptions = {
     /** 未ログインをログインへ誘導する(例: throw redirect(...))。 */
     requireUser: (request: Request) => Promise<unknown>;
     /**
-     * 認可ガード(アプリの createAuthz 由来)。allow で { userId } を返す。
-     * 0.2.0 で GuardResult.userId が nullable 化したため、戻り型も null を受ける。
-     * userId==null(未解決/万一の public 付与)は createAuthzAdminServer 内で deny する
+     * Authorization guard supplied by the app (from `createAuthz`); allow → `{ userId, permission }`.
+     * 認可ガード (アプリの createAuthz 由来)。allow で { userId, permission } を返すポート。
+     * `userId` は nullable(未解決/万一の public 付与)であり、createAuthzAdminServer 内で deny する
      * (管理経路は監査・自己権限計算に実 id が必須のため非 null を保証)。
+     * `permission` は **同一判定から導かれた** 自己権限ビューであり、表示用に再取得しない
+     * (再取得は「ガードは通るのにバッジは権限なし」という乖離の温床)。
      */
     requirePermission: (request: Request, query: PermissionQuery) => Promise<{
         userId: string | number | null;
+        permission: PermissionView;
     }>;
-    /** 自己権限表示用(アプリの createAuthz 由来)。 */
-    getMyPermissions: (request: Request, args: {
-        resourceKeys: string[];
-    }) => Promise<Record<string, PermissionView>>;
     /** 文言の部分上書き(既定は日本語)。 */
     labels?: PartialAuthzAdminLabels;
 };
@@ -307,9 +378,9 @@ declare function createAuthzAdminServer(opts: CreateAuthzAdminServerOptions): {
     resourceKey: string;
     layoutGuard: (request: Request) => Promise<{
         userId: string | number;
+        myPermissions: Record<string, PermissionView | undefined>;
     }>;
-    loadMyPermissions: (request: Request) => Promise<Record<string, PermissionView>>;
-    /** /authz レイアウト: requireUser(302) → requirePermission(read, 403) → 自己権限取得。 */
+    /** /authz レイアウト: requireUser(302) → requirePermission(read, 403)。自己権限はガードの戻り値から得る。 */
     layout: {
         loader({ request }: Req): Promise<AuthzLayoutData>;
     };
@@ -376,6 +447,12 @@ type CreateAuthzAdminAppOptions = CreateAuthzAdminServerOptions & {
     /** マウントのベースパス(タブリンク/未指定セグメントのリダイレクト先)。既定 `/authz`。 */
     basePath?: string;
 };
+/**
+ * Build the loader/action pair that serves the whole authorization admin UI from one splat route.
+ * 認可管理 UI 全体を 1 本のスプラットルートで提供する loader/action 対を生成するファクトリ。
+ *
+ * @returns The route `loader` / `action` plus the underlying server for direct use. ルートの loader/action と内部サーバ。
+ */
 declare function createAuthzAdminApp(opts: CreateAuthzAdminAppOptions): {
     loader: (args: RouteArgs) => Promise<{
         labels: AuthzAdminLabels;
@@ -383,14 +460,14 @@ declare function createAuthzAdminApp(opts: CreateAuthzAdminAppOptions): {
         selfAdminRoleIds?: number[];
         segment: string;
         basePath: string;
-        myPermissions: Record<string, PermissionView>;
+        myPermissions: Record<string, PermissionView | undefined>;
         adminResourceKey: string;
     } | {
         labels: AuthzAdminLabels;
         resources: _aiquants_authz_core.AuthzResource[];
         segment: string;
         basePath: string;
-        myPermissions: Record<string, PermissionView>;
+        myPermissions: Record<string, PermissionView | undefined>;
         adminResourceKey: string;
     } | {
         labels: AuthzAdminLabels;
@@ -406,7 +483,7 @@ declare function createAuthzAdminApp(opts: CreateAuthzAdminAppOptions): {
         }>;
         segment: string;
         basePath: string;
-        myPermissions: Record<string, PermissionView>;
+        myPermissions: Record<string, PermissionView | undefined>;
         adminResourceKey: string;
     } | {
         labels: AuthzAdminLabels;
@@ -420,7 +497,7 @@ declare function createAuthzAdminApp(opts: CreateAuthzAdminAppOptions): {
         selfAdminRoleIds?: number[];
         segment: string;
         basePath: string;
-        myPermissions: Record<string, PermissionView>;
+        myPermissions: Record<string, PermissionView | undefined>;
         adminResourceKey: string;
     } | {
         labels: AuthzAdminLabels;
@@ -429,7 +506,7 @@ declare function createAuthzAdminApp(opts: CreateAuthzAdminAppOptions): {
         groups: _aiquants_authz_core.AuthzGroupSummary[];
         segment: string;
         basePath: string;
-        myPermissions: Record<string, PermissionView>;
+        myPermissions: Record<string, PermissionView | undefined>;
         adminResourceKey: string;
     }>;
     action: (args: RouteArgs) => Promise<unknown>;
@@ -438,8 +515,8 @@ declare function createAuthzAdminApp(opts: CreateAuthzAdminAppOptions): {
         resourceKey: string;
         layoutGuard: (request: Request) => Promise<{
             userId: string | number;
+            myPermissions: Record<string, PermissionView | undefined>;
         }>;
-        loadMyPermissions: (request: Request) => Promise<Record<string, PermissionView>>;
         layout: {
             loader({ request }: {
                 request: Request;
@@ -608,12 +685,16 @@ declare function getPermissionSummary(permission: PermissionView | null | undefi
  */
 declare function MyPermissionGroupStatus({ items, prefixLabel, variant, size, labels, className, style }: MyPermissionGroupStatusProps): react.JSX.Element;
 
-type MyPermissionIndicatorProps = {
-    permission: PermissionView | null | undefined;
+type MyPermissionIndicatorProps<K extends string = string> = {
+    permission: PermissionView<K> | null | undefined;
     /** Human-readable resource display name (e.g. "文書データ"). Falls back to permission.resourceKey. */
     resourceName?: string;
-    /** Expected resource key to detect mismatches with permission.resourceKey during development. */
-    expectedResourceKey?: string;
+    /**
+     * Expected resource key. Typed as `NoInfer<K>`, so when the permission carries a literal key
+     * (`getMyPermissions` / `requirePermission` both do) a mismatch is a **compile error**; the runtime
+     * detector below stays for dynamically-keyed and JavaScript callers.
+     */
+    expectedResourceKey?: NoInfer<K>;
     /** Whether to include resource name/key tooltip. Default true. */
     showResourceTooltip?: boolean;
     labels?: {
@@ -625,7 +706,7 @@ type MyPermissionIndicatorProps = {
     showScopeSummary?: boolean;
     className?: string;
 };
-type MyPermissionStatusProps = MyPermissionIndicatorProps & {
+type MyPermissionStatusProps<K extends string = string> = MyPermissionIndicatorProps<K> & {
     /** Label prefix shown before the indicator badges. Default: "あなたの権限" */
     prefixLabel?: string;
     /** Whether to display the prefix label. Default: true */
@@ -642,12 +723,12 @@ declare function formatResourceTooltip(resourceKey?: string, resourceName?: stri
  * Display permission indicator badges for read, write, and delete capabilities.
  * 閲覧・編集・削除の権限状態バッジ群を描画。
  */
-declare function MyPermissionIndicator({ permission, resourceName, expectedResourceKey, showResourceTooltip, labels, showScopeSummary, className }: MyPermissionIndicatorProps): react.JSX.Element;
+declare function MyPermissionIndicator<K extends string = string>({ permission, resourceName, expectedResourceKey, showResourceTooltip, labels, showScopeSummary, className }: MyPermissionIndicatorProps<K>): react.JSX.Element;
 /**
  * Reusable "Your Permissions" status bar component suitable for any application page.
  * 「あなたの権限」ラベルと権限状態インジケータを束ねた再利用可能なコンポーネント。
  */
-declare function MyPermissionStatus({ permission, resourceName, expectedResourceKey, prefixLabel, showPrefixLabel, showResourceTooltip, labels, showScopeSummary, className, style }: MyPermissionStatusProps): react.JSX.Element;
+declare function MyPermissionStatus<K extends string = string>({ permission, resourceName, expectedResourceKey, prefixLabel, showPrefixLabel, showResourceTooltip, labels, showScopeSummary, className, style, }: MyPermissionStatusProps<K>): react.JSX.Element;
 
 /**
  * Resource definition and registry utilities for preventing page-resource mismatches.
@@ -670,19 +751,66 @@ type ResourceDefinitionInput = {
     description?: string;
 };
 type ResourceRegistry<T extends Record<string, ResourceDefinition>> = T;
+/**
+ * The resource key an entry resolves to: its explicit `key`, otherwise the property name.
+ * `key` を明示していればそれ、無ければプロパティ名。
+ *
+ * `Extract<…, string>` を挟むのは `key?: string` (省略可) が `string | undefined` になり、素の
+ * `extends string` では偽になってプロパティ名を名乗ってしまうため (実行時は `key` を使うので型が嘘になる)。
+ * `key` を書いていないエントリでは `Extract` が `never` になり、プロパティ名へ落ちる。
+ */
+type ResolvedResourceKey<PropertyName extends string, Input extends ResourceDefinitionInput> = [Extract<Input["key"], string>] extends [never] ? PropertyName : Extract<Input["key"], string>;
 /**
  * Define type-safe resource registry for an application.
  * アプリ全体のリソース定義（キー・表示名・説明）を一元管理するヘルパー。
+ *
+ * 各エントリの `key` はリテラル型のまま保持する。`Record<string, …>` へ広げてしまうと
+ * {@link resourceKeysOf} が `string[]` に落ち、権限マップのキー型検査が効かなくなるため。
+ *
+ * @returns The registry with literal-typed resource keys. リソースキーをリテラル型で保持したレジストリ。
  */
-declare function defineResources<T extends Record<string, ResourceDefinitionInput>>(resources: T): {
-    [K in keyof T & string]: ResourceDefinition;
+declare function defineResources<const T extends Record<string, ResourceDefinitionInput>>(resources: T): {
+    [K in keyof T & string]: {
+        key: ResolvedResourceKey<K, T[K]>;
+        name: string;
+        description?: string;
+    };
 };
+/**
+ * Extract a registry's resource keys with their literal types preserved.
+ * レジストリのリソースキーをリテラル型を保ったまま取り出す処理。
+ *
+ * `Object.keys(registry)` は `string[]` になり、`getMyPermissions` の戻り値も索引型へ落ちてキーの誤りを
+ * 検出できなくなる。加えて `Object.keys` は **プロパティ名** を返すため、`key` を明示したエントリでは
+ * 実際のリソースキーと食い違う。
+ *
+ * ⚠️ 1 エントリでもリテラルでない `key` (例: 変数由来の `string`) を持つと、合併の性質上レジストリ全体の
+ * キー型が `string` へ広がり、他のエントリ分のコンパイル時検査も無効になる。`key` は必ずリテラルで書くこと。
+ *
+ * @returns The registry's resource keys as a literal union array. リテラル合併型のリソースキー配列。
+ */
+declare function resourceKeysOf<T extends Record<string, {
+    key: string;
+}>>(registry: T): Array<T[keyof T & string]["key"]>;
+
+/**
+ * Display-state derivation for a {@link PermissionView} (pure, no React state involved).
+ * {@link PermissionView} から表示状態を導出するモジュール (React の状態は一切持たない純粋関数)。
+ */
 
 type PermState = "full" | "partial" | "none";
+/**
+ * Display-oriented reading of a {@link PermissionView}: the same `can*` booleans (safe defaults when the
+ * view is absent) plus the ○△× tri-state used by the indicator components.
+ * {@link PermissionView} の表示向け読み取り結果。同名の `can*` 真偽値と ○△× の三値状態を併せ持つ形。
+ */
 type UsePermission = {
     canRead: boolean;
-    canWrite: boolean;
+    canCreate: boolean;
+    canUpdate: boolean;
     canDelete: boolean;
+    /** create ∪ update */
+    canWrite: boolean;
     /** read: none(×) / partial(△, row|col restricted) / full(○). */
     readState: PermState;
     /** write = create ∪ update: full(○ both) / partial(△ one) / none(×). */
@@ -692,7 +820,10 @@ type UsePermission = {
 /**
  * Derive ○△× display states from a {@link PermissionView}. Pure (safe to call in render);
  * named `usePermission` for ergonomic call-sites.
+ * {@link PermissionView} から ○△× の表示状態を導出する純粋関数 (レンダー内から安全に呼べる形)。
+ *
+ * @returns The permission booleans plus their display states. 権限の真偽値と表示状態の組。
  */
 declare function usePermission(view: PermissionView | null | undefined): UsePermission;
 
-export { AuthzAdminAppView, type AuthzAdminAppViewProps, type AuthzAdminLabels, type AuthzConfig, AuthzErrorBoundary, type AuthzGrantsData, AuthzGrantsView, type AuthzGraphData, AuthzGraphView, type AuthzGroupRolesData, AuthzGroupRolesView, AuthzLayout, type AuthzLayoutData, type AuthzLayoutProps, type AuthzLayoutShellProps, type AuthzNodeType, type AuthzResourcesData, AuthzResourcesView, type AuthzRolesData, AuthzRolesView, type AuthzUserId, type AuthzUserRolesData, AuthzUserRolesView, type CreateAuthzAdminAppOptions, type CreateAuthzAdminServerOptions, ErrorAlert, Field, type MyPermissionGroupItem, MyPermissionGroupStatus, type MyPermissionGroupStatusProps, MyPermissionIndicator, type MyPermissionIndicatorProps, MyPermissionStatus, type MyPermissionStatusProps, type PartialAuthzAdminLabels, type PermState, type PermissionView, type RequirePermissionOptions, type ResourceDefinition, type ResourceDefinitionInput, type ResourceRegistry, type UsePermission, createAuthz, createAuthzAdminApp, createAuthzAdminServer, defaultAuthzAdminLabels, defineResources, flattenGroupItems, formatResourceTooltip, getPermissionSummary, makeAuthzErrorBoundary, resolveLabels, toPermissionView, ui, usePermission };
+export { AuthzAdminAppView, type AuthzAdminAppViewProps, type AuthzAdminLabels, type AuthzConfig, AuthzErrorBoundary, type AuthzGrantsData, AuthzGrantsView, type AuthzGraphData, AuthzGraphView, type AuthzGroupRolesData, AuthzGroupRolesView, AuthzLayout, type AuthzLayoutData, type AuthzLayoutProps, type AuthzLayoutShellProps, type AuthzNodeType, type AuthzResourcesData, AuthzResourcesView, type AuthzRolesData, AuthzRolesView, AuthzUsageError, type AuthzUserId, type AuthzUserRolesData, AuthzUserRolesView, type CreateAuthzAdminAppOptions, type CreateAuthzAdminServerOptions, type EffectivePermissionsQuery, ErrorAlert, Field, type MyPermissionGroupItem, MyPermissionGroupStatus, type MyPermissionGroupStatusProps, MyPermissionIndicator, type MyPermissionIndicatorProps, MyPermissionStatus, type MyPermissionStatusProps, type PartialAuthzAdminLabels, type PermState, type PermissionView, type PermissionViewMap, type RequirePermissionOptions, type RequirePermissionResult, type ResourceDefinition, type ResourceDefinitionInput, type ResourceRegistry, type UsePermission, createAuthz, createAuthzAdminApp, createAuthzAdminServer, defaultAuthzAdminLabels, defineResources, flattenGroupItems, formatResourceTooltip, getPermissionSummary, makeAuthzErrorBoundary, resolveLabels, resourceKeysOf, toPermissionView, ui, usePermission };