myfirstdemoprojectkulliax 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ankul
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,255 @@
+# cds-csrf-cache
+
+A CAP plugin that caches the CSRF token for every destination-backed S/4 remote service, instead
+of letting a fresh token be fetched on every single write.
+
+## Why
+
+The SAP Cloud SDK's CSRF middleware (used internally by `cds.RemoteService` for a destination with
+`csrf` configured) fetches a brand-new token before every non-GET request. S/4 tokens are valid for
+30 minutes, so almost all of those fetches are redundant - they just double the number of requests
+sent for every `POST`/`PUT`/`DELETE`.
+
+This plugin fetches the token once, keeps it in memory, and refreshes it proactively in the
+background before it expires, so request-path latency no longer includes a token fetch except for
+the very first request after startup (or after an unexpected rejection).
+
+## How it works
+
+- **`CsrfTokenCache`** (`src/CsrfTokenCache.ts`) is the actual cache. It is framework-agnostic - it
+  only needs an async `fetchToken()` function and knows nothing about HTTP or CAP. It:
+  - serves the cached token as long as it is within `validitySeconds` of being fetched,
+  - schedules a background refresh `bufferSeconds` before that limit, so the buffer only decides
+    *when* to refresh early - it does not shrink how long a token may still be used if that
+    background refresh fails; the cache keeps serving the last known token until the real
+    `validitySeconds` limit is hit,
+  - deduplicates concurrent callers into a single in-flight fetch,
+  - exposes `invalidate()` for a caller that learns the token was rejected out of band.
+
+- **Two independent token-fetch implementations** plug into that cache, matching how the SAP Cloud
+  SDK and native `fetch` are already treated as separate paths elsewhere in this project - they are
+  never merged into one "smart" client:
+  - `buildCsrfTokenFetcher` (`src/csrfFetch.ts`) uses Node's native `fetch` directly against a plain
+    URL. It has no SAP Cloud SDK or CAP dependency and works against any plain HTTP(S) endpoint -
+    the piece to reach for outside of any CAP service.
+  - `buildCapDestinationCsrfTokenFetcher` (`src/capDestinationTokenFetcher.ts`) is what
+    `attachCsrfCache` uses for a connected `cds.RemoteService`. It does **not** hardcode a client:
+    it reuses CAP's own `shouldUseCloudSdk()` decision
+    (`@sap/cds/libx/_runtime/remote/utils/cloudSdkProvider.js`) - the same function
+    `cds.RemoteService` itself calls for every other request against that destination - and picks
+    the SAP Cloud SDK or CAP's own native-fetch executor accordingly. A BTP destination that routes
+    through Cloud Connector (on-premise) or requires a client certificate always resolves to the
+    Cloud SDK here too, for the same reason `cds.RemoteService` always uses it for that destination:
+    that connectivity configuration only resolves into an Axios/Node-`https.Agent` shape, which
+    native `fetch` (undici) cannot consume. Both `@sap/cds` internals this reaches into are
+    exported-but-undocumented; if a future `@sap/cds` release moves them, the require fails
+    gracefully and the fetcher tries the Cloud SDK first instead.
+
+  The SAP Cloud SDK itself stays optional throughout, exactly as it is for `@sap/cds` - a project
+  that only talks to plain/local destinations can run without `@sap-cloud-sdk/http-client` installed
+  at all. `@sap-cloud-sdk/http-client` is only ever `require()`'d lazily, at the point a token fetch
+  actually needs it, never as a static import; if it isn't installed, CAP's own `shouldUseCloudSdk()`
+  already says so (via its own `isCloudSdkInstalled()` check) and the token fetch goes through native
+  fetch instead - the plugin's `package.json` marks it an optional peer dependency accordingly.
+
+- **`createCsrfFetch`** (`src/csrfFetch.ts`) wraps any fetch-compatible function so every mutating
+  request is armed with the cached token (and its session cookie), and retried exactly once with a
+  freshly fetched token if the backend answers `403` + `x-csrf-token: Required`. This half is fully
+  usable on its own, outside of CAP, against any endpoint reachable via native `fetch`.
+
+- **`attachCsrfCache`** (`src/attachCsrfCache.ts`) is the CAP-specific glue for a `cds.RemoteService`:
+  it registers a `before("*")` handler that injects the cached token/cookie into every non-safe
+  (non-`GET`/`HEAD`) outgoing request, and wraps `send()` so a `403` CSRF rejection invalidates the
+  cache and retries once. It reads the very same `csrf` config CAP itself reads
+  (`.cdsrc.json`'s `requires.<service>.csrf`, a sibling of `credentials` - see Configuration below).
+
+- **`src/sharedCsrfCaches.ts`** is the registry behind `csrf.share`: instead of one cache per service,
+  every service on the same destination can be handed *one* `CsrfTokenCache`, so a single token
+  fetch serves all of them - and a token rejected on one of them is refreshed once for all of them.
+  An S/4 CSRF token is bound to the HTTP session behind the destination, not to the OData service
+  path it was fetched from, which is what makes this valid; see Configuration below for what
+  exactly has to match before two services are allowed to share.
+
+- **`cds-plugin.js`** is the actual CAP plugin entry point. CAP auto-detects and loads it for every
+  package listed as a dependency that has this exact file name next to its `package.json`. It
+  listens for the `served` lifecycle event and calls `attachCsrfCache` on every connected
+  `cds.RemoteService` that has a destination and a `csrf` configuration - no service needs to call
+  anything itself. A service without that configuration, or with `csrf.cache: false`, is left
+  untouched (e.g. a `--with-mocks` stand-in used in dev/test). It `require`s the implementation
+  lazily, inside that handler, and never at load time: `cds-env` requires this file in *every*
+  tool that merely loads `@sap/cds` - `cds-typer`, `cds build`, eslint - and those run in a plain
+  CJS runtime, so a top-level `require` of the compiled implementation would run just as well, but
+  the lazy load also means a consuming project that pulls in this package before its `lib/` build
+  output exists (e.g. a `file:`/git dependency checked out from source) fails gracefully instead of
+  taking the whole host application down with it.
+
+## Setup
+
+1. Install the package:
+   ```sh
+   npm install cds-csrf-cache
+   ```
+   CAP auto-detects the `cds-plugin.js` next to its `package.json` in `node_modules` - this is what
+   makes the plugin loader discover it, no further wiring required.
+2. Every remote service already configured with a destination and a `csrf` entry (`.cdsrc.json`'s
+   `requires.<service>.csrf`, either `{ "url": "..." }` or `true`) picks up the cache automatically
+   the next time the server starts.
+
+## Sample application
+
+[`sample/`](sample/) is a minimal runnable CAP app that uses this plugin against a fake CSRF-protected
+backend - see [`sample/README.md`](sample/README.md) for how to run it and what to look at.
+
+## Configuration
+
+### Per-service, via the existing `csrf` config
+
+This plugin extends the very `csrf` object CAP itself already reads
+(`.cdsrc.json`'s `requires.<service>.csrf`) with three extra, plugin-specific settings:
+
+```json
+{
+  "requires": {
+    "zsd_o2c_order_processing": {
+      "csrf": {
+        "method": "get",
+        "url": "/sap/opu/odata4/.../zsd_o2c_order_processing/0001/",
+        "cache": true,
+        "validitySeconds": 1500,
+        "autoRefresh": true,
+        "share": true
+      }
+    }
+  }
+}
+```
+
+| Field             | Read by      | Meaning                                                                                   |
+|-------------------|--------------|--------------------------------------------------------------------------------------------|
+| `url`             | CAP          | Path the CSRF preflight is sent to.                                                        |
+| `method`          | CAP + plugin | Verb for the preflight. CAP itself defaults to `head` if unset; this plugin defaults to `get` (broader OData compatibility) when it isn't given. |
+| `cache`           | plugin only  | Set to `false` to leave this service on CAP's default per-request CSRF handling instead of caching. Defaults to `true`. |
+| `validitySeconds` | plugin only  | How long a fetched token is trusted before this plugin proactively re-fetches it. Falls back to the environment variable / hardcoded default below when unset. |
+| `autoRefresh`     | plugin only  | Set to `false` to only fetch a replacement token lazily, on the first request after it went stale, instead of proactively in the background. Defaults to `true`. |
+| `share`           | plugin only  | Set to `true` to share one cached token with every other service on the same destination instead of caching one per service, or to a string to share only within that named group. Defaults to the `csrf_token_share` environment variable, i.e. to `false`. |
+
+`csrf: true` (no object, e.g. `zapi_sales_order_srv`) is also supported, exactly like CAP's own
+default: the fetch URL falls back to the service's `credentials.path`, and every plugin-only field
+falls back to its default.
+
+### One token for several services on the same destination (`share`)
+
+By default every remote service keeps a token of its own - four services on `s4-o2c-100` mean four
+token fetches, four background refreshes, and four separate recoveries after an expiry. `share`
+collapses those into one:
+
+```json
+{
+  "requires": {
+    "zsd_o2c_order_processing": { "csrf": { "url": "...", "share": true } },
+    "api_purchaseorder_2":      { "csrf": { "url": "...", "share": true } },
+    "api_purchaserequisition_2":{ "csrf": { "url": "...", "share": true } },
+    "zapi_sales_order_srv":     { "csrf": { "url": "...", "share": true } }
+  }
+}
+```
+
+This is safe because an S/4 CSRF token is bound to the HTTP session behind the destination, not to
+the OData service path it was fetched from: a token fetched via `zsd_o2c_order_processing`'s URL is
+accepted on `api_purchaseorder_2` just as well, as long as both requests really run against the
+same session. Two services therefore only share when **all** of this matches:
+
+- the **destination name** (`credentials.destination`) - a token from another system or another
+  backend client is not valid, and is never shared across destinations, even with `share: true` on
+  both sides;
+- the **`destinationOptions`** - they decide which concrete destination, and therefore which
+  backend user/session, a destination *name* resolves to (`selectionStrategy`, `jwt`, ...); a
+  different resolution can mean a different session, so it counts as a different token. The
+  comparison is order-insensitive, so writing the same options in a different order still shares;
+- the **share group**, if used: `"share": "writes"` shares only with other services configured with
+  exactly that name. Use it to keep one service's token separate while the rest share one, e.g.
+  when two services on one destination address different backend clients.
+
+The first service served creates the shared cache, and its `url`, `method`, `validitySeconds` and
+`autoRefresh` are the ones the shared cache runs with; a service joining with different settings is
+served the existing cache and logged as a warning (a second cache on the same destination is exactly
+what `share` was turned on to avoid). Consequently `invalidate()` after a `403` on *any* of the
+participating services refreshes the token for all of them.
+
+Turn it on for everything at once - without touching each service - with the `csrf_token_share`
+environment variable below. A single service can still opt out again with `"share": false`.
+
+### Environment-wide defaults
+
+Used whenever a service's `csrf` config doesn't set the corresponding field:
+
+| Environment variable          | Default | Meaning                                                            |
+|--------------------------------|---------|---------------------------------------------------------------------|
+| `csrf_token_validity_seconds` | `1800`  | How long a token stays valid on the backend (S/4 default: 30 min)   |
+| `csrf_token_buffer_seconds`   | `60`    | How long before that limit the cache proactively refreshes          |
+| `csrf_token_share`            | `false` | Default for `csrf.share` - set to `true`/`1`/`yes`/`on` to let all services of a destination share one token |
+
+### Programmatic override
+
+For cases the config can't express (mainly tests), pass options directly to `attachCsrfCache` - they
+win over both the `csrf` config and the environment defaults:
+
+```ts
+import { attachCsrfCache } from "cds-csrf-cache"
+
+attachCsrfCache(srv, { validitySeconds: 900, bufferSeconds: 30, share: true })
+```
+
+`share` works the same way here as in the config, and wins over it - `{ share: false }` keeps a
+service on its own cache even though its `csrf` config asks for a shared one. `resetSharedCsrfCaches()`
+disposes every shared cache and empties the registry; tests that attach shared caches should call it
+between cases.
+
+## Using the native-fetch half directly
+
+Outside of any CAP service - e.g. a plain script or a non-CAP integration - the cache and the
+native-fetch adapter can be used standalone:
+
+```ts
+import { CsrfTokenCache, buildCsrfTokenFetcher, createCsrfFetch } from "cds-csrf-cache"
+
+const cache = new CsrfTokenCache(buildCsrfTokenFetcher("https://example.com/service/"))
+const protectedFetch = createCsrfFetch(cache)
+
+await protectedFetch("https://example.com/service/Entities", { method: "POST", body: "{}" })
+```
+
+## Tests
+
+- `test/*.spec.ts` - unit tests (Vitest, run via `npm test`), covering the cache's timing
+  behavior (caching, proactive refresh, hard expiry, invalidate, concurrent dedup), the native-fetch
+  adapter, the CAP-client selection in `capDestinationTokenFetcher`, the shared-cache registry
+  (scope identity, first-one-wins, reset) in `sharedCsrfCaches`, and the CAP wiring (config
+  parsing, header injection, retry-on-403, sharing) in `attachCsrfCache`.
+- `test/CsrfCache.e2e.test.ts` - an end-to-end test (run via `npm run test.e2e`) that exercises
+  `CsrfTokenCache` and `createCsrfFetch` against a real local HTTP server standing in for an S/4
+  gateway, over real sockets and real timers: caching across repeated requests, a timed proactive
+  refresh, and recovery from an out-of-band token rejection.
+
+## Development
+
+- `npm run build` compiles `src/**/*.ts` to `lib/` (the shipped `main`/`types` entry point and what
+  `cds-plugin.js` requires at runtime) via `tsc`. `npm publish` runs it automatically
+  (`prepublishOnly`).
+- `npm test` / `npm run test.e2e` run straight against the TypeScript sources in `src/` via Vitest -
+  no build needed for that.
+
+## Release
+
+`.github/workflows/publish.yml` runs the test suite (Node 22/24) on every push and pull request
+against `main`, and additionally publishes to npm when a tag matching `v*.*.*` is pushed:
+
+1. Bump `version` in `package.json` (e.g. `npm version minor`, which also creates the matching git
+   tag).
+2. Push the commit and the tag: `git push && git push --tags`.
+3. The `publish` job checks the pushed tag against `package.json`'s version, builds, and runs
+   `npm publish --provenance --access public`.
+
+This requires an `NPM_TOKEN` repository secret - an npm automation token with publish rights for
+`cds-csrf-cache` - and, since `--provenance` is used, the workflow running from this repository on
+GitHub (provenance ties the published package to the exact commit/workflow run that built it).

package/cds-plugin.js

@@ -0,0 +1,31 @@
+// Auto-detected and loaded by CAP's plugin loader (`cds serve` / `cds watch`) because this package
+// is listed as a dependency and provides this exact file name next to its package.json
+// (see capire docs "CDS Plugin Packages"). Wires the csrf token cache into every served
+// destination-backed remote service - no service needs to call the plugin itself.
+const cds = require("@sap/cds")
+
+/**
+ * Loaded lazily, inside the `served` handler, and never at plugin-load time: this file is required
+ * by `cds-env` itself, i.e. by *every* tool that merely loads `@sap/cds` - `cds-typer`, `cds build`,
+ * eslint - and those load it in a plain CJS runtime with no TypeScript loader registered, where a
+ * top-level `require` of the compiled `./lib/attachCsrfCache.js` would otherwise run just as well,
+ * but wrapping it keeps a missing/un-built `lib/` (e.g. before this package's own `npm run build`
+ * has ever run) from taking down the whole host application - it just leaves CAP's default
+ * per-request csrf handling in place.
+ */
+function loadAttachCsrfCache() {
+    try {
+        return require("./lib/attachCsrfCache").attachCsrfCache
+    } catch (error) {
+        cds.log("csrf-cache").error("could not load the csrf token cache, remote services keep CAP's per-request csrf handling", error)
+        return undefined
+    }
+}
+
+cds.on("served", all => {
+    const attachCsrfCache = loadAttachCsrfCache()
+    if (!attachCsrfCache) return
+
+    for (const srv of Object.values(all))
+        if (srv instanceof cds.RemoteService) attachCsrfCache(srv)
+})

package/lib/CsrfTokenCache.d.ts

@@ -0,0 +1,56 @@
+export type CsrfToken = {
+    token: string;
+    cookies: string[];
+};
+export type CsrfTokenFetcher = () => Promise<CsrfToken>;
+export type CsrfTokenCacheOptions = {
+    /** How long a token stays valid on the backend, in seconds. S/4 defaults to 1800 (30 minutes). */
+    validitySeconds?: number;
+    /** How long before `validitySeconds` runs out the cache proactively re-fetches in the background. */
+    bufferSeconds?: number;
+    /** Proactively re-fetch `bufferSeconds` before expiry instead of only fetching lazily on demand. Defaults to `true`. */
+    autoRefresh?: boolean;
+};
+/** Shared by every token-fetch implementation and by `attachCsrfCache`'s 403 detection, so the header name and its "Required" rejection value are spelled out exactly once. */
+export declare const CSRF_TOKEN_HEADER = "x-csrf-token";
+/** A cookie's path/domain/etc. attributes are not valid in a request `Cookie` header - only `name=value` survives. */
+export declare function toCookieHeader(cookies: string[]): string | undefined;
+/** True for the exact rejection S/4 (and CAP itself) use to signal an expired/invalid token: `403` + `x-csrf-token: Required`. */
+export declare function isCsrfRequiredRejection(status: number | undefined, csrfTokenHeaderValue: string | null | undefined): boolean;
+/** Thrown by every token-fetch implementation when the preflight didn't come back with a usable token - one wording, so the two call sites can't drift apart. */
+export declare function missingCsrfTokenError(url: string, status: number): Error;
+/**
+ * Caches a CSRF token obtained from `fetchToken` and proactively re-fetches it `bufferSeconds`
+ * before `validitySeconds` (the backend-side lifetime, 30 minutes on S/4) runs out - the buffer is
+ * only a safety margin for *when* to refresh early, not a cut into the token's usable lifetime:
+ * `getToken()` keeps serving the last known token up to the full `validitySeconds`, even if a
+ * background refresh attempt failed, and only fetches synchronously once that hard limit is hit.
+ * Concurrent `getToken()` calls share a single in-flight fetch.
+ *
+ * Framework-agnostic by design: `fetchToken` can be backed by native `fetch` ({@link buildCsrfTokenFetcher})
+ * or by a connected `cds.RemoteService`'s destination ({@link buildCapDestinationCsrfTokenFetcher}) -
+ * the cache itself has no HTTP dependency.
+ */
+export declare class CsrfTokenCache {
+    private readonly log;
+    private readonly validitySeconds;
+    private readonly bufferSeconds;
+    private readonly autoRefresh;
+    private readonly fetchToken;
+    private cached?;
+    private pending?;
+    private refreshTimer?;
+    constructor(fetchToken: CsrfTokenFetcher, options?: CsrfTokenCacheOptions);
+    /** Returns a valid token, fetching (and caching) one first if necessary - and logs which of the two it was, so the cache's effect is visible in the request log. */
+    getToken(): Promise<CsrfToken>;
+    /** Drops the cached token, forcing the next `getToken()` call to fetch a fresh one. */
+    invalidate(): void;
+    /** Clears the proactive refresh timer. Call on shutdown/in tests so the process/test can exit cleanly. */
+    dispose(): void;
+    /** Shared by `getToken()` and the proactive refresh timer, so a request racing the timer joins the same fetch - and logs whether it started that fetch or joined a running one. */
+    private triggerRefresh;
+    private refresh;
+    private scheduleRefresh;
+    private clearRefreshTimer;
+}
+//# sourceMappingURL=CsrfTokenCache.d.ts.map

package/lib/CsrfTokenCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"CsrfTokenCache.d.ts","sourceRoot":"","sources":["../src/CsrfTokenCache.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,SAAS,GAAG;IACpB,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,MAAM,EAAE,CAAA;CACpB,CAAA;AAED,MAAM,MAAM,gBAAgB,GAAG,MAAM,OAAO,CAAC,SAAS,CAAC,CAAA;AAEvD,MAAM,MAAM,qBAAqB,GAAG;IAChC,kGAAkG;IAClG,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,qGAAqG;IACrG,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,wHAAwH;IACxH,WAAW,CAAC,EAAE,OAAO,CAAA;CACxB,CAAA;AAID,+KAA+K;AAC/K,eAAO,MAAM,iBAAiB,iBAAiB,CAAA;AAE/C,sHAAsH;AACtH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAEpE;AAED,kIAAkI;AAClI,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,EAAE,oBAAoB,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAE5H;AAED,iKAAiK;AACjK,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAExE;AAKD;;;;;;;;;;;GAWG;AACH,qBAAa,cAAc;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA4B;IAChD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAQ;IACxC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAQ;IACtC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IAErC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAkB;IAC7C,OAAO,CAAC,MAAM,CAAC,CAAa;IAC5B,OAAO,CAAC,OAAO,CAAC,CAAoB;IACpC,OAAO,CAAC,YAAY,CAAC,CAA+B;gBAExC,UAAU,EAAE,gBAAgB,EAAE,OAAO,GAAE,qBAA0B;IAW7E,oKAAoK;IAC9J,QAAQ,IAAI,OAAO,CAAC,SAAS,CAAC;IAQpC,uFAAuF;IACvF,UAAU,IAAI,IAAI;IAKlB,0GAA0G;IAC1G,OAAO,IAAI,IAAI;IAIf,mLAAmL;IACnL,OAAO,CAAC,cAAc;YAUR,OAAO;IASrB,OAAO,CAAC,eAAe;IAYvB,OAAO,CAAC,iBAAiB;CAI5B"}

package/lib/CsrfTokenCache.js

@@ -0,0 +1,108 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CsrfTokenCache = exports.CSRF_TOKEN_HEADER = void 0;
+exports.toCookieHeader = toCookieHeader;
+exports.isCsrfRequiredRejection = isCsrfRequiredRejection;
+exports.missingCsrfTokenError = missingCsrfTokenError;
+const cds_1 = __importDefault(require("@sap/cds"));
+/** Shared by every token-fetch implementation and by `attachCsrfCache`'s 403 detection, so the header name and its "Required" rejection value are spelled out exactly once. */
+exports.CSRF_TOKEN_HEADER = "x-csrf-token";
+/** A cookie's path/domain/etc. attributes are not valid in a request `Cookie` header - only `name=value` survives. */
+function toCookieHeader(cookies) {
+    return cookies.length ? cookies.map(cookie => cookie.split(";")[0]).join("; ") : undefined;
+}
+/** True for the exact rejection S/4 (and CAP itself) use to signal an expired/invalid token: `403` + `x-csrf-token: Required`. */
+function isCsrfRequiredRejection(status, csrfTokenHeaderValue) {
+    return status === 403 && csrfTokenHeaderValue?.toLowerCase() === "required";
+}
+/** Thrown by every token-fetch implementation when the preflight didn't come back with a usable token - one wording, so the two call sites can't drift apart. */
+function missingCsrfTokenError(url, status) {
+    return new Error(`Could not obtain a CSRF token from ${url} (HTTP ${status})`);
+}
+const DEFAULT_VALIDITY_SECONDS = Number(process.env.csrf_token_validity_seconds ?? 1800);
+const DEFAULT_BUFFER_SECONDS = Number(process.env.csrf_token_buffer_seconds ?? 60);
+/**
+ * Caches a CSRF token obtained from `fetchToken` and proactively re-fetches it `bufferSeconds`
+ * before `validitySeconds` (the backend-side lifetime, 30 minutes on S/4) runs out - the buffer is
+ * only a safety margin for *when* to refresh early, not a cut into the token's usable lifetime:
+ * `getToken()` keeps serving the last known token up to the full `validitySeconds`, even if a
+ * background refresh attempt failed, and only fetches synchronously once that hard limit is hit.
+ * Concurrent `getToken()` calls share a single in-flight fetch.
+ *
+ * Framework-agnostic by design: `fetchToken` can be backed by native `fetch` ({@link buildCsrfTokenFetcher})
+ * or by a connected `cds.RemoteService`'s destination ({@link buildCapDestinationCsrfTokenFetcher}) -
+ * the cache itself has no HTTP dependency.
+ */
+class CsrfTokenCache {
+    log;
+    validitySeconds;
+    bufferSeconds;
+    autoRefresh;
+    fetchToken;
+    cached;
+    pending;
+    refreshTimer;
+    constructor(fetchToken, options = {}) {
+        this.fetchToken = fetchToken;
+        this.validitySeconds = options.validitySeconds ?? DEFAULT_VALIDITY_SECONDS;
+        this.bufferSeconds = options.bufferSeconds ?? DEFAULT_BUFFER_SECONDS;
+        this.autoRefresh = options.autoRefresh ?? true;
+        this.log = cds_1.default.log("csrf-cache");
+        if (this.bufferSeconds < 0 || this.bufferSeconds >= this.validitySeconds)
+            throw new Error(`csrf token buffer (${this.bufferSeconds}s) must be >= 0 and smaller than its validity (${this.validitySeconds}s)`);
+    }
+    /** Returns a valid token, fetching (and caching) one first if necessary - and logs which of the two it was, so the cache's effect is visible in the request log. */
+    async getToken() {
+        if (this.cached && this.cached.expiresAt > Date.now()) {
+            this.log.debug(`csrf token taken from cache, valid until ${new Date(this.cached.expiresAt).toISOString()}`);
+            return this.cached;
+        }
+        return this.triggerRefresh();
+    }
+    /** Drops the cached token, forcing the next `getToken()` call to fetch a fresh one. */
+    invalidate() {
+        this.cached = undefined;
+        this.clearRefreshTimer();
+    }
+    /** Clears the proactive refresh timer. Call on shutdown/in tests so the process/test can exit cleanly. */
+    dispose() {
+        this.clearRefreshTimer();
+    }
+    /** Shared by `getToken()` and the proactive refresh timer, so a request racing the timer joins the same fetch - and logs whether it started that fetch or joined a running one. */
+    triggerRefresh() {
+        if (this.pending) {
+            this.log.debug("csrf token fetch already in flight, joining it");
+            return this.pending;
+        }
+        this.log.debug("requesting a new csrf token");
+        return this.pending = this.refresh().finally(() => { this.pending = undefined; });
+    }
+    async refresh() {
+        const fetchedAt = Date.now();
+        const token = await this.fetchToken();
+        this.cached = { ...token, expiresAt: fetchedAt + this.validitySeconds * 1000 };
+        this.log.info(`fetched a new csrf token, valid until ${new Date(this.cached.expiresAt).toISOString()}`);
+        this.scheduleRefresh(fetchedAt);
+        return this.cached;
+    }
+    scheduleRefresh(fetchedAt) {
+        this.clearRefreshTimer();
+        if (!this.autoRefresh)
+            return;
+        const refreshAt = fetchedAt + (this.validitySeconds - this.bufferSeconds) * 1000;
+        this.refreshTimer = setTimeout(() => {
+            this.triggerRefresh().catch(error => this.log.warn("proactive csrf token refresh failed, keeping the last known token until it expires", error));
+        }, Math.max(0, refreshAt - Date.now()));
+        this.refreshTimer.unref?.();
+    }
+    clearRefreshTimer() {
+        if (this.refreshTimer)
+            clearTimeout(this.refreshTimer);
+        this.refreshTimer = undefined;
+    }
+}
+exports.CsrfTokenCache = CsrfTokenCache;
+//# sourceMappingURL=CsrfTokenCache.js.map

package/lib/CsrfTokenCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CsrfTokenCache.js","sourceRoot":"","sources":["../src/CsrfTokenCache.ts"],"names":[],"mappings":"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"}

package/lib/attachCsrfCache.d.ts

@@ -0,0 +1,29 @@
+import cds from "@sap/cds";
+import { CsrfTokenCache, CsrfTokenCacheOptions } from "./CsrfTokenCache";
+/**
+ * Programmatic overrides for {@link attachCsrfCache} - the cache's own timing options, plus this
+ * plugin's `share` switch, which the `csrf` config expresses as `csrf.share`.
+ */
+export type AttachCsrfCacheOptions = CsrfTokenCacheOptions & {
+    /** Overrides `csrf.share` for this service: share the destination's token cache (optionally within the named group) instead of caching a token of its own. */
+    share?: boolean | string;
+};
+/**
+ * Attaches a {@link CsrfTokenCache} to a connected `cds.RemoteService`: caches the CSRF token
+ * instead of letting CAP fetch a fresh one on every write (its csrf middleware - Cloud SDK or
+ * native fetch alike - only skips its own preflight once `x-csrf-token` is already present on the
+ * outgoing request), and retries once, with a fresh token, if the backend ever rejects the cached
+ * one as expired.
+ *
+ * A service without a destination, without any `csrf` configuration, or with `csrf.cache: false`
+ * (e.g. a `--with-mocks` stand-in used in dev/test) is left untouched - there is nothing to cache a
+ * token for, or the config explicitly opted out. Called automatically by this package's
+ * `cds-plugin.js` for every served remote service; only call it directly for a service the plugin's
+ * auto-discovery does not reach (e.g. a service served in a separate process).
+ *
+ * With `csrf.share` (or `options.share`) turned on, the service does not get a cache of its own but
+ * joins the one shared by every other service on the same destination - one token fetch for all of
+ * them instead of one each; see {@link acquireSharedCsrfCache}.
+ */
+export declare function attachCsrfCache(srv: cds.RemoteService, options?: AttachCsrfCacheOptions): CsrfTokenCache | undefined;
+//# sourceMappingURL=attachCsrfCache.d.ts.map

package/lib/attachCsrfCache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachCsrfCache.d.ts","sourceRoot":"","sources":["../src/attachCsrfCache.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,UAAU,CAAA;AAC1B,OAAO,EAAqB,cAAc,EAAE,qBAAqB,EAA2C,MAAM,kBAAkB,CAAA;AAgDpI;;;GAGG;AACH,MAAM,MAAM,sBAAsB,GAAG,qBAAqB,GAAG;IACzD,8JAA8J;IAC9J,KAAK,CAAC,EAAE,OAAO,GAAG,MAAM,CAAA;CAC3B,CAAA;AAiCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,aAAa,EAAE,OAAO,GAAE,sBAA2B,GAAG,cAAc,GAAG,SAAS,CA6DxH"}

package/lib/attachCsrfCache.js

@@ -0,0 +1,126 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.attachCsrfCache = attachCsrfCache;
+const cds_1 = __importDefault(require("@sap/cds"));
+const CsrfTokenCache_1 = require("./CsrfTokenCache");
+const capDestinationTokenFetcher_1 = require("./capDestinationTokenFetcher");
+const sharedCsrfCaches_1 = require("./sharedCsrfCaches");
+const LOG = cds_1.default.log("csrf-cache");
+const SAFE_METHODS = new Set(["GET", "HEAD"]);
+/** Environment-wide default for `csrf.share`, so all services of a destination can be switched to one token without touching each of them. */
+const DEFAULT_SHARE = /^(true|1|yes|on)$/i.test(process.env.csrf_token_share ?? "");
+/** `csrf.share` as a boolean plus an optional group name; an empty/whitespace-only string is treated as a plain `true`, not as a group called "". */
+function resolveShare(share) {
+    if (share === undefined)
+        return { enabled: DEFAULT_SHARE };
+    if (typeof share === "string") {
+        const group = share.trim();
+        return group ? { enabled: true, group } : { enabled: true };
+    }
+    return { enabled: share };
+}
+/** The owner settings a shared cache actually runs with, so a service joining with different ones can be named in the warning. */
+function describeSettings(csrfUrl, method, csrfConfig) {
+    return `url=${csrfUrl}, method=${method}, validitySeconds=${csrfConfig.validitySeconds ?? "default"}, autoRefresh=${csrfConfig.autoRefresh ?? "default"}`;
+}
+/** `csrf: true` (zapi_sales_order_srv) has no explicit fetch URL - the service's own root path is used, matching CAP's own default. */
+function resolveCsrfConfig(srv) {
+    if (srv.csrf === true)
+        return { url: srv.path };
+    if (srv.csrf && typeof srv.csrf === "object")
+        return srv.csrf;
+    return undefined;
+}
+/** Only `get`/`head` make sense for a CSRF preflight; anything else falls back to `get`, same as an unset `csrf.method`. */
+function normalizeCsrfMethod(method) {
+    return method?.toLowerCase() === "head" ? "head" : "get";
+}
+function isCsrfRejection(error) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const response = error?.reason?.response;
+    const header = response?.headers?.[CsrfTokenCache_1.CSRF_TOKEN_HEADER] ?? response?.headers?.["X-CSRF-Token"];
+    return (0, CsrfTokenCache_1.isCsrfRequiredRejection)(response?.status, header);
+}
+/**
+ * Attaches a {@link CsrfTokenCache} to a connected `cds.RemoteService`: caches the CSRF token
+ * instead of letting CAP fetch a fresh one on every write (its csrf middleware - Cloud SDK or
+ * native fetch alike - only skips its own preflight once `x-csrf-token` is already present on the
+ * outgoing request), and retries once, with a fresh token, if the backend ever rejects the cached
+ * one as expired.
+ *
+ * A service without a destination, without any `csrf` configuration, or with `csrf.cache: false`
+ * (e.g. a `--with-mocks` stand-in used in dev/test) is left untouched - there is nothing to cache a
+ * token for, or the config explicitly opted out. Called automatically by this package's
+ * `cds-plugin.js` for every served remote service; only call it directly for a service the plugin's
+ * auto-discovery does not reach (e.g. a service served in a separate process).
+ *
+ * With `csrf.share` (or `options.share`) turned on, the service does not get a cache of its own but
+ * joins the one shared by every other service on the same destination - one token fetch for all of
+ * them instead of one each; see {@link acquireSharedCsrfCache}.
+ */
+function attachCsrfCache(srv, options = {}) {
+    const { share: shareOverride, ...cacheOptions } = options;
+    const internals = srv;
+    const csrfConfig = resolveCsrfConfig(internals);
+    if (!internals.destination || !csrfConfig?.url || csrfConfig.cache === false) {
+        LOG.debug(`service '${srv.name}' has no cacheable destination-backed csrf configuration, skipping csrf token cache`);
+        return undefined;
+    }
+    const destination = internals.destination;
+    const destinationOptions = internals.destinationOptions ?? {};
+    const csrfUrl = csrfConfig.url;
+    const method = normalizeCsrfMethod(csrfConfig.method);
+    // Built inside `createCache` so a service that only joins an existing shared cache never
+    // constructs a token fetcher it would have no use for.
+    const createCache = () => new CsrfTokenCache_1.CsrfTokenCache((0, capDestinationTokenFetcher_1.buildCapDestinationCsrfTokenFetcher)(destination, destinationOptions, csrfUrl, method), {
+        validitySeconds: csrfConfig.validitySeconds,
+        autoRefresh: csrfConfig.autoRefresh,
+        ...cacheOptions
+    });
+    const share = resolveShare(shareOverride ?? csrfConfig.share);
+    const shared = share.enabled
+        ? (0, sharedCsrfCaches_1.acquireSharedCsrfCache)({ destination, destinationOptions, group: share.group }, srv.name, describeSettings(csrfUrl, method, csrfConfig), createCache)
+        : undefined;
+    const cache = shared?.cache ?? createCache();
+    srv.before("*", async (req) => {
+        if (SAFE_METHODS.has((req.method ?? "").toUpperCase()))
+            return;
+        try {
+            const token = await cache.getToken();
+            req.headers ??= {};
+            req.headers[CsrfTokenCache_1.CSRF_TOKEN_HEADER] = token.token;
+            const cookieHeader = (0, CsrfTokenCache_1.toCookieHeader)(token.cookies);
+            if (cookieHeader)
+                req.headers["cookie"] = cookieHeader;
+        }
+        catch (error) {
+            LOG.warn("could not obtain a cached csrf token, letting the request go through without one", error);
+        }
+    });
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const send = srv.send.bind(srv);
+    srv.send = (async (...args) => {
+        try {
+            return await send(...args);
+        }
+        catch (error) {
+            if (!isCsrfRejection(error))
+                throw error;
+            LOG.warn(`service '${srv.name}' rejected the cached csrf token as expired, refreshing and retrying once`);
+            cache.invalidate();
+            return await send(...args);
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    });
+    if (!shared)
+        LOG.info(`csrf token cache attached to service '${srv.name}'`);
+    else if (shared.joined)
+        LOG.info(`service '${srv.name}' joined the csrf token cache shared for destination '${destination}' (created by '${shared.owner}')`);
+    else
+        LOG.info(`csrf token cache attached to service '${srv.name}', shared with every other service on destination '${destination}'`);
+    return cache;
+}
+//# sourceMappingURL=attachCsrfCache.js.map

package/lib/attachCsrfCache.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachCsrfCache.js","sourceRoot":"","sources":["../src/attachCsrfCache.ts"],"names":[],"mappings":"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"}

package/lib/capDestinationTokenFetcher.d.ts

@@ -0,0 +1,30 @@
+import { CsrfTokenFetcher } from "./CsrfTokenCache";
+type NativeFetchResponse = {
+    data: unknown;
+    headers: Record<string, string | string[] | undefined>;
+    status: number;
+};
+type CloudSdkResponse = {
+    status: number;
+    headers: Record<string, string | string[] | undefined>;
+};
+type CloudSdkExecutor = (destination: unknown, requestConfig: unknown) => Promise<CloudSdkResponse>;
+export type CapInternals = {
+    shouldUseCloudSdk: (destination: unknown) => boolean;
+    nativeFetch: (destination: unknown, requestConfig: unknown) => Promise<NativeFetchResponse>;
+};
+export type CsrfPreflightMethod = "get" | "head";
+export type CapDestinationTokenFetcherOverrides = {
+    capInternals?: CapInternals | null;
+    cloudSdkFetch?: CloudSdkExecutor | null;
+};
+/**
+ * Builds a {@link CsrfTokenFetcher} for a connected `cds.RemoteService`'s destination, letting CAP's
+ * own `shouldUseCloudSdk()` decide between the SAP Cloud SDK and native `fetch` - see the module
+ * comment above for why that decision must not be hardcoded to one client, and why the Cloud SDK
+ * itself must stay optional. `overrides` exists so tests can supply fakes directly instead of
+ * mocking a runtime `require()` of a deep `node_modules` path.
+ */
+export declare function buildCapDestinationCsrfTokenFetcher(destination: string, destinationOptions: Record<string, unknown>, csrfUrl: string, method?: CsrfPreflightMethod, overrides?: CapDestinationTokenFetcherOverrides): CsrfTokenFetcher;
+export {};
+//# sourceMappingURL=capDestinationTokenFetcher.d.ts.map

package/lib/capDestinationTokenFetcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capDestinationTokenFetcher.d.ts","sourceRoot":"","sources":["../src/capDestinationTokenFetcher.ts"],"names":[],"mappings":"AACA,OAAO,EAAqB,gBAAgB,EAAyB,MAAM,kBAAkB,CAAA;AAI7F,KAAK,mBAAmB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AACpH,KAAK,gBAAgB,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAA;CAAE,CAAA;AAGlG,KAAK,gBAAgB,GAAG,CAAC,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,KAAK,OAAO,CAAC,gBAAgB,CAAC,CAAA;AAEnG,MAAM,MAAM,YAAY,GAAG;IACvB,iBAAiB,EAAE,CAAC,WAAW,EAAE,OAAO,KAAK,OAAO,CAAA;IACpD,WAAW,EAAE,CAAC,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAA;CAC9F,CAAA;AAsED,MAAM,MAAM,mBAAmB,GAAG,KAAK,GAAG,MAAM,CAAA;AAEhD,MAAM,MAAM,mCAAmC,GAAG;IAC9C,YAAY,CAAC,EAAE,YAAY,GAAG,IAAI,CAAA;IAClC,aAAa,CAAC,EAAE,gBAAgB,GAAG,IAAI,CAAA;CAC1C,CAAA;AAED;;;;;;GAMG;AACH,wBAAgB,mCAAmC,CAC/C,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC3C,OAAO,EAAE,MAAM,EACf,MAAM,GAAE,mBAA2B,EACnC,SAAS,GAAE,mCAAwC,GACpD,gBAAgB,CAwBlB"}

package/lib/capDestinationTokenFetcher.js

@@ -0,0 +1,103 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCapDestinationCsrfTokenFetcher = buildCapDestinationCsrfTokenFetcher;
+const cds_1 = __importDefault(require("@sap/cds"));
+const CsrfTokenCache_1 = require("./CsrfTokenCache");
+const LOG = cds_1.default.log("csrf-cache");
+/* eslint-enable no-unused-vars */
+/**
+ * `cds.RemoteService` decides per request whether to route through the SAP Cloud SDK or Node's
+ * native `fetch`, via `shouldUseCloudSdk()` in `@sap/cds/libx/_runtime/remote/utils/cloudSdkProvider.js`
+ * (a BTP destination without a locally-resolvable URL, or with anything other than Basic/No auth,
+ * always forces the Cloud SDK - that is what makes an on-premise/Cloud-Connector/mTLS destination
+ * safe to call at all, since only the Cloud SDK resolves that connectivity configuration).
+ *
+ * `buildCapDestinationCsrfTokenFetcher` reuses that exact decision instead of hardcoding a client,
+ * so the token fetch always goes through the same path CAP itself would pick for the real request
+ * on this service. Neither module is part of `@sap/cds`'s public entry point - both are
+ * internal-but-exported (`module.exports` on their own files, just not re-exported from `@sap/cds`'s
+ * `index.js`), so a future `@sap/cds` release could move them without a deprecation notice.
+ * `resolveCapInternals` isolates that risk: if the require ever fails, every caller falls back to
+ * treating the SAP Cloud SDK as the only option - the same one CAP would use once `useCloudSdk`
+ * can no longer be asked for.
+ */
+let capInternals;
+function resolveCapInternals() {
+    if (capInternals !== undefined)
+        return capInternals;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports -- must be a runtime require: not part of @sap/cds's public entry point, see the module comment above
+        const { shouldUseCloudSdk } = require("@sap/cds/libx/_runtime/remote/utils/cloudSdkProvider");
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { executeHttpRequest: nativeFetch } = require("@sap/cds/libx/_runtime/remote/utils/fetchClient");
+        return capInternals = { shouldUseCloudSdk, nativeFetch };
+    }
+    catch (error) {
+        LOG.warn("could not load @sap/cds's internal client-selection module, always trying the Cloud SDK first for csrf token fetches", error);
+        return capInternals = null;
+    }
+}
+/**
+ * The SAP Cloud SDK is an optional peer dependency, exactly as it is for `@sap/cds` itself
+ * (`cloudSdkProvider.js`'s `getCloudSdk()`/`isCloudSdkInstalled()`): a project that only talks to
+ * plain/local destinations can run without `@sap-cloud-sdk/http-client` installed at all, and
+ * `shouldUseCloudSdk()` already returns `false` in that case. A static top-level import of the
+ * package would defeat that - it fails at module load time regardless of whether this branch is
+ * ever taken - so this, too, is a lazy, cached, failure-tolerant require.
+ */
+let cloudSdkExecutor;
+function resolveCloudSdkExecutor() {
+    if (cloudSdkExecutor !== undefined)
+        return cloudSdkExecutor;
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const { executeHttpRequest } = require("@sap-cloud-sdk/http-client");
+        return cloudSdkExecutor = executeHttpRequest;
+    }
+    catch {
+        return cloudSdkExecutor = null;
+    }
+}
+function firstCookie(setCookie) {
+    if (!setCookie)
+        return [];
+    return Array.isArray(setCookie) ? setCookie : [setCookie];
+}
+function tokenFrom(headers, status, csrfUrl) {
+    const token = headers[CsrfTokenCache_1.CSRF_TOKEN_HEADER];
+    if (status !== 200 || typeof token !== "string")
+        throw (0, CsrfTokenCache_1.missingCsrfTokenError)(csrfUrl, status);
+    return { token, cookies: firstCookie(headers["set-cookie"]) };
+}
+/**
+ * Builds a {@link CsrfTokenFetcher} for a connected `cds.RemoteService`'s destination, letting CAP's
+ * own `shouldUseCloudSdk()` decide between the SAP Cloud SDK and native `fetch` - see the module
+ * comment above for why that decision must not be hardcoded to one client, and why the Cloud SDK
+ * itself must stay optional. `overrides` exists so tests can supply fakes directly instead of
+ * mocking a runtime `require()` of a deep `node_modules` path.
+ */
+function buildCapDestinationCsrfTokenFetcher(destination, destinationOptions, csrfUrl, method = "get", overrides = {}) {
+    const destinationRef = { destinationName: destination, ...destinationOptions };
+    const nativeMethod = method === "head" ? "HEAD" : "GET";
+    return async () => {
+        const internals = "capInternals" in overrides ? overrides.capInternals ?? null : resolveCapInternals();
+        // No way to ask CAP - default to trying the Cloud SDK first, same as when internals resolve fine and it turns out to be installed.
+        const useCloudSdk = internals ? internals.shouldUseCloudSdk(destination) : true;
+        if (useCloudSdk) {
+            const cloudSdkFetch = "cloudSdkFetch" in overrides ? overrides.cloudSdkFetch ?? null : resolveCloudSdkExecutor();
+            if (cloudSdkFetch) {
+                const response = await cloudSdkFetch(destinationRef, { method, url: csrfUrl, headers: { [CsrfTokenCache_1.CSRF_TOKEN_HEADER]: "Fetch" } });
+                return tokenFrom(response.headers, response.status, csrfUrl);
+            }
+        }
+        if (internals) {
+            const response = await internals.nativeFetch(destinationRef, { method: nativeMethod, url: csrfUrl, headers: { [CsrfTokenCache_1.CSRF_TOKEN_HEADER]: "Fetch" } });
+            return tokenFrom(response.headers, response.status, csrfUrl);
+        }
+        throw new Error(`Could not fetch a CSRF token from ${csrfUrl}: neither the SAP Cloud SDK nor @sap/cds's native fetch client is available.`);
+    };
+}
+//# sourceMappingURL=capDestinationTokenFetcher.js.map

