Project Overview

@praveentcom/siwa-client-secret is a lightweight npm package that simplifies the process of generating client secrets for Sign in with Apple (SIWA) integrations. It provides a clean, type-safe API for creating signed JWTs required by Apple's authentication system, addressing security vulnerabilities in existing solutions while maintaining backward compatibility.

Key Features

• JWT Generation - Lightweight library that produces signed JSON Web Tokens using essential configuration parameters
• Security Focused - Leveraged jsonwebtoken package from Auth0 to ensure reliable JWT signing compliant with Apple's specifications
• TypeScript Support - Integrated TypeScript type declarations for enhanced code maintainability and type safety
• Easy Distribution - Published on npm under MIT license with simple installation via npm or yarn

Technical Implementation

JWT Signing

Apple Authentication Compliance

Implemented JWT generation following Apple's strict requirements:

• ES256 Algorithm: Uses Elliptic Curve Digital Signature Algorithm
• Required Claims: Includes all mandatory JWT claims (iss, iat, exp, aud, sub)
• Key Format: Supports PEM-encoded private keys
• Expiration: Configurable token expiration (max 6 months)

JWT structure:

{
  iss: teamId,           // Apple Team ID
  iat: issuedAt,         // Issued at timestamp
  exp: expiration,       // Expiration timestamp
  aud: 'https://appleid.apple.com',
  sub: bundleId          // App Bundle ID
}

Configuration Parameters

Simple API requiring minimal configuration:

• Key ID: The 10-character Key ID from Apple Developer
• Team ID: Your Apple Developer Team ID
• Bundle ID: Your app's bundle identifier
• Private Key: P8 private key in PEM format
• Expiration (optional): Token validity period

Security Improvements

Vulnerability Fixes

Addressed security issues in forked repository:

• Dependency Updates: Updated all dependencies to latest secure versions
• Security Audit: Fixed npm audit vulnerabilities
• Key Validation: Added validation for key format and structure
• Error Handling: Comprehensive error handling for security issues

Security enhancements:

• Secure key storage recommendations
• Input validation and sanitization
• Clear error messages for troubleshooting
• No logging of sensitive information

TypeScript Integration

Type Safety

Complete TypeScript support:

• Type Definitions: Full type definitions included
• Interface Definitions: Clear interfaces for configuration
• Type Inference: Automatic type inference for results
• JSDoc Comments: Detailed documentation in types

TypeScript interface:

interface SIWAConfig {
  keyId: string;
  teamId: string;
  bundleId: string;
  privateKey: string;
  expiration?: number;
}
 
function generateClientSecret(config: SIWAConfig): string;

Package Management

NPM Publishing

Professional npm package management:

• Semantic Versioning: Follows semver standards
• Package.json: Complete package metadata
• README: Comprehensive usage documentation
• MIT License: Permissive open-source license

Package features:

• Small Bundle: Minimal dependencies for small package size
• Tree Shakeable: ES modules support
• Node.js Support: Works with Node.js 12+
• CI/CD: Automated testing and publishing

Technologies Used

Core Libraries

• jsonwebtoken: JWT signing from Auth0
• Node.js: Runtime environment
• TypeScript: Type-safe development
• ES6+: Modern JavaScript features

Development Tools

• npm: Package management and distribution
• TypeScript Compiler: Type checking and compilation
• ESLint: Code quality
• Prettier: Code formatting

Testing & Quality

• Jest: Unit testing framework
• npm audit: Security vulnerability scanning
• GitHub Actions: CI/CD pipeline
• Semantic Release: Automated version management

Usage & API

Simple API

Straightforward usage:

import { generateClientSecret } from '@praveentcom/siwa-client-secret';
 
const clientSecret = generateClientSecret({
  keyId: 'ABC123XYZ',
  teamId: 'DEF456ABC',
  bundleId: 'com.example.app',
  privateKey: '-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----',
  expiration: 86400 * 180 // 180 days
});

Integration Examples

Common integration patterns:

• Express.js: Middleware for authentication
• Next.js: API routes for SIWA
• Serverless: AWS Lambda functions
• Mobile Backends: iOS/Android app backends

Implementation Guide

Apple Developer Setup

Prerequisites:

1. Apple Developer Account: Active developer account
2. App ID: Register your app bundle ID
3. Service ID: Create a Service ID for web auth
4. Key Generation: Generate a new key with SIWA enabled
5. Key Download: Download the P8 private key

Integration Steps

Step-by-step integration:

1. Install the package: npm install @praveentcom/siwa-client-secret
2. Configure Apple Developer portal
3. Store credentials securely (environment variables)
4. Generate client secret in authentication flow
5. Exchange authorization code for tokens
6. Verify and validate tokens

Security Best Practices

Recommendations for secure usage:

• Environment Variables: Never hardcode credentials
• Key Storage: Use secure key management systems
• Rotation: Regularly rotate keys and tokens
• Validation: Always validate tokens before use
• HTTPS: Only use over secure connections

Impact & Results

npm Statistics

• Downloads: Regular downloads from npm registry
• Dependents: Used by various projects
• Stars: GitHub repository stars
• Issues: Active issue tracking and resolution

Community Feedback

• Simplified SIWA integration for developers
• Appreciated TypeScript support
• Valued security improvements
• Requested feature additions implemented

Technical Success

• Zero Security Issues: No reported vulnerabilities
• Compatibility: Works across Node.js versions
• Reliability: Stable API with no breaking changes
• Performance: Minimal overhead for JWT generation

Comparison with Alternatives

Advantages

Why choose this package:

• Security: Latest dependencies with no vulnerabilities
• TypeScript: Full TypeScript support included
• Maintained: Active maintenance and updates
• Documentation: Clear, comprehensive documentation
• Lightweight: Minimal dependencies

Use Cases

Perfect for:

• iOS Apps: Backend for iOS Sign in with Apple
• Web Applications: Web-based SIWA integration
• Hybrid Apps: React Native, Flutter backends
• API Services: RESTful APIs with SIWA
• Microservices: Authentication microservices

Future Enhancements

Planned Features

• Key Caching: Cache generated secrets for reuse
• Automatic Rotation: Auto-rotate expiring tokens
• Validation Helpers: Helper functions for token validation
• CLI Tool: Command-line tool for testing
• More Examples: Additional integration examples

Community Contributions

Open to contributions:

• Pull Requests: Welcome improvements
• Issue Reports: Bug reports and feature requests
• Documentation: Help improve docs
• Examples: Share integration examples

Open Source

Fully open-source project:

• GitHub: https://github.com/praveentcom/siwa-client-secret
• npm: https://www.npmjs.com/package/@praveentcom/siwa-client-secret
• MIT License: Free for all use cases
• Contributions: Community contributions welcome

Development Story

Origin

Forked from existing repository to:

• Address security vulnerabilities
• Add TypeScript support
• Improve documentation
• Maintain compatibility

Maintenance

Ongoing maintenance includes:

• Regular dependency updates
• Security patches
• Bug fixes
• Feature enhancements
• Community support

Documentation

Comprehensive documentation:

• README: Detailed usage guide
• API Reference: Complete API documentation
• Examples: Working code examples
• Troubleshooting: Common issues and solutions
• Migration Guide: Upgrade instructions

This package demonstrates the importance of maintaining secure, well-documented open-source libraries for common authentication needs, making Sign in with Apple integration accessible to developers while maintaining high security standards.