What is AMARACUS?

# Liveness: Verifies process is alive
curl https://api.amaracus.tech/health/live

# Readiness: Verifies database connectivity and worker queues
curl https://api.amaracus.tech/health/ready

# Scrape real-time node, HTTP, crypto ops, and queue metrics
curl https://api.amaracus.tech/metrics

# Sample response:
# process_resident_memory_bytes 58490880
# amaracus_crypto_operations_total{status="COMPLETED"} 1420
# amaracus_worker_queue_depth 0
# amaracus_circuit_breaker_state{provider="azure-keyvault"} 0

curl -X POST https://api.amaracus.tech/api/v1/migrations/assess \
  -H "Authorization: Bearer am_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "environment": "production",
    "includeCompliant": false
  }'

# Response returns ranked assessment items with explainable scoring:
# {
#   "summary": { "totalAssessed": 12, "highRisk": 3, "averageScore": 72.4 },
#   "items": [{ "resourceId": "key-rsa-2048", "priorityScore": { "overallScore": 82 } }]
# }

import { Amaracus } from '@amaracus/sdk';

const client = new Amaracus({ apiKey: 'am_live_...' });

// 1. Create Migration Plan
const plan = await client.migrations.createPlan({
  name: 'Upgrade Billing Database to ML-KEM-768',
  migrationType: 'PQC_TRANSITION',
  sourceResourceId: 'key_billing_rsa_2048',
  targetAlgorithm: 'ML-KEM-768',
  proposerId: 'usr_sec_engineer_alice',
  environment: 'production'
});

// 2. Run Non-Destructive Simulation
const sim = await client.migrations.simulatePlan(plan.id);
console.log('Simulation Safe:', sim.overallSafe);
console.log('Rollback Feasible:', sim.rollbackFeasibility.isReversible);

# Step 1: Second officer approves (proposer != approver)
curl -X POST https://api.amaracus.tech/api/v1/migrations/plans/plan_12345/approve \
  -H "Authorization: Bearer am_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "approverId": "usr_ciso_bob" }'

# Step 2: Execute Migration (Generates target key, verifies roundtrip, updates pointer)
curl -X POST https://api.amaracus.tech/api/v1/migrations/plans/plan_12345/execute \
  -H "Authorization: Bearer am_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "executedBy": "usr_ciso_bob" }'

# Step 3: If needed, deterministic rollback:
# curl -X POST https://api.amaracus.tech/api/v1/migrations/plans/plan_12345/rollback \
#   -d '{ "reason": "Downstream legacy system incompatible" }'

// Re-encrypt large historical database datasets in controlled batches:
const result = await client.migrations.reEncrypt({
  sourceKeyId: 'key_old_aes128',
  targetKeyId: 'key_new_aes256_gcm',
  envelopes: [
    { id: 'rec_001', ciphertext: 'base64_blob...', algorithm: 'AES-128-GCM' },
    { id: 'rec_002', ciphertext: 'base64_blob...', algorithm: 'AES-128-GCM' }
  ],
  batchSize: 500
});

console.log('Re-encrypted:', result.successfulCount, 'Failed:', result.failedCount);

import { Amaracus } from '@amaracus/sdk';

const client = new Amaracus({ apiKey: 'am_live_...' });

// Retrieve all verified cryptographic keys, certs, and cloud vaults
const inventory = await client.os.getInventory({ verifiedOnly: true });

console.log('Discovered Resources:', inventory.length);
// Sample item: { id: 'key_master_aes', type: 'KEY', verified: true, verificationSource: 'DIRECT_STORAGE' }

curl https://api.amaracus.tech/api/v1/os/posture \
  -H "Authorization: Bearer am_live_..."

# Response returns overall health score (0-100) and deduplicated findings:
# {
#   "score": 92,
#   "totalFindings": 2,
#   "pqcReadinessPercentage": 60,
#   "verifiedInventoryPercentage": 100,
#   "findings": [
#     { "code": "KEY_ROTATION_OVERDUE", "severity": "MEDIUM", "remediation": { "workflowTemplateId": "tpl_key_rotation" } }
#   ]
# }

// 1. Instantiate Staged Key Rotation Workflow from template
const workflow = await client.os.instantiateTemplate('tpl_key_rotation', {
  name: 'Rotate Database Master Key Q4'
});
console.log('Workflow created in state:', workflow.state); // 'AWAITING_APPROVAL'

// 2. Second Officer approves workflow (server-side proposer !== approver enforcement)
const approved = await client.os.approveWorkflow(workflow.id, 'usr_security_officer_bob');
console.log('Approved state:', approved.state); // 'READY'

// 3. Execute approved workflow steps sequentially
const result = await client.os.executeWorkflow(workflow.id);
console.log('Completed all', result.steps.length, 'steps successfully!');

