@betterportal/tunnels 1.0.0

package/lib/schemas/service-betterportal.json

@@ -0,0 +1,109 @@
+{
+  "pluginName": "service-betterportal",
+  "events": {},
+  "version": "1.0.0",
+  "configSchema": {
+    "anyvaliVersion": "1.0",
+    "schemaVersion": "1.1",
+    "root": {
+      "kind": "object",
+      "properties": {
+        "host": {
+          "kind": "string",
+          "minLength": 1,
+          "default": "0.0.0.0"
+        },
+        "port": {
+          "kind": "int",
+          "min": 1,
+          "default": 8083
+        },
+        "betterportal": {
+          "kind": "optional",
+          "inner": {
+            "kind": "object",
+            "properties": {
+              "bpConfigPath": {
+                "kind": "optional",
+                "inner": {
+                  "kind": "string",
+                  "minLength": 1
+                }
+              },
+              "configApiToken": {
+                "kind": "optional",
+                "inner": {
+                  "kind": "string",
+                  "minLength": 1
+                }
+              },
+              "configEncryptionKey": {
+                "kind": "optional",
+                "inner": {
+                  "kind": "string",
+                  "minLength": 16
+                }
+              },
+              "controlPlaneUrl": {
+                "kind": "optional",
+                "inner": {
+                  "kind": "string",
+                  "minLength": 1
+                }
+              },
+              "serviceApiKey": {
+                "kind": "optional",
+                "inner": {
+                  "kind": "string",
+                  "minLength": 1
+                }
+              },
+              "bootstrapStatePath": {
+                "kind": "string",
+                "minLength": 1,
+                "default": "./.bp-bootstrap/state.enc"
+              },
+              "scopedConfigCachePath": {
+                "kind": "string",
+                "minLength": 1,
+                "default": "./.bp-sync-cache/scoped.json"
+              },
+              "trustedProxyHeaders": {
+                "kind": "bool",
+                "default": false
+              },
+              "cfProxy": {
+                "kind": "bool",
+                "default": false
+              },
+              "trustedProxyIps": {
+                "kind": "array",
+                "items": {
+                  "kind": "string",
+                  "minLength": 1
+                },
+                "default": []
+              }
+            },
+            "required": [
+              "bootstrapStatePath",
+              "scopedConfigCachePath",
+              "trustedProxyHeaders",
+              "cfProxy",
+              "trustedProxyIps"
+            ],
+            "unknownKeys": "strip"
+          }
+        }
+      },
+      "required": [
+        "host",
+        "port"
+      ],
+      "unknownKeys": "strip"
+    },
+    "definitions": {},
+    "extensions": {}
+  },
+  "pluginType": "service"
+}

package/lib/schemas/service-tunnel-client-api.json

