policy

type Document struct {
	// SourceAllowlist restricts where apps may be created from (R-092). Empty
	// means no restriction — Pando ships permissive defaults (R-270).
	SourceAllowlist []string `json:"source_allowlist,omitempty"`

	// DisabledVerbs are denied install-wide, to everyone, including an app's
	// owner. R-085's "host policy may disable exec install-wide" is this list
	// containing app.exec.
	DisabledVerbs []string `json:"disabled_verbs,omitempty"`

	// AgentDisabledVerbs are denied to token principals only — the CLI token an
	// agent holds, and the MCP server acting through one (R-262).
	//
	// This is O-12's resolution. The tempting alternative is a list of tools
	// the MCP server refuses to expose, and it does not work: an agent holding
	// a token can call the REST API directly, so an MCP-layer exclusion is a
	// speed bump rather than a boundary. Expressed here, it is evaluated before
	// grants for every surface, which is the only place it means anything.
	//
	// Default-closed: Default() ships the exclusions design 04 §3 lists, and an
	// install can lift them by editing policy like any other rule.
	AgentDisabledVerbs []string `json:"agent_disabled_verbs,omitempty"`

	// AllowAnonymousGrants controls whether an app may be shared with everyone
	// (R-076). Pointer so that "unset" is distinguishable from "explicitly
	// false", which matters when a policy document is partially written.
	//
	// Superseded by PublicSharing, which says more; still read, so a policy
	// file or environment that sets it keeps meaning what it meant — false is
	// PublicSharingNone. PublicSharing wins when both are set.
	AllowAnonymousGrants *bool `json:"allow_anonymous_grants,omitempty"`

	// PublicSharing is how an app may be shared with everyone (R-076, R-075a):
	// at all, only behind a passcode, or not at all.
	PublicSharing PublicSharing `json:"public_sharing,omitempty"`

	// MinBuildIsolation and MinRuntimeIsolation are floors (R-024, R-114).
	// Separate because how isolated a build must be is a different question
	// from how isolated the running app must be.
	MinBuildIsolation   spec.IsolationClass `json:"min_build_isolation,omitempty"`
	MinRuntimeIsolation spec.IsolationClass `json:"min_runtime_isolation,omitempty"`

	// Egress (R-181 – R-185). The install's rules are a floor (R-183): an
	// app's own list narrows them, and only the loosening moves EgressFor
	// names — adding to an allowlist, removing from a denylist, turning
	// private-range blocking off — are subject to EgressLoosening.
	//
	// EgressMode is allow_all (empty), denylist or allowlist, and EgressList
	// is the list it reads. EgressBlockPrivate works with any mode.
	EgressMode         spec.EgressMode `json:"egress_mode,omitempty"`
	EgressList         []string        `json:"egress_list,omitempty"`
	EgressBlockPrivate bool            `json:"egress_block_private,omitempty"`

	// EgressLoosening is whether an app may loosen the rules above: by
	// somebody holding app.egress.loosen (empty, the default, R-270), only
	// after a deploy approval (R-154), or never.
	EgressLoosening EgressLoosening `json:"egress_loosening,omitempty"`

	// EgressAllowlist is the field before issue #79, when there was no mode
	// and an app's list replaced this one. Still read — a non-empty one with
	// no EgressMode is an allowlist — so a policy file that sets it keeps
	// meaning what its author wrote. Never enforced before, so an install that
	// set it starts being held to it; that is what the setting said.
	EgressAllowlist []string `json:"egress_allowlist,omitempty"`

	// Deploy approval (R-154 – R-159). Off unless something here, or the app's
	// own spec, turns it on.
	//
	// DeployApprovalRequired: every app's deploys need approval.
	// DeployApprovalApps: these apps' deploys do, whatever their owners say.
	// DeployApprovalCount: how many approvals a deploy needs; zero is one.
	// DeployApprovalExpiryHours: how long a request waits; zero is forever.
	// Default() ships seven days.
	DeployApprovalRequired    bool     `json:"deploy_approval_required,omitempty"`
	DeployApprovalApps        []string `json:"deploy_approval_apps,omitempty"`
	DeployApprovalCount       int      `json:"deploy_approval_count,omitempty"`
	DeployApprovalExpiryHours int      `json:"deploy_approval_expiry_hours,omitempty"`

	// RequireBackupBeforeDestroy: an admin sets "never destroy without backup"
	// once, and app owners cannot override downward (R-284).
	RequireBackupBeforeDestroy bool `json:"require_backup_before_destroy,omitempty"`

	// MaxTokenLifetimeDays caps how long a token may live; 0 means no cap.
	// R-061 allows policy to forbid non-expiring tokens.
	MaxTokenLifetimeDays int `json:"max_token_lifetime_days,omitempty"`

	// MaxLogDiskBytes is R-224: the total this install will commit to app logs
	// across every app. Zero means no aggregate limit.
	//
	// Enforced at plan time against the **sum of every app's cap**, not against
	// measured usage — which is O-16's resolution. Bounding what is committed
	// is the stronger guarantee: if every app's logs are capped and the caps
	// sum under the budget, the total cannot exceed it. Measuring usage would
	// mean acting after the disk was already filling, and the only remedy then
	// is recreating containers, which the reconciler may not do on a schedule
	// because an unrelated app turned chatty.
	MaxLogDiskBytes int64 `json:"max_log_disk_bytes,omitempty"`

	// MaxConcurrentDeploys is how many deploys each replica runs at once from
	// the deploy queue (issue #93). Zero means one per CPU, and at least two
	// (deploy.DefaultConcurrency). Per replica, because a build's cost lands
	// on the machine that runs it. Read every time the queue looks for work,
	// so a change applies without a restart; a deploy past the limit waits,
	// and says how many are ahead of it.
	MaxConcurrentDeploys int `json:"max_concurrent_deploys,omitempty"`

	// IdleStopDays and IdleDeleteDays stop, and later delete, an app nobody
	// has used for that many days, both counted from its last activity
	// (R-393 – R-398, issue #131). Zero is off, the default. An app may set
	// its own or turn either off (R-397), so these are defaults, not floors.
	IdleStopDays   int `json:"idle_stop_days,omitempty"`
	IdleDeleteDays int `json:"idle_delete_days,omitempty"`

	// StopOrphanedApps stops an app the moment none of its owners is active
	// (R-408). On unless set false: nil is on, so an install whose stored
	// policy predates the setting has it. Administrators are told either way
	// (R-409).
	StopOrphanedApps *bool `json:"stop_orphaned_apps,omitempty"`

	// Standby keeps a stopped copy of each app on another host, started when
	// its host is lost (R-419). On unless set false: nil is on [P]. An app's
	// spec may turn it on or off for itself (availability.standby). Only a
	// runtime with somewhere else to keep one has any (SupportsStandby).
	Standby *bool `json:"standby,omitempty"`

	// MaxAppsPerUser is how many apps a person may own unless their account or
	// a group of theirs says otherwise (R-244). Zero is unlimited.
	MaxAppsPerUser int `json:"max_apps_per_user,omitempty"`

	// AllowCPUOversubscription and AllowMemoryOversubscription let the apps
	// on a runtime together ask for more CPU, or more memory, than the runtime
	// reports having (R-242 as amended for issue #72). Both off by default: a
	// deploy that would oversubscribe is refused at plan time.
	//
	// Separate, because they fail differently. Too little CPU makes every app
	// slower; too little memory makes the kernel kill one. An install packing
	// many mostly-idle apps onto one host usually wants the first and not the
	// second.
	//
	// There is no disk counterpart and there will not be one: disk is not a
	// reservation the kernel shares out, and a full disk stops every app and
	// Pando with them.
	AllowCPUOversubscription    bool `json:"allow_cpu_oversubscription,omitempty"`
	AllowMemoryOversubscription bool `json:"allow_memory_oversubscription,omitempty"`

	// AllowFailoverOversubscription lets an app's standby be placed past the
	// CPU and memory the other hosts keep free for its host's loss (R-422).
	// Off by default: a standby goes only where, if its app's host were lost,
	// it would start, and an app with nowhere like that runs without one.
	// On, a host that takes over starts what fits, by each app's
	// availability.priority. Disk is still never oversubscribed (R-242): a
	// standby's copies are on its host's disk all the time.
	AllowFailoverOversubscription bool `json:"allow_failover_oversubscription,omitempty"`

	// Audit retention (R-347, R-348). The live audit log keeps
	// AuditRetentionMonths whole months; an older month is archived, the
	// archive read back and checked, and only then is the month removed.
	//
	// Zero is three months. Fewer than three is refused here, and the
	// database refuses it again: the floor is held by the function that
	// removes a month, so nothing the running server can write lowers it.
	// More is anyone's choice.
	//
	// AuditArchive is where an archive goes: keep (empty, the default) under
	// Pando's own directory, export to a backup destination — the default
	// one, or AuditArchiveDestination — or off, which archives nothing and so
	// removes nothing, the log growing as it did before retention existed.
	AuditRetentionMonths    int               `json:"audit_retention_months,omitempty"`
	AuditArchive            audit.ArchiveMode `json:"audit_archive,omitempty"`
	AuditArchiveDestination string            `json:"audit_archive_destination,omitempty"`

	// DisableAIScreening forbids AI screening of deployment plans install-wide
	// (R-336). Default false, like everything else here: Pando ships permissive
	// and configuration narrows (R-270).
	//
	// Worth an explicit setting rather than leaving it to whether an adapter is
	// configured, because the two are different decisions made by different
	// people. Screening sends repository contents to a provider (R-337), and an
	// administrator who has to say no to that should not have to do it by
	// deleting somebody else's adapter.
	DisableAIScreening bool `json:"disable_ai_screening,omitempty"`

	// DisableAnonymousUseAudit stops recording app.use for visitors who are
	// not signed in (R-227). Default false: anonymous use of a public app is
	// recorded like anyone's, once per browser session, because "who used this
	// app" after a leak includes the people nobody knew by name. An install
	// with a busy public site that does not want those rows turns it off.
	DisableAnonymousUseAudit bool `json:"disable_anonymous_use_audit,omitempty"`

	// DisableAnonymousDenialAudit stops recording authz.denied when somebody
	// not signed in reaches an app that is not shared with them (design 06
	// §6). Default false: every denial is audited, these included. Anyone can
	// cause one write per request without an account — a crawler walking a
	// private app's links does — so an install that does not want those rows
	// turns it off. A signed-in person or a token refused is always recorded.
	DisableAnonymousDenialAudit bool `json:"disable_anonymous_denial_audit,omitempty"`

	// The security score (R-314 – R-316, design 09 §5).
	//
	// MinSecurityScore is the floor a deploy has to clear, 0 to 100. Zero is
	// off, which is the shipped posture (R-270) — and so is an installation
	// with no scanner configured, where this is inert and the console says so
	// rather than silently blocking every deploy (R-317).
	MinSecurityScore int `json:"min_security_score,omitempty"`

	// InsecureAction is what happens to an app that is *already running* when
	// it falls below the floor: "warn" or "stop". Empty means warn.
	//
	// A policy change or a newly published CVE is not a reason to take
	// somebody's working service away without notice, so stopping is opt-in
	// and grace comes with it (R-315).
	InsecureAction string `json:"insecure_action,omitempty"`

	// InsecureGraceHours is how long an app has after it is first found below
	// the floor, before "stop" applies. Zero with InsecureAction "stop" means
	// the default below, not "immediately" — an accidental zero must not empty
	// a host.
	InsecureGraceHours int `json:"insecure_grace_hours,omitempty"`

	// IgnoreUnfixableFindings drops findings with no fix available from both
	// the score and the list.
	//
	// Off by default, so the number means "what is wrong with this app" rather
	// than "what could this app's owner do about it today" — and an upgrade
	// does not silently move every score. An installation that has decided it
	// only acts on what it can fix turns it on, and the two agree again: what
	// is counted is what is shown.
	IgnoreUnfixableFindings bool `json:"ignore_unfixable_findings,omitempty"`

	// DisablePasswordSignIn refuses sign-in with a local username and
	// password (issue #51), once people sign in through an external identity
	// provider. Refused while no external provider is on, so it cannot empty
	// the sign-in page. `pando admin enable-password-sign-in` is the way back
	// when every provider is unreachable, and needs shell access on the host.
	DisablePasswordSignIn bool `json:"disable_password_sign_in,omitempty"`

	// DisableJITProvisioning refuses making an account at a first external
	// sign-in, whatever each provider is set to. People then need an account
	// first — pushed by SCIM, or linked by an administrator.
	DisableJITProvisioning bool `json:"disable_jit_provisioning,omitempty"`

	// RequireLocalTwoFactor requires two-factor authentication on every local
	// account (R-405). An account without it can sign in with its password
	// and do nothing but set it up; one with it cannot turn it off. Accounts
	// from an identity provider are not affected: their provider decides.
	// `pando admin reset-two-factor` is the way back for someone who has lost
	// their authenticator and their recovery codes.
	RequireLocalTwoFactor bool `json:"require_local_two_factor,omitempty"`

	// DisableUpdateCheck stops Pando asking GitHub whether a newer release
	// exists (R-349). Default false — on — so an install learns about a
	// security release without anyone remembering to look; off sends no
	// request at all, for an air-gapped install or one that may not call out.
	DisableUpdateCheck bool `json:"disable_update_check,omitempty"`

	// AllowPrivateWebhooks lets an event subscription's webhook reach a
	// private, loopback or link-local address (R-372). Default false: anybody
	// who can see an app can subscribe to it, and a webhook that may point
	// anywhere is a way to make Pando send requests into its own network — to
	// a cloud metadata address, or to the database it runs on.
	AllowPrivateWebhooks bool `json:"allow_private_webhooks,omitempty"`

	// UpdateChannel is which releases the check offers (R-350): stable, the
	// default, or prerelease, which also offers release candidates.
	UpdateChannel UpdateChannel `json:"update_channel,omitempty"`

	// UpgradeInPlace lets Pando replace its own container with a newer
	// release (R-355). Off by default, against R-270 on purpose: a version
	// named in a Compose file or infrastructure-as-code is put back by its
	// next apply, so whoever owns that configuration turns this on — usually
	// there, as PANDO_POLICY_UPGRADE_IN_PLACE, which also locks it here.
	UpgradeInPlace bool `json:"upgrade_in_place,omitempty"`

	// AutoUpgradePatches upgrades to a new patch release of the running minor
	// line inside MaintenanceWindow, with nobody present (R-361). Needs
	// UpgradeInPlace and a window.
	AutoUpgradePatches bool `json:"auto_upgrade_patches,omitempty"`

	// MaintenanceWindow is when an automatic upgrade may start, in UTC:
	// weekdays, a start time and a length, as "sun,wed 02:00 2h" (R-361).
	// One string so that it reads the same in the config file, an
	// environment variable and the API.
	MaintenanceWindow string `json:"maintenance_window,omitempty"`
}

