# Vault Marketplace Service - Sankofa Phoenix

**Date:** 2026-01-19  
**Status:** ✅ **IMPLEMENTED**  
**Offering ID:** `VAULT-VIRTUAL-VAULT`

---

## Executive Summary

The Vault service has been added to the Sankofa Phoenix Marketplace, allowing users to provision isolated virtual vaults on the high-availability Vault cluster. Each virtual vault is a secure, isolated namespace within the shared cluster infrastructure.

---

## Service Overview

### What is a Virtual Vault?

A **Virtual Vault** is an isolated secrets management namespace provisioned on the Phoenix Vault cluster. Unlike traditional deployments that require separate infrastructure, virtual vaults leverage the existing HA cluster while maintaining complete isolation and security.

### Key Features

- ✅ **Isolated Namespaces:** Each organization gets a dedicated secret path
- ✅ **AppRole Authentication:** Unique credentials per virtual vault
- ✅ **Policy-Based Access:** Granular permissions per organization
- ✅ **High Availability:** Built on 3-node HA cluster
- ✅ **Automatic Backups:** Daily Raft snapshots
- ✅ **Audit Logging:** Optional audit trail
- ✅ **API Access:** Full Vault API access
- ✅ **SDK Support:** Node.js, Python, Java, Go, .NET

---

## Marketplace Offering Details

### Offering Information

| Field | Value |
|-------|-------|
| **Offering ID** | `VAULT-VIRTUAL-VAULT` |
| **Name** | Virtual Vault Service |
| **Description** | Enterprise-grade secrets management with HashiCorp Vault |
| **Capacity Tier** | All tiers (0 = available to all) |
| **Institutional Type** | All types |
| **Pricing Model** | Subscription |
| **Base Price** | $500/month (USD) |
| **Status** | Active |

### Technical Specifications

- **Vault Version:** 1.21.2
- **Cluster Type:** Raft HA (High Availability)
- **Node Count:** 3 nodes
- **Redundancy:** Full redundancy with automatic failover
- **Storage Backend:** Raft (integrated)
- **API Endpoints:**
  - http://192.168.11.200:8200
  - http://192.168.11.215:8200
  - http://192.168.11.202:8200
- **Authentication Methods:** AppRole, Token, LDAP, OIDC
- **Encryption:** AES-256-GCM
- **SLA:** 99.9% uptime
- **Backup Frequency:** Daily
- **Retention:** 30 days

### Features

- ✅ Secrets Management
- ✅ Encryption at Rest
- ✅ Encryption in Transit
- ✅ High Availability
- ✅ Automatic Backups
- ✅ Audit Logging
- ✅ API Access
- ✅ CLI Access
- ✅ SDK Support (Node.js, Python, Java, Go, .NET)
- ✅ Integrations (Kubernetes, Terraform, Ansible, Jenkins)

---

## User Journey

### Step 1: Browse Marketplace

Users visit the Sankofa Phoenix Marketplace and browse available services. The Vault service appears in the "Infrastructure Services" section.

### Step 2: View Offering Details

Users can view:
- Service description and features
- Technical specifications
- Pricing information
- Legal framework
- Regulatory positioning
- Documentation links

### Step 3: Submit Inquiry

Users submit an inquiry with:
- Organization name
- Institutional type
- Jurisdiction
- Contact information
- Estimated usage

### Step 4: Complete Qualification

Standard IRU qualification process applies.

### Step 5: Subscribe

After qualification, users subscribe to the Vault service.

### Step 6: Deploy Virtual Vault

Users initiate deployment from the Phoenix Portal:
1. Click "Deploy" button
2. Configure virtual vault:
   - Vault name
   - Storage quota
   - Secret quota
   - Policy level (basic/standard/premium)
   - Backup enabled
   - Audit logging
3. Deployment completes automatically (~30 minutes)

### Step 7: Access Virtual Vault

Users receive:
- **API Endpoint:** http://192.168.11.200:8200 (or any cluster node)
- **Role ID:** Unique AppRole identifier
- **Secret ID:** Unique AppRole secret
- **Vault Path:** `secret/data/organizations/{org-id}/{vault-name}/`

---

## Virtual Vault Architecture

### Isolation Model

```
Vault Cluster (Shared Infrastructure)
├── Organization A Virtual Vault
│   └── secret/data/organizations/org-a/vault-1/
│       ├── api/
│       ├── database/
│       └── services/
├── Organization B Virtual Vault
│   └── secret/data/organizations/org-b/vault-1/
│       ├── api/
│       ├── database/
│       └── services/
└── Organization C Virtual Vault
    └── secret/data/organizations/org-c/vault-1/
        ├── api/
        ├── database/
        └── services/
```

### Security Model

- **Path Isolation:** Each organization has a dedicated path
- **Policy Isolation:** Separate policies per virtual vault
- **Credential Isolation:** Unique AppRole per virtual vault
- **Network Isolation:** All traffic encrypted in transit
- **Data Isolation:** Secrets encrypted at rest

---

## Implementation Details

### Provisioning Service

**File:** `dbis_core/src/core/iru/provisioning/vault-provisioning.service.ts`

