Developer SDK

JavaScript examples

Install the SDK · View source on GitHub ↗

integration/companion/provider_state.go

go
// Installation state of the provider companion, kept in one private directory
// named by URNETWORK_PROVIDER_STATE_DIR (PROVIDER_CONTRACT.md, "Installation
// state"), as in the Go provider example (go/provider/state.go):
//
//   - client.jwt: the scoped client credential that the developer's backend
//     issued for this installation. The developer or the app writes it; the
//     companion rewrites it whenever the SDK refreshes the token.
//   - instance-id: this installation's UUID, created on first run.
//   - identity.json: the provider identity (client key seed, provide TLS
//     certificate and key, extender seed), created on first run so the
//     provider keeps one identity across restarts.
//   - logs/: the SDK's bounded log files.
//
// Every file is replaced atomically with owner-only permissions. On POSIX the
// directory and its files must not be accessible to group or others; Windows
// relies on the access control of the user's profile directory.
package main

import (
	"encoding/base64"
	"encoding/json"
	"errors"
	"fmt"
	"io/fs"
	"os"
	"path/filepath"
	"runtime"
	"strings"

	sdk "github.com/urnetwork/sdk/v2026"
)

// Printed at start in provider mode, and in every provider example's README.
// The app that integrates a provider owns the consent screen; the examples
// start without asking.
const consentDisclaimer = `Consent disclaimer: an app that integrates a URnetwork provider must collect the user's consent before it provides.
Providing shares the user's internet connection: other URnetwork users' traffic exits through the user's device and IP address.
This example starts providing without asking, because the consent screen belongs to your app.`

const clientJwtFileName = "client.jwt"
const instanceIdFileName = "instance-id"
const identityFileName = "identity.json"

// the largest state file the companion reads
const stateFileByteLimit = 64 * 1024

const providerIdentityVersion = 1

// identity.json. Byte fields are standard base64 in json. An identity belongs
// to one client: a newly provisioned client gets a new identity.
type providerIdentity struct {
	Version                  int    `json:"version"`
	ClientId                 string `json:"client_id"`
	ClientKeySeed            []byte `json:"client_key_seed"`
	ProvideTlsCertificatePem []byte `json:"provide_tls_certificate_pem"`
	ProvideTlsPrivateKeyPem  []byte `json:"provide_tls_private_key_pem"`
	ExtenderKeySeed          []byte `json:"extender_key_seed,omitempty"`
}

// The installation state loaded at start.
type providerConfig struct {
	stateDir  string
	clientJwt string
	// the client_id claim of clientJwt
	clientId   string
	instanceId string
	// nil on first run, and when the stored identity belongs to another client
	identity *providerIdentity
}

// Loads the installation state, creating instance-id on first run. Every
// error is a configuration error: restarting does not fix it.
func loadProviderConfig(stateDir string) (*providerConfig, error) {
	if err := checkStateDir(stateDir); err != nil {
		return nil, err
	}
	clientJwtBytes, err := readPrivateFile(filepath.Join(stateDir, clientJwtFileName))
	if err != nil {
		return nil, fmt.Errorf("read %s from the state directory: %w", clientJwtFileName, err)
	}
	clientJwt := strings.TrimSpace(string(clientJwtBytes))
	clientId, err := parseClientJwtClientId(clientJwt)
	if err != nil {
		return nil, err
	}
	instanceId, err := loadOrCreateInstanceId(stateDir)
	if err != nil {
		return nil, err
	}
	identity, err := loadProviderIdentity(stateDir, clientId)
	if err != nil {
		return nil, err
	}
	return &providerConfig{
		stateDir:   stateDir,
		clientJwt:  clientJwt,
		clientId:   clientId,
		instanceId: instanceId,
		identity:   identity,
	}, nil
}

// The state directory must be an existing absolute directory, private to its
// owner on POSIX.
func checkStateDir(stateDir string) error {
	return checkStateDirFor(stateDir, "URNETWORK_PROVIDER_STATE_DIR")
}

// checkStateDir for the setting named variable, which the errors name: the
// provider mode's URNETWORK_PROVIDER_STATE_DIR or the embed mode's
// URNETWORK_EMBED_STATE_DIR.
func checkStateDirFor(stateDir string, variable string) error {
	if stateDir == "" {
		return fmt.Errorf("set %s to this installation's private state directory", variable)
	}
	if !filepath.IsAbs(stateDir) {
		return fmt.Errorf("%s must be an absolute path", variable)
	}
	info, err := os.Stat(stateDir)
	if err != nil {
		return fmt.Errorf("state directory: %w", err)
	}
	if !info.IsDir() {
		return fmt.Errorf("%s is not a directory", variable)
	}
	if runtime.GOOS != "windows" && info.Mode().Perm()&0o077 != 0 {
		return errors.New("the state directory must be private to its owner (chmod 700)")
	}
	return nil
}

// Reads a regular, private state file of bounded size. A symlink is refused
// so that the credential cannot be redirected to another file.
func readPrivateFile(path string) ([]byte, error) {
	info, err := os.Lstat(path)
	if err != nil {
		return nil, err
	}
	if !info.Mode().IsRegular() {
		return nil, errors.New("not a regular file")
	}
	if stateFileByteLimit < info.Size() {
		return nil, errors.New("file is too large")
	}
	if runtime.GOOS != "windows" && info.Mode().Perm()&0o077 != 0 {
		return nil, errors.New("file must be private to its owner (chmod 600)")
	}
	return os.ReadFile(path)
}

