gdp-ts
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chinesegdp-ts
gdp-ts
A sensitive function (one that reads or changes something only some callers
may touch) takes a proof about its exact arguments, so calling it without
the check, or with a check about a different value, does not compile.
- Name values. gives each value a compile-time-only name, valid inside the callback.
name(viewer.id, projectId, async (user, project) => ...) - Prove facts about names. A small trusted module in runs the check and returns a proof such as
proofs/, orUserIsProjectAdmin<U, P>. Only that module can mint it.null - Demand proofs. The sensitive function takes and
project: Named<P, ProjectId>. The wrong proof, a proof about another value, a raw id or no proof is a compile error._proof: UserIsProjectAdmin<U, P>
This is not a theorem prover. Prove the facts whose absence would be an
incident, and stop there (where to stop).
敏感函数(读取或修改某些调用方才有权操作的对象的函数)会接收一份针对其精确参数的 proof,因此,如果不进行该检查,或者使用针对其他值的检查来调用它,代码将无法通过编译。
- 为值命名。 为每个值赋予一个仅在编译期存在的名称,该名称在回调内有效。
name(viewer.id, projectId, async (user, project) => ...) - 证明关于名称的事实。 中的小型可信模块执行检查,并返回诸如
proofs/或UserIsProjectAdmin<U, P>的 proof。只有该模块可以签发此类 proof。null - 要求提供 proof。 敏感函数接收 和
project: Named<P, ProjectId>。错误的 proof、针对另一个值的 proof、原始 id 或缺少 proof,都会导致编译错误。_proof: UserIsProjectAdmin<U, P>
这不是定理证明器。只应证明那些一旦缺失就会引发事故的事实,并就此止步(何时停止)。
Workflow
工作流
When adding or changing authorization in a codebase that uses this pattern:
- Is the id branded? If not, brand it first.
- Is there a proof for the fact you need in ? If yes, reuse it. If no, add one file: private
proofs/, exporteddefineProof, exportedinterface X<...> extends Proof<"X", [...]> {}. Nothing else.async function x(...named): Promise<X<...> | null> - Does the sensitive function take proofs about its named arguments? If it takes raw ids, change the signature; let the compiler list the call sites to fix.
- Does the request carry other values the operation trusts (a token in a
cookie, an id in the body)? Check them in a trusted module against the
resource they claim to unlock (). This is where cross-resource and cross-tenant bugs live.
TokenUnlocksUrl<H> - Are there non-user preconditions (plan, scope, state)? Make them proofs
too ().
PlanIncludesPasswordProtection<P> - In the handler body (not middleware): , call the policy function, turn
name(...)into the right HTTP response, do all sensitive work inside the callback. If that block will likely be called from many places, consider moving it into a shared function (recipe step 5).null - Never write to satisfy a proof or
astype. If you feel the need, the signature is wrong or you are outsideNamed. If the codebase has no gdp-ts lint preset yet, add it (recipe step 6); if it does, fix lint errors rather than disabling them.proofs/ - Never export a prover, never call outside
defineProof, never return aproofs/, or a proof that mentions that callback's names, from aNamedcallback.name() - Add the new mistake you almost made to (a type-checked file that never runs) as one line under
mistakes.ts. It is the cheapest regression test you will write (details).// @ts-expect-error - Test the proof function you added. It is the only thing that can be wrong at runtime.
The recipe shows each step in full.
在使用此模式的代码库中新增或修改授权时:
- 该 id 是否已品牌化?如果没有,先为其添加品牌类型。
- 中是否已有证明所需事实的 proof?如果有,复用。如果没有,只新增一个文件:模块私有的
proofs/、导出的defineProof、导出的interface X<...> extends Proof<"X", [...]> {}。不要做其他事情。async function x(...named): Promise<X<...> | null> - 敏感函数是否接收关于其具名参数的 proof?如果仍接收原始 id,则修改函数签名;让编译器列出需要修复的调用位置。
- 请求是否携带操作所信任的其他值(cookie 中的 token、请求体中的 id)?应在可信模块中,将这些值与其声称要解锁的资源进行核对()。跨资源和跨租户漏洞往往出现在这里。
TokenUnlocksUrl<H> - 是否存在与用户无关的前置条件(套餐、scope、状态)?也应将其定义为 proof()。
PlanIncludesPasswordProtection<P> - 在 handler 主体中(而非 middleware 中):调用 ,调用 policy 函数,将
name(...)转为正确的 HTTP 响应,并在回调内完成所有敏感操作。如果该代码块很可能从许多位置调用,可考虑将其移入共享函数(配方第 5 步)。null - 绝不要编写 来强行满足 proof 或
as类型。如果你觉得有必要这样做,说明函数签名有误,或者当前代码不在Named中。如果代码库尚无 gdp-ts lint preset,请添加它(配方第 6 步);如果已有,则应修复 lint 错误,而不是禁用它们。proofs/ - 绝不要导出 prover,绝不要在 之外调用
proofs/,也绝不要从defineProof回调中返回name(),或返回提及该回调名称的 proof。Named - 将你差点犯下的新错误添加到 (一个经过类型检查但永不运行的文件)中,作为
mistakes.ts下的一行。这是你能写出的成本最低的回归测试(详情)。// @ts-expect-error - 测试新增的 proof 函数。它是唯一可能在运行时出错的部分。
配方完整展示了每个步骤。
References
参考
Read the one you need:
| File | Read it when |
|---|---|
| Adding a proof, a policy or a sensitive function, or adopting the pattern. Six steps: brand ids, trusted modules, policies as unions, sensitive functions, naming in the handler, lint rules. |
| Reusing proofs, weaker-from-stronger proofs, proofs that carry evidence, preconditions that are not about users. |
| A type error mentions |
| Judging what the types do and do not guarantee (forging, stale proofs, older TypeScript). |
| Deciding how much to prove. |
按需阅读以下文档:
| 文件 | 阅读时机 |
|---|---|
| 添加 proof、policy 或敏感函数,或引入该模式时。包含六个步骤:品牌化 id、可信模块、将策略建模为联合类型、敏感函数、在 handler 中命名、lint 规则。 |
| 复用 proof、从更强 proof 推导更弱 proof、携带证据的 proof、与用户无关的前置条件。 |
| 类型错误提及 |
| 判断类型能够和不能保证什么(伪造、过期 proof、较旧 TypeScript)。 |
| 确定需要证明多少内容。 |
API
API
Everything is exported from .
@gdp-ts/core| Export | What it is |
|---|---|
| A value of type |
| Gives one to three values fresh names, scoped to |
| Evidence that fact |
| Returns a |
| The |
| The names of a tuple of |
Lint presets, for the gaps the type system cannot close (recipe step 6):
| Import | What it is |
|---|---|
| |
| |
| The rules themselves ( |
Options: (trusted-module globs, default ),
(also ban every and outside them, default ),
(strict-mode exceptions, default ),
and .
proofs**/proofs/**strictasanyfalseallowAssertions**/lib/ids.tsproofImportsfilesThe only place the library asserts a proof type is inside , so code
using it never needs to. The runtime footprint is one frozen object per call;
returns that same object every time, and wraps each value in a
frozen .
prove{ kind }defineProofprovename{ value }所有内容均从 导出。
@gdp-ts/core| 导出项 | 用途 |
|---|---|
| 类型为 |
| 为一个至三个值赋予全新名称,名称作用域限定为 |
| 表明事实 |
| 返回 |
| |
| |
Lint preset 用于弥补类型系统无法封闭的缺口(配方第 6 步):
| 导入项 | 用途 |
|---|---|
| |
| |
| 规则本身( |
选项包括:(可信模块的 glob 模式,默认值为 )、(同时禁止在这些模块之外使用所有 和 ,默认值为 )、(strict 模式下的例外,默认值为 )、 和 。
proofs**/proofs/**strictasanyfalseallowAssertions**/lib/ids.tsproofImportsfiles该库唯一断言 proof 类型的地方是在 内部,因此使用该库的代码永远不需要进行此类断言。运行时开销仅为每次 调用生成一个冻结的 对象; 每次都返回同一个对象,而 会将每个值包装在冻结的 中。
provedefineProof{ kind }provename{ value }