securenow 8.9.0 → 8.10.0

package/NPM_README.md

@@ -306,6 +306,36 @@ X-SecureNow-App-Key: <app-uuid>
 
 CLI: `npx securenow event send auth.login.failure --user u_1 --ip 1.2.3.4 --attrs reason=bad_token`
 
+### Build alert SQL from the installed telemetry contract
+
+The NPM package ships the exact ClickHouse table/field contract used for alert-rule authoring.
+Agents should read it instead of guessing SQL columns:
+
+```bash
+# Offline: installed SDK schema, tenant scope, timestamp types, event mappings, and templates
+npx securenow telemetry schema --json
+
+# Connected app: names/types/counts observed in real telemetry (never attribute values)
+npx securenow telemetry fields --app <app-key> --env production --since 24h --json
+
+# Prove candidate SQL against the backend before creating anything
+npx securenow alerts rules validate --sql @rule.sql --app <app-key>
+```
+
+The same local contract is available programmatically:
+
+```js
+const telemetrySchema = require('securenow/telemetry-schema');
+```
+
+Use the installed schema to draft SQL, live field discovery to verify that optional/custom
+fields are actually emitted, and `alerts rules validate` to prove the query compiles and runs.
+A field absent from the selected live window is **unverified**, not necessarily unsupported.
+Mark detections `NEEDS_INSTRUMENTATION` when the repository must add a `track()` event,
+`NEEDS_BASELINE` when only the threshold remains unknown, and `READY` only after field
+verification plus SQL validation. See `node_modules/securenow/TELEMETRY-SQL.md` for tables,
+timestamp handling, privacy rules, templates, and the full test-to-production lifecycle.
+
 ```bash
 # Create a custom detection rule from your own SQL (new in 8.1)
 npx securenow alerts rules create \

package/README.md

@@ -223,6 +223,10 @@ npx securenow logs                  # tail logs
 npx securenow status                # dashboard summary
 npx securenow doctor                # diagnose config + connectivity
 
+# Detection authoring contract
+npx securenow telemetry schema --json
+npx securenow telemetry fields --app <key> --env production --since 24h --json
+
 # Security
 npx securenow firewall status --env production
 npx securenow blocklist add 1.2.3.4 --reason "scanner"
@@ -363,6 +367,16 @@ After install, the `securenow` CLI is available via `npx securenow` or globally
 | `securenow analytics` | Response code analytics |
 | `securenow status` | Dashboard summary |
 
+### Detection authoring
+
+| Command | Description |
+|---|---|
+| `securenow telemetry schema --json` | Offline, versioned tables, fields, event mappings, tenant scope, and SQL requirements |
+| `securenow telemetry fields --app <key> --env production --since 24h --json` | Fields, types, and custom event names actually observed for an authorized app; values are never returned |
+| `securenow alerts rules validate --sql @rule.sql --app <key>` | Compile and dry-run candidate SQL before creating a rule |
+
+The machine-readable contract is also exported as `require('securenow/telemetry-schema')`; the full workflow and SQL examples are in [`TELEMETRY-SQL.md`](./TELEMETRY-SQL.md).
+
 ### Detect & Respond
 
 | Command | Description |

package/SKILL-API.md

@@ -453,6 +453,29 @@ Requires peer dep: `npm install @google-cloud/compute`
 
 Logging is enabled by default (`config.logging.enabled: true`). Logs are exported to your OTLP collector alongside traces.
 
+### Telemetry contract for alert-rule agents
+
+The package exports a versioned, machine-readable description of the ClickHouse tables,
+timestamp types, map access, tenant scope, automatic fields, custom-event mapping, client-IP
+expression, and safe SQL templates:
+
+```js
+const telemetrySchema = require('securenow/telemetry-schema');
+```
+
+The CLI exposes the same contract and can compare it with fields observed in the connected app:
+
+```bash
+securenow telemetry schema --json
+securenow telemetry fields --app <key> --env production --since 24h --json
+securenow alerts rules validate --sql @rule.sql --app <key>
+```
+
+The first command works offline. Live discovery returns field names/types/counts and event names,
+never values. A coding agent should inspect the customer repository for routes and `track()` calls,
+use the local contract to construct SQL, use live discovery to verify emitted fields, then validate
+the candidate query. Full guidance is shipped in `TELEMETRY-SQL.md`.
+
 ### Get a Logger
 
 ```javascript

