@agiledigital/pingone-aic-script-tester 0.1.0

package/dist/src/case/types.d.ts

@@ -0,0 +1,266 @@
+/**
+ * Runner-agnostic scripted-decision case: one definition drives the local
+ * Rhino lane and the AIC wrapper-journey lane. `given` is the seed;
+ * `expect` is diffs and per-channel effects, never whole-state equality.
+ */
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | JsonValue[];
+export interface JsonObject {
+    [key: string]: JsonValue;
+}
+export type Pattern = string | RegExp;
+export declare const CASE_KEYS: readonly ["name", "script", "outcomes", "given", "expect"];
+export type CaseKey = (typeof CASE_KEYS)[number];
+export declare const ENGINES: readonly ["next-gen", "legacy"];
+export type Engine = (typeof ENGINES)[number];
+export declare const GIVEN_KEYS: readonly ["sharedState", "transientState", "secureState", "realm", "scriptName", "cookieName", "resumedFromSuspend", "requestHeaders", "requestParameters", "requestCookies", "locales", "existingSession", "esv", "secrets", "callbacks", "managed", "http", "engine", "bindings"];
+export type GivenKey = (typeof GIVEN_KEYS)[number];
+/** Bindings that have a dedicated `given` field; do not also put them in `bindings`. */
+export declare const GIVEN_BINDING_SEEDS: readonly ["realm", "scriptName", "cookieName", "resumedFromSuspend", "requestHeaders", "requestParameters", "requestCookies", "locales", "existingSession"];
+export declare const EXPECT_KEYS: readonly ["outcome", "sharedState", "transientState", "secureState", "callbacks", "openidm", "http", "logs", "allowUndeclared"];
+export type ExpectKey = (typeof EXPECT_KEYS)[number];
+export declare const STATE_DIFF_KEYS: readonly ["added", "changed", "removed"];
+export declare const ALLOW_UNDECLARED_CHANNELS: readonly ["openidmWrites", "openidmReads", "http", "logs", "callbacks", "sharedState", "transientState", "secureState"];
+export type AllowUndeclaredChannel = (typeof ALLOW_UNDECLARED_CHANNELS)[number];
+export type AllowUndeclared = {
+    [K in AllowUndeclaredChannel]?: boolean;
+};
+/**
+ * Per-channel defaults. Fail-closed on undeclared writes, HTTP, callbacks,
+ * and state mutations; fail-open on reads and log lines. Loosening a
+ * fail-closed channel requires an explicit `allowUndeclared` flag.
+ */
+export declare const DEFAULT_ALLOW_UNDECLARED: {
+    readonly [K in AllowUndeclaredChannel]: boolean;
+};
+export declare const OPENIDM_WRITE_METHODS: readonly ["create", "update", "patch", "delete", "action"];
+export declare const OPENIDM_READ_METHODS: readonly ["read", "query"];
+export declare const OPENIDM_METHODS: readonly ["create", "update", "patch", "delete", "action", "read", "query"];
+export type OpenidmWriteMethod = (typeof OPENIDM_WRITE_METHODS)[number];
+export type OpenidmReadMethod = (typeof OPENIDM_READ_METHODS)[number];
+export type OpenidmMethod = (typeof OPENIDM_METHODS)[number];
+export declare const LOG_LEVELS: readonly ["error", "warn", "info", "debug", "trace"];
+export type LogLevel = (typeof LOG_LEVELS)[number];
+export declare const CHANNELS: readonly ["outcome", "sharedState", "transientState", "secureState", "callbacks", "openidm", "http", "logs"];
+export type Channel = (typeof CHANNELS)[number];
+export declare const STATE_CHANNELS: readonly ["sharedState", "transientState", "secureState"];
+export type StateChannel = (typeof STATE_CHANNELS)[number];
+export type EvidenceChannel = Channel | "nodeState";
+export declare const ENV_INPUT_KEYS: readonly ["esv", "secrets", "managed", "http"];
+export type EnvInputKey = (typeof ENV_INPUT_KEYS)[number];
+export interface StateDiff {
+    added?: JsonObject;
+    changed?: JsonObject;
+    removed?: string[];
+}
+export interface HttpMatch {
+    url: Pattern;
+    method?: string;
+}
+export interface HttpReply {
+    status: number;
+    body?: JsonValue;
+    headers?: Record<string, string>;
+}
+export interface HttpStub {
+    match: HttpMatch;
+    reply: HttpReply;
+}
+export interface HttpExpect {
+    url: Pattern;
+    method?: string;
+    times?: number;
+}
+export interface HttpEffect {
+    url: string;
+    method: string;
+    body?: JsonValue;
+}
+export interface OpenidmExpect {
+    method: OpenidmMethod;
+    resource: Pattern;
+    body?: JsonValue;
+    actionName?: Pattern;
+    times?: number;
+}
+export interface OpenidmEffect {
+    method: OpenidmMethod;
+    resource: string;
+    body?: JsonValue;
+    actionName?: string;
+}
+export interface LogExpect {
+    level?: LogLevel;
+    message: Pattern;
+    times?: number;
+}
+export interface LogEffect {
+    level: LogLevel;
+    message: string;
+}
+export interface CallbackEffect {
+    type: string;
+    [key: string]: JsonValue;
+}
+export interface Given {
+    sharedState?: JsonObject;
+    transientState?: JsonObject;
+    secureState?: JsonObject;
+    realm?: string;
+    scriptName?: string;
+    cookieName?: string;
+    resumedFromSuspend?: boolean;
+    requestHeaders?: Record<string, string[]>;
+    requestParameters?: Record<string, string[]>;
+    requestCookies?: Record<string, string>;
+    locales?: JsonObject;
+    /**
+     * `existingSession`. Present only when the request carries a session cookie,
+     * and then a String->String map: AM's own session properties plus anything a
+     * prior journey stored with `putSessionProperty`. Measured 2026-09-14 on both
+     * evaluators (docs/api/12-script-bindings-matrix.md).
+     */
+    existingSession?: Record<string, string>;
+    esv?: Record<string, string>;
+    secrets?: Record<string, string>;
+    /**
+     * Submitted callback values a resumed script reads via `callbacks.getXCallbacks()`.
+     * Omit to leave the binding unseeded (a read throws naming `given.callbacks`);
+     * seed `[]` for a first pass.
+     */
+    callbacks?: CallbackEffect[];
+    managed?: Record<string, JsonObject[]>;
+    http?: HttpStub[];
+    engine?: Engine;
+    /**
+     * Extra binding seeds keyed by generated mock binding name. Unknown names
+     * fail validation — a typo must not silently seed nothing. The runtime
+     * implements one today, `journey` (`name`, `identityResource`); any other
+     * name throws when the case runs.
+     */
+    bindings?: Record<string, JsonValue>;
+}
+export interface Expect {
+    /**
+     * The outcome the script must reach, or `null` for "must not decide" — a
+     * pass that queued callbacks and suspended. A suspended pass is a real
+     * expectation, not an absence of one: measured 2026-09-14, a next-gen node
+     * that sends callbacks returns no outcome at all, and the only way to say so
+     * without `null` is to name an outcome the script never produces.
+     */
+    outcome: string | null;
+    sharedState?: StateDiff;
+    transientState?: StateDiff;
+    secureState?: StateDiff;
+    callbacks?: CallbackEffect[];
+    openidm?: OpenidmExpect[];
+    http?: HttpExpect[];
+    logs?: LogExpect[];
+    allowUndeclared?: AllowUndeclared;
+}
+export interface CaseInit {
+    name: string;
+    script: string;
+    /**
+     * The outcome vocabulary this script may produce. Optional here, required
+     * to run on a tenant: AM answers an undeclared outcome with a bare
+     * `401 Login failure` and no callback, byte-identical to a compile error,
+     * so the wrapper journey has to declare every outcome up front and the
+     * only way to be sure it did is for the case to say what they are.
+     *
+     * Declaring it also moves the typo from an opaque tenant 401 to a local
+     * failure in under a second, which is why the local lane enforces it too.
+     */
+    outcomes?: readonly string[];
+    given?: Given;
+    expect: Expect;
+}
+export interface Case {
+    name: string;
+    script: string;
+    outcomes?: readonly string[];
+    given: Given;
+    expect: Expect;
+}
+export interface StateBucket {
+    initial: JsonObject;
+    final: JsonObject;
+}
+export type StateMutation = {
+    operation: "added";
+    key: string;
+    after: JsonValue;
+} | {
+    operation: "changed";
+    key: string;
+    before: JsonValue;
+    after: JsonValue;
+} | {
+    operation: "removed";
+    key: string;
+    before: JsonValue;
+};
+export type UnbucketedStateMutation = StateMutation & {
+    possibleBuckets: StateChannel[];
+};
+/** What a runner could establish in addition to the effect values themselves. */
+export interface RecordingEvidence {
+    /** `unified` means per-bucket absence and hidden lower-precedence writes are unknowable. */
+    stateBuckets: "exact" | "unified";
+    /** Unified state present before the subject but absent from `given`. */
+    ambientState: JsonObject;
+    /** Unified state mutations whose concrete bucket could not be observed. */
+    unbucketedState: UnbucketedStateMutation[];
+    /** An empty effect value in one of these channels is not an observation of absence. */
+    unobservedChannels: Channel[];
+}
+/**
+ * Observed effects of one run. Every channel is required: omitting a
+ * fail-closed channel would silently assert nothing, which is the failure
+ * mode this harness exists to avoid. The runner fills this in; the verdict
+ * engine treats it as data.
+ */
+export interface RecordedEffects {
+    outcome: string | null;
+    sharedState: StateBucket;
+    transientState: StateBucket;
+    secureState: StateBucket;
+    callbacks: CallbackEffect[];
+    openidm: OpenidmEffect[];
+    http: HttpEffect[];
+    logs: LogEffect[];
+    /** Omitted by exact recorders; present when a lane has qualified evidence. */
+    evidence?: RecordingEvidence;
+    /**
+     * The mock `openidm` store as it stood when the script finished. Evidence
+     * for the post-test residue check, deliberately NOT a judged channel — it
+     * answers "did anything survive that the harness did not create", which is
+     * a property of the test's housekeeping rather than of the script's
+     * behaviour. Only the local lane can produce it; AIC has no way to observe
+     * the tenant's whole store, and pretending otherwise would put an empty
+     * object where "unknown" belongs.
+     */
+    managedStore?: Record<string, JsonObject[]>;
+}
+export interface Mismatch {
+    channel: EvidenceChannel;
+    path: string;
+    expected: string;
+    actual: string;
+    message: string;
+}
+export interface Unverified {
+    channel: EvidenceChannel;
+    path: string;
+    message: string;
+}
+export interface Verdict {
+    pass: boolean;
+    /** False when no contradiction was seen but one or more assertions were unobservable. */
+    conclusive: boolean;
+    portable: boolean;
+    mismatches: Mismatch[];
+    unverified: Unverified[];
+    /** Multi-line explanation; empty string when `pass` is true. */
+    summary: string;
+}

