@voyant-travel/hono 0.127.1 → 0.128.0

package/README.md

@@ -1,7 +1,8 @@
 # @voyant-travel/hono
 
-Hono transport adapter for Voyant. Provides `createApp()`, middleware, auth
-helpers, and plugin expansion for mounting Voyant modules behind a Hono app.
+Voyant's sole server API runtime implementation. Provides `createApp()`,
+middleware, auth helpers, and API bundle expansion for mounting Voyant modules
+behind a Hono app.
 
 ## Install
 
@@ -52,8 +53,8 @@ The middleware chain is: container → requestId → logger → errorBoundary
 | --- | --- |
 | `.` | Barrel re-exports |
 | `./app` | `createApp` factory |
-| `./module` | `HonoModule`, `HonoExtension` contracts |
-| `./bundle` | `HonoBundle`, `defineHonoBundle`, `expandHonoBundles` |
+| `./module` | `ApiModule`, `ApiExtension` contracts |
+| `./bundle` | `ApiBundle`, `defineApiBundle`, `expandApiBundles` |
 | `./middleware` | All middleware re-exports |
 | `./middleware/auth` | `requireAuth` session/API-key/JWT auth |
 | `./middleware/cors` | CORS configuration |

package/dist/anonymous-paths.d.ts

@@ -1,4 +1,4 @@
-import type { HonoExtension, HonoModule } from "./module.js";
+import type { ApiExtension, ApiModule } from "./module.js";
 /**
  * Assemble the anonymous-access allow-list (ADR-0008) from module/extension
  * `anonymous` declarations, unioned with any explicit `publicPaths` the
@@ -11,4 +11,4 @@ import type { HonoExtension, HonoModule } from "./module.js";
  * deterministic, snapshot-auditable result; the global list is what `requireAuth`
  * matches to skip auth (and stamp `actor: "customer"`).
  */
-export declare function assembleAnonymousPaths(modules: readonly HonoModule[], extensions: readonly HonoExtension[], explicit?: readonly string[]): string[];
+export declare function assembleAnonymousPaths(modules: readonly ApiModule[], extensions: readonly ApiExtension[], explicit?: readonly string[]): string[];

package/dist/anonymous-paths.js

