@avelonjs/conformance 0.1.0

package/src/fakes/identity.ts

@@ -0,0 +1,253 @@
+import {
+  Conflict,
+  Invalid,
+  Unauthenticated,
+  type IdentityDriver,
+  type IdentityOrganization,
+  type MagicLinkIdentitySurface,
+  type MfaChallenge,
+  type MfaIdentitySurface,
+  type OAuthIdentitySurface,
+  type OrganizationIdentitySurface,
+  type PasswordIdentitySurface,
+  type RequestCookies,
+} from '@avelonjs/core'
+
+const capabilities = {
+  passwords: true,
+  magicLinks: true,
+  oauth: true,
+  organizations: true,
+  mfa: ['totp', 'recovery'] as const,
+} as const
+
+type Factor = (typeof capabilities.mfa)[number]
+
+/** Actor returned by the in-memory identity implementation. */
+export interface FakeIdentityActor {
+  /** Stable actor identifier. */
+  id: string
+  /** Sign-in address. */
+  email: string
+}
+
+/** Session returned by the in-memory identity implementation. */
+export interface FakeIdentitySession {
+  /** Stable session identifier. */
+  id: string
+  /** Authenticated actor identifier. */
+  actorId: string
+  /** Time after which the session is invalid. */
+  expiresAt: Date
+}
+
+interface StoredActor extends FakeIdentityActor {
+  password: string
+}
+
+interface StoredSession extends FakeIdentitySession {
+  active: boolean
+}
+
+interface FakeIdentityRaw {
+  users: number
+  sessions: number
+}
+
+const sessionCookie = 'avelon_assay_session'
+
+function unauthenticated(message: string): Unauthenticated {
+  return new Unauthenticated(message, { metadata: { guard: 'identity' } })
+}
+
+function invalid(field: string, message: string): Invalid {
+  return new Invalid(message, { metadata: { fields: { [field]: [message] } } })
+}
+
+function isFactor(value: string): value is Factor {
+  return capabilities.mfa.some((factor) => factor === value)
+}
+
+/** In-memory identity reference implementation used by conformance and application tests. */
+export class FakeIdentity
+  implements
+    IdentityDriver<typeof capabilities, FakeIdentityRaw, FakeIdentityActor, FakeIdentitySession>,
+    PasswordIdentitySurface<FakeIdentityActor>,
+    MagicLinkIdentitySurface,
+    OAuthIdentitySurface,
+    OrganizationIdentitySurface,
+    MfaIdentitySurface<Factor>
+{
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured identity connection name. */
+  readonly instance = 'default'
+
+  /** Exact optional-feature declaration. */
+  readonly capabilities = capabilities
+
+  readonly #cookies: RequestCookies
+  readonly #actors = new Map<string, StoredActor>()
+  readonly #sessions = new Map<string, StoredSession>()
+  readonly #resetTokens = new Map<string, string>()
+  readonly #challenges = new Map<string, { actorId: string; challenge: MfaChallenge<Factor> }>()
+  #lastSession: FakeIdentitySession | null = null
+  #nextActor = 1
+  #nextSession = 1
+  #nextChallenge = 1
+
+  /** Creates an identity driver bound to one request-scoped cookie store. */
+  constructor(cookies: RequestCookies) {
+    this.#cookies = cookies
+  }
+
+  /** Returns observable in-memory client counts. */
+  raw(): FakeIdentityRaw {
+    return { users: this.#actors.size, sessions: this.#sessions.size }
+  }
+
+  /** Returns the current actor or null for an anonymous request. */
+  async user(): Promise<FakeIdentityActor | null> {
+    const session = this.#currentSession()
+    if (!session) return null
+    const actor = [...this.#actors.values()].find((candidate) => candidate.id === session.actorId)
+    return actor ? { id: actor.id, email: actor.email } : null
+  }
+
+  /** Returns the current session or null when it is absent or expired. */
+  async session(): Promise<FakeIdentitySession | null> {
+    const session = this.#currentSession()
+    return session ? this.#copySession(session) : null
+  }
+
+  /** Ends the current session and deletes its request cookie. */
+  async signOut(): Promise<void> {
+    const session = this.#requireSession()
+    session.active = false
+    this.#cookies.delete(sessionCookie, { path: '/' })
+  }
+
+  /** Registers an actor without changing the current request session. */
+  async register(email: string, password: string): Promise<FakeIdentityActor> {
+    if (this.#actors.has(email)) {
+      throw new Conflict('An actor with this email already exists.', {
+        metadata: { resource: 'actor', key: 'email' },
+      })
+    }
+    const actor: StoredActor = { id: `actor-${this.#nextActor++}`, email, password }
+    this.#actors.set(email, actor)
+    return { id: actor.id, email: actor.email }
+  }
+
+  /** Authenticates an actor and writes a request-scoped session cookie. */
+  async signInWithPassword(email: string, password: string): Promise<FakeIdentityActor> {
+    const actor = this.#actors.get(email)
+    if (!actor || actor.password !== password) throw unauthenticated('Invalid credentials.')
+
+    const session: StoredSession = {
+      id: `session-${this.#nextSession++}`,
+      actorId: actor.id,
+      expiresAt: new Date(Date.now() + 60 * 60 * 1000),
+      active: true,
+    }
+    this.#sessions.set(session.id, session)
+    this.#lastSession = this.#copySession(session)
+    this.#cookies.set(sessionCookie, session.id, {
+      httpOnly: true,
+      maxAge: 60 * 60,
+      path: '/',
+      sameSite: 'lax',
+      secure: true,
+    })
+    return { id: actor.id, email: actor.email }
+  }
+
+  /** Records a deterministic recovery token for a known actor without revealing account absence. */
+  async sendPasswordReset(email: string): Promise<void> {
+    if (this.#actors.has(email)) this.#resetTokens.set('assay-reset-token', email)
+  }
+
+  /** Replaces a password after validating a recovery token. */
+  async resetPassword(token: string, password: string): Promise<void> {
+    const email = this.#resetTokens.get(token)
+    const actor = email ? this.#actors.get(email) : undefined
+    if (!email || !actor) throw unauthenticated('Invalid password recovery token.')
+    actor.password = password
+    this.#resetTokens.delete(token)
+  }
+
+  /** Changes the current actor's password. */
+  async updatePassword(password: string): Promise<void> {
+    const session = this.#requireSession()
+    const actor = [...this.#actors.values()].find((candidate) => candidate.id === session.actorId)
+    if (!actor) throw unauthenticated('The authenticated actor no longer exists.')
+    actor.password = password
+  }
+
+  /** Accepts a magic-link request without revealing account existence. */
+  async sendMagicLink(_email: string, _redirectTo?: string): Promise<void> {}
+
+  /** Links a completed authorization to the authenticated actor. */
+  async linkOAuthIdentity(_provider: string, _code: string): Promise<void> {
+    this.#requireSession()
+  }
+
+  /** Lists organizations available to the authenticated actor. */
+  async organizations(): Promise<readonly IdentityOrganization[]> {
+    this.#requireSession()
+    return [{ id: 'organization-1', name: 'Assay Organization' }]
+  }
+
+  /** Selects an organization available to the authenticated actor. */
+  async useOrganization(id: string): Promise<void> {
+    this.#requireSession()
+    if (id !== 'organization-1') throw invalid('organization', 'Unknown organization.')
+  }
+
+  /** Begins a challenge for one declared factor. */
+  async challengeMfa(factor?: string): Promise<MfaChallenge<Factor>> {
+    const session = this.#requireSession()
+    const selected = factor ?? capabilities.mfa[0]
+    if (!isFactor(selected)) throw invalid('factor', 'Unsupported multi-factor method.')
+    const challenge: MfaChallenge<Factor> = {
+      id: `challenge-${this.#nextChallenge++}`,
+      factor: selected,
+      expiresAt: new Date(Date.now() + 5 * 60 * 1000),
+    }
+    this.#challenges.set(challenge.id, { actorId: session.actorId, challenge })
+    return { ...challenge }
+  }
+
+  /** Verifies the deterministic code accepted by the in-memory implementation. */
+  async verifyMfa(challengeId: string, code: string): Promise<void> {
+    const pending = this.#challenges.get(challengeId)
+    if (!pending || pending.challenge.expiresAt.getTime() <= Date.now() || code !== '123456') {
+      throw unauthenticated('Invalid multi-factor challenge.')
+    }
+    this.#challenges.delete(challengeId)
+  }
+
+  /** Returns the last issued session for conformance stubs that model stale-session defects. */
+  protected lastIssuedSession(): FakeIdentitySession | null {
+    return this.#lastSession ? this.#copySession(this.#lastSession) : null
+  }
+
+  #copySession(session: FakeIdentitySession): FakeIdentitySession {
+    return { ...session, expiresAt: new Date(session.expiresAt) }
+  }
+
+  #currentSession(): StoredSession | null {
+    const id = this.#cookies.get(sessionCookie)
+    if (!id) return null
+    const session = this.#sessions.get(id)
+    if (!session || !session.active || session.expiresAt.getTime() <= Date.now()) return null
+    return session
+  }
+
+  #requireSession(): StoredSession {
+    const session = this.#currentSession()
+    if (!session) throw unauthenticated('An active session is required.')
+    return session
+  }
+}

