@xcitedbs/client 0.2.7 → 0.2.9

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteQuery } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, CommitRecord, DatabaseContext, DiffRef, DiffResult, Flags, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, LogEntry, MergeResult, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, StoredPolicyResponse, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, XCiteQuery } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -22,6 +22,17 @@ export declare class XCiteDBClient {
      * then returns a client that sends `X-Test-Session` (auth-free by default).
      */
     static createTestSession(opts: CreateTestSessionOptions): Promise<XCiteDBClient>;
+    /**
+     * Canonical `project:<tenant_id>:<role>` group string. The middle segment must match the app JWT `tenant_id`
+     * (internal project id), not the human-readable project name.
+     */
+    static buildProjectGroup(projectId: string, role: 'admin' | 'editor' | 'viewer'): string;
+    private static decodeJwtPayloadJson;
+    /**
+     * Decode `appUserAccessToken`, or `accessToken` if no app token (platform JWT), without verifying the signature.
+     * Use for debugging ABAC (compare `tenant_id` and `groups` to `project:<…>:role` in policies).
+     */
+    getTokenClaims(): XCiteDBJwtClaims | null;
     /** Destroy this test session on the server (`DELETE /api/v1/test/sessions/current`). */
     destroyTestSession(): Promise<{
         message: string;

package/dist/client.js

@@ -69,6 +69,81 @@ class XCiteDBClient {
             testRequireAuth: opts.testRequireAuth,
         });
     }
