@spfn/core 0.2.0-beta.56 → 0.2.0-beta.59

package/dist/authz/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @spfn/core/authz - Authorization primitives
+ *
+ * Small, domain-agnostic guards for resource ownership. The point is to make the
+ * "load, then check it belongs to the requester" step a single call so a handler
+ * can't forget it and leak another user's data (IDOR).
+ */
+interface RequireOwnerOptions<T> {
+    /**
+     * Property on the resource holding the owner id. Defaults to `'ownerId'`.
+     * SPFN entities commonly use `userId` / `createdBy` — pass it explicitly:
+     * `requireOwner(doc, userId, { ownerKey: 'userId' })`.
+     */
+    ownerKey?: keyof T;
+    /** Message for the thrown NotFoundError. @default 'not found' */
+    message?: string;
+}
+/**
+ * Return the resource only if it exists and belongs to `ownerId`; otherwise throw
+ * `NotFoundError`. Not-found and not-owned are deliberately the same response, so
+ * the endpoint never reveals that a resource exists to a non-owner.
+ *
+ * Ids are compared as strings, so number/string/bigint ids interoperate. A
+ * missing or null owner value never matches, so it throws.
+ *
+ * @example
+ * ```ts
+ * const chat = requireOwner(await chats.findById(id), userId, { ownerKey: 'userId' });
+ * // chat is non-null here, narrowed from T | null
+ * ```
+ */
+declare function requireOwner<T extends object>(resource: T | null | undefined, ownerId: string | number | bigint, options?: RequireOwnerOptions<T>): T;
+
+export { type RequireOwnerOptions, requireOwner };

package/dist/authz/index.js