package/SKILL-CLI.md

@@ -250,9 +250,27 @@ MCP parity:
 
 Write tools still require `confirm:true` plus a reason. False positives should stay restrictive to the app, alert rule, path, method/status, user-agent, body pattern, or other exact evidence the AI report supports. Notification IP investigations can include `metadata.matchedSubdetectors`; prefer that exact field over inferring which subdetector fired from the title or sample body.
 
-### Alerts
-
-```bash
+### Alerts
+
+Before authoring any alert SQL, load the contract shipped by the installed package and compare
+it with fields actually observed for the selected application:
+
+```bash
+securenow telemetry schema --json
+securenow telemetry schema logs --json
+securenow telemetry schema traces --json
+securenow telemetry schema events --json
+securenow telemetry fields --app <key> --env production --since 24h --source all --json
+```
+
+`telemetry schema` is offline and versioned with the SDK. `telemetry fields` requires admin
+auth and telemetry access; it returns names, map scopes, data types, occurrence counts, and
+custom event types, but never customer attribute values. Absence means "not observed in this
+window," not "unsupported." Use only documented fields, and label a rule `READY` only when
+its fields were observed and `alerts rules validate` succeeds. Otherwise label it
+`NEEDS_INSTRUMENTATION`, `NEEDS_BASELINE`, or `NEEDS_CUSTOMER_DECISION` as appropriate.
+
+```bash
 securenow alerts                             # list alert rules (default)
 securenow alerts rules                       # list alert rules (columns: Status, Applications, Schedule)
 securenow alerts rules validate \            # dry-run a candidate query BEFORE creating any rule

package/TELEMETRY-SQL.md

@@ -0,0 +1,98 @@
+# SecureNow telemetry and alert SQL contract
+
+This document is the canonical starting point for humans and coding agents that construct SecureNow alert rules from a customer codebase. The same contract is available as machine-readable JSON:
+
+```bash
+npx securenow telemetry schema --json
+```
+
+The SDK contract tells you which tables and fields are supported. Live field discovery tells you which fields the connected application has actually emitted:
+
+```bash
+npx securenow telemetry fields --app <app-key> --env production --since 24h --json
+```
+
+Do not treat a documented optional or custom field as present until it appears in live discovery or the codebase contains the corresponding instrumentation.
+
+## Alert-rule SQL requirements
+
+- Use ClickHouse SQL.
+- Query `signoz_logs.distributed_logs_v2` for custom events and logs.
+- Query `signoz_traces.distributed_signoz_index_v3` for HTTP spans and traces.
+- Keep `__USER_APP_KEYS__` in every customer-scoped query.
+- For logs, scope with `resources_string['service.name'] IN (__USER_APP_KEYS__)`.
+- For traces, scope with `` `resource_string_service$$name` IN (__USER_APP_KEYS__) ``.
+- Bound the query with a time window.
+- Return an `ip` column and exclude empty IPs when the rule can trigger IP remediation.
+- Use the correct timestamp representation: log timestamps are UInt64 nanoseconds; trace timestamps are `DateTime64(9)`.
+- Validate SQL against the connected SecureNow backend before creating the rule.
+
+## Authoring workflow
+
+```bash
+# 1. Read the exact contract shipped with the installed SDK.
+npx securenow telemetry schema --json
+
+# 2. Discover actual fields and types emitted by this app.
+npx securenow telemetry fields --app <app-key> --env production --since 24h --json
+
+# 3. Avoid duplicating existing coverage.
+npx securenow alerts rules --json
+
+# 4. Validate the candidate before any write.
+npx securenow alerts rules validate --sql @rule.sql --app <app-key>
+
+# 5. Create in detect-only mode and dry-run it.
+npx securenow alerts rules create --name "Auth: OTP send abuse" --sql @rule.sql --apps <app-key>
+npx securenow alerts rules test <rule-id> --mode dry_run --wait
+
+# New custom rules start in detect-only test mode. Promote only after reviewing real matches and false positives.
+npx securenow alerts rules promote <rule-id>
+```
+
+`telemetry schema` works offline. `telemetry fields`, alert-rule validation, and rule management require admin authentication and access to the selected app.
+
+## Custom security events
+
+The SDK accepts arbitrary event names and scalar custom attributes:
+
+```js
+const { track } = require('securenow/events');
+
+track('auth.otp.send.result', {
+  userId,
+  sessionId,
+  ip,
+  attributes: {
+    channel: 'sms',
+    provider: 'twilio',
+    provider_result: 'accepted',
+    destination_hash: sha256(normalizedDestination),
+    cost_units: 1,
+  },
+});
+```
+
+Event properties are stored in the logs table:
+
+| SDK property | Alert SQL field |
+|---|---|
+| Event type | `attributes_string['event.type']` |
+| `userId` | `attributes_string['enduser.id']` |
+| `sessionId` | `attributes_string['session.id']` |
+| `ip` | `attributes_string['http.client_ip']` |
+| `userAgent` | `attributes_string['http.user_agent']` |
+| String custom attribute | `attributes_string['<key>']` |
+| Numeric custom attribute | `attributes_number['<key>']` |
+| Boolean custom attribute | `attributes_bool['<key>']` |
+
+Never send raw passwords, tokens, OTPs, session secrets, email addresses, phone numbers, or other unnecessary personal data. Hash destinations when correlation is required.
+
+## Readiness labels for generated detections
+
+- `READY`: every queried field was observed and the SQL validation passed.
+- `NEEDS_INSTRUMENTATION`: the codebase must add one or more `track()` events or attributes.
+- `NEEDS_BASELINE`: fields and SQL are valid, but the threshold needs production traffic history.
+- `NEEDS_CUSTOMER_DECISION`: cost limits or mitigation behavior require customer approval.
+
+Static repository analysis can produce candidate SQL and exact instrumentation TODOs. Only live field discovery plus SQL validation can justify the `READY` label.

