FEAT: 51Did four platform and browser factors, usageIsIndirect and refusing usage bits 000

fiftyone.pipeline.did/didClient.js

@@ -125,6 +125,28 @@
   MISCONFIGURED: 'misconfigured'
 });
 
+/**
+ * The names of the creator context factors, as the cloud writes them as
+ * keys of `factors`, in the order the cloud lists them. The operating
+ * system and the browser each have a name and a version, so a version
+ * mismatch beside a verified name reads as an upgrade, and a mismatched
+ * name reads as a different operating system or browser. These four
+ * replaced the single `browser` factor from cloud release 4.4.38.
+ * {@link RedeemResult#factors} is not limited to these names, so a factor
+ * the cloud adds later still reaches the caller.
+ */
+const Factor = Object.freeze({
+  TRANSPORT: 'transport',
+  DEVICE: 'device',
+  BROWSER_IP: 'browserip',
+  CONNECTION_IP: 'connectionip',
+  ASN: 'asn',
+  PLATFORM_NAME: 'platformname',
+  PLATFORM_VERSION: 'platformversion',
+  BROWSER_NAME: 'browsername',
+  BROWSER_VERSION: 'browserversion'
+});
+
 /**
  * The reason a {@link DidClient#verifySignatureDetailed} answer was given.
  */
