@maravilla-labs/platform 0.5.0 → 0.6.0

package/src/types.ts

@@ -1,7 +1,12 @@
+// The typed document shape (`id`/`_id` row identity) is canonical in
+// `@maravilla-labs/types`. Re-export so platform call sites can use it.
+import type { DbDocument } from '@maravilla-labs/types';
+export type { DbDocument } from '@maravilla-labs/types';
+
 /**
  * Key-Value namespace interface for storing and retrieving data.
  * Similar to Cloudflare Workers KV API for familiar developer experience.
- * 
+ *
  * @example
  * ```typescript
  * const platform = getPlatform();
@@ -161,7 +166,7 @@ export interface Database {
    * );
    * ```
    */
-  find(collection: string, filter?: any, options?: DbFindOptions): Promise<any[]>;
+  find<T = Record<string, unknown>>(collection: string, filter?: any, options?: DbFindOptions): Promise<DbDocument<T>[]>;
 
   /**
    * Find a single document in a collection.
@@ -178,7 +183,7 @@ export interface Database {
    * }
    * ```
    */
-  findOne(collection: string, filter: any): Promise<any | null>;
+  findOne<T = Record<string, unknown>>(collection: string, filter: any): Promise<DbDocument<T> | null>;
 
   /**
    * Insert a single document into a collection.
@@ -790,657 +795,62 @@ export interface PresenceService {
 }
 
 // ── 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>;
-}
-
-// ── Groups ──
-
-export interface AuthGroup {
-  id: string;
-  name: string;
-  description: string | null;
-  permissions: string[];
-  member_count: number;
-  created_at: number;
-  updated_at: number;
-}
-
-export interface CreateGroupOptions {
-  name: string;
-  description?: string;
-  permissions?: string[];
-}
-
-export interface UpdateGroupOptions {
-  name?: string;
-  description?: string;
-  permissions?: string[];
-}
-
-export interface GroupPermission {
-  resource_name: string;
-  actions: string[];
-}
-
-// ── Circles ──
-
-export interface AuthCircle {
-  id: string;
-  name: string;
-  metadata: Record<string, any> | null;
-  member_count: number;
-  created_at: number;
-  updated_at: number;
-}
-
-export interface CreateCircleOptions {
-  name: string;
-  metadata?: Record<string, any>;
-}
-
-export interface UpdateCircleOptions {
-  name?: string;
-  metadata?: Record<string, any>;
-}
-
-export interface AddCircleMemberOptions {
-  user_id: string;
-  relationship: string;
-  is_primary_contact?: boolean;
-}
-
-export interface CircleMembership {
-  user_id: string;
-  email: string;
-  relationship: string;
-  is_primary_contact: boolean;
-  joined_at: number;
-}
-
-// ── Resources ──
-
-export type ResourceServiceType =
-  | 'kv'
-  | 'database'
-  | 'realtime'
-  | 'media'
-  | 'vector'
-  | 'storage'
-  | 'queue'
-  | 'push'
-  | 'workflow'
-  | 'transforms';
-
-export 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;
-}
-
-export interface CreateResourceOptions {
-  resource_name: string;
-  title: string;
-  description?: string;
-  actions?: string[];
-  policy?: string;
-  service_type?: ResourceServiceType;
-  read_filter?: string;
-}
-
-export interface UpdateResourceOptions {
-  title?: string;
-  description?: string;
-  actions?: string[];
-  policy?: string;
-  service_type?: ResourceServiceType;
-  read_filter?: string;
-}
-
-// ── Relation types ──
-
-export 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;
-}
-
-export 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;
-}
-
-export interface UpdateRelationTypeOptions {
-  title?: string;
-  description?: string;
-  category?: string;
-  icon?: string;
-  color?: string;
-  inverse_relation_id?: string;
-  implies_stewardship?: boolean;
-  requires_minor?: boolean;
-  bidirectional?: boolean;
-}
-
-// ── Auth config (extended) ──
-
-export interface AuthConfig {
-  fields: AuthField[];
-  oauth_providers: any[];
-  branding: Record<string, any>;
-  password_policy: Record<string, any>;
-  session_config: Record<string, any>;
-}
-
-// ── Stewardship ──
-
-export type DelegationMode = 'full' | 'scoped';
-export type StewardshipStatus = 'active' | 'suspended' | 'revoked' | 'expired';
-
-export interface ScopedPermission {
-  resource: string;
-  actions: string[];
-}
-
-export 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;
-}
-
-export interface CreateStewardshipOverrideOptions {
-  steward_id: string;
-  ward_id: string;
-  delegation_mode?: DelegationMode;
-  scoped_permissions?: ScopedPermission[];
-  valid_from?: number;
-  valid_until?: number;
-  reason?: string;
-}
-
-export interface StewardshipResolution {
-  stewards: StewardshipOverride[];
-  wards: StewardshipOverride[];
-}
-
-export interface ActAsContext {
-  steward_id: string;
-  ward_id: string;
-  delegation_mode: DelegationMode;
-  scoped_permissions: ScopedPermission[];
-  session_token: string;
-  expires_at: number;
-}
-
-export 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.
- */
-export 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.
- *
- * @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>;
-
-  // ── Groups (RBAC) ──
-
-  createGroup(options: CreateGroupOptions): Promise<AuthGroup>;
-  listGroups(): Promise<AuthGroup[]>;
-  getGroup(groupId: string): Promise<AuthGroup | null>;
-  /**
-   * Look up a group by its declarative name (the same name used in
-   * `maravilla.config.ts`'s `groups: [...]` block). Returns null if the
-   * auth-settings reconciler hasn't created it yet. Apps that want to
-   * add a user to a group typically only know the name, so use this
-   * first to resolve the id, then call `addUserToGroup`.
-   */
-  getGroupByName(name: 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>;
-
-  // ── Circles ──
-
-  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[]>;
-
-  // ── Resources ──
-
-  createResource(options: CreateResourceOptions): Promise<Resource>;
-  listResources(): Promise<Resource[]>;
-  updateResource(resourceId: string, options: UpdateResourceOptions): Promise<Resource>;
-  deleteResource(resourceId: string): Promise<void>;
-
-  // ── Relation types ──
-
-  createRelationType(options: CreateRelationTypeOptions): Promise<RelationType>;
-  listRelationTypes(): Promise<RelationType[]>;
-  updateRelationType(id: string, options: UpdateRelationTypeOptions): Promise<RelationType>;
-  deleteRelationType(id: string): Promise<void>;
-
-  // ── Profile ──
-
-  getProfile(userId: string): Promise<Record<string, any>>;
-  setProfile(userId: string, data: Record<string, any>): Promise<void>;
-
-  // ── Auth config ──
-
-  getAuthConfig(): Promise<AuthConfig>;
-  setAuthConfig(config: AuthConfig): Promise<void>;
-
-  // ── Stewardship (sub-namespace mirroring the runtime bridge) ──
-
-  readonly stewardship: AuthStewardshipApi;
-
-  // ── 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>;
-}
+//
+// The auth/policy/relations type surface is canonical in
+// `@maravilla-labs/types` (the leaf package). We re-export every symbol
+// here so existing `import { ... } from './types.js'` / from
+// `@maravilla-labs/platform` call sites keep working unchanged, and so
+// `RemoteAuthService implements AuthService` references the single source
+// of truth. DRY: do not redeclare these locally.
+//
+// `AuthService` is also imported (not just re-exported) because the
+// `Platform` interface below references it within this module's scope.
+import type { AuthService } from '@maravilla-labs/types';
+export type {
+  AuthUser,
+  AuthCaller,
+  AuthSession,
+  AuthField,
+  RegisterOptions,
+  LoginOptions,
+  CreateManagedUserOptions,
+  UserListFilter,
+  UserListResponse,
+  UpdateUserOptions,
+  AuthGroup,
+  CreateGroupOptions,
+  UpdateGroupOptions,
+  GroupPermission,
+  AuthCircle,
+  CreateCircleOptions,
+  UpdateCircleOptions,
+  AddCircleMemberOptions,
+  CircleMembership,
+  ResourceServiceType,
+  Resource,
+  CreateResourceOptions,
+  UpdateResourceOptions,
+  RelationType,
+  CreateRelationTypeOptions,
+  UpdateRelationTypeOptions,
+  Relation,
+  AddRelationOptions,
+  RelationListDirection,
+  ListRelationsOptions,
+  AuthConfig,
+  DelegationMode,
+  StewardshipStatus,
+  ScopedPermission,
+  StewardshipOverride,
+  CreateStewardshipOverrideOptions,
+  StewardshipResolution,
+  ActAsContext,
+  StewardshipAuditEntry,
+  AuthStewardshipApi,
+  PolicyExplain,
+  CanCheck,
+  AuthService,
+} from '@maravilla-labs/types';
 
 /**
  * Per-request opt-out toggle for the Layer 2 policy evaluator.