@develit-io/backend-sdk 9.11.12 → 9.11.14

package/dist/index.d.mts

@@ -550,7 +550,7 @@ declare const paginationSchema: z.$ZodObject<Readonly<Readonly<{
 
 interface BaseEvent {
     metadata: {
-        timestamp: string;
+        timestamp: Date;
         correlationId: string;
         entityId: string;
         /**

package/dist/index.d.ts

@@ -550,7 +550,7 @@ declare const paginationSchema: z.$ZodObject<Readonly<Readonly<{
 
 interface BaseEvent {
     metadata: {
-        timestamp: string;
+        timestamp: Date;
         correlationId: string;
         entityId: string;
         /**

package/dist/middlewares.d.mts

@@ -15,18 +15,102 @@ interface AccessMiddlewareOptions {
     errorMessage?: string;
 }
 type AccessRequestResolver<TScope extends string = string> = ScopeCondition<TScope> | ((context: Context) => ScopeCondition<TScope>);
+/**
+ * Middleware that enforces role-based access control (RBAC).
+ *
+ * Verifies the authenticated user has the required scopes/permissions by calling
+ * the `RBAC_SERVICE` binding. Supports static scope definitions or a dynamic
+ * resolver function that receives the Hono context.
+ *
+ * @requires `RBAC_SERVICE` binding.
+ * @requires `identity` context variable (set by the `jwt` middleware).
+ * @param accessRequests - Scope conditions to verify, or a function that returns them.
+ * @param options.errorMessage - Custom 403 error message.
+ * @param Can be disabled by setting `MIDDLEWARE_ACCESS_DISABLED` env var.
+ * @throws {HTTPException} 403 if the user does not have the required access.
+ */
 declare const access: <TScope extends string = string>(accessRequests: AccessRequestResolver<TScope>, options?: AccessMiddlewareOptions) => MiddlewareHandler;
 
+/**
+ * Middleware that authenticates requests using an admin API key.
+ *
+ * Expects a `Bearer <token>` in the `Authorization` header and validates it
+ * against the `GATEWAY_ADMIN_API_KEY` secret stored in the Secrets Store binding.
+ *
+ * @requires `SECRETS_STORE` binding with a `GATEWAY_ADMIN_API_KEY` secret provisioned.
+ * @throws {HTTPException} 401 if the token is missing or does not match.
+ */
 declare const adminAuth: MiddlewareHandler;
 
+/**
+ * Middleware that ensures request idempotency using Cloudflare KV.
+ *
+ * Expects an `x-idempotency-key` header. If the key already exists in KV,
+ * the request is rejected as a duplicate (409). Otherwise the key is stored
+ * with a 3-day TTL and the request proceeds. Sets `idempotency.key` in context.
+ *
+ * @requires `IDEMPOTENCY_KV` KV namespace binding.
+ * @param Can be disabled by setting `MIDDLEWARE_IDEMPOTENCY_DISABLED` env var.
+ * @throws {HTTPException} 401 if the `x-idempotency-key` header is missing.
+ * @throws {HTTPException} 409 if the idempotency key has already been used.
+ */
 declare const idempotency: () => MiddlewareHandler;
 
+/**
+ * Middleware that authenticates requests using a JWT access token.
+ *
+ * Extracts the Bearer token from the `Authorization` header, verifies it via
+ * the `AUTH_SERVICE` binding, and populates `identity` in the context with user
+ * details (id, email, role, organizationId, exchangeOfficeId).
+ *
+ * @requires `AUTH_SERVICE` binding.
+ * @param Can be disabled by setting `MIDDLEWARE_JWT_DISABLED` env var.
+ * @throws {HTTPException} 401 if the header is missing, not a Bearer scheme, or token is invalid.
+ * @throws {HTTPException} 422 if user metadata is missing organizationId/exchangeOfficeId.
+ */
 declare const jwt: () => MiddlewareHandler;
 
+/**
+ * Middleware that enforces IP-based access control per organization.
+ *
+ * Retrieves the caller's IP from request headers and checks it against
+ * the organization's authorized IP list via the `ORGANIZATION_SERVICE` binding.
+ *
+ * @requires `ORGANIZATION_SERVICE` binding.
+ * @requires `ENVIRONMENT` binding.
+ * @param Can be disabled by setting `MIDDLEWARE_IP_DISABLED` env var.
+ * @throws {HTTPException} 401 if the IP address cannot be determined or organization ID is missing.
+ * @throws {HTTPException} 404 if the organization is not found or the IP is not authorized.
+ */
 declare const ip: () => MiddlewareHandler;
 
+/**
+ * Middleware that logs incoming requests and outgoing responses.
+ *
+ * Logs request/response details to the console and optionally sends audit log
+ * entries to the `ACTIVITY_SERVICE` binding. Sets `auditLog.requestId` in context
+ * for correlating request/response audit log pairs.
+ *
+ * @requires `ACTIVITY_SERVICE` binding (when audit logging is enabled).
+ * @requires `ENVIRONMENT` binding.
+ * @param Can be disabled by setting `MIDDLEWARE_LOGGER_DISABLED` env var.
+ * @param Audit logging can be separately disabled via `MIDDLEWARE_LOGGER_AUDITLOG_DISABLED` env var.
+ */
 declare const logger: () => MiddlewareHandler;
 
+/**
+ * Middleware that verifies the request payload signature.
+ *
+ * Expects `x-signature` and `x-signature-key` headers. Looks up the corresponding
+ * public key from the organization's signature keys via the `ORGANIZATION_SERVICE` binding
+ * and verifies the payload against it.
+ *
+ * @requires `ORGANIZATION_SERVICE` binding.
+ * @requires `ENVIRONMENT` binding.
+ * @param Can be disabled by setting `MIDDLEWARE_SIGNATURE_DISABLED` env var.
+ * @throws {HTTPException} 401 if signature headers are missing or verification fails.
+ * @throws {HTTPException} 404 if the organization or signature key is not found.
+ */
 declare const signature: () => MiddlewareHandler;
 
 export { access, adminAuth, idempotency, ip, jwt, logger, signature };

package/dist/middlewares.d.ts

@@ -15,18 +15,102 @@ interface AccessMiddlewareOptions {
     errorMessage?: string;
 }
 type AccessRequestResolver<TScope extends string = string> = ScopeCondition<TScope> | ((context: Context) => ScopeCondition<TScope>);
+/**
+ * Middleware that enforces role-based access control (RBAC).
+ *
+ * Verifies the authenticated user has the required scopes/permissions by calling
+ * the `RBAC_SERVICE` binding. Supports static scope definitions or a dynamic
+ * resolver function that receives the Hono context.
+ *
+ * @requires `RBAC_SERVICE` binding.
+ * @requires `identity` context variable (set by the `jwt` middleware).
+ * @param accessRequests - Scope conditions to verify, or a function that returns them.
+ * @param options.errorMessage - Custom 403 error message.
+ * @param Can be disabled by setting `MIDDLEWARE_ACCESS_DISABLED` env var.
+ * @throws {HTTPException} 403 if the user does not have the required access.
+ */
 declare const access: <TScope extends string = string>(accessRequests: AccessRequestResolver<TScope>, options?: AccessMiddlewareOptions) => MiddlewareHandler;
 
+/**
+ * Middleware that authenticates requests using an admin API key.
+ *
+ * Expects a `Bearer <token>` in the `Authorization` header and validates it
+ * against the `GATEWAY_ADMIN_API_KEY` secret stored in the Secrets Store binding.
+ *
+ * @requires `SECRETS_STORE` binding with a `GATEWAY_ADMIN_API_KEY` secret provisioned.
+ * @throws {HTTPException} 401 if the token is missing or does not match.
+ */
 declare const adminAuth: MiddlewareHandler;
 
+/**
+ * Middleware that ensures request idempotency using Cloudflare KV.
+ *
+ * Expects an `x-idempotency-key` header. If the key already exists in KV,
+ * the request is rejected as a duplicate (409). Otherwise the key is stored
+ * with a 3-day TTL and the request proceeds. Sets `idempotency.key` in context.
+ *
+ * @requires `IDEMPOTENCY_KV` KV namespace binding.
+ * @param Can be disabled by setting `MIDDLEWARE_IDEMPOTENCY_DISABLED` env var.
+ * @throws {HTTPException} 401 if the `x-idempotency-key` header is missing.
+ * @throws {HTTPException} 409 if the idempotency key has already been used.
+ */
 declare const idempotency: () => MiddlewareHandler;
 
+/**
+ * Middleware that authenticates requests using a JWT access token.
+ *
+ * Extracts the Bearer token from the `Authorization` header, verifies it via
+ * the `AUTH_SERVICE` binding, and populates `identity` in the context with user
+ * details (id, email, role, organizationId, exchangeOfficeId).
+ *
+ * @requires `AUTH_SERVICE` binding.
+ * @param Can be disabled by setting `MIDDLEWARE_JWT_DISABLED` env var.
+ * @throws {HTTPException} 401 if the header is missing, not a Bearer scheme, or token is invalid.
+ * @throws {HTTPException} 422 if user metadata is missing organizationId/exchangeOfficeId.
+ */
 declare const jwt: () => MiddlewareHandler;
 
+/**
+ * Middleware that enforces IP-based access control per organization.
+ *
+ * Retrieves the caller's IP from request headers and checks it against
+ * the organization's authorized IP list via the `ORGANIZATION_SERVICE` binding.
+ *
+ * @requires `ORGANIZATION_SERVICE` binding.
+ * @requires `ENVIRONMENT` binding.
+ * @param Can be disabled by setting `MIDDLEWARE_IP_DISABLED` env var.
+ * @throws {HTTPException} 401 if the IP address cannot be determined or organization ID is missing.
+ * @throws {HTTPException} 404 if the organization is not found or the IP is not authorized.
+ */
 declare const ip: () => MiddlewareHandler;
 
+/**
+ * Middleware that logs incoming requests and outgoing responses.
+ *
+ * Logs request/response details to the console and optionally sends audit log
+ * entries to the `ACTIVITY_SERVICE` binding. Sets `auditLog.requestId` in context
+ * for correlating request/response audit log pairs.
+ *
+ * @requires `ACTIVITY_SERVICE` binding (when audit logging is enabled).
+ * @requires `ENVIRONMENT` binding.
+ * @param Can be disabled by setting `MIDDLEWARE_LOGGER_DISABLED` env var.
+ * @param Audit logging can be separately disabled via `MIDDLEWARE_LOGGER_AUDITLOG_DISABLED` env var.
+ */
 declare const logger: () => MiddlewareHandler;
 
+/**
+ * Middleware that verifies the request payload signature.
+ *
+ * Expects `x-signature` and `x-signature-key` headers. Looks up the corresponding
+ * public key from the organization's signature keys via the `ORGANIZATION_SERVICE` binding
+ * and verifies the payload against it.
+ *
+ * @requires `ORGANIZATION_SERVICE` binding.
+ * @requires `ENVIRONMENT` binding.
+ * @param Can be disabled by setting `MIDDLEWARE_SIGNATURE_DISABLED` env var.
+ * @throws {HTTPException} 401 if signature headers are missing or verification fails.
+ * @throws {HTTPException} 404 if the organization or signature key is not found.
+ */
 declare const signature: () => MiddlewareHandler;
 
 export { access, adminAuth, idempotency, ip, jwt, logger, signature };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@develit-io/backend-sdk",
-  "version": "9.11.12",
+  "version": "9.11.14",
   "description": "Develit Backend SDK",
   "author": "Develit.io",
   "license": "ISC",