@cosmicdrift/kumiko-samples 0.404.1 → 0.405.0

package/packages/bundled-features/src/personal-access-tokens/resolver.ts

@@ -4,6 +4,7 @@ import { fetchOne } from "@cosmicdrift/kumiko-framework/db";
 import type { SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { isExpiredAt } from "./expiry.ts";
 import { hashPatToken } from "./hash.ts";
+import { parseScopeNames } from "./parse-scope-names.ts";
 import { resolvePatRoles } from "./roles.ts";
 import { apiTokenTable } from "./schema/api-token.ts";
 import { expandScopes, type PatScopeConfig } from "./web/scopes.ts";
@@ -42,12 +43,3 @@ export function createPatResolver(opts: {
     };
   };
 }
-
-function parseScopeNames(raw: string): string[] {
-  try {
-    const parsed: unknown = JSON.parse(raw);
-    return Array.isArray(parsed) ? parsed.filter((s): s is string => typeof s === "string") : [];
-  } catch {
-    return [];
-  }
-}

package/packages/bundled-features/src/renderer-foundation/feature.ts

@@ -1,4 +1,5 @@
 import { defineFeature, type Registry } from "@cosmicdrift/kumiko-framework/engine";
+import { collectExtensionOptions } from "../shared/index.ts";
 import { RENDERER_EXTENSION } from "./constants.ts";
 import { isRendererRegistrationPlugin, type RendererPlugin } from "./types.ts";
 
@@ -22,13 +23,7 @@ export function createRendererFoundationFeature() {
     });
     r.requires({ features: ["template-resolver"] });
 
-    r.extendsRegistrar(RENDERER_EXTENSION, {
-      onRegister: () => {
-        // Plugin conformance check could go here: validate the shape of
-        // options (kinds, render function present). No shape check currently —
-        // the caller's TypeScript type safety applies.
-      },
-    });
+    r.extendsRegistrar(RENDERER_EXTENSION, {});
 
     return {};
   });
