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>

docs/superpowers/plans/2026-08-20-orchest-module-identity.md

@@ -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).

jest.config.ts

@@ -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: [

src/modules/auth/auth.controller.ts

@@ -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();
+  }
 }

src/modules/auth/auth.service.ts

@@ -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';
+    }
+  }
 }

src/modules/auth/module-identity.controller.spec.ts

@@ -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();
+  });
+});

src/modules/auth/orchest-identity.spec.ts

@@ -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);
+  });
+});

src/modules/auth/orchest-identity.ts

@@ -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);
+}

test/jest.setup-env.ts

@@ -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';