package/lib/capDestinationTokenFetcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capDestinationTokenFetcher.js","sourceRoot":"","sources":["../src/capDestinationTokenFetcher.ts"],"names":[],"mappings":"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"}

package/lib/csrfFetch.d.ts

@@ -0,0 +1,23 @@
+import { CsrfTokenCache, CsrfTokenFetcher } from "./CsrfTokenCache";
+/**
+ * Native-`fetch` token fetcher - kept deliberately separate from {@link buildCapDestinationCsrfTokenFetcher}
+ * (see that module for why): this one has no SAP Cloud SDK dependency at all and works with any
+ * plain HTTP(S) endpoint reachable via Node's global `fetch`.
+ *
+ * Builds a {@link CsrfTokenFetcher}: a GET request carrying `x-csrf-token: Fetch` against `url`,
+ * answered with the token in the same response header and the session cookie(s) needed to present
+ * it back on the next write. GET (not HEAD) is used because it is the verb every SAP gateway/OData
+ * implementation is guaranteed to answer a CSRF-fetch on, including services that don't implement HEAD.
+ */
+export declare function buildCsrfTokenFetcher(url: string, init?: RequestInit, fetchImpl?: typeof fetch): CsrfTokenFetcher;
+/**
+ * Wraps a fetch-compatible function so every non-safe request is transparently armed with the
+ * cached CSRF token, and retried exactly once - with a freshly fetched token - if the backend
+ * rejects it as expired (`403` + `x-csrf-token: Required`). Safe methods pass through untouched.
+ *
+ * This is the piece that makes the cache usable with plain native `fetch` calls, independent of
+ * any CAP/Cloud SDK service - see {@link buildCsrfTokenFetcher} for a matching token fetcher, and
+ * `attachCsrfCache` for the equivalent wiring against a `cds.RemoteService`.
+ */
+export declare function createCsrfFetch(cache: CsrfTokenCache, fetchImpl?: typeof fetch): typeof fetch;
+//# sourceMappingURL=csrfFetch.d.ts.map

