# P4Sudo — Project Handoff to Claude Code

This document captures the full context of the P4Sudo design project so that
Claude Code (the `claude` CLI) can continue the work, including setting up
version control and driving the implementation forward.

---

## 1. Project Summary

**P4Sudo** is a site-level extension for the Perforce P4 Server Deployment Package (SDP) environments that gives
non-superuser P4 accounts the ability to run specific privileged
operations — or entirely site-defined commands — through a controlled, audited
mechanism. It is modeled on Unix `sudo`: a configuration file enumerates what
is permitted, every attempt is logged, and the user runs only what they are
explicitly authorized for.

The implementation uses the **P4Broker (p4broker)** to intercept the
non-native command `p4 sudo` and route it to a runtime dispatcher. From the
user's perspective it behaves like a native `p4` command. It is only
accessible through the `p4` CLI connected to the broker port — not through GUI
clients (P4V, etc.) or the P4 API.

The project will be deployed in **SDP (Server Deployment Package)** environments,
which provide a predictable directory structure. All P4Sudo files live under
`/p4/common/site/`.

---

## 2. Original Requirements (verbatim from the requester)

> I'd like to start implement a system that allows non-super P4 users to run
> certain commands that may require super access. Like the `sudo` command in
> UNIX/Linux, it will be controlled by a configuration file. I'd like the
> implementation to involve a p4broker, so that we can take advantage of its
> ability to create a new `p4 sudo` command without requiring server changes.
> A p4broker can intercept and optionally rewrite p4 commands inbound from a
> client and on their way to a P4 Server.
>
> A configuration file would define what commands users are allowed to run with
> elevated access. The p4broker also has a builtin `checkauth` feature we'll
> leverage to ensure the users connecting to the broker are authenticated. One
> of the features of the p4broker to use is the REWRITE feature. That REWRITE
> feature is not formally documented (and technically unsupported), but it works
> perfectly well and has for over a decade.  New commands created this way, with
> a p4broker, are not part of the API and can only be accessed with the 'p4'
> command line interface.
>
> The 'p4 sudo' will not be accessible by GUI clients like P4V. So, a component
> of the P4Sudo will be a web interface of some kind. Perhaps we can do that
> with a NodeJS app or perhaps a regular Apache web server?
>
> The broker filter scripts can be in any language. My intent is to use bash for
> ease of maintenance. The degree of complexity is at an appropriate level for
> handling in bash.

### System Components and Features (from requester)

- A `p4 sudo` command implemented using a p4broker configuration file with
  supplemental scripts.
- The `p4 sudo` command will use the builtin `checkauth` feature to ensure users
  are authenticated.
- The `p4 sudo` command will have logic that validates, based on a configuration
  file, whether the authenticated user is authorized to perform whatever it is
  they are trying to do.
- The `p4 sudo` command will accept commands and arguments/options, and vet them
  against its configuration file.
- The p4broker will intercept the `p4 help sudo` command, and display detailed
  help documentation (as `p4 help edit` or `p4 help <any-real-p4d-command>`).
- The P4Sudo tool will be deployed in SDP environments. Files will be deployed
  under the `/p4/common/site` directory tree, mostly within
  `/p4/common/site/p4sudo`, with a config file at
  `/p4/common/site/config/p4sudo.cfg`.
- SDP allows for `/p4/common/site/bin` for utilities in the PATH, but P4Sudo
  scripts are called by p4broker with fully qualified paths (no PATH requirement).
  A CLI convenience wrapper `p4sudo` may live in `/p4/common/site/bin`.
- The `p4sudo.cfg` file format needs to be defined — inspired by OS sudo but not
  required to follow that format exactly.
- User-defined commands will be supported, e.g. `p4 sudo mkproj <args>` where
  `mkproj` is a site-defined command backed by a script.

### Additional Technical Notes from Requester

- The p4broker REWRITE feature is undocumented but stable and proven over 10+
  years. Working code examples exist and can be provided.
- A web interface component is planned for GUI users who can't use `p4 sudo`
  via CLI. Technology choice (Node.js or Apache) is TBD.
- A specific first use case (not yet described in detail) will be provided to
  sharpen the design. It should be incorporated once shared.

---

## 3. Architecture

```
p4 client (CLI)
      │
      │  p4 sudo <subcmd> <args>
      ▼
┌─────────────┐
│  p4broker   │  ◄──── broker config + filter scripts
│             │         /p4/common/site/p4sudo/
└──────┬──────┘
       │
       │  REWRITE or FILTER action
       │
       ├─── [checkauth]   Verify requesting user has valid ticket
       │
       ├─── [validation]  Read p4sudo.cfg; match user/group against rules
       │
       ├─── [dispatch]    Route to:
       │                    A) Site-defined command script, OR
       │                    B) Native p4 command re-executed as service acct
       │
       └─── [audit log]   Record outcome (allow/deny) with timestamp
```

### Key Components

