imapkit 5.2.0 → 5.3.0

package/README.md

@@ -142,6 +142,21 @@ ImapKit follows these of the strategies that RFC 2180 (IMAP4 Multi-Accessed Mail
 
 By default the only account is user name `"testuser"` with password `"testpass"` (and access token `"testtoken"` for XOAUTH2 and OAUTHBEARER). The `users` option replaces the default account list, for example `{ "testuser": { "password": "testpass" }, "otheruser": { "password": "secret" } }`, and `server.control.addUser()` adds users at runtime (see [Control API](#control-api)). All users share the same mailbox tree.
 
+## OAuth 2.0 and OpenID Connect
+
+The `oauth` option (`--oauth-port`) starts a test identity provider, so a mail client can run its whole OAuth sign-in against ImapKit: the authorization code flow with PKCE, a consent page that needs no password, and tokens that log in to IMAP (XOAUTH2, OAUTHBEARER) and SMTP (AUTH XOAUTH2), expire on the server clock, refresh and can be revoked.
+
+```javascript
+const server = imapkit({
+    plugins: ['SASL-IR', 'XOAUTH2', 'OAUTHBEARER'],
+    users: { 'alice@example.com': { password: 'pw', displayName: 'Alice' }, 'denied@example.com': { password: 'pw', oauth: { consent: 'deny' } } },
+    oauth: { port: 8085 }
+});
+await server.start(1143); // discovery: http://127.0.0.1:8085/.well-known/openid-configuration
+```
+
+A consent policy decides every sign-in, from the first that has one: a queued decision (`control.queueOAuthDecision()`), the user that `login_hint` names, the client, the server default. `prompt` shows the consent page (pick an account, Allow or Deny), `approve` and `deny` redirect right away with a plain HTTP 302, so a test can follow the redirect without a browser, and an error object answers with that error. The clients `imapkit`, `imapkit-approve` and `imapkit-deny` are registered by default, with loopback redirect URIs on any port. The ID token's `email` claim is the user name, so use address-style user names for OAuth tests. The provider is strict like the IMAP side: PKCE S256 for public clients, single-use codes, exact redirect URIs, no unknown scopes. Token faults, forced expiry and revocation are in the control API and the REST API. See [OAuth 2.0 and OpenID Connect](https://imapkit.com/docs/guides/oauth).
+
 ## Status
 
 ### IMAP4rev1
@@ -480,7 +495,7 @@ The REST API controls the whole server, including the mail of every user, so it
 
 Requests and responses are JSON, and every POST needs `Content-Type: application/json`, also without a body (HTTP 415 otherwise). Errors are `{ "error": { "code", "message" } }` with HTTP status 404 for `NONEXISTENT`, 409 for `ALREADYEXISTS` and the response codes of a failed mailbox operation (`CANNOT`, `HASCHILDREN` ...), 400 for `INVALID`, 401 for a missing or wrong token, 404 `NOTFOUND` and 405 `METHOD` for an unknown route or method, 413 `TOOBIG` for a body over 64 MiB (and `addMessage` checks refused by APPENDLIMIT), 500 for a server error. A mailbox is its storage name (modified UTF-7) in the URL, URL encoded with a `/` in the name as `%2F` (`/v1/mailboxes/Work%2FProjects`). Message sources are base64 in responses (`"encoding": "base64"`), a request sends `raw` as text or as base64 with `"encoding": "base64"`. `GET /v1/openapi.json` describes every endpoint.
 
-`GET /v1/events` streams the [events](#events) as [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html) (`event: <type>` with JSON `data`), so a test in another language can wait for "the client selected INBOX" or "a script rule fired" without polling. `?types=session,command` chooses the types (`session`, `command`, `mailbox`, `append`, `expunge`, `flags`, `acl`, `script`, `reset`, and `trace`, which is only sent when asked for, with base64 `data`), mailboxes are paths, messages UIDs and sessions numbers in the data:
+`GET /v1/events` streams the [events](#events) as [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html) (`event: <type>` with JSON `data`), so a test in another language can wait for "the client selected INBOX" or "a script rule fired" without polling. `?types=session,command` chooses the types (`session`, `command`, `mailbox`, `append`, `expunge`, `flags`, `acl`, `script`, `reset`, `oauth`, and `trace`, which is only sent when asked for, with base64 `data`), mailboxes are paths, messages UIDs and sessions numbers in the data:
 
 ```bash
 curl -N 'http://127.0.0.1:8143/v1/events?types=session'
@@ -488,26 +503,27 @@ curl -N 'http://127.0.0.1:8143/v1/events?types=session'
 # data: {"type":"select","session":{"session":1,"user":"testuser","state":"Selected","mailbox":"INBOX",...}}
 ```
 
-| Endpoint                                                                                             | Control API                                                                            |
-| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
-| `GET /v1/snapshot`                                                                                   | `snapshot()`                                                                           |
-| `POST /v1/reset`                                                                                     | `reset()`                                                                              |
-| `POST /v1/shutdown` (`{ graceful }`)                                                                 | `shutdown()`                                                                           |
-| `GET /v1/sessions`, `DELETE /v1/sessions/{n}` (`{ text, reset }`)                                    | `sessions()`, `disconnect()`                                                           |
-| `POST /v1/sessions/{n}/inject` (`{ data, encoding }`)                                                | `inject()`                                                                             |
-| `GET`, `POST /v1/users`, `PUT`, `DELETE /v1/users/{name}`                                            | `listUsers()`, `addUser()`, `updateUser()`, `deleteUser()`                             |
-| `GET`, `POST /v1/mailboxes`, `GET`, `DELETE /v1/mailboxes/{path}`                                    | `listMailboxes()`, `createMailbox()`, `getMailbox()`, `deleteMailbox()`                |
-| `POST /v1/mailboxes/{path}/rename` (`{ newPath }`)                                                   | `renameMailbox()`                                                                      |
-| `PUT`, `DELETE /v1/mailboxes/{path}/subscription`                                                    | `subscribe()`, `unsubscribe()`                                                         |
-| `POST /v1/mailboxes/{path}/uidvalidity`                                                              | `resetUidValidity()`                                                                   |
-| `GET /v1/mailboxes/{path}/messages` (`?uids=1,2&raw=true`), `POST` (`{ raw, flags }`)                | `listMessages()`, `addMessage()`                                                       |
-| `GET`, `DELETE /v1/mailboxes/{path}/messages/{uid}`                                                  | `getMessage()`, `expungeMessages()`                                                    |
-| `POST /v1/mailboxes/{path}/messages/flags`, `.../expunge`, `.../copy`, `.../move`                    | `setFlags()`, `expungeMessages()`, `copyMessages()`, `moveMessages()`                  |
-| `GET /v1/mailboxes/{path}/acl`, `PUT`, `DELETE /v1/mailboxes/{path}/acl/{identifier}` (`{ rights }`) | `getAcl()`, `setAcl()`, `deleteAcl()` (ACL)                                            |
-| `GET`, `PUT /v1/quota`                                                                               | `getQuota()`, `setQuota()` (QUOTA)                                                     |
-| `GET`, `PUT /v1/metadata`, `GET`, `PUT /v1/mailboxes/{path}/metadata`                                | `getMetadata()`, `setMetadata()` (METADATA)                                            |
-| `PUT /v1/mailboxes/{path}/special-use` (`{ specialUse }`)                                            | `setSpecialUse()` (SPECIAL-USE)                                                        |
-| `GET`, `POST`, `DELETE /v1/script/rules`, `DELETE /v1/script/rules/{id}`                             | [script rules](#scripted-faults) in their JSON form, so runtime faults need no restart |
+| Endpoint                                                                                                                       | Control API                                                                            |
+| ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
+| `GET /v1/snapshot`                                                                                                             | `snapshot()`                                                                           |
+| `POST /v1/reset`                                                                                                               | `reset()`                                                                              |
+| `POST /v1/shutdown` (`{ graceful }`)                                                                                           | `shutdown()`                                                                           |
+| `GET /v1/sessions`, `DELETE /v1/sessions/{n}` (`{ text, reset }`)                                                              | `sessions()`, `disconnect()`                                                           |
+| `POST /v1/sessions/{n}/inject` (`{ data, encoding }`)                                                                          | `inject()`                                                                             |
+| `GET`, `POST /v1/users`, `PUT`, `DELETE /v1/users/{name}`                                                                      | `listUsers()`, `addUser()`, `updateUser()`, `deleteUser()`                             |
+| `GET`, `POST /v1/mailboxes`, `GET`, `DELETE /v1/mailboxes/{path}`                                                              | `listMailboxes()`, `createMailbox()`, `getMailbox()`, `deleteMailbox()`                |
+| `POST /v1/mailboxes/{path}/rename` (`{ newPath }`)                                                                             | `renameMailbox()`                                                                      |
+| `PUT`, `DELETE /v1/mailboxes/{path}/subscription`                                                                              | `subscribe()`, `unsubscribe()`                                                         |
+| `POST /v1/mailboxes/{path}/uidvalidity`                                                                                        | `resetUidValidity()`                                                                   |
+| `GET /v1/mailboxes/{path}/messages` (`?uids=1,2&raw=true`), `POST` (`{ raw, flags }`)                                          | `listMessages()`, `addMessage()`                                                       |
+| `GET`, `DELETE /v1/mailboxes/{path}/messages/{uid}`                                                                            | `getMessage()`, `expungeMessages()`                                                    |
+| `POST /v1/mailboxes/{path}/messages/flags`, `.../expunge`, `.../copy`, `.../move`                                              | `setFlags()`, `expungeMessages()`, `copyMessages()`, `moveMessages()`                  |
+| `GET /v1/mailboxes/{path}/acl`, `PUT`, `DELETE /v1/mailboxes/{path}/acl/{identifier}` (`{ rights }`)                           | `getAcl()`, `setAcl()`, `deleteAcl()` (ACL)                                            |
+| `GET`, `PUT /v1/quota`                                                                                                         | `getQuota()`, `setQuota()` (QUOTA)                                                     |
+| `GET`, `PUT /v1/metadata`, `GET`, `PUT /v1/mailboxes/{path}/metadata`                                                          | `getMetadata()`, `setMetadata()` (METADATA)                                            |
+| `PUT /v1/mailboxes/{path}/special-use` (`{ specialUse }`)                                                                      | `setSpecialUse()` (SPECIAL-USE)                                                        |
+| `GET`, `POST`, `DELETE /v1/script/rules`, `DELETE /v1/script/rules/{id}`                                                       | [script rules](#scripted-faults) in their JSON form, so runtime faults need no restart |
+| `GET /v1/oauth`, `/v1/oauth/clients`, `/v1/oauth/consent`, `/v1/oauth/decisions`, `/v1/oauth/token-faults`, `/v1/oauth/tokens` | the [OAuth provider](#oauth-20-and-openid-connect), with the `oauth` option            |
 
 ## Scripted faults
 

package/bin/help.txt

@@ -31,6 +31,15 @@ Usage: imapkit [OPTS]
   --rest-host=<address>    Address of the REST API, defaults to 127.0.0.1.
                            Any other than a loopback address needs a token
   --rest-token=<token>     Bearer token that REST requests must send
+  --oauth-port=<port>      Starts the OAuth 2.0 / OpenID Connect provider:
+                           tokens for IMAP (XOAUTH2, OAUTHBEARER) and SMTP
+                           (AUTH XOAUTH2), no passwords, see "OAuth" below
+  --oauth-host=<address>   Address of the OAuth provider, 127.0.0.1 default
+  --oauth-consent=<policy> What a sign-in does: prompt (consent page, the
+                           default), approve or deny (redirect right away)
+  --oauth-secure=true      Serves the OAuth provider over HTTPS with the
+                           bundled localhost certificate
+  --oauth-issuer=<url>     Public base URL of the OAuth provider (a tunnel)
   --quirk=<name>           Makes the server behave like a known real server
                            (james-fetchgroup, james-late-fetch,
                            yahoo-quoted-sections, m365-throttle, no-uidplus,
@@ -42,7 +51,9 @@ The options can also be set with environment variables: IMAPKIT_PORT,
 IMAPKIT_SECURE, IMAPKIT_DEBUG, IMAPKIT_STORAGE, IMAPKIT_CONFIG,
 IMAPKIT_SCRIPT, IMAPKIT_PLUGINS (comma separated), IMAPKIT_TLS_PORT,
 IMAPKIT_SMTPPORT, IMAPKIT_REST_PORT, IMAPKIT_REST_HOST, IMAPKIT_REST_TOKEN,
-IMAPKIT_QUIRKS and IMAPKIT_SCRIPT_SEED.
+IMAPKIT_OAUTH_PORT, IMAPKIT_OAUTH_HOST, IMAPKIT_OAUTH_CONSENT,
+IMAPKIT_OAUTH_SECURE, IMAPKIT_OAUTH_ISSUER, IMAPKIT_QUIRKS and
+IMAPKIT_SCRIPT_SEED.
 
 NB! If port or smtpPort values are below 1024 you most probably need to
 use sudo or run the command with administrator rights.
@@ -80,6 +91,19 @@ Configuration file takes the following structure
     }
 }
 
+OAuth
+-----
+
+--oauth-port starts a test identity provider. Its discovery document is
+at <issuer>/.well-known/openid-configuration. Three public clients are
+registered (loopback redirect URIs on any port, PKCE S256 required):
+"imapkit" follows the default consent policy, "imapkit-approve" always
+approves and "imapkit-deny" always denies. The consent page needs no
+password: pick an account and click Allow or Deny. The email claim is
+the user name, so use address-style user names for OAuth tests. Load
+SASL-IR with XOAUTH2 or OAUTHBEARER to log in to IMAP with the tokens.
+More clients, scopes and policies go into "oauth" of the --config file.
+
 Scripted faults
 ---------------
 

package/bin/imapkit.js

@@ -27,6 +27,11 @@ const { values: argv } = parseArgs({
         'rest-port': { type: 'string' },
         'rest-host': { type: 'string' },
         'rest-token': { type: 'string' },
+        'oauth-port': { type: 'string' },
+        'oauth-host': { type: 'string' },
+        'oauth-consent': { type: 'string' },
+        'oauth-secure': { type: 'boolean' },
+        'oauth-issuer': { type: 'string' },
         quirk: { type: 'string', multiple: true },
         'script-seed': { type: 'string' }
     }
@@ -53,6 +58,11 @@ const tlsPort = argv['tls-port'] || process.env.IMAPKIT_TLS_PORT;
 const restPort = argv['rest-port'] || process.env.IMAPKIT_REST_PORT;
 const restHost = argv['rest-host'] || process.env.IMAPKIT_REST_HOST;
 const restToken = argv['rest-token'] || process.env.IMAPKIT_REST_TOKEN;
+const oauthPort = argv['oauth-port'] || process.env.IMAPKIT_OAUTH_PORT;
+const oauthHost = argv['oauth-host'] || process.env.IMAPKIT_OAUTH_HOST;
+const oauthConsent = argv['oauth-consent'] || process.env.IMAPKIT_OAUTH_CONSENT;
+const oauthSecure = isTrue(argv['oauth-secure'] || process.env.IMAPKIT_OAUTH_SECURE);
+const oauthIssuer = argv['oauth-issuer'] || process.env.IMAPKIT_OAUTH_ISSUER;
 const quirksList = listOption(argv.quirk || process.env.IMAPKIT_QUIRKS);
 const scriptSeed = argv['script-seed'] || process.env.IMAPKIT_SCRIPT_SEED;
 const pluginsList = listOption(argv.plugin || process.env.IMAPKIT_PLUGINS).map(plugin => plugin.toUpperCase());
@@ -123,6 +133,18 @@ if (argv.help) {
     if (restPort) {
         config.rest = { port: Number(restPort), host: restHost, token: restToken };
     }
+    if (oauthPort) {
+        // the other oauth options (clients, scopes ...) come from the --config file
+        config.oauth = Object.assign({}, config.oauth, { port: Number(oauthPort) });
+        for (const [key, value] of Object.entries({ host: oauthHost, consent: oauthConsent, issuer: oauthIssuer })) {
+            if (value) {
+                config.oauth[key] = value;
+            }
+        }
+        if (oauthSecure) {
+            config.oauth.secure = true;
+        }
+    }
     if (smtpPort) {
         // smtp-server is an optional dependency, start() loads it only when SMTP is enabled
         config.smtp = { port: Number(smtpPort) };
@@ -146,6 +168,19 @@ if (argv.help) {
             if (server.restServer) {
                 console.log('REST API listening on %s:%s', (config.rest && config.rest.host) || '127.0.0.1', server.restServer.address().port);
             }
+            if (server.oauthServer) {
+                const clients = server.control.listOAuthClients().map(client => client.id);
+                const consent = server.oauth.consent;
+                console.log(
+                    'OAuth provider listening on %s (clients: %s; default consent: %s)',
+                    server.oauth.issuer,
+                    clients.join(', '),
+                    typeof consent === 'string' ? consent : 'error ' + consent.error
+                );
+                if (!server.capabilities['AUTH=XOAUTH2'] && !server.capabilities['AUTH=OAUTHBEARER']) {
+                    console.log('Load the XOAUTH2 or OAUTHBEARER plugin (with SASL-IR) to log in to IMAP with its tokens');
+                }
+            }
             if (server.smtpServer) {
                 console.log('Incoming SMTP server up and running on port %s', server.smtpServer.server.address().port);
             }