@voyant-travel/hono 0.128.5 → 0.129.0

package/dist/app.js

@@ -5,7 +5,9 @@ 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 { composeAuthAugmentations } from "./auth-augmentation.js";
 import { expandApiBundles, isLazyApiBundle, } from "./bundle.js";
+import { assembleClientAuthenticatedRoutes, matchesClientAuthenticatedRoute, } from "./client-authenticated-routes.js";
 import { mountLazyRoutePaths, mountLazyRoutesAt } from "./lazy-routes.js";
 import { mountAuthForwarding } from "./lib/auth-forward.js";
 import { createPathDbSelector } from "./lib/db-selector.js";
@@ -104,6 +106,8 @@ export function mountApp(config) {
         ...(expanded?.anonymousPaths ?? []),
         ...lazyPlugins.flatMap((plugin) => plugin.anonymous ?? []),
     ]);
+    const clientAuthenticatedRoutes = assembleClientAuthenticatedRoutes(allModules);
+    const composedAuth = composeAuthAugmentations(config.auth, allModules);
     // When the framework owns the bus, route subscriber-dispatch failures
     // (including the workflow forwarder) to the reporter — they're otherwise
     // only console-logged per the fire-and-forget EventBus contract (RFC #1553).
@@ -404,7 +408,9 @@ export function mountApp(config) {
                 const pathname = normalizePathname(new URL(c.req.url).pathname, {
                     basePath: config.basePath,
                 });
-                const isPublicWrite = pathname.startsWith("/v1/public/") || matchesPublicPath(pathname, anonymousPaths);
+                const isPublicWrite = pathname.startsWith("/v1/public/") ||
+                    matchesPublicPath(pathname, anonymousPaths) ||
+                    matchesClientAuthenticatedRoute(c.req.method, pathname, clientAuthenticatedRoutes);
                 if (!isPublicWrite)
                     return next();
                 return rateLimit(buildRateLimitPolicy(rateLimitConfig, c.env, "public-write", publicWriteRule))(c, next);
@@ -460,7 +466,7 @@ export function mountApp(config) {
     app.get("/health", (c) => c.json({ status: "ok" }));
     // App-owned auth handler (must be before auth middleware — these routes are
     // public). Forwarding + observability bridging live in `mountAuthForwarding`.
-    const authHandler = config.auth?.handler;
+    const authHandler = composedAuth?.handler;
     if (authHandler) {
         mountAuthForwarding(app, authHandler, { reporter, appName });
     }
@@ -475,7 +481,12 @@ export function mountApp(config) {
             transactionalPrefixes: txPrefixes,
         })
         : config.db;
-    const authOptions = { publicPaths: anonymousPaths, basePath: config.basePath, auth: config.auth };
+    const authOptions = {
+        publicPaths: anonymousPaths,
+        clientAuthenticatedRoutes,
+        basePath: config.basePath,
+        auth: composedAuth,
+    };
     // Auth middleware for all other routes
     app.use("*", requireAuth(dbSource, authOptions));
     // DB middleware — sets c.var.db for all downstream handlers.
@@ -502,6 +513,7 @@ export function mountApp(config) {
         basePath: config.basePath,
         resources: config.accessResources,
         accessCatalog: config.accessCatalog,
+        clientAuthenticatedRoutes,
     };
     app.use("/v1/admin/*", requireActor(actorOptions, "staff"));
     app.use("/v1/public/*", requireActor(actorOptions, "customer", "partner", "supplier"));

package/dist/auth-augmentation.d.ts

@@ -0,0 +1,4 @@
+import type { ApiModule } from "./module.js";
+import type { VoyantAuthIntegration, VoyantBindings } from "./types.js";
+/** Compose trusted package app-token resolvers while preserving host auth. */
+export declare function composeAuthAugmentations<TBindings extends VoyantBindings>(hostAuth: VoyantAuthIntegration<TBindings> | undefined, modules: readonly ApiModule[]): VoyantAuthIntegration<TBindings> | undefined;

package/dist/auth-augmentation.js

@@ -0,0 +1,21 @@
+/** Compose trusted package app-token resolvers while preserving host auth. */
+export function composeAuthAugmentations(hostAuth, modules) {
+    const packageResolvers = modules.flatMap((module) => module.authAugmentation ? [module.authAugmentation.resolveAppToken] : []);
+    if (packageResolvers.length === 0)
+        return hostAuth;
+    const hostResolver = hostAuth?.resolveAppToken;
+    return {
+        ...hostAuth,
+        resolveAppToken: async (args) => {
+            const hostResult = await hostResolver?.(args);
+            if (hostResult)
+                return hostResult;
+            for (const resolve of packageResolvers) {
+                const result = await resolve(args);
+                if (result)
+                    return result;
+            }
+            return null;
+        },
+    };
+}

package/dist/client-authenticated-routes.d.ts

@@ -0,0 +1,8 @@
+import type { ApiModule, ClientAuthenticatedRoute } from "./module.js";
+export interface AbsoluteClientAuthenticatedRoute {
+    method: ClientAuthenticatedRoute["method"];
+    path: string;
+}
+/** Resolve trusted module declarations to exact, app-local admin routes. */
+export declare function assembleClientAuthenticatedRoutes(modules: readonly ApiModule[]): AbsoluteClientAuthenticatedRoute[];
+export declare function matchesClientAuthenticatedRoute(method: string, pathname: string, routes: readonly AbsoluteClientAuthenticatedRoute[]): boolean;

package/dist/client-authenticated-routes.js

@@ -0,0 +1,20 @@
+/** Resolve trusted module declarations to exact, app-local admin routes. */
+export function assembleClientAuthenticatedRoutes(modules) {
+    const routes = new Map();
+    for (const module of modules) {
+        const prefix = `/v1/admin/${module.module.name}`;
+        for (const route of module.clientAuthenticated ?? []) {
+            const trimmed = route.path.trim();
+            if (!trimmed.startsWith("/") || trimmed.includes(":") || trimmed.includes("*")) {
+                throw new Error(`clientAuthenticated route for module "${module.module.name}" must be a concrete relative path beginning with "/"`);
+            }
+            const path = `${prefix}${trimmed === "/" ? "" : trimmed.replace(/\/+$/g, "")}`;
+            const resolved = { method: route.method, path };
+            routes.set(`${resolved.method} ${resolved.path}`, resolved);
+        }
+    }
+    return [...routes.values()].sort((left, right) => `${left.method} ${left.path}`.localeCompare(`${right.method} ${right.path}`));
+}
+export function matchesClientAuthenticatedRoute(method, pathname, routes) {
+    return routes.some((route) => route.method === method.toUpperCase() && route.path === pathname);
+}

package/dist/middleware/auth.d.ts

@@ -1,7 +1,9 @@
 import type { MiddlewareHandler } from "hono";
+import type { AbsoluteClientAuthenticatedRoute } from "../client-authenticated-routes.js";
 import { type DbSource, type VoyantAuthIntegration, type VoyantBindings, type VoyantVariables } from "../types.js";
 export declare function requireAuth<TBindings extends VoyantBindings>(dbSource: DbSource<TBindings>, opts?: {
     publicPaths?: string[];
+    clientAuthenticatedRoutes?: readonly AbsoluteClientAuthenticatedRoute[];
     basePath?: string;
     auth?: VoyantAuthIntegration<TBindings>;
 }): MiddlewareHandler<{

package/dist/middleware/auth.js

@@ -3,6 +3,7 @@ import { API_KEY_AUDIENCES, permissionsToStrings } from "@voyant-travel/types/ap
 import { and, eq, sql } from "drizzle-orm";
 import { constantTimeEqual, sha256Base64Url, sha256Hex } from "../auth/crypto.js";
 import { extractBearerToken, verifySession } from "../auth/session-jwt.js";
+import { matchesClientAuthenticatedRoute } from "../client-authenticated-routes.js";
 import { tryGetExecutionCtx } from "../lib/execution-ctx.js";
 import { matchesPublicPath, normalizePathname } from "../lib/public-paths.js";
 import { selectDbFactory, } from "../types.js";
@@ -152,6 +153,8 @@ function applyAuthContext(c, auth) {
         c.set("appTokenMode", auth.appTokenMode);
     if (auth.appViewerId)
         c.set("appViewerId", auth.appViewerId);
+    if (auth.appContextConstraint)
+        c.set("appContextConstraint", auth.appContextConstraint);
 }
 export function requireAuth(dbSource, opts) {
     const publicPaths = opts?.publicPaths ?? [];
@@ -167,6 +170,9 @@ export function requireAuth(dbSource, opts) {
         const isHealthCheck = p === "/health";
         if (isPublicAuth || isHealthCheck)
             return next();
+        if (matchesClientAuthenticatedRoute(c.req.method, p, opts?.clientAuthenticatedRoutes ?? [])) {
+            return next();
+        }
         if (matchesPublicPath(p, publicPaths)) {
             if (p.startsWith("/v1/public/")) {
                 c.set("actor", "customer");
@@ -283,8 +289,11 @@ export function requireAuth(dbSource, opts) {
                 await lease.release();
             }
         }
-        // Strategy 3: Remote app access token support
-        if (token && opts?.auth?.resolveAppToken) {
+        // Strategy 3: Remote app access token support. App grants authorize only
+        // the installation-scoped App API; never resolve them on admin/public
+        // surfaces where similarly named scopes may protect broader host routes.
+        const isAppApi = p === "/v1/app" || p.startsWith("/v1/app/");
+        if (token && isAppApi && opts?.auth?.resolveAppToken) {
             const lease = acquireRequestDb(c, dbFactory);
             try {
                 const resolved = await opts.auth.resolveAppToken({

package/dist/middleware/require-actor.d.ts

@@ -1,6 +1,7 @@
 import type { Actor } from "@voyant-travel/core";
 import { type AccessCatalog } from "@voyant-travel/types/api-keys";
 import type { MiddlewareHandler } from "hono";
+import type { AbsoluteClientAuthenticatedRoute } from "../client-authenticated-routes.js";
 import type { VoyantBindings, VoyantVariables } from "../types.js";
 /**
  * Staff-session RBAC enforcement (member-rbac-rfc, voyant#2085). Enforced **by
@@ -24,6 +25,8 @@ export interface RequireActorOptions {
         authorization?: "coarse" | "route";
     }[];
     accessCatalog?: AccessCatalog;
+    /** Exact admin protocol routes that authenticate their client in-band. */
+    clientAuthenticatedRoutes?: readonly AbsoluteClientAuthenticatedRoute[];
 }
 /**
  * Guards a route surface by actor type.

package/dist/middleware/require-actor.js

@@ -1,4 +1,5 @@
 import { hasApiKeyPermission, permissionStringsToPermissions, } from "@voyant-travel/types/api-keys";
+import { matchesClientAuthenticatedRoute } from "../client-authenticated-routes.js";
 import { normalizePathname } from "../lib/public-paths.js";
 /**
  * Route surfaces exempt from the coarse method+path permission guard because
@@ -98,12 +99,15 @@ export function requireActor(...args) {
     return async (c, next) => {
         if (c.req.method === "OPTIONS")
             return next();
+        const pathname = normalizePathname(new URL(c.req.url).pathname, {
+            basePath: options.basePath,
+        });
+        if (matchesClientAuthenticatedRoute(c.req.method, pathname, options.clientAuthenticatedRoutes ?? [])) {
+            return next();
+        }
         if (c.get("callerType") === "api_key" ||
             c.get("callerType") === "app" ||
             c.get("callerType") === "internal") {
-            const pathname = normalizePathname(new URL(c.req.url).pathname, {
-                basePath: options.basePath,
-            });
             const { resource, authorization } = authorizationForRequest(pathname, options);
             // Coarse-guard-exempt surfaces. `_meta` (capability discovery) and `mcp`
             // (the agent tool server) are dispatch surfaces where authorization is
@@ -139,9 +143,6 @@ export function requireActor(...args) {
         // resource (e.g. `_meta`) stay open until a module is explicitly covered.
         if (actor === "staff" && c.get("callerType") === "session" && isStaffRbacEnforced(c.env)) {
             const scopes = c.get("scopes");
-            const pathname = normalizePathname(new URL(c.req.url).pathname, {
-                basePath: options.basePath,
-            });
             const { resource, authorization } = authorizationForRequest(pathname, options);
             if (resource && authorization !== "route" && !isCoarseGuardExempt(resource)) {
                 const actions = apiKeyPermissionActionsForMethod(c.req.method, pathname);

package/dist/module.d.ts

@@ -1,6 +1,7 @@
 import type { Extension, Module } from "@voyant-travel/core";
 import type { Hono } from "hono";
 import type { LazyApiRoutes, LazyRoutesLoader } from "./lazy-routes.js";
+import type { VoyantAuthIntegration } from "./types.js";
 export interface ApiModule {
     module: Module;
     /** Staff-facing routes — mounted at `/v1/admin/{module.name}`. */
@@ -56,6 +57,23 @@ export interface ApiModule {
      * require a `staff` actor.
      */
     anonymous?: boolean | readonly string[];
+    /**
+     * Concrete admin endpoints whose credential is validated by the route itself
+     * instead of by the staff-session middleware. Each declaration is matched by
+     * exact HTTP method and exact path; it never opens sibling or child routes.
+     *
+     * This is intentionally narrower than `anonymous`: use it only for protocol
+     * endpoints such as an OAuth token exchange where client authentication is
+     * part of the request body or Authorization header. The handler remains
+     * responsible for validating that client credential.
+     */
+    clientAuthenticated?: readonly ClientAuthenticatedRoute[];
+    /**
+     * Trusted package-owned additions to the host authentication pipeline.
+     * Augmentations are composed after any host app-token resolver and do not
+     * replace staff session handling or any other host auth hook.
+     */
+    authAugmentation?: ApiAuthAugmentation;
     /**
      * Absolute API path prefixes whose requests must be served by the
      * transaction-capable db client (ADR-0008). For modules whose
@@ -69,6 +87,14 @@ export interface ApiModule {
      */
     transactionalPaths?: readonly string[];
 }
+export interface ClientAuthenticatedRoute {
+    method: "POST";
+    /** Concrete path relative to `/v1/admin/{module.name}`. */
+    path: string;
+}
+export interface ApiAuthAugmentation {
+    resolveAppToken: NonNullable<VoyantAuthIntegration["resolveAppToken"]>;
+}
 export interface ApiExtension {
     extension: Extension;
     /** Staff-facing routes — mounted at `/v1/admin/{extension.module}`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voyant-travel/hono",
-  "version": "0.128.5",
+  "version": "0.129.0",
   "license": "Apache-2.0",
   "type": "module",
   "exports": {
@@ -130,17 +130,17 @@
     "drizzle-orm": "^0.45.2",
     "hono": "^4.12.27",
     "zod": "^4.4.3",
-    "@voyant-travel/core": "^0.126.1",
-    "@voyant-travel/db": "^0.114.12",
+    "@voyant-travel/db": "^0.114.13",
+    "@voyant-travel/core": "^0.127.0",
     "@voyant-travel/types": "^0.109.4",
     "@voyant-travel/utils": "^0.107.1",
-    "@voyant-travel/workflows": "^0.122.4"
+    "@voyant-travel/workflows": "^0.122.6"
   },
   "devDependencies": {
     "typescript": "^6.0.3",
     "vitest": "^4.1.9",
     "@voyant-travel/voyant-typescript-config": "^0.1.0",
-    "@voyant-travel/workflows-orchestrator": "^0.122.4"
+    "@voyant-travel/workflows-orchestrator": "^0.122.6"
   },
   "files": [
     "dist"