@voltro/plugin-sanctions 0.0.0-stage → 0.88.0

package/dist/strategies.d.ts

@@ -0,0 +1,154 @@
+import { Effect } from 'effect';
+import { RedisStoreOptions } from '@voltro/plugin-ratelimit';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+/** Human reports never call this slot. Other categories default to review-only. */
+export declare const abuseEscalationLadder: (input: EscalationInput) => EscalationStep | null;
+
+declare const ACTION_KINDS: readonly ["warn", "mute", "chatBan", "matchmakingBan", "rankedBan", "tradeBan", "ban", "shadowBan", "nameReset", "rollback"];
+
+declare const CATEGORIES: readonly ["cheating", "abuse", "name", "spam", "griefing", "rmt"];
+
+export declare const conservativeTrustScore: (input: TrustScoreInput) => number;
+
+export declare const defaultSanctionEnforcement: ({ action, point, context }: EnforcementInput) => {
+    readonly denied: boolean;
+    readonly shadow: boolean;
+};
+
+export declare const defaultSanctionsStrategies: Readonly<{
+    escalationLadder: (input: EscalationInput) => EscalationStep | null;
+    trustScore: (input: TrustScoreInput) => number;
+    evidenceCollector: (_input: EvidenceCollectorInput) => Effect.Effect<ReadonlyArray<Readonly<Record<string, unknown>>>, SanctionsError>;
+    enforcementPoints: ({ action, point, context }: EnforcementInput) => {
+        readonly denied: boolean;
+        readonly shadow: boolean;
+    };
+}>;
+
+export declare interface EnforcementInput {
+    readonly action: Sanction;
+    readonly point: SanctionPoint;
+    readonly context: SanctionCheckContext;
+}
+
+export declare interface EscalationInput {
+    readonly category: SanctionCategory;
+    readonly count: number;
+    readonly confidence: number;
+    readonly minimumConfidence: number;
+}
+
+export declare interface EscalationStep {
+    readonly kind: SanctionKind;
+    readonly durationMs: number | null;
+}
+
+export declare interface EvidenceCollectorInput {
+    readonly subject: Subject;
+    readonly targetId: string;
+    readonly context: ReportContext;
+}
+
+/** The default makes no assertion that submitted context IDs are verified evidence. */
+export declare const noCollectedSanctionEvidence: (_input: EvidenceCollectorInput) => Effect.Effect<ReadonlyArray<Readonly<Record<string, unknown>>>, SanctionsError>;
+
+declare const POINTS: readonly ["chat", "matchmaking", "trade", "ranked", "login"];
+
+declare type ReportContext = typeof ReportContextSchema.Type;
+
+declare const ReportContextSchema: Schema.Struct<{
+    readonly channelId: Schema.optional<Schema.String>;
+    readonly messageIds: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly roomId: Schema.optional<Schema.String>;
+    readonly matchId: Schema.optional<Schema.String>;
+    readonly replayRef: Schema.optional<Schema.String>;
+}>;
+
+export declare type ResolvedSanctionsOptions = ReturnType<typeof resolveSanctionsOptions>;
+
+export declare const resolveSanctionsOptions: (input?: SanctionsOptions) => Readonly<{
+    maxActiveActions: number;
+    maxReportsPerCase: number;
+    maxEvidenceRefs: number;
+    maxContextMessageIds: number;
+    maxTextLength: number;
+    pageSize: number;
+    maxExportRows: number;
+    reportLimit: number;
+    reportWindowMs: number;
+    strikeDecayMs: number;
+    minimumSignalConfidence: number;
+    strategies: Readonly<{
+        escalationLadder: (input: EscalationInput) => EscalationStep | null;
+        trustScore: (input: TrustScoreInput) => number;
+        evidenceCollector: (_input: EvidenceCollectorInput) => Effect.Effect<ReadonlyArray<Readonly<Record<string, unknown>>>, SanctionsError>;
+        enforcementPoints: ({ action, point, context }: EnforcementInput) => {
+            readonly denied: boolean;
+            readonly shadow: boolean;
+        };
+    }>;
+    rateLimit: RedisStoreOptions | undefined;
+    now: () => number;
+}>;
+
+declare type Sanction = typeof SanctionSchema.Type;
+
+declare type SanctionCategory = typeof CATEGORIES[number];
+
+declare interface SanctionCheckContext {
+    readonly channelId?: string;
+    readonly queueId?: string;
+}
+
+declare type SanctionKind = typeof ACTION_KINDS[number];
+
+declare type SanctionPoint = typeof POINTS[number];
+
+declare const SanctionSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literals<readonly ["warn", "mute", "chatBan", "matchmakingBan", "rankedBan", "tradeBan", "ban", "shadowBan", "nameReset", "rollback"]>;
+    readonly scope: Schema.Struct<{
+        readonly channels: Schema.$Array<Schema.String>;
+        readonly queues: Schema.$Array<Schema.String>;
+    }>;
+    readonly from: Schema.Number;
+    readonly until: Schema.NullOr<Schema.Number>;
+    readonly publicReason: Schema.String;
+    readonly appealable: Schema.Boolean;
+}>;
+
+declare class SanctionsError extends SanctionsError_base {
+}
+
+declare const SanctionsError_base: Schema.Class<SanctionsError, Schema.TaggedStruct<"SanctionsError", {
+    readonly code: Schema.Literals<readonly ["identity_required", "invalid_input", "forbidden", "not_found", "conflict", "rate_limited", "sanctioned", "unavailable", "export_limit"]>;
+}>, YieldableError>;
+
+export declare interface SanctionsOptions {
+    readonly maxActiveActions?: number;
+    readonly maxReportsPerCase?: number;
+    readonly maxEvidenceRefs?: number;
+    readonly maxContextMessageIds?: number;
+    readonly maxTextLength?: number;
+    readonly pageSize?: number;
+    readonly maxExportRows?: number;
+    readonly reportLimit?: number;
+    readonly reportWindowMs?: number;
+    readonly strikeDecayMs?: number;
+    readonly minimumSignalConfidence?: number;
+    readonly strategies?: Partial<typeof defaultSanctionsStrategies>;
+    readonly rateLimit?: RedisStoreOptions;
+    readonly now?: () => number;
+}
+
+export declare interface TrustScoreInput {
+    readonly strikes: number;
+    readonly verifiedAccountAgeMs: number | null;
+    readonly verifiedPlatform: boolean;
+    readonly verifiedPaymentCount: number;
+}
+
+export { }

