@zintrust/core 0.1.1 → 0.1.3

package/src/templates/project/basic/routes/api.ts.tpl

@@ -5,8 +5,10 @@
 
 import { UserController } from '@app/Controllers/UserController';
 import { Env } from '@config/env';
-import { Logger } from '@config/logger';
-import { useDatabase, type IRouter, Router } from '@zintrust/core';
+import { registerBroadcastRoutes } from '@routes/broadcast';
+import { registerHealthRoutes } from '@routes/health';
+import { registerStorageRoutes } from '@routes/storage';
+import { type IRouter, Router } from '@routing/Router';
 
 export function registerRoutes(router: IRouter): void {
   const userController = UserController.create();
@@ -19,6 +21,13 @@ export function registerRoutes(router: IRouter): void {
  * Register public routes
  */
 function registerPublicRoutes(router: IRouter): void {
+  registerRootRoute(router);
+  registerHealthRoutes(router);
+  registerBroadcastRoutes(router);
+  registerStorageRoutes(router);
+}
+
+function registerRootRoute(router: IRouter): void {
   Router.get(router, '/', async (_req, res) => {
     res.json({
       framework: 'Zintrust Framework',
@@ -28,41 +37,6 @@ function registerPublicRoutes(router: IRouter): void {
       database: Env.DB_CONNECTION ?? 'sqlite',
     });
   });
-
-  Router.get(router, '/health', async (_req, res) => {
-    try {
-      const db = useDatabase();
-      await db.query('SELECT 1');
-
-      const uptime =
-        typeof process !== 'undefined' && typeof process.uptime === 'function'
-          ? process.uptime()
-          : 0;
-
-      res.json({
-        status: 'healthy',
-        timestamp: new Date().toISOString(),
-        uptime,
-        database: 'connected',
-        environment: Env.NODE_ENV ?? 'development',
-      });
-    } catch (error) {
-      Logger.error('Health check failed:', error);
-
-      const isProd =
-        typeof process !== 'undefined' &&
-        typeof process.env === 'object' &&
-        process.env !== null &&
-        process.env['NODE_ENV'] === 'production';
-
-      res.setStatus(503).json({
-        status: 'unhealthy',
-        timestamp: new Date().toISOString(),
-        database: 'disconnected',
-        error: isProd ? 'Service unavailable' : (error as Error).message,
-      });
-    }
-  });
 }
 
 /**

package/src/templates/project/basic/routes/broadcast.ts.tpl

@@ -0,0 +1,32 @@
+/**
+ * Broadcast Routes
+ *
+ * Runtime-only endpoints for broadcast.
+ * Provider setup and secret provisioning remain CLI-only.
+ */
+
+import { type IRouter, Router } from '@routing/Router';
+
+export function registerBroadcastRoutes(router: IRouter): void {
+  Router.get(router, '/broadcast/health', async (_req, res) => {
+    res.json({ ok: true });
+  });
+
+  Router.post(router, '/broadcast/send', async (req: { body?: unknown }, res) => {
+    const body = (req.body ?? {}) as Record<string, unknown>;
+    const channel = typeof body['channel'] === 'string' ? body['channel'] : '';
+    const event = typeof body['event'] === 'string' ? body['event'] : '';
+    const data = body['data'];
+
+    if (!channel || !event) {
+      res
+        .setStatus(400)
+        .json({ ok: false, error: 'Invalid payload: channel and event are required' });
+      return;
+    }
+
+    const { Broadcast } = await import('@broadcast/Broadcast');
+    const result = await Broadcast.send(channel, event, data);
+    res.json({ ok: true, result });
+  });
+}

package/src/templates/project/basic/routes/health.ts.tpl

@@ -0,0 +1,134 @@
+/**
+ * Health Routes
+ * Provides health, liveness, and readiness endpoints.
+ */
+
+import { appConfig } from '@/config';
+import { RuntimeHealthProbes } from '@/health/RuntimeHealthProbes';
+import { Env } from '@config/env';
+import { Logger } from '@config/logger';
+import { useDatabase } from '@orm/Database';
+import { QueryBuilder } from '@orm/QueryBuilder';
+import { type IRouter, Router } from '@routing/Router';
+
+export function registerHealthRoutes(router: IRouter): void {
+  registerHealthRoute(router);
+  registerHealthLiveRoute(router);
+  registerHealthReadyRoute(router);
+}
+
+function registerHealthRoute(router: IRouter): void {
+  Router.get(router, '/health', async (_req, res) => {
+    const environment = Env.NODE_ENV ?? 'development';
+
+    try {
+      const db = useDatabase();
+      await QueryBuilder.ping(db);
+
+      const uptime =
+        typeof process !== 'undefined' && typeof process.uptime === 'function'
+          ? process.uptime()
+          : 0;
+
+      res.json({
+        status: 'healthy',
+        timestamp: new Date().toISOString(),
+        uptime,
+        database: 'connected',
+        environment,
+      });
+    } catch (error) {
+      Logger.error('Health check failed:', error);
+
+      const isProd = environment === 'production' || environment === 'prod';
+
+      res.setStatus(503).json({
+        status: 'unhealthy',
+        timestamp: new Date().toISOString(),
+        database: 'disconnected',
+        error: isProd ? 'Service unavailable' : (error as Error).message,
+      });
+    }
+  });
+}
+
+function registerHealthLiveRoute(router: IRouter): void {
+  Router.get(router, '/health/live', async (_req, res) => {
+    const uptime =
+      typeof process !== 'undefined' && typeof process.uptime === 'function' ? process.uptime() : 0;
+
+    res.json({
+      status: 'alive',
+      timestamp: new Date().toISOString(),
+      uptime,
+    });
+  });
+}
+
+function registerHealthReadyRoute(router: IRouter): void {
+  Router.get(router, '/health/ready', async (_req, res) => {
+    const startTime = Date.now();
+    const environment = appConfig.environment;
+
+    let databaseResponseTime: number | null = null;
+    let cacheResponseTime: number | null = null;
+
+    try {
+      const db = useDatabase();
+      await QueryBuilder.ping(db);
+
+      databaseResponseTime = Date.now() - startTime;
+
+      // Only probe KV at runtime when explicitly configured.
+      cacheResponseTime = await RuntimeHealthProbes.pingKvCache(2000);
+
+      res.json({
+        status: 'ready',
+        timestamp: new Date().toISOString(),
+        environment,
+        dependencies: {
+          database: {
+            status: 'ready',
+            responseTime: databaseResponseTime,
+          },
+          ...(cacheResponseTime === null
+            ? {}
+            : {
+                cache: {
+                  status: 'ready',
+                  responseTime: cacheResponseTime,
+                },
+              }),
+        },
+      });
+    } catch (error) {
+      Logger.error('Readiness check failed:', error);
+
+      const isProd = environment === 'production';
+
+      const responseTime = Date.now() - startTime;
+
+      const dependencies: Record<string, unknown> = {
+        database: {
+          status: databaseResponseTime === null ? 'unavailable' : 'ready',
+          responseTime: databaseResponseTime ?? responseTime,
+        },
+      };
+
+      if (RuntimeHealthProbes.getCacheDriverName() === 'kv') {
+        dependencies['cache'] = {
+          status: 'unavailable',
+          responseTime: cacheResponseTime ?? responseTime,
+        };
+      }
+
+      res.setStatus(503).json({
+        status: 'not_ready',
+        timestamp: new Date().toISOString(),
+        environment,
+        dependencies,
+        error: isProd ? 'Service unavailable' : (error as Error).message,
+      });
+    }
+  });
+}

package/src/templates/project/basic/routes/storage.ts.tpl

@@ -0,0 +1,42 @@
+import { HTTP_HEADERS } from '@config/constants';
+import { Env } from '@config/env';
+import { type IRouter, Router } from '@routing/Router';
+import { LocalSignedUrl } from '@storage/LocalSignedUrl';
+import { Storage } from '@storage/index';
+
+export function registerStorageRoutes(router: IRouter): void {
+  Router.get(router, '/storage/download', async (req, res) => {
+    const tokenRaw = req.getQueryParam('token');
+    const token = typeof tokenRaw === 'string' ? tokenRaw : '';
+
+    if (token.trim() === '') {
+      res.setStatus(400).json({ message: 'Missing token' });
+      return;
+    }
+
+    const appKey = Env.get('APP_KEY', '');
+    if (appKey.trim() === '') {
+      res.setStatus(500).json({ message: 'Storage signing is not configured' });
+      return;
+    }
+
+    try {
+      const payload = LocalSignedUrl.verifyToken(token, appKey);
+
+      // Only local disk is supported by this route.
+      if (payload.disk !== 'local') {
+        res.setStatus(400).json({ message: 'Unsupported disk' });
+        return;
+      }
+
+      const contents = await Storage.get('local', payload.key);
+
+      res.setHeader(HTTP_HEADERS.CONTENT_TYPE, 'application/octet-stream');
+      res.setStatus(200).send(contents);
+    } catch {
+      res.setStatus(403).json({ message: 'Invalid or expired token' });
+    }
+  });
+}
+
+export default registerStorageRoutes;

package/src/templates/project/basic/src/index.ts.tpl

@@ -28,22 +28,49 @@ async function start() {
     await server.listen();
 
     Logger.info(`Server running at http://${host}:${port}`);
+
+    const shutdown = async (signal: string): Promise<void> => {
+      Logger.info(`${signal} received, shutting down gracefully...`);
+
+      const timeoutMs = Env.getInt('SHUTDOWN_TIMEOUT', 10000);
+      const withTimeout = async <T>(promise: Promise<T>, ms: number): Promise<T> => {
+        if (ms <= 0) return promise;
+        return new Promise<T>((resolve, reject) => {
+          const timer = setTimeout(() => reject(new globalThis.Error('Shutdown timed out')), ms);
+          promise
+            .then((value) => {
+              clearTimeout(timer);
+              resolve(value);
+            })
+            .catch((err) => {
+              clearTimeout(timer);
+              reject(err);
+            });
+        });
+      };
+
+      try {
+        await withTimeout(
+          (async () => {
+            await server.close();
+            await app.shutdown();
+          })(),
+          timeoutMs
+        );
+        process.exit(0);
+      } catch (error) {
+        Logger.error('Graceful shutdown failed:', error);
+        process.exit(1);
+      }
+    };
+
+    process.on('SIGTERM', () => void shutdown('SIGTERM'));
+    process.on('SIGINT', () => void shutdown('SIGINT'));
   } catch (error) {
     Logger.error('Failed to start application:', error);
     process.exit(1);
   }
 }
 
-// Handle graceful shutdown
-process.on('SIGTERM', () => {
-  Logger.info('SIGTERM received, shutting down gracefully...');
-  process.exit(0);
-});
-
-process.on('SIGINT', () => {
-  Logger.info('SIGINT received, shutting down gracefully...');
-  process.exit(0);
-});
-
 // Run start
 await start();

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

@@ -8,6 +8,9 @@
     "config",
     "database/migrations",
     "database/seeders",
+    "logs",
+    "storage",
+    "tmp",
     "public",
     "routes",
     "src",

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

@@ -0,0 +1,15 @@
+export type EnvFileWriteMode = 'overwrite';
+export declare const EnvFile: Readonly<{
+    read(params: {
+        cwd: string;
+        path: string;
+    }): Promise<Record<string, string>>;
+    write(params: {
+        cwd: string;
+        path: string;
+        values: Record<string, string>;
+        mode: EnvFileWriteMode;
+    }): Promise<void>;
+}>;
+export default EnvFile;
+//# sourceMappingURL=EnvFile.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"EnvFile.d.ts","sourceRoot":"","sources":["../../../../src/toolkit/Secrets/EnvFile.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,gBAAgB,GAAG,WAAW,CAAC;AAmC3C,eAAO,MAAM,OAAO;iBACC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;kBAgB9D;QAClB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B,IAAI,EAAE,gBAAgB,CAAC;KACxB,GAAG,OAAO,CAAC,IAAI,CAAC;EAgBjB,CAAC;AAEH,eAAe,OAAO,CAAC"}

package/src/toolkit/Secrets/EnvFile.js

@@ -0,0 +1,63 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError';
+import { fsPromises as fs } from '../../node-singletons/fs';
+import * as path from '../../node-singletons/path';
+const isValidKey = (key) => /^[A-Z0-9_]+$/.test(key);
+const parseEnvLine = (line) => {
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#'))
+        return null;
+    const eq = trimmed.indexOf('=');
+    if (eq <= 0)
+        return null;
+    const key = trimmed.slice(0, eq).trim();
+    const raw = trimmed.slice(eq + 1);
+    if (!isValidKey(key))
+        return null;
+    // Preserve value verbatim (except strip surrounding quotes if present)
+    let value = raw;
+    const v = raw.trim();
+    if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        value = v.slice(1, -1);
+    }
+    return { key, value };
+};
+const serializeEnv = (values) => {
+    const keys = Object.keys(values).sort((a, b) => a.localeCompare(b));
+    const lines = keys.map((key) => {
+        const value = values[key] ?? '';
+        // Write as JSON string to safely quote newlines, #, etc.
+        return `${key}=${JSON.stringify(value)}`;
+    });
+    return `${lines.join('\n')}\n`;
+};
+export const EnvFile = Object.freeze({
+    async read(params) {
+        const filePath = path.resolve(params.cwd, params.path);
+        try {
+            const raw = await fs.readFile(filePath, 'utf-8');
+            const result = {};
+            for (const line of raw.split(/\r?\n/)) {
+                const parsed = parseEnvLine(line);
+                if (parsed)
+                    result[parsed.key] = parsed.value;
+            }
+            return result;
+        }
+        catch {
+            return {};
+        }
+    },
+    async write(params) {
+        const filePath = path.resolve(params.cwd, params.path);
+        for (const key of Object.keys(params.values)) {
+            if (!isValidKey(key)) {
+                throw ErrorFactory.createCliError(`Invalid env key: ${key}`);
+            }
+        }
+        const content = serializeEnv(params.values);
+        // Ensure parent dir exists for cases like ./.zintrust/.env.pull
+        await fs.mkdir(path.dirname(filePath), { recursive: true });
+        await fs.writeFile(filePath, content, 'utf-8');
+    },
+});
+export default EnvFile;

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

@@ -0,0 +1,24 @@
+export type SecretsProviderName = 'aws' | 'cloudflare';
+export type ManifestKeySpec = {
+    aws?: {
+        secretId: string;
+        jsonKey?: string;
+    };
+    cloudflare?: {
+        key: string;
+        namespaceId?: string;
+    };
+};
+export type SecretsManifest = {
+    provider: SecretsProviderName;
+    keys: Record<string, ManifestKeySpec>;
+};
+export declare const Manifest: Readonly<{
+    load(params: {
+        cwd: string;
+        path: string;
+        provider: SecretsProviderName;
+    }): Promise<SecretsManifest>;
+}>;
+export default Manifest;
+//# sourceMappingURL=Manifest.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"Manifest.d.ts","sourceRoot":"","sources":["../../../../src/toolkit/Secrets/Manifest.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,YAAY,CAAC;AAEvD,MAAM,MAAM,eAAe,GAAG;IAC5B,GAAG,CAAC,EAAE;QACJ,QAAQ,EAAE,MAAM,CAAC;QACjB,OAAO,CAAC,EAAE,MAAM,CAAC;KAClB,CAAC;IACF,UAAU,CAAC,EAAE;QACX,GAAG,EAAE,MAAM,CAAC;QACZ,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;CACvC,CAAC;AA+DF,eAAO,MAAM,QAAQ;iBACA;QACjB,GAAG,EAAE,MAAM,CAAC;QACZ,IAAI,EAAE,MAAM,CAAC;QACb,QAAQ,EAAE,mBAAmB,CAAC;KAC/B,GAAG,OAAO,CAAC,eAAe,CAAC;EA4B5B,CAAC;AAEH,eAAe,QAAQ,CAAC"}

package/src/toolkit/Secrets/Manifest.js

@@ -0,0 +1,71 @@
+import { ErrorFactory } from '../../exceptions/ZintrustError';
+import { fsPromises as fs } from '../../node-singletons/fs';
+import * as path from '../../node-singletons/path';
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const assertString = (value, name) => {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw ErrorFactory.createCliError(`Manifest: missing/invalid ${name}`);
+    }
+    return value;
+};
+const validateKeyName = (key) => {
+    if (!/^[A-Z0-9_]+$/.test(key)) {
+        throw ErrorFactory.createCliError(`Manifest: invalid env key: ${key}`);
+    }
+};
+const parseProvider = (parsed, fallback) => {
+    const provider = 'provider' in parsed && typeof parsed['provider'] === 'string'
+        ? parsed['provider']
+        : fallback;
+    if (provider !== 'aws' && provider !== 'cloudflare') {
+        throw ErrorFactory.createCliError('Manifest: provider must be aws|cloudflare');
+    }
+    return provider;
+};
+const parseKeySpec = (envKey, specUnknown) => {
+    const spec = {};
+    const awsUnknown = specUnknown['aws'];
+    if (isRecord(awsUnknown)) {
+        spec.aws = {
+            secretId: assertString(awsUnknown['secretId'], `keys.${envKey}.aws.secretId`),
+            jsonKey: typeof awsUnknown['jsonKey'] === 'string' && awsUnknown['jsonKey'].trim() !== ''
+                ? awsUnknown['jsonKey']
+                : undefined,
+        };
+    }
+    const cloudflareUnknown = specUnknown['cloudflare'];
+    if (isRecord(cloudflareUnknown)) {
+        spec.cloudflare = {
+            key: assertString(cloudflareUnknown['key'], `keys.${envKey}.cloudflare.key`),
+            namespaceId: typeof cloudflareUnknown['namespaceId'] === 'string' &&
+                cloudflareUnknown['namespaceId'].trim() !== ''
+                ? cloudflareUnknown['namespaceId']
+                : undefined,
+        };
+    }
+    return spec;
+};
+export const Manifest = Object.freeze({
+    async load(params) {
+        const filePath = path.resolve(params.cwd, params.path);
+        const raw = await fs.readFile(filePath, 'utf-8');
+        const parsedUnknown = JSON.parse(raw);
+        if (!isRecord(parsedUnknown)) {
+            throw ErrorFactory.createCliError('Manifest: expected JSON object');
+        }
+        const provider = parseProvider(parsedUnknown, params.provider);
+        const keysUnknown = parsedUnknown['keys'];
+        if (!isRecord(keysUnknown)) {
+            throw ErrorFactory.createCliError('Manifest: keys must be an object');
+        }
+        const keys = {};
+        for (const [envKey, specUnknown] of Object.entries(keysUnknown)) {
+            validateKeyName(envKey);
+            if (!isRecord(specUnknown))
+                throw ErrorFactory.createCliError(`Manifest: key ${envKey} must be an object`);
+            keys[envKey] = parseKeySpec(envKey, specUnknown);
+        }
+        return { provider, keys };
+    },
+});
+export default Manifest;

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;AAKH,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;AA0GF,eAAO,MAAM,cAAc;kBACL,WAAW,GAAG,OAAO,CAAC;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;kBAkB1D,WAAW,GAAG,OAAO,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;oBAoB7D,aAAa,GAAG;QAC9B,QAAQ,EAAE,mBAAmB,CAAC;QAC9B,EAAE,EAAE,OAAO,CAAC;QACZ,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB;EASD,CAAC;AAEH,eAAe,cAAc,CAAC"}