@mereb/shared-packages 0.0.40 → 0.0.42

package/README.md

@@ -1,44 +1,63 @@
-# Shared Mereb Backend Packages
+# @mereb/shared-packages
 
-This package exposes the shared Fastify/OpenTelemetry helpers used across the backend services. It is built independently with TypeScript and published as `@mereb/shared-packages`.
+Shared backend package consumed by `svc-*` services. It centralizes common auth, config, logging, telemetry, Kafka, Redis, event envelope, and media helper utilities.
+
+## What this package exports
+
+Primary root exports from `src/index.ts`:
+
+- `auth/jwks`: JWT verification helpers (`verifyJwt`, header parsing helpers)
+- `config/env`: env loading and typed env access (`loadEnv`, `getEnv`, `loadThenGetEnvs`, ...)
+- `logger`: pino logger setup + Fastify logger options
+- `observability/otel`: OpenTelemetry bootstrap helpers
+- `messaging/kafka`: Kafka client/config helpers
+- `cache/redis`: Redis client helpers
+- `events/envelope` and `events/publisher`: integration event envelopes + publish helpers
+- `media/s3`: media URL and upload-key helpers
+
+Extra testing exports:
+
+- `@mereb/shared-packages/testing/db`
+- `@mereb/shared-packages/testing/kafka`
+- `@mereb/shared-packages/testing/oidc`
 
 ## Local development
 
 ```bash
-pnpm install
 pnpm --filter @mereb/shared-packages lint
 pnpm --filter @mereb/shared-packages typecheck
+pnpm --filter @mereb/shared-packages test
 pnpm --filter @mereb/shared-packages build
 ```
 
-The compiled JavaScript and type definitions land in `dist/`.
+Build output is written to `dist/`.
 
-## Jenkins publishing workflow
+## Versioning and publishing
 
-The folder contains its own `Jenkinsfile` plus `.ci/ci.yml` so it can run through the `mereb-jenkins` shared library just like the services do.
+Version is controlled in `package.json` and published as `@mereb/shared-packages`.
 
-1. **Version bump** – run `pnpm --filter @mereb/shared-packages version:bump` (optionally pass `major` or `minor`). The script inspects the latest `v*` tag and updates `package.json` to the next version so the release tag and package stay in sync.
-2. **Push to `main`** – Jenkins runs the branch build. After it lints/builds, the `release.autoTag` stage (configured with `allowDirty: true` because the build leaves `node_modules/` around) creates and pushes the next `v<semver>` tag.
-3. **Release stages** – in the same build, the new `releaseStages` block uses that tag (`RELEASE_TAG`) to run `pnpm publish` and then the `release.github` stage publishes release notes.
-4. **Jenkins job** – create a Multibranch Pipeline pointing at this repository. Tags are optional now, but still enable tag discovery if you want Jenkins to react to manual tags.
-5. **Credentials** – add an `npm-registry-token` secret text credential in Jenkins for npm publish, plus `github-credentials` for tagging/GitHub releases. The pipeline writes the npm token to `.npmrc` during the publish stage.
-6. **Registry override (optional)** – set the job environment variable `NPM_REGISTRY` if you publish somewhere other than `https://registry.npmjs.org`.
+Bump version:
 
-Every successful `main` build with a version bump now produces a tag, publishes the package, and creates GitHub release notes without waiting for a second job.
+```bash
+pnpm --filter @mereb/shared-packages version:bump
+```
 
-> Tip: The bump script accepts `major`, `minor`, or `patch` (default) so you can control which segment changes: `pnpm --filter @mereb/shared-packages version:bump minor`.
+Optional bump type:
 
-> The repo installs a Husky `pre-commit` hook that automatically runs `pnpm run version:bump` and stages `services/shared/package.json`, keeping the version aligned with the next release tag before every commit. Jenkins sets `HUSKY=0` (see `.ci/ci.yml`) so the hook never runs in CI; locally you can bypass it with `HUSKY=0 git commit ...`.
+```bash
+pnpm --filter @mereb/shared-packages version:bump minor
+pnpm --filter @mereb/shared-packages version:bump major
+```
 
-## Manual publish (fallback)
+The repository includes Jenkins + `.ci/ci.yml` automation for tag/release/publish flow.
 
-If you need to publish outside Jenkins:
+## Manual publish fallback
 
 ```bash
 cd services/shared
 pnpm install
-pnpm lint && pnpm typecheck && pnpm build
+pnpm lint
+pnpm typecheck
+pnpm build
 NPM_TOKEN=... pnpm publish --registry https://registry.npmjs.org --no-git-checks
 ```
-
-Ensure the git tag matches the package version before publishing so the CI job can take over again on the next release.

package/dist/auth/jwks.d.ts

@@ -1,5 +1,8 @@
 import { type JWTPayload } from 'jose';
 import type { IncomingHttpHeaders } from 'node:http';
