Security Best Practices

This guide provides security recommendations for integrating and operating 4Quays in production environments.

API Key Security

Key Storage

Do:

• Store API keys in environment variables
• Use secrets management (AWS Secrets Manager, HashiCorp Vault)
• Encrypt keys at rest

Don't:

• Commit keys to source control
• Log API keys
• Share keys across environments

// Good
const apiKey = process.env.FOURQ_API_KEY;

// Bad
const apiKey = 'sk_live_xxxxx'; // Hardcoded

Key Rotation

• Rotate keys at least quarterly
• Rotate immediately if compromise suspected
• Use separate keys for each environment
• Revoke unused keys promptly

Key Scoping

• Use test keys (sk_test_) for development
• Use production keys (sk_live_) only in production
• Create separate keys for different services
• Use admin keys (sk_admin_) only for administrative operations

Environment Separation

Separate Organizations

Create separate 4Quays organizations for:

• Development
• Staging
• Production

This ensures:

• Different API keys per environment
• Isolated audit trails
• No accidental cross-environment operations

Policy Naming

Use consistent naming that includes environment:

Good:
- BANK-TRANSFER-DEV-001
- BANK-TRANSFER-STAGE-001
- BANK-TRANSFER-PROD-001

Bad:
- BANK-TRANSFER-001 (which environment?)

Payload Handling

Sensitive Data

• Minimize sensitive data in payloads
• Don't include unnecessary fields
• Consider data classification

// Include only what's needed
const payload = {
  transferId: transfer.id,
  amount: transfer.amount,
  destination: transfer.destination,
  // Don't include: user.ssn, user.fullCreditHistory, etc.
};

Input Validation

Validate data before protecting:

// Validate before protect
const validated = schema.parse(payload);
const protected = await fourq.protect(validated, 'POLICY');

Don't Modify Protected Payloads

Treat protected payloads as opaque:

// Good
const protected = await fourq.protect(payload, 'POLICY');
await sendToService({ data: protected });

// Bad - never modify protected data
protected.extra = 'field'; // Corrupts the payload

Error Handling

Log Appropriately

Log errors without exposing sensitive data:

try {
  await fourq.protect(payload, 'POLICY');
} catch (error) {
  // Good: Log error code and request ID
  logger.error({
    code: error.code,
    requestId: error.requestId,
    message: error.message,
  });

  // Bad: Never log the payload
  logger.error({ payload }); // Exposes sensitive data
}

Handle Crypto Errors Specially

Signature verification failures may indicate tampering:

try {
  const result = await fourq.unprotect(payload, 'POLICY');
} catch (error) {
  if (error.code === 'SIGNATURE_INVALID') {
    // Alert security team - potential tampering
    securityAlert('Signature verification failed', { requestId: error.requestId });
  }
}

Key Management

Rotation Schedule

Key Transition

When rotating keys:

1. Generate new key
2. Update policies to use new key
3. Allow overlap period
4. Verify new key works
5. Deprecate old key
6. Retire old key after grace period

Monitor Key Usage

Set up alerts for:

• Operations with expired keys
• Unusual key usage patterns
• Failed operations due to key issues

Monitoring and Alerting

Essential Alerts

Configure alerts for:

Audit Log Review

Review audit logs regularly:

• Daily: Check for errors
• Weekly: Review algorithm distribution
• Monthly: Generate compliance reports
• Quarterly: Full security review

Network Security

TLS Configuration

Ensure strong TLS configuration:

• Minimum TLS 1.2 (prefer 1.3)
• Strong cipher suites
• Certificate validation

IP Allowlisting

For additional security:

• Restrict 4Quays access to known IPs
• Use VPN for administrative access
• Consider private networking options

Incident Response

If API Key Compromised

1. Immediately revoke the compromised key
2. Generate new key and update applications
3. Review audit logs for unauthorized operations
4. Assess impact of any unauthorized operations
5. Document the incident

If Unexpected Operations Detected

1. Identify the source of operations
2. Verify legitimacy with application teams
3. Revoke credentials if unauthorized
4. Review access controls
5. Implement additional monitoring

Compliance Considerations

Data Residency

• Understand where 4Quays processes data
• Choose appropriate region for your requirements
• Consider on-premises for strict residency requirements

Retention Policies

• Configure appropriate log retention
• Export logs to your SIEM if required
• Document retention for compliance audits

Access Control

• Use least privilege principle
• Separate admin and operational access
• Regular access reviews

Development Practices

Code Review

Review integrations for:

• API key exposure
• Proper error handling
• Correct policy usage
• No payload modification

Testing

Test failure scenarios:

• Invalid API key
• Network failures
• Policy not found
• Key expiration

describe('4Quays integration', () => {
  it('handles policy not found', async () => {
    await expect(
      fourq.protect(payload, 'INVALID-POLICY')
    ).rejects.toThrow('POLICY_NOT_FOUND');
  });
});

Security Scanning

Include in CI/CD:

• Secret scanning for API keys
• Dependency vulnerability scanning
• Static analysis for security issues

Checklist

Before going to production:

• [ ] API keys stored in secrets manager
• [ ] Separate keys for each environment
• [ ] Error handling implemented
• [ ] No payloads logged
• [ ] Alerts configured
• [ ] Key rotation plan documented
• [ ] Incident response plan documented
• [ ] Access controls reviewed
• [ ] Audit log retention configured
• [ ] TLS configuration verified

What's Next

• API Reference — API documentation
• Audit Logs — Monitoring operations