@xignet/payload 0.1.0-beta.1 → 0.1.0-beta.3

package/README.md

@@ -4,6 +4,49 @@ Xignet resource authorization for Payload v3. The adapter uses the official MCP
 
 The current test baseline is Payload and `@payloadcms/plugin-mcp` **3.93.0**. No broad v3 or v4 compatibility is declared. The upstream plugin currently resolves `mcp-handler` 1.1.0 with SDK 1.30.0 despite that handler declaring SDK 1.26.0 as its exact peer; the workspace explicitly acknowledges this one tested combination using pnpm.peerDependencyRules.allowedVersions. Strict-peer pnpm consumers must apply the same narrow rule. This does not permit any other SDK version. Do not infer compatibility with other versions from these fixture results.
 
+## Standard plugin: passwordless managed users
+
+```ts
+import { xignetPlugin } from '@xignet/payload';
+import { createDirectoryClient } from '@xignet/client/directory';
+
+const xignet = xignetPlugin({
+  resource: 'https://cms.example.com/api/mcp',
+  admissionScopes: ['cms:access'],
+  userCollection: 'users',
+  directory: createDirectoryClient({
+    clientId: process.env.XIGNET_DIRECTORY_CLIENT_ID!,
+    clientSecret: process.env.XIGNET_DIRECTORY_CLIENT_SECRET!,
+  }),
+  users: {
+    canManageBindings: (req) => req.user?.collection === 'users' && req.user.role === 'admin',
+    allowUser: (user) => ['admin', 'editor'].includes(user.role),
+    revokeOnFields: ['role'],
+  },
+  mcp: { enabled: true, collections: { bulletins: { find: { scopes: ['cms:read'] } } } },
+  login: { /* dedicated web client and session options shown below */ },
+});
+
+// Standard Payload plugin: buildConfig({ plugins: [xignet] }).
+// The same xignet object works with createXignetRouteHandlers.
+```
+
+The shared provider currently uses `https://signet.marxbio.tech`, the issuer advertised by the production Xignet AS. Projects do not repeat issuer/JWKS settings. A paired `provider: { issuer, jwksUri }` override supports tests or self-hosted Xignet; user data and request headers cannot select the trusted provider.
+
+The plugin owns read-only `xignetIssuer`/`xignetSubject`, `xignetEnabled`, a compound unique identity index, a virtual confirmation field, the Directory lookup endpoint and revocation hooks. An administrator enters a company email, queries Xignet, confirms the identity and chooses a local role. The server resolves the email again on save and checks a five-minute signed preview bound to the acting administrator. A changed result requires a new preview; browser-supplied identity values cannot replace the Directory result. An existing binding cannot transfer to another issuer/subject. Email changes for the same subject, enablement, roles and deletion revoke existing sessions.
+
+`POST /api/<userCollection>/xignet/resolve` requires an authenticated binding manager and an Origin matching the configured resource origin. This uses `@xignet/client/directory` server-side credentials, not the admin's CMS access token. SDK clients must never be exposed to browser code. Omitting `directory` disables provisioning and lookup, while allowing existing users to authenticate. Generate the Payload import map for both `@xignet/payload/components` and `@xignet/payload/client`; the latter requires the matching `@payloadcms/ui` peer.
+
+At browser login the verified ID token must include `email_verified: true` and an email matching the bound local account. MCP continues to resolve only the verified `(issuer, sub)` and local eligibility; it does not expect an ID token or email claim. Directory resolves at provisioning time, not on every session/MCP request. This is not continuous synchronization or instant upstream revocation.
+
+Managed users use Payload's supported `disableLocalStrategy: { enableFields: true }`, keeping auth/session fields while disabling local password operations. New records contain no password hash/salt. A custom `xignet-session` strategy accepts only the signed Payload SSO cookie/JWT with a valid native SID, private metadata, current local binding and absolute deadline. The session strategy does not accept Xignet access tokens; optional REST and MCP adapters validate those separately. API keys require the explicit transitional `legacyAPIKeys` option. Unmanaged custom strategies and automatic Admin login are rejected for this mode. Existing password hashes are retained in additive migrations but cannot authenticate.
+
+Create the first admin through a trusted deployment/seed script using `payload.create` with the approved company email and explicit local role, without a password. Payload's normal public `first-register` password flow is disabled in this mode. An unauthenticated trusted server-side Local API create still resolves Directory but does not need an interactive confirmation. Local API calls carrying a user retain permission and preview checks. After Xignet login, that admin creates subsequent users in the Admin Panel. Generate and review database migrations in each project before enabling the plugin; it never pushes schema at runtime.
+
+## Low-level adapter: custom resolver and mixed authentication
+
+The existing `/v3` API below remains available when a project owns its binding storage or intentionally keeps native password/API-key authentication. Those choices are independent of the standard plugin's Xignet-only policy.
+
 ```ts
 import { createXignetPayload } from '@xignet/payload/v3';
 
@@ -37,7 +80,7 @@ export const GET = handlers.metadata;
 
 The example's `resolveExistingLocalUser` belongs to the project, not this package. A successful resolver must return a real Payload user with an ID and the configured auth collection discriminator. Resolver failures propagate; they do not become an unbound-user response.
 
-For a resource at `/api/mcp`, mount metadata at `/.well-known/oauth-protected-resource/api/mcp`. The resource origin must match configured `serverURL`, and its path must match the Payload API route plus `/mcp`. Trust settings are fixed configuration, never derived from request Host headers or token claims. Only the MCP routes accept Xignet Bearer; no global authentication strategy or cookie/API-key fallback is installed.
+For a resource at `/api/mcp`, mount metadata at `/.well-known/oauth-protected-resource/api/mcp`. The resource origin must match configured `serverURL`, and its path must match the Payload API route plus `/mcp`. Trust settings are fixed configuration, never derived from request Host headers or token claims. MCP validates its own Bearer tokens without cookie/API-key fallback. Optional REST support installs a separate authentication strategy and requires the HTTP boundary described below.
 
 MCP operations require explicit scopes. Unsupported/unlisted operations, entities and experimental tools are closed. Deletion is not supported in this prerelease. The API-key collection added by the official plugin is hidden and denied to API callers; its schema is retained even with MCP disabled, so projects must include it in migrations. `mcp.enabled: false` removes the MCP routes and returns 404 metadata.
 
@@ -90,7 +133,7 @@ const handlers = createXignetRouteHandlers(xignet, {
 // Export GET = handlers.metadata at the resource's well-known path.
 ```
 
