@pikku/kysely 0.13.6 → 0.13.10

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

@@ -1,4 +1,64 @@
+import { ensurePikkuSchema } from './schema/index.js';
+import { auditSchema } from './schema/audit.schema.js';
 const jsonOrNull = (v) => v != null ? JSON.stringify(v) : null;
+const parseJson = (v) => {
+    if (typeof v !== 'string')
+        return v ?? undefined;
+    try {
+        return JSON.parse(v);
+    }
+    catch {
+        // A row written by something other than this service, or truncated in
+        // transit. Surfacing the raw text beats dropping the event: the row is
+        // still evidence that something happened, and swallowing it would make the
+        // trail quietly incomplete.
+        return v;
+    }
+};
+/**
+ * A column by its physical name, whatever the connection renamed it to.
+ *
+ * `CamelCasePlugin` is on most pikku Kysely instances and rewrites result keys
+ * on the way out, so the same row arrives keyed `audit_id` or `auditId`
+ * depending on a plugin this service is never told about. Reading both is
+ * cheaper than demanding a particular connection — and quieter to get wrong,
+ * since the mismatch does not throw, it just returns a page of undefined.
+ */
+const column = (row, name) => {
+    const value = row[name];
+    if (value !== undefined)
+        return value;
+    return row[name.replace(/_(\w)/g, (_, char) => char.toUpperCase())];
+};
+/** Rows are TEXT on every engine, so the shape is whatever the driver returned. */
+const rowToEvent = (row) => {
+    const userId = column(row, 'user_id');
+    const orgId = column(row, 'org_id');
+    const pikkuUserId = column(row, 'pikku_user_id');
+    return {
+        eventId: column(row, 'audit_id') ?? undefined,
+        occurredAt: column(row, 'occurred_at'),
+        type: row.type,
+        source: row.source ?? 'auto',
+        outcome: row.outcome ?? undefined,
+        functionId: column(row, 'function_id') ?? undefined,
+        wireType: column(row, 'wire_type') ?? undefined,
+        traceId: column(row, 'trace_id') ?? undefined,
+        transactionId: column(row, 'transaction_id') ?? undefined,
+        queryId: column(row, 'query_id') ?? undefined,
+        userIdentity: userId || orgId || pikkuUserId
+            ? {
+                userId: userId ?? undefined,
+                orgId: orgId ?? undefined,
+                pikkuUserId: pikkuUserId ?? undefined,
+            }
+            : undefined,
+        metadata: parseJson(row.data),
+    };
+};
+/** The most a single page may return, whatever the caller asked for. */
+const MAX_LIMIT = 200;
+const DEFAULT_LIMIT = 50;
 // No global `crypto` is guaranteed across every runtime, and audit_id is the
 // PK — any collision is dropped by ON CONFLICT DO NOTHING.
 const fallbackId = () => `evt_${Date.now().toString(36)}${Math.random().toString(36).slice(2, 10)}`;
