@voltro/plugin-sanctions 0.0.0-stage → 0.88.0

package/LICENSE

@@ -0,0 +1,61 @@
+Voltro — Proprietary Software License
+
+Copyright (c) 2026 Voltro UG. All rights reserved.
+
+This software and all associated source code, documentation, and other
+materials (the "Software") are the proprietary property of Voltro UG
+("Voltro"). This is NOT open-source software.
+
+Your access to and use of the Software is governed exclusively by the Voltro
+Terms of Service at:
+
+    https://voltro.cloud/legal/terms
+
+By downloading, installing, or using the Software you agree to those Terms.
+Subject to and conditioned on your continued compliance with them, Voltro
+grants you a limited, non-exclusive, non-transferable, non-sublicensable,
+revocable license to use the Software. The license covers use by your
+authorised named users only, up to the number of seats (or other billing metric)
+your plan or order covers; each named user must be an identified individual
+using their own personal account, and accounts, access credentials and seats
+must not be shared. All rights not expressly granted in the
+Terms are reserved by Voltro. If you do not agree to the Terms, you have no
+license and may not use the Software.
+
+The Terms of Service — including the scope of permitted use, plan
+entitlements, fees, and pricing — may change from time to time. The version in
+force is the one published at the URL above. Commercial terms and pricing are
+NOT part of this notice and are not fixed by, or granted in perpetuity by, the
+version of the Software in which this file appears.
+
+Permitted use — your own software. Voltro is a development framework. You may
+use the Software to build, run, and commercially distribute your own
+applications and services, and to charge your own customers for them, without
+owing Voltro any share of that revenue or any further permission beyond the
+Terms. Applications you build with the Software are yours.
+
+Prohibited use — reselling Voltro. You may NOT redistribute, resell,
+sublicense, publish, or otherwise provide the Software itself — in whole or in
+part, in source or compiled form — to third parties as a library, framework,
+SDK, template, starter, or development tool for them to build upon, whether
+standalone or repackaged. Shipping the Software as a non-separable, bundled
+dependency inside an application you deliver (for example, compiled into your
+deployed app) is permitted; extracting or re-exposing it as a reusable
+component for others is not.
+
+Except as expressly permitted above or by the Terms, you may not copy, modify,
+merge, publish, sublicense, sell, distribute, or create derivative works of the
+Software, in whole or in part.
+
+Third-party open-source components distributed alongside the Software are the
+property of their respective owners and are licensed under their own terms; see
+THIRD-PARTY-NOTICES.md where provided. Nothing in this notice limits your
+rights, or extends Voltro's, in those components.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL
+VOLTRO BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS USE.
+
+For licensing inquiries, contact Voltro UG.

package/README.md

