@ e受影响/ jwt

签名和验证 JWTs for Effect v4,并从发行商已公布的密钥集中解析校验密钥. 一层薄的地层 effect/jose,它运行每个签名、密钥导入和权利要求检查,所以它在WebCrypto的任何地方都有效:Node、Bun、Deno、浏览器和Cloudflare工人,没有 node: 导入.

预1.0.0。 。 。 . 此软件包是 @effected/* 工具箱,在 稳定效果 v4并仍在 0.x 发展。 为了保持你的 effect 财务报告和审定财务报表 @effect/* 该工具包在线上构建和测试、安装 @effected/pnpm-plugin-effected。 。 。 .

稳定:不稳定. 此软件包的 API 表面尚未考虑 完成并可能改变 0.x 释放 准确的版本。 满 政策: 释放策略。 。 。 .

为什么 @ effect/jwt

核心 effect/jose 已签名并验证 JWS 和 JWT, 导入 JWK 并获取密钥集 。 当您对照您已经持有的密钥或一个固定的HTTPS JWKS URL进行校验时直接使用它(Jwks.layerRemote,用 PKCS#8 键签名,或需要 HMAC 或 JWE .

当您需要核心留给您时,请联系这个包:

• OIDC发现的钥匙. JwksResolver 找到每个发行人的密钥集 <issuer>/.well-known/openid-configuration,检查发现文件名称 准确的发布者,服务于许多发布者 从一个服务 kid。 。 。 .
• 你选择的缓存 . 获取的密钥集以 JwksStore: 与 JwksStore.layerMemory,或者在工人KV中, 所以每一个孤立者共享一个获取.
• PEMs的人确实有. JwtKey.fromPkcs8Pem 使用 PKCS# 8 和 PKCS# 1 ()BEGIN RSA PRIVATE KEY,格式 github.com 将App 键输出出去),包括一条新行到达的键作为逃出 \n 在一行环境变量中.
• 更安全的违约. Jwt.verify 允许 60 秒时钟 skew, 需要 exp 除非你们选择退出,并且拒绝将来发行的标志。 Core的默认值为零 skew 和可选 exp。 。 。 .
• 一个路径错误 . 每一次失败都是 JwtError 有个公寓 reason 绳子.
• 试发会. TestIssuer 标志通过真正的解析器进行验证,没有网络.

钥匙是核心本身的类型,所以是来自 JwtKey 也与核心协作 Jws 财务报告和审定财务报表 Jwt 直接说.

安装

npm install @effected/jwt effect

pnpm add @effected/jwt effect

在节点上,它需要Node.js QQ24.11.0;它还运行在任何其他WebCrypto运行时间上,Cloudflare Workers也包括在内. effect v4是唯一的对等器. 全体 @effected/* 软件包仅限无害环境管理.

提供什么

在您程序边缘提供的核心服务上签名和验证运行 :

JwtKey.fromPkcs8Pem, (中文(简体) ), JwtKey.fromJwk 财务报告和审定财务报表 Jws.decodeUnverified 不需要任何东西.

import { JwksResolver, JwksStore } from "@effected/jwt";
import { Layer } from "effect";
import { SecureRandom, Signature } from "effect/crypto";
import { FetchHttpClient } from "effect/http";

const CryptoLive = Signature.layerWebCrypto.pipe(Layer.provide(SecureRandom.layerWebCrypto));

const JwtLive = Layer.merge(
  JwksResolver.layer.pipe(Layer.provide(Layer.merge(FetchHttpClient.layer, JwksStore.layerMemory))),
  CryptoLive,
);

签署 JWT

来自 PKCS# 1 关键 github.com 的 GitHub App JWT 问题. 标题是 {"alg":"RS256","typ":"JWT"}数字 : alg 总是来自钥匙.

import { Jwt, JwtKey } from "@effected/jwt";
import { Effect, Redacted } from "effect";

const signAppJwt = (pem: Redacted.Redacted<string>, appId: string, nowSeconds: number) =>
  Effect.gen(function* () {
    const key = yield* JwtKey.fromPkcs8Pem(pem, { alg: "RS256" });
    return yield* Jwt.sign({ iat: nowSeconds - 60, exp: nowSeconds + 540, iss: appId }, key);
  });

对照发行人公布的密钥校验

把发行人交给你 forIssuer,从来没有人从符号读取: 发行者决定哪些密钥是信任的。 总是通过 audience 对于一个共享的发行者,其一键为每个依赖方设置了标志.

import { JwksResolver, Jwt } from "@effected/jwt";
import { Schema } from "effect";

const Claims = Schema.Struct({ sub: Schema.String });

const verify = (token: string) =>
  Jwt.verify(token, {
    key: JwksResolver.forIssuer("https://issuer.example"),
    claims: Claims,
    issuer: "https://issuer.example",
    audience: "my-service",
  });
// Effect<{ readonly sub: string }, JwtError, JwksResolver | Signature>

检查按此顺序进行:签名,然后 exp 现在, iss, (中文(简体) ), aud, (中文(简体) ), exp 未通过, nbf 到达,你的 claims 计划,最后 iat 未来不会. clockTolerance 财务报告和审定财务报表 requireExpiry 调整默认值.

用您持有的密钥校验

key 是一个 VerificationKey,或从符号头到一的函数.

import { Jwk, Jwt, JwtKey } from "@effected/jwt";
import { Effect, Schema } from "effect";

const verifyWith = (jwk: Jwk, token: string) =>
  Effect.gen(function* () {
    const key = yield* JwtKey.fromJwk(jwk);
    return yield* Jwt.verify(token, { key, claims: Schema.Struct({ sub: Schema.String }) });
  });

Jws 在没有索赔规则的情况下是同一签字层(Jws.sign, (中文(简体) ), Jws.verify),以及 Jws.decodeUnverified 读取符号头和有效载荷作为同步 Result,用于路由 kid 或者说 iss 在选择密钥之前。 永远不要相信它回来.

算法

每个不对称算法核心设备: RS256, (中文(简体) ), RS384, (中文(简体) ), RS512, (中文(简体) ), PS256, (中文(简体) ), PS384, (中文(简体) ), PS512, (中文(简体) ), ES256, (中文(简体) ), ES384, (中文(简体) ), ES512 财务报告和审定财务报表 EdDSA (Ed25519) (英语). 该算法出自密钥,从不给符头,2048位以下的RSA密钥被拒绝. HMAC 被拒绝, 因为密钥集中公布的密钥绝不能作为共享密钥; 对于 HMAC 使用 Core 的密钥 Jwk.importSecret 带有核心 Jwt。 。 。 . alg: "none" 永远不会被接受.

错误

每一次失败都是 JwtError路径 reason永远不要 message 或者说 detail当核心产生故障时 JoseError 这是 cause。 。 。 .

一个符号字符串不是身份:ECDSA签名是可商的,所以一个被签名的有效载荷可以有两个有效的符号字符串. 检测在核实的索赔中重放和撤销(jti,或 iss 与 sub 财务报告和审定财务报表 iat),从未在符号文本上.

测试

@effected/jwt/testing 出口 TestIssuer: 生成的密钥对, 用于邮票的签名符 iss, (中文(简体) ), iat 还有十分钟 exp,以及 resolverLayer真实的 JwksResolver 在一个记忆中 HttpClient 为发行人的发现文件和密钥集服务.

import { JwksResolver, Jwt } from "@effected/jwt";
import { TestIssuer } from "@effected/jwt/testing";
import { Effect, Schema } from "effect";

const program = Effect.gen(function* () {
  const issuer = yield* TestIssuer.make({ issuer: "https://issuer.test" });
  const token = yield* issuer.sign({ aud: "my-app", sub: "user-1" });
  return yield* Jwt.verify(token, {
    key: JwksResolver.forIssuer("https://issuer.test"),
    claims: Schema.Struct({ sub: Schema.String }),
    issuer: "https://issuer.test",
    audience: "my-app",
  }).pipe(Effect.provide(issuer.resolverLayer));
});
// provide CryptoLive: TestIssuer and Jwt.verify both need Signature

提供 resolverLayer 当它依赖于缓存或旋转时 整个测试一次. TestIssuer.rotate(issuer, kid) 在新键下添加密钥 kid- 解析器最多每30秒调试一次 TestClock 在用新密钥验证前。 与 @effect/vitest,提供 Signature 每个测试(layer(CryptoLive, { buildPerTest: true }):为整个区块建造的一层 TestClock 整个测试.

许可证

麻省理工学院