@tokenoftrust/storefront-runner 4.11.11 → 4.11.13

package/apps/storefront/migrations-apps/0023_principal_grant_contacts.sql

@@ -0,0 +1,15 @@
+-- Grantee emails for principal grants made through storefront, shown only on the store owner's own
+-- Team page. tot20's grant list names a grantee by an opaque principal id, so storefront records the
+-- email beside the opaque grant ref when tot20 confirms a grant. Display only: never consulted to
+-- decide access. Retention-bounded: expires_at is the grant's confirmed expiry; expired rows are
+-- purged on writes, owner reads and the hourly sweep, and a row is deleted when its grant is revoked
+-- through storefront or no longer appears in the store's active grant list.
+CREATE TABLE principal_grant_contacts (
+ tenant_id TEXT NOT NULL,
+ grant_ref TEXT NOT NULL,
+ grantee_email TEXT NOT NULL,
+ recorded_at TEXT NOT NULL,
+ expires_at TEXT NOT NULL,
+ PRIMARY KEY (tenant_id, grant_ref)
+);
+CREATE INDEX idx_principal_grant_contacts_expires ON principal_grant_contacts(expires_at);

package/apps/storefront/public/js/dashboard-delegate.js

@@ -58,7 +58,9 @@
     for (const g of grants) {
       const tr = document.createElement("tr");
       const dev = document.createElement("td");
-      dev.textContent = (g.principal && g.principal.email) || "";
+      // tot20 names the grantee by an opaque id; storefront adds the email for grants made here.
+      dev.textContent = (g.principal && g.principal.email) || "Granted outside this page (email not recorded)";
+      if (!(g.principal && g.principal.email)) dev.className = "muted";
       const cap = document.createElement("td");
       cap.textContent = LABELS[g.capability] || g.capability || "";
       const exp = document.createElement("td");

package/apps/storefront/src/lib/access/shared/grantContactLookup.ts

@@ -0,0 +1,97 @@
+/**
+ * Grantee emails for principal grants made through storefront, for the store owner's own Team page.
+ *
+ * tot20's principal-grant list names each grantee by an opaque principal id, never the email, so the
+ * owner could not tell who holds a grant. When tot20 CONFIRMS a grant, storefront records the email
+ * it was issued to beside the confirmed opaque ref (`principal_grant_contacts`, migration 0023).
+ *
+ * Display only: nothing here decides access. tot20's writer and the per-person grant reads stay the
+ * only authority. The stored value is the grantee's own address (a ToT staff member or a developer the
+ * owner chose), not a customer contact, so it is kept in plaintext and shown only to that store's
+ * owner. It is never logged and never returned to anyone else.
+ *
+ * Retention: `expires_at` is the grant's confirmed expiry. Expired rows are purged (bounded per call)
+ * on every write and every owner read, and by the hourly sweep (`purgeExpiredGranteeContacts`). After
+ * a SUCCESSFUL tot20 list the owner read also deletes that store's rows whose ref is no longer listed
+ * (revoked outside storefront, or replaced). Every statement is keyed by tenant except the global
+ * expiry purge, which deletes only rows already past their expiry.
+ */
+
+/** The query seam this module needs; D1 (via `fromD1`) and the node:sqlite test shim satisfy it. */
+export interface LookupDb {
+  all<T = Record<string, unknown>>(sql: string, ...params: unknown[]): Promise<T[]>;
+  run(sql: string, ...params: unknown[]): Promise<void>;
+}
+
+/** Rows deleted per purge call, so one request never does unbounded work. */
+export const PURGE_BATCH = 200;
+
+async function purgeExpired(db: LookupDb, now: Date, limit = PURGE_BATCH): Promise<void> {
+  await db.run(
+    `DELETE FROM principal_grant_contacts WHERE rowid IN (
+       SELECT rowid FROM principal_grant_contacts WHERE expires_at <= ? ORDER BY expires_at LIMIT ?)`,
+    now.toISOString(),
+    limit,
+  );
+}
+
+/**
+ * Record the email a confirmed grant was issued to. `expiresAt` is tot20's confirmed expiry
+ * (epoch-ms). Overwrites only this tenant's row for the same ref.
+ */
+export async function recordGranteeContact(
+  db: LookupDb,
+  input: { tenantId: string; grantRef: string; email: string; expiresAt: number; now: Date },
+): Promise<void> {
+  await purgeExpired(db, input.now);
+  if (!input.grantRef || !input.email || !Number.isFinite(input.expiresAt)) return;
+  await db.run(
+    `INSERT INTO principal_grant_contacts (tenant_id, grant_ref, grantee_email, recorded_at, expires_at)
+     VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT (tenant_id, grant_ref) DO UPDATE SET
+       grantee_email = excluded.grantee_email, recorded_at = excluded.recorded_at, expires_at = excluded.expires_at`,
+    input.tenantId,
+    input.grantRef,
+    input.email,
+    input.now.toISOString(),
+    new Date(input.expiresAt).toISOString(),
+  );
+}
+
+/** Forget the email for a grant revoked through storefront. */
+export async function forgetGranteeContact(db: LookupDb, tenantId: string, grantRef: string): Promise<void> {
+  await db.run(`DELETE FROM principal_grant_contacts WHERE tenant_id = ? AND grant_ref = ?`, tenantId, grantRef);
+}
+
+/**
+ * The emails for this store's grants, by ref, for the owner's list. Purges expired rows first.
+ * `activeRefs` is the ref set from a SUCCESSFUL tot20 list: rows for refs not in it are deleted. Pass
+ * null when the list failed, so nothing is reconciled.
+ */
+export async function granteeContactsFor(
+  db: LookupDb,
+  tenantId: string,
+  activeRefs: ReadonlySet<string> | null,
+  now: Date,
+): Promise<Map<string, string>> {
+  await purgeExpired(db, now);
+  const rows = await db.all<{ grant_ref: string; grantee_email: string }>(
+    `SELECT grant_ref, grantee_email FROM principal_grant_contacts WHERE tenant_id = ? AND expires_at > ?`,
+    tenantId,
+    now.toISOString(),
+  );
+  const out = new Map<string, string>();
+  for (const row of rows) {
+    if (activeRefs && !activeRefs.has(row.grant_ref)) {
+      await forgetGranteeContact(db, tenantId, row.grant_ref);
+      continue;
+    }
+    out.set(row.grant_ref, row.grantee_email);
+  }
+  return out;
+}
+
+/** The hourly sweep's purge: rows already past their grant's expiry, bounded per call. */
+export async function purgeExpiredGranteeContacts(db: LookupDb, now: Date, limit = PURGE_BATCH): Promise<void> {
+  await purgeExpired(db, now, limit);
+}

package/apps/storefront/src/lib/access/shared/principalGrants.ts

@@ -82,6 +82,25 @@
  */
 import { readEnv } from "@/lib/publication/shared/env";
 import { BROKER_ASSERTION_HEADER, BROKER_PRIVATE_KEY_ENV } from "@/lib/access/auth/brokerAssertion";
+import { resolveContactReadGrant } from "@/lib/access/auth/contactReaderAuthority";
+import { resolveViewerShipCapability } from "@/lib/access/shared/viewerGrant";
+
+/** The live principal grant a person holds on a store, as far as the grant reads can tell. */
+export type HeldPrincipalGrant = "customer-contact-read" | "ship-on-behalf" | null;
+
+/**
+ * The live principal grant `email` already holds on `tenant`, read through the per-person
+ * subject-capability seam (keyed by email). tot20 keeps ONE principal grant per person per store
+ * (`addPrincipalGrant` writes `principalGrants[principalKey]`, capability included), so a new grant
+ * to someone who holds one REPLACES it; callers refuse instead. tot20's grant LIST cannot answer
+ * this: its rows name the principal by an opaque id, never the email. Both reads fail closed to
+ * "none" on a seam fault, so a fault lets the grant through rather than blocking it.
+ */
+export async function heldPrincipalGrant(email: string, tenant: string): Promise<HeldPrincipalGrant> {
+  if (await resolveContactReadGrant(email, tenant)) return "customer-contact-read";
+  if ((await resolveViewerShipCapability(email, tenant)) === "ship-on-behalf") return "ship-on-behalf";
+  return null;
+}
 
 /** A human grantee — the only principal type this HTTP surface accepts. */
 export interface UserPrincipal {

package/apps/storefront/src/scheduled/contactVaultSweep.ts

@@ -2,7 +2,8 @@
  * The hourly contact vault sweep — the Worker's `scheduled` handler body. One `now` per firing,
  * taken from its scheduled time: clear expired order-contact field groups and contact messages,
  * shorten terminal orders' retention, seal any contact message still held as legacy plaintext,
- * rotate data keys older than a year, and recompute blind indexes still under a retired kid. Expiry predicates only; it never touches an order or audit row.
+ * rotate data keys older than a year, recompute blind indexes still under a retired kid, and purge
+ * grantee emails whose grant has expired. Expiry predicates only; it never touches an order or audit row.
  *
  * Purge never needs a key, so it always runs; sealing and rotation need KMS and are skipped (with
  * `kmsAvailable: false`) when it refuses. It logs ONE structured line of counts on success and ONE
@@ -20,6 +21,7 @@ import {
 } from "@/lib/engagement/contact/contactMessages.js";
 import { loadVaultKms } from "@/lib/orders/vault/kmsEnv.js";
 import { purgeOrderContacts, rotateContactVaultKeys, type PurgeCounts } from "@/lib/orders/vault/orderContactVault.js";
+import { purgeExpiredGranteeContacts } from "@/lib/access/shared/grantContactLookup.js";
 import { readD1 } from "@/lib/publication/shared/env";
 
 export const SWEEP_LEGACY_SEAL_LIMIT = 500;
@@ -51,6 +53,8 @@ export async function runContactVaultSweep(db: Queryable, kms: KmsClient, now: D
   if (Number.isNaN(now.getTime())) throw new Error("contact vault sweep: unreadable clock");
   const orders = await purgeOrderContacts(db, now);
   const messages = await purgeContactMessages(db, now);
+  // Grantee emails recorded for the owner's Team page, once their grant has expired.
+  await purgeExpiredGranteeContacts(db, now);
   const legacy = await withKms(() => sealLegacyContactMessages(db, kms, now, SWEEP_LEGACY_SEAL_LIMIT));
   const rotation = await withKms(() => rotateContactVaultKeys(db, kms, now, { recompute: [recomputeMessageBlindIndexes] }));
   return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tokenoftrust/storefront-runner",
-  "version": "4.11.11",
+  "version": "4.11.13",
   "license": "SEE LICENSE IN LICENSE",
   "description": "World-shareable storefront runner: multi-tenant renderer on Astro/Cloudflare. No control plane.",
   "packageManager": "pnpm@11.9.0",