@btst/stack 3.0.0-rc.2 → 3.0.0-rc.4

package/dist/packages/stack/src/plugins/api/create-endpoint.cjs

@@ -1,8 +1,9 @@
 'use strict';
 
 const betterCall = require('better-call');
+const operation = require('./operation.cjs');
 
-function serializeIssues(issues) {
+function serializeValidationIssues(issues) {
   if (!Array.isArray(issues)) return [];
   return issues.filter((issue) => typeof issue?.message === "string").map((issue) => ({
     message: issue.message,
@@ -12,10 +13,11 @@ function serializeIssues(issues) {
     })
   }));
 }
-const createEndpoint = ((pathOrOptions, handlerOrOptions, handlerOrNever) => {
-  const isPathForm = typeof pathOrOptions === "string";
-  const options = isPathForm ? handlerOrOptions : pathOrOptions;
-  const wrappedOptions = options && typeof options === "object" && !options.onValidationError ? {
+function withValidationIssues(options) {
+  if (!options || typeof options !== "object" || options.onValidationError) {
+    return options;
+  }
+  return {
     ...options,
     onValidationError: ({
       message,
@@ -24,12 +26,28 @@ const createEndpoint = ((pathOrOptions, handlerOrOptions, handlerOrNever) => {
       throw new betterCall.APIError(400, {
         message,
         code: "VALIDATION_ERROR",
-        issues: serializeIssues(issues)
+        issues: serializeValidationIssues(issues)
       });
     }
-  } : options;
-  return isPathForm ? betterCall.createEndpoint(pathOrOptions, wrappedOptions, handlerOrNever) : betterCall.createEndpoint(wrappedOptions, handlerOrOptions);
+  };
+}
+const createEndpoint = ((pathOrOptions, handlerOrOptions, handlerOrNever) => {
+  const isPathForm = typeof pathOrOptions === "string";
+  const options = isPathForm ? handlerOrOptions : pathOrOptions;
+  const wrappedOptions = withValidationIssues(options);
+  const handler = isPathForm ? handlerOrNever : handlerOrOptions;
+  const endpoint = isPathForm ? betterCall.createEndpoint(pathOrOptions, wrappedOptions, handlerOrNever) : betterCall.createEndpoint(wrappedOptions, handlerOrOptions);
+  return operation.bindRouteOperationEndpoint(endpoint, handler);
+});
+createEndpoint.create = ((factoryOptions) => {
+  const create = betterCall.createEndpoint.create(factoryOptions);
+  return (path, options, handler) => {
+    return operation.bindRouteOperationEndpoint(
+      create(path, withValidationIssues(options), handler),
+      handler
+    );
+  };
 });
-createEndpoint.create = betterCall.createEndpoint.create;
 
 exports.createEndpoint = createEndpoint;
+exports.serializeValidationIssues = serializeValidationIssues;

package/dist/packages/stack/src/plugins/api/create-endpoint.mjs

@@ -1,6 +1,7 @@
 import { createEndpoint as createEndpoint$1, APIError } from 'better-call';
+import { bindRouteOperationEndpoint } from './operation.mjs';
 
-function serializeIssues(issues) {
+function serializeValidationIssues(issues) {
   if (!Array.isArray(issues)) return [];
   return issues.filter((issue) => typeof issue?.message === "string").map((issue) => ({
     message: issue.message,
@@ -10,10 +11,11 @@ function serializeIssues(issues) {
     })
   }));
 }
-const createEndpoint = ((pathOrOptions, handlerOrOptions, handlerOrNever) => {
-  const isPathForm = typeof pathOrOptions === "string";
-  const options = isPathForm ? handlerOrOptions : pathOrOptions;
-  const wrappedOptions = options && typeof options === "object" && !options.onValidationError ? {
+function withValidationIssues(options) {
+  if (!options || typeof options !== "object" || options.onValidationError) {
+    return options;
+  }
+  return {
     ...options,
     onValidationError: ({
       message,
@@ -22,12 +24,27 @@ const createEndpoint = ((pathOrOptions, handlerOrOptions, handlerOrNever) => {
       throw new APIError(400, {
         message,
         code: "VALIDATION_ERROR",
-        issues: serializeIssues(issues)
+        issues: serializeValidationIssues(issues)
       });
     }
-  } : options;
-  return isPathForm ? createEndpoint$1(pathOrOptions, wrappedOptions, handlerOrNever) : createEndpoint$1(wrappedOptions, handlerOrOptions);
+  };
+}
+const createEndpoint = ((pathOrOptions, handlerOrOptions, handlerOrNever) => {
+  const isPathForm = typeof pathOrOptions === "string";
+  const options = isPathForm ? handlerOrOptions : pathOrOptions;
+  const wrappedOptions = withValidationIssues(options);
+  const handler = isPathForm ? handlerOrNever : handlerOrOptions;
+  const endpoint = isPathForm ? createEndpoint$1(pathOrOptions, wrappedOptions, handlerOrNever) : createEndpoint$1(wrappedOptions, handlerOrOptions);
+  return bindRouteOperationEndpoint(endpoint, handler);
+});
+createEndpoint.create = ((factoryOptions) => {
+  const create = createEndpoint$1.create(factoryOptions);
+  return (path, options, handler) => {
+    return bindRouteOperationEndpoint(
+      create(path, withValidationIssues(options), handler),
+      handler
+    );
+  };
 });
-createEndpoint.create = createEndpoint$1.create;
 
-export { createEndpoint };
+export { createEndpoint, serializeValidationIssues };

package/dist/packages/stack/src/plugins/api/endpoint-inventory.cjs

@@ -0,0 +1,125 @@
+'use strict';
+
+const operation = require('./operation.cjs');
+
+function endpointIdentity(endpoint) {
+  const runtimeEndpoint = endpoint;
+  const method = runtimeEndpoint.options?.method;
+  return {
+    method: Array.isArray(method) ? method.map(String).join("|").toUpperCase() : String(method ?? "GET").toUpperCase(),
+    path: typeof runtimeEndpoint.path === "string" ? runtimeEndpoint.path : "<unknown-path>"
+  };
+}
+function operationInventoryEntry(pluginKey, pluginName, routeKey, endpoint, operation) {
+  const identity = endpointIdentity(endpoint);
+  if (operation.access === "public") {
+    return Object.freeze({
+      pluginKey,
+      pluginName,
+      routeKey,
+      ...identity,
+      source: "operation",
+      access: "public"
+    });
+  }
+  const permissionId = operation.permission?.id;
+  if (typeof permissionId !== "string" || permissionId.length === 0) {
+    throw new TypeError(
+      `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) has no stable permission id.`
+    );
+  }
+  return Object.freeze({
+    pluginKey,
+    pluginName,
+    routeKey,
+    ...identity,
+    source: "operation",
+    access: "permission",
+    permissionId
+  });
+}
+function composeEndpointInventory(pluginKey, pluginName, routes, operations, requireCompleteInventory, infrastructureRoutes, operationRouteMap) {
+  const strictInventory = requireCompleteInventory || infrastructureRoutes !== void 0 || operationRouteMap !== void 0;
+  if (!strictInventory) return [];
+  const infrastructure = infrastructureRoutes ?? {};
+  const routeMap = operationRouteMap ?? {};
+  for (const routeKey of Object.keys(routeMap).sort()) {
+    if (!Object.hasOwn(routes, routeKey)) {
+      throw new TypeError(
+        `[btst/endpoint-inventory] Plugin "${pluginKey}" operation route mapping "${routeKey}" has no composed endpoint.`
+      );
+    }
+    const operationKey = routeMap[routeKey];
+    if (typeof operationKey !== "string" || operationKey.length === 0 || !Object.hasOwn(operations, operationKey)) {
+      throw new TypeError(
+        `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" maps to unknown operation "${String(operationKey)}".`
+      );
+    }
+  }
+  for (const routeKey of Object.keys(infrastructure).sort()) {
+    if (!Object.hasOwn(routes, routeKey)) {
+      throw new TypeError(
+        `[btst/endpoint-inventory] Plugin "${pluginKey}" infrastructure route "${routeKey}" has no composed endpoint.`
+      );
+    }
+    const declaration = infrastructure[routeKey];
+    if (declaration?.access !== "public" || typeof declaration.rationale !== "string" || declaration.rationale.trim().length === 0) {
+      throw new TypeError(
+        `[btst/endpoint-inventory] Plugin "${pluginKey}" infrastructure route "${routeKey}" must declare public access and a rationale.`
+      );
+    }
+  }
+  return Object.freeze(
+    Object.entries(routes).map(([routeKey, endpoint]) => {
+      const operationKey = Object.hasOwn(routeMap, routeKey) ? routeMap[routeKey] : routeKey;
+      const operation$1 = typeof operationKey === "string" && Object.hasOwn(operations, operationKey) ? operations[operationKey] : void 0;
+      const infrastructureDeclaration = Object.hasOwn(infrastructure, routeKey) ? infrastructure[routeKey] : void 0;
+      const identity = endpointIdentity(endpoint);
+      const binding = operation.getRouteEndpointOperationBinding(endpoint);
+      if (operation$1 && infrastructureDeclaration) {
+        throw new TypeError(
+          `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) cannot be both operation-backed and infrastructure.`
+        );
+      }
+      if (operation$1) {
+        if (binding === void 0) {
+          throw new TypeError(
+            `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) must use an operations.${operationKey}.route(ctx => input) handler.`
+          );
+        }
+        if (binding.pluginKey !== pluginKey || binding.operationKey !== operationKey || binding.operation !== operation$1) {
+          throw new TypeError(
+            `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) maps to operation "${operationKey}" but is bound to "${binding.pluginKey}.${binding.operationKey}".`
+          );
+        }
+        return operationInventoryEntry(
+          pluginKey,
+          pluginName,
+          routeKey,
+          endpoint,
+          operation$1
+        );
+      }
+      if (infrastructureDeclaration) {
+        if (binding !== void 0) {
+          throw new TypeError(
+            `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) cannot be both operation-backed and infrastructure.`
+          );
+        }
+        return Object.freeze({
+          pluginKey,
+          pluginName,
+          routeKey,
+          ...identity,
+          source: "infrastructure",
+          access: "public"
+        });
+      }
+      throw new TypeError(
+        `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) has no same-key operation or infrastructure declaration.`
+      );
+    })
+  );
+}
+
+exports.composeEndpointInventory = composeEndpointInventory;

package/dist/packages/stack/src/plugins/api/endpoint-inventory.mjs

@@ -0,0 +1,123 @@
+import { getRouteEndpointOperationBinding } from './operation.mjs';
+
+function endpointIdentity(endpoint) {
+  const runtimeEndpoint = endpoint;
+  const method = runtimeEndpoint.options?.method;
+  return {
+    method: Array.isArray(method) ? method.map(String).join("|").toUpperCase() : String(method ?? "GET").toUpperCase(),
+    path: typeof runtimeEndpoint.path === "string" ? runtimeEndpoint.path : "<unknown-path>"
+  };
+}
+function operationInventoryEntry(pluginKey, pluginName, routeKey, endpoint, operation) {
+  const identity = endpointIdentity(endpoint);
+  if (operation.access === "public") {
+    return Object.freeze({
+      pluginKey,
+      pluginName,
+      routeKey,
+      ...identity,
+      source: "operation",
+      access: "public"
+    });
+  }
+  const permissionId = operation.permission?.id;
+  if (typeof permissionId !== "string" || permissionId.length === 0) {
+    throw new TypeError(
+      `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) has no stable permission id.`
+    );
+  }
+  return Object.freeze({
+    pluginKey,
+    pluginName,
+    routeKey,
+    ...identity,
+    source: "operation",
+    access: "permission",
+    permissionId
+  });
+}
+function composeEndpointInventory(pluginKey, pluginName, routes, operations, requireCompleteInventory, infrastructureRoutes, operationRouteMap) {
+  const strictInventory = requireCompleteInventory || infrastructureRoutes !== void 0 || operationRouteMap !== void 0;
+  if (!strictInventory) return [];
+  const infrastructure = infrastructureRoutes ?? {};
+  const routeMap = operationRouteMap ?? {};
+  for (const routeKey of Object.keys(routeMap).sort()) {
+    if (!Object.hasOwn(routes, routeKey)) {
+      throw new TypeError(
+        `[btst/endpoint-inventory] Plugin "${pluginKey}" operation route mapping "${routeKey}" has no composed endpoint.`
+      );
+    }
+    const operationKey = routeMap[routeKey];
+    if (typeof operationKey !== "string" || operationKey.length === 0 || !Object.hasOwn(operations, operationKey)) {
+      throw new TypeError(
+        `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" maps to unknown operation "${String(operationKey)}".`
+      );
+    }
+  }
+  for (const routeKey of Object.keys(infrastructure).sort()) {
+    if (!Object.hasOwn(routes, routeKey)) {
+      throw new TypeError(
+        `[btst/endpoint-inventory] Plugin "${pluginKey}" infrastructure route "${routeKey}" has no composed endpoint.`
+      );
+    }
+    const declaration = infrastructure[routeKey];
+    if (declaration?.access !== "public" || typeof declaration.rationale !== "string" || declaration.rationale.trim().length === 0) {
+      throw new TypeError(
+        `[btst/endpoint-inventory] Plugin "${pluginKey}" infrastructure route "${routeKey}" must declare public access and a rationale.`
+      );
+    }
+  }
+  return Object.freeze(
+    Object.entries(routes).map(([routeKey, endpoint]) => {
+      const operationKey = Object.hasOwn(routeMap, routeKey) ? routeMap[routeKey] : routeKey;
+      const operation = typeof operationKey === "string" && Object.hasOwn(operations, operationKey) ? operations[operationKey] : void 0;
+      const infrastructureDeclaration = Object.hasOwn(infrastructure, routeKey) ? infrastructure[routeKey] : void 0;
+      const identity = endpointIdentity(endpoint);
+      const binding = getRouteEndpointOperationBinding(endpoint);
+      if (operation && infrastructureDeclaration) {
+        throw new TypeError(
+          `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) cannot be both operation-backed and infrastructure.`
+        );
+      }
+      if (operation) {
+        if (binding === void 0) {
+          throw new TypeError(
+            `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) must use an operations.${operationKey}.route(ctx => input) handler.`
+          );
+        }
+        if (binding.pluginKey !== pluginKey || binding.operationKey !== operationKey || binding.operation !== operation) {
+          throw new TypeError(
+            `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) maps to operation "${operationKey}" but is bound to "${binding.pluginKey}.${binding.operationKey}".`
+          );
+        }
+        return operationInventoryEntry(
+          pluginKey,
+          pluginName,
+          routeKey,
+          endpoint,
+          operation
+        );
+      }
+      if (infrastructureDeclaration) {
+        if (binding !== void 0) {
+          throw new TypeError(
+            `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) cannot be both operation-backed and infrastructure.`
+          );
+        }
+        return Object.freeze({
+          pluginKey,
+          pluginName,
+          routeKey,
+          ...identity,
+          source: "infrastructure",
+          access: "public"
+        });
+      }
+      throw new TypeError(
+        `[btst/endpoint-inventory] Plugin "${pluginKey}" route "${routeKey}" (${identity.method} ${identity.path}) has no same-key operation or infrastructure declaration.`
+      );
+    })
+  );
+}
+
+export { composeEndpointInventory };

package/dist/packages/stack/src/plugins/api/operation.cjs

@@ -0,0 +1,208 @@
+'use strict';
+
+const z = require('zod');
+
+class OperationHttpError extends Error {
+  statusCode;
+  code;
+  issues;
+  constructor(statusCode, message, code, issues) {
+    super(message);
+    this.name = "OperationHttpError";
+    this.statusCode = statusCode;
+    this.code = code;
+    this.issues = issues;
+  }
+}
+const operationExecutors = /* @__PURE__ */ new WeakMap();
+const operationInputValidationErrors = /* @__PURE__ */ new WeakSet();
+const routeOperationBindings = /* @__PURE__ */ new WeakMap();
+function bindRouteOperationHandler(handler, binding) {
+  routeOperationBindings.set(handler, binding);
+  return handler;
+}
+function bindRouteOperationEndpoint(endpoint, handler) {
+  const binding = routeOperationBindings.get(handler);
+  if (!binding) return endpoint;
+  const existing = routeOperationBindings.get(endpoint);
+  if (existing !== void 0 && existing !== binding) {
+    throw new TypeError(
+      `Endpoint is already bound to operation "${existing.pluginKey}.${existing.operationKey}" and cannot also bind to "${binding.pluginKey}.${binding.operationKey}".`
+    );
+  }
+  routeOperationBindings.set(endpoint, binding);
+  return endpoint;
+}
+function getRouteEndpointOperationBinding(endpoint) {
+  return routeOperationBindings.get(endpoint);
+}
+function isOperationInputValidationError(cause) {
+  return typeof cause === "object" && cause !== null && operationInputValidationErrors.has(cause);
+}
+function freezeOperationData(value, seen = /* @__PURE__ */ new WeakSet(), path = "operation data") {
+  if (value === null || typeof value !== "object" && typeof value !== "function") {
+    if (typeof value === "function" || typeof value === "symbol") {
+      throw new TypeError(`${path} must contain only plain immutable data.`);
+    }
+    return value;
+  }
+  const object = value;
+  const prototype = Object.getPrototypeOf(object);
+  if (!Array.isArray(object) && prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError(
+      `${path} must contain only plain objects and arrays; mutable built-ins are not supported.`
+    );
+  }
+  if (seen.has(object)) {
+    throw new TypeError(`${path} must not contain circular references.`);
+  }
+  seen.add(object);
+  for (const key of Reflect.ownKeys(object)) {
+    if (typeof key === "symbol") {
+      throw new TypeError(`${path} must not contain symbol properties.`);
+    }
+    const descriptor = Object.getOwnPropertyDescriptor(object, key);
+    if (descriptor && !("value" in descriptor)) {
+      throw new TypeError(`${path} must not contain accessor properties.`);
+    }
+    freezeOperationData(
+      object[key],
+      seen,
+      `${path}.${key}`
+    );
+  }
+  seen.delete(object);
+  return Object.freeze(object);
+}
+function defineOperation(config) {
+  return defineOperationRuntime(config, false);
+}
+function definePassthroughOperation(config) {
+  return defineOperationRuntime(config, true);
+}
+function defineOperationRuntime(config, passthroughResult) {
+  const operationAccess = config.access ?? "authorized";
+  if (operationAccess !== "authorized" && operationAccess !== "public") {
+    throw new TypeError(
+      'Operation access must be either "authorized" or "public".'
+    );
+  }
+  const runtimePermission = config.permission;
+  const executeOperation = async (input, options) => {
+    let validatedInput;
+    try {
+      validatedInput = config.input.parse(input);
+    } catch (cause) {
+      if (cause instanceof z.z.ZodError) {
+        operationInputValidationErrors.add(cause);
+      }
+      throw cause;
+    }
+    const parsedInput = freezeOperationData(
+      validatedInput,
+      /* @__PURE__ */ new WeakSet(),
+      "operation input"
+    );
+    const trustedFacts = await config.facts({
+      input: parsedInput,
+      ...options.request ? { request: options.request } : {}
+    });
+    const permissionRequest = config.permission.schema ? runtimePermission(trustedFacts) : runtimePermission();
+    const parsedFacts = freezeOperationData(
+      permissionRequest.facts,
+      /* @__PURE__ */ new WeakSet(),
+      "operation facts"
+    );
+    let identity = null;
+    let runtimeAuth;
+    if (!options.skipAuthorization && operationAccess === "authorized" && options.auth) {
+      if (!options.request) {
+        throw new Error("Authorized operations require a request.");
+      }
+      runtimeAuth = options.auth;
+      const authorizedIdentity = await runtimeAuth.authorize(
+        options.request,
+        permissionRequest
+      );
+      identity = authorizedIdentity ? freezeOperationData(
+        authorizedIdentity,
+        /* @__PURE__ */ new WeakSet(),
+        "operation identity"
+      ) : null;
+    }
+    const additionalPermissions = await config.additionalPermissions?.({
+      input: parsedInput,
+      facts: parsedFacts,
+      ...options.request ? { request: options.request } : {}
+    }) ?? [];
+    if (!Array.isArray(additionalPermissions)) {
+      throw new TypeError(
+        "Operation additionalPermissions() must return an array of permission requests."
+      );
+    }
+    if (runtimeAuth && options.request) {
+      for (const additionalPermission of additionalPermissions) {
+        await runtimeAuth.authorize(options.request, additionalPermission);
+      }
+    }
+    const context = Object.freeze({
+      input: parsedInput,
+      facts: parsedFacts,
+      identity,
+      ...options.request ? { request: options.request } : {}
+    });
+    try {
+      await config.before?.(context);
+      const executed = await config.execute(context);
+      const result = passthroughResult ? executed : freezeOperationData(
+        executed,
+        /* @__PURE__ */ new WeakSet(),
+        "operation result"
+      );
+      const after = config.after;
+      await after?.(Object.freeze({ ...context, result }));
+      return result;
+    } catch (error) {
+      try {
+        await config.onError?.(Object.freeze({ ...context, error }));
+      } catch {
+      }
+      throw error;
+    }
+  };
+  const operation = {
+    input: config.input,
+    permission: config.permission,
+    access: operationAccess,
+    resultMode: passthroughResult ? "passthrough" : "immutable"
+  };
+  operationExecutors.set(operation, executeOperation);
+  return Object.freeze(operation);
+}
+function getOperationExecutor(operation) {
+  const executor = operationExecutors.get(operation);
+  if (!executor) throw new TypeError("Invalid operation descriptor.");
+  return executor;
+}
+function runAuthorizedOperation(operation, input, options) {
+  return getOperationExecutor(operation)(input, {
+    request: options.request,
+    ...options.auth ? { auth: options.auth } : {},
+    skipAuthorization: false
+  });
+}
+function runTrustedOperation(operation, input) {
+  return getOperationExecutor(operation)(input, {
+    skipAuthorization: true
+  });
+}
+
+exports.OperationHttpError = OperationHttpError;
+exports.bindRouteOperationEndpoint = bindRouteOperationEndpoint;
+exports.bindRouteOperationHandler = bindRouteOperationHandler;
+exports.defineOperation = defineOperation;
+exports.definePassthroughOperation = definePassthroughOperation;
+exports.getRouteEndpointOperationBinding = getRouteEndpointOperationBinding;
+exports.isOperationInputValidationError = isOperationInputValidationError;
+exports.runAuthorizedOperation = runAuthorizedOperation;
+exports.runTrustedOperation = runTrustedOperation;