# `naisi_hash_data`

使用业务盐和当前构建的内部数据哈希材料生成确定性摘要。

本函数不会读取许可文件中的项目私有盐、客户 ID、Build ID 或设备指纹。
相同的规范化数据、盐、$scramble_input、内部数据哈希材料及算法版本会得到
相同结果；不同服务器只有部署了相同构建材料时，才可重新计算数据库中的旧值。

注意：$scramble_input 只启用确定性的输入重排，不会加入随机数。该摘要不可逆，
但不应当作数字签名、访问令牌或无碰撞唯一 ID。升级时若重新生成内部数据哈希材料，
已持久化的摘要将无法按原值重算；应安全保留并迁移对应版本的私有构建材料。

## 函数签名

```php
function naisi_hash_data(string $data, string $salt, bool $scramble_input = true): ?string
```

## 调用前提

应用入口先调用 [naisi_is_ext_license_valid](/web/developers/naisilib/naisi-is-ext-license-valid) 并确认返回 `true`。认证 Agent 发布的许可与 heartbeat 快照，并建立或复用本请求的 BASIC 证明；不会读取许可文件或检查当前 Host。

授权类别：`LICENSE`；执行模式：`BASIC`。许可不代替登录、租户或权限上下文；身份与数据要求见本页参数及用途说明。

## 参数

### `$data`

- 类型：`string`
- 必填：是
- 默认值：无
- 方向：输入参数。

原始字节字符串。计算前会移除首尾的空格、制表符、换行符、回车符、垂直制表符和 NUL；空字符串或只含这些首尾字符的字符串会作为规范化后的空数据正常计算摘要，不属于失败。

### `$salt`

- 类型：`string`
- 必填：是
- 默认值：无
- 方向：输入参数。

调用方提供的业务盐字节字符串；空盐为兼容输入并会正常计算，但会削弱域隔离，生产调用应使用稳定的非空盐。需要跨设备重算时必须逐字节一致；盐不会自动从许可文件取得。

### `$scramble_input`

- 类型：`bool`
- 必填：否
- 默认值：`true`
- 方向：输入参数。

是否在最终 SHA-256 摘要前执行项目定义的确定性重排，默认 true。true 与 false 的输出不兼容，持久化结果后不得随意切换。

## 返回值

类型：`string|null`

成功时返回固定 44 字符的项目 URL 安全 Base64 摘要（使用 -、_、$）；未授权、材料不可用或计算失败时返回 null。

## 调用示例

当前请求须满足上方调用前提；请检查实际返回值和引用输出，随机结果及数据包内容以运行环境为准。

```php
$data = 'Hello Naisi';
$salt = 'test_salt_2026';
$scramble_input = true;

$result = naisi_hash_data($data, $salt, $scramble_input);
var_dump($result);
```

## 版本信息

- 自版本：`1.0.6`
- 实现模块：`crypto`
- 授权类别：`LICENSE` / `BASIC`
- 失败回退：`null`
- 文档同步：`2026-10-18`