Issue #198 — Implementation Plan

Public Portal + Archives-led UX + Hard Multi-Tenancy + Governance/Hardening

The Archive and Heritage Group (Pty) Ltd Date: 2026-02-28 Framework: v2.8.2 | Plugins: 79 Tracking Issue: ArchiveHeritageGroup/atom-extensions-catalog#198 Related Issues: #185 (Security DevOps), #197 (Security Hardening)

Executive Summary

This plan addresses issue #198's five EPICs through a phased delivery over 6 milestones. Codebase analysis reveals the system is 60-70% ready — substantial infrastructure exists for multi-tenancy (ahgMultiTenantPlugin v1.2.0), search (ahgDiscoveryPlugin + ahgSemanticSearchPlugin), rights enforcement (3-layer model), and research workflows (ahgResearchPlugin v3.0.0 with 87 tables). The primary gaps are hard isolation (uploads/search/cache/audit lack tenant_id), search explainability UI, bulk edit operations, and security hardening (unsafe unserialize(), missing upload MIME validation).

Current State Summary

What Already Exists (Strength Map)

What's Missing (Gap Map)

Milestone Plan

M0: Immediate Security Fixes (Week 1)

Priority: CRITICAL — Do before any feature work Scope: Issues #197 partial, #185 partial

These are zero-feature-debt items that reduce risk immediately.

M0.1: Serialization Hardening (D4)

New file: Move Getty cache from /tmp/getty_cache/ to /var/cache/atom/getty/ with 0700 permissions.

M0.2: Upload Hardening (D1)

New file: atom-framework/src/Services/FileValidationService.php

• Extension allowlist (configurable via ahg_settings)
• MIME magic-bytes validation via finfo
• Max file size enforcement
• Called by all upload handlers

M0.3: API Path Traversal Fix

File: ahgAPIPlugin/modules/apiv2/actions/fileUploadAction.class.php

• Add $type = basename($request->getParameter('type')) before building upload path

Deliverable: Security fix release via ./bin/release patch "Security hardening: serialization, uploads, API path traversal"

M1: Hard Multi-Tenancy Foundation (Weeks 2-5)

Scope: EPIC C (complete) + EPIC A1 (tenant-scoped routing/branding) Plugin: ahgMultiTenantPlugin (currently disabled)

M1.1: Upload Isolation (C1)

Schema change: Add tenant_id INT NULL to digital_object table (nullable for backward compat — existing objects get NULL = "default tenant")

Data migration CLI: php symfony tenant:migrate-uploads — assigns existing digital objects to default tenant, creates tenant subdirectories, moves files

M1.2: Search Isolation (C2)

Strategy: Single index with mandatory tenant filter (simpler than per-tenant indexes; avoids reindex on tenant creation)

Reindex CLI: php symfony tenant:reindex — populates tenant_id field in ES for all existing documents

M1.3: Cache Isolation (C3)

M1.4: Audit Isolation (C4)

Schema change: Add tenant_id INT NULL + request_id VARCHAR(36) NULL to:

• ahg_audit_log
• ahg_audit_access
• ahg_audit_authentication

M1.5: Tenant-Scoped Branding (A1)

Already implemented: TenantBranding service + domain routing in ahgMultiTenantPlugin. Gap: Need to activate and test.

Verification tests:

# Cross-tenant leakage test
curl -H "Host: tenant-a.heritage.example.com" https://localhost/browse | grep -c "tenant-b-data"
# Should return 0

# Upload isolation test
# Create file as tenant A, try to access as tenant B → expect 404

# Cache isolation test
# Set cache as tenant A, read as tenant B → expect NULL

# Audit test
mysql -u root archive -e "SELECT DISTINCT tenant_id FROM ahg_audit_log WHERE tenant_id IS NOT NULL"

Deliverable: ./bin/release minor "Hard multi-tenancy: upload/search/cache/audit isolation"

M2: Public Portal VNext — Search & Browse (Weeks 6-9)