package/lib/csrfFetch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrfFetch.d.ts","sourceRoot":"","sources":["../src/csrfFetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAgC,cAAc,EAAE,gBAAgB,EAAkE,MAAM,kBAAkB,CAAA;AAIjK;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,gBAAgB,CAc5H;AAcD;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,SAAS,GAAE,OAAO,KAAa,GAAG,OAAO,KAAK,CAepG"}

package/lib/csrfFetch.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildCsrfTokenFetcher = buildCsrfTokenFetcher;
+exports.createCsrfFetch = createCsrfFetch;
+const CsrfTokenCache_1 = require("./CsrfTokenCache");
+const SAFE_METHODS = new Set(["GET", "HEAD", "OPTIONS", "TRACE"]);
+/**
+ * Native-`fetch` token fetcher - kept deliberately separate from {@link buildCapDestinationCsrfTokenFetcher}
+ * (see that module for why): this one has no SAP Cloud SDK dependency at all and works with any
+ * plain HTTP(S) endpoint reachable via Node's global `fetch`.
+ *
+ * Builds a {@link CsrfTokenFetcher}: a GET request carrying `x-csrf-token: Fetch` against `url`,
+ * answered with the token in the same response header and the session cookie(s) needed to present
+ * it back on the next write. GET (not HEAD) is used because it is the verb every SAP gateway/OData
+ * implementation is guaranteed to answer a CSRF-fetch on, including services that don't implement HEAD.
+ */
+function buildCsrfTokenFetcher(url, init = {}, fetchImpl = fetch) {
+    return async () => {
+        const response = await fetchImpl(url, {
+            ...init,
+            method: "GET",
+            headers: { ...init.headers, [CsrfTokenCache_1.CSRF_TOKEN_HEADER]: "Fetch" }
+        });
+        const token = response.headers.get(CsrfTokenCache_1.CSRF_TOKEN_HEADER);
+        if (!response.ok || !token)
+            throw (0, CsrfTokenCache_1.missingCsrfTokenError)(url, response.status);
+        return { token, cookies: response.headers.getSetCookie?.() ?? [] };
+    };
+}
+function withCsrfHeaders(init, token) {
+    const headers = new Headers(init?.headers);
+    headers.set(CsrfTokenCache_1.CSRF_TOKEN_HEADER, token.token);
+    const cookieHeader = (0, CsrfTokenCache_1.toCookieHeader)(token.cookies);
+    if (cookieHeader)
+        headers.set("cookie", cookieHeader);
+    return headers;
+}
+function isCsrfRejection(response) {
+    return (0, CsrfTokenCache_1.isCsrfRequiredRejection)(response.status, response.headers.get(CsrfTokenCache_1.CSRF_TOKEN_HEADER));
+}
+/**
+ * Wraps a fetch-compatible function so every non-safe request is transparently armed with the
+ * cached CSRF token, and retried exactly once - with a freshly fetched token - if the backend
+ * rejects it as expired (`403` + `x-csrf-token: Required`). Safe methods pass through untouched.
+ *
+ * This is the piece that makes the cache usable with plain native `fetch` calls, independent of
+ * any CAP/Cloud SDK service - see {@link buildCsrfTokenFetcher} for a matching token fetcher, and
+ * `attachCsrfCache` for the equivalent wiring against a `cds.RemoteService`.
+ */
+function createCsrfFetch(cache, fetchImpl = fetch) {
+    return (async (input, init) => {
+        const method = (init?.method ?? "GET").toUpperCase();
+        if (SAFE_METHODS.has(method))
+            return fetchImpl(input, init);
+        const token = await cache.getToken();
+        const response = await fetchImpl(input, { ...init, method, headers: withCsrfHeaders(init, token) });
+        if (!isCsrfRejection(response))
+            return response;
+        cache.invalidate();
+        const freshToken = await cache.getToken();
+        return fetchImpl(input, { ...init, method, headers: withCsrfHeaders(init, freshToken) });
+    });
+}
+//# sourceMappingURL=csrfFetch.js.map

