@supacloud/elysia 0.8.1 → 0.10.0

package/README.md

@@ -91,8 +91,9 @@ write retry. Confirm the outcome using the application's durable receipt or
 read-back protocol. A custom `errorMapper` can override this public envelope.
 
 Native `Response` objects are passed through by Elysia, including JSON responses.
-Handlers returning a native `Response` must validate their JSON payload before
-constructing it. The adapter does not consume or parse binary/streaming responses.
+Use `validatedJsonResponse` to opt into validation when constructing a native
+JSON response. Otherwise handlers must validate their JSON payload themselves.
+The adapter does not consume or parse binary/streaming responses.
 
 Jobs are executed explicitly with `executeJob(compiledModule, services, job,
 input, requestContext)`. The asynchronous compiler-generated job scope is
@@ -101,6 +102,99 @@ fails partway through.
 
 ## API
 
+### External SupAuth Identity
+
+`createSupAuthRequestContext(options)` supplies the trusted host adapter for an
+external SupAuth user center. It uses `jose` signature verification, requires
+configured HTTPS issuer/JWKS endpoints, audience, subject, expiry and issued-at,
+and accepts only ES256/RS256. It does not implement login, sessions or token issuance.
+
+```ts
+import { createSupAuthRequestContext } from "@supacloud/elysia";
+
+const requestContext = createSupAuthRequestContext({
+  issuer: "https://identity.example/auth/v1",
+  audience: "authenticated",
+  clientId: "orders-oauth-client",
+  projectId: "orders",
+  jwksUrl: "https://identity.example/auth/v1/.well-known/jwks.json",
+  resolveAccess: async (identity) =>
+    accessRepository.findCurrentAccess(identity.issuer, identity.subject, "orders"),
+});
+```
+
+`accessRepository` is application-owned and must return `{ projectId, tenantId,
+permissions }` or `null` from authoritative local data. The factory rejects
+missing/wrong-project access, ignores forwarded subject/tenant headers and
+returns a frozen identity/access snapshot. Commands must still authorize current
+object relationships within their durable transaction; a permission snapshot is
+not an RLS replacement. The bearer credential is non-enumerable on identity.
+Never log the complete request/context.
+
+The adapter protects all routes using that context factory, including health
+routes; mount intentionally public routes separately. Invalid credentials and
+invalid signing keys fail closed with sanitized 401 responses. Tokens must have
+`role: "authenticated"` and a matching `client_id` or `azp`; when both exist they
+must match each other and the configured `clientId`. Verification service failures
+return sanitized 503 `AUTHENTICATION_UNAVAILABLE`, never an identity fallback. Remote
+JWKS uses bounded fetch timeout and the library's key cache; no token-provided key
+URL or local identity fallback is accepted. `keyResolver` is a trusted host
+override for pinned key sets/testing, never request input.
+
+### Execution Inspection
+
+Set `createApplication({ onExecution })` for metadata-only events: operation,
+stage, kind, phase, elapsed time and a bounded request correlation ID. Module,
+route and command aspects retain declared order. Standard governance exposes
+authorization, idempotency, transaction, handler and successful audit stages.
+Pass the final optional observer argument to `executeJob` for job traces.
+No request input, token, result or error cause is sent to the observer.
+The boundary and aspect index identify the static declaration; JavaScript
+function names are display hints and may change when consumers minify a bundle.
+
+Observer failures are isolated from business results; this is best-effort
+telemetry, not durable audit. Use command governance for mandatory audit.
+An inner successful stage does not prove the enclosing transaction committed.
+The compiler's `context`/`explain` commands show the corresponding static plan.
+
+Command transaction/idempotency continuations, custom route executors and job
+handlers reject repeated invocation. This prevents accidental adapter retries
+inside one invocation; cross-request/process deduplication still requires a
+durable idempotency adapter.
+
+### `validatedJsonResponse(validate, value, init?): Response`
+
+Constructs a native JSON response after a synchronous, caller-owned type guard
+validates the actual serialized JSON snapshot. The value type is inferred from
+the guard; compatible extra fields are preserved. For a TypeBox contract, the
+guard can delegate to `Value.Check(schema, value)` or a compiled validator.
+No additional schema dependency is required by the adapter.
+
+```ts
+import { validatedJsonResponse } from "@supacloud/elysia";
+import { isReportReceipt } from "./contracts";
+
+return validatedJsonResponse(isReportReceipt, receipt, {
+  status: 201,
+  headers: { "x-request-id": requestId },
+});
+```
+
+The helper serializes once, validates that wire snapshot, and sends those same
+bytes. Validation cannot mutate the outgoing body; it is not a transform or
+coercion hook. Guards must be synchronous and side-effect free. Serialization
+failures and invalid receipts throw a sanitized `ApplicationError` with HTTP 500
+and `RESPONSE_VALIDATION_ERROR`, without retaining payloads or validator causes.
+The application's `errorMapper` can map this to its outcome-confirmation
+protocol. The helper never retries a command or implies rollback.
+
+`init` uses native `Response` options. The helper explicitly rejects null-body
+statuses 204, 205 and 304, including on runtimes that otherwise accept a body
+with those statuses. The default content type is
+`application/json`, and explicitly supplied headers are preserved. This helper
+is for bounded JSON payloads, not files or streams. Existing native `Response`
+passthrough is unchanged.
+
 ### `createApplication(options: ApplicationOptions): Elysia`
 
 Creates the root Elysia application from compiled modules.

