@agiledigital/pingone-aic-script-tester 0.1.0

package/dist/src/aic/emit-session.js

@@ -0,0 +1,132 @@
+import { randomUUID } from "node:crypto";
+import { AM_OWNED_SESSION_SET, DEFAULT_SESSION_PRINCIPAL, } from "../case/session.js";
+import { RESOURCE_PREFIX, SUCCESS_NODE_ID } from "./constants.js";
+import { jsStringLiteral } from "./js.js";
+/**
+ * A journey whose only job is to end, so that AM issues a session.
+ *
+ * There is no other way: a session exists only once a journey has run to
+ * completion (`docs/api/09-journeys.md` → "Minting a session for a test").
+ * Measured 2026-09-14 — the tree needs no Identify Existing User node, the
+ * principal need not exist as a managed object, and the journey that later
+ * *consumes* the session needs no configuration at all.
+ *
+ * AM-owned properties are dropped rather than sent. `putSessionProperty` does
+ * not override them; the whole login fails with a bare `401 Unauthorized`
+ * naming nothing, so sending one would turn a harness bug into an unexplained
+ * authentication failure. The five AM derives from the principal arrive by
+ * authenticating AS that principal instead.
+ */
+export function emitSessionJourney(session, options) {
+    const principal = session.UserId ?? DEFAULT_SESSION_PRINCIPAL;
+    const custom = Object.entries(session).filter(([key]) => !AM_OWNED_SESSION_SET.has(key));
+    const treeName = `${RESOURCE_PREFIX}-${options.runId}-session`;
+    const lines = [
+        "// Generated by rhino-local AIC lane: mints a session for the subject",
+        "// journey, which cannot seed `existingSession` any other way.",
+        `nodeState.putShared("username", ${jsStringLiteral(principal)});`,
+        'action.goTo("true")',
+    ];
+    for (const [key, value] of custom) {
+        lines.push(`  .putSessionProperty(${jsStringLiteral(key)}, ${jsStringLiteral(value)})`);
+    }
+    lines.push(";", "");
+    const script = {
+        id: randomUUID(),
+        name: `${treeName}-mint`,
+        source: lines.join("\n"),
+        role: "subject",
+    };
+    const node = {
+        id: randomUUID(),
+        displayName: "mint session",
+        scriptId: script.id,
+        outcomes: ["true"],
+        connections: { true: SUCCESS_NODE_ID },
+        x: 80,
+        y: 100,
+    };
+    return {
+        treeName,
+        realm: options.realm,
+        identityResource: `managed/${options.realm}_user`,
+        scripts: [script],
+        nodes: [node],
+        treeBody: {
+            identityResource: `managed/${options.realm}_user`,
+            entryNodeId: node.id,
+            innerTreeOnly: false,
+            description: "rhino-local AIC lane throwaway. Safe to delete.",
+            noSession: false,
+            mustRun: false,
+            enabled: true,
+            transactionalOnly: false,
+            uiConfig: { categories: '["Test"]' },
+            nodes: {
+                [node.id]: {
+                    connections: node.connections,
+                    displayName: node.displayName,
+                    nodeType: "ScriptedDecisionNode",
+                    version: "1.0",
+                    x: node.x,
+                    y: node.y,
+                },
+            },
+        },
+        nodeBodies: {
+            [node.id]: {
+                _id: node.id,
+                _type: {
+                    _id: "ScriptedDecisionNode",
+                    collection: true,
+                    name: "Scripted Decision",
+                },
+                _outcomes: [{ id: "true", displayName: "true" }],
+                inputs: ["*"],
+                outputs: ["*"],
+                outcomes: ["true"],
+                script: script.id,
+            },
+        },
+        subjectOutcomes: ["true"],
+        invoke: { headers: {}, parameters: {}, cookies: {} },
+    };
+}
+/** Deterministic session-minter resources owned by a file lease. */
+export function emitLeasedSessionJourney(session, options) {
+    const emitted = emitSessionJourney(session, {
+        runId: options.identity.idHash,
+        realm: options.realm,
+    });
+    const script = emitted.scripts[0];
+    const node = emitted.nodes[0];
+    script.id = options.identity.ids.sessionScript;
+    script.name = `${options.identity.ids.sessionTree}-mint`;
+    script.source = `// ${options.identity.marker}\n${script.source}`;
+    node.id = options.identity.ids.sessionNode;
+    node.scriptId = script.id;
+    emitted.treeName = options.identity.ids.sessionTree;
+    emitted.treeBody = {
+        ...emitted.treeBody,
+        entryNodeId: node.id,
+        description: options.identity.marker,
+        nodes: {
+            [node.id]: {
+                connections: node.connections,
+                displayName: node.displayName,
+                nodeType: "ScriptedDecisionNode",
+                x: node.x,
+                y: node.y,
+            },
+        },
+    };
+    emitted.nodeBodies = {
+        [node.id]: {
+            inputs: ["*"],
+            outputs: ["*"],
+            outcomes: node.outcomes,
+            script: script.id,
+        },
+    };
+    return emitted;
+}

