@gdp-ts/core weekly downloads statistics

gdp-ts

A tiny library + linter and AI skill implementation of Ghosts of Departed Proofs for TypeScript, a verification system to make API contracts more secure at compile (type check) time.

gdp-ts makes an entire category of authorization (_"can this user read this resource"_) or entitlement (_"does this user pay for this resource"_) bugs very difficult for humans and coding agents to introduce, by catching them at compile time with negligible runtime overhead.

Features

• Incrementally adoptable: works with any TS codebase and any runtime, and doesn't change how you do I/O or effects. • Ease-to-rigor slider: how much is exhaustively proven is up to the discretion / risk tolerance of each codebase, and the skill bundles advice. • ~Zero runtime overhead: no extra queries or dependencies. The only runtime cost is a tiny wrapper around the ids you check. The safety comes from type checker. • Cheap to typecheck: about 0.3 ms per authorized call site on a cold TypeScript 7 check. The cost grows with how often you use it, not with codebase size (benchmark).

Installation

Requires TypeScript 5.4 or newer.

The problem

A lot of codebases feature code like this:

Looks great, except: all it takes is • a developer to slip and miss the first await • the business rules on who gets to "change password protection" to change (say, Owners only), and one call site to keep running the old check

... for a security / business disaster to occur.

The solution

We change the signature above from something anyone can call from anywhere:

...to forcing the caller to present evidence (proof) that they can do (are admin) and can get (have the plan) the thing:

The skill takes care of guiding agents and humans towards this safer pattern, and away from the *boolean blindness* problem.

How it works

1️⃣ Name values. name(x, k) gives a runtime value a compile-time-only name N. Every call to name creates a different N, and N exists only inside the callback. For our example, wwo project ids named separately are now distinguishable to the compiler even though both are string:

2️⃣ Prove facts about names. A small *trusted module* performs a check and returns a Proof, or null. Only that module can mint that proof. At runtime a proof is a frozen { kind } object.

3️⃣ Demand proofs. Sensitive functions take a proof about their exact arguments. Calling them with the wrong proof, a proof about a different value, a raw id, or no proof is a compile error 🎉

TL;DR: • Middleware only authenticates. The check happens in the route body, right where its result is needed, and disablePasswordProtection does not compile without it. • Because the data layer *demands* a proof instead of performing the check, it is safe to export: a route, a Server Action or a job can call it, and none of them can skip the check. • The proofs are *ghosts*: they do nothing at runtime, and everything at compile time. We rely on linting to prevent "cheating" (e.g: {} as UserIsProjectAdmin).

The package

@gdp-ts/core on npm ships two things:

• The library (@gdp-ts/core): name(), defineProof(), Named and Proof, with no dependencies. • The linter (@gdp-ts/core/lint/eslint, @gdp-ts/core/lint/oxlint): presets for ESLint and Oxlint that catch what the type checker can't, such as forging a proof with as or minting one outside proofs/ (setup).

The skill

npx skills add rauchg/gdp-ts installs a skill that guides coding agents through applying the pattern in your codebase. It is plain Markdown, so it doubles as the reference manual for humans:

• Workflow: the checklist to follow when adding or changing authorization. • The recipe: from branded ids to lint rules, in six steps. 1. Brand your ids 2. One trusted module per fact, in proofs/ 3. Policies are unions 4. Sensitive functions demand proofs 5. Name and prove in the handler 6. Turn on the lint preset • Patterns: weakening for free, proofs that carry evidence, reusing proofs, facts that are not about authorization. • Reading the errors: what the compiler catches, and what each message means. • What this does not guarantee: forged proofs, stale proofs, and other limits of TypeScript. • Where to stop: the ease-to-rigor slider. • API: everything gdp-ts exports.

Examples

All three use the same domain, loosely modeled after Vercel's Password Protection: team admins set a password on a project, and visitors must enter it to open the project's protected URLs.

• basic: start here. No framework and in-memory data, covering both the team side (who may see and change the setting) and the visitor side (passwords and tokens), printed as scenarios. Includes mistakes.ts, a file of compile errors the test suite keeps honest. • express-basic: the team side over HTTP with Express 5. Middleware that only authenticates, routes that name and prove, and the gdp-ts ESLint preset that stops proofs from being forged. • express-drizzle: both sides with Drizzle on an in-process Postgres (PGlite). Proofs backed by SQL joins, a data layer that demands proofs, cookies scoped to one URL, HTTP tests, and the Oxlint preset on TypeScript 7.

Relationship to other solutions…

Description from the npm listing.