@@ -148,7 +170,7 @@
  */
 class DidClientError extends Error {
   /**
    * Builds the error with the status and body the cloud answered.
    * @param {string} message what went wrong
    * @param {number} [statusCode] the HTTP status, where there was one
    * @param {string} [body] the response body, where there was one
@@ -167,7 +189,7 @@
  */
 class DidArgumentError extends DidClientError {
   /**
    * Builds the error from the validation message.
    * @param {string} message the validation message
    * @param {number} [statusCode] the HTTP status
    * @param {string} [body] the response body
@@ -185,7 +207,7 @@
  */
 class DidNotSupportedError extends DidClientError {
   /**
    * Builds the error from what the host said.
    * @param {string} message what the host said
    * @param {number} [statusCode] the HTTP status
    * @param {string} [body] the response body
@@ -202,7 +224,7 @@
  */
 class RedeemResult {
   /**
    * Reads the typed fields out of the parsed body.
    * @param {number} statusCode the HTTP status, 200 or 503
    * @param {string} raw the response body as received
    * @param {object} parsed the body parsed as JSON
@@ -233,10 +255,14 @@
         ? SignatureResult.INVALID
         : SignatureResult.UNKNOWN;
     /**
-     * @type {object | undefined} factor name to {@link FactorResult} value
-     * (or null where nothing was compared), present only when the cloud
-     * sent `factors`, which is the mismatch outcome. The names are
-     * transport, device, browserip, connectionip, asn and browser.
+     * @type {object | undefined} {@link Factor} name to
+     * {@link FactorResult} value (or null where nothing was compared),
+     * present only when the cloud sent `factors`, which it does where there
+     * is something to diagnose, being a mismatch or a misconfigured result
+     * that still compared some factors. Every name is kept exactly as the
+     * cloud sent it, including one this package does not list in
+     * {@link Factor}, so a factor the cloud adds later reaches the caller
+     * without a new release of this package.
      */
     this.factors = parsed.factors && typeof parsed.factors === 'object'
       ? Object.freeze(Object.assign({}, parsed.factors))
@@ -262,7 +288,7 @@
   }
 
   /**
    * Builds a result from a redeem response body.
    * @param {number} statusCode the HTTP status
    * @param {string} raw the response body
    * @returns {RedeemResult} the typed result
@@ -281,7 +307,7 @@
    * The result in the cloud's own response shape (`signature`, `context`,
    * `factors` when present, `verifiedAt`, `secondsSinceVerified`), so a
    * server can answer a page with it directly. `signature` is left out when
    * the cloud did not report it, as the cloud leaves it out.
    * @returns {object} the plain object for JSON.stringify
    */
   toJSON () {
@@ -308,7 +334,7 @@
  * A function with the shape of the global `fetch`, taking a URL and an
  * options object with `method`, `headers` and `body`, and resolving to a
  * response with `status` and a `text()` method. Node 18 and later provide
  * it globally, and tests inject one.
  * @callback FetchFunction
  * @param {string} url the absolute URL to request
  * @param {object} init the request options
@@ -318,14 +344,14 @@
 
 /**
  * A published signing key and the moment it came into force. A key stays in
  * force until the next key starts.
  * @typedef {object} PublicKeyEntry
  * @property {Date} startsAt when the key came, or comes, into force
  * @property {string} publicKey the key in SPKI PEM form
  */
 
 /**
  * The detailed answer to an offline signature check.
  * @typedef {object} SignatureCheck
  * @property {boolean} valid whether a candidate key verified the signature
  * @property {string} reason one of {@link SignatureReason}
@@ -861,6 +887,7 @@
   ContextResult,
   SignatureResult,
   FactorResult,
+  Factor,
   SignatureReason,
   DidClientError,
   DidArgumentError,

fiftyone.pipeline.did/examples/fodIdExample.js

@@ -113,7 +113,7 @@ async function run () {
   console.log('  Domain    :', fodId.domain);
   console.log('  Type      :', IdType.name(fodId.type));
   console.log('  Usage     :', Usage.name(fodId.usage));
-  console.log('  From cons.:', fodId.usageFromConsent);
+  console.log('  Indirect  :', fodId.usageIsIndirect);
   console.log('  LicenseId :', fodId.licenseId);
   console.log('  Match key :', Buffer.from(fodId.matchKey).toString('hex'));
   console.log('  Terms     :', fodId.terms);

fiftyone.pipeline.did/fodId.js

@@ -30,7 +30,7 @@ const FodIdParseError = require('./fodIdParseError');
 /**
  * Why a read of a 51Did succeeded or failed. The OWID library's own
  * vocabulary is carried through unchanged, because a 51Did failing to be
- * an OWID is reported exactly as the OWID library reported it, and two
+ * an OWID is reported exactly as the OWID library reported it, and four
  * members are added for the outcomes that belong to the 51Did payload
  * rather than to the envelope. Frozen, and compared by value rather than
  * by the text of any message.
@@ -55,7 +55,13 @@ const ParseStatus = Object.freeze(Object.assign({}, owid.ParseStatus, {
    * layout this package knows would answer with values that are wrong
    * rather than absent.
    */
-  UNSUPPORTED_PAYLOAD_VERSION: 'UnsupportedPayloadVersion'
+  UNSUPPORTED_PAYLOAD_VERSION: 'UnsupportedPayloadVersion',
+  /**
+   * Bits 0 to 2 of the flags byte are all clear, which is not a usage. The
+   * cloud writes no flags byte without bit 0, so such a payload is damaged
+   * or forged, and it is refused rather than offered as a fourth usage.
+   */
+  NO_USAGE: 'NoUsage'
 }));
 
 /**
@@ -106,7 +112,8 @@ const ParseStatus = Object.freeze(Object.assign({}, owid.ParseStatus, {
 class FodId {
   /**
    * Why a read succeeded or failed, being the OWID library's statuses plus
-   * `PAYLOAD_TOO_SHORT` and `INVALID_TYPE_PAYLOAD_LENGTH`. Frozen.
+   * `PAYLOAD_TOO_SHORT`, `INVALID_TYPE_PAYLOAD_LENGTH`,
+   * `UNSUPPORTED_PAYLOAD_VERSION` and `NO_USAGE`. Frozen.
    * @type {Readonly<Record<string, string>>}
    */
   static ParseStatus = ParseStatus;
@@ -306,13 +313,16 @@ class FodId {
   }
 
   /**
-   * 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.
+   * Whether the usage is indirect, being worked out by the issuer from a
+   * signal other than the caller stating it. Bit 3 of the flags. False
+   * means the caller stated the usage directly. A consent string is the
+   * only indirect signal today, so today this is true only where the usage
+   * was derived from one, but a later signal of another kind sets the same
+   * bit. Both are legitimate ways to arrive at a usage, and this says
+   * nothing about which usage it is.
    * @returns {boolean}
    */
-  get usageFromConsent () {
+  get usageIsIndirect () {
     return (this._flags & 0b1000) !== 0;
   }
 
@@ -462,10 +472,10 @@ class FodId {
  * @param {Uint8Array} payload the payload bytes
  * @returns {{status: string, flags?: number, licenseId?: number,
  * 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
+ * required: number, type?: number, payloadVersion?: number,
+ * usageBits?: number}} `status` PARSED with the fields, or a 51Did status
+ * with the length the type needed, and the version or the usage bits found
+ * where that is what the payload was refused for
  */
 function unpack (payload) {
   const length = payload.length;
@@ -491,6 +501,19 @@ function unpack (payload) {
       payloadVersion
     };
   }
+  // Usage bits 000 are not a usage. The cloud writes no flags byte without
+  // bit 0, so a payload carrying them is damaged or forged, and there is
+  // nothing a caller could do with a fourth usage that a refusal does not
+  // already say, being that the identifier must not be passed on.
+  const usageBits = flags & 0b111;
+  if (usageBits === 0) {
+    return {
+      status: ParseStatus.NO_USAGE,
+      length,
+      required: layout.HEADER_LENGTH,
+      usageBits
+    };
+  }
   // Little-endian unsigned 32-bit. `>>> 0` forces unsigned so the high bit
   // does not produce a negative number.
   const licenseId = (
@@ -616,7 +639,7 @@ function valueOrThrow (read) {
 }
 
 /**
- * The exception for a failed read. The three 51Did payload statuses keep the
+ * The exception for a failed read. The four 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.
@@ -638,6 +661,11 @@ function errorFor (read) {
     error = new RangeError(
       `51Did payload version ${read.detail.payloadVersion} is not one this ` +
       'package can read.');
+  } else if (read.status === ParseStatus.NO_USAGE) {
+    error = new RangeError(
+      '51Did payload carries usage bits ' +
+      read.detail.usageBits.toString(2).padStart(3, '0') +
+      ', which is not a usage.');
   } else {
     return new FodIdParseError(read.status);
   }

fiftyone.pipeline.did/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 three 51Did payload statuses are thrown as RangeError instead, as this
+ * The four 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 {

fiftyone.pipeline.did/index.js

@@ -30,6 +30,7 @@ const {
   ContextResult,
   SignatureResult,
   FactorResult,
+  Factor,
   SignatureReason,
   DidClientError,
   DidArgumentError,
@@ -46,6 +47,7 @@ module.exports = {
   ContextResult,
   SignatureResult,
   FactorResult,
+  Factor,
   SignatureReason,
   DidClientError,
   DidArgumentError,

fiftyone.pipeline.did/readme.md

@@ -88,7 +88,6 @@ 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 |
@@ -101,14 +100,25 @@ 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.
+There are exactly these three values. A payload whose usage bits are all
+clear is not given a fourth value, and is refused with
+`ParseStatus.NO_USAGE` instead, because the cloud never writes such a flags
+byte and the only safe answer to one is not to pass the identifier on, which
+the refusal already gives.
+
+`fodId.usageIsIndirect` says whether the usage is indirect, being worked out
+by the issuer from a signal other than the caller stating it, or direct,
+being stated by the caller. A consent string is the only indirect signal
+today, so today it is true only where the usage was derived from an IAB
+consent string the caller sent. Both are legitimate ways to arrive at a
+usage, and it says nothing about which usage it is. It was called
+`usageFromConsent` before the field was restated as direct against
+indirect, and the old name has been removed.
 
 `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`.
+value, for example `"non-marketing"`. Both answer `null` for a value that
+is not a `Usage`.
 
 ## The terms a 51Did was created under
 
@@ -217,6 +227,7 @@ OWID library's status, so a specific reason is never reduced to a general one.
 | `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 |
+| `NO_USAGE` | 51Did | Bits 0 to 2 of the flags byte are all clear, which is not a usage. The cloud never writes such a flags byte, so the identifier is damaged or forged |
 
 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.
@@ -230,7 +241,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`, `INVALID_TYPE_PAYLOAD_LENGTH` or `UNSUPPORTED_PAYLOAD_VERSION`, being the three statuses the 51Did payload rules produce. The error carries `status` |
+| `RangeError` | The payload is `PAYLOAD_TOO_SHORT`, `INVALID_TYPE_PAYLOAD_LENGTH`, `UNSUPPORTED_PAYLOAD_VERSION` or `NO_USAGE`, being the four 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
@@ -263,7 +274,7 @@ 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 a usage bit | `fodId.usage`, and `fodId.usageIsIndirect` 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 |
@@ -310,14 +321,14 @@ npm test
 ## Usage
 
 ```js
-const { FodId, IdType, Usage, Terms } = 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 usage = fodId.usage;        // Usage.NON_MARKETING / STANDARD / PERSONALIZED
-const fromConsent = fodId.usageFromConsent;
+const indirect = fodId.usageIsIndirect;
 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
@@ -469,16 +480,30 @@ redeemed.context      // ContextResult: 'verified', 'mismatch', 'nocontext',
                       // 'notcheckable', 'expired', 'replayed', 'unreadable',
                       // 'unconfirmed'
 redeemed.signature    // SignatureResult: 'verified', 'invalid' or 'unknown'
-redeemed.factors      // only on a mismatch: { transport, device, browserip,
-                      //   connectionip, asn, browser } each 'verified',
-                      //   'mismatch' or null where nothing was compared
+redeemed.factors      // where there is something to diagnose:
+                      //   { transport, device, browserip, connectionip,
+                      //   asn, platformname, platformversion,
+                      //   browsername, browserversion } each 'verified',
+                      //   'mismatch', 'misconfigured', or null where
+                      //   nothing was compared
 redeemed.verifiedAt   // Date, on the redeemed and expired outcomes
 redeemed.secondsSinceVerified
 redeemed.statusCode   // 200, or 503 for 'unconfirmed', which may be retried
 redeemed.raw          // the body as received
 redeemed.toJSON()     // the cloud's own response shape, for relaying to a page
 ```
 
+The factor names are in `Factor`, in the order the cloud lists them. From
+cloud release 4.4.38 the operating system and the browser each have a name
+and a version, replacing the single `browser` factor, so a version mismatch
+beside a verified name reads as an upgrade and a mismatched name reads as a
+different operating system or browser. `factors` keeps every name exactly as
+the cloud sent it, including a name that is not in `Factor`, so a factor the
+cloud adds later reaches the caller without a new release of this package,
+and an older service's `browser` key stays under its own name rather than
+filling any of the four. A factor that is `misconfigured` was not checked by
+the service, and must never be read as a mismatch.
+
 A context string this package does not know maps to `unreadable`, so an
 unrecognised outcome is never mistaken for a good one, and `contextRaw` keeps
 the string as sent. Every cryptographic failure comes back from the cloud as

fiftyone.pipeline.did/tests/didClient.integration.test.js

@@ -150,10 +150,10 @@ live('DidClient against the cloud', () => {
   // 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) => {
+  const assertAligned = (label, id, usage, terms, indirect) => {
     expect({ label, usage: id.usage }).toEqual({ label, usage });
-    expect({ label, fromConsent: id.usageFromConsent })
-      .toEqual({ label, fromConsent });
+    expect({ label, indirect: id.usageIsIndirect })
+      .toEqual({ label, indirect });
     expect({ label, terms: id.terms }).toEqual({ label, terms });
     expect({ label, type: id.type })
       .toEqual({ label, type: IdType.PROBABILISTIC });
@@ -190,7 +190,7 @@ live('DidClient against the cloud', () => {
       }
     });
 
-  test('a consent string sets the usage-from-consent bit', async () => {
+  test('a consent string sets the usage is indirect 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
@@ -212,10 +212,10 @@ live('DidClient against the cloud', () => {
     }
     if (proven === 0) {
       console.warn('NOTHING PROVEN: this resource key returned no ' +
-        'identifier for either consent string, so the usage-from-consent ' +
+        'identifier for either consent string, so the usage is indirect ' +
         'bit was never read.');
     } else {
-      console.log(`Usage-from-consent read on ${proven} identifier(s).`);
+      console.log(`Usage is indirect read on ${proven} identifier(s).`);
     }
   });
 });