@newhomestar/sdk 0.7.21 → 0.7.24

package/dist/credentials.d.ts

@@ -37,26 +37,26 @@ export declare class TokenExchangeError extends Error {
  */
 export declare function createPlatformClient(): SupabaseClient;
 /**
- * Evict a cached token for the given integration slug and optional userId.
- * Call this when an API returns 401 so the next resolveCredentials() call
- * fetches a fresh token instead of re-using the revoked one.
+ * No-op — token cache has been removed.
+ * Retained for backward compatibility with integration code that calls it on 401.
  */
 export declare function clearTokenCache(slug: string, userId?: string): void;
 /**
  * Resolve credentials for an integration using the HTTP callback strategy.
  *
- * Resolution order:
- * 1. In-memory cache (hot path — no I/O)
- * 2. Client-side refresh_token grant (if refresh metadata is cached)
- * 3. Fetch decrypted credentials from the auth server via HTTP
- * 4. OAuth token exchange (client_credentials / mTLS)
- * 5. Cache result + refresh metadata in memory
+ * Token caching has been intentionally removed — every call fetches fresh
+ * credentials from the auth server to prevent stale/revoked tokens from
+ * being reused. The auth server and Vault maintain their own caching layer.
+ *
+ * On 401 from the integration API, call again with `{ forceRefresh: true }`
+ * to send X-Nova-Token-Invalid: true and force the auth server to discard
+ * any token it has stored for this integration.
  *
  * @param authBaseUrl - Auth server base URL (AUTH_ISSUER_BASE_URL)
- * @param slug        - Integration slug (e.g., "jira", "adp")
- * @param bearerToken - JWT from the inbound request (to authenticate with auth server)
- * @param userId      - Optional user ID for cache key differentiation (standard auth flows)
- * @param options     - forceRefresh: true → skip cache + signal auth server to refresh
+ * @param slug        - Integration slug (e.g., "jira", "bamboohr")
+ * @param bearerToken - JWT from the inbound request (forwarded to auth server)
+ * @param userId      - Optional user ID (for standard/user-level OAuth flows)
+ * @param options     - forceRefresh: true → send X-Nova-Token-Invalid header
  */
 export declare function resolveCredentialsViaHttp(authBaseUrl: string, slug: string, bearerToken: string, userId?: string, options?: {
     forceRefresh?: boolean;

package/dist/credentials.js

@@ -7,14 +7,16 @@
 //   - 'standard'           → authorization_code (per-user OAuth redirect)
 //
 // Credential resolution strategy:
-//   HTTP callback (AUTH_ISSUER_BASE_URL) — container calls auth server with JWT
+//   HTTP callback (AUTH_ISSUER_BASE_URL) — container calls auth server with JWT.
 //   The container receives a JWT from the inbound request, forwards it to the
 //   auth server, which decrypts credentials from Vault and returns them.
 //
-// Tokens are cached in-memory with client-side refresh_token support:
-//   1. In-memory Map (hot path — no I/O)
-//   2. Client-side refresh_token grant (if refresh metadata is cached)
-//   3. Fresh credentials fetch from auth server + token exchange (cold path)
+// NOTE: In-memory token caching has been intentionally removed.
+//   Every call to resolveCredentialsViaHttp() fetches fresh credentials from
+//   the auth server to prevent stale/revoked tokens from being reused.
+//   The auth server and Vault maintain their own caching layer.
+//   On a 401 from the integration API, ctx.fetch() automatically retries once
+//   with forceRefresh=true to bust the auth server's cached token too.
 //
 // Every integration gets this for free via ctx.resolveCredentials() / ctx.fetch().
 import { createClient } from "@supabase/supabase-js";
@@ -74,37 +76,23 @@ export function createPlatformClient() {
     }
     return _platformClient;
 }
-const _tokenCache = new Map();
-/** Token buffer — refresh tokens 5 minutes before actual expiry */
-const TOKEN_EXPIRY_BUFFER_MS = 5 * 60 * 1000;
+// ─── Token Cache (DISABLED) ─────────────────────────────────────────────────
+//
+// The in-memory token cache has been removed to prevent stale/revoked tokens
+// from being re-used after a provider invalidates them server-side.
+// Every call to resolveCredentialsViaHttp() now fetches fresh credentials from
+// the auth server. The auth server (and Vault) provide their own caching layer.
+//
+// clearTokenCache() is retained as a no-op for backward compatibility with any
+// integration code that calls it explicitly.
 /** System user UUID for client_credentials/mTLS connections (audit trail) */
 const SYSTEM_USER_ID = "00000000-0000-0000-0000-000000000000";
-function getCacheKey(integrationSlug, userId) {
-    return `${integrationSlug}:${userId ?? SYSTEM_USER_ID}`;
-}
 /**
- * Evict a cached token for the given integration slug and optional userId.
- * Call this when an API returns 401 so the next resolveCredentials() call
- * fetches a fresh token instead of re-using the revoked one.
+ * No-op — token cache has been removed.
+ * Retained for backward compatibility with integration code that calls it on 401.
  */
 export function clearTokenCache(slug, userId) {
-    const key = getCacheKey(slug, userId);
-    const deleted = _tokenCache.delete(key);
-    console.log(`[nova-sdk] 🗑️  Cleared in-memory token cache for "${slug}" (key=${key}, existed=${deleted})`);
-}
-function getCachedToken(key) {
-    const cached = _tokenCache.get(key);
-    if (!cached) {
-        console.log(`[nova-sdk] 💭 Cache miss for key="${key}"`);
-        return null;
-    }
-    if (new Date().getTime() >= cached.expiresAt.getTime() - TOKEN_EXPIRY_BUFFER_MS) {
-        console.log(`[nova-sdk] 🔄 In-memory cached token expired for key="${key}" (expired at ${cached.expiresAt.toISOString()})`);
-        _tokenCache.delete(key);
-        return null;
-    }
-    console.log(`[nova-sdk] ⚡ Cache hit for key="${key}" (expires ${cached.expiresAt.toISOString()})`);
-    return cached;
+    console.log(`[nova-sdk] 🗑️  clearTokenCache("${slug}") called — cache is disabled, no-op`);
 }
 // ─── mTLS Agent Cache ───────────────────────────────────────────────────────
 // Cache mTLS agents per integration slug (cert/key don't change during container lifetime)
@@ -189,60 +177,6 @@ async function performTokenExchange(slug, params) {
     }
     return res.json();
 }
-// ─── Client-Side Refresh Grant ──────────────────────────────────────────────
-/**
- * Attempt a client-side refresh_token grant using cached refresh metadata.
- * Returns null if refresh metadata is not available (caller should fall through
- * to fetching fresh credentials from the auth server).
- *
- * This avoids a round-trip to the auth server when we already have a valid
- * refresh token — reducing latency and auth server load.
- */
-async function performRefreshGrant(slug, cacheKey, cachedEntry) {
-    const { refreshToken, tokenEndpoint, clientId, clientSecret, httpsAgent, authMode } = cachedEntry;
-    if (!refreshToken || !tokenEndpoint || !clientId || !clientSecret) {
-        console.log(`[nova-sdk] 💭 No refresh metadata cached for "${slug}" — skipping client-side refresh`);
-        return null;
-    }
-    console.log(`[nova-sdk] 🔄 Attempting client-side refresh_token grant for "${slug}" (endpoint: ${tokenEndpoint})`);
-    try {
-        const tokenResponse = await performTokenExchange(slug, {
-            tokenEndpoint,
-            clientId,
-            clientSecret,
-            httpsAgent,
-            grantType: "refresh_token",
-            refreshToken,
-        });
-        const expiresAt = new Date(Date.now() + tokenResponse.expires_in * 1000);
-        const effectiveAuthMode = authMode ?? "client_credentials";
-        console.log(`[nova-sdk] ✅ Client-side refresh successful for "${slug}" — expires ${expiresAt.toISOString()} (${tokenResponse.expires_in}s)`);
-        // Update cache with new access token (and new refresh token if rotated)
-        _tokenCache.set(cacheKey, {
-            accessToken: tokenResponse.access_token,
-            expiresAt,
-            httpsAgent,
-            authMode: effectiveAuthMode,
-            refreshToken: tokenResponse.refresh_token ?? refreshToken, // use new RT if provider rotated it
-            tokenEndpoint,
-            clientId,
-            clientSecret,
-        });
-        return {
-            accessToken: tokenResponse.access_token,
-            expiresAt,
-            integrationId: `http:${slug}`,
-            authMode: effectiveAuthMode,
-            httpsAgent,
-        };
-    }
-    catch (err) {
-        console.warn(`[nova-sdk] ⚠️ Client-side refresh failed for "${slug}": ${err.message} — will re-fetch from auth server`);
-        // Clear stale cached entry so we fall through to auth server fetch
-        _tokenCache.delete(cacheKey);
-        return null;
-    }
-}
 /**
  * Fetch integration credentials from the auth server over HTTP.
  * Requires a valid JWT Bearer token (the same one that authenticated the
@@ -285,105 +219,34 @@ async function fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken, fo
 /**
  * Resolve credentials for an integration using the HTTP callback strategy.
  *
- * Resolution order:
- * 1. In-memory cache (hot path — no I/O)
- * 2. Client-side refresh_token grant (if refresh metadata is cached)
- * 3. Fetch decrypted credentials from the auth server via HTTP
- * 4. OAuth token exchange (client_credentials / mTLS)
- * 5. Cache result + refresh metadata in memory
+ * Token caching has been intentionally removed — every call fetches fresh
+ * credentials from the auth server to prevent stale/revoked tokens from
+ * being reused. The auth server and Vault maintain their own caching layer.
+ *
+ * On 401 from the integration API, call again with `{ forceRefresh: true }`
+ * to send X-Nova-Token-Invalid: true and force the auth server to discard
+ * any token it has stored for this integration.
  *
  * @param authBaseUrl - Auth server base URL (AUTH_ISSUER_BASE_URL)
- * @param slug        - Integration slug (e.g., "jira", "adp")
- * @param bearerToken - JWT from the inbound request (to authenticate with auth server)
- * @param userId      - Optional user ID for cache key differentiation (standard auth flows)
- * @param options     - forceRefresh: true → skip cache + signal auth server to refresh
+ * @param slug        - Integration slug (e.g., "jira", "bamboohr")
+ * @param bearerToken - JWT from the inbound request (forwarded to auth server)
+ * @param userId      - Optional user ID (for standard/user-level OAuth flows)
+ * @param options     - forceRefresh: true → send X-Nova-Token-Invalid header
  */
 export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken, userId, options) {
     const effectiveUserId = userId ?? SYSTEM_USER_ID;
-    const cacheKey = getCacheKey(slug, effectiveUserId);
     const forceRefresh = options?.forceRefresh ?? false;
     console.log(`[nova-sdk] 🔑 resolveCredentialsViaHttp: slug="${slug}" userId="${effectiveUserId}" forceRefresh=${forceRefresh} authBaseUrl="${authBaseUrl}"`);
-    // ── Step 1: Check in-memory cache (skip on forceRefresh) ─────────────
-    if (!forceRefresh) {
-        const cached = getCachedToken(cacheKey);
-        if (cached) {
-            const cachedAuthMode = cached.authMode ?? (cached.httpsAgent ? "mtls" : "client_credentials");
-            console.log(`[nova-sdk] ⚡ Cache hit for "${slug}" — returning cached token (authMode: ${cachedAuthMode}, expires: ${cached.expiresAt.toISOString()})`);
-            return {
-                accessToken: cached.accessToken,
-                expiresAt: cached.expiresAt,
-                integrationId: `http:${slug}`,
-                authMode: cachedAuthMode,
-                httpsAgent: cached.httpsAgent,
-            };
-        }
-        // ── Step 2: Try client-side refresh_token grant ───────────────────
-        // The cached entry was evicted (expired), but it may have left refresh metadata
-        // behind if we stored it before eviction. Check the map directly (bypassing
-        // the expiry check) to get refresh metadata from the evicted entry.
-        // Actually, since getCachedToken deletes the entry on expiry, we need to
-        // try a refresh using data we stored before the eviction. If the map no
-        // longer has the entry, we fall through to the auth server.
-        //
-        // Alternative: keep an expired entry temporarily for refresh metadata.
-        // For simplicity, we store a "refresh-only" entry under a separate key.
-        const refreshKey = `${cacheKey}:refresh`;
-        const refreshEntry = _tokenCache.get(refreshKey);
-        if (refreshEntry) {
-            console.log(`[nova-sdk] 🔄 Found refresh metadata for "${slug}" — attempting client-side refresh`);
-            const refreshed = await performRefreshGrant(slug, cacheKey, refreshEntry);
-            if (refreshed) {
-                // Store updated refresh metadata under the refresh key too
-                const updatedEntry = _tokenCache.get(cacheKey);
-                if (updatedEntry) {
-                    _tokenCache.set(refreshKey, {
-                        ...updatedEntry,
-                        // Extend expiry of refresh key far out (refresh tokens are long-lived)
-                        expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
-                    });
-                }
-                return refreshed;
-            }
-            // Refresh failed — fall through to auth server
-            _tokenCache.delete(refreshKey);
-        }
-    }
-    else {
-        // Force refresh — clear cache and refresh entry
-        _tokenCache.delete(cacheKey);
-        _tokenCache.delete(`${cacheKey}:refresh`);
-        console.log(`[nova-sdk] 🗑️  Force refresh: cleared cache for "${slug}" (key=${cacheKey})`);
-    }
-    // ── Step 3: Fetch credentials from auth server ────────────────────────
+    // ── Fetch credentials from auth server (always fresh — no local cache) ──
     console.log(`[nova-sdk] 📡 Fetching fresh credentials from auth server for "${slug}"`);
     const creds = await fetchCredentialsFromAuthServer(authBaseUrl, slug, bearerToken, forceRefresh);
-    // ── Step 3b: Standard auth — use pre-resolved access token ───────────
+    // ── Standard auth — use pre-resolved access token from auth server ────
     if (creds.authMode === "standard") {
         if (creds.accessToken) {
             const expiresAt = creds.expiresAt
                 ? new Date(creds.expiresAt)
                 : new Date(Date.now() + 3600 * 1000); // default 1h if not provided
-            console.log(`[nova-sdk] ✅ Standard auth: using pre-resolved access token for "${slug}" — expires ${expiresAt.toISOString()}`);
-            // Cache access token
-            const cacheEntry = {
-                accessToken: creds.accessToken,
-                expiresAt,
-                authMode: "standard",
-                // Cache refresh metadata if provided — enables client-side refresh next time
-                refreshToken: creds.refreshToken ?? undefined,
-                tokenEndpoint: creds.tokenEndpoint ?? undefined,
-                clientId: creds.clientId ?? undefined,
-                clientSecret: creds.clientSecret ?? undefined,
-            };
-            _tokenCache.set(cacheKey, cacheEntry);
-            // Also store refresh metadata in the long-lived refresh key
-            if (creds.refreshToken && creds.tokenEndpoint) {
-                _tokenCache.set(`${cacheKey}:refresh`, {
-                    ...cacheEntry,
-                    expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
-                });
-                console.log(`[nova-sdk] 💾 Cached refresh metadata for "${slug}" (standard auth)`);
-            }
+            console.log(`[nova-sdk] ✅ Standard auth: received access token for "${slug}" — expires ${expiresAt.toISOString()}`);
             return {
                 accessToken: creds.accessToken,
                 expiresAt,
@@ -391,11 +254,11 @@ export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken,
                 authMode: "standard",
             };
         }
-        // Standard auth but no access token returned — user hasn't authorized yet
+        // Standard auth but no access token — user hasn't authorized yet
         console.error(`[nova-sdk] ❌ Standard auth: no access token returned for "${slug}" — user must authorize via OAuth popup`);
         throw new ConnectionNotFoundError(slug, `${effectiveUserId} (no stored access token — user must authorize via OAuth popup first)`);
     }
-    // ── Step 4: Validate required fields (client_credentials / mTLS only) ──
+    // ── Validate required fields (client_credentials / mTLS) ─────────────
     if (!creds.clientId) {
         throw new CredentialsNotConfiguredError(slug, "client_id is not set");
     }
@@ -406,7 +269,7 @@ export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken,
         throw new CredentialsNotConfiguredError(slug, "token_endpoint is not set");
     }
     console.log(`[nova-sdk] 🔧 Credentials received: authMode=${creds.authMode} clientId=${creds.clientId?.slice(0, 8)}... tokenEndpoint=${creds.tokenEndpoint}`);
