@starci/hfs 4.0.8 → 4.0.9

package/runtime/scripts/hfs/architecture/sql-returning.mjs

@@ -0,0 +1,64 @@
+import path from 'node:path';
+import { HOLE, tokenizeSql } from './sql-tokens.mjs';
+import { machineKit } from './machine-ast.mjs';
+
+/**
+ * R181 `sql-returning` (BE_SQL_RETURNING_SHAPE). TypeORM's `EntityManager.query` returns an UPDATE or DELETE with RETURNING as
+ * `[rows, affectedCount]`, not as rows (an INSERT ... RETURNING returns rows), so a caller that reads the result as rows silently reads
+ * the wrong thing and no unit spec that stubs the SQL can see it. Every `sql` tagged template (the tag declared in platform/database) of a
+ * `<name>.sql.ts` file in a capability's `persistence/` is read with the tokenizer of sql-tokens.mjs, split into statements at top-level
+ * semicolons, and a statement that STARTS with UPDATE or DELETE and carries RETURNING at the top level is refused: write it as
+ * `WITH changed AS (UPDATE ... RETURNING ...) SELECT ... FROM changed`, which returns rows. A RETURNING inside a parenthesised CTE is the
+ * wrapped form and passes; so does INSERT ... RETURNING and any statement without RETURNING.
+ */
+export const SQL_RETURNING_RULE_IDS = ['BE_SQL_RETURNING_SHAPE'];
+
+const RULE = 'BE_SQL_RETURNING_SHAPE';
+
+/** The leading verbs of the top-level statements of `text` that RETURN from an UPDATE or DELETE without a wrapping SELECT. */
+function unwrappedReturning(text) {
+  const found = [];
+  let depth = 0;
+  let verb = null;
+  let returning = false;
+  const close = () => { if (verb && returning) found.push(verb); verb = null; returning = false; };
+  for (const token of tokenizeSql(text)) {
+    if (token.t === 'punct') {
+      if (token.v === '(') depth += 1;
+      else if (token.v === ')') depth = Math.max(0, depth - 1);
+      else if (token.v === ';' && depth === 0) close();
+      continue;
+    }
+    if (depth !== 0 || token.t !== 'word') continue;
+    if (verb === null) verb = token.up;
+    else if (token.up === 'RETURNING') returning = true;
+  }
+  close();
+  return found.filter(verb => verb === 'UPDATE' || verb === 'DELETE');
+}
+
+export function checkSqlReturning(input) {
+  const { graph } = input;
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  let templates = 0;
+  for (const file of graph.files.values()) {
+    if (file.slot !== 'be.persistence' || !path.posix.basename(file.rel).endsWith('.sql.ts') || !file.owner) continue;
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, node => {
+      if (!ts.isTaggedTemplateExpression(node)) return true;
+      const home = kit.declarationsOf(checker, node.tag).map(kit.ownerOfDeclaration).find(Boolean);
+      if (!home || home.tier !== 'platform' || home.name !== 'database') return true;
+      templates += 1;
+      const template = node.template;
+      const text = ts.isNoSubstitutionTemplateLiteral(template) ? template.text
+        : template.head.text + template.templateSpans.map(span => HOLE + span.literal.text).join('');
+      for (const verb of unwrappedReturning(text)) {
+        violations.push({ ruleId: RULE, path: file.rel, ...kit.at(file.rel, file.sourceFile, node), message: `${verb} ... RETURNING in ${file.rel} is returned by EntityManager.query as [rows, affectedCount], not as rows, so a caller reading rows reads the wrong value. Wrap it: WITH changed AS (${verb} ... RETURNING ...) SELECT ... FROM changed.`, verb });
+      }
+      return true;
+    });
+  }
+  return { violations, coverage: { status: 'checked', templates } };
+}

package/runtime/scripts/hfs/architecture/supabase-ast.mjs

