@zintrust/core 0.1.28 → 0.1.30

package/src/toolkit/Secrets/index.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Secrets Toolkit (Core)
+ *
+ * Internal framework module intended for CLI usage.
+ * It may use Node APIs (via node-singletons) and should not be used by runtime apps.
+ */
+import { type SecretsProviderName } from '../Secrets/Manifest';
+export type { SecretsProviderName } from '../Secrets/Manifest';
+export type PullOptions = {
+    cwd: string;
+    provider?: SecretsProviderName;
+    manifestPath?: string;
+    outFile?: string;
+    dryRun?: boolean;
+};
+export type PushOptions = {
+    cwd: string;
+    provider?: SecretsProviderName;
+    manifestPath?: string;
+    inFile?: string;
+    dryRun?: boolean;
+};
+export type DoctorOptions = {
+    provider?: SecretsProviderName;
+};
+export declare const SecretsToolkit: Readonly<{
+    pull(options: PullOptions): Promise<{
+        outFile: string;
+        keys: string[];
+    }>;
+    push(options: PushOptions): Promise<{
+        inFile: string;
+        keys: string[];
+    }>;
+    doctor(options: DoctorOptions): {
+        provider: SecretsProviderName;
+        ok: boolean;
+        missing: string[];
+    };
+}>;
+export default SecretsToolkit;
+//# sourceMappingURL=index.d.ts.map

package/src/toolkit/Secrets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/toolkit/Secrets/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,EAAY,KAAK,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAI/E,YAAY,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAErE,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,CAAC,EAAE,mBAAmB,CAAC;IAC/B,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,mBAAmB,CAAC;CAChC,CAAC;AA+GF,eAAO,MAAM,cAAc;kBACL,WAAW,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;kBAe1D,WAAW,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;oBAiB7D,aAAa,GAAG;QAC9B,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,EAAE,EAAE,OAAO,CAAC;QACZ,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB;EAMD,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/toolkit/Secrets/index.js