@@ -31,7 +31,7 @@ export function assembleAnonymousPaths(modules, extensions, explicit = []) {
     // at `/v1/{name}`, matching the mount in `app.ts`. Parameterized/wildcard paths
     // are skipped (the literal `matchesPublicPath` matcher can't match them) and
     // must be declared via `anonymous` if ever needed.
-    // biome-ignore lint/suspicious/noExplicitAny: Hono sub-apps have varied env generics -- owner: hono; mirrors the HonoModule.webhookRoutes suppression.
+    // biome-ignore lint/suspicious/noExplicitAny: Hono sub-apps have varied env generics -- owner: hono; mirrors the ApiModule.webhookRoutes suppression.
     const addWebhooks = (name, routes) => {
         if (!routes)
             return;

package/dist/app.js

@@ -5,7 +5,7 @@ import { createContainer, createEventBus, createQueryRunner, } from "@voyant-tra
 import { createLinkServiceFactory } from "@voyant-travel/db/links";
 import { assembleAnonymousPaths } from "./anonymous-paths.js";
 import { containerToServiceResolver, makeFrameworkLogger, wireWorkflowRuntime, } from "./app-workflows.js";
-import { expandHonoBundles, isLazyHonoBundle, } from "./bundle.js";
+import { expandApiBundles, isLazyApiBundle, } from "./bundle.js";
 import { mountLazyRoutePaths, mountLazyRoutesAt } from "./lazy-routes.js";
 import { mountAuthForwarding } from "./lib/auth-forward.js";
 import { createPathDbSelector } from "./lib/db-selector.js";
@@ -80,14 +80,14 @@ export function mountApp(config) {
             throw new Error(`Duplicate bundle name: "${plugin.name}"`);
         }
         pluginNames.add(plugin.name);
-        if (isLazyHonoBundle(plugin))
+        if (isLazyApiBundle(plugin))
             lazyPlugins.push(plugin);
         else
             eagerPlugins.push(plugin);
     }
     // Expand eager plugins into their constituent modules/extensions before
     // mounting. Lazy plugins keep only their static metadata in the eager closure.
-    const expanded = eagerPlugins.length > 0 ? expandHonoBundles(eagerPlugins) : null;
+    const expanded = eagerPlugins.length > 0 ? expandApiBundles(eagerPlugins) : null;
     const allModules = [...(config.modules ?? []), ...(expanded?.modules ?? [])];
     const allExtensions = [...(config.extensions ?? []), ...(expanded?.extensions ?? [])];
     const linkDefinitions = [...(config.linkDefinitions ?? []), ...(expanded?.links ?? [])];
@@ -252,7 +252,7 @@ export function mountApp(config) {
         const pending = bundles.filter((bundle) => !expandedLazyBundleNames.has(bundle.name));
         if (pending.length === 0)
             return;
-        const lazyExpanded = expandHonoBundles(pending);
+        const lazyExpanded = expandApiBundles(pending);
         for (const bundle of pending)
             expandedLazyBundleNames.add(bundle.name);
         allModules.push(...lazyExpanded.modules);
@@ -604,7 +604,7 @@ export function mountApp(config) {
     }
     function buildBundleRouteApp(bundle) {
         const pluginRoutes = new OpenAPIHono();
-        const bundleExpanded = expandHonoBundles([bundle]);
+        const bundleExpanded = expandApiBundles([bundle]);
         for (const mod of bundleExpanded.modules)
             mountModuleRoutesInto(pluginRoutes, mod);
         for (const ext of bundleExpanded.extensions)

package/dist/bundle.d.ts

@@ -1,27 +1,27 @@
 import type { BootstrapHandler, EventFilterDescriptor, LinkDefinition, Subscriber, WorkflowDescriptor } from "@voyant-travel/core";
-import type { HonoExtension, HonoModule } from "./module.js";
+import type { ApiExtension, ApiModule } from "./module.js";
 /**
- * Hono-flavoured bundle contribution surface.
+ * Reusable server API contribution surface.
  *
- * `@voyant-travel/hono` is the default HTTP transport adapter for Voyant. The
- * `HonoBundle` describes reusable packages that contribute {@link HonoModule}
- * / {@link HonoExtension} wrappers that can carry HTTP routes.
+ * `@voyant-travel/hono` is Voyant's sole server API runtime implementation.
+ * `ApiBundle` describes packages that contribute {@link ApiModule} /
+ * {@link ApiExtension} wrappers carrying HTTP routes.
  *
  * Registered via `createApp({ plugins: [...] })` — the app factory expands
  * each bundle into the underlying modules, extensions, subscribers, and link
  * definitions before mounting them.
  */
-export interface HonoBundle {
+export interface ApiBundle {
     /** Unique bundle identifier (e.g. "payload-cms", "bokun"). */
     name: string;
     /** Optional version tag for diagnostics. */
     version?: string;
     /** Optional lazy runtime bootstrap executed once per app/isolate. */
     bootstrap?: BootstrapHandler;
-    /** Hono modules (module + routes) contributed by the plugin. */
-    modules?: HonoModule[];
-    /** Hono extensions (extension + routes) contributed by the plugin. */
-    extensions?: HonoExtension[];
+    /** API modules (module + routes) contributed by the plugin. */
+    modules?: ApiModule[];
+    /** API extensions (extension + routes) contributed by the plugin. */
+    extensions?: ApiExtension[];
     /** Event subscribers wired to the caller's event bus, when provided. */
     subscribers?: Subscriber[];
     /** Link definitions contributed by the plugin. */
@@ -49,15 +49,15 @@ export interface HonoBundle {
      */
     eventFilters?: readonly EventFilterDescriptor[];
 }
-declare const LAZY_HONO_BUNDLE: unique symbol;
+declare const LAZY_API_BUNDLE: unique symbol;
 /**
  * Lazy bundle declaration. The bundle's heavy runtime graph is imported only
  * when a declared route matcher is hit, unless `loadOnBootstrap` asks the app
  * to load it during request/headless bootstrap. `name` and `anonymous` remain
  * eager metadata so duplicate checks and auth allow-lists stay fail-closed.
  */
-export interface LazyHonoBundle {
-    readonly [LAZY_HONO_BUNDLE]: true;
+export interface LazyApiBundle {
+    readonly [LAZY_API_BUNDLE]: true;
     /** Unique bundle identifier matching the loaded bundle's `name`. */
     name: string;
     /** Optional version tag for diagnostics. */
@@ -94,27 +94,27 @@ export interface LazyHonoBundle {
      */
     loadOnBootstrap?: boolean;
     /** Loads and constructs the real bundle. Memoized by `mountApp`. */
-    load: () => Promise<HonoBundle>;
+    load: () => Promise<ApiBundle>;
 }
-export type HonoBundleInput = HonoBundle | LazyHonoBundle;
+export type ApiBundleInput = ApiBundle | LazyApiBundle;
 /**
  * Identity helper — returns the bundle unchanged, purely for IDE inference.
  */
-export declare function defineHonoBundle<P extends HonoBundle>(bundle: P): P;
-export declare function defineLazyHonoBundle<P extends Omit<LazyHonoBundle, typeof LAZY_HONO_BUNDLE>>(bundle: P): P & LazyHonoBundle;
-export declare function isLazyHonoBundle(bundle: HonoBundleInput): bundle is LazyHonoBundle;
-export interface ExpandedHonoBundles {
-    modules: HonoModule[];
-    extensions: HonoExtension[];
+export declare function defineApiBundle<P extends ApiBundle>(bundle: P): P;
+export declare function defineLazyApiBundle<P extends Omit<LazyApiBundle, typeof LAZY_API_BUNDLE>>(bundle: P): P & LazyApiBundle;
+export declare function isLazyApiBundle(bundle: ApiBundleInput): bundle is LazyApiBundle;
+export interface ExpandedApiBundles {
+    modules: ApiModule[];
+    extensions: ApiExtension[];
     subscribers: Subscriber[];
     links: LinkDefinition[];
     /** Absolute anonymous-access paths declared by bundles (ADR-0008). */
     anonymousPaths: string[];
 }
 /**
- * Flatten a list of {@link HonoBundle} values into their constituent pieces.
+ * Flatten a list of {@link ApiBundle} values into their constituent pieces.
  *
  * Throws if two bundles declare the same `name`.
  */
-export declare function expandHonoBundles(bundles: ReadonlyArray<HonoBundle>): ExpandedHonoBundles;
+export declare function expandApiBundles(bundles: ReadonlyArray<ApiBundle>): ExpandedApiBundles;
 export {};

package/dist/bundle.js

@@ -1,22 +1,22 @@
-const LAZY_HONO_BUNDLE = Symbol.for("voyant.hono.lazyBundle");
+const LAZY_API_BUNDLE = Symbol.for("voyant.api.lazyBundle");
 /**
  * Identity helper — returns the bundle unchanged, purely for IDE inference.
  */
-export function defineHonoBundle(bundle) {
+export function defineApiBundle(bundle) {
     return bundle;
 }
-export function defineLazyHonoBundle(bundle) {
-    return { ...bundle, [LAZY_HONO_BUNDLE]: true };
+export function defineLazyApiBundle(bundle) {
+    return { ...bundle, [LAZY_API_BUNDLE]: true };
 }
-export function isLazyHonoBundle(bundle) {
-    return bundle[LAZY_HONO_BUNDLE] === true;
+export function isLazyApiBundle(bundle) {
+    return bundle[LAZY_API_BUNDLE] === true;
 }
 /**
- * Flatten a list of {@link HonoBundle} values into their constituent pieces.
+ * Flatten a list of {@link ApiBundle} values into their constituent pieces.
  *
  * Throws if two bundles declare the same `name`.
  */
-export function expandHonoBundles(bundles) {
+export function expandApiBundles(bundles) {
     const seen = new Set();
     const modules = [];
     const extensions = [];

package/dist/composition.d.ts

@@ -1,4 +1,4 @@
-import type { HonoExtension, HonoModule } from "./module.js";
+import type { ApiExtension, ApiModule } from "./module.js";
 /**
  * Manifest-driven runtime composition.
  *
@@ -30,8 +30,8 @@ export interface CompositionContext<TCapabilities> {
     capabilities: TCapabilities;
     options: Record<string, unknown>;
 }
-export type ModuleFactory<TCapabilities> = (ctx: CompositionContext<TCapabilities>) => HonoModule | HonoModule[];
-export type ExtensionFactory<TCapabilities> = (ctx: CompositionContext<TCapabilities>) => HonoExtension;
+export type ModuleFactory<TCapabilities> = (ctx: CompositionContext<TCapabilities>) => ApiModule | ApiModule[];
+export type ExtensionFactory<TCapabilities> = (ctx: CompositionContext<TCapabilities>) => ApiExtension;
 /**
  * Maps manifest specifiers to the factory that builds the runtime unit. Keys
  * MUST match the `voyant.config.ts` `modules` / `extensions` specifiers.
@@ -41,8 +41,8 @@ export interface CompositionRegistry<TCapabilities> {
     extensions?: Record<string, ExtensionFactory<TCapabilities>>;
 }
 export interface ComposedApp {
-    modules: HonoModule[];
-    extensions: HonoExtension[];
+    modules: ApiModule[];
+    extensions: ApiExtension[];
 }
 /**
  * Derive the `createApp({ modules, extensions })` arrays from a manifest by

package/dist/index.d.ts

@@ -3,17 +3,17 @@ export { assembleAnonymousPaths } from "./anonymous-paths.js";
 export { mountApp } from "./app.js";
 export type { SessionAuthContext } from "./auth/index.js";
 export { constantTimeEqual, extractBearerToken, generateNumericCode, randomBytesHex, requireUserId, sha256Base64Url, sha256Hex, unsignCookie, verifySession, } from "./auth/index.js";
-export type { ExpandedHonoBundles, HonoBundle, HonoBundleInput, LazyHonoBundle, } from "./bundle.js";
-export { defineHonoBundle, defineLazyHonoBundle, expandHonoBundles, isLazyHonoBundle, } from "./bundle.js";
+export type { ApiBundle, ApiBundleInput, ExpandedApiBundles, LazyApiBundle, } from "./bundle.js";
+export { defineApiBundle, defineLazyApiBundle, expandApiBundles, isLazyApiBundle, } from "./bundle.js";
 export { type CreateAppConfig, createApp } from "./create-app.js";
 export type { AuthenticatedDocumentDownloadResolver, AuthenticatedDocumentDownloadResolverOptions, DocumentDownloadEnvelope, DocumentDownloadResolution, DocumentDownloadResolver, DocumentDownloadResolverResult, StoredDocumentReference, } from "./document-download.js";
 export { createAuthenticatedDocumentDownloadResolver, encodeStorageKeyPath, resolveStoredDocumentDownload, } from "./document-download.js";
 export { type AsyncMethodProvider, lazyProvider } from "./lazy-provider.js";
-export { createLazyRouteHandler, type LazyHonoRoutes, type LazyRoutesLoader, mountLazyRoutePaths, mountLazyRoutesAt, } from "./lazy-routes.js";
+export { createLazyRouteHandler, type LazyApiRoutes, type LazyRoutesLoader, mountLazyRoutePaths, mountLazyRoutesAt, } from "./lazy-routes.js";
 export { createPathDbSelector, type PathDbSelectorOptions } from "./lib/db-selector.js";
 export type { RateLimitStore } from "./middleware/index.js";
 export { clientIpKey, consoleLoggerProvider, cors, createMemoryRateLimitStore, createRedisRateLimitStore, DEFAULT_IDEMPOTENCY_TTL_MS, db, enforceRateLimit, errorBoundary, handleApiError, type IdempotencyKeyOptions, idempotencyKey, isStaffRbacEnforced, LIVE_LIMITS, logger, purgeExpiredIdempotencyKeys, rateLimit, requestId, requireActor, requireAuth, requirePermission, } from "./middleware/index.js";
-export type { HonoExtension, HonoModule } from "./module.js";
+export type { ApiExtension, ApiModule } from "./module.js";
 export type { ErrorEvent, Reporter } from "./observability/index.js";
 export { consoleReporter, getRequestId, noopReporter, runWithRequestId, safeCaptureException, } from "./observability/index.js";
 export { stampOpenApiRegistryApiId } from "./openapi-ownership.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { assembleAnonymousPaths } from "./anonymous-paths.js";
 export { mountApp } from "./app.js";
 export { constantTimeEqual, extractBearerToken, generateNumericCode, randomBytesHex, requireUserId, sha256Base64Url, sha256Hex, unsignCookie, verifySession, } from "./auth/index.js";
-export { defineHonoBundle, defineLazyHonoBundle, expandHonoBundles, isLazyHonoBundle, } from "./bundle.js";
+export { defineApiBundle, defineLazyApiBundle, expandApiBundles, isLazyApiBundle, } from "./bundle.js";
 export { createApp } from "./create-app.js";
 export { createAuthenticatedDocumentDownloadResolver, encodeStorageKeyPath, resolveStoredDocumentDownload, } from "./document-download.js";
 export { lazyProvider } from "./lazy-provider.js";

package/dist/lazy-routes.d.ts

@@ -38,7 +38,7 @@ export type LazyRoutesLoader = () => Promise<AnyHono>;
  * matchers the framework installs up front (no bundle import until a request
  * matches).
  */
-export interface LazyHonoRoutes {
+export interface LazyApiRoutes {
     paths: readonly string[];
     load: LazyRoutesLoader;
 }

package/dist/middleware/auth.js

@@ -122,8 +122,15 @@ function applyAuthContext(c, auth) {
         c.set("callerType", auth.callerType);
     if (auth.actor)
         c.set("actor", auth.actor);
-    if (auth.audience)
+    if (auth.audience !== undefined) {
         c.set("audience", auth.audience);
+    }
+    else if (auth.actor) {
+        // VoyantAuthContext defines an omitted grant audience as the authenticated
+        // actor. Normalize once here so every downstream surface, including MCP,
+        // receives the same complete authorization context.
+        c.set("audience", auth.actor);
+    }
     if (auth.scopes !== undefined)
         c.set("scopes", auth.scopes);
     if (auth.isInternalRequest !== undefined)

package/dist/module.d.ts

@@ -1,7 +1,7 @@
 import type { Extension, Module } from "@voyant-travel/core";
 import type { Hono } from "hono";
-import type { LazyHonoRoutes, LazyRoutesLoader } from "./lazy-routes.js";
-export interface HonoModule {
+import type { LazyApiRoutes, LazyRoutesLoader } from "./lazy-routes.js";
+export interface ApiModule {
     module: Module;
     /** Staff-facing routes — mounted at `/v1/admin/{module.name}`. */
     adminRoutes?: Hono<any>;
@@ -35,7 +35,7 @@ export interface HonoModule {
      * returns ABSOLUTE routes; the framework mounts + caches them with the request
      * context bridged in. Context-preserving replacement for `mountLazyRouteApp`.
      */
-    lazyRoutes?: LazyHonoRoutes;
+    lazyRoutes?: LazyApiRoutes;
     /**
      * Optional override for the public mount path relative to `/v1/public`.
      *
@@ -69,7 +69,7 @@ export interface HonoModule {
      */
     transactionalPaths?: readonly string[];
 }
-export interface HonoExtension {
+export interface ApiExtension {
     extension: Extension;
     /** Staff-facing routes — mounted at `/v1/admin/{extension.module}`. */
     adminRoutes?: Hono<any>;
@@ -77,15 +77,15 @@ export interface HonoExtension {
     publicRoutes?: Hono<any>;
     /**
      * Inbound webhook routes — mounted at `/v1/{extension.module}`, concrete paths
-     * auto-added to the anonymous allow-list (ADR-0008). See `HonoModule.webhookRoutes`.
+     * auto-added to the anonymous allow-list (ADR-0008). See `ApiModule.webhookRoutes`.
      */
     webhookRoutes?: Hono<any>;
-    /** Lazy variant of `adminRoutes` — mounted at `/v1/admin/{extension.module}` (see HonoModule). */
+    /** Lazy variant of `adminRoutes` — mounted at `/v1/admin/{extension.module}` (see ApiModule). */
     lazyAdminRoutes?: LazyRoutesLoader;
     /** Lazy variant of `publicRoutes` — mounted at `/v1/public/{publicPath ?? extension.module}`. */
     lazyPublicRoutes?: LazyRoutesLoader;
-    /** Deployment-local lazy family at explicit absolute paths (see HonoModule). */
-    lazyRoutes?: LazyHonoRoutes;
+    /** Deployment-local lazy family at explicit absolute paths (see ApiModule). */
+    lazyRoutes?: LazyApiRoutes;
     /**
      * Optional override for the public mount path relative to `/v1/public`.
      *
@@ -95,13 +95,13 @@ export interface HonoExtension {
     publicPath?: string;
     /**
      * Declares which of this extension's PUBLIC routes are reachable without a
-     * session (ADR-0008). Same semantics as {@link HonoModule.anonymous}, relative
+     * session (ADR-0008). Same semantics as {@link ApiModule.anonymous}, relative
      * to the extension's public mount.
      */
     anonymous?: boolean | readonly string[];
     /**
      * Absolute transactional path prefixes — same semantics as
-     * {@link HonoModule.transactionalPaths}.
+     * {@link ApiModule.transactionalPaths}.
      */
     transactionalPaths?: readonly string[];
 }

package/dist/types.d.ts

@@ -7,8 +7,8 @@ import type { NeonHttpDatabase } from "drizzle-orm/neon-http";
 import type { NeonDatabase as NeonWsDatabase } from "drizzle-orm/neon-serverless";
 import type { PostgresJsDatabase } from "drizzle-orm/postgres-js";
 import type { Handler, Hono } from "hono";
-import type { HonoBundleInput } from "./bundle.js";
-import type { HonoExtension, HonoModule } from "./module.js";
+import type { ApiBundleInput } from "./bundle.js";
+import type { ApiExtension, ApiModule } from "./module.js";
 import type { Reporter } from "./observability/reporter.js";
 export interface VoyantExecutionContext {
     waitUntil?: (promise: Promise<unknown>) => void;
@@ -193,9 +193,9 @@ export interface VoyantAppConfig<TBindings extends VoyantBindings = VoyantBindin
      * together with `dbTransactional`.
      */
     dbTransactionalPaths?: string[];
-    modules?: HonoModule[];
-    extensions?: HonoExtension[];
-    plugins?: HonoBundleInput[];
+    modules?: ApiModule[];
+    extensions?: ApiExtension[];
+    plugins?: ApiBundleInput[];
     eventBus?: EventBus;
     /**
      * Link definitions activated against each request's resolved database.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/hono",
-  "version": "0.127.1",
+  "version": "0.128.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -131,17 +131,17 @@
     "hono": "^4.12.27",
     "zod": "^4.4.3",
     "@voyant-travel/core": "^0.124.0",
-    "@voyant-travel/db": "^0.114.7",
+    "@voyant-travel/db": "^0.114.8",
     "@voyant-travel/types": "^0.109.2",
     "@voyant-travel/utils": "^0.107.1",
-    "@voyant-travel/workflows": "^0.121.0"
+    "@voyant-travel/workflows": "^0.122.0"
   },
   "devDependencies": {
     "@cloudflare/workers-types": "^4.20260702.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
     "@voyant-travel/voyant-typescript-config": "^0.1.0",
-    "@voyant-travel/workflows-orchestrator": "^0.121.0"
+    "@voyant-travel/workflows-orchestrator": "^0.122.0"
   },
   "files": [
     "dist"