@opengroundplan/core 0.1.1

package/templates/layers/auth-jwt/files/src/auth/tests/auth.test.ts

@@ -0,0 +1,102 @@
+import assert from 'node:assert/strict';
+import { beforeAll, describe, it } from 'vitest';
+import { resetAuthConfig } from '../config.js';
+import { AuthError } from '../errors.js';
+import { hashPassword, verifyPassword } from '../password.js';
+import { AuthService } from '../service.js';
+import { InMemoryRefreshTokenStore, InMemoryUserStore } from '../store.memory.js';
+import { signAccessToken, verifyAccessToken } from '../tokens.js';
+
+const PASSWORD = 'correct horse battery staple';
+
+function service(): AuthService {
+  return new AuthService(new InMemoryUserStore(), new InMemoryRefreshTokenStore());
+}
+
+function isAuthError(code: string) {
+  return (error: unknown) => error instanceof AuthError && error.code === code;
+}
+
+beforeAll(() => {
+  process.env.AUTH_JWT_SECRET = 'test-secret-that-is-at-least-32-bytes-long';
+  resetAuthConfig();
+});
+
+describe('access tokens', () => {
+  it('round-trips its claims', async () => {
+    const token = await signAccessToken({ sub: 'user-1', sid: 'sess-1', roles: ['admin'] });
+    const claims = await verifyAccessToken(token);
+
+    assert.equal(claims.sub, 'user-1');
+    assert.equal(claims.sid, 'sess-1');
+    assert.deepEqual(claims.roles, ['admin']);
+  });
+
+  it('rejects a tampered payload', async () => {
+    const token = await signAccessToken({ sub: 'user-1', sid: 'sess-1', roles: [] });
+    const [header, , signature] = token.split('.');
+    const forged = btoa(JSON.stringify({ sub: 'admin', sid: 'sess-1', roles: ['admin'] }));
+
+    await assert.rejects(
+      () => verifyAccessToken(`${header}.${forged}.${signature}`),
+      isAuthError('invalid_token'),
+    );
+  });
+
+  it('rejects a missing token', async () => {
+    await assert.rejects(() => verifyAccessToken(''), isAuthError('invalid_token'));
+  });
+});
+
+describe('passwords', () => {
+  it('verifies only the original password', async () => {
+    const hash = await hashPassword(PASSWORD);
+
+    assert.ok(!hash.includes(PASSWORD));
+    assert.equal(await verifyPassword(hash, PASSWORD), true);
+    assert.equal(await verifyPassword(hash, `${PASSWORD}!`), false);
+  });
+});
+
+describe('sessions', () => {
+  it('issues a usable pair on login', async () => {
+    const auth = service();
+    await auth.register('user@example.test', PASSWORD, ['member']);
+    const pair = await auth.login('user@example.test', PASSWORD);
+
+    const claims = await verifyAccessToken(pair.accessToken);
+    assert.deepEqual(claims.roles, ['member']);
+  });
+
+  it('refuses a wrong password', async () => {
+    const auth = service();
+    await auth.register('user@example.test', PASSWORD);
+
+    await assert.rejects(
+      () => auth.login('user@example.test', 'wrong'),
+      isAuthError('invalid_credentials'),
+    );
+  });
+
+  it('rotates the refresh token and kills the session on replay', async () => {
+    const auth = service();
+    await auth.register('user@example.test', PASSWORD);
+    const first = await auth.login('user@example.test', PASSWORD);
+
+    const second = await auth.refresh(first.refreshToken);
+    assert.notEqual(second.refreshToken, first.refreshToken);
+
+    await assert.rejects(() => auth.refresh(first.refreshToken), isAuthError('refresh_reused'));
+    // Replay revoked the whole family, so the rotated token is dead too.
+    await assert.rejects(() => auth.refresh(second.refreshToken), isAuthError('invalid_token'));
+  });
+
+  it('invalidates the refresh token on logout', async () => {
+    const auth = service();
+    await auth.register('user@example.test', PASSWORD);
+    const pair = await auth.login('user@example.test', PASSWORD);
+
+    await auth.logout(pair.refreshToken);
+    await assert.rejects(() => auth.refresh(pair.refreshToken), isAuthError('invalid_token'));
+  });
+});

package/templates/layers/auth-jwt/files/src/auth/tokens.ts

