Operations, Administration, and Maintenance requirements for the Item Image
Upload feature, organized following the FCAPS model (Fault, Configuration,
Accounting, Performance, Security Management).
| ID | Requirement | Actor | Source |
|---|
| OAM-F-001 | S3 upload failures (network errors, permission errors, presigned credential expiry) shall be surfaced to the user as plain-language retry-able errors. The SPA shall allow retry without re-entering the image. | SPA | NFR-010, FR-013 |
| OAM-F-002 | CloudFront origin errors (S3 unavailable) shall result in grid thumbnails falling back to placeholder + error badge. No system-wide error banner. | SPA | FR-030 |
| OAM-F-003 | Backend presigned credential generation failures shall return structured error responses (HTTP 500 with error code) enabling the BFF to return meaningful errors to the SPA. | Backend | BE-FR-001 |
| OAM-F-004 | Incomplete multipart uploads shall be automatically aborted by S3 lifecycle rule after 1 day. No operator intervention required. | AWS | NFR-011 |
| OAM-F-005 | The BFF reachability/fetch endpoint shall time out external requests within 10 seconds. Timeout responses shall be distinguishable from unreachable responses in the response payload. | BFF | BFF-NFR-002 |
| OAM-F-006 | S3 bucket versioning shall be enabled. If an object is accidentally overwritten (key collision — theoretically impossible with UUID keys), the previous version is recoverable. | AWS | AWS-FR-006 |
| ID | Requirement | Actor | Source |
|---|
| OAM-C-001 | Image field parameters (accepted formats, max file size, aspect ratio, max dimension for compression) shall be configurable per entity type via ImageFieldConfig. Changes require code deployment (design-time parameters). | SPA | FR-008, FR-009, FR-014, SD-06 |
| OAM-C-002 | Presigned POST credential expiry (default 15 minutes, aligned with existing uploadSignatureDuration) shall be configurable via Backend environment variable. | Backend | NFR-006 |
| OAM-C-003 | CDN domain name shall be injected into the Backend via environment variable (from CDK cross-stack export). The Backend shall not hardcode the CDN host. | Backend, AWS | BE-FR-007, AWS cross-stack exports |
| OAM-C-004 | BFF reachability endpoint rate limit (default 30 req/min/tenant) shall be configurable via environment variable. | BFF | BFF-FR-006 |
| OAM-C-005 | S3 bucket name and presigning role ARN shall be injected into the Backend via CloudFormation imports (existing pattern from CSV upload). | Backend, AWS | Existing architecture |
| OAM-C-006 | CORS configuration on the S3 bucket shall whitelist the application’s origin URLs for PUT/POST methods (same pattern as existing upload bucket). | AWS | Existing architecture |
| ID | Requirement | Actor | Source |
|---|
| OAM-A-001 | Every uploaded image object shall carry S3 metadata: x-amz-meta-tenant-id, x-amz-meta-author, x-amz-meta-arda-key. This provides an audit trail independent of entity persistence. | AWS, Backend | AWS specification, S3 Object Metadata |
| OAM-A-002 | Image URL changes (set, replace, remove) shall be tracked in the entity’s bitemporal version history. The history records who changed the image, when, and what the previous value was. | Backend | FR-027, existing persistence model |
| OAM-A-003 | BFF reachability/fetch endpoint usage shall be logged with tenant ID, target URL (redacted to host-only for privacy), and outcome. Logs support abuse detection and debugging. | BFF | BFF-FR-006, BFF-FR-007 |
| OAM-A-004 | S3 access logs or CloudTrail data trail shall be enabled on the image assets bucket for compliance and forensic analysis. | AWS | Operational best practice |
| ID | Requirement | Actor | Source |
|---|
| OAM-P-001 | CloudFront cache hit ratio for image assets shall be monitored. Target: >90% cache hit ratio after initial warm-up. Low hit ratio indicates CDN misconfiguration or excessive invalidation. | AWS | NFR-002, NFR-014 |
| OAM-P-002 | Presigned POST credential generation latency shall be monitored (Backend-side). Alert if P95 exceeds 2 seconds (2x the target). | Backend | NFR-003 |
| OAM-P-003 | S3 upload success/failure rates shall be observable via S3 request metrics or application-level logging. | AWS, SPA | NFR-010 |
| OAM-P-004 | Grid thumbnail load time shall be observable via browser performance metrics (Resource Timing API). No server-side instrumentation needed — CDN delivery is measured at the edge. | SPA | NFR-002, NFR-004 |
| OAM-P-005 | S3 storage consumption per tenant shall be monitorable via S3 Storage Lens or periodic inventory. Alert thresholds should be defined for operational awareness (not blocking — storage cost is negligible at projected volumes). | AWS | NFR-013 |
| ID | Requirement | Actor | Source |
|---|
| OAM-S-001 | The S3 bucket shall block all public access. Only CloudFront (via OAC) and the Backend presigning role shall have read/write access. | AWS | AWS-FR-007, DQ-1 |
| OAM-S-002 | Presigned POST credentials shall be scoped to a specific S3 key prefix containing the tenant ID. A presigned form generated for Tenant A cannot be used to upload to Tenant B’s key space. | Backend, AWS | NFR-006, NFR-007, TD-03 |
| OAM-S-003 | The Backend shall validate all persisted image URLs against the CDN host pattern. No external URLs, data URIs, or non-CDN URLs shall be persisted. | Backend | NFR-005, TD-05, FR-012 |
| OAM-S-004 | The BFF reachability/fetch endpoint shall implement SSRF protection: reject private IP ranges, localhost, non-HTTPS schemes, and managed storage URLs. | BFF | BFF-FR-007, NFR-009 |
| OAM-S-005 | S3 server-side encryption (SSE-S3) shall be enabled. All objects encrypted at rest. | AWS | AWS-FR-006 |
| OAM-S-006 | CloudFront shall serve content over HTTPS only. HTTP requests shall be redirected to HTTPS. | AWS | AWS specification |
| OAM-S-007 | The presigning IAM role shall follow least-privilege: only s3:PutObject on the image assets bucket. No delete, no list, no read permissions. | AWS | AWS specification |
| OAM-S-008 | Content-Type enforcement via presigned POST policy conditions shall prevent uploading non-image content (e.g., HTML, JavaScript) that could be served from the CDN. This mitigates stored XSS risk. | AWS, Backend | FR-024, TD-08 |
| OAM-S-009 | CloudFront shall set Content-Disposition: inline and X-Content-Type-Options: nosniff response headers to prevent MIME-type sniffing attacks. | AWS | Security best practice |
| OAM-S-010 | Copyright acknowledgment is SPA-only (TD-04). If backend-side logging of acknowledgments is required in the future, it shall be a separate enhancement. The current design does not log acknowledgments. | SPA | FR-019, TD-04 |
| OAM-S-011 | CloudFront signed cookies shall be required for all image requests. Unauthenticated CDN requests shall receive 403. Cookies are scoped to the active tenant’s key prefix — Tenant A’s cookie does not grant access to Tenant B’s images. | AWS, BFF | NFR-017, NFR-018, TD-11 |
| OAM-S-012 | The CloudFront signing key pair shall be rotatable without downtime. Procedure: (1) generate new key pair, (2) add new public key to the trusted key group (both keys active), (3) update BFF to sign with new private key, (4) wait for old cookies to expire (max 30 min), (5) remove old public key from trusted key group. | AWS, BFF | NFR-020, TD-11 |
| OAM-S-013 | The CloudFront signing private key shall be stored in AWS Secrets Manager (or equivalent sealed secret). It shall not be committed to source control, logged, or exposed in error messages. | BFF, AWS | BFF-NFR-004, TD-11 |
| OAM-S-014 | Signed cookie TTL shall be configurable (default 30 minutes). Shorter TTLs reduce the breach window from cookie exfiltration. The TTL must balance security (shorter is better) against BFF load (more frequent renewals). | BFF | NFR-019, TD-12 |
| OAM-S-015 | The BFF cdn-cookies endpoint shall extract the tenant ID from the authenticated session context. It shall never accept a tenant ID as a client-supplied parameter, preventing a compromised SPA from requesting cookies for another tenant. | BFF | FR-039, TD-11 |
Copyright: (c) Arda Systems 2025-2026, All rights reserved