better-ship 0.4.1 → 0.6.0

package/src/core/error-table.ts

@@ -0,0 +1,188 @@
+import { panic } from 'better-result'
+import { z } from 'zod'
+
+import { AppError } from './app-error.ts'
+import { AuthenticationError } from './authentication.error.ts'
+import { InternalServerError, ServiceUnavailableError } from './internal.errors.ts'
+import { NotAuthorizedError } from './not-authorized.error.ts'
+import { ValidationProblemErrorSchema } from './problem-details.ts'
+import { RateLimitError } from './rate-limit.error.ts'
+import {
+  MalformedRequestError,
+  RequestTimeoutError,
+  ResourceNotFoundError,
+  UpgradeRequiredError,
+  ValidationError,
+} from './request.errors.ts'
+import { StaleSessionError } from './stale-session.error.ts'
+
+type PublicFields = z.ZodObject
+
+/**
+ * One public error: its class, its HTTP status, and the extra properties a client may read.
+ * `fields` strips the thrown error on the server and parses the payload in the browser.
+ */
+export type ErrorEntry<Tag extends string, Fields extends PublicFields = PublicFields> = {
+  readonly error: abstract new (...args: never[]) => AppError & { readonly _tag: Tag }
+  readonly status: number
+  readonly fields?: Fields
+}
+
+type AnyErrorEntry = ErrorEntry<string>
+
+/** Entries keyed by tag. The compiler rejects a key that differs from the class's `_tag`. */
+export type ErrorEntries<Entries> = {
+  readonly [Tag in keyof Entries & string]: ErrorEntry<Tag>
+}
+
+type EntryPayload<Tag extends string, Entry> = Entry extends {
+  readonly fields: infer Fields extends z.ZodType
+}
+  ? { readonly _tag: Tag; readonly message: string } & z.output<Fields>
+  : { readonly _tag: Tag; readonly message: string }
+
+type PayloadOfEntries<Entries> = {
+  [Tag in keyof Entries & string]: EntryPayload<Tag, Entries[Tag]>
+}[keyof Entries & string]
+
+/** The HTTP status and public payload for one resolved failure. */
+export type ResolvedError<Payload> = {
+  readonly status: number
+  readonly payload: Payload
+}
+
+/**
+ * One application's public errors, shared by every transport boundary and the browser.
+ * `resolve` and `fallback` serve boundaries. `parse` and `generic` serve screens.
+ */
+export type ErrorTable<Entries> = {
+  readonly entries: Entries
+  /** The discriminated union of every entry's `_tag`, `message`, and fields. */
+  readonly payloadSchema: z.ZodType<PayloadOfEntries<Entries>>
+  /** The `InternalServerError` payload, for screens that must show something. */
+  readonly generic: PayloadOfEntries<Entries>
+  /** Read a rejection value. Null means no known tag, so the request never reached the Worker. */
+  parse(cause: unknown): PayloadOfEntries<Entries> | null
+  /** Narrow a rejection value to one tag's payload, for a caller that acts on that one error. */
+  is<Tag extends keyof Entries & string>(
+    cause: unknown,
+    tag: Tag,
+  ): cause is Extract<PayloadOfEntries<Entries>, { readonly _tag: Tag }>
+  /** Match a local instance or a remote error by tag. Null means the failure is not public. */
+  resolve(cause: unknown): ResolvedError<PayloadOfEntries<Entries>> | null
+  /** The replacement for an unmapped failure: 503 when it declared itself transient, else 500. */
+  fallback(cause: unknown): ResolvedError<PayloadOfEntries<Entries>>
+}
+
+/** The union of payloads a table can produce. */
+export type ErrorPayloadOf<Table> =
+  Table extends ErrorTable<infer Entries> ? PayloadOfEntries<Entries> : never
+
+/** The union of tags a table contains. */
+export type ErrorTagOf<Table> =
+  Table extends ErrorTable<infer Entries> ? keyof Entries & string : never
+
+function entriesOf<const Entries extends ErrorEntries<Entries>>(entries: Entries): Entries {
+  return entries
+}
+
+const ValidationFields = z.object({ errors: z.array(ValidationProblemErrorSchema) })
+const RateLimitFields = z.object({ retryAfter: z.number().nullable() })
+
+/** The errors every application can throw, with their statuses. `defineErrors` includes them. */
+export const sharedErrors = entriesOf({
+  MalformedRequestError: { error: MalformedRequestError, status: 400 },
+  AuthenticationError: { error: AuthenticationError, status: 401 },
+  StaleSessionError: { error: StaleSessionError, status: 401 },
+  NotAuthorizedError: { error: NotAuthorizedError, status: 403 },
+  ResourceNotFoundError: { error: ResourceNotFoundError, status: 404 },
+  ValidationError: { error: ValidationError, status: 422, fields: ValidationFields },
+  UpgradeRequiredError: { error: UpgradeRequiredError, status: 426 },
+  RateLimitError: { error: RateLimitError, status: 429, fields: RateLimitFields },
+  InternalServerError: { error: InternalServerError, status: 500 },
+  ServiceUnavailableError: { error: ServiceUnavailableError, status: 503 },
+  RequestTimeoutError: { error: RequestTimeoutError, status: 504 },
+})
+
+type MergedEntries<Entries> = Omit<typeof sharedErrors, keyof Entries> & Entries
+
+// Workers RPC drops the prototype but keeps own properties and marks the error as remote.
+const RemoteErrorSchema = z.object({
+  _tag: z.string(),
+  message: z.string(),
+  remote: z.literal(true),
+})
+
+type Match = { readonly tag: string; readonly entry: AnyErrorEntry; readonly error: Error }
+
+function match(byTag: ReadonlyMap<string, AnyErrorEntry>, cause: unknown): Match | null {
+  if (cause instanceof AppError) {
+    const entry = byTag.get(cause._tag)
+    if (entry === undefined || !(cause instanceof entry.error)) return null
+    return { tag: cause._tag, entry, error: cause }
+  }
+  if (!(cause instanceof Error)) return null
+  const remote = RemoteErrorSchema.safeParse(cause)
+  if (!remote.success) return null
+  const entry = byTag.get(remote.data._tag)
+  return entry === undefined ? null : { tag: remote.data._tag, entry, error: cause }
+}
+
+/**
+ * Build the application's error table. The shared entries are always included;
+ * an entry with the same key replaces the shared one.
+ */
+export function defineErrors<const Entries extends ErrorEntries<Entries>>(
+  entries: Entries,
+): ErrorTable<MergedEntries<Entries>> {
+  type Payload = PayloadOfEntries<MergedEntries<Entries>>
+  const merged = { ...sharedErrors, ...entries }
+  const byTag: ReadonlyMap<string, AnyErrorEntry> = new Map(Object.entries<AnyErrorEntry>(merged))
+
+  const resolve = (cause: unknown): ResolvedError<Payload> | null => {
+    const found = match(byTag, cause)
+    if (found === null) return null
+    const fields = found.entry.fields?.safeParse(found.error)
+    if (fields !== undefined && !fields.success) return null
+    // SAFETY: The entry's own `fields` schema produced these properties, so the payload has the shape declared for this tag.
+    const payload = { _tag: found.tag, message: found.error.message, ...fields?.data } as Payload
+    return { status: found.entry.status, payload }
+  }
+
+  const resolveShared = (error: AppError): ResolvedError<Payload> =>
+    resolve(error) ?? panic(`Error table cannot resolve shared error ${error._tag}`)
+  const generic = resolveShared(new InternalServerError())
+  const unavailable = resolveShared(new ServiceUnavailableError())
+
+  const variants = [...byTag].map(([tag, entry]) =>
+    // oxlint-disable-next-line anti-slop/no-shape-in-symbol-names -- Zod names an object schema's property map `shape`.
+    z.strictObject({ _tag: z.literal(tag), message: z.string(), ...entry.fields?.shape }),
+  )
+  const [first, ...rest] = variants
+  if (first === undefined) return panic('Error table has no entries')
+  // Each variant is one entry's `_tag`, `message`, and fields, which is the union `PayloadOfEntries` describes.
+  const payloadSchema = z.discriminatedUnion('_tag', [first, ...rest]).pipe(z.custom<Payload>())
+
+  // No return annotation: TypeScript resolves the deferred payload union differently in that position.
+  const parse = (cause: unknown) => {
+    const parsed = payloadSchema.safeParse(cause)
+    return parsed.success ? parsed.data : null
+  }
+
+  return {
+    entries: merged,
+    payloadSchema,
+    generic: generic.payload,
+    parse,
+    is<Tag extends keyof MergedEntries<Entries> & string>(
+      cause: unknown,
+      tag: Tag,
+    ): cause is Extract<Payload, { readonly _tag: Tag }> {
+      const parsed = parse(cause)
+      return parsed !== null && parsed._tag === tag
+    },
+    resolve,
+    fallback: (cause) =>
+      cause instanceof AppError && cause.classification === 'transient' ? unavailable : generic,
+  }
+}