@@ -0,0 +1,123 @@
+/**
+ * Secrets Toolkit (Core)
+ *
+ * Internal framework module intended for CLI usage.
+ * It may use Node APIs (via node-singletons) and should not be used by runtime apps.
+ */
+import { Env } from '../../config/env.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { EnvFile } from '../Secrets/EnvFile.js';
+import { Manifest } from '../Secrets/Manifest.js';
+import { AwsSecretsManager } from '../Secrets/providers/AwsSecretsManager.js';
+import { CloudflareKv } from '../Secrets/providers/CloudflareKv.js';
+const resolveDefaultEnvFile = () => Env.ZINTRUST_ENV_FILE;
+const resolveDefaultManifest = () => Env.ZINTRUST_SECRETS_MANIFEST;
+const resolveDefaultInFile = () => Env.ZINTRUST_ENV_IN_FILE;
+const resolveSecretsProvider = () => {
+    return Env.ZINTRUST_SECRETS_PROVIDER;
+};
+const resolveProvider = (provider) => {
+    if (provider === 'aws' || provider === 'cloudflare')
+        return provider;
+    throw ErrorFactory.createCliError('Missing/invalid provider. Use --provider aws|cloudflare or set ZINTRUST_SECRETS_PROVIDER.');
+};
+const resolveOutFile = (outFile) => outFile ?? resolveDefaultEnvFile();
+const resolveManifestPath = (manifestPath) => manifestPath ?? resolveDefaultManifest();
+const resolveInFile = (inFile) => inFile ?? resolveDefaultInFile();
+const pullAws = async (manifest) => {
+    const client = AwsSecretsManager.createFromEnv();
+    const entries = Object.entries(manifest.keys).filter(([, spec]) => spec.aws !== undefined);
+    const pairs = await Promise.all(entries.map(async ([envKey, spec]) => {
+        const aws = spec.aws;
+        if (aws === undefined)
+            return null;
+        const value = await client.getValue(aws.secretId, aws.jsonKey);
+        return value === null ? null : [envKey, value];
+    }));
+    const resolved = {};
+    for (const pair of pairs) {
+        if (pair)
+            resolved[pair[0]] = pair[1];
+    }
+    return resolved;
+};
+const pullCloudflare = async (manifest) => {
+    const client = CloudflareKv.createFromEnv();
+    const entries = Object.entries(manifest.keys).filter(([, spec]) => spec.cloudflare !== undefined);
+    const pairs = await Promise.all(entries.map(async ([envKey, spec]) => {
+        const cf = spec.cloudflare;
+        if (cf === undefined)
+            return null;
+        const value = await client.getValue(cf.key, cf.namespaceId);
+        return value === null ? null : [envKey, value];
+    }));
+    const resolved = {};
+    for (const pair of pairs) {
+        if (pair)
+            resolved[pair[0]] = pair[1];
+    }
+    return resolved;
+};
+const pushAws = async (manifest, env, dryRun) => {
+    const client = AwsSecretsManager.createFromEnv();
+    const entries = Object.entries(manifest.keys).filter(([, spec]) => spec.aws !== undefined);
+    const pushed = await Promise.all(entries.map(async ([envKey, spec]) => {
+        const aws = spec.aws;
+        if (aws === undefined)
+            return null;
+        const value = env[envKey];
+        if (typeof value !== 'string')
+            return null;
+        if (!dryRun)
+            await client.putValue(aws.secretId, value);
+        return envKey;
+    }));
+    return pushed.filter((k) => typeof k === 'string');
+};
+const pushCloudflare = async (manifest, env, dryRun) => {
+    const client = CloudflareKv.createFromEnv();
+    const entries = Object.entries(manifest.keys).filter(([, spec]) => spec.cloudflare !== undefined);
+    const pushed = await Promise.all(entries.map(async ([envKey, spec]) => {
+        const cf = spec.cloudflare;
+        if (cf === undefined)
+            return null;
+        const value = env[envKey];
+        if (typeof value !== 'string')
+            return null;
+        if (!dryRun)
+            await client.putValue(cf.key, value, cf.namespaceId);
+        return envKey;
+    }));
+    return pushed.filter((k) => typeof k === 'string');
+};
+export const SecretsToolkit = Object.freeze({
+    async pull(options) {
+        const provider = resolveProvider(options.provider ?? resolveSecretsProvider());
+        const outFile = resolveOutFile(options.outFile);
+        const manifestPath = resolveManifestPath(options.manifestPath);
+        const manifest = await Manifest.load({ cwd: options.cwd, path: manifestPath, provider });
+        const resolved = provider === 'aws' ? await pullAws(manifest) : await pullCloudflare(manifest);
+        if (options.dryRun === true)
+            return { outFile, keys: Object.keys(resolved) };
+        await EnvFile.write({ cwd: options.cwd, path: outFile, values: resolved, mode: 'overwrite' });
+        return { outFile, keys: Object.keys(resolved) };
+    },
+    async push(options) {
+        const provider = resolveProvider(options.provider ?? resolveSecretsProvider());
+        const inFile = resolveInFile(options.inFile);
+        const manifestPath = resolveManifestPath(options.manifestPath);
+        const manifest = await Manifest.load({ cwd: options.cwd, path: manifestPath, provider });
+        const env = await EnvFile.read({ cwd: options.cwd, path: inFile });
+        const dryRun = options.dryRun === true;
+        const keys = provider === 'aws'
+            ? await pushAws(manifest, env, dryRun)
+            : await pushCloudflare(manifest, env, dryRun);
+        return { inFile, keys };
+    },
+    doctor(options) {
+        const provider = resolveProvider(options.provider ?? resolveSecretsProvider());
+        const missing = provider === 'aws' ? AwsSecretsManager.doctorEnv() : CloudflareKv.doctorEnv();
+        return { provider, ok: missing.length === 0, missing };
+    },
+});
+export default SecretsToolkit;

package/src/toolkit/Secrets/providers/AwsSecretsManager.d.ts

@@ -0,0 +1,14 @@
+export type AwsCredentials = {
+    accessKeyId: string;
+    secretAccessKey: string;
+    sessionToken?: string;
+};
+export declare const AwsSecretsManager: Readonly<{
+    createFromEnv(): {
+        getValue: (secretId: string, jsonKey?: string) => Promise<string | null>;
+        putValue: (secretId: string, value: string) => Promise<void>;
+    };
+    doctorEnv(): string[];
+}>;
+export default AwsSecretsManager;
+//# sourceMappingURL=AwsSecretsManager.d.ts.map

