stated-protocol-parser 1.0.6 → 5.0.0

package/README.md

@@ -11,18 +11,19 @@ npm install stated-protocol-parser
 ## Features
 
 - **Statement Parsing & Formatting**: Parse and build statements with domain verification
+- **Cryptographic Signatures**: Sign and verify statements using Ed25519 (Version 5)
 - **Multiple Statement Types**: Support for various statement types including:
   - Basic statements
-  - Quotations
   - Polls and votes
   - Organisation and person verifications
   - Disputes (authenticity and content)
-  - Ratings, bounties, observations, and boycotts
+  - Ratings
   - PDF signing
   - Responses
 - **Type Safety**: Full TypeScript support with comprehensive type definitions
-- **Version Support**: Handles multiple format versions (v3 and v4)
+- **Version Support**: Supports version 5 format
 - **Validation**: Built-in validation for all statement formats
+- **Cross-Platform**: Works in both Node.js and browser environments
 
 ## Usage
 
@@ -46,6 +47,91 @@ console.log(parsed.domain); // 'example.com'
 console.log(parsed.author); // 'Example Organization'
 ```
 
+### Cryptographic Signatures (Version 5)
+
+Version 5 introduces cryptographic signatures for statements, providing non-repudiation and tamper detection.
+
+#### Node.js Example
+
+```typescript
+import {
+  buildStatement,
+  generateKeyPair,
+  buildSignedStatement,
+  verifySignedStatement,
+  parseSignedStatement
+} from 'stated-protocol-parser/node';
+
+// Generate a key pair
+const { publicKey, privateKey } = generateKeyPair();
+
+// Build a statement
+const statement = buildStatement({
+  domain: 'example.com',
+  author: 'Example Organization',
+  time: new Date(),
+  content: 'This is our official signed statement.',
+});
+
+// Sign the statement
+const signedStatement = buildSignedStatement(statement, privateKey, publicKey);
+
+// Verify the signed statement
+const isValid = verifySignedStatement(signedStatement);
+console.log('Signature valid:', isValid); // true
+
+// Parse the signed statement
+const parsed = parseSignedStatement(signedStatement);
+console.log('Original statement:', parsed?.statement);
+console.log('Public key:', parsed?.publicKey);
+console.log('Signature:', parsed?.signature);
+```
+
+#### Browser Example
+
+```typescript
+import {
+  buildStatement,
+  generateKeyPair,
+  buildSignedStatement,
+  verifySignedStatement
+} from 'stated-protocol-parser';
+
+// Generate a key pair (async in browser)
+const { publicKey, privateKey } = await generateKeyPair();
+
+// Build and sign a statement
+const statement = buildStatement({
+  domain: 'example.com',
+  author: 'Example Organization',
+  time: new Date(),
+  content: 'This is our official signed statement.',
+});
+
+const signedStatement = await buildSignedStatement(statement, privateKey, publicKey);
+
+// Verify the signed statement
+const isValid = await verifySignedStatement(signedStatement);
+console.log('Signature valid:', isValid);
+```
+
+#### Signed Statement Format
+
+```
+Stated protocol version: 5
+Publishing domain: example.com
+Author: Example Organization
+Time: Thu, 15 Jun 2023 20:01:26 GMT
+Statement content:
+This is our official signed statement.
+---
+Statement hash: <url-safe-base64-sha256-hash>
+Public key: <url-safe-base64-encoded-public-key>
+Signature: <url-safe-base64-encoded-signature>
+Algorithm: Ed25519
+```
+
+
 ### Poll
 
 ```typescript
@@ -56,10 +142,6 @@ const pollContent = buildPollContent({
   options: ['Yes', 'No', 'Need more information'],
   deadline: new Date('2024-12-31'),
   scopeDescription: 'All registered users',
-  country: undefined,
-  city: undefined,
-  legalEntity: undefined,
-  domainScope: undefined,
 });
 
 const parsed = parsePoll(pollContent);
