@a4anthony/proctorkit-types 0.1.0 → 0.2.0

package/dist/index.d.ts

@@ -5,4 +5,5 @@ export * from "./worker-protocol.js";
 export * from "./production-safety.js";
 export * from "./status.js";
 export * from "./billing.js";
+export * from "./integrity.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -5,4 +5,5 @@ export * from "./worker-protocol.js";
 export * from "./production-safety.js";
 export * from "./status.js";
 export * from "./billing.js";
+export * from "./integrity.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,cAAc,sBAAsB,CAAC;AACrC,cAAc,wBAAwB,CAAC;AACvC,cAAc,aAAa,CAAC;AAC5B,cAAc,cAAc,CAAC;AAC7B,cAAc,gBAAgB,CAAC"}

package/dist/integrity.d.ts

@@ -0,0 +1,20 @@
+export type IntegrityFindingSeverity = "violation" | "concern" | "info";
+export interface IntegrityCategoryRule {
+    key: string;
+    label: string;
+    tone: string;
+    weight: number;
+    cap: number;
+    severity: IntegrityFindingSeverity;
+    match: (kind: string) => boolean;
+}
+/**
+ * Canonical integrity-score rules shared by the API, dashboard, and reports.
+ * Keep all score consumers on this table so list ordering cannot disagree
+ * with the score shown in session review.
+ */
+export declare const INTEGRITY_CATEGORIES: ReadonlyArray<IntegrityCategoryRule>;
+export declare function isIntegrityFlag(kind: string): boolean;
+export declare function computeIntegrityScoreFromKinds(kinds: readonly string[]): number;
+export declare function computeIntegrityScoreFromKindCounts(counts: ReadonlyMap<string, number>): number;
+//# sourceMappingURL=integrity.d.ts.map

package/dist/integrity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity.d.ts","sourceRoot":"","sources":["../src/integrity.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,wBAAwB,GAAG,WAAW,GAAG,SAAS,GAAG,MAAM,CAAC;AAExE,MAAM,WAAW,qBAAqB;IACpC,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,wBAAwB,CAAC;IACnC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;CAClC;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,aAAa,CAAC,qBAAqB,CAiFrE,CAAC;AAEF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,wBAAgB,8BAA8B,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAM/E;AAED,wBAAgB,mCAAmC,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAS/F"}

package/dist/integrity.js

@@ -0,0 +1,103 @@
+/**
+ * Canonical integrity-score rules shared by the API, dashboard, and reports.
+ * Keep all score consumers on this table so list ordering cannot disagree
+ * with the score shown in session review.
+ */
+export const INTEGRITY_CATEGORIES = [
+    {
+        key: "identity",
+        label: "Identity mismatch",
+        tone: "#dc2626",
+        weight: 40,
+        cap: 40,
+        severity: "violation",
+        match: (kind) => kind.startsWith("face.identity-mismatch"),
+    },
+    {
+        key: "another-person",
+        label: "Another person / device",
+        tone: "#ef4444",
+        weight: 25,
+        cap: 35,
+        severity: "violation",
+        match: (kind) => kind === "face.multiple" ||
+            kind === "face.multiple-at-snapshot" ||
+            kind.startsWith("webcam.second-device-detected") ||
+            kind.startsWith("webcam.second-screen-detected"),
+    },
+    {
+        key: "prohibited-object",
+        label: "Prohibited object",
+        tone: "#f97316",
+        weight: 18,
+        cap: 30,
+        severity: "violation",
+        match: (kind) => kind.startsWith("webcam.phone-detected") || kind.startsWith("webcam.book-detected"),
+    },
+    {
+        key: "evasion",
+        label: "Monitoring evasion",
+        tone: "#dc2626",
+        weight: 12,
+        cap: 30,
+        severity: "violation",
+        match: (kind) => kind === "fullscreen.exited" ||
+            kind === "screen-share.declined" ||
+            kind === "screen-share.stopped",
+    },
+    {
+        key: "window-switching",
+        label: "Window / app switching",
+        tone: "#f59e0b",
+        weight: 3,
+        cap: 20,
+        severity: "concern",
+        match: (kind) => kind === "screen.window-switched" || kind === "focus.lost" || kind === "tab.hidden",
+    },
+    {
+        key: "face-gaze",
+        label: "Face absence / gaze",
+        tone: "#f43f5e",
+        weight: 5,
+        cap: 18,
+        severity: "concern",
+        match: (kind) => kind === "face.lost" ||
+            kind === "face.lost-at-snapshot" ||
+            kind === "face.gaze-off-screen" ||
+            kind === "face.gaze-off-screen-at-snapshot",
+    },
+    {
+        key: "clipboard",
+        label: "Clipboard / screenshot",
+        tone: "#fb923c",
+        weight: 2,
+        cap: 12,
+        severity: "concern",
+        match: (kind) => kind.startsWith("clipboard.") ||
+            kind === "screenshot.attempted" ||
+            kind === "keyboard.blocked" ||
+            kind === "contextmenu.opened",
+    },
+];
+export function isIntegrityFlag(kind) {
+    return INTEGRITY_CATEGORIES.some((category) => category.match(kind));
+}
+export function computeIntegrityScoreFromKinds(kinds) {
+    const counts = new Map();
+    for (const kind of kinds) {
+        counts.set(kind, (counts.get(kind) ?? 0) + 1);
+    }
+    return computeIntegrityScoreFromKindCounts(counts);
+}
+export function computeIntegrityScoreFromKindCounts(counts) {
+    const penalty = INTEGRITY_CATEGORIES.reduce((total, category) => {
+        let count = 0;
+        for (const [kind, occurrences] of counts) {
+            if (category.match(kind))
+                count += occurrences;
+        }
+        return total + Math.min(category.cap, category.weight * count);
+    }, 0);
+    return Math.max(0, Math.min(100, Math.round(100 - penalty)));
+}
+//# sourceMappingURL=integrity.js.map

