@maravilla-labs/platform 0.1.34 → 0.1.36

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 {
@@ -721,10 +1073,14 @@ declare class RealtimeClient {
     presence(channel: string): {
         /** Join the channel with presence (auto-rejoins on reconnect) */
         join: (userId: string, metadata?: any) => void;
+        /** Update metadata for the current presence (must have joined first) */
+        update: (metadata?: any) => void;
         /** Leave the channel */
         leave: () => void;
         /** Listen for users joining */
         onJoin: (callback: (member: PresenceMember) => void) => Unsubscribe;
+        /** Listen for metadata updates */
+        onUpdate: (callback: (member: PresenceMember) => void) => Unsubscribe;
         /** Listen for users leaving */
         onLeave: (callback: (member: PresenceMember) => void) => Unsubscribe;
     };
@@ -963,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 };

package/dist/index.js

@@ -380,6 +380,140 @@ var RemoteRealtimeService = class {
     return data.channels ?? [];
   }
 };
+var RemoteAuthService = class {
+  constructor(baseUrl, headers) {
+    this.baseUrl = baseUrl;
+    this.headers = headers;
+  }
+  baseUrl;
+  headers;
+  async post(path, body) {
+    const res = await fetch(`${this.baseUrl}/api/platform/auth${path}`, {
+      method: "POST",
+      headers: this.headers,
+      body: body !== void 0 ? JSON.stringify(body) : void 0
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Auth error (${res.status}): ${text}`);
+    }
+    if (res.status === 204) return void 0;
+    return res.json();
+  }
+  async register(options) {
+    return this.post("/register", options);
+  }
+  async login(options) {
+    return this.post("/login", options);
+  }
+  async validate(accessToken) {
+    return this.post("/validate", { token: accessToken });
+  }
+  async refresh(refreshToken) {
+    return this.post("/refresh", { token: refreshToken });
+  }
+  async logout(sessionId) {
+    await this.post("/logout", { session_id: sessionId });
+  }
+  async getUser(userId) {
+    return this.post("/get-user", { user_id: userId });
+  }
+  async listUsers(filter) {
+    return this.post("/list-users", filter ?? {});
+  }
+  async updateUser(userId, update) {
+    return this.post("/update-user", { user_id: userId, ...update });
+  }
+  async deleteUser(userId) {
+    await this.post("/delete-user", { user_id: userId });
+  }
+  async sendVerification(userId) {
+    return this.post("/send-verification", { user_id: userId });
+  }
+  async verifyEmail(token) {
+    await this.post("/verify-email", { token });
+  }
+  async sendPasswordReset(email) {
+    return this.post("/send-password-reset", { email });
+  }
+  async resetPassword(token, newPassword) {
+    await this.post("/reset-password", { token, new_password: newPassword });
+  }
+  async changePassword(userId, oldPassword, newPassword) {
+    await this.post("/change-password", { user_id: userId, old_password: oldPassword, new_password: newPassword });
+  }
+  async getFieldConfig() {
+    return this.post("/field-config");
+  }
+  async getOAuthUrl(provider, options) {
+    return this.post("/oauth/start", { provider, redirect_uri: options?.redirectUri || `/_auth/callback/${provider}` });
+  }
+  async handleOAuthCallback(provider, params) {
+    return this.post("/oauth/callback", { provider, code: params.code, state: params.state });
+  }
+  withAuth(handler) {
+    const self = this;
+    return async function(request) {
+      let token = null;
+      const authHeader = request.headers.get("Authorization");
+      if (authHeader?.startsWith("Bearer ")) {
+        token = authHeader.slice(7);
+      } else {
+        const cookies = request.headers.get("Cookie") ?? "";
+        const match = cookies.match(/__session=([^;]+)/);
+        if (match) token = match[1];
+      }
+      if (!token) {
+        return new Response(JSON.stringify({ error: "Authentication required" }), {
+          status: 401,
+          headers: { "Content-Type": "application/json" }
+        });
+      }
+      try {
+        const user = await self.validate(token);
+        request.user = user;
+        return handler(request);
+      } catch {
+        return new Response(JSON.stringify({ error: "Invalid or expired token" }), {
+          status: 401,
+          headers: { "Content-Type": "application/json" }
+        });
+      }
+    };
+  }
+  // ── Request-scoped identity + authorization ──
+  //
+  // These APIs operate on per-request state inside the platform runtime and
+  // don't have a remote equivalent. Throw so callers get a clear message
+  // instead of silently wrong behavior.
+  setCurrentUser(_token) {
+    return Promise.reject(new Error(
+      "platform.auth.setCurrentUser is only available inside the Maravilla runtime. Remote clients should pass the Authorization header with each request instead."
+    ));
+  }
+  getCurrentUser() {
+    throw new Error(
+      "platform.auth.getCurrentUser is only available inside the Maravilla runtime. Remote clients have no per-request caller context."
+    );
+  }
+  can(_action, _resourceId, _node) {
+    return Promise.reject(new Error(
+      "platform.auth.can is only available inside the Maravilla runtime. Remote clients cannot evaluate per-request policies because there is no bound caller."
+    ));
+  }
+};
+var RemotePolicyService = class {
+  setEnabled(_enabled) {
+    throw new Error(
+      "platform.policy.setEnabled is only available inside the Maravilla runtime."
+    );
+  }
+  isEnabled() {
+    throw new Error(
+      "platform.policy.isEnabled is only available inside the Maravilla runtime."
+    );
+  }
+};
 function createRemoteClient(baseUrl, tenant) {
   const headers = {
     "Content-Type": "application/json",
@@ -394,6 +528,8 @@ function createRemoteClient(baseUrl, tenant) {
   const storage = new RemoteStorage(baseUrl, headers);
   const media = new RemoteMediaService(baseUrl, headers);
   const realtime = new RemoteRealtimeService(baseUrl, headers);
+  const auth = new RemoteAuthService(baseUrl, headers);
+  const policy = new RemotePolicyService();
   return {
     env: {
       KV: kvProxy,
@@ -401,7 +537,9 @@ function createRemoteClient(baseUrl, tenant) {
       STORAGE: storage
     },
     media,
-    realtime
+    realtime,
+    auth,
+    policy
   };
 }
 
@@ -677,7 +815,7 @@ var RealtimeClient = class {
         listeners.forEach((cb) => cb(event));
       }
     }
-    if (event.event === "presence:join" || event.event === "presence:leave") {
+    if (event.event === "presence:join" || event.event === "presence:leave" || event.event === "presence:update") {
       const presenceSet = this.presenceListeners.get(event.channel);
       if (presenceSet) {
         const member = {
@@ -687,6 +825,8 @@ var RealtimeClient = class {
         };
         if (event.event === "presence:join") {
           presenceSet.onJoin.forEach((cb) => cb(member));
+        } else if (event.event === "presence:update") {
+          presenceSet.onUpdate.forEach((cb) => cb(member));
         } else {
           presenceSet.onLeave.forEach((cb) => cb(member));
         }
@@ -740,7 +880,8 @@ var RealtimeClient = class {
     if (!this.presenceListeners.has(channel)) {
       this.presenceListeners.set(channel, {
         onJoin: /* @__PURE__ */ new Set(),
-        onLeave: /* @__PURE__ */ new Set()
+        onLeave: /* @__PURE__ */ new Set(),
+        onUpdate: /* @__PURE__ */ new Set()
       });
     }
     const listeners = this.presenceListeners.get(channel);
@@ -755,6 +896,18 @@ var RealtimeClient = class {
           metadata
         });
       },
+      /** Update metadata for the current presence (must have joined first) */
+      update: (metadata) => {
+        const info = this.joinedPresence.get(channel);
+        if (!info) return;
+        info.metadata = metadata;
+        this.sendRaw({
+          action: "presence:update",
+          channel,
+          userId: info.userId,
+          metadata
+        });
+      },
       /** Leave the channel */
       leave: () => {
         this.joinedPresence.delete(channel);
@@ -767,6 +920,13 @@ var RealtimeClient = class {
           listeners.onJoin.delete(callback);
         };
       },
+      /** Listen for metadata updates */
+      onUpdate: (callback) => {
+        listeners.onUpdate.add(callback);
+        return () => {
+          listeners.onUpdate.delete(callback);
+        };
+      },
       /** Listen for users leaving */
       onLeave: (callback) => {
         listeners.onLeave.add(callback);
@@ -1048,7 +1208,7 @@ var MediaRoom = class _MediaRoom {
 };
 
 // src/index.ts
-var cachedPlatform = null;
+var cachedPlatform = void 0;
 function getPlatform(options) {
   if (cachedPlatform) {
     return cachedPlatform;
@@ -1075,7 +1235,7 @@ function getPlatform(options) {
   return cachedPlatform;
 }
 function clearPlatformCache() {
-  cachedPlatform = null;
+  cachedPlatform = void 0;
   if (typeof globalThis !== "undefined") {
     globalThis.__maravilla_platform = void 0;
   }