@agiledigital/pingone-aic-script-tester 0.1.0

package/dist/src/aic/provider.js

@@ -0,0 +1,416 @@
+import { createPrivateKey, randomUUID, sign } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { headerValues, sendHttp } from "./http.js";
+export class TenantProviderError extends Error {
+    constructor(message, options = {}) {
+        super(message, options.cause !== undefined ? { cause: options.cause } : {});
+        this.name = "TenantProviderError";
+    }
+}
+/**
+ * The caller supplies the bearer. The harness calls `getToken` when a
+ * connection opens and again after a 401, and does no caching of its own.
+ */
+export function tokenCallbackProvider(options) {
+    const description = describeUrl(options.baseUrl, options.name);
+    const logs = options.logKeys === undefined
+        ? undefined
+        : logKeysReader(description.baseUrl, options.logKeys, options.http ?? sendHttp);
+    return {
+        describe: () => Promise.resolve(description),
+        async getToken(request) {
+            const token = (await options.getToken(request)).trim();
+            if (token.length === 0) {
+                throw new TenantProviderError("the token callback returned an empty token");
+            }
+            return token;
+        },
+        ...(logs === undefined ? {} : { logs }),
+    };
+}
+// --- service account --------------------------------------------------------
+/** `docs/api/00-auth.md`; a returned scope may be a re-ordered subset. */
+export const DEFAULT_SERVICE_ACCOUNT_SCOPE = "fr:am:* fr:idm:* fr:idc:esv:*";
+/** Assertions are rejected if `exp` is much past 180s (`docs/api/00-auth.md`). */
+const ASSERTION_LIFETIME_S = 180;
+/** Refresh this long before the tenant's `expires_in` runs out. */
+const REFRESH_MARGIN_S = 60;
+/**
+ * Mint bearers with the JWT-bearer grant, as the `aic` agent does: an RS256
+ * assertion (`iss` = `sub` = the account id, `aud` = the token endpoint, a
+ * short `exp`, a fresh `jti`) posted to the root realm's
+ * `/am/oauth2/access_token` as `client_id=service-account`.
+ *
+ * The token is cached until {@link REFRESH_MARGIN_S} before its
+ * `expires_in`; a `"rejected"` request always mints a new one.
+ */
+export function serviceAccountProvider(options) {
+    const description = describeUrl(options.baseUrl, options.name);
+    const key = privateKeyFrom(options.jwk);
+    const http = options.http ?? sendHttp;
+    const now = options.now ?? (() => Date.now() / 1000);
+    const tokenUrl = `${description.baseUrl}/am/oauth2/access_token`;
+    let cached;
+    async function mint() {
+        const issuedAt = Math.floor(now());
+        const assertion = signAssertion(key, {
+            iss: options.serviceAccountId,
+            sub: options.serviceAccountId,
+            aud: tokenUrl,
+            exp: issuedAt + ASSERTION_LIFETIME_S,
+            jti: randomUUID(),
+        });
+        const body = new URLSearchParams({
+            client_id: "service-account",
+            grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer",
+            assertion,
+            scope: options.scope ?? DEFAULT_SERVICE_ACCOUNT_SCOPE,
+        }).toString();
+        const response = await http({
+            url: tokenUrl,
+            method: "POST",
+            headerLines: [
+                ["Content-Type", "application/x-www-form-urlencoded"],
+                ["Accept", "application/json"],
+            ],
+            body,
+        });
+        if (response.status !== 200) {
+            throw new TenantProviderError(`service-account token request (POST /am/oauth2/access_token) returned ${response.status}` +
+                tokenErrorDetail(response.body, description.baseUrl));
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(response.body);
+        }
+        catch (error) {
+            throw new TenantProviderError("service-account token response is not JSON", {
+                cause: error,
+            });
+        }
+        const record = parsed;
+        if (typeof record.access_token !== "string" || record.access_token.length === 0) {
+            throw new TenantProviderError("service-account token response has no access_token");
+        }
+        const lifetime = typeof record.expires_in === "number" ? record.expires_in : 0;
+        cached = {
+            token: record.access_token,
+            refreshAt: issuedAt + Math.max(0, lifetime - REFRESH_MARGIN_S),
+        };
+        return record.access_token;
+    }
+    const logs = options.logKeys === undefined
+        ? undefined
+        : logKeysReader(description.baseUrl, options.logKeys, http);
+    return {
+        describe: () => Promise.resolve(description),
+        async getToken(request) {
+            if (request.reason === "initial" && cached !== undefined && now() < cached.refreshAt) {
+                return cached.token;
+            }
+            return mint();
+        },
+        ...(logs === undefined ? {} : { logs }),
+    };
+}
+function privateKeyFrom(jwk) {
+    let parsed;
+    try {
+        parsed = typeof jwk === "string" ? JSON.parse(jwk) : jwk;
+    }
+    catch (error) {
+        throw new TenantProviderError("the service-account JWK is not JSON", { cause: error });
+    }
+    if (parsed.kty !== "RSA" || typeof parsed.d !== "string") {
+        throw new TenantProviderError("the service-account JWK must be an RSA private key (kty RSA, with d)");
+    }
+    try {
+        return createPrivateKey({ key: parsed, format: "jwk" });
+    }
+    catch (error) {
+        throw new TenantProviderError("the service-account JWK is not a usable RSA private key", {
+            cause: error,
+        });
+    }
+}
+/** Compact JWS, RS256. Exported for tests that verify it with the public key. */
+export function signAssertion(key, claims) {
+    const header = base64url(JSON.stringify({ alg: "RS256", typ: "JWT" }));
+    const payload = base64url(JSON.stringify(claims));
+    const signature = sign("RSA-SHA256", Buffer.from(`${header}.${payload}`), key);
+    return `${header}.${payload}.${signature.toString("base64url")}`;
+}
+function base64url(text) {
+    return Buffer.from(text, "utf8").toString("base64url");
+}
+// --- logs via API key -------------------------------------------------------
+/** What `aic logs tx` reads by default (`src/logs/cli.rs`). */
+export const DEFAULT_LOG_SOURCES = ["am-everything", "idm-everything"];
+const ACCESS_OUTCOME = "AM-ACCESS-OUTCOME";
+const MAX_LOG_PAGES = 50;
+/** `aic`'s spacing (`src/logs/api.rs`): the API allows 60 requests/min. */
+const REQUEST_INTERVAL_MS = 1_050;
+const MAX_429_RETRIES = 6;
+/**
+ * `GET /monitoring/logs?source=…&transactionId=…` with the `x-api-key` /
+ * `x-api-secret` pair, following `pagedResultsCookie` — the query
+ * `aic logs tx` makes, with its request spacing and its `Retry-After`-honouring
+ * 429 backoff. The log API rejects bearers (`docs/api/08-logs.md`), which is
+ * why this needs its own keys.
+ *
+ * `transactionId` is a **prefix** match (`docs/api/08-logs.md`), as it is for
+ * `aic logs tx`: asking for a chain's stem returns every pass under it, which
+ * is what `show-log`'s "whole chain" choice relies on.
+ */
+export function logKeysReader(baseUrl, keys, http, options = {}) {
+    // Exported on its own, so it checks its origin itself: the keys go there.
+    const origin = describeUrl(baseUrl, undefined).baseUrl;
+    const pause = options.sleep ?? sleep;
+    const now = options.now ?? Date.now;
+    // The rate limit is per environment, not per reader: every default reader
+    // in the process shares one spacer, as `aic`'s process-global throttle does.
+    // A test that injects a clock gets its own, so tests cannot delay each other.
+    const spacer = options.sleep === undefined && options.now === undefined
+        ? sharedSpacer
+        : new RequestSpacer(pause, now);
+    async function get(url) {
+        for (let retry = 0;; retry += 1) {
+            await spacer.slot();
+            const response = await http({
+                url,
+                method: "GET",
+                headerLines: [
+                    ["x-api-key", keys.id],
+                    ["x-api-secret", keys.secret],
+                    ["Accept", "application/json"],
+                ],
+            });
+            if (response.status !== 429 || retry >= MAX_429_RETRIES) {
+                return response;
+            }
+            const retryAfter = Number(headerValues(response.headers, "retry-after")[0]);
+            const backoff = 1_000 * 2 ** Math.min(retry, 6);
+            await pause(Math.max(Number.isFinite(retryAfter) ? retryAfter * 1_000 : 0, backoff));
+        }
+    }
+    async function fetchAll(id) {
+        const events = [];
+        let cookie;
+        for (let page = 0; page < MAX_LOG_PAGES; page += 1) {
+            const params = new URLSearchParams({
+                source: DEFAULT_LOG_SOURCES.join(","),
+                transactionId: id,
+            });
+            if (cookie !== undefined) {
+                params.set("_pagedResultsCookie", cookie);
+            }
+            const response = await get(`${origin}/monitoring/logs?${params.toString()}`);
+            if (response.status !== 200) {
+                throw new TenantProviderError(`GET /monitoring/logs returned ${response.status}: ${scrubTenant(response.body, origin).slice(0, 300)}`);
+            }
+            let body;
+            try {
+                body = JSON.parse(response.body);
+            }
+            catch (error) {
+                throw new TenantProviderError("GET /monitoring/logs returned a body that is not JSON", {
+                    cause: error,
+                });
+            }
+            if (!Array.isArray(body.result)) {
+                throw new TenantProviderError("GET /monitoring/logs returned no result array");
+            }
+            events.push(...body.result);
+            cookie = typeof body.pagedResultsCookie === "string" ? body.pagedResultsCookie : undefined;
+            if (cookie === undefined || cookie.length === 0) {
+                return events;
+            }
+        }
+        throw new TenantProviderError(`transaction ${id} spans more than ${MAX_LOG_PAGES} log pages; narrow it`);
+    }
+    return {
+        async transaction(id, readOptions = {}) {
+            const waitMs = readOptions.waitMs ?? 60_000;
+            const started = now();
+            let events = await fetchAll(id);
+            // Back-to-back like `aic logs tx --wait`; the request spacing above is
+            // what keeps the loop inside the rate limit.
+            while (!hasAccessOutcome(events) && now() - started < waitMs) {
+                events = await fetchAll(id);
+            }
+            return events;
+        },
+    };
+}
+/**
+ * Hands out request slots at least {@link REQUEST_INTERVAL_MS} apart, in call
+ * order. Concurrent callers queue on one chain, so two cannot read the same
+ * "last request" time and wake together.
+ */
+class RequestSpacer {
+    #chain = Promise.resolve();
+    #last;
+    #pause;
+    #now;
+    constructor(pause, now) {
+        this.#pause = pause;
+        this.#now = now;
+    }
+    slot() {
+        const next = this.#chain.then(async () => {
+            if (this.#last !== undefined) {
+                const wait = this.#last + REQUEST_INTERVAL_MS - this.#now();
+                if (wait > 0) {
+                    await this.#pause(wait);
+                }
+            }
+            this.#last = this.#now();
+        });
+        this.#chain = next.catch(() => undefined);
+        return next;
+    }
+}
+const sharedSpacer = new RequestSpacer(sleep, Date.now);
+function hasAccessOutcome(events) {
+    return events.some((event) => event?.payload?.eventName ===
+        ACCESS_OUTCOME);
+}
+// --- environment ------------------------------------------------------------
+/** The variables {@link providerFromEnv} reads. */
+export const TENANT_ENV = {
+    url: "AIC_SCRIPT_TESTER_TENANT_URL",
+    name: "AIC_SCRIPT_TESTER_TENANT_NAME",
+    serviceAccountId: "AIC_SCRIPT_TESTER_SA_ID",
+    jwk: "AIC_SCRIPT_TESTER_SA_JWK",
+    jwkFile: "AIC_SCRIPT_TESTER_SA_JWK_FILE",
+    scope: "AIC_SCRIPT_TESTER_SA_SCOPE",
+    logKeyId: "AIC_SCRIPT_TESTER_LOG_KEY_ID",
+    logKeySecret: "AIC_SCRIPT_TESTER_LOG_KEY_SECRET",
+};
+/**
+ * A service-account provider from the environment, or `undefined` when
+ * `AIC_SCRIPT_TESTER_TENANT_URL` is unset. A partial configuration throws rather
+ * than falling back, so a typo cannot quietly send the run to another tenant.
+ */
+export function providerFromEnv(env = process.env) {
+    // Presence, not truthiness, decides whether a configuration was attempted:
+    // `AIC_SCRIPT_TESTER_SA_ID=` must not read as "unset" and fall through to `aic`.
+    const empty = Object.values(TENANT_ENV).filter((name) => env[name] === "");
+    if (empty.length > 0) {
+        throw new TenantProviderError(`${empty.join(", ")} ${empty.length === 1 ? "is" : "are"} set but empty`);
+    }
+    const url = env[TENANT_ENV.url];
+    if (url === undefined) {
+        const stray = Object.values(TENANT_ENV).filter((name) => env[name] !== undefined);
+        if (stray.length > 0) {
+            // Falling back to `aic` here would run against whatever context it has
+            // current — the very tenant these variables were set to avoid.
+            throw new TenantProviderError(`${stray.join(", ")} ${stray.length === 1 ? "is" : "are"} set but ${TENANT_ENV.url} is not`);
+        }
+        return undefined;
+    }
+    const id = env[TENANT_ENV.serviceAccountId];
+    const inline = env[TENANT_ENV.jwk];
+    const file = env[TENANT_ENV.jwkFile];
+    if (!id) {
+        throw new TenantProviderError(`${TENANT_ENV.url} is set but ${TENANT_ENV.serviceAccountId} is not`);
+    }
+    if (!inline === !file) {
+        throw new TenantProviderError(`${TENANT_ENV.url} is set: give exactly one of ${TENANT_ENV.jwk} or ${TENANT_ENV.jwkFile}`);
+    }
+    const jwk = inline ?? readFileSync(file, "utf8");
+    const keyId = env[TENANT_ENV.logKeyId];
+    const keySecret = env[TENANT_ENV.logKeySecret];
+    if (!keyId !== !keySecret) {
+        throw new TenantProviderError(`give both ${TENANT_ENV.logKeyId} and ${TENANT_ENV.logKeySecret}, or neither`);
+    }
+    const scope = env[TENANT_ENV.scope];
+    const name = env[TENANT_ENV.name];
+    return serviceAccountProvider({
+        baseUrl: url,
+        serviceAccountId: id,
+        jwk,
+        ...(scope ? { scope } : {}),
+        ...(name ? { name } : {}),
+        ...(keyId && keySecret ? { logKeys: { id: keyId, secret: keySecret } } : {}),
+    });
+}
+// --- registration -----------------------------------------------------------
+let registered;
+/**
+ * Set the provider every tenant-lane connection in this process uses, e.g.
+ * from a Vitest `setupFiles` module. Pass `undefined` to clear it.
+ */
+export function setTenantProvider(provider) {
+    registered = provider;
+}
+/** The registered provider, else one from the environment, else `undefined`. */
+export function configuredTenantProvider(env = process.env) {
+    return registered ?? providerFromEnv(env);
+}
+// --- helpers ----------------------------------------------------------------
+/**
+ * Re-check what a provider says about its tenant. Every built-in provider
+ * validates its URL when it is made, but a caller's own `TenantProvider` is
+ * only a promise, and `connectTenant` sends a bearer to whatever this returns.
+ */
+export function checkTenantDescription(description) {
+    if (typeof description.name !== "string" || description.name.trim() === "") {
+        throw new TenantProviderError("the tenant provider described a tenant with no name");
+    }
+    return describeUrl(description.baseUrl, description.name);
+}
+function describeUrl(baseUrl, name) {
+    let url;
+    try {
+        url = new URL(baseUrl);
+    }
+    catch (error) {
+        throw new TenantProviderError(`tenant base URL ${JSON.stringify(baseUrl)} is not a URL`, {
+            cause: error,
+        });
+    }
+    if (url.protocol !== "https:") {
+        // The assertion, every bearer and the log keys travel to this origin.
+        throw new TenantProviderError(`tenant base URL must be https (got ${url.protocol.replace(/:$/, "")})`);
+    }
+    if (url.pathname !== "/" && url.pathname !== "") {
+        throw new TenantProviderError(`tenant base URL must have no path (got ${url.pathname}); the harness adds /am and /openidm`);
+    }
+    return { name: name ?? url.hostname, baseUrl: url.origin };
+}
+/**
+ * The OAuth `error` / `error_description` of a refused token request, with the
+ * tenant's origin and hostname replaced. The description is what names the
+ * problem (a bad `aud` quotes the URL it expected), but the message ends up in
+ * test output and CI logs, where the tenant's hostname does not belong.
+ */
+export function tokenErrorDetail(body, baseUrl) {
+    let parsed;
+    try {
+        parsed = JSON.parse(body);
+    }
+    catch {
+        return "";
+    }
+    if (typeof parsed !== "object" || parsed === null) {
+        return "";
+    }
+    const { error, error_description: description } = parsed;
+    const scrub = (text) => scrubTenant(text, baseUrl).slice(0, 200);
+    const parts = [
+        typeof error === "string" ? scrub(error) : undefined,
+        typeof description === "string" ? scrub(description) : undefined,
+    ].filter((part) => part !== undefined && part !== "");
+    return parts.length === 0 ? "" : `: ${parts.join(" — ")}`;
+}
+/** `text` with the tenant's origin and hostname replaced by `<tenant>`. */
+export function scrubTenant(text, baseUrl) {
+    const host = new URL(baseUrl).hostname;
+    return text.split(baseUrl).join("<tenant>").split(host).join("<tenant>");
+}
+function sleep(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}

