@prenta/core 0.118.0

package/dist/security/index.d.ts

@@ -0,0 +1,40 @@
+export { checkAccess, getPermissionsForRole, filterFieldsByRole, filterWritableFields, applyFieldAccess, WRITE_PASSTHROUGH_KEYS, } from './access.js';
+export type { Role, Permission, FieldAccessUser } from './access.js';
+export { generateToken as generateCsrfToken, validateToken as validateCsrfToken } from './csrf.js';
+export { createRateLimiter } from './rate-limit.js';
+export type { RateLimiter, RateLimitConfig, RateLimitResult } from './rate-limit.js';
+export { sanitizeHtml, stripHtml } from './sanitize.js';
+export { validateMimeType, checkMagicBytes } from './upload.js';
+export { validateWebhookUrl, resolveAndCheck } from './webhook.js';
+export { logEvent, getAuditLog } from './audit.js';
+export type { AuditEntry, AuditLogQuery, AuditLogResult } from './audit.js';
+export { getSecurityHeaders } from './headers.js';
+export type { SecurityHeadersConfig } from './headers.js';
+export { applySecurityMiddleware } from './middleware.js';
+export type { SecurityMiddlewareConfig, SecurityMiddlewareResult } from './middleware.js';
+export { checkBreached } from './breach-check.js';
+export { detectLoginAnomaly, checkBruteForce } from './anomaly-detection.js';
+export type { LoginAttempt, AnomalyResult } from './anomaly-detection.js';
+export { requiresReauth, verifyReauth } from './reauth.js';
+export type { ReauthConfig, ReauthContext } from './reauth.js';
+export { isIpAllowed } from './ip-allowlist.js';
+export { enforceSessionLimits } from './session-limits.js';
+export type { SessionInfo, SessionLimitConfig } from './session-limits.js';
+export { encryptField, decryptField } from './encrypted-fields.js';
+export { getCorsHeaders } from './cors.js';
+export type { CorsConfig } from './cors.js';
+export { generateCspNonce, buildCspHeader } from './csp-nonces.js';
+export { generateSecurityTxt } from './security-txt.js';
+export type { SecurityTxtConfig } from './security-txt.js';
+export { generateApiKey, validateApiKeyScope } from './api-key-enhanced.js';
+export type { ApiKeyScope, EnhancedApiKeyConfig } from './api-key-enhanced.js';
+export { verifyCaptcha, getCaptchaConfig, getPublicCaptchaConfig, isCaptchaProviderError, } from './captcha.js';
+export type { CaptchaConfig, CaptchaProvider, CaptchaProviderErrorPolicy, CaptchaVerifyResult, PublicCaptchaConfig, } from './captcha.js';
+export { getClientIp, isResolvedIp } from './client-ip.js';
+export type { TrustedIpOptions } from './client-ip.js';
+export { safeFetch, SsrfBlockedError } from './safe-fetch.js';
+export type { SafeFetchOptions } from './safe-fetch.js';
+export { encryptSecret, decryptSecret, isEncrypted, encryptStringArray, decryptStringArray, } from './secret-storage.js';
+export { redactSecrets } from './redact.js';
+export { INTERNAL_DATA_KEYS, isInternalDataKey, stripInternalDataKeys } from './internal-keys.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/security/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":"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"}

package/dist/security/index.js

