@objectstack/plugin-hono-server 4.0.3 → 4.0.5

package/README.md

@@ -8,6 +8,7 @@ HTTP Server adapter for ObjectStack using Hono.
 - **Fast**: Built on Hono, a high-performance web framework.
 - **Full Protocol Support**: Automatically provides all ObjectStack Runtime endpoints (Auth, Data, Metadata, etc.).
 - **Middleware**: Supports standard Hono middleware.
+- **Wildcard CORS**: Supports wildcard patterns in CORS origins (compatible with better-auth).
 
 ## Usage
 
@@ -18,7 +19,7 @@ import { HonoServerPlugin } from '@objectstack/plugin-hono-server';
 const kernel = new ObjectKernel();
 
 // Register the server plugin
-kernel.use(new HonoServerPlugin({ 
+kernel.use(new HonoServerPlugin({
   port: 3000,
   restConfig: {
       api: {
@@ -30,6 +31,97 @@ kernel.use(new HonoServerPlugin({
 await kernel.start();
 ```
 
+## CORS Configuration
+
+The Hono server plugin supports flexible CORS configuration with wildcard pattern matching.
+
+### Basic CORS
+
+```typescript
+kernel.use(new HonoServerPlugin({
+  port: 3000,
+  cors: {
+    origins: ['https://app.example.com'],
+    credentials: true
+  }
+}));
+```
+
+### Wildcard Patterns (better-auth compatible)
+
+```typescript
+// Subdomain wildcards
+kernel.use(new HonoServerPlugin({
+  cors: {
+    origins: ['https://*.objectui.org', 'https://*.objectstack.ai'],
+    credentials: true
+  }
+}));
+
+// Port wildcards (useful for development)
+kernel.use(new HonoServerPlugin({
+  cors: {
+    origins: 'http://localhost:*'
+  }
+}));
+
+// Comma-separated patterns
+kernel.use(new HonoServerPlugin({
+  cors: {
+    origins: 'https://*.objectui.org,https://*.objectstack.ai,http://localhost:*'
+  }
+}));
+```
+
+### Environment Variables
+
+CORS can also be configured via environment variables:
+
+```bash
+# Single origin
+CORS_ORIGIN=https://app.example.com
+
+# Wildcard patterns (comma-separated)
+CORS_ORIGIN=https://*.objectui.org,https://*.objectstack.ai
+
+# Disable CORS
+CORS_ENABLED=false
+
+# Additional options
+CORS_CREDENTIALS=true
+CORS_MAX_AGE=86400
+```
+
+### Disable CORS
+
+```typescript
+kernel.use(new HonoServerPlugin({
+  cors: false  // Completely disable CORS
+}));
+```
+
+### 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

@@ -1,9 +1,60 @@
-import { Plugin, PluginContext, IHttpServer, RouteHandler, Middleware } from '@objectstack/core';
+import { IHttpServer, RouteHandler, Middleware, Plugin, PluginContext } from '@objectstack/core';
 export * from '@objectstack/core';
 import { RestServerConfig } from '@objectstack/spec/api';
 import * as hono_types from 'hono/types';
 import { Hono } from 'hono';
 
+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;
+}
+/**
+ * Hono Implementation of IHttpServer
+ */
+declare class HonoHttpServer implements IHttpServer {
+    private port;
+    private staticRoot?;
+    private app;
+    private server;
+    private listeningPort;
+    constructor(port?: number, staticRoot?: string | undefined);
+    private wrap;
+    get(path: string, handler: RouteHandler): void;
+    post(path: string, handler: RouteHandler): void;
+    put(path: string, handler: RouteHandler): void;
+    delete(path: string, handler: RouteHandler): void;
+    patch(path: string, handler: RouteHandler): void;
+    use(pathOrHandler: string | Middleware, handler?: Middleware): void;
+    /**
+     * Mount a sub-application or router
+     */
+    mount(path: string, subApp: Hono): void;
+    listen(port: number): Promise<void>;
+    private tryListen;
+    getPort(): number;
+    getRawApp(): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+    close(): Promise<void>;
+}
+
 interface StaticMount {
     root: string;
     path?: string;
@@ -38,6 +89,13 @@ interface HonoPluginOptions {
      * @default false
      */
     spaFallback?: boolean;
+    /**
+     * CORS configuration. Set to `false` to disable entirely.
+     * Enabled by default with origin '*'.
+     * Can also be controlled via environment variables:
+     *   CORS_ENABLED, CORS_ORIGIN, CORS_CREDENTIALS, CORS_MAX_AGE
+     */
+    cors?: HonoCorsOptions | false;
 }
 /**
  * Hono Server Plugin
@@ -79,31 +137,64 @@ declare class HonoServerPlugin implements Plugin {
 }
 
 /**
- * Hono Implementation of IHttpServer
+ * 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.
  */
-declare class HonoHttpServer implements IHttpServer {
-    private port;
-    private staticRoot?;
-    private app;
-    private server;
-    private listeningPort;
-    constructor(port?: number, staticRoot?: string | undefined);
-    private wrap;
-    get(path: string, handler: RouteHandler): void;
-    post(path: string, handler: RouteHandler): void;
-    put(path: string, handler: RouteHandler): void;
-    delete(path: string, handler: RouteHandler): void;
-    patch(path: string, handler: RouteHandler): void;
-    use(pathOrHandler: string | Middleware, handler?: Middleware): void;
-    /**
-     * Mount a sub-application or router
-     */
-    mount(path: string, subApp: Hono): void;
-    listen(port: number): Promise<void>;
-    private tryListen;
-    getPort(): number;
-    getRawApp(): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
-    close(): Promise<void>;
-}
+/**
+ * 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 { HonoHttpServer, type HonoPluginOptions, HonoServerPlugin, type StaticMount };
+export { type HonoCorsOptions, HonoHttpServer, type HonoPluginOptions, HonoServerPlugin, type StaticMount, createOriginMatcher, hasWildcardPattern, isLocalhostOrigin, matchOriginPattern, normalizeOriginPatterns };

package/dist/index.d.ts

@@ -1,9 +1,60 @@
-import { Plugin, PluginContext, IHttpServer, RouteHandler, Middleware } from '@objectstack/core';
+import { IHttpServer, RouteHandler, Middleware, Plugin, PluginContext } from '@objectstack/core';
 export * from '@objectstack/core';
 import { RestServerConfig } from '@objectstack/spec/api';
 import * as hono_types from 'hono/types';
 import { Hono } from 'hono';
 
+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;
+}
+/**
+ * Hono Implementation of IHttpServer
+ */
+declare class HonoHttpServer implements IHttpServer {
+    private port;
+    private staticRoot?;
+    private app;
+    private server;
+    private listeningPort;
+    constructor(port?: number, staticRoot?: string | undefined);
+    private wrap;
+    get(path: string, handler: RouteHandler): void;
+    post(path: string, handler: RouteHandler): void;
+    put(path: string, handler: RouteHandler): void;
+    delete(path: string, handler: RouteHandler): void;
+    patch(path: string, handler: RouteHandler): void;
+    use(pathOrHandler: string | Middleware, handler?: Middleware): void;
+    /**
+     * Mount a sub-application or router
+     */
+    mount(path: string, subApp: Hono): void;
+    listen(port: number): Promise<void>;
+    private tryListen;
+    getPort(): number;
+    getRawApp(): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
+    close(): Promise<void>;
+}
+
 interface StaticMount {
     root: string;
     path?: string;
@@ -38,6 +89,13 @@ interface HonoPluginOptions {
      * @default false
      */
     spaFallback?: boolean;
+    /**
+     * CORS configuration. Set to `false` to disable entirely.
+     * Enabled by default with origin '*'.
+     * Can also be controlled via environment variables:
+     *   CORS_ENABLED, CORS_ORIGIN, CORS_CREDENTIALS, CORS_MAX_AGE
+     */
+    cors?: HonoCorsOptions | false;
 }
 /**
  * Hono Server Plugin
@@ -79,31 +137,64 @@ declare class HonoServerPlugin implements Plugin {
 }
 
 /**
- * Hono Implementation of IHttpServer
+ * 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.
  */
-declare class HonoHttpServer implements IHttpServer {
-    private port;
-    private staticRoot?;
-    private app;
-    private server;
-    private listeningPort;
-    constructor(port?: number, staticRoot?: string | undefined);
-    private wrap;
-    get(path: string, handler: RouteHandler): void;
-    post(path: string, handler: RouteHandler): void;
-    put(path: string, handler: RouteHandler): void;
-    delete(path: string, handler: RouteHandler): void;
-    patch(path: string, handler: RouteHandler): void;
-    use(pathOrHandler: string | Middleware, handler?: Middleware): void;
-    /**
-     * Mount a sub-application or router
-     */
-    mount(path: string, subApp: Hono): void;
-    listen(port: number): Promise<void>;
-    private tryListen;
-    getPort(): number;
-    getRawApp(): Hono<hono_types.BlankEnv, hono_types.BlankSchema, "/">;
-    close(): Promise<void>;
-}
+/**
+ * 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 { HonoHttpServer, type HonoPluginOptions, HonoServerPlugin, type StaticMount };
+export { type HonoCorsOptions, HonoHttpServer, type HonoPluginOptions, HonoServerPlugin, type StaticMount, createOriginMatcher, hasWildcardPattern, isLocalhostOrigin, matchOriginPattern, normalizeOriginPatterns };