@cosmicdrift/kumiko-bundled-features 0.286.0 → 0.288.0

package/src/derivatives-sharp/render.ts

@@ -5,9 +5,12 @@
 import type {
   BlurRegion,
   DerivativeRendererPlugin,
+  OverlayGravity,
+  ResolvedOverlayLayer,
   VariantFit,
   VariantSpec,
 } from "@cosmicdrift/kumiko-types/derivatives-types";
+import QRCode from "qrcode";
 import type { OverlayOptions, ResizeOptions, Sharp } from "sharp";
 import sharp from "sharp";
 
@@ -25,6 +28,16 @@ const MAX_OUTPUT_EDGE = 8192;
 // unbounded region list is a CPU/RAM-multiplying DoS knob independent of
 // output size.
 const MAX_BLUR_REGIONS = 64;
+// Every layer decodes and resizes separately before the composite — an
+// unbounded list is the same CPU/RAM multiplier MAX_BLUR_REGIONS caps.
+const MAX_OVERLAY_LAYERS = 8;
+// Layer bytes ride inside the spec, which is hashed on every variant() call.
+const MAX_OVERLAY_IMAGE_BYTES = 512 * 1024;
+const MAX_QR_DATA_LENGTH = 1024;
+// Below roughly this, a QR's modules land on too few pixels to survive
+// camera capture — the AC claims phone-scannable, so an under-sized layer
+// throws instead of caching a silently unusable image.
+const MIN_QR_PIXEL_WIDTH = 160;
 // sequentialRead trades random pixel access for lower peak memory on
 // streamed formats — applied at every decode entry point below since none
 // of them need non-sequential access to the *original* bytes (extract runs
@@ -39,6 +52,18 @@ function clampSigma(sigma: number): number {
   return Math.min(MAX_SHARP_SIGMA, Math.max(MIN_SHARP_SIGMA, sigma));
 }
 
