fiftyone.pipeline.did 4.5.38 → 4.5.39

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

@@ -33,7 +33,12 @@
  */
 
 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,13 +50,17 @@ 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;
+  const p = new Uint8Array(layout.PAYLOAD_LENGTH);
+  // Bits 6 and 7 are zero, so the type is Probabilistic. 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;
   }
   return p;
 }
@@ -94,7 +103,8 @@ 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('  Verifies  :', await fodId.verify(publicPem));
@@ -129,7 +139,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,9 @@
  * ********************************************************************* */
 
 const owid = require('owid');
+const layout = require('./internal/layout');
 const IdType = require('./idType');
+const Usage = require('./usage');
 const FodIdParseError = require('./fodIdParseError');
 
 /**
@@ -82,42 +84,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.
@@ -303,16 +280,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).
@@ -341,19 +333,6 @@ class FodId {
     return this._matchKey.slice();
   }
 
-  /**
-   * 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}
-   */
-  get hash () {
-    return this.matchKey;
-  }
-
   /** @returns {number} the OWID version. */
   get version () {
     return this._owid.version;
@@ -365,24 +344,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;
   }
 
@@ -464,34 +432,34 @@ class FodId {
  */
 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[FodId.FLAGS_OFFSET];
+  const flags = payload[layout.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,
@@ -506,7 +474,7 @@ function unpack (payload) {
     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),
     length,
     required
   };

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,62 @@
+/* *********************************************************************
+ * 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 flags and licence id fields together. */
+  HEADER_LENGTH: 5,
+  /** Byte length of the GUID match key carried by Random identifiers. */
+  GUID_LENGTH: 16,
+  /** Least payload length for a Random identifier. */
+  RANDOM_PAYLOAD_LENGTH: 21,
+  /**
+   * Least payload length for a Probabilistic or HashedEmail identifier.
+   */
+  PAYLOAD_LENGTH: 37
+});

package/node_modules/owid/owid.crypto.test.js

@@ -227,6 +227,33 @@ test('crypto verify asks the end point for the version the OWID carries', () =>
     });
 });
 
