4. System Components

RFC-SECOPS-0002                                                   Section 4
Category: Standards Track                              System Components

4.1 Component Taxonomy

The interim architecture consists of four components:

Component	Type	Location
AWS Secrets Manager	Managed Service	AWS Cloud
AWS IAM	Managed Service	AWS Cloud
Secret Config Module	Application Library	Per-application codebase
Secrets Inventory Manifest	Configuration File	Git repository
AWS SDK	Library Dependency	Per-application runtime

4.2 Component Responsibilities

4.2.1 AWS Secrets Manager

Aspect	Description
Responsibility	Stores and serves secret values; encrypts at rest using AWS KMS-managed keys
Inputs	Secret name and value (via CreateSecret/PutSecretValue); secret name (via GetSecretValue)
Outputs	Secret value (plaintext, decrypted in transit via TLS)
Dependencies	AWS IAM (authorization)
Failure Mode	Service unavailability returns API errors; secrets are inaccessible
Recovery	Automatic on AWS service restoration; no operator action required

AWS Secrets Manager is the sole authoritative store for all platform secret values during the interim period (Invariant 1).

4.2.2 AWS IAM

Aspect	Description
Responsibility	Authenticates on-premises servers and authorizes access to specific secrets
Inputs	IAM user credentials (access key ID + secret access key) or IAM role assumption
Outputs	Authorization decisions (allow/deny) for Secrets Manager API calls
Dependencies	IAM policy and Secrets Manager resource policy definitions
Failure Mode	Authentication failure prevents all secret access for the affected principal
Recovery	Verify credentials, check IAM policy attachments, rotate if compromised

Security principals MUST be scoped per-application. Each application MUST have its own IAM principal, and access SHOULD be granted using IAM policies scoped to per-application secret name prefixes.

Access Control Model:

AWS Secrets Manager supports two authorization mechanisms. Identity-based IAM policies are RECOMMENDED; resource-based policies are noted for reference.

Mechanism	Scope Granularity	Recommended
Identity-based IAM policies	User/role/group; can scope to secret ARN patterns	YES
Secrets Manager resource policies	Per-secret policy; supports cross-account access	Conditional

IAM Scoping for Least Privilege:

IAM policies are assigned using ARNs, not data-plane URLs. The minimum recommended scope for per-application isolation is a secret name prefix:

arn:aws:secretsmanager:{region}:{account-id}:secret:platform-data/*

The RECOMMENDED permission set for application principals includes secretsmanager:GetSecretValue (read secret contents, no management permissions).

Important: AWS IAM supports wildcard ARN matching for secret name prefixes within a single account. The platform-data/ and platform-config/ naming convention provides logical grouping and enables prefix-scoped access within a shared account.

4.2.3 Secret Config Module

Aspect	Description
Responsibility	Provides a centralized interface for application code to retrieve secrets
Inputs	Secret name (using platform naming convention)
Outputs	Secret value (string or structured data)
Dependencies	AWS SDK, IAM credentials available in the runtime environment
Failure Mode	Propagates SDK errors to the calling application; fails loudly on missing secrets
Recovery	Application-specific (retry, fail startup, degrade gracefully)

The Secret Config Module is the only component in each application that directly calls the AWS SDK for secret retrieval (Invariant 4).

Design constraints for this module:

Constraint	Rationale
Single module per application	Limits migration blast radius
Abstracts AWS SDK behind an interface	Enables replacement with Vault/ESO client during migration
Fails loudly on missing secrets	Prevents silent misconfiguration
Caches secrets in memory after retrieval	Reduces API calls and latency
Does not persist secrets to disk	Prevents local secret accumulation

4.2.4 Secrets Inventory Manifest

Aspect	Description
Responsibility	Documents all secrets stored in AWS Secrets Manager (metadata only)
Inputs	Operator updates when secrets are created, modified, or deleted
Outputs	A machine-readable and human-readable inventory of platform secrets
Dependencies	Git repository access
Failure Mode	Drift from actual Secrets Manager state (inventory says secret exists but it does not, or vice versa)
Recovery	Periodic reconciliation by operators

The manifest follows this structure:

secrets:
  - name: platform-data/postgres/my-app
    description: PostgreSQL credentials for my-app
    consumers:
      - my-app
    rotation: manual
    created: 2026-02-17
    notes: "Primary database credentials"

  - name: platform-config/redis/shared
    description: Redis connection parameters
    consumers:
      - my-app
      - other-service
    rotation: none
    created: 2026-02-17
    notes: "Non-sensitive connection configuration"

The manifest MUST NOT contain secret values (Invariant 3).

4.2.5 AWS SDK

Aspect	Description
Responsibility	Provides the programmatic interface to AWS Secrets Manager
Inputs	API calls from the Secret Config Module
Outputs	Secret values retrieved from AWS Secrets Manager
Dependencies	IAM credentials in the runtime environment, network access to AWS endpoints
Failure Mode	Network errors, authentication failures, throttling
Recovery	Built-in retry logic (exponential backoff); application-level error handling

The AWS SDK is a transitive dependency consumed only through the Secret Config Module. Application code MUST NOT import or call the AWS SDK directly for secret retrieval.

4.3 Component Interaction Model

Interaction	Protocol	Direction
Application → Secret Config Module	In-process function call	Synchronous
Secret Config Module → AWS SDK	In-process function call	Synchronous
AWS SDK → AWS IAM	HTTPS/TLS	Request-response
AWS IAM → AWS Secrets Manager	Internal AWS	Request-response
Operator → secrets-inventory.yaml	Git commit	Asynchronous (manual)

4.4 Failure and Recovery Scenarios

4.4.1 Application Cannot Retrieve Secret at Startup

Aspect	Description
Cause	Network failure, IAM misconfiguration, secret does not exist
Symptom	Application fails to start; Secret Config Module reports error
Resolution	Verify network connectivity to AWS, check IAM credentials and policy attachments, verify secret exists in Secrets Manager
Prevention	Pre-deployment validation against secrets-inventory.yaml

4.4.2 IAM Credentials Expired or Rotated

Aspect	Description
Cause	IAM access key rotated without updating server configuration
Symptom	All secret retrievals fail with authentication errors
Resolution	Update IAM credentials on the affected server(s)
Prevention	Document credential locations and rotation procedures

4.4.3 Secret Deleted From Secrets Manager But Still in Inventory

Aspect	Description
Cause	Operator deleted secret from Secrets Manager without updating manifest
Symptom	Applications fail to retrieve the secret; inventory shows it as existing
Resolution	Either recreate the secret in Secrets Manager or remove from inventory
Prevention	Operational discipline; periodic reconciliation

4.4.4 Secret Exists in Secrets Manager But Not in Inventory

Aspect	Description
Cause	Operator created secret in Secrets Manager without updating manifest
Symptom	No immediate application impact; reduced operational visibility
Resolution	Add the secret to secrets-inventory.yaml
Prevention	Operational discipline; periodic reconciliation

4. System Components

On this page