package/src/core/identity.ts

@@ -0,0 +1,29 @@
+import { v7 as uuidv7 } from 'uuid'
+import { z } from 'zod'
+
+/** A string only `create()` or `schema.parse()` of the same kind can produce. */
+export type Id<Brand extends string> = string & z.core.$brand<Brand>
+
+/** One id kind the application mints. `schema` parses untrusted input; `create` mints a uuid v7. */
+export type IdDefinition<Brand extends string> = {
+  readonly schema: z.core.$ZodBranded<z.ZodUUID, Brand>
+  /** Mint a new time-ordered id. No parse: we produced it, so it is valid by construction. */
+  create(): Id<Brand>
+}
+
+/** The id type of a definition: `type CallId = IdOf<typeof CallId>`. */
+export type IdOf<Definition extends IdDefinition<string>> = z.output<Definition['schema']>
+
+/**
+ * Define an id kind the application mints: `export const CallId = defineId('CallId')`.
+ * An id another system mints, such as a provider's call id, stays a plain branded schema.
+ */
+export function defineId<const Brand extends string>(brand: Brand): IdDefinition<Brand> {
+  const schema = z.uuidv7({ error: `Invalid ${brand}` })
+  return {
+    // SAFETY: `brand()` is type-only and returns a conditional TypeScript cannot reduce for a generic brand; for every literal it is this branded schema.
+    schema: schema.brand<Brand>() as z.core.$ZodBranded<z.ZodUUID, Brand>,
+    // SAFETY: uuidv7() always yields a valid v7 uuid, and the brand is a compile-time mark only.
+    create: () => uuidv7() as Id<Brand>,
+  }
+}

