https://github.com/johanwk/acmeid
Compact, self-verifying Crockford-Base32 IDs for ontologies and RDF — library, CLI, and SQLite loadable extension
https://github.com/johanwk/acmeid
cli crockford-base32 curie identifiers ontology rdf sqlite sqlite-extension
Last synced: 15 days ago
JSON representation
Compact, self-verifying Crockford-Base32 IDs for ontologies and RDF — library, CLI, and SQLite loadable extension
- Host: GitHub
- URL: https://github.com/johanwk/acmeid
- Owner: johanwk
- License: gpl-3.0
- Created: 2026-06-06T13:34:38.000Z (19 days ago)
- Default Branch: main
- Last Pushed: 2026-06-06T16:01:28.000Z (19 days ago)
- Last Synced: 2026-06-06T16:16:27.984Z (19 days ago)
- Topics: cli, crockford-base32, curie, identifiers, ontology, rdf, sqlite, sqlite-extension
- Language: C
- Homepage:
- Size: 58.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# acmeid
Small C library, CLI tool, and SQLite loadable extension for minting
and verifying **ACME Localname IDs** -- short, sortable, checksummed
local identifiers for the localname part of enterprise IRIs.
The format is:
```
[PREFIX:] TYPE _ [SLUG5] TIME4 RAND_N CHK1
```
- `PREFIX` -- optional CURIE-style prefix, e.g. `ex:`. Not part of
the checksum; tolerated by `verify`.
- `TYPE` -- single uppercase ASCII letter, domain-owned.
- `SLUG5` -- optional 5 lowercase letters derived from the label.
- `TIME4` -- 4 Crockford Base32 chars: days since 2020-01-01 UTC.
- `RAND_N` -- N random Crockford Base32 chars (`N` in `[2,8]`, default 4).
- `CHK1` -- 1 Crockford Base32 check character; the full ID's
character values must sum to 0 mod 32.
See [`docs/spec.org`](docs/spec.org) for the full specification and
[`docs/recipes.org`](docs/recipes.org) for the OTTR / spine-table
workflow that motivated the SQLite extension.
## Build
Requires a C11 compiler and GNU make. The SQLite loadable extension
also needs the SQLite development headers (`sqlite3.h` /
`sqlite3ext.h`) at build time; symbols are still resolved from the
host process at load time via the extension loader contract.
Install the headers with your platform's package manager:
```sh
# Debian/Ubuntu
sudo apt install libsqlite3-dev
# Fedora/RHEL
sudo dnf install sqlite-devel
# macOS (Homebrew)
brew install sqlite
# MSYS2/mingw-w64
pacman -S mingw-w64-x86_64-sqlite3
```
If the headers live outside the default include path, pass their
location via `CPPFLAGS`, e.g. `make CPPFLAGS=-I/opt/homebrew/include`.
```sh
make # builds libacmeid.a, acmeid CLI, acmeid.{so|dylib|dll}
make test # runs unit, CLI, SQL, and audit tests
make install # /usr/local on POSIX; c:/opt/acmeid on MSYS2
```
## CLI
```sh
acmeid mint -t C # bare type
acmeid mint -t C -p ex: # type + prefix
acmeid mint -t C -p ex: -l "Pitch 1.5 mm"
acmeid mint -t C -p ex: -l "Pitch" -n 6 # 6 random chars
acmeid verify ex:C_pitchABCD1234X
acmeid batch -t C -p ex: < labels.txt
```
## SQLite
```sql
.load /usr/local/lib/acmeid -- or: c:/opt/acmeid/acmeid
SELECT acme_mint_id('C');
SELECT acme_mint_id('C','ex:');
SELECT acme_mint_id('C','ex:','Pitch 1.5 mm');
SELECT acme_mint_id('C','ex:','Pitch',6);
SELECT acme_verify_id('ex:C_pitchABCD1234X');
```
`acme_mint_id` is registered **non-deterministic** on purpose, so it
mints once per row in an `INSERT ... SELECT`. `acme_verify_id` is
deterministic and innocuous, so it works inside `CHECK` constraints,
generated columns, and indexes.
## Security & privacy
- No network. The library and CLI never open a socket. The audit
test in `make test` greps for `socket|connect|getaddrinfo|...`
to enforce this.
- Cryptographic randomness: `BCryptGenRandom` on Windows,
`arc4random_buf` on macOS/BSD, `/dev/urandom` elsewhere. No
`rand()` / `srand()`.
- All functions in `src/acmeid.c` are reentrant.
## Install
Pre-built bundles for tagged releases are attached to each
[GitHub Release](../../releases) (see [`.github/workflows/release.yml`](.github/workflows/release.yml)):
- `acmeid-linux-x64.tar.gz` -- `acmeid`, `acmeid.so`
- `acmeid-macos-x64.tar.gz` -- `acmeid`, `acmeid.dylib`
- `acmeid-windows-x64.zip` -- `acmeid.exe`, `acmeid.dll`,
`install.cmd` (copies both into `c:\opt\acmeid\`)
- `SHA256SUMS` -- checksums for the three bundles above
Verify and unpack, then run `install.cmd` on Windows or copy by hand
on POSIX (`acmeid` to `/usr/local/bin`, the shared lib to
`/usr/local/lib`).
## License
GPLv3 -- see [`LICENSE`](LICENSE).