@@ -0,0 +1,300 @@
+{
+  "pluginName": "service-tunnel-client-api",
+  "events": {
+    "ws.toOrigin": {
+      "type": "fire-and-forget",
+      "category": "onEvents",
+      "description": "Relay a public websocket frame to the connected tunnel client",
+      "inputSchema": {
+        "anyvaliVersion": "1.0",
+        "schemaVersion": "1.1",
+        "root": {
+          "kind": "object",
+          "properties": {
+            "publicServerId": {
+              "kind": "string"
+            },
+            "publicSocketId": {
+              "kind": "string"
+            },
+            "hostname": {
+              "kind": "string"
+            },
+            "path": {
+              "kind": "string"
+            },
+            "frameType": {
+              "kind": "string"
+            },
+            "event": {
+              "kind": "optional",
+              "inner": {
+                "kind": "string"
+              }
+            },
+            "body": {
+              "kind": "optional",
+              "inner": {
+                "kind": "string"
+              }
+            }
+          },
+          "required": [
+            "publicServerId",
+            "publicSocketId",
+            "hostname",
+            "path",
+            "frameType"
+          ],
+          "unknownKeys": "strip"
+        },
+        "definitions": {},
+        "extensions": {
+          "bsb": {
+            "description": "Public websocket frame to origin"
+          }
+        }
+      },
+      "outputSchema": null
+    },
+    "proxy.metrics": {
+      "type": "fire-and-forget",
+      "category": "onEvents",
+      "description": "Send final proxy request timings to the connected tunnel client",
+      "inputSchema": {
+        "anyvaliVersion": "1.0",
+        "schemaVersion": "1.1",
+        "root": {
+          "kind": "object",
+          "properties": {
+            "hostname": {
+              "kind": "string"
+            },
+            "requestId": {
+              "kind": "string"
+            },
+            "totalMs": {
+              "kind": "number"
+            },
+            "clientApiRoundtripMs": {
+              "kind": "optional",
+              "inner": {
+                "kind": "number"
+              }
+            },
+            "cliOverheadMs": {
+              "kind": "optional",
+              "inner": {
+                "kind": "number"
+              }
+            },
+            "originMs": {
+              "kind": "optional",
+              "inner": {
+                "kind": "number"
+              }
+            },
+            "internalServerMs": {
+              "kind": "optional",
+              "inner": {
+                "kind": "number"
+              }
+            }
+          },
+          "required": [
+            "hostname",
+            "requestId",
+            "totalMs"
+          ],
+          "unknownKeys": "strip"
+        },
+        "definitions": {},
+        "extensions": {
+          "bsb": {
+            "description": "Proxy request metrics"
+          }
+        }
+      },
+      "outputSchema": null
+    },
+    "proxy.request": {
+      "type": "returnable",
+      "category": "onReturnableEvents",
+      "description": "Proxy an HTTP request through a connected tunnel client",
+      "defaultTimeout": 60,
+      "inputSchema": {
+        "anyvaliVersion": "1.0",
+        "schemaVersion": "1.1",
+        "root": {
+          "kind": "object",
+          "properties": {
+            "hostname": {
+              "kind": "string"
+            },
+            "method": {
+              "kind": "string"
+            },
+            "path": {
+              "kind": "string"
+            },
+            "headers": {
+              "kind": "record",
+              "valueSchema": {
+                "kind": "string"
+              }
+            },
+            "body": {
+              "kind": "optional",
+              "inner": {
+                "kind": "string"
+              }
+            },
+            "webStartedAt": {
+              "kind": "number"
+            }
+          },
+          "required": [
+            "hostname",
+            "method",
+            "path",
+            "headers",
+            "webStartedAt"
+          ],
+          "unknownKeys": "strip"
+        },
+        "definitions": {},
+        "extensions": {
+          "bsb": {
+            "description": "Proxy request"
+          }
+        }
+      },
+      "outputSchema": {
+        "anyvaliVersion": "1.0",
+        "schemaVersion": "1.1",
+        "root": {
+          "kind": "object",
+          "properties": {
+            "requestId": {
+              "kind": "string"
+            },
+            "ownerServerId": {
+              "kind": "string"
+            },
+            "status": {
+              "kind": "number"
+            },
+            "headers": {
+              "kind": "record",
+              "valueSchema": {
+                "kind": "string"
+              }
+            },
+            "body": {
+              "kind": "string"
+            },
+            "webStartedAt": {
+              "kind": "number"
+            },
+            "clientApiRoundtripMs": {
+              "kind": "number"
+            },
+            "cliOverheadMs": {
+              "kind": "optional",
+              "inner": {
+                "kind": "number"
+              }
+            },
+            "originMs": {
+              "kind": "optional",
+              "inner": {
+                "kind": "number"
+              }
+            }
+          },
+          "required": [
+            "requestId",
+            "ownerServerId",
+            "status",
+            "headers",
+            "body",
+            "webStartedAt",
+            "clientApiRoundtripMs"
+          ],
+          "unknownKeys": "strip"
+        },
+        "definitions": {},
+        "extensions": {
+          "bsb": {
+            "description": "Proxy response"
+          }
+        }
+      }
+    }
+  },
+  "version": "1.0.0",
+  "configSchema": {
+    "anyvaliVersion": "1.0",
+    "schemaVersion": "1.1",
+    "root": {
+      "kind": "object",
+      "properties": {
+        "port": {
+          "kind": "number",
+          "default": 8081,
+          "metadata": {
+            "description": "Client API listener port"
+          }
+        },
+        "domain": {
+          "kind": "string",
+          "default": "tunnels.betterportal.dev",
+          "metadata": {
+            "description": "Default public tunnel domain"
+          }
+        },
+        "publicUrl": {
+          "kind": "string",
+          "default": "https://tunnels.betterportal.dev",
+          "metadata": {
+            "description": "Public base URL"
+          }
+        },
+        "authAppBaseUrl": {
+          "kind": "string",
+          "default": "https://betterportal.cloud",
+          "metadata": {
+            "description": "BetterPortal app URL used for CLI auth"
+          }
+        },
+        "authVerifyPath": {
+          "kind": "string",
+          "default": "/cli-auth/verify",
+          "metadata": {
+            "description": "BetterPortal CLI auth verify route"
+          }
+        }
+      },
+      "required": [
+        "port",
+        "domain",
+        "publicUrl",
+        "authAppBaseUrl",
+        "authVerifyPath"
+      ],
+      "unknownKeys": "strip",
+      "metadata": {
+        "description": "service-tunnel-client-api config"
+      }
+    },
+    "definitions": {},
+    "extensions": {}
+  },
+  "pluginType": "service",
+  "dependencies": [
+    {
+      "id": "_/service-tunnel-web.js",
+      "version": "1.0.0"
+    }
+  ]
+}

