spine-framework 0.2.1 → 1.0.0

package/.framework/functions/apps.ts

@@ -1,483 +0,0 @@
-/**
- * @module apps
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * CRUD API for the `apps` table. Apps are the installable units of functionality
- * in Spine v2. They group types, roles, integrations, and nav configuration.
- *
- * **Routed by:** `GET/POST/PATCH/DELETE /.netlify/functions/apps`
- *
- * **Authorization model:**
- * - `list` / `get` / `getSchema` / `checkAvailability`: any authenticated principal
- *   (RLS-scoped via `ctx.db`). Returns sanitized records.
- * - `create`: requires `isSystemAdmin` or first-surface `canCreate` permission.
- * - `update` / `remove`: requires authenticated principal + field-level permission
- *   check via `validateUpdatePermissions`.
- * - `updateVersion`: authenticated principal via RPC.
- *
- * INVARIANT: app slugs are globally unique across the `apps` table.
- * INVARIANT: `is_system` apps can only be manipulated by system admins.
- *
- * @seeAlso middleware.ts (createHandler)
- * @seeAlso permissions.ts (PermissionEngine, sanitizeRecordData)
- * @seeAlso audit.ts (emitLog for app.created / app.updated / app.deleted)
- * @seeAlso types.ts (types reference apps via app_id)
- */
-
-import { createHandler } from './_shared/middleware'
-import { joins } from './_shared/db'
-import { emitLog } from './_shared/audit'
-import { PermissionEngine, sanitizeRecordData } from './_shared/permissions'
-
-const permissions = PermissionEngine as any
-
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: APPS_LIST ──────────────────────────────────────────────
-/**
- * @chunk-id    APPS_LIST_1_0_0
- * @version     1.0.0
- * @hash        8eaac3c01786fadeb3c4acb34c9725378f2055766213493859835cadf2bb3963
- * @macro       Apps List Handler
- * @micro       Lists accessible apps via RPC with filtering and sanitization
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     Array of sanitized app records
- * @depends-on  [createHandler, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [RPC call, permission sanitization]
- * @tags        apps, list, crud, rpc
- */
-export const list = createHandler(async (ctx, body) => {
-  const { include_system, include_inactive, account_id } = ctx.query || {}
-
-  const targetAccountId = account_id || ctx.accountId
-
-  if (!targetAccountId) {
-    throw new Error('Account context required')
-  }
-
-  // RLS automatically filters to accessible accounts
-  const { data, error: err } = await ctx.db
-    .rpc('get_account_apps', {
-      account_id: targetAccountId,
-      include_system: include_system !== 'false',
-      include_inactive: include_inactive === 'true'
-    })
-
-  if (err) throw err
-
-  // Sanitize each record based on role permissions
-  const sanitized = []
-  for (const app of data || []) {
-    sanitized.push(await sanitizeRecordData(ctx, app, 'app'))
-  }
-
-  return sanitized
-})
-// ─── CHUNK_END: APPS_LIST ────────────────────────────────────────────────
-
-// ─── CHUNK_START: APPS_GET ──────────────────────────────────────────────
-/**
- * @chunk-id    APPS_GET_1_0_0
- * @version     1.0.0
- * @hash        5449bb3ac8726775412df541e1f2abf2400fb18751e3c9aad5f0aafb09cc7f60
- * @macro       App Get Handler
- * @micro       Returns single app by ID or slug with owner account join
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     Sanitized app record with ownerAccount join
- * @depends-on  [createHandler, joins, sanitizeRecordData]
- * @depended-by [Netlify function routing]
- * @side-effects [DB single row query, permission sanitization]
- * @tags        apps, get, crud, single-record
- */
-export const get = createHandler(async (ctx, body) => {
-  const { id, slug } = ctx.query || {}
-  
-  if (!id && !slug) {
-    throw new Error('App ID or slug is required')
-  }
-
-  let query = ctx.db
-    .from('apps')
-    .select(`*, ${joins.ownerAccount}`)
-    .eq('is_active', true)
-
-  if (id) {
-    query = query.eq('id', id)
-  } else {
-    query = query.eq('slug', slug)
-  }
-
-  const { data, error: err } = await query.single()
-
-  if (err) throw err
-
-  // Sanitize based on role permissions
-  return await sanitizeRecordData(ctx, data, 'app')
-})
-// ─── CHUNK_END: APPS_GET ────────────────────────────────────────────────
-
-// ─── CHUNK_START: APPS_GET_SCHEMA ──────────────────────────────────────────────
-/**
- * @chunk-id    APPS_GET_SCHEMA_1_0_0
- * @version     1.0.0
- * @hash        8b6b7bb419114cbb699ad841dc4ba760ff36a626e8a9513de24715229e5a064b
- * @macro       App Schema Handler
- * @micro       Returns full app schema via RPC with types, roles, views, integrations
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     App schema object with complete configuration
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing]
- * @side-effects [RPC call for schema retrieval]
- * @tags        apps, schema, rpc, configuration
- */
-export const getSchema = createHandler(async (ctx, body) => {
-  const { slug } = ctx.query || {}
-
-  if (!slug) {
-    throw new Error('App slug is required')
-  }
-
-  const { data, error: err } = await ctx.db
-    .rpc('get_app_schema', { app_slug: slug })
-
-  if (err) throw err
-
-  return data
-})
-// ─── CHUNK_END: APPS_GET_SCHEMA ────────────────────────────────────────────────
-
-// ─── CHUNK_START: APPS_CREATE ──────────────────────────────────────────────
-/**
- * @chunk-id    APPS_CREATE_1_0_0
- * @version     1.0.0
- * @hash        f440efbf4a020b2d0d21ed7d90c5995538dd76d631f1b16fc53c1f2e9a1e4f91
- * @macro       App Create Handler
- * @micro       Creates new app with permission validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — App configuration data including slug and name
- * @outputs     Inserted app record
- * @depends-on  [createHandler, permissions, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB insert, permission checks, audit logging]
- * @tags        apps, create, crud, permissions, audit
- */
-export const create = createHandler(async (ctx, body) => {
-  const { slug, name, description, icon, color, version, app_type, source, owner_account_id, config, nav_items, min_role, integration_deps, metadata, route_prefix, renderer } = body
-
-  if (!slug || !name) {
-    throw new Error('slug and name are required')
-  }
-
-  if (!ctx.principal || ctx.principal.id === 'anonymous' || !ctx.accountId) {
-    throw new Error('User context (person and account) required')
-  }
-
-  // Check create permissions
-  if (!permissions.isSystemAdmin(ctx)) {
-    const perms = await permissions.resolveFirstSurfacePermissions(
-      ctx.principal.id,
-      ctx.accountId!,
-      'app',
-      'create'
-    )
-    
-    if (!perms.canCreate) {
-      throw new Error('Insufficient permissions to create apps')
-    }
-  }
-
-  // Check if slug is unique
-  const { data: existing } = await ctx.db
-    .from('apps')
-    .select('id')
-    .eq('slug', slug)
-    .single()
-
-  if (existing) {
-    throw new Error('App slug already exists')
-  }
-
-  const { data, error: err } = await ctx.db
-    .from('apps')
-    .insert({
-      slug,
-      name,
-      description,
-      icon,
-      color,
-      version: version || '1.0.0',
-      app_type: app_type || 'custom',
-      source: source || 'custom',
-      owner_account_id: owner_account_id || ctx.accountId,
-      config: config || {},
-      nav_items: nav_items || [],
-      min_role: min_role || 'member',
-      integration_deps: integration_deps || [],
-      metadata: metadata || {},
-      route_prefix: route_prefix !== undefined ? route_prefix : ('/' + slug),
-      renderer: renderer || 'generic',
-      is_active: true,
-      is_system: false
-    })
-    .select()
-    .single()
-
-  if (err) throw err
-
-  await emitLog(ctx, 'app.created', { type: 'app', id: data.id }, { after: data })
-
-  return data
-})
-// ─── CHUNK_END: APPS_CREATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: APPS_UPDATE ──────────────────────────────────────────────
-/**
- * @chunk-id    APPS_UPDATE_1_0_0
- * @version     1.0.0
- * @hash        77029f18737fee801ff5ebdde199d6b52454fd9fe3842694b072181fc713b937
- * @macro       App Update Handler
- * @micro       Updates app with field-level permission validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — App updates including id
- * @outputs     Updated app record
- * @depends-on  [createHandler, permissions, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB update, permission validation, audit logging]
- * @tags        apps, update, crud, permissions, audit
- */
-export const update = createHandler(async (ctx, body) => {
-  const id = body?.id || ctx.query?.id
-  const { id: _bodyId, ...updates } = body || {}
-
-  if (!id) {
-    throw new Error('App ID is required')
-  }
-
-  if (!ctx.principal || ctx.principal.id === 'anonymous' || !ctx.accountId) {
-    throw new Error('User context (person and account) required')
-  }
-
-  // Get current state for audit - RLS will filter to accessible apps
-  const { data: current } = await ctx.db
-    .from('apps')
-    .select('*')
-    .eq('id', id)
-    .single()
-
-  if (!current) {
-    throw new Error('App not found')
-  }
-
-  // Validate field-level permissions
-  const fieldValidation = await permissions.validateUpdatePermissions(
-    ctx,
-    updates,
-    current,
-    'apps'
-  )
-  
-  if (!fieldValidation.valid) {
-    throw new Error(fieldValidation.error)
-  }
-
-  const { data, error: err } = await ctx.db
-    .from('apps')
-    .update({
-      ...updates,
-      updated_at: new Date().toISOString()
-    })
-    .eq('id', id)
-    .select()
-    .single()
-
-  if (err) throw err
-
-  await emitLog(ctx, 'app.updated', { type: 'app', id }, { before: current, after: data })
-
-  return data
-})
-// ─── CHUNK_END: APPS_UPDATE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: APPS_REMOVE ──────────────────────────────────────────────
-/**
- * @chunk-id    APPS_REMOVE_1_0_0
- * @version     1.0.0
- * @hash        b2c79779820861406f1adabc2279e332727b936abab4c6f5e5762a62d1373169
- * @macro       App Remove Handler
- * @micro       Soft-deletes app with validation and audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body with app ID
- * @outputs     Updated app record with is_active: false
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [DB soft delete, audit logging]
- * @tags        apps, remove, crud, audit
- */
-export const remove = createHandler(async (ctx, body) => {
-  const id = body?.id || ctx.query?.id
-
-  if (!id) {
-    throw new Error('App ID is required')
-  }
-
-  if (!ctx.principal || ctx.principal.id === 'anonymous' || !ctx.accountId) {
-    throw new Error('User context (person and account) required')
-  }
-
-  // Get current state for audit - RLS will filter to accessible apps
-  const { data: current } = await ctx.db
-    .from('apps')
-    .select('*')
-    .eq('id', id)
-    .single()
-
-  if (!current) {
-    throw new Error('App not found')
-  }
-
-  const { data, error: err } = await ctx.db
-    .from('apps')
-    .update({
-      is_active: false,
-      updated_at: new Date().toISOString()
-    })
-    .eq('id', id)
-    .select()
-    .single()
-
-  if (err) throw err
-
-  await emitLog(ctx, 'app.deleted', { type: 'app', id }, { before: current })
-
-  return data
-})
-// ─── CHUNK_END: APPS_REMOVE ────────────────────────────────────────────────
-
-// ─── CHUNK_START: APPS_CHECK_AVAILABILITY ──────────────────────────────────────────────
-/**
- * @chunk-id    APPS_CHECK_AVAILABILITY_1_0_0
- * @version     1.0.0
- * @hash        db7d52bcb1002d923dac039a99e6f6fb0eb9889e9b4a44994bf7bb75477ac9a4
- * @macro       App Availability Checker
- * @micro       Checks if app is available for account via RPC
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body (unused for GET)
- * @outputs     {available: boolean} — Availability status
- * @depends-on  [createHandler]
- * @depended-by [Netlify function routing]
- * @side-effects [RPC call for availability check]
- * @tags        apps, availability, rpc, check
- */
-export const checkAvailability = createHandler(async (ctx, body) => {
-  const { slug } = ctx.query || {}
-
-  if (!slug) {
-    throw new Error('App slug is required')
-  }
-
-  if (!ctx.accountId) {
-    throw new Error('Account context required')
-  }
-
-  const { data, error: err } = await ctx.db
-    .rpc('is_app_available', {
-      app_slug: slug,
-      account_id: ctx.accountId
-    })
-
-  if (err) throw err
-
-  return { available: data }
-})
-// ─── CHUNK_END: APPS_CHECK_AVAILABILITY ────────────────────────────────────────────────
-
-// ─── CHUNK_START: APPS_UPDATE_VERSION ──────────────────────────────────────────────
-/**
- * @chunk-id    APPS_UPDATE_VERSION_1_0_0
- * @version     1.0.0
- * @hash        04a1a3367e4b8ca0f58e0719e73b0ccda378e84b4b874f3f7e07ee0faa423bfd
- * @macro       App Version Update Handler
- * @micro       Updates app version string via RPC with audit logging
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: object — App ID and new version string
- * @outputs     {success: true} — Success confirmation
- * @depends-on  [createHandler, emitLog]
- * @depended-by [Netlify function routing]
- * @side-effects [RPC call, audit logging]
- * @tags        apps, version, update, rpc, audit
- */
-export const updateVersion = createHandler(async (ctx, body) => {
-  const { id, version } = body
-
-  if (!id || !version) {
-    throw new Error('App ID and version are required')
-  }
-
-  const { data, error: err } = await ctx.db
-    .rpc('update_app_version', {
-      app_id: id,
-      new_version: version
-    })
-
-  if (err) throw err
-
-  await emitLog(ctx, 'app.version_updated', { type: 'app', id }, { after: { version } })
-
-  return { success: true }
-})
-// ─── CHUNK_END: APPS_UPDATE_VERSION ────────────────────────────────────────────────
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
-// ─── CHUNK_START: APPS_HANDLER ──────────────────────────────────────────────
-/**
- * @chunk-id    APPS_HANDLER_1_0_0
- * @version     1.0.0
- * @hash        361e1ba86b38a4611f3170526e4ff7f456d58b929c1d39bf847135afdebf3867
- * @macro       Apps Router
- * @micro       Routes HTTP methods and actions to appropriate handlers
- * @inputs      ctx: CoreContext — Request context with principal and database
- * @inputs      body: any — Request body for POST/PATCH operations
- * @outputs     Varies — Depends on routed handler (list/get/create/update/remove/schema/available/version)
- * @depends-on  [createHandler, list, get, getSchema, checkAvailability, create, update, remove, updateVersion]
- * @depended-by [Netlify function routing]
- * @side-effects [Delegates to appropriate handler]
- * @tags        apps, router, crud, netlify-function
- */
-export const handler = createHandler(async (ctx, body) => {
-  const method = ctx.query?.method || 'GET'
-
-  switch (method) {
-    case 'GET':
-      if (ctx.query?.action === 'get' || ctx.query?.id) {
-        return await get(ctx, body)
-      } else if (ctx.query?.slug) {
-        return await get(ctx, body)
-      } else if (ctx.query?.action === 'schema') {
-        return await getSchema(ctx, body)
-      } else if (ctx.query?.action === 'available') {
-        return await checkAvailability(ctx, body)
-      } else {
-        return await list(ctx, body)
-      }
-    case 'POST':
-      if (ctx.query?.action === 'version') {
-        return await updateVersion(ctx, body)
-      } else {
-        return await create(ctx, body)
-      }
-    case 'PATCH':
-      return await update(ctx, body)
-    case 'DELETE':
-      return await remove(ctx, body)
-    default:
-      throw new Error(`Unsupported method: ${method}`)
-  }
-})
-// ─── CHUNK_END: APPS_HANDLER ────────────────────────────────────────────────

