@fonoster/authz 0.27.0 → 0.31.0

package/dist/client/AuthzClient.d.ts

@@ -1,4 +1,4 @@
-import { AddBillingMeterEventRequest, CheckMethodAuthorizedRequest, VoiceRequest } from "../types";
+import { AddBillingMeterEventRequest, CheckMethodAuthorizedRequest, SessionDecision, VoiceRequest } from "../types";
 /**
  * AuthzClient class to interact with the AuthzServer via gRPC.
  */
@@ -15,6 +15,12 @@ export declare class AuthzClient {
      * @returns Promise resolving to a boolean indicating authorization.
      */
     checkSessionAuthorized(request: Partial<VoiceRequest>): Promise<boolean>;
+    /**
+     * Asks whether a session may start; a refusal names its reason (add-billing-service D7).
+     * @param request VoiceRequest containing session details.
+     * @param deadlineMs How long to wait for the answer before failing.
+     */
+    checkSession(request: Partial<VoiceRequest>, deadlineMs?: number): Promise<SessionDecision>;
     /**
      * Checks if a specific method is authorized.
      * @param request CheckMethodAuthorizedRequest containing accessKeyId and method.

package/dist/client/AuthzClient.js

@@ -85,6 +85,36 @@ class AuthzClient {
             });
         });
     }
+    /**
+     * Asks whether a session may start; a refusal names its reason (add-billing-service D7).
+     * @param request VoiceRequest containing session details.
+     * @param deadlineMs How long to wait for the answer before failing.
+     */
+    async checkSession(request, deadlineMs) {
+        const options = deadlineMs
+            ? { deadline: new Date(Date.now() + deadlineMs) }
+            : {};
+        return new Promise((resolve, reject) => {
+            this.client.checkSessionAuthorized(request, options, (error, response) => {
+                if (error) {
+                    reject(new Error(`checkSession failed: ${error.message || error}`));
+                }
+                else if (response && typeof response.authorized === "boolean") {
+                    resolve(response.authorized
+                        ? { authorized: true }
+                        : {
+                            authorized: false,
+                            ...(response.reason
+                                ? { reason: response.reason }
+                                : {})
+                        });
+                }
+                else {
+                    reject(new Error("checkSession failed: Invalid response format."));
+                }
+            });
+        });
+    }
     /**
      * Checks if a specific method is authorized.
      * @param request CheckMethodAuthorizedRequest containing accessKeyId and method.

package/dist/client/AuthzServiceClient.d.ts

@@ -25,6 +25,11 @@ import { AddBillingMeterEventRequest, CheckMethodAuthorizedRequest, VoiceRequest
 interface AuthzServiceClient extends grpc.Client {
     checkSessionAuthorized(request: Partial<VoiceRequest>, callback: grpc.requestCallback<{
         authorized: boolean;
+        reason?: string;
+    }>): void;
+    checkSessionAuthorized(request: Partial<VoiceRequest>, options: Partial<grpc.CallOptions>, callback: grpc.requestCallback<{
+        authorized: boolean;
+        reason?: string;
     }>): void;
     checkMethodAuthorized(request: CheckMethodAuthorizedRequest, callback: grpc.requestCallback<{
         authorized: boolean;

package/dist/server/AuthzServer.d.ts

@@ -1,7 +1,11 @@
 import { AuthzHandler, ServerConfig } from "../types";
 declare class AuthzServer {
     config: ServerConfig;
+    private server?;
     constructor(config?: ServerConfig);
-    listen(handler: AuthzHandler): Promise<void>;
+    /** Serves the handler; resolves with the bound port (undefined if binding failed). */
+    listen(handler: AuthzHandler): Promise<number | undefined>;
+    /** Stops serving at once. */
+    close(): void;
 }
 export { AuthzServer };

package/dist/server/AuthzServer.js