@@ -8,16 +68,31 @@ const fallbackId = () => `evt_${Date.now().toString(36)}${Math.random().toString
  *
  * The column mapping matches a platform audit-queue consumer, so a locally-run
  * project and a deployed stage write identical rows (the read side relies only
- * on `type`, `occurred_at`, `actor_user_id`, and the `data` JSON that holds
+ * on `type`, `occurred_at`, `user_id`, and the `data` JSON that holds
  * `metadata`). The `audit` table is an optional per-project migration (not in
  * the generated schema), so rows are inserted untyped; all columns are TEXT on
  * every engine and ON CONFLICT DO NOTHING keeps writes idempotent on retries.
  */
 export class KyselyAuditService {
     db;
+    initialized = false;
     constructor(db) {
         this.db = db;
     }
+    /**
+     * Creates the `audit` table if the database has none.
+     *
+     * Optional — a project that migrates the table itself can skip it, and the
+     * declaration is written to match the documented shape either way. Calling it
+     * on a database that already has the table is a no-op, so two instances
+     * booting cold do not race each other into a half-applied schema.
+     */
+    async init() {
+        if (this.initialized)
+            return;
+        await ensurePikkuSchema(this.db, auditSchema);
+        this.initialized = true;
+    }
     async audit(event) {
         await this.write([event]);
     }
@@ -37,8 +112,9 @@ export class KyselyAuditService {
                 trace_id: e.traceId ?? null,
                 transaction_id: e.transactionId ?? null,
                 query_id: e.queryId ?? null,
-                actor_user_id: e.actor?.userId ?? null,
-                actor_org_id: e.actor?.orgId ?? null,
+                user_id: e.userIdentity?.userId ?? null,
+                org_id: e.userIdentity?.orgId ?? null,
+                pikku_user_id: e.userIdentity?.pikkuUserId ?? null,
                 tables: jsonOrNull(metadata?.tables),
                 changed_cols: jsonOrNull(metadata?.changedColumns),
                 event: e.eventId ?? null,
@@ -52,4 +128,88 @@ export class KyselyAuditService {
             .onConflict((oc) => oc.doNothing())
             .execute();
     }
+    /**
+     * A page of the trail, newest first.
+     *
+     * Offset paging, matching the rest of the console. The trail is append-only
+     * and ordered by `occurred_at DESC`, so events written *while* a reader is
+     * paging shift the window and can repeat a row across pages. That is visible
+     * but harmless for browsing; anything that must not miss a row should page by
+     * a bounded `from`/`to` window instead of scrolling.
+     *
+     * Ties on `occurred_at` are broken by `audit_id` so the order is total —
+     * without it a batch flushed in one call shares a timestamp and the engine is
+     * free to order it differently per query, which drops or repeats rows at a
+     * page boundary.
+     */
+    async query(query = {}) {
+        const limit = Math.min(Math.max(query.limit ?? DEFAULT_LIMIT, 1), MAX_LIMIT);
+        const offset = Math.max(query.offset ?? 0, 0);
+        let builder = this.db.selectFrom('audit').selectAll();
+        builder = this.applyFilters(builder, query);
+        const rows = await builder
+            .orderBy('occurred_at', 'desc')
+            .orderBy('audit_id', 'desc')
+            // One extra row is the cheapest honest way to know whether another page
+            // exists — a COUNT would be a second scan of the same filter.
+            .limit(limit + 1)
+            .offset(offset)
+            .execute();
+        const hasMore = rows.length > limit;
+        return {
+            events: rows.slice(0, limit).map(rowToEvent),
+            nextCursor: hasMore ? offset + limit : null,
+        };
+    }
+    async facets() {
+        const [users, types] = await Promise.all([
+            this.db
+                .selectFrom('audit')
+                .select('user_id')
+                .distinct()
+                .where('user_id', 'is not', null)
+                .orderBy('user_id', 'asc')
+                .execute(),
+            this.db
+                .selectFrom('audit')
+                .select('type')
+                .distinct()
+                .orderBy('type', 'asc')
+                .execute(),
+        ]);
+        return {
+            userIds: users.map((r) => column(r, 'user_id')),
+            types: types.map((r) => r.type).filter(Boolean),
+        };
+    }
+    /**
+     * An empty array means "match nothing" and is applied as such. Treating it as
+     * "no filter" would turn a reader's deselect-everything into a full-trail
+     * read, which is the opposite of what they asked for.
+     */
+    applyFilters(builder, query) {
+        // `in ()` is a syntax error on Postgres and SQLite alike, so an empty
+        // selection is expressed as a predicate that cannot hold.
+        const matchNothing = (b) => b.where('audit_id', 'is', null);
+        if (query.userIds) {
+            builder = query.userIds.length
+                ? builder.where('user_id', 'in', query.userIds)
+                : matchNothing(builder);
+        }
+        if (query.types) {
+            builder = query.types.length
+                ? builder.where('type', 'in', query.types)
+                : matchNothing(builder);
+        }
+        if (query.orgId) {
+            builder = builder.where('org_id', '=', query.orgId);
+        }
+        if (query.from) {
+            builder = builder.where('occurred_at', '>=', query.from);
+        }
+        if (query.to) {
+            builder = builder.where('occurred_at', '<', query.to);
+        }
+        return builder;
+    }
 }

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

@@ -11,6 +11,8 @@ export interface KyselyCredentialServiceConfig {
 export declare class KyselyCredentialService implements CredentialService {
     private db;
     private initialized;
+    private kekSalts;
+    private keks;
     private key;
     private keyVersion;
     private previousKey?;
@@ -19,6 +21,7 @@ export declare class KyselyCredentialService implements CredentialService {
     constructor(db: Kysely<KyselyPikkuDB>, config: KyselyCredentialServiceConfig);
     init(): Promise<void>;
     private logAudit;
+    private getKEKSalt;
     private getKEK;
     private whereUserId;
     get<T = unknown>(name: string, userId?: string): Promise<T | null>;

package/dist/src/kysely-credential-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 { credentialSchema } from './schema/credential.schema.js';
 export class KyselyCredentialService {
     db;
     initialized = false;
+    kekSalts = new Map();
+    keks = new Map();
     key;
     keyVersion;
     previousKey;
@@ -39,12 +41,47 @@ export class KyselyCredentialService {
         })
             .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('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(),
+            })
+                .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;
+    }
+    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;
     }
     whereUserId(qb, userId) {
         return userId
@@ -60,7 +97,7 @@ export class KyselyCredentialService {
         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(kek, row.ciphertext, row.wrappedDek);
         await this.logAudit(name, userId, 'read');
         try {
@@ -72,7 +109,7 @@ export class KyselyCredentialService {
     }
     async set(name, value, userId) {
         const plaintext = JSON.stringify(value);
-        const { ciphertext, wrappedDEK } = await envelopeEncrypt(this.key, plaintext);
+        const { ciphertext, wrappedDEK } = await envelopeEncrypt(await this.getKEK(this.keyVersion), plaintext);
         const now = new Date().toISOString();
         const exists = await this.has(name, userId);
         if (exists) {
@@ -127,7 +164,7 @@ export class KyselyCredentialService {
             .execute();
         const result = {};
         for (const row of rows) {
-            const kek = this.getKEK(row.keyVersion);
+            const kek = await this.getKEK(row.keyVersion);
             const plaintext = await envelopeDecrypt(kek, row.ciphertext, row.wrappedDek);
             try {
                 result[row.name] = JSON.parse(plaintext);
@@ -166,8 +203,10 @@ export class KyselyCredentialService {
             .select(['name', 'userId', '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);
             let qb = this.db
                 .updateTable('credentials')
                 .set({

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

@@ -1,5 +1,6 @@
 import type { Role, ScopeService } from '@pikku/core/services';
 import type { FlatScope } from '@pikku/core/scope';
+import type { SystemRole } from '@pikku/core/role';
 import type { Kysely } from 'kysely';
 import type { KyselyPikkuDB } from './kysely-tables.js';
 /**
@@ -33,9 +34,28 @@ export declare class KyselyScopeService implements ScopeService {
     listScopes(): Promise<Array<FlatScope & {
         declared: boolean;
     }>>;
+    /**
+     * 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.
+     */
+    syncSystemRoles(roles: SystemRole[]): Promise<void>;
     createRole(role: Role): Promise<void>;
     deleteRole(name: string): Promise<void>;
     setRoleScopes(name: string, scopes: string[]): Promise<void>;
+    /**
+     * 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.
+     */
+    private isSystemRole;
     listRoles(): Promise<Role[]>;
     addUserToRole(userId: string, role: string, grantedBy?: string): Promise<void>;
     removeUserFromRole(userId: string, role: string): Promise<void>;
@@ -56,4 +76,22 @@ export declare class KyselyScopeService implements ScopeService {
      * them. This revokes access, so it is never run implicitly.
      */
     pruneScopes(): Promise<string[]>;
+    /**
+     * 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.
+     */
+    findStaleSystemRoles(): Promise<Array<{
+        role: string;
+        users: number;
+    }>>;
+    /**
+     * Removes undeclared system roles, cascading them out of every user grant
+     * that holds them. This revokes access, so it is never run implicitly.
+     */
+    pruneSystemRoles(): Promise<string[]>;
 }

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

@@ -1,4 +1,5 @@
-import type { SecretService } from '@pikku/core/services';
+import { type SecretValue } from '@pikku/core';
+import type { SecretService, SecretValues } from '@pikku/core/services';
 import type { Kysely } from 'kysely';
 import type { KyselyPikkuDB } from './kysely-tables.js';
 export interface KyselySecretServiceConfig {
@@ -11,6 +12,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,11 +22,12 @@ 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>;
+    getSecret<T = string>(key: string): Promise<SecretValue<T>>;
     hasSecret(key: string): Promise<boolean>;
     setSecret(key: string, value: unknown): Promise<void>;
     deleteSecret(key: string): Promise<void>;
-    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<T>;
+    getSecrets<T extends Record<string, unknown> = Record<string, unknown>>(keys: (keyof T & string)[]): Promise<Partial<SecretValues<T>>>;
     rotateKEK(): Promise<number>;
 }