##############################################################################
# p4sudo.cfg  —  P4Sudo Configuration File
# Location: /p4/common/site/config/p4sudo.cfg
#
# Format version: 1
#
# This is an annotated reference/example configuration file for P4Sudo.
# Copy this file to /p4/common/site/config/p4sudo.cfg and customize for
# your site.
#
# FILE SECURITY:
#   This file must be readable by the p4broker process user and writable
#   ONLY by root or the SDP 'perforce' OS user.  A world-writable config
#   is a critical security vulnerability.
#
#   Recommended permissions:
#     chown perforce:perforce /p4/common/site/config/p4sudo.cfg
#     chmod 640 /p4/common/site/config/p4sudo.cfg
#
##############################################################################


[settings]

# Directory containing site-defined command scripts.
# Scripts must be owned by a trusted OS user (root or perforce), not by
# the p4broker process user.
command_dir    = /p4/common/site/p4sudo/commands

# Operational log — records invocations and outcomes.
log            = /p4/common/site/p4sudo/logs/p4sudo.log

# Audit log — immutable record of allow/deny decisions with timestamps.
# Never delete or modify entries in place; use log rotation with archiving.
audit_log      = /p4/common/site/p4sudo/logs/audit.log

# The P4PORT of the p4d server (NOT the broker port).
# Used by the runtime to execute elevated commands.
p4port         = ssl:perforce:1666

# The P4Sudo service account username.  This account must:
#   - Hold minimum necessary P4 permissions for the commands it runs.
#   - NOT appear in [rules] section (prevents privilege escalation via
#     self-reference).
#   - Have a long-lived / non-expiring broker-side ticket.
p4sudo_user    = p4sudo-svc

# Maximum number of arguments accepted per invocation (safety limit).
max_args       = 20

# Timeout in seconds for site-defined command scripts.
script_timeout = 300

# Set to true to enable verbose debug logging (operational log only).
# Do not leave enabled in production.
debug          = false


[commands]

# Format for each command entry:
#
#   <name>.type        = script | native
#   <name>.script      = /absolute/path/to/script.sh   # required if type=script
#   <name>.description = One-line description
#   <name>.usage       = p4 sudo <name> <synopsis>
#   <name>.ui_def      = /absolute/path/to/<name>.ui.yaml  # optional; required
#                        for commands that expose a web UI form with typed fields,
#                        grouped inputs, required/optional field definitions, and
#                        template token mappings.  See doc/mkblackbelt.ui.yaml
#                        for an annotated example.
#
# NATIVE COMMANDS:
#   Standard p4 commands (e.g. 'protect', 'depot', 'group') do NOT require
#   a [commands] entry.  They can be referenced directly in [rules] by their
#   bare name.  A [commands] entry for a native command is optional and only
#   needed to supply custom help text.
#
# SCRIPT COMMANDS:
#   Site-defined commands that are backed by a local script.  The runtime
#   will call the script with the validated argument list.  Scripts must
#   treat all input as untrusted.

mkproj.type        = script
mkproj.script      = /p4/common/site/p4sudo/commands/mkproj.sh
mkproj.description = Create a new project depot, mainline stream, and default group permissions.
mkproj.usage       = p4 sudo mkproj <project-name> [--template <template>] [--owner <user>] [--dry-run]

archive.type        = script
archive.script      = /p4/common/site/p4sudo/commands/archive.sh
archive.description = Archive and obliterate files from a specified depot path.
archive.usage       = p4 sudo archive <depot-path> [--before <YYYY/MM/DD>] [--dry-run]

# Optional: override help text for native 'protect' command.
protect.type        = native
protect.description = Edit the P4 protections table (requires elevation).
protect.usage       = p4 sudo protect

# PPN-specific: Bootstrap a new Black Belt customer.
# The ui_def file defines the web form (field types, required/optional,
# template token mappings).  This command runs on the PPN server only.
mkblackbelt.type        = script
mkblackbelt.script      = /p4/common/site/p4sudo/commands/mkblackbelt.sh
mkblackbelt.description = Bootstrap a new Black Belt consulting customer on PPN.
mkblackbelt.usage       = p4 sudo mkblackbelt <CustomerTag> [options]
mkblackbelt.ui_def      = /p4/common/site/p4sudo/commands/mkblackbelt.ui.yaml


[rules]

# Format:
#   <ACTION>  <PRINCIPAL>  <COMMAND>  [<ARG-PATTERN>]
#
#   ACTION       : ALLOW | DENY
#   PRINCIPAL    : user:<username> | group:<groupname>
#   COMMAND      : command name, or * to match any command
#   ARG-PATTERN  : (optional) shell-glob matched against normalized argument
#                  string.  Omit to match any args.  Use NOARGS to require
#                  that no arguments are provided.
#
# Rules are evaluated top to bottom; first match wins.
# DENY rules are explicit and unambiguous — they do not fall through.
#
# SECURITY NOTE:
#   Arg-pattern matching provides coarse filtering at the rule layer.
#   Fine-grained argument validation is the responsibility of command scripts.
#   Document the boundary clearly for each command.

# P4 administrators may run any p4 sudo command without restriction.
ALLOW  group:p4admin          *

# Development leads may create new projects (any valid project name/options).
ALLOW  group:devleads         mkproj

# Development leads may inspect archive candidates but not execute the archive.
ALLOW  group:devleads         archive        *--dry-run*

# A named user with full archive authority.
ALLOW  user:alice             archive

# Release managers may open the protections table for editing.
ALLOW  group:rel-mgrs         protect        NOARGS

# DENY example — explicit denial takes effect on first match:
# DENY   user:former-admin    *