# @gjermundgaraba/clankerauth-sdk 中文文档

规范地址：https://npmcn.com/package/%40gjermundgaraba/clankerauth-sdk/

版本：0\.35\.1
npm 元数据更新时间：2026-11-11T02:08:56.825Z
中文译文更新时间：2026-11-16T15:04:13.366Z
软件包许可：MIT

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

原始 npm 页面：https://www.npmjs.com/package/%40gjermundgaraba/clankerauth-sdk
原文对照：https://npmcn.com/package/%40gjermundgaraba/clankerauth-sdk/?lang=original
源码仓库：https://github.com/gjermundgaraba/clankerauth

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

- 包体积（解压后）：124 kB，25 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=26\.13\.0
- 运行依赖：3 个
- peer 依赖：effect ~4\.1\.1，@gjermundgaraba/effect-actions ^0\.31\.0
- 首次发布：2026-09-20T12:43:49.524Z
- 最新版本发布：2026-11-11T02:08:56.365Z
- 近 30 天下载量：4516（2026-10-17 至 2026-11-15，npm 官方下载统计）
- 已发布版本数：45（近 12 个月 45 个）

## 中文简介

Effect-native clankerauth access-token和离线API-key验证,可选效果动作集成

## 安装

```sh
npm install @gjermundgaraba/clankerauth-sdk
```

也可以使用：`pnpm add @gjermundgaraba/clankerauth-sdk`、`yarn add @gjermundgaraba/clankerauth-sdk`、`bun add @gjermundgaraba/clankerauth-sdk`

## README

# @gjermundgaraba/clankerauth-sdk (英语)

