@digimuza/system-core 0.0.0-stage → 0.2.0-rc.1

package/INTEGRATION.md

@@ -0,0 +1,255 @@
+# Integrating `@digimuza/system-core`
+
+`README.md` is the product contract. This guide shows how to wire the package
+into one tenant's Next.js + Convex application.
+
+## Install
+
+```bash
+npm install @digimuza/system-core convex zod        # + next, react for the Next.js entries
+```
+
+Pin the version per tenant app (`"@digimuza/system-core": "0.1.0"`, or `~0.1.0`) and upgrade deliberately.
+
+## Entry points
+
+| Import | Runtime | Purpose |
+| - | - | - |
+| `@digimuza/system-core/config` | Server only | `SystemConfig.load()` / `register(schema)`, Infisical source. Browser builds resolve to a stub that throws. |
+| `@digimuza/system-core/modules` | Any | `defineModule()`, manifest types, `PermissionOf<>`. |
+| `@digimuza/system-core/convex` | Convex | `systemTables`, `defineConvexSystem()`, `requirePermission`, all core services. |
+| `@digimuza/system-core/next` | Next.js server | `createSystemServerClient()` (session token, tracing, typed errors), `createAgentClient()`. |
+| `@digimuza/system-core/react` | Client components | `<SystemProvider>`, `useCan`, `useVisibleModules`, `useCurrentUser`, `useFeatureFlag`, `useRoleView`, `<Can>`. |
+| `@digimuza/system-core/finance` | Convex | The finance business module: `finance` manifest, `financeTables`, `defineFinance(system)` functions, `FinancePermissions`, `InvoiceView`. |
+| `@digimuza/system-core` | Any | `SystemError`, redaction, logger, tracer, shared types. |
+| `@digimuza/system-core/testing` | Tests | `MemoryStore` (same semantics as Convex, serializable transactions). |
+
+These seven subpaths, listed in `package.json#exports`, are the whole public surface. Deep imports
+(`@digimuza/system-core/dist/...`) are not supported. Server and browser entries stay separate:
+`.`, `./modules` and `./react` never import `./config`, `./convex` or `./next`, and never read
+`process.env`. `npm run check:pack` enforces this in CI. Removing or renaming an entry or export,
+or moving code across the server/browser line, is a breaking change (a major bump; while on 0.x,
+a minor bump with a changelog note).
+
+## 1. Declare business modules
+
+```ts
+// modules/finance.ts
+import { defineModule } from "@digimuza/system-core/modules"
+
+export const finance = defineModule({
+  id: "finance",
+  kind: "business",
+  description: "Sąskaitų peržiūra ir tvirtinimas",
+  permissions: [
+    { id: "finance:invoice:read", name: "Skaityti", description: "Peržiūrėti sąskaitą" },
+    { id: "finance:invoice:approve", name: "Tvirtinti", description: "Patvirtinti sąskaitą" },
+  ],
+  initialSubroles: [
+    { id: "finance:reader", name: "Skaitytojas", description: "Gali peržiūrėti sąskaitas", permissions: ["finance:invoice:read"] },
+  ],
+  featureFlags: [{ id: "finance:bulk-approve", description: "Bulk approval", default: false }],
+})
+```
+
+`defineModule` validates when it is imported: ID formats, permission prefixes,
+and subroles that reference only their own module's permissions. When the
+modules are composed, ID collisions and unknown dependencies are rejected.
+
+## 2. Convex
+
+```ts
+// convex/schema.ts
+import { defineSchema, defineTable } from "convex/server"
+import { systemTables } from "@digimuza/system-core/convex"
+export default defineSchema({ ...systemTables, invoices: defineTable({ /* … */ }) })
+```
+
+```ts
+// convex/system.ts  (the module path must match `functionsModule`, default "system")
+import { defineConvexSystem } from "@digimuza/system-core/convex"
+import { finance } from "../modules/finance"
+
+export const system = defineConvexSystem({
+  modules: [finance],
+  // superUserEmails defaults to process.env.SUPER_USER_EMAILS (set on the Convex deployment)
+  inviteDelivery: { deliver: async ({ email, url, operationId }) => { /* send email */ } },
+  inviteUrl: (token) => `${process.env.APP_URL}/invite?token=${token}`,
+})
+
+export const {
+  session, completeSignIn, registerSystem,
+  listModules, setModuleEnabled, listPermissions, explainDecision,
+  getUser, findUserByIdentity, listUsers, suspendUser, activateUser, getMyProfile, updateMyProfile,
+  listRoles, getRole, listSubroles, createRole, copyRole, updateRole, archiveRole,
+  createSubrole, copySubrole, previewSubroleChange, updateSubrole, archiveSubrole,
+  assignRoles, revokeRole, setDelegationScope,
+  listInvites, getInvite, revokeInvite, createInvite, resendInvite, _createInvite, _resendInvite, _recordInviteDelivery,
+  listMyApiKeys, setApiKeyRoles, revokeApiKey, createApiKey, rotateApiKey, _createApiKey, _rotateApiKey,
+  listFeatureFlags, setFeatureFlag, resetFeatureFlag, listAudit,
+  roleViewStatus, startRoleView, stopRoleView,
+} = system.functions
+```
+
+`system.requirePermission(ctx, …)` and `system.context(ctx)` take the app's own
+generated `QueryCtx` / `MutationCtx` directly; no cast is needed.
+
+The default identity mapping reads `email`, and `emailVerified` or the raw
+`email_verified` claim, so custom JWT providers (WorkOS AuthKit with a JWT
+template, most OIDC setups) work without `identityFromJwt`. Pass
+`identityFromJwt` only to change the provider name or claims.
+
+### Business modules shipped in the package
+
+```ts
+// convex/schema.ts
+import { systemTables } from "@digimuza/system-core/convex"
+import { financeTables } from "@digimuza/system-core/finance"
+export default defineSchema({ ...systemTables, ...financeTables })
+
+// convex/system.ts
+import { finance } from "@digimuza/system-core/finance"
+export const system = defineConvexSystem({ modules: [finance] })
+
+// convex/finance.ts
+import { defineFinance } from "@digimuza/system-core/finance"
+import { system } from "./system"
+export const { listInvoices, createInvoice, approveInvoice, bulkApproveInvoices } = defineFinance(system)
+```
+
+Each function guards itself (permission, module enabled, role view), checks the
+object (existence, state transition), writes, and records an audit event in one
+transaction. The UI stays in the app.
+
+### View as role (Super)
+
+A real Super (verified email in `SUPER_USER_EMAILS`) can preview the system as
+a holder of one role: `startRoleView({ roleId })`, `stopRoleView()`,
+`roleViewStatus()`. While a preview is active, every decision treats the Super
+as that role: business permissions, module state (disabled modules stay off),
+Super-only actions (`setModuleEnabled`, …), the core's admin functions,
+delegation and invites. `session` returns `actor.isSuper: false`, the role's
+permissions, `canViewAs: true` and `roleView: { roleId, roleName }`. The
+Super's own API keys keep the owner's real Super status, so a preview never
+breaks running agents. Starting and stopping are audited
+(`super.role_view.start` / `.stop`); an archived role ends the preview.
+
+Business functions guard themselves on the server, in the same transaction as
+the change:
+
+```ts
+// convex/invoices.ts
+import { mutation } from "./_generated/server"
+import { v } from "convex/values"
+import { recordAudit } from "@digimuza/system-core/convex"
+import { system } from "./system"
+
+export const approve = mutation({
+  args: { invoiceId: v.id("invoices"), apiKey: v.optional(v.string()) },
+  handler: async (ctx, args) => {
+    const { sys, actor } = await system.requirePermission(ctx, "finance:invoice:approve", { apiKey: args.apiKey })
+    // Object-level checks (ownership, allowed state transition) go here.
+    await ctx.db.patch("invoices", args.invoiceId, { approved: true })
+    await recordAudit(sys, actor, { action: "finance.invoice.approve", targetType: "invoice", targetId: args.invoiceId })
+    return { operationId: sys.operationId }
+  },
+})
+```
+
+Background jobs store `toActorRef(actor)` and call `authorizeJob(sys, ref, permission)`
+when they run. A `null` result means the job must do nothing. External side
+effects use `claimOperation` and `completeOperation` for replay protection.
+
+## 3. Deployment (Coolify)
+
+1. Pin the app version and the package version.
+2. Coolify provides `INFISCAL_BASE_URL`, `INFISCAL_CLIENT_ID`, `INFISCAL_SECRET`,
+   `INFISCAL_PATH`, `INFISCAL_ENV`, `INFISCAL_PROJECT_ID` and `SUPER_USER_EMAILS`.
+3. `npx convex deploy`, then `npx convex run system:registerSystem`. Running it
+   again is safe. Conflicts abort the whole registration, so a partial catalog
+   is never activated.
+4. On the first sign-in of a verified email from `SUPER_USER_EMAILS`, the
+   Super account is created. Everyone else needs an invite.
+
+## 4. Next.js server
+
+```ts
+import SystemConfig from "@digimuza/system-core/config"
+import { createSystemServerClient } from "@digimuza/system-core/next"
+import { z } from "zod"
+
+await SystemConfig.load()
+const env = SystemConfig.register(z.object({ APP_URL: z.string().url() }), { moduleId: "web" })
+
+const client = createSystemServerClient({ getToken: () => getConvexToken(), headers: await headers() })
+const me = await client.query(api.system.session, { operationId: client.operationId })
+```
+
+Agents call system-aware functions with `createAgentClient({ url, apiKey })`.
+
+## 5. Client components
+
+```tsx
+"use client"
+import { SystemProvider, Can, useVisibleModules } from "@digimuza/system-core/react"
+
+<SystemProvider session={api.system.session}>
+  <Can permission="finance:invoice:approve"><ApproveButton /></Can>
+</SystemProvider>
+```
+
+These values only decide what the UI shows. Convex re-checks every call. The
+subscription is live, so the UI updates when a permission is revoked.
+
+## Errors
+
+Public functions throw `ConvexError({ code, message, operationId, fields? })`
+with `code` ∈ `UNAUTHENTICATED | FORBIDDEN | NOT_FOUND | VALIDATION | CONFLICT | UNAVAILABLE`.
+`toSystemError(e)` normalizes the error on the client. The exact denial reason
+is only logged and is available through `explainDecision` (diagnostics,
+`permissions:decision:explain`). Records the actor may not see return
+`NOT_FOUND`, the same as records that don't exist.
+
+## Development
+
+```bash
+npm test             # vitest: acceptance scenarios, Convex end-to-end (convex-test), units
+npm run typecheck    # TypeScript 7
+npm run build        # tsc → dist/
+npm run check:pack   # pack, install into a clean consumer, import + type-check every entry, browser/server separation
+npm run lint         # biome lint
+```
+
+## Releasing
+
+Branch-based release cycle (same for every digimuza project). The version comes from the release branch name.
+
+```
+feature/DIG-123-x ──PR──▶ main ──cut──▶ release/X.Y.Z ──PR (merge commit)──▶ production
+                          (dev)          npm X.Y.Z-rc.N  @next                 npm X.Y.Z  @latest
+```
+
+| Branch | npm | Who consumes it |
+| - | - | - |
+| `main` | nothing | development |
+| `release/X.Y.Z`, `hotfix/X.Y.Z` | `X.Y.Z-rc.N` under dist-tag `next`, one rc per push | staging: `npm install @digimuza/system-core@next` (or pin `X.Y.Z-rc.N`) |
+| `production` | `X.Y.Z` under dist-tag `latest` | production tenant apps |
+
+1. **Cut**: `npm run release:cut -- 0.2.0` creates `release/0.2.0` from `origin/main`, bumps `package.json` and pushes.
+   After the cut only fixes go into the release branch.
+2. **Stage**: every push to `release/0.2.0` runs `.github/workflows/release.yml` → verify → publish
+   `0.2.0-rc.1`, `-rc.2`, … with tag `next`. Linear issues (`DIG-n` in commit messages) move to **In Staging**
+   and onto project milestone `v0.2.0`.
+3. **Release**: open a PR `release/0.2.0 → production` and merge it **with a merge commit** (not squash).
+   CI checks the source branch and version. The push to `production` publishes `0.2.0` as `latest`,
+   tags `v0.2.0`, creates a GitHub Release, moves the issues to **Done**, posts a Linear project update
+   and opens and auto-merges a PR `production → main` so fixes reach `main`.
+4. **Hotfix**: `hotfix/0.2.1` from `production`, bump `package.json`, push (publishes `0.2.1-rc.N`), then PR to `production`.
+
+Guards: the release branch version must match `package.json`, a version already on npm is never republished,
+and `production` refuses to publish `X.Y.Z` unless an `X.Y.Z-rc.N` was staged first. A manual run
+(Actions → Release → Run workflow, `dry_run` on) does everything with `npm publish --dry-run` and skips tags,
+releases and Linear.
+
+Publishing uses npm trusted publishing (OIDC) bound to `digimuza/system-core` + `release.yml`, so no npm token is stored.
+Linear updates need the `LINEAR_API_KEY` repo secret (sourced from Infisical); without it they are skipped.

