bmad-method-quarkus 1.0.5 → 1.0.6

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-openapi-tmforum/SKILL.md

@@ -31,7 +31,7 @@ The raw OpenAPI document at `/q/openapi` may stay enabled in prod behind the gat
 
 ### URLs & versioning
 - Plural kebab-free camelCase resource names as in TMF specs: `/user`, `/partyAccount` — follow the TMF spec exactly when implementing one; plural nouns for custom resources.
-- Base path starts with the module's semantic name (`iam`, `tenant` — see quarkus-hexagonal-core skill, never a `bcNN` code): `/{module}/{context}/{apiName}/v{major}` e.g. `/iam/tmf-api/digitalIdentityManagement/v4`. Major version in path only.
+- Base path starts with the module's semantic name (`iam`, `tenant` — see quarkus-hexagonal-core skill, never a `bcNN` code): `/{module}/{context}/{apiName}/v{major}` e.g. `/iam/tmf-api/digitalIdentityManagement/v4`. Major version in path only. That leading `/{module}` segment is also the app's **API gateway base path**, and it is declared in the same PR in README §2 and `service.yaml` under `metadata.gateway` — infra configures the route from there (see quarkus-hexagonal-core skill, "Gateway routing").
 
 ### Standard operations
 | Operation | Verb | Response |