package/dist/strategies.js

@@ -0,0 +1,72 @@
+import { sanctionsError as e } from "./errors.js";
+import { Effect as t } from "effect";
+// src/strategies.ts
+var n = [
+	{
+		kind: "warn",
+		durationMs: null
+	},
+	{
+		kind: "mute",
+		durationMs: 36e5
+	},
+	{
+		kind: "mute",
+		durationMs: 864e5
+	},
+	{
+		kind: "chatBan",
+		durationMs: 6048e5
+	},
+	{
+		kind: "ban",
+		durationMs: 2592e6
+	},
+	{
+		kind: "ban",
+		durationMs: null
+	}
+], r = (e) => e.category === "abuse" && e.confidence >= e.minimumConfidence ? n[Math.min(n.length - 1, Math.max(0, e.count - 1))] ?? null : null, i = (e) => Math.max(0, Math.min(100, 50 - Math.min(50, e.strikes * 5) + (e.verifiedPlatform ? 10 : 0) + Math.min(10, e.verifiedPaymentCount * 2) + (e.verifiedAccountAgeMs === null ? 0 : Math.min(20, Math.floor(e.verifiedAccountAgeMs / 864e5 / 30))))), a = (e) => t.succeed([]), o = (e, t, n) => t === "chat" ? e.channels.length === 0 || n.channelId === void 0 || e.channels.includes(n.channelId) : t === "matchmaking" || t === "ranked" ? e.queues.length === 0 || n.queueId === void 0 || e.queues.includes(n.queueId) : !0, s = ({ action: e, point: t, context: n }) => ({
+	denied: e.kind === "ban" || o(e.scope, t, n) && (t === "chat" && (e.kind === "mute" || e.kind === "chatBan") || t === "matchmaking" && e.kind === "matchmakingBan" || t === "ranked" && (e.kind === "rankedBan" || e.kind === "matchmakingBan") || t === "trade" && e.kind === "tradeBan"),
+	shadow: t === "matchmaking" && e.kind === "shadowBan" && o(e.scope, t, n)
+}), c = Object.freeze({
+	escalationLadder: r,
+	trustScore: i,
+	evidenceCollector: a,
+	enforcementPoints: s
+}), l = (t = {}) => {
+	let n = {
+		maxActiveActions: t.maxActiveActions ?? 100,
+		maxReportsPerCase: t.maxReportsPerCase ?? 1e3,
+		maxEvidenceRefs: t.maxEvidenceRefs ?? 100,
+		maxContextMessageIds: t.maxContextMessageIds ?? 41,
+		maxTextLength: t.maxTextLength ?? 4e3,
+		pageSize: t.pageSize ?? 50,
+		maxExportRows: t.maxExportRows ?? 1e4,
+		reportLimit: t.reportLimit ?? 10,
+		reportWindowMs: t.reportWindowMs ?? 36e5,
+		strikeDecayMs: t.strikeDecayMs ?? 2592e6,
+		minimumSignalConfidence: t.minimumSignalConfidence ?? .99,
+		strategies: Object.freeze({
+			...c,
+			...t.strategies
+		}),
+		rateLimit: t.rateLimit,
+		now: t.now ?? Date.now
+	};
+	for (let [t, r] of [
+		[n.maxActiveActions, 1e4],
+		[n.maxReportsPerCase, 1e5],
+		[n.maxEvidenceRefs, 1e3],
+		[n.maxContextMessageIds, 1e3],
+		[n.maxTextLength, 2e4],
+		[n.pageSize, 200],
+		[n.maxExportRows, 1e5],
+		[n.reportLimit, 1e4],
+		[n.reportWindowMs, 864e5],
+		[n.strikeDecayMs, 31536e7]
+	]) if (!Number.isSafeInteger(t) || t < 1 || t > r) throw e("invalid_input");
+	if (!Number.isFinite(n.minimumSignalConfidence) || n.minimumSignalConfidence < 0 || n.minimumSignalConfidence > 1 || typeof n.now != "function" || Object.values(n.strategies).some((e) => typeof e != "function")) throw e("invalid_input");
+	return Object.freeze(n);
+};
+export { r as abuseEscalationLadder, i as conservativeTrustScore, s as defaultSanctionEnforcement, c as defaultSanctionsStrategies, a as noCollectedSanctionEvidence, l as resolveSanctionsOptions };

