@ionite/ecv 0.0.23-beta.20260729.1

package/dist/index.d.ts

@@ -0,0 +1,1035 @@
+import { ChildProcess } from "node:child_process";
+/**
+* Options controlling how readiness is polled.
+*/
+interface WaitForReadyOptions {
+	/**
+	* Readiness path appended to the base URL. When omitted it is derived from {@link basePath}.
+	* @default "`${basePath}/readyz`" (i.e. `/api/ionite/readyz`)
+	*/
+	readyPath?: string;
+	/**
+	* Base path the ionite app mounts the SDK handler under, used to derive {@link readyPath} when it is
+	* not given (ionite apps expose `${basePath}/readyz`). Ignored when `readyPath` is set explicitly.
+	* @default "/api/ionite"
+	*/
+	basePath?: string;
+	/**
+	* Optional liveness path checked before readiness (e.g. "/api/livez").
+	* When set, an attempt only succeeds if liveness is OK and readiness is OK.
+	*/
+	livenessPath?: string;
+	/**
+	* Maximum number of polling attempts.
+	* @default 30
+	*/
+	maxRetries?: number;
+	/**
+	* Delay between attempts in milliseconds.
+	* @default 1000
+	*/
+	retryDelayMs?: number;
+	/**
+	* Per-request abort timeout in milliseconds.
+	* @default 3000
+	*/
+	requestTimeoutMs?: number;
+}
+/**
+* Poll an application until its readiness endpoint responds OK.
+*/
+declare function waitForReady(baseUrl: string, options?: WaitForReadyOptions): Promise<void>;
+/**
+* Options for {@link startAppUnderTest}.
+*/
+interface StartAppOptions extends WaitForReadyOptions {
+	/** Executable to run (e.g. "bun"). */
+	command: string;
+	/** Arguments passed to the command (e.g. ["run", "api"]). */
+	args?: string[];
+	/** Working directory for the spawned process. */
+	cwd?: string;
+	/**
+	* Environment variables merged on top of `process.env`.
+	* Pass `ecv.env` here so the app connects to the ECV mock server.
+	*/
+	env?: Record<string, string | undefined>;
+	/** Public base URL the app will be reachable at (used for readiness polling and returned to callers). */
+	baseUrl: string;
+}
+/**
+* Handle for a spawned application under test.
+*/
+interface AppUnderTest {
+	/** Base URL the app is reachable at. */
+	baseUrl: string;
+	/** The spawned child process. */
+	process: ChildProcess;
+	/** Stop the app (SIGTERM, then SIGKILL fallback if it is still running). */
+	stop(): Promise<void>;
+}
+/**
+* Spawn an application under test, wait for it to become ready, and return a handle with a `stop()`.
+*
+* @example
+* ```ts
+* const ecv = await startEcvServer();
+* const app = await startAppUnderTest({
+*   command: 'bun',
+*   args: ['run', 'api'],
+*   env: { ...ecv.env, APP_BASE_URL: 'http://localhost:3544' },
+*   baseUrl: 'http://localhost:3544',
+*   // readyPath defaults to `${basePath}/readyz` (i.e. /api/ionite/readyz); override basePath if needed.
+* });
+* // ...run tests against app.baseUrl...
+* await app.stop();
+* ```
+*/
+declare function startAppUnderTest(options: StartAppOptions): Promise<AppUnderTest>;
+import { EnterpriseExtension, Ionite } from "@ionite/server";
+declare function setVaultRedisUrl(url: string | undefined): void;
+declare function getVaultRedisUrl(): string | undefined;
+interface EcvServerHandle {
+	baseUrl: string;
+	port: number;
+	host: string;
+	env: {
+		ION_CONFIG_TYPE: "vault";
+		ION_VAULT_URL: string;
+		ION_VAULT_TOKEN: string;
+		ION_VAULT_PATH: string;
+		REDIS_URL?: string;
+	};
+	/**
+	* Narrow tenant config-locator pointer for seeding tenant rows / tenant-create requests. The root
+	* vault connection comes from `env` (ION_VAULT_*); a tenant only stores its config `path`.
+	*/
+	configLocator: {
+		path: string;
+	};
+}
+/**
+* Server configuration options
+*/
+interface ServerOptions {
+	/**
+	* Port to listen on
+	* @default 3515
+	*/
+	port?: number;
+	/**
+	* Host to bind to
+	* @default 'localhost'
+	*/
+	host?: string;
+	/**
+	* Enable verbose logging
+	* @default false
+	*/
+	verbose?: boolean;
+	/**
+	* Redis URL for vault secrets at `{ION_VAULT_PATH}/redis` (consumed by ionRedis).
+	* Falls back to `REDIS_URL` when omitted.
+	*/
+	redisUrl?: string;
+}
+/**
+* Start the ECV mock server
+*
+* @param options - Server configuration options
+* @returns Promise that resolves with the server connection config when the server is listening
+*/
+declare function startEcvServer(options?: ServerOptions): Promise<EcvServerHandle>;
+/**
+* Stop the ECV mock server
+*
+* @returns Promise that resolves when the server has stopped
+*/
+declare function stopEcvServer(): Promise<void>;
+/**
+* ionite Validator Types
+*
+* These types define the configuration and result structures for
+* ionite validation tests.
+*/
+/**
+* Test definition for Vitest-compatible test suites
+*/
+interface TestDef {
+	name: string;
+	fn: () => Promise<void>;
+}
+/**
+* Base configuration for all validation suites
+*/
+interface ValidationConfig {
+	/**
+	* Base URL of the application under test.
+	* May be a getter so Vitest suites can resolve the URL after `beforeAll`.
+	* @example "http://localhost:3000"
+	*/
+	baseUrl: string | (() => string);
+	/**
+	* Optional timeout for requests in milliseconds
+	* @default 5000
+	*/
+	timeout?: number;
+	/**
+	* Whether to skip TLS certificate verification (for local testing)
+	* @default false
+	*/
+	skipTlsVerify?: boolean;
+	/**
+	* Optional custom headers to include in all requests.
+	* May be a function (or async function) so that headers are resolved when the request runs
+	* (e.g. for workload auth token that is obtained in beforeAll).
+	*/
+	headers?: Record<string, string> | (() => Record<string, string> | Promise<Record<string, string>>);
+}
+/**
+* SSO Validation Configuration
+*/
+interface SSOValidationConfig extends ValidationConfig {
+	/**
+	* Path to the login endpoint
+	* @default "/api/auth/login"
+	*/
+	loginPath?: string;
+	/**
+	* Path to the callback endpoint (where the IdP redirects after auth)
+	* @default "/api/auth/callback"
+	*/
+	callbackPath?: string;
+	/**
+	* Path to the user info endpoint
+	* @default "/api/auth/user"
+	*/
+	userPath?: string;
+	/**
+	* Path to the logout endpoint
+	* @default "/api/auth/logout"
+	*/
+	logoutPath?: string;
+	/**
+	* Path to the back-channel logout endpoint
+	* @default "/api/auth/logout/backchannel"
+	*/
+	backChannelLogoutPath?: string;
+	/**
+	* Path to the token endpoint
+	* @default "/api/auth/token"
+	*/
+	tokenPath?: string;
+	/**
+	* Path to the refresh endpoint
+	* @default "/api/auth/refresh"
+	*/
+	refreshPath?: string;
+	/**
+	* Expected redirect location pattern for login
+	* Should match the IdP authorization URL
+	*/
+	expectedAuthorizationUrlPattern?: RegExp;
+	/**
+	* Optional opt-in best-practice assertion: when set, a FAILED callback's `Location` header must
+	* match this pattern. Apps following the recommended pattern redirect login failures to an
+	* unauthenticated-reachable page carrying a generic error code (e.g. `/[?&]auth_error=login_failed/`).
+	* When unset, the failure path is only asserted to be a same-origin 302 (the SDK contract).
+	*/
+	expectedCallbackErrorPattern?: RegExp;
+	/**
+	* Test user credentials for end-to-end SSO testing
+	* If not provided, only structural tests will run
+	*/
+	testCredentials?: {
+		username: string;
+		password: string;
+	};
+	/**
+	* Expected fields returned by the authenticated user endpoint after a successful SSO flow.
+	* Useful for validating userStore.lookup-enriched profile data while preserving JWT-owned auth fields.
+	*/
+	expectedUser?: {
+		id?: string;
+		userName?: string;
+		name?: string;
+		email?: string;
+		avatar?: string;
+		requireSso?: boolean;
+	};
+}
+/**
+* CIAM Validation Configuration
+*
+* Validates the customer (CIAM) domain route contracts that are distinct from
+* the workforce (SSO) domain: the customer info endpoint and magic-link issuance.
+*/
+interface CIAMValidationConfig extends ValidationConfig {
+	/**
+	* Path to the customer info endpoint (CIAM equivalent of the SSO `userPath`).
+	* @default "/api/ionite/auth/customer"
+	*/
+	customerPath?: string;
+	/**
+	* Path to the magic-link generation endpoint (workload-authenticated POST).
+	* @default "/api/ionite/magic-link"
+	*/
+	magicLinkPath?: string;
+	/**
+	* Path to the magic-link login endpoint (GET with token).
+	* @default "/api/ionite/magic-link/login"
+	*/
+	magicLinkLoginPath?: string;
+	/**
+	* Path to the CIAM logout endpoint (distinct from the SSO logout path).
+	* @default "/api/ionite/auth/customer/logout"
+	*/
+	logoutPath?: string;
+	/**
+	* Former CIAM provider-initiated back-channel logout path. The endpoint has been
+	* removed (AUDIT_HISTORY.md §1.6); the validation suite probes this path to confirm it now
+	* returns 404. Customer logout is first-party / local session invalidation only.
+	* @default "/api/ionite/auth/customer/logout/backchannel"
+	*/
+	backChannelLogoutPath?: string;
+	/**
+	* Path to the sanitized third-party provider discovery endpoint (GET).
+	* @default "/api/ionite/auth/customer/providers"
+	*/
+	customerProvidersPath?: string;
+	/**
+	* Path to the third-party customer login endpoint (GET; `?provider=` selects).
+	* @default "/api/ionite/auth/customer/login"
+	*/
+	customerLoginPath?: string;
+}
+/**
+* IAM Validation Configuration
+*/
+interface IAMValidationConfig extends ValidationConfig {
+	/**
+	* Path prefix for SCIM endpoints (used for both outgoing proxy and incoming handler)
+	* @default "/api/iam"
+	*/
+	scimPath?: string;
+	/**
+	* Path for Groups Inbound handler (app's own SCIM server for receiving group provisioning)
+	* If not provided, defaults to `${scimPath}/Groups`
+	* @example "/api/iam/Groups"
+	*/
+	groupsInboundPath?: string;
+	/**
+	* Ionite instance for workload authentication.
+	* Optional escape hatch: when provided, IAM tests use ionite workload token acquisition
+	* (requires workload to be configured). Can be a function that returns the instance
+	* (useful when instance is initialized in beforeAll).
+	*
+	* When omitted, IAM tests mint a workload token from the ECV mock server at `ecvUrl`.
+	*/
+	ion?: Ionite | (() => Ionite | null);
+	/**
+	* URL of the ECV mock server used to mint a workload token for SCIM calls when `ion` is not provided.
+	* @default "http://localhost:3515"
+	*/
+	ecvUrl?: string;
+	/**
+	* Test user data for CRUD operations
+	*/
+	testUser?: {
+		userName: string;
+		displayName: string;
+		emails: Array<{
+			value: string;
+			primary?: boolean;
+		}>;
+		name?: {
+			givenName?: string;
+			familyName?: string;
+		};
+		"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"?: EnterpriseExtension;
+	};
+	/**
+	* Test group data for CRUD operations
+	*/
+	testGroup?: {
+		displayName: string;
+		externalId?: string;
+	};
+}
+/**
+* Workload Validation Configuration
+*/
+interface WorkloadValidationConfig extends ValidationConfig {
+	/**
+	* Path to the token validation endpoint
+	* @default "/api/workload/validate"
+	*/
+	validatePath?: string;
+	/**
+	* Path to the JWKS endpoint
+	* @default "/api/workload/jwks"
+	*/
+	jwksPath?: string;
+	/**
+	* A valid workload token for the positive-path validation tests. When not provided, one is
+	* minted from the ECV mock IdP at `{ecvUrl}/workload/token`; if that fails the tests FAIL
+	* (no silent skip).
+	*/
+	validToken?: string;
+	/**
+	* URL of the ECV mock server for testing workload authentication
+	* Used for the whoami test to validate tokens independently
+	* @default "http://localhost:3515"
+	*/
+	ecvUrl?: string;
+}
+/**
+* Tenant validation scope.
+*
+* - `tenantManager`: full tenant management API (GET/DELETE/upsert by id)
+* - `creation`: POST upsert only (async TMS / deployer-style servers)
+*/
+type TenantValidationProfile = "tenantManager" | "creation";
+/**
+* Tenant Validation Configuration
+*/
+interface TenantValidationConfig extends ValidationConfig {
+	/**
+	* Which tenant-management surface to validate.
+	* @default 'tenantManager'
+	*/
+	profile?: TenantValidationProfile;
+	/**
+	* Path to the tenant creation endpoint
+	* @default "/api/tenant"
+	*/
+	tenantPath?: string;
+	/**
+	* URL path where ESVS webhook server listens for tenant creation updates
+	* If not provided, webhook tests will be skipped
+	*/
+	webhookPath?: string;
+	/**
+	* Test tenant data for tenant creation
+	*/
+	testTenantData?: {
+		id: string;
+		companyId: string;
+		companyName: string;
+		environmentType: "POC" | "DEV" | "QA" | "PROD";
+		email?: string;
+		webhookUrl?: string;
+		callbackUrl?: string;
+		/** Required: create requests must carry a `configLocator` (see `CreateTenantRequest`). */
+		configLocator: {
+			/** Optional name of a secrets source declared on the root Ionite; omit to use the default `ion.secret`. */
+			source?: string;
+			/** Tenant-specific secret path within that source. */
+			path: string;
+			/** Optional poll interval (ms) for the tenant config subscription. */
+			ttl?: number;
+		};
+	};
+}
+/**
+* Capability Catalog Validation Configuration.
+*
+* Validates the runtime readiness endpoint (`${basePath}/readyz`) and catalogs the application's
+* capabilities for publishing to the ECI. Runs at CI/CD time; the readiness endpoint it reads is the
+* runtime source of truth for per-module readiness and shares one capability definition
+* (`ION_CAPABILITY_CATALOG`) with this suite so the SDK, ECV, and docs cannot drift.
+*/
+interface CapabilityValidationConfig extends ValidationConfig {
+	/**
+	* Path to the readiness endpoint (`${basePath}/readyz`).
+	* @default "/api/ionite/readyz"
+	*/
+	readyzPath?: string;
+	/**
+	* Path to the ECV/dev-only capability discovery endpoint (`${basePath}/capabilitiez`).
+	* @default "/api/ionite/capabilitiez"
+	*/
+	capabilitiezPath?: string;
+	/**
+	* ECV mock server base URL used to mint workload tokens for authenticated capabilitiez requests.
+	* @default "http://localhost:3515"
+	*/
+	ecvUrl?: string;
+}
+/**
+* Authz / OAA Validation Configuration.
+*
+* Validates the Veza OAA projection (`ion.authz.oaa`). The in-process closure tests run with no
+* dependencies; the OAA projection tests build an Ionite instance whose OAA client points
+* at the ECV mock server's Veza receiver, so the real SDK OAA payloads can be decoded and asserted.
+*/
+interface AuthzValidationConfig {
+	/**
+	* ECV mock server handle (or getter) from `startEcvServer`. Provides the OAA receiver base URL the
+	* projection tests target. When omitted, only the dependency-free closure tests run.
+	*/
+	ecv?: EcvServerHandle | (() => EcvServerHandle);
+	/**
+	* Timeout (ms) applied to OAA readiness waits.
+	* @default 5000
+	*/
+	timeout?: number;
+}
+/**
+* Result of an individual validation test
+*/
+interface ValidationResult {
+	/**
+	* Name of the test
+	*/
+	name: string;
+	/**
+	* Whether the test passed
+	*/
+	passed: boolean;
+	/**
+	* Error message if the test failed
+	*/
+	error?: string;
+	/**
+	* Duration of the test in milliseconds
+	*/
+	duration: number;
+	/**
+	* Additional details or diagnostics
+	*/
+	details?: Record<string, unknown>;
+}
+/**
+* Result of a validation suite
+*/
+interface ValidationSuiteResult {
+	/**
+	* Name of the suite (e.g., "SSO", "IAM", "Workload")
+	*/
+	suite: string;
+	/**
+	* Whether all tests in the suite passed
+	*/
+	passed: boolean;
+	/**
+	* Individual test results
+	*/
+	tests: ValidationResult[];
+	/**
+	* Total duration of the suite in milliseconds
+	*/
+	duration: number;
+	/**
+	* Summary statistics
+	*/
+	summary: {
+		total: number;
+		passed: number;
+		failed: number;
+		skipped: number;
+	};
+}
+/**
+* Full validation report
+*/
+interface ValidationReport {
+	/**
+	* Timestamp of the validation run
+	*/
+	timestamp: Date;
+	/**
+	* Base URL tested
+	*/
+	baseUrl: string;
+	/**
+	* Whether all suites passed
+	*/
+	passed: boolean;
+	/**
+	* Individual suite results
+	*/
+	suites: ValidationSuiteResult[];
+	/**
+	* Total duration of all tests
+	*/
+	duration: number;
+}
+declare function createAuthzClosureTests(): {
+	tests: TestDef[];
+};
+/**
+* OAA projection tests. They require a running ECV mock server (its Veza receiver records the decoded
+* payloads) and validate that the real `ion.authz.oaa` client emits well-formed, correctly-encoded
+* incremental and full-snapshot payloads for pushes, grants, revokes, and sync.
+*/
+declare function createOaaProjectionTests(config: AuthzValidationConfig): TestDef[];
+/**
+* Workload OAuth-scope tests (require the ECV mock server for JWKS + token minting). They validate
+* the two authorization sources for a workload: explicit `hasScope*` (token claims) and the
+* config-gated `scopesAsEntitlements` auto-honor inside `has*`.
+*/
+declare function createWorkloadScopeTests(config: AuthzValidationConfig): TestDef[];
+/**
+* Programmatic Authz/OAA validation runner. Always runs the in-process closure tests; when an ECV
+* mock server handle is provided, also runs the OAA projection tests against its Veza receiver.
+*/
+declare function validateAuthz(config?: AuthzValidationConfig): Promise<ValidationSuiteResult>;
+/**
+* Runs all Capability Catalog validation tests and returns a suite result whose details carry the
+* capability catalog for publishing to the ECI.
+*/
+declare function validateCapabilities(config: CapabilityValidationConfig): Promise<ValidationSuiteResult>;
+/**
+* Creates a Vitest-compatible test suite for capability catalog validation.
+*/
+declare function createCapabilityTests(config: CapabilityValidationConfig): Array<TestDef>;
+import { CapabilitiezManifest, CapabilityKey, Ionite as Ionite2 } from "@ionite/server";
+interface DiscoveredECVConfig extends ValidationConfig {
+	/**
+	* ionite basePath used by the application under test.
+	* @default "/api/ionite"
+	*/
+	basePath?: string;
+	/**
+	* Override the capabilitiez path when the endpoint is not mounted at `${basePath}/capabilitiez`.
+	*/
+	capabilitiezPath?: string;
+	/**
+	* Opt-in best-practice assertion threaded into the SSO suite: when set, a FAILED callback's
+	* `Location` must match this pattern (e.g. `/[?&]auth_error=login_failed/`). See
+	* {@link SSOValidationConfig.expectedCallbackErrorPattern}.
+	*/
+	expectedCallbackErrorPattern?: RegExp;
+	/**
+	* ECV mock server handle (from `startEcvServer`), or a getter returning it. Preferred over `ecvUrl`:
+	* the discovery and IAM token-minting URL is derived from `ecv.baseUrl`, so it can never drift from
+	* where the server started. A getter is supported because the handle is often created in `beforeAll`,
+	* after test collection.
+	*/
+	ecv?: EcvServerHandle | (() => EcvServerHandle);
+	/**
+	* Ionite instance used by IAM tests to obtain workload-authenticated SCIM tokens.
+	* Optional escape hatch for real-IdP / custom-scope runs; when omitted, tokens are minted from the
+	* ECV mock server.
+	*/
+	ion?: Ionite2 | (() => Ionite2 | null);
+	/**
+	* ECV mock server base URL used to mint workload tokens for authenticated discovery.
+	* Ignored when `ecv` is provided.
+	* @default "http://localhost:3515"
+	*/
+	ecvUrl?: string;
+}
+declare function fetchCapabilitiezManifest(config: DiscoveredECVConfig): Promise<CapabilitiezManifest>;
+/**
+* A single discoverable ECV check. Entries are enumerated up front (so every possible check is
+* visible in the test reporter) and gated at run time against the capabilitiez manifest. `alwaysRun`
+* entries (in-process closure, config retry, manifest reachability) ignore capability gating.
+*/
+interface EcvCatalogEntry {
+	/** Stable machine id (suite + name slug). */
+	id: string;
+	/** Display group: 'SSO' | 'CIAM' | 'IAM' | 'Workload' | 'Authz/OAA' | 'Authz closure' | 'Discovery' | 'Config retry policy'. */
+	suite: string;
+	/** Human-readable test name. */
+	name: string;
+	/** Capability gate; when omitted (or `alwaysRun`), the check is not gated. An array passes if ANY key is testable. */
+	capability?: CapabilityKey | CapabilityKey[];
+	/** Always run regardless of capabilitiez (in-process or infrastructure checks). */
+	alwaysRun?: boolean;
+	/** Execute the underlying assertion using the resolved manifest (present for capability-gated entries). */
+	run: (manifest?: CapabilitiezManifest) => Promise<void>;
+}
+/**
+* Compute a skip reason for an entry's capability gate, or `undefined` when it should run. Prefers the
+* manifest's own `reason` string so skips explain why a capability is not wired/testable.
+*/
+declare function capabilitySkipReason(manifest: CapabilitiezManifest, capability?: CapabilityKey | CapabilityKey[]): string | undefined;
+/**
+* Build the full catalog of discoverable ECV checks. Names are enumerated synchronously so the
+* complete list is visible at collection time; capability-gated entries resolve their shared factory
+* instance lazily from the manifest at run time (preserving cross-test state such as created user ids).
+*/
+declare function buildEcvCatalog(config: DiscoveredECVConfig, options?: {
+	configRetry?: boolean;
+}): EcvCatalogEntry[];
+/**
+* Build discovered ECV tests as a flat `TestDef[]` for manual wiring.
+*
+* @deprecated Plain `TestDef`s cannot signal a real skip to the test reporter, so a capability that
+* is not testable is reported as a pass — only mitigated here by a visible `console.warn` SKIP line.
+* Prefer {@link defineDiscoveredECVSuite}, which reports each skipped capability via `ctx.skip(reason)`
+* so the reporter distinguishes skipped from passed (AUDIT_HISTORY.md §4.10).
+*/
+declare function createDiscoveredECVTests(config: DiscoveredECVConfig): Array<TestDef>;
+/**
+* Runs all CIAM validation tests
+*/
+declare function validateCIAM(config: CIAMValidationConfig): Promise<ValidationSuiteResult>;
+declare function createCIAMTests(config: CIAMValidationConfig): {
+	tests: Array<TestDef>;
+};
+/**
+* Lifecycle hardening coverage (AUDIT_HISTORY.md §5.1/§5.2/§5.4): module-readiness re-arm on de-configuration,
+* async/deadlock-guarded `beforeChange`, and robust `afterChange` error handling.
+*/
+declare function createConfigLifecycleTests(): TestDef[];
+/**
+* Config-merge & secrets-boundary coverage (AUDIT_HISTORY.md §2.1/§2.2/§2.3/§4.3/§4.5): the ConfigSource owns
+* credentials, unimplemented backends fail fast at apply, invalid/empty config payloads and locators
+* are rejected, a configured `beforeChange` always re-applies, and declared-but-unconfigured secrets
+* sources keep the module not-ready.
+*/
+declare function createConfigBoundaryTests(): TestDef[];
+declare function createConfigRetryTests(): TestDef[];
+/**
+* Canonical `ion:*` scope strings the ECV harness embeds in workload tokens so deny-by-default SDK
+* endpoints (AUDIT_HISTORY.md §1.32) authorize via `scopesAsEntitlements`. They mirror the SDK-owned Permission
+* ids so they can never drift from the gate.
+*/
+/** All three SCIM scopes (read + user/group writes) — the IAM suite reads and writes with one token. */
+declare const ION_IAM_SCOPES: string;
+/** Scope required to read the capability manifest at the capabilitiez endpoint. */
+declare const ION_CAPABILITIEZ_SCOPE: string;
+/** Scope required to manage tenant records via the tenant-management endpoints. */
+declare const ION_TENANT_SCOPE: string;
+/**
+* Get a workload token from the ECV mock server for use when calling the SDK's protected endpoints
+* (tenant management, SCIM, capabilitiez). Used by tests so the call is authenticated with a workload
+* identity.
+*
+* The SDK gates its protected endpoints deny-by-default (AUDIT_HISTORY.md §1.32). When the app under test enables
+* `RemoteConfig.authz.scopesAsEntitlements` (the ECV mock vault does), the requested `scope` is honored
+* as the matching entitlement — so pass the `ion:*` permission id(s) the endpoint requires (e.g.
+* `ion:tenant:manage`, `ion:capabilitiez:read`, or the IAM scopes). Omit `scope` to mint an
+* authenticated-but-unauthorized token (useful for asserting 403 denial).
+*
+* @param esvBaseUrl - Base URL of the ECV mock server (e.g. http://localhost:3515)
+* @param scope - Space-delimited OAuth scope(s) to embed in the token (the SDK `ion:*` permission ids)
+* @param clientId - Client ID for client_credentials grant (default: local-workload-client)
+* @param clientSecret - Client secret (default: local-workload-secret)
+* @returns The access token to use as Authorization: Bearer <token>
+*/
+declare function getTenantAuthToken(esvBaseUrl?: string, scope?: string, clientId?: string, clientSecret?: string): Promise<string>;
+declare function createHarnessSelfTests(): TestDef[];
+/**
+* Runs all IAM validation tests (core user tests + optional groups tests)
+*/
+declare function validateIAM(config: IAMValidationConfig): Promise<ValidationSuiteResult>;
+/**
+* Creates Vitest-compatible test suite for IAM validation.
+*
+* Returns `{ tests, ext }` where:
+* - `tests`: Core user management tests (always run)
+* - `ext`: Extension methods for optional functionality:
+*   - `createGroupsOutboundTests()` - Tests app calling external IAM provider
+*   - `createGroupsInboundTests()` - Tests external IAM provider calling app
+*
+* @example
+* ```ts
+* describe('IAM', () => {
+*   const { tests, ext } = createIAMTests({ ... });
+*
+*   // Core user tests
+*   tests.forEach(({ name, fn }) => it(name, fn));
+*
+*   // Optional: Groups Outbound tests (app -> external IAM)
+*   describe('Groups Outbound', () => {
+*     ext.createGroupsOutboundTests().forEach(({ name, fn }) => it(name, fn));
+*   });
+*
+*   // Optional: Groups Inbound tests (external IAM -> app)
+*   describe('Groups Inbound', () => {
+*     ext.createGroupsInboundTests().forEach(({ name, fn }) => it(name, fn));
+*   });
+* });
+* ```
+*/
+declare function createIAMTests(config: IAMValidationConfig): {
+	tests: Array<TestDef>;
+	ext: {
+		createGroupsOutboundTests: () => Array<TestDef>;
+		createGroupsInboundTests: () => Array<TestDef>;
+	};
+};
+declare function createIamDeltaPatchTests(): {
+	tests: TestDef[];
+};
+/**
+* Programmatic IAM delta validation runner (always in-process; no external server required).
+*/
+declare function validateIamDelta(): Promise<ValidationSuiteResult>;
+declare function createLfvCallbackTests(): {
+	tests: TestDef[];
+};
+declare function validateLfvDelivery(): Promise<ValidationSuiteResult>;
+declare function createOtelTests(): {
+	tests: TestDef[];
+};
+declare function validateOtel(): Promise<ValidationSuiteResult>;
+declare function createPerformanceTuningTests(): {
+	tests: TestDef[];
+};
+declare function validatePerformanceTuning(): Promise<ValidationSuiteResult>;
+/**
+* Validate the hardened protocol/error surface of the routed ionite handler. In-process; no running app.
+*/
+declare function createProtocolSurfaceTests(): {
+	tests: TestDef[];
+};
+/**
+* Run the protocol-surface validation suite and return a structured result list.
+*/
+declare function validateProtocolSurface(): Promise<{
+	name: string;
+	passed: boolean;
+	error?: string;
+}[]>;
+declare function createRedisStoreTests(): {
+	tests: TestDef[];
+};
+declare function validateRedisStores(): Promise<ValidationSuiteResult>;
+declare function createSecretsHardeningTests(): {
+	tests: TestDef[];
+};
+declare function validateSecretsHardening(): Promise<ValidationSuiteResult>;
+/**
+* Runs all SSO validation tests
+*/
+declare function validateSSO(config: SSOValidationConfig): Promise<ValidationSuiteResult>;
+/**
+* Creates Vitest-compatible test suite for SSO validation
+*/
+declare function createSSOTests(config: SSOValidationConfig): {
+	tests: Array<TestDef>;
+	ext: {
+		createJITTests: () => Array<TestDef>;
+		createLogoutTests: () => Array<TestDef>;
+		createBackChannelLogoutTests: () => Array<TestDef>;
+	};
+};
+declare function createSsoIdTokenVerificationTests(): {
+	tests: TestDef[];
+};
+declare function validateSsoIdTokenVerification(): Promise<ValidationSuiteResult>;
+/**
+* Runs all Tenant validation tests
+*/
+declare function validateTenant(config: TenantValidationConfig): Promise<ValidationSuiteResult>;
+/**
+* Creates Vitest-compatible test suite for Tenant validation
+*/
+declare function createTenantTests(config: TenantValidationConfig): Array<TestDef>;
+declare function createTenantLifecycleTests(): {
+	tests: TestDef[];
+};
+declare function validateTenantLifecycle(): Promise<ValidationSuiteResult>;
+type StandardSchemaV1 = {
+	readonly "~standard": {
+		readonly validate: (value: unknown) => {
+			value: unknown;
+		} | {
+			issues: ReadonlyArray<{
+				message: string;
+				path?: ReadonlyArray<unknown>;
+			}>;
+		} | Promise<{
+			value: unknown;
+		} | {
+			issues: ReadonlyArray<{
+				message: string;
+				path?: ReadonlyArray<unknown>;
+			}>;
+		}>;
+	};
+};
+/**
+* Creates a fetch function with default configuration
+*/
+declare function resolveBaseUrl(config: Pick<ValidationConfig, "baseUrl">): string;
+declare function createFetcher(config: ValidationConfig): (path: string, options?: RequestInit) => Promise<Response>;
+/**
+* Wraps a test function to capture timing and errors
+*/
+declare function runTest(name: string, testFn: () => Promise<undefined | {
+	details?: Record<string, unknown>;
+}>): Promise<ValidationResult>;
+/**
+* Creates a skipped test result
+*/
+declare function skipTest(name: string, reason: string): ValidationResult;
+/**
+* Assertion helper for tests
+*/
+declare function assert(condition: boolean, message: string): asserts condition;
+/**
+* Assertion helper for equality
+*/
+declare function assertEqual<T>(actual: T, expected: T, message?: string): void;
+/**
+* Assertion helper for validating data against a StandardSchemaV1 validator
+*
+* This is the preferred way to validate data when you have a validator available.
+* The validator can be from valibot, zod, or any other library that implements StandardSchemaV1.
+*
+* @param data - The data to validate
+* @param validator - A StandardSchemaV1 validator (e.g., from valibotValidators or zodValidators)
+* @param message - Optional custom error message
+*
+* @example
+* ```typescript
+* import { valibotValidators } from '@ionite/valibot';
+* const tenantValidator = valibotValidators.tenantResponse();
+* assertValid(data, tenantValidator);
+* ```
+*
+* @throws Error if validation fails
+*/
+declare function assertValid(data: unknown, validator: StandardSchemaV1, message?: string): void;
+declare function createValidatorParityTests(): {
+	tests: TestDef[];
+};
+declare function validateValidatorParity(): Promise<ValidationSuiteResult>;
+declare function createVaultWebSocketTransportTests(): {
+	tests: TestDef[];
+};
+declare function validateVaultWebSocketTransport(): Promise<ValidationSuiteResult>;
+/**
+* Runs all Workload validation tests
+*/
+declare function validateWorkload(config: WorkloadValidationConfig): Promise<ValidationSuiteResult>;
+/**
+* Creates Vitest-compatible test suite for Workload validation
+*/
+declare function createWorkloadTests(config: WorkloadValidationConfig): Array<TestDef>;
+import { Ionite as Ionite3 } from "@ionite/server";
+/**
+* Helper to create a complete Vitest test suite
+*
+* @example
+* ```typescript
+* import { describe, it } from 'vitest';
+* import { defineECVTests } from '@ionite/ecv';
+*
+* defineECVTests(describe, it, {
+*   baseUrl: 'http://localhost:3000',
+*   sso: true,
+*   workload: true,
+* });
+* ```
+*/
+declare function defineECVTests(describe: (name: string, fn: () => void) => void, it: (name: string, fn: () => Promise<void>) => void, config: {
+	baseUrl: string;
+	sso?: boolean | SSOValidationConfig;
+	ciam?: boolean | CIAMValidationConfig;
+	lfv?: boolean;
+	/**
+	* OpenTelemetry module validation. OPT-IN (`otel: true`): the suite starts a process-global
+	* `NodeSDK`, which registers global OTel providers/diagnostics for the whole test process, so it
+	* is off by default to avoid interfering with a consumer's own tracing/other suites. In-repo
+	* coverage still runs it via the discovered `capabilitiez` catalog (always-run).
+	*/
+	otel?: boolean;
+	protocolSurface?: boolean;
+	harness?: boolean;
+	secretsHardening?: boolean;
+	redisStores?: boolean;
+	tenantLifecycle?: boolean;
+	vaultWebsocket?: boolean;
+	idTokenVerification?: boolean;
+	performanceTuning?: boolean;
+	validatorParity?: boolean;
+	iam?: IAMValidationConfig;
+	workload?: boolean | WorkloadValidationConfig;
+	tenant?: boolean | TenantValidationConfig;
+	capabilities?: boolean | CapabilityValidationConfig;
+	authz?: boolean | AuthzValidationConfig;
+}): void;
+/**
+* Vitest-style lifecycle hooks passed into {@link defineDiscoveredECVSuite}.
+*
+* The helper takes hooks rather than importing `vitest` so the package stays framework-agnostic.
+*/
+/**
+* Minimal Vitest test-context shape used by discovered ECV tests. Vitest's real `TestContext`
+* structurally satisfies this (its `skip(note?)` dynamically marks the running test as skipped).
+*/
+interface EcvTestContext {
+	skip: (note?: string) => void;
+}
+interface DiscoveredECVSuiteHooks {
+	describe: (name: string, fn: () => void) => void;
+	it: (name: string, fn: (ctx: EcvTestContext) => Promise<void> | void) => void;
+	beforeAll: (fn: () => Promise<void> | void) => void;
+	afterAll: (fn: () => Promise<void> | void) => void;
+}
+/**
+* Configuration for {@link defineDiscoveredECVSuite}.
+*/
+interface DiscoveredECVSuiteConfig {
+	/**
+	* ECV mock server handle (or getter) from `startEcvServer`. The app's connection env is taken from
+	* `ecv.env`, and IAM/workload/capabilitiez token minting is derived from `ecv.baseUrl`.
+	*/
+	ecv: EcvServerHandle | (() => EcvServerHandle);
+	/**
+	* The application under test to spawn. `ecv.env` is merged in automatically (your `app.env` wins on
+	* conflicts), so you only specify app-specific variables here.
+	*/
+	app: StartAppOptions;
+	/**
+	* ionite basePath used by the application under test.
+	* @default "/api/ionite"
+	*/
+	basePath?: string;
+	/** Timeout (ms) applied to discovered validation requests. */
+	timeout?: number;
+	/**
+	* Opt-in best-practice assertion: when set, a FAILED SSO callback's `Location` must match this
+	* pattern (e.g. `/[?&]auth_error=login_failed/`), proving the app surfaces login errors to the user.
+	*/
+	expectedCallbackErrorPattern?: RegExp;
+	/**
+	* Register the config-retry policy tests alongside discovered tests.
+	* @default false
+	*/
+	configRetry?: boolean;
+	/**
+	* Optional Ionite instance escape hatch for IAM token minting (real-IdP / custom scopes).
+	* When omitted, IAM tokens are minted from the ECV mock server.
+	*/
+	ion?: Ionite3 | (() => Ionite3 | null);
+}
+/**
+* Register a complete discovered-ECV suite: spawn the app under test, run config-retry (optional) and
+* capabilitiez-discovered module tests, and tear the app down afterwards.
+*
+* The ECV mock server (and any Redis) lifecycle stays with the caller, since not every project uses Redis.
+*
+* @example
+* ```ts
+* import { afterAll, beforeAll, describe, it } from 'vitest';
+* import { defineDiscoveredECVSuite, startEcvServer, stopEcvServer } from '@ionite/ecv';
+*
+* let ecv: Awaited<ReturnType<typeof startEcvServer>>;
+* beforeAll(async () => { ecv = await startEcvServer(); });
+* afterAll(async () => { await stopEcvServer(); });
+*
+* defineDiscoveredECVSuite(
+*   { describe, it, beforeAll, afterAll },
+*   {
+*     ecv: () => ecv,
+*     app: { command: 'bun', args: ['run', 'api'], baseUrl: 'http://localhost:3544' },
+*     basePath: '/api/ionite',
+*     configRetry: true,
+*   },
+* );
+* ```
+*/
+declare function defineDiscoveredECVSuite(hooks: DiscoveredECVSuiteHooks, config: DiscoveredECVSuiteConfig): void;
+/**
+* Print a validation report to console
+*/
+declare function printReport(report: ValidationReport): void;
+export { waitForReady, validateWorkload, validateVaultWebSocketTransport, validateValidatorParity, validateTenantLifecycle, validateTenant, validateSsoIdTokenVerification, validateSecretsHardening, validateSSO, validateRedisStores, validateProtocolSurface, validatePerformanceTuning, validateOtel, validateLfvDelivery, validateIamDelta, validateIAM, validateCapabilities, validateCIAM, validateAuthz, stopEcvServer, startEcvServer, startAppUnderTest, skipTest, setVaultRedisUrl, runTest, resolveBaseUrl, printReport, getVaultRedisUrl, getTenantAuthToken, fetchCapabilitiezManifest, defineECVTests, defineDiscoveredECVSuite, createWorkloadTests, createWorkloadScopeTests, createVaultWebSocketTransportTests, createValidatorParityTests, createTenantTests, createTenantLifecycleTests, createSsoIdTokenVerificationTests, createSecretsHardeningTests, createSSOTests, createRedisStoreTests, createProtocolSurfaceTests, createPerformanceTuningTests, createOtelTests, createOaaProjectionTests, createLfvCallbackTests, createIamDeltaPatchTests, createIAMTests, createHarnessSelfTests, createFetcher, createDiscoveredECVTests, createConfigRetryTests, createConfigLifecycleTests, createConfigBoundaryTests, createCapabilityTests, createCIAMTests, createAuthzClosureTests, capabilitySkipReason, buildEcvCatalog, assertValid, assertEqual, assert, WorkloadValidationConfig, WaitForReadyOptions, ValidationSuiteResult, ValidationResult, ValidationReport, ValidationConfig, TestDef, TenantValidationProfile, TenantValidationConfig, StartAppOptions, SSOValidationConfig, ION_TENANT_SCOPE, ION_IAM_SCOPES, ION_CAPABILITIEZ_SCOPE, IAMValidationConfig, EcvTestContext, EcvServerHandle, EcvCatalogEntry, DiscoveredECVSuiteHooks, DiscoveredECVSuiteConfig, DiscoveredECVConfig, CapabilityValidationConfig, CIAMValidationConfig, AuthzValidationConfig, AppUnderTest };