package/lib/csrfFetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"csrfFetch.js","sourceRoot":"","sources":["../src/csrfFetch.ts"],"names":[],"mappings":";;AAcA,sDAcC;AAuBD,0CAeC;AAlED,qDAAiK;AAEjK,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,CAAC,CAAC,CAAA;AAEjE;;;;;;;;;GASG;AACH,SAAgB,qBAAqB,CAAC,GAAW,EAAE,OAAoB,EAAE,EAAE,YAA0B,KAAK;IACtG,OAAO,KAAK,IAAI,EAAE;QACd,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,GAAG,EAAE;YAClC,GAAG,IAAI;YACP,MAAM,EAAE,KAAK;YACb,OAAO,EAAE,EAAE,GAAG,IAAI,CAAC,OAAO,EAAE,CAAC,kCAAiB,CAAC,EAAE,OAAO,EAAE;SAC7D,CAAC,CAAA;QAEF,MAAM,KAAK,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kCAAiB,CAAC,CAAA;QACrD,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,KAAK;YACtB,MAAM,IAAA,sCAAqB,EAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAA;QAErD,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,OAAO,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,EAAE,CAAA;IACtE,CAAC,CAAA;AACL,CAAC;AAED,SAAS,eAAe,CAAC,IAA6B,EAAE,KAAgB;IACpE,MAAM,OAAO,GAAG,IAAI,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;IAC1C,OAAO,CAAC,GAAG,CAAC,kCAAiB,EAAE,KAAK,CAAC,KAAK,CAAC,CAAA;IAC3C,MAAM,YAAY,GAAG,IAAA,+BAAc,EAAC,KAAK,CAAC,OAAO,CAAC,CAAA;IAClD,IAAI,YAAY;QAAE,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,YAAY,CAAC,CAAA;IACrD,OAAO,OAAO,CAAA;AAClB,CAAC;AAED,SAAS,eAAe,CAAC,QAAkB;IACvC,OAAO,IAAA,wCAAuB,EAAC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,kCAAiB,CAAC,CAAC,CAAA;AAC5F,CAAC;AAED;;;;;;;;GAQG;AACH,SAAgB,eAAe,CAAC,KAAqB,EAAE,YAA0B,KAAK;IAClF,OAAO,CAAC,KAAK,EAAE,KAAwB,EAAE,IAAkB,EAAE,EAAE;QAC3D,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,IAAI,KAAK,CAAC,CAAC,WAAW,EAAE,CAAA;QACpD,IAAI,YAAY,CAAC,GAAG,CAAC,MAAM,CAAC;YACxB,OAAO,SAAS,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;QAEjC,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAA;QACpC,MAAM,QAAQ,GAAG,MAAM,SAAS,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,KAAK,CAAC,EAAE,CAAC,CAAA;QACnG,IAAI,CAAC,eAAe,CAAC,QAAQ,CAAC;YAC1B,OAAO,QAAQ,CAAA;QAEnB,KAAK,CAAC,UAAU,EAAE,CAAA;QAClB,MAAM,UAAU,GAAG,MAAM,KAAK,CAAC,QAAQ,EAAE,CAAA;QACzC,OAAO,SAAS,CAAC,KAAK,EAAE,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,CAAC,IAAI,EAAE,UAAU,CAAC,EAAE,CAAC,CAAA;IAC5F,CAAC,CAAiB,CAAA;AACtB,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,9 @@
+export { CSRF_TOKEN_HEADER, CsrfTokenCache, toCookieHeader } from "./CsrfTokenCache";
+export type { CsrfToken, CsrfTokenFetcher, CsrfTokenCacheOptions } from "./CsrfTokenCache";
+export { buildCsrfTokenFetcher, createCsrfFetch } from "./csrfFetch";
+export { buildCapDestinationCsrfTokenFetcher } from "./capDestinationTokenFetcher";
+export { attachCsrfCache } from "./attachCsrfCache";
+export type { AttachCsrfCacheOptions } from "./attachCsrfCache";
+export { acquireSharedCsrfCache, resetSharedCsrfCaches, sharedCsrfCacheKey, sharedCsrfCacheMembers } from "./sharedCsrfCaches";
+export type { SharedCsrfCache, SharedCsrfCacheScope } from "./sharedCsrfCaches";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AACpF,YAAY,EAAE,SAAS,EAAE,gBAAgB,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAC1F,OAAO,EAAE,qBAAqB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AACpE,OAAO,EAAE,mCAAmC,EAAE,MAAM,8BAA8B,CAAA;AAClF,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAA;AACnD,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAA;AAC/D,OAAO,EAAE,sBAAsB,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAA;AAC9H,YAAY,EAAE,eAAe,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA"}

