> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mistrive.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Platform

> Identity management, multi-tenancy, and administrative services

Platform provides the management layer for Mistrive deployments. It handles user authentication, organization hierarchy, project isolation, and access control. All other services integrate with Platform for identity and authorization.

## System components

<CardGroup cols={2}>
  <Card title="Identity & Access Management" icon="shield-halved">
    User authentication, role-based access control, and authorization using a Zanzibar-style relationship model.
  </Card>

  <Card title="Organizations" icon="building">
    Top-level containers that group projects and define membership boundaries.
  </Card>

  <Card title="Projects" icon="folder">
    Resource containers within organizations. Each project isolates its own artifact repositories and service accounts.
  </Card>

  <Card title="Service accounts" icon="robot">
    Machine identities for automation and CI/CD pipelines. Scoped to projects with key-based authentication.
  </Card>
</CardGroup>

Platform exposes both gRPC and REST APIs. The management UI provides a web interface for common administrative tasks.

***

## Identity and access management

Platform implements a relationship-based access control system inspired by Google Zanzibar. Permissions are defined through relationships between subjects (users, service accounts) and objects (organizations, projects, repositories).

### Authentication

Platform supports password-based authentication with secure cookie sessions. Authentication state is managed through HTTP-only cookies with configurable domain and security settings.

| Method               | Description                                           |
| -------------------- | ----------------------------------------------------- |
| Password login       | Username/password authentication with session cookies |
| Service account keys | JWT-based authentication for machine identities       |

### Authorization model

Access control uses a hierarchical role system where higher roles inherit all permissions from lower roles:

```
owner → editor → viewer → member
```

The authorization engine evaluates permission checks by traversing relationship tuples stored in FoundationDB. This model supports:

* **Direct grants**: User explicitly assigned a role on a resource
* **Inherited grants**: Role inherited from a parent resource (organization → project)
* **Computed grants**: Role derived from another role (owner implies editor)

### Roles

| Role            | Scope                 | Permissions                              |
| --------------- | --------------------- | ---------------------------------------- |
| `member`        | Organization          | Basic membership without resource access |
| `viewer`        | Organization, Project | Read access to resources                 |
| `editor`        | Organization, Project | Read and write access to resources       |
| `owner`         | Organization, Project | Full access including IAM management     |
| `administrator` | Global                | System-wide administrative access        |

Organization-level roles propagate to all projects within that organization. A user with `editor` on an organization automatically has `editor` on all its projects.

### Service-specific roles

Artifact Store defines additional roles for fine-grained repository access:

| Role                    | Permissions                                   |
| ----------------------- | --------------------------------------------- |
| `artifact_store_viewer` | Pull images and list repositories             |
| `artifact_store_editor` | Push and pull images                          |
| `artifact_store_owner`  | Full repository management including deletion |

These roles also follow the inheritance hierarchy and can be granted at organization, project, or repository level.

***

## Organizations

Organizations are the top-level containers in the resource hierarchy. Every project belongs to exactly one organization.

### API operations

| Operation                  | Description                                    |
| -------------------------- | ---------------------------------------------- |
| `ListOrganizations`        | List all organizations (requires global admin) |
| `GetOrganization`          | Retrieve organization details                  |
| `CreateOrganization`       | Create a new organization                      |
| `UpdateOrganization`       | Modify organization properties                 |
| `DeleteOrganization`       | Soft-delete an organization                    |
| `RestoreOrganization`      | Restore a deleted organization                 |
| `AddOrganizationMember`    | Add a user with a specified role               |
| `RemoveOrganizationMember` | Remove a user from the organization            |

### Member roles

When adding members to an organization, specify one of the following roles:

| Role     | Effect                                                  |
| -------- | ------------------------------------------------------- |
| `MEMBER` | Organization membership with no implicit project access |
| `VIEWER` | Viewer access to all projects in the organization       |
| `EDITOR` | Editor access to all projects in the organization       |
| `OWNER`  | Owner access to all projects in the organization        |

***

## Projects

Projects provide resource isolation within organizations. Artifact repositories, service accounts, and IAM policies are scoped to individual projects.

### API operations

| Operation            | Description                                           |
| -------------------- | ----------------------------------------------------- |
| `ListProjects`       | List projects in an organization                      |
| `GetProject`         | Retrieve project details                              |
| `CreateProject`      | Create a new project (requires owner on organization) |
| `AddIamRelations`    | Grant roles to a principal on the project             |
| `RemoveIamRelations` | Revoke roles from a principal on the project          |

### Project roles

| Role                    | Description                                         |
| ----------------------- | --------------------------------------------------- |
| `VIEWER`                | Read access to project resources                    |
| `EDITOR`                | Read and write access to project resources          |
| `OWNER`                 | Full access including IAM and deletion              |
| `ARTIFACT_STORE_VIEWER` | Read access to artifact repositories only           |
| `ARTIFACT_STORE_EDITOR` | Read and write access to artifact repositories only |
| `ARTIFACT_STORE_OWNER`  | Full access to artifact repositories only           |

