@objectstack/plugin-hono-server 4.0.4 → 4.1.0

package/README.md

@@ -100,6 +100,28 @@ kernel.use(new HonoServerPlugin({
 }));
 ```
 
+### Bearer token auth (`set-auth-token`)
+
+The CORS middleware always includes `set-auth-token` in `Access-Control-Expose-Headers`
+so that `@objectstack/plugin-auth`'s `bearer()` plugin can deliver rotated session
+tokens to cross-origin and mobile clients. `Authorization` is included in
+`Access-Control-Allow-Headers` by default so `Authorization: Bearer <token>`
+requests succeed preflight.
+
+You can contribute additional exposed / allowed headers — `exposeHeaders`
+entries you supply are **merged** with the `set-auth-token` default:
+
+```typescript
+kernel.use(new HonoServerPlugin({
+  cors: {
+    origins: ['https://app.example.com'],
+    credentials: true,
+    exposeHeaders: ['X-Request-Id'],           // in addition to set-auth-token
+    allowHeaders: ['Content-Type', 'Authorization', 'X-Tenant-Id'],
+  },
+}));
+```
+
 ## Architecture
 
 This plugin wraps `@objectstack/hono` to provide a turnkey HTTP server solution for the Runtime. It binds the standard `HttpDispatcher` to a Hono application and starts listening on the configured port.

package/dist/index.d.mts

@@ -8,6 +8,22 @@ interface HonoCorsOptions {
     enabled?: boolean;
     origins?: string | string[];
     methods?: string[];
+    /**
+     * Request headers allowed on preflight (`Access-Control-Allow-Headers`).
+     *
+     * Defaults to `['Content-Type', 'Authorization', 'X-Requested-With']`,
+     * which is sufficient for cookie and bearer-token auth.
+     */
+    allowHeaders?: string[];
+    /**
+     * Response headers exposed to JS (`Access-Control-Expose-Headers`).
+     *
+     * Defaults to `['set-auth-token']` so that better-auth's `bearer()` plugin
+     * can hand rotated session tokens to cross-origin clients. User-supplied
+     * values are merged with this default — `set-auth-token` is always
+     * exposed unless CORS is disabled entirely.
+     */
+    exposeHeaders?: string[];
     credentials?: boolean;
     maxAge?: number;
 }
@@ -81,6 +97,16 @@ interface HonoPluginOptions {
      */
     cors?: HonoCorsOptions | false;
 }
+/**
+ * Hono Server Plugin
+ *
+ * Provides HTTP server capabilities using Hono framework.
+ * Registers the IHttpServer service so other plugins can register routes.
+ *
+ * Route registration is handled by plugins:
+ * - `@objectstack/rest` → CRUD, metadata, discovery, UI, batch
+ * - `createDispatcherPlugin()` → auth, graphql, analytics, packages, etc.
+ */
 declare class HonoServerPlugin implements Plugin {
     name: string;
     type: string;
@@ -110,4 +136,65 @@ declare class HonoServerPlugin implements Plugin {
     destroy(): Promise<void>;
 }
 
-export { type HonoCorsOptions, HonoHttpServer, type HonoPluginOptions, HonoServerPlugin, type StaticMount };
+/**
+ * CORS origin pattern matching utilities.
+ *
+ * Supports the same wildcard syntax as better-auth's `trustedOrigins`:
+ * - `*`                         → matches any origin
+ * - `https://*.example.com`     → matches any subdomain
+ * - `http://localhost:*`        → matches any port
+ * - Comma-separated list of the above
+ *
+ * These helpers are shared between the Hono plugin's CORS middleware and
+ * consumers that need to apply CORS headers outside the Hono request
+ * pipeline (e.g., the Vercel serverless entrypoint's preflight
+ * short-circuit in `apps/objectos`). Keeping a single implementation
+ * ensures both paths stay consistent — divergence caused bug where
+ * wildcard `CORS_ORIGIN` values worked locally but produced browser
+ * CORS errors on Vercel.
+ */
+/**
+ * Returns true when the origin points to localhost (any port, http or https).
+ *
+ * Matches:
+ * - `http://localhost`
+ * - `http://localhost:3000`
+ * - `https://localhost:8443`
+ * - `http://127.0.0.1:5173`
+ * - `http://[::1]:3000`
+ */
+declare function isLocalhostOrigin(origin: string): boolean;
+/**
+ * Check if an origin matches a pattern with wildcards.
+ *
+ * Localhost origins (`http(s)://localhost:<any-port>`, `127.0.0.1`, `[::1]`)
+ * are **always allowed** regardless of the pattern — this removes the need to
+ * enumerate every development port in `CORS_ORIGIN`.
+ *
+ * @param origin The origin to check (e.g., `https://app.example.com`)
+ * @param pattern The pattern to match against (supports `*` wildcard)
+ * @returns true if origin matches the pattern
+ */
+declare function matchOriginPattern(origin: string, pattern: string): boolean;
+/**
+ * Normalize a single string / comma-separated string / array into a
+ * trimmed array of non-empty patterns.
+ */
+declare function normalizeOriginPatterns(patterns: string | string[]): string[];
+/**
+ * Create a CORS origin matcher function that supports wildcard patterns.
+ *
+ * The returned function follows Hono's `cors({ origin })` contract:
+ * given the request's `Origin` header, it returns the origin to echo
+ * back in `Access-Control-Allow-Origin`, or `null` if the origin is not
+ * allowed.
+ *
+ * @param patterns Single pattern, array of patterns, or comma-separated patterns
+ */
+declare function createOriginMatcher(patterns: string | string[]): (origin: string) => string | null;
+/**
+ * True if any pattern in the given list contains a `*` wildcard.
+ */
+declare function hasWildcardPattern(patterns: string | string[]): boolean;
+
+export { type HonoCorsOptions, HonoHttpServer, type HonoPluginOptions, HonoServerPlugin, type StaticMount, createOriginMatcher, hasWildcardPattern, isLocalhostOrigin, matchOriginPattern, normalizeOriginPatterns };

