@wtfalch/email 0.6.1 → 0.7.0

package/dist/postmaster/apply.d.ts

@@ -1,3 +1,4 @@
+import type { PostmasterAudit } from './audit.js';
 import type { Instance } from './instance.js';
 export interface Applied {
     /** For the audit row's `targetType`. */
@@ -21,19 +22,19 @@ export declare function createMailbox(instance: Instance, input: {
     apex: string;
     description?: string | null;
     external: boolean;
-}): Promise<Applied>;
+}, audit?: PostmasterAudit): Promise<Applied>;
 export declare function addAlias(instance: Instance, input: {
     accountId: string;
     name: string;
     domainId: string;
     apex: string;
-}): Promise<Applied>;
+}, audit?: PostmasterAudit): Promise<Applied>;
 export declare function removeAlias(instance: Instance, input: {
     accountId: string;
     name: string;
     domainId: string;
     apex: string;
-}): Promise<Applied>;
+}, audit?: PostmasterAudit): Promise<Applied>;
 /**
  * Stop one app password working. The secret is never read, here or anywhere
  * else: the entry is identified by its id and the surviving entries go back
@@ -58,4 +59,4 @@ export declare function revokeAppPassword(instance: Instance, input: {
     credentialId: string;
     domainId: string;
     apex: string;
-}): Promise<Applied>;
+}, audit?: PostmasterAudit): Promise<Applied>;

package/dist/postmaster/apply.js

@@ -68,6 +68,21 @@ async function credentialIds(instance, accountId) {
         .map((c) => c.credentialId)
         .filter((id) => typeof id === 'string');
 }
+/** Records an applied write on the caller's audit, when it brought one. */
+async function recorded(audit, action, applied) {
+    if (audit) {
+        await audit.write({
+            action,
+            actor: audit.actor,
+            target: { type: applied.targetType, id: applied.targetId },
+            outcome: 'success',
+            before: applied.before,
+            after: applied.after,
+            request: audit.requestId ? { id: audit.requestId } : undefined,
+        });
+    }
+    return applied;
+}
 /**
  * The account as the server has it right now, confined to the domain the
  * caller resolved. A mismatched domain gets the same answer as a missing
@@ -104,7 +119,7 @@ function isOurOwnAccount(instance, account, apex) {
  * once would otherwise make two accounts, and the second would be the one
  * mail stopped arriving at.
  */