@@ -89,6 +89,7 @@ public class DigitalIdentityResource {
 
     @Inject CreateDigitalIdentityHandler createHandler;   // the slice's business logic
     @Inject FindDigitalIdentityHandler findHandler;
+    @Inject JsonWebToken jwt;                             // tenant/roles come from the validated token
 
     @GET
     @Blocking
@@ -96,12 +97,11 @@ public class DigitalIdentityResource {
     @APIResponse(responseCode = "200", content = @Content(schema = @Schema(implementation = DigitalIdentityDto[].class)))
     @APIResponse(responseCode = "400", ref = "#/components/responses/BadRequest")
     public RestResponse<List<DigitalIdentityDto>> list(
-            @HeaderParam("tenantId") String tenantId,
             @QueryParam("fields") String fields,
             @QueryParam("offset") @DefaultValue("0") int offset,
             @QueryParam("limit") @DefaultValue("20") int limit) {
         var query = FilterDigitalIdentityDto.builder()
-            .tenantId(tenantId).fields(fields).offset(offset).limit(limit).build();
+            .tenantId(jwt.getClaim("tenant_id")).fields(fields).offset(offset).limit(limit).build();
         return RestResponse.ok(findHandler.process(query).getItems());
     }
 
@@ -109,10 +109,9 @@ public class DigitalIdentityResource {
     @Blocking
     @Operation(operationId = "createDigitalIdentity")
     @APIResponse(responseCode = "201", headers = @Header(name = "Location"))
-    public RestResponse<DigitalIdentityDto> create(@HeaderParam("tenantId") String tenantId,
-                                                   @Valid DigitalIdentityCreateDto dto,
+    public RestResponse<DigitalIdentityDto> create(@Valid DigitalIdentityCreateDto dto,
                                                    @Context UriInfo uri) {
-        dto.setTenantId(tenantId);
+        dto.setTenantId(jwt.getClaim("tenant_id"));            // validated JWT claim, never a header
         var created = createHandler.process(dto);              // BusinessException propagates to the global handler
         return RestResponse.ResponseBuilder
             .created(uri.getAbsolutePathBuilder().path(created.getId()).build())
@@ -124,7 +123,7 @@ public class DigitalIdentityResource {
 Rules:
 - Return `RestResponse<T>` synchronously — typed, so the generated schema is right. Never `Uni`/`Multi`: the `Handler` is blocking JDBC.
 - `@Blocking` (`io.smallrye.common.annotation.Blocking`) on JDBC-backed methods. With a plain return type Quarkus REST already dispatches to a worker thread, so it is redundant today — keep it as an explicit threading contract that survives a later signature change. `@RunOnVirtualThread` is the high-concurrency alternative (see sql skill §8).
-- Extract `tenantId`, `partyId`, `partyRolList`, `language` from headers where the contract requires them and set them on the request DTO before calling `process()`.
+- Take `tenantId` — and anything else that drives authorization, such as `partyId` or `partyRolList` — from the validated token (`@Inject JsonWebToken jwt` → `jwt.getClaim(...)`, or `@Claim`; `SecurityIdentity` carries roles and mechanism attributes, **not** claims), **never** from a `@HeaderParam`: a header the caller sets is not authentication (see quarkus-security-standards skill §4 and the tenancy rule in quarkus-hexagonal-core). `language` and other non-security metadata may come from headers. Set them on the request DTO before calling `process()`.
 - No `try/catch` around `process()`. Errors travel as `BusinessException` to `GlobalExceptionHandler`, which resolves the localized TMF Error body (see quarkus-error-handling-i18n skill).
 - `operationId` on every operation (client generation depends on it); match TMF naming (`listX`, `retrieveX`, `createX`, `patchX`, `deleteX`).
 - Reusable components: define common responses (400/401/404/409/500 with TMF Error schema) once via an `@OpenAPIDefinition`/filter class, `ref` them everywhere.

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-security-standards/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: quarkus-security-standards
+description: Security baseline for Quarkus backend services — credential and environment-variable handling via `.env` (never committed) plus a committed `.env.example` template, secrets management, authentication/authorization (OIDC/JWT), transport security, input/output hardening, dependency and container hardening, and secret-safe logging. Use this skill whenever the user creates or reviews `application.properties`/`.env` files, injects a credential/URL/API key/token, adds `quarkus-oidc`/`quarkus-smallrye-jwt`, configures CORS/TLS/headers, writes a `Dockerfile`, adds a dependency, or asks about security review, secret leakage, `.gitignore`, or OWASP. Pairs with quarkus-hexagonal-core (project layout), quarkus-sql-jdbc-agroal (injection-safe SQL), and quarkus-observability-otel (PII-safe logging).
+---
+
+# Security Standard (Quarkus)
+
+Applies to any Quarkus backend project; project directives (CLAUDE.md, ADRs, explicit instructions) override these defaults where they conflict.
+
+## 1. Environment variables: `.env` for local secrets, never committed
+
+**No credential, URL, API key, token, or other environment-specific secret is ever hardcoded in source or committed to the repository.** Locally, they live in a `.env` file at the project root; in every other environment they come from the platform's secret store (see §2). This is the first rule to apply on any new service, before the first `application.properties` line is written.
+
+Rules, in order:
+
+1. **Create `.env`** at the project root (or per-app root in a monorepo, `apps/<app>/.env`) holding every local credential, connection URL, host, port, and API key the service needs to run in `%dev`/`%test`. Real values only, never sample/placeholder values here.
+2. **`.env` is never versioned.** Add it to `.gitignore` **immediately**, in the same commit that creates it — never after the fact:
+
+   ```gitignore
+   # Local environment secrets — never commit
+   .env
+   .env.*
+   !.env.example
+   ```
+
+   If `.env` was ever committed by mistake, it must be purged from history (`git filter-repo` or equivalent) and every credential it contained rotated — removing the file from the tip of the branch is not sufficient.
+3. **Create `.env.example`** alongside it, committed to the repo, listing every variable `.env` must define — **keys only, placeholder or empty values, never real secrets**:
+
+   ```dotenv
+   # .env.example — copy to .env and fill in real values. Never commit .env.
+   DB_HOST=localhost
+   DB_PORT=5432
+   DB_NAME=customer
+   DB_USER=
+   DB_PASSWORD=
+   KAFKA_BOOTSTRAP_SERVERS=localhost:9092
+   OIDC_AUTH_SERVER_URL=
+   OIDC_CLIENT_ID=
+   OIDC_CLIENT_SECRET=
+   EXTERNAL_API_BASE_URL=
+   EXTERNAL_API_KEY=
+   ```
+
+   `.env.example` is the authoritative, reviewable list of what the service needs — update it in the same PR that introduces a new variable. A variable missing from `.env.example` does not exist as far as onboarding and CI are concerned.
+4. **Reference the variables from `application.properties` via Quarkus property expressions**, never by reading `.env` manually in code:
+
+   ```properties
+   quarkus.datasource.username=${DB_USER}
+   quarkus.datasource.password=${DB_PASSWORD}
+   quarkus.datasource.jdbc.url=jdbc:postgresql://${DB_HOST}:${DB_PORT}/${DB_NAME}
+   quarkus.oidc.auth-server-url=${OIDC_AUTH_SERVER_URL}
+   quarkus.oidc.credentials.secret=${OIDC_CLIENT_SECRET}
+   ```
+
+   Quarkus resolves `${VAR}` from process environment variables at runtime (uppercase-with-underscores env var names map automatically — no extra wiring). Quarkus/SmallRye Config reads a `.env` file in the working directory natively in dev and test — no extension is needed, and `quarkus-dotenv` should not be added. Nothing in `main` code parses `.env` directly.
+5. **Never print, log, or return an environment variable's value.** A `Handler`/`Resource` that echoes a config value back for "debugging" is a leak waiting to happen — see §7.
+
+This applies to **every** environment-specific value, not just passwords: hostnames, ports, bucket names, tenant-specific URLs, and feature-flag endpoints belong in `.env`/the platform secret store too — hardcoding a "just a hostname" value is how an internal URL ends up in a public repo.
+
+## 2. Beyond local dev: secrets in real environments
+
+`.env` is a **local-development convenience only** — it is never the secret source in a deployed environment.
+
+- Deployed environments (dev cluster, staging, prod) inject secrets as environment variables or mounted files from a vault (HashiCorp Vault, cloud KMS/Secrets Manager, Kubernetes `Secret` backed by an external secret operator) — never from a `.env` file baked into an image.
+- `application.properties` stays identical across environments: `${VAR}` placeholders only. What changes per environment is *where the platform gets the value from*, never the property file.
+- Kubernetes: mount secrets as env vars via `secretKeyRef`, never as plain `ConfigMap` values, and never bake a secret into the container image at build time.
+- The per-app `README.md` **Secrets** section (see quarkus-hexagonal-core skill, §"Per-app documentation") documents logical name, purpose, vault source, owner, and rotation period for every secret — **never the value itself**.
+- Rotate credentials on a schedule and immediately on suspected exposure (accidental commit, departing team member with access, log leak).
+
+## 3. No secrets in code, config, or version control
+
+- No API key, password, connection string, private key, or token as a string literal anywhere in `src/`, `pom.xml`, test fixtures, or committed `application.properties`. Grep for this in review: `grep -rniE "(password|secret|api[_-]?key|token)[[:space:]]*=[[:space:]]*['\"][^$]" src/` (a `${VAR}` right-hand side is fine; a literal value is not).
+- Test fixtures use `%test` profile values pointing at Dev Services (ephemeral Testcontainers credentials, not real ones) — never a copy of a real credential "just for tests."
+- `application.properties` committed to the repo may reference `${VAR}` freely; it never assigns a literal secret value, including in a profile-specific override (`%prod.quarkus.datasource.password=...` is banned exactly like the unscoped form).
+- Private keys/certificates (`.pem`, `.jks`, `.p12`) are never committed. Reference their filesystem path (mounted from a secret) via `${VAR}`, same as any other credential.
+
+## 4. Authentication and authorization
+
+- Inbound REST/gRPC authentication is `quarkus-oidc` (OIDC/JWT) against the org's identity provider — no home-grown token schemes, no hardcoded API keys as the sole auth mechanism for a production endpoint.
+- `tenantId` is read from a **validated JWT claim**, never a free-form request header (see quarkus-hexagonal-core skill's tenancy rule) — a header the caller can set to any value is not authentication.
+- Authorize at the `Resource`/`GrpcService` boundary with `@RolesAllowed`/`SecurityIdentity` checks before invoking `Handler.process()`; the `Handler` trusts the DTO it receives came from an already-authorized caller and does not re-implement authorization logic.
+- Service-to-service calls (internal gRPC) use mTLS or a service-account token from the platform's identity system, injected via `${VAR}` per §1 — never a shared static secret checked into `common/client`.
+- `quarkus.oidc.credentials.secret` and any client secret follow §1/§3 exactly: `.env` locally, vault in deployed environments, `${VAR}` in properties.
+
+## 5. Transport and network security
+
+- TLS terminates at the ingress/service mesh in most deployments; where the service terminates TLS itself, `quarkus.http.ssl.certificate.*` paths point at mounted secret files via `${VAR}`, never inline certs/keys.
+- HTTP is never the accepted transport for a real environment. **Where TLS terminates at the ingress (the usual case) leave `quarkus.http.insecure-requests` alone** — the pod has no certificate, so forcing `redirect`/`disabled` there breaks its own probes and the mesh's plain-HTTP hop to it. Set it only on a service that terminates TLS itself; otherwise enforce HTTPS at the ingress, where the certificate lives.
+- CORS is explicit and scoped, never `*` in a deployed environment:
+
+  ```properties
+  quarkus.http.cors.enabled=true
+  quarkus.http.cors.origins=${ALLOWED_ORIGINS:http://localhost:3000}
+  quarkus.http.cors.methods=GET,POST,PUT,PATCH,DELETE
+  ```
+
+- Internal service calls are gRPC, external/north-bound is REST (see quarkus-hexagonal-core skill) — this also means the internal surface is not exposed to the public network by default; ingress rules should reflect that boundary.
+
+## 6. Input handling and injection
+
+- SQL: `PreparedStatement` placeholders only, never string-concatenated user input — full standard in quarkus-sql-jdbc-agroal skill (§2 there). This skill's `.env` rule and that skill's placeholder rule are the two halves of "never trust a string that reaches persistence."
+- Bean Validation (`@NotBlank`, `@Size`, `@Pattern`) on every DTO field at the transport boundary; `Handler.validate()` covers business-rule validation (see quarkus-hexagonal-core skill) — reject malformed input before it reaches `execution()`.
+- Deserialize only into typed DTOs (`@RegisterForReflection` where native requires it) — never accept and reflect back arbitrary JSON structures (mass-assignment risk).
+- Any value echoed into a response, log line, or downstream call that originated from user input is treated as untrusted: encode/escape for its destination context (JSON, log line, SQL, shell) rather than assuming it is already safe.
+- Never build a shell command, file path, or SQL fragment by concatenating request data. If a slice genuinely needs to invoke an external process, pass arguments as an array (no shell interpretation), never a single interpolated string.
+
+## 7. Secret-safe logging and error responses
+
+- **Never log a credential, token, full connection string, or environment-variable value.** Log the variable's *name*, never its value, when debugging config issues.
+- Pairs with quarkus-observability-otel skill: spans, attributes, and audit `context` are business-relevant and low-cardinality — the same rule bans PII, and it bans secrets identically. If a field would be a problem in a trace, it is a problem in a log line too.
+- `GlobalExceptionHandler`/`GrpcExceptionInterceptor` (see quarkus-error-handling-i18n skill) return the catalog message only — never a stack trace, an internal exception message, or a raw `SQLException` string to the client. Full detail goes to the log (still secret-scrubbed), the client gets `<MOD>-<HTTP>-<seq>` + localized text + `X-Trace-Id`.
+- Actuator/health/metrics endpoints (`/q/health`, `/q/metrics`) never surface configuration values, environment variables, or datasource URLs — verify no custom health check echoes a connection string in its response.
+
+## 8. Dependencies and container hardening
+
+- Run dependency vulnerability scanning (OWASP Dependency-Check, `mvn org.owasp:dependency-check-maven:check`, or the platform's equivalent) in CI; a new dependency with a known critical CVE and no fix available needs an explicit, documented exception, not a silent merge.
+- Pin dependency versions through the Quarkus BOM; avoid version ranges that can silently pull in an unreviewed transitive update.
+- The native-image Dockerfile (see quarkus-hexagonal-core skill) already enforces the two container-hardening rules that matter most: a minimal base image with **no JDK/JRE layer** in the final image, and a **non-root `USER`**. Never widen either for convenience.
+- No secret is ever baked into a Docker image layer (`ENV MY_SECRET=...` in a `Dockerfile`, or a `COPY .env`) — secrets are injected at container start by the orchestrator, per §2.
+
+## Checklist for a new service or slice
+
+1. `.env` created with real local values; `.gitignore` entry added in the **same commit**.
+2. `.env.example` committed with every variable name `.env` defines, placeholder/empty values only, kept current with every new variable.
+3. `application.properties` references every credential/URL via `${VAR}` — zero literal secrets, in any profile.
+4. `grep -rniE "(password|secret|api[_-]?key|token)[[:space:]]*=[[:space:]]*['\"][^$]" src/` returns nothing.
+5. Deployed environments source the same variables from the platform vault/secret store, documented (never valued) in the app's `README.md` Secrets section.
+6. Inbound auth is `quarkus-oidc`/JWT; `tenantId` comes from a validated claim, not a free header.
+7. TLS enforced outside `%dev`; CORS origins explicit, never `*` in a deployed environment.
+8. No log line, error response, health/metrics endpoint, or trace attribute ever carries a secret, token, or full connection string.
+9. Native Dockerfile: non-root user, no JDK/JRE layer, no secret baked into a layer.
+10. Dependency scan clean or exceptions documented.

package/src/bmm-skills/agents/bmad-quarkus-build/skills/quarkus-sql-jdbc-agroal/SKILL.md

@@ -207,7 +207,7 @@ Read side: `rs.getString("context")` then parse. Index jsonb lookups you actuall
 
 ## 6. Cross-cutting tables get a cross-cutting `Sql`
 
-One `Sql` class per slice is the rule for the slice's **own** tables. A table that every slice writes the same way — `outbox`, `audit_event`, `processed_event` — gets **one** `Sql` class in `common/`, and a `Connection`-first capability bean in front of it:
+One `Sql` class per slice is the rule for the slice's **own** tables. A table that every slice writes the same way — `outbox_event`, `audit_event`, `processed_event` — gets **one** `Sql` class in `common/`, and a `Connection`-first capability bean in front of it:
 
 | Table | Owner in `common/` | Called by |
 |---|---|---|
@@ -284,6 +284,9 @@ quarkus.flyway.migrate-at-start=false
 %test.quarkus.flyway.enabled=true
 %test.quarkus.flyway.migrate-at-start=true
 
+# Classpath location by default. The monorepo keeps migrations in db/ at the REPO root, which is
+# not on the classpath — either copy them into src/main/resources/db/migration at build time, or
+# point Flyway at the filesystem: quarkus.flyway.locations=filesystem:../../db/migration
 quarkus.flyway.locations=db/migration
 quarkus.flyway.baseline-on-migrate=true    # adopting an existing database
 ```
@@ -319,4 +322,4 @@ Rules:
 5. `executeUpdate()` count returned or checked; `SQLException` propagated for the `Handler` to translate, never swallowed.
 6. Generated ids via `RETURNING`; jsonb via `PGobject`; batch + chunking for bulk; keyset pagination if deep.
 7. Rows mapped by hand into the slice's `*Dto`; Dev Services test written.
-8. The table belongs to this slice. If it is cross-cutting (`outbox`, `audit_event`, `processed_event`), the method belongs in `common/` (§6) — not here.
+8. The table belongs to this slice. If it is cross-cutting (`outbox_event`, `audit_event`, `processed_event`), the method belongs in `common/` (§6) — not here.