feat(ci): catalogue-drift gate for @RequirePrivilege/@RequireRole literals (ADR-0025) (#211)
## Summary
Phase 3 (and last) of [ADR-0025](docs/decisions/0025-authorization-model-privileges-roles-scopes.md)'s implementation phasing (§"More Information" / §347): a small CI gate that asserts every string literal passed to the authorization decorators belongs to the closed catalogue declared in `libs/shared/auth/src/lib/authorization.types.ts`.
The TypeScript decorator signatures (`(...privileges: [Privilege, ...Privilege[]])`) already enforce this at compile time. The gate is **defence-in-depth** against the escape hatches the type system cannot catch:
- explicit `as Privilege` / `as FunctionalRole` casts (`'Portal.Foo' as Privilege`),
- the rare case where a developer hand-edits the catalogue type union without updating the runtime constant.
Runs in `<1s`, so it rides the existing `check` CI job rather than spinning up its own.
## What lands
| File | Role |
| --- | --- |
| `scripts/check-catalogue-drift.mjs` | The gate. TypeScript compiler API. Parses `authorization.types.ts` to extract the catalogues, walks every `.ts` file under `apps/` and `libs/`, finds each `CallExpression` whose callee identifier matches `RequirePrivilege` / `RequireRole`, validates every string-literal argument. Non-literal args are skipped (the TypeScript signature catches them already). Reports grouped by file with `line:column` per violation, exits 1 on drift. |
| `scripts/check-catalogue-drift.spec.mjs` | 13 tests via `node --test` (built-in runner, no Vitest dep). Covers catalogue parsing, file-level violation detection, workspace-wide aggregation, skipped folders, gen-stub exclusion, line/column reporting. |
| `package.json` | `ci:catalogue-drift` + `ci:catalogue-drift:test` scripts. |
| `.gitea/workflows/ci.yml` | The existing `check` job now runs the gate's unit tests first (fail-fast if the gate itself is broken), then the gate against the live workspace. |
## Notes for the reviewer
- **Why not an ESLint custom rule.** ADR-0025 §347 floats either option. The ESLint route would give editor-time feedback (red squiggles) but means standing up a local ESLint plugin lib — net ~300 lines of plumbing for a gate the TypeScript signature already enforces in real time via the literal-union types. The pnpm-script route mirrors the existing `ci:gzip-budgets` pattern; ~250 lines including tests; runs in the same `check` CI job that already installs deps. Editor feedback is **already provided by `tsc`**, so the gate's job reduces to "catch escape hatches in CI", which the script does fine.
- **Why `node --test` rather than Vitest / Jest.** The script lives in `scripts/`, outside any Nx project. Wiring Vitest for one spec file would mean a vitest.config + tsconfig.spec + Nx project just to host it. Node's built-in test runner ships with the runtime we already pin (Node 24 in `.nvmrc`), no config, ~250ms wall clock for 13 tests.
- **Generated gRPC stubs are skipped.** `apps/portal-bff/src/grpc/gen/apf-ai/common.ts` defines a `roles: string[]` proto field used by the AI-bridge — entirely unrelated to the ADR-0025 functional-role catalogue. The skip list is explicit (`SKIPPED_SUBPATHS`); adding a new codegen output later is one line.
- **Spec files are NOT skipped.** `auth-guards.persona-matrix.spec.ts` references catalogue values via the decorators in its test fixtures. Those are deliberate references and must stay in sync — if a future ADR amendment removes a role, the spec catches it on the same run as the production code. Explicitly tested in `does NOT skip spec files`.
- **Non-literal arguments (variable indirection) are skipped.** A pattern like `const slug = getRole(); @RequireRole(slug)` would not be caught by string-literal inspection. This is intentional: the TypeScript decorator signature already requires `slug` to be typed `FunctionalRole`, so the type system handles it; the gate's value-add is on literal misspellings the type system cannot see past an `as Privilege` cast.
- **Self-test confirmed the gate works.** Injected `RequirePrivilege('Portal.RogueDrift')` and `RequireRole('rogue-role-x')` into an existing spec, ran `pnpm ci:catalogue-drift`, observed:
```
catalogue-drift: violations found
apps/portal-bff/src/auth/require-privilege.guard.spec.ts
135:18 @RequirePrivilege('Portal.RogueDrift') — not in PRIVILEGES
136:13 @RequireRole('rogue-role-x') — not in FUNCTIONAL_ROLES
```
Exit code 1. Reverted the injection; gate green again.
- **Adding a third decorator** (per ADR-0025's anticipated growth) is one line in `DECORATOR_TO_CATALOGUE` plus the matching test fixture. The script does not hardcode the decorator name list beyond that map.
- **Why no scope-kind check.** `@RequireScope` takes an `(req) => ScopableResource` extractor, not literals. The scope `kind` values are constrained by the `ScopeKind` discriminated union, which TypeScript enforces at every `{ kind: ... }` construction site. No literal escape hatch worth gating in v1.
## Test plan
- [x] `pnpm ci:catalogue-drift:test` — 13/13 green via `node --test`.
- [x] `pnpm ci:catalogue-drift` — clean against the live workspace: `catalogue-drift: clean (catalogues: 4 privileges, 24 roles).`
- [x] Self-test by injection — script catches `'Portal.RogueDrift'` and `'rogue-role-x'` with file:line:column, exits 1.
- [x] `pnpm exec prettier --check` on the new files — clean.
- [ ] CI run on this PR exercises the new step in the `check` job.
## What's next
ADR-0025's phasing closes with this PR. Remaining authorization work waits on [ADR-0026](docs/decisions/) (proposed) — the `Person` + `User` schema brings the Prisma-backed `user_scopes` table; that PR replaces `StubScopeResolver` with a `PrismaScopeResolver` and unlocks the first concrete `@RequireScope` consumer surfaces.
---------
Co-authored-by: Julien Gautier <julien.gautier@apf.asso.fr>
Reviewed-on: #211
This commit was merged in pull request #211.
This commit is contained in:
@@ -0,0 +1,233 @@
|
||||
/**
|
||||
* Tests for `check-catalogue-drift.mjs`. Run via:
|
||||
* node --test scripts/check-catalogue-drift.spec.mjs
|
||||
*
|
||||
* Uses Node's built-in test runner (no Vitest / Jest dependency)
|
||||
* because the script itself has no per-app project hosting it;
|
||||
* shipping a third test runner just for this one file would be
|
||||
* overkill.
|
||||
*/
|
||||
|
||||
import { describe, it } from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
|
||||
import { tmpdir } from 'node:os';
|
||||
import { join } from 'node:path';
|
||||
import {
|
||||
extractCatalogues,
|
||||
findViolationsInFile,
|
||||
scanWorkspace,
|
||||
} from './check-catalogue-drift.mjs';
|
||||
|
||||
/**
|
||||
* Build a self-contained workspace fixture with:
|
||||
* - a synthesised authorization.types.ts file mirroring the real
|
||||
* catalogue declarations,
|
||||
* - a bag of .ts files under apps/ + libs/ exercising the
|
||||
* decorators with whichever values the caller asks for.
|
||||
*/
|
||||
function makeFixture({ files }) {
|
||||
const root = mkdtempSync(join(tmpdir(), 'drift-fixture-'));
|
||||
mkdirSync(join(root, 'libs/shared/auth/src/lib'), { recursive: true });
|
||||
writeFileSync(
|
||||
join(root, 'libs/shared/auth/src/lib/authorization.types.ts'),
|
||||
`export const PRIVILEGES = [
|
||||
'Portal.Admin',
|
||||
'Portal.Auditor',
|
||||
] as const;
|
||||
export const FUNCTIONAL_ROLES = [
|
||||
'collaborateur',
|
||||
'rh',
|
||||
'dpo',
|
||||
] as const;
|
||||
export const SCOPE_KINDS = [
|
||||
'self',
|
||||
'unrestricted',
|
||||
] as const;
|
||||
`,
|
||||
);
|
||||
for (const [relativePath, contents] of Object.entries(files)) {
|
||||
const full = join(root, relativePath);
|
||||
mkdirSync(join(full, '..'), { recursive: true });
|
||||
writeFileSync(full, contents);
|
||||
}
|
||||
return root;
|
||||
}
|
||||
|
||||
describe('extractCatalogues', () => {
|
||||
it('reads the three closed catalogues from authorization.types.ts', () => {
|
||||
const root = makeFixture({ files: {} });
|
||||
const cataloguePath = join(root, 'libs/shared/auth/src/lib/authorization.types.ts');
|
||||
const cats = extractCatalogues(cataloguePath);
|
||||
assert.deepEqual([...cats.PRIVILEGES].sort(), ['Portal.Admin', 'Portal.Auditor']);
|
||||
assert.deepEqual([...cats.FUNCTIONAL_ROLES].sort(), ['collaborateur', 'dpo', 'rh']);
|
||||
});
|
||||
|
||||
it('throws when the catalogue file omits an expected declaration', () => {
|
||||
const root = mkdtempSync(join(tmpdir(), 'drift-fixture-'));
|
||||
mkdirSync(join(root, 'libs/shared/auth/src/lib'), { recursive: true });
|
||||
writeFileSync(
|
||||
join(root, 'libs/shared/auth/src/lib/authorization.types.ts'),
|
||||
`export const PRIVILEGES = ['Portal.Admin'] as const;\n`,
|
||||
);
|
||||
assert.throws(
|
||||
() => extractCatalogues(join(root, 'libs/shared/auth/src/lib/authorization.types.ts')),
|
||||
/FUNCTIONAL_ROLES/,
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe('findViolationsInFile', () => {
|
||||
const catalogues = {
|
||||
PRIVILEGES: new Set(['Portal.Admin', 'Portal.Auditor']),
|
||||
FUNCTIONAL_ROLES: new Set(['collaborateur', 'rh', 'dpo']),
|
||||
};
|
||||
|
||||
it('returns no violations on a file that uses only catalogue values', () => {
|
||||
const text = `
|
||||
class Foo {
|
||||
@RequirePrivilege('Portal.Admin')
|
||||
@RequireRole('rh', 'collaborateur')
|
||||
method() {}
|
||||
}
|
||||
`;
|
||||
const violations = findViolationsInFile('virtual.ts', catalogues, text);
|
||||
assert.equal(violations.length, 0);
|
||||
});
|
||||
|
||||
it('flags every off-catalogue privilege value', () => {
|
||||
const text = `
|
||||
class Foo {
|
||||
@RequirePrivilege('Portal.Admin', 'Portal.Bogus')
|
||||
method() {}
|
||||
}
|
||||
`;
|
||||
const violations = findViolationsInFile('virtual.ts', catalogues, text);
|
||||
assert.equal(violations.length, 1);
|
||||
assert.equal(violations[0].callee, 'RequirePrivilege');
|
||||
assert.equal(violations[0].value, 'Portal.Bogus');
|
||||
assert.equal(violations[0].catalogue, 'PRIVILEGES');
|
||||
});
|
||||
|
||||
it('flags every off-catalogue role value', () => {
|
||||
const text = `
|
||||
class Foo {
|
||||
@RequireRole('rh', 'rogue-role')
|
||||
method() {}
|
||||
}
|
||||
`;
|
||||
const violations = findViolationsInFile('virtual.ts', catalogues, text);
|
||||
assert.equal(violations.length, 1);
|
||||
assert.equal(violations[0].callee, 'RequireRole');
|
||||
assert.equal(violations[0].value, 'rogue-role');
|
||||
assert.equal(violations[0].catalogue, 'FUNCTIONAL_ROLES');
|
||||
});
|
||||
|
||||
it('skips non-literal arguments (variable indirection)', () => {
|
||||
// A real-world escape hatch — TypeScript catches this at
|
||||
// compile time via the decorator signature, the drift gate is
|
||||
// best-effort here.
|
||||
const text = `
|
||||
const slug = 'rogue-role';
|
||||
class Foo {
|
||||
@RequireRole(slug)
|
||||
method() {}
|
||||
}
|
||||
`;
|
||||
const violations = findViolationsInFile('virtual.ts', catalogues, text);
|
||||
assert.equal(violations.length, 0);
|
||||
});
|
||||
|
||||
it('also detects the literal when the decorator is invoked as a function call (non-decorator usage)', () => {
|
||||
// A test fixture might call RequirePrivilege as a function to
|
||||
// produce a decorator value for a manual UseGuards pattern; the
|
||||
// call site shape is identical so the script catches it.
|
||||
const text = `
|
||||
const dec = RequirePrivilege('Portal.Bogus');
|
||||
`;
|
||||
const violations = findViolationsInFile('virtual.ts', catalogues, text);
|
||||
assert.equal(violations.length, 1);
|
||||
assert.equal(violations[0].value, 'Portal.Bogus');
|
||||
});
|
||||
|
||||
it('reports line and column of the offending literal', () => {
|
||||
const text = ['line1', 'line2', " @RequireRole('rogue-role')"].join('\n');
|
||||
const violations = findViolationsInFile('virtual.ts', catalogues, text);
|
||||
assert.equal(violations.length, 1);
|
||||
assert.equal(violations[0].line, 3);
|
||||
// The literal starts at column 16 (0-indexed 15, +1 in the report).
|
||||
assert.equal(violations[0].column, 16);
|
||||
});
|
||||
});
|
||||
|
||||
describe('scanWorkspace', () => {
|
||||
it('returns 0 violations on a clean fixture', () => {
|
||||
const root = makeFixture({
|
||||
files: {
|
||||
'apps/x/src/main.ts': `
|
||||
class Foo {
|
||||
@RequirePrivilege('Portal.Admin')
|
||||
@RequireRole('rh', 'collaborateur')
|
||||
m() {}
|
||||
}
|
||||
`,
|
||||
},
|
||||
});
|
||||
const { violations } = scanWorkspace(root);
|
||||
assert.equal(violations.length, 0);
|
||||
});
|
||||
|
||||
it('aggregates violations across multiple files', () => {
|
||||
const root = makeFixture({
|
||||
files: {
|
||||
'apps/x/src/a.ts': `
|
||||
@RequirePrivilege('Portal.Ghost') class A {}
|
||||
`,
|
||||
'libs/y/src/b.ts': `
|
||||
@RequireRole('phantom-role') class B {}
|
||||
`,
|
||||
},
|
||||
});
|
||||
const { violations } = scanWorkspace(root);
|
||||
assert.equal(violations.length, 2);
|
||||
const values = violations.map((v) => v.value).sort();
|
||||
assert.deepEqual(values, ['Portal.Ghost', 'phantom-role']);
|
||||
});
|
||||
|
||||
it('skips dist/ and node_modules/ folders even when they contain decorator calls', () => {
|
||||
const root = makeFixture({
|
||||
files: {
|
||||
'apps/x/dist/built.ts': `@RequireRole('rogue-role') class X {}`,
|
||||
'apps/x/node_modules/whatever/foo.ts': `@RequireRole('also-rogue') class Y {}`,
|
||||
},
|
||||
});
|
||||
const { violations } = scanWorkspace(root);
|
||||
assert.equal(violations.length, 0);
|
||||
});
|
||||
|
||||
it('skips the generated gRPC stubs (different `roles` semantics)', () => {
|
||||
const root = makeFixture({
|
||||
files: {
|
||||
'apps/portal-bff/src/grpc/gen/apf-ai/common.ts': `
|
||||
// Codegen output: this is NOT an ADR-0025 decorator call,
|
||||
// it just happens to share an identifier.
|
||||
@RequireRole('not-a-real-role') class FromGen {}
|
||||
`,
|
||||
},
|
||||
});
|
||||
const { violations } = scanWorkspace(root);
|
||||
assert.equal(violations.length, 0);
|
||||
});
|
||||
|
||||
it('does NOT skip spec files (deliberate decorator usage in tests must stay in sync)', () => {
|
||||
const root = makeFixture({
|
||||
files: {
|
||||
'libs/y/src/y.spec.ts': `
|
||||
@RequireRole('rogue-role') class TestSubject {}
|
||||
`,
|
||||
},
|
||||
});
|
||||
const { violations } = scanWorkspace(root);
|
||||
assert.equal(violations.length, 1);
|
||||
});
|
||||
});
|
||||
Reference in New Issue
Block a user