@zhin.js/gateway 0.0.0-stage → 1.1.1

package/lib/iam/crypto.js

@@ -0,0 +1,58 @@
+import { createHash, randomBytes, scrypt, timingSafeEqual } from 'node:crypto';
+/** ADR 0049 §2: scrypt N=2^15, r=8, p=1, 32-byte salt. */
+const SCRYPT = Object.freeze({ N: 2 ** 15, r: 8, p: 1, keyLength: 32, maxmem: 64 * 1024 * 1024 });
+export const PASSWORD_MIN_LENGTH = 10;
+export const PASSWORD_MAX_LENGTH = 1024;
+export function passwordProblem(password) {
+    if (typeof password !== 'string')
+        return '密码必须是字符串';
+    if (password.length < PASSWORD_MIN_LENGTH)
+        return `密码至少 ${PASSWORD_MIN_LENGTH} 位`;
+    if (password.length > PASSWORD_MAX_LENGTH)
+        return '密码过长';
+    return null;
+}
+function derive(password, salt, params) {
+    return new Promise((resolve, reject) => {
+        scrypt(password.normalize('NFKC'), salt, params.keyLength, {
+            N: params.N, r: params.r, p: params.p, maxmem: SCRYPT.maxmem,
+        }, (error, key) => (error ? reject(error) : resolve(key)));
+    });
+}
+/** `scrypt$N$r$p$salt$hash` (base64url). */
+export async function hashPassword(password) {
+    const salt = randomBytes(32);
+    const key = await derive(password, salt, SCRYPT);
+    return ['scrypt', SCRYPT.N, SCRYPT.r, SCRYPT.p, salt.toString('base64url'), key.toString('base64url')].join('$');
+}
+export async function verifyPassword(password, encoded) {
+    const parts = encoded.split('$');
+    if (parts.length !== 6 || parts[0] !== 'scrypt')
+        return false;
+    const [N, r, p] = parts.slice(1, 4).map(Number);
+    if (![N, r, p].every(value => Number.isSafeInteger(value) && value > 0) || N > 2 ** 20)
+        return false;
+    const salt = Buffer.from(parts[4], 'base64url');
+    const expected = Buffer.from(parts[5], 'base64url');
+    if (salt.length < 16 || expected.length < 16)
+        return false;
+    const actual = await derive(password, salt, { N: N, r: r, p: p, keyLength: expected.length });
+    return actual.length === expected.length && timingSafeEqual(actual, expected);
+}
+let dummyHash;
+/** Burns the same work as a real check so unknown usernames are not faster. */
+export async function verifyAgainstDummy(password) {
+    dummyHash ??= hashPassword('dummy-password-for-timing');
+    await verifyPassword(password, await dummyHash);
+    return false;
+}
+/** 32 random bytes, base64url (ADR 0049 §2). */
+export function generateToken() {
+    return randomBytes(32).toString('base64url');
+}
+export function sha256(value) {
+    return createHash('sha256').update(value, 'utf8').digest('hex');
+}
+export function newId() {
+    return randomBytes(16).toString('hex');
+}

package/lib/iam/index.d.ts

@@ -0,0 +1,8 @@
+export { installConsoleIam, projectEnvironment, type ConsoleIamInstallation, type InstallConsoleIamOptions } from './install.js';
+export { accountInputProblem, ConsoleIamService, IamError, type BindingInput, type ConsoleAuditView, type ConsoleBindingView, type ConsoleCredentialRevocation, type ConsoleCredentialRevocationReason, type ConsoleIamServiceOptions, type ConsoleRoleView, type ConsoleTokenView, type ConsoleUserView, type IamDatabase, type IamErrorCode, } from './service.js';
+export { ConsoleSetupService, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, type ConsoleSetupServiceOptions, type SetupConfigPort, type SetupDatabaseField, type SetupDatabaseInput, type SetupDatabaseSummary, type SetupDriver, type SetupEnvFilePort, type SetupStatus, } from './setup-service.js';
+export { defineConsoleIamTables, IAM_DIALECTS, IAM_TABLE_DEFINITIONS, IAM_TABLES } from './tables.js';
+export { dispatchIamRpc, isIamRpc } from './rpc.js';
+export { registerConsoleAuthRoutes } from './routes.js';
+export { LoginRateLimiter } from './rate-limit.js';
+export { createLocalConsoleAdmin, type LocalConsoleAdmin, type LocalConsoleAdminOptions, type LocalConsoleAdminResult } from './local-admin.js';

