chainlesschain 0.166.65 → 0.166.69

package/src/lib/evolution/browser-quarantine-retention-authority.js

@@ -0,0 +1,503 @@
+import { createHash, randomUUID } from "node:crypto";
+import { types } from "node:util";
+
+import {
+  BROWSER_FILESYSTEM_QUARANTINE_EXPIRY_PLAN_SCHEMA,
+  captureBrowserFilesystemQuarantineCustody,
+} from "./browser-filesystem-quarantine-custody.js";
+
+export const BROWSER_QUARANTINE_RETENTION_SWEEP_REQUEST_SCHEMA =
+  "chainlesschain.browser-quarantine-retention-sweep-request/v1";
+export const BROWSER_QUARANTINE_RETENTION_SWEEP_RECEIPT_SCHEMA =
+  "chainlesschain.browser-quarantine-retention-sweep-receipt/v1";
+export const BROWSER_QUARANTINE_RETENTION_SWEEP_RESULT_SCHEMA =
+  "chainlesschain.browser-quarantine-retention-sweep-result/v1";
+export const BROWSER_QUARANTINE_RETENTION_OUTCOME_REQUEST_SCHEMA =
+  "chainlesschain.browser-quarantine-retention-outcome-request/v1";
+export const BROWSER_QUARANTINE_RETENTION_OUTCOME_ACK_SCHEMA =
+  "chainlesschain.browser-quarantine-retention-outcome-ack/v1";
+
+const DELETION_ACK_SCHEMA =
+  "chainlesschain.browser-download-artifact-deletion-ack/v1";
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const ID = /^[A-Za-z0-9._:-]{1,128}$/u;
+const ARTIFACT_REF = /^quarantine:[A-Za-z0-9][A-Za-z0-9._-]{0,95}$/u;
+const authorities = new WeakMap();
+
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+    .join(",")}}`;
+}
+
+function digest(domain, value) {
+  return `sha256:${createHash("sha256")
+    .update(`${domain}\0`)
+    .update(canonical(value))
+    .digest("hex")}`;
+}
+
+function exact(value, keys, label) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    types.isProxy(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value)) ||
+    Reflect.ownKeys(value).length !== keys.length ||
+    keys.some((key) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      return !descriptor?.enumerable || !("value" in descriptor);
+    })
+  )
+    throw new TypeError(`${label} has unexpected or accessor fields`);
+}
+
+function normalizeDecision(value, nowMs, maxGrantTtlMs) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    types.isProxy(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value))
+  )
+    throw new TypeError("retention sweep decision is invalid");
+  const decision = Object.getOwnPropertyDescriptor(value, "decision");
+  if (!decision?.enumerable || !("value" in decision))
+    throw new TypeError("retention sweep decision is invalid");
+  if (decision.value === "deny") {
+    exact(value, ["decision", "reason"], "retention sweep denial");
+    if (
+      typeof value.reason !== "string" ||
+      value.reason.length < 1 ||
+      value.reason.length > 512
+    )
+      throw new TypeError("retention sweep denial is invalid");
+    return Object.freeze({ ...value });
+  }
+  exact(
+    value,
+    ["decision", "policyEvidenceRef", "validUntil"],
+    "retention sweep approval",
+  );
+  const validUntilMs = Date.parse(value.validUntil);
+  if (
+    value.decision !== "allow" ||
+    typeof value.policyEvidenceRef !== "string" ||
+    value.policyEvidenceRef.length < 1 ||
+    value.policyEvidenceRef.length > 512 ||
+    !Number.isFinite(validUntilMs) ||
+    validUntilMs <= nowMs ||
+    validUntilMs > nowMs + maxGrantTtlMs
+  )
+    throw new TypeError("retention sweep approval is invalid");
+  return Object.freeze({ ...value, validUntilMs });
+}
+
+function normalizePlanArtifact(value, cutoffAt, nowMs) {
+  exact(
+    value,
+    [
+      "artifactRef",
+      "artifactRefDigest",
+      "artifactDigest",
+      "sourceActionReceiptDigest",
+      "expiresAt",
+    ],
+    "retention expiry plan artifact",
+  );
+  const expiresAtMs = Date.parse(value.expiresAt);
+  if (
+    !ARTIFACT_REF.test(value.artifactRef) ||
+    value.artifactRefDigest !==
+      digest(
+        "chainlesschain.browser-download-artifact-ref/v1",
+        value.artifactRef,
+      ) ||
+    !DIGEST.test(value.artifactDigest) ||
+    !DIGEST.test(value.sourceActionReceiptDigest) ||
+    !Number.isFinite(expiresAtMs) ||
+    new Date(expiresAtMs).toISOString() !== value.expiresAt ||
+    expiresAtMs > Date.parse(cutoffAt) ||
+    expiresAtMs > nowMs
+  )
+    throw new Error("retention expiry plan artifact is invalid");
+  return Object.freeze({ ...value });
+}
+
+function validatePlan(plan, descriptor, sweepId, cutoffAt, nowMs) {
+  exact(
+    plan,
+    [
+      "schema",
+      "custodyId",
+      "authorityId",
+      "tenantId",
+      "handlerArtifactDigest",
+      "policyRevision",
+      "sweepId",
+      "cutoffAt",
+      "plannedAt",
+      "artifacts",
+      "planDigest",
+    ],
+    "retention expiry plan",
+  );
+  if (!Array.isArray(plan.artifacts))
+    throw new Error("retention expiry plan is invalid");
+  const artifacts = Object.freeze(
+    plan.artifacts.map((artifact) =>
+      normalizePlanArtifact(artifact, cutoffAt, nowMs),
+    ),
+  );
+  if (
+    new Set(artifacts.map((artifact) => artifact.artifactRef)).size !==
+      artifacts.length ||
+    artifacts.some(
+      (artifact, index) =>
+        index > 0 &&
+        artifacts[index - 1].artifactRef.localeCompare(artifact.artifactRef) >=
+          0,
+    )
+  )
+    throw new Error("retention expiry plan artifacts are not canonical");
+  const core = Object.freeze({
+    schema: plan.schema,
+    custodyId: plan.custodyId,
+    authorityId: plan.authorityId,
+    tenantId: plan.tenantId,
+    handlerArtifactDigest: plan.handlerArtifactDigest,
+    policyRevision: plan.policyRevision,
+    sweepId: plan.sweepId,
+    cutoffAt: plan.cutoffAt,
+    plannedAt: plan.plannedAt,
+    artifacts,
+  });
+  if (
+    plan.schema !== BROWSER_FILESYSTEM_QUARANTINE_EXPIRY_PLAN_SCHEMA ||
+    !ID.test(plan.custodyId) ||
+    plan.authorityId !== descriptor.authorityId ||
+    plan.tenantId !== descriptor.tenantId ||
+    plan.handlerArtifactDigest !== descriptor.handlerArtifactDigest ||
+    plan.policyRevision !== descriptor.policyRevision ||
+    plan.sweepId !== sweepId ||
+    plan.cutoffAt !== cutoffAt ||
+    Date.parse(plan.plannedAt) !== nowMs ||
+    artifacts.length > descriptor.maxBatchSize ||
+    plan.planDigest !==
+      digest(BROWSER_FILESYSTEM_QUARANTINE_EXPIRY_PLAN_SCHEMA, core)
+  )
+    throw new Error("retention expiry plan is invalid");
+  return Object.freeze({ ...plan, artifacts });
+}
+
+function validateDeletionAck(value, descriptor, artifact, receiptDigest) {
+  exact(
+    value,
+    [
+      "schema",
+      "authorityId",
+      "tenantId",
+      "handlerArtifactDigest",
+      "actionReceiptDigest",
+      "requestDigest",
+      "artifactRef",
+      "artifactDigest",
+      "sourceActionReceiptDigest",
+      "discardedAt",
+      "deletionReceiptDigest",
+      "authenticated",
+      "durable",
+      "readbackVerified",
+      "bytesUnavailable",
+      "qualifiesForPromotion",
+    ],
+    "retention deletion acknowledgement",
+  );
+  if (
+    value.schema !== DELETION_ACK_SCHEMA ||
+    value.authorityId !== descriptor.authorityId ||
+    value.tenantId !== descriptor.tenantId ||
+    value.handlerArtifactDigest !== descriptor.handlerArtifactDigest ||
+    value.actionReceiptDigest !== receiptDigest ||
+    !DIGEST.test(value.requestDigest) ||
+    value.artifactRef !== artifact.artifactRef ||
+    value.artifactDigest !== artifact.artifactDigest ||
+    value.sourceActionReceiptDigest !== artifact.sourceActionReceiptDigest ||
+    !Number.isFinite(Date.parse(value.discardedAt)) ||
+    !DIGEST.test(value.deletionReceiptDigest) ||
+    value.authenticated !== true ||
+    value.durable !== true ||
+    value.readbackVerified !== true ||
+    value.bytesUnavailable !== true ||
+    value.qualifiesForPromotion !== false
+  )
+    throw new Error("retention deletion acknowledgement is invalid");
+  return value;
+}
+
+function normalizeOutcomeAck(value, descriptor, request) {
+  exact(
+    value,
+    [
+      "schema",
+      "authorityId",
+      "tenantId",
+      "handlerArtifactDigest",
+      "sweepReceiptDigest",
+      "outcomeRequestDigest",
+      "auditEventDigest",
+      "durabilityReceiptDigest",
+      "authenticated",
+      "durable",
+      "readbackVerified",
+      "qualifiesForPromotion",
+    ],
+    "retention sweep outcome acknowledgement",
+  );
+  if (
+    value.schema !== BROWSER_QUARANTINE_RETENTION_OUTCOME_ACK_SCHEMA ||
+    value.authorityId !== descriptor.authorityId ||
+    value.tenantId !== descriptor.tenantId ||
+    value.handlerArtifactDigest !== descriptor.handlerArtifactDigest ||
+    value.sweepReceiptDigest !== request.sweepReceiptDigest ||
+    value.outcomeRequestDigest !== request.outcomeRequestDigest ||
+    !DIGEST.test(value.auditEventDigest) ||
+    !DIGEST.test(value.durabilityReceiptDigest) ||
+    value.authenticated !== true ||
+    value.durable !== true ||
+    value.readbackVerified !== true ||
+    value.qualifiesForPromotion !== false
+  )
+    throw new Error("retention sweep outcome acknowledgement is invalid");
+  return Object.freeze({ ...value });
+}
+
+export function createBrowserQuarantineRetentionAuthority(options) {
+  exact(
+    options,
+    ["descriptor", "custody", "authorizeSweep", "recordOutcome", "now"],
+    "browser quarantine retention authority",
+  );
+  const custody = captureBrowserFilesystemQuarantineCustody(options.custody);
+  const retention = custody.bindRetentionAuthority(options.descriptor);
+  if (
+    typeof options.authorizeSweep !== "function" ||
+    types.isProxy(options.authorizeSweep) ||
+    typeof options.recordOutcome !== "function" ||
+    types.isProxy(options.recordOutcome) ||
+    typeof options.now !== "function" ||
+    types.isProxy(options.now)
+  )
+    throw new TypeError("browser quarantine retention ports are invalid");
+  const authority = Object.freeze({});
+  authorities.set(authority, {
+    descriptor: Object.freeze({ ...options.descriptor }),
+    authorizeSweep: options.authorizeSweep,
+    recordOutcome: options.recordOutcome,
+    now: options.now,
+    retention,
+    running: false,
+  });
+  return authority;
+}
+
+export function captureBrowserQuarantineRetentionAuthority(value) {
+  const state = authorities.get(value);
+  if (!state)
+    throw new TypeError(
+      "A branded browser quarantine retention authority is required",
+    );
+  return Object.freeze({
+    descriptor: state.descriptor,
+    runExpirySweep: async () => {
+      if (state.running)
+        throw new Error("browser quarantine retention sweep is already active");
+      state.running = true;
+      try {
+        const nowMs = state.now();
+        if (!Number.isFinite(nowMs))
+          throw new Error("browser quarantine retention clock is invalid");
+        const cutoffAt = new Date(nowMs).toISOString();
+        const sweepId = randomUUID();
+        const plan = validatePlan(
+          await state.retention.planExpiredArtifacts({
+            sweepId,
+            cutoffAt,
+            maxArtifacts: state.descriptor.maxBatchSize,
+          }),
+          state.descriptor,
+          sweepId,
+          cutoffAt,
+          nowMs,
+        );
+        const request = Object.freeze({
+          schema: BROWSER_QUARANTINE_RETENTION_SWEEP_REQUEST_SCHEMA,
+          authorityId: state.descriptor.authorityId,
+          tenantId: state.descriptor.tenantId,
+          handlerArtifactDigest: state.descriptor.handlerArtifactDigest,
+          policyRevision: state.descriptor.policyRevision,
+          sweepId,
+          cutoffAt,
+          planDigest: plan.planDigest,
+          artifactCount: plan.artifacts.length,
+          artifacts: Object.freeze(
+            plan.artifacts.map((artifact) =>
+              Object.freeze({
+                artifactRefDigest: artifact.artifactRefDigest,
+                artifactDigest: artifact.artifactDigest,
+                expiresAt: artifact.expiresAt,
+              }),
+            ),
+          ),
+          requestedAt: cutoffAt,
+        });
+        const decision = normalizeDecision(
+          await state.authorizeSweep(request),
+          nowMs,
+          state.descriptor.maxGrantTtlMs,
+        );
+        if (decision.decision === "deny") {
+          const error = new Error(decision.reason);
+          error.code = "BROWSER_QUARANTINE_RETENTION_DENIED";
+          throw error;
+        }
+        const receiptCore = Object.freeze({
+          schema: BROWSER_QUARANTINE_RETENTION_SWEEP_RECEIPT_SCHEMA,
+          authorityId: state.descriptor.authorityId,
+          tenantId: state.descriptor.tenantId,
+          handlerArtifactDigest: state.descriptor.handlerArtifactDigest,
+          policyRevision: state.descriptor.policyRevision,
+          sweepId,
+          cutoffAt,
+          planDigest: plan.planDigest,
+          artifactCount: plan.artifacts.length,
+          policyEvidenceRef: decision.policyEvidenceRef,
+          authorizedAt: cutoffAt,
+          validUntil: decision.validUntil,
+        });
+        const receiptDigest = digest(
+          BROWSER_QUARANTINE_RETENTION_SWEEP_RECEIPT_SCHEMA,
+          receiptCore,
+        );
+        const deletions = [];
+        let executionError = null;
+        for (const artifact of plan.artifacts) {
+          try {
+            const executionMs = state.now();
+            if (
+              !Number.isFinite(executionMs) ||
+              executionMs >= decision.validUntilMs
+            )
+              throw new Error("retention sweep grant expired during execution");
+            const acknowledgement = validateDeletionAck(
+              await state.retention.disposeExpiredArtifact({
+                sweepReceiptDigest: receiptDigest,
+                planDigest: plan.planDigest,
+                sweepId,
+                cutoffAt,
+                ...artifact,
+              }),
+              state.descriptor,
+              artifact,
+              receiptDigest,
+            );
+            deletions.push(
+              Object.freeze({
+                artifactRefDigest: artifact.artifactRefDigest,
+                artifactDigest: artifact.artifactDigest,
+                discardedAt: acknowledgement.discardedAt,
+                deletionReceiptDigest: acknowledgement.deletionReceiptDigest,
+              }),
+            );
+          } catch (error) {
+            executionError = error;
+            break;
+          }
+        }
+        const completedMs = state.now();
+        if (!Number.isFinite(completedMs))
+          throw new Error("browser quarantine retention clock is invalid");
+        const status = executionError === null ? "succeeded" : "failed";
+        const failureDigest =
+          executionError === null
+            ? null
+            : digest("chainlesschain.browser-quarantine-retention-failure/v1", {
+                name: executionError?.name ?? "Error",
+                code: executionError?.code ?? null,
+              });
+        const outcomeCore = Object.freeze({
+          schema: BROWSER_QUARANTINE_RETENTION_OUTCOME_REQUEST_SCHEMA,
+          authorityId: state.descriptor.authorityId,
+          tenantId: state.descriptor.tenantId,
+          handlerArtifactDigest: state.descriptor.handlerArtifactDigest,
+          policyRevision: state.descriptor.policyRevision,
+          sweepId,
+          sweepReceiptDigest: receiptDigest,
+          planDigest: plan.planDigest,
+          status,
+          plannedCount: plan.artifacts.length,
+          deletedCount: deletions.length,
+          deletionReceiptDigests: Object.freeze(
+            deletions.map((entry) => entry.deletionReceiptDigest),
+          ),
+          failureDigest,
+          recordedAt: new Date(completedMs).toISOString(),
+        });
+        const outcomeRequest = Object.freeze({
+          ...outcomeCore,
+          outcomeRequestDigest: digest(
+            BROWSER_QUARANTINE_RETENTION_OUTCOME_REQUEST_SCHEMA,
+            outcomeCore,
+          ),
+        });
+        const outcomeAck = normalizeOutcomeAck(
+          await state.recordOutcome(outcomeRequest),
+          state.descriptor,
+          outcomeRequest,
+        );
+        if (executionError !== null) {
+          const uncertain = new Error("retention sweep execution failed", {
+            cause: executionError,
+          });
+          uncertain.code = "BROWSER_QUARANTINE_RETENTION_SWEEP_FAILED";
+          throw uncertain;
+        }
+        const resultCore = Object.freeze({
+          schema: BROWSER_QUARANTINE_RETENTION_SWEEP_RESULT_SCHEMA,
+          authorityId: state.descriptor.authorityId,
+          tenantId: state.descriptor.tenantId,
+          handlerArtifactDigest: state.descriptor.handlerArtifactDigest,
+          policyRevision: state.descriptor.policyRevision,
+          sweepId,
+          cutoffAt,
+          planDigest: plan.planDigest,
+          sweepReceiptDigest: receiptDigest,
+          plannedCount: plan.artifacts.length,
+          deletedCount: deletions.length,
+          deletions: Object.freeze(deletions),
+          outcomeRequestDigest: outcomeRequest.outcomeRequestDigest,
+          auditEventDigest: outcomeAck.auditEventDigest,
+          durabilityReceiptDigest: outcomeAck.durabilityReceiptDigest,
+          completedAt: new Date(completedMs).toISOString(),
+        });
+        return Object.freeze({
+          ...resultCore,
+          resultDigest: digest(
+            BROWSER_QUARANTINE_RETENTION_SWEEP_RESULT_SCHEMA,
+            resultCore,
+          ),
+          authenticated: true,
+          durable: true,
+          readbackVerified: true,
+          qualifiesForPromotion: false,
+        });
+      } finally {
+        state.running = false;
+      }
+    },
+  });
+}

package/src/lib/evolution/browser-quarantine-retention-scheduler.js

@@ -0,0 +1,207 @@
+import { createHash } from "node:crypto";
+import { types } from "node:util";
+
+import { captureBrowserQuarantineRetentionAuthority } from "./browser-quarantine-retention-authority.js";
+
+export const BROWSER_QUARANTINE_RETENTION_SCHEDULER_DESCRIPTOR_SCHEMA =
+  "chainlesschain.browser-quarantine-retention-scheduler-descriptor/v1";
+
+const DIGEST = /^sha256:[a-f0-9]{64}$/u;
+const ID = /^[A-Za-z0-9._:-]{1,128}$/u;
+const schedulers = new WeakMap();
+
+function canonical(value) {
+  if (value === null || typeof value !== "object") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  return `{${Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+    .join(",")}}`;
+}
+
+function digest(domain, value) {
+  return `sha256:${createHash("sha256")
+    .update(`${domain}\0`)
+    .update(canonical(value))
+    .digest("hex")}`;
+}
+
+function exact(value, keys, label) {
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    types.isProxy(value) ||
+    ![Object.prototype, null].includes(Object.getPrototypeOf(value)) ||
+    Reflect.ownKeys(value).length !== keys.length ||
+    keys.some((key) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      return !descriptor?.enumerable || !("value" in descriptor);
+    })
+  )
+    throw new TypeError(`${label} has unexpected or accessor fields`);
+}
+
+function normalizeDescriptor(value, authorityDescriptor) {
+  exact(
+    value,
+    [
+      "schema",
+      "schedulerId",
+      "tenantId",
+      "handlerArtifactDigest",
+      "intervalMs",
+      "runOnStart",
+      "overlapMode",
+      "shutdownMode",
+    ],
+    "browser quarantine retention scheduler descriptor",
+  );
+  if (
+    value.schema !== BROWSER_QUARANTINE_RETENTION_SCHEDULER_DESCRIPTOR_SCHEMA ||
+    !ID.test(value.schedulerId) ||
+    value.tenantId !== authorityDescriptor.tenantId ||
+    value.handlerArtifactDigest !== authorityDescriptor.handlerArtifactDigest ||
+    !Number.isSafeInteger(value.intervalMs) ||
+    value.intervalMs < 1000 ||
+    value.intervalMs > 24 * 60 * 60 * 1000 ||
+    typeof value.runOnStart !== "boolean" ||
+    value.overlapMode !== "skip" ||
+    value.shutdownMode !== "drain"
+  )
+    throw new TypeError(
+      "browser quarantine retention scheduler descriptor is invalid",
+    );
+  return Object.freeze({ ...value });
+}
+
+export function createBrowserQuarantineRetentionScheduler(options) {
+  exact(
+    options,
+    ["descriptor", "authority", "setIntervalFn", "clearIntervalFn", "now"],
+    "browser quarantine retention scheduler",
+  );
+  const authority = captureBrowserQuarantineRetentionAuthority(
+    options.authority,
+  );
+  const descriptor = normalizeDescriptor(
+    options.descriptor,
+    authority.descriptor,
+  );
+  for (const [name, port] of Object.entries({
+    setIntervalFn: options.setIntervalFn,
+    clearIntervalFn: options.clearIntervalFn,
+    now: options.now,
+  })) {
+    if (typeof port !== "function" || types.isProxy(port))
+      throw new TypeError(
+        `browser quarantine retention scheduler ${name} is invalid`,
+      );
+  }
+  const scheduler = Object.freeze({});
+  schedulers.set(scheduler, {
+    descriptor,
+    runExpirySweep: authority.runExpirySweep,
+    setIntervalFn: options.setIntervalFn,
+    clearIntervalFn: options.clearIntervalFn,
+    now: options.now,
+    started: false,
+    timer: null,
+    active: null,
+    lastRun: null,
+  });
+  return scheduler;
+}
+
+async function runOnce(state, trigger) {
+  if (state.active !== null)
+    return Object.freeze({ status: "skipped", reason: "already-active" });
+  const startedAtMs = state.now();
+  if (!Number.isFinite(startedAtMs))
+    throw new Error("browser quarantine retention scheduler clock is invalid");
+  state.active = (async () => {
+    try {
+      const result = await state.runExpirySweep();
+      if (
+        !result ||
+        typeof result !== "object" ||
+        types.isProxy(result) ||
+        !DIGEST.test(result.resultDigest) ||
+        result.authenticated !== true ||
+        result.durable !== true ||
+        result.readbackVerified !== true
+      )
+        throw new Error("browser quarantine retention sweep result is invalid");
+      state.lastRun = Object.freeze({
+        status: "succeeded",
+        trigger,
+        startedAt: new Date(startedAtMs).toISOString(),
+        resultDigest: result.resultDigest,
+        failureDigest: null,
+      });
+    } catch (error) {
+      state.lastRun = Object.freeze({
+        status: "failed",
+        trigger,
+        startedAt: new Date(startedAtMs).toISOString(),
+        resultDigest: null,
+        failureDigest: digest(
+          "chainlesschain.browser-quarantine-retention-scheduler-failure/v1",
+          { name: error?.name ?? "Error", code: error?.code ?? null },
+        ),
+      });
+    }
+    return state.lastRun;
+  })();
+  try {
+    return await state.active;
+  } finally {
+    state.active = null;
+  }
+}
+
+export function captureBrowserQuarantineRetentionScheduler(value) {
+  const state = schedulers.get(value);
+  if (!state)
+    throw new TypeError(
+      "A branded browser quarantine retention scheduler is required",
+    );
+  return Object.freeze({
+    descriptor: state.descriptor,
+    start: async () => {
+      if (state.started)
+        throw new Error(
+          "browser quarantine retention scheduler is already started",
+        );
+      const callback = () => {
+        if (!state.started) return;
+        void runOnce(state, "interval").catch(() => {});
+      };
+      const timer = state.setIntervalFn(callback, state.descriptor.intervalMs);
+      if (timer === null || timer === undefined)
+        throw new Error(
+          "browser quarantine retention scheduler timer is invalid",
+        );
+      state.timer = timer;
+      state.started = true;
+      if (state.descriptor.runOnStart) await runOnce(state, "startup");
+      return Object.freeze({ status: "started" });
+    },
+    runNow: async () => runOnce(state, "manual"),
+    stop: async () => {
+      if (state.started) {
+        state.clearIntervalFn(state.timer);
+        state.timer = null;
+        state.started = false;
+      }
+      if (state.active !== null) await state.active;
+      return Object.freeze({ status: "stopped", lastRun: state.lastRun });
+    },
+    inspect: () =>
+      Object.freeze({
+        started: state.started,
+        running: state.active !== null,
+        lastRun: state.lastRun,
+      }),
+  });
+}