@@ -0,0 +1,111 @@
+// supabase-ast.mjs - shared TypeScript-symbol and expression helpers for the front-end and back-end Supabase
+// architecture checks. Recognition follows imported declarations and inferred types, never local spelling alone.
+export const SUPABASE_MODULES = new Set(['@supabase/ssr', '@supabase/supabase-js']);
+
+export const moduleNameOf = (ts, node) => {
+  if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteralLike(node.moduleSpecifier)) return node.moduleSpecifier.text;
+  if (!ts.isCallExpression(node)) return null;
+  const dynamic = node.expression.kind === ts.SyntaxKind.ImportKeyword;
+  const required = ts.isIdentifier(node.expression) && node.expression.text === 'require';
+  return (dynamic || required) && node.arguments.length === 1 && ts.isStringLiteralLike(node.arguments[0]) ? node.arguments[0].text : null;
+};
+
+export const importedFrom = (kit, checker, node, modules, names = null) => {
+  const binding = kit.importBinding(checker, node);
+  return Boolean(binding && modules.has(binding.module) && (names === null || names.has(binding.name)));
+};
+
+const declarationFromSupabase = (declaration) => /(?:^|\/)node_modules\/@supabase\/(?:ssr|supabase-js|auth-js|postgrest-js|storage-js)(?:\/|$)/u
+  .test(String(declaration?.getSourceFile?.().fileName ?? '').replace(/\\/gu, '/'));
+
+const typeFromSupabase = (checker, node) => {
+  let type;
+  try { type = checker.getTypeAtLocation(node); } catch { return false; }
+  const queue = [type];
+  const seen = new Set();
+  while (queue.length) {
+    const item = queue.shift();
+    if (!item || seen.has(item)) continue;
+    seen.add(item);
+    if ([item.symbol, item.aliasSymbol].some((symbol) => symbol?.declarations?.some(declarationFromSupabase))) return true;
+    if (item.types) queue.push(...item.types);
+    if (item.target && item.target !== item) queue.push(item.target);
+  }
+  return false;
+};
+
+export const signatureFromSupabase = (checker, call) => {
+  try { return declarationFromSupabase(checker.getResolvedSignature(call)?.declaration); } catch { return false; }
+};
+
+export const unwrap = (ts, node) => {
+  let current = node;
+  while (current && (ts.isParenthesizedExpression(current) || ts.isAwaitExpression(current) || ts.isAsExpression(current)
+    || ts.isTypeAssertionExpression(current) || ts.isNonNullExpression(current))) current = current.expression;
+  return current;
+};
+
+export const isSupabaseValue = (kit, checker, node) => {
+  const current = unwrap(kit.ts, node);
+  if (!current) return false;
+  if (importedFrom(kit, checker, current, SUPABASE_MODULES)) return true;
+  if (kit.ts.isCallExpression(current) && signatureFromSupabase(checker, current)) return true;
+  return typeFromSupabase(checker, current);
+};
+
+export const callName = (ts, call) => ts.isCallExpression(call) && ts.isPropertyAccessExpression(call.expression) ? call.expression.name.text : null;
+
+export const chainParts = (ts, expression) => {
+  const names = [];
+  let current = unwrap(ts, expression);
+  while (current) {
+    if (ts.isCallExpression(current)) {
+      if (ts.isPropertyAccessExpression(current.expression)) {
+        names.unshift(current.expression.name.text);
+        current = unwrap(ts, current.expression.expression);
+        continue;
+      }
+      current = unwrap(ts, current.expression);
+      continue;
+    }
+    if (ts.isPropertyAccessExpression(current)) {
+      names.unshift(current.name.text);
+      current = unwrap(ts, current.expression);
+      continue;
+    }
+    break;
+  }
+  return names;
+};
+
+export const isSupabaseCall = (kit, checker, node) => kit.ts.isCallExpression(node)
+  && (signatureFromSupabase(checker, node) || isSupabaseValue(kit, checker, kit.ts.isPropertyAccessExpression(node.expression) ? node.expression.expression : node.expression));
+
+export const isDatabaseType = (ts, node) => {
+  if (!node) return false;
+  if (ts.isTypeReferenceNode(node)) {
+    const name = ts.isIdentifier(node.typeName) ? node.typeName.text : node.typeName.right.text;
+    return name === 'Database';
+  }
+  return false;
+};
+
+export const supabaseClientType = (kit, checker, node) => {
+  if (!node || !kit.ts.isTypeReferenceNode(node)) return false;
+  const name = kit.ts.isIdentifier(node.typeName) ? node.typeName : null;
+  return Boolean(name && importedFrom(kit, checker, name, SUPABASE_MODULES, new Set(['SupabaseClient'])));
+};
+
+export const contextTypesClient = (kit, checker, call) => {
+  let parent = call.parent;
+  while (parent && (kit.ts.isParenthesizedExpression(parent) || kit.ts.isAsExpression(parent))) {
+    if (kit.ts.isAsExpression(parent) && supabaseClientType(kit, checker, parent.type) && isDatabaseType(kit.ts, parent.type.typeArguments?.[0])) return true;
+    parent = parent.parent;
+  }
+  return kit.ts.isVariableDeclaration(parent) && supabaseClientType(kit, checker, parent.type)
+    && isDatabaseType(kit.ts, parent.type.typeArguments?.[0]);
+};
+
+export const reportAt = (violations, kit, ruleId, file, node, message, extra = {}) => {
+  violations.push({ ruleId, ...kit.at(file.rel, file.sourceFile, node), message, ...extra });
+};