***

## Service accounts

Service accounts provide machine identities for automation workflows. Each service account belongs to a specific project and authenticates using cryptographic keys.

### API operations

| Operation                 | Description                        |
| ------------------------- | ---------------------------------- |
| `ListServiceAccounts`     | List service accounts in a project |
| `GetServiceAccount`       | Retrieve service account details   |
| `CreateServiceAccount`    | Create a new service account       |
| `DeleteServiceAccount`    | Delete a service account           |
| `CreateServiceAccountKey` | Generate a new authentication key  |
| `ListServiceAccountKeys`  | List keys for a service account    |
| `DeleteServiceAccountKey` | Revoke an authentication key       |

### Key management

Service account keys are JSON credentials containing:

* Service account identifier
* Private key for signing JWTs
* Token endpoint URI for credential exchange

Keys should be stored securely and rotated periodically. Deleting a key immediately revokes all sessions authenticated with that key.

### Authentication flow

1. Load the JSON key file
2. Sign a JWT assertion with the private key
3. Exchange the assertion for an access token at the token endpoint
4. Include the access token in API requests via the `Authorization` header

***

## User administration

Global administrators manage users through the User Admin Service.

### API operations

| Operation                     | Description                               |
| ----------------------------- | ----------------------------------------- |
| `ListUsers`                   | List all users in the system              |
| `GetUser`                     | Retrieve user details                     |
| `CreateUser`                  | Create a new user with email and password |
| `UpdateUser`                  | Modify user properties                    |
| `UpdateUserPassword`          | Reset a user's password                   |
| `DeleteUser`                  | Soft-delete a user                        |
| `RestoreUser`                 | Restore a deleted user                    |
| `UpdateIsGlobalAdministrator` | Grant or revoke global admin status       |

### User lifecycle

Users are soft-deleted rather than permanently removed. Deleted users:

* Cannot authenticate
* Retain their resource assignments (for audit purposes)
* Can be restored by a global administrator

***

## Management UI

Platform includes a web-based management console built with Next.js. The UI provides:

* User authentication (login, logout, password change)
* Organization management (create, list, member administration)
* Project management (create, list, IAM configuration)
* Artifact Store integration (repository browsing, image details)
* Global settings for administrators (user management, organization oversight)

The UI communicates with Platform APIs over REST, with authentication handled through secure cookies.

***

## Quotas

Platform tracks resource usage and enforces limits at organization and project levels.

### Quota dimensions

| Dimension                 | Scope        | Description                             |
| ------------------------- | ------------ | --------------------------------------- |
| `org_count`               | Global       | Total number of organizations           |
| `projects_per_org`        | Organization | Projects within an organization         |
| `repos_per_project`       | Project      | Artifact repositories within a project  |
| `artifact_bytes`          | Project      | Total storage consumed by artifacts     |
| `iam_members_per_project` | Project      | Users and service accounts in a project |

### Enforcement

Quota checks occur during resource creation. When a limit is reached, the operation fails with a clear error indicating the exceeded quota and current usage.

Administrators can view and adjust quotas through the API or management UI.

***

## Configuration

| Variable                    | Description                                              | Required                                        |
| --------------------------- | -------------------------------------------------------- | ----------------------------------------------- |
| `ADDRESS`                   | Bind address for the server                              | No (default: `0.0.0.0:12221`)                   |
| `FDB_DIRECTORY`             | FoundationDB directory path                              | No (default: `topaz`)                           |
| `ARTIFACT_STORE_DIRECTORY`  | FoundationDB directory for artifact metadata             | No (default: `registry`)                        |
| `UI_ADDRESS`                | Public URL of the Platform UI                            | Yes                                             |
| `PCLIENTS_ADDRESS`          | Address for OAuth client redirects                       | Yes                                             |
| `COOKIE_DOMAIN`             | Domain for authentication cookies (e.g., `.example.com`) | Yes                                             |
| `COOKIE_SECURE`             | Enable Secure flag on cookies                            | No (default: `true`)                            |
| `SERVICE_ACCOUNT_TOKEN_URI` | Token endpoint for service account authentication        | No (default: `http://localhost:12221/v1/token`) |
| `ARES_CLIENT_ADDRESS`       | Address of the DFS metadata service                      | No (default: `http://localhost:9182`)           |
| `DEBUG`                     | Enable debug logging                                     | No (default: `false`)                           |

***

## Deployment

### Requirements

Platform requires:

* Access to a FoundationDB cluster
* Network connectivity to DFS for artifact storage operations
* A configured domain for cookie-based authentication

### Initial setup

On first deployment, create an initial administrator:

1. Start Platform with the required configuration
2. Navigate to the setup page in the management UI
3. Create the first user account (automatically granted global administrator)

Subsequent users are created through the User Admin Service or management UI.

### High availability

Platform is stateless. Deploy multiple instances behind a load balancer for availability. All instances share the same FoundationDB cluster for consistent state.

Session cookies are validated against FoundationDB, so users can authenticate through any instance.