nestjs-ddd-cli 3.2.2 → 3.3.1

package/dist/templates/recipes/platform-service-access-request-context/docs.md.hbs

@@ -0,0 +1,61 @@
+# Platform Service Access Request Context
+
+Use this recipe in a NestJS owner service to exchange the opaque, single-use
+`x-service-access-request-context` lease for canonical actor and machine
+principal context. Service Access owns lease verification. The owner service
+must not decode the lease or reconstruct identity from caller headers.
+
+## Guard Order
+
+Import `ServiceAccessRequestContextModule`, then run its guard before the
+route-specific PARC guard:
+
+```typescript
+@RequireParcAuthorization({
+  service: "owner-service",
+  capability: "records.write",
+  action: "create",
+})
+@UseGuards(
+  ServiceAccessRequestContextGuard,
+  PlatformParcAuthorizationGuard,
+)
+```
+
+The generated client sends only `{token}`, `x-internal-api-key`, and
+`x-service-access-credential` to
+`POST /api/v1/internal/request-context/introspect`. It never forwards the
+actor's bearer token. A response is trusted only when it is well formed,
+`active:true`, unexpired, and its audience exactly matches
+`SERVICE_ACCESS_EXPECTED_AUDIENCE`. Inactive results cover unknown, expired,
+revoked, and replayed leases. Non-2xx responses, malformed bodies, audience
+mismatches, and Service Access failures deny in enforce mode.
+
+This recipe supports the legacy ZITADEL principal only. IAM-authenticated
+principals and responses carrying `provenance.authentication` are rejected,
+rather than discarding their realm/session proof. They require PARC's bound
+decision integration and its current IAM relationship checks. Do not relabel
+an IAM actor or fall back to the legacy decision endpoint.
+
+## Environment Contract
+
+- `SERVICE_ACCESS_URL`: Service Access base URL, without `/api/v1`.
+- `SERVICE_ACCESS_ALLOW_INSECURE_HTTP`: defaults to `false`; may be `true` only
+  for loopback or Kubernetes `.svc`/`.svc.cluster.local` URLs.
+- `SERVICE_ACCESS_INTERNAL_API_KEY`: internal transport authentication key.
+- `SERVICE_ACCESS_CREDENTIAL`: this owner service's active Service Access machine credential.
+- `SERVICE_ACCESS_EXPECTED_AUDIENCE`: exact owner-service slug expected in the lease.
+- `SERVICE_ACCESS_REQUEST_CONTEXT_MODE`: `enforce` by default, or explicit `shadow`/`disabled` rollout mode.
+- `SERVICE_ACCESS_TIMEOUT_MS`: positive introspection timeout; defaults to 3000.
+
+`enforce` requires successful introspection. `shadow` attempts introspection and
+attaches context only on success, but allows failure for rollout observation.
+`disabled` skips lease consumption. The guard clears any earlier request
+`platformContext`, so shadow and disabled modes never turn actor, business,
+application, or machine headers into identity. A following PARC guard therefore
+still fails closed unless verified platform context exists.
+
+Only `x-request-id`, `x-correlation-id`, and `idempotency-key` are copied as
+request metadata. They are not identity or authorization evidence. Owner domain
+invariants and transactional audit/outbox recording still apply after PARC
+allows the route-specific action.

package/dist/templates/recipes/platform-service-access-request-context/env.example.hbs

@@ -0,0 +1,7 @@
+SERVICE_ACCESS_URL=
+SERVICE_ACCESS_ALLOW_INSECURE_HTTP=false
+SERVICE_ACCESS_INTERNAL_API_KEY=
+SERVICE_ACCESS_CREDENTIAL=
+SERVICE_ACCESS_EXPECTED_AUDIENCE=replace-me-service
+SERVICE_ACCESS_REQUEST_CONTEXT_MODE=enforce
+SERVICE_ACCESS_TIMEOUT_MS=3000

package/dist/templates/recipes/platform-service-access-request-context/index.ts.hbs

@@ -0,0 +1,7 @@
+export * from "./service-access-request-context.config";
+export * from "./request-context-introspection.types";
+export * from "./request-context-introspection.parser";
+export * from "./request-context-headers";
+export * from "./service-access-request-context.client";
+export * from "./service-access-request-context.guard";
+export * from "./service-access-request-context.module";

package/dist/templates/recipes/platform-service-access-request-context/request-context-headers.ts.hbs

