b416063bcc
* [agent-network] Shared proto, OpenAPI schema, and generated types * [agent-network] Management: store, manager, synthesizer, policy engine, provider catalog, HTTP/gRPC API Adds the account-scoped agent-network module: provider/policy/budget CRUD and store, the reverse-proxy service synthesizer, policy selection + limit enforcement, the provider catalog (incl. Vertex AI and AWS Bedrock entries), and the management HTTP + proxy gRPC surfaces. * [management] Fix agent-network proxy-peer fan-out on affected-peer recompute The affected-peers resolver loaded only persisted reverse-proxy services, but agent-network services are synthesized on demand and never persisted. As a result the embedded proxy peer was never folded into the affected set when a client's group changed, so the proxy received no network-map update for a newly authorised client and rejected its handshake until a full resync (restart). loadProxyServices now merges the synthesized agent-network services (injected via a registration hook to avoid an import cycle), so proxy peers learn newly authorised clients immediately. * [proxy] Reverse-proxy middleware framework, chain, and request plumbing The per-target middleware chain (slots, dispatcher, mutation gate, metadata merger), body capture, access-log terminal sink, and the proxy wiring that builds + runs chains for synthesized agent-network services. * [proxy] LLM parsers, pricing, and builtin middlewares (OpenAI, Anthropic, Vertex AI, AWS Bedrock) Request/response parsers and SSE/event-stream metering, the embedded pricing table, and the builtin middleware set: request parser, router, policy limit-check/record, cost meter, guardrail, identity inject, response parser. Includes the path-routed providers — Google Vertex AI (keyfile:: service-account OAuth minting) and AWS Bedrock (bearer auth, invoke/converse/streaming, optional /bedrock prefix) — plus the Models allowlist and unmeterable-publisher deny. * [proxy] IPv6 in-place apply and TCP accept-loop hardening on netstack listeners * [agent-network] End-to-end test suite, module docs, and deployment preset * [agent-network] Fix codespell typos and exclude false positives - labelgen word pool: vermillion -> vermilion, racoon -> raccoon. - codespell ignore list: add flate (Go compress/flate package), recordin (a test-local identifier), and unparseable (a valid alternative spelling used consistently across identifiers + a metadata-value constant). * [management] Set LastSeen on injected proxy peer in realstack test (MySQL strict-mode) The injected embedded proxy peer had a PeerStatus with a zero LastSeen, which serializes to '0000-00-00' and is rejected by MySQL in strict mode (SQLite tolerates it). Set LastSeen to a valid time so SaveAccount succeeds on both engines. * [agent-network] Remove e2e shell-script suite from this branch The end-to-end shell scripts under scripts/e2e/ are maintained in a separate testing suite and are not part of this change set. * [agent-network] Polish module docs: remove internal review scaffolding, fix links, verify diagrams Strip PR-review framing, commit references, absolute paths, and stale internal references from the agent-network module docs; fix broken relative links; verify all diagrams against the current architecture. Remove the internal AI-reviewer prompt file. * [management] Refine session expiration handling to support 3-state encoding for SSO deadlines * [agent-network] Relocate agentnetwork package to internals/modules Move management/server/agentnetwork (and its catalog/, labelgen/, types/ subpackages) to management/internals/modules/agentnetwork, alongside the reverse-proxy module, and rewrite all importers. Pure relocation: package names, the synthesizer + affectedpeers registration hook, and store access (shared store.Store) are unchanged, so no import cycle is introduced (affectedpeers still depends only on the agentnetwork/types leaf). * [agent-network] Co-locate HTTP handlers in the module (RegisterEndpoints) Move the agent-network HTTP handlers from server/http/handlers/agentnetwork into the module at internals/modules/agentnetwork/handlers (package handlers) and rename the entrypoint AddEndpoints -> RegisterEndpoints, matching the reverse-proxy module convention. Wiring in http/handler.go updated accordingly.
Netbird Reverse Proxy
The NetBird Reverse Proxy is a separate service that can act as a public entrypoint to certain resources within a NetBird network. At a high level, the way that it operates is:
- Configured routes are communicated from the Management server to the proxy.
- For each route the proxy creates a NetBird connection to the NetBird Peer that hosts the resource.
- When traffic hits the proxy at the address and path configured for the proxied resource, the NetBird Proxy brings up a relevant authentication method for that resource.
- On successful authentication the proxy will forward traffic onwards to the NetBird Peer.
Proxy Authentication methods supported are:
- No authentication
- Oauth2/OIDC
- Emailed Magic Link
- Simple PIN
- HTTP Basic Auth Username and Password
Management Connection and Authentication
The Proxy communicates with the Management server over a gRPC connection. Proxies act as clients to the Management server, the following RPCs are used:
- Server-side streaming for proxied service updates.
- Client-side streaming for proxy logs.
To authenticate with the Management server, the proxy server uses Machine-to-Machine OAuth2. If you are using the embedded IdP //TODO: explain how to get credentials. Otherwise, create a new machine-to-machine profile in your IdP for proxy servers and set the relevant settings in the proxy's environment or flags (see below).
User Authentication
When a request hits the Proxy, it looks up the permitted authentication methods for the Host domain. If no authentication methods are registered for the Host domain, then no authentication will be applied (for fully public resources). If any authentication methods are registered for the Host domain, then the Proxy will first serve an authentication page allowing the user to select an authentication method (from the permitted methods) and enter the required information for that authentication method. If the user is successfully authenticated, their request will be forwarded through to the Proxy to be proxied to the relevant Peer. Successful authentication does not guarantee a successful forwarding of the request as there may be failures behind the Proxy, such as with Peer connectivity or the underlying resource.
TLS
Due to the authentication provided, the Proxy uses HTTPS for its endpoint, even if the underlying service is HTTP.
Certificate generation can either be via ACME (by default, using Let's Encrypt, but alternative ACME providers can be used) or through certificate files.
When not using ACME, the proxy server attempts to load a certificate and key from the files tls.crt and tls.key in a specified certificate directory.
When using ACME, the proxy server will store generated certificates in the specified certificate directory.
Auth UI
The authentication UI is a Vite + React application located in the web/ directory. It is embedded into the Go binary at build time.
To build the UI:
cd web
npm install
npm run build
For UI development with hot reload (served at http://localhost:3031):
npm run dev
The built assets in web/dist/ are embedded via //go:embed and served by the web.ServeHTTP handler.
Configuration
NetBird Proxy deployment configuration is via flags or environment variables, with flags taking precedence over the environment. The following deployment configuration is available:
| Flag | Env | Purpose | Default |
|---|---|---|---|
-debug |
NB_PROXY_DEBUG_LOGS |
Enable debug logging | false |
-mgmt |
NB_PROXY_MANAGEMENT_ADDRESS |
The address of the management server for the proxy to get configuration from. | "https://api.netbird.io:443" |
-addr |
NB_PROXY_ADDRESS |
The address that the reverse proxy will listen on. | ":443 |
-url |
NB_PROXY_URL |
The URL that the proxy will be reached at (where endpoints will be CNAMEd to). If unset, this will fall back to the proxy address. | "proxy.netbird.io" |
-cert-dir |
NB_PROXY_CERTIFICATE_DIRECTORY |
The location that certificates are stored in. | "./certs" |
-acme-certs |
NB_PROXY_ACME_CERTIFICATES |
Whether to use ACME to generate certificates. | false |
-acme-addr |
NB_PROXY_ACME_ADDRESS |
The HTTP address the proxy will listen on to respond to HTTP-01 ACME challenges | ":80" |
-acme-dir |
NB_PROXY_ACME_DIRECTORY |
The directory URL of the ACME server to be used | "https://acme-v02.api.letsencrypt.org/directory" |
-oidc-id |
NB_PROXY_OIDC_CLIENT_ID |
The OAuth2 Client ID for OIDC User Authentication | "netbird-proxy" |
-oidc-secret |
NB_PROXY_OIDC_CLIENT_SECRET |
The OAuth2 Client Secret for OIDC User Authentication | "" |
-oidc-endpoint |
NB_PROXY_OIDC_ENDPOINT |
The OAuth2 provider endpoint for OIDC User Authentication | "https://api.netbird.io/oauth2" |
-oidc-scopes |
NB_PROXY_OIDC_SCOPES |
The OAuth2 scopes for OIDC User Authentication, comma separated | "openid,profile,email" |