@avelonjs/conformance 0.1.0 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avelonjs/conformance",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Contract test suites and in-memory fakes for Avelon drivers.",
   "license": "MIT",

package/src/fakes/identity.ts

@@ -4,6 +4,7 @@ import {
   Unauthenticated,
   type IdentityDriver,
   type IdentityOrganization,
+  type EmailVerificationIdentitySurface,
   type MagicLinkIdentitySurface,
   type MfaChallenge,
   type MfaIdentitySurface,
@@ -19,6 +20,7 @@ const capabilities = {
   oauth: true,
   organizations: true,
   mfa: ['totp', 'recovery'] as const,
+  emailVerification: true,
 } as const
 
 type Factor = (typeof capabilities.mfa)[number]
@@ -43,6 +45,7 @@ export interface FakeIdentitySession {
 
 interface StoredActor extends FakeIdentityActor {
   password: string
+  emailVerified: boolean
 }
 
 interface StoredSession extends FakeIdentitySession {
@@ -73,10 +76,11 @@ export class FakeIdentity
   implements
     IdentityDriver<typeof capabilities, FakeIdentityRaw, FakeIdentityActor, FakeIdentitySession>,
     PasswordIdentitySurface<FakeIdentityActor>,
-    MagicLinkIdentitySurface,
+    MagicLinkIdentitySurface<FakeIdentityActor>,
     OAuthIdentitySurface,
     OrganizationIdentitySurface,
-    MfaIdentitySurface<Factor>
+    MfaIdentitySurface<Factor>,
+    EmailVerificationIdentitySurface
 {
   /** Driver implementation name. */
   readonly name = 'fake'
@@ -91,6 +95,8 @@ export class FakeIdentity
   readonly #actors = new Map<string, StoredActor>()
   readonly #sessions = new Map<string, StoredSession>()
   readonly #resetTokens = new Map<string, string>()
+  readonly #magicLinkTokens = new Map<string, string>()
+  readonly #verifyTokens = new Map<string, string>()
   readonly #challenges = new Map<string, { actorId: string; challenge: MfaChallenge<Factor> }>()
   #lastSession: FakeIdentitySession | null = null
   #nextActor = 1
@@ -107,6 +113,25 @@ export class FakeIdentity
     return { users: this.#actors.size, sessions: this.#sessions.size }
   }
 
+  #openSession(actor: StoredActor): FakeIdentityActor {
+    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 }
+  }
+
   /** Returns the current actor or null for an anonymous request. */
   async user(): Promise<FakeIdentityActor | null> {
     const session = this.#currentSession()
@@ -135,7 +160,12 @@ export class FakeIdentity
         metadata: { resource: 'actor', key: 'email' },
       })
     }
-    const actor: StoredActor = { id: `actor-${this.#nextActor++}`, email, password }
+    const actor: StoredActor = {
+      id: `actor-${this.#nextActor++}`,
+      email,
+      password,
+      emailVerified: false,
+    }
     this.#actors.set(email, actor)
     return { id: actor.id, email: actor.email }
   }
@@ -144,23 +174,7 @@ export class FakeIdentity
   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 }
+    return this.#openSession(actor)
   }
 
   /** Records a deterministic recovery token for a known actor without revealing account absence. */
@@ -185,8 +199,19 @@ export class FakeIdentity
     actor.password = password
   }
 