package/dist/testing.d.ts

@@ -0,0 +1,211 @@
+import { Context } from 'effect';
+import { Effect } from 'effect';
+import { Layer } from 'effect';
+import { Schema } from 'effect';
+import { Subject } from '@voltro/protocol';
+import { YieldableError } from 'effect/Cause';
+
+declare const ACTION_KINDS: readonly ["warn", "mute", "chatBan", "matchmakingBan", "rankedBan", "tradeBan", "ban", "shadowBan", "nameReset", "rollback"];
+
+declare const CATEGORIES: readonly ["cheating", "abuse", "name", "spam", "griefing", "rmt"];
+
+declare const DecisionSchema: Schema.Struct<{
+    readonly allowed: Schema.Boolean;
+    readonly actionIds: Schema.$Array<Schema.String>;
+    readonly shadow: Schema.Boolean;
+}>;
+
+declare interface EnforcementInput {
+    readonly action: Sanction;
+    readonly point: SanctionPoint;
+    readonly context: SanctionCheckContext;
+}
+
+declare interface EscalationInput {
+    readonly category: SanctionCategory;
+    readonly count: number;
+    readonly confidence: number;
+    readonly minimumConfidence: number;
+}
+
+declare interface EscalationStep {
+    readonly kind: SanctionKind;
+    readonly durationMs: number | null;
+}
+
+declare interface EvidenceCollectorInput {
+    readonly subject: Subject;
+    readonly targetId: string;
+    readonly context: ReportContext;
+}
+
+export declare const fakeSanctionsLayer: (overrides?: Partial<SanctionsService>) => Layer.Layer<SanctionsPort, never, never>;
+
+export declare const fakeSanctionsService: (overrides?: Partial<SanctionsService>) => SanctionsService;
+
+declare const POINTS: readonly ["chat", "matchmaking", "trade", "ranked", "login"];
+
+declare type ReportContext = typeof ReportContextSchema.Type;
+
+declare const ReportContextSchema: Schema.Struct<{
+    readonly channelId: Schema.optional<Schema.String>;
+    readonly messageIds: Schema.optional<Schema.$Array<Schema.String>>;
+    readonly roomId: Schema.optional<Schema.String>;
+    readonly matchId: Schema.optional<Schema.String>;
+    readonly replayRef: Schema.optional<Schema.String>;
+}>;
+
+declare type Sanction = typeof SanctionSchema.Type;
+
+declare type SanctionCategory = typeof CATEGORIES[number];
+
+declare interface SanctionCheckContext {
+    readonly channelId?: string;
+    readonly queueId?: string;
+}
+
+declare type SanctionDecision = typeof DecisionSchema.Type;
+
+declare type SanctionKind = typeof ACTION_KINDS[number];
+
+declare type SanctionPoint = typeof POINTS[number];
+
+declare const SanctionSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly kind: Schema.Literals<readonly ["warn", "mute", "chatBan", "matchmakingBan", "rankedBan", "tradeBan", "ban", "shadowBan", "nameReset", "rollback"]>;
+    readonly scope: Schema.Struct<{
+        readonly channels: Schema.$Array<Schema.String>;
+        readonly queues: Schema.$Array<Schema.String>;
+    }>;
+    readonly from: Schema.Number;
+    readonly until: Schema.NullOr<Schema.Number>;
+    readonly publicReason: Schema.String;
+    readonly appealable: Schema.Boolean;
+}>;
+
+export declare const sanctionsEnforcementFixture: {
+    kind: "slot";
+    defaultImplementation: ({ action, point, context }: EnforcementInput) => {
+        readonly denied: boolean;
+        readonly shadow: boolean;
+    };
+    defaultProbe: {
+        run: () => Effect.Effect<{
+            readonly denied: boolean;
+            readonly shadow: boolean;
+        }, never, never>;
+        expected: {
+            denied: boolean;
+            shadow: boolean;
+        };
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<{
+            readonly denied: boolean;
+            readonly shadow: boolean;
+        }, never, never>;
+        expected: {
+            denied: boolean;
+            shadow: boolean;
+        };
+    };
+};
+
+declare class SanctionsError extends SanctionsError_base {
+}
+
+declare const SanctionsError_base: Schema.Class<SanctionsError, Schema.TaggedStruct<"SanctionsError", {
+    readonly code: Schema.Literals<readonly ["identity_required", "invalid_input", "forbidden", "not_found", "conflict", "rate_limited", "sanctioned", "unavailable", "export_limit"]>;
+}>, YieldableError>;
+
+export declare const sanctionsEscalationFixture: {
+    kind: "slot";
+    defaultImplementation: (input: EscalationInput) => EscalationStep | null;
+    defaultProbe: {
+        run: () => Effect.Effect< EscalationStep | null, never, never>;
+        expected: {
+            kind: string;
+            durationMs: number;
+        };
+    };
+    overrideProbe: {
+        run: () => Effect.Effect< EscalationStep | null, never, never>;
+        expected: null;
+    };
+};
+
+export declare const sanctionsEvidenceFixture: {
+    kind: "slot";
+    defaultImplementation: (_input: EvidenceCollectorInput) => Effect.Effect<ReadonlyArray<Readonly<Record<string, unknown>>>, SanctionsError>;
+    defaultProbe: {
+        run: () => Effect.Effect<readonly Readonly<Record<string, unknown>>[], SanctionsError, never>;
+        expected: never[];
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<readonly Readonly<Record<string, unknown>>[], SanctionsError, never>;
+        expected: {
+            source: string;
+            verified: boolean;
+        }[];
+    };
+};
+
+export declare const sanctionsFakeLayer: Layer.Layer<SanctionsPort, never, never>;
+
+/** Other systems consult this small port rather than sanction SQL or an app-local enforcement map. */
+declare class SanctionsPort extends SanctionsPort_base {
+}
+
+declare const SanctionsPort_base: Context.ServiceClass<SanctionsPort, "@voltro/SanctionsPort", SanctionsService>;
+
+export declare const sanctionsPortFixture: {
+    kind: "port";
+    tag: typeof SanctionsPort;
+    fakeLayer: Layer.Layer<SanctionsPort, never, never>;
+    probe: {
+        run: () => Effect.Effect<"unavailable" | "conflict" | {
+            readonly allowed: boolean;
+            readonly actionIds: readonly string[];
+            readonly shadow: boolean;
+        } | "identity_required" | "invalid_input" | "forbidden" | "not_found" | "rate_limited" | "sanctioned" | "export_limit", never, never>;
+        expected: string;
+    };
+};
+
+declare interface SanctionsService {
+    readonly check: (subject: Subject, point: SanctionPoint, context?: SanctionCheckContext) => Effect.Effect<SanctionDecision, SanctionsError>;
+    readonly active: (subject: Subject) => Effect.Effect<ReadonlyArray<Sanction>, SanctionsError>;
+    readonly trust: (subject: Subject) => Effect.Effect<number, SanctionsError>;
+    readonly recordSignal: (subject: Subject, input: TrustedSanctionSignal) => Effect.Effect<void, SanctionsError>;
+}
+
+export declare const sanctionsTrustFixture: {
+    kind: "slot";
+    defaultImplementation: (input: TrustScoreInput) => number;
+    defaultProbe: {
+        run: () => Effect.Effect<number, never, never>;
+        expected: number;
+    };
+    overrideProbe: {
+        run: () => Effect.Effect<number, never, never>;
+        expected: number;
+    };
+};
+
+declare interface TrustedSanctionSignal {
+    readonly tenantId: string;
+    readonly targetId: string;
+    readonly requestId: string;
+    readonly category: SanctionCategory;
+    readonly confidence: number;
+    readonly context?: ReportContext;
+}
+
+declare interface TrustScoreInput {
+    readonly strikes: number;
+    readonly verifiedAccountAgeMs: number | null;
+    readonly verifiedPlatform: boolean;
+    readonly verifiedPaymentCount: number;
+}
+
+export { }