package/dist/src/aic/record.d.ts

@@ -0,0 +1,28 @@
+import type { CallbackEffect, Given, JsonObject, RecordedEffects } from "../case/types.ts";
+export interface SubjectDump {
+    outcome: string;
+    before: JsonObject;
+    final: JsonObject;
+    leaseDigest?: string;
+    invocationNonce?: string;
+    subjectDigest?: string;
+}
+/**
+ * Parse the result-script payload. The script records `outcome` and the
+ * unified `nodeState` map; this module classifies keys into shared/transient/
+ * secure using `given`, so the dump does not reimplement the verdict rule.
+ */
+export declare function parseSubjectDump(raw: unknown): SubjectDump;
+export declare function assembleEffects(args: {
+    given: Given;
+    dump?: SubjectDump;
+    callbacks: CallbackEffect[];
+}): RecordedEffects;
+/**
+ * Classify only what the AIC wrapper actually established. The snapshots use
+ * unified `nodeState.keys/get`, so a changed or added value is observable but
+ * its bucket is not. Declared seeds remain exact only while unchanged; a seed
+ * missing afterwards is an exact removal only when it existed in one bucket.
+ * State present before the subject but absent from `given` is ambient.
+ */
+export declare function classifyFinal(given: Given, before: JsonObject, final: JsonObject): Pick<Required<RecordedEffects>, "sharedState" | "transientState" | "secureState" | "evidence">;

