@happyvertical/smrt-profiles

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 2.8万

与SMRT框架的关系、元数据和对等协会的概况管理系统

中文使用文档
文档目录13 节
  1. 安装
  2. 使用量
  3. 拥有资产
  4. 网络链接
  5. API 密码
  6. 模型
  7. Auth 模型
  8. 收款
  9. Auth 函数
  10. 鼻孔密码
  11. 密钥类型
  12. 依赖关系
  13. 活动日志配方

@ 快乐的垂直/ smrt- profile

中央身份系统,包含多自动(Nostr/OIDC/API密钥/魔法链接),关系,被控制的元数据,以及审计记录.

安装

pnpm add @happyvertical/smrt-profiles @happyvertical/sql

使用量

import {
  backfillProfileEmailKeys,
  createProfileFromOidc,
} from '@happyvertical/smrt-profiles';
import { getDatabase } from '@happyvertical/sql';

// Connect after applying schema migrations.
const persistence = { type: 'sqlite' as const, url: 'file:profiles.db' };
// Mark migrated Profile email keys ready before enabling OIDC provisioning.
const db = await getDatabase(persistence);
await backfillProfileEmailKeys(db);

// Provision a new OIDC Profile or reuse its exact issuer/subject link.
const { profile, oidcIdentity, created } = await createProfileFromOidc(
  {
    iss: 'https://accounts.google.com',
    sub: 'abc123',
    email: '[email protected]',
    email_verified: true,
    name: 'Olivia Smith',
  },
  'google',
  { db },
);

拥有资产

import { AssetCollection } from '@happyvertical/smrt-assets';
import { ProfileCollection } from '@happyvertical/smrt-profiles';

const profiles = await ProfileCollection.create({ db });
const assets = await AssetCollection.create({ db });

const headshot = await assets.create({
  name: 'alice-headshot.jpg',
  sourceUri: 'file:///tmp/alice-headshot.jpg',
  mimeType: 'image/jpeg',
});

await profile.addAsset(headshot, 'avatar');
await profiles.addAsset(profile.id!, headshot, 'gallery', 1);

const avatarAssets = await profile.getAssets('avatar');
const galleryAssets = await profiles.getAssets(profile.id!, 'gallery');

概况的社会账户和网站,按显示顺序排列. 几个链接 平台被允许;同一地址被保留一次。 新链接取 档案的房客, 他们被删除 与档案.

import { ProfileLinkCollection } from '@happyvertical/smrt-profiles';

await profile.setLinks([
  { platform: 'facebook', url: 'https://facebook.com/mayor' },
  { platform: 'website', url: 'https://mayor.example/' },
  { platform: 'other', url: 'https://blog.example/', label: 'Blog' },
]); // replaces the whole list in one transaction

const links = await profile.getLinks(); // ordered by sortOrder

const profileLinks = await ProfileLinkCollection.create({ db });
await profileLinks.reorder(profile.id!, [links[2].id!, links[0].id!, links[1].id!]);

平台: facebook, (中文(简体) ), instagram, (中文(简体) ), x, (中文(简体) ), linkedin, (中文(简体) ), youtube, (中文(简体) ), tiktok, (中文(简体) ), website, (中文(简体) ), other (单位:千美元)PROFILE_LINK_PLATFORMS) (中文(简体) ). 地址必须是 http:// 或者说 https:// (单位:千美元)normalizeProfileLinkUrl) (中文(简体) ). 连结的子弹是它的ID,从来不是它的 地址或标签.

Profile.isPublic (默认) false)是公共图案旗:简介为: 公开公开(民选官员、公共机构)。 它只记录事实; 申请决定它显示什么.

API 密码

模型

导出说明
Profile核心身份(瓶/组织/个人的科技创新基础)
Bot自动代理的STI子类
Organization公司/集团的科技和创新子类
Person个人科学、技术和创新子类
ProfileType配置分类查询表
ProfileMetadata每张元数据值
ProfileMetafield具有校验计划的控制词汇
ProfileRelationship两个剖面图之间的方向联系
ProfileRelationshipType与对等旗帜的关系分类
ProfileRelationshipTerm有时限的关系期
ProfileAsset专用自有资产加入存储于 profile_assets 与 relationship 财务报告和审定财务报表 sortOrder
ProfileLink在配置文件上排序的网络链接( E)profile_links: 平台、 url、 可选标签、 排序命令; 带有配置的级联)

