@powerhousedao/portle 0.0.0-stage → 6.2.3-dev.101
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/LICENSE +661 -0
- package/README.md +87 -2
- package/dist/index.d.mts +149 -0
- package/dist/index.d.mts.map +1 -0
- package/dist/index.mjs +2 -0
- package/dist/runner-8L0rxdsD.d.mts +317 -0
- package/dist/runner-8L0rxdsD.d.mts.map +1 -0
- package/dist/subgraph-UKA_XDW0.mjs +1219 -0
- package/dist/subgraph-UKA_XDW0.mjs.map +1 -0
- package/dist/switchboard.d.mts +48 -0
- package/dist/switchboard.d.mts.map +1 -0
- package/dist/switchboard.mjs +72 -0
- package/dist/switchboard.mjs.map +1 -0
- package/package.json +58 -3
package/README.md
CHANGED
|
@@ -1,3 +1,88 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @powerhousedao/portle
|
|
2
2
|
|
|
3
|
-
|
|
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.
|
package/dist/index.d.mts
ADDED
|
@@ -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"}
|