@xcitedbs/client 0.2.27 → 0.3.1

package/dist/bootstrap-real.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/bootstrap-real.test.js

@@ -0,0 +1,264 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Wet-test reproduction of the client developer's "DB-reset Forbidden" bug, end-to-end.
+ *
+ * Set XCITEDB_BASE_URL, XCITEDB_ADMIN_TOKEN, XCITEDB_TENANT_ID to run; otherwise skipped.
+ *
+ * Each `it` exercises one of the four stacked failures from the original incident report:
+ *   1. `default_groups: []` + `registration_enabled: true` produces ghost users → server now
+ *      surfaces `warnings: ["default_groups_empty"]` and the BFF can act on it before users
+ *      register.
+ *   2. SPA tries `PUT /api/v1/app/users/:id/groups` with a public API key → server now returns
+ *      `403 reason: "role_forbidden_public_key"` (previously bare 403 with no reason).
+ *   3. `loginAppUser` sends a stale `Authorization: Bearer …` from a previous session → SDK
+ *      now clears tokens before the request; if a hand-rolled client skips that, server returns
+ *      `403 reason: "already_authenticated"` so the failure is diagnosable.
+ *   4. The `X-Test-Auth: preserve` mode lets us reproduce #2 in a wet test (under legacy bypass
+ *      the public-key context is erased, so the bug couldn't be reproduced in tests at all).
+ */
+const node_test_1 = require("node:test");
+const strict_1 = __importDefault(require("node:assert/strict"));
+const node_crypto_1 = require("node:crypto");
+const client_js_1 = require("./client.js");
+const types_js_1 = require("./types.js");
+function wetEnv() {
+    const baseUrl = process.env.XCITEDB_BASE_URL?.trim();
+    const accessToken = process.env.XCITEDB_ADMIN_TOKEN?.trim();
+    const tenantId = process.env.XCITEDB_TENANT_ID?.trim();
+    if (!baseUrl || !accessToken || !tenantId)
+        return null;
+    return { baseUrl, accessToken, tenantId };
+}
+const w = wetEnv();
+const wd = w ? node_test_1.describe : node_test_1.describe.skip;
+wd('bootstrap reproduction (wet)', () => {
+    (0, node_test_1.it)('default_groups_empty warning surfaces, updateAppAuthConfig clears it', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        // Use preserve mode so admin auth is faithful; we still need real admin credentials to PUT
+        // /api/v1/app/auth/config. The test session is just isolation, not auth bypass.
+        const admin = await client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: e.baseUrl,
+            accessToken: e.accessToken,
+            platformConsole: true,
+            projectId: e.tenantId,
+            context: { branch: 'main', project_id: e.tenantId },
+            testAuth: 'preserve',
+        });
+        try {
+            // First: clear default_groups so the warning condition holds.
+            await admin.updateAppAuthConfig({ registration_enabled: true, default_groups: [] });
+            const before = await admin.getAppAuthConfig();
+            strict_1.default.deepEqual(before.default_groups, [], 'precondition: default_groups must be empty');
+            strict_1.default.ok(Array.isArray(before.warnings) && before.warnings.includes('default_groups_empty'), `getAppAuthConfig must surface "default_groups_empty" — got warnings=${JSON.stringify(before.warnings)}`);
+            // Now patch it.
+            const after = await admin.updateAppAuthConfig({ default_groups: ['editor'] });
+            strict_1.default.deepEqual(after.default_groups, ['editor']);
+            strict_1.default.ok(!after.warnings || !after.warnings.includes('default_groups_empty'), 'warning must clear once default_groups is non-empty');
+        }
+        finally {
+            await admin.destroyTestSession().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('register + login on the same client succeeds (token auto-cleared)', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = await client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: e.baseUrl,
+            accessToken: e.accessToken,
+            platformConsole: true,
+            projectId: e.tenantId,
+            context: { branch: 'main', project_id: e.tenantId },
+            testAuth: 'preserve',
+        });
+        try {
+            // Bootstrap: registration on, default_groups set so the user can do things.
+            await admin.updateAppAuthConfig({
+                registration_enabled: true,
+                default_groups: [client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor')],
+            });
+            // Anonymous app client (no apiKey, no accessToken). Reuses the test session via header
+            // propagation through the testSessionToken on the parent client; spawn a sibling
+            // anon client that shares the test session.
+            const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+            const email = `js_boot_${suffix}@apitest.invalid`;
+            const password = `Js_${suffix}!aA1`;
+            const anon = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                // Same test session so the user lives in the ephemeral DB.
+                testSessionToken: admin.testSessionToken,
+                // Required so the app-auth endpoints see anonymous_app_client (project_id propagates anonymously).
+                testAuth: 'preserve',
+            });
+            // First flow: register, then login on the same client. Without the SDK's clear-before-login
+            // fix this would 403 with reason="already_authenticated" because the register response would
+            // (in some flows) have set a token, and the next login would reuse it.
+            await anon.registerAppUser(email, password);
+            const pair = await anon.loginAppUser(email, password);
+            strict_1.default.ok(pair.access_token.length > 0, 'login returned an access token');
+        }
+        finally {
+            await admin.destroyTestSession().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('hand-rolled stale-bearer login returns 403 reason="already_authenticated"', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = await client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: e.baseUrl,
+            accessToken: e.accessToken,
+            platformConsole: true,
+            projectId: e.tenantId,
+            context: { branch: 'main', project_id: e.tenantId },
+            testAuth: 'preserve',
+        });
+        try {
+            await admin.updateAppAuthConfig({
+                registration_enabled: true,
+                default_groups: [client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor')],
+            });
+            const sessionToken = admin.testSessionToken;
+            const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+            const email = `js_stale_${suffix}@apitest.invalid`;
+            const password = `Js_${suffix}!aA1`;
+            // Step 1: register and login normally to get a real app-user JWT.
+            const anon = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                testSessionToken: sessionToken,
+                testAuth: 'preserve',
+            });
+            await anon.registerAppUser(email, password);
+            const pair = await anon.loginAppUser(email, password);
+            strict_1.default.ok(pair.access_token);
+            // Step 2: simulate a buggy client that re-issues login while still carrying the stale Bearer.
+            // Bypass the SDK (which would clear-before-login) by sending raw fetch.
+            const url = `${e.baseUrl.replace(/\/+$/, '')}/api/v1/app/auth/login`;
+            const r = await fetch(url, {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Authorization: `Bearer ${pair.access_token}`,
+                    'X-Test-Session': sessionToken,
+                    'X-Test-Auth': 'preserve',
+                },
+                body: JSON.stringify({ email, password, tenant_id: e.tenantId }),
+            });
+            strict_1.default.equal(r.status, 403, 'stale-bearer login must 403');
+            const body = (await r.json());
+            strict_1.default.equal(body.reason, 'already_authenticated', `body.reason must be "already_authenticated"; got ${JSON.stringify(body)}`);
+            strict_1.default.ok(body.hint && body.hint.length > 0, 'response must carry a hint');
+        }
+        finally {
+            await admin.destroyTestSession().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('public API key cannot PUT /api/v1/app/users/:id/groups; 403 reason="role_forbidden_public_key"', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        // We need a real public API key to exercise this path. The test session is a separate concern
+        // — the public-key denial is enforced by the role check before any test-session logic. Use
+        // the PROJECT public API key from env if available; otherwise skip with a clear message.
+        const publicKey = process.env.XCITEDB_PUBLIC_API_KEY?.trim();
+        if (!publicKey) {
+            // Run against the real tenant with a public key; not via test session because public keys
+            // can't always provision sessions and the failure mode is the role gate, not the storage.
+            console.log('  ⏭  skipped — set XCITEDB_PUBLIC_API_KEY (a public project key) to verify role_forbidden_public_key');
+            return;
+        }
+        const admin = new client_js_1.XCiteDBClient({
+            baseUrl: e.baseUrl,
+            accessToken: e.accessToken,
+            platformConsole: true,
+            projectId: e.tenantId,
+            context: { branch: 'main', project_id: e.tenantId },
+        });
+        // Create a real app user to target. Don't use a test session — the developer's bug was on
+        // the production tenant, and the role gate fires the same way regardless.
+        const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+        const email = `js_pk_${suffix}@apitest.invalid`;
+        const password = `Js_${suffix}!aA1`;
+        let userId = null;
+        try {
+            const u = await admin.createAppUser(email, password);
+            userId = u.user_id;
+            const url = `${e.baseUrl.replace(/\/+$/, '')}/api/v1/app/users/${encodeURIComponent(u.user_id)}/groups`;
+            const r = await fetch(url, {
+                method: 'PUT',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'X-API-Key': publicKey,
+                    'X-Project-Id': e.tenantId,
+                },
+                body: JSON.stringify({ groups: [client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor')] }),
+            });
+            strict_1.default.equal(r.status, 403, 'public key on admin-write endpoint must 403');
+            const body = (await r.json());
+            strict_1.default.equal(body.reason, 'role_forbidden_public_key', `body.reason must be "role_forbidden_public_key"; got ${JSON.stringify(body)} — this is the bug the developer hit`);
+        }
+        finally {
+            if (userId)
+                await admin.deleteAppUser(userId).catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('preserve mode reproduces public-key denials that bypass mode would mask', async () => {
+        // Sanity check that the new preserve mode actually evaluates auth normally inside a test
+        // session — the whole point of E in the plan. We don't need a public API key to verify
+        // this; we just need to confirm that an unauthenticated request to an admin endpoint
+        // returns 403 (with reason) rather than being silently admined-through.
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = await client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: e.baseUrl,
+            accessToken: e.accessToken,
+            platformConsole: true,
+            projectId: e.tenantId,
+            context: { branch: 'main', project_id: e.tenantId },
+            testAuth: 'preserve',
+        });
+        try {
+            const sessionToken = admin.testSessionToken;
+            // Send an admin GET (/api/v1/app/auth/config) with no credentials at all under preserve mode.
+            // Under bypass mode this would be silently approved (synthesized admin). Under preserve, the
+            // AuthFilter sees no credentials and rejects.
+            const url = `${e.baseUrl.replace(/\/+$/, '')}/api/v1/app/auth/config`;
+            const r = await fetch(url, {
+                method: 'GET',
+                headers: { 'X-Test-Session': sessionToken, 'X-Test-Auth': 'preserve' },
+            });
+            strict_1.default.ok(r.status === 401 || r.status === 403, `preserve mode must enforce auth; got status ${r.status} — likely regressed back to bypass`);
+            if (r.status === 403) {
+                const body = (await r.json());
+                strict_1.default.ok(body.reason && body.reason.length > 0, '403 must carry a reason');
+            }
+        }
+        finally {
+            await admin.destroyTestSession().catch(() => { });
+        }
+    });
+});
+// Type-level sanity check: confirm the typed XCiteDBForbiddenReason union covers the reasons we
+// assert above. This costs nothing at runtime; if the reasons get renamed server-side without an
+// SDK update, this block will fail to typecheck.
+//
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+function _typeFenceForReasons() {
+    const _e = new types_js_1.XCiteDBForbiddenError('Forbidden', 403);
+    // Each branch must compile.
+    const r = 'already_authenticated';
+    const r2 = 'role_forbidden_public_key';
+    const r3 = 'auth_admin_required';
+    void r;
+    void r2;
+    void r3;
+}

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -15,7 +15,12 @@ export declare class XCiteDBClient {
     private onAppUserTokensUpdated?;
     private onSessionInvalid?;
     private testSessionToken?;
-    private testRequireAuth?;
+    /**
+     * Test-session auth fidelity. `'bypass'` is the legacy mode that synthesizes a developer-admin
+     * identity server-side; `'required'` and `'preserve'` send `X-Test-Auth: required|preserve`.
+     * `createTestSession` defaults to `'required'`.
+     */
+    private testAuthMode?;
     private userIsolation?;
     private cachedAppUserId?;
     private readonly requestTimeoutMs?;
@@ -24,7 +29,14 @@ export declare class XCiteDBClient {
     constructor(options: XCiteDBClientOptions);
     /**
      * Create an ephemeral test database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
-     * then returns a client that sends `X-Test-Session` (auth-free by default).
+     * then returns a client that sends `X-Test-Session` on every subsequent request.
+     *
+     * **Auth fidelity (default = `'required'`):** the SDK now defaults to faithful auth so wet tests
+     * exercise the same role/credential gates as production. Pass `testAuth: 'preserve'` to keep
+     * faithful auth but skip ABAC bootstrapping (real auth, lenient policies). The legacy
+     * `'bypass'` mode (server synthesizes a developer-admin identity) is available but not the
+     * default — it erases the public-key context and produces tests that pass when production fails.
+     *
      * With `opts.overlay === true`, the server stores overlay mode: reads merge the empty `_test/...` LMDB
      * over the current project's production data (read-only base); writes stay under `_test/...` only.
      */
@@ -147,17 +159,43 @@ export declare class XCiteDBClient {
     createApiKey(name: string, expiresAt?: number, keyType?: 'secret' | 'public'): Promise<unknown>;
     changePassword(currentPassword: string, newPassword: string): Promise<void>;
     revokeApiKey(keyId: string): Promise<void>;
+    /**
+     * Self-register an app user. Public endpoint — set `context.project_id` on the client first.
+     *
+     * **Side effect:** clears any cached `appUserAccessToken` / `appUserRefreshToken` before the
+     * request. Without this, a previously logged-in client would send `Authorization: Bearer
+     * <stale-token>`, which the server (correctly) rejects with `reason: "already_authenticated"`.
+     * The clear runs before the request fires, so even a 4xx response leaves the client in a clean
+     * unauthenticated state — a fresh `loginAppUser` call works without manual `clearAppUserTokens`.
+     */
     registerAppUser(email: string, password: string, displayName?: string, attributes?: Record<string, unknown>): Promise<AppUser>;
     getOAuthProviders(): Promise<OAuthProvidersResponse>;
     /** Relative path + query for browser navigation to start OAuth (append to API base URL). */
     oauthAuthorizePath(provider: string): string;
-    /** Exchange one-time session code from OAuth browser redirect (public + tenant_id). */
+    /**
+     * Exchange one-time session code from OAuth browser redirect (public + tenant_id).
+     * Clears any cached app-user tokens before the request — see `loginAppUser` for rationale.
+     */
     exchangeOAuthCode(code: string): Promise<AppUserTokenPair>;
+    /**
+     * Sign in as an app user and **store** the issued access/refresh tokens on this client. Subsequent
+     * requests automatically send `Authorization: Bearer <access>` (or `X-App-User-Token` when paired
+     * with a developer key/JWT). Call `clearAppUserTokens()` (or `logoutAppUser()`) to drop them.
+     *
+     * **Side effect:** clears any cached `appUserAccessToken` / `appUserRefreshToken` before the
+     * request. Without this, a previously logged-in client would send `Authorization: Bearer
+     * <stale-token>` and the server would reject with `reason: "already_authenticated"`. The clear
+     * runs before the request fires, so re-logging in as a different user just works.
+     */
     loginAppUser(email: string, password: string): Promise<AppUserTokenPair>;
     refreshAppUser(): Promise<AppUserTokenPair>;
     logoutAppUser(): Promise<void>;
     appUserMe(): Promise<AppUser>;
     updateAppUserProfile(displayName?: string, attributes?: Record<string, unknown>): Promise<AppUser>;
+    /**
+     * Exchange a custom JWT for an app-user session.
+     * Clears any cached app-user tokens before the request — see `loginAppUser` for rationale.
+     */
     exchangeCustomToken(token: string): Promise<AppUserTokenPair>;
     /** Change app-user password (requires valid app-user access token). */
     changeAppUserPassword(currentPassword: string, newPassword: string): Promise<void>;
@@ -168,6 +206,24 @@ export declare class XCiteDBClient {
     /** Issue email verification token (developer-authenticated). Token omitted when delivery is smtp/webhook success. */
     sendAppUserVerification(userId: string): Promise<SendVerificationResponse>;
     getAppAuthConfig(): Promise<AppAuthConfig>;
+    /**
+     * Patch `auth.app_users.*` (PUT /api/v1/app/auth/config). Requires admin developer auth.
+     *
+     * Whitelisted keys: `enabled`, `registration_enabled`, `default_groups`,
+     * `require_email_verification`, `min_password_length`, `max_login_attempts`,
+     * `lockout_duration_seconds`, `access_token_expiry_seconds`, `refresh_token_expiry_seconds`,
+     * `reset_token_expiry_seconds`, `verification_token_expiry_seconds`, `public_base_url`.
+     *
+     * Secret-bearing fields (`jwt_secret`, `signing_key_path`, `custom_token_secret`,
+     * `oauth_providers`) are intentionally not patchable here — set them in server config and reload.
+     * Returns the full effective config including any `warnings`.
+     *
+     * @example Bootstrap a fresh project so registered users land in the editor group:
+     * ```ts
+     * await client.updateAppAuthConfig({ default_groups: ['editor'] });
+     * ```
+     */
+    updateAppAuthConfig(patch: Partial<AppAuthConfig>): Promise<AppAuthConfig>;
     getEmailConfig(): Promise<AppEmailConfig>;
     updateEmailConfig(config: AppEmailConfig): Promise<AppEmailConfig>;
     getEmailTemplates(): Promise<AppEmailTemplates>;
@@ -312,15 +368,31 @@ export declare class XCiteDBClient {
     updateSecurityConfig(config: Partial<SecurityConfig>): Promise<void>;
     /** Per-tenant user data spaces (`GET /api/v1/security/user-isolation`). Requires security admin. */
     getUserIsolationConfig(): Promise<UserIsolationConfig>;
+    /**
+     * Public-read sibling (`GET /api/v1/security/user-isolation/public`). Returns only the
+     * client-prefix-relevant fields (enabled, namespace_pattern, shared_*_paths). Lets SPAs
+     * configure isolation without admin auth.
+     */
+    getUserIsolationConfigPublic(): Promise<UserIsolationConfig>;
     /** Enable or reconfigure user isolation (`PUT /api/v1/security/user-isolation`). */
     setUserIsolationConfig(config: Partial<UserIsolationConfig>): Promise<UserIsolationConfig>;
     /** Disable user isolation and remove generated policies (`DELETE /api/v1/security/user-isolation`). */
     disableUserIsolation(): Promise<void>;
     /**
-     * Loads server isolation config; when enabled, configures client-side identifier prefixing to match
-     * the server (namespace + shared paths). Does not send `X-Prefix`; identifiers in requests are rewritten.
-     */
-    enableUserIsolation(): Promise<UserIsolationConfig>;
+     * Configure client-side identifier prefixing to match server-side user isolation. Does not send
+     * `X-Prefix`; identifiers in requests are rewritten by the SDK.
+     *
+     * Two forms:
+     * 1. **No-arg**: fetches the public read-only endpoint (`/api/v1/security/user-isolation/public`),
+     *    falling back to the admin endpoint on 404 (older servers). No admin auth needed in SPAs.
+     * 2. **Explicit config**: pass `{ namespace, shared_read_paths?, shared_write_paths? }` to skip
+     *    the network round-trip entirely. Useful when the BFF already knows the configuration.
+     */
+    enableUserIsolation(config?: {
+        namespace?: string;
+        shared_read_paths?: string[];
+        shared_write_paths?: string[];
+    }): Promise<UserIsolationConfig>;
     /**
      * Share a document from the caller’s user namespace with another app user (`POST …/user-isolation/shares`).
      * Requires an **app user** session (`appUserAccessToken` / `loginAppUser`) and tenant isolation enabled.
@@ -430,6 +502,26 @@ export declare class XCiteDBClient {
         includeContent?: boolean;
         matchStart?: string;
     }): Promise<DiffResult>;
+    /**
+     * Compare two XML provision trees structurally + textually and write the resulting
+     * diff document — annotated with `<ins>`, `<del>`, `<moved-to>`, `<moved-from>` and
+     * `diff:<key>` metadata attributes — to the target location.
+     *
+     * The output document carries `diff:document="true"` on its root. If the target
+     * identifier already holds a regular (non-diff) document, the call returns 409
+     * `target_not_smart_diff`; existing smart-diff documents are silently overwritten.
+     */
+    smartDiff(from: SmartDiffRef, to: SmartDiffRef, target: SmartDiffRef, metadata?: Record<string, string>, options?: {
+        diffText?: boolean;
+        excludeTags?: string[];
+        maxTextDiffBytes?: number;
+        /**
+         * Hard cap (bytes) on the combined approximate size of source A + source B.
+         * The server returns 413 `smart_diff_sources_too_large` when exceeded.
+         * Defaults to 8 MiB server-side.
+         */
+        maxSourceBytes?: number;
+    }): Promise<SmartDiffResult>;
     publishWorkspace(targetWorkspace: string, sourceWorkspace: string, options?: {
         message?: string;
         autoResolve?: 'none' | 'source' | 'target';

package/dist/client.js

@@ -90,6 +90,27 @@ function warnIfHttpOnTlsPort(baseUrl) {
         /* ignore invalid baseUrl */
     }
 }
+/**
+ * Resolve the test-session auth mode from the new `testAuth` option and the deprecated
+ * `testRequireAuth` boolean. Used by both the {@link XCiteDBClient} constructor and
+ * {@link XCiteDBClient.createTestSession}. Returns `undefined` when the client is not in a
+ * test session at all (no `testSessionToken`).
+ *
+ * Precedence:
+ * - If `testAuth` is set, use it directly.
+ * - Else if `testRequireAuth === true`, use `'required'`.
+ * - Else if `testRequireAuth === false`, use `'bypass'` (legacy explicit opt-out).
+ * - Else `undefined` — caller decides default. `createTestSession` defaults to `'required'`.
+ */
+function resolveTestAuthMode(testAuth, testRequireAuth) {
+    if (testAuth !== undefined)
+        return testAuth;
+    if (testRequireAuth === true)
+        return 'required';
+    if (testRequireAuth === false)
+        return 'bypass';
+    return undefined;
+}
 /** Uses `AbortSignal.timeout` when the runtime supports it. */
 function requestTimeoutSignal(ms) {
     if (ms === undefined || ms <= 0)
@@ -113,14 +134,21 @@ class XCiteDBClient {
         this.onAppUserTokensUpdated = options.onAppUserTokensUpdated;
         this.onSessionInvalid = options.onSessionInvalid;
         this.testSessionToken = options.testSessionToken;
-        this.testRequireAuth = options.testRequireAuth === true;
+        this.testAuthMode = resolveTestAuthMode(options.testAuth, options.testRequireAuth);
         this.userIsolation = options.userIsolation;
         this.requestTimeoutMs = options.requestTimeoutMs;
         warnIfHttpOnTlsPort(this.baseUrl);
     }
     /**
      * Create an ephemeral test database: calls `POST /api/v1/test/sessions` with your API key or Bearer,
-     * then returns a client that sends `X-Test-Session` (auth-free by default).
+     * then returns a client that sends `X-Test-Session` on every subsequent request.
+     *
+     * **Auth fidelity (default = `'required'`):** the SDK now defaults to faithful auth so wet tests
+     * exercise the same role/credential gates as production. Pass `testAuth: 'preserve'` to keep
+     * faithful auth but skip ABAC bootstrapping (real auth, lenient policies). The legacy
+     * `'bypass'` mode (server synthesizes a developer-admin identity) is available but not the
+     * default — it erases the public-key context and produces tests that pass when production fails.
+     *
      * With `opts.overlay === true`, the server stores overlay mode: reads merge the empty `_test/...` LMDB
      * over the current project's production data (read-only base); writes stay under `_test/...` only.
      */
@@ -146,12 +174,14 @@ class XCiteDBClient {
         if (opts.bootstrap !== undefined)
             sessionBody.bootstrap = opts.bootstrap;
         const data = await temp.request('POST', '/api/v1/test/sessions', Object.keys(sessionBody).length ? sessionBody : undefined, undefined, { no401Retry: true });
+        const mode = resolveTestAuthMode(opts.testAuth, opts.testRequireAuth) ?? 'required';
+        const keepCreds = mode !== 'bypass';
         const child = new XCiteDBClient({
             baseUrl: opts.baseUrl,
-            apiKey: opts.testRequireAuth ? opts.apiKey : undefined,
-            accessToken: opts.testRequireAuth ? opts.accessToken : undefined,
-            appUserAccessToken: opts.testRequireAuth ? opts.appUserAccessToken : undefined,
-            appUserRefreshToken: opts.testRequireAuth ? opts.appUserRefreshToken : undefined,
+            apiKey: keepCreds ? opts.apiKey : undefined,
+            accessToken: keepCreds ? opts.accessToken : undefined,
+            appUserAccessToken: keepCreds ? opts.appUserAccessToken : undefined,
+            appUserRefreshToken: keepCreds ? opts.appUserRefreshToken : undefined,
             context: opts.context,
             platformConsole: opts.platformConsole,
             projectId: opts.projectId,
@@ -159,7 +189,7 @@ class XCiteDBClient {
             onAppUserTokensUpdated: opts.onAppUserTokensUpdated,
             onSessionInvalid: opts.onSessionInvalid,
             testSessionToken: data.session_token,
-            testRequireAuth: opts.testRequireAuth,
+            testAuth: mode,
             userIsolation: opts.userIsolation,
             requestTimeoutMs: opts.requestTimeoutMs,
         });
@@ -536,8 +566,10 @@ class XCiteDBClient {
         const h = {};
         if (this.testSessionToken) {
             h['X-Test-Session'] = this.testSessionToken;
-            if (this.testRequireAuth) {
-                h['X-Test-Auth'] = 'required';
+            // 'required' / 'preserve' send the header; 'bypass' (or undefined) omits it so the server
+            // applies the legacy synthesized-admin behavior.
+            if (this.testAuthMode === 'required' || this.testAuthMode === 'preserve') {
+                h['X-Test-Auth'] = this.testAuthMode;
             }
         }
         return h;
@@ -868,7 +900,17 @@ class XCiteDBClient {
         await this.request('DELETE', `/api/v1/project/keys/${encodeURIComponent(keyId)}`);
     }
     // --- App user auth (requires developer API key or JWT on the same tenant) ---
+    /**
+     * Self-register an app user. Public endpoint — set `context.project_id` on the client first.
+     *
+     * **Side effect:** clears any cached `appUserAccessToken` / `appUserRefreshToken` before the
+     * request. Without this, a previously logged-in client would send `Authorization: Bearer
+     * <stale-token>`, which the server (correctly) rejects with `reason: "already_authenticated"`.
+     * The clear runs before the request fires, so even a 4xx response leaves the client in a clean
+     * unauthenticated state — a fresh `loginAppUser` call works without manual `clearAppUserTokens`.
+     */
     async registerAppUser(email, password, displayName, attributes) {
+        this.clearAppUserTokens();
         const body = { email, password };
         if (displayName !== undefined)
             body.display_name = displayName;
@@ -887,15 +929,30 @@ class XCiteDBClient {
         const tid = raw && String(raw).length > 0 ? String(raw) : 'default';
         return `/api/v1/app/auth/oauth/${encodeURIComponent(provider)}/authorize${buildQuery({ tenant_id: tid })}`;
     }
-    /** Exchange one-time session code from OAuth browser redirect (public + tenant_id). */
+    /**
+     * Exchange one-time session code from OAuth browser redirect (public + tenant_id).
+     * Clears any cached app-user tokens before the request — see `loginAppUser` for rationale.
+     */
     async exchangeOAuthCode(code) {
+        this.clearAppUserTokens();
         const pair = await this.request('POST', '/api/v1/app/auth/oauth/exchange', this.mergeAppTenant({ code }));
         this.appUserAccessToken = pair.access_token;
         this.appUserRefreshToken = pair.refresh_token;
         this.cacheAppUserIdFromPair(pair);
         return pair;
     }
+    /**
+     * Sign in as an app user and **store** the issued access/refresh tokens on this client. Subsequent
+     * requests automatically send `Authorization: Bearer <access>` (or `X-App-User-Token` when paired
+     * with a developer key/JWT). Call `clearAppUserTokens()` (or `logoutAppUser()`) to drop them.
+     *
+     * **Side effect:** clears any cached `appUserAccessToken` / `appUserRefreshToken` before the
+     * request. Without this, a previously logged-in client would send `Authorization: Bearer
+     * <stale-token>` and the server would reject with `reason: "already_authenticated"`. The clear
+     * runs before the request fires, so re-logging in as a different user just works.
+     */
     async loginAppUser(email, password) {
+        this.clearAppUserTokens();
         const pair = await this.request('POST', '/api/v1/app/auth/login', this.mergeAppTenant({ email, password }));
         this.appUserAccessToken = pair.access_token;
         this.appUserRefreshToken = pair.refresh_token;
@@ -922,7 +979,12 @@ class XCiteDBClient {
             body.attributes = attributes;
         return this.request('PUT', '/api/v1/app/auth/me', body);
     }
+    /**
+     * Exchange a custom JWT for an app-user session.
+     * Clears any cached app-user tokens before the request — see `loginAppUser` for rationale.
+     */
     async exchangeCustomToken(token) {
+        this.clearAppUserTokens();
         const pair = await this.request('POST', '/api/v1/app/auth/custom-token', { token });
         this.appUserAccessToken = pair.access_token;
         this.appUserRefreshToken = pair.refresh_token;
@@ -953,6 +1015,26 @@ class XCiteDBClient {
     async getAppAuthConfig() {
         return this.request('GET', '/api/v1/app/auth/config');
     }
+    /**
+     * Patch `auth.app_users.*` (PUT /api/v1/app/auth/config). Requires admin developer auth.
+     *
+     * Whitelisted keys: `enabled`, `registration_enabled`, `default_groups`,
+     * `require_email_verification`, `min_password_length`, `max_login_attempts`,
+     * `lockout_duration_seconds`, `access_token_expiry_seconds`, `refresh_token_expiry_seconds`,
+     * `reset_token_expiry_seconds`, `verification_token_expiry_seconds`, `public_base_url`.
+     *
+     * Secret-bearing fields (`jwt_secret`, `signing_key_path`, `custom_token_secret`,
+     * `oauth_providers`) are intentionally not patchable here — set them in server config and reload.
+     * Returns the full effective config including any `warnings`.
+     *
+     * @example Bootstrap a fresh project so registered users land in the editor group:
+     * ```ts
+     * await client.updateAppAuthConfig({ default_groups: ['editor'] });
+     * ```
+     */
+    async updateAppAuthConfig(patch) {
+        return this.request('PUT', '/api/v1/app/auth/config', patch);
+    }
     async getEmailConfig() {
         return this.request('GET', '/api/v1/app/email/config');
     }
@@ -1176,6 +1258,14 @@ class XCiteDBClient {
     async getUserIsolationConfig() {
         return this.request('GET', '/api/v1/security/user-isolation');
     }
+    /**
+     * Public-read sibling (`GET /api/v1/security/user-isolation/public`). Returns only the
+     * client-prefix-relevant fields (enabled, namespace_pattern, shared_*_paths). Lets SPAs
+     * configure isolation without admin auth.
+     */
+    async getUserIsolationConfigPublic() {
+        return this.request('GET', '/api/v1/security/user-isolation/public');
+    }
     /** Enable or reconfigure user isolation (`PUT /api/v1/security/user-isolation`). */
     async setUserIsolationConfig(config) {
         return this.request('PUT', '/api/v1/security/user-isolation', config);
@@ -1185,11 +1275,43 @@ class XCiteDBClient {
         await this.request('DELETE', '/api/v1/security/user-isolation');
     }
     /**
-     * Loads server isolation config; when enabled, configures client-side identifier prefixing to match
-     * the server (namespace + shared paths). Does not send `X-Prefix`; identifiers in requests are rewritten.
+     * Configure client-side identifier prefixing to match server-side user isolation. Does not send
+     * `X-Prefix`; identifiers in requests are rewritten by the SDK.
+     *
+     * Two forms:
+     * 1. **No-arg**: fetches the public read-only endpoint (`/api/v1/security/user-isolation/public`),
+     *    falling back to the admin endpoint on 404 (older servers). No admin auth needed in SPAs.
+     * 2. **Explicit config**: pass `{ namespace, shared_read_paths?, shared_write_paths? }` to skip
+     *    the network round-trip entirely. Useful when the BFF already knows the configuration.
      */
-    async enableUserIsolation() {
-        const cfg = await this.getUserIsolationConfig();
+    async enableUserIsolation(config) {
+        if (config && config.namespace) {
+            this.userIsolation = {
+                enabled: true,
+                namespace: config.namespace,
+                shared_read_paths: config.shared_read_paths,
+                shared_write_paths: config.shared_write_paths,
+            };
+            return {
+                enabled: true,
+                namespace_pattern: config.namespace,
+                shared_read_paths: config.shared_read_paths ?? [],
+                shared_write_paths: config.shared_write_paths ?? [],
+            };
+        }
+        let cfg;
+        try {
+            cfg = await this.getUserIsolationConfigPublic();
+        }
+        catch (err) {
+            // Older servers don't expose the public endpoint — try the admin one.
+            if (err instanceof types_1.XCiteDBError && err.status === 404) {
+                cfg = await this.getUserIsolationConfig();
+            }
+            else {
+                throw err;
+            }
+        }
         if (cfg.enabled) {
             this.userIsolation = {
                 enabled: true,
@@ -1444,6 +1566,30 @@ class XCiteDBClient {
         }
         return this.compare(from, to, third);
     }
+    /**
+     * Compare two XML provision trees structurally + textually and write the resulting
+     * diff document — annotated with `<ins>`, `<del>`, `<moved-to>`, `<moved-from>` and
+     * `diff:<key>` metadata attributes — to the target location.
+     *
+     * The output document carries `diff:document="true"` on its root. If the target
+     * identifier already holds a regular (non-diff) document, the call returns 409
+     * `target_not_smart_diff`; existing smart-diff documents are silently overwritten.
+     */
+    async smartDiff(from, to, target, metadata = {}, options = {}) {
+        const body = {
+            from,
+            to,
+            target,
+            metadata,
+            options: {
+                diff_text: options.diffText,
+                exclude_tags: options.excludeTags,
+                max_text_diff_bytes: options.maxTextDiffBytes,
+                max_source_bytes: options.maxSourceBytes,
+            },
+        };
+        return this.request('POST', '/api/v1/smart-diff', body);
+    }
     async publishWorkspace(targetWorkspace, sourceWorkspace, options) {
         const body = {
             source_workspace: sourceWorkspace,

package/dist/client.test.js

@@ -89,3 +89,299 @@ const types_js_1 = require("./types.js");
         }
     });
 });
+(0, node_test_1.describe)('app-user auth flows clear tokens before request', () => {
+    // The bug: a previously-logged-in client sent Authorization: Bearer <stale-token> on
+    // /app/auth/login, and the server (correctly) 403'd it as already_authenticated.
+    // SDK fix: each of login/register/oauth-exchange/custom-token clears tokens FIRST so the
+    // request goes out unauthenticated. These tests freeze that contract.
+    async function runWithMockedFetch(cb, response) {
+        const requests = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input, init) => {
+            requests.push({ url: String(input), headers: new Headers(init?.headers) });
+            return response();
+        });
+        try {
+            await cb(() => null);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+        return { requests };
+    }
+    (0, node_test_1.it)('loginAppUser drops a stale Authorization: Bearer before the request', async () => {
+        const { requests } = await runWithMockedFetch(async () => {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                // No apiKey/accessToken — the only credential is the stale app-user token below.
+                appUserAccessToken: 'stale-jwt-from-previous-login',
+                context: { project_id: 't1' },
+            });
+            await c.loginAppUser('alice@example.com', 'pw');
+        }, () => new Response(JSON.stringify({ access_token: 'new-jwt', refresh_token: 'new-refresh', expires_in: 3600 }), { status: 200 }));
+        strict_1.default.equal(requests.length, 1);
+        strict_1.default.equal(requests[0].headers.get('Authorization'), null, 'login request must not carry the stale Bearer; otherwise server rejects with already_authenticated');
+        strict_1.default.equal(requests[0].headers.get('X-App-User-Token'), null);
+    });
+    (0, node_test_1.it)('registerAppUser drops stale tokens before the request', async () => {
+        const { requests } = await runWithMockedFetch(async () => {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                appUserAccessToken: 'stale-jwt',
+                appUserRefreshToken: 'stale-refresh',
+                context: { project_id: 't1' },
+            });
+            await c.registerAppUser('bob@example.com', 'pw');
+        }, () => new Response(JSON.stringify({ user_id: 'u-bob', email: 'bob@example.com' }), { status: 201 }));
+        strict_1.default.equal(requests[0].headers.get('Authorization'), null);
+    });
+    (0, node_test_1.it)('exchangeOAuthCode drops stale tokens before the request', async () => {
+        const { requests } = await runWithMockedFetch(async () => {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                appUserAccessToken: 'stale-jwt',
+                context: { project_id: 't1' },
+            });
+            await c.exchangeOAuthCode('one-time-code');
+        }, () => new Response(JSON.stringify({ access_token: 'new', refresh_token: 'r', expires_in: 3600 }), { status: 200 }));
+        strict_1.default.equal(requests[0].headers.get('Authorization'), null);
+    });
+    (0, node_test_1.it)('exchangeCustomToken drops stale tokens before the request', async () => {
+        const { requests } = await runWithMockedFetch(async () => {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                appUserAccessToken: 'stale-jwt',
+                // Mixed with an apiKey so the request would otherwise carry both.
+                apiKey: 'pub-key',
+            });
+            await c.exchangeCustomToken('outside-jwt');
+        }, () => new Response(JSON.stringify({ access_token: 'new', refresh_token: 'r', expires_in: 3600 }), { status: 200 }));
+        // X-API-Key is still allowed; X-App-User-Token must be gone.
+        strict_1.default.equal(requests[0].headers.get('X-API-Key'), 'pub-key');
+        strict_1.default.equal(requests[0].headers.get('X-App-User-Token'), null);
+    });
+    (0, node_test_1.it)('loginAppUser stores the new tokens on success', async () => {
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async () => new Response(JSON.stringify({ access_token: 'new-jwt', refresh_token: 'new-refresh', expires_in: 3600 }), { status: 200 }));
+        try {
+            const c = new client_js_1.XCiteDBClient({
+                baseUrl: 'http://127.0.0.1:9',
+                context: { project_id: 't1' },
+            });
+            const pair = await c.loginAppUser('alice', 'pw');
+            strict_1.default.equal(pair.access_token, 'new-jwt');
+            // Side effect: token is cached for subsequent requests.
+            let captured = null;
+            globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+                captured = new Headers(init?.headers);
+                return new Response(JSON.stringify({}), { status: 200 });
+            });
+            await c.appUserMe();
+            strict_1.default.equal(captured.get('Authorization'), 'Bearer new-jwt');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
+(0, node_test_1.describe)('updateAppAuthConfig', () => {
+    (0, node_test_1.it)('PUTs the patch and returns the effective config', async () => {
+        let capturedMethod = '';
+        let capturedBody = '';
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            capturedMethod = String(init?.method ?? 'GET');
+            capturedBody = String(init?.body ?? '');
+            return new Response(JSON.stringify({
+                enabled: true,
+                registration_enabled: true,
+                default_groups: ['editor'],
+                warnings: [],
+            }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'admin-key' });
+            const cfg = await c.updateAppAuthConfig({ default_groups: ['editor'] });
+            strict_1.default.equal(capturedMethod, 'PUT');
+            strict_1.default.match(capturedBody, /"default_groups":\["editor"\]/);
+            strict_1.default.deepEqual(cfg.default_groups, ['editor']);
+            strict_1.default.deepEqual(cfg.warnings, []);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('getAppAuthConfig surfaces default_groups_empty warning when present', async () => {
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async () => new Response(JSON.stringify({
+            enabled: true,
+            registration_enabled: true,
+            default_groups: [],
+            warnings: ['default_groups_empty'],
+        }), { status: 200 }));
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'admin-key' });
+            const cfg = await c.getAppAuthConfig();
+            strict_1.default.deepEqual(cfg.warnings, ['default_groups_empty']);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});
+(0, node_test_1.describe)('createTestSession testAuth modes', () => {
+    // The legacy bypass mode lets tests pass while the matching production code path can't
+    // possibly succeed (public-key context erased). The SDK now defaults to 'required' so
+    // wet tests are production-faithful by default. These tests freeze the resolution rules.
+    function mockSessionCreate() {
+        return node_test_1.mock.fn(async () => new Response(JSON.stringify({
+            session_token: 'tok-123',
+            expires_at: Date.now() + 60000,
+            session_ttl_seconds: 60,
+        }), { status: 201 }));
+    }
+    async function captureHeadersFromFollowupRequest(create) {
+        const orig = globalThis.fetch;
+        globalThis.fetch = mockSessionCreate();
+        let client;
+        try {
+            client = await create();
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+        let captured = null;
+        const orig2 = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (_i, init) => {
+            captured = new Headers(init?.headers);
+            return new Response(JSON.stringify({}), { status: 200 });
+        });
+        try {
+            await client.health();
+        }
+        finally {
+            globalThis.fetch = orig2;
+        }
+        return captured;
+    }
+    (0, node_test_1.it)('default sends X-Test-Auth: required and keeps credentials', async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({ baseUrl: 'http://127.0.0.1:9', apiKey: 'k' }));
+        strict_1.default.equal(h.get('X-Test-Auth'), 'required');
+        strict_1.default.equal(h.get('X-Test-Session'), 'tok-123');
+        strict_1.default.equal(h.get('X-API-Key'), 'k', 'creds preserved in required mode');
+    });
+    (0, node_test_1.it)("testAuth: 'preserve' sends X-Test-Auth: preserve and keeps credentials", async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            testAuth: 'preserve',
+        }));
+        strict_1.default.equal(h.get('X-Test-Auth'), 'preserve');
+        strict_1.default.equal(h.get('X-API-Key'), 'k');
+    });
+    (0, node_test_1.it)("testAuth: 'bypass' omits X-Test-Auth and drops credentials", async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            testAuth: 'bypass',
+        }));
+        strict_1.default.equal(h.get('X-Test-Auth'), null);
+        strict_1.default.equal(h.get('X-API-Key'), null, 'bypass drops creds — server synthesizes admin');
+    });
+    (0, node_test_1.it)('legacy testRequireAuth: false maps to bypass', async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            testRequireAuth: false,
+        }));
+        strict_1.default.equal(h.get('X-Test-Auth'), null);
+        strict_1.default.equal(h.get('X-API-Key'), null);
+    });
+    (0, node_test_1.it)('legacy testRequireAuth: true maps to required', async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            testRequireAuth: true,
+        }));
+        strict_1.default.equal(h.get('X-Test-Auth'), 'required');
+        strict_1.default.equal(h.get('X-API-Key'), 'k');
+    });
+    (0, node_test_1.it)('explicit testAuth wins over legacy testRequireAuth', async () => {
+        const h = await captureHeadersFromFollowupRequest(() => client_js_1.XCiteDBClient.createTestSession({
+            baseUrl: 'http://127.0.0.1:9',
+            apiKey: 'k',
+            testAuth: 'preserve',
+            testRequireAuth: false,
+        }));
+        strict_1.default.equal(h.get('X-Test-Auth'), 'preserve');
+    });
+});
+(0, node_test_1.describe)('enableUserIsolation', () => {
+    (0, node_test_1.it)('with explicit config, configures prefixing without any HTTP call', async () => {
+        let calls = 0;
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async () => {
+            calls += 1;
+            return new Response('{}', { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9' });
+            const cfg = await c.enableUserIsolation({ namespace: '/users/{userId}' });
+            strict_1.default.equal(calls, 0, 'explicit config skips the network round-trip');
+            strict_1.default.equal(cfg.enabled, true);
+            strict_1.default.equal(cfg.namespace_pattern, '/users/{userId}');
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('no-arg form prefers the public endpoint', async () => {
+        let lastPath = '';
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            lastPath = String(input);
+            return new Response(JSON.stringify({
+                enabled: true,
+                namespace_pattern: '/users/${user.id}',
+                shared_read_paths: [],
+                shared_write_paths: [],
+            }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'public-key' });
+            await c.enableUserIsolation();
+            strict_1.default.match(lastPath, /\/api\/v1\/security\/user-isolation\/public$/);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+    (0, node_test_1.it)('falls back to admin endpoint when public 404s (older servers)', async () => {
+        const calls = [];
+        const orig = globalThis.fetch;
+        globalThis.fetch = node_test_1.mock.fn(async (input) => {
+            const url = String(input);
+            calls.push(url);
+            if (url.endsWith('/public')) {
+                return new Response(JSON.stringify({ message: 'Not found' }), { status: 404 });
+            }
+            return new Response(JSON.stringify({
+                enabled: true,
+                namespace_pattern: '/spaces/${user.id}',
+                shared_read_paths: ['/public'],
+                shared_write_paths: [],
+            }), { status: 200 });
+        });
+        try {
+            const c = new client_js_1.XCiteDBClient({ baseUrl: 'http://127.0.0.1:9', apiKey: 'admin-key' });
+            const cfg = await c.enableUserIsolation();
+            strict_1.default.equal(calls.length, 2);
+            strict_1.default.match(calls[0], /\/public$/);
+            strict_1.default.ok(!calls[1].endsWith('/public'));
+            strict_1.default.deepEqual(cfg.shared_read_paths, ['/public']);
+        }
+        finally {
+            globalThis.fetch = orig;
+        }
+    });
+});

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { XCiteDBClient } from './client';
 export { parseAssetUri, formatAssetUri, collectIdentifiersFromText, ASSET_URI_PREFIX } from './assetUri';
 export { WebSocketSubscription } from './websocket';
-export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, SmartDiffStats, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError, XCiteDBForbiddenError, XCiteDBNotFoundError, XCiteDBAuthError, XCiteDBLockConflictError, } from './types';

package/dist/types.d.ts

@@ -676,7 +676,16 @@ export interface XCiteDBClientOptions {
      * Sends `X-Test-Session`; use with {@link XCiteDBClient.createTestSession}.
      */
     testSessionToken?: string;
-    /** When true with `testSessionToken`, sends `X-Test-Auth: required` so real credentials are validated. */
+    /**
+     * Test-session auth fidelity. `'required'` / `'preserve'` send `X-Test-Auth: <mode>`;
+     * `'bypass'` omits the header (server synthesizes a developer-admin identity). See
+     * {@link CreateTestSessionOptions.testAuth} for guidance on which to pick.
+     */
+    testAuth?: 'required' | 'preserve' | 'bypass';
+    /**
+     * @deprecated Use `testAuth`.
+     * `true` ↔ `testAuth: 'required'`; `false` ↔ `testAuth: 'bypass'`.
+     */
     testRequireAuth?: boolean;
     /** Auto-prefix identifiers for app-user sessions (see {@link UserIsolationOptions}). */
     userIsolation?: UserIsolationOptions;
@@ -730,7 +739,24 @@ export interface CreateTestSessionOptions {
     overlay?: boolean;
     /** Optional server-side bootstrap (user isolation, developer_bypass, policies). */
     bootstrap?: TestSessionBootstrap;
-    /** Keep `apiKey` / `accessToken` on the client and send `X-Test-Auth: required` on each request. */
+    /**
+     * Test-session auth fidelity mode (`X-Test-Auth` header on the returned client).
+     *
+     * - `'required'` (**SDK default**) — auth runs normally; ABAC default-deny applies until you bootstrap policies.
+     *   Tests that exercise role/credential checks (public-key denials, etc.) work as in production.
+     * - `'preserve'` — auth runs normally, but ABAC defaults to allow inside the test tenant when no
+     *   policies are configured. Use when you want production-faithful auth without writing ABAC policies.
+     * - `'bypass'` — server synthesizes a developer-admin identity. Erases the public-key context entirely;
+     *   tests that depend on auth/role failures will pass under bypass and fail in production. Avoid.
+     *
+     * @default 'required'
+     */
+    testAuth?: 'required' | 'preserve' | 'bypass';
+    /**
+     * @deprecated Use `testAuth: 'required'` (or omit for the SDK default).
+     * Setting `testRequireAuth: false` explicitly opts into legacy bypass mode (`testAuth: 'bypass'`).
+     * Setting `true` is equivalent to `testAuth: 'required'`.
+     */
     testRequireAuth?: boolean;
     onSessionTokensUpdated?: (pair: TokenPair) => void;
     onAppUserTokensUpdated?: (pair: AppUserTokenPair) => void;
@@ -763,7 +789,10 @@ export interface OAuthProviderInfo {
 export interface OAuthProvidersResponse {
     providers: OAuthProviderInfo[];
 }
-/** Read-only effective `auth.app_users` (GET /api/v1/app/auth/config). */
+/**
+ * Effective `auth.app_users` (GET /api/v1/app/auth/config). Mutable subset is patchable
+ * via `updateAppAuthConfig` — see that method's JSDoc for which keys are accepted.
+ */
 export interface AppAuthConfig {
     enabled: boolean;
     registration_enabled: boolean;
@@ -778,6 +807,12 @@ export interface AppAuthConfig {
     verification_token_expiry_seconds: number;
     jwt_algorithm: string;
     public_base_url: string;
+    /**
+     * Bootstrap warnings the operator should act on. Today: `"default_groups_empty"` when
+     * `registration_enabled: true` is paired with an empty `default_groups` (self-registered users
+     * authenticate but cannot perform writes). The BFF / app shell should surface these at startup.
+     */
+    warnings?: string[];
 }
 export interface AppEmailSmtpConfig {
     host: string;
@@ -1022,6 +1057,35 @@ export interface CompareResult {
 }
 /** @deprecated Use {@link CompareResult}. */
 export type DiffResult = CompareResult;
+/**
+ * Reference to a single document version in a workspace/branch — used by `smartDiff()`
+ * to address Source A, Source B, and the Target. Supports `branch`+`date` (or `date_key`)
+ * or a `checkpoint_id`.
+ */
+export interface SmartDiffRef {
+    /** Identifier of the document or subtree. Required. */
+    identifier: string;
+    branch?: string;
+    date?: string;
+    date_key?: string;
+    checkpoint_id?: string;
+}
+export interface SmartDiffStats {
+    matched: number;
+    ins: number;
+    del: number;
+    moved_parent: number;
+    moved_order: number;
+}
+export interface SmartDiffResult {
+    status: 'ok';
+    target: {
+        identifier: string;
+        branch: string;
+        date: string;
+    };
+    stats: SmartDiffStats;
+}
 export interface PublishConflict {
     identifier: string;
     source_action: string;
@@ -1051,8 +1115,16 @@ export interface RebaseUserWorkspaceResult {
     auto_mergeable?: string[];
     would_expose?: string[];
 }
+/**
+ * Canonical 403 `reason` codes the server can emit. Use as a discriminator on
+ * `XCiteDBForbiddenError.reason` in catch sites — TypeScript will warn if you forget a case.
+ *
+ * The trailing `(string & {})` keeps the type open to forward-compatible reasons added by newer
+ * servers without forcing a SDK bump on every new code.
+ */
+export type XCiteDBForbiddenReason = 'role_forbidden_public_key' | 'role_forbidden_not_admin' | 'role_forbidden_not_admin_or_editor' | 'role_forbidden_app_user_no_admin' | 'role_forbidden_viewer' | 'role_forbidden' | 'auth_admin_required' | 'auth_developer_required' | 'auth_app_user_required' | 'auth_app_user_or_developer_required' | 'auth_admin_or_app_user_required' | 'auth_developer_or_anonymous_required' | 'auth_developer_or_app_user_required' | 'auth_site_admin_required' | 'auth_platform_required' | 'auth_platform_console_required' | 'auth_project_member_required' | 'auth_project_admin_required' | 'auth_org_admin_required' | 'auth_org_member_required' | 'auth_missing' | 'already_authenticated' | 'registration_disabled' | 'system_tenant_register_forbidden' | 'system_tenant_login_forbidden' | 'system_tenant_refresh_forbidden' | 'forgot_password_self_forbidden' | 'account_pending_approval' | 'email_verification_required' | 'abac_default_deny' | 'abac_explicit_deny' | 'abac_reserved_namespace' | 'tenant_security_unconfigured' | 'user_workspace_forbidden' | 'user_workspace_requires_app_user' | 'user_workspaces_app_user_only' | 'user_workspaces_create_app_user_only' | 'share_invalid_user_id' | 'share_invalid_identifier' | 'share_outside_namespace' | 'share_group_not_owner' | 'share_group_admin_only' | 'magic_link_not_authorized' | 'magic_link_not_owner' | 'magic_link_session_forbidden' | 'magic_link_forbidden' | 'reserved_namespace' | 'xml_path_policy_redacted_all' | 'test_session_not_owned' | 'ip_access_denied' | 'cluster_secret_invalid' | 'tenant_not_active' | 'org_not_active' | 'org_create_not_allowed' | 'org_project_limit_reached' | (string & {});
 export type XCiteDBErrorExtras = {
-    reason?: string;
+    reason?: XCiteDBForbiddenReason;
     policyId?: string;
     hint?: string;
     expectedRole?: string;
@@ -1063,7 +1135,7 @@ export type XCiteDBErrorExtras = {
 export declare class XCiteDBError extends Error {
     readonly status: number;
     readonly body?: unknown | undefined;
-    reason?: string;
+    reason?: XCiteDBForbiddenReason;
     policyId?: string;
     hint?: string;
     expectedRole?: string;

package/llms-full.txt

@@ -61,7 +61,7 @@ Legacy REST paths under `/api/v1/branches`, `/commits`, `/tags`, `/diff` remain
 
 5. **`context.project_id` (or `tenant_id`) is required for app-user self-registration.** `registerAppUser()` uses `mergeAppTenant(body)` to add `tenant_id` to the JSON body only when `context.project_id` or `context.tenant_id` is set. If both are omitted, the server cannot determine which project to register the user in. Always set `project_id` in the constructor `context` when calling `registerAppUser`, `loginAppUser`, and other public app-auth methods.
 
-6. **Self-registration uses server-configured default groups.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. To assign specific groups, use the admin endpoint `createAppUser()` instead, or update groups after registration via `updateAppUserGroups()`.
+6. **Self-registration uses server-configured default groups — set them before opening registration.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. With `default_groups: []` paired with `registration_enabled: true`, registered users authenticate but have no role groups and **cannot perform writes** (the failure is silent — every write returns 403 `role_forbidden_app_user_no_admin`). Set via `updateAppAuthConfig({ default_groups: ["editor"] })` (`PUT /api/v1/app/auth/config`, admin-gated) or via the platform console. `getAppAuthConfig()` includes `warnings: ["default_groups_empty"]` when this combination is detected; surface it at BFF startup so DB-reset bootstrap doesn't silently no-op. To assign specific groups outside the default, use the admin endpoint `createAppUser()` or `updateAppUserGroups()` after registration.
 
 7. **Do not mock XciteDB in tests — use ephemeral test sessions instead.** Unlike most BaaS platforms, XciteDB has built-in support for isolated, throwaway database sessions specifically designed for wet integration tests. Mocking the client skips the actual storage, versioning, querying, and ABAC behavior, producing tests that don't catch real integration issues. Use `createTestSession()` / `test_session()` / `create_test_session()` (SDK helpers) or `POST /api/v1/test/sessions` directly to get a real LMDB under `_test/<uuid>/` (empty by default, or **overlay** on read-only production with **`{"overlay":true}`** / **`overlay: true`** / **`test_session_overlay`**). See "Ephemeral test sessions" below.
 
@@ -227,16 +227,18 @@ For **integration and wet tests** against a shared BaaS host without touching pr
 |------|------------|
 | **Create** | **`POST /api/v1/test/sessions`** with normal **`Authorization: Bearer …`** or **`X-API-Key`**. Response includes **`session_token`** (UUID), **`tenant_id`** (the session's logical tenant id, formatted as `xcitedbtest-<session_token>` — useful for ABAC group strings like `project:<tenant_id>:editor`), `expires_at`, and `session_ttl_seconds`. Server enforces per-credential limits (`test.max_sessions_per_key`, `test.session_ttl_seconds`, `test.max_test_db_size_bytes` in server config). Optional JSON body **`{"overlay":true}`** provisions a **read-through production** session (writable delta only under `_test/<uuid>/`; production LMDB is read-only base). |
 | **Use** | Send **`X-Test-Session: <session_token>`** on document and other data API requests. The server routes to a dedicated LMDB under its data root (`_test/<id>/`), not the caller’s production tenant. **`tenant_id` / `X-Project-Id` semantics do not select production** while the test header is present—the synthetic test tenant is implied. |
-| **Auth** | **Default:** developer auth (API key / platform JWT) is **bypassed** with a synthetic admin identity. However, **app-user identity is still recognized**: if `X-App-User-Token` or a Bearer app-user JWT is present, the request runs as that app user (for routes like `/app/auth/me`). **`X-Test-Auth: required`:** all auth is validated normally; ABAC applies, but data still comes from the test session DB. |
+| **Auth** | Three modes via the **`X-Test-Auth`** header. **`required`** (SDK default as of this release): all auth is validated normally; ABAC applies, so role/credential checks (e.g. public-key on admin-write controllers → 403 `role_forbidden_public_key`) fire as in production. **`preserve`**: auth runs normally, but ABAC defaults to **allow** when the test tenant has no policies — production-faithful auth without forcing a policy bootstrap. **Header omitted** (legacy bypass): server synthesizes a developer-admin identity (`auth_user_type=member, role=admin`) and **erases the public-key context entirely** — tests that exercise auth/role failures will pass under bypass and fail in production. **App-user identity is still recognized in every mode**: if `X-App-User-Token` or a Bearer app-user JWT is present, the request runs as that app user (for routes like `/app/auth/me`). |
 | **Manage** | **`GET /api/v1/test/sessions`** — list sessions for the current credential. **`DELETE /api/v1/test/sessions/current`** — destroy the session named by **`X-Test-Session`** (no other auth). **`DELETE /api/v1/test/sessions/all`** — destroy all sessions for the credential. **`DELETE /api/v1/test/sessions/{token}`** — destroy one session if owned by the credential. Do **not** send **`X-Test-Session`** on these `/api/v1/test/*` routes. **SDKs:** JS `listTestSessions` / `destroyAllTestSessions` / `destroyTestSessionByToken`; Python `list_test_sessions` / `destroy_all_test_sessions` / `destroy_test_session_by_token`; C++ same snake_case; MCP tools `list_test_sessions`, `destroy_all_test_sessions`, `destroy_test_session_by_token`. |
 | **429 / suites** | Per-credential concurrent cap (default **5**, `test.max_sessions_per_key`). If **`createTestSession`** returns **429**, call **`destroyAllTestSessions`** (same API key / Bearer, no `X-Test-Session`) before retrying — typical **once in `beforeAll`** for large wet suites. |
 | **CORS** | Browsers may need **`X-Test-Session`** and **`X-Test-Auth`** in the deployment’s allowed CORS headers (defaults include them). |
 
 **SDK usage (summary):**
 
-- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, …, bootstrap })` returns a client configured with `testSessionToken`; optional **`overlay: true`** for overlay mode; optional `testRequireAuth: true` maps to `X-Test-Auth: required`; optional **`bootstrap`** (`user_isolation`, `developer_bypass`, `policies`); read **`lastTestSessionBootstrap`** on the returned client when the server included a summary. `destroyTestSession()` calls `DELETE …/test/sessions/current`. On a **normal** client (same `apiKey` / Bearer, **no** `testSessionToken`), **`listTestSessions()`**, **`destroyAllTestSessions()`**, **`destroyTestSessionByToken(token)`** wrap the management routes (they never send `X-Test-Session`).
-- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …, bootstrap={…})` provisions and tears down; or **`POST /api/v1/test/sessions`** with JSON **`{"overlay":true}`**, **`bootstrap`**, or both, then construct the client with the returned token; **`client.last_test_session_bootstrap`** mirrors the server summary. Management: **`await client.list_test_sessions()`**, **`await client.destroy_all_test_sessions()`**, **`await client.destroy_test_session_by_token(token)`** with `suppress_test_session` behavior (omit `X-Test-Session` on those paths).
-- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key`, optional **`test_session_overlay`**, optional **`test_session_bootstrap`** on `XCiteDBClientOptions`, optional `test_require_auth`; **`last_test_session_bootstrap()`** on the returned client; `destroy_test_session()`. Management: **`list_test_sessions()`**, **`destroy_all_test_sessions()`**, **`destroy_test_session_by_token(token)`** on a client carrying the provisioning credential only.
+- **JavaScript/TypeScript:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, …, bootstrap })` returns a client configured with `testSessionToken`; optional **`overlay: true`** for overlay mode; **`testAuth: 'required' | 'preserve' | 'bypass'`** (default **`'required'`**); legacy **`testRequireAuth`** still accepted (`true` ↔ `'required'`, `false` ↔ `'bypass'`); optional **`bootstrap`** (`user_isolation`, `developer_bypass`, `policies`); read **`lastTestSessionBootstrap`** on the returned client when the server included a summary. `destroyTestSession()` calls `DELETE …/test/sessions/current`. On a **normal** client (same `apiKey` / Bearer, **no** `testSessionToken`), **`listTestSessions()`**, **`destroyAllTestSessions()`**, **`destroyTestSessionByToken(token)`** wrap the management routes (they never send `X-Test-Session`).
+- **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …, bootstrap={…})` provisions and tears down; default `test_auth="required"`; pass **`test_auth="preserve"`** for real auth + lenient ABAC, **`test_auth="bypass"`** for legacy synthesized-admin. Or **`POST /api/v1/test/sessions`** with JSON **`{"overlay":true}`**, **`bootstrap`**, or both, then construct the client with the returned token; **`client.last_test_session_bootstrap`** mirrors the server summary. Management: **`await client.list_test_sessions()`**, **`await client.destroy_all_test_sessions()`**, **`await client.destroy_test_session_by_token(token)`** with `suppress_test_session` behavior (omit `X-Test-Session` on those paths).
+- **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key`, optional **`test_session_overlay`**, optional **`test_session_bootstrap`** on `XCiteDBClientOptions`, optional **`test_auth`** (`"required"`/`"preserve"`/`"bypass"`; default `"required"`) or legacy `test_require_auth`; **`last_test_session_bootstrap()`** on the returned client; `destroy_test_session()`. Management: **`list_test_sessions()`**, **`destroy_all_test_sessions()`**, **`destroy_test_session_by_token(token)`** on a client carrying the provisioning credential only.
+
+> **Test fidelity warning.** The legacy bypass mode (omit `X-Test-Auth`) erases public-key context entirely — `isPublicKeyContext()` returns false for every request, so role gates that reject public keys silently pass in tests and fail in production. The SDK helpers default to `'required'` as of this release; explicitly opt into `'bypass'` only when you've verified the test does not depend on auth/role behavior. Use `'preserve'` to get production-faithful auth without writing ABAC policies for the test tenant.
 
 **A fresh test session is an empty tenant with zero policies.** With `X-Test-Auth: required`, ABAC default-deny applies until you bootstrap user isolation and/or policies. Typical `POST /api/v1/test/sessions` body:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.2.27",
+  "version": "0.3.1",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",