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

{
  "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

{
  "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:

{
  "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 creation
• Verification Policy Contract - Attestation policies