spine-framework 0.4.4 → 0.5.0-rc.5

package/.framework/tests/unit/api-keys-create-scope-gate.test.ts

@@ -0,0 +1,160 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+
+// S-011: api-keys create accepted `scopes` and `is_internal` verbatim, so any
+// scoped machine caller (service-role ctx.db) could mint a `*:*` or
+// `is_internal` key and escalate itself. These tests pin the gate: wildcard
+// scopes and internal keys are system-principal-only (403 otherwise), other
+// requested scopes are clipped to the caller's own, and an omitted scopes
+// list inherits the caller's scopes.
+
+vi.mock('../../functions/_shared/middleware.ts', () => ({
+  createHandler: (fn: any) => fn,
+  json: vi.fn(),
+  error: vi.fn(),
+  parseBody: vi.fn(),
+}))
+
+vi.mock('../../functions/_shared/db.ts', () => ({
+  adminDb: {
+    from: vi.fn(),
+    rpc: vi.fn(),
+  },
+  getUserDb: vi.fn(() => ({})),
+}))
+
+vi.mock('../../functions/_shared/audit.ts', () => ({
+  emitAudit: vi.fn().mockResolvedValue(undefined),
+  emitLog: vi.fn().mockResolvedValue(undefined),
+  emitSpan: vi.fn().mockResolvedValue(undefined),
+  emitActivity: vi.fn().mockResolvedValue(undefined),
+}))
+
+vi.mock('../../functions/_shared/permissions.ts', () => ({
+  sanitizeRecordData: vi.fn(async (_ctx: any, record: any) => record),
+}))
+
+vi.mock('../../functions/_shared/logging.ts', () => ({
+  resolveAppUuid: vi.fn(async (ref: any) => ref ?? null),
+}))
+
+import { create } from '../../functions/api-keys.ts'
+
+// Chainable query-builder stub — filter/chain methods return the builder;
+// single/maybeSingle/await resolve to the queued result.
+function q(result: { data?: any; error?: any }) {
+  const b: any = {}
+  const chainers = ['select', 'eq', 'in', 'is', 'order', 'limit', 'update',
+    'insert', 'upsert', 'delete', 'or', 'gte', 'lte', 'range']
+  for (const m of chainers) b[m] = vi.fn(() => b)
+  b.single = vi.fn(async () => result)
+  b.maybeSingle = vi.fn(async () => result)
+  b.then = (onF: any, onR: any) => Promise.resolve(result).then(onF, onR)
+  return b
+}
+
+let queue: any[] = []
+let dbBuilt: any[] = []
+
+function stubDb() {
+  return {
+    from: vi.fn(() => {
+      const b = queue.length ? queue.shift() : q({ data: null, error: null })
+      dbBuilt.push(b)
+      return b
+    }),
+    rpc: vi.fn(async () => ({ data: [], error: null })),
+  }
+}
+
+beforeEach(() => {
+  queue = []
+  dbBuilt = []
+  vi.clearAllMocks()
+})
+
+const scopedMachine = (scopes: string[] = ['logs:read'], accountId: string | null = 'acct-1') => ({
+  id: 'key-1',
+  type: 'machine',
+  accountId,
+  roles: [],
+  scopes,
+  isInternal: false,
+  machineType: 'integration',
+  provenance: { sourceType: 'api_key' },
+})
+
+const systemAdmin = () => ({
+  id: 'user-1',
+  type: 'human',
+  accountId: 'acct-1',
+  roles: ['system_admin'],
+  provenance: { sourceType: 'jwt' },
+})
+
+function makeCtx(principal: any, overrides: any = {}) {
+  return {
+    requestId: 'req-1',
+    principal,
+    accountId: principal?.accountId ?? null,
+    db: stubDb(),
+    query: {},
+    headers: {},
+    ...overrides,
+  }
+}
+
+// Queue a successful insert for create() and return the builder's insert spy.
+function queueInsert() {
+  const b = q({ data: { id: 'key-9', name: 'k', key_type: 'inbound' }, error: null })
+  queue.push(b)
+  return b
+}
+
+describe('api-keys create privilege gate (S-011)', () => {
+  it('denies a scoped machine caller minting a *:* key with statusCode 403', async () => {
+    const ctx = makeCtx(scopedMachine())
+    await expect(
+      create(ctx, { name: 'escalated', scopes: ['*:*'] })
+    ).rejects.toMatchObject({ statusCode: 403 })
+    expect(ctx.db.from).not.toHaveBeenCalled()
+  })
+
+  it('denies a scoped machine caller minting an is_internal key with statusCode 403', async () => {
+    const ctx = makeCtx(scopedMachine())
+    await expect(
+      create(ctx, { name: 'internal', is_internal: true })
+    ).rejects.toMatchObject({ statusCode: 403 })
+    expect(ctx.db.from).not.toHaveBeenCalled()
+  })
+
+  it('clips requested scopes to the scopes the caller already holds', async () => {
+    const b = queueInsert()
+    const ctx = makeCtx(scopedMachine(['logs:read', 'items:read']))
+    await create(ctx, { name: 'clipped', scopes: ['logs:read', 'admin:write', '*'] })
+    expect(b.insert).toHaveBeenCalledWith(expect.objectContaining({
+      scopes: ['logs:read'],
+      is_internal: false,
+    }))
+  })
+
+  it('inherits the caller\u2019s own scopes when scopes is omitted', async () => {
+    const b = queueInsert()
+    const ctx = makeCtx(scopedMachine(['logs:read', 'items:write']))
+    await create(ctx, { name: 'inherits' })
+    expect(b.insert).toHaveBeenCalledWith(expect.objectContaining({
+      scopes: ['logs:read', 'items:write'],
+      is_internal: false,
+    }))
+  })
+
+  it('lets a system_admin mint a wildcard-scoped internal key', async () => {
+    const b = queueInsert()
+    const ctx = makeCtx(systemAdmin())
+    const res = await create(ctx, { name: 'root', scopes: ['*:*'], is_internal: true })
+    expect(res.raw_key).toMatch(/^sk_/)
+    expect(b.insert).toHaveBeenCalledWith(expect.objectContaining({
+      scopes: ['*:*'],
+      is_internal: true,
+    }))
+  })
+})

