government

commit f446e2800b994f797ef5d5c74b41c0ff29304839

tree

parent:
d7a5838ae78830c0ba1161fee24dacb9d87725d7

nmyk <nick@nmyk.io>

2026-11-14T15:03:55-05:00

add OID <-> govlisp symbol mapping

diff --git a/ast/builtin.go b/ast/builtin.go
new file mode 100644
index 0000000000000000000000000000000000000000..a74bd00b1e9a2c10574be15f86d8b78e02726539
--- /dev/null
+++ b/ast/builtin.go
@@ -0,0 +1,70 @@
+package ast
+
+// Names for the builtins that have no source spelling as a symbol. The
+// reader turns "()", "T" and "F" into values and handles "." itself, so none
+// of these can collide with a user symbol.
+const (
+	ListNode = "(...)"
+	Dot      = "."
+	True     = "T"
+	False    = "F"
+	Empty    = "()"
+)
+
+// builtinCodes is the table from DESIGN.md. A code is permanent once
+// published: changing one would change the meaning of every .gov file
+// already compiled, so new builtins only ever take a free code.
+var builtinCodes = []struct {
+	code uint64
+	name string
+}{
+	{1, ListNode},
+	{2, Dot},
+	{3, True},
+	{4, False},
+	{5, Empty},
+
+	{10, "quote"},
+	{11, "if"},
+	{12, "define"},
+	{13, "lambda"},
+	{14, "and"},
+	{15, "or"},
+
+	{20, "not"},
+	{21, "+"},
+	{22, "-"},
+	{23, "*"},
+	{24, "/"},
+	{25, "<"},
+	{26, ">"},
+	{27, "<="},
+	{28, ">="},
+	{29, "=="},
+	{30, "!="},
+	{31, "cons"},
+	{32, "car"},
+	{33, "cdr"},
+	{34, "strlen"},
+	{35, "strcat"},
+	{36, "str?"},
+}
+
+var (
+	codeByName = map[string]uint64{}
+	nameByCode = map[uint64]string{}
+)
+
+func init() {
+	for _, b := range builtinCodes {
+		codeByName[b.name] = b.code
+		nameByCode[b.code] = b.name
+	}
+}
+
+// IsBuiltin reports whether name is in namespace 0. A symbol with this name
+// is always encoded as the builtin, which is why programs cannot rebind one.
+func IsBuiltin(name string) bool {
+	_, ok := codeByName[name]
+	return ok
+}
diff --git a/ast/doc.go b/ast/doc.go
new file mode 100644
index 0000000000000000000000000000000000000000..355f97fde82a877865d7d881a56493ffecefcdda
--- /dev/null
+++ b/ast/doc.go
@@ -0,0 +1,4 @@
+// Package ast is the program tree that certificates carry: how each node is
+// named by an OID, how a tree is numbered, and how it is cut into one layer
+// per certificate.
+package ast
diff --git a/ast/oid.go b/ast/oid.go
new file mode 100644
index 0000000000000000000000000000000000000000..9d5c42c9a38beb932e9e94be5b79ba8d92d7477d
--- /dev/null
+++ b/ast/oid.go
@@ -0,0 +1,221 @@
+package ast
+
+import (
+	"crypto/x509"
+	"errors"
+	"fmt"
+	"strings"
+	"unicode/utf8"
+
+	"government/sexpr"
+)
+
+// Root is the arc every node OID starts with.
+const Root = "2.25.9665536045854453410170579537759926404"
+
+// Namespace is an OID's first arc after Root. It says how to read the
+// payload, so the same text can be a symbol, a number or a string.
+type Namespace uint64
+
+const (
+	NSBuiltin Namespace = iota
+	NSSymbol
+	NSInt
+	NSFloat
+	NSString
+)
+
+var nsNames = []string{"builtin", "symbol", "integer", "float", "string"}
+
+func (ns Namespace) String() string {
+	if ns < Namespace(len(nsNames)) {
+		return nsNames[ns]
+	}
+	return fmt.Sprintf("namespace %d", uint64(ns))
+}
+
+// rootBytes is Root in DER. Encoding appends arcs to it and decoding strips
+// it, working on bytes because x509.OID has no way to read its arcs back
+// and Root is too large for OIDFromInts.
+var rootBytes = func() []byte {
+	oid, err := x509.ParseOID(Root)
+	if err != nil {
+		panic(err)
+	}
+	b, err := oid.MarshalBinary()
+	if err != nil {
+		panic(err)
+	}
+	return b
+}()
+
+// EncodeOID builds the OID Root.ns.id.payload. For a builtin, text is its
+// name and the payload is its code; otherwise the payload is text's code
+// points.
+func EncodeOID(ns Namespace, id uint64, text string) (x509.OID, error) {
+	if id == 0 {
+		return x509.OID{}, errors.New("node id must be positive")
+	}
+	var payload []uint64
+	if ns == NSBuiltin {
+		code, ok := codeByName[text]
+		if !ok {
+			return x509.OID{}, fmt.Errorf("%q is not a builtin", text)
+		}
+		payload = []uint64{code}
+	} else {
+		if !utf8.ValidString(text) {
+			return x509.OID{}, fmt.Errorf("%s %q is not valid UTF-8", ns, text)
+		}
+		if err := checkPayload(ns, text); err != nil {
+			return x509.OID{}, err
+		}
+		for _, r := range text {
+			payload = append(payload, uint64(r))
+		}
+	}
+
+	b := append([]byte{}, rootBytes...)
+	b = appendArc(b, uint64(ns))
+	b = appendArc(b, id)
+	for _, arc := range payload {
+		b = appendArc(b, arc)
+	}
+	var oid x509.OID
+	if err := oid.UnmarshalBinary(b); err != nil {
+		return x509.OID{}, err
+	}
+	return oid, nil
+}
+
+// DecodeOID is EncodeOID's inverse. Its input comes from an untrusted
+// certificate, so every rule EncodeOID follows is checked again here.
+func DecodeOID(oid x509.OID) (ns Namespace, id uint64, text string, err error) {
+	b, err := oid.MarshalBinary()
+	if err != nil {
+		return 0, 0, "", err
+	}
+	// An arc's last byte is below 0x80, so a byte prefix match ends on an
+	// arc boundary.
+	rest, ok := strings.CutPrefix(string(b), string(rootBytes))
+	if !ok {
+		return 0, 0, "", fmt.Errorf("OID %s is not under %s", oid, Root)
+	}
+	arcs, err := readArcs([]byte(rest))
+	if err != nil {
+		return 0, 0, "", fmt.Errorf("OID %s: %w", oid, err)
+	}
+	if len(arcs) < 2 {
+		return 0, 0, "", fmt.Errorf("OID %s has no node id", oid)
+	}
+	ns, id, payload := Namespace(arcs[0]), arcs[1], arcs[2:]
+	if ns > NSString {
+		return 0, 0, "", fmt.Errorf("OID %s: unknown %s", oid, ns)
+	}
+	if id == 0 {
+		return 0, 0, "", fmt.Errorf("OID %s: node id must be positive", oid)
+	}
+
+	if ns == NSBuiltin {
+		if len(payload) != 1 {
+			return 0, 0, "", fmt.Errorf("OID %s: a builtin has exactly one payload arc, got %d", oid, len(payload))
+		}
+		name, ok := nameByCode[payload[0]]
+		if !ok {
+			return 0, 0, "", fmt.Errorf("OID %s: unknown builtin code %d", oid, payload[0])
+		}
+		return ns, id, name, nil
+	}
+
+	var sb strings.Builder
+	for _, arc := range payload {
+		// ValidRune rejects both surrogates and values past U+10FFFF.
+		if arc > utf8.MaxRune || !utf8.ValidRune(rune(arc)) {
+			return 0, 0, "", fmt.Errorf("OID %s: arc %d is not a Unicode code point", oid, arc)
+		}
+		sb.WriteRune(rune(arc))
+	}
+	text = sb.String()
+	if err := checkPayload(ns, text); err != nil {
+		return 0, 0, "", fmt.Errorf("OID %s: %w", oid, err)
+	}
+	return ns, id, text, nil
+}
+
+// checkPayload applies the reader's grammar, so a text decodes as a symbol
+// or number exactly when the same text in source would read as one.
+func checkPayload(ns Namespace, text string) error {
+	switch ns {
+	case NSSymbol:
+		if text == "" {
+			return errors.New("empty symbol")
+		}
+		if IsBuiltin(text) {
+			return fmt.Errorf("symbol %q is a builtin name", text)
+		}
+		if _, isNumber, _ := sexpr.ParseNumber(text); isNumber {
+			return fmt.Errorf("symbol %q reads as a number", text)
+		}
+	case NSInt:
+		v, _, err := sexpr.ParseNumber(text)
+		if err != nil {
+			return err
+		}
+		if _, ok := v.(sexpr.Int); !ok {
+			return fmt.Errorf("%q is not an integer", text)
+		}
+	case NSFloat:
+		v, _, err := sexpr.ParseNumber(text)
+		if err != nil {
+			return err
+		}
+		if _, ok := v.(sexpr.Float); !ok {
+			return fmt.Errorf("%q is not a float", text)
+		}
+	case NSString:
+	default:
+		return fmt.Errorf("unknown %s", ns)
+	}
+	return nil
+}
+
+// appendArc writes arc in base 128, high digits first, with the top bit set
+// on every byte but the last. This is how DER encodes each OID arc.
+func appendArc(b []byte, arc uint64) []byte {
+	var digits [10]byte
+	i := len(digits)
+	for {
+		i--
+		digits[i] = byte(arc & 0x7f)
+		arc >>= 7
+		if arc == 0 {
+			break
+		}
+	}
+	for j := i; j < len(digits)-1; j++ {
+		digits[j] |= 0x80
+	}
+	return append(b, digits[i:]...)
+}
+
+func readArcs(b []byte) ([]uint64, error) {
+	var arcs []uint64
+	for len(b) > 0 {
+		var arc uint64
+		for i := 0; ; i++ {
+			if i == len(b) {
+				return nil, errors.New("truncated arc")
+			}
+			if arc > (1<<64-1)>>7 {
+				return nil, errors.New("arc does not fit in 64 bits")
+			}
+			arc = arc<<7 | uint64(b[i]&0x7f)
+			if b[i]&0x80 == 0 {
+				b = b[i+1:]
+				break
+			}
+		}
+		arcs = append(arcs, arc)
+	}
+	return arcs, nil
+}
diff --git a/ast/oid_test.go b/ast/oid_test.go
new file mode 100644
index 0000000000000000000000000000000000000000..acedb1f6119fe2ea245c4d7298c26e1cb639f489
--- /dev/null
+++ b/ast/oid_test.go
@@ -0,0 +1,140 @@
+package ast
+
+import (
+	"crypto/x509"
+	"strings"
+	"testing"
+)
+
+func gov(s string) string { return strings.Replace(s, "GOV", Root, 1) }
+
+func mustParse(t *testing.T, s string) x509.OID {
+	t.Helper()
+	oid, err := x509.ParseOID(gov(s))
+	if err != nil {
+		t.Fatalf("ParseOID(%s): %v", s, err)
+	}
+	return oid
+}
+
+func TestNamespaceTable(t *testing.T) {
+	tests := []struct {
+		ns   Namespace
+		id   uint64
+		text string
+		oid  string
+	}{
+		{NSBuiltin, 7, "+", "GOV.0.7.21"},
+		{NSSymbol, 8, "foo", "GOV.1.8.102.111.111"},
+		{NSInt, 9, "-42", "GOV.2.9.45.52.50"},
+		{NSFloat, 10, "3.14", "GOV.3.10.51.46.49.52"},
+		{NSString, 11, "hi", "GOV.4.11.104.105"},
+		{NSString, 12, "", "GOV.4.12"},
+		{NSBuiltin, 13, ListNode, "GOV.0.13.1"},
+		{NSBuiltin, 14, Empty, "GOV.0.14.5"},
+		{NSSymbol, 15, "😀", "GOV.1.15.128512"},
+		{NSSymbol, 1 << 40, "x", "GOV.1.1099511627776.120"},
+	}
+	for _, tt := range tests {
+		oid, err := EncodeOID(tt.ns, tt.id, tt.text)
+		if err != nil {
+			t.Errorf("EncodeOID(%s, %d, %q): %v", tt.ns, tt.id, tt.text, err)
+			continue
+		}
+		if got, want := oid.String(), gov(tt.oid); got != want {
+			t.Errorf("EncodeOID(%s, %d, %q) = %s, want %s", tt.ns, tt.id, tt.text, got, tt.oid)
+		}
+		ns, id, text, err := DecodeOID(mustParse(t, tt.oid))
+		if err != nil {
+			t.Errorf("DecodeOID(%s): %v", tt.oid, err)
+			continue
+		}
+		if ns != tt.ns || id != tt.id || text != tt.text {
+			t.Errorf("DecodeOID(%s) = %s, %d, %q", tt.oid, ns, id, text)
+		}
+	}
+}
+
+func TestEncodeRejects(t *testing.T) {
+	tests := []struct {
+		ns   Namespace
+		id   uint64
+		text string
+		want string
+	}{
+		{NSSymbol, 0, "x", "positive"},
+		{NSBuiltin, 1, "foo", "not a builtin"},
+		{NSSymbol, 1, "", "empty symbol"},
+		{NSSymbol, 1, "+", "builtin name"},
+		{NSSymbol, 1, "T", "builtin name"},
+		{NSSymbol, 1, "12", "reads as a number"},
+		{NSSymbol, 1, "1.", "reads as a number"},
+		{NSInt, 1, "007", "malformed"},
+		{NSInt, 1, "1.5", "not an integer"},
+		{NSInt, 1, "9223372036854775808", "64 bits"},
+		{NSFloat, 1, "1.", "malformed"},
+		{NSFloat, 1, "1e5", "malformed"},
+		{NSFloat, 1, "42", "not a float"},
+		{NSFloat, 1, "1.0e999", "out of range"},
+		{NSString, 1, "\xff", "UTF-8"},
+		{5, 1, "x", "unknown namespace 5"},
+	}
+	for _, tt := range tests {
+		_, err := EncodeOID(tt.ns, tt.id, tt.text)
+		if err == nil || !strings.Contains(err.Error(), tt.want) {
+			t.Errorf("EncodeOID(%s, %d, %q) error = %v, want %q", tt.ns, tt.id, tt.text, err, tt.want)
+		}
+	}
+}
+
+func TestDecodeRejects(t *testing.T) {
+	tests := []struct {
+		oid  string
+		want string
+	}{
+		{"2.5.29.32.0", "not under"},
+		{"2.25.96655360458544534101705795377599264041.1.1.120", "not under"}, // Root's arc with a digit added
+		{"GOV", "no node id"},
+		{"GOV.1", "no node id"},
+		{"GOV.5.1.120", "unknown namespace 5"},
+		{"GOV.1.0.120", "positive"},
+		{"GOV.0.1", "exactly one payload arc, got 0"},
+		{"GOV.0.1.21.21", "exactly one payload arc, got 2"},
+		{"GOV.0.1.6", "unknown builtin code 6"},
+		{"GOV.4.1.55296", "not a Unicode code point"},   // U+D800, a surrogate
+		{"GOV.4.1.1114112", "not a Unicode code point"}, // one past U+10FFFF
+		{"GOV.1.1", "empty symbol"},
+		{"GOV.1.1.49.46", "reads as a number"}, // "1."
+		{"GOV.3.1.49.46", "malformed"},
+		{"GOV.1.18446744073709551616.120", "64 bits"},
+	}
+	for _, tt := range tests {
+		_, _, _, err := DecodeOID(mustParse(t, tt.oid))
+		if err == nil || !strings.Contains(err.Error(), tt.want) {
+			t.Errorf("DecodeOID(%s) error = %v, want %q", tt.oid, err, tt.want)
+		}
+	}
+}
+
+func TestBuiltinCodesArePinned(t *testing.T) {
+	// Published codes must never change; this list is a second copy of the
+	// DESIGN.md table so an accidental edit to builtinCodes fails here.
+	want := map[string]uint64{
+		ListNode: 1, Dot: 2, True: 3, False: 4, Empty: 5,
+		"quote": 10, "if": 11, "define": 12, "lambda": 13, "and": 14, "or": 15,
+		"not": 20, "+": 21, "-": 22, "*": 23, "/": 24, "<": 25, ">": 26,
+		"<=": 27, ">=": 28, "==": 29, "!=": 30, "cons": 31, "car": 32,
+		"cdr": 33, "strlen": 34, "strcat": 35, "str?": 36,
+	}
+	if len(builtinCodes) != len(want) {
+		t.Errorf("%d builtins, want %d", len(builtinCodes), len(want))
+	}
+	for _, b := range builtinCodes {
+		if want[b.name] != b.code {
+			t.Errorf("%s has code %d, want %d", b.name, b.code, want[b.name])
+		}
+	}
+	if len(nameByCode) != len(builtinCodes) {
+		t.Error("two builtins share a code")
+	}
+}
diff --git a/ast/reserved_test.go b/ast/reserved_test.go
new file mode 100644
index 0000000000000000000000000000000000000000..8b8db2874b0d828cd0804ea90105c251162a5f65
--- /dev/null
+++ b/ast/reserved_test.go
@@ -0,0 +1,24 @@
+package ast
+
+import (
+	"slices"
+	"testing"
+
+	"government/eval"
+)
+
+func TestBuiltinsMatchEvaluator(t *testing.T) {
+	// The structural names are values in source (or reader syntax), not
+	// symbols, so the evaluator never sees them as names.
+	structural := []string{ListNode, Dot, True, False, Empty}
+	var named []string
+	for _, b := range builtinCodes {
+		if !slices.Contains(structural, b.name) {
+			named = append(named, b.name)
+		}
+	}
+	slices.Sort(named)
+	if reserved := eval.ReservedNames(); !slices.Equal(named, reserved) {
+		t.Errorf("builtin codes name %v\nevaluator reserves %v", named, reserved)
+	}
+}
diff --git a/eval/closure.go b/eval/closure.go
index 9cf8d3722c6a0f0f05b338bf2a8e32b788a50dd2..d70b4fd54ca6c0cd11c46a8cbab8b3afd06a99e8 100644
--- a/eval/closure.go
+++ b/eval/closure.go
@@ -1,6 +1,10 @@
 package eval
 