package/dist/testing.js

@@ -0,0 +1,120 @@
+import { sanctionsError as e } from "./errors.js";
+import { SanctionsPort as t } from "./port.js";
+import { abuseEscalationLadder as n, conservativeTrustScore as r, defaultSanctionEnforcement as i, noCollectedSanctionEvidence as a, resolveSanctionsOptions as o } from "./strategies.js";
+import { Effect as s, Layer as c, Result as l } from "effect";
+// src/testing.ts
+var u = (t = {}) => ({
+	check: () => s.fail(e("unavailable")),
+	active: () => s.fail(e("unavailable")),
+	trust: () => s.fail(e("unavailable")),
+	recordSignal: () => s.fail(e("unavailable")),
+	...t
+}), d = (e = {}) => c.sync(t, () => u(e)), f = d(), p = {
+	kind: "port",
+	tag: t,
+	fakeLayer: f,
+	probe: {
+		run: () => s.scoped(t.pipe(s.flatMap((e) => e.check({
+			type: "user",
+			id: "one",
+			tenantId: "tenant"
+		}, "chat")), s.result, s.map((e) => l.isFailure(e) ? e.failure.code : e.success), s.provide(f))),
+		expected: "unavailable"
+	}
+}, m = {
+	category: "abuse",
+	count: 2,
+	confidence: 1,
+	minimumConfidence: .99
+}, h = {
+	kind: "slot",
+	defaultImplementation: n,
+	defaultProbe: {
+		run: () => s.sync(() => n(m)),
+		expected: {
+			kind: "mute",
+			durationMs: 36e5
+		}
+	},
+	overrideProbe: {
+		run: () => s.sync(() => o({ strategies: { escalationLadder: () => null } }).strategies.escalationLadder(m)),
+		expected: null
+	}
+}, g = {
+	strikes: 2,
+	verifiedAccountAgeMs: null,
+	verifiedPlatform: !1,
+	verifiedPaymentCount: 0
+}, _ = {
+	kind: "slot",
+	defaultImplementation: r,
+	defaultProbe: {
+		run: () => s.sync(() => r(g)),
+		expected: 40
+	},
+	overrideProbe: {
+		run: () => s.sync(() => o({ strategies: { trustScore: () => 7 } }).strategies.trustScore(g)),
+		expected: 7
+	}
+}, v = {
+	subject: {
+		type: "user",
+		id: "one",
+		tenantId: "tenant"
+	},
+	targetId: "two",
+	context: { channelId: "channel" }
+}, y = {
+	kind: "slot",
+	defaultImplementation: a,
+	defaultProbe: {
+		run: () => a(v),
+		expected: []
+	},
+	overrideProbe: {
+		run: () => o({ strategies: { evidenceCollector: () => s.succeed([{
+			source: "fixture",
+			verified: !0
+		}]) } }).strategies.evidenceCollector(v),
+		expected: [{
+			source: "fixture",
+			verified: !0
+		}]
+	}
+}, b = {
+	action: {
+		id: "action",
+		kind: "chatBan",
+		scope: {
+			channels: [],
+			queues: []
+		},
+		from: 0,
+		until: null,
+		publicReason: "Policy",
+		appealable: !0
+	},
+	point: "chat",
+	context: {}
+}, x = {
+	kind: "slot",
+	defaultImplementation: i,
+	defaultProbe: {
+		run: () => s.sync(() => i(b)),
+		expected: {
+			denied: !0,
+			shadow: !1
+		}
+	},
+	overrideProbe: {
+		run: () => s.sync(() => o({ strategies: { enforcementPoints: () => ({
+			denied: !1,
+			shadow: !1
+		}) } }).strategies.enforcementPoints(b)),
+		expected: {
+			denied: !1,
+			shadow: !1
+		}
+	}
+};
+export { d as fakeSanctionsLayer, u as fakeSanctionsService, x as sanctionsEnforcementFixture, h as sanctionsEscalationFixture, y as sanctionsEvidenceFixture, f as sanctionsFakeLayer, p as sanctionsPortFixture, _ as sanctionsTrustFixture };