138 lines
4.1 KiB
Markdown
138 lines
4.1 KiB
Markdown
# Security Model
|
|
|
|
## Authentication vs Git Configuration
|
|
|
|
### How User Identity Works
|
|
|
|
**Question:** Can't I just set my git username to anything and bypass validation?
|
|
|
|
**Answer:** No. The validation uses **Gitea account authentication**, not git commit authors.
|
|
|
|
#### Git Commit Author (NOT used for validation)
|
|
```bash
|
|
# This can be set to anything locally
|
|
git config user.name "anyone"
|
|
git config user.email "anyone@example.com"
|
|
git commit -m "My commit"
|
|
```
|
|
These values are **NOT** used for plugin ownership validation.
|
|
|
|
#### PR Creator (used for validation)
|
|
When you create a Pull Request:
|
|
1. You must be logged into your Gitea account
|
|
2. The PR is created through Gitea's authenticated API
|
|
3. `github.event.pull_request.user.login` = your authenticated Gitea username
|
|
|
|
**This is what validation checks against.**
|
|
|
|
### Example Attack Scenario (Prevented)
|
|
|
|
❌ **Attacker tries:**
|
|
```bash
|
|
# Configure git to impersonate someone
|
|
git config user.name "victim"
|
|
git config user.email "victim@example.com"
|
|
|
|
# Modify victim's plugin
|
|
vim plugins/victim-plugin.json
|
|
# Change author to "attacker"
|
|
|
|
git commit -m "Update plugin"
|
|
git push
|
|
|
|
# Create PR (must log into Gitea as "attacker" account)
|
|
```
|
|
|
|
✅ **What happens:**
|
|
1. PR is created by authenticated Gitea user: `attacker`
|
|
2. Validation script receives: `prAuthor = "attacker"`
|
|
3. Validation checks original plugin from main branch: `original.author = "victim"`
|
|
4. Check fails: `"victim" !== "attacker"`
|
|
5. **Result:** ❌ `Cannot modify plugin owned by "victim" (you are "attacker")`
|
|
|
|
The git commit author is irrelevant - what matters is **who is logged into Gitea when creating the PR**.
|
|
|
|
## Security Measures
|
|
|
|
### 1. Dual Checkout
|
|
```yaml
|
|
- Checkout main branch → base/ (trusted validation scripts)
|
|
- Checkout PR branch → pr/ (untrusted user submissions)
|
|
```
|
|
Validation script always runs from `base/`, never from PR branch.
|
|
|
|
### 2. Infrastructure Protection
|
|
PRs that modify `.gitea/` directory are automatically rejected.
|
|
|
|
### 3. Ownership Verification
|
|
All modifications/deletions check **original ownership from main branch**:
|
|
```javascript
|
|
// Check original plugin from main (base/)
|
|
const originalPlugin = readFile('../base/plugins/example.json');
|
|
|
|
// User can only modify if they own the original
|
|
if (originalPlugin.author !== prAuthor) {
|
|
reject("Cannot modify plugin owned by someone else");
|
|
}
|
|
```
|
|
|
|
### 4. Author Field Validation
|
|
New plugins must have `author` field matching the PR creator's authenticated Gitea username.
|
|
|
|
## What About Collaboration?
|
|
|
|
**Q:** What if I want someone else to update my plugin?
|
|
|
|
**A:** They cannot submit PRs directly. Options:
|
|
1. Transfer ownership by updating the `author` field yourself
|
|
2. They fork your plugin repo and create their own plugin entry
|
|
3. Add them as collaborators to your plugin repository (not the directory)
|
|
|
|
## Trust Model
|
|
|
|
### Trusted Components
|
|
- Main branch content (validated history)
|
|
- Gitea authentication system
|
|
- GitHub Actions runner environment
|
|
- Validation scripts on main branch
|
|
|
|
### Untrusted Components
|
|
- PR branch content (user submissions)
|
|
- Git commit metadata (names, emails)
|
|
- PR descriptions and comments
|
|
|
|
### Validation Flow
|
|
```
|
|
1. User authenticates to Gitea → Trusted user identity
|
|
2. User creates PR → github.event.pull_request.user.login
|
|
3. Validation runs from main branch scripts → Trusted code
|
|
4. Checks plugin ownership against main → Trusted ownership data
|
|
5. Validates PR author matches plugin author → Secure check
|
|
```
|
|
|
|
## Reporting Security Issues
|
|
|
|
If you find a security vulnerability in the plugin directory system:
|
|
1. **Do NOT create a public issue or PR**
|
|
2. Contact the repository maintainer directly
|
|
3. Provide detailed reproduction steps
|
|
4. Allow time for a fix before public disclosure
|
|
|
|
## Additional Safeguards
|
|
|
|
### Rate Limiting
|
|
Gitea's built-in rate limiting prevents spam PR attacks.
|
|
|
|
### Branch Protection
|
|
The `main` branch is protected:
|
|
- Direct pushes disabled
|
|
- All changes via PR
|
|
- Auto-merge only after validation passes
|
|
|
|
### Audit Trail
|
|
All changes are tracked in git history:
|
|
- Who created the PR (Gitea account)
|
|
- What changed (git diff)
|
|
- When it was merged (git commit timestamp)
|
|
- Why validation passed (CI logs)
|