package/src/toolkit/Secrets/providers/AwsSecretsManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AwsSecretsManager.d.ts","sourceRoot":"","sources":["../../../../../src/toolkit/Secrets/providers/AwsSecretsManager.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,cAAc,GAAG;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,CAAC;AA0GF,eAAO,MAAM,iBAAiB;qBACX;QACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QACzE,QAAQ,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC9D;iBAsDY,MAAM,EAAE;EAcrB,CAAC;AAEH,eAAe,iBAAiB,CAAC"}

package/src/toolkit/Secrets/providers/AwsSecretsManager.js

@@ -0,0 +1,132 @@
+import { readEnvString } from '../../../common/ExternalServiceUtils.js';
+import { AwsSigV4 } from '../../../common/index.js';
+import { ErrorFactory } from '../../../exceptions/ZintrustError.js';
+const sha256Hex = (data) => AwsSigV4.sha256Hex(data);
+const buildAuthorization = (params) => {
+    const canonicalUri = '/';
+    const canonicalQueryString = '';
+    const headers = {
+        'content-type': 'application/x-amz-json-1.1',
+        host: params.host,
+        'x-amz-date': params.amzDate,
+        'x-amz-target': params.target,
+    };
+    const sessionToken = params.credentials.sessionToken;
+    if (typeof sessionToken === 'string' && sessionToken.trim() !== '') {
+        headers['x-amz-security-token'] = sessionToken;
+    }
+    const payloadHash = sha256Hex(params.body);
+    return AwsSigV4.buildAuthorization({
+        method: params.method,
+        canonicalUri,
+        canonicalQueryString,
+        headers,
+        payloadHash,
+        region: params.region,
+        service: 'secretsmanager',
+        amzDate: params.amzDate,
+        dateStamp: params.dateStamp,
+        credentials: params.credentials,
+    });
+};
+const parseMaybeJson = (value) => {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return value;
+    }
+};
+const requestAwsSecretsManager = async (region, credentials, target, body) => {
+    const host = `secretsmanager.${region}.amazonaws.com`;
+    const url = `https://${host}/`;
+    const now = new Date();
+    const { amzDate, dateStamp } = AwsSigV4.toAmzDate(now);
+    const bodyJson = JSON.stringify(body);
+    const { authorization } = buildAuthorization({
+        method: 'POST',
+        host,
+        region,
+        amzDate,
+        dateStamp,
+        credentials,
+        target,
+        body: bodyJson,
+    });
+    const headers = {
+        'content-type': 'application/x-amz-json-1.1',
+        'x-amz-date': amzDate,
+        'x-amz-target': target,
+        Authorization: authorization,
+    };
+    const sessionToken = credentials.sessionToken;
+    if (typeof sessionToken === 'string' && sessionToken.trim() !== '') {
+        headers['x-amz-security-token'] = sessionToken;
+    }
+    const res = await fetch(url, {
+        method: 'POST',
+        headers,
+        body: bodyJson,
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw ErrorFactory.createCliError(`AWS SecretsManager request failed (${res.status})`, {
+            status: res.status,
+            body: text,
+        });
+    }
+    return JSON.parse(text);
+};
+export const AwsSecretsManager = Object.freeze({
+    createFromEnv() {
+        const region = readEnvString('AWS_REGION') || readEnvString('AWS_DEFAULT_REGION');
+        const accessKeyId = readEnvString('AWS_ACCESS_KEY_ID');
+        const secretAccessKey = readEnvString('AWS_SECRET_ACCESS_KEY');
+        const sessionToken = readEnvString('AWS_SESSION_TOKEN') || undefined;
+        if (region.trim() === '' || accessKeyId.trim() === '' || secretAccessKey.trim() === '') {
+            throw ErrorFactory.createCliError('AWS credentials missing: set AWS_REGION, AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY');
+        }
+        const credentials = { accessKeyId, secretAccessKey, sessionToken };
+        const getValue = async (secretId, jsonKey) => {
+            const data = await requestAwsSecretsManager(region, credentials, 'secretsmanager.GetSecretValue', {
+                SecretId: secretId,
+            });
+            if (typeof data.SecretString !== 'string')
+                return null;
+            if (jsonKey === undefined)
+                return data.SecretString;
+            const parsed = parseMaybeJson(data.SecretString);
+            if (typeof parsed === 'object' && parsed !== null) {
+                const obj = parsed;
+                if (!(jsonKey in obj))
+                    return null;
+                const v = obj[jsonKey];
+                if (typeof v === 'string')
+                    return v;
+                return JSON.stringify(v);
+            }
+            return null;
+        };
+        const putValue = async (secretId, value) => {
+            await requestAwsSecretsManager(region, credentials, 'secretsmanager.PutSecretValue', {
+                SecretId: secretId,
+                SecretString: value,
+            });
+        };
+        return { getValue, putValue };
+    },
+    doctorEnv() {
+        const missing = [];
+        const region = (readEnvString('AWS_REGION') || readEnvString('AWS_DEFAULT_REGION')).trim();
+        if (region === '')
+            missing.push('AWS_REGION');
+        const accessKeyId = readEnvString('AWS_ACCESS_KEY_ID').trim();
+        if (accessKeyId === '')
+            missing.push('AWS_ACCESS_KEY_ID');
+        const secretAccessKey = readEnvString('AWS_SECRET_ACCESS_KEY').trim();
+        if (secretAccessKey === '')
+            missing.push('AWS_SECRET_ACCESS_KEY');
+        return missing;
+    },
+});
+export default AwsSecretsManager;

package/src/toolkit/Secrets/providers/CloudflareKv.d.ts

@@ -0,0 +1,9 @@
+export declare const CloudflareKv: Readonly<{
+    createFromEnv(): {
+        getValue: (key: string, namespaceId?: string) => Promise<string | null>;
+        putValue: (key: string, value: string, namespaceId?: string) => Promise<void>;
+    };
+    doctorEnv(): string[];
+}>;
+export default CloudflareKv;
+//# sourceMappingURL=CloudflareKv.d.ts.map

package/src/toolkit/Secrets/providers/CloudflareKv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CloudflareKv.d.ts","sourceRoot":"","sources":["../../../../../src/toolkit/Secrets/providers/CloudflareKv.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,YAAY;qBACN;QACf,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;QACxE,QAAQ,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;KAC/E;iBAsEY,MAAM,EAAE;EAcrB,CAAC;AAEH,eAAe,YAAY,CAAC"}

package/src/toolkit/Secrets/providers/CloudflareKv.js

@@ -0,0 +1,74 @@
+import { readEnvString } from '../../../common/ExternalServiceUtils.js';
+import { ErrorFactory } from '../../../exceptions/ZintrustError.js';
+export const CloudflareKv = Object.freeze({
+    createFromEnv() {
+        const accountId = readEnvString('CLOUDFLARE_ACCOUNT_ID');
+        const apiToken = readEnvString('CLOUDFLARE_API_TOKEN');
+        const defaultNamespaceId = readEnvString('CLOUDFLARE_KV_NAMESPACE_ID');
+        if (accountId.trim() === '' || apiToken.trim() === '') {
+            throw ErrorFactory.createCliError('Cloudflare credentials missing: set CLOUDFLARE_ACCOUNT_ID, CLOUDFLARE_API_TOKEN');
+        }
+        const getNs = (namespaceId) => {
+            const resolved = namespaceId ?? defaultNamespaceId;
+            if (resolved.trim() === '') {
+                throw ErrorFactory.createCliError('Cloudflare KV namespace missing: set CLOUDFLARE_KV_NAMESPACE_ID or set namespaceId in manifest');
+            }
+            return resolved;
+        };
+        const base = `https://api.cloudflare.com/client/v4/accounts/${accountId}/storage/kv/namespaces`;
+        const getValue = async (key, namespaceId) => {
+            const ns = getNs(namespaceId);
+            const url = `${base}/${encodeURIComponent(ns)}/values/${encodeURIComponent(key)}`;
+            const res = await fetch(url, {
+                method: 'GET',
+                headers: {
+                    Authorization: `Bearer ${apiToken}`,
+                },
+            });
+            if (res.status === 404)
+                return null;
+            const text = await res.text();
+            if (!res.ok) {
+                throw ErrorFactory.createCliError(`Cloudflare KV GET failed (${res.status})`, {
+                    status: res.status,
+                    body: text,
+                });
+            }
+            return text;
+        };
+        const putValue = async (key, value, namespaceId) => {
+            const ns = getNs(namespaceId);
+            const url = `${base}/${encodeURIComponent(ns)}/values/${encodeURIComponent(key)}`;
+            const res = await fetch(url, {
+                method: 'PUT',
+                headers: {
+                    Authorization: `Bearer ${apiToken}`,
+                    'content-type': 'text/plain',
+                },
+                body: value,
+            });
+            const text = await res.text();
+            if (!res.ok) {
+                throw ErrorFactory.createCliError(`Cloudflare KV PUT failed (${res.status})`, {
+                    status: res.status,
+                    body: text,
+                });
+            }
+        };
+        return { getValue, putValue };
+    },
+    doctorEnv() {
+        const missing = [];
+        const accountId = readEnvString('CLOUDFLARE_ACCOUNT_ID').trim();
+        if (accountId === '')
+            missing.push('CLOUDFLARE_ACCOUNT_ID');
+        const apiToken = readEnvString('CLOUDFLARE_API_TOKEN').trim();
+        if (apiToken === '')
+            missing.push('CLOUDFLARE_API_TOKEN');
+        const namespaceId = readEnvString('CLOUDFLARE_KV_NAMESPACE_ID').trim();
+        if (namespaceId === '')
+            missing.push('CLOUDFLARE_KV_NAMESPACE_ID');
+        return missing;
+    },
+});
+export default CloudflareKv;

package/src/tools/broadcast/Broadcast.d.ts

@@ -0,0 +1,17 @@
+type Broadcaster = Readonly<{
+    send: (channel: string, event: string, data: unknown) => Promise<unknown>;
+}>;
+export declare const Broadcast: Readonly<{
+    send(channel: string, event: string, data: unknown): Promise<unknown>;
+    broadcastNow(channel: string, event: string, data: unknown): Promise<unknown>;
+    BroadcastLater(channel: string, event: string, data: unknown, options?: {
+        queueName?: string;
+        timestamp?: number;
+    }): Promise<string>;
+    queue(queueName: string): Readonly<{
+        BroadcastLater: (channel: string, event: string, data: unknown, options?: {}) => Promise<string>;
+    }>;
+    broadcaster(name?: string): Broadcaster;
+}>;
+export default Broadcast;
+//# sourceMappingURL=Broadcast.d.ts.map

package/src/tools/broadcast/Broadcast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Broadcast.d.ts","sourceRoot":"","sources":["../../../../src/tools/broadcast/Broadcast.ts"],"names":[],"mappings":"AAQA,KAAK,WAAW,GAAG,QAAQ,CAAC;IAC1B,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC3E,CAAC,CAAC;AAyDH,eAAO,MAAM,SAAS;kBACA,MAAM,SAAS,MAAM,QAAQ,OAAO;0BAM5B,MAAM,SAAS,MAAM,QAAQ,OAAO;4BAMrD,MAAM,SACR,MAAM,QACP,OAAO,YACJ;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE;qBAepC,MAAM;kCAEa,MAAM,SAAS,MAAM,QAAQ,OAAO;;uBAKrD,MAAM,GAAG,WAAW;EAQvC,CAAC;AAEH,eAAe,SAAS,CAAC"}

package/src/tools/broadcast/Broadcast.js

@@ -0,0 +1,84 @@
+import { InMemoryDriver } from './drivers/InMemory.js';
+import { PusherDriver } from './drivers/Pusher.js';
+import { RedisDriver } from './drivers/Redis.js';
+import { RedisHttpsDriver } from './drivers/RedisHttps.js';
+import broadcastConfig from '../../config/broadcast.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+const resolveBroadcasterConfig = async (name) => {
+    const selection = (name ?? broadcastConfig.getDriverName()).toString().trim().toLowerCase();
+    try {
+        const { BroadcastRegistry } = await import('./BroadcastRegistry.js');
+        if (BroadcastRegistry.has(selection)) {
+            return BroadcastRegistry.get(selection);
+        }
+        try {
+            const { registerBroadcastersFromRuntimeConfig } = await import('./BroadcastRuntimeRegistration.js');
+            registerBroadcastersFromRuntimeConfig(broadcastConfig);
+        }
+        catch {
+            // best-effort
+        }
+        if (BroadcastRegistry.has(selection)) {
+            return BroadcastRegistry.get(selection);
+        }
+    }
+    catch {
+        // best-effort
+    }
+    // Fallback to config lookup (throws on explicit unknown).
+    return broadcastConfig.getDriverConfig(name);
+};
+const sendWithConfig = async (config, channel, event, data) => {
+    const driverName = config.driver;
+    if (driverName === 'inmemory') {
+        return InMemoryDriver.send(undefined, channel, event, data);
+    }
+    if (driverName === 'pusher') {
+        return PusherDriver.send(config, channel, event, data);
+    }
+    if (driverName === 'redis') {
+        return RedisDriver.send(config, channel, event, data);
+    }
+    if (driverName === 'redishttps') {
+        return RedisHttpsDriver.send(config, channel, event, data);
+    }
+    throw ErrorFactory.createConfigError(`Broadcast driver not implemented: ${driverName}`);
+};
+export const Broadcast = Object.freeze({
+    async send(channel, event, data) {
+        const config = await resolveBroadcasterConfig();
+        return sendWithConfig(config, channel, event, data);
+    },
+    // Alias for send() - explicit intent for immediate broadcast
+    async broadcastNow(channel, event, data) {
+        return this.send(channel, event, data);
+    },
+    // Queue broadcast for async processing
+    async BroadcastLater(channel, event, data, options = {}) {
+        const { queueName = 'broadcasts', timestamp = Date.now() } = options;
+        const { Queue } = await import('../queue/Queue.js');
+        const messageId = await Queue.enqueue(queueName, {
+            type: 'broadcast',
+            channel,
+            event,
+            data,
+            timestamp,
+            attempts: 0,
+        });
+        return messageId;
+    },
+    queue(queueName) {
+        return Object.freeze({
+            BroadcastLater: async (channel, event, data, options = {}) => Broadcast.BroadcastLater(channel, event, data, { ...options, queueName }),
+        });
+    },
+    broadcaster(name) {
+        return Object.freeze({
+            send: async (channel, event, data) => {
+                const config = await resolveBroadcasterConfig(name);
+                return sendWithConfig(config, channel, event, data);
+            },
+        });
+    },
+});
+export default Broadcast;

