@zuplo/runtime 6.71.23 → 6.71.25

package/out/types/index.d.ts

@@ -1350,6 +1350,150 @@ declare interface AuditLogEntry {
   };
 }
 
+/**
+ * A CloudEvent 1.0 audit log entry. Most fields are auto-populated by the
+ * runtime; user code only supplies the type/subject/resources/data fields when
+ * calling `AuditLogInboundPolicy.log()`.
+ *
+ * @public
+ */
+export declare interface AuditLogEvent {
+  specversion: "1.0";
+  id: string;
+  source: string;
+  type: string;
+  time: string;
+  datacontenttype?: "application/json";
+  subject?: string;
+  bucketid: string;
+  actorsub?: string;
+  actortype?: "user" | "service" | "apikey" | "anonymous";
+  actoremail?: string;
+  actorconnection?: string;
+  resources?: AuditLogResource[];
+  requestid?: string;
+  success?: boolean;
+  httpmethod?: string;
+  httpurl?: string;
+  httpstatus?: number;
+  ipaddress?: string;
+  useragent?: string;
+  country?: string;
+  region?: string;
+  city?: string;
+  mcpserver?: string;
+  mcpvirtualserver?: string;
+  mcptool?: string;
+  data?: Record<string, unknown>;
+  extensions?: Record<string, unknown>;
+}
+
+/**
+ * Fields a caller may supply when emitting a custom audit event via
+ * `AuditLogInboundPolicy.log()`. Everything else is filled in by the runtime
+ * from the request context.
+ *
+ * @public
+ */
+export declare interface AuditLogEventInput {
+  type: string;
+  subject?: string;
+  resources?: AuditLogResource[];
+  success?: boolean;
+  data?: Record<string, unknown>;
+  /**
+   * Geolocation of the caller. When omitted, these default to the current
+   * request's geo data (from the request context), so custom events carry the
+   * same location information as the auto-emitted per-request event.
+   */
+  country?: string;
+  region?: string;
+  city?: string;
+  /** Override the auto-derived actor (rare). */
+  actor?: {
+    sub?: string;
+    type?: "user" | "service" | "apikey" | "anonymous";
+    email?: string;
+    connection?: string;
+  };
+  /** MCP-specific helpers. */
+  mcp?: {
+    server?: string;
+    virtualServer?: string;
+    tool?: string;
+  };
+}
+
+/**
+ * Capture detailed logs of requests for auditing purposes. The policy emits
+ * one structured CloudEvent per request, and user code can emit additional
+ * events via the static `log()` method.
+ *
+ * @title Audit Logs
+ * @product api-gateway
+ * @public
+ * @enterprise
+ */
+export declare class AuditLogInboundPolicy extends InboundPolicy<AuditLogInboundPolicyOptions> {
+  #private;
+  static readonly policyType = "audit-logs";
+  /**
+   * Emit an audit event for the current request.
+   *
+   * Fields not provided are filled in from the request context (bucket id,
+   * request id, time, actor, IP, user agent, etc).
+   *
+   * @param context - The current ZuploContext.
+   * @param event - The event details to record.
+   */
+  static log(context: ZuploContext, event: AuditLogEventInput): void;
+  constructor(options: AuditLogInboundPolicyOptions, policyName: string);
+  handler(
+    request: ZuploRequest,
+    context: ZuploContext
+  ): Promise<ZuploRequest | Response>;
+}
+
+/**
+ * The options for the Audit Log Inbound policy.
+ * @public
+ */
+export declare interface AuditLogInboundPolicyOptions {
+  /**
+   * Reverse-DNS prefix used for the auto-emitted request event type. Defaults to 'com.zuplo.api'.
+   */
+  eventTypeBase?: string;
+  /**
+   * Override the bucket id this policy emits events for. Defaults to the bucket id from the runtime environment.
+   */
+  bucketId?: string;
+  /**
+   * Fraction of requests to capture, between 0 (none) and 1 (all). Defaults to 1.
+   */
+  samplingRate?: number;
+  /**
+   * Controls which potentially-sensitive parts of each request are captured in the auto-emitted audit event. Disable fields to satisfy your own data-handling and PII policies. All are enabled by default.
+   */
+  include?: {
+    /**
+     * Include the request's query-string parameters in the logged URL. Disable if query strings may contain sensitive data.
+     */
+    queryParams?: boolean;
+    /**
+     * Include the authenticated user / actor identity (subject, email, connection).
+     */
+    user?: boolean;
+    /**
+     * Include the caller's IP address.
+     */
+    ipAddress?: boolean;
+    /**
+     * Include the caller's geolocation (country, region, city).
+     */
+    geolocation?: boolean;
+  };
+}
+
 /**
  * Configuration options for audit logging
  * @public
@@ -1394,6 +1538,16 @@ declare interface AuditLogRequestFilter {
   (request: ZuploRequest, context: ZuploContext): Promise<boolean>;
 }
 
+/**
+ * A resource affected by an audit event.
+ * @public
+ */
+export declare interface AuditLogResource {
+  type: string;
+  id: string;
+  metadata?: Record<string, unknown>;
+}
+
 /**
  * Authenticate users using Auth0 issued JWT tokens.
  *

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@zuplo/runtime",
   "type": "module",
-  "version": "6.71.23",
+  "version": "6.71.25",
   "repository": "https://github.com/zuplo/zuplo",
   "author": "Zuplo, Inc.",
   "exports": {