@@ -40,13 +35,5 @@ export function createRendererFoundationFeature() {
 //
 // Symmetric to collectChannels / collectRenderers in delivery-service.
 export function collectRendererPlugins(registry: Registry): RendererPlugin[] {
-  const usages = registry.getExtensionUsages(RENDERER_EXTENSION);
-  return usages.map((usage) => {
-    if (!isRendererRegistrationPlugin(usage.options)) {
-      throw new Error(
-        `${RENDERER_EXTENSION} registration for "${usage.entityName}" has invalid options`,
-      );
-    }
-    return { name: usage.entityName, ...usage.options };
-  });
+  return collectExtensionOptions(registry, RENDERER_EXTENSION, isRendererRegistrationPlugin);
 }

package/packages/bundled-features/src/secrets/handlers/rotate.job.ts

@@ -22,7 +22,6 @@ import {
   createTenantDb,
   type DbConnection,
   selectMany,
-  type TenantDb,
 } from "@cosmicdrift/kumiko-framework/db";
 import type { JobContext, SessionUser, TenantId } from "@cosmicdrift/kumiko-framework/engine";
 import { InternalError } from "@cosmicdrift/kumiko-framework/errors";
@@ -31,7 +30,11 @@ import {
   encodeStoredEnvelope,
   rewrapDek,
 } from "@cosmicdrift/kumiko-framework/secrets";
-import { type ChunkedMigrationStopReason, runChunkedMigration } from "../../shared/index.ts";
+import {
+  type ChunkedMigrationStopReason,
+  createTenantDbCache,
+  runChunkedMigration,
+} from "../../shared/index.ts";
 import { type StoredEnvelope, tenantSecretEntity, tenantSecretsTable } from "../table.ts";
 
 const DEFAULT_BATCH_SIZE = 100;
@@ -74,23 +77,14 @@ export async function rotateJob(
     ? Date.now() + payload.maxDurationMs
     : Number.POSITIVE_INFINITY;
 
-  // 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,
-        mode: "system",
-        reason: "secret key rotation job re-encrypts secrets of every tenant",
-      });
-      tdbCache.set(tenantId, existing);
-    }
-    return existing;
-  }
+  const tdbFor = createTenantDbCache((tenantId) =>
+    createTenantDb({
+      db,
+      tenantId,
+      mode: "system",
+      reason: "secret key rotation job re-encrypts secrets of every tenant",
+    }),
+  );
 
   type SecretRow = {
     id: string;

package/packages/bundled-features/src/shared/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.405.0",
+    "type": "improvement",
+    "title": "Bundled features share internal helpers",
+    "detail": "Access resolution for folders, ledger, notes-history and tags, the folders/tags write hook, the system-mode TenantDb cache of the re-encryption and rotation jobs, the mail locale templates of auth-email-password and user-data-rights, extension option collection for delivery and renderers, PAT scope parsing, user-data-rights hook DBs, unique-constraint failure checks, tenant member PII decryption, the status banner, the invite-accept request, the tenant label and the jobs subject parser each live in one internal module now. Empty onRegister callbacks are dropped. No behavior change."
+  },
   {
     "version": "0.364.0",
     "type": "improvement",

package/packages/bundled-features/src/shared/collect-extension-options.ts

@@ -0,0 +1,14 @@
+import type { Registry } from "@cosmicdrift/kumiko-framework/engine";
+
+export function collectExtensionOptions<TOptions extends object>(
+  registry: Registry,
+  extension: string,
+  isOptions: (candidate: unknown) => candidate is TOptions,
+): Array<{ name: string } & TOptions> {
+  return registry.getExtensionUsages(extension).map((usage) => {
+    if (!isOptions(usage.options)) {
+      throw new Error(`${extension} registration for "${usage.entityName}" has invalid options`);
+    }
+    return { name: usage.entityName, ...usage.options };
+  });
+}

package/packages/bundled-features/src/shared/hmac-signature.ts

@@ -0,0 +1,15 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+export function signHmacSha256Base64Url(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+export function hmacSignatureMatches(
+  expectedBase64Url: string,
+  providedBase64Url: string,
+): boolean {
+  const expectedBuf = Buffer.from(expectedBase64Url, "base64url");
+  const providedBuf = Buffer.from(providedBase64Url, "base64url");
+  // timingSafeEqual throws on a length mismatch, and the throw itself is a timing signal.
+  return expectedBuf.length === providedBuf.length && timingSafeEqual(expectedBuf, providedBuf);
+}

package/packages/bundled-features/src/shared/index.ts

@@ -15,13 +15,17 @@ export {
   classifyStoredEnvelope,
   type StoredEnvelopeClassification,
 } from "./classify-stored-envelope.ts";
+export { collectExtensionOptions } from "./collect-extension-options.ts";
 export { decryptStoredPii, decryptStoredUserEmail } from "./decrypt-stored-pii.ts";
 export { encryptForDirectWrite } from "./encrypt-for-direct-write.ts";
 export { entitiesOf } from "./entities-of.ts";
 export { isWithinGracePeriod } from "./grace-period.ts";
+export { hmacSignatureMatches, signHmacSha256Base64Url } from "./hmac-signature.ts";
 export { isIdentityV3Hash, verifyIdentityV3Hash } from "./identity-v3-hash.ts";
 export { isTenantDb } from "./is-tenant-db.ts";
+export { isUniqueConstraintFailure } from "./is-unique-constraint-failure.ts";
 export { createLockoutCounter, type LockoutCounterState } from "./lockout-counter.ts";
+export { createMailLocaleTemplates } from "./mail-locale-templates.ts";
 export {
   mailHeading,
   mailParagraph,
@@ -59,6 +63,7 @@ export {
 } from "./redact.ts";
 export { REDACTED_PII_PLACEHOLDER, redactPiiCiphertext } from "./redact-pii-ciphertext.ts";
 export { requireForTenant } from "./require-for-tenant.ts";
+export { resolveFeatureAccess } from "./resolve-feature-access.ts";
 export {
   extensionForResourceContentType,
   isResourceImageContentType,
@@ -108,4 +113,5 @@ export {
   stepFailures,
 } from "./stream-tenant-derived-state.ts";
 export type { SystemQueryFn } from "./system-query.ts";
+export { createTenantDbCache } from "./tenant-db-cache.ts";
 export { type BurnResult, burnToken, unburnToken } from "./token-burn-store.ts";

package/packages/bundled-features/src/shared/is-unique-constraint-failure.ts

@@ -0,0 +1,11 @@
+import type { WriteFailure } from "@cosmicdrift/kumiko-framework/errors";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+
+// The executor reports a unique-index race as a WriteFailure(unique_violation)
+// whose details name the violated constraint.
+export function isUniqueConstraintFailure(failure: WriteFailure, constraint: string): boolean {
+  return (
+    propertyOf(failure.error, "code") === "unique_violation" &&
+    propertyOf(propertyOf(failure.error, "details"), "constraintName") === constraint
+  );
+}

package/packages/bundled-features/src/shared/mail-locale-templates.ts

@@ -0,0 +1,64 @@
+import type { NotificationLocalizedTemplate } from "@cosmicdrift/kumiko-framework/engine";
+import {
+  hasMailTranslationKey,
+  listMailLocales,
+  mailT,
+  resolveMailLocale,
+} from "@cosmicdrift/kumiko-framework/i18n";
+
+type MailLocaleTemplateConfig<Kind extends string> = {
+  readonly kinds: readonly Kind[];
+  readonly notificationTypes: Readonly<Record<Kind, string>>;
+  readonly subjectKey: (kind: Kind) => string;
+  readonly bodyFor: (kind: Kind, locale: string) => string;
+};
+
+export function createMailLocaleTemplates<Kind extends string>(
+  config: MailLocaleTemplateConfig<Kind>,
+): {
+  templateLocale: (notificationType: string, requestedLocale: string) => string;
+  localizedTemplate: (kind: Kind) => () => NotificationLocalizedTemplate;
+} {
+  const subjectKeyByType: ReadonlyMap<string, string> = new Map(
+    config.kinds.map((kind) => [config.notificationTypes[kind], config.subjectKey(kind)]),
+  );
+
+  // A registered locale whose bundle lacks the subject key has no template (see
+  // localizedTemplate); the renderer has no locale fallback, so the sender must
+  // pick a locale that has one or the mail would not go out at all.
+  const templateLocale = (notificationType: string, requestedLocale: string): string => {
+    const locale = resolveMailLocale(requestedLocale);
+    const key = subjectKeyByType.get(notificationType);
+    return key !== undefined && hasMailTranslationKey(locale, key) ? locale : "en";
+  };
+
+  // Evaluated when the registry is built, after every locale feature has
+  // registered its mail translations. English always ships; another locale only
+  // gets a template when it has its own subject, so a missing translation never
+  // silently becomes an English mail in that locale's slot.
+  const localizedTemplate = (kind: Kind): (() => NotificationLocalizedTemplate) => {
+    const kindSubjectKey = config.subjectKey(kind);
+    return () => {
+      const locales = [
+        "en",
+        ...listMailLocales().filter(
+          (locale) => locale !== "en" && hasMailTranslationKey(locale, kindSubjectKey),
+        ),
+      ];
+      return Object.fromEntries(
+        locales.map((locale) => [
+          locale,
+          {
+            body: config.bodyFor(kind, locale),
+            meta: {
+              subject: mailT(locale, kindSubjectKey, { app: "{{appName}}" }),
+              category: "transactional" as const,
+            },
+          },
+        ]),
+      );
+    };
+  };
+
+  return { templateLocale, localizedTemplate };
+}

package/packages/bundled-features/src/shared/resolve-feature-access.ts

@@ -0,0 +1,16 @@
+import type { AccessRule } from "@cosmicdrift/kumiko-framework/engine";
+
+type FeatureAccessOptions = {
+  readonly access?: AccessRule;
+  readonly roles?: readonly string[];
+};
+
+// `access` wins over the `roles` shorthand; neither set falls back to the feature default.
+export function resolveFeatureAccess(
+  opts: FeatureAccessOptions,
+  defaultAccess: AccessRule,
+): AccessRule {
+  if (opts.access !== undefined) return opts.access;
+  if (opts.roles !== undefined) return { roles: opts.roles };
+  return defaultAccess;
+}

package/packages/bundled-features/src/shared/signed-token.ts

@@ -12,17 +12,13 @@
 // Timing-safe comparison on verify so a valid-length forgery can't leak
 // signal through a short-circuit.
 
-import { createHmac, timingSafeEqual } from "node:crypto";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { hmacSignatureMatches, signHmacSha256Base64Url } from "./hmac-signature.ts";
 
 export type VerifyResult =
   | { readonly ok: true; readonly userId: string; readonly expiresAtMs: number }
   | { readonly ok: false; readonly reason: "malformed" | "bad_signature" | "expired" };
 
-function sign(input: string, secret: string): string {
-  return createHmac("sha256", secret).update(input).digest("base64url");
-}
-
 function payload(purpose: string, userId: string, expiresAtMs: number): string {
   return `${purpose}:${userId}.${expiresAtMs}`;
 }
@@ -36,7 +32,7 @@ export function signToken(
 ): { token: string; expiresAt: Temporal.Instant } {
   const expiresAt = now.add({ minutes: ttlMinutes });
   const expiresAtMs = expiresAt.epochMilliseconds;
-  const signature = sign(payload(purpose, userId, expiresAtMs), secret);
+  const signature = signHmacSha256Base64Url(payload(purpose, userId, expiresAtMs), secret);
   return {
     token: `${userId}.${expiresAtMs}.${signature}`,
     expiresAt,
@@ -74,14 +70,8 @@ export function verifyToken(
     return { ok: false, reason: "malformed" };
   }
 
-  const expected = sign(payload(purpose, userId, expiresAtMs), secret);
-  const expectedBuf = Buffer.from(expected, "base64url");
-  const providedBuf = Buffer.from(providedSig, "base64url");
-  // Length mismatch fails BEFORE timingSafeEqual, which throws on different
-  // lengths — but that throw itself leaks via timing. Explicit length check
-  // keeps the path uniform.
-  if (expectedBuf.length !== providedBuf.length) return { ok: false, reason: "bad_signature" };
-  if (!timingSafeEqual(expectedBuf, providedBuf)) return { ok: false, reason: "bad_signature" };
+  const expected = signHmacSha256Base64Url(payload(purpose, userId, expiresAtMs), secret);
+  if (!hmacSignatureMatches(expected, providedSig)) return { ok: false, reason: "bad_signature" };
 
   if (Temporal.Instant.compare(now, Temporal.Instant.fromEpochMilliseconds(expiresAtMs)) > 0) {
     return { ok: false, reason: "expired" };

package/packages/bundled-features/src/shared/single-use-token-store.ts

@@ -38,14 +38,14 @@
 // permanently tax Redis, long enough to catch replays inside any realistic
 // race window).
 
-import { createHash } from "node:crypto";
+import { hashOpaqueTokenSync } from "@cosmicdrift/kumiko-framework/crypto";
 import type { Redis } from "ioredis";
 
 // Exported so a caller that needs a byte-compatible key in a sibling Redis
 // namespace (e.g. a token↔binding side-mapping) can derive it without
 // re-implementing sha256-of-token — see auth-email-password/signup-token-store.ts.
 export function hashSingleUseToken(token: string): string {
-  return createHash("sha256").update(token).digest("hex");
+  return hashOpaqueTokenSync(token);
 }
 
 export function createSingleUseTokenStore(prefixes: {

package/packages/bundled-features/src/shared/stream-tenant-derived-state.ts

@@ -5,7 +5,11 @@
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import { type Registry, SYSTEM_TENANT_ID } from "@cosmicdrift/kumiko-framework/engine";
 import { rebuildProjection } from "@cosmicdrift/kumiko-framework/pipeline";
-import { reindexEntity, type SearchAdapter } from "@cosmicdrift/kumiko-framework/search";
+import {
+  isEntitySearchable,
+  reindexEntity,
+  type SearchAdapter,
+} from "@cosmicdrift/kumiko-framework/search";
 import type { StreamBackfillCandidate, StreamBackfillFailure } from "./stream-tenant-backfill.ts";
 
 export type StreamBackfillStepFailure = StreamBackfillFailure & { readonly step: string };
@@ -88,13 +92,6 @@ export async function rebuildAndReindex(deps: {
   return { projectionsRebuilt, reindexedRows, failures };
 }
 
-function isEntitySearchable(registry: Registry, entityName: string): boolean {
-  return (
-    registry.getSearchableFields(entityName).length > 0 ||
-    registry.getSearchPayloadExtensions(entityName).length > 0
-  );
-}
-
 export function stepFailures(
   step: string,
   failed: readonly StreamBackfillFailure[],

package/packages/bundled-features/src/shared/tenant-db-cache.ts

@@ -0,0 +1,19 @@
+import type { TenantDb } from "@cosmicdrift/kumiko-framework/db";
+import type { TenantId } from "@cosmicdrift/kumiko-framework/engine";
+
+// One TenantDb per tenant, so a job touching many rows of the same tenant does
+// not rebuild the wrapper per row. The caller builds the TenantDb itself, so
+// its createTenantDb call keeps the literal system-mode reason the guard needs.
+export function createTenantDbCache(
+  create: (tenantId: TenantId) => TenantDb,
+): (tenantId: TenantId) => TenantDb {
+  const cache = new Map<TenantId, TenantDb>();
+  return (tenantId) => {
+    let existing = cache.get(tenantId);
+    if (!existing) {
+      existing = create(tenantId);
+      cache.set(tenantId, existing);
+    }
+    return existing;
+  };
+}

package/packages/bundled-features/src/shared/web/status-banner.tsx

@@ -0,0 +1,20 @@
+import { usePrimitives, useTranslation } from "@cosmicdrift/kumiko-renderer";
+import type { ReactNode } from "react";
+
+export type SectionStatus =
+  | { kind: "idle" }
+  | { kind: "submitting" }
+  | { kind: "success"; messageKey: string }
+  | { kind: "error"; messageKey: string };
+
+export function StatusBanner({ status }: { readonly status: SectionStatus }): ReactNode {
+  const t = useTranslation();
+  const { Banner } = usePrimitives();
+  if (status.kind === "success") {
+    return <Banner variant="info">{t(status.messageKey)}</Banner>;
+  }
+  if (status.kind === "error") {
+    return <Banner variant="error">{t(status.messageKey)}</Banner>;
+  }
+  return null;
+}

package/packages/bundled-features/src/shared/web/use-dispatched-writes.ts

@@ -0,0 +1,31 @@
+import { useDispatcher } from "@cosmicdrift/kumiko-renderer";
+import { useState } from "react";
+
+// Busy flag + error key shared by the folders/tags management surfaces: every
+// write goes through the dispatcher and a failed one surfaces its i18n key.
+export function useDispatchedWrites(onWriteSucceeded?: () => Promise<void> | void) {
+  const dispatcher = useDispatcher();
+  const [busy, setBusy] = useState(false);
+  const [errorKey, setErrorKey] = useState<string | null>(null);
+
+  const writeOk = async (type: string, payload: Record<string, unknown>): Promise<boolean> => {
+    const result = await dispatcher.write(type, payload);
+    if (!result.isSuccess) {
+      setErrorKey(result.error.i18nKey);
+      return false;
+    }
+    return true;
+  };
+
+  const apply = async (write: () => Promise<boolean>): Promise<void> => {
+    setBusy(true);
+    setErrorKey(null);
+    try {
+      if (await write()) await onWriteSucceeded?.();
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return { busy, setBusy, errorKey, setErrorKey, writeOk, apply };
+}

package/packages/bundled-features/src/subscription-paddle/feature.ts

@@ -6,7 +6,10 @@
 // subscription-stripe. The `apiKey` / `webhookSecret` / `tenantBindingKey` /
 // `clientToken` options are env→config bridge fallbacks.
 
-import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import {
+  type SubscriptionProviderPlugin,
+  validateOneOffPriceIds,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import {
   access,
   createSystemConfig,
@@ -122,25 +125,10 @@ export type SubscriptionPaddleOptions = {
   readonly nowSeconds?: () => number;
 };
 
-// Validated once at feature-build time so a typo fails app startup instead of
-// silently widening or narrowing the one-off allowlist at request time.
-function validateOneOffPriceIds(priceIds: readonly string[]): void {
-  const seen = new Set<string>();
-  for (const priceId of priceIds) {
-    if (priceId.length === 0) {
-      throw new Error("subscription-paddle: oneOffPriceIds must not contain an empty string");
-    }
-    if (seen.has(priceId)) {
-      throw new Error(`subscription-paddle: duplicate oneOffPriceIds entry "${priceId}"`);
-    }
-    seen.add(priceId);
-  }
-}
-
 export function createSubscriptionPaddleFeature(
   options: SubscriptionPaddleOptions = {},
 ): FeatureWithEnvSchema<FeatureDefinition, typeof subscriptionPaddleEnvSchema.shape> {
-  validateOneOffPriceIds(options.oneOffPriceIds ?? []);
+  validateOneOffPriceIds("subscription-paddle", options.oneOffPriceIds ?? []);
   const now = options.now ?? (() => Temporal.Now.instant().epochMilliseconds);
   const feature: FeatureDefinition = defineFeature(SUBSCRIPTION_PADDLE_FEATURE, (r) => {
     r.describe(

package/packages/bundled-features/src/subscription-paddle/price-methods.ts

@@ -2,10 +2,13 @@
 // cache misses, cached per price id.
 
 import {
+  createTtlPriceCache,
   KNOWN_RECURRING_INTERVALS,
   type ProviderPrice,
+  type TtlPriceCache,
 } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import type { HandlerContext } from "@cosmicdrift/kumiko-framework/engine";
+import { chunk } from "@cosmicdrift/kumiko-framework/utils";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import * as z from "zod";
 import type { PaddleCtxRuntime, PaddlePluginMethod } from "./runtime.ts";
@@ -61,10 +64,7 @@ function mapPaddlePrice(price: PaddlePrice): ProviderPrice {
   return { ...base, interval, intervalCount: interval ? cycle.frequency : null };
 }
 
-export type PaddlePriceCache = {
-  readonly get: (priceId: string) => ProviderPrice | undefined;
-  readonly set: (priceId: string, price: ProviderPrice) => void;
-};
+export type PaddlePriceCache = TtlPriceCache<ProviderPrice>;
 
 export type PaddlePriceCacheOptions = {
   readonly ttlMs?: number;
@@ -75,32 +75,10 @@ export type PaddlePriceCacheOptions = {
 // trigger an audited secret read on every billing-plans render. Failed lookups
 // are never cached.
 export function createPaddlePriceCache({
-  ttlMs = 600_000,
+  ttlMs,
   now = () => Temporal.Now.instant().epochMilliseconds,
 }: PaddlePriceCacheOptions = {}): PaddlePriceCache {
-  const store = new Map<string, { readonly price: ProviderPrice; readonly expiresAt: number }>();
-  return {
-    get: (priceId) => {
-      const entry = store.get(priceId);
-      if (!entry) return undefined;
-      if (entry.expiresAt <= now()) {
-        store.delete(priceId);
-        return undefined;
-      }
-      return entry.price;
-    },
-    set: (priceId, price) => {
-      store.set(priceId, { price, expiresAt: now() + ttlMs });
-    },
-  };
-}
-
-function chunked<T>(items: readonly T[], size: number): T[][] {
-  const chunks: T[][] = [];
-  for (let start = 0; start < items.length; start += size) {
-    chunks.push(items.slice(start, start + size));
-  }
-  return chunks;
+  return createTtlPriceCache<ProviderPrice>({ ttlMs, now });
 }
 
 async function fillPriceCache(
@@ -111,7 +89,7 @@ async function fillPriceCache(
 ): Promise<void> {
   const misses = [...new Set(priceIds.filter((priceId) => cache.get(priceId) === undefined))];
   const settled = await Promise.allSettled(
-    chunked(misses, PRICES_PER_REQUEST).map(async (ids) =>
+    chunk(misses, PRICES_PER_REQUEST).map(async (ids) =>
       pricesResponseSchema.parse(
         await runtime.call(ctx, {
           method: "GET",

package/packages/bundled-features/src/subscription-paddle/runtime.ts

@@ -7,7 +7,10 @@
 // HandlerContext; the pre-tenant webhook reads secrets un-audited from the
 // system SecretsContext the foundation passes in.
 
-import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import {
+  parseStoredSecret,
+  type SubscriptionProviderPlugin,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
 import {
   type ConfigKeyHandle,
@@ -16,7 +19,6 @@ import {
 } from "@cosmicdrift/kumiko-framework/engine";
 import { FeatureDisabledError, UnconfiguredError } from "@cosmicdrift/kumiko-framework/errors";
 import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
-import { parseJsonSafe } from "@cosmicdrift/kumiko-framework/utils";
 import { createPaddleHttp, type PaddleRequest, type PaddleSend } from "./client.ts";
 import {
   PADDLE_BASE_URLS,
@@ -47,19 +49,6 @@ export type PaddleRuntimeDeps = {
   readonly fallback: PaddleFallbacks;
 };
 
-// backing:"secrets" values are stored JSON-serialized, so the store read has to
-// be parsed back; the env fallback is a plain string and stays raw. The error
-// must not carry the input: the JSON parser's own message would repeat the
-// credential into logs and, for webhooks, into the 401 body.
-function parseStoredSecret(raw: string | undefined): string | undefined {
-  if (raw === undefined || raw.length === 0) return undefined;
-  const parsed = parseJsonSafe<unknown>(raw, undefined);
-  if (parsed === undefined) {
-    throw new Error("subscription-paddle credential (backing:secrets) is not valid JSON");
-  }
-  return typeof parsed === "string" && parsed.length > 0 ? parsed : undefined;
-}
-
 function hintFor(shortName: string): string {
   return `Set it via config:write:set on \`${SUBSCRIPTION_PADDLE_FEATURE}:config:${shortName}\` (or seed it from the matching PADDLE_* variable during the env bridge).`;
 }
@@ -108,7 +97,7 @@ export function createPaddleRuntimes(deps: PaddleRuntimeDeps): PaddleRuntimes {
         { secrets: ctx.services.secrets, user: ctx.user },
         SUBSCRIPTION_PADDLE_FEATURE,
       ).get(SYSTEM_TENANT_ID, handle.name);
-      value = parseStoredSecret(got?.reveal());
+      value = parseStoredSecret("subscription-paddle", got?.reveal());
     }
     if (!value && fallback && fallback.length > 0) value = fallback;
     if (!value) {
@@ -129,7 +118,7 @@ export function createPaddleRuntimes(deps: PaddleRuntimeDeps): PaddleRuntimes {
     if (systemSecrets) {
       // No auditCtx: every webhook would otherwise spam the audit trail.
       const got = await systemSecrets.get(SYSTEM_TENANT_ID, handle.name);
-      const stored = parseStoredSecret(got?.reveal());
+      const stored = parseStoredSecret("subscription-paddle", got?.reveal());
       if (stored) return stored;
     }
     if (fallback && fallback.length > 0) return fallback;

package/packages/bundled-features/src/subscription-stripe/feature.ts

@@ -32,7 +32,10 @@
 // api key + webhook secret without auditing (a sanctioned framework-internal
 // read).
 
-import type { SubscriptionProviderPlugin } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import {
+  type SubscriptionProviderPlugin,
+  validateOneOffPriceIds,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
 import {
   access,
   createSystemConfig,
@@ -144,23 +147,6 @@ export type SubscriptionStripeOptions = {
   readonly oneOffPriceIds?: readonly string[];
 };
 
-// Validated once at feature-build time (not per-request) so a config typo
-// (a pasted-twice priceId, a blank string from a bad env-join) fails app
-// startup instead of silently widening — or narrowing — the one-off
-// allowlist at request time. Mirrors legal-pages' validateRoutes.
-function validateOneOffPriceIds(priceIds: readonly string[]): void {
-  const seen = new Set<string>();
-  for (const priceId of priceIds) {
-    if (priceId.length === 0) {
-      throw new Error("subscription-stripe: oneOffPriceIds must not contain an empty string");
-    }
-    if (seen.has(priceId)) {
-      throw new Error(`subscription-stripe: duplicate oneOffPriceIds entry "${priceId}"`);
-    }
-    seen.add(priceId);
-  }
-}
-
 /**
  * Factory for the subscription-stripe feature. Always mounts (no
  * key-presence guard) — activity is gated at runtime through config/secrets
@@ -171,7 +157,7 @@ function validateOneOffPriceIds(priceIds: readonly string[]): void {
 export function createSubscriptionStripeFeature(
   options: SubscriptionStripeOptions = {},
 ): FeatureWithEnvSchema<FeatureDefinition, typeof subscriptionStripeEnvSchema.shape> {
-  validateOneOffPriceIds(options.oneOffPriceIds ?? []);
+  validateOneOffPriceIds("subscription-stripe", options.oneOffPriceIds ?? []);
   const feature: FeatureDefinition = defineFeature(SUBSCRIPTION_STRIPE_FEATURE, (r) => {
     r.describe(
       'Stripe payment provider plugin for `billing-foundation`. Reads its Stripe API key + webhook secret from system config keys with `backing:"secrets"` (envelope-encrypted in the secrets store under the system tenant) and a `billingLive` **system config** flag — all at runtime, so keys rotate and prod goes live without a redeploy. The `mask` on each key derives the sysadmin settings screen + nav, so no app wires a hand-written config UI. Mount via `createSubscriptionStripeFeature({ priceToTier })`; the optional `apiKey`/`webhookSecret` options are env→secrets bridge fallbacks. The plugin always mounts — `createCheckoutSession` throws `feature_disabled` unless `billingLive` is true, so sk_test_ keys in prod never produce a live checkout. Implements webhook verify, checkout, portal, cancel, `retrievePrices` (10-minute TTL-cached price lookup for the billing-plans catalog), `createPlanSwitchSession` (auto-provisions a Customer-Portal configuration for switching an existing subscription to another plan tier — each tier needs its own Stripe product), `retrieveSubscription` (live provider-side snapshot for the `sync-subscriptions` backfill job, mapped identically to the webhook path), plus `isBillingEnabled` (billingLive + an api-key existence probe, no secret read).',