feat(auth): per-service authz branch on /auth/module-identity

When the ingress annotation carries permission (+project_uuid), authorize against the tenant's orchest-api /api/authz/check (host derived from the JWT, allowlist-guarded); relay allow/deny, fail-closed 502. All-or-nothing on incomplete params; param-less requests stay identity-only (webserver case). Co-Authored-By: WOZCODE <contact@withwoz.com>
feat(orchest-identity): tenant orchest-api host derivation + allowlist
2026-08-31 19:58:21 +00:00 · 2026-08-20 10:12:45 -03:00 · 2026-08-20 10:10:43 -03:00 · 2026-08-20 10:09:31 -03:00 · 2026-08-20 10:06:02 -03:00 · 2026-08-20 10:05:26 -03:00
16 changed files with 1584 additions and 7 deletions
@@ -0,0 +1,759 @@
+# Orchest Module Identity Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add a Maestro endpoint `GET /auth/module-identity` that translates a Dadosfera session into the `X-Auth-*` identity headers Orchest's RBAC trusts, gating on a module permission and (for service ingresses) authorizing per-project against orchest-api.
+
+**Architecture:** One route serves two nginx `auth_request` callers, keyed on whether the ingress annotation carries authz query params. Phase 1: authenticate the `ddf-auth` cookie via Maestro's existing JWKS verify, gate on the module permission (seqid 31), emit identity headers, set `X-Auth-Roles: admin` for Super Admin (seqid 34). Phase 2: when the annotation carries `permission`+`project_uuid`, additionally call the calling tenant's orchest-api `/api/authz/check` (host derived from the JWT's `customer_name` + the `orchest-{module}-{customer_name}` namespace convention) and relay allow/deny, fail-closed. A small orchest-side change flips `service_access_auth_url` to build a scoped URL in Maestro mode.
+
+**Tech Stack:** NestJS (controllers/providers, Jest via `Test.createTestingModule`), Express `Request`/`Response`, `jsonwebtoken`, plain `process.env` config. Orchest side: Python (`lib/python/orchest-internals`).
+
+**Spec:** `dbt-to-orchest` repo — `docs/superpowers/specs/2026-08-20-maestro-module-identity-design.md` (the Maestro repo does not hold the spec; executors read it there).
+
+## Global Constraints
+
+- **Config via `process.env`** — Maestro reads env directly (no ConfigService). Pattern: `const X = process.env.X || '<default>'` (see `authentication.guard.ts:140`).
+- **Config values (verbatim):** `ORCHEST_MODULE_PERMISSION_SEQID` default `31` (Intelligence/"Orchest Module", `intelligence:open`); `ORCHEST_ADMIN_PERMISSION_SEQIDS` default `34` (Super Admin, `users:admin`), a comma-separated list parsed to numbers; `ORCHEST_NAMESPACE_MODULE` default `intelli` (∈ `intelli`|`process`).
+- **Token source is the `ddf-auth` COOKIE**, not the `Authorization` header (the nginx `auth_request` subrequest carries the browser cookie). Never read `Authorization` in this route.
+- **`permission`/`project_uuid` come from `request.query`** (the orchest-api-authored annotation), never from the end-user URL. The end-user URL is `X-Original-URI` and MUST NOT be read for authz.
+- **Fail-closed:** any error reaching orchest-api, or an unexpected status, → deny (never allow).
+- **`/auth/me` is not modified.** Other services depend on it.
+- **No orchest-api code change.** `/api/authz/check`, the `AuthCustom/AuthUrl` ingress path, and RBAC already exist.
+- **Namespace pattern:** `orchest-{module}-{customer_name}`. `dadosferademo2` is the one exception (being removed) — explicitly unsupported, no special-casing.
+- Branch: `feat/orchest-module-identity` (off `origin/beta`), already created.
+
+---
+
+## File Structure
+
+**Maestro (`feat/orchest-module-identity` off beta):**
+- Modify `src/modules/auth/auth.service.ts` — make `validateJwtToken` public (or add a public `verifyAccessToken` wrapper); add `authorizeOrchestServiceAccess(...)` helper (Phase 2).
+- Modify `src/modules/auth/auth.controller.ts` — add the `GET /auth/module-identity` route.
+- Create `src/modules/auth/orchest-identity.ts` — pure, testable helpers: `parseAdminSeqids(env)`, `isModuleAllowed(perms, gateSeqid)`, `isAdmin(perms, adminSeqids)`, `tenantOrchestApiHost(customerName, module)`, `isAllowedOrchestApiHost(host)`. Keeps set-membership/string logic out of the controller so it unit-tests without HTTP.
+- Create `src/modules/auth/orchest-identity.spec.ts` — unit tests for the helpers.
+- Create `src/modules/auth/module-identity.controller.spec.ts` — controller tests (mock `AuthClientService`, fake `Request`/`Response`).
+
+**dbt-to-orchest repo (Phase 2 orchest-side, separate branch there):**
+- Modify `lib/python/orchest-internals/_orchest/internals/utils.py:19-51` — `service_access_auth_url` Maestro branch.
+- Modify `lib/python/orchest-internals/tests/…` (or wherever `utils` is tested) — add the Maestro-mode case.
+
+---
+
+## PHASE 1 — Identity (webserver ingress)
+
+### Task 1: Pure helpers for permission mapping
+
+**Files:**
+- Create: `src/modules/auth/orchest-identity.ts`
+- Test: `src/modules/auth/orchest-identity.spec.ts`
+
+**Interfaces:**
+- Consumes: nothing.
+- Produces:
+  - `parseAdminSeqids(raw: string | undefined): number[]` — parse `"34"` / `"34,40"` → `[34]` / `[34,40]`; empty/undefined → `[34]`.
+  - `moduleGateSeqid(raw: string | undefined): number` — parse `ORCHEST_MODULE_PERMISSION_SEQID` → number; default `31`.
+  - `isModuleAllowed(perms: number[], gateSeqid: number): boolean`
+  - `isAdmin(perms: number[], adminSeqids: number[]): boolean`
+
+- [ ] **Step 1: Write the failing test**
+
+```typescript
+import {
+  parseAdminSeqids,
+  moduleGateSeqid,
+  isModuleAllowed,
+  isAdmin,
+} from './orchest-identity';
+
+describe('orchest-identity mapping', () => {
+  it('parseAdminSeqids: default, single, list, whitespace', () => {
+    expect(parseAdminSeqids(undefined)).toEqual([34]);
+    expect(parseAdminSeqids('')).toEqual([34]);
+    expect(parseAdminSeqids('34')).toEqual([34]);
+    expect(parseAdminSeqids('34,40')).toEqual([34, 40]);
+    expect(parseAdminSeqids(' 34 , 40 ')).toEqual([34, 40]);
+  });
+
+  it('moduleGateSeqid: default and override', () => {
+    expect(moduleGateSeqid(undefined)).toBe(31);
+    expect(moduleGateSeqid('43')).toBe(43);
+  });
+
+  it('isModuleAllowed', () => {
+    expect(isModuleAllowed([31, 5], 31)).toBe(true);
+    expect(isModuleAllowed([5, 7], 31)).toBe(false);
+    expect(isModuleAllowed([], 31)).toBe(false);
+  });
+
+  it('isAdmin: intersection', () => {
+    expect(isAdmin([31, 34], [34])).toBe(true);
+    expect(isAdmin([31], [34])).toBe(false);
+    expect(isAdmin([99], [34, 99])).toBe(true);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx jest src/modules/auth/orchest-identity.spec.ts -t 'orchest-identity mapping'`
+Expected: FAIL — `Cannot find module './orchest-identity'`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```typescript
+// src/modules/auth/orchest-identity.ts
+export function parseAdminSeqids(raw: string | undefined): number[] {
+  if (!raw || !raw.trim()) return [34];
+  return raw
+    .split(',')
+    .map((s) => Number(s.trim()))
+    .filter((n) => Number.isInteger(n));
+}
+
+export function moduleGateSeqid(raw: string | undefined): number {
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : 31;
+}
+
+export function isModuleAllowed(perms: number[], gateSeqid: number): boolean {
+  return Array.isArray(perms) && perms.includes(gateSeqid);
+}
+
+export function isAdmin(perms: number[], adminSeqids: number[]): boolean {
+  return (
+    Array.isArray(perms) && perms.some((p) => adminSeqids.includes(p))
+  );
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx jest src/modules/auth/orchest-identity.spec.ts -t 'orchest-identity mapping'`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/modules/auth/orchest-identity.ts src/modules/auth/orchest-identity.spec.ts
+git commit -m "feat(orchest-identity): permission-mapping helpers"
+```
+
+---
+
+### Task 2: Expose JWKS verify on AuthClientService
+
+**Files:**
+- Modify: `src/modules/auth/auth.service.ts:413-425`
+
+**Interfaces:**
+- Consumes: existing `getPublicKeys()`.
+- Produces: `public async verifyAccessToken(token: string): Promise<any>` — verifies the JWT against JWKS and returns its payload; throws on missing/invalid token or unknown `kid`. (Rename of the existing private `validateJwtToken`, kept callable by `validateUserSession`.)
+
+- [ ] **Step 1: Make the method public and rename**
+
+The method already does exactly the needed decode+verify. Rename `validateJwtToken` → `verifyAccessToken`, change `private` → `public`, and update its one caller.
+
+In `src/modules/auth/auth.service.ts`, change line 413:
+
+```typescript
+  public async verifyAccessToken(token: string) {
+    const decoded: any = token && jwt.decode(token, { complete: true });
+    if (!decoded) throw new Error('Invalid token');
+
+    const { kid } = decoded.header;
+    const { keys } = await this.getPublicKeys();
+    const pemValue = keys.find((k) => k.kid === kid)?.pem;
+    if (!pemValue) throw new Error('Public key not found');
+    jwt.verify(token, pemValue);
+
+    return decoded.payload;
+  }
+```
+
+And update the caller in `validateUserSession` (was line 310):
+
+```typescript
+    const payload = await this.verifyAccessToken(accessToken);
+```
+
+- [ ] **Step 2: Verify existing suite still compiles/passes for auth.service**
+
+Run: `npx jest src/modules/auth`
+Expected: PASS (no behavior change; `/auth/me` path unaffected). If there is no existing auth.service spec, run `npx tsc --noEmit` to confirm the rename compiles.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add src/modules/auth/auth.service.ts
+git commit -m "refactor(auth): expose verifyAccessToken (was private validateJwtToken)"
+```
+
+---
+
+### Task 3: `GET /auth/module-identity` — identity + module gate
+
+**Files:**
+- Modify: `src/modules/auth/auth.controller.ts` (add route beside `getMe`, ~after line 533)
+- Test: `src/modules/auth/module-identity.controller.spec.ts`
+
+**Interfaces:**
+- Consumes: `AuthClientService.verifyAccessToken` (Task 2); `parseAdminSeqids`/`moduleGateSeqid`/`isModuleAllowed`/`isAdmin` (Task 1).
+- Produces: route `GET /auth/module-identity`. On 200 sets response headers `X-Auth-User`, `X-Auth-Username`, and (admin only) `X-Auth-Roles: admin`; empty body. 401 (no/invalid cookie), 403 (lacks module gate).
+
+- [ ] **Step 1: Write the failing test**
+
+```typescript
+import { Test } from '@nestjs/testing';
+import { AuthController } from './auth.controller';
+import { AuthClientService } from './auth.service';
+
+function res() {
+  const headers: Record<string, string> = {};
+  const r: any = {
+    _status: 0,
+    _sent: undefined,
+    set: (k: string, v: string) => { headers[k] = v; return r; },
+    status: (c: number) => { r._status = c; return r; },
+    send: (b?: any) => { r._sent = b ?? ''; return r; },
+    json: (b?: any) => { r._sent = b; return r; },
+    _headers: headers,
+  };
+  return r;
+}
+function req(cookie?: string, query: Record<string, string> = {}) {
+  return { cookies: cookie ? { 'ddf-auth': cookie } : {}, query } as any;
+}
+
+describe('GET /auth/module-identity — identity', () => {
+  let controller: AuthController;
+  const auth = { verifyAccessToken: jest.fn() } as unknown as AuthClientService;
+
+  beforeEach(async () => {
+    jest.resetAllMocks();
+    process.env.ORCHEST_MODULE_PERMISSION_SEQID = '31';
+    process.env.ORCHEST_ADMIN_PERMISSION_SEQIDS = '34';
+    const mod = await Test.createTestingModule({
+      controllers: [AuthController],
+      providers: [{ provide: AuthClientService, useValue: auth }],
+    })
+      // Any other providers AuthController injects must be stubbed here the
+      // same way (ApiKeyService, DadosferaLogger, etc.). Add them as the
+      // compile step reports missing providers.
+      .compile();
+    controller = mod.get(AuthController);
+  });
+
+  it('no cookie → 401', async () => {
+    const r = res();
+    await controller.moduleIdentity(req(undefined), r);
+    expect(r._status).toBe(401);
+  });
+
+  it('valid + module + admin → 200 with X-Auth-Roles: admin', async () => {
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-1', username: 'alice', permissions: [31, 34],
+    });
+    const r = res();
+    await controller.moduleIdentity(req('tok'), r);
+    expect(r._status).toBe(200);
+    expect(r._headers['X-Auth-User']).toBe('u-1');
+    expect(r._headers['X-Auth-Username']).toBe('alice');
+    expect(r._headers['X-Auth-Roles']).toBe('admin');
+  });
+
+  it('valid + module, not admin → 200, no X-Auth-Roles', async () => {
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-2', username: 'bob', permissions: [31],
+    });
+    const r = res();
+    await controller.moduleIdentity(req('tok'), r);
+    expect(r._status).toBe(200);
+    expect(r._headers['X-Auth-Roles']).toBeUndefined();
+  });
+
+  it('valid, lacks module → 403', async () => {
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-3', username: 'carol', permissions: [5],
+    });
+    const r = res();
+    await controller.moduleIdentity(req('tok'), r);
+    expect(r._status).toBe(403);
+  });
+
+  it('verify throws (expired/bad) → 401', async () => {
+    (auth.verifyAccessToken as jest.Mock).mockRejectedValue(new Error('bad'));
+    const r = res();
+    await controller.moduleIdentity(req('tok'), r);
+    expect(r._status).toBe(401);
+  });
+
+  it('admin seqids extended by config → 200 admin', async () => {
+    process.env.ORCHEST_ADMIN_PERMISSION_SEQIDS = '34,99';
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-4', username: 'dana', permissions: [31, 99],
+    });
+    const r = res();
+    await controller.moduleIdentity(req('tok'), r);
+    expect(r._headers['X-Auth-Roles']).toBe('admin');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx jest src/modules/auth/module-identity.controller.spec.ts`
+Expected: FAIL — `controller.moduleIdentity is not a function` (and possibly missing-provider errors, which tell you which providers to stub — add them to the `providers` array per the comment).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Add to `auth.controller.ts` (import the helpers at top; `AuthClientService` is already injected as `this.authClient`):
+
+```typescript
+import {
+  parseAdminSeqids,
+  moduleGateSeqid,
+  isModuleAllowed,
+  isAdmin,
+} from './orchest-identity';
+```
+
+```typescript
+  @Get('module-identity')
+  async moduleIdentity(@Req() req: Request, @Res() res: Response) {
+    const token = req.cookies?.['ddf-auth'];
+    if (!token) {
+      return res.status(401).send();
+    }
+
+    let payload: any;
+    try {
+      payload = await this.authClient.verifyAccessToken(token);
+    } catch (e) {
+      return res.status(401).send();
+    }
+
+    const perms: number[] = payload?.permissions ?? [];
+    const gate = moduleGateSeqid(process.env.ORCHEST_MODULE_PERMISSION_SEQID);
+    if (!isModuleAllowed(perms, gate)) {
+      return res.status(403).send();
+    }
+
+    res.set('X-Auth-User', String(payload.user_id));
+    res.set('X-Auth-Username', String(payload.username ?? ''));
+    if (isAdmin(perms, parseAdminSeqids(process.env.ORCHEST_ADMIN_PERMISSION_SEQIDS))) {
+      res.set('X-Auth-Roles', 'admin');
+    }
+
+    // Phase 2 authz branch is inserted here (Task 5) before the 200.
+    return res.status(200).send();
+  }
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx jest src/modules/auth/module-identity.controller.spec.ts`
+Expected: PASS (all identity cases).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/modules/auth/auth.controller.ts src/modules/auth/module-identity.controller.spec.ts
+git commit -m "feat(auth): GET /auth/module-identity — identity + module gate"
+```
+
+---
+
+## PHASE 2 — Per-service authz
+
+### Task 4: Tenant orchest-api host derivation + allowlist
+
+**Files:**
+- Modify: `src/modules/auth/orchest-identity.ts`
+- Modify: `src/modules/auth/orchest-identity.spec.ts`
+
+**Interfaces:**
+- Consumes: nothing.
+- Produces:
+  - `tenantOrchestApiHost(customerName: string, module: string): string` — returns `orchest-api.orchest-{module}-{customerName}.svc.cluster.local`.
+  - `isAllowedOrchestApiHost(host: string): boolean` — matches `^orchest-api\.orchest-(intelli|process)-[a-z0-9-]+\.svc\.cluster\.local$`.
+  - `namespaceModule(raw: string | undefined): 'intelli' | 'process'` — parse `ORCHEST_NAMESPACE_MODULE`; default `intelli`; anything not `process` → `intelli`.
+
+- [ ] **Step 1: Write the failing test (append to orchest-identity.spec.ts)**
+
+```typescript
+import {
+  tenantOrchestApiHost,
+  isAllowedOrchestApiHost,
+  namespaceModule,
+} from './orchest-identity';
+
+describe('orchest-identity tenant routing', () => {
+  it('namespaceModule default and values', () => {
+    expect(namespaceModule(undefined)).toBe('intelli');
+    expect(namespaceModule('process')).toBe('process');
+    expect(namespaceModule('garbage')).toBe('intelli');
+  });
+
+  it('tenantOrchestApiHost builds the namespace pattern', () => {
+    expect(tenantOrchestApiHost('acme', 'intelli')).toBe(
+      'orchest-api.orchest-intelli-acme.svc.cluster.local',
+    );
+    expect(tenantOrchestApiHost('acme', 'process')).toBe(
+      'orchest-api.orchest-process-acme.svc.cluster.local',
+    );
+  });
+
+  it('isAllowedOrchestApiHost guards against malformed values', () => {
+    expect(
+      isAllowedOrchestApiHost('orchest-api.orchest-intelli-acme.svc.cluster.local'),
+    ).toBe(true);
+    expect(isAllowedOrchestApiHost('evil.example.com')).toBe(false);
+    expect(
+      isAllowedOrchestApiHost('orchest-api.orchest-intelli-.svc.cluster.local'),
+    ).toBe(false);
+    expect(
+      isAllowedOrchestApiHost('orchest-api.orchest-other-acme.svc.cluster.local'),
+    ).toBe(false);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx jest src/modules/auth/orchest-identity.spec.ts -t 'tenant routing'`
+Expected: FAIL — the three functions are not exported.
+
+- [ ] **Step 3: Write minimal implementation (append to orchest-identity.ts)**
+
+```typescript
+export function namespaceModule(raw: string | undefined): 'intelli' | 'process' {
+  return raw === 'process' ? 'process' : 'intelli';
+}
+
+export function tenantOrchestApiHost(
+  customerName: string,
+  module: string,
+): string {
+  return `orchest-api.orchest-${module}-${customerName}.svc.cluster.local`;
+}
+
+const ORCHEST_API_HOST_RE =
+  /^orchest-api\.orchest-(intelli|process)-[a-z0-9-]+\.svc\.cluster\.local$/;
+
+export function isAllowedOrchestApiHost(host: string): boolean {
+  return ORCHEST_API_HOST_RE.test(host);
+}
+```
+
+**Slug-normalization note (verify during implementation):** confirm the
+JWT's `customer_name` is *exactly* the namespace slug (lowercase, kebab, no
+spaces). If it is not, normalize deterministically inside
+`tenantOrchestApiHost` (e.g. `customerName.toLowerCase().replace(/[^a-z0-9-]/g, '-')`)
+and extend the test with the raw→normalized case. Do NOT guess the rule —
+inspect a real token or ask the team.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx jest src/modules/auth/orchest-identity.spec.ts -t 'tenant routing'`
+Expected: PASS.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/modules/auth/orchest-identity.ts src/modules/auth/orchest-identity.spec.ts
+git commit -m "feat(orchest-identity): tenant orchest-api host derivation + allowlist"
+```
+
+---
+
+### Task 5: authz branch — call `/api/authz/check`, relay, fail-closed
+
+**Files:**
+- Modify: `src/modules/auth/auth.service.ts` (add `authorizeOrchestServiceAccess`)
+- Modify: `src/modules/auth/auth.controller.ts` (insert the authz branch in `moduleIdentity`)
+- Modify: `src/modules/auth/module-identity.controller.spec.ts`
+
+**Interfaces:**
+- Consumes: `tenantOrchestApiHost`, `isAllowedOrchestApiHost`, `namespaceModule` (Task 4); an HTTP client. Maestro uses gRPC for its own services but plain HTTP for this cross-service call — use `axios` if already a dependency, else the `@nestjs/axios` `HttpService`; confirm which is present before writing (grep `import axios` / `HttpService`).
+- Produces: `AuthClientService.authorizeOrchestServiceAccess(args: { host: string; permission: string; projectUuid?: string; headers: Record<string,string> }): Promise<'allow' | 'deny' | 'error'>` — GET `http://{host}/api/authz/check?permission=…[&project_uuid=…]` with the identity headers; 200→`allow`, 403→`deny`, anything else/throw→`error`.
+
+- [ ] **Step 1: Write the failing test (append to module-identity.controller.spec.ts)**
+
+```typescript
+describe('GET /auth/module-identity — per-service authz', () => {
+  let controller: AuthController;
+  const auth = {
+    verifyAccessToken: jest.fn(),
+    authorizeOrchestServiceAccess: jest.fn(),
+  } as unknown as AuthClientService;
+
+  beforeEach(async () => {
+    jest.resetAllMocks();
+    process.env.ORCHEST_MODULE_PERMISSION_SEQID = '31';
+    process.env.ORCHEST_ADMIN_PERMISSION_SEQIDS = '34';
+    process.env.ORCHEST_NAMESPACE_MODULE = 'intelli';
+    const mod = await Test.createTestingModule({
+      controllers: [AuthController],
+      providers: [{ provide: AuthClientService, useValue: auth }],
+    }).compile(); // add the same stubbed providers as Task 3
+    controller = mod.get(AuthController);
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-1', username: 'alice', permissions: [31], customer_name: 'acme',
+    });
+  });
+
+  const q = { permission: 'session.open', project_uuid: 'p-1' };
+
+  it('has grant → 200 and calls the tenant host', async () => {
+    (auth.authorizeOrchestServiceAccess as jest.Mock).mockResolvedValue('allow');
+    const r = res();
+    await controller.moduleIdentity(req('tok', q), r);
+    expect(r._status).toBe(200);
+    expect(auth.authorizeOrchestServiceAccess).toHaveBeenCalledWith(
+      expect.objectContaining({
+        host: 'orchest-api.orchest-intelli-acme.svc.cluster.local',
+        permission: 'session.open',
+        projectUuid: 'p-1',
+      }),
+    );
+  });
+
+  it('lacks grant → 403', async () => {
+    (auth.authorizeOrchestServiceAccess as jest.Mock).mockResolvedValue('deny');
+    const r = res();
+    await controller.moduleIdentity(req('tok', q), r);
+    expect(r._status).toBe(403);
+  });
+
+  it('orchest-api error → 502 (fail-closed)', async () => {
+    (auth.authorizeOrchestServiceAccess as jest.Mock).mockResolvedValue('error');
+    const r = res();
+    await controller.moduleIdentity(req('tok', q), r);
+    expect(r._status).toBe(502);
+  });
+
+  it('permission without project_uuid → 403 (all-or-nothing)', async () => {
+    const r = res();
+    await controller.moduleIdentity(req('tok', { permission: 'session.open' }), r);
+    expect(r._status).toBe(403);
+    expect(auth.authorizeOrchestServiceAccess).not.toHaveBeenCalled();
+  });
+
+  it('no authz params → 200 identity-only (webserver case)', async () => {
+    const r = res();
+    await controller.moduleIdentity(req('tok', {}), r);
+    expect(r._status).toBe(200);
+    expect(auth.authorizeOrchestServiceAccess).not.toHaveBeenCalled();
+  });
+
+  it('malformed customer_name → host fails allowlist → 403, no call', async () => {
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-1', username: 'alice', permissions: [31], customer_name: 'Bad Name!',
+    });
+    const r = res();
+    await controller.moduleIdentity(req('tok', q), r);
+    expect(r._status).toBe(403);
+    expect(auth.authorizeOrchestServiceAccess).not.toHaveBeenCalled();
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `npx jest src/modules/auth/module-identity.controller.spec.ts -t 'per-service authz'`
+Expected: FAIL — `authorizeOrchestServiceAccess` undefined / authz branch absent.
+
+- [ ] **Step 3a: Implement the service helper**
+
+In `auth.service.ts` (use the HTTP client confirmed in the Interfaces note; `axios` shown):
+
+```typescript
+  public async authorizeOrchestServiceAccess(args: {
+    host: string;
+    permission: string;
+    projectUuid?: string;
+    headers: Record<string, string>;
+  }): Promise<'allow' | 'deny' | 'error'> {
+    const params: Record<string, string> = { permission: args.permission };
+    if (args.projectUuid) params.project_uuid = args.projectUuid;
+    try {
+      const resp = await axios.get(`http://${args.host}/api/authz/check`, {
+        params,
+        headers: args.headers,
+        timeout: 5000,
+        validateStatus: () => true, // never throw on 4xx/5xx; we branch below
+      });
+      if (resp.status === 200) return 'allow';
+      if (resp.status === 403) return 'deny';
+      return 'error';
+    } catch (e) {
+      return 'error';
+    }
+  }
+```
+
+- [ ] **Step 3b: Insert the authz branch in the controller**
+
+Replace the `// Phase 2 authz branch is inserted here` marker (Task 3) with:
+
+```typescript
+    const permission = req.query?.permission as string | undefined;
+    const projectUuid = req.query?.project_uuid as string | undefined;
+    if (permission) {
+      // Service-ingress caller: authorize per-project. All-or-nothing —
+      // an incomplete annotation must not silently skip the check.
+      if (!projectUuid) {
+        return res.status(403).send();
+      }
+      const module = namespaceModule(process.env.ORCHEST_NAMESPACE_MODULE);
+      const host = tenantOrchestApiHost(String(payload.customer_name ?? ''), module);
+      if (!isAllowedOrchestApiHost(host)) {
+        return res.status(403).send();
+      }
+      const identityHeaders: Record<string, string> = {
+        'X-Auth-User': String(payload.user_id),
+        'X-Auth-Username': String(payload.username ?? ''),
+      };
+      if (isAdmin(perms, parseAdminSeqids(process.env.ORCHEST_ADMIN_PERMISSION_SEQIDS))) {
+        identityHeaders['X-Auth-Roles'] = 'admin';
+      }
+      const decision = await this.authClient.authorizeOrchestServiceAccess({
+        host,
+        permission,
+        projectUuid,
+        headers: identityHeaders,
+      });
+      if (decision === 'deny') return res.status(403).send();
+      if (decision === 'error') return res.status(502).send();
+      // 'allow' falls through to the 200 below (identity headers already set).
+    }
+
+    return res.status(200).send();
+```
+
+Add the imports `tenantOrchestApiHost`, `isAllowedOrchestApiHost`, `namespaceModule` to the existing `./orchest-identity` import line.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `npx jest src/modules/auth/module-identity.controller.spec.ts`
+Expected: PASS (identity + per-service authz suites).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add src/modules/auth/auth.service.ts src/modules/auth/auth.controller.ts src/modules/auth/module-identity.controller.spec.ts
+git commit -m "feat(auth): per-service authz branch on /auth/module-identity"
+```
+
+---
+
+### Task 6: orchest-side — scope the Maestro service auth-url (dbt-to-orchest repo)
+
+**Files:**
+- Modify: `lib/python/orchest-internals/_orchest/internals/utils.py:19-51` (`service_access_auth_url`)
+- Test: the module's existing test (grep `service_access_auth_url` under `lib/python/…/tests`; if none, create `lib/python/orchest-internals/tests/test_service_access_auth_url.py`)
+
+**This task is in the `dbt-to-orchest` repo, not Maestro.** Do it on a branch there (e.g. off the current RBAC branch). It has no dependency on Tasks 1-5 compiling, but the annotation it produces is what Task 5 consumes at runtime.
+
+**Interfaces:**
+- Consumes: nothing new.
+- Produces: `service_access_auth_url(base_auth_url, permission, project_uuid, auth_custom)` — in Maestro mode (`auth_custom=True`), returns `f"{base_auth_url}?permission={permission}"` (plus `&project_uuid=…` when set) instead of returning `base_auth_url` unchanged.
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+from _orchest.internals.utils import service_access_auth_url
+
+def test_maestro_mode_appends_scoped_params():
+    url = service_access_auth_url(
+        "http://maestro/auth/module-identity", "session.open", "p-1",
+        auth_custom=True,
+    )
+    assert url == (
+        "http://maestro/auth/module-identity?permission=session.open&project_uuid=p-1"
+    )
+
+def test_maestro_mode_without_project_uuid():
+    url = service_access_auth_url(
+        "http://maestro/auth/module-identity", "project.view", None,
+        auth_custom=True,
+    )
+    assert url == "http://maestro/auth/module-identity?permission=project.view"
+
+def test_local_mode_unchanged():
+    url = service_access_auth_url(
+        "http://auth-server/auth", "session.open", "p-1", auth_custom=False,
+    )
+    assert url == (
+        "http://auth-server/auth/service-access?permission=session.open&project_uuid=p-1"
+    )
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run (in the pod or a venv with the lib on path):
+`python -m pytest lib/python/orchest-internals/tests/test_service_access_auth_url.py -q`
+Expected: FAIL on the two Maestro cases (current code returns the base URL unchanged).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Replace the `if auth_custom:` short-circuit in `utils.py`:
+
+```python
+    if auth_custom:
+        # Maestro mode: no /auth/service-access sibling route — the unified
+        # /auth/module-identity route authorizes when the annotation carries
+        # the scope. Append the same permission/project_uuid params. (Maestro
+        # derives the tenant orchest-api host from the JWT, not from the URL.)
+        query = f"permission={permission}"
+        if project_uuid:
+            query += f"&project_uuid={project_uuid}"
+        return f"{base_auth_url}?{query}"
+```
+
+Update the docstring's "falls back to the plain base_auth_url" paragraph to describe the new scoped behavior.
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `python -m pytest lib/python/orchest-internals/tests/test_service_access_auth_url.py -q`
+Expected: PASS (all three).
+
+- [ ] **Step 5: Commit (dbt-to-orchest repo)**
+
+```bash
+git add lib/python/orchest-internals/_orchest/internals/utils.py lib/python/orchest-internals/tests/test_service_access_auth_url.py
+git commit -m "feat(rbac): scope Maestro-mode service auth-url (close direct-URL bypass)"
+```
+
+---
+
+## Deployment & manual verification (after Tasks 1-6)
+
+Not code steps — run after merging, per the spec §8/§10.
+
+- [ ] **Maestro env** on the Orchest-serving deployment: `ORCHEST_MODULE_PERMISSION_SEQID=31`, `ORCHEST_ADMIN_PERMISSION_SEQIDS=34`, `ORCHEST_NAMESPACE_MODULE=intelli`.
+- [ ] **OrchestCluster spec** (webserver ingress): `AuthCustom: true`, `AuthUrl: http://maestro.<maestro-ns>.svc.cluster.local/auth/module-identity`, `AuthSignin: <platform login URL>`.
+- [ ] **⚠️ celery-worker rebuild (Phase 2 / Task 6):** `service_access_auth_url` runs in the **celery-worker baked image** — rebuild + roll it, and verify the scoped annotation on a **freshly launched** service ingress (`kubectl get ingress …`), never an existing one. (This gotcha cost a debugging cycle last week; see `docs/source/development/building_images_minikube.md`.)
+- [ ] **Verify path A (spec §10):** curl-drive orchest-api with the `X-Auth-*` headers Maestro would set and watch the RBAC ladder + `external_admin` resolve, before standing up real Maestro.
+- [ ] **Forgery checks (spec §9.11, §9.12):** a non-admin's forged `X-Auth-Roles: admin` through the ingress must not reach orchest-api as admin; `?permission=…` appended to the app URL must not trigger an authz check.
+
+---
+
+## Self-Review
+
+**Spec coverage:**
+- §4.1 cookie auth + JWKS reuse → Task 2 (expose verify) + Task 3 (read cookie).
+- §4.2 ladder (401/403/200 + authz + all-or-nothing + no refresh) → Task 3 (401/403/200) + Task 5 (authz, 502, all-or-nothing).
+- §4.3 three headers, no email → Task 3 (sets exactly the three; email never set).
+- §5 module gate + admin set (config, list) → Task 1 + Task 3.
+- §5.1 tenant routing (namespace pattern, allowlist, slug note, dadosferademo2) → Task 4 + Task 5.
+- §6 forgery boundary → deployment verification checklist.
+- §7 service_access_auth_url scoping → Task 6.
+- §8 deployment config → deployment checklist.
+- §9 tests 1-12 → Tasks 1/3 (1-5), Task 5 (6-10), deployment checklist (11-12).
+- §10 minikube verification → deployment checklist.
+- §11 phase split → Phase 1 (Tasks 1-3) / Phase 2 (Tasks 4-6).
+
+**Placeholder scan:** none — every code step has real content; the only deliberately-open items are flagged verify-steps (HTTP client choice in Task 5; `customer_name` slug normalization in Task 4), each with an explicit instruction to inspect rather than guess.
+
+**Type consistency:** `verifyAccessToken` (Task 2) consumed in Tasks 3/5; `moduleIdentity(req,res)` signature identical across Tasks 3/5; helper names (`parseAdminSeqids`, `moduleGateSeqid`, `isModuleAllowed`, `isAdmin`, `tenantOrchestApiHost`, `isAllowedOrchestApiHost`, `namespaceModule`) defined in Tasks 1/4 and used verbatim in Tasks 3/5; `authorizeOrchestServiceAccess` return union `'allow'|'deny'|'error'` consistent between service (Task 5 3a) and controller (Task 5 3b).
@@ -900,6 +900,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -949,6 +952,9 @@
            "connections"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -997,6 +1003,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -1033,6 +1042,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -1066,6 +1078,9 @@
            "connections"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -2403,6 +2418,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -2486,6 +2504,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -2525,6 +2546,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -2564,6 +2588,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -2601,6 +2628,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -2640,6 +2670,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -2681,6 +2714,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -2722,6 +2758,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3071,6 +3110,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3120,6 +3162,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3190,6 +3235,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3230,6 +3278,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3270,6 +3321,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3310,6 +3364,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3350,6 +3407,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3397,6 +3457,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3442,6 +3505,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3490,6 +3556,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3528,6 +3597,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3586,6 +3658,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3634,6 +3709,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3674,6 +3752,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3716,6 +3797,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3765,6 +3849,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3814,6 +3901,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -3861,6 +3951,9 @@
            "PipelinesV2"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4031,6 +4124,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4056,6 +4152,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4092,6 +4191,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4126,6 +4228,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4160,6 +4265,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4187,6 +4295,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4214,6 +4325,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4241,6 +4355,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4277,6 +4394,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4313,6 +4433,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4340,6 +4463,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4367,6 +4493,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4404,6 +4533,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4440,6 +4572,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4484,6 +4619,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4520,6 +4658,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4656,6 +4797,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4690,6 +4834,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4726,6 +4873,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4762,6 +4912,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4799,6 +4952,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4826,6 +4982,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -4853,6 +5012,9 @@
            "Platform API"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5264,6 +5426,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5307,6 +5472,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5416,6 +5584,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5448,6 +5619,9 @@
            "Catalog"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5490,6 +5664,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5625,6 +5802,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5683,6 +5863,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5731,6 +5914,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5824,6 +6010,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5874,6 +6063,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5932,6 +6124,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5988,6 +6183,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -6048,6 +6246,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -6088,6 +6289,9 @@
            "Catalog"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -6128,6 +6332,9 @@
            "Catalog"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -6188,6 +6395,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -6246,6 +6456,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -6622,6 +6835,9 @@
            {
              "access-token": []
            },
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -7075,6 +7291,9 @@
            "Connection Test"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -7111,6 +7330,9 @@
            "Connection Test"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -7147,6 +7369,9 @@
            "Connection Test"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -7183,6 +7408,9 @@
            "Connection Test"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -7219,6 +7447,9 @@
            "Connection Test"
          ],
          "security": [
+            {
+              "access-token": []
+            },
            {
              "access-token": []
            }
@@ -5,6 +5,9 @@ const config: Config.InitialOptions = {
  roots: ['<rootDir>/src/', '<rootDir>/test/'],
  testRegex: '.*\\.(test|spec)\\.[jt]s$',
  transform: { '\\.[jt]s$': 'ts-jest' },
+  // Dummy values for env vars read at module-import time (see the setup file),
+  // so specs importing those modules don't crash on load.
+  setupFiles: ['<rootDir>/test/jest.setup-env.ts'],
  collectCoverageFrom: ['**/*.[jt]s'],
  coverageDirectory: 'coverage',
  coveragePathIgnorePatterns: [
@@ -722,6 +722,8 @@ export const DADOSFERA_MODULES_KEYS = {
  PII: 'pii',
  EMBED: 'embedded-analytics',
  EMBED_ASSIGNED: 'embed-assigned',
+  CATALOG: 'catalog',
+  COLLECT: 'collect',
 }

 export const DADOSFERA_MODULES: Array<DadosferaModule> = [
@@ -32,6 +32,15 @@ import {
 } from '@dadosfera/protospack-v2/dist/lib/Duc/interfaces/messages';

 import { PERMISSIONS_GROUPS } from 'src/authentication/permissions.enum';
+import {
+  parseAdminSeqids,
+  moduleGateSeqid,
+  isModuleAllowed,
+  isAdmin,
+  tenantOrchestApiHost,
+  isAllowedOrchestApiHost,
+  namespaceModule,
+} from './orchest-identity';
 import {
  Authenticated,
  RequireAllPermissions,
@@ -531,4 +540,84 @@ export class AuthController {
      return res.status(200).json(user);
    }
  }
+
+  /**
+   * Ingress auth subrequest for Orchest (see dbt-to-orchest
+   * docs/superpowers/specs/2026-08-20-maestro-module-identity-design.md).
+   *
+   * Authenticates the ddf-auth cookie, gates on the module permission, and
+   * returns the X-Auth-* identity headers orchest-api trusts. Never writes
+   * cookies (an auth_request response cannot). No token refresh: an expired
+   * token is a 401 (the signin flow re-auths).
+   */
+  @Get('module-identity')
+  async moduleIdentity(@Req() req: Request, @Res() res: Response) {
+    const token = req.cookies?.['ddf-auth'];
+    if (!token) {
+      return res.status(401).send();
+    }
+
+    let payload: any;
+    try {
+      payload = await this.authClient.verifyAccessToken(token);
+    } catch (e) {
+      return res.status(401).send();
+    }
+
+    const perms: number[] = payload?.permissions ?? [];
+    const gate = moduleGateSeqid(process.env.ORCHEST_MODULE_PERMISSION_SEQID);
+    if (!isModuleAllowed(perms, gate)) {
+      return res.status(403).send();
+    }
+
+    const adminUser = isAdmin(
+      perms,
+      parseAdminSeqids(process.env.ORCHEST_ADMIN_PERMISSION_SEQIDS),
+    );
+
+    res.set('X-Auth-User', String(payload.user_id));
+    res.set('X-Auth-Username', String(payload.username ?? ''));
+    if (adminUser) {
+      res.set('X-Auth-Roles', 'admin');
+    }
+
+    // Service-ingress caller: the orchest-api-authored annotation carries the
+    // scope. Authorize per-project against the tenant's orchest-api. A
+    // param-less request is the webserver-ingress case → identity only.
+    const permission = req.query?.permission as string | undefined;
+    const projectUuid = req.query?.project_uuid as string | undefined;
+    if (permission) {
+      // All-or-nothing: an incomplete annotation must not silently skip the
+      // per-project check.
+      if (!projectUuid) {
+        return res.status(403).send();
+      }
+      const module = namespaceModule(process.env.ORCHEST_NAMESPACE_MODULE);
+      const host = tenantOrchestApiHost(
+        String(payload.customer_name ?? ''),
+        module,
+      );
+      if (!isAllowedOrchestApiHost(host)) {
+        return res.status(403).send();
+      }
+      const identityHeaders: Record<string, string> = {
+        'X-Auth-User': String(payload.user_id),
+        'X-Auth-Username': String(payload.username ?? ''),
+      };
+      if (adminUser) {
+        identityHeaders['X-Auth-Roles'] = 'admin';
+      }
+      const decision = await this.authClient.authorizeOrchestServiceAccess({
+        host,
+        permission,
+        projectUuid,
+        headers: identityHeaders,
+      });
+      if (decision === 'deny') return res.status(403).send();
+      if (decision === 'error') return res.status(502).send();
+      // 'allow' falls through to the 200 (identity headers already set).
+    }
+
+    return res.status(200).send();
+  }
 }
@@ -9,6 +9,7 @@ import {
 import { ClientGrpc } from '@nestjs/microservices';
 import { DadosferaLogger } from '@dadosfera/dadosfera-logs';
 import { lastValueFrom } from 'rxjs';
+import axios from 'axios';

 import { ProtoServices } from '@dadosfera/protospack-v2/dist/lib/Duc';
 import {
@@ -307,7 +308,7 @@ export class AuthClientService implements OnModuleInit {
  }

  public async validateUserSession(accessToken: any, resourceHost: string) {
-    const payload = await this.validateJwtToken(accessToken);
+    const payload = await this.verifyAccessToken(accessToken);

    const userDto = await this.getUserfromPayload(payload);

@@ -410,7 +411,12 @@ export class AuthClientService implements OnModuleInit {
    this.logger.info('Clean cookie sessions');
  }

-  private async validateJwtToken(token: string) {
+  /**
+   * Verify a DUC access token against the JWKS and return its payload.
+   * Public so the /auth/module-identity route can authenticate the ddf-auth
+   * cookie the same way (was the private validateJwtToken).
+   */
+  public async verifyAccessToken(token: string) {
    const decoded: any = token && jwt.decode(token, { complete: true });
    if (!decoded) throw new Error('Invalid token');

@@ -492,4 +498,33 @@ export class AuthClientService implements OnModuleInit {

    return;
  }
+
+  /**
+   * Ask a tenant's orchest-api whether the acting user holds `permission` on
+   * `projectUuid` (the per-service authz half of /auth/module-identity).
+   * Fail-closed: any error / unexpected status → 'error' (the route denies).
+   */
+  public async authorizeOrchestServiceAccess(args: {
+    host: string;
+    permission: string;
+    projectUuid?: string;
+    headers: Record<string, string>;
+  }): Promise<'allow' | 'deny' | 'error'> {
+    const params: Record<string, string> = { permission: args.permission };
+    if (args.projectUuid) params.project_uuid = args.projectUuid;
+    try {
+      const resp = await axios.get(`http://${args.host}/api/authz/check`, {
+        params,
+        headers: args.headers,
+        timeout: 5000,
+        // Never throw on 4xx/5xx; branch on the status ourselves.
+        validateStatus: () => true,
+      });
+      if (resp.status === 200) return 'allow';
+      if (resp.status === 403) return 'deny';
+      return 'error';
+    } catch (e) {
+      return 'error';
+    }
+  }
 }
@@ -0,0 +1,206 @@
+import { Test } from '@nestjs/testing';
+import { DadosferaLogger } from '@dadosfera/dadosfera-logs';
+import { AuthController } from './auth.controller';
+import { AuthClientService } from './auth.service';
+import { ApiKeyService } from 'src/modules/api-key/api-key.service';
+
+function res() {
+  const headers: Record<string, string> = {};
+  const r: any = {
+    _status: 0,
+    _sent: undefined,
+    set: (k: string, v: string) => {
+      headers[k] = v;
+      return r;
+    },
+    status: (c: number) => {
+      r._status = c;
+      return r;
+    },
+    send: (b?: any) => {
+      r._sent = b ?? '';
+      return r;
+    },
+    json: (b?: any) => {
+      r._sent = b;
+      return r;
+    },
+    _headers: headers,
+  };
+  return r;
+}
+
+function req(cookie?: string, query: Record<string, string> = {}) {
+  return { cookies: cookie ? { 'ddf-auth': cookie } : {}, query } as any;
+}
+
+const loggerStub = {
+  logger: { info: jest.fn(), error: jest.fn(), warn: jest.fn() },
+} as unknown as DadosferaLogger;
+
+async function makeController(auth: AuthClientService): Promise<AuthController> {
+  const mod = await Test.createTestingModule({
+    controllers: [AuthController],
+    providers: [
+      { provide: DadosferaLogger, useValue: loggerStub },
+      { provide: AuthClientService, useValue: auth },
+      { provide: ApiKeyService, useValue: {} },
+    ],
+  }).compile();
+  return mod.get(AuthController);
+}
+
+describe('GET /auth/module-identity — identity', () => {
+  let controller: AuthController;
+  const auth = {
+    verifyAccessToken: jest.fn(),
+  } as unknown as AuthClientService;
+
+  beforeEach(async () => {
+    jest.resetAllMocks();
+    process.env.ORCHEST_MODULE_PERMISSION_SEQID = '31';
+    process.env.ORCHEST_ADMIN_PERMISSION_SEQIDS = '34';
+    controller = await makeController(auth);
+  });
+
+  it('no cookie → 401', async () => {
+    const r = res();
+    await controller.moduleIdentity(req(undefined), r);
+    expect(r._status).toBe(401);
+  });
+
+  it('valid + module + admin → 200 with X-Auth-Roles: admin', async () => {
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-1',
+      username: 'alice',
+      permissions: [31, 34],
+    });
+    const r = res();
+    await controller.moduleIdentity(req('tok'), r);
+    expect(r._status).toBe(200);
+    expect(r._headers['X-Auth-User']).toBe('u-1');
+    expect(r._headers['X-Auth-Username']).toBe('alice');
+    expect(r._headers['X-Auth-Roles']).toBe('admin');
+  });
+
+  it('valid + module, not admin → 200, no X-Auth-Roles', async () => {
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-2',
+      username: 'bob',
+      permissions: [31],
+    });
+    const r = res();
+    await controller.moduleIdentity(req('tok'), r);
+    expect(r._status).toBe(200);
+    expect(r._headers['X-Auth-Roles']).toBeUndefined();
+  });
+
+  it('valid, lacks module → 403', async () => {
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-3',
+      username: 'carol',
+      permissions: [5],
+    });
+    const r = res();
+    await controller.moduleIdentity(req('tok'), r);
+    expect(r._status).toBe(403);
+  });
+
+  it('verify throws (expired/bad) → 401', async () => {
+    (auth.verifyAccessToken as jest.Mock).mockRejectedValue(new Error('bad'));
+    const r = res();
+    await controller.moduleIdentity(req('tok'), r);
+    expect(r._status).toBe(401);
+  });
+
+  it('admin seqids extended by config → 200 admin', async () => {
+    process.env.ORCHEST_ADMIN_PERMISSION_SEQIDS = '34,99';
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-4',
+      username: 'dana',
+      permissions: [31, 99],
+    });
+    const r = res();
+    await controller.moduleIdentity(req('tok'), r);
+    expect(r._headers['X-Auth-Roles']).toBe('admin');
+  });
+});
+
+describe('GET /auth/module-identity — per-service authz', () => {
+  let controller: AuthController;
+  const auth = {
+    verifyAccessToken: jest.fn(),
+    authorizeOrchestServiceAccess: jest.fn(),
+  } as unknown as AuthClientService;
+
+  const q = { permission: 'session.open', project_uuid: 'p-1' };
+
+  beforeEach(async () => {
+    jest.resetAllMocks();
+    process.env.ORCHEST_MODULE_PERMISSION_SEQID = '31';
+    process.env.ORCHEST_ADMIN_PERMISSION_SEQIDS = '34';
+    process.env.ORCHEST_NAMESPACE_MODULE = 'intelli';
+    controller = await makeController(auth);
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-1',
+      username: 'alice',
+      permissions: [31],
+      customer_name: 'acme',
+    });
+  });
+
+  it('has grant → 200 and calls the tenant host', async () => {
+    (auth.authorizeOrchestServiceAccess as jest.Mock).mockResolvedValue('allow');
+    const r = res();
+    await controller.moduleIdentity(req('tok', q), r);
+    expect(r._status).toBe(200);
+    expect(auth.authorizeOrchestServiceAccess).toHaveBeenCalledWith(
+      expect.objectContaining({
+        host: 'orchest-api.orchest-intelli-acme.svc.cluster.local',
+        permission: 'session.open',
+        projectUuid: 'p-1',
+      }),
+    );
+  });
+
+  it('lacks grant → 403', async () => {
+    (auth.authorizeOrchestServiceAccess as jest.Mock).mockResolvedValue('deny');
+    const r = res();
+    await controller.moduleIdentity(req('tok', q), r);
+    expect(r._status).toBe(403);
+  });
+
+  it('orchest-api error → 502 (fail-closed)', async () => {
+    (auth.authorizeOrchestServiceAccess as jest.Mock).mockResolvedValue('error');
+    const r = res();
+    await controller.moduleIdentity(req('tok', q), r);
+    expect(r._status).toBe(502);
+  });
+
+  it('permission without project_uuid → 403 (all-or-nothing)', async () => {
+    const r = res();
+    await controller.moduleIdentity(req('tok', { permission: 'session.open' }), r);
+    expect(r._status).toBe(403);
+    expect(auth.authorizeOrchestServiceAccess).not.toHaveBeenCalled();
+  });
+
+  it('no authz params → 200 identity-only (webserver case)', async () => {
+    const r = res();
+    await controller.moduleIdentity(req('tok', {}), r);
+    expect(r._status).toBe(200);
+    expect(auth.authorizeOrchestServiceAccess).not.toHaveBeenCalled();
+  });
+
+  it('malformed customer_name → host fails allowlist → 403, no call', async () => {
+    (auth.verifyAccessToken as jest.Mock).mockResolvedValue({
+      user_id: 'u-1',
+      username: 'alice',
+      permissions: [31],
+      customer_name: '',
+    });
+    const r = res();
+    await controller.moduleIdentity(req('tok', q), r);
+    expect(r._status).toBe(403);
+    expect(auth.authorizeOrchestServiceAccess).not.toHaveBeenCalled();
+  });
+});
@@ -0,0 +1,76 @@
+import {
+  parseAdminSeqids,
+  moduleGateSeqid,
+  isModuleAllowed,
+  isAdmin,
+  tenantOrchestApiHost,
+  isAllowedOrchestApiHost,
+  namespaceModule,
+} from './orchest-identity';
+
+describe('orchest-identity mapping', () => {
+  it('parseAdminSeqids: default, single, list, whitespace', () => {
+    expect(parseAdminSeqids(undefined)).toEqual([34]);
+    expect(parseAdminSeqids('')).toEqual([34]);
+    expect(parseAdminSeqids('34')).toEqual([34]);
+    expect(parseAdminSeqids('34,40')).toEqual([34, 40]);
+    expect(parseAdminSeqids(' 34 , 40 ')).toEqual([34, 40]);
+  });
+
+  it('moduleGateSeqid: default and override', () => {
+    expect(moduleGateSeqid(undefined)).toBe(31);
+    expect(moduleGateSeqid('43')).toBe(43);
+  });
+
+  it('isModuleAllowed', () => {
+    expect(isModuleAllowed([31, 5], 31)).toBe(true);
+    expect(isModuleAllowed([5, 7], 31)).toBe(false);
+    expect(isModuleAllowed([], 31)).toBe(false);
+  });
+
+  it('isAdmin: intersection', () => {
+    expect(isAdmin([31, 34], [34])).toBe(true);
+    expect(isAdmin([31], [34])).toBe(false);
+    expect(isAdmin([99], [34, 99])).toBe(true);
+  });
+});
+
+describe('orchest-identity tenant routing', () => {
+  it('namespaceModule default and values', () => {
+    expect(namespaceModule(undefined)).toBe('intelli');
+    expect(namespaceModule('process')).toBe('process');
+    expect(namespaceModule('garbage')).toBe('intelli');
+  });
+
+  it('tenantOrchestApiHost builds the namespace pattern', () => {
+    expect(tenantOrchestApiHost('acme', 'intelli')).toBe(
+      'orchest-api.orchest-intelli-acme.svc.cluster.local',
+    );
+    expect(tenantOrchestApiHost('acme', 'process')).toBe(
+      'orchest-api.orchest-process-acme.svc.cluster.local',
+    );
+  });
+
+  it('tenantOrchestApiHost normalizes a non-slug customer_name', () => {
+    expect(tenantOrchestApiHost('Acme Corp', 'intelli')).toBe(
+      'orchest-api.orchest-intelli-acme-corp.svc.cluster.local',
+    );
+  });
+
+  it('isAllowedOrchestApiHost guards against malformed values', () => {
+    expect(
+      isAllowedOrchestApiHost(
+        'orchest-api.orchest-intelli-acme.svc.cluster.local',
+      ),
+    ).toBe(true);
+    expect(isAllowedOrchestApiHost('evil.example.com')).toBe(false);
+    expect(
+      isAllowedOrchestApiHost('orchest-api.orchest-intelli-.svc.cluster.local'),
+    ).toBe(false);
+    expect(
+      isAllowedOrchestApiHost(
+        'orchest-api.orchest-other-acme.svc.cluster.local',
+      ),
+    ).toBe(false);
+  });
+});
@@ -0,0 +1,70 @@
+/**
+ * Pure helpers backing `GET /auth/module-identity` (see
+ * dbt-to-orchest docs/superpowers/specs/2026-08-20-maestro-module-identity-design.md).
+ *
+ * Kept free of HTTP/Nest so the permission mapping and tenant-routing logic
+ * unit-test without a request. Authorization decisions that reach orchest-api
+ * live on AuthClientService; this module only maps Maestro permissions to the
+ * Orchest header contract and derives the tenant orchest-api host.
+ */
+
+/** Parse ORCHEST_ADMIN_PERMISSION_SEQIDS ("34" / "34,40"); default [34]. */
+export function parseAdminSeqids(raw: string | undefined): number[] {
+  if (!raw || !raw.trim()) return [34];
+  return raw
+    .split(',')
+    .map((s) => Number(s.trim()))
+    .filter((n) => Number.isInteger(n));
+}
+
+/** Parse ORCHEST_MODULE_PERMISSION_SEQID; default 31 (Intelligence/Orchest). */
+export function moduleGateSeqid(raw: string | undefined): number {
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : 31;
+}
+
+/** Whether the user's permissions include the module-access gate seqid. */
+export function isModuleAllowed(perms: number[], gateSeqid: number): boolean {
+  return Array.isArray(perms) && perms.includes(gateSeqid);
+}
+
+/** Whether the user's permissions intersect the admin seqid set. */
+export function isAdmin(perms: number[], adminSeqids: number[]): boolean {
+  return Array.isArray(perms) && perms.some((p) => adminSeqids.includes(p));
+}
+
+/** The `{module}` slug in the tenant namespace pattern; default 'intelli'. */
+export function namespaceModule(
+  raw: string | undefined,
+): 'intelli' | 'process' {
+  return raw === 'process' ? 'process' : 'intelli';
+}
+
+/**
+ * The in-cluster DNS of the calling tenant's orchest-api, from the tenant
+ * namespace convention `orchest-{module}-{customer_name}`.
+ *
+ * `customer_name` is normalized to the namespace slug shape (lowercase,
+ * non-[a-z0-9-] → '-') so a display-name value still yields a valid host; a
+ * value that is already a clean slug is unchanged. NOTE: confirm the exact
+ * prod `customer_name` → namespace mapping against a real token before relying
+ * on this in production (the `dadosferademo2` tenant is a known exception and
+ * is unsupported — it is being removed).
+ */
+export function tenantOrchestApiHost(
+  customerName: string,
+  module: string,
+): string {
+  const slug = String(customerName)
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-');
+  return `orchest-api.orchest-${module}-${slug}.svc.cluster.local`;
+}
+
+const ORCHEST_API_HOST_RE =
+  /^orchest-api\.orchest-(intelli|process)-[a-z0-9-]+\.svc\.cluster\.local$/;
+
+/** Defense in depth: only call an orchest-api host matching the convention. */
+export function isAllowedOrchestApiHost(host: string): boolean {
+  return ORCHEST_API_HOST_RE.test(host);
+}
@@ -85,6 +85,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.GET,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async searchCatalog(
    @User() user: RequestUser,
    @Query() query: ICatalogAllRequest,
@@ -124,6 +127,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.GET,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async dowloadAsserts(
    @User() user: RequestUser,
    @Query() query: ICatalogAllRequest,
@@ -167,6 +173,9 @@ export class CatalogController {

  @ApiInternalOnlyEndpoint()
  @Get('data-asset')
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async findByPipelineAndObject(@User() user: RequestUser, @Query() query) {
    const { username, user_id, customer_id, customer_name, permissions } = user;
    const { pipeline, object } = query;
@@ -225,6 +234,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.GET,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async findAllTags(@Body() body) {
    this.logger.info(`/catalog - ON FIND ALL TAGS ROUTE`, {
      user: body.info.user_id,
@@ -293,6 +305,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.GET,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async getDataAsset(
    @User() user: RequestUser,
    @Param('id') id: string,
@@ -404,6 +419,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.GET,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async getDataAssetColumnsMetadata(
    @User() user: RequestUser,
    @Language() language: LanguageEnum,
@@ -435,6 +453,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.GET,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async getDataAssetPreview(
    @User() user: RequestUser,
    @Language() language: LanguageEnum,
@@ -466,6 +487,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.GET,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async getDataAssetDocs(
    @User() user: RequestUser,
    @Language() language: LanguageEnum,
@@ -497,6 +521,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.UPDATE,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async updateDataAsset(
    @User() user: RequestUser,
    @Language() language: LanguageEnum,
@@ -532,6 +559,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.CERTIFY,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async updateDataAssetCertificationStatus(
    @User() user: RequestUser,
    @Language() language: LanguageEnum,
@@ -559,6 +589,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.UPDATE,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async manageDataAssetDocs(
    @User() user: RequestUser,
    @Headers() headers,
@@ -596,6 +629,9 @@ export class CatalogController {

  @ApiInternalOnlyEndpoint()
  @Put('data-asset/:id/manage-permissions')
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async manageDataAssetPermissions(
    @Param('id') id: string,
    @User() user: RequestUser,
@@ -618,6 +654,9 @@ export class CatalogController {

  @ApiInternalOnlyEndpoint()
  @Put('data-asset/:id/revoke-permissions')
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async revokeDataAssetPermissions(
    @Param('id') id: string,
    @User() user: RequestUser,
@@ -643,6 +682,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.CREATE,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async createDataAsset(
    @User() user: RequestUser,
    @Body() body: ICreateDataAsset,
@@ -667,6 +709,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.UPDATE,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async commentOnDataAsset(
    @Param('id') id: string,
    @User() user: RequestUser,
@@ -693,6 +738,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.DELETE,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async deleteDataAsset(@Param('id') id: string, @User() user: RequestUser) {
    const { customer_id, customer_name, user_id, username } = user;
    const metadata = PackTheMetadata({
@@ -714,6 +762,9 @@ export class CatalogController {
    PERMISSIONS_GROUPS.CATALOG.permissions.UPDATE,
    PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async deleteComment(
    @Param('id') id: string,
    @User() user: RequestUser,
@@ -867,6 +918,9 @@ export class CatalogController {

  @Get('nimbus-dashboards')
  @RequireAllPermissions(PERMISSIONS_GROUPS.CATALOG.permissions.DATA_MANAGER)
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.CATALOG
+  )
  async getNimbusDashboards(
    @User() user: RequestUser,
    @Body() body: GetNimbusDashboardsRequest,
@@ -27,15 +27,19 @@ import {
  RefreshCatalogStatusReq,
 } from './dto/connection-test';
 import { DadosferaLogger } from '@dadosfera/dadosfera-logs';
-import { Authenticated } from 'src/decorators/authentication.decorator';
+import { Authenticated, RequireModule } from 'src/decorators/authentication.decorator';
 import { GrpcToHttpExceptionFilter } from 'src/error/grpc-to-http-exception.filter';
 import { ApiInternalOnlyController } from 'src/decorators/swagger.decorator';
+import { DADOSFERA_MODULES_KEYS } from 'src/authentication/permissions.enum';

@ApiInternalOnlyController()
@ApiTags('Connection Test')
@Controller('connection-test')
@UseFilters(new GrpcToHttpExceptionFilter())
@Authenticated()
+@RequireModule(
+  DADOSFERA_MODULES_KEYS.COLLECT
+)
 export class ConnectionTestController {
  logger: any;
  constructor(
@@ -16,8 +16,9 @@ import { DadosferaLogger } from '@dadosfera/dadosfera-logs';
 import {
  Authenticated,
  RequireAllPermissions,
+  RequireModule,
 } from 'src/decorators/authentication.decorator';
-import { PERMISSIONS_GROUPS } from 'src/authentication/permissions.enum';
+import { DADOSFERA_MODULES_KEYS, PERMISSIONS_GROUPS } from 'src/authentication/permissions.enum';
 import { RequestUser, User } from 'src/decorators/user.decorator';
 import { ValidationPipe } from '../../pipes/object-validation.pipe';
 import {
@@ -39,6 +40,9 @@ const connectionPermissions = PERMISSIONS_GROUPS.CONNECTION.permissions;
@ApiTags('connections')
@Authenticated()
@Controller('connections')
+@RequireModule(
+  DADOSFERA_MODULES_KEYS.COLLECT
+)
 export class ConnectionController {
  logger: any;
  constructor(
@@ -25,9 +25,10 @@ import { DadosferaLogger } from '@dadosfera/dadosfera-logs';
 import {
  Authenticated,
  RequireAllPermissions,
+  RequireModule,
  RequireSomePermission,
 } from 'src/decorators/authentication.decorator';
-import { PERMISSIONS_GROUPS } from 'src/authentication/permissions.enum';
+import { DADOSFERA_MODULES_KEYS, PERMISSIONS_GROUPS } from 'src/authentication/permissions.enum';
 import { Language } from 'src/decorators/language.decorator';
 import { LanguageEnum } from 'src/utils/languages.enum';
 import { ApiInternalOnlyController } from 'src/decorators/swagger.decorator';
@@ -99,6 +100,9 @@ export class ConnectorController {
    PERMISSIONS_GROUPS.PIPELINE.permissions.UPDATE,
    PERMISSIONS_GROUPS.PIPELINE.permissions.DELETE,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.COLLECT
+  )
  async getAllConnectors(
    @Language() language: LanguageEnum,
    @Query() queries: GetAllDto,
@@ -131,6 +135,9 @@ export class ConnectorController {
    PERMISSIONS_GROUPS.PIPELINE.permissions.UPDATE,
    PERMISSIONS_GROUPS.PIPELINE.permissions.DELETE,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.COLLECT
+  )
  async getConnectorsTags() {
    return await this.connectorClientService.getConnectorsTags();
  }
@@ -143,6 +150,9 @@ export class ConnectorController {
    PERMISSIONS_GROUPS.PIPELINE.permissions.UPDATE,
    PERMISSIONS_GROUPS.PIPELINE.permissions.DELETE,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.COLLECT
+  )
  async getConnector(
    @Language() language: LanguageEnum,
    @Param('plugin') plugin: string,
@@ -171,6 +181,9 @@ export class ConnectorController {
    PERMISSIONS_GROUPS.PIPELINE.permissions.UPDATE,
    PERMISSIONS_GROUPS.PIPELINE.permissions.DELETE,
  )
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.COLLECT
+  )
  async getConnectorDetails(
    @Language() language: LanguageEnum,
    @Param('plugin') plugin: string,
@@ -193,6 +206,9 @@ export class ConnectorController {
  @Put('/:plugin')
  @RequireAllPermissions(PERMISSIONS_GROUPS.CONNECTORS.permissions.UPDATE)
  @ApiConsumes('multipart/form-data')
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.COLLECT
+  )
  async updateConnector(
    @Param('plugin') plugin: string,
    @Body() body: UpdateDto,
@@ -214,6 +230,9 @@ export class ConnectorController {

  @Put('/:plugin/add-tag')
  @RequireAllPermissions(PERMISSIONS_GROUPS.CONNECTORS.permissions.UPDATE)
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.COLLECT
+  )
  async addTagOnConnector(
    @Param('plugin') plugin: string,
    @Body() body: AddTagDto,
@@ -241,6 +260,9 @@ export class ConnectorController {

  @Put('/:plugin/remove-tag')
  @RequireAllPermissions(PERMISSIONS_GROUPS.CONNECTORS.permissions.UPDATE)
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.COLLECT
+  )
  async removeTagOnConnector(
    @Param('plugin') plugin: string,
    @Body() body: RemoveTagDto,
@@ -269,6 +291,9 @@ export class ConnectorController {

  @Delete('/:plugin')
  @RequireAllPermissions(PERMISSIONS_GROUPS.CONNECTORS.permissions.DELETE)
+  @RequireModule(
+    DADOSFERA_MODULES_KEYS.COLLECT
+  )
  async deleteConnector(
    @Param('plugin') plugin: string,
    @Query('version') version: string,
@@ -25,9 +25,10 @@ import {
 } from '@nestjs/swagger';
 import {
  RequireAllPermissions,
+  RequireModule,
  RequireSomePermission,
 } from 'src/decorators/authentication.decorator';
-import { PERMISSIONS_GROUPS } from '../../authentication/permissions.enum';
+import { DADOSFERA_MODULES_KEYS, PERMISSIONS_GROUPS } from '../../authentication/permissions.enum';
 import { PipelinesService } from './pipelines.service';
 import { DadosferaLogger } from '@dadosfera/dadosfera-logs';
 import { Messages } from '@dadosfera/protospack-v2/dist/lib/PipelineV2';
@@ -57,6 +58,9 @@ type PipelineTablesConfig = { input_id?: string; tables: PipelineTable[] };
@ApiHeaders([{ name: 'dadosfera-lang', enum: LanguageEnum, required: false }])
@UseFilters(new GrpcToHttpExceptionFilter())
@Controller('pipelinesV2')
+@RequireModule(
+  DADOSFERA_MODULES_KEYS.COLLECT
+)
 export class PipelinesController {
  logger: DadosferaLogger;
  constructor(
@@ -20,10 +20,11 @@ import { DadosferaLogger } from '@dadosfera/dadosfera-logs';
 import {
  Authenticated,
  RequireAllPermissions,
+  RequireModule,
 } from '../../decorators/authentication.decorator';
 import { User, RequestUser } from '../../decorators/user.decorator';
 import { PlatformApiService } from './platform-api.service';
-import { PERMISSIONS_GROUPS } from '../../authentication/permissions.enum';
+import { DADOSFERA_MODULES_KEYS, PERMISSIONS_GROUPS } from '../../authentication/permissions.enum';
 import { ElasticsearchService } from '../../services/elasticsearch';
 import { DynamoDBService, ReferenceColumn } from '../../services/dynamodb';
 import { CustomersService } from '../customers/customers.service';
@@ -49,6 +50,7 @@ type RenameTablesBody = {

@ApiTags('Platform API')
@Controller('platform')
+@RequireModule(DADOSFERA_MODULES_KEYS.COLLECT)
 export class PlatformApiController {
  private logger: any;

@@ -0,0 +1,13 @@
+/**
+ * Jest setupFiles hook: provide dummy values for env vars that modules read
+ * at *import time* (module-load side effects), so unit specs that transitively
+ * import those modules don't crash before a single test runs.
+ *
+ * These are never exercised by unit tests — the services that use them are
+ * stubbed via DI — but the values must exist because the reads happen at
+ * module evaluation, before any mock is installed.
+ *
+ * DUC_URL: read at load time in src/modules/duc/client.config.ts, reached via
+ * the AuthClientService import chain.
+ */
+process.env.DUC_URL = process.env.DUC_URL || 'duc:localhost:0';
Author	SHA1	Message	Date
RafaelandWOZCODE	e06e7498db	feat(auth): per-service authz branch on /auth/module-identity When the ingress annotation carries permission (+project_uuid), authorize against the tenant's orchest-api /api/authz/check (host derived from the JWT, allowlist-guarded); relay allow/deny, fail-closed 502. All-or-nothing on incomplete params; param-less requests stay identity-only (webserver case). Co-Authored-By: WOZCODE <contact@withwoz.com>	2026-08-20 10:12:45 -03:00
RafaelandWOZCODE	922a34a393	feat(orchest-identity): tenant orchest-api host derivation + allowlist Derives the tenant orchest-api DNS from customer_name + the orchest-{module}-{customer_name} namespace convention, with deterministic slug normalization and an allowlist-regex guard. TODO before prod: confirm the exact customer_name->namespace mapping against a real token. Co-Authored-By: WOZCODE <contact@withwoz.com>	2026-08-20 10:10:43 -03:00
RafaelandWOZCODE	a795f543f6	feat(auth): GET /auth/module-identity — identity + module gate Adds the route (cookie auth via verifyAccessToken, module gate seqid 31, X-Auth-* headers, admin via seqid set). Adds a jest setupFiles hook giving a dummy DUC_URL for module-load-time env reads, which also unblocks the pre-existing authentication.guard.spec. Co-Authored-By: WOZCODE <contact@withwoz.com>	2026-08-20 10:09:31 -03:00
RafaelandWOZCODE	15b5c49fb2	refactor(auth): expose verifyAccessToken (was private validateJwtToken) Co-Authored-By: WOZCODE <contact@withwoz.com>	2026-08-20 10:06:02 -03:00
RafaelandWOZCODE	1730ec2753	feat(orchest-identity): permission-mapping helpers Co-Authored-By: WOZCODE <contact@withwoz.com>	2026-08-20 10:05:26 -03:00
RafaelandWOZCODE	dc4609cbc5	docs(plan): Orchest module-identity implementation plan (both phases) TDD plan for GET /auth/module-identity: Phase 1 (identity + module gate, Tasks 1-3) and Phase 2 (per-service authz via namespace-derived orchest-api host, Tasks 4-6, incl. the orchest-side service_access_auth_url change in the dbt-to-orchest repo). Reuses the existing JWKS verify (validateJwtToken → public verifyAccessToken); config via process.env; Jest controller specs with mocked AuthClientService. Spec: dbt-to-orchest docs/superpowers/specs/2026-08-20-maestro-module-identity-design.md. Co-Authored-By: WOZCODE <contact@withwoz.com>	2026-08-20 10:03:41 -03:00
marcos.rodrigues	e1b0e88bd8	Merge pull request #507 from dadosfera/bugfix/catalog-module-main Bugfix/catalog module main	2026-08-12 09:59:08 -03:00
marcos.rodrigues	cef1184908	Merge branch 'beta' into bugfix/catalog-module-main	2026-08-12 09:58:58 -03:00
marcos.rodrigues	31dda867d1	FIX: require collect module in endpoints	2026-08-12 09:57:23 -03:00
marcos.rodrigues	b89909ad66	FIX: skip nimbus update when customer haven't catalog module	2026-08-07 14:48:46 -03:00
marcos.rodrigues	2bb280e8de	Merge pull request #505 from dadosfera/bugfix/catalog-module Bugfix/catalog module	2026-08-07 12:26:21 -03:00