nucleus-core-ts 0.9.705 → 0.9.706

package/dist/src/Services/Authorization/EndpointDiscovery/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Endpoint discovery: turn an external (non-nucleus) service's OpenAPI document
+ * into nucleus claim specs, and match a concrete request path back to its claim.
+ *
+ * A discovered claim's `action` is prefixed with the service id
+ * (`{serviceId}.{resource}.{op}`) so it never collides with an auto-seeded entity
+ * claim (which is method-first: `get.users`) and so all of a service's claims can
+ * be found by the `{serviceId}.` prefix during reconcile. `serviceId` therefore MUST
+ * NOT be an HTTP-method word (get/post/put/patch/delete/toggle/bulk).
+ */
+export interface ClaimSpec {
+    action: string;
+    path: string;
+    method: string;
+    description: string;
+}
+/** Minimal slice of an OpenAPI 3.x document we depend on. */
+export interface OpenApiDoc {
+    paths?: Record<string, Record<string, {
+        tags?: string[];
+        operationId?: string;
+        summary?: string;
+        description?: string;
+    } | undefined>>;
+}
+/** Simple glob: exact match, or a trailing `/*` prefix match. */
+export declare function matchesExclude(path: string, patterns: string[] | undefined): boolean;
+export interface ParseOptions {
+    /** Path globs to skip (e.g. ['/health', '/api/v1/internal/*']). */
+    exclude?: string[];
+}
+/**
+ * Convert an OpenAPI document into claim specs. Deterministic and pure.
+ * `action = {serviceId}.{tag|resource}.{operationId | method_normalizedPath}` —
+ * the fallback op token embeds the path, so actions are unique even without
+ * operationIds (method+path is unique within an OpenAPI doc).
+ */
+export declare function parseOpenApiToClaims(serviceId: string, doc: OpenApiDoc, opts?: ParseOptions): ClaimSpec[];
+/** True when a concrete request path matches a templated OpenAPI path. */
+export declare function pathMatchesTemplate(template: string, concrete: string): boolean;
+/**
+ * Given the claim specs for a service and an incoming (method, concrete-path),
+ * return the required claim action, or null when no route matches (the caller
+ * decides allow/deny for unmapped routes).
+ */
+export declare function matchRouteToAction(specs: ClaimSpec[], method: string, concretePath: string): string | null;
+/** An existing claim row as seen during reconcile. */
+export interface ExistingClaim {
+    action: string;
+    isActive: boolean;
+    path: string;
+    method: string;
+    description: string;
+}
+export interface ClaimReconcilePlan {
+    toInsert: ClaimSpec[];
+    toReactivate: ClaimSpec[];
+    toDeactivate: ExistingClaim[];
+    unchanged: ClaimSpec[];
+}
+/**
+ * Pure reconcile: compare a service's currently-discovered specs against its existing
+ * claim rows (already filtered to this service's `{serviceId}.` prefix). Removed
+ * endpoints are DEACTIVATED, not deleted, so their role assignments survive.
+ */
+export declare function diffClaims(existing: ExistingClaim[], specs: ClaimSpec[]): ClaimReconcilePlan;
+/** Fetch and JSON-parse a service's OpenAPI document. `fetchImpl` is injectable for tests. */
+export declare function fetchOpenApi(baseUrl: string, openapiPath: string, fetchImpl?: typeof fetch): Promise<OpenApiDoc>;

package/dist/src/Services/Authorization/EndpointDiscovery/seed.d.ts