package/src/core/index.ts

@@ -1,6 +1,56 @@
 export { AppError } from './app-error.ts'
+export { AuthenticationError } from './authentication.error.ts'
+export { RateLimitError } from './rate-limit.error.ts'
+export { StaleSessionError } from './stale-session.error.ts'
+export { NotAuthorizedError } from './not-authorized.error.ts'
+export { InternalServerError, ServiceUnavailableError } from './internal.errors.ts'
+export {
+  ValidationError,
+  MalformedRequestError,
+  ResourceNotFoundError,
+  UpgradeRequiredError,
+  RequestTimeoutError,
+  type ValidationIssue,
+} from './request.errors.ts'
+export {
+  defineErrors,
+  sharedErrors,
+  type ErrorEntries,
+  type ErrorEntry,
+  type ErrorPayloadOf,
+  type ErrorTable,
+  type ErrorTagOf,
+  type ResolvedError,
+} from './error-table.ts'
+export {
+  ProblemDetailsSchema,
+  ValidationProblemErrorSchema,
+  ValidationProblemDetailsSchema,
+  type ProblemDetails,
+  type ValidationProblemError,
+  type ValidationProblemDetails,
+} from './problem-details.ts'
 export { DatabaseError, type DatabaseFailure, type D1ConstraintKind } from './database.error.ts'
 export { notImplemented, unreachable } from './defects.ts'