-  /** Accepts a magic-link request without revealing account existence. */
-  async sendMagicLink(_email: string, _redirectTo?: string): Promise<void> {}
+  /** Records a deterministic sign-in token for a known actor without revealing account absence. */
+  async sendMagicLink(email: string, _redirectTo?: string): Promise<void> {
+    if (this.#actors.has(email)) this.#magicLinkTokens.set('assay-magic-link-token', email)
+  }
+
+  /** Authenticates an actor with the token a magic link carried. */
+  async signInWithMagicLink(token: string): Promise<FakeIdentityActor> {
+    const email = this.#magicLinkTokens.get(token)
+    const actor = email ? this.#actors.get(email) : undefined
+    if (!email || !actor) throw unauthenticated('Invalid sign-in link.')
+    this.#magicLinkTokens.delete(token)
+    return this.#openSession(actor)
+  }
 
   /** Links a completed authorization to the authenticated actor. */
   async linkOAuthIdentity(_provider: string, _code: string): Promise<void> {
@@ -219,6 +244,22 @@ export class FakeIdentity
     return { ...challenge }
   }
 
+  /** Records a deterministic confirmation token for a known actor without revealing account absence. */
+  async sendEmailVerification(email?: string): Promise<void> {
+    const target = email ?? (await this.user())?.email
+    if (!target) throw invalid('email', 'No email to verify.')
+    if (this.#actors.has(target)) this.#verifyTokens.set('assay-verify-token', target)
+  }
+
+  /** Confirms an email address after validating a confirmation token. */
+  async verifyEmail(token: string): Promise<void> {
+    const email = this.#verifyTokens.get(token)
+    const actor = email ? this.#actors.get(email) : undefined
+    if (!email || !actor) throw invalid('token', 'Invalid email verification token.')
+    actor.emailVerified = true
+    this.#verifyTokens.delete(token)
+  }
+
   /** Verifies the deterministic code accepted by the in-memory implementation. */
   async verifyMfa(challengeId: string, code: string): Promise<void> {
     const pending = this.#challenges.get(challengeId)

package/src/fakes/logs.ts

@@ -1,4 +1,9 @@
-import { type LogDriver, type LogRecord, type TraceLogSurface, type TraceSpan } from '@avelonjs/core'
+import {
+  type LogDriver,
+  type LogRecord,
+  type TraceLogSurface,
+  type TraceSpan,
+} from '@avelonjs/core'
 
 const capabilities = { traces: true } as const
 

package/src/harness.ts

@@ -21,6 +21,10 @@ export interface SuiteContext<TDriver> {
   cleanup?(driver: TDriver): Promise<void> | void
   /** Returns a vendor-issued password recovery token for the fixture identity. */
   recoveryToken?(email: string): Promise<string>
+  /** Returns a vendor-issued email confirmation token for the fixture identity. */
+  emailVerificationToken?(email: string): Promise<string>
+  /** Returns the vendor-issued token a sent magic link carried. */
+  magicLinkToken?(email: string): Promise<string>
   /** Returns the response code for a pending MFA challenge. */
   mfaCode?(challengeId: string): Promise<string>
   /** Verified sender address used by live mail providers. */

package/src/suites/identity.ts

@@ -1,9 +1,11 @@
 import { describe, expect, test } from 'bun:test'
 import {
+  Conflict,
   Invalid,
   Unauthenticated,
   type IdentityCapabilities,
   type IdentityDriver,
+  type EmailVerificationIdentitySurface,
   type MagicLinkIdentitySurface,
   type MfaIdentitySurface,
   type OAuthIdentitySurface,
@@ -72,6 +74,14 @@ async function expectUnauthenticated(operation: () => Promise<unknown>): Promise
   return error
 }
 
+async function expectConflict(operation: () => Promise<unknown>): Promise<Conflict> {
+  const error = await captureFailure(operation)
+  expect(error).toBeInstanceOf(Conflict)
+  if (!(error instanceof Conflict)) throw new Error('Expected Conflict after taxonomy assertion.')
+  expect(error.code).toBe('CONFLICT')
+  return error
+}
+
 async function expectInvalid(operation: () => Promise<unknown>): Promise<Invalid> {
   const error = await captureFailure(operation)
   expect(error).toBeInstanceOf(Invalid)
@@ -84,7 +94,9 @@ function hasPasswords(driver: AssayDriver): driver is AssayDriver & PasswordIden
   return driver.capabilities.passwords
 }
 
-function hasMagicLinks(driver: AssayDriver): driver is AssayDriver & MagicLinkIdentitySurface {
+function hasMagicLinks(
+  driver: AssayDriver,
+): driver is AssayDriver & MagicLinkIdentitySurface<unknown> {
   return driver.capabilities.magicLinks
 }
 
@@ -102,13 +114,20 @@ function hasMfa(driver: AssayDriver): driver is AssayDriver & MfaIdentitySurface
   return driver.capabilities.mfa.length > 0
 }
 
+function hasEmailVerification(
+  driver: AssayDriver,
+): driver is AssayDriver & EmailVerificationIdentitySurface {
+  return driver.capabilities.emailVerification
+}
+
 /**
  * Registers the portable identity contract conformance suite.
  *
  * `context.create()` returns the config-time factory, whose pinned signature is
  * `(cookies: RequestCookies) => TDriver`. Each call to that factory receives one request-scoped
- * cookie store. Recovery-token and MFA-code providers may supply vendor-issued fixture values;
- * otherwise password-capable fixtures accept `assay-reset-token` and MFA fixtures accept `123456`.
+ * cookie store. Recovery-token, email-verification, and MFA-code providers may supply vendor-issued
+ * fixture values; otherwise password-capable fixtures accept `assay-reset-token`, email-verification
+ * fixtures accept `assay-verify-token`, and MFA fixtures accept `123456`.
  *
  * @param context Fresh identity factories and optional cleanup.
  */
@@ -129,10 +148,15 @@ export function identitySuite<TDriver extends AssayDriver>(
             'updatePassword',
           ],
         ],
-        ['magicLinks', driver.capabilities.magicLinks, ['sendMagicLink']],
+        ['magicLinks', driver.capabilities.magicLinks, ['sendMagicLink', 'signInWithMagicLink']],
         ['oauth', driver.capabilities.oauth, ['linkOAuthIdentity']],
         ['organizations', driver.capabilities.organizations, ['organizations', 'useOrganization']],
         ['mfa', driver.capabilities.mfa.length > 0, ['challengeMfa', 'verifyMfa']],
+        [
+          'emailVerification',
+          driver.capabilities.emailVerification,
+          ['sendEmailVerification', 'verifyEmail'],
+        ],
       ]
       for (const [capability, declared, methods] of surfaces) {
         assertCapabilitySurface(driver, capability, declared, methods)
@@ -191,6 +215,19 @@ export function identitySuite<TDriver extends AssayDriver>(
       },
     )
 
+    assay(
+      context,
+      'refuses a second registration of the same email as Conflict',
+      async (driver) => {
+        if (!hasPasswords(driver)) return
+        await driver.register('actor@example.test', 'initial-password')
+        // Every driver has its own vendor wording for this. Application code branches on the
+        // taxonomy member, so a driver that reports it as Invalid makes "email is taken" a string
+        // match against a vendor message.
+        await expectConflict(() => driver.register('actor@example.test', 'another-password'))
+      },
+    )
+
     assay(context, 'signs out the current request and clears its session', async (driver) => {
       if (!hasPasswords(driver)) return
       await driver.register('actor@example.test', 'initial-password')
@@ -244,12 +281,30 @@ export function identitySuite<TDriver extends AssayDriver>(
       expect(await driver.signInWithPassword('actor@example.test', 'reset-password')).not.toBeNull()
     })
 
-    assay(context, 'sends passwordless magic links when declared', async (driver) => {
-      if (!hasMagicLinks(driver)) return
-      await expect(
-        driver.sendMagicLink('actor@example.test', 'https://app.example.test/complete'),
-      ).resolves.toBeUndefined()
-    })
+    assay(
+      context,
+      'sends a magic link and signs in with the token it carried',
+      async (driver, cookies) => {
+        if (!hasMagicLinks(driver)) return
+        await expect(
+          driver.sendMagicLink('actor@example.test', 'https://app.example.test/complete'),
+        ).resolves.toBeUndefined()
+        // Sending is half a flow. A driver that cannot redeem the token it just mailed leaves the
+        // capability declared and unusable, which is the state this assertion exists to catch.
+        if (!hasPasswords(driver)) return
+        await driver.register('actor@example.test', 'initial-password')
+        await driver.sendMagicLink('actor@example.test')
+        const token = context.magicLinkToken
+          ? await context.magicLinkToken('actor@example.test')
+          : 'assay-magic-link-token'
+        const signedIn = await driver.signInWithMagicLink(token)
+        expect(signedIn).not.toBeNull()
+        expect(await driver.user()).toEqual(signedIn)
+        expect(await driver.session()).not.toBeNull()
+        expect(cookies.size).toBeGreaterThan(0)
+        await expectUnauthenticated(() => driver.signInWithMagicLink('not-a-real-token'))
+      },
+    )
 
     assay(context, 'links a completed OAuth identity when declared', async (driver) => {
       if (!hasPasswords(driver) || !hasOAuth(driver)) return
@@ -289,5 +344,22 @@ export function identitySuite<TDriver extends AssayDriver>(
         await expectInvalid(() => driver.challengeMfa('undeclared-factor'))
       },
     )
+
+    assay(
+      context,
+      'sends email confirmation without revealing accounts and verifies the token',
+      async (driver) => {
+        if (!hasEmailVerification(driver) || !hasPasswords(driver)) return
+        await driver.register('actor@example.test', 'initial-password')
+        await driver.signInWithPassword('actor@example.test', 'initial-password')
+        await expect(driver.sendEmailVerification()).resolves.toBeUndefined()
+        await expect(driver.sendEmailVerification('missing@example.test')).resolves.toBeUndefined()
+        const verificationToken = context.emailVerificationToken
+          ? await context.emailVerificationToken('actor@example.test')
+          : 'assay-verify-token'
+        await expect(driver.verifyEmail(verificationToken)).resolves.toBeUndefined()
+        await expectInvalid(() => driver.verifyEmail('invalid-token'))
+      },
+    )
   })
 }

package/src/suites/social.ts

@@ -1,5 +1,10 @@
 import { describe, expect, test } from 'bun:test'
-import { Invalid, Unauthenticated, type SocialCapabilities, type SocialDriver } from '@avelonjs/core'
+import {
+  Invalid,
+  Unauthenticated,
+  type SocialCapabilities,
+  type SocialDriver,
+} from '@avelonjs/core'
 import { captureFailure, type SuiteContext } from '../harness'
 
 type AssayDriver = SocialDriver<SocialCapabilities<string>, unknown, unknown>