@@ -0,0 +1,53 @@
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import type { Logger } from '../../Logger';
+import { type ClaimSpec } from './index';
+export interface DiscoveryServiceConfig {
+    id: string;
+    baseUrl: string;
+    openapi?: string;
+    exclude?: string[];
+}
+export interface EndpointDiscoveryConfig {
+    enabled?: boolean;
+    runOnBoot?: boolean;
+    services?: DiscoveryServiceConfig[];
+    trigger?: {
+        enabled?: boolean;
+        basePath?: string;
+    };
+}
+export interface ServiceDiscoveryResult {
+    id: string;
+    added: number;
+    reactivated: number;
+    deactivated: number;
+    unchanged: number;
+    total: number;
+    error?: string;
+}
+export interface DiscoveryRunResult {
+    services: ServiceDiscoveryResult[];
+}
+type PgTable = ReturnType<typeof import('drizzle-orm/pg-core').pgTable>;
+/**
+ * Seed + reconcile one service's discovered claims into the `claims` table.
+ * Idempotent: inserts missing, reactivates previously-removed, and DEACTIVATES
+ * (never deletes) claims for this service that are no longer present.
+ */
+export declare function seedDiscoveredClaims(db: NodePgDatabase, claimsTable: PgTable, serviceId: string, specs: ClaimSpec[], logger: Logger): Promise<Omit<ServiceDiscoveryResult, 'id' | 'error'>>;
+/**
+ * Boot / on-demand entrypoint: for each configured service, fetch its OpenAPI,
+ * derive claim specs, and seed+reconcile them. A per-service fetch/parse failure is
+ * logged and skipped (never fails the whole run or boot).
+ */
+export declare function runEndpointDiscovery(db: NodePgDatabase, schemaTables: Record<string, unknown>, config: EndpointDiscoveryConfig, logger: Logger, fetchImpl?: typeof fetch): Promise<DiscoveryRunResult>;
+/**
+ * Build the route→claim manifest a reverse proxy consumes: the active discovered
+ * claims for a service (by `{serviceId}.` prefix), as templated route rows.
+ */
+export declare function getRouteManifest(db: NodePgDatabase, claimsTable: PgTable, serviceId: string): Promise<Array<{
+    action: string;
+    path: string;
+    method: string;
+}>>;
+export {};

package/dist/src/Services/Authorization/types.d.ts