| Component | Location | Purpose |
|---|---|---|
| p4broker binary | System PATH (SDP-managed) | Intercepts `p4 sudo` |
| Broker config | `/p4/N/broker/p4broker.conf` (SDP convention) | Declares the `sudo` filter/rewrite rule |
| P4Sudo runtime script | `/p4/common/site/p4sudo/p4sudo.sh` | Core dispatch logic |
| Configuration file | `/p4/common/site/config/p4sudo.cfg` | Access control rules and command definitions |
| Command scripts | `/p4/common/site/p4sudo/commands/` | Site-defined subcommand implementations |
| Logs | `/p4/common/site/p4sudo/logs/` | Operational and audit logs |
| CLI wrapper (optional) | `/p4/common/site/bin/p4sudo` | Convenience alias for admin use |
| Web interface | TBD (Node.js or Apache) | Browser-based access for GUI users |

---

## 4. Directory Layout

```
/p4/common/site/
├── bin/
│   └── p4sudo                  # Optional CLI convenience wrapper
├── config/
│   └── p4sudo.cfg              # Access control configuration
└── p4sudo/
    ├── p4sudo.sh               # Core runtime (called by broker)
    ├── commands/               # Site-defined command scripts
    │   ├── mkproj.sh
    │   └── archive.sh
    └── logs/
        ├── p4sudo.log          # Operational log
        └── audit.log           # Audit trail
```

---

## 5. Design Artifacts Produced So Far

The following three artifacts were drafted in the initial design session.
They should be committed to version control as the starting point.

---

### 5.1 — `p4sudo.cfg` (Configuration File Format)

The format is INI-style with three sections: `[settings]`, `[commands]`,
and `[rules]`. Inline comments explain every field.

**Key design decisions:**
- INI-style was chosen because it is easy to parse in bash with `awk`
  (section-aware parsing is a well-established pattern).
- `[commands]` and `[rules]` are separate sections so that *what commands
  exist* is decoupled from *who can run them*.
- The `[rules]` section uses a whitespace-delimited column format within
  the INI structure — readable, easy to parse left-to-right.
- Native p4 commands (e.g. `protect`) 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 for
  custom help text.
- Explicit `ALLOW` / `DENY` action verbs are used rather than implicit
  "allow by presence", making DENY overrides readable and unambiguous.
- Arg-pattern matching uses shell-glob patterns matched against the
  normalized argument string. This is an area for further discussion —
  it's flexible but requires care to avoid overly loose patterns.

```ini
##############################################################################
# p4sudo.cfg  —  P4Sudo Configuration File
# Location: /p4/common/site/config/p4sudo.cfg
#
# Format version: 1
##############################################################################


[settings]

command_dir    = /p4/common/site/p4sudo/commands
log            = /p4/common/site/p4sudo/logs/p4sudo.log
audit_log      = /p4/common/site/p4sudo/logs/audit.log
p4port         = ssl:perforce:1666
p4sudo_user    = p4sudo-svc
max_args       = 20
script_timeout = 300
debug          = false


[commands]

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]

protect.type        = native
protect.description = Edit the P4 protections table (requires elevation).
protect.usage       = p4 sudo protect


[rules]

# 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 (uncomment and adapt):
# DENY   user:former-admin    *
```

---

### 5.2 — `p4 help sudo` Output

This is what users see when they run `p4 help sudo` or `p4 sudo help`.
It mirrors the style of native `p4 help` output.

```
p4 help sudo
==============================================================================

    sudo -- Run a command with elevated privileges (P4Sudo)

    p4 sudo <subcommand> [options] [arguments]
    p4 sudo help
    p4 sudo help <subcommand>

DESCRIPTION

    The 'p4 sudo' command allows authorized P4 users to run specific
    commands with elevated server privileges, or to execute site-defined
    administrative commands, without requiring full P4 super-user
    access for their normal account.

    Authorization is governed by the site configuration file:
        /p4/common/site/config/p4sudo.cfg

    Authentication is required.  You must have a valid P4 ticket (i.e.,
    be logged in via 'p4 login') before invoking any 'p4 sudo' command.

    Two categories of subcommands are available:

    1. ELEVATED NATIVE COMMANDS
       Standard P4 commands that your account normally lacks permission
       to run (e.g., 'protect', 'depot', 'group') can be invoked through
       'p4 sudo' if your site configuration permits it.

    2. SITE-DEFINED COMMANDS
       Custom administrative commands written by your site team and deployed
       under 'p4 sudo'.  These are not native 'p4' commands.

USAGE

    p4 sudo <subcommand> [subcommand-specific options and arguments]
    p4 sudo help
    p4 sudo help <subcommand>

EXAMPLES

    p4 sudo help
    p4 sudo help mkproj
    p4 sudo mkproj myteam-widget
    p4 sudo mkproj myteam-widget --template standard --owner jsmith
    p4 sudo archive //depot/legacy/... --before 2022/01/01 --dry-run
    p4 sudo archive //depot/legacy/... --before 2022/01/01
    p4 sudo protect

NOTES

    - Only accessible through the 'p4' CLI connected to the broker port.
    - Not available in P4V or other GUI clients.
    - Contact your P4 administrator to request access.

SEE ALSO

    p4 help login
    p4 help protect
    p4 sudo help <subcommand>
```

