{"id":48033,"library":"grpc-hmac-interceptor","title":"grpc-hmac-interceptor","description":"Node.js library (v1.0.4) for adding HMAC authentication to gRPC applications via interceptors. Works with @grpc/grpc-js, supporting both @grpc/proto-loader and protoc-generated protos. Uses SHA512-256 HMAC with key ID and signature in metadata headers. Lightweight, TypeScript-first, and integrates as a gRPC interceptor without modifying service logic.","status":"active","version":"1.0.4","language":"javascript","source_language":"en","source_url":"https://github.com/travix/ts-grpc-hmac","tags":["javascript","grpc","node","interceptor"],"install":[{"cmd":"npm install grpc-hmac-interceptor","lang":"bash","label":"npm"},{"cmd":"yarn add grpc-hmac-interceptor","lang":"bash","label":"yarn"},{"cmd":"pnpm add grpc-hmac-interceptor","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency; library builds on gRPC interceptor API","package":"@grpc/grpc-js","optional":false}],"imports":[{"note":"Library is ESM-only; CommonJS require not supported. TypeScript types included.","wrong":"const NewServerInterceptor = require('grpc-hmac-interceptor').NewServerInterceptor","symbol":"NewServerInterceptor","correct":"import { NewServerInterceptor } from 'grpc-hmac-interceptor'"},{"note":"Named export, not default. Second argument is secretKey string, third optional boolean for protoc.","wrong":"import NewClientInterceptor from 'grpc-hmac-interceptor'","symbol":"NewClientInterceptor","correct":"import { NewClientInterceptor } from 'grpc-hmac-interceptor'"},{"note":"Type export; version ≥1.0.0 includes type definitions.","wrong":"import { GetSecret } from 'grpc-hmac-interceptor/dist/interceptor'","symbol":"GetSecret","correct":"import { GetSecret } from 'grpc-hmac-interceptor'"}],"quickstart":{"code":"import { NewServerInterceptor, NewClientInterceptor, GetSecret } from 'grpc-hmac-interceptor';\nimport { Server, ServerCredentials, credentials } from '@grpc/grpc-js';\n\n// Server side\nconst getSecret: GetSecret = (keyId: string) => {\n  const secrets: Record<string, string> = {\n    'user1': 'my-secret-key-123',\n  };\n  if (!secrets[keyId]) throw new Error(`Unknown keyId: ${keyId}`);\n  return secrets[keyId];\n};\nconst serverInterceptor = NewServerInterceptor(getSecret);\nconst server = new Server({ interceptors: [serverInterceptor.WithInterceptor()] });\nserver.bindAsync('0.0.0.0:50051', ServerCredentials.createInsecure(), () => {\n  server.start();\n});\n\n// Client side\nconst keyId = 'user1';\nconst secretKey = 'my-secret-key-123';\nconst clientInterceptor = NewClientInterceptor(keyId, secretKey);\nconst client = new SomeServiceClient('localhost:50051', credentials.createInsecure(), {\n  interceptors: [clientInterceptor.WithInterceptor()],\n});","lang":"typescript","description":"Sets up gRPC server and client with HMAC authentication interceptors using grpc-hmac-interceptor."},"warnings":[{"fix":"NewClientInterceptor(keyId, secretKey, true) when using protoc","message":"If using protoc-generated protos, pass true as third argument to NewClientInterceptor to handle jspb.Message wrapping.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Use import syntax in an ESM project or enable ESM via 'type': 'module' in package.json","message":"Library is ESM-only since v1.0.0; does not support CommonJS require().","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Use GetSecret callback instead of hardcoded key lookup","message":"Using strings for key/ID is deprecated; prefer typed GetSecret function.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Add server interceptor on server, client interceptor on each client call","message":"Interceptor order matters: must be added to both server and client to avoid mismatched HMACs.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"search_vec":"'-256':30 'ad':9 'applic':14 'authent':11 'first':43 'generat':26 'grpc':2,13,48,55 'grpc-hmac-interceptor':1 'grpc/grpc-js':19 'grpc/proto-loader':22 'header':39 'hmac':3,10,31 'id':34 'integr':45 'interceptor':4,16,49,57 'javascript':54 'key':33 'librari':6 'lightweight':40 'logic':53 'metadata':38 'modifi':51 'node':56 'node.js':5 'proto':27 'protoc':25 'protoc-gener':24 'servic':52 'sha512':29 'signatur':36 'support':20 'typescript':42 'typescript-first':41 'use':28 'v1.0.4':7 'via':15 'without':50 'work':17","created_at":"2026-06-07T16:54:35.371186+00:00","updated_at":"2026-06-07T16:54:35.371186+00:00","problems":[{"fix":"npm install grpc-hmac-interceptor --save","cause":"Package not installed or in devDependencies only.","error":"Error: Cannot find module 'grpc-hmac-interceptor'"},{"fix":"import { NewClientInterceptor } from 'grpc-hmac-interceptor'","cause":"Using default import instead of named import.","error":"TypeError: NewClientInterceptor is not a function"},{"fix":"Ensure GetSecret returns correct secret or handle missing keys","cause":"GetSecret callback not returning a secret for given keyId.","error":"Error: Unknown keyId: undefined"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":"https://github.com/travix/ts-grpc-hmac#readme","github":"https://github.com/travix/ts-grpc-hmac","docs":null,"changelog":null,"pypi":null,"npm":"grpc-hmac-interceptor","openapi_spec":null,"status_page":null,"smithery":null,"categories":["security"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}