package/dist/src/case/types.js

@@ -0,0 +1,106 @@
+/**
+ * Runner-agnostic scripted-decision case: one definition drives the local
+ * Rhino lane and the AIC wrapper-journey lane. `given` is the seed;
+ * `expect` is diffs and per-channel effects, never whole-state equality.
+ */
+export const CASE_KEYS = ["name", "script", "outcomes", "given", "expect"];
+export const ENGINES = ["next-gen", "legacy"];
+export const GIVEN_KEYS = [
+    "sharedState",
+    "transientState",
+    "secureState",
+    "realm",
+    "scriptName",
+    "cookieName",
+    "resumedFromSuspend",
+    "requestHeaders",
+    "requestParameters",
+    "requestCookies",
+    "locales",
+    "existingSession",
+    "esv",
+    "secrets",
+    "callbacks",
+    "managed",
+    "http",
+    "engine",
+    "bindings",
+];
+/** Bindings that have a dedicated `given` field; do not also put them in `bindings`. */
+export const GIVEN_BINDING_SEEDS = [
+    "realm",
+    "scriptName",
+    "cookieName",
+    "resumedFromSuspend",
+    "requestHeaders",
+    "requestParameters",
+    "requestCookies",
+    "locales",
+    "existingSession",
+];
+export const EXPECT_KEYS = [
+    "outcome",
+    "sharedState",
+    "transientState",
+    "secureState",
+    "callbacks",
+    "openidm",
+    "http",
+    "logs",
+    "allowUndeclared",
+];
+export const STATE_DIFF_KEYS = ["added", "changed", "removed"];
+export const ALLOW_UNDECLARED_CHANNELS = [
+    "openidmWrites",
+    "openidmReads",
+    "http",
+    "logs",
+    "callbacks",
+    "sharedState",
+    "transientState",
+    "secureState",
+];
+/**
+ * Per-channel defaults. Fail-closed on undeclared writes, HTTP, callbacks,
+ * and state mutations; fail-open on reads and log lines. Loosening a
+ * fail-closed channel requires an explicit `allowUndeclared` flag.
+ */
+export const DEFAULT_ALLOW_UNDECLARED = {
+    openidmWrites: false,
+    openidmReads: true,
+    http: false,
+    logs: true,
+    callbacks: false,
+    sharedState: false,
+    transientState: false,
+    secureState: false,
+};
+export const OPENIDM_WRITE_METHODS = [
+    "create",
+    "update",
+    "patch",
+    "delete",
+    "action",
+];
+export const OPENIDM_READ_METHODS = ["read", "query"];
+export const OPENIDM_METHODS = [
+    ...OPENIDM_WRITE_METHODS,
+    ...OPENIDM_READ_METHODS,
+];
+export const LOG_LEVELS = ["error", "warn", "info", "debug", "trace"];
+export const CHANNELS = [
+    "outcome",
+    "sharedState",
+    "transientState",
+    "secureState",
+    "callbacks",
+    "openidm",
+    "http",
+    "logs",
+];
+export const STATE_CHANNELS = [
+    "sharedState",
+    "transientState",
+    "secureState",
+];
+export const ENV_INPUT_KEYS = ["esv", "secrets", "managed", "http"];

