@maravilla-labs/platform 0.5.1 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,9 +28,11 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
+    "typecheck:test-d": "tsc --noEmit -p tsconfig.test.json",
     "test": "vitest run"
   },
   "dependencies": {
+    "@maravilla-labs/types": "^0.6.0",
     "@noble/hashes": "^1.5.0",
     "livekit-client": "^2.18.1"
   },

package/src/config.ts

@@ -41,6 +41,173 @@ export type SecretRef = string | { env: string };
 import type { TransformsConfig } from './transforms.js';
 export type { TransformsConfig, TransformsPatternSpec } from './transforms.js';
 
+// ════════════════════════════════════════════════════════════════════
+// Typed policy builder (FR-7)
+// ════════════════════════════════════════════════════════════════════
+//
+// A tiny, composable builder for raisin-rel policy expressions. It exists
+// to (a) make the common patterns terse and discoverable and (b) refuse
+// the two footguns that silently fail closed in the runtime:
+//   - bare `is_admin` / `auth.isAdmin` / `auth.admin` — use `isAdmin()` /
+//     `auth.is_admin`;
+//   - `VIA` followed by anything other than a single-quoted bareword —
+//     use `relatesVia('NAME')`.
+// The builder emits valid syntax; `Policy.raw(...)` lints hand-written
+// expressions for the same footguns and throws on them.
+
+/**
+ * Sentinel wrapping an unexpanded `fragment('name')` reference. Padded
+ * with spaces so it composes safely inside `&&`/`||` chains, and chosen
+ * so it cannot appear in valid raisin-rel source. It is always replaced
+ * by {@link defineConfig} before reaching the runtime.
+ */
+const FRAGMENT_OPEN = ' fragment(';
+const FRAGMENT_CLOSE = ') ';
+/** Matches the sentinel and captures the fragment NAME. */
+const FRAGMENT_RE = / fragment\(([^)]+)\) /g;
+
+/**
+ * Throws when `expr` contains a known legacy/footgun policy shape that the
+ * runtime evaluator would fail closed on. Called by {@link Policy.raw}.
+ *
+ * @internal
+ */
+export function assertNoLegacyShapes(expr: string): void {
+  // `auth.isAdmin` / `auth.admin` — camelCase / wrong field. Check before
+  // the bare-`is_admin` rule so the message is the most specific one.
+  if (/auth\.isAdmin\b/.test(expr)) {
+    throw new Error("Policy: `auth.isAdmin` is invalid — use the `isAdmin()` builder or write `auth.is_admin`.");
+  }
+  if (/auth\.admin\b/.test(expr)) {
+    throw new Error("Policy: `auth.admin` is invalid — use the `isAdmin()` builder or write `auth.is_admin`.");
+  }
+  // Bare `is_admin` (the valid form is the qualified `auth.is_admin`).
+  // Negative lookbehind: any `is_admin` not preceded by a word char or
+  // dot is "bare". `auth.is_admin` is preceded by `.` and thus allowed.
+  if (/(?<![\w.])is_admin\b/.test(expr)) {
+    throw new Error(
+      "Policy: bare `is_admin` is not a valid root — use the `isAdmin()` builder or write `auth.is_admin`.",
+    );
+  }
+  // `VIA` must be followed by a single-quoted relation name: `VIA 'NAME'`.
+  // Reject `VIA "NAME"`, `VIA STEWARDS`, `VIA auth.x`, trailing `VIA`, etc.
+  const viaRe = /\bVIA\b\s*([^\s)]+)?/g;
+  let m: RegExpExecArray | null;
+  while ((m = viaRe.exec(expr)) !== null) {
+    const operand = m[1];
+    if (!operand || !/^'[^']+'$/.test(operand)) {
+      throw new Error(
+        "Policy: `VIA` must be followed by a single-quoted relation name (e.g. VIA 'STEWARDS'). " +
+          "Use the `relatesVia('NAME')` builder instead of writing the clause by hand.",
+      );
+    }
+  }
+}
+
+/**
+ * A composable, typed policy expression. Build with the helper functions
+ * ({@link ownsIt}, {@link isStaff}, {@link isAdmin}, {@link relatesVia},
+ * {@link publicWhen}, {@link fragment}) and combine with `.and()` / `.or()`.
+ * `toString()` yields the raisin-rel source.
+ */
+export class Policy {
+  private constructor(private readonly expr: string) {}
+
+  /**
+   * Wrap a raw raisin-rel expression. Lints for legacy footguns and
+   * throws on them (see {@link assertNoLegacyShapes}).
+   */
+  static raw(expr: string): Policy {
+    assertNoLegacyShapes(expr);
+    return new Policy(expr);
+  }
+
+  /** @internal Build without linting — for the builder helpers only. */
+  private static unchecked(expr: string): Policy {
+    return new Policy(expr);
+  }
+
+  toString(): string {
+    return this.expr;
+  }
+
+  /** Logical OR with another policy (each side parenthesized). */
+  or(other: Policy): Policy {
+    return Policy.unchecked(`${this.expr} || ${other.expr}`);
+  }
+
+  /** Logical AND with another policy (each side parenthesized). */
+  and(other: Policy): Policy {
+    return Policy.unchecked(`${this.expr} && ${other.expr}`);
+  }
+}
+
+/**
+ * Caller owns the resource: `auth.user_id == node.<field>` (default
+ * `owner`).
+ */
+export function ownsIt(field: string = 'owner'): Policy {
+  return Policy.raw(`auth.user_id == node.${field}`);
+}
+
+/**
+ * Caller is a member of a staff-like group:
+ * `auth.roles.contains('<group>')` (default `staff`).
+ */
+export function isStaff(group: string = 'staff'): Policy {
+  return Policy.raw(`auth.roles.contains('${group}')`);
+}
+
+/**
+ * Caller is a platform admin: `auth.is_admin`. Valid now that the runtime
+ * populates `is_admin` from membership in the `admin` group.
+ */
+export function isAdmin(): Policy {
+  return Policy.raw('auth.is_admin');
+}
+
+/**
+ * A typed `RELATES … VIA '<name>'` clause (FR-1). Emits
+ * `<object> RELATES <subject> VIA '<relationName>'[ DEPTH a..b]`.
+ *
+ * @param relationName - the relation type name (cross-validated against
+ *   the declared `relations[]` at {@link defineConfig} time).
+ * @param opts.subject - the related party (default `auth.user_id`).
+ * @param opts.object  - the anchor node (default `node.owner`).
+ * @param opts.depth   - inclusive `[min, max]` traversal depth.
+ */
+export function relatesVia(
+  relationName: string,
+  opts?: { subject?: string; object?: string; depth?: [number, number] },
+): Policy {
+  const subject = opts?.subject ?? 'auth.user_id';
+  const object = opts?.object ?? 'node.owner';
+  let expr = `${object} RELATES ${subject} VIA '${relationName}'`;
+  if (opts?.depth) {
+    expr += ` DEPTH ${opts.depth[0]}..${opts.depth[1]}`;
+  }
+  return Policy.raw(expr);
+}
+
+/**
+ * Resource is publicly readable: `node.<field> == true` (default
+ * `public`).
+ */
+export function publicWhen(field: string = 'public'): Policy {
+  return Policy.raw(`node.${field} == true`);
+}
+
+/**
+ * Reference a named fragment declared in `auth.fragments`. Resolved and
+ * inlined (parenthesized) by {@link defineConfig}; a dangling reference
+ * (no matching fragment) throws there.
+ */
+export function fragment(name: string): Policy {
+  // Carries a sentinel that defineConfig() recognizes and expands. It is
+  // never emitted to the runtime un-expanded.
+  return Policy.raw(`${FRAGMENT_OPEN}${name}${FRAGMENT_CLOSE}`);
+}
+
 // ── Resources + policies ──
 
 /**
@@ -83,14 +250,20 @@ export interface ResourceDefinition {
    * Optional raisin-rel policy expression. Evaluated on every KV/DB/
    * realtime/media op that targets this resource. Leave empty to skip
    * Layer 2 for this resource — tenant + owner isolation still applies.
+   *
+   * Accepts either a raw string or a typed {@link Policy} built with
+   * `ownsIt()`/`isStaff()`/`isAdmin()`/`relatesVia()`/`publicWhen()`/
+   * `fragment()` (and `.and()`/`.or()`). {@link defineConfig} serializes
+   * it via `.toString()` and expands any `fragment()` references.
    */
