diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 97442725..d8772310 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -12,14 +12,14 @@ on: jobs: build: - runs-on: "ubuntu-22.04" + runs-on: "ubuntu-24.04" steps: - name: "checkout repository" uses: "actions/checkout@v3" - name: "setup go" uses: "actions/setup-go@v3" with: - go-version: "1.21" + go-version: "1.25" - name: "install python3-pytest" run: "sudo apt install -y python3-pytest" - name: "make install" diff --git a/.goreleaser.yml b/.goreleaser.yml index 98f8c206..c47ef05c 100644 --- a/.goreleaser.yml +++ b/.goreleaser.yml @@ -1,5 +1,6 @@ # .goreleaser.yml # Build customization +version: 2 project_name: ergo builds: - main: ergo.go @@ -17,6 +18,7 @@ builds: - amd64 - arm - arm64 + - riscv64 goarm: - 6 ignore: @@ -24,30 +26,41 @@ builds: goarch: arm - goos: windows goarch: arm64 + - goos: windows + goarch: riscv64 - goos: darwin goarch: arm + - goos: darwin + goarch: riscv64 - goos: freebsd goarch: arm - goos: freebsd goarch: arm64 + - goos: freebsd + goarch: riscv64 - goos: openbsd goarch: arm - goos: openbsd goarch: arm64 + - goos: openbsd + goarch: riscv64 - goos: plan9 goarch: arm - goos: plan9 goarch: arm64 + - goos: plan9 + goarch: riscv64 flags: - -trimpath archives: - - name_template: "{{ .ProjectName }}-{{ .Version }}-{{ .Os }}-{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}" + name_template: >- + {{ .ProjectName }}-{{ .Version }}- + {{- if eq .Os "darwin" }}macos{{- else }}{{ .Os }}{{ end -}}- + {{- if eq .Arch "amd64" }}x86_64{{- else }}{{ .Arch }}{{ end -}} + {{ if .Arm }}v{{ .Arm }}{{ end -}} format: tar.gz - replacements: - amd64: x86_64 - darwin: macos format_overrides: - goos: windows format: zip @@ -58,6 +71,7 @@ archives: - ergo.motd - default.yaml - traditional.yaml + - docs/API.md - docs/MANUAL.md - docs/USERGUIDE.md - languages/*.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 2e4478d7..b24ce6b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,6 +1,161 @@ # Changelog All notable changes to Ergo will be documented in this file. +## [2.17.0-rc1] - 2025-12-14 + +We're pleased to be publishing the release candidate for v2.17.0 (the official release should follow within a week or so). This release adds support for the [IRCv3 metadata specification](https://ircv3.net/specs/extensions/metadata), thanks to [@thatcher-gaming](https://github.com/thatcher-gaming), as well as bug fixes and minor updates. + +This release includes changes to the config file format, all of which are fully backwards-compatible and do not require updating the file before upgrading. It includes no changes to the database file format. + +Many thanks to [@branchgrove](https://github.com/branchgrove), [@Brutus5000](https://github.com/Brutus5000), [@progval](https://github.com/progval), [@SarahRoseLives](https://github.com/SarahRoseLives), [@thatcher-gaming](https://github.com/thatcher-gaming), [@ValwareIRC](https://github.com/ValwareIRC), and Xogium for contributing patches, reporting issues, and helping test. + +### Config changes +* Added `accounts.metadata` block to configure the new metadata feature. If this block is absent, metadata is disabled. See `default.yaml` for an example. (#2273) +* Added `server.idle-timeouts` for configurable idle timeouts; when unset, the previous hardcoded defaults are used (#2292, thanks [@Brutus5000](https://github.com/Brutus5000)!) +* Added `server.oper-throttle` to configure throttling for failed `OPER` attempts; when unset, this defaults to 1 attempt every 10 seconds (#2296) + +### Added +* Implemented support for the [draft/metadata-2](https://ircv3.net/specs/extensions/metadata) specification, allowing clients to set and retrieve metadata on accounts and channels (#2273, #2277, #2281, #2282, #2301, thanks [@thatcher-gaming](https://github.com/thatcher-gaming)!) +* Added `/v1/status` and `/v1/account_list` HTTP API endpoints (#2261, thanks [@SarahRoseLives](https://github.com/SarahRoseLives)!) +* Enhanced `/v1/account_details` API response with additional fields (#2261, thanks [@SarahRoseLives](https://github.com/SarahRoseLives)!) + +### Fixed +* Fixed `REGISTER` command to strip guest format when applicable, matching `NS REGISTER` behavior (#2270, #2271, thanks [@ValwareIRC](https://github.com/ValwareIRC) and [@thatcher-gaming](https://github.com/thatcher-gaming)!) +* Fixed invalid `FAIL` codes in `REGISTER` command (#2269, thanks [@ValwareIRC](https://github.com/ValwareIRC)!) +* Fixed validation of web push URLs to reject non-HTTPS URLs (#2295) +* Fixed inconsistent behavior when `history.enabled` is set but `history.chathistory-maxmessages` is not (#2303, #2304, thanks [@branchgrove](https://github.com/branchgrove)!) + +### Changed +* The `OPER` command now imposes a throttle on all attempts, never disconnects the client on failure, and logs non-sensitive information about failed attempts (#2296, #2298, thanks Xogium!) + +### Internal +* Official release builds use Go 1.25 (#2290) +* Upgraded the Docker base image from Alpine 3.19 to 3.22 (#2306) + +## [2.16.0] - 2025-05-18 +We're pleased to be publishing v2.16.0, a new stable release. This release contains bug fixes and some minor updates. + +This release includes changes to the config file format, all of which are fully backwards-compatible and do not require updating the file before upgrading. It includes no changes to the database file format. + +Many thanks to [@csmith](https://github.com/csmith), [@delthas](https://github.com/delthas), donio, [@emersion](https://github.com/emersion), [@KlaasT](https://github.com/KlaasT), [@knolley](https://github.com/knolley), [@Mailaender](https://github.com/Mailaender), and [@prdes](https://github.com/prdes) for reporting issues and helping test. + +### Config changes +* Added `api` block for configuring the new HTTP API. If this block is absent, the API is disabled (#2231) +* Added `server.additional-isupport` for publishing arbitrary ISUPPORT tokens (#2220, #2240) +* Added `server.command-aliases` to configure aliases for server commands (#2229, #2236) +* Added options to `roleplay` to customize the NUH's sent for `NPC` and `SCENE`. Roleplay remains deprecated and disabled by default. (#2237) + +### Security +* Mitigated HTTP DoS attacks by rejecting IRC sessions that begin with an HTTP verb, such as `POST`. If you were relying on this to create IRC sessions via an HTTP client, please open an issue. (#2239) + +### Added +* Added an HTTP API, providing programmatic access to Ergo functionality (#2231, thanks [@KlaasT](https://github.com/KlaasT)!) +* Added SAFERATE to 005 ISUPPORT tokens (#2223, thanks [@delthas](https://github.com/delthas)!) +* Added support for ed25519-sha256 for DKIM. However, enabling this algorithm is not recommended since mainstream email providers still do not support it. (#1041, #2242) + +### Fixed +* Fixed `CHATHISTORY TARGETS` from MySQL backend reporting incorrect timestamps when the server timezone is not UTC (#2224) +* Fixed batch name parameter in `draft/isupport` responses (#2253) +* Fixed `NS UNREGISTER` not deleting the stored push subscriptions (#2254) +* Fixed cases where `NS SAREGISTER` could create clients without applying the default user modes (#2252, #2254, thanks donio!) +* Improved validation of `CHATHISTORY` parameters (#2248, #2249, thanks [@prdes](https://github.com/prdes)!) +* Added validation to ensure the MOTD is UTF-8 when `enforce-utf8` is enabled (the recommended default) (#2228, #2233, thanks [@KlaasT](https://github.com/KlaasT)!) +* The client's own `QUIT` line now respects the `server-time` capability (#2218, #2219) +* Fixed sending unnecessary replies to certain invalid `MODE` changes (#2213) +* Improved safety of ISUPPORT length limits (#2241) + +### Changed +* The `draft/message-redaction` capability is no longer advertised when `allow-individual-delete` is disabled (#2215, #2216, thanks [@delthas](https://github.com/delthas)!) +* Receiving the UTF-8 BOM (byte-order mark) at the start of an IRC connection now produces an explicit error (#2244, #2247, thanks [@csmith](https://github.com/csmith), [@Mailaender](https://github.com/Mailaender)!) + +### Internal +* Release builds use Go 1.24.3 (#2217) + +## [2.15.0] - 2025-01-26 + +We're pleased to be publishing v2.15.0, a new stable release. This release adds support for mobile push notifications, via the [draft/webpush](https://github.com/ircv3/ircv3-specifications/pull/471) specification. More information on this is available in the [manual](https://github.com/ergochat/ergo/blob/ab2d842b270d9df217c779df9c7a5c594d85fdd5/docs/MANUAL.md#push-notifications) and [user guide](https://github.com/ergochat/ergo/blob/ab2d842b270d9df217c779df9c7a5c594d85fdd5/docs/USERGUIDE.md#push-notifications). This feature is still considered to be in an experimental state; `default.yaml` ships with it disabled, and its configuration may have backwards-incompatible changes in the future. + +This release includes changes to the config file format, all of which are fully backwards-compatible and do not require updating the file before upgrading. + +This release includes a database change. If you have `datastore.autoupgrade` set to `true` in your configuration, it will be automatically applied when you restart Ergo. Otherwise, you can update the database manually by running `ergo upgradedb` (see the manual for complete instructions). + +Many thanks to [@delthas](https://github.com/delthas), [@donatj](https://github.com/donatj), donio, [@emersion](https://github.com/emersion), and [@eskimo](https://github.com/eskimo) for contributing patches and helping test. + +### Config changes +* Added `webpush` block to the config file to configure push notifications. See `default.yaml` for an example. Note that at this time, `default.yaml` ships with support for push notifications disabled; operators can enable them by setting `webpush.enabled: true`. In the absence of such a block, push notifications are disabled. +* We recommend the addition of `"WEBPUSH": 1` to `fakelag.command-budgets`, to speed up mobile reattach when web push is enabled. See `default.yaml` for an example. + +### Added +* Added support for the [draft/webpush](https://github.com/ircv3/ircv3-specifications/pull/471) specification (#2205, thanks [@emersion](https://github.com/emersion), [@eskimo](https://github.com/eskimo)!) +* Added support for the [draft/extended-isupport](https://github.com/ircv3/ircv3-specifications/pull/543) specification (#2184, thanks [@emersion](https://github.com/emersion)!) +* `UBAN ADD` now accepts `REQUIRE-SASL` with NUH masks, i.e. k-lines (#2198, #2199) +* Ergo now publishes the `SAFELIST` ISUPPORT parameter (#2196, thanks [@delthas](https://github.com/delthas)!) + +### Fixed +* Fixed incorrect parameters when pushing `005` (ISUPPORT) updates to clients on rehash (#2177, #2184) + +### Internal +* Official release builds use Go 1.23.5 +* Added a unique identifier to identify connections in debug logs. This has no privacy implications in a standard, non-debug configuration of Ergo. (#2206, thanks donio!) +* Added support for Solaris on amd64 CPUs (#2183) + +## [2.14.0] - 2024-06-30 + +We're pleased to be publishing v2.14.0, a new stable release. This release contains primarily bug fixes, with the addition of some new authentication mechanisms for integrating with web clients. + +This release includes changes to the config file format, all of which are fully backwards-compatible and do not require updating the file before upgrading. It includes no changes to the database file format. + +Many thanks to [@al3xandros](https://github.com/al3xandros), donio, [@eeeeeta](https://github.com/eeeeeta), [@emersion](https://github.com/emersion), [@Eriner](https://github.com/Eriner), [@eskimo](https://github.com/eskimo), [@Herringway](https://github.com/Herringway), [@jwheare](https://github.com/jwheare), [@knolley](https://github.com/knolley), [@mengzhuo](https://github.com/mengzhuo), pathof, [@poVoq](https://github.com/poVoq), [@progval](https://github.com/progval), [@RNDpacman](https://github.com/RNDpacman), and [@xnaas](https://github.com/xnaas) for contributing patches, reporting issues, and helping test. + +### Config changes +* Added `accounts.oauth2` and `accounts.jwt-auth` blocks for configuring OAuth2 and JWT authentication (#2004) +* Added `protocol` and `local-address` options to `accounts.registration.email-verification`, to force emails to be sent over IPv4 (or IPv6) or to force the use of a particular source address (#2142) +* Added `limits.realnamelen`, a configurable limit on the length of realnames. If unset, no limit is enforced beyond the IRC protocol line length limits (the previous behavior). (#2123, thanks [@eskimo](https://github.com/eskimo)!) +* Added the `accept-hostname` option to the webirc config block, allowing Ergo to accept hostnames passed from reverse proxies on the `WEBIRC` line. Note that this will have no effect under the default/recommended configuration, in which cloaks are used instead (#1686, #2146, thanks [@RNDpacman](https://github.com/RNDpacman)!) +* The default/recommended value of `limits.chan-list-modes` (the size limit for ban/except/invite lists) was raised to 100 (#2081, #2165, #2167) + +### Added +* Added support for the `OAUTHBEARER` SASL mechanism, allowing Ergo to interoperate with Gamja and an OAuth2 provider (#2004, #2122, thanks [@emersion](https://github.com/emersion)!) +* Added support for the [`IRCV3BEARER` SASL mechanism](https://github.com/ircv3/ircv3-specifications/pull/545), allowing Ergo to accept OAuth2 or JWT bearer tokens (#2158) +* Added support for the legacy `rfc1459` and `rfc1459-strict` casemappings (#2099, #2159, thanks [@xnaas](https://github.com/xnaas)!) +* The new `ergo defaultconfig` subcommand prints a copy of the default config file to standard output (#2157, #2160, thanks [@al3xandros](https://github.com/al3xandros)!) + +### Fixed +* Even with `allow-truncation: false` (the recommended default), some oversized messages were being accepted and relayed with truncation. These messages will now be rejected with `417 ERR_INPUTTOOLONG` as expected (#2170) +* NICK and QUIT from invisible members of auditorium channels are no longer recorded in history (#2133, #2137, thanks [@knolley](https://github.com/knolley) and [@poVoq](https://github.com/poVoq)!) +* If channel registration was disabled, registered channels could become inaccessible after rehash; this has been fixed (#2130, thanks [@eeeeeta](https://github.com/eeeeeta)!) +* Attempts to use unrecognized SASL mechanisms no longer count against the login throttle, improving compatibility with Pidgin (#2156, thanks donio and pathof!) +* Fixed database autoupgrade on Windows, which was previously broken due to the use of a colon in the backup filename (#2139, #2140, thanks [@Herringway](https://github.com/Herringway)!) +* Fixed handling of `NS CERT ADD ` when an unprivileged user invokes it on themself (#2128, #2098, thanks [@Eriner](https://github.com/Eriner)!) +* Fixed missing human-readable trailing parameters for two multiline `FAIL` messages (#2043, #2162, thanks [@jwheare](https://github.com/jwheare) and [@progval](https://github.com/progval)!) +* Fixed symbol sent by `353 RPL_NAMREPLY` for secret channels (#2144, #2145, thanks savoyard!) + +### Changed +* Trying to claim a registered nickname that is also actually in use by another client now produces `433 ERR_NICKNAMEINUSE` as expected (#2135, #2136, thanks savoyard!) +* `SAMODE` now overrides the enforcement of `limits.chan-list-modes` (the size limit for ban/except/invite lists) (#2081, #2165) +* Certain unsuccessful `MODE` changes no longer send `324 RPL_CHANNELMODEIS` and `329 RPL_CREATIONTIME` (#2163) +* Debug logging for environment variable configuration overrides no longer prints the value, only the key (#2129, #2132, thanks [@eeeeeta](https://github.com/eeeeeta)!) + +### Internal + +* Official release builds use Go 1.22.4 +* Added a linux/riscv64 release (#2172, #2173, thanks [@mengzhuo](https://github.com/mengzhuo)!) + +## [2.13.1] - 2024-05-06 + +Ergo 2.13.1 is a bugfix release, fixing an exploitable deadlock that could lead to a denial of service. We regret the oversight. + +This release includes no changes to the config file format or database format. + +### Security + +* Fixed an exploitable deadlock that could lead to a denial of service (#2149) + +### Internal + +* Official release builds use Go 1.22.2 + + ## [2.13.0] - 2024-01-14 We're pleased to be publishing v2.13.0, a new stable release. This is a bugfix release that fixes some issues, including a crash. diff --git a/Dockerfile b/Dockerfile index eb21904c..1d5bb800 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ ## build ergo binary -FROM docker.io/golang:1.21-alpine AS build-env +FROM docker.io/golang:1.25-alpine3.22 AS build-env RUN apk upgrade -U --force-refresh --no-cache && apk add --no-cache --purge --clean-protected -l -u make git @@ -16,7 +16,7 @@ RUN sed -i 's/^\(\s*\)\"127.0.0.1:6667\":.*$/\1":6667":/' /go/src/github.com/erg RUN make install ## build ergo container -FROM docker.io/alpine:3.19 +FROM docker.io/alpine:3.22 # metadata LABEL maintainer="Daniel Oaks ,Daniel Thamdrup " \ diff --git a/Makefile b/Makefile index 0a6bcf0e..af4240d1 100644 --- a/Makefile +++ b/Makefile @@ -1,5 +1,3 @@ -.PHONY: all install build release capdefs test smoke gofmt irctest - GIT_COMMIT := $(shell git rev-parse HEAD 2> /dev/null) GIT_TAG := $(shell git tag --points-at HEAD 2> /dev/null | head -n 1) @@ -9,33 +7,42 @@ export CGO_ENABLED ?= 0 capdef_file = ./irc/caps/defs.go +.PHONY: all all: build +.PHONY: install install: go install -v -ldflags "-X main.commit=$(GIT_COMMIT) -X main.version=$(GIT_TAG)" +.PHONY: build build: go build -v -ldflags "-X main.commit=$(GIT_COMMIT) -X main.version=$(GIT_TAG)" +.PHONY: release release: - goreleaser --skip-publish --rm-dist + goreleaser --skip=publish --clean +.PHONY: capdefs capdefs: python3 ./gencapdefs.py > ${capdef_file} +.PHONY: test test: python3 ./gencapdefs.py | diff - ${capdef_file} go test ./... go vet ./... ./.check-gofmt.sh +.PHONY: smoke smoke: install ergo mkcerts --conf ./default.yaml || true ergo run --conf ./default.yaml --smoke +.PHONY: gofmt gofmt: ./.check-gofmt.sh --fix +.PHONY: irctest irctest: install git submodule update --init cd irctest && make ergo diff --git a/default.yaml b/default.yaml index 7936a766..007d8e18 100644 --- a/default.yaml +++ b/default.yaml @@ -100,6 +100,7 @@ server: max-connections-per-duration: 64 # strict transport security, to get clients to automagically use TLS + # (irrelevant in the recommended configuration, with no public plaintext listener) sts: # whether to advertise STS # @@ -134,9 +135,10 @@ server: # the recommended default is 'ascii' (traditional ASCII-only identifiers). # the other options are 'precis', which allows UTF8 identifiers that are "sane" # (according to UFC 8265), with additional mitigations for homoglyph attacks, - # and 'permissive', which allows identifiers containing unusual characters like + # 'permissive', which allows identifiers containing unusual characters like # emoji, at the cost of increased vulnerability to homoglyph attacks and potential - # client compatibility problems. we recommend leaving this value at its default; + # client compatibility problems, and the legacy mappings 'rfc1459' and + # 'rfc1459-strict'. we recommend leaving this value at its default; # however, note that changing it once the network is already up and running is # problematic. casemapping: "ascii" @@ -178,6 +180,17 @@ server: # if this is true, the motd is escaped using formatting codes like $c, $b, and $i motd-formatting: true + # idle timeouts for inactive clients + idle-timeouts: + # give the client this long to complete connection registration (i.e. the initial + # IRC handshake, including capability negotiation and SASL) + registration: 60s + # if the client hasn't sent anything for this long, send them a PING + ping: 1m30s + # if the client hasn't sent anything for this long (including the PONG to the + # above PING), disconnect them + disconnect: 2m30s + # relaying using the RELAYMSG command relaymsg: # is relaymsg enabled at all? @@ -218,6 +231,10 @@ server: # - "192.168.1.1" # - "192.168.10.1/24" + # whether to accept the hostname parameter on the WEBIRC line as the IRC hostname + # (the default/recommended Ergo configuration will use cloaks instead) + accept-hostname: false + # maximum length of clients' sendQ in bytes # this should be big enough to hold bursts of channel/direct messages max-sendq: 96k @@ -352,6 +369,10 @@ server: secure-nets: # - "10.0.0.0/8" + # allow attempts to OPER with a password at most this often. defaults to + # 10 seconds when unset. + oper-throttle: 10s + # Ergo will write files to disk under certain circumstances, e.g., # CPU profiling or data export. by default, these files will be written # to the working directory. set this to customize: @@ -370,6 +391,17 @@ server: # if you don't want to publicize how popular the server is suppress-lusers: false + # publish additional key-value pairs in ISUPPORT (the 005 numeric). + # keys that collide with a key published by Ergo will be silently ignored. + additional-isupport: + #"draft/FILEHOST": "https://example.com/filehost" + #"draft/bazbat": "" # empty string means no value + + # optionally map command alias names to existing ergo commands. most deployments + # should ignore this. + #command-aliases: + #"UMGEBUNG": "AMBIANCE" + # account options accounts: # is account authentication enabled, i.e., can users log into existing accounts? @@ -405,6 +437,10 @@ accounts: sender: "admin@my.network" require-tls: true helo-domain: "my.network" # defaults to server name if unset + # set to `tcp4` to force sending over IPv4, `tcp6` to force IPv6: + # protocol: "tcp4" + # set to force a specific source/local IPv4 or IPv6 address: + # local-address: "1.2.3.4" # options to enable DKIM signing of outgoing emails (recommended, but # requires creating a DNS entry for the public key): # dkim: @@ -501,7 +537,7 @@ accounts: # 1. these nicknames cannot be registered or reserved # 2. if a client is automatically renamed by the server, # this is the template that will be used (e.g., Guest-nccj6rgmt97cg) - # 3. if enforce-guest-format (see below) is enabled, clients without + # 3. if force-guest-format (see below) is enabled, clients without # a registered account will have this template applied to their # nicknames (e.g., 'katie' will become 'Guest-katie') guest-nickname-format: "Guest-*" @@ -586,6 +622,40 @@ accounts: # how many scripts are allowed to run at once? 0 for no limit: max-concurrency: 64 + # support for login via OAuth2 bearer tokens + oauth2: + enabled: false + # should we automatically create users on presentation of a valid token? + autocreate: true + # enable this to use auth-script for validation: + auth-script: false + introspection-url: "https://example.com/api/oidc/introspection" + introspection-timeout: 10s + # omit for auth method `none`; required for auth method `client_secret_basic`: + client-id: "ergo" + client-secret: "4TA0I7mJ3fUUcW05KJiODg" + + # support for login via JWT bearer tokens + jwt-auth: + enabled: false + # should we automatically create users on presentation of a valid token? + autocreate: true + # any of these token definitions can be accepted, allowing for key rotation + tokens: + - + algorithm: "hmac" # either 'hmac', 'rsa', or 'eddsa' (ed25519) + # hmac takes a symmetric key, rsa and eddsa take PEM-encoded public keys; + # either way, the key can be specified either as a YAML string: + key: "nANiZ1De4v6WnltCHN2H7Q" + # or as a path to the file containing the key: + #key-file: "jwt_pubkey.pem" + # list of JWT claim names to search for the user's account name (make sure the format + # is what you expect, especially if using "sub"): + account-claims: ["preferred_username"] + # if a claim is formatted as an email address, require it to have the following domain, + # and then strip off the domain and use the local-part as the account name: + #strip-domain: "example.com" + # channel options channels: # modes that are set when new channels are created @@ -669,6 +739,7 @@ oper-classes: - "history" # modify or delete history messages - "defcon" # use the DEFCON command (restrict server capabilities) - "massmessage" # message all users on the server + - "metadata" # modify arbitrary metadata on channels and users # ircd operators opers: @@ -733,7 +804,7 @@ logging: # be logged, even if you explicitly include it # # useful types include: - # * everything (usually used with exclusing some types below) + # * everything (usually used with excluding some types below) # server server startup, rehash, and shutdown events # accounts account registration and authentication # channels channel creation and operations @@ -777,7 +848,7 @@ lock-file: "ircd.lock" # datastore configuration datastore: - # path to the datastore + # path to the database file (used to store account and channel registrations): path: ircd.db # if the database schema requires an upgrade, `autoupgrade` will attempt to @@ -820,6 +891,9 @@ limits: # identlen is the max ident length allowed identlen: 20 + # realnamelen is the maximum realname length allowed + realnamelen: 150 + # channellen is the max channel length allowed channellen: 64 @@ -839,7 +913,7 @@ limits: whowas-entries: 100 # maximum length of channel lists (beI modes) - chan-list-modes: 60 + chan-list-modes: 100 # maximum number of messages to accept during registration (prevents # DoS / resource exhaustion attacks): @@ -876,6 +950,7 @@ fakelag: "MARKREAD": 16 "MONITOR": 1 "WHO": 4 + "WEBPUSH": 1 # the roleplay commands are semi-standardized extensions to IRC that allow # sending and receiving messages from pseudo-nicknames. this can be used either @@ -894,6 +969,12 @@ roleplay: # add the real nickname, in parentheses, to the end of every roleplay message? add-suffix: true + # allow customizing the NUH's sent for NPC and SCENE commands + # NPC: the first %s is the NPC name, the second is the user's real nick + #npc-nick-mask: "*%s*!%s@npc.fakeuser.invalid" + # SCENE: the %s is the client's real nick + #scene-nick-mask: "=Scene=!%s@npc.fakeuser.invalid" + # external services can integrate with the ircd using JSON Web Tokens (https://jwt.io). # in effect, the server can sign a token attesting that the client is present on # the server, is a member of a particular channel, etc. @@ -1021,3 +1102,56 @@ history: # whether to allow customization of the config at runtime using environment variables, # e.g., ERGO__SERVER__MAX_SENDQ=128k. see the manual for more details. allow-environment-overrides: true + +# metadata support for setting key/value data on channels and nicknames. +metadata: + # can clients store metadata? + enabled: true + # how many keys can a client subscribe to? + max-subs: 100 + # how many keys can be stored per entity? + max-keys: 100 + # rate limiting for client metadata updates, which are expensive to process + client-throttle: + enabled: true + duration: 2m + max-attempts: 10 + +# experimental support for mobile push notifications +# see the manual for potential security, privacy, and performance implications. +# DO NOT enable if you are running a Tor or I2P hidden service (i.e. one +# with no public IP listeners, only Tor/I2P listeners). +webpush: + # are push notifications enabled at all? + enabled: false + # request timeout for POST'ing the http notification + timeout: 10s + # delay sending the notification for this amount of time, then suppress it + # if the client sent MARKREAD to indicate that it was read on another device + delay: 0s + # subscriber field for the VAPID JWT authorization: + #subscriber: "https://your-website.com/" + # maximum number of push subscriptions per user + max-subscriptions: 4 + # expiration time for a push subscription; it must be renewed within this time + # by the client reconnecting to IRC. we also detect whether the client is no longer + # successfully receiving push messages. + expiration: 14d + +# HTTP API. we strongly recommend leaving this disabled unless you have a specific +# need for it. +api: + # is the API enabled at all? + enabled: false + # listen address: + listener: "127.0.0.1:8089" + # serve over TLS (strongly recommended if the listener is public): + #tls: + #cert: fullchain.pem + #key: privkey.pem + # one or more static bearer tokens accepted for HTTP bearer authentication. + # these must be strong, unique, high-entropy printable ASCII strings. + # to generate a new token, use `ergo gentoken` or: + # python3 -c "import secrets; print(secrets.token_urlsafe(32))" + bearer-tokens: + - "example" diff --git a/distrib/docker/README.md b/distrib/docker/README.md index 9d4feed6..d3e214da 100644 --- a/distrib/docker/README.md +++ b/distrib/docker/README.md @@ -53,14 +53,14 @@ For example, to create a new docker volume and then mount it: ```shell docker volume create ergo-data -docker run --init -d -v ergo-data:/ircd -p 6667:6667 -p 6697:6697 ghcr.io/ergochat/ergo:stable +docker run --init --name ergo -d -v ergo-data:/ircd -p 6667:6667 -p 6697:6697 ghcr.io/ergochat/ergo:stable ``` Or to mount a folder from your host machine: ```shell mkdir ergo-data -docker run --init -d -v $(PWD)/ergo-data:/ircd -p 6667:6667 -p 6697:6697 ghcr.io/ergochat/ergo:stable +docker run --init --name ergo -d -v $(pwd)/ergo-data:/ircd -p 6667:6667 -p 6697:6697 ghcr.io/ergochat/ergo:stable ``` ## Customising the config @@ -85,8 +85,8 @@ docker kill -s SIGHUP ergo ## Using custom TLS certificates -TLS certs will by default be read from /ircd/tls.crt, with a private key -in /ircd/tls.key. You can customise this path in the ircd.yaml file if +TLS certs will by default be read from /ircd/fullchain.pem, with a private key +in /ircd/privkey.pem. You can customise this path in the ircd.yaml file if you wish to mount the certificates from another volume. For information on using Let's Encrypt certificates, see [this manual entry](https://github.com/ergochat/ergo/blob/master/docs/MANUAL.md#using-valid-tls-certificates). diff --git a/docs/API.md b/docs/API.md new file mode 100644 index 00000000..524e8077 --- /dev/null +++ b/docs/API.md @@ -0,0 +1,124 @@ + __ __ ______ ___ ______ ___ + __/ // /_/ ____/ __ \/ ____/ __ \ + /_ // __/ __/ / /_/ / / __/ / / / + /_ // __/ /___/ _, _/ /_/ / /_/ / + /_//_/ /_____/_/ |_|\____/\____/ + + Ergo IRCd API Documentation + https://ergo.chat/ + +_Copyright © Daniel Oaks , Shivaram Lingamneni _ + + +-------------------------------------------------------------------------------------------- + +Ergo has an experimental HTTP API. Some general information about the API: + +1. All requests to the API are via POST. +1. All requests to the API are authenticated via bearer authentication. This is a header named `Authorization` with the value `Bearer `. A list of valid tokens is hardcoded in the Ergo config. Future versions of Ergo may allow additional validation schemes for tokens. +1. The request parameters are sent as JSON in the POST body. +1. Any status code other than 200 is an error response; the response body is undefined in this case (likely human-readable text for debugging). +1. A 200 status code indicates successful execution of the request. The response body will be JSON and may indicate application-level success or failure (typically via the `success` field, which takes a boolean value). + +API endpoints are versioned (currently all endpoints have a `/v1/` path prefix). Backwards-incompatible updates will most likely take the form of endpoints with new names, or an increased version prefix. Any exceptions to this will be specifically documented in the changelog. + +All API endpoints should be considered highly privileged. Bearer tokens should be kept secret. Access to the API should be either over a trusted link (like loopback) or secured via verified TLS. See the `api` section of `default.yaml` for examples of how to configure this. + +Here's an example of how to test an API configured to run over loopback TCP in plaintext: + +```bash +curl -d '{"accountName": "invalidaccountname", "passphrase": "invalidpassphrase"}' -H 'Authorization: Bearer EYBbXVilnumTtfn4A9HE8_TiKLGWEGylre7FG6gEww0' -v http://127.0.0.1:8089/v1/check_auth +``` + +This returns: + +```json +{"success":false} +``` + +Endpoints +========= + +`/v1/account_details` +---------------- + +This endpoint fetches account details and returns them as JSON. The request is a JSON object with fields: + +* `accountName`: string, name of the account + +The response is a JSON object with fields: + +* `success`: whether the account exists or not +* `accountName`: canonical, case-unfolded version of the account name +* `email`: email address of the account provided +* `registeredAt`: string, registration date/time of the account (in ISO8601 format) +* `channels`: array of strings, list of channels the account is registered on or associated with + +`/v1/check_auth` +---------------- + +This endpoint verifies the credentials of a NickServ account; this allows Ergo to be used as the source of truth for authentication by another system. The request is a JSON object with fields: + +* `accountName`: string, name of the account +* `passphrase`: string, alleged passphrase of the account + +The response is a JSON object with fields: + +* `success`: whether the credentials provided were valid +* `accountName`: canonical, case-unfolded version of the account name + +`/v1/rehash` +------------ + +This endpoint rehashes the server (i.e. reloads the configuration file, TLS certificates, and other associated data). The body is ignored. The response is a JSON object with fields: + +* `success`: boolean, indicates whether the rehash was successful +* `error`: string, optional, human-readable description of the failure + +`/v1/saregister` +---------------- + +This endpoint registers an account in NickServ, with the same semantics as `NS SAREGISTER`. The request is a JSON object with fields: + +* `accountName`: string, name of the account +* `passphrase`: string, passphrase of the account + +The response is a JSON object with fields: + +* `success`: whether the account creation succeeded +* `errorCode`: string, optional, machine-readable description of the error. Possible values include: `ACCOUNT_EXISTS`, `INVALID_PASSPHRASE`, `UNKNOWN_ERROR`. +* `error`: string, optional, human-readable description of the failure. + +`/v1/account_list` +------------------- + +This endpoint fetches a list of all accounts. The request body is ignored and can be empty. + +The response is a JSON object with fields: + +* `success`: whether the request succeeded +* `accounts`: array of objects, each with fields: + * `success`: boolean, whether this individual account query succeeded + * `accountName`: string, canonical, case-unfolded version of the account name +* `totalCount`: integer, total number of accounts returned + + +`/v1/status` +------------- + +This endpoint returns status information about the running Ergo server. The request body is ignored and can be empty. + +The response is a JSON object with fields: + +* `success`: whether the request succeeded +* `version`: string, Ergo server version string +* `go_version`: string, version of Go runtime used +* `start_time`: string, server start time in ISO8601 format +* `users`: object with fields: + * `total`: total number of users connected + * `invisible`: number of invisible users + * `operators`: number of operators connected + * `unknown`: number of users with unknown status + * `max`: maximum number of users seen connected at once +* `channels`: integer, number of channels currently active +* `servers`: integer, number of servers connected in the network diff --git a/docs/MANUAL.md b/docs/MANUAL.md index 8308fe8c..cfa3ddc9 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -44,6 +44,7 @@ _Copyright © Daniel Oaks , Shivaram Lingamneni , Shivaram Lingamneni