@adventurelabs/scout-core 1.4.75 → 1.4.76

package/dist/helpers/cache.d.ts

@@ -1,4 +1,10 @@
 import { IHerdModule } from "../types/herd_module";
+export type JwtMintCacheKey = "client_abilities" | "pubsub";
+type CachedJwtMint = {
+    token: string;
+    iat: number;
+    exp: number;
+};
 export interface CacheMetadata {
     key: string;
     timestamp: number;
@@ -43,6 +49,9 @@ export declare class ScoutCache {
     private validateDatabaseSchema;
     setHerdModules(herdModules: IHerdModule[], ttlMs?: number, etag?: string): Promise<void>;
     getHerdModules(): Promise<CacheResult<IHerdModule[]>>;
+    setJwtMint<T extends CachedJwtMint>(key: JwtMintCacheKey, mint: T): Promise<void>;
+    getJwtMint<T extends CachedJwtMint>(key: JwtMintCacheKey): Promise<CacheResult<T>>;
+    clearJwtMint(key: JwtMintCacheKey): Promise<void>;
     clearHerdModules(): Promise<void>;
     invalidateHerdModules(): Promise<void>;
     getCacheStats(): Promise<CacheStats>;
@@ -60,3 +69,4 @@ export declare class ScoutCache {
     checkDatabaseHealth(): Promise<DatabaseHealth>;
 }
 export declare const scoutCache: ScoutCache;
+export {};

package/dist/helpers/cache.js

@@ -1,6 +1,7 @@
 const DB_NAME = "ScoutCache";
-const DB_VERSION = 6;
+const DB_VERSION = 8;
 const HERD_MODULES_STORE = "herd_modules";
+const JWT_MINTS_STORE = "jwt_mints";
 const CACHE_METADATA_STORE = "cache_metadata";
 // Default TTL: 24 hours (1 day)
 const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000;
@@ -56,6 +57,13 @@ export class ScoutCache {
                         unique: false,
                     });
                     console.log("[ScoutCache] Created herd_modules object store");
+                    const jwtMintsStore = db.createObjectStore(JWT_MINTS_STORE, {
+                        keyPath: "key",
+                    });
+                    jwtMintsStore.createIndex("timestamp", "timestamp", {
+                        unique: false,
+                    });
+                    console.log("[ScoutCache] Created jwt_mints object store");
                     // Create cache metadata store
                     const metadataStore = db.createObjectStore(CACHE_METADATA_STORE, {
                         keyPath: "key",
@@ -78,14 +86,18 @@ export class ScoutCache {
         if (!this.db)
             return false;
         const hasHerdModulesStore = this.db.objectStoreNames.contains(HERD_MODULES_STORE);
+        const hasJwtMintsStore = this.db.objectStoreNames.contains(JWT_MINTS_STORE);
         const hasMetadataStore = this.db.objectStoreNames.contains(CACHE_METADATA_STORE);
         if (!hasHerdModulesStore) {
             console.error("[ScoutCache] Missing herd_modules object store");
         }
+        if (!hasJwtMintsStore) {
+            console.error("[ScoutCache] Missing jwt_mints object store");
+        }
         if (!hasMetadataStore) {
             console.error("[ScoutCache] Missing cache_metadata object store");
         }
-        return hasHerdModulesStore && hasMetadataStore;
+        return hasHerdModulesStore && hasJwtMintsStore && hasMetadataStore;
     }
     async setHerdModules(herdModules, ttlMs = DEFAULT_TTL_MS, etag) {
         await this.init();
@@ -190,6 +202,78 @@ export class ScoutCache {
             };
         });
     }
+    async setJwtMint(key, mint) {
+        await this.init();
+        if (!this.db)
+            throw new Error("Database not initialized");
+        if (!this.validateDatabaseSchema()) {
+            throw new Error("Database schema validation failed - required object stores not found");
+        }
+        const transaction = this.db.transaction([JWT_MINTS_STORE], "readwrite");
+        return new Promise((resolve, reject) => {
+            transaction.onerror = () => reject(transaction.error);
+            transaction.oncomplete = () => resolve();
+            transaction.objectStore(JWT_MINTS_STORE).put({
+                key,
+                data: mint,
+                timestamp: Date.now(),
+                dbVersion: DB_VERSION,
+            });
+        });
+    }
+    async getJwtMint(key) {
+        await this.init();
+        if (!this.db)
+            throw new Error("Database not initialized");
+        if (!this.validateDatabaseSchema()) {
+            throw new Error("Database schema validation failed - required object stores not found");
+        }
+        const transaction = this.db.transaction([JWT_MINTS_STORE], "readonly");
+        return new Promise((resolve, reject) => {
+            transaction.onerror = () => reject(transaction.error);
+            const request = transaction.objectStore(JWT_MINTS_STORE).get(key);
+            request.onsuccess = () => {
+                const entry = request.result;
+                if (!entry?.data?.token ||
+                    entry.dbVersion !== DB_VERSION ||
+                    !entry.timestamp) {
+                    this.stats.misses++;
+                    resolve({ data: null, isStale: true, age: 0, metadata: null });
+                    return;
+                }
+                const now = Date.now();
+                const age = now - entry.timestamp;
+                const isStale = entry.data.exp <= Math.floor(now / 1000);
+                this.stats.hits++;
+                resolve({
+                    data: entry.data,
+                    isStale,
+                    age,
+                    metadata: {
+                        key,
+                        timestamp: entry.timestamp,
+                        ttl: Math.max((entry.data.exp - entry.data.iat) * 1000, 0),
+                        version: "1.0.0",
+                        dbVersion: DB_VERSION,
+                    },
+                });
+            };
+        });
+    }
+    async clearJwtMint(key) {
+        await this.init();
+        if (!this.db)
+            throw new Error("Database not initialized");
+        if (!this.validateDatabaseSchema()) {
+            throw new Error("Database schema validation failed - required object stores not found");
+        }
+        const transaction = this.db.transaction([JWT_MINTS_STORE], "readwrite");
+        return new Promise((resolve, reject) => {
+            transaction.onerror = () => reject(transaction.error);
+            transaction.oncomplete = () => resolve();
+            transaction.objectStore(JWT_MINTS_STORE).delete(key);
+        });
+    }
     async clearHerdModules() {
         await this.init();
         if (!this.db)

package/dist/helpers/client_abilities_token.d.ts

@@ -4,5 +4,4 @@ import { IClientAbilitiesJwtPublicKeyEntry, IClientAbilitiesTokenMint } from "..
 import { IWebResponseCompatible } from "../types/requests";
 export declare function mint_client_abilities_token(client: SupabaseClient<Database>): Promise<IWebResponseCompatible<IClientAbilitiesTokenMint>>;
 export declare function get_client_abilities_jwt_public_keys(client: SupabaseClient<Database>): Promise<IWebResponseCompatible<IClientAbilitiesJwtPublicKeyEntry[]>>;
-/** Cryptographic check only; returns the same mint envelope from the edge. */
 export declare function verify_client_abilities_token(mint: IClientAbilitiesTokenMint, publicKeys: IClientAbilitiesJwtPublicKeyEntry[]): Promise<IClientAbilitiesTokenMint>;

package/dist/helpers/client_abilities_token.js

@@ -32,7 +32,6 @@ export async function get_client_abilities_jwt_public_keys(client) {
     }
     return IWebResponse.success(keys).to_compatible();
 }
-/** Cryptographic check only; returns the same mint envelope from the edge. */
 export async function verify_client_abilities_token(mint, publicKeys) {
     if (publicKeys.length === 0) {
         throw new Error("no client abilities JWT public keys configured");

package/dist/helpers/pubsub_token.d.ts

@@ -1,5 +1,7 @@
 import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
-import { IPubsubTokenMint } from "../types/pubsub_token";
+import { IPubsubJwtPublicKeyEntry, IPubsubTokenMint } from "../types/pubsub_token";
 import { IWebResponseCompatible } from "../types/requests";
 export declare function mint_pubsub_token(client: SupabaseClient<Database>): Promise<IWebResponseCompatible<IPubsubTokenMint>>;
+export declare function get_pubsub_jwt_public_keys(client: SupabaseClient<Database>): Promise<IWebResponseCompatible<IPubsubJwtPublicKeyEntry[]>>;
+export declare function verify_pubsub_token(mint: IPubsubTokenMint, publicKeys: IPubsubJwtPublicKeyEntry[]): Promise<IPubsubTokenMint>;

package/dist/helpers/pubsub_token.js

@@ -1,3 +1,4 @@
+import * as jose from "jose";
 import { IWebResponse } from "../types/requests";
 export async function mint_pubsub_token(client) {
     const { data, error } = await client.functions.invoke("mint-pubsub-token", {
@@ -12,3 +13,43 @@ export async function mint_pubsub_token(client) {
     }
     return IWebResponse.success(mint).to_compatible();
 }
+export async function get_pubsub_jwt_public_keys(client) {
+    const { data, error } = await client.rpc("get_pubsub_jwt_public_keys");
+    if (error) {
+        return IWebResponse.error(error.message).to_compatible();
+    }
+    const entries = Array.isArray(data) ? data : [];
+    const keys = [];
+    for (const row of entries) {
+        if (row &&
+            typeof row === "object" &&
+            "kid" in row &&
+            "jwk" in row &&
+            typeof row.kid === "string" &&
+            row.jwk &&
+            typeof row.jwk === "object") {
+            keys.push({ kid: row.kid, jwk: row.jwk });
+        }
+    }
+    return IWebResponse.success(keys).to_compatible();
+}
+export async function verify_pubsub_token(mint, publicKeys) {
+    if (publicKeys.length === 0) {
+        throw new Error("no pubsub JWT public keys configured");
+    }
+    const header = jose.decodeProtectedHeader(mint.token);
+    const kid = header.kid;
+    if (!kid || typeof kid !== "string") {
+        throw new Error("pubsub JWT missing kid");
+    }
+    const entry = publicKeys.find((k) => k.kid === kid);
+    if (!entry) {
+        throw new Error(`unknown pubsub JWT kid: ${kid}`);
+    }
+    const alg = typeof entry.jwk.alg === "string" && entry.jwk.alg
+        ? entry.jwk.alg
+        : header.alg ?? "ES256";
+    const verifyKey = await jose.importJWK(entry.jwk, alg);
+    await jose.jwtVerify(mint.token, verifyKey, { algorithms: [alg] });
+    return mint;
+}

package/dist/index.d.ts

@@ -12,6 +12,7 @@ export * from "./types/events";
 export * from "./types/connectivity";
 export * from "./types/pubsub_token";
 export * from "./types/client_abilities_token";
+export * from "./types/jwt_mint";
 export * from "./helpers/analysis_usage";
 export * from "./helpers/artifacts";
 export * from "./helpers/auth";

package/dist/index.js

@@ -14,6 +14,7 @@ export * from "./types/events";
 export * from "./types/connectivity";
 export * from "./types/pubsub_token";
 export * from "./types/client_abilities_token";
+export * from "./types/jwt_mint";
 // Helpers
 export * from "./helpers/analysis_usage";
 export * from "./helpers/artifacts";

package/dist/providers/ScoutRefreshProvider.d.ts

@@ -3,30 +3,31 @@ import { type ReactNode } from "react";
 import { SupabaseClient } from "@supabase/supabase-js";
 import { Database } from "../types/supabase";
 import { IClientAbilitiesTokenMint } from "../types/client_abilities_token";
+import { IPubsubTokenMint } from "../types/pubsub_token";
+import { EnumJwtMintStatus } from "../types/jwt_mint";
 export interface ClientAbilitiesMintState {
-    /** Set only after jose verification against DB pubkeys. */
     mint: IClientAbilitiesTokenMint | null;
-    isLoading: boolean;
+    status: EnumJwtMintStatus;
     error: string | null;
     refreshMint: () => Promise<void>;
 }
 export interface ScoutRefreshAbilityParams {
-    /** Mint and verify a client abilities JWT. Default: `true`. */
     mintClientAbilitiesToken?: boolean;
-    /**
-     * Expected JWT lifetime in seconds (default 1 hour).
-     * Align with edge `CLIENT_ABILITIES_TOKEN_TTL_SEC`; used to schedule re-mint
-     * (falls back when `exp` is missing; otherwise uses `exp` from the mint).
-     */
+    mintPubsubToken?: boolean;
     clientAbilitiesTokenTtlSec?: number;
-    /** Re-mint this many seconds before expiry (default 120). */
+    pubsubTokenTtlSec?: number;
     refreshBeforeExpirySec?: number;
-    /** Ms to cache pubkey RPC results (default 10 min). */
     publicKeysCacheTtlMs?: number;
 }
+export interface PubsubTokenMintState {
+    mint: IPubsubTokenMint | null;
+    status: EnumJwtMintStatus;
+    error: string | null;
+    refreshMint: () => Promise<void>;
+}
 export declare function useSupabase(): SupabaseClient<Database>;
-/** Verified client abilities JWT (minted on a schedule by ScoutRefreshProvider). */
 export declare function useClientAbilitiesMint(): ClientAbilitiesMintState;
+export declare function usePubsubTokenMint(): PubsubTokenMintState;
 export interface ScoutRefreshProviderProps extends UseScoutRefreshOptions {
     children: ReactNode;
     abilityParams?: ScoutRefreshAbilityParams;

package/dist/providers/ScoutRefreshProvider.js

@@ -6,6 +6,10 @@ import { createBrowserClient } from "@supabase/ssr";
 import { CLIENT_ABILITIES_TOKEN_TTL_SEC, } from "../types/client_abilities_token";
 import { EnumWebResponse } from "../types/requests";
 import { get_client_abilities_jwt_public_keys, mint_client_abilities_token, verify_client_abilities_token, } from "../helpers/client_abilities_token";
+import { scoutCache } from "../helpers/cache";
+import { get_pubsub_jwt_public_keys, mint_pubsub_token, verify_pubsub_token, } from "../helpers/pubsub_token";
+import { PUBSUB_TOKEN_TTL_SEC } from "../types/pubsub_token";
+import { derive_jwt_mint_status, } from "../types/jwt_mint";
 const ScoutRefreshContext = createContext(null);
 const DEFAULT_REFRESH_BEFORE_EXPIRY_SEC = 120;
 const DEFAULT_PUBLIC_KEYS_CACHE_MS = 10 * 60 * 1000;
@@ -25,102 +29,123 @@ function useScoutRefreshContext() {
 export function useSupabase() {
     return useScoutRefreshContext().supabase;
 }
-/** Verified client abilities JWT (minted on a schedule by ScoutRefreshProvider). */
 export function useClientAbilitiesMint() {
     return useScoutRefreshContext().abilities;
 }
+export function usePubsubTokenMint() {
+    return useScoutRefreshContext().pubsub;
+}
 function resolveAbilityParams(abilityParams) {
     return {
         mintClientAbilitiesToken: abilityParams?.mintClientAbilitiesToken ?? true,
+        mintPubsubToken: abilityParams?.mintPubsubToken ?? false,
         clientAbilitiesTokenTtlSec: abilityParams?.clientAbilitiesTokenTtlSec ??
             CLIENT_ABILITIES_TOKEN_TTL_SEC,
+        pubsubTokenTtlSec: abilityParams?.pubsubTokenTtlSec ?? PUBSUB_TOKEN_TTL_SEC,
         refreshBeforeExpirySec: abilityParams?.refreshBeforeExpirySec ??
             DEFAULT_REFRESH_BEFORE_EXPIRY_SEC,
         publicKeysCacheTtlMs: abilityParams?.publicKeysCacheTtlMs ?? DEFAULT_PUBLIC_KEYS_CACHE_MS,
     };
 }
-function useClientAbilitiesMintLifecycle(supabase, config) {
-    const { mintClientAbilitiesToken: enabled, clientAbilitiesTokenTtlSec: ttlSec, refreshBeforeExpirySec, publicKeysCacheTtlMs, } = config;
-    const [mint, setMint] = useState(null);
-    const [isLoading, setIsLoading] = useState(false);
-    const [error, setError] = useState(null);
-    const inFlightRef = useRef(false);
-    const publicKeysRef = useRef(null);
-    const publicKeysAtRef = useRef(0);
-    const loadPublicKeys = useCallback(async (force = false) => {
+function useCachedPublicKeys(supabase, publicKeysCacheTtlMs, fetchKeys) {
+    const keysRef = useRef(null);
+    const keysAtRef = useRef(0);
+    return useCallback(async (force = false) => {
         const now = Date.now();
         if (!force &&
-            publicKeysRef.current?.length &&
-            now - publicKeysAtRef.current < publicKeysCacheTtlMs) {
-            return publicKeysRef.current;
+            keysRef.current?.length &&
+            now - keysAtRef.current < publicKeysCacheTtlMs) {
+            return keysRef.current;
         }
-        const { status, data, msg } = await get_client_abilities_jwt_public_keys(supabase);
+        const { status, data, msg } = await fetchKeys(supabase);
         if (status !== EnumWebResponse.SUCCESS || !data?.length) {
-            throw new Error(msg ?? "get_client_abilities_jwt_public_keys returned no keys");
+            throw new Error(msg ?? "jwt public keys RPC returned no keys");
         }
-        publicKeysRef.current = data;
-        publicKeysAtRef.current = now;
+        keysRef.current = data;
+        keysAtRef.current = now;
         return data;
-    }, [supabase, publicKeysCacheTtlMs]);
+    }, [supabase, publicKeysCacheTtlMs, fetchKeys]);
+}
+function useJwtMintLifecycle({ enabled, supabase, cacheKey, ttlSec, refreshBeforeExpirySec, loadPublicKeys, mintToken, verifyToken, }) {
+    const [mint, setMint] = useState(null);
+    const [inFlight, setInFlight] = useState(false);
+    const [error, setError] = useState(null);
+    const inFlightRef = useRef(false);
+    const status = useMemo(() => derive_jwt_mint_status(enabled, mint, inFlight, error), [enabled, mint, inFlight, error]);
     const refreshMint = useCallback(async () => {
         if (!enabled || inFlightRef.current) {
             return;
         }
         inFlightRef.current = true;
-        setIsLoading(true);
+        setInFlight(true);
         setError(null);
         try {
             const { data: { session }, } = await supabase.auth.getSession();
             if (!session) {
                 setMint(null);
+                await scoutCache.clearJwtMint(cacheKey);
                 return;
             }
-            const mintResponse = await mint_client_abilities_token(supabase);
+            const mintResponse = await mintToken(supabase);
             if (mintResponse.status !== EnumWebResponse.SUCCESS ||
                 !mintResponse.data) {
-                setMint(null);
                 setError(mintResponse.msg ?? "mint failed");
                 return;
             }
             let keys = await loadPublicKeys();
             let verified;
             try {
-                verified = await verify_client_abilities_token(mintResponse.data, keys);
+                verified = await verifyToken(mintResponse.data, keys);
             }
             catch {
                 keys = await loadPublicKeys(true);
-                verified = await verify_client_abilities_token(mintResponse.data, keys);
+                verified = await verifyToken(mintResponse.data, keys);
             }
             setMint(verified);
+            try {
+                await scoutCache.setJwtMint(cacheKey, verified);
+            }
+            catch (cacheError) {
+                console.warn(`[ScoutRefreshProvider] ${cacheKey} cache save failed:`, cacheError);
+            }
         }
         catch (e) {
-            setMint(null);
-            setError(e instanceof Error ? e.message : "client abilities mint failed");
+            setError(e instanceof Error ? e.message : "mint failed");
         }
         finally {
             inFlightRef.current = false;
-            setIsLoading(false);
+            setInFlight(false);
         }
-    }, [enabled, supabase, loadPublicKeys]);
+    }, [enabled, supabase, cacheKey, loadPublicKeys, mintToken, verifyToken]);
     useEffect(() => {
         if (!enabled) {
             setMint(null);
             setError(null);
             return;
         }
+        let cancelled = false;
+        void scoutCache.getJwtMint(cacheKey).then((cached) => {
+            if (!cancelled && cached.data) {
+                setMint(cached.data);
+            }
+        });
         void refreshMint();
         const { data: { subscription }, } = supabase.auth.onAuthStateChange((event) => {
             if (event === "SIGNED_OUT") {
                 setMint(null);
                 setError(null);
+                void scoutCache.clearJwtMint(cacheKey);
                 return;
             }
             if (event === "SIGNED_IN" || event === "TOKEN_REFRESHED") {
                 void refreshMint();
             }
         });
-        return () => subscription.unsubscribe();
-    }, [enabled, supabase, refreshMint]);
+        return () => {
+            cancelled = true;
+            subscription.unsubscribe();
+        };
+    }, [enabled, supabase, cacheKey, refreshMint]);
     useEffect(() => {
         if (!enabled || !mint) {
             return;
@@ -134,7 +159,35 @@ function useClientAbilitiesMintLifecycle(supabase, config) {
         }, delayMs);
         return () => clearTimeout(timer);
     }, [enabled, mint, ttlSec, refreshBeforeExpirySec, refreshMint]);
-    return useMemo(() => ({ mint, isLoading, error, refreshMint }), [mint, isLoading, error, refreshMint]);
+    return useMemo(() => ({ mint, status, error, refreshMint }), [mint, status, error, refreshMint]);
+}
+function useClientAbilitiesMintLifecycle(supabase, config) {
+    const { mintClientAbilitiesToken: enabled, clientAbilitiesTokenTtlSec: ttlSec, refreshBeforeExpirySec, publicKeysCacheTtlMs, } = config;
+    const loadPublicKeys = useCachedPublicKeys(supabase, publicKeysCacheTtlMs, get_client_abilities_jwt_public_keys);
+    return useJwtMintLifecycle({
+        enabled,
+        supabase,
+        cacheKey: "client_abilities",
+        ttlSec,
+        refreshBeforeExpirySec,
+        loadPublicKeys,
+        mintToken: mint_client_abilities_token,
+        verifyToken: verify_client_abilities_token,
+    });
+}
+function usePubsubTokenMintLifecycle(supabase, config) {
+    const { mintPubsubToken: enabled, pubsubTokenTtlSec: ttlSec, refreshBeforeExpirySec, publicKeysCacheTtlMs, } = config;
+    const loadPublicKeys = useCachedPublicKeys(supabase, publicKeysCacheTtlMs, get_pubsub_jwt_public_keys);
+    return useJwtMintLifecycle({
+        enabled,
+        supabase,
+        cacheKey: "pubsub",
+        ttlSec,
+        refreshBeforeExpirySec,
+        loadPublicKeys,
+        mintToken: mint_pubsub_token,
+        verifyToken: verify_pubsub_token,
+    });
 }
 export function ScoutRefreshProvider({ children, abilityParams, ...refreshOptions }) {
     const urlRef = useRef(process.env.NEXT_PUBLIC_SUPABASE_URL || "");
@@ -143,6 +196,7 @@ export function ScoutRefreshProvider({ children, abilityParams, ...refreshOption
     const abilitiesConfig = useMemo(() => resolveAbilityParams(abilityParams), [abilityParams]);
     useScoutRefresh({ ...refreshOptions, supabase });
     const abilities = useClientAbilitiesMintLifecycle(supabase, abilitiesConfig);
-    const value = useMemo(() => ({ supabase, abilities }), [supabase, abilities]);
+    const pubsub = usePubsubTokenMintLifecycle(supabase, abilitiesConfig);
+    const value = useMemo(() => ({ supabase, abilities, pubsub }), [supabase, abilities, pubsub]);
     return (_jsx(ScoutRefreshContext.Provider, { value: value, children: children }));
 }

package/dist/types/client_abilities_token.d.ts

@@ -1,10 +1,8 @@
-/** Herd entry inside a minted client abilities JWT (matches edge / RPC payload). */
 export interface IClientAbilitiesHerdClaim {
     herd_id: number;
     slug: string;
     abilities: string[];
 }
-/** Response from `mint-client-abilities-token`. */
 export interface IClientAbilitiesTokenMint {
     token: string;
     platform_superadmin: boolean;
@@ -12,13 +10,10 @@ export interface IClientAbilitiesTokenMint {
     iat: number;
     exp: number;
 }
-/** Entry from `get_client_abilities_jwt_public_keys()`. */
 export interface IClientAbilitiesJwtPublicKeyEntry {
     kid: string;
     jwk: Record<string, unknown>;
 }
 export declare const CLIENT_ABILITIES_JWT_AUDIENCE = "scout-client";
-/** Typical edge `CLIENT_ABILITIES_TOKEN_TTL_SEC` (scheduling uses JWT `exp` from mint). */
 export declare const CLIENT_ABILITIES_TOKEN_TTL_SEC = 3600;
-/** UI-only gate; RLS remains authoritative for data access. */
-export declare function can_herd_ability(mint: IClientAbilitiesTokenMint | null | undefined, herd_id: number, ability: string): boolean;
+export declare function can_herd_ability(mint: IClientAbilitiesTokenMint | null | undefined, herd_id: number, ability: string, require_valid_expiry?: boolean): boolean;

package/dist/types/client_abilities_token.js

@@ -1,11 +1,13 @@
 export const CLIENT_ABILITIES_JWT_AUDIENCE = "scout-client";
-/** Typical edge `CLIENT_ABILITIES_TOKEN_TTL_SEC` (scheduling uses JWT `exp` from mint). */
 export const CLIENT_ABILITIES_TOKEN_TTL_SEC = 3600;
-/** UI-only gate; RLS remains authoritative for data access. */
-export function can_herd_ability(mint, herd_id, ability) {
+export function can_herd_ability(mint, herd_id, ability, require_valid_expiry = true) {
     if (!mint?.token) {
         return false;
     }
+    if (require_valid_expiry &&
+        mint.exp <= Math.floor(Date.now() / 1000)) {
+        return false;
+    }
     if (mint.platform_superadmin) {
         return true;
     }

package/dist/types/jwt_mint.d.ts

@@ -0,0 +1,10 @@
+export declare enum EnumJwtMintStatus {
+    IDLE = "idle",
+    LOADING = "loading",
+    REFRESHING = "refreshing",
+    READY = "ready",
+    ERROR = "error"
+}
+export declare function derive_jwt_mint_status(enabled: boolean, mint: {
+    token: string;
+} | null | undefined, inFlight: boolean, error: string | null): EnumJwtMintStatus;

package/dist/types/jwt_mint.js

@@ -0,0 +1,26 @@
+export var EnumJwtMintStatus;
+(function (EnumJwtMintStatus) {
+    EnumJwtMintStatus["IDLE"] = "idle";
+    EnumJwtMintStatus["LOADING"] = "loading";
+    EnumJwtMintStatus["REFRESHING"] = "refreshing";
+    EnumJwtMintStatus["READY"] = "ready";
+    EnumJwtMintStatus["ERROR"] = "error";
+})(EnumJwtMintStatus || (EnumJwtMintStatus = {}));
+export function derive_jwt_mint_status(enabled, mint, inFlight, error) {
+    if (!enabled) {
+        return EnumJwtMintStatus.IDLE;
+    }
+    if (inFlight && !mint?.token) {
+        return EnumJwtMintStatus.LOADING;
+    }
+    if (inFlight && mint?.token) {
+        return EnumJwtMintStatus.REFRESHING;
+    }
+    if (error) {
+        return EnumJwtMintStatus.ERROR;
+    }
+    if (mint?.token) {
+        return EnumJwtMintStatus.READY;
+    }
+    return EnumJwtMintStatus.LOADING;
+}

package/dist/types/pubsub_token.d.ts

@@ -5,3 +5,8 @@ export interface IPubsubTokenMint {
     iat: number;
     exp: number;
 }
+export interface IPubsubJwtPublicKeyEntry {
+    kid: string;
+    jwk: Record<string, unknown>;
+}
+export declare const PUBSUB_TOKEN_TTL_SEC = 3600;

package/dist/types/pubsub_token.js

@@ -1 +1 @@
-export {};
+export const PUBSUB_TOKEN_TTL_SEC = 3600;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adventurelabs/scout-core",
-  "version": "1.4.75",
+  "version": "1.4.76",
   "description": "Core utilities and helpers for Adventure Labs Scout applications",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",