package/dist/src/aic/emit-subject.d.ts

@@ -0,0 +1,40 @@
+import type { Given, JsonObject } from "../case/types.ts";
+export interface InstrumentedSubject {
+    source: string;
+    bindingName: string;
+    snapshotKey: string;
+    subjectDigest?: string;
+}
+export interface SubjectLeaseProof {
+    snapshotKey: string;
+    invocationNonce: string;
+    header?: string;
+}
+/**
+ * Seed `nodeState`, then capture it immediately before and after the author
+ * source.
+ *
+ * The author source stays at top level: wrapping it in a function or block
+ * changes AM's already-unusual top-level `const` behaviour. One generated
+ * binding is therefore visible to global enumeration. Its identifier and the
+ * state key written after the author source are chosen not to occur anywhere
+ * in the original source; helper names are private inside the binding's IIFE.
+ *
+ * The seed lives here rather than in a preceding setup node, and rather than
+ * in a query parameter. Measured 2026-09-13: state seeded in the subject, in
+ * a preceding node, and with the subject as the entry node all produced
+ * byte-identical results, so the extra node bought nothing. A query parameter
+ * would have been worse than useless — `requestParameters` is a binding the
+ * corpus measures, so harness data sitting in it is observable to the very
+ * scripts under test.
+ *
+ * The seed is applied BEFORE the `before` snapshot, matching what the setup
+ * node did: seeded values are the script's starting state, not a mutation it
+ * made. It is applied only on the node's FIRST pass — see the guard below.
+ */
+export declare function instrumentSubject(authorSource: string, runId: string, given?: Given, proof?: SubjectLeaseProof): InstrumentedSubject;
+/** JSON objects the subject will seed, for tests and invoke classification. */
+export declare function seededState(given: Given): {
+    shared: JsonObject;
+    transient: JsonObject;
+};

package/dist/src/aic/emit-subject.js

