@camunda/e2e-test-suite 0.0.1241 → 0.0.1243

package/dist/tests/api/v2/user-task/user-task-api-tests.spec.js

@@ -0,0 +1,258 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const api_1 = require("../../../../fixtures/api");
+const test_1 = require("@playwright/test");
+const assertions_1 = require("../../../../utils/api/assertions");
+const deployments_1 = require("../../../../utils/api/deployments");
+const bpmn_1 = require("../../../../utils/api/bpmn");
+const eventually_1 = require("../../../../utils/api/eventually");
+const capabilities_1 = require("../../../../utils/api/capabilities");
+const keys_1 = require("../../../../utils/api/keys");
+/** Starts a process holding one Zeebe user task and returns that task's key. */
+async function startUserTask(api, resources) {
+    const processId = (0, bpmn_1.uniqueId)('user-task-api');
+    await (0, deployments_1.deployProcess)(api, resources, processId, (0, bpmn_1.linearProcess)(processId, bpmn_1.element.userTask()));
+    const start = await api.post('/process-instances', {
+        body: { processDefinitionId: processId },
+        tenant: 'root',
+    });
+    await (0, assertions_1.assertStatusIn)(start, [200], 'instance creation is synchronous');
+    const instance = (await start.json());
+    const processInstanceKey = String(instance.processInstanceKey);
+    let tasks;
+    try {
+        tasks = await (0, eventually_1.eventuallyGet)(async () => {
+            const response = await api.post('/user-tasks/search', {
+                body: { filter: { processInstanceKey }, page: { limit: 10 } },
+            });
+            const page = await (0, assertions_1.assertPaginated)(response);
+            return page.items;
+        }, (items) => items.length > 0, { description: `user tasks for instance ${processInstanceKey}` });
+    }
+    catch (error) {
+        // An empty result cannot say *why* it is empty, and that is the whole
+        // question when this fails: did the engine never create the task (our
+        // model is wrong), or did it create one that was never exported (the
+        // cluster is wrong)? The element instances answer it — they come from a
+        // different index, so a `task` element sitting in the instance while the
+        // user-task search stays empty means the record exists and only its
+        // export is missing.
+        throw new Error(`${error instanceof Error ? error.message : String(error)}\n` +
+            (await describeInstance(api, processInstanceKey, processId)));
+    }
+    return { userTaskKey: String(tasks[0].userTaskKey), processInstanceKey };
+}
+/** Where the instance actually got to, for the failure message above. */
+async function describeInstance(api, processInstanceKey, processId) {
+    try {
+        const instances = await api.post('/process-instances/search', {
+            body: { filter: { processInstanceKey } },
+        });
+        const elements = await api.post('/element-instances/search', {
+            body: { filter: { processInstanceKey }, page: { limit: 20 } },
+        });
+        // The definition was deployed moments before the instance started, so it
+        // is the control: both travel the same exporter to the same secondary
+        // storage. A definition that arrived while its instance did not is a
+        // fault specific to this instance; neither arriving means export was
+        // behind or stopped for everything, which is a cluster fault rather than
+        // anything these tests can assert around. Run 35696766504 failed 12 tests
+        // without recording which of the two it was.
+        const definitions = await api.post('/process-definitions/search', {
+            body: { filter: { processDefinitionId: processId }, page: { limit: 1 } },
+        });
+        const instanceJson = (await instances.json());
+        const elementJson = (await elements.json());
+        const definitionJson = (await definitions.json());
+        const state = instanceJson.items?.[0]?.state ?? '<no instance found>';
+        const active = (elementJson.items ?? []).map((item) => `${item.elementId}:${item.type}=${item.state}`);
+        const exported = (definitionJson.items ?? []).length > 0;
+        return (`Instance ${processInstanceKey} state=${state}; ` +
+            `element instances: ${active.length > 0 ? active.join(', ') : '<none>'}; ` +
+            `its definition ${processId} ` +
+            `${exported
+                ? 'DID reach secondary storage (export is live, so this instance is the fault)'
+                : 'did NOT reach secondary storage either (export is behind or stopped cluster-wide)'}`);
+    }
+    catch (error) {
+        return `Could not describe instance ${processInstanceKey}: ${error instanceof Error ? error.message : String(error)}`;
+    }
+}
+api_1.test.describe('User tasks', () => {
+    (0, api_1.test)('finds the task created by a running instance', async ({ api, resources, }) => {
+        const { userTaskKey, processInstanceKey } = await startUserTask(api, resources);
+        resources.track('processInstance', processInstanceKey);
+        const response = await api.post('/user-tasks/search', {
+            body: { filter: { processInstanceKey } },
+        });
+        const page = await (0, assertions_1.assertPaginated)(response, { exactItems: 1 });
+        const task = page.items[0];
+        (0, test_1.expect)(String(task.userTaskKey)).toBe(userTaskKey);
+        (0, test_1.expect)(task.state).toBe('CREATED');
+    });
+    (0, api_1.test)('returns a task by key', async ({ api, resources }) => {
+        const { userTaskKey, processInstanceKey } = await startUserTask(api, resources);
+        resources.track('processInstance', processInstanceKey);
+        const response = await api.get('/user-tasks/{userTaskKey}', {
+            params: { userTaskKey },
+        });
+        const task = (await (0, assertions_1.assertOk)(response));
+        (0, assertions_1.assertRequiredFields)(task, ['userTaskKey', 'state', 'elementId']);
+        (0, test_1.expect)(task.elementId).toBe('task');
+        (0, test_1.expect)(task.state).toBe('CREATED');
+    });
+    (0, api_1.test)('assigns a task to a user', async ({ api, resources }) => {
+        const { userTaskKey, processInstanceKey } = await startUserTask(api, resources);
+        resources.track('processInstance', processInstanceKey);
+        const response = await api.post('/user-tasks/{userTaskKey}/assignment', {
+            params: { userTaskKey },
+            body: { assignee: 'demo', allowOverride: true },
+            tenant: 'none',
+        });
+        await (0, assertions_1.assertStatusIn)(response, [204], 'assignment is acknowledged');
+        await (0, eventually_1.eventually)(async () => {
+            const lookup = await api.get('/user-tasks/{userTaskKey}', {
+                params: { userTaskKey },
+            });
+            const task = (await (0, assertions_1.assertOk)(lookup));
+            // The shell suite asserted the 204 and moved on, so an assignment that
+            // was accepted but never applied counted as a pass.
+            (0, test_1.expect)(task.assignee).toBe('demo');
+        });
+    });
+    (0, api_1.test)('unassigns an assigned task', async ({ api, resources }) => {
+        const { userTaskKey, processInstanceKey } = await startUserTask(api, resources);
+        resources.track('processInstance', processInstanceKey);
+        await api.post('/user-tasks/{userTaskKey}/assignment', {
+            params: { userTaskKey },
+            body: { assignee: 'demo', allowOverride: true },
+            tenant: 'none',
+        });
+        const response = await api.delete('/user-tasks/{userTaskKey}/assignee', {
+            params: { userTaskKey },
+            tenant: 'none',
+        });
+        await (0, assertions_1.assertStatusIn)(response, [204], 'unassignment is acknowledged');
+        await (0, eventually_1.eventually)(async () => {
+            const lookup = await api.get('/user-tasks/{userTaskKey}', {
+                params: { userTaskKey },
+            });
+            const task = (await (0, assertions_1.assertOk)(lookup));
+            (0, test_1.expect)(task.assignee ?? null).toBeNull();
+        });
+    });
+    (0, api_1.test)('updates a task through a patch', async ({ api, resources }) => {
+        const { userTaskKey, processInstanceKey } = await startUserTask(api, resources);
+        resources.track('processInstance', processInstanceKey);
+        const response = await api.patch('/user-tasks/{userTaskKey}', {
+            params: { userTaskKey },
+            body: { changeset: { priority: 75 } },
+            tenant: 'none',
+        });
+        await (0, assertions_1.assertStatusIn)(response, [204], 'the patch is acknowledged');
+        await (0, eventually_1.eventually)(async () => {
+            const lookup = await api.get('/user-tasks/{userTaskKey}', {
+                params: { userTaskKey },
+            });
+            const task = (await (0, assertions_1.assertOk)(lookup));
+            (0, test_1.expect)(task.priority).toBe(75);
+        });
+    });
+    (0, api_1.test)('completes a task and finishes the instance', async ({ api, resources, }) => {
+        const { userTaskKey, processInstanceKey } = await startUserTask(api, resources);
+        const response = await api.post('/user-tasks/{userTaskKey}/completion', {
+            params: { userTaskKey },
+            body: { variables: { approved: true } },
+            tenant: 'none',
+        });
+        await (0, assertions_1.assertStatusIn)(response, [204], 'completion is acknowledged');
+        await (0, eventually_1.eventually)(async () => {
+            const search = await api.post('/process-instances/search', {
+                body: { filter: { processInstanceKey } },
+            });
+            const page = await (0, assertions_1.assertPaginated)(search, { exactItems: 1 });
+            (0, test_1.expect)(page.items[0].state).toBe('COMPLETED');
+        });
+    });
+    (0, api_1.test)('searches the variables visible to a task', async ({ api, resources }) => {
+        const { userTaskKey, processInstanceKey } = await startUserTask(api, resources);
+        resources.track('processInstance', processInstanceKey);
+        const response = await api.post('/user-tasks/{userTaskKey}/variables/search', { params: { userTaskKey }, body: { filter: {} } });
+        await (0, assertions_1.assertPaginated)(response);
+    });
+    (0, api_1.test)('reports no linked form for a task without one', async ({ api, resources, }) => {
+        const { userTaskKey, processInstanceKey } = await startUserTask(api, resources);
+        resources.track('processInstance', processInstanceKey);
+        const response = await api.get('/user-tasks/{userTaskKey}/form', {
+            params: { userTaskKey },
+        });
+        await (0, assertions_1.assertStatusIn)(response, [204, 404], 'a task with no linked form reports 204 on 8.8+ and 404 on earlier minors');
+    });
+    (0, api_1.test)('rejects assigning a completed task', async ({ api, resources }) => {
+        const { userTaskKey } = await startUserTask(api, resources);
+        await api.post('/user-tasks/{userTaskKey}/completion', {
+            params: { userTaskKey },
+            body: { variables: {} },
+            tenant: 'none',
+        });
+        await (0, eventually_1.eventually)(async () => {
+            const response = await api.post('/user-tasks/{userTaskKey}/assignment', {
+                params: { userTaskKey },
+                body: { assignee: 'demo', allowOverride: true },
+                tenant: 'none',
+            });
+            await (0, assertions_1.assertStatusIn)(response, [404, 409], 'a completed task is either gone or in an invalid state, depending on minor version');
+        });
+    });
+    (0, api_1.test)('rejects a lookup for an absent task key', async ({ api }) => {
+        const response = await api.get('/user-tasks/{userTaskKey}', {
+            params: { userTaskKey: keys_1.ABSENT_KEY },
+        });
+        await (0, assertions_1.assertNotFound)(response);
+    });
+    (0, api_1.test)('rejects completing an absent task', async ({ api }) => {
+        const response = await api.post('/user-tasks/{userTaskKey}/completion', {
+            params: { userTaskKey: keys_1.ABSENT_ROUTABLE_KEY },
+            body: { variables: {} },
+            tenant: 'none',
+        });
+        await (0, assertions_1.assertNotFound)(response);
+    });
+    (0, api_1.test)('rejects a patch carrying no changeset', async ({ api, resources }) => {
+        const { userTaskKey, processInstanceKey } = await startUserTask(api, resources);
+        resources.track('processInstance', processInstanceKey);
+        const response = await api.patch('/user-tasks/{userTaskKey}', {
+            params: { userTaskKey },
+            body: {},
+            tenant: 'none',
+        });
+        await (0, assertions_1.assertBadRequest)(response);
+    });
+    (0, api_1.test)('rejects an unauthenticated task search', async ({ api }) => {
+        api_1.test.skip(capabilities_1.unauthenticatedAccessAllowed !== false, capabilities_1.unauthenticatedAccessAllowed === false
+            ? ''
+            : capabilities_1.unauthenticatedAccessAllowed);
+        const response = await api.post('/user-tasks/search', {
+            body: { filter: {} },
+            authorization: null,
+        });
+        await (0, assertions_1.assertUnauthorized)(response);
+    });
+    (0, api_1.test)('rejects assigning a task that is already assigned without override', async ({ api, resources, }) => {
+        const { userTaskKey, processInstanceKey } = await startUserTask(api, resources);
+        resources.track('processInstance', processInstanceKey);
+        await api.post('/user-tasks/{userTaskKey}/assignment', {
+            params: { userTaskKey },
+            body: { assignee: 'demo', allowOverride: true },
+            tenant: 'none',
+        });
+        await (0, eventually_1.eventually)(async () => {
+            const response = await api.post('/user-tasks/{userTaskKey}/assignment', {
+                params: { userTaskKey },
+                body: { assignee: 'someone-else', allowOverride: false },
+                tenant: 'none',
+            });
+            await (0, assertions_1.assertConflict)(response);
+        });
+    });
+});

