@pikku/kysely 0.13.6 → 0.13.7

package/dist/src/kysely-scope-service.js

@@ -1,3 +1,4 @@
+import { SystemRoleImmutableError, SystemRoleShadowedError, } from '@pikku/core/errors';
 import { ensurePikkuSchema } from './schema/index.js';
 import { scopeSchema } from './schema/scope.schema.js';
 /**
@@ -79,11 +80,69 @@ export class KyselyScopeService {
             declared: !!row.declared,
         }));
     }
+    /**
+     * Registers the roles declared with `defineSystemRole`.
+     *
+     * Additive on the same terms as `syncScopes` — a role whose declaration has
+     * gone is marked `declared = false` rather than deleted, so a rollback or a
+     * rolling deploy cannot strip everyone's grant. Its *scope set* is replaced
+     * outright, because that is the declaration's entire content: editing
+     * `defineSystemRole` is how you change what a role means, and the deploy is
+     * when it takes effect.
+     */
+    async syncSystemRoles(roles) {
+        await this.db.transaction().execute(async (trx) => {
+            for (const role of roles) {
+                await trx
+                    .insertInto('pikkuRoles')
+                    .values({
+                    name: role.name,
+                    description: role.description ?? null,
+                    system: true,
+                    declared: true,
+                })
+                    .onConflict((oc) => oc.column('name').doUpdateSet((eb) => ({
+                    description: eb.ref('excluded.description'),
+                    system: true,
+                    declared: true,
+                })))
+                    .execute();
+                await trx
+                    .deleteFrom('pikkuRoleScopes')
+                    .where('role', '=', role.name)
+                    .execute();
+                if (role.scopes.length > 0) {
+                    await trx
+                        .insertInto('pikkuRoleScopes')
+                        .values(role.scopes.map((scope) => ({ role: role.name, scope })))
+                        .execute();
+                }
+            }
+            // Only system rows are in scope here: an admin's own role is not
+            // undeclared, it was never declared, and marking it would take it out of
+            // the console for a reason nobody could act on.
+            const markStale = trx
+                .updateTable('pikkuRoles')
+                .set({ declared: false })
+                .where('system', '=', true);
+            await (roles.length > 0
+                ? markStale.where('name', 'not in', roles.map((role) => role.name))
+                : markStale).execute();
+        });
+    }
     async createRole(role) {
+        if (await this.isSystemRole(role.name)) {
+            throw new SystemRoleShadowedError(role.name);
+        }
         await this.db.transaction().execute(async (trx) => {
             await trx
                 .insertInto('pikkuRoles')
-                .values({ name: role.name, description: role.description ?? null })
+                .values({
+                name: role.name,
+                description: role.description ?? null,
+                system: false,
+                declared: true,
+            })
                 .execute();
             if (role.scopes.length > 0) {
                 await trx
@@ -94,9 +153,15 @@ export class KyselyScopeService {
         });
     }
     async deleteRole(name) {
+        if (await this.isSystemRole(name)) {
+            throw new SystemRoleImmutableError(name, 'delete');
+        }
         await this.db.deleteFrom('pikkuRoles').where('name', '=', name).execute();
     }
     async setRoleScopes(name, scopes) {
+        if (await this.isSystemRole(name)) {
+            throw new SystemRoleImmutableError(name, 're-scope');
+        }
         await this.db.transaction().execute(async (trx) => {
             await trx.deleteFrom('pikkuRoleScopes').where('role', '=', name).execute();
             if (scopes.length > 0) {
@@ -107,10 +172,25 @@ export class KyselyScopeService {
             }
         });
     }
+    /**
+     * Whether the store holds this name as a system role.
+     *
+     * Asked of the store rather than of the generated `SYSTEM_ROLES`, because the
+     * store is where a shadow would actually collide — and because a role whose
+     * declaration was deleted is still immutable until someone prunes it.
+     */
+    async isSystemRole(name) {
+        const row = await this.db
+            .selectFrom('pikkuRoles')
+            .select('system')
+            .where('name', '=', name)
+            .executeTakeFirst();
+        return !!row?.system;
+    }
     async listRoles() {
         const roles = await this.db
             .selectFrom('pikkuRoles')
-            .select(['name', 'description'])
+            .select(['name', 'description', 'system', 'declared'])
             .execute();
         const scopeRows = await this.db
             .selectFrom('pikkuRoleScopes')
@@ -130,6 +210,8 @@ export class KyselyScopeService {
             name: role.name,
             description: role.description ?? undefined,
             scopes: byRole.get(role.name) ?? [],
+            system: !!role.system,
+            declared: !!role.declared,
         }));
     }
     async addUserToRole(userId, role, grantedBy) {
@@ -215,4 +297,45 @@ export class KyselyScopeService {
             .execute();
         return deleted.map((r) => r.name);
     }
+    /**
+     * System roles the last sync found no declaration for, with how many people
+     * still hold each. Powers `pikku roles audit`.
+     *
+     * The count is the whole point: "this role is gone from the code" and "this
+     * role is gone from the code and 40 people are standing on it" call for
+     * different decisions, and the number is what makes pruning a choice rather
+     * than a formality.
+     */
+    async findStaleSystemRoles() {
+        const stale = await this.db
+            .selectFrom('pikkuRoles')
+            .leftJoin('pikkuUserRole', 'pikkuUserRole.role', 'pikkuRoles.name')
+            .select(['pikkuRoles.name as role', 'pikkuUserRole.userId as userId'])
+            .where('pikkuRoles.system', '=', true)
+            .where('pikkuRoles.declared', '=', false)
+            .execute();
+        const byRole = new Map();
+        for (const row of stale) {
+            byRole.set(row.role, (byRole.get(row.role) ?? 0) + (row.userId ? 1 : 0));
+        }
+        return [...byRole.entries()].map(([role, users]) => ({ role, users }));
+    }
+    /**
+     * Removes undeclared system roles, cascading them out of every user grant
+     * that holds them. This revokes access, so it is never run implicitly.
+     */
+    async pruneSystemRoles() {
+        const stale = await this.findStaleSystemRoles();
+        if (stale.length === 0) {
+            return [];
+        }
+        const deleted = await this.db
+            .deleteFrom('pikkuRoles')
+            .where('name', 'in', stale.map((s) => s.role))
+            .where('system', '=', true)
+            .where('declared', '=', false)
+            .returning('name')
+            .execute();
+        return deleted.map((r) => r.name);
+    }
 }

package/dist/src/kysely-secret-service.d.ts

@@ -11,6 +11,8 @@ export interface KyselySecretServiceConfig {
 export declare class KyselySecretService implements SecretService {
     private db;
     private initialized;
+    private kekSalts;
+    private keks;
     private key;
     private keyVersion;
     private previousKey?;
@@ -19,6 +21,7 @@ export declare class KyselySecretService implements SecretService {
     constructor(db: Kysely<KyselyPikkuDB>, config: KyselySecretServiceConfig);
     init(): Promise<void>;
     private logAudit;
+    private getKEKSalt;
     private getKEK;
     getSecret<T = string>(key: string): Promise<T>;
     hasSecret(key: string): Promise<boolean>;

package/dist/src/kysely-secret-service.js

@@ -1,9 +1,11 @@
-import { envelopeEncrypt, envelopeDecrypt, envelopeRewrap, } from '@pikku/core/crypto-utils';
+import { deriveKEK, generateKEKSalt, envelopeEncrypt, envelopeDecrypt, envelopeRewrap, } from '@pikku/core/crypto-utils';
 import { ensurePikkuSchema } from './schema/index.js';
 import { secretSchema } from './schema/secret.schema.js';
 export class KyselySecretService {
     db;
     initialized = false;
+    kekSalts = new Map();
+    keks = new Map();
     key;
     keyVersion;
     previousKey;
@@ -38,12 +40,47 @@ export class KyselySecretService {
         })
             .execute();
     }
-    getKEK(version) {
-        if (version === this.keyVersion)
-            return this.key;
-        if (this.previousKey)
-            return this.previousKey;
-        throw new Error(`No KEK available for key_version ${version}`);
+    async getKEKSalt(version) {
+        const cached = this.kekSalts.get(version);
+        if (cached)
+            return cached;
+        const existing = await this.db
+            .selectFrom('secretKekSalts')
+            .select('salt')
+            .where('keyVersion', '=', version)
+            .executeTakeFirst();
+        let salt = existing?.salt;
+        if (!salt) {
+            await this.db
+                .insertInto('secretKekSalts')
+                .values({
+                keyVersion: version,
+                salt: generateKEKSalt(),
+                createdAt: new Date().toISOString(),
+            })
+                .onConflict((oc) => oc.column('keyVersion').doNothing())
+                .execute();
+            const row = await this.db
+                .selectFrom('secretKekSalts')
+                .select('salt')
+                .where('keyVersion', '=', version)
+                .executeTakeFirstOrThrow();
+            salt = row.salt;
+        }
+        this.kekSalts.set(version, salt);
+        return salt;
+    }
+    async getKEK(version) {
+        const cached = this.keks.get(version);
+        if (cached)
+            return cached;
+        const passphrase = version === this.keyVersion ? this.key : this.previousKey;
+        if (!passphrase) {
+            throw new Error(`No KEK available for key_version ${version}`);
+        }
+        const kek = await deriveKEK(passphrase, await this.getKEKSalt(version));
+        this.keks.set(version, kek);
+        return kek;
     }
     async getSecret(key) {
         const row = await this.db
@@ -53,7 +90,7 @@ export class KyselySecretService {
             .executeTakeFirst();
         if (!row)
             throw new Error('Requested secret not found');
-        const kek = this.getKEK(row.keyVersion);
+        const kek = await this.getKEK(row.keyVersion);
         const result = await envelopeDecrypt(kek, row.ciphertext, row.wrappedDek);
         await this.logAudit(key, 'read');
         return result;
@@ -67,7 +104,7 @@ export class KyselySecretService {
         return !!row;
     }
     async setSecret(key, value) {
-        const { ciphertext, wrappedDEK } = await envelopeEncrypt(this.key, value);
+        const { ciphertext, wrappedDEK } = await envelopeEncrypt(await this.getKEK(this.keyVersion), value);
         const now = new Date().toISOString();
         await this.db
             .insertInto('secrets')
@@ -101,7 +138,7 @@ export class KyselySecretService {
         const out = {};
         for (const row of rows) {
             try {
-                const kek = this.getKEK(row.keyVersion);
+                const kek = await this.getKEK(row.keyVersion);
                 out[row.key] = await envelopeDecrypt(kek, row.ciphertext, row.wrappedDek);
             }
             catch (cause) {
@@ -126,8 +163,10 @@ export class KyselySecretService {
             .select(['key', 'wrappedDek'])
             .where('keyVersion', '<', this.keyVersion)
             .execute();
+        const oldKEK = await this.getKEK(this.keyVersion - 1);
+        const newKEK = await this.getKEK(this.keyVersion);
         for (const row of rows) {
-            const newWrappedDEK = await envelopeRewrap(this.previousKey, this.key, row.wrappedDek);
+            const newWrappedDEK = await envelopeRewrap(oldKEK, newKEK, row.wrappedDek);
             await this.db
                 .updateTable('secrets')
                 .set({

package/dist/src/kysely-tables.d.ts

@@ -116,7 +116,12 @@ export interface AIRunTable {
     agentName: string;
     threadId: string;
     resourceId: string;
-    status: Generated<'running' | 'suspended' | 'completed' | 'failed'>;
+    /**
+     * `interrupted` is distinct from `failed`: the run was stopped on purpose,
+     * usually because the user talked over it. Nothing went wrong, so it should
+     * not show up in error reporting.
+     */
+    status: Generated<'running' | 'suspended' | 'completed' | 'failed' | 'interrupted'>;
     errorMessage: string | null;
     suspendReason: 'approval' | 'credential' | 'rpc-missing' | null;
     missingRpcs: string | null;
@@ -146,6 +151,11 @@ export interface SecretsTable {
     createdAt: Generated<Date>;
     updatedAt: Generated<Date>;
 }
+export interface KekSaltsTable {
+    keyVersion: number;
+    salt: string;
+    createdAt: Generated<Date>;
+}
 export interface SecretsAuditTable {
     id: string;
     secretKey: string;
@@ -191,10 +201,14 @@ export interface PikkuScopesTable {
      */
     declared: Generated<boolean>;
 }
-/** A role: an admin-composed bag of scopes. */
+/** A role: a bag of scopes, composed by an admin or declared in code. */
 export interface PikkuRolesTable {
     name: string;
     description: string | null;
+    /** Declared with `defineSystemRole`, and therefore not editable here. */
+    system: Generated<boolean>;
+    /** False for a system role whose declaration has gone: held, but inert. */
+    declared: Generated<boolean>;
     createdAt: Generated<Date>;
 }
 export interface PikkuRoleScopesTable {
@@ -254,8 +268,10 @@ export interface KyselyPikkuDB {
     pikkuDeployments: PikkuDeploymentsTable;
     pikkuDeploymentFunctions: PikkuDeploymentFunctionsTable;
     secrets: SecretsTable;
+    secretKekSalts: KekSaltsTable;
     secretsAudit: SecretsAuditTable;
     credentials: CredentialsTable;
+    credentialKekSalts: KekSaltsTable;
     credentialsAudit: CredentialsAuditTable;
     pikkuUserSessions: UserSessionsTable;
     webhookDelivery: WebhookDeliveryTable;

package/dist/src/kysely-workflow-service.d.ts

@@ -52,7 +52,6 @@ export declare class KyselyWorkflowService extends PikkuWorkflowService {
         failedNodeIds: string[];
         branchKeys: Record<string, string>;
     }>;
-    getNodesWithoutSteps(runId: string, nodeIds: string[]): Promise<string[]>;
     getStepInstances(runId: string): Promise<Array<{
         stepName: string;
         status: StepStatus;

package/dist/src/kysely-workflow-service.js

@@ -393,18 +393,6 @@ export class KyselyWorkflowService extends PikkuWorkflowService {
         }
         return { completedNodeIds, failedNodeIds, branchKeys };
     }
-    async getNodesWithoutSteps(runId, nodeIds) {
-        if (nodeIds.length === 0)
-            return [];
-        const result = await this.db
-            .selectFrom('workflowStep')
-            .select('stepName')
-            .where('workflowRunId', '=', runId)
-            .where('stepName', 'in', nodeIds)
-            .execute();
-        const existingStepNames = new Set(result.map((r) => r.stepName));
-        return nodeIds.filter((id) => !existingStepNames.has(id));
-    }
     async getStepInstances(runId) {
         const rows = await this.db
             .selectFrom('workflowStep')

package/dist/src/schema/credential.schema.js

@@ -22,6 +22,11 @@ export const credentialSchema = {
             .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
             .addColumn('updatedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
         rawStatement(sql `CREATE UNIQUE INDEX credentials_name_user_id_unique ON credentials (name, COALESCE(user_id, ''))`),
+        (db) => db.schema
+            .createTable('credentialKekSalts')
+            .addColumn('keyVersion', 'integer', (col) => col.primaryKey())
+            .addColumn('salt', 'varchar(64)', (col) => col.notNull())
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
         (db) => db.schema
             .createTable('credentialsAudit')
             .addColumn('id', 'varchar(36)', (col) => col.primaryKey())

package/dist/src/schema/scope.schema.js

@@ -29,6 +29,18 @@ export const scopeSchema = {
             .createTable('pikkuRoles')
             .addColumn('name', 'text', (col) => col.primaryKey())
             .addColumn('description', 'text')
+            // Declared in code with `defineSystemRole` rather than composed by an
+            // admin. What it buys is the refusals: a system role cannot be renamed,
+            // re-scoped or deleted from the console, and a console role cannot be
+            // created with its name — two rows answering to one name would make
+            // "does Susan hold `buyer`?" depend on which one the store returned.
+            .addColumn('system', 'boolean', (col) => col.defaultTo(false).notNull())
+            // A system role whose declaration has gone: still held by whoever holds
+            // it, no longer offered for new grants, awaiting `pikku roles prune`.
+            // The same additive contract as `pikkuScopes.declared`, and for the same
+            // reason — a mid-deploy revocation is not something a code edit should
+            // be able to cause.
+            .addColumn('declared', 'boolean', (col) => col.defaultTo(true).notNull())
             .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
         (db) => db.schema
             .createTable('pikkuRoleScopes')

package/dist/src/schema/secret.schema.js

@@ -19,6 +19,11 @@ export const secretSchema = {
             .addColumn('keyVersion', 'integer', (col) => col.notNull())
             .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull())
             .addColumn('updatedAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
+        (db) => db.schema
+            .createTable('secretKekSalts')
+            .addColumn('keyVersion', 'integer', (col) => col.primaryKey())
+            .addColumn('salt', 'varchar(64)', (col) => col.notNull())
+            .addColumn('createdAt', 'timestamp', (col) => col.defaultTo(sql `CURRENT_TIMESTAMP`).notNull()),
         (db) => db.schema
             .createTable('secretsAudit')
             .addColumn('id', 'varchar(36)', (col) => col.primaryKey())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/kysely",
-  "version": "0.13.6",
+  "version": "0.13.7",
   "description": "Kysely-backed Pikku services — workflow state, secrets, sessions, scopes and audit",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
@@ -21,7 +21,7 @@
     "prepublishOnly": "yarn build"
   },
   "peerDependencies": {
-    "@pikku/core": "^0.12.71"
+    "@pikku/core": "^0.12.74"
   },
   "dependencies": {
     "kysely": "^0.29.0"

package/src/kysely-credential-service.ts

@@ -2,6 +2,8 @@ import type { CredentialService } from '@pikku/core/services'
 import type { Kysely } from 'kysely'
 import type { KyselyPikkuDB } from './kysely-tables.js'
 import {
+  deriveKEK,
+  generateKEKSalt,
   envelopeEncrypt,
   envelopeDecrypt,
   envelopeRewrap,
@@ -19,6 +21,8 @@ export interface KyselyCredentialServiceConfig {
 
 export class KyselyCredentialService implements CredentialService {
   private initialized = false
+  private kekSalts = new Map<number, string>()
+  private keks = new Map<number, CryptoKey>()
   private key: string
   private keyVersion: number
   private previousKey?: string
@@ -62,10 +66,52 @@ export class KyselyCredentialService implements CredentialService {
       .execute()
   }
 
-  private getKEK(version: number): string {
-    if (version === this.keyVersion) return this.key
-    if (this.previousKey) return this.previousKey
-    throw new Error(`No KEK available for key_version ${version}`)
+  private async getKEKSalt(version: number): Promise<string> {
+    const cached = this.kekSalts.get(version)
+    if (cached) return cached
+
+    const existing = await this.db
+      .selectFrom('credentialKekSalts')
+      .select('salt')
+      .where('keyVersion', '=', version)
+      .executeTakeFirst()
+
+    let salt = existing?.salt
+    if (!salt) {
+      await this.db
+        .insertInto('credentialKekSalts')
+        .values({
+          keyVersion: version,
+          salt: generateKEKSalt(),
+          createdAt: new Date().toISOString() as unknown as Date,
+        })
+        .onConflict((oc) => oc.column('keyVersion').doNothing())
+        .execute()
+
+      const row = await this.db
+        .selectFrom('credentialKekSalts')
+        .select('salt')
+        .where('keyVersion', '=', version)
+        .executeTakeFirstOrThrow()
+      salt = row.salt
+    }
+
+    this.kekSalts.set(version, salt)
+    return salt
+  }
+
+  private async getKEK(version: number): Promise<CryptoKey> {
+    const cached = this.keks.get(version)
+    if (cached) return cached
+
+    const passphrase = version === this.keyVersion ? this.key : this.previousKey
+    if (!passphrase) {
+      throw new Error(`No KEK available for key_version ${version}`)
+    }
+
+    const kek = await deriveKEK(passphrase, await this.getKEKSalt(version))
+    this.keks.set(version, kek)
+    return kek
   }
 
   private whereUserId(qb: any, userId?: string) {
@@ -84,7 +130,7 @@ export class KyselyCredentialService implements CredentialService {
     const row = await qb.executeTakeFirst()
     if (!row) return null
 
-    const kek = this.getKEK(row.keyVersion)
+    const kek = await this.getKEK(row.keyVersion)
     const plaintext = await envelopeDecrypt<string>(
       kek,
       row.ciphertext,
@@ -102,7 +148,7 @@ export class KyselyCredentialService implements CredentialService {
   async set(name: string, value: unknown, userId?: string): Promise<void> {
     const plaintext = JSON.stringify(value)
     const { ciphertext, wrappedDEK } = await envelopeEncrypt(
-      this.key,
+      await this.getKEK(this.keyVersion),
       plaintext
     )
     const now = new Date().toISOString()
@@ -166,7 +212,7 @@ export class KyselyCredentialService implements CredentialService {
 
     const result: Record<string, unknown> = {}
     for (const row of rows) {
-      const kek = this.getKEK(row.keyVersion)
+      const kek = await this.getKEK(row.keyVersion)
       const plaintext = await envelopeDecrypt<string>(
         kek,
         row.ciphertext,
@@ -216,12 +262,11 @@ export class KyselyCredentialService implements CredentialService {
       .where('keyVersion', '<', this.keyVersion)
       .execute()
 
+    const oldKEK = await this.getKEK(this.keyVersion - 1)
+    const newKEK = await this.getKEK(this.keyVersion)
+
     for (const row of rows) {
-      const newWrappedDEK = await envelopeRewrap(
-        this.previousKey,
-        this.key,
-        row.wrappedDek
-      )
+      const newWrappedDEK = await envelopeRewrap(oldKEK, newKEK, row.wrappedDek)
       let qb = this.db
         .updateTable('credentials')
         .set({