+    /**
+     * Canonical `project:<tenant_id>:<role>` group string. The middle segment must match the app JWT `tenant_id`
+     * (internal project id), not the human-readable project name.
+     */
+    static buildProjectGroup(projectId, role) {
+        return `project:${projectId}:${role}`;
+    }
+    static decodeJwtPayloadJson(token) {
+        const parts = token.split('.');
+        if (parts.length < 2)
+            return null;
+        try {
+            let b64 = parts[1].replace(/-/g, '+').replace(/_/g, '/');
+            const pad = (4 - (b64.length % 4)) % 4;
+            b64 += '='.repeat(pad);
+            const g = globalThis;
+            let json = null;
+            if (g.Buffer) {
+                json = g.Buffer.from(b64, 'base64').toString('utf8');
+            }
+            else if (typeof atob === 'function') {
+                json = atob(b64);
+            }
+            if (json === null)
+                return null;
+            return JSON.parse(json);
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Decode `appUserAccessToken`, or `accessToken` if no app token (platform JWT), without verifying the signature.
+     * Use for debugging ABAC (compare `tenant_id` and `groups` to `project:<…>:role` in policies).
+     */
+    getTokenClaims() {
+        const raw = this.appUserAccessToken ?? this.accessToken;
+        if (!raw)
+            return null;
+        const p = XCiteDBClient.decodeJwtPayloadJson(raw);
+        if (!p)
+            return null;
+        let groups = [];
+        const g = p['groups'];
+        if (Array.isArray(g)) {
+            groups = g.filter((x) => typeof x === 'string');
+        }
+        else if (g && typeof g === 'object' && !Array.isArray(g)) {
+            groups = Object.keys(g);
+        }
+        else if (typeof g === 'string') {
+            groups = g.split(',').map((s) => s.trim()).filter(Boolean);
+        }
+        const sub = p['sub'];
+        const tenant_id = p['tenant_id'];
+        if (typeof sub !== 'string' || typeof tenant_id !== 'string')
+            return null;
+        const email = p['email'];
+        const type = p['type'];
+        const exp = p['exp'];
+        const iat = p['iat'];
+        const iss = p['iss'];
+        const jti = p['jti'];
+        return {
+            sub,
+            tenant_id,
+            groups,
+            email: typeof email === 'string' ? email : undefined,
+            type: typeof type === 'string' ? type : undefined,
+            exp: typeof exp === 'number' ? exp : undefined,
+            iat: typeof iat === 'number' ? iat : undefined,
+            iss: typeof iss === 'string' ? iss : undefined,
+            jti: typeof jti === 'string' ? jti : undefined,
+        };
+    }
     /** Destroy this test session on the server (`DELETE /api/v1/test/sessions/current`). */
     async destroyTestSession() {
         if (!this.testSessionToken) {

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { XCiteDBClient } from './client';
 export { WebSocketSubscription } from './websocket';
-export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, DatabaseContext, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, DatabaseContext, Flags, JsonDocumentData, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/types.d.ts

@@ -116,6 +116,21 @@ export interface ProjectInfo {
 }
 /** @deprecated Use {@link ProjectInfo}. */
 export type OwnedTenantInfo = ProjectInfo;
+/**
+ * Payload claims from an XCiteDB-issued access JWT (decode only; no signature verification).
+ * Prefer {@link XCiteDBClient.getTokenClaims} to compare `tenant_id` / `groups` with ABAC policies.
+ */
+export interface XCiteDBJwtClaims {
+    sub: string;
+    tenant_id: string;
+    groups: string[];
+    email?: string;
+    type?: string;
+    exp?: number;
+    iat?: number;
+    iss?: string;
+    jti?: string;
+}
 export interface UserInfo {
     user_id: string;
     username: string;

package/llms-full.txt

@@ -26,7 +26,7 @@ Before reading the full reference, note these critical differences from typical
 
 9. **OpenAPI:** See repository `docs/openapi.yaml` for a machine-readable route map.
 
-10. **Ephemeral test sessions.** `POST /api/v1/test/sessions` (authenticated) returns a UUID **`session_token`**. Clients send **`X-Test-Session: <token>`** on API calls to use an isolated, TTL- and quota-limited LMDB instead of production project data. Unless **`X-Test-Auth: required`** is set, normal JWT/API-key checks are bypassed for those requests (synthetic admin for wet tests). Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. The test store starts empty (no cloned production project config).
+10. **Ephemeral test sessions.** `POST /api/v1/test/sessions` (authenticated) returns a UUID **`session_token`**. Clients send **`X-Test-Session: <token>`** on API calls to use an isolated, TTL- and quota-limited LMDB instead of production project data. Unless **`X-Test-Auth: required`** is set, **developer** JWT/API-key checks are bypassed (synthetic admin for wet tests), but **app-user** identity via **`X-App-User-Token`** or Bearer app-user JWT is still recognized. Management routes under **`/api/v1/test/*`** must not include `X-Test-Session`. The test store starts empty (no cloned production project config).
 
 ## Common Pitfalls
 
@@ -48,6 +48,8 @@ Before reading the full reference, note these critical differences from typical
 
 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()`.
 
+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, empty, isolated LMDB that is automatically scoped away from production and destroyed after the test. See "Ephemeral test sessions" below.
+
 ---
 
 # Part 1: Product Overview
@@ -186,13 +188,15 @@ Browser and mobile apps can use OAuth2-style flows against `/api/v1/app/auth/oau
 
 # Ephemeral test sessions
 
+> **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised. Provision a session in `beforeAll` / `setUp` / test fixture setup and destroy it in `afterAll` / `tearDown` / fixture teardown.
+
 For **integration and wet tests** against a shared BaaS host without touching production data:
 
 | Step | What to do |
 |------|------------|
 | **Create** | **`POST /api/v1/test/sessions`** with normal **`Authorization: Bearer …`** or **`X-API-Key`**. Response includes a **`session_token`** (UUID). Server enforces per-credential limits (`test.max_sessions_per_key`, `test.session_ttl_seconds`, `test.max_test_db_size_bytes` in server config). |
 | **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:** test requests **skip** normal auth (convenient for automated tests). **`X-Test-Auth: required`:** require normal Bearer or API key; identity and ABAC apply, but data still comes from the test session DB. |
+| **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. |
 | **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. |
 | **CORS** | Browsers may need **`X-Test-Session`** and **`X-Test-Auth`** in the deployment’s allowed CORS headers (defaults include them). |
 
@@ -202,6 +206,126 @@ For **integration and wet tests** against a shared BaaS host without touching pr
 - **Python:** `async with XCiteDBClient.test_session(base_url, api_key=…, …)` provisions and tears down; or pass `test_session_token` / `test_require_auth` to the constructor.
 - **C++:** `XCiteDBClient::create_test_session(options)` after setting `api_key` (and optional `test_require_auth`); `destroy_test_session()`.
 
+**JavaScript/TypeScript — complete test scaffold (Vitest / Jest):**
+
+```typescript
+import { describe, it, expect, beforeAll, afterAll } from 'vitest';
+import { XCiteDBClient } from '@xcitedbs/client';
+
+describe('XciteDB integration', () => {
+  let client: XCiteDBClient;
+
+  beforeAll(async () => {
+    // Provisions an isolated, throwaway LMDB — production data is never touched.
+    client = await XCiteDBClient.createTestSession({
+      baseUrl: process.env.XCITEDB_URL ?? 'http://localhost:8080',
+      apiKey: process.env.XCITEDB_API_KEY!,
+    });
+  });
+
+  afterAll(async () => {
+    await client.destroyTestSession();
+  });
+
+  it('writes and reads a JSON document', async () => {
+    await client.writeJsonDocument('test.config', { env: 'test' });
+    const doc = await client.readJsonDocument<{ env: string }>('test.config');
+    expect(doc).toMatchObject({ env: 'test' });
+  });
+
+  it('writes and reads an XML document', async () => {
+    await client.writeXmlDocument(
+      '<doc db:identifier="/test/doc1"><title>Hello</title></doc>'
+    );
+    const xml = await client.queryByIdentifier('/test/doc1', 'FirstMatch');
+    expect(xml).toContain('<title>Hello</title>');
+  });
+
+  it('creates a branch, commits, and merges', async () => {
+    await client.withBranch('feature-test', async (c) => {
+      await c.writeJsonDocument('test.feature', { active: true });
+    }, { message: 'Add feature flag', autoMerge: true });
+    const doc = await client.readJsonDocument<{ active: boolean }>('test.feature');
+    expect(doc.active).toBe(true);
+  });
+});
+```
+
+**Python — complete test scaffold (pytest + pytest-asyncio):**
+
+```python
+import os
+import pytest
+import pytest_asyncio
+from xcitedb import XCiteDBClient
+
+@pytest_asyncio.fixture
+async def db():
+    # Provisions an isolated, throwaway LMDB — production data is never touched.
+    async with XCiteDBClient.test_session(
+        os.environ.get("XCITEDB_URL", "http://localhost:8080"),
+        api_key=os.environ["XCITEDB_API_KEY"],
+    ) as client:
+        yield client  # session is destroyed automatically on exit
+
+@pytest.mark.asyncio
+async def test_json_document(db):
+    await db.write_json_document("test.config", {"env": "test"})
+    doc = await db.read_json_document("test.config")
+    assert doc == {"env": "test"}
+
+@pytest.mark.asyncio
+async def test_xml_document(db):
+    await db.write_xml_document(
+        '<doc db:identifier="/test/doc1"><title>Hello</title></doc>'
+    )
+    result = await db.query_by_identifier("/test/doc1", "FirstMatch")
+    assert "<title>Hello</title>" in result
+
+@pytest.mark.asyncio
+async def test_branch_and_merge(db):
+    async with db.with_branch("feature-test", message="Add flag", auto_merge=True):
+        await db.put("test.feature", {"active": True})
+    doc = await db.get("test.feature")
+    assert doc["active"] is True
+```
+
+**C++ — complete test scaffold (Catch2):**
+
+```cpp
+#include <xcitedb/xcitedb.hpp>
+#include <catch2/catch_test_macros.hpp>
+#include <cstdlib>
+
+// Provisions an isolated, throwaway LMDB — production data is never touched.
+static xcitedb::XCiteDBClient make_test_client() {
+    xcitedb::XCiteDBClientOptions opt;
+    opt.base_url = std::getenv("XCITEDB_URL") ? std::getenv("XCITEDB_URL")
+                                               : "http://127.0.0.1:8080";
+    opt.api_key = std::getenv("XCITEDB_API_KEY");
+    return xcitedb::XCiteDBClient::create_test_session(opt);
+}
+
+TEST_CASE("XciteDB JSON document round-trip") {
+    auto client = make_test_client();
+    client.write_json_document("test.config", R"({"env":"test"})");
+    auto doc = client.read_json_document("test.config");
+    REQUIRE(doc.find("\"env\"") != std::string::npos);
+    REQUIRE(doc.find("\"test\"") != std::string::npos);
+    client.destroy_test_session();
+}
+
+TEST_CASE("XciteDB XML document round-trip") {
+    auto client = make_test_client();
+    client.write_xml_document(
+        R"(<doc db:identifier="/test/doc1"><title>Hello</title></doc>)"
+    );
+    auto xml = client.query_by_identifier("/test/doc1", "FirstMatch");
+    REQUIRE(xml.find("<title>Hello</title>") != std::string::npos);
+    client.destroy_test_session();
+}
+```
+
 ---
 
 # Health, version & discovery
@@ -515,6 +639,7 @@ Policies may set **`conditions.expression`** (optional) and **`conditions.branch
 {
   "subject": {
     "id": "...",
+    "user_id": "...",
     "email": "...",
     "type": "app_user|developer|...",
     "role": "...",
@@ -529,7 +654,9 @@ Policies may set **`conditions.expression`** (optional) and **`conditions.branch
 }
 ```
 
-`subject.attr` mirrors app-user **custom attributes** from the user record. `resource.path` is the identifier split on `/` (non-empty segments only).
+`subject.attr` mirrors app-user **custom attributes** from the user record. `resource.path` is the identifier split on `/` (non-empty segments only). **`subject.user_id` is the same string as `subject.id`** (app-user id); use either in expressions.
+
+**`resources.identifiers` patterns** (`exact`, `match_start`, `match_end`): values are **canonicalized** the same way as API identifiers (leading `/` added when missing). Example: `match_start: "userdata/"` matches stored ids like `/userdata/<userId>/…`.
 
 ### Operators (predicates)
 
@@ -1284,6 +1411,9 @@ interface DatabaseContext {
 - `deleteTrigger(name)` → `void`
 
 ### App User Auth
+
+**App-user auth in test sessions.** The full app-user lifecycle works inside a test session: `registerAppUser` → `loginAppUser` → `appUserMe` / `updateAppUserProfile` / etc. App user records are stored in the test session’s isolated LMDB and cleaned up with the session. No `X-Test-Auth: required` is needed for this flow — the default bypass mode recognizes app-user tokens while still skipping developer auth.
+
 - `registerAppUser(email, password, displayName?, attributes?)` → `AppUser` (groups assigned from server config)
 - `loginAppUser(email, password)` → `AppUserTokenPair`
 - `refreshAppUser()` → `AppUserTokenPair`

package/llms.txt

@@ -22,7 +22,13 @@ These are the most common sources of confusion for developers and AI assistants:
 
 8. **Project vs tenant id.** In the SDK, prefer `context.project_id` (and `listMyProjects` / `switchProject`). Many JSON bodies and JWT claims still use the field name `tenant_id` for the same value — the client sends that wire name automatically.
 
-9. **Ephemeral test sessions (wet tests).** Call **`POST /api/v1/test/sessions`** with a normal API key or Bearer token to get a `session_token` (UUID). Send **`X-Test-Session: <token>`** on subsequent document/API calls to use an isolated, short-lived LMDB instead of production data. By default those requests **skip** normal auth; send **`X-Test-Auth: required`** to exercise real JWT/API-key auth against the same test database. Do not send `X-Test-Session` on `/api/v1/test/*` management routes. Server limits apply (`test.session_ttl_seconds`, `test.max_sessions_per_key`, `test.max_test_db_size_bytes` in config). The test DB starts **empty** (no copy of production project config or keys).
+9. **Ephemeral test sessions (wet tests).** Call **`POST /api/v1/test/sessions`** with a normal API key or Bearer token to get a `session_token` (UUID). Send **`X-Test-Session: <token>`** on subsequent document/API calls to use an isolated, short-lived LMDB instead of production data. By default **developer** auth (API key / platform JWT) is bypassed, but **app-user** identity (`X-App-User-Token` or Bearer app-user JWT) is still recognized. Send **`X-Test-Auth: required`** to exercise full developer JWT/API-key auth and ABAC against the same test database. Do not send `X-Test-Session` on `/api/v1/test/*` management routes. Server limits apply (`test.session_ttl_seconds`, `test.max_sessions_per_key`, `test.max_test_db_size_bytes` in config). The test DB starts **empty** (no copy of production project config or keys).
+
+## Glossary: Project id, display name, and groups
+
+- **Project display name** (human-readable, e.g. `invoices`): Shown in the console. The **`X-Project-Id`** header may match either this name **or** the internal project id (server convenience). Do **not** put the display name in JWT claims or in `project:<…>:role` group strings.
+- **Project id / tenant_id** (internal, e.g. `t_…` or `default`): Canonical id in the app JWT **`tenant_id`** claim, in **`context.project_id`** (wire `tenant_id` in many app-auth bodies), and as the **middle segment** of **`project:<tenant_id>:admin|editor|viewer`**. Policies and app-user groups must use this value.
+- **Organization `slug`** (workspace metadata): Org-level label only — not a substitute for project `tenant_id` when scoping app users or ABAC.
 
 ## Common Pitfalls
 
@@ -36,13 +42,56 @@ These are the most common sources of confusion for developers and AI assistants:
 
 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.** `registerAppUser()` assigns groups from the server's `auth.app_users.default_groups` config, not from the client request. To set groups explicitly, use **`createAppUser`** with a `groups` array (e.g. `[XCiteDBClient.buildProjectGroup(projectId, 'editor')]`) or **`updateAppUserGroups`**. The server rejects `project:<x>:*` groups when `<x>` is not a known internal project id (avoids mistaking the display name for the tenant id).
+
+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, empty, isolated LMDB that is automatically scoped away from production and destroyed after the test. See "Test mode" below.
+
+8. **403 on writes with ABAC is often a JWT/group string mismatch.** Decode the app-user access token early: log **`tenant_id`**, **`groups`**, **`sub`**. The middle segment of every **`project:<x>:role`** group must equal **`tenant_id`** exactly. Document write denials may return JSON fields **`policy_id`** and **`hint`** alongside `"Forbidden"`.
+
+9. **`POST /api/v1/security/check` requires admin** (non-public key or app-user admin JWT). An **editor** API key gets **403** on this route — that means the *caller* cannot run the dry-run endpoint, **not** that a hypothetical subject lacks document access. Do not use this endpoint as the primary signal for “can my app user write?”.
+
+10. **`createAppUser` and `updateAppUserGroups` share the same gate:** admin or editor on a **secret** API key (or eligible app-user context), never a **public** key. If provisioning can create users with groups, it can patch groups later with the same credential.
+
+11. **Integration tests should assert token claims**, not only **`/app/auth/me`**. The profile endpoint can look fine while the JWT still carries viewer-style **`groups`**; for ABAC the token payload is authoritative. Use **`getTokenClaims()`** (JS SDK) or decode the JWT in your harness.
+
+## API key capability matrix (typical)
+
+| Capability | API key `role` | Public key allowed? |
+|------------|----------------|---------------------|
+| Read documents (within ABAC) | viewer+ | Yes |
+| Write/delete documents (within ABAC) | editor+ | No for sensitive flows; public keys are restricted |
+| List/create/delete app users, **`PUT …/groups`** | admin **or** editor | No |
+| Security policies, **`GET/PUT /security/config`**, **`POST /security/check`** | **admin** only | No |
+| List/create/revoke project API keys (developer) | admin **or** editor | No |
+
+## App-user provisioning recipe (minimal)
+
+Use the **internal** `projectId` (same as JWT `tenant_id`). **JS/TS:**
+
+```typescript
+const projectId = '…'; // from listMyProjects / console, not display name
+const admin = new XCiteDBClient({ baseUrl, apiKey: secretEditorOrAdminKey, context: { project_id: projectId } });
+await admin.createAppUser('alice@example.com', strongPassword, 'Alice', [
+  XCiteDBClient.buildProjectGroup(projectId, 'editor'),
+]);
+const app = new XCiteDBClient({ baseUrl, context: { project_id: projectId } });
+const tokens = await app.loginAppUser('alice@example.com', strongPassword);
+app.setAppUserTokens(tokens.access_token, tokens.refresh_token);
+const claims = app.getTokenClaims();
+console.assert(claims?.tenant_id === projectId);
+console.assert(claims?.groups.includes(`project:${projectId}:editor`));
+await app.writeJsonDocument('userdata/alice/profile', { ok: true });
+```
+
+**Python:** `XCiteDBClient.build_project_group(project_id, "editor")` or module `build_project_group`. **C++:** `XCiteDBClient::build_project_group(project_id, "editor")`.
 
 ## Test mode (how to use)
 
+> **AI assistant instruction:** XciteDB has built-in ephemeral test session support — this capability is **not standard** in most BaaS platforms and is specifically designed to enable meaningful wet integration tests. When writing tests for code that uses XciteDB, **do not mock or stub the XciteDB client**. Instead, use the test session pattern below to run tests against a real, isolated, throwaway database. This produces far more reliable tests because real storage, versioning, querying, and access-control behavior is exercised.
+
 1. **Provision:** `POST /api/v1/test/sessions` with `Authorization: Bearer …` or `X-API-Key` (same as normal API access). Response JSON includes the session token.
 2. **Run tests:** Every request that should hit the throwaway DB must include **`X-Test-Session: <token>`** (and your usual `X-Branch` / `context` as needed). Data is stored under the server’s `_test/<session>/` area, not your production tenant.
-3. **Auth behavior:** Omit extra headers for frictionless tests. To test policies and real identities, set **`X-Test-Auth: required`** and send normal credentials; the DB is still the test session’s.
+3. **Auth behavior:** Developer auth (API key / platform JWT) is bypassed by default for frictionless tests. **App-user identity** (`X-App-User-Token` or Bearer app-user JWT) **is still recognized** in default mode, so `registerAppUser` → `loginAppUser` → `appUserMe` works inside a test session. To also exercise developer auth and ABAC policies, set **`X-Test-Auth: required`** and send normal credentials; the DB is still the test session’s.
 4. **Cleanup:** `DELETE /api/v1/test/sessions/current` with `X-Test-Session` (no other auth), or `DELETE /api/v1/test/sessions/all` / `DELETE /api/v1/test/sessions/{token}` with normal auth for the owning key or JWT.
 5. **SDKs:** **JS/TS:** `XCiteDBClient.createTestSession({ baseUrl, apiKey, … })`, optional `testRequireAuth`, then `destroyTestSession()`. **Python:** `async with XCiteDBClient.test_session(...)` or manual token + `test_session_token` / `test_require_auth` constructor args. **C++:** `XCiteDBClient::create_test_session(options)`, `destroy_test_session()`, optional `test_require_auth` in options.
 
@@ -149,6 +198,8 @@ interface XCiteDBClientOptions {
 - `version()` — Server version info
 - `platformLogin(email, password)` — Platform operator sign-in
 - `loginAppUser(email, password)` — App end-user sign-in
+- `XCiteDBClient.buildProjectGroup(projectId, 'admin'|'editor'|'viewer')` — Static helper: canonical `project:<tenant_id>:<role>` string
+- `getTokenClaims()` — Decode current `appUserAccessToken` or `accessToken` payload (no signature verification); use for ABAC debugging
 - `setContext(ctx)` — Update branch/date context
 - `setProjectId(id)` — Switch active project (platform console)
 
@@ -209,7 +260,7 @@ interface XCiteDBClientOptions {
 ### Advanced: policy expressions (ABAC)
 
 - **Actions** (use in `policy.actions`): `read`, `write`, `delete`, `list`, `meta:read`, `meta:write`, `unquery`.
-- **`conditions.expression`** uses the same predicate syntax as Unquery `?` filters. **Context:** `subject.id`, `subject.email`, `subject.role`, `subject.groups`, `subject.attr.*` (app-user JSON attributes), `resource.identifier`, `resource.path` (array of path segments), `env.branch`.
+- **`conditions.expression`** uses the same predicate syntax as Unquery `?` filters. **Context:** `subject.id` and **`subject.user_id`** (same value for app users), `subject.email`, `subject.role`, `subject.groups`, `subject.attr.*` (app-user JSON attributes), `resource.identifier`, `resource.path` (array of path segments; indices follow non-empty `/` segments after API canonicalization, e.g. `/userdata/u1/x` → `[userdata,u1,x]`), `env.branch`. Policy **`match_start` / `match_end` / `exact`** strings are canonicalized like API identifiers (add leading `/` when omitted).
 - **Operators:** `=`, `!=`, `>=`, `<=`, `>`, `<`, `in`, `contains`, `starts_with`, `ends_with`, `&`, `|`, `!`, `+` (string concat), postfix `!` (exists).
 - **Examples:** `resource.path[0] = subject.attr.tenant_code` — tenant isolation; `subject.attr.level >= 5` — numeric attribute gate.
 
@@ -247,7 +298,7 @@ When calling `queryByIdentifier` or `queryDocuments`, the `flags` parameter cont
 
 ### Errors
 
-All API errors throw `XCiteDBError` with `.status` (HTTP code) and `.body` (parsed response). Common codes: `401` unauthenticated, `403` forbidden by policy, `404` not found, `409` conflict (lock), `422` validation, `423` project encrypted and locked, `429` rate limited.
+All API errors throw `XCiteDBError` with `.status` (HTTP code) and `.body` (parsed response). Common codes: `401` unauthenticated, `403` forbidden by policy or RBAC, `404` not found, `409` conflict (lock), `422` validation, `423` project encrypted and locked, `429` rate limited. Many **ABAC** denials return `403` with `"message":"Forbidden"` plus optional **`policy_id`** and **`hint`** (check JWT `tenant_id` vs `project:` group middle segment).
 
 ## Python SDK (`xcitedb`)
 

package/package.json

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