package/dist/utils/api/assertions.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Assertion vocabulary for REST v2 responses.
+ *
+ * Each helper asserts the status *and* the problem body the API documents for
+ * it, so a response that is right by accident fails. The legacy shell suite
+ * asserted status codes only, and accepted lists such as `200 201 403` that
+ * passed whether the call succeeded or was rejected outright.
+ *
+ * Where a status genuinely varies — across versions, or because an operation is
+ * synchronous on one path and accepted-for-later on another — use
+ * `assertStatusIn`, which requires the reason in writing at the call site.
+ */
+import { type APIResponse } from '@playwright/test';
+/** Fields every paginated search response carries. */
+export declare const PAGINATED_FIELDS: readonly ["items", "page"];
+export declare function assertStatus(response: APIResponse, expected: number): Promise<void>;
+/**
+ * Accepts any of `expected`. `reason` documents why the endpoint may answer
+ * with more than one status and is printed on failure — it is required so that
+ * widening an assertion is a deliberate, reviewable act.
+ */
+export declare function assertStatusIn(response: APIResponse, expected: readonly number[], reason: string): Promise<void>;
+export declare function assertRequiredFields(payload: unknown, required: readonly string[]): void;
+export declare function assertEqualsForKeys(payload: unknown, expected: Record<string, unknown>, keys: readonly string[]): void;
+export declare function assertOk(response: APIResponse): Promise<unknown>;
+export declare function assertCreated(response: APIResponse): Promise<unknown>;
+export declare function assertNoContent(response: APIResponse): Promise<void>;
+export declare function assertUnauthorized(response: APIResponse): Promise<void>;
+/**
+ * A 403 does not carry one fixed problem title. The authorization layer sends
+ * `FORBIDDEN`, while the filter that closes `/v2/users/**` on an OIDC cluster
+ * sends `Access issue` — both are the API refusing the call. The status and
+ * the detail carry the meaning, so the title is matched loosely and the
+ * caller pins the specific refusal through `detail`.
+ */
+export declare function assertForbidden(response: APIResponse, detail?: string | RegExp): Promise<void>;
+export declare function assertNotFound(response: APIResponse, detail?: string | RegExp): Promise<void>;
+export declare function assertConflict(response: APIResponse, detail?: string | RegExp): Promise<void>;
+export declare function assertBadRequest(response: APIResponse, detail?: string | RegExp, title?: string | RegExp): Promise<void>;
+export declare function assertPaginated(response: APIResponse, options?: {
+    minItems?: number;
+    exactItems?: number;
+    minTotalItems?: number;
+    exactTotalItems?: number;
+}): Promise<{
+    items: unknown[];
+    page: {
+        totalItems: number;
+    };
+}>;

