@vritti/api-sdk 0.3.16 → 0.4.1

package/dist/auth.d.ts

@@ -4,7 +4,7 @@ import * as _nestjs_common from '@nestjs/common';
 import { InjectionToken, ModuleMetadata, DynamicModule, CanActivate, ExecutionContext } from '@nestjs/common';
 import { Reflector } from '@nestjs/core';
 import { JwtService, JwtSignOptions } from '@nestjs/jwt';
-import { FastifyRequest } from 'fastify';
+import { VrittiSessionAuth } from 'fastify';
 export { W as WORKSPACE_HEADER_ORDER } from './request-CDllp7xb.js';
 
 /**
@@ -27,14 +27,6 @@ declare const PARTY_ID_HEADER = "x-party-id";
  * window, which is why app operations should stay idempotent.
  */
 declare const MAX_CLOCK_SKEW_SECONDS = 300;
-/**
- * `sessionInfo.sessionType` for an app request.
- *
- * Not a value of any server's `session_type` enum — no session row exists. It is
- * here so anything reading `sessionType` can tell an app apart from a person
- * without a second field.
- */
-declare const APP_SESSION_TYPE = "APP";
 
 interface AuthConfigInput {
     tokenExpiry: TokenExpiry;
@@ -67,42 +59,22 @@ declare const CookieName: (...dataOrPipes: unknown[]) => ParameterDecorator;
 
 declare const Hostname: (...dataOrPipes: unknown[]) => ParameterDecorator;
 
-declare const Public: () => _nestjs_common.CustomDecorator<string>;
-
 declare const RefreshCookieOptions: (...dataOrPipes: unknown[]) => ParameterDecorator;
 
 declare const RefreshTokenCookie: (...dataOrPipes: unknown[]) => ParameterDecorator;
 
-declare const REQUIRE_APP_KEY = "requiredAppTypes";
-/**
- * Authenticates an external app by its request signature, and restricts the
- * endpoint to the given app types.
- *
- * ```ts
- * @RequireApp(AppTypeValues.GRAPHQL)
- * @Mutation(() => Person, { name: 'createPerson' })
- * async createPerson(@Args('input') input: CreatePersonInput) {}
- * ```
- *
- * Metadata only, exactly like `@RequireSession` — `VrittiAuthGuard` reads it and
- * branches. Nothing else is needed at the call site:
- *
- * - no `@Public()`, because the guard's app branch runs *before* the public check
- * - no `@UseGuards()`, because the global guard owns this
- * - no `@SkipCsrf()`, because that branch returns before CSRF is ever reached —
- *   which also covers REST, where a transport-level exemption would not
- *
- * Types are compared as strings: the enum belongs to the consuming server's
- * schema, and this only ever compares. Passing none authenticates the caller
- * without restricting which kind it is.
- *
- * The consuming server resolves the credential in its `onAuthenticated` callback,
- * which is the only side with a database. See `GuardConfig.onAuthenticated`.
- */
-declare const RequireApp: (...types: string[]) => _nestjs_common.CustomDecorator<string>;
-
-declare const REQUIRE_SESSION_KEY = "requiredSessionTypes";
-declare const RequireSession: (...types: string[]) => _nestjs_common.CustomDecorator<string>;
+declare const REQUIRE_AUTH_KEY = "requireAuth";
+declare enum AuthType {
+    Session = "session",
+    App = "app",
+    Cloud = "cloud",
+    Public = "public"
+}
+interface AuthRequirement {
+    type: AuthType;
+    subtypes: string[];
+}
+declare const Require: (type: AuthType, ...subtypes: string[]) => _nestjs_common.CustomDecorator<string>;
 
 interface SessionInfo$1 {
     userId: string;
@@ -120,7 +92,7 @@ declare const UserAgent: (...dataOrPipes: unknown[]) => ParameterDecorator;
 
 declare const UserId: (...dataOrPipes: unknown[]) => ParameterDecorator;
 
-type SessionInfo = NonNullable<FastifyRequest['sessionInfo']>;
+type SessionInfo = Omit<VrittiSessionAuth, 'kind'>;
 declare class TokenService {
     private readonly jwtService;
     private readonly config;
@@ -150,6 +122,16 @@ declare class VrittiAuthGuard implements CanActivate {
     private readonly logger;
     constructor(reflector: Reflector, requestService: RequestService, tokenService: TokenService, config: AuthConfig);
     canActivate(context: ExecutionContext): Promise<boolean>;
+    /**
+     * Authenticates a signed request from the control plane.
+     *
+     * Same shape as the app branch and for the same reason: verifying the signature needs a key
+     * the consuming server holds, so this delegates to `guard.onAuthenticated` and keeps only
+     * what this side can do — recognising the decorator and seeding the context.
+     *
+     * There is no subtype filter. Cloud is one caller, not a family of them.
+     */
+    private handleCloudAuth;
     /**
      * Authenticates a signed request from an external app.
      *
@@ -174,4 +156,4 @@ declare class VrittiAuthGuard implements CanActivate {
 declare function hashToken(token: string): string;
 declare function verifyTokenHash(token: string, expectedHash: string): boolean;
 
-export { APP_SESSION_TYPE, AccessToken, AuthConfig, AuthConfigModule, CLIENT_ID_HEADER, ClientIp, CookieConfig, CookieDomain, CookieName, DecodedAccessToken, DecodedRefreshToken, GuardConfig, Hostname, MAX_CLOCK_SKEW_SECONDS, PARTY_ID_HEADER, Public, REQUIRE_APP_KEY, REQUIRE_SESSION_KEY, RefreshCookieOptions, RefreshTokenCookie, RequireApp, RequireSession, SKIP_CSRF_KEY, SessionData, type SessionInfo$1 as SessionInfo, SkipCsrf, Subdomain, TokenExpiry, TokenService, TokenType, UserAgent, UserId, VrittiAuthGuard, hashToken, verifyTokenHash };
+export { AccessToken, AuthConfig, AuthConfigModule, type AuthRequirement, AuthType, CLIENT_ID_HEADER, ClientIp, CookieConfig, CookieDomain, CookieName, DecodedAccessToken, DecodedRefreshToken, GuardConfig, Hostname, MAX_CLOCK_SKEW_SECONDS, PARTY_ID_HEADER, REQUIRE_AUTH_KEY, RefreshCookieOptions, RefreshTokenCookie, Require, SKIP_CSRF_KEY, SessionData, type SessionInfo$1 as SessionInfo, SkipCsrf, Subdomain, TokenExpiry, TokenService, TokenType, UserAgent, UserId, VrittiAuthGuard, hashToken, verifyTokenHash };

package/dist/auth.js

@@ -14,7 +14,6 @@ var WORKSPACE_HEADER_ORDER = [
 var CLIENT_ID_HEADER = "x-vritti-client-id";
 var PARTY_ID_HEADER = "x-party-id";
 var MAX_CLOCK_SKEW_SECONDS = 300;
-var APP_SESSION_TYPE = "APP";
 
 // src/auth/auth.config.ts
 var AUTH_CONFIG = Symbol("AUTH_CONFIG");
@@ -159,6 +158,15 @@ var RequestService = class {
     return index === -1 ? "" : url.slice(index + 1);
   }
   /**
+  * Returns a single decoded query param, or undefined when absent.
+  *
+  * Reads the raw URL rather than Fastify's parsed `query` so it is usable from the
+  * guard, which runs before a route's own parsing is meaningful.
+  */
+  getQueryParam(key) {
+    return new URLSearchParams(this.getQuery()).get(key) ?? void 0;
+  }
+  /**
   * Returns the raw request body, as `fastify-raw-body` leaves it.
   *
   * Read structurally rather than through a module augmentation: that plugin is the
@@ -256,20 +264,25 @@ function getResponseFromContext(host) {
 }
 __name(getResponseFromContext, "getResponseFromContext");
 
-// src/auth/decorators/require-app.decorator.ts
+// src/auth/decorators/require.decorator.ts
 import { SetMetadata } from "@nestjs/common";
-var REQUIRE_APP_KEY = "requiredAppTypes";
-var RequireApp = /* @__PURE__ */ __name((...types) => SetMetadata(REQUIRE_APP_KEY, types), "RequireApp");
-
-// src/auth/decorators/require-session.decorator.ts
-import { SetMetadata as SetMetadata2 } from "@nestjs/common";
-var REQUIRE_SESSION_KEY = "requiredSessionTypes";
-var RequireSession = /* @__PURE__ */ __name((...types) => SetMetadata2(REQUIRE_SESSION_KEY, types), "RequireSession");
+var REQUIRE_AUTH_KEY = "requireAuth";
+var AuthType = /* @__PURE__ */ (function(AuthType2) {
+  AuthType2["Session"] = "session";
+  AuthType2["App"] = "app";
+  AuthType2["Cloud"] = "cloud";
+  AuthType2["Public"] = "public";
+  return AuthType2;
+})({});
+var Require = /* @__PURE__ */ __name((type, ...subtypes) => SetMetadata(REQUIRE_AUTH_KEY, {
+  type,
+  subtypes
+}), "Require");
 
 // src/auth/decorators/skip-csrf.decorator.ts
-import { SetMetadata as SetMetadata3 } from "@nestjs/common";
+import { SetMetadata as SetMetadata2 } from "@nestjs/common";
 var SKIP_CSRF_KEY = "skipCsrf";
-var SkipCsrf = /* @__PURE__ */ __name(() => SetMetadata3(SKIP_CSRF_KEY, true), "SkipCsrf");
+var SkipCsrf = /* @__PURE__ */ __name(() => SetMetadata2(SKIP_CSRF_KEY, true), "SkipCsrf");
 
 // src/auth/services/token.service.ts
 import { Inject as Inject2, Injectable as Injectable2, Logger, UnauthorizedException } from "@nestjs/common";
@@ -487,38 +500,64 @@ var VrittiAuthGuard = class _VrittiAuthGuard {
       context.getHandler(),
       context.getClass()
     ]) || csrfExemptTransports.includes(context.getType());
-    const requiredAppTypes = this.reflector.getAllAndOverride(REQUIRE_APP_KEY, [
-      context.getHandler(),
-      context.getClass()
-    ]);
-    if (requiredAppTypes) {
-      return this.handleAppAuth(request, requiredAppTypes, route);
-    }
-    const isPublic = this.reflector.getAllAndOverride("isPublic", [
+    const requirement = this.reflector.getAllAndOverride(REQUIRE_AUTH_KEY, [
       context.getHandler(),
       context.getClass()
-    ]);
-    if (isPublic) {
-      if (!skipCsrf) {
-        await this.validateCsrf(request, reply);
+    ]) ?? {
+      type: AuthType.Session,
+      subtypes: []
+    };
+    switch (requirement.type) {
+      // Signed server-to-server calls return before CSRF is ever reached. Neither carries a
+      // cookie for CSRF to protect, and that holds on REST too — which a transport-level
+      // exemption would not cover.
+      case AuthType.App:
+        return this.handleAppAuth(request, requirement.subtypes, route);
+      case AuthType.Cloud:
+        return this.handleCloudAuth(request, route);
+      case AuthType.Public: {
+        if (!skipCsrf) {
+          await this.validateCsrf(request, reply);
+        }
+        this.logger.debug(`${route} \u2014 public endpoint, skipping auth`);
+        return true;
+      }
+      case AuthType.Session: {
+        const isSseEndpoint = this.reflector.get(SSE_METADATA, context.getHandler());
+        if (isSseEndpoint) {
+          this.logger.debug(`${route} \u2014 SSE endpoint, authenticating via refresh cookie`);
+          return this.handleSseAuth(request, requirement.subtypes);
+        }
+        const sessionType = await this.handleHttpAuth(request, requirement.subtypes);
+        const csrfExemptSessionTypes = this.config.guard.csrfExemptSessionTypes ?? [];
+        if (!skipCsrf && !csrfExemptSessionTypes.includes(sessionType)) {
+          await this.validateCsrf(request, reply);
+        }
+        return true;
       }
-      this.logger.debug(`${route} \u2014 public endpoint, skipping auth`);
-      return true;
-    }
-    const requiredSessionTypes = this.reflector.getAllAndOverride(REQUIRE_SESSION_KEY, [
-      context.getHandler(),
-      context.getClass()
-    ]);
-    const isSseEndpoint = this.reflector.get(SSE_METADATA, context.getHandler());
-    if (isSseEndpoint) {
-      this.logger.debug(`${route} \u2014 SSE endpoint, authenticating via refresh cookie`);
-      return this.handleSseAuth(request, requiredSessionTypes);
     }
-    const sessionType = await this.handleHttpAuth(request, requiredSessionTypes);
-    const csrfExemptSessionTypes = this.config.guard.csrfExemptSessionTypes ?? [];
-    if (!skipCsrf && !csrfExemptSessionTypes.includes(sessionType)) {
-      await this.validateCsrf(request, reply);
+  }
+  /**
+  * Authenticates a signed request from the control plane.
+  *
+  * Same shape as the app branch and for the same reason: verifying the signature needs a key
+  * the consuming server holds, so this delegates to `guard.onAuthenticated` and keeps only
+  * what this side can do — recognising the decorator and seeding the context.
+  *
+  * There is no subtype filter. Cloud is one caller, not a family of them.
+  */
+  async handleCloudAuth(request, route) {
+    const onAuthenticated = this.config.guard.onAuthenticated;
+    if (!onAuthenticated) {
+      this.logger.error(`${route} \u2014 @Require(AuthType.Cloud) requires guard.onAuthenticated to be configured`);
+      throw new UnauthorizedException2("Cloud authentication is not configured");
     }
+    const auth = {
+      kind: "cloud"
+    };
+    request.auth = auth;
+    await onAuthenticated(this.requestService, auth);
+    this.logger.debug(`${route} \u2014 authenticated cloud request`);
     return true;
   }
   /**
@@ -542,16 +581,17 @@ var VrittiAuthGuard = class _VrittiAuthGuard {
       this.logger.error(`${route} \u2014 @RequireApp() requires guard.onAuthenticated to be configured`);
       throw new UnauthorizedException2("App authentication is not configured");
     }
-    const sessionInfo = {
-      sessionType: APP_SESSION_TYPE
+    const auth = {
+      kind: "app"
     };
-    request.sessionInfo = sessionInfo;
-    await onAuthenticated(this.requestService, sessionInfo);
-    if (requiredAppTypes.length && !requiredAppTypes.includes(sessionInfo.appType ?? "")) {
-      this.logger.warn(`${route} \u2014 app type ${sessionInfo.appType ?? "unknown"} not in allowed: [${requiredAppTypes.join(", ")}]`);
+    request.auth = auth;
+    await onAuthenticated(this.requestService, auth);
+    const appType = auth.kind === "app" ? auth.appType : void 0;
+    if (requiredAppTypes.length && !requiredAppTypes.includes(appType ?? "")) {
+      this.logger.warn(`${route} \u2014 app type ${appType ?? "unknown"} not in allowed: [${requiredAppTypes.join(", ")}]`);
       throw new UnauthorizedException2("This client is not recognised.");
     }
-    this.logger.debug(`${route} \u2014 authenticated app (${sessionInfo.appType})`);
+    this.logger.debug(`${route} \u2014 authenticated app (${appType})`);
     return true;
   }
   // Authenticates standard HTTP requests using the access token from Authorization header
@@ -575,17 +615,21 @@ var VrittiAuthGuard = class _VrittiAuthGuard {
       this.logger.warn(`${route} \u2014 session type ${decoded.sessionType} not in allowed: [${requiredSessionTypes.join(", ")}]`);
       throw new UnauthorizedException2(`${decoded.sessionType} sessions cannot access this endpoint`);
     }
-    const { tokenType: _tokenType, refreshTokenHash: _hash, exp: _exp, iat: _iat, ...sessionInfo } = decoded;
-    request.sessionInfo = sessionInfo;
+    const { tokenType: _tokenType, refreshTokenHash: _hash, exp: _exp, iat: _iat, ...claims } = decoded;
+    const auth = {
+      kind: "session",
+      ...claims
+    };
+    request.auth = auth;
     const onAuthenticated = this.config.guard.onAuthenticated;
     if (onAuthenticated) {
-      await onAuthenticated(this.requestService, request.sessionInfo);
+      await onAuthenticated(this.requestService, auth);
     }
     this.logger.debug(`${route} \u2014 authenticated user: ${decoded.userId} (${decoded.sessionType})`);
     return decoded.sessionType;
   }
   // Authenticates SSE connections using the refresh token httpOnly cookie
-  handleSseAuth(request, requiredSessionTypes) {
+  async handleSseAuth(request, requiredSessionTypes) {
     const refreshToken = this.requestService.getRefreshToken();
     if (!refreshToken) {
       this.logger.warn(`SSE ${request.url} \u2014 no refresh token cookie`);
@@ -596,8 +640,16 @@ var VrittiAuthGuard = class _VrittiAuthGuard {
       this.logger.warn(`SSE ${request.url} \u2014 session type ${decoded.sessionType} not allowed`);
       throw new UnauthorizedException2(`${decoded.sessionType} sessions cannot access this endpoint`);
     }
-    const { tokenType: _tokenType, exp: _exp, iat: _iat, ...sessionInfo } = decoded;
-    request.sessionInfo = sessionInfo;
+    const { tokenType: _tokenType, exp: _exp, iat: _iat, ...claims } = decoded;
+    const auth = {
+      kind: "session",
+      ...claims
+    };
+    request.auth = auth;
+    const onAuthenticated = this.config.guard.onAuthenticated;
+    if (onAuthenticated) {
+      await onAuthenticated(this.requestService, auth);
+    }
     this.logger.debug(`SSE ${request.url} \u2014 authenticated user: ${decoded.userId} (${decoded.sessionType})`);
     return true;
   }
@@ -780,10 +832,6 @@ var Hostname = createParamDecorator5((_data, ctx) => {
   return hostStr.split(":")[0] ?? hostStr;
 });
 
-// src/auth/decorators/public.decorator.ts
-import { SetMetadata as SetMetadata4 } from "@nestjs/common";
-var Public = /* @__PURE__ */ __name(() => SetMetadata4("isPublic", true), "Public");
-
 // src/auth/decorators/refresh-cookie-options.decorator.ts
 import { createParamDecorator as createParamDecorator6 } from "@nestjs/common";
 
@@ -909,15 +957,14 @@ var RefreshTokenCookie = createParamDecorator7((_data, ctx) => {
 // src/auth/decorators/session-data.decorator.ts
 import { createParamDecorator as createParamDecorator8 } from "@nestjs/common";
 var SessionData = createParamDecorator8((_data, ctx) => {
-  const request = getRequestFromContext(ctx);
-  const sessionInfo = request.sessionInfo;
-  if (!sessionInfo?.sessionId) {
-    throw new Error("Session info not found on request. Ensure route is protected by auth guard.");
+  const auth = getRequestFromContext(ctx).auth;
+  if (auth?.kind !== "session") {
+    throw new Error(`No session on this request (auth: ${auth?.kind ?? "none"}). @SessionData() is session-only.`);
   }
   return {
-    userId: sessionInfo.userId,
-    sessionId: sessionInfo.sessionId,
-    sessionType: sessionInfo.sessionType
+    userId: auth.userId,
+    sessionId: auth.sessionId,
+    sessionType: auth.sessionType
   };
 });
 
@@ -943,19 +990,18 @@ var UserAgent = createParamDecorator10((_data, ctx) => {
 // src/auth/decorators/user-id.decorator.ts
 import { createParamDecorator as createParamDecorator11 } from "@nestjs/common";
 var UserId = createParamDecorator11((_data, ctx) => {
-  const request = getRequestFromContext(ctx);
-  const sessionInfo = request.sessionInfo;
-  if (!sessionInfo?.userId) {
-    throw new Error("User ID not found on request. Ensure route is protected by auth guard.");
+  const auth = getRequestFromContext(ctx).auth;
+  if (auth?.kind !== "session") {
+    throw new Error(`No user on this request (auth: ${auth?.kind ?? "none"}). @UserId() is session-only.`);
   }
-  return sessionInfo.userId;
+  return auth.userId;
 });
 export {
-  APP_SESSION_TYPE,
   AUTH_CONFIG,
   AUTH_CONFIG_DEFAULTS,
   AccessToken,
   AuthConfigModule,
+  AuthType,
   CLIENT_ID_HEADER,
   ClientIp,
   CookieDomain,
@@ -963,13 +1009,10 @@ export {
   Hostname,
   MAX_CLOCK_SKEW_SECONDS,
   PARTY_ID_HEADER,
-  Public,
-  REQUIRE_APP_KEY,
-  REQUIRE_SESSION_KEY,
+  REQUIRE_AUTH_KEY,
   RefreshCookieOptions,
   RefreshTokenCookie,
-  RequireApp,
-  RequireSession,
+  Require,
   SKIP_CSRF_KEY,
   SessionData,
   SkipCsrf,