@@ -0,0 +1,210 @@
+import { jsonParseCall, jsStringLiteral } from "./js.js";
+import { sha256 } from "./lease-identity.js";
+const BINDING_PREFIX = "__rhinoLocalHarness_";
+const SNAPSHOT_KEY_PREFIX = "__rhino_local_snapshot_";
+const HELPERS = `\
+function keys(ns) {
+  var raw = ns.keys();
+  var out = [];
+  var i;
+  var it;
+  var k;
+  if (raw === null || raw === undefined) {
+    return out;
+  }
+  if (typeof raw.length === "number" && typeof raw !== "string") {
+    for (i = 0; i < raw.length; i += 1) {
+      out.push(String(raw[i]));
+    }
+    return out;
+  }
+  if (typeof raw.toArray === "function") {
+    raw = raw.toArray();
+    for (i = 0; i < raw.length; i += 1) {
+      out.push(String(raw[i]));
+    }
+    return out;
+  }
+  if (typeof raw.iterator === "function") {
+    it = raw.iterator();
+    while (it.hasNext()) {
+      out.push(String(it.next()));
+    }
+    return out;
+  }
+  if (typeof raw.size === "function" && typeof raw.get === "function" && typeof raw.keySet !== "function") {
+    for (i = 0; i < raw.size(); i += 1) {
+      out.push(String(raw.get(i)));
+    }
+    return out;
+  }
+  for (k in raw) {
+    if (Object.prototype.hasOwnProperty.call(raw, k) && typeof raw[k] !== "function") {
+      out.push(String(raw[k]));
+    }
+  }
+  return out;
+}
+
+function valueToJson(value) {
+  var t;
+  var i;
+  var k;
+  var out;
+  var mapKeys;
+  var arr;
+  if (value === null || value === undefined) {
+    return null;
+  }
+  t = typeof value;
+  if (t === "string" || t === "number" || t === "boolean") {
+    return value;
+  }
+  if (typeof Array.isArray === "function" && Array.isArray(value)) {
+    out = [];
+    for (i = 0; i < value.length; i += 1) {
+      out.push(valueToJson(value[i]));
+    }
+    return out;
+  }
+  if (typeof value.keySet === "function" && typeof value.get === "function") {
+    out = {};
+    mapKeys = value.keySet();
+    if (typeof mapKeys.toArray === "function") {
+      arr = mapKeys.toArray();
+      for (i = 0; i < arr.length; i += 1) {
+        out[String(arr[i])] = valueToJson(value.get(arr[i]));
+      }
+      return out;
+    }
+  }
+  if (typeof value.size === "function" && typeof value.get === "function") {
+    out = [];
+    for (i = 0; i < value.size(); i += 1) {
+      out.push(valueToJson(value.get(i)));
+    }
+    return out;
+  }
+  if (t === "object") {
+    out = {};
+    for (k in value) {
+      if (Object.prototype.hasOwnProperty.call(value, k) && typeof value[k] !== "function") {
+        out[String(k)] = valueToJson(value[k]);
+      }
+    }
+    return out;
+  }
+  return String(value);
+}
+
+function seed(map, put) {
+  var names = Object.keys(map);
+  var i;
+  for (i = 0; i < names.length; i += 1) {
+    put(names[i], map[names[i]]);
+  }
+}
+
+function snapshot(ns) {
+  var names = keys(ns);
+  var out = {};
+  var i;
+  var key;
+  for (i = 0; i < names.length; i += 1) {
+    key = names[i];
+    out[key] = valueToJson(ns.get(key));
+  }
+  return out;
+}
+`;
+/**
+ * Seed `nodeState`, then capture it immediately before and after the author
+ * source.
+ *
+ * The author source stays at top level: wrapping it in a function or block
+ * changes AM's already-unusual top-level `const` behaviour. One generated
+ * binding is therefore visible to global enumeration. Its identifier and the
+ * state key written after the author source are chosen not to occur anywhere
+ * in the original source; helper names are private inside the binding's IIFE.
+ *
+ * The seed lives here rather than in a preceding setup node, and rather than
+ * in a query parameter. Measured 2026-09-13: state seeded in the subject, in
+ * a preceding node, and with the subject as the entry node all produced
+ * byte-identical results, so the extra node bought nothing. A query parameter
+ * would have been worse than useless — `requestParameters` is a binding the
+ * corpus measures, so harness data sitting in it is observable to the very
+ * scripts under test.
+ *
+ * The seed is applied BEFORE the `before` snapshot, matching what the setup
+ * node did: seeded values are the script's starting state, not a mutation it
+ * made. It is applied only on the node's FIRST pass — see the guard below.
+ */
+export function instrumentSubject(authorSource, runId, given = {}, proof) {
+    const token = runId.replace(/-/g, "_");
+    const bindingName = unused(`${BINDING_PREFIX}${token}`, authorSource);
+    const snapshotKey = proof?.snapshotKey ?? unused(`${SNAPSHOT_KEY_PREFIX}${runId}`, authorSource);
+    const keyLit = jsStringLiteral(snapshotKey);
+    const body = authorSource.endsWith("\n") ? authorSource : `${authorSource}\n`;
+    const digestPlaceholder = `__AIC_SCRIPT_TESTER_DIGEST_${runId}__`;
+    const source = [
+        ...(proof?.header === undefined ? [] : [`// ${proof.header}`]),
+        "// Generated by rhino-local AIC lane. Seed and instrumentation precede",
+        "// the author source; request headers/parameters/cookies are sent on the",
+        "// authenticate call instead, because no script can assign those bindings.",
+        `var ${bindingName} = (function () {`,
+        HELPERS,
+        `return { snapshot: snapshot, seed: seed };`,
+        `}());`,
+        `// Seed once. A node that sends callbacks re-executes from the top when`,
+        `// the client answers, and re-seeding there would overwrite whatever the`,
+        `// earlier pass left in state with the request's original values — the`,
+        `// chain would silently restart from the top on every step.`,
+        `if (callbacks.isEmpty()) {`,
+        `  ${bindingName}.seed(${jsonParseCall(given.sharedState ?? {})}, function (k, v) {`,
+        `    nodeState.putShared(k, v);`,
+        `  });`,
+        `  ${bindingName}.seed(${jsonParseCall(given.transientState ?? {})}, function (k, v) {`,
+        `    nodeState.putTransient(k, v);`,
+        `  });`,
+        `}`,
+        `${bindingName}.before = ${bindingName}.snapshot(nodeState);`,
+        `// rhino-local author source begins`,
+        body,
+        `// rhino-local author source ends`,
+        `${bindingName}.final = ${bindingName}.snapshot(nodeState);`,
+        `nodeState.putTransient(${keyLit}, JSON.stringify({`,
+        `  before: ${bindingName}.before,`,
+        `  final: ${bindingName}.final${proof === undefined ? "" : ","}`,
+        ...(proof === undefined
+            ? []
+            : [
+                `  invocationNonce: ${jsStringLiteral(proof.invocationNonce)},`,
+                `  subjectDigest: ${jsStringLiteral(digestPlaceholder)}`,
+            ]),
+        `}));`,
+        "",
+    ].join("\n");
+    const subjectDigest = proof === undefined ? undefined : sha256(source);
+    return {
+        bindingName,
+        snapshotKey,
+        source: subjectDigest === undefined
+            ? source
+            : source.replace(digestPlaceholder, subjectDigest),
+        ...(subjectDigest === undefined ? {} : { subjectDigest }),
+    };
+}
+/** JSON objects the subject will seed, for tests and invoke classification. */
+export function seededState(given) {
+    return {
+        shared: given.sharedState ?? {},
+        transient: given.transientState ?? {},
+    };
+}
+function unused(seed, source) {
+    let candidate = seed;
+    while (source.includes(candidate)) {
+        candidate += "_";
+    }
+    return candidate;
+}