-    // ── Step 5: Build mTLS agent if needed ────────────────────────────────
+    // ── Build mTLS agent if needed ────────────────────────────────────────
     let httpsAgent;
     if (creds.authMode === "mtls") {
         if (!creds.mtlsCert || !creds.mtlsKey) {
@@ -414,7 +277,7 @@ export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken,
         }
         httpsAgent = buildMtlsAgentFromPem(slug, creds.mtlsCert, creds.mtlsKey);
     }
-    // ── Step 6: Perform token exchange (client_credentials / mTLS) ────────
+    // ── Perform token exchange (client_credentials / mTLS) ───────────────
     console.log(`[nova-sdk] 🔄 Performing ${creds.authMode} token exchange at ${creds.tokenEndpoint} for "${slug}"`);
     const tokenResponse = await performTokenExchange(slug, {
         tokenEndpoint: creds.tokenEndpoint,
@@ -423,28 +286,7 @@ export async function resolveCredentialsViaHttp(authBaseUrl, slug, bearerToken,
         httpsAgent,
     });
     const expiresAt = new Date(Date.now() + tokenResponse.expires_in * 1000);
-    console.log(`[nova-sdk] ✅ Token exchange successful for "${slug}" — expires ${expiresAt.toISOString()} (${tokenResponse.expires_in}s, hasRefreshToken: ${!!tokenResponse.refresh_token})`);
-    // ── Step 7: Cache in memory with refresh metadata ─────────────────────
-    const cacheEntry = {
-        accessToken: tokenResponse.access_token,
-        expiresAt,
-        httpsAgent,
-        authMode: creds.authMode,
-        // Store refresh metadata for client-side refresh next time
-        refreshToken: tokenResponse.refresh_token ?? undefined,
-        tokenEndpoint: creds.tokenEndpoint,
-        clientId: creds.clientId,
-        clientSecret: creds.clientSecret,
-    };
-    _tokenCache.set(cacheKey, cacheEntry);
-    // Also persist refresh metadata in a long-lived key (survives access token expiry)
-    if (tokenResponse.refresh_token) {
-        _tokenCache.set(`${cacheKey}:refresh`, {
-            ...cacheEntry,
-            expiresAt: new Date(Date.now() + 30 * 24 * 60 * 60 * 1000), // 30 days
-        });
-        console.log(`[nova-sdk] 💾 Cached refresh metadata for "${slug}"`);
-    }
+    console.log(`[nova-sdk] ✅ Token exchange successful for "${slug}" — expires ${expiresAt.toISOString()} (${tokenResponse.expires_in}s)`);
     return {
         accessToken: tokenResponse.access_token,
         expiresAt,

package/dist/index.d.ts

@@ -170,8 +170,9 @@ export interface ActionCtx {
     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.
+     * Handles all auth modes (mtls, client_credentials, standard).
+     * Always fetches fresh credentials from the auth server — no local token cache.
+     * On 401, use ctx.fetch() which automatically retries with forceRefresh=true.
      *
      * @param slug    - Integration slug (defaults to the current worker's name)
      * @param userId  - User ID for standard OAuth; omit for server flows

package/dist/index.js

@@ -6,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 { resolveCredentialsViaHttp as _resolveCredentialsViaHttp, detectCredentialStrategy, integrationFetch as _integrationFetch, clearTokenCache as _clearTokenCache, } from "./credentials.js";
+import { 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 });
@@ -545,7 +545,10 @@ export async function generateOpenAPISpec(def) {
  *   AUTH_ISSUER_BASE_URL → calls the auth server with the inbound JWT to
  *   retrieve credentials, then performs the OAuth token exchange locally.
  *
- * Token cache order: in-memory → client-side refresh_token grant → auth server fetch
+ * No local token cache — every resolveCredentials() call fetches fresh from
+ * the auth server. A per-request _lastCreds variable avoids duplicate calls
+ * within the same handler invocation.
+ * On 401, ctx.fetch() retries once with forceRefresh=true (X-Nova-Token-Invalid).
  *
  * @param defaultSlug - Integration slug (e.g., "jira", "bamboohr")
  * @param authToken   - JWT Bearer token from the inbound request (forwarded to auth server)
@@ -577,14 +580,14 @@ function buildCredentialCtx(defaultSlug, authToken) {
         const response = await _integrationFetch(url, creds, options);
         // ── 401 auto-retry ───────────────────────────────────────────────────────
         // If the API returns 401 AND the caller did NOT supply explicit credentials
-        // (3rd argument), the token may be stale. Clear the cache and force-refresh
-        // from the auth server, then retry the request once.
+        // (3rd argument), force-refresh from the auth server (sends
+        // X-Nova-Token-Invalid: true so the auth server also discards its token),
+        // then retry the request once.
         //
         // If credentials were passed explicitly (3rd arg), skip retry — the caller
         // is managing their own token lifecycle.
         if (response.status === 401 && !credentials) {
-            console.warn(`[nova-sdk] ⚠️ 401 Unauthorized from ${url} — clearing cache and force-refreshing credentials for "${defaultSlug}"`);
-            _clearTokenCache(defaultSlug);
+            console.warn(`[nova-sdk] ⚠️ 401 Unauthorized from ${url} — force-refreshing credentials for "${defaultSlug}" (X-Nova-Token-Invalid)`);
             _lastCreds = null;
             if (strategy !== "http") {
                 console.error(`[nova-sdk] ❌ Cannot force-refresh: strategy is "${strategy}" (not "http")`);
@@ -595,7 +598,7 @@ function buildCredentialCtx(defaultSlug, authToken) {
                 console.error("[nova-sdk] ❌ Cannot force-refresh: no authToken available in request context");
                 return response; // return original 401
             }
-            console.log(`[nova-sdk] 🔄 Force-refreshing token for "${defaultSlug}" via auth server`);
+            console.log(`[nova-sdk] 🔄 Force-refreshing token for "${defaultSlug}" via auth server (forceRefresh=true)`);
             const freshCreds = await _resolveCredentialsViaHttp(authBaseUrl, defaultSlug, authToken, undefined, { forceRefresh: true });
             _lastCreds = freshCreds;
             // Only retry if we actually got a different token — guards against infinite loop

package/dist/next.d.ts

@@ -50,6 +50,183 @@ export interface ParamMeta {
     order?: number;
     group?: string;
 }
+/**
+ * A single FGA relation definition for an object type.
+ * Declared in `defineService().fga.relations[]` and auto-registered in the
+ * IAM service's `entity_relation_definitions` table at `nova services push` time.
+ */
+export interface NovaFgaRelationDef {
+    /** Object type this relation applies to (e.g. 'community', 'trnVideo') */
+    object_type: string;
+    /** The relation name (e.g. 'admin', 'editor', 'member', 'viewer') */
+    relation: string;
+    /**
+     * Relations this relation implies (e.g. admin implies ['editor', 'member']).
+     * The IAM DB trigger pre-expands implied relations into entity_computed_access
+     * automatically — no application code needed for propagation.
+     */
+    implies?: string[];
+    /** Priority for ordering (default: 0). Higher = evaluated first. */
+    priority?: number;
+}
+/**
+ * IAM resource declaration for `defineService().iam.resources[]`.
+ * Declares how the service's permission namespace maps to the Odyssey UI resource tree.
+ * Used by `nova services push` to set resource types, hierarchy levels, and parent-child
+ * relationships between resources.
+ *
+ * @example
+ * ```ts
+ * iam: {
+ *   resources: [
+ *     { name: 'HRIS Admin', resource_path: 'hris_admin', resource_type: 'module', level: 50,
+ *       description: 'HRIS module — unified HR and payroll data' },
+ *     { name: 'Employees', resource_path: 'hris_employees', resource_type: 'block', level: 60,
+ *       parent_resource_path: 'hris_admin', description: 'Employee records' },
+ *   ],
+ * }
+ * ```
+ */
+export interface NovaIamResourceDef {
+    /** Human-readable display name shown in Odyssey UI (e.g. 'Employees', 'HRIS Admin') */
+    name: string;
+    /** Unique resource path — must match the permission slug prefix (e.g. 'hris_employees') */
+    resource_path: string;
+    /** Position in the resource hierarchy */
+    resource_type: 'system' | 'module' | 'block' | 'resource';
+    /** Hierarchy level: 50=module, 60=block, 80=resource */
+    level: number;
+    /** Optional description shown in Odyssey UI */
+    description?: string;
+    /**
+     * resource_path of the parent resource.
+     * Resolved to parentResourceId at `nova services push` time by the IAM service.
+     * e.g. set to 'hris_admin' to nest this resource under the HRIS Admin module.
+     */
+    parent_resource_path?: string;
+    /** Arbitrary metadata stored on the resource record */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * FGA check declared on a novaEndpoint() — runtime-only.
+ * Describes which relation on which object a request's subject must hold.
+ * The schema (relation hierarchy) is declared in `defineService().fga.relations`.
+ *
+ * Used by `nova.assertFga(req, context)` at runtime (Phase 2).
+ * Stored on the endpoint record in the platform DB for Odyssey UI display.
+ */
+export interface NovaFgaCheckDef {
+    /** Object type to check (e.g. 'community', 'trnVideo') */
+    object_type: string;
+    /** Relation the subject must hold (e.g. 'member', 'viewer', 'editor') */
+    relation: string;
+    /**
+     * Where to resolve object_id from in the request:
+     *   'path'  → Next.js route params (e.g. params.id for /communities/:id)
+     *   'query' → URL query string param
+     */
+    object_id_from: 'path' | 'query';
+    /** The param name to extract object_id from (e.g. 'id', 'community_id') */
+    object_id_param: string;
+    /** Optional tenant_id param name for multi-tenant scoped checks */
+    tenant_id_param?: string;
+}
+/**
+ * Service manifest definition — the code-first single source of truth for a
+ * Nova service. `nova services push` reads this to generate nova-service.yaml
+ * and sync all service metadata to the platform.
+ *
+ * Place this in `src/service.ts` (or `src/app/service.ts`) and export as `service`.
+ *
+ * @example
+ * ```ts
+ * // src/service.ts
+ * import { defineService } from '@newhomestar/sdk/next';
+ *
+ * export const service = defineService({
+ *   slug:     'community',
+ *   name:     'Community Service',
+ *   category: 'social',
+ *   runtime:  'nextjs',
+ *   apiDir:   './src/app',
+ *
+ *   fga: {
+ *     relations: [
+ *       { object_type: 'community', relation: 'admin',  implies: ['editor', 'member'], priority: 100 },
+ *       { object_type: 'community', relation: 'editor', implies: ['viewer'],           priority: 50  },
+ *       { object_type: 'community', relation: 'member', implies: ['viewer'],           priority: 30  },
+ *       { object_type: 'community', relation: 'viewer', implies: [],                   priority: 10  },
+ *     ],
+ *   },
+ * });
+ * ```
+ */
+export interface NovaServiceDef {
+    /** Unique service slug (e.g. 'community', 'hris', 'iam') */
+    slug: string;
+    /** Human-readable service name */
+    name: string;
+    /** Service description */
+    description?: string;
+    /** Category for grouping in Odyssey UI (e.g. 'platform', 'social', 'hris') */
+    category?: string;
+    /** Service version (default: '1.0.0') */
+    version?: string;
+    /** Runtime mode (default: 'nextjs') */
+    runtime?: 'nextjs' | 'sdk';
+    /** Path to route files directory (default: './src/app') */
+    apiDir?: string;
+    /** Public base URL for Odyssey UI API tester */
+    baseUrl?: string;
+    /** Shared Zod schemas registered in platform DB on push */
+    schemas?: Array<{
+        slug: string;
+        name: string;
+        file: string;
+        description?: string;
+        version?: string;
+        schemaType?: string;
+    }>;
+    /** Environment variable declarations */
+    envSpec?: Array<{
+        name: string;
+        secret?: boolean;
+        default?: string;
+    }>;
+    /** Container resource requests */
+    resources?: {
+        cpu?: string;
+        memory?: string;
+    };
+    /**
+     * FGA schema — defines relation hierarchies for all object types owned by
+     * this service. Registered in IAM `entity_relation_definitions` at push time.
+     *
+     * This MUST be pushed before any `entity_grants` are assigned, as the
+     * trigger-based expansion relies on these definitions to propagate implied
+     * relations through `entity_computed_access`.
+     */
+    fga?: {
+        relations: NovaFgaRelationDef[];
+    };
+    /**
+     * IAM resource hierarchy — declares how this service's permission namespace
+     * maps to the Odyssey UI resource tree (module → block → resource).
+     *
+     * Resources declared here override the auto-derived defaults (which default
+     * to resource_type: 'module', level: 50, no parent). Use this to:
+     *   - Declare a parent module resource (e.g. 'hris_admin')
+     *   - Nest entity resources as blocks under that module
+     *   - Control display names, descriptions, and hierarchy levels
+     *
+     * At `nova services push` time the CLI reads this, merges with auto-derived
+     * resources from permission slugs, and sends `parent_resource_path` to the
+     * IAM service which resolves it to `parentResourceId` in the DB.
+     */
+    iam?: {
+        resources: NovaIamResourceDef[];
+    };
+}
 /**
  * An event type emitted by a service endpoint.
  * Defined inline in `novaEndpoint()` and auto-registered in the platform
@@ -218,6 +395,47 @@ export interface NovaEndpointDef<I extends ZodTypeAny = ZodTypeAny, O extends Zo
      * ```
      */
     events?: NovaEndpointEventDef[];
+    /**
+     * FGA (Fine-Grained Authorization) check(s) required to access this endpoint.
+     *
+     * The authenticated subject (user) must hold the declared `relation` on the
+     * specified `object_type:object_id` to be granted access.
+     *
+     * The FGA schema (relation hierarchy) is declared separately in
+     * `defineService().fga.relations` and registered at `nova services push` time.
+     * The fgaCheck here is **runtime-only** — it describes how to resolve the
+     * object_id from the current request and which relation to verify.
+     *
+     * Runtime enforcement is via `nova.assertFga(req, { path: params })` (Phase 2).
+     * At push time, the declarations are stored on the endpoint record in the
+     * platform DB for Odyssey UI display.
+     *
+     * @example
+     * ```ts
+     * // Single check: user must be a member of the community
+     * fgaCheck: {
+     *   object_type:     'community',
+     *   relation:        'member',
+     *   object_id_from:  'path',
+     *   object_id_param: 'id',
+     * }
+     *
+     * // Multiple checks: user must be member of community AND editor of the video
+     * fgaCheck: [
+     *   { object_type: 'community', relation: 'member', object_id_from: 'path', object_id_param: 'community_id' },
+     *   { object_type: 'trnVideo',  relation: 'editor', object_id_from: 'path', object_id_param: 'video_id' },
+     * ],
+     * fgaMode: 'all',
+     * ```
+     */
+    fgaCheck?: NovaFgaCheckDef | NovaFgaCheckDef[];
+    /**
+     * When multiple `fgaCheck` entries are declared, controls evaluation logic:
+     *   'all' → every check must pass (default — AND logic, most restrictive)
+     *   'any' → at least one check must pass (OR logic)
+     * Ignored when fgaCheck is a single object.
+     */
+    fgaMode?: 'all' | 'any';
 }
 export type NovaEndpoint<I extends ZodTypeAny = ZodTypeAny, O extends ZodTypeAny = ZodTypeAny> = NovaEndpointDef<I, O> & {
     /**
@@ -370,9 +588,23 @@ export declare function buildPrismaPage(input: CursorPageInputType): {
         id: 'desc';
     }>;
 };
+/**
+ * Convert a snake_case string to camelCase.
+ * Used internally to normalise sort column names from API query params
+ * (snake_case) to Prisma model field names (camelCase).
+ *
+ * @example
+ * ```ts
+ * snakeToCamel('modified_at') // → 'modifiedAt'
+ * snakeToCamel('createdAt')   // → 'createdAt' (no-op)
+ * ```
+ */
+export declare function snakeToCamel(s: string): string;
 /**
  * Build Prisma `skip`, `take`, and `orderBy` from an `OffsetPageInput`.
  * Handles offset pagination and sort direction.
+ * Sort column names are automatically converted from snake_case (API convention)
+ * to camelCase (Prisma convention) via `snakeToCamel()`.
  * Does NOT handle `search` or `filters` — apply those to the `where` clause manually.
  *
  * @example
@@ -497,6 +729,8 @@ export declare const CURSOR_PAGE_PARAMS: Record<string, ParamMeta>;
 export declare const OFFSET_PAGE_PARAMS: Record<string, ParamMeta>;
 /**
  * Metadata for a Nova service — passed to `defineService()`.
+ * Extends `NovaServiceDef` to include FGA relation schema and IAM resource
+ * hierarchy declarations consumed by `nova services push`.
  */
 export interface ServiceDef {
     /** Unique service slug (snake_case). e.g. "nova_ticketing_service" */
@@ -509,6 +743,21 @@ export interface ServiceDef {
     category?: string;
     /** Semver version string — defaults to "1.0.0" */
     version?: string;
+    /**
+     * FGA schema — relation hierarchies for object types owned by this service.
+     * Registered in IAM `entity_relation_definitions` at `nova services push` time.
+     */
+    fga?: {
+        relations: NovaFgaRelationDef[];
+    };
+    /**
+     * IAM resource hierarchy — maps permission namespace to the Odyssey UI tree.
+     * Overrides auto-derived resource names/types/levels and sets parent-child links.
+     * See `NovaIamResourceDef` for field documentation.
+     */
+    iam?: {
+        resources: NovaIamResourceDef[];
+    };
 }
 /**
  * defineService() — declare Nova service identity and auto-set NOVA_SERVICE_SLUG.

package/dist/next.js

@@ -191,9 +191,25 @@ export function buildPrismaPage(input) {
         orderBy: [{ createdAt: 'desc' }, { id: 'desc' }],
     };
 }
+/**
+ * Convert a snake_case string to camelCase.
+ * Used internally to normalise sort column names from API query params
+ * (snake_case) to Prisma model field names (camelCase).
+ *
+ * @example
+ * ```ts
+ * snakeToCamel('modified_at') // → 'modifiedAt'
+ * snakeToCamel('createdAt')   // → 'createdAt' (no-op)
+ * ```
+ */
+export function snakeToCamel(s) {
+    return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
 /**
  * Build Prisma `skip`, `take`, and `orderBy` from an `OffsetPageInput`.
  * Handles offset pagination and sort direction.
+ * Sort column names are automatically converted from snake_case (API convention)
+ * to camelCase (Prisma convention) via `snakeToCamel()`.
  * Does NOT handle `search` or `filters` — apply those to the `where` clause manually.
  *
  * @example
@@ -203,7 +219,7 @@ export function buildPrismaPage(input) {
  * ```
  */
 export function buildPrismaOffsetPage(input, defaultSort = 'createdAt') {
-    const col = input.sort ?? defaultSort;
+    const col = snakeToCamel(input.sort ?? defaultSort);
     return {
         skip: input.offset,
         take: input.limit,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@newhomestar/sdk",
-  "version": "0.7.21",
+  "version": "0.7.24",
   "description": "Type-safe SDK for building Nova pipelines (workers & functions)",
   "homepage": "https://github.com/newhomestar/nova-node-sdk#readme",
   "bugs": {