From df2f2f244d8fab3d9e0a5843662d48cb48cef90f Mon Sep 17 00:00:00 2001 From: Daniel Oaks Date: Tue, 13 Apr 2021 00:41:02 +1000 Subject: [PATCH] Spec cleanups (#441) Unify spec titles, remove version numbers. Fix duplicate markdown headers. We've changed filenames and the folder structure for all but Metadata and SASL because those specs have pending PRs/updates and I don't want to stomp over them with these. We've also unified the initial-page-titles for specs. Mentioned in example-spec.md, but essentially: "Introduction" is for the first section of a multi-section spec, "Description" is for the main body section when a spec only contains one section, and "Motivation" is used when the spec author wants to split out the introduction/description from the motivation of the spec I guess. Makes all our spec appear much more nicely on the website, I assure ya'. --- .../chathistory.md | 7 ++-- .../netsplit-3.2.md => batches/netsplit.md | 7 ++-- client-tags/react.md | 2 +- client-tags/reply.md | 2 +- client-tags/typing.md | 3 +- core/metadata-3.2.md | 2 +- core/sni-3.3.md | 34 ------------------- {documentation => deprecated}/sasl-dh-aes.md | 7 +++- .../sasl-dh-blowfish.md | 7 +++- extensions/tls-3.1.md => deprecated/tls.md | 7 ++-- example-spec.md | 3 ++ ...ccount-notify-3.1.md => account-notify.md} | 7 +++- .../{account-tag-3.2.md => account-tag.md} | 7 +++- .../{away-notify-3.1.md => away-notify.md} | 7 +++- extensions/{batch-3.2.md => batch.md} | 7 ++-- .../capability-negotiation.md | 4 ++- extensions/channel-rename.md | 3 +- extensions/chathistory.md | 5 +-- extensions/{chghost-3.2.md => chghost.md} | 4 ++- .../{echo-message-3.2.md => echo-message.md} | 5 ++- ...{extended-join-3.1.md => extended-join.md} | 7 +++- ...{invite-notify-3.2.md => invite-notify.md} | 5 ++- extensions/labeled-response.md | 3 +- extensions/message-ids.md | 2 +- extensions/message-tags.md | 2 +- core/monitor-3.2.md => extensions/monitor.md | 5 ++- .../{multi-prefix-3.1.md => multi-prefix.md} | 7 ++-- extensions/multiline.md | 2 +- extensions/sasl-3.1.md | 3 ++ extensions/sasl-3.2.md | 3 +- .../{server-time-3.2.md => server-time.md} | 7 +++- extensions/setname.md | 2 +- extensions/standard-replies.md | 4 ++- extensions/sts.md | 2 +- ...t-in-names-3.2.md => userhost-in-names.md} | 7 +++- extensions/webirc.md | 15 ++++++-- 36 files changed, 130 insertions(+), 76 deletions(-) rename extensions/batch/chathistory-3.3.md => batches/chathistory.md (94%) rename extensions/batch/netsplit-3.2.md => batches/netsplit.md (92%) delete mode 100644 core/sni-3.3.md rename {documentation => deprecated}/sasl-dh-aes.md (94%) rename {documentation => deprecated}/sasl-dh-blowfish.md (94%) rename extensions/tls-3.1.md => deprecated/tls.md (96%) rename extensions/{account-notify-3.1.md => account-notify.md} (95%) rename extensions/{account-tag-3.2.md => account-tag.md} (95%) rename extensions/{away-notify-3.1.md => away-notify.md} (93%) rename extensions/{batch-3.2.md => batch.md} (97%) rename {core => extensions}/capability-negotiation.md (99%) rename extensions/{chghost-3.2.md => chghost.md} (97%) rename extensions/{echo-message-3.2.md => echo-message.md} (96%) rename extensions/{extended-join-3.1.md => extended-join.md} (91%) rename extensions/{invite-notify-3.2.md => invite-notify.md} (93%) rename core/monitor-3.2.md => extensions/monitor.md (98%) rename extensions/{multi-prefix-3.1.md => multi-prefix.md} (86%) rename extensions/{server-time-3.2.md => server-time.md} (94%) rename extensions/{userhost-in-names-3.2.md => userhost-in-names.md} (87%) diff --git a/extensions/batch/chathistory-3.3.md b/batches/chathistory.md similarity index 94% rename from extensions/batch/chathistory-3.3.md rename to batches/chathistory.md index e6e104b30..d28311dc6 100644 --- a/extensions/batch/chathistory-3.3.md +++ b/batches/chathistory.md @@ -1,13 +1,16 @@ --- -title: IRCv3 chathistory Batch Type +title: "`chathistory` Batch Type" layout: spec +redirect_from: + - /specs/extensions/batch/chathistory-3.3.html copyrights: - name: "Sadie Powell" period: "2015" email: "sadie@witchery.services" --- -## `chathistory` Batch Type + +## Description This document describes the format of the `chathistory` batch type. diff --git a/extensions/batch/netsplit-3.2.md b/batches/netsplit.md similarity index 92% rename from extensions/batch/netsplit-3.2.md rename to batches/netsplit.md index d2a00ae14..dd87de645 100644 --- a/extensions/batch/netsplit-3.2.md +++ b/batches/netsplit.md @@ -1,13 +1,16 @@ --- -title: IRCv3 netsplit and netjoin Batch Types +title: "`netsplit` and `netjoin` Batch Types" layout: spec +redirect_from: + - /specs/extensions/batch/netsplit-3.2.html copyrights: - name: "Alex Iadicicco" period: "2014" email: "http://github.com/aji" --- -## `netsplit` and `netjoin` Batch Types + +## Description This document describes the format of the `netsplit` and `netjoin` batch types. diff --git a/client-tags/react.md b/client-tags/react.md index 694dffa26..630f669e5 100644 --- a/client-tags/react.md +++ b/client-tags/react.md @@ -1,5 +1,5 @@ --- -title: React client tag +title: "`react` client tag" layout: spec work-in-progress: true copyrights: diff --git a/client-tags/reply.md b/client-tags/reply.md index 7b8b5fca5..3934e6435 100644 --- a/client-tags/reply.md +++ b/client-tags/reply.md @@ -1,5 +1,5 @@ --- -title: Reply client tag +title: "`reply` client tag" layout: spec work-in-progress: true copyrights: diff --git a/client-tags/typing.md b/client-tags/typing.md index 72b7ed930..b16c1dd24 100644 --- a/client-tags/typing.md +++ b/client-tags/typing.md @@ -1,5 +1,5 @@ --- -title: IRCv3 typing client tag +title: "`typing` client tag" layout: spec copyrights: - @@ -10,6 +10,7 @@ copyrights: period: "2020" email: "james@irccloud.com" --- + ## Introduction This specification defines a client-only message tag to indicate the current typing status of users in channels and private messages. diff --git a/core/metadata-3.2.md b/core/metadata-3.2.md index fb28ca362..151bbda95 100644 --- a/core/metadata-3.2.md +++ b/core/metadata-3.2.md @@ -1,5 +1,5 @@ --- -title: IRCv3.2 Metadata +title: Metadata layout: spec deprecated: true copyrights: diff --git a/core/sni-3.3.md b/core/sni-3.3.md deleted file mode 100644 index 70b2ab393..000000000 --- a/core/sni-3.3.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Server Name Indication -layout: spec -work-in-progress: true -copyrights: - - - name: "Attila Molnar" - period: "2015" - email: "attilamolnar@hush.com" ---- - -## Description - -Server Name Indication (SNI) is a mechanism in the TLS protocol in which a TLS -client indicates at the beginning of the handshake which hostname it is -connecting to. - -## Uses - -Servers can use this information to choose which certificate to send to the -client. This is needed because servers may have more than one certificate, for -example a server may have two certificates: one for irc.example.net and another -one for server.example.net. In this scenario, when a client connects the server -has no way of knowing which certificate to offer because it does not know at the -time of the handshake which hostname the client is using. - -SNI fixes this problem by sending the hostname to the server early, so the -server can choose the certificate corresponding to the hostname the client is -using. - -## Requirements - -Clients MUST use SNI when connecting to servers via TLS. (This implies that a TLS -version capable of SNI, i.e. at least TLS 1.1, is required.) diff --git a/documentation/sasl-dh-aes.md b/deprecated/sasl-dh-aes.md similarity index 94% rename from documentation/sasl-dh-aes.md rename to deprecated/sasl-dh-aes.md index 2fdd0003a..25a36137a 100644 --- a/documentation/sasl-dh-aes.md +++ b/deprecated/sasl-dh-aes.md @@ -1,6 +1,8 @@ --- -title: IRCv3 SASL DH-AES Authentication Mechanism +title: SASL DH-AES Authentication Mechanism layout: spec +redirect_from: + - /specs/documentation/sasl-dh-aes.html deprecated: "This mechanism has been deemed unsafe and has been deprecated. Please refer to the [SASL Mechanisms](http://ircv3.net/docs/sasl-mechs.html) page for mechanisms that the IRCv3 WG now recommends." copyrights: - @@ -8,6 +10,9 @@ copyrights: period: "2013-2015" email: "grawity@gmail.com" --- + +## Description + This specification documents the `DH-AES` SASL mechanism currently implemented by some IRC clients and services. diff --git a/documentation/sasl-dh-blowfish.md b/deprecated/sasl-dh-blowfish.md similarity index 94% rename from documentation/sasl-dh-blowfish.md rename to deprecated/sasl-dh-blowfish.md index 19fd1f881..d2bae0909 100644 --- a/documentation/sasl-dh-blowfish.md +++ b/deprecated/sasl-dh-blowfish.md @@ -1,6 +1,8 @@ --- -title: IRCv3 SASL DH-BLOWFISH Authentication Mechanism +title: SASL DH-BLOWFISH Authentication Mechanism layout: spec +redirect_from: + - /specs/documentation/sasl-dh-blowfish.html deprecated: "This mechanism has been deemed unsafe and has been deprecated. Please refer to the [SASL Mechanisms](http://ircv3.net/docs/sasl-mechs.html) page for mechanisms that the IRCv3 WG now recommends." copyrights: - @@ -8,6 +10,9 @@ copyrights: period: "2013-2015" email: "grawity@gmail.com" --- + +## Description + This specification documents the `DH-BLOWFISH` SASL mechanism currently implemented by various IRC clients and services. diff --git a/extensions/tls-3.1.md b/deprecated/tls.md similarity index 96% rename from extensions/tls-3.1.md rename to deprecated/tls.md index 3e6fad168..0897470b0 100644 --- a/extensions/tls-3.1.md +++ b/deprecated/tls.md @@ -1,6 +1,8 @@ --- -title: IRCv3.1 `tls` Extension +title: "`tls` Extension" layout: spec +redirect_from: + - /specs/extensions/tls-3.1.html deprecated: true copyrights: - @@ -12,7 +14,8 @@ copyrights: period: "2014" email: "attilamolnar@hush.com" --- -## The tls Client Capability + +## Description The tls client capability indicates that the server supports the STARTTLS command. diff --git a/example-spec.md b/example-spec.md index 980128d80..bbe6cd003 100644 --- a/example-spec.md +++ b/example-spec.md @@ -67,6 +67,9 @@ If this spec is intended for a certain audience (say, mostly bouncers or private rather than normal public networks), feel free to mention it here. This gives spec readers an opportunity to think about whether this feature is right for their software and networks. +If there is only a single section in your spec, this should be named "Description" instead of "Introduction". +You may also choose to separate out your 'motivation' and 'introduction/description' into two separate sections. + ## Architecture diff --git a/extensions/account-notify-3.1.md b/extensions/account-notify.md similarity index 95% rename from extensions/account-notify-3.1.md rename to extensions/account-notify.md index 5249c186a..8f244a4b0 100644 --- a/extensions/account-notify-3.1.md +++ b/extensions/account-notify.md @@ -1,12 +1,17 @@ --- -title: IRCv3.1 `account-notify` Extension +title: "`account-notify` Extension" layout: spec +redirect_from: + - /specs/extensions/account-notify-3.1.html copyrights: - name: "William Pitcock" period: "2010" email: "nenolod@dereferenced.org" --- + +## Description + The account-notify client capability allows a client to be notified when a client's account name changes. This capability MUST be referred to as 'account-notify' at capability negotiation time. diff --git a/extensions/account-tag-3.2.md b/extensions/account-tag.md similarity index 95% rename from extensions/account-tag-3.2.md rename to extensions/account-tag.md index d5012a1a8..09e6bbaa7 100644 --- a/extensions/account-tag-3.2.md +++ b/extensions/account-tag.md @@ -1,12 +1,17 @@ --- -title: IRCv3.2 `account-tag` Extension +title: "`account-tag` Extension" layout: spec +redirect_from: + - /specs/extensions/account-tag-3.2.html copyrights: - name: "Mantas Mikulėnas" period: "2013-2015" email: "grawity@gmail.com" --- + +## Description + The `account-tag` capability causes the server to add a [message tag][] containing the command sender's services account to commands sent to the client that has requested this capability. It supersedes the `identify-msg` extension. diff --git a/extensions/away-notify-3.1.md b/extensions/away-notify.md similarity index 93% rename from extensions/away-notify-3.1.md rename to extensions/away-notify.md index 9940e55af..51dbf5489 100644 --- a/extensions/away-notify-3.1.md +++ b/extensions/away-notify.md @@ -1,12 +1,17 @@ --- -title: IRCv3.1 `away-notify` Extension +title: "`away-notify` Extension" layout: spec +redirect_from: + - /specs/extensions/away-notify-3.1.html copyrights: - name: "Keith Buck" period: "2012" email: "mr_flea@esper.net" --- + +## Description + The away-notify client capability allows a client to specify that it would like to be notified when users are marked/unmarked as away. This capability is referred to as 'away-notify' at capability negotiation diff --git a/extensions/batch-3.2.md b/extensions/batch.md similarity index 97% rename from extensions/batch-3.2.md rename to extensions/batch.md index 7448b433f..7345e103b 100644 --- a/extensions/batch-3.2.md +++ b/extensions/batch.md @@ -1,6 +1,8 @@ --- -title: IRCv3.2 `batch` Extension +title: "`batch` Extension" layout: spec +redirect_from: + - /specs/extensions/batch-3.2.html copyrights: - name: "William Pitcock" @@ -15,7 +17,8 @@ copyrights: period: "2014" email: "alexey-irc@asokolov.org" --- -## The `batch` client capability + +## Introduction This extension describes a capability which causes a new verb to be sent to clients when the IRC server wishes to designate that a series of events are diff --git a/core/capability-negotiation.md b/extensions/capability-negotiation.md similarity index 99% rename from core/capability-negotiation.md rename to extensions/capability-negotiation.md index 833f1f2b8..8e8f9abd9 100644 --- a/core/capability-negotiation.md +++ b/extensions/capability-negotiation.md @@ -1,7 +1,8 @@ --- -title: IRCv3 Client Capability Negotiation +title: Client Capability Negotiation layout: spec redirect_from: + - /specs/core/capability-negotiation.html - /specs/core/capability-negotiation-3.1.html - /specs/core/capability-negotiation-3.2.html - /specs/extensions/cap-notify-3.2.html @@ -35,6 +36,7 @@ copyrights: period: "2017-2019" email: "james@irccloud.com" --- + ## What Client Capability Negotiation attempts to solve Client Capability Negotiation allows IRC clients and servers to negotiate new features diff --git a/extensions/channel-rename.md b/extensions/channel-rename.md index 51c86dc29..54860167b 100644 --- a/extensions/channel-rename.md +++ b/extensions/channel-rename.md @@ -1,5 +1,5 @@ --- -title: Channel renaming +title: Channel Renaming layout: spec work-in-progress: true copyrights: @@ -23,7 +23,6 @@ The final version of the specification will use an unprefixed capability name. ## Introduction - This specification introduces a method of natively renaming a channel without closing it down and redirecting to a new one. This allows properties such as access and ban lists to be maintained, and avoids issues with client-side logging where history is split across multiple channel names. ## Architecture diff --git a/extensions/chathistory.md b/extensions/chathistory.md index 9816514a4..a23829324 100644 --- a/extensions/chathistory.md +++ b/extensions/chathistory.md @@ -1,5 +1,5 @@ --- -title: IRCv3 chathistory extension +title: "`chathistory` Extension" layout: spec work-in-progress: true copyrights: @@ -15,6 +15,7 @@ copyrights: period: "2020" email: "slingamn@cs.stanford.edu" --- + ## Notes for implementing work-in-progress version This is a work-in-progress specification. @@ -23,7 +24,7 @@ Software implementing this work-in-progress specification MUST NOT use the unpre The `chathistory` batch type is already ratified and SHOULD be used unprefixed. -## Description +## Introduction This document describes the format of the `chathistory` extension. This enables clients to request messages that were previously sent if they are still available on the server. The server as mentioned in this document may refer to either an IRC server or an IRC bouncer. diff --git a/extensions/chghost-3.2.md b/extensions/chghost.md similarity index 97% rename from extensions/chghost-3.2.md rename to extensions/chghost.md index 9f636c40c..d93c96f09 100644 --- a/extensions/chghost-3.2.md +++ b/extensions/chghost.md @@ -1,6 +1,8 @@ --- -title: IRCv3.2 `chghost` Extension +title: "`chghost` Extension" layout: spec +redirect_from: + - /specs/extensions/chghost-3.2.html copyrights: - name: "Christine Dodrill" diff --git a/extensions/echo-message-3.2.md b/extensions/echo-message.md similarity index 96% rename from extensions/echo-message-3.2.md rename to extensions/echo-message.md index 1c6490fd5..63bb52d96 100644 --- a/extensions/echo-message-3.2.md +++ b/extensions/echo-message.md @@ -1,6 +1,8 @@ --- -title: IRCv3.2 `echo-message` Extension +title: "`echo-message` Extension" layout: spec +redirect_from: + - /specs/extensions/echo-message-3.2.html copyrights: - name: "Attila Molnar" @@ -11,6 +13,7 @@ copyrights: period: "2014" email: "jpnurmi@gmail.com" --- + ## Description This client capability MUST be named `echo-message`. diff --git a/extensions/extended-join-3.1.md b/extensions/extended-join.md similarity index 91% rename from extensions/extended-join-3.1.md rename to extensions/extended-join.md index 629720718..63b6820cc 100644 --- a/extensions/extended-join-3.1.md +++ b/extensions/extended-join.md @@ -1,12 +1,17 @@ --- -title: IRCv3.1 `extended-join` Extension +title: "`extended-join` Extension" layout: spec +redirect_from: + - /specs/extensions/extended-join-3.1.html copyrights: - name: "Kiyoshi Aman" period: "2011" email: "kiyoshi.aman@gmail.com" --- + +## Description + The extended-join capability extends the JOIN message to include the account name, or a placeholder if the user hasn't identified with services. This capability MUST be referred to as 'extended-join' at diff --git a/extensions/invite-notify-3.2.md b/extensions/invite-notify.md similarity index 93% rename from extensions/invite-notify-3.2.md rename to extensions/invite-notify.md index cefb61f56..12bb5b9b4 100644 --- a/extensions/invite-notify-3.2.md +++ b/extensions/invite-notify.md @@ -1,6 +1,8 @@ --- -title: IRCv3.2 `invite-notify` Extension +title: "`invite-notify` Extension" layout: spec +redirect_from: + - /specs/extensions/invite-notify-3.2.html copyrights: - name: "Adam" @@ -11,6 +13,7 @@ copyrights: period: "2014" email: "attilamolnar@hush.com" --- + ## Description The `invite-notify` client capability allows a client to specify that it diff --git a/extensions/labeled-response.md b/extensions/labeled-response.md index bea1b0e4c..002e5f40b 100644 --- a/extensions/labeled-response.md +++ b/extensions/labeled-response.md @@ -1,5 +1,5 @@ --- -title: Labeled responses +title: Labeled Responses layout: spec copyrights: - @@ -11,6 +11,7 @@ copyrights: period: "2016-2020" email: "james@irccloud.com" --- + ## Introduction This specification adds a new message tag sent by clients and repeated by servers to correlate responses with a specific request. diff --git a/extensions/message-ids.md b/extensions/message-ids.md index 4702d47d4..a1a5aa9b5 100644 --- a/extensions/message-ids.md +++ b/extensions/message-ids.md @@ -1,5 +1,5 @@ --- -title: IRCv3 Message IDs +title: Message IDs layout: spec copyrights: - diff --git a/extensions/message-tags.md b/extensions/message-tags.md index 33fb1215e..d3e112165 100644 --- a/extensions/message-tags.md +++ b/extensions/message-tags.md @@ -1,5 +1,5 @@ --- -title: IRCv3 Message Tags +title: Message Tags layout: spec redirect_from: - /specs/core/message-tags-3.3.html diff --git a/core/monitor-3.2.md b/extensions/monitor.md similarity index 98% rename from core/monitor-3.2.md rename to extensions/monitor.md index ad87a56af..f06290fcb 100644 --- a/core/monitor-3.2.md +++ b/extensions/monitor.md @@ -1,6 +1,8 @@ --- -title: IRCv3.2 Monitor +title: Monitor layout: spec +redirect_from: + - /specs/core/monitor-3.2.html copyrights: - name: "Lee Hardy" @@ -15,6 +17,7 @@ copyrights: period: "2015" email: "nenolod@dereferenced.org" --- + A protocol for notification of when clients become online/offline ## Introduction diff --git a/extensions/multi-prefix-3.1.md b/extensions/multi-prefix.md similarity index 86% rename from extensions/multi-prefix-3.1.md rename to extensions/multi-prefix.md index 5ca3c40bf..04ad730d3 100644 --- a/extensions/multi-prefix-3.1.md +++ b/extensions/multi-prefix.md @@ -1,13 +1,16 @@ --- -title: IRCv3.1 `multi-prefix` Extension +title: "`multi-prefix` Extension" layout: spec +redirect_from: + - /specs/extensions/multi-prefix-3.1.html copyrights: - name: "William Pitcock" period: "2012" email: "nenolod@dereferenced.org" --- -## The multi-prefix Client Capability + +## Description When requested, the multi-prefix client capability will cause the IRC server to send all possible prefixes which apply to a user in NAMES and WHO output. diff --git a/extensions/multiline.md b/extensions/multiline.md index 035459300..7e554631a 100644 --- a/extensions/multiline.md +++ b/extensions/multiline.md @@ -1,5 +1,5 @@ --- -title: Multiline messages +title: Multiline Messages layout: spec work-in-progress: true copyrights: diff --git a/extensions/sasl-3.1.md b/extensions/sasl-3.1.md index 71d01ff78..5354e80e4 100644 --- a/extensions/sasl-3.1.md +++ b/extensions/sasl-3.1.md @@ -13,6 +13,9 @@ copyrights: period: "2009-2012" email: "nenolod@dereferenced.org" --- + +## Introduction + This document describes the client protocol for SASL authentication, as implemented in Charybdis and Atheme. diff --git a/extensions/sasl-3.2.md b/extensions/sasl-3.2.md index 7b300231b..bfa09314f 100644 --- a/extensions/sasl-3.2.md +++ b/extensions/sasl-3.2.md @@ -13,7 +13,8 @@ copyrights: period: "2015" email: "nenolod@dereferenced.org" --- -## Description + +## Introduction This document describes how [SASL authentication](sasl-3.1.html) makes use of the diff --git a/extensions/server-time-3.2.md b/extensions/server-time.md similarity index 94% rename from extensions/server-time-3.2.md rename to extensions/server-time.md index 224b8dab7..6c8e7cfe8 100644 --- a/extensions/server-time-3.2.md +++ b/extensions/server-time.md @@ -1,6 +1,8 @@ --- -title: IRCv3.2 `server-time` Extension +title: "`server-time` Extension" layout: spec +redirect_from: + - /specs/extensions/server-time-3.2.html copyrights: - name: "Stéphan Kochen" @@ -19,6 +21,9 @@ copyrights: period: "2016" email: "james@irccloud.com" --- + +## Description + Clients indicate support for the extension by requesting a capability server-time as per the [IRC Client Capabilities Extension][cap]. CAP REQ :server-time diff --git a/extensions/setname.md b/extensions/setname.md index f6553f126..4c016c962 100644 --- a/extensions/setname.md +++ b/extensions/setname.md @@ -1,5 +1,5 @@ --- -title: IRCv3 `setname` Extension +title: "`setname` Extension" layout: spec copyrights: - diff --git a/extensions/standard-replies.md b/extensions/standard-replies.md index 9922364ee..ec5e03ab7 100644 --- a/extensions/standard-replies.md +++ b/extensions/standard-replies.md @@ -1,5 +1,5 @@ --- -title: "Standard Replies Extension" +title: Standard Replies layout: spec copyrights: - @@ -8,6 +8,8 @@ copyrights: email: "daniel@danieloaks.net" --- +## Introduction + This document specifies the standard `FAIL`, `WARN`, and `NOTE` messages, intended to provide a clean, consistent interface for sending general errors, warnings, and informational messages to clients. Implementers should not need to reserve new numerics for error, warning, or general informational messages, especially as numerics themselves and the mapping of numerics to names can be unclear or conflicting. The `FAIL` message indicates a complete failure to process a given command/function, or simply some error about the current session that clients should be aware of. diff --git a/extensions/sts.md b/extensions/sts.md index e895d3e78..01629a817 100644 --- a/extensions/sts.md +++ b/extensions/sts.md @@ -1,5 +1,5 @@ --- -title: IRCv3 Strict Transport Security +title: Strict Transport Security layout: spec redirect_from: - /specs/core/sts-3.3.html diff --git a/extensions/userhost-in-names-3.2.md b/extensions/userhost-in-names.md similarity index 87% rename from extensions/userhost-in-names-3.2.md rename to extensions/userhost-in-names.md index 5ea7880ff..40876a0e1 100644 --- a/extensions/userhost-in-names-3.2.md +++ b/extensions/userhost-in-names.md @@ -1,12 +1,17 @@ --- -title: IRCv3.2 `userhost-in-names` Extension +title: "`userhost-in-names` Extension" layout: spec +redirect_from: + - /specs/extensions/userhost-in-names-3.2.html copyrights: - name: "Mantas Mikulėnas" period: "2013" email: "grawity@gmail.com" --- + +## Description + The `userhost-in-names` capability extends the NAMES reply messages (`RPL_NAMREPLY`) to contain the full hostmask (nick!user@host) of every user listed. diff --git a/extensions/webirc.md b/extensions/webirc.md index b23632984..2f142eede 100644 --- a/extensions/webirc.md +++ b/extensions/webirc.md @@ -1,5 +1,5 @@ --- -title: IRCv3 WebIRC extension +title: WebIRC Extension layout: spec copyrights: - @@ -10,13 +10,17 @@ copyrights: period: "2017" email: "prawnsalad@kiwiirc.com" --- -## Purpose + +## Motivation + This specification is intended to document the existing `WEBIRC` command that is already in use by multiple IRC servers and WebIRC gateways to provide a standard specification for implementation. This specification does not add any new features or changes, although new features, such as use of public-key cryptography instead of password authentication, can be submitted as extensions. -## Description +## Introduction + When a user connects through an indirect connection to the IRC server, the user's actual IP address and hostname are not visible. The `WEBIRC` command allows the WebIRC gateway to pass on the user's actual IP address and hostname to the IRC server. This information can be used by the network as if the user was connecting directly. ## Format + The `WEBIRC` command MUST be the first command sent from the WebIRC gateway to the IRC server and MUST be sent before capability negotiation. The `WEBIRC` command takes four or five parameters: `password `, `gateway`, `hostname`, `ip`, and `options`. @@ -31,6 +35,7 @@ If forward and reverse DNS do not match, the IP address SHOULD be sent as the `h Note: Previous implementations referred to the `gateway` field as `user`. This change is for documentation clarity only and maintains compatibility with all existing implementations. ### Options + The `options` parameter is a space-separated set of additional arguments, each argument having the form `[=]`. The option values are escaped using the same escaping method as [message tags values](../extensions/message-tags.html#escaping-values). It is acknowledged that some of the escaping rules are not strictly required, but the same escaping method is used for consistency. @@ -44,6 +49,7 @@ These options are defined and may be sent by clients while connecting: Servers MUST be able to handle options that don't currently have defined values gaining values in the future. For example, they MUST treat the options `secure` and `secure=examplevalue123` in exactly the same way. ### Examples + Generic format. WEBIRC password gateway hostname ip [:option1 option2...] @@ -69,11 +75,13 @@ Error from invalid password. ERROR :Invalid WebIRC password ## Use Cases + Webchat applications that proxy the connection to the IRC server are the primary intended use case. WebIRC allows network and channel operators to use available moderation and security tools to their full extent by exposing user IP addresses and hosts. Other use cases include bouncer services that wish to pass user information to the IRC server. ## Limitations + WebIRC requires that the both WebIRC gateway and IRC server be configured to accept the connection in advance. Specific recommendations are outlined below in the [Security Considerations](#security-considerations) section. ## Security Considerations @@ -82,4 +90,5 @@ WebIRC allows anyone with a valid password to successfully connect to the IRC se Because the possibility for hostname spoofing exists, IRC servers MAY attempt to further validate or resolve hostnames and match them to an IP address. It is the responsibility of IRC servers to verify the authenticity of connecting users and perform additional security checks as they see fit. To assist network operators and prevent abuse, IRC servers SHOULD show when a WebIRC connection is in use and SHOULD provide the original host when possible. This behavior is non-normative and implementation defined. ## Errata + A previous version of this specification did not include handling the occurrence of an IPv6 address beginning with a colon, which would break the message argument format.