package/dist/index.d.ts

@@ -8,6 +8,22 @@ interface HonoCorsOptions {
     enabled?: boolean;
     origins?: string | string[];
     methods?: string[];
+    /**
+     * Request headers allowed on preflight (`Access-Control-Allow-Headers`).
+     *
+     * Defaults to `['Content-Type', 'Authorization', 'X-Requested-With']`,
+     * which is sufficient for cookie and bearer-token auth.
+     */
+    allowHeaders?: string[];
+    /**
+     * Response headers exposed to JS (`Access-Control-Expose-Headers`).
+     *
+     * Defaults to `['set-auth-token']` so that better-auth's `bearer()` plugin
+     * can hand rotated session tokens to cross-origin clients. User-supplied
+     * values are merged with this default — `set-auth-token` is always
+     * exposed unless CORS is disabled entirely.
+     */
+    exposeHeaders?: string[];
     credentials?: boolean;
     maxAge?: number;
 }
@@ -81,6 +97,16 @@ interface HonoPluginOptions {
      */
     cors?: HonoCorsOptions | false;
 }
+/**
+ * Hono Server Plugin
+ *
+ * Provides HTTP server capabilities using Hono framework.
+ * Registers the IHttpServer service so other plugins can register routes.
+ *
+ * Route registration is handled by plugins:
+ * - `@objectstack/rest` → CRUD, metadata, discovery, UI, batch
+ * - `createDispatcherPlugin()` → auth, graphql, analytics, packages, etc.
+ */
 declare class HonoServerPlugin implements Plugin {
     name: string;
     type: string;
@@ -110,4 +136,65 @@ declare class HonoServerPlugin implements Plugin {
     destroy(): Promise<void>;
 }
 
-export { type HonoCorsOptions, HonoHttpServer, type HonoPluginOptions, HonoServerPlugin, type StaticMount };
+/**
+ * CORS origin pattern matching utilities.
+ *
+ * Supports the same wildcard syntax as better-auth's `trustedOrigins`:
+ * - `*`                         → matches any origin
+ * - `https://*.example.com`     → matches any subdomain
+ * - `http://localhost:*`        → matches any port
+ * - Comma-separated list of the above
+ *
+ * These helpers are shared between the Hono plugin's CORS middleware and
+ * consumers that need to apply CORS headers outside the Hono request
+ * pipeline (e.g., the Vercel serverless entrypoint's preflight
+ * short-circuit in `apps/objectos`). Keeping a single implementation
+ * ensures both paths stay consistent — divergence caused bug where
+ * wildcard `CORS_ORIGIN` values worked locally but produced browser
+ * CORS errors on Vercel.
+ */
+/**
+ * Returns true when the origin points to localhost (any port, http or https).
+ *
+ * Matches:
+ * - `http://localhost`
+ * - `http://localhost:3000`
+ * - `https://localhost:8443`
+ * - `http://127.0.0.1:5173`
+ * - `http://[::1]:3000`
+ */
+declare function isLocalhostOrigin(origin: string): boolean;
+/**
+ * Check if an origin matches a pattern with wildcards.
+ *
+ * Localhost origins (`http(s)://localhost:<any-port>`, `127.0.0.1`, `[::1]`)
+ * are **always allowed** regardless of the pattern — this removes the need to
+ * enumerate every development port in `CORS_ORIGIN`.
+ *
+ * @param origin The origin to check (e.g., `https://app.example.com`)
+ * @param pattern The pattern to match against (supports `*` wildcard)
+ * @returns true if origin matches the pattern
+ */
+declare function matchOriginPattern(origin: string, pattern: string): boolean;
+/**
+ * Normalize a single string / comma-separated string / array into a
+ * trimmed array of non-empty patterns.
+ */
+declare function normalizeOriginPatterns(patterns: string | string[]): string[];
+/**
+ * Create a CORS origin matcher function that supports wildcard patterns.
+ *
+ * The returned function follows Hono's `cors({ origin })` contract:
+ * given the request's `Origin` header, it returns the origin to echo
+ * back in `Access-Control-Allow-Origin`, or `null` if the origin is not
+ * allowed.
+ *
+ * @param patterns Single pattern, array of patterns, or comma-separated patterns
+ */
+declare function createOriginMatcher(patterns: string | string[]): (origin: string) => string | null;
+/**
+ * True if any pattern in the given list contains a `*` wildcard.
+ */
+declare function hasWildcardPattern(patterns: string | string[]): boolean;
+
+export { type HonoCorsOptions, HonoHttpServer, type HonoPluginOptions, HonoServerPlugin, type StaticMount, createOriginMatcher, hasWildcardPattern, isLocalhostOrigin, matchOriginPattern, normalizeOriginPatterns };