// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
@available(added=HEAD)
library fuchsia.component.internal;

using fuchsia.component;
using fuchsia.component.decl;

/// The maximum size of the JobPolicyAllowlists entries.
/// This value is currently set arbitrarily.
const MAX_ALLOWLIST_SIZE uint64 = 128;

type Config = table {
    /// If true, component manager will be in debug mode. In this mode, component manager
    /// provides the `EventSource` protocol and exposes this protocol. Component
    /// manager will not start until it is resumed by a call to
    /// `EventSource.StartComponentTree`.
    ///
    /// This is done so that an external component (say an integration test) can subscribe
    /// to events before the root component has started.
    1: debug bool;

    /// How many children, maximum, are returned by a call to `Realm.ChildIterator.next()`.
    2: list_children_batch_size uint32;

    /// Security policy configuration.
    3: security_policy SecurityPolicy;

    /// Capabilities offered from component manager's namespace.
    4: namespace_capabilities vector<fuchsia.component.decl.Capability>:MAX;

    /// Capabilities offered from component manager as built-in capabilities.
    17: builtin_capabilities vector<fuchsia.component.decl.Capability>:MAX;

    /// If true, component_manager will serve an instance of fuchsia.process.Launcher and use this
    /// launcher for the built-in ELF component runner. The root component can additionally
    /// use and/or offer this service using `/builtin/fuchsia.process.Launcher` from realm.
    /// This flag exists because the built-in process launcher *only* works when
    /// component_manager runs under a job that has ZX_POL_NEW_PROCESS set to allow, like the root
    /// job. Otherwise, the component_manager process cannot directly create process through
    /// zx_process_create. When we run component_manager elsewhere, like in test environments, it
    /// has to use the fuchsia.process.Launcher service provided through its namespace instead.
    5: use_builtin_process_launcher bool;

    /// If true, component_manager will maintain a UTC kernel clock and vend write handles through
    /// an instance of `fuchsia.time.Maintenance`. This flag should only be used with the top-level
    /// component_manager.
    6: maintain_utc_clock bool;

    /// The number of threads to use for running component_manager's executor.
    /// If not present, interpreted as 1.
    7: num_threads uint32;

    /// URL of the root component to launch. This field is used if the no URL
    /// is passed to component manager. If value is passed in both places, then
    /// an error is raised.
    10: root_component_url string:fuchsia.component.MAX_URL_SCHEME_LENGTH;

    /// Path to the component ID index. An empty value defaults to an empty index.
    /// An invalid index causes component_manager to abort.
    11: component_id_index_path string:fuchsia.component.MAX_PATH_LENGTH;

    /// Where to log to.
    12: log_destination LogDestination;

    /// If true, component manager will log all events dispatched in the topology.
    13: log_all_events bool;

    /// Which builtin resolver to use for the fuchsia-boot scheme.
    /// If not present, interpreted as BuiltinBootResolver.NONE.
    14: builtin_boot_resolver BuiltinBootResolver;

    /// If and how the realm builder resolver and runner will be used. Typically
    /// these capabilities from realm builder are available to a nested
    /// component manager that is undergoing an integration test.
    16: realm_builder_resolver_and_runner RealmBuilderResolverAndRunner;

    /// Enables Component Manager's introspection APIs (RealmQuery, RealmExplorer,
    /// RouteValidator, LifecycleController, etc.) for use by components.
    18: enable_introspection bool;

    /// The enforcement and validation policy to apply to component target ABI
    /// revisions.
    19: abi_revision_policy AbiRevisionPolicy;

    /// Where to obtain the vmex resource from, if this component_manager is hosting bootfs.
    /// If not present, defaults to `VmexSource::SYSTEM_RESOURCE`.
    20: vmex_source VmexSource;
};

/// The enforcement and validation policy to apply to component target ABI revisions.
type AbiRevisionPolicy = table {
    /// Allowlist entry monikers for components that will be permitted to run
    /// even if they fail ABI revision checks. This should _never_ be used. Any
    /// component that bypasses these checks is unsupported by the platform and
    /// may behave in unexpected ways!
    1: allowlist vector<AllowlistEntryMoniker>:MAX_ALLOWLIST_SIZE;
};

/// Where to obtain the vmex resource from, if this component_manager is hosting bootfs.
type VmexSource = strict enum : uint8 {
    /// Get it from the PA_SYSTEM_RESOURCE handle passed to component_manager
    SYSTEM_RESOURCE = 1;

    /// Get it from the /svc/fuchsia.kernel.VmexResource protocol in
    /// component_manager's namespace.
    NAMESPACE = 2;
};

/// The builtin resolver to use for the fuchsia-boot scheme, if any.
type BuiltinBootResolver = strict enum : uint8 {
    /// No builtin boot resolver is used.
    NONE = 1;

    /// Try to use the /boot directory from the namespace. Typically this is provided
    /// to component manager during initialization of the system.
    BOOT = 2;
};

/// Where to log to.
type LogDestination = strict enum : uint8 {
    /// Log to syslog.
    SYSLOG = 1;

    /// Log to klog.
    KLOG = 2;
};

/// If and how the realm builder resolver and runner will be used.
type RealmBuilderResolverAndRunner = strict enum : uint8 {
    /// The realm builder resolver and runner are not used.
    NONE = 1;

    /// The realm builder resolver and runner will be accessed through component
    /// manager's namespace, and made available to the root realm.
    NAMESPACE = 2;
};

