@cosmicdrift/kumiko-samples 0.341.0 → 0.343.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-samples",
-  "version": "0.341.0",
+  "version": "0.343.0",
   "description": "Source trees of the Kumiko sample recipes, sample apps and bundled features in repo layout, for tooling such as few-shot corpus builds.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

package/packages/bundled-features/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-bundled-features",
-  "version": "0.341.0",
+  "version": "0.343.0",
   "description": "Built-in features — tenant, user, auth, delivery. The stuff you'd rewrite anyway, already typed.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",

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

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "escape-hatch retention follows the tenant compliance profile",
+    "detail": "The audit job `escape-hatch-retention` now deletes `escapeHatchUse` events after the `auditLog.retention` of the tenant's compliance profile. A tenant override can only lengthen that period, never go below the base retention of the selected profile. Cross-tenant audits (with `targetTenantId`, e.g. `identity-switch`) additionally follow the profile of the target tenant. The config key `audit:config:escape-hatch-retention-days` is only the fallback when compliance-profiles is not mounted.\n`pruneEvents` gains the optional `aggregateIds` option to restrict the prune to specific aggregates. `@cosmicdrift/kumiko-framework/compliance` exports `subtractRetentionSpec` and the `RetentionSpec` type for calendar-aware cutoffs (months and years)."
+  },
   {
     "version": "0.313.0",
     "type": "fix",

package/packages/bundled-features/src/audit/constants.ts

@@ -24,3 +24,12 @@ export const AUDIT_LOG_SCREEN_ID = "audit-log" as const;
 
 /** Single-event detail screen, breadcrumb-linked to the audit-log list. */
 export const AUDIT_LOG_DETAIL_SCREEN_ID = "audit-log-detail" as const;
+
+/**
+ * Config key (system scope) for how long `escapeHatchUse` audit events are kept. Only a fallback
+ * for apps without compliance-profiles; with it mounted, the tenant profile's `auditLog.retention`
+ * applies (a tenant override can only lengthen it).
+ */
+export const ESCAPE_HATCH_RETENTION_DAYS_KEY = "audit:config:escape-hatch-retention-days" as const;
+
+export const DEFAULT_ESCAPE_HATCH_RETENTION_DAYS = 90;

package/packages/bundled-features/src/audit/escape-hatch-audit-sink.ts

@@ -15,6 +15,7 @@ const escapeHatchKinds = [
   "global-write",
   "identity-switch",
   "unsafe-all-tenants",
+  "cross-tenant-read",
 ] as const satisfies readonly EscapeHatchKind[];
 
 export const escapeHatchUsedSchema = z.object({

package/packages/bundled-features/src/audit/feature.ts

@@ -1,14 +1,22 @@
 import {
   access,
+  createSystemConfig,
   defineFeature,
   type FeatureDefinition,
   i18nKey,
+  SYSTEM_USER_ID,
 } from "@cosmicdrift/kumiko-framework/engine";
-import { AUDIT_LOG_DETAIL_SCREEN_ID, AUDIT_LOG_SCREEN_ID, AuditQueries } from "./constants.js";
+import {
+  AUDIT_LOG_DETAIL_SCREEN_ID,
+  AUDIT_LOG_SCREEN_ID,
+  AuditQueries,
+  DEFAULT_ESCAPE_HATCH_RETENTION_DAYS,
+} from "./constants.js";
 import { escapeHatchUsedSchema } from "./escape-hatch-audit-sink.js";
 import { detailsQuery } from "./handlers/details.query.js";
 import { listQuery } from "./handlers/list.query.js";
 import { AUDIT_I18N } from "./i18n.js";
+import { runEscapeHatchRetention } from "./run-escape-hatch-retention.js";
 
 // Audit feature — exposes a filtered read over the framework's event log.
 //
@@ -18,10 +26,11 @@ import { AUDIT_I18N } from "./i18n.js";
 // the existing `events` table. See handlers/list.query.ts for the filter
 // surface.
 //
-// Retention lives elsewhere. Events are kept indefinitely as the source of
-// truth for state; archive or compress policies are a separate concern
-// (tracked with the snapshot/archive infrastructure that already exists in
-// the framework).
+// Retention: only `escapeHatchUse` events are pruned (daily job, config key
+// `escapeHatchRetentionDays`). All other events stay as the source of truth
+// for state; archive or compress policies are a separate concern (tracked
+// with the snapshot/archive infrastructure that already exists in the
+// framework).
 export function createAuditFeature(): FeatureDefinition {
   return defineFeature(
     "audit",
@@ -35,11 +44,43 @@ export function createAuditFeature(): FeatureDefinition {
         recommended: false,
       });
       r.translations({ keys: AUDIT_I18N });
-      r.requires("tenant", "user");
+      r.requires("tenant", "user", "config");
 
       // Registered so ops tools/MSPs can discover the type — escape-hatch-audit-sink.ts appends it via the low-level event-store API.
       r.defineEvent("escape-hatch-used", escapeHatchUsedSchema, { piiFields: "none" });
 
+      r.config(
+        "escapeHatchRetentionDays",
+        createSystemConfig("number", {
+          default: DEFAULT_ESCAPE_HATCH_RETENTION_DAYS,
+          bounds: { min: 1 },
+        }),
+      );
+
+      r.job({
+        name: "escape-hatch-retention",
+        trigger: { cron: "30 3 * * *" },
+        concurrency: "skip",
+        // pruneEvents needs a transaction-capable connection, which only unsafeRaw() hands a job.
+        escapeHatch: {
+          reason: "prunes expired escapeHatchUse audit events through pruneEvents",
+          grants: ["unsafeRaw"],
+        },
+        handler: async (_payload, ctx) => {
+          if (!ctx.registry) {
+            throw new Error(
+              "escape-hatch-retention: ctx.registry required (JobContext incomplete)",
+            );
+          }
+          await runEscapeHatchRetention({
+            db: ctx.db.unsafeRaw(),
+            registry: ctx.registry,
+            configResolver: ctx.configResolver,
+            userId: ctx._userId ?? SYSTEM_USER_ID,
+          });
+        },
+      });
+
       const queries = {
         list: r.queryHandler(listQuery),
         details: r.queryHandler(detailsQuery),

package/packages/bundled-features/src/audit/run-escape-hatch-retention.ts

@@ -0,0 +1,144 @@
+import { selectMany } from "@cosmicdrift/kumiko-framework/bun-db";
+import {
+  COMPLIANCE_PROFILES,
+  subtractRetentionSpec,
+} from "@cosmicdrift/kumiko-framework/compliance";
+import type { DbConnection, DbRunner } from "@cosmicdrift/kumiko-framework/db";
+import {
+  type ConfigResolver,
+  parseTenantId,
+  type Registry,
+  SYSTEM_TENANT_ID,
+  type TenantId,
+} from "@cosmicdrift/kumiko-framework/engine";
+import { eventsTable } from "@cosmicdrift/kumiko-framework/event-store";
+import { pruneEvents } from "@cosmicdrift/kumiko-framework/pipeline";
+import { getTemporal } from "@cosmicdrift/kumiko-framework/time";
+import { resolveProfileForTenant } from "../compliance-profiles/index.js";
+import { createConfigAccessor } from "../config/index.js";
+import {
+  DEFAULT_ESCAPE_HATCH_RETENTION_DAYS,
+  ESCAPE_HATCH_RETENTION_DAYS_KEY,
+} from "./constants.js";
+import {
+  ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+  escapeHatchUsedSchema,
+} from "./escape-hatch-audit-sink.js";
+
+// pruneEvents opens its own transaction, so a runner that cannot begin one (a tx handle) is rejected instead of nested.
+export function isDbConnection(runner: DbRunner): runner is DbConnection {
+  return "begin" in runner && typeof runner.begin === "function";
+}
+
+async function resolveRetentionDays(args: {
+  readonly registry: Registry;
+  readonly configResolver: ConfigResolver | undefined;
+  readonly db: DbConnection;
+  readonly userId: string;
+}): Promise<number> {
+  if (!args.configResolver) return DEFAULT_ESCAPE_HATCH_RETENTION_DAYS;
+  const config = createConfigAccessor(
+    args.registry,
+    args.configResolver,
+    SYSTEM_TENANT_ID,
+    args.userId,
+    args.db,
+  );
+  const raw = await config(ESCAPE_HATCH_RETENTION_DAYS_KEY);
+  return typeof raw === "number" && raw >= 1 ? raw : DEFAULT_ESCAPE_HATCH_RETENTION_DAYS;
+}
+
+// Soft dependency: audit must stay mountable without compliance-profiles, so we probe its entity.
+const COMPLIANCE_PROFILE_ENTITY = "tenant-compliance-profile";
+const PRUNE_CHUNK_SIZE = 1000;
+
+type AuditEventRow = {
+  readonly aggregateId: string;
+  readonly tenantId: TenantId;
+  readonly createdAt: Temporal.Instant;
+  readonly payload: unknown;
+};
+
+// Overrides may only lengthen retention: the earlier cutoff (same `now`) is the longer period.
+function earlierInstant(a: Temporal.Instant, b: Temporal.Instant): Temporal.Instant {
+  return Temporal.Instant.compare(a, b) <= 0 ? a : b;
+}
+
+async function resolveTenantCutoff(
+  db: DbConnection,
+  tenantId: TenantId,
+  now: Temporal.Instant,
+): Promise<Temporal.Instant> {
+  const { profile } = await resolveProfileForTenant({ db, tenantId });
+  const effective = subtractRetentionSpec(now, profile.auditLog.retention);
+  const base = subtractRetentionSpec(now, COMPLIANCE_PROFILES[profile.key].auditLog.retention);
+  return earlierInstant(effective, base);
+}
+
+// A cross-tenant audit (e.g. identity-switch) lives under the actor's tenant but must also
+// satisfy the target tenant's retention. A malformed payload falls back to the storing tenant.
+function targetTenantOf(payload: unknown): TenantId | null {
+  const parsed = escapeHatchUsedSchema.safeParse(payload);
+  return parsed.success ? parseTenantId(parsed.data.targetTenantId) : null;
+}
+
+async function pruneByTenantProfiles(db: DbConnection): Promise<number> {
+  const rows = await selectMany<AuditEventRow>(db, eventsTable, {
+    aggregateType: ESCAPE_HATCH_USE_AGGREGATE_TYPE,
+  });
+  const now = getTemporal().Now.instant();
+  const cutoffByTenant = new Map<TenantId, Temporal.Instant>();
+  const cutoffOf = async (tenantId: TenantId): Promise<Temporal.Instant> => {
+    const cached = cutoffByTenant.get(tenantId);
+    if (cached) return cached;
+    const cutoff = await resolveTenantCutoff(db, tenantId, now);
+    cutoffByTenant.set(tenantId, cutoff);
+    return cutoff;
+  };
+
+  const expiredAggregateIds: string[] = [];
+  for (const row of rows) {
+    const targetTenantId = targetTenantOf(row.payload);
+    const storeCutoff = await cutoffOf(row.tenantId);
+    const cutoff = targetTenantId
+      ? earlierInstant(storeCutoff, await cutoffOf(targetTenantId))
+      : storeCutoff;
+    if (Temporal.Instant.compare(row.createdAt, cutoff) < 0) {
+      expiredAggregateIds.push(row.aggregateId);
+    }
+  }
+
+  let deletedCount = 0;
+  for (let i = 0; i < expiredAggregateIds.length; i += PRUNE_CHUNK_SIZE) {
+    const result = await pruneEvents(db, {
+      aggregateTypes: [ESCAPE_HATCH_USE_AGGREGATE_TYPE],
+      aggregateIds: expiredAggregateIds.slice(i, i + PRUNE_CHUNK_SIZE),
+      olderThan: now,
+    });
+    deletedCount += result.deletedCount;
+  }
+  return deletedCount;
+}
+
+export async function runEscapeHatchRetention(args: {
+  readonly db: DbRunner;
+  readonly registry: Registry;
+  readonly configResolver: ConfigResolver | undefined;
+  readonly userId: string;
+}): Promise<{ readonly deletedCount: number }> {
+  const { db } = args;
+  if (!isDbConnection(db)) {
+    throw new Error("audit escape-hatch retention: a transaction-free DbConnection is required");
+  }
+
+  if (!args.registry.getEntity(COMPLIANCE_PROFILE_ENTITY)) {
+    const olderThanDays = await resolveRetentionDays({ ...args, db });
+    const { deletedCount } = await pruneEvents(db, {
+      aggregateTypes: [ESCAPE_HATCH_USE_AGGREGATE_TYPE],
+      olderThanDays,
+    });
+    return { deletedCount };
+  }
+
+  return { deletedCount: await pruneByTenantProfiles(db) };
+}

package/packages/bundled-features/src/auth-email-password/bootstrap.ts

@@ -5,13 +5,17 @@
 // invitation row holds membership role + global roles until the invitee
 // accepts through the regular invite-accept routes.
 
-import { makeDispatchSystemWrite } from "@cosmicdrift/kumiko-framework/api";
+import {
+  makeDispatchSystemWrite,
+  type SystemDispatchArgs,
+} from "@cosmicdrift/kumiko-framework/api";
 import { fetchOne } from "@cosmicdrift/kumiko-framework/bun-db";
 import type { DbConnection } from "@cosmicdrift/kumiko-framework/db";
 import {
   ConfigScopes,
   createSystemUser,
   type TenantId,
+  type WriteResult,
 } from "@cosmicdrift/kumiko-framework/engine";
 import type { Dispatcher } from "@cosmicdrift/kumiko-framework/pipeline";
 import { parseRoles } from "@cosmicdrift/kumiko-framework/utils";
@@ -48,6 +52,12 @@ export type BootstrapSeedDeps = {
   readonly tenantId: TenantId;
   readonly db: DbConnection;
   readonly dispatchSystemWrite: ReturnType<typeof makeDispatchSystemWrite>;
+  /** Writes as the system user with the given tenant roles in the seeded
+   *  tenant; use it when the app gates tenant data on its own roles rather
+   *  than SystemAdmin. */
+  readonly dispatchWriteAs: (
+    args: Pick<SystemDispatchArgs, "handlerQn" | "payload"> & { readonly roles: readonly string[] },
+  ) => Promise<WriteResult>;
 };
 
 export type BootstrapConfigValue = string | number | boolean;
@@ -276,7 +286,13 @@ export async function bootstrapTenants(
     const outcome = await ensureTenant(deps, tenant);
     const shouldSeed = outcome === "created" && plan.seed !== undefined;
     if (shouldSeed) {
-      await plan.seed?.({ tenantId: tenant.id, db: deps.db, dispatchSystemWrite });
+      await plan.seed?.({
+        tenantId: tenant.id,
+        db: deps.db,
+        dispatchSystemWrite,
+        dispatchWriteAs: ({ handlerQn, payload, roles }) =>
+          deps.dispatcher.write(handlerQn, payload, createSystemUser(tenant.id, roles)),
+      });
     }
     const configApplied = await applyTenantConfig(deps, tenant);
     tenants.push({ id: tenant.id, outcome, seeded: shouldSeed, configApplied });

package/packages/bundled-features/src/auth-email-password/changes.json

@@ -1,4 +1,23 @@
 [
+  {
+    "version": "0.343.0",
+    "type": "improvement",
+    "title": "Mail expiry shows duration and local time with time zone",
+    "detail": "Auth mails state the link validity as a duration and in the user's time zone\nThe five token mail renderers replace the UTC timestamp with `{duration}` (for example \"1 day\") and `{when}` (medium date and short time with zone abbreviation, in the recipient's locale). `RenderTokenContentArgs` gains `issuedAt` (default now) and `timeZone` (default UTC; an invalid zone falls back to UTC); the handlers pass the token issue time and `ctx.tz.user`. German strings use \"Konto\" instead of \"Account\".",
+    "migration": "Custom `auth.mail.*.expiry` translations should use the new `{duration}` and `{when}` placeholders; `{when}` now includes the time and zone abbreviation instead of a UTC timestamp."
+  },
+  {
+    "version": "0.342.0",
+    "type": "improvement",
+    "title": "AuthCard styling hooks (className, headerClassName, titleClassName, bodyClassName)",
+    "detail": "AuthCard takes className, headerClassName, titleClassName and bodyClassName\n`AuthCard` renders the body wrapper (`p-6 pt-0 flex flex-col gap-4`) itself and accepts `className` (Card), `headerClassName`, `titleClassName` and `bodyClassName`, merged with tailwind-merge over the defaults. The auth-email-password and auth-mfa screens no longer carry their own body wrapper; the rendered DOM stays the same. The session bootstrap error screen keeps its former bottom padding through `bodyClassName`."
+  },
+  {
+    "version": "0.342.0",
+    "type": "improvement",
+    "title": "Bootstrap seed can write with app tenant roles",
+    "detail": "Bootstrap seed gets `dispatchWriteAs` to write with app tenant roles instead of SystemAdmin."
+  },
   {
     "version": "0.341.0",
     "type": "breaking",

package/packages/bundled-features/src/auth-email-password/email-templates.ts

@@ -20,21 +20,21 @@ export const AUTH_MAIL_EN: Readonly<Record<string, string>> = {
   "auth.mail.reset.intro":
     "you requested a password reset for {app}. Click the link below to set a new password:",
   "auth.mail.reset.button": "Reset password",
-  "auth.mail.reset.expiry": "The link expires on {when}.",
+  "auth.mail.reset.expiry": "The link is valid for {duration} (until {when}).",
   "auth.mail.reset.ignore":
     "If you didn't request a reset, you can safely ignore this email — your password won't change.",
   "auth.mail.verify.subject": "{app} — Verify your email",
   "auth.mail.verify.greeting": "Welcome,",
   "auth.mail.verify.intro": "please verify your email address for {app} to activate your account:",
   "auth.mail.verify.button": "Verify email",
-  "auth.mail.verify.expiry": "The link expires on {when}.",
+  "auth.mail.verify.expiry": "The link is valid for {duration} (until {when}).",
   "auth.mail.verify.ignore": "If you didn't create this account, you can ignore this email.",
   "auth.mail.activation.subject": "{app} — Activate your account",
   "auth.mail.activation.greeting": "Welcome,",
   "auth.mail.activation.intro":
     "click the link below to activate your {app} account. The next step is choosing your password:",
   "auth.mail.activation.button": "Activate account",
-  "auth.mail.activation.expiry": "The link expires on {when}.",
+  "auth.mail.activation.expiry": "The link is valid for {duration} (until {when}).",
   "auth.mail.activation.ignore":
     "If you didn't sign up, you can ignore this email — no account is created until you open the link.",
   "auth.mail.invite.subject": "{app} — Workspace invitation",
@@ -42,14 +42,14 @@ export const AUTH_MAIL_EN: Readonly<Record<string, string>> = {
   "auth.mail.invite.intro":
     "you've been invited to a {app} workspace as {role}. Click the link below to accept:",
   "auth.mail.invite.button": "Accept invitation",
-  "auth.mail.invite.expiry": "The link expires on {when}.",
+  "auth.mail.invite.expiry": "The link is valid for {duration} (until {when}).",
   "auth.mail.invite.ignore": "If you weren't expecting this invitation, you can ignore this email.",
   "auth.mail.unlock.subject": "{app} — Unlock your account",
   "auth.mail.unlock.greeting": "Hi,",
   "auth.mail.unlock.intro":
     "your {app} account was temporarily locked after several failed sign-in attempts. Click the link below to unlock it immediately:",
   "auth.mail.unlock.button": "Unlock account",
-  "auth.mail.unlock.expiry": "The link expires on {when}.",
+  "auth.mail.unlock.expiry": "The link is valid for {duration} (until {when}).",
   "auth.mail.unlock.ignore":
     "If you didn't trigger this lock, you can ignore this email — the lock expires on its own.",
 };
@@ -62,6 +62,10 @@ export type RenderTokenContentArgs = {
   readonly locale?: AuthMailLocale;
   /** Optional app name for subject + intro. Default from auth.mail.appNameDefault. */
   readonly appName?: string;
+  /** ISO instant the token was issued; the validity duration is measured from it. Default: now. */
+  readonly issuedAt?: string;
+  /** IANA zone the expiry time is shown in. Default "UTC"; an invalid zone falls back to "UTC". */
+  readonly timeZone?: string;
 };
 
 export type RenderInviteEmailArgs = RenderTokenContentArgs & { readonly role: string };
@@ -119,7 +123,7 @@ export function renderResetPasswordEmail(args: RenderTokenContentArgs): AuthMail
     intro: t(locale, "auth.mail.reset.intro", { app }),
     buttonLabel: t(locale, "auth.mail.reset.button"),
     buttonUrl: args.url,
-    expiry: t(locale, "auth.mail.reset.expiry", { when: formatExpiry(args.expiresAt) }),
+    expiry: t(locale, "auth.mail.reset.expiry", expiryParams(args, locale)),
     ignore: t(locale, "auth.mail.reset.ignore"),
   });
 }
@@ -134,7 +138,7 @@ export function renderUnlockAccountEmail(args: RenderTokenContentArgs): AuthMail
     intro: t(locale, "auth.mail.unlock.intro", { app }),
     buttonLabel: t(locale, "auth.mail.unlock.button"),
     buttonUrl: args.url,
-    expiry: t(locale, "auth.mail.unlock.expiry", { when: formatExpiry(args.expiresAt) }),
+    expiry: t(locale, "auth.mail.unlock.expiry", expiryParams(args, locale)),
     ignore: t(locale, "auth.mail.unlock.ignore"),
   });
 }
@@ -149,7 +153,7 @@ export function renderVerifyEmail(args: RenderTokenContentArgs): AuthMailContent
     intro: t(locale, "auth.mail.verify.intro", { app }),
     buttonLabel: t(locale, "auth.mail.verify.button"),
     buttonUrl: args.url,
-    expiry: t(locale, "auth.mail.verify.expiry", { when: formatExpiry(args.expiresAt) }),
+    expiry: t(locale, "auth.mail.verify.expiry", expiryParams(args, locale)),
     ignore: t(locale, "auth.mail.verify.ignore"),
   });
 }
