# @estiva-app/identity 中文文档

规范地址：https://npmcn.com/package/%40estiva-app/identity/

版本：0\.3\.0
npm 元数据更新时间：2026-10-17T10:35:07.062Z
中文译文更新时间：2026-11-14T03:16:11.866Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40estiva-app/identity
原文对照：https://npmcn.com/package/%40estiva-app/identity/?lang=original
项目主页：https://github.com/estiva-app/estiva-foundation#readme
源码仓库：https://github.com/estiva-app/estiva-foundation

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

- 包体积（解压后）：216 kB，24 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=20
- 运行依赖：0 个
- peer 依赖：@estiva-app/protocol \>=0\.14\.0
- 首次发布：2026-08-28T08:05:56.507Z
- 最新版本发布：2026-10-17T10:35:06.699Z
- 近 30 天下载量：2418（2026-10-14 至 2026-11-12，npm 官方下载统计）
- 已发布版本数：9（近 12 个月 9 个）

## 中文简介

Estiva ID 签入:授权代码+PKCE,令牌存储,无声续订,签出,通过POST / sign签名,以及认证壳状态机器. 对任何应用程序的数据层一无所知.

## 安装

```sh
npm install @estiva-app/identity
```

也可以使用：`pnpm add @estiva-app/identity`、`yarn add @estiva-app/identity`、`bun add @estiva-app/identity`

## README

# @stiva-app/身份

用 Estiva ID 签名: 授权代码 + PKCE, 令牌存储, 无声 更新,签出, 和认证壳状态机器.

```bash
npm install @estiva-app/identity
```

外面什么都没有 `@estiva-app` 基础,没有数据层,也没有UI. CI执行所有三个.

## 此软件包存在的接合

**在:** 一切决定 _是否有人被签入_ 财务报告和审定财务报表 _说什么 当他们不是的时候_。 。 。 .

**不入:任何应用程序的数据层.** `peek-app/src/auth/useEstivaIdAuth.ts` 这是 适配器 `ConvexProviderWithAuth` 阅读,它留在皮克。 如果它在这里, 船和每个未来的应用 都会继承康维克斯的依赖性 这正是SHA-4的失败 顺序存在来避免.

**船根本不需要适配器 是线上的测试.** 手拿着 直接指向它的中继客户端.

**不入:外壳的渲染.** 每个应用都想要一个全页的表面. 共享是状态机器和原因词汇. 还有这个 软件包清除 `@estiva-app/ui` — ADR 0002 §2 名称身份取决于 `ui` 作为折叠的触发器 `ui` 回到地基里,那应该是 一个人做一个决定 而不是一个登录屏幕 偶然.

## 消费者之间的差别都是个参数

包是工厂,不是免费功能的模块,因为Peek和Ship 每一个问题都存在分歧,而硬编码者 包出出 Peek 形状, 这是整个风险 SHA-4 名称.

| 已注射 | 头皮 | 船舶 |
| --- | --- | --- |
| `clientId` | `estiva-peek` | `estiva-ship` |
| `redirectUri` | a 固定数额 `/auth/callback` | 其当前路径名 - 船舶路线 `location.hash` |
| `keyPrefix` | `peek.estivaId` | `ship.estiva-id` |
| `navigate` | 一个真正不可检验的行为,所以它是可观察的 |  |
| `setTimer` 编号 : `clearTimer` | 计时器 `scheduleRenewal` 运行,注入的原因相同 |  |

**每一个应用程序(PEE-3)的会话都相同.** `storage` 默认 改为 `localStorage` ——每个分页共享一个会话,在分页关闭后幸存下来——和 `pendingStore` 改为 `sessionStorage`,因为一个登录开始和结束在一个分页中. 皮克在PEE -3之前 一直保持每节课,每张新帐单都付了0.5分 `/authorize` 弹出它。 两者均可注射( 测试, 脚本); 呼叫器 只通过 `storage` 和以前一样,为两个都买.

**共享会话需要跨塔布锁更新.** 每个标签的计时器起火 estiva ID 当刷新符号时撤销整个链条 分为两次. `lock` 默认为 Web 锁定 API; 等待的标签 它需要另一个标记 刚刚更新 而不是花旧的.

`pendingStore` 存在是因为第二位消费者找到了软件包 假设一个商店——它是取自皮克,它使用一个. 这就是"a" 库从一个应用中抽出 形状像该应用"故障 SHA-4名称, sHA-4规定, 值得作为证据知道 第二消费者规则是维持而不是举行仪式.

一个应用程序一次性即时发送并再出口它自己的名字,所以调用站点不会churn:

```ts
const client = createEstivaId({
  base: ESTIVA_ID_ORIGIN,
  clientId: 'estiva-peek',
  redirectUri: () => `${window.location.origin}/auth/callback`,
  keyPrefix: 'peek.estivaId',
  navigate: (url) => window.location.assign(url),
})
export const { validToken, beginSignIn, completeSignIn, beginSignOut } = client
```

## 签名在问,必须检查答案

```ts
// Peek: one round trip, a token read fresh each time
const event = await signViaEstivaId(unsigned, { base, token, expectedPubkey: myPubkey })

// Ship: a protocol Signer, built once. Pass a READER, not a string, if anything
// else can replace the token — `scheduleRenewal` does.
const signer = estivaIdSigner({
  base,
  pubkey,
  token: () => client.validToken()?.accessToken,
  renew: client.refreshAccessToken,
})
```

应用软件以个人身份发布,从未看到他们的秘密. `@estiva-app/protocol` 拥有事件如何获得签名; 此软件包拥有 _谁被允许问_。 。 。 .