package/.framework/tests/unit/api-keys-omit-secret-fields.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect } from 'vitest'
+import { omitSecretFields } from '../../functions/_shared/hash-api-key'
+
+describe('omitSecretFields', () => {
+  it('removes key_value and key_hash and keeps the other fields', () => {
+    const row = { id: 'key-1', name: 'Prod', key_prefix: 'sk_abc123', key_hash: 'hash', key_value: 'sk_secret' }
+    const result = omitSecretFields(row)
+    expect(result).toEqual({ id: 'key-1', name: 'Prod', key_prefix: 'sk_abc123' })
+    expect(result).not.toHaveProperty('key_value')
+    expect(result).not.toHaveProperty('key_hash')
+  })
+
+  it('does not mutate the input row', () => {
+    const row = { id: 'key-1', key_value: 'sk_secret', key_hash: 'hash' }
+    omitSecretFields(row)
+    expect(row.key_value).toBe('sk_secret')
+    expect(row.key_hash).toBe('hash')
+  })
+
+  it('returns null and undefined input as-is', () => {
+    expect(omitSecretFields(null)).toBeNull()
+    expect(omitSecretFields(undefined)).toBeUndefined()
+  })
+
+  it('returns an equal copy for a row without secret fields', () => {
+    const row = { id: 'key-1', name: 'Prod', is_active: true, metadata: { env: 'prod' } }
+    const result = omitSecretFields(row)
+    expect(result).toEqual(row)
+    expect(result).not.toBe(row)
+  })
+
+  it('strips key_hash even when it is the only secret field present', () => {
+    const row = { id: 'key-2', name: 'CI', key_hash: 'pbkdf2$100000$salt$hash' }
+    const result = omitSecretFields(row)
+    expect(result).toEqual({ id: 'key-2', name: 'CI' })
+    expect(result).not.toHaveProperty('key_hash')
+  })
+})

package/.framework/tests/unit/app-mount.test.ts