-  policy?: string;
+  policy?: string | Policy;
   /**
    * C+D read-filter (option ii). JSON object the runtime ANDs into the
    * caller's filter on `db.find` / `db.findOne`. Supports `$auth.<path>`
    * placeholder strings (e.g. `"$auth.user_id"`) substituted from the
    * caller's identity at request time. Allowed paths: `user_id`, `email`,
-   * `is_admin`, `roles`.
+   * `is_admin`, `status`, `email_verified`, `groups`, `roles`, `circles`,
+   * `profile.<field>`, `scopes.<field>`.
    *
    * Independent of `policy` — `policy` gates writes and resolved-doc reads;
    * `read_filter` scopes which rows the caller can ever see.
@@ -98,6 +271,19 @@ export interface ResourceDefinition {
    * Example: `'{"$or":[{"owner":"$auth.user_id"},{"public":true}]}'`
    */
   read_filter?: string;
+  /**
+   * Field-level redaction. Maps a field dot-path to a raisin-rel expression;
+   * a field is replaced with null on read when its expression is truthy for
+   * the caller (fail-closed). Example: `{ birth_date: "!auth.is_admin" }`.
+   */
+  redact?: Record<string, string>;
+  /** When true, every policy decision on this resource is recorded. */
+  audit?: boolean;
+  /**
+   * Fallback decision when this resource has no `policy`: `'allow'` (the
+   * default) or `'deny'`. Overrides the tenant-wide `security.default_policy`.
+   */
+  default_policy?: 'allow' | 'deny';
 }
 
 // ── Groups ──
