tunnel: simplify allowlist grammar to bare host:port (SUBTEXT-350) by joelgwebber · Pull Request #63 · fullstorydev/subtext

joelgwebber · 2026-05-13T17:02:07Z

SUBTEXT-350: Simplify tunnel allowlist grammar to bare `host:port`

Jira: https://fullstory.atlassian.net/browse/SUBTEXT-350
Companion PR (fullstory/mn): https://github.com/cowpaths/mn/pull/104388

What changed

Mirror the server-side grammar change in the TypeScript tunnel client.

tunnel/src/allowlist.ts

OriginPattern type simplified to {host, port, isIP, raw}; scheme,
wildcard, and suffix fields removed
canonicalizeHost() collapses multi-label DNS hosts to last two labels:
www.fullstory.test → fullstory.test
Parser strips legacy scheme:// prefix and *. wildcard prefix silently
(both are no-ops under the new rules)
patternMatches() is scheme-agnostic; DNS patterns match host or
*.host; IP patterns require exact match
New export canonicalizedFrom() detects when an input was broadened

tunnel/src/main.ts

tunnel-connect handler collects canonicalization warnings before
registering patterns and spreads
canonicalized: [{input, canonical}] into the response for any
rewritten entries
Tool description updated: documents bare host:port grammar, trunk
semantics, and the canonicalized response field

skills/tunnel/SKILL.md (and live/onboard)

All examples updated to bare host:port form
Trunk semantics and canonicalized field documented

tunnel/build/ — compiled output included

Why

The old scheme://*.suffix:port syntax required callers to know the
scheme and write an explicit *. prefix. The new grammar is shorter,
scheme-agnostic, and makes subdomain coverage the default — reducing the
most common source of chrome-error://chromewebdata/ in tunneled
sessions.

Testing

All unit tests updated and passing (pnpm test in tunnel/)
End-to-end integration test via local lidar + subtext-tunnel-local MCP:
- tunnel-connect with www.fullstory.test:8043 → state: ready,
  canonicalized: [{input: "www.fullstory.test:8043", canonical: "fullstory.test:8043"}]
- Navigation to https://app.fullstory.test:8043/ui succeeded through
  the tunnel (scheme-agnostic match + subdomain coverage confirmed)
- Legacy https://*.fullstory.test:8043 input accepted, canonicalized,
  navigation succeeded

Mirror the server-side grammar change in the TypeScript allowlist client. Key changes: - OriginPattern type simplified to {host, port, isIP, raw}; Scheme, Wildcard, and Suffix fields removed - canonicalizeHost() collapses multi-label DNS hosts to last two labels (www.fullstory.test -> fullstory.test) - Parser tolerates legacy scheme:// prefix and *. prefix (stripped silently; both are no-ops under the new rules) - patternMatches() is scheme-agnostic; DNS patterns match host or *.host, IP patterns require exact match - canonicalizedFrom() detects when an input was broadened to its trunk - tunnel-connect MCP handler spreads canonicalized:[{input,canonical}] into the response for any rewritten entries - Tool description updated: documents bare host:port grammar, trunk semantics, and the canonicalized response field - SKILL.md updated with new grammar, examples, and canonicalized docs - Compiled build/ output included

jurassix

all feedback optional and all basically replace fs with example but up to you s/fullstory/example

jurassix · 2026-05-15T18:40:43Z

+
+```json
+"canonicalized": [
+  {"input": "www.fullstory.test:8043", "canonical": "fullstory.test:8043"}


feels safer to not use real ones?

Suggested change

{"input": "www.fullstory.test:8043", "canonical": "fullstory.test:8043"}

{"input": "www.example.test:8043", "canonical": "example.test:8043"}

jurassix · 2026-05-15T18:41:00Z

- Hosts must be loopback-resolving (`localhost`, `127.x`, `::1`, `*.test`, `*.localhost`).
- Schemes can mix freely — one tunnel can serve `http://...` and `https://...` entries.
+- Each entry is a bare `host:port` — for example `fullstory.test:8043` or `localhost:3000`.
+- For DNS hosts, the entry matches the bare host **and any subdomain on the same port**. List the trunk you want to allow, not individual subdomains: `fullstory.test:8043` covers `app.fullstory.test:8043`, `oauthtest.fullstory.test:8043`, and so on.


Suggested change

- For DNS hosts, the entry matches the bare host **and any subdomain on the same port**. List the trunk you want to allow, not individual subdomains: `fullstory.test:8043` covers `app.fullstory.test:8043`, `oauthtest.fullstory.test:8043`, and so on.

