docs: implement Phase 2 - API documentation with TypeDoc

Set up TypeDoc to auto-generate comprehensive API reference documentation from TypeScript source code. Changes: - Installed typedoc and typedoc-plugin-markdown (v0.2.0 plugins) - Created typedoc.json configuration with 9 entry points - Added docs:api and docs:watch npm scripts - Fixed test file imports (validateNamespace → isValidNamespace) - Updated tsconfig.json to exclude test files from compilation - Generated markdown API documentation in docs/api-reference/generated/ Generated API documentation: - 9 modules documented (lib/, hooks/, types/) - lib/crypto - 14 encryption/certificate functions - lib/controller - 5 Kubernetes API functions - lib/validators - 6 validation functions - lib/retry - Exponential backoff utilities - lib/rbac - RBAC permission checking - types - Result types, branded types, interfaces - hooks/useSealedSecretEncryption - Encryption React hook - hooks/usePermissions - RBAC React hooks - hooks/useControllerHealth - Health monitoring hook Benefits: - Auto-generated from TypeScript source (stays in sync) - Markdown format for easy integration - Type signatures and JSDoc included - Function parameters and return types documented - Links between related types and functions Phase 2 deliverables (2-3 days estimated, completed in 1 session): ✅ TypeDoc installed and configured ✅ Entry points identified for all core modules ✅ API documentation generated (9 modules, 40+ functions) ✅ npm scripts added for docs generation ✅ Test files excluded from documentation Next: Phase 3 - User tutorials and guides Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
2026-02-11 23:27:18 -05:00
parent bdf19cd3bf
commit ebbdb42c05
98 changed files with 2951 additions and 5702 deletions
@@ -0,0 +1,51 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/crypto](../README.md) / encryptKeyValues
+
+# Function: encryptKeyValues()
+
+> **encryptKeyValues**(`publicKey`, `keyValues`, `namespace`, `name`, `scope`): [`Result`](../../../types/type-aliases/Result.md)\<`Record`\<`string`, [`Base64String`](../../../types/type-aliases/Base64String.md)\>, `string`\>
+
+Defined in: [src/lib/crypto.ts:126](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/crypto.ts#L126)
+
+Encrypt multiple key-value pairs for a SealedSecret
+
+## Parameters
+
+### publicKey
+
+`PublicKey`
+
+RSA public key from the controller's certificate
+
+### keyValues
+
+`object`[]
+
+Array of {key, value} pairs to encrypt (values are branded plaintext)
+
+### namespace
+
+`string`
+
+The namespace
+
+### name
+
+`string`
+
+The secret name
+
+### scope
+
+[`SealedSecretScope`](../../../types/type-aliases/SealedSecretScope.md)
+
+The encryption scope
+
+## Returns
+
+[`Result`](../../../types/type-aliases/Result.md)\<`Record`\<`string`, [`Base64String`](../../../types/type-aliases/Base64String.md)\>, `string`\>
+
+Result containing object mapping keys to encrypted values, or error message
@@ -0,0 +1,57 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/crypto](../README.md) / encryptValue
+
+# Function: encryptValue()
+
+> **encryptValue**(`publicKey`, `value`, `namespace`, `name`, `key`, `scope`): [`Result`](../../../types/type-aliases/Result.md)\<[`Base64String`](../../../types/type-aliases/Base64String.md), `string`\>
+
+Defined in: [src/lib/crypto.ts:55](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/crypto.ts#L55)
+
+Encrypt a secret value using the kubeseal format
+
+## Parameters
+
+### publicKey
+
+`PublicKey`
+
+RSA public key from the controller's certificate
+
+### value
+
+[`PlaintextValue`](../../../types/type-aliases/PlaintextValue.md)
+
+The plaintext secret value to encrypt (branded type)
+
+### namespace
+
+`string`
+
+The namespace (for strict/namespace-wide scoping)
+
+### name
+
+`string`
+
+The secret name (for strict scoping)
+
+### key
+
+`string`
+
+The key name within the secret
+
+### scope
+
+[`SealedSecretScope`](../../../types/type-aliases/SealedSecretScope.md)
+
+The encryption scope
+
+## Returns
+
+[`Result`](../../../types/type-aliases/Result.md)\<[`Base64String`](../../../types/type-aliases/Base64String.md), `string`\>
+
+Result containing base64-encoded encrypted value or error message
@@ -0,0 +1,33 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/crypto](../README.md) / isCertificateExpiringSoon
+
+# Function: isCertificateExpiringSoon()
+
+> **isCertificateExpiringSoon**(`info`, `daysThreshold?`): `boolean`
+
+Defined in: [src/lib/crypto.ts:220](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/crypto.ts#L220)
+
+Check if certificate will expire soon (within threshold)
+
+## Parameters
+
+### info
+
+[`CertificateInfo`](../../../types/interfaces/CertificateInfo.md)
+
+Certificate information
+
+### daysThreshold?
+
+`number` = `30`
+
+Number of days to consider "expiring soon" (default: 30)
+
+## Returns
+
+`boolean`
+
+true if certificate will expire within threshold days
@@ -0,0 +1,30 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/crypto](../README.md) / parseCertificateInfo
+
+# Function: parseCertificateInfo()
+
+> **parseCertificateInfo**(`pemCert`): [`Result`](../../../types/type-aliases/Result.md)\<[`CertificateInfo`](../../../types/interfaces/CertificateInfo.md), `string`\>
+
+Defined in: [src/lib/crypto.ts:168](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/crypto.ts#L168)
+
+Parse certificate and extract metadata
+
+Extracts validity dates, issuer/subject information, and calculates
+expiration status and fingerprint.
+
+## Parameters
+
+### pemCert
+
+[`PEMCertificate`](../../../types/type-aliases/PEMCertificate.md)
+
+PEM-encoded certificate string (branded type)
+
+## Returns
+
+[`Result`](../../../types/type-aliases/Result.md)\<[`CertificateInfo`](../../../types/interfaces/CertificateInfo.md), `string`\>
+
+Result containing certificate information or error message
@@ -0,0 +1,27 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/crypto](../README.md) / parsePublicKeyFromCert
+
+# Function: parsePublicKeyFromCert()
+
+> **parsePublicKeyFromCert**(`pemCert`): [`Result`](../../../types/type-aliases/Result.md)\<`PublicKey`, `string`\>
+
+Defined in: [src/lib/crypto.ts:32](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/crypto.ts#L32)
+
+Parse a PEM certificate and extract the RSA public key
+
+## Parameters
+
+### pemCert
+
+[`PEMCertificate`](../../../types/type-aliases/PEMCertificate.md)
+
+PEM-encoded certificate string (branded type)
+
+## Returns
+
+[`Result`](../../../types/type-aliases/Result.md)\<`PublicKey`, `string`\>
+
+Result containing the public key or an error message
@@ -0,0 +1,27 @@
+[**Headlamp Sealed Secrets API v0.2.0**](../../../README.md)
+
+***
+
+[Headlamp Sealed Secrets API](../../../README.md) / [lib/crypto](../README.md) / validateCertificate
+
+# Function: validateCertificate()
+
+> **validateCertificate**(`pemCert`): `boolean`
+
+Defined in: [src/lib/crypto.ts:154](https://github.com/cpfarhood/headlamp-sealed-secrets-plugin/blob/bdf19cd3bf5a2d679b7ba949108fe9df1843c5f4/headlamp-sealed-secrets/src/lib/crypto.ts#L154)
+
+Validate a PEM certificate
+
+## Parameters
+
+### pemCert
+
+[`PEMCertificate`](../../../types/type-aliases/PEMCertificate.md)
+
+PEM-encoded certificate string (branded type)
+
+## Returns
+
+`boolean`
+
+true if certificate is valid, false otherwise