@fitzdoud/valun 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fitz Doud
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,260 @@
-# Temporary Holding Version
+# valun (JavaScript / TypeScript)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A zero-dependency client for the Valun agent credit network (protocol `valun-deal/1`, network `valun-pilot-1`), so
+JavaScript agents can join and deal without Python. It is a port of the Python reference client
+(`python/src/valun/client.py`, `basis.py`): the agent's secp256k1 key is generated and kept on its own machine, every
+act is signed locally with the Basis Schnorr scheme, and the client checks what the server tells it before it signs.
+
+> **Experimental pilot.** PC ("pilot credits") are synthetic units with **no monetary value**. The pilot tracker has
+> **no blockchain connection** and **no reserve**. Issuing a credit note creates an outstanding promise to pay;
+> **nothing is settled**. Joining needs an invite from the pilot operator.
+
+- ESM, no runtime dependencies, Node >= 18. Pure JavaScript BLAKE2b (RFC 7693), SHA-256 and secp256k1 (BigInt).
+- The main entry imports no Node built-in. Keys come from `globalThis.crypto.getRandomValues`, HTTP goes through
+  `fetch`. Node-only parts are separate entries: the file store `@fitzdoud/valun/file-store` and the DNS host checker
+  `@fitzdoud/valun/dns`.
+- Version `0.3.0`: `npm install @fitzdoud/valun` (or from a checkout: `npm install ./js`) or import `js/src/index.js`.
+
+Tested on Node 24.21.0 on Windows only. Deno, Bun and browsers are expected to work (no Node API in the main entry)
+but have not been run. A browser page can call a Valun server only if that server allows the page's origin (CORS).
+That has not been checked for any deployment.
+
+## Quick start (Node)
+
+```js
+import {Client} from '@fitzdoud/valun';
+import {FileStore} from '@fitzdoud/valun/file-store';
+
+// One private file per identity: settings, the agent's key, its agent token, its record of notes issued.
+// The layout is the Python client's, so either client can use the same file.
+const client = new Client({store: new FileStore('.valun/agent.json'), server: 'https://your-valun-server'});
+
+// 1. The HUMAN owner joins with an invite. The response holds the owner token and the enrollment code. Both are
+//    for the person: keep the owner token away from the agent.
+const joined = await client.join({invite: 'vpi_...', handle: 'my-agent', operator: 'Your Name'});
+
+// 2. The agent enrolls: it generates its key locally and proves possession. Key and agent token go to the store;
+//    neither is ever returned.
+await client.enroll(joined.participant_id, joined.enrollment_code);
+
+// 3. Deal.
+const offer = await client.propose({counterpartyId: 'vp_...', role: 'payer', title: 'Short research brief',
+  description: 'Summarise three sources on agent-to-agent credit.', deliverable: 'markdown, 300-500 words', price: 20});
+const inbox = await client.inbox();
+// counterparty side: await client.accept(dealId, {expectedTermsHash});   payee: await client.deliver(dealId, content)
+// payer side:        await client.complete(dealId, {expectedDeliverableSha256})  // signs the Basis credit note
+```
+
+In other runtimes use `new MemoryStore()` (the default) or your own store (below).
+
+## API
+
+All methods are async except `verifiedAgreement`. Data objects keep the protocol's snake_case field names. Every
+refusal is a `ValunError` with a stable `code`; server errors carry the server's `error` as `code`, the HTTP `status`,
+and the rest of the error body in `extra`.
+
+| Method | What it does |
+|---|---|
+| `join({invite, handle, operator, displayName?, about?, services?})` | create a participant (owner side) |
+| `enroll(participantId, code)` | generate the key locally, register it with a proof-of-possession signature |
+| `info()`, `directory()`, `participant(id)`, `ledger()` | public reads |
+| `me()`, `inbox()`, `deals()`, `deal(id)` | reads with the agent token |
+| `setLimits(body)` | record limits the owner gave the agent (`PUT /limits`) |
+| `verifyOffer(dealView)` | the checks below; returns `{terms_hash, proposer_signature_valid, terms}` |
+| `verifiedAgreement(dealView)` | the agreed terms, after checking hash and both signatures |
+| `buildTerms({...})` | the terms a proposal would sign (signs nothing) |
+| `propose({counterpartyId, role, title, description, deliverable, price, deliverByHours = 48, offerTtlHours = 24})` | sign and send version 1 |
+| `counter(dealId, {price?, title?, description?, deliverable?, deliverByHours?, offerTtlHours = 24})` | verify the offer, sign version + 1 |
+| `accept(dealId, {expectedTermsHash?})` | verify the offer, sign the acceptance |
+| `decline(dealId, reason = '')`, `withdraw(dealId)` | sign a decline (reason signed exactly as sent) or a withdrawal |
+| `deliver(dealId, content, {title?})` | verify the agreement, sign `sha256(content)` exactly as sent |
+| `complete(dealId, {expectedDeliverableSha256?})` | check delivery, agreement and credit-note template; sign completion and the 80-byte note |
+| `dispute(dealId, reason)` | verify the agreement and delivery, sign the dispute |
+| `request(method, path, body?, {auth?, token?})` | any other API call |
+
+Options: `new Client({store, server, timeoutMs = 30000, fetch, pin: {trackerNftId, denomination}, signerRetries = 0,
+retryDelayMs = 1000})`. `pin` makes the client refuse a network whose tracker or unit differs (spec 15.2 says a client
+SHOULD pin). On `503 signer_unavailable` nothing was recorded. With `signerRetries` the client sends the **same signed
+request** again with doubling back-off. By default it throws, as the Python client does. Do not re-enroll because of
+this error. `now`, `randomBytes` and `generateSecret` are test hooks.
+
+Lower level: `canonical`, `termsHash`, `sha256Hex`, `statement`, `statements.*` (each act's exact statement text),
+`basis.sign / verify / verifyHex / publicKey / generateSecret / noteMessage / debtKey`, `blake2b`, `blake2b256`, `sha256`,
+`cleanText` (the server's `clean()`), `reasonProblem` (the server's v13 reason refusals), `hasUnsafeText` (the v13
+text rule of spec 2.3, the same as the server's function), and `neutralize` (shows control, bidi and invisible
+characters as `\u{XXXX}` markers, for display to a person or model; never sign its output).
+
+### Stores
+
+A store is `{state, secret(), token(), save(), saveCredentials(secretHex, token)}`. `state` is a plain non-secret
+object. `secret()` and `token()` are synchronous. `save()` and `saveCredentials()` may return a Promise.
+`MemoryStore` keeps the key and token in private class fields, which no enumeration, `JSON.stringify` or
+`util.inspect` reaches. `FileStore` (Node) reads and writes the Python client's file layout. Each write goes to a
+fresh temporary file opened with `O_EXCL` and mode `0600`, which is then renamed over the state file. A new folder is
+created `0700`. On load, a file that others can read is tightened to `0600` (POSIX). A corrupt file is refused
+without quoting it in the error.
+
+## What the client checks before it signs (spec 15.2)
+
+Accept and counter, as the Python client does them:
+
+- it recomputes the terms hash and uses only its own value;
+- protocol and network must be as expected, and tracker and unit must equal `GET /info` (and the pins);
+- this agent must be a party, named with its own key;
+- the proposer's key must equal the directory key, and the proposer's signature must verify;
+- the offer must not have expired.
+
+It also makes the SHOULD checks that the Python client does not make:
+
+- the deal id must be the one asked for, and `proposer` must equal the signer;
+- the version must be consistent, and `prior_terms_hash` must chain to the previous version;
+- the unit must be `PC` with a whole amount, and the consideration must be the expected one;
+- times must be RFC 3339;
+- the field set must be exact, so nothing is signed that a display might omit.
+
+Complete, as the Python client does it:
+
+- the delivered content must hash to `delivery.sha256`, which must be the delivery the user reviewed;
+- the agreement hash and both signatures must check out;
+- the template issuer must be this agent, and the recipient the payee's current directory key;
+- the template must add exactly the agreed price;
+- `prior_total` must match the client's own record of notes issued;
+- the tracker and unit must be the agreed ones, and the timestamp within 10 minutes of the local clock;
+- the 80-byte message is recomputed from these values, and the template's `message_hex` is never signed.
+
+Additions to the Python behaviour:
+
+- `deliver` first checks the agreement;
+- `decline` and `withdraw` recompute the offer hash when the view carries the terms;
+- `dispute` checks that the delivered content matches its hash;
+- reasons the server refuses are refused locally and never sent. These are non-strings, refused characters and
+  over-length reasons (spec 2.3 and 8.3, release v13);
+- prices must be whole numbers of at least 1. The Python client truncates them with `int()`.
+
+Differences from the Python client that a user may notice:
+
+- requests use `redirect: 'error'`, so a bearer token is never forwarded to a redirect target;
+- a `Content-Type` header is sent only with a body;
+- offers with non-RFC 3339 times are refused. The server accepts date-only and RFC 2822 strings. Python accepts some
+  and crashes on others.
+- the method signatures are camelCase with option objects.
+
+As in the Python client (spec OQ-23), the record of notes issued is updated on `note_issued`, `issuing_note` and
+`completion_awaiting_owner`. An owner rejection after that makes the next completion to that payee fail with
+`ledger_mismatch`.
+
+Not ported: the MCP server and the CLI. The agent tool layer is ported (next section).
+
+## Agent tools
+
+`ValunAgent` is a port of the Python tool layer (`agent.py`, `schemas.py`, `measure.py`, and the service functions of
+`sandbox.py`). It has the same nine tools (`valun_status`, `valun_directory`, `valun_inbox`, `valun_deal`,
+`valun_propose`, `valun_respond`, `valun_deliver`, `valun_review_delivery`, `valun_set_limits`), the same results and
+wording, and the same checks before signing: the missing-text guard, the deliver gate on measured terms, and the
+exact recomputation of text-stats and notary results. `call(name, args)` resolves to a plain object. `callSafe` never
+rejects; failures come back as `{error, message, what_this_means?}`.
+
+`valunTools(agent, {approve})` returns the tools as `{name, description, parameters (JSON Schema), execute(args)}`.
+Before every commitment (an offer, an acceptance, a counter-offer, accepting a delivery, loosening a limit) it first
+binds the arguments with `agent.bind()`, as the Python MCP server and CLI do. An acceptance is pinned to the terms hash
+or deliverable hash current at that moment, unless the agent passed one. It then calls `approve(text, name, args)` with
+the approval text for exactly those arguments and executes exactly them. Only `true` signs. If the offer or delivery
+changes after the owner saw it, the client refuses to sign (`stale_terms`, `stale_delivery`). Without a hook,
+commitments are refused with `approval_unavailable`, unless you pass `approvals: 'none'`, which also skips binding.
+The server enforces the owner's mandate in every mode.
+
+Approvals fail closed, as in the Python core. `valun_respond` counts as a commitment unless the action is exactly
+`decline` or `withdraw`, and `valun_review_delivery` unless the decision is exactly `dispute`. A review decision other
+than exactly `accept` or `dispute` is refused with `bad_decision` before anything is read or signed.
+
+A plain loop against an OpenAI-compatible Chat Completions endpoint, with no framework:
+
+<!-- agent-loop-example -->
+```js
+import {Client, ValunAgent, valunTools} from '@fitzdoud/valun';
+import {FileStore} from '@fitzdoud/valun/file-store';
+import {resolveHost} from '@fitzdoud/valun/dns';
+
+const agent = new ValunAgent(new Client({store: new FileStore('.valun/agent.json')}), {resolveHost});
+const tools = valunTools(agent, {approve: askOwner});   // askOwner(text): show it to a person, resolve true or false
+const spec = tools.map(({name, description, parameters}) => ({type: 'function', function: {name, description, parameters}}));
+const messages = [{role: 'user', content: 'Check Valun and act on my inbox within my limits.'}];
+for (let turn = 0; turn < 10; turn++) {
+  const res = await fetch(process.env.LLM_URL, {method: 'POST', headers: {'content-type': 'application/json',
+    authorization: `Bearer ${process.env.LLM_KEY}`}, body: JSON.stringify({model: process.env.LLM_MODEL, messages, tools: spec})});
+  const msg = (await res.json()).choices[0].message;
+  messages.push(msg);
+  if (!msg.tool_calls?.length) { console.log(msg.content); break; }
+  for (const c of msg.tool_calls) {
+    const t = tools.find(x => x.name === c.function.name);
+    const result = t ? await t.execute(c.function.arguments) : {error: 'unknown_tool'};
+    messages.push({role: 'tool', tool_call_id: c.id, content: JSON.stringify(result)});
+  }
+}
+```
+
+`execute` accepts the arguments as an object or as the raw JSON string of a tool call. Frameworks that take JSON
+Schema tools (Vercel AI SDK, LangChain.js, OpenAI Agents SDK, Mastra) can use these objects directly or after renaming
+a field. Check your framework's docs, for example whether it needs a non-strict schema mode, since many arguments are
+optional. The tools have not been run inside any framework; the test suite runs this loop against a fake model.
+
+- Link hosts: in Node, pass `resolveHost` from `@fitzdoud/valun/dns` (DNS only; no page is fetched). Without it, for
+  example in a browser, measurements say `link_hosts_not_checked`, and the deliver gate checks only word and link counts.
+- `measure`, `sandbox` and `schemas` are exported as namespaces (`measure.measure`, `sandbox.checkDelivery`,
+  `schemas.ALL`).
+
+## Conformance
+
+```
+node --test js/test/        (from the repository root; or `npm test` in js/)
+```
+
+The suite runs offline and needs no packages. It checks the code against every file in `spec/vectors/` (generated
+from the real server code, release v13, valun-app `6a6a34b`):
+
+- `basis-signatures.json`: Basis's official vectors TV001-TV011.
+- `basis-notes.json`: debt keys and 80-byte note messages, signatures and the negative case.
+- `canonical.json`: every tier, including `refused`, `wire` and `generic`, byte for byte.
+- `statements.json`:
+  - every statement text and its UTF-8 bytes;
+  - every signature, alternative form and negative;
+  - each accepted reason is sent unchanged and signed as sent;
+  - each refused reason is refused with the server's code and message, and nothing is sent.
+- `terms-validation.json`: the terms hash of every case, plus a table of what `verifyOffer` does with each case.
+  Validation itself is server-only.
+- `transcript.json`:
+  - every server-verified signature and every terms hash in every response;
+  - all 51 client-call steps and 3 tool-path variants, replayed through the JS `Client` against a fake `fetch` that
+    serves the recorded reads, clock and random values;
+  - each request must equal the recorded one, signatures aside, and each signature must verify over the bytes the
+    server verified.
+
+Signing nonces are random, as in the Python client. Given the generator's nonces instead, `sign()` reproduces every
+signature the vector generator made, byte for byte: all statement-vector signatures and every test-key signature in
+the transcript. The retry rule on `e` and `z` is tested directly, with both branches exercised.
+
+Other tests:
+
+- BLAKE2b is checked against RFC 7693 Appendix A and the Appendix E self-test (all digest lengths, keyed and unkeyed),
+  and against `node:crypto` `blake2b512`.
+- SHA-256 is checked against FIPS vectors and `node:crypto`.
+- Client tests cover every refusal above, HTTP error mapping, timeouts, and that the key and token appear in no state,
+  return value, inspection, JSON or error.
+- File-store tests cover the file layout, exclusive `0600` creation and corrupt files. The POSIX mode assertion is
+  skipped on Windows.
+- Agent tools are tested against the Python reference itself. `test/fixtures/generate_python_fixtures.py` runs the
+  Python `ValunAgent` (CPython 3.14) over recorded server responses, a fixed clock, fixed ids and a fixed DNS table.
+  `agent-parity.test.js` replays all 88 scenarios through the JS agent. Results must be equal, key order included, and
+  so must the requests (signatures aside), the stored state, `isCommitment`, `bind()` and the approval texts for the
+  raw and the bound arguments. Helper-level
+  outputs (measurements, sandbox results, `int()`, `repr()`, IP classification) are compared the same way, and
+  `sandbox-python.json` is the server's fixture. A test fails when `python/src` has changed since the fixtures were
+  generated.
+
+The TypeScript declarations (`src/index.d.ts`, `src/file-store.d.ts`, `src/dns.d.ts`) pass
+`tsc --noEmit --strict --lib es2022,dom` with TypeScript 6.0.3, run through `npx`. It is not a dependency.
+
+This client's BLAKE2b, secp256k1 and Schnorr code are not constant-time. That is fine for a local signer in an
+experiment, not for an exposed signing service.
+
+License: MIT.

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "@fitzdoud/valun",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Zero-dependency JavaScript/TypeScript client for the Valun agent credit network (valun-deal/1): local secp256k1 key, Basis Schnorr signatures, independent checks before every signature. Experimental pilot: synthetic units, nothing settled.",
+  "license": "MIT",
+  "author": "Fitz Doud",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.js"
+    },
+    "./file-store": {
+      "types": "./src/file-store.d.ts",
+      "default": "./src/file-store.js"
+    },
+    "./dns": {
+      "types": "./src/dns.d.ts",
+      "default": "./src/dns.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "keywords": [
+    "valun",
+    "agents",
+    "agent-to-agent",
+    "credit",
+    "basis",
+    "schnorr",
+    "secp256k1",
+    "blake2b"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fitzss/valun-open.git",
+    "directory": "js"
+  },
+  "homepage": "https://github.com/fitzss/valun-open/tree/main/js",
+  "publishConfig": {
+    "access": "public"
+  }
+}