@cosmicdrift/kumiko-samples 0.378.0 → 0.379.0

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-pages.ts

@@ -6,6 +6,7 @@ import { escapeHtml, escapeHtmlAttr } from "@cosmicdrift/kumiko-renderer/headles
 import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import type { Context } from "hono";
 import { getCookie } from "hono/cookie";
+import * as z from "zod";
 import {
   type PublicPageWrapLayout,
   redirectToCanonicalPath,
@@ -13,11 +14,16 @@ import {
   slashVariantOf,
   wrapInLayout,
 } from "../../page-render/index.ts";
-import { SubscriptionFoundationHandlers } from "../constants.ts";
 import { CONTRACT_TERMINATION_DECLARATION_TYPES, CONTRACT_TERMINATION_KINDS } from "../events.ts";
+import { SubscriptionFoundationHandlers } from "../web/constants.ts";
 import type { ConsentLocale } from "./consent-text.ts";
 import { formatReceivedAt } from "./termination-mail.ts";
 import { requestContractTerminationSchema } from "./termination-request.ts";
+import {
+  REVOCATION_PATHS,
+  type RevocationOutcome,
+  revokeContractTerminationSchema,
+} from "./termination-revoke.ts";
 import { type PageTexts, TERMINATION_TEXTS } from "./termination-texts.ts";
 
 export type ContractTerminationRoutesOptions = {
@@ -77,6 +83,8 @@ function pageHeaders(): Record<string, string> {
     ...headers,
     "content-security-policy": `${headers["content-security-policy"] ?? ""}; frame-ancestors 'none'; form-action 'self'`,
     "x-frame-options": "DENY",
+    // The revoke link carries its token in the query string.
+    "referrer-policy": "no-referrer",
   };
 }
 
@@ -302,17 +310,19 @@ function reentryHeaders(c: Context): Headers {
   return headers;
 }
 
-async function submitDeclaration(
+type PageApp = { fetch: (request: Request, env?: unknown) => Response | Promise<Response> };
+
+async function dispatchAnonymousWrite(
   c: Context,
-  app: { fetch: (request: Request, env?: unknown) => Response | Promise<Response> },
+  app: PageApp,
   clientIp: string,
-  values: FormValues,
-  locale: ConsentLocale,
-): Promise<
-  | { readonly kind: "received"; readonly requestId: string; readonly receivedAtIso: string }
-  | { readonly kind: "rate-limited" }
-  | { readonly kind: "failed" }
-> {
+  type: string,
+  payload: Record<string, string>,
+): Promise<{
+  readonly rateLimited: boolean;
+  readonly ok: boolean;
+  readonly data: WriteResponseBody["data"];
+}> {
   // deps.write only resolves a session user under /api/*; this page lives
   // outside it, so it re-enters the dispatcher through the app like the
   // user-export by-token route. The resolved clientIp as env keeps the
@@ -323,30 +333,158 @@ async function submitDeclaration(
     new Request(`${new URL(c.req.url).origin}/api/write`, {
       method: "POST",
       headers: reentryHeaders(c),
-      body: JSON.stringify({
-        type: SubscriptionFoundationHandlers.requestContractTermination,
-        payload: payloadOf(values, locale),
-      }),
+      body: JSON.stringify({ type, payload }),
     }),
     clientIp,
   );
   const parsed: WriteResponseBody | null = await response.json().catch(() => null);
-  if (response.status === 429 || parsed?.error?.code === RATE_LIMITED_CODE) {
-    return { kind: "rate-limited" };
-  }
-  const requestId = parsed?.data?.requestId;
-  const receivedAtIso = parsed?.data?.receivedAtIso;
-  if (
-    response.ok &&
-    parsed?.isSuccess === true &&
-    typeof requestId === "string" &&
-    typeof receivedAtIso === "string"
-  ) {
+  return {
+    rateLimited: response.status === 429 || parsed?.error?.code === RATE_LIMITED_CODE,
+    ok: response.ok && parsed?.isSuccess === true,
+    data: parsed?.data,
+  };
+}
+
+async function submitDeclaration(
+  c: Context,
+  app: PageApp,
+  clientIp: string,
+  values: FormValues,
+  locale: ConsentLocale,
+): Promise<
+  | { readonly kind: "received"; readonly requestId: string; readonly receivedAtIso: string }
+  | { readonly kind: "rate-limited" }
+  | { readonly kind: "failed" }
+> {
+  const response = await dispatchAnonymousWrite(
+    c,
+    app,
+    clientIp,
+    SubscriptionFoundationHandlers.requestContractTermination,
+    payloadOf(values, locale),
+  );
+  if (response.rateLimited) return { kind: "rate-limited" };
+  const requestId = response.data?.requestId;
+  const receivedAtIso = response.data?.receivedAtIso;
+  if (response.ok && typeof requestId === "string" && typeof receivedAtIso === "string") {
     return { kind: "received", requestId, receivedAtIso };
   }
   return { kind: "failed" };
 }
 
+const revocationOutcomeSchema = z.object({
+  outcome: z.enum(["revoked", "already-revoked", "too-late", "invalid"]),
+});
+
+type RevocationLinkValues = z.infer<typeof revokeContractTerminationSchema>;
+
+// Missing or malformed link parameters answer like a wrong token.
+function revocationValuesOf(source: Record<string, unknown>): RevocationLinkValues | null {
+  const text = (key: string): string => {
+    const value = source[key];
+    return typeof value === "string" ? value : "";
+  };
+  const parsed = revokeContractTerminationSchema.safeParse({
+    requestId: text("r"),
+    token: text("t"),
+    tenantId: text("tenant"),
+  });
+  return parsed.success ? parsed.data : null;
+}
+
+async function submitRevocation(
+  c: Context,
+  app: PageApp,
+  clientIp: string,
+  values: RevocationLinkValues,
+): Promise<RevocationOutcome | "rate-limited"> {
+  const response = await dispatchAnonymousWrite(
+    c,
+    app,
+    clientIp,
+    SubscriptionFoundationHandlers.revokeContractTermination,
+    values,
+  );
+  if (response.rateLimited) return "rate-limited";
+  const outcome = revocationOutcomeSchema.safeParse(response.data);
+  return response.ok && outcome.success ? outcome.data.outcome : "invalid";
+}
+
+function revokeConfirmPage(
+  ctx: PageContext,
+  revokePath: string,
+  values: RevocationLinkValues,
+): Response {
+  const { revoke } = TERMINATION_TEXTS[ctx.locale].page;
+  const hidden = (
+    [
+      ["r", values.requestId],
+      ["t", values.token],
+      ["tenant", values.tenantId],
+    ] as const
+  )
+    .map(
+      ([name, value]) =>
+        `<input type="hidden" name="${escapeHtmlAttr(name)}" value="${escapeHtmlAttr(value ?? "")}">`,
+    )
+    .join("\n");
+  const body = `<h1>${escapeHtml(revoke.confirmTitle)}</h1>
+<p>${escapeHtml(revoke.confirmLead)}</p>
+<form method="post" action="${escapeHtmlAttr(revokePath)}" data-kumiko-form="contract-termination-revoke">
+${hidden}
+<button type="submit" data-kumiko-button="revoke">${escapeHtml(revoke.confirmButton)}</button>
+</form>`;
+  return htmlResponse(ctx, revoke.confirmTitle, body, 200);
+}
+
+function revokeResultPage(ctx: PageContext, outcome: RevocationOutcome | "rate-limited"): Response {
+  const { page } = TERMINATION_TEXTS[ctx.locale];
+  const { revoke } = page;
+  const simple = (title: string, text: string, status: 200 | 400 | 429): Response =>
+    htmlResponse(ctx, title, `<h1>${escapeHtml(title)}</h1><p>${escapeHtml(text)}</p>`, status);
+  switch (outcome) {
+    case "revoked":
+      return simple(revoke.revokedTitle, revoke.revokedBody, 200);
+    case "already-revoked":
+      return simple(revoke.alreadyRevokedTitle, revoke.alreadyRevokedBody, 200);
+    case "too-late":
+      return simple(revoke.tooLateTitle, revoke.tooLateBody, 200);
+    case "rate-limited":
+      return simple(page.rateLimitedTitle, page.rateLimitedBody, 429);
+    case "invalid":
+      return simple(revoke.invalidTitle, revoke.invalidBody, 400);
+  }
+}
+
+// GET only renders the confirmation form: mail scanners prefetch links, so the
+// state change waits for the POST.
+function revokeRoutesFor(ctx: PageContext): AnonymousExtraRoute[] {
+  const revokePath = REVOCATION_PATHS[ctx.locale];
+  return [
+    {
+      method: "GET",
+      path: revokePath,
+      entry: "anonymous",
+      handler: (c) => {
+        const values = revocationValuesOf(c.req.query());
+        return values === null
+          ? revokeResultPage(ctx, "invalid")
+          : revokeConfirmPage(ctx, revokePath, values);
+      },
+    },
+    {
+      method: "POST",
+      path: revokePath,
+      entry: "anonymous",
+      handler: async (c, deps) => {
+        const values = revocationValuesOf(await c.req.parseBody());
+        if (values === null) return revokeResultPage(ctx, "invalid");
+        return revokeResultPage(ctx, await submitRevocation(c, deps.app, deps.clientIp, values));
+      },
+    },
+  ];
+}
+
 function routesFor(ctx: PageContext): AnonymousExtraRoute[] {
   const { locale, path } = ctx;
   const slashVariant = slashVariantOf(path);
@@ -409,7 +547,8 @@ export function createContractTerminationRoutes(
     en: options.paths?.en ?? DEFAULT_PATHS.en,
   };
   const wrapLayout = options.wrapLayout ?? wrapInLayout;
-  return (["de", "en"] as const).flatMap((locale) =>
-    routesFor({ locale, path: alternates[locale], wrapLayout, alternates }),
-  );
+  return (["de", "en"] as const).flatMap((locale) => {
+    const pageContext = { locale, path: alternates[locale], wrapLayout, alternates };
+    return [...routesFor(pageContext), ...revokeRoutesFor(pageContext)];
+  });
 }

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-record.ts

@@ -14,25 +14,30 @@ import { UnprocessableError } from "@cosmicdrift/kumiko-framework/errors";
 import * as z from "zod";
 import { subscriptionAggregateId, terminationUnmatchedAggregateId } from "../aggregate-id.ts";
 import { resolveProviderPlugin } from "../checkout-core.ts";
-import { isTerminalSubscriptionStatus, SubscriptionCancelTimings } from "../constants.ts";
 import {
   CONTRACT_TERMINATION_CHANNELS,
   CONTRACT_TERMINATION_DECLARATION_TYPES,
   CONTRACT_TERMINATION_DECLARED_EVENT_QN,
   CONTRACT_TERMINATION_KINDS,
   CONTRACT_TERMINATION_REQUESTED_EVENT_QN,
+  CONTRACT_TERMINATION_REVOKED_EVENT_QN,
   CONTRACT_TERMINATION_UNMATCHED_AGGREGATE_TYPE,
   CONTRACT_TERMINATION_UNMATCHED_EVENT_QN,
   type ContractTerminationDeclaredPayload,
   type ContractTerminationRequestedPayload,
   type ContractTerminationUnmatchedPayload,
   contractTerminationRequestedPayloadSchema,
+  contractTerminationRevokedPayloadSchema,
   type ProviderCancelOutcome,
   SUBSCRIPTION_AGGREGATE_TYPE,
 } from "../events.ts";
-import { getSubscriptionForTenant } from "../get-subscription-for-tenant.ts";
+import { getSubscriptionForTenant, type SubscriptionView } from "../get-subscription-for-tenant.ts";
 import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.ts";
-import { CONSENT_LOCALES, FALLBACK_CONSENT_LOCALE } from "./consent-locale.ts";
+import { isTerminalSubscriptionStatus, SubscriptionCancelTimings } from "../web/constants.ts";
+import {
+  CONSENT_LOCALES,
+  FALLBACK_CONSENT_LOCALE,
+} from "../web/consumer-protection/consent-locale.ts";
 import { notifyOperator } from "./termination-notify.ts";
 import type { OperatorNoticeReason } from "./termination-texts.ts";
 import { isWithinWithdrawalPeriod } from "./withdrawal-period.ts";
@@ -64,6 +69,7 @@ export const declareContractTerminationSchema = z
     terminationKind: z.enum(CONTRACT_TERMINATION_KINDS),
     receivedAtIso: z.string().min(1),
     locale: z.enum(CONSENT_LOCALES),
+    revocationTokenHash: z.string().length(64).optional(),
   })
   .strict();
 
@@ -170,6 +176,51 @@ export function createDeclareContractTerminationHandler(): WriteHandlerDef {
   };
 }
 
