GOVERNMENT

   |                 |
  / \               / \
 /   \             /   \
(_____)           (_____)
 |   |  _   _   _  |   |
 | O |_| |_| |_| |_| O |
 |-  |             | - |
 |   |  GOVERNMENT |   |
 | - |          _  |   |
 |   |   - _^_     |   |
 |  _|    //|\\  - |   |
 |   |   ///|\\\   |  -|
 |-  |_  |||||||   |   |
 |   |   |||||||   |-  |
 |___|___|||||||___|___|
         (      (
          \      \
           )      )
           |      |
           (      (
            \      \ 

GOVERNMENT is a 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

Install

Run:

go install nmyk.io/government/cmd/government@latest
go install nmyk.io/government/cmd/govlisp@latest

Alternatively, compile from source:

git clone https://git.nmyk.io/government.git
cd government
make install

government compiles, checks, inspects, runs and repeals .gov files.

govlisp runs GovLisp source directly, with no certificates, and has an interactive REPL.

Quick start

  1. Write a program, for example square.gov.lisp:
    ; The square of a number.
    (def square (fn (n) (* n n)))
    (square 12)
  2. Compile it: government compile square.gov.lisp. That writes square.gov.
  3. Run it: government square.gov. It prints 144.
  4. Inspect the certificates with any X.509 tool, for example openssl:
    openssl crl2pkcs7 -nocrl -certfile square.gov |\
    openssl pkcs7 -print_certs -text -noout
  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 Compile a program to example.gov, or to the file -o names.
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.

A file name of - means standard input, and -o - means standard output, so commands can be piped:

government compile example.gov.lisp -o - | government run -

GovLisp reference

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.<id>.<type>, followed by a payload for the types that need one. GOV is 2.25.4673366: the value 0x474F56 ("GOV" in ASCII) under the UUID arc 2.25. Types below 128 take one byte, and the functions from 128 on take two.

Type Kind Payload Source OID
0 List None (a b) GOV.<id>.0
2 Symbol The name's code points foo GOV.<id>.2.102.111.111
3 Integer The value, zigzag encoded -42 GOV.<id>.3.83
4 Float Decimal mantissa with sign, then exponent 3.14 GOV.<id>.4.628.3
5 String The string's code points "hi" GOV.<id>.5.104.105
16-31 Constant None T GOV.<id>.16
32-63 Special form None if GOV.<id>.33
64-127 Function None + GOV.<id>.65
128- Function None $f GOV.<id>.128

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.
E-DECODE The policy graph is not a valid GovLisp tree.

verify, tree and decompile allow 1,000,000 nodes by default, so they are safe on a file you do not trust yet. Running a program has no limit unless you set one with --max-nodes.

A runtime error stops the program with exit code 1. The runtime errors are in Output and errors in the GovLisp specification.

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