better-ship 0.8.0 → 0.11.0

package/dist/{unit-of-work-context-BWTJfYPW.d.ts → unit-of-work-context-BzmnjlDa.d.ts}

@@ -1,5 +1,5 @@
-import "./index-6XMPJu7u.js";
-import { o as IEventCollector } from "./index-_Cihfq1J.js";
+import "./index-Bl0K1RQW.js";
+import { w as IEventCollector } from "./index-DgDyeR5s.js";
 import { BatchItem } from "drizzle-orm/batch";
 //#region src/infrastructure/drizzle-schema.d.ts
 /**
@@ -13,4 +13,4 @@ type DrizzleSchema = Record<string, unknown>;
 declare const eventCollector: IEventCollector;
 //#endregion
 export { DrizzleSchema as n, eventCollector as t };
-//# sourceMappingURL=unit-of-work-context-BWTJfYPW.d.ts.map
+//# sourceMappingURL=unit-of-work-context-BzmnjlDa.d.ts.map

package/dist/{unit-of-work-context-BWTJfYPW.d.ts.map → unit-of-work-context-BzmnjlDa.d.ts.map}

@@ -1 +1 @@
-{"version":3,"file":"unit-of-work-context-BWTJfYPW.d.ts","names":[],"sources":["../src/infrastructure/drizzle-schema.ts","../src/infrastructure/unit-of-work-context.ts"],"mappings":";;;;;;;;KAKY,gBAAgB;;;;cCuBf,gBAAgB"}
+{"version":3,"file":"unit-of-work-context-BzmnjlDa.d.ts","names":[],"sources":["../src/infrastructure/drizzle-schema.ts","../src/infrastructure/unit-of-work-context.ts"],"mappings":";;;;;;;;KAKY,gBAAgB;;;;cCuBf,gBAAgB"}

package/dist/webhook-verification-BQ9qZnVK.js

@@ -0,0 +1,18 @@
+import { Q as AppError } from "./core-DG_cC8YT.js";
+
+//#region src/infrastructure/http/webhook-verification.ts
+/** A webhook cannot be trusted or parsed. The HTTP handler logs the rejection once. */
+var WebhookVerificationError = class extends AppError {
+	reason;
+	_tag = "WebhookVerificationError";
+	classification = "terminal";
+	/** Keep secrets and payload details out of the public message. */
+	constructor(reason, cause) {
+		super(`Webhook rejected: ${reason}`, { cause });
+		this.reason = reason;
+	}
+};
+
+//#endregion
+export { WebhookVerificationError as t };
+//# sourceMappingURL=webhook-verification-BQ9qZnVK.js.map

package/dist/webhook-verification-BQ9qZnVK.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-verification-BQ9qZnVK.js","names":[],"sources":["../src/infrastructure/http/webhook-verification.ts"],"sourcesContent":["import { AppError } from '@/core'\n\n/** A webhook cannot be trusted or parsed. The HTTP handler logs the rejection once. */\nexport class WebhookVerificationError extends AppError {\n  readonly _tag = 'WebhookVerificationError'\n  readonly classification = 'terminal'\n\n  /** Keep secrets and payload details out of the public message. */\n  constructor(\n    readonly reason: 'missing_headers' | 'invalid_signature' | 'invalid_payload',\n    cause?: unknown,\n  ) {\n    super(`Webhook rejected: ${reason}`, { cause })\n  }\n}\n\n/** A verified event, an ignored event, or an invalid request. */\nexport type WebhookVerification<Event> =\n  | { readonly outcome: 'event'; readonly event: Event }\n  | { readonly outcome: 'ignored'; readonly type: string }\n  | { readonly outcome: 'rejected'; readonly error: WebhookVerificationError }\n\n/** The provider owns signature verification, timestamp tolerance, and payload parsing. */\nexport interface WebhookVerifier<Event> {\n  /** Verify the exact body before parsing it. Return invalid requests; throw operational failures. */\n  verify(body: string, headers: Headers): Promise<WebhookVerification<Event>>\n}\n"],"mappings":";;;;AAGA,IAAa,2BAAb,cAA8C,SAAS;CAM1C;CALX,AAAS,OAAO;CAChB,AAAS,iBAAiB;;CAG1B,YACE,AAAS,QACT,OACA;EACA,MAAM,qBAAqB,UAAU,EAAE,MAAM,CAAC;EAHrC;CAIX;AACF"}

