Security

Kobaru implements multiple layers of security to protect your payments and prevent abuse. This page explains the security mechanisms and best practices.

API key security

API keys authenticate your requests to Kobaru's gateway endpoints.

Key format

kbr_{env}_{random}

Component	Description
`kbr`	Kobaru prefix
`env`	Environment (`live` or `test`)
`random`	40 character base62 string (256 bits of entropy)

Example: kbr_live_aB3dE5fG7hI9jK1lM3nO5pQ7rS9tU1vW3xY5zA

Storage and validation

Keys are never stored in plaintext - only SHA-256 hashes

Validation uses constant-time comparison to prevent timing attacks

Keys are generated with cryptographically secure randomness

Best practices

Never commit keys to source control - Use environment variables

Rotate keys periodically - Create new keys and revoke old ones

Use separate keys for test and production - kbr_test_* vs kbr_live_*

Limit key scope - Create service-specific keys when possible

Monitor key usage - Check last-used timestamps in the console

Transaction verification

Kobaru validates every payment transaction before settlement.

Solana validation checks

Check	What it prevents
Fee payer validation	Spoofed fee payer addresses
Amount validation	Underpayment attacks
Recipient validation	Payment to wrong address
Instruction topology	Malformed transactions
Priority fee limits	Gas exhaustion attacks
Transaction simulation	Failed transactions

Simulation before settlement

Every transaction is simulated on-chain before signing. This ensures:

Payer has sufficient balance

Token account exists

Transaction will succeed

If simulation fails, the transaction is rejected without consuming gas.

Idempotency and replay protection

Kobaru prevents duplicate payments through a multi-layer defense strategy.

The problem

In distributed systems, the same payment request might arrive multiple times due to:

Network retries

Client bugs

Intentional replay attacks

The solution

Layer 1: PostgreSQL atomic upsert

This is a single, atomic database operation. No race condition is possible.

Layer 2: Redis distributed lock

Before processing, we acquire a distributed lock. This provides early rejection for concurrent requests without hitting the database.

Layer 3: State machine caching

Once a payment reaches a terminal state (APPROVED, REJECTED, CONFIRMED, FAILED), that result is cached and returned for any duplicate requests.

Idempotency key computation

SHA-256(clientId + amount + signature/transaction)

The same payment authorization always produces the same idempotency key, ensuring consistent handling.

TOCTOU prevention

Time-of-check to time-of-use (TOCTOU) attacks occur when state changes between validation and action.

The attack:

Attacker submits payment A

System checks: no duplicate found

Attacker submits payment A again (concurrent)

System checks: no duplicate found

Both payments succeed (double charge!)

Kobaru's defense:

The atomic upsert pattern eliminates the gap between check and insert:

Rate limiting

All endpoints are rate-limited to prevent abuse.

Endpoint	Limit
POST /v1/verify	100 req/min per API key
POST /v1/settle	100 req/min per API key
GET /v1/supported	100 req/min per API key

When rate limited, you receive HTTP 429 with a Retry-After header.

Network security

Edge deployment

Kobaru runs on Cloudflare Workers, providing:

Global edge distribution

DDoS protection

TLS encryption everywhere

No single point of failure

Request validation

All requests are validated:

Body size limit: 64KB max

Content-Type validation: JSON only

Schema validation: Zod schemas for all inputs

Secrets validation: Fail fast if environment misconfigured

Best practices for merchants

1. Validate payment responses

Always check the response from /v1/verify or /v1/settle:

2. Use HTTPS everywhere

Never transmit API keys or payment data over unencrypted connections.

3. Implement webhook signature verification

When we add webhooks, always verify signatures before processing.

4. Monitor for anomalies

Watch for:

Unusual payment volumes

High failure rates

Requests from unexpected locations

5. Keep dependencies updated

Update your SDK and dependencies regularly to receive security patches.

Reporting security issues

If you discover a security vulnerability, please report it responsibly:

Email: security@kobaru.io

Do not disclose publicly until we've addressed the issue

We appreciate responsible disclosure and will acknowledge your contribution

API keys - Creating and managing keys

Error codes - Understanding error responses

Production guide - Security checklist for go-live

Security

Security#

API key security#

Key format#

Storage and validation#

Best practices#

Transaction verification#

Solana validation checks#

Simulation before settlement#

Idempotency and replay protection#

The problem#

The solution#

Idempotency key computation#

TOCTOU prevention#

Rate limiting#

Network security#

Edge deployment#

Request validation#

Best practices for merchants#

1. Validate payment responses#

2. Use HTTPS everywhere#

3. Implement webhook signature verification#

4. Monitor for anomalies#

5. Keep dependencies updated#

Reporting security issues#

Related documentation#

Security

API key security

Key format

Storage and validation

Best practices

Transaction verification

Solana validation checks

Simulation before settlement

Idempotency and replay protection

The problem

The solution

Idempotency key computation

TOCTOU prevention

Rate limiting

Network security

Edge deployment

Request validation

Best practices for merchants

1. Validate payment responses

2. Use HTTPS everywhere

3. Implement webhook signature verification

4. Monitor for anomalies

5. Keep dependencies updated

Reporting security issues

Related documentation