@@ -100,13 +182,12 @@ const verification = buildPersonVerificationContent({
 ### Statement Functions
 
 - `buildStatement(params)` - Build a statement string
-- `parseStatement({ statement, allowNoVersion? })` - Parse a statement string
+- `parseStatement({ statement })` - Parse a statement string
 
 ### Content Type Functions
 
 Each content type has corresponding build and parse functions:
 
-- **Quotation**: `buildQuotationContent()`, `parseQuotation()`
 - **Poll**: `buildPollContent()`, `parsePoll()`
 - **Vote**: `buildVoteContent()`, `parseVote()`
 - **Organisation Verification**: `buildOrganisationVerificationContent()`, `parseOrganisationVerification()`
@@ -116,9 +197,6 @@ Each content type has corresponding build and parse functions:
 - **Response**: `buildResponseContent()`, `parseResponseContent()`
 - **PDF Signing**: `buildPDFSigningContent()`, `parsePDFSigning()`
 - **Rating**: `buildRating()`, `parseRating()`
-- **Bounty**: `buildBounty()`, `parseBounty()`
-- **Observation**: `buildObservation()`, `parseObservation()`
-- **Boycott**: `buildBoycott()`, `parseBoycott()`
 
 ### Constants
 
@@ -138,7 +216,6 @@ All TypeScript types are exported:
 ```typescript
 import type {
   Statement,
-  Quotation,
   Poll,
   OrganisationVerification,
   PersonVerification,
@@ -147,10 +224,7 @@ import type {
   DisputeContent,
   ResponseContent,
   PDFSigning,
-  Rating,
-  Bounty,
-  Observation,
-  Boycott
+  Rating
 } from 'stated-protocol-parser';
 ```
 
@@ -169,6 +243,8 @@ Optional fields:
 - Authorized signing representative
 - Tags
 - Superseded statement
+- Translations (multi-language support)
+- Attachments (up to 5 file references)
 
 ### Validation Rules
 
@@ -179,11 +255,7 @@ Optional fields:
 
 ## Version Support
 
-The library supports multiple format versions:
-- **Version 3**: Legacy format with different poll structure
-- **Version 4**: Current format (default)
-
-Use `parsePoll(content, '3')` to parse version 3 polls.
+The library supports version 5 format with cryptographic signature support using Ed25519.
 
 ## Error Handling
 
@@ -196,3 +268,140 @@ try {
   console.error('Invalid statement format:', error.message);
 }
 ```
+
+## Static File Publication Standard
+
+Organizations can publish statements as static files on their domain following this standardized structure. This enables automated verification and aggregation of statements.
+
+### Directory Structure
+
+All statement files should be published under the `/.well-known/` directory:
+
+```
+/.well-known/
+├── statements.txt                           # All statements concatenated
+├── statements/
+│   ├── index.txt                           # List of all statement files
+│   ├── <urlsafe_b64_statement_hash>.txt    # Individual statement files
+│   └── attachments/
+│       ├── index.txt                       # List of all attachment files
+│       └── <urlsafe_b64_contents_hash>.<ext>    # Attachment files
+```
+
+### Peer Replication Structure
+
+For peer-to-peer replication of statements from other domains, use the following directory structure under `/.well-known/statements/peers/`:
+
+```
+/.well-known/statements/
+├── peers/
+│   ├── index.txt                                    # List of all peer domains
+│   └── <peer_domain>/
+│       ├── metadata.json                            # Sync metadata for this peer
+│       ├── statements.txt                           # All statements from peer
+│       ├── statements/
+│       │   ├── index.txt                           # List of statement files
+│       │   ├── <urlsafe_b64_statement_hash>.txt    # Individual statements
+│       │   └── attachments/
+│       │       ├── index.txt                       # List of attachments
+│       │       └── <urlsafe_b64_contents_hash>.<ext>  # Attachment files
+```
+
+
+### File Specifications
+
+#### `/.well-known/statements.txt`
+
+Contains all statements concatenated with 2 newline characters (`\n\n`) between each statement.
+
+**Example:**
+```
+Stated protocol version: 5
+Publishing domain: example.com
+Author: Example Organization
+Time: Thu, 15 Jun 2023 20:01:26 GMT
+Statement content:
+First statement content
+
+
+Stated protocol version: 5
+Publishing domain: example.com
+Author: Example Organization
+Time: Fri, 16 Jun 2023 10:30:00 GMT
+Statement content:
+Second statement content
+```
+
+#### `/.well-known/statements/<urlsafe_b64_signed_statement_hash>.txt`
+
+Individual statement files named using the URL-safe base64-encoded SHA-256 hash of the complete file content.
+
+**Important Hash Terminology:**
+
+For signed statements, there are three distinct hash values:
+
+1. **Statement content hash**: Hash of only the content field (the actual message text)
+2. **Statement hash**: Hash of the complete unsigned statement (all fields: domain, author, time, content, etc., but excluding the signature block)
+3. **Signed statement hash**: Hash of the complete signed statement (unsigned statement + signature block)
+
+**Usage:**
+- **Filename**: Uses the **signed statement hash** (hash of entire file content)
+- **Signature block "Statement hash" field**: Contains the **statement hash** (hash of unsigned statement, used for cryptographic verification)
+- **Response references**: Use the **signed statement hash** to reference which statement is being responded to
+
+**Naming Convention:**
+- Hash the complete statement text using SHA-256
+- Encode the hash using URL-safe base64 (replacing `+` with `-` and `/` with `_`, removing padding `=`)
+- Use `.txt` extension
+
+**Example:**
+```
+/.well-known/statements/qg51IiW3RKIXSxiaF_hVQdZdtHzKsU4YePxFuZ2YVtQ.txt
+```
+
+**File Content:**
+```
+Stated protocol version: 5
+Publishing domain: example.com
+Author: Example Organization
+Time: Thu, 15 Jun 2023 20:01:26 GMT
+Statement content:
+This is the statement content
+```
+
+#### `/.well-known/statements/index.txt`
+
+Newline-delimited list of all statement file paths relative to `/.well-known/statements/`.
+
+**Example:**
+```
+qg51IiW3RKIXSxiaF_hVQdZdtHzKsU4YePxFuZ2YVtQ.txt
+YTIhylbTsXvJZN8og3LvusdfjjjnnVudocw1mki11Vs.txt
+NF6irhgDU0F_HEgTRKnhnDlA2R8c9YnjihhiCyNGsQA.txt
+```
+
+#### `/.well-known/statements/attachments/<urlsafe_b64_contents_hash>.<file_extension>`
+
+Attachment files referenced in statements, named using the URL-safe base64-encoded SHA-256 hash of the file contents with the appropriate file extension.
+
+**Naming Convention:**
+- Hash the complete file contents using SHA-256
+- Encode the hash using URL-safe base64
+- Append the original file extension (e.g., `.pdf`, `.jpg`, `.png`, `.json`)
+
+**Example:**
+```
+/.well-known/statements/attachments/8kF3mN9pQ2rT5vW7xY1zA3bC4dE6fG8hI0jK2lM4nO6.pdf
+/.well-known/statements/attachments/pQ9rS1tU3vW5xY7zA9bC1dE3fG5hI7jK9lM1nO3pQ5.jpg
+```
+
+#### `/.well-known/statements/attachments/index.txt`
+
+Newline-delimited list of all attachment file paths relative to `/.well-known/statements/attachments/`.
+
+**Example:**
+```
+8kF3mN9pQ2rT5vW7xY1zA3bC4dE6fG8hI0jK2lM4nO6.pdf
+pQ9rS1tU3vW5xY7zA9bC1dE3fG5hI7jK9lM1nO3pQ5.jpg
+xY1zA3bC4dE6fG8hI0jK2lM4nO6pQ9rS1tU3vW5xY7z.json
+```

package/dist/constants.d.ts

@@ -6,7 +6,6 @@ export declare const legalForms: {
 };
 export declare const statementTypes: {
     statement: string;
-    quotation: string;
     organisationVerification: string;
     personVerification: string;
     poll: string;
@@ -14,23 +13,205 @@ export declare const statementTypes: {
     response: string;
     disputeContent: string;
     disputeAuthenticity: string;
-    boycott: string;
-    observation: string;
     rating: string;
     signPdf: string;
-    bounty: string;
     unsupported: string;
 };
 export declare const peopleCountBuckets: {
-    "0": string;
-    "10": string;
-    "100": string;
-    "1000": string;
-    "10000": string;
-    "100000": string;
-    "1000000": string;
-    "10000000": string;
+    '0': string;
+    '10': string;
+    '100': string;
+    '1000': string;
+    '10000': string;
+    '100000': string;
+    '1000000': string;
+    '10000000': string;
 };
+export declare const supportedLanguages: {
+    readonly aa: "aa";
+    readonly ab: "ab";
+    readonly af: "af";
+    readonly ak: "ak";
+    readonly am: "am";
+    readonly ar: "ar";
+    readonly an: "an";
+    readonly as: "as";
+    readonly av: "av";
+    readonly ay: "ay";
+    readonly az: "az";
+    readonly ba: "ba";
+    readonly bm: "bm";
+    readonly be: "be";
+    readonly bn: "bn";
+    readonly bi: "bi";
+    readonly bo: "bo";
+    readonly bs: "bs";
+    readonly br: "br";
+    readonly bg: "bg";
+    readonly ca: "ca";
+    readonly cs: "cs";
+    readonly ch: "ch";
+    readonly ce: "ce";
+    readonly cv: "cv";
+    readonly kw: "kw";
+    readonly co: "co";
+    readonly cr: "cr";
+    readonly cy: "cy";
+    readonly da: "da";
+    readonly de: "de";
+    readonly dv: "dv";
+    readonly dz: "dz";
+    readonly el: "el";
+    readonly en: "en";
+    readonly eo: "eo";
+    readonly et: "et";
+    readonly eu: "eu";
+    readonly ee: "ee";
+    readonly fo: "fo";
+    readonly fa: "fa";
+    readonly fj: "fj";
+    readonly fi: "fi";
+    readonly fr: "fr";
+    readonly fy: "fy";
+    readonly ff: "ff";
+    readonly gd: "gd";
+    readonly ga: "ga";
+    readonly gl: "gl";
+    readonly gv: "gv";
+    readonly gn: "gn";
+    readonly gu: "gu";
+    readonly ht: "ht";
+    readonly ha: "ha";
+    readonly sh: "sh";
+    readonly he: "he";
+    readonly hz: "hz";
+    readonly hi: "hi";
+    readonly ho: "ho";
+    readonly hr: "hr";
+    readonly hu: "hu";
+    readonly hy: "hy";
+    readonly ig: "ig";
+    readonly io: "io";
+    readonly ii: "ii";
+    readonly iu: "iu";
+    readonly ie: "ie";
+    readonly ia: "ia";
+    readonly id: "id";
+    readonly ik: "ik";
+    readonly is: "is";
+    readonly it: "it";
+    readonly jv: "jv";
+    readonly ja: "ja";
+    readonly kl: "kl";
+    readonly kn: "kn";
+    readonly ks: "ks";
+    readonly ka: "ka";
+    readonly kr: "kr";
+    readonly kk: "kk";
+    readonly km: "km";
+    readonly ki: "ki";
+    readonly rw: "rw";
+    readonly ky: "ky";
+    readonly kv: "kv";
+    readonly kg: "kg";
+    readonly ko: "ko";
+    readonly kj: "kj";
+    readonly ku: "ku";
+    readonly lo: "lo";
+    readonly la: "la";
+    readonly lv: "lv";
+    readonly li: "li";
+    readonly ln: "ln";
+    readonly lt: "lt";
+    readonly lb: "lb";
+    readonly lu: "lu";
+    readonly lg: "lg";
+    readonly mh: "mh";
+    readonly ml: "ml";
+    readonly mr: "mr";
+    readonly mk: "mk";
+    readonly mg: "mg";
+    readonly mt: "mt";
+    readonly mn: "mn";
+    readonly mi: "mi";
+    readonly ms: "ms";
+    readonly my: "my";
+    readonly na: "na";
+    readonly nv: "nv";
+    readonly nr: "nr";
+    readonly nd: "nd";
+    readonly ng: "ng";
+    readonly ne: "ne";
+    readonly nl: "nl";
+    readonly nn: "nn";
+    readonly nb: "nb";
+    readonly no: "no";
+    readonly ny: "ny";
+    readonly oc: "oc";
+    readonly oj: "oj";
+    readonly or: "or";
+    readonly om: "om";
+    readonly os: "os";
+    readonly pa: "pa";
+    readonly pi: "pi";
+    readonly pl: "pl";
+    readonly pt: "pt";
+    readonly ps: "ps";
+    readonly qu: "qu";
+    readonly rm: "rm";
+    readonly ro: "ro";
+    readonly rn: "rn";
+    readonly ru: "ru";
+    readonly sg: "sg";
+    readonly sa: "sa";
+    readonly si: "si";
+    readonly sk: "sk";
+    readonly sl: "sl";
+    readonly se: "se";
+    readonly sm: "sm";
+    readonly sn: "sn";
+    readonly sd: "sd";
+    readonly so: "so";
+    readonly st: "st";
+    readonly es: "es";
+    readonly sq: "sq";
+    readonly sc: "sc";
+    readonly sr: "sr";
+    readonly ss: "ss";
+    readonly su: "su";
+    readonly sw: "sw";
+    readonly sv: "sv";
+    readonly ty: "ty";
+    readonly ta: "ta";
+    readonly tt: "tt";
+    readonly te: "te";
+    readonly tg: "tg";
+    readonly tl: "tl";
+    readonly th: "th";
+    readonly ti: "ti";
+    readonly to: "to";
+    readonly tn: "tn";
+    readonly ts: "ts";
+    readonly tk: "tk";
+    readonly tr: "tr";
+    readonly tw: "tw";
+    readonly ug: "ug";
+    readonly uk: "uk";
+    readonly ur: "ur";
+    readonly uz: "uz";
+    readonly ve: "ve";
+    readonly vi: "vi";
+    readonly vo: "vo";
+    readonly wa: "wa";
+    readonly wo: "wo";
+    readonly xh: "xh";
+    readonly yi: "yi";
+    readonly yo: "yo";
+    readonly za: "za";
+    readonly zh: "zh";
+    readonly zu: "zu";
+};
+export type SupportedLanguage = (typeof supportedLanguages)[keyof typeof supportedLanguages];
 export declare const UTCFormat: RegExp;
 export declare const pollKeys: RegExp;
 export declare const organisationVerificationKeys: RegExp;
@@ -41,7 +222,4 @@ export declare const disputeContentKeys: RegExp;
 export declare const responseKeys: RegExp;
 export declare const PDFSigningKeys: RegExp;
 export declare const ratingKeys: RegExp;
-export declare const BountyKeys: RegExp;
-export declare const ObservationKeys: RegExp;
-export declare const BoycottKeys: RegExp;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU;;;;;CAKtB,CAAA;AAED,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;CAgB1B,CAAA;AAED,eAAO,MAAM,kBAAkB;;;;;;;;;CAS9B,CAAA;AAED,eAAO,MAAM,SAAS,EAAE,MAAkI,CAAA;AAE1J,eAAO,MAAM,QAAQ,QAAmX,CAAA;AAExY,eAAO,MAAM,4BAA4B,QAAgV,CAAA;AAEzX,eAAO,MAAM,sBAAsB,QAAqP,CAAA;AAExR,eAAO,MAAM,QAAQ,QAAwC,CAAA;AAE7D,eAAO,MAAM,uBAAuB,QAA6F,CAAA;AAEjI,eAAO,MAAM,kBAAkB,QAA6F,CAAA;AAE5H,eAAO,MAAM,YAAY,QAAuD,CAAA;AAEhF,eAAO,MAAM,cAAc,QAA2C,CAAA;AAEtE,eAAO,MAAM,UAAU,QAAyI,CAAA;AAEhK,eAAO,MAAM,UAAU,QAA8L,CAAA;AAErN,eAAO,MAAM,eAAe,QAA8J,CAAA;AAE1L,eAAO,MAAM,WAAW,QAAkE,CAAA"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,UAAU;;;;;CAKtB,CAAC;AAEF,eAAO,MAAM,cAAc;;;;;;;;;;;;CAY1B,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;CAS9B,CAAC;AAEF,eAAO,MAAM,kBAAkB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuLrB,CAAC;AAEX,MAAM,MAAM,iBAAiB,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,OAAO,kBAAkB,CAAC,CAAC;AAE7F,eAAO,MAAM,SAAS,EAAE,MACmG,CAAC;AAE5H,eAAO,MAAM,QAAQ,QAC6V,CAAC;AAEnX,eAAO,MAAM,4BAA4B,QACmT,CAAC;AAE7V,eAAO,MAAM,sBAAsB,QACiN,CAAC;AAErP,eAAO,MAAM,QAAQ,QAAwC,CAAC;AAE9D,eAAO,MAAM,uBAAuB,QACwD,CAAC;AAE7F,eAAO,MAAM,kBAAkB,QAC6D,CAAC;AAE7F,eAAO,MAAM,YAAY,QAAuD,CAAC;AAEjF,eAAO,MAAM,cAAc,QAA4C,CAAC;AAExE,eAAO,MAAM,UAAU,QACiH,CAAC"}