@suluk/keys 0.1.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@suluk/keys",
+  "version": "0.1.0",
+  "description": "The delegation-chain ALGEBRA for hierarchical API keys: effective-caps (scope ∩, cap/expiry min up the chain), POOLED subtree headroom (a parent cap bounds parent+children TOTAL spend — abuse-proof), the cascade read-checks (expired/disabled ancestor), child-grant clamping, the materialized-path utilities, and the scope/metadata model. Pure + portable: the app supplies the chain rows + spend (its DB query is the seam); this owns the money/abuse-correctness logic. Extracted from a real app (C046). CANDIDATE tooling.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MahmoodKhalil57/suluk.git",
+    "directory": "tooling/ts/packages/keys"
+  },
+  "homepage": "https://github.com/MahmoodKhalil57/suluk#readme",
+  "bugs": "https://github.com/MahmoodKhalil57/suluk/issues",
+  "type": "module",
+  "main": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@suluk/better-auth": "^0.1.3",
+    "@suluk/credits": "^0.1.0",
+    "drizzle-orm": "^0.45.2"
+  },
+  "devDependencies": {
+    "@types/bun": "latest"
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit -p ."
+  }
+}

package/src/chain.ts

@@ -0,0 +1,122 @@
+/**
+ * The delegation-chain ALGEBRA (C046) — the money/abuse-correctness logic, pure and portable. A caller's chain is itself
+ * (last) + its ancestors (root→parent), each a {@link ChainNode} with its OWN granted scopes + caps + expiry. The four
+ * rules that keep a child from ever out-scoping or out-spending an ancestor:
+ *   • effectiveCaps  — scopes = ∩ up the chain, credit-cap/rate-share/expiry = the MIN (soonest) of the declared ones.
+ *   • pooledHeadroom — a node's cap bounds its WHOLE subtree's total spend (pooling = the abuse-proof property).
+ *   • expired/disabledAncestor — a child dies the moment a parent up the chain expires or is revoked (the read-time cascade).
+ *   • clampChildGrant — a freshly-minted child is clamped to the parent's effective grant.
+ * The app supplies the rows (its DB query is the seam); this owns the algebra. Extracted verbatim from the source.
+ */
+import { inSubtree } from "./path";
+
+/** One node of a caller's chain — itself or an ancestor — with its OWN (pre-chain) grant + caps + its materialized path. */
+export interface ChainNode {
+  keyId: string;
+  /** the node's own materialized path (a prefix of the caller's) — used to sum its subtree spend. */
+  path: string;
+  /** the node's OWN granted tool scopes (an unrestricted account-root never appears as a node). */
+  scopes: string[];
+  ownCreditLimit: number | null;
+  ownRateSharePct: number | null;
+  /** epoch ms — the node's own expiry; null = never. */
+  ownExpiresAt: number | null;
+  /** an ancestor soft-disabled (enabled=false) — drives the auth-time revocation cascade. */
+  disabled?: boolean;
+}
+
+export interface EffectiveCaps {
+  scopes: string[];
+  creditLimit: number | null;
+  rateLimitSharePct: number | null;
+  expiresAt: number | null;
+}
+
+/** The caller's EFFECTIVE grant, derived by walking UP the chain. Scopes = the intersection of every node's grant; the
+ *  credit cap + rate share + expiry = the MIN (soonest) of the declared (non-null) ones. The depth-0 identity for a plain
+ *  root key (one node → its own values), so single-key behaviour is preserved. */
+export function effectiveCaps(chain: ChainNode[]): EffectiveCaps {
+  let scopes: string[] | null = null;
+  for (const n of chain) scopes = scopes == null ? [...n.scopes] : scopes.filter((s) => n.scopes.includes(s));
+  const limits = chain.map((n) => n.ownCreditLimit).filter((x): x is number => x != null);
+  const shares = chain.map((n) => n.ownRateSharePct).filter((x): x is number => x != null);
+  const expiries = chain.map((n) => n.ownExpiresAt).filter((x): x is number => x != null);
+  return {
+    scopes: scopes ?? [],
+    creditLimit: limits.length ? Math.min(...limits) : null,
+    rateLimitSharePct: shares.length ? Math.min(...shares) : null,
+    expiresAt: expiries.length ? Math.min(...expiries) : null, // soonest up the chain — a child can't outlive any ancestor
+  };
+}
+
+/** TRUE when any ANCESTOR (a node other than the caller) has already expired — so the caller auto-expires the moment a
+ *  parent does. The caller's OWN expiry is enforced upstream (the token verify rejects it), so it's excluded. */
+export function expiredAncestor(chain: ChainNode[], callerKeyId: string, now: number): boolean {
+  return chain.some((n) => n.keyId !== callerKeyId && n.ownExpiresAt != null && n.ownExpiresAt <= now);
+}
+
+/** TRUE when any ANCESTOR has been soft-disabled — so a child auto-dies the moment a parent is revoked, EVEN when the
+ *  revocation didn't cascade through the write path. The read-time half of the cascade. The caller's OWN disable is
+ *  enforced upstream, so it's excluded. */
+export function disabledAncestor(chain: ChainNode[], callerKeyId: string): boolean {
+  return chain.some((n) => n.keyId !== callerKeyId && n.disabled === true);
+}
+
+/** One row of per-path spend (a positive amount), as the app's subtree query returns it. */
+export interface SpendRow {
+  path: string;
+  spent: number;
+}
+
+export interface Headroom {
+  limit: number;
+  spent: number;
+  remaining: number;
+}
+
+/**
+ * The chain's POOLED credit headroom — the BINDING constraint a charge must clear: over every node that declares an own
+ * cap, the LEAST `cap − subtreeSpend(node)` (a node's subtree = itself ∪ descendants). Pooling is what makes a cap
+ * abuse-proof: a parent capped at 50 can't mint children to spend 50 each, because every child's spend lands in the
+ * parent's subtree. The app fetches `spendRows` (per-path spend over the topmost capped node's subtree — one grouped
+ * query); this sums per node in O(nodes × rows). Returns null when no node declares a cap (uncapped — only the balance gates).
+ */
+export function pooledHeadroom(chain: ChainNode[], spendRows: readonly SpendRow[]): Headroom | null {
+  const capped = chain.filter((n): n is ChainNode & { ownCreditLimit: number } => n.ownCreditLimit != null);
+  if (capped.length === 0) return null;
+  let binding: Headroom | null = null;
+  for (const node of capped) {
+    let spent = 0;
+    for (const r of spendRows) if (inSubtree(node.path, r.path)) spent += Number(r.spent);
+    const remaining = node.ownCreditLimit - spent;
+    if (binding === null || remaining < binding.remaining) binding = { limit: node.ownCreditLimit, spent, remaining };
+  }
+  return binding;
+}
+
+/** The topmost capped node in a chain (the shortest path) — whose subtree contains every other capped node's subtree, so
+ *  one query over it suffices for {@link pooledHeadroom}. Null when no node declares a cap. */
+export function topCappedPath(chain: ChainNode[]): string | null {
+  const capped = chain.filter((n) => n.ownCreditLimit != null);
+  if (!capped.length) return null;
+  return capped.reduce((a, b) => (a.path.split("/").length <= b.path.split("/").length ? a : b)).path;
+}
+
+/** Clamp a requested CHILD grant to the parent's EFFECTIVE grant — a child can never out-scope or out-spend an ancestor.
+ *  scopes ⊆ parent's; each cap/expiry = min(requested ?? ∞, parent ?? ∞) (null only when BOTH are unbounded). Pure. */
+export function clampChildGrant(
+  parent: EffectiveCaps,
+  requested: { scopes: string[]; creditLimit?: number | null; rateLimitSharePct?: number | null; expiresAt?: number | null },
+): EffectiveCaps {
+  const minOrNull = (a: number | null | undefined, b: number | null): number | null => {
+    const xs = [a, b].filter((x): x is number => typeof x === "number");
+    return xs.length ? Math.min(...xs) : null;
+  };
+  return {
+    scopes: requested.scopes.filter((s) => parent.scopes.includes(s)),
+    creditLimit: minOrNull(requested.creditLimit, parent.creditLimit),
+    rateLimitSharePct: minOrNull(requested.rateLimitSharePct, parent.rateLimitSharePct),
+    // a child that asks for no/longer expiry INHERITS the parent's (min of one finite + ∞ = the finite one).
+    expiresAt: minOrNull(requested.expiresAt, parent.expiresAt),
+  };
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * @suluk/keys — the delegation-chain ALGEBRA for hierarchical API keys (C046, extracted from a real app).
+ *
+ * The app builds a `ChainNode[]` (a caller + its ancestors) and per-path `SpendRow[]` from its OWN store — the DB query
+ * is the seam (a Drizzle reference adapter is a follow-on, deferred per C046) — then calls these PURE functions for the
+ * money/abuse-correctness logic so it can never drift:
+ *   • effectiveCaps   — scope ∩, credit-cap/rate-share/expiry min up the chain (a child can't out-scope/out-spend a parent)
+ *   • pooledHeadroom  — a node's cap bounds its WHOLE subtree's total spend (the abuse-proof property)
+ *   • expired/disabledAncestor — the read-time revocation/expiry cascade
+ *   • clampChildGrant — clamp a minted child to the parent's effective grant
+ * plus the materialized-path utilities and the scope/metadata model.
+ */
+export {
+  type ChainNode, type EffectiveCaps, type SpendRow, type Headroom,
+  effectiveCaps, expiredAncestor, disabledAncestor, pooledHeadroom, topCappedPath, clampChildGrant,
+} from "./chain";
+export { MAX_KEY_DEPTH, escapeLike, subtreeLikePattern, inSubtree, childPath, pathDepth, ancestorIdsOf, pathAt } from "./path";
+export { parseScopes, parseKeyMeta } from "./scopes";
+// the lineage-tree DB ops (over an injected Drizzle handle) + the pooled-headroom query that joins @suluk/credits.
+export { type KeysDB, keyLineage, subtreeOf, parentPathOf, insertLineage, chainHeadroom, revokeKeyTree } from "./lineage";

package/src/lineage.ts

@@ -0,0 +1,96 @@
+/**
+ * The lineage-tree DB ops (C046) — the materialized-path queries over a key delegation tree, plus the POOLED headroom
+ * query that joins the credit ledger (where @suluk/keys meets @suluk/credits). The package OWNS the `key_lineage` schema;
+ * the app injects a Drizzle handle. The grant-fetch that builds a ChainNode[] is app-specific (apikey vs MCP tables), so
+ * it stays in the app and calls the pure algebra (chain.ts); these are the generic, table-owned operations. Extracted
+ * verbatim from the source.
+ */
+import { and, eq, lt, sql } from "drizzle-orm";
+import type { DrizzleD1Database } from "drizzle-orm/d1";
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+import { creditKey, creditTransaction } from "@suluk/credits";
+import { type ChainNode, type Headroom, pooledHeadroom, topCappedPath } from "./chain";
+import { subtreeLikePattern } from "./path";
+
+/** The injected DB handle (drizzle/d1 in prod; bun:sqlite bridged in tests). */
+export type KeysDB = DrizzleD1Database;
+
+/** The delegation tree: each node's parent + a materialized `path` of keyIds (root→…→self). `userId`/`keyId` are plain
+ *  columns (the app owns the user + apikey tables); `keyId` is the SAME string as `credit_key.keyId`. */
+export const keyLineage = sqliteTable("key_lineage", {
+  keyId: text("keyId").primaryKey(),
+  parentKeyId: text("parentKeyId"),
+  userId: text("userId").notNull(),
+  path: text("path").notNull(),
+  depth: integer("depth").notNull(),
+});
+
+/** SQL: "`key_lineage.path` is within <path>'s subtree" — self (exact) OR a descendant (escaped LIKE prefix). */
+const subtreeSql = (path: string) => sql`(${keyLineage.path} = ${path} OR ${keyLineage.path} LIKE ${subtreeLikePattern(path)} ESCAPE '\\')`;
+
+/** The keyIds in a node's subtree (itself + every descendant) — for cascade revoke. Falls back to `[keyId]` for a
+ *  legacy caller with no lineage row (a childless root). */
+export async function subtreeOf(db: KeysDB, keyId: string): Promise<string[]> {
+  const self = await db.select({ path: keyLineage.path }).from(keyLineage).where(eq(keyLineage.keyId, keyId)).limit(1);
+  const path = self[0]?.path ?? keyId;
+  const rows = await db.select({ keyId: keyLineage.keyId }).from(keyLineage).where(subtreeSql(path));
+  const ids = rows.map((r) => r.keyId);
+  return ids.length ? ids : [keyId];
+}
+
+/** A parent's materialized path (for building a child's path). A parent with no row is a root → its bare id; a null
+ *  parent (a session/account caller) → null (the child is a root). */
+export async function parentPathOf(db: KeysDB, parentKeyId: string | null): Promise<string | null> {
+  if (parentKeyId == null) return null;
+  const rows = await db.select({ path: keyLineage.path }).from(keyLineage).where(eq(keyLineage.keyId, parentKeyId)).limit(1);
+  return rows[0]?.path ?? parentKeyId;
+}
+
+/** Record a freshly-minted child (or root, when parentKeyId is null) in the lineage tree. Idempotent on the keyId PK. */
+export async function insertLineage(db: KeysDB, opts: { keyId: string; parentKeyId: string | null; userId: string; parentPath: string | null }): Promise<void> {
+  const path = opts.parentPath ? `${opts.parentPath}/${opts.keyId}` : opts.keyId;
+  const depth = path.split("/").length - 1;
+  await db.insert(keyLineage).values({ keyId: opts.keyId, parentKeyId: opts.parentKeyId, userId: opts.userId, path, depth }).onConflictDoNothing().run();
+}
+
+/**
+ * The chain's POOLED credit headroom — one grouped query over the TOPMOST capped node's subtree (joining the credit
+ * ledger via the `credit_key` sidecar), then {@link pooledHeadroom}. This is where the abuse-proof cap becomes real: a
+ * parent's cap bounds its whole subtree's spend. Null when no node in the chain declares a cap (uncapped).
+ */
+export async function chainHeadroom(db: KeysDB, chain: ChainNode[]): Promise<Headroom | null> {
+  const top = topCappedPath(chain);
+  if (top == null) return null;
+  const rows = await db
+    .select({ path: keyLineage.path, spent: sql<number>`coalesce(sum(-${creditTransaction.delta}), 0)` })
+    .from(keyLineage)
+    .innerJoin(creditKey, eq(creditKey.keyId, keyLineage.keyId))
+    .innerJoin(creditTransaction, eq(creditTransaction.id, creditKey.txnId))
+    .where(and(subtreeSql(top), lt(creditTransaction.delta, 0)))
+    .groupBy(keyLineage.path);
+  return pooledHeadroom(chain, rows.map((r) => ({ path: r.path, spent: Number(r.spent) })));
+}
+
+/**
+ * Cascade-revoke a key's subtree: compute the api-key ids in `keyId`'s subtree (a keyed caller may revoke ONLY a STRICT
+ * descendant of itself — not itself, an ancestor, or another branch) and soft-disable them via the injected `disableKeys`
+ * (the app's apikey update — so @suluk/keys stays free of the Better Auth apikey table). MCP ids are skipped (a
+ * connection is revoked elsewhere). Returns the count disabled.
+ */
+export async function revokeKeyTree(
+  db: KeysDB,
+  opts: { userId: string; keyId: string; callerKeyId?: string },
+  disableKeys: (userId: string, keyIds: string[]) => Promise<number>,
+): Promise<{ revoked: number }> {
+  if (opts.callerKeyId != null) {
+    const callerRow = await db.select({ path: keyLineage.path }).from(keyLineage).where(eq(keyLineage.keyId, opts.callerKeyId)).limit(1);
+    const callerPath = callerRow[0]?.path ?? opts.callerKeyId;
+    const targetRow = await db.select({ path: keyLineage.path }).from(keyLineage).where(eq(keyLineage.keyId, opts.keyId)).limit(1);
+    const targetPath = targetRow[0]?.path;
+    // the target must be a STRICT descendant of the caller (its path extends the caller's by ≥1 segment)
+    if (targetPath == null || !targetPath.startsWith(callerPath + "/")) return { revoked: 0 };
+  }
+  const ids = (await subtreeOf(db, opts.keyId)).filter((id) => !id.startsWith("mcp:")); // only api-keys are disable-able
+  if (ids.length === 0) return { revoked: 0 };
+  return { revoked: await disableKeys(opts.userId, ids) };
+}

package/src/path.ts

@@ -0,0 +1,32 @@
+/**
+ * Materialized-path utilities for a key delegation tree (C046). A node's `path` is its keyIds root→…→self joined by "/".
+ * That makes every chain/subtree question recursion-free: ancestors = the ids before self; descendants = a "/"-prefix
+ * match. Pure — the app owns the storage; this owns the shape. Extracted verbatim from the source's key-lineage logic.
+ */
+
+/** A delegation chain can be at most this deep (root..leaf) — bounds the path length + the per-request walk. */
+export const MAX_KEY_DEPTH = 8;
+
+/** Escape SQL-LIKE metacharacters (a keyId can contain `_`, a LIKE wildcard) so a path prefix matches LITERALLY — pair
+ *  with `ESCAPE '\'` in the query. Without this, a sibling whose id shares a `_`-adjacent prefix could leak into a
+ *  subtree match. */
+export const escapeLike = (s: string): string => s.replace(/[\\%_]/g, (c) => `\\${c}`);
+
+/** The `LIKE` pattern for "<path>'s strict descendants" — pair with `ESCAPE '\'`. (The node itself is matched by `= path`.) */
+export const subtreeLikePattern = (path: string): string => `${escapeLike(path)}/%`;
+
+/** TRUE when `candidate` is within `path`'s subtree: the node itself (exact) OR a descendant (a "/"-prefix). The JS twin
+ *  of the SQL subtree predicate — the single rule for spend pooling, log visibility, and cascade. */
+export const inSubtree = (path: string, candidate: string): boolean => candidate === path || candidate.startsWith(path + "/");
+
+/** A child's path = `parentPath/childId`, or the bare `childId` when the parent is a root (no path / a session caller). */
+export const childPath = (parentPath: string | null | undefined, childId: string): string => (parentPath ? `${parentPath}/${childId}` : childId);
+
+/** Depth of a path: 0 = root, >0 = a delegated child. */
+export const pathDepth = (path: string): number => path.split("/").length - 1;
+
+/** The ancestor keyIds in a path (everything before self), root→parent order. */
+export const ancestorIdsOf = (path: string): string[] => path.split("/").slice(0, -1);
+
+/** The own-path of the ancestor at index `i` in a path's segments (the prefix up to and including it). */
+export const pathAt = (path: string, i: number): string => path.split("/").slice(0, i + 1).join("/");

package/src/scopes.ts

@@ -0,0 +1,46 @@
+/**
+ * The key permission/metadata model (C046) — pure, defensive parsing of what a key carries: its permissions JSON
+ * (`{resource:[actions]}` → flat `["resource:action"]` scopes, via @suluk/better-auth) and its metadata (the per-key
+ * PAID credit cap + the rate-limit share %). A bad/absent value reads as "no scopes" / "no override" — never throws.
+ * Extracted verbatim from the source.
+ */
+import { permissionsToScopes } from "@suluk/better-auth";
+
+/** permissions JSON (`{resource:[actions]}`) → flat `["resource:action"]` scopes, defensively (a bad value → no scopes). */
+export const parseScopes = (permissions: string | null): string[] => {
+  if (!permissions) return [];
+  try {
+    const parsed: unknown = JSON.parse(permissions);
+    if (typeof parsed !== "object" || parsed === null) return [];
+    const perms: Record<string, string[]> = {};
+    for (const [k, v] of Object.entries(parsed)) if (Array.isArray(v)) perms[k] = v.filter((x): x is string => typeof x === "string");
+    return permissionsToScopes(perms);
+  } catch {
+    return [];
+  }
+};
+
+/** metadata JSON → the per-key controls (each null when absent/invalid): the PAID credit cap + the rate-limit share %.
+ *  Defensive — a bad value reads as "no override"; the share is clamped to [1,100] to mirror the auth-time clamp. */
+export function parseKeyMeta(metadata: string | null): { creditLimit: number | null; rateLimitSharePct: number | null } {
+  let creditLimit: number | null = null;
+  let rateLimitSharePct: number | null = null;
+  if (metadata) {
+    try {
+      const parsed: unknown = JSON.parse(metadata);
+      if (typeof parsed === "object" && parsed !== null) {
+        if ("creditLimit" in parsed) {
+          const n = Number((parsed as Record<string, unknown>).creditLimit);
+          if (Number.isFinite(n)) creditLimit = n;
+        }
+        if ("rateLimitSharePct" in parsed) {
+          const n = Number((parsed as Record<string, unknown>).rateLimitSharePct);
+          if (Number.isFinite(n)) rateLimitSharePct = Math.min(100, Math.max(1, Math.round(n)));
+        }
+      }
+    } catch {
+      /* bad value → no override */
+    }
+  }
+  return { creditLimit, rateLimitSharePct };
+}

package/test/chain.test.ts

@@ -0,0 +1,81 @@
+import { test, expect, describe } from "bun:test";
+import { effectiveCaps, expiredAncestor, disabledAncestor, pooledHeadroom, topCappedPath, clampChildGrant, type ChainNode } from "../src/index";
+
+/**
+ * C046 — the delegation-chain algebra (money/abuse-correctness). The pooledHeadroom test is load-bearing: a parent cap
+ * must bound the parent + ALL descendants' TOTAL spend, so a key can't multiply its budget by minting children.
+ */
+const node = (over: Partial<ChainNode> & { keyId: string; path: string }): ChainNode => ({ scopes: [], ownCreditLimit: null, ownRateSharePct: null, ownExpiresAt: null, ...over });
+
+describe("effectiveCaps — ∩ scopes, min caps/expiry up the chain", () => {
+  test("scopes intersect; caps + expiry take the min (soonest)", () => {
+    const chain = [
+      node({ keyId: "root", path: "root", scopes: ["a", "b", "c"], ownCreditLimit: 100, ownRateSharePct: 100, ownExpiresAt: 5000 }),
+      node({ keyId: "child", path: "root/child", scopes: ["a", "b"], ownCreditLimit: 40, ownRateSharePct: 50, ownExpiresAt: 3000 }),
+    ];
+    expect(effectiveCaps(chain)).toEqual({ scopes: ["a", "b"], creditLimit: 40, rateLimitSharePct: 50, expiresAt: 3000 });
+  });
+
+  test("a lone root key is the depth-0 identity (its own values)", () => {
+    const root = node({ keyId: "r", path: "r", scopes: ["x"], ownCreditLimit: 10, ownRateSharePct: null, ownExpiresAt: null });
+    expect(effectiveCaps([root])).toEqual({ scopes: ["x"], creditLimit: 10, rateLimitSharePct: null, expiresAt: null });
+  });
+
+  test("an unrestricted ancestor (no scopes node) does not appear; a node with [] scopes intersects to empty", () => {
+    const chain = [node({ keyId: "p", path: "p", scopes: ["a"] }), node({ keyId: "c", path: "p/c", scopes: [] })];
+    expect(effectiveCaps(chain).scopes).toEqual([]);
+  });
+});
+
+describe("cascade read-checks", () => {
+  const chain = [
+    node({ keyId: "root", path: "root", ownExpiresAt: 1000, disabled: true }),
+    node({ keyId: "self", path: "root/self", ownExpiresAt: 9999, disabled: false }),
+  ];
+  test("expiredAncestor is true when a PARENT expired (caller's own expiry excluded)", () => {
+    expect(expiredAncestor(chain, "self", 2000)).toBe(true); // root expired at 1000
+    expect(expiredAncestor(chain, "self", 500)).toBe(false); // not yet
+    expect(expiredAncestor([chain[1]], "self", 999999)).toBe(false); // self only — own expiry ignored here
+  });
+  test("disabledAncestor is true when a PARENT is soft-disabled (caller's own disable excluded)", () => {
+    expect(disabledAncestor(chain, "self")).toBe(true);
+    expect(disabledAncestor([chain[1]], "self")).toBe(false);
+  });
+});
+
+describe("pooledHeadroom — the abuse-proof property", () => {
+  test("a parent cap bounds the parent + descendants' TOTAL spend (pooled, not just its own)", () => {
+    const chain = [node({ keyId: "root", path: "root", ownCreditLimit: 50 }), node({ keyId: "child", path: "root/child" })];
+    const spend = [{ path: "root", spent: 20 }, { path: "root/child", spent: 30 }];
+    // pooled: root's subtree spend = 20 + 30 = 50 (NOT just its own 20) → remaining 0
+    expect(pooledHeadroom(chain, spend)).toEqual({ limit: 50, spent: 50, remaining: 0 });
+  });
+
+  test("the BINDING constraint is the least remaining across every capped node", () => {
+    const chain = [node({ keyId: "root", path: "root", ownCreditLimit: 100 }), node({ keyId: "child", path: "root/child", ownCreditLimit: 40 })];
+    const spend = [{ path: "root", spent: 10 }, { path: "root/child", spent: 35 }];
+    // root: subtree 45 → remaining 55; child: subtree 35 → remaining 5 → binding
+    expect(pooledHeadroom(chain, spend)).toEqual({ limit: 40, spent: 35, remaining: 5 });
+  });
+
+  test("no cap anywhere → null (only the balance gates)", () => {
+    expect(pooledHeadroom([node({ keyId: "r", path: "r" })], [])).toBeNull();
+  });
+
+  test("topCappedPath picks the shortest-path capped node (whose subtree covers the rest)", () => {
+    const chain = [node({ keyId: "root", path: "root", ownCreditLimit: 100 }), node({ keyId: "c", path: "root/c", ownCreditLimit: 40 })];
+    expect(topCappedPath(chain)).toBe("root");
+    expect(topCappedPath([node({ keyId: "r", path: "r" })])).toBeNull();
+  });
+});
+
+describe("clampChildGrant — a child never out-scopes/out-spends a parent", () => {
+  const parent = { scopes: ["a", "b"], creditLimit: 40, rateLimitSharePct: 50, expiresAt: 3000 };
+  test("scopes ⊆ parent; caps = min(requested, parent)", () => {
+    expect(clampChildGrant(parent, { scopes: ["a", "z"], creditLimit: 100, rateLimitSharePct: 10, expiresAt: 9999 })).toEqual({ scopes: ["a"], creditLimit: 40, rateLimitSharePct: 10, expiresAt: 3000 });
+  });
+  test("a child asking for no expiry INHERITS the parent's; both-null stays null", () => {
+    expect(clampChildGrant(parent, { scopes: ["b"] }).expiresAt).toBe(3000);
+    expect(clampChildGrant({ scopes: [], creditLimit: null, rateLimitSharePct: null, expiresAt: null }, { scopes: [] }).creditLimit).toBeNull();
+  });
+});

package/test/lineage.test.ts

@@ -0,0 +1,84 @@
+import { test, expect, describe, beforeEach } from "bun:test";
+import { Database } from "bun:sqlite";
+import { drizzle } from "drizzle-orm/bun-sqlite";
+import { insertLineage, subtreeOf, parentPathOf, chainHeadroom, revokeKeyTree, type KeysDB, type ChainNode } from "../src/index";
+import { addCredits, debitIfCovers, type CreditsDB } from "@suluk/credits";
+
+/**
+ * C046 — the keys lineage DB ops, witnessed against a REAL bun:sqlite. chainHeadroom is the INTEGRATION point where
+ * @suluk/keys meets @suluk/credits: the pooled headroom is computed by joining the credit ledger, proving the abuse-proof
+ * cap is real across a whole subtree (a parent cap bounds parent + children TOTAL spend, not just the parent's own).
+ */
+function freshDb(): KeysDB & CreditsDB {
+  const sqlite = new Database(":memory:");
+  sqlite.run(`CREATE TABLE key_lineage (keyId TEXT PRIMARY KEY, parentKeyId TEXT, userId TEXT NOT NULL, path TEXT NOT NULL, depth INTEGER NOT NULL)`);
+  sqlite.run(`CREATE TABLE credit_transaction (id TEXT PRIMARY KEY, userId TEXT NOT NULL, delta INTEGER NOT NULL, reason TEXT NOT NULL, createdAt INTEGER NOT NULL)`);
+  sqlite.run(`CREATE TABLE credit_amount (txnId TEXT PRIMARY KEY REFERENCES credit_transaction(id), amountCents INTEGER NOT NULL)`);
+  sqlite.run(`CREATE TABLE credit_key (txnId TEXT PRIMARY KEY REFERENCES credit_transaction(id), keyId TEXT NOT NULL)`);
+  return drizzle(sqlite) as unknown as KeysDB & CreditsDB;
+}
+
+const node = (over: Partial<ChainNode> & { keyId: string; path: string }): ChainNode => ({ scopes: [], ownCreditLimit: null, ownRateSharePct: null, ownExpiresAt: null, ...over });
+let db: KeysDB & CreditsDB;
+const U = "user_1";
+beforeEach(() => {
+  db = freshDb();
+});
+
+describe("lineage tree", () => {
+  test("insertLineage builds materialized paths; subtreeOf + parentPathOf walk them", async () => {
+    await insertLineage(db, { keyId: "root", parentKeyId: null, userId: U, parentPath: null });
+    await insertLineage(db, { keyId: "child", parentKeyId: "root", userId: U, parentPath: "root" });
+    await insertLineage(db, { keyId: "grand", parentKeyId: "child", userId: U, parentPath: "root/child" });
+
+    expect((await subtreeOf(db, "root")).sort()).toEqual(["child", "grand", "root"]);
+    expect((await subtreeOf(db, "child")).sort()).toEqual(["child", "grand"]);
+    expect(await parentPathOf(db, "child")).toBe("root/child");
+    expect(await parentPathOf(db, null)).toBeNull();
+    expect(await subtreeOf(db, "unknown")).toEqual(["unknown"]); // legacy/childless fallback
+  });
+});
+
+describe("chainHeadroom — keys × credits, the pooled cap is real", () => {
+  test("a parent cap bounds parent + child TOTAL spend (pooled across the subtree)", async () => {
+    await insertLineage(db, { keyId: "root", parentKeyId: null, userId: U, parentPath: null });
+    await insertLineage(db, { keyId: "child", parentKeyId: "root", userId: U, parentPath: "root" });
+    await addCredits(db, U, 1000, "topup");
+    await debitIfCovers(db, U, 30, "use", "root"); // attributed to key "root"
+    await debitIfCovers(db, U, 10, "use", "child"); // attributed to key "child"
+
+    const chain = [node({ keyId: "root", path: "root", ownCreditLimit: 50 }), node({ keyId: "child", path: "root/child" })];
+    // pooled: root's subtree spend = 30 (own) + 10 (child) = 40 → remaining 10 (NOT 20, which un-pooled would give)
+    expect(await chainHeadroom(db, chain)).toEqual({ limit: 50, spent: 40, remaining: 10 });
+  });
+
+  test("no cap in the chain → null (only the account balance gates)", async () => {
+    await insertLineage(db, { keyId: "root", parentKeyId: null, userId: U, parentPath: null });
+    expect(await chainHeadroom(db, [node({ keyId: "root", path: "root" })])).toBeNull();
+  });
+});
+
+describe("revokeKeyTree — cascade with the strict-descendant guard", () => {
+  test("disables the subtree via the injected disableKeys; a keyed caller may revoke only a STRICT descendant", async () => {
+    await insertLineage(db, { keyId: "root", parentKeyId: null, userId: U, parentPath: null });
+    await insertLineage(db, { keyId: "child", parentKeyId: "root", userId: U, parentPath: "root" });
+    let disabled: string[] = [];
+    const disableKeys = async (_userId: string, ids: string[]) => {
+      disabled = ids;
+      return ids.length;
+    };
+
+    // a session (no callerKeyId) revokes child + its subtree
+    expect(await revokeKeyTree(db, { userId: U, keyId: "child" }, disableKeys)).toEqual({ revoked: 1 });
+    expect(disabled).toEqual(["child"]);
+
+    // a keyed caller "root" may revoke its STRICT descendant "child"
+    disabled = [];
+    expect(await revokeKeyTree(db, { userId: U, keyId: "child", callerKeyId: "root" }, disableKeys)).toEqual({ revoked: 1 });
+
+    // a keyed caller may NOT revoke itself (not a strict descendant)
+    disabled = [];
+    expect(await revokeKeyTree(db, { userId: U, keyId: "child", callerKeyId: "child" }, disableKeys)).toEqual({ revoked: 0 });
+    expect(disabled).toEqual([]);
+  });
+});

package/test/path-scopes.test.ts

@@ -0,0 +1,49 @@
+import { test, expect, describe } from "bun:test";
+import { escapeLike, subtreeLikePattern, inSubtree, childPath, pathDepth, ancestorIdsOf, parseScopes, parseKeyMeta } from "../src/index";
+
+/** C046 — the materialized-path utilities + the scope/metadata model. */
+
+describe("path utilities", () => {
+  test("inSubtree: self (exact) or a descendant (/-prefix); a sibling is NOT in the subtree", () => {
+    expect(inSubtree("root", "root")).toBe(true);
+    expect(inSubtree("root", "root/child")).toBe(true);
+    expect(inSubtree("root", "root2")).toBe(false); // a sibling sharing a prefix is not a descendant
+    expect(inSubtree("root/a", "root/b")).toBe(false);
+  });
+  test("escapeLike guards LIKE wildcards (a keyId can contain `_`)", () => {
+    expect(escapeLike("ab_c%d\\e")).toBe("ab\\_c\\%d\\\\e");
+    expect(subtreeLikePattern("k_1")).toBe("k\\_1/%");
+  });
+  test("childPath / pathDepth / ancestorIdsOf", () => {
+    expect(childPath("root/a", "b")).toBe("root/a/b");
+    expect(childPath(null, "b")).toBe("b");
+    expect(pathDepth("root")).toBe(0);
+    expect(pathDepth("root/a/b")).toBe(2);
+    expect(ancestorIdsOf("root/a/b")).toEqual(["root", "a"]);
+  });
+});
+
+describe("parseScopes — defensive permissions → scopes", () => {
+  test("null / non-JSON / non-object → no scopes (never throws)", () => {
+    expect(parseScopes(null)).toEqual([]);
+    expect(parseScopes("not json")).toEqual([]);
+    expect(parseScopes("42")).toEqual([]);
+  });
+  test("a valid permissions object yields a non-empty scope list", () => {
+    const scopes = parseScopes(JSON.stringify({ tools: ["read", "write"] }));
+    expect(Array.isArray(scopes)).toBe(true);
+    expect(scopes.length).toBeGreaterThan(0);
+  });
+});
+
+describe("parseKeyMeta — defensive per-key controls", () => {
+  test("absent / bad → null overrides", () => {
+    expect(parseKeyMeta(null)).toEqual({ creditLimit: null, rateLimitSharePct: null });
+    expect(parseKeyMeta("nope")).toEqual({ creditLimit: null, rateLimitSharePct: null });
+  });
+  test("reads creditLimit; clamps rateLimitSharePct to [1,100] and rounds", () => {
+    expect(parseKeyMeta(JSON.stringify({ creditLimit: 250, rateLimitSharePct: 33.4 }))).toEqual({ creditLimit: 250, rateLimitSharePct: 33 });
+    expect(parseKeyMeta(JSON.stringify({ rateLimitSharePct: 0 })).rateLimitSharePct).toBe(1);
+    expect(parseKeyMeta(JSON.stringify({ rateLimitSharePct: 999 })).rateLimitSharePct).toBe(100);
+  });
+});

package/tsconfig.json

@@ -0,0 +1 @@
+{ "extends": "../../tsconfig.base.json", "compilerOptions": { "types": ["bun"] }, "include": ["src", "test"] }