Merge pull request #24 from StepenkoAnatoli/fix/client-ref-is-public

client_ref is public: say so where a dispatcher reads it

Author: StepenkoAnatoli

.github/workflows/collect.yml

@@ -25,6 +25,13 @@ name: collect
 # `client_ref` is OPTIONAL insurance for a caller stuck on the old API version, and for
 # display. It is not the correlation mechanism.
 #
+# AND IT IS PUBLIC. It becomes the run name and the artifact name, both of which an
+# anonymous caller can read on a public repository. Everything this file does to keep the
+# topic out of those names is undone by a caller who puts the subject in the reference -
+# `layoff-plan-q3` fits the permitted shape perfectly. Treat it as an opaque job id.
+# The input description says so at the point of entry, which is the only place a
+# dispatcher is actually looking.
+#
 # THE TOPIC IS NOT IN THE RUN NAME OR THE ARTIFACT NAME
 #
 # An artifact listing and a run listing are readable by an ANONYMOUS caller on a public
@@ -65,7 +72,7 @@ on:
         type: choice
         options: [probe, quick, normal]
       client_ref:
-        description: 'Optional caller reference for display and retries: [A-Za-z0-9][A-Za-z0-9._-]{0,63}. Correlation does not need it - pin X-GitHub-Api-Version and read workflow_run_id.'
+        description: 'PUBLIC on a public repository - it becomes the run name and the artifact name. Use an opaque id (job-0417), never the subject. Optional: correlation does not need it - pin X-GitHub-Api-Version and read workflow_run_id. Shape [A-Za-z0-9][A-Za-z0-9._-]{0,63}.'
         required: false
         default: ''
       runner:
@@ -135,6 +142,12 @@ jobs:
               console.error("Refused rather than rewritten: a sanitised token means you poll for a reference the artifact does not carry.");
               process.exit(1);
             }
+            // A WARNING, not a refusal. Whether a reference discloses a subject is a
+            // judgement about meaning, and a regex that tried to make it would refuse
+            // honest ids and pass `layoff-plan-q3` anyway - it fits the shape perfectly.
+            // What this can do is make sure nobody can say they were not told, on the run
+            // that used it, where they will see it.
+            console.log(`::warning::client_ref "${value}" is PUBLIC: it is this run's name and the artifact's name, both readable by anyone who can read this repository. If it names the subject, that subject is disclosed.`);
             console.log("client_ref accepted");
           '
 

research-kit/README.md

@@ -201,6 +201,11 @@ configured environment can supply.
 would return a measurably worse corpus under the same artifact name, and the person who
 asked for research would have no way to tell.
 
+**`client_ref` is public.** If you pass one it becomes the run name *and* the artifact
+name, both readable by anyone who can read the repository. Use an opaque job id
+(`job-0417`); never put the subject in it. `layoff-plan-q3` fits the permitted shape
+perfectly, which is why the workflow warns rather than pretending a regex could judge it.
+
 **Privacy, stated honestly.** The topic is in neither the run name nor the artifact name,
 because an anonymous caller can read both listings on a public repository. But
 `workflow_dispatch` inputs *are* visible on the run page to anyone with read access — this
@@ -328,7 +333,7 @@ node research-kit/bin/selftest.mjs            # all of it
 node research-kit/bin/selftest.mjs gate hook  # just these files
 ```
 
-753 tests, offline, no key and no network. The runner **awaits** every test, so `ok` means
+754 tests, offline, no key and no network. The runner **awaits** every test, so `ok` means
 the assertions settled (ADR-0021), and each test is raced against a watchdog
 (`RESEARCH_KIT_TEST_TIMEOUT`, default 60s).
 

research-kit/test/collector-workflow.test.mjs

@@ -151,6 +151,20 @@ test('the step summary reports hosts and counts, never URLs', () => {
     'the summary prints a whole URL; a path or query string discloses what was being researched');
 });
 
+test('the caller reference is declared PUBLIC where a dispatcher will read it', () => {
+  // Everything this workflow does to keep the topic out of the run and artifact names is
+  // undone by a caller who puts the subject in the reference - `layoff-plan-q3` fits the
+  // permitted shape perfectly. No regex can judge that, so the defence is that nobody can
+  // say they were not told, in the place they are actually looking: the dispatch form.
+  const input = body.slice(body.indexOf('client_ref:'));
+  const description = (input.match(/^\s*description:.*$/m) ?? [''])[0];
+  assert.ok(/PUBLIC/.test(description),
+    `the client_ref input does not warn that it becomes the public run and artifact name: ${description.trim()}`);
+
+  assert.ok(/::warning::client_ref/.test(body),
+    'the run should also warn on the run itself, where the reference was actually used');
+});
+
 // ---------------------------------------------------------------- correlation
 
 test('the dispatch API version is pinned, and the documented one', () => {