-export async function createMailbox(instance, input) {
+export async function createMailbox(instance, input, audit) {
     // Throws before any read when the request is one this app does not make
     // (a whole address, an empty name, a domain that keeps its own passwords).
     const value = newAccount(input);
@@ -115,40 +130,40 @@ export async function createMailbox(instance, input) {
         throw new MailWriteRefused(`${address} already has a mailbox`);
     }
     const id = await instance.client.create('Account', value);
-    return {
+    return recorded(audit, 'mail.mailbox_created', {
         targetType: 'mailbox',
         targetId: address,
         before: null,
         after: { id, name: local, domainId: input.domainId, description: input.description ?? null },
         message: `${address} now has a mailbox. They sign in through the issuer and make an app password for their mail client.`,
-    };
+    });
 }
-export async function addAlias(instance, input) {
+export async function addAlias(instance, input, audit) {
     const account = await readAccount(instance, input.accountId, input.domainId);
     const aliases = withAlias(account, { name: input.name, domainId: input.domainId });
     await instance.client.update('Account', account.id, { aliases });
     const added = Object.values(aliases).at(-1)?.name;
     const lost = missingSince(Object.values(aliases).map((a) => a.name), await aliasNames(instance, account.id));
-    return {
+    return recorded(audit, 'mail.alias_added', {
         targetType: 'mail_alias',
         targetId: `${added}@${input.apex}`,
         before: null,
         after: { alias: added, mailbox: `${account.name}@${input.apex}` },
         message: `${added}@${input.apex} is now delivered to ${account.name}@${input.apex}.${lost}`,
-    };
+    });
 }
-export async function removeAlias(instance, input) {
+export async function removeAlias(instance, input, audit) {
     const account = await readAccount(instance, input.accountId, input.domainId);
     const aliases = withoutAlias(account, input.name);
     await instance.client.update('Account', account.id, { aliases });
     const lost = missingSince(Object.values(aliases).map((a) => a.name), await aliasNames(instance, account.id));
-    return {
+    return recorded(audit, 'mail.alias_removed', {
         targetType: 'mail_alias',
         targetId: `${input.name}@${input.apex}`,
         before: { alias: input.name, mailbox: `${account.name}@${input.apex}` },
         after: null,
         message: `${input.name}@${input.apex} is no longer delivered anywhere. Mail sent to it will be rejected.${lost}`,
-    };
+    });
 }
 /**
  * Stop one app password working. The secret is never read, here or anywhere
@@ -169,7 +184,7 @@ export async function removeAlias(instance, input) {
  * limits here; its credentials belong to the bootstrap and to this app,
  * never to a mail client, and the web admin is where they are managed.
  */
-export async function revokeAppPassword(instance, input) {
+export async function revokeAppPassword(instance, input, audit) {
     const account = await readAccount(instance, input.accountId, input.domainId);
     if (isOurOwnAccount(instance, account, input.apex)) {
         throw new MailWriteRefused(`${instance.user} is the account this management app signs in as, and one of its app passwords is serving this request. Manage its credentials in the web admin.`);
@@ -181,11 +196,11 @@ export async function revokeAppPassword(instance, input) {
     const lost = missingSince(Object.values(credentials)
         .map((c) => c.credentialId)
         .filter((id) => typeof id === 'string'), await credentialIds(instance, account.id));
-    return {
+    return recorded(audit, 'mail.app_password_revoked', {
         targetType: 'mail_app_password',
         targetId: input.credentialId,
         before: { mailbox: `${account.name}@${input.apex}`, description },
         after: null,
         message: `That app password no longer works${description ? ` (${description})` : ''}. Any mail client using it will be asked to sign in again.${lost}`,
-    };
+    });
 }

package/dist/postmaster/audit.d.ts

@@ -0,0 +1,56 @@
+/**
+ * The events the postmaster's four writes record, when a caller hands them
+ * an audit. Declared here so a host can merge them into its ledger's
+ * vocabulary before it binds a writer to the `mail` namespace; the names sit
+ * in that namespace and nowhere else. `tenantVisible` is true throughout:
+ * these are an organisation's own facts about its own mail.
+ */
+export declare const POSTMASTER_AUDIT_EVENTS: {
+    readonly 'mail.mailbox_created': {
+        readonly tenantVisible: true;
+    };
+    readonly 'mail.alias_added': {
+        readonly tenantVisible: true;
+    };
+    readonly 'mail.alias_removed': {
+        readonly tenantVisible: true;
+    };
+    readonly 'mail.app_password_revoked': {
+        readonly tenantVisible: true;
+    };
+};
+export type PostmasterAuditAction = keyof typeof POSTMASTER_AUDIT_EVENTS;
+/** One write, as the host's writer receives it. `targetId` is an address or a credential id, never a secret. */
+export interface PostmasterAuditEvent {
+    readonly action: PostmasterAuditAction;
+    readonly actor: {
+        readonly id: string;
+        readonly display: string;
+    };
+    readonly target: {
+        readonly type: 'mailbox' | 'mail_alias' | 'mail_app_password';
+        readonly id: string;
+    };
+    readonly outcome: 'success';
+    readonly before: unknown;
+    readonly after: unknown;
+    readonly request?: {
+        readonly id?: string;
+    };
+}
+/**
+ * What a caller passes to a write: a writer the host bound to its ledger and
+ * to the `mail` namespace, the principal the host resolved for this request,
+ * and the request id that joins the row to the host's event log. The write
+ * records itself after the mail server has answered, so the row carries what
+ * actually happened; a write the server refused throws before this is
+ * called, and the caller records that refusal as it sees fit.
+ */
+export interface PostmasterAudit {
+    readonly write: (event: PostmasterAuditEvent) => Promise<void>;
+    readonly actor: {
+        readonly id: string;
+        readonly display: string;
+    };
+    readonly requestId?: string;
+}

package/dist/postmaster/audit.js

@@ -0,0 +1,13 @@
+/**
+ * The events the postmaster's four writes record, when a caller hands them
+ * an audit. Declared here so a host can merge them into its ledger's
+ * vocabulary before it binds a writer to the `mail` namespace; the names sit
+ * in that namespace and nowhere else. `tenantVisible` is true throughout:
+ * these are an organisation's own facts about its own mail.
+ */
+export const POSTMASTER_AUDIT_EVENTS = {
+    'mail.mailbox_created': { tenantVisible: true },
+    'mail.alias_added': { tenantVisible: true },
+    'mail.alias_removed': { tenantVisible: true },
+    'mail.app_password_revoked': { tenantVisible: true },
+};

package/dist/postmaster/index.d.ts

@@ -22,3 +22,4 @@ export { planMailboxes, withPassword } from './mailboxes.js';
 export { overview, pickDomain, type AccountView, type CredentialSummary, type DomainView, type Managed, type Overview, type OverviewInput, type PeopleView, type Person, type WireAccount, type WireAlias, type WireDomain, type WireSystemSettings, } from './overview.js';
 export { MailWriteRefused, newAccount, withAlias, withoutAlias, withoutAppPassword, } from './writes.js';
 export { addAlias, createMailbox, removeAlias, revokeAppPassword, type Applied, } from './apply.js';
+export { POSTMASTER_AUDIT_EVENTS, type PostmasterAudit, type PostmasterAuditAction, type PostmasterAuditEvent, } from './audit.js';

package/dist/postmaster/index.js

@@ -22,3 +22,4 @@ export { planMailboxes, withPassword } from './mailboxes.js';
 export { overview, pickDomain, } from './overview.js';
 export { MailWriteRefused, newAccount, withAlias, withoutAlias, withoutAppPassword, } from './writes.js';
 export { addAlias, createMailbox, removeAlias, revokeAppPassword, } from './apply.js';
+export { POSTMASTER_AUDIT_EVENTS, } from './audit.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wtfalch/email",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "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",