-Provide the app's actual Payload instance lazily. SSO-enabled route factories require this provider. SSO requires the native local auth strategy and `useSessions`; MCP-only consumers may use other auth models. The adapter invokes beforeLogin/afterLogin hooks and composes existing refresh hooks. These HTTP login routes return redirects or generic error responses with no token body.
+Provide the app's actual Payload instance lazily. SSO-enabled route factories require this provider. The low-level adapter's default mixed mode uses native local auth with `useSessions`; the standard plugin uses the dedicated Xignet-only strategy described above. MCP-only low-level consumers may use other auth models. The adapter invokes beforeLogin/afterLogin hooks and composes existing refresh hooks. These HTTP login routes return redirects or generic error responses with no token body.
 
 Next standalone can expose its internal hostname and port in `Request.url`. The Next callback handler uses the trusted Payload `serverURL` as its public origin while retaining the incoming path and query for OIDC validation. Configure `serverURL` to the canonical CMS origin; Host and forwarded-host headers never select that origin. Direct `integration.callback` callers must supply the canonical public request URL themselves.
 
@@ -106,7 +149,7 @@ Login failure rolls back SID/metadata when the adapter supports transactions, or
 
 The adapter logs structured MCP operation/transport outcomes with a generated request ID and verified issuer/subject/client/local user, without content bodies or credentials. SSO refusals, service failures and revocation have structured events; unexpected exception messages are not copied into HTTP error responses or logs.
 