- For DNS hosts, the entry matches the bare host **and any subdomain on the same port**. List the trunk you want to allow, not individual subdomains: `example.test:8043` covers `app.example.test:8043`, `oauthtest.example.test:8043`, and so on.

jurassix · 2026-05-15T18:41:12Z

- No bare `*`. No port ranges. No paths.
- Hosts must be loopback-resolving (`localhost`, `127.x`, `::1`, `*.test`, `*.localhost`).
- Schemes can mix freely — one tunnel can serve `http://...` and `https://...` entries.
+- Each entry is a bare `host:port` — for example `fullstory.test:8043` or `localhost:3000`.


Suggested change

- Each entry is a bare `host:port` — for example `fullstory.test:8043` or `localhost:3000`.

- Each entry is a bare `host:port` — for example `example.test:8043` or `localhost:3000`.

jurassix · 2026-05-15T18:42:11Z

+- **App with auth/SSO redirects between subdomains** (the common case). List the trunk:
  ```
-  allowedOrigins: ["https://*.example.test:8043"]
+  allowedOrigins: ["fullstory.test:8043"]


Suggested change

allowedOrigins: ["fullstory.test:8043"]

allowedOrigins: ["example.test:8043"]

jurassix · 2026-05-15T18:42:24Z

+  allowedOrigins: ["fullstory.test:8043"]
  ```
-  Without the wildcard, the first redirect into the SSO subdomain (`oauthtest.example.test`, `auth.example.test`, etc.) returns a 502 and chromium lands on `chrome-error://chromewebdata/`.
+  This covers `app.fullstory.test:8043`, `oauthtest.fullstory.test:8043`, every other subdomain. Don't narrow to `app.fullstory.test:8043` — the first OAuth bounce will fail.


Suggested change

This covers `app.fullstory.test:8043`, `oauthtest.fullstory.test:8043`, every other subdomain. Don't narrow to `app.fullstory.test:8043` — the first OAuth bounce will fail.

This covers `app.example.test:8043`, `oauthtest.example.test:8043`, every other subdomain. Don't narrow to `app.example.test:8043` — the first OAuth bounce will fail.

jurassix · 2026-05-15T18:42:33Z

  allowedOrigins: [
-    "https://*.example.test:8043",
-    "http://127.0.0.1:8766",
+    "fullstory.test:8043",


Suggested change

"fullstory.test:8043",

"example.test:8043",

jurassix · 2026-05-15T18:42:43Z

 1. `tunnel-disconnect` the current tunnel.
 2. `live-tunnel` again — the `connection_id` is preserved across reconnect, so chromium continuity is fine.
-3. `tunnel-connect` with a wildcard that covers the redirect target (e.g. `https://*.example.test:8043` instead of `https://app.example.test:8043`).
+3. `tunnel-connect` with a trunk that covers the redirect target (e.g. `fullstory.test:8043` instead of `app.fullstory.test:8043`).


Suggested change

3. `tunnel-connect` with a trunk that covers the redirect target (e.g. `fullstory.test:8043` instead of `app.fullstory.test:8043`).

3. `tunnel-connect` with a trunk that covers the redirect target (e.g. `example.test:8043` instead of `app.example.test:8043`).

jurassix · 2026-05-15T18:45:01Z

+            "individual hostnames: `fullstory.test:8043` covers " +
+            "`app.fullstory.test:8043`, `oauthtest.fullstory.test:8043`, etc. " +
+            "Hosts are restricted to the loopback class (localhost, 127.x, " +
+            "::1, *.test, *.localhost). IP literals match exactly with no " +
+            "subdomain expansion. The response includes a `canonicalized` " +
+            "field listing any entries that were rewritten (e.g. legacy " +
+            "scheme prefix stripped, or a sub-trunk collapsed to its parent)."),


Suggested change

"individual hostnames: `fullstory.test:8043` covers " +

"`app.fullstory.test:8043`, `oauthtest.fullstory.test:8043`, etc. " +

"Hosts are restricted to the loopback class (localhost, 127.x, " +

"::1, *.test, *.localhost). IP literals match exactly with no " +

"subdomain expansion. The response includes a `canonicalized` " +

"field listing any entries that were rewritten (e.g. legacy " +

"scheme prefix stripped, or a sub-trunk collapsed to its parent)."),

"individual hostnames: `example.test:8043` covers " +

"`app.example.test:8043`, `oauthtest.example.test:8043`, etc. " +