-import "government/sexpr"
+import (
+	"sort"
+
+	"government/sexpr"
+)
 
 // Closure is a lambda's code paired with the environment it was created
 // in. Calling it extends that environment, never the caller's, which is
@@ -130,3 +134,18 @@ 		return true
 	}
 	return builtinNames[name]
 }
+
+// ReservedNames lists the names isReserved accepts. The ast package checks
+// its builtin code table against this list, so the evaluator and the OID
+// encoding cannot disagree about which names are builtins.
+func ReservedNames() []string {
+	names := make([]string, 0, len(specialForms)+len(builtins))
+	for name := range specialForms {
+		names = append(names, string(name))
+	}
+	for _, b := range builtins {
+		names = append(names, b.name)
+	}
+	sort.Strings(names)
+	return names
+}
diff --git a/sexpr/reader.go b/sexpr/reader.go
index 093c5001ea972e0f6f89ce91eca65ec601b644cf..6743ed0c2e447ed76fdb614ea2c592cdee8a939e 100644
--- a/sexpr/reader.go
+++ b/sexpr/reader.go
@@ -222,26 +222,42 @@ 	numberLike = regexp.MustCompile(`^[-+]?\.?[0-9]`)
 )
 
 func parseAtom(t Token) (Value, error) {
-	s := t.Text
-	switch {
-	case s == "T":
+	switch t.Text {
+	case "T":
 		return T, nil
-	case s == "F":
+	case "F":
 		return F, nil
+	}
+	v, ok, err := ParseNumber(t.Text)
+	if err != nil {
+		return nil, &SyntaxError{Pos: t.Pos, Msg: err.Error()}
+	}
+	if ok {
+		return v, nil
+	}
+	return Symbol(t.Text), nil
+}
+
+// ParseNumber reads s as a number literal. ok is false when s does not start
+// like a number, so it is a symbol. The OID decoder uses this too, so a
+// payload is a valid integer, float or symbol exactly when the same text is
+// in source.
+func ParseNumber(s string) (v Value, ok bool, err error) {
+	switch {
 	case intPattern.MatchString(s):
 		n, err := strconv.ParseInt(s, 10, 64)
 		if err != nil {
-			return nil, &SyntaxError{Pos: t.Pos, Msg: fmt.Sprintf("integer %s does not fit in 64 bits", s)}
+			return nil, true, fmt.Errorf("integer %s does not fit in 64 bits", s)
 		}
-		return Int(n), nil
+		return Int(n), true, nil
 	case floatPattern.MatchString(s):
 		f, err := strconv.ParseFloat(s, 64)
 		if err != nil || math.IsInf(f, 0) {
-			return nil, &SyntaxError{Pos: t.Pos, Msg: fmt.Sprintf("float %s is out of range", s)}
+			return nil, true, fmt.Errorf("float %s is out of range", s)
 		}
-		return Float(f), nil
+		return Float(f), true, nil
 	case numberLike.MatchString(s):
-		return nil, &SyntaxError{Pos: t.Pos, Msg: fmt.Sprintf("malformed number %s", s)}
+		return nil, true, fmt.Errorf("malformed number %s", s)
 	}
-	return Symbol(s), nil
+	return nil, false, nil
 }