@maravilla-labs/platform 0.1.35 → 0.1.38

package/dist/config.d.ts

@@ -0,0 +1,192 @@
+/**
+ * @fileoverview Typed schema for `maravilla.config.{ts,yaml,json}` files.
+ *
+ * Declares your project's auth settings (resources, groups, relations,
+ * registration fields, OAuth providers, security policy, branding) alongside
+ * your code. The Maravilla adapter reads this at build time and reconciles
+ * the settings into delivery on deploy.
+ *
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [
+ *       { name: 'todos', title: 'Todos', actions: ['read', 'write'],
+ *         policy: 'auth.user_id == node.owner' },
+ *     ],
+ *   },
+ * });
+ * ```
+ *
+ * Omitted sections leave the DB alone — partial adoption is explicitly
+ * supported. List-based sections (`resources`, `groups`, `relations`,
+ * `oauth`) are upserted and never auto-delete DB-only entries. Singleton
+ * sections (`registration`, `security`, `branding`) are replaced wholesale
+ * when declared.
+ */
+/**
+ * String value that may either be a literal secret or a reference to an
+ * environment variable on the **tenant** (resolved server-side at
+ * reconcile time, never shipped plaintext in the manifest).
+ *
+ * Accepted forms:
+ *   - `"literal-value"` — inline (not recommended for real secrets)
+ *   - `"${env.VAR_NAME}"` — string-template form
+ *   - `{ env: "VAR_NAME" }` — object form
+ */
+type SecretRef = string | {
+    env: string;
+};
+interface ResourceDefinition {
+    /** URL-safe slug. Used as the resource key in code (e.g. the KV namespace). */
+    name: string;
+    /** Human-readable title for the admin UI. */
+    title: string;
+    /** Optional longer description. */
+    description?: string;
+    /** Actions this resource supports, e.g. `['read', 'write', 'delete']`. */
+    actions: string[];
+    /**
+     * 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.
+     */
+    policy?: string;
+}
+interface GroupPermissionDefinition {
+    /** Must match a `ResourceDefinition.name`. */
+    resource_name: string;
+    /** Actions this group is granted on the resource. */
+    actions: string[];
+}
+interface GroupDefinition {
+    /** Unique group name per tenant. */
+    name: string;
+    /** Optional description for the admin UI. */
+    description?: string;
+    /** Resource permissions granted to the group. Replaces the group's current permissions when declared. */
+    permissions?: GroupPermissionDefinition[];
+}
+interface RelationTypeDefinition {
+    /** Uppercase identifier used in policies (`... VIA 'STEWARDS'`). */
+    relation_name: string;
+    /** Human-readable title. */
+    title: string;
+    description?: string;
+    /** Grouping for the admin UI (e.g. `"family"`, `"work"`). */
+    category?: string;
+    icon?: string;
+    color?: string;
+    /** Name of the inverse relation type, if one exists. */
+    inverse_relation_name?: string;
+    /** When true, membership in this relation implies stewardship rights. */
+    implies_stewardship?: boolean;
+    /** When true, the relation can only target users flagged as minors. */
+    requires_minor?: boolean;
+    /** When true, the relation is symmetric (A→B implies B→A). */
+    bidirectional?: boolean;
+}
+interface RegistrationFieldDefinition {
+    /** Field key used as the form field name + in profile data. */
+    key: string;
+    /** Display label. */
+    label: string;
+    /** One of: text, email, phone, date, number, select, boolean, url, textarea. */
+    field_type: string;
+    required: boolean;
+    show_on_register: boolean;
+    /** Optional validation metadata — passed through to the UI. */
+    validation?: Record<string, unknown>;
+}
+interface RegistrationConfig {
+    /** Ordered list of custom registration fields. Declaring this replaces the full list. */
+    fields: RegistrationFieldDefinition[];
+}
+interface OAuthProviderDefinition {
+    enabled: boolean;
+    client_id: string;
+    /** Prefer `{ env: "VAR_NAME" }` or `"${env.VAR_NAME}"`. */
+    client_secret: SecretRef;
+    scopes: string[];
+    /** Only for `custom_oidc`. */
+    discovery_url?: string;
+}
+interface OAuthProvidersConfig {
+    google?: OAuthProviderDefinition;
+    github?: OAuthProviderDefinition;
+    okta?: OAuthProviderDefinition;
+    custom_oidc?: OAuthProviderDefinition;
+}
+interface PasswordPolicyDefinition {
+    min_length: number;
+    require_uppercase: boolean;
+    require_number: boolean;
+    require_special: boolean;
+}
+interface SessionConfigDefinition {
+    access_token_ttl_secs: number;
+    refresh_token_ttl_secs: number;
+    max_sessions_per_user: number;
+    require_email_verification: boolean;
+}
+interface SecurityConfig {
+    password_policy?: PasswordPolicyDefinition;
+    session?: SessionConfigDefinition;
+}
+interface BrandingConfig {
+    app_name?: string;
+    logo_url?: string;
+    primary_color?: string;
+    secondary_color?: string;
+    welcome_message?: string;
+    welcome_subtitle?: string;
+    /** `"centered"`, `"split-left"`, `"split-right"`, or `"fullscreen"`. */
+    layout?: string;
+    background_image_url?: string;
+    /** 0–100 percentage. */
+    background_focal_point?: {
+        x: number;
+        y: number;
+    };
+    background_gradient?: string;
+    /** `"light"`, `"dark"`, or `"auto"`. */
+    color_mode?: string;
+    font_family?: string;
+    terms_url?: string;
+    privacy_url?: string;
+    /** Raw CSS merged into the hosted auth pages. */
+    custom_css?: string;
+}
+interface AuthConfigBlock {
+    resources?: ResourceDefinition[];
+    groups?: GroupDefinition[];
+    relations?: RelationTypeDefinition[];
+    registration?: RegistrationConfig;
+    oauth?: OAuthProvidersConfig;
+    security?: SecurityConfig;
+    branding?: BrandingConfig;
+}
+interface MaravillaConfig {
+    /** All project-level auth settings. Every field is optional — partial adoption is supported. */
+    auth?: AuthConfigBlock;
+}
+/**
+ * Identity function that returns the config unchanged — exists purely so the
+ * TypeScript compiler can infer `MaravillaConfig` and give you IntelliSense
+ * on every field.
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@maravilla-labs/platform/config';
+ *
+ * export default defineConfig({
+ *   auth: {
+ *     resources: [{ name: 'todos', title: 'Todos', actions: ['read', 'write'] }],
+ *   },
+ * });
+ * ```
+ */
+declare function defineConfig(config: MaravillaConfig): MaravillaConfig;
+
+export { type AuthConfigBlock, type BrandingConfig, type GroupDefinition, type GroupPermissionDefinition, type MaravillaConfig, type OAuthProviderDefinition, type OAuthProvidersConfig, type PasswordPolicyDefinition, type RegistrationConfig, type RegistrationFieldDefinition, type RelationTypeDefinition, type ResourceDefinition, type SecretRef, type SecurityConfig, type SessionConfigDefinition, defineConfig };

