@avelonjs/core 0.1.0 → 0.3.0

package/README.md

@@ -159,7 +159,7 @@ export const IndexPublishedPost = defineListener<PostPublished, void, 'queued'>(
 
 ## Runtime Facades
 
-Wave B implements the frozen contracts as process-local facades. You wire drivers with `defineConfig`, dispatch events through `Events`, authorize with `Gate`, validate with `defineRequest`, inject wards with `injectWard`, and run background work through `Errands`. Named mailers, disks, and connections never fall back to the default when the name is unknown.
+The runtime implements the frozen contracts as process-local facades. You wire drivers with `defineConfig`, dispatch events through `Events`, authorize with `Gate`, validate with `defineRequest`, inject wards with `injectWard`, and run background work through `Errands`. Named mailers, disks, and connections never fall back to the default when the name is unknown.
 
 ```ts
 import {
@@ -301,6 +301,7 @@ The table lists every public export. Capability surface interfaces describe meth
 | `DriverContract`              | `interface DriverContract<TCapabilities, TRaw>`                             | Shared name, instance, capabilities, and raw client contract.            |
 | `DriverFault`                 | `class DriverFault`                                                         | Normalized unmapped driver error.                                        |
 | `DriverFaultMetadata`         | `interface DriverFaultMetadata`                                             | Driver contract and operation identifiers.                               |
+| `EmailVerificationIdentitySurface` | `interface EmailVerificationIdentitySurface`                           | Send-confirmation and token-verify methods.                              |
 | `EmbeddingAiSurface`          | `interface EmbeddingAiSurface`                                              | Text embedding method.                                                   |
 | `EmbeddingResult`             | `interface EmbeddingResult`                                                 | Ordered embedding vectors and token count.                               |
 | `ErrorCode`                   | `type ErrorCode`                                                            | Fixed machine-readable error code union.                                 |
@@ -320,8 +321,8 @@ The table lists every public export. Capability surface interfaces describe meth
 | `ForbiddenMetadata`           | `interface ForbiddenMetadata`                                               | Denied ability and resource identifiers.                                 |
 | `HttpMethod`                  | `type HttpMethod`                                                           | Methods accepted by route manifests.                                     |
 | `HttpRequest`                 | `interface HttpRequest<TBody>`                                              | Framework-neutral decoded request with access to raw bytes.              |
-| `Identity`                    | `type Identity<TDriver>`                                                    | Identity facade narrowed to five auth capabilities.                      |
-| `IdentityCapabilities`        | `interface IdentityCapabilities<TFactor>`                                   | Password, magic-link, OAuth, organization, and MFA factor declaration.   |
+| `Identity`                    | `type Identity<TDriver>`                                                    | Identity facade narrowed to six auth capabilities.                       |
+| `IdentityCapabilities`        | `interface IdentityCapabilities<TFactor>`                                   | Password, magic-link, OAuth, organization, MFA, and email-verification declaration. |
 | `IdentityDriver`              | `interface IdentityDriver<TCapabilities, TRaw, TActor, TSession>`           | Current actor, session, and sign-out contract.                           |
 | `IdentityOrganization`        | `interface IdentityOrganization`                                            | Normalized organization summary.                                         |
 | `Invalid`                     | `class Invalid`                                                             | Normalized invalid-input error.                                          |
@@ -339,7 +340,7 @@ The table lists every public export. Capability surface interfaces describe meth
 | `LogLevel`                    | `type LogLevel`                                                             | Portable structured log severity.                                        |
 | `LogRecord`                   | `interface LogRecord`                                                       | Structured application log event.                                        |
 | `Logs`                        | `type Logs<TDriver>`                                                        | Logging facade narrowed to tracing support.                              |
-| `MagicLinkIdentitySurface`    | `interface MagicLinkIdentitySurface`                                        | Passwordless sign-in link method.                                        |
+| `MagicLinkIdentitySurface`    | `interface MagicLinkIdentitySurface<TActor>`                                | Passwordless sign-in: send a link, then redeem its token.                |
 | `Mail`                        | `type Mail<TDriver>`                                                        | Mail facade narrowed to hosted templates.                                |
 | `MailAttachment`              | `interface MailAttachment`                                                  | Portable attachment filename, bytes, and media type.                     |
 | `MailCapabilities`            | `interface MailCapabilities`                                                | Literal hosted-template capability declaration.                          |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@avelonjs/core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "private": false,
   "description": "Frozen TypeScript contracts, errors, and capability types shared by Avelon packages.",
   "license": "MIT",

package/src/drivers/identity.ts

@@ -12,6 +12,8 @@ export interface IdentityCapabilities<TFactor extends string = string> {
   readonly organizations: boolean
   /** Supported factors retained as a literal readonly list; empty means no MFA surface. */
   readonly mfa: readonly TFactor[]
+  /** Whether email-address confirmation is available. */
+  readonly emailVerification: boolean
 }
 
 /** Authentication capability alias matching the application-facing `Auth` vocabulary. */
@@ -77,9 +79,11 @@ export interface PasswordIdentitySurface<TActor = unknown> {
 }
 
 /** Passwordless operations exposed only by magic-link-capable identity drivers. */
-export interface MagicLinkIdentitySurface {
+export interface MagicLinkIdentitySurface<TActor = unknown> {
   /** Sends a sign-in link to an email address. */
   sendMagicLink(email: string, redirectTo?: string): Promise<void>
+  /** Authenticates an actor with the token a magic link carried. */
+  signInWithMagicLink(token: string): Promise<TActor>
 }
 
 /** OAuth linking exposed only when the identity driver supports linked identities. */
@@ -104,6 +108,14 @@ export interface MfaIdentitySurface<TFactor extends string = string> {
   verifyMfa(challengeId: string, code: string): Promise<void>
 }
 
+/** Email confirmation exposed only by drivers that verify addresses. */
+export interface EmailVerificationIdentitySurface {
+  /** Sends a confirmation message without revealing account existence. */
+  sendEmailVerification(email?: string): Promise<void>
+  /** Confirms an email address after validating a vendor token. */
+  verifyEmail(token: string): Promise<void>
+}
+
 type ActorOf<TDriver extends IdentityDriver> =
   TDriver extends IdentityDriver<IdentityCapabilities, unknown, infer TActor, unknown>
     ? TActor
@@ -124,10 +136,14 @@ export type Identity<TDriver extends IdentityDriver> = Pick<
     TDriver['capabilities']['passwords'],
     PasswordIdentitySurface<ActorOf<TDriver>>
   > &
-  CapabilitySurface<TDriver['capabilities']['magicLinks'], MagicLinkIdentitySurface> &
+  CapabilitySurface<
+    TDriver['capabilities']['magicLinks'],
+    MagicLinkIdentitySurface<ActorOf<TDriver>>
+  > &
   CapabilitySurface<TDriver['capabilities']['oauth'], OAuthIdentitySurface> &
   CapabilitySurface<TDriver['capabilities']['organizations'], OrganizationIdentitySurface> &
-  MfaIdentityFor<TDriver['capabilities']>
+  MfaIdentityFor<TDriver['capabilities']> &
+  CapabilitySurface<TDriver['capabilities']['emailVerification'], EmailVerificationIdentitySurface>
 
 /** Authentication facade alias matching the application-facing `Auth` vocabulary. */
 export type Auth<TDriver extends IdentityDriver> = Identity<TDriver>

package/src/runtime/config.ts

@@ -36,7 +36,7 @@ export interface AvelonDrivers {
 export interface AvelonConfig {
   /** Application name used in diagnostics. */
   name?: string
-  /** Optional adapter. Wave C mounts routes; Wave B only stores the reference. */
+  /** Optional adapter. The Next adapter mounts routes. Core only stores the reference. */
   adapter?: Adapter
   /** Driver wiring for the current environment. */
   drivers: AvelonDrivers

package/src/runtime/gate.ts

@@ -1,3 +1,4 @@
+import { AsyncLocalStorage } from 'node:async_hooks'
 import { Forbidden, Unauthenticated } from '../errors'
 
 /** Actor shape accepted by the gate. `null` is an anonymous caller. */
@@ -12,7 +13,18 @@ export type PolicyAbilities = Readonly<Record<string, PolicyHandler>>
 type ResourceKey = string | { readonly name: string }
 
 const policies = new Map<string, PolicyAbilities>()
-let currentActor: GateActor = null
+const storage = new AsyncLocalStorage<{ actor: GateActor }>()
+let fallbackActor: GateActor = null
+
+function activeActor(): GateActor {
+  const store = storage.getStore()
+  return store === undefined ? fallbackActor : store.actor
+}
+
+/** Runs `fn` with `actor` bound for that call and everything it awaits. */
+export async function runWithActor<T>(actor: GateActor, fn: () => Promise<T>): Promise<T> {
+  return await storage.run({ actor }, fn)
+}
 
 function resourceName(resource: ResourceKey | object): string {
   if (typeof resource === 'string') return resource
@@ -39,7 +51,7 @@ export function definePolicy(resource: ResourceKey, abilities: PolicyAbilities):
 /** Clears registered policies and the request actor. Intended for tests. */
 export function resetPolicies(): void {
   policies.clear()
-  currentActor = null
+  fallbackActor = null
 }
 
 async function allows(actor: GateActor, ability: string, resource?: unknown): Promise<boolean> {
@@ -56,21 +68,31 @@ async function allows(actor: GateActor, ability: string, resource?: unknown): Pr
 
 /** Authorization helpers used by controllers. */
 export const Gate = {
-  /** Binds the request actor used when `authorize`/`can` omit one. */
+  /**
+   * Binds the request actor used when `authorize`/`can` omit one.
+   *
+   * Inside `runWithActor` the write stays scoped to that call; outside one it writes the
+   * process-wide fallback.
+   */
   setActor(actor: GateActor): void {
-    currentActor = actor
+    const store = storage.getStore()
+    if (store !== undefined) {
+      store.actor = actor
+      return
+    }
+    fallbackActor = actor
   },
 
   /** Returns the actor bound for this request, or `null`. */
   actor(): GateActor {
-    return currentActor
+    return activeActor()
   },
 
   /** Returns whether the actor may perform the ability. */
   async can(
     ability: string,
     resource?: unknown,
-    actor: GateActor = currentActor,
+    actor: GateActor = activeActor(),
   ): Promise<boolean> {
     return allows(actor, ability, resource)
   },
@@ -79,7 +101,7 @@ export const Gate = {
   async authorize(
     ability: string,
     resource?: unknown,
-    actor: GateActor = currentActor,
+    actor: GateActor = activeActor(),
   ): Promise<void> {
     if (actor === null) {
       const handlerAllowsAnonymous = await allows(null, ability, resource)

package/src/runtime/kernel.ts

@@ -7,8 +7,16 @@ import type {
   RouteDefinition,
   ViewResult,
 } from '../adapter'
-import { Forbidden, Invalid, NotFound, Unauthenticated } from '../errors'
-import { Gate, type GateActor } from './gate'
+import {
+  Conflict,
+  Forbidden,
+  Invalid,
+  NotFound,
+  RateLimited,
+  Unauthenticated,
+  Unavailable,
+} from '../errors'
+import { Gate, runWithActor, type GateActor } from './gate'
 import { Events } from './dispatcher'
 import { flushAfterErrands } from './errands'
 
@@ -46,7 +54,15 @@ function hasHeader(headers: Readonly<Record<string, string>>, name: string): boo
   )
 }
 
-/** Maps framework errors onto transport-neutral kernel results. */
+/**
+ * Maps framework errors onto transport-neutral kernel results.
+ *
+ * Every taxonomy member except `DriverFault` has a result here; that one stays unmapped because an
+ * unrecognized driver failure is a server fault, not an answer to give the caller. A member left
+ * unmapped propagates out of the dispatcher, and the adapter above it turns that into a runtime
+ * error whose message a production build hides, which is how a driver reporting "Signups not
+ * allowed for this instance" reaches the browser as a blank failure.
+ */
 export function mapKernelException(error: unknown): KernelResult | undefined {
   if (error instanceof Invalid) {
     return {
@@ -63,6 +79,30 @@ export function mapKernelException(error: unknown): KernelResult | undefined {
       status: 302,
     } satisfies RedirectResult
   }
+  if (error instanceof Conflict) {
+    return {
+      type: 'action',
+      ok: false,
+      errors: { _form: [error.message] },
+      status: 409,
+    } satisfies ActionResult
+  }
+  if (error instanceof RateLimited) {
+    return {
+      type: 'action',
+      ok: false,
+      errors: { _form: [error.message] },
+      status: 429,
+    } satisfies ActionResult
+  }
+  if (error instanceof Unavailable) {
+    return {
+      type: 'action',
+      ok: false,
+      errors: { _form: [error.message] },
+      status: 503,
+    } satisfies ActionResult
+  }
   if (error instanceof Forbidden) {
     return {
       type: 'action',
@@ -92,20 +132,20 @@ export function createKernel(options: CreateKernelOptions = {}): Kernel<Controll
   return {
     async dispatch(route, request) {
       try {
-        if (options.resolveActor) {
-          Gate.setActor(await options.resolveActor(request))
-        }
-        await runMiddleware(route, request, options)
-        const bindings = await resolveBindings(route, request, options.resolveBinding)
-        const controller = new route.controller()
-        const action = Reflect.get(controller, route.action)
-        if (typeof action !== 'function') {
-          throw new NotFound(`Controller action ${route.action} was not found.`, {
-            metadata: { resource: 'controller_action', identifier: route.action },
-          })
-        }
-        const result = await (action as ControllerMethod).call(controller, request, ...bindings)
-        return normalizeResult(result)
+        const actor = options.resolveActor ? await options.resolveActor(request) : Gate.actor()
+        return await runWithActor(actor, async () => {
+          await runMiddleware(route, request, options)
+          const bindings = await resolveBindings(route, request, options.resolveBinding)
+          const controller = new route.controller()
+          const action = Reflect.get(controller, route.action)
+          if (typeof action !== 'function') {
+            throw new NotFound(`Controller action ${route.action} was not found.`, {
+              metadata: { resource: 'controller_action', identifier: route.action },
+            })
+          }
+          const result = await (action as ControllerMethod).call(controller, request, ...bindings)
+          return normalizeResult(result)
+        })
       } catch (error) {
         const mapped = options.mapException?.(error) ?? mapKernelException(error)
         if (mapped !== undefined) return mapped