better-auth-studio 1.1.3-beta.47 → 1.1.3-beta.49

package/README.md

@@ -187,12 +187,14 @@ pnpx better-auth-studio start [options]
 
 **Options:**
 
-- `--port <number>` - Specify port (default: 3000)
+- `--port <number>` - Specify port (default: 3002)
 - `--host <string>` - Specify host (default: localhost)
 - `--no-open` - Don't automatically open browser
 - `--config <path>` - Path to auth config file (default: auto-detect)
 - `--watch` - Watch for changes in auth config file and reload server automatically
 
+`3002` is just the standalone Studio default so it does not clash with apps that already use `3000`. You can run Studio on `3000`, `4000`, or any other free port.
+
 **Examples:**
 
 ```bash
@@ -270,6 +272,62 @@ pnpm add better-auth-studio
 
 > **Note:** The CLI usage (standalone studio) can be installed as a dev dependency, but self-hosting requires it in `dependencies` for production deployments.
 
+### Docker (Standalone Self-Host)
+
+If you want to run Better Auth Studio in its own container, this repository includes a Docker setup for the standalone CLI server.
+
+This mode is useful when:
+
+- you want a separate admin container
+- your Better Auth app already lives in its own repository
+- you want Docker-managed `node_modules` and package-manager cache volumes
+
+> **Important:** The standalone container still needs your Better Auth project mounted into it, because Studio loads your real `auth.ts` and `studio.config.*` files at runtime.
+
+Build the image from this repository:
+
+```bash
+docker build -t better-auth-studio:self-host .
+```
+
+Run it with Docker Compose:
+
+```bash
+HOST_PROJECT_PATH=/absolute/path/to/your-better-auth-project \
+CONFIG_PATH=./auth.ts \
+docker compose -f docker/compose.yml up --build
+```
+
+If your auth config is not at the project root, pass it explicitly:
+
+```bash
+HOST_PROJECT_PATH=/absolute/path/to/your-better-auth-project \
+CONFIG_PATH=./src/lib/auth.ts \
+docker compose -f docker/compose.yml up --build
+```
+
+If you already used the older filename, `docker/docker-compose.self-host.yml` still works too.
+
+What the container does:
+
+- mounts your Better Auth project into `/workspace`
+- installs project dependencies into Docker volumes on first boot
+- starts `better-auth-studio start --host 0.0.0.0 --port 3002 --no-open`
+
+Useful environment variables:
+
+- `HOST_PROJECT_PATH` - absolute path to your Better Auth project on the host machine
+- `CONFIG_PATH` - optional auth config path inside the mounted project, for example `./src/lib/auth.ts`
+- `PORT` - studio port, defaults to `3002`
+- `WATCH` - set to `true` to enable watch mode
+- `AUTO_INSTALL` - set to `false` if your container/project already has dependencies installed
+- `PROJECT_INSTALL_CMD` - optional custom install command for non-standard setups
+- `GEO_DB_PATH` - optional GeoLite database path inside the mounted project
+
+If you change the Studio port, make sure your Better Auth config also trusts that origin when needed. The examples usually include both `http://localhost:3000` and `http://localhost:3002` for that reason.
+
+If you already embed Studio in your server with the framework adapters below, that remains the recommended production setup. The Docker flow is mainly for running the standalone Studio server in a containerized environment.
+
 ### Setup
 
 **Step 1: Initialize configuration**
@@ -294,6 +352,8 @@ const config: StudioConfig = {
   access: {
     roles: ["admin"],
     allowEmails: ["admin@example.com"],
+    allowIpAddresses: ["127.0.0.1", "::1", "192.168.*"],
+    blockIpAddresses: ["203.0.113.45"],
   },
 };
 
@@ -339,15 +399,17 @@ Access at `http://localhost:3000/api/studio`
 
 ### Configuration Options
 
