# Access Control Policy

**Document Version**: 1.0  
**Last Updated**: 2025-10-03  
**Owners**: Platform Security Guild & Identity Engineering

The Lilith platform enforces a unified access-control strategy that combines
role-based access control (RBAC) with attribute-based access control (ABAC).
This document defines the canonical roles, attribute constraints,
service-account lifecycle policies, and least-privilege guardrails that every
service must honour.

## RBAC Model

The RBAC model enumerates platform roles and their baseline permissions. Roles
map to personas (human users) or workloads (service accounts) and are always
additive—no implicit wildcards are granted.

| Role                    | Permissions                                                                                                                             | Scope                                   | Service Accounts  |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------- | ----------------- |
| `user`                  | `profile:read`, `profile:update:self`, `content:view:published`, `comments:create:self`, `comments:update:self`, `comments:delete:self` | Tenant-scoped                           | N/A               |
| `support`               | `user:roles:view`, `user:status:update`, `content:view:drafts`                                                                          | Restricted to customer-tenants assigned | N/A               |
| `auditor`               | `audit-log:read:any`, `compliance:report:download`                                                                                      | Read-only, redacted PII                 | N/A               |
| `admin`                 | `user:roles:update`, `audit-log:read:any`, `policy:update`, `service-account:manage`                                                    | Production only, trusted network        | N/A               |
| `service_bff`           | `auth.tokens.issue`, `session:validate`                                                                                                 | Production, BFF to Auth bridge          | `svc-bff-gateway` |
| `service_observability` | `telemetry:ingest`, `telemetry:read:aggregated`                                                                                         | Observability plane                     | `svc-observe`     |

Roles are provisioned through the Auth service with explicit audit logging. All
privileged roles (`support`, `auditor`, `admin`) require break-glass approval
and hardened network paths.

## ABAC Conditions

ABAC rules overlay RBAC permissions to ensure contextual checks (ownership,
network, geography) are enforced consistently.

- **Self-access guardrail**: Standard users (`user`) may only read or mutate
  resources where `resource.ownerId === principal.id`. The engine enforces this
  via the `SELF_ACCESS_REQUIRED` denial reason when violated.
- **Admin network policy**: Administrative actions must originate from approved
  IP ranges supplied via `AUTH_ADMIN_ALLOWED_IPS`. Requests outside the allow
  list are denied with `ADMIN_NETWORK_RESTRICTED`.
- **Geo sensitivity**: Moderator and auditor actions evaluate the
  `context.location.country` attribute; high-risk locales require MFA elevation
  (enforced upstream).
- **Temporal controls**: Break-glass administrator sessions expire after 60
  minutes and are invalid for batch automation workloads.

## Service Accounts

Service accounts power service-to-service flows and are isolated from human
credentials. Each service account is defined by:

- Deterministic identifier (`sa_<slug>`), owner, and business justification.
- Scoped roles that map to workload personas (`service_bff`,
  `service_observability`, etc.).
- Explicit scopes/permissions (e.g., `auth.tokens.issue`).
- IP allow lists and environment bindings.
- Rotation policy (default 30 days) with automation tracked in Vault.

Provisioning and rotation are orchestrated through the Auth service
`service-account:manage` endpoints. Secrets are stored in the secrets manager;
only hashed fingerprints are persisted in app stores.

## Least Privilege Matrix

The following table captures the least-privilege expectations that are verified
continuously via automated tests.

| Principal                           | Allowed Actions                           | Attributes Required                                         | Denial Reason on Violation                                 |
| ----------------------------------- | ----------------------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------- |
| End user (`user`)                   | `profile:read`, `profile:update:self`     | `context.attributes.isOwner === true`                       | `SELF_ACCESS_REQUIRED`                                     |
| Service account (`svc-bff-gateway`) | `auth.tokens.issue`                       | `context.ip` in allow list & `environment === 'production'` | `INSUFFICIENT_SCOPE`, `SERVICE_ACCOUNT_NETWORK_RESTRICTED` |
| Administrator (`admin`)             | `user:roles:update`, `audit-log:read:any` | `context.ip` in trusted range & short-lived session         | `ADMIN_NETWORK_RESTRICTED`                                 |

## Policy Artefacts

The canonical machine-readable policy is stored at
[`docs/schemas/access-policy.schema.json`](../schemas/access-policy.schema.json)
and is validated in CI through `tests/security.rbac-abac.spec.ts`. All services
must align their enforcement logic with this schema; deviations require a
security review and updated regression coverage.