@@ -3,6 +3,12 @@ export interface AuthorizationConfig {
     autoSeedClaims: boolean;
     skipTables: string[];
     skipColumns: string[];
+    /**
+     * @deprecated NOT ENFORCED. This key was never wired into the request pipeline —
+     * paths listed here are still authenticated and authorized normally. To make a
+     * path public (skip auth), use `publicPaths` (which has method-qualification and
+     * anomalous-path hardening). Kept only for config back-compat; will be removed.
+     */
     excludedPaths: string[];
     publicPaths: string[];
     godminEmail?: string;

package/dist/src/Services/OAuth/providers/microsoft.d.ts

@@ -1,3 +1,20 @@
 import type { OAuthCallbackResult, OAuthProviderConfig } from '../types';
+/**
+ * Decide whether the Microsoft email may be TRUSTED for account-merge.
+ *
+ * SECURITY: the Graph `mail` / `userPrincipalName` is directory-controlled, but on
+ * multi-tenant ("common"/"organizations"/"consumers") or personal-account apps the
+ * signing tenant is NOT owned by us — a hostile tenant admin (or an MSA user) can
+ * set `mail` to victim@ourcompany.com. Blindly trusting it let an attacker merge
+ * into a victim's existing local account (merge-by-email takeover). Trust the email
+ * only when:
+ *   1. Microsoft asserts it via the `xms_edov` (email domain-owner verified) claim, OR
+ *   2. the app is pinned to a single specific tenant (config.tenantId is a concrete
+ *      directory, not a multi-tenant meta-authority) — then the issuing directory is
+ *      one we trust.
+ * Otherwise it is treated as UNVERIFIED, so the callback refuses to merge it into a
+ * pre-existing local account (a fresh OAuth-origin sign-up is still allowed).
+ */
+export declare function resolveMicrosoftEmailVerified(config: OAuthProviderConfig, idTokenPayload: Record<string, unknown> | null): boolean;
 export declare function buildMicrosoftAuthUrl(config: OAuthProviderConfig, state: string): string;
 export declare function exchangeMicrosoftCode(code: string, config: OAuthProviderConfig): Promise<OAuthCallbackResult>;

package/dist/src/Services/OAuth/providers/microsoft.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/Services/Tenant/TenantRegistry.d.ts

@@ -34,7 +34,7 @@ export declare class TenantRegistry {
      * Resolve a tenant from an incoming HTTP request.
      * Priority: subdomain → x-tenant header → fallback to main
      */
-    resolveFromRequest(request: Request): TenantResolutionResult;
+    resolveFromRequest(request: Request, vettedClientIp?: string): TenantResolutionResult;
     /**
      * Get schema context for a specific schema name.
      */

package/dist/src/Services/Tenant/helpers.d.ts

@@ -39,4 +39,12 @@ export declare const isIpInCidr: (ip: string, cidr: string) => boolean;
 /**
  * Check if a request comes from a trusted source for the given tenant.
  */
-export declare const isTrustedSource: (tenant: TenantRecord, request: Request, authMode: "full" | "consumer" | undefined, fallbackSources?: TenantRecord["trustedSources"]) => boolean;
+export declare const isTrustedSource: (tenant: TenantRecord, request: Request, authMode: "full" | "consumer" | undefined, fallbackSources?: TenantRecord["trustedSources"], 
+/**
+ * The VETTED client IP, resolved by the middleware via resolveClientIp (which
+ * only honors X-Forwarded-For from configured trusted proxies). MUST be passed
+ * for the allowedIps check to be safe — never re-derive it from raw request
+ * headers here, or a client could spoof X-Forwarded-For to match an allowedIp
+ * and select another tenant.
+ */
+vettedClientIp?: string) => boolean;

package/dist/src/Services/Tenant/isTrustedSource.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/types.d.ts

@@ -675,6 +675,10 @@ export interface NucleusConfigOptions {
         claimsCachePrefix?: string;
         skipTables?: string[];
         skipColumns?: string[];
+        /**
+         * @deprecated NOT ENFORCED — paths here are still authenticated + authorized.
+         * Use `publicPaths` to make a path public. Kept for config back-compat only.
+         */
         excludedPaths?: string[];
         publicPaths?: string[];
         godminEmail?: string;
@@ -708,6 +712,43 @@ export interface NucleusConfigOptions {
                 scope?: string;
             }>;
         };
+        /**
+         * Auto-discover the endpoints of EXTERNAL (non-nucleus) services from their
+         * OpenAPI documents and seed a claim per endpoint, so a nucleus IDP can protect
+         * 500+ routes across other services (e.g. FastAPI) with the same role/claim model
+         * without hand-writing claims. Full (IDP) mode only. Discovered claim actions are
+         * `{serviceId}.{tag}.{operationId}` (idempotent on action; removed endpoints are
+         * DEACTIVATED, not deleted). Enforcement happens at the reverse proxy via
+         * `HttpProxyTarget.authorize` (see nucleus-core-ts/proxy) consuming the
+         * `/authorization/route-manifest` this produces. `serviceId` must not be an
+         * HTTP-method word (get/post/put/…).
+         */
+        endpointDiscovery?: {
+            enabled?: boolean;
+            /** Run discovery at boot (default true when enabled). */
+            runOnBoot?: boolean;
+            services?: Array<{
+                /** Stable prefix for this service's claim actions (e.g. "agent"). */
+                id: string;
+                /** Base URL reachable from the IDP (e.g. "http://vorion-agent:8000"). */
+                baseUrl: string;
+                /** OpenAPI document path (default "/openapi.json"). */
+                openapi?: string;
+                /** Path globs to skip, e.g. ["/health","/api/v1/internal/*"]. */
+                exclude?: string[];
+            }>;
+            /** godmin-only on-demand re-discovery endpoint. */
+            trigger?: {
+                enabled?: boolean;
+                basePath?: string;
+            };
+            /**
+             * Shared secret that lets the reverse proxy fetch `/authorization/route-manifest`
+             * without a user session (presented as the `x-discovery-token` header). Godmin
+             * callers are always allowed. Falls back to the `NUCLEUS_DISCOVERY_TOKEN` env.
+             */
+            token?: string;
+        };
     };
     audit?: {
         enabled?: boolean;
@@ -980,6 +1021,14 @@ export interface NucleusConfigOptions {
         wsPath?: string;
         /** Dapr pubsub component name (default: "pubsub-redis") */
         pubsubName?: string;
+        /**
+         * Shared secret Dapr presents as the `dapr-api-token` header when POSTing a
+         * delivered message to the subscription endpoint. REQUIRED to secure that
+         * endpoint — without it (and without the APP_API_TOKEN/DAPR_API_TOKEN env
+         * fallback) any caller reaching the route can inject realtime events to any
+         * user. Falls back to env APP_API_TOKEN, then DAPR_API_TOKEN.
+         */
+        daprApiToken?: string;
         /** Max clients per user (default: 10) */
         maxClientsPerUser?: number;
         /** WebSocket idle timeout in seconds (default: 120) */

package/package.json

@@ -1,115 +1,115 @@
 {
-  "name": "nucleus-core-ts",
-  "version": "0.9.705",
-  "description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
-  "author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
-  "license": "SEE LICENSE IN LICENSE",
-  "keywords": [
-    "backend",
-    "framework",
-    "elysia",
-    "drizzle",
-    "typescript"
-  ],
-  "files": [
-    "bin",
-    "dist",
-    "schemas",
-    "scripts",
-    "infra/templates",
-    "infra/scripts/generate-project.ts",
-    "src/system.tables.json",
-    "public",
-    "LICENSE"
-  ],
-  "module": "dist/index.js",
-  "type": "module",
-  "types": "dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js"
-    },
-    "./fe": {
-      "types": "./dist/fe/index.d.ts",
-      "import": "./dist/fe/index.js"
-    },
-    "./fe/auth": {
-      "types": "./dist/fe/components/AuthGuard/index.d.ts",
-      "import": "./dist/fe/components/AuthGuard/index.js"
-    },
-    "./proxy": {
-      "types": "./dist/src/Client/Proxy/index.d.ts",
-      "import": "./dist/src/Client/Proxy/index.js"
-    }
-  },
-  "scripts": {
-    "test": "bun test src",
-    "build": "bun run scripts/build.ts",
-    "build:quick": "bun run build:js && bun run build:types",
-    "build:js": "bun build ./index.ts ./client.ts ./fe/index.ts ./src/Client/Proxy/index.ts --outdir=dist --target=bun --format=esm --splitting --minify --external react --external react-dom --external gsap --external @gsap/react --external h-state --external three --external @react-three/fiber --external elysia --external drizzle-orm --external drizzle-kit --external ioredis --external googleapis --external @dapr/dapr --external pg --external @xyflow/react --external @xyflow/system --external @azure/communication-email --external @azure/identity --external stripe",
-    "build:types": "tsc --declaration --emitDeclarationOnly --outDir dist --skipLibCheck",
-    "version:patch": "bun run scripts/version.ts patch",
-    "version:minor": "bun run scripts/version.ts minor",
-    "version:major": "bun run scripts/version.ts major",
-    "publish:npm": "bun run scripts/publish.ts",
-    "publish:dry": "bun run scripts/publish.ts --dry-run",
-    "release": "bun run version:patch && bun run publish:npm",
-    "release:minor": "bun run version:minor && bun run publish:npm",
-    "release:major": "bun run version:major && bun run publish:npm",
-    "generate:schemas": "bun run scripts/generate-types-schema.ts",
-    "lint": "biome check . --write",
-    "lint:fix": "biome check --config-path ./biome.json --write",
-    "prepublishOnly": "echo 'Use: bun run publish:npm'"
-  },
-  "bin": {
-    "nucleus-core-ts": "./bin/cli.ts",
-    "nucleus": "./bin/cli.ts",
-    "nucleus-generate": "./bin/cli.ts"
-  },
-  "devDependencies": {
-    "@react-three/fiber": "latest",
-    "@types/bun": "latest",
-    "@types/pg": "latest",
-    "@types/react": "latest",
-    "@types/react-dom": "latest",
-    "@types/three": "latest",
-    "bun-plugin-tailwind": "latest",
-    "drizzle-kit": "latest",
-    "javascript-obfuscator": "latest",
-    "lucide-react": "latest",
-    "three": "latest"
-  },
-  "peerDependencies": {
-    "typescript": "latest",
-    "elysia": "latest",
-    "@dapr/dapr": "latest",
-    "react": "latest",
-    "react-dom": "latest",
-    "pg": "latest",
-    "tailwindcss": "latest",
-    "tailwind-merge": "latest",
-    "clsx": "latest"
-  },
-  "dependencies": {
-    "@elysiajs/static": "latest",
-    "@elysiajs/swagger": "latest",
-    "@gsap/react": "latest",
-    "@simplewebauthn/server": "^13.3.0",
-    "@xyflow/react": "latest",
-    "drizzle-orm": "latest",
-    "googleapis": "latest",
-    "gsap": "latest",
-    "h-state": "latest",
-    "ioredis": "latest",
-    "reflect-metadata": "^0.2.2"
-  },
-  "optionalDependencies": {
-    "@azure/communication-email": "latest",
-    "stripe": "latest"
-  }
+	"name": "nucleus-core-ts",
+	"version": "0.9.706",
+	"description": "Production-ready, enterprise-grade TypeScript framework for building multi-tenant APIs",
+	"author": "Hidayet Can Özcan <hidayetcan@gmail.com>",
+	"license": "SEE LICENSE IN LICENSE",
+	"keywords": [
+		"backend",
+		"framework",
+		"elysia",
+		"drizzle",
+		"typescript"
+	],
+	"files": [
+		"bin",
+		"dist",
+		"schemas",
+		"scripts",
+		"infra/templates",
+		"infra/scripts/generate-project.ts",
+		"src/system.tables.json",
+		"public",
+		"LICENSE"
+	],
+	"module": "dist/index.js",
+	"type": "module",
+	"types": "dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		},
+		"./client": {
+			"types": "./dist/client.d.ts",
+			"import": "./dist/client.js"
+		},
+		"./fe": {
+			"types": "./dist/fe/index.d.ts",
+			"import": "./dist/fe/index.js"
+		},
+		"./fe/auth": {
+			"types": "./dist/fe/components/AuthGuard/index.d.ts",
+			"import": "./dist/fe/components/AuthGuard/index.js"
+		},
+		"./proxy": {
+			"types": "./dist/src/Client/Proxy/index.d.ts",
+			"import": "./dist/src/Client/Proxy/index.js"
+		}
+	},
+	"scripts": {
+		"test": "bun test src",
+		"build": "bun run scripts/build.ts",
+		"build:quick": "bun run build:js && bun run build:types",
+		"build:js": "bun build ./index.ts ./client.ts ./fe/index.ts ./src/Client/Proxy/index.ts --outdir=dist --target=bun --format=esm --splitting --minify --external react --external react-dom --external gsap --external @gsap/react --external h-state --external three --external @react-three/fiber --external elysia --external drizzle-orm --external drizzle-kit --external ioredis --external googleapis --external @dapr/dapr --external pg --external @xyflow/react --external @xyflow/system --external @azure/communication-email --external @azure/identity --external stripe",
+		"build:types": "tsc --declaration --emitDeclarationOnly --outDir dist --skipLibCheck",
+		"version:patch": "bun run scripts/version.ts patch",
+		"version:minor": "bun run scripts/version.ts minor",
+		"version:major": "bun run scripts/version.ts major",
+		"publish:npm": "bun run scripts/publish.ts",
+		"publish:dry": "bun run scripts/publish.ts --dry-run",
+		"release": "bun run version:patch && bun run publish:npm",
+		"release:minor": "bun run version:minor && bun run publish:npm",
+		"release:major": "bun run version:major && bun run publish:npm",
+		"generate:schemas": "bun run scripts/generate-types-schema.ts",
+		"lint": "biome check . --write",
+		"lint:fix": "biome check --config-path ./biome.json --write",
+		"prepublishOnly": "echo 'Use: bun run publish:npm'"
+	},
+	"bin": {
+		"nucleus-core-ts": "./bin/cli.ts",
+		"nucleus": "./bin/cli.ts",
+		"nucleus-generate": "./bin/cli.ts"
+	},
+	"devDependencies": {
+		"@react-three/fiber": "latest",
+		"@types/bun": "latest",
+		"@types/pg": "latest",
+		"@types/react": "latest",
+		"@types/react-dom": "latest",
+		"@types/three": "latest",
+		"bun-plugin-tailwind": "latest",
+		"drizzle-kit": "latest",
+		"javascript-obfuscator": "latest",
+		"lucide-react": "latest",
+		"three": "latest"
+	},
+	"peerDependencies": {
+		"typescript": "latest",
+		"elysia": "latest",
+		"@dapr/dapr": "latest",
+		"react": "latest",
+		"react-dom": "latest",
+		"pg": "latest",
+		"tailwindcss": "latest",
+		"tailwind-merge": "latest",
+		"clsx": "latest"
+	},
+	"dependencies": {
+		"@elysiajs/static": "latest",
+		"@elysiajs/swagger": "latest",
+		"@gsap/react": "latest",
+		"@simplewebauthn/server": "^13.3.0",
+		"@xyflow/react": "latest",
+		"drizzle-orm": "latest",
+		"googleapis": "latest",
+		"gsap": "latest",
+		"h-state": "latest",
+		"ioredis": "latest",
+		"reflect-metadata": "^0.2.2"
+	},
+	"optionalDependencies": {
+		"@azure/communication-email": "latest",
+		"stripe": "latest"
+	}
 }