@gwydion-id/icao-9303-models 0.1.0

package/src/digitalseal.js

@@ -0,0 +1,234 @@
+// SPDX-FileCopyrightText: 2026 Don Geronimo <https://sentamal.in>
+// SPDX-License-Identifier: LGPL-3.0-or-later
+
+import { VDS_SIGNATURE_MARKER } from "./utilities/vds-signature-marker.js";
+import { lengthToDERLength } from "./utilities/length-to-der-length.js";
+import { setSignatureZone } from "./utilities/set-signature-zone.js";
+import { validateMRZString } from "./utilities/validate-mrz-string.js"
+import { validateIdentifierCode } from "./utilities/validate-identifier-code.js";
+import { validateHexString } from "./utilities/validate-hex-string.js";
+import { IcaoDate } from "./utilities/icao-date.js";
+
+/**
+ * Stores common properties and methods for all ICAO 9303 visible digital seals
+ *     (VDSs).
+ * 
+ * `DigitalSeal` is intended to be used to compose different VDS versions. It is
+ *     not intended to be instantiated directly.
+ */
+export class DigitalSeal {
+  /**
+   * Create a `DigitalSeal`.
+   * @param { Object } [opt] - An options object.
+   * @param { string } [opt.authorityCode] - A 3-character string consisting of
+   *     the characters A-Z, 0-9, ' ', or <. A code from ISO-3166-1,
+   *     ICAO 9303-3, or these user-assigned ranges are recommended: AAA-AAZ,
+   *     QMA-QZZ, XAA-XZZ, or ZZA-ZZZ.
+   * @param { string } [opt.identifierCode] - A 4-character string consisting of
+   *     the characters 0-9 and A-Z.
+   * @param { string } [opt.certReference] - A hex-string that uniquely
+   *     identifies a certificate for a given signer.
+   * @param { string | Date | IcaoDate } [opt.issueDate] - A calendar date string in
+   *     YYYY-MM-DD format, a `Date` object, or an `IcaoDate` object.
+   * @param { string | Date | IcaoDate } [opt.signatureDate] - A calendar date string in
+   *     YYYY-MM-DD format, a `Date` object, or an `IcaoDate` object.
+   * @param { number } [opt.featureDefinition] - A number in the range of
+   *     0x01-0xFE.
+   * @param { number } [opt.typeCategory] - A number in the range of 0x01-0xFE.
+   *     Odd numbers in the range between 0x01 and 0xFD shall be used for
+   *     ICAO-specified document type categories.
+   * @param { Map<number, number[]> } [opt.features] - A store of
+   *     digitally-encoded document features used to create the message zone.
+   * @param { number[] } [opt.signatureData] - The raw signature data generated
+   *     by concatenating the header and message zone, hashing the result, and
+   *     signing the hash with a cryptographic key.
+   * @param { number[] } [opt.signatureZone] - The signature zone of the VDS as
+   *     a TLV of the signature marker, its length in BER/DER definite length
+   *     form, and the raw signature data.
+   */
+  constructor(opt) {
+    this.authorityCode = opt?.authorityCode ?? "UTO";
+    this.identifierCode = opt?.identifierCode ?? "UTSS";
+    this.certReference = opt?.certReference ?? "00000";
+    this.issueDate = opt?.issueDate ?? "2007-04-15";
+    this.signatureDate = opt?.signatureDate ?? "2007-04-15";
+    this.featureDefinition = opt?.featureDefinition ?? 0x01;
+    this.typeCategory = opt?.typeCategory ?? 0x01;
+    this.features = opt?.features ?? new Map();
+    this.signatureData = opt?.signatureData ?? Array(64).fill(0);
+
+    if (opt?.signatureZone) { this.signatureZone = opt.signatureZone; }
+  }
+  
+  #authorityCode;
+  /**
+   * A code identifying the authority who issued this seal.
+   * @type { string }
+   */
+  get authorityCode() { return this.#authorityCode; }
+  /**
+   * @param { string } value - A 3-character string consisting of the characters
+   *     A-Z, 0-9, ' ', or <. A code from ISO-3166-1, ICAO 9303-3, or these
+   *     user-assigned ranges are recommended: AAA-AAZ, QMA-QZZ, XAA-XZZ, or
+   *     ZZA-ZZZ.
+   */
+  set authorityCode(value) {
+    const isInvalid = validateMRZString(value, {
+      minimum: 1,
+      maximum: 3
+    });
+    if (isInvalid) {
+      throw new RangeError(
+        `Value set on 'authorityCode' has errors: ${isInvalid}`
+      );
+    }
+    this.#authorityCode = value.toUpperCase();
+  }
+
+  #identifierCode;
+  /**
+   * A combination of a two-letter authority code and of two alphanumeric
+   *     characters to identify a signer within the issuing authority.
+   * @type { string }
+   */
+  get identifierCode() { return this.#identifierCode; }
+  /**
+   * @param { string } value - A 4-character string consisting of the characters
+   *     0-9 and A-Z.
+   */
+  set identifierCode(value) {
+    const isInvalid = validateIdentifierCode(value);
+    if (isInvalid) {
+      throw new RangeError(
+        `Value set on 'identifierCode' has errors: ${isInvalid}`
+      );
+    }
+    this.#identifierCode = value.toUpperCase();
+  }
+
+  #certReference;
+  /**
+   * A hex-string that uniquely identifies a certificate for a given signer.
+   * @type { string }
+   */
+  get certReference() { return this.#certReference; }
+  /**
+   * @param { string } value - A hexadecimal string.
+   */
+  set certReference(value) {
+    const isInvalid = validateHexString(value);
+    if (isInvalid) {
+      throw new RangeError(
+        `Value set on 'certReference' has errors: ${isInvalid}`
+      );
+    }
+    this.#certReference = value.toUpperCase();
+  }
+
+  #issueDate;
+  /**
+   * A date string on which the document was issued.
+   * @type { IcaoDate }
+   */
+  get issueDate() { return this.#issueDate; }
+  /**
+   * @param { string | Date | IcaoDate } value - A calendar date string in YYYY-MM-DD
+   *     format, a `Date` object, or an `IcaoDate` object.
+   */
+  set issueDate(value) {
+    this.#issueDate = new IcaoDate(value);
+  }
+
+  #signatureDate;
+  /**
+   * A date string on which the seal was signed.
+   * @type { IcaoDate }
+   */
+  get signatureDate() { return this.#signatureDate; }
+  /**
+   * @param { string | Date | IcaoDate } value - A calendar date string in YYYY-MM-DD
+   *     format or a `Date` object.
+   */
+  set signatureDate(value) {
+    this.#signatureDate = new IcaoDate(value);
+  }
+
+  #featureDefinition;
+  /**
+   * A reference code to a document that defines the number and encoding of VDS
+   *     features.
+   * @type { number }
+   */
+  get featureDefinition() { return this.#featureDefinition; }
+  /**
+   * @param { number } value - A number in the range of 0x01-0xFE.
+   */
+  set featureDefinition(value) {
+    if (value <= 0 || value > 254) {
+      throw new RangeError(
+        "Document feature definition reference must be in the range between " +
+            "1-254."
+      );
+    } else {
+      this.#featureDefinition = value;
+    }
+  }
+
+  #typeCategory;
+  /**
+   * A code defining the document type category to which the seal is attached.
+   * @type { number }
+   */
+  get typeCategory() { return this.#typeCategory; }
+  /**
+   * @param { number } value - A number in the range of 0x01 - 0xFE. Odd numbers
+   *     in the range between 0x01 and 0xFD shall be used for ICAO-specified
+   *     document type categories.
+   */
+  set typeCategory(value) {
+    if (value <= 0 || value > 254) {
+      throw new RangeError(
+        "Document type category must be in the range between 1-254."
+      );
+    } else {
+      this.#typeCategory = value;
+    }
+  }
+
+  /**
+   * A store of digitally-encoded document features used to create the message
+   *     zone.
+   * @type { Map<number, number[]>}
+   */
+  features;
+
+  /**
+   * The raw signature data generated by concatenating the header and message
+   *     zone, hashing the result, and signing the hash with a cryptographic
+   *     key.
+   * @type { number[] }
+   */
+  signatureData;
+
+  /**
+   * The signature zone of the VDS as a TLV of the signature marker, its length
+   *     in BER/DER definite length form, and the raw signature data.
+   * @type { number[] }
+   */
+  get signatureZone() {
+    let output = [];
+    output.push(VDS_SIGNATURE_MARKER);
+    output = output.concat(
+      lengthToDERLength(this.signatureData.length)
+    );
+    output = output.concat(this.signatureData);
+    return output;
+  }
+  /**
+   * @param { number[] } value
+   */
+  set signatureZone(value) {
+    this.signature = setSignatureZone(0, value);
+  }
+}
+

package/src/digitalsealv3.js

@@ -0,0 +1,359 @@
+// SPDX-FileCopyrightText: 2026 Don Geronimo <https://sentamal.in>
+// SPDX-License-Identifier: LGPL-3.0-or-later
+
+import { DigitalSeal } from "./digitalseal.js";
+import { c40Encode } from "./utilities/c40-encode.js";
+import { c40Decode } from "./utilities/c40-decode.js";
+import { VDS_MAGIC } from "./utilities/vds-magic.js";
+import { VDS_SIGNATURE_MARKER } from "./utilities/vds-signature-marker.js";
+import { setSignatureZone } from "./utilities/set-signature-zone.js";
+import { VDS_VERSION_3 } from "./utilities/vds-version-3.js";
+import { IcaoDate } from "./utilities/icao-date.js";
+
+/**
+ * Stores properties and methods for ICAO 9303 visible digital seals (VDSs)
+ *     version 3. Consult ICAO 9030 part 13 to see the differences between this
+ *     version and other versions. Use of version 3 VDSs are discouraged but may
+ *     still be encountered in the wild.
+ * 
+ * `DigitalSealV3` is intended to be used to compose different kinds of
+ *     machine-readable travel documents (MRTDs) with attached VDSs containing
+ *     different document features. It is not intended to be instantiated
+ *     directly.
+ */
+export class DigitalSealV3 {
+  /**
+   * Create a `DigitalSealV3`.
+   * @param { Object } [opt] - An options object.
+   * @param { string } [opt.authorityCode] - A 3-character string consisting of
+   *     the characters A-Z, 0-9, ' ', or <. A code from ISO-3166-1,
+   *     ICAO 9303-3, or these user-assigned ranges are recommended: AAA-AAZ,
+   *     QMA-QZZ, XAA-XZZ, or ZZA-ZZZ.
+   * @param { string } [opt.identifierCode] - A 4-character string consisting of
+   *     the characters 0-9 and A-Z.
+   * @param { string } [opt.certReference] - A hex-string that uniquely
+   *     identifies a certificate for a given signer.
+   * @param { string | Date | IcaoDate } [opt.issueDate] - A calendar date string in
+   *     YYYY-MM-DD format, a `Date` object, or an `IcaoDate` object.
+   * @param { string | Date | IcaoDate } [opt.signatureDate] - A calendar date string in
+   *     YYYY-MM-DD format, a `Date` object, or an `IcaoDate` object.
+   * @param { number } [opt.featureDefinition] - A number in the range of
+   *     0x01-0xFE.
+   * @param { number } [opt.typeCategory] - A number in the range of 0x01-0xFE.
+   *     Odd numbers in the range between 0x01 and 0xFD shall be used for
+   *     ICAO-specified document type categories.
+   * @param { Map<number, number[]> } [opt.features] - A store of
+   *     digitally-encoded document features used to create the message zone.
+   * @param { number[] } [opt.signatureData] - The raw signature data generated
+   *     by concatenating the header and message zone, hashing the result, and
+   *     signing the hash with a cryptographic key.
+   * @param { number[] } [opt.headerZone] - The header zone of the VDS as
+   *     defined by ICAO 9303 part 13.
+   * @param { number[] } [opt.messageZone] - The message zone of the VDS as
+   *     defined by ICAO 9303 part 13.
+   * @param { number[] } [opt.signatureZone] - The signature zone of the VDS as
+   *     a TLV of the signature marker, its length in BER/DER definite length
+   *     form, and the raw signature data.
+   * @param { number[] } [opt.unsignedSeal] - A concatenation of the header zone
+   *     and the message zone of the VDS.
+   * @param { number[] } [opt.signedSeal] - A concatenation of the header zone,
+   *     the message zone, and the signature zone of the VDS.
+   */
+  constructor(opt) {
+    this.#digitalseal = new DigitalSeal();
+
+    this.authorityCode = opt?.authorityCode ?? "UTO";
+    this.identifierCode = opt?.identifierCode ?? "UTSS";
+    this.certReference = opt?.certReference ?? "00000";
+    this.issueDate = opt?.issueDate ?? "2007-04-15";
+    this.signatureDate = opt?.signatureDate ?? "2007-04-15";
+    this.featureDefinition = opt?.featureDefinition ?? 0x01;
+    this.typeCategory = opt?.typeCategory ?? 0x01;
+    this.features = opt?.features ?? new Map();
+    this.signatureData = opt?.signatureData ?? Array(64).fill(0);
+
+    if (opt?.headerZone) { this.headerZone = opt.headerZone; }
+    if (opt?.messageZone) { this.messageZone = opt.messageZone; }
+    if (opt?.signatureZone) { this.signatureZone = opt.signatureZone; }
+    if (opt?.unsignedSeal) { this.unsignedSeal = opt.unsignedSeal; }
+    if (opt?.signedSeal) { this.signedSeal = opt.signedSeal; }
+  }
+
+  // The object `DigitalSealV3` uses to compose itself.
+  #digitalseal;
+
+  /**
+   * A code identifying the authority who issued this seal.
+   * @type { string }
+   */
+  get authorityCode() { return this.#digitalseal.authorityCode; }
+  /**
+   * @param { string } value - A 3-character string consisting of the characters
+   *     A-Z, 0-9, ' ', or <. A code from ISO-3166-1, ICAO 9303-3, or these
+   *     user-assigned ranges are recommended: AAA-AAZ, QMA-QZZ, XAA-XZZ, or ZZA-ZZZ.
+   */
+  set authorityCode(value) { this.#digitalseal.authorityCode = value; }
+
+  /**
+   * A combination of a two-letter authority code and of two alphanumeric
+   *     characters to identify a signer within the issuing authority.
+   * @type { string }
+   */
+  get identifierCode() { return this.#digitalseal.identifierCode; }
+  /**
+   * @param { string } value - A 4-character string consisting of the characters
+   *     0-9 and A-Z.
+   */
+  set identifierCode(value) { this.#digitalseal.identifierCode = value; }
+
+  /**
+   * A hex-string that uniquely identifies a certificate for a given signer.
+   * @type { string }
+   */
+  get certReference() { return this.#digitalseal.certReference; }
+  /**
+   * @param { string } value - A hex-string of exactly 5 characters.
+   */
+  set certReference(value) {
+    if (value.length !== 5) {
+      throw new RangeError(
+        "Certificate reference must be a hex string of exactly 5 characters."
+      );
+    } else {
+      this.#digitalseal.certReference = value;
+    }
+  }
+
+  /**
+   * A date string on which the document was issued.
+   * @type { IcaoDate }
+   */
+  get issueDate() { return this.#digitalseal.issueDate; }
+  /**
+   * @param { string | Date | IcaoDate } value - A calendar date string in YYYY-MM-DD
+   *     format, a `Date` object, or an `IcaoDate` object.
+   */
+  set issueDate(value) { this.#digitalseal.issueDate = value; }
+
+  /**
+   * A date string on which the seal was signed.
+   * @type { IcaoDate }
+   */
+  get signatureDate() { return this.#digitalseal.signatureDate; }
+  /**
+   * @param { string | Date | IcaoDate } value - A calendar date string in YYYY-MM-DD
+   *     format, a `Date` object, or an `IcaoDate` object.
+   */
+  set signatureDate(value) { this.#digitalseal.signatureDate = value; }
+
+  /**
+   * A reference code to a document that defines the number and encoding of VDS
+   *     features.
+   * @type { number }
+   */
+  get featureDefinition() { return this.#digitalseal.featureDefinition; }
+  /**
+   * @param { number } value - A number in the range of 0x01 - 0xFE.
+   */
+  set featureDefinition(value) { this.#digitalseal.featureDefinition = value; }
+
+  /**
+   * A code defining the document type category to which the seal is attached.
+   * @type { number }
+   */
+  get typeCategory() { return this.#digitalseal.typeCategory; }
+  /**
+   * @param { number } value - A number in the range of 0x01-0xFE. Odd numbers
+   *     in the range between 0x01 and 0xFD shall be used for ICAO-specified
+   *     document type categories.
+   */
+  set typeCategory(value) { this.#digitalseal.typeCategory = value; }
+
+  /**
+   * A store of digitally-encoded document features used to create the message
+   *     zone.
+   * @type { Map<number, number[]>}
+   */
+  get features() { return this.#digitalseal.features; }
+  /**
+   * @param { Map<number, number[]> } value
+   */
+  set features(value) { this.#digitalseal.features = value; }
+
+  /**
+   * The raw signature data generated by concatenating the header and message
+   *     zone, hashing the result, and signing the hash with a cryptographic
+   *     key.
+   * @type { number[] }
+   */
+  get signatureData() { return this.#digitalseal.signatureData; }
+  /**
+   * @param { number[] } value
+   */
+  set signatureData(value) { this.#digitalseal.signatureData = value; }
+
+  /**
+   * The header zone of the VDS as defined by ICAO 9303 part 13.
+   * @type { number[] }
+   */
+  get headerZone() {
+    let output = [];
+    output.push(VDS_MAGIC);
+    output.push(VDS_VERSION_3);
+    output =
+        output.concat(c40Encode(this.authorityCode.padEnd(3, "<")));
+    output = output.concat(c40Encode(
+      this.identifierCode +
+      this.certReference
+    ));
+    output = output.concat(this.issueDate.toVDSArray());
+    output = output.concat(this.signatureDate.toVDSArray());
+    output.push(this.featureDefinition);
+    output.push(this.typeCategory);
+    return output;
+  }
+  /**
+   * @param { number[] } value
+   */
+  set headerZone(value) {
+    this.#setHeader(0, value);
+  }
+  /**
+   * Given a point 'start' in an array 'value', extract the header data.
+   * @param { number } start 
+   * @param { number[] } value
+   * @returns { number } The point in the array where the method stopped
+   *     reading.
+   */
+  #setHeader(start, value) {
+    if (value[0] !== VDS_MAGIC) {
+      throw new TypeError(
+        `Value '${value[0].toString(16).padStart(2, "0").toUpperCase()}' is ` +
+            `not an ICAO Digital Seal (` +
+            `${VDS_MAGIC.toString(16).padStart(2, "0").toUpperCase()}).`
+      );
+    }
+    if (value[1] !== VDS_VERSION_3) {
+      throw new TypeError(
+        `Value '${value[0].toString(16).padStart(2, "0").toUpperCase()}' is ` +
+            `not version 3 of an ICAO Digital Seal (` +
+            `${VDS_VERSION_3.toString(16).padStart(
+              2, "0"
+            ).toUpperCase()}).`
+      );
+    }
+    start += 2;
+    this.authority =
+        c40Decode(value.slice(start, start + 2)).trim();
+    start += 2;
+    const ID_CERT_REF = c40Decode(value.slice(start, start + 6));
+    this.identifierCode = ID_CERT_REF.substring(0, 4);
+    this.certReference = ID_CERT_REF.substring(4);
+    start += 6;
+    this.issueDate = new IcaoDate(value.slice(start, start + 3));
+    start += 3;
+    this.signatureDate = new IcaoDate(value.slice(start, start + 3));
+    start += 3;
+    this.featureDefinition = value[start];
+    start += 1;
+    this.typeCategory = value[start];
+    start += 1;
+    return start;
+  }
+
+  /**
+   * The message zone of the VDS as defined by ICAO 9303 part 13.
+   * @type { number[] }
+   */
+  get messageZone() {
+    let output = [];
+    for (const [tag, value] of this.features) {
+      output.push(tag);
+      output.push(value.length);
+      output = output.concat(value);
+    }
+    return output;
+  }
+  /**
+   * @param { number[] } value
+   */
+  set messageZone(value) {
+    this.#setMessage(0, value);
+  }
+  /**
+   * Given a point 'start' in an array 'value', extract the document feature
+   *     data.
+   * @param { number } start 
+   * @param { number[] } value
+   * @returns { number } The point in the array where the method stopped
+   *     reading.
+   */
+  #setMessage(start, value) {
+    this.features.clear();
+    while (start < value.length) {
+      if (value[start] === VDS_SIGNATURE_MARKER) {
+        break;
+      }
+      const TAG = value[start];
+      start += 1;
+      const LENGTH = value[start];
+      start += 1;
+      const slicedValue = value.slice(start, start + LENGTH);
+      if (slicedValue.length !== LENGTH) {
+        throw new RangeError(
+          `Length '${LENGTH}' of document feature does not match the actual ` +
+              `length (${slicedValue.length}).`
+        );
+      }
+      this.features.set(TAG, slicedValue);
+      start += LENGTH;
+    }
+    return start;
+  }
+
+  /**
+   * The signature zone of the VDS as a TLV of the signature marker, its length
+   *     in BER/DER definite length form, and the raw signature data.
+   * @type { number[] }
+   */
+  get signatureZone() { return this.#digitalseal.signatureZone; }
+  /**
+   * @param { number[] } value
+   */
+  set signatureZone(value) { this.#digitalseal.signatureZone = value; }
+
+  /**
+   * A concatenation of the header zone and the message zone of the VDS.
+   * @type { number[] }
+   */
+  get unsignedSeal() {
+    return this.headerZone.concat(this.messageZone);
+  }
+  /**
+   * @param { number[] } value
+   */
+  set unsignedSeal(value) {
+    let start = 0;
+    start = this.#setHeader(start, value);
+    this.#setMessage(start, value);
+  }
+
+  /**
+   * A concatenation of the header zone, the message zone, and the signature
+   *     zone of the VDS.
+   * @type { number[] }
+   */
+  get signedSeal() {
+    return this.headerZone.concat(this.messageZone.concat(this.signatureZone));
+  }
+  /**
+   * @param { number[] } value
+   */
+  set signedSeal(value) {
+    let start = 0;
+    start = this.#setHeader(start, value);
+    start = this.#setMessage(start, value);
+    this.signatureData = setSignatureZone(start, value);
+  }
+}
+