Subdomain Architecture

Special Subdomains

Subdomain Rules

1. Each subdomain is isolated: Cookies set on slack.gimme.tools cannot be read by notion.gimme.tools
2. Root domain cookies are forbidden: No cookies on bare gimme.tools
3. Tokens are audience-bound: JWT aud claim must match subdomain
4. Cross-origin requires explicit CORS: Services can't call each other without permission

Cookie & Token Scoping

Cookie Configuration

Set-Cookie: session_token=xxx;
  Domain=auth.gimme.tools;
  Path=/;
  HttpOnly;
  Secure;
  SameSite=Strict;
  Max-Age=604800

Critical cookie attributes:

Cookie Scoping Rules

❌ WRONG: Cookies on root domain
Set-Cookie: token=xxx; Domain=gimme.tools

✅ CORRECT: Cookies on specific subdomain
Set-Cookie: token=xxx; Domain=auth.gimme.tools

Token Audience Binding

Every JWT must include an aud (audience) claim matching the subdomain:

{
  "iss": "auth.gimme.tools",
  "sub": "user_12345",
  "aud": "slack.gimme.tools",
  "exp": 1704067200,
  "scope": "GET:channels/*,POST:channels/*/messages",
  "session_id": "sess_abc123",
  "device_id": "dev_xyz789"
}

Token Validation

function validateToken(token, request) {
  const payload = decodeJWT(token);
  const requestSubdomain = new URL(request.url).hostname;

  // Audience must match request subdomain
  if (payload.aud !== requestSubdomain) {
    return { valid: false, error: 'Token audience mismatch' };
  }

  // Check expiration
  if (Date.now() > payload.exp * 1000) {
    return { valid: false, error: 'Token expired' };
  }

  // Check scope covers requested action
  if (!scopeCovers(payload.scope, request)) {
    return { valid: false, error: 'Insufficient scope' };
  }

  return { valid: true, payload };
}

local.gimme.tools Bridge

Architecture

The local bridge provides secure access to localhost services through a WebSocket tunnel:

┌───────────────────────────────────────────────────────────────┐
│                         Browser/Agent                          │
│                              │                                 │
│                    HTTPS request to                            │
│                  local.gimme.tools/...                         │
│                              │                                 │
│                              ▼                                 │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │              local.gimme.tools (Cloud)                   │  │
│  │                                                          │  │
│  │   1. Validates session token                             │  │
│  │   2. Checks device binding                               │  │
│  │   3. Routes through WebSocket tunnel                     │  │
│  │                                                          │  │
│  └────────────────────────┬────────────────────────────────┘  │
│                           │                                    │
│                    WebSocket tunnel                            │
│                    (authenticated)                             │
│                           │                                    │
│                           ▼                                    │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │              Local Bridge Agent                          │  │
│  │              (runs on user's machine)                    │  │
│  │                                                          │  │
│  │   1. Validates tunnel authentication                     │  │
│  │   2. Maps to local Unix socket                           │  │
│  │   3. Returns response through tunnel                     │  │
│  │                                                          │  │
│  └────────────────────────┬────────────────────────────────┘  │
│                           │                                    │
│                    Unix socket                                 │
│                           │                                    │
│                           ▼                                    │
│  ┌─────────────────────────────────────────────────────────┐  │
│  │              Local Service                               │  │
│  │              (filesystem, clipboard, etc.)               │  │
│  └─────────────────────────────────────────────────────────┘  │
└───────────────────────────────────────────────────────────────┘

WebSocket Protocol

// Client → Server: Request
{
  "type": "request",
  "id": "req_123",
  "method": "GET",
  "path": "/clipboard",
  "headers": { "Authorization": "Bearer ..." }
}

// Server → Client: Response
{
  "type": "response",
  "id": "req_123",
  "status": 200,
  "headers": { "Content-Type": "text/plain" },
  "body": "clipboard contents..."
}

Device Binding

Local bridge requires device binding verification:

{
  "aud": "local.gimme.tools",
  "device_id": "dev_xyz789",
  "device_verified": true,
  "local_scopes": ["clipboard:read", "filesystem:read"]
}

Local Service Architecture

Unix Socket Isolation

Local services communicate through Unix domain sockets for security:

/var/run/gimme/
├── clipboard.sock      # Clipboard access
├── filesystem.sock     # File operations
├── terminal.sock       # Terminal access
└── browser.sock        # Browser automation

Benefits of Unix sockets:

• No network exposure (localhost-only)
• File permission controls
• Fast IPC without network overhead
• Natural sandboxing

Service Registration

# /etc/gimme/services.d/clipboard.yaml