GOVERNMENT

   |                 |
  / \               / \
 /   \             /   \
(_____)           (_____)
 |   |  _   _   _  |   |
 | 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.

browse the source code

Terms

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).

Install

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:

  1. Clone the repository.
  2. In its root directory, run make bin to build the commands into ./bin, or make install to install them.

Quick start

  1. Write a program, for example square.gov.lisp:
    ; The square of a number.
    (define sq (lambda (n) (* n n)))
    (sq 12)
    
  2. Compile it: government compile square.gov.lisp -o square.gov
  3. Run it: government square.gov. It prints 144.
  4. Inspect the certificates with any X.509 tool, for example openssl x509.
  5. Show the program as a policy tree: government tree square.gov
  6. Get the source back: government decompile square.gov

Commands

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.

The REPL

On a terminal, the govlisp REPL has line editing and history, saved in ~/.govlisp_history.

The language

GovLisp is a strict Lisp with lexical scope. All values are immutable. There is no I/O, no mutation and no macro system.

Values

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 ().

Special forms

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.

Builtin functions

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?

Definitions and scope

Output

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.

The .gov file

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.

OIDs

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.

Ratification

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.

Civic features

These features never change what a program computes. They decide when it may run, and record who made it.

Dates

--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.

Authorship

  1. Make an Ed25519 key:
    openssl genpkey -algorithm ed25519 -out ada.pem
  2. Compile with the key and your name:
    government compile law.gov.lisp -o law.gov \
        --key ada.pem --author "Ada Lovelace <ada@example.org>"
    
  3. Print the certificate of ratification:
    government verify law.gov
  4. To run only programs by this author, pass --anchor with one of their programs, a certificate, or their public key:
    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).

Repeal

  1. Write a CRL that repeals the program, signed with the key that compiled it:
    government repeal law.gov --key ada.pem --reason superseded -o repeal.crl
  2. Pass the CRL to the interpreter:
    government law.gov --crl repeal.crl
    The program is refused with E-REPEALED.

repeal also takes:

Notes

Comments in the source become notes in the certificates. government tree shows them, and government decompile turns them back into comments.

Limits

References