@@ -0,0 +1,61 @@
+export const SERVICE_ACCESS_REQUEST_CONTEXT_HEADER =
+  "x-service-access-request-context";
+
+export type RequestHeaders = Record<string, string | string[] | undefined>;
+
+export interface PlatformRequestMetadataHeaders {
+  requestId?: string;
+  correlationId?: string;
+  idempotencyKey?: string;
+}
+
+export class RequestContextHeaderError extends Error {
+  constructor() {
+    super("Invalid Service Access request-context headers");
+    this.name = "RequestContextHeaderError";
+  }
+}
+
+export function extractOpaqueRequestContextLease(headers: RequestHeaders): string {
+  const token = requiredSingleHeader(headers, SERVICE_ACCESS_REQUEST_CONTEXT_HEADER);
+  if (token.length > 512) {
+    throw new RequestContextHeaderError();
+  }
+  return token;
+}
+
+export function platformRequestMetadataFromHeaders(
+  headers: RequestHeaders,
+): PlatformRequestMetadataHeaders {
+  return {
+    requestId: optionalSingleHeader(headers, "x-request-id"),
+    correlationId: optionalSingleHeader(headers, "x-correlation-id"),
+    idempotencyKey: optionalSingleHeader(headers, "idempotency-key"),
+  };
+}
+
+function requiredSingleHeader(headers: RequestHeaders, name: string): string {
+  const value = optionalSingleHeader(headers, name);
+  if (!value) {
+    throw new RequestContextHeaderError();
+  }
+  return value;
+}
+
+function optionalSingleHeader(
+  headers: RequestHeaders,
+  name: string,
+): string | undefined {
+  const value = headers[name];
+  if (value === undefined) {
+    return undefined;
+  }
+  if (typeof value !== "string") {
+    throw new RequestContextHeaderError();
+  }
+  const cleaned = value.trim();
+  if (!cleaned || cleaned.includes(",")) {
+    throw new RequestContextHeaderError();
+  }
+  return cleaned;
+}

package/dist/templates/recipes/platform-service-access-request-context/request-context-introspection.parser.ts.hbs

@@ -0,0 +1,132 @@
+import type {
+  ActiveRequestContextIntrospectionResponse,
+  ServiceAccessRequestContextProvenance,
+  ServiceAccessVerifiedPrincipal,
+} from "./request-context-introspection.types";
+
+type UnknownRecord = Record<string, unknown>;
+
+export class RequestContextIntrospectionParseError extends Error {
+  constructor() {
+    super("Invalid Service Access request-context introspection response");
+    this.name = "RequestContextIntrospectionParseError";
+  }
+}
+
+export function parseActiveRequestContextIntrospection(
+  payload: unknown,
+  expectedAudience: string,
+  now = new Date(),
+): ActiveRequestContextIntrospectionResponse {
+  const record = requiredRecord(payload);
+  if (record["active"] !== true) {
+    throw invalidResponse();
+  }
+
+  const audience = requiredString(record["audience"]);
+  if (audience !== requiredString(expectedAudience)) {
+    throw invalidResponse();
+  }
+
+  const expiresAt = requiredIsoDate(record["expiresAt"]);
+  if (new Date(expiresAt).getTime() <= now.getTime()) {
+    throw invalidResponse();
+  }
+
+  const principal = parsePrincipal(record["principal"]);
+  if (principal.machine.serviceName !== audience) {
+    throw invalidResponse();
+  }
+
+  return {
+    active: true,
+    audience,
+    expiresAt,
+    principal,
+    provenance: parseProvenance(record["provenance"]),
+  };
+}
+
+function parsePrincipal(value: unknown): ServiceAccessVerifiedPrincipal {
+  const principal = requiredRecord(value);
+  const actor = requiredRecord(principal["actor"]);
+  const machine = requiredRecord(principal["machine"]);
+  // This recipe models the legacy ZITADEL lease only. Do not flatten a
+  // realm-bound IAM principal into a legacy authorization context.
+  if (actor["authenticatedBy"] !== "zitadel") {
+    throw invalidResponse();
+  }
+  const sessionId = optionalString(actor["sessionId"]);
+  const tokenId = optionalString(actor["tokenId"]);
+  const serviceInstanceId = optionalString(machine["serviceInstanceId"]);
+
+  return {
+    actor: {
+      subjectId: requiredString(actor["subjectId"]),
+      businessId: requiredString(actor["businessId"]),
+      applicationId: requiredString(actor["applicationId"]),
+      ...(sessionId ? { sessionId } : {}),
+      ...(tokenId ? { tokenId } : {}),
+      authenticatedBy: requiredString(actor["authenticatedBy"]),
+    },
+    machine: {
+      serviceName: requiredString(machine["serviceName"]),
+      clientId: requiredString(machine["clientId"]),
+      ...(serviceInstanceId ? { serviceInstanceId } : {}),
+      grantId: requiredString(machine["grantId"]),
+      credentialId: requiredString(machine["credentialId"]),
+    },
+  };
+}
+
+function parseProvenance(value: unknown): ServiceAccessRequestContextProvenance {
+  const provenance = requiredRecord(value);
+  if (
+    provenance["identityAuthority"] !== "identity-manager" ||
+    provenance["credentialAuthority"] !== "service-access" ||
+    provenance["authentication"] !== undefined
+  ) {
+    throw invalidResponse();
+  }
+
+  return {
+    identityAuthority: "identity-manager",
+    membershipId: requiredString(provenance["membershipId"]),
+    credentialAuthority: "service-access",
+    parcDecisionReference: requiredString(provenance["parcDecisionReference"]),
+  };
+}
+
+function requiredRecord(value: unknown): UnknownRecord {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw invalidResponse();
+  }
+  return value as UnknownRecord;
+}
+
+function requiredString(value: unknown): string {
+  if (typeof value !== "string" || !value.trim()) {
+    throw invalidResponse();
+  }
+  return value.trim();
+}
+
+function optionalString(value: unknown): string | undefined {
+  if (value === undefined) {
+    return undefined;
+  }
+  return requiredString(value);
+}
+
+function requiredIsoDate(value: unknown): string {
+  const date = requiredString(value);
+  const parsed = new Date(date);
+  if (Number.isNaN(parsed.getTime()) || parsed.toISOString() !== date) {
+    throw invalidResponse();
+  }
+  return date;
+}
+
+function invalidResponse(): RequestContextIntrospectionParseError {
+  return new RequestContextIntrospectionParseError();
+}