package/dist/execution.d.ts

@@ -0,0 +1,12 @@
+export interface ExecutionEvent {
+    kind: "route" | "command" | "job";
+    operation: string;
+    stage: string;
+    phase: "started" | "succeeded" | "failed";
+    requestId?: string;
+    durationMs?: number;
+}
+/** Metadata only: never receives request bodies, credentials, results or errors. */
+export type ExecutionObserver = (event: Readonly<ExecutionEvent>) => void | Promise<void>;
+export declare function observeExecution<T>(observer: ExecutionObserver | undefined, event: Pick<ExecutionEvent, "kind" | "operation" | "stage" | "requestId">, next: () => T | Promise<T>): Promise<T>;
+export declare function executionRequestId(context: unknown): string | undefined;

package/dist/identity.d.ts

@@ -0,0 +1,37 @@
+import { type JWTVerifyGetKey } from "jose";
+import { type SupaCloudRequestContext, type TrustedRequestIdentity } from "./index";
+export interface SupAuthIdentity extends TrustedRequestIdentity {
+    authenticated: true;
+    subject: string;
+    issuer: string;
+    clientId: string;
+}
+export interface SupAuthAccess {
+    projectId: string;
+    tenantId: string;
+    permissions: readonly string[];
+}
+export interface SupAuthRequestContext extends SupaCloudRequestContext {
+    identity: SupAuthIdentity;
+    access: Readonly<SupAuthAccess>;
+}
+export interface SupAuthContextOptions {
+    issuer: string;
+    audience: string;
+    /** SupAuth OAuth application binding, independent of audience/project membership. */
+    clientId: string;
+    projectId: string;
+    /** Explicit trusted JWKS endpoint; never read from a token's jku/x5u header. */
+    jwksUrl: string;
+    /** Defaults to ES256 and RS256; symmetric algorithms are not supported. */
+    algorithms?: readonly ("ES256" | "RS256")[];
+    /** Trusted host override for pinned/local keys and deterministic tests. */
+    keyResolver?: JWTVerifyGetKey;
+    /** Read current application-local access, not user-supplied tenant headers. */
+    resolveAccess(identity: Readonly<SupAuthIdentity>, request: Request): Promise<SupAuthAccess | null>;
+}
+/**
+ * External user-center verification only. SupAuth/GoTrue still owns login,
+ * passwords, sessions and token issuance; applications own access decisions.
+ */
+export declare function createSupAuthRequestContext(options: SupAuthContextOptions): (request: Request) => Promise<SupAuthRequestContext>;

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 import { Elysia } from "elysia";
+import { type ExecutionObserver } from "./execution";
+export type { ExecutionEvent, ExecutionObserver } from "./execution";
 export interface CompiledRoute {
     method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
     path: string;
@@ -23,6 +25,7 @@ export interface CompiledRoute {
     aspects?: ApplicationAspect[];
 }
 export interface CompiledCommand {
+    rpc?: string;
     className: string;
     name: string;
     permission?: string;
@@ -61,6 +64,8 @@ export interface CompiledModule {
     aspects?: ApplicationAspect[];
 }
 export type RequestContextFactory = (request: Request) => unknown | Promise<unknown>;
+export { createSupAuthRequestContext } from "./identity";
+export type { SupAuthIdentity, SupAuthAccess, SupAuthRequestContext, SupAuthContextOptions } from "./identity";
 export declare const VERIFIED_JWT_SUBJECT_HEADER = "x-supacloud-jwt-sub";
 export declare const EXECUTION_ID_HEADER = "x-sb-execution-id";
 export declare const IDEMPOTENCY_KEY_HEADER = "idempotency-key";
@@ -116,6 +121,15 @@ export interface CommandAudit {
     failed(invocation: CommandInvocation, error: unknown): void | Promise<void>;
 }
 export interface CommandGovernance {
+    /** Application-owned adapters: a single RPC owns all declared persistence. */
+    rpc?: Record<string, {
+        capabilities: {
+            audit?: boolean;
+            transaction?: boolean;
+            idempotency?: boolean;
+        };
+        execute: CommandMiddleware;
+    }>;
     authorize: CommandAuthorizer;
     idempotency?: CommandMiddleware;
     transaction?: CommandMiddleware;
@@ -144,6 +158,13 @@ export declare class ApplicationError extends Error implements PublicApplication
     readonly details?: unknown;
     constructor(message: string, options?: ApplicationErrorOptions);
 }
+export type JsonResponseValidator<T> = (value: unknown) => value is T;
+/**
+ * Validate the serialized JSON snapshot before creating a native Response.
+ * Validators must be synchronous and side-effect free; response failures do not
+ * imply that application writes were rolled back.
+ */
+export declare function validatedJsonResponse<T>(validate: JsonResponseValidator<T>, value: NoInfer<T>, init?: ResponseInit): Response;
 export interface ErrorContext {
     request: Request;
     requestContext: unknown;
@@ -164,6 +185,8 @@ export interface ApplicationOptions {
     commandExecutor?: CommandExecutor;
     /** Maps framework or application failures to the public HTTP contract. */
     errorMapper?: ErrorMapper;
+    /** Best-effort execution metadata only; durable audit belongs to governance. */
+    onExecution?: ExecutionObserver;
 }
 export interface JobInvocation {
     job: CompiledJob;
@@ -178,13 +201,27 @@ export type JobExecutor = (invocation: JobInvocation, next: () => unknown | Prom
  * Runtime. The runtime strips incoming x-supacloud-jwt-sub values and writes
  * the header only after JWT verification.
  */
-export declare const createSupaCloudRequestContext: RequestContextFactory;
+export declare const createSupaCloudRequestContext: (request: Request) => SupaCloudRequestContext;
 /**
  * Compose the standard command governance order:
  * authorization -> idempotency -> transaction -> audit -> handler.
  * Declared governance metadata fails closed when its adapter is absent.
  */
-export declare function createCommandExecutor(governance: CommandGovernance): CommandExecutor;
+export declare function createCommandExecutor(governance: CommandGovernance, observer?: ExecutionObserver): CommandExecutor;
+/** Execute at the business-selected boundary without binding or re-entering an HTTP route. */
+export declare function executeCompiledCommand<Input, Result>(options: {
+    module: Pick<CompiledModule, "name" | "commands" | "aspects">;
+    command: string;
+    input: Input;
+    request: Request;
+    requestContext: unknown;
+    services?: Record<string, unknown>;
+    scope?: Record<string, unknown>;
+    governance: CommandGovernance;
+    observer?: ExecutionObserver;
+    handler: (input: Input) => Result | Promise<Result>;
+    decode: (value: unknown) => Result;
+}): Promise<Result>;
 export declare function requireTrustedIdentity(requestContext: unknown): Required<Pick<TrustedRequestIdentity, "subject" | "accessToken">> & TrustedRequestIdentity;
 export declare function requireIdempotencyKey(invocation: CommandInvocation): string;
 /**
@@ -195,7 +232,7 @@ export declare function requireIdempotencyKey(invocation: CommandInvocation): st
  * exposed on the `scope` context key. Request-scoped controller instances are
  * looked up on `scope`, everything else on `services`.
  */
-export declare function createModulePlugin(compiled: CompiledModule, services: Record<string, unknown>, ctxFactory?: RequestContextFactory, options?: Pick<ApplicationOptions, "commandGovernance" | "commandExecutor" | "errorMapper">, imported?: Record<string, Record<string, unknown>>): Elysia;
+export declare function createModulePlugin(compiled: CompiledModule, services: Record<string, unknown>, ctxFactory?: RequestContextFactory, options?: Pick<ApplicationOptions, "commandGovernance" | "commandExecutor" | "errorMapper" | "onExecution">, imported?: Record<string, Record<string, unknown>>): Elysia;
 /**
  * Execute one compiler-emitted Job descriptor.
  *
@@ -203,7 +240,7 @@ export declare function createModulePlugin(compiled: CompiledModule, services: R
  * accepted for command-like job implementations. The scope factory and
  * destruction hooks are generated statically by the compiler.
  */
-export declare function executeJob(compiled: CompiledModule, services: Record<string, unknown>, job: CompiledJob, input: unknown, requestContext: unknown, imported?: Record<string, Record<string, unknown>>, executor?: JobExecutor): Promise<unknown>;
+export declare function executeJob(compiled: CompiledModule, services: Record<string, unknown>, job: CompiledJob, input: unknown, requestContext: unknown, imported?: Record<string, Record<string, unknown>>, executor?: JobExecutor, observer?: ExecutionObserver): Promise<unknown>;
 export declare function defaultErrorResponse(error: unknown, frameworkCode?: string | number): Response;
 /**
  * Create the root Elysia application from compiled modules.

package/dist/index.js

@@ -1,6 +1,108 @@
 // src/index.ts
 import { Elysia } from "elysia";
 
+// src/execution.ts
+async function observeExecution(observer, event, next) {
+  const emit = (phase, durationMs) => {
+    if (!observer)
+      return;
+    try {
+      Promise.resolve(observer(Object.freeze({ ...event, phase, durationMs }))).catch(() => {});
+    } catch {}
+  };
+  const started = performance.now();
+  emit("started");
+  try {
+    const result = await next();
+    emit("succeeded", performance.now() - started);
+    return result;
+  } catch (error) {
+    emit("failed", performance.now() - started);
+    throw error;
+  }
+}
+function executionRequestId(context) {
+  if (!context || typeof context !== "object" || !("requestId" in context))
+    return;
+  const value = context.requestId;
+  return typeof value === "string" && /^[A-Za-z0-9._:-]{1,256}$/.test(value) ? value : undefined;
+}
+
+// src/identity.ts
+import { createRemoteJWKSet, jwtVerify, errors } from "jose";
+function httpsUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== "https:" || url.username || url.password || url.hash) {
+    throw new TypeError("Identity endpoints must be HTTPS URLs without credentials or fragments");
+  }
+  return url;
+}
+function createSupAuthRequestContext(options) {
+  httpsUrl(options.issuer);
+  const jwksUrl = httpsUrl(options.jwksUrl);
+  if (!options.audience.trim() || !options.projectId.trim() || !options.clientId?.trim()) {
+    throw new TypeError("SupAuth audience, clientId and projectId are required");
+  }
+  const algorithms = [...options.algorithms ?? ["ES256", "RS256"]];
+  if (!algorithms.length || algorithms.some((value) => value !== "ES256" && value !== "RS256")) {
+    throw new TypeError("SupAuth requires ES256 or RS256");
+  }
+  const { issuer, audience, clientId, projectId, resolveAccess } = options;
+  const keyResolver = options.keyResolver ?? createRemoteJWKSet(jwksUrl, { timeoutDuration: 5000 });
+  return async (request) => {
+    const match = request.headers.get("authorization")?.match(/^Bearer ([^\s]+)$/i);
+    const token = match?.[1];
+    if (!token || token.length > 16384)
+      throw unauthenticated();
+    let subject;
+    try {
+      const { payload } = await jwtVerify(token, keyResolver, {
+        issuer,
+        audience,
+        algorithms,
+        requiredClaims: ["sub", "exp", "iat"]
+      });
+      if (typeof payload.sub !== "string" || !payload.sub.trim() || payload.sub.length > 1024 || /[\u0000-\u001f\u007f]/.test(payload.sub)) {
+        throw unauthenticated();
+      }
+      const application = payload.client_id ?? payload.azp;
+      if (application !== clientId || payload.role !== "authenticated" || payload.client_id !== undefined && payload.client_id !== clientId || payload.azp !== undefined && payload.azp !== clientId) {
+        throw unauthenticated();
+      }
+      subject = payload.sub;
+    } catch (error) {
+      if (error instanceof ApplicationError || error instanceof errors.JWTClaimValidationFailed || error instanceof errors.JWTExpired || error instanceof errors.JWTInvalid || error instanceof errors.JWSInvalid || error instanceof errors.JWSSignatureVerificationFailed || error instanceof errors.JOSEAlgNotAllowed || error instanceof errors.JOSENotSupported || error instanceof errors.JWKSNoMatchingKey)
+        throw unauthenticated();
+      throw new ApplicationError("Identity verification service unavailable", {
+        status: 503,
+        code: "AUTHENTICATION_UNAVAILABLE"
+      });
+    }
+    const identity = { authenticated: true, subject, issuer, clientId };
+    Object.defineProperty(identity, "accessToken", { value: token, enumerable: false });
+    Object.freeze(identity);
+    const access = await resolveAccess(identity, request);
+    if (!access || access.projectId !== projectId || typeof access.tenantId !== "string" || !access.tenantId.trim() || !Array.isArray(access.permissions) || access.permissions.some((permission) => typeof permission !== "string" || !permission.trim())) {
+      throw new ApplicationError("Application access denied", { status: 403, code: "APPLICATION_ACCESS_DENIED" });
+    }
+    const context = createSupaCloudRequestContext(request);
+    return {
+      ...context,
+      identity,
+      access: Object.freeze({
+        projectId,
+        tenantId: access.tenantId,
+        permissions: Object.freeze([...new Set(access.permissions)])
+      })
+    };
+  };
+}
+function unauthenticated() {
+  return new ApplicationError("Authenticated user context is required", {
+    status: 401,
+    code: "AUTHENTICATION_REQUIRED"
+  });
+}
 // src/feature.ts
 function assertFeatureTransition(spec, state, event) {
   const transition = Object.hasOwn(spec.transitions, event) ? spec.transitions[event] : undefined;
@@ -368,6 +470,14 @@ function composeAspects(...aspects) {
     return dispatch(0);
   };
 }
+function observedAspects(aspects, boundary, observer) {
+  return composeAspects(...aspects.map((aspect, index) => (context, next) => observeExecution(observer, {
+    kind: context.kind,
+    operation: context.name,
+    stage: `${boundary}.aspect[${index}]:${aspect.name || "anonymous"}`,
+    requestId: executionRequestId(context.requestContext)
+  }, () => aspect(context, next))));
+}
 function composeCommandExecutors(...executors) {
   const active = executors.filter((e) => typeof e === "function");
   if (active.length === 0)
@@ -405,6 +515,28 @@ class ApplicationError extends Error {
     this.details = options.details;
   }
 }
+function validatedJsonResponse(validate, value, init) {
+  if (init?.status === 204 || init?.status === 205 || init?.status === 304) {
+    throw new TypeError("JSON responses cannot use a null-body status");
+  }
+  let body;
+  try {
+    const serialized = JSON.stringify(value);
+    if (serialized === undefined || validate(JSON.parse(serialized)) !== true) {
+      throw new Error("Invalid JSON response");
+    }
+    body = serialized;
+  } catch {
+    throw new ApplicationError("Response validation failed", {
+      status: 500,
+      code: "RESPONSE_VALIDATION_ERROR"
+    });
+  }
+  const headers = new Headers(init?.headers);
+  if (!headers.has("content-type"))
+    headers.set("content-type", "application/json");
+  return new Response(body, { ...init, headers });
+}
 function safeHeaderValue(value, maxLength) {
   if (!value || value.length > maxLength || /[\u0000-\u001f\u007f]/.test(value)) {
     return;
@@ -460,9 +592,31 @@ function missingGovernanceAdapter(command, adapter) {
     code: codes[adapter]
   });
 }
-function createCommandExecutor(governance) {
+function createCommandExecutor(governance, observer) {
   return async (invocation, next) => {
     const { command } = invocation;
+    for (const mode of [command.transaction, command.idempotency]) {
+      if (mode !== undefined && mode !== "required" && mode !== "none") {
+        throw new ApplicationError("Invalid command governance mode", { code: "COMMAND_MODE_INVALID" });
+      }
+    }
+    if (command.rpc !== undefined) {
+      const adapter = Object.hasOwn(governance.rpc ?? {}, command.rpc) ? governance.rpc?.[command.rpc] : undefined;
+      if (!adapter)
+        throw new ApplicationError("RPC governance adapter unavailable", { code: "COMMAND_RPC_UNAVAILABLE", status: 501 });
+      for (const capability of ["audit", "transaction", "idempotency"]) {
+        const required = capability === "audit" ? !!command.audit : command[capability] === "required";
+        if (required && adapter.capabilities[capability] !== true)
+          throw missingGovernanceAdapter(command, capability);
+      }
+      const event = {
+        kind: "command",
+        operation: command.name,
+        requestId: executionRequestId(invocation.requestContext)
+      };
+      await observeExecution(observer, { ...event, stage: "authorize" }, () => governance.authorize(invocation));
+      return observeExecution(observer, { ...event, stage: `rpc:${command.rpc}` }, () => adapter.execute(invocation, once(next)));
+    }
     const audit = command.audit ? governance.audit : undefined;
     const transaction = command.transaction === "required" ? governance.transaction : undefined;
     const idempotency = command.idempotency === "required" ? governance.idempotency : undefined;
@@ -476,24 +630,31 @@ function createCommandExecutor(governance) {
       throw missingGovernanceAdapter(command, "idempotency");
     }
     try {
-      await governance.authorize(invocation);
+      const observe = (stage, next2) => observeExecution(observer, {
+        kind: "command",
+        operation: command.name,
+        stage,
+        requestId: executionRequestId(invocation.requestContext)
+      }, next2);
+      await observe("authorize", () => governance.authorize(invocation));
       let execute = async () => {
-        const result = await next();
+        const result = await observe("handler", invokeOnce);
         if (audit)
-          await audit.succeeded.call(audit, invocation, result);
+          await observe("audit", () => audit.succeeded.call(audit, invocation, result));
         return result;
       };
+      const invokeOnce = once(next);
       if (command.transaction === "required") {
         if (!transaction)
           throw missingGovernanceAdapter(command, "transaction");
         const inner = execute;
-        execute = () => Promise.resolve(transaction.call(governance, invocation, inner));
+        execute = () => observe("transaction", () => transaction.call(governance, invocation, once(inner)));
       }
       if (command.idempotency === "required") {
         if (!idempotency)
           throw missingGovernanceAdapter(command, "idempotency");
         const inner = execute;
-        execute = () => Promise.resolve(idempotency.call(governance, invocation, inner));
+        execute = () => observe("idempotency", () => idempotency.call(governance, invocation, once(inner)));
       }
       return await execute();
     } catch (error) {
@@ -503,6 +664,44 @@ function createCommandExecutor(governance) {
     }
   };
 }
+async function executeCompiledCommand(options) {
+  const matches = options.module.commands?.filter((item) => item.className === options.command) ?? [];
+  if (matches.length !== 1)
+    throw new ApplicationError("Command descriptor missing or ambiguous", { code: "COMMAND_NOT_REGISTERED" });
+  const command = matches[0];
+  const invocation = {
+    command,
+    input: { body: options.input, params: {}, query: {} },
+    request: options.request,
+    requestContext: options.requestContext,
+    services: options.services ?? {},
+    scope: options.scope
+  };
+  const aspects = composeAspects(observedAspects(options.module.aspects ?? [], `module:${options.module.name}`, options.observer), observedAspects(command.aspects ?? [], "command", options.observer));
+  const value = await createCommandExecutor(options.governance, options.observer)(invocation, once(() => aspects({
+    kind: "command",
+    name: command.name,
+    input: options.input,
+    request: options.request,
+    requestContext: options.requestContext,
+    services: invocation.services,
+    scope: invocation.scope,
+    metadata: command
+  }, once(() => options.handler(options.input)))));
+  return options.decode(value);
+}
+function once(next) {
+  let called = false;
+  return async () => {
+    if (called) {
+      throw new ApplicationError("Command continuation called multiple times", {
+        code: "COMMAND_CONTINUATION_REUSED"
+      });
+    }
+    called = true;
+    return await next();
+  };
+}
 function requireTrustedIdentity(requestContext) {
   const context = isRecord(requestContext) ? requestContext : {};
   const identity = isTrustedIdentity(context.identity) ? context.identity : undefined;
@@ -548,7 +747,7 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
     }
   }
   const requestContexts = new WeakMap;
-  const governanceExecutor = options.commandGovernance ? createCommandExecutor(options.commandGovernance) : undefined;
+  const governanceExecutor = options.commandGovernance ? createCommandExecutor(options.commandGovernance, options.onExecution) : undefined;
   const commandExecutor = options.commandExecutor && governanceExecutor ? composeCommandExecutors(options.commandExecutor, governanceExecutor) : options.commandExecutor ?? governanceExecutor;
   const plugin = new Elysia({ name: `supacloud:${compiled.name}` }).decorate("services", services);
   const createRequestScope = compiled.createRequestScope;
@@ -614,7 +813,13 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
           scope: requestScope,
           requestContext
         };
-        const invoke = () => route.invoker ? route.invoker(instance, input) : Reflect.apply(method, instance, [input]);
+        const handlerCall = () => route.invoker ? route.invoker(instance, input) : Reflect.apply(method, instance, [input]);
+        const invoke = once(() => route.command && options.commandGovernance ? handlerCall() : observeExecution(options.onExecution, {
+          kind: route.command ? "command" : "route",
+          operation: route.command ?? `${route.method} ${path}`,
+          stage: "handler",
+          requestId: executionRequestId(requestContext)
+        }, handlerCall));
         const routeContext = {
           kind: "route",
           name: `${route.method} ${path}`,
@@ -637,9 +842,9 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
           metadata: command ?? route
         };
         const commandAspects = route.command ? commandsByClassName.get(route.command)?.aspects ?? [] : [];
-        const routePipeline = composeAspects(...route.aspects ?? []);
-        const commandPipeline = composeAspects(...commandAspects);
-        const modulePipeline = composeAspects(...compiled.aspects ?? []);
+        const routePipeline = observedAspects(route.aspects ?? [], "route", options.onExecution);
+        const commandPipeline = observedAspects(commandAspects, "command", options.onExecution);
+        const modulePipeline = observedAspects(compiled.aspects ?? [], `module:${compiled.name}`, options.onExecution);
         const invokeRoute = () => routePipeline(routeContext, () => route.command ? commandPipeline(commandContext, () => invokeCommand()) : invoke());
         const invokeCommand = () => {
           if (!route.command)
@@ -663,7 +868,12 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
             scope: requestScope,
             services
           };
-          return commandExecutor(invocation, invoke);
+          return observeExecution(options.onExecution, {
+            kind: "command",
+            operation: command.name,
+            stage: "commandExecutor",
+            requestId: executionRequestId(requestContext)
+          }, () => commandExecutor(invocation, invoke));
         };
         return modulePipeline(route.command ? commandContext : routeContext, invokeRoute);
       };
@@ -694,7 +904,7 @@ function createModulePlugin(compiled, services, ctxFactory = defaultRequestConte
   }
   return plugin;
 }
-async function executeJob(compiled, services, job, input, requestContext, imported = {}, executor) {
+async function executeJob(compiled, services, job, input, requestContext, imported = {}, executor, observer) {
   const jobScope = job.scope === "job" && compiled.createJobScope ? await compiled.createJobScope(services, requestContext, imported) : undefined;
   try {
     const source = job.scope === "job" ? jobScope : services;
@@ -719,9 +929,20 @@ async function executeJob(compiled, services, job, input, requestContext, import
       services,
       metadata: job
     };
-    const invoke = () => Reflect.apply(method, instance, [input]);
-    const pipeline = composeAspects(...compiled.aspects ?? [], ...job.aspects ?? []);
-    return await pipeline(context, executor ? () => executor(invocation, invoke) : invoke);
+    const invoke = once(() => observeExecution(observer, {
+      kind: "job",
+      operation: job.name,
+      stage: "handler",
+      requestId: executionRequestId(requestContext)
+    }, () => Reflect.apply(method, instance, [input])));
+    const pipeline = observedAspects(compiled.aspects ?? [], `module:${compiled.name}`, observer);
+    const jobPipeline = observedAspects(job.aspects ?? [], "job", observer);
+    return await pipeline(context, () => jobPipeline(context, () => observeExecution(observer, {
+      kind: "job",
+      operation: job.name,
+      stage: "jobExecutor",
+      requestId: executionRequestId(requestContext)
+    }, executor ? () => executor(invocation, invoke) : invoke)));
   } finally {
     if (jobScope && compiled.destroyJobScope) {
       await compiled.destroyJobScope(jobScope);
@@ -781,7 +1002,8 @@ function createApplication(options) {
     app.use(createModulePlugin(module, services, ctxFactory, {
       commandGovernance: options.commandGovernance,
       commandExecutor: options.commandExecutor,
-      errorMapper: options.errorMapper
+      errorMapper: options.errorMapper,
+      onExecution: options.onExecution
     }, imported));
   }
   return app;
@@ -802,10 +1024,13 @@ export {
   createMemoryPolicy,
   createMemorySandbox,
   createModulePlugin,
+  createSupAuthRequestContext,
   createSupaCloudRequestContext,
   createTestApp,
   defaultErrorResponse,
+  executeCompiledCommand,
   executeJob,
   requireIdempotencyKey,
-  requireTrustedIdentity
+  requireTrustedIdentity,
+  validatedJsonResponse
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supacloud/elysia",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Elysia runtime adapter for SupaCloud compiled modules: application/request scopes, route registration and validation",
   "type": "module",
   "main": "./dist/index.js",
@@ -19,7 +19,7 @@
   ],
   "scripts": {
     "build": "bun run clean && bun run build:js && bun run build:types",
-    "build:js": "bun build src/index.ts --outdir dist --target node --external elysia",
+    "build:js": "bun build src/index.ts --outdir dist --target node --external elysia --external jose",
     "build:types": "tsc -p tsconfig.json --emitDeclarationOnly",
     "clean": "rm -rf dist",
     "prepublishOnly": "bun run build",
@@ -40,6 +40,9 @@
     "url": "https://github.com/vibeunion/supacloud.git",
     "directory": "packages/elysia"
   },
+  "dependencies": {
+    "jose": "^6.2.11"
+  },
   "peerDependencies": {
     "elysia": "^1.4.30"
   },