@@ -0,0 +1,26 @@
+export { checkAccess, getPermissionsForRole, filterFieldsByRole, filterWritableFields, applyFieldAccess, WRITE_PASSTHROUGH_KEYS, } from './access.js';
+export { generateToken as generateCsrfToken, validateToken as validateCsrfToken } from './csrf.js';
+export { createRateLimiter } from './rate-limit.js';
+export { sanitizeHtml, stripHtml } from './sanitize.js';
+export { validateMimeType, checkMagicBytes } from './upload.js';
+export { validateWebhookUrl, resolveAndCheck } from './webhook.js';
+export { logEvent, getAuditLog } from './audit.js';
+export { getSecurityHeaders } from './headers.js';
+export { applySecurityMiddleware } from './middleware.js';
+export { checkBreached } from './breach-check.js';
+export { detectLoginAnomaly, checkBruteForce } from './anomaly-detection.js';
+export { requiresReauth, verifyReauth } from './reauth.js';
+export { isIpAllowed } from './ip-allowlist.js';
+export { enforceSessionLimits } from './session-limits.js';
+export { encryptField, decryptField } from './encrypted-fields.js';
+export { getCorsHeaders } from './cors.js';
+export { generateCspNonce, buildCspHeader } from './csp-nonces.js';
+export { generateSecurityTxt } from './security-txt.js';
+export { generateApiKey, validateApiKeyScope } from './api-key-enhanced.js';
+export { verifyCaptcha, getCaptchaConfig, getPublicCaptchaConfig, isCaptchaProviderError, } from './captcha.js';
+export { getClientIp, isResolvedIp } from './client-ip.js';
+export { safeFetch, SsrfBlockedError } from './safe-fetch.js';
+export { encryptSecret, decryptSecret, isEncrypted, encryptStringArray, decryptStringArray, } from './secret-storage.js';
+export { redactSecrets } from './redact.js';
+export { INTERNAL_DATA_KEYS, isInternalDataKey, stripInternalDataKeys } from './internal-keys.js';
+//# sourceMappingURL=index.js.map

package/dist/security/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/security/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,WAAW,EACX,qBAAqB,EACrB,kBAAkB,EAClB,oBAAoB,EACpB,gBAAgB,EAChB,sBAAsB,GACvB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,aAAa,IAAI,iBAAiB,EAAE,aAAa,IAAI,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAElG,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAA;AAGnD,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAA;AAEvD,OAAO,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAE/D,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,cAAc,CAAA;AAElE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGlD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAA;AAGjD,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AAGzD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAA;AAEjD,OAAO,EAAE,kBAAkB,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AAG5E,OAAO,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAG1D,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,OAAO,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAA;AAG1D,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAElE,OAAO,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAG1C,OAAO,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AAElE,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AAGvD,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAA;AAG3E,OAAO,EACL,aAAa,EACb,gBAAgB,EAChB,sBAAsB,EACtB,sBAAsB,GACvB,MAAM,cAAc,CAAA;AASrB,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAA;AAG1D,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,iBAAiB,CAAA;AAG7D,OAAO,EACL,aAAa,EACb,aAAa,EACb,WAAW,EACX,kBAAkB,EAClB,kBAAkB,GACnB,MAAM,qBAAqB,CAAA;AAE5B,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA"}

