# `rho repo`

## Purpose

`rho repo` owns the repo as a collaboration space.

It should initialize, inspect, and manage the repo-local Rho layout and policy.

## Responsibilities

- initialize visible repo-local `rho/`
- use git to handle atomicity of changes
- manage participant membership
- manage permissions policy
- manage encryption metadata
- manage repo-level tool and message roots
- help configure Git attributes and hooks where appropriate
- check things are configured correctly
- install github actions that will install rho and run rho tasks on PR requests / merge
- rho repo could auto comment / reject PRs that dont follow the .gitattributes rules 
- rho repo could run code in a github action against the mock data and report a full trace of everything
- rho repo could also install various standard security scanners which can be run on code that is submitted from users
- allow for including external resources like other repos or cloud storage / hugging face storage sources, especially for large files


## Root Manifest

Every Rho repo should have a root `rho.yaml`. It is the stable entry point for
the project and points to the files that define membership, permissions, crypto,
auth, tools, and external resources.

```yaml
rho: 1

project:
  id: rho://repo/github/org/project
  name: example-project
  owner: rho://id/github/rho-owner

transport:
  kind: git
  provider: github
  repo:
    owner: org
    name: project

members:
  file: rho/membership.yaml

participants:
  path: rho/participants/

permissions:
  file: rho/policy/permissions.yaml

crypto:
  file: rho/policy/crypto.yaml

auth:
  file: rho/policy/auth.yaml

tools:
  path: rho/tools/

resources:
  file: rho/resources.yaml
```

The transport section identifies the logical provider and repo. It should not
enforce whether a user's local Git remote uses SSH, HTTPS, a local folder, or
some other auth mechanism.

## Permissions

- all file paths should be abstracted to something like `rho://` to:
  - prevent path traversal on the machine they are interpreted on
  - validate paths in tool call checks
  - easily substitute private data paths at run time
  - work on all operating systems
- one canonical repo manifest
- one canonical permissions policy file
- `.gitattributes` integration where useful, but not as the only policy engine
- references to crypto policies managed by `rho crypto`
- references to auth policies managed by `rho auth`

## Important Design Note

Git metadata can help signal policy, but Git alone should not be the security boundary.

`rho run` and `rho middleware` must still enforce:

- who can request access
- who can write where
- what must be encrypted
- what needs approval

`rho/policy/permissions.yaml` owns read/write path semantics:

```yaml
version: 1

permissions:
  - id: direct_inbox
    pattern: rho/messages/inbox/{member.handle}/**
    expand: members
    write:
      allowed:
        - members
    read:
      encrypted_to:
        - "{member.id}"

  - id: group_messages
    pattern: rho/messages/groups/{group.id}/**
    expand: groups
    write:
      allowed:
        - "{group.members}"
    read:
      encrypted_to:
        - "{group.members}"

  - id: public_workspace
    pattern: workspace/public/**
    write:
      allowed:
        - members
    read:
      public: true
```

Direct inboxes are writable by admitted members and encrypted to the recipient.
Group paths are writable by group members and encrypted to all current group
members. Public paths do not require encryption.

For v1, permission and membership changes are admin-only. A later
`rho repo check-pr` should reject non-admin PRs that change `rho.yaml`,
`rho/membership.yaml`, `rho/policy/**`, or `rho/participants/**`.

## Crypto Policy And Git Filters

Rho can install Git clean/smudge filters for selected protected paths, inspired
by Transcrypt's Git integration. That should be treated as a working-tree
convenience, not the core policy.

Repo init should first write explicit policy files in the visible committed
`rho/` folder:

```text
rho/repo.yaml
rho.yaml
rho/membership.yaml
rho/participants/
rho/policy/permissions.yaml
rho/policy/crypto.yaml
rho/policy/auth.yaml
rho/tools/
```

Initial command shape:

```bash
rho repo init --repo-id rho://repo/local/example --owner rho://id/github/user1
```

The command should also write `.gitignore`, `.gitattributes`, and the minimal
host tool manifests for `run_mock`, `run_real`, and `publish_results`.

`rho/repo.yaml` records the owner identity. `rho/membership.yaml` is the
owner-managed list of admitted participants:

```yaml
version: 1
members:
  - identity: rho://id/github/user1
    role: owner
  - identity: rho://id/github/user2
    role: collaborator
```

New users can request access by adding their public bundle under
`rho/participants/` and a join request. The owner accepts by verifying the
identity, trusting it locally, then updating membership and policy files.

`.gitattributes` can mirror those policies for Git tooling:

```gitattributes
*.rhoenc binary
rho/messages/private/** filter=rho-crypt diff=rho-crypt
```

but `rho repo check`, `rho messages`, `rho run`, and `rho middleware` must still
validate the committed artifacts directly.

The initial implementation should prefer explicit `.rhoenc` envelope files over
transparent filters. That makes the two-account branch scenario inspectable and
avoids decrypted working-tree files being accidentally read by agents.

The transparent filter command is:

```bash
rho repo protect-path "secrets/**"
```

It appends a `filter=rho-crypt` rule to `.gitattributes`, creates or reuses a
repo key under `~/.rho/repo-keys/`, configures local Git clean/smudge filters to
call `rho crypto clean` and `rho crypto smudge`, and installs a pre-commit hook
that rejects protected files staged as plaintext. Authorized local users see
plaintext in the working tree, while the Git index and commits contain
`rho_transparent_file` encrypted envelopes.

The preferred policy-backed form is recipient-aware:

```bash
rho repo protect-path "rho/messages/inbox/user1/**" \
  --recipient rho://id/github/user1
```

That writes or updates a private-read path rule. The eventual canonical form is
`rho/policy/permissions.yaml`:

```yaml
permissions:
  - id: direct_inbox_user1
    pattern: rho/messages/inbox/user1/**
    write:
      allowed:
        - members
    read:
      encrypted_to:
        - rho://id/github/user1
```

Git filters and doctor/check-pr derive encrypted read requirements from
`permissions.yaml`. `rho/policy/crypto.yaml` only declares the crypto mechanisms
used by those policies.

Fresh clones should not need to rewrite policy just to make local Git encryption
work. They install the committed policy into local Git config with:

```bash
rho repo install-filters --root <clone> --rho-bin <path-to-rho>
```

This reads `rho/policy/permissions.yaml`, ensures encrypted path patterns have
matching `.gitattributes` entries, configures clean/smudge filters for that clone,
and installs the same pre-commit plaintext guard. The command should be idempotent
when the committed policy already matches `.gitattributes`.

## Doctor

`rho repo doctor --root <repo>` validates the local repo health without mutating
policy. The first implementation checks:

- `rho.yaml` exists and points to the repo policy files
- `rho/membership.yaml` exists and includes the owner
- each member has a matching public bundle under `rho/participants/`
- each participant bundle has signing and X25519 encryption public keys
- core policy files exist
- private-read path recipients are valid members
- `.gitattributes` has `rho-crypt` entries for encrypted paths
- tracked or untracked files under encrypted paths are encrypted
- recipient envelopes include the expected readers

This is the local deterministic safety rail. A later `rho repo check-pr` should
build on the same checks and add actor/diff rules for PR review.

## Future Work
- use https://github.com/huggingface/xet-core to store large files easily
- look at https://github.com/huggingface/hf-mount
- not be git only and not be github only
