@xcitedbs/client 0.2.27 → 0.3.0

package/dist/client.d.ts

@@ -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.

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,

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;
@@ -1051,8 +1086,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 +1106,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.0",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",