| |
/ \ / \
/ \ / \
(_____) (_____)
| | _ _ _ | |
| O |_| |_| |_| |_| O |
|- | | - |
| | GOVERNMENT | |
| - | _ | |
| | - _^_ | |
| _| //|\\ - | |
| | ///|\\\ | -|
|- |_ ||||||| | |
| | ||||||| |- |
|___|___|||||||___|___|
( (
\ \
) )
| |
( (
\ \
GOVERNMENT is a small Lisp whose programs are written as X.509 certificate chains.
The interpreter validates the chain as an X.509 certification path, then reads its certificate policies as the program and evaluates them. If the chain does not validate, the program does not run.
Each expression in a program is one certificate policy OID. Each pair of parentheses is a set of policy mappings. The program's nesting depth is the length of the chain.
| Term | Meaning |
|---|---|
| GovLisp | The Lisp source language. Source files use the extension .gov.lisp. |
| Compile | Turn GovLisp source into a .gov file. |
| Ratify | Validate a .gov file as a certification path. |
| Trust anchor | The one self-signed certificate at the top of the chain. |
| Depth | A certificate's position below the trust anchor. The anchor is depth 0. |
| Node | One expression of the program, stored as one policy OID. |
| Repeal | Revoke a program with a certificate revocation list (CRL). |
You need Go 1.25 or later.
go install nmyk.io/government/cmd/government@latest go install nmyk.io/government/cmd/govlisp@latest
Alternatively, compile from source:
; The square of a number. (define sq (lambda (n) (* n n))) (sq 12)
| Command | Does |
|---|---|
| government example.gov | Ratify, decode and run the program. government run example.gov is the long form. |
| government verify example.gov | Ratify and decode the program without running it, and print its certificate of ratification. |
| government tree example.gov | Print the policy tree, with notes. |
| government decompile example.gov | Print the GovLisp source, with notes as comments. |
| government compile example.gov.lisp -o example.gov | Compile a program. |
| government repeal example.gov -o repeal.crl | Write a CRL that repeals a program. |
| govlisp | Start the REPL. |
| govlisp example.gov.lisp | Run GovLisp source, with no certificates. |
On a terminal, the govlisp REPL has line editing and history, saved in ~/.govlisp_history.
GovLisp is a strict Lisp with lexical scope. All values are immutable. There is no I/O, no mutation and no macro system.
| Type | Example | Notes |
|---|---|---|
| Integer | -42 | 64 bits. Overflow is an error. |
| Float | 3.25 | 64 bits. A NaN or infinite result is an error. Floats always print with a dot. |
| String | "hi\n" | Escapes: \" \\ \n \t \u{1F3DB}. |
| Boolean | T, F | |
| Symbol | foo | |
| Pair | (1 2 3), (1 . 2) | A list is a chain of pairs ending in (). |
| Empty list | () | |
| Function | #<lambda sq>, #<builtin +> | Builtins are ordinary values, so (define add +) works. |
Only F is false. Everything else is true, including 0, "" and ().
| Form | Result |
|---|---|
| (quote d), 'd | d itself, unevaluated. |
| (if c a b) | a if c is not F, otherwise b. With no b, the result is (). |
| (define name expr) | Binds name and returns the symbol name. |
| (lambda (p1 ... pk) body...) | A closure with a fixed number of parameters. |
| (and x...) | Stops at the first F; otherwise returns the last value. (and) is T. |
| (or x...) | Returns the first value that is not F; otherwise F. (or) is F. |
| Group | Functions |
|---|---|
| Arithmetic | + - * /. Integers stay integers; any float makes the result a float. Integer / truncates toward zero. |
| Comparison | < > <= >=, each on two numbers. |
| Equality | == !=, each on any two values. (== 1 1.0) is T. |
| Logic | not |
| Lists | cons car cdr |
| Strings | strlen strcat str? |
Running a program evaluates its top-level forms in order and prints the value of each one that is not a define, one per line.
A .gov file contains a series of PEM CERTIFICATE blocks: a trust anchor, then one certificate for each depth of the program. The compiler writes the anchor first, but the interpreter accepts the certificates in any order, because each signature links a certificate to its parent.
Every node OID has the form GOV.<namespace>.<id>.<payload>, where GOV is 2.25.9665536045854453410170579537759926404, a UUID arc.
| Namespace | Kind | Payload | Source | OID |
|---|---|---|---|---|
| 0 | Builtin | One fixed code | + | GOV.0.<id>.21 |
| 1 | Symbol | The name's code points | foo | GOV.1.<id>.102.111.111 |
| 2 | Integer | The decimal text's code points | -42 | GOV.2.<id>.45.52.50 |
| 3 | Float | The decimal text's code points | 3.14 | GOV.3.<id>.51.46.49.52 |
| 4 | String | The string's code points | "hi" | GOV.4.<id>.104.105 |
IDs are unique within a program. A certificate's policies are an unordered set, so the IDs are what determine argument order.
The interpreter runs these checks before anything else. If one fails, the program does not run and the exit code is 2.
| Error | Cause |
|---|---|
| E-MALFORMED | The file is not valid PEM, or holds a block that is not a certificate. |
| E-CHAIN | The certificates do not form one clean chain, or one has a forbidden extension. |
| E-TAMPERED | A signature does not verify. |
| E-FOREIGN | The anchor's key does not match --anchor, or a CRL comes from another program. |
| E-NOT-IN-FORCE | The check time is before the program takes effect. |
| E-LAPSED | The check time is after the program expires. |
| E-REPEALED | A CRL revokes one of the program's certificates. |
| E-STALE-REPEALS | A CRL is past its next update time. |
| E-POLICY | The policies do not form a valid program, for example because a node is missing. |
| E-TOO-LARGE | The policy graph needs more nodes than --max-nodes allows (1,000,000 by default). |
| E-DECODE | The policy graph is not a valid GovLisp tree. |
A runtime error stops the program with exit code 1. The message gives the OID and depth of the expression that failed, plus the nearest note if there is one.
| Runtime error | Cause |
|---|---|
| E-UNBOUND | A symbol is not bound in the current scope. |
| E-SYNTAX | A special form is malformed. |
| E-SPECIAL-FORM | A special form's name is used as a value. |
| E-NOT-A-FUNCTION | The head of a call is not a function. |
| E-ARITY | A call has the wrong number of arguments. |
| E-TYPE | An argument has the wrong type. |
| E-ARITH | Overflow, division by zero, or a float result that is not a number. |
| E-IMMUTABLE | A name is defined twice in the same scope. |
These features never change what a program computes. They decide when it may run, and record who made it.
--not-before and --not-after set when a program is in force. Each takes an RFC 3339 time or a date, which means midnight UTC at the start of that day.
government compile law.gov.lisp -o law.gov \
--not-before 2027-01-01 --not-after 2027-12-31
government law.gov --at 2027-06-01
--at sets the time to check against. It defaults to now.
openssl genpkey -algorithm ed25519 -out ada.pem
government compile law.gov.lisp -o law.gov \
--key ada.pem --author "Ada Lovelace <ada@example.org>"
government verify law.gov
government law.gov --anchor ada.gov
Warning: without --key, the compiler uses a public default key, so anyone can amend or repeal the program. government verify names the ratifier as Public (Default Key).
government repeal law.gov --key ada.pem --reason superseded -o repeal.crl
government law.gov --crl repeal.crlThe program is refused with E-REPEALED.
repeal also takes:
Comments in the source become notes in the certificates. government tree shows them, and government decompile turns them back into comments.