效应本土 [科克劳斯](https://github.com/gjermundgaraba/clankerauth) 核查。 验证 JWT 访问令牌和API 密钥,两者都离线,包括一个反向代理通过发行方的转发权限为浏览器会话获取的令牌. 可选 **效果动作** 整合提供了认证描述、OAuth发现、范围强制执行和 `Whoami` 合同,浏览器页自行从 `/session`。 。 。 .

## 安装

```sh
vp add @gjermundgaraba/clankerauth-sdk
```

效果为对等:应用程序安装Effect 4.1,从4.1.1起,SDK共享该副本.

```sh
vp add effect
```

这个 `/session` 财务报告和审定财务报表 `/effect-actions` 切入点还需要效果行动,一个可选的对等点. 安装此范围: SDK 的申报是针对它构建的, 以及以下 `skipLibCheck` 他们默默地退化到 `any` 和另一个.

```sh
vp add @gjermundgaraba/effect-actions@^0.31.0
```

效应-动作0.31需要Effect 4.1.3或后4.1补丁.

## 入境点

| 导入 | 需求效应行动 | 浏览器安全 | 它所持有的 |
| --- | --- | --- | --- |
| `…/clankerauth-sdk` | 没有 | 没有 | `Verifier` |
| `…/clankerauth-sdk/errors` | 没有 | **对** | 核查员的错误; `ProviderUnavailable` 是一个描述者 |
| `…/clankerauth-sdk/session` | 对 | **对** | `CurrentPrincipal` 联 合 国 `Caller`,则 `Whoami` 合同, `Principal`, (中文(简体) ), `signOutUrl`, (中文(简体) ), `signOutPath`, (中文(简体) ), `returnToParameter` |
| `…/clankerauth-sdk/effect-actions` | 对 | 没有 | `Resource` |
| `…/clankerauth-sdk/key-list` | 没有 | 没有 | 关键列表格式和 `keyPrefix`,用于发行者和假冒者 |
| `…/clankerauth-sdk/credentials` | 没有 | 没有 | `token` 财务报告和审定财务报表 `authorizing`,一个应用程序的无记名符号;所有者在 CLI 保存的签名(仅节点) |
| `…/clankerauth-sdk/testing` | 没有 | 没有 | `startFakeIssuer`,用于测试(仅指节点) |

软件包没有副作用,所以一个捆绑器会放下一个页面不使用的东西. 错误是 **没有** 从根部再出口: 共同合同从 `/errors`,没有关于该导入的任何东西将符号校验拉入浏览器捆绑.

## 从程序调用应用程序

一个叫作crankerauth背后的应用程序的程序,如应用程序自己的CLI,取自它的无记名标志 `token` 联 合 国 `/credentials`,或者已经 `authorizing` 随请求一起发送。 店主签一次字 `clankerauth login https://notes.internal`,从应用程序中读取资源、发行人和范围 `/.well-known/oauth-protected-resource`· ; `token` 然后刷新签入时间。 环境给出的指使,访问指使或API密钥,在设定时被返回,因此同一程序运行时无人关注. 程序将变量命名为 `token`;没有它就没有从环境读取的东西. 为了管理发行人,公约是: `CLANKERAUTH_TOKEN` 持有管理密钥、 API 密钥, 该密钥来自发行者的源根 `clankerauth` 命令也读取.

```ts
import * as Credentials from "@gjermundgaraba/clankerauth-sdk/credentials";
import { Config, Effect } from "effect";
import { HttpClient } from "effect/http";

const notes = Credentials.authorizing({
  url: "https://notes.internal",
  token: Config.Redacted("NOTES_TOKEN"),
});

const program = Effect.gen(function* () {
  const client = notes(yield* HttpClient.HttpClient);

  return yield* client.get("https://notes.internal/api/notes");
});
```

`authorizing` 选择选项 `token` 并且是一个效果动作客户端的 `transformClient`数字 : `ActionHttp.client(NotesHttp, { baseUrl, transformClient: notes })` 给出失败的方法 `SignInRequired` 财务报告和审定财务报表 `TokenUnavailable` 长跑也是新鲜的.

`url` 是资源下的任何地址,例如程序所拨打的地址: 所使用的登录是资源所持有的地址, 数个地址最具体. `token` 失败 `SignInRequired` 当没有 登录使用,它的 `command` 页:1 `clankerauth login` 要运行,并使用 `TokenUnavailable` 当文件或发行失败时。 每一次通话或每跑一次 都会有信号 程序和CLI共享登录文件, `~/.config/clankerauth/sign-ins.json`,不管发行者如何,每个资源都有一个登录: 每一个更改其锁定,所以过期的登录被刷新一次,无论谁问,中断的刷新仍然使发行者旋转.

作为 CLI 的签名程序本身 `login` 是的,电话 `signIn(url, { scope, approve })`数字 : `approve` 显示发行人的批准页, 并保留登录 `token`,取消任何它替换. `list` 给签注保存 `signOut(url?)` 忘记和取消拥有资源的人 `url`,或每一个.

## 直接校验令牌

核心消费者不需要效应行动或 `skipLibCheck`。 。 。 .

```ts
import { Verifier } from "@gjermundgaraba/clankerauth-sdk";
import { Effect } from "effect";
import { FetchHttpClient } from "effect/http";

// Once, at module scope: what every verification has read.
const store = Verifier.store();

// Per request, in the request that verifies.
const verify = (token: string) =>
  Verifier.make({
    issuer: "https://clankerauth.internal/api/auth",
    resource: "https://notes.internal/",
    store,
    requiredScopes: ["notes:read"],
  }).pipe(
    Effect.flatMap((verifier) => verifier.verifyToken(token)),
    Effect.provide(FetchHttpClient.layer)
  );
```

商店持有的是验证器读取,解码和检查过的:每个发行商的JWKS密钥,每个资源在读取时和过期时都有经过验证的密钥列表. 它只持有价值,从来不是效应,纤维,承诺 `Response` 或计时器,所以它可能与过程一样活. 一个验证员只持有它的选项,商店和HTTP客户端. 在一次打击中,它在当地验证;在一次失手,或它持有的东西已过期后,它就会在核查中读出失手的发行者,并将结果写回。 同时错失了每个读数, 没有人在等待另一个读数: 一个在读数完成之前就错失的校正。 稳定交通费用为一至两个额外发行人每次刷新时读取;冲出一空或过期的商店时,每次在店中校验一次.

克劳德弗莱尔工人需要的就是这种分裂 一个工人的I/O属于启动它的请求:一个请求不能恢复工作,另一个启动的请求,一个终止了请求的续作被撤销([I/O代表不同的请求](https://developers.cloudflare.com/workers/observability/errors/#cannot-perform-io-on-behalf-of-a-different-request), (中文(简体) ), [跨请求承诺解决方案](https://developers.cloudflare.com/workers/configuration/compatibility-flags/#handle-cross-request-promise-resolution-correctly)) (中文(简体) ). 数据可能存在于全球范围;飞行中可能没有。 因此,保持存储在模块范围,作为数据,并在每次请求中获取验证器. 在节点上,一次获得的核查员同样正确,因为它也没有运行中的工作.

## 每个应用程序一个资源

登记册 **一个** 由应用程序的公用源根所识别的 crankerauth 仪表板中的资源, 并用其后端的斜线写出 : `https://notes.internal/`资源涵盖 `/api`, (中文(简体) ), `/mcp` 和任何套接字,带有一个 RFC 9728 文档 `/.well-known/oauth-protected-resource` 和一个 `forward_auth` 按钮.

已宣布资源 `layer` 取取公开的 URL 并获取该标识符本身, 因此应用程序从未写过两次, 也从未写过 MCP 客户端会重写的形式 。 URL上的任何路径都会被丢弃. 官方客户自己的 `checkResourceAllowed` 为它下面的终点接受源根资源.

公开的URL是发布发现的收听者被到达的地方,因为OAuth客户端拒绝将另一个资源命名于它所到达的资源(RFC 9728). API密钥从不读取发现,所以无论URL怎么说,它们都会继续工作;只有OAuth登录失败. 因此,当一个请求第一次到达另一个主机的出版听众时,资源会登录一个警告。 重写主机的代理使警告变得无害;其他任何表示URL是错误的.

合同规定谁可以召唤他们, `caller: CurrentPrincipal`,以及一个绑定的名称 一个呼叫者如何证明它:一个效果动作认证描述符,曾经在合同旁边声明过,浏览器客户端也从那里导入它. 描述者还声明,除拒绝外,其核查者未能履行下列义务: `ProviderUnavailable`发行者无法联系.

```ts
import { ProviderUnavailable } from "@gjermundgaraba/clankerauth-sdk/errors";
import {
  CurrentPrincipal,
  Whoami,
} from "@gjermundgaraba/clankerauth-sdk/session";
// contracts.ts: browser-safe.
import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";

// A bearer token proving a `CurrentPrincipal`. Its name is unique per process. Refusals are
// effect-actions' built-in `Unauthenticated` and `Forbidden`, declared on every endpoint; the
// descriptor declares the one answer that is the SDK's own, the 503, which every protected
// endpoint of a binding naming it then declares, so a typed client decodes it.
export const Login = Authentication.make("notes.Login", CurrentPrincipal, {
  error: ProviderUnavailable,
});

export const Http = ActionHttp.make([List, Write, Whoami], {
  authentication: Login,
});
```

服务器在模块级别上从描述器上声明资源一次,它拥有的每一个范围,每个证书必须携带的那个范围, `required`其中一个 `scopes` 作为类型检查。 它提供其 `layer` 联 合 国 `provider` 一次在应用构建时. `Resource.make` 只使用描述符声明 `ProviderUnavailable`: 不是一个类型错误, 命名 `error: ProviderUnavailable`。 。 。 .

```ts
import { Verifier } from "@gjermundgaraba/clankerauth-sdk";
import { Resource } from "@gjermundgaraba/clankerauth-sdk/effect-actions";
import * as ActionHttp from "@gjermundgaraba/effect-actions/ActionHttp";
import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
import { Layer } from "effect";
import { FetchHttpClient } from "effect/http";

import { Http, Login } from "./contracts.ts";

// The application's resource: the descriptor's name is its service's, unique in the process.
export const NotesResource = Resource.make(Login, {
  scopes: ["notes:read", "notes:write"], // every scope it has, published in discovery
  required: "notes:read", // every credential must carry it; every 401 names it
});

// `app` is your implementation, behind your own authorizer, a module-level value: see
// "Scope enforcement".
const routes = Layer.mergeAll(
  ActionHttp.layer(Http, [app, NotesResource.session]),
  ActionMcp.layerHttp(app, {
    name: "notes",
    version: "1.0.0",
    authentication: Login,
  })
).pipe(
  Layer.provide(NotesResource.provider),
  Layer.provide(
    NotesResource.layer({
      issuer: "https://clankerauth.internal/api/auth",
      publicUrl: new URL("https://notes.internal"),
      store: Verifier.store(),
    })
  ),
  Layer.provide(FetchHttpClient.layer)
);
```

以效果为本层服务 `HttpRouter` 和您的节点服务器层。 如果使用 `@effect/platform-node`,安装符合您效果的释放。 每次部署范围都是一样的,因此用资源申报; `NotesResource.layer` 使用因部署而异,并一次性构建资源:其验证和拒绝。 内容 `store` 如上所述,是核查者的。 资源没有运行中的工作,所以一旦它仍然只在请求中读取验证的发行人,就建成了;一个按请求分层构建的应用程序,如工人可能,会通过一个在模块范围所制作的商店,所以所读内容会超过每个请求. `NotesResource.provider` 是描述器的提供者, 效果动作 `Authentication.layer`:它在解码前验证每个受保护的路线和工具呼叫,并公布发现本身,公开和外部认证;没有发现路线可以合并. 发现缓存策略属于主机. 对它认证的请求的每一个答复 `Cache-Control: no-store`。您自己运行的中间软件作为效果动作运行它:在提供者之后提供的路由器中间软件,或者 HTTP 层的 `middleware`。 。 。 .

其调用者持有 API 密钥且从未运行 OAuth 流的表面, 如发布资源时旁边的第二个收听器 `discovery: false`:它以同样的方式认证,不发表任何东西,它的挑战是一个平庸的 `Bearer`。它是相同的注册资源,所以它需要出版听众的公开URL,而不是自己的地址:除了私人管理员之外,一个公共机器听众仍然通过管理员的URL.

两个具有不同视野的听众,如管理员和机器配对,仍然是仪表板上的一个资源,两者的每一个范围。 过程宣布两个描述符和两个资源,每个听众一个,每个需要自己的范围,并且给予相同的 `layer` 选项但 `discovery`数字 : `Resource.make(Authentication.make("notes.admin", CurrentPrincipal, { error: ProviderUnavailable }), { scopes: ["notes:read", "notes:write"], required: "notes:read" })` 一个给 `"notes.machine"`,每个名称由自己的约束。 每一个都是自己的服务,所以每个地表都读取自己的资源,用一层图或数个图. 描述者的名字是身份:两次宣布一个名字,两次宣布同一资源.

已申报资源是 `Resource.Declared<"notes.Login">`及其内容 `layer` 构建一个 `Resource.Built`;其描述是 `Resource.Login<"notes.Login">`。 。 。 . `Declared` 财务报告和审定财务报表 `Login` 将描述者宣布为可选的第二个参数, `ProviderUnavailable` 一个人待着. `Declared` 财务报告和审定财务报表 `Built` 将资源范围作为可选参数, 最后一个, 哪个 `make` 推断从 `scopes`: 一种不包含它的注释 , 接受任何范围字符串 。 切入点还输出每类资源在统一名称下提及的申报(`DeclaredResource`, (中文(简体) ), `BuiltResource`, (中文(简体) ), `ResourceService`, (中文(简体) ), `ResourceDeclaration`, (中文(简体) ), `ResourceOptions`, (中文(简体) ), `Login`, (中文(简体) ), `Admission`, (中文(简体) ), `Refusal`, (中文(简体) ), `Principal`, (中文(简体) ), `Verifier`(三); `CurrentPrincipal` 联 合 国 `Caller` 为: `/session`'',在那里,宣言命名他们。 因此,一个输出其描述符、资源或执行的软件包在没有注释的情况下发出声明.

供给 `HttpClient` 不得重试信用交换或跟踪方向。 SDK 覆盖只获取 HttpClient 的重定向策略 `manual`,但以重定向( 任意 3xx) 读取失败 `ProviderUnavailable`;它保留了其他调用器提供的取取默认值,并且从不安装重试中间软件. `manual`没有 `error`因为Cloudflare工人拒绝 `redirect: "error"` 发送前( e)[请求](https://developers.cloudflare.com/workers/runtime-apis/request/#options)) (中文(简体) ).

## 范围强制执行

申请决定动作需要的范畴; SDK 验证证书并给出检查. 需要核查 `required` 每一个证书,所以行动 不需要更多的通过。 任何其他范围是申请书的规则,说明其执行授权人: `requires(scope)`:它运行于输入解码后,在每个表面的每一个处理器——HTTP,MCP,工具包,CLI——之前,所以没有一个处理器可以忘记它.

```ts
import { CurrentPrincipal } from "@gjermundgaraba/clankerauth-sdk/session";
import * as Action from "@gjermundgaraba/effect-actions/Action";
import { Effect } from "effect";

const List = Action.make("list", {
  description: "List notes",
  readOnly: true,
  caller: CurrentPrincipal,
  success: Notes,
});

const Write = Action.make("write", {
  description: "Write a note",
  readOnly: false,
  caller: CurrentPrincipal,
  success: Note,
});

// The application's rule: a read needs only what verification required, a write needs
// `notes:write`. It reads no built resource, so this is a module-level value.
const authorize = (action: Action.Any) =>
  action.readOnly ? Effect.void : NotesResource.requires("notes:write");

const app = Action.implement([List, Write], handlers, { authorize });
```

`requires(scope)` 取一个资源宣布的范围, 所以一个打字, `requires("notes:wirte")`,是类型错误,因为它位于 `admitted`, (中文(简体) ), `admit` 财务报告和审定财务报表 `watch`这是一个 `Effect<void, Action.Forbidden, CurrentPrincipal>`:没有范围的访问者被拒绝使用 `Forbidden` (403) 命名 **仅限** 范围,所以它从来没有列出资源的权限。 单镜资源, `{ scopes: ["notes:read"], required: "notes:read" }`,没有其他需要:其执行状态 `{ authorize: Action.allowAll }`每个瞄准镜是OAuth瞄准镜符号,可打印的ASCII没有空格, `"` 或者说 `\`: 效果- 动作拒绝当提供者建立其公布的发现时不是的效果。 与 `discovery: false` 没有检查它们,拒绝 OAuth 客户端 宣布的范围,不是范围标志 是缺陷,500: `Action.Forbidden`建筑师把它扔下去.

一个可信赖的本地表面,如stdio MCP或本地命令,没有远程呼叫器,也没有验证证书. 过程是呼叫者: `NotesResource.local(subject)` 这是它的主要, `{ kind: "local" }`,保留资源申报的每一个范围,并且永远不会过期。 主办方提供它作为效果行动提供任何当地特征,并服务于同样的执行,其授权方承认它,因为它拥有每一个范围:

```ts
const stdio = ActionMcp.runStdio(app, { name: "notes", version: "1.0.0" }).pipe(
  Effect.provide(NodeStdio.layer),
  Effect.provideService(CurrentPrincipal, NotesResource.local("owner"))
);
```

在一个地方 `ActionCli` 命令, `Command.provideSync(CurrentPrincipal, NotesResource.local("owner"))`。局部表面没有构建资源 : `local` 财务报告和审定财务报表 `requires` 只读已宣布的瞄准镜和呼叫器.

前向自动浏览器符载 **每个** 范围定义资源,因为发行者将它用于签名所有者而不是程序。 范围 应用程序因此需要闸门代理和 API 密钥, 而不是键盘上的主人: 只给出一个只读代理或密钥 `notes:read` 同样的规则拒绝它的写作.

动作读取身份从 `CurrentPrincipal`页:1 `Caller`,包含 `subject`, (中文(简体) ), `scopes`, (中文(简体) ), `actor` —— 说 `{ kind: "client", clientId }`, (中文(简体) ), `{ kind: "key", keyId }`,或 `{ kind: "local" }` 用于当地表面的进程——和 `expiresAt`: 访问符已验证 `exp`,或者一个 API 密钥的过期, 以 epoch 毫秒表示, 因此一个连接到其证书的主机永远不会再次解码它 。 没错 `undefined` 对于未过期的密钥,对于当地校长。 在此之前,钥匙也可以被吊销; `watch`,下面,在先到者时结束连接。 一个核查者证明, `Verifier.Principal`,仅是客户端或密钥: `verifyToken` 财务报告和审定财务报表 `admit` 给,每个人都是 `Caller`。 。 。 .

每一次拒绝都是效果动作的内置出错,每个端点和工具都会声明,每个客户端都会解码: `Unauthenticated` (401个)和 `Forbidden` (403) (英语). 进入标志的 `Forbidden` 标出缺失范围,并在MCP中被解答为403 `insufficient_scope` 挑战 OAuth 客户端继续前进 。 API 密钥不能重授权, 因此它 `Forbidden` name no: a plain 403, 和 MCP 上的一个工具错误. `Cache-Control: no-store` 挑战来自效果行动 围绕每个请求 提供者认证。 在核查人运行前,无无记名证的请求被拒绝: `A bearer token is required.`

提供者对请求进行认证,应用程序的授权人授权;既没有过滤MCP工具的发现.

## 自己的路线

除了其动作,例如页面框架、文件下载或OpenAPI文档之外,程序本身服务的一个路由也随着动作的进行而被接受 `admitted`,周围提供的路由器中间软件:

```ts
import { CurrentPrincipal } from "@gjermundgaraba/clankerauth-sdk/session";
import { Effect, Layer } from "effect";
import { HttpRouter, HttpServerResponse } from "effect/http";

const frame = HttpRouter.add(
  "GET",
  "/frame",
  Effect.map(CurrentPrincipal, ({ subject }) =>
    HttpServerResponse.text(subject)
  )
).pipe(Layer.provide(NotesResource.admitted().layer));
```

`admitted()` 接受任何经核实的呼叫者; `admitted("notes:write")` 并检查其范围,与 `requires`作为授权人 检查一个动作。 这是效果行动 `Authentication.protect` 使用资源描述符, a `Authentication.Protection`,所以该路由被准确的回答作为一个动作路由 回答相同的请求: 拒绝具有相同的状态,挑战, `Cache-Control` 和JSON,503 当发行人没有, `Cache-Control: no-store` 除非路由表明自己的缓冲 和拒绝 路由本身失败, `Unauthenticated` 或者说 `Forbidden`或一个401的答案, 挑战。 被允许的路线读取其呼叫者来自 `CurrentPrincipal`。其层需要资源 `provider`,它认证:提供 `provider` 环绕被接受的路线 环绕行动,一次为两者。 这是Effect自己的 `HttpRouter.Middleware`这样 `combine` 由你自己的中间软件 来读里面的呼叫器: `myMiddleware.combine(NotesResource.admitted())`。 。 。 .

## 在路由器外

一个插座, 一个节点 `upgrade` 处理器或每个请求的终点,它持有一个标题,没有路由请求,对照同一资源验证同一证书,并作出同样的拒绝,但 `admit`任何经核实的来电者被接纳,或只有具有范围的人被接纳,但也持有:

```ts
// `notes` is the built resource: `yield* NotesResource.service`, under `NotesResource.layer`.
const admission = await Effect.runPromise(
  notes.admit(request.headers.authorization, "notes:write")
);

if (!admission.ok) {
  const { status, headers, body } = admission.refusal;
  response.writeHead(status, headers).end(body);
  return;
}

connect(admission.principal);
```

拒绝的每个错误都具有自己的地位(401/403/503),RFC 6750质疑,包括无证案件, `Cache-Control: no-store`,错误的JSON编码。 没错 `admitted`由效果动作制成的检查 `Authentication.refusalResponse`,一个路径得到的答案是相同的拒绝,所以一个路由器和一个套接字永远无法做出不同的答复. `admission.principal` 是一个 `Verifier.Principal`,客户端或密钥.

超过其承认的连接,例如 WebSocket, 被保持到相同的标题值和范围 `watch`拒绝失败 `admit` 然后会回答, `Action.Refusal` 或者说 `ProviderUnavailable`:一旦一个访问符过期,或者一旦更新的密钥列表不再授予该密钥,或者不再授予该范围. 它永远不会成功,所以与连接竞争:

```ts
const session = Effect.raceFirst(
  serve(socket),
  notes.watch(request.headers.authorization, "notes:write")
);
```

访问符不能被撤销, 所以 `watch` 等待过期, 然后失败 `Unauthenticated`,而不再次询问发行者;一个密钥大约每分钟对列表重新检查一次,最后读取的资源本身大约每分钟读取一次,所以被撤销的密钥会在大约两分钟内结束被监视的连接. 一个关键需要发行者 只有在列表经过它的窗口.

资源也暴露了 `verifier.verifyToken(token)` 对于自己做出回应的来电者来说,这是一种效果 `Authentication.bearerTokenOf(authorization)` 读取每一个表面。 你自己的一个提供者, 效果行动' `Authentication.layer` 绕着你自己的核查员,从 `Resource.authenticate(verifier, token)`,鉴于标记符的图案解码:本金,一个表面发出的拒绝,或者 `ProviderUnavailable`您的描述者也声明了这一点, 所以一个表面发出它作为503.

## 请求政策

前进认证使浏览器的认证环境: 代理附加一个 `Authorization` 浏览器发送的任何信息,包括跨站点导航,都带有标题. 因此,它背后的应用程序 检查从哪里来的 请求之前,任何东西读到证书。 效果动作' `RequestPolicy` 与主机和源码的精确比较 `/healthz` 保留在容器探测器上 :

```ts
import * as RequestPolicy from "@gjermundgaraba/effect-actions/RequestPolicy";

const policy = RequestPolicy.make({
  publicUrl: new URL("https://notes.internal"),
  allowedOrigins: ["wtf://app"], // a desktop shell's private renderer scheme
});

const routes = protectedRoutes.pipe(Layer.provide(policy.middleware.layer));
```

内容 `policy.allows({ target, host, origin })` 给一个没有服务的节点升级处理器做出同样的决定。 SDK 将此策略导出为 `RequestPolicy` 直至0.34.0;效果-动作之一采取相同的选项,并以同样的方式决定. 这不是认证,它也没有设定身体限制或安全头条——那些保留应用程序的.

## 浏览器应用程序

浏览器页面没有自有的证书: 将它放在反向代理后面, 由发行方的前置认证, 描述于 clankerauth README 中 `Authorization` 此软件包的页眉已验证 。 该页面确实需要的 是谁被签入, 和出路:

```ts
import {
  Principal,
  Whoami,
  signOutUrl,
} from "@gjermundgaraba/clankerauth-sdk/session";

// `Whoami` is the contract, bound beside your own actions; the server answers it with
// its resource's `session`. `api` is `ActionHttp.fetchClient(Http)`.
const principal: Principal = await Effect.runPromise(api.whoami());
link.href = signOutUrl(principal.issuer, `${location.origin}/`);
```

`Principal` 实值 `{ subject, issuer, scopes }`。 。 。 . `signOutUrl` 发行方的分数 `/forward-auth/logout?rd=…`,它结束了发行会话和每个应用程序的前置饼干;这是一个简单的链接。 在服务器上,一个已声明的资源 `session`, (中文(简体) ), `NotesResource.session`,为 `Whoami` 从经核实的证书中已执行——交给 `ActionHttp.layer` 并删除手写 `whoami`。 。 。 .

## 测试用的假发行商

`@gjermundgaraba/clankerauth-sdk/testing` 是程序测试通常想要的发行者: 资源服务器实际调用的两个端点, 而其他的则没有。 它用真实的EdDSA密钥来签名并发布为JWKS,因此每个令牌和密钥列表仍然会穿行资源服务器自己的验证器——签名,发行者,受众,类型,权利要求,范围,每个密钥被封入的条目,而不启动整个发售器. 它运行在节点.

```ts
import { startFakeIssuer } from "@gjermundgaraba/clankerauth-sdk/testing";

const auth = await startFakeIssuer({
  resource: "http://127.0.0.1:8080/",
  scopes: ["notes:read", "notes:write"],
});

auth.issuer; // configure the resource server with this
const token = await auth.sign(); // every claim is overridable: auth.sign({ exp, aud, scope })
const key = auth.apiKey(); // every configured scope on the configured resource
const hosts = auth.apiKey(
  { [hostA]: ["host:write"], [hostB]: ["host:write"] },
  expiresAt
);
auth.revoke(key); // gone from the next key list, as the real issuer behaves
auth.fail(503); // both endpoints answer this instead; auth.fail() restores them
auth.keyLists(); // how many key lists were served
await auth.close();
```

`apiKey` 将权限与真正的发行者一样,将资源标识符带入范围,因此一个密钥可以到达多个资源. 资源服务器为它命名的密钥每分钟读取一次密钥列表,所以测试会撤销密钥并期望拒绝用新的验证符验证,或者将时钟推过该分钟. 修饰者读完之后的密钥被拒绝,直到读完5秒,所以在第一次请求之前,试铸薄荷其密钥. 测试整个发行人——签入,同意,转发认证——使用 `@gjermundgaraba/clankerauth-dev`。 。 。 .

## 错误和可观察性

标记错误,全部来自 `@gjermundgaraba/clankerauth-sdk/errors`数字 : `Unauthorized`, (中文(简体) ), `InsufficientScope` 财务报告和审定财务报表 `ProviderUnavailable` 是什么样的 `Verifier` 失败 。 仅 `ProviderUnavailable` (503)是一种图案,资源描述者宣布它并宣布其具有约束力的名称的每一个受保护的终点;前两个从未到达过电线,作为一个 `Resource` 把它们作为效果动作内置 `Unauthenticated` (401个)和 `Forbidden` (403) (英语). 无效的构造, 如没有 URL 的发行器, 失败 `ConfigurationError`。 。 。 .

有一个403。 只有核查员自己的检查失败 `InsufficientScope`: 有效的证书,但不包含 `requiredScopes`,资源 `required`它命名了范围和证书 `actor`,决定其是否 `Forbidden` 站起来。 核查后要求的范围 `requires(scope)`, (中文(简体) ), `admitted(scope)`, (中文(简体) ), `admit(header, scope)` 或者说 `watch(header, scope)`,以效果行动拒绝 `Action.Forbidden` 直接,由同一条规则决定. 根本不是这种资源的证书—— 错误的受众, 或在这种资源的密钥列表中没有条目的 API 密钥—— 是 `Unauthorized`因为从资源的角度来说 这些都是同样的事情.

JWT是对照发行商、受众、EDDSA签名、标志类型、要求的索赔、到期和范围进行核对的。 寄出者受约束的相克被拒. 一个JWKS读取每分每分每秒的回答,所以发行者开始或停止出版的密钥在该分钟内生效; a `kid` 当前文档不发布为 `Unauthorized` 永远不触发读取, 所以一个符号与发明 `kid` 无法成为提供者流量。 读取失败的答案 `ProviderUnavailable` (503)在下一次尝试之前的5秒钟;其核查被中断的读取没有写出什么,而下一份核查读取了一遍. API 密钥在资源密钥列表中进行离线校验: 一张带有访问密钥的发证人标志的文档,按此资源所授予的密钥持有被封入的条目,只有该密钥才能找到或打开. 清单经过一次核实,在读取时,一个读取了每一个它命名的密钥一分钟,没有发行者流量;所以一个已禁用、删除或重新扫描的密钥保持其访问权限,直到下次读取时,大约一分钟之内。 持有的列表没有名称的密钥可能是从此资源创建,启用或授予的,因此该列表在拒绝该密钥之前再次被读取,除非它在过去5秒内被读取:这样的密钥在秒内工作,未知密钥最多每5秒一次到达发行者. 每次核查都会检查钥匙的过期时间,因此立即适用. 读取失败,或者其列表或JWKS取取取时间超过三秒的,在最后列表处于自身寿命内,发行者设定为24小时时,则无出错:密钥持续通过出局验证,JWKS与否,发行者5秒后再次被试. 被中断核查的读取没有写出任何内容,下一个密钥读取再次. 毕生,或者在任何列表被读取之前,一个关键是 `ProviderUnavailable`。读取的开始失败会被记录一次,作为警告,并且它们恢复一次信息级别,所以被保存的列表隐藏在应用程序日志中,每次重试时仍没有行. 上一个名单是 持有的,无论它的 `iat`:HTTPS到发行商是阻止旧列表被重放的原因,一个人只能在自己的一天内被重放. 发行商不计密钥用途,所以速率限制是应用程序的. 一个密钥是一个不记名的秘密,一个在几个资源上授予的密钥可以被其中任何一个重放给其他资源;一个你不太信任的资源得到自己的密钥. 只接受 OAuth 访问令牌集的资源 `apiKeys: false`;按键形状的持卡人随后失败为 `Unauthorized` 不读取密钥列表。 A. 通过委员会 `Resource` 期限为5秒;未到期 `Verifier` 没有,所以一个进程内调用者可以等待一个提供者调用它不能取消。 例外是读取的密钥列表,该列表将它的两个抓取,列表和它被验证的JWKS一起运行,当没有被持有时,每三秒给出一次,所以一个慢抓取不会缩短另一个. 因此,一个密钥列表在三秒钟内结束,不管什么摊位,在列表被持有时,一个密钥永远不会失败.

捆绑的发行方不配置自动签名键旋转. 即时使用旋转被支持,但被新密钥所签名的指使被拒绝,直到下一次JWKS读取,最多一分钟;它所签名的密钥列表直到那时也不会被取出,所持有的列表继续决定. 一个没有 JWKS 的读取也一样: 它的 JWKS 获取列表旁边的运行, 因此, 一个在获取开始后由密钥计时器签名的列表在下一次 JWKS 读取前失败 。 捆绑的发行商薄荷在开始时会将它的签名密钥放入其中,因此由JWKS出版的密钥签出一款新鲜的发行商的第一份清单. 公布使用前可避免该窗口,但并非强制性的。 每个读取的密钥列表都会重新签名,所以所发的API密钥不会被旋转所影响.

SDK的资源地图验证失败 执行动作的拒绝和它自己的503; 效果动作提供请求范围的身份,挑战头和 `Cache-Control: no-store` 对它认证的请求的每个响应; 其他缓存策略是主机的。 缺陷和中断不会被重新标为认证拒绝. 命名效应供应追踪边界;应用程序记录/跟踪层仍为呼叫者所有。 没有 `onFailure` 调用或隐藏运行时间.

业务失败仍然有其基础 `cause` 用于应用程序侧效应错误处理. `ProviderUnavailable` 财务报告和审定财务报表 `Unauthorized` 保持这个诊断领域不可假定, 在序列化之外。 原因可能包含敏感的运输或提供者细节:有选择地检查,从不将其序列化为答复,或不加区别地记录.

麻省理工学院有执照.

## 常见问题

### @gjermundgaraba/clankerauth-sdk 是什么？

Effect-native clankerauth access-token和离线API-key验证,可选效果动作集成

### 如何安装 @gjermundgaraba/clankerauth-sdk？

在项目目录运行 npm install @gjermundgaraba/clankerauth-sdk，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：effect（~4\.1\.1）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @gjermundgaraba/clankerauth-sdk 支持 TypeScript 吗？

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

### @gjermundgaraba/clankerauth-sdk 支持 ESM 还是 CommonJS？

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

### @gjermundgaraba/clankerauth-sdk 需要什么版本的 Node\.js？

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

### @gjermundgaraba/clankerauth-sdk 可以商用吗？

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

### @gjermundgaraba/clankerauth-sdk 的下载量有多少？

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

### @gjermundgaraba/clankerauth-sdk 还在维护吗？

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