@@ -0,0 +1,56 @@
+import { errors, type JWTPayload, jwtVerify, SignJWT } from 'jose';
+import { authConfig, JWT_ALGORITHM } from './config.js';
+import { AuthError } from './errors.js';
+import { randomId } from './random.js';
+
+export interface AccessClaims {
+  /** User id. */
+  sub: string;
+  /** Session id, shared with the refresh-token family so one logout kills both. */
+  sid: string;
+  roles: string[];
+}
+
+export async function signAccessToken(claims: AccessClaims): Promise<string> {
+  const config = authConfig();
+  const now = Math.floor(Date.now() / 1000);
+
+  return new SignJWT({ sid: claims.sid, roles: claims.roles })
+    .setProtectedHeader({ alg: JWT_ALGORITHM, typ: 'JWT' })
+    .setSubject(claims.sub)
+    .setIssuer(config.issuer)
+    .setAudience(config.audience)
+    .setIssuedAt(now)
+    .setNotBefore(now)
+    .setExpirationTime(now + config.accessTtlSeconds)
+    .setJti(randomId())
+    .sign(config.secret);
+}
+
+export async function verifyAccessToken(token: string): Promise<AccessClaims> {
+  const config = authConfig();
+
+  try {
+    const { payload } = await jwtVerify(token, config.secret, {
+      // Allow-list the algorithm: without it a token may nominate its own.
+      algorithms: [JWT_ALGORITHM],
+      issuer: config.issuer,
+      audience: config.audience,
+    });
+    return toClaims(payload);
+  } catch (error) {
+    if (error instanceof errors.JWTExpired) throw new AuthError('token_expired');
+    if (error instanceof AuthError) throw error;
+    throw new AuthError('invalid_token');
+  }
+}
+
+/** A signature proves the payload is ours, not that it has the shape this release expects. */
+function toClaims(payload: JWTPayload): AccessClaims {
+  const { sub, sid, roles } = payload as JWTPayload & { sid?: unknown; roles?: unknown };
+  if (typeof sub !== 'string' || typeof sid !== 'string') throw new AuthError('invalid_token');
+  if (!Array.isArray(roles) || roles.some((role) => typeof role !== 'string')) {
+    throw new AuthError('invalid_token');
+  }
+  return { sub, sid, roles: roles as string[] };
+}

package/templates/layers/auth-jwt/files/tests/auth/test_auth.py

