@zintrust/core 3.5.1 → 3.6.0

package/src/cli/commands/InitProxyCommand.js

@@ -0,0 +1,442 @@
+import { BaseCommand } from '../BaseCommand.js';
+import { PromptHelper } from '../PromptHelper.js';
+import { Logger } from '../../config/logger.js';
+import { copyFileSync, existsSync, mkdirSync, writeFileSync } from '../../node-singletons/fs.js';
+import { join } from '../../node-singletons/path.js';
+const DOCKER_COMPOSE_PROXY_TEMPLATE = `name: zintrust-proxies
+
+x-proxy-runtime: &proxy-runtime
+  image: \${PROXY_IMAGE:-zintrust-proxy:local}
+  restart: on-failure:3
+  ulimits:
+    nofile:
+      soft: 65535
+      hard: 65535
+  environment:
+    NODE_ENV: \${NODE_ENV:-development}
+    APP_NAME: \${APP_NAME:-ZinTrust}
+    APP_KEY: \${APP_KEY:-}
+  networks:
+    - zintrust-proxy-network
+
+services:
+  proxy-gateway:
+    image: \${PROXY_GATEWAY_IMAGE:-zintrust-proxy-gateway:local}
+    build:
+      context: ./docker/proxy-gateway
+      dockerfile: Dockerfile
+    restart: on-failure:3
+    ulimits:
+      nofile:
+        soft: 200000
+        hard: 200000
+    depends_on:
+      - proxy-mysql
+      - proxy-pg
+      - proxy-redis
+      - proxy-mongodb
+      - proxy-sqlserver
+      - proxy-smtp
+    ports:
+      - \${PROXY_GATEWAY_PORT:-8800}:8080
+    environment:
+      NODE_ENV: \${NODE_ENV:-development}
+    healthcheck:
+      disable: \${PROXY_GATEWAY_HEALTHCHECK_DISABLE:-false}
+      test: ['CMD-SHELL', 'wget -q -O /dev/null http://127.0.0.1:8080/health']
+      interval: 15s
+      timeout: 5s
+      retries: 5
+      start_period: 10s
+    networks:
+      - zintrust-proxy-network
+
+  proxy-mysql:
+    <<: *proxy-runtime
+    build:
+      context: .
+      dockerfile: Dockerfile
+      target: runtime
+    command: ['node', 'dist/bin/zin.js', 'proxy:mysql', '--host', '0.0.0.0', '--port', '8789']
+    expose:
+      - '8789'
+    environment:
+      NODE_ENV: \${NODE_ENV:-development}
+      APP_NAME: \${APP_NAME:-ZinTrust}
+      APP_KEY: \${APP_KEY:-}
+      MYSQL_PROXY_REQUIRE_SIGNING: true
+      MYSQL_PROXY_KEY_ID: \${MYSQL_PROXY_KEY_ID:-}
+      MYSQL_PROXY_SECRET: \${MYSQL_PROXY_SECRET:-}
+      MYSQL_PROXY_SIGNING_WINDOW_MS: \${MYSQL_PROXY_SIGNING_WINDOW_MS:-60000}
+      MYSQL_DB_HOST: \${MYSQL_DB_HOST:-\${DOCKER_DB_HOST:-host.docker.internal}}
+      MYSQL_DB_PORT: \${MYSQL_DB_PORT:-\${DB_PORT:-3306}}
+      MYSQL_DB_DATABASE: \${MYSQL_DB_DATABASE:-\${DB_DATABASE:-zintrust}}
+      MYSQL_DB_USERNAME: \${MYSQL_DB_USERNAME:-\${DB_USERNAME:-zintrust}}
+      MYSQL_DB_PASSWORD: \${MYSQL_DB_PASSWORD:-\${DB_PASSWORD:-secret}}
+      DB_HOST: \${DOCKER_DB_HOST:-host.docker.internal}
+      DB_PORT: \${DB_PORT:-3306}
+      DB_DATABASE: \${DB_DATABASE:-zintrust}
+      DB_USERNAME: \${DB_USERNAME:-zintrust}
+      DB_PASSWORD: \${DB_PASSWORD:-secret}
+      MYSQL_PROXY_POOL_LIMIT: \${MYSQL_PROXY_POOL_LIMIT:-100}
+    healthcheck:
+      disable: \${PROXY_HEALTHCHECK_DISABLE:-false}
+      test:
+        [
+          'CMD',
+          'node',
+          '-e',
+          "require('node:http').get('http://127.0.0.1:8789/health', (r)=>{process.exit(r.statusCode===200?0:1)}).on('error', ()=>process.exit(1));",
+        ]
+      interval: 20s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+  proxy-pg:
+    <<: *proxy-runtime
+    command: ['node', 'dist/bin/zin.js', 'proxy:postgres', '--host', '0.0.0.0', '--port', '8790']
+    expose:
+      - '8790'
+    environment:
+      NODE_ENV: \${NODE_ENV:-development}
+      APP_NAME: \${APP_NAME:-ZinTrust}
+      APP_KEY: \${APP_KEY:-}
+      POSTGRES_PROXY_REQUIRE_SIGNING: true
+      POSTGRES_PROXY_KEY_ID: \${POSTGRES_PROXY_KEY_ID:-}
+      POSTGRES_PROXY_SECRET: \${POSTGRES_PROXY_SECRET:-}
+      POSTGRES_PROXY_SIGNING_WINDOW_MS: \${POSTGRES_PROXY_SIGNING_WINDOW_MS:-60000}
+      DB_HOST: \${DOCKER_DB_HOST:-host.docker.internal}
+      DB_PORT_POSTGRESQL: \${POSTGRES_DB_PORT:-5432}
+      DB_DATABASE_POSTGRESQL: \${POSTGRES_DB_DATABASE:-postgres}
+      DB_USERNAME_POSTGRESQL: \${POSTGRES_DB_USERNAME:-postgres}
+      DB_PASSWORD_POSTGRESQL: \${POSTGRES_DB_PASSWORD:-postgres}
+      POSTGRES_PROXY_POOL_LIMIT: \${POSTGRES_PROXY_POOL_LIMIT:-100}
+    healthcheck:
+      disable: \${PROXY_HEALTHCHECK_DISABLE:-false}
+      test:
+        [
+          'CMD',
+          'node',
+          '-e',
+          "require('node:http').get('http://127.0.0.1:8790/health', (r)=>{process.exit(r.statusCode===200?0:1)}).on('error', ()=>process.exit(1));",
+        ]
+      interval: 20s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+  proxy-redis:
+    <<: *proxy-runtime
+    command: ['node', 'dist/bin/zin.js', 'proxy:redis', '--host', '0.0.0.0', '--port', '8791']
+    expose:
+      - '8791'
+    environment:
+      NODE_ENV: \${NODE_ENV:-development}
+      APP_NAME: \${APP_NAME:-ZinTrust}
+      APP_KEY: \${APP_KEY:-}
+      REDIS_PROXY_REQUIRE_SIGNING: true
+      REDIS_PROXY_KEY_ID: \${REDIS_PROXY_KEY_ID:-}
+      REDIS_PROXY_SECRET: \${REDIS_PROXY_SECRET:-}
+      REDIS_PROXY_SIGNING_WINDOW_MS: \${REDIS_PROXY_SIGNING_WINDOW_MS:-60000}
+      REDIS_PROXY_TARGET_HOST: \${REDIS_PROXY_TARGET_HOST:-\${DOCKER_REDIS_HOST:-host.docker.internal}}
+      REDIS_PROXY_TARGET_PORT: \${REDIS_PROXY_TARGET_PORT:-\${REDIS_PORT:-6379}}
+      REDIS_PROXY_TARGET_PASSWORD: \${REDIS_PROXY_TARGET_PASSWORD:-\${REDIS_PASSWORD:-}}
+      REDIS_PROXY_TARGET_DB: \${REDIS_PROXY_TARGET_DB:-\${REDIS_DB:-0}}
+      REDIS_HOST: \${DOCKER_REDIS_HOST:-host.docker.internal}
+      REDIS_PORT: \${REDIS_PORT:-6379}
+      REDIS_PASSWORD: \${REDIS_PASSWORD:-}
+      REDIS_DB: \${REDIS_DB:-0}
+    healthcheck:
+      disable: \${PROXY_HEALTHCHECK_DISABLE:-false}
+      test:
+        [
+          'CMD',
+          'node',
+          '-e',
+          "require('node:http').get('http://127.0.0.1:8791/health', (r)=>{process.exit(r.statusCode===200?0:1)}).on('error', ()=>process.exit(1));",
+        ]
+      interval: 20s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+  proxy-mongodb:
+    <<: *proxy-runtime
+    command: ['node', 'dist/bin/zin.js', 'proxy:mongodb', '--host', '0.0.0.0', '--port', '8792']
+    expose:
+      - '8792'
+    environment:
+      NODE_ENV: \${NODE_ENV:-development}
+      APP_NAME: \${APP_NAME:-ZinTrust}
+      APP_KEY: \${APP_KEY:-}
+      MONGODB_PROXY_REQUIRE_SIGNING: true
+      MONGODB_PROXY_KEY_ID: \${MONGODB_PROXY_KEY_ID:-}
+      MONGODB_PROXY_SECRET: \${MONGODB_PROXY_SECRET:-}
+      MONGODB_PROXY_SIGNING_WINDOW_MS: \${MONGODB_PROXY_SIGNING_WINDOW_MS:-60000}
+      MONGO_URI: \${MONGODB_PROXY_TARGET_URI:-mongodb://host.docker.internal:27017}
+      MONGO_DB: \${MONGODB_PROXY_TARGET_DB:-zintrust}
+    healthcheck:
+      disable: \${PROXY_HEALTHCHECK_DISABLE:-false}
+      test:
+        [
+          'CMD',
+          'node',
+          '-e',
+          "require('node:http').get('http://127.0.0.1:8792/health', (r)=>{process.exit(r.statusCode===200?0:1)}).on('error', ()=>process.exit(1));",
+        ]
+      interval: 20s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+  proxy-sqlserver:
+    <<: *proxy-runtime
+    command: ['node', 'dist/bin/zin.js', 'proxy:sqlserver', '--host', '0.0.0.0', '--port', '8793']
+    expose:
+      - '8793'
+    environment:
+      NODE_ENV: \${NODE_ENV:-development}
+      APP_NAME: \${APP_NAME:-ZinTrust}
+      APP_KEY: \${APP_KEY:-}
+      SQLSERVER_PROXY_REQUIRE_SIGNING: true
+      SQLSERVER_PROXY_KEY_ID: \${SQLSERVER_PROXY_KEY_ID:-}
+      SQLSERVER_PROXY_SECRET: \${SQLSERVER_PROXY_SECRET:-}
+      SQLSERVER_PROXY_SIGNING_WINDOW_MS: \${SQLSERVER_PROXY_SIGNING_WINDOW_MS:-60000}
+      DB_HOST_MSSQL: \${SQLSERVER_DB_HOST:-host.docker.internal}
+      DB_PORT_MSSQL: \${SQLSERVER_DB_PORT:-1433}
+      DB_DATABASE_MSSQL: \${SQLSERVER_DB_DATABASE:-zintrust}
+      DB_USERNAME_MSSQL: \${SQLSERVER_DB_USERNAME:-sa}
+      DB_PASSWORD_MSSQL: \${SQLSERVER_DB_PASSWORD:-}
+      SQLSERVER_PROXY_POOL_LIMIT: \${SQLSERVER_PROXY_POOL_LIMIT:-100}
+    healthcheck:
+      disable: \${PROXY_HEALTHCHECK_DISABLE:-false}
+      test:
+        [
+          'CMD',
+          'node',
+          '-e',
+          "require('node:http').get('http://127.0.0.1:8793/health', (r)=>{process.exit(r.statusCode===200?0:1)}).on('error', ()=>process.exit(1));",
+        ]
+      interval: 20s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+  proxy-smtp:
+    <<: *proxy-runtime
+    command: ['node', 'dist/bin/zin.js', 'proxy:smtp', '--host', '0.0.0.0', '--port', '8794']
+    expose:
+      - '8794'
+    environment:
+      NODE_ENV: \${NODE_ENV:-development}
+      APP_NAME: \${APP_NAME:-ZinTrust}
+      APP_KEY: \${APP_KEY:-}
+      SMTP_PROXY_REQUIRE_SIGNING: true
+      SMTP_PROXY_KEY_ID: \${SMTP_PROXY_KEY_ID:-}
+      SMTP_PROXY_SECRET: \${SMTP_PROXY_SECRET:-}
+      SMTP_PROXY_SIGNING_WINDOW_MS: \${SMTP_PROXY_SIGNING_WINDOW_MS:-60000}
+      MAIL_DRIVER: \${MAIL_DRIVER:-smtp}
+      MAIL_CONNECTION: \${MAIL_CONNECTION:-smtp}
+      MAIL_HOST: \${MAIL_HOST}
+      MAIL_PORT: \${MAIL_PORT:-587}
+      MAIL_SECURE: \${MAIL_SECURE:-false}
+      MAIL_USERNAME: \${MAIL_USERNAME}
+      MAIL_PASSWORD: \${MAIL_PASSWORD}
+      MAIL_FROM_ADDRESS: \${MAIL_FROM_ADDRESS}
+      MAIL_FROM_NAME: \${MAIL_FROM_NAME:-ZinTrust}
+    healthcheck:
+      disable: \${PROXY_HEALTHCHECK_DISABLE:-false}
+      test:
+        [
+          'CMD',
+          'node',
+          '-e',
+          "require('node:http').get('http://127.0.0.1:8794/health', (r)=>{process.exit(r.statusCode===200?0:1)}).on('error', ()=>process.exit(1));",
+        ]
+      interval: 20s
+      timeout: 5s
+      retries: 5
+      start_period: 15s
+
+networks:
+  zintrust-proxy-network:
+    driver: bridge
+`;
+const NGINX_PROXY_GATEWAY_TEMPLATE = `worker_processes auto;
+worker_rlimit_nofile 200000;
+
+events {
+  worker_connections 8192;
+  multi_accept on;
+  use epoll;
+}
+
+http {
+  include /etc/nginx/mime.types;
+  default_type application/octet-stream;
+
+  sendfile on;
+  tcp_nopush on;
+  tcp_nodelay on;
+  keepalive_timeout 30s;
+  keepalive_requests 10000;
+
+  client_max_body_size 2m;
+  client_body_buffer_size 128k;
+
+  server_tokens off;
+  types_hash_max_size 4096;
+
+  resolver 127.0.0.11 valid=10s ipv6=off;
+  resolver_timeout 2s;
+
+  access_log /var/log/nginx/access.log;
+  error_log /var/log/nginx/error.log warn;
+
+  server {
+    listen 8080 reuseport backlog=65535;
+    server_name _;
+
+    proxy_http_version 1.1;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+    proxy_set_header Connection "";
+
+    proxy_connect_timeout 2s;
+    proxy_send_timeout 30s;
+    proxy_read_timeout 30s;
+
+    proxy_buffering on;
+    proxy_request_buffering on;
+    proxy_buffer_size 8k;
+    proxy_buffers 16 16k;
+    proxy_busy_buffers_size 64k;
+
+    proxy_next_upstream error timeout http_502 http_503 http_504;
+    proxy_next_upstream_tries 3;
+    proxy_next_upstream_timeout 5s;
+
+    location = /health {
+      default_type application/json;
+      return 200 '{"status":"ok","service":"proxy-gateway"}';
+    }
+
+    location /mysql {
+      rewrite ^/mysql/?(.*)$ /$1 break;
+      proxy_pass http://proxy-mysql:8789;
+    }
+
+    location /postgres {
+      rewrite ^/postgres/?(.*)$ /$1 break;
+      proxy_pass http://proxy-pg:8790;
+    }
+
+    location /redis {
+      rewrite ^/redis/?(.*)$ /$1 break;
+      proxy_pass http://proxy-redis:8791;
+    }
+
+    location /mongodb {
+      rewrite ^/mongodb/?(.*)$ /$1 break;
+      proxy_pass http://proxy-mongodb:8792;
+    }
+
+    location /sqlserver {
+      rewrite ^/sqlserver/?(.*)$ /$1 break;
+      proxy_pass http://proxy-sqlserver:8793;
+    }
+
+    location /smtp {
+      rewrite ^/smtp/?(.*)$ /$1 break;
+      proxy_pass http://proxy-smtp:8794;
+    }
+  }
+}
+`;
+const NGINX_PROXY_DOCKERFILE_TEMPLATE = `FROM nginx:1.27-alpine
+
+COPY nginx.conf /etc/nginx/nginx.conf
+`;
+const backupSuffix = () => new Date().toISOString().replace(/[:.]/g, '-');
+const backupFileIfExists = (filePath) => {
+    if (!existsSync(filePath))
+        return;
+    const backupPath = `${filePath}.bak.${backupSuffix()}`;
+    copyFileSync(filePath, backupPath);
+    Logger.info(`🗂️ Backup created: ${backupPath}`);
+};
+async function writeDockerComposeFile(cwd) {
+    const composePath = join(cwd, 'docker-compose.proxy.yml');
+    let shouldWrite = true;
+    if (existsSync(composePath)) {
+        shouldWrite = await PromptHelper.confirm('docker-compose.proxy.yml already exists. Overwrite?', false);
+    }
+    if (shouldWrite) {
+        backupFileIfExists(composePath);
+        writeFileSync(composePath, DOCKER_COMPOSE_PROXY_TEMPLATE);
+        Logger.info('✅ Created docker-compose.proxy.yml');
+    }
+    else {
+        Logger.info('Skipped docker-compose.proxy.yml');
+    }
+}
+async function writeNginxConfig(cwd) {
+    const gatewayDir = join(cwd, 'docker', 'proxy-gateway');
+    const nginxPath = join(gatewayDir, 'nginx.conf');
+    if (!existsSync(gatewayDir)) {
+        mkdirSync(gatewayDir, { recursive: true });
+    }
+    let shouldWrite = true;
+    if (existsSync(nginxPath)) {
+        shouldWrite = await PromptHelper.confirm('docker/proxy-gateway/nginx.conf already exists. Overwrite?', false);
+    }
+    if (shouldWrite) {
+        backupFileIfExists(nginxPath);
+        writeFileSync(nginxPath, NGINX_PROXY_GATEWAY_TEMPLATE);
+        Logger.info('✅ Created docker/proxy-gateway/nginx.conf');
+    }
+    else {
+        Logger.info('Skipped docker/proxy-gateway/nginx.conf');
+    }
+}
+async function writeNginxDockerfile(cwd) {
+    const gatewayDir = join(cwd, 'docker', 'proxy-gateway');
+    const dockerfilePath = join(gatewayDir, 'Dockerfile');
+    if (!existsSync(gatewayDir)) {
+        mkdirSync(gatewayDir, { recursive: true });
+    }
+    let shouldWrite = true;
+    if (existsSync(dockerfilePath)) {
+        shouldWrite = await PromptHelper.confirm('docker/proxy-gateway/Dockerfile already exists. Overwrite?', false);
+    }
+    if (shouldWrite) {
+        backupFileIfExists(dockerfilePath);
+        writeFileSync(dockerfilePath, NGINX_PROXY_DOCKERFILE_TEMPLATE);
+        Logger.info('✅ Created docker/proxy-gateway/Dockerfile');
+    }
+    else {
+        Logger.info('Skipped docker/proxy-gateway/Dockerfile');
+    }
+}
+export const InitProxyCommand = Object.freeze({
+    create() {
+        return BaseCommand.create({
+            name: 'init:proxy',
+            aliases: ['init:cp', 'init:container-proxies', 'init:py'],
+            description: 'Initialize container-based proxy stack infrastructure',
+            async execute() {
+                Logger.info('Initializing container-based proxy stack infrastructure...');
+                const cwd = process.cwd();
+                await writeDockerComposeFile(cwd);
+                await writeNginxConfig(cwd);
+                await writeNginxDockerfile(cwd);
+                Logger.info('✅ Proxy stack scaffolding complete.');
+                Logger.info('Run with: zin cp up -d');
+                await Promise.resolve();
+            },
+        });
+    },
+});