package/dist/utils/api/assertions.js

@@ -0,0 +1,142 @@
+"use strict";
+/**
+ * Assertion vocabulary for REST v2 responses.
+ *
+ * Each helper asserts the status *and* the problem body the API documents for
+ * it, so a response that is right by accident fails. The legacy shell suite
+ * asserted status codes only, and accepted lists such as `200 201 403` that
+ * passed whether the call succeeded or was rejected outright.
+ *
+ * Where a status genuinely varies — across versions, or because an operation is
+ * synchronous on one path and accepted-for-later on another — use
+ * `assertStatusIn`, which requires the reason in writing at the call site.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.assertPaginated = exports.assertBadRequest = exports.assertConflict = exports.assertNotFound = exports.assertForbidden = exports.assertUnauthorized = exports.assertNoContent = exports.assertCreated = exports.assertOk = exports.assertEqualsForKeys = exports.assertRequiredFields = exports.assertStatusIn = exports.assertStatus = exports.PAGINATED_FIELDS = void 0;
+const test_1 = require("@playwright/test");
+/** Fields every RFC 7807 problem body from the API carries. */
+const PROBLEM_FIELDS = ['title', 'detail'];
+/** Fields every paginated search response carries. */
+exports.PAGINATED_FIELDS = ['items', 'page'];
+async function describe(response) {
+    const body = await response.text().catch(() => '<unreadable body>');
+    return `${response.url()} -> ${response.status()}\n${body}`;
+}
+async function assertStatus(response, expected) {
+    if (response.status() !== expected) {
+        throw new Error(`Expected status ${expected}, got ${response.status()}.\n${await describe(response)}`);
+    }
+}
+exports.assertStatus = assertStatus;
+/**
+ * Accepts any of `expected`. `reason` documents why the endpoint may answer
+ * with more than one status and is printed on failure — it is required so that
+ * widening an assertion is a deliberate, reviewable act.
+ */
+async function assertStatusIn(response, expected, reason) {
+    if (!expected.includes(response.status())) {
+        throw new Error(`Expected one of [${expected.join(', ')}] (${reason}), got ${response.status()}.\n${await describe(response)}`);
+    }
+}
+exports.assertStatusIn = assertStatusIn;
+function assertRequiredFields(payload, required) {
+    (0, test_1.expect)(payload, 'response body should be an object').toBeTruthy();
+    const record = payload;
+    const missing = required.filter((field) => !Object.prototype.hasOwnProperty.call(record, field) ||
+        record[field] === undefined);
+    if (missing.length > 0) {
+        throw new Error(`Response is missing required field(s): ${missing.join(', ')}\n` +
+            `Body: ${JSON.stringify(payload, null, 2)}`);
+    }
+}
+exports.assertRequiredFields = assertRequiredFields;
+function assertEqualsForKeys(payload, expected, keys) {
+    const record = payload;
+    for (const key of keys) {
+        (0, test_1.expect)(record?.[key], `field "${key}"`).toEqual(expected[key]);
+    }
+}
+exports.assertEqualsForKeys = assertEqualsForKeys;
+async function assertProblem(response, status, title, detail) {
+    await assertStatus(response, status);
+    const json = await response.json();
+    assertRequiredFields(json, PROBLEM_FIELDS);
+    if (typeof title === 'string') {
+        (0, test_1.expect)(json.title, `problem title for ${response.url()}`).toBe(title);
+    }
+    else {
+        (0, test_1.expect)(String(json.title)).toMatch(title);
+    }
+    if (detail !== undefined) {
+        (0, test_1.expect)(String(json.detail)).toMatch(typeof detail === 'string'
+            ? new RegExp(detail.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'), 'i')
+            : detail);
+    }
+}
+async function assertOk(response) {
+    await assertStatus(response, 200);
+    return response.json();
+}
+exports.assertOk = assertOk;
+async function assertCreated(response) {
+    await assertStatus(response, 201);
+    return response.json();
+}
+exports.assertCreated = assertCreated;
+async function assertNoContent(response) {
+    await assertStatus(response, 204);
+}
+exports.assertNoContent = assertNoContent;
+async function assertUnauthorized(response) {
+    await assertStatus(response, 401);
+    const json = await response.json().catch(() => undefined);
+    // 401 may be produced by the ingress or the security filter chain before the
+    // API's problem-body writer runs, so only assert the body when there is one.
+    if (json) {
+        (0, test_1.expect)(String(json.title)).toMatch(/unauthorized/i);
+    }
+}
+exports.assertUnauthorized = assertUnauthorized;
+/**
+ * A 403 does not carry one fixed problem title. The authorization layer sends
+ * `FORBIDDEN`, while the filter that closes `/v2/users/**` on an OIDC cluster
+ * sends `Access issue` — both are the API refusing the call. The status and
+ * the detail carry the meaning, so the title is matched loosely and the
+ * caller pins the specific refusal through `detail`.
+ */
+async function assertForbidden(response, detail) {
+    await assertProblem(response, 403, /forbidden|access issue/i, detail);
+}
+exports.assertForbidden = assertForbidden;
+async function assertNotFound(response, detail) {
+    await assertProblem(response, 404, /not[_ ]?found/i, detail);
+}
+exports.assertNotFound = assertNotFound;
+async function assertConflict(response, detail) {
+    await assertProblem(response, 409, /already[_ ]exists|invalid[_ ]state/i, detail);
+}
+exports.assertConflict = assertConflict;
+async function assertBadRequest(response, detail, title = /invalid[_ ]argument|bad request/i) {
+    await assertProblem(response, 400, title, detail);
+}
+exports.assertBadRequest = assertBadRequest;
+async function assertPaginated(response, options = {}) {
+    await assertStatus(response, 200);
+    const json = await response.json();
+    assertRequiredFields(json, exports.PAGINATED_FIELDS);
+    (0, test_1.expect)(Array.isArray(json.items), 'items should be an array').toBe(true);
+    if (options.minItems !== undefined) {
+        (0, test_1.expect)(json.items.length).toBeGreaterThanOrEqual(options.minItems);
+    }
+    if (options.exactItems !== undefined) {
+        (0, test_1.expect)(json.items.length).toBe(options.exactItems);
+    }
+    if (options.minTotalItems !== undefined) {
+        (0, test_1.expect)(json.page.totalItems).toBeGreaterThanOrEqual(options.minTotalItems);
+    }
+    if (options.exactTotalItems !== undefined) {
+        (0, test_1.expect)(json.page.totalItems).toBe(options.exactTotalItems);
+    }
+    return json;
+}
+exports.assertPaginated = assertPaginated;

package/dist/utils/api/auth.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Authentication strategies for the Orchestration Cluster REST v2 API.
+ *
+ * The orchestration-cluster suite in `camunda/camunda` hardcodes Basic auth, so
+ * it cannot drive an OIDC-secured cluster. Helm-upgrade runs are OIDC, which is
+ * why this layer exists: it resolves an `Authorization` header from whichever
+ * strategy the environment selects, and refreshes bearer tokens before they
+ * expire so a long suite does not start 401-ing part way through.
+ */
+import type { APIRequestContext } from '@playwright/test';
+import { type ApiConfig } from './config';
+/**
+ * The `Authorization` header for the suite's principal, refreshed when stale.
+ * Throws rather than returning an unauthenticated header, so a broken token
+ * endpoint surfaces as a setup error instead of 300 misleading 401 assertions.
+ */
+export declare function authHeader(request: APIRequestContext, config?: ApiConfig): Promise<string>;
+/**
+ * A bearer header for a different OAuth2 client, used by the authorization
+ * enforcement tests to act as an under-privileged principal. Returns undefined
+ * when the client cannot authenticate, which those tests assert on directly.
+ */
+export declare function clientAuthHeader(request: APIRequestContext, clientId: string, clientSecret: string, config?: ApiConfig): Promise<string | undefined>;
+/** A bearer header obtained via the password grant, for per-user assertions. */
+export declare function userAuthHeader(request: APIRequestContext, username: string, password: string, config?: ApiConfig): Promise<string | undefined>;
+/** Drops cached tokens. Used by tests that deliberately invalidate a principal. */
+export declare function clearTokenCache(): void;

package/dist/utils/api/auth.js

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * Authentication strategies for the Orchestration Cluster REST v2 API.
+ *
+ * The orchestration-cluster suite in `camunda/camunda` hardcodes Basic auth, so
+ * it cannot drive an OIDC-secured cluster. Helm-upgrade runs are OIDC, which is
+ * why this layer exists: it resolves an `Authorization` header from whichever
+ * strategy the environment selects, and refreshes bearer tokens before they
+ * expire so a long suite does not start 401-ing part way through.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clearTokenCache = exports.userAuthHeader = exports.clientAuthHeader = exports.authHeader = void 0;
+const config_1 = require("./config");
+/**
+ * Re-fetch this long before the server-stated expiry. A request issued at the
+ * very edge of a token's lifetime can still arrive expired, and the suite runs
+ * long enough for that to be a routine occurrence rather than a rare race.
+ */
+const EXPIRY_MARGIN_MS = 60000;
+/** Fallback lifetime when the token endpoint omits `expires_in`. */
+const DEFAULT_TOKEN_TTL_MS = 300000;
+const tokenCache = new Map();
+function cacheKey(clientId, subject = '') {
+    return `${clientId}::${subject}`;
+}
+function basicHeader(username, password) {
+    return `Basic ${Buffer.from(`${username}:${password}`).toString('base64')}`;
+}
+async function fetchToken(request, tokenUrl, form) {
+    let response;
+    try {
+        response = await request.post(tokenUrl, {
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            form,
+        });
+    }
+    catch (error) {
+        // An unreachable token endpoint is the single most likely reason a whole
+        // run fails: on a Helm cluster the identity provider may not be serving
+        // yet. Reported raw, it surfaces as a Playwright stack inside auth.ts on
+        // every one of the suite's tests, which says nothing about the cause.
+        console.error(`Token endpoint ${tokenUrl} is unreachable: ${error instanceof Error ? error.message : String(error)}`);
+        return undefined;
+    }
+    if (!response.ok()) {
+        const body = await response.text().catch(() => '<no-body>');
+        console.error(`Token request to ${tokenUrl} failed with ${response.status()}: ${body}`);
+        return undefined;
+    }
+    const json = (await response.json());
+    if (!json.access_token) {
+        console.error(`Token response from ${tokenUrl} carried no access_token`);
+        return undefined;
+    }
+    const ttl = json.expires_in ? json.expires_in * 1000 : DEFAULT_TOKEN_TTL_MS;
+    return {
+        header: `Bearer ${json.access_token}`,
+        expiresAt: Date.now() + Math.max(ttl - EXPIRY_MARGIN_MS, 0),
+    };
+}
+function clientCredentialsForm(oauth, clientId, clientSecret) {
+    const form = {
+        grant_type: 'client_credentials',
+        client_id: clientId,
+        client_secret: clientSecret,
+    };
+    if (oauth.audience)
+        form.audience = oauth.audience;
+    if (oauth.scope)
+        form.scope = oauth.scope;
+    return form;
+}
+/**
+ * The `Authorization` header for the suite's principal, refreshed when stale.
+ * Throws rather than returning an unauthenticated header, so a broken token
+ * endpoint surfaces as a setup error instead of 300 misleading 401 assertions.
+ */
+async function authHeader(request, config = config_1.apiConfig) {
+    if (config.authMethod === 'basic') {
+        return basicHeader(config.basic.username, config.basic.password);
+    }
+    const key = cacheKey(config.oauth.clientId);
+    const cached = tokenCache.get(key);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.header;
+    }
+    const token = await fetchToken(request, config.oauth.tokenUrl, clientCredentialsForm(config.oauth, config.oauth.clientId, config.oauth.clientSecret));
+    if (!token) {
+        throw new Error(`Could not obtain an OAuth2 token for client "${config.oauth.clientId}" from ${config.oauth.tokenUrl}`);
+    }
+    tokenCache.set(key, token);
+    return token.header;
+}
+exports.authHeader = authHeader;
+/**
+ * A bearer header for a different OAuth2 client, used by the authorization
+ * enforcement tests to act as an under-privileged principal. Returns undefined
+ * when the client cannot authenticate, which those tests assert on directly.
+ */
+async function clientAuthHeader(request, clientId, clientSecret, config = config_1.apiConfig) {
+    const key = cacheKey(clientId);
+    const cached = tokenCache.get(key);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.header;
+    }
+    const token = await fetchToken(request, config.oauth.tokenUrl, clientCredentialsForm(config.oauth, clientId, clientSecret));
+    if (!token)
+        return undefined;
+    tokenCache.set(key, token);
+    return token.header;
+}
+exports.clientAuthHeader = clientAuthHeader;
+/** A bearer header obtained via the password grant, for per-user assertions. */
+async function userAuthHeader(request, username, password, config = config_1.apiConfig) {
+    const key = cacheKey(config.oauth.clientId, username);
+    const cached = tokenCache.get(key);
+    if (cached && cached.expiresAt > Date.now()) {
+        return cached.header;
+    }
+    const token = await fetchToken(request, config.oauth.tokenUrl, {
+        grant_type: 'password',
+        client_id: config.oauth.clientId,
+        client_secret: config.oauth.clientSecret,
+        username,
+        password,
+    });
+    if (!token)
+        return undefined;
+    tokenCache.set(key, token);
+    return token.header;
+}
+exports.userAuthHeader = userAuthHeader;
+/** Drops cached tokens. Used by tests that deliberately invalidate a principal. */
+function clearTokenCache() {
+    tokenCache.clear();
+}
+exports.clearTokenCache = clearTokenCache;