type EffectiveEgress struct {
	// Mode and List are the install's rules with the app's additions and
	// removals applied.
	Mode spec.EgressMode `json:"mode"`
	List []EgressEntry   `json:"list"`

	// AppMode and AppList are the app's own list, applied on top. Empty when
	// the app has none.
	AppMode spec.EgressMode `json:"app_mode,omitempty"`
	AppList []string        `json:"app_list,omitempty"`

	BlockPrivate     bool   `json:"block_private"`
	BlockPrivateFrom string `json:"block_private_from,omitempty"` // install | app

	// Loosenings is every way this app is looser than the install, and Gate
	// is what policy says they need. Gate is empty when there are none.
	Loosenings []Loosening     `json:"loosenings,omitempty"`
	Gate       EgressLoosening `json:"gate,omitempty"`

	// Unused is the app's additions and removals that change nothing — adding
	// to an install with no list, removing an entry it does not have. Shown as
	// a warning (never a blocker): somebody wrote them expecting an effect.
	Unused []string `json:"unused,omitempty"`

	// Restricted is whether anything is refused at all. When it is not, the
	// app runs exactly as it would with no egress controls (R-186).
	Restricted bool `json:"restricted"`

	// Rules is what a runtime adapter enforces.
	Rules egress.Rules `json:"-"`
}

