auth.guard.ts · Source

auth.guard.tsapps/api/src/common/guards/auth.guard.tsraw ← guards14,395 B← Back to the app
1import { CanActivate, ExecutionContext, Inject, Injectable } from "@nestjs/common";
2import { v4 as uuid } from "uuid";
3import type { Request } from "express";
4import { sha256hex } from "../../lib/crypto.js";
5import { verifyToken, TokenError } from "../../lib/jwt.js";
6import { loadEnv } from "../../config/env.js";
7import { ApiError } from "../errors.js";
8import { PrismaService } from "../prisma.service.js";
9import { RedisService } from "../redis.service.js";
10import { isJtiRevoked } from "../../modules/oauth/token-keys.js";
11import type { AuthContext } from "../types.js";
12 
13/**
14 * Global authentication guard.
15 *
16 * Accepts:
17 *  - `Authorization: Bearer <JWT>` (HS256 access token)
18 *  - `Authorization: Bearer fk_<key>` (workspace API key — sha256 lookup)
19 *
20 * Public paths (whitelist) pass through with no auth. Everything else
21 * requires a valid credential → `req.auth` is set; failures are
22 * 401 { code: "UNAUTHORIZED" | "INVALID_TOKEN" | "TOKEN_EXPIRED" }.
23 *
24 * `/internal/*` paths (TASK-0092 slice 2) pass through THIS guard too —
25 * they authenticate with the service token in `InternalServiceGuard`
26 * (controller-level) instead of a user JWT / API key.
27 */
28@Injectable()
29export class AuthGuard implements CanActivate {
30  constructor(
31    @Inject(PrismaService) private readonly prisma: PrismaService,
32    @Inject(RedisService) private readonly redis: RedisService
33  ) {}
34 
35  async canActivate(context: ExecutionContext): Promise<boolean> {
36    const req = context.switchToHttp().getRequest<Request>();
37    if (!req.id) req.id = uuid();
38    if (this.isPublic(req)) return true;
39 
40    const header = req.headers.authorization;
41    if (!header || !header.startsWith("Bearer ")) {
42      throw ApiError.unauthorized("Missing bearer token.", [{ reason: "token_missing" }]);
43    }
44    const token = header.slice(7).trim();
45    if (!token) throw ApiError.unauthorized("Missing bearer token.", [{ reason: "token_missing" }]);
46 
47    req.auth = token.startsWith("fk_")
48      ? await this.resolveApiKey(token, req)
49      : await this.resolveJwt(token, req);
50    return true;
51  }
52 
53  private isPublic(req: Request): boolean {
54    const path = req.path;
55    // The global prefix makes the public health path `/api/v1/health` at
56    // request time — `req.path` is post-prefix, so BOTH spellings are
57    // whitelisted (the bare `/health` line predates the global prefix).
58    if (path.startsWith("/health")) return true;
59    if (path.startsWith("/api/v1/health")) return true;
60    // Service-token-authenticated internal surface (TASK-0092 slice 2):
61    // `InternalServiceGuard` (controller-level) authenticates it — the JWT
62    // / API-key path must not 401 it first.
63    if (path.startsWith("/internal/")) return true;
64    if (path.startsWith("/api/v1/auth/login")) return true;
65    if (path.startsWith("/api/v1/auth/register")) return true;
66    if (path.startsWith("/api/v1/auth/refresh")) return true;
67    // TASK-0133 enforcement #1: the 2FA step completes a PASSWORD login —
68    // the user is not authenticated yet (the pending step + TOTP code are
69    // the credentials), exactly like `/auth/login`.
70    if (path.startsWith("/api/v1/auth/2fa/")) return true;
71    if (path.startsWith("/api/v1/auth/reset-password")) return true;
72    // TASK-0131: the login page's ANONYMOUS SSO discovery (minimal-info —
73    // org slug + boolean, no provider details). Public by design (the
74    // email is the input; an unknown email returns the same empty shape).
75    if (path.startsWith("/api/v1/auth/sso/options")) return true;
76    // TASK-0131: the SAML/OIDC protocol endpoints are mounted OUTSIDE the
77    // api/v1 prefix (main.ts excludes them — browser bindings, not JSON
78    // API). Their authentication is the assertion/ID-token signature + the
79    // state/nonce/PKCE checks inside the services; no user JWT.
80    if (path.startsWith("/saml/")) return true;
81    if (path.startsWith("/sso/")) return true;
82    // TASK-0132: the SCIM protocol surface (`/scim/v2/*`) is a third-party
83    // IdP binding — bearer-token auth via `ScimBearerGuard` (controller
84    // level), no user JWT. The SCIM ADMIN routes (`/api/v1/orgs/:orgId/
85    // scim/*`) are NOT whitelisted here (they stay user-JWT + owner-gated).
86    if (path.startsWith("/scim/")) return true;
87    // public shared content + public forms + oauth token endpoint
88    if (/^\/api\/v1\/share\/[^/]+$/.test(path)) return true;
89    if (/^\/api\/v1\/f\/[^/]+\/?$/.test(path)) return true;
90    // Phase 10 (TASK-0107/0108): the public form SURFACE — GET payload,
91    // POST submit, and the anonymous form-attributed file sessions. The
92    // submit is ATTRIBUTED only when a valid user JWT is present (the
93    // controller's OptionalAuthGuard decodes it) — the path itself is
94    // never auth-gated (anonymous submits are the point; never a 401).
95    if (path.startsWith("/api/v1/public/forms/")) return true;
96    // Phase 10 (TASK-0109): the test-only debug events endpoint. It
97    // 404s unless NODE_ENV=test AND requires the X-Debug-Token — the
98    // whitelist here only means "no user JWT required" (a production
99    // build still 404s it; see debug.controller.ts).
100    if (path === "/api/v1/debug/events") return true;
101    if (path.startsWith("/api/v1/oauth/")) return true;
102    // Phase 11 (TASK-0110): the INCOMING webhook endpoint is public by
103    // design — the HMAC-SHA256 signature (X-FS-Signature) IS the auth.
104    // Only POST /webhooks/incoming/:webhookId lives here; no user JWT is
105    // required (the signature carries workspace identity via the stored
106    // trigger).
107    if (path.startsWith("/api/v1/webhooks/incoming/")) return true;
108    // TASK-0127: the interactive API docs + spec download are public
109    // content (like /health). They leak no data — the spec is a committed
110    // file in the repo — and key holders are the primary audience.
111    if (path.startsWith("/api/v1/docs")) return true;
112    if (path === "/docs" || path.startsWith("/docs/")) return true;
113    return false;
114  }
115 
116  private async resolveJwt(token: string, req: Request): Promise<AuthContext> {
117    let claims;
118    try {
119      claims = verifyToken(token, loadEnv().JWT_SECRET);
120    } catch (err) {
121      if (err instanceof TokenError) {
122        throw new ApiError(err.code, 401, err.message, [
123          { reason: err.code === "TOKEN_EXPIRED" ? "token_expired" : "token_malformed" }
124        ]);
125      }
126      throw err;
127    }
128    if (!claims.sub) throw ApiError.unauthorized("Token has no subject.", [{ reason: "token_malformed" }]);
129 
130    // TASK-0129: the consent CSRF token (kind "oauth_consent") is a
131    // single-purpose form nonce — it must NEVER authenticate an API call
132    // even though it carries a valid `sub` (the user id).
133    if (claims.kind === "oauth_consent") {
134      throw ApiError.unauthorized("Token is not an access token.", [{ reason: "token_malformed" }]);
135    }
136 
137    // TASK-0132 (prerequisite fix): a SUSPENDED user must not ride an
138    // in-flight access token. Phase 1's status check already blocks
139    // LOGIN and REFRESH; without this, a token minted before suspension
140    // (or a SCIM `replace active:false`) stays valid until its exp (≤15
141    // m). Point query on the PK — the same cost class as the API-key
142    // path's lookup. Placed AFTER the cheap consent rejection (above) so a
143    // consent token keeps its 401; applies to BOTH user JWTs and OAuth
144    // access tokens (they carry the same user identity).
145    if (await this.isUserSuspended(claims.sub)) {
146      this.auditSuspendedBlock(claims.sub, req);
147      throw ApiError.forbidden("Account suspended.", [{ reason: "account_suspended" }]);
148    }
149 
150    // TASK-0129: an OAuth access token (claims.type === "oauth") keeps
151    // kind "user" (it carries the user's identity) but is gated by its SCOPE,
152    // not the user's membership — `lib/authorize.ts` branches on the presence
153    // of `oauthScopes`. The target workspace comes from X-Factory-Workspace
154    // (the OAuth JWT carries no workspace claim); `authorize.ts` validates
155    // the user is a member of it (401 if not). The JTI denylist check lets a
156    // revoked access token be rejected immediately (before its 15-min exp).
157    if (claims.type === "oauth") {
158      if (await isJtiRevoked(this.redis.getRedis(), typeof claims.jti === "string" ? claims.jti : undefined)) {
159        throw ApiError.unauthorized("Access token revoked.", [{ reason: "token_revoked" }]);
160      }
161      return {
162        kind: "user",
163        userId: claims.sub,
164        oauthScopes: Array.isArray(claims.scope) ? (claims.scope as string[]) : (typeof claims.scope === "string" ? (claims.scope as string).split(" ").filter(Boolean) : []),
165        oauthClientId: typeof claims.client_id === "string" ? claims.client_id : undefined,
166        workspaceId: (req.headers["x-factory-workspace"] as string | undefined)
167      };
168    }
169 
170    const headerWs = req.headers["x-factory-workspace"] as string | undefined;
171    return {
172      kind: "user",
173      userId: claims.sub,
174      workspaces: Array.isArray(claims.workspaces) ? (claims.workspaces as string[]) : undefined,
175      sessionId: typeof claims.sid === "string" ? claims.sid : undefined,
176      workspaceId: headerWs ?? (claims.workspaces?.length === 1 ? claims.workspaces[0] : undefined)
177    };
178  }
179 
180  private async resolveApiKey(rawKey: string, req: Request): Promise<AuthContext> {
181    const keyHash = sha256hex(rawKey);
182    const row = await this.prisma.apiKey.findUnique({ where: { keyHash } });
183    if (!row) throw ApiError.unauthorized("Unknown API key.", [{ reason: "api_key_invalid" }]);
184    if (row.revokedAt) {
185      await this.recordAuthFailure(row.id, "api_key_revoked");
186      throw ApiError.unauthorized("API key revoked.", [{ reason: "api_key_revoked" }]);
187    }
188    if (row.expiresAt && row.expiresAt.getTime() < Date.now()) {
189      await this.recordAuthFailure(row.id, "api_key_expired");
190      throw ApiError.unauthorized("API key expired.", [{ reason: "api_key_expired" }]);
191    }
192    const headerWs = req.headers["x-factory-workspace"] as string | undefined;
193    if (headerWs && headerWs !== row.workspaceId) {
194      throw ApiError.forbidden("API key does not belong to the requested workspace.", [
195        { reason: "workspace_mismatch" }
196      ]);
197    }
198    const scopeList: string[] = [...row.scopes];
199    if (scopeList.includes("ADMIN")) scopeList.push("WRITE", "READ");
200    if (scopeList.includes("WRITE")) scopeList.push("READ");
201    // TASK-0127: resolve the key's creator so API-key requests can be
202    // attributed to a real user row (createdBy-style columns, audit) while
203    // acting as the WORKSPACE — scope decisions never consult this id
204    // (see the API-key branch of `assertCan`/`assertRole`).
205    const creator = await this.prisma.user
206      .findUnique({ where: { id: row.createdById }, select: { id: true } })
207      .catch(() => null);
208    // Best-effort last-used bump (fire and forget), TASK-0127 debounced:
209    // only write when the last bump is > 60 s old (avoids write amplification
210    // on high-frequency CI keys; "recent enough" for the list UI's
211    // "last used" relative time).
212    if (!row.lastUsedAt || Date.now() - row.lastUsedAt.getTime() > 60_000) {
213      void this.prisma
214        .apiKey.update({ where: { id: row.id }, data: { lastUsedAt: new Date() } })
215        .catch(() => undefined);
216    }
217    return {
218      kind: "api",
219      workspaceId: row.workspaceId,
220      scopes: scopeList,
221      apiKeyId: row.id,
222      userId: creator?.id,
223      rateLimit: row.rateLimit
224    };
225  }
226 
227  /**
228   * TASK-0127: audit `api_key.auth_failure` for a known-but-dead key
229   * (revoked/expired), throttled per key to 1/hour (Redis SET NX EX) so a
230   * leaked key cannot spam the audit log. Unknown keys (key-guess
231   * brute-forcing) are not audited per key — the per-key/IP rate limit and
232   * the single hash-index probe already cover that surface (docs §7
233   * Security: timing must not leak existence). Fail-open: never break auth.
234   */
235  /**
236   * TASK-0132 (prerequisite fix): is the user for this token currently
237   * SUSPENDED? A point query on the PK. A not-found user (a token for a
238   * since-deleted account) is treated as "not suspended" so the normal 401
239   * (bad token) still governs — we only short-circuit the suspended case.
240   */
241  private async isUserSuspended(sub: string): Promise<boolean> {
242    try {
243      const row = await this.prisma.user.findUnique({
244        where: { id: sub },
245        select: { status: true }
246      });
247      return row?.status === "SUSPENDED";
248    } catch {
249      return false; // a transient DB error must not turn a valid token into a 500
250    }
251  }
252 
253  /**
254   * Audit the in-flight-session suspension block (TASK-0132). Best-effort,
255   * like `recordAuthFailure` — a failed audit must never break auth. No
256   * workspace is in scope here (the suspended user's own), so the row is
257   * user-scoped (workspaceId null).
258   */
259  private auditSuspendedBlock(userId: string, req: Request): void {
260    void this.prisma.auditLog
261      .create({
262        data: {
263          actorType: "USER",
264          actorId: userId,
265          resourceType: "user",
266          resourceId: userId,
267          action: "auth.suspended_blocked",
268          ipAddress: req.ip ?? null,
269          userAgent: (req.headers["user-agent"] as string | undefined) ?? null,
270          metadata: { path: req.path } as object
271        }
272      })
273      .catch(() => {
274        /* audit must never break auth */
275      });
276  }
277 
278  private async recordAuthFailure(apiKeyId: string, reason: string): Promise<void> {
279    let passed = false;
280    try {
281      passed = (await this.redis.getRedis().set(`apikey:authfail:${apiKeyId}`, "1", "EX", 3600, "NX")) !== null;
282    } catch {
283      passed = true; // fail-open: audit the failure even if throttling is down
284    }
285    if (!passed) return;
286    try {
287      const row = await this.prisma.apiKey.findUnique({
288        where: { id: apiKeyId },
289        select: { workspaceId: true }
290      });
291      if (!row) return;
292      await this.prisma.auditLog.create({
293        data: {
294          actorType: "API_KEY",
295          actorId: `api:${apiKeyId}`,
296          workspaceId: row.workspaceId,
297          resourceType: "api_key",
298          resourceId: apiKeyId,
299          action: "api_key.auth_failure",
300          metadata: { reason } as object
301        }
302      });
303    } catch {
304      /* audit must never break auth */
305    }
306  }
307}
308