# irc.now Network (net.irc.now) Design

## Goal

Deploy an Ergo IRC server at net.irc.now as the irc.now platform's own IRC network, with Keycloak SSO and automatic soju bouncer uplink.

## Architecture

Single Ergo IRC server managed by the existing ergo-operator. Users authenticate via SASL OAUTHBEARER against Keycloak (same SSO as all other irc.now services). Every soju bouncer gets net.irc.now as a default upstream network.

## Components

### Ergo IRC Server

- Domain: net.irc.now
- Image: ghcr.io/ergochat/ergo:stable (unmodified)
- Listeners: ircs://0.0.0.0:6697 (TLS), irc+insecure://0.0.0.0:6667 (plain)
- Storage: 1Gi PVC on customer-workload-storage
- Network name: irc.now
- TLS: cert-manager Certificate via letsencrypt-prod, passthrough Route

### Authentication

SASL OAUTHBEARER via Keycloak. Ergo's `accounts.oauth2` config block:

```yaml
accounts:
  oauth2:
    enabled: true
    autocreate: true
    introspection-url: "https://auth.irc.now/realms/irc-now/protocol/openid-connect/token/introspect"
    introspection-timeout: 10s
    client-id: "ergo"
    client-secret: "<from secret>"
```

New Keycloak client `ergo` (confidential) in `irc-now` realm. Client secret in OCP secret `oidc-ergo`.

### Hostname Cloaking

Ergo's built-in IP cloaking with netname `irc.now`:

```yaml
server:
  ip-cloaking:
    enabled: true
    enabled-for-always-on: true
    netname: "irc.now"
    cidr-len-ipv4: 32
    cidr-len-ipv6: 64
    num-bits: 64
```

Users see hostnames like `<hash>.irc.now` in whois. Authenticated users' Ergo account names match their Keycloak username.

### ergo-operator Changes

The ergo-operator CRD and configmap generation need:

- `oauth2` field on ErgoNetwork spec (introspection URL, secret ref, autocreate flag)
- Configmap emits `accounts.oauth2` block when OAuth2 is configured
- Configmap emits `server.ip-cloaking` block with configurable netname

### Soju Default Upstream

web-api inserts a default upstream network into the soju user's PostgreSQL database when provisioning a new bouncer:

- Table: `Network` in the bouncer's soju DB
- Fields: server=net.irc.now, port=6697, tls=true, nick=<username>
- Internal service address used for soju->ergo connectivity (ClusterIP)
- One-time migration script for existing bouncers

### DNS + TLS

- Cloudflare A record: net.irc.now -> cluster ingress IP
- cert-manager Certificate CR: net-irc-now-cert -> net-irc-now-tls
- Route: passthrough TLS termination

## Deployment Order

1. Commit and deploy ergo-operator + CRD
2. Create Keycloak client `ergo` with token introspection
3. Set up DNS (net.irc.now A record)
4. Create ErgoNetwork CR for net.irc.now
5. Verify Ergo reachable, OAuth2 login works
6. Update web-api to add default upstream on bouncer creation
7. Migrate existing bouncers to have net.irc.now upstream

## Keycloak Clients (updated)

| Client | Type | Purpose |
|--------|------|---------|
| account-portal | confidential | web-api portal login |
| paste | confidential | txt.irc.now login |
| pics | confidential | irc.pics login |
| chat | public | gamja OAuth2 SSO |
| soju | confidential | soju token introspection |
| ergo | confidential | ergo token introspection |