fiftyone.pipeline.did 4.5.46 → 4.5.48

package/examples/creator-context-web/page.html

@@ -138,6 +138,18 @@
     stolen identifier is caught the moment it is presented, with nothing
     stored server side.</p>
   </div>
+
+  <hr>
+  <h3 class="c-eg-page__heading">Find out more</h3>
+  <ul>
+    <li><a href="https://51degrees.com/documentation/_identifiers__index.html?utm_source=code&amp;utm_medium=example&amp;utm_campaign=pipeline-node&amp;utm_content=fiftyone.pipeline.did-creator-context-web-page.html&amp;utm_term=find-out-more">What a 51Did is, and what the creator context binds it to</a></li>
+    <li><a href="https://51degrees.com/contact-us?utm_source=code&amp;utm_medium=example&amp;utm_campaign=pipeline-node&amp;utm_content=fiftyone.pipeline.did-creator-context-web-page.html&amp;utm_term=find-out-more">Talk to 51Degrees about using 51Did</a></li>
+  </ul>
+  <p class="c-eg-page__lead">The source of this demo and of the code it runs on.</p>
+  <ul>
+    <li><a href="https://github.com/51Degrees/pipeline-node">https://github.com/51Degrees/pipeline-node</a></li>
+    <li><a href="https://github.com/51Degrees/specifications">https://github.com/51Degrees/specifications</a></li>
+  </ul>
 </div>
 
 <script>
@@ -280,26 +292,93 @@
     tr.appendChild(result);
   }
 
+  // The name the client script gives its object on the page. It can be
+  // set per resource key, and every key used with this demo leaves it at
+  // the default.
+  var OBJECT_NAME = "fod";
+
+  // The 51Did is created by the 51Degrees client script, never by a
+  // request of our own. The service creates one only once the page has
+  // run the snippets it asks for and sent what they collected, so a page
+  // that asks for an identifier before then is told the page has not
+  // finished and is given nothing at all. The script runs those snippets,
+  // sends them with its own request, and calls back through its complete
+  // function with the answer, which carries the six identifiers because
+  // the resource key is entitled to them. The usage and the email address
+  // travel on the script's own address, and the service puts both into
+  // the request the script makes.
+  function created() {
+    return new Promise(function (resolve, reject) {
+      var script = document.createElement("script");
+      script.async = true;
+      script.src = API + RESOURCE + ".js?id.usage=non-marketing"
+        + "&id.email=" + encodeURIComponent("demo@51did.example");
+      script.onerror = function () {
+        reject(new Error("the 51Degrees client script at " + script.src
+          + " did not load"));
+      };
+      script.onload = function () {
+        var object = window[OBJECT_NAME];
+        if (!object || typeof object.complete !== "function") {
+          reject(new Error("the 51Degrees client script loaded but left "
+            + "no '" + OBJECT_NAME + "' object with a complete function "
+            + "on the page, so nothing can be created here"));
+          return;
+        }
+        object.complete(function (data) { resolve(data || {}); });
+      };
+      document.head.appendChild(script);
+    });
+  }
+
+  // What the snippets collected, taken from the cookies the client
+  // script writes on this page and sent with the verification call. The
+  // service compares this browser's device and browser against the
+  // creator's from these values, and where a browser needs them and they
+  // are absent it answers that the page has not sent them yet rather
+  // than giving a verdict. Every name the script writes begins 51D_, so
+  // forwarding all of them needs no list here that could fall behind the
+  // script.
+  function snippetQuery() {
+    var query = "";
+    (document.cookie || "").split(";").forEach(function (pair) {
+      var text = pair.trim();
+      var split = text.indexOf("=");
+      if (split > 0 && text.slice(0, 4) === "51D_") {
+        query += "&" + encodeURIComponent(text.slice(0, split))
+          + "=" + encodeURIComponent(text.slice(split + 1));
+      }
+    });
+    return query;
+  }
+
   var given = new URLSearchParams(location.search).get("51did");
 