package/cli/telemetry.js

@@ -0,0 +1,199 @@
+'use strict';
+
+const schemaContract = require('../telemetry-schema.json');
+const { api, requireAuth } = require('./client');
+const config = require('./config');
+const appConfig = require('../app-config');
+const ui = require('./ui');
+
+function parseDurationToMinutes(value) {
+  if (value == null || value === '') return 24 * 60;
+  const match = String(value).trim().match(/^(\d+)\s*(m|h|d)?$/i);
+  if (!match) return null;
+  const amount = Number.parseInt(match[1], 10);
+  const unit = String(match[2] || 'm').toLowerCase();
+  if (amount < 1) return null;
+  if (unit === 'm') return amount;
+  if (unit === 'h') return amount * 60;
+  if (unit === 'd') return amount * 24 * 60;
+  return null;
+}
+
+function filteredSchema(section) {
+  const selected = String(section || 'all').toLowerCase();
+  if (selected === 'all') return schemaContract;
+  if (selected === 'logs' || selected === 'traces') {
+    return {
+      contract: schemaContract.contract,
+      schemaVersion: schemaContract.schemaVersion,
+      dialect: schemaContract.dialect,
+      ruleContract: schemaContract.ruleContract,
+      table: schemaContract.tables[selected],
+      clientIp: schemaContract.clientIp,
+      templates: schemaContract.templates,
+    };
+  }
+  if (selected === 'events') {
+    return {
+      contract: schemaContract.contract,
+      schemaVersion: schemaContract.schemaVersion,
+      dialect: schemaContract.dialect,
+      ruleContract: schemaContract.ruleContract,
+      storageTable: schemaContract.tables.logs,
+      customEvents: schemaContract.customEvents,
+      templates: { eventFailuresByIp: schemaContract.templates.eventFailuresByIp },
+    };
+  }
+  return null;
+}
+
+async function schema(args, flags) {
+  const section = args[0] || flags.source || 'all';
+  const contract = filteredSchema(section);
+  if (!contract) {
+    ui.error('Unknown schema section. Use all, logs, traces, or events.');
+    process.exitCode = 1;
+    return;
+  }
+
+  if (flags.json) {
+    ui.json(contract);
+    return;
+  }
+
+  console.log('');
+  ui.heading('SecureNow Telemetry & Alert SQL Contract');
+  console.log('');
+  ui.keyValue([
+    ['Schema version', schemaContract.schemaVersion],
+    ['SQL dialect', schemaContract.dialect],
+    ['Tenant placeholder', schemaContract.ruleContract.tenantPlaceholder],
+    ['Required result', 'ip column for IP-remediation rules'],
+  ]);
+
+  const tables = section === 'all'
+    ? Object.entries(schemaContract.tables)
+    : section === 'events'
+      ? [['logs', schemaContract.tables.logs]]
+      : [[section, schemaContract.tables[section]]];
+  console.log('');
+  ui.subheading('Tables');
+  console.log('');
+  ui.table(
+    ['Signal', 'Table', 'Timestamp', 'Tenant scope'],
+    tables.map(([name, table]) => [
+      name,
+      table.name,
+      `${table.timestamp.type} (${table.timestamp.unit})`,
+      table.tenantExpression,
+    ])
+  );
+
+  if (section === 'all' || section === 'events') {
+    console.log('');
+    ui.subheading('Custom event mapping');
+    console.log('');
+    ui.table(
+      ['SDK property', 'SQL field'],
+      Object.entries(schemaContract.customEvents.propertyMapping).map(([property, field]) => [property, field])
+    );
+  }
+
+  console.log('');
+  ui.info('Machine-readable: securenow telemetry schema --json');
+  ui.info('Live verification: securenow telemetry fields --app <key> --env production --since 24h --json');
+  ui.info('Full guide: node_modules/securenow/TELEMETRY-SQL.md');
+  console.log('');
+}
+
+async function fields(args, flags) {
+  requireAuth();
+  const appKey = flags.app || config.getDefaultApp() || appConfig.resolveAppKey();
+  if (!appKey) {
+    ui.error('No app specified. Use --app <key>, run `securenow app connect`, or set a default app.');
+    process.exitCode = 1;
+    return;
+  }
+
+  const sinceMinutes = parseDurationToMinutes(flags.since || '24h');
+  if (sinceMinutes == null || sinceMinutes > 30 * 24 * 60) {
+    ui.error('Invalid --since value. Use a duration such as 30m, 24h, or 7d (maximum 30d).');
+    process.exitCode = 1;
+    return;
+  }
+  const source = String(flags.source || args[0] || 'all').toLowerCase();
+  if (!['all', 'logs', 'traces'].includes(source)) {
+    ui.error('Invalid --source. Use all, logs, or traces.');
+    process.exitCode = 1;
+    return;
+  }
+  const parsedLimit = Number.parseInt(flags.limit || '200', 10);
+  if (!Number.isFinite(parsedLimit) || parsedLimit < 1 || parsedLimit > 500) {
+    ui.error('--limit must be between 1 and 500.');
+    process.exitCode = 1;
+    return;
+  }
+  const environment = flags.env || flags.environment || 'production';
+
+  const spinner = ui.spinner('Discovering observed telemetry fields');
+  try {
+    const data = await api.get('/telemetry/fields', {
+      query: {
+        appKeys: appKey,
+        environment,
+        sinceMinutes,
+        source,
+        limit: parsedLimit,
+      },
+    });
+    spinner.stop(`Found ${(data.fields || []).length} observed field${(data.fields || []).length === 1 ? '' : 's'}`);
+    if (flags.json) {
+      ui.json(data);
+      return;
+    }
+
+    console.log('');
+    ui.heading('Observed Telemetry Fields');
+    console.log('');
+    ui.keyValue([
+      ['App', appKey],
+      ['Environment', (data.environments || [environment]).join(', ')],
+      ['Window', `${sinceMinutes} minutes`],
+      ['Source', source],
+    ]);
+    console.log('');
+    ui.table(
+      ['Signal', 'Scope', 'Type', 'Field', 'Occurrences'],
+      (data.fields || []).map((field) => [
+        field.source,
+        field.fieldScope,
+        field.dataType,
+        field.field,
+        String(field.occurrences || 0),
+      ])
+    );
+
+    if ((data.eventTypes || []).length > 0) {
+      console.log('');
+      ui.subheading('Observed custom event types');
+      console.log('');
+      ui.table(
+        ['Event type', 'Occurrences'],
+        data.eventTypes.map((event) => [event.eventType, String(event.occurrences || 0)])
+      );
+    }
+    console.log('');
+    ui.info(data.note || 'Absence in this window does not prove a field can never be emitted.');
+    console.log('');
+  } catch (error) {
+    spinner.fail('Failed to discover telemetry fields');
+    throw error;
+  }
+}
+
+module.exports = {
+  schema,
+  fields,
+  parseDurationToMinutes,
+  filteredSchema,
+};

