@astram/guard 0.17.0 → 0.18.0

package/dist/messaging/email-delivery.d.ts

@@ -0,0 +1,42 @@
+import { type EmailProvider } from '@astram/core';
+import type { FrameworkSchemas } from '@astram/core';
+import type { Pool } from 'mariadb';
+import type { EmailSender } from '../auth/ports/email-sender.js';
+import { type EmailDeliveryConfig } from '../config/message-config.js';
+import { type MessageAuditWriter } from './message-dispatcher.js';
+/** `ShieldModule.forRoot({ emailSender })`. */
+export type EmailSenderOption = EmailSender | 'disabled' | 'env';
+/** What `@astram/messaging` must export for guard (spec P-2). */
+export interface MessagingModule {
+    createEmailProvider(config: EmailDeliveryConfig): Promise<EmailProvider>;
+}
+export interface EmailDelivery {
+    /** `null` ⇒ mail disabled. */
+    readonly provider: EmailProvider | null;
+    /** The per-send bound the dispatcher applies. */
+    readonly timeoutMs: number;
+}
+export interface BuildEmailProviderDeps {
+    readonly env?: NodeJS.ProcessEnv;
+    /** Loader for the optional peer (default `require`). */
+    readonly load?: (id: string) => unknown;
+    readonly readFile?: (path: string) => string;
+}
+export declare function buildEmailProvider(option: EmailSenderOption | undefined, boundSender: EmailSender | null, deps: BuildEmailProviderDeps): Promise<EmailDelivery>;
+/**
+ * The link-base boot rule applies only with a real sender (Phase 13 #1). `'env'` is real unless
+ * `EMAIL_PROVIDER=disabled`. Read at `forRoot` time, after `resolveBootSecrets()`.
+ */
+export declare function isMailDisabled(option: EmailSenderOption | undefined, env: Readonly<Record<string, string | undefined>>): boolean;
+/**
+ * The `EmailSender` bound under `SHIELD_EMAIL_SENDER` for `'env'`, so existing injectors keep the
+ * port they know. Each send is bounded; a failure rejects (callers already treat it best-effort).
+ */
+export declare function senderFromProvider(provider: EmailProvider, timeoutMs: number): EmailSender;
+/**
+ * `message.sent` / `message.failed` rows go to the framework audit log over guard's own pool
+ * (the runtime account holds append-only INSERT on the audit schema), independent of the
+ * optional app `auditSink` (Shield #6).
+ */
+export declare function messageAuditWriter(pool: Pick<Pool, 'query'>, schemas: Pick<FrameworkSchemas, 'audit'>): MessageAuditWriter;
+//# sourceMappingURL=email-delivery.d.ts.map

package/dist/messaging/email-delivery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"email-delivery.d.ts","sourceRoot":"","sources":["../../src/messaging/email-delivery.ts"],"names":[],"mappings":"AAcA,OAAO,EAAwB,KAAK,aAAa,EAAE,MAAM,cAAc,CAAC;AAExE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAEpC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AACjE,OAAO,EAGL,KAAK,mBAAmB,EACzB,MAAM,6BAA6B,CAAC;AAGrC,OAAO,EAAsB,KAAK,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAEtF,+CAA+C;AAC/C,MAAM,MAAM,iBAAiB,GAAG,WAAW,GAAG,UAAU,GAAG,KAAK,CAAC;AAEjE,iEAAiE;AACjE,MAAM,WAAW,eAAe;IAC9B,mBAAmB,CAAC,MAAM,EAAE,mBAAmB,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CAC1E;AAED,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IACxC,iDAAiD;IACjD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,wDAAwD;IACxD,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC;IACxC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;CAC9C;AAKD,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,WAAW,EAAE,WAAW,GAAG,IAAI,EAC/B,IAAI,EAAE,sBAAsB,GAC3B,OAAO,CAAC,aAAa,CAAC,CA+BxB;AA+BD;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,MAAM,EAAE,iBAAiB,GAAG,SAAS,EACrC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,GAChD,OAAO,CAIT;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,GAAG,WAAW,CAM1F;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,EACzB,OAAO,EAAE,IAAI,CAAC,gBAAgB,EAAE,OAAO,CAAC,GACvC,kBAAkB,CAKpB"}