package/lib/iam/index.js

@@ -0,0 +1,8 @@
+export { installConsoleIam, projectEnvironment } from './install.js';
+export { accountInputProblem, ConsoleIamService, IamError, } from './service.js';
+export { ConsoleSetupService, SETUP_NO_MIGRATION_NOTICE, upsertDotenv, } from './setup-service.js';
+export { defineConsoleIamTables, IAM_DIALECTS, IAM_TABLE_DEFINITIONS, IAM_TABLES } from './tables.js';
+export { dispatchIamRpc, isIamRpc } from './rpc.js';
+export { registerConsoleAuthRoutes } from './routes.js';
+export { LoginRateLimiter } from './rate-limit.js';
+export { createLocalConsoleAdmin } from './local-admin.js';

package/lib/iam/install.d.ts

@@ -0,0 +1,36 @@
+import type { HttpHost } from '@zhin.js/host-http';
+import { ConsoleIamService, type IamDatabase } from './service.js';
+import { ConsoleSetupService, type SetupConfigPort } from './setup-service.js';
+import { type IamTableHost } from './tables.js';
+export interface InstallConsoleIamOptions {
+    /** Process database; tables are defined here, so call before it starts. */
+    readonly database: IamDatabase & IamTableHost;
+    /** Config file writer (ConsoleConfigurationStore). */
+    readonly configStore: SetupConfigPort;
+    readonly projectRoot: string;
+    readonly apiBase?: string;
+    readonly logger?: Readonly<{
+        warn(message: string): void;
+    }>;
+    /** Process restart after the setup wizard changed the database. */
+    readonly requestRestart?: () => void;
+    /** `${…}` lookup for setup validation (defaults to process env + project `.env`). */
+    readonly environment?: () => Promise<Readonly<Record<string, string | undefined>>>;
+}
+export interface ConsoleIamInstallation {
+    readonly service: ConsoleIamService;
+    readonly setup: ConsoleSetupService;
+    /** Whether this database dialect can hold accounts. */
+    readonly supported: boolean;
+    /** Call once the database has started (idempotent). */
+    activate(): Promise<void>;
+    dispose(): void;
+}
+/**
+ * The single wiring point of Console access control (ADR 0049) into a Host process:
+ * tables, the session resolver behind `http.tokenRegistry`, `/auth/*` routes and the setup flow.
+ * Depends only on host-http, the database port and config/env file IO.
+ */
+export declare function installConsoleIam(http: HttpHost, options: InstallConsoleIamOptions): ConsoleIamInstallation;
+/** process env overlaid with the project `.env` (what `${…}` in config resolves against). */
+export declare function projectEnvironment(projectRoot: string): Promise<Readonly<Record<string, string | undefined>>>;

package/lib/iam/install.js

@@ -0,0 +1,74 @@
+import { join } from 'node:path';
+import { readEnvFile, writeEnvFile } from '../config/environment-files.js';
+import { normalizeBase } from '../http-response.js';
+import { registerConsoleAuthRoutes } from './routes.js';
+import { ConsoleIamService } from './service.js';
+import { ConsoleSetupService } from './setup-service.js';
+import { defineConsoleIamTables } from './tables.js';
+/**
+ * The single wiring point of Console access control (ADR 0049) into a Host process:
+ * tables, the session resolver behind `http.tokenRegistry`, `/auth/*` routes and the setup flow.
+ * Depends only on host-http, the database port and config/env file IO.
+ */
+export function installConsoleIam(http, options) {
+    const supported = defineConsoleIamTables(options.database);
+    const service = new ConsoleIamService({
+        database: options.database,
+        projectRoot: options.projectRoot,
+        onError: error => options.logger?.warn(`console iam: ${error instanceof Error ? error.message : String(error)}`),
+        // Installed on the token registry by the runtime composition root; empty until then.
+        pluginPermissions: () => http.tokenRegistry.pluginPermissions(),
+    });
+    const setup = new ConsoleSetupService({
+        projectRoot: options.projectRoot,
+        config: options.configStore,
+        envFile: {
+            read: () => readEnvFile(options.projectRoot, '.env'),
+            write: content => writeEnvFile(options.projectRoot, '.env', content),
+        },
+        iam: () => (supported ? service : undefined),
+        environment: options.environment ?? (() => projectEnvironment(options.projectRoot)),
+    });
+    const disposers = [];
+    if (supported)
+        disposers.push(http.tokenRegistry.useAccessProvider(service));
+    else
+        options.logger?.warn('console iam: the configured database cannot store Console users; run the setup wizard to choose sqlite/mysql/pg/mongodb');
+    disposers.push(...registerConsoleAuthRoutes({
+        http,
+        base: normalizeBase(options.apiBase ?? '/api'),
+        iam: () => (supported ? service : undefined),
+        setup,
+        ...(options.requestRestart ? { requestRestart: options.requestRestart } : {}),
+    }));
+    let activation;
+    return Object.freeze({
+        service,
+        setup,
+        supported,
+        activate() {
+            if (!supported)
+                return Promise.resolve();
+            activation ??= service.start();
+            return activation;
+        },
+        dispose() {
+            service.stop();
+            for (const dispose of disposers.reverse())
+                dispose();
+        },
+    });
+}
+/** process env overlaid with the project `.env` (what `${…}` in config resolves against). */
+export async function projectEnvironment(projectRoot) {
+    const { parse } = await import('dotenv');
+    const values = { ...process.env };
+    for (const file of ['.env', `.env.${process.env.NODE_ENV === 'production' ? 'production' : 'development'}`]) {
+        try {
+            const { readFile } = await import('node:fs/promises');
+            Object.assign(values, parse(await readFile(join(projectRoot, file), 'utf8')));
+        }
+        catch { /* missing layers are fine */ }
+    }
+    return values;
+}

