@upyo/smtp 0.5.0-dev.120 → 0.5.0-dev.136

package/README.md

@@ -22,6 +22,7 @@ Features
  -  TLS/SSL support
  -  Connection pooling
  -  Multiple authentication methods
+ -  OAuth 2.0 authentication (SASL XOAUTH2 and OAUTHBEARER)
  -  HTML and plain text email support
  -  File attachments (regular and inline)
  -  Multiple recipients (To, CC, BCC)
@@ -116,12 +117,46 @@ Configuration options
 
 ### `SmtpAuth`
 
+`SmtpAuth` is a discriminated union of three strategies.
+
+Username/password (`SmtpUserPassAuth`), discriminated by `pass`:
+
 | Option   | Type                               | Default   | Description |
 | -------- | ---------------------------------- | --------- | ----------- |
 | `user`   | `string`                           |           | Username    |
 | `pass`   | `string`                           |           | Password    |
 | `method` | `"plain" \| "login" \| "cram-md5"` | `"plain"` | Auth method |
 
+OAuth 2.0 access token (`SmtpOAuth2TokenAuth`), discriminated by `accessToken`:
+
+| Option        | Type                            | Default     | Description                                 |
+| ------------- | ------------------------------- | ----------- | ------------------------------------------- |
+| `user`        | `string`                        |             | User (email address)                        |
+| `accessToken` | `string \| OAuth2TokenProvider` |             | Access token, or a callback returning one   |
+| `method`      | `"xoauth2" \| "oauthbearer"`    | `"xoauth2"` | SASL mechanism (auto-detected when omitted) |
+
+OAuth 2.0 refresh-token flow (`SmtpOAuth2RefreshAuth`), discriminated by
+`refreshToken`:
+
+| Option          | Type                         | Default     | Description                                 |
+| --------------- | ---------------------------- | ----------- | ------------------------------------------- |
+| `user`          | `string`                     |             | User (email address)                        |
+| `clientId`      | `string`                     |             | OAuth 2.0 client identifier                 |
+| `clientSecret`  | `string`                     |             | OAuth 2.0 client secret (optional)          |
+| `refreshToken`  | `string`                     |             | OAuth 2.0 refresh token                     |
+| `tokenEndpoint` | `string`                     |             | Token endpoint URL                          |
+| `scope`         | `string`                     |             | Space-delimited scopes (optional)           |
+| `method`        | `"xoauth2" \| "oauthbearer"` | `"xoauth2"` | SASL mechanism (auto-detected when omitted) |
+
+The access token may be a static string or a callback (`OAuth2TokenProvider`)
+that returns a fresh token on demand—use the callback to integrate an OAuth
+client such as `google-auth-library` or `msal-node`.  With the refresh-token
+flow the transport runs the `refresh_token` grant itself, caching the access
+token across pooled connections.  See the
+[OAuth 2.0 authentication guide][oauth-guide] for details.
+
+[oauth-guide]: https://upyo.org/transports/smtp#oauth-2-0-authentication
+
 
 DKIM signing
 ------------
@@ -197,3 +232,40 @@ console.log(received[0].data); // Raw email content
 
 await server.stop();
 ~~~~
+
+### OAuth 2.0 end-to-end tests
+
+The OAuth 2.0 end-to-end tests run against a real provider (e.g. Gmail or
+Outlook) and are skipped unless the following environment variables are set:
+
+| Variable                | Description                            |
+| ----------------------- | -------------------------------------- |
+| `SMTP_OAUTH2_HOST`      | SMTP host (e.g. `smtp.gmail.com`)      |
+| `SMTP_OAUTH2_PORT`      | SMTP port (default `587`)              |
+| `SMTP_OAUTH2_SECURE`    | `true` for implicit TLS                |
+| `SMTP_OAUTH2_USER`      | User (email address)                   |
+| `SMTP_OAUTH2_MECHANISM` | `xoauth2` or `oauthbearer` (optional)  |
+| `SMTP_OAUTH2_FROM`      | Envelope sender (defaults to the user) |
+| `SMTP_OAUTH2_TO`        | Recipient (defaults to the user)       |
+
+Provide a token source as either a static access token:
+
+| Variable                   | Description        |
+| -------------------------- | ------------------ |
+| `SMTP_OAUTH2_ACCESS_TOKEN` | OAuth access token |
+
+or the refresh-token flow:
+
+| Variable                     | Description                       |
+| ---------------------------- | --------------------------------- |
+| `SMTP_OAUTH2_CLIENT_ID`      | OAuth client identifier           |
+| `SMTP_OAUTH2_CLIENT_SECRET`  | OAuth client secret (optional)    |
+| `SMTP_OAUTH2_REFRESH_TOKEN`  | OAuth refresh token               |
+| `SMTP_OAUTH2_TOKEN_ENDPOINT` | Token endpoint URL                |
+| `SMTP_OAUTH2_SCOPE`          | Space-delimited scopes (optional) |
+
+A Gmail access token can be minted with [google-auth-library], and an Outlook
+one with [msal-node].
+
+[google-auth-library]: https://github.com/googleapis/google-auth-library-nodejs
+[msal-node]: https://github.com/AzureAD/microsoft-authentication-library-for-js/tree/dev/lib/msal-node