model.fga

# Copyright 2026 Google LLC
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
#     http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.

model
  schema 1.1
# Naming Conventions:
# - Roles and graph edges are nouns (e.g. owner, editor, viewer, parent_global, host_node).
# - Permission checks evaluated at runtime must start with the 'can_' prefix
#   (e.g. can_get, can_create_access_policy, can_create_actor).

# Unified Principal Identity (human users, machine service accounts, SPIFFE workload identities)
type user

# Physical host node running atelet
type node

# Worker pod running ateworker (global-scoped)
type worker
  relations
    define parent_global: [global]
    define host_node: [node]

    define can_get: viewer from parent_global or controller from parent_global
    define can_list_actor_assignments: viewer from parent_global
    define can_update: owner from parent_global or controller from parent_global
    define can_delete: owner from parent_global or controller from parent_global
    define can_drain: owner from parent_global or controller from parent_global

# Global Scope (singleton: there will only ever be one instance, e.g. 'global:root')
type global
  relations
    define owner: [user]
    define viewer: [user] or owner

    # --- System Component Roles ---
    # Held only by Substrate's own components, through contextual tuples that
    # ateapi adds for their mTLS SPIFFE IDs. AccessPolicy cannot grant them.
    # Each grants only the permissions its component calls ateapi for.
    define controller: [user]
    define egress_gateway: [user]
    define ingress_router: [user]
    define atelet: [user]
    define api_server_sidecar: [user]

    define can_create_atespace: owner
    define can_list_atespaces: viewer
    define can_create_worker: owner or controller
    define can_list_workers: viewer or controller

    # Listing across all atespaces (List RPCs with an empty atespace).
    # atenet-router and atenet-egress, one binary, list actors as their ateapi
    # health check.
    define can_list_actors: viewer or ingress_router or egress_gateway
    define can_list_actor_templates: viewer
    define can_list_tags: viewer

    # --- Policy Governance ---
    define can_create_access_policy: owner
    define can_get_access_policy: viewer
    define can_update_access_policy: owner

type atespace
  relations
    define parent_global: [global]

    # --- 1. Aligned 3-Tier Roles ---
    # Global owner automatically inherits owner without explicit per-atespace tuples
    define owner: [user] or owner from parent_global
    define editor: [user] or owner
    define viewer: [user] or editor or viewer from parent_global

    # System component roles, inherited from global only.
    define egress_gateway: egress_gateway from parent_global
    define ingress_router: ingress_router from parent_global
    define atelet: atelet from parent_global
    define api_server_sidecar: api_server_sidecar from parent_global

    # --- 2. Policy Governance ---
    define can_create_access_policy: owner
    define can_get_access_policy: viewer
    define can_update_access_policy: owner
    define can_delete_access_policy: owner

    # --- 3. Atespace Lifecycle & Container Operations ---
    define can_create_actor: editor
    define can_create_actor_template: editor
    define can_list_actors: viewer
    define can_list_actor_templates: viewer
    define can_create_tag: editor
    define can_list_tags: viewer
    define can_get: viewer
    define can_delete: owner

type actor_template
  relations
    define parent_atespace: [atespace]

    # Policy stops at atespace: No direct per-user template bindings
    define can_get: viewer from parent_atespace
    # Run actors from this template (CreateActor, UpdateActor). Same grant as
    # can_get for now; a separate relation so running a template can later
    # require more than reading it.
    define can_use_template: viewer from parent_atespace
    define can_delete: editor from parent_atespace

# A named snapshot owned by an atespace. Its scope controls which atespaces
# CreateActor accepts it in, which the handler enforces; can_use_tag controls
# who may clone it. Managing the tag stays with its owning atespace.
#
# TODO: A tag is a durable copy of an actor's memory and disk, including any
# secrets it held, and it outlives the actor. Any atespace editor can tag any
# actor in the atespace, publish it, and clone it. Restrict who can create,
# publish, and clone tags once the tag scoping design is settled.
type tag
  relations
    define parent_atespace: [atespace]

    define can_get: viewer from parent_atespace
    define can_update: editor from parent_atespace
    define can_delete: editor from parent_atespace
    # Create actors from this tag (CreateActor source_tag).
    define can_use_tag: editor from parent_atespace

type actor
  relations
    define parent_atespace: [atespace]

    # --- Dynamic Infrastructure Scheduling Graph ---
    define scheduled_worker: [worker]
    define host_node: host_node from scheduled_worker

    # --- User-Facing Operations (Inherited from Atespace) ---
    # atenet-egress reads the actor to resolve its egress policy. The
    # ate-api-server pod's sidecars, today the objectstore control plugin,
    # read it to derive the snapshot prefixes a per-actor storage credential
    # may cover, and nothing else.
    define can_get: viewer from parent_atespace or egress_gateway from parent_atespace or api_server_sidecar from parent_atespace
    define can_update: editor from parent_atespace
    define can_delete: editor from parent_atespace

    # Egress policy: one per actor, so its permissions live on the actor.
    # atelet reads it on behalf of the worker hosting the actor, which
    # enforces it.
    #
    # TODO(#1564): Every node's atelet shares one SPIFFE ID, so any atelet can read
    # any actor's egress policy, and atelet does not check that the worker
    # asking hosts the actor. Serve the read from WorkerService instead,
    # authorizing atelet on the node hosting the actor as MintWorkerActorJwt
    # does, have atelet check the requesting worker, and drop atelet here.
    define can_get_egress_policy: viewer from parent_atespace or egress_gateway from parent_atespace or atelet from parent_atespace
    define can_create_egress_policy: editor from parent_atespace
    define can_update_egress_policy: editor from parent_atespace
    define can_delete_egress_policy: editor from parent_atespace

    # Node Restriction: Only the node hosting the scheduled worker can mint ateworker actor credentials
    define can_mint_worker_actor_credential: host_node

    # Credentials asserting the actor's own identity. Only the egress gateway
    # mints them; an editor holding one could impersonate the actor.
    define can_mint_actor_jwt: egress_gateway from parent_atespace
    define can_mint_actor_certificate: egress_gateway from parent_atespace

    # Data Plane Ingress: Routers (or editors) can resume
    define can_resume: [user] or editor from parent_atespace or ingress_router from parent_atespace

    # Lifecycle Operations
    define can_suspend: [user] or editor from parent_atespace
    define can_revert: [user] or editor from parent_atespace