@dbx-tools/tunnel 0.9.131 → 0.9.136
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 +117 -107
- package/index.ts +1 -1
- package/lib/index.d.ts +1 -1
- package/lib/index.js +2 -2
- package/lib/src/gate.d.ts +2 -0
- package/lib/src/gate.js +4 -2
- package/lib/src/generated/_login-client.d.ts +1 -1
- package/lib/src/generated/_login-client.js +2 -2
- package/lib/src/login-page.d.ts +2 -0
- package/lib/src/login-page.js +14 -2
- package/lib/src/plugin.d.ts +2 -0
- package/lib/src/plugin.js +28 -8
- package/package.json +8 -8
- package/src/gate.ts +5 -1
- package/src/generated/_login-client.ts +1 -1
- package/src/login-page.ts +15 -1
- package/src/plugin.ts +33 -10
package/README.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
# @dbx-tools/tunnel
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
[
|
|
3
|
+
Expose an application through a public Portr or FRP tunnel with an in-process
|
|
4
|
+
passwordless access gate from [@dbx-tools/auth-gate](../auth-gate).
|
|
5
5
|
|
|
6
|
-
## Quick
|
|
6
|
+
## Quick start
|
|
7
7
|
|
|
8
8
|
Add an authenticated public FRP endpoint to an AppKit app:
|
|
9
9
|
|
|
@@ -28,7 +28,7 @@ based on [upstream Portr](https://github.com/amalshaji/portr), plus
|
|
|
28
28
|
when an app needs to be reachable from outside its network - a stakeholder demo,
|
|
29
29
|
a webhook sender that has to reach a dev build, an OAuth redirect that cannot
|
|
30
30
|
point at `localhost` - without publishing the app to anyone who learns the URL.
|
|
31
|
-
It is shaped for Databricks Apps (it
|
|
31
|
+
It is shaped for Databricks Apps (it honors the `DATABRICKS_APP_PORT` contract
|
|
32
32
|
and lets the platform's own front door through ungated) but the gate itself is
|
|
33
33
|
platform-neutral.
|
|
34
34
|
|
|
@@ -36,15 +36,15 @@ The tunnel plugs into `@dbx-tools/appkit`'s `createApp` through its INTERCEPTOR
|
|
|
36
36
|
context: `createApp({ interceptor: tunnelInterceptor() })` applies the computed
|
|
37
37
|
`DATABRICKS_HOST`, launches the selected client(s) pointed at the app's public
|
|
38
38
|
port, and binds them so the app and tunnels live and die as one (signals pass
|
|
39
|
-
through, either death tears the pair down). The app is the process
|
|
40
|
-
rides along inside it. Access is granted per email address against an
|
|
41
|
-
authenticated by Better Auth email OTP or a passkey
|
|
39
|
+
through, either death tears the pair down). The app is the process. The tunnel
|
|
40
|
+
rides along inside it. Access is granted per email address against an allowlist,
|
|
41
|
+
authenticated by Better Auth email OTP or a passkey. The gate itself is the
|
|
42
42
|
`authGate` AppKit plugin, which registers the login routes and a gating
|
|
43
43
|
middleware on the app's Express server (no separate proxy process).
|
|
44
44
|
|
|
45
|
-
|
|
45
|
+
The package:
|
|
46
46
|
|
|
47
|
-
- Consumed in-process
|
|
47
|
+
- Consumed in-process through the `createApp` interceptor context - no wrapper CLI,
|
|
48
48
|
no separate process: `createApp({ interceptor: tunnelInterceptor() })`. A no-op
|
|
49
49
|
when the selected clients are not configured, so it is safe to register
|
|
50
50
|
unconditionally.
|
|
@@ -55,27 +55,27 @@ middleware on the app's Express server (no separate proxy process).
|
|
|
55
55
|
`Your verification code is: / <code> / This code expires in N minutes`, and the
|
|
56
56
|
code input carries `autocomplete="one-time-code"`. iOS, Gmail, Outlook, and
|
|
57
57
|
Android detect a code from that shape and offer it directly from the
|
|
58
|
-
notification
|
|
58
|
+
notification. Novel phrasing breaks the detection. Both MIME parts carry
|
|
59
59
|
the code as visible text, never an image, and no trailer follows the copy.
|
|
60
|
-
- The code
|
|
60
|
+
- The code appears in the subject, preheader, and body:
|
|
61
61
|
`123456 is your verification code`. Mobile autofill reads an incoming
|
|
62
|
-
|
|
62
|
+
notification, and a notification contains the sender, the subject, and a short
|
|
63
63
|
snippet - nothing else - so a code that lives only in the body is unreachable
|
|
64
64
|
however cleanly the body is shaped. See
|
|
65
65
|
[Why the code is in the subject](#email-code-subject).
|
|
66
66
|
- The two MIME parts are built separately, on purpose. The HTML card uses the
|
|
67
67
|
configured subject template as its neutral title and shows the code once as a
|
|
68
|
-
large styled body heading
|
|
69
|
-
is authored directly, keeping the prompt and the code on
|
|
68
|
+
large styled body heading. The `text/plain` part
|
|
69
|
+
is authored directly, keeping the prompt and the code on one line
|
|
70
70
|
(`Your verification code is: 123456`) because that is the shape client code
|
|
71
71
|
detection reads most reliably. A generated text part cannot hold it - the text
|
|
72
72
|
part is a rendering of the HTML, so the heading's CSS margin arrives as blank
|
|
73
|
-
lines and autofill stops being offered while the HTML still
|
|
73
|
+
lines and autofill stops being offered while the HTML still renders correctly. See
|
|
74
74
|
`codeEmailTextBody` in the `app` module.
|
|
75
|
-
- The sign-in code is
|
|
76
|
-
`EMAIL_SYSTEM_FROM`), never a person's address,
|
|
75
|
+
- The sign-in code is system mail: it sends from `no-reply@EMAIL_DOMAIN` (or
|
|
76
|
+
`EMAIL_SYSTEM_FROM`), never a person's address, because a reply to a
|
|
77
77
|
machine-generated code reaches nobody. `EMAIL_FROM` is not required - see
|
|
78
|
-
[
|
|
78
|
+
[@dbx-tools/email](../../node/email#sender-addresses).
|
|
79
79
|
- Better Auth owns users, hashed OTP verification records, sessions, rate
|
|
80
80
|
limits, and passkey credentials. `@dbx-tools/tunnel` supplies only its
|
|
81
81
|
authorization policy, branded email delivery, and transport boundary.
|
|
@@ -83,8 +83,12 @@ middleware on the app's Express server (no separate proxy process).
|
|
|
83
83
|
the operating system's application-data directory. Both adapters run Better
|
|
84
84
|
Auth's own migrations under a Postgres advisory lock or file lock.
|
|
85
85
|
- Email OTP remains bootstrap and recovery. Returning users can authenticate
|
|
86
|
-
with discoverable passkeys
|
|
87
|
-
|
|
86
|
+
with discoverable passkeys. The OTP form can create a passkey immediately
|
|
87
|
+
after verification, and users can enroll, name, or remove more passkeys
|
|
88
|
+
through [@dbx-tools/ui/auth](../../ui/appkit). Each passkey uses the exact
|
|
89
|
+
public tunnel hostname as its WebAuthn relying-party ID. Its display name
|
|
90
|
+
combines `TUNNEL_AUTH_PASSKEY_NAME_PREFIX` with the humanized first hostname
|
|
91
|
+
label; the prefix defaults to `projectUtils.name()`.
|
|
88
92
|
- Allow-list patterns in three shapes, matched in order: a domain shortcut
|
|
89
93
|
(`example.com`, `@example.com`), a shell-style glob (`*@example.com`), or a
|
|
90
94
|
regex literal (`/^ops-.*@example\.com$/`). An empty list allows nobody.
|
|
@@ -95,14 +99,14 @@ middleware on the app's Express server (no separate proxy process).
|
|
|
95
99
|
`x-forwarded-access-token`, which would otherwise let anyone drive the app's
|
|
96
100
|
workspace calls with a pasted token. Add an app's own headers with
|
|
97
101
|
`TUNNEL_FORWARD_HEADERS`.
|
|
98
|
-
- Only
|
|
102
|
+
- Only Portr traffic is gated. The gate identifies tunnel requests by their
|
|
99
103
|
`Host` header (`TUNNEL_PUBLIC_DOMAIN`), which portr's client preserves from the
|
|
100
104
|
public visitor. Platform front-door traffic and any other local caller carry a
|
|
101
|
-
different `Host` and pass through
|
|
105
|
+
different `Host` and pass through without a gate, so health checks and the workspace UI
|
|
102
106
|
keep working. (There is no portr-injected identifying header and no source-IP
|
|
103
107
|
signal - the client dials the app over plain loopback - so `Host` is the signal.)
|
|
104
108
|
- SPA-aware gating: static assets and the login routes stay open so the browser
|
|
105
|
-
can load the client and render the login form
|
|
109
|
+
can load the client and render the login form. Every other `/api/*` needs a
|
|
106
110
|
valid session cookie or gets `401`. A WebSocket handshake is an ordinary `GET`
|
|
107
111
|
and runs through the same gate.
|
|
108
112
|
- Supervised teardown - `tunnelInterceptor` registers its tunnel supervisor with
|
|
@@ -114,10 +118,10 @@ middleware on the app's Express server (no separate proxy process).
|
|
|
114
118
|
supervision alone is not enough: portr can stay alive after the edge drops the
|
|
115
119
|
registration, leaving the subdomain dark until a full app bounce.
|
|
116
120
|
- The gate fails fast when email is not configured for SMTP, because a gate that
|
|
117
|
-
cannot send codes locks everyone out. `@dbx-tools/email` is an
|
|
118
|
-
dependency, imported lazily
|
|
121
|
+
cannot send codes locks everyone out. `@dbx-tools/email` is an optional peer
|
|
122
|
+
dependency, imported lazily. The app that mounts the gate provides it.
|
|
119
123
|
|
|
120
|
-
##
|
|
124
|
+
## Choose tunnel and authentication behavior
|
|
121
125
|
|
|
122
126
|
A bare tunnel (`ngrok`, `portr` on its own) makes the app reachable by anyone
|
|
123
127
|
with the URL. This package keeps the tunnel but puts a gate in front of it,
|
|
@@ -126,7 +130,12 @@ reusing what the app already has: AppKit's cache for code storage, the
|
|
|
126
130
|
Because it rides inside the app's own `createApp`, there is no second process to
|
|
127
131
|
supervise and no wrapper command to thread flags through.
|
|
128
132
|
|
|
129
|
-
|
|
133
|
+
Use [@dbx-tools/auth](../auth) to obtain Databricks credentials for outbound
|
|
134
|
+
workspace calls. It doesn't authenticate visitors to a public application. Use
|
|
135
|
+
the tunnel gate for visitor access, or run with `TUNNEL_INSECURE=true` only when
|
|
136
|
+
the public endpoint intentionally requires no gate.
|
|
137
|
+
|
|
138
|
+
## Full app configuration
|
|
130
139
|
|
|
131
140
|
```ts
|
|
132
141
|
import { appkit } from "@dbx-tools/appkit";
|
|
@@ -152,56 +161,57 @@ await appkit.createApp({
|
|
|
152
161
|
});
|
|
153
162
|
```
|
|
154
163
|
|
|
155
|
-
Two pieces
|
|
156
|
-
(children bound to the app), and `authGate()` is the in-app gate. Portr
|
|
157
|
-
the default. Set `transport: "frp"` or `TUNNEL_TRANSPORT=frp
|
|
164
|
+
Two pieces run in one process: `tunnelInterceptor()` runs the selected tunnel
|
|
165
|
+
clients (children bound to the app), and `authGate()` is the in-app gate. Portr
|
|
166
|
+
remains the default. Set `transport: "frp"` or `TUNNEL_TRANSPORT=frp`. Use `both` with
|
|
158
167
|
separate `TUNNEL_PUBLIC_DOMAIN` and `TUNNEL_FRP_PUBLIC_DOMAIN` hosts.
|
|
159
|
-
See [Use
|
|
168
|
+
See [Use the gate](#use-the-gate) for the gate on its own.
|
|
160
169
|
|
|
161
170
|
## Options
|
|
162
171
|
|
|
163
|
-
The interceptor reads tunnel wiring from the environment
|
|
172
|
+
The interceptor reads tunnel wiring from the environment. The gate (the `authGate`
|
|
164
173
|
plugin) reads its own settings the same way, so a deployment configures both
|
|
165
174
|
without touching code.
|
|
166
175
|
|
|
167
|
-
| Env
|
|
168
|
-
|
|
|
169
|
-
| `TUNNEL_AUTH_ALLOW`
|
|
170
|
-
| `TUNNEL_AUTH_SUBJECT`
|
|
171
|
-
| `TUNNEL_AUTH_BRAND_NAME`
|
|
172
|
-
| `
|
|
173
|
-
| `
|
|
174
|
-
| `
|
|
175
|
-
| `
|
|
176
|
-
| `
|
|
177
|
-
| `
|
|
178
|
-
| `
|
|
179
|
-
| `
|
|
180
|
-
| `
|
|
181
|
-
| `
|
|
182
|
-
| `
|
|
183
|
-
| `
|
|
184
|
-
| `
|
|
185
|
-
| `
|
|
186
|
-
| `
|
|
187
|
-
| `
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
176
|
+
| Env | Default |
|
|
177
|
+
| --------------------------------- | ---------------------------- |
|
|
178
|
+
| `TUNNEL_AUTH_ALLOW` | empty (allow nobody) |
|
|
179
|
+
| `TUNNEL_AUTH_SUBJECT` | `Your verification code` |
|
|
180
|
+
| `TUNNEL_AUTH_BRAND_NAME` | the brand context `name` |
|
|
181
|
+
| `TUNNEL_AUTH_PASSKEY_NAME_PREFIX` | `projectUtils.name()` |
|
|
182
|
+
| `TUNNEL_AUTH_MESSAGE` | `Your verification code is:` |
|
|
183
|
+
| `TUNNEL_AUTH_SESSION_TTL` | `2592000` (30 days) |
|
|
184
|
+
| `TUNNEL_AUTH_CODE_TTL` | `600` (10 minutes) |
|
|
185
|
+
| `TUNNEL_AUTH_SESSION_CUTOFF` | unset (no cutoff) |
|
|
186
|
+
| `TUNNEL_AUTH_LOGOUT_REDIRECT` | `/` (show login again) |
|
|
187
|
+
| `TUNNEL_PUBLIC_DOMAIN` | - (no tunnel when unset) |
|
|
188
|
+
| `TUNNEL_FRP_PUBLIC_DOMAIN` | - (no FRP tunnel when unset) |
|
|
189
|
+
| `TUNNEL_TRANSPORT` | `portr` |
|
|
190
|
+
| `PORTR_SSH_URL` | Portr host on port `4444` |
|
|
191
|
+
| `FRP_SERVER` | FRP public domain |
|
|
192
|
+
| `FRP_SERVER_PORT` | `443` |
|
|
193
|
+
| `FRP_PROTOCOL` | `wss` |
|
|
194
|
+
| `FRP_TOKEN` | unset (no frps auth) |
|
|
195
|
+
| `FRP_PROXY_NAME` | public domain's first label |
|
|
196
|
+
| `FRP_PATH` | `DATABRICKS_APP_NAME` |
|
|
197
|
+
| `FRP_STRIP_PREFIX` | `true` for non-root paths |
|
|
198
|
+
| `TUNNEL_FORWARD_HEADERS` | the built-in `x-` allowlist |
|
|
199
|
+
| `TUNNEL_AUTH_JWT_SECRET` | an ephemeral per-process key |
|
|
190
200
|
|
|
191
201
|
Every tunnel-owned variable is `TUNNEL_`-prefixed because the tunnel shares one
|
|
192
202
|
environment with the app it fronts, so a generic name may already belong to the
|
|
193
203
|
app. Only the names listed above are read.
|
|
194
204
|
`PORTR_*` and `FRP_*` keep their names: those namespaces belong to the clients
|
|
195
205
|
itself, as does `DATABRICKS_APP_PORT`, which the platform sets and the tunnel
|
|
196
|
-
|
|
206
|
+
honors.
|
|
197
207
|
|
|
198
|
-
##
|
|
208
|
+
## Keep sessions across restarts
|
|
199
209
|
|
|
200
|
-
The signing key decides whether an already-issued session
|
|
210
|
+
The signing key decides whether an already-issued session cookie still verifies,
|
|
201
211
|
so where that key comes from is what decides whether a restart signs everyone out.
|
|
202
212
|
Resolution order:
|
|
203
213
|
|
|
204
|
-
1. **`TUNNEL_AUTH_JWT_SECRET`**, when set.
|
|
214
|
+
1. **`TUNNEL_AUTH_JWT_SECRET`**, when set. An
|
|
205
215
|
operator-held secret needs no shared cache, and it survives a cache flush.
|
|
206
216
|
2. **A key persisted in AppKit's cache for 30 days.** With a persistent
|
|
207
217
|
`CacheStorage` (Lakebase) the key outlives the process, so cookies stay valid
|
|
@@ -210,7 +220,7 @@ Resolution order:
|
|
|
210
220
|
same as having no secret at all.
|
|
211
221
|
|
|
212
222
|
Getting that persistence is not automatic, and the gate does the work at boot
|
|
213
|
-
|
|
223
|
+
using `lakebaseResolver.applyLakebaseEnv()`: it turns `LAKEBASE_ENDPOINT` into the
|
|
214
224
|
`PGHOST` / `PGDATABASE` / `PGUSER` the cache's pool also needs. Without them
|
|
215
225
|
AppKit cannot build the pool, silently uses an in-memory cache, and every
|
|
216
226
|
redeploy signs everyone out - so the startup log says which one you got
|
|
@@ -220,33 +230,33 @@ Resolution order:
|
|
|
220
230
|
3. **An ephemeral per-process key**, when there is no secret and no reachable
|
|
221
231
|
cache. Sessions do not survive a restart, but the gate still serves: the key
|
|
222
232
|
only validates an existing session, so losing it costs sessions, never
|
|
223
|
-
admission. A caller still needs a code delivered to an
|
|
233
|
+
admission. A caller still needs a code delivered to an address on the allowlist.
|
|
224
234
|
|
|
225
|
-
The cached key is read, generated
|
|
226
|
-
booting together both miss the cache, so both generate
|
|
227
|
-
|
|
235
|
+
The cached key is read, generated and stored, then read again. Two instances
|
|
236
|
+
booting together both miss the cache, so both generate. Adopting whatever is
|
|
237
|
+
stored afterward makes them converge on one key instead of each trusting
|
|
228
238
|
the one it minted. Set `TUNNEL_AUTH_JWT_SECRET` to remove the race entirely.
|
|
229
239
|
|
|
230
240
|
`TUNNEL_AUTH_SESSION_TTL` defaults to the same 30 days the key is stored for, on
|
|
231
241
|
purpose - a key that expired before the cookies it signed would sign everyone out
|
|
232
242
|
for no reason.
|
|
233
243
|
|
|
234
|
-
##
|
|
244
|
+
## <a id="email-code-subject"></a> Put the email code in the subject
|
|
235
245
|
|
|
236
|
-
The subject line the gate
|
|
246
|
+
The subject line the gate sends is `123456 is your verification code` -
|
|
237
247
|
`--subject` is the template the code is spliced into, not the literal line.
|
|
238
248
|
|
|
239
|
-
Mobile autofill
|
|
249
|
+
Mobile autofill reads notification text instead of email body content. iOS scans
|
|
240
250
|
incoming notification text for a code and offers to fill it - natively for
|
|
241
251
|
Messages and Mail, and since iOS 26 for any app's notification, which is what
|
|
242
252
|
finally made Gmail work. A notification carries the sender, the subject, and a
|
|
243
253
|
short snippet. That is all. A code sitting in the body is invisible to it no
|
|
244
|
-
matter how carefully the body is formatted, which is why a
|
|
254
|
+
matter how carefully the body is formatted, which is why a correctly shaped
|
|
245
255
|
`text/plain` part alone produced no prompt in Gmail.
|
|
246
256
|
|
|
247
257
|
So the code goes in both strings a notification actually shows:
|
|
248
258
|
|
|
249
|
-
- **The subject**, code
|
|
259
|
+
- **The subject**, with the code first, because a notification and an inbox row both
|
|
250
260
|
truncate: `123456 is your verification code` survives the cut wherever it lands,
|
|
251
261
|
and keeps the code in the same sentence as the words the heuristics look for.
|
|
252
262
|
A subject that does not use the conventional `Your ...` phrasing is treated as
|
|
@@ -256,11 +266,11 @@ So the code goes in both strings a notification actually shows:
|
|
|
256
266
|
(`Your verification code is: 123456`).
|
|
257
267
|
|
|
258
268
|
The opened card keeps the configured subject template as a code-free title and
|
|
259
|
-
shows the code once as a large styled body heading.
|
|
260
|
-
|
|
261
|
-
|
|
269
|
+
shows the code once as a large styled body heading. It does not use Apple's
|
|
270
|
+
domain-bound `@domain #code` trailer, which binds a code to a single origin.
|
|
271
|
+
Subject and preheader text work across clients and need no origin.
|
|
262
272
|
|
|
263
|
-
###
|
|
273
|
+
### Sign everyone out
|
|
264
274
|
|
|
265
275
|
`TUNNEL_AUTH_SESSION_CUTOFF` (or `sessionCutoff` on the `authGate` config)
|
|
266
276
|
invalidates every session issued before a given moment:
|
|
@@ -276,31 +286,31 @@ ISO instant, epoch seconds or millis from `date +%s`, and a relative duration
|
|
|
276
286
|
(`-30d`, `12 hours ago`) all work - the relative spelling being the one an
|
|
277
287
|
operator usually wants, since "sign out anything older than a month" needs no
|
|
278
288
|
timestamp arithmetic. It works two ways at once, so it holds however the key was
|
|
279
|
-
resolved: the cutoff is part of the key's
|
|
289
|
+
resolved: the cutoff is part of the key's cache key (moving it orphans the
|
|
280
290
|
previous key), and it is also checked against each token's `iat` (which is what
|
|
281
291
|
makes it bite when `TUNNEL_AUTH_JWT_SECRET` is set and there is no key to
|
|
282
292
|
rotate).
|
|
283
293
|
|
|
284
|
-
A
|
|
294
|
+
A future date is clamped to now, because an unclamped one would refuse the
|
|
285
295
|
sessions it is about to mint as well as the old ones - an app nobody can sign in
|
|
286
296
|
to, from a mistyped year. An unparseable value is ignored with a warning rather
|
|
287
297
|
than failing startup: this is the switch that gets a fleet back in.
|
|
288
298
|
|
|
289
|
-
## Inbound
|
|
299
|
+
## Inbound header policy
|
|
290
300
|
|
|
291
301
|
Tunnel traffic arrives from the public internet, so every header on it is
|
|
292
302
|
attacker-controlled - and the headers an app trusts are exactly the ones a caller
|
|
293
303
|
must not be able to write, because the app cannot tell a header the Databricks
|
|
294
304
|
front door set from one a browser typed.
|
|
295
305
|
|
|
296
|
-
Enumerating headers to remove is a losing game (a
|
|
306
|
+
Enumerating headers to remove is a losing game (a denylist is only correct until
|
|
297
307
|
the platform adds a header), so the policy is inverted: **every `x-`-prefixed
|
|
298
308
|
request header is stripped from tunnel traffic unless a pattern allows it.** A
|
|
299
309
|
header nobody thought about is removed rather than trusted. Non-`x-` headers -
|
|
300
310
|
`content-type`, `accept`, `authorization`, `cookie` - are the app's normal input
|
|
301
311
|
and pass through untouched.
|
|
302
312
|
|
|
303
|
-
The default
|
|
313
|
+
The default allowlist covers the `x-` namespaces this repo's own client sends
|
|
304
314
|
and its own server reads, so a dbx-tools app works behind the tunnel with no
|
|
305
315
|
configuration:
|
|
306
316
|
|
|
@@ -312,8 +322,8 @@ configuration:
|
|
|
312
322
|
|
|
313
323
|
Add an app's own headers with `TUNNEL_FORWARD_HEADERS` (or `forwardHeaders` on
|
|
314
324
|
`authGate`). Each entry is a literal name, a shell-style glob, or a `/regex/` -
|
|
315
|
-
the same three shapes the email
|
|
316
|
-
|
|
325
|
+
the same three shapes the email allowlist takes - and the configured list is
|
|
326
|
+
combined with the defaults, so extending it never silently breaks the built-in
|
|
317
327
|
surfaces:
|
|
318
328
|
|
|
319
329
|
```sh
|
|
@@ -323,17 +333,17 @@ TUNNEL_FORWARD_HEADERS="x-acme-*, /^x-trace-/, x-tenant" ...
|
|
|
323
333
|
Some headers no pattern can forward. These decide who a request is and where it
|
|
324
334
|
came from, and on tunnel traffic only the gate may answer that:
|
|
325
335
|
|
|
326
|
-
| Header | Why it is never forwarded
|
|
327
|
-
| ------------------------------------- |
|
|
328
|
-
| `x-forwarded-access-token` | OBO auth. A pasted workspace token would make every call in the app run as its owner
|
|
329
|
-
| `x-forwarded-user`, `-email` | Caller identity. The gate sets these itself, from a verified session.
|
|
330
|
-
| `x-forwarded-preferred-username` | Display identity from the IdP.
|
|
331
|
-
| `x-forwarded-host`, `-proto`, `-port` | Original host/scheme/port. Spoofing them poisons absolute URLs the app builds, or makes a plaintext request look like TLS.
|
|
332
|
-
| `x-forwarded-for`, `x-real-ip` | Client IP. Spoofing forges the audit trail and gives a caller a fresh rate-limit bucket per request.
|
|
333
|
-
| `x-request-id` | Request correlation UUID. Forged or colliding ids make logs unreliable.
|
|
334
|
-
|
|
335
|
-
The identity headers are AppKit's OBO contract
|
|
336
|
-
[
|
|
336
|
+
| Header | Why it is never forwarded |
|
|
337
|
+
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
338
|
+
| `x-forwarded-access-token` | On-behalf-of-user (OBO) auth. A pasted workspace token would make every call in the app run as its owner. A verified email proves nothing about who a credential belongs to. |
|
|
339
|
+
| `x-forwarded-user`, `-email` | Caller identity. The gate sets these itself, from a verified session. |
|
|
340
|
+
| `x-forwarded-preferred-username` | Display identity from the IdP. |
|
|
341
|
+
| `x-forwarded-host`, `-proto`, `-port` | Original host/scheme/port. Spoofing them poisons absolute URLs the app builds, or makes a plaintext request look like TLS. |
|
|
342
|
+
| `x-forwarded-for`, `x-real-ip` | Client IP. Spoofing forges the audit trail and gives a caller a fresh rate-limit bucket per request. |
|
|
343
|
+
| `x-request-id` | Request correlation UUID. Forged or colliding ids make logs unreliable. |
|
|
344
|
+
|
|
345
|
+
The identity headers are AppKit's OBO contract. The rest are the
|
|
346
|
+
[X-Forwarded-* set that Databricks Apps documents passing to an
|
|
337
347
|
app](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/http-headers),
|
|
338
348
|
plus the conventional `x-forwarded-proto`/`-port`/`x-real-ip` a library may read
|
|
339
349
|
anyway. Dropping the transport headers costs nothing: `xfwd` re-adds them from the
|
|
@@ -342,12 +352,12 @@ caller's claim. Rate limiting reads the client IP before stripping, and takes th
|
|
|
342
352
|
**rightmost** `x-forwarded-for` entry - the only one portr appended rather than a
|
|
343
353
|
client supplied.
|
|
344
354
|
|
|
345
|
-
## Use
|
|
355
|
+
## Use the gate
|
|
346
356
|
|
|
347
357
|
`authGate()` is the gate. Register it in your app's `createApp` plugins and it
|
|
348
358
|
mounts the `/api/email/auth/*` login routes plus a gating middleware on your app's
|
|
349
|
-
own server
|
|
350
|
-
app's shared `@dbx-tools/email` transport
|
|
359
|
+
own server through AppKit's `this.context`. By default it delivers codes through the
|
|
360
|
+
app's shared `@dbx-tools/email` transport, so the minimal wiring is an
|
|
351
361
|
`allow` list (or `TUNNEL_AUTH_ALLOW`):
|
|
352
362
|
|
|
353
363
|
```ts
|
|
@@ -365,14 +375,14 @@ await appkit.createApp({
|
|
|
365
375
|
```
|
|
366
376
|
|
|
367
377
|
Override `sendCode` only to deliver through something other than the shared
|
|
368
|
-
transport
|
|
378
|
+
transport. The default builds the OTP email (code in the subject + preheader for
|
|
369
379
|
mobile autofill) and sends it as the system sender. `@dbx-tools/email` is an
|
|
370
|
-
|
|
380
|
+
optional peer dependency - a tunnel without the gate needs no mail - so the app
|
|
371
381
|
that mounts `authGate` must include it (or run `TUNNEL_INSECURE=true` to skip the
|
|
372
|
-
gate)
|
|
382
|
+
gate). A missing transport fails fast at boot.
|
|
373
383
|
|
|
374
384
|
`GET /api/email/auth/status` is what a client asks before deciding to render a
|
|
375
|
-
login screen, and it answers per
|
|
385
|
+
login screen, and it answers per request, not per deployment: on a non-tunnel
|
|
376
386
|
`Host` it returns `{ authenticated: false, enabled: false }` without looking at
|
|
377
387
|
the cookie, because that request was never going to be gated. So the same running
|
|
378
388
|
app shows the OTP screen to a portr visitor and no login at all to a browser on
|
|
@@ -380,17 +390,17 @@ app shows the OTP screen to a portr visitor and no login at all to a browser on
|
|
|
380
390
|
|
|
381
391
|
When the hosted login page interrupts a navigation, it carries the original
|
|
382
392
|
same-origin path through the login flow and replaces the page with that path
|
|
383
|
-
after OTP verification. API denials expose the hosted login URL in `loginPath
|
|
384
|
-
|
|
393
|
+
after OTP verification. API denials expose the hosted login URL in `loginPath`.
|
|
394
|
+
Its `returnTo` query value comes from a same-origin referrer and is normalized
|
|
385
395
|
to an application path, so it cannot become an external redirect.
|
|
386
396
|
|
|
387
397
|
`POST /api/email/auth/logout` clears the current session and returns
|
|
388
398
|
`{ ok, redirectTo }`. `GET` on the same path clears the session and answers with
|
|
389
399
|
a `303` redirect. `logoutRedirectPath` or
|
|
390
|
-
`TUNNEL_AUTH_LOGOUT_REDIRECT` controls the same-origin destination
|
|
400
|
+
`TUNNEL_AUTH_LOGOUT_REDIRECT` controls the same-origin destination. `/` is the
|
|
391
401
|
default because reloading the application root presents the login gate again.
|
|
392
402
|
|
|
393
|
-
## Verify
|
|
403
|
+
## Verify the live Portr install
|
|
394
404
|
|
|
395
405
|
The normal test task skips the networked portr release download. Run the
|
|
396
406
|
integration test explicitly when validating GitHub release discovery, archive
|
|
@@ -402,7 +412,7 @@ RUN_LIVE_INSTALL_TEST=1 bun test packages/js/node/tunnel/test/portr-install.inte
|
|
|
402
412
|
|
|
403
413
|
The test installs into an isolated temporary home, runs `portr --version`, logs
|
|
404
414
|
the selected release and executable path, then removes the temporary directory.
|
|
405
|
-
The same command also discovers `frp-install.integration.test.ts
|
|
415
|
+
The same command also discovers `frp-install.integration.test.ts`. It downloads
|
|
406
416
|
the pinned `frpc` release and verifies its exact version. On macOS the installer
|
|
407
417
|
applies an ad-hoc signature before version detection because the unsigned
|
|
408
418
|
upstream binary is otherwise terminated by the platform loader.
|
|
@@ -422,13 +432,13 @@ upstream binary is otherwise terminated by the platform loader.
|
|
|
422
432
|
- `signingKey` - the cache-persisted Better Auth secret and
|
|
423
433
|
`TUNNEL_AUTH_SESSION_CUTOFF` force-clear cutoff.
|
|
424
434
|
- `allowlist` - email domain / glob / regex matching and `looksLikeEmail`.
|
|
425
|
-
- `headers` - the inbound-header
|
|
435
|
+
- `headers` - the inbound-header allowlist: `toHeaderPolicy()`,
|
|
426
436
|
`DEFAULT_FORWARD_HEADERS`, and the `PROTECTED_HEADERS` no pattern can forward.
|
|
427
|
-
- `rate-limit` - the in-memory fixed-window limiter (single-instance only
|
|
437
|
+
- `rate-limit` - the in-memory fixed-window limiter (single-instance only, not
|
|
428
438
|
distributed).
|
|
429
439
|
- `portr` - portr install, config rendering, and child launch.
|
|
430
440
|
- `_config` - exact environment-only lookup for canonical `TUNNEL_*` names.
|
|
431
441
|
|
|
432
442
|
Browser-safe gate contracts live in
|
|
433
|
-
[
|
|
434
|
-
credential manager live in [
|
|
443
|
+
[@dbx-tools/shared-auth](../../shared/auth). The passkey-first React login and
|
|
444
|
+
credential manager live in [@dbx-tools/ui/auth](../../ui/appkit).
|
package/index.ts
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
// Hand edits are overwritten on the next watch; this file is read-only.
|
|
4
4
|
|
|
5
5
|
export const PACKAGE_IDENTIFIER = "@dbx-tools/tunnel";
|
|
6
|
-
export const PACKAGE_VERSION = "0.9.
|
|
6
|
+
export const PACKAGE_VERSION = "0.9.136";
|
|
7
7
|
export * as allowlist from "./src/allowlist.ts";
|
|
8
8
|
export * as codeEmail from "./src/code-email.ts";
|
|
9
9
|
export * as frp from "./src/frp.ts";
|
package/lib/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export declare const PACKAGE_IDENTIFIER = "@dbx-tools/tunnel";
|
|
2
|
-
export declare const PACKAGE_VERSION = "0.9.
|
|
2
|
+
export declare const PACKAGE_VERSION = "0.9.136";
|
|
3
3
|
export * as allowlist from "./src/allowlist.ts";
|
|
4
4
|
export * as codeEmail from "./src/code-email.ts";
|
|
5
5
|
export * as frp from "./src/frp.ts";
|
package/lib/index.js
CHANGED
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
// Regenerated from the exporting modules in ./src.
|
|
3
3
|
// Hand edits are overwritten on the next watch; this file is read-only.
|
|
4
4
|
export const PACKAGE_IDENTIFIER = "@dbx-tools/tunnel";
|
|
5
|
-
export const PACKAGE_VERSION = "0.9.
|
|
5
|
+
export const PACKAGE_VERSION = "0.9.136";
|
|
6
6
|
export * as allowlist from "./src/allowlist.js";
|
|
7
7
|
export * as codeEmail from "./src/code-email.js";
|
|
8
8
|
export * as frp from "./src/frp.js";
|
|
@@ -26,4 +26,4 @@ export { PortrOptionsSchema } from "./src/portr.js";
|
|
|
26
26
|
export { TUNNEL_TRACE_TAG, TUNNEL_SUBDOMAIN_TRACE_TAG } from "./src/request-context.js";
|
|
27
27
|
export { KEY_TTL_SECONDS } from "./src/signing-key.js";
|
|
28
28
|
export * from "./exports.js";
|
|
29
|
-
//# sourceMappingURL=data:application/json;base64,
|
|
29
|
+
//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyxtQkFBbUIsQ0FBQztBQUN0RCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsU0FBUyxDQUFDO0FBQ3pDLE9BQU8sS0FBSyxTQUFTLE1BQU0sb0JBQW9CLENBQUM7QUFDaEQsT0FBTyxLQUFLLFNBQVMsTUFBTSxxQkFBcUIsQ0FBQztBQUNqRCxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssSUFBSSxNQUFNLGVBQWUsQ0FBQztBQUN0QyxPQUFPLEtBQUssT0FBTyxNQUFNLGtCQUFrQixDQUFDO0FBQzVDLE9BQU8sS0FBSyxXQUFXLE1BQU0sc0JBQXNCLENBQUM7QUFDcEQsT0FBTyxLQUFLLFNBQVMsTUFBTSxxQkFBcUIsQ0FBQztBQUNqRCxPQUFPLEtBQUssU0FBUyxNQUFNLHFCQUFxQixDQUFDO0FBQ2pELE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLEtBQUssTUFBTSxnQkFBZ0IsQ0FBQztBQUN4QyxPQUFPLEtBQUssY0FBYyxNQUFNLDBCQUEwQixDQUFDO0FBQzNELE9BQU8sS0FBSyxRQUFRLE1BQU0sb0JBQW9CLENBQUM7QUFDL0MsT0FBTyxLQUFLLFVBQVUsTUFBTSxzQkFBc0IsQ0FBQztBQUNuRCxPQUFPLEtBQUssVUFBVSxNQUFNLHFCQUFxQixDQUFDO0FBRWxELE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUVoRCxPQUFPLEVBQUUsVUFBVSxFQUFFLGlCQUFpQixFQUFFLE1BQU0sZUFBZSxDQUFDO0FBRTlELE9BQU8sRUFBRSxpQkFBaUIsRUFBRSx1QkFBdUIsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBRTlFLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSw4QkFBOEIsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBRzdGLE9BQU8sRUFBRSxvQkFBb0IsRUFBRSxjQUFjLEVBQUUsUUFBUSxFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFFakYsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFcEQsT0FBTyxFQUFFLGdCQUFnQixFQUFFLDBCQUEwQixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFDeEYsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBR3ZELGNBQWMsY0FBYyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0IGNvbnN0IFBBQ0tBR0VfSURFTlRJRklFUiA9IFwiQGRieC10b29scy90dW5uZWxcIjtcbmV4cG9ydCBjb25zdCBQQUNLQUdFX1ZFUlNJT04gPSBcIjAuOS4xMzZcIjtcbmV4cG9ydCAqIGFzIGFsbG93bGlzdCBmcm9tIFwiLi9zcmMvYWxsb3dsaXN0LnRzXCI7XG5leHBvcnQgKiBhcyBjb2RlRW1haWwgZnJvbSBcIi4vc3JjL2NvZGUtZW1haWwudHNcIjtcbmV4cG9ydCAqIGFzIGZycCBmcm9tIFwiLi9zcmMvZnJwLnRzXCI7XG5leHBvcnQgKiBhcyBnYXRlIGZyb20gXCIuL3NyYy9nYXRlLnRzXCI7XG5leHBvcnQgKiBhcyBoZWFkZXJzIGZyb20gXCIuL3NyYy9oZWFkZXJzLnRzXCI7XG5leHBvcnQgKiBhcyBpbnRlcmNlcHRvciBmcm9tIFwiLi9zcmMvaW50ZXJjZXB0b3IudHNcIjtcbmV4cG9ydCAqIGFzIGxvZ2luUGFnZSBmcm9tIFwiLi9zcmMvbG9naW4tcGFnZS50c1wiO1xuZXhwb3J0ICogYXMgcGF0aFByb3h5IGZyb20gXCIuL3NyYy9wYXRoLXByb3h5LnRzXCI7XG5leHBvcnQgKiBhcyBwbHVnaW4gZnJvbSBcIi4vc3JjL3BsdWdpbi50c1wiO1xuZXhwb3J0ICogYXMgcG9ydHIgZnJvbSBcIi4vc3JjL3BvcnRyLnRzXCI7XG5leHBvcnQgKiBhcyByZXF1ZXN0Q29udGV4dCBmcm9tIFwiLi9zcmMvcmVxdWVzdC1jb250ZXh0LnRzXCI7XG5leHBvcnQgKiBhcyBzZW5kQ29kZSBmcm9tIFwiLi9zcmMvc2VuZC1jb2RlLnRzXCI7XG5leHBvcnQgKiBhcyBzaWduaW5nS2V5IGZyb20gXCIuL3NyYy9zaWduaW5nLWtleS50c1wiO1xuZXhwb3J0ICogYXMgc3VwZXJ2aXNvciBmcm9tIFwiLi9zcmMvc3VwZXJ2aXNvci50c1wiO1xuZXhwb3J0IHR5cGUgeyBDb2RlQ29weSB9IGZyb20gXCIuL3NyYy9jb2RlLWVtYWlsLnRzXCI7XG5leHBvcnQgeyBGcnBPcHRpb25zU2NoZW1hIH0gZnJvbSBcIi4vc3JjL2ZycC50c1wiO1xuZXhwb3J0IHR5cGUgeyBGcnBJbnN0YWxsT3B0aW9ucywgRnJwQ29uZmlnLCBGcnBPcHRpb25zIH0gZnJvbSBcIi4vc3JjL2ZycC50c1wiO1xuZXhwb3J0IHsgaXNBdXRoUGF0aCwgVU5BVVRIT1JJWkVEX0JPRFkgfSBmcm9tIFwiLi9zcmMvZ2F0ZS50c1wiO1xuZXhwb3J0IHR5cGUgeyBHYXRlT3B0aW9ucywgR2F0ZUFjdGlvbiB9IGZyb20gXCIuL3NyYy9nYXRlLnRzXCI7XG5leHBvcnQgeyBQUk9URUNURURfSEVBREVSUywgREVGQVVMVF9GT1JXQVJEX0hFQURFUlMgfSBmcm9tIFwiLi9zcmMvaGVhZGVycy50c1wiO1xuZXhwb3J0IHR5cGUgeyBIZWFkZXJQb2xpY3kgfSBmcm9tIFwiLi9zcmMvaGVhZGVycy50c1wiO1xuZXhwb3J0IHsgVHVubmVsVHJhbnNwb3J0U2NoZW1hLCBUdW5uZWxJbnRlcmNlcHRvck9wdGlvbnNTY2hlbWEgfSBmcm9tIFwiLi9zcmMvaW50ZXJjZXB0b3IudHNcIjtcbmV4cG9ydCB0eXBlIHsgVHVubmVsVHJhbnNwb3J0LCBUdW5uZWxJbnRlcmNlcHRvck9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvaW50ZXJjZXB0b3IudHNcIjtcbmV4cG9ydCB0eXBlIHsgTG9naW5QYWdlT3B0aW9ucyB9IGZyb20gXCIuL3NyYy9sb2dpbi1wYWdlLnRzXCI7XG5leHBvcnQgeyBBdXRoR2F0ZUNvbmZpZ1NjaGVtYSwgQXV0aEdhdGVQbHVnaW4sIGF1dGhHYXRlIH0gZnJvbSBcIi4vc3JjL3BsdWdpbi50c1wiO1xuZXhwb3J0IHR5cGUgeyBBdXRoR2F0ZUNvbmZpZywgU2VuZENvZGVPcHRpb25zLCBSZXNvbHZlZEF1dGhHYXRlQ29uZmlnLCBBdXRoR2F0ZUFwaSB9IGZyb20gXCIuL3NyYy9wbHVnaW4udHNcIjtcbmV4cG9ydCB7IFBvcnRyT3B0aW9uc1NjaGVtYSB9IGZyb20gXCIuL3NyYy9wb3J0ci50c1wiO1xuZXhwb3J0IHR5cGUgeyBQb3J0ckluc3RhbGxPcHRpb25zLCBQb3J0ckNvbmZpZywgUG9ydHJPcHRpb25zIH0gZnJvbSBcIi4vc3JjL3BvcnRyLnRzXCI7XG5leHBvcnQgeyBUVU5ORUxfVFJBQ0VfVEFHLCBUVU5ORUxfU1VCRE9NQUlOX1RSQUNFX1RBRyB9IGZyb20gXCIuL3NyYy9yZXF1ZXN0LWNvbnRleHQudHNcIjtcbmV4cG9ydCB7IEtFWV9UVExfU0VDT05EUyB9IGZyb20gXCIuL3NyYy9zaWduaW5nLWtleS50c1wiO1xuZXhwb3J0IHR5cGUgeyBTaWduaW5nS2V5IH0gZnJvbSBcIi4vc3JjL3NpZ25pbmcta2V5LnRzXCI7XG5leHBvcnQgdHlwZSB7IFByb2Nlc3NTdXBlcnZpc29yLCBQcm9jZXNzU3VwZXJ2aXNvck9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvc3VwZXJ2aXNvci50c1wiO1xuZXhwb3J0ICogZnJvbSBcIi4vZXhwb3J0cy50c1wiO1xuIl19
|
package/lib/src/gate.d.ts
CHANGED
|
@@ -55,6 +55,8 @@ export interface GateOptions {
|
|
|
55
55
|
gatePaths?: readonly string[];
|
|
56
56
|
/** Product name displayed by the hosted login page. */
|
|
57
57
|
brandName?: string;
|
|
58
|
+
/** Prefix added before the humanized tunnel subdomain in new passkey names. */
|
|
59
|
+
passkeyNamePrefix?: string;
|
|
58
60
|
}
|
|
59
61
|
/**
|
|
60
62
|
* True when the request's `Host` is one of the tunnel's public domains - i.e. it
|