{"id":24079997,"url":"https://github.com/lukateras/holo-router","last_synced_at":"2025-04-30T14:41:35.558Z","repository":{"id":137083410,"uuid":"254663226","full_name":"lukateras/holo-router","owner":"lukateras","description":"Holo routing infrastructure","archived":false,"fork":false,"pushed_at":"2024-12-26T03:26:36.000Z","size":288,"stargazers_count":5,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-23T19:36:03.887Z","etag":null,"topics":["cloudflare-workers","dns-resolver","holo","rust","sni","tls-proxy","zerotier"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lukateras.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-Apache-2.0.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-04-10T15:02:39.000Z","updated_at":"2024-12-26T21:41:30.000Z","dependencies_parsed_at":"2024-01-13T22:24:11.307Z","dependency_job_id":"0867ce1c-de06-44bd-b42d-bb17a4f07f2f","html_url":"https://github.com/lukateras/holo-router","commit_stats":null,"previous_names":["transumption-crypto/holo-router","lukateras/holo-router"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukateras%2Fholo-router","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukateras%2Fholo-router/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukateras%2Fholo-router/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lukateras%2Fholo-router/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lukateras","download_url":"https://codeload.github.com/lukateras/holo-router/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251722825,"owners_count":21633023,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare-workers","dns-resolver","holo","rust","sni","tls-proxy","zerotier"],"created_at":"2025-01-09T22:40:34.356Z","updated_at":"2025-04-30T14:41:35.527Z","avatar_url":"https://github.com/lukateras.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# Holo Router\n\n## Architecture\n\n![Architecture diagram](./diagram.svg)\n\n### Agent\n\nAgent sends a JSON payload of `instant` (current Unix time in milliseconds,\nused to protect against replay attacks), `holochain_public_key` in [Base36][]\nencoding, and `zerotier_address` in hexadecimal to [Registry](#registry) `POST\n/v1/update` endpoint. Payload is signed by Holochain and ZeroTier keys.\nSignatures are specified as HTTP headers in Base64 format.\n\n[Base36]: https://github.com/transumption-unstable/base36\n\nExample request:\n\n```\nHTTP POST https://router-registry.holo.host/v1/update\nX-Holochain-Signature: Rl0zgv+t2aBVHX2hrvx7OwZZnssA4n3WMp3i\nX-ZeroTier-Signature: xgTafxZtsb4DzWij4mk40ONC2QlHQ1UfB+FMC\n\n{\n  \"instant\": 1568784840568,\n  \"holochain_public_key\": \"cf05t9ugbh4wukhcws2m0ra4vginah2wnx3cd9kuselrfxncj\",\n  \"zerotier_address\": \"59727631b0\"\n}\n```\n\nEndpoint is idempotent, so that Agent can run periodically, at the very least\non each boot. This makes loss of Registry state much less of an issue, since\nAgents will naturally repopulate it (subject to how often it is set up to run).\n\n### Gateway\n\nGateway dispatches unaltered TCP traffic by TLS SNI that is resolved using\nsystem-wide DNS, which is normally set to [Registry](#registry) `GET\n/v1/dns-query` passed through [dnscrypt-proxy][].\n\nDispatch is only allowed for hostnames that end with `.holohost.net`.\n\n[dnscrypt-proxy]: https://github.com/DNSCrypt/dnscrypt-proxy\n[letsencrypt]: https://letsencrypt.org\n[wikipedia-sni]: https://en.wikipedia.org/wiki/Server_Name_Indication\n\n### Registry\n\n[DNS-over-HTTPS][wikipedia-dns-over-https] resolver and HTTP `POST /v1/update`\nserver implemented on top of [Cloudflare Workers][cloudflare-workers].\n\nEndpoints:\n\n- `POST /v1/update` adds Base36-encoded Holochain public key -\u003e internal\n  ZeroTier IPv4 address mapping to [Workers KV][cloudflare-workers-kv].\n\n  See [Agent](#agent) docs for request docs. Response doesn't have a body.\n\n- `POST /v1/dns-query` is a [DNS-over-HTTPS][wikipedia-dns-over-https] resolver.\n\n  It accepts `A` queries, looks internal IPv4 address by public key, and\n  responds with ZeroTier IPv4 address. TTL is hardcoded to 10 seconds.\n\n  Both request and response are in `application/dns-message` DNS wire format.\n  For encoder/decoder, see [dns-packet][]. Also see [RFC 8484][rfc8484].\n\n[cloudflare-workers]: https://workers.cloudflare.com\n[cloudflare-workers-kv]: https://cloudflare.com/products/workers-kv/\n[dns-packet]: https://github.com/mafintosh/dns-packet\n[rfc8484]: https://tools.ietf.org/html/rfc8484\n[wikipedia-dns-over-https]: https://en.wikipedia.org/wiki/DNS_over_HTTPS\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukateras%2Fholo-router","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flukateras%2Fholo-router","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flukateras%2Fholo-router/lists"}