@zintrust/core 0.5.9 → 0.7.2

package/src/security/SecurePayload.js

@@ -0,0 +1,214 @@
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+import { isObject, isString } from '../helper/index.js';
+import { EncryptedEnvelope } from './EncryptedEnvelope.js';
+import { Validator } from '../validation/Validator.js';
+const decryptors = new Map();
+const createStageError = (stage, message, details) => {
+    return ErrorFactory.createValidationError(`SecurePayload ${stage} failed: ${message}`, {
+        stage,
+        details,
+    });
+};
+const resolveDecryptor = (decryptor) => {
+    if (typeof decryptor === 'function') {
+        return decryptor;
+    }
+    if (typeof decryptor === 'string' && decryptor.trim().length > 0) {
+        const registered = decryptors.get(decryptor);
+        if (registered) {
+            return registered;
+        }
+        throw createStageError('decrypt', `Unknown decryptor: ${decryptor}`);
+    }
+    throw createStageError('decrypt', 'No decryptor was provided');
+};
+const coerceBoolean = (value) => {
+    if (typeof value === 'boolean')
+        return value;
+    if (typeof value === 'number') {
+        if (value === 1)
+            return true;
+        if (value === 0)
+            return false;
+    }
+    if (typeof value === 'string') {
+        const normalized = value.trim().toLowerCase();
+        if (['true', '1', 'yes', 'on'].includes(normalized))
+            return true;
+        if (['false', '0', 'no', 'off'].includes(normalized))
+            return false;
+    }
+    throw createStageError('coerce', 'Boolean coercion failed', { value });
+};
+const throwNumberCoercionError = (value, integer) => {
+    throw createStageError('coerce', integer ? 'Integer coercion failed' : 'Numeric coercion failed', {
+        value,
+    });
+};
+const coerceExistingNumber = (value, integer) => {
+    if (!Number.isFinite(value)) {
+        throwNumberCoercionError(value, integer);
+    }
+    if (integer && !Number.isInteger(value)) {
+        throwNumberCoercionError(value, true);
+    }
+    return value;
+};
+const coerceStringNumber = (value, integer) => {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throwNumberCoercionError(value, integer);
+    }
+    if (integer && !/^[-+]?\d+$/.test(trimmed)) {
+        throwNumberCoercionError(value, true);
+    }
+    const parsed = integer ? Number.parseInt(trimmed, 10) : Number.parseFloat(trimmed);
+    if (!Number.isFinite(parsed)) {
+        throwNumberCoercionError(value, integer);
+    }
+    return parsed;
+};
+const coerceNumber = (value, integer = false) => {
+    if (typeof value === 'number') {
+        return coerceExistingNumber(value, integer);
+    }
+    if (typeof value === 'string') {
+        return coerceStringNumber(value, integer);
+    }
+    return throwNumberCoercionError(value, integer);
+};
+const coerceValue = (value, target) => {
+    if (value === null || value === undefined)
+        return value;
+    if (target === 'string') {
+        return isString(value) ? value : String(value);
+    }
+    if (target === 'number') {
+        return coerceNumber(value, false);
+    }
+    if (target === 'integer') {
+        return coerceNumber(value, true);
+    }
+    return coerceBoolean(value);
+};
+const applyCoercion = (input, shape) => {
+    if (!isObject(input)) {
+        throw createStageError('coerce', 'Coercion requires a JSON object payload', {
+            receivedType: Array.isArray(input) ? 'array' : typeof input,
+        });
+    }
+    const output = { ...input };
+    for (const [key, target] of Object.entries(shape)) {
+        if (!(key in output))
+            continue;
+        output[key] = coerceValue(output[key], target);
+    }
+    return output;
+};
+const validatePayload = (input, schema) => {
+    if (!isObject(input)) {
+        throw createStageError('validate', 'Validation requires an object payload', {
+            receivedType: Array.isArray(input) ? 'array' : typeof input,
+        });
+    }
+    try {
+        return Validator.validate(input, schema);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw createStageError('validate', error.message, { cause: error.message });
+        }
+        throw createStageError('validate', 'Schema validation failed', { cause: error });
+    }
+};
+const parseJson = (input) => {
+    if (!isString(input)) {
+        throw createStageError('json', 'JSON parsing requires a string payload', {
+            receivedType: Array.isArray(input) ? 'array' : typeof input,
+        });
+    }
+    try {
+        return JSON.parse(input);
+    }
+    catch (error) {
+        throw createStageError('json', 'Invalid JSON payload', {
+            cause: error instanceof Error ? error.message : String(error),
+        });
+    }
+};
+const decryptPayload = async (input, options) => {
+    if (!isString(input)) {
+        throw createStageError('decrypt', 'Encrypted payload must be a string', {
+            receivedType: Array.isArray(input) ? 'array' : typeof input,
+        });
+    }
+    const decryptor = resolveDecryptor(options.decryptor);
+    try {
+        return await decryptor(input, options.context);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw createStageError('decrypt', error.message, { cause: error.message });
+        }
+        throw createStageError('decrypt', 'Decryptor failed', { cause: error });
+    }
+};
+const createPipeline = (raw, options, operations = []) => {
+    const withOperation = (operation) => {
+        return createPipeline(raw, options, [...operations, operation]);
+    };
+    const execute = async () => {
+        return operations.reduce(async (currentPromise, operation) => {
+            const current = await currentPromise;
+            if (operation.type === 'decrypt') {
+                return decryptPayload(current, options);
+            }
+            if (operation.type === 'json') {
+                return parseJson(current);
+            }
+            if (operation.type === 'coerce') {
+                return applyCoercion(current, operation.shape);
+            }
+            return validatePayload(current, operation.schema);
+        }, Promise.resolve(raw));
+    };
+    return Object.freeze({
+        decrypt: () => withOperation({ type: 'decrypt' }),
+        json: () => withOperation({ type: 'json' }),
+        coerce: (shape) => withOperation({ type: 'coerce', shape }),
+        validate: (schema) => withOperation({ type: 'validate', schema }),
+        value: async () => execute(),
+        typed: async () => execute(),
+    });
+};
+export const SecurePayload = Object.freeze({
+    registerDecryptor(name, decryptor) {
+        if (!isString(name) || name.trim().length === 0) {
+            throw ErrorFactory.createValidationError('SecurePayload decryptor name must be provided');
+        }
+        decryptors.set(name.trim(), decryptor);
+    },
+    unregisterDecryptor(name) {
+        return decryptors.delete(name);
+    },
+    hasDecryptor(name) {
+        return decryptors.has(name);
+    },
+    listDecryptors() {
+        return Array.from(decryptors.keys()).sort((left, right) => left.localeCompare(right));
+    },
+    clearDecryptors() {
+        decryptors.clear();
+    },
+    createEnvelopeDecryptor(options) {
+        return (raw) => EncryptedEnvelope.decryptString(raw, {
+            cipher: options.cipher,
+            key: options.key,
+            previousKeys: options.previousKeys,
+        });
+    },
+    decode(raw, options = {}) {
+        return createPipeline(raw, options);
+    },
+});
+export default SecurePayload;

