fix(security)!: do not embed TOTP secret in unseal token

CRITICAL security fix in enterprise mode. Previous alpha versions
(0.1.0-alpha.{1,2,3}) embedded the operator's literal TOTP secret in
the JWS payload of every minted unseal token. JWS payload is base64
JSON, NOT encrypted — anyone observing a token (CI logs, container
env dumps, kubectl describe pod, stack traces in error reporters)
could extract the secret and, with the master key, mint unseal tokens
for FUTURE deploys indefinitely.

The fix:

  Token payload now carries a salt-bound HMAC derivative:
    enterprise_epoch = HMAC-SHA256(totpSecret, salt || "epoch-v1")

  File commits to:
    epoch_commit = HMAC-SHA256(derivedKey, enterprise_epoch || "epoch-commit-v1")

  Verification:
    expected = HMAC-SHA256(derivedKey, payload.epoch || "epoch-commit-v1")
    assert expected == file.EPOCH-COMMIT

  The TOTP secret never leaves the operator's machine. A leaked token
  reveals only the salt-bound derivative, which is useless for minting
  tokens against re-sealed files (different salt → different epoch).

BREAKING:

  - Wire format field renamed: TOTP-VERIFIER → EPOCH-COMMIT
  - Token payload field renamed: totp_secret → epoch
  - buildUnsealToken signature now requires the file's salt
  - Files sealed by 0.1.0-alpha.{1,2,3} are NOT readable by 0.1.0-alpha.4

Migration: re-init keys (TOTP rotation is mandatory) and re-seal all
files. See CHANGELOG entry for the full migration playbook.

Regression tests verify:
  - Serialized files do not contain TOTP-VERIFIER field
  - Minted tokens do not contain the literal secret in any encoding
    (hex, base64) or under the field name totp_secret

Both Node and Java sides updated in lockstep. Cross-stack vector
regenerated with the new format.

Reported by an external reviewer who decoded the JWS payload of a
minted token and matched the embedded value bit-for-bit against the
operator's .env.local TOTP secret. Thank you.

Author: davidalmeidac

CHANGELOG.md

@@ -14,6 +14,88 @@ files written today will remain readable forever. See [SPEC.md](./SPEC.md).
 
 ---
 
