stated-protocol 5.0.0

package/src/constants.ts

@@ -0,0 +1,245 @@
+export const legalForms = {
+  local_government: 'local government',
+  state_government: 'state government',
+  foreign_affairs_ministry: 'foreign affairs ministry',
+  corporation: 'corporation',
+};
+
+export const statementTypes = {
+  statement: 'statement',
+  organisationVerification: 'organisation_verification',
+  personVerification: 'person_verification',
+  poll: 'poll',
+  vote: 'vote',
+  response: 'response',
+  disputeContent: 'dispute_statement_content',
+  disputeAuthenticity: 'dispute_statement_authenticity',
+  rating: 'rating',
+  signPdf: 'sign_pdf',
+  unsupported: 'unsupported',
+};
+
+export const peopleCountBuckets = {
+  '0': '0-10',
+  '10': '10-100',
+  '100': '100-1000',
+  '1000': '1000-10,000',
+  '10000': '10,000-100,000',
+  '100000': '100,000+',
+  '1000000': '1,000,000+',
+  '10000000': '10,000,000+',
+};
+
+export const supportedLanguages = {
+  aa: 'aa',
+  ab: 'ab',
+  af: 'af',
+  ak: 'ak',
+  am: 'am',
+  ar: 'ar',
+  an: 'an',
+  as: 'as',
+  av: 'av',
+  ay: 'ay',
+  az: 'az',
+  ba: 'ba',
+  bm: 'bm',
+  be: 'be',
+  bn: 'bn',
+  bi: 'bi',
+  bo: 'bo',
+  bs: 'bs',
+  br: 'br',
+  bg: 'bg',
+  ca: 'ca',
+  cs: 'cs',
+  ch: 'ch',
+  ce: 'ce',
+  cv: 'cv',
+  kw: 'kw',
+  co: 'co',
+  cr: 'cr',
+  cy: 'cy',
+  da: 'da',
+  de: 'de',
+  dv: 'dv',
+  dz: 'dz',
+  el: 'el',
+  en: 'en',
+  eo: 'eo',
+  et: 'et',
+  eu: 'eu',
+  ee: 'ee',
+  fo: 'fo',
+  fa: 'fa',
+  fj: 'fj',
+  fi: 'fi',
+  fr: 'fr',
+  fy: 'fy',
+  ff: 'ff',
+  gd: 'gd',
+  ga: 'ga',
+  gl: 'gl',
+  gv: 'gv',
+  gn: 'gn',
+  gu: 'gu',
+  ht: 'ht',
+  ha: 'ha',
+  sh: 'sh',
+  he: 'he',
+  hz: 'hz',
+  hi: 'hi',
+  ho: 'ho',
+  hr: 'hr',
+  hu: 'hu',
+  hy: 'hy',
+  ig: 'ig',
+  io: 'io',
+  ii: 'ii',
+  iu: 'iu',
+  ie: 'ie',
+  ia: 'ia',
+  id: 'id',
+  ik: 'ik',
+  is: 'is',
+  it: 'it',
+  jv: 'jv',
+  ja: 'ja',
+  kl: 'kl',
+  kn: 'kn',
+  ks: 'ks',
+  ka: 'ka',
+  kr: 'kr',
+  kk: 'kk',
+  km: 'km',
+  ki: 'ki',
+  rw: 'rw',
+  ky: 'ky',
+  kv: 'kv',
+  kg: 'kg',
+  ko: 'ko',
+  kj: 'kj',
+  ku: 'ku',
+  lo: 'lo',
+  la: 'la',
+  lv: 'lv',
+  li: 'li',
+  ln: 'ln',
+  lt: 'lt',
+  lb: 'lb',
+  lu: 'lu',
+  lg: 'lg',
+  mh: 'mh',
+  ml: 'ml',
+  mr: 'mr',
+  mk: 'mk',
+  mg: 'mg',
+  mt: 'mt',
+  mn: 'mn',
+  mi: 'mi',
+  ms: 'ms',
+  my: 'my',
+  na: 'na',
+  nv: 'nv',
+  nr: 'nr',
+  nd: 'nd',
+  ng: 'ng',
+  ne: 'ne',
+  nl: 'nl',
+  nn: 'nn',
+  nb: 'nb',
+  no: 'no',
+  ny: 'ny',
+  oc: 'oc',
+  oj: 'oj',
+  or: 'or',
+  om: 'om',
+  os: 'os',
+  pa: 'pa',
+  pi: 'pi',
+  pl: 'pl',
+  pt: 'pt',
+  ps: 'ps',
+  qu: 'qu',
+  rm: 'rm',
+  ro: 'ro',
+  rn: 'rn',
+  ru: 'ru',
+  sg: 'sg',
+  sa: 'sa',
+  si: 'si',
+  sk: 'sk',
+  sl: 'sl',
+  se: 'se',
+  sm: 'sm',
+  sn: 'sn',
+  sd: 'sd',
+  so: 'so',
+  st: 'st',
+  es: 'es',
+  sq: 'sq',
+  sc: 'sc',
+  sr: 'sr',
+  ss: 'ss',
+  su: 'su',
+  sw: 'sw',
+  sv: 'sv',
+  ty: 'ty',
+  ta: 'ta',
+  tt: 'tt',
+  te: 'te',
+  tg: 'tg',
+  tl: 'tl',
+  th: 'th',
+  ti: 'ti',
+  to: 'to',
+  tn: 'tn',
+  ts: 'ts',
+  tk: 'tk',
+  tr: 'tr',
+  tw: 'tw',
+  ug: 'ug',
+  uk: 'uk',
+  ur: 'ur',
+  uz: 'uz',
+  ve: 've',
+  vi: 'vi',
+  vo: 'vo',
+  wa: 'wa',
+  wo: 'wo',
+  xh: 'xh',
+  yi: 'yi',
+  yo: 'yo',
+  za: 'za',
+  zh: 'zh',
+  zu: 'zu',
+} as const;
+
+export type SupportedLanguage = (typeof supportedLanguages)[keyof typeof supportedLanguages];
+
+export const UTCFormat: RegExp =
+  /(Mon|Tue|Wed|Thu|Fri|Sat|Sun),\s\d{2}\s(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s\d{4}\s\d{2}:\d{2}:\d{2}\sGMT/;
+
+export const pollKeys =
+  /(Type: |The poll outcome is finalized when the following nodes agree: |Voting deadline: |Poll: |Option 1: |Option 2: |Option 3: |Option 4: |Option 5: |Allow free text votes: |Who can vote: |Description: |Country scope: |City scope: |Legal form scope: |Domain scope: |All entities with the following property: |As observed by: |Link to query defining who can vote: )/g;
+
+export const organisationVerificationKeys =
+  /(Type: |Description: |Name: |English name: |Country: |Legal entity: |Legal form: |Department using the domain: |Owner of the domain: |Foreign domain used for publishing statements: |Province or state: |Business register number: |City: |Longitude: |Latitude: |Population: |Logo: |Employee count: |Reliability policy: |Confidence: |Public key: )/g;
+
+export const personVerificationKeys =
+  /(Type: |Description: |Name: |Date of birth: |City of birth: |Country of birth: |Job title: |Employer: |Owner of the domain: |Foreign domain used for publishing statements: |Picture: |Verification method: |Confidence: |Reliability policy: )/g;
+
+export const voteKeys = /(Type: |Poll id: |Poll: |Option: )/g;
+
+export const disputeAuthenticityKeys =
+  /(Type: |Description: |Hash of referenced statement: |Confidence: |Reliability policy: )/g;
+
+export const disputeContentKeys =
+  /(Type: |Description: |Hash of referenced statement: |Confidence: |Reliability policy: )/g;
+
+export const responseKeys = /(Type: |Hash of referenced statement: |Response: )/;
+
+export const PDFSigningKeys = /(Type: |Description: |PDF file hash: )/g;
+
+export const ratingKeys =
+  /(Type: |Subject type: |Subject name: |URL that identifies the subject: |Document file hash: |Rated quality: |Our rating: |Comment: )/;

package/src/fixtures.test.ts

@@ -0,0 +1,236 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import {
+  buildStatement,
+  parseStatement,
+  buildPollContent,
+  buildVoteContent,
+  buildOrganisationVerificationContent,
+  buildPersonVerificationContent,
+  buildDisputeAuthenticityContent,
+  buildDisputeContentContent,
+  buildResponseContent,
+  buildPDFSigningContent,
+  buildRating,
+} from './protocol';
+import { verifySignedStatement } from './signature';
+
+// ESM-compatible __dirname
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const fixturesDir = path.join(__dirname, '../fixtures');
+
+function getFixtureDirs(): string[] {
+  if (!fs.existsSync(fixturesDir)) {
+    return [];
+  }
+  return fs
+    .readdirSync(fixturesDir, { withFileTypes: true })
+    .filter((dirent) => dirent.isDirectory())
+    .map((dirent) => dirent.name);
+}
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+function buildContentFromInput(contentObj: any): string {
+  if (!contentObj || typeof contentObj !== 'object') {
+    throw new Error('Content must be an object with a type field');
+  }
+
+  switch (contentObj.type) {
+    case 'poll':
+      return buildPollContent({
+        poll: contentObj.poll,
+        options: contentObj.options || [],
+        deadline: contentObj.deadline ? new Date(contentObj.deadline) : undefined,
+        scopeDescription: contentObj.scopeDescription,
+        allowArbitraryVote: contentObj.allowArbitraryVote,
+      });
+    case 'vote':
+      return buildVoteContent({
+        pollHash: contentObj.pollHash,
+        poll: contentObj.poll,
+        vote: contentObj.vote,
+      });
+    case 'organisation_verification':
+      return buildOrganisationVerificationContent({
+        name: contentObj.name,
+        englishName: contentObj.englishName,
+        country: contentObj.country,
+        city: contentObj.city,
+        province: contentObj.province,
+        legalForm: contentObj.legalForm,
+        department: contentObj.department,
+        domain: contentObj.domain,
+        foreignDomain: contentObj.foreignDomain,
+        serialNumber: contentObj.serialNumber,
+        confidence: contentObj.confidence,
+        reliabilityPolicy: contentObj.reliabilityPolicy,
+        employeeCount: contentObj.employeeCount,
+        pictureHash: contentObj.pictureHash,
+        latitude: contentObj.latitude,
+        longitude: contentObj.longitude,
+        population: contentObj.population,
+        publicKey: contentObj.publicKey,
+      });
+    case 'person_verification':
+      return buildPersonVerificationContent({
+        name: contentObj.name,
+        countryOfBirth: contentObj.countryOfBirth,
+        cityOfBirth: contentObj.cityOfBirth,
+        ownDomain: contentObj.ownDomain,
+        foreignDomain: contentObj.foreignDomain,
+        dateOfBirth: new Date(contentObj.dateOfBirth),
+        jobTitle: contentObj.jobTitle,
+        employer: contentObj.employer,
+        verificationMethod: contentObj.verificationMethod,
+        confidence: contentObj.confidence,
+        picture: contentObj.picture,
+        reliabilityPolicy: contentObj.reliabilityPolicy,
+        publicKey: contentObj.publicKey,
+      });
+    case 'dispute_authenticity':
+      return buildDisputeAuthenticityContent({
+        hash: contentObj.hash,
+        confidence: contentObj.confidence,
+        reliabilityPolicy: contentObj.reliabilityPolicy,
+      });
+    case 'dispute_content':
+      return buildDisputeContentContent({
+        hash: contentObj.hash,
+        confidence: contentObj.confidence,
+        reliabilityPolicy: contentObj.reliabilityPolicy,
+      });
+    case 'response':
+      return buildResponseContent({
+        hash: contentObj.hash,
+        response: contentObj.response,
+      });
+    case 'pdf_signing':
+      return buildPDFSigningContent({
+        hash: contentObj.hash,
+      });
+    case 'rating':
+      return buildRating({
+        subjectName: contentObj.subjectName,
+        subjectType: contentObj.subjectType,
+        subjectReference: contentObj.subjectReference,
+        documentFileHash: contentObj.documentFileHash,
+        rating: contentObj.rating,
+        quality: contentObj.quality,
+        comment: contentObj.comment,
+      });
+    default:
+      throw new Error(`Unknown content type: ${contentObj.type}`);
+  }
+}
+
+describe('Fixture Validation', () => {
+  const fixtureDirs = getFixtureDirs();
+
+  if (fixtureDirs.length === 0) {
+    it('no fixtures found', () => {
+      // No fixture directories found
+      assert.ok(true);
+    });
+    return;
+  }
+
+  for (const dir of fixtureDirs) {
+    describe(`Fixture: ${dir}`, () => {
+      const inputPath = path.join(fixturesDir, dir, 'input.json');
+      const outputPath = path.join(fixturesDir, dir, 'output.txt');
+
+      if (!fs.existsSync(inputPath)) {
+        it('should have input.json', () => {
+          assert.fail(`Missing input.json in ${dir}`);
+        });
+        return;
+      }
+
+      if (!fs.existsSync(outputPath)) {
+        it('should have output.txt', () => {
+          assert.fail(`Missing output.txt in ${dir}`);
+        });
+        return;
+      }
+
+      it('output.txt should match built statement from input.json', async () => {
+        const input = JSON.parse(fs.readFileSync(inputPath, 'utf-8'));
+        const expectedOutput = fs.readFileSync(outputPath, 'utf-8');
+
+        if (input.signature) {
+          const isValid = await verifySignedStatement(expectedOutput);
+          assert.strictEqual(isValid, true);
+          return;
+        }
+
+        let content: string;
+        if (typeof input.content === 'string') {
+          content = input.content;
+        } else {
+          content = buildContentFromInput(input.content);
+        }
+
+        // Build statement
+        const builtStatement = buildStatement({
+          domain: input.domain,
+          author: input.author,
+          time: new Date(input.time),
+          tags: input.tags,
+          content,
+          representative: input.representative,
+          supersededStatement: input.supersededStatement,
+          translations: input.translations,
+          attachments: input.attachments,
+        });
+
+        assert.strictEqual(builtStatement, expectedOutput);
+      });
+
+      it('output.txt should not contain double newlines', () => {
+        const output = fs.readFileSync(outputPath, 'utf-8');
+        assert.ok(!/\n\n/.test(output));
+      });
+
+      it('output.txt should be parseable', () => {
+        const output = fs.readFileSync(outputPath, 'utf-8');
+        const parsed = parseStatement({ statement: output });
+
+        assert.ok(parsed.domain);
+        assert.ok(parsed.author);
+        assert.ok(parsed.content);
+        assert.strictEqual(parsed.formatVersion, '5');
+      });
+
+      it('round-trip: parse(output.txt) should match input.json structure', () => {
+        const input = JSON.parse(fs.readFileSync(inputPath, 'utf-8'));
+        const output = fs.readFileSync(outputPath, 'utf-8');
+        const parsed = parseStatement({ statement: output });
+
+        assert.strictEqual(parsed.domain, input.domain);
+        assert.strictEqual(parsed.author, input.author);
+        assert.strictEqual(new Date(parsed.time).toISOString(), new Date(input.time).toISOString());
+
+        if (input.tags) {
+          assert.deepStrictEqual(parsed.tags, input.tags);
+        }
+        if (input.representative) {
+          assert.strictEqual(parsed.representative, input.representative);
+        }
+        if (input.supersededStatement) {
+          assert.strictEqual(parsed.supersededStatement, input.supersededStatement);
+        }
+        if (input.attachments) {
+          assert.deepStrictEqual(parsed.attachments, input.attachments);
+        }
+        if (input.translations) {
+          assert.deepStrictEqual(parsed.translations, input.translations);
+        }
+      });
+    });
+  }
+});

package/src/hash.test.ts

@@ -0,0 +1,219 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { sha256, verify, fromUrlSafeBase64, toUrlSafeBase64 } from './hash';
+
+describe('Hash utilities', () => {
+  describe('sha256', () => {
+    it('should hash a simple string', () => {
+      const input = 'hello world';
+      const hash = sha256(input);
+
+      // Verify it's URL-safe (no +, /, or =)
+      assert.ok(!hash.includes('+'));
+      assert.ok(!hash.includes('/'));
+      assert.ok(!hash.includes('='));
+
+      // Verify consistent output
+      const hash2 = sha256(input);
+      assert.strictEqual(hash, hash2);
+    });
+
+    it('should produce correct hash for known input', () => {
+      const input = 'hello world';
+      const expectedHash = 'uU0nuZNNPgilLlLX2n2r-sSE7-N6U4DukIj3rOLvzek';
+      const hash = sha256(input);
+      assert.strictEqual(hash, expectedHash);
+    });
+
+    it('should handle empty string', () => {
+      const hash = sha256('');
+      assert.ok(hash);
+      assert.strictEqual(typeof hash, 'string');
+    });
+
+    it('should handle unicode characters', () => {
+      const input = '你好世界 🌍';
+      const hash = sha256(input);
+      assert.ok(hash);
+      assert.strictEqual(typeof hash, 'string');
+
+      // Verify consistency
+      const hash2 = sha256(input);
+      assert.strictEqual(hash, hash2);
+    });
+
+    it('should handle Buffer input', () => {
+      const data = Buffer.from('hello world');
+      const hash = sha256(data);
+
+      // Should produce same hash as string input
+      const stringHash = sha256('hello world');
+      assert.strictEqual(hash, stringHash);
+    });
+
+    it('should produce different hashes for different inputs', () => {
+      const hash1 = sha256('hello');
+      const hash2 = sha256('world');
+      assert.notStrictEqual(hash1, hash2);
+    });
+
+    it('should produce 43-character URL-safe base64 string', () => {
+      const hash = sha256('test');
+      // SHA-256 produces 256 bits = 32 bytes
+      // Base64 encoding: 32 bytes * 4/3 = 42.67, rounded up = 43 chars (without padding)
+      assert.strictEqual(hash.length, 43);
+    });
+  });
+
+  describe('verify', () => {
+    it('should verify correct hash', () => {
+      const content = 'hello world';
+      const hash = sha256(content);
+      const isValid = verify(content, hash);
+      assert.strictEqual(isValid, true);
+    });
+
+    it('should reject incorrect hash', () => {
+      const content = 'hello world';
+      const wrongHash = 'incorrect_hash_value_here_1234567890';
+      const isValid = verify(content, wrongHash);
+      assert.strictEqual(isValid, false);
+    });
+
+    it('should reject hash for different content', () => {
+      const content1 = 'hello world';
+      const content2 = 'goodbye world';
+      const hash1 = sha256(content1);
+      const isValid = verify(content2, hash1);
+      assert.strictEqual(isValid, false);
+    });
+
+    it('should work with Buffer', () => {
+      const data = Buffer.from('test data');
+      const hash = sha256(data);
+      const isValid = verify(data, hash);
+      assert.strictEqual(isValid, true);
+    });
+  });
+
+  describe('fromUrlSafeBase64', () => {
+    it('should convert URL-safe base64 to standard base64', () => {
+      // Use a URL-safe string that contains both - and _ characters
+      const urlSafe = 'abc-def_ghi';
+      const standard = fromUrlSafeBase64(urlSafe);
+
+      // Should replace - with + and _ with /
+      assert.ok(standard.includes('+'));
+      assert.ok(standard.includes('/'));
+      // Should add padding
+      assert.strictEqual(standard.endsWith('='), true);
+    });
+
+    it('should add correct padding', () => {
+      // Test different padding scenarios
+      const testCases = [
+        { input: 'abc', expectedPadding: 1 },
+        { input: 'abcd', expectedPadding: 0 },
+        { input: 'abcde', expectedPadding: 3 },
+        { input: 'abcdef', expectedPadding: 2 },
+      ];
+
+      testCases.forEach(({ input, expectedPadding }) => {
+        const result = fromUrlSafeBase64(input);
+        const paddingCount = (result.match(/=/g) || []).length;
+        assert.strictEqual(paddingCount, expectedPadding);
+      });
+    });
+
+    it('should handle strings without special characters', () => {
+      const input = 'abcdefghijklmnop';
+      const result = fromUrlSafeBase64(input);
+      assert.ok(result);
+    });
+  });
+
+  describe('toUrlSafeBase64', () => {
+    it('should convert standard base64 to URL-safe', () => {
+      const standard = 'uU0nuZNNPgilLlLX2n2r+sSE7+N6U4DukIj3rOLvzek=';
+      const urlSafe = toUrlSafeBase64(standard);
+
+      // Should not contain standard base64 special characters
+      assert.ok(!urlSafe.includes('+'));
+      assert.ok(!urlSafe.includes('/'));
+      assert.ok(!urlSafe.includes('='));
+
+      // Should contain URL-safe replacements
+      assert.ok(urlSafe.includes('-'));
+    });
+
+    it('should remove padding', () => {
+      const withPadding = 'abc=';
+      const result = toUrlSafeBase64(withPadding);
+      assert.ok(!result.includes('='));
+      assert.strictEqual(result, 'abc');
+    });
+
+    it('should be reversible with fromUrlSafeBase64', () => {
+      // Start with a standard base64 string with special chars
+      const original = 'test+data/with==';
+      const urlSafe = toUrlSafeBase64(original);
+      const restored = fromUrlSafeBase64(urlSafe);
+
+      // Should restore to equivalent base64 (padding might differ slightly)
+      assert.strictEqual(restored.replace(/=+$/, ''), original.replace(/=+$/, ''));
+    });
+  });
+
+  describe('Round-trip conversions', () => {
+    it('should maintain hash integrity through URL-safe conversion', () => {
+      const content = 'test content for hashing';
+      const hash = sha256(content);
+
+      // Convert to standard base64 and back
+      const standard = fromUrlSafeBase64(hash);
+      const backToUrlSafe = toUrlSafeBase64(standard);
+
+      assert.strictEqual(backToUrlSafe, hash);
+    });
+
+    it('should verify hash after conversion', () => {
+      const content = 'verification test';
+      const hash = sha256(content);
+
+      // Convert and back
+      const standard = fromUrlSafeBase64(hash);
+      const urlSafe = toUrlSafeBase64(standard);
+
+      // Should still verify
+      const isValid = verify(content, urlSafe);
+      assert.strictEqual(isValid, true);
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('should handle very long strings', () => {
+      const longString = 'a'.repeat(10000);
+      const hash = sha256(longString);
+      assert.ok(hash);
+      assert.strictEqual(hash.length, 43);
+    });
+
+    it('should handle special characters', () => {
+      const special = '!@#$%^&*()_+-=[]{}|;:,.<>?';
+      const hash = sha256(special);
+      assert.ok(hash);
+
+      const isValid = verify(special, hash);
+      assert.strictEqual(isValid, true);
+    });
+
+    it('should handle newlines and whitespace', () => {
+      const withNewlines = 'line1\nline2\r\nline3\ttab';
+      const hash = sha256(withNewlines);
+      assert.ok(hash);
+
+      const isValid = verify(withNewlines, hash);
+      assert.strictEqual(isValid, true);
+    });
+  });
+});