feat: add SecretShare model and migration (Phase 3 foundation)

[kevalyq]

Overview

Implements the foundation for Phase 3: Secret Sharing & Access Control (#182) by adding database schema, models, and relationships for fine-grained permission management.

Changes

Database Schema

• ✅ New secret_shares table with UUID primary key
• ✅ XOR constraint: share with user OR role (not both)
• ✅ Permission levels: read, write, admin (hierarchical)
• ✅ Optional expiration via expires_at timestamp
• ✅ Foreign keys with CASCADE DELETE for referential integrity
• ✅ Indexes on: secret_id, user_id, role_id, expires_at
• ✅ Unique constraints prevent duplicate shares

Models

• ✅ SecretShare model with UUID, relationships, and scopes

  • secret() - BelongsTo Secret
  • user() - BelongsTo User (nullable, XOR with role)
  • role() - BelongsTo Role (nullable, XOR with user)
  • granter() - BelongsTo User (who granted access)
  • active() - Scope for non-expired shares
  • is_expired - Accessor for expiration logic

• ✅ Secret model extensions

  • shares() - HasMany SecretShare relationship
  • userHasPermission($user, $permission) - Authorization helper with hierarchy

Tests

• ✅ Migration tests (3 tests): Schema validation, indexes, constraints
• ✅ Model tests (10 tests): Relationships, scopes, accessors, expiration logic
• ✅ All 355 tests passing (1116 assertions)

Testing

# Migration tests
ddev exec "vendor/bin/pest tests/Feature/Migrations/CreateSecretSharesTableTest.php"
# ✓ 3/3 passing

# Model tests
ddev exec "vendor/bin/pest tests/Feature/Models/SecretShareTest.php"
# ✓ 10/10 passing

# Full test suite
ddev exec "vendor/bin/pest --no-coverage"
# ✓ 355/355 passing

Next Steps (Separate PRs)

This PR provides the foundation. Follow-up PRs will add:

1. SecretController - CRUD with permission checks
2. SecretShareController - Grant/revoke endpoints
3. Policies - SecretPolicy, SecretSharePolicy
4. Form Requests - Validation with XOR logic
5. Integration Tests - End-to-end scenarios

Checklist

• Conventional commit message
• CHANGELOG.md updated
• Tests written and passing (13 new tests)
• PHPStan passing (level 9)
• Laravel Pint passing
• Migration reversible
• REUSE compliance
• Domain policy check

Related

• Closes: Part of Phase 3: Secret Sharing & Access Control (RBAC Integration) #182 (Phase 3: Secret Sharing & Access Control)
• Epic: [EPIC] Secret Management System (Password Vault) #173 (Secret Management)
• Depends on: Phase 2: File Attachments API (Upload/Download/Encryption) #175 (File Attachments - merged)

[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! 😊

[codecov]

Codecov Report

❌ Patch coverage is 47.50000% with 21 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
app/Models/Secret.php	8.69%	21 Missing ⚠️

📢 Thoughts on this report? Let us know!

[Copilot]

Pull Request Overview

This PR establishes the database foundation for Phase 3: Secret Sharing & Access Control by introducing a secret_shares table, model, and relationships. The implementation enables fine-grained permission management where secrets can be shared with individual users or roles with read/write/admin permissions and optional expiration.

Key Changes:

• Database schema with XOR constraint ensuring shares target either a user OR a role
• SecretShare model with UUID keys, temporal filtering, and relationship definitions
• Secret model extensions adding share relationship and permission checking logic

Reviewed Changes

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

Show a summary per file

File	Description
database/migrations/2025_11_16_164313_create_secret_shares_table.php	Creates secret_shares table with UUID keys, XOR constraint, permission enum, and comprehensive indexes
app/Models/SecretShare.php	Defines SecretShare model with relationships, active scope for non-expired shares, and expiration accessor
app/Models/Secret.php	Adds shares() relationship and userHasPermission() method for authorization checks with permission hierarchy
tests/Feature/Migrations/CreateSecretSharesTableTest.php	Migration tests validating schema structure, indexes, and unique constraints
tests/Feature/Models/SecretShareTest.php	Model tests covering relationships, UUID keys, scopes, and expiration logic
CHANGELOG.md	Documents new secret sharing foundation features