+// A creator whose domain answers with a redirect does not get the key at
+// the other end trusted as its own. The library asks fetch not to follow,
+// so the answer is the redirect itself, which is not ok and reads as the
+// key being unavailable, and no second request is made. Without this a
+// network attacker able to bend a creator's DNS, or a misconfigured
+// creator, could substitute the key, and the publisher's fetchHeaders
+// credential would travel to wherever the redirect pointed.
+test('crypto verify does not follow a redirect from the creator', () => {
+    var redirectDomain = "redirecting.example";
+    fetchMock.mockResponse(req => {
+        return Promise.resolve({
+            status: 302,
+            headers: { Location: "https://elsewhere.example/key.pem" },
+            body: ""
+        });
+    });
+    var unsigned = buildUnsignedOWID(
+        redirectDomain, testDateInMinutes, Buffer.from("example"));
+    var o = read(signOWID(unsigned, creatorKeyPair.privateKey));
+
+    return o.checkSignature().then(r => {
+        expect(r.status).toBe(owid.SignatureStatus.KEY_UNAVAILABLE);
+        expect(fetch.mock.calls.length).toBe(1);
+        expect(fetch.mock.calls[0][1].redirect).toBe("manual");
+    });
+});
+
 test('crypto verify sends configured fetch headers', () => {
     var unsigned = buildUnsignedOWID(
         creatorDomain, testDateInMinutes, Buffer.from("example"));

package/node_modules/owid/v1.js

@@ -1048,9 +1048,20 @@ var owid = (function () {
         if (instance.date != null) {
             url += "?date=" + instance.date;
         }
+        // A redirect is never followed. fetch follows one by default, to
+        // any other origin, so a creator whose domain answered 302 to
+        // some other place would have that other place's key trusted
+        // as its own, and a network attacker able to bend the creator's
+        // DNS, or a creator that was simply misconfigured, could put a
+        // key there and have forgeries verify. It would also carry
+        // owid.fetchHeaders, a publisher's credential, to wherever the
+        // redirect pointed. With manual the browser hands back an opaque
+        // redirect that is not ok, which reads below as the key being
+        // unavailable, which it is.
         return fetch(url, {
             mode: "cors",
             cache: "default",
+            redirect: "manual",
             headers: owid.fetchHeaders
         }).then(function (r) {
             if (r.ok) {
@@ -1114,10 +1125,14 @@ var owid = (function () {
         body.append("parent", encodeBase64(joined));
         body.append("owid", instance.data);
         var url = creatorApiUrl(instance, "verify");
+        // Not followed either, for the same reasons as the creator
+        // request, and because a redirected POST would resend the
+        // identifier and the credential to wherever it pointed.
         return fetch(url, {
             method: "POST",
             mode: "cors",
             cache: "no-cache",
+            redirect: "manual",
             headers: owid.fetchHeaders,
             body: body
         }).then(function (r) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "fiftyone.pipeline.did",
-  "version": "4.5.38",
-  "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.",
+  "version": "4.5.39",
+  "description": "Strongly typed reader for the 51Did (51Degrees Identifier) value returned by the 51Degrees Cloud service. Parses the OWID envelope and exposes the usage, licence id and match key plus the identifier type. Compare match keys, never envelopes.",
   "keywords": [
     "51degrees",
     "51did",
@@ -11,13 +11,20 @@
   ],
   "main": "index.js",
   "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "default": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "scripts": {
     "test": "jest"
   },
   "author": "51Degrees Engineering <engineering@51degrees.com>",
   "license": "EUPL-1.2",
   "dependencies": {
-    "owid": "github:51Degrees/owid-js#9aeb0d24"
+    "owid": "github:51Degrees/owid-js#148763cb"
   },
   "bundleDependencies": [
     "owid"

package/readme.md

@@ -20,11 +20,22 @@ 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), see below               |
-|      5 |  16/32 | Match key  | SHA-256 (Probabilistic, HashedEmail) or GUID (Random) |
+The byte layout is specified once for every language in the 51Did
+specification, and that specification is the authority for it:
+
+- [Identifier layout](https://github.com/51Degrees/specifications/blob/main/did-specification/identifier-layout.md)
+- [Package surface](https://github.com/51Degrees/specifications/blob/main/did-specification/package-surface.md)
+
+Your code never needs the offsets, because every field has a named accessor,
+so the offsets and the lengths are internal to this package. Reading the flags
+byte by hand is the mistake they are kept internal to prevent, because the
+usage bits are cumulative and a mask for one of them answers the wrong
+question. The summary here explains what the accessors report, and the
+specification governs wherever the two differ.
+
+The payload carries a one byte Flags field, a four byte little-endian
+LicenseId and then the match key. Bits 6 and 7 of the flags name the
+identifier type, which decides how long the match key is.
 
 | Bits 7-6 | `IdType`        | Match key length | Least payload accepted |
 |---------:|-----------------|-----------------:|-----------------------:|
@@ -47,6 +58,36 @@ the lower bound for the identifier type, holds no upper bound of its own, and
 leaves anything longer for the cloud to judge. A reader built before a longer
 context section existed therefore still reads the identifier.
 
+## The usage a 51Did was created for
+
+Every 51Did says what it was created for, and `fodId.usage` reports it as one
+of the `Usage` values. The usage decides where the identifier may go, so it is
+read before the identifier is passed anywhere.
+
+| `Usage` | The cloud's `id.usage` | Meaning |
+| --- | --- | --- |
+| `NONE` | none | No usage bit is set. The cloud never issues such an identifier, so treat it as one that may not be passed on |
+| `NON_MARKETING` | `non-marketing` | Created for use that is not marketing. Must never be passed to a demand source |
+| `STANDARD` | `standard` | Created for standard marketing, being targeting unrelated to browsing history |
+| `PERSONALIZED` | `personalized` | Created for personalized marketing, being targeting related to browsing history |
+
+The three usages are cumulative in the flags byte rather than exclusive.
+Non-marketing sets one bit, standard sets two and personalized sets three, so
+every marketing identifier also carries the non-marketing bit. Code masking
+the byte for that bit alone would read every marketing identifier as
+non-marketing, which is the wrong way round for a rule that turns on it.
+`fodId.usage` answers with the highest usage granted, so that mistake cannot
+be made, and it is the only supported way to read the usage.
+
+`fodId.usageFromConsent` says whether the usage was worked out from an IAB
+consent string the caller sent rather than stated by the caller directly. Both
+are legitimate ways to arrive at a usage, and it says nothing about which
+usage it is.
+
+`Usage.name(usage)` gives the cross language name, for example
+`"NonMarketing"`, and `Usage.idUsage(usage)` gives the cloud's own `id.usage`
+value, for example `"non-marketing"`, or `null` for `NONE`.
+
 ## Reading a 51Did
 
 A 51Did arrives from outside, from a page, a link or a log line, so a value
@@ -134,9 +175,26 @@ the OWID library through this package changes as follows.
 | `FodId.fromOwid(new owid(s))` | `FodId.fromBase64(s)`, or `FodId.tryParse(s)` for a result |
 | `try { FodId.fromBase64(s) } catch (e) { /* e was a string */ }` | `const r = FodId.tryParse(s); if (!r.ok) { /* r.status */ }` |
 | `catch (e)` on `fromBase64` reading `e.message` | `catch (e)` reading `e.status`, one of `FodId.ParseStatus` |
-| `fodId.date` read as a signed number | `fodId.date` is now unsigned, the same value as `fodId.dateMinutes` |
+| `fodId.date` read as a signed number | `fodId.date` is now unsigned |
 | `fodId.verify(pem)` resolving `false` for a key that could not be imported | `verify` rejects when the question could not be answered, and `checkSignature(pem)` reports `INVALID_KEY` |
 
+### Migrating from the removed raw surface
+
+The raw byte and the offsets were the way to read by hand a field that already
+has a name, so they have gone. `fodId.flags`, `fodId.dateMinutes`, the
+deprecated `fodId.hash`, and the layout constants `FLAGS_OFFSET`,
+`LICENSE_ID_OFFSET`, `LICENSE_ID_LENGTH`, `MATCH_KEY_OFFSET`,
+`MATCH_KEY_LENGTH`, `HEADER_LENGTH`, `GUID_LENGTH`, `RANDOM_PAYLOAD_LENGTH`
+and `PAYLOAD_LENGTH` are no longer part of the package.
+
+| Before | After |
+| --- | --- |
+| `fodId.flags` masked for a usage bit | `fodId.usage`, and `fodId.usageFromConsent` for bit 3 |
+| `fodId.flags` masked for the type bits | `fodId.type` |
+| `fodId.hash` | `fodId.matchKey`, the same bytes under the name the Model Terms for Marketing use |
+| `fodId.dateMinutes` | `fodId.date`, which reports the same unsigned value |
+| `FodId.PAYLOAD_LENGTH` and the other layout constants | Nothing. Every field has a named accessor, and the layout is in the specification linked above |
+
 ## OWID dependency
 
 `FodId` builds on the OWID envelope library
@@ -158,7 +216,7 @@ and `FodId.checkSignature()` run without contacting a network endpoint.
 
 The library is not on the npm registry, so `package.json` names it as a
 GitHub reference, which npm resolves by cloning the repository. The reference
-is `github:51Degrees/owid-js#9aeb0d24`, the commit on `main` that carries the key selection fix
+is `github:51Degrees/owid-js#148763cb`, the commit on `main` that carries the key selection fix and refuses redirects when fetching a key
 of the [51Degrees/owid-js](https://github.com/51Degrees/owid-js) fork. That
 applies only when working in this repository, because the published
 `fiftyone.pipeline.did` package carries the OWID source inside its own
@@ -178,32 +236,28 @@ npm test
 ## Usage
 
 ```js
-const { FodId, IdType } = require('fiftyone.pipeline.did');
+const { FodId, IdType, Usage } = require('fiftyone.pipeline.did');
 
 // Either base64 alphabet is accepted, the standard one the cloud issues and
 // the URL-safe one a page puts in a link, with or without padding.
 const fodId = FodId.fromBase64(base64FromCloudService);
 
-const flags = fodId.flags;
+const usage = fodId.usage;        // Usage.NON_MARKETING / STANDARD / PERSONALIZED
+const fromConsent = fodId.usageFromConsent;
 const type = fodId.type;          // IdType.PROBABILISTIC / RANDOM / HASHED_EMAIL
 const licenseId = fodId.licenseId;
 const matchKey = fodId.matchKey;  // Uint8Array: SHA-256 or GUID bytes, see type
 
 const domain = fodId.domain;
-const minutes = fodId.dateMinutes; // minutes since 2020-01-01T00:00:00Z
+const minutes = fodId.date;       // minutes since 2020-01-01T00:00:00Z
 const verified = await fodId.verify(publicKeyPem);   // async (Web Crypto)
 const base64 = fodId.asBase64();      // standard alphabet with padding
 const inLink = fodId.asBase64Url();   // URL-safe alphabet, no padding
 ```
 
-`fodId.hash` remains as a deprecated alias of `matchKey` returning the same
-bytes, so existing callers keep working, and will be removed in a future
-release.
-
-`dateMinutes` is the envelope's own date as the unsigned 32-bit count of
-minutes since 2020-01-01T00:00:00Z, the value the OWID `public-key?date=`
-parameter takes, for callers comparing creation times. `date` now reports
-the same unsigned value.
+`date` is 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, and it is the
+integer to compare when asking which of two identifiers was issued first.
 
 Where the value may not be a 51Did at all, read it without throwing.
 

package/tests/didClient.integration.test.js

@@ -66,7 +66,7 @@ live('DidClient against the cloud', () => {
 
   test('parses, verifies offline and verifies through the cloud', async () => {
     expect(fodId.version).toBe(3);
-    expect(fodId.dateMinutes).toBeGreaterThan(0);
+    expect(fodId.date).toBeGreaterThan(0);
     const key = await client.publicKeyFor(fodId);
     expect(key).not.toBeNull();
     expect(key.publicKey).toMatch(/BEGIN PUBLIC KEY/);

package/tests/didClient.test.js

@@ -40,6 +40,7 @@ const {
   signedWith,
   minutesOf
 } = require('./envelope');
+const layout = require('../internal/layout');
 
 const RESOURCE = 'AQTestResourceKey';
 const LICENCE = 'TEST-LICENCE-KEY';
@@ -429,7 +430,7 @@ describe('DidClient verifySignature', () => {
     // A Reserved type parses at any length from the header up, so it is
     // the way to present a payload the cloud's length rule refuses.
     const short = new Uint8Array(20);
-    short[FodId.FLAGS_OFFSET] = 0b11000000;
+    short[layout.FLAGS_OFFSET] = 0b11000000;
     const fod = await signedAt(pairs[1], new Date(START_2.getTime() + DAY), { payload: short });
     await expect(client.verifySignatureDetailed(fod)).resolves.toEqual({
       valid: false, reason: SignatureReason.LENGTH
@@ -449,9 +450,9 @@ describe('DidClient verifySignature', () => {
   test('true for a payload longer than the base (a context section)', async () => {
     const { pairs, json } = await schedule();
     const { client } = keyClient(json);
-    const withContext = new Uint8Array(FodId.PAYLOAD_LENGTH + 40);
+    const withContext = new Uint8Array(layout.PAYLOAD_LENGTH + 40);
     withContext.set(canonicalPayload());
-    withContext.fill(0x5A, FodId.PAYLOAD_LENGTH);
+    withContext.fill(0x5A, layout.PAYLOAD_LENGTH);
     const fod = await signedAt(pairs[1], new Date(START_2.getTime() + DAY), {
       payload: withContext
     });
@@ -461,9 +462,9 @@ describe('DidClient verifySignature', () => {
   test('true for a long context section and a long creator domain', async () => {
     const { pairs, json } = await schedule();
     const { client } = keyClient(json);
-    const withContext = new Uint8Array(FodId.PAYLOAD_LENGTH + 200);
+    const withContext = new Uint8Array(layout.PAYLOAD_LENGTH + 200);
     withContext.set(canonicalPayload());
-    withContext.fill(0x5A, FodId.PAYLOAD_LENGTH);
+    withContext.fill(0x5A, layout.PAYLOAD_LENGTH);
     const fod = await signedAt(pairs[1], new Date(START_2.getTime() + DAY), {
       payload: withContext,
       domain: 'a-self-hosted-container.example.internal.51degrees.com'