/// Runtime security policy.
type SecurityPolicy = table {
    /// Allowlists for Zircon job policy.
    1: job_policy JobPolicyAllowlists;
    /// Capability access policy.
    2: capability_policy CapabilityPolicyAllowlists;
    /// Debug capability registration policy.
    3: debug_registration_policy DebugRegistrationPolicyAllowlists;
    /// Component child options policy.
    4: child_policy ChildPolicyAllowlists;
};

/// A single entry in an allowlist, expressed in one of three forms:
///
///   1. Exact moniker - Most entries should fall under this case,
///      where the exact monikers of allowed components are listed.
///      For example, "/foo/bar".
///   2. Realm - Realms can be allowlisted such that any descendant will be
///      allowed without being listed explicitly. For example, "/foo/**"
///      allows any descendant of "/foo" (but not foo itself).
///   3. Collection - Individual collections can also be allowlisted. For
///      example, "/foo/bar:**" will allow any child in foo's "bar"
///      collection and any descendant thereof, but not foo or other
///      children of foo.
alias AllowlistEntryMoniker = string:fuchsia.component.MAX_MONIKER_LENGTH;

/// Allowlists for Zircon job policy.
type JobPolicyAllowlists = table {
    /// Allowlist entry monikers for components allowed to be given the
    /// ZX_POL_AMBIENT_MARK_VMO_EXEC job policy.
    ///
    /// Components must request this policy by including "job_policy_ambient_mark_vmo_exec: true" in
    /// their CML's `program` section and must be using the ELF runner.
    /// This is equivalent to the v1 'deprecated-ambient-replace-as-executable' feature.
    1: ambient_mark_vmo_exec vector<AllowlistEntryMoniker>:MAX_ALLOWLIST_SIZE;

    /// Allowlist entry monikers for components allowed to have their original process
    /// marked as critical to component_manager's job.
    ///
    /// Components must request this critical marking by including "main_process_critical: true" in
    /// their CML's `program` section and must be using the ELF runner.
    2: main_process_critical vector<AllowlistEntryMoniker>:MAX_ALLOWLIST_SIZE;

    /// Allowlist entry monikers for components allowed to call zx_process_create directly
    /// (e.g., do not have ZX_POL_NEW_PROCESS set to ZX_POL_ACTION_DENY).
    ///
    /// Components must request this policy by including "job_policy_create_raw_processes: true" in
    /// their manifest's program object and must be using the ELF runner.
    3: create_raw_processes vector<AllowlistEntryMoniker>:MAX_ALLOWLIST_SIZE;
};

/// Represents the class of capabilities supported to be allowlisted.
type AllowlistedCapability = flexible union {
    1: directory AllowlistedDirectory;
    3: protocol AllowlistedProtocol;
    4: service AllowlistedService;
    5: storage AllowlistedStorage;
    6: runner AllowlistedRunner;
    7: resolver AllowlistedResolver;
};

type AllowlistedDirectory = table {};

type AllowlistedProtocol = table {};

type AllowlistedService = table {};

type AllowlistedStorage = table {};

type AllowlistedRunner = table {};

type AllowlistedResolver = table {};

/// Defines a single capability policy entry in the set of capability policy
/// allowlists.
type CapabilityAllowlistEntry = table {
    /// The `source_moniker` represents the origin of a capability. The
    /// `source_moniker` is either a moniker or '<component_manager>'.
    1: source_moniker string:fuchsia.component.MAX_MONIKER_LENGTH;

    /// The source name of this particular capability.
    2: source_name string:fuchsia.component.MAX_NAME_LENGTH;

    /// Represents the type of capability that is being restricted along
    /// with any other properties required by a particular capability type.
    3: capability AllowlistedCapability;

    /// The set of components, described by either exact monikers, realm, or collection,
    /// that are allowed to use this specific capability.
    4: target_monikers vector<AllowlistEntryMoniker>:MAX_ALLOWLIST_SIZE;

    /// The original source type of this capability, self or framework.
    5: source fuchsia.component.decl.Ref;
};

/// Defines the total set of capability allowlists. Each
/// `source_moniker` + `capability` pair must be unique in the vector.
type CapabilityPolicyAllowlists = table {
    1: allowlist vector<CapabilityAllowlistEntry>:MAX_ALLOWLIST_SIZE;
};

/// Represents the class of capabilities supported to be allowlisted.
type AllowlistedDebugRegistration = flexible union {
    1: protocol AllowlistedProtocol;
};

/// Defines a capability policy entry in the set of debug capability policy
/// allowlists.
type DebugRegistrationAllowlistEntry = table {
    /// The name of the capability as it's registered in the environment.
    1: name string:fuchsia.component.MAX_NAME_LENGTH;

    /// Represents the type of capability that is being restricted along
    /// with any other properties required by a particular capability type.
    2: debug AllowlistedDebugRegistration;

    /// The moniker of the component which is allowed to register
    /// this capability in its environment's debug sction.
    3: moniker AllowlistEntryMoniker;

    /// Name of the environment where this capability can be registered.
    4: environment_name fuchsia.component.name;
};

/// Defines the total set of debug capability allowlists.
type DebugRegistrationPolicyAllowlists = table {
    1: allowlist vector<DebugRegistrationAllowlistEntry>:MAX_ALLOWLIST_SIZE;
};

/// Allowlists for privileged child options.
type ChildPolicyAllowlists = table {
    /// Allowlist entry monikers of component instances allowed to have the
    /// `on_terminate=REBOOT` in their `children` declaration.
    1: reboot_on_terminate vector<AllowlistEntryMoniker>:MAX_ALLOWLIST_SIZE;
};