@@ -0,0 +1,80 @@
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-mount.test.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/tests/unit/app-mount.test.ts"]
+// CIL[DOC-MACRO purpose="Unit tests for resolveAppMount — host-keyed mount overrides on apps records"]
+// CIL[DOC-CONTRACT inputs="resolveAppMount calls with injected hostname/environment" outputs="vitest assertions" errors="none" side_effects="none"]
+// CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+// CIL[DOC-STABILITY stability="experimental"]
+import { describe, it, expect } from 'vitest'
+import { resolveAppMount } from '../../src/lib/app-mount.ts'
+// CIL[END stable_id="~/.framework/tests/unit/app-mount.test.ts:module_header:module_header"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-mount.test.ts:fixtures:block" type="block" identity="fixtures" parent="none"]
+// CIL[DOC-MACRO purpose="Shared app record fixture and default opts (localhost, prod env)"]
+
+const base = {
+  route_prefix: '/demo' as string | null,
+  preview_domain: null as string | null,
+  prod_domain: null as string | null,
+  preview_route_prefix: null as string | null,
+  prod_route_prefix: null as string | null,
+}
+
+const opts = { hostname: 'localhost', environment: 'prod' }
+// CIL[END stable_id="~/.framework/tests/unit/app-mount.test.ts:fixtures:block"]
+
+// CIL[BEGIN stable_id="~/.framework/tests/unit/app-mount.test.ts:resolveappmount_suite:block" type="block" identity="resolveappmount_suite" parent="none"]
+// CIL[DOC-MACRO purpose="Cover default mount, host-matched override, non-matching fallback, legacy domain lock, preview env fields, URL/port domains, and idempotence"]
+describe('resolveAppMount', () => {
+  it('returns the default mount when no domain is configured', () => {
+    expect(resolveAppMount({ ...base }, opts))
+      .toEqual({ routable: true, route_prefix: '/demo' })
+  })
+
+  it('mounts at prod_route_prefix when the host matches prod_domain', () => {
+    const app = { ...base, prod_domain: 'demo.answer-once.com', prod_route_prefix: '/' }
+    expect(resolveAppMount(app, { hostname: 'demo.answer-once.com', environment: 'prod' }))
+      .toEqual({ routable: true, route_prefix: '/' })
+  })
+
+  it('stays routable at the default mount on other hosts when an override exists', () => {
+    const app = { ...base, prod_domain: 'demo.answer-once.com', prod_route_prefix: '/' }
+    expect(resolveAppMount(app, opts))
+      .toEqual({ routable: true, route_prefix: '/demo' })
+  })
+
+  it('filters the app on other hosts when a domain is set without an override (legacy lock)', () => {
+    const app = { ...base, prod_domain: 'demo.answer-once.com' }
+    expect(resolveAppMount(app, opts)).toEqual({ routable: false, route_prefix: '/demo' })
+    expect(resolveAppMount(app, { hostname: 'demo.answer-once.com', environment: 'prod' }))
+      .toEqual({ routable: true, route_prefix: '/demo' })
+  })
+
+  it('uses preview fields when environment is preview', () => {
+    const app = {
+      ...base,
+      preview_domain: 'staging.answer-once.com',
+      preview_route_prefix: '/',
+      prod_domain: 'demo.answer-once.com',
+      prod_route_prefix: '/',
+    }
+    expect(resolveAppMount(app, { hostname: 'staging.answer-once.com', environment: 'preview' }))
+      .toEqual({ routable: true, route_prefix: '/' })
+    // prod host does not match under preview env — falls back to default mount
+    expect(resolveAppMount(app, { hostname: 'demo.answer-once.com', environment: 'preview' }))
+      .toEqual({ routable: true, route_prefix: '/demo' })
+  })
+
+  it('accepts full URLs and host:port in domain fields', () => {
+    const app = { ...base, prod_domain: 'https://demo.answer-once.com/', prod_route_prefix: '/' }
+    expect(resolveAppMount(app, { hostname: 'demo.answer-once.com', environment: 'prod' }))
+      .toEqual({ routable: true, route_prefix: '/' })
+  })
+
+  it('is idempotent — re-resolving a resolved record returns the same mount', () => {
+    const app = { ...base, prod_domain: 'demo.answer-once.com', prod_route_prefix: '/' }
+    const once = resolveAppMount(app, { hostname: 'demo.answer-once.com', environment: 'prod' })
+    const twice = resolveAppMount({ ...app, route_prefix: once.route_prefix },
+      { hostname: 'demo.answer-once.com', environment: 'prod' })
+    expect(twice).toEqual(once)
+  })
+})
+// CIL[END stable_id="~/.framework/tests/unit/app-mount.test.ts:resolveappmount_suite:block"]

package/.framework/tests/unit/bootstrap.test.ts