+function revokedRecordResult(receivedAtIso: string) {
+  return {
+    isSuccess: true as const,
+    data: {
+      receivedAtIso,
+      effectiveAtIso: null,
+      providerCancel: "none",
+      noticeReason: null,
+      withdrawalPeriodExpired: false,
+    } satisfies RecordContractTerminationResult,
+  };
+}
+
+// A revocation that landed during the provider cancel found nothing to take back yet.
+async function takeBackLateRevokedCancel(
+  ctx: HandlerContext,
+  consumerProtection: ConsumerProtectionOptions,
+  args: {
+    readonly payload: z.infer<typeof recordContractTerminationSchema>;
+    readonly tenantId: string;
+    readonly receivedAtIso: string;
+    readonly providerCancel: ProviderCancelOutcome;
+  },
+): Promise<void> {
+  const { payload, tenantId, receivedAtIso, providerCancel } = args;
+  // skip: nothing was cancelled at the provider, nothing to resume
+  if (providerCancel !== "period-end") return;
+  const reasons = await resumeAtProvider(ctx, await getSubscriptionForTenant(ctx, tenantId));
+  // skip: resumed cleanly, the revocation notice already tells the operator
+  if (reasons.length === 0) return;
+  await notifyOperator(ctx, consumerProtection, {
+    locale: payload.locale ?? FALLBACK_CONSENT_LOCALE,
+    requestId: payload.requestId,
+    receivedAtIso,
+    channel: "public",
+    declaration: {
+      declarationType: payload.declarationType,
+      terminationKind: payload.terminationKind,
+    },
+    reasons,
+    tenantId,
+    providerCancel,
+  });
+}
+
 export function createRecordContractTerminationHandler(
   options: ResolvedBillingFoundationOptions,
   consumerProtection: ConsumerProtectionOptions,
@@ -218,6 +269,11 @@ export function createRecordContractTerminationHandler(
         };
       }
 
