@voltro/plugin-social 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,152 @@
-# Temporary Holding Version
+# @voltro/plugin-social
 
-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 { socialPlugin } from '@voltro/plugin-social'
+
+const plugin = socialPlugin()
+```
+
+The factory declares `_voltro_social_relations`, `_voltro_social_recent` and
+`_voltro_social_settings`, sixteen typed RPCs, `SocialBlockPort`, a configuration
+inspect endpoint and user/guest export/erase hooks. SQL owns the durable graph.
+Friendships have one canonical row; requests, blocks and favorites are directed.
+A block in either direction refuses a request and invitation. Removing one block
+does not remove the other person's block or recreate an old friendship.
+
+Self routes require a verified human subject; guest upgrade keeps the stable ID.
+The tenant and acting identity come from the request, never a client row.
+Participants may request, accept incoming requests, decline, cancel, remove,
+block, unblock, favorite or change their own settings. The query routes return
+friends, the caller's directed favorites, requests, the caller's block list, recent peers, settings and suggestions.
+
+## Configure
+
+| Option | Default | Meaning |
+|---|---|---|
+| `maxFriends` | 500 | Admission budget for both people |
+| `maxPendingRequests` | 100 | Incoming plus outgoing requests per person |
+| `recentLimit` | 50 | Retained rows per recent-player owner |
+| `recentRetentionMs` | 30 days | Old rows excluded from reads and trimmed on writes |
+| `maxMatchParticipants` | 64 | Server-authorized recent-pair/block-pair input budget |
+| `requestLimit` | 10 | Request attempts per window |
+| `requestWindowMs` | 60,000 | Rate window in milliseconds |
+| `suggestionLimit` | 20 | Maximum suggestion output |
+| `maxExportRows` | 10,000 | Bounded complete export; overflow refuses |
+| `rateLimit` | Registry Redis | Existing rate-limiter connection/HotStore options |
+| `strategies` | exported defaults | Three pure rule slots |
+| `now` | `Date.now` | Clock used for retention and observations |
+
+These are configured budgets, not measured capacity. Settings default to
+`requestsFrom: 'anyone'`, private online/activity, and friend-only party invites.
+A `friends-of-friends` request needs an actual mutual SQL friendship; `nobody`
+refuses. Friendship and pending counts are read after SQL admission locks on both
+people's settings rows. There is no process-local uniqueness or graph cache.
+
+The limiter reuses `plugin-ratelimit`'s Registry-backed Redis/HotStore adapter.
+The installing app owns connections and credentials. Missing activation or a
+limiter fail-open observation refuses a request with `unavailable`; it does not
+silently admit unlimited requests. Explicit injected HotStore state is admitted
+only when deployment evidence does not declare multiple nodes. Multi-node
+activation with an injected port is refused; use the Registry Redis path.
+No independent Redis socket or counter implementation is added here.
+
+## Hook
+
+Installed source assets discover `social.requested` and `social.accepted` with
+post-commit relation subscribers. A request uses the recipient routing key;
+an accepted friendship emits to both participants. The payload only identifies
+the relation. Listeners require the explicit operator scope `social:events:read`.
+These are best-effort CDC notifications, not durable business delivery or a
+public player event stream. Publication takes its tenant from committed rows.
+Notification delivery, listener resource authorization, volatile event erasure
+and a debounced Presence `social.friendOnline` transition remain to integrate.
+
+`SocialBlockPort.recordRecent` accepts only an internal system subject or a
+same-tenant service account with `social:recent:write`. Server input contains
+`tenantId`, `participants`, `context` and optional `at`. It stores directed pairs,
+refuses client/self invocation, suppresses blocked pairs and repeated context
+rows, and trims per-owner retention/row limits transactionally. Rooms should call
+this outside the tick, after disposal. `dataStoreSocial(...).pruneRecent` is an
+explicit tenant service-account sweep; periodic scheduling remains open.
+
+## Override
+
+`strategies` accepts `suggestions`, `requestPolicy` and `recentPolicy`. Their
+single exported defaults in `@voltro/plugin-social/strategies` are
+`mutualMatchSuggestions`, `recipientRequestPolicy` and `distinctRecentPeers`.
+Suggestions use mutual SQL friendships, matching recent rows, stable sorting and
+a bounded output. Custom output must remain a subset of actual candidates;
+fabricated identities or counts are refused. The panel labels custom/default slots.
+
+`canMessage` admits existing friends or the recipient request policy, always after symmetric block refusal. This is the default DM admission seam.
+
+## Extend or replace
+
+`SocialBlockPort` from `@voltro/plugin-social/port` has five methods: `isBlocked`,
+`blockPairs`, `canMessage`, `canInvite`, `recordRecent`. Chat, party and matchmaking integrations
+should depend on that tag and provide a replacement Layer when needed. Scoped
+service-account block-pair scans need `social:blocks:read`; a human scan returns
+only pairs involving that human. A fake Layer is exported from `./testing`.
+Social's own RPCs continue using its graph adapter; replacing the dependency port
+does not remove the plugin's graph routes or tables.
+
+All three server table handles are exported; their persisted `metadata` fields
+carry small extensions. Export keeps actual custom row columns. Static query
+schemas currently do not project arbitrary mixin columns. Full S4a propagation,
+custom-column UI and the system-removal command remain open.
+
+## Panel and GM
+
+`GET /status`, shared `SocialPage`, Local HTTP provider and Cloud app-authorized,
+replica-selected proxy form the four authored panel layers. They show dated
+configuration, store binding and completed rate-backend activation. None is a
+live SQL/Redis health or capacity assertion. Graph enumeration, request-volume/
+block metrics, support relation removal and settings reset remain to build.
+
+`./web` exports `useFriends`, `useFavoriteFriends`, `useFriendRequests`, `useBlockList`,
+`useRecentPlayers`, `useSocialSuggestions`, `useSocialSettings`, `FriendsPanel`,
+`FriendRow` and `AddFriendDialog`, with en/de labels. Components use `ui-shadcn`.
+The application supplies trusted Players/Presence projections, not client roster
+names. Unknown online status remains unknown. Party/DM/profile controls are
+explicit callbacks sending only an identity intention; server admission remains
+required. Exact-name lookup/search integration is not built by the dialog.
+Its parent owns async state and search results; `FoundFriend.query` and
+`FoundFriend.scopeKey` must match the current query/session before sending.
+Closing never replays a request or clears its external pending state.
+
+## Tests
+
+Source includes transactional memory-store fixtures, native PostgreSQL/MySQL/
+MariaDB/MSSQL/SQLite/Turso cases, two independent SQL pool admission cases,
+symmetric blocks, tenant and guest identity, retention/retry, rate fail-closed,
+privacy for all tables, real event schemas, component states and panel/proxy
+contracts. Every strategy has default/override probes and the dependency port
+has a fail-closed fake Layer. `systemContractConformance` is registered against
+the real factory, descriptors, tables, slots, port, events and inspect handler.
+Missing native connection settings fail the fixture instead of claiming acceptance.
+
+No fixture has run.
+
+## Privacy and limits
+
+Export/erase covers both sides of relations and recent pairs, plus own settings,
+for user and guest targets. Erase is transactional and repeatable, preserving
+peer settings and other tenants; source fixtures encode these expectations. A
+complete bounded scan refuses overflow. Hot rate counters contain hashed
+identity tuples with window expiry; coordinated volatile counter deletion and
+full deactivation/recreation fencing remain open integration work. Presence
+joins, exact player directory lookup, periodic sweeps, notification/ Chat/party
+enforcement, full GM tooling and the thin Social/Chat template are still
+pending.
+
+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.
+
+`social.favorites` reads only the current human subject’s directed favorite rows
+in the current tenant. Reads use the existing `maxFriends` bound, refuse
+overflow and recheck exact owner/tenant equality after SQL. `useFavoriteFriends`
+consumes that live query; generated native facades capture it with the installed
+alias.

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.