package/src/fakes/logs.ts

@@ -0,0 +1,101 @@
+import { type LogDriver, type LogRecord, type TraceLogSurface, type TraceSpan } from '@avelonjs/core'
+
+const capabilities = { traces: true } as const
+
+/** Observable trace state retained by the in-memory logging reference implementation. */
+export interface FakeTraceRecord {
+  /** Trace operation name. */
+  readonly name: string
+  /** Stable trace identifier. */
+  readonly traceId: string
+  /** Stable span identifier. */
+  readonly spanId: string
+  /** Structured attributes attached to the span. */
+  readonly attributes: Record<string, string | number | boolean>
+  /** Errors recorded by the span. */
+  readonly errors: unknown[]
+  /** Whether the span has ended. */
+  ended: boolean
+}
+
+interface FakeLogsRaw {
+  readonly records: readonly LogRecord[]
+  readonly spans: readonly FakeTraceRecord[]
+}
+
+class FakeTraceSpan implements TraceSpan {
+  readonly traceId: string
+  readonly spanId: string
+  readonly #record: FakeTraceRecord
+
+  constructor(record: FakeTraceRecord) {
+    this.#record = record
+    this.traceId = record.traceId
+    this.spanId = record.spanId
+  }
+
+  attribute(name: string, value: string | number | boolean): void {
+    this.#record.attributes[name] = value
+  }
+
+  recordError(error: unknown): void {
+    this.#record.errors.push(error)
+  }
+
+  end(): void {
+    this.#record.ended = true
+  }
+}
+
+/** In-memory structured logging reference implementation with trace support. */
+export class FakeLogs implements LogDriver<typeof capabilities, FakeLogsRaw>, TraceLogSurface {
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured log connection name. */
+  readonly instance: string
+
+  /** Exact optional-feature declaration. */
+  readonly capabilities = capabilities
+
+  /** Structured records accepted by the fake sink. */
+  readonly records: LogRecord[] = []
+
+  /** Trace records accepted by the fake sink. */
+  readonly spans: FakeTraceRecord[] = []
+
+  #nextSpan = 1
+
+  /** Creates an isolated log connection. */
+  constructor(instance = 'default') {
+    this.instance = instance
+  }
+
+  /** Returns the observable fake sink. */
+  raw(): FakeLogsRaw {
+    return { records: this.records, spans: this.spans }
+  }
+
+  /** Writes one structured record and supplies its omitted timestamp. */
+  async write(record: LogRecord): Promise<void> {
+    this.records.push({ ...record, timestamp: record.timestamp ?? new Date() })
+  }
+
+  /** Starts an observable trace span. */
+  startSpan(
+    name: string,
+    attributes: Readonly<Record<string, string | number | boolean>> = {},
+  ): TraceSpan {
+    const sequence = this.#nextSpan++
+    const record: FakeTraceRecord = {
+      name,
+      traceId: `trace-${sequence}`,
+      spanId: `span-${sequence}`,
+      attributes: { ...attributes },
+      errors: [],
+      ended: false,
+    }
+    this.spans.push(record)
+    return new FakeTraceSpan(record)
+  }
+}