package/src/tools/broadcast/BroadcastRegistry.d.ts

@@ -0,0 +1,15 @@
+import type { KnownBroadcastDriverConfig } from '../../config/type';
+declare function register(name: string, config: KnownBroadcastDriverConfig): void;
+declare function get(name: string): KnownBroadcastDriverConfig;
+declare function has(name: string): boolean;
+declare function list(): string[];
+declare function reset(): void;
+export declare const BroadcastRegistry: Readonly<{
+    register: typeof register;
+    get: typeof get;
+    has: typeof has;
+    list: typeof list;
+    reset: typeof reset;
+}>;
+export {};
+//# sourceMappingURL=BroadcastRegistry.d.ts.map

package/src/tools/broadcast/BroadcastRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BroadcastRegistry.d.ts","sourceRoot":"","sources":["../../../../src/tools/broadcast/BroadcastRegistry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,cAAc,CAAC;AAQ/D,iBAAS,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,0BAA0B,GAAG,IAAI,CAExE;AAED,iBAAS,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,0BAA0B,CAKrD;AAED,iBAAS,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAElC;AAED,iBAAS,IAAI,IAAI,MAAM,EAAE,CAExB;AAED,iBAAS,KAAK,IAAI,IAAI,CAErB;AAED,eAAO,MAAM,iBAAiB;;;;;;EAM5B,CAAC"}