package/lib/index.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sharedCsrfCacheMembers = exports.sharedCsrfCacheKey = exports.resetSharedCsrfCaches = exports.acquireSharedCsrfCache = exports.attachCsrfCache = exports.buildCapDestinationCsrfTokenFetcher = exports.createCsrfFetch = exports.buildCsrfTokenFetcher = exports.toCookieHeader = exports.CsrfTokenCache = exports.CSRF_TOKEN_HEADER = void 0;
+var CsrfTokenCache_1 = require("./CsrfTokenCache");
+Object.defineProperty(exports, "CSRF_TOKEN_HEADER", { enumerable: true, get: function () { return CsrfTokenCache_1.CSRF_TOKEN_HEADER; } });
+Object.defineProperty(exports, "CsrfTokenCache", { enumerable: true, get: function () { return CsrfTokenCache_1.CsrfTokenCache; } });
+Object.defineProperty(exports, "toCookieHeader", { enumerable: true, get: function () { return CsrfTokenCache_1.toCookieHeader; } });
+var csrfFetch_1 = require("./csrfFetch");
+Object.defineProperty(exports, "buildCsrfTokenFetcher", { enumerable: true, get: function () { return csrfFetch_1.buildCsrfTokenFetcher; } });
+Object.defineProperty(exports, "createCsrfFetch", { enumerable: true, get: function () { return csrfFetch_1.createCsrfFetch; } });
+var capDestinationTokenFetcher_1 = require("./capDestinationTokenFetcher");
+Object.defineProperty(exports, "buildCapDestinationCsrfTokenFetcher", { enumerable: true, get: function () { return capDestinationTokenFetcher_1.buildCapDestinationCsrfTokenFetcher; } });
+var attachCsrfCache_1 = require("./attachCsrfCache");
+Object.defineProperty(exports, "attachCsrfCache", { enumerable: true, get: function () { return attachCsrfCache_1.attachCsrfCache; } });
+var sharedCsrfCaches_1 = require("./sharedCsrfCaches");
+Object.defineProperty(exports, "acquireSharedCsrfCache", { enumerable: true, get: function () { return sharedCsrfCaches_1.acquireSharedCsrfCache; } });
+Object.defineProperty(exports, "resetSharedCsrfCaches", { enumerable: true, get: function () { return sharedCsrfCaches_1.resetSharedCsrfCaches; } });
+Object.defineProperty(exports, "sharedCsrfCacheKey", { enumerable: true, get: function () { return sharedCsrfCaches_1.sharedCsrfCacheKey; } });
+Object.defineProperty(exports, "sharedCsrfCacheMembers", { enumerable: true, get: function () { return sharedCsrfCaches_1.sharedCsrfCacheMembers; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,mDAAoF;AAA3E,mHAAA,iBAAiB,OAAA;AAAE,gHAAA,cAAc,OAAA;AAAE,gHAAA,cAAc,OAAA;AAE1D,yCAAoE;AAA3D,kHAAA,qBAAqB,OAAA;AAAE,4GAAA,eAAe,OAAA;AAC/C,2EAAkF;AAAzE,iJAAA,mCAAmC,OAAA;AAC5C,qDAAmD;AAA1C,kHAAA,eAAe,OAAA;AAExB,uDAA8H;AAArH,0HAAA,sBAAsB,OAAA;AAAE,yHAAA,qBAAqB,OAAA;AAAE,sHAAA,kBAAkB,OAAA;AAAE,0HAAA,sBAAsB,OAAA"}

package/lib/sharedCsrfCaches.d.ts

@@ -0,0 +1,48 @@
+import { CsrfTokenCache } from "./CsrfTokenCache";
+/**
+ * Everything that has to match before two remote services may present the *same* CSRF token.
+ *
+ * An S/4 CSRF token is bound to the HTTP session behind the destination, not to the OData service
+ * path it was fetched from - so a token fetched for `zsd_o2c_order_processing` is equally valid on
+ * `api_purchaseorder_2` as long as both go to the same system, through the same destination, with
+ * the same destination resolution (`destinationOptions` decide *which* concrete destination, and
+ * therefore which backend user/session, a name resolves to - a different `selectionStrategy` or a
+ * different `jwt` can mean a different session entirely, so they are part of the identity here).
+ *
+ * `group` narrows that further, for the case where two services share a destination but must not
+ * share a token (different backend clients behind one destination name, or simply to keep one
+ * service's token isolated while the rest share one).
+ */
+export type SharedCsrfCacheScope = {
+    destination: string;
+    destinationOptions?: Record<string, unknown>;
+    group?: string;
+};
+/** The identity of a shared cache - see {@link SharedCsrfCacheScope} for why each part is in it. */
+export declare function sharedCsrfCacheKey(scope: SharedCsrfCacheScope): string;
+export type SharedCsrfCache = {
+    cache: CsrfTokenCache;
+    key: string;
+    /** `true` if an existing cache was joined, `false` if this call created it. */
+    joined: boolean;
+    /** The service that created the cache (the caller itself when `joined` is `false`). */
+    owner: string;
+};
+/**
+ * Returns the {@link CsrfTokenCache} for `scope`, creating it via `create` on first use and handing
+ * the very same instance to every later caller with the same scope. That is what lets several
+ * remote services on one destination fetch a single token instead of one each - and it also means
+ * an `invalidate()` after a rejected token (from *any* of them) refreshes the token for all of
+ * them at once.
+ *
+ * The first service in wins: the shared cache keeps fetching from that service's `csrf.url`, with
+ * its method and validity. A service joining with different settings is served the existing cache
+ * and warned about, rather than silently getting a second one - two caches on one destination is
+ * exactly what sharing was turned on to avoid.
+ */
+export declare function acquireSharedCsrfCache(scope: SharedCsrfCacheScope, member: string, settings: string, create: () => CsrfTokenCache): SharedCsrfCache;
+/** The services sharing the cache under `key`, owner first - for diagnostics and tests. */
+export declare function sharedCsrfCacheMembers(key: string): string[];
+/** Disposes every shared cache (stopping its refresh timer) and empties the registry. For tests and for a clean shutdown/restart of the server process. */
+export declare function resetSharedCsrfCaches(): void;
+//# sourceMappingURL=sharedCsrfCaches.d.ts.map

package/lib/sharedCsrfCaches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedCsrfCaches.d.ts","sourceRoot":"","sources":["../src/sharedCsrfCaches.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAA;AAIjD;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,GAAG;IAC/B,WAAW,EAAE,MAAM,CAAA;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;CACjB,CAAA;AAuBD,oGAAoG;AACpG,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,oBAAoB,GAAG,MAAM,CAEtE;AAED,MAAM,MAAM,eAAe,GAAG;IAC1B,KAAK,EAAE,cAAc,CAAA;IACrB,GAAG,EAAE,MAAM,CAAA;IACX,+EAA+E;IAC/E,MAAM,EAAE,OAAO,CAAA;IACf,uFAAuF;IACvF,KAAK,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAClC,KAAK,EAAE,oBAAoB,EAC3B,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,cAAc,GAC7B,eAAe,CAejB;AAED,2FAA2F;AAC3F,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAE5D;AAED,2JAA2J;AAC3J,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C"}

package/lib/sharedCsrfCaches.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sharedCsrfCacheKey = sharedCsrfCacheKey;
+exports.acquireSharedCsrfCache = acquireSharedCsrfCache;
+exports.sharedCsrfCacheMembers = sharedCsrfCacheMembers;
+exports.resetSharedCsrfCaches = resetSharedCsrfCaches;
+const cds_1 = __importDefault(require("@sap/cds"));
+const LOG = cds_1.default.log("csrf-cache");
+const registry = new Map();
+/** `JSON.stringify` with sorted keys, so two equal `destinationOptions` objects can't produce two different keys just because they were written in a different order. */
+function stableStringify(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value) ?? "null";
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    const entries = Object.keys(value).sort()
+        .map(key => `${JSON.stringify(key)}:${stableStringify(value[key])}`);
+    return `{${entries.join(",")}}`;
+}
+/** The identity of a shared cache - see {@link SharedCsrfCacheScope} for why each part is in it. */
+function sharedCsrfCacheKey(scope) {
+    return `${scope.destination}::${stableStringify(scope.destinationOptions ?? {})}::${scope.group ?? ""}`;
+}
+/**
+ * Returns the {@link CsrfTokenCache} for `scope`, creating it via `create` on first use and handing
+ * the very same instance to every later caller with the same scope. That is what lets several
+ * remote services on one destination fetch a single token instead of one each - and it also means
+ * an `invalidate()` after a rejected token (from *any* of them) refreshes the token for all of
+ * them at once.
+ *
+ * The first service in wins: the shared cache keeps fetching from that service's `csrf.url`, with
+ * its method and validity. A service joining with different settings is served the existing cache
+ * and warned about, rather than silently getting a second one - two caches on one destination is
+ * exactly what sharing was turned on to avoid.
+ */
+function acquireSharedCsrfCache(scope, member, settings, create) {
+    const key = sharedCsrfCacheKey(scope);
+    const existing = registry.get(key);
+    if (existing) {
+        if (!existing.members.includes(member))
+            existing.members.push(member);
+        if (existing.settings !== settings)
+            LOG.warn(`service '${member}' joins the shared csrf token cache of destination '${scope.destination}' with different settings (${settings}) `
+                + `than its owner '${existing.owner}' (${existing.settings}); the owner's settings stay in effect`);
+        return { cache: existing.cache, key, joined: true, owner: existing.owner };
+    }
+    const registration = { cache: create(), owner: member, members: [member], settings };
+    registry.set(key, registration);
+    return { cache: registration.cache, key, joined: false, owner: member };
+}
+/** The services sharing the cache under `key`, owner first - for diagnostics and tests. */
+function sharedCsrfCacheMembers(key) {
+    return [...registry.get(key)?.members ?? []];
+}
+/** Disposes every shared cache (stopping its refresh timer) and empties the registry. For tests and for a clean shutdown/restart of the server process. */
+function resetSharedCsrfCaches() {
+    for (const { cache } of registry.values())
+        cache.dispose();
+    registry.clear();
+}
+//# sourceMappingURL=sharedCsrfCaches.js.map

package/lib/sharedCsrfCaches.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharedCsrfCaches.js","sourceRoot":"","sources":["../src/sharedCsrfCaches.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "myfirstdemoprojectkulliax",
+  "version": "0.1.0",
+  "description": "CAP plugin that caches SAP CSRF tokens per destination-backed remote service, injects them into outgoing requests, and refreshes them in the background before they expire.",
+  "keywords": [
+    "sap",
+    "cap",
+    "cds",
+    "csrf",
+    "cds-plugin"
+  ],
+  "license": "MIT",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "files": [
+    "lib",
+    "cds-plugin.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test.watch": "vitest",
+    "test.e2e": "vitest run --config vitest.e2e.config.ts"
+  },
+  "peerDependencies": {
+    "@sap/cds": "^10",
+    "@sap-cloud-sdk/http-client": "^4"
+  },
+  "peerDependenciesMeta": {
+    "@sap-cloud-sdk/http-client": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@cap-js/cds-types": "^0",
+    "@sap-cloud-sdk/http-client": "^4",
+    "@sap/cds": "^10",
+    "@sap/cds-dk": "^10",
+    "@types/node": "^24",
+    "typescript": "^6",
+    "vitest": "^4"
+  }
+}