@maravilla-labs/platform 0.1.35 → 0.1.38

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;
 }

package/tsup.config.ts

@@ -1,7 +1,7 @@
 import { defineConfig } from 'tsup';
 
 export default defineConfig({
-  entry: ['src/index.ts'],
+  entry: ['src/index.ts', 'src/config.ts'],
   format: ['esm'],
   dts: true,
   splitting: false,