@openemail/sdk 0.0.5 → 0.0.7

package/README.md

@@ -44,9 +44,9 @@
 
 ## Intro to the Npm Package
 
-The official TypeScript client for the OpenEmail API. A method for every one of the 178 endpoints, 259 in all once the paging and upload helpers are counted, typed end to end, with zero dependencies. It runs on Node 20+, Bun, Deno and Cloudflare Workers, and ships as ESM and CommonJS.
+The official TypeScript client for the OpenEmail API. A method for every one of the 197 endpoints, 282 in all once the paging and upload helpers are counted, typed end to end, with zero dependencies. It runs on Node 20+, Bun, Deno and Cloudflare Workers, and ships as ESM and CommonJS.
 
-It carries a workspace API key, so it belongs on a server. The one exception is disposable inboxes, which need no key and work in a browser.
+It carries a workspace API key or an OAuth access token, so it belongs on a server or in a tool that runs on your own machine. The one exception is disposable inboxes, which need no credential and work in a browser.
 
 ### Installing
 ```bash
@@ -158,6 +158,46 @@ const { items } = await temp.listMessages(inbox.id, { inboxToken: inbox.token })
 
 `create` needs no credential and is the only call that returns the inbox token, so keep it.
 
+### OAuth access tokens
+An app a person connected to OpenEmail with OAuth, such as a command line tool or an agent, holds an access token rather than an API key. Pass it as `accessToken`:
+
+```typescript
+import { OpenEmail } from '@openemail/sdk'
+
+export const openemail = new OpenEmail({
+    accessToken: async () => session.freshAccessToken()
+})
+```
+
+`accessToken` takes the token itself, or a function that returns it. The function runs before every request, so renew the token there when it is close to expiring and the client never has to be rebuilt. Pass `apiKey` or `accessToken`, not both. `createOpenEmail()` reads `OPENEMAIL_ACCESS_TOKEN` when you pass neither and `OPENEMAIL_API_KEY` is not set. `me.get()` answers `object: 'oauth_token'` for a token, with the connected app's `clientId` and `expiresAt`, when the person's approval of the app runs out.
+
+A token acts for a person, so before a sensitive change, such as deleting a domain or changing a webhook, it is asked for the same verification code the web app asks for. The request fails with `isStepUpRequired`. Ask for a code, check it, then replay the request:
+
+```typescript
+import { OpenEmailApiError } from '@openemail/sdk'
+
+try {
+    await openemail.domains.delete(domain.id)
+}
+
+catch (error) {
+    if (!(error instanceof OpenEmailApiError) || !error.isStepUpRequired) throw error
+
+    const challenge = await openemail.security.beginStepUp()
+
+    const code = await ask(challenge.method === 'email'
+        ? `Enter the code we emailed to ${challenge.sentTo}`
+        : 'Enter the code from your authenticator app, or a backup code')
+
+    await openemail.security.verifyStepUp({ code })
+    await openemail.domains.delete(domain.id)
+}
+```
+
+An emailed code works for 10 minutes, and `beginStepUp({ resend: true })` sends a fresh one. The email shows the name the app registered with, its client ID and the change it asked to make, so the person can check who is asking before they hand the code over. Once a code is verified the app is not asked again for 60 minutes, for any of the 14 changes that ask for one, through the REST API or through the MCP tools that make the same changes. `verifyStepUp` lists them. `security.stepUpStatus()` says whether it is verified right now. An app that cannot ask for a code, such as an MCP connector, can instead be allowed by the person for 60 minutes with Allow changes for 60 minutes in Account settings, Connected apps, on the website. API keys are never asked for a code.
+
+Each app has its own budget of codes, so another app never uses it up, and neither does the web app, which keeps its own 10 an hour. An app can ask for 5 codes an hour and 20 in 24 hours, then gets 429 `step_up_throttled`. A code allows 5 tries, and after the fifth wrong one a plain `beginStepUp()` starts a fresh challenge. Ten wrong codes in 24 hours pause verification for the app, and 20 in 24 hours from all of a person's apps together pause it for every app they connected. Either way both calls answer 429 `step_up_locked`, with the time the pause ends in the message. Codes entered in the web app count toward neither pause, and the person can still verify there.
+
 ### Configuring
 Pass an options object instead of the bare key when the defaults are not right:
 
@@ -176,7 +216,18 @@ export const openemail = new OpenEmail({
 
 `createOpenEmail(options)` is the same constructor with one difference: anything you leave out is read from the environment. The shipped `openemail` takes the same options through `init(options)`, called once at startup.
 
-`baseUrl` also comes from `OPENEMAIL_BASE_URL`, for a server you run yourself. Reads are retried on 408 and 5xx with backoff. A 429 is retried only when it carries a `Retry-After`, and any wait longer than a minute throws instead of sleeping. Writes that cannot safely repeat are not retried. Every method outside `tempMail` takes `{ signal, apiKey }` as its last argument, so one process can serve several workspaces with one client. The `tempMail` methods take `{ signal, inboxToken }` instead.
+`baseUrl` also comes from `OPENEMAIL_BASE_URL`. Use an `https:` origin: the client refuses to send an API key, an access token or an inbox token over plain `http:`, and throws before the request leaves, unless the server is on this machine at `localhost`, a `127.x.x.x` address or `::1`. A `baseUrl` on `0.0.0.0` throws when the client is built, since that is the address a server listens on: use `127.0.0.1` with the same port. Reads are retried on 408 and 5xx with backoff. A 429 is retried only when it carries a `Retry-After`, and any wait longer than a minute throws instead of sleeping. Writes that cannot safely repeat are not retried. Every method outside `tempMail` takes `{ signal, apiKey }` as its last argument, so one process can serve several workspaces with one client. The `tempMail` methods take `{ signal, inboxToken }` instead.
+
+An endpoint no method wraps yet is one `raw.request()` away, with the client's credential, base URL, timeout and retry policy applied:
+
+```typescript
+const result = await openemail.raw.request('/something-new', {
+    method: 'POST',
+    body: { name: 'Invoices' }
+})
+```
+
+The path must begin with a single `/`. Anything else, such as `//host/x` or `@host/x`, throws before a request is sent, and so does a path whose finished URL leaves the base URL's origin, so the credential it carries never reaches another host.
 
 When a newer version is on npm the client says so once on a TTY. `OPENEMAIL_DISABLE_UPDATE_NOTICE=1` or `{ disableUpdateNotice: true }` turns that off.
 