Auth 模型

导出说明
OidcIdentityOIDC 提供者身份( 发行者+主题)
NostrIdentity带有 AES-256-GCM 加密的鼻孔键盘
ApiKeySHA-256 散列 API 密钥,范围及过期
MagicLinkToken一次性无密码验证符
AuditLog有源头追踪的行动/资源审计线索

收款

导出说明
ProfileCollectionCRUD 配置文件查询
ProfileAssetCollection直接进入 profile_assets 行外加资产助手包装
ProfileTypeCollection概况类型管理,包括房客安全 getAvailableById(id, tenantId) 租户或全球类型
ProfileLinkCollectionlistForProfile, (中文(简体) ), replaceForProfile (一次交易中命令替换), reorder
ProfileMetadataCollection元数据值操作
ProfileMetafieldCollection梅塔菲尔德词汇管理
ProfileRelationshipCollection关系查询
ProfileRelationshipTypeCollection关系类型管理
ProfileRelationshipTermCollection任期管理
ApiKeyCollectionAPI 密钥查询和管理
AuditLogCollection审计日志查询
MagicLinkTokenCollection魔法链接符号操作
NostrIdentityCollection鼻孔身份查询(包括NIP-05)
OidcIdentityCollectionOIDC 身份查询

ProfileCollection.findUniqueGlobalPersonByEmail(email) 被支持为 验证身份查询。 它横跨租户范围阅读并返回一个简介 只有当对大小写不敏感的邮件完全匹配时,该行才是一个 全球 Person; 租户范围、非租户和重复火柴投掷 CanonicalPersonProfileError。匹配用户只读,已索引 Profile.emailKey,随导出类型脚本 normalizeIdentityEmail() 帮助器,所以 Unicode 外壳和白空执行 每个数据库适配器都一样。 使用 requireCanonicalGlobalPerson(profileId, email?) 以验证 针对同一变量的应用程序选择的配置文件。 何时 email 实值 删除, 帮助者使用配置文件当前存储的特性验证 电子邮件. reserveCanonicalIdentityEmail(profileId, email) 额外索赔 私人地址 oidc_profile_email_reservations 页:1 奥米 email 以同步 从配置文件当前存储的电子邮件中保留; 更改地址移动 保留,并消除保留。 遗产简单 Person 科学、技术和创新歧视者仍然有效,由核心正常处理 升级路径.

