@a4anthony/proctorkit-types 0.3.0 → 0.4.0

package/src/investigation/support-event-policy.ts

@@ -0,0 +1,548 @@
+import type { EventKind } from "../events.js";
+
+export type SupportEventDisposition = "state" | "aggregate" | "latest";
+export type SupportEventSection = "preflight" | "resume" | "runtime" | "writing";
+export type SupportEventDataClass =
+  | "support_safe"
+  | "candidate_personal"
+  | "device_identifier"
+  | "biometric"
+  | "assessment_content"
+  | "integrity_signal"
+  | "internal_diagnostic"
+  | "secret";
+
+/** DTO paths that the first support-context projection is allowed to derive. */
+export const SUPPORT_DERIVED_FACTS = [
+  "lifecycle.activityState",
+  "lifecycle.endedAt",
+  "lifecycle.journeyStage",
+  "lifecycle.lastActivityAt",
+  "lifecycle.observationState",
+  "preflight.checks[]",
+  "preflight.checks[].microphoneVerification",
+  "preflight.completedAt",
+  "preflight.devices",
+  "preflight.devices.camera.availableCount",
+  "preflight.devices.camera.virtualCount",
+  "preflight.devices.microphone.availableCount",
+  "preflight.devices.microphone.virtualCount",
+  "preflight.devices.speaker.availableCount",
+  "preflight.devices.speaker.virtualCount",
+  "preflight.observationState",
+  "preflight.startedAt",
+  "preflight.verdict",
+  "resume.currentOrLatest",
+  "resume.totalResumes",
+  "runtime.activeBlocker",
+  "runtime.delivery.drainTimeouts",
+  "runtime.delivery.lastFailureCode",
+  "runtime.delivery.mediaFailures",
+  "runtime.delivery.sdkErrors",
+  "runtime.delivery.uploadFailures",
+  "runtime.delivery.workerFailures",
+  "runtime.issues[]",
+  "runtime.observationState",
+  "writing.clipboard.blockedCopyAttempts",
+  "writing.clipboard.blockedCutAttempts",
+  "writing.clipboard.blockedPasteAttempts",
+  "writing.clipboard.lastBlockedAction",
+  "writing.clipboard.lastBlockedAt",
+  "writing.lastSaveFailure",
+  "writing.saveFailures",
+] as const;
+
+export type SupportDerivedFact = (typeof SUPPORT_DERIVED_FACTS)[number];
+
+export interface SupportEventPayloadFieldDefinition {
+  dataClasses: SupportEventDataClass[];
+  description: string;
+}
+
+export interface IncludedSupportEventDecision {
+  disposition: SupportEventDisposition;
+  section: SupportEventSection;
+  allowedPayloadFields: string[];
+  derivedFacts: SupportDerivedFact[];
+  resolvedBy?: EventKind[];
+  resolves?: EventKind[];
+  absenceMeans: string;
+}
+
+export interface ExcludedSupportEventDecision {
+  disposition: "exclude";
+  reason: string;
+}
+
+export interface ExcludedSupportEventSource extends ExcludedSupportEventDecision {
+  kind: EventKind;
+}
+
+export type CandidateSupportEventDecision =
+  | IncludedSupportEventDecision
+  | ExcludedSupportEventDecision;
+
+export interface SupportEventDefinitionSource {
+  decision: IncludedSupportEventDecision;
+  payload: Record<string, SupportEventPayloadFieldDefinition>;
+}
+
+const SAFE_OPERATIONAL_FIELDS = {
+  code: "A stable machine-readable support code.",
+  phase: "A stable SDK lifecycle phase.",
+  recoverable: "Whether the emitting producer classified the failure as recoverable.",
+  row: "A stable preflight check kind.",
+  durationMs: "Elapsed check time in milliseconds.",
+  retryCount: "Retries observed before this result.",
+  attempt: "The current retry ordinal.",
+  downloadMbps: "Measured downstream throughput in megabits per second.",
+  uploadMbps: "Measured upstream throughput in megabits per second.",
+  latencyMs: "Measured connection latency in milliseconds.",
+  jitterMs: "Measured connection jitter in milliseconds.",
+  recordingUploadMode: "The selected stable recording upload mode.",
+  readinessMedianMs: "Median readiness request duration in milliseconds.",
+  readinessWindowMs: "Readiness sampling window in milliseconds.",
+  readinessSampleCount: "Number of readiness samples.",
+  verificationMode: "The stable microphone verification mode.",
+  fallbackReason: "The stable microphone verification fallback code.",
+  vadPreparationMs: "Voice-activity detector preparation time in milliseconds.",
+  class: "The stable resume interruption class.",
+  awayMs: "Observed unavailability duration in milliseconds.",
+  navigationType: "The browser navigation category.",
+  surface: "The browser display-surface category.",
+  passed: "Whether the completed preflight attempt passed.",
+  blocked: "Whether policy blocked the clipboard action.",
+} as const;
+
+export const SUPPORT_SAFE_PAYLOAD_FIELDS = Object.fromEntries(
+  Object.entries(SAFE_OPERATIONAL_FIELDS).map(([name, description]) => [
+    name,
+    { dataClasses: ["support_safe"], description },
+  ]),
+) as Record<keyof typeof SAFE_OPERATIONAL_FIELDS, SupportEventPayloadFieldDefinition>;
+
+const decision = (
+  disposition: SupportEventDisposition,
+  section: SupportEventSection,
+  derivedFacts: SupportDerivedFact[],
+  allowedPayloadFields: Array<keyof typeof SAFE_OPERATIONAL_FIELDS> = [],
+  relationships: Pick<IncludedSupportEventDecision, "resolvedBy" | "resolves"> = {},
+): SupportEventDefinitionSource => ({
+  decision: {
+    disposition,
+    section,
+    allowedPayloadFields,
+    derivedFacts,
+    ...relationships,
+    absenceMeans:
+      "Absence is inconclusive unless the corresponding section reports complete collection.",
+  },
+  payload: Object.fromEntries(
+    allowedPayloadFields.map((field) => [field, SUPPORT_SAFE_PAYLOAD_FIELDS[field]]),
+  ),
+});
+
+/**
+ * Candidate-safe operational events only. Payload fields are deliberately
+ * allowlisted; the server must still map them into normalized facts and must
+ * never use this metadata to serialize an event payload automatically.
+ */
+export const INCLUDED_SUPPORT_EVENT_DEFINITIONS = {
+  "session.started": decision("state", "runtime", ["lifecycle.journeyStage"]),
+  "session.heartbeat": decision("latest", "runtime", ["lifecycle.lastActivityAt"]),
+  "session.end_requested": decision("state", "runtime", ["lifecycle.activityState"]),
+  "session.ended": decision("latest", "runtime", ["lifecycle.endedAt"]),
+  "session.resumed": decision(
+    "aggregate",
+    "resume",
+    ["resume.totalResumes", "resume.currentOrLatest"],
+    ["class", "awayMs", "navigationType"],
+  ),
+  "session.abandoned": decision("latest", "runtime", ["lifecycle.activityState"]),
+  "sdk.initialized": decision("state", "runtime", ["lifecycle.observationState"]),
+  "sdk.delivery.ready": decision("state", "runtime", ["runtime.observationState"]),
+  "sdk.ready": decision("state", "runtime", ["lifecycle.journeyStage"]),
+  "sdk.error": decision(
+    "aggregate",
+    "runtime",
+    ["runtime.delivery.sdkErrors", "runtime.delivery.lastFailureCode"],
+    ["code", "phase", "recoverable"],
+  ),
+  "sdk.upload.failed": decision(
+    "aggregate",
+    "runtime",
+    ["runtime.delivery.uploadFailures", "runtime.delivery.lastFailureCode"],
+    ["code", "phase", "recoverable"],
+  ),
+  "sdk.media.failed": decision(
+    "aggregate",
+    "runtime",
+    ["runtime.delivery.mediaFailures", "runtime.delivery.lastFailureCode"],
+    ["code", "phase", "recoverable"],
+  ),
+  "sdk.permission.denied": decision(
+    "aggregate",
+    "runtime",
+    ["runtime.issues[]"],
+    ["code", "phase", "recoverable"],
+  ),
+  "sdk.worker.failed": decision(
+    "aggregate",
+    "runtime",
+    ["runtime.delivery.workerFailures", "runtime.delivery.lastFailureCode"],
+    ["code", "phase", "recoverable"],
+  ),
+  "sdk.storage.fallback": decision("latest", "runtime", ["runtime.issues[]"]),
+  "sdk.recording.buffer-degraded": decision("aggregate", "runtime", ["runtime.issues[]"]),
+  "sdk.recording.buffer-evicted": decision("aggregate", "runtime", ["runtime.issues[]"]),
+  "sdk.stop.drain-timeout": decision(
+    "aggregate",
+    "runtime",
+    ["runtime.delivery.drainTimeouts"],
+    ["code"],
+  ),
+  "screen-share.started": decision("state", "runtime", ["runtime.issues[]"], [], {
+    resolves: ["screen-share.declined", "screen-share.wrong-surface"],
+  }),
+  "screen-share.stopped": decision("latest", "runtime", ["runtime.issues[]"]),
+  "screen-share.declined": decision("aggregate", "runtime", ["runtime.issues[]"], [], {
+    resolvedBy: ["screen-share.started"],
+  }),
+  "screen-share.wrong-surface": decision(
+    "aggregate",
+    "runtime",
+    ["runtime.issues[]"],
+    ["surface"],
+    { resolvedBy: ["screen-share.started"] },
+  ),
+  "screen-share.recording.started": decision("state", "runtime", ["runtime.issues[]"]),
+  "screen-share.recording.stopped": decision("latest", "runtime", ["runtime.issues[]"]),
+  "screen-share.recording.unavailable": decision("aggregate", "runtime", ["runtime.issues[]"]),
+  "webcam.started": decision("state", "runtime", ["runtime.issues[]"], [], {
+    resolves: ["webcam.declined", "webcam.unavailable"],
+  }),
+  "webcam.stopped": decision("latest", "runtime", ["runtime.issues[]"]),
+  "webcam.declined": decision("aggregate", "runtime", ["runtime.issues[]"], [], {
+    resolvedBy: ["webcam.started"],
+  }),
+  "webcam.unavailable": decision("aggregate", "runtime", ["runtime.issues[]"], [], {
+    resolvedBy: ["webcam.started"],
+  }),
+  "audio-playback.started": decision("state", "preflight", ["preflight.checks[]"]),
+  "audio-playback.paused": decision("latest", "preflight", ["preflight.checks[]"]),
+  "audio-playback.stopped": decision("latest", "preflight", ["preflight.checks[]"]),
+  "audio-playback.ended": decision("latest", "preflight", ["preflight.checks[]"]),
+  "audio-playback.error": decision("aggregate", "preflight", [
+    "preflight.checks[]",
+    "runtime.issues[]",
+  ]),
+  "audio-playback.sink-applied": decision("latest", "preflight", ["preflight.checks[]"]),
+  "audio-playback.sink-unsupported": decision("latest", "preflight", ["preflight.checks[]"]),
+  "audio-playback.sink-failed": decision("aggregate", "preflight", [
+    "preflight.checks[]",
+    "runtime.issues[]",
+  ]),
+  "audio-playback.sink-disconnected": decision("aggregate", "preflight", [
+    "preflight.checks[]",
+    "runtime.issues[]",
+  ]),
+  "video-playback.started": decision("state", "runtime", ["runtime.issues[]"]),
+  "video-playback.paused": decision("latest", "runtime", ["runtime.issues[]"]),
+  "video-playback.stopped": decision("latest", "runtime", ["runtime.issues[]"]),
+  "video-playback.ended": decision("latest", "runtime", ["runtime.issues[]"]),
+  "video-playback.error": decision("aggregate", "runtime", ["runtime.issues[]"]),
+  "video-playback.sink-applied": decision("latest", "runtime", ["runtime.issues[]"]),
+  "video-playback.sink-unsupported": decision("latest", "runtime", ["runtime.issues[]"]),
+  "video-playback.sink-failed": decision("aggregate", "runtime", ["runtime.issues[]"]),
+  "video-playback.sink-disconnected": decision("aggregate", "runtime", ["runtime.issues[]"]),
+  "network.online": decision("state", "runtime", ["runtime.issues[]"], [], {
+    resolves: ["network.offline"],
+  }),
+  "network.offline": decision("state", "runtime", ["runtime.issues[]"], [], {
+    resolvedBy: ["network.online"],
+  }),
+  "preflight.started": decision(
+    "state",
+    "preflight",
+    ["preflight.observationState", "preflight.startedAt"],
+    [],
+    { resolvedBy: ["preflight.completed"] },
+  ),
+  "preflight.row-checking": decision("latest", "preflight", ["preflight.checks[]"], ["row"], {
+    resolvedBy: ["preflight.row-passed", "preflight.row-failed"],
+  }),
+  "preflight.row-passed": decision(
+    "latest",
+    "preflight",
+    ["preflight.checks[]"],
+    [
+      "row",
+      "durationMs",
+      "downloadMbps",
+      "uploadMbps",
+      "latencyMs",
+      "jitterMs",
+      "recordingUploadMode",
+      "readinessMedianMs",
+      "readinessWindowMs",
+      "readinessSampleCount",
+    ],
+    { resolves: ["preflight.row-checking", "preflight.row-failed"] },
+  ),
+  "preflight.row-failed": decision(
+    "aggregate",
+    "preflight",
+    ["preflight.checks[]", "runtime.issues[]"],
+    [
+      "row",
+      "code",
+      "durationMs",
+      "retryCount",
+      "downloadMbps",
+      "uploadMbps",
+      "latencyMs",
+      "jitterMs",
+      "recordingUploadMode",
+      "readinessMedianMs",
+      "readinessWindowMs",
+      "readinessSampleCount",
+    ],
+    {
+      resolvedBy: ["preflight.row-retried", "preflight.row-passed"],
+      resolves: ["preflight.row-checking"],
+    },
+  ),
+  "preflight.row-retried": decision(
+    "aggregate",
+    "preflight",
+    ["preflight.checks[]"],
+    ["row", "attempt"],
+    { resolves: ["preflight.row-failed"] },
+  ),
+  "preflight.device-picked": decision("latest", "preflight", ["preflight.devices"]),
+  "preflight.devices-enumerated": decision("latest", "preflight", [
+    "preflight.devices.camera.availableCount",
+    "preflight.devices.camera.virtualCount",
+    "preflight.devices.microphone.availableCount",
+    "preflight.devices.microphone.virtualCount",
+    "preflight.devices.speaker.availableCount",
+    "preflight.devices.speaker.virtualCount",
+  ]),
+  "preflight.devices-changed": decision("aggregate", "preflight", [
+    "preflight.devices.camera.availableCount",
+    "preflight.devices.camera.virtualCount",
+    "preflight.devices.microphone.availableCount",
+    "preflight.devices.microphone.virtualCount",
+    "preflight.devices.speaker.availableCount",
+    "preflight.devices.speaker.virtualCount",
+  ]),
+  "preflight.microphone-verification": decision(
+    "latest",
+    "preflight",
+    ["preflight.checks[].microphoneVerification"],
+    ["verificationMode", "fallbackReason", "vadPreparationMs"],
+  ),
+  "preflight.face-detected": decision("latest", "preflight", ["preflight.checks[]"]),
+  "preflight.completed": decision(
+    "latest",
+    "preflight",
+    ["preflight.verdict", "preflight.completedAt"],
+    ["passed"],
+    { resolves: ["preflight.started"] },
+  ),
+  "clipboard.copy": decision(
+    "aggregate",
+    "writing",
+    [
+      "writing.clipboard.blockedCopyAttempts",
+      "writing.clipboard.lastBlockedAction",
+      "writing.clipboard.lastBlockedAt",
+    ],
+    ["blocked"],
+  ),
+  "clipboard.paste": decision(
+    "aggregate",
+    "writing",
+    [
+      "writing.clipboard.blockedPasteAttempts",
+      "writing.clipboard.lastBlockedAction",
+      "writing.clipboard.lastBlockedAt",
+    ],
+    ["blocked"],
+  ),
+  "clipboard.cut": decision(
+    "aggregate",
+    "writing",
+    [
+      "writing.clipboard.blockedCutAttempts",
+      "writing.clipboard.lastBlockedAction",
+      "writing.clipboard.lastBlockedAt",
+    ],
+    ["blocked"],
+  ),
+  "text.saved": decision("latest", "writing", ["writing.lastSaveFailure"], [], {
+    resolves: ["text.save-failed"],
+  }),
+  "text.save-failed": decision(
+    "aggregate",
+    "writing",
+    ["writing.saveFailures", "writing.lastSaveFailure"],
+    ["code"],
+    { resolvedBy: ["text.saved"] },
+  ),
+} satisfies Partial<Record<EventKind, SupportEventDefinitionSource>>;
+
+const INTEGRITY_AND_BEHAVIOUR_EVENTS = [
+  "session.integrity-hold",
+  "session.integrity-cleared",
+  "session.checkpoint",
+  "focus.lost",
+  "focus.gained",
+  "tab.hidden",
+  "tab.visible",
+  "page.viewed",
+  "fullscreen.entered",
+  "fullscreen.exited",
+  "contextmenu.opened",
+  "keyboard.blocked",
+  "screenshot.attempted",
+  "pointer.left-window",
+  "pointer.returned",
+  "idle.started",
+  "idle.ended",
+] as const satisfies readonly EventKind[];
+
+const MEDIA_AND_RECORDING_EVENTS = [
+  "screen-share.chunk-uploaded",
+  "screen-share.chunk-dropped",
+  "assessment-replay.started",
+  "assessment-replay.chunk-uploaded",
+  "assessment-replay.chunk-dropped",
+  "assessment-replay.unavailable",
+  "assessment-replay.stopped",
+  "webcam.photo.captured",
+  "webcam.photo.dropped",
+  "webcam.recording.started",
+  "webcam.recording.stopped",
+  "webcam.recording.chunk-uploaded",
+  "webcam.recording.chunk-dropped",
+  "video-clip.started",
+  "video-clip.stopped",
+  "video-clip.uploaded",
+  "video-clip.dropped",
+  "audio-clip.started",
+  "audio-clip.stopped",
+  "audio-clip.uploaded",
+  "audio-clip.dropped",
+  "media.frame.captured",
+  "media.audio.chunk",
+] as const satisfies readonly EventKind[];
+
+const DEVICE_AND_POLICY_EVENTS = [
+  "session.fingerprint",
+  "session.policy",
+  "preflight.camera-photo",
+] as const satisfies readonly EventKind[];
+
+const UNTRUSTED_OPEN_PAYLOAD_EVENTS = [
+  "preflight.attestation",
+] as const satisfies readonly EventKind[];
+
+const ANALYSIS_AND_SURVEILLANCE_EVENTS = [
+  "face.detector-ready",
+  "face.detector-failed",
+  "face.detector-degraded",
+  "face.lost",
+  "face.returned",
+  "face.multiple",
+  "face.multiple-cleared",
+  "face.gaze-off-screen",
+  "face.gaze-restored",
+  "face.identity-mismatch",
+  "screen.window-switched",
+  "screen.scene-stable",
+  "screen.recording-paused",
+  "webcam.phone-detected",
+  "webcam.phone-cleared",
+  "webcam.book-detected",
+  "webcam.book-cleared",
+  "webcam.second-device-detected",
+  "webcam.second-device-cleared",
+  "webcam.second-screen-detected",
+  "webcam.second-screen-cleared",
+  "face.lost-at-snapshot",
+  "face.multiple-at-snapshot",
+  "face.gaze-off-screen-at-snapshot",
+  "face.identity-mismatch-at-snapshot",
+  "webcam.phone-detected-at-snapshot",
+  "webcam.book-detected-at-snapshot",
+  "webcam.second-device-detected-at-snapshot",
+  "webcam.second-screen-detected-at-snapshot",
+] as const satisfies readonly EventKind[];
+
+const ASSESSMENT_WRITING_EVENTS = [
+  "text.started",
+  "text.paste",
+  "text.copy",
+  "text.cut",
+  "text.keystroke-summary",
+  "text.checkpoint",
+  "text.focus-lost",
+  "text.focus-regained",
+  "text.synthetic-input",
+  "text.submitted",
+] as const satisfies readonly EventKind[];
+
+const exclude = (events: readonly EventKind[], reason: string): ExcludedSupportEventSource[] =>
+  events.map((kind) => ({ kind, disposition: "exclude", reason }));
+
+/**
+ * Every excluded event is named explicitly. The generator rejects duplicates,
+ * omissions, and unknown events so a new EventKind cannot silently inherit a
+ * candidate-support policy.
+ */
+export const EXCLUDED_SUPPORT_EVENT_SOURCES = [
+  ...exclude(
+    INTEGRITY_AND_BEHAVIOUR_EVENTS,
+    "Candidate-facing support excludes behavioural and integrity-surveillance telemetry.",
+  ),
+  ...exclude(
+    MEDIA_AND_RECORDING_EVENTS,
+    "Candidate-facing support excludes media, recording, upload, and evidence telemetry.",
+  ),
+  ...exclude(
+    DEVICE_AND_POLICY_EVENTS,
+    "The payload may expose raw device identifiers, fingerprints, biometric media, or internal policy.",
+  ),
+  ...exclude(
+    UNTRUSTED_OPEN_PAYLOAD_EVENTS,
+    "Candidate-facing support excludes untrusted open payloads until a closed server mapping exists.",
+  ),
+  ...exclude(
+    ANALYSIS_AND_SURVEILLANCE_EVENTS,
+    "Candidate-facing support excludes biometric, object, screen-analysis, and review evidence.",
+  ),
+  ...exclude(
+    ASSESSMENT_WRITING_EVENTS,
+    "Candidate-facing support excludes answers, questions, clipboard content, typing dynamics, and writing-integrity signals.",
+  ),
+] satisfies ExcludedSupportEventSource[];
+
+const buildExcludedSupportEventDecisions = (
+  sources: readonly ExcludedSupportEventSource[],
+): Partial<Record<EventKind, ExcludedSupportEventDecision>> => {
+  const seen = new Set<EventKind>();
+  for (const { kind } of sources) {
+    if (seen.has(kind)) {
+      throw new Error(`Duplicate candidate-support exclusion source: ${kind}`);
+    }
+    seen.add(kind);
+  }
+  return Object.fromEntries(
+    sources.map(({ kind, disposition, reason }) => [kind, { disposition, reason }]),
+  ) as Partial<Record<EventKind, ExcludedSupportEventDecision>>;
+};
+
+export const EXCLUDED_SUPPORT_EVENT_DECISIONS = buildExcludedSupportEventDecisions(
+  EXCLUDED_SUPPORT_EVENT_SOURCES,
+);

package/src/investigation/version.ts

@@ -0,0 +1,3 @@
+export const PROCTORKIT_TELEMETRY_SCHEMA_VERSION = "1.0.0";
+export const PROCTORKIT_SESSION_CONTEXT_FORMAT_VERSION = "1.0.0";
+export const PROCTORKIT_SUPPORT_PROJECTION_VERSION = "1.0.0";