nervur 0.3.0 → 0.6.0

package/LICENSE

@@ -1,4 +1,3 @@
-
                                  Apache License
                            Version 2.0, January 2004
                         http://www.apache.org/licenses/

package/NOTICE

@@ -0,0 +1,2 @@
+Nervur
+Copyright 2026 Razvan Gherghina

package/README.md

@@ -1,53 +1,338 @@
-# nervur
+# Nervur
 
-The nervur CLI — the operator's command-line face over a running carcass.
-It is a client, never the runtime: every verb speaks to the carcass's HTTP
-API, and the same verbs exist at parity on the nervur console, the
-machine-level face the carcass serves on loopback.
+The library. **A distributed system of sovereign beings**: an address is its
+own verification key, authority is a signature, and every relationship is
+one ref with declared rights — so a reference cannot be forged and no
+ambient authority exists anywhere. A ground is one sovereign process holding
+many beings — it creates them and it destroys them, and it exposes exactly
+one handler where every message for every being arrives. A being is one
+function closed over its own cells; the door asks by whose authority and
+refuses every other question. The lineage is the object-capability
+tradition — CapTP, the actor model — with one honest departure: the door
+verifies who is calling, and rights are declared per reference. Pure
+Crockford JavaScript — factory functions, closures for privacy, no `this`,
+no classes, frozen surfaces — on `node:` built-ins, plus `graphql` for the
+one thing that would be madness to hand-roll: the schema and its execution.
 
-nervur is neutral ground for inter-company work: two companies are two
-cryptographic identities meeting in one shared datastore that neither hosts
-and both can read. Humans and AI agents are first-class colleagues on it.
+## Quickstart
 
-## Install
+`npm install nervur` — what ships is this source, byte for byte, one
+dependency (`graphql`). The package is a library and carries no command;
+the `nervur` command on an operator's PATH belongs to the
+[`nervurd`](../nervurd/README.md) package, its name twin. Construction is
+synchronous; every call through a door — `pointer`, `mcp`, `gql`, and each
+function they hand back — is async. This runs today, lifted from the
+bench's own passing suites:
 
-```sh
-npm create nervur
+```js
+import { Cells, Ground, Keychain, Tools, Voice } from 'nervur';
+
+const DIARY = `({
+  name: 'acme.diary',
+  needs: { modules: [{ module: 'memory', contract: 'nervur.memory' }] },
+  memory: { pages: { type: '[String!]', class: 'data' } },
+  interface: \`
+    type Query { pages: [String!] @rights(is: [SELF, MEMBER]) }
+    type Mutation { write(line: String!): Int @rights(is: [SELF, MEMBER]) }
+  \`,
+  resolvers: {
+    Query: { pages: (_, __, { modules }) => modules.memory.read('pages') ?? [] },
+    Mutation: {
+      write: (_, { line }, { modules }) => {
+        const kept = modules.memory.read('pages') ?? [];
+        kept.push(line);
+        modules.memory.write('pages', kept);
+        return kept.length;
+      },
+    },
+  },
+})`;
+
+const secret = Buffer.from(process.env.NERVUR_SECRET, 'base64'); // 32 bytes, minted once with Tools.secret()
+const ground = Ground({ cells: Cells({ file: 'ground.json' }), keychain: Keychain(secret) });
+
+const me = Voice(); // keep it: writeFileSync of me.pack(), or it dies with the process
+const serve = ground.serve(me);
+const stranger = await serve.pointer('Ground');
+await stranger.init({ address: Tools.address(me.pk) }); // first boot only — once, ever
+
+const admin = await serve.pointer('Ground'); // a pointer is your rights at mint — re-mint after they change
+const diary = await admin.create({
+  program: DIARY,
+  refs: [{ address: Tools.address(me.pk), rights: 'MEMBER' }],
+});
+const mine = await serve.pointer(diary);
+await mine.write({ line: 'first entry' });
+console.log(await mine.pages()); // [ 'first entry' ]
 ```
 
-One command stands the whole thing: verifies Docker (binary · daemon ·
-permission, each failure a one-line fix), pulls the carcass image, lays down
-compose + volume under `~/.nervur`, and mints your first identity.
-
-## Verbs
-
-```text
-carcass family: install, up, down, reset, preflight, whoami, status,
-                identity, use, add, list, remove
-being family:   scaffold, deploy, species
-
-  install                 Docker preflight, then stand a carcass at
-                          NERVUR_HOME (default ~/.nervur)
-  whoami · status         the carcass answers with its identity and state
-  identity add <name>     mint an identity on this machine (silent, idempotent);
-                          --key <file> adopts a brought ed25519 key instead —
-                          it never replaces an existing different owner
-  identity key <name>     print the identity's private key (base64url PKCS8),
-                          the exact shape --key accepts back
-  identity list           identities on this machine · name + public id
-  identity remove <name>  destroy an identity — refused while beings or
-                          sealed lineages remain (only an empty one goes)
-  use [name]              select which identity add/list act as
-  add <kind> [--as name]  add a being under the selected identity
-  list · remove <name>    the fleet registry · retire a being
-  scaffold <name>         mint a species repo (the DNA)
-  deploy <name> <repo> <hash>   grant + pin + run a species
-  species                 list deployed species and their pins
+The rights enum here is the default (`SELF MEMBER STRANGER`); declare your
+own `enum Rights` in the interface to replace it. Reboot: construct the
+same `Ground` from the same two arguments — it wakes remembering; `init`
+refuses, because the ref survived in the cells.
+
+**The wire, when a caller is remote.** An envelope is plain JSON:
+
+```json
+{
+  "from": "G…",
+  "to": "G…",
+  "seq": 1755170000000,
+  "op": { "ask": { "source": "{ pages }", "variables": {} } },
+  "sig": "base64 over canon({from, op, seq, to})"
+}
 ```
 
