fiftyone.pipeline.did 4.5.25

package/examples/fodIdExample.js

@@ -0,0 +1,116 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+/**
+ * Offline example for the 51Did (FodId) reader.
+ *
+ * The 51Degrees Cloud service issues real 51Dids. To keep this example
+ * self-contained and offline, it builds a sample 51Did in process - generate
+ * an ECDSA P-256 key pair, sign a canonical 37-byte payload - then parses it
+ * back and prints the three payload fields. It also shows the headline use
+ * case: a 51Did is re-issued fresh on every call (the envelope, hence the
+ * base64, changes), but the value (the Hash) is stable. Compare values, never
+ * envelopes.
+ */
+
+const { webcrypto } = require('crypto');
+const { FodId, IdType } = require('../index');
+
+const subtle = webcrypto.subtle;
+const VERSION = 2;
+const DOMAIN = '51degrees.com';
+const DATE = 2900000; // minutes since 2020-01-01
+
+function uint32LE (v) {
+  return [v & 0xFF, (v >>> 8) & 0xFF, (v >>> 16) & 0xFF, (v >>> 24) & 0xFF];
+}
+
+function samplePayload () {
+  const p = new Uint8Array(FodId.PAYLOAD_LENGTH); // Probabilistic (flags 0x00)
+  p[FodId.LICENSE_ID_OFFSET] = 0x78;
+  p[FodId.LICENSE_ID_OFFSET + 1] = 0x56;
+  p[FodId.LICENSE_ID_OFFSET + 2] = 0x34;
+  p[FodId.LICENSE_ID_OFFSET + 3] = 0x12;
+  for (let i = 0; i < FodId.HASH_LENGTH; i++) { p[FodId.HASH_OFFSET + i] = 0x20 + i; }
+  return p;
+}
+
+function noSigBytes (payload, date) {
+  const out = [VERSION];
+  for (let i = 0; i < DOMAIN.length; i++) { out.push(DOMAIN.charCodeAt(i)); }
+  out.push(0);
+  out.push(...uint32LE(date));
+  out.push(...uint32LE(payload.length));
+  for (const b of payload) { out.push(b); }
+  return Uint8Array.from(out);
+}
+
+async function issue (privateKey, payload, date) {
+  const noSig = noSigBytes(payload, date);
+  const sig = new Uint8Array(await subtle.sign(
+    { name: 'ECDSA', hash: 'SHA-256' }, privateKey, noSig));
+  const full = new Uint8Array(noSig.length + sig.length);
+  full.set(noSig);
+  full.set(sig, noSig.length);
+  return Buffer.from(full).toString('base64');
+}
+
+function toPem (label, der) {
+  const b64 = Buffer.from(der).toString('base64');
+  return `-----BEGIN ${label}-----\n${b64.match(/.{1,64}/g).join('\n')}\n` +
+    `-----END ${label}-----\n`;
+}
+
+async function run () {
+  const keyPair = await subtle.generateKey(
+    { name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify']);
+  const publicPem = toPem('PUBLIC KEY',
+    new Uint8Array(await subtle.exportKey('spki', keyPair.publicKey)));
+  const payload = samplePayload();
+
+  const fodId = FodId.fromBase64(await issue(keyPair.privateKey, payload, DATE));
+
+  console.log('51Did parsed from base64:');
+  console.log('  Domain    :', fodId.domain);
+  console.log('  Type      :', IdType.name(fodId.type));
+  console.log('  Flags     : 0x' + fodId.flags.toString(16));
+  console.log('  LicenseId :', fodId.licenseId);
+  console.log('  Hash      :', Buffer.from(fodId.hash).toString('hex'));
+  console.log('  Verifies  :', await fodId.verify(publicPem));
+
+  // Re-issue the same payload at a later time: a separate envelope, same value.
+  const reissued = FodId.fromBase64(
+    await issue(keyPair.privateKey, payload, DATE + 5));
+  const sameEnvelope = fodId.asBase64() === reissued.asBase64();
+  const sameValue = Buffer.from(fodId.hash).equals(Buffer.from(reissued.hash));
+
+  console.log('\nSame payload, re-issued:');
+  console.log('  Same envelope (base64) :', sameEnvelope);
+  console.log('  Same value (Hash)      :', sameValue);
+
+  if (sameEnvelope || !sameValue) {
+    throw new Error(
+      'Expected a different envelope but the same value across reissues.');
+  }
+}
+
+run().catch((e) => { console.error(e); process.exit(1); });

package/fodId.js

@@ -0,0 +1,208 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+const owid = require('owid');
+const IdType = require('./idType');
+
+/**
+ * A strongly typed reader for the 51Did (51Degrees Identifier) value returned
+ * by the 51Degrees Cloud service.
+ *
+ * A 51Did is described at three levels. The 51Did is the identifier as a
+ * whole. The envelope is the signed OWID that carries it (version, domain,
+ * date, payload, signature), re-issued fresh on every call. The value is the
+ * stable, comparable part of the payload after the Flags and License Id,
+ * exposed via {@link FodId#hash}. Two 51Dids for the same inputs share the
+ * same value even though their envelopes differ. Compare values, never
+ * envelopes.
+ *
+ * The owid-js library is verify-only and exposes no instance asBase64, so this
+ * type composes an owid instance (holds it and delegates) and keeps the
+ * original base64 for {@link FodId#asBase64}. Construction does NOT verify the
+ * signature; call {@link FodId#verify} (async) explicitly.
+ */
+class FodId {
+  static FLAGS_OFFSET = 0;
+  static LICENSE_ID_OFFSET = 1;
+  static LICENSE_ID_LENGTH = 4;
+  static HASH_OFFSET = 5;
+  static HASH_LENGTH = 32;
+  static HEADER_LENGTH = 5;
+  static GUID_LENGTH = 16;
+  static RANDOM_PAYLOAD_LENGTH = 21;
+  static PAYLOAD_LENGTH = 37;
+
+  /**
+   * Promotes an already-parsed owid instance into a 51Did by unpacking its
+   * payload.
+   * @param {object} owidInstance an owid instance (from `new owid(base64)`)
+   */
+  constructor (owidInstance) {
+    if (owidInstance === null || owidInstance === undefined) {
+      throw new TypeError('owid must not be null or undefined');
+    }
+    this._owid = owidInstance;
+    const payload = owidInstance.owid.payload;
+    const length = payload ? payload.length : 0;
+    if (!payload || length < FodId.HEADER_LENGTH) {
+      throw new RangeError(
+        `51Did payload must be at least ${FodId.HEADER_LENGTH} bytes; ` +
+        `got ${length}.`);
+    }
+    this._flags = payload[FodId.FLAGS_OFFSET];
+    // Little-endian unsigned 32-bit. `>>> 0` forces unsigned so the high bit
+    // does not produce a negative number.
+    this._licenseId = (
+      payload[FodId.LICENSE_ID_OFFSET] |
+      (payload[FodId.LICENSE_ID_OFFSET + 1] << 8) |
+      (payload[FodId.LICENSE_ID_OFFSET + 2] << 16) |
+      (payload[FodId.LICENSE_ID_OFFSET + 3] << 24)
+    ) >>> 0;
+    const type = IdType.fromFlags(this._flags);
+    let valueLength;
+    if (type === IdType.RANDOM) {
+      valueLength = FodId.GUID_LENGTH;
+    } else if (type === IdType.RESERVED) {
+      valueLength = length - FodId.HEADER_LENGTH;
+    } else {
+      valueLength = FodId.HASH_LENGTH;
+    }
+    if (length < FodId.HEADER_LENGTH + valueLength) {
+      throw new RangeError(
+        `51Did payload for the ${IdType.name(type)} type must be at least ` +
+        `${FodId.HEADER_LENGTH + valueLength} bytes; got ${length}.`);
+    }
+    // slice() copies, so the stored value cannot mutate the OWID payload.
+    this._hash = payload.slice(
+      FodId.HASH_OFFSET, FodId.HASH_OFFSET + valueLength);
+  }
+
+  /**
+   * Parses a 51Did from its base64-encoded OWID string.
+   * @param {string} base64
+   * @returns {FodId}
+   */
+  static fromBase64 (base64) {
+    if (typeof base64 !== 'string') {
+      throw new TypeError('base64 must be a string');
+    }
+    return new FodId(new owid(base64));
+  }
+
+  /**
+   * Parses a 51Did from the raw bytes of an OWID envelope.
+   * @param {Uint8Array} buffer
+   * @returns {FodId}
+   */
+  static fromByteArray (buffer) {
+    if (!(buffer instanceof Uint8Array)) {
+      throw new TypeError('buffer must be a Uint8Array');
+    }
+    return new FodId(new owid(Buffer.from(buffer).toString('base64')));
+  }
+
+  /**
+   * Promotes an already-parsed owid instance into a 51Did. The owid is
+   * **copied** (re-parsed from its base64), not aliased, so a FodId can never
+   * desync from its envelope if the caller later mutates the owid it passed
+   * in.
+   * @param {object} owidInstance
+   * @returns {FodId}
+   */
+  static fromOwid (owidInstance) {
+    if (owidInstance === null || owidInstance === undefined) {
+      throw new TypeError('owid must not be null or undefined');
+    }
+    return new FodId(new owid(owidInstance.data));
+  }
+
+  /** @returns {number} the 1-byte usage flags bit-mask (0-255). */
+  get flags () {
+    return this._flags;
+  }
+
+  /** @returns {number} the IdType carried in bits 6-7 of the flags. */
+  get type () {
+    return IdType.fromFlags(this._flags);
+  }
+
+  /** @returns {number} the 4-byte little-endian License Id (0-4294967295). */
+  get licenseId () {
+    return this._licenseId;
+  }
+
+  /**
+   * @returns {Uint8Array} a defensive copy of the value bytes (a 32-byte
+   * SHA-256, or 16 GUID bytes for Random) - the stable cache / dedup key.
+   */
+  get hash () {
+    return this._hash.slice();
+  }
+
+  /** @returns {number} the OWID version. */
+  get version () {
+    return this._owid.owid.version;
+  }
+
+  /** @returns {string} the domain of the OWID creator. */
+  get domain () {
+    return this._owid.domain;
+  }
+
+  /** @returns {number} the OWID date as minutes since 2020-01-01 UTC. */
+  get date () {
+    return this._owid.date;
+  }
+
+  /** @returns {Uint8Array} the OWID payload bytes. */
+  get payload () {
+    return this._owid.owid.payload;
+  }
+
+  /** @returns {Uint8Array} the 64-byte OWID signature. */
+  get signature () {
+    return this._owid.signature;
+  }
+
+  /** @returns {string} the OWID as a base64 string (the original envelope). */
+  asBase64 () {
+    return this._owid.data;
+  }
+
+  /** @returns {Uint8Array} the OWID envelope as raw bytes. */
+  asByteArray () {
+    return Uint8Array.from(atob(this._owid.data), (c) => c.charCodeAt(0));
+  }
+
+  /**
+   * Verifies the OWID signature against the supplied SPKI public key PEM. This
+   * is an explicit, separate step - construction never verifies. Asynchronous
+   * because it uses Web Crypto.
+   * @param {string} publicPem the creator public key in SPKI PEM form
+   * @returns {Promise<boolean>}
+   */
+  verify (publicPem) {
+    return this._owid.verifyWithPublicKey(publicPem, []);
+  }
+}
+
+module.exports = FodId;

package/idType.js

@@ -0,0 +1,60 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+const NAMES = ['Probabilistic', 'Random', 'HashedEmail', 'Reserved'];
+
+/**
+ * The identifier type carried in bits 6-7 of the 51Did flags byte. Existing
+ * identifiers were issued with these bits zeroed, so they decode as
+ * PROBABILISTIC. The type selects the length of the value that follows the
+ * header in the payload.
+ */
+const IdType = Object.freeze({
+  /** Device fingerprint + IP. Payload carries a 32-byte SHA-256 value. */
+  PROBABILISTIC: 0,
+  /** Server-generated random GUID. Payload carries 16 GUID bytes. */
+  RANDOM: 1,
+  /** Caller email + salt. Payload carries a 32-byte SHA-256 value. */
+  HASHED_EMAIL: 2,
+  /** Not yet assigned. Parsed best-effort; remaining bytes exposed as-is. */
+  RESERVED: 3,
+
+  /**
+   * Decodes the identifier type from the top two bits (6-7) of a flags byte.
+   * @param {number} flags the 1-byte flags value (0-255)
+   * @returns {number} the IdType value
+   */
+  fromFlags (flags) {
+    return (flags >> 6) & 0b11;
+  },
+
+  /**
+   * The human-readable name of an IdType value.
+   * @param {number} type an IdType value
+   * @returns {string}
+   */
+  name (type) {
+    return NAMES[type];
+  }
+});
+
+module.exports = IdType;

package/index.js

@@ -0,0 +1,26 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+const FodId = require('./fodId');
+const IdType = require('./idType');
+
+module.exports = { FodId, IdType };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "fiftyone.pipeline.did",
+  "version": "4.5.25",
+  "description": "Strongly typed reader for the 51Did (51Degrees Identifier) value returned by the 51Degrees Cloud service. Parses the OWID envelope and exposes the Flags, License Id and value (Hash) plus the identifier type. Compare values, never envelopes.",
+  "keywords": [
+    "51degrees",
+    "51did",
+    "fodid",
+    "owid",
+    "pipeline"
+  ],
+  "main": "index.js",
+  "scripts": {
+    "test": "jest"
+  },
+  "author": "51Degrees Engineering <engineering@51degrees.com>",
+  "license": "EUPL-1.2",
+  "dependencies": {
+    "owid": "github:51Degrees/owid-js#main"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
+  },
+  "jest": {
+    "setupFiles": [
+      "./tests/setup.js"
+    ]
+  },
+  "bugs": {
+    "url": "https://github.com/51Degrees/pipeline-node/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/51Degrees/pipeline-node"
+  }
+}

package/readme.md

@@ -0,0 +1,90 @@
+# fiftyone.pipeline.did
+
+Strongly typed Node.js reader for the 51Did (51Degrees Identifier) returned by
+the 51Degrees Cloud service. Mirrors the .NET `FiftyOne.Did` package.
+
+## Terminology
+
+- The **51Did** (51Degrees Identifier) is the identifier as a whole.
+- The **envelope** is the data model that carries it: a signed OWID holding the
+  version, domain, date, payload and signature. It changes byte-for-byte every
+  time the cloud issues one.
+- The **value** is the stable, comparable part of the payload after the Flags
+  and License Id: a 32-byte SHA-256 for Probabilistic and HashedEmail
+  identifiers, or 16 GUID bytes for Random.
+
+**Comparing two 51Dids means comparing their values, never their envelopes.**
+
+## Payload layout
+
+| Offset | Length | Field      | Type                                            |
+|-------:|-------:|------------|-------------------------------------------------|
+|      0 |      1 | Flags      | uint8: bits 0-2 usage, bits 6-7 identifier type |
+|      1 |      4 | LicenseId  | uint32 (little-endian)                          |
+|      5 |  16/32 | Value      | SHA-256 (Probabilistic, HashedEmail) or GUID (Random) |
+
+| Bits 7-6 | `IdType`        | Value length | Minimum payload |
+|---------:|-----------------|-------------:|----------------:|
+|     `00` | `PROBABILISTIC` |           32 |              37 |
+|     `01` | `RANDOM`        |           16 |              21 |
+|     `10` | `HASHED_EMAIL`  |           32 |              37 |
+|     `11` | `RESERVED`      |    remainder |               5 |
+
+Identifiers issued before the type tag existed have bits 6-7 zeroed and decode
+as `PROBABILISTIC`.
+
+## OWID dependency
+
+`FodId` builds on the OWID envelope library
+([SWAN-community/owid-js](https://github.com/SWAN-community/owid-js)), consumed
+via the `51Degrees/owid-js` fork as a git submodule and a `file:` dependency
+(switch to the npm registry once published). owid-js is parse + verify only and
+exposes no instance `asBase64`, so `FodId` **composes** an owid instance, keeps
+the original base64 for `asBase64()`, and delegates the rest.
+
+The fork was extended with an offline `verifyWithPublicKey(pem, others)` that
+works in Node and the browser (Web Crypto), so `FodId.verify()` runs without
+contacting a network endpoint.
+
+## Install / build
+
+```bash
+git submodule update --init   # fetches owid-js into ../owid-js
+npm install
+npm test
+```
+
+## Usage
+
+```js
+const { FodId, IdType } = require('fiftyone.pipeline.did');
+
+const fodId = FodId.fromBase64(base64FromCloudService);
+
+const flags = fodId.flags;
+const type = fodId.type;          // IdType.PROBABILISTIC / RANDOM / HASHED_EMAIL
+const licenseId = fodId.licenseId;
+const value = fodId.hash;         // Uint8Array: SHA-256 or GUID bytes, see type
+
+const domain = fodId.domain;
+const verified = await fodId.verify(publicKeyPem);   // async (Web Crypto)
+const base64 = fodId.asBase64();
+```
+
+## Comparing two 51Dids
+
+```js
+const a = FodId.fromBase64(idprobglobalA);
+const b = FodId.fromBase64(idprobglobalB);
+
+// The envelope (date, signature, base64) differs across reissues.
+// The value inside the payload is stable - this is what you compare:
+const sameValue = Buffer.from(a.hash).equals(Buffer.from(b.hash));
+```
+
+## Non-goals
+
+- **No signature verification on construction.** Call `verify(publicKeyPem)`
+  when needed (it is asynchronous).
+- **No creation of new 51Dids.** This is a parser; new 51Dids are issued by the
+  51Degrees cloud / on-premise hashing engines.

package/tests/fodId.test.js

@@ -0,0 +1,372 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+const owid = require('owid');
+const { FodId, IdType } = require('../index');
+
+const VERSION = 2;
+const DOMAIN = '51degrees.com';
+const DATE = 2900000; // minutes since 2020-01-01
+const CANONICAL_FLAGS = 0xA5; // HashedEmail type tag + usage bits
+const CANONICAL_LICENSE_ID = 0x12345678;
+
+function canonicalHash () {
+  const h = new Uint8Array(FodId.HASH_LENGTH);
+  for (let i = 0; i < h.length; i++) { h[i] = 0x20 + i; }
+  return h;
+}
+
+function writeLicenseId (payload) {
+  // Little-endian 0x12345678 -> 78 56 34 12.
+  payload[FodId.LICENSE_ID_OFFSET] = 0x78;
+  payload[FodId.LICENSE_ID_OFFSET + 1] = 0x56;
+  payload[FodId.LICENSE_ID_OFFSET + 2] = 0x34;
+  payload[FodId.LICENSE_ID_OFFSET + 3] = 0x12;
+}
+
+function canonicalPayload () {
+  const p = new Uint8Array(FodId.PAYLOAD_LENGTH);
+  p[FodId.FLAGS_OFFSET] = CANONICAL_FLAGS;
+  writeLicenseId(p);
+  p.set(canonicalHash(), FodId.HASH_OFFSET);
+  return p;
+}
+
+function canonicalRandomPayload () {
+  const p = new Uint8Array(FodId.RANDOM_PAYLOAD_LENGTH);
+  p[FodId.FLAGS_OFFSET] = (1 << 6) | 0b001; // Random tag + usage bits
+  writeLicenseId(p);
+  for (let i = 0; i < FodId.GUID_LENGTH; i++) {
+    p[FodId.HASH_OFFSET + i] = 0x40 + i;
+  }
+  return p;
+}
+
+function uint32LE (v) {
+  return [v & 0xFF, (v >>> 8) & 0xFF, (v >>> 16) & 0xFF, (v >>> 24) & 0xFF];
+}
+
+// Builds OWID envelope bytes (version 2 wire format) with the given payload and
+// an arbitrary signature, matching owid-js getByteArray + a 64-byte signature.
+function noSigBytes (payload, date) {
+  const out = [VERSION];
+  for (let i = 0; i < DOMAIN.length; i++) { out.push(DOMAIN.charCodeAt(i)); }
+  out.push(0);
+  out.push(...uint32LE(date));
+  out.push(...uint32LE(payload.length));
+  for (const b of payload) { out.push(b); }
+  return Uint8Array.from(out);
+}
+
+const DUMMY_SIG = (() => {
+  const s = new Uint8Array(64);
+  for (let i = 0; i < 64; i++) { s[i] = i + 1; }
+  return s;
+})();
+
+function envelopeBytes (payload, { date = DATE, signature = DUMMY_SIG } = {}) {
+  const noSig = noSigBytes(payload, date);
+  const full = new Uint8Array(noSig.length + signature.length);
+  full.set(noSig);
+  full.set(signature, noSig.length);
+  return full;
+}
+
+function envelopeBase64 (payload, opts) {
+  return Buffer.from(envelopeBytes(payload, opts)).toString('base64');
+}
+
+// Real ECDSA P-256 signing via Web Crypto, for the verify tests.
+async function signedVerifiable (payload, date = DATE) {
+  const keyPair = await crypto.subtle.generateKey(
+    { name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify']);
+  const noSig = noSigBytes(payload, date);
+  const sig = new Uint8Array(await crypto.subtle.sign(
+    { name: 'ECDSA', hash: 'SHA-256' }, keyPair.privateKey, noSig));
+  const full = new Uint8Array(noSig.length + sig.length);
+  full.set(noSig);
+  full.set(sig, noSig.length);
+  const spki = await crypto.subtle.exportKey('spki', keyPair.publicKey);
+  return {
+    base64: Buffer.from(full).toString('base64'),
+    publicPem: toPem('PUBLIC KEY', new Uint8Array(spki))
+  };
+}
+
+async function randomPublicPem () {
+  const keyPair = await crypto.subtle.generateKey(
+    { name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify']);
+  const spki = await crypto.subtle.exportKey('spki', keyPair.publicKey);
+  return toPem('PUBLIC KEY', new Uint8Array(spki));
+}
+
+function toPem (label, der) {
+  const b64 = Buffer.from(der).toString('base64');
+  return `-----BEGIN ${label}-----\n${b64.match(/.{1,64}/g).join('\n')}\n` +
+    `-----END ${label}-----\n`;
+}
+
+describe('FodId', () => {
+  // ----- Current .NET coverage -----
+
+  test('constants are internally consistent', () => {
+    expect(FodId.HASH_OFFSET + FodId.HASH_LENGTH).toBe(FodId.PAYLOAD_LENGTH);
+    expect(FodId.LICENSE_ID_OFFSET + FodId.LICENSE_ID_LENGTH)
+      .toBe(FodId.HASH_OFFSET);
+    expect(FodId.HASH_OFFSET + FodId.GUID_LENGTH)
+      .toBe(FodId.RANDOM_PAYLOAD_LENGTH);
+  });
+
+  test('exposes OWID-level fields', () => {
+    const fod = FodId.fromBase64(envelopeBase64(canonicalPayload()));
+    // OWID-level concerns are delegated to the wrapped envelope.
+    expect(fod.domain).toBe(DOMAIN);
+    expect(fod.version).toBeDefined();
+  });
+
+  test('fromBase64 unpacks all three fields', () => {
+    const fod = FodId.fromBase64(envelopeBase64(canonicalPayload()));
+    expect(fod.flags).toBe(CANONICAL_FLAGS);
+    expect(fod.licenseId).toBe(CANONICAL_LICENSE_ID);
+    expect(fod.hash).toEqual(canonicalHash());
+    expect(fod.domain).toBe(DOMAIN);
+  });
+
+  test('fromByteArray unpacks all three fields', () => {
+    const fod = FodId.fromByteArray(envelopeBytes(canonicalPayload()));
+    expect(fod.flags).toBe(CANONICAL_FLAGS);
+    expect(fod.licenseId).toBe(CANONICAL_LICENSE_ID);
+    expect(fod.hash).toEqual(canonicalHash());
+    expect(fod.domain).toBe(DOMAIN);
+  });
+
+  test('fromOwid unpacks all three fields', () => {
+    const o = new owid(envelopeBase64(canonicalPayload()));
+    const fod = FodId.fromOwid(o);
+    expect(fod.flags).toBe(CANONICAL_FLAGS);
+    expect(fod.licenseId).toBe(CANONICAL_LICENSE_ID);
+    expect(fod.hash).toEqual(canonicalHash());
+    expect(fod.domain).toBe(o.domain);
+    expect(fod.date).toBe(o.date);
+    expect(fod.version).toBe(o.owid.version);
+    expect(fod.payload).toEqual(o.owid.payload);
+    expect(fod.signature).toEqual(o.signature);
+  });
+
+  test('null owid throws', () => {
+    expect(() => FodId.fromOwid(null)).toThrow(TypeError);
+  });
+
+  test('licenseId is little-endian', () => {
+    const p = canonicalPayload();
+    p[1] = 0x01; p[2] = 0x00; p[3] = 0x00; p[4] = 0x00;
+    expect(FodId.fromBase64(envelopeBase64(p)).licenseId).toBe(1);
+  });
+
+  test('licenseId max value', () => {
+    const p = canonicalPayload();
+    p[1] = 0xFF; p[2] = 0xFF; p[3] = 0xFF; p[4] = 0xFF;
+    expect(FodId.fromBase64(envelopeBase64(p)).licenseId).toBe(4294967295);
+  });
+
+  test('licenseId high bit stays unsigned', () => {
+    const p = canonicalPayload();
+    p[1] = 0x00; p[2] = 0x00; p[3] = 0x00; p[4] = 0x80;
+    expect(FodId.fromBase64(envelopeBase64(p)).licenseId).toBe(0x80000000);
+  });
+
+  test('flags zero value exposed', () => {
+    const p = canonicalPayload();
+    p[FodId.FLAGS_OFFSET] = 0x00;
+    expect(FodId.fromBase64(envelopeBase64(p)).flags).toBe(0);
+  });
+
+  test('flags all bits set exposed', () => {
+    const p = canonicalPayload();
+    p[FodId.FLAGS_OFFSET] = 0xFF;
+    expect(FodId.fromBase64(envelopeBase64(p)).flags).toBe(255);
+  });
+
+  test('hash is a defensive copy', () => {
+    const fod = FodId.fromBase64(envelopeBase64(canonicalPayload()));
+    const h = fod.hash;
+    h[0] = 0x00;
+    h[FodId.HASH_LENGTH - 1] = 0x00;
+    expect(fod.hash).toEqual(canonicalHash());
+    expect(fod.payload[FodId.HASH_OFFSET]).toBe(0x20);
+  });
+
+  test('payload one byte short throws', () => {
+    expect(() => FodId.fromBase64(envelopeBase64(new Uint8Array(FodId.PAYLOAD_LENGTH - 1))))
+      .toThrow(RangeError);
+  });
+
+  test('empty payload throws', () => {
+    expect(() => FodId.fromBase64(envelopeBase64(new Uint8Array(0))))
+      .toThrow(RangeError);
+  });
+
+  test('null base64 throws', () => {
+    expect(() => FodId.fromBase64(null)).toThrow(TypeError);
+  });
+
+  test('null buffer throws', () => {
+    expect(() => FodId.fromByteArray(null)).toThrow(TypeError);
+  });
+
+  test('invalid base64 throws', () => {
+    expect(() => FodId.fromBase64('This is not valid Base64!@#$')).toThrow();
+  });
+
+  test('payload larger than spec uses first 37 bytes', () => {
+    const p = new Uint8Array(64);
+    p.set(canonicalPayload());
+    p.fill(0xCC, FodId.PAYLOAD_LENGTH);
+    const fod = FodId.fromBase64(envelopeBase64(p));
+    expect(fod.flags).toBe(CANONICAL_FLAGS);
+    expect(fod.licenseId).toBe(CANONICAL_LICENSE_ID);
+    expect(fod.hash).toEqual(canonicalHash());
+    expect(fod.hash.length).toBe(FodId.HASH_LENGTH);
+  });
+
+  test('is cryptographically verifiable', async () => {
+    const { base64, publicPem } = await signedVerifiable(canonicalPayload());
+    const fod = FodId.fromBase64(base64);
+    await expect(fod.verify(publicPem)).resolves.toBe(true);
+  });
+
+  test('base64 round-trip preserves all fields', () => {
+    const fod1 = FodId.fromBase64(envelopeBase64(canonicalPayload()));
+    const fod2 = FodId.fromBase64(fod1.asBase64());
+    expect(fod2.flags).toBe(fod1.flags);
+    expect(fod2.licenseId).toBe(fod1.licenseId);
+    expect(fod2.hash).toEqual(fod1.hash);
+    expect(fod2.domain).toBe(fod1.domain);
+  });
+
+  // ----- Type model -----
+
+  test('type decoded from top two flag bits', () => {
+    expect(typeFor(0b0000_0101)).toBe(IdType.PROBABILISTIC);
+    expect(typeFor(0b1000_0101)).toBe(IdType.HASHED_EMAIL);
+    expect(typeFor(0b1100_0101)).toBe(IdType.RESERVED);
+  });
+
+  function typeFor (flags) {
+    const p = canonicalPayload();
+    p[FodId.FLAGS_OFFSET] = flags;
+    return FodId.fromBase64(envelopeBase64(p)).type;
+  }
+
+  test('type is Random when bits are 01', () => {
+    const fod = FodId.fromBase64(envelopeBase64(canonicalRandomPayload()));
+    expect(fod.type).toBe(IdType.RANDOM);
+  });
+
+  test('Random 21-byte payload parses', () => {
+    const fod = FodId.fromBase64(envelopeBase64(canonicalRandomPayload()));
+    expect(fod.licenseId).toBe(CANONICAL_LICENSE_ID);
+    expect(fod.hash.length).toBe(FodId.GUID_LENGTH);
+    const guid = new Uint8Array(FodId.GUID_LENGTH);
+    for (let i = 0; i < guid.length; i++) { guid[i] = 0x40 + i; }
+    expect(fod.hash).toEqual(guid);
+  });
+
+  test('Random payload one byte short throws', () => {
+    const p = canonicalRandomPayload().slice(0, FodId.RANDOM_PAYLOAD_LENGTH - 1);
+    expect(() => FodId.fromBase64(envelopeBase64(p))).toThrow(RangeError);
+  });
+
+  test('Random payload larger than spec uses first 16 value bytes', () => {
+    const p = new Uint8Array(FodId.PAYLOAD_LENGTH);
+    p.set(canonicalRandomPayload());
+    p.fill(0xCC, FodId.RANDOM_PAYLOAD_LENGTH);
+    const fod = FodId.fromBase64(envelopeBase64(p));
+    expect(fod.type).toBe(IdType.RANDOM);
+    expect(fod.hash.length).toBe(FodId.GUID_LENGTH);
+  });
+
+  test('HashedEmail payload one byte short throws', () => {
+    const p = canonicalPayload().slice(0, FodId.PAYLOAD_LENGTH - 1);
+    expect(() => FodId.fromBase64(envelopeBase64(p))).toThrow(RangeError);
+  });
+
+  test('Reserved header-only payload parses', () => {
+    const p = new Uint8Array(FodId.HASH_OFFSET);
+    p[FodId.FLAGS_OFFSET] = 0b1100_0000;
+    const fod = FodId.fromBase64(envelopeBase64(p));
+    expect(fod.type).toBe(IdType.RESERVED);
+    expect(fod.hash.length).toBe(0);
+  });
+
+  // ----- Gap tests (runbook section 6b) -----
+
+  test('compare two 51Dids over the same payload', () => {
+    const payload = canonicalPayload();
+    const sigB = DUMMY_SIG.map((b) => b ^ 0xFF);
+    const a = envelopeBase64(payload, { date: DATE, signature: DUMMY_SIG });
+    const b = envelopeBase64(payload, { date: DATE + 5, signature: sigB });
+    const fa = FodId.fromBase64(a);
+    const fb = FodId.fromBase64(b);
+
+    expect(fa.hash).toEqual(fb.hash);            // value is stable
+    expect(fa.date).not.toBe(fb.date);           // envelope differs
+    expect(fa.signature).not.toEqual(fb.signature);
+    expect(a).not.toBe(b);
+  });
+
+  test('construction does not verify', () => {
+    // An envelope with a bogus signature still constructs and exposes all
+    // three fields - construction must not verify.
+    const fod = FodId.fromBase64(envelopeBase64(canonicalPayload()));
+    expect(fod.flags).toBe(CANONICAL_FLAGS);
+    expect(fod.licenseId).toBe(CANONICAL_LICENSE_ID);
+    expect(fod.hash).toEqual(canonicalHash());
+  });
+
+  test('fromOwid is decoupled from the source owid', () => {
+    // Mutating the source owid after construction must not affect the FodId
+    // (it holds an independent copy).
+    const o = new owid(envelopeBase64(canonicalPayload()));
+    const fod = FodId.fromOwid(o);
+    o.owid.payload = new Uint8Array(FodId.PAYLOAD_LENGTH); // mutate the source
+    expect(fod.hash).toEqual(canonicalHash());
+    expect(fod.flags).toBe(CANONICAL_FLAGS);
+    expect(fod.payload[FodId.HASH_OFFSET]).toBe(0x20);
+  });
+
+  test('verify with the wrong key returns false', async () => {
+    const { base64 } = await signedVerifiable(canonicalPayload());
+    const otherPublicPem = await randomPublicPem();
+    const fod = FodId.fromBase64(base64);
+    await expect(fod.verify(otherPublicPem)).resolves.toBe(false);
+  });
+
+  test('round-trip through the bytes constructor preserves all fields', () => {
+    const fod1 = FodId.fromBase64(envelopeBase64(canonicalPayload()));
+    const fod2 = FodId.fromByteArray(fod1.asByteArray());
+    expect(fod2.flags).toBe(fod1.flags);
+    expect(fod2.licenseId).toBe(fod1.licenseId);
+    expect(fod2.hash).toEqual(fod1.hash);
+    expect(fod2.domain).toBe(fod1.domain);
+  });
+});

package/tests/setup.js

@@ -0,0 +1,35 @@
+/* *********************************************************************
+ * This Original Work is copyright of 51 Degrees Mobile Experts Limited.
+ * Copyright 2026 51 Degrees Mobile Experts Limited, Davidson House,
+ * Forbury Square, Reading, Berkshire, United Kingdom RG1 3EU.
+ *
+ * This Original Work is licensed under the European Union Public Licence
+ * (EUPL) v.1.2 and is subject to its terms as set out below.
+ *
+ * If a copy of the EUPL was not distributed with this file, You can obtain
+ * one at https://opensource.org/licenses/EUPL-1.2.
+ *
+ * The 'Compatible Licences' set out in the Appendix to the EUPL (as may be
+ * amended by the European Commission) shall be deemed incompatible for
+ * the purposes of the Work and the provisions of the compatibility
+ * clause in Article 5 of the EUPL shall not apply.
+ *
+ * If using the Work as, or as part of, a network application, by
+ * including the attribution notice(s) required under Article 5 of the EUPL
+ * in the end user terms of the application under an appropriate heading,
+ * such notice(s) shall fulfill the requirements of that article.
+ * ********************************************************************* */
+
+// Ensure the Web Crypto and base64 globals owid-js relies on are present in
+// the Jest sandbox. In a normal Node 19+ runtime these already exist.
+const { webcrypto } = require('crypto');
+
+if (!globalThis.crypto) {
+  globalThis.crypto = webcrypto;
+}
+if (typeof globalThis.atob !== 'function') {
+  globalThis.atob = (b64) => Buffer.from(b64, 'base64').toString('binary');
+}
+if (typeof globalThis.btoa !== 'function') {
+  globalThis.btoa = (bin) => Buffer.from(bin, 'binary').toString('base64');
+}