nucleus-core-ts 0.9.705 → 0.9.707

package/dist/src/Client/Proxy/types.d.ts

@@ -34,6 +34,44 @@ export interface TokenRefreshConfig {
     onRefreshSuccess?: (path: string) => void;
     onRefreshFailure?: (path: string, error: string) => void;
 }
+export interface ManifestRoute {
+    action: string;
+    path: string;
+    method: string;
+}
+/**
+ * Claim-gate config for a proxy target: enforce the discovered endpoint claims
+ * (nucleus endpointDiscovery) at the proxy. Requires the IDP in `jwtClaimsMode: 'embed'`.
+ */
+export interface ProxyAuthorizeConfig {
+    serviceId: string;
+    manifest: {
+        /** Route→action manifest URL (GET /authorization/route-manifest). */
+        url: string;
+        /**
+         * Role→claim-actions manifest URL (GET /authorization/role-claims-manifest),
+         * REQUIRED when claimsMode is 'resolve' (JWT carries roles, not claims).
+         */
+        roleClaimsUrl?: string;
+        token?: string;
+        refreshSec?: number;
+    };
+    jwt: {
+        secret: string;
+        cookieName?: string;
+        headerName?: string;
+    };
+    /**
+     * How the caller's claims are obtained. 'embed' (default): read from the JWT's
+     * `claims`. 'resolve': the JWT carries only `roles`; resolve them to claims via
+     * the role-claims manifest (matches the IDP's jwtClaimsMode: 'resolve').
+     */
+    claimsMode?: 'embed' | 'resolve';
+    mode?: 'audit' | 'enforce';
+    onUnmapped?: 'allow' | 'deny';
+    publicPaths?: string[];
+    godminRole?: string;
+}
 export interface HttpProxyTarget {
     url: string;
     paths: string[];
@@ -48,6 +86,8 @@ export interface HttpProxyTarget {
         cookieName: string;
         headerName?: string;
     };
+    /** Enforce discovered endpoint claims for this target at the proxy. */
+    authorize?: ProxyAuthorizeConfig;
     tokenRefresh?: TokenRefreshConfig;
     changeOrigin?: boolean;
     timeout?: number;

package/dist/src/ElysiaPlugin/routes/authorization/discovery.test.d.ts

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

package/dist/src/ElysiaPlugin/routes/authorization/index.d.ts

@@ -0,0 +1,50 @@
+import type { NodePgDatabase } from 'drizzle-orm/node-postgres';
+import { Elysia } from 'elysia';
+import { type EndpointDiscoveryConfig } from 'src/Services/Authorization/EndpointDiscovery/seed';
+import type { Logger } from 'src/Services/Logger';
+export interface AuthorizationRoutesConfig {
+    db: NodePgDatabase;
+    schemaTables: Record<string, unknown>;
+    logger: Logger;
+    /** endpointDiscovery config, plus an optional shared token for the proxy. */
+    discovery: EndpointDiscoveryConfig & {
+        token?: string;
+    };
+}
+/**
+ * Endpoint-discovery admin + manifest routes.
+ * - `POST /authorization/discover` — godmin re-runs discovery + reconcile.
+ * - `GET /authorization/route-manifest` — the templated route→claim table the reverse
+ *   proxy consumes. Reachable by godmin OR by a caller presenting the configured
+ *   discovery token (`x-discovery-token`), so the proxy (which has no user session)
+ *   can fetch it. The token resolves from `endpointDiscovery.token` then the
+ *   `NUCLEUS_DISCOVERY_TOKEN` env.
+ */
+export declare function createAuthorizationDiscoveryRoutes(cfg: AuthorizationRoutesConfig): Elysia<"", {
+    decorator: {};
+    store: {};
+    derive: {};
+    resolve: {};
+}, {
+    typebox: {};
+    error: {};
+}, {
+    schema: {};
+    standaloneSchema: {};
+    macro: {};
+    macroFn: {};
+    parser: {};
+    response: {};
+}, {}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}, {
+    derive: {};
+    resolve: {};
+    schema: {};
+    standaloneSchema: {};
+    response: {};
+}>;

package/dist/src/ElysiaPlugin/routes/domain/hostnames.d.ts

