securl 1.10.0 → 1.11.1

package/CHANGELOG.md

@@ -6,11 +6,16 @@ The format is based on Keep a Changelog and this package follows Semantic Versio
 
 ## [Unreleased]
 
+## [1.11.1] - 2026-06-24
+
+### Changed
+- Updated `node-html-parser` to 8.0.3, replacing the retired entity decoder while preserving the existing parsing API and Node 22 runtime floor.
+
+## [1.11.0] - 2026-06-20
+
 ### Added
-- Added `buildVendorExposureBrief()` for compact vendor and supply-chain exposure summaries covering visible third-party providers, data-flow categories, SRI gaps, priority vendors, and next actions.
-- Added `vendorExposure` to analysis results and the `securl/vendor-exposure` package export for SDK consumers.
-- Added `buildExposureBrief()` for compact outside-observer action briefs covering public entry points, sensitive exposures, trust gaps, abuse indicators, third-party risk, AI surface signals, and next actions.
-- Added `exposureBrief` to analysis results and the `securl/exposure-brief` package export for SDK consumers.
+- Added a bounded declarative observation policy engine, maintained baseline policy, validation helper, and `securl/observation-policy` export.
+- Added `diffObservationLedgers()` and `securl/observation-drift` for deterministic observation-level regression and improvement classification.
 
 ## [1.10.0] - 2026-06-20
 
@@ -18,6 +23,29 @@ The format is based on Keep a Changelog and this package follows Semantic Versio
 - Added `buildObservationLedger()` and the `securl/observations` package export for stable, source-aware posture observations.
 - Added `observationLedger` to completed analysis results with deterministic IDs, confidence, status, and freshness metadata.
 
+## [1.9.0] - 2026-06-15
+
+### Added
+- Added `scanLiveCertificate()` and the `securl/live-certificate` package export for bounded TLS handshake-only certificate reads.
+- Added certificate chain, protocol, key-strength, and expiry metadata for lightweight certificate clients.
+
+## [1.8.0] - 2026-06-15
+
+### Added
+- Added `buildActionPlan()` and the `securl/action-plan` package export for prioritized owner, effort, and impact-ranked remediation actions.
+
+## [1.7.0] - 2026-06-15
+
+### Added
+- Added `buildVendorExposureBrief()` for compact vendor and supply-chain exposure summaries covering visible third-party providers, data-flow categories, SRI gaps, priority vendors, and next actions.
+- Added `vendorExposure` to analysis results and the `securl/vendor-exposure` package export for SDK consumers.
+
+## [1.6.0] - 2026-06-15
+
+### Added
+- Added `buildExposureBrief()` for compact outside-observer action briefs covering public entry points, sensitive exposures, trust gaps, abuse indicators, third-party risk, AI surface signals, and next actions.
+- Added `exposureBrief` to analysis results and the `securl/exposure-brief` package export for SDK consumers.
+
 ## [1.5.1] - 2026-06-15
 
 ### Changed

package/README.md

@@ -227,6 +227,10 @@ console.log(ledger.summary, ledger.observations);
 
 Observation IDs are deterministic across scans for the same subject and signal, making the ledger suitable for change detection without exposing backend job metadata.
 
+Version `1.11.0+` adds `diffObservationLedgers(current, previous)` from `securl/observation-drift` to classify observation-level regressions, improvements, and neutral changes.
+
+Use `evaluateObservationPolicy({ ledger, drift, policy })` from `securl/observation-policy` to apply bounded declarative rules. Rules can select an exact observation kind, kind prefix, or category, then assert equality, membership, or numeric thresholds against current observations or changes. `DEFAULT_OBSERVATION_POLICY` provides a maintained baseline for certificate validity/window, HSTS, CSP, DMARC, and critical regressions.
+
 ### 9. Evidence-backed remediation plans
 
 Version `1.4.0+` includes a remediation plan helper that turns score drivers and findings into prioritized, owner-aware fix guidance. Findings can also carry structured evidence references so clients can show why a finding was raised.