-Publish core first, then payload under `payload-vX.Y.Z` using `payload-publish.yml`. Configure npm trusted publishing for both new package names before tagging. Only the exact peer baseline above is supported in this prerelease; Payload's Node requirement is `^22.23.4 || >=24.22.1`; a server runtime is required. Adapter CI verifies Node 22.23.4, 24 and 26.13.1. Core independently supports Node 22.22.0+. The package's Next helpers use standard Request/Response and have no Next.js runtime import.
+Ensure the required core version is available, publish and verify the new client version through `client-publish.yml`, then publish payload under `payload-vX.Y.Z` using `payload-publish.yml`. Configure npm trusted publishing for both new package names before tagging. Only the exact peer baseline above is supported in this prerelease; Payload's Node requirement is `^22.23.4 || >=24.22.1`; a server runtime is required. Adapter CI verifies Node 22.23.4, 24 and 26.13.1. Core independently supports Node 22.22.0+. The package's Next helpers use standard Request/Response and have no Next.js runtime import.
 
 RPC audit events use the server-generated request ID, principal, allowlisted method/tool target and outcome (success, denied, failed, partial_failure or unobserved). They never include tool arguments, response content, access tokens or exception messages. Inspection retains at most 64 KiB per message. Response bytes are forwarded as the consumer reads them, with terminal audit on EOF, error or cancellation; an open stream does not block delivery. An oversized or unreadable request is recorded as unobserved. Official tool response hooks also report execution failures and partial bulk results, even when the transport returns HTTP 200.
 
@@ -117,3 +160,30 @@ For staged rollout, configure the final collection/global policies once and set
 ## Reusing the adapter
 
 Each CMS supplies its own canonical resource/serverURL, web client, secrets, auth collection, local resolver and collection/global policies. Keep project binding and role rules in that resolver and call `revokeUserSessions` from local lifecycle hooks; mount the shared Next handlers rather than copying the OIDC flow. Tests cover a second CMS profile with a `members` auth collection, separate origin/client/admission scope, native login, refresh and revocation. This fixture verifies configurable reuse; it is not a claim that a second production project has been deployed.
+
+Directory audit records use generated `x-request-id` correlation IDs, local actor/user IDs and fixed operation/outcome/reason fields. Identity values, preview proofs and credentials are not logged. Downstream deployments must preserve the correlation header when forwarding to Directory.
+
+### REST access tokens and API-key migration
+
+REST is opt-in and shares the CMS `resource` audience with MCP, normally `https://cms.example.com/api/mcp`. Directory has its own audience. Configure `rest.enabled`, `admissionScopes`, explicit `collections` / `globals` operation scopes, and optional exact custom `endpoints`. REST and MCP each enforce their own route, scope and local access policies. Only document GET, collection POST, document PATCH and global GET/POST are supported by the REST adapter. Delete, bulk update, auth, versions and GraphQL routes are denied for REST Bearer tokens.
+
+```ts
+const integration = xignetPlugin({
+  // Existing provider, users, MCP and login configuration...
+  legacyAPIKeys: true, // temporary migration bridge; default is false
+  rest: {
+    enabled: true,
+    admissionScopes: ['cms:access'],
+    collections: {
+      pages: { read: ['cms:read'], create: ['cms:write', 'cms:publish'], update: ['cms:write', 'cms:publish'] },
+    },
+    services: [{ subject: 'service:cms-sync', clientId: 'service:cms-sync' }],
+  },
+})
+```
+
+**Wrap every Payload REST HTTP method** with `integration.rest(request, payload, () => originalHandler(request, context))`. This boundary is required: Payload catches strategy exceptions and otherwise may continue as anonymous. The wrapper rejects an invalid Bearer token before dispatch, independently of any cookie. It carries the verified principal through the request's async context, so authentication cannot silently fall back after a second lookup. MCP keeps its existing endpoint validation. Browser cookie requests and transitional API-key requests retain normal Payload behavior. Other custom HTTP/GraphQL entry points must not reuse REST credentials.
+
+Human subjects resolve through the managed local binding and eligibility policy on every request. Services must have the reserved `service:` subject equal to `client_id` and match the local `rest.services` allowlist. Their principal has collection `xignet-services` and no human role, password or session; this is an in-memory principal, not a new database collection. Existing collection/global access control is preserved. Where appropriate, explicitly allow `isXignetService(req)` in the application's **content** access policy; the adapter still caps access to configured operation scopes. Never add this exception to user management or admin access. Field access rules also remain in force.
+
+Keep `legacyAPIKeys: true` only while existing consumers migrate. It does not re-enable passwords. Deploy REST validation first, register environment-specific machine clients for the shared CMS audience and least required scopes, migrate consumers, verify their reads/writes/uploads, then set `legacyAPIKeys: false`. No automatic token-to-API-key fallback exists. Machine authorization revocation at the AS is bounded by the access token's lifetime; removing the local service allowlist entry takes effect with the new configuration. No remote introspection is performed.

