standdown 0.1.0 → 0.2.0

package/dist/content.cjs

@@ -21,8 +21,24 @@ function detect(signals, policies) {
   }
   const advertiserHost = currentUrl.hostname.toLowerCase();
   const matched = [];
+  const selfExemptScopes = [];
   let selfMatch = false;
   for (const policy of policies) {
+    const disabledHostRule = (policy.detection.disableHosts ?? []).find(
+      (rule) => domainRuleMatchesUrl(rule, advertiserHost)
+    );
+    if (disabledHostRule) {
+      matched.push(
+        matchedRule(
+          policy,
+          "disabled-host",
+          `${disabledHostRule.kind}:${disabledHostRule.pattern}`,
+          advertiserHost,
+          disabledHostRule.comment ?? "host disabled for this network"
+        )
+      );
+      continue;
+    }
     const scopedSelfMatch = hasScopedSelfExemption(
       currentUrl,
       signals.selfPatterns,
@@ -36,6 +52,10 @@ function detect(signals, policies) {
       selfMatch = true;
     }
     if (scopedSelfMatch) {
+      selfExemptScopes.push({
+        policyId: policy.id,
+        networkId: policy.network.id
+      });
       continue;
     }
     matched.push(
@@ -48,7 +68,14 @@ function detect(signals, policies) {
     advertiserHost: matched[0].advertiserHost,
     reason: matched[0].reason
   } : void 0;
-  return strongest ? { matched, selfMatch, strongest } : { matched, selfMatch };
+  const base = { matched, selfMatch };
+  if (strongest) {
+    base.strongest = strongest;
+  }
+  if (selfExemptScopes.length > 0) {
+    base.selfExemptScopes = selfExemptScopes;
+  }
+  return base;
 }
 function classifyReferrer(signals, advertiserHost) {
   const candidate = signals.initiator ?? signals.referrer;
@@ -165,16 +192,19 @@ function matchedRule(policy, kind, rule, advertiserHost, reason) {
   };
 }
 function kindPriority(kind) {
-  if (kind === "redirect-domain") {
+  if (kind === "disabled-host") {
     return 0;
   }
-  if (kind === "landing-param") {
+  if (kind === "redirect-domain") {
     return 1;
   }
-  if (kind === "cookie") {
+  if (kind === "landing-param") {
     return 2;
   }
-  return 3;
+  if (kind === "cookie") {
+    return 3;
+  }
+  return 4;
 }
 function paramRuleMatches(rule, params) {
   return rule.anyOf.some(
@@ -286,6 +316,9 @@ function validatePolicy(value) {
   optionalArray(detection.initiatorRules, "policy.detection.initiatorRules").forEach(
     validateInitiatorRule
   );
+  optionalArray(detection.disableHosts, "policy.detection.disableHosts").forEach(
+    validateDomainRule
+  );
   const standdown = object(policy.standdown, "policy.standdown");
   literal(standdown.scope, "advertiser", "policy.standdown.scope");
   if (standdown.sessionRule !== "session-or-min" && standdown.sessionRule !== "inactivity-window") {
@@ -311,12 +344,6 @@ function validatePolicy(value) {
   if (activation.mode !== "user-click" && activation.mode !== "never") {
     throw new TypeError("policy.activation.mode is invalid");
   }
-  if (activation.maxPromptsPerJourney !== void 0) {
-    nonNegativeFiniteNumber(
-      activation.maxPromptsPerJourney,
-      "policy.activation.maxPromptsPerJourney"
-    );
-  }
   for (const referrerClass of optionalArray(
     activation.allowedReferrerClasses,
     "policy.activation.allowedReferrerClasses"
@@ -460,11 +487,13 @@ var StanddownSession = class {
   #store;
   #auditLog;
   #maxAuditEntries;
+  #selfExemptionScope;
   #readOnlyAuditLog = [];
   constructor(store, opts) {
     this.#store = store;
     this.#auditLog = opts?.auditLog ?? true;
     this.#maxAuditEntries = Math.max(0, opts?.maxAuditEntries ?? 1e3);
+    this.#selfExemptionScope = opts?.selfExemptionScope ?? "policy";
   }
   async ingest(signals, policies) {
     const advertiserHost = hostFromUrl2(signals.url);
@@ -490,38 +519,49 @@ var StanddownSession = class {
     }
     return this.#withState(signals.now, (state) => {
       pruneExpiredSessions(state, signals.now);
-      if (detection.strongest) {
-        const matchedPolicies = policiesForDetection(policies, detection);
+      let effective = detection;
+      if (this.#selfExemptionScope === "session" && advertiserHost) {
+        recordSessionExemptions(state, advertiserHost, detection, signals.now);
+        effective = applySessionExemptions(
+          advertiserHost,
+          detection,
+          state.exemptions?.[advertiserHost]
+        );
+      }
+      if (effective.strongest) {
+        const matchedPolicies = policiesForDetection(policies, effective);
         if (matchedPolicies.length === 0) {
           return {
             decision: failClosedDecision("matched-policy-missing"),
-            detection
+            detection: effective
           };
         }
         const record = upsertSessionRecord(
           state,
-          detection.strongest.advertiserHost,
-          detection.strongest.policyId,
+          effective.strongest.advertiserHost,
+          effective.strongest.policyId,
           matchedPolicies,
           signals.now
         );
         return {
           decision: decisionFromRecord(record, signals.now, {
-            reason: detection.strongest.reason,
+            reason: effective.strongest.reason,
             referrerClass: classifyReferrer(signals, record.advertiserHost)
           }),
-          detection
+          detection: effective
         };
       }
       const activeDecision = advertiserHost ? activeDecisionForHost(state, advertiserHost, signals.now) : void 0;
+      const sessionExempted = detection.strongest !== void 0 && effective.strongest === void 0;
       return {
         decision: activeDecision ?? {
           standDown: false,
-          reason: detection.selfMatch ? "self-exempted-no-active-standdown" : "no-active-standdown",
+          reason: sessionExempted ? "self-exempted-session" : detection.selfMatch ? "self-exempted-no-active-standdown" : "no-active-standdown",
           behaviors: [],
-          referrerClass: advertiserHost ? classifyReferrer(signals, advertiserHost) : "other"
+          referrerClass: advertiserHost ? classifyReferrer(signals, advertiserHost) : "other",
+          ...signals.signalCoverage === "partial" ? { degraded: true } : {}
         },
-        detection
+        detection: effective
       };
     }, "ingest");
   }
@@ -690,6 +730,66 @@ function upsertSessionRecord(state, advertiserHost, primaryPolicyId, policies, n
   state.sessions[key] = baseRecord;
   return baseRecord;
 }
+function recordSessionExemptions(state, advertiserHost, detection, now) {
+  const scopes = detection.selfExemptScopes;
+  if (!scopes || scopes.length === 0) {
+    return;
+  }
+  if (activeDecisionForHost(state, advertiserHost, now) !== void 0) {
+    return;
+  }
+  const key = normalizeHost(advertiserHost);
+  if (state.exemptions === void 0) {
+    state.exemptions = {};
+  }
+  const exemptions = state.exemptions;
+  const existing = exemptions[key];
+  const policyIds = new Set(existing?.policyIds ?? []);
+  const networkIds = new Set(existing?.networkIds ?? []);
+  for (const scope of scopes) {
+    policyIds.add(scope.policyId);
+    networkIds.add(scope.networkId);
+  }
+  exemptions[key] = {
+    advertiserHost: key,
+    policyIds: [...policyIds],
+    networkIds: [...networkIds],
+    grantedAt: existing?.grantedAt ?? now
+  };
+}
+function applySessionExemptions(advertiserHost, detection, record) {
+  if (!record) {
+    return detection;
+  }
+  const host = normalizeHost(advertiserHost);
+  const policyIds = new Set(record.policyIds);
+  const networkIds = new Set(record.networkIds);
+  const filtered = detection.matched.filter((match) => {
+    if (match.kind === "disabled-host") {
+      return true;
+    }
+    if (normalizeHost(match.advertiserHost) !== host) {
+      return true;
+    }
+    return !(policyIds.has(match.policyId) || networkIds.has(match.networkId));
+  });
+  if (filtered.length === detection.matched.length) {
+    return detection;
+  }
+  const strongest = filtered[0] ? {
+    policyId: filtered[0].policyId,
+    advertiserHost: filtered[0].advertiserHost,
+    reason: filtered[0].reason
+  } : void 0;
+  const next = { matched: filtered, selfMatch: detection.selfMatch };
+  if (strongest) {
+    next.strongest = strongest;
+  }
+  if (detection.selfExemptScopes) {
+    next.selfExemptScopes = detection.selfExemptScopes;
+  }
+  return next;
+}
 function policiesForDetection(policies, detection) {
   if (detection.strongest === void 0) {
     return [];
@@ -801,6 +901,11 @@ function cloneAuditEntry(entry) {
     if (entry.detection.strongest !== void 0) {
       detection.strongest = { ...entry.detection.strongest };
     }
+    if (entry.detection.selfExemptScopes !== void 0) {
+      detection.selfExemptScopes = entry.detection.selfExemptScopes.map(
+        (scope) => ({ ...scope })
+      );
+    }
     if (entry.detection.failClosedReason !== void 0) {
       detection.failClosedReason = entry.detection.failClosedReason;
     }
@@ -925,6 +1030,7 @@ function dropSessionBoundRecords(state, now) {
       delete next.sessions[host];
     }
   }
+  delete next.exemptions;
   return next;
 }
 function createSessionId() {
@@ -958,10 +1064,36 @@ function parseState(value) {
   for (const [host, record] of Object.entries(value.sessions)) {
     sessions[host] = parseSessionRecord(record);
   }
-  return {
+  const state = {
     sessions,
     auditLog: value.auditLog.map(parseAuditEntry)
   };
+  if (value.exemptions !== void 0) {
+    if (!isRecord(value.exemptions)) {
+      throw new Error("invalid standdown state");
+    }
+    const exemptions = {};
+    for (const [host, record] of Object.entries(value.exemptions)) {
+      exemptions[host] = parseExemptionRecord(record);
+    }
+    state.exemptions = exemptions;
+  }
+  return state;
+}
+function parseExemptionRecord(value) {
+  if (!isRecord(value)) {
+    throw new Error("invalid exemption record");
+  }
+  const { advertiserHost, policyIds, networkIds, grantedAt } = value;
+  if (typeof advertiserHost !== "string" || typeof grantedAt !== "number" || !Array.isArray(policyIds) || !policyIds.every((id) => typeof id === "string") || !Array.isArray(networkIds) || !networkIds.every((id) => typeof id === "string")) {
+    throw new Error("invalid exemption record");
+  }
+  return {
+    advertiserHost,
+    policyIds: [...policyIds],
+    networkIds: [...networkIds],
+    grantedAt
+  };
 }
 function parseSessionRecord(value) {
   if (!isRecord(value)) {
@@ -1019,7 +1151,7 @@ function parseAuditEntry(value) {
   return entry;
 }
 function cloneState(state) {
-  return {
+  const next = {
     sessions: Object.fromEntries(
       Object.entries(state.sessions).map(([host, record]) => [
         host,
@@ -1028,6 +1160,19 @@ function cloneState(state) {
     ),
     auditLog: state.auditLog.map(cloneAuditEntry2)
   };
+  if (state.exemptions) {
+    next.exemptions = Object.fromEntries(
+      Object.entries(state.exemptions).map(([host, record]) => [
+        host,
+        {
+          ...record,
+          policyIds: [...record.policyIds],
+          networkIds: [...record.networkIds]
+        }
+      ])
+    );
+  }
+  return next;
 }
 function cloneSessionRecord(record) {
   const next = {
@@ -1063,6 +1208,11 @@ function cloneAuditEntry2(entry) {
     if (entry.detection.strongest !== void 0) {
       next.detection.strongest = { ...entry.detection.strongest };
     }
+    if (entry.detection.selfExemptScopes !== void 0) {
+      next.detection.selfExemptScopes = entry.detection.selfExemptScopes.map(
+        (scope) => ({ ...scope })
+      );
+    }
     if (entry.detection.failClosedReason !== void 0) {
       next.detection.failClosedReason = entry.detection.failClosedReason;
     }
@@ -1097,10 +1247,7 @@ function createContentStanddown(opts) {
   const windowLike = opts.window ?? currentWindow();
   const now = opts.now ?? Date.now;
   const store = opts.store ?? createContentStore(windowLike, opts, now);
-  const session = new StanddownSession(
-    store,
-    opts.auditLog === void 0 ? void 0 : { auditLog: opts.auditLog }
-  );
+  const session = new StanddownSession(store, contentSessionOptions(opts));
   let disposed = false;
   let pending = false;
   const restoreHistory = patchHistory(windowLike, scheduleEvaluation);
@@ -1181,7 +1328,10 @@ function collectContentSignals(opts = {}) {
   }
   const signals = {
     url: windowLike.location.href,
-    now: now()
+    now: now(),
+    // The content plane never observes redirect chains, so a non-stand-down
+    // here can miss redirect-only attribution.
+    signalCoverage: "partial"
   };
   const referrer = windowLike.document.referrer;
   const cookieNames = cookieNamesFromString(windowLike.document.cookie);
@@ -1205,6 +1355,16 @@ function cookieNamesFromString(cookie) {
   }
   return cookie.split(";").map((part) => part.trim()).filter((part) => part.length > 0).map((part) => part.split("=")[0]?.trim() ?? "").filter((name) => name.length > 0);
 }
+function contentSessionOptions(opts) {
+  const sessionOpts = {};
+  if (opts.auditLog !== void 0) {
+    sessionOpts.auditLog = opts.auditLog;
+  }
+  if (opts.selfExemptionScope !== void 0) {
+    sessionOpts.selfExemptionScope = opts.selfExemptionScope;
+  }
+  return Object.keys(sessionOpts).length > 0 ? sessionOpts : void 0;
+}
 function createContentStore(windowLike, opts, now) {
   if (windowLike === void 0) {
     return new UnavailableStateStore("content window unavailable");