fiftyone.pipeline.did 4.5.35 → 4.5.37

package/didClient.js

@@ -69,6 +69,19 @@ const ContextResult = Object.freeze({
   NO_CONTEXT: 'nocontext',
   /** The service holds no secret covering the identifier's date. */
   NOT_CHECKABLE: 'notcheckable',
+  /**
+   * The service that checked the identifier could not complete the check,
+   * and the reason is that service rather than the identifier. It either
+   * compared nothing, or compared some factors and reports at least one as
+   * `misconfigured` in `factors`. Nothing a caller sends can produce it.
+   */
+  MISCONFIGURED: 'misconfigured',
+  /**
+   * The creation date is one the scheme could not have produced, being in
+   * the future or before the creator context scheme began, so the
+   * identifier is fabricated rather than the service being wrong.
+   */
+  INVALID_DATE: 'invaliddate',
   /** The sealed result was redeemed outside the freshness window. */
   EXPIRED: 'expired',
   /** The sealed result had already been redeemed on that instance. */
@@ -102,7 +115,13 @@ const SignatureResult = Object.freeze({
  */
 const FactorResult = Object.freeze({
   VERIFIED: 'verified',
-  MISMATCH: 'mismatch'
+  MISMATCH: 'mismatch',
+  /**
+   * The service that checked the identifier is not configured to determine
+   * this factor, so it could not have checked it for any request. This is
+   * NOT a mismatch and must not be read as one.
+   */
+  MISCONFIGURED: 'misconfigured'
 });
 
 /**
@@ -776,7 +795,7 @@ function dateOf (fodId) {
 function payloadLengthValid (fodId) {
   const matchKeyLength = fodId.type === IdType.RANDOM
     ? FodId.GUID_LENGTH
-    : FodId.HASH_LENGTH;
+    : FodId.MATCH_KEY_LENGTH;
   return fodId.payload.length >= FodId.HEADER_LENGTH + matchKeyLength;
 }
 

package/examples/fodIdExample.js

@@ -50,7 +50,9 @@ function samplePayload () {
   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; }
+  for (let i = 0; i < FodId.MATCH_KEY_LENGTH; i++) {
+    p[FodId.MATCH_KEY_OFFSET + i] = 0x20 + i;
+  }
   return p;
 }
 

package/fodId.js

@@ -88,17 +88,35 @@ class FodId {
   static LICENSE_ID_OFFSET = 1;
   static LICENSE_ID_LENGTH = 4;
   /** Byte offset of the match key field within the payload. */
-  static HASH_OFFSET = 5;
+  static MATCH_KEY_OFFSET = 5;
   /**
    * Byte length of the match key field for Probabilistic and HashedEmail
    * identifiers, being a SHA-256.
    */
-  static HASH_LENGTH = 32;
-  static HEADER_LENGTH = 5;
+  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 = 37;
+  static PAYLOAD_LENGTH = FodId.MATCH_KEY_OFFSET + FodId.MATCH_KEY_LENGTH;
 
   /**
    * Why a read succeeded or failed, being the OWID library's statuses plus
@@ -471,7 +489,7 @@ function unpack (payload) {
     // is the match key.
     matchKeyLength = length - FodId.HEADER_LENGTH;
   } else {
-    matchKeyLength = FodId.HASH_LENGTH;
+    matchKeyLength = FodId.MATCH_KEY_LENGTH;
   }
   const required = FodId.HEADER_LENGTH + matchKeyLength;
   if (length < required) {
@@ -488,7 +506,7 @@ function unpack (payload) {
     licenseId,
     // slice() copies, so the stored match key is this identifier's own.
     matchKey: payload.slice(
-      FodId.HASH_OFFSET, FodId.HASH_OFFSET + matchKeyLength),
+      FodId.MATCH_KEY_OFFSET, FodId.MATCH_KEY_OFFSET + matchKeyLength),
     length,
     required
   };

package/idType.js

@@ -49,8 +49,8 @@ const IdType = Object.freeze({
 
   /**
    * The human-readable name of an IdType value.
-   * @param {number} type an IdType value
-   * @returns {string}
+   * @param {number} type an IdType value, being 0 to 3 as fromFlags returns
+   * @returns {string} the name of that type, for example "Probabilistic"
    */
   name (type) {
     return NAMES[type];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fiftyone.pipeline.did",
-  "version": "4.5.35",
+  "version": "4.5.37",
   "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 match key plus the identifier type. Compare match keys, never envelopes.",
   "keywords": [
     "51degrees",

package/tests/envelope.js

@@ -37,7 +37,7 @@ const CANONICAL_LICENSE_ID = 0x12345678;
 const OWID_EPOCH_MS = Date.UTC(2020, 0, 1);
 
 function canonicalMatchKey () {
-  const h = new Uint8Array(FodId.HASH_LENGTH);
+  const h = new Uint8Array(FodId.MATCH_KEY_LENGTH);
   for (let i = 0; i < h.length; i++) { h[i] = 0x20 + i; }
   return h;
 }
@@ -54,7 +54,7 @@ function canonicalPayload () {
   const p = new Uint8Array(FodId.PAYLOAD_LENGTH);
   p[FodId.FLAGS_OFFSET] = CANONICAL_FLAGS;
   writeLicenseId(p);
-  p.set(canonicalMatchKey(), FodId.HASH_OFFSET);
+  p.set(canonicalMatchKey(), FodId.MATCH_KEY_OFFSET);
   return p;
 }
 
@@ -63,7 +63,7 @@ function canonicalRandomPayload () {
   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;
+    p[FodId.MATCH_KEY_OFFSET + i] = 0x40 + i;
   }
   return p;
 }

package/tests/fodId.test.js

@@ -43,10 +43,11 @@ describe('FodId', () => {
   // ----- Current .NET coverage -----
 
   test('constants are internally consistent', () => {
-    expect(FodId.HASH_OFFSET + FodId.HASH_LENGTH).toBe(FodId.PAYLOAD_LENGTH);
+    expect(FodId.MATCH_KEY_OFFSET + FodId.MATCH_KEY_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.MATCH_KEY_OFFSET);
+    expect(FodId.MATCH_KEY_OFFSET + FodId.GUID_LENGTH)
       .toBe(FodId.RANDOM_PAYLOAD_LENGTH);
   });
 
@@ -128,9 +129,9 @@ describe('FodId', () => {
     const fod = FodId.fromBase64(envelopeBase64(canonicalPayload()));
     const k = fod.matchKey;
     k[0] = 0x00;
-    k[FodId.HASH_LENGTH - 1] = 0x00;
+    k[FodId.MATCH_KEY_LENGTH - 1] = 0x00;
     expect(fod.matchKey).toEqual(canonicalMatchKey());
-    expect(fod.payload[FodId.HASH_OFFSET]).toBe(0x20);
+    expect(fod.payload[FodId.MATCH_KEY_OFFSET]).toBe(0x20);
   });
 
   test('the deprecated hash getter returns the match key', () => {
@@ -175,7 +176,7 @@ describe('FodId', () => {
     expect(fod.flags).toBe(CANONICAL_FLAGS);
     expect(fod.licenseId).toBe(CANONICAL_LICENSE_ID);
     expect(fod.matchKey).toEqual(canonicalMatchKey());
-    expect(fod.matchKey.length).toBe(FodId.HASH_LENGTH);
+    expect(fod.matchKey.length).toBe(FodId.MATCH_KEY_LENGTH);
   });
 
   test('a long context section and a long creator domain both parse', () => {
@@ -286,7 +287,7 @@ describe('FodId', () => {
   });
 
   test('Reserved header-only payload parses', () => {
-    const p = new Uint8Array(FodId.HASH_OFFSET);
+    const p = new Uint8Array(FodId.MATCH_KEY_OFFSET);
     p[FodId.FLAGS_OFFSET] = 0b1100_0000;
     const fod = FodId.fromBase64(envelopeBase64(p));
     expect(fod.type).toBe(IdType.RESERVED);
@@ -304,7 +305,7 @@ describe('FodId', () => {
     const fb = FodId.fromBase64(b);
 
     expect(fa.matchKey).toEqual(fb.matchKey); // match key is stable
-    expect(fa.date).not.toBe(fb.date);           // envelope differs
+    expect(fa.date).not.toBe(fb.date); // envelope differs
     expect(fa.signature).not.toEqual(fb.signature);
     expect(a).not.toBe(b);
   });
@@ -325,11 +326,11 @@ describe('FodId', () => {
     const o = owid.parse(envelopeBase64(canonicalPayload())).owid;
     const fod = FodId.fromOwid(o);
     expect(Object.isFrozen(o)).toBe(true);
-    o.payload[FodId.HASH_OFFSET] = 0x00; // writes into a copy
-    expect(o.payload[FodId.HASH_OFFSET]).toBe(0x20);
+    o.payload[FodId.MATCH_KEY_OFFSET] = 0x00; // writes into a copy
+    expect(o.payload[FodId.MATCH_KEY_OFFSET]).toBe(0x20);
     expect(fod.matchKey).toEqual(canonicalMatchKey());
     expect(fod.flags).toBe(CANONICAL_FLAGS);
-    expect(fod.payload[FodId.HASH_OFFSET]).toBe(0x20);
+    expect(fod.payload[FodId.MATCH_KEY_OFFSET]).toBe(0x20);
   });
 
   test('constructor is decoupled from the source owid', () => {
@@ -338,10 +339,10 @@ describe('FodId', () => {
     const o = owid.parse(envelopeBase64(canonicalPayload())).owid;
     const fod = new FodId(o);
     expect(fod._owid).not.toBe(o);
-    fod.payload[FodId.HASH_OFFSET] = 0x00; // writes into a copy
+    fod.payload[FodId.MATCH_KEY_OFFSET] = 0x00; // writes into a copy
     expect(fod.matchKey).toEqual(canonicalMatchKey());
     expect(fod.flags).toBe(CANONICAL_FLAGS);
-    expect(fod.payload[FodId.HASH_OFFSET]).toBe(0x20);
+    expect(fod.payload[FodId.MATCH_KEY_OFFSET]).toBe(0x20);
   });
 
   test('verify with the wrong key returns false', async () => {
@@ -367,9 +368,9 @@ describe('FodId', () => {
   function alphabetPayload () {
     const p = canonicalPayload();
     // 0xFB 0xFF 0xBF encodes to "+/+/" in standard base64.
-    p[FodId.HASH_OFFSET] = 0xFB;
-    p[FodId.HASH_OFFSET + 1] = 0xFF;
-    p[FodId.HASH_OFFSET + 2] = 0xBF;
+    p[FodId.MATCH_KEY_OFFSET] = 0xFB;
+    p[FodId.MATCH_KEY_OFFSET + 1] = 0xFF;
+    p[FodId.MATCH_KEY_OFFSET + 2] = 0xBF;
     return p;
   }
 

package/types/didClient.d.ts

@@ -345,6 +345,8 @@ export const ContextResult: Readonly<{
     NO_CONTEXT: "nocontext";
     /** The service holds no secret covering the identifier's date. */
     NOT_CHECKABLE: "notcheckable";
+    MISCONFIGURED: "misconfigured";
+    INVALID_DATE: "invaliddate";
     /** The sealed result was redeemed outside the freshness window. */
     EXPIRED: "expired";
     /** The sealed result had already been redeemed on that instance. */
@@ -369,12 +371,14 @@ export const SignatureResult: Readonly<{
     UNKNOWN: "unknown";
 }>;
 /**
- * The outcome of one factor in a mismatch. The cloud reports `null` for a
+ * The outcome of one factor in a mismatch or a partly misconfigured
+ * result. The cloud reports `null` for a
  * factor that was not compared, which is passed through unchanged.
  */
 export const FactorResult: Readonly<{
     VERIFIED: "verified";
     MISMATCH: "mismatch";
+    MISCONFIGURED: "misconfigured";
 }>;
 /**
  * The reason a {@link DidClient#verifySignatureDetailed} answer was given.

package/types/fodId.d.ts

@@ -39,11 +39,29 @@ declare class FodId {
     static LICENSE_ID_OFFSET: number;
     static LICENSE_ID_LENGTH: number;
     /** Byte offset of the match key field within the payload. */
-    static HASH_OFFSET: number;
+    static MATCH_KEY_OFFSET: number;
     /**
      * Byte length of the match key field for Probabilistic and HashedEmail
      * identifiers, being a SHA-256.
      */
+    static MATCH_KEY_LENGTH: number;
+    /**
+     * 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: number;
+    /**
+     * 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: number;
     static HEADER_LENGTH: number;
     /** Byte length of the GUID match key carried by Random identifiers. */

package/types/idType.d.ts

@@ -22,8 +22,8 @@ declare const IdType: Readonly<{
     fromFlags(flags: number): number;
     /**
      * The human-readable name of an IdType value.
-     * @param {number} type an IdType value
-     * @returns {string}
+     * @param {number} type an IdType value, being 0 to 3 as fromFlags returns
+     * @returns {string} the name of that type, for example "Probabilistic"
      */
     name(type: number): string;
 }>;