# Hiyve Identity System — Security Compliance Report

**Scope:** `@hiyve/identity-client`, `@hiyve/identity-react`, Hiyve Cloud Identity Backend
**Audit Date:** February 2026
**Status:** 9 of 10 OWASP Top 10 (2021) categories pass; 1 partial

---

## Overview

This report summarizes the security posture of the Hiyve Identity system. It covers what security guarantees your application receives out of the box and what you need to configure on your side.

---

## OWASP Top 10 (2021) Compliance

| # | Category | Status | What This Means for You |
|---|----------|--------|------------------------|
| A01 | Broken Access Control | **Pass** | All data is scoped to your organization. Users in one tenant cannot access another tenant's data, tokens, or sessions. |
| A02 | Cryptographic Failures | **Pass** | Passwords are hashed with industry-standard algorithms. Tokens are cryptographically signed. All transport is over TLS. OAuth flows use PKCE (S256). |
| A03 | Injection | **Pass** | All inputs are validated server-side. The client SDK validates inputs before transmission. |
| A04 | Insecure Design | **Pass** | Defense-in-depth with layered rate limiting, adaptive two-factor authentication, and automatic session invalidation. Secure defaults on all configuration. |
| A05 | Security Misconfiguration | **Pass** | Cookies use `HttpOnly`, `Secure`, and `SameSite=Strict` attributes. CORS is restricted to allowed origins. |
| A06 | Vulnerable Components | **Pass** | The client SDK has zero runtime dependencies, eliminating supply-chain risk. |
| A07 | Auth Failures | **Pass** | Adaptive TFA with device recognition. Password complexity requirements enforced. Short-lived access tokens with rotating refresh tokens. Account lockout after repeated failures. |
| A08 | Data Integrity Failures | **Pass** | OAuth PKCE prevents authorization code interception. Tokens are signed to prevent tampering. CSRF protection prevents cross-site attacks on all state-changing operations. |
| A09 | Logging & Monitoring | **Partial** | Authentication events are logged. Structured audit logging for compliance exports is planned (see [Roadmap](#upcoming-improvements)). |
| A10 | SSRF | **N/A** | The identity system does not make server-side requests to user-supplied URLs. |

---

## What the System Provides

### Password Security

- Passwords are hashed with an industry-standard adaptive algorithm before storage
- Password policy: 8–128 characters with complexity requirements enforced server-side
- Password reset tokens are single-use with time-limited validity

### Token Security

- Access tokens are cryptographically signed and short-lived (15 minutes)
- Refresh tokens rotate on each use — old tokens cannot be replayed
- Failed refresh attempts clear all local auth state automatically

### CSRF Protection

- Handled automatically by the SDK — no consumer configuration needed
- All state-changing operations (login, registration, password reset, token creation) are protected
- CSRF tokens are scoped per-organization, preventing cross-tenant reuse
- Mismatched or missing tokens are rejected with HTTP 403

### Rate Limiting

- Layered rate limiting protects authentication and login endpoints independently
- Per-tenant isolation ensures one organization's traffic cannot affect another
- When rate limited, the SDK throws an `AuthError` with code `RATE_LIMITED` and the server returns a `Retry-After` header
- Rate limits are enforced consistently across all infrastructure

### Multi-Tenant Isolation

All identity operations are scoped to the organization associated with your API key:

- Every read and write is scoped to your organization
- Tokens are bound to the issuing organization
- CSRF tokens cannot be reused across tenants
- Rate limits are tracked per-organization
- MCP tokens and OAuth clients are restricted to their creating organization
- There is no mechanism for cross-tenant data access

### Two-Factor Authentication

- Known devices bypass TFA automatically using device recognition
- Unknown devices trigger email OTP verification (6-digit codes)
- Trusted device registrations expire after 90 days of inactivity
- Users can view and revoke trusted devices at any time

### OAuth 2.1 with PKCE

- Standards-compliant OAuth 2.1 implementation
- PKCE (S256) prevents authorization code interception
- Authorization codes are single-use with a 10-minute expiry

---

## Client SDK Security

### Zero Dependencies

`@hiyve/identity-client` has **zero runtime dependencies**. This eliminates supply-chain risk from transitive dependencies. The SDK is built on native browser APIs (`fetch`, `localStorage`, Web Crypto API).

### API Key Scoping

The SDK only accepts **publishable API keys** (prefixed `pk_live_` or `pk_test_`). These keys identify your organization but cannot perform privileged operations. Secret keys are never used or accepted by the client SDK.

### Token Storage

- **Default:** `localStorage` for persistent sessions across page reloads
- **Alternative:** In-memory storage for SSR, testing, or environments without `localStorage`
- **Automatic fallback:** If `localStorage` is unavailable at runtime, the SDK falls back to memory storage silently

### Content Security Policy Recommendations

For applications using the Hiyve Identity SDK, configure your CSP headers to allow connections to the Hiyve API:

```
Content-Security-Policy:
  default-src 'self';
  connect-src 'self' https://api.hiyve.dev;
  script-src 'self';
```

---

## Token Lifecycle

| Token | Lifetime | Storage | Rotation |
|-------|----------|---------|----------|
| Access token | 15 minutes | Client-side (localStorage or memory) | Auto-refreshed before expiry |
| Refresh token | 7 days | Client-side (localStorage or memory) | Rotated on each refresh |
| TFA challenge | 10 minutes | Server-side only | Single use |
| OTP code | 10 minutes | Server-side only | Invalidated after verification or expiry |
| MCP token | Configurable (up to 365 days) | Consumer-managed | Manual rotation via revoke + create |
| OAuth authorization code | 10 minutes | Server-side only | Single use, bound to PKCE verifier |

---

## Upcoming Improvements

The following improvements are planned for future releases:

| Priority | Feature | Target |
|----------|---------|--------|
| High | Token storage XSS mitigation guidance | Ongoing — see [CSP Recommendations](#content-security-policy-recommendations) |
| Medium | Progressive account lockout policy | Q2 2026 |
| Medium | Per-endpoint OTP attempt rate limiting | Q2 2026 |
| Medium | Structured audit logging for compliance exports | Q3 2026 |
| Medium | Enhanced key rotation support | Q3 2026 |

### Token Storage and XSS

Tokens stored in `localStorage` are accessible to any JavaScript running on the same origin. While the SDK does not introduce XSS vectors (zero dependencies, no DOM manipulation), your application must prevent XSS through:

- Strict Content Security Policy (see [CSP Recommendations](#content-security-policy-recommendations))
- Input sanitization on all user-generated content
- Subresource Integrity (SRI) on third-party scripts

For high-security environments, use `tokenStorage: 'memory'` to keep tokens out of persistent storage (tokens will not survive page reloads).

---

## Consumer Security Checklist

Use this checklist to verify your integration follows security best practices:

- [ ] **HTTPS only** — serve your application exclusively over HTTPS
- [ ] **CSP headers** — configure `connect-src` to allow `https://api.hiyve.dev` and block inline scripts
- [ ] **API key management** — use `pk_live_*` keys in production and `pk_test_*` keys in development; never expose secret keys to the browser
- [ ] **Token storage** — use `localStorage` (default) for standard applications; use `memory` for high-security or SSR environments
- [ ] **Session timeouts** — configure `refreshBuffer` appropriate to your security requirements (default: 300 seconds)
- [ ] **TFA enforcement** — ensure your UI handles the `tfaRequired` response and `onTfaRequired` event
- [ ] **Device management** — provide users access to trusted device listing and revocation
- [ ] **Error handling** — handle `RATE_LIMITED`, `TFA_CHALLENGE_LOCKED`, and `TOKEN_REFRESH_FAILED` errors gracefully
- [ ] **Cleanup** — call `auth.destroy()` on application unmount to stop auto-refresh timers and clear listeners
- [ ] **Subresource Integrity** — use SRI hashes on all third-party scripts loaded by your application

---

*This report covers the Hiyve Identity system as of February 2026. For questions about security practices or to report a vulnerability, contact security@hiyve.dev.*