package/dist/templates/recipes/platform-service-access-request-context/request-context-introspection.types.ts.hbs

@@ -0,0 +1,40 @@
+import type {
+  PlatformActorContext,
+  PlatformMachineContext,
+  VerifiedPlatformPrincipal,
+} from "../../platform-context";
+
+export interface ServiceAccessVerifiedPrincipal extends VerifiedPlatformPrincipal {
+  actor: PlatformActorContext & {
+    businessId: string;
+    applicationId: string;
+  };
+  machine: PlatformMachineContext & {
+    clientId: string;
+    grantId: string;
+    credentialId: string;
+  };
+}
+
+export interface ServiceAccessRequestContextProvenance {
+  identityAuthority: "identity-manager";
+  membershipId: string;
+  credentialAuthority: "service-access";
+  parcDecisionReference: string;
+}
+
+export interface ActiveRequestContextIntrospectionResponse {
+  active: true;
+  audience: string;
+  expiresAt: string;
+  principal: ServiceAccessVerifiedPrincipal;
+  provenance: ServiceAccessRequestContextProvenance;
+}
+
+export interface InactiveRequestContextIntrospectionResponse {
+  active: false;
+}
+
+export type RequestContextIntrospectionResponse =
+  | ActiveRequestContextIntrospectionResponse
+  | InactiveRequestContextIntrospectionResponse;

package/dist/templates/recipes/platform-service-access-request-context/service-access-request-context.client.ts.hbs

@@ -0,0 +1,45 @@
+import { Injectable, UnauthorizedException } from "@nestjs/common";
+import type { ActiveServiceAccessRequestContextConfig } from "./service-access-request-context.config";
+import { parseActiveRequestContextIntrospection } from "./request-context-introspection.parser";
+import type { ActiveRequestContextIntrospectionResponse } from "./request-context-introspection.types";
+
+@Injectable()
+export class ServiceAccessRequestContextClient {
+  async introspect(
+    token: string,
+    config: ActiveServiceAccessRequestContextConfig,
+  ): Promise<ActiveRequestContextIntrospectionResponse> {
+    try {
+      const response = await fetch(
+        config.serviceAccessUrl + "/api/v1/internal/request-context/introspect",
+        {
+          method: "POST",
+          redirect: "error",
+          headers: {
+            Accept: "application/json",
+            "Content-Type": "application/json",
+            "x-internal-api-key": config.internalApiKey,
+            "x-service-access-credential": config.serviceAccessCredential,
+          },
+          signal: AbortSignal.timeout(config.timeoutMs),
+          body: JSON.stringify({ token }),
+        },
+      );
+
+      if (!response.ok) {
+        throw new Error("Service Access request-context introspection failed");
+      }
+
+      return parseActiveRequestContextIntrospection(
+        await response.json(),
+        config.expectedAudience,
+      );
+    } catch {
+      throw this.denied();
+    }
+  }
+
+  private denied(): UnauthorizedException {
+    return new UnauthorizedException("Service Access request context denied");
+  }
+}

