@lastshotlabs/bunshot 0.0.21 → 0.0.27

package/dist/lib/appConfig.d.ts

@@ -84,6 +84,10 @@ export interface MfaWebAuthnConfig {
     timeout?: number;
     /** Reject authentication when sign count goes backward (cloned key detection). Default: false (accept + warn). */
     strictSignCount?: boolean;
+    /** Allow passwordless (first-factor) passkey login. When true, mounts POST /auth/passkey/login-options and POST /auth/passkey/login. Default: false. */
+    allowPasswordlessLogin?: boolean;
+    /** When true (default), a verified passkey login satisfies MFA — no subsequent TOTP/OTP prompt even if the user has MFA enabled. Set false to require MFA after passkey login. */
+    passkeyMfaBypass?: boolean;
 }
 export interface MfaConfig {
     /** Issuer name shown in authenticator apps. Defaults to app name. */
@@ -102,6 +106,8 @@ export interface MfaConfig {
     emailOtp?: MfaEmailOtpConfig;
     /** WebAuthn/FIDO2 configuration. When set, enables security key MFA routes. */
     webauthn?: MfaWebAuthnConfig;
+    /** When true, authenticated users must complete MFA setup before accessing non-auth endpoints. Default: false. */
+    required?: boolean;
 }
 export declare const setMfaConfig: (config: MfaConfig | null) => void;
 export declare const getMfaConfig: () => MfaConfig | null;
@@ -114,5 +120,156 @@ export declare const getMfaChallengeTtl: () => number;
 export declare const getMfaEmailOtpConfig: () => MfaEmailOtpConfig | null;
 export declare const getMfaEmailOtpCodeLength: () => number;
 export declare const getMfaWebAuthnConfig: () => MfaWebAuthnConfig | null;
+export declare const getMfaRequired: () => boolean;
+export declare const getMfaWebAuthnAllowPasswordlessLogin: () => boolean;
+export declare const getMfaWebAuthnPasskeyMfaBypass: () => boolean;
 export declare const setCsrfEnabled: (v: boolean) => void;
 export declare const getCsrfEnabled: () => boolean;
+export interface SigningConfig {
+    /**
+     * HMAC secret. Defaults to JWT_SECRET_DEV/JWT_SECRET_PROD env var if omitted.
+     * Pass string[] to support key rotation — first element signs, all elements verify.
+     */
+    secret?: string | string[];
+    /** Sign/verify cookie values set via exported helpers. Default: false. */
+    cookies?: boolean;
+    /** Sign pagination cursor tokens to prevent client tampering. Default: false. */
+    cursors?: boolean;
+    /** HMAC-based stateless presigned URLs (no DB lookup). Default: false. */
+    presignedUrls?: boolean | {
+        defaultExpiry?: number;
+    };
+    /** Require clients to HMAC-sign requests (method+path+timestamp+body). Default: false. */
+    requestSigning?: boolean | {
+        tolerance?: number;
+        header?: string;
+        timestampHeader?: string;
+    };
+    /** Hash idempotency keys before storage. Default: false. */
+    idempotencyKeys?: boolean;
+    /** Bind sessions to client IP+UA fingerprint. Default: false. */
+    sessionBinding?: boolean | {
+        fields?: Array<"ip" | "ua" | "accept-language">;
+        /**
+         * What to do when fingerprint doesn't match.
+         * - "unauthenticate": treat as logged-out (default — graceful but masks attacks)
+         * - "reject": return 401 (strict — recommended for security-conscious apps)
+         * - "log-only": allow through but log the mismatch (useful during rollout)
+         */
+        onMismatch?: "unauthenticate" | "reject" | "log-only";
+    };
+}
+export declare const setSigningConfig: (config: SigningConfig | null) => void;
+export declare const getSigningConfig: () => SigningConfig | null;
+/**
+ * Returns the active signing secret: signing.secret → JWT_SECRET_PROD/DEV env var.
+ * Returns null when neither is configured — callers must handle this gracefully.
+ */
+export declare const getSigningSecret: () => string | string[] | null;
+export interface JwtConfig {
+    /** JWT issuer claim (`iss`). When set, added to all tokens and validated on verify. */
+    issuer?: string;
+    /** JWT audience claim (`aud`). When set, added to all tokens and validated on verify. */
+    audience?: string | string[];
+    /** JWT signing algorithm. Default: "HS256". Use "RS256" for OIDC. Requires OidcConfig when set to "RS256". */
+    algorithm?: "HS256" | "RS256";
+}
+export declare const setJwtConfig: (config: JwtConfig | null) => void;
+export declare const getJwtConfig: () => JwtConfig | null;
+export declare const getJwtIssuer: () => string | undefined;
+export declare const getJwtAudience: () => string | string[] | undefined;
+export interface BreachedPasswordConfig {
+    /** Block registration/reset when password is breached. Default: true. */
+    block?: boolean;
+    /** Minimum breach count to consider breached. Default: 1. */
+    minBreachCount?: number;
+    /** Request timeout in ms. Default: 3000. */
+    timeout?: number;
+    /** What to do when the HIBP API is unavailable. Default: "allow". */
+    onApiFailure?: "allow" | "block";
+}
+export declare const setBreachedPasswordConfig: (config: BreachedPasswordConfig | null) => void;
+export declare const getBreachedPasswordConfig: () => BreachedPasswordConfig | null;
+export interface StepUpConfig {
+    /** Max age in seconds since last MFA verification. Default: 300 (5 min). */
+    maxAge?: number;
+}
+export declare const setStepUpConfig: (config: StepUpConfig | null) => void;
+export declare const getStepUpConfig: () => StepUpConfig | null;
+export declare const setCheckSuspensionOnIdentify: (v: boolean) => void;
+export declare const getCheckSuspensionOnIdentify: () => boolean;
+export declare const setCaptchaConfig: (config: import("./captcha").CaptchaConfig | null) => void;
+export declare const getCaptchaConfig: () => import("./captcha").CaptchaConfig | null;
+export interface M2MConfig {
+    enabled?: boolean;
+    /** Access token expiry in seconds. Default: 3600 (1 hour). */
+    tokenExpiry?: number;
+    /** Allowed scopes for M2M clients. */
+    scopes?: string[];
+}
+export declare const setM2MConfig: (config: M2MConfig | null) => void;
+export declare const getM2MConfig: () => M2MConfig | null;
+export declare const getM2MTokenExpiry: () => number;
+export interface SamlConfig {
+    /** Service Provider entity ID (e.g. "https://yourapp.com/auth/saml"). */
+    entityId: string;
+    /** Assertion Consumer Service URL. */
+    acsUrl: string;
+    /** IdP metadata — XML string or URL. */
+    idpMetadata: string;
+    /** SP signing private key PEM. Optional. */
+    signingKey?: string;
+    /** SP signing certificate PEM. Optional. */
+    signingCert?: string;
+    /** Map IdP attribute names to profile fields. */
+    attributeMapping?: {
+        email?: string;
+        firstName?: string;
+        lastName?: string;
+        groups?: string;
+    };
+    /** Custom user lookup/creation. When provided, takes precedence over findOrCreateByProvider. */
+    onLogin?: (profile: SamlProfile) => Promise<{
+        userId: string;
+    }>;
+    /** Where to redirect after successful SAML login. Default: "/". */
+    postLoginRedirect?: string;
+}
+import type { SamlProfile } from "./saml";
+export declare const setSamlConfig: (config: SamlConfig | null) => void;
+export declare const getSamlConfig: () => SamlConfig | null;
+export interface OidcConfig {
+    enabled?: boolean;
+    /** JWT issuer — included in all tokens and OIDC discovery doc. Required. */
+    issuer: string;
+    /** RSA signing key. If not provided, a key pair is auto-generated on startup. */
+    signingKey?: {
+        privateKey: string;
+        publicKey: string;
+        kid?: string;
+    };
+    /** Previous signing keys for rotation (verification only). */
+    previousKeys?: Array<{
+        publicKey: string;
+        kid?: string;
+    }>;
+    /** Scopes advertised in the discovery document. Default: ["openid"]. */
+    scopes?: string[];
+    /** Token endpoint URL. Defaults to `${issuer}/oauth/token`. */
+    tokenEndpoint?: string;
+}
+export declare const setOidcConfig: (config: OidcConfig | null) => void;
+export declare const getOidcConfig: () => OidcConfig | null;
+export interface ScimConfig {
+    enabled?: boolean;
+    /** Bearer token(s) for SCIM endpoint authentication. Required. */
+    bearerTokens: string | string[];
+    /** Username mapping strategy. Default: "email". */
+    userMapping?: {
+        userName?: "email" | "username";
+    };
+    /** What to do when a user is deleted via SCIM. Default: "suspend". */
+    onDeprovision?: "suspend" | "delete" | ((userId: string) => Promise<void>);
+}
+export declare const setScimConfig: (config: ScimConfig | null) => void;
+export declare const getScimConfig: () => ScimConfig | null;

package/dist/lib/appConfig.js

@@ -59,9 +59,63 @@ export const getMfaChallengeTtl = () => _mfaConfig?.challengeTtlSeconds ?? 300;
 export const getMfaEmailOtpConfig = () => _mfaConfig?.emailOtp ?? null;
 export const getMfaEmailOtpCodeLength = () => _mfaConfig?.emailOtp?.codeLength ?? 6;
 export const getMfaWebAuthnConfig = () => _mfaConfig?.webauthn ?? null;
+export const getMfaRequired = () => _mfaConfig?.required ?? false;
+export const getMfaWebAuthnAllowPasswordlessLogin = () => _mfaConfig?.webauthn?.allowPasswordlessLogin ?? false;
+export const getMfaWebAuthnPasskeyMfaBypass = () => _mfaConfig?.webauthn?.passkeyMfaBypass ?? true;
 // ---------------------------------------------------------------------------
 // CSRF config
 // ---------------------------------------------------------------------------
 let _csrfEnabled = false;
 export const setCsrfEnabled = (v) => { _csrfEnabled = v; };
 export const getCsrfEnabled = () => _csrfEnabled;
+let _signingConfig = null;
+export const setSigningConfig = (config) => { _signingConfig = config; };
+export const getSigningConfig = () => _signingConfig;
+/**
+ * Returns the active signing secret: signing.secret → JWT_SECRET_PROD/DEV env var.
+ * Returns null when neither is configured — callers must handle this gracefully.
+ */
+export const getSigningSecret = () => {
+    if (_signingConfig?.secret)
+        return _signingConfig.secret;
+    const isProd = process.env.NODE_ENV === "production";
+    const envKey = isProd ? "JWT_SECRET_PROD" : "JWT_SECRET_DEV";
+    const rawSecret = process.env[envKey];
+    return rawSecret ?? null;
+};
+let _jwtConfig = null;
+export const setJwtConfig = (config) => { _jwtConfig = config; };
+export const getJwtConfig = () => _jwtConfig;
+export const getJwtIssuer = () => _jwtConfig?.issuer;
+export const getJwtAudience = () => _jwtConfig?.audience;
+let _breachedPasswordConfig = null;
+export const setBreachedPasswordConfig = (config) => { _breachedPasswordConfig = config; };
+export const getBreachedPasswordConfig = () => _breachedPasswordConfig;
+let _stepUpConfig = null;
+export const setStepUpConfig = (config) => { _stepUpConfig = config; };
+export const getStepUpConfig = () => _stepUpConfig;
+// ---------------------------------------------------------------------------
+// Suspension config
+// ---------------------------------------------------------------------------
+let _checkSuspensionOnIdentify = false;
+export const setCheckSuspensionOnIdentify = (v) => { _checkSuspensionOnIdentify = v; };
+export const getCheckSuspensionOnIdentify = () => _checkSuspensionOnIdentify;
+// ---------------------------------------------------------------------------
+// CAPTCHA config
+// ---------------------------------------------------------------------------
+let _captchaConfig = null;
+export const setCaptchaConfig = (config) => { _captchaConfig = config; };
+export const getCaptchaConfig = () => _captchaConfig;
+let _m2mConfig = null;
+export const setM2MConfig = (config) => { _m2mConfig = config; };
+export const getM2MConfig = () => _m2mConfig;
+export const getM2MTokenExpiry = () => _m2mConfig?.tokenExpiry ?? 3600;
+let _samlConfig = null;
+export const setSamlConfig = (config) => { _samlConfig = config; };
+export const getSamlConfig = () => _samlConfig;
+let _oidcConfig = null;
+export const setOidcConfig = (config) => { _oidcConfig = config; };
+export const getOidcConfig = () => _oidcConfig;
+let _scimConfig = null;
+export const setScimConfig = (config) => { _scimConfig = config; };
+export const getScimConfig = () => _scimConfig;

package/dist/lib/auditLog.d.ts

@@ -0,0 +1,58 @@
+import type { Database } from "bun:sqlite";
+export interface AuditLogEntry {
+    id: string;
+    userId: string | null;
+    sessionId: string | null;
+    tenantId: string | null;
+    method: string;
+    path: string;
+    status: number;
+    ip: string | null;
+    userAgent: string | null;
+    action?: string;
+    resource?: string;
+    resourceId?: string;
+    meta?: Record<string, unknown>;
+    requestId?: string;
+    /** ISO 8601 string across all backends. */
+    createdAt: string;
+    /** MongoDB TTL only — silently ignored by SQLite and memory stores. */
+    expiresAt?: Date;
+}
+export type AuditLogStore = "mongo" | "sqlite" | "memory";
+export interface AuditLogOptions {
+    store: AuditLogStore;
+    /** Required when `store === "sqlite"`. */
+    db?: Database;
+}
+export interface AuditLogQuery {
+    userId?: string;
+    tenantId?: string;
+    after?: Date | string;
+    before?: Date | string;
+    /** Default 50, max 200. */
+    limit?: number;
+    /** Default 0. */
+    offset?: number;
+}
+export declare function clearAuditLogMemoryStore(): void;
+/**
+ * Persist an audit log entry to the configured store.
+ * Errors are caught internally — this function never throws, to ensure
+ * storage failures never fail the HTTP request.
+ */
+export declare function logAuditEntry(entry: AuditLogEntry, options: AuditLogOptions): Promise<void>;
+/**
+ * Blocking variant of logAuditEntry for critical events (e.g. account deletion,
+ * password changes). Awaits the write and logs errors, but never rethrows —
+ * a logging failure must not break the HTTP response.
+ */
+export declare function logAuditEntryBlocking(entry: AuditLogEntry, options: AuditLogOptions): Promise<void>;
+/**
+ * Query audit log entries from the configured store.
+ * Returns `{ items, total }` where `total` is the filtered count before pagination.
+ */
+export declare function getAuditLogs(query: AuditLogQuery, options: AuditLogOptions): Promise<{
+    items: AuditLogEntry[];
+    total: number;
+}>;

package/dist/lib/auditLog.js

@@ -0,0 +1,218 @@
+// ---------------------------------------------------------------------------
+// Memory store
+// ---------------------------------------------------------------------------
+let _auditLogs = [];
+export function clearAuditLogMemoryStore() {
+    _auditLogs = [];
+}
+// ---------------------------------------------------------------------------
+// SQLite helpers
+// ---------------------------------------------------------------------------
+function ensureSqliteTable(db) {
+    // No module-level flag — CREATE IF NOT EXISTS is idempotent and cheap.
+    // A flag would break when multiple Database instances are used (e.g. in tests).
+    db.run(`
+    CREATE TABLE IF NOT EXISTS audit_logs (
+      id         TEXT PRIMARY KEY,
+      userId     TEXT,
+      sessionId  TEXT,
+      tenantId   TEXT,
+      method     TEXT NOT NULL,
+      path       TEXT NOT NULL,
+      status     INTEGER NOT NULL,
+      ip         TEXT,
+      userAgent  TEXT,
+      action     TEXT,
+      resource   TEXT,
+      resourceId TEXT,
+      meta       TEXT,
+      createdAt  TEXT NOT NULL
+    )
+  `);
+    db.run("CREATE INDEX IF NOT EXISTS idx_al_user   ON audit_logs(userId,   createdAt)");
+    db.run("CREATE INDEX IF NOT EXISTS idx_al_tenant ON audit_logs(tenantId, createdAt)");
+    db.run("CREATE INDEX IF NOT EXISTS idx_al_path   ON audit_logs(path)");
+}
+// ---------------------------------------------------------------------------
+// logAuditEntry
+// ---------------------------------------------------------------------------
+/**
+ * Persist an audit log entry to the configured store.
+ * Errors are caught internally — this function never throws, to ensure
+ * storage failures never fail the HTTP request.
+ */
+export async function logAuditEntry(entry, options) {
+    try {
+        if (options.store === "memory") {
+            _auditLogs.push(entry);
+            return;
+        }
+        if (options.store === "sqlite") {
+            const db = options.db;
+            if (!db)
+                throw new Error("AuditLog: store is 'sqlite' but no db instance was provided");
+            ensureSqliteTable(db);
+            db.run(`INSERT INTO audit_logs
+           (id, userId, sessionId, tenantId, method, path, status,
+            ip, userAgent, action, resource, resourceId, meta, createdAt)
+         VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`, [
+                entry.id,
+                entry.userId ?? null,
+                entry.sessionId ?? null,
+                entry.tenantId ?? null,
+                entry.method,
+                entry.path,
+                entry.status,
+                entry.ip ?? null,
+                entry.userAgent ?? null,
+                entry.action ?? null,
+                entry.resource ?? null,
+                entry.resourceId ?? null,
+                entry.meta !== undefined ? JSON.stringify(entry.meta) : null,
+                entry.createdAt,
+            ]);
+            return;
+        }
+        if (options.store === "mongo") {
+            // Lazy import to avoid bundling mongoose when not used
+            const { AuditLog } = await import("../models/AuditLog");
+            await AuditLog.create({
+                ...entry,
+                createdAt: new Date(entry.createdAt),
+            });
+            return;
+        }
+    }
+    catch (err) {
+        console.error("[auditLog] failed to write entry:", err);
+    }
+}
+// ---------------------------------------------------------------------------
+// logAuditEntryBlocking
+// ---------------------------------------------------------------------------
+/**
+ * Blocking variant of logAuditEntry for critical events (e.g. account deletion,
+ * password changes). Awaits the write and logs errors, but never rethrows —
+ * a logging failure must not break the HTTP response.
+ */
+export async function logAuditEntryBlocking(entry, options) {
+    try {
+        await logAuditEntry(entry, options);
+    }
+    catch (err) {
+        console.error("[auditLog] CRITICAL: blocking audit write failed:", err);
+        // Don't rethrow — we never want a logging failure to break the response
+    }
+}
+// ---------------------------------------------------------------------------
+// getAuditLogs
+// ---------------------------------------------------------------------------
+/**
+ * Query audit log entries from the configured store.
+ * Returns `{ items, total }` where `total` is the filtered count before pagination.
+ */
+export async function getAuditLogs(query, options) {
+    const limit = Math.min(query.limit ?? 50, 200);
+    const offset = query.offset ?? 0;
+    const after = query.after ? new Date(query.after).toISOString() : undefined;
+    const before = query.before ? new Date(query.before).toISOString() : undefined;
+    // --- Memory ---
+    if (options.store === "memory") {
+        let filtered = _auditLogs.slice();
+        if (query.userId !== undefined)
+            filtered = filtered.filter(e => e.userId === query.userId);
+        if (query.tenantId !== undefined)
+            filtered = filtered.filter(e => e.tenantId === query.tenantId);
+        if (after)
+            filtered = filtered.filter(e => e.createdAt >= after);
+        if (before)
+            filtered = filtered.filter(e => e.createdAt < before);
+        return { items: filtered.slice(offset, offset + limit), total: filtered.length };
+    }
+    // --- SQLite ---
+    if (options.store === "sqlite") {
+        const db = options.db;
+        if (!db)
+            throw new Error("AuditLog: store is 'sqlite' but no db instance was provided");
+        ensureSqliteTable(db);
+        const conditions = [];
+        const params = [];
+        if (query.userId !== undefined) {
+            conditions.push("userId = ?");
+            params.push(query.userId);
+        }
+        if (query.tenantId !== undefined) {
+            conditions.push("tenantId = ?");
+            params.push(query.tenantId);
+        }
+        if (after) {
+            conditions.push("createdAt >= ?");
+            params.push(after);
+        }
+        if (before) {
+            conditions.push("createdAt < ?");
+            params.push(before);
+        }
+        const where = conditions.length > 0 ? `WHERE ${conditions.join(" AND ")}` : "";
+        const { count } = db.query(`SELECT COUNT(*) as count FROM audit_logs ${where}`).get(...params) ?? { count: 0 };
+        const rows = db.query(`SELECT * FROM audit_logs ${where} ORDER BY createdAt DESC LIMIT ? OFFSET ?`).all(...params, limit, offset);
+        const items = rows.map(row => ({
+            id: row.id,
+            userId: row.userId ?? null,
+            sessionId: row.sessionId ?? null,
+            tenantId: row.tenantId ?? null,
+            method: row.method,
+            path: row.path,
+            status: row.status,
+            ip: row.ip ?? null,
+            userAgent: row.userAgent ?? null,
+            action: row.action ?? undefined,
+            resource: row.resource ?? undefined,
+            resourceId: row.resourceId ?? undefined,
+            meta: row.meta ? JSON.parse(row.meta) : undefined,
+            createdAt: row.createdAt,
+        }));
+        return { items, total: count };
+    }
+    // --- MongoDB ---
+    if (options.store === "mongo") {
+        const { AuditLog } = await import("../models/AuditLog");
+        const filter = {};
+        if (query.userId !== undefined)
+            filter.userId = query.userId;
+        if (query.tenantId !== undefined)
+            filter.tenantId = query.tenantId;
+        if (after || before) {
+            filter.createdAt = {
+                ...(after ? { $gte: new Date(after) } : {}),
+                ...(before ? { $lt: new Date(before) } : {}),
+            };
+        }
+        const [total, docs] = await Promise.all([
+            AuditLog.countDocuments(filter),
+            AuditLog.find(filter)
+                .sort({ createdAt: -1 })
+                .skip(offset)
+                .limit(limit)
+                .lean(),
+        ]);
+        const items = docs.map(doc => ({
+            id: doc.id,
+            userId: doc.userId ?? null,
+            sessionId: doc.sessionId ?? null,
+            tenantId: doc.tenantId ?? null,
+            method: doc.method,
+            path: doc.path,
+            status: doc.status,
+            ip: doc.ip ?? null,
+            userAgent: doc.userAgent ?? null,
+            action: doc.action,
+            resource: doc.resource,
+            resourceId: doc.resourceId,
+            meta: doc.meta,
+            createdAt: doc.createdAt.toISOString(),
+        }));
+        return { items, total };
+    }
+    return { items: [], total: 0 };
+}

package/dist/lib/authAdapter.d.ts

@@ -1,8 +1,23 @@
-export interface OAuthProfile {
+import type { GroupRecord, GroupMembershipRecord, PaginationOpts, PaginatedResult } from "./groups";
+export type { GroupRecord, GroupMembershipRecord, PaginationOpts, PaginatedResult };
+export interface M2MClientRecord {
+    id: string;
+    clientId: string;
+    name: string;
+    scopes: string[];
+    active: boolean;
+}
+export interface IdentityProfile {
     email?: string;
     name?: string;
+    firstName?: string;
+    lastName?: string;
+    displayName?: string;
     avatarUrl?: string;
+    externalId?: string;
 }
+/** @deprecated Use IdentityProfile */
+export type OAuthProfile = IdentityProfile;
 export interface WebAuthnCredential {
     /** Base64url-encoded credential ID. */
     credentialId: string;
@@ -47,6 +62,12 @@ export interface AuthAdapter {
         email?: string;
         providerIds?: string[];
         emailVerified?: boolean;
+        displayName?: string;
+        firstName?: string;
+        lastName?: string;
+        externalId?: string;
+        suspended?: boolean;
+        suspendedReason?: string;
     } | null>;
     /** Optional. Unlink a provider identity from a user (used by DELETE /auth/:provider/link). */
     unlinkProvider?(userId: string, provider: string): Promise<void>;
@@ -102,6 +123,124 @@ export interface AuthAdapter {
     updateWebAuthnCredentialSignCount?(userId: string, credentialId: string, signCount: number): Promise<void>;
     /** Optional. Find the user who owns a WebAuthn credential. Returns userId or null. Used for cross-user uniqueness checks. */
     findUserByWebAuthnCredentialId?(credentialId: string): Promise<string | null>;
+    /** Suspend or unsuspend a user. */
+    setSuspended?(userId: string, suspended: boolean, reason?: string): Promise<void>;
+    /** Get suspension status. Returns false if adapter doesn't track it. */
+    getSuspended?(userId: string): Promise<{
+        suspended: boolean;
+        suspendedReason?: string;
+    } | null>;
+    /** Update profile fields. */
+    updateProfile?(userId: string, fields: Partial<Pick<IdentityProfile, "displayName" | "firstName" | "lastName" | "externalId">>): Promise<void>;
+    /** List users matching a normalized query. */
+    listUsers?(query: UserQuery): Promise<{
+        users: UserRecord[];
+        totalResults: number;
+    }>;
+    /**
+     * Create a new group. Returns the new group's id.
+     * The name must be a slug (/^[a-z0-9_-]+$/) and unique within its scope.
+     * tenantId: null = app-wide group, string = tenant-scoped group.
+     */
+    createGroup?(group: Omit<GroupRecord, "id" | "createdAt" | "updatedAt">): Promise<{
+        id: string;
+    }>;
+    /**
+     * Delete a group and cascade-delete all its memberships.
+     * Cascade behavior is adapter-specific (MongoDB: manual deleteMany, SQLite: ON DELETE CASCADE).
+     */
+    deleteGroup?(groupId: string): Promise<void>;
+    /** Get a group by ID. Returns null if not found. */
+    getGroup?(groupId: string): Promise<GroupRecord | null>;
+    /**
+     * List groups scoped to a tenant (tenantId string) or app-wide (tenantId null).
+     * Results are paginated (default limit 50, max 200).
+     */
+    listGroups?(tenantId: string | null, opts?: PaginationOpts): Promise<PaginatedResult<GroupRecord>>;
+    /**
+     * Update mutable group fields: name, displayName, description, roles.
+     * tenantId is intentionally excluded — it is immutable after creation.
+     */
+    updateGroup?(groupId: string, updates: Partial<Pick<GroupRecord, "roles" | "name" | "displayName" | "description">>): Promise<void>;
+    /**
+     * Add a user to a group with optional per-membership roles.
+     *
+     * CONTRACT: throws if the user is already a member (unique constraint violation).
+     * All adapters must surface this as a thrown error, not a silent no-op.
+     * Use updateGroupMembership to change roles on an existing membership.
+     */
+    addGroupMember?(groupId: string, userId: string, roles?: string[]): Promise<void>;
+    /**
+     * Update the per-membership roles for an existing group member.
+     * Replaces the member's roles[] in place (not additive).
+     * No updatedAt is tracked — intentional, see GroupMembershipRecord.
+     */
+    updateGroupMembership?(groupId: string, userId: string, roles: string[]): Promise<void>;
+    /** Remove a user from a group. No-op if the user is not a member. */
+    removeGroupMember?(groupId: string, userId: string): Promise<void>;
+    /** List members of a group with their per-membership roles. Paginated. */
+    getGroupMembers?(groupId: string, opts?: PaginationOpts): Promise<PaginatedResult<{
+        userId: string;
+        roles: string[];
+    }>>;
+    /**
+     * List all groups a user belongs to in the given scope, with their per-membership roles.
+     * tenantId = null → app-wide groups; tenantId = string → tenant-scoped groups.
+     */
+    getUserGroups?(userId: string, tenantId: string | null): Promise<Array<{
+        group: GroupRecord;
+        membershipRoles: string[];
+    }>>;
+    /**
+     * Return all roles a user effectively has in the given scope, combining:
+     *   1. Direct roles (app-wide or tenant-scoped)
+     *   2. Group baseline roles (from all groups the user belongs to in that scope)
+     *   3. Per-membership roles (user-specific extras within each group)
+     *
+     * SCOPE CONTRACT (matches requireRole behavior):
+     *   - tenantId = null  → app-wide direct roles + app-wide group roles only
+     *   - tenantId = string → tenant-scoped direct roles + tenant-scoped group roles only
+     *
+     * Tenant-scoped group roles NEVER satisfy app-wide role checks and vice versa.
+     */
+    getEffectiveRoles?(userId: string, tenantId: string | null): Promise<string[]>;
+    /** Optional. Look up an active M2M client by clientId (includes clientSecretHash for verification). */
+    getM2MClient?(clientId: string): Promise<(M2MClientRecord & {
+        clientSecretHash: string;
+    }) | null>;
+    /** Optional. Create a new M2M client. Returns the new client's id. */
+    createM2MClient?(client: {
+        clientId: string;
+        clientSecretHash: string;
+        name: string;
+        scopes: string[];
+    }): Promise<{
+        id: string;
+    }>;
+    /** Optional. Delete an M2M client by clientId. */
+    deleteM2MClient?(clientId: string): Promise<void>;
+    /** Optional. List all M2M clients (without secrets). */
+    listM2MClients?(): Promise<M2MClientRecord[]>;
+}
+export interface UserQuery {
+    email?: string;
+    externalId?: string;
+    suspended?: boolean;
+    startIndex?: number;
+    count?: number;
+}
+export interface UserRecord {
+    id: string;
+    email?: string;
+    displayName?: string;
+    firstName?: string;
+    lastName?: string;
+    externalId?: string;
+    suspended: boolean;
+    suspendedAt?: Date;
+    suspendedReason?: string;
+    emailVerified?: boolean;
+    providerIds?: string[];
 }
 export declare const setAuthAdapter: (adapter: AuthAdapter) => void;
 export declare const getAuthAdapter: () => AuthAdapter;