package/src/fakes/mail.ts

@@ -0,0 +1,140 @@
+import {
+  Invalid,
+  type MailAttachment,
+  type MailDriver,
+  type MailMessage,
+  type MailReceipt,
+  type TemplateMailSurface,
+} from '@avelonjs/core'
+
+const capabilities = {
+  templates: true,
+} as const
+
+interface FakeMailRaw {
+  messages: number
+  templates: number
+}
+
+interface TemplateDelivery {
+  template: string
+  to: string | readonly string[]
+  variables: Readonly<Record<string, unknown>>
+}
+
+function addressList(value: string | readonly string[] | undefined): readonly string[] {
+  if (value === undefined) return []
+  return typeof value === 'string' ? [value] : value
+}
+
+function validAddress(address: string): boolean {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(address)
+}
+
+function validateAddresses(message: MailMessage): void {
+  const fields: readonly [string, readonly string[]][] = [
+    ['to', addressList(message.to)],
+    ['from', addressList(message.from)],
+    ['replyTo', addressList(message.replyTo)],
+    ['cc', addressList(message.cc)],
+    ['bcc', addressList(message.bcc)],
+  ]
+  for (const [field, addresses] of fields) {
+    const malformed = addresses.find((address) => !validAddress(address))
+    if (malformed) {
+      throw new Invalid(`Invalid email address in ${field}.`, {
+        metadata: { fields: { [field]: [`${malformed} is not a valid email address.`] } },
+      })
+    }
+  }
+}
+
+function copyAddresses(value: string | readonly string[]): string | readonly string[] {
+  return typeof value === 'string' ? value : [...value]
+}
+
+function copyAttachments(
+  attachments: readonly MailAttachment[] | undefined,
+): readonly MailAttachment[] | undefined {
+  return attachments?.map((attachment) => ({
+    filename: attachment.filename,
+    content: attachment.content.slice(),
+    ...(attachment.contentType === undefined ? {} : { contentType: attachment.contentType }),
+  }))
+}
+
+function copyMessage(message: MailMessage, defaultFrom: string): MailMessage {
+  const attachments = copyAttachments(message.attachments)
+  return {
+    to: copyAddresses(message.to),
+    from: message.from ?? defaultFrom,
+    ...(message.replyTo === undefined ? {} : { replyTo: copyAddresses(message.replyTo) }),
+    ...(message.cc === undefined ? {} : { cc: [...message.cc] }),
+    ...(message.bcc === undefined ? {} : { bcc: [...message.bcc] }),
+    subject: message.subject,
+    ...(message.text === undefined ? {} : { text: message.text }),
+    ...(message.html === undefined ? {} : { html: message.html }),
+    ...(attachments === undefined ? {} : { attachments }),
+  }
+}
+
+/** In-memory mail reference implementation used by conformance and application tests. */
+export class FakeMail implements MailDriver<typeof capabilities, FakeMailRaw>, TemplateMailSurface {
+  /** Driver implementation name. */
+  readonly name = 'fake'
+
+  /** Configured mailer name. */
+  readonly instance: string
+
+  /** Exact optional-feature declaration. */
+  readonly capabilities = capabilities
+
+  readonly #defaultFrom: string
+  readonly #sent: MailMessage[] = []
+  readonly #templates: TemplateDelivery[] = []
+  #nextId = 1
+
+  /** Creates an isolated mailer with an instance-specific default sender. */
+  constructor(instance = 'default', defaultFrom = 'no-reply@example.test') {
+    this.instance = instance
+    this.#defaultFrom = defaultFrom
+  }
+
+  /** Returns copies of messages accepted by this fake mailer. */
+  get sent(): readonly MailMessage[] {
+    return this.#sent.map((message) => copyMessage(message, this.#defaultFrom))
+  }
+
+  /** Returns observable accepted-message and template counts. */
+  raw(): FakeMailRaw {
+    return { messages: this.#sent.length, templates: this.#templates.length }
+  }
+
+  /** Validates and records a transport-neutral message. */
+  async send(message: MailMessage): Promise<MailReceipt> {
+    const normalized = copyMessage(message, this.#defaultFrom)
+    validateAddresses(normalized)
+    this.#sent.push(normalized)
+    // Every to, cc, and bcc address is an envelope recipient; reply-to is intentionally excluded.
+    const accepted = [
+      ...addressList(normalized.to),
+      ...addressList(normalized.cc),
+      ...addressList(normalized.bcc),
+    ]
+    return { id: `message-${this.#nextId++}`, accepted }
+  }
+
+  /** Records a hosted-template delivery after validating all recipients. */
+  async sendTemplate(
+    template: string,
+    to: string | readonly string[],
+    variables: Readonly<Record<string, unknown>>,
+  ): Promise<MailReceipt> {
+    validateAddresses({ to, subject: template })
+    this.#templates.push({ template, to: copyAddresses(to), variables: { ...variables } })
+    return {
+      id: `message-${this.#nextId++}`,
+      accepted: [...addressList(to)],
+    }
+  }
+}

package/src/fakes/notifications.ts

@@ -0,0 +1,73 @@
+import {
+  Invalid,
+  type NotificationCapabilities,
+  type NotificationChannel,
+  type NotificationDriver,
+  type NotificationMessage,
+  type NotificationReceipt,
+} from '@avelonjs/core'
+
+/** One notification accepted by the in-memory reference implementation. */
+export interface FakeSentNotification {
+  /** Delivery channel used for the message. */
+  readonly channel: NotificationChannel
+  /** Message retained without transport-specific conversion. */
+  readonly message: NotificationMessage
+}
+
+interface FakeNotificationsRaw {
+  readonly sent: readonly FakeSentNotification[]
+}
+
+class FakeNotificationsBase<TChannel extends NotificationChannel> implements NotificationDriver<
+  NotificationCapabilities<TChannel>,
+  FakeNotificationsRaw
+> {
+  readonly name = 'fake'
+  readonly instance: string
+  readonly capabilities: NotificationCapabilities<TChannel>
+  readonly sent: FakeSentNotification[] = []
+  #nextId = 1
+
+  constructor(channels: readonly TChannel[], instance = 'default') {
+    this.capabilities = { channels }
+    this.instance = instance
+  }
+
+  raw(): FakeNotificationsRaw {
+    return { sent: this.sent }
+  }
+
+  async send<TData>(
+    channel: NotificationChannel,
+    message: NotificationMessage<TData>,
+  ): Promise<NotificationReceipt> {
+    if (!this.capabilities.channels.some((declared) => declared === channel)) {
+      throw new Invalid(`Notification channel ${channel} is not configured.`, {
+        metadata: { fields: { channel: [`${channel} is not declared by this driver.`] } },
+      })
+    }
+    this.sent.push({ channel, message })
+    return { id: `notification-${this.#nextId++}`, channel }
+  }
+}
+
+const allChannels = ['push', 'sms', 'inApp'] as const
+
+/** In-memory notification reference implementation supporting every portable channel. */
+export class FakeNotifications extends FakeNotificationsBase<(typeof allChannels)[number]> {
+  /** Creates an isolated all-channel notification connection. */
+  constructor(instance = 'default') {
+    super(allChannels, instance)
+  }
+}
+
+const noChannels = [] as const
+
+/** In-memory notification reference implementation with every channel disabled. */
+export class FakeNotificationsWithoutChannels extends FakeNotificationsBase<never> {
+  /** Creates an isolated notification connection with no configured channels. */
+  constructor(instance = 'default') {
+    super(noChannels, instance)
+  }
+}