@@ -68,17 +68,25 @@ class AuthzServer {
     constructor(config = defaultServerConfig_1.defaultServerConfig) {
         this.config = (0, deepmerge_1.default)(defaultServerConfig_1.defaultServerConfig, config);
     }
+    /** Serves the handler; resolves with the bound port (undefined if binding failed). */
     async listen(handler) {
         try {
             const healthImpl = new grpc_health_check_1.HealthImplementation(common_1.statusMap);
             const credentials = await (0, common_1.getServerCredentials)({});
             const server = new grpc.Server();
+            this.server = server;
             server.addService(serviceDefinition_1.serviceDefinition, {
                 checkSessionAuthorized: async (call, callback) => {
-                    logger.verbose("checkSessionAuthorized called", call.request);
+                    // Not the request itself: it carries the caller's token (M11).
+                    logger.verbose("checkSessionAuthorized called", {
+                        accessKeyId: call.request?.accessKeyId ?? call.request?.access_key_id,
+                        appRef: call.request?.appRef ?? call.request?.app_ref
+                    });
                     try {
-                        const authorized = await handler.checkSessionAuthorized(call.request);
-                        callback(null, { authorized });
+                        const decision = await handler.checkSessionAuthorized(call.request);
+                        callback(null, typeof decision === "boolean"
+                            ? { authorized: decision }
+                            : { authorized: decision.authorized, reason: decision.reason });
                     }
                     catch (error) {
                         logger.error("error in checkSessionAuthorized:", error);
@@ -89,7 +97,11 @@ class AuthzServer {
                     }
                 },
                 checkMethodAuthorized: async (call, callback) => {
-                    logger.verbose("checkMethodAuthorized called", call.request);
+                    // Not the request itself: it carries the caller's token (M11).
+                    logger.verbose("checkMethodAuthorized called", {
+                        accessKeyId: call.request?.accessKeyId,
+                        method: call.request?.method
+                    });
                     try {
                         const authorized = await handler.checkMethodAuthorized(call.request);
                         callback(null, { authorized });
@@ -103,7 +115,9 @@ class AuthzServer {
                     }
                 },
                 addBillingMeterEvent: async (call, callback) => {
-                    logger.verbose("addBillingMeterEvent called", call.request);
+                    logger.verbose("addBillingMeterEvent called", {
+                        accessKeyId: call.request?.accessKeyId
+                    });
                     try {
                         const request = {
                             accessKeyId: call.request.accessKeyId,
@@ -123,18 +137,24 @@ class AuthzServer {
             });
             healthImpl.addToServer(server);
             const bindAddr = `${this.config.bind}:${this.config.port}`;
-            server.bindAsync(bindAddr, credentials, async (err, port) => {
+            return await new Promise((resolve) => server.bindAsync(bindAddr, credentials, async (err, port) => {
                 if (err) {
                     logger.error("Failed to bind server:", err);
-                    return;
+                    return resolve(undefined);
                 }
                 healthImpl.setStatus("", common_1.GRPC_SERVING_STATUS);
                 logger.info(`Authz server started at ${this.config.bind}:${port}`);
-            });
+                resolve(port);
+            }));
         }
         catch (err) {
             logger.error("Error starting AuthzServer:", err);
+            return undefined;
         }
     }
+    /** Stops serving at once. */
+    close() {
+        this.server?.forceShutdown();
+    }
 }
 exports.AuthzServer = AuthzServer;

package/dist/server/DummyAuthzHandler.d.ts

@@ -1,6 +1,6 @@
-import { AddBillingMeterEventRequest, AuthzHandler, CheckMethodAuthorizedRequest, VoiceRequest } from "../types";
+import { AddBillingMeterEventRequest, AuthzHandler, CheckMethodAuthorizedRequest, SessionDecision, VoiceRequest } from "../types";
 declare class DummyAuthzHandler implements AuthzHandler {
-    checkSessionAuthorized(request: VoiceRequest): Promise<boolean>;
+    checkSessionAuthorized(request: VoiceRequest): Promise<SessionDecision>;
     checkMethodAuthorized(request: CheckMethodAuthorizedRequest): Promise<boolean>;
     addBillingMeterEvent(request: AddBillingMeterEventRequest): Promise<void>;
 }

package/dist/server/DummyAuthzHandler.js

@@ -24,7 +24,7 @@ const logger = (0, logger_1.getLogger)({ service: "authz", filePath: __filename
 class DummyAuthzHandler {
     async checkSessionAuthorized(request) {
         logger.verbose("checkSessionAuthorized called", request);
-        return true;
+        return { authorized: true };
     }
     async checkMethodAuthorized(request) {
         logger.verbose("checkMethodAuthorized called", request);

package/dist/types.d.ts

@@ -16,7 +16,20 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { VoiceRequest } from "@fonoster/common";
+/** The call a session would serve (CheckSessionAuthorizedRequest in authz.proto). */
+type VoiceRequest = {
+    appRef: string;
+    accessKeyId: string;
+    endpoint: string;
+    ingressNumber: string;
+    callerName: string;
+    callerNumber: string;
+    mediaSessionRef: string;
+    callRef: string;
+    sessionToken: string;
+    callDirection: "FROM_PSTN" | "TO_PSTN" | "INTRA_NETWORK";
+    metadata?: Record<string, string>;
+};
 type ServerConfig = {
     bind?: string;
     port?: number;
@@ -29,9 +42,17 @@ type AddBillingMeterEventRequest = {
     accessKeyId: string;
     payload: Record<string, unknown>;
 };
+/** Why a session was refused (add-billing-service D7; trial_ended: a Trial past its 30 days). */
+type SessionRefusal = "insufficient_balance" | "concurrency_limit" | "trial_ended";
+/** A session admission answer: a refusal names its reason. */
+type SessionDecision = {
+    authorized: boolean;
+    reason?: SessionRefusal;
+};
 type AuthzHandler = {
-    checkSessionAuthorized(request: VoiceRequest): Promise<boolean>;
+    /** A plain boolean is still accepted from handlers written before reasons existed. */
+    checkSessionAuthorized(request: VoiceRequest): Promise<boolean | SessionDecision>;
     checkMethodAuthorized(request: CheckMethodAuthorizedRequest): Promise<boolean>;
     addBillingMeterEvent(request: AddBillingMeterEventRequest): Promise<void>;
 };
-export { ServerConfig, AuthzHandler, VoiceRequest, CheckMethodAuthorizedRequest, AddBillingMeterEventRequest };
+export { ServerConfig, AuthzHandler, SessionDecision, SessionRefusal, VoiceRequest, CheckMethodAuthorizedRequest, AddBillingMeterEventRequest };

package/dist/types.js

@@ -1,2 +1,20 @@
 "use strict";
+/**
+ * Copyright (C) 2025 by Fonoster Inc (https://fonoster.com)
+ * http://github.com/fonoster/fonoster
+ *
+ * This file is part of Fonoster
+ *
+ * Licensed under the MIT License (the "License");
+ * you may not use this file except in compliance with
+ * the License. You may obtain a copy of the License at
+ *
+ *    https://opensource.org/licenses/MIT
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
 Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fonoster/authz",
-  "version": "0.27.0",
+  "version": "0.31.0",
   "description": "Authorization module for Fonoster",
   "author": "Pedro Sanders <psanders@fonoster.com>",
   "homepage": "https://github.com/fonoster/fonoster#readme",
@@ -14,8 +14,7 @@
   "scripts": {
     "prebuild": "rimraf ./dist tsconfig.tsbuildinfo",
     "build": "tsc -b tsconfig.json",
-    "clean": "rimraf ./dist node_modules tsconfig.tsbuildinfo",
-    "start:dev": "nodemon --exec tsx --watch src src/server/server.ts"
+    "dev": "nodemon --exec tsx --watch src src/server/server.ts"
   },
   "files": [
     "dist"
@@ -24,10 +23,10 @@
     "access": "public"
   },
   "dependencies": {
-    "@fonoster/common": "^0.27.0",
-    "@fonoster/identity": "^0.27.0",
-    "@fonoster/logger": "^0.27.0",
-    "@grpc/grpc-js": "~1.10.6",
+    "@fonoster/common": "^0.31.0",
+    "@fonoster/identity": "^0.31.0",
+    "@fonoster/logger": "^0.31.0",
+    "@grpc/grpc-js": "~1.14.6",
     "deepmerge": "^4.3.1",
     "grpc-health-check": "^2.0.2"
   },
@@ -38,5 +37,5 @@
   "bugs": {
     "url": "https://github.com/fonoster/fonoster/issues"
   },
-  "gitHead": "1191b34677b51a36000177887ff82303ef2693e1"
+  "gitHead": "f0a5102dddeea0f70f659234108805bc10690f2e"
 }