package/lib/schemas/service-tunnel-web.json

@@ -0,0 +1,140 @@
+{
+  "pluginName": "service-tunnel-web",
+  "events": {
+    "ws.fromOrigin": {
+      "type": "fire-and-forget",
+      "category": "onEvents",
+      "description": "Relay an origin websocket frame to the public websocket",
+      "inputSchema": {
+        "anyvaliVersion": "1.0",
+        "schemaVersion": "1.1",
+        "root": {
+          "kind": "object",
+          "properties": {
+            "publicSocketId": {
+              "kind": "string"
+            },
+            "frameType": {
+              "kind": "string"
+            },
+            "event": {
+              "kind": "optional",
+              "inner": {
+                "kind": "string"
+              }
+            },
+            "body": {
+              "kind": "optional",
+              "inner": {
+                "kind": "string"
+              }
+            }
+          },
+          "required": [
+            "publicSocketId",
+            "frameType"
+          ],
+          "unknownKeys": "strip"
+        },
+        "definitions": {},
+        "extensions": {
+          "bsb": {
+            "description": "Origin websocket frame to public client"
+          }
+        }
+      },
+      "outputSchema": null
+    }
+  },
+  "version": "1.0.0",
+  "configSchema": {
+    "anyvaliVersion": "1.0",
+    "schemaVersion": "1.1",
+    "root": {
+      "kind": "object",
+      "properties": {
+        "port": {
+          "kind": "number",
+          "default": 8080,
+          "metadata": {
+            "description": "Public web listener port"
+          }
+        },
+        "domain": {
+          "kind": "string",
+          "default": "tunnels.betterportal.dev",
+          "metadata": {
+            "description": "Tunnel root domain"
+          }
+        },
+        "verificationHost": {
+          "kind": "string",
+          "default": "verify.tunnels.betterportal.dev",
+          "metadata": {
+            "description": "Verification host"
+          }
+        },
+        "cookieSecret": {
+          "kind": "string",
+          "default": "dev-cookie-secret",
+          "metadata": {
+            "description": "Signed verification cookie secret"
+          }
+        },
+        "turnstileSiteKey": {
+          "kind": "optional",
+          "inner": {
+            "kind": "string"
+          },
+          "metadata": {
+            "description": "Cloudflare Turnstile site key"
+          }
+        },
+        "turnstileSecretKey": {
+          "kind": "optional",
+          "inner": {
+            "kind": "string"
+          },
+          "metadata": {
+            "description": "Cloudflare Turnstile secret key"
+          }
+        },
+        "maxHeaderBytes": {
+          "kind": "number",
+          "default": 32768,
+          "metadata": {
+            "description": "Maximum accepted request header bytes"
+          }
+        },
+        "maxBodyBytes": {
+          "kind": "number",
+          "default": 2097152,
+          "metadata": {
+            "description": "Maximum accepted request body bytes"
+          }
+        }
+      },
+      "required": [
+        "port",
+        "domain",
+        "verificationHost",
+        "cookieSecret",
+        "maxHeaderBytes",
+        "maxBodyBytes"
+      ],
+      "unknownKeys": "strip",
+      "metadata": {
+        "description": "service-tunnel-web config"
+      }
+    },
+    "definitions": {},
+    "extensions": {}
+  },
+  "pluginType": "service",
+  "dependencies": [
+    {
+      "id": "_/service-tunnel-client-api.js",
+      "version": "1.0.0"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@betterportal/tunnels",
+  "version": "1.0.0",
+  "type": "module",
+  "license": "(AGPL-3.0-only OR Commercial)",
+  "files": [
+    "lib/",
+    "prisma/",
+    "README.md",
+    "SPEC.md",
+    "package.json"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bsb-plugin-cli build",
+    "typecheck": "tsc -p tsconfig.json",
+    "dev": "bsb-plugin-cli dev",
+    "start": "bsb-plugin-cli start",
+    "cli": "tsx src/cli.ts",
+    "bp-codegen": "bp-codegen",
+    "prisma:generate": "prisma generate",
+    "prisma:migrate": "prisma migrate dev",
+    "test": "node --import tsx --test tests/*.test.ts",
+    "check": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@betterportal/framework": "^10.0.0",
+    "@betterportal/plugin-bsb": "^10.0.0",
+    "@bsb/base": "^9.6.41",
+    "@bsb/config-vault": "^9.6.47",
+    "@prisma/adapter-pg": "^7.8.0",
+    "@prisma/client": "^7.8.0",
+    "anyvali": "^1.0.6",
+    "dotenv": "^17.2.3",
+    "h3": "^2.0.1-rc.22",
+    "jsx-htmx": "^4.0.0-beta2",
+    "pg": "^8.22.0",
+    "ws": "^8.18.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@types/ws": "^8.18.1",
+    "prisma": "^7.8.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  },
+  "bsb": {
+    "hooks": {
+      "afterSchemas": "bp-codegen",
+      "beforeCompile": "prisma:generate"
+    }
+  },
+  "betterportal": {
+    "routes": [
+      "src/plugins/service-betterportal/bp-routes/"
+    ]
+  }
+}

package/prisma/migrations/0001_init/migration.sql

@@ -0,0 +1,63 @@
+CREATE TYPE "TunnelStatus" AS ENUM ('created', 'active', 'draining', 'disconnected', 'expired', 'closed');
+
+CREATE TABLE "Account" (
+  "id" TEXT PRIMARY KEY,
+  "email" TEXT UNIQUE,
+  "createdAt" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE TABLE "ClientSession" (
+  "id" TEXT PRIMARY KEY,
+  "accountId" TEXT,
+  "ipHash" TEXT,
+  "userAgent" TEXT,
+  "createdAt" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "expiresAt" TIMESTAMPTZ
+);
+
+CREATE TABLE "Tunnel" (
+  "id" TEXT PRIMARY KEY,
+  "accountId" TEXT,
+  "sessionId" TEXT NOT NULL,
+  "subdomain" TEXT NOT NULL UNIQUE,
+  "targetHost" TEXT NOT NULL,
+  "targetPort" INTEGER NOT NULL,
+  "authenticated" BOOLEAN NOT NULL DEFAULT false,
+  "status" "TunnelStatus" NOT NULL DEFAULT 'created',
+  "createdAt" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "expiresAt" TIMESTAMPTZ NOT NULL,
+  CONSTRAINT "Tunnel_accountId_fkey" FOREIGN KEY ("accountId") REFERENCES "Account"("id") ON DELETE SET NULL ON UPDATE CASCADE,
+  CONSTRAINT "Tunnel_sessionId_fkey" FOREIGN KEY ("sessionId") REFERENCES "ClientSession"("id") ON DELETE RESTRICT ON UPDATE CASCADE
+);
+
+CREATE TABLE "VisitorValidation" (
+  "id" TEXT PRIMARY KEY,
+  "tunnelId" TEXT NOT NULL,
+  "visitorIpHash" TEXT NOT NULL,
+  "userAgentHash" TEXT NOT NULL,
+  "validationCookieHash" TEXT NOT NULL,
+  "validatedAt" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP,
+  "expiresAt" TIMESTAMPTZ NOT NULL,
+  CONSTRAINT "VisitorValidation_tunnelId_fkey" FOREIGN KEY ("tunnelId") REFERENCES "Tunnel"("id") ON DELETE RESTRICT ON UPDATE CASCADE
+);
+
+CREATE TABLE "UsageCounter" (
+  "tunnelId" TEXT PRIMARY KEY,
+  "requests" INTEGER NOT NULL DEFAULT 0,
+  "bytesIn" BIGINT NOT NULL DEFAULT 0,
+  "bytesOut" BIGINT NOT NULL DEFAULT 0,
+  "updatedAt" TIMESTAMPTZ NOT NULL,
+  CONSTRAINT "UsageCounter_tunnelId_fkey" FOREIGN KEY ("tunnelId") REFERENCES "Tunnel"("id") ON DELETE RESTRICT ON UPDATE CASCADE
+);
+
+CREATE TABLE "AuditEvent" (
+  "id" TEXT PRIMARY KEY,
+  "event" TEXT NOT NULL,
+  "subjectId" TEXT,
+  "data" JSONB,
+  "createdAt" TIMESTAMPTZ NOT NULL DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX "Tunnel_sessionId_idx" ON "Tunnel"("sessionId");
+CREATE INDEX "Tunnel_expiresAt_idx" ON "Tunnel"("expiresAt");
+CREATE INDEX "VisitorValidation_tunnelId_visitorIpHash_userAgentHash_idx" ON "VisitorValidation"("tunnelId", "visitorIpHash", "userAgentHash");

package/prisma/migrations/0002_account_plan/migration.sql

@@ -0,0 +1,6 @@
+CREATE TYPE "AccountPlan" AS ENUM ('anonymous', 'free', 'paid', 'admin');
+
+ALTER TABLE "Account"
+  ADD COLUMN "plan" "AccountPlan" NOT NULL DEFAULT 'anonymous',
+  ADD COLUMN "verificationBypass" BOOLEAN NOT NULL DEFAULT false,
+  ADD COLUMN "ipVerification" BOOLEAN NOT NULL DEFAULT false;

package/prisma/migrations/0003_tunnel_owner_server/migration.sql

@@ -0,0 +1 @@
+ALTER TABLE "Tunnel" ADD COLUMN "ownerServerId" TEXT;