@agiledigital/pingone-aic-script-tester 0.1.0

package/dist/src/aic/managed.js

@@ -0,0 +1,199 @@
+import { createHash } from "node:crypto";
+import { mkdir, readFile, rmdir, stat, unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deepEqual } from "../case/equal.js";
+import { isPlainObject } from "../case/util.js";
+import { AicLaneError, amRequest } from "./tenant.js";
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/**
+ * Fields the maintainer measured as accepted on create but omitted by GET.
+ * Additions need their own live evidence; skipping every absent field would
+ * let a silently dropped readable value pass the seed check.
+ */
+const READBACK_EXEMPT_FIELDS = {
+    "managed/alpha_user": ["password"],
+};
+/** Whether the first pass's managed seed came exactly from this fixture ledger. */
+export function managedSeedMatches(managed, fixtures) {
+    const seeded = {};
+    for (const fixture of fixtures) {
+        const rows = seeded[fixture.type] ?? [];
+        rows.push(fixture.record);
+        seeded[fixture.type] = rows;
+    }
+    return deepEqual(managed ?? {}, seeded);
+}
+/** Create with CREST's create-only request, then prove every declared field landed. */
+export async function seedManagedFixtures(io, session, fixtures, seeded) {
+    for (const fixture of fixtures) {
+        const identity = fixtureIdentity(fixture);
+        const response = await amRequest(io, session, {
+            method: "POST",
+            path: `${identity.collection}?_action=create`,
+            body: JSON.stringify(fixture.record),
+        });
+        if (response.status === 412) {
+            throw new AicLaneError(`managed fixture collision at ${identity.resource}: _id ${JSON.stringify(identity.id)} already exists; it may be a leaked fixture or tenant-owned record`);
+        }
+        if (response.status !== 201) {
+            throw new AicLaneError(`create managed fixture ${identity.resource} returned HTTP ${response.status}: ${response.bodyText}`);
+        }
+        seeded.push({ type: fixture.type, id: identity.id });
+        await checkSeededManaged(io, session, fixture, identity.resource);
+    }
+}
+/** Delete one fixture the harness successfully created. A prior script delete is clean. */
+export async function deleteManagedFixture(io, session, fixture) {
+    const resource = managedResource(fixture.type, fixture.id);
+    const response = await amRequest(io, session, {
+        method: "DELETE",
+        path: resource,
+    });
+    if (response.status === 404 || (response.status >= 200 && response.status < 300)) {
+        return;
+    }
+    throw new AicLaneError(`delete managed fixture ${resource} returned HTTP ${response.status}: ${response.bodyText}`);
+}
+/**
+ * Serialize managed-fixture runs across worker processes for one tenant.
+ * A collision after this lock is acquired is therefore pre-existing state,
+ * not two files in this harness racing each other.
+ */
+export async function acquireManagedFixtureLock(session, label) {
+    const tenantKey = createHash("sha256")
+        .update(session.baseUrl)
+        .digest("hex")
+        .slice(0, 20);
+    const lockPath = join(tmpdir(), `rhino-local-managed-${tenantKey}.lock`);
+    const ownerPath = join(lockPath, "owner.json");
+    const deadline = Date.now() + 120_000;
+    for (;;) {
+        let acquired = false;
+        try {
+            await mkdir(lockPath, { mode: 0o700 });
+            acquired = true;
+        }
+        catch (error) {
+            if (!hasCode(error, "EEXIST")) {
+                throw error;
+            }
+        }
+        if (acquired) {
+            try {
+                await writeFile(ownerPath, JSON.stringify({ pid: process.pid, label }), { mode: 0o600 });
+            }
+            catch (error) {
+                await removeLock(lockPath, ownerPath);
+                throw error;
+            }
+            return async () => removeLock(lockPath, ownerPath);
+        }
+        const owner = await readOwner(ownerPath);
+        if (owner !== undefined && !processExists(owner.pid)) {
+            await removeLock(lockPath, ownerPath);
+            continue;
+        }
+        if (owner === undefined && (await lockIsStale(lockPath))) {
+            await removeLock(lockPath, ownerPath);
+            continue;
+        }
+        if (Date.now() >= deadline) {
+            throw new AicLaneError(`timed out waiting for managed-fixture tenant lock${owner === undefined ? "" : ` held by ${JSON.stringify(owner.label)}`}`);
+        }
+        await delay(100);
+    }
+}
+async function checkSeededManaged(io, session, fixture, resource) {
+    const response = await amRequest(io, session, { method: "GET", path: resource });
+    if (response.status < 200 || response.status >= 300 || !isPlainObject(response.body)) {
+        throw new AicLaneError(`managed fixture ${resource} was not readable after create (HTTP ${response.status})`);
+    }
+    for (const [key, expected] of Object.entries(fixture.record)) {
+        const present = Object.prototype.hasOwnProperty.call(response.body, key);
+        if (!present &&
+            READBACK_EXEMPT_FIELDS[fixture.type]?.includes(key) === true) {
+            continue;
+        }
+        if (!present || !deepEqual(response.body[key], expected)) {
+            throw new AicLaneError(`managed fixture ${resource} did not contain the declared field ${JSON.stringify(key)} after create`);
+        }
+    }
+}
+export function fixtureIdentity(fixture) {
+    const match = /^managed\/([^/]+)$/.exec(fixture.type);
+    if (match === null || match[1] === undefined) {
+        throw new AicLaneError(`managed fixture type ${JSON.stringify(fixture.type)} must be managed/<type>`);
+    }
+    const id = fixture.record._id;
+    if (typeof id !== "string" || id.length === 0) {
+        throw new AicLaneError(`managed fixture ${fixture.type} needs a non-empty string _id`);
+    }
+    if (fixture.type === "managed/alpha_user" && !UUID_PATTERN.test(id)) {
+        throw new AicLaneError(`managed/alpha_user fixture _id ${JSON.stringify(id)} must be a 36-character UUID because user _id is the fr-idm-uuid RDN; managed/alpha_role accepts readable ids instead`);
+    }
+    const collection = `/openidm/managed/${encodeURIComponent(match[1])}`;
+    return { collection, id, resource: `${collection}/${encodeURIComponent(id)}` };
+}
+export function managedResource(type, id) {
+    const match = /^managed\/([^/]+)$/.exec(type);
+    if (match === null || match[1] === undefined) {
+        throw new AicLaneError(`managed fixture type ${JSON.stringify(type)} must be managed/<type>`);
+    }
+    return `/openidm/managed/${encodeURIComponent(match[1])}/${encodeURIComponent(id)}`;
+}
+async function readOwner(path) {
+    try {
+        const value = JSON.parse(await readFile(path, "utf8"));
+        return typeof value.pid === "number" && typeof value.label === "string"
+            ? { pid: value.pid, label: value.label }
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return hasCode(error, "EPERM");
+    }
+}
+async function lockIsStale(path) {
+    try {
+        return Date.now() - (await stat(path)).mtimeMs > 5_000;
+    }
+    catch {
+        return false;
+    }
+}
+async function removeLock(lockPath, ownerPath) {
+    try {
+        await unlink(ownerPath);
+    }
+    catch (error) {
+        if (!hasCode(error, "ENOENT")) {
+            throw error;
+        }
+    }
+    try {
+        await rmdir(lockPath);
+    }
+    catch (error) {
+        if (!hasCode(error, "ENOENT")) {
+            throw error;
+        }
+    }
+}
+function hasCode(error, code) {
+    return (typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        error.code === code);
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,156 @@
+import { createPrivateKey, type JsonWebKey } from "node:crypto";
+import { type HttpRequest, type HttpResponse } from "./http.ts";
+/**
+ * Where the tenant lane gets its tenant and its bearer.
+ *
+ * This is the one seam between the harness and whatever holds the
+ * credentials. In this repo that is the `aic` agent ({@link aicCliProvider});
+ * outside it, a service account ({@link serviceAccountProvider}) or the
+ * caller's own token source ({@link tokenCallbackProvider}). Everything past
+ * this seam — journey upload, `/authenticate`, IDM seeding, teardown — is the
+ * same code whichever provider supplied the bearer.
+ */
+export interface TenantProvider {
+    /** Where the tenant is. Called once per connection, before any token. */
+    describe(): Promise<TenantDescription>;
+    /**
+     * A bearer for AM and IDM calls. Called with `reason: "initial"` when a
+     * connection opens, and again with `reason: "rejected"` after a
+     * non-anonymous call came back 401 — so a provider that caches must not
+     * hand back the token that was just refused.
+     */
+    getToken(request: TokenRequest): Promise<string>;
+    /** Present when this provider can read the tenant's logs (`show-log`). */
+    readonly logs?: LogReader;
+}
+export interface TenantDescription {
+    /** Recorded in failure dumps and traces; `show-log` matches on it. */
+    name: string;
+    /** `https://<tenant>` — no trailing slash, no path. */
+    baseUrl: string;
+}
+export interface TokenRequest {
+    reason: "initial" | "rejected";
+    /** The bearer the tenant refused, when `reason` is `"rejected"`. */
+    rejected?: string;
+}
+export interface LogReader {
+    /**
+     * Every event for one transaction id, polling until AM's trailing
+     * `AM-ACCESS-OUTCOME` event arrives or `waitMs` elapses — logs lag the
+     * request by tens of seconds. Whatever has arrived is returned on timeout.
+     */
+    transaction(id: string, options?: {
+        waitMs?: number;
+    }): Promise<unknown[]>;
+}
+/** Console-issued log API key pair (`docs/api/08-logs.md`). */
+export interface LogKeys {
+    id: string;
+    secret: string;
+}
+export type HttpSend = (req: HttpRequest) => Promise<HttpResponse>;
+export declare class TenantProviderError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+export interface TokenCallbackOptions {
+    baseUrl: string;
+    /** Default: the base URL's hostname. */
+    name?: string;
+    getToken: (request: TokenRequest) => Promise<string> | string;
+    logKeys?: LogKeys;
+    http?: HttpSend;
+}
+/**
+ * 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 declare function tokenCallbackProvider(options: TokenCallbackOptions): TenantProvider;
+/** `docs/api/00-auth.md`; a returned scope may be a re-ordered subset. */
+export declare const DEFAULT_SERVICE_ACCOUNT_SCOPE = "fr:am:* fr:idm:* fr:idc:esv:*";
+export interface ServiceAccountOptions {
+    baseUrl: string;
+    /** The service account's UUID — `iss` and `sub` of the assertion. */
+    serviceAccountId: string;
+    /** The RSA private key the console issued, as a JWK object or JSON text. */
+    jwk: JsonWebKey | string;
+    scope?: string;
+    name?: string;
+    logKeys?: LogKeys;
+    http?: HttpSend;
+    /** Seconds since the epoch; injected by tests. */
+    now?: () => number;
+}
+/**
+ * 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 declare function serviceAccountProvider(options: ServiceAccountOptions): TenantProvider;
+/** Compact JWS, RS256. Exported for tests that verify it with the public key. */
+export declare function signAssertion(key: ReturnType<typeof createPrivateKey>, claims: Record<string, unknown>): string;
+/** What `aic logs tx` reads by default (`src/logs/cli.rs`). */
+export declare const DEFAULT_LOG_SOURCES: readonly ["am-everything", "idm-everything"];
+export interface LogReaderOptions {
+    /** Injected by tests; default `setTimeout`. */
+    sleep?: (ms: number) => Promise<void>;
+    /** Milliseconds since the epoch; injected by tests. */
+    now?: () => number;
+}
+/**
+ * `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 declare function logKeysReader(baseUrl: string, keys: LogKeys, http: HttpSend, options?: LogReaderOptions): LogReader;
+/** The variables {@link providerFromEnv} reads. */
+export declare const TENANT_ENV: {
+    readonly url: "AIC_SCRIPT_TESTER_TENANT_URL";
+    readonly name: "AIC_SCRIPT_TESTER_TENANT_NAME";
+    readonly serviceAccountId: "AIC_SCRIPT_TESTER_SA_ID";
+    readonly jwk: "AIC_SCRIPT_TESTER_SA_JWK";
+    readonly jwkFile: "AIC_SCRIPT_TESTER_SA_JWK_FILE";
+    readonly scope: "AIC_SCRIPT_TESTER_SA_SCOPE";
+    readonly logKeyId: "AIC_SCRIPT_TESTER_LOG_KEY_ID";
+    readonly 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 declare function providerFromEnv(env?: NodeJS.ProcessEnv): TenantProvider | undefined;
+/**
+ * Set the provider every tenant-lane connection in this process uses, e.g.
+ * from a Vitest `setupFiles` module. Pass `undefined` to clear it.
+ */
+export declare function setTenantProvider(provider: TenantProvider | undefined): void;
+/** The registered provider, else one from the environment, else `undefined`. */
+export declare function configuredTenantProvider(env?: NodeJS.ProcessEnv): TenantProvider | undefined;
+/**
+ * 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 declare function checkTenantDescription(description: TenantDescription): TenantDescription;
+/**
+ * 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 declare function tokenErrorDetail(body: string, baseUrl: string): string;
+/** `text` with the tenant's origin and hostname replaced by `<tenant>`. */
+export declare function scrubTenant(text: string, baseUrl: string): string;