git.stella-ops.org/docs/contracts/authority-effective-write.md

# Authority Effective Write Contract

**Contract ID:** `CONTRACT-AUTHORITY-EFFECTIVE-WRITE-008`
**Version:** 1.0
**Status:** Published
**Last Updated:** 2025-12-05

## Overview

This contract defines the `effective:write` scope and associated APIs for managing effective policies and scope attachments in the Authority module. It enables attaching policies to subjects with priority and expiration rules.

## Implementation References

- **Authority Module:** `src/Authority/`
- **API Spec:** `src/Api/StellaOps.Api.OpenApi/authority/openapi.yaml`

## Scope Definition

### effective:write

Grants permission to:
- Create and update effective policies
- Attach scopes to policies
- Manage policy priorities and expiration

## Data Models

### EffectivePolicy

```json
{
  "effective_policy_id": "eff-001",
  "tenant_id": "default",
  "policy_id": "policy-001",
  "policy_version": "1.0.0",
  "subject_pattern": "pkg:npm/*",
  "priority": 100,
  "enabled": true,
  "expires_at": "2025-12-31T23:59:59Z",
  "scopes": ["scan:read", "scan:write"],
  "created_at": "2025-12-05T10:00:00Z",
  "created_by": "admin@example.com",
  "updated_at": "2025-12-05T10:00:00Z"
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `effective_policy_id` | string | Auto | Unique identifier |
| `tenant_id` | string | Yes | Tenant scope |
| `policy_id` | string | Yes | Referenced policy |
| `policy_version` | string | No | Specific version (latest if omitted) |
| `subject_pattern` | string | Yes | Subject matching pattern |
| `priority` | integer | Yes | Priority (higher = more important) |
| `enabled` | boolean | No | Whether policy is active (default: true) |
| `expires_at` | datetime | No | Optional expiration time |
| `scopes` | array | No | Attached authorization scopes |

### ScopeAttachment

```json
{
  "attachment_id": "att-001",
  "effective_policy_id": "eff-001",
  "scope": "scan:write",
  "conditions": {
    "repository_pattern": "github.com/org/*"
  },
  "created_at": "2025-12-05T10:00:00Z"
}
```

### Subject Patterns

Subject patterns use glob-style matching:

| Pattern | Matches |
|---------|---------|
| `*` | All subjects |
| `pkg:npm/*` | All npm packages |
| `pkg:npm/@org/*` | Npm packages in @org scope |
| `pkg:maven/com.example/*` | Maven packages in com.example |
| `oci://registry.example.com/*` | All images in registry |

## API Endpoints

### Effective Policies

#### Create Effective Policy

```
POST /api/v1/authority/effective-policies
Content-Type: application/json
Authorization: Bearer <token with effective:write scope>

{
  "tenant_id": "default",
  "policy_id": "security-policy-v1",
  "subject_pattern": "pkg:npm/*",
  "priority": 100,
  "scopes": ["scan:read", "scan:write"]
}

Response: 201 Created
{
  "effective_policy_id": "eff-001",
  "tenant_id": "default",
  "policy_id": "security-policy-v1",
  "subject_pattern": "pkg:npm/*",
  "priority": 100,
  "enabled": true,
  "scopes": ["scan:read", "scan:write"],
  "created_at": "2025-12-05T10:00:00Z"
}
```

#### Update Effective Policy

```
PUT /api/v1/authority/effective-policies/{effective_policy_id}
Content-Type: application/json
Authorization: Bearer <token with effective:write scope>

{
  "priority": 150,
  "expires_at": "2025-12-31T23:59:59Z"
}

Response: 200 OK
```

#### Delete Effective Policy

```
DELETE /api/v1/authority/effective-policies/{effective_policy_id}
Authorization: Bearer <token with effective:write scope>

Response: 204 No Content
```

#### List Effective Policies

```
GET /api/v1/authority/effective-policies?tenant_id=default

Response: 200 OK
{
  "items": [
    {
      "effective_policy_id": "eff-001",
      "policy_id": "security-policy-v1",
      "subject_pattern": "pkg:npm/*",
      "priority": 100
    }
  ],
  "total": 1
}
```

### Scope Attachments

#### Attach Scope

```
POST /api/v1/authority/scope-attachments
Content-Type: application/json
Authorization: Bearer <token with effective:write scope>

{
  "effective_policy_id": "eff-001",
  "scope": "promotion:approve",
  "conditions": {
    "environment": "production"
  }
}

Response: 201 Created
{
  "attachment_id": "att-001",
  "effective_policy_id": "eff-001",
  "scope": "promotion:approve",
  "conditions": {...}
}
```

#### Detach Scope

```
DELETE /api/v1/authority/scope-attachments/{attachment_id}
Authorization: Bearer <token with effective:write scope>

Response: 204 No Content
```

### Policy Resolution

#### Resolve Effective Policy for Subject

```
GET /api/v1/authority/resolve?subject=pkg:npm/lodash@4.17.20

Response: 200 OK
{
  "subject": "pkg:npm/lodash@4.17.20",
  "effective_policy": {
    "effective_policy_id": "eff-001",
    "policy_id": "security-policy-v1",
    "policy_version": "1.0.0",
    "priority": 100
  },
  "granted_scopes": ["scan:read", "scan:write"],
  "matched_pattern": "pkg:npm/*"
}
```

## Priority Resolution

When multiple effective policies match a subject:

1. Higher `priority` value wins
2. If equal priority, more specific pattern wins
3. If equal specificity, most recently updated wins

Example:
```
Pattern: pkg:npm/*         Priority: 100  → Matches
Pattern: pkg:npm/@org/*    Priority: 50   → Matches (more specific)
Pattern: pkg:*             Priority: 200  → Matches

Winner: pkg:npm/@org/* (most specific among matches)
```

## Audit Trail

All effective:write operations are logged:

```json
{
  "event": "effective_policy.created",
  "effective_policy_id": "eff-001",
  "actor": "admin@example.com",
  "timestamp": "2025-12-05T10:00:00Z",
  "changes": {
    "policy_id": "security-policy-v1",
    "subject_pattern": "pkg:npm/*"
  }
}
```

## Error Codes

| Code | Message |
|------|---------|
| `ERR_AUTH_001` | Invalid subject pattern |
| `ERR_AUTH_002` | Policy not found |
| `ERR_AUTH_003` | Duplicate attachment |
| `ERR_AUTH_004` | Invalid scope |
| `ERR_AUTH_005` | Priority conflict |

## Unblocks

This contract unblocks the following tasks:

- POLICY-AOC-19-002
- POLICY-AOC-19-003
- POLICY-AOC-19-004

## Related Contracts

- [Policy Studio Contract](./policy-studio.md) - Policy creation
- [Verification Policy Contract](./verification-policy.md) - Attestation policies