+// Shared trust boundary for every image byte source this renderer decodes —
+// the original upload (renderImage) and an overlay layer's bytes (applyOverlays)
+// alike: a base64 string in a field declaration isn't more trustworthy than
+// an upload just because it came from app code.
+function assertNotSvg(format: string | undefined): void {
+  if (format === "svg") {
+    throw new Error(
+      "derivatives-sharp: SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this renderer doesn't need to cross.",
+    );
+  }
+}
+
 function assertValidRegion(region: BlurRegion): void {
   const values = [region.x, region.y, region.width, region.height];
   if (values.some((v) => !Number.isFinite(v)) || region.width <= 0 || region.height <= 0) {
@@ -86,6 +111,102 @@ async function applyBlurRegions(
   return sharp(data, SHARP_INPUT_OPTIONS).composite(overlays).toBuffer();
 }
 
+// Placement is anchored to the OUTPUT box (overlays run after resize, see
+// applyOverlays), then clamped the same way applyBlurRegions clamps its
+// region coordinates — a caller-declared marginPct can't push a layer
+// off-canvas.
+function overlayPosition(
+  gravity: OverlayGravity,
+  marginPx: number,
+  outputWidth: number,
+  outputHeight: number,
+  layerWidth: number,
+  layerHeight: number,
+): { left: number; top: number } {
+  let left: number;
+  let top: number;
+  switch (gravity) {
+    case "north-west":
+      left = marginPx;
+      top = marginPx;
+      break;
+    case "north-east":
+      left = outputWidth - layerWidth - marginPx;
+      top = marginPx;
+      break;
+    case "south-west":
+      left = marginPx;
+      top = outputHeight - layerHeight - marginPx;
+      break;
+    case "south-east":
+      left = outputWidth - layerWidth - marginPx;
+      top = outputHeight - layerHeight - marginPx;
+      break;
+    case "center":
+      left = (outputWidth - layerWidth) / 2;
+      top = (outputHeight - layerHeight) / 2;
+      break;
+    default:
+      throw new Error(`derivatives-sharp: unknown overlay gravity "${gravity satisfies never}".`);
+  }
+  const maxLeft = Math.max(0, outputWidth - layerWidth);
+  const maxTop = Math.max(0, outputHeight - layerHeight);
+  return {
+    left: Math.min(Math.max(Math.round(left), 0), maxLeft),
+    top: Math.min(Math.max(Math.round(top), 0), maxTop),
+  };
+}
+
+// Runs AFTER resize (see the AC in renderImage) so a layer sized as a
+// fraction of the output is a fraction of what the caller actually gets,
+// regardless of the source's own dimensions or `fit` crop.
+async function applyOverlays(
+  pipeline: Sharp,
+  layers: readonly ResolvedOverlayLayer[],
+): Promise<Sharp> {
+  const { data, info } = await pipeline.toBuffer({ resolveWithObject: true });
+
+  const composites: OverlayOptions[] = [];
+  for (const layer of layers) {
+    const layerBytes =
+      layer.kind === "qr"
+        ? await QRCode.toBuffer(layer.data, { margin: 1, errorCorrectionLevel: "M" })
+        : Buffer.from(layer.imageBase64, "base64");
+
+    const layerMeta = await sharp(layerBytes, SHARP_INPUT_OPTIONS).metadata();
+    assertNotSvg(layerMeta.format);
+
+    const targetWidth = Math.max(1, Math.round(info.width * layer.widthPct));
+    if (layer.kind === "qr" && targetWidth < MIN_QR_PIXEL_WIDTH) {
+      throw new Error(
+        `derivatives-sharp: qr overlay would render at ${targetWidth}px wide, below the ${MIN_QR_PIXEL_WIDTH}px minimum a camera can reliably scan.`,
+      );
+    }
+
+    // PNG (not the layer's own format) to keep any alpha through the resize.
+    // height caps the other axis too — sharp's composite() rejects an input
+    // larger than the base image, which a tall/square layer would otherwise
+    // hit once widthPct alone drives its width past the output's height.
+    const resized = await sharp(layerBytes, SHARP_INPUT_OPTIONS)
+      .resize({ width: targetWidth, height: info.height, fit: "inside" })
+      .png()
+      .toBuffer({ resolveWithObject: true });
+
+    const marginPx = Math.round(info.width * (layer.marginPct ?? 0));
+    const { left, top } = overlayPosition(
+      layer.gravity,
+      marginPx,
+      info.width,
+      info.height,
+      resized.info.width,
+      resized.info.height,
+    );
+    composites.push({ input: resized.data, left, top });
+  }
+
+  return sharp(data, SHARP_INPUT_OPTIONS).composite(composites);
+}
+
 function buildResizeOptions(width: number, height: number, fit: VariantFit): ResizeOptions {
   const options: ResizeOptions = { width, height, fit };
   if (fit === "inside") {
@@ -153,6 +274,51 @@ function applyEncoder(pipeline: Sharp, spec: VariantSpec, sourceMimeType: string
   return encode(pipeline, quality);
 }
 
+// Split out of assertRenderSpecBounds (not inlined there) purely to stay
+// under the AST-guard complexity budget — see assertRenderSpecBounds's own
+// comment. Still the single call site for every overlay bound.
+function assertOverlayLayerBounds(layer: ResolvedOverlayLayer): void {
+  if (!Number.isFinite(layer.widthPct) || layer.widthPct <= 0 || layer.widthPct > 1) {
+    throw new Error(
+      `derivatives-sharp: overlay widthPct ${layer.widthPct} is out of range — must be a finite number in (0, 1].`,
+    );
+  }
+  if (layer.marginPct !== undefined && (layer.marginPct < 0 || layer.marginPct >= 0.5)) {
+    throw new Error(
+      `derivatives-sharp: overlay marginPct ${layer.marginPct} is out of range — must be within [0, 0.5).`,
+    );
+  }
+  if (layer.kind === "qr") {
+    if (layer.data.length === 0 || layer.data.length > MAX_QR_DATA_LENGTH) {
+      throw new Error(
+        `derivatives-sharp: qr overlay data length ${layer.data.length} is out of range — must be 1–${MAX_QR_DATA_LENGTH} characters.`,
+      );
+    }
+    // skip: qr layers have no imageBase64 field to validate; this return also
+    // narrows the union below to the image variant without a cast.
+    return;
+  }
+  const byteLength = Buffer.byteLength(layer.imageBase64, "base64");
+  if (byteLength > MAX_OVERLAY_IMAGE_BYTES) {
+    throw new Error(
+      `derivatives-sharp: overlay image is ${byteLength} bytes, exceeding the limit of ${MAX_OVERLAY_IMAGE_BYTES}.`,
+    );
+  }
+}
+
+function assertOverlayBounds(layers: readonly ResolvedOverlayLayer[] | undefined): void {
+  // skip: no overlays configured for this variant, nothing to validate
+  if (!layers) return;
+  if (layers.length > MAX_OVERLAY_LAYERS) {
+    throw new Error(
+      `derivatives-sharp: overlays has ${layers.length} entries, exceeding the limit of ${MAX_OVERLAY_LAYERS} — each layer decodes and resizes separately before the composite.`,
+    );
+  }
+  for (const layer of layers) {
+    assertOverlayLayerBounds(layer);
+  }
+}
+
 // Input-validation for the DoS caps above — kept out of renderImage so the
 // complexity hotspot stays under the AST-guard budget.
 function assertRenderSpecBounds(spec: VariantSpec): void {
@@ -181,6 +347,7 @@ function assertRenderSpecBounds(spec: VariantSpec): void {
       );
     }
   }
+  assertOverlayBounds(spec.resolvedOverlays);
 }
 
 export const renderImage: DerivativeRendererPlugin["render"] = async (
@@ -194,11 +361,7 @@ export const renderImage: DerivativeRendererPlugin["render"] = async (
   // the SVG rejection from the actual bytes so a mislabeled upload can't
   // reach libvips as SVG.
   const sniffed = await sharp(input, SHARP_INPUT_OPTIONS).metadata();
-  if (sniffed.format === "svg") {
-    throw new Error(
-      "derivatives-sharp: SVG is not supported — rendering untrusted SVG through libvips is a trust boundary this renderer doesn't need to cross.",
-    );
-  }
+  assertNotSvg(sniffed.format);
 
   assertRenderSpecBounds(spec);
 
@@ -225,6 +388,10 @@ export const renderImage: DerivativeRendererPlugin["render"] = async (
     pipeline = pipeline.blur(spec.blur);
   }
 
+  if (spec.resolvedOverlays && spec.resolvedOverlays.length > 0) {
+    pipeline = await applyOverlays(pipeline, spec.resolvedOverlays);
+  }
+
   pipeline = applyEncoder(pipeline, spec, normalizedSource);
 
   const buffer = await pipeline.toBuffer();

package/src/file-derivatives/__tests__/public-variant-route.integration.test.ts

@@ -77,9 +77,23 @@ const widgetEntity = createEntity({
   },
 });
 
+// Registered as a real entity (so upload's registry-hardening resolves it)
+// but with no EXT_DERIVATIVE_PUBLIC_PREDICATE registration — the "no
+// predicate registered for this entityType" default-deny case below needs
+// an entity that upload can attach to, distinct from "the entityType string
+// isn't registered at all" (which upload now rejects before the file ever
+// reaches file_refs, see kumiko-framework#3005).
+const noPredicateEntity = createEntity({
+  table: "public_variant_no_predicate",
+  fields: {
+    img: createImageField({ variants: { thumb: { maxEdge: 160, format: "webp" } } }),
+  },
+});
+
 let predicateCalls = 0;
 const widgetPredicateFeature = defineFeature("publicvariantroutetest", (r) => {
   r.entity("widget", widgetEntity);
+  r.entity("nopredicate", noPredicateEntity);
   r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, "widget", {
     isPublic: (args: DerivativePublicPredicateArgs) => {
       predicateCalls++;
@@ -161,7 +175,7 @@ async function uploadFile(
 
 describe("GET /media/:fileRefId/:variant (anonymous, default-deny)", () => {
   test("no predicate registered for the FileRef's entityType → 404", async () => {
-    const fileId = await uploadFile(userA, { entityType: "unregistered-type", entityId: "x" });
+    const fileId = await uploadFile(userA, { entityType: "nopredicate", entityId: "x" });
 
     const res = await stack.app.request(`http://${HOST_A}/media/${fileId}/thumb`);
 

package/src/file-derivatives/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "Add overlay stage (QR codes, badge images) to derived image variants",
+    "detail": "VariantSpec now supports declarative overlay layers (qr via a resolver-token, or a base64 image) composited onto derived image variants. QR values are never free text — only a dataToken resolved server-side via a new extension point, keeping the anonymous derivative route from becoming an open image generator."
+  },
   {
     "version": "0.194.0",
     "type": "breaking",

package/src/file-derivatives/feature.ts

@@ -9,6 +9,7 @@
 import { cachedResponse, computeRevisionEtag } from "@cosmicdrift/kumiko-framework/api";
 import {
   defineFeature,
+  EXT_DERIVATIVE_OVERLAY_RESOLVER,
   EXT_DERIVATIVE_PUBLIC_PREDICATE,
   EXT_DERIVATIVE_RENDERER,
   type FeatureDefinition,
@@ -78,7 +79,7 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
 
   return defineFeature(FEATURE_NAME, (r) => {
     r.describe(
-      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) trusts the first `x-forwarded-for` hop — deployers must ensure their ingress overwrites rather than appends to that header, or the throttle is bypassable by rotating it.",
+      "Declares the `derivativeRenderer` extension point. `ctx.derivatives.variant(fileRefId, spec, name)` derives a variant of a tracked FileRef the first time it's requested and reuses the stored result afterwards (derive-on-first-use, keyed by a hash of the spec). Mount at least one `derivatives-*` renderer feature alongside this one — without a registered renderer for the FileRef's MIME type, every `variant(...)` call throws. Also declares the `derivativePublicPredicate` extension point (`r.useExtension(EXT_DERIVATIVE_PUBLIC_PREDICATE, '<entityType>', { isPublic })`) and, when `createFileDerivativesFeature({resolveApexTenant})` is passed a host-resolver, mounts an anonymous `GET {basePath}/:fileRefId/:variant` route that serves any variant name the FileRef's field declared in its `variants` for a FileRef whose entityType has a registered predicate returning true — default-deny (404) otherwise, same as an unknown FileRef or an undeclared variant name. The route's only rate-limit (`per: \"ip\"`) trusts the first `x-forwarded-for` hop — deployers must ensure their ingress overwrites rather than appends to that header, or the throttle is bypassable by rotating it. Also declares the `derivativeOverlayResolver` extension point (`r.useExtension(EXT_DERIVATIVE_OVERLAY_RESOLVER, '<entityType>', { resolve })`), used to turn a variant's `overlays[].dataToken` into the actual QR payload for that FileRef's entityType before the variant is rendered — a variant declaring a `qr` overlay throws at request-time if no resolver is registered for the FileRef's entityType.",
     );
     r.uiHints({
       displayLabel: "File Derivatives",
@@ -108,6 +109,13 @@ export function createFileDerivativesFeature(opts: FileDerivativesOptions = {}):
         // entityType.
       },
     });
+    r.extendsRegistrar(EXT_DERIVATIVE_OVERLAY_RESOLVER, {
+      onRegister: () => {
+        // No side-effects at register-time — resolution happens in
+        // variant(), keyed by the FileRef's entityType, before the spec
+        // hash is computed.
+      },
+    });
 
     // Registered ONLY when resolveApexTenant is supplied — r.queryHandler
     // registers publicVariantQuery into the feature's dispatch table as a

package/src/shared/__tests__/row-bound-grant.integration.test.ts

@@ -0,0 +1,184 @@
+// Row-bound grants end-to-end over real /api/write calls without a session:
+// the shape a consumer builds on (anonymous caller created a row, now performs
+// exactly one narrow further write on it). The unit tests fake the anchor
+// store; this one uses a real conditional UPDATE against Postgres, which is
+// the only way to show that `commitAnchor` can actually be atomic and that two
+// simultaneous redemptions of the same grant leave exactly one winner.
+
+import { afterAll, beforeAll, beforeEach, describe, expect, test } from "bun:test";
+import { executeRawQuery } from "@cosmicdrift/kumiko-framework/db";
+import { defineFeature } from "@cosmicdrift/kumiko-framework/engine";
+import { UnprocessableError, writeFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { setupTestStack, type TestStack, testTenantId } from "@cosmicdrift/kumiko-framework/stack";
+import { z } from "zod";
+import { redeemRowBoundGrant, signRowBoundGrant } from "../row-bound-grant";
+
+const TABLE = "row_bound_grant_demo";
+const SECRET = "row-bound-grant-integration-secret";
+const PURPOSE = "demo-enrich";
+const ENRICH = "grantdemo:write:enrich";
+const ROW_ID = "11111111-1111-4111-8111-111111111111";
+const ANCHOR = "22222222-2222-4222-8222-222222222222";
+
+// Two /api/write calls fired together still run to completion one after the
+// other, so a plain Promise.all would never open the window a conditional
+// UPDATE exists for. This holds every redeemer between reading the anchor and
+// spending it until `expected` of them have read it — the interleaving itself,
+// deterministic instead of a sleep. The timeout keeps a serialising stack from
+// hanging the suite: it fails the assertion instead.
+function createRaceGate(expected: number, timeoutMs = 2_000) {
+  let arrived = 0;
+  let open: () => void = () => {};
+  const opened = new Promise<void>((resolve) => {
+    open = resolve;
+  });
+  return {
+    async wait(): Promise<void> {
+      arrived += 1;
+      if (arrived >= expected) open();
+      await Promise.race([opened, Bun.sleep(timeoutMs)]);
+    },
+  };
+}
+
+let raceGate: { wait: () => Promise<void> } | null = null;
+
+const RAW_REASON =
+  "the grant holder has no session, so the anchor spend is a conditional UPDATE " +
+  "outside the entity write map";
+
+const grantDemoFeature = defineFeature("grantdemo", (r) => {
+  r.writeHandler(
+    "enrich",
+    z.object({ token: z.string().min(1), note: z.string().min(1) }),
+    async (event, ctx) => {
+      const db = ctx.db.unsafeRaw(RAW_REASON);
+      const redeemed = await redeemRowBoundGrant({
+        token: event.payload.token,
+        purpose: PURPOSE,
+        secret: SECRET,
+        loadAnchor: async (subject) => {
+          const rows = await executeRawQuery<{ anchor: string | null }>(
+            db,
+            `SELECT anchor FROM ${TABLE} WHERE id = $1`,
+            [subject],
+          );
+          await raceGate?.wait();
+          return rows[0]?.anchor ?? null;
+        },
+        commitAnchor: async (subject, expected) => {
+          const rows = await executeRawQuery<{ id: string }>(
+            db,
+            `UPDATE ${TABLE} SET anchor = NULL, note = $3 WHERE id = $1 AND anchor = $2 RETURNING id`,
+            [subject, expected, event.payload.note],
+          );
+          return rows.length === 1;
+        },
+      });
+      if (!redeemed.ok) return writeFailure(new UnprocessableError("invalid_or_expired_grant"));
+      return { isSuccess: true as const, data: { id: redeemed.subject } };
+    },
+    {
+      access: { roles: ["anonymous"] },
+      escapeHatch: {
+        reason:
+          "the row is written by an anonymous grant holder through raw SQL, so the write " +
+          "cannot go through the entity write map of a tenant-scoped user",
+      },
+    },
+  );
+});
+
+let stack: TestStack;
+
+function grantFor(anchor: string): string {
+  return signRowBoundGrant({
+    subject: ROW_ID,
+    purpose: PURPOSE,
+    anchor,
+    ttlMinutes: 30,
+    secret: SECRET,
+  }).token;
+}
+
+function enrich(token: string, note: string) {
+  return stack.http.raw("POST", "/api/write", { type: ENRICH, payload: { token, note } });
+}
+
+async function readRow(): Promise<{ anchor: string | null; note: string | null } | undefined> {
+  const rows = await executeRawQuery<{ anchor: string | null; note: string | null }>(
+    stack.db,
+    `SELECT anchor, note FROM ${TABLE} WHERE id = $1`,
+    [ROW_ID],
+  );
+  return rows[0];
+}
+
+beforeAll(async () => {
+  stack = await setupTestStack({
+    features: [grantDemoFeature],
+    anonymousAccess: { defaultTenantId: testTenantId(1) },
+  });
+  await executeRawQuery(
+    stack.db,
+    `CREATE TABLE IF NOT EXISTS ${TABLE} (id uuid PRIMARY KEY, anchor uuid, note text)`,
+  );
+});
+
+afterAll(async () => {
+  await stack.cleanup();
+});
+
+beforeEach(async () => {
+  raceGate = null;
+  await executeRawQuery(stack.db, `DELETE FROM ${TABLE}`);
+  await executeRawQuery(stack.db, `INSERT INTO ${TABLE} (id, anchor, note) VALUES ($1, $2, NULL)`, [
+    ROW_ID,
+    ANCHOR,
+  ]);
+});
+
+describe("row-bound grant over anonymous HTTP", () => {
+  test("a valid grant performs the one write and spends the anchor", async () => {
+    const res = await enrich(grantFor(ANCHOR), "first");
+
+    expect(res.status).toBe(200);
+    expect(await readRow()).toEqual({ anchor: null, note: "first" });
+  });
+
+  test("replaying the same grant fails and leaves the row alone", async () => {
+    const token = grantFor(ANCHOR);
+    expect((await enrich(token, "first")).status).toBe(200);
+
+    const replay = await enrich(token, "second");
+
+    expect(replay.status).toBe(422);
+    expect(await readRow()).toEqual({ anchor: null, note: "first" });
+  });
+
+  test("two simultaneous redemptions of one grant leave exactly one winner", async () => {
+    const token = grantFor(ANCHOR);
+    raceGate = createRaceGate(2);
+
+    const results = await Promise.all([enrich(token, "a"), enrich(token, "b")]);
+
+    expect(results.map((r) => r.status).sort()).toEqual([200, 422]);
+    const row = await readRow();
+    expect(row?.anchor).toBeNull();
+    expect(["a", "b"]).toContain(row?.note ?? "");
+  });
+
+  test("a grant for a superseded anchor fails without spending the live one", async () => {
+    const res = await enrich(grantFor("33333333-3333-4333-8333-333333333333"), "stale");
+
+    expect(res.status).toBe(422);
+    expect(await readRow()).toEqual({ anchor: ANCHOR, note: null });
+  });
+
+  test("a garbage token is a 422, not a 500 from the row lookup", async () => {
+    const res = await enrich("not.a.token", "junk");
+
+    expect(res.status).toBe(422);
+    expect(await readRow()).toEqual({ anchor: ANCHOR, note: null });
+  });
+});

package/src/shared/changes.json

@@ -1 +1,8 @@
-[]
+[
+  {
+    "version": "0.287.0",
+    "type": "improvement",
+    "title": "row-bound grants: one short-lived, single-use capability for anonymous writes on one row",
+    "detail": "`signed-token.ts` moves from `auth-email-password/` to `shared/` — the mechanism\nwas never email/password specific (user-data-rights already used it). The old\npath re-exports it, so no importer breaks. New subpaths:\n`./shared/signed-token` and `./shared/row-bound-grant`.\n`shared/row-bound-grant.ts` is the new piece. It folds the row's *current*\nanchor (a request id, a status, a version — anything that moves on when the row\nis consumed) into the HMAC purpose on both mint and redeem, so a replayed token\nstops working the moment the row moves on. Single-use semantics without a burn\nkey and without Redis. Minting and redeeming share one purpose-building\nfunction, because an unanchored purpose silently degrades into a bearer token\nvalid for the whole TTL.\nAnchoring alone only closes the replay window once the row has moved on, so\nspending the anchor is part of the primitive, not homework for the caller:\n`redeemRowBoundGrant` takes a mandatory `commitAnchor(subject, expectedAnchor)`\nthat must move the row on atomically (a conditional UPDATE) and report whether\nthis caller won. It runs strictly after verification, so nobody can invalidate a\nrow by naming it with a junk token, and the loser of a race gets the same\nrejection as a forged grant. Skipping it is possible but has to be declared with\na reason (`{ unsafeSkip: { reason } }`), the way the framework handles\n`escapeHatch` — an undeclared skip is how a single-use grant quietly becomes a\nbearer token for the length of its TTL.\nEvery rejection returns a bare `{ ok: false }` with no reason, so a caller\ncannot accidentally turn an anonymous endpoint into a row-existence oracle.\n`user-data-rights`' deletion token now runs on the helper and its hand-rolled\n`peekDeletionTokenUserId` is gone. The tokens stay byte-compatible — a test\npins the wire format against the pre-refactor formula. It declares an\n`unsafeSkip` for the spend: `pendingDeletionRequestId` may only change through\n`updateUserLifecycle`, so a conditional UPDATE there would lose the field on a\nprojection rebuild. Behaviour of that flow is unchanged.\nNote for callers: the subject is not secret. `signToken` puts it in the token\nbody in the clear, so a grant on a row exposes that row's id to whoever holds\nthe link. Where the id itself must stay hidden, use an opaque handle\n(`./shared/single-use-token-store`) instead."
+  }
+]

package/src/shared/index.ts

@@ -20,9 +20,21 @@ export { createLockoutCounter, type LockoutCounterState } from "./lockout-counte
 export { mapWithConcurrency } from "./map-with-concurrency";
 export { joinRowParentIsVisible, parentRowIsVisible } from "./parent-visibility";
 export { hashPassword, verifyDummyPassword, verifyPassword } from "./password-hashing";
+export {
+  type RowBoundGrantResult,
+  redeemRowBoundGrant,
+  signRowBoundGrant,
+} from "./row-bound-grant";
 export { sessionField } from "./session-field";
 export { sessionLocaleField } from "./session-locale-field";
 export { sessionTimezoneField } from "./session-timezone-field";
+export {
+  peekTokenSubject,
+  signToken,
+  TokenPurpose,
+  type VerifyResult,
+  verifyToken,
+} from "./signed-token";
 export { createSingleUseTokenStore } from "./single-use-token-store";
 export type { SystemQueryFn } from "./system-query";
 export { type BurnResult, burnToken, unburnToken } from "./token-burn-store";