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

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>;
+}