+## [0.1.0-alpha.4] — 2026-05-07
+
+> **🚨 SECURITY: this release fixes a critical issue in `enterprise` mode.
+> Prior versions (alpha.1, alpha.2, alpha.3) embedded the operator's TOTP
+> secret in the JWS payload of every unseal token. JWS payload is base64-
+> encoded JSON, NOT encrypted — anyone observing a token (CI logs, container
+> env dumps, stack traces) could extract the secret and use it (with the
+> master key) to mint unseal tokens for FUTURE deploys indefinitely.**
+>
+> **All `0.1.0-alpha.{1,2,3}` releases are deprecated on npm and Maven
+> Central. If you adopted enterprise mode in any of those versions:**
+>
+> 1. **Rotate your TOTP secret.** Re-run `sealed-env init --mode enterprise`.
+> 2. **Re-seal all `.env.sealed` files.** Old files use the deprecated wire
+>    field (`TOTP-VERIFIER`) and won't decrypt with `0.1.0-alpha.4`.
+> 3. **Update CI / production env to use the new package version.**
+>
+> The wire format intentionally breaks compatibility — files sealed before
+> alpha.4 are NOT readable by alpha.4. Since the package was not yet adopted
+> in the wild (only the author's own dogfooding), this seemed safer than a
+> backward-compatible code path that would silently keep reading the
+> insecure field on old files.
+
+### Security
+
+- **CRITICAL: TOTP secret no longer appears in unseal tokens.** The token
+  payload now carries an `enterprise_epoch`:
+  ```
+  enterprise_epoch = HMAC-SHA256(totp_secret, salt || "epoch-v1")
+  ```
+  This is a salt-bound HMAC derivative — knowing it does NOT let an
+  attacker recompute it for files with a different salt. The blast radius
+  of a leaked token is reduced from "permanent compromise of all current
+  and future enterprise files" to "compromise of one specific file
+  generation, until re-seal".
+
+- **Wire format field renamed:** `TOTP-VERIFIER` → `EPOCH-COMMIT`. The new
+  field commits to the salt-bound epoch instead of the raw TOTP secret:
+  ```
+  epoch_commit = HMAC-SHA256(derived_key, enterprise_epoch || "epoch-commit-v1")
+  ```
+
+- **Token payload field renamed:** `totp_secret` → `epoch`. Old field is
+  rejected. Any code or test that referenced the old field will fail at
+  parse time, surfacing the upgrade as a hard error rather than silent
+  insecurity.
+
+- **Regression tests added** that fail if either:
+  - The serialized file contains `TOTP-VERIFIER`, or
+  - A minted token contains the literal TOTP secret in any common encoding
+    (hex or base64), or the field name `totp_secret`.
+
+### Migration
+
+This release is **incompatible with files sealed by `0.1.0-alpha.{1,2,3}`**.
+To migrate:
+
+```sh
+# 1. Decrypt with the old version
+npx sealed-env@0.1.0-alpha.3 decrypt .env.sealed > /tmp/.env.plaintext
+
+# 2. Upgrade
+npm i -D sealed-env@0.1.0-alpha.4
+
+# 3. Re-init keys (TOTP secret rotation is mandatory)
+sealed-env init --mode enterprise
+
+# 4. Re-seal with the new keys
+sealed-env encrypt /tmp/.env.plaintext --mode enterprise
+
+# 5. Securely wipe the plaintext
+shred -u /tmp/.env.plaintext   # or: rm -P on macOS
+```
+
+### Credit
+
+This issue was identified by an external reviewer comparing the actual JWS
+payload of a minted token against the operator's `.env.local` TOTP secret
+and confirming bit-for-bit equality. Thank you for the careful eyes.
+
+---
+
 ## [0.1.0-alpha.3] — 2026-05-06
 
 Operational ergonomics release — adds the day-to-day commands that

README.md

@@ -155,7 +155,8 @@ private String stripeKey;
                                                      plaintext
 
                                                      ▲
-                                                     │ + totp_secret
+                                                     │ + unseal token (carries
+                                                     │   salt-bound TOTP epoch)
                                                      │ + deploy_id
 ```
 

SPEC.md

@@ -68,7 +68,7 @@ are simply skipped (the order remains stable).
 | 2 | `KDF-PARAMS` | all | For argon2id: `t=<int>,m=<int>,p=<int>`. For scrypt: `N=<int>,r=<int>,p=<int>` |
 | 3 | `SALT` | all | base64, 16 bytes raw |
 | 4 | `NONCE` | all | base64, 12 bytes raw |
-| 5 | `TOTP-VERIFIER` | enterprise only | base64, 32 bytes (HMAC-SHA256 commitment) |
+| 5 | `EPOCH-COMMIT` | enterprise only | base64, 32 bytes (HMAC-SHA256 commitment to the salt-bound enterprise epoch — see §6) |
 | 6 | `CHALLENGE-BIND` | enterprise only | `enabled` or `disabled` |
 | 7 | `AAD-DIGEST` | all | base64, 32 bytes (SHA-256 of associated data) |
 | 8 | `HMAC` | team and enterprise | base64, 32 bytes |
@@ -111,7 +111,11 @@ PKCS#1 v1.5 padding, custom RNG.
    `aad_digest = SHA-256(aad)`.
 6. `ciphertext_with_tag = AES-256-GCM-encrypt(enc_key, nonce, plaintext, aad)`.
 7. If `mode == enterprise`:
-   - `totp_verifier = HMAC-SHA256(derived_key, totp_secret || "verify-v1")`.
+   - `enterprise_epoch = HMAC-SHA256(totp_secret, salt || "epoch-v1")`.
+   - `epoch_commit = HMAC-SHA256(derived_key, enterprise_epoch || "epoch-commit-v1")`.
+   - The file commits to `epoch_commit`. The TOTP secret itself never appears
+     in any persisted artifact (file or token). The salt binding ensures a
+     leaked epoch is only useful against this specific file generation.
 8. If `mode in (team, enterprise)`:
    - `mac_key = HKDF(signing_key, salt=salt, info="sealed-env:v1:mac", L=32)`.
    - `hmac = HMAC-SHA256(mac_key, magic_line || metadata_without_HMAC || ciphertext_with_tag)`.
@@ -143,8 +147,10 @@ Always exclude the `HMAC` line itself when computing the HMAC over metadata.
    - Parse the unseal token (JWT-like, see §9).
    - Verify token signature with `derived_key`.
    - Verify `token.exp > now`.
-   - Verify `HMAC-SHA256(derived_key, token.totp_secret || "verify-v1") ==
-     stored TOTP-VERIFIER`. Constant-time compare.
+   - Verify `HMAC-SHA256(derived_key, token.epoch || "epoch-commit-v1") ==
+     stored EPOCH-COMMIT`. Constant-time compare. The token carries
+     `enterprise_epoch` (a salt-bound HMAC derivative of the operator's
+     TOTP secret), NOT the TOTP secret itself.
    - If `CHALLENGE-BIND=enabled`: verify `token.deploy_id` matches the
      current deploy challenge (provided by CI as `SEALED_ENV_DEPLOY_ID`).
 6. **AAD reconstruction:** rebuild `aad` from magic + metadata (excluding HMAC),
@@ -202,12 +208,26 @@ usl_<base64url(header)>.<base64url(payload)>.<base64url(signature)>
   "iss": "sealed-env-cli",
   "iat": 1717024500,
   "exp": 1717024560,
-  "totp_secret": "<base64-of-totp-seed>",
+  "epoch": "<base64-of-32-byte-enterprise-epoch>",
   "deploy_id": "<sha-256-of-commit-or-null>",
   "ops_id": "<random-uuid-v4>"
 }
 ```
 
+Where:
+
+```
+enterprise_epoch = HMAC-SHA256(totp_secret, salt || "epoch-v1")
+```
+
+The `enterprise_epoch` is a **salt-bound HMAC derivative** of the operator's
+TOTP secret — never the secret itself. This is the central security property
+of the unseal protocol: a leaked token (e.g., from CI logs, container env
+dumps, or stack traces) does NOT give the attacker the TOTP secret. Without
+the secret, the attacker cannot recompute `enterprise_epoch` for files with
+a different salt (i.e., future re-sealings), so the blast radius of a
+leaked token is bounded to the specific file generation that produced it.
+
 **Signature:**
 `HMAC-SHA256(derived_key, base64url(header) + "." + base64url(payload))`
 

docs/05-enterprise-mode.md

@@ -48,7 +48,7 @@ Enterprise mode adds two layers on top of `team`:
         │                                 │                          2. verify HMAC      ✓
         │                                 │                          3. verify token sig ✓
         │                                 │                          4. verify deploy_id ✓
-        │                                 │                          5. verify TOTP-VERIFIER
+        │                                 │                          5. verify EPOCH-COMMIT
         │                                 │                             commitment        ✓
         │                                 │                          6. AES-GCM decrypt   ✓
         │                                 │                                    │
@@ -72,27 +72,42 @@ Enterprise mode adds two layers on top of `team`:
         │           │                   header.payload)
         │           │
         │           └──▶ payload (JSON, base64url):