package/index.cjs

@@ -28,7 +28,7 @@ const BROADCAST_RECIPIENT_FILTERS = {
     UNSUBSCRIBED: 'unsubscribed'
 };
 
-var version = "0.0.5";
+var version = "0.0.7";
 
 const BUILD_BASE_URL = 'https://api.openemail.uk';
 
@@ -42,8 +42,8 @@ const DEFAULTS = {
 const BROWSER_REFUSAL = [
     'OpenEmail refused to start in a browser.',
     '',
-    '  This client carries a workspace API key that can send mail and read the mailbox. Anything',
-    '  you ship to a browser is readable by anyone who opens devtools.',
+    '  This client carries a workspace API key or an OAuth access token that can send mail and read',
+    '  the mailbox. Anything you ship to a browser is readable by anyone who opens devtools.',
     '',
     '  Call it from a server, a serverless function or a script instead. Disposable inboxes are',
     '  the exception: createTempMail() needs no API key and is safe to use in a browser.',
@@ -53,6 +53,7 @@ const BROWSER_REFUSAL = [
 ].join('\n');
 const ENV_VARS = {
     API_KEY: 'OPENEMAIL_API_KEY',
+    ACCESS_TOKEN: 'OPENEMAIL_ACCESS_TOKEN',
     BASE_URL: 'OPENEMAIL_BASE_URL'
 };
 const API_KEY_PREFIXES = {
@@ -63,10 +64,22 @@ const API_KEY_MODES = {
     LIVE: 'live',
     TEST: 'test'
 };
+const ACCESS_TOKEN_RULES = {
+    RESERVED_PREFIX: 'oe_',
+    MAX_LENGTH: 512
+};
+const CREDENTIAL_KINDS = {
+    API_KEY: 'apiKey',
+    OAUTH: 'oauth'
+};
 const CLIENT_MESSAGES = {
     API_KEY_REQUIRED: `An OpenEmail API key is required. Pass { apiKey } or set ${ENV_VARS.API_KEY}. Create one in OpenEmail under Settings, API keys.`,
-    API_KEY_SHAPE: 'is not an OpenEmail API key. The API accepts only keys beginning "oe_live_" or "oe_test_", so a session cookie, a session token or a key for another service is refused.',
-    BASE_URL_SHAPE: 'is not a usable base URL. Pass an origin such as "https://api.openemail.uk", or the http origin of a server you run yourself.',
+    CREDENTIAL_REQUIRED: `An OpenEmail API key or OAuth access token is required. Pass { apiKey } or { accessToken }, or set ${ENV_VARS.API_KEY} or ${ENV_VARS.ACCESS_TOKEN}. Create a key in OpenEmail under Settings, API keys.`,
+    CREDENTIAL_CONFLICT: 'Pass { apiKey } or { accessToken }, not both. Every request carries one credential, so the client cannot tell which of the two you meant.',
+    API_KEY_SHAPE: 'is not an OpenEmail API key. The API accepts only keys beginning "oe_live_" or "oe_test_", so a session cookie, a session token or a key for another service is refused. Pass an OAuth access token as { accessToken } instead.',
+    ACCESS_TOKEN_SHAPE: `is not an OAuth access token. Pass the access token OpenEmail issued when the app was connected: a string of 1 to ${ACCESS_TOKEN_RULES.MAX_LENGTH} characters that does not begin "${ACCESS_TOKEN_RULES.RESERVED_PREFIX}". An API key goes in { apiKey } instead.`,
+    ACCESS_TOKEN_PROVIDED: 'The value the { accessToken } function resolved to',
+    BASE_URL_SHAPE: 'is not a usable base URL. Pass an https origin such as "https://api.openemail.uk". Plain http is for a server on this machine only, at localhost, a 127.x.x.x address or ::1, because the client never sends a credential over plain http to any other host.',
     NO_FETCH: 'No global fetch is available. Pass one as { fetch }, or run on Node 20+, Bun, Deno, Cloudflare Workers or a browser.',
     EMPTY_SEGMENT: 'An id must not be empty.',
     FILENAME_REQUIRED: 'A file name is required. Pass it as { filename }, the name the file is stored and downloaded under.',
@@ -556,6 +569,8 @@ const PATHS = {
     TRACKING_STATS: '/tracking/stats',
     CALENDAR_EVENTS: '/calendar/events',
     SETTINGS: '/settings',
+    SECURITY_STEP_UP: '/security/step-up',
+    SECURITY_STEP_UP_VERIFY: '/security/step-up/verify',
     ROLES: '/roles',
     ROLES_PERMISSIONS: '/roles/permissions',
     MEMBERS: '/members',
@@ -711,6 +726,20 @@ const API_SCOPES = {
     KEYS_MANAGE: 'keys:manage'
 };
 
+const STEP_UP_METHODS = {
+    EMAIL: 'email',
+    TOTP: 'totp'
+};
+const STEP_UP_ERROR_CODES = {
+    STEP_UP_REQUIRED: 'step_up_required',
+    STEP_UP_NOT_APPLICABLE: 'step_up_not_applicable',
+    STEP_UP_THROTTLED: 'step_up_throttled',
+    STEP_UP_UNDELIVERABLE: 'step_up_undeliverable',
+    STEP_UP_CODE_INVALID: 'step_up_code_invalid',
+    STEP_UP_CODE_EXPIRED: 'step_up_code_expired',
+    STEP_UP_LOCKED: 'step_up_locked'
+};
+
 const SUPPRESSION_REASONS = {
     BOUNCE: 'bounce',
     COMPLAINT: 'complaint',
@@ -783,7 +812,12 @@ const WEBHOOK_SIGNATURE_HEADERS = WEBHOOK_HEADERS;
 const CLIENT_REGISTRY_KEY = Symbol.for('openemail.sdk.client.v1');
 const CLIENT_REGISTRY = globalThis;
 
-const LOCAL_HOSTS = ['localhost', '127.0.0.1', '0.0.0.0', '::1'];
+const LOOPBACK_HOSTNAMES = ['localhost', '::1', '[::1]'];
+const LOOPBACK_IPV4_PATTERN = /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/;
+const LOOPBACK_IPV4_ADDRESS = '127.0.0.1';
+const LOOPBACK_IPV6_ADDRESS = '[::1]';
+const UNSPECIFIED_HOSTNAMES = ['0.0.0.0', '::', '[::]'];
+const LOCAL_HOSTS = [...LOOPBACK_HOSTNAMES, LOOPBACK_IPV4_ADDRESS, ...UNSPECIFIED_HOSTNAMES];
 const ENDPOINT_SCHEME_PATTERN = /^[a-z][a-z0-9+.-]*:\/\//i;
 
 const RETRYABLE_STATUSES = new Set(RETRY.STATUSES);
@@ -892,13 +926,36 @@ const RETRYABLE_METHODS = new Set(RETRY.METHODS);
     scopes: [API_SCOPES.WEBHOOKS_READ]});
 
 const IsApiKey = (value) => typeof value === 'string' && (value.startsWith(API_KEY_PREFIXES.LIVE) || value.startsWith(API_KEY_PREFIXES.TEST));
-const ModeOf = (apiKey) => apiKey.startsWith(API_KEY_PREFIXES.TEST) ? API_KEY_MODES.TEST : API_KEY_MODES.LIVE;
+const IsAccessToken = (value) => typeof value === 'string'
+    && value.length > 0
+    && value.length <= ACCESS_TOKEN_RULES.MAX_LENGTH
+    && !value.startsWith(ACCESS_TOKEN_RULES.RESERVED_PREFIX);
+const IsPresent = (value) => value !== undefined && value !== null && value !== '';
+const ModeOf = (apiKey) => apiKey?.startsWith(API_KEY_PREFIXES.TEST) ? API_KEY_MODES.TEST : API_KEY_MODES.LIVE;
 const AssertApiKey = (apiKey, where) => {
     if (!apiKey)
         throw new Error(CLIENT_MESSAGES.API_KEY_REQUIRED);
     if (!IsApiKey(apiKey))
         throw new Error(`${where} ${CLIENT_MESSAGES.API_KEY_SHAPE}`);
 };
+const AssertAccessToken = (accessToken, where) => {
+    if (typeof accessToken === 'function')
+        return;
+    if (!IsAccessToken(accessToken))
+        throw new Error(`${where} ${CLIENT_MESSAGES.ACCESS_TOKEN_SHAPE}`);
+};
+const AssertCredential = (apiKey, accessToken, required) => {
+    const withKey = IsPresent(apiKey);
+    const withToken = IsPresent(accessToken);
+    if (withKey && withToken)
+        throw new Error(CLIENT_MESSAGES.CREDENTIAL_CONFLICT);
+    if (withKey)
+        AssertApiKey(apiKey, '{ apiKey }');
+    else if (withToken)
+        AssertAccessToken(accessToken, '{ accessToken }');
+    else if (required)
+        throw new Error(CLIENT_MESSAGES.CREDENTIAL_REQUIRED);
+};
 
 const IsBrowser = () => {
     const scope = globalThis;
@@ -936,6 +993,9 @@ class OpenEmailApiError extends Error {
     get isScopeMissing() {
         return this.code === ERROR_CODES.INSUFFICIENT_SCOPE;
     }
+    get isStepUpRequired() {
+        return this.code === STEP_UP_ERROR_CODES.STEP_UP_REQUIRED;
+    }
     get isInvalidRequest() {
         return this.type === ERROR_TYPES.INVALID_REQUEST_ERROR;
     }
@@ -1035,8 +1095,25 @@ const Backoff = (attempt) => {
     return Math.round(ceiling * (0.5 + Math.random() * 0.5));
 };
 
-const BuildUrl = (baseUrl, path, query) => {
+const PATH_SHAPE = 'is not a usable request path. Pass a path on the API that begins with a single "/", such as "/threads". Anything else could send the request, and the credential it carries, to another host.';
+const OFF_ORIGIN = 'leaves the API origin, so the request was not sent. Pass a path on the API that begins with a single "/", such as "/threads".';
+const ApiUrl = (baseUrl, path) => {
+    if (typeof path !== 'string' || !path.startsWith('/') || path.startsWith('//') || path.startsWith('/\\')) {
+        throw new Error(`${JSON.stringify(path)} ${PATH_SHAPE}`);
+    }
     const url = `${baseUrl.replace(/\/+$/, '')}${path}`;
+    let origin = null;
+    try {
+        origin = new URL(url).origin;
+    }
+    catch { }
+    if (origin === null || origin !== new URL(baseUrl).origin)
+        throw new Error(`${JSON.stringify(path)} ${OFF_ORIGIN}`);
+    return url;
+};
+
+const BuildUrl = (baseUrl, path, query) => {
+    const url = ApiUrl(baseUrl, path);
     if (!query)
         return url;
     const params = new URLSearchParams();
@@ -1049,6 +1126,8 @@ const BuildUrl = (baseUrl, path, query) => {
     return serialized ? `${url}?${serialized}` : url;
 };
 
+const CleartextCredentialMessage = (baseUrl) => `Refused to send a credential to ${baseUrl} over plain http, where anyone on the network can read it. Use an https base URL. Plain http is accepted only for a server on this machine: localhost, a 127.x.x.x address or ::1.`;
+
 const Deadline = (timeoutMs, signal) => {
     const controller = new AbortController();
     let expired = false;
@@ -1087,6 +1166,23 @@ const IdempotencyKey = () => {
     return `${IDEMPOTENCY_KEY_PREFIX}${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 14)}`;
 };
 
+const IsLoopbackHost = (hostname) => {
+    const host = hostname.toLowerCase();
+    return LOOPBACK_HOSTNAMES.includes(host) || LOOPBACK_IPV4_PATTERN.test(host);
+};
+
+const IsSecureOrigin = (url) => {
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === 'https:' || (parsed.protocol === 'http:' && IsLoopbackHost(parsed.hostname));
+    }
+    catch {
+        return false;
+    }
+};
+
+const IsUnspecifiedHost = (hostname) => UNSPECIFIED_HOSTNAMES.includes(hostname.toLowerCase());
+
 const RetryAfter = (value) => {
     if (!value)
         return undefined;
@@ -1145,6 +1241,13 @@ const ToErrorProps = (response, body, rawText, retryAfterSeconds) => {
     };
 };
 
+const Substitute = (url) => {
+    const suggestion = new URL(url.href);
+    suggestion.hostname = url.hostname.startsWith('[') ? LOOPBACK_IPV6_ADDRESS : LOOPBACK_IPV4_ADDRESS;
+    return suggestion.href.replace(/\/+$/, '');
+};
+const UnspecifiedHostMessage = (baseUrl, url) => `${JSON.stringify(baseUrl)} names ${url.hostname}, an address a server listens on, not one to send requests to. For a server on this machine, use ${Substitute(url)}.`;
+
 const Describe = (error) => error instanceof Error ? error.message : String(error);
 const ParseJson = (text) => {
     if (!text)
@@ -1156,34 +1259,45 @@ const ParseJson = (text) => {
         return undefined;
     }
 };
-const ValidBaseUrl = (value) => {
-    const trimmed = value.trim().replace(/\/+$/, '');
+const ParseBaseUrl = (value) => {
     try {
-        const parsed = new URL(trimmed);
-        if (parsed.protocol === 'https:' || parsed.protocol === 'http:')
-            return trimmed;
+        const parsed = new URL(value);
+        return parsed.protocol === 'https:' || parsed.protocol === 'http:' ? parsed : undefined;
+    }
+    catch {
+        return undefined;
     }
-    catch { }
-    throw new Error(`${JSON.stringify(value)} ${CLIENT_MESSAGES.BASE_URL_SHAPE}`);
+};
+const ValidBaseUrl = (value) => {
+    const trimmed = value.trim().replace(/\/+$/, '');
+    const parsed = ParseBaseUrl(trimmed);
+    if (!parsed)
+        throw new Error(`${JSON.stringify(value)} ${CLIENT_MESSAGES.BASE_URL_SHAPE}`);
+    if (IsUnspecifiedHost(parsed.hostname))
+        throw new Error(UnspecifiedHostMessage(value, parsed));
+    return trimmed;
 };
 class Transport {
     #apiKey;
+    #accessToken;
     #inboxToken;
     baseUrl;
+    #secureOrigin;
     fetchImpl;
     maxRetries;
     timeoutMs;
     userAgent;
     headers;
     constructor(options) {
-        if (options.apiKey !== undefined)
-            AssertApiKey(options.apiKey, '{ apiKey }');
+        AssertCredential(options.apiKey, options.accessToken, false);
         const fetchImpl = options.fetch ?? globalThis.fetch?.bind(globalThis);
         if (!fetchImpl)
             throw new Error(CLIENT_MESSAGES.NO_FETCH);
-        this.#apiKey = options.apiKey;
+        this.#apiKey = IsPresent(options.apiKey) ? options.apiKey : undefined;
+        this.#accessToken = IsPresent(options.accessToken) ? options.accessToken : undefined;
         this.#inboxToken = options.inboxToken;
         this.baseUrl = ValidBaseUrl(options.baseUrl ?? DEFAULTS.BASE_URL);
+        this.#secureOrigin = IsSecureOrigin(this.baseUrl);
         this.fetchImpl = fetchImpl;
         this.maxRetries = Math.max(0, options.maxRetries ?? DEFAULTS.MAX_RETRIES);
         this.timeoutMs = options.timeoutMs ?? DEFAULTS.TIMEOUT_MS;
@@ -1195,7 +1309,7 @@ class Transport {
     async request(path, options = {}) {
         const method = (options.method ?? HTTP_METHODS.GET).toUpperCase();
         const url = BuildUrl(this.baseUrl, path, options.query);
-        const headers = this.headersFor(options);
+        const headers = await this.headersFor(options);
         const body = options.raw !== undefined
             ? options.raw
             : options.body === undefined ? undefined : JSON.stringify(options.body);
@@ -1227,7 +1341,16 @@ class Transport {
             throw new OpenEmailApiError(ToErrorProps(response, ParseJson(text), text, retryAfter));
         }
     }
-    headersFor(options) {
+    async resolveAccessToken() {
+        const source = this.#accessToken;
+        if (typeof source !== 'function')
+            return source;
+        const token = await source();
+        if (!IsAccessToken(token))
+            throw new Error(`${CLIENT_MESSAGES.ACCESS_TOKEN_PROVIDED} ${CLIENT_MESSAGES.ACCESS_TOKEN_SHAPE}`);
+        return token;
+    }
+    async headersFor(options) {
         const headers = {
             ...this.headers,
             [HEADER_KEYS.ACCEPT]: options.accept ?? CONTENT_TYPES.JSON
@@ -1241,7 +1364,10 @@ class Transport {
         if (options.anonymous !== true) {
             if (options.apiKey !== undefined)
                 AssertApiKey(options.apiKey, '{ apiKey } on this call');
-            const credential = options.inboxToken ?? options.apiKey ?? this.#inboxToken ?? this.#apiKey;
+            const direct = options.inboxToken ?? options.apiKey ?? this.#inboxToken ?? this.#apiKey;
+            if ((direct ?? this.#accessToken) && !this.#secureOrigin)
+                throw new Error(CleartextCredentialMessage(this.baseUrl));
+            const credential = direct ?? await this.resolveAccessToken();
             if (credential)
                 headers[HEADER_KEYS.AUTHORIZATION] = `Bearer ${credential}`;
         }
@@ -2299,6 +2425,22 @@ const Rules = (transport) => ({
     iterateRuns: (options = {}) => IteratePages(transport, PATHS.RULES_RUNS, CURSOR_STYLES.CURSOR, options, RunsQuery(options))
 });
 
+const Security = (transport) => ({
+    stepUpStatus: (options = {}) => transport.request(PATHS.SECURITY_STEP_UP, { signal: options.signal, apiKey: options.apiKey }),
+    beginStepUp: (body = {}, options = {}) => transport.request(PATHS.SECURITY_STEP_UP, {
+        method: HTTP_METHODS.POST,
+        body,
+        signal: options.signal,
+        apiKey: options.apiKey
+    }),
+    verifyStepUp: (body, options = {}) => transport.request(PATHS.SECURITY_STEP_UP_VERIFY, {
+        method: HTTP_METHODS.POST,
+        body,
+        signal: options.signal,
+        apiKey: options.apiKey
+    })
+});
+
 const Settings = (transport) => ({
     get: (options = {}) => transport.request(PATHS.SETTINGS, {
         query: { [QUERY_KEYS.ADDRESS]: options.address },
@@ -2687,6 +2829,7 @@ class OpenEmail {
     transport;
     mode;
     me;
+    security;
     keys;
     addresses;
     languages;
@@ -2713,12 +2856,13 @@ class OpenEmail {
     tempMail;
     constructor(configuration) {
         const options = typeof configuration === 'string' ? { apiKey: configuration } : configuration;
-        AssertApiKey(options.apiKey, '{ apiKey }');
+        AssertCredential(options.apiKey, options.accessToken, true);
         if (IsBrowser() && options.dangerouslyAllowBrowser !== true)
             throw new Error(BROWSER_REFUSAL);
         this.transport = new Transport(options);
         this.mode = ModeOf(options.apiKey);
         this.me = Me(this.transport);
+        this.security = Security(this.transport);
         this.keys = Keys(this.transport);
         this.addresses = Addresses(this.transport);
         this.languages = Languages(this.transport);
@@ -2760,6 +2904,19 @@ const FromEnvironment = (name) => {
     }
 };
 
+const IsLocalHost = (hostname) => {
+    const host = hostname.toLowerCase();
+    return LOCAL_HOSTS.includes(host) || LOOPBACK_IPV4_PATTERN.test(host);
+};
+
+const HostnameOf = (authority) => {
+    try {
+        return new URL(`http://${authority}`).hostname;
+    }
+    catch {
+        return '';
+    }
+};
 const NormaliseEndpoint = (value) => {
     if (!value)
         return undefined;
@@ -2768,15 +2925,18 @@ const NormaliseEndpoint = (value) => {
         return undefined;
     if (ENDPOINT_SCHEME_PATTERN.test(trimmed))
         return trimmed;
-    const host = trimmed.split(':')[0];
-    return `${LOCAL_HOSTS.includes(host) ? 'http' : 'https'}://${trimmed}`;
+    return `${IsLocalHost(HostnameOf(trimmed)) ? 'http' : 'https'}://${trimmed}`;
 };
 
 const CreateClient = (configuration = {}) => {
     const options = typeof configuration === 'string' ? { apiKey: configuration } : configuration;
+    const explicit = options.apiKey !== undefined || options.accessToken !== undefined;
+    const apiKey = explicit ? options.apiKey : FromEnvironment(ENV_VARS.API_KEY);
+    const accessToken = explicit || apiKey !== undefined ? options.accessToken : FromEnvironment(ENV_VARS.ACCESS_TOKEN);
     return new OpenEmail({
         ...options,
-        apiKey: options.apiKey ?? FromEnvironment(ENV_VARS.API_KEY),
+        apiKey,
+        accessToken,
         baseUrl: NormaliseEndpoint(options.baseUrl ?? FromEnvironment(ENV_VARS.BASE_URL))
     });
 };
@@ -2784,6 +2944,7 @@ const CreateClient = (configuration = {}) => {
 const CreateTempMail = (options = {}) => TempMail(new Transport({
     ...options,
     apiKey: undefined,
+    accessToken: undefined,
     baseUrl: NormaliseEndpoint(options.baseUrl ?? FromEnvironment(ENV_VARS.BASE_URL))
 }));
 
@@ -2911,6 +3072,7 @@ const createTempMail = CreateTempMail;
 const verifyWebhookSignature = VerifyWebhookSignature;
 const toBase64 = ToBase64;
 const isApiKey = IsApiKey;
+const isAccessToken = IsAccessToken;
 const isSealed = IsSealed;
 const resolveLanguage = ResolveLanguage;
 const languageByCode = LanguageByCode;
@@ -2923,6 +3085,7 @@ exports.BROADCAST_STATUSES = BROADCAST_STATUSES;
 exports.CONTACT_BLOCK_LISTS = CONTACT_BLOCK_LISTS;
 exports.CONTACT_PHOTO_TYPES = CONTACT_PHOTO_TYPES;
 exports.CONTACT_THREAD_SORTS = CONTACT_THREAD_SORTS;
+exports.CREDENTIAL_KINDS = CREDENTIAL_KINDS;
 exports.DOMAIN_DMARC_STAGES = DOMAIN_DMARC_STAGES;
 exports.DOMAIN_RECORD_STATUSES = DOMAIN_RECORD_STATUSES;
 exports.ERROR_TYPES = ERROR_TYPES;
@@ -2944,6 +3107,8 @@ exports.PROVIDER_IMPORT_STATUSES = PROVIDER_IMPORT_STATUSES;
 exports.RULE_ACTIONS = RULE_ACTIONS;
 exports.RULE_FIELDS = RULE_FIELDS;
 exports.RULE_OPERATORS = RULE_OPERATORS;
+exports.STEP_UP_ERROR_CODES = STEP_UP_ERROR_CODES;
+exports.STEP_UP_METHODS = STEP_UP_METHODS;
 exports.SUPPRESSION_REASONS = SUPPRESSION_REASONS;
 exports.THREAD_SORTS = THREAD_SORTS;
 exports.VERSION = VERSION;
@@ -2956,6 +3121,7 @@ exports.createTempMail = createTempMail;
 exports.default = OpenEmail;
 exports.getClient = getClient;
 exports.init = init;
+exports.isAccessToken = isAccessToken;
 exports.isApiKey = isApiKey;
 exports.isRtlLanguage = isRtlLanguage;
 exports.isSealed = isSealed;