@maravilla-labs/types 0.5.0 → 0.6.0

package/index.ts

@@ -176,12 +176,33 @@ export interface DbFindOptions {
   vector?: VectorQuery;
 }
 
+/**
+ * A document as it is returned by the runtime. Every row the platform
+ * stores carries a string `id` (mirrored as `_id`) injected at insert
+ * time, plus optional server-managed timestamps. `find`/`findOne` return
+ * this shape; the generic `T` is your own document fields.
+ *
+ * This is a **type-level** contract — the runtime already injects/returns
+ * `id`+`_id` on both the dev (SQLite) and production (Mongo) paths, so no
+ * normalization happens here.
+ */
+export type DbDocument<T = Record<string, unknown>> = T & {
+  /** Stable string row id, injected by the runtime on insert. */
+  id: string;
+  /** Mirror of `id` for MongoDB-style call sites. Always equals `id`. */
+  _id: string;
+  /** Server-managed creation timestamp, when present. */
+  _created_at?: string;
+  /** Server-managed update timestamp, when present. */
+  _updated_at?: string;
+};
+
 /**
  * Database collection interface
  */
 export interface DbCollection {
-  find(filter?: Record<string, any>, options?: DbFindOptions): Promise<any[]>;
-  findOne(filter?: Record<string, any>): Promise<any | null>;
+  find<T = Record<string, unknown>>(filter?: Record<string, any>, options?: DbFindOptions): Promise<DbDocument<T>[]>;
+  findOne<T = Record<string, unknown>>(filter?: Record<string, any>): Promise<DbDocument<T> | null>;
   insertOne(document: Record<string, any>): Promise<string>;
   updateOne(filter: Record<string, any>, update: Record<string, any>): Promise<void>;
   deleteOne(filter: Record<string, any>): Promise<void>;
@@ -317,7 +338,378 @@ export interface Storage {
   getMetadata(key: string): Promise<StorageMetadata>;
 }
 
-// Stewardship Types
+// ════════════════════════════════════════════════════════════════════
+// Auth, Stewardship, Resources, Circles, Groups, Relations
+// ════════════════════════════════════════════════════════════════════
+//
+// These are the CANONICAL definitions for the entire auth/policy/relations
+// surface. `@maravilla-labs/platform` re-exports every symbol below from
+// its own `types.ts`, and `RemoteAuthService implements AuthService`. Keep
+// this the single source of truth — do not fork divergent copies in the
+// platform package.
+
+/**
+ * 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", "managed", etc.) */
+  provider: string;
+  /** Group IDs the user belongs to */
+  groups: string[];
+  /**
+   * Caller-supplied external identifier used for idempotent
+   * managed-user creation (FR-3). `null`/absent for normal accounts.
+   */
+  external_id?: string | null;
+  /** 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.
+ * This is exactly what per-resource policies see as `auth.*`.
+ */
+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>;
+  /**
+   * Caller-supplied external id. When set, registration is idempotent on
+   * `(tenant, external_id)` — re-registering with the same key returns the
+   * existing user instead of erroring (FR-3).
+   */
+  external_id?: string;
+}
+
+/**
+ * Options for logging in.
+ */
+export interface LoginOptions {
+  /** User's email address */
+  email: string;
+  /** User's password */
+  password: string;
+}
+
+/**
+ * Options for creating a managed (no-login) user — e.g. an imported
+ * contact or service-owned record that authenticates out-of-band (FR-2).
+ * Created with no password; sessions are only minted when the account is
+ * later activated.
+ */
+export interface CreateManagedUserOptions {
+  /** Optional email. A synthetic no-login address is generated when omitted. */
+  email?: string;
+  /** Optional profile data. */
+  profile?: Record<string, any>;
+  /** Optional external id for idempotent create-by-key (FR-3). */
+  external_id?: string;
+  /** Optional group ids/slugs to add the user to on creation. */
+  groups?: 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 (RBAC) ──
+
+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;
+}
+
+/** Circle membership entry */
+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';
+
+/** A platform resource definition. */
+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;
+}
+
+// ── Relations (typed edges) ──
+
+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;
+}
+
+/** A single typed relation edge between two users (FR-1). */
+export interface Relation {
+  id: string;
+  from_user_id: string;
+  to_user_id: string;
+  /** The relation type's name (e.g. `STEWARDS`). */
+  relation_type: string;
+  /** The relation type's id (`rlt_…`). */
+  relation_type_id: string;
+  metadata?: Record<string, any> | null;
+  created_at: number;
+}
+
+/** Options for adding a relation edge. */
+export interface AddRelationOptions {
+  from_user_id: string;
+  to_user_id: string;
+  /** Either a relation-type id (`rlt_…`) or a relation name. */
+  relation_type: string;
+  metadata?: Record<string, any>;
+}
+
+/** Direction filter when listing a user's relations. */
+export type RelationListDirection = 'outgoing' | 'incoming' | 'both';
+
+/** Options for listing relation edges touching a user. */
+export interface ListRelationsOptions {
+  user_id: string;
+  direction?: RelationListDirection;
+}
+
+// ── 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 ──
 
 /** Delegation mode for stewardship overrides */
 export type DelegationMode = 'full' | 'scoped';