package/dist/security/internal-keys.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Centralised list of "system" keys that may appear inside `Document.data`
+ * but are managed by the CMS rather than the user. Anything here is:
+ *
+ *  - stripped from API responses (so internal scoring data isn't leaked)
+ *  - allowed through field-level write access checks (so plugins can
+ *    set them even when the field isn't declared in the collection)
+ *
+ * Keep this in lockstep with `actions.ts`/`access.ts` to avoid drift.
+ */
+export declare const INTERNAL_DATA_KEYS: Set<string>;
+export declare function isInternalDataKey(key: string): boolean;
+/** Return a shallow copy of `data` with all internal/system keys removed. */
+export declare function stripInternalDataKeys<T extends Record<string, unknown>>(data: T): T;
+//# sourceMappingURL=internal-keys.d.ts.map

package/dist/security/internal-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-keys.d.ts","sourceRoot":"","sources":["../../src/security/internal-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,aAQ7B,CAAA;AAEF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAEtD;AAED,6EAA6E;AAC7E,wBAAgB,qBAAqB,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,CAAC,GAAG,CAAC,CAOnF"}

package/dist/security/internal-keys.js

@@ -0,0 +1,33 @@
+/**
+ * Centralised list of "system" keys that may appear inside `Document.data`
+ * but are managed by the CMS rather than the user. Anything here is:
+ *
+ *  - stripped from API responses (so internal scoring data isn't leaked)
+ *  - allowed through field-level write access checks (so plugins can
+ *    set them even when the field isn't declared in the collection)
+ *
+ * Keep this in lockstep with `actions.ts`/`access.ts` to avoid drift.
+ */
+export const INTERNAL_DATA_KEYS = new Set([
+    '_layout',
+    '_pageSettings',
+    '_aiScore',
+    '_embedding',
+    '_seoScore',
+    '_brandScore',
+    '_readabilityScore',
+]);
+export function isInternalDataKey(key) {
+    return key.startsWith('_') || INTERNAL_DATA_KEYS.has(key);
+}
+/** Return a shallow copy of `data` with all internal/system keys removed. */
+export function stripInternalDataKeys(data) {
+    const out = {};
+    for (const [key, value] of Object.entries(data)) {
+        if (isInternalDataKey(key))
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+//# sourceMappingURL=internal-keys.js.map

package/dist/security/internal-keys.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"internal-keys.js","sourceRoot":"","sources":["../../src/security/internal-keys.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,GAAG,CAAS;IAChD,SAAS;IACT,eAAe;IACf,UAAU;IACV,YAAY;IACZ,WAAW;IACX,aAAa;IACb,mBAAmB;CACpB,CAAC,CAAA;AAEF,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,OAAO,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,IAAI,kBAAkB,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;AAC3D,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,qBAAqB,CAAoC,IAAO;IAC9E,MAAM,GAAG,GAA4B,EAAE,CAAA;IACvC,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAChD,IAAI,iBAAiB,CAAC,GAAG,CAAC;YAAE,SAAQ;QACpC,GAAG,CAAC,GAAG,CAAC,GAAG,KAAK,CAAA;IAClB,CAAC;IACD,OAAO,GAAQ,CAAA;AACjB,CAAC"}

package/dist/security/ip-allowlist.d.ts

@@ -0,0 +1,15 @@
+/**
+ * IP allowlist matcher supporting both IPv4 and IPv6, including CIDR ranges.
+ *
+ * - Empty allowlist allows everything (the integrator opted out).
+ * - When the allowlist is non-empty, the literal `'unknown'` (the sentinel
+ *   returned by the trusted-IP resolver when no proxy header was present)
+ *   never matches.
+ * - IPv4 entries match IPv4 addresses (with optional `/n` CIDR mask, n=0..32).
+ * - IPv6 entries match IPv6 addresses (with optional `/n` CIDR mask, n=0..128).
+ *   Two IPv6 strings are equal when their canonical 16-byte form matches —
+ *   so `2001:db8::1` matches `2001:db8:0:0:0:0:0:1`.
+ * - Mapped IPv4-in-IPv6 addresses (`::ffff:1.2.3.4`) are normalised to IPv4.
+ */
+export declare function isIpAllowed(ip: string, allowlist: string[]): boolean;
+//# sourceMappingURL=ip-allowlist.d.ts.map

package/dist/security/ip-allowlist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip-allowlist.d.ts","sourceRoot":"","sources":["../../src/security/ip-allowlist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAcpE"}

package/dist/security/ip-allowlist.js

@@ -0,0 +1,141 @@
+/**
+ * IP allowlist matcher supporting both IPv4 and IPv6, including CIDR ranges.
+ *
+ * - Empty allowlist allows everything (the integrator opted out).
+ * - When the allowlist is non-empty, the literal `'unknown'` (the sentinel
+ *   returned by the trusted-IP resolver when no proxy header was present)
+ *   never matches.
+ * - IPv4 entries match IPv4 addresses (with optional `/n` CIDR mask, n=0..32).
+ * - IPv6 entries match IPv6 addresses (with optional `/n` CIDR mask, n=0..128).
+ *   Two IPv6 strings are equal when their canonical 16-byte form matches —
+ *   so `2001:db8::1` matches `2001:db8:0:0:0:0:0:1`.
+ * - Mapped IPv4-in-IPv6 addresses (`::ffff:1.2.3.4`) are normalised to IPv4.
+ */
+export function isIpAllowed(ip, allowlist) {
+    if (allowlist.length === 0)
+        return true;
+    if (!ip || ip === 'unknown')
+        return false;
+    const normalised = normaliseIp(ip);
+    for (const entry of allowlist) {
+        if (entry.includes('/')) {
+            if (isInCidr(normalised, entry))
+                return true;
+        }
+        else if (ipsEqual(normalised, normaliseIp(entry))) {
+            return true;
+        }
+    }
+    return false;
+}
+function ipsEqual(a, b) {
+    if (a === b)
+        return true;
+    // Compare IPv6 by canonical bytes so `2001:db8::1` === `2001:db8:0:0:0:0:0:1`.
+    if (a.includes(':') && b.includes(':')) {
+        const ca = canonicalIpv6(a);
+        const cb = canonicalIpv6(b);
+        return ca !== null && cb !== null && ca === cb;
+    }
+    return false;
+}
+function canonicalIpv6(ip) {
+    const bytes = ipv6ToBytes(ip);
+    if (!bytes)
+        return null;
+    let out = '';
+    for (let i = 0; i < 16; i++) {
+        out += (bytes[i] ?? 0).toString(16).padStart(2, '0');
+    }
+    return out;
+}
+function normaliseIp(ip) {
+    const trimmed = ip.trim();
+    // ::ffff:1.2.3.4 → 1.2.3.4
+    if (trimmed.toLowerCase().startsWith('::ffff:')) {
+        const v4 = trimmed.slice(7);
+        if (isValidIPv4(v4))
+            return v4;
+    }
+    return trimmed;
+}
+function isValidIPv4(s) {
+    const parts = s.split('.').map(Number);
+    return parts.length === 4 && parts.every((p) => Number.isInteger(p) && p >= 0 && p <= 255);
+}
+function isInCidr(ip, cidr) {
+    const [range, bitsStr] = cidr.split('/');
+    if (!range || !bitsStr)
+        return false;
+    const bits = parseInt(bitsStr, 10);
+    if (Number.isNaN(bits))
+        return false;
+    if (ip.includes(':') || range.includes(':')) {
+        return matchIpv6Cidr(ip, range, bits);
+    }
+    return matchIpv4Cidr(ip, range, bits);
+}
+function matchIpv4Cidr(ip, range, bits) {
+    if (bits < 0 || bits > 32)
+        return false;
+    const ipNum = ipv4ToNumber(ip);
+    const rangeNum = ipv4ToNumber(range);
+    if (ipNum === null || rangeNum === null)
+        return false;
+    if (bits === 0)
+        return true;
+    const mask = ~((1 << (32 - bits)) - 1) >>> 0;
+    return (ipNum & mask) === (rangeNum & mask);
+}
+function ipv4ToNumber(ip) {
+    if (!isValidIPv4(ip))
+        return null;
+    const parts = ip.split('.').map(Number);
+    return ((parts[0] << 24) | (parts[1] << 16) | (parts[2] << 8) | parts[3]) >>> 0;
+}
+function matchIpv6Cidr(ip, range, bits) {
+    if (bits < 0 || bits > 128)
+        return false;
+    const ipBytes = ipv6ToBytes(ip);
+    const rangeBytes = ipv6ToBytes(range);
+    if (!ipBytes || !rangeBytes)
+        return false;
+    let remaining = bits;
+    for (let i = 0; i < 16 && remaining > 0; i++) {
+        const take = Math.min(8, remaining);
+        const mask = (0xff << (8 - take)) & 0xff;
+        if ((ipBytes[i] & mask) !== (rangeBytes[i] & mask))
+            return false;
+        remaining -= take;
+    }
+    return true;
+}
+/** Expand the `::` shorthand and return 16 bytes; null when the input isn't a valid IPv6. */
+function ipv6ToBytes(ip) {
+    // Reject IPv4-mapped form for the IPv6 path; caller normalises ::ffff:x.x.x.x first.
+    if (ip.includes('.'))
+        return null;
+    const halves = ip.split('::');
+    if (halves.length > 2)
+        return null;
+    const left = halves[0] ? halves[0].split(':') : [];
+    const groups = halves.length === 2 ? fillGroups(left, halves[1] ? halves[1].split(':') : []) : left;
+    if (groups.length !== 8)
+        return null;
+    const bytes = new Uint8Array(16);
+    for (let i = 0; i < 8; i++) {
+        const value = parseInt(groups[i] || '0', 16);
+        if (Number.isNaN(value) || value < 0 || value > 0xffff)
+            return null;
+        bytes[i * 2] = (value >> 8) & 0xff;
+        bytes[i * 2 + 1] = value & 0xff;
+    }
+    return bytes;
+}
+function fillGroups(left, right) {
+    const fill = 8 - left.length - right.length;
+    if (fill < 0)
+        return [];
+    return [...left, ...new Array(fill).fill('0'), ...right];
+}
+//# sourceMappingURL=ip-allowlist.js.map

package/dist/security/ip-allowlist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip-allowlist.js","sourceRoot":"","sources":["../../src/security/ip-allowlist.ts"],"names":[],"mappings":"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"}

package/dist/security/ip-canon.d.ts

@@ -0,0 +1,71 @@
+/**
+ * IP canonicalization for SSRF defense.
+ *
+ * The previous regex-based approach in `webhook.ts` only matched the literal
+ * dotted-quad form. It missed every encoding that `getaddrinfo` (and therefore
+ * `fetch`) accepts:
+ *
+ *   - Decimal:        http://2130706433/        → 127.0.0.1
+ *   - Octal:          http://0177.0.0.1/        → 127.0.0.1
+ *   - Hex:            http://0x7f.0.0.1/        → 127.0.0.1
+ *   - Short-form:     http://127.1/             → 127.0.0.1
+ *   - IPv4-mapped v6: http://[::ffff:127.0.0.1] → 127.0.0.1
+ *   - IPv4-compat v6: http://[::127.0.0.1]      → 127.0.0.1
+ *
+ * This module canonicalizes any of those forms to a 4-octet IPv4 string (or
+ * a normalized 16-byte IPv6 address), then range-checks against a complete
+ * private/internal block list including AWS/GCP/Azure metadata endpoints and
+ * the carrier-grade NAT range.
+ */
+/**
+ * Result of {@link canonicalizeHostname}. There are exactly three valid
+ * shapes:
+ *
+ *  - **Valid IPv4 literal** — `isHostname=false`, `isValidIp=true`, `ipv4` set.
+ *  - **Valid IPv6 literal** — `isHostname=false`, `isValidIp=true`, `ipv6` set.
+ *  - **Hostname (DNS name)** — `isHostname=true`, `isValidIp=false`, neither
+ *    `ipv4` nor `ipv6` set.
+ *  - **Malformed IP literal** — `isHostname=false`, `isValidIp=false`, neither
+ *    IP field set. (Inputs that look like IP literals — e.g. contain `:` or
+ *    only digits and dots — but fail to parse cleanly.)
+ *
+ * SSRF gates MUST treat the malformed shape as "reject" rather than as
+ * "validated IP literal". Use `isValidIp` to distinguish the two `false`
+ * `isHostname` cases.
+ */
+export interface CanonicalizedHost {
+    /** Original hostname as it appeared in the URL. */
+    raw: string;
+    /** Canonical IPv4 dotted-quad string when the literal was IPv4 (in any form). */
+    ipv4?: string;
+    /** Canonical IPv6 hextet string when the literal was IPv6. */
+    ipv6?: string;
+    /** True when the input was a DNS name (not an IP literal in any form). */
+    isHostname: boolean;
+    /**
+     * True when the input parsed cleanly into a canonical IP address (`ipv4`
+     * or `ipv6` is set). False for both DNS hostnames and malformed IP-shaped
+     * strings. Callers performing a security check on the parsed IP MUST
+     * verify `isValidIp` before reading `ipv4` / `ipv6`.
+     */
+    isValidIp: boolean;
+}
+/**
+ * Canonicalize a URL hostname into either a normalized IP address or a
+ * passthrough hostname. Handles every IPv4 encoding accepted by `inet_aton`
+ * (decimal, octal, hex, short-form), IPv4-mapped IPv6, and bracketed IPv6.
+ */
+export declare function canonicalizeHostname(rawHostname: string): CanonicalizedHost;
+/**
+ * Returns the matching private/internal range when the canonicalized host is
+ * one, `null` when it's a safe public IP, or a "malformed" reason when the
+ * input claims to be an IP literal but didn't parse cleanly.
+ *
+ * Defense-in-depth: even if a caller forgets to gate on `isValidIp`, this
+ * function still fails closed on the malformed shape (`isHostname=false`
+ * with no `ipv4`/`ipv6`).
+ */
+export declare function isPrivateAddress(host: CanonicalizedHost): {
+    reason: string;
+} | null;
+//# sourceMappingURL=ip-canon.d.ts.map

package/dist/security/ip-canon.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ip-canon.d.ts","sourceRoot":"","sources":["../../src/security/ip-canon.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAiCH;;;;;;;;;;;;;;;GAeG;AACH,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,GAAG,EAAE,MAAM,CAAA;IACX,iFAAiF;IACjF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,0EAA0E;IAC1E,UAAU,EAAE,OAAO,CAAA;IACnB;;;;;OAKG;IACH,SAAS,EAAE,OAAO,CAAA;CACnB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,iBAAiB,CAmC3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,iBAAiB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA4BnF"}