policy.proto

syntax = "proto2";

import "package.proto";

message Policy {
  // Name of repository
  required string repository = 1;

  // Policy name within the repository
  // (matches ^[a-z0-9][a-z0-9_\-\.]*[a-z0-9]$, length 3..64)
  required string name = 2;

  // Optional, free-form description.
  optional string description = 3;

  // Whether the policy is publicly readable or restricted to org members.
  // Read at the edge to decide whether to enforce auth on the fetch.
  // Consumers that use this field to authorize access MUST treat unknown
  // values as PRIVATE.
  required Visibility visibility = 4;

  // One entry per repository the policy constrains (in practice "hexpm" and
  // the org's own repository). A candidate release is matched to the entry
  // whose repository equals the release's repository; a release from a
  // repository with no matching entry is unconstrained by this policy.
  repeated RepositoryPolicy repositories = 5;
}

enum Visibility {
  // PRIVATE is the safe default; unknown enum values must be treated as PRIVATE.
  VISIBILITY_PRIVATE = 0;
  VISIBILITY_PUBLIC = 1;
}

message RepositoryPolicy {
  // Repository this entry applies to (e.g. "hexpm" or the org's repository).
  required string repository = 1;

  // Baseline limits applied to every release in this repository. Unset = no
  // restriction. Restrictions never apply to releases permitted by an ALLOW
  // override (those bypass all limits).
  optional Restriction restriction = 2;

  // Per-package overrides. ALLOW and DENY provide a final decision for the
  // matching release. ADVISORY, RETIREMENT, and COOLDOWN each bypass only the
  // selected restriction. Consumers MUST ignore invalid or unknown entries.
  repeated Override overrides = 3;
}

message Restriction {
  // Advisory limit. If set, deny any release whose maximum advisory severity
  // is at least this value. Unset = no advisory limit.
  optional AdvisorySeverity advisory_min_severity = 1;

  // Retirement limit. If non-empty, deny any release retired with a reason in
  // this set. Empty = no retirement limit.
  repeated RetirementReason retirement_reasons = 2 [packed=true];

  // Minimum release age ("7d", "2w", "1mo", "0"). Unset or "0" = no
  // minimum age.
  optional string cooldown = 3;
}

message PackageRef {
  // Package name.
  required string package = 1;

  // Optional version requirement (e.g. "~> 1.7"). Unset = the whole package.
  optional string requirement = 2;
}

message Override {
  // The effect of this override. The fields permitted for each action are
  // described below. Consumers MUST ignore unknown actions.
  required OverrideAction action = 1;

  // The package (and optional requirement) the override applies to.
  required PackageRef ref = 2;

  // ADVISORY requires advisory_id and forbids retirement_reason. Advisory
  // identifiers match primary advisory IDs and aliases without regard to
  // case. RETIREMENT requires retirement_reason and forbids advisory_id.
  // ALLOW, DENY, and COOLDOWN forbid both selector fields.
  optional string advisory_id = 3;
  optional RetirementReason retirement_reason = 4;

  // Optional UTF-8 explanation. At most 500 Unicode code points; control,
  // format, line separator, and paragraph separator characters are invalid.
  // This is public when the policy visibility is VISIBILITY_PUBLIC.
  optional string comment = 5;
}

enum OverrideAction {
  // Permit the release and bypass every policy restriction.
  OVERRIDE_ACTION_ALLOW = 0;
  // Block the release.
  OVERRIDE_ACTION_DENY = 1;
  // Accept only the advisory selected by advisory_id.
  OVERRIDE_ACTION_ADVISORY = 2;
  // Accept only a retirement with the selected retirement_reason.
  OVERRIDE_ACTION_RETIREMENT = 3;
  // Bypass only the policy cooldown.
  OVERRIDE_ACTION_COOLDOWN = 4;
}