@maravilla-labs/types 0.5.0 → 0.6.0

package/index.d.ts

@@ -149,12 +149,32 @@ export interface DbFindOptions {
     /** Hybrid metadata + vector search clause. */
     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>;
@@ -274,6 +294,316 @@ export interface Storage {
      */
     getMetadata(key: string): Promise<StorageMetadata>;
 }
+/**
+ * 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>;
+}
+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[];
+}
+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;
+}
+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;
+}
+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;
+}
+export interface AuthConfig {
+    fields: AuthField[];
+    oauth_providers: any[];
+    branding: Record<string, any>;
+    password_policy: Record<string, any>;
+    session_config: Record<string, any>;
+}
 /** Delegation mode for stewardship overrides */
 export type DelegationMode = 'full' | 'scoped';
 /** Status of a stewardship override */
@@ -292,18 +622,18 @@ 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;
@@ -334,57 +664,224 @@ 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[]>;
-}
-/** A platform resource definition */
-export interface Resource {
-    id: string;
-    resource_name: string;
-    title: string;
-    description?: string;
-    actions: string[];
-    created_at: number;
-    updated_at: number;
-}
-/** Options for creating a resource */
-export interface CreateResourceRequest {
-    resource_name: string;
-    title: string;
-    description?: string;
-    actions?: string[];
+    listAudit(userId: string, options?: {
+        limit?: number;
+        offset?: number;
+    }): Promise<StewardshipAuditEntry[]>;
+}
+/** 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;
 }
-/** Circle membership entry */
-export interface CircleMembership {
-    user_id: string;
-    email: string;
-    relationship: string;
-    is_primary_contact: boolean;
-    joined_at: number;
+/** A single authorization check for batched `canMany()`. */
+export interface CanCheck {
+    action: string;
+    resourceId: string;
+    node?: Record<string, unknown> | null;
 }
-/** A circle */
-export interface Circle {
-    id: string;
-    name: string;
-    metadata?: Record<string, any>;
-    member_count: number;
-    created_at: number;
-    updated_at: number;
+/**
+ * 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>;
+    /**
+     * 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.
+     * @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>;
+    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>;
+    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[]>;
+    createResource(options: CreateResourceOptions): Promise<Resource>;
+    listResources(): Promise<Resource[]>;
+    updateResource(resourceId: string, options: UpdateResourceOptions): Promise<Resource>;
+    deleteResource(resourceId: string): Promise<void>;
+    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>;
+    /** 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[]>;
+    getProfile(userId: string): Promise<Record<string, any>>;
+    setProfile(userId: string, data: Record<string, any>): Promise<void>;
+    getAuthConfig(): Promise<AuthConfig>;
+    setAuthConfig(config: AuthConfig): Promise<void>;
+    readonly stewardship: AuthStewardshipApi;
+    /**
+     * 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;
+    }[]>;
 }
 /** State of a workflow run. */
 export type WorkflowRunStatus = 'queued' | 'running' | 'sleeping' | 'waiting_event' | 'completed' | 'failed' | 'cancelled';
@@ -460,48 +957,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;
@@ -510,9 +972,14 @@ 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 };