package/lib/iam/local-admin.d.ts

@@ -0,0 +1,27 @@
+import { type LocalGatewayError } from '../local/protocol.js';
+import { type ConsoleIamService } from './service.js';
+import type { ConsoleSetupService } from './setup-service.js';
+export type LocalConsoleAdminResult = Readonly<{
+    ok: true;
+    data: unknown;
+}> | Readonly<{
+    ok: false;
+    error: LocalGatewayError;
+}>;
+export interface LocalConsoleAdmin {
+    owns(type: string): boolean;
+    handle(type: string, data: unknown): Promise<LocalConsoleAdminResult>;
+}
+export interface LocalConsoleAdminOptions {
+    readonly setup: ConsoleSetupService;
+    readonly iam: () => ConsoleIamService | undefined;
+    /**
+     * After the setup database was written: reconnect the gateway to it (awaited, so the next
+     * request already uses it) and restart the instance (not awaited). Returns whether the instance
+     * is being restarted.
+     */
+    readonly switchDatabase: () => Promise<{
+        restarting: boolean;
+    }>;
+}
+export declare function createLocalConsoleAdmin(options: LocalConsoleAdminOptions): LocalConsoleAdmin;

package/lib/iam/local-admin.js

@@ -0,0 +1,102 @@
+/**
+ * Socket-only Console administration (`gateway.console.*`, principal `'local'`): what
+ * `zhin console init` / `zhin console user …` do when a gateway runs (ADR 0049 §7, ADR 0053 §5).
+ * The gateway's own {@link ConsoleSetupService} and {@link ConsoleIamService} answer, so the CLI
+ * and the web wizard share one flow, a database switch is applied by the gateway itself and the
+ * owner state changes at once. Never reachable over HTTP (the local socket's owner check is the
+ * authentication).
+ */
+import { DATABASE_BUSY_RETRY_AFTER_SECONDS, isDatabaseBusyError } from '../database/project-database.js';
+import { LOCAL_GATEWAY_RPC } from '../local/protocol.js';
+import { IamError } from './service.js';
+const TYPES = new Set([
+    LOCAL_GATEWAY_RPC.CONSOLE_SETUP_STATUS,
+    LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DRIVERS,
+    LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DATABASE_TEST,
+    LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DATABASE,
+    LOCAL_GATEWAY_RPC.CONSOLE_SETUP_OWNER,
+    LOCAL_GATEWAY_RPC.CONSOLE_USER_LIST,
+    LOCAL_GATEWAY_RPC.CONSOLE_USER_CREATE,
+    LOCAL_GATEWAY_RPC.CONSOLE_USER_PASSWD,
+    LOCAL_GATEWAY_RPC.CONSOLE_USER_DISABLE,
+]);
+const ACTOR = 'local';
+export function createLocalConsoleAdmin(options) {
+    const { setup } = options;
+    const requireIam = () => {
+        const iam = options.iam();
+        if (!iam?.ready)
+            throw new IamError('unavailable', '当前数据库不能存储 Console 用户，或尚未就绪；请先运行 zhin console init 选择 sqlite/mysql/pg/mongodb');
+        return iam;
+    };
+    const requireUser = async (iam, username) => {
+        const user = typeof username === 'string' ? await iam.findUser(username) : null;
+        if (!user)
+            throw new IamError('not_found', `用户不存在：${typeof username === 'string' ? username : ''}`);
+        return user;
+    };
+    const audit = (action, target) => {
+        options.iam()?.audit({ actor: ACTOR, action, ...(target ? { target } : {}), outcome: 'ok' });
+    };
+    async function run(type, input) {
+        switch (type) {
+            case LOCAL_GATEWAY_RPC.CONSOLE_SETUP_STATUS: return setup.status();
+            case LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DRIVERS: return setup.drivers();
+            case LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DATABASE_TEST:
+                return setup.testDatabase({ dialect: input.dialect, connection: input.connection });
+            case LOCAL_GATEWAY_RPC.CONSOLE_SETUP_DATABASE: {
+                const applied = await setup.applyDatabase({ dialect: input.dialect, connection: input.connection });
+                const { restarting } = await options.switchDatabase();
+                audit('auth.setup.database');
+                return { notice: applied.notice, switched: true, restarting };
+            }
+            case LOCAL_GATEWAY_RPC.CONSOLE_SETUP_OWNER: {
+                const { user } = await setup.createOwner({ username: input.username, password: input.password, displayName: input.displayName });
+                audit('auth.setup', `user:${user.id}`);
+                return { user };
+            }
+            case LOCAL_GATEWAY_RPC.CONSOLE_USER_LIST: return { users: await requireIam().listUsers() };
+            case LOCAL_GATEWAY_RPC.CONSOLE_USER_CREATE: {
+                const role = typeof input.role === 'string' && input.role ? input.role : 'viewer';
+                const user = await requireIam().createUser({
+                    username: input.username, password: input.password, displayName: input.displayName,
+                    bindings: [{ role, scopeKind: 'global' }],
+                });
+                audit('iam.users.create', `user:${user.id}`);
+                return { user };
+            }
+            case LOCAL_GATEWAY_RPC.CONSOLE_USER_PASSWD: {
+                const iam = requireIam();
+                const user = await requireUser(iam, input.username);
+                await iam.resetPassword(user.id, input.password);
+                audit('iam.users.resetPassword', `user:${user.id}`);
+                return { user };
+            }
+            case LOCAL_GATEWAY_RPC.CONSOLE_USER_DISABLE: {
+                const iam = requireIam();
+                const user = await requireUser(iam, input.username);
+                const updated = await iam.setDisabled(user.id, input.disabled !== false);
+                audit(updated.disabled ? 'iam.users.disable' : 'iam.users.enable', `user:${user.id}`);
+                return { user: updated };
+            }
+            default: throw new IamError('invalid_input', `Unknown RPC type: ${type}`);
+        }
+    }
+    return Object.freeze({
+        owns: (type) => TYPES.has(type),
+        async handle(type, data) {
+            const input = data && typeof data === 'object' && !Array.isArray(data) ? data : {};
+            try {
+                return { ok: true, data: await run(type, input) };
+            }
+            catch (error) {
+                if (error instanceof IamError)
+                    return { ok: false, error: { code: error.code, message: error.message, status: error.status } };
+                if (isDatabaseBusyError(error)) {
+                    return { ok: false, error: { code: 'database_busy', message: `数据库正忙，请 ${DATABASE_BUSY_RETRY_AFTER_SECONDS} 秒后重试`, status: 503 } };
+                }
+                return { ok: false, error: { code: 'internal', message: error instanceof Error ? error.message : String(error), status: 500 } };
+            }
+        },
+    });
+}

package/lib/iam/rate-limit.d.ts

@@ -0,0 +1,15 @@
+/** Login throttling: 5 failures / 15 minutes per IP and per username, then exponential lockout. */
+export interface LoginRateLimitOptions {
+    readonly maxFailures?: number;
+    readonly windowMs?: number;
+    readonly maxLockMs?: number;
+    readonly now?: () => number;
+}
+export declare class LoginRateLimiter {
+    #private;
+    constructor(options?: LoginRateLimitOptions);
+    /** Milliseconds until any of `keys` may try again; 0 when allowed. */
+    retryAfter(keys: readonly string[]): number;
+    fail(keys: readonly string[]): void;
+    succeed(keys: readonly string[]): void;
+}

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[];