OidcIdentity.identityKey 存储一个无效的、独特的发行者/主题的自然密钥 用于交易安全第一记录赛。 模型来源于发行商和 每个保存上的主题,所以调用者不能使其脱同步 。 新链接居中 它和遗留的一行回填 当再利用它。 发行商和主体不透明, 对大小写敏感的 OIDC 标识符: 周围的白空间被保存并且是 键的一部分; 修剪只用于拒绝全白空间要求。 这个 生成 REST, MCP, 和 CLI 表面只读, 因为身份突变 是一个认证权限更改; 信任的呼叫者通过 交易提供 API。 遗产 OidcIdentity.findOrCreate() 方法被贬值:它以交易方式重复使用 用于兼容性的精确安全发布器/主题链接,但拒绝创建 新建认证链接 。 使用 createProfileFromOidc() 或用户软件包 拥有者意识为创建提供API. 堕落者 OidcIdentityCollection.linkToProfile() 财务报告和审定财务报表 Profile.linkOidcIdentity() 帮助者指派到同样的完全重复使用路径, 并且不能植入或重置 链接. 现有设施必须停止或升级 配置文件编写、运行 smrt db:status, (中文(简体) ), smrt db:migrate,然后则 smrt db:status 部署前 此版本用于添加身份密钥和私人电子邮件保留表 。 礛 运行 backfillProfileEmailKeys(db) 一次从一个单一部署流程中 能够提供经核实的电子邮件。 交易安全回填是 同位素; canonical 电子邮件搜索和预订失败 email_key_backfill_required 标准时 _smrt_backfills 准备 标记缺失 。 精确的发行者/主体再利用不依赖于电子邮件密钥 准备,因为它不执行基于电子邮件的链接. 身份边界帮手使用备战后卫并索引了钥匙. 这个 普通用途 ProfileCollection.findByEmail() 保留其相容的遗产 寻找行为, 不适合身份链接 。 只有明确的 部署时间回填扫描配置表和记录准备状态; 守护 运行时身份查询使用索引键并验证返回的候选人. createProfileFromOidc() 需要一个交易能力数据库。 通过 根数据库,必须曝光 beginTransaction和s -m 交易; 通过一个 保存点。 执行 Cononical 电子邮件搜索或预定所需的路径 _smrt_backfills 以第一个存在。 提供从未尝试的跟踪器 DDL 对于这些路径,如果没有表格,则通过 root 数据库 这样 s- m-r- t 就可以在交易之外初始化它 。 准确 发行者/ 主体重用跳过电子邮件键准备标记搜索, 但 root 协调仍在初始化共享跟踪表。 呼叫者拥有的密钥 重复使用不参考跟踪器,因此不需要该表. 只露出一个手柄 transaction() 模棱两可,没有关闭。 对于 没有嵌入保存点支持的适配器,包括 DuckDB, pass 根数据库,而不是在外部交易中调用帮助者. 在无法找到安全路径时, 无法在持久写入之前提供 . 键入 OIDC 提供决定矩阵 是"逐个包装"的行为契约 它记录了精确的再利用, 新的身份和解决者结果、准备、重试、适配者支持、公开 错误和允许的行创建; 配置和用户套件执行 直接应用行。 特别是,仅配置文件的精确再利用保留了 已建立后继链接,因为它没有创建用户/会话认证状态, 时 UserCollection.getOrCreateFromOidc() 保持所有者意识并关闭故障. 使用用户API进行已核实的电子邮件再利用和应用调节. 内容 authorizeProfileOwner 选项是新选项中唯一支持的例外 发行人/主体针对预设的拥有者:用户包 解析验证 Cononical 配置文件, 唯一批准的所有者, 匹配用户 电子邮件,以及不可重现的身份。 没有明确适用 授权, 拥有的配置文件仍然返回 profile_owned。 。 。 .

Profile 财务报告和审定财务报表 ProfileCollection 都暴露出来 getAssets(), (中文(简体) ), addAsset(),以及 removeAsset() 辅助人员 profile_assets。典型的关系是: avatar, (中文(简体) ), gallery,以及 attachment。 。 。 .

Auth 函数

导出说明
resolveIdentity从任何认证方法解析配置
createProfileFromOidc创建 Profile + OIDC 身份或重用精确的发件人/ 主题链接; 已存在的邮件匹配失败关闭
normalizeIdentityEmail身份密钥使用的适应器独立 Unicode/ whitespace 电子邮件卡通器
backfillProfileEmailKeys用于迁移配置文件的常态化密钥
PROFILE_EMAIL_KEY_BACKFILL_NAME由 Profile 电子邮件键回填记录的持久准备标记名称
createProfileFromNostr在一个呼叫中创建配置文件 + 节点身份
createAuthEvent创建节点认证事件
verifyAuthEvent验证 Nostr 自动事件签名
createMagicLinkService魔法链接认证服务工厂
createNip05HandlerNIP-05地址处理器工厂

鼻孔密码

导出说明
generateNostrKeypair生成新的 Nostr 密钥派
encryptPrivkey 编号 : decryptPrivkeyAES-256-GCM (法语) 密钥加密
deriveEncryptionKey来自主密钥的衍生加密密钥
getPublicKey从小金刚取出的小金刚
signEvent 编号 : computeEventId节点事件签名
verifyNostrSignature校验节点签名
pubkeyToNpub 编号 : npubToPubkeyBech32 公用钥匙转换
privkeyToNsec 编号 : nsecToPrivkeyBech32 组合键转换
isValidPubkey 编号 : isValidPrivkey密钥验证
parseNip05Identifier 编号 : isValidNip05IdentifierNIP-05 解析

