@newhomestar/sdk 0.5.2 → 0.6.5

package/dist/index.d.ts

@@ -13,6 +13,18 @@ export interface ActionDef<I extends ZodTypeAny, O extends ZodTypeAny> {
     };
     method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
     path?: string;
+    /**
+     * Per-field parameter metadata — tells the platform where each input field
+     * goes (path, query, body, header) and what UI widget the admin dashboard
+     * should render (text, number, date, select, boolean, etc.).
+     *
+     * If not provided, the system falls back to convention:
+     *   - Fields matching `:param` in path → path params
+     *   - Remaining fields for GET → query params
+     *   - Remaining fields for POST/PUT/PATCH → body params
+     *   - UI type inferred from Zod type (string→text, number→number, boolean→boolean, enum→select)
+     */
+    params?: Record<string, import("./integration.js").ParamMeta>;
     capabilities?: Array<{
         type: 'webhook';
         eventTypes: string[];
@@ -40,12 +52,61 @@ export interface ActionDef<I extends ZodTypeAny, O extends ZodTypeAny> {
         consumerGroup?: string;
     }>;
 }
+/** Validated JWT claims from express-oauth2-jwt-bearer */
+export interface JWTPayload {
+    /** Issuer (iss claim) */
+    iss?: string;
+    /** Subject (sub claim) — typically the user ID */
+    sub?: string;
+    /** Audience (aud claim) */
+    aud?: string | string[];
+    /** Expiration time (exp claim) */
+    exp?: number;
+    /** Issued at (iat claim) */
+    iat?: number;
+    /** JWT ID (jti claim) */
+    jti?: string;
+    /** Client ID (azp / client_id claim) */
+    azp?: string;
+    client_id?: string;
+    /** Any additional custom claims */
+    [key: string]: unknown;
+}
 export interface ActionCtx {
     jobId: string;
     progress: (percent: number, meta?: unknown) => void;
+    /** Raw HTTP headers from the inbound request (HTTP mode only) */
+    headers?: Record<string, string | string[] | undefined>;
+    /** Bearer token extracted from the Authorization header (HTTP mode only) */
+    authToken?: string;
+    /** Validated JWT payload from JWKS verification (HTTP mode only) */
+    auth?: JWTPayload;
+    /**
+     * Resolve OAuth credentials for the current integration (or a named slug).
+     * Handles all auth modes (mtls, client_credentials, standard) with
+     * 3-tier caching: in-memory → DB (vault-encrypted) → fresh token exchange.
+     *
+     * @param slug    - Integration slug (defaults to the current worker's name)
+     * @param userId  - User ID for standard OAuth; omit for server flows
+     */
+    resolveCredentials: (slug?: string, userId?: string) => Promise<import("./credentials.js").ResolvedCredentials>;
+    /**
+     * mTLS-aware fetch wrapper. Resolves credentials automatically (or accepts
+     * pre-resolved ones) and handles node:https for mTLS integrations.
+     *
+     * @param url         - Full URL to fetch
+     * @param options     - Standard fetch options (method, headers, body)
+     * @param credentials - Pre-resolved credentials; if omitted, calls resolveCredentials()
+     */
+    fetch: (url: string, options?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string;
+    }, credentials?: import("./credentials.js").ResolvedCredentials) => Promise<Response>;
 }
 export declare function action<I extends ZodTypeAny, O extends ZodTypeAny>(cfg: {
     name?: string;
+    description?: string;
     input: I;
     output: O;
     fga?: {
@@ -56,6 +117,14 @@ export declare function action<I extends ZodTypeAny, O extends ZodTypeAny>(cfg:
     };
     method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
     path?: string;
+    scopes?: string[];
+    category?: string;
+    /**
+     * Per-field parameter metadata — tells the platform where each input field
+     * goes (path, query, body, header) and what UI widget to render.
+     * @see ParamMeta from ./integration.js
+     */
+    params?: Record<string, import("./integration.js").ParamMeta>;
     capabilities?: Array<{
         type: 'webhook';
         eventTypes: string[];
@@ -121,11 +190,40 @@ export declare function generateOpenAPISpec<T extends WorkerDef>(def: T): Promis
     paths: any;
 }>;
 /**
- * Enhanced HTTP server exposing each action under configurable routes
+ * Options for runHttpServer, including optional JWKS auth configuration.
  */
-export declare function runHttpServer<T extends WorkerDef>(def: T, opts?: {
+export interface HttpServerOptions {
     port?: number;
-}): void;
+    /**
+     * Auth issuer base URL (OIDC provider). The library fetches
+     * `{issuerBaseURL}/.well-known/jwks.json` automatically.
+     * Falls back to AUTH_ISSUER_BASE_URL env var, then to the production default.
+     */
+    issuerBaseURL?: string;
+    /**
+     * Expected JWT audience claim.
+     * Falls back to AUTH_AUDIENCE env var, then "starfleet".
+     */
+    audience?: string;
+    /**
+     * Paths that should NOT require a valid JWT (e.g. health checks).
+     * `/health` and `/healthcheck` are always exempt.
+     */
+    publicPaths?: string[];
+    /**
+     * Set to true to completely disable JWKS auth (e.g. local dev without an auth server).
+     * Falls back to NOVA_SKIP_AUTH env var ("true" / "1").
+     */
+    skipAuth?: boolean;
+}
+/**
+ * Enhanced HTTP server exposing each action under configurable routes.
+ * All routes are protected by JWKS-based JWT verification (RS256) via
+ * express-oauth2-jwt-bearer, matching the project-starfleet-backend pattern.
+ *
+ * Health / liveness endpoints are automatically exempted from auth.
+ */
+export declare function runHttpServer<T extends WorkerDef>(def: T, opts?: HttpServerOptions): void;
 /**
  * Run both HTTP server and queue consumer concurrently
  * This gives you the best of both worlds: direct API access AND event processing
@@ -136,6 +234,10 @@ export declare function runDualMode<T extends WorkerDef>(def: T, opts?: {
 export type { ZodTypeAny as SchemaAny, ZodTypeAny };
 export { parseNovaSpec } from "./parseSpec.js";
 export type { NovaSpec } from "./parseSpec.js";
+export { defineIntegration, validateIntegration, integrationSchema, integrationEvent, integrationFunction, schema, event, IntegrationDefSchema, } from "./integration.js";
+export type { IntegrationDef, IntegrationSchemaDef, IntegrationEventDef, IntegrationFunctionDef, ValidationResult, SchemaType, ParamMeta, ParamIn, ParamUiType, } from "./integration.js";
+export { parseIntegrationSpec, IntegrationSpecSchema } from "./integrationSpec.js";
+export type { IntegrationSpec } from "./integrationSpec.js";
 export type WebhookCapability = {
     type: 'webhook';
     eventTypes: string[];
@@ -166,3 +268,5 @@ export type StreamCapability = {
     consumerGroup?: string;
 };
 export type Capability = WebhookCapability | ScheduledCapability | QueueCapability | StreamCapability;
+export { createPlatformClient, resolveCredentials, resolveCredentialsViaHttp, detectCredentialStrategy, integrationFetch, emitPlatformEvent, IntegrationNotFoundError, IntegrationDisabledError, CredentialsNotConfiguredError, ConnectionNotFoundError, TokenExchangeError, } from "./credentials.js";
+export type { ResolvedCredentials, IntegrationConfig, AuthMode, } from "./credentials.js";

package/dist/index.js

@@ -1,12 +1,3 @@
-// nova-sdk-esm – Modern ESM Nova SDK with full oRPC integration (v0.4.2)
-// =====================================================
-// 1. Public API – action(), defineWorker(), enqueue() - SAME AS BEFORE
-// 2. Enhanced HTTP server with REST endpoints and custom routing
-// 3. Full oRPC integration with OpenAPI spec generation
-// 4. Runtime harness for *worker* pipelines using Supabase RPC
-// 5. Modern ESM architecture for future compatibility
-// -----------------------------------------------------------
-import { z } from "zod";
 import dotenv from "dotenv";
 import { createClient } from "@supabase/supabase-js";
 import { OpenFgaClient } from "@openfga/sdk";
@@ -15,7 +6,7 @@ import { createServer } from "node:http";
 import { os } from "@orpc/server";
 import { RPCHandler } from "@orpc/server/node";
 import { CORSPlugin } from "@orpc/server/plugins";
-import { OpenAPIHandler } from "@orpc/openapi/fetch";
+import { createPlatformClient, resolveCredentials as _resolveCredentials, resolveCredentialsViaHttp as _resolveCredentialsViaHttp, detectCredentialStrategy, integrationFetch as _integrationFetch, } from "./credentials.js";
 if (!process.env.RUNTIME_SUPABASE_URL) {
     // local dev – read .env.local
     dotenv.config({ path: ".env.local", override: true });
@@ -71,11 +62,13 @@ export function createORPCRouter(def) {
             .input(actionDef.input)
             .output(actionDef.output)
             .handler(async ({ input, context }) => {
+            const credCtx = buildCredentialCtx(def.name);
             const ctx = {
                 jobId: context?.jobId || `orpc-${Date.now()}`,
                 progress: (percent, meta) => {
                     console.log(`[${actionName}] Progress: ${percent}%`, meta);
-                }
+                },
+                ...credCtx,
             };
             return await actionDef.handler(input, ctx);
         })
@@ -258,9 +251,11 @@ export async function runWorker(def) {
             }
             try {
                 const parsedInput = act.input.parse(payload);
+                const credCtx = buildCredentialCtx(def.name);
                 const ctx = {
                     jobId,
                     progress: (percent, meta) => runtime.from("job_events").insert({ job_id: jobId, percent, meta }),
+                    ...credCtx,
                 };
                 const result = await act.handler(parsedInput, ctx);
                 act.output.parse(result);
@@ -323,29 +318,245 @@ export async function generateOpenAPISpec(def) {
         }, {})
     };
 }
+/*──────────────── Credential Context Builder ───────────────*/
+/**
+ * Build resolveCredentials() and fetch() methods bound to this worker's slug.
+ *
+ * Automatically detects the credential resolution strategy:
+ *   - **Strategy A (DB)**: PLATFORM_SUPABASE_* env vars → direct Supabase Vault access
+ *   - **Strategy B (HTTP)**: AUTH_ISSUER_BASE_URL env var → call auth server with JWT
+ *
+ * @param defaultSlug - Integration slug (e.g., "adp")
+ * @param authToken   - JWT Bearer token from the inbound request (for HTTP strategy)
+ */
+function buildCredentialCtx(defaultSlug, authToken) {
+    // Cache the resolved credentials per request to avoid duplicate round-trips
+    let _lastCreds = null;
+    const strategy = detectCredentialStrategy();
+    const ctxResolveCredentials = async (slug, userId) => {
+        const targetSlug = slug ?? defaultSlug;
+        if (strategy === "db") {
+            // Strategy A: Direct DB access via PLATFORM_SUPABASE_*
+            const platformDB = createPlatformClient();
+            const creds = await _resolveCredentials(platformDB, targetSlug, userId);
+            _lastCreds = creds;
+            return creds;
+        }
+        if (strategy === "http") {
+            // Strategy B: HTTP callback to auth server with JWT
+            const authBaseUrl = process.env.AUTH_ISSUER_BASE_URL;
+            if (!authToken) {
+                throw new Error(`[nova-sdk] HTTP credential resolution requires a JWT bearer token, ` +
+                    `but no authToken was provided in the request context. ` +
+                    `Ensure the request includes an Authorization: Bearer header.`);
+            }
+            const creds = await _resolveCredentialsViaHttp(authBaseUrl, targetSlug, authToken, userId);
+            _lastCreds = creds;
+            return creds;
+        }
+        // strategy === "none"
+        throw new Error(`[nova-sdk] No credential resolution strategy available. ` +
+            `Set either PLATFORM_SUPABASE_URL + PLATFORM_SUPABASE_SERVICE_ROLE_KEY (direct DB) ` +
+            `or AUTH_ISSUER_BASE_URL (HTTP callback) to enable credential resolution.`);
+    };
+    const ctxFetch = async (url, options, credentials) => {
+        const creds = credentials ?? _lastCreds ?? await ctxResolveCredentials();
+        return _integrationFetch(url, creds, options);
+    };
+    return { resolveCredentials: ctxResolveCredentials, fetch: ctxFetch };
+}
 /*──────────────── HTTP Server Harness (Enhanced) ───────────────*/
 import express from "express";
 import bodyParser from "body-parser";
+import { auth } from "express-oauth2-jwt-bearer";
 /**
- * Enhanced HTTP server exposing each action under configurable routes
+ * Enhanced HTTP server exposing each action under configurable routes.
+ * All routes are protected by JWKS-based JWT verification (RS256) via
+ * express-oauth2-jwt-bearer, matching the project-starfleet-backend pattern.
+ *
+ * Health / liveness endpoints are automatically exempted from auth.
  */
 export function runHttpServer(def, opts = {}) {
     const app = express();
     app.use(bodyParser.json());
+    // ── Determine whether auth is enabled ──
+    const skipAuth = opts.skipAuth ??
+        ['true', '1'].includes((process.env.NOVA_SKIP_AUTH ?? '').toLowerCase());
+    // ── Build the set of public (unauthenticated) paths ──
+    const publicPaths = new Set([
+        '/health',
+        '/healthcheck',
+        '/healthcheck/',
+        ...(opts.publicPaths ?? []),
+    ]);
+    // Also exempt any action named "health"
+    for (const [actionName, act] of Object.entries(def.actions)) {
+        if (actionName === 'health') {
+            const route = act.path || `/${def.name}/${actionName}`;
+            publicPaths.add(route);
+        }
+    }
+    if (!skipAuth) {
+        // ── JWKS middleware (same pattern as project-starfleet-backend) ──
+        const issuerBaseURL = opts.issuerBaseURL ??
+            process.env.AUTH_ISSUER_BASE_URL ??
+            'https://auth.newhomeconnect.dev';
+        const audience = opts.audience ??
+            process.env.AUTH_AUDIENCE ??
+            'starfleet';
+        console.log(`[nova] 🔐 JWKS auth enabled — issuer: ${issuerBaseURL}, audience: ${audience}`);
+        console.log(`[nova] 🔓 Public (unauthenticated) paths: ${[...publicPaths].join(', ')}`);
+        const jwtCheck = auth({
+            audience,
+            issuerBaseURL,
+            tokenSigningAlg: 'RS256',
+        });
+        // Apply JWKS middleware to all routes EXCEPT public paths
+        app.use((req, res, next) => {
+            if (publicPaths.has(req.path)) {
+                return next();
+            }
+            return jwtCheck(req, res, next);
+        });
+        // ── InvalidTokenError handler (matches project-starfleet-backend) ──
+        app.use((err, _req, res, next) => {
+            if (err && (err.name === 'InvalidTokenError' || err.code === 'invalid_token')) {
+                console.warn(`[nova] 🚫 JWT rejected: ${err.message}`);
+                return res.status(401).json({
+                    error: 'Unauthorized',
+                    message: 'Invalid or expired token',
+                    code: 'invalid_token',
+                });
+            }
+            if (err && err.status === 401) {
+                console.warn(`[nova] 🚫 Auth failed: ${err.message}`);
+                return res.status(401).json({
+                    error: 'Unauthorized',
+                    message: err.message || 'Authentication failed',
+                });
+            }
+            next(err);
+        });
+    }
+    else {
+        console.warn(`[nova] ⚠️  JWKS auth DISABLED (skipAuth=true). All routes are public.`);
+    }
+    // ── Register action routes ──
     for (const [actionName, act] of Object.entries(def.actions)) {
         const method = (act.method || 'POST').toLowerCase();
         const route = act.path || `/${def.name}/${actionName}`;
-        // unified handler: parse JSON body or default to empty object
         const handler = async (req, res) => {
             try {
-                const payload = req.body && typeof req.body === 'object' ? req.body : {};
-                const input = act.input.parse(payload);
-                const ctx = { jobId: `http-${Date.now()}`, progress: () => { } };
+                // ── Smart input extraction using params metadata ──
+                // Merges path params, query params, and body based on explicit
+                // `params` metadata OR convention (GET→query, POST→body).
+                const rawInput = {};
+                const paramsMeta = act.params ?? {};
+                const hasExplicitParams = Object.keys(paramsMeta).length > 0;
+                if (hasExplicitParams) {
+                    // ── Explicit params mode: use metadata to route fields ──
+                    for (const [key, meta] of Object.entries(paramsMeta)) {
+                        if (meta.in === 'path' && req.params?.[key] !== undefined) {
+                            rawInput[key] = req.params[key];
+                        }
+                        else if (meta.in === 'query' && req.query?.[key] !== undefined) {
+                            rawInput[key] = req.query[key];
+                        }
+                        else if (meta.in === 'header') {
+                            const headerVal = req.headers?.[key.toLowerCase()];
+                            if (headerVal !== undefined)
+                                rawInput[key] = headerVal;
+                        }
+                        else if (meta.in === 'body' && req.body?.[key] !== undefined) {
+                            rawInput[key] = req.body[key];
+                        }
+                    }
+                    // Also include any body fields not in params (backward compat)
+                    if (req.body && typeof req.body === 'object') {
+                        for (const [k, v] of Object.entries(req.body)) {
+                            if (!(k in rawInput))
+                                rawInput[k] = v;
+                        }
+                    }
+                }
+                else {
+                    // ── Convention mode: derive from HTTP method + path ──
+                    // 1. Path params from Express :param matching
+                    if (req.params && typeof req.params === 'object') {
+                        Object.assign(rawInput, req.params);
+                    }
+                    // 2. For GET requests: all remaining input comes from query params
+                    if (method === 'get' && req.query && typeof req.query === 'object') {
+                        Object.assign(rawInput, req.query);
+                    }
+                    // 3. Body params (for all methods — Express won't have body for GET usually)
+                    if (req.body && typeof req.body === 'object') {
+                        Object.assign(rawInput, req.body);
+                    }
+                }
+                // ── Type coercion for query/path string values ──
+                // Express delivers query and path params as strings, but Zod expects
+                // numbers/booleans. Coerce based on params metadata or Zod schema shape.
+                for (const [key, val] of Object.entries(rawInput)) {
+                    if (typeof val !== 'string')
+                        continue;
+                    const meta = paramsMeta[key];
+                    const uiType = meta?.uiType;
+                    // Coerce numbers
+                    if (uiType === 'number' || uiType === 'integer') {
+                        const parsed = Number(val);
+                        if (!isNaN(parsed))
+                            rawInput[key] = parsed;
+                    }
+                    // Coerce booleans
+                    else if (uiType === 'boolean') {
+                        rawInput[key] = val === 'true' || val === '1';
+                    }
+                    // Auto-detect from Zod schema shape if no explicit uiType
+                    else if (!uiType && act.input?._def?.shape) {
+                        const fieldDef = act.input._def.shape()?.[key];
+                        const innerType = fieldDef?._def?.innerType?._def?.typeName ?? fieldDef?._def?.typeName;
+                        if (innerType === 'ZodNumber') {
+                            const parsed = Number(val);
+                            if (!isNaN(parsed))
+                                rawInput[key] = parsed;
+                        }
+                        else if (innerType === 'ZodBoolean') {
+                            rawInput[key] = val === 'true' || val === '1';
+                        }
+                    }
+                }
+                const input = act.input.parse(rawInput);
+                const jobId = `http-${Date.now()}`;
+                const authHeader = req.headers['authorization'];
+                const authToken = authHeader?.startsWith('Bearer ') ? authHeader.slice(7) : undefined;
+                // Extract validated JWT payload from express-oauth2-jwt-bearer
+                // The library attaches it as req.auth after successful verification
+                const jwtPayload = req.auth?.payload ?? req.auth;
+                const credCtx = buildCredentialCtx(def.name, authToken);
+                const ctx = {
+                    jobId,
+                    progress: (percent, meta) => {
+                        console.log(`[nova][${actionName}] Progress: ${percent}%`, meta ?? '');
+                    },
+                    headers: req.headers,
+                    authToken,
+                    auth: jwtPayload,
+                    ...credCtx,
+                };
+                const authLabel = jwtPayload?.sub
+                    ? ` [auth ✓ sub=${jwtPayload.sub}]`
+                    : authToken
+                        ? ' [auth ✓]'
+                        : ' [no auth]';
+                console.log(`[nova] ▶ ${method.toUpperCase()} ${route} → ${actionName} (${jobId})${authLabel}`);
                 const out = await act.handler(input, ctx);
                 act.output.parse(out);
+                console.log(`[nova] ✅ ${actionName} completed (${jobId})`);
                 res.json(out);
             }
             catch (err) {
+                console.error(`[nova] ❌ ${actionName} failed:`, err.message);
                 res.status(400).json({ error: err.message });
             }
         };
@@ -356,13 +567,22 @@ export function runHttpServer(def, opts = {}) {
             app.get('/health', handler);
         }
     }
+    // ── Log credential resolution strategy ──
+    const credStrategy = detectCredentialStrategy();
+    const strategyLabels = {
+        db: '🗄️  Direct DB (PLATFORM_SUPABASE_*)',
+        http: '🌐 HTTP callback (AUTH_ISSUER_BASE_URL → auth server)',
+        none: '⚠️  NONE — ctx.resolveCredentials() will throw if called',
+    };
+    console.log(`[nova] 🔑 Credential strategy: ${strategyLabels[credStrategy]}`);
     const port = opts.port ?? (process.env.PORT ? parseInt(process.env.PORT) : 8000);
     app.listen(port, () => {
         console.log(`[nova] HTTP server listening on http://localhost:${port}`);
         Object.entries(def.actions).forEach(([actionName, actionDef]) => {
             const method = (actionDef.method || 'POST').toUpperCase();
             const path = actionDef.path || `/${def.name}/${actionName}`;
-            console.log(`[nova] ${method} ${path} -> ${actionName}`);
+            const isPublic = publicPaths.has(path) ? ' 🔓' : ' 🔐';
+            console.log(`[nova] ${method} ${path} -> ${actionName}${isPublic}`);
         });
     });
 }
@@ -392,3 +612,30 @@ export function runDualMode(def, opts = {}) {
 }
 // YAML spec parsing utility
 export { parseNovaSpec } from "./parseSpec.js";
+// Integration definition API
+export { defineIntegration, validateIntegration, 
+// Verbose helpers (backward-compatible)
+integrationSchema, integrationEvent, integrationFunction, 
+// Lean helpers (recommended)
+schema, event, IntegrationDefSchema, } from "./integration.js";
+// Integration spec parsing utility
+export { parseIntegrationSpec, IntegrationSpecSchema } from "./integrationSpec.js";
+/*──────────────── Credential Resolution (re-exports) ───────────────*/
+// These are the first-class SDK exports for integration credential management.
+// Every integration gets vault-backed token caching, mTLS, and OAuth for free.
+export { createPlatformClient, resolveCredentials, resolveCredentialsViaHttp, detectCredentialStrategy, integrationFetch, emitPlatformEvent, 
+// Error classes
+IntegrationNotFoundError, IntegrationDisabledError, CredentialsNotConfiguredError, ConnectionNotFoundError, TokenExchangeError, } from "./credentials.js";
+// // Default export for compatibility
+// import { parseNovaSpec as parseNovaSpecFunction } from "./parseSpec.js";
+// export default {
+//   defineWorker,
+//   action,
+//   enqueue,
+//   runHttpServer,
+//   runORPCServer,
+//   runWorker,
+//   generateOpenAPISpec,
+//   createORPCRouter,
+//   parseNovaSpec: parseNovaSpecFunction
+// };