-        │                  iss          : sealed-env-cli
-        │                  iat          : <unix-seconds>
-        │                  exp          : <iat + 60>
-        │                  totp_secret  : <base64>
-        │                  deploy_id    : <commit-sha or null>
-        │                  ops_id       : <random uuid v4>
+        │                  iss        : sealed-env-cli
+        │                  iat        : <unix-seconds>
+        │                  exp        : <iat + 60>
+        │                  epoch      : <base64-of-32-byte enterprise epoch>
+        │                  deploy_id  : <commit-sha or null>
+        │                  ops_id     : <random uuid v4>
         │
         └──▶ header (JSON, base64url):
                alg : HS256
                typ : sealed-env-unseal/v1
 ```
 
+Where the **enterprise epoch** is a salt-bound HMAC derivative of the TOTP
+secret:
+
+```
+enterprise_epoch = HMAC-SHA256(totp_secret, salt || "epoch-v1")
+```
+
+The TOTP secret itself **never appears in the token**. A captured token
+gives the attacker only this salt-bound derivative — useful against the
+specific file generation that produced it (until re-sealing rotates the
+salt), but useless for minting tokens against future re-sealings.
+
 Key properties:
 - **Lifetime ≤ 600 seconds** (default 60). Short enough that a leaked token
   is rarely useful.
 - **Signed with the file's `derived_key`** (master_key + salt-derived). A
   token cannot be forged from the master key alone — you also need the
   file's salt, which means you need the file.
-- **`totp_secret` is committed at seal time** via the `TOTP-VERIFIER` field
-  (an HMAC commitment). The token's TOTP secret must match what was sealed
-  in, so an attacker cannot mint a token from a different TOTP secret.
+- **The TOTP secret never leaves the operator's machine.** What goes into
+  the token is `enterprise_epoch`, a salt-bound HMAC derivative committed
+  in the file via the `EPOCH-COMMIT` field. A leaked token cannot be used
+  to mint tokens against re-sealed files (different salt → different
+  epoch). This is what makes "TOTP" act as a real second factor and not a
+  one-time secret leak.
 
 ## What this protects against
 

docs/06-format-anatomy.md

@@ -44,7 +44,7 @@ verification fails.
 | `KDF-PARAMS` | all | Format depends on KDF |
 | `SALT` | all | 16 bytes, fed to KDF |
 | `NONCE` | all | 12 bytes, fed to AES-GCM |
-| `TOTP-VERIFIER` | enterprise | HMAC commitment to the TOTP secret |
+| `EPOCH-COMMIT` | enterprise | HMAC commitment to the salt-bound enterprise epoch (does NOT reveal the TOTP secret — see SPEC §6) |
 | `CHALLENGE-BIND` | enterprise | `enabled` or `disabled` |
 | `AAD-DIGEST` | all | SHA-256 over the bound metadata |
 | `HMAC` | team, enterprise | HMAC-SHA256 over magic + metadata + ciphertext |
@@ -71,7 +71,7 @@ newline.
                         │   join with \n          ┌─▶ AES-GCM
    SALT, NONCE         ─┼──▶ ──────────▶ AAD ────┤    setAAD(...)
                         │                         │
-   TOTP-VERIFIER,      ─┤                         ├─▶ SHA-256
+   EPOCH-COMMIT,       ─┤                         ├─▶ SHA-256
    CHALLENGE-BIND      ─┤                         │   ─▶ AAD-DIGEST
    (enterprise only)    │                         │      (defense in
                         │                         │       depth)

docs/07-operational-guide.md

@@ -185,7 +185,7 @@ Add the starter to `pom.xml`:
 <dependency>
   <groupId>io.github.davidalmeidac</groupId>
   <artifactId>sealed-env-spring-boot-starter</artifactId>
-  <version>0.1.0-alpha.3</version>
+  <version>0.1.0-alpha.4</version>
 </dependency>
 ```
 