package/src/tools/broadcast/BroadcastRegistry.js

@@ -0,0 +1,29 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+const registry = new Map();
+const normalize = (value) => value.trim().toLowerCase();
+function register(name, config) {
+    registry.set(normalize(name), config);
+}
+function get(name) {
+    const key = normalize(name);
+    const found = registry.get(key);
+    if (found !== undefined)
+        return found;
+    throw ErrorFactory.createConfigError(`Broadcast driver not configured: ${key}`);
+}
+function has(name) {
+    return registry.has(normalize(name));
+}
+function list() {
+    return Array.from(registry.keys());
+}
+function reset() {
+    registry.clear();
+}
+export const BroadcastRegistry = Object.freeze({
+    register,
+    get,
+    has,
+    list,
+    reset,
+});

package/src/tools/broadcast/BroadcastRuntimeRegistration.d.ts

@@ -0,0 +1,11 @@
+import type { BroadcastConfigInput } from '../../config/type';
+/**
+ * Register broadcasters from runtime config.
+ *
+ * This follows the framework's config-driven availability pattern:
+ * - Every `broadcastConfig.drivers[name]` is registered under `name`.
+ * - The configured default name is also registered as `'default'`.
+ * - Unknown names throw when selected via `BroadcastRegistry.get(name)`.
+ */
+export declare function registerBroadcastersFromRuntimeConfig(config: Pick<BroadcastConfigInput, 'default' | 'drivers'>): void;
+//# sourceMappingURL=BroadcastRuntimeRegistration.d.ts.map