+      // A revoked public declaration never reaches the provider.
+      if (hasRevocation(stream.events, payload.requestId)) {
+        return revokedRecordResult(receivedAtIso);
+      }
+
       const withdrawalPeriodExpired =
         payload.declarationType === "withdrawal" &&
         payload.when === SubscriptionCancelTimings.immediately &&
@@ -245,6 +301,16 @@ export function createRecordContractTerminationHandler(
         aggregateId: subscriptionAggregateId(tenantId),
         aggregateType: SUBSCRIPTION_AGGREGATE_TYPE,
       });
+      // A revocation that landed during the provider call found no cancel to take back.
+      if (hasRevocation(streamAfterProviderCall.events, payload.requestId)) {
+        await takeBackLateRevokedCancel(ctx, consumerProtection, {
+          payload,
+          tenantId,
+          receivedAtIso,
+          providerCancel,
+        });
+        return revokedRecordResult(receivedAtIso);
+      }
       await streamAfterProviderCall.appendOne({
         type: CONTRACT_TERMINATION_REQUESTED_EVENT_QN,
         payload: recorded,
@@ -282,6 +348,39 @@ export function createRecordContractTerminationHandler(
   };
 }
 
+export function hasRevocation(
+  events: readonly { type: string; payload: unknown }[],
+  requestId: string,
+) {
+  return events.some(
+    (e) =>
+      e.type === CONTRACT_TERMINATION_REVOKED_EVENT_QN &&
+      contractTerminationRevokedPayloadSchema.safeParse(e.payload).data?.requestId === requestId,
+  );
+}
+
+export async function resumeAtProvider(
+  ctx: HandlerContext,
+  subscription: SubscriptionView | null,
+): Promise<OperatorNoticeReason[]> {
+  if (subscription === null || isTerminalSubscriptionStatus(subscription.status)) {
+    return ["revocation_resume_manual"];
+  }
+  const plugin = findPlugin(ctx, subscription.providerName);
+  if (!plugin?.resumeSubscription) return ["revocation_resume_manual"];
+  try {
+    await plugin.resumeSubscription(ctx, {
+      providerSubscriptionId: subscription.providerSubscriptionId,
+    });
+  } catch (error) {
+    ctx.log?.warn(
+      `[billing-foundation:revoke-contract-termination] provider resume failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    return ["revocation_resume_failed"];
+  }
+  return [];
+}
+
 function findPlugin(ctx: Parameters<typeof resolveProviderPlugin>[0], providerName: string) {
   try {
     return resolveProviderPlugin(ctx, providerName).plugin;

package/packages/bundled-features/src/billing-foundation/consumer-protection/termination-request.ts

@@ -15,12 +15,6 @@ import { generateId } from "@cosmicdrift/kumiko-framework/utils";
 import * as z from "zod";
 import { TenantQueries } from "../../tenant/index.ts";
 import { UserQueries } from "../../user/index.ts";
-import {
-  CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE,
-  SubscriptionCancelTimings,
-  SubscriptionFoundationHandlers,
-  SubscriptionFoundationQueries,
-} from "../constants.ts";
 import {
   CONTRACT_TERMINATION_DECLARATION_TYPES,
   CONTRACT_TERMINATION_KINDS,
@@ -30,11 +24,19 @@ import {
 } from "../events.ts";
 import { purchaseRolesOf } from "../plan-catalog.ts";
 import type { ConsumerProtectionOptions, ResolvedBillingFoundationOptions } from "../types.ts";
+import {
+  CONTRACT_TERMINATION_RECEIPT_NOTIFICATION_TYPE,
+  SubscriptionCancelTimings,
+  SubscriptionFoundationHandlers,
+  SubscriptionFoundationQueries,
+} from "../web/constants.ts";
 import { resolveConsentLocale } from "./consent-text.ts";
+import { openStoredUserEmail } from "./stored-user-email.ts";
 import { type TerminationDeclaration, terminationReceiptVariables } from "./termination-mail.ts";
 import { notifyOperator, type OperatorNoticePlan, requireNotify } from "./termination-notify.ts";
 import { mayMailReceipt } from "./termination-receipt-limit.ts";
 import type { RecordContractTerminationResult } from "./termination-record.ts";
+import { createRevocationToken, revocationUrl } from "./termination-revoke.ts";
 import type { OperatorNoticeReason } from "./termination-texts.ts";
 
 const EXTRAORDINARY_REASON_MESSAGE = "reason is required for an extraordinary termination";
@@ -102,7 +104,10 @@ function needsOperatorNotice(declaration: {
   ];
 }
 
-type TerminationMailPlan = OperatorNoticePlan & { readonly declaration: TerminationDeclaration };
+type TerminationMailPlan = OperatorNoticePlan & {
+  readonly declaration: TerminationDeclaration;
+  readonly revokeUrl?: string;
+};
 
 async function sendTerminationMails(
   ctx: HandlerContext,
@@ -122,6 +127,7 @@ async function sendTerminationMails(
           terminationKind: plan.declaration.terminationKind,
         },
         operatorEmail: consumerProtection.operatorEmail,
+        ...(plan.revokeUrl !== undefined && { revokeUrl: plan.revokeUrl }),
       }),
       locale: plan.locale,
       priority: "critical",
@@ -132,7 +138,8 @@ async function sendTerminationMails(
     : [...plan.reasons, "receipt_rate_limited" as const];
   // skip: no operator notice needed for this declaration
   if (reasons.length === 0) return;
-  await notifyOperator(ctx, consumerProtection, { ...plan, reasons });
+  const { revokeUrl: _revokeUrl, ...noticePlan } = plan;
+  await notifyOperator(ctx, consumerProtection, { ...noticePlan, reasons });
 }
 
 // Tenants the entered email can terminate a contract for: tenants where the
@@ -205,6 +212,7 @@ export function createRequestContractTerminationHandler(
       const reasons: OperatorNoticeReason[] = [];
       const locale = resolveConsentLocale(payload.locale);
       let matchedTenantId: string | undefined;
+      let revokeUrl: string | undefined;
 
       const candidates = await findTerminableTenantIds(
         ctx,
@@ -215,12 +223,30 @@ export function createRequestContractTerminationHandler(
       const [onlyCandidate] = candidates;
       if (candidates.length === 1 && onlyCandidate !== undefined) {
         matchedTenantId = onlyCandidate;
+        const revocation = createRevocationToken();
         const declared = await ctx.writeAs(
           createSystemUser(onlyCandidate),
           SubscriptionFoundationHandlers.declareContractTermination,
-          { requestId, declarationType, terminationKind, receivedAtIso, locale },
+          {
+            requestId,
+            declarationType,
+            terminationKind,
+            receivedAtIso,
+            locale,
+            revocationTokenHash: revocation.tokenHash,
+          },
         );
-        if (!declared.isSuccess) reasons.push("recording_failed");
+        if (!declared.isSuccess) {
+          reasons.push("recording_failed");
+        } else if (options.baseUrl !== undefined) {
+          revokeUrl = revocationUrl({
+            baseUrl: options.baseUrl,
+            locale,
+            requestId,
+            token: revocation.token,
+            tenantId: onlyCandidate,
+          });
+        }
       } else {
         reasons.push(candidates.length === 0 ? "unmatched" : "ambiguous");
         const recorded = await ctx.writeAs(
@@ -255,6 +281,7 @@ export function createRequestContractTerminationHandler(
         },
         reasons,
         ...(matchedTenantId !== undefined && { tenantId: matchedTenantId }),
+        ...(revokeUrl !== undefined && { revokeUrl }),
       });
 
       return {
@@ -291,7 +318,11 @@ export function createTerminateContractHandler(
           id: event.user.id,
         }),
       );
-      if (!caller.success || !caller.data.email || caller.data.isDeleted === true) {
+      const callerEmail =
+        caller.success && caller.data.email && caller.data.isDeleted !== true
+          ? await openStoredUserEmail(caller.data.email, "billing-foundation:terminate-contract")
+          : null;
+      if (callerEmail === null) {
         throw new InternalError({
           message: "billing-foundation:terminate-contract: calling user has no email on record",
         });
@@ -323,7 +354,7 @@ export function createTerminateContractHandler(
         declaration: {
           declarationType,
           terminationKind,
-          email: caller.data.email,
+          email: callerEmail,
           ...(payload.reason !== undefined && { reason: payload.reason }),
         },
         reasons: [