"Hosts are restricted to the loopback class (localhost, 127.x, " +

"::1, *.test, *.localhost). IP literals match exactly with no " +

"subdomain expansion. The response includes a `canonicalized` " +

"field listing any entries that were rewritten (e.g. legacy " +

"scheme prefix stripped, or a sub-trunk collapsed to its parent)."),

jurassix · 2026-05-15T18:45:51Z

+            "individual hostnames: `fullstory.test:8043` covers " +
+            "`app.fullstory.test:8043`, `oauthtest.fullstory.test:8043`, etc. " +
+            "Hosts are restricted to the loopback class (localhost, 127.x, " +
+            "::1, *.test, *.localhost). IP literals match exactly with no " +
+            "subdomain expansion. The response includes a `canonicalized` " +
+            "field listing any entries that were rewritten (e.g. legacy " +


Suggested change

"individual hostnames: `fullstory.test:8043` covers " +

"`app.fullstory.test:8043`, `oauthtest.fullstory.test:8043`, etc. " +

"Hosts are restricted to the loopback class (localhost, 127.x, " +

"::1, *.test, *.localhost). IP literals match exactly with no " +

"subdomain expansion. The response includes a `canonicalized` " +

"field listing any entries that were rewritten (e.g. legacy " +

"individual hostnames: `example.test:8043` covers " +

"`app.example.test:8043`, `oauthtest.example.test:8043`, etc. " +

"Hosts are restricted to the loopback class (localhost, 127.x, " +

"::1, *.test, *.localhost). IP literals match exactly with no " +

"subdomain expansion. The response includes a `canonicalized` " +

"field listing any entries that were rewritten (e.g. legacy " +

joelgwebber requested a review from jurassix May 13, 2026 17:40

jurassix approved these changes May 15, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

tunnel: simplify allowlist grammar to bare host:port (SUBTEXT-350)#63

tunnel: simplify allowlist grammar to bare host:port (SUBTEXT-350)#63
joelgwebber wants to merge 1 commit into
mainfrom
joel/subtext-350-tunnel-allowlist

joelgwebber commented May 13, 2026 •

edited

Loading

Uh oh!

jurassix left a comment

Uh oh!

jurassix May 15, 2026

Uh oh!

jurassix May 15, 2026

Uh oh!

jurassix May 15, 2026

Uh oh!

jurassix May 15, 2026

Uh oh!

jurassix May 15, 2026

Uh oh!

jurassix May 15, 2026

Uh oh!

jurassix May 15, 2026

Uh oh!

jurassix May 15, 2026

Uh oh!

jurassix May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	{"input": "www.fullstory.test:8043", "canonical": "fullstory.test:8043"}
	{"input": "www.example.test:8043", "canonical": "example.test:8043"}

	- For DNS hosts, the entry matches the bare host and any subdomain on the same port. List the trunk you want to allow, not individual subdomains: `fullstory.test:8043` covers `app.fullstory.test:8043`, `oauthtest.fullstory.test:8043`, and so on.
	- For DNS hosts, the entry matches the bare host and any subdomain on the same port. List the trunk you want to allow, not individual subdomains: `example.test:8043` covers `app.example.test:8043`, `oauthtest.example.test:8043`, and so on.

	- Each entry is a bare `host:port` — for example `fullstory.test:8043` or `localhost:3000`.
	- Each entry is a bare `host:port` — for example `example.test:8043` or `localhost:3000`.

	allowedOrigins: ["fullstory.test:8043"]
	allowedOrigins: ["example.test:8043"]

	This covers `app.fullstory.test:8043`, `oauthtest.fullstory.test:8043`, every other subdomain. Don't narrow to `app.fullstory.test:8043` — the first OAuth bounce will fail.
	This covers `app.example.test:8043`, `oauthtest.example.test:8043`, every other subdomain. Don't narrow to `app.example.test:8043` — the first OAuth bounce will fail.

	3. `tunnel-connect` with a trunk that covers the redirect target (e.g. `fullstory.test:8043` instead of `app.fullstory.test:8043`).
	3. `tunnel-connect` with a trunk that covers the redirect target (e.g. `example.test:8043` instead of `app.example.test:8043`).

Conversation

joelgwebber commented May 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

SUBTEXT-350: Simplify tunnel allowlist grammar to bare host:port

What changed

Why

Testing

Uh oh!

jurassix left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

joelgwebber commented May 13, 2026 •

edited

Loading

SUBTEXT-350: Simplify tunnel allowlist grammar to bare `host:port`