package/src/templates/project/basic/app/Controllers/AuthController.ts.tpl

@@ -8,15 +8,15 @@ import type { AuthControllerApi, JsonRecord, UserRow } from '@app/Types/controll
 import type { IRequest, IResponse } from '@zintrust/core';
 import {
   Auth,
+  ErrorFactory,
   JwtManager,
+  LoginFlow,
   Logger,
   getString,
   getValidatedBody,
   isUndefinedOrNull,
 } from '@zintrust/core';
 
-
-
 const pickPublicUser = (row: UserRow): { id: unknown; name: string; email: string } => {
   return {
     id: row.id,
@@ -25,75 +25,155 @@ const pickPublicUser = (row: UserRow): { id: unknown; name: string; email: strin
   };
 };
 
-/**
- * Authenticates a user by email and password.
- * Validates credentials against the database and returns a JWT access token on success.
- * Logs all authentication attempts for security auditing.
- * @param req - HTTP request containing email and password
- * @param res - HTTP response to send authentication result
- * @returns Promise that resolves after sending the response
- */
-async function login(req: IRequest, res: IResponse): Promise<void> {
-  const body = getValidatedBody<JsonRecord>(req);
-  if (!body) {
-    Logger.error('AuthController.login: validation middleware did not populate req.validated.body');
-    return res.setStatus(500).json({ error: 'Internal server error' });
+type PasswordLoginContext = {
+  email: string;
+  ipAddress: string;
+  requestId?: string;
+};
+
+const toSubject = (id: unknown): string | undefined => {
+  if (typeof id === 'string' && id.length > 0) return id;
+  if (typeof id === 'number' && Number.isFinite(id)) return String(id);
+  return undefined;
+};
+
+const toDeviceId = (subject: string | undefined): string | undefined => {
+  return isUndefinedOrNull(subject) ? undefined : `dev-${subject}`;
+};
+
+const getClaimString = (claims: unknown, key: string): string | undefined => {
+  if (typeof claims !== 'object' || claims === null) {
+    return undefined;
   }
-  const email = getString(body['email']);
-  const password = getString(body['password']);
-  const ipAddress = req.getRaw().socket.remoteAddress ?? 'unknown';
 
-  try {
-    const existing = await User.where('email', '=', email).limit(1).first<UserRow>();
+  const value = (claims as Record<string, unknown>)[key];
+  return typeof value === 'string' && value.trim() !== '' ? value : undefined;
+};
+
+const getIssuedToken = (issued: unknown): string => {
+  if (typeof issued === 'string' && issued.trim() !== '') {
+    return issued;
+  }
+
+  throw ErrorFactory.createSecurityError('LoginFlow jwt issuer returned an invalid access token');
+};
+
+const isLoginFlowUnauthorizedFailure = (error: unknown): boolean => {
+  if (typeof error !== 'object' || error === null) {
+    return false;
+  }
+
+  const details = (error as { details?: unknown }).details;
+  if (typeof details !== 'object' || details === null) {
+    return false;
+  }
+
+  const nested = (details as Record<string, unknown>)['error'];
+  return (
+    typeof nested === 'object' &&
+    nested !== null &&
+    (nested as { statusCode?: unknown }).statusCode === 401
+  );
+};
+
+const passwordLoginProvider = Object.freeze({
+  async identify(
+    input: { email: string },
+    context: PasswordLoginContext
+  ): Promise<UserRow | null> {
+    const existing = await User.where('email', '=', input.email).first<UserRow>();
 
     if (existing === null) {
       Logger.warn('AuthController.login: failed login attempt', {
-        email,
-        ip: ipAddress,
+        email: context.email,
+        ip: context.ipAddress,
         reason: 'user_not_found',
+        ...(context.requestId ? { requestId: context.requestId } : {}),
         timestamp: new Date().toISOString(),
       });
-      res.setStatus(401).json({ error: 'Invalid credentials' });
-      return;
     }
 
-    const passwordHash = getString(existing.password);
-    const ok = await Auth.compare(password, passwordHash);
+    return existing;
+  },
+
+  async verify(
+    identity: UserRow | null,
+    input: { password: string },
+    context: PasswordLoginContext
+  ) {
+    if (identity === null) {
+      throw ErrorFactory.createUnauthorizedError('Invalid credentials');
+    }
+
+    const passwordHash = getString(identity.password);
+    const ok = await Auth.compare(input.password, passwordHash);
     if (!ok) {
       Logger.warn('AuthController.login: failed login attempt', {
-        email,
-        ip: ipAddress,
+        email: context.email,
+        ip: context.ipAddress,
         reason: 'invalid_password',
+        ...(context.requestId ? { requestId: context.requestId } : {}),
         timestamp: new Date().toISOString(),
       });
-      res.setStatus(401).json({ error: 'Invalid credentials' });
-      return;
+      throw ErrorFactory.createUnauthorizedError('Invalid credentials');
     }
 
-    const user = pickPublicUser(existing);
+    const user = pickPublicUser(identity);
+    const subject = toSubject(user.id);
+    const deviceId = toDeviceId(subject);
+
+    return {
+      user,
+      subject,
+      claims: {
+        sub: subject,
+        email: user.email,
+        ...(isUndefinedOrNull(deviceId) ? {} : { deviceId }),
+      },
+    };
+  },
+});
 
-    const subject = ((): string | undefined => {
-      const id = user.id;
-      if (typeof id === 'string' && id.length > 0) return id;
-      if (typeof id === 'number' && Number.isFinite(id)) return String(id);
-      return undefined;
-    })();
+/**
+ * Authenticates a user by email and password.
+ * Validates credentials against the database and returns a JWT access token on success.
+ * Logs all authentication attempts for security auditing.
+ * @param req - HTTP request containing email and password
+ * @param res - HTTP response to send authentication result
+ * @returns Promise that resolves after sending the response
+ */
+async function login(req: IRequest, res: IResponse): Promise<void> {
+  const body = getValidatedBody<JsonRecord>(req);
+  if (!body) {
+    Logger.error('AuthController.login: validation middleware did not populate req.validated.body');
+    return res.setStatus(500).json({ error: 'Internal server error' });
+  }
+  const email = getString(body['email']);
+  const password = getString(body['password']);
+  const ipAddress = req.getRaw().socket.remoteAddress ?? 'unknown';
+  const requestId = typeof req.getHeader === 'function' ? req.getHeader('x-request-id') : undefined;
 
-    // Bulletproof Auth (device binding) expects a device id header to match a JWT claim.
-    // For the example app, we mint a stable device id derived from the subject.
-    // Production apps should issue a per-device id and manage a per-device signing secret.
-    const deviceId = isUndefinedOrNull(subject) ? undefined : `dev-${subject}`;
+  try {
+    const result = await LoginFlow.create({
+      provider: passwordLoginProvider,
+      context: Object.freeze({ email, ipAddress, requestId }),
+    })
+      .identify({ email })
+      .verify({ password })
+      .issue('jwt')
+      .audit()
+      .run();
 
-    const token = await JwtManager.signAccessToken({
-      sub: subject,
-      email,
-      ...(isUndefinedOrNull(deviceId) ? {} : { deviceId }),
-    });
+    const user = result.verified.user as { id: unknown; name: string; email: string };
+    const subject = getClaimString(result.verified.claims, 'sub');
+    const deviceId = getClaimString(result.verified.claims, 'deviceId');
+    const token = getIssuedToken(result.issued);
 
     Logger.info('AuthController.login: successful login', {
       userId: subject,
       email,
       ip: ipAddress,
+      ...(requestId ? { requestId } : {}),
       timestamp: new Date().toISOString(),
     });
 
@@ -104,9 +184,15 @@ async function login(req: IRequest, res: IResponse): Promise<void> {
       user,
     });
   } catch (error) {
+    if (isLoginFlowUnauthorizedFailure(error)) {
+      res.setStatus(401).json({ error: 'Invalid credentials' });
+      return;
+    }
+
     Logger.error('AuthController.login: unexpected error', {
       email,
       ip: ipAddress,
+      ...(requestId ? { requestId } : {}),
       error: error instanceof Error ? error.message : String(error),
       timestamp: new Date().toISOString(),
     });

package/src/templates/project/basic/package.json.tpl

@@ -12,8 +12,7 @@
     "type-check": "tsc --noEmit"
   },
   "dependencies": {
-    "@zintrust/core": "^{{coreVersion}}",
-    "@zintrust/d1-migrator": "^0.4.6"
+    "@zintrust/core": "^{{coreVersion}}"
   },
   "devDependencies": {
     "@zintrust/governance": "{{governanceVersion}}",
@@ -23,5 +22,10 @@
     "tsc-alias": "^1.8.16",
     "typescript": "^5.9.3",
     "vitest": "^4.0.16"
+  },
+  "overrides": {
+    "@zintrust/governance": {
+      "@zintrust/core": ">=0.6.0"
+    }
   }
 }

package/src/tools/notification/Composer.d.ts

@@ -0,0 +1,40 @@
+export type NotificationComposePolicy = 'required' | 'best_effort';
+export type NotificationChannelHandler<TPayload = unknown, TContext = unknown> = (payload: TPayload, context: TContext) => Promise<unknown>;
+export type NotificationComposeChannelResult = {
+    channel: string;
+    policy: NotificationComposePolicy;
+    ok: boolean;
+    payload: unknown;
+    result?: unknown;
+    error?: unknown;
+};
+export type NotificationComposeResult = {
+    ok: boolean;
+    results: NotificationComposeChannelResult[];
+};
+export type NotificationComposeError = Error & {
+    results: NotificationComposeChannelResult[];
+};
+export type NotificationComposeOptions<TContext = unknown> = {
+    context?: TContext;
+};
+export type NotificationComposeBuilder<TContext = unknown> = {
+    channel: (name: string, payload: unknown) => NotificationComposeBuilder<TContext>;
+    email: (payload: unknown) => NotificationComposeBuilder<TContext>;
+    push: (payload: unknown) => NotificationComposeBuilder<TContext>;
+    sms: (payload: unknown) => NotificationComposeBuilder<TContext>;
+    webhook: (payload: unknown) => NotificationComposeBuilder<TContext>;
+    required: (channels: string[]) => NotificationComposeBuilder<TContext>;
+    bestEffort: (channels: string[]) => NotificationComposeBuilder<TContext>;
+    send: () => Promise<NotificationComposeResult>;
+};
+export type NotificationComposerNamespace = {
+    compose: <TContext = unknown>(options?: NotificationComposeOptions<TContext>) => NotificationComposeBuilder<TContext>;
+    registerChannel: <TPayload = unknown, TContext = unknown>(name: string, handler: NotificationChannelHandler<TPayload, TContext>) => void;
+    unregisterChannel: (name: string) => void;
+    hasChannel: (name: string) => boolean;
+    listChannels: () => string[];
+    clearChannels: () => void;
+};
+export declare const NotificationComposer: NotificationComposerNamespace;
+//# sourceMappingURL=Composer.d.ts.map

package/src/tools/notification/Composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Composer.d.ts","sourceRoot":"","sources":["../../../../src/tools/notification/Composer.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,yBAAyB,GAAG,UAAU,GAAG,aAAa,CAAC;AAEnE,MAAM,MAAM,0BAA0B,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO,IAAI,CAC/E,OAAO,EAAE,QAAQ,EACjB,OAAO,EAAE,QAAQ,KACd,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB,MAAM,MAAM,gCAAgC,GAAG;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,yBAAyB,CAAC;IAClC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,EAAE,EAAE,OAAO,CAAC;IACZ,OAAO,EAAE,gCAAgC,EAAE,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,KAAK,GAAG;IAC7C,OAAO,EAAE,gCAAgC,EAAE,CAAC;CAC7C,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,QAAQ,GAAG,OAAO,IAAI;IAC3D,OAAO,CAAC,EAAE,QAAQ,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,0BAA0B,CAAC,QAAQ,GAAG,OAAO,IAAI;IAC3D,OAAO,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,KAAK,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IAClF,KAAK,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IAClE,IAAI,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IACjE,GAAG,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IAChE,OAAO,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IACpE,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IACvE,UAAU,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IACzE,IAAI,EAAE,MAAM,OAAO,CAAC,yBAAyB,CAAC,CAAC;CAChD,CAAC;AAEF,MAAM,MAAM,6BAA6B,GAAG;IAC1C,OAAO,EAAE,CAAC,QAAQ,GAAG,OAAO,EAC1B,OAAO,CAAC,EAAE,0BAA0B,CAAC,QAAQ,CAAC,KAC3C,0BAA0B,CAAC,QAAQ,CAAC,CAAC;IAC1C,eAAe,EAAE,CAAC,QAAQ,GAAG,OAAO,EAAE,QAAQ,GAAG,OAAO,EACtD,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,0BAA0B,CAAC,QAAQ,EAAE,QAAQ,CAAC,KACpD,IAAI,CAAC;IACV,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IACtC,YAAY,EAAE,MAAM,MAAM,EAAE,CAAC;IAC7B,aAAa,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAsMF,eAAO,MAAM,oBAAoB,EAAE,6BAOjC,CAAC"}

package/src/tools/notification/Composer.js

@@ -0,0 +1,140 @@
+import { SystemTraceBridge } from '../../trace/SystemTraceBridge.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { isArray, isFunction, isNonEmptyString } from '../../helper/index.js';
+const channelRegistry = new Map();
+const normalizeChannelName = (name) => {
+    const normalized = String(name ?? '')
+        .trim()
+        .toLowerCase();
+    if (!isNonEmptyString(normalized)) {
+        throw ErrorFactory.createValidationError('Notification channel name must be a non-empty string');
+    }
+    return normalized;
+};
+const createComposeError = (message, results) => {
+    return Object.assign(ErrorFactory.createValidationError(message, {
+        results,
+    }), { results });
+};
+const ensureChannelsInput = (channels) => {
+    if (!isArray(channels)) {
+        throw ErrorFactory.createValidationError('Notification compose channel list must be an array');
+    }
+    return channels.map((channel) => normalizeChannelName(channel));
+};
+const ensureHandler = (handler) => {
+    if (!isFunction(handler)) {
+        throw ErrorFactory.createValidationError('Notification channel handler must be a function');
+    }
+};
+const getPolicy = (policies, channel) => {
+    return policies.get(channel) ?? 'required';
+};
+const ensureEntries = (entries) => {
+    if (entries.length === 0) {
+        throw ErrorFactory.createValidationError('Notification compose requires at least one channel before send()');
+    }
+};
+const deliverEntry = async (entry, policy, context) => {
+    const handler = channelRegistry.get(entry.channel);
+    if (!handler) {
+        return {
+            channel: entry.channel,
+            policy,
+            ok: false,
+            payload: entry.payload,
+            error: ErrorFactory.createConfigError(`Notification compose channel not registered: ${entry.channel}`),
+        };
+    }
+    try {
+        const result = await handler(entry.payload, context);
+        SystemTraceBridge.emitNotification(`compose:${entry.channel}`, [entry.channel], undefined, undefined, entry.payload);
+        return {
+            channel: entry.channel,
+            policy,
+            ok: true,
+            payload: entry.payload,
+            result,
+        };
+    }
+    catch (error) {
+        return {
+            channel: entry.channel,
+            policy,
+            ok: false,
+            payload: entry.payload,
+            error,
+        };
+    }
+};
+const hasRequiredFailure = (results) => {
+    return results.some((entry) => !entry.ok && entry.policy === 'required');
+};
+const compose = (options = {}) => {
+    const entries = [];
+    const policies = new Map();
+    const builder = Object.freeze({
+        channel(name, payload) {
+            entries.push({ channel: normalizeChannelName(name), payload });
+            return this;
+        },
+        email(payload) {
+            return this.channel('email', payload);
+        },
+        push(payload) {
+            return this.channel('push', payload);
+        },
+        sms(payload) {
+            return this.channel('sms', payload);
+        },
+        webhook(payload) {
+            return this.channel('webhook', payload);
+        },
+        required(channels) {
+            for (const channel of ensureChannelsInput(channels)) {
+                policies.set(channel, 'required');
+            }
+            return this;
+        },
+        bestEffort(channels) {
+            for (const channel of ensureChannelsInput(channels)) {
+                policies.set(channel, 'best_effort');
+            }
+            return this;
+        },
+        async send() {
+            ensureEntries(entries);
+            const results = await Promise.all(entries.map(async (entry) => deliverEntry(entry, getPolicy(policies, entry.channel), options.context)));
+            if (hasRequiredFailure(results)) {
+                throw createComposeError('Notification compose failed for required channels', results);
+            }
+            return {
+                ok: true,
+                results,
+            };
+        },
+    });
+    return builder;
+};
+const registerChannel = (name, handler) => {
+    ensureHandler(handler);
+    channelRegistry.set(normalizeChannelName(name), handler);
+};
+const unregisterChannel = (name) => {
+    channelRegistry.delete(normalizeChannelName(name));
+};
+const hasChannel = (name) => channelRegistry.has(normalizeChannelName(name));
+const listChannels = () => {
+    return Array.from(channelRegistry.keys()).sort((left, right) => left.localeCompare(right));
+};
+const clearChannels = () => {
+    channelRegistry.clear();
+};
+export const NotificationComposer = Object.freeze({
+    compose,
+    registerChannel,
+    unregisterChannel,
+    hasChannel,
+    listChannels,
+    clearChannels,
+});

package/src/tools/notification/Notification.d.ts

@@ -18,6 +18,12 @@ export declare const Notification: Readonly<{
     channel: (name: string) => Readonly<{
         send: (recipient: string, message: string, options?: Record<string, unknown>) => Promise<unknown>;
     }>;
+    compose: <TContext = unknown>(options?: import("./Composer").NotificationComposeOptions<TContext>) => import("./Composer").NotificationComposeBuilder<TContext>;
+    registerChannel: <TPayload = unknown, TContext = unknown>(name: string, handler: import("./Composer").NotificationChannelHandler<TPayload, TContext>) => void;
+    unregisterChannel: (name: string) => void;
+    hasChannel: (name: string) => boolean;
+    listChannels: () => string[];
+    clearChannels: () => void;
     listDrivers: () => string[];
 }>;
 export default Notification;

package/src/tools/notification/Notification.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Notification.d.ts","sourceRoot":"","sources":["../../../../src/tools/notification/Notification.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,eAAO,MAAM,YAAY;;;2BAQV,MAAM,WACR,MAAM,kBACA,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,iBACxB;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACvD,OAAO,CAAC,MAAM,CAAC;qBAcD,MAAM;iCAGN,MAAM,WACR,MAAM,kBACA,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,iBACxB;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE;;oBAM1B,MAAM;0BAEM,MAAM,WAAW,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;EAItF,CAAC;AAEH,eAAe,YAAY,CAAC"}
+{"version":3,"file":"Notification.d.ts","sourceRoot":"","sources":["../../../../src/tools/notification/Notification.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,eAAO,MAAM,YAAY;;;2BAQV,MAAM,WACR,MAAM,kBACA,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,iBACxB;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GACvD,OAAO,CAAC,MAAM,CAAC;qBAcD,MAAM;iCAGN,MAAM,WACR,MAAM,kBACA,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,iBACxB;YAAE,SAAS,CAAC,EAAE,MAAM,CAAA;SAAE;;oBAM1B,MAAM;0BAEM,MAAM,WAAW,MAAM,YAAY,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;;;;;;;;;EAUtF,CAAC;AAEH,eAAe,YAAY,CAAC"}