package/runtime/scripts/hfs/architecture/supabase-be.mjs

@@ -0,0 +1,131 @@
+// supabase-be.mjs - the back-end half of the slot-driven Supabase architecture machine: a single integration owns
+// JWT verification, pins the remote JWKS/issuer/audience/algorithms, and never trusts authorization claims from a body.
+import path from 'node:path';
+import { machineKit } from './machine-ast.mjs';
+import { importedFrom, reportAt, unwrap } from './supabase-ast.mjs';
+
+const BE_SUPABASE_SLOT = 'be.integrations.supabase';
+const BE_JWT_VERIFIED = 'BE_SUPABASE_JWT_VERIFIED';
+const JWT_MODULES = new Set(['jose', 'jsonwebtoken', 'jwt-decode']);
+const CLAIM_NAMES = new Set(['role', 'roles', 'membership', 'memberships']);
+
+const objectLiteral = (kit, checker, node) => {
+  const current = unwrap(kit.ts, node);
+  if (kit.ts.isObjectLiteralExpression(current)) return current;
+  if (!kit.ts.isIdentifier(current)) return null;
+  for (const declaration of kit.declarationsOf(checker, current)) {
+    if (kit.ts.isVariableDeclaration(declaration) && declaration.initializer) {
+      const value = unwrap(kit.ts, declaration.initializer);
+      if (kit.ts.isObjectLiteralExpression(value)) return value;
+    }
+  }
+  return null;
+};
+
+const staticStrings = (kit, checker, node) => {
+  const current = unwrap(kit.ts, node);
+  if (kit.ts.isStringLiteralLike(current)) return [current.text];
+  if (kit.ts.isArrayLiteralExpression(current) && current.elements.every((element) => kit.ts.isStringLiteralLike(element))) return current.elements.map((element) => element.text);
+  const value = kit.stringValue(checker, current);
+  return value === null ? null : [value];
+};
+
+const jwksArgument = (kit, checker, node) => {
+  const current = unwrap(kit.ts, node);
+  if (kit.ts.isCallExpression(current)) return importedFrom(kit, checker, current.expression, new Set(['jose']), new Set(['createRemoteJWKSet']));
+  if (!kit.ts.isIdentifier(current)) return false;
+  return kit.declarationsOf(checker, current).some((declaration) => kit.ts.isVariableDeclaration(declaration) && declaration.initializer
+    && jwksArgument(kit, checker, declaration.initializer));
+};
+
+const importedCall = (kit, checker, call) => {
+  const direct = kit.importBinding(checker, call.expression);
+  if (direct?.module === 'jwt-decode' && direct.name === 'default') return { module: direct.module, name: 'jwtDecode' };
+  if (direct) return direct;
+  if (!kit.ts.isPropertyAccessExpression(call.expression) || !kit.ts.isIdentifier(call.expression.expression)) return null;
+  const owner = kit.importBinding(checker, call.expression.expression);
+  return owner?.name === 'default' ? { module: owner.module, name: call.expression.name.text } : null;
+};
+
+const accessName = (ts, node) => {
+  if (ts.isPropertyAccessExpression(node)) return node.name.text;
+  if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) return node.argumentExpression.text;
+  return null;
+};
+
+const requestLike = (ts, node) => {
+  const current = unwrap(ts, node);
+  if (ts.isIdentifier(current)) return /^(?:req|request)$/iu.test(current.text);
+  return (ts.isPropertyAccessExpression(current) || ts.isElementAccessExpression(current)) && accessName(ts, current) === 'request';
+};
+
+const fromRequestBody = (kit, checker, node, seen = new Set()) => {
+  const current = unwrap(kit.ts, node);
+  if (!current || seen.has(current)) return false;
+  seen.add(current);
+  if (kit.ts.isPropertyAccessExpression(current) || kit.ts.isElementAccessExpression(current)) {
+    if (accessName(kit.ts, current) === 'body' && requestLike(kit.ts, current.expression)) return true;
+    return fromRequestBody(kit, checker, current.expression, seen);
+  }
+  if (!kit.ts.isIdentifier(current)) return false;
+  return kit.declarationsOf(checker, current).some(declaration => kit.ts.isVariableDeclaration(declaration) && declaration.initializer
+    && fromRequestBody(kit, checker, declaration.initializer, seen));
+};
+
+export function checkBackendJwt(input) {
+  const kit = machineKit(input);
+  const { ts } = kit;
+  const violations = [];
+  const integrations = [...input.graph.files.values()].filter((file) => file.slot === BE_SUPABASE_SLOT);
+  if (!integrations.length) return { violations, coverage: { status: 'not-applicable', integrationFiles: 0, verifiedCalls: 0 } };
+  let verifyCalls = 0;
+  let verifiedCalls = 0;
+  for (const file of input.graph.files.values()) {
+    const checker = kit.checkerOf(file.sourceFile);
+    kit.walk(file.sourceFile, (node) => {
+      if (ts.isCallExpression(node)) {
+        const binding = importedCall(kit, checker, node);
+        if (binding && JWT_MODULES.has(binding.module) && ['decode', 'decodeJwt', 'jwtDecode'].includes(binding.name)) {
+          reportAt(violations, kit, BE_JWT_VERIFIED, file, node, `${binding.module}.${binding.name} decodes a token without proving its signature; use the Supabase JWKS verifier.`, { module: binding.module, method: binding.name });
+        }
+        if (binding?.module === 'jose' && binding.name === 'jwtVerify') {
+          verifyCalls += 1;
+          if (file.slot !== BE_SUPABASE_SLOT) {
+            reportAt(violations, kit, BE_JWT_VERIFIED, file, node, `jwtVerify is called outside ${BE_SUPABASE_SLOT}; the integration is the one token verifier.`);
+            return true;
+          }
+          const options = objectLiteral(kit, checker, node.arguments[2]);
+          const property = (name) => options ? kit.propertyOf(options, name) : null;
+          const values = (name) => {
+            const entry = property(name);
+            return entry ? staticStrings(kit, checker, kit.valueOfProperty(entry)) : null;
+          };
+          const issuer = property('issuer');
+          const audience = values('audience');
+          const algorithms = values('algorithms');
+          const good = jwksArgument(kit, checker, node.arguments[1]) && issuer != null && audience?.includes('authenticated')
+            && algorithms !== null && algorithms.length > 0;
+          if (!good) {
+            reportAt(violations, kit, BE_JWT_VERIFIED, file, node, 'Supabase jwtVerify must use createRemoteJWKSet(...) and pin issuer, audience `authenticated`, and a non-empty algorithms list; jwtVerify then enforces signature and exp.');
+          } else verifiedCalls += 1;
+        }
+      }
+      if ((ts.isPropertyAccessExpression(node) || ts.isElementAccessExpression(node)) && CLAIM_NAMES.has(accessName(ts, node))) {
+        const claim = accessName(ts, node);
+        if (fromRequestBody(kit, checker, node.expression)) reportAt(violations, kit, BE_JWT_VERIFIED, file, node, `${claim} is read from the request body; authorization claims come only from the verified token or the database.`, { claim });
+      }
+      if (ts.isVariableDeclaration(node) && ts.isObjectBindingPattern(node.name) && node.initializer && fromRequestBody(kit, checker, node.initializer)) {
+        for (const element of node.name.elements) {
+          const property = element.propertyName ?? element.name;
+          if (ts.isIdentifier(property) && CLAIM_NAMES.has(property.text)) reportAt(violations, kit, BE_JWT_VERIFIED, file, element, `${property.text} is destructured from the request body; authorization claims come only from the verified token or the database.`, { claim: property.text });
+        }
+      }
+      return true;
+    });
+  }
+  if (verifyCalls === 0) {
+    const anchor = integrations.find((file) => path.posix.basename(file.rel).endsWith('.jwks.ts')) ?? integrations[0];
+    reportAt(violations, kit, BE_JWT_VERIFIED, anchor, anchor.sourceFile, `${BE_SUPABASE_SLOT} has no jose.jwtVerify call backed by createRemoteJWKSet.`);
+  }
+  return { violations, coverage: { status: 'checked', integrationFiles: integrations.length, verifyCalls, verifiedCalls } };
+}

