stated-protocol 5.0.0

package/src/rating.test.ts

@@ -0,0 +1,25 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { parseRating, buildRating } from './protocol';
+
+const randomUnicodeString = () =>
+  Array.from({ length: 20 }, () => String.fromCharCode(Math.floor(Math.random() * 65536)))
+    .join('')
+    .replace(/[\n;>=<"''\\]/g, '');
+
+describe('Rating building', () => {
+  it('build & parse function compatibility: input=parse(build(input))', () => {
+    const [subjectName, subjectReference, comment, quality] = Array.from(
+      { length: 4 },
+      randomUnicodeString
+    );
+    const rating = Math.ceil(Math.random() * 5);
+    const ratingContent = buildRating({ subjectName, subjectReference, rating, comment, quality });
+    const parsedRating = parseRating(ratingContent);
+    assert.strictEqual(parsedRating.subjectName, subjectName);
+    assert.strictEqual(parsedRating.subjectReference, subjectReference);
+    assert.strictEqual(parsedRating.quality, quality);
+    assert.strictEqual(parsedRating.rating, rating);
+    assert.strictEqual(parsedRating.comment, comment);
+  });
+});

package/src/signature.test.ts

@@ -0,0 +1,200 @@
+import { describe, it, before } from 'node:test';
+import assert from 'node:assert';
+import {
+  generateKeyPair,
+  signStatement,
+  verifySignature,
+  buildSignedStatement,
+  parseSignedStatement,
+  verifySignedStatement,
+} from './signature';
+import { buildStatement, parseStatement } from './protocol';
+
+describe('Signature Functions', () => {
+  let publicKey: string;
+  let privateKey: string;
+  const testStatement = `Stated protocol version: 5
+Publishing domain: example.com
+Author: Test Author
+Time: Thu, 15 Jun 2023 20:01:26 GMT
+Statement content:
+This is a test statement
+`;
+
+  before(async () => {
+    const keys = await generateKeyPair();
+    publicKey = keys.publicKey;
+    privateKey = keys.privateKey;
+  });
+
+  describe('generateKeyPair', () => {
+    it('should generate a valid Ed25519 key pair in URL-safe base64', async () => {
+      const keys = await generateKeyPair();
+      assert.ok(keys.publicKey);
+      assert.ok(keys.privateKey);
+      assert.ok(/^[A-Za-z0-9_-]+$/.test(keys.publicKey));
+      assert.ok(/^[A-Za-z0-9_-]+$/.test(keys.privateKey));
+    });
+  });
+
+  describe('signStatement', () => {
+    it('should sign a statement and return URL-safe base64 signature', async () => {
+      const signature = await signStatement(testStatement, privateKey);
+      assert.ok(signature);
+      assert.strictEqual(typeof signature, 'string');
+      assert.ok(/^[A-Za-z0-9_-]+$/.test(signature));
+    });
+  });
+
+  describe('verifySignature', () => {
+    it('should verify a valid signature', async () => {
+      const signature = await signStatement(testStatement, privateKey);
+      const isValid = await verifySignature(testStatement, signature, publicKey);
+      assert.strictEqual(isValid, true);
+    });
+
+    it('should reject an invalid signature', async () => {
+      const signature = await signStatement(testStatement, privateKey);
+      const tamperedStatement = testStatement.replace('Test Author', 'Hacker');
+      const isValid = await verifySignature(tamperedStatement, signature, publicKey);
+      assert.strictEqual(isValid, false);
+    });
+
+    it('should reject a signature with wrong public key', async () => {
+      const signature = await signStatement(testStatement, privateKey);
+      const { publicKey: wrongPublicKey } = await generateKeyPair();
+      const isValid = await verifySignature(testStatement, signature, wrongPublicKey);
+      assert.strictEqual(isValid, false);
+    });
+  });
+
+  describe('buildSignedStatement', () => {
+    it('should build a properly formatted signed statement', async () => {
+      const signedStatement = await buildSignedStatement(testStatement, privateKey, publicKey);
+      assert.ok(signedStatement.includes(testStatement));
+      assert.ok(signedStatement.includes('---'));
+      assert.ok(signedStatement.includes('Statement hash:'));
+      assert.ok(signedStatement.includes('Public key:'));
+      assert.ok(signedStatement.includes('Signature:'));
+      assert.ok(signedStatement.includes('Algorithm: Ed25519'));
+      assert.ok(signedStatement.includes(publicKey));
+    });
+  });
+
+  describe('parseSignedStatement', () => {
+    it('should parse a valid signed statement', async () => {
+      const signedStatement = await buildSignedStatement(testStatement, privateKey, publicKey);
+      const parsed = parseSignedStatement(signedStatement);
+
+      assert.ok(parsed !== null);
+      assert.strictEqual(parsed?.statement, testStatement);
+      assert.ok(parsed?.statementHash);
+      assert.strictEqual(parsed?.publicKey, publicKey);
+      assert.ok(parsed?.signature);
+      assert.strictEqual(parsed?.algorithm, 'Ed25519');
+    });
+
+    it('should return null for invalid format', () => {
+      const invalidStatement = 'This is not a signed statement';
+      const parsed = parseSignedStatement(invalidStatement);
+      assert.strictEqual(parsed, null);
+    });
+
+    it('should reject statement with tampered hash', async () => {
+      const signedStatement = await buildSignedStatement(testStatement, privateKey, publicKey);
+      const tamperedStatement = signedStatement.replace(
+        /Statement hash: [A-Za-z0-9_-]+/,
+        'Statement hash: invalid_hash_here'
+      );
+      const parsed = parseSignedStatement(tamperedStatement);
+      assert.strictEqual(parsed, null);
+    });
+
+    it('should reject statement with unsupported algorithm', async () => {
+      const signedStatement = await buildSignedStatement(testStatement, privateKey, publicKey);
+      const tamperedStatement = signedStatement.replace('Algorithm: Ed25519', 'Algorithm: RSA');
+      const parsed = parseSignedStatement(tamperedStatement);
+      assert.strictEqual(parsed, null);
+    });
+  });
+
+  describe('verifySignedStatement', () => {
+    it('should verify a valid signed statement', async () => {
+      const signedStatement = await buildSignedStatement(testStatement, privateKey, publicKey);
+      const isValid = await verifySignedStatement(signedStatement);
+      assert.strictEqual(isValid, true);
+    });
+
+    it('should reject a tampered signed statement', async () => {
+      const signedStatement = await buildSignedStatement(testStatement, privateKey, publicKey);
+      const tamperedStatement = signedStatement.replace('Test Author', 'Hacker');
+      const isValid = await verifySignedStatement(tamperedStatement);
+      assert.strictEqual(isValid, false);
+    });
+  });
+
+  describe('Integration with buildStatement and parseStatement', () => {
+    it('should work with statements built using buildStatement', async () => {
+      const statement = buildStatement({
+        domain: 'example.com',
+        author: 'Test Author',
+        time: new Date('2023-06-15T20:01:26Z'),
+        content: 'This is a test statement',
+      });
+
+      const signedStatement = await buildSignedStatement(statement, privateKey, publicKey);
+      const isValid = await verifySignedStatement(signedStatement);
+      assert.strictEqual(isValid, true);
+
+      const parsed = parseSignedStatement(signedStatement);
+      assert.strictEqual(parsed?.statement, statement);
+    });
+
+    it('should automatically verify signature when parsing with parseStatement', async () => {
+      const statement = buildStatement({
+        domain: 'example.com',
+        author: 'Test Author',
+        time: new Date('2023-06-15T20:01:26Z'),
+        content: 'This is a test statement',
+      });
+
+      const signedStatement = await buildSignedStatement(statement, privateKey, publicKey);
+
+      const parsed = parseStatement({ statement: signedStatement });
+      assert.strictEqual(parsed.domain, 'example.com');
+      assert.strictEqual(parsed.author, 'Test Author');
+      assert.strictEqual(parsed.content, 'This is a test statement');
+    });
+
+    it('should reject tampered signed statement in parseStatement', async () => {
+      const statement = buildStatement({
+        domain: 'example.com',
+        author: 'Test Author',
+        time: new Date('2023-06-15T20:01:26Z'),
+        content: 'This is a test statement',
+      });
+
+      const signedStatement = await buildSignedStatement(statement, privateKey, publicKey);
+      const tamperedStatement = signedStatement.replace('Test Author', 'Hacker');
+
+      assert.throws(() => {
+        parseStatement({ statement: tamperedStatement });
+      }, /Statement hash mismatch|Invalid cryptographic signature/);
+    });
+
+    it('should still parse unsigned statements (backward compatibility)', () => {
+      const statement = buildStatement({
+        domain: 'example.com',
+        author: 'Test Author',
+        time: new Date('2023-06-15T20:01:26Z'),
+        content: 'This is a test statement',
+      });
+
+      // Should parse successfully without signature
+      const parsed = parseStatement({ statement });
+      assert.strictEqual(parsed.domain, 'example.com');
+      assert.strictEqual(parsed.author, 'Test Author');
+      assert.strictEqual(parsed.content, 'This is a test statement');
+    });
+  });
+});

package/src/signature.ts

@@ -0,0 +1,159 @@
+/**
+ * Universal signature utilities using @noble/ed25519
+ * Works in both browser and Node.js environments
+ */
+
+import * as ed from '@noble/ed25519';
+import { sha512 } from '@noble/hashes/sha2.js';
+import { toUrlSafeBase64, fromUrlSafeBase64, sha256, base64ToBytes } from './hash';
+import type { CryptographicallySignedStatement } from './types';
+
+// Set up sha512 for @noble/ed25519
+ed.hashes.sha512 = (message: Uint8Array) => sha512(message);
+
+const ALGORITHM = 'Ed25519'; // Fully specifies: EdDSA signature scheme with Curve25519
+
+/**
+ * Generate a new Ed25519 key pair for signing statements
+ * @returns Object containing publicKey and privateKey as URL-safe base64
+ */
+export const generateKeyPair = async (): Promise<{ publicKey: string; privateKey: string }> => {
+  const privateKey = ed.utils.randomSecretKey();
+  const publicKey = await ed.getPublicKey(privateKey);
+
+  return {
+    publicKey: toUrlSafeBase64(bytesToBase64(publicKey)),
+    privateKey: toUrlSafeBase64(bytesToBase64(privateKey)),
+  };
+};
+
+/**
+ * Sign a statement with a private key
+ * @param statement - The statement text to sign
+ * @param privateKeyUrlSafe - Private key in URL-safe base64 format
+ * @returns URL-safe base64-encoded signature
+ */
+export const signStatement = async (
+  statement: string,
+  privateKeyUrlSafe: string
+): Promise<string> => {
+  const privateKeyBytes = base64ToBytes(fromUrlSafeBase64(privateKeyUrlSafe));
+  const messageBytes = new TextEncoder().encode(statement);
+
+  const signature = await ed.sign(messageBytes, privateKeyBytes);
+
+  return toUrlSafeBase64(bytesToBase64(signature));
+};
+
+/**
+ * Verify a statement signature
+ * @param statement - The statement text that was signed
+ * @param signatureUrlSafe - URL-safe base64-encoded signature
+ * @param publicKeyUrlSafe - Public key in URL-safe base64 format
+ * @returns true if signature is valid, false otherwise
+ */
+export const verifySignature = async (
+  statement: string,
+  signatureUrlSafe: string,
+  publicKeyUrlSafe: string
+): Promise<boolean> => {
+  try {
+    const publicKeyBytes = base64ToBytes(fromUrlSafeBase64(publicKeyUrlSafe));
+    const signatureBytes = base64ToBytes(fromUrlSafeBase64(signatureUrlSafe));
+    const messageBytes = new TextEncoder().encode(statement);
+
+    return await ed.verify(signatureBytes, messageBytes, publicKeyBytes);
+  } catch (error) {
+    return false;
+  }
+};
+
+/**
+ * Build a signed statement
+ * @param statement - The statement text to sign
+ * @param privateKeyUrlSafe - Private key in URL-safe base64 format
+ * @param publicKeyUrlSafe - Public key in URL-safe base64 format
+ * @returns Signed statement with appended signature fields
+ */
+export const buildSignedStatement = async (
+  statement: string,
+  privateKeyUrlSafe: string,
+  publicKeyUrlSafe: string
+): Promise<string> => {
+  const statementHash = sha256(statement);
+  const signature = await signStatement(statement, privateKeyUrlSafe);
+  return (
+    statement +
+    `---\n` +
+    `Statement hash: ${statementHash}\n` +
+    `Public key: ${publicKeyUrlSafe}\n` +
+    `Signature: ${signature}\n` +
+    `Algorithm: ${ALGORITHM}\n`
+  );
+};
+
+/**
+ * Parse a signed statement
+ * @param signedStatement - The signed statement text
+ * @returns Parsed CryptographicallySignedStatement object or null if invalid
+ */
+export const parseSignedStatement = (
+  signedStatement: string
+): CryptographicallySignedStatement | null => {
+  const regex =
+    /^([\s\S]+?)---\nStatement hash: ([A-Za-z0-9_-]+)\nPublic key: ([A-Za-z0-9_-]+)\nSignature: ([A-Za-z0-9_-]+)\nAlgorithm: ([^\n]+)\n$/;
+  const match = signedStatement.match(regex);
+
+  if (!match) return null;
+
+  const statement = match[1];
+  const statementHash = match[2];
+  const publicKey = match[3];
+  const signature = match[4];
+  const algorithm = match[5];
+
+  // Verify statement hash matches
+  const computedHash = sha256(statement);
+  if (computedHash !== statementHash) {
+    return null;
+  }
+
+  // Verify algorithm is supported
+  if (algorithm !== ALGORITHM) {
+    return null;
+  }
+
+  return {
+    statement,
+    publicKey,
+    signature,
+    statementHash,
+    algorithm,
+  };
+};
+
+/**
+ * Verify a signed statement
+ * @param signedStatement - The signed statement text
+ * @returns true if signature is valid, false otherwise
+ */
+export const verifySignedStatement = async (signedStatement: string): Promise<boolean> => {
+  const parsed = parseSignedStatement(signedStatement);
+  if (!parsed) return false;
+
+  return await verifySignature(parsed.statement, parsed.signature, parsed.publicKey);
+};
+
+/**
+ * Convert bytes to base64 string
+ * @param bytes - Uint8Array to convert
+ * @returns Base64 string
+ */
+function bytesToBase64(bytes: Uint8Array): string {
+  // Use btoa if available (browser), otherwise use Buffer (Node.js)
+  if (typeof btoa !== 'undefined') {
+    return btoa(String.fromCharCode(...Array.from(bytes)));
+  } else {
+    return Buffer.from(bytes).toString('base64');
+  }
+}

package/src/statement.test.ts

@@ -0,0 +1,101 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { parseStatement, buildStatement } from './protocol';
+
+const randomUnicodeString = () =>
+  Array.from({ length: 20 }, () => String.fromCharCode(Math.floor(Math.random() * 65536)))
+    .join('')
+    .replace(/[\n;>=<"''\\]/g, '');
+
+describe('Statement building', () => {
+  it('build & parse function compatibility: input=parse(build(input))', () => {
+    const [domain, author, representative, content, supersededStatement] = Array.from(
+      { length: 5 },
+      randomUnicodeString
+    );
+    const tags = Array.from({ length: 4 }, randomUnicodeString);
+    const contentWithTrailingNewline = content + (content.match(/\n$/) ? '' : '\n');
+    const time = new Date('Sun, 04 Sep 2022 14:48:50 GMT');
+    const statementContent = buildStatement({
+      domain,
+      author,
+      time,
+      content: contentWithTrailingNewline,
+      representative,
+      supersededStatement,
+      tags,
+    });
+    const parsedStatement = parseStatement({ statement: statementContent });
+    assert.strictEqual(parsedStatement.domain, domain);
+    assert.strictEqual(parsedStatement.author, author);
+    assert.strictEqual(parsedStatement.time?.toUTCString(), time.toUTCString());
+    assert.strictEqual(parsedStatement.content, content);
+    assert.strictEqual(parsedStatement.representative, representative);
+    assert.strictEqual(parsedStatement.supersededStatement, supersededStatement);
+    assert.deepStrictEqual(parsedStatement.tags?.sort(), tags.sort());
+  });
+  it('build & parse statement with attachments', () => {
+    const domain = 'example.com';
+    const author = 'Test Author';
+    const time = new Date('Thu, 15 Jun 2023 20:01:26 GMT');
+    const content = 'Statement with attachments';
+    const attachments = ['abc123_-XYZ.pdf', 'def456-_ABC.jpg', 'xyz789_hash.docx'];
+
+    const statementContent = buildStatement({
+      domain,
+      author,
+      time,
+      content,
+      attachments,
+    });
+
+    const parsedStatement = parseStatement({ statement: statementContent });
+    assert.strictEqual(parsedStatement.domain, domain);
+    assert.strictEqual(parsedStatement.author, author);
+    assert.strictEqual(parsedStatement.content, content);
+    assert.deepStrictEqual(parsedStatement.attachments, attachments);
+  });
+
+  it('reject statement with more than 5 attachments', () => {
+    const domain = 'example.com';
+    const author = 'Test Author';
+    const time = new Date();
+    const content = 'Too many attachments\n';
+    const attachments = [
+      'hash1.pdf',
+      'hash2.pdf',
+      'hash3.pdf',
+      'hash4.pdf',
+      'hash5.pdf',
+      'hash6.pdf',
+    ];
+
+    assert.throws(() => {
+      buildStatement({
+        domain,
+        author,
+        time,
+        content,
+        attachments,
+      });
+    }, /Maximum 5 attachments allowed/);
+  });
+
+  it('reject attachment with invalid format', () => {
+    const domain = 'example.com';
+    const author = 'Test Author';
+    const time = new Date();
+    const content = 'Invalid attachment\n';
+    const attachments = ['invalid file name.pdf'];
+
+    assert.throws(() => {
+      buildStatement({
+        domain,
+        author,
+        time,
+        content,
+        attachments,
+      });
+    }, /Attachment 1 must be in format 'base64hash.extension' \(URL-safe base64\)/);
+  });
+});

package/src/types.ts

@@ -0,0 +1,185 @@
+import type { SupportedLanguage } from './constants';
+
+export type LegalForm =
+  | 'local government'
+  | 'state government'
+  | 'foreign affairs ministry'
+  | 'corporation';
+
+export type PeopleCountBucket =
+  | '0-10'
+  | '10-100'
+  | '100-1000'
+  | '1000-10,000'
+  | '10,000-100,000'
+  | '100,000+'
+  | '1,000,000+'
+  | '10,000,000+';
+
+// Type guards
+export function isLegalForm(value: string): value is LegalForm {
+  return [
+    'local government',
+    'state government',
+    'foreign affairs ministry',
+    'corporation',
+  ].includes(value);
+}
+
+export function isPeopleCountBucket(value: string): value is PeopleCountBucket {
+  return [
+    '0-10',
+    '10-100',
+    '100-1000',
+    '1000-10,000',
+    '10,000-100,000',
+    '100,000+',
+    '1,000,000+',
+    '10,000,000+',
+  ].includes(value);
+}
+
+export function isRatingValue(value: number): value is RatingValue {
+  return [1, 2, 3, 4, 5].includes(value);
+}
+
+export type StatementTypeValue =
+  | 'statement'
+  | 'organisation_verification'
+  | 'person_verification'
+  | 'poll'
+  | 'vote'
+  | 'response'
+  | 'dispute_statement_content'
+  | 'dispute_statement_authenticity'
+  | 'rating'
+  | 'sign_pdf';
+
+export type Statement = {
+  domain: string;
+  author: string;
+  time: Date;
+  tags?: string[];
+  content: string;
+  representative?: string;
+  supersededStatement?: string;
+  formatVersion?: string;
+  translations?: Partial<Record<SupportedLanguage, string>>;
+  attachments?: string[];
+};
+
+export type CryptographicallySignedStatement = {
+  statement: string;
+  statementHash: string;
+  publicKey: string;
+  signature: string;
+  algorithm: string;
+};
+
+export type Poll = {
+  deadline: Date | undefined;
+  poll: string;
+  scopeDescription?: string;
+  options: string[];
+  allowArbitraryVote?: boolean;
+};
+
+export type OrganisationVerification = {
+  name: string;
+  englishName?: string;
+  country: string;
+  city?: string;
+  province?: string;
+  legalForm: LegalForm;
+  department?: string;
+  domain: string;
+  foreignDomain?: string;
+  serialNumber?: string;
+  confidence?: number;
+  reliabilityPolicy?: string;
+  employeeCount?: PeopleCountBucket;
+  pictureHash?: string;
+  latitude?: number;
+  longitude?: number;
+  population?: PeopleCountBucket;
+  publicKey?: string;
+};
+
+export type withOwnDomain = {
+  ownDomain: string;
+  foreignDomain?: string;
+};
+
+export type withForeignDomain = {
+  foreignDomain: string;
+  ownDomain?: string;
+};
+
+export type PersonVerification = {
+  name: string;
+  countryOfBirth: string;
+  cityOfBirth: string;
+  dateOfBirth: Date;
+  jobTitle?: string;
+  employer?: string;
+  verificationMethod?: string;
+  confidence?: number;
+  picture?: string;
+  reliabilityPolicy?: string;
+  publicKey?: string;
+} & (withOwnDomain | withForeignDomain);
+
+export type Vote = {
+  pollHash: string;
+  poll: string;
+  vote: string;
+};
+
+export type DisputeAuthenticity = {
+  hash: string;
+  confidence?: number;
+  reliabilityPolicy?: string;
+};
+
+export type DisputeContent = {
+  hash: string;
+  confidence?: number;
+  reliabilityPolicy?: string;
+};
+
+export type ResponseContent = {
+  hash: string;
+  response: string;
+};
+
+export type PDFSigning = {
+  hash: string;
+};
+
+export type RatingSubjectTypeValue =
+  | 'Organisation'
+  | 'Policy proposal'
+  | 'Treaty draft'
+  | 'Research publication'
+  | 'Regulation'
+  | 'Product';
+
+export type RatingValue = 1 | 2 | 3 | 4 | 5;
+
+export type Rating = {
+  subjectType?: RatingSubjectTypeValue;
+  subjectName: string;
+  subjectReference?: string;
+  documentFileHash?: string;
+  rating: RatingValue;
+  quality?: string;
+  comment?: string;
+};
+
+export type Bounty = {
+  motivation?: string;
+  bounty: string;
+  reward: string;
+  judge: string;
+  judgePay?: string;
+};