stated-protocol 5.0.0

package/README.md

@@ -0,0 +1,409 @@
+# Stated Protocol Parser
+
+[![npm](https://img.shields.io/badge/npm-stated--protocol--parser-CB3837?logo=npm)](https://www.npmjs.com/package/stated-protocol-parser)
+
+A TypeScript library for parsing and formatting statements in the Stated protocol - a decentralized statement verification system.
+
+## Installation
+
+```bash
+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
+  - Polls and votes
+  - Organisation and person verifications
+  - Disputes (authenticity and content)
+  - Ratings
+  - PDF signing
+  - Responses
+- **Type Safety**: Full TypeScript support with comprehensive type definitions
+- **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
+
+### Basic Statement
+
+```typescript
+import { buildStatement, parseStatement } from 'stated-protocol-parser';
+
+// Build a statement
+const statement = buildStatement({
+  domain: 'example.com',
+  author: 'Example Organization',
+  time: new Date(),
+  tags: ['announcement', 'update'],
+  content: 'This is our official statement.',
+});
+
+// Parse a statement
+const parsed = parseStatement({ statement });
+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
+import { buildPollContent, parsePoll } from 'stated-protocol-parser';
+
+const pollContent = buildPollContent({
+  poll: 'Should we implement feature X?',
+  options: ['Yes', 'No', 'Need more information'],
+  deadline: new Date('2024-12-31'),
+  scopeDescription: 'All registered users',
+});
+
+const parsed = parsePoll(pollContent);
+```
+
+### Organisation Verification
+
+```typescript
+import { buildOrganisationVerificationContent, parseOrganisationVerification } from 'stated-protocol-parser';
+
+const verification = buildOrganisationVerificationContent({
+  name: 'Example Corp',
+  country: 'United States',
+  city: 'New York',
+  legalForm: 'corporation',
+  domain: 'example.com',
+  // ... other fields
+});
+```
+
+### Person Verification
+
+```typescript
+import { buildPersonVerificationContent, parsePersonVerification } from 'stated-protocol-parser';
+
+const verification = buildPersonVerificationContent({
+  name: 'John Doe',
+  dateOfBirth: new Date('1990-01-01'),
+  cityOfBirth: 'New York',
+  countryOfBirth: 'United States',
+  ownDomain: 'johndoe.com',
+  // ... other fields
+});
+```
+
+## API Reference
+
+### Statement Functions
+
+- `buildStatement(params)` - Build a statement string
+- `parseStatement({ statement })` - Parse a statement string
+
+### Content Type Functions
+
+Each content type has corresponding build and parse functions:
+
+- **Poll**: `buildPollContent()`, `parsePoll()`
+- **Vote**: `buildVoteContent()`, `parseVote()`
+- **Organisation Verification**: `buildOrganisationVerificationContent()`, `parseOrganisationVerification()`
+- **Person Verification**: `buildPersonVerificationContent()`, `parsePersonVerification()`
+- **Dispute Authenticity**: `buildDisputeAuthenticityContent()`, `parseDisputeAuthenticity()`
+- **Dispute Content**: `buildDisputeContentContent()`, `parseDisputeContent()`
+- **Response**: `buildResponseContent()`, `parseResponseContent()`
+- **PDF Signing**: `buildPDFSigningContent()`, `parsePDFSigning()`
+- **Rating**: `buildRating()`, `parseRating()`
+
+### Constants
+
+```typescript
+import { 
+  statementTypes,
+  legalForms,
+  peopleCountBuckets,
+  UTCFormat 
+} from 'stated-protocol-parser';
+```
+
+### Types
+
+All TypeScript types are exported:
+
+```typescript
+import type {
+  Statement,
+  Poll,
+  OrganisationVerification,
+  PersonVerification,
+  Vote,
+  DisputeAuthenticity,
+  DisputeContent,
+  ResponseContent,
+  PDFSigning,
+  Rating
+} from 'stated-protocol-parser';
+```
+
+## Format Specifications
+
+### Statement Format
+
+Statements follow a specific format with required fields:
+- Publishing domain
+- Author
+- Time (UTC format)
+- Format version
+- Statement content
+
+Optional fields:
+- Authorized signing representative
+- Tags
+- Superseded statement
+- Translations (multi-language support)
+- Attachments (up to 5 file references)
+
+### Validation Rules
+
+- Statements must not exceed 3,000 characters
+- Statements cannot contain double line breaks (`\n\n`)
+- Time must be in UTC format
+- Domain, author, and content are required fields
+
+## Version Support
+
+The library supports version 5 format with cryptographic signature support using Ed25519.
+
+## Error Handling
+
+All parse functions throw descriptive errors when encountering invalid formats:
+
+```typescript
+try {
+  const parsed = parseStatement({ statement: invalidStatement });
+} catch (error) {
+  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

@@ -0,0 +1,225 @@
+export declare const legalForms: {
+    local_government: string;
+    state_government: string;
+    foreign_affairs_ministry: string;
+    corporation: string;
+};
+export declare const statementTypes: {
+    statement: string;
+    organisationVerification: string;
+    personVerification: string;
+    poll: string;
+    vote: string;
+    response: string;
+    disputeContent: string;
+    disputeAuthenticity: string;
+    rating: string;
+    signPdf: string;
+    unsupported: string;
+};
+export declare const peopleCountBuckets: {
+    '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;
+export declare const personVerificationKeys: RegExp;
+export declare const voteKeys: RegExp;
+export declare const disputeAuthenticityKeys: RegExp;
+export declare const disputeContentKeys: RegExp;
+export declare const responseKeys: RegExp;
+export declare const PDFSigningKeys: RegExp;
+export declare const ratingKeys: RegExp;
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"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"}