// The HTTP token server (EMBED_CONTRACT.md, "The token server"): the shape of
// a real service's sign-in endpoint. An embed app posts its installation id
// with its demo session, and gets its installation's scoped client JWT:
//
// POST /urnetwork/client-token
// Authorization: Bearer <demo session token>
// {"installation_id": "<the installation's instance-id>"}
//
// Each installation is keyed user:<service-user-id>:<installation-id>, so a
// user's installations that run at the same time each get their own client.
// Serve the internet through your own HTTPS front end, never this listener
// directly. There is no browser CORS support: the callers are native apps.
package main
import (
"bytes"
"context"
"encoding/json"
"errors"
"fmt"
"io"
"log"
"net"
"net/http"
"os"
"os/signal"
"path/filepath"
"strconv"
"strings"
"sync"
"syscall"
"time"
)
const tokenRoute = "/urnetwork/client-token"
// the largest request body
const tokenRequestByteLimit = 4 * 1024
// what the token server's provisions send
const tokenDescription = "embed installation"
const tokenDeviceSpec = "urnetwork-examples/embed-token-server"
const defaultTokenServerAddress = "127.0.0.1:8790"
const defaultMaxInstallationsPerUser = 5
// The user already has the maximum number of installations.
type installationLimitError struct {
maxInstallations int
}
// The limit.
func (self *installationLimitError) Error() string {
return fmt.Sprintf("this user already has the most installations allowed (%d)", self.maxInstallations)
}
// The token server's settings and state.
type tokenServer struct {
sessions *demoSessions
store *mapStore
issuer *issuer
api *apiClient
maxInstallations int
// one line per request: the route, the status and the latency, never
// keys, ids or tokens
logf func(format string, args ...any)
// reports once that the server predates ACL groups
aclUnsupportedReport sync.Once
// reports once that Embed isn't enabled for the network
embedNotEnabledReport sync.Once
}
// The answer of a successful request. DataCap is the client's cap object, or
// null when it could not be read.
type clientTokenAnswer struct {
ClientId string `json:"client_id"`
ByClientJwt string `json:"by_client_jwt"`
DataCap json.RawMessage `json:"data_cap"`
}
// Validates the token server's settings and returns the server and its bind
// address.
func newTokenServer(env *environment) (*tokenServer, string, error) {
shared, err := loadSettings(env.getenv)
if err != nil {
return nil, "", err
}
sessionsPath := env.getenv("URNETWORK_DEMO_SESSIONS")
if sessionsPath == "" || !filepath.IsAbs(sessionsPath) {
return nil, "", configErrorf("set URNETWORK_DEMO_SESSIONS to the absolute filename of the private demo session file")
}
if err := checkPrivateDir(filepath.Dir(sessionsPath), "URNETWORK_DEMO_SESSIONS's directory"); err != nil {
return nil, "", err
}
sessions, err := loadDemoSessions(sessionsPath)
if err != nil {
return nil, "", err
}
maxInstallations := defaultMaxInstallationsPerUser
if text := env.getenv("URNETWORK_MAX_INSTALLATIONS_PER_USER"); text != "" {
maxInstallations, err = strconv.Atoi(text)
if err != nil || maxInstallations < 1 || 1000000 < maxInstallations {
return nil, "", configErrorf("URNETWORK_MAX_INSTALLATIONS_PER_USER must be an integer from 1 to 1000000")
}
}
address := env.getenv("URNETWORK_TOKEN_SERVER_ADDRESS")
if address == "" {
address = defaultTokenServerAddress
}
api := &apiClient{transport: env.transport(shared.apiOrigin, shared.rootCredential)}
store := newMapStore(shared.mapPath)
logger := log.New(env.stderr, "", log.LstdFlags)
return &tokenServer{
sessions: sessions,
store: store,
issuer: &issuer{
api: api,
store: store,
defaults: shared.defaults,
aclGroup: shared.defaultAclGroup,
description: tokenDescription,
deviceSpec: tokenDeviceSpec,
},
api: api,
maxInstallations: maxInstallations,
logf: logger.Printf,
}, address, nil
}
// Runs the token server until SIGINT or SIGTERM.
func serve(env *environment) error {
server, address, err := newTokenServer(env)
if err != nil {
return err
}
listener, err := net.Listen("tcp", address)
if err != nil {
return fmt.Errorf("could not listen on %s: %v", address, err)
}
httpServer := &http.Server{
Handler: server,
ReadHeaderTimeout: 10 * time.Second,
ReadTimeout: 30 * time.Second,
// a request waits for the map lock and up to three api calls
WriteTimeout: 3 * time.Minute,
IdleTimeout: 60 * time.Second,
MaxHeaderBytes: 16 * 1024,
}
fmt.Fprintf(env.stdout, "token server listening on http://%s%s\n", listener.Addr(), tokenRoute)
ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
defer stop()
served := make(chan error, 1)
go func() {
served <- httpServer.Serve(listener)
}()
select {
case <-ctx.Done():
shutdownCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
defer cancel()
httpServer.Shutdown(shutdownCtx)
return nil
case err := <-served:
return err
}
}
// Answers one request and logs its route, status and latency.
func (self *tokenServer) ServeHTTP(w http.ResponseWriter, r *http.Request) {
startTime := time.Now()
status, code := self.answer(w, r)
route := r.Method + " (other path)"
if r.URL.Path == tokenRoute {
route = r.Method + " " + tokenRoute
}
result := fmt.Sprintf("%d", status)
if code != "" {
result += " " + code
}
self.logf("%s %s %s", route, result, time.Since(startTime).Round(time.Millisecond))
}
// Answers one request; returns the status and the error code, empty on
// success. Every answer carries Cache-Control: no-store.
func (self *tokenServer) answer(w http.ResponseWriter, r *http.Request) (int, string) {
w.Header().Set("Cache-Control", "no-store")
if r.URL.Path != tokenRoute {
return writeError(w, http.StatusNotFound, "not_found", "unknown path")
}
if r.Method != http.MethodPost {
w.Header().Set("Allow", http.MethodPost)
return writeError(w, http.StatusMethodNotAllowed, "method_not_allowed", "use POST")
}
userId, ok := self.authenticate(r)
if !ok {
return writeError(w, http.StatusUnauthorized, "unauthorized", "missing or unknown session")
}
installationId, ok := readInstallationId(w, r)
if !ok {
return writeError(w, http.StatusBadRequest, "invalid_request", `send {"installation_id": "<lowercase uuid>"} as a JSON body of at most 4 KiB`)
}
answer, err := self.clientToken("user:"+userId+":"+installationId, "user:"+userId+":")
if err != nil {
return writeIssueError(w, err)
}
return writeJson(w, http.StatusOK, answer), ""
}
// The service user of the request's demo session.
func (self *tokenServer) authenticate(r *http.Request) (string, bool) {
scheme, token, found := strings.Cut(r.Header.Get("Authorization"), " ")
if !found || !strings.EqualFold(scheme, "Bearer") || token == "" {
return "", false
}
return self.sessions.UserId(token)
}
// The request's installation_id: a lowercase uuid in a JSON body of at most
// 4 KiB.
func readInstallationId(w http.ResponseWriter, r *http.Request) (string, bool) {
data, err := io.ReadAll(http.MaxBytesReader(w, r.Body, tokenRequestByteLimit))
if err != nil {
return "", false
}
decoder := json.NewDecoder(bytes.NewReader(data))
var body struct {
InstallationId *string `json:"installation_id"`
}
if err := decoder.Decode(&body); err != nil || body.InstallationId == nil {
return "", false
}
// one JSON value, nothing after it
if _, err := decoder.Token(); !errors.Is(err, io.EOF) {
return "", false
}
if !uuidPattern.MatchString(*body.InstallationId) {
return "", false
}
return *body.InstallationId, true
}
// Issues key's client under the map lock, then reads its cap object with the
// root credential. The cap read never blocks the token: a failure answers
// data_cap as null.
func (self *tokenServer) clientToken(key string, userPrefix string) (*clientTokenAnswer, error) {
unlock, err := self.store.Lock()
if err != nil {
return nil, err
}
defer unlock()
clients, err := self.store.Load()
if err != nil {
return nil, err
}
issued, err := self.issuer.Issue(clients, key, func(clients *clientMap) error {
if self.maxInstallations <= clients.CountPrefix(userPrefix) {
return &installationLimitError{maxInstallations: self.maxInstallations}
}
return nil
})
if err != nil {
return nil, err
}
if issued.aclUnsupported {
// a server without ACL groups: the client stays in the default group,
// pending_acl keeps the key, and a later request applies the group
self.aclUnsupportedReport.Do(func() {
self.logf("the URnetwork API predates ACL groups: new clients stay in the default group until it adds them")
})
}
if issued.embedNotEnabled {
// Embed isn't enabled for the network: the token still answers, the
// key keeps its pending defaults, and a request after the team enables
// Embed applies them
self.embedNotEnabledReport.Do(func() {
self.logf("Embed isn't enabled for this network: new clients' default ACL group and caps stay pending until it is; see https://ur.io/services")
})
}
// a failed read, including the Embed-not-enabled refusal, answers null
dataCap, err := self.api.GetDataCap(issued.clientId)
if err != nil {
dataCap = nil
}
return &clientTokenAnswer{
ClientId: issued.clientId,
ByClientJwt: issued.clientJwt,
DataCap: dataCap,
}, nil
}
// Answers an issue failure with its status and code.
func writeIssueError(w http.ResponseWriter, err error) (int, string) {
var busy *busyError
var installationLimit *installationLimitError
var upstream *upstreamError
var refusal *apiRefusal
var caps *capsError
var acl *aclError
switch {
case errors.As(err, &busy):
return writeError(w, http.StatusServiceUnavailable, "busy", "another process holds the client map; retry")
case errors.As(err, &installationLimit):
return writeError(w, http.StatusConflict, "installation_limit", installationLimit.Error())
case isClientLimit(err):
return writeError(w, http.StatusConflict, "client_limit", "your network is at its client limit; see https://ur.io/services")
case errors.As(err, &upstream) || errors.As(err, &refusal) || errors.As(err, &caps) || errors.As(err, &acl):
return writeError(w, http.StatusBadGateway, "upstream", "the URnetwork API failed; retry later")
default:
return writeError(w, http.StatusInternalServerError, "internal", "the token server failed; check its client map with token-server usage-all")
}
}
// Answers {"error": {"code": ..., "message": ...}}.
func writeError(w http.ResponseWriter, status int, code string, message string) (int, string) {
writeJson(w, status, map[string]any{
"error": map[string]string{
"code": code,
"message": message,
},
})
return status, code
}
// Answers value as JSON with status.
func writeJson(w http.ResponseWriter, status int, value any) int {
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(status)
json.NewEncoder(w).Encode(value)
return status
}