|
| 1 | +// Copyright 2026 Google LLC |
| 2 | +// |
| 3 | +// Licensed under the Apache License, Version 2.0 (the "License"); |
| 4 | +// you may not use this file except in compliance with the License. |
| 5 | +// You may obtain a copy of the License at |
| 6 | +// |
| 7 | +// http://www.apache.org/licenses/LICENSE-2.0 |
| 8 | +// |
| 9 | +// Unless required by applicable law or agreed to in writing, software |
| 10 | +// distributed under the License is distributed on an "AS IS" BASIS, |
| 11 | +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 12 | +// See the License for the specific language governing permissions and |
| 13 | +// limitations under the License. |
| 14 | + |
| 15 | +package api |
| 16 | + |
| 17 | +import ( |
| 18 | + "errors" |
| 19 | + "fmt" |
| 20 | + "net/url" |
| 21 | + "strings" |
| 22 | +) |
| 23 | + |
| 24 | +// ============================================================================ |
| 25 | +// Device Enrollment URI |
| 26 | +// ============================================================================ |
| 27 | +// |
| 28 | +// A control plane hands a new device everything it needs to enroll in one |
| 29 | +// scannable string: |
| 30 | +// |
| 31 | +// sam://enroll?server=<control-plane-url>&token=<bootstrap-token> |
| 32 | +// |
| 33 | +// The token is an ordinary bootstrap token (POST /enroll spends it), so the |
| 34 | +// URI grants exactly what the token grants: one enrollment, in the token's |
| 35 | +// role, until it expires, against any control plane deployment — sam-one or |
| 36 | +// a full sam-control-plane. The server URL is the same base URL a node |
| 37 | +// passes to `sam-node join`, and the same transport rule applies |
| 38 | +// (ValidateControlPlaneTransport): https, or plaintext http only to a |
| 39 | +// loopback host, because whoever answers that URL becomes the device's trust |
| 40 | +// root. Clients (the mobile app, CLIs) parse the URI with ParseEnrollURI and |
| 41 | +// must reject anything else; there is deliberately no second form to keep |
| 42 | +// the scanner-to-enrollment path free of guesswork. |
| 43 | + |
| 44 | +const ( |
| 45 | + // EnrollURIScheme is the URI scheme of a device enrollment payload. |
| 46 | + EnrollURIScheme = "sam" |
| 47 | + // EnrollURIHost is the fixed host component; it names the action. |
| 48 | + EnrollURIHost = "enroll" |
| 49 | +) |
| 50 | + |
| 51 | +// EnrollURI builds the device enrollment URI for the given control plane |
| 52 | +// base URL and bootstrap token. |
| 53 | +func EnrollURI(server, token string) string { |
| 54 | + q := url.Values{} |
| 55 | + q.Set("server", server) |
| 56 | + q.Set("token", token) |
| 57 | + u := url.URL{Scheme: EnrollURIScheme, Host: EnrollURIHost, RawQuery: q.Encode()} |
| 58 | + return u.String() |
| 59 | +} |
| 60 | + |
| 61 | +// ParseEnrollURI extracts the control plane URL and bootstrap token from a |
| 62 | +// device enrollment URI. The server must be an absolute URL that a device |
| 63 | +// may trust as its control plane: https, or http to a loopback host. |
| 64 | +func ParseEnrollURI(raw string) (server, token string, err error) { |
| 65 | + u, err := url.Parse(strings.TrimSpace(raw)) |
| 66 | + if err != nil { |
| 67 | + return "", "", fmt.Errorf("invalid enrollment URI: %w", err) |
| 68 | + } |
| 69 | + if u.Scheme != EnrollURIScheme || u.Host != EnrollURIHost { |
| 70 | + return "", "", fmt.Errorf("invalid enrollment URI: expected %s://%s?server=<url>&token=<token>", EnrollURIScheme, EnrollURIHost) |
| 71 | + } |
| 72 | + q := u.Query() |
| 73 | + server, token = q.Get("server"), q.Get("token") |
| 74 | + if token == "" { |
| 75 | + return "", "", fmt.Errorf("invalid enrollment URI: missing token") |
| 76 | + } |
| 77 | + if su, err := url.Parse(server); err != nil || su.Host == "" { |
| 78 | + return "", "", fmt.Errorf("invalid enrollment URI: server must be an absolute http(s) URL") |
| 79 | + } |
| 80 | + if err := ValidateControlPlaneTransport(server, false); err != nil { |
| 81 | + if errors.Is(err, ErrInsecureControlPlaneURL) { |
| 82 | + // Devices have no --insecure-control-plane escape hatch. |
| 83 | + return "", "", fmt.Errorf("invalid enrollment URI: server %q must use https:// (plaintext http:// is accepted for loopback hosts only)", server) |
| 84 | + } |
| 85 | + return "", "", fmt.Errorf("invalid enrollment URI: %w", err) |
| 86 | + } |
| 87 | + return server, token, nil |
| 88 | +} |
0 commit comments