# @happy-technologies/audit 中文文档

规范地址：https://npmcn.com/package/%40happy-technologies/audit/

版本：0\.2\.0
npm 元数据更新时间：2026-07-10T11:20:59.546Z
中文译文更新时间：2026-11-17T09:17:46.155Z
软件包许可：Apache-2\.0

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40happy-technologies/audit
原文对照：https://npmcn.com/package/%40happy-technologies/audit/?lang=original
项目主页：https://github.com/Happy-Technologies-LLC/happy-audit#readme
源码仓库：https://github.com/Happy-Technologies-LLC/happy-audit

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：62.3 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- 运行依赖：0 个
- peer 依赖：pg \*
- 首次发布：2026-07-10T10:34:00.115Z
- 最新版本发布：2026-07-10T11:20:59.398Z
- 近 30 天下载量：6020（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：2（近 12 个月 2 个）

## 中文简介

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

## 安装

```sh
npm install @happy-technologies/audit
```

也可以使用：`pnpm add @happy-technologies/audit`、`yarn add @happy-technologies/audit`、`bun add @happy-technologies/audit`

## README

# @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下核实. (本变更时不存在生产审计数据

## 安装

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

## 使用量

### 根导出: 纯内核

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

```ts
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` 绑在一个秘密上:

```ts
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` 在一个 交易.

```ts
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 是什么？

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 和提交记录判断。

