@happy-technologies/audit

中文文档
0.2.0发布于 2026/07/10Apache-2.0TypeScriptESM + CJS零依赖近 30 天下载 6020

Tamper防控审计散列-链内核共享于Happy Technology产品:按键HMAC-SHA256入门散列,链检,可选 Postgres 单写帮助器. 域-不可知; 产品拥有其审计 log 计划并迁移; app ow

中文使用文档
文档目录7 节
  1. 安装
  2. 使用量
  3. 根导出: 纯内核
  4. ./pg 子路径: 可选 Postgres 写入助手
  5. 主要管理(消费者责任)
  6. Canonical外地订单合同
  7. 非目标

@happy-technology/ 审计

Tamper-防审计散列内核 产品。 每个审计条目为HMAC-SHA256-hashed,用一个应用设备键入 与上一个条目的散列 同一房客,形成 a 租户散列链:任何内容编辑、插入、删除或重排间隔 链被检测。 因为大麻是按键的 派对只能 写入数据库(无应用程序秘密)无法伪造一个重新验证的链条: 这是篡改 -证明不仅仅是不言自明的.

0.2.0是一个从0.1.x.的突破变化. 无钥匙的平地SHA -256 computeEntryHash编号 :verifyAuditChain 顶级导出被删除。 每个 消费者必须打电话 createAuditChain(secret) 获取密钥内核。 那边 没有将数据迁移路径烤入此软件包: 因为 HMAC 取代 根据0.1.x计算的链条不会在0.2.0下核实. (本变更时不存在生产审计数据

安装

{
  "dependencies": {
    "@happy-technologies/audit": "^0.2.0"
  }
}

使用量

根导出: 纯内核

createAuditChain, (中文(简体) ), stableStringify,类型有 没有 依赖性 在 Postgres 或任何数据库驱动程序上,任何类型脚本运行时间都可以使用.

import { createAuditChain, type ChainRow } from "@happy-technologies/audit";

// secret comes from the app's own env/KMS -- see "Key management" below.
const chain = createAuditChain(process.env.AUDIT_HMAC_SECRET!);

const entryHash = chain.computeEntryHash(
  {
    id: "entry-1",
    action: "document.created",
    actorId: "user-1",
    tenantId: "tenant-1",
    resourceType: "document",
    resourceId: "doc-1",
    metadata: { source: "upload" },
    ipAddress: "127.0.0.1",
    userAgent: "Mozilla/5.0",
  },
  null, // prevHash, or the previous row's entryHash
);

const rows: ChainRow[] = []; // loaded from storage, ordered (timestamp ASC, id ASC)
const result = chain.verifyAuditChain(rows);
if (!result.ok) {
  console.error(`chain broken at ${result.brokenAt} (${result.reason})`);
}

createAuditChain 返回 a ChainKernel 绑在一个秘密上:

interface ChainKernel {
  computeEntryHash(fields: AuditChainFields, prevHash: string | null): string;
  verifyAuditChain(rows: readonly ChainRow[]): ChainVerification;
}

./pg 子路径: 可选 Postgres 写入助手

消费者使用 pg 直接, insertAuditEntry 提供强制执行的 单写路径: 它获得租户 pg_advisory_xact_lock,读取 房客的最后一个 entry_hash,通过 ChainKernel 插入 prev_hash + 键 entry_hash 在一个 交易.

import { createAuditChain } from "@happy-technologies/audit";
import { insertAuditEntry } from "@happy-technologies/audit/pg";

const chain = createAuditChain(process.env.AUDIT_HMAC_SECRET!); // create once, reuse

const client = await pool.connect();
try {
  await insertAuditEntry(
    client,
    {
      id: "entry-1",
      timestamp: new Date(),
      action: "document.created",
      actorId: "user-1",
      tenantId: "tenant-1",
      resourceType: "document",
      resourceId: "doc-1",
      metadata: { source: "upload" },
      ipAddress: "127.0.0.1",
      userAgent: "Mozilla/5.0",
    },
    chain,
  );
} finally {
  client.release();
}

pg 是一个 可选端点依赖性: 只有在从 @happy-technologies/audit/pg。根出口从不进口 pg。 。 。 .

主要管理(消费者责任)

该应用程序提供 HMAC 秘密; 此软件包永远不会有 .

  • 该秘密由CONSUMER应用程序创建和持有,来源于 环境变量或进程启动时 KMS 支持的秘密存储. 它传递给 createAuditChain(secret) 一次(通常在启动时)和 返回时 ChainKernel 重复使用过呼叫.
  • 密钥必须不被硬化 默认 或在此任何地方实施 软件包的源代码,并且不存储在审计数据库本身 (在它所保护的数据旁边储存核查密钥将使 DB- write 攻击者伪造新条目, 击败整个点 键入链).
  • createAuditChain 如果给定了空/ 未定义的密钥, 则丢出; 它永远不会 返回到未按键或默认模式.
  • 丢失密钥不会丢失数据 . 如果秘密丢失或旋转 现有链条仍然保留 完整且可读,但 verifyAuditChain 无法再确认他们的 在新的/缺漏的密钥下保持完整性。 将秘密损失视为可用性 核查事件,不是数据损失事件.
  • 旋转新密钥下的新链 需要连续可核查的旋转必须设计 移徙本身(超出本一揽子计划的范围).

Canonical外地订单合同

ChainKernel#computeEntryHash 计算 HMAC-SHA256 文摘,按键 内核的秘密, 一个犬JSON序列化的Tuple:

[prevHash ?? "", id, action, actorId, tenantId, resourceType, resourceId,
 metadata ?? {}, ipAddress ?? null, userAgent ?? null]
  • 这行 timestamp 是故意的,这是故意的 不包括 从散列。 订购 完整性来自 prevHash 链接,而不是从散列时间戳 值; 时间戳-值完整性是一个有记录的非目标.
  • metadata 序列化为 stableStringify键 递归到如此密钥顺序( 如在 JSONB 往返之后) 永不更改 散货.

这个字段订单和序列化是一个版本合同. 改变它 打破根据旧合同计算的每个链条; 添加一个字段必须是 有意的、版本的改动(例如: computeEntryHashV2没有沉默 编辑到 computeEntryHash。 。 。 .

非目标

  • 这个软件包是 没有 定义 audit_log 表格计划,一组 已审计行动,或添加性列迁移。 每个消耗的应用程序都有 它的图谋和移民(例如:快乐知识) scripts/040_audit_hash_chain.sql) (中文(简体) ).
  • 这个软件包是 没有 吸收SDK拥有的或特定用途的链条 (例如快乐生活) governance_provenance 并且不主张 全球跨租户链; 连锁是租户.
  • 这个软件包是 没有 管理HMAC秘密的生命周期(生成, 存储,旋转)——这完全是消耗性应用程序的 责任。 见上文"关键管理".
  • 这个软件包是 没有 实施外部定位(例如定期) 发布链头散列 外部,独立控制 对攻击者进行辩护 调和数据库和应用程序的机密 那个 将进一步加强防篡改的保证 除了"攻击者" "攻击者缺乏秘密,不能改变" 外部记录,但它是可选的未来硬化,没有执行 在这里.
  • 只使用节点的脚本类型 crypto.createHmac。无粗口执行 存在或正在计划; 没有多块双向同步.

版本与发布记录

@happy-technologies/audit 共发布 2 个版本,首次发布于 2026/07/10;过去 12 个月发布了 2 个版本。

版本发布日期距今
0.2.0latest2026/07/104 个月前
0.1.02026/07/104 个月前

关于 @happy-technologies/audit 的常见问题

@happy-technologies/audit 是什么?

Tamper防控审计散列-链内核共享于Happy Technology产品:按键HMAC-SHA256入门散列,链检,可选 Postgres 单写帮助器. 域-不可知; 产品拥有其审计 log 计划并迁移; app ow

如何安装 @happy-technologies/audit?

在项目目录运行 npm install @happy-technologies/audit,或使用 pnpm add / yarn add / bun add。

@happy-technologies/audit 支持 TypeScript 吗?

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

@happy-technologies/audit 支持 ESM 还是 CommonJS?

同时提供 ES Module 与 CommonJS 入口,import 和 require() 都可以使用,打包工具会自动选择合适的版本。

@happy-technologies/audit 可以商用吗?

@happy-technologies/audit 使用 Apache-2.0 许可。宽松许可:允许商业使用、修改和再分发,并附带明确的专利授权;分发时需保留许可与 NOTICE 文件,修改过的文件要注明改动。以上为概括,不构成法律意见,请以许可原文为准。

@happy-technologies/audit 的下载量有多少?

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

@happy-technologies/audit 还在维护吗?

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