@gdp-ts/core

中文文档
0.1.0发布于 2026/10/05MITTypeScriptES Module零依赖近 30 天下载 179.2万

TypeScript的出走证明的"幽灵":授权(和其他检查),其结果类型检查者可以看到.

中文使用文档
文档目录11 节
  1. 特征
  2. 安装
  3. 问题
  4. 解决办法
  5. 如何运作
  6. 包裹
  7. 技术
  8. 实例
  9. 与其他解决办法的关系
  10. 以前的艺术和信用
  11. 许可证
A pixel-art ghost carrying a TypeScript document with a green checkmark

常规

一个小 库+线条 财务报告和审定财务报表 人工智能技能 执行情况 离开的鬼魂 用于 TypeScript,一种在编译(类型检查)时使 API 合同更加安全的验证系统.

gdp-ts 制定一整套授权(“ 此用户能否读取此资源 ”)或应享权利(此用户是否为此资源付费 通过在编译时捕捉到这些虫子,在可忽略不计的运行时间上,人类和编码代理非常难以引入.

特征

  • 可递增采用:与任何TS代码库和任何运行时间一起工作,不会改变你如何做I/O或效果.
  • 易燃滑轮:详尽证明的多少取决于每个代码库的斟酌/风险承受能力,以及 技术 捆绑 咨询。 。 。 .
  • ~零运行时间 :: 没有额外的查询或依赖。 唯一的运行时间成本是很小的 包裹在你检查的身份证上 安全来自类型检查器.
  • 输入检查的成本:每个经授权的呼叫站点在冷的TypeScript 7检查时大约0.3 ms. 成本随着使用频率的增长而增加,而不是随着代码库大小的提高(基准) (中文(简体) ).

安装

$ npx skills add rauchg/gdp-ts
$ pnpm add @gdp-ts/core

需要 TypeScript 5.4 或更新 .

问题

许多像这样的代码库特征代码:

async function handler(req, res) {
  await assertProjectAdmin(req.user.id, req.params.projectId); // throws 403
  await setPasswordProtection(req.params.projectId, req.body.password); // nothing connects this to the line above
  res.sendStatus(204);
}

看上去不错,除了: 它只需要

  • 开发者滑倒并错过第一个 await
  • 关于谁可以"更改密码保护"以更改(例如,只有所有者)的业务规则,和一个继续运行旧支票的呼叫站点

...为了安全/商业灾难的发生.

解决办法

我们改变上面的签名 从什么 任何人都可以从任何地方打电话数字 :

function setPasswordProtection(projectId: ProjectId, password: string): Promise<void>;

...强迫打电话的人 现有证据(证据) 他们可以做,也可以做计划

function setPasswordProtection<U, P>(
  project: Named<P, ProjectId>,
  password: string,
  _proofs: { admin: UserIsProjectAdmin<U, P>; plan: PlanIncludesPasswordProtection<P> },
): Promise<void>;

技能要注意引导代理人和人类走向这种更安全的模式,并远离 布尔失明 问题.

如何运作

1️⃣ 名称值. name(x, k) 给一个运行时间值 一个只编译时间的名称 N。每次呼叫 name 创建不同的 N,以及 N 仅存在于召回中。 例如,单独命名的wwo项目代号现在可以被编译器区分,尽管两者都是 string数字 :

// app.ts
import { name } from "@gdp-ts/core";
import { disablePasswordProtection } from "@/data/projects";
import { ProjectId } from "@/lib/ids";
import { userIsProjectAdmin } from "@/proofs/user-is-project-admin";
import { app, authenticated, HttpError } from "@/lib/server"; // your Express app, auth middleware, error type

app.delete(
  "/projects/:id/password-protection",
  authenticated((viewer, req, res) => // authenticated() resolves the logged-in user
    name(viewer.id, ProjectId(req.params.id), async (user, project) => {
      const admin = await userIsProjectAdmin(user, project);
      if (!admin) throw new HttpError(403, "Only Owners and Members can change this");
      await disablePasswordProtection(project, admin);
      res.sendStatus(204);
    }),
  ),
);

2 证明姓名的事实. 一个小 信任模块 检查并返回 a Proof<"UserIsProjectAdmin", [U, P]>,或 null只有那个模块才能铸造出证据 跑步时,证据是被冻结的 { kind } 对象.

// proofs/user-is-project-admin.ts  (trusted: the only place that can mint this proof)
import { defineProof, type Named, type Proof } from "@gdp-ts/core";
import { db } from "@/lib/db";
import type { ProjectId, UserId } from "@/lib/ids";

const UserIsProjectAdmin = defineProof("UserIsProjectAdmin"); // not exported
export interface UserIsProjectAdmin<U, P> extends Proof<"UserIsProjectAdmin", [U, P]> {}

export async function userIsProjectAdmin<U, P>(
  user: Named<U, UserId>,
  project: Named<P, ProjectId>,
): Promise<UserIsProjectAdmin<U, P> | null> {
  const role = await db.roleInProjectTeam(user.value, project.value);
  return role === "owner" || role === "member" ? UserIsProjectAdmin.prove(user, project) : null;
}

3 要求证明. 敏感功能需要证明他们的确切论点。 用错误的证据召唤他们, 一个不同值的证据, 一个原始的ID, 或者没有证据是一个编译错误 QQ

// data/projects.ts  (sensitive: demands exact proofs)
import type { Named } from "@gdp-ts/core";
import { db } from "@/lib/db";
import type { ProjectId } from "@/lib/ids";
import type { UserIsProjectAdmin } from "@/proofs/user-is-project-admin";

export function disablePasswordProtection<U, P>(
  project: Named<P, ProjectId>,
  _proof: UserIsProjectAdmin<U, P>,
): Promise<void> {
  return db.writePasswordProtection(project.value, null);
}

TL; 大卫:

  • 中间软件只认证。 检查发生在路由体, 就在需要结果的地方 disablePasswordProtection 没有它就不会编译.
  • 因为数据层 需求 一个证明,而不是执行检查,可以安全地导出:一个路由,一个服务器动作或者一个工作可以调用它,而他们都无法跳过检查.
  • 证据是 幽灵: 他们在运行时无所事事, 在编译时无所事事 时间. 我们靠林克 防止"取食"(例如: {} as UserIsProjectAdmin<U, P>) (中文(简体) ).

包裹

@gdp-ts/core 在npm舰上两件事:

  • 图书馆 (单位:千美元)@gdp-ts/core: name(), (中文(简体) ), defineProof(), (中文(简体) ), Named 财务报告和审定财务报表 Proof,没有依赖关系.
  • 电线 (单位:千美元)@gdp-ts/core/lint/eslint, (中文(简体) ), @gdp-ts/core/lint/oxlint:用于ESLint和Oxlint的预设,可以捕捉类型检查器无法捕捉的东西,例如用 as 或在外边铸造 proofs/ (单位:千美元)设置) (中文(简体) ).