@@ -339,6 +343,8 @@ Primary exports:
 - `buildActionPlan(result)` - turn remediation, score drivers, exposure, and vendor context into prioritized fix actions.
 - `scanLiveCertificate(url)` - perform a TLS handshake-only certificate read for lightweight cert monitoring.
 - `buildObservationLedger(result)` - produce stable source, confidence, status, and freshness-aware posture observations.
+- `diffObservationLedgers(current, previous)` - compare stable observations and classify their operational impact.
+- `evaluateObservationPolicy({ ledger, drift, policy })` - evaluate bounded declarative posture and change rules.
 - `buildPostureDriftReportFromSnapshots(current, previous)` - produce a complete scan-to-scan drift report for monitoring, alerting, and history views.
 - `buildPostureRemediationPlan(result)` - generate prioritized, owner-aware remediation actions from findings and score drivers.
 - `attachIssueEvidence(result)` - add structured evidence references to findings without changing their existing fields.
@@ -351,6 +357,8 @@ Package subpath exports:
 - `securl/action-plan`
 - `securl/live-certificate`
 - `securl/observations`
+- `securl/observation-drift`
+- `securl/observation-policy`
 - `securl/posture-drift`
 - `securl/remediation-plan`
 - `securl/risk-events`

package/RELEASING.md