+export { defineId, type Id, type IdDefinition, type IdOf } from './identity.ts'
+export {
+  defineMessages,
+  type AppMessages,
+  type CommandOf,
+  type EventOf,
+  type MessageDefinition,
+  type MessageOf,
+  type PayloadSchemas,
+  type QueryOf,
+} from './define-messages.ts'
+export type {
+  DomainCommand,
+  DomainEvent,
+  DomainMessage,
+  DomainQuery,
+  MessageId,
+} from './messages.ts'
+export { Entity, type EntityData } from './entity.ts'
 export {
   shouldRetryFailure,
   type FailureClassification,

package/src/core/internal.errors.ts

@@ -0,0 +1,21 @@
+import { AppError } from './app-error.ts'
+
+/** Safe public replacement for an unknown failure, ported from Porte's internal.errors.ts. */
+export class InternalServerError extends AppError {
+  readonly _tag = 'InternalServerError'
+  readonly classification = 'unknown'
+
+  constructor() {
+    super('Something went wrong')
+  }
+}
+
+/** Safe public replacement for a classified transient failure. */
+export class ServiceUnavailableError extends AppError {
+  readonly _tag = 'ServiceUnavailableError'
+  readonly classification = 'transient'
+
+  constructor() {
+    super('Try again shortly')
+  }
+}

package/src/core/logger.ts

@@ -47,7 +47,8 @@ export type LogEntry = {
   readonly level: LogLevel
   readonly module: string
   readonly message: string
-  readonly data: ReadonlyArray<LogValue>
+  readonly details: LogFields
+  readonly userId?: string
   /** Present on `Logger.error` entries that carried an error. */
   readonly error?: SerializedError
 }
@@ -159,7 +160,7 @@ function prettyLine(entry: LogEntry): string {
 }
 
 /**
- * JSON format writes the entry object. Pretty format writes one line, then the data,
+ * JSON format writes the entry object. Pretty format writes one line, then the details,
  * the error, and the stack as separate console arguments.
  */
 export const consoleSink: LogSink = (entry) => {
@@ -170,14 +171,17 @@ export const consoleSink: LogSink = (entry) => {
     return
   }
   const line = prettyLine(entry)
+  const fields =
+    entry.userId === undefined ? entry.details : { ...entry.details, userId: entry.userId }
+  const details = Object.keys(fields).length === 0 ? [] : [fields]
   if (entry.error === undefined) {
-    write(line, ...entry.data)
+    write(line, ...details)
     return
   }
   // A stack inside an object prints as one quoted string; as its own argument it prints as lines.
   const { stack, ...error } = entry.error
-  if (stack === undefined) write(line, ...entry.data, error)
-  else write(line, ...entry.data, error, `\n${stack}`)
+  if (stack === undefined) write(line, ...details, error)
+  else write(line, ...details, error, `\n${stack}`)
 }
 
 let logSink: LogSink = consoleSink
@@ -259,37 +263,45 @@ export class Logger {
   private log(
     level: LogLevel,
     message: string,
-    data: ReadonlyArray<LogValue>,
+    details: LogFields,
     error?: SerializedError,
+    userId?: string,
   ): void {
     const threshold = this.config.level ?? settings.level
     if (threshold === 'OFF') return
     if (LOG_LEVELS.indexOf(level) < LOG_LEVELS.indexOf(threshold)) return
 
-    const entry = { timestamp: new Date().toISOString(), level, module: this.module, message, data }
+    let entry: LogEntry = {
+      timestamp: new Date().toISOString(),
+      level,
+      module: this.module,
+      message,
+      details,
+    }
+    if (userId !== undefined) entry = { ...entry, userId }
     logSink(error === undefined ? entry : { ...entry, error })
   }
 
   /** Write a debug log. */
-  debug(message: string, ...values: ReadonlyArray<LogValue>): void {
-    this.log(LogLevel.DEBUG, message, values)
+  debug(message: string, details: LogFields = {}): void {
+    this.log(LogLevel.DEBUG, message, details)
   }
 
   /** Write an information log. */
-  info(message: string, ...values: ReadonlyArray<LogValue>): void {
-    this.log(LogLevel.INFO, message, values)
+  info(message: string, details: LogFields = {}): void {
+    this.log(LogLevel.INFO, message, details)
   }
 
   /** Write a warning log. */
-  warn(message: string, ...values: ReadonlyArray<LogValue>): void {
-    this.log(LogLevel.WARN, message, values)
+  warn(message: string, details: LogFields = {}): void {
+    this.log(LogLevel.WARN, message, details)
   }
 
   /**
    * Write an error log and send the error to the configured hook.
    *
    * The details say which call this was, and the error says what went wrong
-   * inside it. The entry carries the details as data and the error beside them.
+   * inside it. Both the entry and the error hook receive the supplied user ID.
    */
   error(message: string, context: ErrorLogContext = {}): void {
     const details = context.details ?? {}
@@ -307,7 +319,7 @@ export class Logger {
       }
       error = { name: 'NonError', message: json }
     }
-    this.log(LogLevel.ERROR, message, context.details === undefined ? [] : [details], error)
+    this.log(LogLevel.ERROR, message, details, error, context.userId)
 
     if (errorHook !== null && thrown !== undefined) {
       errorHook({ error: thrown, distinctId: context.userId, context: details })

package/src/{application → core}/messages.ts

@@ -8,24 +8,24 @@
 export type MessageId = string
 
 /** An action to perform. One handler, returns a value. The product adds its payload. */
-export type Command<Name extends string = string> = {
+export type DomainCommand<Name extends string = string> = {
   readonly type: 'command'
   readonly name: Name
   readonly id: MessageId
 }
 
 /** A request for data. One handler, returns a value. No id: nothing claims a read. */
-export type Query<Name extends string = string> = {
+export type DomainQuery<Name extends string = string> = {
   readonly type: 'query'
   readonly name: Name
 }
 
 /** A fact that happened. Zero or more subscribers, returns nothing. The product adds its payload. */
-export type Event<Name extends string = string> = {
+export type DomainEvent<Name extends string = string> = {
   readonly type: 'event'
   readonly name: Name
   readonly id: MessageId
 }
 
 /** The routing fields the bus reads. `type` selects the table, `name` selects the slot. */
-export type Message = Command | Event | Query
+export type DomainMessage = DomainCommand | DomainEvent | DomainQuery

package/src/core/not-authorized.error.ts

@@ -0,0 +1,11 @@
+import { AppError } from './app-error.ts'
+
+/** The authenticated caller cannot perform this operation. Ported from Porte's auth.errors.ts. */
+export class NotAuthorizedError extends AppError {
+  readonly _tag = 'NotAuthorizedError'
+  readonly classification = 'terminal'
+
+  constructor() {
+    super('Not allowed')
+  }
+}

package/src/core/problem-details.ts

@@ -0,0 +1,57 @@
+import { z } from 'zod'
+
+/**
+ * The standard RFC 9457 body for a failed HTTP response.
+ * The HTTP response status remains authoritative; extensions may add problem-specific data.
+ * @see https://http.dev/problem-details
+ */
+export const ProblemDetailsSchema = z.looseObject({
+  /**
+   * Stable URI for the problem type; use `about:blank` when the HTTP status is sufficient.
+   * @example "about:blank"
+   */
+  type: z.string(),
+  /**
+   * Stable human-readable name for the problem type.
+   * @example "Service Unavailable"
+   */
+  title: z.string(),
+  /**
+   * Safe human-readable explanation for this occurrence; clients must not parse it.
+   * @example "The service is unavailable."
+   */
+  detail: z.string().optional(),
+  /**
+   * URI reference for this occurrence; omit it when no correlation resource exists.
+   * @example "/problems/occurrences/01K5F6Y7"
+   */
+  instance: z.string().optional(),
+})
+
+/** An RFC 9457 problem body for a failed HTTP response. */
+export type ProblemDetails = z.infer<typeof ProblemDetailsSchema>
+
+/** One invalid value in a `422` validation problem. */
+export const ValidationProblemErrorSchema = z.object({
+  /**
+   * Safe explanation of why this value is invalid.
+   * @example "Must be a positive integer."
+   */
+  detail: z.string(),
+  /**
+   * RFC 6901 JSON Pointer fragment for the invalid value.
+   * @example "#/age"
+   */
+  pointer: z.string().regex(/^#(?:\/(?:[^~]|~[01])*)*$/u),
+})
+
+/** One invalid value in a `422` validation problem. */
+export type ValidationProblemError = z.infer<typeof ValidationProblemErrorSchema>
+
+/** An RFC 9457 validation problem with one or more invalid content values. */
+export const ValidationProblemDetailsSchema = ProblemDetailsSchema.extend({
+  errors: z.array(ValidationProblemErrorSchema).min(1),
+})
+
+/** An RFC 9457 validation problem with one or more invalid content values. */
+export type ValidationProblemDetails = z.infer<typeof ValidationProblemDetailsSchema>

package/src/core/rate-limit.error.ts

@@ -0,0 +1,12 @@
+import { AppError } from './app-error.ts'
+
+/** HTTP 429 with a retry delay in seconds. A null delay means the response supplies no valid duration. */
+export class RateLimitError extends AppError {
+  readonly _tag = 'RateLimitError'
+  readonly classification = 'transient'
+  readonly status = 429
+
+  constructor(readonly retryAfter: number | null) {
+    super('Too many requests')
+  }
+}

package/src/core/request.errors.ts

@@ -0,0 +1,86 @@
+import { z } from 'zod'
+
+import { AppError } from './app-error.ts'
+import type { ValidationProblemError } from './problem-details.ts'
+
+/** One invalid value as a validator reports it: a message and a path of keys. */
+export type ValidationIssue = {
+  readonly message: string
+  readonly path: readonly PropertyKey[]
+}
+
+/** Invalid user input, one entry per invalid value in the RFC 9457 shape. Technical failures use another error. */
+export class ValidationError extends AppError {
+  readonly _tag = 'ValidationError'
+  readonly classification = 'terminal'
+
+  constructor(
+    readonly errors: readonly ValidationProblemError[],
+    message = 'The request was not valid',
+  ) {
+    super(message)
+  }
+
+  /** Convert a Zod error. Each issue path becomes a JSON Pointer. */
+  static fromZod(error: z.ZodError, message?: string): ValidationError {
+    return ValidationError.fromIssues(error.issues, message)
+  }
+
+  /** Convert issues from any validator, such as issues TanStack serialized into an error message. */
+  static fromIssues(issues: readonly ValidationIssue[], message?: string): ValidationError {
+    return new ValidationError(
+      issues.map((issue) => ({ detail: issue.message, pointer: jsonPointer(issue.path) })),
+      message,
+    )
+  }
+}
+
+/** The server cannot parse the request syntax. */
+export class MalformedRequestError extends AppError {
+  readonly _tag = 'MalformedRequestError'
+  readonly classification = 'terminal'
+
+  constructor(args: { cause: unknown }) {
+    super('The request was malformed', args)
+  }
+}
+
+/** No resource matches the requested HTTP path. */
+export class ResourceNotFoundError extends AppError {
+  readonly _tag = 'ResourceNotFoundError'
+  readonly classification = 'terminal'
+
+  constructor() {
+    super('Resource not found')
+  }
+}
+
+/** A WebSocket route received a request without an upgrade. */
+export class UpgradeRequiredError extends AppError {
+  readonly _tag = 'UpgradeRequiredError'
+  readonly classification = 'terminal'
+
+  constructor() {
+    super('WebSocket upgrade required')
+  }
+}
+
+/** The requested operation did not answer before its deadline. */
+export class RequestTimeoutError extends AppError {
+  readonly _tag = 'RequestTimeoutError'
+  readonly classification = 'transient'
+
+  constructor() {
+    super('The request timed out')
+  }
+}
+
+const readablePathSchema = z.array(z.union([z.string(), z.number()]))
+
+// A symbol step cannot be shown, so the pointer keeps only the steps a person can read.
+function jsonPointer(path: readonly PropertyKey[]): string {
+  const parsed = readablePathSchema.safeParse(path)
+  const steps = parsed.success ? parsed.data : []
+  if (steps.length === 0) return '#'
+  return `#/${steps.map((step) => String(step).replaceAll('~', '~0').replaceAll('/', '~1')).join('/')}`
+}

package/src/core/stale-session.error.ts

@@ -0,0 +1,11 @@
+import { AppError } from './app-error.ts'
+
+/** A presented session cookie no longer resolves; the application owns cleanup and redirect policy. */
+export class StaleSessionError extends AppError {
+  readonly _tag = 'StaleSessionError'
+  readonly classification = 'terminal'
+
+  constructor() {
+    super('Session is no longer valid. Sign in again.')
+  }
+}

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

@@ -0,0 +1,54 @@
+import { importPKCS8, SignJWT } from 'jose'
+
+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 sends its OAuth callback from this origin. Include it in trustedOrigins when enabling Apple. */
+export const APPLE_ORIGIN = 'https://appleid.apple.com'
+
+/** Apple credentials used to sign a client secret. Ported from Porte's apple-client-secret.ts. */
+export type AppleKeyConfig = {
+  readonly appleClientId: string
+  readonly appleTeamId: string
+  readonly appleKeyId: string
+  readonly applePrivateKey: string
+}
+
+/** Apple signing failed. The application's error boundary owns reporting. */
+export class AppleClientSecretError extends AppError {
+  readonly _tag = 'AppleClientSecretError'
+  readonly classification = 'terminal'
+
+  constructor(cause: unknown) {
+    super('Apple client secret signing failed', { cause })
+  }
+}
+
+/** 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>>
+  try {
+    key = await importPKCS8(config.applePrivateKey.replace(/\\n/g, '\n'), 'ES256')
+  } catch (error) {
+    if (!appleKeyFailureLogged) {
+      appleKeyFailureLogged = true
+      logger.error('apple_private_key_invalid', { error, details: { keyId: config.appleKeyId } })
+    }
+    return ''
+  }
+  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)
+  } catch (cause) {
+    throw new AppleClientSecretError(cause)
+  }
+}