java/pom.xml

@@ -7,7 +7,7 @@
 
   <groupId>io.github.davidalmeidac</groupId>
   <artifactId>sealed-env-parent</artifactId>
-  <version>0.1.0-alpha.3</version>
+  <version>0.1.0-alpha.4</version>
   <packaging>pom</packaging>
 
   <name>sealed-env (parent)</name>

java/sealed-env-core/pom.xml

@@ -8,7 +8,7 @@
   <parent>
     <groupId>io.github.davidalmeidac</groupId>
     <artifactId>sealed-env-parent</artifactId>
-    <version>0.1.0-alpha.3</version>
+    <version>0.1.0-alpha.4</version>
   </parent>
 
   <artifactId>sealed-env-core</artifactId>

java/sealed-env-core/src/main/java/io/github/davidalmeidac/sealedenv/SealedEnv.java

@@ -88,10 +88,12 @@ public static SealResult seal(SealOptions opts) {
         try {
             encKey = CryptoPrimitives.hkdf(derivedKey, salt, Constants.HKDF_INFO_ENC, Constants.KEY_LEN);
 
-            Optional<byte[]> totpVerifier = Optional.empty();
+            // Enterprise: derive the salt-bound epoch and commit to it.
+            // The token will carry the epoch (NOT the TOTP secret).
+            Optional<byte[]> epochCommit = Optional.empty();
             Optional<ChallengeBind> challengeBind = Optional.empty();
             if (opts.mode == Mode.ENTERPRISE) {
-                totpVerifier = Optional.of(buildVerifier(derivedKey, opts.totpSecret));
+                epochCommit = Optional.of(buildEpochCommit(derivedKey, opts.totpSecret, salt));
                 boolean cbEnabled = opts.challengeBind == null || opts.challengeBind;
                 challengeBind = Optional.of(cbEnabled
                         ? ChallengeBind.ENABLED : ChallengeBind.DISABLED);
@@ -101,7 +103,7 @@ public static SealResult seal(SealOptions opts) {
             // canonically build the AAD over metadata.
             SealedFile draft = new SealedFile(
                     1, opts.mode, params.algorithm(), params, salt, nonce,
-                    totpVerifier, challengeBind,
+                    epochCommit, challengeBind,
                     new byte[32], Optional.empty(),
                     created, Optional.empty(), new byte[0]);
 
@@ -123,7 +125,7 @@ public static SealResult seal(SealOptions opts) {
 
             SealedFile file = new SealedFile(
                     1, opts.mode, params.algorithm(), params, salt, nonce,
-                    totpVerifier, challengeBind, aadDigest, hmac,
+                    epochCommit, challengeBind, aadDigest, hmac,
                     created, Optional.empty(), ciphertext);
             return new SealResult(file, SealedFileSerializer.serialize(file));
         } finally {
@@ -168,7 +170,10 @@ public static byte[] unseal(UnsealOptions opts) {
                 }
             }
 
-            // Enterprise: verify unseal token + TOTP-VERIFIER commitment
+            // Enterprise: verify unseal token carries an epoch matching
+            // the file's EPOCH-COMMIT. The TOTP secret never appears
+            // in the token — the carried `enterpriseEpoch` is a salt-
+            // bound HMAC derivative.
             if (file.mode() == Mode.ENTERPRISE) {
                 UnsealToken.VerifyResult result = UnsealToken.verify(
                         new UnsealToken.VerifyInput(
@@ -177,13 +182,13 @@ public static byte[] unseal(UnsealOptions opts) {
                                 opts.deployId,
                                 file.challengeBind().orElse(ChallengeBind.ENABLED)
                                         == ChallengeBind.ENABLED));
-                byte[] expectedVerifier = buildVerifier(derivedKey, result.totpSecret());
-                if (file.totpVerifier().isEmpty()
+                byte[] expectedCommit = buildEpochCommitFromEpoch(derivedKey, result.enterpriseEpoch());
+                if (file.epochCommit().isEmpty()
                         || !CryptoPrimitives.constantTimeEqual(
-                        expectedVerifier, file.totpVerifier().get())) {
+                        expectedCommit, file.epochCommit().get())) {
                     throw SealedEnvException.decryptFailed();
                 }
-                CryptoPrimitives.wipe(result.totpSecret());
+                CryptoPrimitives.wipe(result.enterpriseEpoch());
             }
 
             // AAD digest defense in depth (GCM tag would also catch this)
@@ -281,9 +286,36 @@ public static void applyToSystemProperties(Map<String, String> env) {
 
     // ── helpers ────────────────────────────────────────────────────────────
 
-    private static byte[] buildVerifier(byte[] derivedKey, byte[] totpSecret) {
-        byte[] tag = Constants.TOTP_VERIFY_TAG.getBytes(StandardCharsets.UTF_8);
-        return CryptoPrimitives.hmacSha256(derivedKey, concat(totpSecret, tag));
+    /**
+     * Compute the salt-bound enterprise epoch (used at seal/mint time):
+     * {@code enterprise_epoch = HMAC(totpSecret, salt || "epoch-v1")}.
+     * Caller is responsible for wiping the returned buffer.
+     */
+    static byte[] buildEnterpriseEpoch(byte[] totpSecret, byte[] salt) {
+        byte[] tag = Constants.EPOCH_DERIVE_TAG.getBytes(StandardCharsets.UTF_8);
+        return CryptoPrimitives.hmacSha256(totpSecret, concat(salt, tag));
+    }
+
+    /**
+     * Compute the file-side epoch commitment:
+     * {@code epoch_commit = HMAC(derivedKey, enterprise_epoch || "epoch-commit-v1")}.
+     */
+    private static byte[] buildEpochCommitFromEpoch(byte[] derivedKey, byte[] enterpriseEpoch) {
+        byte[] tag = Constants.EPOCH_COMMIT_TAG.getBytes(StandardCharsets.UTF_8);
+        return CryptoPrimitives.hmacSha256(derivedKey, concat(enterpriseEpoch, tag));
+    }
+
+    /**
+     * Compose: derive epoch from totpSecret + salt, then commit it under derivedKey.
+     * Used at seal time. Wipes the intermediate epoch.
+     */
+    private static byte[] buildEpochCommit(byte[] derivedKey, byte[] totpSecret, byte[] salt) {
+        byte[] epoch = buildEnterpriseEpoch(totpSecret, salt);
+        try {
+            return buildEpochCommitFromEpoch(derivedKey, epoch);
+        } finally {
+            CryptoPrimitives.wipe(epoch);
+        }
     }
 
     private static byte[] concat(byte[] a, byte[] b) {

java/sealed-env-core/src/main/java/io/github/davidalmeidac/sealedenv/core/Constants.java

@@ -42,6 +42,24 @@ private Constants() {
     public static final String HKDF_INFO_ENC = "sealed-env:v1:enc";
     public static final String HKDF_INFO_MAC = "sealed-env:v1:mac";
 
-    /** TOTP verifier domain-separation tag. */
-    public static final String TOTP_VERIFY_TAG = "verify-v1";
+    /**
+     * Enterprise epoch derivation tag — used at seal/mint time to derive
+     * the salt-bound enterprise epoch from the TOTP secret:
+     *
+     *   enterprise_epoch = HMAC-SHA256(totpSecret, salt || EPOCH_DERIVE_TAG)
+     */
+    public static final String EPOCH_DERIVE_TAG = "epoch-v1";
+
+    /**
+     * Enterprise epoch commitment tag — used by the file to commit to a
+     * specific epoch without revealing it:
+     *
+     *   epoch_commit = HMAC-SHA256(derivedKey, enterprise_epoch || EPOCH_COMMIT_TAG)
+     *
+     * The verifier recomputes this from the token's epoch field and
+     * compares against the file's EPOCH-COMMIT field. This commits to
+     * the operator-side TOTP secret WITHOUT requiring the verifier to
+     * ever see the secret itself.
+     */
+    public static final String EPOCH_COMMIT_TAG = "epoch-commit-v1";
 }