fiftyone.pipeline.did 4.5.38 → 4.5.40

package/didClient.js

@@ -21,6 +21,7 @@
  * ********************************************************************* */
 
 const FodId = require('./fodId');
+const layout = require('./internal/layout');
 const IdType = require('./idType');
 const packageVersion = require('./package.json').version;
 
@@ -777,7 +778,7 @@ function ensureEncodedLength (value) {
  * @returns {Date} the moment the envelope says it was created
  */
 function dateOf (fodId) {
-  return new Date(OWID_EPOCH_MS + fodId.dateMinutes * MINUTE_MS);
+  return new Date(OWID_EPOCH_MS + fodId.date * MINUTE_MS);
 }
 
 /**
@@ -794,9 +795,9 @@ function dateOf (fodId) {
  */
 function payloadLengthValid (fodId) {
   const matchKeyLength = fodId.type === IdType.RANDOM
-    ? FodId.GUID_LENGTH
-    : FodId.MATCH_KEY_LENGTH;
-  return fodId.payload.length >= FodId.HEADER_LENGTH + matchKeyLength;
+    ? layout.GUID_LENGTH
+    : layout.MATCH_KEY_LENGTH;
+  return fodId.payload.length >= layout.HEADER_LENGTH + matchKeyLength;
 }
 
 /**

package/examples/fodIdExample.js

@@ -25,15 +25,20 @@
  *
  * 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
+ * an ECDSA P-256 key pair, sign a canonical payload - then parses it back
+ * and prints the 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 match key is stable. Compare match keys, never
  * envelopes.
  */
 
 const { webcrypto } = require('crypto');
-const { FodId, IdType } = require('../index');
+const { FodId, IdType, Usage } = require('../index');
+// The payload byte layout is internal to the package, so a consumer
+// never reaches for it. This example builds a sample 51Did to work on,
+// which the cloud would otherwise issue, so it reads the layout from
+// inside the package.
+const layout = require('../internal/layout');
 
 const subtle = webcrypto.subtle;
 const VERSION = 2;
@@ -45,14 +50,27 @@ function uint32LE (v) {
 }
 
 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.MATCH_KEY_LENGTH; i++) {
-    p[FodId.MATCH_KEY_OFFSET + i] = 0x20 + i;
+  // One byte longer than the least length, because the terms byte follows
+  // the match key. A 51Did whose payload stops at the match key carries
+  // no terms byte and reads as Terms.NOT_STATED.
+  const p = new Uint8Array(layout.PAYLOAD_LENGTH + layout.TERMS_LENGTH);
+  // Bits 6 and 7 are zero, so the type is Probabilistic. Bits 4 and 5 are
+  // zero, so the payload version is 0, which is the layout this package
+  // reads. Bits 0 to 2 are the usage and they are cumulative, so 0b011
+  // grants standard marketing and, with it, non-marketing use.
+  p[layout.FLAGS_OFFSET] = 0b0000_0011;
+  p[layout.LICENSE_ID_OFFSET] = 0x78;
+  p[layout.LICENSE_ID_OFFSET + 1] = 0x56;
+  p[layout.LICENSE_ID_OFFSET + 2] = 0x34;
+  p[layout.LICENSE_ID_OFFSET + 3] = 0x12;
+  for (let i = 0; i < layout.MATCH_KEY_LENGTH; i++) {
+    p[layout.MATCH_KEY_OFFSET + i] = 0x20 + i;
   }
+  // The terms document this sample was created under, being index 1, the
+  // Model Terms for Marketing version 2. The byte is an index into a table
+  // in the specification and is not a version number, and an issuer writes
+  // it for every marketing identifier.
+  p[layout.PAYLOAD_LENGTH] = 1;
   return p;
 }
 
@@ -94,9 +112,11 @@ async function run () {
   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('  Usage     :', Usage.name(fodId.usage));
+  console.log('  From cons.:', fodId.usageFromConsent);
   console.log('  LicenseId :', fodId.licenseId);
   console.log('  Match key :', Buffer.from(fodId.matchKey).toString('hex'));
+  console.log('  Terms     :', fodId.terms);
   console.log('  Verifies  :', await fodId.verify(publicPem));
 
   // Re-issue the same payload at a later time. The envelope differs and the
@@ -129,7 +149,7 @@ async function run () {
       ', status ' + result.status);
   }
   const shortPayload = await issue(
-    keyPair.privateKey, payload.slice(0, FodId.PAYLOAD_LENGTH - 1), DATE);
+    keyPair.privateKey, payload.slice(0, layout.PAYLOAD_LENGTH - 1), DATE);
   const short = FodId.tryParse(shortPayload);
   console.log('  a payload one byte short -> ok ' + short.ok +
     ', status ' + short.status);

