@dbx-tools/tunnel 0.9.131 → 0.9.132
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 +89 -84
- package/index.ts +1 -1
- package/lib/index.d.ts +1 -1
- package/lib/index.js +2 -2
- package/package.json +8 -8
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.
|
|
@@ -84,7 +84,7 @@ middleware on the app's Express server (no separate proxy process).
|
|
|
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
86
|
with discoverable passkeys, enroll multiple devices, and name or remove them
|
|
87
|
-
through [
|
|
87
|
+
through [@dbx-tools/ui/auth](../../ui/appkit).
|
|
88
88
|
- Allow-list patterns in three shapes, matched in order: a domain shortcut
|
|
89
89
|
(`example.com`, `@example.com`), a shell-style glob (`*@example.com`), or a
|
|
90
90
|
regex literal (`/^ops-.*@example\.com$/`). An empty list allows nobody.
|
|
@@ -95,14 +95,14 @@ middleware on the app's Express server (no separate proxy process).
|
|
|
95
95
|
`x-forwarded-access-token`, which would otherwise let anyone drive the app's
|
|
96
96
|
workspace calls with a pasted token. Add an app's own headers with
|
|
97
97
|
`TUNNEL_FORWARD_HEADERS`.
|
|
98
|
-
- Only
|
|
98
|
+
- Only Portr traffic is gated. The gate identifies tunnel requests by their
|
|
99
99
|
`Host` header (`TUNNEL_PUBLIC_DOMAIN`), which portr's client preserves from the
|
|
100
100
|
public visitor. Platform front-door traffic and any other local caller carry a
|
|
101
|
-
different `Host` and pass through
|
|
101
|
+
different `Host` and pass through without a gate, so health checks and the workspace UI
|
|
102
102
|
keep working. (There is no portr-injected identifying header and no source-IP
|
|
103
103
|
signal - the client dials the app over plain loopback - so `Host` is the signal.)
|
|
104
104
|
- SPA-aware gating: static assets and the login routes stay open so the browser
|
|
105
|
-
can load the client and render the login form
|
|
105
|
+
can load the client and render the login form. Every other `/api/*` needs a
|
|
106
106
|
valid session cookie or gets `401`. A WebSocket handshake is an ordinary `GET`
|
|
107
107
|
and runs through the same gate.
|
|
108
108
|
- Supervised teardown - `tunnelInterceptor` registers its tunnel supervisor with
|
|
@@ -114,10 +114,10 @@ middleware on the app's Express server (no separate proxy process).
|
|
|
114
114
|
supervision alone is not enough: portr can stay alive after the edge drops the
|
|
115
115
|
registration, leaving the subdomain dark until a full app bounce.
|
|
116
116
|
- 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
|
|
117
|
+
cannot send codes locks everyone out. `@dbx-tools/email` is an optional peer
|
|
118
|
+
dependency, imported lazily. The app that mounts the gate provides it.
|
|
119
119
|
|
|
120
|
-
##
|
|
120
|
+
## Choose tunnel and authentication behavior
|
|
121
121
|
|
|
122
122
|
A bare tunnel (`ngrok`, `portr` on its own) makes the app reachable by anyone
|
|
123
123
|
with the URL. This package keeps the tunnel but puts a gate in front of it,
|
|
@@ -126,7 +126,12 @@ reusing what the app already has: AppKit's cache for code storage, the
|
|
|
126
126
|
Because it rides inside the app's own `createApp`, there is no second process to
|
|
127
127
|
supervise and no wrapper command to thread flags through.
|
|
128
128
|
|
|
129
|
-
|
|
129
|
+
Use [@dbx-tools/auth](../auth) to obtain Databricks credentials for outbound
|
|
130
|
+
workspace calls. It doesn't authenticate visitors to a public application. Use
|
|
131
|
+
the tunnel gate for visitor access, or run with `TUNNEL_INSECURE=true` only when
|
|
132
|
+
the public endpoint intentionally requires no gate.
|
|
133
|
+
|
|
134
|
+
## Full app configuration
|
|
130
135
|
|
|
131
136
|
```ts
|
|
132
137
|
import { appkit } from "@dbx-tools/appkit";
|
|
@@ -152,15 +157,15 @@ await appkit.createApp({
|
|
|
152
157
|
});
|
|
153
158
|
```
|
|
154
159
|
|
|
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
|
|
160
|
+
Two pieces run in one process: `tunnelInterceptor()` runs the selected tunnel
|
|
161
|
+
clients (children bound to the app), and `authGate()` is the in-app gate. Portr
|
|
162
|
+
remains the default. Set `transport: "frp"` or `TUNNEL_TRANSPORT=frp`. Use `both` with
|
|
158
163
|
separate `TUNNEL_PUBLIC_DOMAIN` and `TUNNEL_FRP_PUBLIC_DOMAIN` hosts.
|
|
159
|
-
See [Use
|
|
164
|
+
See [Use the gate](#use-the-gate) for the gate on its own.
|
|
160
165
|
|
|
161
166
|
## Options
|
|
162
167
|
|
|
163
|
-
The interceptor reads tunnel wiring from the environment
|
|
168
|
+
The interceptor reads tunnel wiring from the environment. The gate (the `authGate`
|
|
164
169
|
plugin) reads its own settings the same way, so a deployment configures both
|
|
165
170
|
without touching code.
|
|
166
171
|
|
|
@@ -185,7 +190,7 @@ without touching code.
|
|
|
185
190
|
| `FRP_PROXY_NAME` | public domain's first label |
|
|
186
191
|
| `FRP_PATH` | `DATABRICKS_APP_NAME` |
|
|
187
192
|
| `FRP_STRIP_PREFIX` | `true` for non-root paths |
|
|
188
|
-
| `TUNNEL_FORWARD_HEADERS` | the built-in `x-`
|
|
193
|
+
| `TUNNEL_FORWARD_HEADERS` | the built-in `x-` allowlist |
|
|
189
194
|
| `TUNNEL_AUTH_JWT_SECRET` | an ephemeral per-process key |
|
|
190
195
|
|
|
191
196
|
Every tunnel-owned variable is `TUNNEL_`-prefixed because the tunnel shares one
|
|
@@ -193,15 +198,15 @@ environment with the app it fronts, so a generic name may already belong to the
|
|
|
193
198
|
app. Only the names listed above are read.
|
|
194
199
|
`PORTR_*` and `FRP_*` keep their names: those namespaces belong to the clients
|
|
195
200
|
itself, as does `DATABRICKS_APP_PORT`, which the platform sets and the tunnel
|
|
196
|
-
|
|
201
|
+
honors.
|
|
197
202
|
|
|
198
|
-
##
|
|
203
|
+
## Keep sessions across restarts
|
|
199
204
|
|
|
200
|
-
The signing key decides whether an already-issued session
|
|
205
|
+
The signing key decides whether an already-issued session cookie still verifies,
|
|
201
206
|
so where that key comes from is what decides whether a restart signs everyone out.
|
|
202
207
|
Resolution order:
|
|
203
208
|
|
|
204
|
-
1. **`TUNNEL_AUTH_JWT_SECRET`**, when set.
|
|
209
|
+
1. **`TUNNEL_AUTH_JWT_SECRET`**, when set. An
|
|
205
210
|
operator-held secret needs no shared cache, and it survives a cache flush.
|
|
206
211
|
2. **A key persisted in AppKit's cache for 30 days.** With a persistent
|
|
207
212
|
`CacheStorage` (Lakebase) the key outlives the process, so cookies stay valid
|
|
@@ -210,7 +215,7 @@ Resolution order:
|
|
|
210
215
|
same as having no secret at all.
|
|
211
216
|
|
|
212
217
|
Getting that persistence is not automatic, and the gate does the work at boot
|
|
213
|
-
|
|
218
|
+
using `lakebaseResolver.applyLakebaseEnv()`: it turns `LAKEBASE_ENDPOINT` into the
|
|
214
219
|
`PGHOST` / `PGDATABASE` / `PGUSER` the cache's pool also needs. Without them
|
|
215
220
|
AppKit cannot build the pool, silently uses an in-memory cache, and every
|
|
216
221
|
redeploy signs everyone out - so the startup log says which one you got
|
|
@@ -220,33 +225,33 @@ Resolution order:
|
|
|
220
225
|
3. **An ephemeral per-process key**, when there is no secret and no reachable
|
|
221
226
|
cache. Sessions do not survive a restart, but the gate still serves: the key
|
|
222
227
|
only validates an existing session, so losing it costs sessions, never
|
|
223
|
-
admission. A caller still needs a code delivered to an
|
|
228
|
+
admission. A caller still needs a code delivered to an address on the allowlist.
|
|
224
229
|
|
|
225
|
-
The cached key is read, generated
|
|
226
|
-
booting together both miss the cache, so both generate
|
|
227
|
-
|
|
230
|
+
The cached key is read, generated and stored, then read again. Two instances
|
|
231
|
+
booting together both miss the cache, so both generate. Adopting whatever is
|
|
232
|
+
stored afterward makes them converge on one key instead of each trusting
|
|
228
233
|
the one it minted. Set `TUNNEL_AUTH_JWT_SECRET` to remove the race entirely.
|
|
229
234
|
|
|
230
235
|
`TUNNEL_AUTH_SESSION_TTL` defaults to the same 30 days the key is stored for, on
|
|
231
236
|
purpose - a key that expired before the cookies it signed would sign everyone out
|
|
232
237
|
for no reason.
|
|
233
238
|
|
|
234
|
-
##
|
|
239
|
+
## <a id="email-code-subject"></a> Put the email code in the subject
|
|
235
240
|
|
|
236
|
-
The subject line the gate
|
|
241
|
+
The subject line the gate sends is `123456 is your verification code` -
|
|
237
242
|
`--subject` is the template the code is spliced into, not the literal line.
|
|
238
243
|
|
|
239
|
-
Mobile autofill
|
|
244
|
+
Mobile autofill reads notification text instead of email body content. iOS scans
|
|
240
245
|
incoming notification text for a code and offers to fill it - natively for
|
|
241
246
|
Messages and Mail, and since iOS 26 for any app's notification, which is what
|
|
242
247
|
finally made Gmail work. A notification carries the sender, the subject, and a
|
|
243
248
|
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
|
|
249
|
+
matter how carefully the body is formatted, which is why a correctly shaped
|
|
245
250
|
`text/plain` part alone produced no prompt in Gmail.
|
|
246
251
|
|
|
247
252
|
So the code goes in both strings a notification actually shows:
|
|
248
253
|
|
|
249
|
-
- **The subject**, code
|
|
254
|
+
- **The subject**, with the code first, because a notification and an inbox row both
|
|
250
255
|
truncate: `123456 is your verification code` survives the cut wherever it lands,
|
|
251
256
|
and keeps the code in the same sentence as the words the heuristics look for.
|
|
252
257
|
A subject that does not use the conventional `Your ...` phrasing is treated as
|
|
@@ -256,11 +261,11 @@ So the code goes in both strings a notification actually shows:
|
|
|
256
261
|
(`Your verification code is: 123456`).
|
|
257
262
|
|
|
258
263
|
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
|
-
|
|
264
|
+
shows the code once as a large styled body heading. It does not use Apple's
|
|
265
|
+
domain-bound `@domain #code` trailer, which binds a code to a single origin.
|
|
266
|
+
Subject and preheader text work across clients and need no origin.
|
|
262
267
|
|
|
263
|
-
###
|
|
268
|
+
### Sign everyone out
|
|
264
269
|
|
|
265
270
|
`TUNNEL_AUTH_SESSION_CUTOFF` (or `sessionCutoff` on the `authGate` config)
|
|
266
271
|
invalidates every session issued before a given moment:
|
|
@@ -276,31 +281,31 @@ ISO instant, epoch seconds or millis from `date +%s`, and a relative duration
|
|
|
276
281
|
(`-30d`, `12 hours ago`) all work - the relative spelling being the one an
|
|
277
282
|
operator usually wants, since "sign out anything older than a month" needs no
|
|
278
283
|
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
|
|
284
|
+
resolved: the cutoff is part of the key's cache key (moving it orphans the
|
|
280
285
|
previous key), and it is also checked against each token's `iat` (which is what
|
|
281
286
|
makes it bite when `TUNNEL_AUTH_JWT_SECRET` is set and there is no key to
|
|
282
287
|
rotate).
|
|
283
288
|
|
|
284
|
-
A
|
|
289
|
+
A future date is clamped to now, because an unclamped one would refuse the
|
|
285
290
|
sessions it is about to mint as well as the old ones - an app nobody can sign in
|
|
286
291
|
to, from a mistyped year. An unparseable value is ignored with a warning rather
|
|
287
292
|
than failing startup: this is the switch that gets a fleet back in.
|
|
288
293
|
|
|
289
|
-
## Inbound
|
|
294
|
+
## Inbound header policy
|
|
290
295
|
|
|
291
296
|
Tunnel traffic arrives from the public internet, so every header on it is
|
|
292
297
|
attacker-controlled - and the headers an app trusts are exactly the ones a caller
|
|
293
298
|
must not be able to write, because the app cannot tell a header the Databricks
|
|
294
299
|
front door set from one a browser typed.
|
|
295
300
|
|
|
296
|
-
Enumerating headers to remove is a losing game (a
|
|
301
|
+
Enumerating headers to remove is a losing game (a denylist is only correct until
|
|
297
302
|
the platform adds a header), so the policy is inverted: **every `x-`-prefixed
|
|
298
303
|
request header is stripped from tunnel traffic unless a pattern allows it.** A
|
|
299
304
|
header nobody thought about is removed rather than trusted. Non-`x-` headers -
|
|
300
305
|
`content-type`, `accept`, `authorization`, `cookie` - are the app's normal input
|
|
301
306
|
and pass through untouched.
|
|
302
307
|
|
|
303
|
-
The default
|
|
308
|
+
The default allowlist covers the `x-` namespaces this repo's own client sends
|
|
304
309
|
and its own server reads, so a dbx-tools app works behind the tunnel with no
|
|
305
310
|
configuration:
|
|
306
311
|
|
|
@@ -312,8 +317,8 @@ configuration:
|
|
|
312
317
|
|
|
313
318
|
Add an app's own headers with `TUNNEL_FORWARD_HEADERS` (or `forwardHeaders` on
|
|
314
319
|
`authGate`). Each entry is a literal name, a shell-style glob, or a `/regex/` -
|
|
315
|
-
the same three shapes the email
|
|
316
|
-
|
|
320
|
+
the same three shapes the email allowlist takes - and the configured list is
|
|
321
|
+
combined with the defaults, so extending it never silently breaks the built-in
|
|
317
322
|
surfaces:
|
|
318
323
|
|
|
319
324
|
```sh
|
|
@@ -323,17 +328,17 @@ TUNNEL_FORWARD_HEADERS="x-acme-*, /^x-trace-/, x-tenant" ...
|
|
|
323
328
|
Some headers no pattern can forward. These decide who a request is and where it
|
|
324
329
|
came from, and on tunnel traffic only the gate may answer that:
|
|
325
330
|
|
|
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
|
-
[
|
|
331
|
+
| Header | Why it is never forwarded |
|
|
332
|
+
| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
333
|
+
| `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. |
|
|
334
|
+
| `x-forwarded-user`, `-email` | Caller identity. The gate sets these itself, from a verified session. |
|
|
335
|
+
| `x-forwarded-preferred-username` | Display identity from the IdP. |
|
|
336
|
+
| `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. |
|
|
337
|
+
| `x-forwarded-for`, `x-real-ip` | Client IP. Spoofing forges the audit trail and gives a caller a fresh rate-limit bucket per request. |
|
|
338
|
+
| `x-request-id` | Request correlation UUID. Forged or colliding ids make logs unreliable. |
|
|
339
|
+
|
|
340
|
+
The identity headers are AppKit's OBO contract. The rest are the
|
|
341
|
+
[X-Forwarded-* set that Databricks Apps documents passing to an
|
|
337
342
|
app](https://docs.databricks.com/aws/en/dev-tools/databricks-apps/http-headers),
|
|
338
343
|
plus the conventional `x-forwarded-proto`/`-port`/`x-real-ip` a library may read
|
|
339
344
|
anyway. Dropping the transport headers costs nothing: `xfwd` re-adds them from the
|
|
@@ -342,12 +347,12 @@ caller's claim. Rate limiting reads the client IP before stripping, and takes th
|
|
|
342
347
|
**rightmost** `x-forwarded-for` entry - the only one portr appended rather than a
|
|
343
348
|
client supplied.
|
|
344
349
|
|
|
345
|
-
## Use
|
|
350
|
+
## Use the gate
|
|
346
351
|
|
|
347
352
|
`authGate()` is the gate. Register it in your app's `createApp` plugins and it
|
|
348
353
|
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
|
|
354
|
+
own server through AppKit's `this.context`. By default it delivers codes through the
|
|
355
|
+
app's shared `@dbx-tools/email` transport, so the minimal wiring is an
|
|
351
356
|
`allow` list (or `TUNNEL_AUTH_ALLOW`):
|
|
352
357
|
|
|
353
358
|
```ts
|
|
@@ -365,14 +370,14 @@ await appkit.createApp({
|
|
|
365
370
|
```
|
|
366
371
|
|
|
367
372
|
Override `sendCode` only to deliver through something other than the shared
|
|
368
|
-
transport
|
|
373
|
+
transport. The default builds the OTP email (code in the subject + preheader for
|
|
369
374
|
mobile autofill) and sends it as the system sender. `@dbx-tools/email` is an
|
|
370
|
-
|
|
375
|
+
optional peer dependency - a tunnel without the gate needs no mail - so the app
|
|
371
376
|
that mounts `authGate` must include it (or run `TUNNEL_INSECURE=true` to skip the
|
|
372
|
-
gate)
|
|
377
|
+
gate). A missing transport fails fast at boot.
|
|
373
378
|
|
|
374
379
|
`GET /api/email/auth/status` is what a client asks before deciding to render a
|
|
375
|
-
login screen, and it answers per
|
|
380
|
+
login screen, and it answers per request, not per deployment: on a non-tunnel
|
|
376
381
|
`Host` it returns `{ authenticated: false, enabled: false }` without looking at
|
|
377
382
|
the cookie, because that request was never going to be gated. So the same running
|
|
378
383
|
app shows the OTP screen to a portr visitor and no login at all to a browser on
|
|
@@ -380,17 +385,17 @@ app shows the OTP screen to a portr visitor and no login at all to a browser on
|
|
|
380
385
|
|
|
381
386
|
When the hosted login page interrupts a navigation, it carries the original
|
|
382
387
|
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
|
-
|
|
388
|
+
after OTP verification. API denials expose the hosted login URL in `loginPath`.
|
|
389
|
+
Its `returnTo` query value comes from a same-origin referrer and is normalized
|
|
385
390
|
to an application path, so it cannot become an external redirect.
|
|
386
391
|
|
|
387
392
|
`POST /api/email/auth/logout` clears the current session and returns
|
|
388
393
|
`{ ok, redirectTo }`. `GET` on the same path clears the session and answers with
|
|
389
394
|
a `303` redirect. `logoutRedirectPath` or
|
|
390
|
-
`TUNNEL_AUTH_LOGOUT_REDIRECT` controls the same-origin destination
|
|
395
|
+
`TUNNEL_AUTH_LOGOUT_REDIRECT` controls the same-origin destination. `/` is the
|
|
391
396
|
default because reloading the application root presents the login gate again.
|
|
392
397
|
|
|
393
|
-
## Verify
|
|
398
|
+
## Verify the live Portr install
|
|
394
399
|
|
|
395
400
|
The normal test task skips the networked portr release download. Run the
|
|
396
401
|
integration test explicitly when validating GitHub release discovery, archive
|
|
@@ -402,7 +407,7 @@ RUN_LIVE_INSTALL_TEST=1 bun test packages/js/node/tunnel/test/portr-install.inte
|
|
|
402
407
|
|
|
403
408
|
The test installs into an isolated temporary home, runs `portr --version`, logs
|
|
404
409
|
the selected release and executable path, then removes the temporary directory.
|
|
405
|
-
The same command also discovers `frp-install.integration.test.ts
|
|
410
|
+
The same command also discovers `frp-install.integration.test.ts`. It downloads
|
|
406
411
|
the pinned `frpc` release and verifies its exact version. On macOS the installer
|
|
407
412
|
applies an ad-hoc signature before version detection because the unsigned
|
|
408
413
|
upstream binary is otherwise terminated by the platform loader.
|
|
@@ -422,13 +427,13 @@ upstream binary is otherwise terminated by the platform loader.
|
|
|
422
427
|
- `signingKey` - the cache-persisted Better Auth secret and
|
|
423
428
|
`TUNNEL_AUTH_SESSION_CUTOFF` force-clear cutoff.
|
|
424
429
|
- `allowlist` - email domain / glob / regex matching and `looksLikeEmail`.
|
|
425
|
-
- `headers` - the inbound-header
|
|
430
|
+
- `headers` - the inbound-header allowlist: `toHeaderPolicy()`,
|
|
426
431
|
`DEFAULT_FORWARD_HEADERS`, and the `PROTECTED_HEADERS` no pattern can forward.
|
|
427
|
-
- `rate-limit` - the in-memory fixed-window limiter (single-instance only
|
|
432
|
+
- `rate-limit` - the in-memory fixed-window limiter (single-instance only, not
|
|
428
433
|
distributed).
|
|
429
434
|
- `portr` - portr install, config rendering, and child launch.
|
|
430
435
|
- `_config` - exact environment-only lookup for canonical `TUNNEL_*` names.
|
|
431
436
|
|
|
432
437
|
Browser-safe gate contracts live in
|
|
433
|
-
[
|
|
434
|
-
credential manager live in [
|
|
438
|
+
[@dbx-tools/shared-auth](../../shared/auth). The passkey-first React login and
|
|
439
|
+
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.132";
|
|
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.132";
|
|
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.132";
|
|
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,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSwyQ0FBMkM7QUFDM0MsbURBQW1EO0FBQ25ELHdFQUF3RTtBQUV4RSxNQUFNLENBQUMsTUFBTSxrQkFBa0IsR0FBRyxtQkFBbUIsQ0FBQztBQUN0RCxNQUFNLENBQUMsTUFBTSxlQUFlLEdBQUcsU0FBUyxDQUFDO0FBQ3pDLE9BQU8sS0FBSyxTQUFTLE1BQU0sb0JBQW9CLENBQUM7QUFDaEQsT0FBTyxLQUFLLFNBQVMsTUFBTSxxQkFBcUIsQ0FBQztBQUNqRCxPQUFPLEtBQUssR0FBRyxNQUFNLGNBQWMsQ0FBQztBQUNwQyxPQUFPLEtBQUssSUFBSSxNQUFNLGVBQWUsQ0FBQztBQUN0QyxPQUFPLEtBQUssT0FBTyxNQUFNLGtCQUFrQixDQUFDO0FBQzVDLE9BQU8sS0FBSyxXQUFXLE1BQU0sc0JBQXNCLENBQUM7QUFDcEQsT0FBTyxLQUFLLFNBQVMsTUFBTSxxQkFBcUIsQ0FBQztBQUNqRCxPQUFPLEtBQUssU0FBUyxNQUFNLHFCQUFxQixDQUFDO0FBQ2pELE9BQU8sS0FBSyxNQUFNLE1BQU0saUJBQWlCLENBQUM7QUFDMUMsT0FBTyxLQUFLLEtBQUssTUFBTSxnQkFBZ0IsQ0FBQztBQUN4QyxPQUFPLEtBQUssY0FBYyxNQUFNLDBCQUEwQixDQUFDO0FBQzNELE9BQU8sS0FBSyxRQUFRLE1BQU0sb0JBQW9CLENBQUM7QUFDL0MsT0FBTyxLQUFLLFVBQVUsTUFBTSxzQkFBc0IsQ0FBQztBQUNuRCxPQUFPLEtBQUssVUFBVSxNQUFNLHFCQUFxQixDQUFDO0FBRWxELE9BQU8sRUFBRSxnQkFBZ0IsRUFBRSxNQUFNLGNBQWMsQ0FBQztBQUVoRCxPQUFPLEVBQUUsVUFBVSxFQUFFLGlCQUFpQixFQUFFLE1BQU0sZUFBZSxDQUFDO0FBRTlELE9BQU8sRUFBRSxpQkFBaUIsRUFBRSx1QkFBdUIsRUFBRSxNQUFNLGtCQUFrQixDQUFDO0FBRTlFLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSw4QkFBOEIsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBRzdGLE9BQU8sRUFBRSxvQkFBb0IsRUFBRSxjQUFjLEVBQUUsUUFBUSxFQUFFLE1BQU0saUJBQWlCLENBQUM7QUFFakYsT0FBTyxFQUFFLGtCQUFrQixFQUFFLE1BQU0sZ0JBQWdCLENBQUM7QUFFcEQsT0FBTyxFQUFFLGdCQUFnQixFQUFFLDBCQUEwQixFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUFDeEYsT0FBTyxFQUFFLGVBQWUsRUFBRSxNQUFNLHNCQUFzQixDQUFDO0FBR3ZELGNBQWMsY0FBYyxDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLy8gR0VORVJBVEVEIGJ5IHByb2plbiB3YXRjaCAtIERPIE5PVCBFRElULlxuLy8gUmVnZW5lcmF0ZWQgZnJvbSB0aGUgZXhwb3J0aW5nIG1vZHVsZXMgaW4gLi9zcmMuXG4vLyBIYW5kIGVkaXRzIGFyZSBvdmVyd3JpdHRlbiBvbiB0aGUgbmV4dCB3YXRjaDsgdGhpcyBmaWxlIGlzIHJlYWQtb25seS5cblxuZXhwb3J0IGNvbnN0IFBBQ0tBR0VfSURFTlRJRklFUiA9IFwiQGRieC10b29scy90dW5uZWxcIjtcbmV4cG9ydCBjb25zdCBQQUNLQUdFX1ZFUlNJT04gPSBcIjAuOS4xMzJcIjtcbmV4cG9ydCAqIGFzIGFsbG93bGlzdCBmcm9tIFwiLi9zcmMvYWxsb3dsaXN0LnRzXCI7XG5leHBvcnQgKiBhcyBjb2RlRW1haWwgZnJvbSBcIi4vc3JjL2NvZGUtZW1haWwudHNcIjtcbmV4cG9ydCAqIGFzIGZycCBmcm9tIFwiLi9zcmMvZnJwLnRzXCI7XG5leHBvcnQgKiBhcyBnYXRlIGZyb20gXCIuL3NyYy9nYXRlLnRzXCI7XG5leHBvcnQgKiBhcyBoZWFkZXJzIGZyb20gXCIuL3NyYy9oZWFkZXJzLnRzXCI7XG5leHBvcnQgKiBhcyBpbnRlcmNlcHRvciBmcm9tIFwiLi9zcmMvaW50ZXJjZXB0b3IudHNcIjtcbmV4cG9ydCAqIGFzIGxvZ2luUGFnZSBmcm9tIFwiLi9zcmMvbG9naW4tcGFnZS50c1wiO1xuZXhwb3J0ICogYXMgcGF0aFByb3h5IGZyb20gXCIuL3NyYy9wYXRoLXByb3h5LnRzXCI7XG5leHBvcnQgKiBhcyBwbHVnaW4gZnJvbSBcIi4vc3JjL3BsdWdpbi50c1wiO1xuZXhwb3J0ICogYXMgcG9ydHIgZnJvbSBcIi4vc3JjL3BvcnRyLnRzXCI7XG5leHBvcnQgKiBhcyByZXF1ZXN0Q29udGV4dCBmcm9tIFwiLi9zcmMvcmVxdWVzdC1jb250ZXh0LnRzXCI7XG5leHBvcnQgKiBhcyBzZW5kQ29kZSBmcm9tIFwiLi9zcmMvc2VuZC1jb2RlLnRzXCI7XG5leHBvcnQgKiBhcyBzaWduaW5nS2V5IGZyb20gXCIuL3NyYy9zaWduaW5nLWtleS50c1wiO1xuZXhwb3J0ICogYXMgc3VwZXJ2aXNvciBmcm9tIFwiLi9zcmMvc3VwZXJ2aXNvci50c1wiO1xuZXhwb3J0IHR5cGUgeyBDb2RlQ29weSB9IGZyb20gXCIuL3NyYy9jb2RlLWVtYWlsLnRzXCI7XG5leHBvcnQgeyBGcnBPcHRpb25zU2NoZW1hIH0gZnJvbSBcIi4vc3JjL2ZycC50c1wiO1xuZXhwb3J0IHR5cGUgeyBGcnBJbnN0YWxsT3B0aW9ucywgRnJwQ29uZmlnLCBGcnBPcHRpb25zIH0gZnJvbSBcIi4vc3JjL2ZycC50c1wiO1xuZXhwb3J0IHsgaXNBdXRoUGF0aCwgVU5BVVRIT1JJWkVEX0JPRFkgfSBmcm9tIFwiLi9zcmMvZ2F0ZS50c1wiO1xuZXhwb3J0IHR5cGUgeyBHYXRlT3B0aW9ucywgR2F0ZUFjdGlvbiB9IGZyb20gXCIuL3NyYy9nYXRlLnRzXCI7XG5leHBvcnQgeyBQUk9URUNURURfSEVBREVSUywgREVGQVVMVF9GT1JXQVJEX0hFQURFUlMgfSBmcm9tIFwiLi9zcmMvaGVhZGVycy50c1wiO1xuZXhwb3J0IHR5cGUgeyBIZWFkZXJQb2xpY3kgfSBmcm9tIFwiLi9zcmMvaGVhZGVycy50c1wiO1xuZXhwb3J0IHsgVHVubmVsVHJhbnNwb3J0U2NoZW1hLCBUdW5uZWxJbnRlcmNlcHRvck9wdGlvbnNTY2hlbWEgfSBmcm9tIFwiLi9zcmMvaW50ZXJjZXB0b3IudHNcIjtcbmV4cG9ydCB0eXBlIHsgVHVubmVsVHJhbnNwb3J0LCBUdW5uZWxJbnRlcmNlcHRvck9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvaW50ZXJjZXB0b3IudHNcIjtcbmV4cG9ydCB0eXBlIHsgTG9naW5QYWdlT3B0aW9ucyB9IGZyb20gXCIuL3NyYy9sb2dpbi1wYWdlLnRzXCI7XG5leHBvcnQgeyBBdXRoR2F0ZUNvbmZpZ1NjaGVtYSwgQXV0aEdhdGVQbHVnaW4sIGF1dGhHYXRlIH0gZnJvbSBcIi4vc3JjL3BsdWdpbi50c1wiO1xuZXhwb3J0IHR5cGUgeyBBdXRoR2F0ZUNvbmZpZywgU2VuZENvZGVPcHRpb25zLCBSZXNvbHZlZEF1dGhHYXRlQ29uZmlnLCBBdXRoR2F0ZUFwaSB9IGZyb20gXCIuL3NyYy9wbHVnaW4udHNcIjtcbmV4cG9ydCB7IFBvcnRyT3B0aW9uc1NjaGVtYSB9IGZyb20gXCIuL3NyYy9wb3J0ci50c1wiO1xuZXhwb3J0IHR5cGUgeyBQb3J0ckluc3RhbGxPcHRpb25zLCBQb3J0ckNvbmZpZywgUG9ydHJPcHRpb25zIH0gZnJvbSBcIi4vc3JjL3BvcnRyLnRzXCI7XG5leHBvcnQgeyBUVU5ORUxfVFJBQ0VfVEFHLCBUVU5ORUxfU1VCRE9NQUlOX1RSQUNFX1RBRyB9IGZyb20gXCIuL3NyYy9yZXF1ZXN0LWNvbnRleHQudHNcIjtcbmV4cG9ydCB7IEtFWV9UVExfU0VDT05EUyB9IGZyb20gXCIuL3NyYy9zaWduaW5nLWtleS50c1wiO1xuZXhwb3J0IHR5cGUgeyBTaWduaW5nS2V5IH0gZnJvbSBcIi4vc3JjL3NpZ25pbmcta2V5LnRzXCI7XG5leHBvcnQgdHlwZSB7IFByb2Nlc3NTdXBlcnZpc29yLCBQcm9jZXNzU3VwZXJ2aXNvck9wdGlvbnMgfSBmcm9tIFwiLi9zcmMvc3VwZXJ2aXNvci50c1wiO1xuZXhwb3J0ICogZnJvbSBcIi4vZXhwb3J0cy50c1wiO1xuIl19
|
package/package.json
CHANGED
|
@@ -19,21 +19,21 @@
|
|
|
19
19
|
"projen": "projen"
|
|
20
20
|
},
|
|
21
21
|
"devDependencies": {
|
|
22
|
-
"@dbx-tools/email": "^0.9.
|
|
22
|
+
"@dbx-tools/email": "^0.9.132",
|
|
23
23
|
"@types/bun": "1.4.2",
|
|
24
24
|
"@types/node": "^24.6.0",
|
|
25
25
|
"typescript": "^5.9.3"
|
|
26
26
|
},
|
|
27
27
|
"peerDependencies": {
|
|
28
|
-
"@dbx-tools/email": "^0.9.
|
|
28
|
+
"@dbx-tools/email": "^0.9.132"
|
|
29
29
|
},
|
|
30
30
|
"dependencies": {
|
|
31
31
|
"@databricks/appkit": "0.81.0",
|
|
32
|
-
"@dbx-tools/appkit": "^0.9.
|
|
33
|
-
"@dbx-tools/auth-gate": "^0.9.
|
|
34
|
-
"@dbx-tools/core": "^0.9.
|
|
35
|
-
"@dbx-tools/shared-auth": "^0.9.
|
|
36
|
-
"@dbx-tools/shared-core": "^0.9.
|
|
32
|
+
"@dbx-tools/appkit": "^0.9.132",
|
|
33
|
+
"@dbx-tools/auth-gate": "^0.9.132",
|
|
34
|
+
"@dbx-tools/core": "^0.9.132",
|
|
35
|
+
"@dbx-tools/shared-auth": "^0.9.132",
|
|
36
|
+
"@dbx-tools/shared-core": "^0.9.132",
|
|
37
37
|
"@types/express": "^5.0.5",
|
|
38
38
|
"better-call": "1.4.0",
|
|
39
39
|
"http-proxy-3": "^1.23.1",
|
|
@@ -113,7 +113,7 @@
|
|
|
113
113
|
"./package.json": "./package.json"
|
|
114
114
|
}
|
|
115
115
|
},
|
|
116
|
-
"version": "0.9.
|
|
116
|
+
"version": "0.9.132",
|
|
117
117
|
"types": "./lib/index.d.ts",
|
|
118
118
|
"dbxToolsConfig": {
|
|
119
119
|
"tags": [
|