feat: add Secret Management API specification (OpenAPI 3.1)

[kevalyq]

📋 Overview

Implements the complete OpenAPI 3.1 specification for Secret Management API (CRUD + Sharing), unblocking Frontend development for file upload integration and PWA features.

✨ What This PR Does

Secret CRUD Endpoints (5 total)

• GET /v1/secrets - List user's secrets with pagination
• POST /v1/secrets - Create new secret with encrypted fields
• GET /v1/secrets/{id} - View secret details
• PATCH /v1/secrets/{id} - Update secret (version auto-incremented)
• DELETE /v1/secrets/{id} - Soft delete secret

Secret Sharing Endpoints (3 total)

• GET /v1/secrets/{id}/shares - List all shares for a secret
• POST /v1/secrets/{id}/shares - Grant read/write/admin access
• DELETE /v1/secrets/{id}/shares/{shareId} - Revoke access

🔑 Key Features Documented

Schemas

• Secret: Encrypted fields (title, username, password, url, notes), tags, expiration, versioning
• SecretShare: User/role sharing with permission hierarchy

Permission Hierarchy

admin → Can do everything (view, update, delete) - but not grant shares (owner only)
write → View + update secret + upload attachments
read  → View secret + download attachments (read-only)

XOR Constraint

Share with user OR role (not both):

// Valid: Share with user
{"user_id": "uuid", "permission": "read"}

// Valid: Share with role
{"role_id": 5, "permission": "write"}

// Invalid: Both user_id AND role_id (422 error)

Validation Rules

• title: Required, max 255 chars
• username, password, url, notes: Optional, with max lengths
• tags: Array of strings (max 50 chars each)
• expires_at: Must be future date
• permission: Enum (read, write, admin)

Error Responses

• 400: Bad Request (invalid parameters)
• 401: Unauthorized (missing/invalid token)
• 403: Forbidden (insufficient permissions)
• 404: Not Found (secret doesn't exist)
• 422: Validation Error (with detailed field errors)

📦 Files Changed

• docs/openapi.yaml - Added 8 new endpoints + 2 schemas (~593 lines)
• CHANGELOG.md - Documented new API specification

✅ Quality Gates

• ✅ OpenAPI Validation: Valid with Redocly CLI (2 warnings - cosmetic only)
• ✅ Prettier: Code formatted
• ✅ Markdownlint: All docs pass
• ✅ REUSE 3.3: Compliant (41/41 files)
• ✅ Domain Policy: secpal.app/secpal.dev only
• ✅ Preflight: All checks passed (593 changed lines)

🎯 Unblocks

Frontend Issues (can now start):

• enhancement: Add file upload to backend API for Secret attachments frontend#141 - File Upload Integration
• enhancement: Implement IndexedDB storage for offline file queue frontend#142 - IndexedDB Offline Queue
• [EPIC] Client-Side File Encryption for Zero-Knowledge Architecture frontend#143 - Client-side File Encryption

Backend PRs (already merged, this documents them):

• feat: add SecretShare model and migration (Phase 3 foundation) api#183 - SecretShare Model Foundation ✅
• Phase 3: Secret Sharing & Access Control (RBAC Integration) api#185 - Full Secret API Implementation ✅

🔗 Related

• Part of: [EPIC] Secret Management System (Password Vault) api#173 (Secret Management System Epic - Phase 3)
• Backend Phase 1: Phase 1: Secret Model + CRUD API (Backend Foundation) api#174 (Secret Model) ✅ Merged
• Backend Phase 2: Phase 2: File Attachments API (Upload/Download/Encryption) api#175 (File Attachments) ✅ Merged
• Backend Phase 3: Phase 3: Secret Sharing & Access Control (RBAC Integration) api#182 (Sharing) ✅ Complete

🚫 Breaking Changes

None - These are all new endpoints. Existing API endpoints unchanged.

📝 Checklist

• OpenAPI 3.1 spec valid (Redocly)
• CHANGELOG.md updated
• All quality gates passing
• REUSE compliant
• Conventional commit format
• Self-review completed

---

Estimated Impact: Unblocks 3 Frontend issues + documents 2 merged Backend PRs
Spec Coverage: 8 endpoints, 2 schemas, 5 error types, permission hierarchy, XOR constraint

[github-actions]

💡 Tip: Consider Using Draft PRs

Benefits of opening PRs as drafts initially:

• 💰 Saves CI runtime and Copilot review credits
• 🎯 Automatically sets linked issues to "🚧 In Progress" status
• 🚀 Mark "Ready for review" when done to trigger full CI pipeline

How to convert:

1. Click "Still in progress? Convert to draft" in the sidebar, OR
2. Use gh pr ready when ready for review

This is just a friendly reminder - feel free to continue as is! 😊

[Copilot]

Pull Request Overview

This PR adds a complete OpenAPI 3.1 specification for the Secret Management API, providing 8 new endpoints for CRUD operations and sharing functionality. The specification documents encrypted secret storage with fields for credentials, tags, versioning, and expiration, along with a permission-based sharing system supporting user and role-based access control.

Key additions include:

• 5 Secret CRUD endpoints with encrypted field support and versioning
• 3 Secret Sharing endpoints with XOR constraint (user OR role) and permission hierarchy (read/write/admin)
• Comprehensive validation rules, error responses, and detailed examples for all endpoints

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
docs/openapi.yaml	Adds Secret and SecretShare schemas with complete CRUD and sharing endpoint definitions, including authentication, pagination, validation rules, and error responses (400, 401, 403, 404, 422)
CHANGELOG.md	Documents the addition of Secret Management API specification with details on endpoints, schemas, validation rules, XOR constraints, and permission hierarchy