@xignet/payload 0.0.0-stage → 0.1.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marx Biotech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# @xignet/payload
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Xignet resource authorization for Payload v3. The adapter uses the official MCP plugin and applies token scopes together with existing Payload collection, document and field access. This package is under implementation and has not been published. MCP and native-session OIDC are implemented; website rollout and final delivery review remain in progress under the [implementation plan](../../docs/architecture/core-payload-implementation-plan.md).
+
+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.
+
+```ts
+import { createXignetPayload } from '@xignet/payload/v3';
+
+const xignet = createXignetPayload({
+  issuer: process.env.XIGNET_ISSUER!,
+  jwksUri: process.env.XIGNET_JWKS_URI!,
+  resource: 'https://cms.example.com/api/mcp',
+  admissionScopes: ['cms:access'],
+  userCollection: 'users',
+  resolveUser: async ({ identity, payload }) => {
+    // Server-side lookup by (identity.issuer, identity.subject), requiring
+    // an enabled local user. Do not auto-link by email or infer local roles.
+    const user = await resolveExistingLocalUser(payload, identity);
+    return user
+      ? { status: 'allowed', user: { ...user, collection: 'users' } }
+      : { status: 'denied', reason: 'unbound' };
+  },
+  mcp: {
+    enabled: true,
+    collections: { bulletins: { find: { scopes: ['cms:read'] } } },
+    globals: {},
+  },
+});
+
+// Add xignet.plugin() once to buildConfig({ plugins: [...] }).
+// Mount the metadata GET route using the standard Next.js handler helper:
+import { createXignetRouteHandlers } from '@xignet/payload/next';
+const handlers = createXignetRouteHandlers(xignet);
+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.
+
+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.
+
+## Write policies
+
+```ts
+bulletins: {
+  find: { scopes: ['cms:read'] },
+  update: { scopes: ['cms:write'] },
+  mutationPolicy: ({ originalDoc, data, operation, req, identity }) => {
+    // This project has no drafts: any write changes public API content.
+    return ['cms:publish'];
+  },
+}
+```
+
+Every enabled write requires a mutationPolicy. Return additional required scopes or `false` to refuse; scopes must also be declared in `mcp.scopesSupported` when they cannot be derived from operation policies. The policy runs before document changes and is evaluated for each update in a batch. Globals use update semantics. Project-specific draft, publish, retire and immediate-live behavior belongs here.
+
+The adapter preserves the original Access return value, including Where document filters, after enforcing scopes. Field access remains Payload's responsibility. Official content tools use `overrideAccess: false`. Verified request markers survive Local API context copies but cannot be forged by JSON. These controls apply to `payloadAPI: 'MCP'`; existing public REST/GraphQL and trusted Local API behavior follow the project's existing rules.
+
+## Validation
+
+`pnpm --filter @xignet/payload test` initializes a temporary SQLite Payload database and sends requests through the actual official MCP handler. It verifies Bearer admission, token claims, local binding/disablement, scope-based tool lists, document/field access, user isolation, forged-context rejection, publication scopes, public access preservation and resolver outage propagation. Fixtures disable automatic types/import-map generation and release upstream MCP cleanup timers; they do not force-exit the test process.
+
+
+## Native-session SSO
+
+Set `login` on the integration:
+
+```ts
+login: {
+  enabled: true,
+  clientId: process.env.XIGNET_WEB_CLIENT_ID!,
+  redirectUri: 'https://cms.example.com/auth/xignet/callback',
+  scopes: ['openid', 'email'],
+  transactionSecret: process.env.XIGNET_LOGIN_TRANSACTION_SECRET!,
+  successRedirect: '/admin',
+  session: { maxAgeSeconds: 7200, absoluteMaxAgeSeconds: 7200 },
+}
+```
+
+Use a dedicated public web client with fixed callback and S256 PKCE, separate from MCP clients. The callback must share the configured CMS origin; redirects remain on that origin. `transactionSecret` must contain at least 32 random bytes. The adapter encrypts/authenticates the entire transaction in a short-lived, host-only HttpOnly SameSite=Lax cookie (Secure on HTTPS). It clears the cookie on completion or failure. Access/ID tokens and refresh credentials are not returned to application JavaScript or stored as browser sessions.
+
+```ts
+const handlers = createXignetRouteHandlers(xignet, {
+  getPayload: async () => getPayload({ config }),
+});
+// Export GET = handlers.login at /auth/xignet/login.
+// Export GET = handlers.callback at /auth/xignet/callback.
+// 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.
+
+The plugin adds the private `xignet-sessions` collection even while login is disabled. Include it and the official MCP key collection in database migrations. It stores native SID linkage, absolute expiry and the verified access-token identity from login; it never stores the raw access/ID/refresh token. Metadata is not readable/writable through REST/MCP, including by ordinary admin accounts. The project remains responsible for approved `(issuer, subject)` bindings and local roles.
+
+`resolveUser` receives `channel: 'session'` during subsequent SSO authentication and refresh. This is the historical verified identity stored at login, not a newly verified OAuth token: its OAuth expiry may have elapsed. Resolve current local binding/enablement and roles without treating that historical expiry as the browser session expiry. No Xignet network call is required on each native session request.
+
+Native JWTs remain signed by the project's Payload secret and reference a real SID. Refresh cannot cross the stored absolute deadline. Missing/expired metadata and disabled/unbound users observed during authentication invalidate the native SID persistently. For immediate revocation, projects must call revokeUserSessions with the update request from their binding/enablement change hook; this also prevents a disable/re-enable sequence with no intervening request from reviving an old cookie. `integration.revokeUserSessions({ payload, userId, req? })` explicitly removes that user's SSO sessions while retaining independent local sessions. Native logout cleans the current metadata entry. Global Xignet logout is not an automatic CMS logout.
+
+Login failure rolls back SID/metadata when the adapter supports transactions, or explicitly removes the newly created SID/metadata otherwise. Arbitrary external side effects in custom hooks cannot be rolled back by this package. Existing local-password login retains its native expiration and has no SSO marker.
+
+## Auditing and release
+
+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.
+
+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.
+
+The database adapter must provide read-after-write consistency for login session records. Before issuing the browser cookie, the callback confirms the native SID and private metadata with fresh reads outside the completed transaction, since some adapter commit helpers can suppress an underlying transaction failure. A missing record refuses login instead of issuing an unusable cookie.
+
+For staged rollout, configure the final collection/global policies once and set `mcp.writesEnabled: false` to hide and deny create/update while retaining the same schema. Set it to true after write/publish validation; omission preserves the default of enabling configured operations. `mcp.enabled` and `login.enabled` also retain their private collections when disabled.

