@oneidentity/safeguard 7.4.0 → 8.0.0-pre36948

package/dist/index.cjs

@@ -0,0 +1,1248 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+let undici = require("undici");
+//#region src/types.ts
+/**
+* Safeguard appliance service endpoints.
+*/
+let Service = /* @__PURE__ */ function(Service) {
+	Service["CORE"] = "core";
+	Service["APPLIANCE"] = "appliance";
+	Service["NOTIFICATION"] = "notification";
+	Service["A2A"] = "a2a";
+	Service["EVENT"] = "event";
+	Service["RSTS"] = "RSTS";
+	return Service;
+}({});
+/**
+* HTTP methods supported by the Safeguard API.
+*/
+let HttpMethod = /* @__PURE__ */ function(HttpMethod) {
+	HttpMethod["GET"] = "GET";
+	HttpMethod["POST"] = "POST";
+	HttpMethod["PUT"] = "PUT";
+	HttpMethod["DELETE"] = "DELETE";
+	HttpMethod["PATCH"] = "PATCH";
+	return HttpMethod;
+}({});
+//#endregion
+//#region src/errors.ts
+var errors_exports = /* @__PURE__ */ __exportAll({
+	ApiError: () => ApiError,
+	AuthenticationError: () => AuthenticationError,
+	AuthorizationError: () => AuthorizationError,
+	ConfigurationError: () => ConfigurationError,
+	NotFoundError: () => NotFoundError,
+	SafeguardError: () => SafeguardError,
+	TransportError: () => TransportError
+});
+/**
+* Error hierarchy for the Safeguard SDK.
+*
+* SafeguardError
+* ├── ApiError              (HTTP errors from Safeguard API)
+* │   ├── AuthenticationError  (401)
+* │   ├── AuthorizationError   (403)
+* │   └── NotFoundError        (404)
+* ├── TransportError        (Network/connection failures)
+* └── ConfigurationError    (Invalid client options)
+*/
+var SafeguardError = class extends Error {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "SafeguardError";
+	}
+};
+var ApiError = class ApiError extends SafeguardError {
+	status;
+	body;
+	constructor(message, status, body = null, options) {
+		super(message, options);
+		this.name = "ApiError";
+		this.status = status;
+		this.body = body;
+	}
+	/**
+	* Creates an appropriate ApiError subclass based on HTTP status code.
+	*/
+	static fromResponse(status, body) {
+		const parsed = ApiError.parseBody(body);
+		const message = ApiError.buildMessage(status, parsed);
+		switch (status) {
+			case 401: return new AuthenticationError(message, parsed);
+			case 403: return new AuthorizationError(message, parsed);
+			case 404: return new NotFoundError(message, parsed);
+			default: return new ApiError(message, status, parsed);
+		}
+	}
+	static parseBody(body) {
+		if (body === null || body === void 0) return null;
+		if (typeof body === "object") return body;
+		try {
+			return JSON.parse(body);
+		} catch {
+			return { Message: body };
+		}
+	}
+	static buildMessage(status, body) {
+		const apiMessage = body?.Message ?? body?.InnerError?.Message;
+		if (apiMessage) return `HTTP ${String(status)}: ${apiMessage}`;
+		return `HTTP ${String(status)}`;
+	}
+};
+var AuthenticationError = class extends ApiError {
+	constructor(message, body = null, options) {
+		super(message, 401, body, options);
+		this.name = "AuthenticationError";
+	}
+};
+var AuthorizationError = class extends ApiError {
+	constructor(message, body = null, options) {
+		super(message, 403, body, options);
+		this.name = "AuthorizationError";
+	}
+};
+var NotFoundError = class extends ApiError {
+	constructor(message, body = null, options) {
+		super(message, 404, body, options);
+		this.name = "NotFoundError";
+	}
+};
+var TransportError = class extends SafeguardError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "TransportError";
+	}
+};
+var ConfigurationError = class extends SafeguardError {
+	constructor(message, options) {
+		super(message, options);
+		this.name = "ConfigurationError";
+	}
+};
+//#endregion
+//#region src/secret.ts
+const REDACTED = "[REDACTED]";
+/**
+* A wrapper that prevents accidental logging of sensitive values.
+*
+* - `toString()` returns "[REDACTED]"
+* - `toJSON()` returns "[REDACTED]"
+* - `console.log(secretValue)` prints "[REDACTED]"
+* - `.expose()` returns the raw value when intentionally needed
+*/
+var SecretValue = class {
+	#value;
+	constructor(value) {
+		this.#value = value;
+	}
+	/** Returns the raw secret. Use only when you intentionally need the plaintext. */
+	expose() {
+		return this.#value;
+	}
+	toString() {
+		return REDACTED;
+	}
+	toJSON() {
+		return REDACTED;
+	}
+	/** Node.js custom inspect (prevents leaking in console.log / util.inspect). */
+	[Symbol.for("nodejs.util.inspect.custom")]() {
+		return REDACTED;
+	}
+	get [Symbol.toStringTag]() {
+		return "SecretValue";
+	}
+};
+//#endregion
+//#region src/utils.ts
+/**
+* Validates that a host string is a bare hostname or IP address.
+* Rejects URLs, paths, query strings, userinfo, and embedded ports.
+*
+* @throws {ConfigurationError} if the host contains disallowed characters
+*/
+function validateHost(host) {
+	if (!host) throw new ConfigurationError("Host must not be empty");
+	if (host.trim() !== host) throw new ConfigurationError("Host must not contain leading or trailing whitespace");
+	if (/^[a-z][a-z0-9+.-]*:\/\//i.test(host)) throw new ConfigurationError(`Host must be a bare hostname or IP, not a URL. Remove the protocol prefix (e.g., use "${host.replace(/^[a-z][a-z0-9+.-]*:\/\//i, "")}")`);
+	if (/[/?#@]/.test(host)) throw new ConfigurationError("Host must be a bare hostname or IP address — must not contain /, ?, #, or @");
+	if (/:\d+$/.test(host) && !host.startsWith("[")) throw new ConfigurationError("Host must not include a port number. The SDK always connects over HTTPS (port 443).");
+	return host;
+}
+/**
+* Builds the base URL for a Safeguard service endpoint.
+*
+* @example
+* buildServiceUrl('appliance.example.com', Service.CORE)
+* // => 'https://appliance.example.com/service/core'
+*/
+function buildServiceUrl(host, service) {
+	if (service === "RSTS") return `https://${host}/RSTS`;
+	return `https://${host}/service/${service}`;
+}
+/**
+* Builds a full API URL including path and optional query parameters.
+*
+* @example
+* buildRequestUrl('appliance.example.com', Service.CORE, 'v4/Users', { filter: 'Name eq "admin"' })
+* // => 'https://appliance.example.com/service/core/v4/Users?filter=Name+eq+%22admin%22'
+*/
+function buildRequestUrl(host, service, relativeUrl, query) {
+	const base = buildServiceUrl(host, service);
+	const path = relativeUrl.startsWith("/") ? relativeUrl.slice(1) : relativeUrl;
+	const url = new URL(`${base}/${path}`);
+	if (query) for (const [key, value] of Object.entries(query)) url.searchParams.set(key, String(value));
+	return url.toString();
+}
+/**
+* Encodes bytes to a URL-safe base64 string (no padding).
+*/
+function base64UrlEncode(bytes) {
+	const binary = String.fromCharCode(...bytes);
+	return btoa(binary).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+/**
+* Generates a cryptographically random code verifier for PKCE.
+* Returns a 43-character base64url string (32 random bytes).
+*/
+function generateCodeVerifier() {
+	const bytes = new Uint8Array(32);
+	crypto.getRandomValues(bytes);
+	return base64UrlEncode(bytes);
+}
+/**
+* Computes the S256 code challenge from a code verifier.
+* Uses Web Crypto API (available in Node 20+ and all modern browsers).
+*/
+async function generateCodeChallenge(verifier) {
+	const data = new TextEncoder().encode(verifier);
+	const digest = await crypto.subtle.digest("SHA-256", data);
+	return base64UrlEncode(new Uint8Array(digest));
+}
+/**
+* Generates a random state parameter for OAuth flows.
+*/
+function generateState() {
+	const bytes = new Uint8Array(16);
+	crypto.getRandomValues(bytes);
+	return base64UrlEncode(bytes);
+}
+/**
+* Extracts the `exp` claim from a JWT and returns expiresIn (seconds from now).
+* Returns undefined if the token is not a valid JWT or has no `exp` claim.
+*/
+function getTokenExpiresIn(jwt) {
+	try {
+		const parts = jwt.split(".");
+		if (parts.length !== 3) return void 0;
+		const payload = parts[1].replace(/-/g, "+").replace(/_/g, "/");
+		const json = atob(payload);
+		const claims = JSON.parse(json);
+		if (typeof claims.exp !== "number") return void 0;
+		const now = Math.floor(Date.now() / 1e3);
+		return Math.max(0, claims.exp - now);
+	} catch {
+		return;
+	}
+}
+//#endregion
+//#region src/storage/memory.ts
+/**
+* In-memory storage provider. Default for Node.js environments.
+* Data does not persist across process restarts.
+*/
+var MemoryStorage = class {
+	#store = /* @__PURE__ */ new Map();
+	get(key) {
+		return this.#store.get(key) ?? null;
+	}
+	set(key, value) {
+		this.#store.set(key, value);
+	}
+	remove(key) {
+		this.#store.delete(key);
+	}
+	clear() {
+		this.#store.clear();
+	}
+};
+//#endregion
+//#region src/storage/session.ts
+/**
+* Browser sessionStorage adapter. Data persists for the browser tab lifetime.
+* Requires a DOM environment (browser or jsdom).
+*/
+var BrowserSessionStorage = class {
+	get(key) {
+		return sessionStorage.getItem(key);
+	}
+	set(key, value) {
+		sessionStorage.setItem(key, value);
+	}
+	remove(key) {
+		sessionStorage.removeItem(key);
+	}
+	clear() {
+		sessionStorage.clear();
+	}
+};
+//#endregion
+//#region src/storage/types.ts
+/** Well-known storage keys used by the SDK. */
+const StorageKeys = {
+	STATE: "safeguard_state",
+	CODE_VERIFIER: "safeguard_code_verifier"
+};
+//#endregion
+//#region src/http/node.ts
+/**
+* Node.js HTTP client using undici for full TLS control.
+* Creates a per-instance Agent — no global state mutation.
+*/
+var NodeHttpClient = class {
+	#agent;
+	constructor(tlsOptions) {
+		this.#agent = new undici.Agent({ connect: {
+			ca: tlsOptions?.ca,
+			cert: tlsOptions?.cert,
+			key: tlsOptions?.key,
+			passphrase: tlsOptions?.passphrase,
+			rejectUnauthorized: tlsOptions?.rejectUnauthorized ?? true
+		} });
+	}
+	async request(options) {
+		const { url, method, headers, body, signal, timeout } = options;
+		const requestOptions = {
+			method,
+			dispatcher: this.#agent
+		};
+		if (headers) requestOptions.headers = headers;
+		if (body != null) requestOptions.body = body;
+		if (signal) requestOptions.signal = signal;
+		if (timeout) {
+			requestOptions.bodyTimeout = timeout;
+			requestOptions.headersTimeout = timeout;
+		}
+		const response = await (0, undici.request)(url, requestOptions);
+		const responseHeaders = {};
+		const rawHeaders = response.headers;
+		for (const [key, value] of Object.entries(rawHeaders)) if (value !== void 0) responseHeaders[key] = Array.isArray(value) ? value.join(", ") : value;
+		const responseBody = await response.body.text();
+		return {
+			status: response.statusCode,
+			headers: responseHeaders,
+			body: responseBody
+		};
+	}
+	dispose() {
+		this.#agent.close().catch(() => {});
+	}
+};
+//#endregion
+//#region src/http/browser.ts
+/**
+* Browser HTTP client using native fetch API.
+* No TLS configuration needed — browser handles certificates.
+*/
+var BrowserHttpClient = class {
+	#credentials;
+	constructor(options) {
+		this.#credentials = options?.credentials ?? "include";
+	}
+	async request(options) {
+		const { url, method, headers, body, signal, timeout } = options;
+		const requestInit = {
+			method,
+			credentials: this.#credentials
+		};
+		if (headers) requestInit.headers = headers;
+		if (body != null) requestInit.body = body;
+		if (signal || timeout) {
+			const controller = new AbortController();
+			let timeoutId;
+			if (timeout) timeoutId = setTimeout(() => controller.abort(/* @__PURE__ */ new Error("Request timed out")), timeout);
+			requestInit.signal = signal ? AbortSignal.any([signal, controller.signal]) : controller.signal;
+			try {
+				return await this.#doFetch(url, requestInit);
+			} finally {
+				if (timeoutId !== void 0) clearTimeout(timeoutId);
+			}
+		}
+		return this.#doFetch(url, requestInit);
+	}
+	async #doFetch(url, init) {
+		const response = await fetch(url, init);
+		const responseHeaders = {};
+		response.headers.forEach((value, key) => {
+			responseHeaders[key] = value;
+		});
+		const responseBody = await response.text();
+		return {
+			status: response.status,
+			headers: responseHeaders,
+			body: responseBody
+		};
+	}
+};
+//#endregion
+//#region src/auth/password.ts
+/**
+* Authenticates using username/password via RSTS Resource Owner grant.
+*/
+var PasswordAuth = class {
+	#username;
+	#password;
+	#provider;
+	constructor(options) {
+		if (!options.username) throw new ConfigurationError("PasswordAuth requires username");
+		if (!options.password) throw new ConfigurationError("PasswordAuth requires password");
+		if (!options.provider) throw new ConfigurationError("PasswordAuth requires provider");
+		this.#username = options.username;
+		this.#password = new SecretValue(options.password);
+		this.#provider = options.provider;
+	}
+	get description() {
+		return `PasswordAuth(${this.#username}@${this.#provider})`;
+	}
+	async authenticate(host, httpClient, _storage) {
+		const rstsToken = await this.#getRstsToken(host, httpClient);
+		return await this.#exchangeForUserToken(host, httpClient, rstsToken);
+	}
+	async refreshToken(host, httpClient, storage) {
+		return this.authenticate(host, httpClient, storage);
+	}
+	async #getRstsToken(host, httpClient) {
+		const body = JSON.stringify({
+			grant_type: "password",
+			username: this.#username,
+			password: this.#password.expose(),
+			scope: "rsts:sts:primaryproviderid:" + this.#provider.toLowerCase()
+		});
+		const response = await httpClient.request({
+			url: `https://${host}/RSTS/oauth2/token`,
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body
+		});
+		if (response.status !== 200) {
+			const { ApiError } = await Promise.resolve().then(() => errors_exports);
+			throw ApiError.fromResponse(response.status, response.body);
+		}
+		return JSON.parse(response.body).access_token;
+	}
+	async #exchangeForUserToken(host, httpClient, rstsToken) {
+		const response = await httpClient.request({
+			url: `https://${host}/service/core/v4/Token/LoginResponse`,
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${rstsToken}`
+			},
+			body: JSON.stringify({ StsAccessToken: rstsToken })
+		});
+		if (response.status !== 200) {
+			const { ApiError } = await Promise.resolve().then(() => errors_exports);
+			throw ApiError.fromResponse(response.status, response.body);
+		}
+		const data = JSON.parse(response.body);
+		const tokenSet = {
+			accessToken: new SecretValue(data.UserToken),
+			acquiredAt: Date.now()
+		};
+		if (data.ExpiresIn != null) tokenSet.expiresIn = data.ExpiresIn;
+		else {
+			const expiresIn = getTokenExpiresIn(data.UserToken);
+			if (expiresIn != null) tokenSet.expiresIn = expiresIn;
+		}
+		return tokenSet;
+	}
+};
+//#endregion
+//#region src/auth/certificate.ts
+/**
+* Authenticates using a client certificate (mTLS) against RSTS.
+* Node.js only — requires TLS client cert support in HttpClient.
+*/
+var CertificateAuth = class {
+	#certFile;
+	#keyFile;
+	#cert;
+	#key;
+	#pfxFile;
+	#pfx;
+	#passphrase;
+	#provider;
+	constructor(options) {
+		const hasPfx = options.pfx ?? options.pfxFile;
+		const hasCert = options.cert ?? options.certFile;
+		const hasKey = options.key ?? options.keyFile;
+		if (!hasPfx && !hasCert) throw new ConfigurationError("CertificateAuth requires cert/certFile or pfxFile/pfx");
+		if (!hasPfx && !hasKey) throw new ConfigurationError("CertificateAuth requires key or keyFile");
+		this.#certFile = options.certFile;
+		this.#keyFile = options.keyFile;
+		this.#cert = options.cert;
+		this.#key = options.key;
+		this.#pfxFile = options.pfxFile;
+		this.#pfx = options.pfx;
+		this.#passphrase = options.passphrase ? new SecretValue(options.passphrase) : void 0;
+		this.#provider = options.provider ?? "certificate";
+	}
+	get description() {
+		return `CertificateAuth(${this.#provider})`;
+	}
+	/** Returns the TLS options needed to create an mTLS HttpClient. */
+	getTlsOptions() {
+		const opts = {};
+		if (this.#pfx ?? this.#pfxFile) opts.pfx = this.#pfx ?? this.#pfxFile;
+		else {
+			opts.cert = this.#cert ?? this.#certFile;
+			opts.key = this.#key ?? this.#keyFile;
+		}
+		if (this.#passphrase) opts.passphrase = this.#passphrase.expose();
+		return opts;
+	}
+	async authenticate(host, httpClient, _storage) {
+		const rstsToken = await this.#getRstsToken(host, httpClient);
+		return this.#exchangeForUserToken(host, httpClient, rstsToken);
+	}
+	async refreshToken(host, httpClient, storage) {
+		return this.authenticate(host, httpClient, storage);
+	}
+	async #getRstsToken(host, httpClient) {
+		const body = JSON.stringify({
+			grant_type: "client_credentials",
+			scope: "rsts:sts:primaryproviderid:" + this.#provider.toLowerCase()
+		});
+		const response = await httpClient.request({
+			url: `https://${host}/RSTS/oauth2/token`,
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			body
+		});
+		if (response.status !== 200) {
+			const { ApiError } = await Promise.resolve().then(() => errors_exports);
+			throw ApiError.fromResponse(response.status, response.body);
+		}
+		return JSON.parse(response.body).access_token;
+	}
+	async #exchangeForUserToken(host, httpClient, rstsToken) {
+		const response = await httpClient.request({
+			url: `https://${host}/service/core/v4/Token/LoginResponse`,
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${rstsToken}`
+			},
+			body: JSON.stringify({ StsAccessToken: rstsToken })
+		});
+		if (response.status !== 200) {
+			const { ApiError } = await Promise.resolve().then(() => errors_exports);
+			throw ApiError.fromResponse(response.status, response.body);
+		}
+		const data = JSON.parse(response.body);
+		const tokenSet = {
+			accessToken: new SecretValue(data.UserToken),
+			acquiredAt: Date.now()
+		};
+		if (data.ExpiresIn != null) tokenSet.expiresIn = data.ExpiresIn;
+		else {
+			const expiresIn = getTokenExpiresIn(data.UserToken);
+			if (expiresIn != null) tokenSet.expiresIn = expiresIn;
+		}
+		return tokenSet;
+	}
+};
+//#endregion
+//#region src/auth/pkce.ts
+/**
+* Authenticates using PKCE (Proof Key for Code Exchange) with browser redirect.
+* For browser environments where the user is redirected to RSTS login.
+*/
+var PkceAuth = class {
+	#redirectUri;
+	#provider;
+	constructor(options) {
+		if (!options.redirectUri) throw new ConfigurationError("PkceAuth requires redirectUri");
+		if (!options.provider) throw new ConfigurationError("PkceAuth requires provider");
+		this.#redirectUri = options.redirectUri;
+		this.#provider = options.provider;
+	}
+	get description() {
+		return `PKCE(redirect=${this.#redirectUri})`;
+	}
+	/**
+	* Initiates the PKCE flow. If a stored authorization code exists (from callback),
+	* exchanges it for a token. Otherwise, redirects to RSTS login.
+	*/
+	async authenticate(host, httpClient, storage) {
+		const code = storage.get("safeguard_auth_code");
+		if (code) {
+			const verifier = storage.get(StorageKeys.CODE_VERIFIER);
+			if (!verifier) throw new ConfigurationError("PKCE code verifier not found in storage");
+			storage.remove("safeguard_auth_code");
+			storage.remove(StorageKeys.CODE_VERIFIER);
+			storage.remove(StorageKeys.STATE);
+			return this.#exchangeCode(host, httpClient, code, verifier);
+		}
+		await this.#initiateRedirect(host, storage);
+		throw new ConfigurationError("PKCE redirect initiated. Call handlePkceCallback() on the callback page.");
+	}
+	async #initiateRedirect(host, storage) {
+		const verifier = generateCodeVerifier();
+		const challenge = await generateCodeChallenge(verifier);
+		const state = generateState();
+		storage.set(StorageKeys.CODE_VERIFIER, verifier);
+		storage.set(StorageKeys.STATE, state);
+		const authUrl = `https://${host}/RSTS/Login?${new URLSearchParams({
+			response_type: "code",
+			client_id: "safeguard.js",
+			redirect_uri: this.#redirectUri,
+			scope: "rsts:sts:primaryproviderid:" + this.#provider,
+			code_challenge: challenge,
+			code_challenge_method: "S256",
+			state
+		}).toString()}`;
+		if (typeof window !== "undefined" && window.location) window.location.href = authUrl;
+	}
+	async #exchangeCode(host, httpClient, code, verifier) {
+		const body = new URLSearchParams({
+			grant_type: "authorization_code",
+			code,
+			redirect_uri: this.#redirectUri,
+			client_id: "safeguard.js",
+			code_verifier: verifier
+		});
+		const response = await httpClient.request({
+			url: `https://${host}/RSTS/oauth2/token`,
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: body.toString()
+		});
+		if (response.status !== 200) {
+			const { ApiError } = await Promise.resolve().then(() => errors_exports);
+			throw ApiError.fromResponse(response.status, response.body);
+		}
+		const data = JSON.parse(response.body);
+		const userTokenResponse = await httpClient.request({
+			url: `https://${host}/service/core/v4/Token/LoginResponse`,
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${data.access_token}`
+			},
+			body: JSON.stringify({ StsAccessToken: data.access_token })
+		});
+		if (userTokenResponse.status !== 200) {
+			const { ApiError } = await Promise.resolve().then(() => errors_exports);
+			throw ApiError.fromResponse(userTokenResponse.status, userTokenResponse.body);
+		}
+		const userData = JSON.parse(userTokenResponse.body);
+		const tokenSet = {
+			accessToken: new SecretValue(userData.UserToken),
+			acquiredAt: Date.now()
+		};
+		if (userData.ExpiresIn != null) tokenSet.expiresIn = userData.ExpiresIn;
+		return tokenSet;
+	}
+};
+//#endregion
+//#region src/auth/pkce-noninteractive.ts
+/**
+* Non-interactive PKCE authentication for Node.js automation.
+* Starts a local HTTP server to receive the callback, opens the system browser
+* for login, and waits for the redirect.
+*
+* Matches PySafeguard's PkceAuth behavior (local server pattern).
+*/
+var PkceNonInteractiveAuth = class {
+	#provider;
+	#callbackPort;
+	constructor(options) {
+		this.#provider = options?.provider ?? "local";
+		this.#callbackPort = options?.callbackPort ?? 8400;
+	}
+	get description() {
+		return `PkceNonInteractiveAuth(port=${String(this.#callbackPort)})`;
+	}
+	async authenticate(host, httpClient, _storage) {
+		const { createServer } = await import("node:http");
+		const { once } = await import("node:events");
+		const verifier = generateCodeVerifier();
+		const challenge = await generateCodeChallenge(verifier);
+		const state = generateState();
+		const redirectUri = `http://localhost:${String(this.#callbackPort)}/callback`;
+		const server = createServer();
+		server.listen(this.#callbackPort);
+		const authUrl = `https://${host}/RSTS/Login?${new URLSearchParams({
+			response_type: "code",
+			client_id: "safeguard.js",
+			redirect_uri: redirectUri,
+			scope: "rsts:sts:primaryproviderid:" + this.#provider,
+			code_challenge: challenge,
+			code_challenge_method: "S256",
+			state
+		}).toString()}`;
+		await this.#openBrowser(authUrl);
+		const code = await new Promise((resolve, reject) => {
+			const timeout = setTimeout(() => {
+				server.close();
+				reject(new ConfigurationError("PKCE callback timed out after 120 seconds"));
+			}, 12e4);
+			server.on("request", (req, res) => {
+				const url = new URL(req.url ?? "/", `http://localhost:${String(this.#callbackPort)}`);
+				if (url.pathname === "/callback") {
+					const receivedCode = url.searchParams.get("code");
+					if (url.searchParams.get("state") !== state) {
+						res.writeHead(400, { "Content-Type": "text/plain" });
+						res.end("State mismatch");
+						clearTimeout(timeout);
+						server.close();
+						reject(new ConfigurationError("PKCE state mismatch"));
+						return;
+					}
+					if (!receivedCode) {
+						res.writeHead(400, { "Content-Type": "text/plain" });
+						res.end("No authorization code received");
+						clearTimeout(timeout);
+						server.close();
+						reject(new ConfigurationError("No authorization code in callback"));
+						return;
+					}
+					res.writeHead(200, { "Content-Type": "text/html" });
+					res.end("<html><body><h1>Authentication successful!</h1><p>You may close this window.</p></body></html>");
+					clearTimeout(timeout);
+					server.close();
+					resolve(receivedCode);
+				}
+			});
+			once(server, "error").then(([err]) => {
+				clearTimeout(timeout);
+				reject(err);
+			}).catch(reject);
+		});
+		return this.#exchangeCode(host, httpClient, code, verifier, redirectUri);
+	}
+	async #exchangeCode(host, httpClient, code, verifier, redirectUri) {
+		const body = new URLSearchParams({
+			grant_type: "authorization_code",
+			code,
+			redirect_uri: redirectUri,
+			client_id: "safeguard.js",
+			code_verifier: verifier
+		});
+		const response = await httpClient.request({
+			url: `https://${host}/RSTS/oauth2/token`,
+			method: "POST",
+			headers: { "Content-Type": "application/x-www-form-urlencoded" },
+			body: body.toString()
+		});
+		if (response.status !== 200) {
+			const { ApiError } = await Promise.resolve().then(() => errors_exports);
+			throw ApiError.fromResponse(response.status, response.body);
+		}
+		const data = JSON.parse(response.body);
+		const userResponse = await httpClient.request({
+			url: `https://${host}/service/core/v4/Token/LoginResponse`,
+			method: "POST",
+			headers: {
+				"Content-Type": "application/json",
+				Authorization: `Bearer ${data.access_token}`
+			},
+			body: JSON.stringify({ StsAccessToken: data.access_token })
+		});
+		if (userResponse.status !== 200) {
+			const { ApiError } = await Promise.resolve().then(() => errors_exports);
+			throw ApiError.fromResponse(userResponse.status, userResponse.body);
+		}
+		const userData = JSON.parse(userResponse.body);
+		const tokenSet = {
+			accessToken: new SecretValue(userData.UserToken),
+			acquiredAt: Date.now()
+		};
+		if (userData.ExpiresIn != null) tokenSet.expiresIn = userData.ExpiresIn;
+		return tokenSet;
+	}
+	async #openBrowser(url) {
+		const { platform } = await import("node:os");
+		const { execFile } = await import("node:child_process");
+		if (platform() === "win32") execFile("cmd", [
+			"/c",
+			"start",
+			"",
+			url
+		]);
+		else if (platform() === "darwin") execFile("open", [url]);
+		else execFile("xdg-open", [url]);
+	}
+};
+//#endregion
+//#region src/auth/pkce-callback.ts
+/**
+* Parses the PKCE callback URL and stores the authorization code.
+* Call this on the callback/redirect page to complete the PKCE flow.
+*
+* This is the explicit replacement for the legacy `safeguardJsAccessTokenChecker.js`
+* script that ran as a side-effect on import.
+*
+* @param storage - StorageProvider to persist the code
+* @param url - The callback URL to parse (defaults to window.location.href)
+* @returns The parsed code and state, or null if not a valid callback
+*/
+function handlePkceCallback(storage, url) {
+	const callbackUrl = url ?? (typeof window !== "undefined" ? window.location.href : "");
+	if (!callbackUrl) return null;
+	const parsed = new URL(callbackUrl);
+	const code = parsed.searchParams.get("code");
+	const state = parsed.searchParams.get("state");
+	if (!code || !state) return null;
+	const storedState = storage.get(StorageKeys.STATE);
+	if (storedState && storedState !== state) throw new ConfigurationError("PKCE state mismatch — possible CSRF attack");
+	storage.set("safeguard_auth_code", code);
+	return {
+		code,
+		state
+	};
+}
+//#endregion
+//#region src/auth/token.ts
+/**
+* Uses a pre-existing access token. No authentication flow — the token is assumed valid.
+* Useful when tokens are obtained externally or for service-to-service scenarios.
+*/
+var TokenAuth = class {
+	#accessToken;
+	constructor(options) {
+		if (!options.accessToken) throw new ConfigurationError("TokenAuth requires accessToken");
+		this.#accessToken = new SecretValue(options.accessToken);
+	}
+	get description() {
+		return "TokenAuth(pre-existing)";
+	}
+	async authenticate(_host, _httpClient, _storage) {
+		return {
+			accessToken: this.#accessToken,
+			acquiredAt: Date.now()
+		};
+	}
+};
+//#endregion
+//#region src/auth/anonymous.ts
+/**
+* Anonymous authentication — no credentials.
+* Used for accessing public Safeguard endpoints (e.g., appliance status).
+*/
+var AnonymousAuth = class {
+	get description() {
+		return "AnonymousAuth";
+	}
+	async authenticate(_host, _httpClient, _storage) {
+		return {
+			accessToken: new SecretValue(""),
+			acquiredAt: Date.now()
+		};
+	}
+};
+//#endregion
+//#region src/client.ts
+const DEFAULT_TIMEOUT = 3e5;
+const DEFAULT_API_VERSION = "v4";
+const TOKEN_REFRESH_MARGIN_MS = 6e4;
+/**
+* Main entry point for the Safeguard SDK.
+* Instance-based — no global state. Multiple clients to different appliances are supported.
+*/
+var SafeguardClient = class {
+	#host;
+	#auth;
+	#apiVersion;
+	#timeout;
+	#autoRefresh;
+	#ca;
+	#verify;
+	#httpClient;
+	#storage;
+	#tokenSet;
+	#connected = false;
+	constructor(host, options) {
+		if (!host) throw new ConfigurationError("SafeguardClient requires a host");
+		if (!options.auth) throw new ConfigurationError("SafeguardClient requires an auth strategy");
+		this.#host = validateHost(host);
+		this.#auth = options.auth;
+		this.#apiVersion = options.apiVersion ?? DEFAULT_API_VERSION;
+		this.#timeout = options.timeout ?? DEFAULT_TIMEOUT;
+		this.#autoRefresh = options.autoRefresh !== false;
+		this.#ca = options.ca;
+		this.#verify = options.verify !== false;
+		this.#storage = new MemoryStorage();
+	}
+	/** The appliance hostname this client connects to. */
+	get host() {
+		return this.#host;
+	}
+	/** The API version prefix (e.g. 'v4'). */
+	get apiVersion() {
+		return this.#apiVersion;
+	}
+	/** Custom CA certificate, if provided. */
+	get ca() {
+		return this.#ca;
+	}
+	/** Whether TLS verification is enabled. */
+	get verify() {
+		return this.#verify;
+	}
+	/** Whether the client has an active authenticated session. */
+	get isConnected() {
+		return this.#connected;
+	}
+	/**
+	* Sets a custom StorageProvider (e.g., BrowserSessionStorage).
+	* Must be called before connect().
+	*/
+	setStorage(storage) {
+		this.#storage = storage;
+		return this;
+	}
+	/**
+	* Sets the HttpClient implementation. If not called, must be set before connect().
+	* The factory pattern allows platform-specific client injection:
+	*   - Node: `new NodeHttpClient({ ca, rejectUnauthorized })`
+	*   - Browser: `new BrowserHttpClient()`
+	*/
+	setHttpClient(httpClient) {
+		this.#httpClient = httpClient;
+		return this;
+	}
+	/**
+	* Authenticate and establish a session.
+	* @throws {AuthenticationError} if authentication fails
+	* @throws {ConfigurationError} if httpClient not set
+	*/
+	async connect() {
+		if (!this.#httpClient) throw new ConfigurationError("HttpClient not set. Call setHttpClient() before connect(), or use SafeguardClient.createNode() / SafeguardClient.createBrowser().");
+		this.#tokenSet = await this.#auth.authenticate(this.#host, this.#httpClient, this.#storage);
+		if (!this.#tokenSet.accessToken.expose()) throw new AuthenticationError("Authentication returned empty access token");
+		this.#connected = true;
+	}
+	/**
+	* Disconnect — dispose HTTP client and clear token.
+	*/
+	async disconnect() {
+		this.#tokenSet = void 0;
+		this.#connected = false;
+		this.#httpClient?.dispose?.();
+	}
+	/**
+	* Returns seconds until the current access token expires, or -1 if unknown.
+	*/
+	getAccessTokenLifetimeRemaining() {
+		if (!this.#tokenSet?.expiresIn) return -1;
+		const elapsed = (Date.now() - this.#tokenSet.acquiredAt) / 1e3;
+		return Math.max(0, this.#tokenSet.expiresIn - elapsed);
+	}
+	async get(service, relativeUrl, options) {
+		return this.invoke(service, "GET", relativeUrl, options);
+	}
+	async post(service, relativeUrl, options) {
+		return this.invoke(service, "POST", relativeUrl, options);
+	}
+	async put(service, relativeUrl, options) {
+		return this.invoke(service, "PUT", relativeUrl, options);
+	}
+	async delete(service, relativeUrl, options) {
+		return this.invoke(service, "DELETE", relativeUrl, options);
+	}
+	async patch(service, relativeUrl, options) {
+		return this.invoke(service, "PATCH", relativeUrl, options);
+	}
+	/**
+	* Low-level request method. Convenience verbs delegate here.
+	*
+	* When `options.fullResponse` is true, returns SafeguardResponse<T> with status + headers.
+	* Otherwise returns just the parsed response body as T.
+	*/
+	async invoke(service, method, relativeUrl, options) {
+		if (!this.#connected || !this.#httpClient) throw new ConfigurationError("Client not connected. Call connect() first.");
+		if (this.#autoRefresh) await this.#ensureValidToken();
+		const url = buildRequestUrl(this.#host, service, relativeUrl, options?.query);
+		const headers = {
+			Authorization: `Bearer ${this.#tokenSet.accessToken.expose()}`,
+			Accept: "application/json",
+			...options?.headers
+		};
+		let body = null;
+		if (options?.json != null) {
+			body = JSON.stringify(options.json);
+			headers["Content-Type"] = "application/json";
+		} else if (options?.body != null) body = options.body;
+		const requestOpts = {
+			url,
+			method,
+			headers,
+			body,
+			timeout: options?.timeout ?? this.#timeout
+		};
+		if (options?.signal) requestOpts.signal = options.signal;
+		const response = await this.#httpClient.request(requestOpts);
+		if (response.status >= 400) throw ApiError.fromResponse(response.status, response.body);
+		const data = response.body ? JSON.parse(response.body) : void 0;
+		if (options?.fullResponse) return {
+			data,
+			status: response.status,
+			headers: response.headers
+		};
+		return data;
+	}
+	async #ensureValidToken() {
+		if (!this.#tokenSet) return;
+		if (!this.#tokenSet.expiresIn) return;
+		const elapsed = Date.now() - this.#tokenSet.acquiredAt;
+		const expiresInMs = this.#tokenSet.expiresIn * 1e3;
+		if (elapsed + TOKEN_REFRESH_MARGIN_MS >= expiresInMs) {
+			if (this.#auth.refreshToken) {
+				const refreshed = await this.#auth.refreshToken(this.#host, this.#httpClient, this.#storage);
+				if (refreshed) {
+					this.#tokenSet = refreshed;
+					return;
+				}
+			}
+			this.#tokenSet = await this.#auth.authenticate(this.#host, this.#httpClient, this.#storage);
+		}
+	}
+};
+//#endregion
+//#region src/a2a/types.ts
+/**
+* SSH key formats for private key retrieval.
+*/
+let SshKeyFormat = /* @__PURE__ */ function(SshKeyFormat) {
+	SshKeyFormat["OpenSsh"] = "OpenSsh";
+	SshKeyFormat["Ssh2"] = "Ssh2";
+	SshKeyFormat["Putty"] = "Putty";
+	return SshKeyFormat;
+}({});
+/**
+* Brokered access request types.
+*/
+let BrokeredAccessRequestType = /* @__PURE__ */ function(BrokeredAccessRequestType) {
+	BrokeredAccessRequestType["Password"] = "Password";
+	BrokeredAccessRequestType["SshKey"] = "SshKey";
+	BrokeredAccessRequestType["ApiKey"] = "ApiKey";
+	BrokeredAccessRequestType["Token"] = "Token";
+	BrokeredAccessRequestType["RdpFile"] = "RdpFile";
+	BrokeredAccessRequestType["RemoteDesktop"] = "RemoteDesktop";
+	BrokeredAccessRequestType["SshSession"] = "SshSession";
+	return BrokeredAccessRequestType;
+}({});
+//#endregion
+//#region src/a2a/index.ts
+/**
+* Application-to-Application client for programmatic credential retrieval.
+* Uses client certificate authentication exclusively.
+*
+* Full parity with PySafeguard and SafeguardDotNet A2A clients.
+*/
+var A2AClient = class {
+	#host;
+	#auth;
+	#ca;
+	#verify;
+	#httpClient;
+	constructor(host, options) {
+		if (!host) throw new ConfigurationError("A2AClient requires a host");
+		if (!options.auth) throw new ConfigurationError("A2AClient requires a CertificateAuth");
+		this.#host = host;
+		this.#auth = options.auth;
+		this.#ca = options.ca;
+		this.#verify = options.verify !== false;
+	}
+	/** The appliance hostname. */
+	get host() {
+		return this.#host;
+	}
+	/** Custom CA, if set. */
+	get ca() {
+		return this.#ca;
+	}
+	/** Whether TLS verification is enabled. */
+	get verify() {
+		return this.#verify;
+	}
+	/** The CertificateAuth providing TLS client cert configuration. */
+	get auth() {
+		return this.#auth;
+	}
+	/**
+	* Sets the HttpClient (must be configured with client cert TLS).
+	*/
+	setHttpClient(httpClient) {
+		this.#httpClient = httpClient;
+		return this;
+	}
+	/**
+	* Retrieve a password credential via A2A.
+	* @param apiKey - The API key for the retrievable account
+	*/
+	async retrievePassword(apiKey) {
+		return new SecretValue(await this.#a2aRequest(apiKey, "Credentials", "Password"));
+	}
+	/**
+	* Retrieve an SSH private key credential via A2A.
+	* @param apiKey - The API key for the retrievable account
+	* @param format - SSH key format (default: OpenSsh)
+	*/
+	async retrievePrivateKey(apiKey, format) {
+		const keyType = format ?? "OpenSsh";
+		return new SecretValue(await this.#a2aRequest(apiKey, "Credentials", `SshKey?keyFormat=${keyType}`));
+	}
+	/**
+	* Retrieve an API key secret credential via A2A.
+	* @param apiKey - The API key for the retrievable account
+	*/
+	async retrieveApiKeySecret(apiKey) {
+		return new SecretValue(await this.#a2aRequest(apiKey, "Credentials", "ApiKey"));
+	}
+	/**
+	* Get the list of retrievable accounts available to this certificate.
+	*/
+	async getRetrievableAccounts() {
+		this.#ensureHttpClient();
+		const response = await this.#httpClient.request({
+			url: `https://${this.#host}/service/a2a/v4/A2ARegistrations`,
+			method: "GET",
+			headers: { Accept: "application/json" }
+		});
+		if (response.status !== 200) throw ApiError.fromResponse(response.status, response.body);
+		return JSON.parse(response.body);
+	}
+	/**
+	* Set a password on a managed account via A2A.
+	* @param apiKey - The API key for the account
+	* @param password - The new password value
+	*/
+	async setPassword(apiKey, password) {
+		this.#ensureHttpClient();
+		const response = await this.#httpClient.request({
+			url: `https://${this.#host}/service/a2a/v4/Credentials/Password`,
+			method: "PUT",
+			headers: {
+				Authorization: `A2A ${apiKey}`,
+				"Content-Type": "application/json",
+				Accept: "application/json"
+			},
+			body: JSON.stringify(password)
+		});
+		if (response.status !== 200 && response.status !== 204) throw ApiError.fromResponse(response.status, response.body);
+	}
+	/**
+	* Set a private key on a managed account via A2A.
+	* @param apiKey - The API key for the account
+	* @param key - The private key content
+	* @param passphrase - Optional passphrase for the key
+	* @param format - SSH key format (default: OpenSsh)
+	*/
+	async setPrivateKey(apiKey, key, passphrase, format) {
+		this.#ensureHttpClient();
+		const payload = {
+			PrivateKey: key,
+			KeyFormat: format ?? "OpenSsh"
+		};
+		if (passphrase) payload["Passphrase"] = passphrase;
+		const response = await this.#httpClient.request({
+			url: `https://${this.#host}/service/a2a/v4/Credentials/SshKey`,
+			method: "PUT",
+			headers: {
+				Authorization: `A2A ${apiKey}`,
+				"Content-Type": "application/json",
+				Accept: "application/json"
+			},
+			body: JSON.stringify(payload)
+		});
+		if (response.status !== 200 && response.status !== 204) throw ApiError.fromResponse(response.status, response.body);
+	}
+	/**
+	* Submit a brokered access request via A2A.
+	* @param apiKey - The API key for the access request
+	* @param request - The access request details
+	*/
+	async brokerAccessRequest(apiKey, request) {
+		this.#ensureHttpClient();
+		const response = await this.#httpClient.request({
+			url: `https://${this.#host}/service/a2a/v4/AccessRequests`,
+			method: "POST",
+			headers: {
+				Authorization: `A2A ${apiKey}`,
+				"Content-Type": "application/json",
+				Accept: "application/json"
+			},
+			body: JSON.stringify(request)
+		});
+		if (response.status !== 200 && response.status !== 201) throw ApiError.fromResponse(response.status, response.body);
+		return JSON.parse(response.body);
+	}
+	async #a2aRequest(apiKey, ...pathSegments) {
+		this.#ensureHttpClient();
+		const path = pathSegments.join("/");
+		const response = await this.#httpClient.request({
+			url: `https://${this.#host}/service/a2a/v4/${path}`,
+			method: "GET",
+			headers: {
+				Authorization: `A2A ${apiKey}`,
+				Accept: "application/json"
+			}
+		});
+		if (response.status !== 200) throw ApiError.fromResponse(response.status, response.body);
+		return response.body;
+	}
+	#ensureHttpClient() {
+		if (!this.#httpClient) throw new ConfigurationError("HttpClient not set. Call setHttpClient() with a client configured for mTLS.");
+	}
+};
+//#endregion
+exports.A2AClient = A2AClient;
+exports.AnonymousAuth = AnonymousAuth;
+exports.ApiError = ApiError;
+exports.AuthenticationError = AuthenticationError;
+exports.AuthorizationError = AuthorizationError;
+exports.BrokeredAccessRequestType = BrokeredAccessRequestType;
+exports.BrowserHttpClient = BrowserHttpClient;
+exports.BrowserSessionStorage = BrowserSessionStorage;
+exports.CertificateAuth = CertificateAuth;
+exports.ConfigurationError = ConfigurationError;
+exports.HttpMethod = HttpMethod;
+exports.MemoryStorage = MemoryStorage;
+exports.NodeHttpClient = NodeHttpClient;
+exports.NotFoundError = NotFoundError;
+exports.PasswordAuth = PasswordAuth;
+exports.PkceAuth = PkceAuth;
+exports.PkceNonInteractiveAuth = PkceNonInteractiveAuth;
+exports.SafeguardClient = SafeguardClient;
+exports.SafeguardError = SafeguardError;
+exports.SecretValue = SecretValue;
+exports.Service = Service;
+exports.SshKeyFormat = SshKeyFormat;
+exports.StorageKeys = StorageKeys;
+exports.TokenAuth = TokenAuth;
+exports.TransportError = TransportError;
+exports.base64UrlEncode = base64UrlEncode;
+exports.buildRequestUrl = buildRequestUrl;
+exports.buildServiceUrl = buildServiceUrl;
+exports.generateCodeChallenge = generateCodeChallenge;
+exports.generateCodeVerifier = generateCodeVerifier;
+exports.generateState = generateState;
+exports.handlePkceCallback = handlePkceCallback;
+exports.validateHost = validateHost;
+
+//# sourceMappingURL=index.cjs.map