package/dist/config.js

@@ -0,0 +1,8 @@
+// src/config.ts
+function defineConfig(config) {
+  return config;
+}
+export {
+  defineConfig
+};
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +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\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}\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":";AAwNO,SAAS,aAAa,QAA0C;AACrE,SAAO;AACT;","names":[]}

package/dist/index.d.ts

@@ -598,6 +598,354 @@ interface PresenceService {
         lastSeen?: number;
     }>>;
 }
+/**
+ * Authenticated user record from the platform auth service.
+ */
+interface AuthUser {
+    /** Unique user ID (prefixed with "usr_") */
+    id: string;
+    /** User's email address */
+    email: string;
+    /** Whether the email has been verified */
+    email_verified: boolean;
+    /** Account status */
+    status: 'active' | 'suspended' | 'deactivated';
+    /** Authentication provider ("email", "google", "github", etc.) */
+    provider: string;
+    /** Group IDs the user belongs to */
+    groups: string[];
+    /** Unix timestamp when the user was created */
+    created_at: number;
+    /** Unix timestamp when the user was last updated */
+    updated_at: number;
+    /** Unix timestamp of last login (if any) */
+    last_login_at?: number;
+}
+/**
+ * Snapshot of whoever is currently bound to the request as the caller.
+ *
+ * Populated by {@link AuthService.login} (implicit), {@link AuthService.setCurrentUser}
+ * (explicit), or left anonymous if neither has run for this request.
+ * This is exactly what per-resource policies see as `auth.*` when they run.
+ */
+interface AuthCaller {
+    /** Caller's user id, or `""` if anonymous */
+    user_id: string;
+    /** Caller's email, or `""` if anonymous */
+    email: string;
+    /** Admin flag from the session */
+    is_admin: boolean;
+    /** Role names (project-scoped) */
+    roles: string[];
+    /** `true` when no identity is bound to this request */
+    is_anonymous: boolean;
+}
+/**
+ * Session returned after successful login or token refresh.
+ */
+interface AuthSession {
+    /** Short-lived JWT access token (default 15 min) */
+    access_token: string;
+    /** Single-use opaque refresh token (default 30 days) */
+    refresh_token: string;
+    /** Access token lifetime in seconds */
+    expires_in: number;
+    /** The authenticated user */
+    user: AuthUser;
+}
+/**
+ * Custom registration field defined in project auth settings.
+ */
+interface AuthField {
+    /** Field key (used as form field name) */
+    key: string;
+    /** Display label */
+    label: string;
+    /** Field type: text, email, phone, date, number, select, boolean, url, textarea */
+    field_type: string;
+    /** Whether the field is required */
+    required: boolean;
+    /** Whether the field appears on the registration form */
+    show_on_register: boolean;
+}
+/**
+ * Options for registering a new user.
+ */
+interface RegisterOptions {
+    /** User's email address */
+    email: string;
+    /** Password (minimum 8 characters) */
+    password: string;
+    /** Optional profile data (custom fields) */
+    profile?: Record<string, any>;
+}
+/**
+ * Options for logging in.
+ */
+interface LoginOptions {
+    /** User's email address */
+    email: string;
+    /** User's password */
+    password: string;
+}
+/**
+ * Filter options for listing users.
+ */
+interface UserListFilter {
+    /** Max results per page (default 50) */
+    limit?: number;
+    /** Number of results to skip */
+    offset?: number;
+    /** Filter by account status */
+    status?: 'active' | 'suspended' | 'deactivated';
+    /** Filter by email (partial match) */
+    email_contains?: string;
+    /** Filter by group ID */
+    group_id?: string;
+}
+/**
+ * Paginated user list response.
+ */
+interface UserListResponse {
+    /** Users in this page */
+    users: AuthUser[];
+    /** Total number of matching users */
+    total: number;
+    /** Page size */
+    limit: number;
+    /** Offset */
+    offset: number;
+}
+/**
+ * Options for updating a user.
+ */
+interface UpdateUserOptions {
+    /** New email address */
+    email?: string;
+    /** New status */
+    status?: 'active' | 'suspended' | 'deactivated';
+    /** Profile data to merge */
+    profile?: Record<string, any>;
+}
+/**
+ * Auth service for end-user authentication and user management.
+ *
+ * @example
+ * ```typescript
+ * const platform = getPlatform();
+ *
+ * // Register a new user
+ * const user = await platform.auth.register({
+ *   email: 'user@example.com',
+ *   password: 'securePassword123'
+ * });
+ *
+ * // Login
+ * const session = await platform.auth.login({
+ *   email: 'user@example.com',
+ *   password: 'securePassword123'
+ * });
+ * // session.access_token — short-lived JWT
+ * // session.refresh_token — single-use refresh token
+ *
+ * // Validate a token (e.g. from Authorization header or cookie)
+ * const user = await platform.auth.validate(session.access_token);
+ *
+ * // Protect a route with withAuth middleware
+ * export default {
+ *   fetch: platform.auth.withAuth(async (request) => {
+ *     // request.user is guaranteed to be set
+ *     return new Response(`Hello ${request.user.email}`);
+ *   })
+ * };
+ * ```
+ */
+interface AuthService {
+    /**
+     * Register a new user with email and password.
+     * @returns The created user (not yet email-verified)
+     */
+    register(options: RegisterOptions): Promise<AuthUser>;
+    /**
+     * Authenticate a user and create a session.
+     * @returns Session with access token, refresh token, and user info
+     */
+    login(options: LoginOptions): Promise<AuthSession>;
+    /**
+     * Validate an access token and return the authenticated user.
+     * @param accessToken - JWT access token from login or refresh
+     * @throws If the token is invalid or expired
+     */
+    validate(accessToken: string): Promise<AuthUser>;
+    /**
+     * Refresh a session using a refresh token (single-use).
+     * @param refreshToken - The refresh token from a previous login/refresh
+     * @returns New session with fresh access and refresh tokens
+     */
+    refresh(refreshToken: string): Promise<AuthSession>;
+    /**
+     * Revoke a specific session.
+     */
+    logout(sessionId: string): Promise<void>;
+    /**
+     * Get a user by ID.
+     * @returns The user, or null if not found
+     */
+    getUser(userId: string): Promise<AuthUser | null>;
+    /**
+     * List users with optional filtering and pagination.
+     */
+    listUsers(filter?: UserListFilter): Promise<UserListResponse>;
+    /**
+     * Update a user's email, status, or profile data.
+     */
+    updateUser(userId: string, update: UpdateUserOptions): Promise<AuthUser>;
+    /**
+     * Delete a user and all their sessions.
+     */
+    deleteUser(userId: string): Promise<void>;
+    /**
+     * Create an email verification token.
+     * @returns The verification token (caller decides how to deliver it)
+     */
+    sendVerification(userId: string): Promise<{
+        token: string;
+    }>;
+    /**
+     * Verify an email address using a verification token.
+     */
+    verifyEmail(token: string): Promise<void>;
+    /**
+     * Create a password reset token for an email address.
+     * @returns The reset token (caller decides how to deliver it)
+     */
+    sendPasswordReset(email: string): Promise<{
+        token: string;
+    }>;
+    /**
+     * Reset a password using a reset token.
+     */
+    resetPassword(token: string, newPassword: string): Promise<void>;
+    /**
+     * Change a user's password (requires old password).
+     */
+    changePassword(userId: string, oldPassword: string, newPassword: string): Promise<void>;
+    /**
+     * Get the configured registration fields for this project.
+     */
+    getFieldConfig(): Promise<{
+        fields: AuthField[];
+    }>;
+    /**
+     * Start an OAuth flow by generating an authorization URL.
+     * Redirect the user to the returned URL to begin authentication.
+     *
+     * @param provider - Provider name: "google", "github", "okta", or "custom_oidc"
+     * @param options - Optional configuration
+     * @returns Object with `auth_url` (redirect target) and `state` (for CSRF verification)
+     */
+    getOAuthUrl(provider: string, options?: {
+        redirectUri?: string;
+    }): Promise<{
+        auth_url: string;
+        state: string;
+    }>;
+    /**
+     * Complete an OAuth flow by exchanging the authorization code.
+     * Call this after the provider redirects back with a code and state.
+     *
+     * @param provider - Provider name
+     * @param params - The code and state from the OAuth callback
+     * @returns Either a session (user authenticated) or a link_required result
+     */
+    handleOAuthCallback(provider: string, params: {
+        code: string;
+        state: string;
+    }): Promise<AuthSession | {
+        type: 'LinkRequired';
+        email: string;
+        provider: string;
+        provider_id: string;
+        existing_user_id: string;
+    }>;
+    /**
+     * Middleware helper that validates auth and injects `request.user`.
+     * Returns 401 JSON response if no valid token is found.
+     *
+     * Extracts token from `Authorization: Bearer <token>` header
+     * or `__session` cookie.
+     *
+     * @example
+     * ```typescript
+     * export default {
+     *   fetch: platform.auth.withAuth(async (request) => {
+     *     const data = await platform.db.items.find({ owner: request.user.id });
+     *     return Response.json(data);
+     *   })
+     * };
+     * ```
+     */
+    withAuth<T extends (request: Request & {
+        user: AuthUser;
+    }) => Promise<Response>>(handler: T): (request: Request) => Promise<Response>;
+    /**
+     * Explicitly bind the caller for the remainder of this request.
+     * Pass a JWT to validate + bind, or `null` / `""` to clear.
+     *
+     * `login()` already binds implicitly on success; reach for `setCurrentUser`
+     * when you receive a JWT from an inbound `Authorization` header or cookie
+     * and want subsequent KV/DB/realtime/media ops to run as that user.
+     *
+     * Not available on remote clients — throws.
+     */
+    setCurrentUser(token: string | null): Promise<void>;
+    /**
+     * Snapshot of the currently bound caller. Returns an anonymous caller
+     * (`is_anonymous: true`) when no identity has been bound.
+     *
+     * Not available on remote clients — throws.
+     */
+    getCurrentUser(): AuthCaller;
+    /**
+     * Ask the policy engine whether the bound caller would be allowed to
+     * perform `action` on `resourceId`, given the supplied `node` payload.
+     * Returns a boolean — never throws on denial.
+     *
+     * The check runs the exact same evaluator that gates direct KV/DB/
+     * realtime/media ops, so `can(...)` is authoritative.
+     *
+     * @example
+     * ```typescript
+     * const ok = await platform.auth.can("delete", "documents", {
+     *   owner: doc.owner,
+     *   status: doc.status,
+     * });
+     * if (!ok) return new Response("Forbidden", { status: 403 });
+     * ```
+     *
+     * Not available on remote clients — throws.
+     */
+    can(action: string, resourceId: string, node?: Record<string, unknown> | null): Promise<boolean>;
+}
+/**
+ * Per-request opt-out toggle for the Layer 2 policy evaluator.
+ *
+ * Flipping `setEnabled(false)` disables **per-resource policies only** for
+ * the remainder of the current request. Layer 1 (tenant + owner isolation)
+ * is always enforced — no call can ever escape its tenant. Every flip is
+ * audit-logged server-side with the caller's identity.
+ *
+ * Intended for trusted in-app flows (first-run seeders, admin jobs). Do not
+ * toggle based on untrusted input.
+ *
+ * Not available on remote clients — throws.
+ */
+interface PolicyService {
+    /** Disable or re-enable Layer 2 policy checks for this request. */
+    setEnabled(enabled: boolean): void;
+    /** `true` when Layer 2 is active for this request. */
+    isEnabled(): boolean;
+}
 interface Platform {
     /** Environment containing all available platform services */
     env: PlatformEnv;
@@ -605,6 +953,10 @@ interface Platform {
     media?: MediaService;
     /** Realtime service for pub/sub channels and presence */
     realtime: RealtimeService;
+    /** Auth service for end-user authentication, identity binding, and authorization checks */
+    auth: AuthService;
+    /** Per-request Layer 2 policy toggle (Layer 1 isolation always applies) */
+    policy: PolicyService;
 }
 
 interface RenEvent {
@@ -967,4 +1319,4 @@ declare function getPlatform(options?: {
  */
 declare function clearPlatformCache(): void;
 
-export { type Database, type DbFindOptions, type KvListResult, type KvNamespace, MediaLocalParticipant, type MediaParticipant, type MediaParticipantInfo, MediaRoom, MediaRoomEvent, type MediaRoomInfo, type MediaRoomInfoSettings, type MediaRoomOptions, type MediaService, type MediaTokenResult, type MediaTrackPublication, type Platform, type PlatformEnv, type PresenceMember, type PresenceService, RealtimeClient, type RealtimeClientOptions, type RealtimeEvent, type RealtimeService, RemoteMediaService, RenClient, type RenClientOptions, type RenEvent, type Storage$1 as Storage, type StoragePutStreamSource, type TrackKind, type TrackSource, type VideoResolution, attachTrack, clearPlatformCache, detachTrack, getOrCreateClientId, getPlatform, renFetch, storageDelete, storageUpload };
+export { type AuthCaller, type AuthField, type AuthService, type AuthSession, type AuthUser, type Database, type DbFindOptions, type KvListResult, type KvNamespace, type LoginOptions, MediaLocalParticipant, type MediaParticipant, type MediaParticipantInfo, MediaRoom, MediaRoomEvent, type MediaRoomInfo, type MediaRoomInfoSettings, type MediaRoomOptions, type MediaService, type MediaTokenResult, type MediaTrackPublication, type Platform, type PlatformEnv, type PolicyService, type PresenceMember, type PresenceService, RealtimeClient, type RealtimeClientOptions, type RealtimeEvent, type RealtimeService, type RegisterOptions, RemoteMediaService, RenClient, type RenClientOptions, type RenEvent, type Storage$1 as Storage, type StoragePutStreamSource, type TrackKind, type TrackSource, type UpdateUserOptions, type UserListFilter, type UserListResponse, type VideoResolution, attachTrack, clearPlatformCache, detachTrack, getOrCreateClientId, getPlatform, renFetch, storageDelete, storageUpload };