@easygov/react-components 0.4.6 → 0.4.7

package/README.md

@@ -74,6 +74,46 @@ and pass `--build-arg NEXT_PUBLIC_OIDC_AUTHORITY=...` (or the equivalent in
 your CI pipeline) when building the image — not only in the Deployment spec
 that runs it.
 
+### Reading the header context
+
+The header resolves the signed-in user, the selected customer account and the running process
+from core-backend and publishes them to consumers:
+
+```tsx
+import { useEasygovHeaderContext } from '@easygov/react-components';
+
+function ContactForm() {
+  const { claims } = useEasygovHeaderContext();
+  const account = claims?.customerAccount;
+
+  return (
+    <form>
+      <input defaultValue={claims?.currentUser.firstName ?? ''} />
+      <input defaultValue={account?.label ?? ''} />
+      {account?.accountType === 'ORGANIZATION' && <input defaultValue={account.uid ?? ''} />}
+    </form>
+  );
+}
+```
+
+`claims` is `null` until the first response lands and again after logout — render a fallback,
+don't assume it is present on first paint. The hook reflects the last context an `EasygovHeader`
+resolved; it never fetches on its own, and it is not cleared when the header unmounts. Claims
+track the last context that resolved successfully, so if a later refetch fails, they can still
+describe the previously selected account rather than resetting to `null`.
+
+Outside React — including `<eg-easygov-header>` — listen for the event instead:
+
+```js
+document.addEventListener('contextchange', (e) => {
+  const { contextJwt, claims } = e.detail;
+});
+```
+
+**The claims are decoded, not verified.** Use them for prefilling and rendering. Any backend
+that receives `contextJwt` must verify its signature against core-backend's published JWKS
+before trusting a claim.
+
 ## License
 
 MIT

package/dist/easygov.d.mts

@@ -306,6 +306,107 @@ type AuthStatus = 'initializing' | 'authenticated' | 'renewing' | 'signing-in' |
 declare function getAuthStatus(): AuthStatus;
 declare function requireSession(): void;
 