---

### 5.3 — Admin and Maintainer's Guide (high-level, pre-implementation)

Key points from the admin guide:

- **Config file security:** `p4sudo.cfg` must be writable only by root or
  the SDP `perforce` OS user. World-writable config = critical vulnerability.
- **Command script security:** Scripts must be owned by trusted OS users,
  not by the `p4broker` process user.
- **Service account (`p4sudo-svc`):** Must hold minimum necessary P4
  permissions. Should NOT appear in `p4sudo.cfg` rules (prevents
  privilege escalation via self-reference). Needs a long-lived/non-expiring
  broker-side ticket.
- **Group membership:** Resolved at request time by querying p4d (not cached),
  so group changes take effect immediately.
- **No broker restart needed** for config changes, rule changes, or new
  command scripts. Restart only needed if `p4broker.conf` itself changes.
- **Audit log:** Never delete/modify entries in place. Use log rotation with
  archiving. Forward to centralized logging if available.
- **Input handling:** Runtime normalizes and validates all arguments before
  passing to scripts. Scripts must treat all input as untrusted.
- **Web interface (planned):** Will authenticate via P4 credentials or
  SSO. Will present only authorized commands. Will use same backend and
  audit trail as CLI path.

---

## 6. Open Questions and Decisions Pending

These items were identified during the initial design session and need to
be resolved before or during implementation:

1. **Arg-pattern matching granularity:** Should glob matching on the full
   normalized argument string be the rule-layer's job, or should argument
   validation be pushed entirely into command scripts? The current design
   does both (rules do coarse filtering; scripts do fine-grained validation),
   but the boundary needs to be clearly documented.

2. **`p4 sudo help <subcommand>` routing:** When `help` is the first
   argument, the broker needs to recognize this and return the help text
   for the named subcommand from `p4sudo.cfg`. The exact broker-side
   mechanism for this (separate filter rule vs. logic inside the runtime
   script) needs to be decided.

3. **Service account privilege scope:** Should `p4sudo-svc` have global
   `super` access, or should it be scoped more narrowly per command? The
   latter is more secure but more complex to administer. Likely
   command-dependent.

4. **Web interface technology:** Node.js app or Apache/CGI? Factors to
   consider: existing SDP environment, maintenance burden, SSO requirements,
   whether the web UI is read-only (view audit logs) or fully interactive
   (execute sudo commands from browser).

5. **First use case:** The requester has a specific first concrete use case
   to share, which will likely sharpen several of the above decisions.
   **This should be the first thing to capture in the next session.**

6. **`p4sudo` CLI wrapper:** Exact behavior — does it just call `p4 -p
   <broker-port> sudo "$@"`, or does it add more convenience logic?

7. **Configuration file versioning:** The `[settings]` section has a
   `format_version` concept implied; should this be made explicit with a
   `format_version = 1` key so the runtime can detect and reject incompatible
   future config formats?

---

## 7. Suggested First Steps for Claude Code

1. **Create a P4 depot and workspace** for this project. Suggested
   depot name: `p4sudo` (a local or stream depot under your admin server).
   A stream depot with a `//p4sudo/main` mainline is recommended.

2. **Add and submit the three design artifacts** from section 5 as the
   initial changelist, in their appropriate file locations:
   - `//p4sudo/main/doc/p4sudo.cfg.example` — annotated reference config
   - `//p4sudo/main/doc/p4help-sudo.txt` — help text
   - `//p4sudo/main/doc/admin-guide.md` — admin guide

3. **Capture the first use case** from the requester and add it to
   `//p4sudo/main/doc/use-cases.md`.

4. **Resolve open questions** in section 6 through conversation, then
   update the design docs before writing any implementation code.

5. **Implement in this suggested order** (after design is stable):
   a. `p4sudo.cfg` parser (bash function/library)
   b. Core runtime dispatcher (`p4sudo.sh`)
   c. Broker config snippet for the `sudo` filter/rewrite rule
   d. `p4 help sudo` interception
   e. First real command script (driven by the first use case)
   f. CLI wrapper (`/p4/common/site/bin/p4sudo`)
   g. Web interface (after CLI path is solid)

---

## 8. Reference: p4broker REWRITE Feature

The REWRITE feature is the key p4broker mechanism used by P4Sudo. It allows
the broker to intercept a command and rewrite it to a different command
before forwarding to p4d, or to execute a script and return its output
directly to the client without ever forwarding to p4d.

The requester has working code examples of the REWRITE feature and can
provide them. **Ask the requester to share these before implementing the
broker config snippet.**

The REWRITE feature is:
- Not formally documented by Perforce.
- Technically unsupported.
- Stable and proven in production over 10+ years
- Not expected to be removed.

---

*Handoff prepared from initial design session in Claude.ai.*
*Continue in Claude Code (`claude` CLI) for implementation and version control.*