@cosmicdrift/kumiko-samples 0.393.0 → 0.395.0

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

@@ -0,0 +1,203 @@
+// Call-time key/flag resolution for the subscription-paddle plugin, mirroring
+// subscription-stripe/runtime.ts: credentials come from backing:"secrets" config
+// keys under SYSTEM_TENANT_ID, so rotation and go-live need no redeploy.
+// The factory options survive as env-bridge fallbacks.
+//
+// Two read paths: post-tenant handlers read the key audited through the
+// 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 { requireSecretsContext } from "@cosmicdrift/kumiko-bundled-features/secrets";
+import {
+  type ConfigKeyHandle,
+  type HandlerContext,
+  SYSTEM_TENANT_ID,
+} 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,
+  type PaddleEnvironment,
+  PaddleEnvironments,
+  SUBSCRIPTION_PADDLE_FEATURE,
+} from "./constants.ts";
+
+export type PaddlePluginMethod<TName extends keyof SubscriptionProviderPlugin> = NonNullable<
+  SubscriptionProviderPlugin[TName]
+>;
+
+export type PaddleFallbacks = {
+  readonly apiKey?: string;
+  readonly webhookSecret?: string;
+  readonly tenantBindingKey?: string;
+  readonly clientToken?: string;
+};
+
+export type PaddleRuntimeDeps = {
+  readonly apiKeyHandle: ConfigKeyHandle<"text">;
+  readonly webhookSecretHandle: ConfigKeyHandle<"text">;
+  readonly tenantBindingKeyHandle: ConfigKeyHandle<"text">;
+  readonly clientTokenHandle: ConfigKeyHandle<"text">;
+  readonly billingLiveHandle: ConfigKeyHandle<"boolean">;
+  readonly environmentHandle: ConfigKeyHandle<"select">;
+  readonly send: PaddleSend;
+  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).`;
+}
+
+export type PaddleCtxRuntime = {
+  readonly call: (ctx: HandlerContext, request: PaddleRequest) => Promise<unknown>;
+  readonly assertBillingLive: (ctx: HandlerContext, handlerName?: string) => Promise<void>;
+  readonly isBillingEnabled: (ctx: HandlerContext) => Promise<boolean>;
+  readonly tenantBindingKey: (ctx: HandlerContext) => Promise<string>;
+};
+
+export type PaddleWebhookRuntime = {
+  readonly resolveWebhookSecret: (systemSecrets?: SecretsContext) => Promise<string>;
+  readonly resolveTenantBindingKey: (systemSecrets?: SecretsContext) => Promise<string>;
+};
+
+export type PaddleCheckoutConfig = {
+  readonly clientToken: string | null;
+  readonly environment: PaddleEnvironment;
+};
+
+export type PaddleRuntimes = {
+  readonly ctx: PaddleCtxRuntime;
+  readonly webhook: PaddleWebhookRuntime;
+  readonly readCheckoutConfig: (
+    ctx: Pick<HandlerContext, "config">,
+  ) => Promise<PaddleCheckoutConfig>;
+};
+
+function environmentOf(value: string | undefined): PaddleEnvironment {
+  return value === PaddleEnvironments.live ? PaddleEnvironments.live : PaddleEnvironments.sandbox;
+}
+
+export function createPaddleRuntimes(deps: PaddleRuntimeDeps): PaddleRuntimes {
+  const http = createPaddleHttp(deps.send);
+
+  async function ctxSecret(
+    ctx: HandlerContext,
+    handle: ConfigKeyHandle<"text">,
+    fallback: string | undefined,
+    shortName: string,
+  ): Promise<string> {
+    let value: string | undefined;
+    if (ctx.services.secrets) {
+      const got = await requireSecretsContext(
+        { secrets: ctx.services.secrets, user: ctx.user },
+        SUBSCRIPTION_PADDLE_FEATURE,
+      ).get(SYSTEM_TENANT_ID, handle.name);
+      value = parseStoredSecret(got?.reveal());
+    }
+    if (!value && fallback && fallback.length > 0) value = fallback;
+    if (!value) {
+      throw new UnconfiguredError({
+        feature: SUBSCRIPTION_PADDLE_FEATURE,
+        key: handle.name,
+        hint: hintFor(shortName),
+      });
+    }
+    return value;
+  }
+
+  async function webhookSecret(
+    systemSecrets: SecretsContext | undefined,
+    handle: ConfigKeyHandle<"text">,
+    fallback: string | undefined,
+  ): Promise<string> {
+    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());
+      if (stored) return stored;
+    }
+    if (fallback && fallback.length > 0) return fallback;
+    throw new Error(
+      `subscription-paddle: '${handle.name}' unresolved — no system-secret set and no factory fallback. Webhook cannot verify until it is configured.`,
+    );
+  }
+
+  async function hasSecret(
+    ctx: HandlerContext,
+    handle: ConfigKeyHandle<"text">,
+    fallback: string | undefined,
+  ): Promise<boolean> {
+    if (fallback !== undefined && fallback.length > 0) return true;
+    // Existence-only probe on every billing-plans render: must stay un-audited.
+    return ctx.services.secrets
+      ? await ctx.services.secrets.has(SYSTEM_TENANT_ID, handle.name)
+      : false;
+  }
+
+  async function baseUrlFor(ctx: HandlerContext): Promise<string> {
+    const environment = ctx.config ? await ctx.config(deps.environmentHandle) : undefined;
+    return PADDLE_BASE_URLS[environmentOf(environment)];
+  }
+
+  return {
+    ctx: {
+      call: async (ctx, request) =>
+        http(
+          {
+            baseUrl: await baseUrlFor(ctx),
+            apiKey: await ctxSecret(ctx, deps.apiKeyHandle, deps.fallback.apiKey, "api-key"),
+          },
+          request,
+        ),
+      assertBillingLive: async (ctx, handlerName = "create-checkout-session") => {
+        const live = ctx.config ? await ctx.config(deps.billingLiveHandle) : undefined;
+        if (live !== true) {
+          throw new FeatureDisabledError(SUBSCRIPTION_PADDLE_FEATURE, handlerName);
+        }
+      },
+      isBillingEnabled: async (ctx) => {
+        const live = ctx.config ? await ctx.config(deps.billingLiveHandle) : undefined;
+        if (live !== true) return false;
+        return (
+          (await hasSecret(ctx, deps.apiKeyHandle, deps.fallback.apiKey)) &&
+          (await hasSecret(ctx, deps.tenantBindingKeyHandle, deps.fallback.tenantBindingKey))
+        );
+      },
+      tenantBindingKey: (ctx) =>
+        ctxSecret(
+          ctx,
+          deps.tenantBindingKeyHandle,
+          deps.fallback.tenantBindingKey,
+          "tenant-binding-key",
+        ),
+    },
+    webhook: {
+      resolveWebhookSecret: (systemSecrets) =>
+        webhookSecret(systemSecrets, deps.webhookSecretHandle, deps.fallback.webhookSecret),
+      resolveTenantBindingKey: (systemSecrets) =>
+        webhookSecret(systemSecrets, deps.tenantBindingKeyHandle, deps.fallback.tenantBindingKey),
+    },
+    readCheckoutConfig: async (ctx) => {
+      const stored = ctx.config ? await ctx.config(deps.clientTokenHandle) : undefined;
+      const environment = ctx.config ? await ctx.config(deps.environmentHandle) : undefined;
+      const clientToken = stored || deps.fallback.clientToken || null;
+      return { clientToken, environment: environmentOf(environment) };
+    },
+  };
+}

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

@@ -0,0 +1,73 @@
+// Paddle's subscription entity and its mapping onto the foundation's state.
+// Shared by the webhook and retrieveSubscription so both map identically.
+
+import {
+  type SubscriptionStatus,
+  SubscriptionStatuses,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import * as z from "zod";
+
+const PADDLE_SUBSCRIPTION_STATUSES: Readonly<Record<string, SubscriptionStatus>> = {
+  active: SubscriptionStatuses.active,
+  trialing: SubscriptionStatuses.trialing,
+  past_due: SubscriptionStatuses.pastDue,
+  paused: SubscriptionStatuses.pastDue,
+  canceled: SubscriptionStatuses.canceled,
+};
+
+const SCHEDULED_CANCEL_ACTION = "cancel";
+
+const instantSchema = z.iso.datetime({ offset: true });
+
+export const paddleCustomDataSchema = z.record(z.string(), z.unknown()).nullish();
+
+export const paddleSubscriptionSchema = z.object({
+  id: z.string().min(1),
+  status: z.string(),
+  customer_id: z.string().min(1),
+  items: z.array(
+    z.object({
+      price: z.object({ id: z.string().min(1) }),
+      quantity: z.number().int().positive().optional(),
+    }),
+  ),
+  custom_data: paddleCustomDataSchema,
+  current_billing_period: z.object({ ends_at: instantSchema }).nullish(),
+  next_billed_at: instantSchema.nullish(),
+  scheduled_change: z.object({ action: z.string(), effective_at: instantSchema }).nullish(),
+  canceled_at: instantSchema.nullish(),
+});
+export type PaddleSubscription = z.infer<typeof paddleSubscriptionSchema>;
+
+export type MappedPaddleSubscriptionState = {
+  readonly status: SubscriptionStatus;
+  readonly tier: string;
+  readonly currentPeriodEnd: string;
+  readonly cancelAt: string | null;
+};
+
+/** Null when the status is unknown, no item's price is in `priceToTier`
+ *  (SubscriptionEvent.tier is required) or no period end can be derived. */
+export function mapPaddleSubscriptionState(
+  sub: PaddleSubscription,
+  priceToTier: Readonly<Record<string, string>>,
+): MappedPaddleSubscriptionState | null {
+  const status = Object.hasOwn(PADDLE_SUBSCRIPTION_STATUSES, sub.status)
+    ? PADDLE_SUBSCRIPTION_STATUSES[sub.status]
+    : undefined;
+  const tier = sub.items
+    .map((item) =>
+      Object.hasOwn(priceToTier, item.price.id) ? priceToTier[item.price.id] : undefined,
+    )
+    .find((name) => name);
+  const currentPeriodEnd =
+    sub.current_billing_period?.ends_at ?? sub.next_billed_at ?? sub.canceled_at;
+  if (!status || !tier || !currentPeriodEnd) return null;
+  const scheduled = sub.scheduled_change;
+  return {
+    status,
+    tier,
+    currentPeriodEnd,
+    cancelAt: scheduled?.action === SCHEDULED_CANCEL_ACTION ? scheduled.effective_at : null,
+  };
+}

package/packages/bundled-features/src/subscription-paddle/tenant-binding.ts

@@ -0,0 +1,34 @@
+// Paddle.js runs with a public client token and can open checkouts with any
+// `customData` from the browser, so `custom_data.tenantId` alone proves nothing.
+// The binding is an HMAC only the server can produce: webhooks whose tenantId
+// does not carry a valid binding are ignored.
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { parseProviderConsentId } from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+
+const BINDING_CONTEXT = "kumiko-paddle-tenant:v1:";
+
+export function signTenantBinding(key: string, tenantId: string): string {
+  return createHmac("sha256", key).update(`${BINDING_CONTEXT}${tenantId}`).digest("base64url");
+}
+
+export function isValidTenantBinding(key: string, tenantId: string, binding: string): boolean {
+  const expected = Buffer.from(signTenantBinding(key, tenantId));
+  const candidate = Buffer.from(binding);
+  return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+}
+
+export type BoundTenant = { readonly tenantId: string; readonly consentId?: string };
+
+/** Null unless `customData` names a tenant together with a binding that `key` signed. */
+export function boundTenantOf(
+  customData: Readonly<Record<string, unknown>> | null | undefined,
+  key: string,
+): BoundTenant | null {
+  const tenantId = customData?.["tenantId"];
+  const binding = customData?.["tenantBinding"];
+  if (typeof tenantId !== "string" || tenantId.length === 0) return null;
+  if (typeof binding !== "string" || !isValidTenantBinding(key, tenantId, binding)) return null;
+  const consentId = parseProviderConsentId(customData?.["consentId"]);
+  return { tenantId, ...(consentId !== undefined && { consentId }) };
+}

package/packages/bundled-features/src/subscription-paddle/verify-webhook.ts

@@ -0,0 +1,61 @@
+// Paddle webhook signature check: `Paddle-Signature: ts=<unix>;h1=<hex>[;h1=<hex>]`,
+// HMAC-SHA256 over `${ts}:${rawBody}` keyed with the raw secret string.
+//
+// Verification always runs against the raw body string; re-serialized JSON
+// would change whitespace and break the HMAC. It happens before any parsing,
+// so no path bypasses it.
+
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+// Paddle's own SDK accepts 5 s. 300 s matches Stripe here: the foundation
+// de-duplicates by event_id and pod clocks drift.
+export const PADDLE_WEBHOOK_TOLERANCE_SECONDS = 300;
+
+const SIGNATURE_HEADER = "paddle-signature";
+const TIMESTAMP_PATTERN = /^\d+$/;
+const SHA256_HEX_PATTERN = /^[0-9a-f]{64}$/i;
+
+type ParsedSignatureHeader = { readonly timestamp: string; readonly signatures: readonly string[] };
+
+function parseSignatureHeader(header: string): ParsedSignatureHeader | null {
+  let timestamp: string | undefined;
+  const signatures: string[] = [];
+  for (const part of header.split(";")) {
+    const separator = part.indexOf("=");
+    if (separator < 0) continue;
+    const name = part.slice(0, separator).trim();
+    const value = part.slice(separator + 1).trim();
+    if (name === "ts") timestamp = value;
+    else if (name === "h1") signatures.push(value);
+  }
+  return timestamp === undefined ? null : { timestamp, signatures };
+}
+
+/** Throws unless one `h1` signature over `rawBody` is valid and the timestamp is
+ *  within the tolerance in both directions. Header names must be lower-case. */
+export function verifyPaddleSignature(
+  rawBody: string,
+  headers: Readonly<Record<string, string>>,
+  secret: string,
+  nowSeconds: number,
+): void {
+  const header = headers[SIGNATURE_HEADER];
+  if (!header) throw new Error("subscription-paddle: paddle-signature header missing");
+  const parsed = parseSignatureHeader(header);
+  if (!parsed || parsed.signatures.length === 0) {
+    throw new Error("subscription-paddle: paddle-signature header is malformed");
+  }
+  if (!TIMESTAMP_PATTERN.test(parsed.timestamp)) {
+    throw new Error("subscription-paddle: webhook ts is not a Unix timestamp in seconds");
+  }
+  if (Math.abs(nowSeconds - Number(parsed.timestamp)) > PADDLE_WEBHOOK_TOLERANCE_SECONDS) {
+    throw new Error("subscription-paddle: webhook timestamp outside the tolerance window");
+  }
+  const expected = createHmac("sha256", secret).update(`${parsed.timestamp}:${rawBody}`).digest();
+  const matches = parsed.signatures.some((signature) => {
+    if (!SHA256_HEX_PATTERN.test(signature)) return false;
+    const candidate = Buffer.from(signature, "hex");
+    return candidate.length === expected.length && timingSafeEqual(candidate, expected);
+  });
+  if (!matches) throw new Error("subscription-paddle: webhook signature verify failed");
+}

package/packages/bundled-features/src/subscription-paddle/webhook-events.ts

@@ -0,0 +1,172 @@
+// Paddle webhook: signature check, then mapping of Paddle's event envelope onto
+// the foundation's normalized events. Events without a valid tenant binding are
+// dropped (200 ignored): see tenant-binding.ts.
+
+import {
+  BillingEventKinds,
+  type PaymentEvent,
+  type SubscriptionEvent,
+  type SubscriptionEventType,
+  SubscriptionEventTypes,
+} from "@cosmicdrift/kumiko-bundled-features/billing-foundation";
+import { createFallbackLogger } from "@cosmicdrift/kumiko-framework/logging";
+import type { SecretsContext } from "@cosmicdrift/kumiko-framework/secrets";
+import { parseJsonOrThrow } from "@cosmicdrift/kumiko-framework/utils";
+import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import * as z from "zod";
+import { PADDLE_PROVIDER_NAME } from "./constants.ts";
+import type { PaddleWebhookRuntime } from "./runtime.ts";
+import {
+  mapPaddleSubscriptionState,
+  paddleCustomDataSchema,
+  paddleSubscriptionSchema,
+} from "./subscription-state.ts";
+import { boundTenantOf } from "./tenant-binding.ts";
+import { verifyPaddleSignature } from "./verify-webhook.ts";
+
+const PADDLE_SUBSCRIPTION_EVENT_TYPES: Readonly<Record<string, SubscriptionEventType>> = {
+  "subscription.created": SubscriptionEventTypes.created,
+  "subscription.activated": SubscriptionEventTypes.updated,
+  "subscription.updated": SubscriptionEventTypes.updated,
+  "subscription.trialing": SubscriptionEventTypes.updated,
+  "subscription.paused": SubscriptionEventTypes.updated,
+  "subscription.resumed": SubscriptionEventTypes.updated,
+  "subscription.past_due": SubscriptionEventTypes.invoicePaymentFailed,
+  "subscription.canceled": SubscriptionEventTypes.canceled,
+};
+
+const TRANSACTION_COMPLETED = "transaction.completed";
+
+const envelopeSchema = z.object({
+  event_id: z.string().min(1),
+  event_type: z.string(),
+  occurred_at: z.iso.datetime({ offset: true }),
+  data: z.unknown(),
+});
+
+const paddleTransactionSchema = z.object({
+  id: z.string().min(1),
+  subscription_id: z.string().nullish(),
+  customer_id: z.string().min(1).nullish(),
+  custom_data: paddleCustomDataSchema,
+  items: z.array(
+    z.object({
+      price: z.object({ id: z.string().min(1) }),
+      quantity: z.number().int().positive().optional(),
+    }),
+  ),
+});
+
+export type PaddleWebhookOptions = {
+  readonly priceToTier: Readonly<Record<string, string>>;
+  /** Test seam: Unix seconds. Defaults to the wall clock. */
+  readonly nowSeconds?: () => number;
+};
+
+function currentUnixSeconds(): number {
+  return Math.floor(Temporal.Now.instant().epochMilliseconds / 1000);
+}
+
+function parsePaymentEvent(
+  providerEventId: string,
+  data: unknown,
+  bindingKey: string,
+): PaymentEvent | null {
+  const parsed = paddleTransactionSchema.safeParse(data);
+  if (!parsed.success) return null;
+  const transaction = parsed.data;
+  // A subscription's own payments are covered by its subscription.* events.
+  if (transaction.subscription_id) return null;
+  const priceId = transaction.items[0]?.price.id;
+  const quantity = transaction.items[0]?.quantity ?? 1;
+  const bound = boundTenantOf(transaction.custom_data, bindingKey);
+  if (!bound || !priceId || !transaction.customer_id) return null;
+  return {
+    kind: BillingEventKinds.payment,
+    providerEventId,
+    providerName: PADDLE_PROVIDER_NAME,
+    tenantId: bound.tenantId,
+    ...(bound.consentId !== undefined && { consentId: bound.consentId }),
+    providerCheckoutId: transaction.id,
+    providerCustomerId: transaction.customer_id,
+    priceId,
+    quantity,
+  };
+}
+
+// Subscription prices are meant to be quantity 1; the tier is still set, but a
+// different quantity is worth an operator's attention. Event id and quantity only.
+function warnOnUnexpectedQuantity(
+  providerEventId: string,
+  items: readonly { readonly quantity?: number | undefined }[],
+): void {
+  for (const item of items) {
+    if (item.quantity !== undefined && item.quantity !== 1) {
+      createFallbackLogger("subscription-paddle").warn(
+        "paddle subscription item quantity is not 1; the tier is still set",
+        { providerEventId, quantity: item.quantity },
+      );
+    }
+  }
+}
+
+function parseSubscriptionEvent(
+  providerEventId: string,
+  type: SubscriptionEventType,
+  providerEventAt: string,
+  data: unknown,
+  options: { readonly priceToTier: Readonly<Record<string, string>>; readonly bindingKey: string },
+): SubscriptionEvent | null {
+  const parsed = paddleSubscriptionSchema.safeParse(data);
+  if (!parsed.success) return null;
+  const sub = parsed.data;
+  const bound = boundTenantOf(sub.custom_data, options.bindingKey);
+  const state = mapPaddleSubscriptionState(sub, options.priceToTier);
+  if (!bound || !state) return null;
+  warnOnUnexpectedQuantity(providerEventId, sub.items);
+  return {
+    providerEventId,
+    providerName: PADDLE_PROVIDER_NAME,
+    type,
+    tenantId: bound.tenantId,
+    ...(bound.consentId !== undefined && { consentId: bound.consentId }),
+    providerCustomerId: sub.customer_id,
+    providerSubscriptionId: sub.id,
+    providerEventAt,
+    ...state,
+  };
+}
+
+export function verifyAndParsePaddleWebhook(
+  runtime: PaddleWebhookRuntime,
+  options: PaddleWebhookOptions,
+): (
+  rawBody: string,
+  headers: Record<string, string>,
+  systemSecrets?: SecretsContext,
+) => Promise<SubscriptionEvent | PaymentEvent | null> {
+  const nowSeconds = options.nowSeconds ?? currentUnixSeconds;
+  return async (rawBody, headers, systemSecrets) => {
+    const secret = await runtime.resolveWebhookSecret(systemSecrets);
+    verifyPaddleSignature(rawBody, headers, secret, nowSeconds());
+    // After verification only: an unauthenticated request must not trigger a second secret read.
+    const bindingKey = await runtime.resolveTenantBindingKey(systemSecrets);
+
+    // Past verification the body is trusted to be Paddle's; a malformed shape is
+    // schema drift, so it is dropped (200 ignored) instead of answered with a 401.
+    const envelope = envelopeSchema.safeParse(
+      parseJsonOrThrow<unknown>(rawBody, "subscription-paddle webhook body"),
+    );
+    if (!envelope.success) return null;
+
+    const { event_id: providerEventId, event_type: type, occurred_at, data } = envelope.data;
+    if (type === TRANSACTION_COMPLETED) return parsePaymentEvent(providerEventId, data, bindingKey);
+    if (!Object.hasOwn(PADDLE_SUBSCRIPTION_EVENT_TYPES, type)) return null;
+    const normalizedType = PADDLE_SUBSCRIPTION_EVENT_TYPES[type];
+    if (!normalizedType) return null;
+    return parseSubscriptionEvent(providerEventId, normalizedType, occurred_at, data, {
+      priceToTier: options.priceToTier,
+      bindingKey,
+    });
+  };
+}

package/packages/bundled-features/src/template-resolver/README.md

@@ -232,8 +232,8 @@ including SSE refresh, and an editor target with the `collectionId`. The app pas
 under an unmounted feature causes boot to fail instead of silently disappearing from the sidebar. Node
 visibility follows `access` unless `nav.access` specifies otherwise.
 
-A "+" on the node requires an explicit `nav.createAction`, whose target is usually
-`treeHandle.create`; without it, the collection only lists existing items. `nav.actions` adds hover actions to the row.
+A "+" on the node opens the built-in create form (`template-resolver:create`) unless
+`nav.createAction` points elsewhere, usually at `treeHandle.create`. `nav.actions` adds hover actions to the row.
 
 Saving **publishes immediately**, with status `active` and an empty `variableSchema`.
 Anyone who needs a draft stage or a variable schema uses

package/packages/bundled-features/src/template-resolver/changes.json

@@ -1,4 +1,24 @@
 [
+  {
+    "version": "0.395.0",
+    "type": "breaking",
+    "title": "Content collections edit in plain or document format; rich and markdown are gone",
+    "detail": "ContentEditorFormat is \"plain\" | \"document\". RichContentEditor and the old tiptap editor are removed from @cosmicdrift/kumiko-renderer/web; the document editor is DocumentContentEditor from @cosmicdrift/kumiko-bundled-features/template-resolver/web. A collection's storage format comes from its declaration on the server (plain stores plain, document stores html sanitized with sanitizeDocumentHtml for every collection kind) and the collection write no longer takes contentFormat. Saved content with {{name}} as text opens with variable nodes. Every collection gets a create form behind a \"+\" in its nav (unless it declares its own createAction); the collection write takes createOnly and answers an existing slug with the field error slug_exists. The text block editor and the secrets edit screen use FormScreenLayout, which takes an optional unsavedCount. useDispatchTarget is exported from @cosmicdrift/kumiko-renderer/web.",
+    "migration": "Run bun kumiko-upgrade --apply. It rewrites contentFormat \"rich\" and \"markdown\" in collection declarations to \"document\". Replace imports of RichContentEditor with DocumentContentEditor from @cosmicdrift/kumiko-bundled-features/template-resolver/web, and drop contentFormat from collection write payloads.",
+    "codemod": "scripts/codemod/content-collection-format.ts"
+  },
+  {
+    "version": "0.394.0",
+    "type": "fix",
+    "title": "collection trees and Save follow the server's access rules",
+    "detail": "textBlocksClient({ tenantId }) no longer sends tenantIdOverride for `ownership: \"user\"` collections, and a tenant-wide tree that the server answers with tenant_override_requires_system_admin reloads on the session tenant, so members see and edit their own entries instead of an error. The Save button follows the collection's own access rule (DEFAULT_COLLECTION_ACCESS when none is declared), the same rule the list, item and set handlers check; the public text-block pair keeps TenantAdmin or SystemAdmin. A save reloads the tree of its collection, so a new per-user entry shows without a page reload. The editor sets the page header title to the entry title, so the breadcrumb no longer shows the screen behind it."
+  },
+  {
+    "version": "0.394.0",
+    "type": "fix",
+    "title": "user-owned collection entries no longer fail with pii_ciphertext_leak",
+    "detail": "With a PII key service configured, the list and item queries of an `ownership: \"user\"` collection (signatures) returned the stored ciphertext, so the API rejected the response and the editor showed \"Could not load block\". Both queries now decrypt `content` for the owner before returning it."
+  },
   {
     "version": "0.390.0",
     "type": "fix",

package/packages/bundled-features/src/template-resolver/document-sanitizer.ts

@@ -299,6 +299,18 @@ function isSanitizedHtmlKind(kind: string): boolean {
   return kind === "snippet" || isOneOf(DOCUMENT_HTML_KINDS, kind);
 }
 
+type SanitizeBodyInput = {
+  readonly kind: string;
+  readonly contentFormat: ContentFormat;
+  readonly content: string | null;
+  /** A document collection stores html whatever its kind, so its html is always rebuilt. */
+  readonly alwaysSanitizeHtml?: boolean;
+};
+
+function isSanitizedBody(input: SanitizeBodyInput): boolean {
+  return input.alwaysSanitizeHtml === true || isSanitizedHtmlKind(input.kind);
+}
+
 const HTML_ONLY_KINDS: ReadonlySet<string> = new Set(DOCUMENT_HTML_KINDS);
 
 function requiredFormatViolation(
@@ -319,14 +331,10 @@ const IMAGES_BLOCK_KIND = "document-pdf";
 
 // The node is part of the shared document model, so a mail body would keep it after the
 // rebuild; only a PDF resolves the record's images.
-function imagesBlockViolation(input: {
-  readonly kind: string;
-  readonly contentFormat: ContentFormat;
-  readonly content: string | null;
-}): DocumentViolation | null {
+function imagesBlockViolation(input: SanitizeBodyInput): DocumentViolation | null {
   if (
     input.kind === IMAGES_BLOCK_KIND ||
-    !isSanitizedHtmlKind(input.kind) ||
+    !isSanitizedBody(input) ||
     input.contentFormat !== "html" ||
     input.content === null
   ) {
@@ -345,20 +353,12 @@ function imagesBlockViolation(input: {
     : null;
 }
 
-export function sanitizeTemplateBody(input: {
-  readonly kind: string;
-  readonly contentFormat: ContentFormat;
-  readonly content: string | null;
-}): SanitizeBodyResult {
+export function sanitizeTemplateBody(input: SanitizeBodyInput): SanitizeBodyResult {
   const formatViolation = requiredFormatViolation(input.kind, input.contentFormat);
   if (formatViolation !== null) return { ok: false, violations: [formatViolation] };
   const imagesViolation = imagesBlockViolation(input);
   if (imagesViolation !== null) return { ok: false, violations: [imagesViolation] };
-  if (
-    !isSanitizedHtmlKind(input.kind) ||
-    input.contentFormat !== "html" ||
-    input.content === null
-  ) {
+  if (!isSanitizedBody(input) || input.contentFormat !== "html" || input.content === null) {
     return { ok: true, content: input.content };
   }
   const result = sanitizeDocumentHtml(input.content);