Imported from bedkillerspacex-boop/codex-skill-library (typescript-hsm-notes/SKILL.md). Install upstream with npx skills add bedkillerspacex-boop/codex-skill-library --skill typescript-hsm-notes. Copyright stays with the author.

TypeScript HSM Integration Notes

Scope And Authorization

• In scope: systems, clusters, repos, and apps you own or have written authorization to assess/change.
• Out of scope: unauthorized scanning, exploitation, credential abuse, or third-party harm.
• Prefer non-production validation; use change windows for production.
• Redact secrets, tokens, personal data, and customer identifiers from notes and tickets.
• Prefer cloud KMS/HSM APIs over shipping soft keys; dual-control for key admin.
• Pair implementation changes with code-quality-standards.

When To Use

• Signing JWTs, code, or documents with HSM-backed keys from Node/TS.
• Migrating PEM private keys out of app config into KMS/HSM.
• Writing ADRs for key classes (app DEK, TLS, code signing).
• Auditing who can use vs manage keys.

Do Not Use As Primary

Domain Focus

Workflow

1. Classify keys

1. List signing vs encryption vs TLS keys and owners.
2. Decide HSM-required vs software KMS acceptable.

2. Design use path

1. App authenticates to KMS via IRSA/Workload Identity — no static cloud keys if possible.
2. Algorithms: prefer modern (RSA-PSS/ECDSA P-256/Ed25519 per policy).
3. Cache public keys only; never log signatures with sensitive payloads unnecessarily.

3. Implement TypeScript client

1. Thin wrapper with timeouts, retries, metrics.
2. Unit tests with local mock; integration tests in lab account.
3. Fail closed if KMS unavailable for security-critical paths.

4. Operate

1. Rotation runbook; dual control for destroy.
2. Inventory key aliases and grants quarterly.

Verify with evidence

# Example: AWS KMS sign (owned account, redacted)
aws kms list-keys --region us-east-1 | head
# aws kms sign --key-id alias/ts-api --message fileb://msg.bin --signing-algorithm RSASSA_PSS_SHA_256
pnpm tsc --noEmit
pnpm vitest run tests/crypto
# Ensure no PEM private keys committed
rg -n "BEGIN (RSA |EC |OPENSSH )?PRIVATE KEY" . || true

1. Keep command output redacted (keys, tokens, customer IDs, kubeconfigs).
2. Attach before/after evidence to the change or ticket.
3. Prefer automated tests or CI gates where regressions are likely.

Good / Bad

Key note template

Output Checklist

• Key inventory and classification
• HSM/KMS key policies reviewed
• TS client uses workload identity
• No private PEM in repo
• Rotation and break-glass documented
• Audit log review path defined
• code-quality-standards applied if code/config shipped
• Residual risk and next review date noted

Rules

• Never paste key material into tickets.
• Notes must match actual key policy, not aspirational.
• Authorized crypto accounts only.
• Authorized/owned/lab scope only; evidence over guesses.
• Never paste live secrets, private keys, or customer PII into notes or chat.
• Keep this skill focused on typescript-hsm-notes; route neighbors via the catalog/index.