@rytass/wms-module-graphql 0.3.0 → 0.4.0

package/README.md

@@ -62,6 +62,32 @@ You register a **single** `GraphQLModule.forRootAsync(...)` of your own, mix you
 
 `WmsModuleGraphqlModule` internally wires `WmsModuleCoreModule.forRootAsync` so you do not need to import the core module separately when using this package.
 
+## Authorization
+
+Every WMS root `@Query` / `@Mutation` is annotated with `@WmsOperation({ resource, action })` — a **host-neutral** permission requirement enforced by the library's own route-level `WmsAuthGuard`, which delegates the allow/deny decision to an `authChecker` **you** supply. The library never imports your auth system; you map WMS's `resource`/`action` onto whatever you use (Casbin, RBAC, JWT scopes…).
+
+> ⚠️ **Using a global guard (e.g. member-base's `CasbinGuard` as `APP_GUARD`)?** A deny-by-default global guard blankets *every* resolver in the schema, including WMS's, and rejects them all because they carry no host-specific metadata — "every WMS operation is forbidden". WMS fixes this by stamping each operation with a host-skip marker so your global guard **defers**, while `WmsAuthGuard` does the real enforcement. **You do not touch your global guard.**
+
+```ts
+import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+import { createMemberBaseWmsAuthChecker } from '@rytass/wms-module-graphql/adapters/member-base';
+
+WmsModuleGraphqlModule.forRootAsync({
+  useFactory: async () => ({}),
+  defaultLoaderSerialId: 'DEFAULT',
+  defaultLoaderTypeKey: 'DEFAULT',
+  defaultLocationKey: 'DEFAULT',
+  // optional — omit to stay fully permissive (local dev / demos)
+  authChecker: createMemberBaseWmsAuthChecker({
+    map: ({ resource, action }) => [[`wms:${resource}`, action]],
+  }),
+});
+```
+
+The member-base adapter reuses everything `CasbinGuard` already put on the request (verified `payload`, `enforcer`, your custom `casbinPermissionChecker`) so WMS enforces with the **exact same** policy engine as your own resolvers — with **zero** member-base import on the WMS side. For custom JWT/RBAC, pass your own `authChecker: (ctx, { resource, action }) => boolean`.
+
+➡️ **Full design & recipes: [`docs/authorization.md`](./docs/authorization.md)** (the problem, execution order, member-base / custom-JWT / no-guard recipes, the single coupling point, public API, FAQ).
+
 ## DataLoader context
 
 The module ships a `HelperModule` (auto-registered) that provides a singleton `LoaderService`. To avoid N+1 queries, the WMS resolvers expect a per-request DataLoader trio at `context.loaders`:
@@ -97,12 +123,14 @@ Full documentation is shipped inside this package under the `docs/` directory (a
 | Document | Description |
 |---|---|
 | [`docs/integration-guide.md`](./docs/integration-guide.md) | Step-by-step wiring guide for NestJS + Next.js consumers |
+| [`docs/authorization.md`](./docs/authorization.md) | Complete resolver-authorization design & integration recipes (member-base / custom JWT / no-guard) |
 | [`docs/api-reference.md`](./docs/api-reference.md) | Complete export catalog with signatures and usage examples |
 
 GitHub hosted links (always up-to-date):
 
 - [Integration Guide — §4 Backend setup](https://github.com/Rytass/WMS-Module/blob/main/docs/integration-guide.md#4-backend-setup-nestjs--graphql--typeorm)
 - [Integration Guide — §13.1 Existing GraphQLModule co-existence](https://github.com/Rytass/WMS-Module/blob/main/docs/integration-guide.md#13-integrating-into-an-existing-nestjs--nextjs-project)
+- [Authorization — design & recipes](https://github.com/Rytass/WMS-Module/blob/main/libs/graphql/docs/authorization.md)
 - [API Reference — @rytass/wms-module-graphql](https://github.com/Rytass/WMS-Module/blob/main/docs/api-reference.md#rytasswms-module-graphql)
 
 ## License

package/adapters/member-base.d.ts

@@ -0,0 +1,35 @@
+import type { WmsAuthChecker, WmsOperationRequirement } from '../lib/auth';
+/**
+ * A Casbin `[subject, action]` tuple, e.g. `['wms:material', 'read']`.
+ */
+export type CasbinAction = [string, string];
+export interface MemberBaseWmsAuthCheckerOptions {
+    /**
+     * Map a host-neutral WMS requirement onto one or more Casbin
+     * `[subject, action]` tuples. This is where your project's permission naming
+     * convention lives. Returning several tuples means "allow if *any* passes"
+     * (member-base's default checker is OR-based).
+     *
+     * @example
+     * ```ts
+     * map: ({ resource, action }) => [[`wms:${resource}`, action]]
+     * // material:read  ->  enforce(memberId, domain, 'wms:material', 'read')
+     * ```
+     */
+    readonly map: (requirement: WmsOperationRequirement) => CasbinAction[];
+}
+/**
+ * Builds a {@link WmsAuthChecker} that authorizes WMS operations against
+ * `@rytass/member-base-nestjs-module`'s Casbin setup.
+ *
+ * It reuses everything the host's global `CasbinGuard` already prepared on the
+ * request — the verified `payload`, the `enforcer`, and even the consumer's
+ * (possibly customized) `casbinPermissionChecker`. WMS therefore enforces with
+ * the *exact same* policy engine and rules as the host's own resolvers, with no
+ * member-base import on the WMS side.
+ *
+ * Prerequisite: register `MemberBaseModule` with its global guard enabled
+ * (the default), and expose the request on the GraphQL context as `req`
+ * (Apollo's default).
+ */
+export declare const createMemberBaseWmsAuthChecker: (options: MemberBaseWmsAuthCheckerOptions) => WmsAuthChecker;

package/adapters/member-base.js

@@ -0,0 +1,47 @@
+import { GqlExecutionContext } from '@nestjs/graphql';
+
+const extractRequest = (context) => {
+    const gqlContext = GqlExecutionContext.create(context).getContext();
+    return gqlContext?.req;
+};
+/**
+ * Builds a {@link WmsAuthChecker} that authorizes WMS operations against
+ * `@rytass/member-base-nestjs-module`'s Casbin setup.
+ *
+ * It reuses everything the host's global `CasbinGuard` already prepared on the
+ * request — the verified `payload`, the `enforcer`, and even the consumer's
+ * (possibly customized) `casbinPermissionChecker`. WMS therefore enforces with
+ * the *exact same* policy engine and rules as the host's own resolvers, with no
+ * member-base import on the WMS side.
+ *
+ * Prerequisite: register `MemberBaseModule` with its global guard enabled
+ * (the default), and expose the request on the GraphQL context as `req`
+ * (Apollo's default).
+ */
+const createMemberBaseWmsAuthChecker = (options) => {
+    return async (context, requirement) => {
+        const request = extractRequest(context);
+        // No verified member → unauthenticated. CasbinGuard sets `payload` to
+        // undefined when the token is missing or invalid.
+        if (!request?.payload) {
+            return false;
+        }
+        // The enforcer / checker are injected by CasbinGuard. Their absence means
+        // the host did not enable the global guard — fail closed rather than
+        // silently allowing everything.
+        if (!request.enforcer || !request.casbinPermissionChecker) {
+            return false;
+        }
+        const actions = options.map(requirement);
+        if (actions.length === 0) {
+            return false;
+        }
+        return request.casbinPermissionChecker({
+            enforcer: request.enforcer,
+            payload: request.payload,
+            actions,
+        });
+    };
+};
+
+export { createMemberBaseWmsAuthChecker };

package/docs/README.md

@@ -7,6 +7,7 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 | Document                                       | Description                                                                                       |
 |------------------------------------------------|---------------------------------------------------------------------------------------------------|
 | [Integration Guide](./integration-guide.md)    | Step-by-step instructions for wiring the three packages into a new consumer project (NestJS + Next.js + PostgreSQL). Includes ready-to-paste `_app.tsx`, `app.module.ts`, `next.config.ts`, the 19 Pages Router shell pattern, AuthGuard stub, seed script template, deployment notes, and known issues. |
+| [Authorization](./authorization.md)            | Complete design of the resolver-level authorization protocol (`@WmsOperation` + `WmsAuthGuard` + `authChecker`). Explains the global deny-by-default guard pitfall, execution order, and integration recipes for member-base / Casbin, custom JWT / RBAC, and no-guard setups. Read this if any WMS query/mutation returns *forbidden*. |
 | [API Reference](./api-reference.md)            | Complete export catalog for all three packages — every NestJS module, TypeORM entity, GraphQL resolver, DTO, React component, hook, and utility, organized by role with source paths and usage examples. Mirrors the actual `src/index.ts` barrel exports of `@rytass/wms-module-graphql@0.3.0` and `@rytass/wms-module-{core,react}@0.1.6`. |
 
 ## Quick links
@@ -23,6 +24,8 @@ Reference material for consumers of `@rytass/wms-module-{core,graphql,react}`.
 | Look up a specific export's signature                   | [API Reference](./api-reference.md)                                    |
 | Understand why the lib needs `transpilePackages`        | [Integration Guide section 5.3](./integration-guide.md#53-appsclientnextconfigts) |
 | Replace the `AuthGuard` stub with real auth             | [Integration Guide section 8.4](./integration-guide.md#84-real-auth-integration) |
+| Authorize WMS resolvers with member-base / Casbin / RBAC | [Authorization](./authorization.md)                                   |
+| Fix "every WMS query/mutation is forbidden"             | [Authorization section 1](./authorization.md#1-the-problem)            |
 | Decide between PostgreSQL and SQLite                    | [Integration Guide section 9](./integration-guide.md#9-database-support-matrix) |
 | Build a custom UI on top of the lib's GraphQL operations| [Integration Guide section 7.3](./integration-guide.md#73-graphql-operations--typed-hooks) |
 

package/docs/api-reference.md

@@ -301,17 +301,23 @@ enum ShipInventoryOrderStatus { PENDING, PARTIAL_SHIPPED, SHIPPED, REMOVED }
 **`forRootAsync(options): DynamicModule`** (since 0.3.0)
 ```ts
 static forRootAsync(
-  options: WmsModuleCoreModuleAsyncOptions,
+  options: WmsModuleGraphqlModuleAsyncOptions,
+  // = WmsModuleCoreModuleAsyncOptions & WmsAuthModuleOptions
+  //
   // WMSBaseModuleAsyncOptions（Vault/DB 選項）
   // + WmsModuleCoreModuleOptions:
   //     defaultLoaderSerialId: string  — 庫存作業預設載具序號
   //     defaultLoaderTypeKey: string   — 預設載具類型 key
   //     defaultLocationKey: string     — 預設儲存位置 key
+  // + WmsAuthModuleOptions:
+  //     authChecker?: WmsAuthChecker   — 選填；resolver 授權委派函式（見 Authorization）
 ): DynamicModule
 ```
 
 > **Breaking from 0.2.x**: 0.2.0 took a second `gqlOptions` argument and started Apollo Server internally; 0.3.0 dropped it. Consumers now own `GraphQLModule.forRootAsync(...)` and the GraphQL context factory. Use `createWmsLoaders(loaderService)` inside `context` to provide the WMS DataLoader trio (see below).
 
+> **Authorization (`authChecker`)**: optional. Omit it and the module stays fully permissive. Supply it to authorize every WMS root op against your permission system — see the dedicated [**Authorization**](#authorization) section below and [`docs/authorization.md`](./authorization.md).
+
 ### `LoaderService` (`@Injectable()`, since 0.3.0 publicly exported)
 - 用途: 提供 DataLoader 工廠方法（`batchEntity()`、`batchEntities()`、`batchEntitiesWithPagination()`）。每次呼叫產生新的 DataLoader instance — 須在 GraphQL context factory **per request** 呼叫，**勿** 在 module scope 重用。
 - 來源: `lib/helpers/loader.service.ts`
@@ -390,6 +396,59 @@ material(
 
 ---
 
+## Authorization
+
+Host-neutral, opt-in resolver authorization. Every WMS root `@Query`/`@Mutation` carries `@WmsOperation({ resource, action })`; `WmsAuthGuard` enforces it by delegating to the consumer-supplied `authChecker`. Full design & recipes: [`docs/authorization.md`](./authorization.md).
+
+### Root exports (`@rytass/wms-module-graphql`)
+
+| Export | Kind | Signature / shape |
+|---|---|---|
+| `WmsOperation` | decorator | `(requirement: WmsOperationRequirement) => MethodDecorator` — already applied across the library; add it to any new root op. |
+| `WmsAuthGuard` | `@Injectable()` guard | route-level `CanActivate`; reads the requirement, calls `authChecker`. Auto-registered by `forRootAsync`. |
+| `WmsAuthChecker` | type | `(context: ExecutionContext, requirement: WmsOperationRequirement) => boolean \| Promise<boolean>` |
+| `WmsOperationRequirement` | type | `{ readonly resource: string; readonly action: string }` |
+| `WmsAuthModuleOptions` | type | `{ readonly authChecker?: WmsAuthChecker }` |
+| `WmsModuleGraphqlModuleAsyncOptions` | type | `WmsModuleCoreModuleAsyncOptions & WmsAuthModuleOptions` (the `forRootAsync` arg) |
+| `WMS_AUTH_OPTIONS` | `symbol` | DI token holding the resolved auth options |
+| `WMS_OPERATION_METADATA` | `string` (`'wms:operation'`) | Reflector key carrying the requirement |
+| `HOST_SKIP_METADATA_KEY` | `string` (`'IS_ROUTE_PUBLIC'`) | host-skip metadata key stamped on each op so a global guard defers (default matches member-base) |
+
+### Adapter subpath (`@rytass/wms-module-graphql/adapters/member-base`)
+
+| Export | Kind | Signature / shape |
+|---|---|---|
+| `createMemberBaseWmsAuthChecker` | factory | `(options: MemberBaseWmsAuthCheckerOptions) => WmsAuthChecker` |
+| `MemberBaseWmsAuthCheckerOptions` | type | `{ readonly map: (requirement: WmsOperationRequirement) => CasbinAction[] }` |
+| `CasbinAction` | type | `[string, string]` — a `[subject, action]` tuple |
+
+```ts
+// member-base / Casbin
+import { createMemberBaseWmsAuthChecker } from '@rytass/wms-module-graphql/adapters/member-base';
+
+WmsModuleGraphqlModule.forRootAsync({
+  useFactory: async () => ({}),
+  defaultLoaderSerialId: 'DEFAULT',
+  defaultLoaderTypeKey: 'DEFAULT',
+  defaultLocationKey: 'DEFAULT',
+  authChecker: createMemberBaseWmsAuthChecker({
+    map: ({ resource, action }) => [[`wms:${resource}`, action]],
+  }),
+});
+
+// custom JWT / RBAC
+import type { WmsAuthChecker } from '@rytass/wms-module-graphql';
+
+const authChecker: WmsAuthChecker = (ctx, { resource, action }) => {
+  // read your session off ctx and decide
+  return true;
+};
+```
+
+The adapter imports nothing from member-base — it reads the `payload` / `enforcer` / `casbinPermissionChecker` that `CasbinGuard` attaches to the request at runtime. member-base is therefore **not** a dependency or peer dependency of this package.
+
+---
+
 ## Resolvers（`@Resolver()` decorator class）
 
 以下 Resolver 類別處理 GraphQL `@ResolveField`，解析關聯欄位（防止 N+1）：

package/docs/authorization.md

@@ -0,0 +1,349 @@
+# Authorization
+
+How `@rytass/wms-module-graphql` lets **you** authorize its resolvers with **your**
+permission system — without the library knowing anything about it, and without
+your global auth guard rejecting every WMS operation.
+
+- [1. The problem](#1-the-problem)
+- [2. The design](#2-the-design)
+- [3. Execution order — why it composes](#3-execution-order--why-it-composes)
+- [4. Recipe A — member-base / Casbin](#4-recipe-a--member-base--casbin)
+- [5. Recipe B — your own JWT / RBAC](#5-recipe-b--your-own-jwt--rbac)
+- [6. Recipe C — no global guard / fully open](#6-recipe-c--no-global-guard--fully-open)
+- [7. The single coupling point](#7-the-single-coupling-point)
+- [8. Public API](#8-public-api)
+- [9. FAQ & gotchas](#9-faq--gotchas)
+
+---
+
+## 1. The problem
+
+The library exposes ~66 root `@Query` / `@Mutation` operations. Like any
+publishable NestJS GraphQL module, it cannot know how *your* application
+authorizes requests — RBAC? ABAC? Casbin? JWT scopes? a custom session table?
+So historically its resolvers were **bare** (`@Query()` with no guard metadata).
+
+That collides badly with a **globally registered, deny-by-default guard**. The
+canonical example is the `CasbinGuard` that `@rytass/member-base-nestjs-module`
+registers as `APP_GUARD`:
+
+```
+Host App
+  APP_GUARD = CasbinGuard          <- one net over EVERY resolver in the schema
+        |
+        v
+  +------------------------------+
+  | compiled GraphQL schema      |
+  |  - your resolvers            |  carry @AllowActions -> authorized OK
+  |  - WMS resolvers (bare)      |  no metadata -> guard returns false -> ALL denied
+  +------------------------------+
+```
+
+`CasbinGuard` is white-list: a handler with no `@AllowActions` / `@Authenticated`
+/ `@IsPublic` metadata is **rejected**. WMS resolvers had none, so every WMS
+query and mutation came back *forbidden*. You could not fix it from the consumer
+side either — you do not own the WMS resolver classes, so you cannot decorate
+them.
+
+**Conclusion:** the library itself must participate in authorization, while
+staying ignorant of which auth system you use.
+
+---
+
+## 2. The design
+
+A host-neutral, opt-in authorization protocol with three moving parts, all
+shipped by the library:
+
+| Part | What it is | Who supplies it |
+|------|------------|-----------------|
+| `@WmsOperation({ resource, action })` | Method decorator on every WMS root op. Declares a **neutral** permission requirement (just two strings) and wires the guard. | Library (already applied) |
+| `WmsAuthGuard` | Route-level guard (NOT global) that reads the requirement and delegates the decision. | Library |
+| `authChecker` | Your function `(ctx, { resource, action }) => boolean`. Maps WMS's neutral requirement onto your real permission system. | **You**, via `forRootAsync` |
+
+```
+WMS resolver
+  |
+  +- @WmsOperation({ resource: 'material', action: 'read' })
+  |     |
+  |     +- stamps neutral metadata  ............ read by WmsAuthGuard
+  |     +- stamps a host-skip marker ........... tells your global guard to defer
+  |     +- @UseGuards(WmsAuthGuard) ............ the guard that actually enforces
+  |
+  v
+WmsAuthGuard.canActivate(ctx)
+  |
+  +- reads { resource, action } from the handler
+  +- calls YOUR authChecker(ctx, { resource, action })
+        |
+        v
+   true -> resolve   /   false -> ForbiddenError
+```
+
+Key properties:
+
+- **The library never imports your auth system.** It only knows two strings.
+- **`authChecker` is optional.** Omit it and the module stays fully permissive
+  (handy for local dev / demos) — identical to the pre-auth releases.
+- **`resource` / `action` are internal metadata**, not part of the GraphQL
+  schema. Refining them later is *not* a breaking change for GraphQL consumers.
+- The host-skip marker is what lets WMS coexist with your global guard — see §3.
+
+---
+
+## 3. Execution order — why it composes
+
+NestJS runs guards in the order **global -> controller -> route**. So a global
+`APP_GUARD` (your `CasbinGuard`) runs *before* WMS's route-level `WmsAuthGuard`.
+That is exactly why `@WmsOperation` stamps a host-skip marker: it makes the
+global guard *defer* on WMS operations so it never blanket-rejects them.
+
+```
+request
+  |
+  v  [1] APP_GUARD = CasbinGuard (global, runs first)
+  |        - verifies token, attaches payload/enforcer to the request
+  |        - sees host-skip marker (IS_ROUTE_PUBLIC) -> returns true (defers)
+  |
+  v  [2] @UseGuards(WmsAuthGuard) (route-level, runs next)
+  |        - reads { resource, action }
+  |        - calls your authChecker -> real allow/deny decision
+  |
+  v  resolver executes
+```
+
+With member-base specifically there is a bonus: before `CasbinGuard` defers on
+the skip marker, it has *already* attached the verified `payload`, the Casbin
+`enforcer`, and your `casbinPermissionChecker` to the request. The member-base
+adapter (§4) reuses those — so WMS enforces with the **exact same** policy
+engine and rules as your own resolvers.
+
+> Your global guard configuration does **not** change. You do not whitelist WMS
+> routes, you do not enumerate operations, you do not weaken your default-deny
+> posture. WMS makes itself transparent to the global guard and self-enforces.
+
+---
+
+## 4. Recipe A — member-base / Casbin
+
+The common case: you use `@rytass/member-base-nestjs-module` with its global
+`CasbinGuard`. Use the ready-made adapter from the dedicated subpath.
+
+```ts
+// app.module.ts
+import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+import { createMemberBaseWmsAuthChecker } from '@rytass/wms-module-graphql/adapters/member-base';
+
+@Module({
+  imports: [
+    // ...MemberBaseModule.forRoot({ ... }) with its global guard enabled (default)...
+    WmsModuleGraphqlModule.forRootAsync({
+      // existing core options:
+      useFactory: async () => ({}),
+      defaultLoaderSerialId: 'DEFAULT',
+      defaultLoaderTypeKey: 'DEFAULT',
+      defaultLocationKey: 'DEFAULT',
+
+      // authorization:
+      authChecker: createMemberBaseWmsAuthChecker({
+        // Map WMS resource/action onto YOUR Casbin [subject, action] tuples.
+        // This is the one place your permission naming convention lives.
+        // Return several tuples to mean "allow if ANY passes" (OR semantics).
+        map: ({ resource, action }) => [[`wms:${resource}`, action]],
+        //   material + read -> enforce(memberId, domain, 'wms:material', 'read')
+      }),
+    }),
+    // ...your own GraphQLModule.forRootAsync (must expose `req` on context)...
+  ],
+})
+export class AppModule {}
+```
+
+What the adapter does, step by step:
+
+1. Pulls the request off the GraphQL `ExecutionContext`
+   (`GqlExecutionContext.create(ctx).getContext().req` — member-base's own
+   convention).
+2. Reads `request.payload` (the JWT member, attached by `CasbinGuard`). Missing
+   payload -> **deny** (unauthenticated).
+3. Reads `request.enforcer` and `request.casbinPermissionChecker` (also attached
+   by `CasbinGuard`). Missing -> **deny** (fail closed: the global guard was not
+   actually enabled).
+4. Runs `your map({ resource, action })` to get the Casbin tuples.
+5. Calls the **consumer's own** `casbinPermissionChecker({ enforcer, payload,
+   actions })` and returns its verdict.
+
+The adapter imports **nothing** from member-base — it relies only on the runtime
+contract `CasbinGuard` already established on the request. So member-base is not
+even a dependency of `@rytass/wms-module-graphql`.
+
+**Prerequisites**
+
+- Keep member-base's global guard enabled (`enableGlobalGuard: true`, the
+  default).
+- Your `GraphQLModule` context must expose the request as `req` (Apollo's
+  default): `context: ({ req }) => ({ ...createWmsLoaders(loaderService), req })`.
+
+**Permission grants.** Make sure your Casbin policy grants the mapped subjects.
+With the example `map` above, a warehouse operator role might be granted
+`wms:material:read`, `wms:receive-inventory-order:create`, etc. The full list of
+`resource` values mirrors the WMS domains (`material`, `loader`, `stock`,
+`location`, `unit`, `batch`, `warehouse-map`, `transfer-order`,
+`receive-inventory-order`, `ship-inventory-order`, `allocate-inventory-order`,
+`hold-inventory-order`, `reclassify-inventory-order`, `transfer-customer-order`,
+`transfer-vendor-order`, `sale-order`, `scrape-order`,
+`quality-inspection-order`). `action` is `read` for queries, and the leading
+verb (`create` / `update` / `delete` / `ship` / `hold` / `allocate` / `split` /
+`merge` / `transfer` / ...) for mutations.
+
+---
+
+## 5. Recipe B — your own JWT / RBAC
+
+`authChecker` is a plain function — you do not need Casbin or member-base. Read
+whatever you need off the `ExecutionContext` and decide.
+
+```ts
+import { GqlExecutionContext } from '@nestjs/graphql';
+import type { WmsAuthChecker } from '@rytass/wms-module-graphql';
+
+const myWmsAuthChecker: WmsAuthChecker = (ctx, { resource, action }) => {
+  const { req } = GqlExecutionContext.create(ctx).getContext<{ req: { user?: { scopes: string[] } } }>();
+  const user = req.user;
+
+  if (!user) return false;                                  // unauthenticated -> deny
+
+  // your own convention; e.g. scopes like "wms:material:read" or "wms:*"
+  return user.scopes.includes('wms:*')
+    || user.scopes.includes(`wms:${resource}:${action}`)
+    || user.scopes.includes(`wms:${resource}:*`);
+};
+
+WmsModuleGraphqlModule.forRootAsync({
+  useFactory: async () => ({}),
+  defaultLoaderSerialId: 'DEFAULT',
+  defaultLoaderTypeKey: 'DEFAULT',
+  defaultLocationKey: 'DEFAULT',
+  authChecker: myWmsAuthChecker,
+});
+```
+
+`authChecker` may be sync or async (return `Promise<boolean>`). Throwing also
+works — the exception propagates exactly like any guard rejection (use a
+`ForbiddenException` if you want a clean 403-style GraphQL error).
+
+If you *also* run a global deny-by-default guard that is **not** member-base, you
+must make it skip WMS routes too — see §7 to change the host-skip key.
+
+---
+
+## 6. Recipe C — no global guard / fully open
+
+- **No `authChecker`.** The module is permissive: `WmsAuthGuard` lets every
+  operation through. The host-skip marker is inert. Good for local dev, internal
+  tooling, or demos.
+
+  ```ts
+  WmsModuleGraphqlModule.forRootAsync({
+    useFactory: async () => ({}),
+    defaultLoaderSerialId: 'DEFAULT',
+    defaultLoaderTypeKey: 'DEFAULT',
+    defaultLocationKey: 'DEFAULT',
+    // no authChecker -> open
+  });
+  ```
+
+- **You guard your own resolvers explicitly** (`@UseGuards(...)` per resolver
+  instead of a global `APP_GUARD`). Then there is no net over WMS at all; the
+  skip marker does nothing and WMS still self-enforces through your
+  `authChecker` if you supply one.
+
+---
+
+## 7. The single coupling point
+
+`@WmsOperation` stamps a host-skip metadata key so your global guard defers. A
+global guard reads its skip key *statically* (at decoration time), so the key
+must be a fixed value baked into the decorator. The default matches
+member-base's:
+
+```ts
+// libs/graphql/src/lib/auth/host-skip.constant.ts
+export const HOST_SKIP_METADATA_KEY = 'IS_ROUTE_PUBLIC';
+```
+
+This is the **only** place WMS assumes anything about a specific host guard. If
+your global guard uses a different "public / skip" metadata key, change this one
+constant (when building from source) — nothing else moves. If you do not run a
+global guard, it is irrelevant.
+
+---
+
+## 8. Public API
+
+Exported from the package root (`@rytass/wms-module-graphql`):
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `WmsOperation(requirement)` | decorator | Annotate a WMS root op (already applied across the library). |
+| `WmsAuthGuard` | class | Route-level guard that delegates to `authChecker`. |
+| `WmsAuthChecker` | type | `(ctx: ExecutionContext, req: WmsOperationRequirement) => boolean \| Promise<boolean>` |
+| `WmsOperationRequirement` | type | `{ readonly resource: string; readonly action: string }` |
+| `WmsAuthModuleOptions` | type | `{ readonly authChecker?: WmsAuthChecker }` |
+| `WmsModuleGraphqlModuleAsyncOptions` | type | Core async options **+** `WmsAuthModuleOptions`. |
+| `WMS_AUTH_OPTIONS` | symbol | DI token holding the resolved auth options. |
+| `WMS_OPERATION_METADATA` | string | Reflector key carrying the requirement. |
+| `HOST_SKIP_METADATA_KEY` | string | The host-skip metadata key (default `'IS_ROUTE_PUBLIC'`). |
+
+Exported from the adapter subpath (`@rytass/wms-module-graphql/adapters/member-base`):
+
+| Export | Kind | Purpose |
+|--------|------|---------|
+| `createMemberBaseWmsAuthChecker(options)` | factory | Builds a `WmsAuthChecker` for member-base / Casbin. |
+| `MemberBaseWmsAuthCheckerOptions` | type | `{ readonly map: (req: WmsOperationRequirement) => CasbinAction[] }` |
+| `CasbinAction` | type | `[string, string]` — a `[subject, action]` tuple. |
+
+`forRootAsync` accepts the optional `authChecker` on its single options object:
+
+```ts
+static forRootAsync(options: WmsModuleGraphqlModuleAsyncOptions): DynamicModule;
+```
+
+---
+
+## 9. FAQ & gotchas
+
+**"Every WMS query/mutation is forbidden after I added member-base."**
+Your global `CasbinGuard` is rejecting bare resolvers. Upgrade to a WMS version
+that ships `@WmsOperation` (this protocol) and wire an `authChecker` per §4. You
+do not need to touch the global guard.
+
+**Does the GraphQL context need anything special?**
+Yes — expose the request as `req` on the context (Apollo's default). Both the
+member-base adapter and most custom checkers read `GqlExecutionContext.create(ctx).getContext().req`.
+
+**Is member-base a dependency now?**
+No. The adapter reads runtime fields the host's guard attaches to the request;
+it imports nothing from member-base. member-base is not in this package's
+`dependencies` or `peerDependencies`.
+
+**What about `@ResolveField` resolvers?**
+They are intentionally *not* annotated. A field resolver is only ever reached
+through a root `@Query`/`@Mutation` that already passed `WmsAuthGuard`, so
+authorizing the root op authorizes the whole selection. `WmsAuthGuard` returns
+`true` for any handler without a requirement.
+
+**Fail-open or fail-closed?**
+The library is permissive only when *you* opt out (no `authChecker`). When an
+`authChecker` is configured, missing identity / missing enforcer -> **deny**. The
+member-base adapter fails closed.
+
+**Can I change `resource`/`action` strings?**
+Yes, freely — they are internal metadata, never exposed in the GraphQL schema.
+Changing them only affects your `authChecker` / `map`, never your GraphQL
+clients.
+
+---
+
+See also: [Integration Guide §8.5](./integration-guide.md#85-backend-authorization-resolver-level)
+· [API Reference](./api-reference.md#rytasswms-module-graphql)

package/docs/integration-guide.md

@@ -741,7 +741,7 @@ The full list of generated `Document` constants and their types is in
 
 ## 8. Authentication / authorization
 
-The lib **does not** ship an auth system. The page components assume they render in an authenticated context — they call queries on mount without checking session state.
+The lib ships **no frontend auth** — the page components assume they render in an authenticated context and call queries on mount without checking session state. On the **backend**, `@rytass/wms-module-graphql` ships an *opt-in, host-neutral authorization protocol* you wire to your own permission system (member-base / Casbin / JWT / anything). See [§8.5 Backend authorization](#85-backend-authorization-resolver-level).
 
 ### 8.1 Stub for demos
 
@@ -829,7 +829,43 @@ Replace the `AuthGuard` stub with your own logic that:
 2. Provides member identity to GraphQL via the Apollo client's `context` link.
 3. Handles 401 responses (logout / redirect).
 
-The lib's resolvers do not enforce auth themselves. If you need RBAC, layer your own guard/decorator on top of the resolvers or apply NestJS-level guards globally in `app.module.ts`.
+### 8.5 Backend authorization (resolver-level)
+
+> 📖 This is the condensed version. The full design — execution order, member-base / custom-JWT / no-guard recipes, the single coupling point, the exported API, and a troubleshooting FAQ — lives in [**`docs/authorization.md`**](./authorization.md).
+
+Every WMS root `@Query` / `@Mutation` is annotated with `@WmsOperation({ resource, action })` — a host-neutral permission requirement. The library enforces it through its own route-level `WmsAuthGuard`, which delegates the actual allow/deny decision to an `authChecker` **you** supply at module registration. The library never imports your auth system; you map WMS's `resource`/`action` onto whatever your system understands.
+
+> ⚠️ **The global-guard pitfall.** A deny-by-default global guard — e.g. the `CasbinGuard` that `@rytass/member-base-nestjs-module` registers as `APP_GUARD` — blankets *every* resolver in the compiled schema, including WMS's. Because WMS resolvers carry no host-specific permission metadata, such a guard rejects them all ("every WMS query/mutation is forbidden"). WMS solves this by stamping each operation with a host-skip marker (default: member-base's `IS_ROUTE_PUBLIC`) so the global guard defers, while `WmsAuthGuard` does the real enforcement. **You do not need to touch your global guard.**
+
+#### Wire it up (member-base / Casbin)
+
+```ts
+// app.module.ts
+import { WmsModuleGraphqlModule } from '@rytass/wms-module-graphql';
+import { createMemberBaseWmsAuthChecker } from '@rytass/wms-module-graphql/adapters/member-base';
+
+WmsModuleGraphqlModule.forRootAsync({
+  // ...existing core options (defaultLoaderSerialId, useFactory, etc.)...
+  authChecker: createMemberBaseWmsAuthChecker({
+    // Map WMS resource/action onto your Casbin [subject, action] tuples.
+    // Return multiple tuples to mean "allow if ANY passes" (OR semantics).
+    map: ({ resource, action }) => [[`wms:${resource}`, action]],
+    //  e.g. material:read -> enforce(memberId, domain, 'wms:material', 'read')
+  }),
+});
+```
+
+The member-base adapter reuses everything `CasbinGuard` already prepared on the request (the verified `payload`, the `enforcer`, and your possibly-customized `casbinPermissionChecker`), so WMS enforces with the **exact same** policy engine as your own resolvers — with zero member-base import on the WMS side. Requirement: keep member-base's global guard enabled (default) and expose the request on the GraphQL context as `req` (Apollo's default).
+
+#### Other auth systems
+
+`authChecker` is a plain function — `(execContext, { resource, action }) => boolean | Promise<boolean>`. For JWT/RBAC without Casbin, read your session off the `ExecutionContext` and decide there. If your global guard uses a different "public/skip" metadata key than member-base's `IS_ROUTE_PUBLIC`, change the single `HOST_SKIP_METADATA_KEY` constant in `libs/graphql/src/lib/auth/host-skip.constant.ts`.
+
+#### No global guard at all
+
+If you omit `authChecker`, the module stays fully permissive (handy for local dev). If you protect your own resolvers with explicit `@UseGuards(...)` instead of a global `APP_GUARD`, the host-skip marker is simply inert and WMS still self-enforces through `authChecker`.
+
+The WMS `resource`/`action` strings are **internal metadata only** — they are not part of the GraphQL schema, so refining them later is not a breaking change for GraphQL consumers (it only affects your `map`).
 
 ---