gitspace 0.2.0-rc.20 → 0.2.0-rc.21

package/docs/GATEWAY-WORKER.md

@@ -1,319 +0,0 @@
-# Gateway Worker Specification
-
-> **Status: SPECIFICATION ONLY - NOT YET IMPLEMENTED**
->
-> This document describes the planned Gateway Worker for subdomain routing and
-> authentication. The current implementation only includes the API Worker
-> (`api.gitspace.sh`) for user/subdomain management. The Gateway Worker
-> described here is Phase 2 of the platform architecture.
-
-## Overview
-
-A Cloudflare Worker that sits in front of all user subdomains (`*.{user}.gitspace.sh`), providing:
-- Authentication via gitspace.sh GitHub OAuth
-- Authorization for shared services
-- Routing to appropriate Cloudflare Tunnels
-
-## Why Not Cloudflare Access?
-
-Cloudflare Access:
-- Uses its own identity providers (separate OAuth flows)
-- Policies configured per-app in dashboard, not programmatically
-- Can't query our D1 database for ACL/invites
-- Can't validate our signed tokens
-
-We need:
-- Single identity across all gitspace.sh subdomains
-- Programmatic access control via our API
-- Custom authorization logic (invites, ACL, port sharing)
-- Portable session (one login works everywhere)
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                        Cloudflare Edge                               │
-│                                                                      │
-│   Request: app.username.gitspace.sh                                  │
-│                    │                                                 │
-│                    ▼                                                 │
-│   ┌────────────────────────────────────────────────────────────┐    │
-│   │                   Gateway Worker                            │    │
-│   │                                                             │    │
-│   │  1. Parse: owner=username, service=app                      │    │
-│   │  2. Validate session cookie (JWT signed by gitspace.sh)     │    │
-│   │  3. Check authorization (D1 query)                          │    │
-│   │  4. Route to tunnel                                         │    │
-│   │                                                             │    │
-│   └────────────────────────────────────────────────────────────┘    │
-│                    │                                                 │
-│                    ▼                                                 │
-│   ┌──────────────────────────────────────────────────────────────┐  │
-│   │              Cloudflare Tunnel → User's Machine               │  │
-│   └──────────────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-## URL Structure
-
-```
-{service}.{owner}.gitspace.sh
-
-Examples:
-  username.gitspace.sh           → relay (default, terminal access)
-  app.username.gitspace.sh       → localhost:3000
-  api.username.gitspace.sh       → localhost:8080
-  preview.username.gitspace.sh   → localhost:5173
-```
-
-## Data Model
-
-```sql
--- Services (ports exposed under a subdomain)
-CREATE TABLE services (
-  id TEXT PRIMARY KEY,
-  subdomain_id TEXT REFERENCES subdomains(id),
-  name TEXT NOT NULL,              -- 'app', 'api', '' (root = relay)
-  local_port INTEGER NOT NULL,     -- 3000, 8080, 4480 (relay)
-  visibility TEXT DEFAULT 'owner', -- 'public', 'owner', 'shared'
-  created_at INTEGER,
-  updated_at INTEGER,
-
-  UNIQUE(subdomain_id, name)
-);
-
--- Service access grants (for visibility='shared')
-CREATE TABLE service_access (
-  id TEXT PRIMARY KEY,
-  service_id TEXT REFERENCES services(id),
-  user_id TEXT REFERENCES users(id),   -- GitHub-authenticated user
-  invite_token_hash TEXT,               -- Alternative: invite-based access
-  expires_at INTEGER,
-  created_at INTEGER
-);
-```
-
-## Authentication
-
-### Session Token (JWT)
-
-Issued by gitspace.sh after GitHub OAuth:
-
-```typescript
-interface SessionToken {
-  sub: string;            // gitspace.sh user ID
-  github_id: string;      // GitHub user ID
-  github_username: string;
-  iat: number;
-  exp: number;
-}
-```
-
-Cookie settings:
-```
-__gitspace_session=<jwt>
-Domain=.gitspace.sh    // Works for all subdomains
-HttpOnly=true
-Secure=true
-SameSite=Lax
-```
-
-### Auth Flow
-
-**First visit (no session):**
-1. User visits `app.username.gitspace.sh`
-2. Gateway Worker: no valid session cookie
-3. Redirect → `gitspace.sh/login?redirect=https://app.username.gitspace.sh`
-4. User authenticates with GitHub
-5. gitspace.sh sets session cookie on `.gitspace.sh`
-6. Redirect back to original URL
-7. Gateway Worker validates session, checks authorization
-
-**Return visit (has session):**
-1. User visits `app.username.gitspace.sh`
-2. Gateway Worker: session cookie present
-3. Validate JWT signature and expiry
-4. Query D1: does this user have access?
-5. Forward to tunnel
-
-**Invite link (no login required):**
-1. User visits `app.username.gitspace.sh?invite=xxx`
-2. Gateway Worker: validate invite signature (Ed25519)
-3. Valid → forward to tunnel
-4. Optionally prompt to "claim" by logging in
-
-## Authorization Logic
-
-```typescript
-async function checkAccess(
-  user: SessionUser | null,
-  service: Service,
-  inviteToken: string | null
-): Promise<boolean> {
-  // Public services: anyone
-  if (service.visibility === 'public') {
-    return true;
-  }
-
-  // Valid invite token: allow
-  if (inviteToken && await validateInvite(inviteToken, service)) {
-    return true;
-  }
-
-  // Must be logged in from here
-  if (!user) {
-    return false;
-  }
-
-  // Owner: always has access to their own services
-  const subdomain = await getSubdomain(service.subdomain_id);
-  if (subdomain.user_id === user.id) {
-    return true;
-  }
-
-  // Shared: check access grants
-  if (service.visibility === 'shared') {
-    const grant = await getAccessGrant(service.id, user.id);
-    return grant !== null && (grant.expires_at === null || grant.expires_at > Date.now());
-  }
-
-  return false;
-}
-```
-
-## Gateway Worker Implementation
-
-```typescript
-// worker-gateway/src/index.ts
-export default {
-  async fetch(request: Request, env: Env): Promise<Response> {
-    const url = new URL(request.url);
-    const host = url.hostname;
-
-    // Parse subdomain: app.username.gitspace.sh
-    const parsed = parseHost(host);
-    if (!parsed) {
-      return new Response('Invalid hostname', { status: 400 });
-    }
-
-    const { owner, serviceName } = parsed;
-
-    // Lookup service in D1
-    const service = await env.DB.prepare(`
-      SELECT s.*, sub.user_id as owner_user_id, sub.tunnel_id
-      FROM services s
-      JOIN subdomains sub ON s.subdomain_id = sub.id
-      WHERE sub.subdomain = ? AND s.name = ?
-    `).bind(owner, serviceName || '').first();
-
-    if (!service) {
-      return new Response('Service not found', { status: 404 });
-    }
-
-    // Get session from cookie
-    const sessionToken = getSessionCookie(request);
-    const user = sessionToken ? await validateSession(sessionToken, env) : null;
-
-    // Get invite from query param
-    const inviteToken = url.searchParams.get('invite');
-
-    // Check authorization
-    const hasAccess = await checkAccess(user, service, inviteToken);
-
-    if (!hasAccess) {
-      // No session? Redirect to login
-      if (!user) {
-        const loginUrl = new URL('https://gitspace.sh/login');
-        loginUrl.searchParams.set('redirect', request.url);
-        return Response.redirect(loginUrl.toString(), 302);
-      }
-
-      // Has session but not authorized
-      return new Response('Access denied', { status: 403 });
-    }
-
-    // Forward to tunnel
-    // The tunnel is already configured with ingress rules
-    // We just need to pass through the request
-    return fetch(request);
-  }
-}
-```
-
-## CLI Commands
-
-```bash
-# Share a port as a service
-gssh share port 3000 --as app
-# Creates: app.username.gitspace.sh → localhost:3000
-
-# Share with specific user
-gssh share port 3000 --as app --with alice
-# Adds alice to service_access
-
-# Make public (no auth required)
-gssh share port 3000 --as app --public
-
-# List shared services
-gssh share list
-# app.username.gitspace.sh → :3000 (owner-only)
-# api.username.gitspace.sh → :8080 (shared: alice, bob)
-# preview.username.gitspace.sh → :5173 (public)
-
-# Stop sharing
-gssh share remove app
-
-# Grant access to existing service
-gssh share grant app --to bob
-
-# Revoke access
-gssh share revoke app --from bob
-```
-
-## Tunnel Configuration
-
-When a user shares a port, the tunnel ingress is updated:
-
-```yaml
-ingress:
-  - hostname: username.gitspace.sh
-    service: http://localhost:4480      # relay
-  - hostname: "*.username.gitspace.sh"
-    service: http://localhost:4480      # default to relay
-  - hostname: app.username.gitspace.sh
-    service: http://localhost:3000      # specific service
-  - service: http_status:404
-```
-
-The Gateway Worker handles auth BEFORE the request reaches the tunnel.
-
-## Migration Path
-
-### Phase 1 (Current)
-- Relay-level auth only (signed messages + challenge-response)
-- No Gateway Worker
-
-### Phase 2 (This Spec)
-- Deploy Gateway Worker
-- Session cookies via gitspace.sh OAuth
-- Owner-only access (prove you own the GitHub account)
-
-### Phase 3 (Future)
-- Invite system for sharing with others
-- Service-level access grants
-- Port sharing CLI commands
-
-## Security Considerations
-
-1. **Session tokens** - Signed by gitspace.sh, validated at edge
-2. **Invite tokens** - Ed25519 signed by service owner, time-limited
-3. **Cookie scope** - `.gitspace.sh` allows SSO across all subdomains
-4. **HTTPS only** - All traffic through Cloudflare, TLS enforced
-5. **No secrets in Worker** - Only public keys for signature validation
-
-## Open Questions
-
-1. **Wildcard routing** - How to handle `*.username.gitspace.sh` efficiently?
-2. **WebSocket support** - Gateway Worker must handle WS upgrade
-3. **Rate limiting** - Per-user or per-service limits?
-4. **Audit logging** - Track access for security/debugging?