package/dist/webhook-verification-sZtwTI5n.d.ts

@@ -0,0 +1,29 @@
+import { Ut as AppError } from "./index-Bl0K1RQW.js";
+//#region src/infrastructure/http/webhook-verification.d.ts
+/** A webhook cannot be trusted or parsed. The HTTP handler logs the rejection once. */
+declare class WebhookVerificationError extends AppError {
+  readonly reason: 'missing_headers' | 'invalid_signature' | 'invalid_payload';
+  readonly _tag = "WebhookVerificationError";
+  readonly classification = "terminal";
+  /** Keep secrets and payload details out of the public message. */
+  constructor(reason: 'missing_headers' | 'invalid_signature' | 'invalid_payload', cause?: unknown);
+}
+/** A verified event, an ignored event, or an invalid request. */
+type WebhookVerification<Event> = {
+  readonly outcome: 'event';
+  readonly event: Event;
+} | {
+  readonly outcome: 'ignored';
+  readonly type: string;
+} | {
+  readonly outcome: 'rejected';
+  readonly error: WebhookVerificationError;
+};
+/** The provider owns signature verification, timestamp tolerance, and payload parsing. */
+interface WebhookVerifier<Event> {
+  /** Verify the exact body before parsing it. Return invalid requests; throw operational failures. */
+  verify(body: string, headers: Headers): Promise<WebhookVerification<Event>>;
+}
+//#endregion
+export { WebhookVerificationError as n, WebhookVerifier as r, WebhookVerification as t };
+//# sourceMappingURL=webhook-verification-sZtwTI5n.d.ts.map

package/dist/webhook-verification-sZtwTI5n.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook-verification-sZtwTI5n.d.ts","names":[],"sources":["../src/infrastructure/http/webhook-verification.ts"],"mappings":";;;cAGa,iCAAiC;WAMjC;WALF;WACA;;EAGT,YACW,qEACT;;;KAOQ,oBAAoB;WACjB;WAA2B,OAAO;;WAClC;WAA6B;;WAC7B;WAA8B,OAAO;;;UAGnC,gBAAgB;;EAE/B,OAAO,cAAc,SAAS,UAAU,QAAQ,oBAAoB"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://www.schemastore.org/package.json",
   "name": "better-ship",
-  "version": "0.8.0",
+  "version": "0.11.0",
   "description": "Foundation for applications on Cloudflare Workers: logger, errors, message bus, infrastructure adapters, and UI primitives",
   "license": "Apache-2.0",
   "repository": {
@@ -25,9 +25,13 @@
     "./cloudflare": "./dist/cloudflare.js",
     "./cloudflare/auth-secondary-storage": "./dist/cloudflare/auth-secondary-storage.js",
     "./cloudflare/queue": "./dist/cloudflare/queue.js",
+    "./cloudflare/scheduled": "./dist/cloudflare/scheduled.js",
     "./core": "./dist/core.js",
+    "./http": "./dist/http.js",
     "./postgres": "./dist/postgres.js",
+    "./resend": "./dist/resend.js",
     "./tanstack": "./dist/tanstack.js",
+    "./tanstack/server": "./dist/tanstack/server.js",
     "./ui": "./dist/ui.js",
     "./package.json": "./package.json"
   },
@@ -53,8 +57,9 @@
     "better-auth": "^1.7.4",
     "drizzle-kit": "^0.31.10",
     "drizzle-orm": "^0.45.2",
-    "jose": "^6.2.12",
     "postgres": "^3.4.9",
+    "resend": "^6.28.0",
+    "standardwebhooks": "^1.1.1",
     "stripe": "^22.6.2",
     "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
@@ -67,17 +72,17 @@
     "@tanstack/react-start": "^1.168.52",
     "better-auth": "^1.7.4",
     "drizzle-orm": "^0.45.2",
