@wtfalch/email 0.3.0 → 0.4.1

package/dist/mailbox/client.d.ts

@@ -31,13 +31,11 @@ export type MailClientOptions = {
     /** Use a different account than the session's primary one. */
     accountId?: string;
 };
-/**
- * A connection to one JMAP account.
- *
- * Every other module in this package takes one of these. It owns the session
- * document, the account id, and the `jmap-jam` client the wire calls go
- * through; `jmap-jam` itself is not part of this package's public surface.
- */
+/** Passed to every `jmap-jam` call, whose `fetchInit` is spread over the
+ *  request it builds. */
+export declare const JAM_FETCH: {
+    fetchInit: RequestInit;
+};
 export declare class MailClient {
     #private;
     constructor(options: MailClientOptions);

package/dist/mailbox/client.js

@@ -1,5 +1,5 @@
 import { JamClient } from 'jmap-jam';
-import { MailError, guard, toMailError } from "./errors.js";
+import { MailError, guard } from "./errors.js";
 import { expandTemplate } from "./uri.js";
 export const MAIL_CAPABILITY = 'urn:ietf:params:jmap:mail';
 export const SUBMISSION_CAPABILITY = 'urn:ietf:params:jmap:submission';
@@ -16,6 +16,26 @@ function looksLikeSession(value) {
  * document, the account id, and the `jmap-jam` client the wire calls go
  * through; `jmap-jam` itself is not part of this package's public surface.
  */
+/**
+ * Never let the browser answer an authentication challenge for us.
+ *
+ * Every request here carries its own `Authorization` header. If one is
+ * refused, Stalwart answers with both `WWW-Authenticate: Bearer` and
+ * `WWW-Authenticate: Basic`, and a browser that is allowed to use
+ * credentials honours the second by opening its native password prompt —
+ * a modal that hides whatever the application was about to say about the
+ * refusal. `omit` declines that on our behalf: the 401 comes back as an
+ * ordinary response and the application gets to explain it.
+ *
+ * Outside a browser this is inert.
+ */
+const NO_BROWSER_CREDENTIALS = { credentials: 'omit' };
+/** Passed to every `jmap-jam` call, whose `fetchInit` is spread over the
+ *  request it builds. */
+export const JAM_FETCH = { fetchInit: NO_BROWSER_CREDENTIALS };
+/** Handed to `JamClient`'s constructor so its eager session request resolves
+ *  in-process instead of going to the server. See `#open`. */
+const NO_SESSION_URL = 'data:application/json,{}';
 export class MailClient {
     #sessionUrl;
     #wantedAccountId;
@@ -60,37 +80,34 @@ export class MailClient {
     async #open() {
         const authorization = this.#authorization;
         const isBearer = authorization.startsWith('Bearer ');
-        // `JamClient` can only build a `Bearer` header from the string it is
-        // given, so a credential that is not a bearer token (an app password,
-        // which Stalwart takes as Basic) needs the header replaced afterwards.
-        // The constructor has already fired its own session request by then, so
-        // that path reads the session here and discards what the constructor
-        // fetched; the bearer path, which is what the product uses, costs one
-        // request as usual.
+        // `JamClient`'s constructor fires a session request of its own, and we
+        // want neither the request nor its result. It calls `.json()` without
+        // looking at the status, so a refusal arrives as an unreadable parse
+        // error — and, worse, it is a plain same-origin fetch, so a 401 carrying
+        // `WWW-Authenticate: Basic` makes the browser put up its own password
+        // prompt. To a person that is indistinguishable from being asked to sign
+        // in again, on the right domain, when in fact they are already signed in
+        // and the token is the problem.
+        //
+        // So point the constructor at a `data:` URL, which resolves in-process
+        // and never touches the network, and read the session ourselves with the
+        // status checked. `jam.session` is overwritten with that document, and
+        // it is the document — not the URL — that carries `apiUrl`, so nothing
+        // downstream notices.
         const jam = new JamClient({
-            sessionUrl: this.#sessionUrl,
+            sessionUrl: NO_SESSION_URL,
             bearerToken: isBearer ? authorization.slice('Bearer '.length) : '',
         });
-        let doc;
-        if (isBearer) {
-            let loaded;
-            try {
-                loaded = await jam.session;
-            }
-            catch (cause) {
-                // `JamClient.loadSession` calls `.json()` without checking the
-                // status, so a 401 with an HTML body arrives here as a parse error.
-                throw await this.#sessionFailure(authorization, cause);
-            }
-            if (!looksLikeSession(loaded))
-                throw await this.#sessionFailure(authorization, loaded);
-            doc = loaded;
-        }
-        else {
+        // Nothing ever reads the promise the constructor made, and in Node an
+        // unobserved rejection takes the process down. Say so explicitly.
+        void jam.session.catch(() => { });
+        // `JamClient` can only build a `Bearer` header from the string it is
+        // given, so a credential that is not a bearer token — an app password,
+        // which Stalwart takes as Basic — needs the header replaced.
+        if (!isBearer)
             jam.authHeader = authorization;
-            doc = await this.#fetchSession(authorization);
-            jam.session = Promise.resolve(doc);
-        }
+        const doc = await this.#fetchSession(authorization);
+        jam.session = Promise.resolve(doc);
         const accountId = this.#wantedAccountId ?? doc.primaryAccounts?.[MAIL_CAPABILITY];
         if (!accountId) {
             throw new MailError(`the session document names no primary account for ${MAIL_CAPABILITY}; the server may not offer JMAP Mail to this login`, { operation: 'client.connect' });
@@ -110,6 +127,7 @@ export class MailClient {
             response = await fetch(this.#sessionUrl, {
                 headers: { Authorization: authorization, Accept: 'application/json' },
                 cache: 'no-cache',
+                ...NO_BROWSER_CREDENTIALS,
             });
         }
         catch (cause) {
@@ -134,18 +152,6 @@ export class MailClient {
         }
         return parsed;
     }
-    /** Turn a failed or unrecognisable session read into an error that says
-     *  what happened, by asking again with the status checked. */
-    async #sessionFailure(authorization, cause) {
-        try {
-            await this.#fetchSession(authorization);
-        }
-        catch (error) {
-            return toMailError(error, 'client.connect');
-        }
-        // The second read succeeded, so the first was a transient failure.
-        return toMailError(cause, 'client.connect');
-    }
     /** The signed-in person and the account being read. */
     async session() {
         const { doc, accountId } = await this.connect();
@@ -185,6 +191,7 @@ export class MailClient {
         return guard('client.upload', async () => {
             const result = await jam.uploadBlob(accountId, body, {
                 headers: { Authorization: this.#authorization, 'Content-Type': type },
+                ...NO_BROWSER_CREDENTIALS,
             });
             return { blobId: result.blobId, type: result.type, size: result.size };
         });

package/dist/mailbox/identities.d.ts

@@ -1,4 +1,4 @@
-import type { MailClient } from './client.ts';
+import { type MailClient } from './client.ts';
 import type { MailIdentity } from './types.ts';
 /** Every address this account may send as. */
 export declare function identities(client: MailClient): Promise<readonly MailIdentity[]>;

package/dist/mailbox/identities.js

@@ -1,9 +1,10 @@
+import { JAM_FETCH } from "./client.js";
 import { guard } from "./errors.js";
 /** Every address this account may send as. */
 export async function identities(client) {
     const { jam, accountId } = await client.connect();
     return guard('identities', async () => {
-        const [result] = await jam.api.Identity.get({ accountId });
+        const [result] = await jam.api.Identity.get({ accountId }, JAM_FETCH);
         return result.list.map((identity) => ({
             id: identity.id,
             name: identity.name ?? '',

package/dist/mailbox/mailboxes.d.ts

@@ -1,4 +1,4 @@
-import type { MailClient } from './client.ts';
+import { type MailClient } from './client.ts';
 import type { MailboxNode, MailboxRole } from './types.ts';
 /** A mailbox as the server returns it, before the tree is built. */
 export type FlatMailbox = {

package/dist/mailbox/mailboxes.js

@@ -1,3 +1,4 @@
+import { JAM_FETCH } from "./client.js";
 import { guard } from "./errors.js";
 /** RFC 8621 §2: order by `sortOrder`, and break ties by name. */
 function compare(a, b) {
@@ -101,7 +102,7 @@ export async function mailboxes(client) {
         const [result] = await jam.api.Mailbox.get({
             accountId,
             properties: MAILBOX_PROPERTIES,
-        });
+        }, JAM_FETCH);
         return buildTree(result.list);
     });
 }

package/dist/mailbox/submit.d.ts

@@ -1,4 +1,4 @@
-import type { MailClient } from './client.ts';
+import { type MailClient } from './client.ts';
 import type { Draft, EmailAddress, MailIdentity, MailboxNode, Sent } from './types.ts';
 /** The JMAP `Email` object a draft becomes. Exported so the shape can be
  *  asserted without a server. */

package/dist/mailbox/submit.js

@@ -1,3 +1,4 @@
+import { JAM_FETCH } from "./client.js";
 import { MailError, guard } from "./errors.js";
 import { identities } from "./identities.js";
 import { findRole, mailboxes } from "./mailboxes.js";
@@ -119,7 +120,7 @@ export async function send(client, draft, options = {}) {
         const [created] = await jam.api.Email.set({
             accountId,
             create: { draft: draftToEmail(draft, from, drafts.id) },
-        });
+        }, JAM_FETCH);
         const email = created.created?.draft;
         if (!email)
             failed('draft', created.notCreated);
@@ -137,7 +138,7 @@ export async function send(client, draft, options = {}) {
         // declare the mail capability as well as submission. jmap-jam derives
         // capabilities from the method names alone and would send only
         // submission and core.
-        { using: ['urn:ietf:params:jmap:mail'] });
+        { using: ['urn:ietf:params:jmap:mail'], ...JAM_FETCH });
         const submission = submitted.created?.submission;
         if (!submission)
             failed('submission', submitted.notCreated);

package/dist/mailbox/thread.d.ts

@@ -1,4 +1,4 @@
-import type { MailClient } from './client.ts';
+import { type MailClient } from './client.ts';
 import type { EmailAddress, Message, ThreadDetail } from './types.ts';
 /** A body part as `Email/get` returns it. */
 type BodyPart = {

package/dist/mailbox/thread.js

@@ -1,3 +1,4 @@
+import { JAM_FETCH } from "./client.js";
 import { MailError, guard } from "./errors.js";
 import { expandTemplate } from "./uri.js";
 const MESSAGE_PROPERTIES = [
@@ -125,7 +126,7 @@ export async function thread(client, threadId, options = {}) {
                 maxBodyValueBytes: options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES,
             });
             return { threads, messages };
-        });
+        }, JAM_FETCH);
         const found = results.threads.list;
         if (found.length === 0) {
             throw new MailError(`no thread ${threadId} in this account`, {

package/dist/mailbox/threads.d.ts

@@ -1,4 +1,4 @@
-import type { MailClient } from './client.ts';
+import { type MailClient } from './client.ts';
 import type { EmailAddress, MailFilter, MailSort, ThreadPage, ThreadSummary } from './types.ts';
 type SummaryEmail = {
     id: string;

package/dist/mailbox/threads.js

@@ -1,3 +1,4 @@
+import { JAM_FETCH } from "./client.js";
 import { guard } from "./errors.js";
 /** What a list row needs from the newest message in each thread. */
 const SUMMARY_PROPERTIES = [
@@ -121,7 +122,7 @@ export async function queryThreads(client, filter, options = {}) {
                 properties: MEMBER_PROPERTIES,
             });
             return { query, latest, threads, members };
-        });
+        }, JAM_FETCH);
         const query = results.query;
         const latest = results.latest;
         const threads = results.threads;

package/dist/postmaster/objects.d.ts

@@ -13,13 +13,32 @@ export interface MailObjectsInput {
     /**
      * The project's identity provider, once the mail applications are
      * registered there (docs/plans/email.md E3, phase-4.md slice 1): tokens
-     * from `issuerUrl` for `audience` (the ZITADEL project id) sign people in,
-     * on the domain and as the server's default. Absent, the domain keeps the
-     * internal directory and people have passwords.
+     * from `issuerUrl` for `audience` (the provider's project or resource id)
+     * sign people in, on the domain and as the server's default. Absent, the
+     * domain keeps the internal directory and people have passwords.
      */
     oidc?: {
         issuerUrl: string;
         audience: string;
+        /**
+         * Scopes an access token must carry, on top of the audience check.
+         *
+         * **Empty by default, and that is the safe default rather than a lax
+         * one.** Whether an access token carries a `scope` claim at all is the
+         * provider's choice: OIDC Core keeps the `profile` and `email` claims at
+         * the userinfo endpoint rather than in the token, and a provider that
+         * follows it mints access tokens with no `scope` claim to check. Stalwart
+         * reads this against the token's own claims when it validates a JWT
+         * offline, so a requirement here refuses *every* token such a provider
+         * issues — 401 on a credential that is real, current and for this
+         * audience, which is a dead end with nothing on screen to explain it.
+         *
+         * The audience is what binds a token to this server. Set this only for a
+         * provider known to put scopes in the token.
+         */
+        requireScopes?: Record<string, boolean>;
+        /** The claim holding the login name. The OIDC standard one by default. */
+        claimUsername?: string;
     };
 }
 /** A value that names an object created earlier in the same plan. */

package/dist/postmaster/objects.js

@@ -19,8 +19,8 @@ export function mailObjects(i) {
                     description: oidcDescription,
                     issuerUrl: i.oidc.issuerUrl,
                     requireAudience: i.oidc.audience,
-                    requireScopes: { openid: true, email: true },
-                    claimUsername: 'preferred_username',
+                    requireScopes: i.oidc.requireScopes ?? {},
+                    claimUsername: i.oidc.claimUsername ?? 'preferred_username',
                     usernameDomain: i.apex,
                     claimName: 'name',
                 },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/email",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "description": "The wtfalch estate: reading a mailbox over JMAP, and administering the Stalwart server it lives on. Two entries with no code in common.",
   "license": "MIT",
   "type": "module",
@@ -33,11 +33,14 @@
     },
     "./package.json": "./package.json"
   },
-  "files": [
-    "dist",
-    "LICENSE",
-    "README.md"
-  ],
+  "files": ["dist", "LICENSE", "README.md"],
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/mailbox/react/mail.css dist/mailbox/mail.css",
+    "prepack": "pnpm build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "record-fixtures": "node scripts/record-fixtures.mjs"
+  },
   "peerDependencies": {
     "@wtfalch/design": ">=0.4.0",
     "react": "^19.0.0",
@@ -72,20 +75,8 @@
   "engines": {
     "node": ">=22.0.0"
   },
-  "keywords": [
-    "jmap",
-    "email",
-    "mail",
-    "stalwart",
-    "rfc8621"
-  ],
+  "keywords": ["jmap", "email", "mail", "stalwart", "rfc8621"],
   "dependencies": {
     "jmap-jam": "^0.13.6"
-  },
-  "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json && cp src/mailbox/react/mail.css dist/mailbox/mail.css",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "record-fixtures": "node scripts/record-fixtures.mjs"
   }
-}
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 William Tallis Falch
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.