@xcitedbs/client 0.2.8 → 0.2.10

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, ProjectSearchSettings, ProjectSearchSettingsUpdate, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TokenPair, UserInfo, UserIsolationConfig, UserIsolationOptions, WriteDocumentOptions, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError } from './types';

package/dist/types.d.ts

@@ -41,6 +41,12 @@ export interface TextSearchQuery {
     branch?: string;
     offset?: number;
     limit?: number;
+    /** Default `fts`. `semantic` / `hybrid` require vector search (and hybrid requires FTS). */
+    mode?: 'fts' | 'semantic' | 'hybrid';
+    /** Minimum cosine similarity for semantic / hybrid vector leg (default 0.3). */
+    min_score?: number;
+    /** Hybrid only: weight of semantic vs FTS in weighted RRF (0–1, default 0.5). */
+    semantic_weight?: number;
 }
 export interface TextSearchHit {
     identifier: string;
@@ -51,12 +57,138 @@ export interface TextSearchHit {
     branch: string;
     snippet: string;
     score: number;
+    /** Present for semantic / hybrid search. */
+    source?: 'fts' | 'semantic' | 'both';
 }
 export interface TextSearchResult {
     hits: TextSearchHit[];
     total: number;
     query: string;
 }
+/** Progress object when the server is indexing (FTS or vector). */
+export interface SearchIndexingProgress {
+    done: number;
+    total: number;
+}
+/** Last finished vector re-embed job (`vector_index_job` in project settings). */
+export interface VectorIndexingLastJob {
+    ok?: boolean;
+    finished_at_ms?: number;
+    message?: string;
+    detail?: string;
+    phase?: string;
+    rows_indexed?: number;
+}
+/**
+ * Vector index workload + indicative cost.
+ * Blocking scan: `GET /api/v1/project/settings/search/vector-index-estimate` (no `session`).
+ * Incremental UI: `POST` same path, then `GET` / `DELETE` with `?session=`.
+ */
+export interface VectorIndexEstimate {
+    document_count?: number;
+    chunk_count?: number;
+    approx_input_tokens?: number;
+    approx_input_tokens_xml?: number;
+    approx_input_tokens_json?: number;
+    /** Serialized XML on disk (only docs that produced ≥1 embed chunk). */
+    xml_source_serialized_bytes_total?: number;
+    /** UTF-8 bytes of XML embed text (text nodes only; same as embedding input). */
+    xml_embed_text_bytes_total?: number;
+    /** Raw JSON document bytes (only docs that produced ≥1 embed chunk). */
+    json_source_bytes_total?: number;
+    /** UTF-8 bytes of JSON scalar chunks sent to the embedder. */
+    json_embed_text_bytes_total?: number;
+    token_estimate_note?: string;
+    embedding_provider?: string;
+    embedding_model?: string;
+    embedding_configured?: boolean;
+    pricing_info_url?: string;
+    /** Null when unknown (e.g. openai_compatible). */
+    usd_per_million_tokens_indicative?: number | null;
+    estimated_cost_usd_indicative?: number | null;
+    cost_disclaimer?: string;
+    /** Async session responses only (`POST` / `GET ?session=`). */
+    session_id?: string;
+    branches_done?: number;
+    branches_total?: number;
+    estimate_complete?: boolean;
+    estimate_cancelled?: boolean;
+    estimate_error?: string;
+}
+/** `GET /api/v1/project/settings/search` (and returned after `PUT`). */
+export interface ProjectSearchSettings {
+    search_enabled?: boolean;
+    search_language?: string;
+    indexing_status?: 'indexing' | 'idle';
+    indexing_progress?: SearchIndexingProgress;
+    vector_search_enabled?: boolean;
+    embedding_provider?: string;
+    embedding_model?: string;
+    embedding_base_url?: string;
+    llm_provider?: string;
+    llm_model?: string;
+    llm_base_url?: string;
+    embedding_configured?: boolean;
+    llm_configured?: boolean;
+    vector_indexing_status?: 'indexing' | 'scheduled' | 'idle';
+    vector_indexing_progress?: SearchIndexingProgress | null;
+    vector_indexing_last_job?: VectorIndexingLastJob | null;
+    [key: string]: unknown;
+}
+/**
+ * `PUT /api/v1/project/settings/search` body (all keys optional).
+ * `embedding_api_key` / `llm_api_key` are write-only: send a new secret or empty string to clear.
+ * While `vector_search_enabled` is true, changing embedding provider/model/base URL triggers a full vector re-embed on the server.
+ */
+export interface ProjectSearchSettingsUpdate {
+    search_enabled?: boolean;
+    search_language?: string;
+    vector_search_enabled?: boolean;
+    embedding_provider?: string;
+    embedding_model?: string;
+    embedding_base_url?: string | null;
+    embedding_api_key?: string;
+    llm_provider?: string;
+    llm_model?: string;
+    llm_base_url?: string | null;
+    llm_api_key?: string;
+}
+/** `POST /api/v1/rag/query` (non-streaming: set `stream: false` or omit). */
+export interface RagQueryOptions {
+    question: string;
+    branch?: string;
+    max_context_docs?: number;
+    doc_types?: ('xml' | 'json')[];
+    /** Default `false` for JSON response with `answer` and `sources`. */
+    stream?: boolean;
+    /** Default `auto`: hybrid if FTS+vector enabled, else best available mode. */
+    search_mode?: 'auto' | 'hybrid' | 'semantic' | 'fts';
+    /** Minimum cosine similarity for semantic / hybrid vector leg (default 0.35). */
+    min_score?: number;
+    /** Hybrid retrieval only: semantic vs FTS weight in weighted RRF (0–1, default 0.5). */
+    semantic_weight?: number;
+}
+export interface RagQueryResult {
+    answer: string;
+    sources: unknown;
+}
+/** One SSE JSON payload from streaming RAG (`stream: true`). */
+export type RagStreamEvent = {
+    text: string;
+    done: false;
+    sources?: undefined;
+    error?: undefined;
+} | {
+    text?: string;
+    done: true;
+    sources?: unknown;
+    error?: undefined;
+} | {
+    error: string;
+    done: true;
+    text?: undefined;
+    sources?: undefined;
+};
 /** Response from `GET /api/v1/documents/identifiers` */
 export interface ListIdentifiersResult {
     identifiers: string[];
@@ -116,6 +248,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;
@@ -191,6 +338,24 @@ export interface RealtimeEvent {
     timestamp?: number;
     tenant_id?: string;
 }
+/** When enabled, prefixes document/meta paths with the app user's namespace (e.g. `/users/{userId}/…`) for convenience; ABAC still enforces access on the server. */
+export interface UserIsolationOptions {
+    enabled: boolean;
+    /** Template with `{userId}` or server-style `${user.id}` replaced from JWT or login response; default `/users/{userId}`. */
+    namespace?: string;
+    /** Paths left unchanged by prefixing (optional; {@link XCiteDBClient.enableUserIsolation} fills from server). */
+    shared_read_paths?: string[];
+    shared_write_paths?: string[];
+}
+/** Effective user isolation settings from `GET /api/v1/security/user-isolation`. */
+export interface UserIsolationConfig {
+    enabled: boolean;
+    namespace_pattern: string;
+    shared_read_paths: string[];
+    shared_write_paths: string[];
+    shared_write_groups: string[];
+    generated_policies?: string[];
+}
 export interface XCiteDBClientOptions {
     baseUrl: string;
     apiKey?: string;
@@ -219,6 +384,8 @@ export interface XCiteDBClientOptions {
     testSessionToken?: string;
     /** When true with `testSessionToken`, sends `X-Test-Auth: required` so real credentials are validated. */
     testRequireAuth?: boolean;
+    /** Auto-prefix identifiers for app-user sessions (see {@link UserIsolationOptions}). */
+    userIsolation?: UserIsolationOptions;
 }
 /** Options for {@link XCiteDBClient.createTestSession} (provisions via API key or Bearer). */
 export interface CreateTestSessionOptions {
@@ -235,6 +402,7 @@ export interface CreateTestSessionOptions {
     onSessionTokensUpdated?: (pair: TokenPair) => void;
     onAppUserTokensUpdated?: (pair: AppUserTokenPair) => void;
     onSessionInvalid?: () => void;
+    userIsolation?: UserIsolationOptions;
 }
 /** Application user (tenant-scoped), distinct from developer users. */
 export interface AppUser {

package/dist/user-isolation.test.d.ts

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

package/dist/user-isolation.test.js

@@ -0,0 +1,175 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+/**
+ * Wet tests: set XCITEDB_BASE_URL, XCITEDB_ADMIN_TOKEN, XCITEDB_TENANT_ID (platform + project).
+ * Run: npm test (builds then runs node:test).
+ */
+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");
+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 };
+}
+function adminClient(e) {
+    return new client_js_1.XCiteDBClient({
+        baseUrl: e.baseUrl,
+        accessToken: e.accessToken,
+        platformConsole: true,
+        projectId: e.tenantId,
+        context: { branch: 'main', project_id: e.tenantId },
+    });
+}
+async function openTestSession(e) {
+    const url = `${e.baseUrl.replace(/\/+$/, '')}/api/v1/test/sessions`;
+    const r = await fetch(url, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${e.accessToken}`,
+            'X-Project-Id': e.tenantId,
+            'X-Branch': 'main',
+        },
+        body: '{}',
+    });
+    const data = (await r.json());
+    if (!r.ok || !data.session_token) {
+        throw new Error(`test session failed ${r.status}: ${JSON.stringify(data)}`);
+    }
+    const client = new client_js_1.XCiteDBClient({
+        baseUrl: e.baseUrl,
+        accessToken: e.accessToken,
+        platformConsole: true,
+        projectId: e.tenantId,
+        context: { branch: 'main', project_id: e.tenantId },
+        testSessionToken: data.session_token,
+        testRequireAuth: true,
+    });
+    return { client, token: data.session_token };
+}
+const w = wetEnv();
+const wd = w ? node_test_1.describe : node_test_1.describe.skip;
+wd('user isolation (wet)', () => {
+    (0, node_test_1.it)('setUserIsolationConfig enables isolation (round-trip)', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const c = adminClient(e);
+        try {
+            const out = await c.setUserIsolationConfig({
+                enabled: true,
+                namespace_pattern: '/users/${user.id}',
+            });
+            strict_1.default.equal(out.enabled, true);
+            const again = await c.getUserIsolationConfig();
+            strict_1.default.equal(again.enabled, true);
+        }
+        finally {
+            await c.disableUserIsolation().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('getUserIsolationConfig returns disabled in fresh test session', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const { client: s, token } = await openTestSession(e);
+        try {
+            const cfg = await s.getUserIsolationConfig();
+            strict_1.default.equal(cfg.enabled, false);
+        }
+        finally {
+            await fetch(`${e.baseUrl.replace(/\/+$/, '')}/api/v1/test/sessions/current`, {
+                method: 'DELETE',
+                headers: { 'X-Test-Session': token },
+            });
+        }
+    });
+    (0, node_test_1.it)('disableUserIsolation after enable', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const c = adminClient(e);
+        try {
+            await c.setUserIsolationConfig({ enabled: true, namespace_pattern: '/users/${user.id}' });
+            await c.disableUserIsolation();
+            const cfg = await c.getUserIsolationConfig();
+            strict_1.default.equal(cfg.enabled, false);
+        }
+        finally {
+            await c.disableUserIsolation().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('document write uses transparent prefix for app user', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = adminClient(e);
+        const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+        const email = `js_iso_${suffix}@apitest.invalid`;
+        const password = `Js_${suffix}!aA1`;
+        const slug = `js-iso-doc-${suffix}`;
+        try {
+            await admin.setUserIsolationConfig({ enabled: true, namespace_pattern: '/users/${user.id}' });
+            const u = await admin.createAppUser(email, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            const app = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                userIsolation: { enabled: true },
+            });
+            await app.loginAppUser(email, password);
+            await app.writeJsonDocument(`/${slug}`, { _xcite_json_doc: true, v: 1 });
+            const doc = await app.readJsonDocument(`/${slug}`);
+            strict_1.default.equal(doc.v, 1);
+            await admin.deleteJsonDocument(`/users/${u.user_id}/${slug}`);
+            await admin.deleteAppUser(u.user_id);
+        }
+        finally {
+            await admin.disableUserIsolation().catch(() => { });
+        }
+    });
+    (0, node_test_1.it)('shared_read_paths passthrough: app reads shared path without double-prefix', async () => {
+        const e = wetEnv();
+        if (!e)
+            throw new Error('missing env');
+        const admin = adminClient(e);
+        const suffix = (0, node_crypto_1.randomUUID)().slice(0, 8);
+        const email = `js_shr_${suffix}@apitest.invalid`;
+        const password = `Js_${suffix}!aA1`;
+        const sharedPath = `/shared-read-${suffix}`;
+        const docPath = `${sharedPath}/doc`;
+        try {
+            await admin.setUserIsolationConfig({
+                enabled: true,
+                namespace_pattern: '/users/${user.id}',
+                shared_read_paths: [sharedPath],
+            });
+            await admin.writeJsonDocument(docPath, { _xcite_json_doc: true, tag: 'shared' });
+            const created = await admin.createAppUser(email, password, undefined, [
+                client_js_1.XCiteDBClient.buildProjectGroup(e.tenantId, 'editor'),
+            ]);
+            const app = new client_js_1.XCiteDBClient({
+                baseUrl: e.baseUrl,
+                context: { branch: 'main', project_id: e.tenantId },
+                userIsolation: { enabled: true, shared_read_paths: [sharedPath] },
+            });
+            await app.loginAppUser(email, password);
+            const doc = await app.readJsonDocument(docPath);
+            strict_1.default.equal(doc.tag, 'shared');
+            await admin.deleteJsonDocument(docPath);
+            await admin.deleteAppUser(created.user_id);
+        }
+        finally {
+            await admin.disableUserIsolation().catch(() => { });
+        }
+    });
+});

package/llms-full.txt

@@ -518,7 +518,7 @@ Can also use `"query"` instead of `"identifier"` to target multiple documents by
 
 # Search
 
-Full-text search (backed by Meilisearch or Elasticsearch).
+Full-text search uses embedded XciteFTS (enable per project in server settings).
 
 **Base path:** `/api/v1/search`
 
@@ -639,6 +639,7 @@ Policies may set **`conditions.expression`** (optional) and **`conditions.branch
 {
   "subject": {
     "id": "...",
+    "user_id": "...",
     "email": "...",
     "type": "app_user|developer|...",
     "role": "...",
@@ -653,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)
 

package/llms.txt

@@ -24,6 +24,12 @@ These are the most common sources of confusion for developers and AI assistants:
 
 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
 
 1. **`baseUrl` must be origin-only (no `/api` or `/api/v1` path).** The SDK prepends `/api/v1/…` to every request. If `baseUrl` is `https://host/api/v1`, requests hit `/api/v1/api/v1/…` which typically returns **405 Not Allowed** from the reverse proxy. Use only the scheme + host + optional port: `https://host` or `http://localhost:8080`.
@@ -36,10 +42,49 @@ 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.
@@ -116,7 +161,7 @@ const lock = await client.acquireLock('/manual/v1/intro');
 // ... edit ...
 await client.releaseLock('/manual/v1/intro', lock.lock_id);
 
-// Full-text search (requires Meilisearch or Elasticsearch backend)
+// Full-text search (embedded XciteFTS; enable per project in server settings)
 const results = await client.search({ query: 'installation guide', limit: 20 });
 
 // Subscribe to real-time changes via WebSocket
@@ -153,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)
 
@@ -213,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.
 
@@ -251,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,13 +1,14 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.2.8",
+  "version": "0.2.10",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
     "build": "tsc",
     "prepublishOnly": "npm run build",
-    "test": "node --test dist/**/*.test.js 2>/dev/null || echo 'No tests'"
+    "test": "npm run build && node --test dist/**/*.test.js",
+    "test:only": "node --test dist/**/*.test.js"
   },
   "keywords": [
     "xcitedb",
@@ -34,6 +35,7 @@
   },
   "dependencies": {},
   "devDependencies": {
+    "@types/node": "^20.14.0",
     "typescript": "^5.0.0"
   },
   "files": [