package/src/cli/commands/JwtDevCommand.d.ts

@@ -0,0 +1,8 @@
+/**
+ * JWT Dev Command
+ * Mint a local development JWT for quick manual API testing.
+ */
+import { type IBaseCommand } from '../BaseCommand.js';
+export declare const JwtDevCommand: IBaseCommand;
+export default JwtDevCommand;
+//# sourceMappingURL=JwtDevCommand.d.ts.map

package/src/cli/commands/JwtDevCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"JwtDevCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/JwtDevCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAoC,KAAK,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAyHvF,eAAO,MAAM,aAAa,EAAE,YAgD3B,CAAC;AAEF,eAAe,aAAa,CAAC"}

package/src/cli/commands/JwtDevCommand.js

@@ -0,0 +1,133 @@
+/**
+ * JWT Dev Command
+ * Mint a local development JWT for quick manual API testing.
+ */
+import { isUndefinedOrNull } from '../../helper/index.js';
+import { BaseCommand } from '../BaseCommand.js';
+import { appConfig } from '../../config/app.js';
+import { securityConfig } from '../../config/security.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import * as crypto from '../../node-singletons/crypto.js';
+import { JwtManager } from '../../security/JwtManager.js';
+const sha256Hex = (value) => {
+    return crypto.createHash('sha256').update(value).digest('hex');
+};
+const optionalTrimmed = (value) => {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+};
+const buildPayload = (options) => {
+    const payload = {};
+    const sub = optionalTrimmed(options.sub);
+    if (!isUndefinedOrNull(sub))
+        payload.sub = sub;
+    const email = optionalTrimmed(options.email);
+    if (!isUndefinedOrNull(email))
+        payload['email'] = email;
+    const role = optionalTrimmed(options.role);
+    if (!isUndefinedOrNull(role))
+        payload['role'] = role;
+    const deviceId = optionalTrimmed(options.deviceId);
+    if (!isUndefinedOrNull(deviceId))
+        payload['deviceId'] = deviceId;
+    const tenantId = optionalTrimmed(options.tenantId);
+    if (!isUndefinedOrNull(tenantId))
+        payload['tenantId'] = tenantId;
+    const tz = optionalTrimmed(options.tz);
+    if (!isUndefinedOrNull(tz))
+        payload['tz'] = tz;
+    const uaHash = optionalTrimmed(options.uaHash);
+    if (isUndefinedOrNull(uaHash)) {
+        const ua = optionalTrimmed(options.ua);
+        if (ua !== undefined) {
+            payload['uaHash'] = sha256Hex(ua);
+        }
+    }
+    else {
+        payload['uaHash'] = uaHash;
+    }
+    return payload;
+};
+const parseExpiresToSeconds = (value) => {
+    const raw = typeof value === 'string' ? value.trim() : '';
+    if (raw === '')
+        return 60 * 60;
+    // Allow raw seconds
+    if (/^\d+$/.test(raw)) {
+        const seconds = Number.parseInt(raw, 10);
+        if (!Number.isFinite(seconds) || seconds <= 0) {
+            throw ErrorFactory.createCliError(`Invalid --expires '${raw}'. Must be > 0 seconds.`);
+        }
+        return seconds;
+    }
+    const match = /^(\d+)([smhd])$/i.exec(raw);
+    if (!match) {
+        throw ErrorFactory.createCliError(`Invalid --expires '${raw}'. Use seconds (e.g. 3600) or a duration like 30m, 1h, 7d.`);
+    }
+    const amount = Number.parseInt(match[1] ?? '', 10);
+    const unit = (match[2] ?? '').toLowerCase();
+    if (!Number.isFinite(amount) || amount <= 0) {
+        throw ErrorFactory.createCliError(`Invalid --expires '${raw}'. Must be > 0.`);
+    }
+    const multipliers = {
+        s: 1,
+        m: 60,
+        h: 60 * 60,
+        d: 24 * 60 * 60,
+    };
+    const multiplier = multipliers[unit];
+    if (multiplier === undefined) {
+        throw ErrorFactory.createCliError(`Invalid --expires '${raw}'. Supported units: s, m, h, d (e.g. 30m, 1h).`);
+    }
+    return amount * multiplier;
+};
+const assertNotProduction = (allowProduction) => {
+    if (!appConfig.isProduction())
+        return;
+    if (allowProduction === true)
+        return;
+    throw ErrorFactory.createCliError("Refusing to mint a dev JWT in production. Use --allow-production only if you know what you're doing.");
+};
+export const JwtDevCommand = Object.freeze(BaseCommand.create({
+    name: 'jwt:dev',
+    description: 'Mint a local development JWT (for manual API testing)',
+    aliases: ['jwt:token', 'jwt:mint'],
+    addOptions: (command) => {
+        command
+            .option('--sub <sub>', 'JWT subject claim (default: 1)', '1')
+            .option('--email <email>', 'Email claim')
+            .option('--role <role>', 'Role claim')
+            .option('--device-id <id>', 'Attach deviceId claim (for bulletproof auth)')
+            .option('--tenant-id <id>', 'Attach tenantId claim')
+            .option('--tz <tz>', 'Attach timezone claim (tz)')
+            .option('--ua <ua>', 'Compute and attach uaHash claim from a User-Agent string')
+            .option('--ua-hash <hash>', 'Attach uaHash claim directly (hex)')
+            .option('--expires <duration>', "Expiry: seconds or 30m/1h/7d (default: '1h')", '1h')
+            .option('--json', 'Output machine-readable JSON')
+            .option('--allow-production', 'Allow running in production (dangerous)');
+    },
+    execute: async (options) => {
+        assertNotProduction(options.allowProduction);
+        const expiresInSeconds = parseExpiresToSeconds(options.expires);
+        const payload = buildPayload(options);
+        const token = await JwtManager.signAccessToken(payload, expiresInSeconds);
+        /* eslint-disable no-console */
+        if (options.json === true) {
+            const nowSeconds = Math.floor(Date.now() / 1000);
+            console.log(JSON.stringify({
+                token,
+                algorithm: securityConfig.jwt.algorithm,
+                expiresIn: expiresInSeconds,
+                issuedAt: nowSeconds,
+                expiresAt: nowSeconds + expiresInSeconds,
+                payload,
+            }));
+            return;
+        }
+        console.log(token);
+        /* eslint-enable no-console */
+    },
+}));
+export default JwtDevCommand;