-    "jose": "^6.2.12",
+    "resend": "^6.28.0",
     "stripe": "^22.6.2"
   },
   "peerDependenciesMeta": {
-    "@better-auth/stripe": {
+    "resend": {
       "optional": true
     },
-    "stripe": {
+    "@better-auth/stripe": {
       "optional": true
     },
-    "jose": {
+    "stripe": {
       "optional": true
     },
     "better-auth": {

package/src/application/email-service.ts

@@ -0,0 +1,55 @@
+import type { EmailIdempotencyKey } from '@/core'
+
+/** A media type such as `application/pdf`. */
+export type MimeType = `${string}/${string}`
+
+/** A file to attach. Binary content is bytes; the adapter encodes it for the provider. */
+export type EmailAttachment = {
+  readonly filename: string
+  readonly content: string | Uint8Array
+  /** Optional MIME metadata; Resend accepts filename and content without it. */
+  readonly contentType?: MimeType
+}
+
+/**
+ * One transactional email. Resend accepts 50 recipients, 75 tags with ASCII names and values,
+ * and 40 MB of attachments after base64. Sources: https://resend.com/docs/api-reference/emails/send-email
+ * and https://resend.com/docs/dashboard/emails/tags
+ */
+export type OutboundEmail = {
+  readonly to: string | readonly string[]
+  readonly subject: string
+  readonly html: string
+  /** The stable identity of this send. Resend deduplicates it for 24 hours. */
+  readonly idempotencyKey: EmailIdempotencyKey
+  /** Resend generates plain text from html when omitted. An empty string disables that generation. */
+  readonly text?: string
+  readonly replyTo?: string
+  /** Labels the provider stores with the email and returns on every delivery event. */
+  readonly tags?: Readonly<Record<string, string>>
+  readonly attachments?: readonly EmailAttachment[]
+}
+
+/** The provider accepted the email and assigned its id. */
+export type EmailAccepted = { readonly providerId: string }
+
+/**
+ * The port a handler sends through. The adapter owns the sender address and the provider error mapping.
+ * A provider rejection throws `EmailServiceError`; unexpected SDK rejections propagate unchanged.
+ */
+export interface IEmailService {
+  /** Resolve after provider acceptance; this does not confirm delivery to the recipient. */
+  sendEmail(email: OutboundEmail): Promise<EmailAccepted>
+}
+
+/** Records every send for a test. Provider ids count up as `recorded-1`, `recorded-2`. */
+export class RecordingEmailService implements IEmailService {
+  /** Sends in call order, including repeated idempotency keys. */
+  readonly sent: OutboundEmail[] = []
+
+  /** Record the send before returning its provider id. */
+  async sendEmail(email: OutboundEmail): Promise<EmailAccepted> {
+    this.sent.push(email)
+    return { providerId: `recorded-${this.sent.length}` }
+  }
+}

package/src/application/index.ts

@@ -1,4 +1,20 @@
 export type { CommandHandler, EventHandler, QueryHandler } from './handlers.ts'
+export {
+  RecordingEmailService,
+  type IEmailService,
+  type OutboundEmail,
+  type EmailAttachment,
+  type MimeType,
+  type EmailAccepted,
+} from './email-service.ts'
+export {
+  recordEmailEvent,
+  type EmailBounceRecord,
+  type IEmailDeliverabilityStore,
+  type RecordEmailEventRepos,
+  type RecordEmailEventDeps,
+  type RecordEmailEventCommand,
+} from './record-email-event.ts'
 export type { IMessageStore } from './message-store.ts'
 export type { DomainCommand, DomainEvent, DomainMessage, DomainQuery, MessageId } from '@/core'
 export { MessageBus, type IMessageBus } from './message-bus.ts'

package/src/application/record-email-event.ts

@@ -0,0 +1,53 @@
+import type { BounceType, DomainCommand, EmailAddress, RecordEmailEventPayload } from '@/core'
+
+import type { IUnitOfWork } from './unit-of-work.ts'
+
+/** What a bounce records for one address. */
+export type EmailBounceRecord = {
+  readonly type: BounceType
+  readonly subType: string | null
+}
+
+/**
+ * The application's deliverability state per address. An implementation keeps the higher bounce
+ * severity with `shouldUpdateBounce`, and treats an unknown address as nothing to record.
+ */
+export interface IEmailDeliverabilityStore {
+  /** Keep the higher severity atomically. Equal severity permits replacement; the store owns timestamp ordering. */
+  recordBounce(address: EmailAddress, bounce: EmailBounceRecord): Promise<void>
+  /** Record a complaint without clearing existing suppression state. */
+  recordComplaint(address: EmailAddress): Promise<void>
+}
+
+/** The repositories the handler needs from the unit of work. */
+export type RecordEmailEventRepos = { readonly emailDeliverability: IEmailDeliverabilityStore }
+
+/** The container slice the handler reads. */
+export type RecordEmailEventDeps = { readonly uow: IUnitOfWork<RecordEmailEventRepos> }
+
+/** The command, under whatever name the application registered the payload. */
+export type RecordEmailEventCommand = DomainCommand & RecordEmailEventPayload
+
+/**
+ * Record a bounce or a complaint for every recipient inside the command's unit of work.
+ * The command id is the provider's event id, so a redelivered webhook is `MessageAlreadyProcessedError`.
+ */
+export async function recordEmailEvent(
+  command: RecordEmailEventCommand,
+  deps: RecordEmailEventDeps,
+): Promise<void> {
+  await deps.uow.run(command.id, async ({ emailDeliverability }) => {
+    for (const address of command.recipients) {
+      if (command.event.type === 'bounced') {
+        // oxlint-disable-next-line no-await-in-loop -- Finish each transaction write before starting another; a failure must leave no pending writes.
+        await emailDeliverability.recordBounce(address, {
+          type: command.event.bounceType,
+          subType: command.event.bounceSubType,
+        })
+      } else {
+        // oxlint-disable-next-line no-await-in-loop -- A rejected write must stop the transaction before another write starts.
+        await emailDeliverability.recordComplaint(address)
+      }
+    }
+  })
+}

package/src/core/email-address.ts

@@ -0,0 +1,7 @@
+import { z } from 'zod'
+
+/** A parsed email address for message payloads and webhook recipients. Ported from Typist's `EmailSchema`. */
+export const EmailAddressSchema = z.email().brand<'EmailAddress'>()
+
+/** An address the schema accepted. */
+export type EmailAddress = z.infer<typeof EmailAddressSchema>

package/src/core/email-deliverability.ts

@@ -0,0 +1,31 @@
+import { z } from 'zod'
+
+/** The bounce classes Resend reports, ported from Typist's comm-eligibility.ts. */
+export const BounceTypeSchema = z.enum(['Permanent', 'Transient', 'Undetermined'])
+
+/** One bounce class. */
+export type BounceType = z.infer<typeof BounceTypeSchema>
+
+/** Parse a provider's bounce type. An unknown value is `Undetermined`, which suppresses. */
+export function parseBounceType(value: string | undefined): BounceType {
+  const parsed = BounceTypeSchema.safeParse(value)
+  return parsed.success ? parsed.data : 'Undetermined'
+}
+
+const BOUNCE_SEVERITY = {
+  Transient: 1,
+  Undetermined: 2,
+  Permanent: 3,
+} satisfies Record<BounceType, number>
+
+/** Keep the higher severity. Equal severity permits replacement; callers own timestamp ordering. */
+export function shouldUpdateBounce(incoming: BounceType, current: BounceType | null): boolean {
+  if (current === null) return true
+  return BOUNCE_SEVERITY[incoming] >= BOUNCE_SEVERITY[current]
+}
+
+/** Typist's send policy: no complaint, and either no bounce or a transient one. Delivery is not guaranteed. */
+export function isEmailDeliverable(bounceType: BounceType | null, complained: boolean): boolean {
+  if (complained) return false
+  return bounceType === null || bounceType === 'Transient'
+}

package/src/core/email-idempotency-key.ts

@@ -0,0 +1,34 @@
+import type { z } from 'zod'
+
+import { AppError } from './app-error.ts'
+
+/** A key only `emailIdempotencyKey` mints, so every send carries one built by its rules. */
+export type EmailIdempotencyKey = string & z.core.$brand<'EmailIdempotencyKey'>
+
+// Resend accepts 1 to 256 characters. Source: https://resend.com/docs/dashboard/emails/idempotency-keys
+const MAX_KEY_LENGTH = 256
+
+/** A key outside 1 to 256 characters. Keys come from stable ids, so this is a defect, not a retry. */
+export class InvalidEmailIdempotencyKeyError extends AppError {
+  readonly _tag = 'InvalidEmailIdempotencyKeyError'
+  readonly classification = 'terminal'
+
+  constructor(readonly length: number) {
+    super(`Email idempotency key must have 1 to ${MAX_KEY_LENGTH} characters`)
+  }
+}
+
+/**
+ * `<scope>/<id>` for one logical send. Resend deduplicates it for 24 hours.
+ * Derive `id` from a stable identity: a message id, a job id, a user id with a template name.
+ * The same key must map to an identical payload; a changed body is rejected as terminal.
+ * A random `id` means every request is a deliberate new send, as a sign-in code resend is.
+ * Source: https://resend.com/docs/dashboard/emails/idempotency-keys
+ */
+export function emailIdempotencyKey(scope: string, id: string): EmailIdempotencyKey {
+  const key = `${scope}/${id}`
+  if (scope.length === 0 || id.length === 0 || key.length > MAX_KEY_LENGTH)
+    throw new InvalidEmailIdempotencyKeyError(key.length)
+  // SAFETY: the brand is a compile-time mark; the checks above are the whole rule.
+  return key as EmailIdempotencyKey
+}

package/src/core/email-service.error.ts

@@ -0,0 +1,51 @@
+import { AppError } from './app-error.ts'
+import type { FailureClassification } from './failure-classification.ts'
+
+/** Why the provider rejected a send. The reason owns the classification, so the two never disagree. */
+export type EmailSendFailureReason =
+  | 'rate_limited'
+  | 'idempotency_conflict'
+  | 'provider_error'
+  | 'quota_exceeded'
+  | 'invalid_request'
+  | 'configuration'
+
+const CLASSIFICATION_BY_REASON = {
+  rate_limited: 'transient',
+  idempotency_conflict: 'transient',
+  provider_error: 'transient',
+  quota_exceeded: 'terminal',
+  invalid_request: 'terminal',
+  configuration: 'terminal',
+} satisfies Record<EmailSendFailureReason, FailureClassification>
+
+/**
+ * The provider rejected a send. The boundary that awaited the send logs once; the adapter never does.
+ * `retryAfter` is the server's delay in seconds when it sent one, so `retryAfterSecondsOf` reads it.
+ */
+export class EmailServiceError extends AppError {
+  readonly _tag = 'EmailServiceError'
+  readonly classification: FailureClassification
+  readonly reason: EmailSendFailureReason
+  readonly provider: string
+  readonly providerCode: string
+  readonly statusCode: number | null
+  readonly retryAfter: number | null
+
+  constructor(args: {
+    readonly reason: EmailSendFailureReason
+    readonly provider: string
+    readonly providerCode: string
+    readonly statusCode: number | null
+    readonly retryAfter: number | null
+    readonly cause: unknown
+  }) {
+    super(`Email send failed: ${args.provider} ${args.providerCode}`, { cause: args.cause })
+    this.reason = args.reason
+    this.classification = CLASSIFICATION_BY_REASON[args.reason]
+    this.provider = args.provider
+    this.providerCode = args.providerCode
+    this.statusCode = args.statusCode
+    this.retryAfter = args.retryAfter
+  }
+}

package/src/core/index.ts

@@ -1,4 +1,22 @@
 export { AppError } from './app-error.ts'
+export { EmailAddressSchema, type EmailAddress } from './email-address.ts'
+export {
+  emailIdempotencyKey,
+  InvalidEmailIdempotencyKeyError,
+  type EmailIdempotencyKey,
+} from './email-idempotency-key.ts'
+export { EmailServiceError, type EmailSendFailureReason } from './email-service.error.ts'
+export {
+  BounceTypeSchema,
+  parseBounceType,
+  shouldUpdateBounce,
+  isEmailDeliverable,
+  type BounceType,
+} from './email-deliverability.ts'
+export {
+  RecordEmailEventPayloadSchema,
+  type RecordEmailEventPayload,
+} from './record-email-event.ts'
 export { AuthenticationError } from './authentication.error.ts'
 export { RateLimitError } from './rate-limit.error.ts'
 export { StaleSessionError } from './stale-session.error.ts'

package/src/core/record-email-event.ts

@@ -0,0 +1,23 @@
+import { z } from 'zod'
+
+import { EmailAddressSchema } from './email-address.ts'
+import { BounceTypeSchema } from './email-deliverability.ts'
+
+/**
+ * The payload of the command an application registers to record a bounce or a complaint.
+ * Register it under a name of the application's choice in `defineMessages`; `recordEmailEvent` handles it.
+ */
+export const RecordEmailEventPayloadSchema = z.object({
+  recipients: z.array(EmailAddressSchema).min(1),
+  event: z.discriminatedUnion('type', [
+    z.object({
+      type: z.literal('bounced'),
+      bounceType: BounceTypeSchema,
+      bounceSubType: z.string().nullable(),
+    }),
+    z.object({ type: z.literal('complained') }),
+  ]),
+})
+
+/** A parsed payload. */
+export type RecordEmailEventPayload = z.infer<typeof RecordEmailEventPayloadSchema>

package/src/infrastructure/better-auth/apple-client-secret.ts

@@ -1,12 +1,21 @@
-import { importPKCS8, SignJWT } from 'jose'
+import { Buffer } from 'node:buffer'
+import { createPrivateKey, sign } from 'node:crypto'
 
 import { AppError, createLogger } from '@/core'
 
 const logger = createLogger('auth')
 // Typist reports an invalid key once per isolate because session checks repeatedly construct auth options.
 let appleKeyFailureLogged = false
+/**
+ * Apple caps `exp` at 15,777,000 seconds after `iat`; 180 days stays under it. Source:
+ * https://developer.apple.com/documentation/accountorganizationaldatasharing/creating-a-client-secret
+ */
+const SECRET_LIFETIME_SECONDS = 180 * 24 * 60 * 60
 
-/** Apple sends its OAuth callback from this origin. Include it in trustedOrigins when enabling Apple. */
+/**
+ * Apple's issuer and OAuth callback origin, and the `aud` claim of the client secret. Include it in
+ * trustedOrigins when enabling Apple. Source: the same Apple page as `SECRET_LIFETIME_SECONDS`.
+ */
 export const APPLE_ORIGIN = 'https://appleid.apple.com'
 
 /** Apple credentials used to sign a client secret. Ported from Porte's apple-client-secret.ts. */
@@ -27,11 +36,23 @@ export class AppleClientSecretError extends AppError {
   }
 }
 
-/** Sign Apple's six-month client secret. Invalid private keys return an empty secret and log once per isolate, as in Typist. */
-export async function generateAppleClientSecret(config: AppleKeyConfig): Promise<string> {
-  let key: Awaited<ReturnType<typeof importPKCS8>>
+/** One JWS segment before encoding: the protected header or the claims. */
+type JwsSegment = Readonly<Record<string, string | number>>
+
+function base64UrlJson(segment: JwsSegment): string {
+  return Buffer.from(JSON.stringify(segment)).toString('base64url')
+}
+
+/**
+ * Sign Apple's six-month client secret synchronously, so Better Auth options can be built without awaiting it.
+ * Signing uses `node:crypto` as Typist does, so the Worker needs the `nodejs_compat` flag.
+ * Invalid private keys return an empty secret and log once per isolate, as in Typist.
+ */
+export function generateAppleClientSecret(config: AppleKeyConfig): string {
+  const key = config.applePrivateKey.replace(/\\n/g, '\n')
+  // Validation only: workerd's sign() takes the PEM string, not the KeyObject.
   try {
-    key = await importPKCS8(config.applePrivateKey.replace(/\\n/g, '\n'), 'ES256')
+    createPrivateKey(key)
   } catch (error) {
     if (!appleKeyFailureLogged) {
       appleKeyFailureLogged = true
@@ -39,15 +60,21 @@ export async function generateAppleClientSecret(config: AppleKeyConfig): Promise
     }
     return ''
   }
+  const issuedAt = Math.floor(Date.now() / 1000)
+  const header = base64UrlJson({ alg: 'ES256', kid: config.appleKeyId })
+  const claims = base64UrlJson({
+    iss: config.appleTeamId,
+    sub: config.appleClientId,
+    aud: APPLE_ORIGIN,
+    iat: issuedAt,
+    exp: issuedAt + SECRET_LIFETIME_SECONDS,
+  })
+  const input = `${header}.${claims}`
   try {
-    return await new SignJWT({})
-      .setProtectedHeader({ alg: 'ES256', kid: config.appleKeyId })
-      .setIssuer(config.appleTeamId)
-      .setSubject(config.appleClientId)
-      .setAudience(APPLE_ORIGIN)
-      .setIssuedAt()
-      .setExpirationTime('180d')
-      .sign(key)
+    // A JWS carries the raw r||s signature; OpenSSL emits DER unless told otherwise.
+    const signature = sign('sha256', Buffer.from(input), { key, dsaEncoding: 'ieee-p1363' })
+    // TypeScript 7 types the returned buffer without an encoding parameter on toString.
+    return `${input}.${Buffer.from(signature).toString('base64url')}`
   } catch (cause) {
     throw new AppleClientSecretError(cause)
   }

package/src/infrastructure/better-auth/rate-limit.ts

@@ -1,7 +1,13 @@
-import type { BetterAuthRateLimitStorage } from 'better-auth'
+import type { BetterAuthOptions, BetterAuthRateLimitStorage } from 'better-auth'
 
 import { AppError, createLogger } from '@/core'
 
+/** A rule Better Auth passes to storage: a window in seconds and the requests it allows. */
+export type AuthRateLimitRule = {
+  readonly window: number
+  readonly max: number
+}
+
 /** Each rule must match its binding's deployed limit and period. Cloudflare accepts only 10 or 60 seconds. */
 export type AuthRateLimitBinding = {
   readonly binding: Pick<RateLimit, 'limit'>
@@ -9,6 +15,43 @@ export type AuthRateLimitBinding = {
   readonly max: number
 }
 
+/**
+ * Better Auth's built-in rules, which it does not export. Sign-in, sign-up, change-password, and
+ * change-email paths get 3 requests per 10 seconds. Password reset, verification email, forget-password,
+ * and email OTP send paths get 3 per 60 seconds. A package test pins both against the installed version.
+ * Source: `getDefaultSpecialRules` in
+ * https://github.com/better-auth/better-auth/blob/v1.7.4/packages/better-auth/src/api/rate-limiter/index.ts
+ */
+export const BUILT_IN_AUTH_RATE_LIMIT_RULES: readonly AuthRateLimitRule[] = [
+  { window: 10, max: 3 },
+  { window: 60, max: 3 },
+]
+
+/**
+ * Every rule the configured instance can pass to storage, deduplicated: the general rule, the built-in
+ * rules, each plugin's rules, and static custom rules. Function-valued custom rules decide per request
+ * and are not listed. Disabled rate limiting returns no rules.
+ */
+export function authRateLimitRules(
+  options: Pick<BetterAuthOptions, 'rateLimit' | 'plugins'>,
+): readonly AuthRateLimitRule[] {
+  const rateLimit = options.rateLimit
+  if (rateLimit?.enabled === false) return []
+  // Better Auth's own defaults when the general rule is not set: window 10, max 100. Source:
+  // https://github.com/better-auth/better-auth/blob/v1.7.4/packages/better-auth/src/context/create-context.ts
+  const rules: AuthRateLimitRule[] = [
+    { window: rateLimit?.window ?? 10, max: rateLimit?.max ?? 100 },
+    ...BUILT_IN_AUTH_RATE_LIMIT_RULES,
+  ]
+  for (const plugin of options.plugins ?? [])
+    for (const rule of plugin.rateLimit ?? []) rules.push({ window: rule.window, max: rule.max })
+  for (const rule of Object.values(rateLimit?.customRules ?? {}))
+    if (rule !== false && !(rule instanceof Function))
+      rules.push({ window: rule.window, max: rule.max })
+  const unique = new Map(rules.map((rule) => [`${rule.window}:${rule.max}`, rule]))
+  return [...unique.values()]
+}
+
 /** A binding failure with no known retry classification. The cause preserves the original failure. */
 export class AuthRateLimitError extends AppError {
   readonly _tag = 'AuthRateLimitError'

package/src/infrastructure/cloudflare/scheduled/index.ts

@@ -0,0 +1,8 @@
+export {
+  defineSchedules,
+  scheduledMessageId,
+  type AppSchedules,
+  type ScheduledHandler,
+  type ScheduledRun,
+  type ScheduleExpression,
+} from './scheduled-handler.ts'

package/src/infrastructure/cloudflare/scheduled/scheduled-handler.ts

@@ -0,0 +1,62 @@
+import { z } from 'zod'
+
+import { createLogger, type MessageId } from '@/core'
+
+const logger = createLogger('scheduled')
+
+/** The work one schedule runs. Nothing returns to the platform, so each run reports its own outcome. */
+export type ScheduledRun<Deps> = (deps: Deps, at: Date) => Promise<void>
+
+/** The cron expressions of a schedule map, as literal types. */
+export type ScheduleExpression<Schedules extends Readonly<Record<string, string>>> =
+  Schedules[keyof Schedules]
+
+/** The Cloudflare `scheduled` export, with the application's dependencies as its second argument. */
+export type ScheduledHandler<Deps> = (controller: ScheduledController, deps: Deps) => Promise<void>
+
+/** What `defineSchedules` returns: the map, its parser, and the handler factory. */
+export type AppSchedules<Schedules extends Readonly<Record<string, string>>> = {
+  readonly schedules: Schedules
+  /** Parses `controller.cron`, a bare string from the platform, into a known expression. */
+  readonly schema: z.ZodType<ScheduleExpression<Schedules>>
+  /**
+   * Route each schedule to its work. One run per expression, so a schedule added without
+   * work fails to compile. An expression Wrangler fires that the map does not know is logged
+   * once and ignored. A run that throws rejects, so Cloudflare marks the invocation failed.
+   */
+  handler<Deps>(
+    runs: Readonly<Record<ScheduleExpression<Schedules>, ScheduledRun<Deps>>>,
+  ): ScheduledHandler<Deps>
+}
+
+/**
+ * Define the application's schedules once: `EVERY_MINUTE: '* * * * *'`. Keys name the time,
+ * not the work, because one schedule may drive several commands. Wrangler's `triggers.crons`
+ * must hold exactly these expressions. Cron does not retry: a run that sweeps many items
+ * catches each item's failure itself.
+ */
+export function defineSchedules<const Schedules extends Readonly<Record<string, string>>>(
+  schedules: Schedules,
+): AppSchedules<Schedules> {
+  const schema = z.enum(schedules)
+  return {
+    schedules,
+    schema,
+    handler: (runs) => async (controller, deps) => {
+      const { cron } = controller
+      if (!schema.validate(cron)) {
+        logger.error('scheduled_unknown_cron', { details: { cron } })
+        return
+      }
+      await runs[cron](deps, new Date(controller.scheduledTime))
+    },
+  }
+}
+
+/**
+ * The id of a command a schedule issues: `cron:<Name>:<scheduledTime>`. A doubled trigger for
+ * the same time is then a duplicate by construction, and the unit of work skips it.
+ */
+export function scheduledMessageId(name: string, at: Date): MessageId {
+  return `cron:${name}:${String(at.getTime())}`
+}