package/fodId.js

@@ -21,7 +21,10 @@
  * ********************************************************************* */
 
 const owid = require('owid');
+const layout = require('./internal/layout');
 const IdType = require('./idType');
+const Usage = require('./usage');
+const Terms = require('./internal/terms');
 const FodIdParseError = require('./fodIdParseError');
 
 /**
@@ -44,7 +47,15 @@ const ParseStatus = Object.freeze(Object.assign({}, owid.ParseStatus, {
    * the match key that type carries after the header (16 GUID bytes for
    * Random, 32 hash bytes for Probabilistic and HashedEmail).
    */
-  INVALID_TYPE_PAYLOAD_LENGTH: 'InvalidTypePayloadLength'
+  INVALID_TYPE_PAYLOAD_LENGTH: 'InvalidTypePayloadLength',
+  /**
+   * Bits 4 and 5 of the flags byte name a payload layout version this
+   * package does not know, so no field is read. A later version exists
+   * precisely because a field moved, so reading the payload under the
+   * layout this package knows would answer with values that are wrong
+   * rather than absent.
+   */
+  UNSUPPORTED_PAYLOAD_VERSION: 'UnsupportedPayloadVersion'
 }));
 
 /**
@@ -82,42 +93,17 @@ const ParseStatus = Object.freeze(Object.assign({}, owid.ParseStatus, {
  * A FodId composes the OWID the OWID library read (holds it and delegates
  * the envelope fields to it). That OWID is frozen and hands out its byte
  * arrays as copies, so nothing a caller holds can change the identifier.
+ *
+ * Every field has a named accessor here, so nothing needs the payload
+ * bytes or their offsets. The byte layout itself is specified once for all
+ * languages, and that specification is the authority rather than this
+ * comment:
+ * https://github.com/51Degrees/specifications/blob/main/did-specification/identifier-layout.md
+ *
+ * What each 51Did package offers on top of that layout is specified at:
+ * https://github.com/51Degrees/specifications/blob/main/did-specification/package-surface.md
  */
 class FodId {
-  static FLAGS_OFFSET = 0;
-  static LICENSE_ID_OFFSET = 1;
-  static LICENSE_ID_LENGTH = 4;
-  /** Byte offset of the match key field within the payload. */
-  static MATCH_KEY_OFFSET = 5;
-  /**
-   * Byte length of the match key field for Probabilistic and HashedEmail
-   * identifiers, being a SHA-256.
-   */
-  static MATCH_KEY_LENGTH = 32;
-  /**
-   * Deprecated alias for {@link FodId.MATCH_KEY_OFFSET}. The stable,
-   * comparable part of a 51Did is now called the match key, mirroring the
-   * Model Terms for Marketing vocabulary. This alias will be removed in a
-   * future release.
-   * @deprecated Renamed to MATCH_KEY_OFFSET. This alias will be removed in
-   * a future release.
-   */
-  static HASH_OFFSET = FodId.MATCH_KEY_OFFSET;
-  /**
-   * Deprecated alias for {@link FodId.MATCH_KEY_LENGTH}. The stable,
-   * comparable part of a 51Did is now called the match key, mirroring the
-   * Model Terms for Marketing vocabulary. This alias will be removed in a
-   * future release.
-   * @deprecated Renamed to MATCH_KEY_LENGTH. This alias will be removed in
-   * a future release.
-   */
-  static HASH_LENGTH = FodId.MATCH_KEY_LENGTH;
-  static HEADER_LENGTH = FodId.MATCH_KEY_OFFSET;
-  /** Byte length of the GUID match key carried by Random identifiers. */
-  static GUID_LENGTH = 16;
-  static RANDOM_PAYLOAD_LENGTH = 21;
-  static PAYLOAD_LENGTH = FodId.MATCH_KEY_OFFSET + FodId.MATCH_KEY_LENGTH;
-
   /**
    * Why a read succeeded or failed, being the OWID library's statuses plus
    * `PAYLOAD_TOO_SHORT` and `INVALID_TYPE_PAYLOAD_LENGTH`. Frozen.
@@ -167,6 +153,8 @@ class FodId {
     this._licenseId = read.value._licenseId;
     /** @type {Uint8Array} this identifier's own copy of the match key bytes */
     this._matchKey = read.value._matchKey;
+    /** @type {number} the terms index, zero where the payload carries none */
+    this._termsIndex = read.value._termsIndex;
   }
 
   /**
@@ -303,16 +291,31 @@ class FodId {
     return new FodId(owidInstance);
   }
 
-  /** @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);
   }
 
+  /**
+   * The Usage carried in bits 0-2 of the flags, as the highest usage
+   * granted. See Usage for why it is read that way.
+   * @returns {number} a Usage value
+   */
+  get usage () {
+    return Usage.fromFlags(this._flags);
+  }
+
+  /**
+   * Whether the usage was derived from an IAB consent string the caller
+   * sent, rather than stated by the caller directly. Bit 3 of the flags.
+   * Both are legitimate ways to arrive at a usage, and this says nothing
+   * about which usage it is.
+   * @returns {boolean}
+   */
+  get usageFromConsent () {
+    return (this._flags & 0b1000) !== 0;
+  }
+
   /**
    * The 4-byte little-endian field at offset 1 of the payload, as an
    * unsigned integer (0-4294967295).
@@ -342,16 +345,26 @@ class FodId {
   }
 
   /**
-   * Deprecated alias for {@link FodId#matchKey}. The stable, comparable
-   * part of a 51Did is now called the match key, mirroring the Model Terms
-   * for Marketing vocabulary. This alias will be removed in a future
-   * release.
-   * @deprecated Renamed to matchKey. This alias will be removed in a future
-   * release.
-   * @returns {Uint8Array} the same bytes as {@link FodId#matchKey}
+   * The address of the terms document this 51Did was created under, read
+   * from the byte after the match key. The byte is an index into a table
+   * in the specification and this package turns the index into the
+   * address, so a caller never handles the byte. Nothing here fetches the
+   * address, because what to do with the document is the caller's
+   * decision.
+   *
+   * Null covers both an index of zero, which says the terms are not
+   * stated in the identifier, and an index added to the table after this
+   * package was released, which it cannot name. A caller cannot tell
+   * those two apart, which is deliberate, because both lead to the same
+   * place, being that the identifier does not say which terms it was
+   * created under and the answer has to come from somewhere else. No
+   * address is ever built from an index, since that would name a document
+   * nobody wrote.
+   * @returns {string|null} the address, or null where the identifier names
+   * no document this package knows, which is never an empty string
    */