package/src/tools/broadcast/BroadcastRuntimeRegistration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BroadcastRuntimeRegistration.d.ts","sourceRoot":"","sources":["../../../../src/tools/broadcast/BroadcastRuntimeRegistration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAKzD;;;;;;;GAOG;AACH,wBAAgB,qCAAqC,CACnD,MAAM,EAAE,IAAI,CAAC,oBAAoB,EAAE,SAAS,GAAG,SAAS,CAAC,GACxD,IAAI,CAeN"}

package/src/tools/broadcast/BroadcastRuntimeRegistration.js

@@ -0,0 +1,23 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import { BroadcastRegistry } from './BroadcastRegistry.js';
+/**
+ * Register broadcasters from runtime config.
+ *
+ * This follows the framework's config-driven availability pattern:
+ * - Every `broadcastConfig.drivers[name]` is registered under `name`.
+ * - The configured default name is also registered as `'default'`.
+ * - Unknown names throw when selected via `BroadcastRegistry.get(name)`.
+ */
+export function registerBroadcastersFromRuntimeConfig(config) {
+    for (const [name, driverConfig] of Object.entries(config.drivers)) {
+        BroadcastRegistry.register(name, driverConfig);
+    }
+    const defaultName = (config.default ?? '').toString().trim().toLowerCase();
+    if (defaultName.length === 0) {
+        throw ErrorFactory.createConfigError('Broadcast default driver is not configured');
+    }
+    if (!BroadcastRegistry.has(defaultName)) {
+        throw ErrorFactory.createConfigError(`Broadcast default driver not configured: ${defaultName}`);
+    }
+    BroadcastRegistry.register('default', BroadcastRegistry.get(defaultName));
+}