package/dist/src/case/util.d.ts

@@ -0,0 +1,7 @@
+import type { JsonObject, JsonValue } from "./types.ts";
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+export declare function formatValue(value: unknown): string;
+export declare function suggestKey(unknown: string, allowed: readonly string[]): string | undefined;
+export declare function unknownKeyError(path: string, key: string, allowed: readonly string[]): Error;
+export declare function parseJsonValue(raw: unknown, path: string): JsonValue;
+export declare function parseJsonObject(raw: unknown, path: string): JsonObject;

package/dist/src/case/util.js

@@ -0,0 +1,115 @@
+export function isPlainObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const proto = Object.getPrototypeOf(value);
+    return proto === Object.prototype || proto === null;
+}
+export function formatValue(value) {
+    if (value === undefined) {
+        return "<absent>";
+    }
+    if (value instanceof RegExp) {
+        return String(value);
+    }
+    if (typeof value === "string") {
+        return JSON.stringify(value);
+    }
+    if (typeof value === "function") {
+        return "<function>";
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+export function suggestKey(unknown, allowed) {
+    const lower = unknown.toLowerCase();
+    const contained = allowed.filter((key) => key.toLowerCase().includes(lower) || lower.includes(key.toLowerCase()));
+    if (contained.length === 1) {
+        return contained[0];
+    }
+    let best;
+    let bestDistance = Infinity;
+    for (const key of allowed) {
+        const distance = editDistance(lower, key.toLowerCase());
+        if (distance < bestDistance) {
+            bestDistance = distance;
+            best = key;
+        }
+    }
+    if (best !== undefined && bestDistance <= 2) {
+        return best;
+    }
+    return contained[0];
+}
+export function unknownKeyError(path, key, allowed) {
+    const suggestion = suggestKey(key, allowed);
+    const hint = suggestion === undefined ? "" : ` (did you mean "${suggestion}"?)`;
+    return new Error(`rhino-local: ${path} has unknown key "${key}"${hint}. Allowed: ${allowed.join(", ")}`);
+}
+function editDistance(a, b) {
+    const rows = a.length;
+    const cols = b.length;
+    const width = cols + 1;
+    const dp = new Int32Array((rows + 1) * width);
+    for (let i = 0; i <= rows; i += 1) {
+        dp[i * width] = i;
+    }
+    for (let j = 0; j <= cols; j += 1) {
+        dp[j] = j;
+    }
+    for (let i = 1; i <= rows; i += 1) {
+        for (let j = 1; j <= cols; j += 1) {
+            const cost = a.charAt(i - 1) === b.charAt(j - 1) ? 0 : 1;
+            const deletion = (dp[(i - 1) * width + j] ?? 0) + 1;
+            const insertion = (dp[i * width + (j - 1)] ?? 0) + 1;
+            const substitution = (dp[(i - 1) * width + (j - 1)] ?? 0) + cost;
+            dp[i * width + j] = Math.min(deletion, insertion, substitution);
+        }
+    }
+    return dp[rows * width + cols] ?? Math.max(rows, cols);
+}
+export function parseJsonValue(raw, path) {
+    if (raw === null || typeof raw === "string" || typeof raw === "boolean") {
+        return raw;
+    }
+    if (typeof raw === "number") {
+        if (!Number.isFinite(raw)) {
+            throw new Error(`rhino-local: ${path} must be a finite number`);
+        }
+        return raw;
+    }
+    if (Array.isArray(raw)) {
+        return raw.map((item, index) => parseJsonValue(item, `${path}[${index}]`));
+    }
+    if (isPlainObject(raw)) {
+        const object = {};
+        for (const [key, value] of Object.entries(raw)) {
+            object[key] = parseJsonValue(value, `${path}.${key}`);
+        }
+        return object;
+    }
+    throw new Error(`rhino-local: ${path} is not a JSON value (${describeType(raw)})`);
+}
+export function parseJsonObject(raw, path) {
+    const value = parseJsonValue(raw, path);
+    if (!isPlainObject(value)) {
+        throw new Error(`rhino-local: ${path} must be an object`);
+    }
+    return value;
+}
+function describeType(value) {
+    if (value === null) {
+        return "null";
+    }
+    if (Array.isArray(value)) {
+        return "array";
+    }
+    if (value instanceof RegExp) {
+        return "RegExp";
+    }
+    return typeof value;
+}

package/dist/src/case/validate.d.ts

@@ -0,0 +1,8 @@
+import type { Case, CaseInit } from "./types.ts";
+/** Typed entry point for case authors. */
+export declare function defineCase(input: CaseInit): Case;
+/**
+ * Runtime validation. Dynamic cases (and typos TypeScript never sees) must
+ * fail here rather than assert nothing.
+ */
+export declare function validateCase(input: unknown): Case;