Operations Security - osama1998H/Moca GitHub Wiki

Security

Authentication methods, permission layers, and security architecture.

Security Layers

  1. Network: TLS termination at reverse proxy (Caddy/NGINX)
  2. Authentication: Session-based, JWT tokens, API keys
  3. Authorization: RBAC + FLS + RLS (see Permission Engine)
  4. Tenant Isolation: Schema-per-tenant with search_path enforcement
  5. Input Validation: MetaType-driven field validation, parameterized queries
  6. Rate Limiting: Redis-backed sliding window per endpoint
  7. Encryption at Rest: Optional field encryption for Password fields and encrypted backup artifacts
  8. Audit Trail: Request logging with user/site context

Authentication Methods

Method Use Case Status
Session (cookie) Browser-based Desk access Implemented
JWT Bearer token API access Implemented
API Key + Secret Server-to-server Planned (MS-18)
OAuth2 SSO Browser login against a generic OAuth2 identity provider Implemented
OIDC SSO Browser login with discovery and ID token verification Implemented
SAML 2.0 SSO Enterprise browser login via SP metadata + ACS Implemented

For browser-authenticated clients:

  • POST /api/v1/auth/login sets moca_sid and moca_rid as HttpOnly cookies
  • login and refresh responses return only access_token and expires_in; the refresh token stays in moca_rid
  • POST /api/v1/auth/refresh can read the refresh token from moca_rid when the request body omits refresh_token, and it rotates the cookie on success
  • POST /api/v1/auth/logout clears both cookies

Password Security

  • bcrypt hashing with configurable work factor
  • Password policy enforcement (min length, complexity)
  • user account passwords remain hashed
  • MetaType fields of type Password can additionally be encrypted at rest when MOCA_ENCRYPTION_KEY is configured for the server

Field Encryption

When MOCA_ENCRYPTION_KEY is present, Moca enables transparent encryption for MetaType fields whose field_type is Password:

  • values are encrypted before save using AES-256-GCM
  • encrypted values are stored with an enc:v1: prefix for versioning and idempotency
  • values are transparently decrypted when documents are loaded through the document manager

This protects application secrets stored in document data. It does not replace bcrypt hashing for login passwords, and it does not retroactively re-encrypt old rows unless they are saved again.

Single Sign-On

Enterprise SSO is configured per site with the builtin SSOProvider DocType. Supported provider_type values are OAuth2, OIDC, and SAML.

  • client_secret and sp_private_key are Password fields, so they are encrypted at rest when MOCA_ENCRYPTION_KEY is enabled
  • auto_create_user controls whether first-time SSO users are provisioned automatically
  • default_role is assigned during auto-provisioning when a new user is created
  • OAuth2 and OIDC flows start at GET /api/v1/auth/sso/authorize?provider={name}
  • SAML uses GET /api/v1/auth/saml/metadata?provider={name} for SP metadata and POST /api/v1/auth/saml/acs for assertion consumption
  • successful SSO login creates the moca_sid session cookie and redirects to /desk or the caller-provided relative redirect_to
  • state tokens are stored in Redis and expire after 10 minutes

See REST API Reference for the browser endpoints.

Backup Encryption

moca backup create --encrypt encrypts backup files before they are written to sites/{site}/backups/. Restore auto-detects .enc files and requires the same key material. See Backup & Restore for the CLI flow and key resolution order.

SQL Injection Prevention

  • All queries use parameterized statements via pgx
  • QueryBuilder generates parameterized SQL ($1, $2, ...)
  • No string interpolation in SQL

Related