@@ -0,0 +1,242 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { verifyApiKey } from '../../functions/_shared/hash-api-key'
+
+// S-002: `spine-framework bootstrap` provisions the first system_admin and
+// mints the first sk_ key without a browser. These tests pin the idempotent
+// skip, the register-path row shape, the auth-user path, and the
+// hash-only key storage.
+
+type DbCall = { op: string; args: any[] }
+type DbQuery = { table: string; calls: DbCall[] }
+type DbResult = { data?: any; error?: any }
+
+const supaState = vi.hoisted(() => ({
+  responder: null as null | ((q: DbQuery) => DbResult),
+  history: [] as DbQuery[],
+  createUser: vi.fn(),
+}))
+
+vi.mock('@supabase/supabase-js', () => ({
+  createClient: () => ({
+    from(table: string) {
+      const calls: DbCall[] = []
+      const query: DbQuery = { table, calls }
+      const builder: any = {
+        select(...a: any[]) { calls.push({ op: 'select', args: a }); return builder },
+        upsert(...a: any[]) { calls.push({ op: 'upsert', args: a }); return builder },
+        update(...a: any[]) { calls.push({ op: 'update', args: a }); return builder },
+        insert(...a: any[]) { calls.push({ op: 'insert', args: a }); return builder },
+        eq(...a: any[]) { calls.push({ op: 'eq', args: a }); return builder },
+        neq(...a: any[]) { calls.push({ op: 'neq', args: a }); return builder },
+        in(...a: any[]) { calls.push({ op: 'in', args: a }); return builder },
+        is(...a: any[]) { calls.push({ op: 'is', args: a }); return builder },
+        or(...a: any[]) { calls.push({ op: 'or', args: a }); return builder },
+        order(...a: any[]) { calls.push({ op: 'order', args: a }); return builder },
+        limit(...a: any[]) { calls.push({ op: 'limit', args: a }); return builder },
+        range(...a: any[]) { calls.push({ op: 'range', args: a }); return builder },
+        single() { supaState.history.push(query); return Promise.resolve(supaState.responder!(query)) },
+        maybeSingle() { supaState.history.push(query); return Promise.resolve(supaState.responder!(query)) },
+        then(res: any, rej: any) {
+          supaState.history.push(query)
+          return Promise.resolve(supaState.responder!(query)).then(res, rej)
+        },
+      }
+      return builder
+    },
+    auth: {
+      admin: {
+        createUser: (...args: any[]) => supaState.createUser(...args),
+      },
+    },
+  }),
+}))
+
+vi.mock('../../functions/_shared/audit.ts', () => ({
+  emitAudit: vi.fn(async () => {}),
+  emitSpan: vi.fn(async () => {}),
+  emitLog: vi.fn(async () => {}),
+  emitActivity: vi.fn(async () => {}),
+}))
+
+import { createClient } from '@supabase/supabase-js'
+import { runBootstrap } from '../../cli/commands/bootstrap'
+import { emitLog } from '../../functions/_shared/audit'
+
+// Per-test table state. `people` routes on recorded ops: `limit` = the
+// idempotent system_admin existence check, `insert`/`update` = writes,
+// anything else = the email lookup (maybeSingle).
+const tables = {
+  account: { id: 'acct-spine' } as any,
+  role: { id: 'role-admin' } as any,
+  personType: { id: 'type-person', design_schema: { fields: {} }, validation_schema: {} } as any,
+  existingAdmins: [] as any[],
+  personByEmail: null as any,
+}
+
+function defaultResponder(q: DbQuery): DbResult {
+  const ops = q.calls.map((c) => c.op)
+  switch (q.table) {
+    case 'accounts':
+      return { data: tables.account, error: null }
+    case 'roles':
+      return { data: tables.role, error: null }
+    case 'types':
+      return { data: tables.personType, error: null }
+    case 'people':
+      if (ops.includes('insert')) return { data: { id: 'person-new' }, error: null }
+      if (ops.includes('update')) return { data: null, error: null }
+      if (ops.includes('limit')) return { data: tables.existingAdmins, error: null }
+      return { data: tables.personByEmail, error: null }
+    case 'api_keys': {
+      const row = q.calls.find((c) => c.op === 'insert')?.args?.[0] || {}
+      return {
+        data: { id: 'key-1', name: row.name, key_prefix: row.key_prefix, scopes: row.scopes },
+        error: null,
+      }
+    }
+    default:
+      return { data: null, error: null }
+  }
+}
+
+function queriesTo(table: string, op?: string): DbQuery[] {
+  return supaState.history.filter(
+    (q) => q.table === table && (!op || q.calls.some((c) => c.op === op))
+  )
+}
+
+function insertedRow(table: string): any {
+  const q = queriesTo(table, 'insert')[0]
+  return q?.calls.find((c) => c.op === 'insert')?.args?.[0]
+}
+
+beforeEach(() => {
+  supaState.history = []
+  supaState.createUser.mockReset()
+  vi.mocked(emitLog).mockClear()
+  tables.account = { id: 'acct-spine' }
+  tables.role = { id: 'role-admin' }
+  tables.personType = { id: 'type-person', design_schema: { fields: {} }, validation_schema: {} }
+  tables.existingAdmins = []
+  tables.personByEmail = null
+  supaState.responder = defaultResponder
+})
+
+function db() {
+  return createClient('https://example.supabase.co', 'service-key') as any
+}
+
+describe('bootstrap idempotency', () => {
+  it('skips person creation when a system_admin already exists, still mints a key', async () => {
+    tables.existingAdmins = [{ id: 'person-admin', email: 'root@x.com' }]
+
+    const result = await runBootstrap(db(), {})
+
+    expect(result.admin).toBe('existing')
+    expect(result.personId).toBe('person-admin')
+    expect(result.authUserCreated).toBe(false)
+    expect(queriesTo('people', 'insert')).toHaveLength(0)
+    expect(queriesTo('people', 'update')).toHaveLength(0)
+    expect(queriesTo('api_keys', 'insert')).toHaveLength(1)
+    expect(result.apiKey.raw_key).toMatch(/^sk_[0-9a-f]{32}$/)
+    // Only the key mint is audited — no person.created event.
+    const events = vi.mocked(emitLog).mock.calls.map((c) => c[1])
+    expect(events).toEqual(['api_key.created'])
+  })
+
+  it('creates the first admin person (db-only) when none exists', async () => {
+    const result = await runBootstrap(db(), {})
+
+    expect(result.admin).toBe('created')
+    expect(result.authUserCreated).toBe(false)
+    expect(result.personEmail).toBe('admin@spine.local')
+
+    const row = insertedRow('people')
+    // Register-path (handle_new_auth_user) column parity.
+    expect(row.account_id).toBe('acct-spine')
+    expect(row.role_id).toBe('role-admin')
+    expect(row.type_id).toBe('type-person')
+    expect(row.status).toBe('active')
+    expect(row.is_active).toBe(true)
+    expect(row.auth_uid).toBeNull()
+    expect(row.email).toBe('admin@spine.local')
+    expect(row.full_name).toBe('admin')
+    expect(row.design_schema).toEqual({ fields: {} })
+    expect(supaState.createUser).not.toHaveBeenCalled()
+    expect(vi.mocked(emitLog).mock.calls.map((c) => c[1])).toEqual([
+      'person.created',
+      'api_key.created',
+    ])
+  })
+
+  it('creates a confirmed auth user + person when --email/--password are given', async () => {
+    supaState.createUser.mockResolvedValue({
+      data: { user: { id: 'auth-1' } },
+      error: null,
+    })
+
+    const result = await runBootstrap(db(), {
+      email: 'me@x.com',
+      password: 's3cret',
+      fullName: 'Me',
+    })
+
+    expect(supaState.createUser).toHaveBeenCalledWith({
+      email: 'me@x.com',
+      password: 's3cret',
+      email_confirm: true,
+      user_metadata: { full_name: 'Me' },
+    })
+    expect(result.authUserCreated).toBe(true)
+    const row = insertedRow('people')
+    // Register path: person id === auth user id, auth_uid === auth user id.
+    expect(row.id).toBe('auth-1')
+    expect(row.auth_uid).toBe('auth-1')
+    expect(row.email).toBe('me@x.com')
+    expect(row.full_name).toBe('Me')
+  })
+
+  it('rejects --password without --email before any DB work', async () => {
+    await expect(runBootstrap(db(), { password: 'x' })).rejects.toThrow('--password requires --email')
+    expect(supaState.history).toHaveLength(0)
+  })
+
+  it('fails clearly when the spine-system account seed is missing', async () => {
+    tables.account = null
+    await expect(runBootstrap(db(), {})).rejects.toThrow(/spine-system account not found/)
+    expect(queriesTo('api_keys', 'insert')).toHaveLength(0)
+  })
+})
+
+describe('bootstrap api key minting', () => {
+  it('stores only the hash — raw key is returned once and verifies', async () => {
+    const result = await runBootstrap(db(), {})
+
+    const keyRow = insertedRow('api_keys')
+    expect(keyRow.key_hash).toMatch(/^pbkdf2\$\d+\$/)
+    expect(keyRow.key_prefix).toBe(result.apiKey.raw_key.slice(0, 8))
+    expect(keyRow.raw_key).toBeUndefined()
+    expect(keyRow.key_value).toBeUndefined()
+    expect(verifyApiKey(result.apiKey.raw_key, keyRow.key_hash)).toBe(true)
+    expect(keyRow.is_active).toBe(true)
+    expect(keyRow.created_by).toBe(result.personId)
+    expect(keyRow.account_id).toBe('acct-spine')
+  })
+
+  it('defaults to the system_admin wildcard scope', async () => {
+    const result = await runBootstrap(db(), {})
+    expect(result.apiKey.scopes).toEqual(['*:*'])
+    expect(insertedRow('api_keys').scopes).toEqual(['*:*'])
+  })
+
+  it('honors repeated --scope flags for narrower keys', async () => {
+    const result = await runBootstrap(db(), { scopes: ['items:read', 'items:write'] })
+    expect(insertedRow('api_keys').scopes).toEqual(['items:read', 'items:write'])
+    expect(result.apiKey.scopes).toEqual(['items:read', 'items:write'])
+  })
+
+  it('maps the literal system_admin scope to *:*', async () => {
+    const result = await runBootstrap(db(), { scopes: ['system_admin'] })
+    expect(result.apiKey.scopes).toEqual(['*:*'])
+  })
+})

