nucleus-core-ts 0.9.779 → 0.9.780

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "nucleus-core-ts",
-	"version": "0.9.779",
+	"version": "0.9.780",
 	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
 	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
 	"license": "SEE LICENSE IN LICENSE",
@@ -19,6 +19,8 @@
 		"infra/templates",
 		"infra/scripts/generate-project.ts",
 		"src/system.tables.json",
+		"src/Services/SchemaTables/resolveEntities.ts",
+		"src/Services/Logger/auditTaxonomy.ts",
 		"public",
 		"LICENSE"
 	],

package/scripts/packagedScripts.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, test } from 'bun:test'
+import { existsSync, readdirSync, readFileSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+
+/**
+ * Guard: everything `scripts/` imports must actually be IN the npm tarball.
+ *
+ * The scripts in this package are shipped as raw TypeScript and executed inside a
+ * consumer's node_modules (`bunx nucleus-generate` runs scripts/generate-schema.ts
+ * during their Docker build). `package.json#files` ships `scripts` and `dist` but
+ * NOT `src` — so a relative import that reaches into src/ resolves fine in this
+ * repo and fails in every consumer with
+ *
+ *     Cannot find module '../src/…' from '/app/node_modules/nucleus-core-ts/scripts/…'
+ *
+ * That shipped in 0.9.779 and broke the Docker build of every app that generates
+ * its schema at build time. Local tests could not see it: the failure only exists
+ * in the packaged layout.
+ */
+const ROOT = join(import.meta.dir, '..')
+const FILES: string[] = JSON.parse(readFileSync(join(ROOT, 'package.json'), 'utf-8')).files
+
+/**
+ * Scripts only ever run from THIS repo by a maintainer (release tooling). They may
+ * read repo-only files like nucleus.config.ts, which is deliberately not shipped.
+ */
+const MAINTAINER_ONLY = new Set(['build.ts', 'publish.ts', 'version.ts'])
+
+/** True when `relPath` (repo-relative) is covered by a package.json#files entry. */
+function isShipped(relPath: string): boolean {
+  return FILES.some((entry) => relPath === entry || relPath.startsWith(`${entry}/`))
+}
+
+function scriptFiles(): string[] {
+  return readdirSync(join(ROOT, 'scripts'))
+    .filter((f) => f.endsWith('.ts') && !f.endsWith('.test.ts') && !MAINTAINER_ONLY.has(f))
+    .map((f) => join(ROOT, 'scripts', f))
+}
+
+function relativeImports(file: string): string[] {
+  const src = readFileSync(file, 'utf-8')
+  const out: string[] = []
+  for (const m of src.matchAll(/(?:from|import)\s+['"](\.[^'"]+)['"]/g)) {
+    const spec = m[1]
+    if (spec) out.push(spec)
+  }
+  return out
+}
+
+/** Resolve an extensionless TS import the way Bun does. */
+function resolveImport(fromFile: string, spec: string): string | null {
+  const base = resolve(dirname(fromFile), spec)
+  for (const candidate of [base, `${base}.ts`, `${base}.json`, join(base, 'index.ts')]) {
+    if (existsSync(candidate)) return candidate
+  }
+  return null
+}
+
+describe('shipped scripts only import shipped files', () => {
+  test('package.json#files does not include the whole src directory', () => {
+    // If this ever changes the guard below becomes vacuous — fail loudly instead.
+    expect(FILES).not.toContain('src')
+  })
+
+  test('every relative import of every shipped script is in the tarball', () => {
+    const missing: string[] = []
+
+    for (const file of scriptFiles()) {
+      for (const spec of relativeImports(file)) {
+        const target = resolveImport(file, spec)
+        // Unresolvable specifiers come from the code these scripts EMIT (the schema
+        // generator writes `import … from './schema'` into its output), not from the
+        // script's own imports. Only real imports matter here.
+        if (!target) continue
+        const rel = relative(ROOT, target)
+        if (!isShipped(rel)) {
+          missing.push(`${relative(ROOT, file)} -> ${rel} (not in package.json#files)`)
+        }
+      }
+    }
+
+    expect(missing).toEqual([])
+  })
+})

package/src/Services/Logger/auditTaxonomy.ts

@@ -0,0 +1,154 @@
+/**
+ * Audit taxonomy — the single source of truth for classifying audit_logs rows by
+ * security severity and category, and for deciding which routine outcomes are
+ * noise that should NOT be persisted by default.
+ *
+ * Why this exists: the auth middleware writes an audit row on every rejected
+ * request. A logged-out browser tab polling an authenticated endpoint (e.g.
+ * `/auth/me`) therefore produces one "No session token" row per poll — an HTTP
+ * outcome with no security signal — which numerically swamps the real events
+ * (logins, CRUD, admin actions). Classifying every row by severity/category and
+ * suppressing the routine credential-absence reasons by default keeps the
+ * Security Logs view high-signal while preserving every genuine security event.
+ */
+
+export type AuditSeverity = 'info' | 'low' | 'medium' | 'high' | 'critical'
+
+export type AuditCategory =
+  | 'auth' // authentication outcomes (login/logout/register, token/session checks)
+  | 'authz' // authorization outcomes (claims/cohort/role denials)
+  | 'data_change' // entity CREATE/UPDATE/PATCH/DELETE
+  | 'admin' // privileged operations (impersonate, hard-delete, change-user-id, provision)
+  | 'config' // server/configuration problems surfaced on a request
+  | 'security_anomaly' // suspicious: forged/tampered token, tenant mismatch, revoked-token reuse
+  | 'system' // internal/system-originated
+
+/** Numeric ordering so a configured `minSeverity` can drop everything below it. */
+export const AUDIT_SEVERITY_RANK: Record<AuditSeverity, number> = {
+  info: 0,
+  low: 1,
+  medium: 2,
+  high: 3,
+  critical: 4,
+}
+
+export function severityRank(severity: AuditSeverity | undefined): number {
+  return AUDIT_SEVERITY_RANK[severity ?? 'info'] ?? 0
+}
+
+/**
+ * Routine, NON-security auth outcomes — the steady state of any unauthenticated
+ * or stale client. These carry no actor identity and no attack signal, so they
+ * are suppressed from audit_logs by default (still emitted at debug level). The
+ * strings MUST match the `summary` passed at the middleware reject sites in
+ * `src/ElysiaPlugin/index.ts`.
+ */
+export const ROUTINE_AUTH_REASONS = [
+  'No session token',
+  'Invalid session',
+  'Session expired',
+  'Session inactive timeout',
+  'Authentication secrets not defined',
+] as const
+
+/** Default value for `audit.suppressReasons` — set to `[]` to capture everything (legacy). */
+export const DEFAULT_AUDIT_SUPPRESS_REASONS: string[] = [...ROUTINE_AUTH_REASONS]
+
+/**
+ * Explicit severity/category for each known auth-middleware reject reason. The
+ * middleware passes these via `toAudit(...)` so they don't depend on string
+ * re-classification. Reasons absent here fall back to {@link classifyAudit}.
+ */
+export const AUTH_FAILURE_CLASSIFICATION: Record<
+  string,
+  { severity: AuditSeverity; category: AuditCategory }
+> = {
+  'No session token': { severity: 'low', category: 'auth' },
+  'Invalid session': { severity: 'low', category: 'auth' },
+  'Session expired': { severity: 'low', category: 'auth' },
+  'Session inactive timeout': { severity: 'low', category: 'auth' },
+  'Authentication secrets not defined': { severity: 'critical', category: 'config' },
+  'Session revoked': { severity: 'high', category: 'security_anomaly' },
+  'Invalid or missing access token': { severity: 'medium', category: 'auth' },
+  'Access token tenant binding failed': { severity: 'high', category: 'security_anomaly' },
+  'Invalid API key': { severity: 'medium', category: 'auth' },
+  'Cohort expired': { severity: 'medium', category: 'authz' },
+}
+
+/**
+ * Derive a sensible default severity/category from an audit `operation` (and
+ * optional `summary`) when the call site did not provide them explicitly. This
+ * lets the ~20 route audit sites get correct classification for free, while the
+ * middleware still passes explicit tags via {@link AUTH_FAILURE_CLASSIFICATION}.
+ */
+export function classifyAudit(
+  operation: string,
+  summary?: string
+): { severity: AuditSeverity; category: AuditCategory } {
+  const op = (operation || '').toUpperCase()
+
+  // Dynamic API-key rejection ("API key rejected: <reason>").
+  if (summary?.startsWith('API key rejected')) {
+    return { severity: 'medium', category: 'auth' }
+  }
+
+  // Known auth-failure reasons (also covers middleware sites that pass operation
+  // = HTTP method but a recognizable summary).
+  if (summary && AUTH_FAILURE_CLASSIFICATION[summary]) {
+    return AUTH_FAILURE_CLASSIFICATION[summary]
+  }
+
+  // Privileged/admin operations. IMPERSONATE is matched by prefix because the
+  // routes write IMPERSONATE_START / IMPERSONATE_STOP (never a bare 'IMPERSONATE') —
+  // an exact match here silently dropped impersonation to info/data_change.
+  if (
+    op.startsWith('IMPERSONATE') ||
+    op === 'HARD_DELETE' ||
+    op === 'CHANGE_USER_ID' ||
+    op === 'PROVISION' ||
+    op === 'RESTORE' ||
+    op.startsWith('ADMIN_')
+  ) {
+    return { severity: 'high', category: 'admin' }
+  }
+
+  // Authentication lifecycle.
+  if (op.endsWith('_FAILED')) {
+    return { severity: 'medium', category: 'auth' }
+  }
+  if (op.startsWith('PASSWORD')) {
+    return { severity: 'medium', category: 'auth' }
+  }
+  if (
+    op === 'LOGIN' ||
+    op === 'LOGOUT' ||
+    op === 'REGISTER' ||
+    op === 'OAUTH_LOGIN' ||
+    op === 'MAGIC_LINK' ||
+    op === 'INVITE'
+  ) {
+    return { severity: 'info', category: 'auth' }
+  }
+
+  // Entity data changes.
+  if (
+    op === 'CREATE' ||
+    op === 'UPDATE' ||
+    op === 'PATCH' ||
+    op === 'DELETE' ||
+    op === 'TOGGLE' ||
+    op === 'VERIFICATION'
+  ) {
+    return { severity: 'info', category: 'data_change' }
+  }
+
+  // Raw HTTP method with no recognized summary => an untagged middleware reject.
+  if (op === 'GET' || op === 'POST' || op === 'PUT' || op === 'PATCH' || op === 'HEAD') {
+    return { severity: 'low', category: 'auth' }
+  }
+
+  return { severity: 'info', category: 'data_change' }
+}
+
+/** Label to show for an audit row that has no resolved actor. */
+export const ANONYMOUS_ACTOR_LABEL = 'Anonymous'

package/src/Services/SchemaTables/resolveEntities.ts

@@ -0,0 +1,197 @@
+/**
+ * Single source of truth for "what tables does this app actually have".
+ *
+ * Three consumers used to answer this question independently — schema generation
+ * (scripts/generate-schema.ts), entity route registration
+ * (ElysiaPlugin/routes/entity/index.ts) and claim seeding (ElysiaPlugin/index.ts,
+ * three call sites) — and they disagreed: the boot/main-schema seeding site let the
+ * BUILT-IN columns win while the tenant sites let the CONFIG columns win, so the
+ * same config produced different claims in the main schema and in a tenant schema.
+ * This function replaces all of that with one rule.
+ *
+ * PURE: no I/O, no logger, no process access. Errors and warnings are RETURNED, so
+ * the caller decides whether to fail boot (runtime) or print and exit (script).
+ */
+
+/**
+ * Minimal structural shape this module reads. Arrays are `readonly` so that both
+ * the deeply-`as const` SYSTEM_TABLES tuple and a mutable NucleusTable[] satisfy it.
+ */
+export interface ExtendableColumnLike {
+  name: string
+  notNull?: boolean
+  nullable?: boolean
+  default?: unknown
+  defaultRaw?: string
+  generatedAlwaysAs?: string
+  generatedAlwaysAsIdentity?: boolean
+  generatedByDefaultAsIdentity?: boolean
+  sensitive?: boolean
+}
+
+export interface ExtendableTableLike {
+  table_name: string
+  extends?: boolean
+  add_base_columns?: boolean
+  feature_set?: readonly string[]
+  columns?: readonly ExtendableColumnLike[]
+  indexes?: readonly unknown[]
+}
+
+export type ExtendErrorCode =
+  | 'E1_COLUMN_COLLISION'
+  | 'E2_NOT_NULL_WITHOUT_DEFAULT'
+  | 'E3_CONSUMER_AUTH_TABLE'
+  | 'E4_UNKNOWN_SYSTEM_TABLE'
+  | 'E5_FEATURE_DISABLED'
+
+export interface ExtendError {
+  code: ExtendErrorCode
+  table: string
+  column?: string
+  message: string
+}
+
+export interface ResolveEntitiesOptions {
+  /** Base column names added when add_base_columns is not false. Enables the base half of E1. */
+  baseColumnNames?: readonly string[]
+  /** True when authentication.mode === 'consumer'. Enables E3. */
+  consumerMode?: boolean
+  /** System table names that survived feature gating. When given, enables E5. */
+  enabledTableNames?: ReadonlySet<string>
+}
+
+export interface ResolveEntitiesResult<T> {
+  entities: T[]
+  errors: ExtendError[]
+  warnings: string[]
+}
+
+/** Fields an extending entry may declare. Anything else is inherited and warned about. */
+const EXTEND_ALLOWED_KEYS = new Set(['table_name', 'extends', 'columns', 'indexes'])
+
+/** A column can satisfy notNull without a client-supplied value only via a DB-side default. */
+function hasDbDefault(column: ExtendableColumnLike): boolean {
+  return (
+    column.default !== undefined ||
+    column.defaultRaw !== undefined ||
+    column.generatedAlwaysAs !== undefined ||
+    column.generatedAlwaysAsIdentity === true ||
+    column.generatedByDefaultAsIdentity === true
+  )
+}
+
+const AUTH_FEATURES = new Set(['authentication', 'authorization'])
+
+export function resolveEntities<T extends ExtendableTableLike>(
+  systemTables: readonly T[],
+  configEntities: readonly T[],
+  options: ResolveEntitiesOptions = {}
+): ResolveEntitiesResult<T> {
+  const errors: ExtendError[] = []
+  const warnings: string[] = []
+  const consumed = new Set<string>()
+  const entities: T[] = []
+
+  for (const system of systemTables) {
+    const config = configEntities.find((c) => c.table_name === system.table_name)
+    if (!config) {
+      entities.push(system)
+      continue
+    }
+    consumed.add(config.table_name)
+
+    if (!config.extends) {
+      warnings.push(
+        `[Schema] "${config.table_name}" is declared in config.entities AND ships as a system table. ` +
+          'Using YOUR definition and skipping the built-in one. Add "extends": true to inherit the ' +
+          'built-in columns and route policy instead.'
+      )
+      entities.push(config)
+      continue
+    }
+
+    for (const key of Object.keys(config)) {
+      if (!EXTEND_ALLOWED_KEYS.has(key)) {
+        warnings.push(
+          `[Schema] "${config.table_name}" sets "${key}" alongside "extends": true — ignored. ` +
+            'An extending entry inherits every table-level setting from the built-in definition.'
+        )
+      }
+    }
+
+    if (options.enabledTableNames && !options.enabledTableNames.has(system.table_name)) {
+      errors.push({
+        code: 'E5_FEATURE_DISABLED',
+        table: system.table_name,
+        message:
+          `"${system.table_name}" is extended but its feature is disabled, so the table is never ` +
+          'created. Enable the feature or remove the extending entry.',
+      })
+    }
+
+    if (options.consumerMode && (system.feature_set ?? []).some((f) => AUTH_FEATURES.has(f))) {
+      errors.push({
+        code: 'E3_CONSUMER_AUTH_TABLE',
+        table: system.table_name,
+        message:
+          `"${system.table_name}" is an auth system table and cannot be extended in consumer mode — ` +
+          'the identity tables live in the IDP. Extending it would create a local copy here.',
+      })
+    }
+
+    const builtInNames = new Set((system.columns ?? []).map((c) => c.name))
+    if (system.add_base_columns !== false) {
+      for (const name of options.baseColumnNames ?? []) builtInNames.add(name)
+    }
+
+    for (const column of config.columns ?? []) {
+      if (builtInNames.has(column.name)) {
+        errors.push({
+          code: 'E1_COLUMN_COLLISION',
+          table: system.table_name,
+          column: column.name,
+          message:
+            `"${system.table_name}.${column.name}" already exists in the built-in definition. ` +
+            'An extending entry may only ADD columns; rename yours.',
+        })
+      }
+      if (column.notNull === true && column.nullable !== true && !hasDbDefault(column)) {
+        errors.push({
+          code: 'E2_NOT_NULL_WITHOUT_DEFAULT',
+          table: system.table_name,
+          column: column.name,
+          message:
+            `"${system.table_name}.${column.name}" is notNull without a default. The framework writes ` +
+            'this table from fixed-column inserts (register, invite, admin create-user, godmin seed, ' +
+            'tenant provisioning) that cannot supply it — every one of them would fail. Make it ' +
+            'nullable or give it a default.',
+        })
+      }
+    }
+
+    const merged = {
+      ...system,
+      columns: [...(system.columns ?? []), ...(config.columns ?? [])],
+      indexes: [...(system.indexes ?? []), ...(config.indexes ?? [])],
+    } as unknown as T
+    entities.push(merged)
+  }
+
+  for (const config of configEntities) {
+    if (consumed.has(config.table_name)) continue
+    if (config.extends) {
+      errors.push({
+        code: 'E4_UNKNOWN_SYSTEM_TABLE',
+        table: config.table_name,
+        message:
+          `"${config.table_name}" sets "extends": true but there is no system table with that name. ` +
+          'Remove the flag to declare it as an ordinary entity.',
+      })
+      continue
+    }
+    entities.push(config)
+  }
+
+  return { entities, errors, warnings }
+}