// Replaces a state file atomically: a private temporary file in the same
// directory is written, synced and renamed over the old file.
func writePrivateFile(path string, data []byte) (returnErr error) {
	file, err := os.CreateTemp(filepath.Dir(path), "."+filepath.Base(path)+".*")
	if err != nil {
		return err
	}
	tempPath := file.Name()
	defer func() {
		if returnErr != nil {
			os.Remove(tempPath)
		}
	}()
	if err := file.Chmod(0o600); err != nil {
		file.Close()
		return err
	}
	if _, err := file.Write(data); err != nil {
		file.Close()
		return err
	}
	if err := file.Sync(); err != nil {
		file.Close()
		return err
	}
	if err := file.Close(); err != nil {
		return err
	}
	return os.Rename(tempPath, path)
}

// The client_id claim of a scoped client JWT. This checks the token's shape
// and claim only; the SDK and the server verify the token itself.
func parseClientJwtClientId(clientJwt string) (string, error) {
	notJwt := errors.New("client.jwt does not hold a JWT; write the scoped client JWT from your backend")
	parts := strings.Split(clientJwt, ".")
	if len(parts) != 3 || parts[0] == "" || parts[1] == "" || parts[2] == "" {
		return "", notJwt
	}
	payload, err := base64.RawURLEncoding.DecodeString(strings.TrimRight(parts[1], "="))
	if err != nil {
		return "", notJwt
	}
	var claims struct {
		ClientId string `json:"client_id"`
	}
	if err := json.Unmarshal(payload, &claims); err != nil || claims.ClientId == "" {
		return "", errors.New("client.jwt has no client_id claim; write a scoped client JWT, not a network JWT")
	}
	clientId, err := sdk.ParseId(claims.ClientId)
	if err != nil {
		return "", errors.New("client.jwt has an invalid client_id claim")
	}
	return clientId.String(), nil
}

// Reads instance-id, creating it on first run. An installation keeps one
// instance id for its lifetime.
func loadOrCreateInstanceId(stateDir string) (string, error) {
	path := filepath.Join(stateDir, instanceIdFileName)
	data, err := readPrivateFile(path)
	if err == nil {
		instanceId, err := sdk.ParseId(strings.TrimSpace(string(data)))
		if err != nil {
			return "", fmt.Errorf("%s does not hold a UUID", instanceIdFileName)
		}
		return instanceId.String(), nil
	}
	if !errors.Is(err, fs.ErrNotExist) {
		return "", fmt.Errorf("read %s from the state directory: %w", instanceIdFileName, err)
	}
	instanceId := sdk.NewId().String()
	if err := writePrivateFile(path, []byte(instanceId+"\n")); err != nil {
		return "", fmt.Errorf("write %s: %w", instanceIdFileName, err)
	}
	return instanceId, nil
}

// Reads identity.json for clientId. A missing file, or an identity of another
// client, returns nil: the device then creates a new identity, which the
// companion saves.
func loadProviderIdentity(stateDir string, clientId string) (*providerIdentity, error) {
	data, err := readPrivateFile(filepath.Join(stateDir, identityFileName))
	if errors.Is(err, fs.ErrNotExist) {
		return nil, nil
	}
	if err != nil {
		return nil, fmt.Errorf("read %s from the state directory: %w", identityFileName, err)
	}
	identity := &providerIdentity{}
	if err := json.Unmarshal(data, identity); err != nil || identity.Version != providerIdentityVersion || len(identity.ClientKeySeed) != 32 {
		return nil, fmt.Errorf("%s is not a valid provider identity; remove it to create a new one", identityFileName)
	}
	if identity.ClientId != clientId {
		return nil, nil
	}
	return identity, nil
}

// Writes identity.json.
func saveProviderIdentity(stateDir string, identity *providerIdentity) error {
	data, err := json.Marshal(identity)
	if err != nil {
		return err
	}
	return writePrivateFile(filepath.Join(stateDir, identityFileName), data)
}

// The identity of a running device, for identity.json.
func newProviderIdentity(clientId string, keyMaterial *sdk.DeviceLocalKeyMaterial) *providerIdentity {
	return &providerIdentity{
		Version:                  providerIdentityVersion,
		ClientId:                 clientId,
		ClientKeySeed:            keyMaterial.GetClientKeySeed(),
		ProvideTlsCertificatePem: keyMaterial.GetProvideTlsCertificatePem(),
		ProvideTlsPrivateKeyPem:  keyMaterial.GetProvideTlsPrivateKeyPem(),
		ExtenderKeySeed:          keyMaterial.GetExtenderKeySeed(),
	}
}

// The key material that recreates the device's identity. nil without an
// identity (the first run, or another client's identity): the device then
// makes a new identity, which the companion saves.
func (self *providerIdentity) keyMaterial() *sdk.DeviceLocalKeyMaterial {
	if self == nil {
		return nil
	}
	keyMaterial := sdk.NewDeviceLocalKeyMaterial(
		self.ClientKeySeed,
		self.ProvideTlsCertificatePem,
		self.ProvideTlsPrivateKeyPem,
	)
	keyMaterial.SetExtenderKeySeed(self.ExtenderKeySeed)
	return keyMaterial
}