+  // The client script runs whichever path the page is on, because the
+  // service compares this browser against the creator using the values
+  // the snippets collect, and it only has them once the script has run.
+  var ready = created();
+
   // 1. The identifier: created for THIS browser's connection, or
   // taken from the link when demonstrating the transplant.
   var owidPromise = given
-    ? Promise.resolve(given).then(function (owid) {
+    ? ready.then(function () { return given; }).then(function (owid) {
         // The row shows the identifier itself, truncated as the table
         // below truncates every identifier, so the reader sees which
         // 51Did the link carried rather than a description of it.
         show("s-create", owid.slice(0, 30) + "…", NONE);
         return owid;
       })
-    : fetch(API + "json?resource=" + RESOURCE
-        + "&id.usage=non-marketing"
-        + "&id.email=" + encodeURIComponent("demo@51did.example")
-        + "&values=FODiD.IdProbGlobal&values=FODiD.IdProbLic"
-        + "&values=FODiD.IdHemGlobal&values=FODiD.IdHemLic"
-        + "&values=FODiD.IdRandGlobal&values=FODiD.IdRandLic")
-      .then(asJson)
+    : ready
       .then(function (json) {
+        if (!json.fodid) {
+          // Said here rather than where the script is loaded, because a
+          // page checking an identifier from another browser still wants
+          // the script for its snippet values and does not need one of
+          // its own.
+          throw new Error("the client script completed with no 51Did "
+            + "section, so this resource key is not entitled to one");
+        }
         var families = [
           ["Probabilistic", "Global", "idprobglobal"],
           ["Probabilistic", "Licensed", "idproblic"],
@@ -351,7 +430,7 @@
     // 2. Verify from THIS browser, so the cloud observes this live
     // connection. The verdict returns only as an encrypted result.
     return fetch(API + "id/verify-full/" + RESOURCE + "/"
-        + owid + "?challenge=" + CHALLENGE)
+        + owid + "?challenge=" + CHALLENGE + snippetQuery())
       .then(asJson)
       .then(function (verified) {
         if (!verified.result) {

package/examples/creator-context-web/server.js

@@ -28,10 +28,16 @@
  * adding the licence key the browser never sees. The page runs the 51Did
  * flow the way production does.
  *
- * 1. Create. The browser calls the json endpoint, which issues a 51Did
- *    for the browser's connection.
+ * 1. Create. The browser loads the 51Degrees client script, which runs
+ *    the snippets the service asks for, sends what they collected, and
+ *    hands the page the answer with the 51Did in it, created for the
+ *    browser's own connection. The service issues an identifier only
+ *    once those values are in, so a page asking for one by itself is
+ *    told the page has not finished and is given nothing.
  * 2. Verify. The browser calls verify-full, the first verification
- *    step, so the cloud observes the browser's live connection. Both
+ *    step, so the cloud observes the browser's live connection, and
+ *    sends what the snippets collected with the call so that this
+ *    browser can be compared with the creator. Both
  *    the signature outcome and the creator context verdict return only
  *    as an encrypted result that the browser cannot read or forge. (A
  *    deployment holding no context secret answers in the open instead.)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fiftyone.pipeline.did",
-  "version": "4.5.46",
+  "version": "4.5.48",
   "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",

package/readme.md

@@ -517,10 +517,16 @@ runs against the code beside it.
 `examples/creator-context-web/` holds a small demo web app, `server.js`
 serving `page.html`, that runs the full 51Did flow the way production does.
 
-1. **Create.** The browser calls the `json` endpoint, which issues a 51Did
-   for the browser's connection.
+1. **Create.** The browser loads the 51Degrees client script, which runs the
+   snippets the service asks for, sends what they collected, and hands the
+   page the answer with the 51Did in it, created for the browser's own
+   connection. The service issues an identifier only once those values are
+   in, so a page asking for one by itself is told the page has not finished
+   and is given nothing.
 2. **Verify.** The browser calls `verify-full`, the first verification step,
-   so the cloud observes the browser's live connection. Both the signature
+   so the cloud observes the browser's live connection, and sends what the
+   snippets collected with the call so that this browser can be compared
+   with the creator. Both the signature
    outcome and the creator context verdict return only as an encrypted
    `result` that the browser cannot read or forge. (A deployment holding no
    context secret answers in the open instead.) The page then hands the

package/tests/creatorContextPage.test.js

@@ -0,0 +1,155 @@
+/* *********************************************************************
+ * 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.
+ * ********************************************************************* */
+
+// What the creator context demo page does in a browser, checked by
+// running its script with a small stand in for a browser
+// (creatorContextPageHarness.js). No browser is started and nothing
+// reaches a network.
+//
+// The service creates a 51Did only once the page has run the snippets it
+// asks for and sent what they collected, so a page that asks for one
+// directly is told the page has not finished and is given nothing. The
+// 51Degrees client script is what runs those snippets, so the page has
+// to create through the script and then send what the snippets collected
+// with its verification call as well. These tests pin both, because
+// neither shows up in a unit test of the demo's server.
+
+const { execFileSync } = require('child_process');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const HARNESS = path.join(__dirname, 'creatorContextPageHarness.js');
+const PAGE = path.join(
+  __dirname, '..', 'examples', 'creator-context-web', 'page.html');
+
+// The licensed probabilistic identifier the stand in client script
+// reports, once the page has made it safe for a URL.
+const CREATED_URL_SAFE = 'prob-lic_value';
+
+function runPage (given) {
+  const args = [HARNESS, PAGE];
+  if (given !== undefined) { args.push(given); }
+  const printed = execFileSync(process.execPath, args, {
+    encoding: 'utf8', timeout: 60000
+  });
+  const lines = printed.trim().split(/\r?\n/);
+  return JSON.parse(lines[lines.length - 1]);
+}
+
+function scriptBlock () {
+  const page = fs.readFileSync(PAGE, 'utf8');
+  // A checkout on Windows has carriage returns in it, so the ends of
+  // lines are matched either way.
+  const match = page.match(/<script>\r?\n([\s\S]*?)\r?\n<\/script>/);
+  expect(match).not.toBeNull();
+  return match[1];
+}
+
+describe('creator context demo page', () => {
+  // A page whose script does not parse defines nothing and reports
+  // nothing, and the browser says so only in its console. node --check
+  // reads JavaScript rather than HTML, so the page's script block is
+  // written out on its own and checked.
+  test('the page script parses and runs without error', () => {
+    const folder = fs.mkdtempSync(path.join(os.tmpdir(), 'page-'));
+    const file = path.join(folder, 'page-script.js');
+    fs.writeFileSync(file, scriptBlock());
+    try {
+      execFileSync(process.execPath, ['--check', file], { stdio: 'pipe' });
+    } finally {
+      fs.rmSync(folder, { recursive: true, force: true });
+    }
+    expect(runPage().errors).toEqual([]);
+  });
+
+  // The page asks the cloud for the client script, with the usage and
+  // the email address on its address, and takes the identifier from what
+  // the script reports.
+  test('the identifier comes from the client script', () => {
+    const record = runPage();
+    expect(record.scripts).toHaveLength(1);
+    expect(record.scripts[0]).toContain('TEST-RESOURCE-KEY.js');
+    expect(record.scripts[0]).toContain('id.usage=non-marketing');
+    expect(record.scripts[0]).toContain('id.email=');
+    expect(record.rows['s-create']).toBe('created for this browser');
+  });
+
+  // A request of the page's own would be made before the snippets had
+  // run, and the service would answer it with no identifier at all.
+  test('the page does not ask for an identifier itself', () => {
+    for (const address of runPage().fetches) {
+      expect(address).not.toContain('json?resource=');
+      expect(address).not.toContain('/json');
+    }
+  });
+
+  // The identifier the script reported is verified, made safe for a URL,
+  // and what the snippets collected goes with it, because the service
+  // compares this browser against the creator from those values.
+  test('the verification carries the identifier and the snippets', () => {
+    const verify = runPage().fetches
+      .filter((address) => address.includes('id/verify-full'));
+    expect(verify).toHaveLength(1);
+    expect(verify[0]).toContain(CREATED_URL_SAFE);
+    expect(verify[0].split('?')[0]).not.toContain('+');
+    expect(verify[0]).toContain('51D_ScreenPixelsHeight=1080');
+    expect(verify[0]).toContain('51D_ProfileIds=1-2-3');
+    expect(verify[0]).not.toContain('unrelated=ignored');
+  });
+
+  // The licence key lives on the server, so the sealed result goes there
+  // and the verdict comes back from there.
+  test("the result is redeemed on the page's own server", () => {
+    const record = runPage();
+    const redeem = record.fetches
+      .filter((address) => address.startsWith('/redeem?'));
+    expect(redeem).toHaveLength(1);
+    expect(redeem[0]).toContain('result=sealed-result');
+    expect(record.rows['s-signature']).toBe('verified');
+    expect(record.rows['s-context']).toBe('verified');
+  });
+
+  // The page opened with an identifier from another browser checks that
+  // identifier, and still needs this browser's snippet values for the
+  // comparison, so the script runs on that path too.
+  test('a transplanted identifier still runs the client script', () => {
+    const record = runPage('given-value');
+    expect(record.scripts).toHaveLength(1);
+    const verify = record.fetches
+      .filter((address) => address.includes('id/verify-full'));
+    expect(verify).toHaveLength(1);
+    expect(verify[0]).toContain('given-value');
+    expect(verify[0]).toContain('51D_ProfileIds=1-2-3');
+  });
+
+  // Someone running the demo is interested in the subject, so the page
+  // ends with somewhere to go next. The links to 51degrees.com carry the
+  // campaign tags the link lint asks for and the source repositories are
+  // given as plain addresses.
+  test('the page ends with a Find out more section', () => {
+    const page = fs.readFileSync(PAGE, 'utf8');
+    expect(page).toContain('Find out more');
+    expect(page).toContain('utm_campaign=pipeline-node');
+    expect(page).toContain('https://github.com/51Degrees/pipeline-node');
+  });
+});

package/tests/creatorContextPageHarness.js

@@ -0,0 +1,198 @@
+// Runs the creator context demo page's script in Node with a small stand
+// in for a browser, and prints what the page did as one line of JSON.
+//
+// Usage: node creator_context_page_harness.js <page.html> [51did]
+//
+// The optional second argument is the identifier the page is opened with,
+// which is the transplant path. Without it the page creates one.
+//
+// The stand in gives the page a document, a window, a location and a
+// fetch. Inserting a script element stands for loading the 51Degrees
+// client script: the harness answers it by putting an object on the
+// window whose complete function hands back a fixed cloud answer with
+// the six 51Did values in it, which is what the real script does once it
+// has run the page's snippets. Nothing here reaches a network.
+//
+// The printed object says which script the page asked for, which
+// addresses it fetched, and what each row of the page ended up saying, so
+// a test can check that the page creates through the client script and
+// verifies the identifier the script reported.
+'use strict';
+const fs = require('fs');
+const vm = require('vm');
+
+const pageFile = process.argv[2];
+const given = process.argv[3];
+
+const page = fs.readFileSync(pageFile, 'utf8');
+// A checkout on Windows has carriage returns in it, so the ends of
+// lines are matched either way.
+const match = page.match(/<script>\r?\n([\s\S]*?)\r?\n<\/script>/);
+if (!match) {
+  console.log(JSON.stringify({ error: 'no script block in the page' }));
+  process.exit(1);
+}
+const source = match[1]
+  .replace(/__RESOURCE__/g, 'TEST-RESOURCE-KEY')
+  .replace(/__CHALLENGE__/g, 'test-challenge')
+  .replace(/__API__/g, 'https://cloud.51degrees.com/api/v4/');
+
+// The identifiers the stand in client script reports. Base64 with a plus
+// and a slash in it, so a test can see the page make the value safe for a
+// URL before it sends it.
+const IDS = {
+  idprobglobal: 'prob+global/value=',
+  idproblic: 'prob+lic/value=',
+  idhemglobal: 'hem+global/value=',
+  idhemlic: 'hem+lic/value=',
+  idrandglobal: 'rand+global/value=',
+  idrandlic: 'rand+lic/value='
+};
+
+const record = { scripts: [], fetches: [], rows: {}, revealed: [], errors: [] };
+
+/**
+ *
+ * @param id
+ */
+function element (id) {
+  return {
+    id,
+    style: {},
+    children: [],
+    set textContent (value) { record.rows[this.id] = String(value); },
+    get textContent () { return record.rows[this.id] || ''; },
+    set className (value) { record.rows[this.id + '.class'] = value; },
+    get className () { return record.rows[this.id + '.class'] || ''; },
+    appendChild: function (child) { this.children.push(child); },
+    onclick: null
+  };
+}
+
+const elements = {};
+/**
+ *
+ * @param id
+ */
+function byId (id) {
+  if (!elements[id]) { elements[id] = element(id); }
+  return elements[id];
+}
+
+const document = {
+  // The page reads this the way a browser gives it, as one string of
+  // name and value pairs. The client script stand in writes the two
+  // below when it "loads", which is what the real script does.
+  cookie: 'unrelated=ignored',
+  getElementById: byId,
+  createElement: function (tag) {
+    const made = element('<' + tag + '>');
+    if (tag === 'script') {
+      // Loading the client script. The page sets src, then this
+      // harness answers as the real script does, by leaving its
+      // object on the window.
+      let source = '';
+      Object.defineProperty(made, 'src', {
+        get: function () { return source; },
+        set: function (value) {
+          source = value;
+          record.scripts.push(value);
+        }
+      });
+    }
+    return made;
+  },
+  head: {
+    appendChild: function (node) {
+      // The client script has "loaded". Give the page the object it
+      // looks for, then tell it the load finished.
+      document.cookie = 'unrelated=ignored; ' +
+        '51D_ScreenPixelsHeight=1080; 51D_ProfileIds=1-2-3';
+      sandbox.window.fod = {
+        complete: function (report) {
+          report({ fodid: Object.assign({}, IDS) });
+        }
+      };
+      if (typeof node.onload === 'function') { node.onload(); }
+    }
+  },
+  body: { appendChild: function () {} }
+};
+
+/**
+ *
+ * @param body
+ */
+function response (body) {
+  return Promise.resolve({
+    ok: true,
+    status: 200,
+    url: 'stub',
+    text: function () { return Promise.resolve(JSON.stringify(body)); }
+  });
+}
+
+/**
+ *
+ * @param url
+ */
+function fetchStub (url) {
+  record.fetches.push(url);
+  if (url.indexOf('id/verify-full') !== -1 ||
+        url.indexOf('id/verify-context') !== -1) {
+    return response({ result: 'sealed-result' });
+  }
+  if (url.indexOf('/redeem') !== -1) {
+    return response({
+      signature: 'verified',
+      context: 'verified',
+      serverSignature: 'verified'
+    });
+  }
+  return response({});
+}
+
+const sandbox = {
+  console: {
+    log: function () {},
+    warn: function () {},
+    error: function (...a) { record.errors.push(a.join(' ')); }
+  },
+  document,
+  fetch: fetchStub,
+  URLSearchParams,
+  Promise,
+  setTimeout,
+  clearTimeout,
+  navigator: { clipboard: { writeText: function () {} } },
+  location: {
+    search: given ? '?51did=' + encodeURIComponent(given) : '',
+    origin: 'http://localhost:5100',
+    pathname: '/'
+  }
+};
+sandbox.window = sandbox;
+sandbox.globalThis = sandbox;
+
+vm.createContext(sandbox);
+try {
+  vm.runInContext(source, sandbox, { filename: 'page.html' });
+} catch (error) {
+  record.errors.push(String(error));
+}
+
+// The page's work is a chain of promises, so let them settle before
+// reporting. Several turns, because each step waits for the one before.
+let turns = 0;
+/**
+ *
+ */
+function settle () {
+  turns += 1;
+  if (turns < 20) {
+    setTimeout(settle, 0);
+    return;
+  }
+  console.log(JSON.stringify(record));
+}
+settle();