@@ -112,6 +298,8 @@ export interface GroupPermissionDefinition {
 export interface GroupDefinition {
   /** Unique group name per tenant. */
   name: string;
+  /** Tenant-unique slug for stable addressing in JWT/API/policies. */
+  slug?: string;
   /** Optional description for the admin UI. */
   description?: string;
   /** Resource permissions granted to the group. Replaces the group's current permissions when declared. */
@@ -121,8 +309,15 @@ export interface GroupDefinition {
 // ── Relations ──
 
 export interface RelationTypeDefinition {
-  /** Uppercase identifier used in policies (`... VIA 'STEWARDS'`). */
+  /**
+   * Uppercase identifier referenced from policies. Don't hand-write the
+   * `... VIA 'STEWARDS'` clause — use the typed {@link relatesVia} builder
+   * (`relatesVia('STEWARDS')`), which emits the correct single-quoted form
+   * and is cross-validated against this list at {@link defineConfig} time.
+   */
   relation_name: string;
+  /** Tenant-unique slug for stable addressing. */
+  slug?: string;
   /** Human-readable title. */
   title: string;
   description?: string;
@@ -234,6 +429,23 @@ export interface AuthConfigBlock {
   oauth?: OAuthProvidersConfig;
   security?: SecurityConfig;
   branding?: BrandingConfig;
+  /**
+   * Named, reusable policy fragments. Reference a fragment from any
+   * resource policy with `fragment('name')`; {@link defineConfig} expands
+   * the reference inline (wrapped in parens) at build time, so the
+   * runtime never sees the indirection. Values may be a {@link Policy} or
+   * a raw string expression.
+   *
+   * @example
+   * ```ts
+   * defineConfig({ auth: {
+   *   fragments: { staffOrAdmin: isStaff().or(isAdmin()) },
+   *   resources: [{ name: 'todos', title: 'Todos', actions: ['read'],
+   *     policy: ownsIt().or(fragment('staffOrAdmin')) }],
+   * }});
+   * ```
+   */
+  fragments?: Record<string, Policy | string>;
 }
 
 export interface MaravillaConfig {
@@ -306,21 +518,132 @@ export interface DatabaseConfigBlock {
 }
 
 /**
- * Identity function that returns the config unchanged — exists purely so the
- * TypeScript compiler can infer `MaravillaConfig` and give you IntelliSense
- * on every field.
+ * Recursively expand `fragment(name)` sentinels in `expr` against the
+ * declared `fragments` map. Each expansion is wrapped in parens so it
+ * binds correctly inside `&&`/`||`. Throws on an unknown fragment or a
+ * fragment cycle.
+ *
+ * @internal
+ */
+function expandFragments(
+  expr: string,
+  fragments: Record<string, string>,
+  seen: ReadonlySet<string> = new Set(),
+): string {
+  return expr.replace(FRAGMENT_RE, (_match, rawName: string) => {
+    const name = rawName.trim();
+    if (!(name in fragments)) {
+      throw new Error(
+        `Policy: fragment('${name}') is not declared in auth.fragments. ` +
+          `Declared fragments: ${Object.keys(fragments).join(', ') || '(none)'}.`,
+      );
+    }
+    if (seen.has(name)) {
+      throw new Error(
+        `Policy: fragment('${name}') is part of a reference cycle (${[...seen, name].join(' → ')}).`,
+      );
+    }
+    const expanded = expandFragments(fragments[name], fragments, new Set([...seen, name]));
+    return `(${expanded.trim()})`;
+  });
+}
+
+/** Extract every relation name referenced via `VIA 'NAME'`. @internal */
+function relationNamesIn(expr: string): string[] {
+  const out: string[] = [];
+  const re = /\bVIA\s+'([^']+)'/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(expr)) !== null) out.push(m[1]);
+  return out;
+}
+
+/** Extract every group referenced via `auth.roles.contains('GROUP')`. @internal */
+function groupNamesIn(expr: string): string[] {
+  const out: string[] = [];
+  const re = /auth\.roles\.contains\(\s*'([^']+)'\s*\)/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(expr)) !== null) out.push(m[1]);
+  return out;
+}
+
+/**
+ * Validate + normalize a Maravilla config.
+ *
+ * Beyond giving you full IntelliSense, this:
+ *  - serializes every `Policy`-typed resource policy to its string form;
+ *  - inlines `fragment('name')` references against `auth.fragments`
+ *    (throws on an unknown fragment or a cycle);
+ *  - cross-validates that relation names used in `relatesVia()` exist in
+ *    the declared `auth.relations[]`, and (when `auth.groups[]` is
+ *    declared) that groups referenced via `isStaff()` /
+ *    `auth.roles.contains(...)` exist there — throwing on unknown.
+ *
+ * The returned config has all policies as plain strings, ready for the
+ * reconciler. Sections you didn't declare are left untouched.
  *
  * @example
  * ```typescript
- * import { defineConfig } from '@maravilla-labs/platform/config';
+ * import { defineConfig, ownsIt, isStaff } from '@maravilla-labs/platform/config';
  *
  * export default defineConfig({
  *   auth: {
- *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'] }],
+ *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'],
+ *       policy: ownsIt().or(isStaff()) }],
  *   },
  * });
  * ```
  */
 export function defineConfig(config: MaravillaConfig): MaravillaConfig {
-  return config;
+  const auth = config.auth;
+  if (!auth) return config;
+
+  // Normalize the declared fragments to strings up front (a fragment may
+  // itself be a Policy or a raw string).
+  const fragmentStrings: Record<string, string> = {};
+  if (auth.fragments) {
+    for (const [name, frag] of Object.entries(auth.fragments)) {
+      fragmentStrings[name] = typeof frag === 'string' ? frag : frag.toString();
+    }
+  }
+
+  const declaredRelations = new Set((auth.relations ?? []).map((r) => r.relation_name));
+  const declaredGroups = new Set((auth.groups ?? []).map((g) => g.name));
+  const validateGroups = (auth.groups ?? []).length > 0;
+
+  const resources = auth.resources?.map((res) => {
+    if (res.policy == null) return res;
+    const raw = typeof res.policy === 'string' ? res.policy : res.policy.toString();
+    const expanded = expandFragments(raw, fragmentStrings).trim();
+
+    for (const rel of relationNamesIn(expanded)) {
+      if (!declaredRelations.has(rel)) {
+        throw new Error(
+          `Policy for resource '${res.name}' references relation '${rel}' via relatesVia(), ` +
+            `but it is not declared in auth.relations[]. ` +
+            `Declared relations: ${[...declaredRelations].join(', ') || '(none)'}.`,
+        );
+      }
+    }
+    if (validateGroups) {
+      for (const group of groupNamesIn(expanded)) {
+        if (!declaredGroups.has(group)) {
+          throw new Error(
+            `Policy for resource '${res.name}' references group '${group}', ` +
+              `but it is not declared in auth.groups[]. ` +
+              `Declared groups: ${[...declaredGroups].join(', ')}.`,
+          );
+        }
+      }
+    }
+
+    return { ...res, policy: expanded };
+  });
+
+  return {
+    ...config,
+    auth: {
+      ...auth,
+      ...(resources ? { resources } : {}),
+    },
+  };
 }

package/src/remote-client.ts

@@ -1,4 +1,4 @@
-import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, UserListFilter, UserListResponse, UpdateUserOptions, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor, Workflows, WorkflowHandle, WorkflowRun, WorkflowStepRecord } from './types.js';
+import type { KvNamespace, KvListResult, Database, DbDocument, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, CreateManagedUserOptions, UserListFilter, UserListResponse, UpdateUserOptions, Relation, AddRelationOptions, ListRelationsOptions, PolicyExplain, CanCheck, PolicyService, VectorIndexSpec, VectorIndexDescriptor, VectorQueryWithFilter, VectorSearchHit, IndexSpec, IndexDescriptor, Workflows, WorkflowHandle, WorkflowRun, WorkflowStepRecord } from './types.js';
 import type { TransformsService, TranscodeOpts, ThumbnailOpts, ResizeOpts, OcrOpts, DocToPdfOpts, DocThumbnailOpts, DocConvertOpts, DocToMarkdownOpts, DocToHtmlOpts, DocReplaceImagesOpts, DocInsertQrCodeOpts, DocTemplateMergeOpts, JobHandle, JobStatusResponse, MediaInfo } from './transforms.js';
 import { RemoteMediaService } from './media.js';
 import { getRequestAuthHeader } from './request-scope.js';
@@ -107,21 +107,21 @@ class RemoteDatabase implements Database {
     return response;
   }
 
-  async find(collection: string, filter: any = {}, options: DbFindOptions = {}): Promise<any[]> {
+  async find<T = Record<string, unknown>>(collection: string, filter: any = {}, options: DbFindOptions = {}): Promise<DbDocument<T>[]> {
     const response = await this.fetch(`${this.baseUrl}/api/db/${collection}`, {
       method: 'POST',
       body: JSON.stringify({ filter, options }),
     });
-    return response.json() as Promise<any[]>;
+    return response.json() as Promise<DbDocument<T>[]>;
   }
 
-  async findOne(collection: string, filter: any): Promise<any | null> {
+  async findOne<T = Record<string, unknown>>(collection: string, filter: any): Promise<DbDocument<T> | null> {
     const response = await this.fetch(`${this.baseUrl}/api/db/${collection}/findOne`, {
       method: 'POST',
       body: JSON.stringify(filter),
     });
     if (response.status === 404) return null;
-    return response.json();
+    return response.json() as Promise<DbDocument<T>>;
   }
 
   async insertOne(collection: string, document: any): Promise<string> {
@@ -558,6 +558,10 @@ class RemoteAuthService implements AuthService {
     await this.post('/delete-user', { user_id: userId });
   }
 
+  async createManagedUser(options: CreateManagedUserOptions): Promise<AuthUser> {
+    return this.post('/create-managed-user', options);
+  }
+
   async sendVerification(userId: string): Promise<{ token: string }> {
     return this.post('/send-verification', { user_id: userId });
   }
@@ -693,6 +697,32 @@ class RemoteAuthService implements AuthService {
     await this.post('/relation-types/delete', { id });
   }
 
+  // ── Relations (typed edges, FR-1) ──
+
+  async addRelation(options: AddRelationOptions): Promise<Relation> {
+    return this.post('/relations/add', {
+      from_user_id: options.from_user_id,
+      to_user_id: options.to_user_id,
+      relation_type: options.relation_type,
+      metadata: options.metadata ?? null,
+    });
+  }
+
+  async removeRelation(fromUserId: string, toUserId: string, relationTypeId: string): Promise<void> {
+    await this.post('/relations/remove', {
+      from_user_id: fromUserId,
+      to_user_id: toUserId,
+      relation_type_id: relationTypeId,
+    });
+  }
+
+  async listRelations(options: ListRelationsOptions): Promise<Relation[]> {
+    return this.post('/relations/list', {
+      user_id: options.user_id,
+      direction: options.direction ?? 'both',
+    });
+  }
+
   // ── Profile ──
 
   async getProfile(userId: string): Promise<Record<string, any>> {
@@ -856,6 +886,52 @@ class RemoteAuthService implements AuthService {
     });
     return Boolean((r as any)?.allowed);
   }
+
+  async explain(
+    action: string,
+    resourceId: string,
+    node?: Record<string, unknown> | null,
+  ): Promise<PolicyExplain> {
+    const { getCurrentRequestStore } = await import('./request-scope.js');
+    const store = getCurrentRequestStore();
+    const token = store?.token;
+    if (!token) {
+      // No bound user → fail-closed with a reason, mirroring can().
+      return { allowed: false, reason: 'no bound user' };
+    }
+    const r = await this.post('/can-explain', {
+      token,
+      action,
+      resource_id: resourceId,
+      node: node ?? null,
+    }) as any;
+    return {
+      allowed: Boolean(r?.allowed),
+      reason: r?.reason,
+      failedClause: r?.failedClause,
+    };
+  }
+
+  async canMany(checks: CanCheck[]): Promise<{ allowed: boolean }[]> {
+    const { getCurrentRequestStore } = await import('./request-scope.js');
+    const store = getCurrentRequestStore();
+    const token = store?.token;
+    if (!token) {
+      // No bound user → fail-closed for every check, preserving order.
+      return checks.map(() => ({ allowed: false }));
+    }
+    const r = await this.post('/can-many', {
+      token,
+      checks: checks.map((c) => ({
+        action: c.action,
+        resource_id: c.resourceId,
+        node: c.node ?? null,
+      })),
+    }) as any;
+    const results: any[] = Array.isArray(r) ? r : (r?.results ?? []);
+    // Preserve request order; default any missing entry to fail-closed.
+    return checks.map((_, i) => ({ allowed: Boolean(results[i]?.allowed) }));
+  }
 }
 
 // Cache the request-scope module on the class so getCurrentUser can read