package/dist/login.d.ts

@@ -0,0 +1,7 @@
+import { type Payload, type TypedUser } from 'payload';
+import { type createNativeSessions } from './native-session.js';
+import type { XignetPayloadOptions } from './types.js';
+export declare function createLogin<TUser extends TypedUser>(options: XignetPayloadOptions<TUser>, sessions: ReturnType<typeof createNativeSessions<TUser>>): {
+    login(request: Request): Promise<Response>;
+    callback(request: Request, payload: Payload): Promise<Response>;
+};

package/dist/login.js

@@ -0,0 +1,312 @@
+import { hkdfSync } from 'node:crypto';
+import { createOidcClient, LoginDiscoveryError, LoginTransportError, OidcError, } from '@xignet/core/oidc';
+import { trustedUrl } from '@xignet/core';
+import { EncryptJWT, errors, jwtDecrypt } from 'jose';
+import { APIError, commitTransaction, createLocalReq, getFieldsToSign, initTransaction, jwtSign, } from 'payload';
+import { addSessionToUser, generatePayloadCookie } from 'payload/shared';
+import { SESSION_CLAIM, SESSION_COLLECTION, } from './native-session.js';
+class LoginTransactionInterrupted extends Error {
+    constructor() {
+        super('Owned login transaction was interrupted by a nested operation');
+        this.name = 'LoginTransactionInterrupted';
+    }
+}
+export function createLogin(options, sessions) {
+    const login = options.login;
+    const resource = trustedUrl(options.resource, options.allowInsecureLoopback);
+    const redirect = login
+        ? trustedUrl(login.redirectUri, options.allowInsecureLoopback)
+        : undefined;
+    if (redirect && redirect.origin !== resource.origin)
+        throw new Error('SSO callback must share the CMS resource origin');
+    const success = new URL(login?.successRedirect ?? '/admin', resource.origin);
+    if (success.origin !== resource.origin ||
+        (login?.enabled && !login.successRedirect.startsWith('/')))
+        throw new Error('SSO successRedirect must be a local absolute path');
+    let key;
+    if (login?.enabled) {
+        if (Buffer.byteLength(login.transactionSecret, 'utf8') < 32)
+            throw new Error('SSO transactionSecret must be at least 32 random bytes');
+        key = new Uint8Array(hkdfSync('sha256', login.transactionSecret, new Uint8Array(), '@xignet/payload/v3 transaction', 32));
+    }
+    const oidc = login?.enabled
+        ? createOidcClient({
+            ...options,
+            audience: options.resource,
+            clientId: login.clientId,
+            redirectUri: login.redirectUri,
+            scopes: login.scopes,
+            admissionScopes: options.admissionScopes,
+        })
+        : undefined;
+    const cookieName = `xignet_login.${options.userCollection}`;
+    const transactionCookie = (value, seconds) => `${cookieName}=${value}; Path=${redirect.pathname}; Max-Age=${seconds}; HttpOnly; SameSite=Lax${redirect.protocol === 'https:' ? '; Secure' : ''}`;
+    return {
+        async login(request) {
+            if (!oidc || !key)
+                return new Response(null, { status: 404 });
+            if (request.method !== 'GET')
+                return new Response(null, { status: 405, headers: { allow: 'GET' } });
+            const begin = await oidc.begin();
+            const sealed = await new EncryptJWT({ transaction: begin.transaction })
+                .setProtectedHeader({ alg: 'dir', enc: 'A256GCM' })
+                .setIssuer(resource.origin)
+                .setAudience(login.redirectUri)
+                .setIssuedAt()
+                .setExpirationTime('600s')
+                .encrypt(key);
+            return new Response(null, {
+                status: 303,
+                headers: {
+                    location: begin.authorizationUrl,
+                    'set-cookie': transactionCookie(sealed, 600),
+                    'cache-control': 'no-store',
+                    'referrer-policy': 'no-referrer',
+                },
+            });
+        },
+        async callback(request, payload) {
+            if (!oidc || !key)
+                return new Response(null, { status: 404 });
+            if (request.method !== 'GET')
+                return new Response(null, { status: 405, headers: { allow: 'GET' } });
+            if (!payload.config.serverURL ||
+                new URL(payload.config.serverURL).origin !== resource.origin)
+                throw new Error('SSO Payload provider has the wrong serverURL');
+            const headers = new Headers({
+                'set-cookie': transactionCookie('', 0),
+                'cache-control': 'no-store',
+                'referrer-policy': 'no-referrer',
+            });
+            const req = await createLocalReq({ req: request.clone() }, payload);
+            req.payloadAPI = 'REST';
+            let ownTransaction = false;
+            let ownedTransactionID;
+            let transactionCompleted = false;
+            let createdSession;
+            try {
+                const values = (request.headers.get('cookie') ?? '')
+                    .split(';')
+                    .map((pair) => pair.trim())
+                    .filter((pair) => pair.startsWith(`${cookieName}=`));
+                if (values.length !== 1)
+                    throw new OidcError('state_invalid');
+                const decrypted = await jwtDecrypt(values[0].slice(cookieName.length + 1), key, {
+                    keyManagementAlgorithms: ['dir'],
+                    contentEncryptionAlgorithms: ['A256GCM'],
+                    issuer: resource.origin,
+                    audience: login.redirectUri,
+                    requiredClaims: ['exp'],
+                });
+                const result = await oidc.complete({
+                    callbackUrl: request.url,
+                    transaction: decrypted.payload
+                        .transaction,
+                });
+                const resolved = await options.resolveUser({
+                    identity: result.identity,
+                    channel: 'login',
+                    payload,
+                    login: { idTokenClaims: result.idTokenClaims },
+                });
+                if (resolved.status !== 'allowed' ||
+                    resolved.user.collection !== options.userCollection)
+                    throw new APIError('SSO access denied', 403);
+                ownTransaction = await initTransaction(req);
+                if (ownTransaction)
+                    ownedTransactionID = await req.transactionID;
+                const collectionConfig = payload.collections[options.userCollection].config;
+                let user = (await payload.db.findOne({
+                    collection: options.userCollection,
+                    req,
+                    where: { id: { equals: resolved.user.id } },
+                }));
+                if (!user ||
+                    (collectionConfig.auth.verify && user._verified !== true) ||
+                    (user.lockUntil && Date.parse(user.lockUntil) > Date.now()))
+                    throw new APIError('SSO access denied', 403);
+                user.collection = options.userCollection;
+                for (const hook of collectionConfig.hooks.beforeLogin)
+                    user =
+                        (await hook({
+                            collection: collectionConfig,
+                            context: req.context,
+                            req,
+                            user,
+                        })) || user;
+                if (user.id !== resolved.user.id)
+                    throw new APIError('SSO user mismatch', 403);
+                const ttl = Math.min(sessions.maxAge, sessions.absoluteMaxAge);
+                const { sid } = await addSessionToUser({
+                    collectionConfig: {
+                        ...collectionConfig,
+                        auth: { ...collectionConfig.auth, tokenExpiration: ttl },
+                    },
+                    payload,
+                    req,
+                    user,
+                });
+                if (!sid)
+                    throw new Error('Native Payload SID was not created');
+                createdSession = { sid, userId: user.id };
+                const signed = await jwtSign({
+                    fieldsToSign: {
+                        ...getFieldsToSign({
+                            collectionConfig,
+                            user,
+                            email: user.email ?? '',
+                            sid,
+                        }),
+                        [SESSION_CLAIM]: true,
+                    },
+                    secret: payload.secret,
+                    tokenExpiration: ttl,
+                });
+                await payload.create({
+                    collection: SESSION_COLLECTION,
+                    req,
+                    overrideAccess: true,
+                    data: {
+                        sid,
+                        resource: options.resource,
+                        user: user.id,
+                        absoluteExpiresAt: new Date(Date.now() + sessions.absoluteMaxAge * 1000).toISOString(),
+                        identity: result.identity,
+                    },
+                });
+                user._sid = sid;
+                user._strategy = 'local-jwt';
+                req.user = user;
+                for (const hook of collectionConfig.hooks.afterLogin) {
+                    user =
+                        (await hook({
+                            collection: collectionConfig,
+                            context: req.context,
+                            req,
+                            user,
+                            token: signed.token,
+                        })) || user;
+                    if (user.id !== resolved.user.id)
+                        throw new APIError('SSO user mismatch', 403);
+                }
+                // Error responses may only clear the transaction cookie, including
+                // when committing the database transaction fails after signing.
+                const successHeaders = new Headers(headers);
+                successHeaders.append('set-cookie', generatePayloadCookie({
+                    collectionAuthConfig: {
+                        ...collectionConfig.auth,
+                        tokenExpiration: ttl,
+                    },
+                    cookiePrefix: payload.config.cookiePrefix,
+                    token: signed.token,
+                }));
+                successHeaders.set('location', success.toString());
+                const response = new Response(null, {
+                    status: 303,
+                    headers: successHeaders,
+                });
+                if (ownTransaction) {
+                    if (req.transactionID !== ownedTransactionID)
+                        throw new LoginTransactionInterrupted();
+                    await commitTransaction(req);
+                    transactionCompleted = true;
+                }
+                // Some adapters fulfill commit even if the underlying transaction
+                // rolled back. Fresh reads outside req's transaction must confirm
+                // both records before the browser receives its authentication cookie.
+                const [persistedMetadata, persistedUser] = await Promise.all([
+                    payload.db.findOne({
+                        collection: SESSION_COLLECTION,
+                        where: {
+                            and: [
+                                { sid: { equals: sid } },
+                                { resource: { equals: options.resource } },
+                                { user: { equals: user.id } },
+                            ],
+                        },
+                    }),
+                    payload.db.findOne({
+                        collection: options.userCollection,
+                        where: { id: { equals: user.id } },
+                    }),
+                ]);
+                if (!persistedMetadata ||
+                    !persistedUser?.sessions?.some((session) => session.id === sid))
+                    throw new APIError('SSO session persistence failed', 503);
+                return response;
+            }
+            catch (error) {
+                try {
+                    if (ownTransaction && !transactionCompleted) {
+                        // Payload's killTransaction swallows adapter rollback errors.
+                        // This callback owns the transaction and must observe failures.
+                        try {
+                            const interrupted = req.transactionID !== ownedTransactionID;
+                            await payload.db.rollbackTransaction(ownedTransactionID);
+                            // Nested Local API operations may call killTransaction first,
+                            // suppress rollback errors and remove req.transactionID. The
+                            // adapter cannot establish cleanup success in that case.
+                            if (interrupted)
+                                throw new LoginTransactionInterrupted();
+                        }
+                        finally {
+                            delete req.transactionID;
+                        }
+                    }
+                    else if (createdSession)
+                        await sessions.revokeSession(req, createdSession.userId, createdSession.sid);
+                }
+                catch (cleanupError) {
+                    payload.logger.error({
+                        event: 'xignet_login_cleanup_failed',
+                        category: cleanupError instanceof Error ? cleanupError.name : 'unknown',
+                    });
+                    return Response.json({ error: 'login_failed' }, { status: 503, headers });
+                }
+                if (error instanceof LoginDiscoveryError ||
+                    error instanceof LoginTransportError) {
+                    payload.logger.warn({
+                        event: 'xignet_login_unavailable',
+                        category: error.name,
+                        detail: error.detail,
+                    });
+                    return Response.json({ error: 'verification_unavailable' }, { status: 503, headers });
+                }
+                if (error instanceof OidcError ||
+                    error instanceof errors.JOSEError ||
+                    error instanceof APIError) {
+                    const status = error instanceof OidcError &&
+                        error.reason === 'verification_unavailable'
+                        ? 503
+                        : error instanceof APIError
+                            ? error.status
+                            : 401;
+                    payload.logger.warn({
+                        event: 'xignet_login_refused',
+                        category: error.name,
+                        ...(error instanceof OidcError
+                            ? { reason: error.reason, detail: error.detail }
+                            : {}),
+                    });
+                    return Response.json({
+                        error: status === 503 ? 'verification_unavailable' : 'login_failed',
+                    }, { status, headers });
+                }
+                // HTTP is the outer boundary: preserve the 500, clear browser state,
+                // and log stack locations without an arbitrary exception message.
+                const header = error instanceof Error
+                    ? `${error.name}: ${error.message}`
+                    : undefined;
+                const frames = error instanceof Error && header && error.stack?.startsWith(header)
+                    ? error.stack.slice(header.length)
+                    : undefined;
+                payload.logger.error({
+                    event: 'xignet_login_failed',
+                    category: error instanceof Error ? error.name : 'unknown',
+                    stack: frames,
+                });
+                return Response.json({ error: 'login_failed' }, { status: 500, headers });
+            }
+        },
+    };
+}

package/dist/native-session.d.ts

@@ -0,0 +1,26 @@
+import { type VerifiedIdentity } from '@xignet/core';
+import { type CollectionConfig, type Payload, type PayloadRequest, type TypedUser } from 'payload';
+import type { XignetPayloadOptions } from './types.js';
+export declare const SESSION_COLLECTION = "xignet-sessions";
+export declare const SESSION_CLAIM = "__xignet_sso";
+export type UserID = string | number;
+export type SessionRecord = {
+    id: UserID;
+    sid: string;
+    resource: string;
+    user: UserID;
+    absoluteExpiresAt: string;
+    identity: VerifiedIdentity;
+};
+export declare function createNativeSessions<TUser extends TypedUser>(options: XignetPayloadOptions<TUser>): {
+    collection: CollectionConfig;
+    revokeSession: (req: PayloadRequest, userId: UserID, sid: string) => Promise<void>;
+    enhanceUser: (config: CollectionConfig) => CollectionConfig;
+    revokeUserSessions: ({ payload, userId, req: existingReq, }: {
+        payload: Payload;
+        userId: UserID;
+        req?: PayloadRequest;
+    }) => Promise<void>;
+    maxAge: number;
+    absoluteMaxAge: number;
+};