standdown 0.1.0 → 0.2.1

package/dist/webext.cjs

@@ -45,6 +45,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") {
@@ -70,12 +73,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"
@@ -504,8 +501,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,
@@ -519,6 +532,10 @@ function detect(signals, policies) {
       selfMatch = true;
     }
     if (scopedSelfMatch) {
+      selfExemptScopes.push({
+        policyId: policy.id,
+        networkId: policy.network.id
+      });
       continue;
     }
     matched.push(
@@ -531,7 +548,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;
@@ -648,16 +672,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(
@@ -729,11 +756,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);
@@ -759,38 +788,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");
   }
@@ -959,6 +999,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 [];
@@ -1070,6 +1170,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;
     }
@@ -1188,6 +1293,7 @@ function dropSessionBoundRecords(state, now) {
       delete next.sessions[host];
     }
   }
+  delete next.exemptions;
   return next;
 }
 function createSessionId() {
@@ -1221,10 +1327,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)) {
@@ -1282,7 +1414,7 @@ function parseAuditEntry(value) {
   return entry;
 }
 function cloneState(state) {
-  return {
+  const next = {
     sessions: Object.fromEntries(
       Object.entries(state.sessions).map(([host, record]) => [
         host,
@@ -1291,6 +1423,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 = {
@@ -1326,6 +1471,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;
     }
@@ -1409,10 +1559,7 @@ function createStanddown(opts) {
     sessionId: opts.sessionId,
     now
   });
-  const session = new StanddownSession(
-    store,
-    opts.auditLog === void 0 ? void 0 : { auditLog: opts.auditLog }
-  );
+  const session = new StanddownSession(store, sessionOptions(opts));
   const redirectChains = /* @__PURE__ */ new Map();
   const redirectRequestIds = /* @__PURE__ */ new Map();
   const initiators = /* @__PURE__ */ new Map();
@@ -1503,7 +1650,10 @@ function createStanddown(opts) {
       redirectChain,
       initiator,
       selfPatterns: opts.selfPatterns,
-      publisherSites: opts.publisherSites
+      publisherSites: opts.publisherSites,
+      // Without the webRequest plane we never observe redirect chains, so a
+      // non-stand-down could be a false negative — mark the coverage partial.
+      signalCoverage: mode === "webRequest" ? "full" : "partial"
     });
     return session.ingest(signals, activePolicies);
   }
@@ -1601,6 +1751,16 @@ function createStanddown(opts) {
     dispose
   };
 }
+function sessionOptions(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 createChromeStore(chromeApi, opts) {
   if (chromeApi?.storage?.local === void 0) {
     return new UnavailableStateStore();
@@ -1622,6 +1782,9 @@ function navigationSignals(value) {
     url: value.url,
     now: value.now
   };
+  if (value.signalCoverage !== void 0) {
+    signals.signalCoverage = value.signalCoverage;
+  }
   if (value.redirectChain !== void 0 && value.redirectChain.length > 0) {
     signals.redirectChain = [...value.redirectChain];
   }