package/dist/client.d.ts

@@ -0,0 +1,9 @@
+/** Only public collection metadata crosses the client-component boundary. */
+export declare function XignetDirectoryField({ path, collection, }: {
+    path: string;
+    collection: string;
+}): import("react").DetailedReactHTMLElement<{
+    style: {
+        marginBottom: string;
+    };
+}, HTMLElement>;

package/dist/client.js

@@ -0,0 +1,57 @@
+'use client';
+import { createElement, useState } from 'react';
+import { useConfig, useField } from '@payloadcms/ui';
+import { directoryMessages } from './directory-messages.js';
+/** Only public collection metadata crosses the client-component boundary. */
+export function XignetDirectoryField({ path, collection, }) {
+    const { config } = useConfig();
+    const email = useField({ path: 'email' });
+    const confirmation = useField({ path });
+    const [preview, setPreview] = useState();
+    const [message, setMessage] = useState('');
+    const [busy, setBusy] = useState(false);
+    const current = typeof email.value === 'string' ? email.value.trim().toLowerCase() : '';
+    async function lookup() {
+        setBusy(true);
+        setMessage('');
+        setPreview(undefined);
+        confirmation.setValue('');
+        try {
+            const response = await fetch(`${config.routes.api}/${encodeURIComponent(collection)}/xignet/resolve`, {
+                method: 'POST',
+                credentials: 'same-origin',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify({ email: current }),
+            });
+            if (!response.ok) {
+                const error = (await response.json().catch(() => null));
+                const code = error?.error;
+                setMessage(typeof code === 'string' && Object.hasOwn(directoryMessages, code)
+                    ? directoryMessages[code]
+                    : response.status === 403
+                        ? '沒有身分查詢權限。'
+                        : response.status === 400
+                            ? directoryMessages.invalid_email
+                            : directoryMessages.unavailable);
+                return;
+            }
+            const result = (await response.json());
+            setPreview(result.identity);
+            confirmation.setValue(result.confirmation);
+        }
+        catch {
+            setMessage('身分查詢暫時無法使用，請稍後再試。');
+        }
+        finally {
+            setBusy(false);
+        }
+    }
+    return createElement('div', { style: { marginBottom: '1.5rem' } }, createElement('button', {
+        type: 'button',
+        disabled: busy || !current,
+        onClick: lookup,
+        className: 'btn btn--style-secondary',
+    }, busy ? '查詢中…' : '查詢 Xignet 身分'), preview && preview.email === current
+        ? createElement('p', { role: 'status' }, `公司信箱：${preview.email}｜Xignet sub：${preview.sub}。請確認身分後儲存。`)
+        : createElement('p', null, '新增用戶或變更 email 時，請先查詢並確認公司身分。'), message ? createElement('p', { role: 'alert' }, message) : null);
+}

package/dist/components.d.ts

@@ -0,0 +1,10 @@
+/** Server component; configuration contains only display data, never secrets. */
+export declare function XignetLogin({ enabled, loginPath, label, }: {
+    enabled: boolean;
+    loginPath: string;
+    label: string;
+}): import("react").DetailedReactHTMLElement<import("react").HTMLAttributes<HTMLElement>, HTMLElement> | import("react").DetailedReactHTMLElement<{
+    style: {
+        marginBottom: string;
+    };
+}, HTMLElement>;

package/dist/components.js

