@davidlee49/launchgate 0.0.0-stage → 0.5.1

package/README.md

@@ -1,3 +1,409 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# launchgate
+
+Hide work in progress from the public while you keep seeing it. Kill a shipped
+feature without a redeploy. No platform, no service, no database required.
+
+Design of record: [adr/0001-launch-gate-design.md](adr/0001-launch-gate-design.md).
+
+API reference, every export with its signature: [API.md](API.md).
+
+```ts
+import { defineFlags, createResolver, envOverride, cookieOverride, envDefault } from "@davidlee49/launchgate";
+
+export const flags = defineFlags({
+  newPricingPage: {
+    fallback: false,
+    description: "Rebuilt pricing page — hidden until launch",
+    overridable: true,
+    byEnv: { development: true },
+  },
+});
+
+export const gate = createResolver({
+  flags,
+  sources: [
+    envOverride(),                                  // 1. kill switch
+    cookieOverride({ secret: process.env.FLAG_SECRET! }), // 2. you, on the live site
+    envDefault({ env: process.env.NODE_ENV! }),     // 4. per-environment default
+  ],
+  onError: (error, { flag, source }) => console.error("launchgate", flag, source, error),
+});
+
+if (await gate.resolve("newPricingPage", { cookie })) { /* … */ }
+```
+
+## How resolution works
+
+An **ordered list of sources**; each answers with a value or `undefined`
+(*undecided — ask the next one*); the first definite answer wins. The flag's
+`fallback` is terminal, so it can't be forgotten.
+
+| # | Source | Purpose |
+| --- | --- | --- |
+| 0 | `retired` | Not a source. A retired flag answers with its recorded disposition and the chain never starts. |
+| 1 | `envOverride()` | `FLAG_NEW_PRICING_PAGE=off`. The kill switch. |
+| 2 | `cookieOverride({ secret })` | Signed per-visitor token — how you see hidden work in production. |
+| 3 | *yours* | Allowlist, grant, opt-in, entitlement. Usually a database read. |
+| 4 | `envDefault({ env })` | The registry's `byEnv` value. Preview deployments are just a different `env`. |
+| — | `fallback` | Terminal, always present. |
+
+`false` is a decision. `undefined` is not. That three-valued fall-through is the
+whole mechanic — and there is no traversal: no flag ever consults another flag.
+
+### Two invariants
+
+- **`envOverride` sits above `cookieOverride`.** A flag forced on by a cookie
+  must not survive the attempt to kill it.
+- **`cookieOverride` honours only `overridable: true` flags.** A visitor must
+  never force a flag with real consequences.
+
+### Failure is per flag, not global
+
+Every source call is wrapped. A source that throws **aborts to that flag's
+`fallback`** and reports through `onError` — it does not fall through, so there
+is exactly one degraded answer per flag and it's declared next to the flag.
+
+That value is per flag because polarity differs: a WIP gate's safe state is
+`false`, but a kill switch on a year-old feature's safe state is `true` — failing
+*that* one closed would take down working functionality because a database
+blipped.
+
+## Retiring a flag
+
+A release toggle is temporary by definition, and so is the feature behind it
+eventually. `retired` is the terminal state of both:
+
+```ts
+collections: {
+  fallback: true,
+  description: "Collections — retired 2026-08-29, code awaiting deletion",
+  retired: { since: "2026-08-29", value: false },
+},
+```
+
+It resolves to `value` and **consults no source at all** — not `envOverride`,
+which outranks everything else. That is the point rather than an optimisation: a
+retirement is a decision someone committed to git, so the only way to reverse it
+is to revert the commit. A forgotten `FLAG_COLLECTIONS=on` secret or an override
+cookie an engineer is still holding must not be able to reopen it, or the
+registry stops describing what the system actually does.
+
+Note `value` is *not* `fallback`. `fallback` is where a **failure** lands; a
+retirement isn't a failure, and a feature whose safe-on-failure state is `true`
+still retires to `false`. Declaring it separately is also the disposition record
+Unleash makes you supply when completing a flag — the cleanup PR needs to know
+which branch of the code survives, and `value: "v1"` on a dynamic-config flag
+says exactly that.
+
+**Keep the entry.** Retirement archives, it doesn't delete — Unleash's rule, for
+Unleash's reason: while the key is in the registry it cannot be reused by a new
+feature (a duplicate key is a type error), so a stale override can never attach
+to something it was never about. Delete the entry *last*, once the components,
+the routes, and the API handlers are gone.
+
+### The clock
+
+```ts
+const { problems, warnings } = auditRegistry(flags, { today, retiredAfterDays: 40 });
+```
+
+Retired code that nobody deletes is the same debt as a stale release flag, seen
+from the other end, so it gets the same 40-day budget. `auditRegistry` audits
+only what the library owns — the retirement shape and its age. Your own
+lifecycle vocabulary is yours to check; merge the two reports and print them
+together in one build step.
+
+This is deliberately a *build* step. LaunchDarkly ships `find-code-refs` to
+crawl a customer's repository, because a SaaS control plane can't see the code
+and can only warn on a dashboard. A registry that lives in the repo doesn't need
+the scanner: it can fail the build instead.
+
+## Flags aren't only booleans
+
+```ts
+renderPipeline: {
+  fallback: "v1" as "v1" | "v2",
+  description: "Which render pipeline a submitted job uses",
+}
+```
+
+`FLAG_RENDER_PIPELINE=v2` and cookie overrides carry the value. Booleans are the
+common case, not the only one.
+
+> **Typing note.** `fallback: false` is widened back to `boolean` for you.
+> Strings and numbers keep what you declare, which is why the `as "v1" | "v2"`
+> above gives you a checked union.
+
+## Custom sources
+
+A source is `{ name, decide(flag, ctx) }`. Return a value to decide, `undefined`
+to pass:
+
+```ts
+const orgGrant: Source = {
+  name: "orgGrant",
+  async decide({ key }, ctx) {
+    if (!ctx.targetingKey) return undefined;
+    const row = await db.grantFor(ctx.targetingKey, key);
+    return row?.enabled;         // undefined when there's no row — undecided
+  },
+};
+```
+
+Conjunctions ("entitled **and** opted in") are a *requirement* source: return the
+off-value, or `undefined` to stay out of the way. The chain stays first-wins.
+
+## Gating routes
+
+Flags answer "is this on". `createRouteGate` answers the question a web app
+actually asks — **"may this path be served"** — from two lists you supply:
+
+```ts
+const gate = createRouteGate({
+  resolver: launch,
+  routes: { workflows: ["/workflows"], network: ["/network", "/api/network"] },
+  allow:   ["/", "/assets", "/api/assets"],   // the launched surface
+  unlisted: "deny",
+});
+
+await gate.isPermitted("/workflows", { cookie });   // middleware
+await gate.revealedPrefixes({ cookie });            // to filter nav server-side
+```
+
+The allowlist is checked **first**, so a launched route short-circuits and
+resolves no flags at all.
+
+`unlisted` has no default, because it is the whole safety posture and the two
+answers fail very differently:
+
+- `"deny"` — a route added tomorrow is hidden until someone lists it. It 404s
+  loudly, and safely. Right for an app with unlaunched surfaces in the tree.
+- `"allow"` — a new route ships the moment it exists, and forgetting to flag
+  work in progress leaks it silently.
+
+A flag that is **off** denies its paths under either posture; `unlisted` only
+decides paths nothing has an opinion about.
+
+**It throws at construction** if a prefix is both allowed and flagged. That flag
+could never change anything — the allowlist would serve the path regardless — and
+a dead launch gate is precisely the bug you cannot afford to discover late.
+
+`matchesPrefix(pathname, prefixes)` is exported standalone for client-side nav
+filtering, so the menu can't disagree with the router.
+
+## Storage-backed flags
+
+For projects that want to flip a flag per tenant without a deploy. `subjectStore`
+owns the semantics; you own the SQL — any database, any client:
+
+```ts
+const store = subjectStore({
+  // One read for the whole registry. `load: async (subject, key) => …` is the
+  // per-flag alternative when a batch query is awkward.
+  loadAll: async (subject) => {
+    const rows = await db.overridesFor(subject);      // (subject_id, flag_key, override)
+    return Object.fromEntries(rows.map((r) => [r.flag_key, { override: r.override, optedIn: r.opted_in }]));
+  },
+  requiresOptIn: (flag) => flag.def.selfServe === true,
+});
+
+createResolver({
+  flags,
+  sources: [
+    envOverride(),
+    store.kill,           // 1. a 'disabled' row — outranks the cookie
+    cookieOverride({ secret }),
+    store.requireOptIn,   // 3a. veto anything the tenant hasn't switched on
+    store.grant,          // 3b. an 'enabled' row
+    envDefault({ env }),
+  ],
+});
+```
+
+Three sources, one storage read: they share a cache keyed on the `EvaluationContext`
+object, which is per request, so a request pays one `load` per flag no matter how
+many of the three are in the chain. Swap `load` for `loadAll` and the whole
+registry costs one read instead of one per flag — see **Bootstrapping a client** below.
+
+`'disabled'` and `'enabled'` are one row but two sources because they belong in
+**different slots** — a per-tenant kill has to outrank a visitor cookie for the
+same reason the env kill switch does, while a grant sits below it. `requireOptIn`
+sits ahead of `grant` because it must be able to veto an entitlement decided by a
+*later* source (a plan lookup, a stage rule) — a veto that runs after the
+decision it's vetoing never fires.
+
+Project-specific policy stays yours. Hang your own fields on a flag def (`stage`,
+`tier`, `owner`) and read them in your own source — the registry keeps their real
+types.
+
+> There is no `launchgate/postgres` subpath. Once the interface is a `load`
+> function, nothing Postgres-specific is left to ship.
+
+## Bootstrapping a client
+
+`resolveAll(ctx)` evaluates the whole registry at once — LaunchDarkly's
+`allFlagsState()` pattern. Resolve on the server, hand the map down, and the UI
+never flickers because it never had to ask:
+
+```ts
+const enabled = await gate.resolveAll(await requestContext({ targetingKey: orgId }));
+// → { newPricingPage: true, network: false, renderPipeline: "v2" }
+```
+
+Every flag shares the one context object, which is the cache key
+`subjectStore` uses — so with `loadAll` the whole registry costs **one** read.
+
+> Pass the **values**, never the registry. Flag keys name unshipped work, and a
+> viewer who can't see a surface shouldn't learn its name from the payload.
+
+## Testing
+
+```ts
+import { withFlags } from "@davidlee49/launchgate";
+
+const gate = withFlags(flags, { newPricingPage: true });
+```
+
+Answers from a fixed map, falls back for anything unset. Use it instead of
+standing up real sources — flags multiply a test matrix, and that's only
+tolerable if pinning a value is one line.
+
+## Minting an override token
+
+```ts
+import { signOverrides } from "@davidlee49/launchgate";
+
+const token = await signOverrides({ newPricingPage: true }, secret);
+// set it as the `lg_override` cookie
+```
+
+HMAC-SHA256 over Web Crypto, so the same build runs on Cloudflare Workers and
+Node 18+. Tampered or foreign-signed tokens are silently *undecided* — hostile
+input falls through the normal chain rather than pushing the flag anywhere.
+
+## What this deliberately isn't
+
+- **Not experimentation.** No assignment, no exposure logging, no metrics. At the
+  scale this is built for, statistical inference is noise with a dashboard.
+- **Not entitlements.** Those derive from a *contract*. Put billing truth in a
+  flag store and it has no transactional relationship to the subscription, so a
+  downgrade and a flag flip can disagree — and a stale-flag sweep deletes revenue
+  logic that looked like dead state. Supply an entitlement source instead.
+- **Not a circuit breaker.** Failing over to a backup provider is a machine
+  decision made in seconds from observed health; as a flag, a human has to notice
+  the outage first. A flag may say whether the alternative path is *permitted to
+  exist* — it must never *choose* it.
+
+> A flag records a decision a person made. A circuit breaker records a fact the
+> system observed.
+
+## Next.js
+
+```sh
+pnpm add @davidlee49/launchgate   # `next` is an optional peer dependency
+```
+
+```ts
+// app/flag-override/route.ts   ← NOT app/__flags/: see the trap below
+import { createOverrideRoute } from "@davidlee49/launchgate/next";
+import { gate } from "@/flags";
+
+export const { GET } = createOverrideRoute({
+  resolver: gate,
+  secret: process.env.FLAG_SECRET!,
+  accessToken: process.env.FLAG_ACCESS_TOKEN!,   // presented as ?token=, never the signing secret
+});
+```
+
+**If your app has an auth gate, exclude this route from it.** Inside the matcher
+it redirects to your login page and the cookie is never set — the mechanic
+silently does nothing. Its `?token=` is its authorization, and working logged-out
+is the point.
+
+Then `GET /flag-override?token=…&flag=newHomepage&value=on` sets the cookie,
+`&value=off` flips it, omitting `value` clears that flag, and `&clear=1` drops
+all of them. A wrong token gets a 404, not a 401 — an unadvertised route should
+stay unadvertised.
+
+Read a flag in a page or handler:
+
+```ts
+import { requestContext, requireFlag } from "@davidlee49/launchgate/next";
+
+const on = await gate.resolve("newHomepage", await requestContext());     // page
+const blocked = await requireFlag(gate, "network", { targetingKey: orgId }); // handler → 404
+```
+
+### Static rendering — measured, not guessed
+
+`requestContext()` calls `cookies()`, and that **opts the page into dynamic
+rendering**. Verified against Next 16.3.1 by reading `next build`'s route table:
+
+| Page | How it reads the flag | Build classification |
+| --- | --- | --- |
+| `/hidden` | `requestContext()` in the page | **ƒ Dynamic** |
+| `/home` → `/variants/v1`,`/v2` | proxy reads the cookie and rewrites | **○ Static** (all three) |
+
+- **Already-dynamic page** (anything authenticated): just call
+  `requestContext()`. The dynamic cost is already paid.
+- **Page that must stay static** (marketing, landing, docs): don't read the flag
+  in the page. Author the variants as separate routes and rewrite in `proxy.ts`:
+
+```ts
+// proxy.ts  (Next 16's rename of middleware.ts)
+import { NextResponse, type NextRequest } from "next/server";
+import { readOverrides } from "@davidlee49/launchgate";
+
+export async function proxy(request: NextRequest) {
+  const token = request.cookies.get("lg_override")?.value;
+  const overrides = token ? await readOverrides(token, process.env.FLAG_SECRET!) : undefined;
+  const variant = overrides?.newHomepage === true ? "v2" : "v1";
+  return NextResponse.rewrite(new URL(`/variants/${variant}`, request.url));
+}
+
+export const config = { matcher: "/home" };
+```
+
+There is no third option. Resolving in the proxy and forwarding a request header
+doesn't help: the page then calls `headers()`, which opts it into dynamic
+rendering just the same. Forwarding moves the read, not the cost.
+
+> **Trap.** A route handler under a `_`-prefixed directory — `app/__flags/route.ts`
+> — **never registers**. `_` marks a private folder in the App Router, excluded
+> from routing silently, with no build error and no 404 in the route table. Mount
+> the override route at a normal path.
+
+## Async work
+
+Resolve at submission and **stamp the value into the job payload**. A job
+enqueued Monday and run Wednesday must use Monday's value, or you get a job
+that's half one behaviour and half the other — and under a deterministic workflow
+engine, a replay failure. Downstream services get resolved values, not a flag
+client. Records produced by gated code should carry their own provenance rather
+than being re-interpreted through the current flag value.
+
+## Install
+
+```sh
+pnpm add @davidlee49/launchgate
+```
+
+Published to npm as a public package (scoped: the bare name `launchgate` is
+taken on the registry). The repo is private; the tarball is the built `dist/`.
+
+## Releasing
+
+1. Bump `version` in `package.json`.
+2. `pnpm publish` — `prepublishOnly` runs `pnpm check` (typecheck, tests, build),
+   so an unbuilt or failing tree never ships. `dist/` is not committed; the
+   registry holds it.
+3. `git tag vX.Y.Z && git push origin main vX.Y.Z`.
+4. Consumers bump the version range and `pnpm install`. A published version is
+   immutable: a fix is a new version, never a re-tag.
+
+## Development
+
+```sh
+pnpm install
+pnpm check     # tsc --noEmit && vitest run
+```