package/.framework/functions/auth.ts

@@ -1,196 +0,0 @@
-/**
- * @module auth
- * @audience core-contributor
- * @layer api-handler
- * @stability stable
- *
- * Authentication context endpoint. Returns the full user session context for
- * the authenticated principal: person record, account, role, permissions, and
- * accessible child accounts (via the `get_account_hierarchy` RPC).
- *
- * **Routed by:** `GET /.netlify/functions/auth`
- *
- * **Actions:**
- * | method | handler  |
- * |--------|----------|
- * | GET    | context  |
- * | HEALTH | health   |
- *
- * **Authorization:** `context` requires a non-anonymous authenticated
- * principal. `health` is unauthenticated.
- *
- * **Returned session shape:**
- * ```ts
- * {
- *   id: string             // person UUID
- *   email: string
- *   full_name: string
- *   account_id: string
- *   account: { id, slug, display_name, parent_id }
- *   roles: string[]        // role slugs (e.g. ['system_admin'])
- *   permissions: string[]  // derived from role.slug or role.permissions
- *   accessible_accounts: AccountHierarchyRow[]
- * }
- * ```
- *
- * INVARIANT: `system_admin` role always receives the full permission set
- *   ['read', 'write', 'admin', 'system'] regardless of `role.permissions`.
- *
- * @seeAlso middleware.ts (createHandler builds ctx.principal from JWT)
- * @seeAlso _shared/db.ts (get_account_hierarchy RPC)
- * @seeAlso roles.ts (role records referenced by FK)
- */
-
-import { createHandler } from './_shared/middleware'
-
-// ─── HANDLERS ─────────────────────────────────────────────────────────────────
-
-/**
- * Returns the full authenticated user context. Fetches person, account,
- * and role in a single query, then calls `get_account_hierarchy` to
- * resolve accessible child accounts.
- *
- * @returns Session object (see module-level shape doc)
- * @throws Error('Authentication required') if principal is anonymous
- * @throws Error('User not found: <id>') if person row is inactive or missing
- * @sideEffects DB read: people table (with account + role joins)
- * @sideEffects DB read: get_account_hierarchy RPC
- * @calledBy handler (GET)
- * @testUnit tests/unit/auth.test.ts — 'context'
- * @testIntegration tests/integration/auth.test.ts — 'returns valid context'
- */
-export const context = createHandler(async (ctx, _body) => {
-  // Authentication is required
-  if (!ctx.principal || ctx.principal.id === 'anonymous') {
-    throw new Error('Authentication required')
-  }
-
-  console.log('Backend: Fetching user context for person:', ctx.principal.id)
-
-  // Single query gets everything - person, account, role using simplified model
-  const { data: personData, error: personError } = await ctx.db
-    .from('people')
-    .select(`
-      id,
-      email,
-      full_name,
-      avatar_url,
-      account_id,
-      role_id,
-      account:accounts!people_account_id_fkey(
-        id,
-        slug,
-        display_name,
-        parent_id
-      ),
-      role:roles(
-        id,
-        slug,
-        name,
-        is_system
-      )
-    `)
-    .eq('id', ctx.principal.id)
-    .eq('is_active', true)
-    .single()
-
-  if (personError) {
-    console.error('Backend: Error fetching person:', personError)
-  }
-
-  if (!personData) {
-    throw new Error('User not found: ' + ctx.principal.id)
-  }
-
-  console.log('Backend: Person data found:', {
-    id: personData.id,
-    email: personData.email,
-    account_id: personData.account_id,
-    role_id: personData.role_id
-  })
-
-  // Extract account and role (handle array responses)
-  const account = Array.isArray(personData.account) ? personData.account[0] : personData.account
-  const role = Array.isArray(personData.role) ? personData.role[0] : personData.role
-
-  // Get child accounts recursively
-  let accessibleAccounts = []
-  if (personData.account_id) {
-    const { data: childAccounts } = await ctx.db
-      .rpc('get_account_hierarchy', { 
-        parent_account_id: personData.account_id 
-      })
-    
-    accessibleAccounts = childAccounts || []
-    console.log('Backend: Found', accessibleAccounts.length, 'accessible accounts')
-  }
-
-  // Determine permissions from role - system_admin role has full permissions
-  let effectivePermissions = []
-  const roleSlug = role?.slug
-  
-  if (roleSlug === 'system_admin') {
-    effectivePermissions = ['read', 'write', 'admin', 'system']
-  } else if (role?.permissions && Array.isArray(role.permissions)) {
-    effectivePermissions = role.permissions
-  }
-
-  console.log('Backend: User context complete:', {
-    id: personData.id,
-    email: personData.email,
-    account: account?.slug,
-    role: roleSlug,
-    permissionsCount: effectivePermissions.length
-  })
-
-  // Return complete user context
-  // Note: system_admin status is determined by 'system_admin' in roles array
-  return {
-    id: personData.id,
-    email: personData.email,
-    full_name: personData.full_name,
-    account_id: personData.account_id,
-    account: account,
-    roles: [roleSlug].filter(Boolean),
-    permissions: effectivePermissions,
-    is_system_admin: roleSlug === 'system_admin',
-    accessible_accounts: accessibleAccounts
-  }
-})
-
-/**
- * Lightweight health check for the auth function. Returns service name
- * and current timestamp. No authentication required.
- *
- * @returns `{ status: 'healthy', timestamp: string, service: 'auth' }`
- * @calledBy handler (HEALTH method)
- * @calledBy load balancer health probes
- */
-export const health = createHandler(async (ctx, _body) => {
-  return {
-    status: 'healthy',
-    timestamp: new Date().toISOString(),
-    service: 'auth'
-  }
-})
-
-// ─── MAIN HANDLER ────────────────────────────────────────────────────────────
-
-/**
- * Netlify function entry point. Routes by HTTP method:
- * GET → context | HEALTH → health
- * @throws Error('Unsupported method: <method>') on unmatched method
- * @calledBy Netlify function routing
- */
-export const handler = createHandler(async (ctx, _body) => {
-  const method = ctx.query?.method || 'GET'
-
-  switch (method) {
-    case 'GET':
-      return await context(ctx, _body)
-    case 'HEALTH':
-      return await health(ctx, _body)
-    default:
-      throw new Error(`Unsupported method: ${method}`)
-  }
-})