@@ -0,0 +1,415 @@
+// src/errors/error-registry.ts
+var ErrorRegistry = class _ErrorRegistry {
+  errors = /* @__PURE__ */ new Map();
+  constructor(initialErrors) {
+    if (initialErrors) {
+      for (const input of initialErrors) {
+        if (input instanceof _ErrorRegistry) {
+          this.concat(input);
+        } else if (Array.isArray(input)) {
+          this.append(input);
+        } else {
+          this.append(input);
+        }
+      }
+    }
+  }
+  /**
+   * Append error class(es) to the registry
+   *
+   * @param input - Error constructor or array of constructors
+   * @returns This registry for chaining
+   */
+  append(input) {
+    if (Array.isArray(input)) {
+      for (const ErrorClass of input) {
+        this.errors.set(ErrorClass.name, ErrorClass);
+      }
+    } else {
+      this.errors.set(input.name, input);
+    }
+    return this;
+  }
+  /**
+   * Concatenate another ErrorRegistry into this one
+   *
+   * @param registry - Another ErrorRegistry to merge
+   * @returns This registry for chaining
+   */
+  concat(registry) {
+    for (const [name, ErrorClass] of registry.errors) {
+      this.errors.set(name, ErrorClass);
+    }
+    return this;
+  }
+  /**
+   * Check if error type is registered
+   *
+   * @param name - Error class name
+   */
+  has(name) {
+    return this.errors.has(name);
+  }
+  /**
+   * Deserialize error from JSON data
+   *
+   * @param data - Serialized error data with __type field
+   * @returns Deserialized error instance
+   * @throws Error if error type is not registered
+   */
+  deserialize(data) {
+    const ErrorClass = this.errors.get(data.__type);
+    if (!ErrorClass) {
+      throw new Error(`Unknown error type: ${data.__type}`);
+    }
+    return new ErrorClass(data);
+  }
+  /**
+   * Try to deserialize error, return null if type unknown
+   *
+   * @param data - Serialized error data
+   * @returns Deserialized error or null
+   */
+  tryDeserialize(data) {
+    if (!data.__type || !this.has(data.__type)) {
+      return null;
+    }
+    try {
+      return this.deserialize(data);
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Get all registered error types
+   */
+  getRegisteredTypes() {
+    return Array.from(this.errors.keys());
+  }
+};
+
+// src/errors/serializable-error.ts
+var SerializableError = class extends Error {
+  /**
+   * Serialize error to JSON-compatible object
+   *
+   * Automatically includes:
+   * - __type: Constructor name for deserialization
+   * - message: Error message
+   * - All public instance properties (except name, stack)
+   */
+  toJSON() {
+    const json = {
+      __type: this.constructor.name,
+      message: this.message
+    };
+    for (const key of Object.keys(this)) {
+      if (key !== "name" && key !== "message" && key !== "stack" && key !== "statusCode") {
+        json[key] = this[key];
+      }
+    }
+    return json;
+  }
+};
+
+// src/errors/http-errors.ts
+var HttpError = class extends SerializableError {
+  statusCode;
+  details;
+  constructor(data) {
+    super(data.message);
+    this.name = "HttpError";
+    this.statusCode = data.statusCode;
+    if (data.details) {
+      this.details = data.details;
+    }
+    Error.captureStackTrace(this, this.constructor);
+  }
+};
+var BadRequestError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Bad request",
+      statusCode: 400,
+      details: data.details
+    });
+    this.name = "BadRequestError";
+  }
+};
+var ValidationError = class extends HttpError {
+  fields;
+  constructor(data) {
+    super({
+      message: data.message,
+      statusCode: 400,
+      details: data.details
+    });
+    this.name = "ValidationError";
+    if (data.fields) {
+      this.fields = data.fields;
+    }
+  }
+};
+var UnauthorizedError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Authentication required",
+      statusCode: 401,
+      details: data.details
+    });
+    this.name = "UnauthorizedError";
+  }
+};
+var ForbiddenError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Access forbidden",
+      statusCode: 403,
+      details: data.details
+    });
+    this.name = "ForbiddenError";
+  }
+};
+var NotFoundError = class extends HttpError {
+  resource;
+  constructor(data = {}) {
+    super({
+      message: data.message || "Resource not found",
+      statusCode: 404,
+      details: data.details
+    });
+    this.name = "NotFoundError";
+    if (data.resource) {
+      this.resource = data.resource;
+    }
+  }
+};
+var ConflictError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Resource conflict",
+      statusCode: 409,
+      details: data.details
+    });
+    this.name = "ConflictError";
+  }
+};
+var GoneError = class extends HttpError {
+  resource;
+  constructor(data = {}) {
+    super({
+      message: data.message || "Resource permanently deleted",
+      statusCode: 410,
+      details: data.details
+    });
+    this.name = "GoneError";
+    if (data.resource) {
+      this.resource = data.resource;
+    }
+  }
+};
+var TooManyRequestsError = class extends HttpError {
+  retryAfter;
+  constructor(data = {}) {
+    super({
+      message: data.message || "Too many requests",
+      statusCode: 429,
+      details: data.details
+    });
+    this.name = "TooManyRequestsError";
+    if (data.retryAfter) {
+      this.retryAfter = data.retryAfter;
+    }
+  }
+};
+var InternalServerError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Internal server error",
+      statusCode: 500,
+      details: data.details
+    });
+    this.name = "InternalServerError";
+  }
+};
+var UnsupportedMediaTypeError = class extends HttpError {
+  mediaType;
+  supportedTypes;
+  constructor(data = {}) {
+    super({
+      message: data.message || "Unsupported media type",
+      statusCode: 415,
+      details: data.details
+    });
+    this.name = "UnsupportedMediaTypeError";
+    if (data.mediaType) {
+      this.mediaType = data.mediaType;
+    }
+    if (data.supportedTypes) {
+      this.supportedTypes = data.supportedTypes;
+    }
+  }
+};
+var UnprocessableEntityError = class extends HttpError {
+  constructor(data = {}) {
+    super({
+      message: data.message || "Unprocessable entity",
+      statusCode: 422,
+      details: data.details
+    });
+    this.name = "UnprocessableEntityError";
+  }
+};
+var ServiceUnavailableError = class extends HttpError {
+  retryAfter;
+  constructor(data = {}) {
+    super({
+      message: data.message || "Service unavailable",
+      statusCode: 503,
+      details: data.details
+    });
+    this.name = "ServiceUnavailableError";
+    if (data.retryAfter) {
+      this.retryAfter = data.retryAfter;
+    }
+  }
+};
+
+// src/errors/database-errors.ts
+var DatabaseError = class extends SerializableError {
+  statusCode;
+  details;
+  constructor(data) {
+    super(data.message);
+    this.name = "DatabaseError";
+    this.statusCode = data.statusCode ?? 500;
+    this.details = data.details;
+    Error.captureStackTrace(this, this.constructor);
+  }
+  /**
+   * Whether this error's message/details are derived from the raw database
+   * driver (SQL text, table/column/constraint names, parameter values) and
+   * therefore must NOT be exposed to clients in production. Defined as a
+   * prototype getter so it is never serialized into the response by toJSON().
+   * Subclasses with a safe, constructed message override this to `false`.
+   */
+  get internal() {
+    return true;
+  }
+};
+var ConnectionError = class extends DatabaseError {
+  constructor(data) {
+    super({ message: data.message, statusCode: 503, details: data.details });
+    this.name = "ConnectionError";
+  }
+};
+var QueryError = class extends DatabaseError {
+  constructor(data) {
+    super({
+      message: data.message,
+      statusCode: data.statusCode ?? 500,
+      details: data.details
+    });
+    this.name = "QueryError";
+  }
+};
+var EntityNotFoundError = class extends QueryError {
+  resource;
+  id;
+  constructor(data) {
+    super({
+      message: `${data.resource} with id ${data.id} not found`,
+      statusCode: 404,
+      details: { resource: data.resource, id: data.id }
+    });
+    this.name = "EntityNotFoundError";
+    this.resource = data.resource;
+    this.id = data.id;
+  }
+  // Message/details are constructed from the resource + id, not driver text
+  get internal() {
+    return false;
+  }
+};
+var ConstraintViolationError = class extends QueryError {
+  constructor(data) {
+    super({ message: data.message, statusCode: 400, details: data.details });
+    this.name = "ConstraintViolationError";
+  }
+};
+var TransactionError = class extends DatabaseError {
+  constructor(data) {
+    super({
+      message: data.message,
+      statusCode: data.statusCode ?? 500,
+      details: data.details
+    });
+    this.name = "TransactionError";
+  }
+};
+var DeadlockError = class extends TransactionError {
+  constructor(data) {
+    super({ message: data.message, statusCode: 409, details: data.details });
+    this.name = "DeadlockError";
+  }
+};
+var DuplicateEntryError = class extends QueryError {
+  field;
+  value;
+  constructor(data) {
+    super({
+      message: `${data.field} already exists`,
+      statusCode: 409,
+      details: { field: data.field }
+    });
+    this.name = "DuplicateEntryError";
+    this.field = data.field;
+    this.value = data.value;
+  }
+  // Field-only message/details — safe to surface to the client (not internal)
+  get internal() {
+    return false;
+  }
+};
+
+// src/errors/index.ts
+var errorRegistry = new ErrorRegistry();
+errorRegistry.append([
+  HttpError,
+  BadRequestError,
+  ValidationError,
+  UnauthorizedError,
+  ForbiddenError,
+  NotFoundError,
+  ConflictError,
+  GoneError,
+  TooManyRequestsError,
+  UnsupportedMediaTypeError,
+  UnprocessableEntityError,
+  InternalServerError,
+  ServiceUnavailableError
+]);
+errorRegistry.append([
+  DatabaseError,
+  ConnectionError,
+  QueryError,
+  EntityNotFoundError,
+  ConstraintViolationError,
+  TransactionError,
+  DeadlockError,
+  DuplicateEntryError
+]);
+
+// src/authz/index.ts
+function requireOwner(resource, ownerId, options = {}) {
+  const ownerKey = options.ownerKey ?? "ownerId";
+  const value = resource ? resource[ownerKey] : void 0;
+  if (!resource || value === null || value === void 0 || String(value) !== String(ownerId)) {
+    throw new NotFoundError({ message: options.message ?? "not found" });
+  }
+  return resource;
+}
+
+export { requireOwner };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/authz/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/errors/error-registry.ts","../../src/errors/serializable-error.ts","../../src/errors/http-errors.ts","../../src/errors/database-errors.ts","../../src/errors/index.ts","../../src/authz/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * Error Registry\n *\n * Central registry for serializable error types.\n * Enables automatic error deserialization on the client side.\n */\n\nimport type { SerializableError } from './serializable-error';\n\n/**\n * Error constructor type\n */\nexport type SerializableErrorConstructor = new (data: any) => SerializableError;\n\n/**\n * Input type for ErrorRegistry constructor\n */\nexport type ErrorRegistryInput =\n    | SerializableErrorConstructor\n    | SerializableErrorConstructor[]\n    | ErrorRegistry;\n\n/**\n * Error registry for serialization/deserialization\n *\n * @example\n * ```typescript\n * // Create registry with initial errors\n * const registry = new ErrorRegistry([\n *     errorRegistry,           // Another ErrorRegistry\n *     PaymentFailedError,      // Single error class\n *     [RefundError, OrderError], // Array of error classes\n * ]);\n *\n * // Or create empty and append\n * const registry = new ErrorRegistry();\n * registry\n *     .append(ValidationError)\n *     .append([PaymentFailedError, RefundError]);\n *\n * // Deserialize from JSON\n * const error = registry.deserialize({\n *     __type: 'PaymentFailedError',\n *     message: 'Payment failed',\n *     transactionId: 'tx_123',\n *     reason: 'insufficient_funds'\n * });\n *\n * // error instanceof PaymentFailedError === true\n * ```\n */\nexport class ErrorRegistry\n{\n    private errors = new Map<string, SerializableErrorConstructor>();\n\n    constructor(initialErrors?: ErrorRegistryInput[])\n    {\n        if (initialErrors)\n        {\n            for (const input of initialErrors)\n            {\n                if (input instanceof ErrorRegistry)\n                {\n                    this.concat(input);\n                }\n                else if (Array.isArray(input))\n                {\n                    this.append(input);\n                }\n                else\n                {\n                    this.append(input);\n                }\n            }\n        }\n    }\n\n    /**\n     * Append error class(es) to the registry\n     *\n     * @param ErrorClass - Single error constructor\n     * @returns This registry for chaining\n     */\n    append(ErrorClass: SerializableErrorConstructor): this;\n\n    /**\n     * Append error class(es) to the registry\n     *\n     * @param ErrorClasses - Array of error constructors\n     * @returns This registry for chaining\n     */\n    append(ErrorClasses: SerializableErrorConstructor[]): this;\n\n    /**\n     * Append error class(es) to the registry\n     *\n     * @param input - Error constructor or array of constructors\n     * @returns This registry for chaining\n     */\n    append(input: SerializableErrorConstructor | SerializableErrorConstructor[]): this\n    {\n        if (Array.isArray(input))\n        {\n            for (const ErrorClass of input)\n            {\n                this.errors.set(ErrorClass.name, ErrorClass);\n            }\n        }\n        else\n        {\n            this.errors.set(input.name, input);\n        }\n\n        return this;\n    }\n\n    /**\n     * Concatenate another ErrorRegistry into this one\n     *\n     * @param registry - Another ErrorRegistry to merge\n     * @returns This registry for chaining\n     */\n    concat(registry: ErrorRegistry): this\n    {\n        for (const [name, ErrorClass] of registry.errors)\n        {\n            this.errors.set(name, ErrorClass);\n        }\n\n        return this;\n    }\n\n    /**\n     * Check if error type is registered\n     *\n     * @param name - Error class name\n     */\n    has(name: string): boolean\n    {\n        return this.errors.has(name);\n    }\n\n    /**\n     * Deserialize error from JSON data\n     *\n     * @param data - Serialized error data with __type field\n     * @returns Deserialized error instance\n     * @throws Error if error type is not registered\n     */\n    deserialize(data: { __type: string; [key: string]: any }): SerializableError\n    {\n        const ErrorClass = this.errors.get(data.__type);\n\n        if (!ErrorClass)\n        {\n            throw new Error(`Unknown error type: ${data.__type}`);\n        }\n\n        // Pass entire data object to constructor\n        return new ErrorClass(data);\n    }\n\n    /**\n     * Try to deserialize error, return null if type unknown\n     *\n     * @param data - Serialized error data\n     * @returns Deserialized error or null\n     */\n    tryDeserialize(data: { __type?: string; [key: string]: any }): SerializableError | null\n    {\n        if (!data.__type || !this.has(data.__type))\n        {\n            return null;\n        }\n\n        try\n        {\n            return this.deserialize(data as any);\n        }\n        catch\n        {\n            return null;\n        }\n    }\n\n    /**\n     * Get all registered error types\n     */\n    getRegisteredTypes(): string[]\n    {\n        return Array.from(this.errors.keys());\n    }\n}\n","/**\n * Serializable Error Base Class\n *\n * Base class for errors that can be serialized/deserialized across HTTP boundary.\n * Automatically serializes public fields for transmission to client.\n */\n\n/**\n * Serialized error format for JSON transmission\n */\nexport interface SerializedError\n{\n    __type: string;\n    message: string;\n    [key: string]: unknown;\n}\n\n/**\n * Base class for all serializable errors\n *\n * Features:\n * - Auto-serialization of public fields via toJSON()\n * - Constructor accepts object with all fields\n * - Type-safe error handling with instanceof\n *\n * @example\n * ```typescript\n * class PaymentFailedError extends SerializableError\n * {\n *     readonly statusCode = 402;\n *     transactionId!: string;\n *     reason!: 'insufficient_funds' | 'card_declined';\n *\n *     constructor(data: {\n *         message: string;\n *         transactionId: string;\n *         reason: 'insufficient_funds' | 'card_declined';\n *     })\n *     {\n *         super(data.message);\n *         this.name = 'PaymentFailedError';\n *         Object.assign(this, data);\n *     }\n * }\n * ```\n */\nexport abstract class SerializableError extends Error\n{\n    /**\n     * HTTP status code for this error type\n     */\n    abstract readonly statusCode: number;\n\n    /**\n     * Serialize error to JSON-compatible object\n     *\n     * Automatically includes:\n     * - __type: Constructor name for deserialization\n     * - message: Error message\n     * - All public instance properties (except name, stack)\n     */\n    toJSON(): SerializedError\n    {\n        const json: SerializedError = {\n            __type: this.constructor.name,\n            message: this.message,\n        };\n\n        // Extract all public instance properties\n        for (const key of Object.keys(this))\n        {\n            // Skip Error built-ins and statusCode (inferred from type)\n            if (key !== 'name' && key !== 'message' && key !== 'stack' && key !== 'statusCode')\n            {\n                json[key] = (this as unknown as Record<string, unknown>)[key];\n            }\n        }\n\n        return json;\n    }\n}\n","/**\n * HTTP Error Classes\n *\n * Standard HTTP error classes for API responses\n * All errors are serializable for type-safe client-side error handling\n */\n\nimport { SerializableError } from './serializable-error';\n\n/**\n * Base HTTP Error\n *\n * Base class for all HTTP-related errors\n */\nexport class HttpError extends SerializableError\n{\n    public readonly statusCode: number;\n    public details?: Record<string, unknown>;\n\n    constructor(data: {\n        message: string;\n        statusCode: number;\n        details?: Record<string, unknown>;\n    })\n    {\n        super(data.message);\n\n        this.name = 'HttpError';\n        this.statusCode = data.statusCode;\n\n        if (data.details)\n        {\n            this.details = data.details;\n        }\n\n        Error.captureStackTrace(this, this.constructor);\n    }\n}\n\n/**\n * Bad Request Error (400)\n *\n * Generic bad request - malformed syntax, invalid parameters, etc.\n */\nexport class BadRequestError extends HttpError\n{\n    constructor(data: { message?: string; details?: Record<string, any> } = {})\n    {\n        super({\n            message: data.message || 'Bad request',\n            statusCode: 400,\n            details: data.details,\n        });\n\n        this.name = 'BadRequestError';\n    }\n}\n\n/**\n * Validation Error (400)\n *\n * Input validation failure (request params, query, body)\n * Used by define-route system for automatic validation\n */\nexport class ValidationError extends HttpError\n{\n    fields?: Array<{ path: string; message: string; value?: any }>;\n\n    constructor(data: {\n        message: string;\n        fields?: Array<{ path: string; message: string; value?: any }>;\n        details?: Record<string, any>;\n    })\n    {\n        super({\n            message: data.message,\n            statusCode: 400,\n            details: data.details,\n        });\n\n        this.name = 'ValidationError';\n\n        if (data.fields)\n        {\n            this.fields = data.fields;\n        }\n    }\n}\n\n/**\n * Unauthorized Error (401)\n *\n * Authentication required or authentication failed\n */\nexport class UnauthorizedError extends HttpError\n{\n    constructor(data: { message?: string; details?: Record<string, any> } = {})\n    {\n        super({\n            message: data.message || 'Authentication required',\n            statusCode: 401,\n            details: data.details,\n        });\n\n        this.name = 'UnauthorizedError';\n    }\n}\n\n/**\n * Forbidden Error (403)\n *\n * Authenticated but lacks permission to access resource\n */\nexport class ForbiddenError extends HttpError\n{\n    constructor(data: { message?: string; details?: Record<string, any> } = {})\n    {\n        super({\n            message: data.message || 'Access forbidden',\n            statusCode: 403,\n            details: data.details,\n        });\n\n        this.name = 'ForbiddenError';\n    }\n}\n\n/**\n * Not Found Error (404)\n *\n * Requested resource does not exist\n */\nexport class NotFoundError extends HttpError\n{\n    resource?: string;\n\n    constructor(data: { message?: string; resource?: string; details?: Record<string, any> } = {})\n    {\n        super({\n            message: data.message || 'Resource not found',\n            statusCode: 404,\n            details: data.details,\n        });\n\n        this.name = 'NotFoundError';\n\n        if (data.resource)\n        {\n            this.resource = data.resource;\n        }\n    }\n}\n\n/**\n * Conflict Error (409)\n *\n * Generic conflict - resource state conflict, concurrent modification, etc.\n */\nexport class ConflictError extends HttpError\n{\n    constructor(data: { message?: string; details?: Record<string, any> } = {})\n    {\n        super({\n            message: data.message || 'Resource conflict',\n            statusCode: 409,\n            details: data.details,\n        });\n\n        this.name = 'ConflictError';\n    }\n}\n\n/**\n * Gone Error (410)\n *\n * Resource permanently deleted and no longer available\n */\nexport class GoneError extends HttpError\n{\n    resource?: string;\n\n    constructor(data: { message?: string; resource?: string; details?: Record<string, any> } = {})\n    {\n        super({\n            message: data.message || 'Resource permanently deleted',\n            statusCode: 410,\n            details: data.details,\n        });\n\n        this.name = 'GoneError';\n\n        if (data.resource)\n        {\n            this.resource = data.resource;\n        }\n    }\n}\n\n/**\n * Too Many Requests Error (429)\n *\n * Rate limit exceeded\n */\nexport class TooManyRequestsError extends HttpError\n{\n    retryAfter?: number;\n\n    constructor(data: {\n        message?: string;\n        retryAfter?: number;\n        details?: Record<string, any>;\n    } = {})\n    {\n        super({\n            message: data.message || 'Too many requests',\n            statusCode: 429,\n            details: data.details,\n        });\n\n        this.name = 'TooManyRequestsError';\n\n        if (data.retryAfter)\n        {\n            this.retryAfter = data.retryAfter;\n        }\n    }\n}\n\n/**\n * Internal Server Error (500)\n *\n * Generic server error when no specific error type applies\n */\nexport class InternalServerError extends HttpError\n{\n    constructor(data: { message?: string; details?: Record<string, any> } = {})\n    {\n        super({\n            message: data.message || 'Internal server error',\n            statusCode: 500,\n            details: data.details,\n        });\n\n        this.name = 'InternalServerError';\n    }\n}\n\n/**\n * Unsupported Media Type Error (415)\n *\n * Media type not supported - invalid file type, content type, etc.\n */\nexport class UnsupportedMediaTypeError extends HttpError\n{\n    mediaType?: string;\n    supportedTypes?: string[];\n\n    constructor(data: {\n        message?: string;\n        mediaType?: string;\n        supportedTypes?: string[];\n        details?: Record<string, any>;\n    } = {})\n    {\n        super({\n            message: data.message || 'Unsupported media type',\n            statusCode: 415,\n            details: data.details,\n        });\n\n        this.name = 'UnsupportedMediaTypeError';\n\n        if (data.mediaType)\n        {\n            this.mediaType = data.mediaType;\n        }\n\n        if (data.supportedTypes)\n        {\n            this.supportedTypes = data.supportedTypes;\n        }\n    }\n}\n\n/**\n * Unprocessable Entity Error (422)\n *\n * Request is well-formed but contains semantic errors\n */\nexport class UnprocessableEntityError extends HttpError\n{\n    constructor(data: { message?: string; details?: Record<string, any> } = {})\n    {\n        super({\n            message: data.message || 'Unprocessable entity',\n            statusCode: 422,\n            details: data.details,\n        });\n\n        this.name = 'UnprocessableEntityError';\n    }\n}\n\n/**\n * Service Unavailable Error (503)\n *\n * Service temporarily unavailable (maintenance, overload, etc.)\n */\nexport class ServiceUnavailableError extends HttpError\n{\n    retryAfter?: number;\n\n    constructor(data: {\n        message?: string;\n        retryAfter?: number;\n        details?: Record<string, any>;\n    } = {})\n    {\n        super({\n            message: data.message || 'Service unavailable',\n            statusCode: 503,\n            details: data.details,\n        });\n\n        this.name = 'ServiceUnavailableError';\n\n        if (data.retryAfter)\n        {\n            this.retryAfter = data.retryAfter;\n        }\n    }\n}\n","/**\n * Database Error Classes\n *\n * Type-safe error handling with custom error class hierarchy\n * Mapped to HTTP status codes for API responses\n * All errors extend SerializableError for consistent JSON serialization\n */\n\nimport { SerializableError } from './serializable-error';\n\n/**\n * Base Database Error\n *\n * Base class for all database-related errors\n */\nexport class DatabaseError<TDetails extends Record<string, unknown> = Record<string, unknown>>\n    extends SerializableError\n{\n    public readonly statusCode: number;\n    public readonly details?: TDetails;\n\n    constructor(data: {\n        message: string;\n        statusCode?: number;\n        details?: TDetails;\n    })\n    {\n        super(data.message);\n        this.name = 'DatabaseError';\n        this.statusCode = data.statusCode ?? 500;\n        this.details = data.details;\n        Error.captureStackTrace(this, this.constructor);\n    }\n\n    /**\n     * Whether this error's message/details are derived from the raw database\n     * driver (SQL text, table/column/constraint names, parameter values) and\n     * therefore must NOT be exposed to clients in production. Defined as a\n     * prototype getter so it is never serialized into the response by toJSON().\n     * Subclasses with a safe, constructed message override this to `false`.\n     */\n    get internal(): boolean\n    {\n        return true;\n    }\n}\n\n/**\n * Connection Error (503 Service Unavailable)\n *\n * Database connection failure, connection pool exhaustion, etc.\n */\nexport class ConnectionError extends DatabaseError\n{\n    constructor(data: { message: string; details?: Record<string, unknown> })\n    {\n        super({ message: data.message, statusCode: 503, details: data.details });\n        this.name = 'ConnectionError';\n    }\n}\n\n/**\n * Query Error (500 Internal Server Error)\n *\n * SQL query execution failure, syntax errors, etc.\n */\nexport class QueryError extends DatabaseError\n{\n    constructor(data: {\n        message: string;\n        statusCode?: number;\n        details?: Record<string, unknown>;\n    })\n    {\n        super({\n            message: data.message,\n            statusCode: data.statusCode ?? 500,\n            details: data.details,\n        });\n        this.name = 'QueryError';\n    }\n}\n\n/**\n * Entity Not Found Error (404 Not Found)\n *\n * Database entity does not exist\n */\nexport class EntityNotFoundError extends QueryError\n{\n    public readonly resource: string;\n    public readonly id: string | number;\n\n    constructor(data: { resource: string; id: string | number })\n    {\n        super({\n            message: `${data.resource} with id ${data.id} not found`,\n            statusCode: 404,\n            details: { resource: data.resource, id: data.id },\n        });\n        this.name = 'EntityNotFoundError';\n        this.resource = data.resource;\n        this.id = data.id;\n    }\n\n    // Message/details are constructed from the resource + id, not driver text\n    override get internal(): boolean\n    {\n        return false;\n    }\n}\n\n/**\n * Constraint Violation Error (400 Bad Request)\n *\n * Database constraint violation (NOT NULL, CHECK, FOREIGN KEY, etc.)\n * This is different from HTTP ValidationError which validates request input\n */\nexport class ConstraintViolationError extends QueryError\n{\n    constructor(data: { message: string; details?: Record<string, unknown> })\n    {\n        super({ message: data.message, statusCode: 400, details: data.details });\n        this.name = 'ConstraintViolationError';\n    }\n}\n\n/**\n * Transaction Error (500 Internal Server Error)\n *\n * Transaction start/commit/rollback failure\n */\nexport class TransactionError extends DatabaseError\n{\n    constructor(data: {\n        message: string;\n        statusCode?: number;\n        details?: Record<string, unknown>;\n    })\n    {\n        super({\n            message: data.message,\n            statusCode: data.statusCode ?? 500,\n            details: data.details,\n        });\n        this.name = 'TransactionError';\n    }\n}\n\n/**\n * Deadlock Error (409 Conflict)\n *\n * Database deadlock detected\n */\nexport class DeadlockError extends TransactionError\n{\n    constructor(data: { message: string; details?: Record<string, unknown> })\n    {\n        super({ message: data.message, statusCode: 409, details: data.details });\n        this.name = 'DeadlockError';\n    }\n}\n\n/**\n * Duplicate Entry Error (409 Conflict)\n *\n * Unique constraint violation (e.g., duplicate email)\n */\nexport class DuplicateEntryError extends QueryError\n{\n    public readonly field: string;\n    public readonly value: string | number;\n\n    constructor(data: { field: string; value: string | number })\n    {\n        // The client-facing message/details name the field but NOT the value: echoing\n        // the value back (e.g. an email) confirms it exists, an enumeration aid. The\n        // raw value stays on the instance for server-side handling/logging.\n        super({\n            message: `${data.field} already exists`,\n            statusCode: 409,\n            details: { field: data.field },\n        });\n        this.name = 'DuplicateEntryError';\n        this.field = data.field;\n        this.value = data.value;\n    }\n\n    // Field-only message/details — safe to surface to the client (not internal)\n    override get internal(): boolean\n    {\n        return false;\n    }\n}\n","/**\n * Error Module Exports\n *\n * Entry point for error handling module with serialization support\n */\n\n// Core Error Registry\n// Pre-configured registry with all built-in HTTP and Database errors\nimport { ErrorRegistry } from './error-registry';\nimport {\n    HttpError,\n    BadRequestError,\n    ValidationError,\n    UnauthorizedError,\n    ForbiddenError,\n    NotFoundError,\n    ConflictError,\n    GoneError,\n    TooManyRequestsError,\n    UnsupportedMediaTypeError,\n    UnprocessableEntityError,\n    InternalServerError,\n    ServiceUnavailableError,\n} from './http-errors';\nimport {\n    DatabaseError,\n    ConnectionError,\n    QueryError,\n    EntityNotFoundError,\n    ConstraintViolationError,\n    TransactionError,\n    DeadlockError,\n    DuplicateEntryError,\n} from './database-errors';\n\n// Base Classes\nexport { SerializableError } from './serializable-error';\nexport type { SerializedError } from './serializable-error';\nexport { ErrorRegistry } from './error-registry';\nexport type { SerializableErrorConstructor, ErrorRegistryInput } from './error-registry';\n\n// Database Error Classes\nexport {\n    DatabaseError,\n    ConnectionError,\n    QueryError,\n    EntityNotFoundError,\n    ConstraintViolationError,\n    TransactionError,\n    DeadlockError,\n    DuplicateEntryError,\n} from './database-errors';\n\n// HTTP Error Classes\nexport {\n    HttpError,\n    BadRequestError,\n    ValidationError,\n    UnauthorizedError,\n    ForbiddenError,\n    NotFoundError,\n    ConflictError,\n    GoneError,\n    TooManyRequestsError,\n    UnsupportedMediaTypeError,\n    UnprocessableEntityError,\n    InternalServerError,\n    ServiceUnavailableError,\n} from './http-errors';\n\n// Error Utilities\nexport {\n    isDatabaseError,\n    isHttpError,\n    hasStatusCode,\n} from './error-utils';\n\nexport const errorRegistry = new ErrorRegistry();\n\n// HTTP Errors\nerrorRegistry.append([\n    HttpError,\n    BadRequestError,\n    ValidationError,\n    UnauthorizedError,\n    ForbiddenError,\n    NotFoundError,\n    ConflictError,\n    GoneError,\n    TooManyRequestsError,\n    UnsupportedMediaTypeError,\n    UnprocessableEntityError,\n    InternalServerError,\n    ServiceUnavailableError,\n]);\n\n// Database Errors\nerrorRegistry.append([\n    DatabaseError,\n    ConnectionError,\n    QueryError,\n    EntityNotFoundError,\n    ConstraintViolationError,\n    TransactionError,\n    DeadlockError,\n    DuplicateEntryError,\n]);\n\nexport * as HttpErrors from './http-errors';\nexport * as DatabaseErrors from './database-errors';\n","/**\n * @spfn/core/authz - Authorization primitives\n *\n * Small, domain-agnostic guards for resource ownership. The point is to make the\n * \"load, then check it belongs to the requester\" step a single call so a handler\n * can't forget it and leak another user's data (IDOR).\n */\n\nimport { NotFoundError } from '../errors';\n\nexport interface RequireOwnerOptions<T>\n{\n    /**\n     * Property on the resource holding the owner id. Defaults to `'ownerId'`.\n     * SPFN entities commonly use `userId` / `createdBy` — pass it explicitly:\n     * `requireOwner(doc, userId, { ownerKey: 'userId' })`.\n     */\n    ownerKey?: keyof T;\n\n    /** Message for the thrown NotFoundError. @default 'not found' */\n    message?: string;\n}\n\n/**\n * Return the resource only if it exists and belongs to `ownerId`; otherwise throw\n * `NotFoundError`. Not-found and not-owned are deliberately the same response, so\n * the endpoint never reveals that a resource exists to a non-owner.\n *\n * Ids are compared as strings, so number/string/bigint ids interoperate. A\n * missing or null owner value never matches, so it throws.\n *\n * @example\n * ```ts\n * const chat = requireOwner(await chats.findById(id), userId, { ownerKey: 'userId' });\n * // chat is non-null here, narrowed from T | null\n * ```\n */\nexport function requireOwner<T extends object>(\n    resource: T | null | undefined,\n    ownerId: string | number | bigint,\n    options: RequireOwnerOptions<T> = {},\n): T\n{\n    const ownerKey = (options.ownerKey ?? 'ownerId') as keyof T;\n    const value = resource ? (resource as Record<PropertyKey, unknown>)[ownerKey] : undefined;\n\n    if (!resource || value === null || value === undefined || String(value) !== String(ownerId))\n    {\n        throw new NotFoundError({ message: options.message ?? 'not found' });\n    }\n\n    return resource;\n}\n"]}

package/dist/{boss-CEik0yq-.d.ts → boss-CjClX7G4.d.ts}

@@ -21,6 +21,13 @@ interface JobOptions {
      * @default 1000
      */
     retryDelay?: number;
+    /**
+     * Exponential backoff between retries (retryDelay * 2^attempt). Defaults to
+     * true so a failed cohort (e.g. on a provider 429) doesn't all retry at the
+     * same fixed offset — a thundering herd. Set false for fixed retryDelay.
+     * @default true
+     */
+    retryBackoff?: boolean;
     /**
      * Job expiration in seconds
      * @default 300 (5 minutes)

package/dist/config/index.d.ts

@@ -564,6 +564,50 @@ declare const coreEnvSchema: {
     } & {
         key: "TRUSTED_PROXY_HOPS";
     };
+    RATE_LIMIT_MODE: Omit<_spfn_core_env.EnvVarSchema<"off" | "on">, "key" | "type" | "validator"> & {
+        type: "enum";
+        validator: (val: string) => "off" | "on";
+    } & {
+        key: "RATE_LIMIT_MODE";
+    };
+    RATE_LIMIT_DEFAULT_LIMIT: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "RATE_LIMIT_DEFAULT_LIMIT";
+    };
+    RATE_LIMIT_DEFAULT_WINDOW_MS: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "RATE_LIMIT_DEFAULT_WINDOW_MS";
+    };
+    RATE_LIMIT_FAIL_CLOSED: {
+        description: string;
+        default: boolean;
+    } & {
+        type: "boolean";
+        validator: (value: string) => boolean;
+    } & {
+        key: "RATE_LIMIT_FAIL_CLOSED";
+    };
+    SAFE_FETCH_BLOCK_PRIVATE_IPS: {
+        description: string;
+        default: boolean;
+    } & {
+        type: "boolean";
+        validator: (value: string) => boolean;
+    } & {
+        key: "SAFE_FETCH_BLOCK_PRIVATE_IPS";
+    };
 };
 
 /**
@@ -1120,6 +1164,50 @@ declare const registry: _spfn_core_env.EnvRegistry<{
     } & {
         key: "TRUSTED_PROXY_HOPS";
     };
+    RATE_LIMIT_MODE: Omit<_spfn_core_env.EnvVarSchema<"off" | "on">, "key" | "type" | "validator"> & {
+        type: "enum";
+        validator: (val: string) => "off" | "on";
+    } & {
+        key: "RATE_LIMIT_MODE";
+    };
+    RATE_LIMIT_DEFAULT_LIMIT: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "RATE_LIMIT_DEFAULT_LIMIT";
+    };
+    RATE_LIMIT_DEFAULT_WINDOW_MS: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "RATE_LIMIT_DEFAULT_WINDOW_MS";
+    };
+    RATE_LIMIT_FAIL_CLOSED: {
+        description: string;
+        default: boolean;
+    } & {
+        type: "boolean";
+        validator: (value: string) => boolean;
+    } & {
+        key: "RATE_LIMIT_FAIL_CLOSED";
+    };
+    SAFE_FETCH_BLOCK_PRIVATE_IPS: {
+        description: string;
+        default: boolean;
+    } & {
+        type: "boolean";
+        validator: (value: string) => boolean;
+    } & {
+        key: "SAFE_FETCH_BLOCK_PRIVATE_IPS";
+    };
 }>;
 /**
  * Validated environment configuration
@@ -1669,6 +1757,50 @@ declare const env: _spfn_core_env.InferEnvType<{
     } & {
         key: "TRUSTED_PROXY_HOPS";
     };
+    RATE_LIMIT_MODE: Omit<_spfn_core_env.EnvVarSchema<"off" | "on">, "key" | "type" | "validator"> & {
+        type: "enum";
+        validator: (val: string) => "off" | "on";
+    } & {
+        key: "RATE_LIMIT_MODE";
+    };
+    RATE_LIMIT_DEFAULT_LIMIT: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "RATE_LIMIT_DEFAULT_LIMIT";
+    };
+    RATE_LIMIT_DEFAULT_WINDOW_MS: {
+        description: string;
+        default: number;
+        examples: number[];
+    } & {
+        type: "number";
+        validator: (value: string) => number;
+    } & {
+        key: "RATE_LIMIT_DEFAULT_WINDOW_MS";
+    };
+    RATE_LIMIT_FAIL_CLOSED: {
+        description: string;
+        default: boolean;
+    } & {
+        type: "boolean";
+        validator: (value: string) => boolean;
+    } & {
+        key: "RATE_LIMIT_FAIL_CLOSED";
+    };
+    SAFE_FETCH_BLOCK_PRIVATE_IPS: {
+        description: string;
+        default: boolean;
+    } & {
+        type: "boolean";
+        validator: (value: string) => boolean;
+    } & {
+        key: "SAFE_FETCH_BLOCK_PRIVATE_IPS";
+    };
 }>;
 
 export { env, coreEnvSchema as envSchema, registry };