@xcitedbs/client 0.3.0 → 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;
@@ -502,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

@@ -1566,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

@@ -1057,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;

package/package.json

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