authorization-scope

This library helps to scope the json-web-token authentication with permissions returned from svc-auth

Installation

npm i @mcf/authorization-scope --save

or

yarn add @mcf/authorization-scope

Development

Use the Node.js version pinned in .nvmrc and Yarn Classic 1.22.22:

nvm install
nvm use
export COREPACK_PREFIX="$HOME/.local/share/authorization-scope/corepack"
export PATH="$COREPACK_PREFIX/bin:$PATH"
export COREPACK_ENABLE_AUTO_PIN=0
export COREPACK_DEFAULT_TO_LATEST=0
npm install --global --prefix "$COREPACK_PREFIX" [email protected]
corepack enable --install-directory "$COREPACK_PREFIX/bin" yarn
corepack install --global [email protected]
yarn install --frozen-lockfile
yarn lint
yarn test --runInBand
yarn build

Node.js 25 and later require installing Corepack explicitly. This setup installs Corepack and its Yarn shims under your home directory without requiring root access. The Corepack settings keep Yarn pinned without automatically modifying package.json. CI installs its tools and bootstrap caches in a per-job temporary directory so non-root runners can use the same pinned versions.

yarn lint runs ESLint, Prettier, and the TypeScript check. Use yarn lint:fix to apply lint fixes and formatting, or yarn format for formatting alone. Run yarn audit to check both runtime and development dependencies for known vulnerabilities.

Kotlin development

Use JDK 25 with JAVA_HOME pointing to that installation, and the repository's Gradle 9.5.1 wrapper (./gradlew). The Kotlin Gradle plugin and standard library are pinned to 2.4.10.

java -version
./gradlew --version
./gradlew --no-daemon check assemble

check runs tests and ktlint; assemble produces build/libs/authorization-scope-mutator.jar. Use ./gradlew --no-daemon ktlintFix to apply Kotlin formatting fixes. The JAR targets Java 25 and requires a Java 25 runtime; it is incompatible with Java 8, 11, 17, and 21.

This producer uses jose4j 0.9.7. svcAuth's parent-first classloader still supplies jose4j 0.9.6 until svcAuth's own dependency upgrade. The test task includes host-fixture integration tests for both versions to check that compatibility.

Test dependencies use the JUnit 6.1.3 and Jackson 2.22.2 BOMs, with JaCoCo 0.8.15 for coverage. Formatting uses ktlint-cli 1.8.0 with Logback 1.6.3 isolated to its tool classpath.

CI dependency cache

Node.js

Node jobs cache Yarn dependency downloads in .yarn-cache/. The cache key uses the contents of package.json and yarn.lock, with a Node/Yarn toolchain prefix. Rebases and force-pushes with identical dependency files can reuse the same cache; changed dependency files use a different key.

Every Node job runs yarn install --frozen-lockfile --non-interactive to create its own node_modules, so a cache miss only requires downloading dependencies. The dependencies setup job uploads the cache; test, lint, and publish jobs only restore it. When changing the Node/Yarn toolchain or cache layout, update the cache-key prefix in .gitlab-ci.yml as well.

Kotlin / Gradle

Kotlin jobs use a digest-pinned Temurin JDK 25.0.4+7 image on Ubuntu Jammy from the public ECR Docker Official Images mirror, together with the repository's Gradle 9.5.1 wrapper. Their writable GRADLE_USER_HOME is $CI_PROJECT_DIR/.gradle, including on non-root runners. Per-command kotlin.user.home and kotlin.project.persistent.dir properties keep Kotlin's user and project state under .gradle/kotlin/. Each Kotlin job creates .gradle/xdg-data/ and sets its XDG_DATA_HOME there so the compiler daemon's runtime files are writable too. If HOME is unset, missing, or unwritable, the job uses .gradle/home/ for a writable home, including Java user preferences. This job-local Kotlin state is separate from the exported dependency snapshot.

Only dependencies_kotlin_tools uploads the wrapper cache; other Kotlin jobs pull it. Each setup job uploads only its own dependency cache, and only the unit-test job uploads the task-output cache. Node jobs do not download Kotlin artifacts. Wrapper cache keys use gradle/wrapper/gradle-wrapper.properties; dependency and task-output keys also use build.gradle, with gradle-9.5.1-temurin-25-jammy- toolchain prefixes. The dependencies-tools-v2 and dependencies-core-v2 suffixes isolate the profiles from each other and from the old full-dependency cache, which would inflate the exports. Wrapper and task-output caches have separate suffixes. Gradle additionally checks task inputs, including source files, before reusing outputs. Update the relevant cache-key prefixes when changing the image/toolchain or cache layout. A shared GitLab runner cache improves reuse between pipelines; artifacts provide the Maven dependency handoff within each pipeline.