@cosmicdrift/kumiko-bundled-features 0.1.0

package/src/secrets/handlers/rotate.job.ts

@@ -0,0 +1,193 @@
+// Rotation job. Scans tenant_secrets for rows whose kekVersion is older
+// than provider.currentVersion() and rewraps their DEK under the new KEK
+// — the ciphertext itself never changes, only the 60-byte DEK wrapper
+// and the kek_version column. See architecture/core-secrets.md for the
+// full rotation story.
+//
+// The job is idempotent: re-running it after a partial failure picks up
+// the remaining old-version rows. Consumers that want a time-bound run
+// pass a maxDurationMs in the payload.
+//
+// Post-ES pivot: each rotation is an executor.update against the
+// tenantSecret aggregate. The resulting `.updated` event carries
+// {changes, previous} with BOTH envelopes — useful for a full rotation
+// audit trail (when did row X flip from v1 to v2, who triggered it).
+// Concurrency-guard shifts from the pre-ES `WHERE kek_version = old`
+// check to the executor's stream-version check; a parallel secrets.set
+// that landed the row on the new kekVersion first surfaces here as a
+// version_conflict error (counted as "skipped", not "failed").
+
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+  type TenantDb,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { JobHandlerFn, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
+import { rewrapDek } from "@cosmicdrift/kumiko-framework/secrets";
+import { ne } from "drizzle-orm";
+import { type StoredEnvelope, tenantSecretEntity, tenantSecretsTable } from "../table";
+
+const DEFAULT_BATCH_SIZE = 100;
+const DEFAULT_MAX_FAILURES = 10;
+const SYSTEM_ROLES = ["system"] as const;
+
+const executor = createEventStoreExecutor(tenantSecretsTable, tenantSecretEntity, {
+  entityName: "tenant-secret",
+});
+
+export type RotateJobPayload = {
+  readonly batchSize?: number;
+  readonly maxDurationMs?: number;
+  readonly maxFailures?: number;
+};
+
+export type RotateJobResult = {
+  readonly migrated: number;
+  readonly failed: number;
+  readonly batchesProcessed: number;
+  readonly stoppedReason: "empty" | "timeout" | "signal" | "too_many_failures";
+};
+
+export const rotateJob: JobHandlerFn = async (rawPayload, ctx): Promise<void> => {
+  const payload = rawPayload as RotateJobPayload;
+  if (!ctx.masterKeyProvider) {
+    throw new InternalError({
+      message:
+        "[secrets:rotate] ctx.masterKeyProvider missing — wire it via extraContext.masterKeyProvider at boot.",
+    });
+  }
+  const provider = ctx.masterKeyProvider;
+  if (!ctx.db) {
+    throw new InternalError({
+      message: "[secrets:rotate] ctx.db missing — job context requires a database connection.",
+    });
+  }
+  const db = ctx.db as DbConnection;
+  const batchSize = payload.batchSize ?? DEFAULT_BATCH_SIZE;
+  const maxFailures = payload.maxFailures ?? DEFAULT_MAX_FAILURES;
+  const deadline = payload.maxDurationMs
+    ? Date.now() + payload.maxDurationMs
+    : Number.POSITIVE_INFINITY;
+
+  let migrated = 0;
+  let failed = 0;
+  let batchesProcessed = 0;
+  let stoppedReason: RotateJobResult["stoppedReason"] = "empty";
+
+  // Reuse a TenantDb-per-tenant map so we don't rebuild the wrapper for
+  // each row in the same tenant. Rotation typically hits one tenant in a
+  // batch; the map trims an allocation without adding complexity.
+  const tdbCache = new Map<TenantId, TenantDb>();
+  function tdbFor(tenantId: TenantId): TenantDb {
+    let existing = tdbCache.get(tenantId);
+    if (!existing) {
+      existing = createTenantDb(db, tenantId, "system");
+      tdbCache.set(tenantId, existing);
+    }
+    return existing;
+  }
+
+  while (true) {
+    if (ctx.signal?.aborted) {
+      stoppedReason = "signal";
+      break;
+    }
+    if (Date.now() >= deadline) {
+      stoppedReason = "timeout";
+      break;
+    }
+
+    const targetVersion = provider.currentVersion();
+    const batch = await db
+      .select({
+        id: tenantSecretsTable.id,
+        tenantId: tenantSecretsTable.tenantId,
+        version: tenantSecretsTable.version,
+        envelope: tenantSecretsTable.envelope,
+        kekVersion: tenantSecretsTable.kekVersion,
+      })
+      .from(tenantSecretsTable)
+      .where(ne(tenantSecretsTable.kekVersion, targetVersion))
+      .limit(batchSize);
+
+    if (batch.length === 0) break;
+
+    batchesProcessed++;
+
+    if (failed >= maxFailures) {
+      stoppedReason = "too_many_failures";
+      break;
+    }
+
+    for (const row of batch) {
+      if (failed >= maxFailures) {
+        stoppedReason = "too_many_failures";
+        break;
+      }
+      try {
+        const oldEnvelope = {
+          ciphertext: Buffer.from(row.envelope.ciphertext, "base64"),
+          iv: Buffer.from(row.envelope.iv, "base64"),
+          authTag: Buffer.from(row.envelope.authTag, "base64"),
+          encryptedDek: Buffer.from(row.envelope.encryptedDek, "base64"),
+          kekVersion: row.envelope.kekVersion,
+        };
+        const rotated = await rewrapDek(oldEnvelope, provider);
+
+        if (rotated.kekVersion === row.kekVersion) continue;
+
+        const newEnvelope: StoredEnvelope = {
+          ciphertext: rotated.ciphertext.toString("base64"),
+          iv: rotated.iv.toString("base64"),
+          authTag: rotated.authTag.toString("base64"),
+          encryptedDek: rotated.encryptedDek.toString("base64"),
+          kekVersion: rotated.kekVersion,
+        };
+
+        const actor: SessionUser = {
+          id: "system",
+          tenantId: row.tenantId as TenantId,
+          roles: SYSTEM_ROLES,
+        };
+
+        const result = await executor.update(
+          {
+            id: row.id,
+            version: row.version,
+            changes: {
+              envelope: newEnvelope,
+              kekVersion: rotated.kekVersion,
+            },
+          },
+          actor,
+          tdbFor(row.tenantId as TenantId),
+        );
+
+        // version_conflict == another writer (secrets.set or a parallel
+        // rotation worker) beat us. Count as "skipped" and move on — the
+        // row is already in a valid state, potentially even past target.
+        if (!result.isSuccess) {
+          if (result.error.code === "version_conflict") continue;
+          failed++;
+          ctx.log?.warn?.(`[secrets:rotate] executor rejected row ${row.id}`, {
+            code: result.error.code,
+          });
+          continue;
+        }
+      } catch (err) {
+        failed++;
+        ctx.log?.warn?.(`[secrets:rotate] failed to rotate row ${row.id}`, { err });
+        continue;
+      }
+      migrated++;
+    }
+
+    if (stoppedReason === "too_many_failures") break;
+    if (batch.length < batchSize) break;
+  }
+
+  const result: RotateJobResult = { migrated, failed, batchesProcessed, stoppedReason };
+  ctx.log?.info?.(`[secrets:rotate] complete: ${JSON.stringify(result)}`);
+};

package/src/secrets/handlers/set.write.ts

@@ -0,0 +1,50 @@
+import { defineWriteHandler } from "@cosmicdrift/kumiko-framework/engine";
+import { z } from "zod";
+import { requireSecretsContext } from "../feature";
+
+export const setWrite = defineWriteHandler({
+  name: "set",
+  schema: z.object({
+    key: z.string().min(1).max(100),
+    value: z.string(),
+    // Optional fixed-length preview — if the caller's UI wants a domain-
+    // specific redaction ("sk_live_abc…xyz") it can send it here; else the
+    // handler derives a generic one (first-3-chars + bullets).
+    redactedPreview: z.string().max(50).optional(),
+    hint: z.string().max(200).optional(),
+  }),
+  access: { roles: ["TenantAdmin"] },
+  handler: async (event, ctx) => {
+    const secrets = requireSecretsContext(ctx, "secrets:write:set");
+    const { key, value, redactedPreview, hint } = event.payload;
+
+    // Preview-priority: explicit payload param > feature-declared redact
+    // (via r.secret()) > generic default. A feature that declared a
+    // domain-aware redact (Stripe keys: "sk_test...2345") wins over the
+    // framework default unless the caller sent a specific preview.
+    const keyDef = ctx.registry.getSecretKey(key);
+    const featureRedact = keyDef?.redact;
+    const redactFn: (v: string) => string = redactedPreview
+      ? () => redactedPreview
+      : (featureRedact ?? defaultRedact);
+
+    await secrets.set(event.user.tenantId, key, value, {
+      redact: redactFn,
+      ...(hint ? { hint } : {}),
+      updatedBy: event.user.id,
+    });
+
+    return {
+      isSuccess: true,
+      data: { key, redactedPreview: redactedPreview ?? redactFn(value) },
+    };
+  },
+});
+
+// Fallback redaction: show at most the first 3 chars + trailing bullets.
+// Deliberately conservative — a too-generous preview defeats the point.
+function defaultRedact(value: string): string {
+  if (value.length === 0) return "";
+  const prefix = value.slice(0, Math.min(3, value.length));
+  return `${prefix}${"•".repeat(Math.max(1, value.length - 3))}`;
+}

package/src/secrets/index.ts

@@ -0,0 +1,16 @@
+export {
+  createSecretsContext,
+  createSecretsFeature,
+  requireSecretsContext,
+  type SecretsContext,
+  type SecretsContextOptions,
+  type StoredEnvelope,
+  type StoredMetadata,
+  TENANT_SECRET_READ_EVENT,
+  tenantSecretsTable,
+} from "./feature";
+export {
+  type RotateJobPayload,
+  type RotateJobResult,
+  rotateJob,
+} from "./handlers/rotate.job";

package/src/secrets/secrets-context.ts

@@ -0,0 +1,296 @@
+// Feature-level accessor injected as `ctx.secrets` at boot. Not a HTTP API —
+// feature code that needs a plaintext secret (SMTP-connect, Stripe-call, …)
+// pulls it via ctx.secrets.get. Cleartext never crosses the wire.
+//
+// Post-ES pivot: all three ops (get/set/delete) flow through the events-
+// table.
+//   - set → executor.create / .update on the tenantSecret aggregate
+//   - delete → executor.delete
+//   - get → low-level append of tenantSecretRead-event on a fresh
+//           aggregate-stream (one-event-per-read, so parallel reads never
+//           race on the secret's own version). The audit invariant ("every
+//           read logged") now sits on the events-table instead of a
+//           dedicated audit-table.
+
+import {
+  createEventStoreExecutor,
+  createTenantDb,
+  type DbConnection,
+  fetchOne,
+} from "@cosmicdrift/kumiko-framework/db";
+import type { SessionUser } from "@cosmicdrift/kumiko-framework/engine";
+import { InternalError, type WriteErrorInfo } from "@cosmicdrift/kumiko-framework/errors";
+import { append, type EventMetadata } from "@cosmicdrift/kumiko-framework/event-store";
+import {
+  createDekCache,
+  createSecret,
+  type DekCache,
+  decryptValue,
+  encryptValue,
+  type MasterKeyProvider,
+  type SecretsContext,
+} from "@cosmicdrift/kumiko-framework/secrets";
+import { generateId } from "@cosmicdrift/kumiko-framework/utils";
+import { and, eq } from "drizzle-orm";
+import { z } from "zod";
+import {
+  type StoredEnvelope,
+  type StoredMetadata,
+  tenantSecretEntity,
+  tenantSecretsTable,
+} from "./table";
+
+// Re-export the framework interface so consumers of bundled-features/secrets
+// don't need to reach into @cosmicdrift/kumiko-framework/secrets separately.
+export type { Secret, SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+
+export type SecretsContextOptions = {
+  readonly db: DbConnection;
+  readonly masterKeyProvider: MasterKeyProvider;
+  // Shared DEK cache. Default: a fresh 5-min TTL cache. Pass in a shared
+  // instance if several features decrypt overlapping secret sets — lowers
+  // provider-call count across the app.
+  readonly dekCache?: DekCache;
+};
+
+// Synthetic actor identity for set/delete — the executor wants a full
+// SessionUser, but the secrets-context API takes only a user-id string
+// (via opts.updatedBy / opts.deletedBy). `system`-role mirrors how jobs
+// and seeds attribute out-of-band writes: non-admin paths stay blocked,
+// framework-internal ops keep working.
+const SYSTEM_ROLES = ["system"] as const;
+
+// Secret-read audit-event type name + schema. Colocated here instead of
+// in secrets-feature.ts because the feature file imports the context
+// (via createSecretsContext), so schema-in-feature-file would cycle.
+// secrets-feature.ts re-exports `secretReadSchema` for r.defineEvent.
+export const TENANT_SECRET_READ_EVENT = "secrets:event:read";
+export const secretReadSchema = z.object({
+  key: z.string(),
+  userId: z.string(),
+  handlerName: z.string(),
+});
+
+const executor = createEventStoreExecutor(tenantSecretsTable, tenantSecretEntity, {
+  entityName: "tenant-secret",
+});
+
+function resolveKey(keyOrHandle: string | { readonly name: string }): string {
+  return typeof keyOrHandle === "string" ? keyOrHandle : keyOrHandle.name;
+}
+
+// Wrap a provider so its unwrapDek goes through the cache. Lets decryptValue
+// use the full provider contract without knowing about caching — separation
+// of concerns: decryptValue handles crypto, cache handles cost.
+function cachedProvider(provider: MasterKeyProvider, cache: DekCache): MasterKeyProvider {
+  return {
+    wrapDek: provider.wrapDek.bind(provider),
+    unwrapDek: (encryptedDek, version) => cache.unwrapDek(encryptedDek, version, provider),
+    currentVersion: provider.currentVersion.bind(provider),
+    isAvailable: provider.isAvailable.bind(provider),
+  };
+}
+
+function decodeEnvelope(stored: StoredEnvelope): {
+  ciphertext: Buffer;
+  iv: Buffer;
+  authTag: Buffer;
+  encryptedDek: Buffer;
+  kekVersion: number;
+} {
+  return {
+    ciphertext: Buffer.from(stored.ciphertext, "base64"),
+    iv: Buffer.from(stored.iv, "base64"),
+    authTag: Buffer.from(stored.authTag, "base64"),
+    encryptedDek: Buffer.from(stored.encryptedDek, "base64"),
+    kekVersion: stored.kekVersion,
+  };
+}
+
+export function createSecretsContext(opts: SecretsContextOptions): SecretsContext {
+  const { db, masterKeyProvider } = opts;
+  const provider = cachedProvider(masterKeyProvider, opts.dekCache ?? createDekCache());
+
+  type SecretLookupRow = {
+    readonly id: string;
+    readonly version: number;
+    readonly envelope: StoredEnvelope;
+  };
+
+  async function lookup(tenantId: string, key: string): Promise<SecretLookupRow | undefined> {
+    return fetchOne<SecretLookupRow>(
+      db,
+      tenantSecretsTable,
+      eq(tenantSecretsTable.tenantId, tenantId),
+      eq(tenantSecretsTable.key, key),
+    );
+  }
+
+  return {
+    async get(tenantId, keyOrHandle, auditCtx) {
+      const key = resolveKey(keyOrHandle);
+      // Atomic audit + read: a decrypt that "escaped" the audit trail
+      // (because the audit-append threw) would violate the compliance
+      // promise "every read is logged". Wrapping both in a TX means
+      // either the caller gets the plaintext AND a read-event row, or
+      // neither. Reads without audit (framework-internal, rotation job)
+      // skip the TX — there's nothing to couple.
+      if (!auditCtx) {
+        const existing = await lookup(tenantId, key);
+        if (!existing) return undefined;
+        const plaintext = await decryptValue(decodeEnvelope(existing.envelope), provider);
+        return createSecret(plaintext);
+      }
+
+      const plaintext = await db.transaction(async (tx) => {
+        // Inline select inside the TX — fetchOne's SelectChainDb shape
+        // doesn't widen to drizzle's tx-object cleanly. Structurally
+        // identical; the one-off repeat beats a double-cast at the
+        // call site.
+        const [row] = await tx
+          .select({ envelope: tenantSecretsTable.envelope })
+          .from(tenantSecretsTable)
+          .where(and(eq(tenantSecretsTable.tenantId, tenantId), eq(tenantSecretsTable.key, key)))
+          .limit(1);
+        if (!row) return undefined;
+        const envelope = row.envelope;
+        const pt = await decryptValue(decodeEnvelope(envelope), provider);
+
+        // One event per read on its own aggregate-stream (fresh UUID as
+        // aggregateId). Avoids version-conflicts between parallel reads —
+        // a shared stream on the tenantSecret-aggregate would force
+        // serialization and turn read-amplification into lock-amplification.
+        // MSP consumers still group by payload.key if they want per-secret
+        // read counts.
+        const readId = generateId();
+        const metadata: EventMetadata = { userId: auditCtx.userId };
+        // Parse against the registered schema so the low-level append
+        // here gets the same validation guarantee as ctx.appendEvent.
+        // A payload-shape drift between schema + call-site fails at the
+        // source instead of landing on the events-stream.
+        const payload = secretReadSchema.parse({
+          key,
+          userId: auditCtx.userId,
+          handlerName: auditCtx.handlerName,
+        });
+        await append(tx, {
+          aggregateId: readId,
+          aggregateType: "tenantSecretRead",
+          tenantId,
+          expectedVersion: 0,
+          type: TENANT_SECRET_READ_EVENT,
+          payload,
+          metadata,
+        });
+        return pt;
+      });
+
+      if (plaintext === undefined) return undefined;
+      // Brand the plaintext only after audit committed. The response
+      // serializer rejects any Secret<> it finds on the response path.
+      return createSecret(plaintext);
+    },
+
+    async set(tenantId, keyOrHandle, value, setOpts = {}) {
+      const key = resolveKey(keyOrHandle);
+      const envelope = await encryptValue(value, masterKeyProvider);
+      const stored: StoredEnvelope = {
+        ciphertext: envelope.ciphertext.toString("base64"),
+        iv: envelope.iv.toString("base64"),
+        authTag: envelope.authTag.toString("base64"),
+        encryptedDek: envelope.encryptedDek.toString("base64"),
+        kekVersion: envelope.kekVersion,
+      };
+      const metadata: StoredMetadata = {
+        ...(setOpts.redact ? { redactedPreview: setOpts.redact(value) } : {}),
+        ...(setOpts.hint ? { hint: setOpts.hint } : {}),
+      };
+
+      const actor: SessionUser = {
+        id: setOpts.updatedBy ?? "system",
+        tenantId,
+        roles: SYSTEM_ROLES,
+      };
+      const tdb = createTenantDb(db, tenantId, "system");
+
+      const existing = await lookup(tenantId, key);
+      const commonFields = {
+        envelope: stored,
+        kekVersion: envelope.kekVersion,
+        metadata,
+        lastRotatedAt: Temporal.Now.instant(),
+      };
+
+      if (existing) {
+        const result = await executor.update(
+          {
+            id: existing.id,
+            version: existing.version,
+            changes: commonFields,
+          },
+          actor,
+          tdb,
+        );
+        if (!result.isSuccess) throw wrapSetFailure(result.error);
+        // skip: update path done — don't fall through into the create branch below.
+        return;
+      }
+
+      try {
+        const result = await executor.create(
+          {
+            key,
+            tenantId,
+            ...commonFields,
+          },
+          actor,
+          tdb,
+        );
+        if (!result.isSuccess) throw wrapSetFailure(result.error);
+      } catch (err) {
+        // Race-fallback: a concurrent set won the insert. Re-lookup and
+        // convert to an update. The unique-index on (tenant, key) is what
+        // triggers this path.
+        const afterRace = await lookup(tenantId, key);
+        if (!afterRace) throw err;
+        const result = await executor.update(
+          {
+            id: afterRace.id,
+            version: afterRace.version,
+            changes: commonFields,
+          },
+          actor,
+          tdb,
+        );
+        if (!result.isSuccess) throw wrapSetFailure(result.error);
+      }
+    },
+
+    async delete(tenantId, keyOrHandle, deleteOpts = {}) {
+      const key = resolveKey(keyOrHandle);
+      const existing = await lookup(tenantId, key);
+      if (!existing) return false;
+
+      const actor: SessionUser = {
+        id: deleteOpts.deletedBy ?? "system",
+        tenantId,
+        roles: SYSTEM_ROLES,
+      };
+      const tdb = createTenantDb(db, tenantId, "system");
+      const result = await executor.delete({ id: existing.id }, actor, tdb);
+      return result.isSuccess;
+    },
+  };
+}
+
+// Wrap an executor-level write failure into a KumikoError so callers of
+// ctx.secrets.set / .delete can still branch on .code / details / i18nKey
+// after it propagates up. Plain `new Error(...)` would have stripped the
+// structured payload the error-contract promises.
+function wrapSetFailure(err: WriteErrorInfo): InternalError {
+  return new InternalError({
+    message: `[secrets.set] executor returned failure: ${err.code}`,
+    i18nKey: "secrets.errors.set_failed",
+    details: { executorCode: err.code, executorDetails: err.details ?? {} },
+  });
+}

package/src/secrets/table.ts

@@ -0,0 +1,68 @@
+import {
+  buildBaseColumns,
+  instant,
+  integer,
+  jsonb,
+  table,
+  text,
+  uniqueIndex,
+} from "@cosmicdrift/kumiko-framework/db";
+import {
+  createEntity,
+  createNumberField,
+  createTextField,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { sql } from "drizzle-orm";
+
+// Envelope stored as a single jsonb blob. All ops are upsert-by-(tenantId, key)
+// so there's no value in decomposing the envelope into separate columns —
+// we never query or index on any sub-field of the envelope itself.
+//
+// kekVersion IS broken out as its own column so the rotation job can filter
+// `WHERE kek_version != currentVersion()` with an index on just that column
+// without deserializing the jsonb. Duplicated inside envelope too — the two
+// always stay in sync via the write path.
+export type StoredEnvelope = {
+  readonly ciphertext: string; // base64
+  readonly iv: string; // base64
+  readonly authTag: string; // base64
+  readonly encryptedDek: string; // base64
+  readonly kekVersion: number;
+};
+
+export type StoredMetadata = {
+  readonly redactedPreview?: string;
+  readonly hint?: string;
+};
+
+// Entity registration for the ES pivot. Only `key` + `kekVersion` are
+// declared as business-validated fields; the jsonb columns (envelope,
+// metadata) and the instant column (lastRotatedAt) ride along as extra
+// table-columns. The executor writes whatever keys land in `flatData`
+// into both the projection row AND the event payload, so the whole
+// envelope round-trips through events.
+//
+// The envelope is cipher-safe by construction (AES-GCM ciphertext + authTag
+// + DEK encrypted under the KEK). A leaked event row can't recover the
+// plaintext without the master key — so shipping it into the events-table
+// doesn't weaken the threat model vs. the pre-ES tenant_secrets column.
+export const tenantSecretEntity = createEntity({
+  table: "read_tenant_secrets",
+  fields: {
+    key: createTextField({ required: true }),
+    kekVersion: createNumberField({ required: true }),
+  },
+});
+
+export const tenantSecretsTable = table(
+  "read_tenant_secrets",
+  {
+    ...buildBaseColumns(false, "uuid"),
+    key: text("key").notNull(),
+    envelope: jsonb("envelope").$type<StoredEnvelope>().notNull(),
+    kekVersion: integer("kek_version").notNull(),
+    metadata: jsonb("metadata").$type<StoredMetadata>().default({}).notNull(),
+    lastRotatedAt: instant("last_rotated_at").default(sql`now()`).notNull(),
+  },
+  (t) => [uniqueIndex("read_tenant_secrets_tenant_key_unique").on(t.tenantId, t.key)],
+);