type EgressEntry struct {
	Entry string `json:"entry"`
	From  string `json:"from"` // install | app
}

type EgressLoosening string

type Evaluator struct {
	// contains filtered or unexported fields
}

type Fixed struct {
	Key    string          `json:"key"`
	Value  json.RawMessage `json:"value"`
	Source Source          `json:"source"`
}

type InstallEgress struct {
	Mode         spec.EgressMode `json:"mode"`
	List         []string        `json:"list"`
	BlockPrivate bool            `json:"block_private"`
	Loosening    EgressLoosening `json:"loosening"`
}

type Loosening struct {
	Kind  string `json:"kind"`
	Entry string `json:"entry,omitempty"`
	// Message is written for the app's owner (R-105).
	Message string `json:"message"`
}

type Overlay struct {
	// contains filtered or unexported fields
}

type PublicSharing string

type Setting struct {
	Key    string
	Value  any
	Source Source
}

type Source struct {
	Kind string `json:"kind"`
	Name string `json:"name,omitempty"`
	Key  string `json:"key,omitempty"`
}

type Store interface {
	Load(ctx context.Context) (Document, error)
	Save(ctx context.Context, doc Document, updatedBy string) error
}

type UpdateChannel string

type Window struct {
	Days   []time.Weekday
	Start  time.Duration // since midnight UTC
	Length time.Duration
}