@powerhousedao/portle 0.0.0-stage → 6.2.3-dev.100

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,88 @@
1
- # Temporary Holding Version
1
+ # @powerhousedao/portle
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Publish a Powerhouse project through [Portle](https://portle.host), the
4
+ TLS-passthrough relay for sites that run on a machine behind NAT. EXPERIMENTAL.
5
+
6
+ The package is a switchboard host plugin. List it in the project's switchboard
7
+ host file and it is active; it takes no config:
8
+
9
+ ```js
10
+ // hosts/switchboard/host.js
11
+ runner: {
12
+ plugins: [
13
+ "@powerhousedao/switchboard/plugins/mcp",
14
+ "@powerhousedao/portle/switchboard",
15
+ ],
16
+ },
17
+ ```
18
+
19
+ ## What runs where
20
+
21
+ Portle hosts the relay (frps), the authoritative DNS for every site zone and
22
+ the control plane. This plugin runs the site side on the machine next to the
23
+ switchboard: **frpc** keeps one outbound tunnel to the relay, **Caddy** holds
24
+ the private key and the wildcard certificate (obtained by DNS-01 through the
25
+ relay's DNS) and terminates TLS locally, forwarding `app.<zone>` to Connect and
26
+ `api.<zone>` to the Switchboard. The relay never decrypts anything.
27
+
28
+ ## The publication gate
29
+
30
+ The plugin brings the tunnel up only for a host that is locked down, and only
31
+ for one of its admins. `portleReadiness` reports the gate check by check:
32
+
33
+ | Check | Passes when |
34
+ |---|---|
35
+ | `identity` | the host verifies bearer tokens (`RESOLVE_CALLER_IDENTITY`) |
36
+ | `floor` | anonymous callers are refused (`REQUIRE_AUTHENTICATED_CALLER`) |
37
+ | `policy` | the policy is `ADMIN_ONLY`, or `DOCUMENT_PERMISSIONS` with default protection |
38
+ | `protection` | under `DOCUMENT_PERMISSIONS`, `DEFAULT_PROTECTION` is on |
39
+ | `admins` | `ADMINS` lists at least one address |
40
+ | `caller` | the caller is one of those addresses |
41
+
42
+ Every failing check carries the setting to change. The report also carries
43
+ warnings no setting can clear, such as the project's own subgraphs having to
44
+ guard their resolvers themselves. The gate is judged on the host's resolved
45
+ settings, not on environment variable names, so a setting that is inert under
46
+ the active policy never counts.
47
+
48
+ It is an interlock, not security: what makes it meaningful is that the same
49
+ plugin owns the tunnel, so "published" implies "locked down" for as long as the
50
+ plugin is the thing publishing. At boot the tunnel comes back only when the
51
+ operator left it running **and** the host still passes the gate.
52
+
53
+ ## The `portle` subgraph
54
+
55
+ Under an `OPEN` policy `portleReadiness` answers everyone (there is no admin to
56
+ tell apart) and everything else is refused. Under any other policy every field
57
+ is for listed admins only.
58
+
59
+ ```graphql
60
+ query { portleReadiness { publishable checks { id ok detail fix } me { address isAdmin } } }
61
+ query { portleStatus { enrolled siteZone delegation { zone nameservers } settings { upstreams { label target } autostart } binaries { frpc caddy } tunnel { state frpc { running pid restarts } caddy { running } } urls } }
62
+
63
+ mutation { portleEnrol(controlPlaneUrl: "https://cp.portle.host", token: "…") { siteZone delegation { nameservers } } }
64
+ mutation { portleConfigure(appUpstream: "127.0.0.1:2540", upstreams: [{ label: "api", target: "127.0.0.1:7540" }]) { urls } }
65
+ mutation { portleStart { tunnel { state } } } # refused unless every readiness check passes for the caller
66
+ mutation { portleStop { tunnel { state } } }
67
+ ```
68
+
69
+ ## On disk
70
+
71
+ Everything lives under the project's `.ph/portle/`: `enrollment.json` (the
72
+ site's identity and secrets, mode 600), `site.json` (the operator's choices and
73
+ `autostart`), the rendered `frpc.toml`, `Caddyfile` and `certs/`, Caddy's data
74
+ directory `caddy/` (the certificate, which must persist) and `logs/`.
75
+
76
+ The two executables are looked up in this order: `PORTLE_FRPC_BIN` /
77
+ `PORTLE_CADDY_BIN`, then `~/.ph/portle/bin/`, then the PATH. The Caddy must
78
+ be Portle's build with the `rfc2136` and `acmedns` DNS modules; a stock Caddy
79
+ starts but cannot obtain the certificate. Fetching them from the control
80
+ plane's release endpoint is the next step.
81
+
82
+ ## For a customer zone
83
+
84
+ The zone (`dev.example.com`) must be delegated to the relay's nameservers
85
+ before Caddy's first start, or the CA caches a negative answer for an hour.
86
+ `portleStatus.delegation` names the records to create. The relay's site agent
87
+ waits for the delegation on its own; this plugin reports it and the studio
88
+ UI will poll it.
@@ -0,0 +1,149 @@
1
+ import { C as writeSiteSettings, D as portleBinDir, E as BinaryLocations, O as resolveBinaries, S as writeEnrollment, T as BINARY_ENV, _ as hostStateDir, a as SettingsPatch, b as readSiteSettings, c as Supervised, d as SupervisedStatus, f as DEFAULT_SITE_SETTINGS, g as SiteSettings, h as SITE_FILE, i as PortleRunnerLike, l as SupervisedLike, m as PORTLE_DIR, n as PortleRunner, o as TunnelState, p as ENROLLMENT_FILE, r as PortleRunnerDeps, s as TunnelStatus, t as EnrolInput, u as SupervisedOptions, v as projectRootOf, w as EnrollmentResponse, x as stateDirOf, y as readEnrollment } from "./runner-8L0rxdsD.mjs";
2
+ import { API, Context, ISubgraph } from "@powerhousedao/reactor-api";
3
+ //#region src/gate.d.ts
4
+ /**
5
+ * The publication gate: the host's authorization facts, judged.
6
+ *
7
+ * Publishing a project through Portle puts its switchboard on the internet,
8
+ * so the plugin refuses to bring the tunnel up unless the host is locked
9
+ * down and the person asking is one of its admins. The gate is expressed in
10
+ * terms of the RESOLVED authorization settings, never the environment
11
+ * variables that produced them: `DEFAULT_PROTECTION` is inert under
12
+ * `ADMIN_ONLY`, and the env can be contradicted by the config file.
13
+ *
14
+ * It is an interlock, not security. The server does not become safer because
15
+ * the studio refuses; what makes the gate mean something is that the same
16
+ * plugin owns the tunnel, so "published" implies "locked down" for as long as
17
+ * the plugin is the thing publishing.
18
+ */
19
+ /** The host's authorization policy, as reactor-api resolves it at boot. */
20
+ type PortlePolicy = "OPEN" | "ADMIN_ONLY" | "DOCUMENT_PERMISSIONS";
21
+ /** What the gate judges: read off the switchboard's `API` object. */
22
+ interface GateFacts {
23
+ policy: PortlePolicy;
24
+ /** Lower-cased addresses of the host's supreme admins. */
25
+ admins: readonly string[];
26
+ /** Documents without a permission row count as protected. */
27
+ defaultProtection: boolean;
28
+ /** The bearer is verified and `ctx.user` is populated. */
29
+ identityResolved: boolean;
30
+ /** Anonymous callers are refused with a 401 before any resolver. */
31
+ requireAuthenticatedCaller: boolean;
32
+ }
33
+ interface GateCheck {
34
+ id: GateCheckId;
35
+ ok: boolean;
36
+ /** What was found. */
37
+ detail: string;
38
+ /** What to change when `ok` is false. */
39
+ fix?: string;
40
+ }
41
+ type GateCheckId = "identity" | "floor" | "policy" | "protection" | "admins" | "caller" | "custom-subgraphs";
42
+ interface GateReport {
43
+ /** Every check passed: the tunnel may come up for this caller. */
44
+ publishable: boolean;
45
+ checks: GateCheck[];
46
+ /** True of every deployment; not blocking, never silent. */
47
+ warnings: GateCheck[];
48
+ }
49
+ /** One of the host's listed admins, whatever the policy. */
50
+ export declare function isListedAdmin(admins: readonly string[], address: string | undefined): boolean;
51
+ export declare function evaluateGate(facts: GateFacts, caller: {
52
+ address?: string;
53
+ } | undefined): GateReport;
54
+ /**
55
+ * The gate without the caller: what the host itself must satisfy before the
56
+ * tunnel may come up unattended at boot. The caller check is per request.
57
+ */
58
+ export declare function bootGatePasses(facts: GateFacts): boolean;
59
+ //#endregion
60
+ //#region src/subgraph.d.ts
61
+ /** The slice of the switchboard's API object the subgraph reads. */
62
+ type PortleApi = Pick<API, "authorizationService" | "requireAuthenticatedCaller" | "relationalDb"> & {
63
+ /** Present exactly when the host resolves caller identity. */
64
+ authService: unknown;
65
+ };
66
+ export declare const PORTLE_SUBGRAPH_NAME = "portle";
67
+ export declare const portleTypeDefs: import("graphql").DocumentNode;
68
+ /** The host's authorization facts, read off the API object. */
69
+ export declare function gateFactsOf(api: PortleApi): GateFacts;
70
+ type PortleReadiness = GateReport & {
71
+ me: {
72
+ address: string | null;
73
+ isAdmin: boolean;
74
+ };
75
+ };
76
+ export declare function readiness(api: PortleApi, ctx: Context): PortleReadiness;
77
+ /** Every other field: a listed admin on a host that is not OPEN. */
78
+ export declare function requireAdmin(api: PortleApi, ctx: Context): GateFacts;
79
+ type WireUpstream = {
80
+ label: string;
81
+ target: string;
82
+ };
83
+ /** The GraphQL shape of a status: maps become lists, exits flatten. */
84
+ export declare function toWireStatus(status: TunnelStatus, delegated?: boolean | null): {
85
+ stateDir: string;
86
+ enrolled: boolean;
87
+ siteId: string | null;
88
+ siteZone: string | null;
89
+ zoneKind: string | null;
90
+ binaries: BinaryLocations;
91
+ urls: string[];
92
+ delegation: {
93
+ zone: string;
94
+ nameservers: string[];
95
+ delegated: boolean | null;
96
+ } | null;
97
+ settings: {
98
+ controlPlaneUrl: string;
99
+ appUpstream: string;
100
+ dns01Mode: "rfc2136" | "acmedns";
101
+ listen: {
102
+ https: number;
103
+ http: number;
104
+ };
105
+ autostart: boolean;
106
+ rewriteHostHeader: boolean;
107
+ sameOrigin: boolean;
108
+ upstreams: WireUpstream[];
109
+ } | null;
110
+ tunnel: {
111
+ state: TunnelState;
112
+ frpc: {
113
+ name: string;
114
+ command: string;
115
+ running: boolean;
116
+ pid: number | null;
117
+ startedAt: string | null;
118
+ restarts: number;
119
+ lastExitCode: number | null;
120
+ lastExitSignal: string | null;
121
+ lastExitAt: string | null;
122
+ } | null;
123
+ caddy: {
124
+ name: string;
125
+ command: string;
126
+ running: boolean;
127
+ pid: number | null;
128
+ startedAt: string | null;
129
+ restarts: number;
130
+ lastExitCode: number | null;
131
+ lastExitSignal: string | null;
132
+ lastExitAt: string | null;
133
+ } | null;
134
+ };
135
+ };
136
+ interface PortleSubgraphDeps {
137
+ api: PortleApi;
138
+ runner: PortleRunnerLike;
139
+ }
140
+ /**
141
+ * The `portle` subgraph as a plain `ISubgraph`: no reactor reads, no setup,
142
+ * so it needs none of `BaseSubgraph` and keeps the plugin free of runtime
143
+ * imports from reactor-api.
144
+ */
145
+ export declare function createPortleSubgraph({ api, runner }: PortleSubgraphDeps): ISubgraph;
146
+ //#endregion
147
+ export { BINARY_ENV, type BinaryLocations, DEFAULT_SITE_SETTINGS, ENROLLMENT_FILE, type EnrolInput, type EnrollmentResponse, type GateCheck, type GateCheckId, type GateFacts, type GateReport, PORTLE_DIR, type PortleApi, type PortlePolicy, type PortleReadiness, PortleRunner, type PortleRunnerDeps, type PortleRunnerLike, type PortleSubgraphDeps, SITE_FILE, type SettingsPatch, type SiteSettings, Supervised, type SupervisedLike, type SupervisedOptions, type SupervisedStatus, type TunnelState, type TunnelStatus, hostStateDir, portleBinDir, projectRootOf, readEnrollment, readSiteSettings, resolveBinaries, stateDirOf, writeEnrollment, writeSiteSettings };
148
+ export {};
149
+ //# sourceMappingURL=index.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.mts","names":[],"sources":["../src/gate.ts","../src/subgraph.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KAiBY;;UAGK;EACf,QAAQ;;EAER;;EAEA;;EAEA;;EAEA;;UAGe;EACf,IAAI;EACJ;;EAEA;;EAEA;;KAGU;UASK;;EAEf;EACA,QAAQ;;EAER,UAAU;;;wBAII,cACd,2BACA;wBAUc,aACd,OAAO,WACP;EAAU;gBACT;;;;;wBA6Fa,eAAe,OAAO;;;;KC3J1B,YAAY,KACtB;;EAIA;;qBAGW;qBAEA,kCAAc;;wBA+IX,YAAY,KAAK,YAAY;KAWjC,kBAAkB;EAC5B;IAAM;IAAwB;;;wBAOhB,UAAU,KAAK,WAAW,KAAK,UAAU;;wBAczC,aAAa,KAAK,WAAW,KAAK,UAAU;KAavD;EAAiB;EAAe;;;wBAGrB,aACd,QAAQ,cACR;;;;;;YADQ;;;;;;;;;;;;;;;;;;;;;IA2BJ;IACA;;;;;;;;;;;IACA;;;;;;;;;;;;;UAKW;EACf,KAAK;EACL,QAAQ;;;;;;;wBAQM,uBACd,KACA,UACC,qBAAqB"}
package/dist/index.mjs ADDED
@@ -0,0 +1,2 @@
1
+ import { C as isListedAdmin, E as resolveBinaries, S as evaluateGate, T as portleBinDir, _ as readSiteSettings, a as readiness, b as writeSiteSettings, c as PortleRunner, d as ENROLLMENT_FILE, f as PORTLE_DIR, g as readEnrollment, h as projectRootOf, i as portleTypeDefs, l as Supervised, m as hostStateDir, n as createPortleSubgraph, o as requireAdmin, p as SITE_FILE, r as gateFactsOf, s as toWireStatus, t as PORTLE_SUBGRAPH_NAME, u as DEFAULT_SITE_SETTINGS, v as stateDirOf, w as BINARY_ENV, x as bootGatePasses, y as writeEnrollment } from "./subgraph-UKA_XDW0.mjs";
2
+ export { BINARY_ENV, DEFAULT_SITE_SETTINGS, ENROLLMENT_FILE, PORTLE_DIR, PORTLE_SUBGRAPH_NAME, PortleRunner, SITE_FILE, Supervised, bootGatePasses, createPortleSubgraph, evaluateGate, gateFactsOf, hostStateDir, isListedAdmin, portleBinDir, portleTypeDefs, projectRootOf, readEnrollment, readSiteSettings, readiness, requireAdmin, resolveBinaries, stateDirOf, toWireStatus, writeEnrollment, writeSiteSettings };
@@ -0,0 +1,317 @@
1
+ import { spawn } from "node:child_process";
2
+ //#region src/binaries.d.ts
3
+ /**
4
+ * Where the two executables come from, in order:
5
+ * 1. `PORTLE_FRPC_BIN` / `PORTLE_CADDY_BIN` (an explicit path wins, and only it is tried);
6
+ * 2. `~/.ph/portle/bin/<name>` (where the release download will put them);
7
+ * 3. the PATH.
8
+ * The Caddy must be Portle's own build (rfc2136 + acme-dns modules); a stock
9
+ * Caddy on the PATH starts but cannot obtain the certificate.
10
+ */
11
+ interface BinaryLocations {
12
+ frpc: string | null;
13
+ caddy: string | null;
14
+ /** Every path that was looked at, for the status report. */
15
+ searched: string[];
16
+ }
17
+ interface ResolveBinariesOptions {
18
+ env?: NodeJS.ProcessEnv;
19
+ home?: string;
20
+ platform?: NodeJS.Platform;
21
+ exists?: (path: string) => boolean;
22
+ }
23
+ declare const BINARY_ENV: {
24
+ readonly frpc: "PORTLE_FRPC_BIN";
25
+ readonly caddy: "PORTLE_CADDY_BIN";
26
+ };
27
+ declare function portleBinDir(home: string, platform?: NodeJS.Platform): string;
28
+ declare function resolveBinaries(options?: ResolveBinariesOptions): BinaryLocations;
29
+ //#endregion
30
+ //#region src/delegation.d.ts
31
+ type ResolveNs = (zone: string) => Promise<string[]>;
32
+ type DelegationCheckOptions = {
33
+ /** Resolver attempts before a failure is reported; default 4. */
34
+ attempts?: number;
35
+ /** First retry delay, doubled per attempt; default 1000 ms. */
36
+ delayMs?: number;
37
+ sleep?: (ms: number) => Promise<void>;
38
+ };
39
+ //#endregion
40
+ //#region src/site/hostnames.d.ts
41
+ type ZoneKind = "customer" | "shared";
42
+ //#endregion
43
+ //#region src/site/types.d.ts
44
+ /**
45
+ * What the control plane answers to `POST /v1/enroll`. Vendored from
46
+ * site-relay (`packages/shared/src/types.ts` at df26ab8); the secrets in it
47
+ * live only in the plugin's state directory, mode 600.
48
+ */
49
+ interface EnrollmentResponse {
50
+ siteId: string;
51
+ siteSecret: string;
52
+ /** The DNS name the site lives under: `*.<siteZone>` is its wildcard. */
53
+ siteZone: string;
54
+ zoneKind: ZoneKind;
55
+ /**
56
+ * For a customer zone: the delegation the customer must create at their DNS
57
+ * provider (`<zone> NS <nameserver>` for each nameserver). Null for shared.
58
+ */
59
+ delegation: {
60
+ zone: string;
61
+ nameservers: string[];
62
+ } | null;
63
+ frp: {
64
+ serverAddr: string;
65
+ serverPort: number;
66
+ token: string;
67
+ /** PEM bundle the site must trust for the frps control connection. */
68
+ caPem: string;
69
+ serverName: string;
70
+ };
71
+ dns: {
72
+ tsigKeyName: string;
73
+ tsigAlgorithm: string;
74
+ tsigSecret: string;
75
+ /** host:port of the authoritative server that accepts RFC2136 updates. */
76
+ server: string;
77
+ /** Resolvers Caddy should use to check that the challenge TXT is visible. */
78
+ resolvers: string[];
79
+ };
80
+ /** HTTPS fallback for DNS-01 (acme-dns protocol served by the control plane). */
81
+ acmeDns: {
82
+ baseUrl: string;
83
+ username: string;
84
+ password: string;
85
+ fullDomain: string;
86
+ subdomain: string;
87
+ };
88
+ acme: {
89
+ caUrl?: string;
90
+ caRootPem?: string;
91
+ email: string;
92
+ };
93
+ }
94
+ //#endregion
95
+ //#region src/state.d.ts
96
+ /**
97
+ * Everything the plugin keeps on disk lives under `<project>/.ph/portle/`:
98
+ *
99
+ * enrollment.json the site's identity and secrets (mode 600)
100
+ * site.json the operator's choices: what the tunnel exposes, autostart
101
+ * frpc.toml, Caddyfile, certs/ rendered on every start (mode 600)
102
+ * caddy/ Caddy's data dir: the certificate, which must persist
103
+ * logs/ frpc.log, caddy.log
104
+ */
105
+ declare const PORTLE_DIR: string;
106
+ declare const ENROLLMENT_FILE = "enrollment.json";
107
+ declare const SITE_FILE = "site.json";
108
+ /** The operator's choices, kept beside the enrolment. */
109
+ interface SiteSettings {
110
+ /** The control plane the site enrolled with (needed for `ask` and acme-dns). */
111
+ controlPlaneUrl: string;
112
+ /** host:port every name proxies to unless `upstreams` names its label. */
113
+ appUpstream: string;
114
+ /** Per-label upstreams, e.g. `{ api: "127.0.0.1:7540", app: "127.0.0.1:2540" }`. */
115
+ upstreams: Record<string, string>;
116
+ /** rfc2136 straight to the relay's PowerDNS, or the acme-dns HTTPS fallback. */
117
+ dns01Mode: "rfc2136" | "acmedns";
118
+ /**
119
+ * The local ports Caddy listens on. 443/80 is what the LAN path needs; a
120
+ * machine that cannot bind them (another server, macOS without root)
121
+ * can use high ports and still be reached through the relay.
122
+ */
123
+ listen: {
124
+ https: number;
125
+ http: number;
126
+ };
127
+ /**
128
+ * Send the upstream's own host:port as the Host header instead of the
129
+ * public name. Dev servers that check the Host header (Vite's
130
+ * `server.allowedHosts`) refuse the public name otherwise.
131
+ */
132
+ rewriteHostHeader?: boolean;
133
+ /**
134
+ * Publish Connect and the switchboard on ONE origin: the `app` label also
135
+ * serves the switchboard's paths (proxied to the `api` upstream) and a
136
+ * runtime config in which the switchboard's local origin is replaced by
137
+ * the public one. Needs both the `app` and `api` labels. Default on.
138
+ */
139
+ sameOrigin?: boolean;
140
+ /** Bring the tunnel up at boot when the gate passes. Set by start, cleared by stop. */
141
+ autostart: boolean;
142
+ }
143
+ /**
144
+ * The project root the switchboard serves: the directory of its config file
145
+ * when the host passed one, else the working directory.
146
+ */
147
+ declare function projectRootOf(options: {
148
+ configFile?: unknown;
149
+ } | undefined): string;
150
+ declare function stateDirOf(projectRoot: string): string;
151
+ /**
152
+ * Where this host keeps its Portle state: with the rest of its `.ph`. A desktop
153
+ * app points `PH_USER_DATA_DIR` at the identity that signed in, so each identity
154
+ * has its own site, and a run with its own data can't pick up this project's
155
+ * enrolment and bring up its tunnel.
156
+ */
157
+ declare function hostStateDir(options: {
158
+ configFile?: unknown;
159
+ } | undefined, env?: Record<string, string | undefined>): string;
160
+ declare function readEnrollment(stateDir: string): EnrollmentResponse | null;
161
+ declare function writeEnrollment(stateDir: string, enrollment: EnrollmentResponse): void;
162
+ declare const DEFAULT_SITE_SETTINGS: Omit<SiteSettings, "controlPlaneUrl">;
163
+ declare function readSiteSettings(stateDir: string): SiteSettings | null;
164
+ declare function writeSiteSettings(stateDir: string, settings: SiteSettings): void;
165
+ //#endregion
166
+ //#region src/supervisor.d.ts
167
+ /**
168
+ * One long-running child (frpc, Caddy) kept alive by the plugin: started
169
+ * hidden, logged to a file, restarted with backoff when it dies, and stopped
170
+ * as a process tree. Mirrors host-core's spawn conventions (`windowsHide`,
171
+ * SIGTERM then SIGKILL after a timeout).
172
+ */
173
+ interface SupervisedOptions {
174
+ name: string;
175
+ command: string;
176
+ args: string[];
177
+ cwd: string;
178
+ /** Appended to; stdout and stderr of every run. */
179
+ logFile: string;
180
+ env?: NodeJS.ProcessEnv;
181
+ /** Restart delay after a death: doubles from `initialMs` up to `maxMs`, resets after a healthy run. */
182
+ backoff?: {
183
+ initialMs: number;
184
+ maxMs: number;
185
+ };
186
+ /** A run longer than this resets the backoff. */
187
+ healthyAfterMs?: number;
188
+ stopTimeoutMs?: number;
189
+ platform?: NodeJS.Platform;
190
+ spawnImpl?: typeof spawn;
191
+ onEvent?: (event: SupervisedEvent) => void;
192
+ }
193
+ type SupervisedEvent = {
194
+ type: "started";
195
+ name: string;
196
+ pid: number;
197
+ } | {
198
+ type: "exited";
199
+ name: string;
200
+ code: number | null;
201
+ signal: string | null;
202
+ restarting: boolean;
203
+ delayMs: number;
204
+ } | {
205
+ type: "stopped";
206
+ name: string;
207
+ } | {
208
+ type: "spawn-failed";
209
+ name: string;
210
+ error: string;
211
+ };
212
+ interface SupervisedStatus {
213
+ name: string;
214
+ command: string;
215
+ running: boolean;
216
+ pid: number | null;
217
+ startedAt: string | null;
218
+ restarts: number;
219
+ lastExit: {
220
+ code: number | null;
221
+ signal: string | null;
222
+ at: string;
223
+ } | null;
224
+ }
225
+ interface SupervisedLike {
226
+ start(): void;
227
+ stop(): Promise<void>;
228
+ status(): SupervisedStatus;
229
+ }
230
+ declare class Supervised implements SupervisedLike {
231
+ #private;
232
+ constructor(options: SupervisedOptions);
233
+ status(): SupervisedStatus;
234
+ start(): void;
235
+ stop(): Promise<void>;
236
+ }
237
+ //#endregion
238
+ //#region src/runner.d.ts
239
+ type TunnelState = "down" | "up" | "degraded";
240
+ interface TunnelStatus {
241
+ stateDir: string;
242
+ enrolled: boolean;
243
+ siteId: string | null;
244
+ siteZone: string | null;
245
+ zoneKind: string | null;
246
+ delegation: {
247
+ zone: string;
248
+ nameservers: string[];
249
+ } | null;
250
+ settings: SiteSettings | null;
251
+ binaries: BinaryLocations;
252
+ tunnel: {
253
+ state: TunnelState;
254
+ frpc: SupervisedStatus | null;
255
+ caddy: SupervisedStatus | null;
256
+ };
257
+ /** The public names this site serves, from its labels. */
258
+ urls: string[];
259
+ }
260
+ interface EnrolInput {
261
+ controlPlaneUrl: string;
262
+ token: string;
263
+ }
264
+ type SettingsPatch = Partial<Pick<SiteSettings, "appUpstream" | "upstreams" | "dns01Mode" | "listen" | "rewriteHostHeader" | "sameOrigin">>;
265
+ /** What the subgraph and the hooks drive; the class below is the real one. */
266
+ interface PortleRunnerLike {
267
+ status(): TunnelStatus;
268
+ /** True/false for a customer zone; null when the site needs no delegation. */
269
+ checkDelegation(): Promise<boolean | null>;
270
+ enrol(input: EnrolInput): Promise<TunnelStatus>;
271
+ configure(patch: SettingsPatch): TunnelStatus;
272
+ start(): Promise<TunnelStatus>;
273
+ /** Stops both processes; clears `autostart` unless `keepAutostart` (a host shutdown). */
274
+ stop(options?: StopOptions): Promise<TunnelStatus>;
275
+ }
276
+ interface StopOptions {
277
+ /** The host is going down, not the operator's wish: the tunnel comes back at the next boot. */
278
+ keepAutostart?: boolean;
279
+ }
280
+ interface PortleRunnerDeps extends ResolveBinariesOptions {
281
+ stateDir: string;
282
+ fetchImpl?: typeof fetch;
283
+ resolveNs?: ResolveNs;
284
+ /** Retry policy of the delegation check (tests shorten it). */
285
+ delegationCheck?: DelegationCheckOptions;
286
+ createSupervised?: (options: SupervisedOptions) => SupervisedLike;
287
+ log?: (msg: string, detail?: Record<string, unknown>) => void;
288
+ }
289
+ declare class PortleRunner implements PortleRunnerLike {
290
+ #private;
291
+ constructor(deps: PortleRunnerDeps);
292
+ get stateDir(): string;
293
+ status(): TunnelStatus;
294
+ /** For status: a resolver that cannot answer reads as not delegated (yet). */
295
+ checkDelegation(): Promise<boolean | null>;
296
+ enrol(input: EnrolInput): Promise<TunnelStatus>;
297
+ configure(patch: SettingsPatch): TunnelStatus;
298
+ /** Writes the CA files, frpc.toml and the Caddyfile for the current enrolment and settings. */
299
+ render(): {
300
+ frpcConfig: string;
301
+ caddyfile: string;
302
+ certsDir: string;
303
+ };
304
+ /**
305
+ * Brings the tunnel up. A customer zone must be delegated first: Caddy
306
+ * would otherwise ask the CA for a name the CA cannot resolve, and the
307
+ * negative answer is cached for an hour.
308
+ */
309
+ start(): Promise<TunnelStatus>;
310
+ stop(options?: StopOptions): Promise<TunnelStatus>;
311
+ /** Whether the operator asked for the tunnel to come up at boot. */
312
+ wantsAutostart(): boolean;
313
+ }
314
+ //#endregion
315
+ export { writeSiteSettings as C, portleBinDir as D, BinaryLocations as E, resolveBinaries as O, writeEnrollment as S, BINARY_ENV as T, hostStateDir as _, SettingsPatch as a, readSiteSettings as b, Supervised as c, SupervisedStatus as d, DEFAULT_SITE_SETTINGS as f, SiteSettings as g, SITE_FILE as h, PortleRunnerLike as i, SupervisedLike as l, PORTLE_DIR as m, PortleRunner as n, TunnelState as o, ENROLLMENT_FILE as p, PortleRunnerDeps as r, TunnelStatus as s, EnrolInput as t, SupervisedOptions as u, projectRootOf as v, EnrollmentResponse as w, stateDirOf as x, readEnrollment as y };
316
+ export {};
317
+ //# sourceMappingURL=runner-8L0rxdsD.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"runner-8L0rxdsD.d.mts","names":[],"sources":["../src/binaries.ts","../src/delegation.ts","../src/site/hostnames.ts","../src/site/types.ts","../src/state.ts","../src/supervisor.ts","../src/runner.ts"],"mappings":";;;;;;;;;;UAWiB;EACf;EACA;;EAEA;;UAGe;EACf,MAAM,OAAO;EACb;EACA,WAAW,OAAO;EAClB,UAAU;;cAGC;WACX;WACA;;iBAGc,aACd,cACA,WAAU,OAAO;iBAUH,gBACd,UAAS,yBACR;;;KCzBS,aAAa,iBAAiB;KAoC9B;;EAEV;;EAEA;EACA,SAAS,eAAe;;;;KC/Cd;;;;;;;;UCNK;EACf;EACA;;EAEA;EACA,UAAU;;;;;EAKV;IAAc;IAAc;;EAC5B;IACE;IACA;IACA;;IAEA;IACA;;EAEF;IACE;IACA;IACA;;IAEA;;IAEA;;;EAGF;IACE;IACA;IACA;IACA;IACA;;EAEF;IACE;IACA;IACA;;;;;;;;;;;;;;cC1BS;cACA;cACA;;UAGI;;EAEf;;EAEA;;EAEA,WAAW;;EAEX;;;;;;EAMA;IAAU;IAAe;;;;;;;EAMzB;;;;;;;EAOA;;EAEA;;;;;;iBAOc,cACd;EAAW;;iBAQG,WAAW;;;;;;;iBAUX,aACd;EAAW;eACX,MAAK;iBAsBS,eAAe,mBAAmB;iBAYlC,gBACd,kBACA,YAAY;cASD,uBAAuB,KAAK;iBAUzB,iBAAiB,mBAAmB;iBAapC,kBACd,kBACA,UAAU;;;;;;;;;UC9IK;EACf;EACA;EACA;EACA;;EAEA;EACA,MAAM,OAAO;;EAEb;IAAY;IAAmB;;;EAE/B;EACA;EACA,WAAW,OAAO;EAClB,mBAAmB;EACnB,WAAW,OAAO;;KAGR;EACN;EAAiB;EAAc;;EAE/B;EACA;EACA;EACA;EACA;EACA;;EAEA;EAAiB;;EACjB;EAAsB;EAAc;;UAEzB;EACf;EACA;EACA;EACA;EACA;EACA;EACA;IAAY;IAAqB;IAAuB;;;UAGzC;EACf;EACA,QAAQ;EACR,UAAU;;cAGC,sBAAsB;;EAkBjC,YAAY,SAAS;EAWrB,UAAU;EAcV;EAMM,QAAQ;;;;KCpEJ;UAEK;EACf;EACA;EACA;EACA;EACA;EACA;IAAc;IAAc;;EAC5B,UAAU;EACV,UAAU;EACV;IACE,OAAO;IACP,MAAM;IACN,OAAO;;;EAGT;;UAGe;EACf;EACA;;KAGU,gBAAgB,QAC1B,KACE;;UAWa;EACf,UAAU;;EAEV,mBAAmB;EACnB,MAAM,OAAO,aAAa,QAAQ;EAClC,UAAU,OAAO,gBAAgB;EACjC,SAAS,QAAQ;;EAEjB,KAAK,UAAU,cAAc,QAAQ;;UAGtB;;EAEf;;UAGe,yBAAyB;EACxC;EACA,mBAAmB;EACnB,YAAY;;EAEZ,kBAAkB;EAClB,oBAAoB,SAAS,sBAAsB;EACnD,OAAO,aAAa,SAAS;;cAGlB,wBAAwB;;EAKnC,YAAY,MAAM;MAId;EAIJ,UAAU;;EA8BJ,mBAAmB;EAenB,MAAM,OAAO,aAAa,QAAQ;EA8BxC,UAAU,OAAO,gBAAgB;;EA6BjC;IACE;IACA;IACA;;;;;;;EAyFI,SAAS,QAAQ;EA4FjB,KAAK,UAAS,cAAmB,QAAQ;;EAsB/C"}