# Trigger automated background rules check across key ages and cert validity:
curl -X POST https://api.amaracus.tech/api/v1/os/automations/evaluate \
  -H "Authorization: Bearer am_live_..."

# Response:
# {
#   "totalRules": 3,
#   "evaluations": [
#     { "rule": { "trigger": "CERT_EXPIRING" }, "triggered": false, "reason": "All certificates within validity windows" }
#   ]
# }

import { Amaracus } from '@amaracus/sdk';

const client = new Amaracus({ apiKey: 'am_live_...' });

// Query active recommendations sorted by priority score
const recommendations = await client.intelligence.getRecommendations({
  status: 'DETECTED',
  severity: 'CRITICAL'
});

for (const rec of recommendations) {
  console.log(`[${rec.priorityScore} pts] ${rec.title}`);
  console.log('Observed Facts:', rec.explanation.observedFacts);
  console.log('Remediation:', rec.proposedAction.type);
}

// Simulate proposed action without mutating production keys:
const dryRun = await client.intelligence.dryRunRecommendation('rec-rot-master');

console.log('Downtime:', dryRun.potentialDowntime); // 'NONE'
console.log('Reversibility:', dryRun.reversibility); // 'FULLY_REVERSIBLE'
console.log('Policy Compliant:', dryRun.policyConsequences.compliant); // true
console.log('Required Approvals:', dryRun.requiredApprovals); 
// ['SECURITY_OFFICER_APPROVAL', 'FOUR_EYES_SECOND_PARTY_APPROVAL']

// Step 1: Officer Alice accepts the recommendation
await client.intelligence.acceptRecommendation('rec-rot-master', {
  reason: 'Scheduled for Q4 key cryptoperiod renewal'
});

// Step 2: Officer Bob executes the remediation (proposer != executor)
// If Alice tries to execute, AMARACUS rejects with 403 Forbidden.
const completed = await client.intelligence.executeRecommendation('rec-rot-master');
console.log('Remediation completed! Status:', completed.status); // 'COMPLETED'

# Triggers live telemetry scan across Keys, Certs, Circuit Breakers, and Policies:
curl -X POST https://api.amaracus.tech/api/v1/intelligence/analyze \
  -H "Authorization: Bearer am_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "categories": ["SECURITY_RISK", "KEY_LIFECYCLE", "PQC_READINESS"] }'

# Response:
# {
#   "data": {
#     "newlyDetected": 2,
#     "total": 5,
#     "recommendations": [...]
#   }
# }

import { Amaracus } from '@amaracus/sdk';

const client = new Amaracus({ apiKey: 'am_live_...' });

// Evaluate SOC 2 Type II compliance in real-time
const report = await client.compliance.evaluate({
  frameworkId: 'SOC_2_TYPE_II',
  forceRefresh: true
});

console.log('Overall SOC 2 Score:', report.overallScore + '%'); // e.g. 100%
console.log('Satisfied Controls:', report.satisfiedControls, '/', report.totalControls);
console.log('Identified Gaps:', report.gapsCount);
console.log('Cryptographic Digest:', report.reportDigest); // SHA-256 hash

// Step 1: Officer Alice requests a temporary exception for a legacy connection
const exception = await client.compliance.requestException({
  controlId: 'SOC2-CC6.1',
  justification: 'Legacy banking mainframe batch connector migration scheduled for Q4',
  compensatingControls: 'Air-gapped VPC subnet, mutual TLS 1.3, hourly log verification',
  expiresAt: new Date(Date.now() + 30 * 86400000).toISOString() // 30-day grace period
});

console.log('Exception created! Status:', exception.status); // 'PENDING'

// Step 2: Independent Officer Bob approves the exception
// (If Alice attempts to approve her own exception, AMARACUS rejects with 403 Forbidden)
const approved = await client.compliance.approveException(exception.id, 'usr_bob_auditor');
console.log('Exception approved by Bob! Status:', approved.status); // 'APPROVED'

# Export RFC 4180 CSV report for compliance spreadsheets (Vanta, Drata, Excel):
curl -s -H "Authorization: Bearer am_live_..." \
  "https://api.amaracus.tech/api/v1/compliance/reports/csv?frameworkId=SOC_2_TYPE_II" > soc2_audit_report.csv

# Export programmatic JSON report with SHA-256 integrity stamp:
curl -s -H "Authorization: Bearer am_live_..." \
  "https://api.amaracus.tech/api/v1/compliance/reports/json?frameworkId=ISO_27001_2022" > iso27001_report.json

import { Amaracus } from '@amaracus/sdk';