@@ -21,14 +21,19 @@ git diff --name-status securl-v$(node -p "require('./packages/core/package.json'
 3. Run:
    - `npm run release:core:check`
 4. Review the dry-run tarball contents.
-5. Confirm `NPM_TOKEN` is present in GitHub repository secrets.
+5. Confirm npm Trusted Publishing is configured for this package:
+   - provider: GitHub Actions
+   - organization: `this-is-securl`
+   - repository: `securl`
+   - workflow filename: `publish-core-package.yml`
+   - allowed action: `npm publish`
 
 ## Release steps
 
 1. Commit the version/changelog update.
 2. Tag the release using `securl-v<version>`, for example `securl-v1.4.1`.
 3. Push the tag.
-4. Let `.github/workflows/publish-core-package.yml` publish the package.
+4. Let `.github/workflows/publish-core-package.yml` publish the package through short-lived npm OIDC credentials.
 
 ## Post-release
 

package/dist/index.d.ts

@@ -12,6 +12,8 @@ export declare const analyzeTarget: typeof analyzeUrl;
 export { formatErrorMessage };
 export { buildCompromiseSignals, emptyCompromiseSignals } from "./compromiseSignals.js";
 export { buildObservationLedger } from "./observations.js";
+export { diffObservationLedgers } from "./observationDrift.js";
+export { DEFAULT_OBSERVATION_POLICY, evaluateObservationPolicy, validateObservationPolicy } from "./observationPolicy.js";
 export { buildActionPlan } from "./actionPlan.js";
 export { scanLiveCertificate } from "./certificate.js";
 export { buildExposureBrief } from "./exposureBrief.js";

package/dist/index.js

@@ -1053,6 +1053,8 @@ export const analyzeTarget = analyzeUrl;
 export { formatErrorMessage };
 export { buildCompromiseSignals, emptyCompromiseSignals } from "./compromiseSignals.js";
 export { buildObservationLedger } from "./observations.js";
+export { diffObservationLedgers } from "./observationDrift.js";
+export { DEFAULT_OBSERVATION_POLICY, evaluateObservationPolicy, validateObservationPolicy } from "./observationPolicy.js";
 export { buildActionPlan } from "./actionPlan.js";
 export { scanLiveCertificate } from "./certificate.js";
 export { buildExposureBrief } from "./exposureBrief.js";

package/dist/observationDrift.d.ts

@@ -0,0 +1,2 @@
+import type { ObservationDriftReport, ObservationLedger } from "./types.js";
+export declare function diffObservationLedgers(current: ObservationLedger, previous: ObservationLedger): ObservationDriftReport;

package/dist/observationDrift.js

@@ -0,0 +1,152 @@
+import { createHash } from "node:crypto";
+const STATUS_RANK = {
+    unavailable: 0,
+    missing: 1,
+    inferred: 2,
+    observed: 3,
+};
+const CRITICAL_KINDS = new Set([
+    "tls.certificate.valid",
+    "email.dmarc",
+    "http.header.strict-transport-security",
+    "http.header.content-security-policy",
+]);
+function equalValue(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
+function certificateBand(days) {
+    if (days < 0)
+        return 0;
+    if (days <= 7)
+        return 1;
+    if (days <= 14)
+        return 2;
+    if (days <= 30)
+        return 3;
+    return 4;
+}
+function impactFor(previous, current) {
+    if (!previous && current) {
+        return current.status === "missing" || current.status === "unavailable" ? "regression" : "change";
+    }
+    if (previous && !current) {
+        return previous.status === "missing" || previous.status === "unavailable" ? "improvement" : "regression";
+    }
+    if (!previous || !current)
+        return "change";
+    if (STATUS_RANK[current.status] < STATUS_RANK[previous.status])
+        return "regression";
+    if (STATUS_RANK[current.status] > STATUS_RANK[previous.status])
+        return "improvement";
+    if (current.kind === "tls.certificate.days_remaining"
+        && typeof previous.value === "number"
+        && typeof current.value === "number") {
+        const previousBand = certificateBand(previous.value);
+        const currentBand = certificateBand(current.value);
+        if (currentBand < previousBand)
+            return "regression";
+        if (currentBand > previousBand || current.value > previous.value + 7)
+            return "improvement";
+        return "change";
+    }
+    if (current.kind === "tls.certificate.valid"
+        && typeof previous.value === "boolean"
+        && typeof current.value === "boolean") {
+        return current.value ? "improvement" : "regression";
+    }
+    return "change";
+}
+function severityFor(kind, impact, current) {
+    if (impact !== "regression")
+        return "info";
+    if (kind === "tls.certificate.valid" && current?.value === false)
+        return "critical";
+    if (CRITICAL_KINDS.has(kind) && (current?.status === "missing" || current?.status === "unavailable"))
+        return "critical";
+    if (kind === "tls.certificate.days_remaining" && typeof current?.value === "number" && current.value <= 14)
+        return "critical";
+    return "warning";
+}
+function changeId(observationId, type) {
+    return `chg_${createHash("sha256").update(`${observationId}\u0000${type}`).digest("hex").slice(0, 20)}`;
+}
+function summaryFor(type, previous, current) {
+    const label = current?.kind ?? previous?.kind ?? "observation";
+    if (type === "added")
+        return `${label} was newly detected.`;
+    if (type === "removed")
+        return `${label} is no longer detected.`;
+    if (type === "status_changed")
+        return `${label} changed from ${previous?.status} to ${current?.status}.`;
+    if (type === "confidence_changed")
+        return `${label} confidence changed from ${previous?.confidence} to ${current?.confidence}.`;
+    return `${label} changed from ${JSON.stringify(previous?.value)} to ${JSON.stringify(current?.value)}.`;
+}
+function buildChange(type, previous, current) {
+    const observation = current ?? previous;
+    if (!observation)
+        throw new Error("Observation change requires a current or previous value.");
+    const impact = impactFor(previous, current);
+    return {
+        id: changeId(observation.id, type),
+        observationId: observation.id,
+        type,
+        impact,
+        severity: severityFor(observation.kind, impact, current),
+        category: observation.category,
+        kind: observation.kind,
+        subject: observation.subject,
+        previous,
+        current,
+        summary: summaryFor(type, previous, current),
+    };
+}
+export function diffObservationLedgers(current, previous) {
+    const currentById = new Map(current.observations.map((observation) => [observation.id, observation]));
+    const previousById = new Map(previous.observations.map((observation) => [observation.id, observation]));
+    const changes = [];
+    for (const observation of current.observations) {
+        const before = previousById.get(observation.id) ?? null;
+        if (!before) {
+            changes.push(buildChange("added", null, observation));
+            continue;
+        }
+        if (before.status !== observation.status)
+            changes.push(buildChange("status_changed", before, observation));
+        if (!equalValue(before.value, observation.value))
+            changes.push(buildChange("value_changed", before, observation));
+        if (before.confidence !== observation.confidence)
+            changes.push(buildChange("confidence_changed", before, observation));
+    }
+    for (const observation of previous.observations) {
+        if (!currentById.has(observation.id))
+            changes.push(buildChange("removed", observation, null));
+    }
+    const severityRank = { critical: 3, warning: 2, info: 1 };
+    changes.sort((left, right) => severityRank[right.severity] - severityRank[left.severity] || left.id.localeCompare(right.id));
+    const regressions = changes.filter((change) => change.impact === "regression").length;
+    const improvements = changes.filter((change) => change.impact === "improvement").length;
+    const bySeverity = { info: 0, warning: 0, critical: 0 };
+    const byCategory = {};
+    for (const change of changes) {
+        bySeverity[change.severity] += 1;
+        byCategory[change.category] = (byCategory[change.category] ?? 0) + 1;
+    }
+    return {
+        version: "1.0",
+        target: current.target,
+        comparedAt: current.generatedAt,
+        previousObservedAt: previous.generatedAt,
+        currentObservedAt: current.generatedAt,
+        changes,
+        summary: {
+            direction: regressions ? "regressed" : improvements ? "improved" : changes.length ? "changed" : "unchanged",
+            total: changes.length,
+            regressions,
+            improvements,
+            neutralChanges: changes.length - regressions - improvements,
+            bySeverity,
+            byCategory,
+        },
+    };
+}

package/dist/observationPolicy.d.ts

@@ -0,0 +1,8 @@
+import type { ObservationDriftReport, ObservationLedger, ObservationPolicy, ObservationPolicyEvaluation } from "./types.js";
+export declare const DEFAULT_OBSERVATION_POLICY: ObservationPolicy;
+export declare function validateObservationPolicy(value: unknown): ObservationPolicy;
+export declare function evaluateObservationPolicy({ ledger, drift, policy, }: {
+    ledger: ObservationLedger;
+    drift?: ObservationDriftReport | null;
+    policy?: ObservationPolicy;
+}): ObservationPolicyEvaluation;

package/dist/observationPolicy.js

@@ -0,0 +1,226 @@
+import { createHash } from "node:crypto";
+const MAX_RULES = 25;
+const VALID_OPERATORS = new Set(["eq", "neq", "in", "gte", "lte"]);
+const VALID_SEVERITIES = new Set(["info", "warning", "critical"]);
+const VALID_SCOPES = new Set(["observation", "change"]);
+const VALID_FIELDS = new Set(["status", "value", "confidence", "impact", "severity", "type"]);
+const VALID_CATEGORIES = new Set(["transport", "header", "certificate", "dns", "email", "infrastructure", "technology", "trust", "availability"]);
+export const DEFAULT_OBSERVATION_POLICY = {
+    id: "securl-baseline-v1",
+    name: "SecURL baseline",
+    version: "1.0",
+    rules: [
+        {
+            id: "certificate-valid",
+            title: "Certificate must remain valid",
+            severity: "critical",
+            scope: "observation",
+            selector: { kind: "tls.certificate.valid" },
+            assertion: { field: "value", operator: "eq", value: true },
+            requireMatch: true,
+        },
+        {
+            id: "certificate-window",
+            title: "Certificate must have at least 14 days remaining",
+            severity: "critical",
+            scope: "observation",
+            selector: { kind: "tls.certificate.days_remaining" },
+            assertion: { field: "value", operator: "gte", value: 14 },
+            requireMatch: true,
+        },
+        {
+            id: "hsts-present",
+            title: "HSTS must be present",
+            severity: "warning",
+            scope: "observation",
+            selector: { kind: "http.header.strict-transport-security" },
+            assertion: { field: "status", operator: "eq", value: "observed" },
+            requireMatch: true,
+        },
+        {
+            id: "csp-present",
+            title: "Content Security Policy must be present",
+            severity: "warning",
+            scope: "observation",
+            selector: { kind: "http.header.content-security-policy" },
+            assertion: { field: "status", operator: "eq", value: "observed" },
+            requireMatch: true,
+        },
+        {
+            id: "dmarc-enforced",
+            title: "DMARC should be strong or monitored",
+            severity: "warning",
+            scope: "observation",
+            selector: { kind: "email.dmarc" },
+            assertion: { field: "value", operator: "in", value: ["strong", "watch"] },
+            requireMatch: true,
+        },
+        {
+            id: "critical-regression",
+            title: "Critical observation regressions are not allowed",
+            severity: "critical",
+            scope: "change",
+            selector: {},
+            assertion: { field: "severity", operator: "neq", value: "critical" },
+            requireMatch: false,
+        },
+    ],
+};
+function boundedText(value, field, max) {
+    if (typeof value !== "string" || !value.trim() || value.length > max) {
+        throw new Error(`Observation policy ${field} must be a non-empty string up to ${max} characters.`);
+    }
+    return value.trim();
+}
+export function validateObservationPolicy(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error("Observation policy must be an object.");
+    const input = value;
+    if (!Array.isArray(input.rules) || input.rules.length === 0 || input.rules.length > MAX_RULES) {
+        throw new Error(`Observation policy must contain between 1 and ${MAX_RULES} rules.`);
+    }
+    const seen = new Set();
+    const rules = input.rules.map((rawRule) => {
+        if (!rawRule || typeof rawRule !== "object" || Array.isArray(rawRule))
+            throw new Error("Each observation policy rule must be an object.");
+        const rule = rawRule;
+        const id = boundedText(rule.id, "rule id", 64);
+        if (!/^[a-z0-9][a-z0-9._-]*$/i.test(id) || seen.has(id))
+            throw new Error(`Observation policy rule id is invalid or duplicated: ${id}.`);
+        seen.add(id);
+        if (!VALID_SEVERITIES.has(String(rule.severity)))
+            throw new Error(`Observation policy rule ${id} has an invalid severity.`);
+        if (!VALID_SCOPES.has(String(rule.scope)))
+            throw new Error(`Observation policy rule ${id} has an invalid scope.`);
+        const selector = rule.selector && typeof rule.selector === "object" && !Array.isArray(rule.selector)
+            ? rule.selector
+            : {};
+        const assertion = rule.assertion && typeof rule.assertion === "object" && !Array.isArray(rule.assertion)
+            ? rule.assertion
+            : null;
+        if (!assertion || !VALID_FIELDS.has(String(assertion.field)) || !VALID_OPERATORS.has(String(assertion.operator))) {
+            throw new Error(`Observation policy rule ${id} has an invalid assertion.`);
+        }
+        if (selector.category !== undefined && !VALID_CATEGORIES.has(String(selector.category))) {
+            throw new Error(`Observation policy rule ${id} has an invalid selector category.`);
+        }
+        if (rule.scope === "observation" && ["impact", "severity", "type"].includes(String(assertion.field))) {
+            throw new Error(`Observation policy rule ${id} uses a change-only field for an observation rule.`);
+        }
+        if (rule.scope === "change" && ["status", "confidence"].includes(String(assertion.field))) {
+            throw new Error(`Observation policy rule ${id} uses an observation-only field for a change rule.`);
+        }
+        if (assertion.operator === "in" && !Array.isArray(assertion.value))
+            throw new Error(`Observation policy rule ${id} requires an array value for in.`);
+        if ((assertion.operator === "gte" || assertion.operator === "lte") && typeof assertion.value !== "number") {
+            throw new Error(`Observation policy rule ${id} requires a numeric assertion value.`);
+        }
+        return {
+            id,
+            title: boundedText(rule.title, `rule ${id} title`, 160),
+            ...(typeof rule.description === "string" ? { description: rule.description.trim().slice(0, 500) } : {}),
+            enabled: rule.enabled !== false,
+            severity: rule.severity,
+            scope: rule.scope,
+            selector: {
+                ...(typeof selector.kind === "string" ? { kind: selector.kind.slice(0, 160) } : {}),
+                ...(typeof selector.kindPrefix === "string" ? { kindPrefix: selector.kindPrefix.slice(0, 160) } : {}),
+                ...(typeof selector.category === "string" ? { category: selector.category } : {}),
+            },
+            assertion: {
+                field: assertion.field,
+                operator: assertion.operator,
+                value: assertion.value,
+            },
+            requireMatch: rule.requireMatch === true,
+        };
+    });
+    return {
+        id: boundedText(input.id, "id", 64),
+        name: boundedText(input.name, "name", 120),
+        version: boundedText(input.version, "version", 32),
+        rules,
+    };
+}
+function matchesSelector(entity, rule) {
+    const { selector } = rule;
+    return (!selector.kind || entity.kind === selector.kind)
+        && (!selector.kindPrefix || entity.kind.startsWith(selector.kindPrefix))
+        && (!selector.category || entity.category === selector.category);
+}
+function actualValue(entity, field) {
+    if (field === "value")
+        return "current" in entity ? entity.current?.value ?? null : entity.value;
+    return entity[field] ?? null;
+}
+function assertionPasses(actual, rule) {
+    const { operator, value } = rule.assertion;
+    if (operator === "eq")
+        return JSON.stringify(actual) === JSON.stringify(value);
+    if (operator === "neq")
+        return JSON.stringify(actual) !== JSON.stringify(value);
+    if (operator === "in")
+        return Array.isArray(value) && value.some((candidate) => JSON.stringify(candidate) === JSON.stringify(actual));
+    if (operator === "gte")
+        return typeof actual === "number" && typeof value === "number" && actual >= value;
+    if (operator === "lte")
+        return typeof actual === "number" && typeof value === "number" && actual <= value;
+    return false;
+}
+function violationId(ruleId, entityId) {
+    return `pol_${createHash("sha256").update(`${ruleId}\u0000${entityId}`).digest("hex").slice(0, 20)}`;
+}
+function violationFor(rule, entity) {
+    const actual = entity ? actualValue(entity, rule.assertion.field) : null;
+    const isChange = entity && "observationId" in entity;
+    const entityId = entity?.id ?? "missing";
+    return {
+        id: violationId(rule.id, entityId),
+        ruleId: rule.id,
+        title: rule.title,
+        severity: rule.severity,
+        scope: rule.scope,
+        observationId: isChange ? entity.observationId : entity?.id ?? null,
+        changeId: isChange ? entity.id : null,
+        kind: entity?.kind ?? rule.selector.kind ?? rule.selector.kindPrefix ?? null,
+        subject: entity?.subject ?? null,
+        expected: rule.assertion,
+        actual: actual,
+        summary: entity
+            ? `${rule.title}: ${rule.assertion.field} ${rule.assertion.operator} ${JSON.stringify(rule.assertion.value)} was not satisfied.`
+            : `${rule.title}: no matching observation was available.`,
+    };
+}
+export function evaluateObservationPolicy({ ledger, drift = null, policy = DEFAULT_OBSERVATION_POLICY, }) {
+    const normalized = validateObservationPolicy(policy);
+    const violations = [];
+    const enabledRules = normalized.rules.filter((rule) => rule.enabled !== false);
+    for (const rule of enabledRules) {
+        const source = rule.scope === "change" ? drift?.changes ?? [] : ledger.observations;
+        const matches = source.filter((entity) => matchesSelector(entity, rule));
+        if (!matches.length && rule.requireMatch)
+            violations.push(violationFor(rule, null));
+        for (const entity of matches) {
+            if (!assertionPasses(actualValue(entity, rule.assertion.field), rule))
+                violations.push(violationFor(rule, entity));
+        }
+    }
+    const bySeverity = { info: 0, warning: 0, critical: 0 };
+    for (const violation of violations)
+        bySeverity[violation.severity] += 1;
+    const highestSeverity = bySeverity.critical ? "critical" : bySeverity.warning ? "warning" : bySeverity.info ? "info" : null;
+    return {
+        version: "1.0",
+        policy: { id: normalized.id, name: normalized.name, version: normalized.version },
+        target: ledger.target,
+        evaluatedAt: ledger.generatedAt,
+        passed: violations.length === 0,
+        violations,
+        summary: {
+            rulesEvaluated: enabledRules.length,
+            violations: violations.length,
+            bySeverity,
+            highestSeverity,
+        },
+    };
+}

package/dist/types.d.ts

@@ -843,6 +843,100 @@ export interface ObservationLedger {
         highConfidence: number;
     };
 }
+export type ObservationChangeType = "added" | "removed" | "status_changed" | "value_changed" | "confidence_changed";
+export type ObservationChangeImpact = "regression" | "improvement" | "change";
+export type ObservationChangeSeverity = "info" | "warning" | "critical";
+export interface ObservationChange {
+    id: string;
+    observationId: string;
+    type: ObservationChangeType;
+    impact: ObservationChangeImpact;
+    severity: ObservationChangeSeverity;
+    category: ObservationCategory;
+    kind: string;
+    subject: string;
+    previous: PostureObservation | null;
+    current: PostureObservation | null;
+    summary: string;
+}
+export interface ObservationDriftReport {
+    version: "1.0";
+    target: string;
+    comparedAt: string;
+    previousObservedAt: string;
+    currentObservedAt: string;
+    changes: ObservationChange[];
+    summary: {
+        direction: "regressed" | "improved" | "changed" | "unchanged";
+        total: number;
+        regressions: number;
+        improvements: number;
+        neutralChanges: number;
+        bySeverity: Record<ObservationChangeSeverity, number>;
+        byCategory: Partial<Record<ObservationCategory, number>>;
+    };
+}
+export type ObservationPolicySeverity = "info" | "warning" | "critical";
+export type ObservationPolicyScope = "observation" | "change";
+export type ObservationPolicyField = "status" | "value" | "confidence" | "impact" | "severity" | "type";
+export type ObservationPolicyOperator = "eq" | "neq" | "in" | "gte" | "lte";
+export interface ObservationPolicyRule {
+    id: string;
+    title: string;
+    description?: string;
+    enabled?: boolean;
+    severity: ObservationPolicySeverity;
+    scope: ObservationPolicyScope;
+    selector: {
+        kind?: string;
+        kindPrefix?: string;
+        category?: ObservationCategory;
+    };
+    assertion: {
+        field: ObservationPolicyField;
+        operator: ObservationPolicyOperator;
+        value: ObservationValue | ObservationChangeImpact | ObservationChangeSeverity | ObservationChangeType;
+    };
+    requireMatch?: boolean;
+}
+export interface ObservationPolicy {
+    id: string;
+    name: string;
+    version: string;
+    rules: ObservationPolicyRule[];
+}
+export interface ObservationPolicyViolation {
+    id: string;
+    ruleId: string;
+    title: string;
+    severity: ObservationPolicySeverity;
+    scope: ObservationPolicyScope;
+    observationId: string | null;
+    changeId: string | null;
+    kind: string | null;
+    subject: string | null;
+    expected: ObservationPolicyRule["assertion"];
+    actual: ObservationValue;
+    summary: string;
+}
+export interface ObservationPolicyEvaluation {
+    version: "1.0";
+    policy: {
+        id: string;
+        name: string;
+        version: string;
+    };
+    target: string;
+    evaluatedAt: string;
+    passed: boolean;
+    violations: ObservationPolicyViolation[];
+    summary: {
+        rulesEvaluated: number;
+        violations: number;
+        bySeverity: Record<ObservationPolicySeverity, number>;
+        highestSeverity: ObservationPolicySeverity | null;
+    };
+}
 export interface AnalysisResult {
     inputUrl: string;
     normalizedUrl: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securl",
-  "version": "1.10.0",
+  "version": "1.11.1",
   "type": "module",
   "description": "Passive external security posture scanner for public URLs and web services.",
   "author": {
@@ -85,6 +85,14 @@
     "./observations": {
       "types": "./dist/observations.d.ts",
       "default": "./dist/observations.js"
+    },
+    "./observation-drift": {
+      "types": "./dist/observationDrift.d.ts",
+      "default": "./dist/observationDrift.js"
+    },
+    "./observation-policy": {
+      "types": "./dist/observationPolicy.d.ts",
+      "default": "./dist/observationPolicy.js"
     }
   },
   "files": [
@@ -121,6 +129,6 @@
   ],
   "license": "MIT",
   "dependencies": {
-    "node-html-parser": "^7.1.0"
+    "node-html-parser": "^8.0.3"
   }
 }