@@ -2,8 +2,10 @@ import { Elysia } from 'elysia';
 import type { DomainRouteConfig } from './types';
 /**
  * Custom-hostname lifecycle routes. Management requires an authenticated user
- * (x-user-id); deeper ownership/authorization is enforced by the deployment
- * via claims. Mounted under config.basePath (default "/domains").
+ * (x-user-id). Creation additionally binds the hostname's target schema to the
+ * caller's own verified tenant (`x-tenant-schema`) unless the caller is godmin —
+ * see the createHostname handler. Mounted under config.basePath (default
+ * "/domains").
  */
 export declare function createHostnameRoutes(config: DomainRouteConfig): Elysia<"", {
     decorator: {};

package/dist/src/ElysiaPlugin/routes/domain/hostnames.test.d.ts

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

package/dist/src/ElysiaPlugin/routes/payment/marketplace/authz.test.d.ts

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

package/dist/src/ElysiaPlugin/routes/payment/marketplace/types.d.ts

@@ -32,6 +32,15 @@ export declare const isAdmin: (ctx: MarketplaceCtx) => boolean;
  * not an operator.
  */
 export declare const requireAdmin: (ctx: MarketplaceCtx) => string | null;
+/**
+ * Authorizes READING an owner's financial ledger (balance, splits, settlement
+ * policy, payout requests, disputes). Operators may read any owner. A non-operator
+ * may only read their OWN user-scoped ledger — the framework keeps no generic
+ * seller/tenant → user mapping, so ownerType 'seller'/'tenant'/'platform' cannot be
+ * proven to belong to the caller and is operator-only by default. Without this,
+ * any authenticated user could read ANY owner's balances/payouts (financial IDOR).
+ */
+export declare const canReadOwnerLedger: (ctx: MarketplaceCtx, ownerType: string | undefined, ownerId: string | undefined | null) => boolean;
 export declare const failResponse: (ctx: MarketplaceCtx, status: number, message: string) => {
     success: boolean;
     message: string;

package/dist/src/ElysiaPlugin/routes/pubsub/daprAuth.test.d.ts

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

package/dist/src/ElysiaPlugin/routes/pubsub/types.d.ts

@@ -70,6 +70,14 @@ export interface PubSubRouteConfig {
         debounceMs: number;
     };
     cleanupIntervalMs: number;
+    /**
+     * Shared secret Dapr presents (as the `dapr-api-token` header) when it POSTs a
+     * delivered message to the subscription endpoint. When set, the endpoint rejects
+     * any inbound event whose token does not match — without it, ANY caller who can
+     * reach the route could inject realtime events to any user. Resolved from
+     * config.pubsub.daprApiToken, then env APP_API_TOKEN / DAPR_API_TOKEN.
+     */
+    daprApiToken?: string;
     getLiveMonitoringService?: () => LiveMonitoringService | null;
     /**
      * Optional WebSocket handshake authenticator. When provided, every WS

package/dist/src/ElysiaPlugin/routes/storage/cdn.test.d.ts

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

package/dist/src/ElysiaPlugin/utils.d.ts

@@ -71,6 +71,11 @@ export interface ValidationResult {
     errors: ValidationError[];
 }
 export declare function validatePayload(payload: Record<string, unknown>, columns: NucleusColumn[], isPartial?: boolean): ValidationResult;
+/**
+ * True when a column name is an auth-secret that must never cross the wire (in a
+ * row OR as a distinct-value projection). Accepts camelCase or snake_case.
+ */
+export declare function isSensitiveOutputKey(key: string): boolean;
 /** Strip auth-secret columns from a row (or null) before it crosses the wire. */
 export declare function redactSensitiveOutput<T>(row: T): T;
 export declare function sanitizePayload(payload: Record<string, unknown>, columns: NucleusColumn[]): Record<string, unknown>;

package/dist/src/Services/Authorization/EndpointDiscovery/discovery.test.d.ts

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

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,60 @@
+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;
+}>>;
+/**
+ * Build the role→claim-actions manifest a reverse proxy consumes in RESOLVE mode
+ * (where the JWT carries roles but not claims). Returns each role's claim actions
+ * scoped to a service (`{serviceId}.` prefix, plus the bare `{serviceId}` grant),
+ * so the proxy can resolve a user's roles → claim set locally. Active rows only.
+ */
+export declare function getRoleClaimsManifest(db: NodePgDatabase, schemaTables: Record<string, unknown>, serviceId: string): Promise<Record<string, string[]>>;
+export {};

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

@@ -0,0 +1 @@
+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) */