package/dist/templates/recipes/platform-service-access-request-context/service-access-request-context.config.ts.hbs

@@ -0,0 +1,142 @@
+export const SERVICE_ACCESS_REQUEST_CONTEXT_MODES = [
+  "disabled",
+  "shadow",
+  "enforce",
+] as const;
+
+export type ServiceAccessRequestContextMode =
+  (typeof SERVICE_ACCESS_REQUEST_CONTEXT_MODES)[number];
+export type ActiveServiceAccessRequestContextMode = Exclude<
+  ServiceAccessRequestContextMode,
+  "disabled"
+>;
+
+export interface DisabledServiceAccessRequestContextConfig {
+  mode: "disabled";
+}
+
+export interface ActiveServiceAccessRequestContextConfig {
+  mode: ActiveServiceAccessRequestContextMode;
+  serviceAccessUrl: string;
+  allowInsecureHttp: boolean;
+  internalApiKey: string;
+  serviceAccessCredential: string;
+  expectedAudience: string;
+  timeoutMs: number;
+}
+
+export type ServiceAccessRequestContextConfig =
+  | DisabledServiceAccessRequestContextConfig
+  | ActiveServiceAccessRequestContextConfig;
+
+export function serviceAccessRequestContextModeFromEnv(): ServiceAccessRequestContextMode {
+  const mode = clean(process.env["SERVICE_ACCESS_REQUEST_CONTEXT_MODE"]) ?? "enforce";
+  if (!SERVICE_ACCESS_REQUEST_CONTEXT_MODES.includes(mode as ServiceAccessRequestContextMode)) {
+    throw new Error("SERVICE_ACCESS_REQUEST_CONTEXT_MODE must be disabled, shadow, or enforce");
+  }
+  return mode as ServiceAccessRequestContextMode;
+}
+
+export function serviceAccessRequestContextConfigFromEnv(
+  mode: "disabled",
+): DisabledServiceAccessRequestContextConfig;
+export function serviceAccessRequestContextConfigFromEnv(
+  mode: ActiveServiceAccessRequestContextMode,
+): ActiveServiceAccessRequestContextConfig;
+export function serviceAccessRequestContextConfigFromEnv(
+  mode?: ServiceAccessRequestContextMode,
+): ServiceAccessRequestContextConfig;
+export function serviceAccessRequestContextConfigFromEnv(
+  mode = serviceAccessRequestContextModeFromEnv(),
+): ServiceAccessRequestContextConfig {
+  if (mode === "disabled") {
+    return { mode };
+  }
+
+  const allowInsecureHttp = booleanEnv(
+    "SERVICE_ACCESS_ALLOW_INSECURE_HTTP",
+    false,
+  );
+
+  return {
+    mode,
+    serviceAccessUrl: requiredServiceAccessUrl(allowInsecureHttp),
+    allowInsecureHttp,
+    internalApiKey: requiredEnv("SERVICE_ACCESS_INTERNAL_API_KEY"),
+    serviceAccessCredential: requiredEnv("SERVICE_ACCESS_CREDENTIAL"),
+    expectedAudience: requiredEnv("SERVICE_ACCESS_EXPECTED_AUDIENCE"),
+    timeoutMs: positiveIntegerEnv("SERVICE_ACCESS_TIMEOUT_MS", 3000),
+  };
+}
+
+function requiredServiceAccessUrl(allowInsecureHttp: boolean): string {
+  const value = requiredEnv("SERVICE_ACCESS_URL").replace(/\/+$/, "");
+  let parsed: URL;
+  try {
+    parsed = new URL(value);
+  } catch {
+    throw new Error("SERVICE_ACCESS_URL must be an absolute HTTP(S) URL");
+  }
+  if (parsed.protocol === "https:") {
+    return value;
+  }
+  if (
+    parsed.protocol === "http:" &&
+    allowInsecureHttp &&
+    isApprovedInsecureHostname(parsed.hostname)
+  ) {
+    return value;
+  }
+  throw new Error(
+    "SERVICE_ACCESS_URL must use HTTPS unless insecure HTTP is explicitly enabled for loopback or cluster service DNS",
+  );
+}
+
+function requiredEnv(name: string): string {
+  const value = clean(process.env[name]);
+  if (!value) {
+    throw new Error(name + " is required for Service Access request context");
+  }
+  return value;
+}
+
+function positiveIntegerEnv(name: string, fallback: number): number {
+  const value = clean(process.env[name]);
+  if (!value) {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(name + " must be a positive integer");
+  }
+  return parsed;
+}
+
+function booleanEnv(name: string, fallback: boolean): boolean {
+  const value = clean(process.env[name]);
+  if (!value) {
+    return fallback;
+  }
+  if (value === "true") {
+    return true;
+  }
+  if (value === "false") {
+    return false;
+  }
+  throw new Error(name + " must be true or false");
+}
+
+function isApprovedInsecureHostname(hostname: string): boolean {
+  return (
+    hostname === "localhost" ||
+    hostname === "127.0.0.1" ||
+    hostname === "::1" ||
+    hostname.endsWith(".svc") ||
+    hostname.endsWith(".svc.cluster.local")
+  );
+}
+
+function clean(value: string | undefined): string | undefined {
+  const cleaned = value?.trim();
+  return cleaned || undefined;
+}