@@ -1,3 +1,199 @@
-# Temporary Holding Version
+# @voltro/plugin-sanctions
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+## Take
+
+```ts
+import { sanctionsPlugin } from '@voltro/plugin-sanctions'
+
+const plugin = sanctionsPlugin()
+```
+
+The factory declares seven SQL tables: `_voltro_sanc_reports`,
+`_voltro_sanc_cases`, `_voltro_sanc_actions`, `_voltro_sanc_appeals`,
+`_voltro_sanc_strikes`, `_voltro_sanc_device_hints`, `_voltro_sanc_admissions`.
+SQL owns durable state and successor readback. It contributes eleven typed
+RPCs, eleven client hooks, four rule slots, SanctionsPort, metadata events,
+configuration inspection and user/guest export/erase hooks. There is no Room
+tick I/O or independent Redis connection.
+
+Actions are `sanctions.report`, `appeal`, `reviewCase`, `issue`, `revoke`,
+`reviewAppeal`; queries are `sanctions.reportsMine`, `mine`, `appealsMine`,
+`cases`, `appealsQueue`. Human/guest identity and tenant come from the verified
+request. Operator reads/writes require a trusted user/service account carrying
+`sanctions:manage` or `admin:full`; a request payload cannot grant these scopes.
+The operator projection includes evidence references and decision identity;
+player measures include only kind, scope, dates, public reason and appealability.
+Internal reason, issuer, target identity and metadata never appear in that view.
+
+A report contains request ID, target, category, bounded context IDs and note.
+It groups into the target's case and is idempotent for the exact intention;
+changed content under the same request ID refuses. **Human reports never call
+the automatic escalation ladder.** The default collector returns no verified
+evidence: a submitted message/replay ID is context, not verified evidence.
+
+## Configure
+
+| Option | Default | Meaning |
+|---|---|---|
+| `maxActiveActions` | 100 | Active measure admission budget per subject |
+| `maxReportsPerCase` | 1,000 | Report budget per case |
+| `maxEvidenceRefs` | 100 | Collected evidence reference budget per case |
+| `maxContextMessageIds` | 41 | Submitted message-context budget |
+| `maxTextLength` | 4,000 code points | Notes/reasons/appeal text limit |
+| `pageSize` | 50 | Raw SQL read page budget |
+| `maxExportRows` | 10,000 | Complete bounded export; overflow refuses |
+| `reportLimit` | 10 | Report attempts per window |
+| `reportWindowMs` | 3,600,000 | Report admission window |
+| `strikeDecayMs` | 2,592,000,000 | Lazy strike expiry window |
+| `minimumSignalConfidence` | 0.99 | Minimum trusted signal confidence for strikes |
+| `rateLimit` | Registry Redis | Existing limiter connection/HotStore options |
+| `strategies` | four defaults | Named rule replacements |
+| `now` | `Date.now` | Clock for rule/observation instants |
+
+These are configured budgets, not measured capacity. Report admission uses the
+Registry-backed HotStore limiter. Unbound/fail-open/store-error decisions refuse
+new reports; exact committed retries are read before rate consumption. Borrowed
+HotStore state refuses activation with declared multi-node evidence. A named
+Registry memory transport is a local example and cannot supply cross-node data.
+
+Subject admission rows acquire SQL writer admission in deterministic hash order
+before measures, counts and reviews. Case reviews require `baseVersion`.
+Issue intentions retain their receipt after expiry/revocation. An action may be
+permanent or expire; revoked, future and expired rows do not enforce policy.
+Appeals are once per action/owner, preserve exact retry text and allow one
+review outcome; `revoked` also revokes the action transactionally.
+
+## Hook
+
+`SanctionsPort` from `./port` has four methods: `check(subject, point, context?)`,
+`active(subject)`, `trust(subject)`, `recordSignal(subject, input)`. The SQL
+adapter reads policy afresh. The default matrix applies bans at all points,
+mute/chatBan to chat, matchmakingBan to matchmaking/ranked, rankedBan to ranked,
+tradeBan to trade; shadowBan marks only matchmaking. Channel/queue context
+selects an exact scope. Omitted context conservatively matches restricted scopes.
+Warnings, nameReset and rollback do not themselves execute game mutations.
+
+Only System or an explicitly authorized same-tenant service account can submit
+trusted signals. Low-confidence signals stay in review; high-confidence abuse
+signals increment once and use warn → mute 1h → mute 24h → chatBan 7d → ban 30d
+→ permanent ban. Other categories default to review only. Trust uses current
+non-expired strikes; unverified account age/platform/payment facts remain
+unknown. The service does not manufacture those facts.
+
+The discovered `sanctions.changed` producer carries only action ID under a
+subject routing key, with `sanctions:events:read` for operator listeners. It
+uses committed tenant evidence and suppresses erased identities. Delivery is
+best-effort. Automatic HotStore policy caching, live auth-cache invalidation,
+Replay/chat evidence collectors and Inbox notification remain integration work.
+
+Chat consults the installed port with the actual channel before new sends/edits;
+denial gives `sanctioned`, unavailable policy refuses. An exact already committed
+send retry returns its original receipt. Deletion remains available. Chat without
+the optional port has no sanction policy. This admission is not an atomic
+cross-plugin transaction with a concurrent sanction write.
+
+`./guard` exports `sanctionsLoginGuard(service)` for Auth's pre-session guard
+and `sanctionsSubjectGuard(service)` for request-side auth composition. Both use
+the supplied actual check service and refuse unavailability. They are opt-in;
+installing Sanctions alone does not alter an Auth default. A request-side guard
+cached by a host still needs its explicit invalidation integration.
+
+## Override
+
+`./strategies` exports `abuseEscalationLadder` (`escalationLadder`),
+`conservativeTrustScore` (`trustScore`), `noCollectedSanctionEvidence`
+(`evidenceCollector`), `defaultSanctionEnforcement` (`enforcementPoints`).
+Each default has a real replacement probe in `./testing`.
+
+```ts
+import { sanctionsPlugin } from '@voltro/plugin-sanctions'
+
+const plugin = sanctionsPlugin({
+  strategies: { escalationLadder: () => null },
+})
+```
+
+## Extend or replace
+
+Other systems depend on `./port`, not sanction tables. Install a replacement
+Layer for the four-method port; `fakeSanctionsLayer(overrides)` defaults every
+unimplemented method to `unavailable`, never an implicit allow. The explicit
+`dataStoreSanctions(store, resolveSanctionsOptions(options), limiter)` adapter
+exposes its API/port and trusted device-hint/privacy methods.
+
+Device hints require a supplied server-owned random salt of at least 32 bytes;
+the adapter persists only a tenant-bound HMAC. No salt is shipped or read from
+an undeclared env name. The template does not collect hints. Hints are evidence
+for review, never a hardware-ban guarantee.
+
+Export selects bounded exact tenant/subject references across all seven tables.
+Erase removes device/strike rows, redacts reports, evidence, reasons and appeal
+text, revokes the erased target's measures, retains peers and leaves a redacted
+admission tombstone. Sorted writer fences cover subject and related targets;
+a changed reference set retries before redaction. Erased identity cannot create
+new measures/reports/signals and check refuses it. Reactivation, identity merge,
+namespace/mixins, custom-column query/UI propagation and stack removal remain open.
+
+## Panel and GM
+
+The server `/status`, shared SanctionsPage, Local read-token provider and Cloud
+authorized-app/replica proxy display configuration, slots, limiter activation
+and store binding. They do not enumerate cases or claim backend health/capacity.
+The operator RPC queue/review actions are written. Full GM evidence views,
+history, audit receipts, governed bulk approval and replay scrubber remain open;
+install `plugin-audit` with its durable sink for the framework RPC audit path.
+
+`./web` provides ReportDialog, SanctionNotice and AppealDialog with EN/DE labels.
+They render escaped public text, scope-fence stale observations and keep drafts,
+request IDs and uncertain pending writes in the parent. No component automatically
+replays a request or discards a draft. Presence/profile/Chat report wiring remains
+for the composed frontend template.
+
+## Tests
+
+Written fixtures cover the default kind × point matrix, scoped/future/expired/
+revoked decisions, human/trusted separation, rates, exact receipts, one appeal,
+case versions, replacement slots/port, opt-in guards, device redaction and
+privacy. `systemContractConformance` registers all slots/port/events, inspect
+and user/guest hooks for all seven tables. Five native cases per six dialects
+cover round trips, two-pool admission/versioning and successor privacy; missing
+native configuration refuses the fixture rather than skipping acceptance. No
+Scheduled Run number, budget or support claim is inferred from file existence.
+
+## Prepared SQL permission admission
+
+`SanctionsPlugin.sanctions.admission()` returns a server-only
+`SanctionsSqlAdmissionService` with `read(subject, { point, at, context? })` and
+`prepare(subject, { point, at, context?, expected })`. The app supplies captured
+server time; there is no player RPC accepting time or permission facts. `read`
+returns actual `allowed` and strike-derived `trustScore`. It borrows the existing
+seven SQL roles and the same active-measure, trust and enforcement rules; missing
+verified account/payment facts receive no invented bonus. The ordinary four-method
+`SanctionsPort` stays unchanged.
+
+The service reads a complete bounded action/strike snapshot under the owning
+SQL subject fence. Pure trust/enforcement slots run after that snapshot
+transaction ends. `prepare` checks the expected permission and returns an
+exact-store `PreparedSqlMutation<void>`. Its acceptance locks the same subject
+fence and compares actual SQL records with the captured fingerprint. A changed
+measure, strike or erased identity refuses; the whole enclosing asset group
+rolls back. Clock, slots and external reads do not run in this replayable commit.
+The installed wrapper revokes escaped prepared capabilities after deactivation.
+No new table, automatic trade permission, consent/age record or player state
+endpoint is introduced. The owning policy's configured work bounds remain budgets.
+
+The four configuration inspect layers expose `atomicAdmissionInstalled:true`;
+binding state remains separate. This declares a capability, not successful
+runtime enforcement or SQL health.
+
+`prepareMany({ tenantId, point, at, context?, participants })` prepares one
+complete permission unit for multiple expected owner facts, with a configured
+32-participant budget. All subject fences follow the owning SQL adapter's same
+canonical order in snapshot and commit. `prepare` delegates its single
+participant to that same path. The Trade adapter uses this batch capability for
+both parties, so reversed trades do not choose competing participant lock
+orders. Duplicate, oversized, sparse or accessor-owned inputs refuse.
+
+Production activation now source-checks the actual deployment-wide plugin grant.
+Declare actual Licensing first; development/test remains free. See the bilingual
+Licensing contract and manual update migration.

