-
The framework's authorization layer is now live. Until now, every authenticated user could do everything; the framework had only an authentication gate. This chunk adds method-level @RequirePermission annotations enforced by a Spring AOP aspect that consults the JWT's roles claim and a metadata-driven role-permission map. What landed ----------- * New `Role` and `UserRole` JPA entities mapping the existing identity__role + identity__user_role tables (the schema was created in the original identity init but never wired to JPA). RoleJpaRepository + UserRoleJpaRepository with a JPQL query that returns a user's role codes in one round-trip. * `JwtIssuer.issueAccessToken(userId, username, roles)` now accepts a Set<String> of role codes and encodes them as a `roles` JWT claim (sorted for deterministic tests). Refresh tokens NEVER carry roles by design — see the rationale on `JwtIssuer.issueRefreshToken`. A role revocation propagates within one access-token lifetime (15 min default). * `JwtVerifier` reads the `roles` claim into `DecodedToken.roles`. Missing claim → empty set, NOT an error (refresh tokens, system tokens, and pre-P4.3 tokens all legitimately omit it). * `AuthService.login` now calls `userRoles.findRoleCodesByUserId(...)` before minting the access token. `AuthService.refresh` re-reads the user's roles too — so a refresh always picks up the latest set, since refresh tokens deliberately don't carry roles. * New `AuthorizationContext` ThreadLocal in `platform-security.authz` carrying an `AuthorizedPrincipal(id, username, roles)`. Separate from `PrincipalContext` (which lives in platform-persistence and carries only the principal id, for the audit listener). The two contexts coexist because the audit listener has no business knowing what roles a user has. * `PrincipalContextFilter` now populates BOTH contexts on every authenticated request, reading the JWT's `username` and `roles` claims via `Jwt.getClaimAsStringList("roles")`. The filter is the one and only place that knows about Spring Security types AND about both vibe_erp contexts; everything downstream uses just the Spring-free abstractions. * `PermissionEvaluator` Spring bean: takes a role set + permission key, returns boolean. Resolution chain: 1. The literal `admin` role short-circuits to `true` for every key (the wildcard exists so the bootstrap admin can do everything from the very first boot without seeding a complete role-permission mapping). 2. Otherwise consults an in-memory `Map<role, Set<permission>>` loaded from `metadata__role_permission` rows. The cache is rebuilt by `refresh()`, called from `VibeErpPluginManager` after the initial core load AND after every plug-in load. 3. Empty role set is always denied. No implicit grants. * `@RequirePermission("...")` annotation in `platform-security.authz`. `RequirePermissionAspect` is a Spring AOP @Aspect with @Around advice that intercepts every annotated method, reads the current request's `AuthorizationContext`, calls `PermissionEvaluator.has(...)`, and either proceeds or throws `PermissionDeniedException`. * New `PermissionDeniedException` carrying the offending key. `GlobalExceptionHandler` maps it to HTTP 403 Forbidden with `"permission denied: 'partners.partner.deactivate'"` as the detail. The key IS surfaced to the caller (unlike the 401's generic "invalid credentials") because the SPA needs it to render a useful "your role doesn't include X" message and callers are already authenticated, so it's not an enumeration vector. * `BootstrapAdminInitializer` now creates the wildcard `admin` role on first boot and grants it to the bootstrap admin user. * `@RequirePermission` applied to four sensitive endpoints as the demo: `PartnerController.deactivate`, `StockBalanceController.adjust`, `SalesOrderController.confirm`, `SalesOrderController.cancel`. More endpoints will gain annotations as additional roles are introduced; v1 keeps the blast radius narrow. End-to-end smoke test --------------------- Reset Postgres, booted the app, verified: * Admin login → JWT length 265 (was 241), decoded claims include `"roles":["admin"]` * Admin POST /sales-orders/{id}/confirm → 200, status DRAFT → CONFIRMED (admin wildcard short-circuits the permission check) * Inserted a 'powerless' user via raw SQL with no role assignments but copied the admin's password hash so login works * Powerless login → JWT length 247, decoded claims have NO roles field at all * Powerless POST /sales-orders/{id}/cancel → **403 Forbidden** with `"permission denied: 'orders.sales.cancel'"` in the body * Powerless DELETE /partners/{id} → **403 Forbidden** with `"permission denied: 'partners.partner.deactivate'"` * Powerless GET /sales-orders, /partners, /catalog/items → all 200 (read endpoints have no @RequirePermission) * Admin regression: catalog uoms, identity users, inventory locations, printing-shop plates with i18n, metadata custom-fields endpoint — all still HTTP 2xx Build ----- * `./gradlew build`: 15 subprojects, 163 unit tests (was 153), all green. The 10 new tests cover: - PermissionEvaluator: empty roles deny, admin wildcard, explicit role-permission grant, multi-role union, unknown role denial, malformed payload tolerance, currentHas with no AuthorizationContext, currentHas with bound context (8 tests). - JwtRoundTrip: roles claim round-trips through the access token, refresh token never carries roles even when asked (2 tests). What was deferred ----------------- * **OIDC integration (P4.2)**. Built-in JWT only. The Keycloak- compatible OIDC client will reuse the same authorization layer unchanged — the roles will come from OIDC ID tokens instead of the local user store. * **Permission key validation at boot.** The framework does NOT yet check that every `@RequirePermission` value matches a declared metadata permission key. The plug-in linter is the natural place for that check to land later. * **Role hierarchy**. Roles are flat in v1; a role with permission X cannot inherit from another role. Adding a `parent_role` field on the role row is a non-breaking change later. * **Resource-aware permissions** ("the user owns THIS partner"). v1 only checks the operation, not the operand. Resource-aware checks are post-v1. * **Composite (AND/OR) permission requirements**. A single key per call site keeps the contract simple. Composite requirements live in service code that calls `PermissionEvaluator.currentHas` directly. * **Role management UI / REST**. The framework can EVALUATE permissions but has no first-class endpoints for "create a role", "grant a permission to a role", "assign a role to a user". v1 expects these to be done via direct DB writes or via the future SPA's role editor (P3.x); the wiring above is intentionally policy-only, not management. -
The keystone of the framework's "key user adds fields without code" promise. A YAML declaration is now enough to add a typed custom field to an existing entity, validate it on every save, and surface it to the SPA / OpenAPI / AI agent. This is the bit that makes vibe_erp a *framework* instead of a fork-per-customer app. What landed ----------- * Extended `MetadataYamlFile` with a top-level `customFields:` section and `CustomFieldYaml` + `CustomFieldTypeYaml` wire-format DTOs. The YAML uses a flat `kind: decimal / scale: 2` discriminator instead of Jackson polymorphic deserialization so plug-in authors don't have to nest type configs and api.v1's `FieldType` stays free of Jackson imports. * `MetadataLoader.doLoad` now upserts `metadata__custom_field` rows alongside entities/permissions/menus, with the same delete-by-source idempotency. `LoadResult` carries the count for the boot log. * `CustomFieldRegistry` reads every `metadata__custom_field` row from the database and builds an in-memory `Map<entityName, List<CustomField>>` for the validator's hot path. `refresh()` is called by `VibeErpPluginManager` after the initial core load AND after every plug-in load, so a freshly-installed plug-in's custom fields are immediately enforceable. ConcurrentHashMap under the hood; reads are lock-free. * `ExtJsonValidator` is the on-save half: takes (entityName, ext map), walks the declared fields, coerces each value to its native type, and returns the canonicalised map (or throws IllegalArgumentException with ALL violations joined for a single 400). Per-FieldType rules: - String: maxLength enforced. - Integer: accepts Number and numeric String, rejects garbage. - Decimal: precision/scale enforced; preserved as plain string in canonical form so JSON encoding doesn't lose trailing zeros. - Boolean: accepts true/false (case-insensitive). - Date / DateTime: ISO-8601 parse via java.time. - Uuid: java.util.UUID parse. - Enum: must be in declared `allowedValues`. - Money / Quantity / Json / Reference: pass-through (Reference target existence check pending the cross-PBC EntityRegistry seam). Unknown ext keys are rejected with the entity's name and the keys themselves listed. ALL violations are returned in one response, not failing on the first, so a form submitter fixes everything in one round-trip. * `Partner` is the first PBC entity to wire ext through the validator: `CreatePartnerRequest` and `UpdatePartnerRequest` accept an `ext: Map<String, Any?>?`; `PartnerService.create/update` calls `extValidator.validate("Partner", ext)` and persists the canonical JSON to the existing `partners__partner.ext` JSONB column; `PartnerResponse` parses it back so callers see what they wrote. * `partners.yml` now declares two custom fields on Partner — `partners_credit_limit` (Decimal precision=14, scale=2) and `partners_industry` (Enum of printing/publishing/packaging/other) — with English and Chinese labels. Tagged `source=core` so the framework has something to demo from a fresh boot. * New public `GET /api/v1/_meta/metadata/custom-fields/{entityName}` endpoint serves the api.v1 runtime view of declarations from the in-memory registry (so it reflects every refresh) for the SPA's form builder, the OpenAPI generator, and the AI agent function catalog. The existing `GET /api/v1/_meta/metadata` endpoint also gained a `customFields` list. End-to-end smoke test --------------------- Reset Postgres, booted the app, verified: * Boot log: `CustomFieldRegistry: refreshed 2 custom fields across 1 entities (0 malformed rows skipped)` — twice (after core load and after plug-in load). * `GET /api/v1/_meta/metadata/custom-fields/Partner` → both declarations with their labels. * `POST /api/v1/partners/partners` with `ext = {credit_limit: "50000.00", industry: "printing"}` → 201; the response echoes the canonical map. * `POST` with `ext = {credit_limit: "1.234", industry: "unicycles", rogue: "x"}` → 400 with all THREE violations in one body: "ext contains undeclared key(s) for 'Partner': [rogue]; ext.partners_credit_limit: decimal scale 3 exceeds declared scale 2; ext.partners_industry: value 'unicycles' is not in allowed set [printing, publishing, packaging, other]". * `SELECT ext FROM partners__partner WHERE code = 'CUST-EXT-OK'` → `{"partners_industry": "printing", "partners_credit_limit": "50000.00"}` — the canonical JSON is in the JSONB column verbatim. * Regression: catalog uoms, identity users, partners list, and the printing-shop plug-in's POST /plates (with i18n via Accept-Language: zh-CN) all still HTTP 2xx. Build ----- * `./gradlew build`: 13 subprojects, 129 unit tests (was 118), all green. The 11 new tests cover each FieldType variant, multi-violation reporting, required missing rejection, unknown key rejection, and the null-value-dropped case. What was deferred ----------------- * JPA listener auto-validation. Right now PartnerService explicitly calls extValidator.validate(...) before save; Item, Uom, User and the plug-in tables don't yet. Promoting the validator to a JPA PrePersist/PreUpdate listener attached to a marker interface HasExt is the right next step but is its own focused chunk. * Reference target existence check. FieldType.Reference passes through unchanged because the cross-PBC EntityRegistry that would let the validator look up "does an instance with this id exist?" is a separate seam landing later. * The customization UI (Tier 1 self-service add a field via the SPA) is P3.3 — the runtime enforcement is done, the editor is not. * Custom-field-aware permissions. The `pii: true` flag is in the metadata but not yet read by anything; the DSAR/erasure pipeline that will consume it is post-v1.0. -
The third real PBC. Validates the modular-monolith template against a parent-with-children aggregate (Partner → Addresses → Contacts), where the previous two PBCs only had single-table or two-independent-table shapes. What landed ----------- * New Gradle subproject `pbc/pbc-partners` (12 modules total now). * Three JPA entities, all extending `AuditedJpaEntity`: - `Partner` — code, name, type (CUSTOMER/SUPPLIER/BOTH), tax_id, website, email, phone, active, ext jsonb. Single-table for both customers and suppliers because the role flag is a property of the relationship, not the organisation. - `Address` — partner_id FK, address_type (BILLING/SHIPPING/OTHER), line1/line2/city/region/postal_code/country_code (ISO 3166-1), is_primary. Two free address lines + structured city/region/code is the smallest set that round-trips through every postal system. - `Contact` — partner_id FK, full_name, role, email, phone, active. PII-tagged in metadata YAML for the future audit/export tooling. * Spring Data JPA repos, application services with full CRUD and the invariants below, REST controllers under `/api/v1/partners/partners` (+ nested addresses, contacts). * `partners-init.xml` Liquibase changelog with the three tables, FKs, GIN index on `partner.ext`, indexes on type/active/country. * New api.v1 facade `org.vibeerp.api.v1.ext.partners` with `PartnersApi` + `PartnerRef`. Third `ext.<pbc>` after identity and catalog. Inactive partners hidden at the facade boundary. * `PartnersApiAdapter` runtime implementation in pbc-partners, never leaking JPA entity types. * `partners.yml` metadata declaring all 3 entities, 12 permission keys, 1 menu entry. Picked up automatically by `MetadataLoader`. * 15 new unit tests across `PartnerServiceTest`, `AddressServiceTest` and `ContactServiceTest` (mockk-based, mirroring catalog tests). Invariants enforced in code (not blindly delegated to the DB) ------------------------------------------------------------- * Partner code uniqueness — explicit check produces a 400 with a real message instead of a 500 from the unique-index violation. * Partner code is NOT updatable — every external reference uses code, so renaming is a data-migration concern, not an API call. * Partner deactivate cascades to contacts (also flipped to inactive). Addresses are NOT touched (no `active` column — they exist or they don't). Verified end-to-end against Postgres. * "Primary" flag is at most one per (partner, address_type). When a new/updated address is marked primary, all OTHER primaries of the same type for the same partner are demoted in the same transaction. * Addresses and contacts reject operations on unknown partners up-front to give better errors than the FK-violation. End-to-end smoke test --------------------- Reset Postgres, booted the app, hit: * POST /api/v1/auth/login (admin) → JWT * POST /api/v1/partners/partners (CUSTOMER, SUPPLIER) → 201 * GET /api/v1/partners/partners → lists both * GET /api/v1/partners/partners/by-code/CUST-ACME → resolves * POST /api/v1/partners/partners (dup code) → 400 with real message * POST .../{id}/addresses (BILLING, primary) → 201 * POST .../{id}/contacts → 201 * DELETE /api/v1/partners/partners/{id} → 204; partner active=false * GET .../contacts → contact ALSO active=false (cascade verified) * GET /api/v1/_meta/metadata/entities → 3 partners entities present * GET /api/v1/_meta/metadata/permissions → 12 partners permissions * Regression: catalog UoMs/items, identity users, printing-shop plug-in plates all still HTTP 200. Build ----- * `./gradlew build`: 12 subprojects, 107 unit tests, all green (was 11 / 92 before this commit). * The architectural rule still enforced: pbc-partners depends on api-v1 + platform-persistence + platform-security only — no cross-PBC dep, no platform-bootstrap dep. What was deferred ----------------- * Permission enforcement on contact endpoints (P4.3). Currently plain authenticated; the metadata declares the planned `partners.contact.*` keys for when @RequirePermission lands. * Per-country address structure layered on top via metadata forms (P3.x). The current schema is the smallest universal subset. * `deletePartnerCompletely` — out of scope for v1; should be a separate "data scrub" admin tool, not a routine API call.