@@ -0,0 +1,7 @@
+import { createElement } from 'react';
+/** Server component; configuration contains only display data, never secrets. */
+export function XignetLogin({ enabled, loginPath, label, }) {
+    return enabled
+        ? createElement('div', { style: { marginBottom: '1.5rem' } }, createElement('a', { className: 'btn btn--style-primary', href: loginPath }, label))
+        : createElement('p', null, 'Xignet sign-in is not enabled.');
+}

package/dist/directory-binding.d.ts

@@ -0,0 +1,12 @@
+import { type Endpoint, type PayloadRequest } from 'payload';
+import { type DirectoryClient, type DirectoryIdentity } from '@xignet/client/directory';
+export declare function directoryBindings({ directory, issuer, collection, origin, canManage, }: {
+    directory?: DirectoryClient;
+    issuer: string;
+    collection: string;
+    origin: string;
+    canManage(req: PayloadRequest): boolean | Promise<boolean>;
+}): {
+    endpoint: Endpoint;
+    verify: (req: PayloadRequest, email: string, confirmation: unknown) => Promise<DirectoryIdentity>;
+};

package/dist/directory-binding.js

@@ -0,0 +1,135 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { jwtVerify, SignJWT } from 'jose';
+import { APIError } from 'payload';
+import { canonicalEmail, DirectoryError, } from '@xignet/client/directory';
+import { directoryMessages as messages } from './directory-messages.js';
+export function directoryBindings({ directory, issuer, collection, origin, canManage, }) {
+    const key = (req) => createHash('sha256')
+        .update(`xignet-directory-confirmation:${req.payload.secret}`)
+        .digest();
+    async function resolve(req, email, operation) {
+        const requestId = randomUUID();
+        req.context.xignetDirectoryRequestId = requestId;
+        const audit = {
+            event: 'xignet_directory_lookup',
+            requestId,
+            operation,
+            actorId: req.user?.id ?? 'trusted-local',
+        };
+        try {
+            if (!directory)
+                throw new DirectoryError('unavailable');
+            const identity = await directory.resolve(canonicalEmail(email), {
+                requestId,
+            });
+            if (identity.issuer !== issuer ||
+                identity.email !== canonicalEmail(email) ||
+                !identity.sub ||
+                identity.sub.startsWith('service:'))
+                throw new DirectoryError('invalid_response');
+            req.payload.logger.info({ ...audit, outcome: 'success' });
+            return identity;
+        }
+        catch (error) {
+            const code = error instanceof DirectoryError && Object.hasOwn(messages, error.code)
+                ? error.code
+                : 'unavailable';
+            req.payload.logger.warn({ ...audit, outcome: 'denied', reason: code });
+            throw new APIError(messages[code], code === 'invalid_email'
+                ? 400
+                : code === 'not_found'
+                    ? 404
+                    : code === 'rate_limited'
+                        ? 429
+                        : 503, { code }, true);
+        }
+    }
+    const endpoint = {
+        path: '/xignet/resolve',
+        method: 'post',
+        handler: async (req) => {
+            if (!req.user || !(await canManage(req)))
+                throw new APIError('Forbidden', 403);
+            if (req.headers.get('origin') !== origin)
+                throw new APIError('Forbidden origin', 403);
+            const text = await req.text?.();
+            if (!text || text.length > 1024)
+                throw new APIError('Invalid lookup request', 400);
+            let email;
+            try {
+                email = JSON.parse(text).email;
+            }
+            catch {
+                throw new APIError('Invalid lookup request', 400);
+            }
+            if (typeof email !== 'string')
+                throw new APIError('Invalid email', 400);
+            let identity;
+            try {
+                identity = await resolve(req, email, 'preview');
+            }
+            catch (error) {
+                if (!(error instanceof APIError))
+                    throw error;
+                return Response.json({ error: error.data?.code ?? 'unavailable' }, {
+                    status: error.status,
+                    headers: {
+                        'cache-control': 'no-store',
+                        'x-request-id': String(req.context.xignetDirectoryRequestId),
+                    },
+                });
+            }
+            const confirmation = await new SignJWT({
+                identity,
+                actor: String(req.user.id),
+            })
+                .setProtectedHeader({ alg: 'HS256' })
+                .setIssuer('xignet-directory-confirmation')
+                .setAudience(`${origin}/${collection}`)
+                .setIssuedAt()
+                .setExpirationTime('5m')
+                .sign(key(req));
+            return Response.json({ identity, confirmation }, {
+                headers: {
+                    'cache-control': 'no-store',
+                    'x-request-id': String(req.context.xignetDirectoryRequestId),
+                },
+            });
+        },
+    };
+    async function verify(req, email, confirmation) {
+        const identity = await resolve(req, email, 'save');
+        // Only trusted server-side Local API calls can skip the interactive preview.
+        if (req.payloadAPI === 'local' && !req.user)
+            return identity;
+        if (!req.user || !(await canManage(req)))
+            throw new APIError('Forbidden', 403);
+        try {
+            if (typeof confirmation !== 'string')
+                throw new Error();
+            const { payload } = await jwtVerify(confirmation, key(req), {
+                algorithms: ['HS256'],
+                issuer: 'xignet-directory-confirmation',
+                audience: `${origin}/${collection}`,
+                requiredClaims: ['exp', 'iat'],
+            });
+            const prior = payload.identity;
+            if (payload.actor !== String(req.user.id) ||
+                prior?.issuer !== identity.issuer ||
+                prior.sub !== identity.sub ||
+                prior.email !== identity.email)
+                throw new Error();
+        }
+        catch {
+            req.payload.logger.warn({
+                event: 'xignet_directory_confirmation_rejected',
+                requestId: req.context.xignetDirectoryRequestId,
+                actorId: req.user.id,
+                reason: 'confirmation_invalid',
+            });
+            throw new APIError('請重新查詢並確認 Xignet 身分後儲存。', 409);
+        }
+        return identity;
+    }
+    return { endpoint, verify };
+}

