TenantAtlas/specs/104-provider-permission-posture/data-model.md

Data Model: Provider Permission Posture (Spec 104)

Date: 2026-02-21 | Branch: 104-provider-permission-posture

New Table: stored_reports

Column	Type	Nullable	Default	Notes
id	bigint (PK)	NO	auto
workspace_id	bigint (FK → workspaces)	NO	—	SCOPE-001: tenant-owned table
tenant_id	bigint (FK → tenants)	NO	—	SCOPE-001: tenant-owned table
report_type	string	NO	—	Polymorphic type discriminator (e.g., permission_posture)
payload	jsonb	NO	—	Full report data, structure depends on report_type
created_at	timestampTz	NO	—
updated_at	timestampTz	NO	—

Indexes:

• [workspace_id, tenant_id, report_type] — composite for filtered queries
• [tenant_id, created_at] — for temporal ordering per tenant
• GIN on payload — for future JSONB querying (e.g., filter by posture_score)

Relationships:

• workspace() → BelongsTo Workspace
• tenant() → BelongsTo Tenant

Traits: DerivesWorkspaceIdFromTenant, HasFactory

---

Modified Table: findings (migration)

Column	Type	Nullable	Default	Notes
resolved_at	timestampTz	YES	null	When the finding was resolved
resolved_reason	string(255)	YES	null	Why resolved (e.g., permission_granted, registry_removed)

No new indexes — queries filter by status (already indexed as [tenant_id, status]).

---

Modified Model: Finding

New Constants

const FINDING_TYPE_PERMISSION_POSTURE = 'permission_posture';
const STATUS_RESOLVED = 'resolved';

New Casts

'resolved_at' => 'datetime',

New Method

/**
 * Auto-resolve the finding.
 */
public function resolve(string $reason): void
{
    $this->status = self::STATUS_RESOLVED;
    $this->resolved_at = now();
    $this->resolved_reason = $reason;
    $this->save();
}

/**
 * Re-open a resolved finding.
 */
public function reopen(array $evidence): void
{
    $this->status = self::STATUS_NEW;
    $this->resolved_at = null;
    $this->resolved_reason = null;
    $this->evidence_jsonb = $evidence;
    $this->save();
}

---

Modified Model: AlertRule

New Constant

const EVENT_PERMISSION_MISSING = 'permission_missing';

No schema change — event_type is already a string column.

---

Modified Model: OperationCatalog

New Constant

const TYPE_PERMISSION_POSTURE_CHECK = 'permission_posture_check';

---

New Model: StoredReport

class StoredReport extends Model
{
    use DerivesWorkspaceIdFromTenant;
    use HasFactory;

    const REPORT_TYPE_PERMISSION_POSTURE = 'permission_posture';

    protected $fillable = [
        'workspace_id',
        'tenant_id',
        'report_type',
        'payload',
    ];

    protected function casts(): array
    {
        return [
            'payload' => 'array',
        ];
    }

    public function workspace(): BelongsTo { ... }
    public function tenant(): BelongsTo { ... }
}

---

New Factory: StoredReportFactory

// Default state
[
    'workspace_id' => via DerivesWorkspaceIdFromTenant,
    'tenant_id'    => Tenant::factory(),
    'report_type'  => StoredReport::REPORT_TYPE_PERMISSION_POSTURE,
    'payload'      => [...default posture payload...],
]

---

Posture Report Payload Schema (report_type=permission_posture)

{
    "posture_score": 86,
    "required_count": 14,
    "granted_count": 12,
    "checked_at": "2026-02-21T14:30:00Z",
    "permissions": [
        {
            "key": "DeviceManagementConfiguration.ReadWrite.All",
            "type": "application",
            "status": "granted",
            "features": ["policy-sync", "backup", "restore"]
        },
        {
            "key": "DeviceManagementApps.ReadWrite.All",
            "type": "application",
            "status": "missing",
            "features": ["policy-sync", "backup"]
        }
    ]
}

---

Finding Evidence Schema (finding_type=permission_posture)

{
    "permission_key": "DeviceManagementApps.ReadWrite.All",
    "permission_type": "application",
    "expected_status": "granted",
    "actual_status": "missing",
    "blocked_features": ["policy-sync", "backup"],
    "checked_at": "2026-02-21T14:30:00Z"
}

---

Fingerprint Formula

sha256("permission_posture:{tenant_id}:{permission_key}")

Truncated to 64 chars (matching fingerprint column size).

---

State Machine: Finding Lifecycle (permission_posture)

              permission missing
                    ↓
    ┌────────── [new] ──────────┐
    │              │             │
    │         user acks         │ permission granted
    │              ↓             ↓
    │        [acknowledged] → [resolved]
    │                            │
    │                            │ permission revoked again
    │                            ↓
    └─────────── [new] ←────────┘
                (re-opened)

• new → acknowledged: Manual user action (existing acknowledge() method)
• new → resolved: Auto-resolve when permission is granted
• acknowledged → resolved: Auto-resolve when permission is granted (acknowledgement metadata preserved)
• resolved → new: Re-open when permission becomes missing again (cleared resolved fields)

---

Entity Relationship Summary

Workspace ──┬── StoredReport (new, 1:N)
             │     └── Tenant (FK)
             │
             ├── AlertRule (existing, extended with EVENT_PERMISSION_MISSING)
             │     └── AlertDestination (M:N pivot)
             │
             └── Tenant ──┬── Finding (existing, extended)
                           │     ├── finding_type: permission_posture (new)
                           │     ├── source: permission_check (new usage)
                           │     └── status: resolved (new global status)
                           │
                           ├── TenantPermission (existing, read-only input)
                           │
                           └── OperationRun (existing, type: permission_posture_check)