package/.framework/tests/unit/cli-context-api-key.test.ts

@@ -0,0 +1,114 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { hashApiKey } from '../../functions/_shared/hash-api-key'
+
+const { mockFrom, mockLimit } = vi.hoisted(() => ({
+  mockFrom: vi.fn(),
+  mockLimit: vi.fn(),
+}))
+
+vi.mock('../../functions/_shared/index.ts', () => ({
+  adminDb: { from: mockFrom },
+  getUserDb: vi.fn(),
+  SYSTEM_PRINCIPAL: { id: 'system', type: 'system' },
+}))
+
+const ENV_KEYS = [
+  'SUPABASE_URL',
+  'SUPABASE_SERVICE_ROLE_KEY',
+  'SPINE_CLI_API_KEY',
+  'SPINE_CLI_JWT',
+  'SPINE_CLI_ACCOUNT_ID',
+] as const
+
+const savedEnv: Record<string, string | undefined> = {}
+
+async function loadContext() {
+  vi.resetModules()
+  return await import('../../cli/context.ts')
+}
+
+beforeEach(() => {
+  vi.clearAllMocks()
+  for (const key of ENV_KEYS) savedEnv[key] = process.env[key]
+  process.env.SUPABASE_URL = 'https://example.supabase.co'
+  process.env.SUPABASE_SERVICE_ROLE_KEY = 'service-role-test-key'
+  delete process.env.SPINE_CLI_API_KEY
+  delete process.env.SPINE_CLI_JWT
+  delete process.env.SPINE_CLI_ACCOUNT_ID
+
+  mockFrom.mockReturnValue({
+    select: vi.fn(() => ({
+      eq: vi.fn(() => ({
+        eq: vi.fn(() => ({
+          order: vi.fn(() => ({ limit: mockLimit })),
+        })),
+      })),
+    })),
+  })
+})
+
+afterEach(() => {
+  for (const key of ENV_KEYS) {
+    if (savedEnv[key] === undefined) {
+      delete process.env[key]
+    } else {
+      process.env[key] = savedEnv[key]
+    }
+  }
+})
+
+describe('buildCliContext API key auth', () => {
+  it('returns a machine principal for a valid raw key', async () => {
+    const rawKey = 'sk_validrawkey0001'
+    const { key_hash } = hashApiKey(rawKey)
+    mockLimit.mockResolvedValue({
+      data: [{ id: 'key-id-1', account_id: 'acct-1', scopes: ['read'], key_hash, expires_at: null }],
+      error: null,
+    })
+    process.env.SPINE_CLI_API_KEY = rawKey
+
+    const { buildCliContext } = await loadContext()
+    const ctx = await buildCliContext()
+
+    expect(ctx.principal.type).toBe('machine')
+    expect(ctx.principal.id).toBe('key-id-1')
+    expect(ctx.principal.provenance.apiKeyId).toBe('key-id-1')
+    expect(ctx.principal.provenance.sourceType).toBe('api_key')
+    expect(ctx.accountId).toBe('acct-1')
+    expect(ctx.requestId).toBeTruthy()
+    expect(mockFrom).toHaveBeenCalledWith('api_keys')
+  })
+
+  it('rejects a wrong key sharing the same prefix', async () => {
+    const { key_hash } = hashApiKey('sk_wrongxx_other')
+    mockLimit.mockResolvedValue({
+      data: [{ id: 'key-id-1', account_id: 'acct-1', scopes: [], key_hash, expires_at: null }],
+      error: null,
+    })
+    process.env.SPINE_CLI_API_KEY = 'sk_wrongxx_guess'
+
+    const { buildCliContext } = await loadContext()
+    await expect(buildCliContext()).rejects.toThrow('Invalid or inactive SPINE_CLI_API_KEY')
+  })
+
+  it('skips expired rows and rejects when only expired keys match', async () => {
+    const rawKey = 'sk_expiredkey001'
+    const { key_hash } = hashApiKey(rawKey)
+    mockLimit.mockResolvedValue({
+      data: [{ id: 'key-id-1', account_id: 'acct-1', scopes: [], key_hash, expires_at: '2000-01-01T00:00:00Z' }],
+      error: null,
+    })
+    process.env.SPINE_CLI_API_KEY = rawKey
+
+    const { buildCliContext } = await loadContext()
+    await expect(buildCliContext()).rejects.toThrow('Invalid or inactive SPINE_CLI_API_KEY')
+  })
+
+  it('rejects when no active keys match the prefix', async () => {
+    mockLimit.mockResolvedValue({ data: [], error: null })
+    process.env.SPINE_CLI_API_KEY = 'sk_nomatch_00000'
+
+    const { buildCliContext } = await loadContext()
+    await expect(buildCliContext()).rejects.toThrow('Invalid or inactive SPINE_CLI_API_KEY')
+  })
+})

