@pikku/kysely 0.13.0 → 0.13.2

package/src/kysely-scope-service.ts

@@ -0,0 +1,350 @@
+import type { Role, ScopeService } from '@pikku/core/services'
+import type { FlatScope } from '@pikku/core/scope'
+import type { Kysely } from 'kysely'
+import { sql } from 'kysely'
+import type { KyselyPikkuDB } from './kysely-tables.js'
+
+/**
+ * Resolves and administers user scopes against four self-created tables.
+ *
+ * Requires better-auth: `pikku_user_role.user_id` references its `user` table
+ * with ON DELETE CASCADE, so deleting a user takes their grants with it. That
+ * table is created by better-auth's own migrations, which `pikku db migrate`
+ * hard-fails without, so it exists before `init()` runs.
+ *
+ * Scopes are declared in code and synced here; roles are data, composed by
+ * admins at runtime. `pikku_role_scopes` FKs into `pikku_scopes`, so the
+ * database itself refuses to grant a scope that was never declared.
+ */
+export class KyselyScopeService implements ScopeService {
+  private initialized = false
+
+  constructor(private db: Kysely<KyselyPikkuDB>) {}
+
+  public async init(): Promise<void> {
+    if (this.initialized) {
+      return
+    }
+
+    await this.db.schema
+      .createTable('pikku_scopes')
+      .ifNotExists()
+      .addColumn('name', 'text', (col) => col.primaryKey())
+      .addColumn('description', 'text')
+      .addColumn('declared', 'boolean', (col) => col.defaultTo(true).notNull())
+      .execute()
+
+    await this.db.schema
+      .createTable('pikku_roles')
+      .ifNotExists()
+      .addColumn('name', 'text', (col) => col.primaryKey())
+      .addColumn('description', 'text')
+      .addColumn('created_at', 'timestamp', (col) =>
+        col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+      )
+      .execute()
+
+    await this.db.schema
+      .createTable('pikku_role_scopes')
+      .ifNotExists()
+      .addColumn('role', 'text', (col) =>
+        col.notNull().references('pikku_roles.name').onDelete('cascade')
+      )
+      .addColumn('scope', 'text', (col) =>
+        col.notNull().references('pikku_scopes.name').onDelete('cascade')
+      )
+      .addPrimaryKeyConstraint('pikku_role_scopes_pk', ['role', 'scope'])
+      .execute()
+
+    await this.db.schema
+      .createTable('pikku_user_role')
+      .ifNotExists()
+      .addColumn('user_id', 'text', (col) =>
+        col.notNull().references('user.id').onDelete('cascade')
+      )
+      .addColumn('role', 'text', (col) =>
+        col.notNull().references('pikku_roles.name').onDelete('cascade')
+      )
+      .addColumn('granted_by', 'text')
+      .addColumn('granted_at', 'timestamp', (col) =>
+        col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+      )
+      .addPrimaryKeyConstraint('pikku_user_role_pk', ['user_id', 'role'])
+      .execute()
+
+    await this.db.schema
+      .createTable('pikku_user_scope')
+      .ifNotExists()
+      .addColumn('user_id', 'text', (col) =>
+        col.notNull().references('user.id').onDelete('cascade')
+      )
+      .addColumn('scope', 'text', (col) =>
+        col.notNull().references('pikku_scopes.name').onDelete('cascade')
+      )
+      .addColumn('granted_by', 'text')
+      .addColumn('granted_at', 'timestamp', (col) =>
+        col.defaultTo(sql`CURRENT_TIMESTAMP`).notNull()
+      )
+      .addPrimaryKeyConstraint('pikku_user_scope_pk', ['user_id', 'scope'])
+      .execute()
+
+    await this.db.schema
+      .createIndex('pikku_role_scopes_scope_idx')
+      .ifNotExists()
+      .on('pikku_role_scopes')
+      .column('scope')
+      .execute()
+
+    await this.db.schema
+      .createIndex('pikku_user_role_role_idx')
+      .ifNotExists()
+      .on('pikku_user_role')
+      .column('role')
+      .execute()
+
+    this.initialized = true
+  }
+
+  /**
+   * Registers the declared scope set.
+   *
+   * Additive: rows are upserted and anything no longer declared is *marked*
+   * (`declared = false`), never deleted. Marking is non-destructive, so a
+   * rename, a rollback, or a rolling deploy where an older replica is still
+   * serving cannot silently strip a grant. `pruneScopes` is the deliberate
+   * removal path.
+   */
+  async syncScopes(scopes: FlatScope[]): Promise<void> {
+    await this.db.transaction().execute(async (trx) => {
+      if (scopes.length > 0) {
+        await trx
+          .insertInto('pikkuScopes')
+          .values(
+            scopes.map((scope) => ({
+              name: scope.id,
+              description: scope.description ?? null,
+              declared: true,
+            }))
+          )
+          .onConflict((oc) =>
+            oc.column('name').doUpdateSet((eb) => ({
+              description: eb.ref('excluded.description'),
+              declared: true,
+            }))
+          )
+          .execute()
+      }
+
+      const markStale = trx.updateTable('pikkuScopes').set({ declared: false })
+      await (
+        scopes.length > 0
+          ? markStale.where(
+              'name',
+              'not in',
+              scopes.map((s) => s.id)
+            )
+          : markStale
+      ).execute()
+    })
+  }
+
+  async resolveScopes(userId: string): Promise<string[]> {
+    const roleScopes = this.db
+      .selectFrom('pikkuUserRole')
+      .innerJoin(
+        'pikkuRoleScopes',
+        'pikkuRoleScopes.role',
+        'pikkuUserRole.role'
+      )
+      .select('pikkuRoleScopes.scope')
+      .where('pikkuUserRole.userId', '=', userId)
+
+    const directScopes = this.db
+      .selectFrom('pikkuUserScope')
+      .select('pikkuUserScope.scope')
+      .where('pikkuUserScope.userId', '=', userId)
+
+    const rows = await roleScopes.union(directScopes).execute()
+
+    return rows.map((row) => row.scope)
+  }
+
+  async listScopes(): Promise<Array<FlatScope & { declared: boolean }>> {
+    const rows = await this.db
+      .selectFrom('pikkuScopes')
+      .select(['name', 'description', 'declared'])
+      .execute()
+
+    return rows.map((row) => ({
+      id: row.name,
+      description: row.description ?? undefined,
+      declared: !!row.declared,
+    }))
+  }
+
+  async createRole(role: Role): Promise<void> {
+    await this.db.transaction().execute(async (trx) => {
+      await trx
+        .insertInto('pikkuRoles')
+        .values({ name: role.name, description: role.description ?? null })
+        .execute()
+
+      if (role.scopes.length > 0) {
+        await trx
+          .insertInto('pikkuRoleScopes')
+          .values(role.scopes.map((scope) => ({ role: role.name, scope })))
+          .execute()
+      }
+    })
+  }
+
+  async deleteRole(name: string): Promise<void> {
+    await this.db.deleteFrom('pikkuRoles').where('name', '=', name).execute()
+  }
+
+  async setRoleScopes(name: string, scopes: string[]): Promise<void> {
+    await this.db.transaction().execute(async (trx) => {
+      await trx.deleteFrom('pikkuRoleScopes').where('role', '=', name).execute()
+
+      if (scopes.length > 0) {
+        await trx
+          .insertInto('pikkuRoleScopes')
+          .values(scopes.map((scope) => ({ role: name, scope })))
+          .execute()
+      }
+    })
+  }
+
+  async listRoles(): Promise<Role[]> {
+    const roles = await this.db
+      .selectFrom('pikkuRoles')
+      .select(['name', 'description'])
+      .execute()
+
+    const scopeRows = await this.db
+      .selectFrom('pikkuRoleScopes')
+      .select(['role', 'scope'])
+      .execute()
+
+    const byRole = new Map<string, string[]>()
+    for (const row of scopeRows) {
+      const existing = byRole.get(row.role)
+      if (existing) {
+        existing.push(row.scope)
+      } else {
+        byRole.set(row.role, [row.scope])
+      }
+    }
+
+    return roles.map((role) => ({
+      name: role.name,
+      description: role.description ?? undefined,
+      scopes: byRole.get(role.name) ?? [],
+    }))
+  }
+
+  async addUserToRole(
+    userId: string,
+    role: string,
+    grantedBy?: string
+  ): Promise<void> {
+    await this.db
+      .insertInto('pikkuUserRole')
+      .values({ userId, role, grantedBy: grantedBy ?? null })
+      .onConflict((oc) => oc.columns(['userId', 'role']).doNothing())
+      .execute()
+  }
+
+  async removeUserFromRole(userId: string, role: string): Promise<void> {
+    await this.db
+      .deleteFrom('pikkuUserRole')
+      .where('userId', '=', userId)
+      .where('role', '=', role)
+      .execute()
+  }
+
+  async listUserRoles(userId: string): Promise<string[]> {
+    const rows = await this.db
+      .selectFrom('pikkuUserRole')
+      .select('role')
+      .where('userId', '=', userId)
+      .execute()
+
+    return rows.map((row) => row.role)
+  }
+
+  async addScopeToUser(
+    userId: string,
+    scope: string,
+    grantedBy?: string
+  ): Promise<void> {
+    await this.db
+      .insertInto('pikkuUserScope')
+      .values({ userId, scope, grantedBy: grantedBy ?? null })
+      .onConflict((oc) => oc.columns(['userId', 'scope']).doNothing())
+      .execute()
+  }
+
+  async removeScopeFromUser(userId: string, scope: string): Promise<void> {
+    await this.db
+      .deleteFrom('pikkuUserScope')
+      .where('userId', '=', userId)
+      .where('scope', '=', scope)
+      .execute()
+  }
+
+  async listUserScopes(userId: string): Promise<string[]> {
+    const rows = await this.db
+      .selectFrom('pikkuUserScope')
+      .select('scope')
+      .where('userId', '=', userId)
+      .execute()
+
+    return rows.map((row) => row.scope)
+  }
+
+  /**
+   * Scopes marked undeclared by the last sync, with the roles that would lose
+   * them. Powers `pikku scopes audit`.
+   */
+  async findStaleScopes(): Promise<Array<{ scope: string; roles: string[] }>> {
+    const stale = await this.db
+      .selectFrom('pikkuScopes')
+      .leftJoin('pikkuRoleScopes', 'pikkuRoleScopes.scope', 'pikkuScopes.name')
+      .select(['pikkuScopes.name as scope', 'pikkuRoleScopes.role as role'])
+      .where('pikkuScopes.declared', '=', false)
+      .execute()
+
+    const byScope = new Map<string, string[]>()
+    for (const row of stale) {
+      const roles = byScope.get(row.scope) ?? []
+      if (row.role) {
+        roles.push(row.role)
+      }
+      byScope.set(row.scope, roles)
+    }
+
+    return [...byScope.entries()].map(([scope, roles]) => ({ scope, roles }))
+  }
+
+  /**
+   * Removes undeclared scopes, cascading them out of every role that holds
+   * them. This revokes access, so it is never run implicitly.
+   */
+  async pruneScopes(): Promise<string[]> {
+    const stale = await this.findStaleScopes()
+    if (stale.length === 0) {
+      return []
+    }
+
+    const names = stale.map((s) => s.scope)
+    const deleted = await this.db
+      .deleteFrom('pikkuScopes')
+      .where('name', 'in', names)
+      .where('declared', '=', false)
+      .returning('name')
+      .execute()
+
+    return deleted.map((r) => r.name)
+  }
+}

