User and Team Management

User & Team Management

Introduction

The User & Team Management system in SecondLayer provides identity management, access control, and collaborative structures for the platform. It supports multi-provider authentication, organization-based team hierarchies, role-based permissions, and matter-level data isolation for legal work.

The system integrates with the MCP (Model Context Protocol) architecture, ensuring that user context and permissions are consistently enforced across the web frontend, backend HTTP API, and distributed MCP clients (stdio, SSE).

Authentication

SecondLayer supports multiple authentication methods, selectable by the user at login:

Method	Description
Google OAuth	Primary social login for web users
Email + Password	Traditional credentials with bcrypt hashing
WebAuthn / Passkeys	Hardware security keys and platform authenticators (FIDO2)
Diia (Дія)	Ukrainian government digital identity (Дія.Підпис)
OIDC / Authentik SSO	Enterprise single sign-on via Authentik identity provider
API Keys	Static bearer tokens for cross-service and MCP client communication

Dual-Auth Middleware

The backend uses a dual-auth strategy that accepts either a JWT (issued after any user login method) or a static API key (for automated/MCP clients). Each incoming request is validated and enriched with user context before reaching protected routes.

flowchart TD
    Req[Incoming Request] --> Auth{Authorization Header}
    Auth -- "Bearer JWT" --> JWT[Validate JWT]
    Auth -- "API Key" --> Key[Validate SECONDARY_LAYER_KEYS]
    JWT -- Valid --> Ctx[Set req.user context]
    Key -- Valid --> Ctx
    Ctx --> Route[Grant access to route/tool]
    JWT -- Invalid --> Err[401 Unauthorized]
    Key -- Invalid --> Err

Loading

On successful authentication, new users are automatically provisioned in Authentik (for SSO across connected services like Nextcloud) and receive a welcome bonus.

User Roles and Types

Platform Roles

Users have a platform-level role that determines their global capabilities:

Role	Description
user	Individual user (default)
company	Law firm / organization account
administrator	System administrator with full platform access

User Types

Within a role, the user_type field distinguishes:

• individual -- private person using the platform
• attorney -- legal professional with access to matter management
• company_admin -- administrator of an organization/firm

Access Gating

The platform uses a beta access model: full features (chat, document upload) are available to beta testers, administrators, and users who have topped up their balance via Monobank. Others see a restricted access modal.

Organizations and Team Management

Teams are structured around Organizations. A user can own one organization or be a member of another user's organization.

Organization Membership Roles

Role	Capabilities
owner	Full control; billing, member management, all matters
admin	Member management, access to all organization matters
user	Standard team member; access to assigned matters
observer	Read-only access to assigned matters

Team Operations

The team management system supports:

• Create organization -- with name, tax ID, description
• Invite members -- by email, with role assignment (pending until accepted)
• Update member roles -- promote/demote within the role hierarchy
• Remove members -- revoke access
• Resend invitations -- for pending members
• Team statistics -- total members, active users, aggregate usage

Organization Plans

Organizations have a plan tier (free, professional, business, enterprise) that determines the maximum number of members allowed.

Matters and Client Management

The Matter is the primary unit of collaborative legal work. Matters provide data isolation, team assignment, and audit trails for legal cases.

Client-Matter Hierarchy

erDiagram
    ORGANIZATION ||--o{ CLIENT : manages
    CLIENT ||--o{ MATTER : contains
    MATTER ||--o{ MATTER_TEAM : assigns
    MATTER_TEAM }o--|| USER : member
    MATTER ||--o{ LEGAL_HOLD : preserves
    MATTER ||--o{ DOCUMENT : tracks

Loading

Clients

Clients belong to an organization and represent the parties a firm serves. Each client has:

• A type classification (individual, business, government)
• Conflict-of-interest status tracking
• Contact and tax information

Matter Features

Each matter includes:

• Status lifecycle: open, active, closed, archived
• Team assignment: users are added with specific roles and access levels
• Document attachment: documents can be assigned/unassigned to matters
• Legal holds: preservation orders that prevent document deletion
• Conflict checks: AI-assisted detection of conflicts of interest across the organization
• Audit trail: tamper-evident log of all actions (hash-chained entries)

Matter Team Roles

Role	Access Level
lead_attorney	Full access
associate	Full access
paralegal	Full or read-only
assistant	Read-only or limited
observer	Read-only
consultant	Limited (scoped)

Matter Access Middleware

A dedicated middleware enforces matter-level data isolation. When a request includes a matter context, the middleware verifies the user is either on the matter's team or is an organization admin/owner before granting access.

Legal Holds

Legal holds are preservation orders placed on a matter that prevent associated documents from being deleted or modified. Each hold tracks:

• Hold type (litigation, investigation, regulatory, internal)
• Custodians (users responsible for preservation)
• Issuer and release information
• Status (active, released, expired)

Audit Trail

All matter operations are logged in an append-only, hash-chained audit table. Each entry records:

• Action performed
• Resource type and ID
• User, IP address, user agent
• Previous and current hash (tamper detection)

The audit log can be validated for integrity and filtered by user, action, resource, or date range.

GDPR Compliance

The platform provides GDPR (right to erasure / right to access) features:

• Data export -- users can request a full export of their data (gathered from all tables, stored temporarily in MinIO)
• Account deletion -- cascade-safe deletion with SET NULL on foreign keys (preserves system integrity while removing personal data)
• AUP consent tracking -- records each acceptance of the Acceptable Use Policy with version and timestamp
• Cookie consent -- granular category-based consent (essential, functional, analytics, marketing) persisted on the frontend

Frontend State Management

User and team state on the frontend is managed via Zustand stores (persisted with localStorage where appropriate) and TanStack React Query for server data:

Store	Purpose
accessGateStore	Tracks whether the user has paid access (beta tester, admin, or topped-up)
clientMatterStore	Navigation state for active client/matter and detail tabs
settingsStore	User preferences (thinking steps, citations, precedent count)
consentStore	GDPR cookie consent preferences
onboardingStore	Guided tour / onboarding completion state
uiStore	Layout preferences and UI state

Frontend API Layer

• authApi -- session management (get current user, logout, refresh, update profile)
• teamApi -- organization CRUD, member invite/update/remove, stats

Profile Management

Authenticated users can manage their profile:

• Update display name and avatar (with image compression via sharp)
• Auto-generated decorative banners
• View and manage WebAuthn credentials (passkeys)
• Upload avatar to MinIO object storage
• Accept attorney partnership offers (for professional accounts)

Summary

The User & Team Management module provides layered identity and access control:

1. Authentication -- six methods covering social, enterprise SSO, government ID, and passwordless
2. Platform roles -- user, company, administrator
3. Organizations -- team grouping with owner/admin/user/observer hierarchy
4. Matters -- data-isolated legal cases with fine-grained team roles and access levels
5. Compliance -- GDPR export/deletion, audit trails, legal holds, consent tracking