fiftyone.pipeline.did 4.5.39 → 4.5.41

package/examples/fodIdExample.js

@@ -25,8 +25,8 @@
  *
  * 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.
@@ -50,10 +50,14 @@ function uint32LE (v) {
 }
 
 function samplePayload () {
-  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.
+  // 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;
@@ -62,6 +66,11 @@ function samplePayload () {
   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;
 }
 
@@ -107,6 +116,7 @@ async function run () {
   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

package/fodId.js

@@ -24,6 +24,7 @@ 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');
 
 /**
@@ -46,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'
 }));
 
 /**
@@ -144,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;
   }
 
   /**
@@ -333,6 +344,29 @@ class FodId {
     return this._matchKey.slice();
   }
 
+  /**
+   * 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 terms () {
+    return Terms.url(Terms.fromIndex(this._termsIndex));
+  }
+
   /** @returns {number} the OWID version. */
   get version () {
     return this._owid.version;
@@ -421,14 +455,17 @@ 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;
@@ -440,6 +477,20 @@ function unpack (payload) {
     };
   }
   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
+    };
+  }
   // Little-endian unsigned 32-bit. `>>> 0` forces unsigned so the high bit
   // does not produce a negative number.
   const licenseId = (
@@ -468,6 +519,20 @@ 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,
@@ -475,6 +540,7 @@ function unpack (payload) {
     // slice() copies, so the stored match key is this identifier's own.
     matchKey: payload.slice(
       layout.MATCH_KEY_OFFSET, layout.MATCH_KEY_OFFSET + matchKeyLength),
+    termsIndex,
     length,
     required
   };
@@ -505,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 };
 }
 
@@ -549,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.
@@ -567,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/internal/layout.js