Scope: EPIC A2, A3 partial Plugins: ahgDisplayPlugin (bug fixes only — it's stable), ahgDiscoveryPlugin, ahgThemeB5Plugin overrides

M2.1: Hierarchy-Aware Search Ranking (A2)

Strategy: Boost ES scores for records whose parent fonds/series matches query terms.

Index change: Add parent_titles field to ES mapping (denormalized from MPTT hierarchy)

M2.2: Search Explainability Panel (A2)

UI: "Why this result?" expandable panel per search result showing:

• Which fields matched (title, scope_and_content, creator, etc.)
• Which synonyms/expansions contributed
• Hierarchy context boost applied

M2.3: Record View — Hierarchy Breadcrumb (A3)

Implementation: Use MPTT (lft/rgt) columns on information_object to walk the tree. Laravel QB query with ancestor_slugs for breadcrumb links.

M2.4: Record View — Restrictions Banner (A3)

Implementation: Call RightsService, ExtendedRightsService, SecurityClearanceService to build restriction summary. Display as Bootstrap 5 alert (color-coded: red=blocked, yellow=restricted, green=open).

M2.5: Provenance & Integrity Display (A3)

Implementation: Query ahg_audit_log for provenance chain + preservation_checksum for fixity data.

Deliverable: ./bin/release minor "Public portal: search explainability, hierarchy breadcrumb, restrictions banner"

M3: Description UX & Authority Workbench (Weeks 10-14)

Scope: EPIC B (complete) Plugins: ahgFormsPlugin (minor), ahgWorkflowPlugin, ahgDedupePlugin, NEW: ahgBulkEditPlugin

M3.1: Bulk Edit with Diff Preview (B2)

New plugin: ahgBulkEditPlugin

New service: BulkEditService.php

planBulkEdit(array $objectIds, array $fieldChanges, string $culture): array
    → returns [{object_id, field, old_value, new_value}] preview

executeBulkEdit(int $jobId, int $userId): void
    → async: iterates objects, applies changes via StandaloneInformationObjectWriteService
    → stores snapshots in ahg_bulk_edit_snapshot
    → logs each change to ahg_audit_log with correlation_id
    → emits workflow events

rollbackBulkEdit(int $jobId, int $userId): void
    → restores old_values from snapshots
    → logs rollback event

Integration points:

• ChangeSummaryService: reuse for diff computation
• AhgAuditService: log all changes with correlation_id
• WorkflowEventService: emit bulk_edit_started, bulk_edit_completed, bulk_edit_rolled_back

M3.2: Authority Workbench — Merge with Rollback (B3)

Extend ahgDedupePlugin:

New service: AuthorityMergeService.php (in ahgDedupePlugin)

previewMerge(int $targetId, array $sourceIds): array
    → returns field-by-field comparison: which values kept, which discarded
    → identifies linked records (events, relations) that will be re-pointed

executeMerge(int $targetId, array $sourceIds, array $fieldChoices, int $userId): int
    → takes pre-merge snapshots
    → merges chosen fields into target
    → re-points all events, relations, contact info from sources to target
    → marks sources as redirects (or deletes)
    → logs merge in ahg_authority_merge_log + ahg_audit_log

rollbackMerge(int $mergeLogId, int $userId): bool
    → restores snapshots
    → re-creates source actors
    → re-points events/relations back
    → logs rollback

M3.3: External Authority Linking (B3)

Extend ahgSemanticSearchPlugin or create new service:

New service: ExternalAuthorityService.php

searchWikidata(string $query, string $entityType): array
    → SPARQL query to wikidata.org, returns [{qid, label, description, sameAs}]

searchViaf(string $query): array
    → REST query to viaf.org, returns [{viafId, name, sources}]

searchGeoNames(string $query): array
    → REST query to api.geonames.org, returns [{geonameId, name, country, coordinates}]

linkAuthority(int $actorId, string $source, string $externalId): void
    → stores in new `ahg_authority_link` table
    → pulls enrichment data (dates, alternate names)
    → logs in audit trail

getLinkedAuthorities(int $actorId): array
    → returns all external links for actor

New table: ahg_authority_link (actor_id, source, external_id, external_label, cached_data JSON, linked_at, linked_by)

UI: Authority detail page shows "External Links" panel with search + link capability.

Deliverable: ./bin/release minor "Bulk edit with rollback, authority merge workbench, external authority linking"

M4: Digital Object Delivery & Public Requests (Weeks 15-17)

Scope: EPIC A4, A5

M4.1: Derivative Policy Engine (A4)

New table: ahg_derivative_policy (id, scope_type, scope_id, access_level, policy JSON, created_at)

• scope_type: global, repository, collection, object
• access_level: public, authenticated, researcher, admin
• Policy JSON: {thumb: true, reference: true, master: false, watermark: true, max_dimension: 1200}

New service: DerivativePolicyService.php (in atom-framework)

resolvePolicy(int $objectId, ?int $userId): array
    → cascading resolution: object → collection → repository → global
    → factors in user role + security clearance
    → returns {thumb, reference, master, watermark, max_dimension, streaming_allowed}

canAccess(int $objectId, string $derivativeType, ?int $userId): bool
    → resolvePolicy() → check if requested derivative is allowed

applyPolicy(int $objectId, string $derivativeType, ?int $userId): array
    → returns {allowed, watermark, max_dimension, reason}

Integration: IIIF manifest generation, digital object download handler, and API file endpoints all call DerivativePolicyService::canAccess() before serving.

M4.2: Unified Requester Dashboard (A5)

New module in ahgAccessRequestPlugin (or new lightweight plugin):

New file: ahgAccessRequestPlugin/modules/security/templates/requesterDashboardSuccess.php

Implementation: Aggregates across 3 request types:

1. access_request (ahgAccessRequestPlugin) — restricted material access
2. request_to_publish (ahgRequestToPublishPlugin) — publication requests
3. ahg_order (ahgCartPlugin) — reproduction orders

UI: Tabbed dashboard showing:

• All requests with status (pending/approved/denied/completed)
• Filter by type, date, status
• Click through to individual request detail

Route: /my-requests (public, authenticated users only)

M4.3: Automated Rights Gate Before Submission (A5)

Extend PublishGateService to also act as a "request gate":

New method:

evaluateRequestGate(int $objectId, string $requestType, int $userId): array
    → checks: user has researcher role, object not embargoed, object has reproduction rights, user signed terms
    → returns [{rule, status, message}]

UI: Before any request form submission, AJAX call to evaluateRequestGate(). If blockers exist, show them with instructions (e.g., "This object is under embargo until 2028-01-01").

M5: Security & Ops Hardening (Weeks 18-22)

Scope: EPIC D (remaining) + EPIC E (complete) Related issues: #185, #197

M5.1: Outbound HTTP Policy (D2)

New service: atom-framework/src/Services/HttpClientService.php

get(string $url, array $options): Response
post(string $url, array $data, array $options): Response

// Built-in protections:
// - RFC1918/link-local IP blocking (configurable allowlist)
// - Redirect limit (max 3)
// - Timeout enforcement (connect: 5s, total: 30s)
// - Request logging (tenant_id + request_id)
// - DNS resolution check before connect

Files to modify: Replace raw curl_*() and file_get_contents() in:

• ElasticsearchService (localhost exempt from IP check)
• GettySparqlService
• WebhookService (user-provided URLs get full validation)
• DOI plugin (DataCite API)
• Federation plugin (OAI-PMH endpoints)

M5.2: Shell Execution Policy (D3)

New service: atom-framework/src/Services/ProcessService.php

run(string $command, array $args, array $options): ProcessResult
    → $command must be in allowlist (python3, clamdscan, sf, tesseract, etc.)
    → all $args passed through escapeshellarg()
    → working directory constrained via realpath()
    → timeout enforcement
    → no secrets in argv (use env vars)

Files to modify: Replace any remaining shell_exec() calls with ProcessService::run().

M5.3: Health Endpoints (E2)

Health checks:

• Database connection (SELECT 1)
• Elasticsearch ping
• Upload directory writable
• PHP memory/version
• Disk space (warn if >90%)
• Queue worker running (if applicable)

Response:

{
  "status": "healthy",
  "checks": {
    "database": {"status": "up", "latency_ms": 2},
    "elasticsearch": {"status": "up", "latency_ms": 15},
    "disk": {"status": "warning", "usage_pct": 92},
    "uploads": {"status": "up", "writable": true}
  },
  "version": "2.8.2"
}

M5.4: Job Queue Improvements (E1)

Strategy: Keep existing nohup/CLI pattern but add reliability:

New table: ahg_job_queue (id, job_type, payload JSON, status, attempts, max_attempts, last_attempt_at, timeout_seconds, started_at, completed_at, error_log, created_by)

New service: JobQueueService.php

enqueue(string $jobType, array $payload, array $options): int
    → options: {max_attempts: 3, timeout: 3600, priority: 'normal'}

processNext(): bool
    → picks oldest pending job, marks in_progress, executes
    → on failure: increment attempts, schedule retry with backoff (1min, 5min, 15min)
    → on timeout: mark failed, allow retry

getStatus(int $jobId): array
heartbeat(int $jobId): void  // worker calls every 30s
detectStale(int $timeoutMinutes): array  // find jobs without heartbeat

CLI: php symfony queue:worker --daemon — persistent worker process

Systemd unit file: /etc/systemd/system/atom-worker.service

M5.5: Backup Automation (E3)

Cron configuration:

# Daily DB backup at 2 AM
0 2 * * * cd /usr/share/nginx/archive && php symfony backup:create --preset=db --quiet

# Weekly full backup at 3 AM Sunday
0 3 * * 0 cd /usr/share/nginx/archive && php symfony backup:create --preset=full --quiet

# Daily cleanup (keep 30 days)
0 4 * * * cd /usr/share/nginx/archive && php symfony backup:cleanup --older-than=30d --quiet

M5.6: Audit Log Retention & Tamper Detection (E-cross)

New table: ahg_audit_archive — cold storage for audit records older than 1 year

New CLI: php symfony audit:verify-integrity — verify HMAC chain is unbroken

Deliverable: ./bin/release minor "Security hardening: HTTP policy, health endpoints, job queue, backup automation"

M6: Documentation & Governance (Weeks 23-24)

Scope: Issue #197 documentation deliverables

New documentation files (in atom-extensions-catalog/docs/):

Feature overview documents (per plugin docs/):

• ahgMultiTenantPlugin/docs/AtoM_Heratio_Multi_Tenancy_Feature_Overview.md + .docx
• ahgBulkEditPlugin/docs/AtoM_Heratio_Bulk_Edit_Feature_Overview.md + .docx

File Summary

Dependency Graph

M0 (Security Fixes)
 └─→ M1 (Multi-Tenancy)
      ├─→ M2 (Search & Browse)
      │    └─→ M4 (Digital Delivery & Requests)
      └─→ M3 (Description UX)
                └─→ M4
                     └─→ M5 (Ops Hardening)
                          └─→ M6 (Documentation)

M0 is a prerequisite for everything (security baseline). M1 must complete before M2 (search needs tenant isolation). M2 and M3 can run in parallel after M1. M4 depends on both M2 (UI patterns) and M3 (form patterns). M5 can start during M3/M4 (independent ops work). M6 is the final wrap-up.

Risk Register

Issues to Close After Completion

Duplicate Issues to Close Now

Verification Plan

M0 Verification

# Serialization: grep for unserialize without allowed_classes
grep -rn "unserialize(" atom-ahg-plugins/ --include="*.php" | grep -v "allowed_classes"
# Should return 0 results

# Upload MIME: test with crafted file
echo "#!/bin/bash" > /tmp/test.jpg
curl -X POST -F "file=@/tmp/test.jpg" /api/v2/file-upload -H "Authorization: Bearer <key>"
# Should return 400 Bad Request (MIME mismatch)

M1 Verification

# Upload isolation
ls /mnt/nas/heratio/archive/r/ | head -5  # Should show tenant subdirectories

# Search isolation
curl -s "localhost:9200/archive_qubitinformationobject/_search?q=*&size=1" | python3 -m json.tool | grep tenant_id
# Should show tenant_id field

# Cache isolation
mysql -u root archive -e "SELECT setting_key FROM ahg_settings WHERE setting_key LIKE 'tenant_%'"

# Audit isolation
mysql -u root archive -e "SELECT COUNT(*) FROM ahg_audit_log WHERE tenant_id IS NOT NULL"

M2 Verification

# Search explainability
curl -s "https://psis.theahg.co.za/discovery/search?q=test&explain=true" -b cookies.txt | grep "explanation"

# Hierarchy breadcrumb
curl -s "https://psis.theahg.co.za/test-slug" -b cookies.txt | grep "breadcrumb"

M5 Verification

# Health endpoint
curl -s https://psis.theahg.co.za/api/health | python3 -m json.tool

# Job worker
systemctl status atom-worker

# Backup schedule
crontab -l | grep backup

The Archive and Heritage Group (Pty) Ltd https://github.com/ArchiveHeritageGroup