Architecture Overview
This document provides a high-level overview of the Prividium™ architecture and its components.
High Level Architecture
Actors & Auth Model
Prividium™ distinguishes three types of actors that interact with the system:
| Actor | What it represents | Auth Mechanism | Functionality |
|---|---|---|---|
| Organizations | A third-party organization. | None (admin-managed) | Group users under a shared identity, configure org-level settings, and scope roles/permissions per organization. |
| User Apps | A registered client application that end-users interact with (e.g. a dApp, a web portal, or a mobile app). | No direct app auth — relies on the user's OIDC/SIWE token. | Provide "Login with Prividium" functionality, appear in the User Panel for discovery, and define OAuth redirect URIs. |
| M2M Apps | A backend system or machine integration (e.g. an indexer, a CI pipeline, or a monitoring service). | API keys | Authenticate without a user session, call the API with app-level permissions, and perform automated operations. |
Migrating from the Legacy Model
The previous model used Tenants, Apps, and Services. Tenants handled both user grouping and machine authentication, while Services provided a separate M2M mechanism using SIWE. This created overlap and confusion — particularly between tenants and multi-tenancy, which are unrelated concepts.
The new model cleanly separates concerns: Organizations only group users, User Apps only handle user-facing OAuth, and M2M Apps are the single model for all machine access using API keys.
Legacy model:
| Actor | What it represents | Auth Mechanism | Functionality |
|---|---|---|---|
| Tenants | A third-party organization | SIWE, API keys | Manage users, read data from them |
| Apps | A registered client app | No direct app auth (uses user token) | Login with Prividium functionality |
| Services | M2M integration | SIWE | M2M API and service RPC access |
Migration mapping:
| Legacy pattern | New model |
|---|---|
| Tenant grouping (organizing users under an entity) | Organizations |
| Tenant machine operations (create user, attach wallet) | M2M Apps with organization-level permissions |
| Service integrations (RPC reads, contract metadata) | M2M Apps with system permissions |
Authorization Model
Prividium™ implements a Zero-Trust, per-request authorization model using industry-standard patterns. Every request is evaluated by a single Policy Decision Point (PDP) — the Prividium™ API — and enforced at the Policy Enforcement Points (PEPs): the RPC proxy (and additional enforcement layers depending on deployment). Nothing is implicitly trusted by network location.
The model combines two complementary mechanisms:
- Role-Based Access Control (RBAC) for platform actions — what a principal may do in the system. Roles carry system permissions (e.g. read access, contract deployment, admin access), following the standard users → roles → permissions model.
- Attribute-Based Access Control (ABAC) for fine-grained conditions — e.g. a function rule that only permits a call when an address argument equals the caller's own wallet, or an event rule scoped to the caller's address. These are attribute predicates evaluated per request.
Identity vs. authority
Authentication (OIDC or SIWE) establishes who the caller is. Authorization (roles + permissions) determines what they may do. A wallet is an attribute the caller must own to act from a given on-chain address — it is not the principal.
Delegation
- Transaction authorizations are single-use, short-lived capabilities: an authenticated user pre-authorizes one specific transaction (exact wallet, recipient, nonce, calldata, and value) for a limited time, so an unattended client such as a browser wallet can submit exactly that transaction and nothing else. This is distinct from an ERC-20 token allowance.
- M2M Apps act on behalf of a backend system using API keys with app-level permissions.
Vocabulary mapping
For teams accustomed to standard access-control terminology:
| Prividium™ term | Standard equivalent |
|---|---|
| System permissions (on roles) | RBAC roles & permissions |
| Contract function / event / argument rules | ABAC attribute predicates |
| Prividium™ API authorization check | Policy Decision Point (PDP) |
| RPC proxy enforcement | Policy Enforcement Point (PEP) |
| Transaction authorization | Single-use bearer capability (least authority) |
| OIDC / SIWE login | OpenID Connect / Sign-In with Ethereum |
Prividium™ Core Components
User Panel
Vue 3 application for users to:
- Authenticate via OIDC or Web3 wallet.
- Associate wallets and manage user profile.
- View assigned permissions.
Prividium™ API
Fastify-based backend service providing:
REST API:
- Authentication via OIDC and Web3 (SIWE)
- User, role, and permission management
- Contract and template configuration
RPC Proxy:
- Permission-enforced JSON-RPC proxy to ZKsync node
- Wallet RPC for Per-User RPC URLs
Permission System (PostgreSQL):
- Role-based access control
- Function-level contract permissions with argument validation
- Event-level permissions
- Reusable permission templates
Admin Panel
Vue 3 application for administrators to:
- Manage contract metadata and permissions
- Configure function-level permissions with argument validation
- Assign user roles and manage user-role relationships
Prividium™ Block Explorer
Specialized implementation of the ZKsync Block Explorer for Prividium™ authentication and privacy support.
For more details, please refer to ZKsync Block Explorer repository.
Prividium™ SDK & CLI
A TypeScript SDK and CLI for integrating with the Prividium™ authorization system.
SDK:
- Popup-based OAuth authentication
- Token management with automatic expiration handling
- Viem transport with auth headers
- Wallet integration (network setup, transaction authorization)
CLI:
- Local authenticated JSON-RPC proxy (
prividium proxy) - Configuration management
See: Prividium™ SDK & CLI.
Example Flow: User accessing a contract function with restricted access
- Client makes RPC call via dApp, wallet or Explorer.
- SDK adds access token to Authorization header
- Prividium™ API receives the RPC call and, acting as the Policy Decision Point (PDP), performs the authorization check based on the configured permissions for the contract function stored in the Prividium™ Permission System Database.
- If authorized, Prividium™ API forwards requests to ZKsync node.
- Prividium™ API applies response filtering based on user permissions.
- Prividium™ API returns filtered response to client.