**`/sign` 无论交到什么 标语是标志对象.** 这么说 属于他人的标志不是错误,而是 **HTTP 200 带有效 由该另一人撰写的事件**。 。 。 . `expectedPubkey` 这是支票,不是 请求,以及 `estivaIdSigner` 从酒吧里无条件供应 搭载。 在SHA -4之前有三份 只有一个 查过了,不是船的,谁都写进 船通过.

A 类 `401` 掷出 `SignerTokenExpired`; 任何其他拒绝 `SignRefused` 携带 HTTP `status`因为消费者对此进行分类 信息不是 a API -- -- `403` 表示管理员必须恢复身份,而 `422` 政策拒绝完全意味着别的东西。 还有 `estivaIdSigner` 续约 **一次** 并重试。 从来没有两次: 一秒 `401` 之后 成功续约是服务无法接受的象征 一个被拒绝的签名是如何变成热回路的。 任何不是过期的东西 所以拒绝错误的作者从来不会花一个新鲜的符号.

## 延期是预定的,不是被动的

```ts
const schedule = client.scheduleRenewal({
  onRenewed: (token) => setSignedIn(true),
  onEnded: () => setSignedIn(false),   // drop to the shell
})
// later, on sign-out or unmount
schedule.cancel()
```

`tokenFrom` 故意提前储存30秒过期,以及 `scheduleRenewal` 事情是这样的 换句话说,是某人的 _下一个动作_ 实值 发现会话的结局是失败的发布,空白列表,充其量是a 重试他们能感觉到。 早点续约意味着他们什么也没有注意到, 也就是整个 (原始内容存档于2017-09-10). point of PEEK-108.

**两次续会不得一一出.** 刷新符号是单用 estiva ID读取了回放,作为盗窃的证据,撤销了整个链条——所以 重复更新不会浪费往返,它会给某人签出 一切众生. `refreshAccessToken` 将同时调用者合并为一个请求, 不仅有排程员 船也签了NIP-98 认证事件和内容事件为两个独立的 `POST /sign` 和一种迹象 他们之间的答案 `401` 对两者.

**`setTimeout` 在背景标签中节奏.** Chrome和Safari夹子a 隐藏标签的计时器大约每分钟一次, 并且可能在之后完全冻结 隐藏了5分钟,因此背景标签会错过其更新窗口. 自兹 0.3.0 当标签再次显示或网络出现时, 时间表也会续订 背数( r)`onWake`,默认为 `visibilitychange` 财务报告和审定财务报表 `online`;读取 本地声明的全局, 因此所公布的类型仍然名无所取, ADR 0002 (第4a条)。 更新后得不到答复,而不是结束登录; 只有EstivaID的拒绝电话 `onEnded`。 。 。 .

## 这个软件包的预测是伪造的

开始之前,票上的期望是那个身份 **无法** 遵循 ARD0002 §4a 一样干净 `@estiva-app/protocol` 做了,这是 浏览器形状贯穿全过程,需要 `lib: dom`,并且发展成果评估需要 修正为说.

这是错误的,值得指出的是,为什么不悄悄地提及:

-   `crypto`, (中文(简体) ), `btoa`, (中文(简体) ), `TextEncoder`, (中文(简体) ), `URL`, (中文(简体) ), `URLSearchParams`, (中文(简体) ), `fetch` 财务报告和审定财务报表 `console` 在使用它们的模块内声明,并在功能机构内读取.
-   DOM的游戏 `Storage` 成为本地人 `KeyValueStore` 接口. `sessionStorage`, (中文(简体) ), `localStorage` 和一个普通物体 都满足它的结构 和出版 声明名称没有环境类型.
-   导航是一个 **所需经费** `navigate` 调用而不是调用 `location` 到达.

因此,软件包构建 `types: []` 没有 `lib: dom`,与 `protocol` ,而一个测试可以在每个浏览器全局被删除的情况下导入它。 CI声称两者兼有.

让它成为现实的不是聪明 这是 **浏览器 API 是一个 app必须注入也是一个浏览器 API 一个测试可以观察** ——接缝 第4a条力量 和缝合一个测试想要是相同的接合。 假设之前值得记住 下一个浏览器形状的软件包需要免责.

`@estiva-app/ui` 仍然是反比喻:它飞船 `.d.ts` 文件命名 `HTMLButtonElement`并逃脱了它 仅仅因为它的消费者都是 浏览器应用程序.

## 释放

```bash
git tag identity@0.1.1 && git push origin identity@0.1.1
```

这个 **第一个** 因为一个值得信赖的出版商 配置在已经存在的软件包上 – ADR 0002 §4c, §7 。 每一次发布 之后是标记.

## 常见问题

### @estiva-app/identity 是什么？

Estiva ID 签入:授权代码\+PKCE,令牌存储,无声续订,签出,通过POST / sign签名,以及认证壳状态机器\. 对任何应用程序的数据层一无所知\.

### 如何安装 @estiva-app/identity？

在项目目录运行 npm install @estiva-app/identity，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@estiva-app/protocol（\>=0\.14\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @estiva-app/identity 支持 TypeScript 吗？

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

### @estiva-app/identity 支持 ESM 还是 CommonJS？

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

### @estiva-app/identity 需要什么版本的 Node\.js？

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

### @estiva-app/identity 可以商用吗？

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

### @estiva-app/identity 的下载量有多少？

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

### @estiva-app/identity 还在维护吗？

最新版本 0\.3\.0 发布于 2026/10/17（27 天前）；至今共发布 9 个版本，其中过去 12 个月发布了 9 个；首次发布于 2026/08/28。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。