unjwt 0.8.3 → 0.8.5

package/dist/_chunks/{_jwt-internal.mjs → jwt.mjs}

@@ -1,43 +1,86 @@
-import { UnsecureError, base64Parse as base64Parse$1, base64Stringify as base64Stringify$1, safeJsonParse, textEncoder } from "./libs/unsecure.mjs";
-var JWTError = class extends Error {
-	code;
-	cause;
-	constructor(message, code, cause) {
-		super(message);
-		this.name = "JWTError";
-		this.code = code;
-		this.cause = cause;
-	}
-};
-function isJWTError(error, code) {
-	if (!(error instanceof JWTError)) return false;
-	return code === void 0 || error.code === code;
+import { UnsecureError, safeJsonParse, textEncoder } from "./libs/unsecure.mjs";
+import { JWTError } from "../error.mjs";
+function base64UrlStringify(data) {
+	return encode(bytesOf(data, "Base64Url"), "base64url");
 }
-function isUnsecureError(error, code) {
-	if (!(error instanceof UnsecureError)) return false;
-	return code === void 0 || error.code === code;
+function base64Stringify(data) {
+	return encode(bytesOf(data, "Base64"), "base64");
 }
-function base64UrlStringify(data) {
-	return base64Stringify$1(data, { alphabet: "base64url" });
+function base64UrlParse(text, options) {
+	return parse(text, URL, false, "Base64Url", options);
 }
-function base64UrlParse(input, options) {
-	const parseOptions = {
-		...options,
-		alphabet: "base64url",
-		padding: false
-	};
-	return typeof input === "string" ? base64Parse$1(input, parseOptions) : base64Parse$1(input, parseOptions);
+function base64Parse(text, options) {
+	return parse(text, STD, true, "Base64", options);
 }
-function base64Stringify(data) {
-	return base64Stringify$1(data);
+const URL = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+const STD = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
+const fatalDecoder = /* @__PURE__ */ new TextDecoder("utf-8", {
+	ignoreBOM: true,
+	fatal: true
+});
+function bytesOf(data, label) {
+	if (typeof data === "string") return textEncoder.encode(data);
+	if (data instanceof Uint8Array) return data;
+	throw new UnsecureError("INVALID_TYPE", `${label}.stringify: expected a string or Uint8Array.`);
+}
+function encode(bytes, name) {
+	const buffer = globalThis.Buffer;
+	if (typeof buffer?.from === "function") return buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString(name);
+	if ("toBase64" in Uint8Array.prototype) return (bytes.byteOffset === 0 && bytes.byteLength === bytes.buffer.byteLength ? bytes : bytes.slice()).toBase64({
+		alphabet: name,
+		omitPadding: name === "base64url"
+	});
+	const alphabet = name === "base64url" ? URL : STD;
+	const padded = name === "base64";
+	let out = "";
+	let i = 0;
+	for (; i + 2 < bytes.length; i += 3) {
+		const n = bytes[i] << 16 | bytes[i + 1] << 8 | bytes[i + 2];
+		out += alphabet[n >>> 18] + alphabet[n >>> 12 & 63] + alphabet[n >>> 6 & 63] + alphabet[n & 63];
+	}
+	const rem = bytes.length - i;
+	if (rem === 1) {
+		const n = bytes[i] << 16;
+		out += alphabet[n >>> 18] + alphabet[n >>> 12 & 63] + (padded ? "==" : "");
+	} else if (rem === 2) {
+		const n = bytes[i] << 16 | bytes[i + 1] << 8;
+		out += alphabet[n >>> 18] + alphabet[n >>> 12 & 63] + alphabet[n >>> 6 & 63] + (padded ? "=" : "");
+	}
+	return out;
+}
+function parse(text, alphabet, padded, label, options) {
+	if (typeof text !== "string") throw new UnsecureError("INVALID_TYPE", `${label}.parse: expected a string, got ${typeof text}.`);
+	const wantString = options?.returnAs === void 0 || options.returnAs === "string";
+	let end = text.length;
+	while (end > 0 && text.charCodeAt(end - 1) === 61) end--;
+	const rem = end % 4;
+	if (rem === 1) throw malformed(label, `${end} symbols cannot encode whole bytes.`);
+	const padNeeded = padded && rem !== 0 ? 4 - rem : 0;
+	if (text.length - end !== padNeeded) throw malformed(label, `expected ${padNeeded} "=" padding characters, found ${text.length - end}.`);
+	const out = new Uint8Array(end * 6 >>> 3);
+	let acc = 0;
+	let held = 0;
+	let j = 0;
+	for (let i = 0; i < end; i++) {
+		const value = alphabet.indexOf(text[i]);
+		if (value < 0) throw malformed(label, `invalid character ${JSON.stringify(text[i])} at index ${i}.`);
+		acc = acc << 6 | value;
+		held += 6;
+		if (held >= 8) {
+			held -= 8;
+			out[j++] = acc >>> held & 255;
+		}
+	}
+	if (held !== 0 && (acc & (1 << held) - 1) !== 0) throw malformed(label, "the last symbol sets bits past the final byte.");
+	if (!wantString) return out;
+	try {
+		return fatalDecoder.decode(out);
+	} catch {
+		throw malformed(label, "decoded bytes are not valid UTF-8.");
+	}
 }
-function base64Parse(input, options) {
-	const parseOptions = {
-		...options,
-		alphabet: "base64",
-		padding: true
-	};
-	return typeof input === "string" ? base64Parse$1(input, parseOptions) : base64Parse$1(input, parseOptions);
+function malformed(label, detail) {
+	return new UnsecureError("MALFORMED", `${label}.parse: ${detail}`);
 }
 const base64UrlEncode = base64UrlStringify;
 const base64UrlDecode = base64UrlParse;
@@ -75,11 +118,20 @@ function isPrivateJWK(key) {
 	return "d" in key && typeof key.d === "string";
 }
 function isPublicJWK(key) {
-	if (!isJWK(key) || key.kty === "oct" || "d" in key && typeof key.d === "string") return false;
+	if (!isJWK(key) || key.kty === "oct" || Object.hasOwn(key, "k")) return false;
+	if ("d" in key && typeof key.d === "string") return false;
 	if (key.kty === "EC") return typeof key.x === "string" && typeof key.y === "string";
 	if (key.kty === "OKP") return typeof key.x === "string";
 	return typeof key.n === "string" && typeof key.e === "string";
 }
+function hasSymmetricSecret(key) {
+	return key.kty === "oct" || Object.hasOwn(key, "k");
+}
+const MAX_QUOTED_VALUE = 64;
+function quoteTokenValue(value) {
+	const text = String(value);
+	return JSON.stringify(text.length > MAX_QUOTED_VALUE ? `${text.slice(0, MAX_QUOTED_VALUE)}…` : text);
+}
 function concatUint8Arrays(...arrays) {
 	const totalLength = arrays.reduce((length, arr) => length + arr.length, 0);
 	const result = new Uint8Array(totalLength);
@@ -91,7 +143,7 @@ function concatUint8Arrays(...arrays) {
 	return result;
 }
 function uint32be(value) {
-	if (value < 0 || value >= 2 ** 32) throw new JWTError(`value must be >= 0 and <= ${2 ** 32 - 1}. Received ${value}`, "ERR_INVALID_OPTION");
+	if (value < 0 || value >= 2 ** 32) throw new JWTError(`value must be >= 0 and <= ${2 ** 32 - 1} (got ${value})`, "ERR_INVALID_OPTION");
 	return new Uint8Array([
 		value >>> 24,
 		value >>> 16,
@@ -142,7 +194,7 @@ function parseDurationSeconds(value) {
 	}
 	if (typeof value === "string") {
 		const match = value.match(DURATION_REGEX);
-		if (!match || !match[1]) throw new JWTError("Invalid duration format. Must be an integer or a string like '10m', '2h', '7D', etc.", "ERR_INVALID_OPTION");
+		if (!match || !match[1]) throw new JWTError("Duration must be an integer or a string like '10m' or '7D'.", "ERR_INVALID_OPTION");
 		const n = Number.parseInt(match[1], 10);
 		const unit = match[2] || "s";
 		return n * TIME_CONSTANTS[unit];
@@ -155,12 +207,12 @@ function computeDurationInSeconds(duration) {
 	return seconds;
 }
 function expiredClaimMessage(exp) {
-	return `JWT "exp" (Expiration Time) Claim validation failed: Token has expired (exp: ${(/* @__PURE__ */ new Date(exp * 1e3)).toISOString()})`;
+	return `JWT "exp" is in the past (${_formatNumericDate(exp)}).`;
 }
 function validateJwtClaims(jwtClaims, options = {}) {
 	assertClaimValidationOptions(options);
 	const clockTolerance = _normalizeClockTolerance(options.clockTolerance);
-	const currentTime = Math.round((options.currentDate ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+	const currentTime = (options.currentDate ?? /* @__PURE__ */ new Date()).getTime() / 1e3;
 	if (options.requiredClaims !== void 0 || options.issuer !== void 0 || options.audience !== void 0 || options.subject !== void 0 || options.maxTokenAge !== void 0) {
 		const allRequiredClaims = new Set(options.requiredClaims);
 		if (options.issuer !== void 0) allRequiredClaims.add("iss");
@@ -171,33 +223,25 @@ function validateJwtClaims(jwtClaims, options = {}) {
 		for (const claimName of allRequiredClaims) if (!Object.hasOwn(jwtClaims, claimName)) missingClaims.push(claimName);
 		if (missingClaims.length > 0) throw new JWTError(`Missing required JWT Claims: ${missingClaims.join(", ")}`, "ERR_JWT_CLAIM_MISSING");
 	}
-	_assertNumericDate(jwtClaims.exp, "exp", "Expiration Time");
-	_assertNumericDate(jwtClaims.nbf, "nbf", "Not Before");
-	_assertNumericDate(jwtClaims.iat, "iat", "Issued At");
+	_assertNumericDate(jwtClaims.exp, "exp");
+	_assertNumericDate(jwtClaims.nbf, "nbf");
+	_assertNumericDate(jwtClaims.iat, "iat");
 	if (options.issuer !== void 0) {
 		const expectedIssuers = maybeArray(options.issuer);
-		if (!jwtClaims.iss || !expectedIssuers.includes(jwtClaims.iss)) throw new JWTError(`Invalid JWT "iss" (Issuer) Claim: Expected ${expectedIssuers.join(" or ")}, got ${jwtClaims.iss}`, "ERR_JWT_CLAIM_INVALID");
+		if (!jwtClaims.iss || !expectedIssuers.includes(jwtClaims.iss)) throw new JWTError(`Invalid JWT "iss": expected ${expectedIssuers.join(" or ")}, got ${jwtClaims.iss}`, "ERR_JWT_CLAIM_INVALID");
 	}
-	if (options.subject !== void 0 && jwtClaims.sub !== options.subject) throw new JWTError(`Invalid JWT "sub" (Subject) Claim: Expected ${options.subject}, got ${jwtClaims.sub}`, "ERR_JWT_CLAIM_INVALID");
+	if (options.subject !== void 0 && jwtClaims.sub !== options.subject) throw new JWTError(`Invalid JWT "sub": expected ${options.subject}, got ${jwtClaims.sub}`, "ERR_JWT_CLAIM_INVALID");
 	if (options.audience !== void 0) {
 		const expectedAudiences = maybeArray(options.audience);
 		const claimAudience = maybeArray(jwtClaims.aud || []);
-		if (!claimAudience.some((aud) => expectedAudiences.includes(aud))) throw new JWTError(`Invalid JWT "aud" (Audience) Claim: Expected ${expectedAudiences.join(" or ")}, got ${claimAudience.join(", ")}`, "ERR_JWT_CLAIM_INVALID");
+		if (!claimAudience.some((aud) => expectedAudiences.includes(aud))) throw new JWTError(`Invalid JWT "aud": expected ${expectedAudiences.join(" or ")}, got ${claimAudience.join(", ")}`, "ERR_JWT_CLAIM_INVALID");
 	}
-	if (typeof jwtClaims.nbf === "number" && jwtClaims.nbf > currentTime + clockTolerance) throw new JWTError(`JWT "nbf" (Not Before) Claim validation failed: Token is not yet valid (nbf: ${(/* @__PURE__ */ new Date(jwtClaims.nbf * 1e3)).toISOString()})`, "ERR_JWT_NBF");
-	if (typeof jwtClaims.exp === "number" && jwtClaims.exp <= currentTime - clockTolerance) throw new JWTError(expiredClaimMessage(jwtClaims.exp), "ERR_JWT_EXPIRED", {
-		jti: jwtClaims.jti,
-		iat: jwtClaims.iat,
-		exp: jwtClaims.exp
-	});
+	if (typeof jwtClaims.nbf === "number" && jwtClaims.nbf > currentTime + clockTolerance) throw new JWTError(`JWT "nbf" is in the future (${_formatNumericDate(jwtClaims.nbf)}).`, "ERR_JWT_NBF");
+	if (typeof jwtClaims.exp === "number" && jwtClaims.exp <= currentTime - clockTolerance) throw new JWTError(expiredClaimMessage(jwtClaims.exp), "ERR_JWT_EXPIRED", _expiredCause(jwtClaims));
 	if (options.maxTokenAge !== void 0) {
-		if (typeof jwtClaims.iat !== "number") throw new JWTError("JWT \"iat\" (Issued At) Claim must be a number when maxTokenAge is set.", "ERR_JWT_CLAIM_INVALID");
-		if (jwtClaims.iat > currentTime + clockTolerance) throw new JWTError(`JWT "iat" (Issued At) Claim validation failed: Token was issued in the future (iat: ${(/* @__PURE__ */ new Date(jwtClaims.iat * 1e3)).toISOString()})`, "ERR_JWT_CLAIM_INVALID");
-		if (jwtClaims.iat < currentTime - computeDurationInSeconds(options.maxTokenAge) - clockTolerance) throw new JWTError(`JWT "iat" (Issued At) Claim validation failed: Token is too old (maxTokenAge: ${options.maxTokenAge}, iat: ${(/* @__PURE__ */ new Date(jwtClaims.iat * 1e3)).toISOString()})`, "ERR_JWT_EXPIRED", {
-			jti: jwtClaims.jti,
-			iat: jwtClaims.iat,
-			exp: jwtClaims.exp
-		});
+		if (typeof jwtClaims.iat !== "number") throw new JWTError("JWT \"iat\" must be a number when maxTokenAge is set.", "ERR_JWT_CLAIM_INVALID");
+		if (jwtClaims.iat > currentTime + clockTolerance) throw new JWTError(`JWT "iat" is in the future (${_formatNumericDate(jwtClaims.iat)}).`, "ERR_JWT_CLAIM_INVALID");
+		if (jwtClaims.iat < currentTime - computeDurationInSeconds(options.maxTokenAge) - clockTolerance) throw new JWTError(`JWT "iat" is older than maxTokenAge ${options.maxTokenAge}.`, "ERR_JWT_EXPIRED", _expiredCause(jwtClaims));
 	}
 }
 function assertClaimValidationOptions(options) {
@@ -238,10 +282,22 @@ function _assertExpectedValues(value, name) {
 function _isNonEmptyString(value) {
 	return typeof value === "string" && value !== "";
 }
-function _assertNumericDate(value, claim, label) {
+function _assertNumericDate(value, claim) {
 	if (value === void 0) return;
-	if (typeof value !== "number" || !Number.isFinite(value)) throw new JWTError(`JWT "${claim}" (${label}) Claim must be a number.`, "ERR_JWT_CLAIM_INVALID");
-	if (value < 0) throw new JWTError(`JWT "${claim}" (${label}) Claim must be a non-negative NumericDate.`, "ERR_JWT_CLAIM_INVALID");
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new JWTError(`JWT "${claim}" must be a number.`, "ERR_JWT_CLAIM_INVALID");
+	if (value < 0) throw new JWTError(`JWT "${claim}" must be a non-negative NumericDate.`, "ERR_JWT_CLAIM_INVALID");
+}
+function _formatNumericDate(seconds) {
+	const date = /* @__PURE__ */ new Date(seconds * 1e3);
+	return Number.isFinite(date.getTime()) ? date.toISOString() : String(seconds);
+}
+function _expiredCause(claims) {
+	const { jti, iat, exp } = claims;
+	return {
+		jti: typeof jti === "string" ? jti : void 0,
+		iat,
+		exp
+	};
 }
 function applyTypDefault(header, payload) {
 	const declared = header.typ;
@@ -285,8 +341,8 @@ function getPlaintextBytes(payload) {
 function computeJwtTimeClaims(payload, options) {
 	const { currentDate, issuedAt, expiresIn, expiresAt, notBeforeIn, notBeforeAt } = options ?? {};
 	if (issuedAt !== void 0 && typeof issuedAt !== "boolean" && !(issuedAt instanceof Date)) throw new JWTError("\"issuedAt\" must be a boolean or a Date.", "ERR_INVALID_OPTION");
-	if (expiresIn !== void 0 && expiresAt !== void 0) throw new JWTError("\"expiresIn\" and \"expiresAt\" are mutually exclusive; pass only one.", "ERR_JWT_CLAIM_INVALID");
-	if (notBeforeIn !== void 0 && notBeforeAt !== void 0) throw new JWTError("\"notBeforeIn\" and \"notBeforeAt\" are mutually exclusive; pass only one.", "ERR_JWT_CLAIM_INVALID");
+	if (expiresIn !== void 0 && expiresAt !== void 0) throw new JWTError("\"expiresIn\" and \"expiresAt\" are mutually exclusive.", "ERR_JWT_CLAIM_INVALID");
+	if (notBeforeIn !== void 0 && notBeforeAt !== void 0) throw new JWTError("\"notBeforeIn\" and \"notBeforeAt\" are mutually exclusive.", "ERR_JWT_CLAIM_INVALID");
 	const hasExpHint = expiresIn !== void 0 || expiresAt !== void 0;
 	const hasNbfHint = notBeforeIn !== void 0 || notBeforeAt !== void 0;
 	const hasIatHint = issuedAt === true || issuedAt instanceof Date;
@@ -296,7 +352,7 @@ function computeJwtTimeClaims(payload, options) {
 	const wantsNbf = hasNbfHint && (!("nbf" in payload) || payload.nbf === void 0);
 	const wantsIat = hasIatHint && (!("iat" in payload) || payload.iat === void 0);
 	if (!wantsExp && !wantsNbf && !wantsIat) return void 0;
-	const now = Math.round((currentDate ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
+	const now = Math.floor((currentDate ?? /* @__PURE__ */ new Date()).getTime() / 1e3);
 	const claims = { ...payload };
 	claims.iat ||= issuedAt instanceof Date ? Math.floor(_instantOf(issuedAt, "issuedAt") / 1e3) : now;
 	if (wantsExp) {
@@ -384,8 +440,8 @@ function validateCriticalHeaders(protectedHeader, options) {
 	const { family, recognizedHeaders = [] } = options;
 	assertCritShape(crit, { family });
 	for (const param of crit) {
-		if (!Object.hasOwn(protectedHeader, param)) throw new JWTError(`Critical header parameter "${param}" listed in "crit" but not present in the protected header.`, `ERR_${family}_INVALID`);
-		if (!recognizedHeaders.includes(param) && !BASE_PROCESSED[family].includes(param)) throw new JWTError(`Unprocessed critical header parameters: ${param}`, `ERR_${family}_INVALID`);
+		if (!Object.hasOwn(protectedHeader, param)) throw new JWTError(`Critical header parameter ${quoteTokenValue(param)} is missing from the protected header.`, `ERR_${family}_INVALID`);
+		if (!recognizedHeaders.includes(param) && !BASE_PROCESSED[family].includes(param)) throw new JWTError(`Unprocessed critical header parameters: ${quoteTokenValue(param)}`, `ERR_${family}_INVALID`);
 	}
 }
-export { JWTError, applyTypDefault, assertClaimValidationOptions, assertCritShape, assertCryptoKey, assertPlainObject, assertStringList, base64Decode, base64Encode, base64Parse, base64Stringify, base64UrlDecode, base64UrlEncode, base64UrlParse, base64UrlStringify, computeDurationInSeconds, computeJwtTimeClaims, concatUint8Arrays, expiredClaimMessage, getPlaintextBytes, isAsymmetricJWK, isCryptoKey, isCryptoKeyPair, isJWK, isJWKSet, isJWTContent, isJWTError, isPlainObject, isPrivateJWK, isPublicJWK, isSymmetricJWK, isUnsecureError, maybeArray, parsePayloadBytes, parsePayloadSegment, parsePayloadText, uint32be, validateCriticalHeadersJWE, validateCriticalHeadersJWS, validateJwtClaims };
+export { applyTypDefault, assertClaimValidationOptions, assertCritShape, assertCryptoKey, assertPlainObject, assertStringList, base64Decode, base64Encode, base64Parse, base64Stringify, base64UrlDecode, base64UrlEncode, base64UrlParse, base64UrlStringify, computeDurationInSeconds, computeJwtTimeClaims, concatUint8Arrays, expiredClaimMessage, getPlaintextBytes, hasSymmetricSecret, isAsymmetricJWK, isCryptoKey, isCryptoKeyPair, isJWK, isJWKSet, isJWTContent, isPlainObject, isPrivateJWK, isPublicJWK, isSymmetricJWK, maybeArray, parsePayloadBytes, parsePayloadSegment, parsePayloadText, quoteTokenValue, uint32be, validateCriticalHeadersJWE, validateCriticalHeadersJWS, validateJwtClaims };

package/dist/_chunks/libs/unsecure.d.mts

@@ -92,7 +92,8 @@ export declare function safeJsonParse<T = any>(json: string): T;
  * Remove prototype-pollution vectors from a plain record in-place.
  *
  * Strips own properties named `__proto__`, `prototype`, and `constructor`
- * through nested objects and arrays, enumerable or not. Cycle-safe.
+ * through nested objects and arrays — a named property hung on an array
+ * included — enumerable or not. Cycle-safe.
  *
  * Values are read from their property descriptors — array elements included —
  * so a getter is never invoked: an accessor is neither traversed nor removed
@@ -114,17 +115,36 @@ export declare function safeJsonParse<T = any>(json: string): T;
  *                         one.
  */
 export declare function sanitizeObject<T extends Record<string, unknown> | undefined>(obj: T): T;
+/** Options for {@link sanitizeObjectCopy}. */
+interface SanitizeCopyOptions {
+  /**
+   * Constructors whose instances the copy carries by reference, untouched.
+   * Everything the copy meets must be JSON-shaped — a plain object or an
+   * array — unless it is an instance (`instanceof`, so subclasses count) of
+   * one of these. By reference means unchanged *and* unsanitized: an instance
+   * listed here is trusted as the caller holds it.
+   *
+   * `instanceof` is bound to the realm the constructor came from, which is
+   * the realm the caller's own `Date` or `Map` belong to.
+   */
+  allowlist?: Iterable<abstract new (...args: never[]) => object>;
+}
 /**
  * Return a sanitized deep copy of `obj`. The input is never mutated.
  *
  * Dangerous keys (`__proto__`, `prototype`, `constructor`) are stripped from
  * every array and plain object reached. A plain object is one rooted on
- * `Object.prototype` or on `null`; copies of both are rooted on
- * `Object.prototype`. Every other value — `Date`, `Map`, `Set`, typed
- * arrays, `RegExp`, class instances, functions — is carried into the copy by
- * reference, exactly as {@link sanitizeObject} leaves it in place. By
- * reference means unchanged *and* unsanitized: what a `Map` or `Set` holds is
- * never read by either function.
+ * `null` or on an `Object.prototype` — this realm's or another's, so a value
+ * parsed inside a `vm` context or a frame is rebuilt like one parsed here;
+ * copies of both are rooted on this realm's `Object.prototype`.
+ *
+ * Anything else — a `Date`, `Map`, `Set`, typed array, `RegExp` or class
+ * instance — is refused: such a value is not the JSON shape this copy exists
+ * for, and carrying it through silently would report a sanitized copy that
+ * holds an unexamined object. Name the constructors you trust in
+ * `allowlist`, and their instances are carried into the copy by reference,
+ * or use {@link sanitizeObject} to walk a live object graph in place.
+ * Functions are values, not containers, and are carried by reference.
  *
  * Only own enumerable data properties are copied — the JSON shape. Accessors
  * are skipped rather than invoked, so the copy never runs caller code; an
@@ -135,10 +155,14 @@ export declare function sanitizeObject<T extends Record<string, unknown> | undef
  * Cycle-safe: circular references in the input are preserved in the output
  * (pointing at the copied node, not the original reference).
  *
- * Non-object / undefined inputs — and objects that are not arrays or plain
- * objects — are returned unchanged.
+ * Primitives and `undefined` are returned unchanged.
+ *
+ * @throws {UnsecureError} `INVALID_TYPE` if an object that is neither plain,
+ *                         an array nor an instance of an `allowlist` entry is
+ *                         met at any depth, or if `allowlist` holds something
+ *                         that is not a constructor.
  */
-export declare function sanitizeObjectCopy<T extends Record<string, unknown> | undefined>(obj: T): T;
+export declare function sanitizeObjectCopy<T>(obj: T, options?: SanitizeCopyOptions): T;
 /**
  * Shared UTF-8 `TextEncoder`. Encoding holds no state between calls, so a
  * single instance serves every caller.
@@ -156,18 +180,4 @@ export type BytesSource = ArrayBufferLike | ArrayBufferView<ArrayBufferLike>;
  * payload, not a signature to swallow.
  */
 export declare const textDecoder: TextDecoder;
-/**
- * Decoder output shape. Omit to mirror the input (`string` in → `string` out,
- * `Uint8Array` in → `Uint8Array` out). `"bytes"` aliases `"uint8array"`.
- */
-export type DecodeReturnAs = "string" | "uint8array" | "bytes";
-/** Shared `parse` options. */
-export interface DecodeOptions {
-  /** Output shape. Mirrors the input type when omitted. */
-  returnAs?: DecodeReturnAs;
-  /**
-   * Tolerate malformed input (skip/normalize) instead of throwing.
-   * @default false
-   */
-  loose?: boolean;
-}
+export {};