package/dist/templates/recipes/platform-service-access-request-context/service-access-request-context.guard.ts.hbs

@@ -0,0 +1,77 @@
+import {
+  CanActivate,
+  ExecutionContext,
+  Injectable,
+  Logger,
+  UnauthorizedException,
+} from "@nestjs/common";
+import { createPlatformRequestContext } from "../../platform-context";
+import type { PlatformRequestContext } from "../../platform-context";
+import {
+  serviceAccessRequestContextConfigFromEnv,
+  serviceAccessRequestContextModeFromEnv,
+} from "./service-access-request-context.config";
+import {
+  extractOpaqueRequestContextLease,
+  platformRequestMetadataFromHeaders,
+} from "./request-context-headers";
+import type { RequestHeaders } from "./request-context-headers";
+import { ServiceAccessRequestContextClient } from "./service-access-request-context.client";
+
+export interface RequestWithServiceAccessRequestContext {
+  headers: RequestHeaders;
+  platformContext?: PlatformRequestContext;
+}
+
+@Injectable()
+export class ServiceAccessRequestContextGuard implements CanActivate {
+  private readonly logger = new Logger(ServiceAccessRequestContextGuard.name);
+
+  constructor(private readonly client: ServiceAccessRequestContextClient) {}
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    const request = context
+      .switchToHttp()
+      .getRequest<RequestWithServiceAccessRequestContext>();
+
+    delete request.platformContext;
+
+    let mode;
+    try {
+      mode = serviceAccessRequestContextModeFromEnv();
+    } catch {
+      throw this.denied();
+    }
+
+    if (mode === "disabled") {
+      return true;
+    }
+
+    try {
+      const config = serviceAccessRequestContextConfigFromEnv(mode);
+      const token = extractOpaqueRequestContextLease(request.headers);
+      const introspection = await this.client.introspect(token, config);
+      const metadata = platformRequestMetadataFromHeaders(request.headers);
+
+      request.platformContext = createPlatformRequestContext({
+        principal: introspection.principal,
+        requestId: metadata.requestId,
+        correlationId: metadata.correlationId,
+        idempotencyKey: metadata.idempotencyKey,
+      });
+      return true;
+    } catch {
+      if (mode === "shadow") {
+        this.logger.warn(
+          "Service Access request-context shadow verification failed",
+        );
+        return true;
+      }
+      throw this.denied();
+    }
+  }
+
+  private denied(): UnauthorizedException {
+    return new UnauthorizedException("Service Access request context denied");
+  }
+}

package/dist/templates/recipes/platform-service-access-request-context/service-access-request-context.module.ts.hbs

@@ -0,0 +1,17 @@
+import { Module } from "@nestjs/common";
+import { PlatformContextModule } from "../../platform-context";
+import { ServiceAccessRequestContextClient } from "./service-access-request-context.client";
+import { ServiceAccessRequestContextGuard } from "./service-access-request-context.guard";
+
+@Module({
+  imports: [PlatformContextModule],
+  providers: [
+    ServiceAccessRequestContextClient,
+    ServiceAccessRequestContextGuard,
+  ],
+  exports: [
+    ServiceAccessRequestContextClient,
+    ServiceAccessRequestContextGuard,
+  ],
+})
+export class ServiceAccessRequestContextModule {}