@@ -0,0 +1,106 @@
+"""Auth layer suite.
+
+Coroutines are driven with `asyncio.run` so the suite needs no pytest-asyncio plugin
+and cannot clash with whatever async config the base already has.
+"""
+
+import asyncio
+
+import pytest
+
+from {{ solutionName | snake }}.auth import (
+    AccessClaims,
+    AuthError,
+    AuthService,
+    InMemoryRefreshTokenStore,
+    InMemoryUserStore,
+    hash_password,
+    reset_auth_settings,
+    sign_access_token,
+    verify_access_token,
+    verify_password,
+)
+
+PASSWORD = "correct horse battery staple"
+EMAIL = "user@example.test"
+
+
+@pytest.fixture(autouse=True)
+def _auth_env(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("AUTH_JWT_SECRET", "test-secret-that-is-at-least-32-bytes-long")
+    reset_auth_settings()
+
+
+@pytest.fixture
+def service() -> AuthService:
+    return AuthService(InMemoryUserStore(), InMemoryRefreshTokenStore())
+
+
+def test_access_token_round_trips() -> None:
+    token = sign_access_token(AccessClaims(sub="user-1", sid="sess-1", roles=["admin"]))
+    claims = verify_access_token(token)
+
+    assert claims.sub == "user-1"
+    assert claims.sid == "sess-1"
+    assert claims.roles == ["admin"]
+
+
+def test_tampered_token_is_rejected() -> None:
+    token = sign_access_token(AccessClaims(sub="user-1", sid="sess-1", roles=[]))
+    header, payload, signature = token.split(".")
+    swapped = "BBBB" if payload.endswith("AAAA") else "AAAA"
+    forged = f"{header}.{payload[:-4]}{swapped}.{signature}"
+
+    with pytest.raises(AuthError) as caught:
+        verify_access_token(forged)
+    assert caught.value.code == "invalid_token"
+
+
+def test_password_verifies_only_the_original() -> None:
+    stored = hash_password(PASSWORD)
+
+    assert PASSWORD not in stored
+    assert verify_password(stored, PASSWORD) is True
+    assert verify_password(stored, PASSWORD + "!") is False
+
+
+def test_login_issues_a_usable_pair(service: AuthService) -> None:
+    asyncio.run(service.register(EMAIL, PASSWORD, ["member"]))
+    pair = asyncio.run(service.login(EMAIL, PASSWORD))
+
+    assert verify_access_token(pair.access_token).roles == ["member"]
+
+
+def test_login_refuses_a_wrong_password(service: AuthService) -> None:
+    asyncio.run(service.register(EMAIL, PASSWORD))
+
+    with pytest.raises(AuthError) as caught:
+        asyncio.run(service.login(EMAIL, "wrong"))
+    assert caught.value.code == "invalid_credentials"
+
+
+def test_refresh_rotates_and_replay_kills_the_session(service: AuthService) -> None:
+    asyncio.run(service.register(EMAIL, PASSWORD))
+    first = asyncio.run(service.login(EMAIL, PASSWORD))
+
+    second = asyncio.run(service.refresh(first.refresh_token))
+    assert second.refresh_token != first.refresh_token
+
+    with pytest.raises(AuthError) as replay:
+        asyncio.run(service.refresh(first.refresh_token))
+    assert replay.value.code == "refresh_reused"
+
+    # Replay revoked the whole family, so the rotated token is dead too.
+    with pytest.raises(AuthError) as rotated:
+        asyncio.run(service.refresh(second.refresh_token))
+    assert rotated.value.code == "invalid_token"
+
+
+def test_logout_invalidates_the_refresh_token(service: AuthService) -> None:
+    asyncio.run(service.register(EMAIL, PASSWORD))
+    pair = asyncio.run(service.login(EMAIL, PASSWORD))
+
+    asyncio.run(service.logout(pair.refresh_token))
+    with pytest.raises(AuthError) as caught:
+        asyncio.run(service.refresh(pair.refresh_token))
+    assert caught.value.code == "invalid_token"

package/templates/layers/auth-oidc/blueprint.yaml

@@ -0,0 +1,89 @@
+id: auth-oidc
+kind: layer
+name: OIDC / OAuth2 authentication
+description: >-
+  Standards-compliant OpenID Connect wiring. Browser stacks get Authorization Code + PKCE
+  login with an encrypted session cookie; API stacks get bearer-token validation against the
+  provider's JWKS. Everything is discovery-driven, so no endpoint, signing key, or algorithm
+  is ever pinned in code.
+
+tags: [auth, authentication, authorization, security, oidc, oauth2, identity]
+
+# No blueprint prerequisite: this layer only adds an auth module and reads env, so it composes
+# with any base. `auth-jwt` issues and signs its own tokens against the same routes and guards —
+# selecting both leaves two authentication schemes competing for the same pipeline.
+requires: []
+conflicts: [auth-jwt]
+provides: [auth, oidc, oauth2]
+
+# Auth is an infrastructure concern, not a layout concern — every architecture overlay is fine.
+supportsArchitectures: []
+# Framework packages these templates import are installed by the base itself.
+peerProvidedBy: [nextjs-app, nestjs-api]
+
+
+variables:
+  - name: oidcScopes
+    prompt: "Scopes to request from the identity provider"
+    type: string
+    default: openid profile email
+
+  - name: oidcRoleClaim
+    prompt: "Token claim that carries the user's roles"
+    type: string
+    default: roles
+
+  - name: oidcSessionTtlMinutes
+    prompt: "Session lifetime in minutes (browser login flows)"
+    type: number
+    default: 60
+
+files:
+  # Next.js / App Router — interactive login, encrypted cookie session.
+  - from: files/typescript/**/*
+    to: "."
+    when: "stack == 'typescript'"
+
+  # NestJS — resource server validating bearer tokens.
+  - from: files/node/**/*
+    to: "."
+    when: "stack == 'node'"
+
+  # FastAPI — resource server validating bearer tokens.
+  - from: files/python/**/*
+    to: "."
+    when: "stack == 'python'"
+
+  # ASP.NET Core — JwtBearer bound to the OIDC authority.
+  - from: files/dotnet/**/*
+    to: "."
+    when: "stack == 'dotnet'"
+
+  # Code that imports a package the manifest never installs does not build (ADR 0005).
+  - from: files/package.json
+    to: .
+    onConflict: merge-json
+    when: "stack == 'typescript' || stack == 'node'"
+
+  # Declared, not installed by a post-apply step: a package added after generation is
+  # missing from the first install (ADR 0005, spec 003).
+  - from: files/pyproject.toml
+    to: .
+    onConflict: merge
+    when: "stack == 'python'"
+
+postApply:
+  # Safe unattended: adds two well-known packages, writes nothing outside node_modules
+  # and the lockfile, and a failure leaves the generated source intact.
+  - run: npm install openid-client@^6.8.4 jose@^6.2.3
+    when: "stack == 'typescript'"
+    optional: true
+
+  - run: npm install jose@^6.2.3
+    when: "stack == 'node'"
+    optional: true
+
+  # Safe unattended: installs from the manifest this layer just wrote, nothing else.
+  - run: python -m pip install -r requirements-auth-oidc.txt
+    when: "stack == 'python'"
+    optional: true

package/templates/layers/auth-oidc/files/dotnet/.env.oidc.example

@@ -0,0 +1,14 @@
+# OIDC — environment form of the "Oidc" configuration section.
+# ASP.NET Core maps the double underscore to a section separator.
+# In local development prefer: dotnet user-secrets set "Oidc:Authority" "..."
+
+# Required
+Oidc__Authority=https://your-tenant.example-idp.com
+Oidc__Audience=
+
+# Optional — defaults live in Auth/OidcOptions.cs
+# Oidc__Scopes={{ oidcScopes }}
+# Oidc__RoleClaim={{ oidcRoleClaim }}
+# Oidc__ClockSkewSeconds=30
+# Dev only: allow a plaintext http authority such as a local Keycloak.
+# Oidc__RequireHttpsMetadata=true

package/templates/layers/auth-oidc/files/dotnet/docs/auth-oidc.md

@@ -0,0 +1,73 @@
+# Authentication — OpenID Connect
+
+{{ solutionName | title }} is an OAuth2 **resource server**. It does not log users in; it
+validates the bearer tokens an identity provider already issued. `Authority` drives OIDC
+discovery, so endpoints and signing keys are fetched and rotated without a redeploy.
+
+## Setup
+
+1. Register an **API / resource** in your identity provider and note its audience identifier.
+2. Add the package:
+
+   ```bash
+   dotnet add src/{{ solutionName | pascal }}.Api package Microsoft.AspNetCore.Authentication.JwtBearer
+   ```
+
+3. Configure the `Oidc` section — `appsettings.Development.json`, user-secrets, or the
+   `Oidc__*` environment variables in `.env.oidc.example`:
+
+   ```json
+   {
+     "Oidc": {
+       "Authority": "https://your-tenant.example-idp.com",
+       "Audience": "api://invoices"
+     }
+   }
+   ```
+
+4. Wire it in `Program.cs`:
+
+   ```csharp
+   using {{ solutionName | pascal }}.Api.Auth;
+
+   builder.Services.AddOidcAuthentication(builder.Configuration);
+   builder.Services.AddScopePolicy("invoices:read", "invoices:read");
+
+   var app = builder.Build();
+
+   app.UseAuthentication();
+   app.UseAuthorization();
+   ```
+
+   Order matters: `UseAuthentication` must come before `UseAuthorization`.
+
+## Usage
+
+```csharp
+app.MapGet("/health", () => Results.Ok(new { ok = true }))
+   .AllowAnonymous();
+
+app.MapGet("/invoices", (ClaimsPrincipal user) => Results.Ok(new { requestedBy = user.Identity?.Name }))
+   .RequireAuthorization("invoices:read");
+
+app.MapDelete("/invoices/{id}", (string id) => Results.NoContent())
+   .RequireAuthorization(policy => policy.RequireRole("admin"));
+```
+
+- `RequireAuthorization()` with no argument requires only a valid token.
+- Roles are read from the `{{ oidcRoleClaim }}` claim, so `RequireRole` works directly.
+- `AddScopePolicy` builds a policy for a single OAuth2 scope, which the space-delimited
+  `scope` claim otherwise cannot express.
+
+To deny by default, add a fallback policy:
+
+```csharp
+builder.Services.AddAuthorizationBuilder()
+    .SetFallbackPolicy(new AuthorizationPolicyBuilder().RequireAuthenticatedUser().Build());
+```
+
+## Configuration
+
+`Auth/OidcOptions.cs` is the single source. Every value has a typed default there and is
+bound from the `Oidc` configuration section; validation runs at startup, so a missing
+`Authority` or `Audience` fails the host instead of surfacing as a 500 later.

package/templates/layers/auth-oidc/files/dotnet/src/__solutionName.pascal__.Api/Auth/OidcAuthenticationExtensions.cs

@@ -0,0 +1,65 @@
+using Microsoft.AspNetCore.Authentication.JwtBearer;
+using Microsoft.AspNetCore.Authorization;
+using Microsoft.IdentityModel.Tokens;
+
+namespace {{ solutionName | pascal }}.Api.Auth;
+
+public static class OidcAuthenticationExtensions
+{
+    /// <summary>Wires JWT bearer validation against the OIDC authority. Call before Build().</summary>
+    public static IServiceCollection AddOidcAuthentication(
+        this IServiceCollection services,
+        IConfiguration configuration)
+    {
+        var section = configuration.GetSection(OidcOptions.SectionName);
+
+        // Fail at startup rather than on the first request with a 500.
+        services.AddOptions<OidcOptions>()
+            .Bind(section)
+            .Validate(o => !string.IsNullOrWhiteSpace(o.Authority), $"{OidcOptions.SectionName}:Authority is required")
+            .Validate(o => !string.IsNullOrWhiteSpace(o.Audience), $"{OidcOptions.SectionName}:Audience is required")
+            .ValidateOnStart();
+
+        var options = section.Get<OidcOptions>() ?? new OidcOptions();
+
+        services
+            .AddAuthentication(JwtBearerDefaults.AuthenticationScheme)
+            .AddJwtBearer(bearer =>
+            {
+                // Authority drives discovery, so signing keys rotate without a redeploy.
+                bearer.Authority = options.Authority;
+                bearer.Audience = options.Audience;
+                bearer.RequireHttpsMetadata = options.RequireHttpsMetadata;
+                // Keep the original OIDC claim names instead of the legacy SOAP mappings.
+                bearer.MapInboundClaims = false;
+                bearer.TokenValidationParameters = new TokenValidationParameters
+                {
+                    ValidateIssuer = true,
+                    ValidateAudience = true,
+                    ValidateLifetime = true,
+                    ValidateIssuerSigningKey = true,
+                    ClockSkew = TimeSpan.FromSeconds(options.ClockSkewSeconds),
+                    NameClaimType = OidcOptions.SubjectClaim,
+                    RoleClaimType = options.RoleClaim,
+                };
+            });
+
+        services.AddSingleton<IAuthorizationHandler, ScopeAuthorizationHandler>();
+        services.AddAuthorization();
+
+        return services;
+    }
+
+    /// <summary>Registers a named policy that requires a single OAuth2 scope.</summary>
+    public static IServiceCollection AddScopePolicy(this IServiceCollection services, string policyName, string scope)
+    {
+        services.AddAuthorizationBuilder()
+            .AddPolicy(policyName, policy =>
+            {
+                policy.RequireAuthenticatedUser();
+                policy.Requirements.Add(new ScopeRequirement(scope));
+            });
+
+        return services;
+    }
+}

package/templates/layers/auth-oidc/files/dotnet/src/__solutionName.pascal__.Api/Auth/OidcOptions.cs

@@ -0,0 +1,25 @@
+namespace {{ solutionName | pascal }}.Api.Auth;
+
+/// <summary>The only place OIDC configuration is defined. Bound from the "Oidc" section.</summary>
+public sealed class OidcOptions
+{
+    public const string SectionName = "Oidc";
+
+    /// <summary>Protocol claim name, not a tunable.</summary>
+    public const string SubjectClaim = "sub";
+
+    /// <summary>Issuer URL. Drives discovery of every endpoint and signing key.</summary>
+    public string Authority { get; set; } = string.Empty;
+
+    public string Audience { get; set; } = string.Empty;
+
+    public string Scopes { get; set; } = "{{ oidcScopes }}";
+
+    public string RoleClaim { get; set; } = "{{ oidcRoleClaim }}";
+
+    /// <summary>Tolerance for clock drift between this service and the provider.</summary>
+    public int ClockSkewSeconds { get; set; } = 30;
+
+    /// <summary>Only turn off for a local plaintext provider.</summary>
+    public bool RequireHttpsMetadata { get; set; } = true;
+}

package/templates/layers/auth-oidc/files/dotnet/src/__solutionName.pascal__.Api/Auth/ScopeRequirement.cs

@@ -0,0 +1,29 @@
+using Microsoft.AspNetCore.Authorization;
+
+namespace {{ solutionName | pascal }}.Api.Auth;
+
+/// <summary>OAuth2 delivers scopes as one space-delimited claim, so the built-in claim check is not enough.</summary>
+public sealed class ScopeRequirement(string scope) : IAuthorizationRequirement
+{
+    public string Scope { get; } = scope;
+}
+
+public sealed class ScopeAuthorizationHandler : AuthorizationHandler<ScopeRequirement>
+{
+    private const string ScopeClaim = "scope";
+
+    protected override Task HandleRequirementAsync(
+        AuthorizationHandlerContext context,
+        ScopeRequirement requirement)
+    {
+        var granted = context.User.FindAll(ScopeClaim)
+            .SelectMany(claim => claim.Value.Split(' ', StringSplitOptions.RemoveEmptyEntries));
+
+        if (granted.Contains(requirement.Scope))
+        {
+            context.Succeed(requirement);
+        }
+
+        return Task.CompletedTask;
+    }
+}

package/templates/layers/auth-oidc/files/node/.env.oidc.example

@@ -0,0 +1,14 @@
+# OIDC — copy these into .env and fill them in.
+# Discovery reads every endpoint and signing key from OIDC_ISSUER/.well-known/openid-configuration.
+
+# Required
+OIDC_ISSUER=https://your-tenant.example-idp.com
+OIDC_AUDIENCE=
+
+# Optional — defaults live in src/auth/auth.config.ts
+# OIDC_SCOPES={{ oidcScopes }}
+# OIDC_ROLE_CLAIM={{ oidcRoleClaim }}
+# OIDC_ALGORITHMS=RS256
+# OIDC_CLOCK_TOLERANCE_SECONDS=5
+# OIDC_JWKS_CACHE_SECONDS=600
+# OIDC_DISCOVERY_TIMEOUT_MS=5000

package/templates/layers/auth-oidc/files/node/docs/auth-oidc.md

@@ -0,0 +1,66 @@
+# Authentication — OpenID Connect
+
+{{ solutionName | title }} is an OAuth2 **resource server**. It does not log users in; it
+validates the bearer tokens an identity provider already issued. Signing keys come from the
+provider's JWKS, discovered from the issuer, so key rotation needs no redeploy.
+
+## Setup
+
+1. Register an **API / resource** in your identity provider and note its audience identifier.
+2. Copy `.env.oidc.example` into `.env` and fill in `OIDC_ISSUER` and `OIDC_AUDIENCE`.
+3. Install the runtime dependency if the generator did not:
+
+   ```bash
+   npm install jose
+   ```
+
+4. Register the module in your root module:
+
+   ```ts
+   import { AuthModule } from './auth/auth.module';
+
+   @Module({ imports: [AuthModule] })
+   export class AppModule {}
+   ```
+
+`AuthModule` installs a global `APP_GUARD`, so **every route requires a valid token by
+default**.
+
+## Usage
+
+```ts
+import { Public, Roles, Scopes, CurrentUser } from './auth/auth.decorators';
+import type { AuthenticatedUser } from './auth/jwt-verifier';
+
+@Controller('invoices')
+export class InvoicesController {
+  @Get('health')
+  @Public()
+  health() {
+    return { ok: true };
+  }
+
+  @Get()
+  @Scopes('invoices:read')
+  list(@CurrentUser() user: AuthenticatedUser) {
+    return { requestedBy: user.sub };
+  }
+
+  @Delete(':id')
+  @Roles('admin')
+  remove() {
+    return { deleted: true };
+  }
+}
+```
+
+- `@Public()` opts a route out of authentication.
+- `@Roles(...)` requires **one of** the listed roles, read from the `{{ oidcRoleClaim }}` claim.
+- `@Scopes(...)` requires **all** listed scopes from the token's `scope` claim.
+
+## Configuration
+
+`src/auth/auth.config.ts` is the single source. Every value has a typed default there and an
+environment override; no other module reads `process.env`. Only asymmetric algorithms are
+accepted (`RS256` by default) — a resource server must never trust an HMAC-signed token it
+did not issue.