@@ -164,7 +168,7 @@ export function renderActivationEmail(args: RenderTokenContentArgs): AuthMailCon
     intro: t(locale, "auth.mail.activation.intro", { app }),
     buttonLabel: t(locale, "auth.mail.activation.button"),
     buttonUrl: args.url,
-    expiry: t(locale, "auth.mail.activation.expiry", { when: formatExpiry(args.expiresAt) }),
+    expiry: t(locale, "auth.mail.activation.expiry", expiryParams(args, locale)),
     ignore: t(locale, "auth.mail.activation.ignore"),
   });
 }
@@ -179,20 +183,76 @@ export function renderInviteEmail(args: RenderInviteEmailArgs): AuthMailContent
     intro: t(locale, "auth.mail.invite.intro", { app, role: args.role }),
     buttonLabel: t(locale, "auth.mail.invite.button"),
     buttonUrl: args.url,
-    expiry: t(locale, "auth.mail.invite.expiry", { when: formatExpiry(args.expiresAt) }),
+    expiry: t(locale, "auth.mail.invite.expiry", expiryParams(args, locale)),
     ignore: t(locale, "auth.mail.invite.ignore"),
   });
 }
 
-function formatExpiry(iso: string): string {
+const MS_PER_MINUTE = 60_000;
+const MS_PER_HOUR = 60 * MS_PER_MINUTE;
+const MS_PER_DAY = 24 * MS_PER_HOUR;
+
+type DurationUnit = "day" | "hour" | "minute";
+
+// Rounds to whole minutes first so a few ms between issuing and signing still
+// read as "1 day"; a larger unit is only used when it divides the span exactly.
+function durationParts(ms: number): { readonly amount: number; readonly unit: DurationUnit } {
+  const minutes = Math.max(1, Math.round(ms / MS_PER_MINUTE));
+  const minutesPerHour = MS_PER_HOUR / MS_PER_MINUTE;
+  const minutesPerDay = MS_PER_DAY / MS_PER_MINUTE;
+  if (minutes % minutesPerDay === 0) return { amount: minutes / minutesPerDay, unit: "day" };
+  if (minutes % minutesPerHour === 0) return { amount: minutes / minutesPerHour, unit: "hour" };
+  return { amount: minutes, unit: "minute" };
+}
+
+function formatDuration(ms: number, locale: string): string {
+  const { amount, unit } = durationParts(ms);
+  const options: Intl.NumberFormatOptions = { style: "unit", unit, unitDisplay: "long" };
   try {
-    const z = Temporal.Instant.from(iso).toZonedDateTimeISO("UTC");
-    return `${z.year}-${pad2(z.month)}-${pad2(z.day)} ${pad2(z.hour)}:${pad2(z.minute)} UTC`;
+    return new Intl.NumberFormat(locale, options).format(amount);
   } catch {
-    return iso;
+    return new Intl.NumberFormat("en", options).format(amount);
   }
 }
 
-function pad2(n: number): string {
-  return String(n).padStart(2, "0");
+// Intl rejects timeZoneName together with dateStyle/timeStyle, so the zone
+// abbreviation is read from a second formatter and appended.
+function formatWhen(expiresAt: Temporal.Instant, locale: string, timeZone: string): string {
+  const build = (tag: string, zone: string): string => {
+    const at = expiresAt.epochMilliseconds;
+    const dateTime = new Intl.DateTimeFormat(tag, {
+      dateStyle: "medium",
+      timeStyle: "short",
+      timeZone: zone,
+    }).format(at);
+    const zoneName = new Intl.DateTimeFormat(tag, { timeZone: zone, timeZoneName: "short" })
+      .formatToParts(at)
+      .find((part) => part.type === "timeZoneName")?.value;
+    return zoneName ? `${dateTime} ${zoneName}` : dateTime;
+  };
+  try {
+    return build(locale, timeZone);
+  } catch {
+    try {
+      return build(locale, "UTC");
+    } catch {
+      return build("en", "UTC");
+    }
+  }
+}
+
+function expiryParams(
+  args: RenderTokenContentArgs,
+  locale: string,
+): { readonly duration: string; readonly when: string } {
+  try {
+    const expiresAt = Temporal.Instant.from(args.expiresAt);
+    const issuedAt = args.issuedAt ? Temporal.Instant.from(args.issuedAt) : Temporal.Now.instant();
+    return {
+      duration: formatDuration(expiresAt.epochMilliseconds - issuedAt.epochMilliseconds, locale),
+      when: formatWhen(expiresAt, locale, args.timeZone ?? "UTC"),
+    };
+  } catch {
+    return { duration: args.expiresAt, when: args.expiresAt };
+  }
 }

package/packages/bundled-features/src/auth-email-password/handlers/invite-create.write.ts

@@ -160,7 +160,8 @@ async function issueInvitation(
 
   const email = request.email.toLowerCase();
   const tenantId = inviter.tenantId;
-  const expiresAt = Temporal.Now.instant().add({ seconds: ttlSeconds });
+  const issuedAt = Temporal.Now.instant();
+  const expiresAt = issuedAt.add({ seconds: ttlSeconds });
 
   // The unique index allows one row per (tenantId, email). Whatever its
   // status, a re-invite resets it to pending with a fresh token.
@@ -233,6 +234,8 @@ async function issueInvitation(
       appUrl: opts.appUrl,
       token,
       expiresAt: expiresAt.toString(),
+      issuedAt: issuedAt.toString(),
+      timeZone: ctx.tz.user,
       ...(opts.appName !== undefined && { appName: opts.appName }),
       locale,
     },

package/packages/bundled-features/src/auth-email-password/handlers/signup-request.write.ts

@@ -150,7 +150,8 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
       // session tokens.
       const token = generateToken();
 
-      const expiresAt = Temporal.Now.instant().add({ seconds: ttlSeconds });
+      const issuedAt = Temporal.Now.instant();
+      const expiresAt = issuedAt.add({ seconds: ttlSeconds });
       const expiresAtIso = expiresAt.toString();
 
       await storeSignupToken(ctx.redis, { email, token, ttlSeconds });
@@ -211,6 +212,8 @@ export function createSignupRequestHandler(opts: SignupRequestOptions) {
           appUrl: opts.appUrl,
           token,
           expiresAt: expiresAtIso,
+          issuedAt: issuedAt.toString(),
+          timeZone: ctx.tz.user,
           ...(opts.appName !== undefined && { appName: opts.appName }),
           locale,
         },

package/packages/bundled-features/src/auth-email-password/handlers/token-request-handler.ts

@@ -137,6 +137,7 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
       }
 
       const { token, expiresAt } = spec.sign(user.id, ttl, opts.hmacSecret);
+      const issuedAt = expiresAt.subtract({ minutes: ttl }).toString();
 
       const locale = resolveHandlerMailLocale(ctx, opts.locale);
 
@@ -154,6 +155,8 @@ export function createTokenRequestHandler<TName extends string, TSuccessKind ext
           appUrl: opts.appUrl,
           token,
           expiresAt: expiresAt.toString(),
+          issuedAt,
+          timeZone: ctx.tz.user,
           ...(opts.appName !== undefined && { appName: opts.appName }),
           locale,
         },

package/packages/bundled-features/src/auth-email-password/magic-link-mail.ts

@@ -34,6 +34,8 @@ export type MagicLinkMailParams = {
   readonly expiresAt: string;
   readonly appName?: string;
   readonly locale?: AuthMailLocale;
+  readonly issuedAt?: string;
+  readonly timeZone?: string;
 };
 
 function resolveAppUrl(appUrl: string | ((locale: string) => string), locale: string): string {
@@ -78,6 +80,8 @@ export async function dispatchMagicLinkMail(
     expiresAt: params.expiresAt,
     ...(params.locale !== undefined && { locale: params.locale }),
     ...(params.appName !== undefined && { appName: params.appName }),
+    ...(params.issuedAt !== undefined && { issuedAt: params.issuedAt }),
+    ...(params.timeZone !== undefined && { timeZone: params.timeZone }),
   });
   await notify(spec.notificationType, {
     route: { email: params.email },