package/README.md

@@ -1,3 +1,165 @@
-# Temporary Holding Version
+Vienai įmonei diegiama atskira Next.js ir Convex aplikacija. `@digimuza/system-core` yra bendras NPM paketas. Kliento aplikacija registruoja verslo modulius, o branduolys tvarko konfigūraciją, tapatybes, teises ir diagnostiką. `finance` ir `powerbi` yra modulio sutarties pavyzdžiai.
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Moduliai ir jų paskirtis
+
+`config` įkelia ir pagal Zod schemas validuoja serverio konfigūraciją. `auth` susieja patikimo tiekėjo tapatybę su lokaliu vartotoju. `users` saugo stabilų ID, tapatybės sąsają, patvirtinto el. pašto būseną ir paskyros būseną. Kliento papildomi įrašai siejami per `userId`. `profile` leidžia aktyviam vartotojui tvarkyti savo profilio pateikimo laukus. Tapatybės, el. pašto patvirtinimo, būsenos ir rolių keitimas turi atskirus procesus.
+
+`roles` valdo roles, subroles, jų sudėtį ir priskyrimus. `permissions` registruoja kode aprašytus veiksmus ir priima prieigos sprendimus. `invites` valdo vienkartinius, atšaukiamus kvietimus su galiojimo terminu ir numatomomis rolėmis. `api-keys` išduoda, rotuoja ir atšaukia agentų raktus. Modulių registras saugo modulių tipą, verslo modulių būseną ir registracijos versiją.
+
+`logging` registruoja struktūruotus įvykius. `tracing` sieja Next.js, Convex ir išorinių operacijų žingsnius pagal operacijos ID. `feature-flags` valdo funkcijų prieinamumą jau įjungtuose moduliuose. Funkcijos žyma negali suteikti teisės. Audito įrašai fiksuoja saugumui svarbių pakeitimų autorių, taikinį, laiką, rezultatą ir pakeistas sąsajas. Diagnostikoje maskuojamos paslaptys, sesijų duomenys ir raktai, taip pat ir `Super` rodinyje.
+
+# Viešasis paketas ir jo naudotojai
+
+Pirmoji versija platinama vienu versijuojamu NPM paketu su atskirais importo keliais. Kiekvienas klientas savo aplikacijoje fiksuoja paketo versiją ir turi atskirą Convex diegimą. Aplikacija pasirenka įtraukiamus verslo modulius, jų ekranus, prisijungimo ir kvietimų pristatymo tiekėjus. Paketas apibrėžia bendras serverio operacijas, duomenų schemas, TypeScript tipus ir sąsajas šioms integracijoms.
+
+| Kas integruoja | Siūlomas importo kelias | Ką gauna |
+| - | - | - |
+| Serverio paleidimas | `@digimuza/system-core/config` | `SystemConfig.load()` ir sinchroninį `register(schema)` po įkėlimo |
+| Modulio autorius | `@digimuza/system-core/modules` | `defineModule()`, manifesto tipus ir validaciją |
+| Convex aplikacija | `@digimuza/system-core/convex` | Sistemos registraciją, užklausų ir mutacijų pagalbines funkcijas, teisių patikrą |
+| Next.js serveris | `@digimuza/system-core/next` | Autentifikuotos sesijos perdavimą ir tipizuotą kreipimąsi į Convex |
+| Next.js kliento komponentai | `@digimuza/system-core/react` | Dabartinio vartotojo, matomų modulių ir leidžiamų veiksmų duomenis kliento kuriamam UI |
+
+Šie pavadinimai yra projektuojama v1 sutartis. Paleidimo konfigūracija, Infisical klientas ir paslaptys pasiekiami tik serverio importuose. Kliento komponentų importavimas neturi reikalauti serverio aplinkos kintamųjų.
+
+# Funkcijų katalogas
+
+| Modulis | V1 operacijos | Tikrinamas rezultatas |
+| - | - | - |
+| `config` | Įkelti vieną konfigūracijos versiją, validuoti kelių modulių schemas, pateikti nuasmenintą būseną | Lygiagretūs `load()` naudoja tą patį įkėlimą. `register()` iki įkėlimo grąžina aiškią klaidą. Būsena nerodo reikšmių. |
+| `modules` | Registruoti manifestus, išvardyti įdiegtus modulius, gauti efektyvią būseną, įjungti ar išjungti verslo modulį | Pakartotinis registravimas išsaugo kliento pasirinkimą. Sisteminio modulio išjungimo užklausa atmetama. |
+| `auth` | Pradėti ir užbaigti prisijungimą per pasirinktą tiekėją, nustatyti veikėją, atsijungti | Pasibaigusi sesija neleidžia atlikti apsaugoto veiksmo. Neatpažintai paskyrai reikalingas galiojantis kvietimas arba pradinis patvirtintas `Super` prisijungimas. |
+| `users` | Peržiūrėti vartotoją, rasti pagal tapatybę, puslapiuoti sąrašą, sustabdyti ir aktyvuoti paskyrą | Pakartotinai gavus prisijungimo įvykį lieka vienas vartotojas. Aktyvavimas neatkuria atšauktų raktų. |
+| `profile` | Skaityti ir redaguoti savo rodomą vardą, kalbą ir laiko juostą | Įrašomi tik leidžiami laukai. Kliento profilio plėtiniai turi atskirą schemą ir prieigos taisykles. |
+| `invites` | Sukurti, pristatyti, pakartotinai išsiųsti, atšaukti, priimti, rodyti būseną | Pakartotinis siuntimas pakeičia ankstesnį žetoną. Nepavykus pristatyti galima kartoti nesukuriant naujos paskyros. |
+| `permissions` | Registruoti katalogą, išvardyti teises pagal modulį, patikrinti veiksmą, paaiškinti sprendimą įgaliotam operatoriui | UI ir serveris naudoja tą patį sprendimo modelį. Serveris apsaugo veiksmą net tiesiogiai iškvietus Convex funkciją. |
+| `roles` | Kurti, kopijuoti, redaguoti ir archyvuoti roles bei subroles, peržiūrėti ryšius, priskirti roles ir jas atšaukti | Prieš keitimą galima matyti paveiktas roles ir gavėjų skaičių. Archyvuotas objektas nebesuteikia teisių. |
+| `api-keys` | Sukurti savininko raktą su rolėmis, išvardyti jo raktus, keisti roles, rotuoti ir atšaukti | Raktų sąraše matomas identifikavimo prefiksas, galiojimas ir būsena. Paslaptis parodoma vieną kartą. |
+| `feature-flags` | Registruoti modulio žymas kode, skaityti efektyvią reikšmę, keisti instaliacijos reikšmę, grąžinti numatytąją | V1 žymos yra loginės ir galioja vienai instaliacijai. Nežinoma žyma nesuaktyvina funkcijos. Žymos reikšmė naudojama kartu su modulio ir teisės patikromis. |
+| `logging` | Rašyti struktūruotus įvykius su lygiu, modulio ID, įvykio vardu ir koreliacijos ID | Vienos užklausos klaidą galima rasti pagal ID. Tokenai ir slapti laukai pašalinami prieš siunčiant į žurnalų saugyklą. |
+| `tracing` | Pradėti operaciją, susieti jos žingsnius, perduoti kontekstą foninei užduočiai, užbaigti su rezultatu | Pagal vieną trace ID matomi Next.js, Convex ir integracijos žingsniai, jų trukmės ir klaidos vieta. |
+| `audit` | Įrašyti prieigos bei administravimo pakeitimus, leisti įgaliotam asmeniui filtruoti pagal laiką, veikėją ir objektą | Agentui išsaugomi rakto ir savininko ID. Sėkmingo saugomo pakeitimo auditas įrašomas kartu su DB pakeitimu. |
+
+# Naujo modulio sutartis
+
+Modulio autorius pateikia manifestą ir registruoja jį aplikacijos sudėtyje. Identifikatorius nekinta tarp versijų. Kiekviena teisė ir pradinė subrolė turi identifikatorių, pavadinimą ir aprašą. Žemiau pateiktas sutrumpintas siūlomo API pavyzdys.
+
+```ts
+import { defineModule } from "@digimuza/system-core/modules"
+
+export const finance = defineModule({
+  id: "finance",
+  kind: "business",
+  description: "Sąskaitų peržiūra ir tvirtinimas",
+  permissions: [
+    { id: "finance:invoice:read", name: "Skaityti", description: "Peržiūrėti sąskaitą" },
+    { id: "finance:invoice:approve", name: "Tvirtinti", description: "Patvirtinti sąskaitą" },
+  ],
+  initialSubroles: [{
+    id: "finance:reader",
+    name: "Skaitytojas",
+    description: "Gali peržiūrėti sąskaitas",
+    permissions: ["finance:invoice:read"],
+  }],
+})
+```
+
+Kiekvieno modulio dokumentacijoje privalomi paskirtis, tipas, viešos operacijos, duomenų savininkas, konfigūracijos raktai, teisės, pradinės subrolės, žymos ir bent vienas sėkmės bei atsisakymo scenarijus. Programinė priklausomybė nuo kito modulio nesuteikia jo teisių. Išimtas iš aplikacijos ar nepažįstamas modulis tampa neprieinamas net turint ankstesnį DB priskyrimą.
+
+# Administravimo ir integracijų paviršius
+
+Kliento dashboardas gali pateikti šiuos rodinius: mano profilis ir raktai, vartotojai ir kvietimai, rolės bei subrolės, modulių katalogas, funkcijų žymos, auditas ir diagnostika. Sąrašai palaiko puslapiavimą. Rolės detalė rodo subroles, jų teises ir gavėjus pagal žiūrinčiojo įgaliojimus. Modulio kortelėje rodoma konfigūruota ir konkrečiam veikėjui efektyvi būsena, kad `Super` aiškiai matytų, ką gali naudoti klientas.
+
+Autentifikacijos adapteris grąžina patikrintą tiekėjo tapatybę. Kvietimų siuntimo adapteris gauna gavėją, vienkartinę nuorodą ir pristatymo operacijos ID. Logų ir trace eksportuotojai gauna jau išvalytus įvykius. Adapterių klaidos turi aiškų rezultatą: privalomos tapatybės patikros gedimas blokuoja prieigą, laiško siuntimo gedimas palieka kartojamą pristatymą, diagnostikos eksportuotojo gedimas nekeičia jau įvykdytos verslo operacijos rezultato.
+
+Viešos funkcijos pateikia stabilius klaidų kodus autentifikacijos, teisių, duomenų validacijos, konflikto ir laikino nepasiekiamumo atvejams. Klientui grąžinamas operacijos ID. Kai pats įrašo egzistavimas yra ribota informacija, svetimas ir neegzistuojantis įrašas išorei atrodo vienodai. Tiksli atmetimo priežastis pasiekiama tik įgaliotame diagnostikos rodinyje.
+
+# Diegimo ir leidimų priėmimas
+
+Coolify diegimas turi fiksuoti aplikacijos bei paketo versijas, validuoti konfigūraciją, vykdyti suderinamas Convex migracijas, registruoti manifestus ir patikrinti abiejų vykdymo aplinkų parengtį. Projekto identifikacijai numatomas diegimo parametras `INFISCAL_PROJECT_ID`. Pakartotinas migracijos ar registracijos paleidimas išsaugo rezultatą. Nepavykęs diegimas neaktyvuoja iš dalies užregistruoto katalogo. Grįžimas prie ankstesnės kodo versijos galimas tik jei ji suderinama su aktyvia schema ir teisių katalogu.
+
+Prieš publikuojant versiją etaloninė Next.js + Convex aplikacija įdiegia supakuotą NPM artefaktą. Tikrinami deklaruoti importai ir tipai, serverio ir naršyklės paketų atskyrimas, įdiegimas į tuščią Convex, atnaujinimas iš ankstesnės palaikomos versijos ir to paties diegimo pakartojimas. Suderinamos Next.js, React, Convex ir Zod versijos nurodomos leidimo peer dependencies ir tikrinamos CI.
+
+#
+
+Priėmimo bandyme operatorius pakviečia darbuotoją, darbuotojas prisijungia ir susikuria ribotos rolės raktą. Įjungus bandomąjį verslo modulį agentas atlieka leidžiamą veiksmą. Tada pakeičiama rolė, atšaukiamas raktas ir tikrinama, ar jau suplanuotas darbas sustabdomas. Pagal tą pačią operaciją turi būti galima susieti audito įrašą ir techninę diagnostiką. Papildomai kartojamas nepavykęs kvietimo pristatymas, simuliuojamas išjungtas diagnostikos eksportuotojas ir patikrinama, kad jokioje naršyklės ar žurnalo išvestyje nėra paslapčių.
+
+# Konfigūracija ir diegimas
+
+`import SystemConfig from "@digimuza/system-core/config"` → `await SystemConfig.load()` → `const env = SystemConfig.register(schema)`. Coolify pateikia pradinius `INFISCAL_BASE_URL`, `INFISCAL_CLIENT_ID`, `INFISCAL_SECRET`, `INFISCAL_PATH` ir `INFISCAL_ENV`. Diegimo konfigūracija taip pat turi vienareikšmiškai identifikuoti Infisical projektą. Aplikacijos paslapčių šaltinis yra Infisical. Trūkstant privalomos reikšmės atitinkamas servisas nepasiekia parengties būsenos. Klaidoje pateikiamas rakto pavadinimas.
+
+Next.js ir Convex vykdymo aplinkoms konfigūracija pateikiama atskirai. Convex užklausos ir mutacijos prieigos patikrą atlieka naudodamos lokaliai prieinamą aktyvios versijos konfigūraciją. Diegimas laikomas baigtu, kai ankstesnės versijos instancijos nebeaptarnauja užklausų. Naršyklė gauna tik aiškiai viešomis paskelbtas reikšmes.
+
+# Peržiūra kaip rolė
+
+Tikras `Super` (patvirtintas el. paštas `SUPER_USER_EMAILS` sąraše) gali laikinai peržiūrėti sistemą kaip vienos rolės turėtojas. Peržiūros metu kiekvienas prieigos sprendimas taikomas kaip tai rolei: verslo teisės, modulių būsena, tik `Super` leidžiami veiksmai, administravimo funkcijos, delegavimas ir kvietimai. Sesija rodo `isSuper: false` ir rolės teises. `Super` savo API raktams lieka tikruoju `Super`. Pradžia ir pabaiga įrašomos į auditą; archyvuota rolė peržiūrą užbaigia.
+
+# Verslo moduliai pakete
+
+`@digimuza/system-core/finance` yra pirmasis pakartotinai naudojamas verslo modulis: manifestas, `financeTables`, `defineFinance(system)` funkcijos ir teisės. Aplikacija tik įtraukia lenteles į schemą ir eksportuoja funkcijas; vartotojo sąsaja lieka aplikacijoje.
+
+# Rolės ir modulio registracija
+
+Vienintelė įmonės valdomų suteikimų grandinė yra gavėjas → rolė → subrolė → teisė. Gavėjas yra vartotojas arba agento API raktas. Kiekviename lygyje leidžiama turėti kelias sąsajas. Viena subrolė priklauso vienam moduliui. Rolė gali sujungti kelių modulių subroles. Tiesioginis subrolės ar teisės suteikimas gavėjui yra neleistina operacija.
+
+Teisės raktas yra stabilus `modulis:objektas:veiksmas`. Kiekvienas modulis kode deklaruoja savo ID, tipą, paskirtį, teises ir pradinių subrolių šablonus. Diegimo registracija pagal stabilius ID sukuria trūkstamus įrašus. Esamų subrolių administratoriaus pakeitimai ir modulio būsena išsaugomi. Nauja teisė atsiranda kataloge. Jos įtraukimas į jau naudojamą subrolę turi būti sąmoningas DB pakeitimas. Pasenusi arba nežinoma teisė atmetama, identifikatoriai naujai prasmei nenaudojami. Nesuderinamos registracijos ir ID kolizijos sustabdo diegimą.
+
+Sisteminiai moduliai visada įjungti. Verslo modulis pirmą kartą registruojamas išjungtas. Jį įjungti ar išjungti gali tik `Super`. Išjungus išlieka duomenys ir priskyrimai. `Admin` yra įprasta administravimo rolė su konkrečiomis teisėmis. `Super` nustatomas pagal aktyvios paskyros patikimo autentifikacijos tiekėjo patvirtintą el. paštą ir diegimo `SUPER_USER_EMAILS` sąrašą. Sąrašas taikomas po pakartotinio diegimo. DB rolės pavadinimas šio statuso nesuteikia.
+
+# Prieigos sprendimas
+
+Serveris nustato veikėją iš sesijos arba API rakto. Neaiški tapatybė, nežinoma teisė, neveikianti paskyra ar prieigos patikros klaida užklausą atmeta. Autentifikacijos pradžia ir kvietimo priėmimas turi atskirus aiškiai aprašytus įėjimo taškus. Verslo kode kviečiama `await requirePermission(ctx, "finance:invoice:approve")`. Konkretų objektą turinčioms teisėms serverio funkcija papildomai tikrina objekto ryšį ir leistiną būsenos perėjimą.
+
+Žmogui teisė galioja, kai bent viena jo rolė ją suteikia ir modulis įjungtas. Aktyviam vartotojui automatiškai priskiriama apsaugota profilio rolė, suteikianti visas savo profilio teises. Profilio savininką serveris nustato iš sesijos. Aktyvus `Super` gali naudoti visus registruotus modulius ir visas teises, įskaitant diagnostiką. Verslo duomenų vientisumo taisyklės galioja visiems.
+
+Agentui būtinas aktyvus raktas, aktyvus savininkas, įjungtas modulis, teisė per rakto roles ir ta pati šiuo metu galiojanti savininko teisė. Tikrinama teisės, o ne rolės ID sankirta. Kiekvieno rakto rolės nepriklausomos. `Super` statusas, išjungtų modulių išimtis ir asmeninės sesijos veiksmai raktui nepersiduoda. Pirmajai versijai raktų išdavimas, prieigos administravimas ir `Super` diagnostika skirti tik žmogaus sesijai.
+
+# Delegavimas ir paskyrų gyvavimo ciklas
+
+Rolės priskyrimui reikia ir `roles:assignment:create`, ir leidimo suteikti konkrečią tikslinę rolę. Delegavimo apimtis saugoma pagal stabilius rolių ID. Rolę galima suteikti tik jei visos jos suteikiamos teisės telpa į suteikiančiojo įgaliojimus. Vertinamos ir išjungtų modulių teisės, kad modulis vėliau neaktyvuotų neautorizuotų priskyrimų. Įprastas delegatas negali keisti savo įgaliojimų, saugomų rolių ar delegavimo ribų. Pradinę `Admin` rolę įmonei suteikia `Super`.
+
+Subrolės redagavimas keičia visas ją naudojančias roles. Prieš pakeitimą serveris įvertina paveiktas roles ir gavėjus. Pakeitimas leidžiamas tik valdant visas paveiktas roles ir galint deleguoti pridedamas teises. Jei bendrą subrolę naudoja saugoma rolė, administratorius gali kurti atskirą kopiją savo valdomai rolei. Šios taisyklės galioja ir importui, masiniams veiksmams bei kvietimams.
+
+Kvietimas susiejamas su el. paštu ir konkrečių rolių ID. Priėmimo metu tikrinamas patvirtintas gavėjo adresas, galiojimas, vienkartinis panaudojimas ir dabartinė kvietėjo teisė suteikti kiekvieną rolę. Pasikeitus įgaliojimams visas priėmimas atmetamas. Paskyra, priskyrimai ir kvietimo panaudojimas įrašomi atominiu veiksmu. Prisijungimo tapatybė susiejama pagal patikimo tiekėjo stabilų subjekto ID. Vien sutampančio el. pašto nepakanka sulieti paskyras.
+
+API rakto paslaptis rodoma vieną kartą. Convex saugo rakto ID, kriptografinę patikros reikšmę, savininką, pavadinimą, galiojimą ir atšaukimo būseną. Panaikinus raktą jo atkurti negalima. Blokavus arba uždarius savininko paskyrą atšaukiami jo raktai. Savininkui praradus tik vieną teisę kitos rakto teisės išlieka. Savininkui vėl gavus teisę ji vėl veikia, jei raktas tebėra aktyvus ir jo rolė vis dar ją suteikia.
+
+# Convex įgyvendinimo sutartis
+
+Ryšiams numatytos atskiros indeksuotos lentelės: `userRoles`, `apiKeyRoles`, `roleSubroles`, `subrolePermissions`. Atskirai saugomi `users`, `roles`, `subroles`, `modules`, `apiKeys`, `invites`, delegavimo ribos ir audito įvykiai. Užtikrinamas porų unikalumas, pakartotinių operacijų saugumas ir puslapiavimas. Nėra produkto nustatyto rolių skaičiaus limito. Didžiausiai palaikomai instaliacijai prieš išleidimą atliekamas apkrovos bandymas. Jei prieigos sprendimo nepavyksta apskaičiuoti iki galo, jis atmetamas.
+
+Next.js UI gali paslėpti veiksmą, tačiau visos viešos Convex funkcijos tikrina veikėją serveryje. Mutacija tikrina teises ir keičia duomenis vienoje transakcijoje. Užklausa skaito aktualius priskyrimus. Ilgalaikis JWT arba naršyklės kešas negali išsaugoti atšauktos teisės. Po atšaukimo patikra taikoma ir aktyvioms prenumeratoms. Jau vartotojui perduotų duomenų atšaukimas nesugrąžina.
+
+Foninė užduotis saugo veikėjo ir rakto ID, vykdymo metu iš naujo tikrina būseną ir teises. Išorinis veiksmas vykdomas pagal identifikuojamą operaciją su apsauga nuo pakartojimo. Atšaukimas sustabdo dar nepradėtą darbą. Jei išorinė sistema jau priėmė komandą, rezultatas užfiksuojamas audite. Vidiniams sistemos priežiūros darbams naudojamas siauras atskiras įėjimo taškas be vartotojo `Super` privilegijų.
+
+# Privalomi priėmimo scenarijai
+
+1. Gavėjas gauna tą pačią teisę per dvi roles. Pašalinus vieną kelią veiksmas leidžiamas, pašalinus paskutinį atmetamas.
+
+2. Pasikeitus subrolei pokytis pasiekia ir vartotoją, ir rakto roles nuo kitos patikros. Agentui savininko teisės išlieka viršutine riba.
+
+3. Raktui tiesiogiai siunčiamas teisės arba subrolės ID. Serveris atmeta visą priskyrimą.
+
+4. `Super` savininko raktas be rolių neturi verslo teisių. Su finansų role jis gali naudoti tik įjungtą `finance` modulį.
+
+5. Išjungus modulį blokuojami UI, tiesioginė API, agentas ir laukiančios užduotys. Žmogaus `Super` sesijai modulis prieinamas. Įjungus grįžta anksčiau suteiktos teisės.
+
+6. Pakeitęs profilio užklausos `userId`, vartotojas negali perskaityti ar redaguoti kito profilio. Asmeninis profilio veiksmas negali pakeisti `Super` identiteto.
+
+7. Kvietimas panaudojamas du kartus, pasibaigia arba kvietėjas netenka įgaliojimų. Papildomų priskyrimų nesukuriama.
+
+8. Raktas atšaukiamas tarp užduoties sukūrimo ir vykdymo. Užduotis nesukuria šalutinio poveikio.
+
+9. Delegatas mėgina suteikti `Admin` per kvietimą, pakeisti bendrą subrolę ar savo delegavimo ribas. Operacija atmetama.
+
+10. Du lygiagretūs pakeitimai mėgina apeiti delegavimo ribą. Galutinė būsena tenkina tas pačias taisykles kaip nuosekliai įvykdyti patikrinti pakeitimai.
+
+11. Pakartotinė modulio registracija išsaugo vartotojų pakeitimus ir įjungimo būseną. Nauja teisė savaime nepatenka į seną `Full` subrolę.
+
+12. Po diegimo iš `SUPER_USER_EMAILS` pašalinta aktyvi sesija praranda `Super`. Nepatvirtintas adresas arba DB rolė vardu `Super` privilegijos nesuteikia.
+
+13. Nežinoma teisė, ištrinta rolė, pasibaigęs raktas ar užblokuotas savininkas nesuteikia prieigos. Audite galima atskirti agentą nuo jo savininko.
+
+# Techniniai šaltiniai
+
+[OWASP Authorization Cheat Sheet](https://cheatsheetseries.owasp.org/cheatsheets/Authorization_Cheat_Sheet.html) · [Convex transakcijos](https://docs.convex.dev/database/advanced/occ) · [Convex actions](https://docs.convex.dev/functions/actions)

package/dist/config/browser.d.ts

@@ -0,0 +1,17 @@
+declare const fail: () => never;
+export declare const envSource: typeof fail;
+export declare const staticSource: typeof fail;
+export declare const infisicalSource: typeof fail;
+export declare const createSystemConfig: typeof fail;
+export declare const INFISICAL_BOOTSTRAP_KEYS: readonly string[];
+export declare class ConfigError extends Error {
+}
+declare const SystemConfig: {
+    load: typeof fail;
+    register: typeof fail;
+    status: typeof fail;
+    reset: typeof fail;
+};
+export default SystemConfig;
+export { SystemConfig };
+//# sourceMappingURL=browser.d.ts.map

package/dist/config/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/config/browser.ts"],"names":[],"mappings":"AAEA,QAAA,MAAM,IAAI,QAAO,KAEhB,CAAA;AAED,eAAO,MAAM,SAAS,aAAO,CAAA;AAC7B,eAAO,MAAM,YAAY,aAAO,CAAA;AAChC,eAAO,MAAM,eAAe,aAAO,CAAA;AACnC,eAAO,MAAM,kBAAkB,aAAO,CAAA;AACtC,eAAO,MAAM,wBAAwB,EAAE,SAAS,MAAM,EAAO,CAAA;AAC7D,qBAAa,WAAY,SAAQ,KAAK;CAAG;AAEzC,QAAA,MAAM,YAAY;IAAK,IAAI;IAAQ,QAAQ;IAAQ,MAAM;IAAQ,KAAK;CAAQ,CAAA;eAC/D,YAAY;AAC3B,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/dist/config/browser.js

@@ -0,0 +1,16 @@
+// Browser stub for `@digimuza/system-core/config`. Configuration, the Infisical
+// client and secrets are server-only; this file keeps them out of client bundles.
+const fail = () => {
+    throw new Error("@digimuza/system-core/config is server-only and cannot be used in the browser");
+};
+export const envSource = fail;
+export const staticSource = fail;
+export const infisicalSource = fail;
+export const createSystemConfig = fail;
+export const INFISICAL_BOOTSTRAP_KEYS = [];
+export class ConfigError extends Error {
+}
+const SystemConfig = { load: fail, register: fail, status: fail, reset: fail };
+export default SystemConfig;
+export { SystemConfig };
+//# sourceMappingURL=browser.js.map

package/dist/config/browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/config/browser.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,kFAAkF;AAClF,MAAM,IAAI,GAAG,GAAU,EAAE;IACvB,MAAM,IAAI,KAAK,CAAC,+EAA+E,CAAC,CAAA;AAClG,CAAC,CAAA;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,CAAA;AAC7B,MAAM,CAAC,MAAM,YAAY,GAAG,IAAI,CAAA;AAChC,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,CAAA;AACnC,MAAM,CAAC,MAAM,kBAAkB,GAAG,IAAI,CAAA;AACtC,MAAM,CAAC,MAAM,wBAAwB,GAAsB,EAAE,CAAA;AAC7D,MAAM,OAAO,WAAY,SAAQ,KAAK;CAAG;AAEzC,MAAM,YAAY,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AAC9E,eAAe,YAAY,CAAA;AAC3B,OAAO,EAAE,YAAY,EAAE,CAAA"}

package/dist/config/index.d.ts

@@ -0,0 +1,71 @@
+import type { z } from "zod";
+import { SystemError } from "../core/errors.js";
+export type ConfigValues = Readonly<Record<string, string>>;
+/** A source of configuration values (env, Infisical, static for tests). */
+export interface ConfigSource {
+    readonly name: string;
+    load(): Promise<Record<string, string>>;
+}
+export declare class ConfigError extends SystemError {
+    /** Only key names — never values. */
+    readonly keys: string[];
+    constructor(reason: string, keys: string[], message: string);
+}
+type Env = Record<string, string | undefined>;
+/** Reads process environment variables (Coolify deployment parameters). */
+export declare function envSource(env?: Env): ConfigSource;
+export declare function staticSource(values: Record<string, string>, name?: string): ConfigSource;
+/** Bootstrap parameters Coolify provides for Infisical. */
+export declare const INFISICAL_BOOTSTRAP_KEYS: readonly ["INFISCAL_BASE_URL", "INFISCAL_CLIENT_ID", "INFISCAL_SECRET", "INFISCAL_PATH", "INFISCAL_ENV", "INFISCAL_PROJECT_ID"];
+export interface InfisicalSourceOptions {
+    env?: Env;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}
+/**
+ * Loads secrets from Infisical using Universal Auth. Bootstrap credentials come
+ * from the deployment environment; missing ones produce a ConfigError naming the keys.
+ */
+export declare function infisicalSource(options?: InfisicalSourceOptions): ConfigSource;
+export interface RegisteredSchema {
+    moduleId: string;
+    keys: string[];
+}
+/** De-identified status: names only, never values. */
+export interface ConfigStatus {
+    state: "idle" | "loading" | "loaded" | "failed";
+    /** Incremented on each successful load. */
+    version: number;
+    loadedAt: number | null;
+    sources: string[];
+    keys: string[];
+    registered: RegisteredSchema[];
+    error?: {
+        reason: string;
+        keys: string[];
+    };
+}
+export interface SystemConfigOptions {
+    /** Default: env, then Infisical (Infisical wins on conflicts). */
+    sources?: readonly ConfigSource[];
+}
+export interface SystemConfigApi {
+    /** Loads one configuration version. Concurrent calls share the same load. */
+    load(): Promise<ConfigStatus>;
+    /**
+     * Synchronously validates and returns typed values for `schema`.
+     * Throws ConfigError before `load()` finished or when keys are missing/invalid.
+     */
+    register<S extends z.ZodType>(schema: S, options?: {
+        moduleId?: string;
+    }): z.infer<S>;
+    status(): ConfigStatus;
+    /** Testing only: forget the loaded version. */
+    reset(): void;
+}
+export declare function createSystemConfig(options?: SystemConfigOptions): SystemConfigApi;
+/** Process-wide instance: `await SystemConfig.load(); const env = SystemConfig.register(schema)`. */
+declare const SystemConfig: SystemConfigApi;
+export default SystemConfig;
+export { SystemConfig };
+//# sourceMappingURL=index.d.ts.map

package/dist/config/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/config/index.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAC5B,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAE/C,MAAM,MAAM,YAAY,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAE3D,2EAA2E;AAC3E,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACxC;AAED,qBAAa,WAAY,SAAQ,WAAW;IAC1C,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,CAAA;IACvB,YAAY,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAI1D;CACF;AAED,KAAK,GAAG,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAA;AAG7C,2EAA2E;AAC3E,wBAAgB,SAAS,CAAC,GAAG,GAAE,GAAkB,GAAG,YAAY,CAS/D;AAED,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,IAAI,SAAW,GAAG,YAAY,CAE1F;AAED,2DAA2D;AAC3D,eAAO,MAAM,wBAAwB,YACnC,mBAAmB,EACnB,oBAAoB,EACpB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,qBAAqB,CACb,CAAA;AAEV,MAAM,WAAW,sBAAsB;IACrC,GAAG,CAAC,EAAE,GAAG,CAAA;IACT,KAAK,CAAC,EAAE,OAAO,KAAK,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,GAAE,sBAA2B,GAAG,YAAY,CAoClF;AAED,MAAM,WAAW,gBAAgB;IAAG,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,EAAE,CAAA;CAAE;AAEtE,sDAAsD;AACtD,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,QAAQ,CAAA;IAC/C,2CAA2C;IAC3C,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,IAAI,EAAE,MAAM,EAAE,CAAA;IACd,UAAU,EAAE,gBAAgB,EAAE,CAAA;IAC9B,KAAK,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,EAAE,CAAA;KAAE,CAAA;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,kEAAkE;IAClE,OAAO,CAAC,EAAE,SAAS,YAAY,EAAE,CAAA;CAClC;AAED,MAAM,WAAW,eAAe;IAC9B,6EAA6E;IAC7E,IAAI,IAAI,OAAO,CAAC,YAAY,CAAC,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;IACrF,MAAM,IAAI,YAAY,CAAA;IACtB,+CAA+C;IAC/C,KAAK,IAAI,IAAI,CAAA;CACd;AAOD,wBAAgB,kBAAkB,CAAC,OAAO,GAAE,mBAAwB,GAAG,eAAe,CAyErF;AAED,qGAAqG;AACrG,QAAA,MAAM,YAAY,EAAE,eAAsC,CAAA;eAC3C,YAAY;AAC3B,OAAO,EAAE,YAAY,EAAE,CAAA"}