package/src/cli/commands/KeyGenerateCommand.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Key Generate Command
+ * Generates and sets the application key
+ */
+import type { IBaseCommand } from '../BaseCommand.js';
+export declare const KeyGenerateCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+//# sourceMappingURL=KeyGenerateCommand.d.ts.map

package/src/cli/commands/KeyGenerateCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KeyGenerateCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/KeyGenerateCommand.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAkB,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAQrE,eAAO,MAAM,kBAAkB;cACnB,YAAY;EAmEtB,CAAC"}

package/src/cli/commands/KeyGenerateCommand.js

@@ -0,0 +1,76 @@
+/**
+ * Key Generate Command
+ * Generates and sets the application key
+ */
+import { BaseCommand } from '../BaseCommand.js';
+import { Logger } from '../../config/logger.js';
+import * as crypto from '../../node-singletons/crypto.js';
+import { fsPromises as fs } from '../../node-singletons/fs.js';
+import * as path from '../../node-singletons/path.js';
+export const KeyGenerateCommand = Object.freeze({
+    create() {
+        return BaseCommand.create({
+            name: 'key:generate',
+            description: 'Set the application key',
+            addOptions: (command) => {
+                command.option('--show', 'Display the key instead of modifying files');
+                command.option('--force', 'Force the operation to run when in production');
+            },
+            execute: async (options) => {
+                const key = generateRandomKey();
+                if (options['show'] === true) {
+                    Logger.info(`Application key: [${key}]`);
+                    return;
+                }
+                const envPath = path.resolve(process.cwd(), '.env');
+                try {
+                    let envContent = '';
+                    try {
+                        envContent = await fs.readFile(envPath, 'utf-8');
+                    }
+                    catch (error) {
+                        Logger.warn('Could not read .env file, attempting to create from example', { error });
+                        // If .env doesn't exist, try to copy .env.example
+                        const examplePath = path.resolve(process.cwd(), '.env.example');
+                        try {
+                            envContent = await fs.readFile(examplePath, 'utf-8');
+                            await fs.writeFile(envPath, envContent);
+                            Logger.info('.env file created from .env.example');
+                        }
+                        catch (copyError) {
+                            Logger.error('Failed to create .env from example', { error: copyError });
+                            Logger.warn('.env file not found and .env.example not found. Creating new .env file.');
+                        }
+                    }
+                    // Backup existing key if present
+                    const appKeyMatch = /^APP_KEY=(.*)$/m.exec(envContent);
+                    const currentKey = appKeyMatch?.[1]?.trim();
+                    if (currentKey !== undefined && currentKey.length > 0) {
+                        const oldKey = currentKey;
+                        if (envContent.includes('APP_KEY_BK=')) {
+                            envContent = envContent.replace(/^APP_KEY_BK=.*$/m, `APP_KEY_BK=${oldKey}`);
+                        }
+                        else {
+                            envContent += `\nAPP_KEY_BK=${oldKey}`;
+                        }
+                    }
+                    if (envContent.includes('APP_KEY=')) {
+                        const regex = /^APP_KEY=.*/m;
+                        envContent = envContent.replace(regex, `APP_KEY=${key}`);
+                    }
+                    else {
+                        envContent += `\nAPP_KEY=${key}\n`;
+                    }
+                    await fs.writeFile(envPath, envContent);
+                    Logger.info(`Application key set successfully. [${key}]`);
+                }
+                catch (error) {
+                    Logger.error('Failed to update .env file', error);
+                }
+            },
+        });
+    },
+});
+function generateRandomKey() {
+    return 'base64:' + crypto.randomBytes(32).toString('base64');
+}

package/src/cli/commands/KvProxyCommand.d.ts

@@ -0,0 +1,6 @@
+import type { IBaseCommand } from '../BaseCommand.js';
+export declare const KvProxyCommand: Readonly<{
+    create(): IBaseCommand;
+}>;
+export default KvProxyCommand;
+//# sourceMappingURL=KvProxyCommand.d.ts.map

package/src/cli/commands/KvProxyCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"KvProxyCommand.d.ts","sourceRoot":"","sources":["../../../../src/cli/commands/KvProxyCommand.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAmGrD,eAAO,MAAM,cAAc;cACf,YAAY;EAkBtB,CAAC;AAEH,eAAe,cAAc,CAAC"}