package/SECURITY.md

@@ -0,0 +1,56 @@
+# Security Policy
+
+We take the security of Voltro and the applications built on it seriously. This
+document explains how to report a vulnerability and what to expect in return.
+
+## Reporting a vulnerability
+
+**Please do not open public issues or discuss suspected vulnerabilities in
+public channels.** Report them privately by email:
+
+**security contact: [support@voltro.dev](mailto:support@voltro.dev)**
+(subject line: `SECURITY`).
+
+Include, where you can:
+
+- the affected package(s) and version(s) (e.g. `@voltro/runtime@x.y.z`);
+- a description of the issue and its impact;
+- a minimal reproduction or proof of concept;
+- any suggested remediation.
+
+If you'd like to encrypt your report, ask in a first plain email and we'll
+arrange a key.
+
+## What to expect
+
+- **Acknowledgement** of your report within **3 business days**.
+- An initial assessment (severity, affected surface) and a remediation plan as
+  soon as we've reproduced the issue.
+- **Coordinated disclosure:** we'll agree a disclosure timeline with you and
+  credit you in the release notes if you wish. Please give us reasonable time to
+  ship a fix before any public disclosure.
+
+We do not currently run a paid bug-bounty program, but we genuinely appreciate
+responsible disclosure and will credit reporters.
+
+## Software Bill of Materials (SBOM)
+
+A CycloneDX SBOM of the third-party runtime dependency graph is generated for the
+published packages (`pnpm gen:sbom` → `sbom.cdx.json`). If your procurement or
+security team needs it, request it at
+[support@voltro.dev](mailto:support@voltro.dev).
+
+## Supported versions
+
+Voltro is pre-1.0 and ships in lockstep: **only the latest published minor of
+each `@voltro/*` package receives security fixes.** Please upgrade to the latest
+release before reporting, and pin exact versions in production.
+
+## Scope
+
+In scope: the published `@voltro/*` packages and the framework's own code.
+
+Out of scope: vulnerabilities in third-party dependencies that are already
+tracked upstream (we monitor these via a production-dependency audit gate in
+CI), and issues that require a non-default, explicitly-unsafe configuration. If
+you're unsure, report it anyway — we'd rather hear about it.