-  get hash () {
-    return this.matchKey;
+  get terms () {
+    return Terms.url(Terms.fromIndex(this._termsIndex));
   }
 
   /** @returns {number} the OWID version. */
@@ -365,24 +378,13 @@ class FodId {
   }
 
   /**
-   * @returns {number} the OWID date as minutes since 2020-01-01 UTC, as an
-   * unsigned 32-bit number, the same value as {@link FodId#dateMinutes}.
-   */
-  get date () {
-    return this._owid.date;
-  }
-
-  /**
-   * The envelope's own date as the unsigned 32-bit count of minutes since
-   * 2020-01-01T00:00:00Z, exactly as the wire carries it. This is the value
-   * the OWID `public-key?date=` parameter takes, and the integer to use when
-   * comparing creation times. The OWID library now reads the field unsigned
-   * too, so {@link FodId#date} agrees with this getter. The getter is kept
-   * because callers were told to use it, and it still forces the unsigned
-   * reading should the field ever arrive signed.
+   * The envelope's own date, being the count of minutes since
+   * 2020-01-01T00:00:00Z exactly as the wire carries it, read as an
+   * unsigned 32-bit number. This is the integer to compare when asking
+   * which of two identifiers was issued first.
    * @returns {number} minutes since 2020-01-01T00:00:00Z
    */
-  get dateMinutes () {
+  get date () {
     return this._owid.date >>> 0;
   }
 
@@ -453,45 +455,62 @@ class FodId {
  * Reads the 51Did fields out of an envelope payload, answering with a
  * status rather than throwing. This is the one walk of the payload, shared
  * by every surface that reads a 51Did. The type is read from the header and
- * decides the least the payload must hold after the header. Anything beyond
- * the match key is a creator context section whose lengths belong to the
- * cloud, so a longer payload is accepted whatever its length.
+ * decides the least the payload must hold after the header. The terms byte
+ * follows the match key, and anything beyond the terms byte is a creator
+ * context section whose lengths belong to the cloud, so a longer payload is
+ * accepted whatever its length.
  * @param {Uint8Array} payload the payload bytes
  * @returns {{status: string, flags?: number, licenseId?: number,
- * matchKey?: Uint8Array, length: number, required: number, type?: number}}
- * `status` PARSED with the fields, or a 51Did status with the length the
- * type needed
+ * matchKey?: Uint8Array, termsIndex?: number, length: number,
+ * required: number, type?: number, payloadVersion?: number}} `status`
+ * PARSED with the fields, or a 51Did status with the length the type
+ * needed, and the version found where that is what the payload was refused
+ * for
  */
 function unpack (payload) {
   const length = payload.length;
-  if (length < FodId.HEADER_LENGTH) {
+  if (length < layout.HEADER_LENGTH) {
     return {
       status: ParseStatus.PAYLOAD_TOO_SHORT,
       length,
-      required: FodId.HEADER_LENGTH
+      required: layout.HEADER_LENGTH
+    };
+  }
+  const flags = payload[layout.FLAGS_OFFSET];
+  // The version is read before any field, because a later version exists
+  // precisely because a field moved. Reading a payload of a version this
+  // package does not know under the layout it does know would answer with
+  // values that are wrong rather than absent, which is worse than
+  // refusing, and a version that nothing checks protects nothing.
+  const payloadVersion = (flags >> 4) & 0b11;
+  if (payloadVersion !== layout.SUPPORTED_PAYLOAD_VERSION) {
+    return {
+      status: ParseStatus.UNSUPPORTED_PAYLOAD_VERSION,
+      length,
+      required: layout.HEADER_LENGTH,
+      payloadVersion
     };
   }
-  const flags = payload[FodId.FLAGS_OFFSET];
   // Little-endian unsigned 32-bit. `>>> 0` forces unsigned so the high bit
   // does not produce a negative number.
   const 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)
+    payload[layout.LICENSE_ID_OFFSET] |
+    (payload[layout.LICENSE_ID_OFFSET + 1] << 8) |
+    (payload[layout.LICENSE_ID_OFFSET + 2] << 16) |
+    (payload[layout.LICENSE_ID_OFFSET + 3] << 24)
   ) >>> 0;
   const type = IdType.fromFlags(flags);
   let matchKeyLength;
   if (type === IdType.RANDOM) {
-    matchKeyLength = FodId.GUID_LENGTH;
+    matchKeyLength = layout.GUID_LENGTH;
   } else if (type === IdType.RESERVED) {
     // Not yet assigned, so read best-effort, whatever follows the header
     // is the match key.
-    matchKeyLength = length - FodId.HEADER_LENGTH;
+    matchKeyLength = length - layout.HEADER_LENGTH;
   } else {
-    matchKeyLength = FodId.MATCH_KEY_LENGTH;
+    matchKeyLength = layout.MATCH_KEY_LENGTH;
   }
-  const required = FodId.HEADER_LENGTH + matchKeyLength;
+  const required = layout.HEADER_LENGTH + matchKeyLength;
   if (length < required) {
     return {
       status: ParseStatus.INVALID_TYPE_PAYLOAD_LENGTH,
@@ -500,13 +519,28 @@ function unpack (payload) {
       type
     };
   }
+  // The terms byte sits after the match key, so where it sits follows the
+  // match key length the type selects. A payload with no byte to read is a
+  // terms index of zero, which says the terms are not stated, so absence
+  // and zero are the same answer and neither has to be told from the
+  // other.
+  //
+  // A Reserved type cannot carry a terms byte this reader can find, because
+  // the match key length for that type is not defined and every byte after
+  // the header is therefore the match key. Such an identifier reads as a
+  // terms index of zero, which is correct and is not a missing case here.
+  const termsOffset = layout.MATCH_KEY_OFFSET + matchKeyLength;
+  const termsIndex = termsOffset + layout.TERMS_LENGTH <= length
+    ? payload[termsOffset]
+    : Terms.NOT_STATED;
   return {
     status: ParseStatus.PARSED,
     flags,
     licenseId,
     // slice() copies, so the stored match key is this identifier's own.
     matchKey: payload.slice(
-      FodId.MATCH_KEY_OFFSET, FodId.MATCH_KEY_OFFSET + matchKeyLength),
+      layout.MATCH_KEY_OFFSET, layout.MATCH_KEY_OFFSET + matchKeyLength),
+    termsIndex,
     length,
     required
   };
@@ -537,6 +571,7 @@ function readEnvelope (read) {
   fodId._flags = unpacked.flags;
   fodId._licenseId = unpacked.licenseId;
   fodId._matchKey = unpacked.matchKey;
+  fodId._termsIndex = unpacked.termsIndex;
   return { ok: true, value: fodId, status: ParseStatus.PARSED };
 }
 
@@ -581,7 +616,7 @@ function valueOrThrow (read) {
 }
 
 /**
- * The exception for a failed read. The two 51Did payload statuses keep the
+ * The exception for a failed read. The three 51Did payload statuses keep the
  * RangeError this package has always thrown for them, and every OWID status
  * is a FodIdParseError carrying the status. Each error carries `status` so
  * the reason can be acted on without reading the message.
@@ -599,6 +634,10 @@ function errorFor (read) {
       `51Did payload for the ${IdType.name(read.detail.type)} type must be ` +
       `at least ${read.detail.required} bytes, and ${read.detail.length} ` +
       'were given.');
+  } else if (read.status === ParseStatus.UNSUPPORTED_PAYLOAD_VERSION) {
+    error = new RangeError(
+      `51Did payload version ${read.detail.payloadVersion} is not one this ` +
+      'package can read.');
   } else {
     return new FodIdParseError(read.status);
   }

package/fodIdParseError.js

@@ -26,7 +26,7 @@
  * constructor) when the OWID library refused the envelope. The status names
  * the reason in the same vocabulary the non-throwing surfaces report, so a
  * caller catching this can act on the reason without reading the message.
- * The two 51Did payload statuses are thrown as RangeError instead, as this
+ * The three 51Did payload statuses are thrown as RangeError instead, as this
  * package has always thrown them, and that RangeError carries `status` too.
  */
 class FodIdParseError extends Error {

package/index.js

@@ -23,6 +23,7 @@
 const FodId = require('./fodId');
 const FodIdParseError = require('./fodIdParseError');
 const IdType = require('./idType');
+const Usage = require('./usage');
 const {
   DidClient,
   RedeemResult,
@@ -39,6 +40,7 @@ module.exports = {
   FodId,
   FodIdParseError,
   IdType,
+  Usage,
   DidClient,
   RedeemResult,
   ContextResult,

package/internal/layout.js

@@ -0,0 +1,77 @@
+/* *********************************************************************
+ * 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.
+ * ********************************************************************* */
+
+/**
+ * The byte layout of a 51Did payload. Internal to this package, because the
+ * only reason to read the payload by hand is to read a field that already
+ * has a name on FodId, and reading the flags byte by hand is how the usage
+ * comes out backwards. The usage bits are cumulative, so a caller masking
+ * for the non-marketing bit alone reads every marketing identifier as
+ * non-marketing. Use the FodId accessors instead.
+ *
+ * The layout is described once for every language in the 51Did
+ * specification, which is the authority for these numbers:
+ * https://github.com/51Degrees/specifications/blob/main/did-specification/identifier-layout.md
+ *
+ * What each package offers on top of that layout is described in:
+ * https://github.com/51Degrees/specifications/blob/main/did-specification/package-surface.md
+ */
+module.exports = Object.freeze({
+  /** Byte offset of the flags byte within the payload. */
+  FLAGS_OFFSET: 0,
+  /** Byte offset of the licence id field within the payload. */
+  LICENSE_ID_OFFSET: 1,
+  /** Byte length of the licence id field. */
+  LICENSE_ID_LENGTH: 4,
+  /** Byte offset of the match key field within the payload. */
+  MATCH_KEY_OFFSET: 5,
+  /**
+   * Byte length of the match key field for Probabilistic and HashedEmail
+   * identifiers, being a SHA-256.
+   */
+  MATCH_KEY_LENGTH: 32,
+  /**
+   * Byte length of the terms field, which follows the match key. Its
+   * offset is not a constant here, because the match key length depends on
+   * the identifier type, so the offset is worked out from the type. A
+   * payload that ends at the match key carries no terms byte and reads as
+   * a terms index of zero, so the least payload lengths below do not
+   * include it.
+   */
+  TERMS_LENGTH: 1,
+  /** Byte length of the flags and licence id fields together. */
+  HEADER_LENGTH: 5,
+  /** Byte length of the GUID match key carried by Random identifiers. */
+  GUID_LENGTH: 16,
+  /**
+   * The payload layout version this package reads, carried in bits 4 and
+   * 5 of the flags byte. Any other version is refused rather than read
+   * under this layout.
+   */
+  SUPPORTED_PAYLOAD_VERSION: 0,
+  /** Least payload length for a Random identifier. */
+  RANDOM_PAYLOAD_LENGTH: 21,
+  /**
+   * Least payload length for a Probabilistic or HashedEmail identifier.
+   */
+  PAYLOAD_LENGTH: 37
+});