技术

npx skills add rauchg/gdp-ts 安装指导编码代理的技能 通过应用代码库中的模式。 这是普通的马克下,所以它 作为人类参考手册的双倍:

实例

三个都使用同一个域名, 以Vercel的域名为模式 密码保护:团队管理员在一个项目上设置了密码,访客必须输入它才能打开项目受保护的URL.

  • basic从这里开始。 没有框架和内存数据,既涵盖团队一方(可能看到并改变设置),也涵盖访客一方(密码和信使),被印成情景. 包括 mistakes.ts,一个汇编错误的文件 测试套件保持诚实.
  • express-basic:球队侧过HTTP并有快车5号. 只认证的中端软件,命名和证明的路由,以及阻止被伪造的gdp-ts ESLint预设.
  • express-drizzle:在Postgres(PGlite)的进程中与Drizzle并列的两侧. 由 SQL 支持的证明加入,一个需要证明的数据层, cookie 范围到一个 URL, HTTP 测试, Oxlint 预设在 TypeScript 7上.

与其他解决办法的关系

  • 政策引擎 (CASL、Oso、Cerbos、许可证、OpenFGA、桑给巴尔式服务): 决定 是否一个主题可以对资源采取行动. gdp-ts 而不是:它确保决定到达取决于它的函数,关于正确的值。 你可以同时使用:在证明函数内调用引擎并返回证明. 见 examples/express-drizzle 对于"在证明功能之外" 与平原SQL的相像.
  • 品牌/名义类型 (单位:千美元)ts-brand效果 Brand,手工滚动 string & { __brand }:一个品牌说什么 类型 价值的东西是。 A 类 name() 帮助我们陈述 哪个 它的价值是。 标识使用品牌( U)食谱步骤1)并取名于上.
  • 验证库 (Zod, valibot, ArkType):他们证明了事实: 形状 在边缘的数据. gdp-ts 证明事实 关系 在特定值之间(这个符号,这个 URL),这是没有计划可以知道的.
  • 哈斯凯尔 gdp, (中文(简体) ), 锈 departed 编号 : mononym 编号 : gdp_rs:在语言中具有更强类型保证的同一种思想. gdp-ts 切实落实这些想法.

以前的艺术和信用

  • 马特·努南, justified-containers (2017) (中文(简体) )
  • 马特·努南, 离开的鬼魂 财务报告和审定财务报表 gdp (2018) (中文(简体) )
  • 奥利·查尔斯, 谁授权这些幽灵? (2019年)是这个项目的一大灵感.
  • 与Malte Ubl商谈我们大型的TypeScript monorepo的缩放安全,与数百名活跃的工程师+他们的代理商.

许可证

麻省理工学院

版本与发布记录

@gdp-ts/core 共发布 1 个版本,首次发布于 2026/10/05;过去 12 个月发布了 1 个版本。

版本发布日期距今
0.1.0latest2026/10/051 个月前

关于 @gdp-ts/core 的常见问题

@gdp-ts/core 是什么?

TypeScript的出走证明的"幽灵":授权(和其他检查),其结果类型检查者可以看到.

如何安装 @gdp-ts/core?

在项目目录运行 npm install @gdp-ts/core,或使用 pnpm add / yarn add / bun add。

@gdp-ts/core 支持 TypeScript 吗?

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

@gdp-ts/core 支持 ESM 还是 CommonJS?

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

@gdp-ts/core 可以商用吗?

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

@gdp-ts/core 的下载量有多少?

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

@gdp-ts/core 还在维护吗?

最新版本 0.1.0 发布于 2026/10/05(1 个月前);至今共发布 1 个版本,其中过去 12 个月发布了 1 个;首次发布于 2026/10/05。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。