Client abilities token helpers

See Client abilities tokens (database) for claims, keys, and access rules.

mint_client_abilities_token

• Client: Supabase client with user session (not device api_key).
• Calls: Edge function mint-client-abilities-token.
• Returns: { status, msg, data: IClientAbilitiesTokenMint } — token, herds, platform_superadmin, iat, exp.

get_client_abilities_jwt_public_keys / verify_client_abilities_token

Browser helpers for pubkey lookup and jose verification. Verification checks the signature; claims come from the mint response.

Server usage

The matching server helper creates the request-scoped Supabase client:

import { mint_client_abilities_token } from "@adventurelabs/scout-core/server";

const response = await mint_client_abilities_token();

can_herd_ability

UI-only helper (RLS still enforces data access). Optional fourth argument require_valid_expiry (default true) denies when JWT exp is in the past — set false for offline checks against a cached mint.

import {
  can_herd_ability,
  useClientAbilitiesMint,
} from "@adventurelabs/scout-core/client";

const { mint } = useClientAbilitiesMint();
if (can_herd_ability(mint, herdId, "herd_invitations.write")) {
  // show invite UI
}
if (can_herd_ability(mint, herdId, "realtime_streams.read", false)) {
  // offline: skip exp check
}

ScoutRefreshProvider

ScoutRefreshProvider uses one React context for the Supabase client and the verified abilities mint. Optional abilityParams:

Re-mint scheduling uses JWT exp from the mint when present, otherwise iat + clientAbilitiesTokenTtlSec. When a suspended tab becomes visible, Scout immediately rechecks mints that are near expiry.

<ScoutRefreshProvider
  abilityParams={{
    mintClientAbilitiesToken: true,
    clientAbilitiesTokenTtlSec: 3600,
  }}
>
  <Child />
</ScoutRefreshProvider>

Read minted abilities state with useClientAbilitiesMint() — { mint, status, error, refreshMint }. status is EnumJwtMintStatus: loading (no valid online mint yet), refreshing (valid cached mint + background re-mint), ready, error, idle. Expired cached mints remain available for explicitly expiry-agnostic offline gates, but are not reported as ready while online.

Herd roles helpers

Server role helpers use canonical names such as get_herd_roles, get_herd_roles_with_abilities, and set_herd_role_abilities.