-| Option               | Required | Description                                                                                                                                   |
-| -------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
-| `auth`               | Yes      | Your Better Auth instance                                                                                                                     |
-| `basePath`           | Yes      | URL path where studio is mounted                                                                                                              |
-| `access.allowEmails` | No       | Array of admin email addresses                                                                                                                |
-| `access.roles`       | No       | Array of allowed user roles                                                                                                                   |
-| `ipAddress`          | No       | IP geolocation for Events/Sessions: `provider` ("ipinfo" \| "ipapi"), `apiToken`, `baseUrl`, optional `endpoint` (ipinfo: "lite" \| "lookup") |
-| `lastSeenAt`         | No       | Enable last-seen tracking: `{ enabled: true, columnName?: string }`                                                                           |
-| `metadata`           | No       | Custom branding (title, theme)                                                                                                                |
+| Option                    | Required | Description                                                                                                                                   |
+| ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auth`                    | Yes      | Your Better Auth instance                                                                                                                     |
+| `basePath`                | Yes      | URL path where studio is mounted                                                                                                              |
+| `access.allowEmails`      | No       | Array of admin email addresses                                                                                                                |
+| `access.roles`            | No       | Array of allowed user roles                                                                                                                   |
+| `access.allowIpAddresses` | No       | IP allowlist for Studio requests. Supports exact IPs and wildcard patterns (example: `192.168.*`)                                             |
+| `access.blockIpAddresses` | No       | IP blocklist for Studio requests. Supports exact IPs and wildcard patterns                                                                    |
+| `ipAddress`               | No       | IP geolocation for Events/Sessions: `provider` ("ipinfo" \| "ipapi"), `apiToken`, `baseUrl`, optional `endpoint` (ipinfo: "lite" \| "lookup") |
+| `lastSeenAt`              | No       | Enable last-seen tracking: `{ enabled: true, columnName?: string }`                                                                           |
+| `metadata`                | No       | Custom branding (title, theme)                                                                                                                |
 
 ## 📝 Development
 

package/dist/adapters/express.js

@@ -28,6 +28,7 @@ function convertExpressToUniversal(req) {
         url: req.originalUrl,
         method: req.method,
         headers: req.headers,
+        ip: req.ip,
         body: req.body,
     };
 }

package/dist/core/handler.js

@@ -5,6 +5,7 @@ import { createClickHouseProvider, createHttpProvider, createNodeSqliteProvider,
 import { initializeEventIngestion, isEventIngestionInitialized } from "../utils/event-ingestion.js";
 import { injectEventHooks, injectLastSeenAtHooks } from "../utils/hook-injector.js";
 import { serveIndexHtml as getIndexHtml } from "../utils/html-injector.js";
+import { evaluateRequestAccess } from "../utils/access-rules.js";
 import { decryptSession, isSessionValid, STUDIO_COOKIE_NAME } from "../utils/session.js";
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -132,6 +133,23 @@ export async function handleStudioRequest(request, config) {
         if (path === "" || path === "/") {
             path = "/";
         }
+        if (isSelfHosted) {
+            const accessDecision = evaluateRequestAccess({
+                accessConfig: config.access,
+                path,
+                method: request.method,
+                headers: request.headers,
+                ip: request.ip,
+            });
+            if (!accessDecision.allowed) {
+                return jsonResponse(403, {
+                    success: false,
+                    message: accessDecision.message,
+                    reason: accessDecision.reason,
+                    ...(accessDecision.ipAddress ? { ipAddress: accessDecision.ipAddress } : {}),
+                });
+            }
+        }
         if (path.startsWith("/assets/") ||
             path === "/vite.svg" ||
             path === "/favicon.svg" ||
@@ -262,6 +280,7 @@ async function handleApiRoute(request, path, config) {
             path: path,
             method: request.method,
             headers: request.headers,
+            ip: request.ip,
             body: request.body,
             auth: config.auth,
             basePath: config.basePath || "/api/studio",