Ask to reach a host
A forge hosted by another reaches the internet only through its host's gate, by name, on port 443, and only the names on the host's list. The list starts as the public git hosts (GitHub, GitLab, Codeberg, Bitbucket) and the forges beside it. A person who connects their own forge on their own domain is refused by the gate, and cannot change the host's list. So the hosted forge asks, and the host's admin answers.
On the hosted forge
- The refusal. Settings, Connected accounts says one sentence where the form was: "This forge is hosted by forge.example.com, which has not allowed it to reach git.example.com yet." Under it is one button: Ask the host to allow git.example.com.
- The ask. Pressing it sends the host who asked, the name, port 443 and why ("to connect an origin"). The same place then says how it stands: "Asked 2 minutes ago. The host's admin has not answered yet." A repeat is the same ask, never a second one.
- The answer. When the host allows the name, the connect that was refused runs again by itself, as the person who tried it, and the row says "The host allowed it. Connected benji at git.example.com." If the host puts the ask aside the row says so and offers Ask again.
- What is never asked for. An address (
10.1.2.3), a name that is private by its shape (localhost,db.internal,printer.local), a wildcard and any port but 443 are told why and offered no button. A name that looks public and points inside a network is refused by the host when it is asked. - For an agent.
POST /api/v1/user/origins(and/oauth) answers 422unreachablewithsays(the sentence),ask: { method, path, body }(the call that asks, ready to send) andsetting(the host's key, for the record).POST /api/v1/reach/askssends the ask;GET /api/v1/reach/asksreads how each stands and is what an agent polls.
The pasted token waits with the ask, sealed like a connected account's token: fifteen minutes if nobody asks, seven days once asked, and it is erased the moment the connect runs. The forge looks for the answer every ten seconds while an ask is under an hour old, with every heartbeat after that, and whenever the page is open.
On the host
- Home. The line that says what needs you reads "ben-test asks to reach git.example.com to connect an origin (2 minutes ago)" with Allow and Not now.
- Forges (
/forges). The ask is the first row under the forge's name, with Allow, Allow for every hosted forge and Not now. A grant reads "May also reach git.example.com" with Remove this name. - Settings, Hosted forges (
/settings/hosted-forges#reach). One sentence with a switch: "Hosted forges may reach the public git hosts (GitHub, GitLab, Codeberg, Bitbucket) and each other." Then "and also:", the names every hosted forge may reach, with a box to add one. Then "and for one forge only:", each forge's own grants and asks. The row that used to hold the switch on Settings, Usage, Capacity now points here. - In the terminal. Open the palette (ctrl-k), "What hosted forges may reach":
aallows for that forge,efor every hosted forge,nputs the ask aside,xtakes a grant back,greads again.
A grant applies at once and restarts nothing. The gate asks for the list on every connection (childGate, src/spawn/child_reach.ts), so Allow opens, and Remove or the switch closes, a forge that is running.
What stays closed
- Names only, port 443 only, no wildcard, from an ask or from an admin's own typing.
- The gate still resolves a granted name and refuses a private, loopback, link-local or metadata address (
decide,src/apps/egress.ts). - Only a person who is a site admin answers, and only from this forge's own pages: a form sent from another site is refused.
- A forge keeps at most 20 asks waiting; the oldest gives way to a new one, so nobody is ever turned away. An ask put aside is not raised again by a repeat for a day.
- Each refusal by the gate is one log line per forge and name an hour,
[egress] ben-test was refused git.example.com:443, and aforge.reach_refusedevent. Asks and answers are events with who and when:forge.reach_asked,forge.reach_allowed,forge.reach_put_aside,forge.reach_revokedon the host;reach.asked,reach.allowed,reach.connectedon the hosted forge.
Where it lives
Rows: child_reach_ask and child_reach_grant on the host, reach_ask on the hosted forge (src/core/child_reach.ts, src/core/reach_ask.ts). The ask travels as a signed call on the door a hosted forge already has to its host (POST /api/v1/reach on src/spawn/beat-door.ts, checked by src/spawn/signed_call.ts). Actions: src/actions/ask_host.ts (hosted forge), src/actions/child_reach.ts (host). Tests: test/ask-to-reach.test.ts, with the real gate.
The sentence and its one action are built by blockedBy (docs/features/blocked-by.md).