package/dist/chunk-YIOEKCH6.js

@@ -0,0 +1,98 @@
+// src/signing.ts
+var encoder = new TextEncoder();
+var decoder = new TextDecoder();
+function b64urlFromBytes(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function bytesFromB64url(value) {
+  const b64 = value.replace(/-/g, "+").replace(/_/g, "/");
+  const padded = b64 + "=".repeat((4 - b64.length % 4) % 4);
+  const binary = atob(padded);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) bytes[i] = binary.charCodeAt(i);
+  return bytes;
+}
+var keyCache = /* @__PURE__ */ new Map();
+async function hmacKey(secret) {
+  const cached = keyCache.get(secret);
+  if (cached) return cached;
+  const key = await crypto.subtle.importKey(
+    "raw",
+    encoder.encode(secret),
+    { name: "HMAC", hash: "SHA-256" },
+    false,
+    ["sign"]
+  );
+  keyCache.set(secret, key);
+  return key;
+}
+async function signature(payload, secret) {
+  const key = await hmacKey(secret);
+  const signed = await crypto.subtle.sign("HMAC", key, encoder.encode(payload));
+  return b64urlFromBytes(new Uint8Array(signed));
+}
+function timingSafeEqual(a, b) {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let i = 0; i < a.length; i++) diff |= a.charCodeAt(i) ^ b.charCodeAt(i);
+  return diff === 0;
+}
+function isFlagValue(value) {
+  return typeof value === "boolean" || typeof value === "string" || typeof value === "number" && Number.isFinite(value);
+}
+async function signOverrides(overrides, secret) {
+  const payload = b64urlFromBytes(encoder.encode(JSON.stringify(overrides)));
+  return `${payload}.${await signature(payload, secret)}`;
+}
+async function readOverrides(token, secret) {
+  const split = token.lastIndexOf(".");
+  if (split < 1) return void 0;
+  const payload = token.slice(0, split);
+  const provided = token.slice(split + 1);
+  let expected;
+  try {
+    expected = await signature(payload, secret);
+  } catch {
+    return void 0;
+  }
+  if (!timingSafeEqual(provided, expected)) return void 0;
+  try {
+    const parsed = JSON.parse(decoder.decode(bytesFromB64url(payload)));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+      return void 0;
+    }
+    const overrides = {};
+    for (const [key, value] of Object.entries(parsed)) {
+      if (isFlagValue(value)) overrides[key] = value;
+    }
+    return overrides;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/sources/cookie.ts
+var DEFAULT_OVERRIDE_COOKIE = "lg_override";
+function cookieOverride(options) {
+  const { secret } = options;
+  const cookieName = options.cookieName ?? DEFAULT_OVERRIDE_COOKIE;
+  return {
+    name: "cookieOverride",
+    async decide({ key, def }, ctx) {
+      if (!def.overridable) return void 0;
+      const token = ctx.cookie?.(cookieName);
+      if (!token) return void 0;
+      const overrides = await readOverrides(token, secret);
+      return overrides?.[key];
+    }
+  };
+}
+
+export {
+  signOverrides,
+  readOverrides,
+  DEFAULT_OVERRIDE_COOKIE,
+  cookieOverride
+};