常规
一个小 库+线条 财务报告和审定财务报表 人工智能技能 执行情况 离开的鬼魂 用于 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 安装指导编码代理的技能
通过应用代码库中的模式。 这是普通的马克下,所以它
作为人类参考手册的双倍:
- 工作流程: 增加或更改授权时应遵循的清单.
- 食谱:从有品牌的标识到出出彩规则,分六步走.
- 模式:免费削弱,带出证据的证明,再用证明,与授权无关的事实.
- 读取错误:编译器捕获到什么,以及每个消息的含义.
- 这不能保证: 伪造的证明, stale 证明,以及TypeScript的其他限制.
- 在哪里停下来:"易"作"易"作"易"作"易"作"易"作".
- API 密码: 万事俱备
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的缩放安全,与数百名活跃的工程师+他们的代理商.
许可证
麻省理工学院