@cosmicdrift/kumiko-samples 0.393.0 → 0.394.0

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/changes.json

@@ -1,4 +1,16 @@
 [
+  {
+    "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/handlers/collection-item.query.ts

@@ -8,7 +8,7 @@ import { DEFAULT_COLLECTION_ACCESS } from "../web/constants.ts";
 import {
   type CollectionEntryRow,
   collectionStore,
-  toCollectionEntry,
+  readableCollectionEntry,
 } from "./collection-shared.ts";
 
 // Single entry of one collection, for the editor behind a tree node. Same
@@ -40,7 +40,7 @@ export function makeCollectionItemQuery(collection: ContentCollectionDefinition)
       });
 
       if (!row) return null;
-      return toCollectionEntry(row);
+      return readableCollectionEntry(row, store, `${collection.id}-item`);
     },
   });
 }

package/packages/bundled-features/src/template-resolver/handlers/collection-list.query.ts

@@ -8,7 +8,7 @@ import { DEFAULT_COLLECTION_ACCESS } from "../web/constants.ts";
 import {
   type CollectionEntryRow,
   collectionStore,
-  toCollectionEntry,
+  readableCollectionEntry,
 } from "./collection-shared.ts";
 
 // One list handler per declared collection: `kind`, `ownership` and `access`
@@ -42,7 +42,11 @@ export function makeCollectionListQuery(collection: ContentCollectionDefinition)
           ...store.scopeOf(query.user),
         }),
       );
-      return { blocks: rows.map(toCollectionEntry) };
+      return {
+        blocks: await Promise.all(
+          rows.map((row) => readableCollectionEntry(row, store, `${collection.id}-list`)),
+        ),
+      };
     },
   });
 }

package/packages/bundled-features/src/template-resolver/handlers/collection-shared.ts

@@ -1,3 +1,8 @@
+import { requestContext } from "@cosmicdrift/kumiko-framework/api";
+import {
+  configuredPiiSubjectKms,
+  decryptPiiFieldValues,
+} from "@cosmicdrift/kumiko-framework/crypto";
 import type { EventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import { createEventStoreExecutor } from "@cosmicdrift/kumiko-framework/db";
 import type {
@@ -41,6 +46,8 @@ export type CollectionStore = {
   scopeOf(user: SessionUser): Readonly<Record<string, unknown>>;
   /** Columns a create needs beyond the editable ones the payload carries. */
   createDefaults(tenantId: TenantId): Readonly<Record<string, unknown>>;
+  /** True when `content` is stored as PII ciphertext and must be decrypted on read. */
+  readonly contentIsPii: boolean;
 };
 
 // `ownership: "user"` means every user keeps their own entries (signatures);
@@ -55,6 +62,7 @@ export function collectionStore(collection: ContentCollectionDefinition): Collec
       executor: userContentExecutor,
       scopeOf: (user) => ({ ownerId: user.id }),
       createDefaults: () => ({}),
+      contentIsPii: true,
     };
   }
   return {
@@ -68,9 +76,26 @@ export function collectionStore(collection: ContentCollectionDefinition): Collec
       parentTemplateId: null,
       status: "active",
     }),
+    contentIsPii: false,
   };
 }
 
+// Raw reads return the stored column, which is ciphertext for a user-owned entry while a KMS
+// is configured; the API's leak guard rejects any response that still carries it.
+export async function readableCollectionEntry(
+  row: CollectionEntryRow,
+  store: CollectionStore,
+  fallbackRequestId: string,
+) {
+  const kms = configuredPiiSubjectKms();
+  if (!store.contentIsPii || !kms || row.content === null) return toCollectionEntry(row);
+  const decrypted = await decryptPiiFieldValues({ content: row.content }, ["content"], kms, {
+    requestId: requestContext.get()?.requestId ?? fallbackRequestId,
+  });
+  const content = decrypted["content"];
+  return toCollectionEntry({ ...row, content: typeof content === "string" ? content : null });
+}
+
 export function toCollectionEntry(row: CollectionEntryRow) {
   return {
     slug: row.slug,