nsa-sheets-db-builder 4.0.0

package/src/templates/main.ts.ejs

@@ -0,0 +1,288 @@
+// ========================================
+// Sheets Deployer — Entry Point (POST-only)
+// Auto-generated by nsa-sheets-db-builder
+// Instance type: <%- instance_type %>
+<% if (rbac_enabled) { -%>
+// RBAC: enabled (auth mode: <%- auth_mode %>)
+<% } -%>
+<% if (views_enabled) { -%>
+// SQL Views: enabled (<%- view_names.length %> view(s))
+<% } -%>
+// ========================================
+
+function getLogger(): any {
+  if (typeof GASLoggerV2 !== 'undefined') {
+    return new GASLoggerV2(DEPLOYER_CONFIG.name, null, LOGGING_VERBOSITY_LEVEL, '');
+  }
+  return {
+    info: (src: string, msg: string, ctx?: any) => console.log(`[INFO] ${src}: ${msg}`),
+    warn: (src: string, msg: string, ctx?: any) => console.warn(`[WARN] ${src}: ${msg}`),
+    error: (err: any) => console.error(`[ERROR]`, err?.message || err),
+    debug: (src: string, msg: string, ctx?: any) => {},
+    getTraceId: () => ''
+  };
+}
+
+// ── Auth ──────────────────────────────────
+
+function validateApiKey(key: string): boolean {
+  const storedKey = PropertiesService.getScriptProperties().getProperty('DDL_API_KEY');
+  if (!storedKey) return false;
+  return key === storedKey;
+}
+
+// ── Response Helper ───────────────────────
+
+function jsonResponse(data: any): GoogleAppsScript.Content.TextOutput {
+  return ContentService
+    .createTextOutput(JSON.stringify(data))
+    .setMimeType(ContentService.MimeType.JSON);
+}
+
+// ── DB Instance Helper ──────────────────────
+
+function getDb(logger: any): any {
+  const systemSpreadsheetId = DEPLOYER_CONFIG.systemSpreadsheetId;
+  const tables = typeof DB_SCHEMA !== 'undefined' ? DB_SCHEMA : {};
+
+  return new DBV2({
+    name: DEPLOYER_CONFIG.name,
+    systemSpreadsheetId,
+    tables,
+    loggingVerbosity: DEPLOYER_CONFIG.loggingVerbosity
+  } as DBConfigV2, logger);
+}
+
+// ── POST Handler ──────────────────────────
+
+function doPost(e: GoogleAppsScript.Events.DoPost): GoogleAppsScript.Content.TextOutput {
+  const logger = getLogger();
+
+  try {
+    const body = JSON.parse(e?.postData?.contents || '{}');
+
+    // Validate API key
+    if (!validateApiKey(body.apiKey)) {
+      logger.warn('doPost', 'Unauthorized request — invalid API key');
+      return jsonResponse({ error: 'Unauthorized: invalid API key' });
+    }
+
+    // ── DDL Admin Actions (per-script ops only) ────
+    // Generic DDL operations (setup, provision, sync, etc.) are handled
+    // by the shared DDL handler web app. This endpoint only handles
+    // per-script operations that need PropertiesService / CacheService / ScriptApp.
+    if (body.ddlAction) {
+      const adminKey = DEPLOYER_CONFIG.ddlAdminKey;
+      if (!adminKey || body.ddlKey !== adminKey) {
+        return jsonResponse({ error: 'Unauthorized: invalid DDL admin key' });
+      }
+      const allowed = [
+        'ddlRotateApiKey', 'ddlSetApiKey', 'ddlGetApiKey',
+        'ddlCacheSchema', 'ddlGetCachedSchema', 'ddlInvalidateCache', 'ddlRefreshCache',
+        'ddlSetupCacheTrigger', 'ddlRemoveCacheTrigger'
+      ];
+      if (!allowed.includes(body.ddlAction)) {
+        return jsonResponse({ error: `DDL action "${body.ddlAction}" not available on this endpoint` });
+      }
+      const fn = (globalThis as any)[body.ddlAction];
+      if (typeof fn !== 'function') {
+        return jsonResponse({ error: `Unknown DDL function: ${body.ddlAction}` });
+      }
+      return jsonResponse(fn(body.params));
+    }
+
+    const action = body.action;
+    if (!action) {
+      return jsonResponse({ error: 'Missing "action" parameter' });
+    }
+
+    // ── Status ──────────────────────────
+    if (action === 'status') {
+      return jsonResponse({
+        status: 'ok',
+        name: DEPLOYER_CONFIG.name,
+        env: DEPLOYER_CONFIG.env,
+        instanceType: DEPLOYER_CONFIG.instanceType<% if (rbac_enabled) { %>,
+        rbac: true,
+        authMode: '<%- auth_mode %>'<% } %><% if (views_enabled) { %>,
+        views: [<%- view_names.map(v => `'${v}'`).join(', ') %>]<% } %>
+      });
+    }
+
+<% if (rbac_enabled) { -%>
+    // ── Resolve User ─────────────────────
+    const db = getDb(logger);
+    const currentUser = resolveUser(body, db);
+    if (!currentUser) {
+      logger.warn('doPost', 'RBAC: could not resolve user identity');
+      return jsonResponse({ error: 'Unauthorized: user identity required' });
+    }
+<% } else { -%>
+    const db = getDb(logger);
+<% } -%>
+
+    // ══════════════════════════════════════
+    // CAPABILITY-BASED ROUTING
+    //
+    // All permissions use unified hasCapability() check:
+    //   "table:action"  — table CRUD     (e.g. "entries:list")
+    //   "view:name"     — SQL views      (e.g. "view:activeUsers")
+    //   "methodName"    — custom methods  (e.g. "getStats")
+    // ══════════════════════════════════════
+
+    // ── Table CRUD ───────────────────────
+    if (body.table) {
+      return handleCrudAction(action, body, db, logger<%- rbac_enabled ? ', currentUser' : '' %>);
+    }
+
+<% if (views_enabled) { -%>
+    // ── SQL Views ────────────────────────
+    if (action === 'listViews') {
+<% if (rbac_enabled) { -%>
+      const viewNames = Object.keys(VIEWS_CONFIG || {});
+      const available = viewNames.filter(v => hasCapability(currentUser.role, 'view:' + v));
+      return jsonResponse({ views: available });
+<% } else { -%>
+      return jsonResponse({ views: Object.keys(VIEWS_CONFIG || {}) });
+<% } -%>
+    }
+
+<% for (const viewName of view_names) { -%>
+    if (action === '<%- viewName %>') {
+<% if (rbac_enabled) { -%>
+      if (!hasCapability(currentUser.role, 'view:<%- viewName %>')) {
+        return jsonResponse({ error: 'Forbidden: missing capability "view:<%- viewName %>"' });
+      }
+      return jsonResponse(executeView('<%- viewName %>', db, body.params, currentUser));
+<% } else { -%>
+      return jsonResponse(executeView('<%- viewName %>', db, body.params));
+<% } -%>
+    }
+
+<% } -%>
+<% } -%>
+    // ── Custom Methods ───────────────────
+<% if (custom_methods && custom_methods.length > 0) { -%>
+<% for (const method of custom_methods) { -%>
+    if (action === '<%- method %>') {
+<% if (rbac_enabled) { -%>
+      if (!hasCapability(currentUser.role, '<%- method %>')) {
+        return jsonResponse({ error: `Forbidden: missing capability "<%- method %>"` });
+      }
+      return handle_<%- method %>(body, db, logger, currentUser);
+<% } else { -%>
+      return handle_<%- method %>(body, db, logger);
+<% } -%>
+    }
+
+<% } -%>
+<% } -%>
+    return jsonResponse({ error: `Unknown action: ${action}` });
+
+  } catch (err: any) {
+    logger.warn('doPost', 'Request failed', { error: String(err) });
+    return jsonResponse({ error: err.message || String(err) });
+  }
+}
+
+// ── CRUD Handler ──────────────────────────
+
+<% const isReader = instance_type === 'read-only' || instance_type === 'read-write'; -%>
+<% const isWriter = instance_type === 'write-only' || instance_type === 'read-write'; -%>
+
+function handleCrudAction(action: string, body: any, db: any, logger: any<%- rbac_enabled ? ', user: { email: string; role: string; id: string }' : '' %>): GoogleAppsScript.Content.TextOutput {
+  const tableName = body.table;
+
+  const table = db.table(tableName);
+  if (!table) {
+    return jsonResponse({ error: `Table "${tableName}" not found` });
+  }
+
+<% if (rbac_enabled) { -%>
+  // Capability check: "tableName:action"
+  if (!hasCapability(user.role, tableName + ':' + action)) {
+    return jsonResponse({ error: `Forbidden: missing capability "${tableName}:${action}"` });
+  }
+
+  // Row-level filter
+  const rbacFilter = resolveFilter(user.role, tableName, user);
+  const hasRbacFilter = Object.keys(rbacFilter).length > 0;
+
+<% } -%>
+  switch (action) {
+<% if (isReader) { -%>
+    case 'list': {
+<% if (rbac_enabled) { -%>
+      const userOptions = body.options || {};
+      const userFilters = userOptions.filters || {};
+      const mergedOptions = { ...userOptions, filters: { ...userFilters, ...rbacFilter } };
+      return jsonResponse(table.list(mergedOptions));
+<% } else { -%>
+      return jsonResponse(table.list(body.options || {}));
+<% } -%>
+    }
+
+    case 'get': {
+      if (!body.id) return jsonResponse({ error: 'Missing "id" for get action' });
+<% if (rbac_enabled) { -%>
+      const result = table.get(body.id);
+      if (hasRbacFilter && result?.data && !matchesFilter(result.data, rbacFilter)) {
+        return jsonResponse({ error: `Record not found: ${body.id}` });
+      }
+      return jsonResponse(result);
+<% } else { -%>
+      return jsonResponse(table.get(body.id));
+<% } -%>
+    }
+
+<% } -%>
+<% if (isWriter) { -%>
+    case 'create':
+      if (!body.data) return jsonResponse({ error: 'Missing "data" for create action' });
+      return jsonResponse(table.create(body.data));
+
+    case 'update': {
+      if (!body.id) return jsonResponse({ error: 'Missing "id" for update action' });
+      if (!body.data) return jsonResponse({ error: 'Missing "data" for update action' });
+<% if (rbac_enabled) { -%>
+      if (hasRbacFilter) {
+        const existing = table.get(body.id);
+        if (!existing?.data || !matchesFilter(existing.data, rbacFilter)) {
+          return jsonResponse({ error: `Record not found: ${body.id}` });
+        }
+      }
+<% } -%>
+      return jsonResponse(table.update(body.id, body.data));
+    }
+
+    case 'delete': {
+      if (!body.id) return jsonResponse({ error: 'Missing "id" for delete action' });
+<% if (rbac_enabled) { -%>
+      if (hasRbacFilter) {
+        const existing = table.get(body.id);
+        if (!existing?.data || !matchesFilter(existing.data, rbacFilter)) {
+          return jsonResponse({ error: `Record not found: ${body.id}` });
+        }
+      }
+<% } -%>
+      return jsonResponse(table.delete(body.id));
+    }
+
+<% } -%>
+<% if (views_enabled) { -%>
+    case 'query':
+      if (!body.view) return jsonResponse({ error: 'Missing "view" for query action' });
+<% if (rbac_enabled) { -%>
+      if (!hasCapability(user.role, 'view:' + body.view)) {
+        return jsonResponse({ error: `Forbidden: missing capability "view:${body.view}"` });
+      }
+      return jsonResponse(executeView(body.view, db, body.params, user));
+<% } else { -%>
+      return jsonResponse(executeView(body.view, db, body.params));
+<% } -%>
+
+<% } -%>
+    default:
+      return jsonResponse({ error: `Unknown or disallowed action "${action}" for instance type "<%- instance_type %>"` });
+  }
+}