package/runtime/scripts/hfs/architecture/supabase-tables.mjs

@@ -0,0 +1,42 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const CACHE = new Map();
+
+/** A static TypeScript property name, as emitted by `supabase gen types typescript`. */
+const propertyName = (typescript, name) => (typescript.isIdentifier(name) || typescript.isStringLiteralLike(name) ? name.text : null);
+
+/** The type-literal members below property `name`, or null when the generated shape is not statically readable. */
+const propertyMembers = (typescript, members, name) => {
+  const property = members.find(member => typescript.isPropertySignature(member) && propertyName(typescript, member.name) === name);
+  return property?.type && typescript.isTypeLiteralNode(property.type) ? property.type.members : null;
+};
+
+/**
+ * The lower-case keys of `Database['public']['Tables']`, parsed with the architecture context's target compiler.
+ * An absent, malformed or unreadable contract proves no table. The result is cached once per app root.
+ */
+export function supabaseTablesOf(appRoot, typescript) {
+  const root = path.resolve(appRoot);
+  if (CACHE.has(root)) return CACHE.get(root);
+  const tables = new Set();
+  const file = path.join(root, 'supabase', 'types', 'database.types.ts');
+  try {
+    const source = typescript.createSourceFile(file, fs.readFileSync(file, 'utf8'), typescript.ScriptTarget.Latest, true, typescript.ScriptKind.TS);
+    if (source.parseDiagnostics.length === 0) {
+      const database = source.statements.find(statement => typescript.isTypeAliasDeclaration(statement) && statement.name.text === 'Database');
+      const databaseMembers = database && typescript.isTypeLiteralNode(database.type) ? database.type.members : null;
+      const publicMembers = databaseMembers ? propertyMembers(typescript, databaseMembers, 'public') : null;
+      const tableMembers = publicMembers ? propertyMembers(typescript, publicMembers, 'Tables') : null;
+      if (tableMembers) for (const member of tableMembers) {
+        if (!typescript.isPropertySignature(member)) continue;
+        const name = propertyName(typescript, member.name);
+        if (name) tables.add(name.toLowerCase());
+      }
+    }
+  } catch {
+    // Missing and unreadable generated contracts are fail-closed: no table is proven.
+  }
+  CACHE.set(root, tables);
+  return tables;
+}