ngit-grasp/2cdc-nip-86-relay-management-api.md

# NIP-86 Relay Management API

**ID:** 2cdc

> **⚠️ COORDINATION REQUIRED:** This issue is part of the Administrator Observability and Management Strategy (issue ec1f).
> **Before starting work:** Check issue ec1f for current phase, dependencies, and coordination requirements.
> **STATUS:** Deferred in favor of simpler HTTP API first (see ec1f Phase 3). NIP-86 compliance planned for post-Phase 3.

## Issue Summary

Implement NIP-86 (Relay Management API) to provide authenticated administrative control over the relay. This enables operators to blacklist users, delete repositories, ban event posting, and perform other management actions through a standardized API.

## NIP-86 Overview

NIP-86 defines a standardized API for relay management operations using Nostr events and HTTP endpoints. It provides:
- Authentication via Nostr event signatures
- RESTful API for management actions
- Standardized endpoints and response formats
- Audit trail of management actions

Reference: https://github.com/nostr-protocol/nips/blob/master/86.md

## Required Management Operations

### 1. User management
- **Blacklist user from all operations**
  - Ban user (npub) from pushing to any repository
  - Ban user from posting any events to the relay
  - Block all WebSocket connections from user
  - Temporary bans (time-limited) vs permanent bans
  - Whitelist exceptions (allow banned user back)

- **User-specific restrictions**
  - Block user from creating new repos (but allow pushes to existing)
  - Read-only mode for specific users
  - Custom storage quotas per user

### 2. Repository management
- **Delete repository**
  - Remove git repository data
  - Remove associated events (proposals, revisions, etc.)
  - Cascade deletion (what happens to dependent data?)
  - Soft delete vs hard delete
  - Backup before deletion option

- **Blacklist repository**
  - Prevent new pushes to specific repo
  - Hide repo from queries
  - Mark repo as archived/frozen

- **Repository-specific actions**
  - Force garbage collection on large repo
  - Set custom size limits per repo
  - Transfer repository to different maintainer

### 3. Event management
- **Delete individual events**
  - Remove specific event by ID
  - Cascade to related events?
  - Audit log of deletions

- **Block event types**
  - Disable specific event kinds relay-wide
  - Per-user event kind restrictions

### 4. Storage management
- **Force cleanup operations**
  - Run git GC on all repos
  - Compact database
  - Clear caches
  - Prune old events

- **Set limits**
  - Adjust global storage limits
  - Modify per-user quotas
  - Configure per-repo limits

### 5. Monitoring and audit
- **View recent admin actions**
  - Audit log of all management operations
  - Who performed what action when
  - Track changes to configuration

- **System operations**
  - Trigger backup
  - Reload configuration
  - Export metrics
  - Health check

## NIP-86 Endpoints to Implement

Based on NIP-86 specification:

```
POST /api/v1/relay/management
```

With action types:
- `ban-user` - Blacklist user from all operations
- `allow-user` - Remove user from blacklist
- `delete-event` - Remove specific event
- `delete-repository` - Remove repository and associated data
- `block-repository` - Prevent writes to repository
- `set-user-quota` - Set custom storage limit for user
- `set-repo-quota` - Set custom storage limit for repository
- `run-gc` - Force garbage collection
- `get-stats` - Retrieve relay statistics
- `get-audit-log` - View management action history

## Authentication

NIP-86 uses Nostr event signatures for authentication:
1. Client creates kind 27235 event with management command
2. Event includes authentication (admin npub signature)
3. Relay validates signature and admin privileges
4. Executes command if authorized
5. Returns result as signed event

### Admin configuration
- Configure admin npubs in relay config
- Support multiple admin users
- Role-based permissions (read-only admin, full admin, etc.)
- Emergency recovery mechanism

## Investigation Tasks

### NIP-86 Specification
- [ ] Read full NIP-86 specification
- [ ] Understand authentication flow
- [ ] Review example implementations
- [ ] Identify gaps between NIP-86 and our needs
- [ ] Determine if custom extensions needed

### Implementation Planning
- [ ] Design admin permission system
- [ ] Create database schema for blacklists and audit log
- [ ] Plan cascade deletion strategy for repos
- [ ] Design API endpoints structure
- [ ] Plan authentication middleware

### Security Considerations
- [ ] Verify Nostr signature validation for admin events
- [ ] Implement rate limiting on management endpoints
- [ ] Protect against replay attacks
- [ ] Audit logging for all management actions
- [ ] Emergency admin override mechanism

### Integration Points
- [ ] Integrate blacklist checks into event handler
- [ ] Add blacklist checks to git push handler
- [ ] Hook into connection handler for banned users
- [ ] Update subscription handler to respect blocks
- [ ] Integrate with storage quota system

### User Experience
- [ ] Design clear error messages for blocked users
- [ ] Implement graceful degradation (blocked users see reason)
- [ ] Create admin CLI tool or web UI
- [ ] Document all management operations
- [ ] Provide examples of common admin tasks

## Questions to Answer

1. **How to handle existing data from banned users?**
   - Leave existing repos/events?
   - Auto-delete all user data?
   - Admin choice at ban time?

2. **What happens to PRs/proposals for deleted repos?**
   - Orphan them (keep events but mark repo gone)?
   - Delete all related events?
   - Return errors on queries?

3. **How to handle multiple admins?**
   - All admins have full privileges?
   - Role-based access control?
   - Audit who performed what action?

4. **What operations require confirmation?**
   - Destructive operations need two-step?
   - Ability to preview deletion impact?
   - Undo/rollback capability?

5. **How to communicate bans to users?**
   - Return specific error codes?
   - NIP-specific error messages?
   - Permanent vs temporary ban messages?

## Implementation Considerations

### Database schema
```sql
-- Admin users
CREATE TABLE admins (
  npub TEXT PRIMARY KEY,
  role TEXT NOT NULL,
  added_at INTEGER NOT NULL
);

-- Blacklisted users
CREATE TABLE blacklisted_users (
  npub TEXT PRIMARY KEY,
  reason TEXT,
  banned_at INTEGER NOT NULL,
  banned_by TEXT, -- admin npub
  expires_at INTEGER, -- NULL for permanent
  ban_type TEXT -- 'full', 'events_only', 'repos_only'
);

-- Audit log
CREATE TABLE admin_audit_log (
  id INTEGER PRIMARY KEY,
  admin_npub TEXT NOT NULL,
  action TEXT NOT NULL,
  target TEXT, -- user/repo/event ID
  details TEXT, -- JSON
  timestamp INTEGER NOT NULL
);
```

### Performance
- Cache blacklist in memory for fast checks
- Background task to expire temporary bans
- Efficient cascade deletion for large repos
- Async operations for slow tasks (GC, deletion)

### Safety
- Dry-run mode for destructive operations
- Backups before major deletions
- Confirmation required for irreversible actions
- Rate limiting on management endpoints

## Findings

*(To be filled in during investigation)*

## Implementation Plan

*(To be determined after investigation)*

## Success Criteria

- Full NIP-86 compliance for core operations
- Ability to blacklist users from all operations
- Ability to delete repositories with proper cleanup
- Audit trail of all management actions
- Secure authentication using Nostr signatures
- Clear documentation for relay operators
- CLI tool or web UI for common admin tasks

## Related Issues

- See Management Dashboard for UI/metrics
- See Storage Limits for quota enforcement
- See Poor Naughty List for abuse detection
- See Defensive Relay Features for rate limiting