@zhin.js/gateway 0.0.1-bootstrap.0 → 1.1.2

package/lib/iam/rate-limit.js

@@ -0,0 +1,52 @@
+/** Login throttling: 5 failures / 15 minutes per IP and per username, then exponential lockout. */
+export class LoginRateLimiter {
+    #buckets = new Map();
+    #max;
+    #window;
+    #maxLock;
+    #now;
+    constructor(options = {}) {
+        this.#max = options.maxFailures ?? 5;
+        this.#window = options.windowMs ?? 15 * 60_000;
+        this.#maxLock = options.maxLockMs ?? 24 * 60 * 60_000;
+        this.#now = options.now ?? Date.now;
+    }
+    /** Milliseconds until any of `keys` may try again; 0 when allowed. */
+    retryAfter(keys) {
+        const now = this.#now();
+        let wait = 0;
+        for (const key of keys) {
+            const bucket = this.#buckets.get(key);
+            if (bucket && bucket.lockedUntil > now)
+                wait = Math.max(wait, bucket.lockedUntil - now);
+        }
+        return wait;
+    }
+    fail(keys) {
+        const now = this.#now();
+        for (const key of keys) {
+            const bucket = this.#buckets.get(key) ?? { failures: [], lockedUntil: 0, lockouts: 0 };
+            bucket.failures = bucket.failures.filter(at => now - at < this.#window);
+            bucket.failures.push(now);
+            if (bucket.failures.length >= this.#max) {
+                // 15 min, 30 min, 60 min … capped.
+                bucket.lockedUntil = now + Math.min(this.#window * 2 ** bucket.lockouts, this.#maxLock);
+                bucket.lockouts += 1;
+                bucket.failures = [];
+            }
+            this.#buckets.set(key, bucket);
+        }
+        if (this.#buckets.size > 10_000)
+            this.#prune(now);
+    }
+    succeed(keys) {
+        for (const key of keys)
+            this.#buckets.delete(key);
+    }
+    #prune(now) {
+        for (const [key, bucket] of this.#buckets) {
+            if (bucket.lockedUntil <= now && bucket.failures.every(at => now - at >= this.#window))
+                this.#buckets.delete(key);
+        }
+    }
+}

package/lib/iam/routes.d.ts

@@ -0,0 +1,23 @@
+import { type HttpHost, type TokenRegistry } from '@zhin.js/host-http';
+import { type ConsoleIamService } from './service.js';
+import type { ConsoleSetupService } from './setup-service.js';
+/** What `/auth/*` needs from a Host: the gateway's HTTP server or an in-process `HttpHost`. */
+export interface ConsoleAuthRouteHost {
+    route: HttpHost['route'];
+    readonly tokenRegistry: TokenRegistry;
+}
+export interface RegisterConsoleAuthRoutesOptions {
+    readonly http: ConsoleAuthRouteHost;
+    readonly base: string;
+    readonly iam: () => ConsoleIamService | undefined;
+    readonly setup: ConsoleSetupService;
+    /** Restarts the process after the database changed (injected; never exits directly). */
+    readonly requestRestart?: () => void;
+    /**
+     * Onboarding state (ADR 0053 §4): added to `GET /auth/setup`, and to `/auth/me` for callers
+     * holding `plugin.manage`.
+     */
+    readonly onboarding?: () => Promise<unknown>;
+}
+/** `/auth/*` (ADR 0049 §5, §7). The HTTP Host has already authenticated the caller. */
+export declare function registerConsoleAuthRoutes(options: RegisterConsoleAuthRoutesOptions): Array<() => void>;

package/lib/iam/routes.js

@@ -0,0 +1,157 @@
+import { CONSOLE_AUTH_ROUTES } from '@zhin.js/console-protocol';
+import { HttpBodyError, globalPermissions, isUserPrincipal, jsonResponse, readJsonBody, requestMeta, } from '@zhin.js/host-http';
+import { CONSOLE_PERMISSIONS } from '@zhin.js/console-protocol';
+import { DATABASE_BUSY_RETRY_AFTER_SECONDS, isDatabaseBusyError } from '../database/project-database.js';
+import { IamError } from './service.js';
+const BODY_LIMIT = 16 * 1024;
+/** `/auth/*` (ADR 0049 §5, §7). The HTTP Host has already authenticated the caller. */
+export function registerConsoleAuthRoutes(options) {
+    const { http, base } = options;
+    const route = (method, path, handler, summary) => http.route(method, `${base}${path}`, async (request, { principal, remoteAddress }) => {
+        const noStore = { 'cache-control': 'no-store' };
+        try {
+            const result = await handler({
+                request,
+                meta: requestMeta(request, remoteAddress),
+                principal,
+                body: async () => {
+                    const value = await readJsonBody(request, { limit: BODY_LIMIT });
+                    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+                },
+            });
+            return jsonResponse(result.status, result.body, { ...noStore, ...result.headers });
+        }
+        catch (error) {
+            if (error instanceof HttpBodyError) {
+                return jsonResponse(error.statusCode, { success: false, error: error.message }, noStore);
+            }
+            if (error instanceof IamError) {
+                return jsonResponse(error.status, { success: false, code: error.code, error: error.message }, error.retryAfterMs ? { ...noStore, 'retry-after': String(Math.ceil(error.retryAfterMs / 1000)) } : noStore);
+            }
+            if (isDatabaseBusyError(error)) {
+                return jsonResponse(503, { success: false, code: 'database_busy', error: '数据库正忙，请稍后重试' }, { ...noStore, 'retry-after': String(DATABASE_BUSY_RETRY_AFTER_SECONDS) });
+            }
+            return jsonResponse(500, { success: false, code: 'failed', error: '操作失败' }, noStore);
+        }
+    }, { summary, tags: ['auth'] });
+    const requireIam = () => {
+        const iam = options.iam();
+        if (!iam?.ready)
+            throw new IamError('unavailable', '当前数据库不能存储账号，或尚未就绪');
+        return iam;
+    };
+    const requireUser = (principal) => {
+        if (!isUserPrincipal(principal))
+            throw new IamError('unauthorized', '需要登录');
+        return principal;
+    };
+    /** Setup is open only to the bootstrap principal while no owner exists. */
+    const requireSetup = (principal) => {
+        if (!options.setup.setupRequired())
+            throw new IamError('conflict', '已初始化');
+        if (principal?.kind !== 'bootstrap')
+            throw new IamError('forbidden', '需要初始化令牌');
+    };
+    const ok = (data, status = 200) => ({ status, body: { success: true, data } });
+    const onboarding = async () => {
+        if (!options.onboarding)
+            return {};
+        try {
+            return { onboarding: await options.onboarding() };
+        }
+        catch {
+            return {};
+        }
+    };
+    const managesPlugins = (permissions) => permissions.includes(CONSOLE_PERMISSIONS.PLUGIN_MANAGE);
+    return [
+        route('POST', CONSOLE_AUTH_ROUTES.LOGIN, async ({ meta, body }) => {
+            const input = await body();
+            const result = await requireIam().login(input.username, input.password, meta);
+            return ok(result);
+        }, 'Console login'),
+        route('POST', CONSOLE_AUTH_ROUTES.LOGOUT, async ({ principal }) => {
+            await requireIam().logout(requireUser(principal));
+            return ok({ loggedOut: true });
+        }, 'Console logout'),
+        route('GET', CONSOLE_AUTH_ROUTES.ME, async ({ principal }) => {
+            const setupRequired = options.setup.setupRequired();
+            if (!principal)
+                return ok({ kind: 'anonymous', permissions: [], bindings: [], setupRequired });
+            if (principal.kind === 'bootstrap') {
+                const permissions = globalPermissions(principal);
+                return ok({
+                    kind: 'bootstrap', open: principal.open, permissions, bindings: [], setupRequired,
+                    ...(managesPlugins(permissions) ? await onboarding() : {}),
+                });
+            }
+            const user = await options.iam()?.getUser(principal.userId);
+            // Level grants expanded over the loaded plugins' permission catalog.
+            const permissions = globalPermissions(principal, options.http.tokenRegistry?.pluginPermissions?.() ?? []);
+            return ok({
+                kind: principal.kind,
+                user: user ? { id: user.id, username: user.username, displayName: user.displayName } : { id: principal.userId, username: principal.username, displayName: principal.displayName },
+                permissions,
+                bindings: principal.grants.map(grant => ({ role: grant.role, scope: grant.scope, permissions: grant.permissions })),
+                setupRequired,
+                ...(managesPlugins(permissions) ? await onboarding() : {}),
+            });
+        }, 'Current Console principal'),
+        route('POST', CONSOLE_AUTH_ROUTES.PASSWORD, async ({ meta, principal, body }) => {
+            const input = await body();
+            const issued = await requireIam().changePassword(requireUser(principal), input.currentPassword, input.newPassword, meta);
+            return ok({ changed: true, ...issued });
+        }, 'Change own password'),
+        route('GET', CONSOLE_AUTH_ROUTES.TOKENS, async ({ principal }) => {
+            return ok({ tokens: await requireIam().listTokens(requireUser(principal).userId) });
+        }, 'List own API tokens'),
+        route('POST', CONSOLE_AUTH_ROUTES.TOKENS, async ({ principal, body }) => {
+            const user = requireUser(principal);
+            const input = await body();
+            const created = await requireIam().createToken(user.userId, { name: input.name, permissions: input.permissions, expiresAt: input.expiresAt });
+            requireIam().audit({ actor: `user:${user.userId}`, action: 'auth.tokens.create', target: `api-token:${created.record.id}`, outcome: 'ok' });
+            return ok(created, 201);
+        }, 'Create own API token'),
+        route('POST', CONSOLE_AUTH_ROUTES.TOKENS_REVOKE, async ({ principal, body }) => {
+            const user = requireUser(principal);
+            const input = await body();
+            await requireIam().revokeToken(String(input.id ?? ''), user.userId);
+            requireIam().audit({ actor: `user:${user.userId}`, action: 'auth.tokens.revoke', target: `api-token:${String(input.id ?? '')}`, outcome: 'ok' });
+            return ok({ revoked: true });
+        }, 'Revoke own API token'),
+        // ---------------------------------------------------------------- setup (bootstrap only)
+        route('GET', CONSOLE_AUTH_ROUTES.SETUP, async ({ principal }) => {
+            requireSetup(principal);
+            return ok({ ...await options.setup.status(), ...await onboarding() });
+        }, 'Setup status'),
+        route('POST', CONSOLE_AUTH_ROUTES.SETUP, async ({ meta, principal, body }) => {
+            requireSetup(principal);
+            const input = await body();
+            const { user } = await options.setup.createOwner({ username: input.username, password: input.password, displayName: input.displayName });
+            const iam = requireIam();
+            const session = await iam.issueSession(user.id, meta);
+            iam.audit({ actor: 'bootstrap', action: 'auth.setup', target: `user:${user.id}`, outcome: 'ok' });
+            return ok({ ...session, user }, 201);
+        }, 'Create the first owner'),
+        route('GET', CONSOLE_AUTH_ROUTES.SETUP_DATABASE, async ({ principal }) => {
+            requireSetup(principal);
+            const status = await options.setup.status();
+            return ok({ ...status.database, drivers: await options.setup.drivers() });
+        }, 'Setup database choices'),
+        route('POST', CONSOLE_AUTH_ROUTES.SETUP_DATABASE_TEST, async ({ principal, body }) => {
+            requireSetup(principal);
+            const input = await body();
+            return ok(await options.setup.testDatabase({ dialect: input.dialect, connection: input.connection }));
+        }, 'Test a database connection'),
+        route('POST', CONSOLE_AUTH_ROUTES.SETUP_DATABASE, async ({ principal, body }) => {
+            requireSetup(principal);
+            const input = await body();
+            const result = await options.setup.applyDatabase({ dialect: input.dialect, connection: input.connection });
+            if (!options.requestRestart)
+                return ok({ restarting: false, ...result });
+            // Respond first; the database is a process resource and needs a restart.
+            setTimeout(() => options.requestRestart?.(), 300).unref?.();
+            return ok({ restarting: true, notice: result.notice });
+        }, 'Save the setup database'),
+    ];
+}

package/lib/iam/rpc.d.ts

@@ -0,0 +1,14 @@
+import type { ConsolePrincipal } from '@zhin.js/host-http';
+import { type BindingInput, type ConsoleIamService } from './service.js';
+export interface IamRpcReply {
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+    readonly headers?: Readonly<Record<string, string>>;
+}
+export declare function isIamRpc(type: unknown): boolean;
+/**
+ * `iam.*` Console RPC. The caller has already passed the permission gate
+ * (`iam.view` / `iam.manage`); this only validates input and runs the operation.
+ */
+export declare function dispatchIamRpc(message: Readonly<Record<string, unknown>>, service: ConsoleIamService | undefined, principal: ConsolePrincipal): Promise<IamRpcReply>;
+export declare function bindingsOf(value: unknown): readonly BindingInput[];

package/lib/iam/rpc.js

@@ -0,0 +1,100 @@
+import { IAM_RPC, toConsoleIamPluginPermissions } from '@zhin.js/console-protocol';
+import { DATABASE_BUSY_RETRY_AFTER_SECONDS, isDatabaseBusyError } from '../database/project-database.js';
+import { IamError } from './service.js';
+const IAM_TYPES = new Set(Object.values(IAM_RPC));
+export function isIamRpc(type) {
+    return typeof type === 'string' && IAM_TYPES.has(type);
+}
+/**
+ * `iam.*` Console RPC. The caller has already passed the permission gate
+ * (`iam.view` / `iam.manage`); this only validates input and runs the operation.
+ */
+export async function dispatchIamRpc(message, service, principal) {
+    const requestId = message.requestId;
+    const type = String(message.type ?? '');
+    const payload = (message.data && typeof message.data === 'object' && !Array.isArray(message.data)
+        ? message.data
+        : message);
+    const ok = (data) => ({ status: 200, body: { success: true, data, type, requestId } });
+    try {
+        if (!service?.ready)
+            throw new IamError('unavailable', '当前数据库不能存储账号，或尚未就绪');
+        const id = (key = 'id') => {
+            const value = payload[key];
+            if (typeof value !== 'string' || !value)
+                throw new IamError('invalid_input', `${key} 必填`);
+            return value;
+        };
+        switch (type) {
+            case IAM_RPC.USERS_LIST: return ok({ users: await service.listUsers() });
+            case IAM_RPC.USERS_CREATE: return ok({ user: await service.createUser({
+                    username: payload.username, password: payload.password, displayName: payload.displayName,
+                    bindings: bindingsOf(payload.bindings ?? []),
+                }) });
+            case IAM_RPC.USERS_UPDATE: return ok({ user: await service.updateUser(id(), { displayName: payload.displayName, disabled: payload.disabled }) });
+            case IAM_RPC.USERS_DISABLE: return ok({ user: await service.setDisabled(id(), payload.disabled !== false) });
+            case IAM_RPC.USERS_DELETE:
+                await service.deleteUser(id());
+                return ok({ deleted: true });
+            case IAM_RPC.USERS_RESET_PASSWORD:
+                await service.resetPassword(id(), payload.password);
+                return ok({ reset: true });
+            case IAM_RPC.ROLES_LIST: return ok({ roles: await service.listRoles(), pluginPermissions: toConsoleIamPluginPermissions(service.pluginPermissionCatalog()) });
+            case IAM_RPC.ROLES_CREATE: return ok(withWarnings(service, { role: await service.createRole({ name: payload.name, description: payload.description, permissions: payload.permissions }) }));
+            case IAM_RPC.ROLES_UPDATE: return ok(withWarnings(service, { role: await service.updateRole(id(), { description: payload.description, permissions: payload.permissions }) }));
+            case IAM_RPC.ROLES_DELETE:
+                await service.deleteRole(id());
+                return ok({ deleted: true });
+            case IAM_RPC.BINDINGS_SET: return ok({ user: await service.setBindings(id('userId'), bindingsOf(payload.bindings)) });
+            case IAM_RPC.TOKENS_LIST: return ok({ tokens: await service.listTokens(typeof payload.userId === 'string' ? payload.userId : undefined) });
+            case IAM_RPC.TOKENS_CREATE: {
+                const userId = typeof payload.userId === 'string' && payload.userId
+                    ? payload.userId
+                    : principal.kind === 'bootstrap' ? id('userId') : principal.userId;
+                const created = await service.createToken(userId, { name: payload.name, permissions: payload.permissions, expiresAt: payload.expiresAt });
+                return ok({ token: created.token, record: created.record, ...pluginWarnings(service, created.record.permissions ?? []) });
+            }
+            case IAM_RPC.TOKENS_REVOKE:
+                await service.revokeToken(id());
+                return ok({ revoked: true });
+            case IAM_RPC.AUDIT_LIST: return ok(await service.listAudit({
+                actor: payload.actor, action: payload.action, since: payload.since, until: payload.until,
+                limit: payload.limit, before: payload.before,
+            }));
+            default: return { status: 400, body: { success: false, error: `Unknown RPC type: ${type}`, requestId } };
+        }
+    }
+    catch (error) {
+        if (error instanceof IamError) {
+            return { status: error.status, body: { success: false, code: error.code, error: error.message, requestId } };
+        }
+        if (isDatabaseBusyError(error)) {
+            return { status: 503, body: { success: false, code: 'database_busy', error: '数据库正忙，请稍后重试', requestId }, headers: { 'retry-after': String(DATABASE_BUSY_RETRY_AFTER_SECONDS) } };
+        }
+        return { status: 500, body: { success: false, code: 'failed', error: '访问控制操作失败', requestId } };
+    }
+}
+/** `warnings` for plugin permissions no loaded plugin uses yet (accepted; they grant nothing until one does). */
+function pluginWarnings(service, permissions) {
+    const unknown = service.unknownPluginPermissions(permissions);
+    return unknown.length ? { warnings: unknown.map(permission => `插件权限 ${permission} 当前没有已加载的插件使用`) } : {};
+}
+function withWarnings(service, data) {
+    return { ...data, ...pluginWarnings(service, data.role.permissions) };
+}
+export function bindingsOf(value) {
+    if (!Array.isArray(value))
+        throw new IamError('invalid_input', 'bindings 必须是数组');
+    return value.map(item => {
+        if (!item || typeof item !== 'object')
+            throw new IamError('invalid_input', 'binding 无效');
+        const record = item;
+        if (typeof record.role !== 'string')
+            throw new IamError('invalid_input', 'binding.role 必填');
+        return {
+            role: record.role,
+            ...(typeof record.scopeKind === 'string' ? { scopeKind: record.scopeKind } : {}),
+            ...(typeof record.scopeKey === 'string' ? { scopeKey: record.scopeKey } : {}),
+        };
+    });
+}

package/lib/iam/service.d.ts

@@ -0,0 +1,203 @@
+import { type ConsoleBindingScope, type ConsolePluginPermissionInfo, type ConsoleRolePluginPermission } from '@zhin.js/console-protocol';
+import type { ConsoleAccessProvider, ConsoleAuditEntry, ConsoleRequestMeta, ConsoleUserPrincipal } from '@zhin.js/host-http';
+import type { DatabaseHostModel } from '@zhin.js/plugin-runtime';
+import { LoginRateLimiter } from './rate-limit.js';
+export type IamErrorCode = 'invalid_input' | 'not_found' | 'conflict' | 'forbidden' | 'last_owner' | 'unauthorized' | 'rate_limited' | 'unavailable';
+export declare class IamError extends Error {
+    readonly code: IamErrorCode;
+    readonly retryAfterMs?: number | undefined;
+    readonly status: number;
+    constructor(code: IamErrorCode, message: string, retryAfterMs?: number | undefined);
+}
+/** Minimal database surface: the process DatabaseHost, or one the CLI opens itself. */
+export interface IamDatabase {
+    readonly started: boolean;
+    readonly models: {
+        get(name: string): DatabaseHostModel | undefined;
+    };
+}
+export interface ConsoleUserView {
+    readonly id: string;
+    readonly username: string;
+    readonly displayName: string;
+    readonly disabled: boolean;
+    readonly createdAt: number;
+    readonly updatedAt: number;
+    readonly passwordChangedAt: number;
+    readonly bindings: readonly ConsoleBindingView[];
+}
+export interface ConsoleBindingView {
+    readonly id: string;
+    readonly roleId: string;
+    readonly role: string;
+    readonly scope: ConsoleBindingScope;
+}
+export interface ConsoleRoleView {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly builtin: boolean;
+    readonly permissions: readonly string[];
+    /**
+     * Plugin permissions this role holds right now: by level (`plugin.perms.<level>`, expanded
+     * over the loaded plugins' catalog) or listed explicitly. Only on `listRoles` / role writes.
+     */
+    readonly pluginPermissions?: readonly ConsoleRolePluginPermission[];
+}
+export interface ConsoleTokenView {
+    readonly id: string;
+    readonly userId: string;
+    readonly name: string;
+    readonly permissions: readonly string[] | null;
+    readonly expiresAt: number | null;
+    readonly lastUsedAt: number | null;
+    readonly createdAt: number;
+}
+export interface ConsoleAuditView {
+    readonly id: string;
+    readonly at: number;
+    readonly actor: string;
+    readonly action: string;
+    readonly target: string | null;
+    readonly outcome: string;
+    readonly detail: unknown;
+    readonly ip: string | null;
+}
+export interface BindingInput {
+    readonly role: string;
+    readonly scopeKind?: string;
+    readonly scopeKey?: string | null;
+}
+export interface ConsoleIamServiceOptions {
+    readonly database: IamDatabase;
+    /** Marker telling a restarting Host that setup is done before the database is up. */
+    readonly projectRoot?: string;
+    readonly now?: () => number;
+    readonly sessionIdleMs?: number;
+    readonly sessionMaxMs?: number;
+    readonly auditRetentionMs?: number;
+    readonly rateLimiter?: LoginRateLimiter;
+    readonly onError?: (error: unknown) => void;
+    /**
+     * Plugin permission catalog of the loaded plugins (ids and declared-or-inferred levels).
+     * Without it, levels are inferred from the permission suffix.
+     */
+    readonly pluginPermissions?: () => readonly ConsolePluginPermissionInfo[];
+}
+/**
+ * What is wrong with a new account's username / password, or null — the rules
+ * {@link ConsoleIamService.createUser} / `createOwner` enforce, for callers that must check before
+ * changing anything else (`zhin console init` switches the database first).
+ */
+export declare function accountInputProblem(input: Readonly<{
+    username: unknown;
+    password: unknown;
+}>): string | null;
+/** Why a user's credentials were revoked (sessions always; API tokens on disable/delete). */
+export type ConsoleCredentialRevocationReason = 'password' | 'disabled' | 'deleted' | 'bindings';
+export interface ConsoleCredentialRevocation {
+    readonly userId: string;
+    readonly reason: ConsoleCredentialRevocationReason;
+}
+/** DB-backed users, roles, sessions, API tokens and audit (ADR 0049 §2, §5, §6). */
+export declare class ConsoleIamService implements ConsoleAccessProvider {
+    #private;
+    constructor(options: ConsoleIamServiceOptions);
+    get ready(): boolean;
+    /** Seeds built-in roles and loads the owner state; call after the database started. */
+    start(options?: Readonly<{
+        timers?: boolean;
+    }>): Promise<void>;
+    /**
+     * Notified after a user's sessions were revoked or their grants changed, so long-lived
+     * connections (terminal, SSE) authenticated earlier can be closed. Returns an unsubscriber.
+     */
+    onCredentialsRevoked(listener: (event: ConsoleCredentialRevocation) => void): () => void;
+    stop(): void;
+    initialized(): boolean;
+    refreshOwnerState(): Promise<boolean>;
+    authenticate(token: string, meta?: ConsoleRequestMeta): Promise<ConsoleUserPrincipal | null>;
+    audit(entry: ConsoleAuditEntry): void;
+    login(usernameInput: unknown, password: unknown, meta?: ConsoleRequestMeta): Promise<{
+        token: string;
+        expiresAt: number;
+        user: ConsoleUserView;
+    }>;
+    logout(principal: ConsoleUserPrincipal): Promise<void>;
+    changePassword(principal: ConsoleUserPrincipal, current: unknown, next: unknown, meta?: ConsoleRequestMeta): Promise<{
+        token?: string;
+        expiresAt?: number;
+    }>;
+    listUsers(): Promise<readonly ConsoleUserView[]>;
+    getUser(id: string): Promise<ConsoleUserView | null>;
+    findUser(username: string): Promise<ConsoleUserView | null>;
+    createUser(input: Readonly<{
+        username: unknown;
+        password: unknown;
+        displayName?: unknown;
+        bindings?: readonly BindingInput[];
+    }>): Promise<ConsoleUserView>;
+    /** First owner (setup). Conflict once an enabled global owner exists. */
+    createOwner(input: Readonly<{
+        username: unknown;
+        password: unknown;
+        displayName?: unknown;
+    }>): Promise<ConsoleUserView>;
+    /** Issues a session for a user (setup returns one for the new owner). */
+    issueSession(userId: string, meta?: ConsoleRequestMeta): Promise<{
+        token: string;
+        expiresAt: number;
+    }>;
+    updateUser(id: string, patch: Readonly<{
+        displayName?: unknown;
+        disabled?: unknown;
+    }>): Promise<ConsoleUserView>;
+    setDisabled(id: string, disabled: boolean): Promise<ConsoleUserView>;
+    deleteUser(id: string): Promise<void>;
+    resetPassword(id: string, password: unknown): Promise<void>;
+    listRoles(): Promise<readonly ConsoleRoleView[]>;
+    /** The loaded plugins' permission catalog (what the Console's role editor offers). */
+    pluginPermissionCatalog(): readonly ConsolePluginPermissionInfo[];
+    /**
+     * Plugin permission ids in `permissions` that no loaded plugin uses (accepted, but they grant
+     * nothing until a plugin uses them); for the warnings of role and token writes.
+     */
+    unknownPluginPermissions(permissions: readonly string[]): readonly string[];
+    createRole(input: Readonly<{
+        name: unknown;
+        description?: unknown;
+        permissions: unknown;
+    }>): Promise<ConsoleRoleView>;
+    updateRole(id: string, patch: Readonly<{
+        description?: unknown;
+        permissions?: unknown;
+    }>): Promise<ConsoleRoleView>;
+    deleteRole(id: string): Promise<void>;
+    /** Replaces all bindings of a user. */
+    setBindings(userId: string, inputs: readonly BindingInput[]): Promise<ConsoleUserView>;
+    listTokens(userId?: string): Promise<readonly ConsoleTokenView[]>;
+    /** Returns the plaintext once; only its SHA-256 is stored. */
+    createToken(userId: string, input: Readonly<{
+        name: unknown;
+        permissions?: unknown;
+        expiresAt?: unknown;
+    }>): Promise<{
+        token: string;
+        record: ConsoleTokenView;
+    }>;
+    /** `ownerUserId` restricts the revoke to that user's own tokens (self-service). */
+    revokeToken(id: string, ownerUserId?: string): Promise<void>;
+    listAudit(filter?: Readonly<{
+        actor?: unknown;
+        action?: unknown;
+        since?: unknown;
+        until?: unknown;
+        limit?: unknown;
+        before?: unknown;
+    }>): Promise<{
+        entries: readonly ConsoleAuditView[];
+        next: number | null;
+    }>;
+    /** Daily: audit older than the retention window and expired sessions. */
+    cleanup(): Promise<void>;
+}