feat(portal-bff): signed-assertion strategy + /.well-known/jwks.json (#138)

## Summary

Second half of the **DownstreamApiClient + OBO** chantier per [ADR-0014](docs/decisions/0014-downstream-api-access-obo-pattern.md). Ships the **signed-assertion strategy** (non-Entra downstreams) and the **JWKS publishing endpoint** as testable primitives, completing the strategy layer the OBO PR (#137) started. The framework around them (DownstreamApiClientFactory, cockatiel, audience pre-check, error translation) still waits for the first concrete integration per the ADR's own "until then" clause.

After this PR the BFF has, ready to plug into a future integration:

- `OboStrategy` — Entra-protected downstreams (PR #137)
- `SignedAssertionStrategy` — non-Entra downstreams (this PR)
- `DownstreamTokenCache` — encrypted-at-rest OBO token cache (PR #137)
- `GET /.well-known/jwks.json` — public key publication (this PR)

## What lands

### [`assertJwksConfig`](apps/portal-bff/src/config/check-jwks-config.ts)

Boot validator for `BFF_JWKS_PRIVATE_KEY_PATH` + `BFF_JWKS_KID`. Reads the PEM file once at startup, refuses missing / unreadable / weak material (RSA < 2048, Ed25519, unknown key type), derives the JOSE algorithm (`RS256` / `ES256` / `ES384`) from the key shape, and validates the kid against `[A-Za-z0-9_-]{4,128}` so the value lives unescaped in JWT headers + JWKS payloads.

### [`BffSigningKey`](apps/portal-bff/src/downstream/bff-signing-key.ts)

Singleton holding `{ config: JwksConfig, publicJwk: JWK }`. The `publicJwk` is derived from the **public half** of the key (via `jose.exportJWK` on a `createPublicKey`-derived `KeyObject`) so no private material can leak through. Single DI source for both consumers (strategy + JWKS controller) so a key rotation only changes one provider.

### [`SignedAssertionStrategy`](apps/portal-bff/src/downstream/strategies/signed-assertion.strategy.ts)

Wraps `jose.SignJWT` with the ADR-0014 claim shape:

```json
{
  "iss": "portal-bff",
  "sub": "<actor_id_hash>",
  "aud": "<downstream-name>",
  "audience": "workforce" | "customer",
  "claims": { /* curated subset */ },
  "exp": <now + 60s>,
  "iat": <now>,
  "trace_id": "<W3C trace id>"
}
```

- **60 s TTL** hard-coded — the ADR mandates it.
- **No JWT cache** — at 60 s lifetime the savings would be negligible and a cache would let replayed assertions linger past their useful life. The signing operation itself is cheap (~hundreds of µs for RS256 with a 3 KB key).
- **kid in the protected header** matches the JWKS so a downstream picks the right key during rotation.
- Supports **RS256 / ES256 / ES384** transparently — picks the alg the validator derived at boot.

### [`JwksController`](apps/portal-bff/src/downstream/jwks.controller.ts)

`GET /.well-known/jwks.json` returns `{ keys: [<single jwk>] }`. v1 publishes one key; the rotation chantier will add a second entry + window-based eviction so a downstream that cached the previous JWK keeps verifying during cut-over.

[`main.ts`](apps/portal-bff/src/main.ts) excludes `/.well-known/*` from the global `/api` prefix so the route lands at the bare root per RFC 8615. No auth gate — the JWKS is the verification anchor; gating it would defeat the purpose. The CSRF middleware already exempts GET methods, so the route comes out clean.

## Required env update (mandatory at boot)

Generate the key:

```bash
mkdir -p apps/portal-bff/.secrets
openssl genpkey -algorithm RSA -pkeyopt rsa_keygen_bits:3072 \
  -out apps/portal-bff/.secrets/jwks.pem
```

Set in `apps/portal-bff/.env`:

```env
BFF_JWKS_PRIVATE_KEY_PATH=apps/portal-bff/.secrets/jwks.pem
BFF_JWKS_KID=bff-2026-05
```

The repo's existing `*.pem` / `*.key` gitignore patterns cover `.secrets/`.

## Dependency

- **`jose@^6`** added as a direct dep (was transitive via MSAL). Pinned at the workspace root since the BFF is the only consumer today and the package isn't part of the Angular bundle graph.
- `jest.config.cts`: `jose` ships ESM-only, so its `node_modules` path is removed from `transformIgnorePatterns`. The pattern walks pnpm's deep `.pnpm/` layout — anything under `/node_modules/` whose path also contains `jose` somewhere gets transformed by ts-jest.

## Out of scope (deferred until the first concrete integration)

Per ADR-0014's "until then" clause:

- `DownstreamApiClientFactory` + per-service typed `DownstreamApiConfig`.
- `cockatiel` resilience composition (timeout, retry, circuit breaker, bulkhead).
- Audience pre-check at the call site (`audienceConstraint` → `authz.deny` audit).
- Error translation tables per service.
- OTel custom spans `downstream.<service>.<verb>.<path>`.
- The framework code that actually calls `SignedAssertionStrategy.sign()` and attaches `X-User-Assertion` + the `ServiceCredential` auth header to an outbound HTTP request.
- Key rotation (the JWKS lists one key for now; the rotation chantier adds the second entry + eviction policy).

These land alongside the first concrete integration so the framework shape is validated against a real consumer, not speculative needs.

## Test plan

- [x] `pnpm nx test portal-bff` — **358 specs pass** (was 334; +24: env validators 11, signing key 4, strategy 6, controller 3).
- [x] `pnpm exec nx affected -t format:check lint test build --base=origin/main` — clean.
- [x] Env validator: missing path, unreadable file, garbage PEM, RSA-1024 (weak), Ed25519 (unsupported), missing kid, illegal kid charset, kid too short.
- [x] Signing key: RSA / EC P-256 / EC P-384 round-trip to public JWK with no private material (`d`, `p`, `q`, `dp`, `dq`, `qi` all absent from the published JWK).
- [x] Strategy: claim shape matches ADR-0014, `exp - iat == 60`, audience mismatch rejected, signature mismatch rejected, EC P-256 signing path (ES256), per-call freshness.
- [x] Controller: returns JWKS with the single public key, no private material leaks.
- [ ] Manual smoke: generate a key locally + set the two env vars + `curl http://localhost:3000/.well-known/jwks.json` should return the JWKS shape with the chosen kid.

## Notes for the reviewer

- The strategy uses `setProtectedHeader({ alg, kid })` — the kid in the protected header is the canonical way to tell a verifier "use the entry with this kid in the JWKS". Without it, a verifier holding two keys during rotation has to try both.
- The `60 s` TTL is intentionally not env-overridable. ADR-0014 mandates it; making it tunable would create a tempting knob to widen the replay window for "performance".
- `jose` was already in the tree transitively (likely via MSAL). Promoting it to a direct dep + pinning means a future hoist deduplication can't silently remove it without our review.

## What's next

The chantier's strategy layer is complete. Open follow-ups on the roadmap:

- **First concrete downstream integration** — when a real consumer arrives, the framework gets built around the two strategies (DownstreamApiClientFactory, cockatiel resilience, audience pre-check, error translation, OTel spans, audit events). Until then the strategies + cache + JWKS sit ready.
- **Strategic security baseline ADR** — RSSI sign-off on ASVS / HDS / GDPR / NIS 2. Paused per [CLAUDE.md](CLAUDE.md) §"Repository status".
- **portal-admin v1 modules** — CMS pages, menu management, user list. Each is its own self-contained chantier.

---------

Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr>
Reviewed-on: #138

apps/portal-bff/src/config/check-jwks-config.spec.ts

@@ -0,0 +1,135 @@
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { generateKeyPairSync } from 'node:crypto';
+import { assertJwksConfig } from './check-jwks-config';
+
+const tmpDir = mkdtempSync(join(tmpdir(), 'apf-jwks-spec-'));
+
+function writeKey(
+  filename: string,
+  type: 'rsa-3072' | 'rsa-1024' | 'ec-p256' | 'ec-p384' | 'ed25519' | 'garbage',
+): string {
+  const path = join(tmpDir, filename);
+  let pem: string;
+  switch (type) {
+    case 'rsa-3072':
+      pem = generateKeyPairSync('rsa', { modulusLength: 3072 }).privateKey.export({
+        type: 'pkcs8',
+        format: 'pem',
+      }) as string;
+      break;
+    case 'rsa-1024':
+      pem = generateKeyPairSync('rsa', { modulusLength: 1024 }).privateKey.export({
+        type: 'pkcs8',
+        format: 'pem',
+      }) as string;
+      break;
+    case 'ec-p256':
+      pem = generateKeyPairSync('ec', { namedCurve: 'prime256v1' }).privateKey.export({
+        type: 'pkcs8',
+        format: 'pem',
+      }) as string;
+      break;
+    case 'ec-p384':
+      pem = generateKeyPairSync('ec', { namedCurve: 'secp384r1' }).privateKey.export({
+        type: 'pkcs8',
+        format: 'pem',
+      }) as string;
+      break;
+    case 'ed25519':
+      pem = generateKeyPairSync('ed25519').privateKey.export({
+        type: 'pkcs8',
+        format: 'pem',
+      }) as string;
+      break;
+    case 'garbage':
+      pem = '-----BEGIN PRIVATE KEY-----\nbm90LWEta2V5\n-----END PRIVATE KEY-----\n';
+      break;
+  }
+  writeFileSync(path, pem);
+  return path;
+}
+
+describe('assertJwksConfig', () => {
+  const originalPath = process.env['BFF_JWKS_PRIVATE_KEY_PATH'];
+  const originalKid = process.env['BFF_JWKS_KID'];
+
+  beforeEach(() => {
+    process.env['BFF_JWKS_KID'] = 'bff-2026-05';
+  });
+
+  afterEach(() => {
+    restore('BFF_JWKS_PRIVATE_KEY_PATH', originalPath);
+    restore('BFF_JWKS_KID', originalKid);
+  });
+
+  it('returns the parsed key + kid + alg=RS256 for a well-formed RSA-3072 key', () => {
+    process.env['BFF_JWKS_PRIVATE_KEY_PATH'] = writeKey('rsa.pem', 'rsa-3072');
+    const config = assertJwksConfig();
+    expect(config.kid).toBe('bff-2026-05');
+    expect(config.alg).toBe('RS256');
+    expect(config.privateKey.asymmetricKeyType).toBe('rsa');
+  });
+
+  it('returns alg=ES256 for an EC P-256 key', () => {
+    process.env['BFF_JWKS_PRIVATE_KEY_PATH'] = writeKey('ec256.pem', 'ec-p256');
+    expect(assertJwksConfig().alg).toBe('ES256');
+  });
+
+  it('returns alg=ES384 for an EC P-384 key', () => {
+    process.env['BFF_JWKS_PRIVATE_KEY_PATH'] = writeKey('ec384.pem', 'ec-p384');
+    expect(assertJwksConfig().alg).toBe('ES384');
+  });
+
+  it('throws when BFF_JWKS_PRIVATE_KEY_PATH is unset', () => {
+    delete process.env['BFF_JWKS_PRIVATE_KEY_PATH'];
+    expect(() => assertJwksConfig()).toThrow(/BFF_JWKS_PRIVATE_KEY_PATH is not set/);
+  });
+
+  it('throws when the file does not exist', () => {
+    process.env['BFF_JWKS_PRIVATE_KEY_PATH'] = join(tmpDir, 'missing.pem');
+    expect(() => assertJwksConfig()).toThrow(/could not be read/);
+  });
+
+  it('throws when the file is not a valid PEM private key', () => {
+    process.env['BFF_JWKS_PRIVATE_KEY_PATH'] = writeKey('garbage.pem', 'garbage');
+    expect(() => assertJwksConfig()).toThrow(/not a valid PEM private key/);
+  });
+
+  it('refuses RSA keys weaker than 2048 bits', () => {
+    process.env['BFF_JWKS_PRIVATE_KEY_PATH'] = writeKey('weak.pem', 'rsa-1024');
+    expect(() => assertJwksConfig()).toThrow(/unsupported key type/);
+  });
+
+  it('refuses Ed25519 keys (v1 supports RSA + EC P-256/P-384 only)', () => {
+    process.env['BFF_JWKS_PRIVATE_KEY_PATH'] = writeKey('ed25519.pem', 'ed25519');
+    expect(() => assertJwksConfig()).toThrow(/unsupported key type/);
+  });
+
+  it('throws when BFF_JWKS_KID is unset', () => {
+    process.env['BFF_JWKS_PRIVATE_KEY_PATH'] = writeKey('rsa.pem', 'rsa-3072');
+    delete process.env['BFF_JWKS_KID'];
+    expect(() => assertJwksConfig()).toThrow(/BFF_JWKS_KID is not set/);
+  });
+
+  it('throws when BFF_JWKS_KID has illegal characters', () => {
+    process.env['BFF_JWKS_PRIVATE_KEY_PATH'] = writeKey('rsa.pem', 'rsa-3072');
+    process.env['BFF_JWKS_KID'] = 'has spaces and !';
+    expect(() => assertJwksConfig()).toThrow(/must match/);
+  });
+
+  it('throws when BFF_JWKS_KID is too short', () => {
+    process.env['BFF_JWKS_PRIVATE_KEY_PATH'] = writeKey('rsa.pem', 'rsa-3072');
+    process.env['BFF_JWKS_KID'] = 'ab';
+    expect(() => assertJwksConfig()).toThrow(/must match/);
+  });
+});
+
+function restore(name: string, original: string | undefined): void {
+  if (original === undefined) {
+    delete process.env[name];
+  } else {
+    process.env[name] = original;
+  }
+}