async function main() {
  // 1. Initialize Amaracus Client
  const client = new Amaracus({
    apiKey: process.env.AMARACUS_API_KEY!,
    baseUrl: process.env.AMARACUS_BASE_URL || 'https://api.amaracus.tech/api/v1'
  });

  console.log('=== Step 1: Discover Unified Inventory ===');
  const inventory = await client.os.getInventory({ verifiedOnly: true });
  console.log(`Found ${inventory.length} cryptographic resources.`);

  console.log('\n=== Step 2: Query Security Posture & Deduplicated Findings ===');
  const posture = await client.os.getPosture();
  console.log(`Overall Health Score: ${posture.score} / 100`);
  console.log(`PQC Readiness: ${posture.pqcReadinessPercentage}%`);
  for (const finding of posture.findings) {
    console.log(`  - [${finding.severity}] ${finding.title} (${finding.code})`);
  }

  console.log('\n=== Step 3: Create & Simulate Migration Plan ===');
  const plan = await client.migrations.createPlan({
    name: 'Transition Billing Keys to ML-KEM-768',
    migrationType: 'PQC_TRANSITION',
    sourceResourceId: 'key_billing_rsa_2048',
    sourceAlgorithm: 'RSA-2048',
    targetAlgorithm: 'ML-KEM-768',
    proposerId: 'usr_alice_engineer',
    environment: 'production'
  });
  console.log(`Created plan ${plan.id} in state: ${plan.state}`);

  // Run non-destructive simulation
  const simulation = await client.migrations.simulatePlan(plan.id);
  console.log(`Simulation Safe: ${simulation.overallSafe}`);
  console.log(`Rollback Feasible: ${simulation.rollbackFeasibility.isReversible}`);

  console.log('\n=== Step 4: Multi-Party Approval (Four-Eyes Principle) ===');
  // Proposer Alice cannot approve her own plan; Bob the CISO signs off
  const approvedPlan = await client.migrations.approvePlan(plan.id, 'usr_bob_ciso');
  console.log(`Plan approved by ${approvedPlan.approverId}. State: ${approvedPlan.state}`);

  console.log('\n=== Step 5: Execute Migration with Zero Downtime ===');
  const executed = await client.migrations.executePlan(plan.id, 'usr_bob_ciso');
  console.log(`Migration completed! New active key pointer: ${executed.targetResourceId}`);
  console.log(`Old key ${executed.sourceResourceId} status: RETIRED_FOR_ENCRYPTION (Historical reads preserved).`);

  console.log('\n=== Step 6: Evaluate Continuous Automation Rules ===');
  const automations = await client.os.evaluateAutomations();
  console.log(`Evaluated ${automations.totalRules} rules across estate. Active watchdogs: ${automations.evaluations.length}`);
}

main().catch(console.error);

// If any downstream client experiences an issue, trigger instant deterministic rollback:
const rollback = await client.migrations.rollbackPlan(
  'plan_mig_12345',
  'Downstream payment partner incompatible with multi-kilobyte lattice keys'
);

console.log('Rollback status:', rollback.state); // 'ROLLED_BACK'
console.log('Active key restored to original source key pointer.');

# AMARACUS Cryptographic Integration Guardrails

When generating encryption, decryption, signing, or post-quantum key exchange in this codebase:
1. NEVER generate custom, local cryptographic algorithms, unauthenticated AES modes (ECB/CBC), or insecure random math.
2. Use the AMARACUS REST API (https://api.amaracus.tech/v1) or the @amaracus/sdk TypeScript client.
3. Keep the API key in process.env.AMARACUS_API_KEY. NEVER expose it to client-side bundles (e.g., no NEXT_PUBLIC_ prefixes).
4. Core endpoints:
   - Encrypt with a managed key: POST /v1/encrypt { key, data } -> data.envelope
   - Decrypt: POST /v1/decrypt { key, envelope } -> data.plaintext, data.encoding
   - Hashing (SHA-2 / SHA-3 only): POST /v1/hash { algorithm, data }
   - Post-Quantum KEM (ML-KEM-768): POST /v1/crypto/kem/keygen, /v1/crypto/kem/encapsulate, /v1/crypto/kem/decapsulate
   - Security Posture & CBOM: GET /v1/os/posture & GET /v1/os/inventory
5. Passwords: AMARACUS does not hash passwords. Use Argon2id (or scrypt/bcrypt) locally; never SHA-256 alone.
6. Zero-out sensitive plaintext from memory after use and never log plaintext or keys.

# 1. Check your API key works (lists the keys it can see)
curl https://api.amaracus.tech/v1/keys \
  -H "Authorization: Bearer $AMARACUS_API_KEY"

# 2. Encrypt with one of your managed keys
curl -X POST https://api.amaracus.tech/v1/encrypt \
  -H "Authorization: Bearer $AMARACUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"key":"'"$AMARACUS_KEY_ID"'","data":"Sensitive payload test"}'