payment-kit 1.29.1 → 1.29.2

package/scripts/scan-tenant-queries.js

@@ -0,0 +1,235 @@
+#!/usr/bin/env node
+/* eslint-disable no-console */
+// W1′ Phase 5: structural tenant-isolation backstop scanner.
+//
+// Phase 3 made the 38 tenant models `extends TenantModel`, so a bare
+// `Coupon.findAll()` is now tenant-scoped BY CONSTRUCTION — the old denylist
+// ("bare model query = violation, 151-file whitelist") is obsolete and
+// fail-open. This scanner replaces it with two STRUCTURAL invariants that make
+// the safety load-bearing, plus the single-Host-reader rule:
+//
+//   Assertion ①  every tenant-table model `extends TenantModel` (not `Model`).
+//                If a tenant model regresses to `extends Model`, every query on
+//                it silently stops being scoped — caught here.
+//   Assertion ②  a raw `.query(...)` whose SQL touches a tenant TABLE (DML, not
+//                DDL) must bind a tenant via `$instance_did` / `:instance_did`.
+//   Host rule    the raw Host header is read at exactly one place (middleware).
+//
+// The whitelist collapses from 151 files to a handful of genuine raw/system
+// exceptions (see tenant-scan-whitelist.json, reasons in three classes).
+//
+// Usage:  node scripts/scan-tenant-queries.js [--json] [extra files...]
+// Exit 1 when violations outside the whitelist are found (or whitelist is stale).
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const SRC_DIR = path.join(ROOT, 'api/src');
+const MODELS_DIR = path.join(ROOT, 'api/src/store/models');
+// TENANT_SCAN_WHITELIST overrides the whitelist path (tests point it at a temp
+// file to prove an entry can never wildcard-swallow a directory).
+const WHITELIST_FILE = process.env.TENANT_SCAN_WHITELIST || path.join(__dirname, 'tenant-scan-whitelist.json');
+
+// canonical single source (scoped.ts re-exports this same constant)
+const { TENANT_TABLES } = require(path.join(ROOT, 'api/src/store/tenant-tables.ts'));
+const TENANT_TABLE_SET = new Set(TENANT_TABLES);
+
+// table name -> model class name (customers -> Customer, payment_currencies -> PaymentCurrency)
+function modelNameFor(table) {
+  const singular = table.endsWith('ies') ? `${table.slice(0, -3)}y` : table.replace(/s$/, '');
+  return singular
+    .split('_')
+    .map((part) => part[0].toUpperCase() + part.slice(1))
+    .join('');
+}
+const TENANT_MODEL_NAMES = new Set(TENANT_TABLES.map(modelNameFor));
+
+// The raw-query exemptions encode the THREE reason classes that used to live as
+// 151 whole-file whitelist entries (Phase 1 declared them; Phase 5 makes them
+// structural). The whitelist file itself is now empty — these are the only
+// exceptions, and they are by-design, not "unscheduled".
+//
+//   class ① design-permanent  : migrations + tenant-backfill cross tenants by
+//                               design (RAW_EXEMPT_PATH).
+//   class ② entry-validated /  : the scopedQuery guard helper (scoped.ts), the
+//           contract              D1/SQLite executor whose callers own scoping
+//                               (drivers/db.ts), startup pragmas (sequelize.ts),
+//                               and DDL/schema statements (DDL regex below).
+//   class ③ unscheduled route  : ELIMINATED — the route read surface is now
+//                               tenant-scoped by construction (TenantModel),
+//                               so it needs no exception at all.
+const RAW_EXEMPT_FILES = new Set([
+  path.join('api', 'src', 'store', 'scoped.ts'),
+  path.join('api', 'src', 'libs', 'drivers', 'db.ts'),
+  path.join('api', 'src', 'store', 'sequelize.ts'),
+]);
+const RAW_EXEMPT_PATH = /(^|\/)(store\/migrations|store\/tenant-backfill)/;
+
+const ANY_QUERY = /\.query\s*\(/g;
+// The STATEMENT VERB — the first keyword inside the query's string literal —
+// decides DDL vs DML, so a DML SELECT can't hide behind a later `/* CREATE */`.
+const QUERY_VERB = /\.query\s*\(\s*[`'"]\s*(\w+)/;
+const DDL_VERBS = new Set(['PRAGMA', 'CREATE', 'ALTER', 'DROP', 'ATTACH', 'DETACH', 'REINDEX', 'VACUUM']);
+const TENANT_BIND = /[$:]instance_did\b/;
+const TENANT_TABLE_IN_SQL = new RegExp(`\\b(${TENANT_TABLES.join('|')})\\b`);
+
+const HOST_READ =
+  /\breq\s*\.\s*(?:headers\s*(?:\.\s*host\b|\[\s*['"]host['"]\s*\])|hostname\b|get\s*\(\s*['"]host['"])/gi;
+const HOST_READ_EXEMPT = [path.join('api', 'src', 'libs', 'middleware.ts')];
+
+function listFiles(dir) {
+  const out = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) out.push(...listFiles(full));
+    else if (entry.isFile() && full.endsWith('.ts')) out.push(full);
+  }
+  return out;
+}
+
+function stripLineComments(source) {
+  return source.replace(/\/\/[^\n]*/g, (m) => ' '.repeat(m.length));
+}
+
+function lineOf(source, index) {
+  return source.slice(0, index).split('\n').length;
+}
+
+// Assertion ① — scan model files: a tenant-table model must extend TenantModel.
+function scanModelExtends() {
+  const violations = [];
+  for (const file of listFiles(MODELS_DIR)) {
+    const source = stripLineComments(fs.readFileSync(file, 'utf8'));
+    const rel = path.relative(ROOT, file);
+    const re = /export\s+class\s+(\w+)\s+extends\s+(\w+)\s*</g;
+    let m;
+    // eslint-disable-next-line no-cond-assign
+    while ((m = re.exec(source))) {
+      const [, className, base] = m;
+      if (TENANT_MODEL_NAMES.has(className) && base !== 'TenantModel') {
+        violations.push({
+          file: rel,
+          line: lineOf(source, m.index),
+          call: `${className} extends ${base}`,
+          kind: 'model-not-tenant',
+        });
+      }
+    }
+  }
+  return violations;
+}
+
+// Assertion ② (+ Host rule) — per-file scan.
+function scanFile(file) {
+  const rel = path.relative(ROOT, file);
+  // Bad input: a file we cannot read/decode must FAIL LOUDLY, never be silently
+  // skipped (a silent skip would let an unscannable file hide a violation).
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    return [{ file: rel, line: 0, call: `unreadable file: ${err.message}`, kind: 'unreadable' }];
+  }
+  if (raw.includes('\x00') || raw.includes('\uFFFD')) {
+    return [{ file: rel, line: 0, call: 'unparseable (binary/non-utf8) file', kind: 'unreadable' }];
+  }
+  const source = stripLineComments(raw);
+  const violations = [];
+
+  const rawExempt = RAW_EXEMPT_FILES.has(rel) || RAW_EXEMPT_PATH.test(rel.replace(/\\/g, '/'));
+  if (!rawExempt) {
+    ANY_QUERY.lastIndex = 0;
+    let m;
+    // eslint-disable-next-line no-cond-assign
+    while ((m = ANY_QUERY.exec(source))) {
+      // Skip the HTTP query accessor `req.query(...)` / `c.req.query(...)` — it
+      // reads the request query string, not SQL. hono resource routes (Phase 3
+      // express→hono) call `c.req.query()` pervasively; without this guard the
+      // 600-char SQL window below catches a nearby tenant-model name and false-
+      // positives. A raw `sequelize.query(` is never preceded by `req`.
+      if (source.slice(m.index - 3, m.index) === 'req') continue;
+      // inspect the SQL window after the `.query(` opening
+      const sql = source.slice(m.index, m.index + 600);
+      const verb = (sql.match(QUERY_VERB)?.[1] || '').toUpperCase();
+      if (DDL_VERBS.has(verb)) continue; // schema op, not a tenant-row read
+      if (TENANT_TABLE_IN_SQL.test(sql) && !TENANT_BIND.test(sql)) {
+        violations.push({
+          file: rel,
+          line: lineOf(source, m.index),
+          call: 'raw .query on tenant table without $instance_did',
+          kind: 'raw-unguarded',
+        });
+      }
+    }
+  }
+
+  if (!HOST_READ_EXEMPT.includes(rel)) {
+    HOST_READ.lastIndex = 0;
+    let m;
+    // eslint-disable-next-line no-cond-assign
+    while ((m = HOST_READ.exec(source))) {
+      violations.push({ file: rel, line: lineOf(source, m.index), call: m[0].replace(/\s*\($/, ''), kind: 'host' });
+    }
+  }
+  return violations;
+}
+
+function main() {
+  const args = process.argv.slice(2);
+  const json = args.includes('--json');
+  const extraFiles = args.filter((a) => !a.startsWith('--'));
+
+  const whitelist = JSON.parse(fs.readFileSync(WHITELIST_FILE, 'utf8'));
+  const whitelisted = new Set(whitelist.map((entry) => entry.file));
+
+  const files = extraFiles.length ? extraFiles.map((f) => path.resolve(f)) : listFiles(SRC_DIR);
+
+  let violations = [];
+  let whitelistedCount = 0;
+  for (const file of files) {
+    const rel = path.relative(ROOT, file);
+    const found = scanFile(file);
+    if (!found.length) continue;
+    if (whitelisted.has(rel)) whitelistedCount += found.length;
+    else violations = violations.concat(found);
+  }
+
+  // Assertion ① runs over the canonical model dir (skip when scanning explicit
+  // extra files, e.g. the scanner self-test fixture).
+  if (!extraFiles.length) {
+    for (const v of scanModelExtends()) {
+      if (whitelisted.has(v.file)) whitelistedCount += 1;
+      else violations.push(v);
+    }
+  }
+
+  // a whitelist entry is stale when its file is clean (or gone) under the NEW rules
+  const stale = whitelist
+    .map((entry) => entry.file)
+    .filter((file) => {
+      const full = path.join(ROOT, file);
+      if (!fs.existsSync(full)) return true;
+      return scanFile(full).length === 0;
+    });
+
+  const result = { violations, whitelisted: whitelistedCount, staleWhitelistEntries: stale };
+  if (json) {
+    console.log(JSON.stringify(result));
+  } else {
+    for (const v of violations) {
+      const label =
+        v.kind === 'host'
+          ? 'host read outside tenant middleware'
+          : v.kind === 'model-not-tenant'
+            ? 'tenant model not extending TenantModel'
+            : 'raw query on tenant table missing $instance_did';
+      console.error(`${label}: ${v.file}:${v.line} ${v.call}`);
+    }
+    if (stale.length) console.error(`stale whitelist entries (remove them): ${stale.join(', ')}`);
+    console.log(`tenant-scan: ${violations.length} violations, ${whitelistedCount} whitelisted`);
+  }
+  process.exit(violations.length > 0 || stale.length > 0 ? 1 : 0);
+}
+
+main();

package/scripts/schema-drift-guard.ts

@@ -0,0 +1,210 @@
+/* eslint-disable no-console */
+// Phase 11 (W2′): schema-drift guard — the "done" gate for the D1 SQL migration
+// lineage (Path A). It builds two schemas from scratch and diffs them:
+//   - CANONICAL: the 75 Umzug TS migrations (api/src/store/migrations) run via
+//     api/src/store/migrate.ts — the authoritative blocklet-server SQLite schema.
+//   - D1 LINEAGE: the 7 cloudflare/migrations/*.sql applied to a fresh SQLite.
+// If the D1 lineage drifts (missing/extra tables, columns, or indexes), the SQL
+// lineage must be fixed — NOT switched to Umzug-on-D1.
+//
+//   npx tsx scripts/schema-drift-guard.ts
+// Exits non-zero on table/column drift (index drift is reported, warn-only).
+
+import { DatabaseSync } from 'node:sqlite';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { fromRandom } from '@ocap/wallet';
+import { types } from '@ocap/mcrypto';
+
+// Self-build a throwaway test blocklet env BEFORE importing the core: the
+// canonical (Umzug) import graph pulls auth/wallet (libs/auth.ts initializes a
+// wallet at import). This gate must NOT depend on the developer's machine env —
+// it provisions its own, like the e2e scripts.
+function setupTestEnv(): string {
+  const w = fromRandom({ role: types.RoleType.ROLE_APPLICATION });
+  const a = w.address;
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'drift-env-'));
+  Object.assign(process.env, {
+    ABT_NODE_DID: a,
+    ABT_NODE_PK: w.publicKey,
+    ABT_NODE_PORT: '8089',
+    ABT_NODE_SERVICE_PORT: '40406',
+    BLOCKLET_MODE: 'test',
+    BLOCKLET_DID: a,
+    BLOCKLET_COMPONENT_DID: a,
+    BLOCKLET_APP_SK: w.secretKey,
+    BLOCKLET_APP_PSK: w.secretKey,
+    BLOCKLET_APP_PK: w.publicKey,
+    BLOCKLET_APP_EK: w.secretKey,
+    BLOCKLET_APP_ID: a,
+    BLOCKLET_APP_PID: a,
+    BLOCKLET_APP_IDS: a,
+    BLOCKLET_APP_NAME: 'payment-kit',
+    BLOCKLET_APP_DESCRIPTION: 'payment-kit',
+    BLOCKLET_APP_URL: 'http://127.0.0.1:3030',
+    BLOCKLET_DATA_DIR: dir,
+    BLOCKLET_LOG_DIR: dir,
+    BLOCKLET_APP_DIR: dir,
+    BLOCKLET_MOUNT_POINTS: '[]',
+  });
+  return dir;
+}
+
+type Column = { name: string; type: string; notnull: number; pk: number };
+type TableSchema = { columns: Column[]; indexes: string[] };
+type Schema = Record<string, TableSchema>;
+
+const META_TABLES = new Set(['SequelizeMeta', 'd1_migrations', 'sqlite_sequence']);
+// D1-only infrastructure tables: the standalone worker owns its locks + DID-Connect
+// token storage as real tables; the blocklet server gets those from the blocklet
+// runtime, so they never appear in the Umzug canonical. Not business-schema drift.
+const D1_INFRA_TABLES = new Set(['_locks', '_did_connect_tokens']);
+// `*_tmp` tables are transient SQLite rebuild scaffolding (ALTER-via-recreate);
+// if one survives in a final schema it's a migration leftover, not real schema.
+const isArtifact = (n: string) => n.endsWith('_tmp');
+const isUserTable = (n: string) =>
+  !n.startsWith('sqlite_') && !META_TABLES.has(n) && !D1_INFRA_TABLES.has(n) && !isArtifact(n);
+
+// Normalize index columns into a stable signature so the two engines compare
+// equal regardless of index NAME (the SQL lineage and Umzug may name them
+// differently); we compare the set of indexed-column-tuples per table.
+function indexSignature(cols: string[]): string {
+  return cols.join(',');
+}
+
+function dump(query: (sql: string) => any[]): Schema {
+  const tables = query("SELECT name FROM sqlite_master WHERE type='table' ORDER BY name")
+    .map((r: any) => r.name)
+    .filter(isUserTable);
+  const schema: Schema = {};
+  for (const t of tables) {
+    const columns: Column[] = query(`PRAGMA table_info("${t}")`)
+      .map((c: any) => ({ name: c.name, type: String(c.type || '').toUpperCase(), notnull: c.notnull, pk: c.pk }))
+      .sort((a: Column, b: Column) => a.name.localeCompare(b.name));
+    const idxList = query(`PRAGMA index_list("${t}")`);
+    const indexes: string[] = [];
+    for (const idx of idxList) {
+      const info = query(`PRAGMA index_info("${idx.name}")`);
+      indexes.push(indexSignature(info.map((i: any) => i.name)));
+    }
+    schema[t] = { columns, indexes: [...new Set(indexes)].sort() };
+  }
+  return schema;
+}
+
+async function canonicalSchema(): Promise<Schema> {
+  // run the 75 Umzug TS migrations against a throwaway temp SQLite
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'drift-canon-'));
+  process.env.BLOCKLET_DATA_DIR = tmp;
+  process.env.BLOCKLET_LOG_DIR = tmp;
+  // eslint-disable-next-line global-require, import/no-dynamic-require
+  const { sequelize } = require('../api/src/store/sequelize');
+  // eslint-disable-next-line global-require
+  const migrate = require('../api/src/store/migrate').default;
+  await migrate();
+  // dump via a direct sync handle to the same file the sequelize migrations wrote
+  const dbFile = path.join(tmp, 'payment-kit.db');
+  await sequelize.close();
+  const db = new DatabaseSync(dbFile);
+  const schema = dump((sql) => db.prepare(sql).all() as any[]);
+  db.close();
+  fs.rmSync(tmp, { recursive: true, force: true });
+  return schema;
+}
+
+function d1Schema(): Schema {
+  const db = new DatabaseSync(':memory:');
+  const dir = path.resolve(__dirname, '../cloudflare/migrations');
+  const files = fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.sql'))
+    .sort();
+  for (const f of files) {
+    const sql = fs.readFileSync(path.join(dir, f), 'utf8');
+    db.exec(sql); // node:sqlite exec runs a multi-statement script
+  }
+  const schema = dump((sql) => db.prepare(sql).all() as any[]);
+  db.close();
+  return schema;
+}
+
+function diff(canon: Schema, d1: Schema) {
+  const drift: { tables: any; columns: any; indexes: any } = { tables: {}, columns: {}, indexes: {} };
+  const canonTables = new Set(Object.keys(canon));
+  const d1Tables = new Set(Object.keys(d1));
+  const missingInD1 = [...canonTables].filter((t) => !d1Tables.has(t));
+  const extraInD1 = [...d1Tables].filter((t) => !canonTables.has(t));
+  if (missingInD1.length) drift.tables.missing_in_d1 = missingInD1;
+  if (extraInD1.length) drift.tables.extra_in_d1 = extraInD1;
+
+  for (const t of [...canonTables].filter((x) => d1Tables.has(x))) {
+    const cCols = new Map(canon[t]!.columns.map((c) => [c.name, c]));
+    const dCols = new Map(d1[t]!.columns.map((c) => [c.name, c]));
+    const missingCols = [...cCols.keys()].filter((c) => !dCols.has(c));
+    const extraCols = [...dCols.keys()].filter((c) => !cCols.has(c));
+    if (missingCols.length || extraCols.length) {
+      drift.columns[t] = {
+        ...(missingCols.length ? { missing_in_d1: missingCols } : {}),
+        ...(extraCols.length ? { extra_in_d1: extraCols } : {}),
+      };
+    }
+    // index drift (warn-only): compare the set of indexed-column signatures
+    const cIdx = new Set(canon[t]!.indexes);
+    const dIdx = new Set(d1[t]!.indexes);
+    const missingIdx = [...cIdx].filter((i) => !dIdx.has(i) && i !== '');
+    if (missingIdx.length) drift.indexes[t] = { missing_in_d1: missingIdx };
+  }
+  return drift;
+}
+
+async function main() {
+  setupTestEnv();
+  const canon = await canonicalSchema();
+  const d1 = d1Schema();
+  console.log(JSON.stringify({ canonical_tables: Object.keys(canon).length, d1_tables: Object.keys(d1).length }));
+  const drift = diff(canon, d1);
+
+  // HARD GATE = anything the canonical has that D1 is MISSING (the worker would
+  // fail to write it). Extra-in-D1 (rebuild leftovers) and index diffs are
+  // WARN-only: inert for model reads/writes, and dropping columns on a deployed
+  // D1 is destructive — cleaned up separately if ever needed.
+  const missingTables = drift.tables.missing_in_d1 || [];
+  const missingCols = Object.entries(drift.columns).filter(([, v]: any) => v.missing_in_d1);
+  const extraTables = drift.tables.extra_in_d1 || [];
+  const extraCols = Object.entries(drift.columns).filter(([, v]: any) => v.extra_in_d1);
+
+  const hardFail = missingTables.length > 0 || missingCols.length > 0;
+
+  if (missingTables.length) console.log(JSON.stringify({ HARD_missing_tables_in_d1: missingTables }, null, 2));
+  if (missingCols.length)
+    console.log(
+      JSON.stringify(
+        { HARD_missing_columns_in_d1: Object.fromEntries(missingCols.map(([t, v]: any) => [t, v.missing_in_d1])) },
+        null,
+        2
+      )
+    );
+  if (extraTables.length) console.log(JSON.stringify({ WARN_extra_tables_in_d1: extraTables }));
+  if (extraCols.length)
+    console.log(
+      JSON.stringify({
+        WARN_extra_columns_in_d1: Object.fromEntries(extraCols.map(([t, v]: any) => [t, v.extra_in_d1])),
+      })
+    );
+  if (Object.keys(drift.indexes).length) console.log(JSON.stringify({ WARN_missing_indexes_in_d1: drift.indexes }));
+
+  console.log(
+    JSON.stringify({
+      success: !hardFail,
+      hard_gate: 'no canonical table/column missing in D1',
+      warns: { extra_in_d1: 'inert leftovers', indexes: 'perf-only' },
+    })
+  );
+  if (hardFail) process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(JSON.stringify({ success: false, error: String(err?.stack || err) }));
+  process.exit(1);
+});

package/scripts/tenant-scan-whitelist.json

@@ -0,0 +1 @@
+[]

package/src/env.d.ts

@@ -1,10 +1,22 @@
 declare var blocklet: {
+  appId: string;
+  appPk: string;
   appName: string;
   appLogo: string;
   appUrl: string;
   prefix: string;
   languages: { code: string; name: string }[];
-  preferences: { overdraftProtectionMaxCount: number };
+  preferences: { overdraftProtectionMaxCount: number; [key: string]: any };
+  componentMountPoints: Array<{
+    appId?: string;
+    did?: string;
+    appName?: string;
+    appLogo?: string;
+    appUrl?: string;
+    [key: string]: any;
+  }>;
+  PAYMENT_CHANGE_LOCKED_PRICE?: string;
+  [key: string]: any;
 };
 
 declare module '*.svg';

package/tsconfig.json

@@ -33,7 +33,7 @@
     // "moduleResolution": "node",                       /* Specify how TypeScript looks up a file from a given module specifier. */
     // "rootDirs": [],                                   /* Allow multiple folders to be treated as one when resolving modules. */
     // "typeRoots": [],                                  /* Specify multiple folders that act like './node_modules/@types'. */
-    "types": ["node", "react", "react-dom", "express", "cookie-parser", "cors", "debug", "dotenv-flow", "jest"],  /* Only include types explicitly used by this package */
+    "types": ["node", "react", "react-dom", "debug", "dotenv-flow", "jest"],  /* Only include types explicitly used by this package */
     // "allowUmdGlobalAccess": true,                     /* Allow accessing UMD globals from modules. */
     // "moduleSuffixes": [],                             /* List of file name suffixes to search when resolving a module. */
     // "resolveJsonModule": true,                        /* Enable importing .json files. */