@@ -49,10 +49,25 @@ module.exports = Object.freeze({
    * 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,
   /**

package/internal/terms.js

@@ -0,0 +1,172 @@
+/* *********************************************************************
+ * 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 terms document a 51Did was created under, carried in the byte that
+ * follows the match key. A 51Did created for marketing may only be used by
+ * a receiver that has accepted the terms it was created under, so the terms
+ * have to travel with the identifier rather than beside it, because an
+ * identifier passed as a query string parameter arrives on its own and any
+ * hop can drop what was sent alongside it without the identifier looking
+ * any different.
+ *
+ * The byte is an index into a table in the specification and is not a
+ * version number, so that a later document can live at any address rather
+ * than only at an address a number could be turned into. A new document is
+ * a new index, and every package has to be released to know it, which is
+ * the cost of a receiver being able to trust what it reads. An index is
+ * never reused or repointed once published, because repointing one would
+ * rewrite what a past identifier says it agreed to.
+ *
+ * An identifier whose payload ends at the match key carries no terms byte
+ * and reads as NOT_STATED, which is the right answer for it because no
+ * terms are stated in it. An identifier of the Reserved type
+ * reads as NOT_STATED too, because the match key length for that type is
+ * not defined, so every byte after the header is the match key and no byte
+ * is left for a reader to find.
+ *
+ * This module is internal to the package. It sits beside layout.js on the
+ * internal path, and is not exported from the package entry point nor
+ * reachable as a subpath, because the exports map in package.json offers
+ * only the entry point. The package turns the index into the address that
+ * fodId.terms answers with, so a caller never handles the byte, and the
+ * names here are the ones the specification gives so that every package
+ * describes one document the same way.
+ *
+ * UNKNOWN is an index added after this package was released, so the package
+ * cannot name the document. It answers with no address, as NOT_STATED does,
+ * because no package may build an address from an index it does not know,
+ * since that would name a document nobody wrote.
+ *
+ * NOT_STATED does not mean the identifier is unrestricted. It means only
+ * that the identifier does not carry the answer, so the answer has to come
+ * from the data accompanying it, being the Terms Document Locator in an
+ * OpenRTB request or whatever the surrounding protocol offers. Where both
+ * are present and they disagree, the identifier's own value is the one that
+ * describes the identifier, because it is inside the signature and the
+ * accompanying data is not.
+ *
+ * The usage says where an identifier may go and the terms say which
+ * document it was created under, so a receiver needs both. An identifier
+ * created for non-marketing carries NOT_STATED, since the Model Terms
+ * govern marketing use, and it stays barred from a demand source by its
+ * usage.
+ *
+ * url answers with the address for an index this package knows and null for
+ * every other value. This package never fetches the address, because what
+ * to do with the document is the receiver's decision.
+ *
+ * The table, and the rule that an index this package does not know is not
+ * zero, are specified once for all languages at
+ * https://github.com/51Degrees/specifications/blob/main/did-specification/identifier-layout.md
+ * which is the authority rather than this comment.
+ */
+// The terms table from the specification, which is the whole of the
+// definition of which index is which document. It is published at
+// https://github.com/51Degrees/specifications/blob/main/did-specification/identifier-layout.md#terms
+// and this is the only place in the shipped code that carries it. The
+// tests write the address out again on purpose, so that a test never
+// compares the reader with itself.
+//
+// One row per terms document, at the position of the index the payload
+// carries, holding the name for it and the address it stands for. A new
+// terms document is one new row here and one named value below, and nothing
+// else in the package changes. The name and the address sit in the same row
+// so that they cannot be added apart, which two lists side by side allowed.
+//
+// Index 0 has a row because it is a named value the specification gives,
+// and its address is null because it names no document.
+//
+// Each address names an exact version rather than a landing page, because a
+// document at an unversioned address can be edited afterwards and a
+// receiver has to know the document that was in force when the identifier
+// was made.
+const TABLE = [
+  { name: 'NotStated', url: null },
+  { name: 'ModelTermsForMarketing2', url: 'https://m4ow.uk/mtm/2.txt' }
+];
+
+// Not a row, because it stands for every index the table does not carry and
+// so has no index of its own. A Terms index read from a payload is one byte,
+// so it is 0 to 255 and can never be negative.
+const UNKNOWN = -1;
+const UNKNOWN_NAME = 'Unknown';
+
+/**
+ * The table row a Terms value stands for, and null where the value is not
+ * a row, being UNKNOWN or anything else outside the table. Every lookup
+ * goes through here so that the bounds are decided once and no lookup
+ * subscripts the table with a value it has not checked, which would raise
+ * at the caller rather than answer with no address.
+ * @param {number} terms a Terms value
+ * @returns {{name: string, url: string|null}|null} the row, or null
+ */
+function rowFor (terms) {
+  return terms >= 0 && terms < TABLE.length ? TABLE[terms] : null;
+}
+const Terms = Object.freeze({
+  /**
+   * An index this package does not know, being one added to the table
+   * after this package was released. It answers with no address, because
+   * no address may be built from an index the package cannot name.
+   */
+  UNKNOWN,
+  /**
+   * The terms are not stated in the identifier, which is also how an
+   * identifier whose payload ends at the match key reads. The answer has
+   * to come from the data accompanying the identifier.
+   */
+  NOT_STATED: 0,
+  /** The Model Terms for Marketing, version 2, at https://m4ow.uk/mtm/2.txt. */
+  MODEL_TERMS_FOR_MARKETING_2: 1,
+  /**
+   * The Terms value for a raw index byte, being UNKNOWN for every index
+   * this package does not know.
+   * @param {number} index the 1-byte terms index (0-255)
+   * @returns {number} the Terms value
+   */
+  fromIndex (index) {
+    return rowFor(index) === null ? UNKNOWN : index;
+  },
+  /**
+   * The cross language name of a Terms value.
+   * @param {number} terms a Terms value
+   * @returns {string} for example "ModelTermsForMarketing2"
+   */
+  name (terms) {
+    const row = rowFor(terms);
+    return row === null ? UNKNOWN_NAME : row.name;
+  },
+  /**
+   * The address of the terms document a Terms value stands for, or null
+   * for NOT_STATED and for UNKNOWN. Never an empty string, and never an
+   * address built from the index. The address is returned and never
+   * fetched.
+   * @param {number} terms a Terms value
+   * @returns {string|null} for example "https://m4ow.uk/mtm/2.txt"
+   */
+  url (terms) {
+    const row = rowFor(terms);
+    return row === null ? null : row.url;
+  }
+});
+module.exports = Terms;

package/package.json

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

package/readme.md

@@ -34,8 +34,9 @@ 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.
+LicenseId, the match key and then a one byte Terms. Bits 6 and 7 of the
+flags name the identifier type, which decides how long the match key is,
+and so where the Terms byte sits.
 
 | Bits 7-6 | `IdType`        | Match key length | Least payload accepted |
 |---------:|-----------------|-----------------:|-----------------------:|
@@ -58,6 +59,27 @@ 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 Terms byte sits between the match key and the creator context. An
+identifier whose payload ends at the match key carries no terms byte, and
+the reader answers with a terms index of zero for one.
+
+## The payload version
+
+Bits 4 and 5 of the flags byte say which payload layout the identifier
+follows, and this package reads version 0. A payload naming version 1, 2 or
+3 is refused with `ParseStatus.UNSUPPORTED_PAYLOAD_VERSION`, and the errors
+the throwing surfaces raise name the version they found.
+
+No field is read under the layout this package knows once the version says
+otherwise. A later version exists precisely because a field moved, so
+reading such a payload here would answer with values that are wrong rather
+than absent, which is worse than refusing. A version that nothing checks
+protects nothing.
+
+The version is not exposed. Either this package read the layout, in which
+case the accessors are the answer, or it did not, in which case there is no
+identifier to read fields from.
+
 ## The usage a 51Did was created for
 
 Every 51Did says what it was created for, and `fodId.usage` reports it as one
@@ -88,6 +110,57 @@ usage it is.
 `"NonMarketing"`, and `Usage.idUsage(usage)` gives the cloud's own `id.usage`
 value, for example `"non-marketing"`, or `null` for `NONE`.
 
+## The terms a 51Did was created under
+
+A 51Did created for marketing may only be used by a receiver that has
+accepted the terms it was created under, so the terms travel inside the
+identifier rather than beside it. An identifier passed as a query string
+parameter arrives on its own, and any hop can drop what was sent alongside it
+without the identifier looking any different.
+
+The byte after the match key is an index into a table in the specification
+and is not a version number, so that a later document can live at any address
+rather than only at an address a number could be turned into. An index is
+never reused or repointed once published, because repointing one would
+rewrite what a past identifier says it agreed to.
+
+| Index | Document | `fodId.terms` |
+| ---: | --- | --- |
+| `0` | Not stated in the identifier | `null` |
+| `1` | Model Terms for Marketing, version 2 | `https://m4ow.uk/mtm/2.txt` |
+| anything else | One this package cannot name | `null` |
+
+`fodId.terms` is the address of the document. The package turns the index
+into the address, so you never handle the byte. Nothing here fetches the
+address, because what to do with the document is your decision.
+
+**No address is ever built from an index this package cannot name**, because
+that would name a document nobody wrote and a receiver would record having
+accepted terms that do not exist. An index of zero and an index added after
+this package was released therefore give the same answer, which you cannot
+tell apart, and that is deliberate, since both say the identifier does not
+give the terms and the answer has to come from somewhere else.
+
+No address does not mean the identifier is unrestricted. It means only that
+the identifier does not carry the answer, so the answer has to come from the
+data accompanying it, being the Terms Document Locator in an OpenRTB request
+or whatever the surrounding protocol offers. Carrying the terms does not
+remove the need to carry a Terms Document Locator where a protocol has one,
+and where both are present and they disagree the identifier's own value is
+the one that describes the identifier, because it is inside the signature and
+the accompanying data is not.
+
+The usage says where an identifier may go and the terms say which document it
+was created under, so both are needed. An identifier created for
+non-marketing carries `NOT_STATED`, since the Model Terms govern marketing
+use, and it stays barred from a demand source by its usage.
+
+An identifier whose payload ends at the match key, and one of the
+`RESERVED` type, both read as `NOT_STATED`. The first carries no byte after
+the match key and the second exposes every byte after the header as the
+match key, so neither leaves a byte for the reader to find, and no terms
+are stated in either.
+
 ## Reading a 51Did
 
 A 51Did arrives from outside, from a page, a link or a log line, so a value
@@ -124,7 +197,7 @@ reads successfully and then fails verification. Verify with
 
 `FodId.ParseStatus` is a frozen object of stable string values. Compare
 against its members rather than against the text of any message. The
-vocabulary is the OWID library's own, carried through unchanged, plus two
+vocabulary is the OWID library's own, carried through unchanged, plus three
 members for the 51Did payload. A failure the OWID library reported keeps the
 OWID library's status, so a specific reason is never reduced to a general one.
 
@@ -143,6 +216,7 @@ OWID library's status, so a specific reason is never reduced to a general one.
 | `MALFORMED_ENVELOPE` | OWID | Malformed in a way none of the above describes |
 | `PAYLOAD_TOO_SHORT` | 51Did | The payload is shorter than the 5 byte header (flags and licence id), so the type cannot be read |
 | `INVALID_TYPE_PAYLOAD_LENGTH` | 51Did | The header named a type and the payload is shorter than that type's match key needs, being 21 bytes for Random and 37 for Probabilistic and HashedEmail |
+| `UNSUPPORTED_PAYLOAD_VERSION` | 51Did | Bits 4 and 5 of the flags byte name a payload layout version this package does not know, so no field is read |
 
 A Reserved type is not yet assigned, so the reader accepts it at any length
 from the header up and exposes whatever follows the header as the match key.
@@ -156,7 +230,7 @@ exception. They run the same checks, in the same order, and throw:
 | Thrown | When |
 | --- | --- |
 | `TypeError` | The argument is the wrong kind of thing, being `null`, `undefined`, a non-string to `fromBase64`, or a non-`Uint8Array` to `fromByteArray` |
-| `RangeError` | The payload is `PAYLOAD_TOO_SHORT` or `INVALID_TYPE_PAYLOAD_LENGTH`. The error carries `status` |
+| `RangeError` | The payload is `PAYLOAD_TOO_SHORT`, `INVALID_TYPE_PAYLOAD_LENGTH` or `UNSUPPORTED_PAYLOAD_VERSION`, being the three statuses the 51Did payload rules produce. The error carries `status` |
 | `FodIdParseError` | The OWID library refused the envelope for any other status. The error carries `status` |
 
 A wrong argument type is a programming error and stays exceptional on every
@@ -236,7 +310,7 @@ npm test
 ## Usage
 
 ```js
-const { FodId, IdType, Usage } = require('fiftyone.pipeline.did');
+const { FodId, IdType, Usage, Terms } = 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.
@@ -247,6 +321,9 @@ 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 terms = fodId.terms;        // address of the terms document it was
+                                  // created under, null where it names none
+                                  // this package knows
 
 const domain = fodId.domain;
 const minutes = fodId.date;       // minutes since 2020-01-01T00:00:00Z

package/tests/didClient.integration.test.js

@@ -27,7 +27,7 @@
 // FOD_CLOUD_API_URL as the client does.
 
 const {
-  FodId, DidClient, ContextResult, DidNotSupportedError
+  FodId, DidClient, ContextResult, DidNotSupportedError, Usage, IdType
 } = require('../index');
 
 const resourceKey = process.env._51DEGREES_RESOURCE_KEY ||
@@ -92,4 +92,130 @@ live('DidClient against the cloud', () => {
     expect(result.statusCode).toBe(200);
     expect(result.context).toBe(ContextResult.UNREADABLE);
   });
+  // The versioned Model Terms for Marketing document a marketing 51Did is
+  // created under. Written out here rather than read from the package,
+  // because a test that asked the package what it expects would agree with
+  // itself whatever the package said. The literal is what a receiver has to
+  // be able to fetch.
+  const MODEL_TERMS_FOR_MARKETING_2 = 'https://m4ow.uk/mtm/2.txt';
+
+  // Each id.usage the service offers, the usage this package must answer
+  // with, and the terms the identifier must carry. A non-marketing
+  // identifier may not reach a demand source at all, so there is nothing
+  // for a receiver to agree to and it states no terms.
+  const usages = [
+    ['non-marketing', Usage.NON_MARKETING, null],
+    ['standard', Usage.STANDARD, MODEL_TERMS_FOR_MARKETING_2],
+    ['personalized', Usage.PERSONALIZED, MODEL_TERMS_FOR_MARKETING_2]
+  ];
+
+  // IAB TCF v2 consent strings, and the usage the service must derive from
+  // each without the caller stating one. The first grants all twelve
+  // purposes, the second the Appendix 1 standard set of 1, 2, 7, 8 and 11.
+  // These are the strings the cloud's own IabTcfElement tests use, repeated
+  // here rather than shared, for the same reason as the address above.
+  const consentStrings = [
+    ['AAAAAAAAAAAAAAAAAAAAAAAAAP_w', Usage.PERSONALIZED],
+    ['AAAAAAAAAAAAAAAAAAAAAAAAAMMg', Usage.STANDARD]
+  ];
+
+  // Asks the json endpoint for a 51Did with the given query fragment and
+  // returns every identifier it answered with. An empty array means the
+  // resource key is not entitled to that usage, which is reported by the
+  // caller rather than failed.
+  const identifiersFor = async (fragment) => {
+    const url = client.endpoint + 'json?resource=' +
+      encodeURIComponent(resourceKey) + '&' + fragment +
+      '&values=FODiD.IdProbGlobal&values=FODiD.IdProbLic';
+    const response = await fetch(url, {
+      headers: { 'User-Agent': 'fiftyone.pipeline.did tests' }
+    });
+    const body = await response.text();
+    if (response.status !== 200) {
+      throw new Error(`json answered HTTP ${response.status}: ${body}`);
+    }
+    const fodid = JSON.parse(body).fodid;
+    if (!fodid) {
+      return [];
+    }
+    return ['idprobglobal', 'idproblic']
+      .map((name) => fodid[name])
+      .filter((value) => typeof value === 'string' && value.length > 0)
+      .map((value) => FodId.fromBase64(value));
+  };
+
+  // Every field the flags byte carries, plus the terms, read through the
+  // accessors rather than by masking. The usage values are cumulative,
+  // being 001, 011 and 111, so a caller masking the byte for the
+  // non-marketing bit reads every marketing identifier as non-marketing.
+  // The label travels into the expectation so a failure names which
+  // identifier it was.
+  const assertAligned = (label, id, usage, terms, fromConsent) => {
+    expect({ label, usage: id.usage }).toEqual({ label, usage });
+    expect({ label, fromConsent: id.usageFromConsent })
+      .toEqual({ label, fromConsent });
+    expect({ label, terms: id.terms }).toEqual({ label, terms });
+    expect({ label, type: id.type })
+      .toEqual({ label, type: IdType.PROBABILISTIC });
+  };
+
+  test('every usage reads back the terms and flags the service wrote',
+    async () => {
+      let checked = 0;
+      for (const [name, usage, terms] of usages) {
+        const identifiers = await identifiersFor(
+          'id.usage=' + encodeURIComponent(name));
+        if (identifiers.length === 0) {
+          console.warn(`id.usage=${name}: no identifier returned, so this ` +
+            'key is not entitled to that usage.');
+          continue;
+        }
+        identifiers.forEach((id, index) => {
+          assertAligned(`${name}[${index}]`, id, usage, terms, false);
+        });
+        // Only a marketing usage carries a terms address, so only a
+        // marketing identifier shows that the service wrote the byte. A
+        // non-marketing one states no terms either way, which is the same
+        // answer a service predating the Terms release would give.
+        if (terms !== null) {
+          checked += identifiers.length;
+        }
+      }
+      if (checked === 0) {
+        console.warn('NOTHING PROVEN: this resource key returned no ' +
+          'marketing 51Did, so no terms address was read. Use a key ' +
+          'entitled to the standard or personalized usage.');
+      } else {
+        console.log(`Terms checked on ${checked} marketing identifier(s).`);
+      }
+    });
+
+  test('a consent string sets the usage-from-consent bit', async () => {
+    let proven = 0;
+    for (const [tcString, usage] of consentStrings) {
+      // No id.usage is sent. A stated usage wins over a consent string, so
+      // sending one would leave the bit clear and prove the opposite.
+      const identifiers = await identifiersFor(
+        'tcstring=' + encodeURIComponent(tcString));
+      if (identifiers.length === 0) {
+        console.warn(`consent string granting ${usage}: no identifier ` +
+          'returned, so this key is not entitled to that marketing usage.');
+        continue;
+      }
+      identifiers.forEach((id, index) => {
+        // A consent string granting a marketing usage produces a marketing
+        // identifier, so the terms travel with it too.
+        assertAligned(`consent/${usage}[${index}]`, id, usage,
+          MODEL_TERMS_FOR_MARKETING_2, true);
+      });
+      proven += identifiers.length;
+    }
+    if (proven === 0) {
+      console.warn('NOTHING PROVEN: this resource key returned no ' +
+        'identifier for either consent string, so the usage-from-consent ' +
+        'bit was never read.');
+    } else {
+      console.log(`Usage-from-consent read on ${proven} identifier(s).`);
+    }
+  });
 });

package/tests/envelope.js

@@ -32,7 +32,13 @@ const VERSION = 2;
 const SIGNED_VERSION = 3;
 const DOMAIN = '51degrees.com';
 const DATE = 2900000; // minutes since 2020-01-01
-const CANONICAL_FLAGS = 0xA5; // HashedEmail type tag + usage bits
+// HashedEmail type tag in bits 6-7, payload version 0 in bits 4-5 and
+// the personalized marketing usage in bits 0-2.
+const CANONICAL_FLAGS = 0x85;
+// The terms index a marketing identifier carries, being the Model Terms
+// for Marketing version 2, and the zero a non-marketing one carries.
+const MARKETING_TERMS_INDEX = 1;
+const NON_MARKETING_TERMS_INDEX = 0;
 const CANONICAL_LICENSE_ID = 0x12345678;
 const OWID_EPOCH_MS = Date.UTC(2020, 0, 1);
 
@@ -50,7 +56,10 @@ function writeLicenseId (payload) {
   payload[layout.LICENSE_ID_OFFSET + 3] = 0x12;
 }
 
-function canonicalPayload () {
+// The canonical payload cut off at the end of the match key, so it carries
+// no terms byte. A reader takes that as a terms index of zero, and this is
+// the fixture for that rule rather than anything an issuer would write.
+function payloadEndingAtMatchKey () {
   const p = new Uint8Array(layout.PAYLOAD_LENGTH);
   p[layout.FLAGS_OFFSET] = CANONICAL_FLAGS;
   writeLicenseId(p);
@@ -58,7 +67,16 @@ function canonicalPayload () {
   return p;
 }
 
-function canonicalRandomPayload () {
+// The canonical payload as an issuer writes one, carrying the payload
+// version 0 in its flags byte and the terms byte of the document a
+// personalized marketing identifier is created under. This is the creating
+// side, so it writes every field an issuer writes.
+function canonicalPayload () {
+  return withTerms(payloadEndingAtMatchKey(), MARKETING_TERMS_INDEX);
+}
+
+// The canonical Random payload cut off at the end of its GUID.
+function randomPayloadEndingAtMatchKey () {
   const p = new Uint8Array(layout.RANDOM_PAYLOAD_LENGTH);
   p[layout.FLAGS_OFFSET] = (1 << 6) | 0b001; // Random tag + usage bits
   writeLicenseId(p);
@@ -68,6 +86,38 @@ function canonicalRandomPayload () {
   return p;
 }
 
+// The canonical Random payload as an issuer writes one, carrying the zero
+// terms byte a non-marketing identifier carries.
+function canonicalRandomPayload () {
+  return withTerms(
+    randomPayloadEndingAtMatchKey(), NON_MARKETING_TERMS_INDEX);
+}
+
+// The same payload with its version bits set to the given version, leaving
+// every other bit of the flags byte alone.
+function withPayloadVersion (payload, version) {
+  const p = payload.slice();
+  p[layout.FLAGS_OFFSET] =
+    (payload[layout.FLAGS_OFFSET] & 0b11001111) | (version << 4);
+  return p;
+}
+
+// The same payload with a terms byte written after the match key, and a
+// creator context section of contextLength bytes after that where one is
+// asked for. The payload given must end at the match key, as both the
+// canonical builders above do, so that the byte lands at the offset a
+// reader works out from the identifier type.
+function withTerms (payload, index, contextLength = 0) {
+  const p = new Uint8Array(
+    payload.length + layout.TERMS_LENGTH + contextLength);
+  p.set(payload);
+  p[payload.length] = index;
+  if (contextLength > 0) {
+    p.fill(0xCC, payload.length + layout.TERMS_LENGTH);
+  }
+  return p;
+}
+
 function uint32LE (v) {
   return [v & 0xFF, (v >>> 8) & 0xFF, (v >>> 16) & 0xFF, (v >>> 24) & 0xFF];
 }
@@ -157,11 +207,17 @@ module.exports = {
   DOMAIN,
   DATE,
   CANONICAL_FLAGS,
+  MARKETING_TERMS_INDEX,
+  NON_MARKETING_TERMS_INDEX,
   CANONICAL_LICENSE_ID,
   DUMMY_SIG,
   canonicalMatchKey,
   canonicalPayload,
   canonicalRandomPayload,
+  payloadEndingAtMatchKey,
+  randomPayloadEndingAtMatchKey,
+  withTerms,
+  withPayloadVersion,
   noSigBytes,
   envelopeBytes,
   envelopeBase64,

package/tests/fodId.test.js

@@ -22,6 +22,10 @@
 
 const owid = require('owid');
 const { FodId, FodIdParseError, IdType, Usage } = require('../index');
+// The named value is internal to the package and is not exported, so the
+// table test below reaches the module directly rather than through the
+// package entry point.
+const Terms = require('../internal/terms');
 const {
   DOMAIN,
   DATE,
@@ -31,6 +35,10 @@ const {
   canonicalMatchKey,
   canonicalPayload,
   canonicalRandomPayload,
+  payloadEndingAtMatchKey,
+  randomPayloadEndingAtMatchKey,
+  withTerms,
+  withPayloadVersion,
   envelopeBytes,
   envelopeBase64,
   signedVerifiable,
@@ -40,6 +48,14 @@ const layout = require('../internal/layout');
 
 const { ParseStatus, SignatureStatus } = FodId;
 
+// Written out here rather than taken from the package, so that the test
+// fails if the address the package answers with ever changes. An index is
+// never repointed once published, because repointing one would rewrite what
+// a past identifier says it agreed to.
+const MODEL_TERMS_2_URL = 'https://m4ow.uk/mtm/2.txt';
+// An index added to the table after this package was released.
+const UNKNOWN_INDEX = 200;
+
 describe('FodId', () => {
   // ----- Current .NET coverage -----
 
@@ -133,10 +149,13 @@ describe('FodId', () => {
     expect(FodId.fromBase64(envelopeBase64(p))._flags).toBe(0);
   });
 
-  test('a flags byte with every bit set is read unchanged', () => {
+  test('every flags bit outside the version is read unchanged', () => {
+    // Bits 4 and 5 are the payload version and only version 0 is read, so
+    // every other bit is set and those two are left clear. A payload with
+    // them set is refused rather than read, which the version tests cover.
     const p = canonicalPayload();
-    p[layout.FLAGS_OFFSET] = 0xFF;
-    expect(FodId.fromBase64(envelopeBase64(p))._flags).toBe(255);
+    p[layout.FLAGS_OFFSET] = 0xCF;
+    expect(FodId.fromBase64(envelopeBase64(p))._flags).toBe(0xCF);
   });
 
   test('matchKey is a defensive copy', () => {
@@ -323,6 +342,270 @@ describe('FodId', () => {
     expect(fod.matchKey.length).toBe(0);
   });
 
+  // ----- Terms -----
+
+  // The terms document the identifier was created under, carried in the
+  // byte after the match key. Absence and zero are the same answer, and an
+  // index this package does not know is neither of them.
+
+  test('a payload ending at the match key answers with no address', () => {
+    // There is no byte after the match key to read, so the reader answers
+    // zero and everything else about the identifier reads as it does when
+    // the byte is present.
+    const fod = FodId.fromBase64(
+      envelopeBase64(payloadEndingAtMatchKey()));
+    expect(fod.terms).toBeNull();
+    expect(fod.matchKey).toEqual(canonicalMatchKey());
+    expect(fod.licenseId).toBe(CANONICAL_LICENSE_ID);
+  });
+
+  test('terms index one is the Model Terms for Marketing address', () => {
+    const fod = FodId.fromBase64(
+      envelopeBase64(withTerms(payloadEndingAtMatchKey(), 1)));
+    expect(fod.terms).toBe(MODEL_TERMS_2_URL);
+    expect(fod.matchKey).toEqual(canonicalMatchKey());
+  });
+
+  test('an index this package does not know has no address', () => {
+    // No address is ever built from an index the package cannot name,
+    // because that would name a document nobody wrote and a receiver
+    // would record having accepted terms that do not exist.
+    for (const index of [2, 127, UNKNOWN_INDEX, 255]) {
+      const fod = FodId.fromBase64(
+        envelopeBase64(withTerms(payloadEndingAtMatchKey(), index)));
+      expect(fod.terms).toBeNull();
+      expect(fod.terms).not.toBe('');
+    }
+  });
+
+  test('not stated and an unknown index both answer with no address',
+    () => {
+      // A caller cannot tell the two apart, which is deliberate, since
+      // both say the identifier does not give the terms and the answer
+      // has to come from somewhere else.
+      const notStated = FodId.fromBase64(
+        envelopeBase64(withTerms(payloadEndingAtMatchKey(), 0)));
+      const unknown = FodId.fromBase64(
+        envelopeBase64(withTerms(payloadEndingAtMatchKey(), UNKNOWN_INDEX)));
+      expect(notStated.terms).toBeNull();
+      expect(unknown.terms).toBeNull();
+    });
+
+  test('a zero terms byte written out reads the same as none at all', () => {
+    const written = FodId.fromBase64(
+      envelopeBase64(withTerms(payloadEndingAtMatchKey(), 0)));
+    const absent = FodId.fromBase64(
+      envelopeBase64(payloadEndingAtMatchKey()));
+    expect(written.terms).toBe(absent.terms);
+    expect(written.terms).toBeNull();
+  });
+
+  // The byte follows the match key, so its offset comes from the identifier
+  // type. Reading it at a fixed offset would read a context byte on one
+  // type and the wrong end of the match key on the other.
+  test.each([
+    ['a 32 byte match key', payloadEndingAtMatchKey,
+      layout.MATCH_KEY_LENGTH],
+    ['a 16 byte match key', randomPayloadEndingAtMatchKey,
+      layout.GUID_LENGTH]
+  ])('the terms byte is read after %s', (name, build, matchKeyLength) => {
+    const bare = FodId.fromBase64(envelopeBase64(build()));
+    expect(bare.matchKey.length).toBe(matchKeyLength);
+    expect(bare.terms).toBeNull();
+
+    for (const [index, url] of [
+      [0, null],
+      [1, MODEL_TERMS_2_URL],
+      [UNKNOWN_INDEX, null]
+    ]) {
+      const fod = FodId.fromBase64(envelopeBase64(withTerms(build(), index)));
+      expect(fod.matchKey).toEqual(bare.matchKey);
+      expect(fod.matchKey.length).toBe(matchKeyLength);
+      expect(fod.terms).toBe(url);
+    }
+  });
+
+  test.each([
+    ['a 32 byte match key', payloadEndingAtMatchKey],
+    ['a 16 byte match key', randomPayloadEndingAtMatchKey]
+  ])('a context section after the terms byte leaves it read, with %s',
+    (name, build) => {
+      // The byte sits before the creator context, so a payload carrying
+      // both proves the byte is read at its own offset rather than at the
+      // end of whatever the payload holds.
+      const p = withTerms(build(), 1, 96);
+      const bytes = envelopeBytes(p);
+      const encoded = Buffer.from(bytes).toString('base64');
+      const bare = FodId.fromBase64(envelopeBase64(build()));
+
+      for (const fod of [
+        FodId.fromBase64(encoded),
+        FodId.fromByteArray(bytes),
+        FodId.fromOwid(owid.parse(encoded).owid),
+        FodId.tryParse(encoded).value,
+        FodId.tryFromByteArray(bytes).value
+      ]) {
+        expect(fod.matchKey).toEqual(bare.matchKey);
+        expect(fod.licenseId).toBe(CANONICAL_LICENSE_ID);
+        expect(fod.terms).toBe(MODEL_TERMS_2_URL);
+        expect(fod.payload).toHaveLength(p.length);
+      }
+    });
+
+  test('a Reserved payload answers with no address', () => {
+    // A Reserved type is not yet assigned, so everything after the header
+    // is exposed as the match key and no byte is left to read as the terms.
+    const p = new Uint8Array(layout.MATCH_KEY_OFFSET);
+    p[layout.FLAGS_OFFSET] = 0b1100_0000;
+    const fod = FodId.fromBase64(envelopeBase64(p));
+    expect(fod.type).toBe(IdType.RESERVED);
+    expect(fod.terms).toBeNull();
+  });
+
+  test('the terms survive both base64 alphabets and the byte round-trip',
+    () => {
+      const p = withTerms(payloadEndingAtMatchKey(), 1);
+      const first = FodId.fromBase64(envelopeBase64(p));
+      for (const again of [
+        FodId.fromBase64(first.asBase64()),
+        FodId.fromBase64(first.asBase64Url()),
+        FodId.fromByteArray(first.asByteArray())
+      ]) {
+        expect(again.terms).toBe(first.terms);
+        expect(again.terms).toBe(MODEL_TERMS_2_URL);
+      }
+    });
+
+  test('every row of the Terms table agrees with itself', () => {
+    // The row carries the name and the address together, so this fails if
+    // a later change puts either somewhere else and the two disagree, or
+    // if a row is added without an address.
+    for (let index = 0; index < 256; index++) {
+      const terms = Terms.fromIndex(index);
+      const name = Terms.name(terms);
+      const url = Terms.url(terms);
+      if (terms === Terms.UNKNOWN) {
+        expect(name).toBe('Unknown');
+        expect(url).toBeNull();
+        continue;
+      }
+      // A row is reached by its own index and answers a name.
+      expect(terms).toBe(index);
+      expect(typeof name).toBe('string');
+      expect(name.length).toBeGreaterThan(0);
+      if (index === Terms.NOT_STATED) {
+        // Names no document, so it has no address.
+        expect(url).toBeNull();
+      } else {
+        expect(typeof url).toBe('string');
+        expect(url.startsWith('https://')).toBe(true);
+      }
+    }
+  });
+
+  test('the Terms table maps every index, name and address', () => {
+    expect(Terms.fromIndex(0)).toBe(Terms.NOT_STATED);
+    expect(Terms.fromIndex(1)).toBe(Terms.MODEL_TERMS_FOR_MARKETING_2);
+    expect(Terms.fromIndex(2)).toBe(Terms.UNKNOWN);
+    expect(Terms.fromIndex(UNKNOWN_INDEX)).toBe(Terms.UNKNOWN);
+    expect(Terms.fromIndex(255)).toBe(Terms.UNKNOWN);
+    expect(Terms.name(Terms.NOT_STATED)).toBe('NotStated');
+    expect(Terms.name(Terms.MODEL_TERMS_FOR_MARKETING_2))
+      .toBe('ModelTermsForMarketing2');
+    expect(Terms.name(Terms.UNKNOWN)).toBe('Unknown');
+    expect(Terms.url(Terms.NOT_STATED)).toBeNull();
+    expect(Terms.url(Terms.MODEL_TERMS_FOR_MARKETING_2))
+      .toBe(MODEL_TERMS_2_URL);
+    expect(Terms.url(Terms.UNKNOWN)).toBeNull();
+    // A value that is not a row answers rather than raising, so a lookup
+    // never reaches the caller as a TypeError from a table subscript.
+    expect(Terms.url(99)).toBeNull();
+    expect(Terms.name(99)).toBe('Unknown');
+    expect(Terms.url(-2)).toBeNull();
+    expect(Object.isFrozen(Terms)).toBe(true);
+    // The named value is internal, so the package entry point does not
+    // offer it. The address on FodId is the whole of the surface.
+    expect(require('../index').Terms).toBeUndefined();
+  });
+
+  // ----- The payload version -----
+
+  // Bits 4 and 5 of the flags byte say which payload layout the identifier
+  // follows. This package reads version 0 and refuses every other version
+  // rather than reading fields that may have moved.
+
+  test('a flags byte with the version bits clear reads every field', () => {
+    const fod = FodId.fromBase64(envelopeBase64(canonicalPayload()));
+    expect(fod.type).toBe(IdType.HASHED_EMAIL);
+    expect(fod.usage).toBe(Usage.PERSONALIZED);
+    expect(fod.licenseId).toBe(CANONICAL_LICENSE_ID);
+    expect(fod.matchKey).toEqual(canonicalMatchKey());
+    expect(fod.terms).toBe(MODEL_TERMS_2_URL);
+  });
+
+  test.each([[1], [2], [3]])(
+    'payload version %i is refused and names the version', (version) => {
+      const p = withPayloadVersion(canonicalPayload(), version);
+      const read = FodId.tryParse(envelopeBase64(p));
+
+      expect(read.ok).toBe(false);
+      expect(read.status).toBe(ParseStatus.UNSUPPORTED_PAYLOAD_VERSION);
+      // Nothing is handed back, rather than a value with some fields
+      // filled in, because there is no identifier to expose fields for
+      // when the layout was not understood.
+      expect(read.value).toBeNull();
+
+      let thrown = null;
+      try {
+        FodId.fromBase64(envelopeBase64(p));
+      } catch (error) {
+        thrown = error;
+      }
+      expect(thrown).not.toBeNull();
+      expect(thrown.status).toBe(ParseStatus.UNSUPPORTED_PAYLOAD_VERSION);
+      expect(thrown.message).toContain(`version ${version}`);
+    });
+
+  test('the version is read apart from the usage and type bits', () => {
+    // A reader masking the wrong bits would refuse a version 0 identifier
+    // or let a later version through, so every combination is tried.
+    for (const usage of [0b000, 0b001, 0b011, 0b111]) {
+      for (const type of [0b00, 0b10, 0b11]) {
+        const p = payloadEndingAtMatchKey();
+        p[layout.FLAGS_OFFSET] = (type << 6) | usage;
+
+        expect(FodId.tryParse(envelopeBase64(p)).ok).toBe(true);
+
+        for (const version of [1, 2, 3]) {
+          const refused = FodId.tryParse(
+            envelopeBase64(withPayloadVersion(p, version)));
+          expect(refused.status)
+            .toBe(ParseStatus.UNSUPPORTED_PAYLOAD_VERSION);
+          expect(refused.value).toBeNull();
+        }
+      }
+    }
+  });
+
+  test('reading the address does not fetch it', () => {
+    // The package answers with the address and never fetches it, because
+    // what to do with the document is the caller's decision.
+    const before = globalThis.fetch;
+    const calls = [];
+    globalThis.fetch = (...args) => {
+      calls.push(args);
+      return Promise.reject(new Error('a read must not fetch'));
+    };
+    try {
+      const fod = FodId.fromBase64(
+        envelopeBase64(withTerms(payloadEndingAtMatchKey(), 1)));
+      expect(fod.terms).toBe(MODEL_TERMS_2_URL);
+    } finally {
+      globalThis.fetch = before;
+    }
+    expect(calls).toHaveLength(0);
+  });
+
   // ----- Gap tests (runbook section 6b) -----
 
   test('compare two 51Dids over the same payload', () => {
@@ -531,7 +814,7 @@ describe('FodId.tryParse and tryFromByteArray', () => {
     }
   }
 
-  test('the status vocabulary is the OWID one plus the two 51Did members', () => {
+  test('the status vocabulary is the OWID one plus the three 51Did members', () => {
     expect(Object.isFrozen(ParseStatus)).toBe(true);
     for (const [name, value] of Object.entries(owid.ParseStatus)) {
       expect(ParseStatus[name]).toBe(value);
@@ -539,8 +822,10 @@ describe('FodId.tryParse and tryFromByteArray', () => {
     expect(ParseStatus.PAYLOAD_TOO_SHORT).toBe('PayloadTooShort');
     expect(ParseStatus.INVALID_TYPE_PAYLOAD_LENGTH)
       .toBe('InvalidTypePayloadLength');
+    expect(ParseStatus.UNSUPPORTED_PAYLOAD_VERSION)
+      .toBe('UnsupportedPayloadVersion');
     expect(Object.keys(ParseStatus))
-      .toHaveLength(Object.keys(owid.ParseStatus).length + 2);
+      .toHaveLength(Object.keys(owid.ParseStatus).length + 3);
     expect(SignatureStatus).toBe(owid.SignatureStatus);
   });
 
@@ -649,7 +934,7 @@ describe('FodId.tryParse and tryFromByteArray', () => {
   });
 
   test('an OWID declaration mismatch is propagated unchanged without any cryptography', () => {
-    const bytes = envelopeBytes(canonicalPayload());
+    const bytes = envelopeBytes(payloadEndingAtMatchKey());
     const at = lengthFieldOffset();
     expect(bytes[at]).toBe(layout.PAYLOAD_LENGTH); // the field under test
     bytes[at] = layout.PAYLOAD_LENGTH + 1; // declares one byte more than sent
@@ -754,7 +1039,7 @@ describe('FodId.tryParse and tryFromByteArray', () => {
     expect(() => FodId.fromByteArray(null)).toThrow(TypeError);
     expect(() => FodId.fromByteArray('QUJD')).toThrow(TypeError);
 
-    // The two 51Did payload statuses stay RangeError, now carrying the
+    // The three 51Did payload statuses stay RangeError, now carrying the
     // status as well.
     const tooShort = envelopeBase64(new Uint8Array(3));
     expect(() => FodId.fromBase64(tooShort)).toThrow(RangeError);
@@ -770,6 +1055,16 @@ describe('FodId.tryParse and tryFromByteArray', () => {
       }));
     expect(() => FodId.fromByteArray(envelopeBytes(new Uint8Array(0))))
       .toThrow(RangeError);
+    // A refused payload version is the third of them, and is a RangeError
+    // and not a FodIdParseError, because the version is a rule this package
+    // applies to the payload rather than anything the OWID library judged.
+    const wrongVersion = envelopeBase64(
+      withPayloadVersion(canonicalPayload(), 1));
+    expect(() => FodId.fromBase64(wrongVersion)).toThrow(RangeError);
+    expect(() => FodId.fromBase64(wrongVersion)).toThrow(
+      expect.objectContaining({
+        status: ParseStatus.UNSUPPORTED_PAYLOAD_VERSION
+      }));
 
     // An OWID status is a FodIdParseError carrying that status.
     expect(() => FodId.fromBase64('****')).toThrow(FodIdParseError);

package/types/fodId.d.ts

@@ -172,6 +172,8 @@ declare class FodId {
     _licenseId: number;
     /** @type {Uint8Array} this identifier's own copy of the match key bytes */
     _matchKey: Uint8Array;
+    /** @type {number} the terms index, zero where the payload carries none */
+    _termsIndex: number;
     /** @returns {number} the IdType carried in bits 6-7 of the flags. */
     get type(): number;
     /**
@@ -210,6 +212,26 @@ declare class FodId {
      * @returns {Uint8Array} a defensive copy of the match key bytes
      */
     get matchKey(): Uint8Array;
+    /**
+     * 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 terms(): string | null;
     /** @returns {number} the OWID version. */
     get version(): number;
     /** @returns {string} the domain of the OWID creator. */

package/types/fodIdParseError.d.ts

@@ -5,7 +5,7 @@ export = FodIdParseError;
  * 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.
  */
 declare class FodIdParseError extends Error {

package/types/internal/layout.d.ts

@@ -12,10 +12,25 @@ declare const _exports: Readonly<{
      * 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;
     /**

package/types/internal/terms.d.ts

@@ -0,0 +1,39 @@
+export = Terms;
+declare const Terms: Readonly<{
+    /**
+     * An index this package does not know, being one added to the table
+     * after this package was released. It answers with no address, because
+     * no address may be built from an index the package cannot name.
+     */
+    UNKNOWN: -1;
+    /**
+     * The terms are not stated in the identifier, which is also how an
+     * identifier whose payload ends at the match key reads. The answer has
+     * to come from the data accompanying the identifier.
+     */
+    NOT_STATED: 0;
+    /** The Model Terms for Marketing, version 2, at https://m4ow.uk/mtm/2.txt. */
+    MODEL_TERMS_FOR_MARKETING_2: 1;
+    /**
+     * The Terms value for a raw index byte, being UNKNOWN for every index
+     * this package does not know.
+     * @param {number} index the 1-byte terms index (0-255)
+     * @returns {number} the Terms value
+     */
+    fromIndex(index: number): number;
+    /**
+     * The cross language name of a Terms value.
+     * @param {number} terms a Terms value
+     * @returns {string} for example "ModelTermsForMarketing2"
+     */
+    name(terms: number): string;
+    /**
+     * The address of the terms document a Terms value stands for, or null
+     * for NOT_STATED and for UNKNOWN. Never an empty string, and never an
+     * address built from the index. The address is returned and never
+     * fetched.
+     * @param {number} terms a Terms value
+     * @returns {string|null} for example "https://m4ow.uk/mtm/2.txt"
+     */
+    url(terms: number): string | null;
+}>;