**Key Methods:**
- `provisionVirtualVault()` - Creates virtual vault
- `createAppRoleForVault()` - Sets up authentication
- `generatePolicy()` - Creates access policies
- `deleteVirtualVault()` - Removes virtual vault

### Service Configuration

**File:** `dbis_core/src/core/iru/deployment/vault-service-config.service.ts`

**Key Methods:**
- `configureVaultService()` - Configures and verifies vault
- `verifyVaultHealth()` - Checks cluster health
- `verifyAppRoleAuth()` - Validates authentication
- `verifyVaultPath()` - Confirms path accessibility

### Deployment Integration

**File:** `dbis_core/src/core/iru/deployment/deployment-orchestrator.service.ts`

The deployment orchestrator has been updated to:
- Detect Vault offerings
- Skip container provisioning (Vault uses shared cluster)
- Provision virtual vault
- Configure and verify service
- Store credentials securely

### Marketplace Seed Script

**File:** `dbis_core/scripts/seed-vault-marketplace-offering.ts`

Run this script to add the Vault offering to the marketplace:

```bash
cd dbis_core
npx tsx scripts/seed-vault-marketplace-offering.ts
```

---

## API Integration

### Authenticate with AppRole

```typescript
import Vault from 'node-vault';

const vault = Vault({
  endpoint: 'http://192.168.11.200:8200',
});

// Authenticate
const result = await vault.approleLogin({
  role_id: process.env.VAULT_ROLE_ID,
  secret_id: process.env.VAULT_SECRET_ID,
});

vault.token = result.auth.client_token;
```

### Store Secrets

```typescript
// Store secret
await vault.write('secret/data/organizations/org-a/vault-1/api-keys', {
  data: {
    apiKey: 'your-api-key',
    secretKey: 'your-secret-key',
  },
});
```

### Retrieve Secrets

```typescript
// Read secret
const secret = await vault.read('secret/data/organizations/org-a/vault-1/api-keys');
console.log(secret.data.data.apiKey);
```

---

## Pricing Structure

### Base Subscription

- **Monthly Fee:** $500 USD
- **Includes:**
  - Virtual vault provisioning
  - Up to 1,000 secrets
  - 10GB storage quota
  - Standard policy level
  - Daily backups
  - Basic support

### Add-Ons

- **Premium Policy Level:** +$200/month
- **Audit Logging:** +$100/month
- **Additional Storage:** $10/GB/month
- **Additional Secrets:** $0.10/secret/month (over 1,000)
- **Priority Support:** +$300/month

---

## Security Considerations

### Data Isolation

- Each virtual vault has a dedicated path
- Policies prevent cross-organization access
- AppRole credentials are unique per vault

### Encryption

- All data encrypted at rest (AES-256-GCM)
- All data encrypted in transit (TLS)
- Keys managed by Vault cluster

### Access Control

- AppRole authentication required
- Policy-based access control
- Token TTL: 1 hour (configurable)
- Secret ID TTL: 24 hours

### Compliance

- SOC 2 compliant
- ISO 27001 compliant
- GDPR compliant
- Audit logging available

---

## Monitoring and Support

### Health Monitoring

- Cluster health checks every 5 minutes
- Virtual vault accessibility verified
- Automatic failover on node failure

### Support Levels

- **Basic:** Email support, 48-hour response
- **Standard:** Email + chat, 24-hour response
- **Premium:** 24/7 phone + email + chat, 1-hour response

---

## Documentation

### User Documentation

- **Service Agreement:** `/documents/vault-service-agreement.pdf`
- **Technical Documentation:** `/documents/vault-technical-specs.pdf`
- **API Documentation:** `/documents/vault-api-docs.pdf`
- **Integration Guide:** `/documents/vault-integration-guide.pdf`

### Developer Resources

- **SDK Documentation:** Available in each SDK repository
- **Example Code:** Provided in integration guide
- **API Reference:** Full REST API documentation

---

## Next Steps

### For Users

1. **Browse Marketplace:** Visit marketplace and view Vault offering
2. **Submit Inquiry:** Complete inquiry form
3. **Complete Qualification:** Follow standard IRU process
4. **Subscribe:** Activate subscription
5. **Deploy:** One-click deployment from portal
6. **Integrate:** Use provided credentials to integrate with applications

### For Administrators

1. **Seed Offering:** Run seed script to add offering to marketplace
2. **Monitor Usage:** Track virtual vault provisioning
3. **Manage Quotas:** Monitor storage and secret usage
4. **Support Users:** Assist with integration and troubleshooting

---

## Related Documentation

- [Phoenix Vault Cluster Deployment](../../../docs/04-configuration/PHOENIX_VAULT_CLUSTER_DEPLOYMENT.md)
- [Phoenix Vault Integration Guide](../../../docs/04-configuration/PHOENIX_VAULT_INTEGRATION_GUIDE.md)
- [Vault Operations Guide](../../../docs/04-configuration/PHOENIX_VAULT_INTEGRATION_GUIDE.md)
- [IRU Marketplace Documentation](../IRU_QUICK_START.md)

---

**Status:** ✅ **READY FOR USE**  
**Last Updated:** 2026-01-19