package/dist/integrity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"integrity.js","sourceRoot":"","sources":["../src/integrity.ts"],"names":[],"mappings":"AAYA;;;;GAIG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAyC;IACxE;QACE,GAAG,EAAE,UAAU;QACf,KAAK,EAAE,mBAAmB;QAC1B,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE;QACV,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,WAAW;QACrB,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,UAAU,CAAC,wBAAwB,CAAC;KAC3D;IACD;QACE,GAAG,EAAE,gBAAgB;QACrB,KAAK,EAAE,yBAAyB;QAChC,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE;QACV,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,WAAW;QACrB,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CACd,IAAI,KAAK,eAAe;YACxB,IAAI,KAAK,2BAA2B;YACpC,IAAI,CAAC,UAAU,CAAC,+BAA+B,CAAC;YAChD,IAAI,CAAC,UAAU,CAAC,+BAA+B,CAAC;KACnD;IACD;QACE,GAAG,EAAE,mBAAmB;QACxB,KAAK,EAAE,mBAAmB;QAC1B,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE;QACV,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,WAAW;QACrB,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CACd,IAAI,CAAC,UAAU,CAAC,uBAAuB,CAAC,IAAI,IAAI,CAAC,UAAU,CAAC,sBAAsB,CAAC;KACtF;IACD;QACE,GAAG,EAAE,SAAS;QACd,KAAK,EAAE,oBAAoB;QAC3B,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,EAAE;QACV,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,WAAW;QACrB,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CACd,IAAI,KAAK,mBAAmB;YAC5B,IAAI,KAAK,uBAAuB;YAChC,IAAI,KAAK,sBAAsB;KAClC;IACD;QACE,GAAG,EAAE,kBAAkB;QACvB,KAAK,EAAE,wBAAwB;QAC/B,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,CAAC;QACT,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,SAAS;QACnB,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CACd,IAAI,KAAK,wBAAwB,IAAI,IAAI,KAAK,YAAY,IAAI,IAAI,KAAK,YAAY;KACtF;IACD;QACE,GAAG,EAAE,WAAW;QAChB,KAAK,EAAE,qBAAqB;QAC5B,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,CAAC;QACT,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,SAAS;QACnB,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CACd,IAAI,KAAK,WAAW;YACpB,IAAI,KAAK,uBAAuB;YAChC,IAAI,KAAK,sBAAsB;YAC/B,IAAI,KAAK,kCAAkC;KAC9C;IACD;QACE,GAAG,EAAE,WAAW;QAChB,KAAK,EAAE,wBAAwB;QAC/B,IAAI,EAAE,SAAS;QACf,MAAM,EAAE,CAAC;QACT,GAAG,EAAE,EAAE;QACP,QAAQ,EAAE,SAAS;QACnB,KAAK,EAAE,CAAC,IAAI,EAAE,EAAE,CACd,IAAI,CAAC,UAAU,CAAC,YAAY,CAAC;YAC7B,IAAI,KAAK,sBAAsB;YAC/B,IAAI,KAAK,kBAAkB;YAC3B,IAAI,KAAK,oBAAoB;KAChC;CACF,CAAC;AAEF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;AACvE,CAAC;AAED,MAAM,UAAU,8BAA8B,CAAC,KAAwB;IACrE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAkB,CAAC;IACzC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAChD,CAAC;IACD,OAAO,mCAAmC,CAAC,MAAM,CAAC,CAAC;AACrD,CAAC;AAED,MAAM,UAAU,mCAAmC,CAAC,MAAmC;IACrF,MAAM,OAAO,GAAG,oBAAoB,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,QAAQ,EAAE,EAAE;QAC9D,IAAI,KAAK,GAAG,CAAC,CAAC;QACd,KAAK,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,MAAM,EAAE,CAAC;YACzC,IAAI,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC;gBAAE,KAAK,IAAI,WAAW,CAAC;QACjD,CAAC;QACD,OAAO,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC;IACjE,CAAC,EAAE,CAAC,CAAC,CAAC;IACN,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAC/D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@a4anthony/proctorkit-types",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Shared TypeScript types for the proctoring platform",
   "license": "MIT",
   "type": "module",