package/dist/directory-messages.d.ts

@@ -0,0 +1,9 @@
+export declare const directoryMessages: {
+    invalid_email: string;
+    not_found: string;
+    unauthorized: string;
+    forbidden: string;
+    rate_limited: string;
+    unavailable: string;
+    invalid_response: string;
+};

package/dist/directory-messages.js

@@ -0,0 +1,9 @@
+export const directoryMessages = {
+    invalid_email: '請輸入完整公司 email。',
+    not_found: '查無可使用此 CMS 的確定身分，請聯絡 Xignet 管理員。',
+    unauthorized: '身分查詢服務認證失敗，請聯絡管理員。',
+    forbidden: '此 CMS 尚未獲得身分查詢權限。',
+    rate_limited: '查詢過於頻繁，請稍後再試。',
+    unavailable: '身分查詢暫時無法使用，請稍後再試。',
+    invalid_response: '身分查詢回應無法驗證，請聯絡管理員。',
+};

package/dist/login.js

@@ -175,7 +175,10 @@ export function createLogin(options, sessions) {
                     },
                 });
                 user._sid = sid;
-                user._strategy = 'local-jwt';
+                user._strategy =
+                    options.sessionAuthentication === 'xignet-only'
+                        ? 'xignet-session'
+                        : 'local-jwt';
                 req.user = user;
                 for (const hook of collectionConfig.hooks.afterLogin) {
                     user =

package/dist/managed-users.d.ts

@@ -0,0 +1,22 @@
+import { type DirectoryClient } from '@xignet/client/directory';
+import { type CollectionConfig, type PayloadRequest, type TypedUser } from 'payload';
+import type { ResolveUser, XignetPayloadIntegration } from './types.js';
+export interface ManagedUsersOptions<TUser extends TypedUser = TypedUser> {
+    /** Project policy for the administrators allowed to edit identity bindings. */
+    readonly canManageBindings: (req: PayloadRequest) => boolean | Promise<boolean>;
+    /** Local account eligibility; the plugin does not assign business roles. */
+    readonly allowUser: (user: TUser) => boolean | Promise<boolean>;
+    /** Local fields whose changes must revoke SSO sessions, for example role. */
+    readonly revokeOnFields?: readonly string[];
+}
+export declare function createManagedUsers<TUser extends TypedUser>({ issuer, resource, directory, userCollection, policy, revoke, }: {
+    issuer: string;
+    resource: string;
+    directory?: DirectoryClient;
+    userCollection: string;
+    policy: ManagedUsersOptions<TUser>;
+    revoke: XignetPayloadIntegration['revokeUserSessions'];
+}): {
+    resolveUser: ResolveUser<TUser>;
+    enhanceUser: (config: CollectionConfig) => CollectionConfig;
+};

package/dist/managed-users.js

@@ -0,0 +1,206 @@
+import { randomUUID } from 'node:crypto';
+import { canonicalEmail } from '@xignet/client/directory';
+import { directoryBindings } from './directory-binding.js';
+import { APIError, } from 'payload';
+export function createManagedUsers({ issuer, resource, directory, userCollection, policy, revoke, }) {
+    const bindings = directoryBindings({
+        directory,
+        issuer,
+        collection: userCollection,
+        origin: new URL(resource).origin,
+        canManage: policy.canManageBindings,
+    });
+    const changedFields = [
+        ...new Set([
+            'email',
+            'xignetIssuer',
+            'xignetSubject',
+            'xignetEnabled',
+            ...(policy.revokeOnFields ?? []),
+        ]),
+    ];
+    const resolveUser = async ({ identity, payload, channel, login, }) => {
+        if (identity.issuer !== issuer)
+            return { status: 'denied', reason: 'not_allowed' };
+        const found = await payload.find({
+            collection: userCollection,
+            overrideAccess: true,
+            limit: 2,
+            depth: 0,
+            where: {
+                and: [
+                    { xignetIssuer: { equals: identity.issuer } },
+                    { xignetSubject: { equals: identity.subject } },
+                ],
+            },
+        });
+        if (!found.docs.length)
+            return { status: 'denied', reason: 'unbound' };
+        if (found.docs.length !== 1)
+            return { status: 'denied', reason: 'not_allowed' };
+        const user = found.docs[0];
+        if (channel === 'login' &&
+            (login?.idTokenClaims.email_verified !== true ||
+                typeof login.idTokenClaims.email !== 'string' ||
+                canonicalEmail(login.idTokenClaims.email) !== user.email))
+            return { status: 'denied', reason: 'not_allowed' };
+        if (!user.xignetEnabled)
+            return { status: 'denied', reason: 'disabled' };
+        if (!(await policy.allowUser(user)))
+            return { status: 'denied', reason: 'not_allowed' };
+        return { status: 'allowed', user: { ...user, collection: userCollection } };
+    };
+    const enhanceUser = (config) => {
+        const reserved = [
+            'xignetIssuer',
+            'xignetSubject',
+            'xignetEnabled',
+            'xignetDirectoryConfirmation',
+        ];
+        if (config.fields.some((field) => 'name' in field && reserved.includes(field.name)))
+            throw new Error('Managed Xignet identity fields are installed by the plugin');
+        const access = ({ req }) => policy.canManageBindings(req);
+        return {
+            ...config,
+            endpoints: [...(config.endpoints || []), bindings.endpoint],
+            indexes: [
+                ...(config.indexes ?? []),
+                {
+                    fields: ['xignetIssuer', 'xignetSubject'],
+                    unique: true,
+                },
+            ],
+            fields: [
+                ...config.fields,
+                {
+                    name: 'xignetDirectoryConfirmation',
+                    type: 'text',
+                    virtual: true,
+                    access: { read: access, create: access, update: access },
+                    admin: {
+                        components: {
+                            Field: {
+                                path: '@xignet/payload/client#XignetDirectoryField',
+                                clientProps: { collection: userCollection },
+                            },
+                        },
+                    },
+                },
+                {
+                    name: 'xignetIssuer',
+                    type: 'text',
+                    label: 'Xignet issuer',
+                    admin: {
+                        readOnly: true,
+                        description: 'Managed by the Xignet provider configuration.',
+                    },
+                    access: { read: access, create: access, update: access },
+                },
+                {
+                    name: 'xignetSubject',
+                    type: 'text',
+                    label: 'Xignet sub',
+                    admin: {
+                        readOnly: true,
+                        description: '由公司 email 查詢取得的 Xignet 身分。',
+                    },
+                    access: { read: access, create: access, update: access },
+                },
+                {
+                    name: 'xignetEnabled',
+                    type: 'checkbox',
+                    defaultValue: true,
+                    label: 'Enable Xignet access',
+                    access: { read: access, create: access, update: access },
+                },
+            ],
+            hooks: {
+                ...config.hooks,
+                beforeValidate: [
+                    ...(config.hooks?.beforeValidate ?? []),
+                    async ({ data, originalDoc, operation, req }) => {
+                        if (!data)
+                            return data;
+                        const trusted = req.payloadAPI === 'local' && !req.user;
+                        const protectedFields = ['email', ...reserved];
+                        const changes = protectedFields.some((field) => data[field] !== undefined &&
+                            data[field] !== originalDoc?.[field]);
+                        if ((operation === 'create' || changes) &&
+                            !trusted &&
+                            !(await policy.canManageBindings(req)))
+                            throw new APIError('Xignet binding management is forbidden', 403);
+                        let email;
+                        try {
+                            email =
+                                data.email === undefined
+                                    ? originalDoc?.email
+                                    : canonicalEmail(data.email);
+                        }
+                        catch {
+                            throw new APIError('請輸入完整公司 email。', 400, null, true);
+                        }
+                        const needsLookup = operation === 'create' ||
+                            email !== originalDoc?.email ||
+                            (data.xignetEnabled === true && !originalDoc?.xignetEnabled) ||
+                            Boolean(data.xignetDirectoryConfirmation);
+                        if (needsLookup) {
+                            const identity = await bindings.verify(req, email, data.xignetDirectoryConfirmation);
+                            if (operation !== 'create' &&
+                                originalDoc?.xignetSubject &&
+                                (originalDoc.xignetSubject !== identity.sub ||
+                                    originalDoc.xignetIssuer !== identity.issuer))
+                                throw new APIError('現有帳號不能改綁另一個 Xignet 身分。', 409);
+                            for (const [field, value] of Object.entries({
+                                xignetIssuer: identity.issuer,
+                                xignetSubject: identity.sub,
+                            })) {
+                                if (data[field] != null &&
+                                    data[field] !== '' &&
+                                    data[field] !== value)
+                                    throw new APIError('Xignet identity is managed by Directory', 400);
+                                data[field] = value;
+                            }
+                            data.email = identity.email;
+                        }
+                        else {
+                            for (const field of ['xignetIssuer', 'xignetSubject'])
+                                if (data[field] !== undefined &&
+                                    data[field] !== originalDoc?.[field])
+                                    throw new APIError('Xignet identity is managed by Directory', 400);
+                        }
+                        delete data.xignetDirectoryConfirmation;
+                        return data;
+                    },
+                ],
+                afterChange: [
+                    ...(config.hooks?.afterChange ?? []),
+                    async ({ doc, previousDoc, req, operation }) => {
+                        if (operation === 'update' &&
+                            previousDoc &&
+                            changedFields.some((field) => doc[field] !== previousDoc[field]))
+                            await revoke({ payload: req.payload, userId: doc.id, req });
+                        if (operation === 'create' ||
+                            !previousDoc ||
+                            changedFields.some((field) => doc[field] !== previousDoc[field]))
+                            req.payload.logger.info({
+                                event: 'xignet_user_changed',
+                                outcome: 'applied',
+                                requestId: req.context.xignetDirectoryRequestId ?? randomUUID(),
+                                actorId: req.user?.id ?? 'trusted-local',
+                                userId: doc.id,
+                                operation,
+                            });
+                        return doc;
+                    },
+                ],
+                beforeDelete: [
+                    ...(config.hooks?.beforeDelete ?? []),
+                    async ({ id, req }) => {
+                        await revoke({ payload: req.payload, userId: id, req });
+                    },
+                ],
+            },
+        };
+    };
+    return { resolveUser, enhanceUser };
+}