package/src/templates/rbac.ts.ejs

@@ -0,0 +1,148 @@
+// ========================================
+// RBAC Middleware — Auto-generated by nsa-sheets-db-builder
+// Auth mode: <%- auth_mode %>
+// ========================================
+
+/**
+ * RBAC role definitions — loaded from rbac.json at build time.
+ *
+ * Per-role config:
+ *   capabilities — unified permission list (what you CAN DO)
+ *   filter       — per-table user ownership field (what you CAN SEE)
+ *
+ * Capability notation:
+ *   "entries:list"   — specific table + action
+ *   "entries:*"      — all actions on a table
+ *   "*:list"         — action on all tables
+ *   "*:*"            — all table actions
+ *   "view:myEntries" — specific SQL view
+ *   "view:*"         — all SQL views
+ *   "getStats"       — custom method (no colon)
+ *   "*"              — all custom methods
+ *
+ * Filter notation (privacy — row-level ownership):
+ *   "entries": "author_id"  — records filtered by author_id = user.id
+ *   Only declares the user field. For complex filtering, use views or custom methods.
+ */
+var RBAC_CONFIG = <%- JSON.stringify(rbac_config, null, 2) %>;
+
+// ── Auth ─────────────────────────────────
+
+/**
+ * Resolve the current user identity based on auth mode.
+ *
+ * @param body - The parsed request body
+ * @param db - DBV2 instance (for user/role lookups)
+ * @returns {{ email: string, role: string, id: string } | null}
+ */
+function resolveUser(body: any, db: any): { email: string; role: string; id: string } | null {
+<% if (auth_mode === 'noAuth') { -%>
+  return { email: 'system', role: 'admin', id: 'system' };
+<% } else if (auth_mode === 'google') { -%>
+  try {
+    const email = Session.getActiveUser().getEmail();
+    if (!email) return null;
+
+    const usersTable = db.table('users');
+    if (!usersTable) return null;
+
+    const allUsers = usersTable.list({ filters: { email: email, __archived__: false } });
+    const user = allUsers?.data?.[0];
+
+    if (!user) {
+      return { email, role: RBAC_CONFIG.defaultRole || 'viewer', id: '' };
+    }
+
+    return { email, role: user.role || RBAC_CONFIG.defaultRole || 'viewer', id: user.id || '' };
+  } catch (e) {
+    return null;
+  }
+<% } else { -%>
+  if (!body.user || !body.user.email) return null;
+
+  const email = body.user.email;
+  const passphrase = body.user.passphrase || '';
+
+  const usersTable = db.table('users');
+  if (!usersTable) return null;
+
+  const allUsers = usersTable.list({ filters: { email: email, __archived__: false } });
+  const user = allUsers?.data?.[0];
+
+  if (!user) return null;
+  if (user.passphrase && user.passphrase !== passphrase) return null;
+
+  return { email, role: user.role || RBAC_CONFIG.defaultRole || 'viewer', id: user.id || '' };
+<% } -%>
+}
+
+// ── Capabilities ─────────────────────────
+
+/**
+ * Check if a role has a capability.
+ *
+ * For table operations (contains ":"):
+ *   "entries:list" matches: entries:list, entries:*, *:list, *:*
+ *
+ * For custom methods (no ":"):
+ *   "getStats" matches: getStats, *
+ *
+ * @param role - Role name
+ * @param capability - "table:action" or "methodName"
+ */
+function hasCapability(role: string, capability: string): boolean {
+  const roleDef = RBAC_CONFIG.roles?.[role];
+  if (!roleDef || !Array.isArray(roleDef.capabilities)) return false;
+
+  const caps = roleDef.capabilities;
+
+  // Direct match
+  if (caps.includes(capability)) return true;
+
+  const colonIdx = capability.indexOf(':');
+
+  if (colonIdx === -1) {
+    // Custom method — check method wildcard
+    return caps.includes('*');
+  }
+
+  // Table capability — check wildcard patterns
+  const table = capability.substring(0, colonIdx);
+  const action = capability.substring(colonIdx + 1);
+
+  return caps.includes(table + ':*') ||
+         caps.includes('*:' + action) ||
+         caps.includes('*:*');
+}
+
+// ── Privacy (row-level ownership) ────────
+
+/**
+ * Resolve the user-ownership filter for a role + table.
+ *
+ * Filter config is a simple mapping: table name → user field name.
+ *   "entries": "author_id"  → { author_id: user.id }
+ *
+ * Returns empty object if no filter applies (no row-level restriction).
+ * For complex filtering logic, use SQL views or custom methods instead.
+ */
+function resolveFilter(role: string, tableName: string, user: { email: string; role: string; id: string }): Record<string, any> {
+  const roleDef = RBAC_CONFIG.roles?.[role];
+  if (!roleDef || !roleDef.filter) return {};
+
+  const userField = roleDef.filter[tableName];
+  if (!userField || typeof userField !== 'string') return {};
+
+  return { [userField]: user.id };
+}
+
+/**
+ * Check if a record belongs to the user (ownership check).
+ * Used for get/update/delete post-fetch validation.
+ */
+function matchesFilter(record: Record<string, any>, filter: Record<string, any>): boolean {
+  for (const key of Object.keys(filter)) {
+    if (record[key] !== filter[key]) return false;
+  }
+  return true;
+}

