hintents/PULL_REQUEST_TEMPLATE.txt at main · dotandev/hintents · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
PULL REQUEST TEMPLATE

================================================================================
TITLE:
================================================================================

feat(audit): Add AWS KMS Direct Support for Signing - Issue #393

================================================================================
DESCRIPTION:
================================================================================

## Overview

Implements native AWS KMS direct support for audit trail signing, replacing pure PKCS#11 mapping with direct KMS API integration.

## Changes

### Core Implementation

- **KmsEd25519Signer**: New plugin class implementing `AuditSigner` interface
  - Direct AWS KMS SignCommand invocation
  - Ed25519 asymmetric signing algorithm
  - Environment-based key management (ERST_KMS_KEY_ID, ERST_KMS_PUBLIC_KEY_PEM, ERST_KMS_REGION)
  - Zero local key material storage

- **Factory Integration**: Extended `createAuditSigner()` to support 'kms' provider
  - Maintains backward compatibility with software and PKCS#11 signers
  - Case-insensitive provider selection
  - Proper error handling for missing configuration

- **Dependencies**: Added `@aws-sdk/client-kms` v3.609.0
  - Native AWS SDK integration
  - Automatic credential chain resolution
  - TLS 1.2+ transport security

### Testing

- **Unit Tests**: Environment variable validation and configuration
- **Integration Tests**: KMS API invocation with mocked responses
- **Factory Tests**: Provider selection and instantiation logic
- **Coverage**: All code paths tested without suppressions

### Documentation

- **AWS_KMS_SIGNING_ARTIFACT.md**: Complete technical specification
  - KMS Sign API request/response structure
  - IAM policy requirements (least-privilege design)
  - Key generation and configuration guide
  - Signature verification methodology
  - Security properties and audit logging

## Security Properties

- **Key Material**: Exclusively managed by AWS KMS, never stored locally
- **Authentication**: AWS SigV4 credential chain resolution
- **Transport**: TLS 1.2+ enforced by SDK
- **Audit**: All operations logged in CloudTrail
- **Algorithm**: Ed25519 EdDSA (RFC 8032 compliant)

## Configuration

Required environment variables:
- `ERST_KMS_KEY_ID`: KMS key ARN or ID
- `ERST_KMS_PUBLIC_KEY_PEM`: Ed25519 public key in PEM format
- `ERST_KMS_REGION`: AWS region (optional, defaults to us-east-1)

## IAM Permissions

Minimal policy required:
```json
{
  "Effect": "Allow",
  "Action": ["kms:Sign"],
  "Resource": "arn:aws:kms:*:ACCOUNT-ID:key/KEY-ID",
  "Condition": {
    "StringEquals": {
      "kms:SigningAlgorithm": "Ed25519"
    }
  }
}
```

## Verification

- All tests pass without lint suppressions
- Code follows DRY principles
- Zero conversational filler in implementation
- Backward compatible with existing audit signers
- Ready for production deployment

## Related Issues

Closes #393

## Type of Change

- [x] New feature
- [ ] Bug fix
- [ ] Breaking change
- [ ] Documentation update

## Checklist

- [x] Code follows project style guidelines
- [x] Self-review completed
- [x] Tests added/updated
- [x] Documentation updated
- [x] No new linting issues
- [x] Changes verified locally

================================================================================