+export declare const FULL_ADMIN_ROLES: readonly ["admin", "mereb.admin", "realm-admin"];
+export declare const LIMITED_ADMIN_ROLES: readonly ["moderator", "support", "admin.viewer", "mereb.staff"];
+export declare const READ_ONLY_ADMIN_ROLES: readonly ["admin", "mereb.admin", "realm-admin", "moderator", "support", "admin.viewer", "mereb.staff"];
 export interface VerifyJwtOptions {
     issuer: string;
     audience?: string | string[];
@@ -8,5 +11,9 @@ export interface VerifyJwtOptions {
 export declare function initJwks(issuer: string): Promise<void>;
 export declare function verifyJwt(token: string, { issuer, audience }: VerifyJwtOptions): Promise<JWTPayload>;
 export declare function extractUserId(payload: JWTPayload): string | undefined;
+export declare function extractJwtRoles(payload: JWTPayload): string[];
+export declare function hasAnyRole(roles: readonly string[] | undefined, allowedRoles: readonly string[]): boolean;
+export declare function hasAdminReadAccess(roles: readonly string[] | undefined): boolean;
+export declare function hasFullAdminAccess(roles: readonly string[] | undefined): boolean;
 export declare function parseAuthHeader(headers: IncomingHttpHeaders): string | undefined;
 //# sourceMappingURL=jwks.d.ts.map

package/dist/auth/jwks.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../../src/auth/jwks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AACtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAIrD,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,iBAI5C;AAED,wBAAsB,SAAS,CAC7B,KAAK,EAAE,MAAM,EACb,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,gBAAgB,uBAYvC;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,sBAEhD;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,mBAAmB,GAC3B,MAAM,GAAG,SAAS,CAMpB"}
+{"version":3,"file":"jwks.d.ts","sourceRoot":"","sources":["../../src/auth/jwks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiC,KAAK,UAAU,EAAE,MAAM,MAAM,CAAC;AACtE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAIrD,eAAO,MAAM,gBAAgB,kDAAmD,CAAC;AACjF,eAAO,MAAM,mBAAmB,kEAKtB,CAAC;AACX,eAAO,MAAM,qBAAqB,yGAAyD,CAAC;AAE5F,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;IAC7B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,wBAAsB,QAAQ,CAAC,MAAM,EAAE,MAAM,iBAI5C;AAED,wBAAsB,SAAS,CAC7B,KAAK,EAAE,MAAM,EACb,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,gBAAgB,uBAYvC;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,UAAU,sBAEhD;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,MAAM,EAAE,CAS7D;AAED,wBAAgB,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,EAAE,YAAY,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAKzG;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAEhF;AAED,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,SAAS,GAAG,OAAO,CAEhF;AAED,wBAAgB,eAAe,CAC7B,OAAO,EAAE,mBAAmB,GAC3B,MAAM,GAAG,SAAS,CAMpB"}

package/dist/auth/jwks.js

@@ -1,5 +1,13 @@
 import { createRemoteJWKSet, jwtVerify } from 'jose';
 let jwks;
+export const FULL_ADMIN_ROLES = ['admin', 'mereb.admin', 'realm-admin'];
+export const LIMITED_ADMIN_ROLES = [
+    'moderator',
+    'support',
+    'admin.viewer',
+    'mereb.staff'
+];
+export const READ_ONLY_ADMIN_ROLES = [...FULL_ADMIN_ROLES, ...LIMITED_ADMIN_ROLES];
 export async function initJwks(issuer) {
     jwks = createRemoteJWKSet(new URL(`${issuer.replace(/\/$/, '')}/protocol/openid-connect/certs`));
 }
@@ -16,6 +24,25 @@ export async function verifyJwt(token, { issuer, audience }) {
 export function extractUserId(payload) {
     return typeof payload.sub === 'string' ? payload.sub : undefined;
 }
+export function extractJwtRoles(payload) {
+    const realmRoles = Array.isArray(payload.realm_access?.roles)
+        ? (payload.realm_access?.roles ?? [])
+        : [];
+    const resourceRoles = Object.values(payload.resource_access ?? {}).flatMap((access) => (Array.isArray(access?.roles) ? access.roles.filter((role) => typeof role === 'string') : []));
+    return Array.from(new Set([...realmRoles, ...resourceRoles]));
+}
+export function hasAnyRole(roles, allowedRoles) {
+    if (!roles || roles.length === 0) {
+        return false;
+    }
+    return roles.some((role) => allowedRoles.includes(role));
+}
+export function hasAdminReadAccess(roles) {
+    return hasAnyRole(roles, READ_ONLY_ADMIN_ROLES);
+}
+export function hasFullAdminAccess(roles) {
+    return hasAnyRole(roles, FULL_ADMIN_ROLES);
+}
 export function parseAuthHeader(headers) {
     const auth = headers.authorization;
     if (!auth || !auth.startsWith('Bearer ')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mereb/shared-packages",
-  "version": "0.0.40",
+  "version": "0.0.42",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",