PIN Gate - Infra Guide

Quick guide for adding PIN protection to *.nominate.ai sites.

Prerequisites

Already configured: - cbauth service running on 127.0.0.1:32202 - Upstream defined in /etc/nginx/conf.d/pin-gate-upstream.conf - Auth snippet at /etc/nginx/snippets/pin-gate-auth.conf - PIN hash stored in /home/bisenbek/projects/nominate/cbauth/.env

Add PIN Protection to a Site

Edit the site's NGINX config in /etc/nginx/sites-enabled/:

1. Add the include (inside the server block, before location /):

# PIN Gate Auth
include snippets/pin-gate-auth.conf;

2. Add auth to protected locations:

location / {
    auth_request /internal/auth/verify;
    error_page 401 = @pin_redirect;

    # ... existing proxy_pass etc ...
}

3. Test and reload:

sudo nginx -t && sudo systemctl reload nginx

Full Example

Before:

server {
    listen 443 ssl;
    server_name example.nominate.ai;

    # SSL config...

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        # ...
    }
}

After:

server {
    listen 443 ssl;
    server_name example.nominate.ai;

    # SSL config...

    # PIN Gate Auth
    include snippets/pin-gate-auth.conf;

    location / {
        auth_request /internal/auth/verify;
        error_page 401 = @pin_redirect;

        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        # ...
    }
}

Exclude Paths from Auth

For public endpoints (health checks, webhooks, etc.):

# Public - no auth
location /health {
    proxy_pass http://backend;
}

# Protected - requires PIN
location / {
    auth_request /internal/auth/verify;
    error_page 401 = @pin_redirect;
    proxy_pass http://backend;
}

API Endpoints (Return JSON instead of redirect)

location /api/ {
    auth_request /internal/auth/verify;
    error_page 401 = @api_unauthorized;
    proxy_pass http://backend;
}

location @api_unauthorized {
    default_type application/json;
    return 401 '{"error": "authentication_required"}';
}

Currently Protected Sites

• docs.nominate.ai
• nominate.ai
• www.nominate.ai

Service Management

sudo systemctl status cbauth      # Check status
sudo systemctl restart cbauth     # Restart service
sudo journalctl -u cbauth -f      # View logs

Change PIN

For security, store the PIN as a SHA256 hash (not plaintext):

# 1. Generate hash from your new PIN (PIN not stored in shell history)
read -sp "Enter new PIN: " pin && echo -n "$pin" | sha256sum | cut -d' ' -f1 && unset pin

# 2. Update .env with the hash
sudo nano /home/bisenbek/projects/nominate/cbauth/.env
# Set: PIN_GATE_PIN_HASH=<your_hash>
# Remove any PIN_GATE_PIN line

# 3. Restart service
sudo systemctl restart cbauth

# 4. Verify no warning in logs
sudo journalctl -u cbauth -n 10 | grep -i warning

Why use hashes? Plaintext PINs in environment files can be exposed via process listings or backup leaks. With PIN_GATE_PIN_HASH, the actual PIN never exists on the server.