密钥类型

ProfileOptions, (中文(简体) ), ProfileTypeOptions, (中文(简体) ), ProfileLinkOptions, (中文(简体) ), ProfileLinkPlatform, (中文(简体) ), ProfileLinkInput, (中文(简体) ), ProfileMetadataOptions, (中文(简体) ), ProfileMetafieldOptions, (中文(简体) ), ProfileRelationshipOptions, (中文(简体) ), ProfileRelationshipTypeOptions, (中文(简体) ), ProfileRelationshipTermOptions, (中文(简体) ), OidcIdentityOptions, (中文(简体) ), CanonicalPersonProfileErrorCode, (中文(简体) ), NostrIdentityOptions, (中文(简体) ), ApiKeyOptions, (中文(简体) ), GenerateKeyResult, (中文(简体) ), MagicLinkTokenOptions, (中文(简体) ), GenerateTokenResult, (中文(简体) ), AuditLogOptions, (中文(简体) ), AuditSource, (中文(简体) ), AuthContext, (中文(简体) ), ResolveIdentityResult, (中文(简体) ), InitiateResult, (中文(简体) ), VerifyResult, (中文(简体) ), MagicLinkConfig, (中文(简体) ), MagicLinkService, (中文(简体) ), Nip05HandlerConfig, (中文(简体) ), Nip05HandlerResult, (中文(简体) ), Nip05Request, (中文(简体) ), Nip05Response, (中文(简体) ), NostrEvent, (中文(简体) ), NostrKeypair, (中文(简体) ), EncryptedKey, (中文(简体) ), ValidationSchema, (中文(简体) ), ValidatorFunction, (中文(简体) ), ReciprocalHandler

依赖关系

  • @happyvertical/smrt-core - ORM基础课程
  • @happyvertical/ai -- AI 客户端 (SDK)
  • @happyvertical/sql - 数据库操作(SDK)
  • @happyvertical/files - 文件系统公用设施(SDK)
  • @happyvertical/logger - 结构化记录(SDK)
  • @happyvertical/utils -- -- 共享公用事业
  • @noble/curves -- 鼻孔密码
  • bech32 -- Bech32 节点键编码
  • 端点 : @happyvertical/smrt-tenancy

活动日志配方

AuditLogRecipe 声明 profiles.audit-log。在授权通过 readAuditTrail,将返回的记录传递给 auditActivityEntries,然后通过它的 作为 DTO entries 改为 ActivityList 从 @happyvertical/smrt-svelte 在行政壳内部. 包装器只将自己的行绑入 shell 列表, 当 替换或卸载。 查看者的授权更改时替换条目 . 演员标签和记录链接是可选的主机回调;投影从未 推断有效载荷之前/之后的准入权或暴露。 无效的日期被省略 .

活动功能卡可以独立于Message独立启用. 它的食谱 在不创建模式路由的情况下建议活动段; 授权 活性绑定仍然是唯一的UI数据源.

这个 /activity 表面决定公众 @happyvertical/smrt-svelte#ActivityList 包装在Adminshell内部. 规定 audit-log 提供者指经主机授权 readAuditTrail 接下来是 auditActivityEntries; 无法通用 审计日志路线. JSON种子提供虚构 entries 直接发送给 包装. runtime: both 反映浏览器渲染加只读服务器审计; 种子数据从未被插入审计数据库,也从未作为授权历史处理.

版本与发布记录

@happyvertical/smrt-profiles 共发布 365 个版本,首次发布于 2026/06/23;过去 12 个月发布了 365 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-profiles 的常见问题

@happyvertical/smrt-profiles 是什么?

与SMRT框架的关系、元数据和对等协会的概况管理系统

如何安装 @happyvertical/smrt-profiles?

在项目目录运行 npm install @happyvertical/smrt-profiles,或使用 pnpm add / yarn add / bun add。

@happyvertical/smrt-profiles 支持 TypeScript 吗?

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

@happyvertical/smrt-profiles 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-profiles 可以商用吗?

@happyvertical/smrt-profiles 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-profiles 的下载量有多少?

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

@happyvertical/smrt-profiles 还在维护吗?

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