@voltro/plugin-sanctions 0.0.0-stage → 0.87.0

package/dist/server.d.ts

@@ -0,0 +1,363 @@
+import { DataStore } from '@voltro/database';
+import { Effect } from 'effect';
+import { PluginPrivacyTarget } from '@voltro/protocol';
+import { PreparedSqlMutation } from '@voltro/database/sql';
+import { RateLimitStore } from '@voltro/plugin-ratelimit';
+import { RedisStoreOptions } from '@voltro/plugin-ratelimit';
+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 ACTIONS_TABLE = "_voltro_sanc_actions";
+
+declare const ADMISSIONS_TABLE = "_voltro_sanc_admissions";
+
+declare const APPEALS_TABLE = "_voltro_sanc_appeals";
+
+declare const AppealSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly actionId: Schema.String;
+    readonly text: Schema.String;
+    readonly state: Schema.Literals<readonly ["pending", "reviewed"]>;
+    readonly outcome: Schema.NullOr<Schema.Literals<readonly ["upheld", "revoked"]>>;
+    readonly createdAt: Schema.Number;
+    readonly decidedAt: Schema.NullOr<Schema.Number>;
+}>;
+
+declare namespace C {
+    export {
+        REPORTS_TABLE,
+        CASES_TABLE,
+        ACTIONS_TABLE,
+        APPEALS_TABLE,
+        STRIKES_TABLE,
+        DEVICE_HINTS_TABLE,
+        ADMISSIONS_TABLE,
+        ACTION_KINDS,
+        CATEGORIES,
+        POINTS,
+        SanctionKind,
+        SanctionCategory,
+        SanctionPoint,
+        SanctionScopeSchema,
+        ReportContextSchema,
+        ReportContext,
+        SanctionSchema,
+        ReportSchema,
+        AppealSchema,
+        CaseSchema,
+        DecisionSchema,
+        Sanction,
+        SanctionReport,
+        SanctionAppeal,
+        SanctionCase,
+        SanctionDecision,
+        SanctionScope,
+        ReportInput,
+        IssueSanctionInput,
+        SanctionCheckContext,
+        TrustedSanctionSignal
+    }
+}
+
+declare const CASES_TABLE = "_voltro_sanc_cases";
+
+declare const CaseSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly targetId: Schema.NullOr<Schema.String>;
+    readonly reports: Schema.Number;
+    readonly evidence: Schema.$Array<Schema.$Record<Schema.String, Schema.Unknown>>;
+    readonly trustScore: Schema.Number;
+    readonly state: Schema.Literals<readonly ["open", "reviewing", "actioned", "dismissed"]>;
+    readonly decidedBy: Schema.NullOr<Schema.String>;
+    readonly decidedAt: Schema.NullOr<Schema.Number>;
+    readonly version: Schema.Number;
+}>;
+
+declare const CATEGORIES: readonly ["cheating", "abuse", "name", "spam", "griefing", "rmt"];
+
+export declare const dataStoreSanctions: (store: DataStore, options: ResolvedSanctionsOptions, limiter: RateLimitStore) => {
+    api: SanctionsApi;
+    port: SanctionsService;
+    admission: SanctionsSqlAdmissionService;
+    operator: SanctionsOperatorService;
+    recordDeviceHint: (subject: Subject, input: {
+        readonly tenantId: string;
+        readonly subjectId: string;
+        readonly deviceId: string;
+    }, salt: Uint8Array) => Effect.Effect<void, SanctionsError, never>;
+    exportSubject: (target: PluginPrivacyTarget) => Effect.Effect<unknown, SanctionsError, never>;
+    eraseSubject: (target: PluginPrivacyTarget) => Effect.Effect<void, SanctionsError, never>;
+};
+
+declare const DecisionSchema: Schema.Struct<{
+    readonly allowed: Schema.Boolean;
+    readonly actionIds: Schema.$Array<Schema.String>;
+    readonly shadow: Schema.Boolean;
+}>;
+
+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;
+    };
+}>;
+
+declare const DEVICE_HINTS_TABLE = "_voltro_sanc_device_hints";
+
+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;
+}
+
+declare interface IssueSanctionInput {
+    readonly requestId: string;
+    readonly targetId: string;
+    readonly kind: SanctionKind;
+    readonly scope?: SanctionScope;
+    readonly durationMs?: number | null;
+    readonly reason: string;
+    readonly publicReason: string;
+    readonly evidenceCaseId?: string;
+    readonly appealable?: boolean;
+}
+
+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 interface ReportInput {
+    readonly requestId: string;
+    readonly targetId: string;
+    readonly category: SanctionCategory;
+    readonly context?: ReportContext;
+    readonly note?: string;
+}
+
+declare const REPORTS_TABLE = "_voltro_sanc_reports";
+
+declare const ReportSchema: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly targetId: Schema.String;
+    readonly category: Schema.Literals<readonly ["cheating", "abuse", "name", "spam", "griefing", "rmt"]>;
+    readonly state: Schema.Literals<readonly ["open", "reviewing", "actioned", "dismissed"]>;
+    readonly createdAt: Schema.Number;
+    readonly caseId: Schema.String;
+}>;
+
+declare type ResolvedSanctionsOptions = ReturnType<typeof resolveSanctionsOptions>;
+
+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 SanctionAppeal = typeof AppealSchema.Type;
+
+declare type SanctionCase = typeof CaseSchema.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 type SanctionReport = typeof ReportSchema.Type;
+
+export declare interface SanctionsAdmissionBatch extends SanctionsAdmissionRead {
+    readonly tenantId: string;
+    readonly participants: readonly {
+        readonly ownerId: string;
+        readonly expected: SanctionsPermission;
+    }[];
+}
+
+export declare interface SanctionsAdmissionPrepare extends SanctionsAdmissionRead {
+    readonly expected: SanctionsPermission;
+}
+
+export declare interface SanctionsAdmissionRead {
+    readonly point: SanctionPoint;
+    readonly at: number;
+    readonly context?: SanctionCheckContext;
+}
+
+export declare interface SanctionsApi {
+    readonly report: (subject: Subject, input: C.ReportInput) => Effect.Effect<C.SanctionReport, SanctionsError>;
+    readonly reportsMine: (subject: Subject) => Effect.Effect<ReadonlyArray<C.SanctionReport>, SanctionsError>;
+    readonly mine: (subject: Subject) => Effect.Effect<ReadonlyArray<C.Sanction>, SanctionsError>;
+    readonly appeal: (subject: Subject, input: {
+        readonly actionId: string;
+        readonly text: string;
+    }) => Effect.Effect<C.SanctionAppeal, SanctionsError>;
+    readonly appealsMine: (subject: Subject) => Effect.Effect<ReadonlyArray<C.SanctionAppeal>, SanctionsError>;
+    readonly cases: (subject: Subject) => Effect.Effect<ReadonlyArray<C.SanctionCase>, SanctionsError>;
+    readonly reviewCase: (subject: Subject, input: {
+        readonly caseId: string;
+        readonly baseVersion: number;
+        readonly state: C.SanctionCase['state'];
+    }) => Effect.Effect<C.SanctionCase, SanctionsError>;
+    readonly issue: (subject: Subject, input: C.IssueSanctionInput) => Effect.Effect<C.Sanction, SanctionsError>;
+    readonly revoke: (subject: Subject, actionId: string) => Effect.Effect<void, SanctionsError>;
+    readonly appealsQueue: (subject: Subject) => Effect.Effect<ReadonlyArray<C.SanctionAppeal>, SanctionsError>;
+    readonly reviewAppeal: (subject: Subject, input: {
+        readonly appealId: string;
+        readonly outcome: 'upheld' | 'revoked';
+    }) => Effect.Effect<C.SanctionAppeal, SanctionsError>;
+}
+
+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 type SanctionScope = typeof SanctionScopeSchema.Type;
+
+declare const SanctionScopeSchema: Schema.Struct<{
+    readonly channels: Schema.$Array<Schema.String>;
+    readonly queues: Schema.$Array<Schema.String>;
+}>;
+
+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>;
+
+/** The tenant and human operator a trusted server caller (a GM console) acts as; recorded as the issuer. */
+declare interface SanctionsOperator {
+    readonly tenantId: string;
+    readonly operatorId: string;
+}
+
+/** Server-only issue/revoke for code that already admitted its operator. No request scope is read. */
+declare interface SanctionsOperatorService {
+    readonly issue: (operator: SanctionsOperator, input: C.IssueSanctionInput) => Effect.Effect<C.Sanction, SanctionsError>;
+    readonly revoke: (operator: SanctionsOperator, actionId: string) => Effect.Effect<void, SanctionsError>;
+}
+
+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 SanctionsPermission {
+    readonly allowed: boolean;
+    readonly trustScore: number;
+}
+
+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>;
+}
+
+/** Server-only capability; the small ordinary SanctionsPort remains unchanged. */
+export declare interface SanctionsSqlAdmissionService {
+    readonly read: (subject: Subject, input: SanctionsAdmissionRead) => Effect.Effect<SanctionsPermission, SanctionsError>;
+    readonly prepare: (subject: Subject, input: SanctionsAdmissionPrepare) => Effect.Effect<PreparedSqlMutation<void>, SanctionsError>;
+    readonly prepareMany: (input: SanctionsAdmissionBatch) => Effect.Effect<PreparedSqlMutation<void>, SanctionsError>;
+}
+
+declare const STRIKES_TABLE = "_voltro_sanc_strikes";
+
+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/server.js

@@ -0,0 +1 @@
+export { dataStoreSanctions } from "./service.js";