package/cli.js

@@ -188,16 +188,54 @@ const COMMANDS = {
     },
     defaultSub: 'list',
   },
-  logs: {
+  logs: {
     desc: 'View application logs',
     usage: 'securenow logs [options]',
     sub: {
       list: { desc: 'List recent logs', flags: { app: 'App key', env: 'Environment (production, staging, preview, local, or all)', environment: 'Alias for --env', limit: 'Max results (default 200)', since: 'Time window (e.g. 30m, 6h, 2d)', minutes: 'Time window in minutes (alias for --since Nm)', level: 'Filter by level (error, warn, info, debug)', start: 'Start time (ISO 8601)', end: 'End time (ISO 8601)' }, run: (a, f) => require('./cli/monitor').logsList(a, f) },
       trace: { desc: 'Show logs for a trace', usage: 'securenow logs trace <traceId>', flags: { app: 'App key', env: 'Environment', environment: 'Alias for --env' }, run: (a, f) => require('./cli/monitor').logsTrace(a, f) },
     },
-    defaultSub: 'list',
-  },
-  notifications: {
+    defaultSub: 'list',
+  },
+  telemetry: {
+    desc: 'Inspect the alert-SQL telemetry contract and fields observed for an app',
+    usage: 'securenow telemetry <schema|fields> [options]',
+    flags: {
+      app: 'With fields: application key (defaults to connected/default app)',
+      env: 'With fields: environment or all (default: production)',
+      since: 'With fields: observation window such as 30m, 24h, or 7d (maximum 30d)',
+      source: 'Schema section or live signal source',
+      limit: 'With fields: maximum fields per signal (1-500, default 200)',
+      json: 'Machine-readable output',
+    },
+    sub: {
+      schema: {
+        desc: 'Print the packaged ClickHouse tables, fields, mappings, and SQL requirements',
+        usage: 'securenow telemetry schema [all|logs|traces|events] [--json]',
+        flags: {
+          source: 'Schema section: all, logs, traces, or events',
+          json: 'Output the machine-readable contract as JSON',
+        },
+        run: (a, f) => require('./cli/telemetry').schema(a, f),
+      },
+      fields: {
+        desc: 'Discover fields and custom event types actually emitted by an app',
+        usage: 'securenow telemetry fields [--app <key>] [--env production] [--since 24h] [--source all] [--limit 200] [--json]',
+        flags: {
+          app: 'Application key (defaults to connected/default app)',
+          env: 'Environment, comma-separated environments, or all (default: production)',
+          environment: 'Alias for --env',
+          since: 'Observation window such as 30m, 24h, or 7d (maximum 30d)',
+          source: 'Signal source: all, logs, or traces',
+          limit: 'Maximum fields per signal (1-500, default 200)',
+          json: 'Output JSON for agents and scripts',
+        },
+        run: (a, f) => require('./cli/telemetry').fields(a, f),
+      },
+    },
+    defaultSub: 'schema',
+  },
+  notifications: {
     desc: 'Manage notifications',
     usage: 'securenow notifications <subcommand> [options]',
     sub: {
@@ -765,7 +803,7 @@ function showHelp(commandName) {
     'Investigate': ['ip', 'forensics'],
     'Firewall': ['firewall'],
     'Remediation': ['automation', 'ratelimit', 'challenge', 'blocklist', 'revoke', 'allowlist', 'trusted'],
-    'Telemetry': ['log', 'event', 'test-span'],
+    'Telemetry': ['telemetry', 'log', 'event', 'test-span'],
     'Utilities': ['redact', 'cidr', 'doctor', 'env', 'mcp'],
     'Settings': ['instances', 'config', 'version'],
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "securenow",
-  "version": "8.9.0",
+  "version": "8.10.0",
   "description": "OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt - Send traces and logs to any OTLP-compatible backend",
   "type": "commonjs",
   "main": "register.js",
@@ -50,10 +50,14 @@
       "types": "./tracing.d.ts",
       "default": "./tracing.js"
     },
-    "./events": {
-      "types": "./events.d.ts",
-      "default": "./events.js"
-    },
+    "./events": {
+      "types": "./events.d.ts",
+      "default": "./events.js"
+    },
+    "./telemetry-schema": {
+      "types": "./telemetry-schema.d.ts",
+      "default": "./telemetry-schema.js"
+    },
     "./sessions": {
       "types": "./sessions.d.ts",
       "default": "./sessions.js"
@@ -123,8 +127,11 @@
     "register.d.ts",
     "tracing.js",
     "tracing.d.ts",
-    "events.js",
-    "events.d.ts",
+    "events.js",
+    "events.d.ts",
+    "telemetry-schema.js",
+    "telemetry-schema.d.ts",
+    "telemetry-schema.json",
     "sessions.js",
     "sessions.d.ts",
     "console-instrumentation.js",
@@ -159,34 +166,35 @@
     "web-vite.mjs",
     "app-config.js",
     "README.md",
-    "NPM_README.md",
+    "NPM_README.md",
+    "TELEMETRY-SQL.md",
     "SKILL-CLI.md",
     "SKILL-API.md"
   ],
   "dependencies": {
     "@opentelemetry/api": ">=1.9.0 <1.10.0",
-    "@opentelemetry/api-logs": "0.218.0",
-    "@opentelemetry/auto-instrumentations-node": "0.76.0",
-    "@opentelemetry/core": "2.7.1",
-    "@opentelemetry/exporter-logs-otlp-http": "0.218.0",
-    "@opentelemetry/exporter-trace-otlp-http": "0.218.0",
-    "@opentelemetry/instrumentation": "0.218.0",
-    "@opentelemetry/instrumentation-document-load": "0.63.0",
-    "@opentelemetry/instrumentation-fetch": "0.218.0",
-    "@opentelemetry/instrumentation-http": "0.218.0",
-    "@opentelemetry/instrumentation-mongodb": "0.71.0",
-    "@opentelemetry/instrumentation-user-interaction": "0.62.0",
-    "@opentelemetry/instrumentation-xml-http-request": "0.218.0",
-    "@opentelemetry/resources": "2.7.1",
-    "@opentelemetry/sdk-logs": "0.218.0",
-    "@opentelemetry/sdk-metrics": "2.7.1",
-    "@opentelemetry/sdk-node": "0.218.0",
-    "@opentelemetry/sdk-trace-base": "2.7.1",
-    "@opentelemetry/sdk-trace-web": "2.7.1",
-    "@opentelemetry/semantic-conventions": "1.41.1"
+    "@opentelemetry/api-logs": "0.220.0",
+    "@opentelemetry/auto-instrumentations-node": "0.78.0",
+    "@opentelemetry/core": "2.9.0",
+    "@opentelemetry/exporter-logs-otlp-http": "0.220.0",
+    "@opentelemetry/exporter-trace-otlp-http": "0.220.0",
+    "@opentelemetry/instrumentation": "0.220.0",
+    "@opentelemetry/instrumentation-document-load": "0.65.0",
+    "@opentelemetry/instrumentation-fetch": "0.220.0",
+    "@opentelemetry/instrumentation-http": "0.220.0",
+    "@opentelemetry/instrumentation-mongodb": "0.73.0",
+    "@opentelemetry/instrumentation-user-interaction": "0.64.0",
+    "@opentelemetry/instrumentation-xml-http-request": "0.220.0",
+    "@opentelemetry/resources": "2.9.0",
+    "@opentelemetry/sdk-logs": "0.220.0",
+    "@opentelemetry/sdk-metrics": "2.9.0",
+    "@opentelemetry/sdk-node": "0.220.0",
+    "@opentelemetry/sdk-trace-base": "2.9.0",
+    "@opentelemetry/sdk-trace-web": "2.9.0",
+    "@opentelemetry/semantic-conventions": "1.43.0"
   },
   "optionalDependencies": {
-    "@vercel/otel": "2.1.2"
+    "@vercel/otel": "2.1.3"
   },
   "sideEffects": true,
   "license": "ISC"

package/telemetry-schema.d.ts

@@ -0,0 +1,16 @@
+export interface SecureNowTelemetrySchema {
+  contract: string;
+  schemaVersion: string;
+  dialect: 'ClickHouse';
+  purpose: string;
+  ruleContract: Record<string, unknown>;
+  tables: Record<string, unknown>;
+  clientIp: Record<string, unknown>;
+  customEvents: Record<string, unknown>;
+  automaticTraceFields: Record<string, string[]>;
+  templates: Record<string, string>;
+  authoringWorkflow: string[];
+}
+
+declare const schema: SecureNowTelemetrySchema;
+export = schema;

package/telemetry-schema.js

@@ -0,0 +1,3 @@
+'use strict';
+
+module.exports = require('./telemetry-schema.json');

package/telemetry-schema.json

@@ -0,0 +1,188 @@
+{
+  "contract": "securenow.telemetry.alert-sql",
+  "schemaVersion": "1.0.0",
+  "dialect": "ClickHouse",
+  "purpose": "Canonical local contract for agents and humans authoring SecureNow alert rules.",
+  "ruleContract": {
+    "tenantPlaceholder": "__USER_APP_KEYS__",
+    "requiredResultColumns": [
+      {
+        "name": "ip",
+        "type": "String",
+        "reason": "Per-IP grouping and IP-based remediation use this column. Keep empty IPs out of the final result."
+      }
+    ],
+    "requirements": [
+      "Query only documented telemetry tables and fields.",
+      "Keep __USER_APP_KEYS__ in every customer-scoped query.",
+      "Use the tenant expression documented for the selected table.",
+      "Return an ip column and exclude empty IP values for IP-remediation rules.",
+      "Bound every query with a time window.",
+      "Validate candidate SQL before creating or updating a rule.",
+      "Treat fields absent from live field discovery as unverified until instrumentation emits them."
+    ]
+  },
+  "tables": {
+    "logs": {
+      "name": "signoz_logs.distributed_logs_v2",
+      "purpose": "OpenTelemetry logs and SecureNow custom security events.",
+      "timestamp": {
+        "column": "timestamp",
+        "type": "UInt64",
+        "unit": "nanoseconds",
+        "timeFilterExample": "timestamp >= toUnixTimestamp64Nano(now64() - INTERVAL 15 MINUTE)"
+      },
+      "tenantExpression": "resources_string['service.name'] IN (__USER_APP_KEYS__)",
+      "columns": {
+        "timestamp": "UInt64 nanoseconds",
+        "observed_timestamp": "UInt64 nanoseconds",
+        "id": "String",
+        "trace_id": "String",
+        "span_id": "String",
+        "severity_text": "LowCardinality(String)",
+        "severity_number": "UInt8",
+        "body": "String",
+        "attributes_string": "Map(String, String)",
+        "attributes_number": "Map(String, Float64)",
+        "attributes_bool": "Map(String, Bool)",
+        "resources_string": "Map(String, String)",
+        "scope_name": "String",
+        "scope_version": "String"
+      },
+      "mapAccess": {
+        "string": "attributes_string['field.name']",
+        "number": "attributes_number['field.name']",
+        "boolean": "attributes_bool['field.name']",
+        "resource": "resources_string['field.name']"
+      }
+    },
+    "traces": {
+      "name": "signoz_traces.distributed_signoz_index_v3",
+      "purpose": "OpenTelemetry spans including automatically captured HTTP request telemetry.",
+      "timestamp": {
+        "column": "timestamp",
+        "type": "DateTime64(9)",
+        "unit": "nanoseconds precision",
+        "timeFilterExample": "timestamp >= now64(9) - INTERVAL 15 MINUTE"
+      },
+      "tenantExpression": "`resource_string_service$$name` IN (__USER_APP_KEYS__)",
+      "columns": {
+        "timestamp": "DateTime64(9)",
+        "trace_id": "FixedString(32)",
+        "span_id": "String",
+        "parent_span_id": "String",
+        "name": "LowCardinality(String)",
+        "kind": "Int8 (1 internal, 2 server, 3 client, 4 producer, 5 consumer)",
+        "duration_nano": "UInt64",
+        "status_code": "Int16",
+        "status_message": "String",
+        "attributes_string": "Map(String, String)",
+        "attributes_number": "Map(String, Float64)",
+        "attributes_bool": "Map(String, Bool)",
+        "resources_string": "Map(String, String)",
+        "response_status_code": "LowCardinality(String)",
+        "http_url": "LowCardinality(String)",
+        "http_method": "LowCardinality(String)",
+        "http_host": "LowCardinality(String)",
+        "has_error": "Bool",
+        "resource_string_service$$name": "LowCardinality(String)",
+        "attribute_string_http$$route": "LowCardinality(String)"
+      },
+      "mapAccess": {
+        "string": "attributes_string['field.name']",
+        "number": "attributes_number['field.name']",
+        "boolean": "attributes_bool['field.name']",
+        "resource": "resources_string['field.name']"
+      }
+    }
+  },
+  "clientIp": {
+    "preferredField": "http.client_ip",
+    "traceExpression": "coalesce(nullIf(attributes_string['http.client_ip'], ''), nullIf(attributes_string['net.peer.ip'], ''), nullIf(attributes_string['network.peer.address'], ''), nullIf(attributes_string['client.address'], ''), nullIf(attributes_string['net.sock.peer.addr'], ''))",
+    "eventExpression": "attributes_string['http.client_ip']",
+    "trustNote": "Confirm trusted-proxy configuration before using forwarded IPs for blocking."
+  },
+  "customEvents": {
+    "sdkImport": "securenow/events",
+    "signature": "track(type: string, props?: TrackProps): void",
+    "storageTable": "logs",
+    "propertyMapping": {
+      "type": "attributes_string['event.type']",
+      "userId": "attributes_string['enduser.id']",
+      "sessionId": "attributes_string['session.id']",
+      "ip": "attributes_string['http.client_ip']",
+      "userAgent": "attributes_string['http.user_agent']",
+      "severity": "severity_text",
+      "attributes.string": "attributes_string['<custom-key>']",
+      "attributes.number": "attributes_number['<custom-key>']",
+      "attributes.boolean": "attributes_bool['<custom-key>']"
+    },
+    "recommendedAuthenticationEvents": [
+      "auth.login.failure",
+      "auth.login.success",
+      "auth.otp.send.requested",
+      "auth.otp.send.result",
+      "auth.otp.verify.failure",
+      "auth.otp.verify.success",
+      "auth.password_reset.requested",
+      "auth.password_reset.completed",
+      "auth.mfa.challenge.failure",
+      "auth.mfa.challenge.success",
+      "auth.session.revoked"
+    ]
+  },
+  "automaticTraceFields": {
+    "http": [
+      "http.method",
+      "http.route",
+      "http.target",
+      "http.url",
+      "http.status_code",
+      "http.host",
+      "http.scheme",
+      "http.user_agent"
+    ],
+    "clientAndProxy": [
+      "http.client_ip",
+      "http.client_ip.source",
+      "http.socket_ip",
+      "http.forwarded_for",
+      "http.real_ip",
+      "http.cf.connecting_ip",
+      "http.proxy.trusted"
+    ],
+    "securityPresenceOnly": [
+      "http.security.auth_present",
+      "http.security.cookies_present",
+      "http.security.csrf_token_present"
+    ],
+    "optionalBodyCapture": [
+      "http.request.body",
+      "http.request.body.type",
+      "http.request.body.size",
+      "http.request.body.parse_error"
+    ],
+    "resources": [
+      "service.name",
+      "service.instance.id",
+      "service.version",
+      "deployment.environment",
+      "telemetry.sdk.name",
+      "telemetry.sdk.language",
+      "telemetry.sdk.version"
+    ]
+  },
+  "templates": {
+    "traceBurstByIp": "WITH coalesce(nullIf(attributes_string['http.client_ip'], ''), nullIf(attributes_string['net.peer.ip'], ''), nullIf(attributes_string['network.peer.address'], ''), nullIf(attributes_string['client.address'], ''), nullIf(attributes_string['net.sock.peer.addr'], '')) AS client_ip\nSELECT client_ip AS ip, count() AS hits\nFROM signoz_traces.distributed_signoz_index_v3\nWHERE `resource_string_service$$name` IN (__USER_APP_KEYS__)\n  AND timestamp >= now64(9) - INTERVAL 15 MINUTE\n  AND attributes_string['http.target'] = '/replace-with-real-route'\nGROUP BY ip\nHAVING ip != '' AND hits >= 20",
+    "eventFailuresByIp": "SELECT attributes_string['http.client_ip'] AS ip, count() AS failures\nFROM signoz_logs.distributed_logs_v2\nWHERE resources_string['service.name'] IN (__USER_APP_KEYS__)\n  AND timestamp >= toUnixTimestamp64Nano(now64() - INTERVAL 15 MINUTE)\n  AND attributes_string['event.type'] = 'replace.with.verified.event'\nGROUP BY ip\nHAVING ip != '' AND failures >= 10"
+  },
+  "authoringWorkflow": [
+    "npx securenow telemetry schema --json",
+    "npx securenow telemetry fields --app <key> --env production --since 24h --json",
+    "npx securenow alerts rules --json",
+    "npx securenow alerts rules validate --sql @rule.sql --app <key>",
+    "npx securenow alerts rules create --name <name> --sql @rule.sql --apps <key>",
+    "npx securenow alerts rules test <rule-id> --mode dry_run --wait",
+    "npx securenow alerts rules promote <rule-id>"
+  ]
+}