BREAKING CHANGE(js)!: Reconcile authPolicy. add firebase and api key helpers

js/core/src/context.ts

@@ -58,3 +58,30 @@ export function getContext(
   registry = registry as Registry;
   return registry.asyncStore.getStore<ActionContext>(contextAlsKey);
 }
+
+/**
+ * A universal type that request handling extensions (e.g. express, next) can map their request to.
+ * This allows middleware to build consistent interfacese on any web framework.
+ * Headers must be lowercase to ensure portability.
+ */
+export interface RequestData<T = any> {
+  method: 'GET' | 'PUT' | 'POST' | 'DELETE' | 'OPTIONS' | 'QUERY';
+  headers: Record<string, string>;
+  input: T;
+}
+
+/**
+ * Middleware can read request data and add information to the context that will
+ * be passed to the Action. If middleware throws an error, that error will fail
+ * the request and the Action will not be invoked. Expected cases should return a
+ * UserFacingError, which allows the request handler to know what data is safe to
+ * return to end users.
+ *
+ * Middleware can provide validation in addition to parsing. For example, an auth
+ * middleware can have policies for validating auth in addition to passing auth context
+ * to the Action.
+ */
+export type ContextProvider<
+  C extends ActionContext = ActionContext,
+  T = any,
+> = (request: RequestData<T>) => C | Promise<C>;

js/core/src/error.ts

@@ -15,7 +15,13 @@
  */
 
 import { Registry } from './registry.js';
-import { StatusName } from './statusTypes.js';
+import { httpStatusCode, StatusName } from './statusTypes.js';
+
+interface HttpErrorWireFormat {
+  details?: unknown;
+  message: string;
+  status: StatusName;
+}
 
 /**
  * Base error class for Genkit errors.
@@ -24,6 +30,7 @@ export class GenkitError extends Error {
   source?: string;
   status: StatusName;
   detail?: any;
+  code: number;
 
   constructor({
     status,
@@ -37,10 +44,24 @@ export class GenkitError extends Error {
     source?: string;
   }) {
     super(`${source ? `${source}: ` : ''}${status}: ${message}`);
+    this.code = httpStatusCode(status);
     this.status = status;
     this.detail = detail;
     this.name = 'GenkitError';
   }
+
+  /**
+   * Returns a JSON-serializable representation of this object.
+   */
+  public toJSON(): HttpErrorWireFormat {
+    return {
+      // This error type is used by 3P authors with the field "detail",
+      // but the actual Callable protocol value is "details"
+      ...(this.detail === undefined ? {} : { details: this.detail }),
+      status: this.status,
+      message: this.message,
+    };
+  }
 }
 
 export class UnstableApiError extends GenkitError {
@@ -69,6 +90,39 @@ export function assertUnstable(
   }
 }
 
+/**
+ * Creates a new class of Error for issues to be returned to users.
+ * Using this error allows a web framework handler (e.g. express, next) to know it
+ * is safe to return the message in a request. Other kinds of errors will
+ * result in a generic 500 message to avoid the possibility of internal
+ * exceptions being leaked to attackers.
+ * In JSON requests, code will be an HTTP code and error will be a response body.
+ * In streaming requests, { code, message } will be passed as the error message.
+ */
+export class UserFacingError extends GenkitError {
+  constructor(status: StatusName, message: string, details?: any) {
+    super({ status, detail: details, message });
+    super.name = 'UserFacingError';
+  }
+}
+
+export function getHttpStatus(e: any): number {
+  if (e instanceof GenkitError) {
+    return e.code;
+  }
+  return 500;
+}
+
+export function getCallableJSON(e: any): HttpErrorWireFormat {
+  if (e instanceof GenkitError) {
+    return e.toJSON();
+  }
+  return {
+    message: 'Internal Error',
+    status: 'INTERNAL',
+  };
+}
+
 /**
  * Extracts error message from the given error object, or if input is not an error then just turn the error into a string.
  */

js/core/src/index.ts

@@ -29,8 +29,21 @@ export const GENKIT_REFLECTION_API_SPEC_VERSION = 1;
 
 export { z } from 'zod';
 export * from './action.js';
-export { getContext, runWithContext, type ActionContext } from './context.js';
-export { GenkitError, UnstableApiError, assertUnstable } from './error.js';
+export {
+  getContext,
+  runWithContext,
+  type ActionContext,
+  type ContextProvider,
+  type RequestData,
+} from './context.js';
+export {
+  GenkitError,
+  UnstableApiError,
+  UserFacingError,
+  assertUnstable,
+  getCallableJSON,
+  getHttpStatus,
+} from './error.js';
 export {
   defineFlow,
   run,

js/core/src/statusTypes.ts

@@ -176,6 +176,7 @@ export enum StatusCodes {
 }
 
 export const StatusNameSchema = z.enum([
+  'OK',
   'CANCELLED',
   'UNKNOWN',
   'INVALID_ARGUMENT',
@@ -195,6 +196,33 @@ export const StatusNameSchema = z.enum([
 ]);
 export type StatusName = z.infer<typeof StatusNameSchema>;
 
+const statusCodeMap: Record<StatusName, number> = {
+  OK: 200,
+  CANCELLED: 499,
+  UNKNOWN: 500,
+  INVALID_ARGUMENT: 400,
+  DEADLINE_EXCEEDED: 504,
+  NOT_FOUND: 404,
+  ALREADY_EXISTS: 409,
+  PERMISSION_DENIED: 403,
+  UNAUTHENTICATED: 401,
+  RESOURCE_EXHAUSTED: 429,
+  FAILED_PRECONDITION: 400,
+  ABORTED: 409,
+  OUT_OF_RANGE: 400,
+  UNIMPLEMENTED: 501,
+  INTERNAL: 500,
+  UNAVAILABLE: 503,
+  DATA_LOSS: 500,
+};
+
+export function httpStatusCode(status: StatusName): number {
+  if (!(status in statusCodeMap)) {
+    throw new Error(`Invalid status code ${status}`);
+  }
+  return statusCodeMap[status];
+}
+
 const StatusCodesSchema = z.nativeEnum(StatusCodes);
 
 // If changing below

js/genkit/package.json

@@ -156,6 +156,12 @@
       "require": "./lib/client/index.js",
       "import": "./lib/client/index.mjs",
       "default": "./lib/client/index.js"
+    },
+    "./authPolicy": {
+      "types": "./lib/authPolicy.d.ts",
+      "require": "./lib/authPolicy.js",
+      "import": "./lib/authPolicy.mjs",
+      "default": "./lib/authPolicy.js"
     }
   },
   "typesVersions": {
@@ -216,6 +222,9 @@
       ],
       "beta/client": [
         "lib/client/index"
+      ],
+      "authPolicy": [
+        "lib/authPolicy"
       ]
     }
   }

js/genkit/src/index.ts

@@ -120,6 +120,7 @@ export {
   ReflectionServer,
   StatusCodes,
   StatusSchema,
+  UserFacingError,
   defineJsonSchema,
   defineSchema,
   getCurrentEnv,
@@ -130,6 +131,7 @@ export {
   type Action,
   type ActionContext,
   type ActionMetadata,
+  type ContextProvider,
   type Flow,
   type FlowConfig,
   type FlowFn,

js/plugins/api-key/.npmignore

@@ -0,0 +1 @@
+node_modules