@@ -340,19 +732,19 @@ export interface StewardshipOverride {
   ward_id: string;
   delegation_mode: DelegationMode;
   scoped_permissions: ScopedPermission[];
-  valid_from?: number;
-  valid_until?: number;
+  valid_from: number | null;
+  valid_until: number | null;
   status: StewardshipStatus;
-  reason?: string;
+  reason: string | null;
   source: string;
-  source_circle_id?: string;
-  source_relation_type_id?: string;
+  source_circle_id: string | null;
+  source_relation_type_id: string | null;
   created_at: number;
   updated_at: number;
 }
 
 /** Options for creating a stewardship override */
-export interface CreateStewardshipOverrideRequest {
+export interface CreateStewardshipOverrideOptions {
   steward_id: string;
   ward_id: string;
   delegation_mode?: DelegationMode;
@@ -386,67 +778,261 @@ export interface StewardshipAuditEntry {
   performed_by: string;
   on_behalf_of: string;
   action: string;
-  resource?: string;
-  details?: Record<string, any>;
+  resource: string | null;
+  details: Record<string, any> | null;
   created_at: number;
 }
 
-/** Options for listing audit log entries */
-export interface AuditListOptions {
-  limit?: number;
-  offset?: number;
-}
-
-/** Stewardship service interface */
-export interface Stewardship {
+/**
+ * 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(options: CreateStewardshipOverrideRequest): Promise<StewardshipOverride>;
+  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?: AuditListOptions): Promise<StewardshipAuditEntry[]>;
+  listAudit(userId: string, options?: { limit?: number; offset?: number }): Promise<StewardshipAuditEntry[]>;
 }
 
-// Resource Types
+// ── Authorization explain / batch (FR-7) ──
 
-/** A platform resource definition */
-export interface Resource {
-  id: string;
-  resource_name: string;
-  title: string;
-  description?: string;
-  actions: string[];
-  created_at: number;
-  updated_at: number;
+/** Result of an `explain()` policy check. */
+export interface PolicyExplain {
+  allowed: boolean;
+  reason?: string;
+  /** The specific clause that caused a denial, when the engine can isolate it. */
+  failedClause?: string;
 }
 
-/** Options for creating a resource */
-export interface CreateResourceRequest {
-  resource_name: string;
-  title: string;
-  description?: string;
-  actions?: string[];
+/** A single authorization check for batched `canMany()`. */
+export interface CanCheck {
+  action: string;
+  resourceId: string;
+  node?: Record<string, unknown> | null;
 }
 
-// Circle Types
+/**
+ * Auth service for end-user authentication and user management.
+ * Implemented by the in-runtime native bridge and by the dev-server
+ * remote client (`RemoteAuthService`).
+ */
+export interface AuthService {
+  /**
+   * Register a new user with email and password.
+   * @returns The created user (not yet email-verified)
+   */
+  register(options: RegisterOptions): Promise<AuthUser>;
 
-/** Circle membership entry */
-export interface CircleMembership {
-  user_id: string;
-  email: string;
-  relationship: string;
-  is_primary_contact: boolean;
-  joined_at: number;
-}
+  /**
+   * Authenticate a user and create a session.
+   * @returns Session with access token, refresh token, and user info
+   */
+  login(options: LoginOptions): Promise<AuthSession>;
 
-/** A circle */
-export interface Circle {
-  id: string;
-  name: string;
-  metadata?: Record<string, any>;
-  member_count: number;
-  created_at: number;
-  updated_at: number;
+  /**
+   * Validate an access token and return the authenticated user.
+   * @throws If the token is invalid or expired
+   */
+  validate(accessToken: string): Promise<AuthUser>;
+
+  /**
+   * Refresh a session using a refresh token (single-use).
+   * @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 a managed (no-login) user (FR-2). Idempotent on `external_id`
+   * when supplied (FR-3).
+   */
+  createManagedUser(options: CreateManagedUserOptions): Promise<AuthUser>;
+
+  /**
+   * 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.
+   * @param provider - "google", "github", "okta", or "custom_oidc"
+   */
+  getOAuthUrl(provider: string, options?: { redirectUri?: string }): Promise<{ auth_url: string; state: string }>;
+
+  /** Complete an OAuth flow by exchanging the authorization code. */
+  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.
+   */
+  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[]>;
+  /** @param groupId - the group id **or slug** (resolved server-side). */
+  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.
+   */
+  getGroupByName(name: string): Promise<AuthGroup | null>;
+  /** @param groupId - the group id **or slug** (resolved server-side). */
+  updateGroup(groupId: string, options: UpdateGroupOptions): Promise<AuthGroup>;
+  /** @param groupId - the group id **or slug** (resolved server-side). */
+  deleteGroup(groupId: string): Promise<void>;
+  /** @param groupId - the group id **or slug** (resolved server-side). */
+  addUserToGroup(userId: string, groupId: string): Promise<void>;
+  /** @param groupId - the group id **or slug** (resolved server-side). */
+  removeUserFromGroup(userId: string, groupId: string): Promise<void>;
+  getUserGroups(userId: string): Promise<AuthGroup[]>;
+  /** @param groupId - the group id **or slug** (resolved server-side). */
+  getGroupMembers(groupId: string): Promise<AuthUser[]>;
+  /** @param groupId - the group id **or slug** (resolved server-side). */
+  getGroupPermissions(groupId: string): Promise<GroupPermission[]>;
+  /** @param groupId - the group id **or slug** (resolved server-side). */
+  setGroupPermissions(groupId: string, permissions: GroupPermission[]): Promise<void>;
+
+  // ── Circles ──
+
+  createCircle(options: CreateCircleOptions): Promise<AuthCircle>;
+  listCircles(): Promise<AuthCircle[]>;
+  /** @param circleId - the circle id **or slug** (resolved server-side). */
+  getCircle(circleId: string): Promise<AuthCircle | null>;
+  /** @param circleId - the circle id **or slug** (resolved server-side). */
+  updateCircle(circleId: string, options: UpdateCircleOptions): Promise<AuthCircle>;
+  /** @param circleId - the circle id **or slug** (resolved server-side). */
+  deleteCircle(circleId: string): Promise<void>;
+  /** @param circleId - the circle id **or slug** (resolved server-side). */
+  addCircleMember(circleId: string, options: AddCircleMemberOptions): Promise<void>;
+  /** @param circleId - the circle id **or slug** (resolved server-side). */
+  removeCircleMember(circleId: string, userId: string): Promise<void>;
+  /** @param circleId - the circle id **or slug** (resolved server-side). */
+  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[]>;
+  /** @param id - the relation-type id **or slug** (resolved server-side). */
+  updateRelationType(id: string, options: UpdateRelationTypeOptions): Promise<RelationType>;
+  /** @param id - the relation-type id **or slug** (resolved server-side). */
+  deleteRelationType(id: string): Promise<void>;
+
+  // ── Relations (typed edges, FR-1) ──
+
+  /** Add a directed relation edge between two users. */
+  addRelation(options: AddRelationOptions): Promise<Relation>;
+  /** Remove a relation edge by its endpoints and relation-type id. */
+  removeRelation(fromUserId: string, toUserId: string, relationTypeId: string): Promise<void>;
+  /** List relation edges touching a user, optionally filtered by direction. */
+  listRelations(options: ListRelationsOptions): Promise<Relation[]>;
+
+  // ── 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 operate on the current request's caller context. They're
+  // meaningful inside the runtime; on remote clients they throw (no
+  // per-request context) or fail closed.
+
+  /**
+   * Explicitly bind the caller for the remainder of this request.
+   * Pass a JWT to validate + bind, or `null` / `""` to clear.
+   */
+  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.
+   */
+  getCurrentUser(): AuthCaller;
+
+  /**
+   * Ask the policy engine whether the bound caller would be allowed to
+   * perform `action` on `resourceId`. Returns a boolean — never throws on
+   * denial. Fails closed when no caller is bound.
+   */
+  can(action: string, resourceId: string, node?: Record<string, unknown> | null): Promise<boolean>;
+
+  /**
+   * Like {@link can}, but returns *why* (FR-7). Fails closed with
+   * `{ allowed: false, reason: 'no bound user' }` when no caller is bound.
+   */
+  explain(action: string, resourceId: string, node?: Record<string, unknown> | null): Promise<PolicyExplain>;
+
+  /**
+   * Batch authorization check (FR-7). Results are returned in the same
+   * order as `checks`. Fails closed (all `{ allowed: false }`) when no
+   * caller is bound.
+   */
+  canMany(checks: CanCheck[]): Promise<{ allowed: boolean }[]>;
 }
 
 // Platform Types
@@ -538,39 +1124,13 @@ export interface Platform {
   storage: Storage;
   /** Durable multi-step workflows */
   workflows: Workflows;
-  /** Auth service with stewardship, resources, and circle helpers */
-  auth: {
-    register(options: { email: string; password: string; profile?: Record<string, any> }): Promise<any>;
-    login(options: { email: string; password: string }): Promise<any>;
-    validate(accessToken: string): Promise<any>;
-    refresh(refreshToken: string): Promise<any>;
-    logout(sessionId: string): Promise<void>;
-    getUser(userId: string): Promise<any>;
-    listUsers(filter?: Record<string, any>): Promise<any>;
-    updateUser(userId: string, update: Record<string, any>): Promise<any>;
-    deleteUser(userId: string): Promise<void>;
-    sendVerification(userId: string): Promise<any>;
-    verifyEmail(token: string): Promise<void>;
-    sendPasswordReset(email: string): Promise<any>;
-    resetPassword(token: string, newPassword: string): Promise<void>;
-    changePassword(userId: string, oldPassword: string, newPassword: string): Promise<void>;
-    getFieldConfig(): Promise<any>;
-    getOAuthUrl(provider: string, options?: { redirectUri?: string }): Promise<any>;
-    handleOAuthCallback(provider: string, params: { code: string; state: string }): Promise<any>;
-
-    /** Stewardship (guardian/ward delegation) */
-    stewardship: Stewardship;
-
-    /** List available resources */
-    listResources(): Promise<Resource[]>;
-    /** Create a resource definition */
-    createResource(options: CreateResourceRequest): Promise<Resource>;
-
-    /** Get circle members */
-    getCircleMembers(circleId: string): Promise<CircleMembership[]>;
-    /** Get circles a user belongs to */
-    getUserCircles(userId: string): Promise<Circle[]>;
-  };
+  /**
+   * Auth service — the full canonical {@link AuthService} surface:
+   * authentication, user management, groups, circles, resources, relation
+   * types, typed relation edges, stewardship, profile/config, and the
+   * request-scoped `can`/`explain`/`canMany` authorization checks.
+   */
+  auth: AuthService;
   /** Legacy aliases for compatibility */
   env: {
     KV: KvStore;
@@ -580,10 +1140,15 @@ export interface Platform {
 }
 
 /**
- * Global platform object available in runtime
+ * The ambient `platform` global is declared in `./global.d.ts` (kept
+ * separate so that *type-only* imports of these interfaces — e.g. from
+ * `@maravilla-labs/platform`, which has its own `getPlatform()` global —
+ * do not pull a conflicting ambient `const platform` into scope). Tooling
+ * and app code that want the global reference it explicitly:
+ *
+ * ```ts
+ * /// <reference types="@maravilla-labs/types/global" />
+ * ```
  */
-declare global {
-  const platform: Platform;
-}
 
 export { Platform as default };