@xcitedbs/client 0.2.8 → 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

@@ -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.
@@ -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,6 +1,6 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.2.8",
+  "version": "0.2.9",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",