package/src/index.ts

@@ -5,3 +5,4 @@ export * from "./worker-protocol.js";
 export * from "./production-safety.js";
 export * from "./status.js";
 export * from "./billing.js";
+export * from "./integrity.js";

package/src/integrity.ts

@@ -0,0 +1,122 @@
+export type IntegrityFindingSeverity = "violation" | "concern" | "info";
+
+export interface IntegrityCategoryRule {
+  key: string;
+  label: string;
+  tone: string;
+  weight: number;
+  cap: number;
+  severity: IntegrityFindingSeverity;
+  match: (kind: string) => boolean;
+}
+
+/**
+ * Canonical integrity-score rules shared by the API, dashboard, and reports.
+ * Keep all score consumers on this table so list ordering cannot disagree
+ * with the score shown in session review.
+ */
+export const INTEGRITY_CATEGORIES: ReadonlyArray<IntegrityCategoryRule> = [
+  {
+    key: "identity",
+    label: "Identity mismatch",
+    tone: "#dc2626",
+    weight: 40,
+    cap: 40,
+    severity: "violation",
+    match: (kind) => kind.startsWith("face.identity-mismatch"),
+  },
+  {
+    key: "another-person",
+    label: "Another person / device",
+    tone: "#ef4444",
+    weight: 25,
+    cap: 35,
+    severity: "violation",
+    match: (kind) =>
+      kind === "face.multiple" ||
+      kind === "face.multiple-at-snapshot" ||
+      kind.startsWith("webcam.second-device-detected") ||
+      kind.startsWith("webcam.second-screen-detected"),
+  },
+  {
+    key: "prohibited-object",
+    label: "Prohibited object",
+    tone: "#f97316",
+    weight: 18,
+    cap: 30,
+    severity: "violation",
+    match: (kind) =>
+      kind.startsWith("webcam.phone-detected") || kind.startsWith("webcam.book-detected"),
+  },
+  {
+    key: "evasion",
+    label: "Monitoring evasion",
+    tone: "#dc2626",
+    weight: 12,
+    cap: 30,
+    severity: "violation",
+    match: (kind) =>
+      kind === "fullscreen.exited" ||
+      kind === "screen-share.declined" ||
+      kind === "screen-share.stopped",
+  },
+  {
+    key: "window-switching",
+    label: "Window / app switching",
+    tone: "#f59e0b",
+    weight: 3,
+    cap: 20,
+    severity: "concern",
+    match: (kind) =>
+      kind === "screen.window-switched" || kind === "focus.lost" || kind === "tab.hidden",
+  },
+  {
+    key: "face-gaze",
+    label: "Face absence / gaze",
+    tone: "#f43f5e",
+    weight: 5,
+    cap: 18,
+    severity: "concern",
+    match: (kind) =>
+      kind === "face.lost" ||
+      kind === "face.lost-at-snapshot" ||
+      kind === "face.gaze-off-screen" ||
+      kind === "face.gaze-off-screen-at-snapshot",
+  },
+  {
+    key: "clipboard",
+    label: "Clipboard / screenshot",
+    tone: "#fb923c",
+    weight: 2,
+    cap: 12,
+    severity: "concern",
+    match: (kind) =>
+      kind.startsWith("clipboard.") ||
+      kind === "screenshot.attempted" ||
+      kind === "keyboard.blocked" ||
+      kind === "contextmenu.opened",
+  },
+];
+
+export function isIntegrityFlag(kind: string): boolean {
+  return INTEGRITY_CATEGORIES.some((category) => category.match(kind));
+}
+
+export function computeIntegrityScoreFromKinds(kinds: readonly string[]): number {
+  const counts = new Map<string, number>();
+  for (const kind of kinds) {
+    counts.set(kind, (counts.get(kind) ?? 0) + 1);
+  }
+  return computeIntegrityScoreFromKindCounts(counts);
+}
+
+export function computeIntegrityScoreFromKindCounts(counts: ReadonlyMap<string, number>): number {
+  const penalty = INTEGRITY_CATEGORIES.reduce((total, category) => {
+    let count = 0;
+    for (const [kind, occurrences] of counts) {
+      if (category.match(kind)) count += occurrences;
+    }
+    return total + Math.min(category.cap, category.weight * count);
+  }, 0);
+  return Math.max(0, Math.min(100, Math.round(100 - penalty)));
+}