Completed project and documentation setup

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,40 @@
+---
+name: Bug report
+about: Please create a bug report to help us solve any problems and improve the software
+title: ''
+labels: bug
+assignees: ''
+---
+
+## Issue details
+
+### Description
+
+Please give a short description of the problem in one or two sentences...
+
+### Environment / Versions
+
+#### Software
+
+    * OS:  <name> <version>
+    * Node.js: <version>
+    * whiteflag-js: <version>
+    * (please list allother relevant software components)
+
+#### Blockchain
+
+Name of the used blockchain, if relevant...
+
+### Symptoms and Problem details
+
+#### Steps to reproduce
+
+Please describe what action(s) you performed...
+
+#### Expected result
+
+Please describe what you did expect to happen...
+
+#### Actual result
+
+Please describe what actually happened. Include relevant debug or trace level logs...

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,32 @@
+---
+name: Feature request
+about: Feel free to suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+## Issue details
+
+### Description
+
+Please give a short description of the request in one or two sentences...
+
+### Rationale
+
+Please describe why you think the feature should be included in this software or added to the documentation. E.g. it is specified in the protocol standard but not yet implemented, it solves a practical problem, it enhances usability or interoperability, etc....
+
+### Solution
+
+#### Specification
+
+Please provide a clear and exact description of the functionality you want to be added to the software. Refer to the correct parts of any standard, specification, etc. if applicable...
+
+#### Affected components
+
+Please list any component (including documentation) that is likely to be affected if this request is implemented...
+
+#### Alternatives
+
+Please give a clear and concise description of any alternative solutions or features you've considered...

.github/workflows/nodejs.ubuntu.test.yaml

@@ -0,0 +1,23 @@
+name: Ubuntu Test
+on:
+  push:
+    branches:
+      - master
+      - develop
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [ubuntu-22.04, ubuntu-latest]
+        node-version: [22, 24, 25]
+    steps:
+    - uses: actions/checkout@v2
+    - name: Setup Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: Install dependencies
+      run: npm install
+    - name: Run tests
+      run: npm test

.github/workflows/nodejs.windows.test.yaml

@@ -0,0 +1,23 @@
+name: Windows Test
+on:
+  push:
+    branches:
+      - master
+      - develop
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      matrix:
+        os: [windows-latest]
+        node-version: [22.x, 24.x, 25.x]
+    steps:
+    - uses: actions/checkout@v2
+    - name: Setup Node.js ${{ matrix.node-version }}
+      uses: actions/setup-node@v1
+      with:
+        node-version: ${{ matrix.node-version }}
+    - name: Install dependencies
+      run: npm install
+    - name: Run tests
+      run: npm test

LICENSE.md

@@ -1,18 +1,18 @@
-# Whiteflag API Software Dedication to the Public Domain
+# Whiteflag Software Dedication to the Public Domain
 
 ## Preamble
 
 All persons and organisations that contributed to the initial development
-of the Whiteflag Protocol and the Whiteflag API software did so
-disinterestedly.
+of the Whiteflag Protocol and the Whiteflag JavaScript Library software did
+so disinterestedly.
 
-## Whiteflag API Software CC0-1.0 Statement
+## Whiteflag JavaScript Library CC0-1.0 Statement
 
