@haneinfo/identity-core

中文文档
4.7.1发布于 2026/11/17UNLICENSEDTypeScriptCommonJS近 30 天下载 5309

Provider-neutral user and service-account identity for Haneinfo apps: the User model, Users CRUD and the haneinfo.identity-store capability.

原始使用文档
文档目录5 节
  1. Reader picker identity search
  2. Batched active display names
  3. Authenticated name lookup
  4. Email matching preflight
  5. Default roles and CSV roles column

Identity core

Provider-neutral identity storage and user management for Haneinfo plugins.

IdentityStoreService implements optional IdentityStorePort.searchActiveByName. Active/name/excluded-user/keyset predicates and the 20-row cap run in PostgreSQL; only id and nullable name are selected. A caller transaction may be supplied. The method grants no instance access and exposes no new public user-search endpoint: collaboration performs the authorization. Upgrade identity-core together with collaboration for mention discovery.

Batched active display names

Identity-store optionally implements findActiveNamesByIds(ids, transaction?), returning only { id, name } for active matching users in one projected query, deduplicating ids and skipping empty input. Unknown, deleted and inactive users are omitted. Consumers use null for omitted names and for older providers without this optional method; they must authorize their objects before lookup and must not fall back to per-row findById calls. This adds no general-user HTTP endpoint or schema field.

Authenticated name lookup

GET /identity/users/lookup?q= uses InteractiveAuthGuard without AdminGuard. It trims q and requires 2–200 characters, otherwise INVALID_INPUT/400. It returns an array of at most twenty active users, each exactly { id, name }, with nullable name, ordered by name then id. Percent, underscore and backslash are literal search characters. There is no email/role disclosure, cursor or bulk export, and no new MCP tool. The existing identity-store keyset search keeps its id ordering; only this controller requests the concrete implementation's optional name sorting.

Email matching preflight

Before enabling this version, run psql -X -v ON_ERROR_STOP=1 -f node_modules/@haneinfo/identity-core/scripts/check-email-duplicates.sql against the target database with a read-only account. Configure the connection with standard PostgreSQL client settings. The SELECT prints existing case-insensitive duplicate emails to standard output; it does not write files, merge accounts, or modify data. Resolve duplicates manually before enabling authentication. Protect the output as personal data and do not redirect it to logs or files.

New users are stored with lowercase email. Lookup ignores case and rejects ambiguous matches, including during import. Existing rows are not rewritten. The existing case-sensitive unique constraint cannot prevent an external writer from concurrently inserting mixed-case duplicates; all writers must follow this policy and operators should repeat the preflight as needed.

Default roles and CSV roles column

Behavior change: Creating a user without explicit roleIds (manual UsersService.create, OIDC JIT via IdentityStoreService.create, and CSV import with an empty roles cell) no longer assigns USER (SYSTEM_USER_ROLE) by default. Apps that want default roles must declare defaultRoleNames in @haneinfo/rbac (configRef: "rbac"); to keep the previous behavior, set defaultRoleNames: ["USER"].

CSV import (UsersImportService) supports an optional roles column (aliases: role, roles, 角色), with multiple role machine names separated by ;. When creating a new user:

  • Non-empty values are validated via RbacPolicyPort.resolveImportRoleIds (failing closed with ROLES_UNSUPPORTED if missing, or ROLE_NOT_ASSIGNABLE if any role is ADMIN or unknown).
  • Empty cells fall back to the App's declared defaultRoleIds().
  • For existing users (bind or skip), roles are never modified and non-empty cells are flagged with ROLES_IGNORED_FOR_EXISTING_USER.

版本与发布记录

@haneinfo/identity-core 共发布 38 个版本,首次发布于 2026/10/02;过去 12 个月发布了 38 个版本。

版本发布日期距今
4.7.1latest2026/11/17今天
4.7.02026/11/161 天前
4.6.192026/11/0412 天前
4.6.182026/11/0214 天前
4.6.172026/11/0115 天前
4.6.162026/10/3017 天前

关于 @haneinfo/identity-core 的常见问题

@haneinfo/identity-core 是什么?

Provider-neutral user and service-account identity for Haneinfo apps: the User model, Users CRUD and the haneinfo.identity-store capability.

如何安装 @haneinfo/identity-core?

在项目目录运行 npm install @haneinfo/identity-core,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:zod(^4.4.0)、@nestjs/core(^11.0.0 || ^12.0.0)、@nestjs/common(^11.0.0 || ^12.0.0)、@prisma/client(^6.19.0 || ^7.10.1)、@haneinfo/common(^0.6.1 || ^0.7.0)、@haneinfo/plugin-host-nest(^2.0.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@haneinfo/identity-core 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@haneinfo/identity-core 支持 ESM 还是 CommonJS?

以 CommonJS 形式发布,可以直接 require();在 ES Module 项目中也可以用 import 引入(Node.js 会把 module.exports 作为默认导出)。

@haneinfo/identity-core 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.0.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@haneinfo/identity-core 可以商用吗?

@haneinfo/identity-core 使用 UNLICENSED 许可。作者声明为 UNLICENSED,即不授予公开使用许可(与公共领域的 Unlicense 不同)。使用前需获得作者授权。以上为概括,不构成法律意见,请以许可原文为准。

@haneinfo/identity-core 的下载量有多少?

根据 npm 官方下载统计,@haneinfo/identity-core 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,309 次,日均约 177 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@haneinfo/identity-core 还在维护吗?

最新版本 4.7.1 发布于 2026/11/17(今天);至今共发布 38 个版本,其中过去 12 个月发布了 38 个;首次发布于 2026/10/02。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。