@maravilla-labs/platform 0.1.35 → 0.1.36

package/src/remote-client.ts

@@ -1,4 +1,4 @@
-import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage, RealtimeService, PresenceService } from './types.js';
+import type { KvNamespace, KvListResult, Database, DbFindOptions, Storage, RealtimeService, PresenceService, AuthService, AuthCaller, AuthUser, AuthSession, AuthField, RegisterOptions, LoginOptions, UserListFilter, UserListResponse, UpdateUserOptions, PolicyService } from './types.js';
 import { RemoteMediaService } from './media.js';
 
 /**
@@ -405,6 +405,176 @@ class RemoteRealtimeService implements RealtimeService {
   }
 }
 
+/**
+ * Remote auth service for development environments.
+ * Calls the dev-server's platform auth ops via HTTP.
+ * @internal
+ */
+class RemoteAuthService implements AuthService {
+  constructor(
+    private baseUrl: string,
+    private headers: Record<string, string>
+  ) {}
+
+  private async post(path: string, body?: any): Promise<any> {
+    const res = await fetch(`${this.baseUrl}/api/platform/auth${path}`, {
+      method: 'POST',
+      headers: this.headers,
+      body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(`Auth error (${res.status}): ${text}`);
+    }
+    if (res.status === 204) return undefined;
+    return res.json();
+  }
+
+  async register(options: RegisterOptions): Promise<AuthUser> {
+    return this.post('/register', options);
+  }
+
+  async login(options: LoginOptions): Promise<AuthSession> {
+    return this.post('/login', options);
+  }
+
+  async validate(accessToken: string): Promise<AuthUser> {
+    return this.post('/validate', { token: accessToken });
+  }
+
+  async refresh(refreshToken: string): Promise<AuthSession> {
+    return this.post('/refresh', { token: refreshToken });
+  }
+
+  async logout(sessionId: string): Promise<void> {
+    await this.post('/logout', { session_id: sessionId });
+  }
+
+  async getUser(userId: string): Promise<AuthUser | null> {
+    return this.post('/get-user', { user_id: userId });
+  }
+
+  async listUsers(filter?: UserListFilter): Promise<UserListResponse> {
+    return this.post('/list-users', filter ?? {});
+  }
+
+  async updateUser(userId: string, update: UpdateUserOptions): Promise<AuthUser> {
+    return this.post('/update-user', { user_id: userId, ...update });
+  }
+
+  async deleteUser(userId: string): Promise<void> {
+    await this.post('/delete-user', { user_id: userId });
+  }
+
+  async sendVerification(userId: string): Promise<{ token: string }> {
+    return this.post('/send-verification', { user_id: userId });
+  }
+
+  async verifyEmail(token: string): Promise<void> {
+    await this.post('/verify-email', { token });
+  }
+
+  async sendPasswordReset(email: string): Promise<{ token: string }> {
+    return this.post('/send-password-reset', { email });
+  }
+
+  async resetPassword(token: string, newPassword: string): Promise<void> {
+    await this.post('/reset-password', { token, new_password: newPassword });
+  }
+
+  async changePassword(userId: string, oldPassword: string, newPassword: string): Promise<void> {
+    await this.post('/change-password', { user_id: userId, old_password: oldPassword, new_password: newPassword });
+  }
+
+  async getFieldConfig(): Promise<{ fields: AuthField[] }> {
+    return this.post('/field-config');
+  }
+
+  async getOAuthUrl(provider: string, options?: { redirectUri?: string }): Promise<{ auth_url: string; state: string }> {
+    return this.post('/oauth/start', { provider, redirect_uri: options?.redirectUri || `/_auth/callback/${provider}` });
+  }
+
+  async handleOAuthCallback(provider: string, params: { code: string; state: string }): Promise<any> {
+    return this.post('/oauth/callback', { provider, code: params.code, state: params.state });
+  }
+
+  withAuth<T extends (request: Request & { user: AuthUser }) => Promise<Response>>(
+    handler: T
+  ): (request: Request) => Promise<Response> {
+    const self = this;
+    return async function(request: Request): Promise<Response> {
+      let token: string | null = 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 as any).user = user;
+        return handler(request as Request & { user: AuthUser });
+      } 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: string | null): Promise<void> {
+    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(): AuthCaller {
+    throw new Error(
+      'platform.auth.getCurrentUser is only available inside the Maravilla runtime. ' +
+      'Remote clients have no per-request caller context.'
+    );
+  }
+
+  can(_action: string, _resourceId: string, _node?: Record<string, unknown> | null): Promise<boolean> {
+    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.'
+    ));
+  }
+}
+
+/**
+ * Remote stub for the per-request Layer 2 policy toggle. The toggle lives in
+ * per-request state inside the runtime and has no remote equivalent.
+ */
+class RemotePolicyService implements PolicyService {
+  setEnabled(_enabled: boolean): void {
+    throw new Error(
+      'platform.policy.setEnabled is only available inside the Maravilla runtime.'
+    );
+  }
+
+  isEnabled(): boolean {
+    throw new Error(
+      'platform.policy.isEnabled is only available inside the Maravilla runtime.'
+    );
+  }
+}
+
 /**
  * Create a remote platform client for development environments.
  * 
@@ -446,6 +616,8 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
   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: {
@@ -455,5 +627,7 @@ export function createRemoteClient(baseUrl: string, tenant: string) {
     },
     media,
     realtime,
+    auth,
+    policy,
   };
 }

package/src/types.ts

@@ -559,6 +559,378 @@ export interface PresenceService {
   members(channel: string): Promise<Array<{ userId: string; metadata?: any; lastSeen?: number }>>;
 }
 
+// ── Auth Types ──
+
+/**
+ * Authenticated user record from the platform auth service.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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.
+ */
+export interface LoginOptions {
+  /** User's email address */
+  email: string;
+  /** User's password */
+  password: string;
+}
+
+/**
+ * Filter options for listing users.
+ */
+export 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.
+ */
+export 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.
+ */
+export 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}`);
+ *   })
+ * };
+ * ```
+ */
+export 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>;
+
+  // ── Request-scoped identity + authorization ──
+  //
+  // These methods operate on the **current request's** caller context.
+  // They're meaningful inside the platform runtime (one isolate serving a
+  // Deno request). When called from a remote client — code running outside
+  // the runtime — they throw, because there is no per-request context to
+  // bind.
+
+  /**
+   * 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.
+ */
+export 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;
+}
+
 export interface Platform {
   /** Environment containing all available platform services */
   env: PlatformEnv;
@@ -566,4 +938,8 @@ export interface Platform {
   media?: import('./media.js').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;
 }