@maravilla-labs/platform 0.3.3 → 0.3.7

package/dist/config.d.ts

@@ -42,6 +42,16 @@ type SecretRef = string | {
     env: string;
 };
 
+/**
+ * The platform service this resource binds to. Used by the UI to offer
+ * service-correct action presets and policy snippets, and by the reconciler
+ * to validate that policies reference legal `node.*` fields for the service.
+ *
+ * Omit for legacy / cross-service umbrella resources — the runtime falls back
+ * to matching purely by `name` (a name collision between e.g. a KV namespace
+ * and a DB collection will silently share a policy, which is rarely desired).
+ */
+type ResourceServiceType = 'kv' | 'database' | 'realtime' | 'media' | 'vector' | 'storage' | 'queue' | 'push' | 'workflow' | 'transforms';
 interface ResourceDefinition {
     /** URL-safe slug. Used as the resource key in code (e.g. the KV namespace). */
     name: string;
@@ -49,6 +59,12 @@ interface ResourceDefinition {
     title: string;
     /** Optional longer description. */
     description?: string;
+    /**
+     * Which platform service this resource gates. When set, the reconciler
+     * validates that the policy only references `node.*` fields legal for that
+     * service (e.g. a `realtime` policy can't reference `node.collection`).
+     */
+    type?: ResourceServiceType;
     /** Actions this resource supports, e.g. `['read', 'write', 'delete']`. */
     actions: string[];
     /**
@@ -57,6 +73,19 @@ interface ResourceDefinition {
      * Layer 2 for this resource — tenant + owner isolation still applies.
      */
     policy?: string;
+    /**
+     * 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`.
+     *
+     * Independent of `policy` — `policy` gates writes and resolved-doc reads;
+     * `read_filter` scopes which rows the caller can ever see.
+     *
+     * Example: `'{"$or":[{"owner":"$auth.user_id"},{"public":true}]}'`
+     */
+    read_filter?: string;
 }
 interface GroupPermissionDefinition {
     /** Must match a `ResourceDefinition.name`. */
@@ -244,4 +273,4 @@ interface DatabaseConfigBlock {
  */
 declare function defineConfig(config: MaravillaConfig): MaravillaConfig;
 
-export { type AuthConfigBlock, type BrandingConfig, type DatabaseConfigBlock, type DocumentIndexDeclaration, type GroupDefinition, type GroupPermissionDefinition, type IndexDirectionConfig, type MaravillaConfig, type OAuthProviderDefinition, type OAuthProvidersConfig, type PasswordPolicyDefinition, type RegistrationConfig, type RegistrationFieldDefinition, type RelationTypeDefinition, type ResourceDefinition, type SecretRef, type SecurityConfig, type SessionConfigDefinition, TransformsConfig, type VectorIndexDeclaration, type VectorMetricConfig, type VectorStorageConfig, defineConfig };
+export { type AuthConfigBlock, type BrandingConfig, type DatabaseConfigBlock, type DocumentIndexDeclaration, type GroupDefinition, type GroupPermissionDefinition, type IndexDirectionConfig, type MaravillaConfig, type OAuthProviderDefinition, type OAuthProvidersConfig, type PasswordPolicyDefinition, type RegistrationConfig, type RegistrationFieldDefinition, type RelationTypeDefinition, type ResourceDefinition, type ResourceServiceType, type SecretRef, type SecurityConfig, type SessionConfigDefinition, TransformsConfig, type VectorIndexDeclaration, type VectorMetricConfig, type VectorStorageConfig, defineConfig };

package/dist/config.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/config.ts"],"sourcesContent":["/**\n * @fileoverview Typed schema for `maravilla.config.{ts,yaml,json}` files.\n *\n * Declares your project's auth settings (resources, groups, relations,\n * registration fields, OAuth providers, security policy, branding) alongside\n * your code. The Maravilla adapter reads this at build time and reconciles\n * the settings into delivery on deploy.\n *\n * ```typescript\n * import { defineConfig } from '@maravilla-labs/platform/config';\n *\n * export default defineConfig({\n *   auth: {\n *     resources: [\n *       { name: 'todos', title: 'Todos', actions: ['read', 'write'],\n *         policy: 'auth.user_id == node.owner' },\n *     ],\n *   },\n * });\n * ```\n *\n * Omitted sections leave the DB alone — partial adoption is explicitly\n * supported. List-based sections (`resources`, `groups`, `relations`,\n * `oauth`) are upserted and never auto-delete DB-only entries. Singleton\n * sections (`registration`, `security`, `branding`) are replaced wholesale\n * when declared.\n */\n\n/**\n * String value that may either be a literal secret or a reference to an\n * environment variable on the **tenant** (resolved server-side at\n * reconcile time, never shipped plaintext in the manifest).\n *\n * Accepted forms:\n *   - `\"literal-value\"` — inline (not recommended for real secrets)\n *   - `\"${env.VAR_NAME}\"` — string-template form\n *   - `{ env: \"VAR_NAME\" }` — object form\n */\nexport type SecretRef = string | { env: string };\n\nimport type { TransformsConfig } from './transforms.js';\nexport type { TransformsConfig, TransformsPatternSpec } from './transforms.js';\n\n// ── Resources + policies ──\n\nexport interface ResourceDefinition {\n  /** URL-safe slug. Used as the resource key in code (e.g. the KV namespace). */\n  name: string;\n  /** Human-readable title for the admin UI. */\n  title: string;\n  /** Optional longer description. */\n  description?: string;\n  /** Actions this resource supports, e.g. `['read', 'write', 'delete']`. */\n  actions: string[];\n  /**\n   * Optional raisin-rel policy expression. Evaluated on every KV/DB/\n   * realtime/media op that targets this resource. Leave empty to skip\n   * Layer 2 for this resource — tenant + owner isolation still applies.\n   */\n  policy?: string;\n}\n\n// ── Groups ──\n\nexport interface GroupPermissionDefinition {\n  /** Must match a `ResourceDefinition.name`. */\n  resource_name: string;\n  /** Actions this group is granted on the resource. */\n  actions: string[];\n}\n\nexport interface GroupDefinition {\n  /** Unique group name per tenant. */\n  name: string;\n  /** Optional description for the admin UI. */\n  description?: string;\n  /** Resource permissions granted to the group. Replaces the group's current permissions when declared. */\n  permissions?: GroupPermissionDefinition[];\n}\n\n// ── Relations ──\n\nexport interface RelationTypeDefinition {\n  /** Uppercase identifier used in policies (`... VIA 'STEWARDS'`). */\n  relation_name: string;\n  /** Human-readable title. */\n  title: string;\n  description?: string;\n  /** Grouping for the admin UI (e.g. `\"family\"`, `\"work\"`). */\n  category?: string;\n  icon?: string;\n  color?: string;\n  /** Name of the inverse relation type, if one exists. */\n  inverse_relation_name?: string;\n  /** When true, membership in this relation implies stewardship rights. */\n  implies_stewardship?: boolean;\n  /** When true, the relation can only target users flagged as minors. */\n  requires_minor?: boolean;\n  /** When true, the relation is symmetric (A→B implies B→A). */\n  bidirectional?: boolean;\n}\n\n// ── Registration fields ──\n\nexport interface RegistrationFieldDefinition {\n  /** Field key used as the form field name + in profile data. */\n  key: string;\n  /** Display label. */\n  label: string;\n  /** One of: text, email, phone, date, number, select, boolean, url, textarea. */\n  field_type: string;\n  required: boolean;\n  show_on_register: boolean;\n  /** Optional validation metadata — passed through to the UI. */\n  validation?: Record<string, unknown>;\n}\n\nexport interface RegistrationConfig {\n  /** Ordered list of custom registration fields. Declaring this replaces the full list. */\n  fields: RegistrationFieldDefinition[];\n}\n\n// ── OAuth providers ──\n\nexport interface OAuthProviderDefinition {\n  enabled: boolean;\n  client_id: string;\n  /** Prefer `{ env: \"VAR_NAME\" }` or `\"${env.VAR_NAME}\"`. */\n  client_secret: SecretRef;\n  scopes: string[];\n  /** Only for `custom_oidc`. */\n  discovery_url?: string;\n}\n\nexport interface OAuthProvidersConfig {\n  google?: OAuthProviderDefinition;\n  github?: OAuthProviderDefinition;\n  okta?: OAuthProviderDefinition;\n  custom_oidc?: OAuthProviderDefinition;\n}\n\n// ── Security ──\n\nexport interface PasswordPolicyDefinition {\n  min_length: number;\n  require_uppercase: boolean;\n  require_number: boolean;\n  require_special: boolean;\n}\n\nexport interface SessionConfigDefinition {\n  access_token_ttl_secs: number;\n  refresh_token_ttl_secs: number;\n  max_sessions_per_user: number;\n  require_email_verification: boolean;\n}\n\nexport interface SecurityConfig {\n  password_policy?: PasswordPolicyDefinition;\n  session?: SessionConfigDefinition;\n}\n\n// ── Branding ──\n\nexport interface BrandingConfig {\n  app_name?: string;\n  logo_url?: string;\n  primary_color?: string;\n  secondary_color?: string;\n  welcome_message?: string;\n  welcome_subtitle?: string;\n  /** `\"centered\"`, `\"split-left\"`, `\"split-right\"`, or `\"fullscreen\"`. */\n  layout?: string;\n  background_image_url?: string;\n  /** 0–100 percentage. */\n  background_focal_point?: { x: number; y: number };\n  background_gradient?: string;\n  /** `\"light\"`, `\"dark\"`, or `\"auto\"`. */\n  color_mode?: string;\n  font_family?: string;\n  terms_url?: string;\n  privacy_url?: string;\n  /** Raw CSS merged into the hosted auth pages. */\n  custom_css?: string;\n}\n\n// ── Top-level shape ──\n\nexport interface AuthConfigBlock {\n  resources?: ResourceDefinition[];\n  groups?: GroupDefinition[];\n  relations?: RelationTypeDefinition[];\n  registration?: RegistrationConfig;\n  oauth?: OAuthProvidersConfig;\n  security?: SecurityConfig;\n  branding?: BrandingConfig;\n}\n\nexport interface MaravillaConfig {\n  /** All project-level auth settings. Every field is optional — partial adoption is supported. */\n  auth?: AuthConfigBlock;\n  /** Declarative database indexes (regular + vector). Reconciled upsert-only on deploy. */\n  database?: DatabaseConfigBlock;\n  /**\n   * Declarative media transforms — each entry compiles into a synthetic\n   * `storage.put` event handler that fans out the declared\n   * `platform.media.transforms.*` calls (via `Promise.all`) for every\n   * matching upload. See {@link TransformsConfig}.\n   */\n  transforms?: TransformsConfig;\n}\n\n// ── Database block ──\n//\n// Regular indexes speed up document reads on frequently-queried fields.\n// Vector indexes back hybrid semantic search via sqlite-vec. Both are\n// upsert-only — declaring an index in config creates it if missing,\n// updates metadata when safe, and never auto-deletes DB-only indexes.\n\n/** MongoDB-style key direction: `1` ascending, `-1` descending. */\nexport type IndexDirectionConfig = 1 | -1;\n\nexport interface DocumentIndexDeclaration {\n  /** Collection the index lives on. */\n  collection: string;\n  /** Optional name; falls back to an auto-derived name. */\n  name?: string;\n  /**\n   * Compound-index key shape. Array of `[field, direction]` tuples\n   * preserves ordering, which matters for compound indexes.\n   */\n  keys: Array<[string, IndexDirectionConfig]> | Record<string, IndexDirectionConfig>;\n  unique?: boolean;\n  sparse?: boolean;\n  /**\n   * Partial-index predicate — restricted to inline-literal operators\n   * (`$eq`, `$ne`, `$gt`/`$gte`/`$lt`/`$lte`, `$in`/`$nin`, `$exists`,\n   * `$and`, `$or`). No `$regex` / `$where` / `$text`.\n   */\n  partial?: Record<string, unknown>;\n  /** TTL in seconds. Requires a single-field index on a unix-seconds field. */\n  expireAfterSeconds?: number;\n}\n\n/** Distance metric used by a vector index. */\nexport type VectorMetricConfig = 'cosine' | 'l2' | 'hamming';\n\n/** Storage precision for a vector index. */\nexport type VectorStorageConfig = 'float32' | 'int8' | 'bit';\n\nexport interface VectorIndexDeclaration {\n  collection: string;\n  field: string;\n  dimensions: number;\n  metric?: VectorMetricConfig;\n  storage?: VectorStorageConfig;\n  matryoshka?: boolean;\n  multiVector?: boolean;\n}\n\nexport interface DatabaseConfigBlock {\n  /** MongoDB-style secondary indexes. */\n  indexes?: DocumentIndexDeclaration[];\n  /** sqlite-vec-backed vector indexes. */\n  vectorIndexes?: VectorIndexDeclaration[];\n}\n\n/**\n * Identity function that returns the config unchanged — exists purely so the\n * TypeScript compiler can infer `MaravillaConfig` and give you IntelliSense\n * on every field.\n *\n * @example\n * ```typescript\n * import { defineConfig } from '@maravilla-labs/platform/config';\n *\n * export default defineConfig({\n *   auth: {\n *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'] }],\n *   },\n * });\n * ```\n */\nexport function defineConfig(config: MaravillaConfig): MaravillaConfig {\n  return config;\n}\n"],"mappings":";AA2RO,SAAS,aAAa,QAA0C;AACrE,SAAO;AACT;","names":[]}
+{"version":3,"sources":["../src/config.ts"],"sourcesContent":["/**\n * @fileoverview Typed schema for `maravilla.config.{ts,yaml,json}` files.\n *\n * Declares your project's auth settings (resources, groups, relations,\n * registration fields, OAuth providers, security policy, branding) alongside\n * your code. The Maravilla adapter reads this at build time and reconciles\n * the settings into delivery on deploy.\n *\n * ```typescript\n * import { defineConfig } from '@maravilla-labs/platform/config';\n *\n * export default defineConfig({\n *   auth: {\n *     resources: [\n *       { name: 'todos', title: 'Todos', actions: ['read', 'write'],\n *         policy: 'auth.user_id == node.owner' },\n *     ],\n *   },\n * });\n * ```\n *\n * Omitted sections leave the DB alone — partial adoption is explicitly\n * supported. List-based sections (`resources`, `groups`, `relations`,\n * `oauth`) are upserted and never auto-delete DB-only entries. Singleton\n * sections (`registration`, `security`, `branding`) are replaced wholesale\n * when declared.\n */\n\n/**\n * String value that may either be a literal secret or a reference to an\n * environment variable on the **tenant** (resolved server-side at\n * reconcile time, never shipped plaintext in the manifest).\n *\n * Accepted forms:\n *   - `\"literal-value\"` — inline (not recommended for real secrets)\n *   - `\"${env.VAR_NAME}\"` — string-template form\n *   - `{ env: \"VAR_NAME\" }` — object form\n */\nexport type SecretRef = string | { env: string };\n\nimport type { TransformsConfig } from './transforms.js';\nexport type { TransformsConfig, TransformsPatternSpec } from './transforms.js';\n\n// ── Resources + policies ──\n\n/**\n * The platform service this resource binds to. Used by the UI to offer\n * service-correct action presets and policy snippets, and by the reconciler\n * to validate that policies reference legal `node.*` fields for the service.\n *\n * Omit for legacy / cross-service umbrella resources — the runtime falls back\n * to matching purely by `name` (a name collision between e.g. a KV namespace\n * and a DB collection will silently share a policy, which is rarely desired).\n */\nexport type ResourceServiceType =\n  | 'kv'\n  | 'database'\n  | 'realtime'\n  | 'media'\n  | 'vector'\n  | 'storage'\n  | 'queue'\n  | 'push'\n  | 'workflow'\n  | 'transforms';\n\nexport interface ResourceDefinition {\n  /** URL-safe slug. Used as the resource key in code (e.g. the KV namespace). */\n  name: string;\n  /** Human-readable title for the admin UI. */\n  title: string;\n  /** Optional longer description. */\n  description?: string;\n  /**\n   * Which platform service this resource gates. When set, the reconciler\n   * validates that the policy only references `node.*` fields legal for that\n   * service (e.g. a `realtime` policy can't reference `node.collection`).\n   */\n  type?: ResourceServiceType;\n  /** Actions this resource supports, e.g. `['read', 'write', 'delete']`. */\n  actions: string[];\n  /**\n   * Optional raisin-rel policy expression. Evaluated on every KV/DB/\n   * realtime/media op that targets this resource. Leave empty to skip\n   * Layer 2 for this resource — tenant + owner isolation still applies.\n   */\n  policy?: string;\n  /**\n   * C+D read-filter (option ii). JSON object the runtime ANDs into the\n   * caller's filter on `db.find` / `db.findOne`. Supports `$auth.<path>`\n   * placeholder strings (e.g. `\"$auth.user_id\"`) substituted from the\n   * caller's identity at request time. Allowed paths: `user_id`, `email`,\n   * `is_admin`, `roles`.\n   *\n   * Independent of `policy` — `policy` gates writes and resolved-doc reads;\n   * `read_filter` scopes which rows the caller can ever see.\n   *\n   * Example: `'{\"$or\":[{\"owner\":\"$auth.user_id\"},{\"public\":true}]}'`\n   */\n  read_filter?: string;\n}\n\n// ── Groups ──\n\nexport interface GroupPermissionDefinition {\n  /** Must match a `ResourceDefinition.name`. */\n  resource_name: string;\n  /** Actions this group is granted on the resource. */\n  actions: string[];\n}\n\nexport interface GroupDefinition {\n  /** Unique group name per tenant. */\n  name: string;\n  /** Optional description for the admin UI. */\n  description?: string;\n  /** Resource permissions granted to the group. Replaces the group's current permissions when declared. */\n  permissions?: GroupPermissionDefinition[];\n}\n\n// ── Relations ──\n\nexport interface RelationTypeDefinition {\n  /** Uppercase identifier used in policies (`... VIA 'STEWARDS'`). */\n  relation_name: string;\n  /** Human-readable title. */\n  title: string;\n  description?: string;\n  /** Grouping for the admin UI (e.g. `\"family\"`, `\"work\"`). */\n  category?: string;\n  icon?: string;\n  color?: string;\n  /** Name of the inverse relation type, if one exists. */\n  inverse_relation_name?: string;\n  /** When true, membership in this relation implies stewardship rights. */\n  implies_stewardship?: boolean;\n  /** When true, the relation can only target users flagged as minors. */\n  requires_minor?: boolean;\n  /** When true, the relation is symmetric (A→B implies B→A). */\n  bidirectional?: boolean;\n}\n\n// ── Registration fields ──\n\nexport interface RegistrationFieldDefinition {\n  /** Field key used as the form field name + in profile data. */\n  key: string;\n  /** Display label. */\n  label: string;\n  /** One of: text, email, phone, date, number, select, boolean, url, textarea. */\n  field_type: string;\n  required: boolean;\n  show_on_register: boolean;\n  /** Optional validation metadata — passed through to the UI. */\n  validation?: Record<string, unknown>;\n}\n\nexport interface RegistrationConfig {\n  /** Ordered list of custom registration fields. Declaring this replaces the full list. */\n  fields: RegistrationFieldDefinition[];\n}\n\n// ── OAuth providers ──\n\nexport interface OAuthProviderDefinition {\n  enabled: boolean;\n  client_id: string;\n  /** Prefer `{ env: \"VAR_NAME\" }` or `\"${env.VAR_NAME}\"`. */\n  client_secret: SecretRef;\n  scopes: string[];\n  /** Only for `custom_oidc`. */\n  discovery_url?: string;\n}\n\nexport interface OAuthProvidersConfig {\n  google?: OAuthProviderDefinition;\n  github?: OAuthProviderDefinition;\n  okta?: OAuthProviderDefinition;\n  custom_oidc?: OAuthProviderDefinition;\n}\n\n// ── Security ──\n\nexport interface PasswordPolicyDefinition {\n  min_length: number;\n  require_uppercase: boolean;\n  require_number: boolean;\n  require_special: boolean;\n}\n\nexport interface SessionConfigDefinition {\n  access_token_ttl_secs: number;\n  refresh_token_ttl_secs: number;\n  max_sessions_per_user: number;\n  require_email_verification: boolean;\n}\n\nexport interface SecurityConfig {\n  password_policy?: PasswordPolicyDefinition;\n  session?: SessionConfigDefinition;\n}\n\n// ── Branding ──\n\nexport interface BrandingConfig {\n  app_name?: string;\n  logo_url?: string;\n  primary_color?: string;\n  secondary_color?: string;\n  welcome_message?: string;\n  welcome_subtitle?: string;\n  /** `\"centered\"`, `\"split-left\"`, `\"split-right\"`, or `\"fullscreen\"`. */\n  layout?: string;\n  background_image_url?: string;\n  /** 0–100 percentage. */\n  background_focal_point?: { x: number; y: number };\n  background_gradient?: string;\n  /** `\"light\"`, `\"dark\"`, or `\"auto\"`. */\n  color_mode?: string;\n  font_family?: string;\n  terms_url?: string;\n  privacy_url?: string;\n  /** Raw CSS merged into the hosted auth pages. */\n  custom_css?: string;\n}\n\n// ── Top-level shape ──\n\nexport interface AuthConfigBlock {\n  resources?: ResourceDefinition[];\n  groups?: GroupDefinition[];\n  relations?: RelationTypeDefinition[];\n  registration?: RegistrationConfig;\n  oauth?: OAuthProvidersConfig;\n  security?: SecurityConfig;\n  branding?: BrandingConfig;\n}\n\nexport interface MaravillaConfig {\n  /** All project-level auth settings. Every field is optional — partial adoption is supported. */\n  auth?: AuthConfigBlock;\n  /** Declarative database indexes (regular + vector). Reconciled upsert-only on deploy. */\n  database?: DatabaseConfigBlock;\n  /**\n   * Declarative media transforms — each entry compiles into a synthetic\n   * `storage.put` event handler that fans out the declared\n   * `platform.media.transforms.*` calls (via `Promise.all`) for every\n   * matching upload. See {@link TransformsConfig}.\n   */\n  transforms?: TransformsConfig;\n}\n\n// ── Database block ──\n//\n// Regular indexes speed up document reads on frequently-queried fields.\n// Vector indexes back hybrid semantic search via sqlite-vec. Both are\n// upsert-only — declaring an index in config creates it if missing,\n// updates metadata when safe, and never auto-deletes DB-only indexes.\n\n/** MongoDB-style key direction: `1` ascending, `-1` descending. */\nexport type IndexDirectionConfig = 1 | -1;\n\nexport interface DocumentIndexDeclaration {\n  /** Collection the index lives on. */\n  collection: string;\n  /** Optional name; falls back to an auto-derived name. */\n  name?: string;\n  /**\n   * Compound-index key shape. Array of `[field, direction]` tuples\n   * preserves ordering, which matters for compound indexes.\n   */\n  keys: Array<[string, IndexDirectionConfig]> | Record<string, IndexDirectionConfig>;\n  unique?: boolean;\n  sparse?: boolean;\n  /**\n   * Partial-index predicate — restricted to inline-literal operators\n   * (`$eq`, `$ne`, `$gt`/`$gte`/`$lt`/`$lte`, `$in`/`$nin`, `$exists`,\n   * `$and`, `$or`). No `$regex` / `$where` / `$text`.\n   */\n  partial?: Record<string, unknown>;\n  /** TTL in seconds. Requires a single-field index on a unix-seconds field. */\n  expireAfterSeconds?: number;\n}\n\n/** Distance metric used by a vector index. */\nexport type VectorMetricConfig = 'cosine' | 'l2' | 'hamming';\n\n/** Storage precision for a vector index. */\nexport type VectorStorageConfig = 'float32' | 'int8' | 'bit';\n\nexport interface VectorIndexDeclaration {\n  collection: string;\n  field: string;\n  dimensions: number;\n  metric?: VectorMetricConfig;\n  storage?: VectorStorageConfig;\n  matryoshka?: boolean;\n  multiVector?: boolean;\n}\n\nexport interface DatabaseConfigBlock {\n  /** MongoDB-style secondary indexes. */\n  indexes?: DocumentIndexDeclaration[];\n  /** sqlite-vec-backed vector indexes. */\n  vectorIndexes?: VectorIndexDeclaration[];\n}\n\n/**\n * Identity function that returns the config unchanged — exists purely so the\n * TypeScript compiler can infer `MaravillaConfig` and give you IntelliSense\n * on every field.\n *\n * @example\n * ```typescript\n * import { defineConfig } from '@maravilla-labs/platform/config';\n *\n * export default defineConfig({\n *   auth: {\n *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'] }],\n *   },\n * });\n * ```\n */\nexport function defineConfig(config: MaravillaConfig): MaravillaConfig {\n  return config;\n}\n"],"mappings":";AAmUO,SAAS,aAAa,QAA0C;AACrE,SAAO;AACT;","names":[]}

package/dist/index.d.ts

@@ -945,6 +945,201 @@ interface UpdateUserOptions {
     /** Profile data to merge */
     profile?: Record<string, any>;
 }
+interface AuthGroup {
+    id: string;
+    name: string;
+    description: string | null;
+    permissions: string[];
+    member_count: number;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateGroupOptions {
+    name: string;
+    description?: string;
+    permissions?: string[];
+}
+interface UpdateGroupOptions {
+    name?: string;
+    description?: string;
+    permissions?: string[];
+}
+interface GroupPermission {
+    resource_name: string;
+    actions: string[];
+}
+interface AuthCircle {
+    id: string;
+    name: string;
+    metadata: Record<string, any> | null;
+    member_count: number;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateCircleOptions {
+    name: string;
+    metadata?: Record<string, any>;
+}
+interface UpdateCircleOptions {
+    name?: string;
+    metadata?: Record<string, any>;
+}
+interface AddCircleMemberOptions {
+    user_id: string;
+    relationship: string;
+    is_primary_contact?: boolean;
+}
+interface CircleMembership {
+    user_id: string;
+    email: string;
+    relationship: string;
+    is_primary_contact: boolean;
+    joined_at: number;
+}
+type ResourceServiceType = 'kv' | 'database' | 'realtime' | 'media' | 'vector' | 'storage' | 'queue' | 'push' | 'workflow' | 'transforms';
+interface Resource {
+    id: string;
+    resource_name: string;
+    title: string;
+    description: string | null;
+    actions: string[];
+    policy: string | null;
+    service_type: ResourceServiceType | null;
+    read_filter: string | null;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateResourceOptions {
+    resource_name: string;
+    title: string;
+    description?: string;
+    actions?: string[];
+    policy?: string;
+    service_type?: ResourceServiceType;
+    read_filter?: string;
+}
+interface UpdateResourceOptions {
+    title?: string;
+    description?: string;
+    actions?: string[];
+    policy?: string;
+    service_type?: ResourceServiceType;
+    read_filter?: string;
+}
+interface RelationType {
+    id: string;
+    relation_name: string;
+    title: string;
+    description: string | null;
+    category: string;
+    icon: string | null;
+    color: string | null;
+    inverse_relation_id: string | null;
+    implies_stewardship: boolean;
+    requires_minor: boolean;
+    bidirectional: boolean;
+    is_system: boolean;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateRelationTypeOptions {
+    relation_name: string;
+    title: string;
+    description?: string;
+    category?: string;
+    icon?: string;
+    color?: string;
+    inverse_relation_id?: string;
+    implies_stewardship?: boolean;
+    requires_minor?: boolean;
+    bidirectional?: boolean;
+    is_system?: boolean;
+}
+interface UpdateRelationTypeOptions {
+    title?: string;
+    description?: string;
+    category?: string;
+    icon?: string;
+    color?: string;
+    inverse_relation_id?: string;
+    implies_stewardship?: boolean;
+    requires_minor?: boolean;
+    bidirectional?: boolean;
+}
+interface AuthConfig {
+    fields: AuthField[];
+    oauth_providers: any[];
+    branding: Record<string, any>;
+    password_policy: Record<string, any>;
+    session_config: Record<string, any>;
+}
+type DelegationMode = 'full' | 'scoped';
+type StewardshipStatus = 'active' | 'suspended' | 'revoked' | 'expired';
+interface ScopedPermission {
+    resource: string;
+    actions: string[];
+}
+interface StewardshipOverride {
+    id: string;
+    steward_id: string;
+    ward_id: string;
+    delegation_mode: DelegationMode;
+    scoped_permissions: ScopedPermission[];
+    valid_from: number | null;
+    valid_until: number | null;
+    status: StewardshipStatus;
+    reason: string | null;
+    source: string;
+    source_circle_id: string | null;
+    source_relation_type_id: string | null;
+    created_at: number;
+    updated_at: number;
+}
+interface CreateStewardshipOverrideOptions {
+    steward_id: string;
+    ward_id: string;
+    delegation_mode?: DelegationMode;
+    scoped_permissions?: ScopedPermission[];
+    valid_from?: number;
+    valid_until?: number;
+    reason?: string;
+}
+interface StewardshipResolution {
+    stewards: StewardshipOverride[];
+    wards: StewardshipOverride[];
+}
+interface ActAsContext {
+    steward_id: string;
+    ward_id: string;
+    delegation_mode: DelegationMode;
+    scoped_permissions: ScopedPermission[];
+    session_token: string;
+    expires_at: number;
+}
+interface StewardshipAuditEntry {
+    id: string;
+    performed_by: string;
+    on_behalf_of: string;
+    action: string;
+    resource: string | null;
+    details: Record<string, any> | null;
+    created_at: number;
+}
+/**
+ * Sub-namespace exposed at `platform.auth.stewardship` mirroring the
+ * runtime's `globalThis.platform.auth.stewardship.*` surface.
+ */
+interface AuthStewardshipApi {
+    resolve(userId: string): Promise<StewardshipResolution>;
+    createOverride(opts: CreateStewardshipOverrideOptions): Promise<StewardshipOverride>;
+    revoke(id: string): Promise<void>;
+    checkPermission(stewardId: string, wardId: string, resource: string, action: string): Promise<boolean>;
+    createActAs(stewardId: string, wardId: string): Promise<ActAsContext>;
+    listAudit(userId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<StewardshipAuditEntry[]>;
+}
 /**
  * Auth service for end-user authentication and user management.
  *
@@ -1106,6 +1301,39 @@ interface AuthService {
     withAuth<T extends (request: Request & {
         user: AuthUser;
     }) => Promise<Response>>(handler: T): (request: Request) => Promise<Response>;
+    createGroup(options: CreateGroupOptions): Promise<AuthGroup>;
+    listGroups(): Promise<AuthGroup[]>;
+    getGroup(groupId: string): Promise<AuthGroup | null>;
+    updateGroup(groupId: string, options: UpdateGroupOptions): Promise<AuthGroup>;
+    deleteGroup(groupId: string): Promise<void>;
+    addUserToGroup(userId: string, groupId: string): Promise<void>;
+    removeUserFromGroup(userId: string, groupId: string): Promise<void>;
+    getUserGroups(userId: string): Promise<AuthGroup[]>;
+    getGroupMembers(groupId: string): Promise<AuthUser[]>;
+    getGroupPermissions(groupId: string): Promise<GroupPermission[]>;
+    setGroupPermissions(groupId: string, permissions: GroupPermission[]): Promise<void>;
+    createCircle(options: CreateCircleOptions): Promise<AuthCircle>;
+    listCircles(): Promise<AuthCircle[]>;
+    getCircle(circleId: string): Promise<AuthCircle | null>;
+    updateCircle(circleId: string, options: UpdateCircleOptions): Promise<AuthCircle>;
+    deleteCircle(circleId: string): Promise<void>;
+    addCircleMember(circleId: string, options: AddCircleMemberOptions): Promise<void>;
+    removeCircleMember(circleId: string, userId: string): Promise<void>;
+    getCircleMembers(circleId: string): Promise<CircleMembership[]>;
+    getUserCircles(userId: string): Promise<AuthCircle[]>;
+    createResource(options: CreateResourceOptions): Promise<Resource>;
+    listResources(): Promise<Resource[]>;
+    updateResource(resourceId: string, options: UpdateResourceOptions): Promise<Resource>;
+    deleteResource(resourceId: string): Promise<void>;
+    createRelationType(options: CreateRelationTypeOptions): Promise<RelationType>;
+    listRelationTypes(): Promise<RelationType[]>;
+    updateRelationType(id: string, options: UpdateRelationTypeOptions): Promise<RelationType>;
+    deleteRelationType(id: string): Promise<void>;
+    getProfile(userId: string): Promise<Record<string, any>>;
+    setProfile(userId: string, data: Record<string, any>): Promise<void>;
+    getAuthConfig(): Promise<AuthConfig>;
+    setAuthConfig(config: AuthConfig): Promise<void>;
+    readonly stewardship: AuthStewardshipApi;
     /**
      * Explicitly bind the caller for the remainder of this request.
      * Pass a JWT to validate + bind, or `null` / `""` to clear.
@@ -1652,6 +1880,64 @@ declare class MediaRoom {
     private wireEvents;
 }
 
+/**
+ * Per-request scope for the SDK's remote client. Mirrors the runtime's
+ * `REQUEST_CTX` (a `tokio::task_local!` in Rust) so that
+ * `platform.auth.setCurrentUser(token)`, `getCurrentUser()`, and `can()`
+ * — plus future per-request state like the Layer-2 policy toggle —
+ * have a place to live when the SDK is running outside the runtime
+ * (Vite SSR, Node.js HTTP servers, edge workers that expose Node APIs).
+ *
+ * Implementation: Node's `AsyncLocalStorage`. Tenant code wraps each
+ * inbound request with `runWithRequest(async () => { ... })` so the
+ * store stays scoped to the request's async chain. `setCurrentUser`
+ * / `can` read and write that store; if a tenant forgets to wrap, the
+ * methods either no-op (set) or throw a clear error (get/can).
+ */
+
+interface RequestStore {
+    /** Bound access-token JWT (set by `auth.setCurrentUser`). */
+    token?: string;
+    /** Bound user (cached so `getCurrentUser` doesn't re-validate). */
+    user?: AuthUser;
+    /** Whether Layer-2 policy enforcement is enabled for this request. */
+    policyEnabled: boolean;
+}
+/**
+ * Wrap a function in a fresh request scope. **Rarely needed** — the
+ * Maravilla Vite plugin (`@maravilla-labs/vite-plugin`) auto-opens a
+ * scope around every inbound dev HTTP request, so tenant code
+ * (SvelteKit `hooks.server.ts`, RR/Remix loaders, etc.) reaches
+ * `setCurrentUser/getCurrentUser/can` with a scope already active.
+ *
+ * Reach for `runWithRequest` only when the SDK runs **outside** an
+ * HTTP request: standalone Node scripts, test fixtures, custom
+ * servers that don't go through Vite. Inside an active scope,
+ * `platform.auth.setCurrentUser/getCurrentUser/can` operate on a
+ * per-request store keyed by Node's `AsyncLocalStorage`.
+ *
+ * @example
+ * ```ts
+ * // Test fixture that needs to bind a user before exercising the SDK
+ * await runWithRequest(async () => {
+ *   await getPlatform().auth.setCurrentUser(testToken);
+ *   const result = await getPlatform().env.DB.find('users', {});
+ *   expect(result).toEqual(...);
+ * });
+ * ```
+ */
+declare function runWithRequest<T>(fn: () => Promise<T> | T): Promise<T>;
+/**
+ * Read the current request's store, if any. Returns undefined when
+ * called outside a `runWithRequest` scope. Used by `RemoteAuthService`
+ * and (future) other Remote* services to source per-request state.
+ *
+ * Note: the `als` may not yet be initialised when this is called; in
+ * that case the function returns undefined synchronously. Subsequent
+ * `runWithRequest` calls will populate it.
+ */
+declare function getCurrentRequestStore(): RequestStore | undefined;
+
 /**
  * @fileoverview Maravilla Platform SDK
  *
@@ -1772,4 +2058,4 @@ declare function getPlatform(options?: {
  */
 declare function clearPlatformCache(): void;
 
-export { type AuthCaller, type AuthField, type AuthService, type AuthSession, type AuthUser, type Database, type DbFindOptions, type IndexDescriptor, type IndexDirection, type IndexKind, type IndexSpec, type KvListResult, type KvNamespace, type ListScheduledFilter, type LoginOptions, MediaLocalParticipant, type MediaParticipant, type MediaParticipantInfo, MediaRoom, MediaRoomEvent, type MediaRoomInfo, type MediaRoomInfoSettings, type MediaRoomOptions, type MediaService, type MediaTokenResult, type MediaTrackPublication, type NotificationPayload, type Platform, type PlatformEnv, type PolicyService, type PresenceMember, type PresenceService, type PublicPushConfig, type PushService, type PushTarget, type QueueStats, RealtimeClient, type RealtimeClientOptions, type RealtimeEvent, type RealtimeService, type RegisterOptions, RemoteMediaService, type ScheduleOptions, type ScheduledJob, type SendReport, type Storage, type StoragePutStreamSource, type StoredPushSubscription, type SubscriptionCounts, type TrackKind, type TrackSource, type UpdateUserOptions, type UserListFilter, type UserListResponse, type VectorAggregation, type VectorIndexDescriptor, type VectorIndexSpec, type VectorMetric, type VectorQuery, type VectorQueryMode, type VectorQueryWithFilter, type VectorSearchHit, type VectorStorage, type VideoResolution, type WorkflowHandle, type WorkflowRun, type WorkflowRunStatus, type WorkflowStepKind, type WorkflowStepRecord, type Workflows, attachTrack, clearPlatformCache, detachTrack, getPlatform };
+export { type ActAsContext, type AddCircleMemberOptions, type AuthCaller, type AuthCircle, type AuthConfig, type AuthField, type AuthGroup, type AuthService, type AuthSession, type AuthStewardshipApi, type AuthUser, type CircleMembership, type CreateCircleOptions, type CreateGroupOptions, type CreateRelationTypeOptions, type CreateResourceOptions, type CreateStewardshipOverrideOptions, type Database, type DbFindOptions, type DelegationMode, type GroupPermission, type IndexDescriptor, type IndexDirection, type IndexKind, type IndexSpec, type KvListResult, type KvNamespace, type ListScheduledFilter, type LoginOptions, MediaLocalParticipant, type MediaParticipant, type MediaParticipantInfo, MediaRoom, MediaRoomEvent, type MediaRoomInfo, type MediaRoomInfoSettings, type MediaRoomOptions, type MediaService, type MediaTokenResult, type MediaTrackPublication, type NotificationPayload, type Platform, type PlatformEnv, type PolicyService, type PresenceMember, type PresenceService, type PublicPushConfig, type PushService, type PushTarget, type QueueStats, RealtimeClient, type RealtimeClientOptions, type RealtimeEvent, type RealtimeService, type RegisterOptions, type RelationType, RemoteMediaService, type RequestStore, type Resource, type ResourceServiceType, type ScheduleOptions, type ScheduledJob, type ScopedPermission, type SendReport, type StewardshipAuditEntry, type StewardshipOverride, type StewardshipResolution, type StewardshipStatus, type Storage, type StoragePutStreamSource, type StoredPushSubscription, type SubscriptionCounts, type TrackKind, type TrackSource, type UpdateCircleOptions, type UpdateGroupOptions, type UpdateRelationTypeOptions, type UpdateResourceOptions, type UpdateUserOptions, type UserListFilter, type UserListResponse, type VectorAggregation, type VectorIndexDescriptor, type VectorIndexSpec, type VectorMetric, type VectorQuery, type VectorQueryMode, type VectorQueryWithFilter, type VectorSearchHit, type VectorStorage, type VideoResolution, type WorkflowHandle, type WorkflowRun, type WorkflowRunStatus, type WorkflowStepKind, type WorkflowStepRecord, type Workflows, attachTrack, clearPlatformCache, detachTrack, getCurrentRequestStore, getPlatform, runWithRequest };