package/src/kysely-tables.ts

@@ -187,7 +187,79 @@ export interface UserSessionsTable {
   updatedAt: Generated<Date>
 }
 
+/**
+ * The declared scope set, synced from generated SCOPES.
+ *
+ * Additive: a scope removed from code leaves an inert row rather than
+ * cascading a grant away mid-deploy. `pikku scopes prune` removes them
+ * deliberately.
+ */
+export interface PikkuScopesTable {
+  name: string
+  description: string | null
+  /**
+   * False once a scope is no longer declared in code. Marking is
+   * non-destructive — grants survive until `pikku scopes prune` removes them
+   * deliberately.
+   */
+  declared: Generated<boolean>
+}
+
+/** A role: an admin-composed bag of scopes. */
+export interface PikkuRolesTable {
+  name: string
+  description: string | null
+  createdAt: Generated<Date>
+}
+
+export interface PikkuRoleScopesTable {
+  role: string
+  scope: string
+}
+
+export interface PikkuUserRoleTable {
+  userId: string
+  role: string
+  grantedBy: string | null
+  grantedAt: Generated<Date>
+}
+
+/** A scope granted directly to a user, outside of any role. */
+export interface PikkuUserScopeTable {
+  userId: string
+  scope: string
+  grantedBy: string | null
+  grantedAt: Generated<Date>
+}
+
+export interface WebhookDeliveryTable {
+  deliveryId: string
+  organizationId: string | null
+  url: string
+  event: string | null
+  status: Generated<'pending' | 'delivered' | 'failed'>
+  attempts: Generated<number>
+  createdAt: Generated<Date>
+  updatedAt: Generated<Date>
+  deliveredAt: Date | null
+}
+
+export interface WebhookDeliveryAttemptTable {
+  attemptId: string
+  deliveryId: string
+  attemptNumber: number
+  statusCode: number | null
+  responseBody: string | null
+  error: string | null
+  createdAt: Generated<Date>
+}
+
 export interface KyselyPikkuDB {
+  pikkuScopes: PikkuScopesTable
+  pikkuRoles: PikkuRolesTable
+  pikkuRoleScopes: PikkuRoleScopesTable
+  pikkuUserRole: PikkuUserRoleTable
+  pikkuUserScope: PikkuUserScopeTable
   channels: ChannelsTable
   channelSubscriptions: ChannelSubscriptionsTable
   workflowRuns: WorkflowRunsTable
@@ -206,4 +278,6 @@ export interface KyselyPikkuDB {
   credentials: CredentialsTable
   credentialsAudit: CredentialsAuditTable
   pikkuUserSessions: UserSessionsTable
+  webhookDelivery: WebhookDeliveryTable
+  webhookDeliveryAttempt: WebhookDeliveryAttemptTable
 }

package/src/kysely-webhook-service.test.ts

@@ -0,0 +1,120 @@
+import { describe, test, beforeEach } from 'node:test'
+import assert from 'node:assert/strict'
+import { CamelCasePlugin, Kysely, SqliteDialect } from 'kysely'
+import Database from 'better-sqlite3'
+import { setSingletonServices } from '@pikku/core'
+
+import type { KyselyPikkuDB } from './kysely-tables.js'
+import { SerializePlugin } from './serialize-plugin.js'
+import { KyselyWebhookService } from './kysely-webhook-service.js'
+
+const noopLogger = { error() {}, info() {}, warn() {}, debug() {} }
+
+function createDb(): Kysely<KyselyPikkuDB> {
+  return new Kysely<KyselyPikkuDB>({
+    dialect: new SqliteDialect({ database: new Database(':memory:') }),
+    plugins: [new CamelCasePlugin(), new SerializePlugin()],
+  })
+}
+
+const createQueue = () => {
+  const added: { data: any; options: any }[] = []
+  return {
+    added,
+    queue: {
+      supportsResults: false,
+      add: async (_name: string, data: any, options: any) => {
+        added.push({ data, options })
+        return options?.jobId ?? 'job-1'
+      },
+      getJob: async () => null,
+    },
+  }
+}
+
+// send() resolves config/secrets through the singleton services.
+const setServices = () =>
+  setSingletonServices({
+    logger: noopLogger,
+    config: {},
+    secrets: {
+      getSecret: async (key: string) => {
+        throw new Error(`Secret not found: ${key}`)
+      },
+    },
+  } as any)
+
+describe('KyselyWebhookService', () => {
+  beforeEach(setServices)
+
+  test('send() inserts a pending delivery and enqueues with deliveryId === jobId', async () => {
+    const db = createDb()
+    const { added, queue } = createQueue()
+    const service = new KyselyWebhookService(queue as any, db)
+    await service.init()
+
+    const { jobId } = await service.send({
+      url: 'https://example.com/hook',
+      event: 'user.created',
+      data: { id: 'u1' },
+      organizationId: 'org-1',
+    })
+
+    // jobId is the delivery id and rides in the payload.
+    assert.equal(added.length, 1)
+    assert.equal(added[0]!.options.jobId, jobId)
+    assert.equal(added[0]!.data.deliveryId, jobId)
+
+    const delivery = await service.getDelivery(jobId)
+    assert.ok(delivery)
+    assert.equal(delivery!.delivery.status, 'pending')
+    assert.equal(delivery!.delivery.organizationId, 'org-1')
+    assert.equal(delivery!.delivery.url, 'https://example.com/hook')
+    assert.equal(delivery!.attempts.length, 0)
+  })
+
+  test('recordAttempt() appends attempts and rolls status forward', async () => {
+    const db = createDb()
+    const { queue } = createQueue()
+    const service = new KyselyWebhookService(queue as any, db)
+    await service.init()
+
+    const { jobId } = await service.send({
+      url: 'https://example.com/hook',
+      data: {},
+    })
+
+    await service.recordAttempt(jobId, {
+      statusCode: 500,
+      error: 'boom',
+      delivered: false,
+    })
+    await service.recordAttempt(jobId, { statusCode: 200, delivered: true })
+
+    const result = await service.getDelivery(jobId)
+    assert.equal(result!.attempts.length, 2)
+    assert.equal(result!.attempts[0]!.attemptNumber, 1)
+    assert.equal(result!.attempts[0]!.statusCode, 500)
+    assert.equal(result!.attempts[1]!.attemptNumber, 2)
+    assert.equal(result!.delivery.status, 'delivered')
+    assert.equal(result!.delivery.attempts, 2)
+    assert.ok(result!.delivery.deliveredAt)
+  })
+
+  test('listDeliveries() filters by organization', async () => {
+    const db = createDb()
+    const { queue } = createQueue()
+    const service = new KyselyWebhookService(queue as any, db)
+    await service.init()
+
+    await service.send({ url: 'https://a.com', data: {}, organizationId: 'o1' })
+    await service.send({ url: 'https://b.com', data: {}, organizationId: 'o2' })
+
+    const o1 = await service.listDeliveries({ organizationId: 'o1' })
+    assert.equal(o1.length, 1)
+    assert.equal(o1[0]!.url, 'https://a.com')
+
+    const all = await service.listDeliveries()
+    assert.equal(all.length, 2)
+  })
+})