package/.framework/tests/unit/debug-auth.test.ts

@@ -0,0 +1,38 @@
+import { describe, it, expect, vi } from 'vitest'
+
+const principalRef = vi.hoisted(() => ({ principal: null as any }))
+
+vi.mock('../../functions/_shared/middleware', () => ({
+  createHandler: (fn: any) => async () =>
+    fn({ principal: principalRef.principal, requestId: 'req-1', accountId: 'acct-1' }, {}),
+}))
+
+import { handler } from '../../functions/debug-auth'
+
+const event = (method?: string) => ({ queryStringParameters: method ? { method } : {} })
+
+describe('debug-auth system_admin gate', () => {
+  it('denies a non-admin principal with statusCode 403', async () => {
+    principalRef.principal = { type: 'person', id: 'p1', roles: [{ slug: 'member' }] }
+    await expect(handler(event(), {})).rejects.toMatchObject({ statusCode: 403 })
+  })
+
+  it('denies an unauthenticated request (no principal)', async () => {
+    principalRef.principal = null
+    await expect(handler(event(), {})).rejects.toMatchObject({ statusCode: 403 })
+  })
+
+  it('returns debug data for a system_admin principal', async () => {
+    principalRef.principal = { type: 'person', id: 'p1', roles: [{ slug: 'system_admin' }] }
+    const res = await handler(event('debug'), {})
+    expect(res.data.message).toBe('Debug auth endpoint')
+    expect(res.data.hasPrincipal).toBe(true)
+  })
+
+  it('returns tokenValid for testJwt with a system_admin principal', async () => {
+    principalRef.principal = { type: 'person', id: 'p1', roles: [{ slug: 'system_admin' }] }
+    const res = await handler(event('testJwt'), {})
+    expect(res.data.tokenValid).toBe(true)
+    expect(res.data.principal.id).toBe('p1')
+  })
+})