+type ManagementRoleType = 'SUPER_AGENT' | 'AGENT';
+/**
+ * Verification level of a customer account's identity, and — as `ServiceApp.requiredAccountStatus`
+ * — the minimum level a service demands. One type for both because the knockout rule compares
+ * them to each other.
+ */
+type AccountVerificationStatus = 'NOT_VERIFIED' | 'VERIFIED';
+/**
+ * Verification of a management-role grant. Same values as `AccountVerificationStatus` today, but
+ * a separate type deliberately: it verifies a different thing (the grant, not the identity) and
+ * the two are free to diverge on the wire.
+ */
+type ManagementRoleStatus = 'NOT_VERIFIED' | 'VERIFIED';
+type ProcessStatus = 'PRELIMINARY' | 'REQUEST_IN_PROGRESS' | 'REQUEST_COMPLETED' | 'SERVICE_PROVISION_PENDING' | 'FINISHED' | 'CANCELED';
+/**
+ * The caller's management role on the selected account: SUPER_AGENT (Kontoverwalter/in,
+ * unrestricted) or AGENT (Mitwirkende/r, restricted by per-service permissions, which this
+ * context does NOT carry).
+ * @see HeaderContextClaims for unverified-claims boundary; roleType and status must not drive authorization.
+ */
+interface ManagementRole {
+    roleType: ManagementRoleType;
+    /** Only present for SUPER_AGENT. */
+    status?: ManagementRoleStatus;
+}
+interface CustomerAccountBase {
+    id: string;
+    label: string;
+    status: AccountVerificationStatus;
+    managementRole: ManagementRole;
+}
+/**
+ * A customer account of type ORGANIZATION. Decoded from the context JWT, signature unverified: safe to render, never to authorize.
+ */
+interface OrganizationAccount extends CustomerAccountBase {
+    accountType: 'ORGANIZATION';
+    legalForm: string;
+    /** Absent while the organization has no UID register entry. */
+    uid?: string;
+}
+/**
+ * A customer account of type INDIVIDUAL. Decoded from the context JWT, signature unverified: safe to render, never to authorize.
+ */
+interface IndividualAccount extends CustomerAccountBase {
+    accountType: 'INDIVIDUAL';
+}
+/**
+ * Discriminated on `accountType` — narrow before reading organization-only fields.
+ * Decoded from the context JWT, signature unverified: safe to render, never to authorize.
+ */
+type SelectedCustomerAccount = OrganizationAccount | IndividualAccount;
+/**
+ * The selected Behördengang with its resolved ServiceApp.
+ * Decoded from the context JWT, signature unverified: safe to render, never to authorize.
+ */
+interface SelectedProcess {
+    id: string;
+    status: ProcessStatus;
+    serviceApp: {
+        id: string;
+        /** Minimum `CustomerAccount.status` the service requires (knockout). */
+        requiredAccountStatus: AccountVerificationStatus;
+        individualServicePermissionModel: boolean;
+    };
+}
+/**
+ * The authenticated user's identity and profile information.
+ * Decoded from the context JWT, signature unverified: safe to render, never to authorize.
+ */
+interface UserProfile {
+    id: string;
+    eiamIdentity: string;
+    eiamSSOsessionID: string;
+    qoA: number;
+    emailAddress?: string;
+    firstName?: string;
+    lastName?: string;
+    roles?: string[];
+}
+/**
+ * Decoded payload of `contextJwt`. The signature is NOT verified by EasygovHeader — the
+ * authenticated HTTPS fetch to core-backend is the trust boundary. Safe for prefilling forms and
+ * rendering decisions; never for authorization. A backend receiving this JWT MUST verify it
+ * against core-backend's published JWKS.
+ */
+interface HeaderContextClaims {
+    currentUser: UserProfile;
+    customerAccount?: SelectedCustomerAccount;
+    process?: SelectedProcess;
+}
+
+interface EasygovHeaderContext {
+    contextJwt: string | null;
+    /**
+     * Decoded but NOT signature-verified — see HeaderContextClaims. Null until the first
+     * context resolves and again after sign-out; a failed refetch keeps the previously resolved
+     * claims.
+     */
+    claims: HeaderContextClaims | null;
+}
+
 declare const dictionaries: {
     de: {
         readonly login: "Anmelden";
@@ -380,6 +481,21 @@ interface EasygovSession {
 }
 declare function useEasygovSession(): EasygovSession;
 declare function useEasygovAuthStatus(): AuthStatus;
+/**
+ * The header's current context: the raw `contextJwt` and its decoded claims. Reflects the last
+ * context an EasygovHeader resolved — the hook never fetches on its own, returns empty values
+ * until that first resolution, and is NOT cleared when the header unmounts.
+ *
+ * Claims track the last context that resolved successfully: if a *re*fetch fails (non-2xx,
+ * network error), the previous claims stay in place rather than resetting to null, so they can
+ * still describe a previously selected account after the URL has moved on. Only sign-out (or a
+ * failed *first* fetch) leaves `claims` at `null`.
+ *
+ * IMPORTANT — trust boundary: `claims` is decoded, NOT signature-verified. Use it to prefill
+ * forms and drive rendering; never to authorize. A backend receiving `contextJwt` MUST verify it
+ * against core-backend's published JWKS.
+ */
+declare function useEasygovHeaderContext(): EasygovHeaderContext;
 interface EasygovHeaderProps {
     readonly locale?: Locale;
     readonly onLanguageChange?: (locale: Locale) => void;
@@ -387,7 +503,16 @@ interface EasygovHeaderProps {
     /**
      * Called whenever a fresh `contextJwt` is obtained from core-backend's
      * `header-context` endpoint (mirrored by the `contextchange` CustomEvent
-     * dispatched on the header element).
+     * dispatched on the header element), together with its decoded `claims`.
+     *
+     * Both are always present when this fires: a payload that fails to decode never produces a
+     * `contextJwt`, so a decode failure suppresses the call rather than delivering null claims.
+     *
+     * This is the push surface — the only one a `<eg-easygov-header>` consumer has, since function
+     * props cannot cross the custom-element boundary. React consumers can read the same pair
+     * reactively with `useEasygovHeaderContext()`, which re-renders them when the context changes;
+     * there `claims` IS nullable, because the store is empty before the first context resolves and
+     * again after sign-out.
      *
      * IMPORTANT — trust boundary: this JWT's signature is NOT verified by
      * EasygovHeader. The authenticated HTTPS fetch to core-backend is the
@@ -396,7 +521,7 @@ interface EasygovHeaderProps {
      * against core-backend's published JWKS before trusting any claim
      * decoded from it.
      */
-    readonly onContextChange?: (contextJwt: string) => void;
+    readonly onContextChange?: (contextJwt: string, claims: HeaderContextClaims) => void;
     readonly onLogout?: () => void;
 }
 declare function EasygovHeader({ locale: localeProp, onLanguageChange, onNavigate, onContextChange, onLogout, }: EasygovHeaderProps): React__default.JSX.Element;
@@ -413,27 +538,4 @@ interface RequireCustomerAccountProps {
 }
 declare function RequireCustomerAccount({ children, onNavigate, }: RequireCustomerAccountProps): React__default.JSX.Element;
 
-interface UserProfile {
-    id: string;
-    emailAddress?: string | null;
-    firstName?: string | null;
-    lastName?: string | null;
-    language: 'DE' | 'FR' | 'IT' | 'EN';
-    eiamSSOsessionID: string;
-    roles?: string[];
-}
-interface SelectedCustomerAccount {
-    id: string;
-    label: string;
-}
-/**
- * Decoded (not verified — see useHeaderContext) payload of `contextJwt`. Mirrors
- * core-backend's CoreContext claims plus the standard iss/iat/exp claims, which
- * EasygovHeader itself does not read.
- */
-interface HeaderContextClaims {
-    currentUser: UserProfile;
-    customerAccount?: SelectedCustomerAccount;
-}
-
-export { type AuthStatus, BrandBase, BrandEasygov, BrandFacebook, BrandKdk, BrandLinkedin, type BrandProps, BrandSeg, BrandSgv, BrandSsv, BrandSwiss, BrandXing, BrandYoutube, Button, type ButtonProps, type DesktopSpan, Dropdown, DropdownChip, DropdownChipsOverflow, type DropdownChipsOverflowProps, DropdownChipsTrigger, type DropdownChipsTriggerProps, DropdownCollection, DropdownEmpty, DropdownGroup, DropdownGroupLabel, DropdownHelperText, type DropdownHelperTextProps, DropdownInput, DropdownItem, type DropdownItemProps, DropdownItemText, DropdownLabel, type DropdownLabelProps, DropdownList, DropdownPopup, type DropdownPopupProps, DropdownSeparator, DropdownToggle, DropdownTrigger, type DropdownTriggerProps, DropdownValue, EasygovFooter, EasygovHeader, type EasygovHeaderProps, type EasygovSession, Grid, GridItem, type GridItemProps, type GridProps, type HeaderContextClaims, type UserProfile as HeaderContextUserProfile, Heading, type HeadingProps, Input, type InputProps, type Locale, type MobileSpan, NavigationMenu, NavigationMenuAnchor, type NavigationMenuAnchorProps, NavigationMenuContent, type NavigationMenuContentProps, NavigationMenuItem, type NavigationMenuItemProps, NavigationMenuLink, type NavigationMenuLinkProps, NavigationMenuList, type NavigationMenuListProps, type NavigationMenuProps, NavigationMenuTrigger, type NavigationMenuTriggerProps, RequireCustomerAccount, type RequireCustomerAccountProps, RequireSession, type RequireSessionProps, Select, SelectContent, type SelectContentProps, SelectGroup, SelectGroupLabel, type SelectGroupLabelProps, SelectHelperText, type SelectHelperTextProps, SelectItem, type SelectItemProps, SelectLabel, type SelectLabelProps, SelectSeparator, type SelectSeparatorProps, SelectTrigger, type SelectTriggerProps, type SelectedCustomerAccount, type SessionUser, type TabletSpan, Text, TextLink, type TextLinkProps, type TextProps, buttonVariants, getAuthStatus, headingVariants, requireSession, textLinkVariants, textVariants, useEasygovAuthStatus, useEasygovSession, useRequireCustomerAccount };
+export { type AuthStatus, BrandBase, BrandEasygov, BrandFacebook, BrandKdk, BrandLinkedin, type BrandProps, BrandSeg, BrandSgv, BrandSsv, BrandSwiss, BrandXing, BrandYoutube, Button, type ButtonProps, type DesktopSpan, Dropdown, DropdownChip, DropdownChipsOverflow, type DropdownChipsOverflowProps, DropdownChipsTrigger, type DropdownChipsTriggerProps, DropdownCollection, DropdownEmpty, DropdownGroup, DropdownGroupLabel, DropdownHelperText, type DropdownHelperTextProps, DropdownInput, DropdownItem, type DropdownItemProps, DropdownItemText, DropdownLabel, type DropdownLabelProps, DropdownList, DropdownPopup, type DropdownPopupProps, DropdownSeparator, DropdownToggle, DropdownTrigger, type DropdownTriggerProps, DropdownValue, EasygovFooter, EasygovHeader, type EasygovHeaderContext, type EasygovHeaderProps, type EasygovSession, Grid, GridItem, type GridItemProps, type GridProps, type AccountVerificationStatus as HeaderContextAccountVerificationStatus, type HeaderContextClaims, type IndividualAccount as HeaderContextIndividualAccount, type ManagementRole as HeaderContextManagementRole, type ManagementRoleStatus as HeaderContextManagementRoleStatus, type ManagementRoleType as HeaderContextManagementRoleType, type OrganizationAccount as HeaderContextOrganizationAccount, type ProcessStatus as HeaderContextProcessStatus, type UserProfile as HeaderContextUserProfile, Heading, type HeadingProps, Input, type InputProps, type Locale, type MobileSpan, NavigationMenu, NavigationMenuAnchor, type NavigationMenuAnchorProps, NavigationMenuContent, type NavigationMenuContentProps, NavigationMenuItem, type NavigationMenuItemProps, NavigationMenuLink, type NavigationMenuLinkProps, NavigationMenuList, type NavigationMenuListProps, type NavigationMenuProps, NavigationMenuTrigger, type NavigationMenuTriggerProps, RequireCustomerAccount, type RequireCustomerAccountProps, RequireSession, type RequireSessionProps, Select, SelectContent, type SelectContentProps, SelectGroup, SelectGroupLabel, type SelectGroupLabelProps, SelectHelperText, type SelectHelperTextProps, SelectItem, type SelectItemProps, SelectLabel, type SelectLabelProps, SelectSeparator, type SelectSeparatorProps, SelectTrigger, type SelectTriggerProps, type SelectedCustomerAccount, type SelectedProcess, type SessionUser, type TabletSpan, Text, TextLink, type TextLinkProps, type TextProps, buttonVariants, getAuthStatus, headingVariants, requireSession, textLinkVariants, textVariants, useEasygovAuthStatus, useEasygovHeaderContext, useEasygovSession, useRequireCustomerAccount };