OrzattyAccount

1. Abstract & Problem Statement

As the Orzatty ecosystem grows beyond a single application into a suite of interconnected services — Sylor (AI assistant), OrzattyCloud CDN, OrzattyOS, Rany IDE, OpenRany, and others — the authentication problem becomes a first-class infrastructure challenge. Each service managing its own user accounts creates:

• Fragmented user identity: Users must maintain separate credentials across every Orzatty service
• Security inconsistency: Individual services may implement authentication with varying security postures
• Operational overhead: User management operations (password resets, account deactivation) must be replicated across every service
• Audit gaps: No unified view of user access patterns across the ecosystem

OrzattyAccount resolves this by providing a single identity layer: one account, one login, all services. Architecturally, it is modeled after enterprise identity platforms like Auth0, Google Identity Platform, and Okta — but built in-house to maintain data sovereignty and eliminate vendor dependency.

2. Microservices Architecture

OrzattyAccount is a Cargo-workspace-style TypeScript monorepo with 7 independent services communicating over internal REST APIs. Each service owns its data domain and can be scaled, deployed, and updated independently:

Service Communication

All inter-service traffic is internal to the cluster (not exposed externally) and authenticated with service-to-service API keys. Services communicate synchronously for critical auth paths and asynchronously via an internal event bus for audit logging and cache invalidation:

External Request
    → API Gateway (Port 8000) — validates JWT, rate limits, routes
        → Auth Service (Port 8001) — credential verification
        → Session Service (Port 8003) — token refresh, session management
        → User Service (Port 8004) — profile reads/writes
        → Organization Service (Port 8005) — RBAC enforcement
        → OAuth Service (Port 8002) — third-party app authorization

3. Authentication Flow (OAuth2 / OpenID Connect)

OrzattyAccount implements the OAuth2 Authorization Code flow with PKCE (Proof Key for Code Exchange) as the primary authentication mechanism for all Orzatty services. This prevents authorization code interception attacks on mobile and single-page applications:

// 1. Client app generates a code verifier and code challenge
const codeVerifier = crypto.randomBytes(32).toString('base64url');
const codeChallenge = crypto.createHash('sha256')
    .update(codeVerifier).digest('base64url');

// 2. Redirect user to OrzattyAccount authorization endpoint
const authUrl = new URL('https://account.orzatty.com/oauth2/authorize');
authUrl.searchParams.set('response_type', 'code');
authUrl.searchParams.set('client_id', CLIENT_ID);
authUrl.searchParams.set('redirect_uri', REDIRECT_URI);
authUrl.searchParams.set('scope', 'openid profile email');
authUrl.searchParams.set('code_challenge', codeChallenge);
authUrl.searchParams.set('code_challenge_method', 'S256');

// 3. User authenticates, OrzattyAccount returns code
// 4. Client exchanges code for tokens
const tokenResponse = await fetch('https://account.orzatty.com/oauth2/token', {
    method: 'POST',
    body: new URLSearchParams({
        grant_type: 'authorization_code',
        code: authorizationCode,
        redirect_uri: REDIRECT_URI,
        code_verifier: codeVerifier,  // Proves ownership of code challenge
        client_id: CLIENT_ID,
    }),
});
const { access_token, id_token, refresh_token } = await tokenResponse.json();

OpenID Connect Discovery

All configuration metadata is published at the standard discovery endpoint, enabling any compliant OIDC library to automatically configure itself:

GET /.well-known/openid-configuration

{
  "issuer": "https://account.orzatty.com",
  "authorization_endpoint": "https://account.orzatty.com/oauth2/authorize",
  "token_endpoint": "https://account.orzatty.com/oauth2/token",
  "userinfo_endpoint": "https://account.orzatty.com/oauth2/userinfo",
  "jwks_uri": "https://account.orzatty.com/oauth2/jwks",
  "scopes_supported": ["openid", "profile", "email", "phone", "org:read", "org:write"],
  "response_types_supported": ["code", "token", "id_token"],
  "code_challenge_methods_supported": ["S256"]
}

4. Security Design

Password Security

Passwords are hashed using bcrypt with a configurable work factor (default: 12 rounds, equivalent to ~300ms verification time). The work factor is designed to resist brute-force attacks while maintaining a reasonable user experience. Argon2id migration is planned for OrzattyAccount v2.

Multi-Factor Authentication (MFA)

• TOTP (Time-based One-Time Password): RFC 6238 compliant. Compatible with Google Authenticator, Authy, 1Password, and any TOTP application.
• Backup codes: 10 one-time-use backup codes generated at MFA enrollment. Stored as bcrypt hashes, not plaintext.
• Recovery flow: Account recovery via verified email with time-limited tokens (15-minute TTL).

Session Security

Sessions are stored in Redis with a sliding expiration window. Each session includes:

{
  "session_id": "sess_01HXK7...",    // 128-bit random session identifier
  "user_id": "usr_01HXK7...",
  "device_fingerprint": "sha256:...", // Browser/device signature
  "ip_address": "190.x.x.x",         // Logged for impossible-travel detection
  "created_at": "2026-03-21T21:00:00Z",
  "last_active": "2026-03-21T21:05:00Z",
  "expires_at": "2026-04-21T21:00:00Z" // 30-day sliding window
}

Rate Limiting

All authentication endpoints are protected by a GCRA (Generic Cell Rate Algorithm) rate limiter at the API Gateway level, preventing credential stuffing attacks:

• POST /api/auth/login — 5 attempts per IP per 15 minutes
• POST /api/auth/register — 3 attempts per IP per hour
• POST /api/auth/forgot-password — 3 attempts per IP per hour

5. REST API Reference

Authentication Endpoints

• POST /api/auth/login — Credential validation, returns access + refresh tokens
• POST /api/auth/register — New account creation with email verification
• POST /api/auth/logout — Revoke current session token
• POST /api/auth/refresh — Exchange refresh token for new access token
• POST /api/auth/forgot-password — Initiate password reset via email
• POST /api/auth/mfa/enable — Enroll TOTP MFA device
• POST /api/auth/mfa/verify — Verify TOTP code

OAuth2 Endpoints (Standard)

• GET /oauth2/authorize — Authorization endpoint (redirects with code)
• POST /oauth2/token — Token exchange endpoint
• GET /oauth2/userinfo — Returns user profile for valid access token
• GET /oauth2/jwks — JSON Web Key Set for token signature verification
• GET /.well-known/openid-configuration — OIDC discovery document

User Management

• GET /api/users/profile — Get authenticated user's profile
• PUT /api/users/profile — Update profile fields
• GET /api/users/sessions — List all active sessions for user
• DEL /api/users/sessions/:id — Revoke a specific session
• GET /api/users/audit-log — Paginated account activity log

6. TypeScript SDK: @orzattyholding/account-sdk

Services integrating with OrzattyAccount use the official TypeScript SDK, which handles token validation, user info retrieval, and webhook registration without requiring services to implement the OAuth2 flow from scratch:

import { OrzattyAuthSDK } from '@orzattyholding/account-sdk';

const auth = new OrzattyAuthSDK({
    apiUrl:  'https://account.orzatty.com',
    apiKey:  process.env.ORZATTY_SERVICE_KEY,  // Per-service API key issued by OrzattyAccount
    timeout: 5000,  // ms — fail-fast for auth critical paths
});

// Validate an incoming request token (used in middleware)
app.use(async (req, res, next) => {
    const token = req.headers.authorization?.replace('Bearer ', '');
    if (!token) return res.status(401).json({ error: 'Unauthorized' });
    
    try {
        const user = await auth.validateToken(token);
        req.user = user;  // { id, email, name, orgs: [...] }
        next();
    } catch (err) {
        return res.status(401).json({ error: 'Invalid or expired token' });
    }
});

// Check organization membership before granting access
async function requireOrgRole(userId: string, orgId: string, minRole: string) {
    const membership = await auth.getOrgMembership(userId, orgId);
    if (!membership || !hasRole(membership.role, minRole)) {
        throw new UnauthorizedError('Insufficient organization role');
    }
}

Webhook SDK Usage

// Register a webhook for user login events
await auth.registerWebhook({
    eventType: 'user.login',
    url: 'https://sylor.orzatty.com/webhooks/user-login',
    secret: process.env.WEBHOOK_SECRET,   // Used to sign HMAC-SHA256 payloads
    active: true,
});

// Verify incoming webhook payload signature
app.post('/webhooks/user-login', (req, res) => {
    const isValid = auth.verifyWebhookSignature(
        req.body,
        req.headers['x-orzatty-signature'],
        process.env.WEBHOOK_SECRET
    );
    if (!isValid) return res.status(401).send('Invalid signature');
    // Handle event...
});

7. Multi-Organization System

OrzattyAccount supports multi-tenancy at the organizational level. Users can belong to multiple organizations simultaneously and switch contexts seamlessly. This enables enterprise deployments where a company may use Orzatty services under their own branded organization with custom policies.

Role-Based Access Control (RBAC)

Five roles are defined with a hierarchical permission model:

Domain Restrictions

Organizations can restrict membership to users with verified email addresses from approved domains. For example, an enterprise deploying Orzatty services can restrict their organization to @company.com email addresses, ensuring that only verified corporate users can join.

8. Webhook Infrastructure

OrzattyAccount emits signed webhooks for all significant identity events, enabling downstream services to react in real-time to user actions without polling the API:

All webhook payloads are signed with HMAC-SHA256 using the registered webhook secret. The signature is delivered in the X-Orzatty-Signature header as sha256=<hex_digest>, following the same convention as GitHub webhooks.

9. Infrastructure & Scalability

Primary Storage: PostgreSQL 15+

All persistent identity data (users, organizations, OAuth clients, refresh tokens) is stored in PostgreSQL. The schema uses UUIDs as primary keys (not sequential integers) to prevent enumeration attacks. Row-level security policies at the database level enforce data isolation between organizations.

Session Cache: Redis 7+

Active sessions, TOTP challenges, and rate limiter state are stored in Redis with TTL-based expiration. Redis's atomic operations (INCR, GETSET) are used for rate limiting counters, preventing race conditions that could allow burst attacks to slip through.

Horizontal Scaling

Because all state is externalized (PostgreSQL + Redis), every OrzattyAccount service is stateless and can be horizontally scaled behind a load balancer without session affinity requirements. The Docker Compose configuration supports multi-instance deployment with shared database and cache:

docker-compose -f docker-compose.prod.yml up --scale api-gateway=3 \
    --scale auth-service=2 --scale session-service=3

Health & Observability

• Health endpoints: /health on every service (database connectivity + Redis ping) — used by Kubernetes liveness/readiness probes
• Prometheus metrics: Exported on /metrics — request counts, authentication success/failure rates, token validation latency
• Structured JSON logging: All log lines include trace_id, service_name, user_id (when available), and duration_ms

10. Roadmap