package/src/templates/views.ts.ejs

@@ -0,0 +1,92 @@
+// ========================================
+// Views Runtime — Auto-generated by nsa-sheets-db-builder
+// SQL views via alasql, with optional RBAC gating
+// ========================================
+
+/**
+ * View definitions — loaded from views.json at build time.
+ * Each view: { query, description?, roles?, params? }
+ */
+var VIEWS_CONFIG: Record<string, any> = <%- JSON.stringify(views_config, null, 2) %>;
+
+/**
+ * Execute a named view query against in-memory table data.
+ *
+ * Flow:
+ *   1. Load all referenced tables into alasql in-memory DB
+ *   2. Merge params: client params + server-injected $user.* (user wins — can't be spoofed)
+ *   3. Execute the view's SQL query with {{param}} substitution
+ *   4. Return the result set
+ *
+ * @param viewName - The view name (key in VIEWS_CONFIG)
+ * @param db - DBV2 instance
+ * @param params - Optional query parameters (for parameterized views)
+ * @param user - Optional authenticated user (injected by RBAC middleware)
+ * @returns { data: any[], viewName: string } | { error: string }
+ */
+function executeView(viewName: string, db: any, params?: Record<string, any>, user?: { email: string; role: string; id: string }): any {
+  const viewDef = VIEWS_CONFIG[viewName];
+  if (!viewDef) {
+    return { error: `View "${viewName}" not found` };
+  }
+
+  try {
+    // Get all table names referenced in the schema
+    const schema = typeof DB_SCHEMA !== 'undefined' ? DB_SCHEMA : {};
+    const tableNames = Object.keys(schema);
+
+    // Load tables into alasql
+    for (const tableName of tableNames) {
+      const table = db.table(tableName);
+      if (!table) continue;
+
+      const result = table.list({});
+      const rows = result?.data || [];
+
+      // Drop if exists, then create and insert
+      try { alasql(`DROP TABLE IF EXISTS ${tableName}`); } catch (_) {}
+      if (rows.length > 0) {
+        alasql(`CREATE TABLE ${tableName}`);
+        alasql.tables[tableName].data = rows;
+      } else {
+        alasql(`CREATE TABLE ${tableName}`);
+      }
+    }
+
+    // Execute the view query
+    let query = viewDef.query;
+
+    // Merge params: client-supplied first, then $user.* (server-side, can't be spoofed)
+    const queryParams: Record<string, any> = { ...(params || {}) };
+    if (user) {
+      queryParams['$user.email'] = user.email;
+      queryParams['$user.id'] = user.id;
+      queryParams['$user.role'] = user.role;
+    }
+
+    // Parameter substitution: {{paramName}} → value
+    for (const [key, value] of Object.entries(queryParams)) {
+      query = query.replace(new RegExp(`\\{\\{${key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\}\\}`, 'g'), String(value));
+    }
+
+    const data = alasql(query);
+
+    return { data, viewName, rowCount: data.length };
+  } catch (err: any) {
+    return { error: `View query failed: ${err.message || String(err)}` };
+  }
+}
+
+/**
+ * List all available view names (optionally filtered by RBAC role).
+ */
+function listViews(role?: string): string[] {
+  const viewNames = Object.keys(VIEWS_CONFIG);
+  if (!role) return viewNames;
+
+  return viewNames.filter(name => {
+    const viewDef = VIEWS_CONFIG[name];
+    if (!viewDef.roles || viewDef.roles.length === 0) return true;
+    return viewDef.roles.includes(role);
+  });
+}

package/templates/blank.json

@@ -0,0 +1,33 @@
+{
+  "name": "blank",
+  "description": "Minimal starter — one example table",
+  "tables": {
+    "items": {
+      "spreadsheetId": "__new__",
+      "sheetName": "items",
+      "schema": {
+        "id": {
+          "type": "string",
+          "primaryKey": true,
+          "required": true
+        },
+        "name": {
+          "type": "string",
+          "required": true
+        },
+        "description": {
+          "type": "string"
+        },
+        "__audit__": {
+          "type": "object"
+        },
+        "__archived__": {
+          "type": "boolean",
+          "defaultValue": false
+        }
+      },
+      "idGenerator": "UUID",
+      "deleteMode": "soft"
+    }
+  }
+}