package/src/tools/broadcast/drivers/BaseDriver.d.ts

@@ -0,0 +1,5 @@
+export declare const BaseDriver: Readonly<{
+    send(): Promise<unknown>;
+}>;
+export default BaseDriver;
+//# sourceMappingURL=BaseDriver.d.ts.map

package/src/tools/broadcast/drivers/BaseDriver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BaseDriver.d.ts","sourceRoot":"","sources":["../../../../../src/tools/broadcast/drivers/BaseDriver.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,UAAU;YACP,OAAO,CAAC,OAAO,CAAC;EAI9B,CAAC;AAEH,eAAe,UAAU,CAAC"}

package/src/tools/broadcast/drivers/BaseDriver.js

@@ -0,0 +1,8 @@
+import { ErrorFactory } from '../../../exceptions/ZintrustError.js';
+export const BaseDriver = Object.freeze({
+    async send() {
+        await Promise.resolve();
+        throw ErrorFactory.createConfigError('Broadcast driver must implement send()');
+    },
+});
+export default BaseDriver;

package/src/tools/broadcast/drivers/InMemory.d.ts

@@ -0,0 +1,18 @@
+export declare const InMemoryDriver: Readonly<{
+    _events: Array<{
+        channel: string;
+        event: string;
+        data: unknown;
+    }>;
+    send(_config: unknown, channel: string, event: string, data: unknown): Promise<{
+        ok: boolean;
+    }>;
+    getEvents(): {
+        channel: string;
+        event: string;
+        data: unknown;
+    }[];
+    reset(): void;
+}>;
+export default InMemoryDriver;
+//# sourceMappingURL=InMemory.d.ts.map

package/src/tools/broadcast/drivers/InMemory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InMemory.d.ts","sourceRoot":"","sources":["../../../../../src/tools/broadcast/drivers/InMemory.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc;aACV,KAAK,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;kBAEnD,OAAO,WAAW,MAAM,SAAS,MAAM,QAAQ,OAAO;;;;iBAF1C,MAAM;eAAS,MAAM;cAAQ,OAAO;;;EAgBpE,CAAC;AAEH,eAAe,cAAc,CAAC"}