organic-protocol 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 suipotryot
+
+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/PROTOCOL.md

@@ -0,0 +1,131 @@
+# Organic Money — Protocole inter-instances (v1)
+
+Ce document est le **standard** que toute implémentation compatible (application ou serveur) doit respecter. Le paquet npm [`organic-protocol`](https://www.npmjs.com/package/organic-protocol) en est la traduction TypeScript exacte ; les implémentations JS/TS devraient l'importer plutôt que réimplémenter. La cryptographie (signatures, chaînes, chiffrement) est définie par [`organic-money`](https://www.npmjs.com/package/organic-money) et n'est pas répétée ici.
+
+Version du protocole : **1**. Version du format QR : **1** (indépendante, voir §4).
+
+---
+
+## 1. Identité fédérée
+
+Une clé publique seule ne suffit pas à joindre quelqu'un dans un réseau décentralisé. Une **identité** est toujours la paire :
+
+```json
+{ "pk": "<clé publique SECP256K1 compressée, hex>", "url": "<URL racine du serveur référent>" }
+```
+
+L'`url` est l'URL **racine** du serveur (sans `/api`, sans slash final), normalisée : schéma `https` par défaut (`http` toléré s'il est explicite — réseaux locaux, développement), hôte en minuscules. Voir `normalizeServerUrl`.
+
+## 2. Formats de fil (wire)
+
+### 2.1 Transaction (`TxWire`)
+
+```json
+{ "v": 1, "d": 20260719, "t": 3, "p": "<pk cible>", "s": "<pk signataire>",
+  "m": [20260719001], "i": [], "h": "<signature DER hex>" }
+```
+
+| Champ | Nom long | Contenu |
+|---|---|---|
+| `v` | version | version du protocole (1) |
+| `d` | date | entier `YYYYMMDD` |
+| `t` | type | type de transaction (§3) |
+| `p` | target | clé publique du destinataire |
+| `s` | signer | clé publique de l'émetteur |
+| `m` | money | ids d'unités de monnaie (`YYYYMMDDXXX`) |
+| `i` | invests | ids d'unités d'invest (`YYYYMMDD9XXX`) |
+| `h` | signature | signature SECP256K1 DER, hex |
+
+### 2.2 Bloc (`BlockWire`)
+
+```json
+{ "v": 1, "d": 20260719, "p": "<signature du bloc précédent>", "s": "<pk>",
+  "m": [], "i": [], "t": 42, "r": "<racine de Merkle>", "h": "<signature>", "x": [ …TxWire ] }
+```
+
+`t` est ici le **total** (expérience économique cumulée) ; `p` est la signature du bloc précédent (chaînage) ; `x` la liste des transactions.
+
+## 3. Types de transaction
+
+| # | Type | # | Type |
+|---|---|---|---|
+| 1 | INIT | 8 | SETPAYER |
+| 2 | CREATE | 9 | UNSETADMIN |
+| 3 | PAY | 10 | UNSETACTOR |
+| 4 | ENGAGE | 11 | UNSETPAYER |
+| 5 | PAPER | 12 | PAYERORDER |
+| 6 | SETADMIN | 13 | EARN |
+| 7 | SETACTOR | | |
+
+## 4. QR codes
+
+Format : **`OM<version>:<TYPE>:<payload JSON>`** — le préfixe est hors JSON pour permettre le dispatch (et le rejet d'une version inconnue) sans parser. Version courante : `1`.
+
+**Règle de compatibilité** : un lecteur qui rencontre une version qu'il ne connaît pas DOIT refuser proprement (« mettez à jour l'application ») et NE DOIT JAMAIS tenter d'interpréter au mieux.
+
+| Type | Forme | Usage |
+|---|---|---|
+| `CT` | `OM1:CT:{"pk","url","n","e"?}` | Carte de contact. `n` = nom affiché ; `e` = true si écosystème. |
+| `TX` | `OM1:TX:{"tx":<TxWire PAY>,"url"}` | Paiement hors-ligne, caméra contre écran. `url` = serveur du PAYEUR, pour la vérification différée (§5, `tx/verify`). |
+| `BR` | `OM1:BR:{"pk","url","n"}` | Demande de validation d'un nouveau citoyen. Les blocs sont récupérés via `GET {url}/api/v1/validations/{pk}` (Phase 2) — le QR est un pointeur, pas un conteneur. |
+| `PP` | `OM1:PP:{"tx":<TxWire PAPER>}` | Billet papier imprimé. |
+
+Contraintes : le `tx` d'un `TX` est de type PAY ; celui d'un `PP` est de type PAPER.
+
+## 5. API REST `/api/v1`
+
+Toutes les routes vivent sous `{url}/api/v1`. Corps en JSON. Les erreurs portent `{ "error": "<message>", "code": "<ApiErrorCode>"? }`.
+
+### 5.1 Authentifications
+
+**Block-auth** (`PUT /users/save`, `PUT /users/sign`) — en-tête `x-signature` = signature du hash du bloc soumis, par la clé du compte :
+`x-signature = signHash(block.hash(), sk)`.
+
+**Timestamp-auth** (`GET /tx/list`, `POST /users/password`, …) — en-tête `x-signature` = `signHash(sha256(publickey + ":" + timestamp), sk)` avec `publickey` et `timestamp` (secondes Unix) transmis en paramètres/corps. Tolérance : ±5 minutes, sinon 401.
+
+### 5.2 Endpoints (Phase 1)
+
+| Méthode & route | Auth | Corps → Réponse | Notes |
+|---|---|---|---|
+| `GET /info` | — | → `InfoResponse` | carte d'identité publique du serveur |
+| `GET /servers` | — | → `ServerListEntry[]` | annuaire des serveurs connus |
+| `POST /users/register` | — | `RegisterBody` → `RegisterResponse` | la `secretkey` arrive CHIFFRÉE (opaque pour le serveur) ; le mot de passe est bcrypté à l'arrivée |
+| `POST /users/login` | — | `LoginBody` → `LoginResponse` | **rotation du devicetoken** : l'appareil précédent est révoqué |
+| `PUT /users/save` | block | `SaveBlockBody` → 200 | `409 DEVICE_REVOKED` si le devicetoken n'est plus l'actif |
+| `PUT /users/sign` | block | `SignBlockBody` → 200 | le serveur signe le dernier bloc (billets, genèse) |
+| `POST /users/password` | timestamp | `PasswordChangeBody` → 200 | met à jour bcrypt + sk re-chiffrée, sans rien lire |
+| `POST /tx/send` | — | `TxSendBody` → 200 | **vérification croisée OBLIGATOIRE** (§5.3) |
+| `GET /tx/list` | timestamp | → `TxWire[]` | paiements en attente pour la clé |
+| `POST /tx/verify` | — | `TxVerifyBody` → `TxVerifyResponse` | lecture seule ; statuts : `confirmed` / `pending` / `invalid` / `unknown-sender` |
+| `POST /papers/cash` | — | `PapersCashBody` → 200 | exige le PAPER complet, vérifie sa crypto ; `409 ALREADY_CASHED` |
+| `GET /papers/isCashed?hash=` | — | → `IsCashedResponse` \| 404 | 404 = jamais encaissé |
+
+### 5.3 Vérification croisée (obligation du serveur)
+
+Avant d'accepter sur `tx/send` (et, en Phase 2, toute entrée d'écosystème), le serveur DOIT :
+
+1. vérifier la validité cryptographique de la transaction ;
+2. charger la chaîne **sauvegardée** de l'émetteur (`tx.s`) et la valider (`assertIsValid`) ;
+3. vérifier que la transaction figure dans l'historique de cette chaîne (par sa signature `h`).
+
+Sans l'étape 3, un attaquant peut signer une transaction portant des unités qu'il ne possède pas. Conséquence côté client : l'ordre **`pay → save → send` est strict**.
+
+### 5.4 Un compte = un appareil actif
+
+Le serveur émet un `devicetoken` opaque (UUID) au `register` et à chaque `login` ; seul le dernier émis est valide. Un `save` portant un jeton périmé reçoit `409 DEVICE_REVOKED` — l'application doit alors passer en lecture seule et proposer la restauration. Ce mécanisme n'est pas cryptographique (l'identité reste prouvée par `x-signature`) ; il empêche le fork accidentel d'une chaîne entre deux appareils.
+
+### 5.5 Codes d'erreur
+
+`INVALID_TX` · `INVALID_CHAIN` · `TX_NOT_IN_CHAIN` · `UNKNOWN_SENDER` · `UNKNOWN_USER` · `INVALID_SIGNATURE` · `DEVICE_REVOKED` · `ALREADY_CASHED`
+
+## 6. Versionnement
+
+- **Protocole** (`PROTOCOL_VERSION`, champ `v` des tx/blocs) : n'augmente que sur rupture du format de fil.
+- **QR** (`QR_VERSION`, préfixe `OM<v>`) : n'augmente que sur rupture des payloads QR.
+- **API** (`/api/v1`) : une rupture de contrat REST crée `/api/v2` ; `GET /info` annonce les versions parlées.
+
+Les trois évoluent indépendamment. Toute implémentation DOIT annoncer ses versions via `GET /info` et refuser proprement ce qu'elle ne parle pas.
+
+---
+
+*Licence MIT — © suipotryot. Les phases 2 (écosystèmes, validations) et 3 (fédération) étendront ce document sans casser la v1.*

package/README.md

@@ -0,0 +1,30 @@
+# organic-protocol
+
+> The shared protocol of the [Organic Economy](https://economie-organique.fr) — wire formats, QR codes and REST contracts, verified by the TypeScript compiler.
+
+This package carries the **shapes** that travel between Organic Economy instances: transaction and block wire formats, the versioned QR standard (`OM1:CT/TX/BR/PP`) with its encode/decode functions, and the DTOs of the `/api/v1` REST contract. It contains **no cryptography** — that lives in [`organic-money`](https://www.npmjs.com/package/organic-money).
+
+The [organic-webapp](https://github.com/GuziEconomy/organic-webapp) client and the [organic-webserver](https://github.com/GuziEconomy/organic-webserver) server both import this package, so any drift between what one sends and the other expects becomes a compile error instead of a silent bug. Third-party implementations should either import it or implement [PROTOCOL.md](PROTOCOL.md), which is the same standard in prose.
+
+```bash
+npm install organic-protocol
+```
+
+```ts
+import { decodeQr, encodeContactQr, UnsupportedQrVersionError } from 'organic-protocol'
+
+const qr = encodeContactQr({ pk: '02ab…', url: 'https://trifouillis.fr', n: 'Alice' })
+const decoded = decodeQr(qr) // { type: 'CT', payload: { pk, url, n } }
+```
+
+## Development
+
+```bash
+npm install
+npm run build   # tsc → dist/
+npm test        # mocha + chai (via tsx)
+```
+
+## License
+
+[MIT](LICENSE) — © suipotryot

package/dist/api.d.ts

@@ -0,0 +1,103 @@
+/**
+ * DTOs of the `/api/v1` REST contract — the exact request and response bodies
+ * every compatible server must speak. See PROTOCOL.md §5 for semantics
+ * (authentication, error cases, verification duties).
+ */
+import type { BlockWire, PublicKeyHex, TxWire } from './wire.js';
+/** Machine-readable error codes carried alongside HTTP status codes. */
+export type ApiErrorCode = 'INVALID_TX' | 'INVALID_CHAIN' | 'TX_NOT_IN_CHAIN' | 'UNKNOWN_SENDER' | 'UNKNOWN_USER' | 'INVALID_SIGNATURE' | 'DEVICE_REVOKED' | 'ALREADY_CASHED';
+/** Error body returned with any non-2xx response. */
+export interface ApiError {
+    error: string;
+    code?: ApiErrorCode;
+}
+export interface InfoResponse {
+    protocolVersion: number;
+    apiVersion: string;
+    /** human-readable server name, shown on the server-selection screen */
+    name: string;
+    serverPk: PublicKeyHex;
+    /** public key of the core ecosystem of this server (null until Phase 2) */
+    corePk: PublicKeyHex | null;
+    stats: {
+        users: number;
+    };
+}
+/** One entry of the known-servers directory. */
+export interface ServerListEntry {
+    name: string;
+    url: string;
+}
+export type ServersResponse = ServerListEntry[];
+export interface RegisterBody {
+    publickey: PublicKeyHex;
+    name: string;
+    mail: string;
+    /** LOGIN password (bcrypted server-side). Never the encryption password. */
+    password: string;
+    /** ISO date of birth, e.g. "1990-03-15" */
+    birthdate: string;
+    /** the secret key AES-encrypted client-side — opaque to the server */
+    secretkey: string;
+    /** the chain holding exactly one BirthBlock awaiting validation */
+    blocks: BlockWire[];
+}
+export interface RegisterResponse {
+    publickey: PublicKeyHex;
+    /** the validated chain (server-signed in genesis mode) */
+    blocks: BlockWire[];
+    devicetoken: string;
+}
+export interface LoginBody {
+    mail: string;
+    password: string;
+}
+/** A successful login rotates the devicetoken: the previous device is revoked. */
+export interface LoginResponse {
+    publickey: PublicKeyHex;
+    name: string;
+    mail: string;
+    /** the AES-encrypted secret key, exactly as uploaded */
+    secretkey: string;
+    blocks: BlockWire[];
+    devicetoken: string;
+}
+export interface SaveBlockBody {
+    publickey: PublicKeyHex;
+    block: BlockWire;
+    devicetoken: string;
+}
+export interface SignBlockBody {
+    publickey: PublicKeyHex;
+    block: BlockWire;
+}
+export interface PasswordChangeBody {
+    publickey: PublicKeyHex;
+    /** Unix timestamp (seconds) also used by the timestamp-auth signature */
+    timestamp: number;
+    newpassword: string;
+    /** the secret key re-encrypted client-side with the new password */
+    secretkey: string;
+}
+/**
+ * The server MUST cross-verify before queueing: load the sender's saved chain,
+ * assert it is valid, and check the transaction exists in its history.
+ */
+export interface TxSendBody {
+    tx: TxWire;
+}
+export type TxListResponse = TxWire[];
+export interface TxVerifyBody {
+    tx: TxWire;
+}
+export type TxVerifyStatus = 'confirmed' | 'pending' | 'invalid' | 'unknown-sender';
+export interface TxVerifyResponse {
+    status: TxVerifyStatus;
+}
+/** The full PAPER transaction is required — the server verifies it before registering the hash. */
+export interface PapersCashBody {
+    tx: TxWire;
+}
+export interface IsCashedResponse {
+    id: number | string;
+}

package/dist/api.js

@@ -0,0 +1,6 @@
+/**
+ * DTOs of the `/api/v1` REST contract — the exact request and response bodies
+ * every compatible server must speak. See PROTOCOL.md §5 for semantics
+ * (authentication, error cases, verification duties).
+ */
+export {};

package/dist/identity.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Federated identity: in a decentralized network, a public key alone is not
+ * enough to reach someone — you also need to know which server hosts them.
+ * An identity is therefore always the pair { pk, url }.
+ */
+import type { PublicKeyHex } from './wire.js';
+/** A reachable actor of the network: a key and its referent server. */
+export interface Identity {
+    pk: PublicKeyHex;
+    /** Root URL of the referent server, normalized (no trailing slash, no /api). */
+    url: string;
+}
+export type ContactType = 'citizen' | 'ecosystem';
+/** A saved contact, as stored by the app. */
+export interface Contact extends Identity {
+    name: string;
+    type: ContactType;
+}
+export declare class InvalidServerUrlError extends Error {
+    constructor(raw: string);
+}
+/**
+ * Normalize a user-supplied server URL to its canonical form:
+ * - adds `https://` when no scheme is given (plain `http:` is kept if explicit,
+ *   for local networks and development)
+ * - lowercases the host
+ * - strips trailing slashes and a trailing `/api` (identities carry the ROOT url)
+ * @throws InvalidServerUrlError when the input cannot be parsed as an URL.
+ */
+export declare function normalizeServerUrl(raw: string): string;

package/dist/identity.js

@@ -0,0 +1,38 @@
+/**
+ * Federated identity: in a decentralized network, a public key alone is not
+ * enough to reach someone — you also need to know which server hosts them.
+ * An identity is therefore always the pair { pk, url }.
+ */
+export class InvalidServerUrlError extends Error {
+    constructor(raw) {
+        super(`Invalid server URL: "${raw}"`);
+        this.name = 'InvalidServerUrlError';
+    }
+}
+/**
+ * Normalize a user-supplied server URL to its canonical form:
+ * - adds `https://` when no scheme is given (plain `http:` is kept if explicit,
+ *   for local networks and development)
+ * - lowercases the host
+ * - strips trailing slashes and a trailing `/api` (identities carry the ROOT url)
+ * @throws InvalidServerUrlError when the input cannot be parsed as an URL.
+ */
+export function normalizeServerUrl(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        throw new InvalidServerUrlError(raw);
+    const withScheme = /^[a-zA-Z][a-zA-Z0-9+.-]*:\/\//.test(trimmed) ? trimmed : `https://${trimmed}`;
+    let url;
+    try {
+        url = new URL(withScheme);
+    }
+    catch {
+        throw new InvalidServerUrlError(raw);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        throw new InvalidServerUrlError(raw);
+    let path = url.pathname.replace(/\/+$/, '');
+    if (path.toLowerCase().endsWith('/api'))
+        path = path.slice(0, -4);
+    return `${url.protocol}//${url.host}${path}`;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { PROTOCOL_VERSION, TxType, isTxWire, isBlockWire, type IntDate, type UnitId, type PublicKeyHex, type SignatureHex, type TxWire, type BlockWire, } from './wire.js';
+export { InvalidServerUrlError, normalizeServerUrl, type Identity, type Contact, type ContactType, } from './identity.js';
+export { QR_VERSION, QrError, UnsupportedQrVersionError, InvalidQrError, encodeContactQr, encodeOfflineTxQr, encodeValidationQr, encodePaperQr, decodeQr, type QrType, type DecodedQr, type ContactQrPayload, type OfflineTxQrPayload, type ValidationQrPayload, type PaperQrPayload, } from './qr.js';
+export type { ApiError, ApiErrorCode, InfoResponse, ServerListEntry, ServersResponse, RegisterBody, RegisterResponse, LoginBody, LoginResponse, SaveBlockBody, SignBlockBody, PasswordChangeBody, TxSendBody, TxListResponse, TxVerifyBody, TxVerifyStatus, TxVerifyResponse, PapersCashBody, IsCashedResponse, } from './api.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { PROTOCOL_VERSION, TxType, isTxWire, isBlockWire, } from './wire.js';
+export { InvalidServerUrlError, normalizeServerUrl, } from './identity.js';
+export { QR_VERSION, QrError, UnsupportedQrVersionError, InvalidQrError, encodeContactQr, encodeOfflineTxQr, encodeValidationQr, encodePaperQr, decodeQr, } from './qr.js';

package/dist/qr.d.ts

@@ -0,0 +1,77 @@
+/**
+ * QR code formats — the inter-instance standard for camera-to-screen exchange.
+ *
+ * Every Organic Money QR is the string `OM<version>:<TYPE>:<JSON payload>`.
+ * The prefix lives OUTSIDE the JSON so any reader can dispatch (or reject an
+ * unknown version) without parsing. Current version: 1.
+ *
+ * Types:
+ *   CT — contact card         {pk, url, n, e?}
+ *   TX — offline payment      {tx, url}
+ *   BR — validation request   {pk, url, n}
+ *   PP — paper money          {tx}
+ */
+import { type PublicKeyHex, type TxWire } from './wire.js';
+/** Current QR format version (independent of PROTOCOL_VERSION on purpose). */
+export declare const QR_VERSION = 1;
+export type QrType = 'CT' | 'TX' | 'BR' | 'PP';
+/** Contact card: shown by `account-details`, scanned by `add-contact`. */
+export interface ContactQrPayload {
+    pk: PublicKeyHex;
+    url: string;
+    /** display name */
+    n: string;
+    /** true when the contact is an ecosystem */
+    e?: boolean;
+}
+/** Offline payment: a signed PAY transaction handed camera-to-screen. */
+export interface OfflineTxQrPayload {
+    tx: TxWire;
+    /** root URL of the PAYER's server, for deferred verification (tx/verify) */
+    url: string;
+}
+/** Validation request: shown by a candidate citizen, scanned by a core-ecosystem admin. */
+export interface ValidationQrPayload {
+    pk: PublicKeyHex;
+    url: string;
+    n: string;
+}
+/** Paper money: a signed PAPER transaction printed on a bill. */
+export interface PaperQrPayload {
+    tx: TxWire;
+}
+export type DecodedQr = {
+    type: 'CT';
+    payload: ContactQrPayload;
+} | {
+    type: 'TX';
+    payload: OfflineTxQrPayload;
+} | {
+    type: 'BR';
+    payload: ValidationQrPayload;
+} | {
+    type: 'PP';
+    payload: PaperQrPayload;
+};
+export declare class QrError extends Error {
+}
+/** The scanned QR is an Organic Money QR of a version this build doesn't speak. */
+export declare class UnsupportedQrVersionError extends QrError {
+    readonly version: number;
+    constructor(version: number);
+}
+/** The scanned text is not a valid Organic Money QR. */
+export declare class InvalidQrError extends QrError {
+    constructor(reason: string);
+}
+export declare const encodeContactQr: (payload: ContactQrPayload) => string;
+export declare const encodeOfflineTxQr: (payload: OfflineTxQrPayload) => string;
+export declare const encodeValidationQr: (payload: ValidationQrPayload) => string;
+export declare const encodePaperQr: (payload: PaperQrPayload) => string;
+/**
+ * Decode any Organic Money QR.
+ * @throws UnsupportedQrVersionError for a QR of a newer/unknown version —
+ *         the app must tell the user to update, never guess.
+ * @throws InvalidQrError for anything that is not a well-formed OM QR.
+ */
+export declare function decodeQr(text: string): DecodedQr;

package/dist/qr.js

@@ -0,0 +1,100 @@
+/**
+ * QR code formats — the inter-instance standard for camera-to-screen exchange.
+ *
+ * Every Organic Money QR is the string `OM<version>:<TYPE>:<JSON payload>`.
+ * The prefix lives OUTSIDE the JSON so any reader can dispatch (or reject an
+ * unknown version) without parsing. Current version: 1.
+ *
+ * Types:
+ *   CT — contact card         {pk, url, n, e?}
+ *   TX — offline payment      {tx, url}
+ *   BR — validation request   {pk, url, n}
+ *   PP — paper money          {tx}
+ */
+import { isTxWire, TxType } from './wire.js';
+/** Current QR format version (independent of PROTOCOL_VERSION on purpose). */
+export const QR_VERSION = 1;
+export class QrError extends Error {
+}
+/** The scanned QR is an Organic Money QR of a version this build doesn't speak. */
+export class UnsupportedQrVersionError extends QrError {
+    version;
+    constructor(version) {
+        super(`Unsupported Organic Money QR version ${version} (this app speaks version ${QR_VERSION}). Please update the app.`);
+        this.version = version;
+        this.name = 'UnsupportedQrVersionError';
+    }
+}
+/** The scanned text is not a valid Organic Money QR. */
+export class InvalidQrError extends QrError {
+    constructor(reason) {
+        super(`Invalid Organic Money QR: ${reason}`);
+        this.name = 'InvalidQrError';
+    }
+}
+const PREFIX_RE = /^OM(\d+):([A-Z]{2}):([\s\S]*)$/;
+const encode = (type, payload) => `OM${QR_VERSION}:${type}:${JSON.stringify(payload)}`;
+export const encodeContactQr = (payload) => encode('CT', payload);
+export const encodeOfflineTxQr = (payload) => encode('TX', payload);
+export const encodeValidationQr = (payload) => encode('BR', payload);
+export const encodePaperQr = (payload) => encode('PP', payload);
+const isNonEmptyString = (s) => typeof s === 'string' && s.length > 0;
+function assertContact(p) {
+    if (!isNonEmptyString(p.pk) || !isNonEmptyString(p.url) || !isNonEmptyString(p.n))
+        throw new InvalidQrError('contact payload requires pk, url and n');
+    if (p.e !== undefined && typeof p.e !== 'boolean')
+        throw new InvalidQrError('contact field e must be a boolean');
+}
+function assertValidation(p) {
+    if (!isNonEmptyString(p.pk) || !isNonEmptyString(p.url) || !isNonEmptyString(p.n))
+        throw new InvalidQrError('validation payload requires pk, url and n');
+}
+function assertTx(p, requireUrl, expectedType) {
+    if (!isTxWire(p.tx))
+        throw new InvalidQrError('payload requires a well-formed tx');
+    if (requireUrl && !isNonEmptyString(p.url))
+        throw new InvalidQrError('payload requires the payer server url');
+    if (expectedType !== undefined && p.tx.t !== expectedType)
+        throw new InvalidQrError(`tx must be of type ${TxType[expectedType]}`);
+}
+/**
+ * Decode any Organic Money QR.
+ * @throws UnsupportedQrVersionError for a QR of a newer/unknown version —
+ *         the app must tell the user to update, never guess.
+ * @throws InvalidQrError for anything that is not a well-formed OM QR.
+ */
+export function decodeQr(text) {
+    const match = PREFIX_RE.exec(text.trim());
+    if (!match)
+        throw new InvalidQrError('not an OM<v>:<TYPE>:<payload> string');
+    const version = Number(match[1]);
+    if (version !== QR_VERSION)
+        throw new UnsupportedQrVersionError(version);
+    const type = match[2];
+    let payload;
+    try {
+        payload = JSON.parse(match[3]);
+    }
+    catch {
+        throw new InvalidQrError('payload is not valid JSON');
+    }
+    if (typeof payload !== 'object' || payload === null)
+        throw new InvalidQrError('payload must be a JSON object');
+    const p = payload;
+    switch (type) {
+        case 'CT':
+            assertContact(p);
+            return { type: 'CT', payload: { pk: p.pk, url: p.url, n: p.n, ...(p.e !== undefined ? { e: p.e } : {}) } };
+        case 'TX':
+            assertTx(p, true, TxType.PAY);
+            return { type: 'TX', payload: { tx: p.tx, url: p.url } };
+        case 'BR':
+            assertValidation(p);
+            return { type: 'BR', payload: { pk: p.pk, url: p.url, n: p.n } };
+        case 'PP':
+            assertTx(p, false, TxType.PAPER);
+            return { type: 'PP', payload: { tx: p.tx } };
+        default:
+            throw new InvalidQrError(`unknown QR type "${type}"`);
+    }
+}

package/dist/wire.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Wire formats of the Organic Money protocol — the exact shapes that travel
+ * between instances (app ↔ server, QR codes, blockchain exports).
+ * Mirrors the serialization implemented by organic-money.js.
+ */
+/** Current protocol version. Bump only on breaking wire-format changes. */
+export declare const PROTOCOL_VERSION = 1;
+/** Transaction types (see PROTOCOL.md §3). */
+export declare enum TxType {
+    INIT = 1,
+    CREATE = 2,
+    PAY = 3,
+    ENGAGE = 4,
+    PAPER = 5,
+    SETADMIN = 6,
+    SETACTOR = 7,
+    SETPAYER = 8,
+    UNSETADMIN = 9,
+    UNSETACTOR = 10,
+    UNSETPAYER = 11,
+    PAYERORDER = 12,
+    EARN = 13
+}
+/** Date as a YYYYMMDD integer, e.g. 20260719. */
+export type IntDate = number;
+/**
+ * Money unit id (`YYYYMMDDXXX`, e.g. 20260719003) or invest unit id
+ * (`YYYYMMDD9XXX`, e.g. 202607199003 — the `9` separator marks invests).
+ * The creation date is embedded in the id.
+ */
+export type UnitId = number;
+/** Compressed SECP256K1 public key, hex-encoded (33 bytes → 66 chars). */
+export type PublicKeyHex = string;
+/** DER-encoded SECP256K1 signature, hex-encoded. */
+export type SignatureHex = string;
+/**
+ * A transaction in wire format (short field names for compactness).
+ * Field meanings: v=version, d=date, t=type, p=target, s=signer,
+ * m=money ids, i=invest ids, h=signature.
+ */
+export interface TxWire {
+    v: number;
+    d: IntDate;
+    t: TxType;
+    p: PublicKeyHex;
+    s: PublicKeyHex;
+    m: UnitId[];
+    i: UnitId[];
+    h: SignatureHex;
+}
+/**
+ * A sealed (or open) block in wire format.
+ * Field meanings: v=version, d=closedate, p=previous block signature,
+ * s=signer, m=available money at seal time, i=available invests,
+ * t=total (economic experience), r=merkle root, h=block signature,
+ * x=transactions.
+ */
+export interface BlockWire {
+    v: number;
+    d: IntDate;
+    p: string;
+    s: PublicKeyHex;
+    m: UnitId[];
+    i: UnitId[];
+    t: number;
+    r: string;
+    h: SignatureHex;
+    x: TxWire[];
+}
+/** Structural check that an unknown value is a well-formed TxWire. */
+export declare function isTxWire(o: unknown): o is TxWire;
+/** Structural check that an unknown value is a well-formed BlockWire. */
+export declare function isBlockWire(o: unknown): o is BlockWire;

package/dist/wire.js

@@ -0,0 +1,60 @@
+/**
+ * Wire formats of the Organic Money protocol — the exact shapes that travel
+ * between instances (app ↔ server, QR codes, blockchain exports).
+ * Mirrors the serialization implemented by organic-money.js.
+ */
+/** Current protocol version. Bump only on breaking wire-format changes. */
+export const PROTOCOL_VERSION = 1;
+/** Transaction types (see PROTOCOL.md §3). */
+export var TxType;
+(function (TxType) {
+    TxType[TxType["INIT"] = 1] = "INIT";
+    TxType[TxType["CREATE"] = 2] = "CREATE";
+    TxType[TxType["PAY"] = 3] = "PAY";
+    TxType[TxType["ENGAGE"] = 4] = "ENGAGE";
+    TxType[TxType["PAPER"] = 5] = "PAPER";
+    TxType[TxType["SETADMIN"] = 6] = "SETADMIN";
+    TxType[TxType["SETACTOR"] = 7] = "SETACTOR";
+    TxType[TxType["SETPAYER"] = 8] = "SETPAYER";
+    TxType[TxType["UNSETADMIN"] = 9] = "UNSETADMIN";
+    TxType[TxType["UNSETACTOR"] = 10] = "UNSETACTOR";
+    TxType[TxType["UNSETPAYER"] = 11] = "UNSETPAYER";
+    TxType[TxType["PAYERORDER"] = 12] = "PAYERORDER";
+    TxType[TxType["EARN"] = 13] = "EARN";
+})(TxType || (TxType = {}));
+const isHex = (s) => typeof s === 'string' && /^[0-9a-fA-F]*$/.test(s);
+const isUnitIdArray = (a) => Array.isArray(a) && a.every((n) => typeof n === 'number' && Number.isInteger(n));
+/** Structural check that an unknown value is a well-formed TxWire. */
+export function isTxWire(o) {
+    if (typeof o !== 'object' || o === null)
+        return false;
+    const t = o;
+    return (typeof t.v === 'number' &&
+        typeof t.d === 'number' &&
+        Number.isInteger(t.d) &&
+        typeof t.t === 'number' &&
+        t.t >= TxType.INIT &&
+        t.t <= TxType.EARN &&
+        isHex(t.p) &&
+        isHex(t.s) &&
+        isUnitIdArray(t.m) &&
+        isUnitIdArray(t.i) &&
+        isHex(t.h));
+}
+/** Structural check that an unknown value is a well-formed BlockWire. */
+export function isBlockWire(o) {
+    if (typeof o !== 'object' || o === null)
+        return false;
+    const b = o;
+    return (typeof b.v === 'number' &&
+        typeof b.d === 'number' &&
+        isHex(b.p) &&
+        isHex(b.s) &&
+        isUnitIdArray(b.m) &&
+        isUnitIdArray(b.i) &&
+        typeof b.t === 'number' &&
+        isHex(b.r) &&
+        isHex(b.h) &&
+        Array.isArray(b.x) &&
+        b.x.every(isTxWire));
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "organic-protocol",
+  "version": "0.1.0",
+  "description": "The shared protocol of the Organic Economy: wire formats, QR codes and API contracts, verified by the TypeScript compiler. Companion of organic-money.",
+  "keywords": [
+    "organic-economy",
+    "organic-money",
+    "protocol",
+    "qr"
+  ],
+  "license": "MIT",
+  "author": "suipotryot",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "PROTOCOL.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "mocha",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "devDependencies": {
+    "@types/chai": "^5.0.1",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "^24.0.0",
+    "chai": "^5.1.2",
+    "mocha": "^11.0.1",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}