-Excluding third party software that is part of this distribution as
-listed below, the Whiteflag API software and associated documentation is
-dedicated to the public domain under the [Creative Commons CC0-1.0 Universal Public Domain Dedication](http://creativecommons.org/publicdomain/zero/1.0/)
+Excluding third party software that may be part of this distribution, the
+Whiteflag JavaScript Library software and associated documentation is dedicated
+to the public domain under the [Creative Commons CC0-1.0 Universal Public Domain Dedication](http://creativecommons.org/publicdomain/zero/1.0/)
 statement, meaning that to the extent possible under law, the authors
-and their organisations have waived all copyright and related or neighboring
+and their organisations have waived all copyright and related or neighbouring
 rights to this work, allowing anyone to copy, modify, distribute and implement
 the work, even for commercial purposes, all without asking permission.
 
@@ -26,12 +26,12 @@ the work, you should not imply endorsement by the authors or the affirmer.
 
 ## Third Party Software Dependencies
 
-The Whiteflag API software requires a number of third party software packages,
-which are not part of this distribution. These third party software packages
-need to be obtained through their respective official distribution channels,
-and may be licensed.
+Where the Whiteflag JavaScript Library software requires third party
+software packages, which are not part of this distribution. These third party
+software packages need to be obtained through their respective official
+distribution channels, and may be licensed.
 
-## Legal Restrictions for the Usage of the Whiteflag API Software
+## Legal Restrictions for the Usage of the Whiteflag software
 
 WARNING: THE USAGE OF SIGNS AND SIGNALS WITH THIS SOFTWARE IS SUBJECT
 TO LOCAL AND/OR INTERNATIONAL LAWS. Please take note of the following when

README.md

@@ -1,27 +1,31 @@
 # Whiteflag JavaScript Library
 
+![GitHub latest release](https://img.shields.io/github/v/release/whiteflagprotocol/whiteflag-js?label=latest&logo=github&sort=semver)
+![Ubuntu Test](https://github.com/WhiteflagProtocol/whiteflag-js/workflows/Ubuntu%20Test/badge.svg)
+![Windows Test](https://github.com/WhiteflagProtocol/whiteflag-js/workflows/Windows%20Test/badge.svg)
+
 ## Introduction
 
 [Whiteflag](https://www.whiteflagprotocol.org) is a fully neutral and
-secure communciations protocol based on blockchain technology. It enables
+secure communications protocol based on blockchain technology. It enables
 near real-time communication in armed conflicts and disasters to exchange
 early warning and status information to create shared situational awareness.
 The [Whiteflag Protocol specification](https://standard.whiteflagprotocol.org)
 is an open standard.
 
 The Whiteflag JavaScript Library (WFJSL) will be the reference implementation
-of the Whiteflag Protocol in [TypeScript](https://www.typescriptlang.org/),
+of the Whiteflag Protocol written in [TypeScript](https://developer.mozilla.org/en-US/docs/Glossary/TypeScript),
 and compiled to [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript),
 to support the development of Whiteflag-enabled applications in JavaScript.
 
-The WFJSL is currently **in development** in order to seperate the Whiteflag
+The WFJSL is currently **in development** in order to separate the Whiteflag
 core protocol code from the current reference implementation, i.e. the
 [Whiteflag API](https://api.whiteflagprotocol.org). This makes the code
 better to maintain and test in support of future Whiteflag protocol
 development, while ensuring reusability for other implementations.
 
 The WFJSL is to include all Whiteflag protocol features, but with minimal
-dependencies. Therefore, the library is independent from any specific
+dependencies. Therefore, the library is independent of any specific
 blockchain, database solution, user interface, etc.
 
 Version 1 of the WFJSL corresponds with version 1 of the protocol, and
@@ -31,18 +35,25 @@ functionality and corresponding `1.x` subversions are defined as
 
 ## Documentation
 
-All detailed documentation of the WFJSL programming interface will become
-available at [js.whiteflagprotocol.org](https://js.whiteflagprotocol.org/).
+Detailed documentation of the WFJSL programming interface is available
+at [js.whiteflagprotocol.org](https://js.whiteflagprotocol.org/).
 The documentation is also found in this repository in the `docs/` directory.
 
+## Testing
+
+Testing of the software is done with the [Mocha](https://mochajs.org/)
+test framework. To do a full test and run all the test scripts, use the
+following NPM command in the project root:
+
+```{sh}
+npm test
+```
+
 ## License and Third Party Software
 
 The WFJSL software is dedicated to the public domain under the
 [Creative Commons CC0-1.0 Universal Public Domain Dedication](http://creativecommons.org/publicdomain/zero/1.0/)
 statement. See `LICENSE.md` for details.
 
 The library may require third party software packages, which are not part of
-this distribution and may be licenced differently. The third party software
-dependencies of the WFJSL are:
-
-* the [Mocha](https://mochajs.org/) for testing the software
+this distribution and may be licensed differently.

dist/core/LICENSE.md

@@ -0,0 +1,53 @@
+# Whiteflag Software Dedication to the Public Domain
+
+## Preamble
+
+All persons and organisations that contributed to the initial development
+of the Whiteflag Protocol and the Whiteflag JavaScript Library software did
+so disinterestedly.
+
+## Whiteflag JavaScript Library CC0-1.0 Statement
+
+Excluding third party software that may be part of this distribution, the
+Whiteflag JavaScript Library software and associated documentation is dedicated
+to the public domain under the [Creative Commons CC0-1.0 Universal Public Domain Dedication](http://creativecommons.org/publicdomain/zero/1.0/)
+statement, meaning that to the extent possible under law, the authors
+and their organisations have waived all copyright and related or neighbouring
+rights to this work, allowing anyone to copy, modify, distribute and implement
+the work, even for commercial purposes, all without asking permission.
+
+In no way are the patent or trademark rights of any person affected by this
+dedication to the public domain, nor are the rights that other persons may
+have in the work or in how the work is used, such as publicity or privacy
+rights. Unless expressly stated otherwise, the authors and their organisations
+make no warranties about the work, and disclaim liability for all uses of the
+work, to the fullest extent permitted by applicable law. When using or citing
+the work, you should not imply endorsement by the authors or the affirmer.
+
+## Third Party Software Dependencies
+
+Where the Whiteflag JavaScript Library software requires third party
+software packages, which are not part of this distribution. These third party
+software packages need to be obtained through their respective official
+distribution channels, and may be licensed.
+
+## Legal Restrictions for the Usage of the Whiteflag software
+
+WARNING: THE USAGE OF SIGNS AND SIGNALS WITH THIS SOFTWARE IS SUBJECT
+TO LOCAL AND/OR INTERNATIONAL LAWS. Please take note of the following when
+using this software:
+
+- This software only provides an additional means of communication for
+  certain signs and signals, and it does not replace any existing
+  standard, regulation or means of communication, whether mandatory or
+  not, including but not limited to physical signs, radio communications,
+  official registers, etc.
+
+- The usage of protective signs is subject to International Humanitarian
+  Law. Misuse of protective signs is a punishable violation under local
+  and international laws.
+
+- The usage of emergency signals may be subject to various regulations and
+  standards, depending on location and context. The misuse of emergency
+  signals, including misuse of the duress functionality, may be a
+  punishable violation under local and international laws.

dist/core/README.md

@@ -0,0 +1,104 @@
+# WFJSL Core Implementation
+
+## Overview
+
+The Whiteflag JavaScript Library (WFJSL) is an implementation of the Whiteflag
+Protocol written in [TypeScript](https://developer.mozilla.org/en-US/docs/Glossary/TypeScript),
+and compiled to [JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript),
+to support the development of Whiteflag-enabled applications in JavaScript.
+
+The `@whiteflagprotocol/core` package provides the modules that define
+Whiteflag core protocol features as specified in the Whiteflag standard.
+As such, this package is not a fully functional implementation of the
+protocol, but separates core protocol functions from implementation-specific
+design decisions. Therefore, this package is not intended to be used directly
+by implementations of Whiteflag; instead, the `@whiteflagprotocol/main` should
+be used.
+
+This description provides a generic overview of the WFJSL core package.
+Please see the [WFJSL TypeDoc documentation](https://js.whiteflagprotocol.org/typedoc)
+for a detailed description of all classes and functions.
+
+## Whiteflag Message class
+
+The Whiteflag message class `WfCoreMessage` defined in the `message` module
+represents a Whiteflag message. The class contains the methods to create,
+set field values, encode and encrypt a Whiteflag message. Please note that
+there normally is no need to use the `WfCoreMessage` directly. Instead, the
+`WfMessage` child class of the `@whiteflagprotocol/main` package is the main
+class to use for Whiteflag message, as this extended class provides methods to
+process the metadata required for full protocol functionality.
+
+A new message may be created using the constructor, or by using a static
+factory method. For example, creating a new FreeText message (message
+code `F`) and set the `Text` field, may be done as follows:
+
+```{javascript}
+let wfMessage = new WfCoreMessage('F');
+WfCoreMessage.set('Text', 'Example text to be sent with the FreeText message');
+```
+
+The `encode()` method encodes the message. The `WfCoreMessage` class
+automatically verifies the fields and values when encoding and decoding.
+Encoding and decoding are asynchronous, meaning the functions return
+[Promises](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise).
+Once encoded, the methods `toHex()` and `toU8a()` may be used to obtain the
+encoded message as a hexadecimal string or a UInt8array, respectively.
+
+```{javascript}
+await wfMessage.encode();
+const hexMessage = wfMessage.toHex();
+```
+
+If a message is encoded, or decoded, the message is "final", meaning its
+content cannot be changed. Decoding a message is done using a one of the
+static factory methods such as `fromHex(...)` or `fromU8a(...)`, since the
+message type is probably not known before decoding.
+
+```{javascript}
+wfMessage = await WfCoreMessage.fromHex(hexMessage);
+```
+
+Encryption and decryption is automatically performed upon encoding and
+decoding, based on the value of the `EncryptionIndicator` field in the message
+header. Since the `WfCoreMessage` class does not hold any metadata, all
+encryption and decryption parameters must be provided to the respective method
+when encoding or decoding a message.
+
+The `message` module, also provides the following functions. These functions
+are used by the `WfCoreMessage` class, but may also be used for alternative
+processing of Whiteflag messages.
+
+| Function          | Purpose                                          |
+|-------------------|--------------------------------------------------|
+| `isValidMessage`  | Checks if an object is a valid Whiteflag message |
+| `validateMessage` | Checks a message object for validation errors    |
+| `encryptMessage`  | Encrypts a binary encoded message                |
+| `decryptMessage`  | Decrypts an encrypted binary message             |
+
+Both validation functions may be used for both plain JavaScript objects and
+objects of the `WfCoreMessage` class. The encryption and decryption functions
+work only on binary encoded messages provided as a `BinaryBuffer`.
+
+## Whiteflag message field encoding
+
+The `codec` module provides the encoding and decoding for each field in
+a Whiteflag message i.a.w. the Whiteflag specification. The available field
+encodings are defined with the `WfCodec` enum. For the encoding, decoding, and
+verification of field values, the module provides the following functions.
+
+| Function       | Purpose                            |
+|----------------|------------------------------------|
+| `encodeField`  | Encodes a Whiteflag message field  |
+| `decodeField`  | Decodes a Whiteflag message field  |
+| `isValidValue` | Checks if the field value is valid |
+
+These functions are used by the `WfCoreMessage` class when encoding and
+decoding a message.
+
+## Whiteflag versions
+
+Currently, only one version of the Whiteflag protocol has been developed. For
+ease of implementation of future Whiteflag versions, WFJSL functions and
+classes take the Whiteflag version into account. The `versions` module defines
+the available Whiteflag versions with the `WfVersions` enum.