Tamper-resistant native licensing validator for Lambda Kata Integration
npm install @lambda-kata/licensingA tamper-resistant native licensing validator for the Lambda Kata SST Integration workspace. This package provides enhanced security through a native C implementation that replaces the existing TypeScript-based licensing validation.
- Tamper-Resistant: Native C implementation prevents JavaScript-based tampering
- Fail-Closed Security: All error conditions result in denying access
- Hardened Network: Compile-time hardcoded endpoints with strict TLS validation
- AWS Lambda Compatible: Optimized for Amazon Linux 2023 (x64 and arm64)
- Drop-in Replacement: Compatible with existing LicensingService interface
``bash`
npm install @lambda-kata/licensing
`typescript
import { NativeLicensingService } from '@lambda-kata/licensing';
const service = new NativeLicensingService();
const result = await service.checkEntitlement('123456789012');
if (result.entitled) {
console.log(Layer ARN: ${result.layerArn});Not entitled: ${result.message}
} else {
console.log();`
}
`typescript
import { createLicensingService } from '@lambda-kata/licensing';
const service = createLicensingService();
const result = await service.checkEntitlement('123456789012');
`
The native validator is designed to be a drop-in replacement for the existing HTTP-based licensing service:
`typescript
// Before (HTTP-based)
import { HttpLicensingService } from '@lambda-kata/sst-v2';
// After (Native-based)
import { NativeLicensingService } from '@lambda-kata/licensing';
// Same interface, enhanced security
const service = new NativeLicensingService();
`
The validator implements a fail-closed security model where any error condition results in denying access:
- Network timeouts or connection failures
- TLS certificate validation failures
- Invalid response formats
- Native addon loading failures
- Invalid input parameters
- Compile-time endpoints: Network destinations cannot be modified at runtime
- No proxy support: Ignores proxy environment variables
- Strict TLS: Requires TLS 1.2+ with certificate validation
- No redirects: HTTP redirects are completely disabled
- Response authenticity: Verifies response signatures or certificate pinning
- Single function interface: Only checkEntitlement(accountId: string) is exposed
- Input validation: Account ID format validated in both JavaScript and native code
- No configuration: All security settings are compile-time constants
- Node.js 18+ with npm/yarn
- C compiler (gcc/clang)
- libcurl development headers
- OpenSSL development headers
- json-c development headers (Linux only)
`bashInstall dependencies
yarn install
$3
`bash
Build for all architectures
./scripts/build-docker.shBuild for specific architecture
./scripts/build-docker.sh x64
./scripts/build-docker.sh arm64
`The Docker build produces Lambda Layer packages ready for deployment.
Testing
`bash
Run all tests
yarn testRun tests with coverage
yarn test:coverageRun tests in watch mode
yarn test:watch
`$3
- Unit Tests: Specific examples and edge cases
- Property-Based Tests: Universal properties using fast-check
- Integration Tests: End-to-end validation with mock servers
- Security Tests: Tampering resistance and fail-closed behavior
API Reference
$3
####
checkEntitlement(accountId: string): PromiseValidates licensing entitlement for an AWS account.
Parameters:
-
accountId - 12-digit AWS account ID stringReturns:
-
Promise - Licensing validation resultExample:
`typescript
const result = await service.checkEntitlement('123456789012');
`$3
`typescript
interface LicensingResponse {
entitled: boolean; // Entitlement status
layerArn?: string; // Customer Lambda Layer ARN (if entitled)
message?: string; // Human-readable status message
expiresAt?: string; // ISO 8601 expiration timestamp
}
`Error Handling
The validator never throws exceptions. All errors result in a fail-closed response:
`typescript
{
entitled: false,
message: "Error description"
}
`Common error messages:
-
"Invalid account ID format" - Account ID is not a 12-digit string
- "Native validator unavailable" - Native addon failed to load
- "Network error" - Network communication failed
- "Security error" - TLS or authenticity verification failed
- "System error" - Unexpected system errorPerformance
- Validation time: < 5 seconds under normal conditions
- Memory usage: < 1MB heap usage
- Addon loading: < 100ms in Lambda environment
- Caching: 5-minute TTL for successful responses
- Connection reuse: HTTP connections are pooled and reused
Deployment
$3
The package includes pre-built Lambda Layer packages for both x64 and arm64 architectures:
`bash
Extract from build artifacts
unzip build/native-licensing-validator-amd64.zip -d layer/
`Layer structure:
`
nodejs/
└── node_modules/
└── @lambda-kata/
└── native-licensing-validator/
├── build/Release/lambda_kata_licensing.node
├── out/dist/index.js
└── package.json
`$3
The package includes prebuilt binaries for supported platforms:
`json
{
"binary": {
"napi_versions": [8, 9]
}
}
`Documentation
Comprehensive documentation is available in the docs/ directory:
$3
- API Reference - Complete API documentation and usage examples
- Build Instructions - Build procedures for all architectures
- Deployment Guide - Lambda Layer deployment procedures
- Migration Guide - Migration from TypeScript implementation
- Troubleshooting - Common issues and solutions
- Security Model - Threat model and security considerations
- Performance Benchmarks - Performance analysis and optimization$3
| Document | Purpose | Audience |
|----------|---------|----------|
| API Reference | Complete API documentation | Developers |
| Build Instructions | Build procedures and requirements | Build Engineers |
| Deployment Guide | Lambda Layer deployment | DevOps Engineers |
| Migration Guide | TypeScript to Native migration | Developers |
| Troubleshooting | Issue diagnosis and resolution | All Users |
| Security Model | Security architecture and threats | Security Teams |
| Performance | Benchmarks and optimization | Performance Engineers |
Quick Troubleshooting
$3
Native Addon Loading Fails:
`typescript
// Check if addon loaded successfully
const service = new NativeLicensingService();
const result = await service.checkEntitlement('123456789012');if (result.message === 'Native validator unavailable') {
console.warn('Native addon not available, using fail-closed fallback');
}
``Build Issues:
- Missing dependencies → Install libcurl-devel, openssl-devel
- Architecture mismatch → Use Docker build for Lambda compatibility
- Node.js version → Ensure Node.js 18+ is installed
For detailed troubleshooting, see Troubleshooting Guide.
The validator implements defense-in-depth security:
- Tamper Resistance: Core logic in compiled native code
- Network Security: Hardcoded endpoints, strict TLS, certificate pinning
- Fail-Closed Design: All errors result in denial of access
- Environment Isolation: Ignores proxy and environment variables
For complete security analysis, see Security Considerations.
MIT License - see LICENSE file for details.
1. Fork the repository
2. Create a feature branch
3. Make changes with tests
4. Run the full test suite
5. Submit a pull request
All contributions must maintain the security properties and fail-closed behavior of the validator.
For issues and questions:
1. Check the troubleshooting guide
2. Review existing GitHub issues
3. Create a new issue with detailed reproduction steps
Security issues should be reported privately to the maintainers.