package/dist/messaging/email-delivery.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildEmailProvider = buildEmailProvider;
+exports.isMailDisabled = isMailDisabled;
+exports.senderFromProvider = senderFromProvider;
+exports.messageAuditWriter = messageAuditWriter;
+/**
+ * Email delivery binding (G-010, docs/features/message-delivery/SPEC.md R2, R8, R14). Turns the
+ * `ShieldModule.forRoot({ emailSender })` option into the provider the {@link MessageDispatcher}
+ * wraps:
+ *  - `'env'` → {@link loadMessageConfig}, then `@astram/messaging` loaded as an OPTIONAL peer (only
+ *    here, so apps that never choose `'env'` never load it) and its `createEmailProvider`; with
+ *    `MESSAGE_BOOT_PROBE=1` the adapter's probe runs (no message is sent) and a failure refuses
+ *    boot. `EMAIL_PROVIDER=disabled` binds nothing and loads nothing.
+ *  - `'disabled'` → no provider (nothing delivered, nothing audited).
+ *  - an app `EmailSender` → adapted as provider `custom`; omitted (development/test) → `log`.
+ */
+const node_fs_1 = require("node:fs");
+const common_1 = require("@nestjs/common");
+const core_1 = require("@astram/core");
+const engine_1 = require("@astram/engine");
+const message_config_js_1 = require("../config/message-config.js");
+const boot_secrets_js_1 = require("../secrets/boot-secrets.js");
+const optional_peer_js_1 = require("../storage/optional-peer.js");
+const message_dispatcher_js_1 = require("./message-dispatcher.js");
+const MESSAGING_PACKAGE = '@astram/messaging';
+const logger = new common_1.Logger('ShieldMessaging');
+async function buildEmailProvider(option, boundSender, deps) {
+    const fallback = { timeoutMs: message_config_js_1.DEFAULT_MESSAGE_SEND_TIMEOUT_MS };
+    if (option === 'disabled')
+        return { provider: null, ...fallback };
+    if (option !== 'env') {
+        if (boundSender === null)
+            return { provider: null, ...fallback };
+        return { provider: (0, message_dispatcher_js_1.providerFromSender)(boundSender, option ? 'custom' : 'log'), ...fallback };
+    }
+    const env = deps.env ?? process.env;
+    const config = (0, message_config_js_1.loadMessageConfig)(env, {
+        resolvedFromSecretRef: boot_secrets_js_1.wasResolvedFromSecretRef,
+        readFile: deps.readFile ?? ((path) => (0, node_fs_1.readFileSync)(path, 'utf8')),
+    });
+    if (config.email.provider === 'disabled') {
+        logger.warn("emailSender: 'env' with EMAIL_PROVIDER=disabled — framework emails (password reset, " +
+            'invites, notices) are NOT delivered.');
+        return { provider: null, ...fallback };
+    }
+    const messaging = (0, optional_peer_js_1.requireOptionalPeer)(MESSAGING_PACKAGE, "ShieldModule.forRoot({ emailSender: 'env' })", deps.load);
+    const provider = await messaging.createEmailProvider(config.email);
+    const timeoutMs = config.email.timeoutMs;
+    if (config.probe)
+        await probe(provider, timeoutMs);
+    logger.log(`Email delivery: ${provider.name}${config.probe ? ' (boot probe passed)' : ''}`);
+    return { provider, timeoutMs };
+}
+/** Reachability + credentials, no message (R8). Bounded; any failure refuses boot. */
+async function probe(provider, timeoutMs) {
+    const fail = (detail) => new Error(`MESSAGE_BOOT_PROBE: the ${provider.name} check failed (${detail}); check EMAIL_PROVIDER ` +
+        'and the provider host / credential variables');
+    if (!provider.probe)
+        return;
+    const signal = AbortSignal.timeout(timeoutMs);
+    let timer;
+    const expiry = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(fail('timeout')), timeoutMs + 1_000);
+        timer.unref?.();
+    });
+    try {
+        await Promise.race([provider.probe({ signal }), expiry]);
+    }
+    catch (e) {
+        if (e instanceof core_1.MessageDeliveryError) {
+            const status = e.status !== undefined ? `, HTTP ${e.status}` : '';
+            throw fail(`${e.failureClass}${status}`);
+        }
+        if (signal.aborted)
+            throw fail('timeout');
+        if (e instanceof Error && e.message.startsWith('MESSAGE_BOOT_PROBE:'))
+            throw e;
+        throw fail('unreachable');
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * The link-base boot rule applies only with a real sender (Phase 13 #1). `'env'` is real unless
+ * `EMAIL_PROVIDER=disabled`. Read at `forRoot` time, after `resolveBootSecrets()`.
+ */
+function isMailDisabled(option, env) {
+    if (option === undefined || option === 'disabled')
+        return true;
+    if (option === 'env')
+        return env.EMAIL_PROVIDER?.trim() === 'disabled';
+    return false;
+}
+/**
+ * The `EmailSender` bound under `SHIELD_EMAIL_SENDER` for `'env'`, so existing injectors keep the
+ * port they know. Each send is bounded; a failure rejects (callers already treat it best-effort).
+ */
+function senderFromProvider(provider, timeoutMs) {
+    return {
+        send: async (message) => {
+            await provider.send(message, { signal: AbortSignal.timeout(timeoutMs) });
+        },
+    };
+}
+/**
+ * `message.sent` / `message.failed` rows go to the framework audit log over guard's own pool
+ * (the runtime account holds append-only INSERT on the audit schema), independent of the
+ * optional app `auditSink` (Shield #6).
+ */
+function messageAuditWriter(pool, schemas) {
+    const sink = new engine_1.MariaDbAuditSink({ schemas });
+    return {
+        record: (event) => sink.record(event, (sql, params) => pool.query(sql, params)),
+    };
+}

package/dist/messaging/message-dispatcher.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The one exit for framework messages (G-010, docs/features/message-delivery/SPEC.md R6, R9, R10;
+ * spec P-1). Every framework email — password reset, invite, email-change confirmation, security
+ * notices — goes through {@link MessageDispatcher.sendEmail}, which:
+ *  - bounds the send (the provider gets an abort signal at `timeoutMs`; the call itself settles by
+ *    `timeoutMs + graceMs` even if the provider ignores the signal);
+ *  - records `message.sent` / `message.failed` with channel, provider, purpose, masked recipient
+ *    and the provider's message id or the failure class — never the link, subject or body;
+ *  - never throws, so a delivery failure never changes a public response.
+ *
+ * It wraps whatever is bound: an `@astram/messaging` adapter (`emailSender: 'env'`), an app's own
+ * `EmailSender` (provider `custom`) or the dev log sender (`log`). `'disabled'` binds no provider
+ * and audits nothing.
+ */
+import { type AuditEvent, type DeliveryFailureClass, type EmailMessage, type EmailProvider, type MessagePurpose } from '@astram/core';
+import type { EmailSender } from '../auth/ports/email-sender.js';
+/** Who the message is about, for the audit row (from the session or the resolved credential). */
+export interface MessageAuditContext {
+    readonly actorId: string;
+    readonly tenantId: string;
+}
+export type EmailDeliveryOutcome = {
+    readonly status: 'sent';
+    readonly provider: string;
+    readonly messageId?: string;
+} | {
+    readonly status: 'failed';
+    readonly provider: string;
+    readonly failureClass: DeliveryFailureClass;
+} | {
+    readonly status: 'disabled';
+};
+export interface MessageDispatcher {
+    /** `false` when mail is `'disabled'`: nothing can be delivered. */
+    readonly emailEnabled: boolean;
+    sendEmail(purpose: MessagePurpose, message: EmailMessage, context: MessageAuditContext): Promise<EmailDeliveryOutcome>;
+}
+/** Appends one audit event. Best-effort here: a failure is swallowed. */
+export interface MessageAuditWriter {
+    record(event: AuditEvent): Promise<void>;
+}
+export interface MessageDispatcherOptions {
+    /** The per-send bound (`MESSAGE_SEND_TIMEOUT_MS`). */
+    readonly timeoutMs: number;
+    /** Extra time after the bound for a provider to honour the abort before the call settles. */
+    readonly graceMs?: number;
+    readonly now?: () => number;
+}
+export declare class GuardMessageDispatcher implements MessageDispatcher {
+    private readonly provider;
+    private readonly audit;
+    private readonly options;
+    readonly emailEnabled: boolean;
+    private readonly graceMs;
+    private readonly now;
+    constructor(provider: EmailProvider | null, audit: MessageAuditWriter | null, options: MessageDispatcherOptions);
+    sendEmail(purpose: MessagePurpose, message: EmailMessage, context: MessageAuditContext): Promise<EmailDeliveryOutcome>;
+    private bounded;
+    private record;
+}
+/**
+ * Adapt an app's `EmailSender` (or the dev log sender) to the provider port. The message passes
+ * through verbatim; the sender cannot be aborted, so the dispatcher's race settles the call.
+ */
+export declare function providerFromSender(sender: EmailSender, name: string): EmailProvider;
+//# sourceMappingURL=message-dispatcher.d.ts.map

package/dist/messaging/message-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-dispatcher.d.ts","sourceRoot":"","sources":["../../src/messaging/message-dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,OAAO,EAEL,KAAK,UAAU,EACf,KAAK,oBAAoB,EACzB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,cAAc,CAAC;AAEtB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAGjE,iGAAiG;AACjG,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,MAAM,oBAAoB,GAC5B;IAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAE,GACnF;IACE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;CAC7C,GACD;IAAE,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAAC;AAEpC,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,SAAS,CACP,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,oBAAoB,CAAC,CAAC;CAClC;AAED,yEAAyE;AACzE,MAAM,WAAW,kBAAkB;IACjC,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1C;AAED,MAAM,WAAW,wBAAwB;IACvC,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAMD,qBAAa,sBAAuB,YAAW,iBAAiB;IAM5D,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAP1B,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;gBAGhB,QAAQ,EAAE,aAAa,GAAG,IAAI,EAC9B,KAAK,EAAE,kBAAkB,GAAG,IAAI,EAChC,OAAO,EAAE,wBAAwB;IAO9C,SAAS,CACb,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,oBAAoB,CAAC;IA4BhC,OAAO,CAAC,OAAO;YAwBD,MAAM;CAiCrB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,CAQnF"}

package/dist/messaging/message-dispatcher.js

@@ -0,0 +1,133 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GuardMessageDispatcher = void 0;
+exports.providerFromSender = providerFromSender;
+/**
+ * The one exit for framework messages (G-010, docs/features/message-delivery/SPEC.md R6, R9, R10;
+ * spec P-1). Every framework email — password reset, invite, email-change confirmation, security
+ * notices — goes through {@link MessageDispatcher.sendEmail}, which:
+ *  - bounds the send (the provider gets an abort signal at `timeoutMs`; the call itself settles by
+ *    `timeoutMs + graceMs` even if the provider ignores the signal);
+ *  - records `message.sent` / `message.failed` with channel, provider, purpose, masked recipient
+ *    and the provider's message id or the failure class — never the link, subject or body;
+ *  - never throws, so a delivery failure never changes a public response.
+ *
+ * It wraps whatever is bound: an `@astram/messaging` adapter (`emailSender: 'env'`), an app's own
+ * `EmailSender` (provider `custom`) or the dev log sender (`log`). `'disabled'` binds no provider
+ * and audits nothing.
+ */
+const core_1 = require("@astram/core");
+const email_address_js_1 = require("../auth/email-address.js");
+const DEFAULT_GRACE_MS = 1_000;
+class BoundExpired extends Error {
+}
+class GuardMessageDispatcher {
+    provider;
+    audit;
+    options;
+    emailEnabled;
+    graceMs;
+    now;
+    constructor(provider, audit, options) {
+        this.provider = provider;
+        this.audit = audit;
+        this.options = options;
+        this.emailEnabled = provider !== null;
+        this.graceMs = options.graceMs ?? DEFAULT_GRACE_MS;
+        this.now = options.now ?? Date.now;
+    }
+    async sendEmail(purpose, message, context) {
+        const provider = this.provider;
+        if (provider === null)
+            return { status: 'disabled' };
+        let outcome;
+        let status;
+        try {
+            const receipt = await this.bounded(provider, message);
+            outcome = {
+                status: 'sent',
+                provider: receipt.provider || provider.name,
+                ...(receipt.messageId ? { messageId: receipt.messageId } : {}),
+            };
+        }
+        catch (e) {
+            const failureClass = e instanceof BoundExpired
+                ? 'timeout'
+                : e instanceof core_1.MessageDeliveryError
+                    ? e.failureClass
+                    : 'transient';
+            if (e instanceof core_1.MessageDeliveryError)
+                status = e.status;
+            outcome = { status: 'failed', provider: provider.name, failureClass };
+        }
+        await this.record(purpose, message.to, context, outcome, status);
+        return outcome;
+    }
+    bounded(provider, message) {
+        const signal = AbortSignal.timeout(this.options.timeoutMs);
+        let timer;
+        const expiry = new Promise((_, reject) => {
+            timer = setTimeout(() => reject(new BoundExpired()), this.options.timeoutMs + this.graceMs);
+            timer.unref?.();
+        });
+        // Started inside a promise so a provider that throws synchronously still settles the race
+        // (never an orphaned expiry rejection, and the timer below is always cleared).
+        const send = Promise.resolve()
+            .then(() => provider.send(message, { signal }))
+            .catch((e) => {
+            // A provider that stopped on our abort reports it however it likes: it is the bound.
+            if (signal.aborted &&
+                !(e instanceof core_1.MessageDeliveryError && e.failureClass !== 'timeout')) {
+                throw new BoundExpired();
+            }
+            throw e;
+        });
+        return Promise.race([send, expiry]).finally(() => clearTimeout(timer));
+    }
+    async record(purpose, to, context, outcome, status) {
+        if (this.audit === null || outcome.status === 'disabled')
+            return;
+        const attributes = {
+            channel: 'email',
+            provider: outcome.provider,
+            purpose,
+            recipient: (0, email_address_js_1.maskEmail)(to),
+        };
+        if (outcome.status === 'sent') {
+            if (outcome.messageId)
+                attributes.messageId = outcome.messageId;
+        }
+        else {
+            attributes.failureClass = outcome.failureClass;
+            if (status !== undefined)
+                attributes.status = status;
+        }
+        try {
+            await this.audit.record({
+                type: purpose === 'invite' ? 'admin_action' : 'authentication',
+                occurredAtMs: this.now(),
+                actorId: context.actorId,
+                tenantId: context.tenantId,
+                action: { key: outcome.status === 'sent' ? 'message.sent' : 'message.failed' },
+                attributes,
+            });
+        }
+        catch {
+            // Best-effort: an audit outage never fails a delivery the user already got (or did not).
+        }
+    }
+}
+exports.GuardMessageDispatcher = GuardMessageDispatcher;
+/**
+ * Adapt an app's `EmailSender` (or the dev log sender) to the provider port. The message passes
+ * through verbatim; the sender cannot be aborted, so the dispatcher's race settles the call.
+ */
+function providerFromSender(sender, name) {
+    return {
+        name,
+        send: async (message) => {
+            await sender.send(message);
+            return { provider: name };
+        },
+    };
+}

package/dist/messaging/recipient-mask.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The masked form of a phone number for audit rows (G-010 R9): `+`, the first two digits, one `*`
+ * per hidden digit, the last two digits (`+919876543210` → `+91********10`). A value that is not
+ * E.164 is never echoed (`***`). Emails use `maskEmail`.
+ */
+export declare function maskPhone(value: string): string;
+//# sourceMappingURL=recipient-mask.d.ts.map

package/dist/messaging/recipient-mask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recipient-mask.d.ts","sourceRoot":"","sources":["../../src/messaging/recipient-mask.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/C"}

package/dist/messaging/recipient-mask.js

@@ -0,0 +1,15 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.maskPhone = maskPhone;
+const core_1 = require("@astram/core");
+/**
+ * The masked form of a phone number for audit rows (G-010 R9): `+`, the first two digits, one `*`
+ * per hidden digit, the last two digits (`+919876543210` → `+91********10`). A value that is not
+ * E.164 is never echoed (`***`). Emails use `maskEmail`.
+ */
+function maskPhone(value) {
+    if (!(0, core_1.isE164PhoneNumber)(value))
+        return '***';
+    const digits = value.slice(1);
+    return `+${digits.slice(0, 2)}${'*'.repeat(digits.length - 4)}${digits.slice(-2)}`;
+}

package/dist/module/shield.module.d.ts

@@ -115,8 +115,10 @@ export interface ShieldModuleOptions {
      * sender, or `'disabled'` (no-op, forgot-password still 204). REQUIRED under
      * `auth: true` unless the raw `NODE_ENV` is `development`/`test` (where the dev
      * `LogEmailSender` is the default); otherwise boot fails (security hardening #6).
+     * `'env'` (G-010) reads the provider from `EMAIL_PROVIDER` and the `EMAIL_*` / provider
+     * variables (needs the `@astram/messaging` package; runbook §6).
      */
-    readonly emailSender?: EmailSender | 'disabled';
+    readonly emailSender?: EmailSender | 'disabled' | 'env';
     readonly recoveryCodeStore?: RecoveryCodeStore;
     readonly profileWriter?: ProfileWriter;
     readonly sessionSweeper?: SessionSweeper;
@@ -248,8 +250,8 @@ export interface ShieldModuleAsyncOptions {
      */
     readonly credentialWriter?: CredentialWriter;
     readonly resetTokenStore?: ResetTokenStore;
-    /** See {@link ShieldModuleOptions.emailSender} (a sender, or `'disabled'`). */
-    readonly emailSender?: EmailSender | 'disabled';
+    /** See {@link ShieldModuleOptions.emailSender} (a sender, `'disabled'` or `'env'`). */
+    readonly emailSender?: EmailSender | 'disabled' | 'env';
     readonly recoveryCodeStore?: RecoveryCodeStore;
     readonly profileWriter?: ProfileWriter;
     readonly sessionSweeper?: SessionSweeper;

package/dist/module/shield.module.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shield.module.d.ts","sourceRoot":"","sources":["../../src/module/shield.module.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"shield.module.d.ts","sourceRoot":"","sources":["../../src/module/shield.module.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astram/guard",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "license": "MIT",
   "description": "Astram framework — the enforcement guard + real-world adapters (the 'hands'). One global deny-by-default gate every request passes through (ADR-0002), classification decorators, boot-pool assertion (ADR-0018), the forRoot() registration seam, and the DB/Redis/crypto adapters that connect the sealed core to a real backend. Depends on @astram/core (ADR-0003, ADR-0023).",
   "type": "commonjs",
@@ -36,17 +36,21 @@
     "argon2": "^0.41.1",
     "ioredis": "^5.4.1",
     "mariadb": "^3.5.4",
-    "@astram/engine": "0.10.0",
-    "@astram/core": "1.8.0"
+    "@astram/core": "1.9.0",
+    "@astram/engine": "0.10.1"
   },
   "peerDependencies": {
     "@nestjs/common": "^11",
     "@nestjs/core": "^11",
     "@nestjs/platform-express": "^11",
     "reflect-metadata": "^0.2",
-    "rxjs": "^7"
+    "rxjs": "^7",
+    "@astram/messaging": "^0.1.1"
   },
   "peerDependenciesMeta": {
+    "@astram/messaging": {
+      "optional": true
+    },
     "@nestjs/platform-express": {
       "optional": true
     }
@@ -63,7 +67,8 @@
     "supertest": "^7.0.0",
     "typescript": "^5.7.0",
     "unplugin-swc": "^1.5.1",
-    "vitest": "^2.1.8"
+    "vitest": "^2.1.8",
+    "@astram/messaging": "0.1.1"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",