diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index bdb4a496..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.22" + 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 d6c40839..b24ce6b8 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,13 +1,111 @@ # Changelog All notable changes to Ergo will be documented in this file. -## [2.14.0-rc1] - 2024-06-09 +## [2.17.0-rc1] - 2025-12-14 -We're pleased to be publishing the release candidate for v2.14.0 (the official release should follow within two weeks or so). This release contains primarily bug fixes, with the addition of some new authentication mechanisms for integrating with web clients. +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 [@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), 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. +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) @@ -23,6 +121,7 @@ Many thanks to [@al3xandros](https://github.com/al3xandros), donio, [@eeeeeta](h * 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!) @@ -40,6 +139,7 @@ Many thanks to [@al3xandros](https://github.com/al3xandros), donio, [@eeeeeta](h ### 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 diff --git a/Dockerfile b/Dockerfile index 83e50c57..1d5bb800 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,5 +1,5 @@ ## build ergo binary -FROM docker.io/golang:1.22-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 7a62f227..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 # @@ -179,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? @@ -357,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: @@ -375,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? @@ -510,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-*" @@ -712,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: @@ -776,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 @@ -820,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 @@ -922,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 @@ -940,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. @@ -1067,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 b38e905a..cfa3ddc9 100644 --- a/docs/MANUAL.md +++ b/docs/MANUAL.md @@ -44,6 +44,7 @@ _Copyright © Daniel Oaks , Shivaram Lingamneni , Shivaram Lingamneni