package/dist/utils/api/beans.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Request bodies for identity resources.
+ *
+ * Every factory randomises its identifier. The shell suite seeded ids from
+ * `$(date +%s)-$$`, which collides between workers started in the same second
+ * and left tests fighting over the same role or group.
+ */
+export declare const roleRequiredFields: readonly ["roleId", "name", "description"];
+export declare const groupRequiredFields: readonly ["groupId", "name"];
+export declare const tenantRequiredFields: readonly ["tenantId", "name"];
+export declare const userRequiredFields: readonly ["username", "name", "email"];
+export declare const mappingRuleRequiredFields: readonly ["mappingRuleId", "claimName", "claimValue", "name"];
+export declare function newRole(overrides?: Record<string, unknown>): {
+    roleId: string;
+    name: string;
+    description: string;
+};
+export declare function newGroup(overrides?: Record<string, unknown>): {
+    groupId: string;
+    name: string;
+    description: string;
+};
+export declare function newTenant(overrides?: Record<string, unknown>): {
+    tenantId: string;
+    name: string;
+    description: string;
+};
+export declare function newUser(overrides?: Record<string, unknown>): {
+    username: string;
+    name: string;
+    email: string;
+    password: string;
+};
+export declare function newMappingRule(overrides?: Record<string, unknown>): {
+    mappingRuleId: string;
+    claimName: string;
+    claimValue: string;
+    name: string;
+};
+export declare function newAuthorization(overrides?: Record<string, unknown>): {
+    ownerId: string;
+    ownerType: string;
+    resourceId: string;
+    resourceType: string;
+    permissionTypes: string[];
+};