package/dist/src/aic/record.js

@@ -0,0 +1,183 @@
+import { STATE_CHANNELS } from "../case/types.js";
+import { deepEqual } from "../case/equal.js";
+import { diffState } from "../case/state.js";
+import { isPlainObject, parseJsonObject } from "../case/util.js";
+const AIC_UNOBSERVED = ["openidm", "http", "logs"];
+/**
+ * Parse the result-script payload. The script records `outcome` and the
+ * unified `nodeState` map; this module classifies keys into shared/transient/
+ * secure using `given`, so the dump does not reimplement the verdict rule.
+ */
+export function parseSubjectDump(raw) {
+    if (typeof raw === "string") {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`rhino-local: harness dump is not JSON: ${message}`, { cause: error });
+        }
+        return parseSubjectDump(parsed);
+    }
+    if (!isPlainObject(raw)) {
+        throw new Error("rhino-local: harness dump is not an object");
+    }
+    if (typeof raw.outcome !== "string") {
+        throw new Error("rhino-local: harness dump.outcome must be a string");
+    }
+    if (!("before" in raw) || !("final" in raw)) {
+        throw new Error("rhino-local: harness dump must have before and final");
+    }
+    return {
+        outcome: raw.outcome,
+        before: parseJsonObject(raw.before, "dump.before"),
+        final: parseJsonObject(raw.final, "dump.final"),
+        ...(typeof raw.leaseDigest === "string" ? { leaseDigest: raw.leaseDigest } : {}),
+        ...(typeof raw.invocationNonce === "string"
+            ? { invocationNonce: raw.invocationNonce }
+            : {}),
+        ...(typeof raw.subjectDigest === "string"
+            ? { subjectDigest: raw.subjectDigest }
+            : {}),
+    };
+}
+export function assembleEffects(args) {
+    const sharedInitial = args.given.sharedState ?? {};
+    const transientInitial = args.given.transientState ?? {};
+    const secureInitial = args.given.secureState ?? {};
+    if (args.dump === undefined) {
+        // Subject suspended with callbacks: the result node never ran, so we
+        // did not observe nodeState. Claiming every given key was removed would
+        // be a false mutation.
+        return {
+            outcome: null,
+            sharedState: { initial: sharedInitial, final: { ...sharedInitial } },
+            transientState: { initial: transientInitial, final: { ...transientInitial } },
+            secureState: { initial: secureInitial, final: { ...secureInitial } },
+            callbacks: args.callbacks,
+            openidm: [],
+            http: [],
+            logs: [],
+            evidence: {
+                stateBuckets: "unified",
+                ambientState: {},
+                unbucketedState: [],
+                unobservedChannels: [
+                    "sharedState",
+                    "transientState",
+                    "secureState",
+                    ...AIC_UNOBSERVED,
+                ],
+            },
+        };
+    }
+    const classified = classifyFinal(args.given, args.dump.before, args.dump.final);
+    return {
+        outcome: args.dump.outcome,
+        sharedState: classified.sharedState,
+        transientState: classified.transientState,
+        secureState: classified.secureState,
+        callbacks: args.callbacks,
+        openidm: [],
+        http: [],
+        logs: [],
+        evidence: classified.evidence,
+    };
+}
+/**
+ * Classify only what the AIC wrapper actually established. The snapshots use
+ * unified `nodeState.keys/get`, so a changed or added value is observable but
+ * its bucket is not. Declared seeds remain exact only while unchanged; a seed
+ * missing afterwards is an exact removal only when it existed in one bucket.
+ * State present before the subject but absent from `given` is ambient.
+ */
+export function classifyFinal(given, before, final) {
+    const sharedInitial = given.sharedState ?? {};
+    const transientInitial = given.transientState ?? {};
+    const secureInitial = given.secureState ?? {};
+    verifySeedsVisible(given, before);
+    const sharedFinal = { ...sharedInitial };
+    const transientFinal = { ...transientInitial };
+    const secureFinal = { ...secureInitial };
+    const ambientState = {};
+    for (const [key, value] of Object.entries(before)) {
+        if (seedBuckets(given, key).length === 0) {
+            ambientState[key] = value;
+        }
+    }
+    const unbucketedState = [];
+    for (const mutation of diffState(before, final)) {
+        const buckets = seedBuckets(given, mutation.key);
+        if (mutation.operation === "removed" && buckets.length === 1) {
+            const bucket = buckets[0];
+            if (bucket !== undefined) {
+                delete finalFor(bucket, sharedFinal, transientFinal, secureFinal)[mutation.key];
+            }
+            continue;
+        }
+        unbucketedState.push({
+            ...mutation,
+            possibleBuckets: buckets.length === 0 && mutation.operation === "added"
+                ? ["sharedState", "transientState"]
+                : [...STATE_CHANNELS],
+        });
+    }
+    return {
+        sharedState: { initial: sharedInitial, final: sharedFinal },
+        transientState: { initial: transientInitial, final: transientFinal },
+        secureState: { initial: secureInitial, final: secureFinal },
+        evidence: {
+            stateBuckets: "unified",
+            ambientState,
+            unbucketedState,
+            unobservedChannels: [...AIC_UNOBSERVED],
+        },
+    };
+}
+function seedBuckets(given, key) {
+    const buckets = [];
+    if (Object.prototype.hasOwnProperty.call(given.sharedState ?? {}, key)) {
+        buckets.push("sharedState");
+    }
+    if (Object.prototype.hasOwnProperty.call(given.transientState ?? {}, key)) {
+        buckets.push("transientState");
+    }
+    if (Object.prototype.hasOwnProperty.call(given.secureState ?? {}, key)) {
+        buckets.push("secureState");
+    }
+    return buckets;
+}
+function verifySeedsVisible(given, before) {
+    const keys = new Set([
+        ...Object.keys(given.sharedState ?? {}),
+        ...Object.keys(given.secureState ?? {}),
+        ...Object.keys(given.transientState ?? {}),
+    ]);
+    for (const key of keys) {
+        const expected = visibleSeed(given, key);
+        if (!Object.prototype.hasOwnProperty.call(before, key) ||
+            !deepEqual(before[key], expected)) {
+            throw new Error(`rhino-local: AIC subject state did not contain the declared seed ${JSON.stringify(key)}`);
+        }
+    }
+}
+function visibleSeed(given, key) {
+    // AM's unified lookup precedence is transient → secure → shared.
+    if (Object.prototype.hasOwnProperty.call(given.transientState ?? {}, key)) {
+        return given.transientState?.[key];
+    }
+    if (Object.prototype.hasOwnProperty.call(given.secureState ?? {}, key)) {
+        return given.secureState?.[key];
+    }
+    return given.sharedState?.[key];
+}
+function finalFor(bucket, shared, transient, secure) {
+    if (bucket === "sharedState") {
+        return shared;
+    }
+    if (bucket === "transientState") {
+        return transient;
+    }
+    return secure;
+}

package/dist/src/aic/resource-snapshot.d.ts

@@ -0,0 +1,12 @@
+export type AicResourceKind = "script" | "node" | "tree";
+/** Strip server-owned node metadata even though AM accepts some of it. */
+export declare function nodeRequestProjection(value: Readonly<Record<string, unknown>>): Record<string, unknown>;
+export declare function resourceRequestProjection(kind: AicResourceKind, value: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/**
+ * Return the snapshot from the confirming GET, never from submitted bytes.
+ *
+ * Script and tree `description` round-trips byte-exact (measured 2026-09-14,
+ * `docs/api/04-scripts.md`), so the marker stays in the comparison rather than
+ * being normalized away — a rewritten marker is a real failure, not noise.
+ */
+export declare function confirmResourceSnapshot(kind: AicResourceKind, submitted: Readonly<Record<string, unknown>>, confirmed: unknown): Record<string, unknown>;