opencode-workflow/skills/security-boundary-design/SKILL.md

name	description
security-boundary-design	Knowledge contract for security boundary design. Provides principles and patterns for authentication, authorization, service identity, token propagation, tenant isolation, secret management, and audit logging. Referenced by design-architecture when defining security boundaries.

This is a knowledge contract, not a workflow skill. It provides theoretical guidance that the Architect references when designing security boundaries. It does not produce artifacts directly.

Core Principles

Defense in Depth

• Never rely on a single security boundary
• Apply security at every layer: network, service, data, application
• Assume breach: design so that compromise of one layer doesn't compromise all

Least Privilege

• Services and users should have the minimum permissions required
• Default deny: start with no access, grant explicitly
• Rotate and expire credentials regularly

Zero Trust

• Don't trust internal network traffic by default
• Authenticate and authorize every service-to-service call
• Encrypt data in transit, even within the internal network

Authentication

Patterns

• Token-based authentication: JWT, OAuth2 tokens
• API key authentication: For service-to-service and public APIs
• Certificate-based authentication: mTLS for internal service communication
• Session-based authentication: For web applications with stateful sessions

Design Considerations

• Define where authentication happens (edge gateway, service level, or both)
• Define token format, issuer, audience, and expiration
• Define token refresh and revocation strategy
• Define credential rotation strategy
• Consider token size impact on request headers

Authorization

Patterns

• RBAC (Role-Based Access Control): Assign permissions to roles, assign roles to users
• ABAC (Attribute-Based Access Control): Assign permissions based on attributes (user, resource, environment)
• ACL (Access Control List): Explicit list of who can access what
• ReBAC (Relationship-Based Access Control): Permissions based on relationships between entities

Design Considerations

• Choose the simplest model that meets PRD requirements
• Define permission granularity: coarse-grained (role-level) vs fine-grained (resource-level)
• Define where authorization is enforced (gateway, service, or both)
• Define how permissions are stored and cached
• Consider multi-tenant authorization: can users in one tenant access resources in another?

Service Identity

Patterns

• Service accounts: Each service has its own identity with specific permissions
• Workload identity: Identity tied to the deployment (Kubernetes service accounts, cloud IAM roles)
• Service mesh identity: Identity managed by the service mesh (Istio, Linkerd)

Design Considerations

• Each service should have its own identity (no shared credentials)
• Service identity should be short-lived and automatically rotated
• Service identity should be bound to the deployment environment
• Service identity permissions should follow least privilege

Token Propagation

Patterns

• Pass-through: Gateway validates token, passes it to downstream services
• Token exchange: Gateway validates external token, issues internal token
• Token relay: Each service forwards the token to downstream services
• Impersonation: Service calls downstream on behalf of the user

Design Considerations

• Define token format for internal vs external communication
• Define token lifecycle: creation, validation, refresh, revocation
• Consider token size when propagating through multiple hops
• Consider what context to propagate (user identity, tenant, permissions, correlation ID)

Tenant Isolation

Patterns

• Database-level isolation: Separate database per tenant
• Schema-level isolation: Separate schema per tenant, shared database
• Row-level isolation: Shared schema, tenant_id column with enforcement
• Application-level isolation: Shared infrastructure, application enforces isolation

Design Considerations

• Choose isolation level based on PRD requirements (compliance, performance, cost)
• Row-level isolation is simplest but requires careful query filtering
• Database-level isolation provides strongest isolation but highest cost
• Define how tenant context is resolved (subdomain, header, token claim)
• Define how tenant isolation is enforced (middleware, query filter, database policy)

Secret Management

Patterns

• Environment variables: Simple, but don't support rotation well
• Secret management service: HashiCorp Vault, AWS Secrets Manager, GCP Secret Manager
• Platform-native secrets: Kubernetes Secrets, cloud IAM role-based access
• Configuration service: Centralized configuration with encryption at rest

Design Considerations

• Secrets must never be stored in code, configuration files in version control, or logs
• Define secret rotation strategy for each type of secret
• Define how services access secrets (sidecar, SDK, environment injection)
• Define audit trail for secret access
• Consider secret hierarchies (global, per-environment, per-service)

Audit Logging

Design Considerations

• Log all authentication and authorization events (success and failure)
• Log all data modification operations (who, what, when, from where)
• Log all administrative actions
• Define log retention period based on compliance requirements
• Define log format: structured JSON with consistent fields
• Log must be tamper-evident or append-only for compliance

Anti-Patterns

• Shared credentials across services: Each service must have its own identity
• Hard-coded secrets: Secrets must be externalized and rotated
• Overly broad permissions: Grant least privilege, not convenience privilege
• Missing authentication for internal services: Internal traffic must also be authenticated
• Missing audit logging for sensitive operations: All auth events and data modifications must be logged
• Trust based on network location: Don't assume internal network is safe