@flowselections/core
v1.0.37
Published
Fundament-module: authenticatie, shell-layout (sidebar/header), instellingen en de gedeelde UI-componenten. Elke module heeft core als `peerDependency`; de shell bepaalt welke core-versie draait.
Readme
@flowselections/core
Fundament-module: authenticatie, shell-layout (sidebar/header), instellingen en de
gedeelde UI-componenten. Elke module heeft core als peerDependency; de shell
bepaalt welke core-versie draait.
Gebruik 1.0.23 t/m 1.0.25 niet
Core 1.0.23 tot en met 1.0.25 breken de clientbuild van shells ("Readable"/"AsyncLocalStorage" is not exported by "__vite-browser-external"): servercode van @tanstack/start-server-core (node:async_hooks, node:stream) lekte naar de clientbundel. In 1.0.23 liep dat via de handoverpagina, in 1.0.24 en 1.0.25 via ./server, dat @tanstack/react-start/server statisch importeerde — elke shell met een module die ./server her-exporteert (zoals de admin-add-on) faalde. Gebruik 1.0.26 of hoger.
Vanaf 1.0.24 wisselt HandoverPage de code in via een server-route in de shell. Het dashboard genereert daarvoor src/routes/api/public/auth/handover.ts:
import { createFileRoute } from "@tanstack/react-router";
import { handoverExchangeHandler } from "@flowselections/core/server";
export const Route = createFileRoute("/api/public/auth/handover")({
server: { handlers: { POST: handoverExchangeHandler() } },
});Ander pad? Geef exchangePath mee aan HandoverPage of handoverRoute. Zonder dit bestand mislukt alleen de handover (neutrale foutmelding); /login blijft werken.
build:pkg controleert met scripts/check-client-graph.mjs dat de hoofdbarrel, ./routes én ./server geen letterlijke serverimport bevatten (statisch of import("…")). npm run verify:consumer bouwt twee minimale consumer-apps tegen het gepakte pakket: één zonder en één met ./server in de clientgraaf (het geval van de admin-add-on).
Modulecontract
interface FlowModule {
id: string; // pakket-id (npm), NIET de externe sleutel
name: string;
version: string;
nav: NavItem;
settingsCards: SettingsCard[];
registryKey?: string; // optionele expliciete externe sleutel
}De modulesleutel
Core matcht extern (module_registry, rechten) altijd op moduleKey(mod) en
nooit op mod.id — id is een pakket-id, terwijl de registry route-slugs bevat.
moduleKey():
registryKeyals die is opgegeven;- anders het eerste padsegment van
nav.href; - afsluitende underscores worden gestript.
Regel 3 is een expliciete beslissing: een afsluitende underscore in een routepad
(/voorraad_/detail) is een TanStack un-nesting-conventie en geen betekenisvol
segment. Zonder strippen krijgt dezelfde module twee sleutels (voorraad en
voorraad_) en verdwijnt hij half uit de zijbalk. Er is gekozen voor strippen in
plaats van registryKey verplicht maken, omdat dat laatste bestaande modules
stil zou breken. Wil je afwijken, zet dan registryKey expliciet.
Core kent geen enkele module- of domeinnaam; de regel is volledig generiek.
Shell-extensiepunten
Alles optioneel. Zonder provider gedraagt een shell zich exact zoals voorheen: default-allow, code-volgorde.
// src/routes/_authenticated.tsx
import { ShellExtensionsProvider, ModuleGuardSlot, Sidebar, useModulePermissionTransform } from "@flowselections/core";
import { useModuleOrderTransform } from "@flowselections/sidebar-ordening-installatie-techniek";
<ShellExtensionsProvider
useModuleList={[useModulePermissionTransform, useModuleOrderTransform]}
>
<Sidebar auth={auth} modules={modules} />
<ModuleGuardSlot>
<Outlet />
</ModuleGuardSlot>
</ShellExtensionsProvider>Pipeline-volgorde is de array-volgorde: eerst rechten filteren, dan sorteren. Meegegeven hooks moeten stabiele referenties zijn (module-scope functies, geen inline lambdas), zodat de hook-volgorde tussen renders nooit verandert.
Elke transform ontvangt (modules, { allModules }): modules is de actuele
pipeline-uitkomst en allModules is altijd de ongefilterde shell-lijst. Een
transform moet puur op basis van deze input werken en mag geen side-effects
hebben: geen synchronisatie, schrijfacties of andere mutaties buiten zijn
retourwaarde.
Bij laden, een ontbrekende tabel/RPC of een fout in een transform komt de lijst ongewijzigd terug. Een lege zijbalk is nooit een geldige uitkomst.
Parent/child-gedrag in de zijbalk
- Groep waarvan alle kinderen wegvallen → groep wordt niet gerenderd.
- Parent-sleutel geweigerd maar een kind toegestaan → groep blijft staan met
alleen de toegestane kinderen.
NavItem.hrefis op een groep een uitklapknop, geen echte bestemming, dus de parent-sleutel wordt voor groepen niet gebruikt om zichtbaarheid te bepalen. - Platte items worden op hun eigen sleutel beoordeeld.
Rechten (leeskant)
useMyModulePermissions()/useModulePermission(moduleId, featureId?)— React Query op RPCmy_module_permissions(),queryKey: ["my-module-permissions"].useModulePermissionTransform()— laat zijbalkitems metnoneweg.ModuleAccessGuard— pad-gebaseerde guard (module-id uit het eerste URL-segment).requireModulePermission()— server-only, alleen via@flowselections/core/server.
Core leest of schrijft geen enkele tabel uit het rechtenschema. Alleen de twee
RPC's my_module_permissions() en effective_module_permission(). Het schema
blijft eigendom van de admin-add-on.
ModuleAccessGuard is fail-open — met opzet
ModuleAccessGuard en useModulePermission laten door bij:
- laden (eerste render, eerste login);
- een ontbrekende RPC (add-on niet geïnstalleerd op die database — PostgREST 404 / Postgres 42883);
- elke andere fout in de query;
- een module zonder rij in
module_registry(default-allow).
Dit is een bewuste keuze: zichtbaarheid is geen beveiliging, en een dichte guard zou bij elke laadfout of ontbrekende add-on de hele app onbruikbaar maken.
De echte afscherming is requireModulePermission() server-side plus RLS/policies
op de database. Lees deze guard niet als beveiligingslaag.
De permissie-query heeft retry: false: een ontbrekende RPC mag nooit een
retry-storm veroorzaken.
Supabase
De browser-client is env-gedreven en lazy (VITE_SUPABASE_URL /
VITE_SUPABASE_PUBLISHABLE_KEY, met SUPABASE_* fallback voor SSR). Er staat
geen projectref of key in de code, ook niet als fallback.
Rechten in 1.0.23
Zichtbaarheid, geen beveiliging. Alles hieronder verbergt of toont UI. De data wordt afgeschermd door RLS en serverfuncties (
requireModulePermission).
- Automatisch via
AuthenticatedLayout+requireAuth— het gegenereerde_authenticated.tsxhoeft niet te veranderen.- Zijbalk: eerst het rechtenfilter, dan extensie-transforms (ordening). Uit met
permissions={false}. Tijdens het eerste laden een skeleton; na een fout of 3 s time-out de volledige lijst (fail-open). requireAuthgeeft{ moduleAccess }terug uitbeforeLoad(context wordt niet gemuteerd). Bijnonetoont de layout "Geen toegang". Wacht max. 3 s.- Werkt zonder
QueryClientProvider(gedeelde store,useSyncExternalStore).
- Zijbalk: eerst het rechtenfilter, dan extensie-transforms (ordening). Uit met
useCan(module, feature?, level?)/<Can>— niveausnone < view < edit.NavItem.featureId(andersfeatureKey(href)); groepen zonder zichtbare kinderen verdwijnen, tenzij de module een eigen link heeft.SettingsCard.moduleId/featureId: kaarten erven het recht van hun module.- Footer:
ShellExtensionsProvider useFooterkan Instellingen verbergen; Uitloggen is nooit te verbergen. useIsSuperadmin()(claimuser_roles, terugval tabel); server:getRoleFlags(claims),isSuperadminServer(). Nooit voor moduletoegang.useShell()/useShellModules()— ruwe modulelijst +shellId.- Admin en superadmin zien altijd alles.
Gedragswijziging requireModulePermission
Vóór 1.0.23 liet deze functie alles door: de RPC werd zonder _user_id
aangeroepen, werd niet gevonden, en dat gold als "add-on ontbreekt" →
toegestaan. Sinds 1.0.23 roept hij de 3-argumentversie aan; _user_id komt
uitsluitend uit het geverifieerde token van het verzoek, moduleniveau is
_feature_id ''. Zonder geldige sessie: 401. Controleer serverfuncties die
erop leunen: ze kunnen nu echt 403 geven.
Huisstijl
Flora Select is de standaardhuisstijl. De tokens staan in
src/core/styles/brand-default.css en worden via @flowselections/core/styles.css
geladen; een latere src/brand.generated.css van de shell overschrijft dezelfde
variabelen. Alle statuskleuren hebben een vol en zacht paar. Inter is de
interfaceletter, Fraunces is voor login en lege toestanden en JetBrains Mono voor
codes. Logo: logoSrc-prop, anders /brand/logo-wit.svg; login gebruikt
/brand/logo.svg. Een ontbrekend bestand valt terug op het tekstlogo.
Shells laden de fontstylesheet in hun root head:
https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght,[email protected],600..800,0..100&family=Inter:wght@400;500;600&family=JetBrains+Mono:wght@400;500&display=swapSysteemroutes (@flowselections/core/routes, vanaf 1.0.23)
Shells houden per systeemroute een dun omhulsel; core levert de opties:
// src/routes/login.tsx
import { createFileRoute } from "@tanstack/react-router";
import { loginRoute } from "@flowselections/core/routes";
export const Route = createFileRoute("/login")(loginRoute({ landing: "/voorraad" }));Ook: resetPasswordRoute({ landing }) (/reset-wachtwoord), landingRoute({ landing }) (/),
handoverRoute({ landing }) (/auth/handover, ssr: false). Bij loginRoute wint een veilig ?redirect
(same-site pad) van landing, ook als je al ingelogd bent. Shells met eigen routebestanden blijven werken.
Publiceren
vite build (preview/hosting) schrijft verplicht naar dist/ en overschrijft dan het pakket. Daarom:
prepublishOnly draait build:pkg, dat dist/ eerst leegmaakt, opnieuw bouwt en met
scripts/check-pkg.mjs controleert dat dist/ precies het pakket bevat. npm publish publiceert dus nooit
een preview-build.
Shell-adres en Central-koppeling (./server)
De door het dashboard gegenereerde globale request-middleware roept per verzoek aan:
import { runShellRuntime } from "@flowselections/core/server";
await runShellRuntime(); // bestaand gedrag, geeft null terug; geen croncontrole zonder contextVereist SUPABASE_URL, SB_SERVICE_ROLE_KEY, CENTRAL_AUTH_URL, CENTRAL_AUTH_SECRET. Gooit nooit; de leessleutel wordt nooit gelogd of teruggegeven.
Centrale croncontrole (dashboardaansluiting)
Het dashboard past system-files.js, buildBody, voor het systeembestand
src/lib/shell-runtime-middleware.ts aan. Houd deze middleware als eerste:
createMiddleware({ type: "request" }).server(async ({ request, pathname, next }) => {
const { runShellRuntime } = await import("@flowselections/core/server");
const denied = await runShellRuntime({ request, pathname }); return denied ?? next();
});ensureCronKeys() synchroniseert SUPABASE_PUBLISHABLE_KEY ?? SUPABASE_ANON_KEY
(zonder omringende aanhalingstekens) via flowselections_set_anon_key.
Central-koppeling en sleutelsynchronisatie wachten één uur na succes en vijf
minuten na een mislukking, per isolate. Geen sleutels in logs of responses.
checkCronRequest(request) controleert uitsluitend exacte paden uit
flowselections_cron_paths(), met x-flowselections-cron-key tegen
flowselections_cron_secret(). Native Web Crypto verifieert de vergelijking.
Paden, sleutel en configuratie worden vijf minuten gecachet; een afwijkende
sleutel veroorzaakt één herlezing vóór de beslissing. Gelijktijdige herlezingen
delen een Promise; daarna blijven herhaalde mismatches tot de volgende cacheverversing
zonder extra RPC's, om een verzoekenstorm te voorkomen. Ontbrekende RPC's, netwerkfouten of ongeldige antwoorden laten
verzoeken door en worden begrensd gemeld; deze laag vervangt geen modulebeveiliging.
module_runtime_config heeft key/value-rijen: shell_base_url,
cron_auth_mode (compat standaard, of afdwingen) en
cron_auth_exempt_paths (komma-gescheiden extra padprefixen). In compat komt
alleen een waarschuwing; in afdwingen een 401 vóór de handler. De drie vaste
uitzonderingsprefixen blijven altijd gelden, ook bij een lege configuratie:
/api/public/print/queue-tick/api/public/hooks/logistics-shipping-note-now/api/public/cron/ping
De eigen engine-tick en verkoop_cron_post staan buiten deze centrale padenlijst.
Er worden geen requestheaders herschreven en geen modules gewijzigd.