package/dist/src/aic/file-lease.d.ts

@@ -0,0 +1,35 @@
+import type { TenantProvider } from "./provider.ts";
+import type { LeaseLaneHooks } from "../harness/lease.ts";
+import { type ChainConformanceReport, type LocalChainResult } from "./conform.ts";
+import { type LeaseIdentity } from "./lease-identity.ts";
+import { type AicIo } from "./tenant.ts";
+export interface AicFileLeaseOptions {
+    id: string;
+    suiteName: string;
+    source: string;
+    outcomes: readonly string[];
+    realm?: string;
+    tenant?: string;
+    project?: string;
+    /** Where the tenant and its bearer come from; see `resolveTenantProvider`. */
+    provider?: TenantProvider;
+    unsupported?: "fail" | "skip";
+    io?: AicIo;
+    /** Test seam; production state defaults to the machine temp directory. */
+    stateDir?: string;
+    /** Test seam for proving a live lock fails closed without a long wait. */
+    lockTimeoutMs?: number;
+}
+export interface AicLeaseRunRequest extends LocalChainResult {
+    source: string;
+    hooks: LeaseLaneHooks;
+}
+export declare class AicFileLease {
+    #private;
+    constructor(options: AicFileLeaseOptions);
+    get identity(): LeaseIdentity;
+    open(): Promise<void>;
+    run(request: AicLeaseRunRequest): Promise<ChainConformanceReport>;
+    endTest(): Promise<void>;
+    close(): Promise<void>;
+}