-No verb ever prompts — every fork is a flag or env var with a sane default,
-and destructive turns are their own explicitly named verbs.
+The ops are `describe`, `introspect`, `ask`, `rotate`, `release`,
+`acceptInvite`. An answer is `{ body, sig }`, signed by the being asked —
+verify against `pkOf(to)`, which `Client` does for you. A refusal is no
+answer at all; how silence rides your transport (a 204, an empty body) is
+the host module's choice. The library never opens a socket: your host
+listens however it likes and hands each envelope to `receive` —
+[the bench's sky.mjs](../bench/sky.mjs) is the reference harness for
+wiring grounds together.
+
+**The runbook, honestly.** Back up two things: the cells and the keychain
+secret — together they are the whole ground. A lost secret is permanent
+loss: nothing decrypts. A stolen secret plus stolen cells is total
+compromise, and rekey does not exist yet — destroy and recreate is
+today's remedy. The bench README's honest limits carry every known gap;
+read them before production.
+
+## The two halves
+
+**The server** is `Ground(Modules)` — modules are the whole of what a ground
+is handed, and the ground is exactly what they offer. The floor is `cells`
+(storage, including the one boot cell) and `keychain` (boot power as two
+operations, seal and unseal — the enclave's own shape once a phone hosts a
+ground); `paths`, `wire`, `contracts` and `blueprints` are
+taken if given; everything else is a module for programs. It installs itself
+the first time and boots from the same two forever after, and hands back
+three things while hiding everything it is made of:
+
+- `address` — its own admin being, aliased `Ground`.
+- `receive(envelope)` — the one handler. Every message for every being on the
+  ground arrives here and routes on the envelope's `to`. An address the
+  ground does not hold is silence. A host module that listens on a port, or
+  an app shell that calls in process, hands its envelopes to this and
+  nothing else — the library never opens a socket.
+- `serve(voice)` — authority established once, and every face inherits it.
+
+A fresh ground holds no reference, so whoever reaches it first takes the
+first one: `pointer('Ground').init({ address })` writes the first MEMBER ref
+on the admin being — the same ref row as any other — exactly once, refusing
+everyone after. That window is what running-is-custody looks like from the
+outside, and it is stated rather than hidden.
+
+**`serve` is the client, and it has four faces of one door.** `pointer(at)`
+is a plain object with one function per field, generated from the schema that
+caller is allowed to see. `gql(at)` is the raw document. `mcp(at)` is the
+same schema as tools, filtered the same way, so an agent gets exactly what
+its rights allow — a projection into JSON Schema, so scalar fields travel
+whole while unions and custom scalars flatten; the rights filtering happens
+on the SDL before the projection, so what flattens is shape, never
+permission. `client` is the bare envelope underneath all three. Each
+takes an address or an alias; each signs as the identity `serve` was given
+and verifies every answer against the address it asked.
+
+Delivery is local or remote through one API — a local answer and a remote
+one carry the same shape, and the calling code does not branch. Failure
+stays observable, as it always is: a missing endpoint or a dead ground is
+silence, and silence is something local delivery never answers with.
+
+## The files
+
+- [tools.mjs](tools.mjs) — the world's arithmetic, one frozen literal, and it
+  holds nothing: `digest`, `verifies`, `seal`/`unseal`/`secret`, `canon`
+  (canonical bytes), `envelope` (the signed message, numbered), `derive` (a
+  class key from a root), `address`/`pkOf` (StrKey, so every key is a Stellar
+  account and an address is a verification key). Same input, same output, any
+  machine — which is why an attacker computes all of it exactly as well as
+  you do. Nothing here holds a key: `envelope` assembles and numbers the
+  message and asks the voice it is handed to sign. Beside the literal stands
+  `Stamp`, the one stateful thing in the file: each caller mints one and
+  numbers its own envelopes, strictly rising. `Client` and a being's port
+  keep one lane per counterparty, so concurrent calls to the same door
+  land in order on their own; only a bare-envelope caller orders its own.
+- [voice.mjs](voice.mjs) — the identity: three private keys shut in a closure
+  and never reachable from outside. `Voice()` mints one already committed to
+  its own successor, `Voice.revive` wakes a packed one, `Voice.sealTo` seals
+  to a voice's box key and `voice.open` is the only thing that opens it.
+  `succeed()` retires both hands at once — the committed key starts speaking
+  and a fresh box starts reading. The re-wrap is the handover's own
+  choreography: the retiring voice still stands when `succeed()` returns, so
+  the holder opens with the old box and seals to the new one in the same
+  act, then discards the old voice — after which it opens nothing that
+  remains. `pack()` is the one door out — the ground's custody, and
+  precisely why hosting is custody.
+- [blueprint.mjs](blueprint.mjs) — the blueprint law. A program is compiled
+  from one serialisable source with no identity, no ground and no ambient
+  power in it: forbidden names are refused where they are read as powers and
+  shadowed at evaluation, the modules and bindings it needs are declared and
+  typed, the cells it keeps are declared with their class, its rights are its
+  own and every door declares them — a root field without `@rights`, or one
+  naming a right the enum never declared, is refused at compile — and the
+  whole of it digests to one canonical hash, rights included. Reformatting
+  the schema does not move the digest; a resolver digests by its source
+  text, so reformatting the code mints a new program. The forbidden-name
+  scan is a code-only regex, not a parser — a bounded blast radius, stated
+  as such, never a jail.
+- [program.mjs](program.mjs) — a blueprint made executable: every field
+  gated by the `@rights` it declares, resolver or no resolver, and
+  introspection curtained per caller exactly as describe is. Errors never
+  leave the house.
+- [modules.mjs](modules.mjs) — what a ground offers. `Cells` is dumb storage,
+  optionally a file. `Memory` is the memory law: reads free, writes signed by
+  the compartment's current voice, one version per cell, the chain by
+  prove-and-replace. `Clock` and `Entropy` are pinnable, so a program need
+  never reach for the wall. `Paths` resolves an address to an endpoint and
+  vouches for nothing; `Wire` carries; `Dns` is the directory they share.
+- [contract.mjs](contract.mjs) — an interface with a digest and nothing else.
+  What `needs.modules` cites, what a bound module's client is generated from,
+  and what `attest` judges a stander by: more than the contract asks is fine,
+  less is not.
+- [pointer.mjs](pointer.mjs) — `Pointer` and `Mcp`, both read off an SDL, so
+  no client is ever written by hand for a program.
+- [client.mjs](client.mjs) — the bare envelope client, usable on its own.
+  Signs as its voice and verifies every reply against `pkOf(to)`.
+- [being.mjs](being.mjs) — the being. `Compartment` seals a cell by its
+  class, `Port` carries authority both ways, `Being` is the door — prove,
+  read rights, execute, sign — and `Registry` creates, takes custody of,
+  activates and destroys, reachable only through the admin being.
+- [admin.mjs](admin.mjs) — the administrative program every ground installs
+  for itself, aliased `Ground`: census, create, activate, destroy, upgrade,
+  alias, attest. Upgrade is custody moving the one cell that was always the
+  core's to move: the program is replaced in place — address, cells, refs
+  and chain surviving — refused whole when a cell the being holds would go
+  undeclared, and visible to every peer because `describe` answers the
+  program's digest.
+- [ground.mjs](ground.mjs) — the sovereign ground, its one handler and
+  `serve`.
+- [index.mjs](index.mjs) — the surface an adopter imports.
+
+## The two reference tables
+
+A being keeps one row per direction, and nothing anywhere keeps a shared
+record of the relation.
+
+- **`refs/`** — who refers to me, and with what rights. This is the inbound
+  reference table: each entry is one capability the being issued, plus the
+  highest envelope number seen from that holder — which is what makes a
+  captured envelope worthless. A holder drops its own row with `release`;
+  the door answers it like any op and the row is gone for good.
+- **`handles/`** — whom I refer to, and under which face. Outbound, and the
+  face is a keypair minted per counterparty, so no two peers can correlate
+  the same being by its keys — timing and shape stay visible to whoever
+  already sees them.
+
+## Classes, not tiers
+
+No super-user stands inside the system — no voice passes every door. The
+host running the ground is custody, not a user: root on the live process
+holds everything, and stands outside every claim made here (the bench's
+honest limits say it whole). A `class` here is a cell's sealing class,
+never a JavaScript class — the code has none. A being holds one root
+secret, and every class of
+cell seals with a key derived from it — so a leaked class key opens one
+class. Today no path hands out a class key without the root: the partition
+prices a future delegation of reading and bounds a bug, it does not defend
+against a present leak. A blueprint declares which cells it keeps and under which class, and a
+resolver may write only those, plus its own refs and handles. Its program,
+its chain and its keys are the core's to move, never its own.
+
+## What an adopter brings
+
+Their own modules, their own programs, their own keys. A program names the
+contracts it needs and runs on any ground that stands them — as a module, or
+as a being, on this ground or another. A ground missing one refuses the
+creation rather than failing later. The regress ends at one cell: the ground
+needs just enough local storage to hold its own seed and where everything
+else lives.
+
+## The floor — what is mandatory, what is yours
+
+`Ground(Modules)` reads exactly seven names from what you hand it; every
+other name passes through untouched as a module for programs.
+
+- **`cells` — mandatory.** The shelf: `peek`/`put`/`keys`/`drop`/`dump`,
+  key to value, nothing else. Ships as a Map, optionally mirrored to one
+  JSON file. Swap it for anything that keeps those five promises
+  **synchronously, to a single writing process** — SQLite through a
+  synchronous driver, localStorage in a tab — the memory law versions
+  writes, it does not lock them, so exactly one ground writes a shelf. A
+  shared or remote store is never a cells swap: it stands behind its own
+  door as a memory being (bench suite 8), whose own ground is the single
+  writer of its own shelf. What sits on it: sealed content, the
+  deliberately unsealed
+  blueprints, and the shape — names, sizes, versions, timing. Sealed
+  content is safe wherever the shelf lives; the shape and the program
+  source are readable by whoever holds it, so where it lives decides who
+  sees those.
+- **`keychain` — mandatory.** Two operations, `seal` and `unseal`, guarding
+  the one cell that boots the ground — the ground hands its boot cell to
+  the keychain and never sees a secret at all. `Keychain(secret)` builds
+  one from 32 bytes; a KMS stands behind the same two operations as an API
+  call; the Secure Enclave stands behind them natively, because sealing
+  without exporting the key is exactly what such hardware does. Choosing
+  the keychain is the host's one security decision: a root-only file
+  restarts unattended and dies with the disk image; a KMS can refuse the
+  next boot — revocation stops tomorrow, it does not evict a thief who
+  already copied (rekey is owed; the bench's honest limits carry it); the
+  Enclave keeps the power in the device, and it never leaves. A keychain
+  that cannot unseal yields no ground at all.
+- **`paths` — optional; defaults to a private in-memory map.** The
+  phonebook: `publish`/`find`, address to endpoint, and it vouches for
+  nothing — a poisoned phonebook makes a being unreachable, never
+  impersonated, because the address verifies every answer.
+- **`wire` — optional; defaults to in-process delivery.** The courier:
+  `carry(endpoint, envelope)`. The library never opens a socket — a host
+  module listens on whatever transport it likes and hands envelopes to
+  `receive`; the wire carries the outbound ones.
+- **`contracts` — optional; empty by default.** The dictionary of
+  interfaces this ground can attest. Required the moment a module is bound
+  by address, so that `memory` offers the same interface under the same
+  digest on every ground and a pretender is refused. A digest pins shape;
+  what the words mean is the contract author's prose to state.
+- **`blueprints` — optional.** `blueprints.ground()` replaces the default
+  admin blueprint, which is how a host customises what administering this
+  ground even means.
+- **`watch` — optional.** The custodian's eye: a function called at every
+  door decision with one frozen fact, `{ to, from, kind, outcome }`, and
+  the outcomes are a closed set — `no-door`, `unproven`, `replayed`,
+  `mute`, `answered`. It sees outcomes and outsides, never an op body and
+  never a cell — exactly as knowing as the host already is. The caller's
+  silence is untouched; a watch that throws changes nothing; no watch
+  costs nothing. Tracing, metrics and logs are a host package built on
+  this, never the library's.
+
+Boot, in order: on first boot the ground installs itself — mints its admin
+voice, writes the admin being, hands the packed voice to the keychain to
+seal into one cell. Every boot after: the keychain unseals, the voice
+revives, every being in custody is announced, the ground answers. The first voice to call `init` names the first
+MEMBER — once, and never again. `Clock` and `Entropy` are not floor: they
+are ordinary modules a program declares, pinnable so a program never
+reaches for the wall.
+
+## Writing a module
 
-## License
+Five rules, each load-bearing:
 
-Apache-2.0 — see [LICENSE](./LICENSE).
+1. **A frozen object of functions and nothing else** — no classes, no
+   events, no state a being could share through it. State belongs behind a
+   door: a stateful module is a being with cells of its own, bound by
+   address under rule 5.
+2. **Params carry the authority.** The module holds no account, no key, no
+   ambient context: `stripe.charge({ account, apikey, amount })`. This is
+   what makes the same module safe to hand to every being on the ground —
+   without the context it opens nothing.
+3. **It knows nobody.** A module never learns which being calls; per-being
+   authority arrives through the blueprint's declared bindings, typed, with
+   a declared owner.
+4. **Undefined is refusal** — the same silence the door speaks, never an
+   error that narrates.
+5. **A module blueprints will name needs a contract** — the interface whose
+   fields mirror its calls, digested, so the same word means the same thing
+   on every ground. The ground attests a stander against it: more than the
+   contract asks is fine, less is not. A module a being stands remotely is
+   bound as `{ at, contract }`; the floor — cells, keychain, paths, wire —
+   is host code, because it must exist before any being can speak.

package/admin.mjs

@@ -0,0 +1,60 @@
+const ADMIN = `({
+  name: 'nervur.ground',
+  needs: { modules: [{ module: 'memory', contract: 'nervur.memory' }] },
+  memory: { 'aliases/*': { type: 'String', class: 'data' } },
+  interface: \`
+    input RefInput { address: String!, nextPkHash: String, rights: String }
+    type Census { stored: Int!, active: Int! }
+    type Query {
+      census: Census                   @rights(is: [SELF, MEMBER])
+      aliasOf(name: String!): String   @rights(is: [SELF, MEMBER])
+      attest(module: String!): Boolean @rights(is: [SELF, MEMBER])
+      opened: Boolean                  @rights(is: [SELF, MEMBER, STRANGER])
+    }
+    type Mutation {
+      init(address: String!, nextPkHash: String): Boolean @rights(is: [SELF, MEMBER, STRANGER])
+      create(program: String!, refs: [RefInput!], data: String, config: String): String
+        @rights(is: [SELF, MEMBER])
+      activate(address: String!): String                   @rights(is: [SELF, MEMBER])
+      destroy(address: String!): String                    @rights(is: [SELF, MEMBER])
+      upgrade(address: String!, program: String!): Boolean  @rights(is: [SELF, MEMBER])
+      alias(name: String!, address: String!): Boolean       @rights(is: [SELF, MEMBER])
+    }
+  \`,
+  resolvers: {
+    Query: {
+      census: (_, __, { registry }) => ({
+        active: registry.active(),
+        stored: registry.stored(),
+      }),
+      aliasOf: (_, { name }, { modules }) => modules.memory.read('aliases/' + name),
+      attest: (_, { module }, { registry }) => registry.attest(module),
+      opened: (_, __, { modules }) => modules.memory.list('refs/').length > 0,
+    },
+    Mutation: {
+      init: (_, { address, nextPkHash }, { modules }) =>
+        modules.memory.list('refs/').length > 0
+          ? false
+          : modules.memory.write('refs/' + address, {
+              nextPkHash: nextPkHash ?? null,
+              rights: 'MEMBER',
+            }) !== undefined,
+      create: (_, { program, refs, data, config }, { registry }) =>
+        registry.create({
+          config: config === undefined ? undefined : JSON.parse(config),
+          data: data ? JSON.parse(data) : {},
+          program,
+          refs: refs ?? [],
+        }),
+      activate: (_, { address }, { registry }) =>
+        registry.activate(address) === undefined ? null : address,
+      destroy: (_, { address }, { registry }) => registry.destroy(address) ?? null,
+      upgrade: (_, { address, program }, { registry }) =>
+        registry.upgrade({ address, program }) !== undefined,
+      alias: (_, { name, address }, { modules }) =>
+        modules.memory.write('aliases/' + name, address) !== undefined,
+    },
+  },
+})`;
+
+export { ADMIN };