@vritti/api-sdk 0.3.11 → 0.3.13

package/dist/auth.d.ts

@@ -1,10 +1,40 @@
 import { T as TokenExpiry, C as CookieConfig, G as GuardConfig, A as AuthConfig, a as TokenType, D as DecodedAccessToken, b as DecodedRefreshToken, R as RequestService } from './index.js';
 export { d as AUTH_CONFIG, e as AUTH_CONFIG_DEFAULTS, c as AccessTokenPayload, f as CookieSerializeOptions, O as OnAuthenticatedCallback, g as RefreshTokenPayload, h as TokenExpiryString } from './index.js';
 import * as _nestjs_common from '@nestjs/common';
-import { InjectionToken, DynamicModule, CanActivate, ExecutionContext } 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';
+export { W as WORKSPACE_HEADER_ORDER } from './request-CDllp7xb.js';
+
+/**
+ * The shared contract between this guard and a server that authenticates apps.
+ *
+ * The guard recognises `@RequireApp()` and enforces the type filter; the server
+ * resolves the credential in `guard.onAuthenticated`, because only it has a
+ * database. These are the values both sides have to agree on.
+ */
+/** The client id an app sends alongside the standard signature headers. */
+declare const CLIENT_ID_HEADER = "x-vritti-client-id";
+/** The party (person) a signed request is acting for, when there is one. */
+declare const PARTY_ID_HEADER = "x-party-id";
+
+/**
+ * How far a signed request's timestamp may drift before it is refused.
+ *
+ * Five minutes, matching the deployment-signing path. Wide enough for ordinary
+ * clock drift between two servers; a captured request is replayable inside the
+ * 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;
@@ -14,6 +44,14 @@ interface AuthConfigInput {
 interface AuthConfigModuleOptions<T extends unknown[] = unknown[]> {
     useFactory: (...args: [...T]) => AuthConfigInput | Promise<AuthConfigInput>;
     inject?: InjectionToken[];
+    /**
+     * Extra modules the factory's injected providers come from.
+     *
+     * Needed because `guard.onAuthenticated` is where a server resolves an app
+     * credential, so the factory has to be able to inject the service that owns that
+     * lookup. Mirrors `NatsClientModule.forRoot`.
+     */
+    imports?: ModuleMetadata['imports'];
 }
 declare class AuthConfigModule {
     static forRootAsync<T extends unknown[] = unknown[]>(options: AuthConfigModuleOptions<T>): DynamicModule;
@@ -35,6 +73,34 @@ declare const RefreshCookieOptions: (...dataOrPipes: unknown[]) => ParameterDeco
 
 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>;
 
@@ -84,6 +150,22 @@ 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 an external app.
+     *
+     * The credential lookup and the signature check are the consuming server's job —
+     * it is the only side with a database — so this delegates to
+     * `guard.onAuthenticated`, the same hook the session path already uses to resolve
+     * organization and workspace context. That server fills in `organizationId`,
+     * `appType` and whatever else it knows.
+     *
+     * What stays here is the part only this side can do: reading the decorator's
+     * metadata and enforcing the app-type filter against what the server resolved.
+     *
+     * An empty list means "any type" — the caller is still authenticated. That makes
+     * `@RequireApp()` with no arguments mean what it reads like.
+     */
+    private handleAppAuth;
     private handleHttpAuth;
     private handleSseAuth;
     private validateCsrf;
@@ -92,4 +174,4 @@ declare class VrittiAuthGuard implements CanActivate {
 declare function hashToken(token: string): string;
 declare function verifyTokenHash(token: string, expectedHash: string): boolean;
 
-export { AccessToken, AuthConfig, AuthConfigModule, ClientIp, CookieConfig, CookieDomain, CookieName, DecodedAccessToken, DecodedRefreshToken, GuardConfig, Hostname, Public, REQUIRE_SESSION_KEY, RefreshCookieOptions, RefreshTokenCookie, RequireSession, SKIP_CSRF_KEY, SessionData, type SessionInfo$1 as SessionInfo, SkipCsrf, Subdomain, TokenExpiry, TokenService, TokenType, UserAgent, UserId, VrittiAuthGuard, hashToken, verifyTokenHash };
+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 };

package/dist/auth.js

@@ -1,6 +1,21 @@
 var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
+// src/signing/request.ts
+import { createHash, createPrivateKey, createPublicKey, sign, verify } from "crypto";
+var WORKSPACE_HEADER_ORDER = [
+  "x-site-id",
+  "x-sg-id",
+  "x-le-id",
+  "x-org-id"
+];
+
+// src/auth/app-request.ts
+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");
 var AUTH_CONFIG_DEFAULTS = {
@@ -117,6 +132,46 @@ var RequestService = class {
   getAllHeaders() {
     return this.request.headers || {};
   }
+  // Returns the HTTP method
+  getMethod() {
+    return this.request.method ?? "";
+  }
+  /**
+  * Returns the path with any query string stripped.
+  *
+  * Signature canonicals cover the path only, so a query string must not be part
+  * of what gets signed or verified.
+  */
+  getPath() {
+    const url = this.request.url ?? "";
+    return url.split("?")[0] ?? url;
+  }
+  /**
+  * Returns the raw query string, without the leading `?`.
+  *
+  * Companion to `getPath()`, which strips it. Signed separately so a REST request's
+  * filters are covered — `getPath()` alone would sign `GET /people?search=salt` as
+  * though the filter were not there.
+  */
+  getQuery() {
+    const url = this.request.url ?? "";
+    const index = url.indexOf("?");
+    return index === -1 ? "" : url.slice(index + 1);
+  }
+  /**
+  * Returns the raw request body, as `fastify-raw-body` leaves it.
+  *
+  * Read structurally rather than through a module augmentation: that plugin is the
+  * consuming server's dependency, not this SDK's, and declaring `rawBody` here
+  * would collide with the plugin's own declaration the moment the two drift.
+  *
+  * A server that has not registered it yields `undefined`, which hashes as an empty
+  * body and therefore fails any signature made over real bytes — refused, never
+  * waved through.
+  */
+  getRawBody() {
+    return this.request.rawBody;
+  }
 };
 RequestService = _ts_decorate([
   Injectable({
@@ -201,15 +256,20 @@ function getResponseFromContext(host) {
 }
 __name(getResponseFromContext, "getResponseFromContext");
 
-// src/auth/decorators/require-session.decorator.ts
+// src/auth/decorators/require-app.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) => SetMetadata(REQUIRE_SESSION_KEY, types), "RequireSession");
+var RequireSession = /* @__PURE__ */ __name((...types) => SetMetadata2(REQUIRE_SESSION_KEY, types), "RequireSession");
 
 // src/auth/decorators/skip-csrf.decorator.ts
-import { SetMetadata as SetMetadata2 } from "@nestjs/common";
+import { SetMetadata as SetMetadata3 } from "@nestjs/common";
 var SKIP_CSRF_KEY = "skipCsrf";
-var SkipCsrf = /* @__PURE__ */ __name(() => SetMetadata2(SKIP_CSRF_KEY, true), "SkipCsrf");
+var SkipCsrf = /* @__PURE__ */ __name(() => SetMetadata3(SKIP_CSRF_KEY, true), "SkipCsrf");
 
 // src/auth/services/token.service.ts
 import { Inject as Inject2, Injectable as Injectable2, Logger, UnauthorizedException } from "@nestjs/common";
@@ -427,6 +487,13 @@ 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", [
       context.getHandler(),
       context.getClass()
@@ -454,6 +521,39 @@ var VrittiAuthGuard = class _VrittiAuthGuard {
     }
     return true;
   }
+  /**
+  * Authenticates a signed request from an external app.
+  *
+  * The credential lookup and the signature check are the consuming server's job —
+  * it is the only side with a database — so this delegates to
+  * `guard.onAuthenticated`, the same hook the session path already uses to resolve
+  * organization and workspace context. That server fills in `organizationId`,
+  * `appType` and whatever else it knows.
+  *
+  * What stays here is the part only this side can do: reading the decorator's
+  * metadata and enforcing the app-type filter against what the server resolved.
+  *
+  * An empty list means "any type" — the caller is still authenticated. That makes
+  * `@RequireApp()` with no arguments mean what it reads like.
+  */
+  async handleAppAuth(request, requiredAppTypes, route) {
+    const onAuthenticated = this.config.guard.onAuthenticated;
+    if (!onAuthenticated) {
+      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
+    };
+    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(", ")}]`);
+      throw new UnauthorizedException2("This client is not recognised.");
+    }
+    this.logger.debug(`${route} \u2014 authenticated app (${sessionInfo.appType})`);
+    return true;
+  }
   // Authenticates standard HTTP requests using the access token from Authorization header
   async handleHttpAuth(request, requiredSessionTypes) {
     const route = `${request.method} ${request.url}`;
@@ -589,6 +689,7 @@ var AuthConfigModule = class _AuthConfigModule {
       imports: [
         ConfigModule,
         RequestModule,
+        ...options.imports ?? [],
         JwtModule.registerAsync({
           imports: [
             ConfigModule
@@ -680,8 +781,8 @@ var Hostname = createParamDecorator5((_data, ctx) => {
 });
 
 // src/auth/decorators/public.decorator.ts
-import { SetMetadata as SetMetadata3 } from "@nestjs/common";
-var Public = /* @__PURE__ */ __name(() => SetMetadata3("isPublic", true), "Public");
+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";
@@ -850,18 +951,24 @@ var UserId = createParamDecorator11((_data, ctx) => {
   return sessionInfo.userId;
 });
 export {
+  APP_SESSION_TYPE,
   AUTH_CONFIG,
   AUTH_CONFIG_DEFAULTS,
   AccessToken,
   AuthConfigModule,
+  CLIENT_ID_HEADER,
   ClientIp,
   CookieDomain,
   CookieName,
   Hostname,
+  MAX_CLOCK_SKEW_SECONDS,
+  PARTY_ID_HEADER,
   Public,
+  REQUIRE_APP_KEY,
   REQUIRE_SESSION_KEY,
   RefreshCookieOptions,
   RefreshTokenCookie,
+  RequireApp,
   RequireSession,
   SKIP_CSRF_KEY,
   SessionData,
@@ -872,6 +979,7 @@ export {
   UserAgent,
   UserId,
   VrittiAuthGuard,
+  WORKSPACE_HEADER_ORDER,
   hashToken,
   verifyTokenHash
 };