@blamejs/core 0.14.11 → 0.14.13

package/lib/auth/oid4vp.js

@@ -148,40 +148,52 @@ function _validateDcql(dcql) {
 }
 
 /**
- * Walk the path against the resolved-claim object the SD-JWT VC
- * verifier produced. Returns { found, value }.
- *   path = ["address", "country"]    → claims.address.country
- *   path = ["array", 0]              → claims.array[0]
- *   null = "any element" (DCQL §6.4.2 array path semantics) — for
- *     v1-defensible we don't dispatch on null; refuse with a clear
- *     error so the operator knows the gap.
+ * Walk a DCQL claims path pointer (OpenID4VP 1.0 §7.1.1) against the
+ * resolved-claim object the SD-JWT VC verifier produced, applying
+ * `leafPredicate` at the terminal node and returning a boolean:
+ *   string  → object property                  (["address", "country"])
+ *   integer → array index                       (["array", 0])
+ *   null    → all elements of the array at this depth (recurse; the
+ *             match is an existence check over the candidate leaves)
+ * A `null` segment on a non-array node — like an integer index into a
+ * non-array or a string key into an array — is a NON-MATCH, not an
+ * error: this walks holder credential data, not operator config, so a
+ * structural mismatch fails the match cleanly (rule §5 defensive
+ * request-shape reader tier) rather than throwing and crashing the
+ * verify request.
  */
-function _resolvePath(claims, path) {
-  var node = claims;
-  for (var i = 0; i < path.length; i++) {
-    var seg = path[i];
-    if (seg === null) {
-      // DCQL §6.4.2: null means "any element of the array at this
-      // depth". Not in v1 — refuse loudly so it doesn't silently
-      // match nothing.
-      throw new AuthError("auth-oid4vp/null-path-segment-not-supported",
-        "DCQL: null path segment (any-element) not supported in v1; supply a numeric index");
-    }
-    if (node === undefined || node === null) return { found: false, value: undefined };
-    node = node[seg];
+function _walkPath(node, path, idx, leafPredicate) {
+  if (idx === path.length) return leafPredicate(node);
+  if (node === undefined || node === null) return false;
+  var seg = path[idx];
+  if (seg === null) {
+    if (!Array.isArray(node)) return false;
+    return node.some(function (el) { return _walkPath(el, path, idx + 1, leafPredicate); });
+  }
+  if (typeof seg === "number") {
+    if (!Array.isArray(node)) return false;
+    return _walkPath(node[seg], path, idx + 1, leafPredicate);
   }
-  return { found: node !== undefined, value: node };
+  // string segment selects an object property; a string key into an
+  // array is a non-match (use a null wildcard or integer index instead).
+  if (Array.isArray(node)) return false;
+  return _walkPath(node[seg], path, idx + 1, leafPredicate);
 }
 
 function _matchClaim(claims, claimQuery) {
-  var resolved = _resolvePath(claims, claimQuery.path);
-  if (!resolved.found) return false;
-  if (claimQuery.values && claimQuery.values.length > 0) {
-    return claimQuery.values.some(function (v) {
-      return v === resolved.value || JSON.stringify(v) === JSON.stringify(resolved.value);
-    });
+  var values = claimQuery.values;
+  var leafPredicate;
+  if (values && values.length > 0) {
+    leafPredicate = function (leaf) {
+      if (leaf === undefined) return false;
+      return values.some(function (v) {
+        return v === leaf || JSON.stringify(v) === JSON.stringify(leaf);
+      });
+    };
+  } else {
+    leafPredicate = function (leaf) { return leaf !== undefined; };
   }
-  return true;
+  return _walkPath(claims, claimQuery.path, 0, leafPredicate);
 }
 
 function _matchCredentialQuery(presentation, query) {
@@ -219,6 +231,13 @@ function _matchCredentialQuery(presentation, query) {
  * implement their own verifier transport call this directly after
  * SD-JWT VC verification.
  *
+ * Claim path pointers follow OpenID4VP 1.0 §7.1.1: a string segment
+ * selects an object property, a non-negative integer indexes an array,
+ * and a `null` segment matches any element of the array at that depth
+ * (e.g. `["degrees", null, "type"]` matches the `type` claim of any
+ * element in the `degrees` array). A `null` segment applied to a
+ * non-array node is a non-match.
+ *
  * @example
  *   var match = b.auth.oid4vp.matchDcql([
  *     { id: "id-card", format: "vc+sd-jwt", claims: { vct: "...", given_name: "Alice" } }

package/lib/cluster.js

@@ -52,6 +52,7 @@ var safeAsync = require("./safe-async");
 var safeJson = require("./safe-json");
 var safeSql = require("./safe-sql");
 var safeUrl = require("./safe-url");
+var validateOpts = require("./validate-opts");
 var { FrameworkError, ClusterError } = require("./framework-error");
 
 // Lazy: vault → db → cluster forms a load-time chain, and external-db is
@@ -99,6 +100,15 @@ var configuredDialect            = null;
 // (or external observer) can resolve "where is the current leader?"
 // via cluster.currentLeader() / cluster.discoveryHandler().
 var configuredEndpoint          = null;
+// Operator declaration that this node's vault keypair legitimately
+// changed via a key rotation (b.vault.rotate). When set, a fingerprint
+// that differs from the canonical cluster-state row is ADOPTED (the row
+// advances to the new fingerprint + bumps the rotation epoch) instead
+// of FATAL-refusing boot. Unset (the default) keeps the strict
+// drift-refusal posture for the UNexpected mismatch. See
+// _checkVaultKeyConsistency for the consistency model.
+var configuredAcceptRotation     = false;
+var configuredExpectedVaultKeyFp = null;
 
 var log = boot("cluster");
 
@@ -142,6 +152,16 @@ function _emitTransition(kind, detail) {
  * outside `leader` / `follower`, and on a chain or vault-key mismatch
  * that would let this node corrupt cluster state.
  *
+ * After a vault-key rotation (`b.vault.rotate`) the public-key
+ * fingerprint changes, so the canonical cluster-state row no longer
+ * matches and every node would otherwise refuse boot with
+ * `VAULT_KEY_DRIFT`. Pass `acceptVaultKeyRotation: true` to declare the
+ * change legitimate: the node advances the canonical fingerprint and
+ * bumps a rotation epoch instead of refusing. `expectedVaultKeyFp`
+ * narrows the acceptance to a single blessed fingerprint so a typo'd /
+ * stale key file is still caught. The strict cross-node drift refusal
+ * stays in force whenever the rotation is NOT declared.
+ *
  * @opts
  *   nodeId:             string,            // required; stable identity
  *   role:               "leader"|"follower",
@@ -152,6 +172,11 @@ function _emitTransition(kind, detail) {
  *   provider:           object,            // custom election provider
  *   externalDbBackend:  object,            // required when no custom provider
  *   dialect:            "postgres"|"sqlite"|"mysql",
+ *   acceptVaultKeyRotation: boolean,        // adopt a rotated vault-key
+ *                                          // fingerprint instead of
+ *                                          // refusing boot on mismatch
+ *   expectedVaultKeyFp: string,            // optional; bless ONLY this
+ *                                          // post-rotation fingerprint
  *   onTransition:       function (event),
  *
  * @example
@@ -227,6 +252,31 @@ async function init(opts) {
     configuredEndpoint = null;
   }
 
+  // Vault-key rotation acceptance (config-time tier: THROW on bad
+  // input). acceptVaultKeyRotation is a boolean declaration; an
+  // expectedVaultKeyFp without it is a misconfiguration (the operator
+  // blessed a fingerprint but never enabled adoption).
+  validateOpts.optionalBoolean(opts.acceptVaultKeyRotation,
+    "cluster.init({ acceptVaultKeyRotation })", ClusterError, "INVALID_CONFIG");
+  configuredAcceptRotation = opts.acceptVaultKeyRotation === true;
+  if (opts.expectedVaultKeyFp !== undefined) {
+    if (typeof opts.expectedVaultKeyFp !== "string" ||
+        !/^[0-9a-f]{128}$/.test(opts.expectedVaultKeyFp)) {
+      throw _err("INVALID_CONFIG",
+        "cluster.init({ expectedVaultKeyFp }) must be a 128-char " +
+        "lowercase-hex SHA3-512 fingerprint (b.vault rotation output)", true);
+    }
+    if (!configuredAcceptRotation) {
+      throw _err("INVALID_CONFIG",
+        "cluster.init({ expectedVaultKeyFp }) requires " +
+        "acceptVaultKeyRotation: true — blessing a fingerprint without " +
+        "enabling adoption has no effect", true);
+    }
+    configuredExpectedVaultKeyFp = opts.expectedVaultKeyFp;
+  } else {
+    configuredExpectedVaultKeyFp = null;
+  }
+
   if (typeof opts.onTransition === "function") {
     transitionHandlers.push(opts.onTransition);
   }
@@ -433,6 +483,49 @@ function _vaultKeyFingerprint() {
                          keys.ecPublicKey);
 }
 
+// Idempotent migration for the rotationEpoch column. cluster-provider-db
+// ensureSchema creates _blamejs_cluster_state without it (the column was
+// added when rotation-epoch acceptance landed); ADD COLUMN here keeps the
+// path version-agnostic the same way the provider migrates the leader
+// row's `endpoint` column. The only expected failure is "column already
+// exists," which is swallowed. SQLite / MySQL don't take a DEFAULT on a
+// non-constant, so the column is nullable and treated as epoch 0 when
+// absent on legacy rows.
+async function _ensureRotationEpochColumn() {
+  try {
+    await externalDb().query(
+      "ALTER TABLE _blamejs_cluster_state ADD COLUMN rotationEpoch BIGINT",
+      [],
+      { backend: configuredExternalDbBackend }
+    );
+  } catch (_e) { /* column already exists (or table absent — caught upstream) */ }
+}
+
+// Consistency model (CWE-345 binding-integrity for sealed columns):
+//
+//   Every node fingerprints its vault PUBLIC keys (SHA3-512, one-way) and
+//   the cluster agrees on ONE canonical fingerprint stored in
+//   _blamejs_cluster_state. A node holding a different key seals new
+//   writes the rest of the cluster can't unseal — silent corruption — so
+//   an UNDECLARED mismatch fails closed (FATAL: VAULT_KEY_DRIFT).
+//
+//   A vault-key rotation (b.vault.rotate, lib/vault/rotate.js) legitimately
+//   changes the public-key fingerprint on EVERY node. The rotation only
+//   re-seals the local dataDir; it does not touch the external coordination
+//   row, so the canonical fingerprint goes stale and every node would
+//   refuse boot. acceptVaultKeyRotation: true is the operator's signed-off
+//   declaration "this change is a rotation, not drift": the booting node
+//   ADVANCES the canonical row to its own fingerprint and bumps a
+//   monotonic rotationEpoch. expectedVaultKeyFp narrows the adoption to a
+//   single blessed fingerprint so a stale / wrong key file is still
+//   refused. The strict refusal is unchanged when no rotation is declared,
+//   which is exactly the cross-node drift case the check defends.
+//
+//   The epoch is observability + a future-replay guard, not an auth
+//   boundary — the auth boundary is the operator's deliberate opt
+//   (acceptVaultKeyRotation) plus the optional fingerprint allowlist. A
+//   forged row can only ever cost a single declared boot, and a genuinely
+//   different key would still fail every sealed read.
 async function _checkVaultKeyConsistency() {
   var localFp = _vaultKeyFingerprint();
   if (localFp === null) {
@@ -469,10 +562,15 @@ async function _checkVaultKeyConsistency() {
     throw e;
   }
 
+  // Bring the rotationEpoch column into existence (idempotent). The INSERT
+  // above already proved the table is present, so a real ALTER failure
+  // here is "column exists" and is swallowed.
+  await _ensureRotationEpochColumn();
+
   // Read whatever fingerprint is canonical (ours if first boot,
   // someone else's if we lost the race or are joining an existing cluster).
   var rows = await externalDb().query(
-    "SELECT vaultKeyFp, recordedByNode, recordedAt FROM _blamejs_cluster_state " +
+    "SELECT vaultKeyFp, recordedByNode, recordedAt, rotationEpoch FROM _blamejs_cluster_state " +
     "WHERE scope = 'state'",
     [],
     { backend: configuredExternalDbBackend }
@@ -486,22 +584,92 @@ async function _checkVaultKeyConsistency() {
       true);
   }
   var canonical = rows.rows[0];
+  var fpPrefix = C.BYTES.bytes(16);
   if (canonical.vaultKeyFp !== localFp) {
-    var fpPrefix = C.BYTES.bytes(16);
-    throw _err("VAULT_KEY_DRIFT",
-      "FATAL: vault-key drift detected. " +
-      "local node: " + nodeId +
-      "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
-      "; canonical recorded by: " + canonical.recordedByNode +
-      "; canonical fingerprint: " + canonical.vaultKeyFp.slice(0, fpPrefix) + "…" +
-      ". This node holds a DIFFERENT vault key than the rest of the " +
-      "cluster. Sealed-column writes from this node would be unreadable " +
-      "by the others (and vice versa). Restore the same vault key file " +
-      "before booting this node into the cluster.",
-      true);
+    // Mismatch. Two readings: a legitimate vault-key rotation the
+    // operator has declared, or genuine cross-node drift. Without the
+    // declaration, always fail closed — sealed-column corruption is the
+    // worse outcome.
+    if (!configuredAcceptRotation) {
+      throw _err("VAULT_KEY_DRIFT",
+        "FATAL: vault-key drift detected. " +
+        "local node: " + nodeId +
+        "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
+        "; canonical recorded by: " + canonical.recordedByNode +
+        "; canonical fingerprint: " + canonical.vaultKeyFp.slice(0, fpPrefix) + "…" +
+        ". This node holds a DIFFERENT vault key than the rest of the " +
+        "cluster. Sealed-column writes from this node would be unreadable " +
+        "by the others (and vice versa). If the key changed via " +
+        "b.vault.rotate, re-init with acceptVaultKeyRotation: true to " +
+        "advance the cluster's recorded fingerprint; otherwise restore the " +
+        "same vault key file before booting this node into the cluster.",
+        true);
+    }
+    // Rotation declared. If the operator blessed a specific fingerprint,
+    // the LOCAL key must match it — this rejects a stale / wrong key file
+    // that happens to differ from canonical for the wrong reason.
+    if (configuredExpectedVaultKeyFp && configuredExpectedVaultKeyFp !== localFp) {
+      throw _err("VAULT_KEY_ROTATION_MISMATCH",
+        "FATAL: acceptVaultKeyRotation is set but this node's vault-key " +
+        "fingerprint does not match the blessed expectedVaultKeyFp. " +
+        "local node: " + nodeId +
+        "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
+        "; expected fingerprint: " + configuredExpectedVaultKeyFp.slice(0, fpPrefix) + "…" +
+        ". This node is NOT holding the rotated key the operator approved. " +
+        "Restore the post-rotation vault key file (or correct " +
+        "expectedVaultKeyFp) before booting this node into the cluster.",
+        true);
+    }
+    // Adopt: advance the canonical row to the new fingerprint and bump
+    // the monotonic rotation epoch. The UPDATE is gated on the OLD
+    // fingerprint so two nodes adopting concurrently converge on a single
+    // advance (the loser's WHERE matches nothing and it re-reads the
+    // already-advanced row below).
+    var priorEpoch = (canonical.rotationEpoch != null) ? Number(canonical.rotationEpoch) : 0;
+    if (!isFinite(priorEpoch) || priorEpoch < 0) priorEpoch = 0;
+    var nextEpoch = priorEpoch + 1;
+    await externalDb().query(
+      "UPDATE _blamejs_cluster_state SET " +
+      "  vaultKeyFp = " + (ph ? "$1" : "?") + ", " +
+      "  recordedAt = " + (ph ? "$2" : "?") + ", " +
+      "  recordedByNode = " + (ph ? "$3" : "?") + ", " +
+      "  rotationEpoch = " + (ph ? "$4" : "?") + " " +
+      "WHERE scope = 'state' AND vaultKeyFp = " + (ph ? "$5" : "?"),
+      [localFp, nowMs, nodeId, nextEpoch, canonical.vaultKeyFp],
+      { backend: configuredExternalDbBackend }
+    );
+    // Re-read so the post-adopt state reflects whoever actually won the
+    // advance (this node, or a peer that adopted the SAME rotated key a
+    // beat earlier). A surviving mismatch here means the row now carries a
+    // fingerprint that is neither the old one nor ours — a real drift that
+    // the rotation declaration does not cover, so fail closed.
+    var after = await externalDb().query(
+      "SELECT vaultKeyFp, recordedByNode, rotationEpoch FROM _blamejs_cluster_state " +
+      "WHERE scope = 'state'",
+      [],
+      { backend: configuredExternalDbBackend }
+    );
+    var post = (after.rows && after.rows[0]) || canonical;
+    if (post.vaultKeyFp !== localFp) {
+      throw _err("VAULT_KEY_DRIFT",
+        "FATAL: vault-key drift detected after rotation-accept. " +
+        "local node: " + nodeId +
+        "; local fingerprint: " + localFp.slice(0, fpPrefix) + "…" +
+        "; canonical fingerprint: " + post.vaultKeyFp.slice(0, fpPrefix) + "…" +
+        ". A concurrent node advanced the cluster to a DIFFERENT key than " +
+        "this node holds — the declared rotation does not cover this " +
+        "fingerprint. Restore the agreed post-rotation vault key file.",
+        true);
+    }
+    log("cluster vault-key rotation accepted (fingerprint " +
+      localFp.slice(0, fpPrefix) + "… epoch " +
+      (post.rotationEpoch != null ? Number(post.rotationEpoch) : nextEpoch) +
+      ", recorded by " + post.recordedByNode + ")");
+    return;
   }
   log("cluster vault-key consistency ok (fingerprint " +
-    localFp.slice(0, C.BYTES.bytes(16)) + "… recorded by " + canonical.recordedByNode + ")");
+    localFp.slice(0, fpPrefix) + "… recorded by " + canonical.recordedByNode +
+    (canonical.rotationEpoch != null ? ", epoch " + Number(canonical.rotationEpoch) : "") + ")");
 }
 
 async function _tryAcquire() {
@@ -967,6 +1135,8 @@ async function shutdown() {
   configuredExternalDbBackend = null;
   configuredDialect = null;
   configuredEndpoint = null;
+  configuredAcceptRotation = false;
+  configuredExpectedVaultKeyFp = null;
   transitionHandlers = [];
   // nodeId is preserved post-shutdown so audit metadata still reflects
   // who this process was; cleared only by _resetForTest.
@@ -988,6 +1158,8 @@ function _resetForTest() {
   configuredExternalDbBackend = null;
   configuredDialect = null;
   configuredEndpoint = null;
+  configuredAcceptRotation = false;
+  configuredExpectedVaultKeyFp = null;
   transitionHandlers = [];
 }
 

package/lib/crypto-field.js

@@ -1105,6 +1105,11 @@ module.exports = {
   getSealedFields:  getSealedFields,
   sealRow:          sealRow,
   unsealRow:        unsealRow,
+  // _aadParts — the column-AAD builder the seal/unseal path uses. Exported
+  // (internal) so the vault-key rotation pipeline reconstructs the IDENTICAL
+  // AAD tuple a cell was sealed under — one source of truth, no drift
+  // between the seal side and the rotate side.
+  _aadParts:        _aadParts,
   // Doc-shaped aliases — operators / tests preparing a JS document
   // object (vs. a SQL row) reach for sealDoc / unsealDoc naming. Same
   // function, identical shape, returns a new object (input untouched).

package/lib/db.js

@@ -1318,6 +1318,15 @@ async function init(opts) {
       derivedHashes:   t.derivedHashes,
       hashNamespaces:  t.hashNamespaces,
       derivedHashMode: t.derivedHashMode,
+      // AAD-binding metadata MUST pass through — without it a schema that
+      // declares { aad: true } registers as a plain table, so its cells
+      // seal under vault: (not vault.aad:) and the vault-key rotation
+      // pipeline cannot reconstruct their AAD. registerTable defaults these
+      // (aad:false / rowIdField:"id" / schemaVersion:"1") so non-AAD tables
+      // are unaffected.
+      aad:             t.aad,
+      rowIdField:      t.rowIdField,
+      schemaVersion:   t.schemaVersion,
     });
     tableMetadata[t.name] = {
       primaryKey:             _normalizePk(t),
@@ -3161,6 +3170,12 @@ module.exports = {
   // (plain mode) or when the plaintext DB doesn't exist.
   flushToDisk:         encryptToDisk,
   snapshot:            snapshot,
+  // Internal AAD constructors, exported so the vault-key rotation
+  // pipeline (lib/vault/rotate.js) re-seals db.enc / db.key.enc under the
+  // SAME deployment-bound AAD this module writes them with — single source
+  // of truth for the wire-format literals (no duplicated constants).
+  _dbEncAad:           _dbEncAad,
+  _dbKeyAad:           _dbKeyAad,
   // integrityCheck — runs PRAGMA integrity_check against the live db
   // and returns "ok" on success, an array of corruption lines
   // otherwise. Operators wire this into a periodic monitor or a

package/lib/mail-srs.js

@@ -28,15 +28,24 @@
  *     - `local` is the original sender's local-part
  *     - `forwarder.example` is the rewriting forwarder's domain
  *
- *   SRS1 (double-forward case): when an already-SRS0-encoded address
- *   gets forwarded a second time, SRS1 wraps the SRS0 envelope
- *   instead of re-encoding from scratch, preserving the original
- *   sender chain.
+ *   Wire format (SRS1 — the multi-hop chain case):
+ *
+ *     SRS1=HHH=priorForwarder==<SRS0-body>@thisForwarder
+ *
+ *   When an already-SRS0 (or SRS1) address is forwarded again,
+ *   `srs1Rewrite(srsAddress)` wraps it: it keeps the original SRS0
+ *   body verbatim, prepends the preceding forwarder's domain, and
+ *   binds the pair with this forwarder's own HMAC tag — no new
+ *   timestamp, no repeated original local-part. `reverse()` detects
+ *   SRS1, verifies this hop's tag, and unwraps exactly one hop back to
+ *   the prior forwarder's SRS0 address so the bounce re-routes to it.
  *
  *   `b.mail.srs.create({ secret, forwarderDomain })` returns
- *   `{ rewrite, reverse }`. `rewrite(originalSender)` produces the
- *   SRS-encoded address; `reverse(srsAddress)` decodes back to the
- *   original sender + verifies the HMAC.
+ *   `{ rewrite, srs1Rewrite, reverse }`. `rewrite(originalSender)`
+ *   produces the SRS0 address; `srs1Rewrite(srsAddress)` chains a
+ *   further hop as SRS1; `reverse(srsAddress)` decodes an SRS0 back to
+ *   the original sender (verifying HMAC + expiry) or unwraps an SRS1
+ *   one hop back to the prior forwarder.
  *
  * @card
  *   SRS Sender Rewriting Scheme — forwarder envelope-from rewriting with HMAC-bound day-rotated tags so the next-hop SPF check passes and bounces route correctly back to the original sender.
@@ -94,6 +103,34 @@ function _dayDiff(stamp, nowMs) {
   return diff;
 }
 
+// Parse an SRS1 local-part "SRS1=<tag>=<priorForwarder>==<srs0Body>"
+// into its three fields. The 4-char base32 tag and the prior-forwarder
+// domain both carry no "=", so the FIRST "=" ends the tag and the FIRST
+// "==" (which can only fall immediately after the "="-free prior-forwarder
+// domain) ends the prior forwarder — even when the inner SRS0 body carries
+// its own single "=" separators.
+function _parseSrs1(localPart) {
+  var rest = localPart.slice(5);                                                                   // strip "SRS1="
+  var firstEq = rest.indexOf("=");
+  if (firstEq <= 0) {
+    throw new SrsError("srs/malformed",
+      "srs.reverse: SRS1 must be SRS1=tag=priorForwarder==<srs0body>");
+  }
+  var tag = rest.slice(0, firstEq);
+  var afterTag = rest.slice(firstEq + 1);
+  var sep = afterTag.indexOf("==");
+  if (sep <= 0) {
+    throw new SrsError("srs/malformed",
+      "srs.reverse: SRS1 missing the '==' prior-forwarder separator");
+  }
+  var srs0Body = afterTag.slice(sep + 2);
+  if (!srs0Body) {
+    throw new SrsError("srs/malformed",
+      "srs.reverse: SRS1 carries an empty inner SRS0 body");
+  }
+  return { tag: tag, priorForwarder: afterTag.slice(0, sep), srs0Body: srs0Body };
+}
+
 /**
  * @primitive b.mail.srs.create
  * @signature b.mail.srs.create(opts)
@@ -101,7 +138,11 @@ function _dayDiff(stamp, nowMs) {
  * @status    stable
  *
  * Build an SRS rewriter bound to the operator's forwarder domain +
- * HMAC signing secret. Returns `{ rewrite, reverse }`.
+ * HMAC signing secret. Returns `{ rewrite, srs1Rewrite, reverse }` —
+ * `rewrite` produces an SRS0 origin address, `srs1Rewrite` chains an
+ * already-SRS0/SRS1 address as SRS1 for a further forwarding hop, and
+ * `reverse` decodes either form (SRS0 → original sender with HMAC +
+ * expiry checks; SRS1 → the prior forwarder's address, one hop back).
  *
  * @opts
  *   secret:           string,   // operator's HMAC-SHA-256 signing secret (>=32 bytes recommended)
@@ -121,6 +162,11 @@ function _dayDiff(stamp, nowMs) {
  *   // Bounce arrives back at SRS0=...; decode to deliver
  *   var original = srs.reverse(rewritten);
  *   // → "alice@bob.com"
+ *
+ *   // A further forwarding hop chains the already-SRS0 address as SRS1
+ *   var hop2 = srs.srs1Rewrite(rewritten);
+ *   // → "SRS1=HHHH=forwarder.example==HHHH=TT=bob.com=alice@forwarder.example"
+ *   srs.reverse(hop2);   // → the prior-hop SRS0 address, re-routed one hop back
  */
 function create(opts) {
   if (!opts || typeof opts !== "object") {
@@ -158,13 +204,12 @@ function create(opts) {
       throw new SrsError("srs/bad-address",
         "srs.rewrite: localPart / domain exceeds RFC 5321 length cap");
     }
-    // Refuse SRS double-encoding from this primitive — operator must
-    // use srs1Rewrite() for already-SRS0 inputs (deferred per the
-    // v1-defensible decision: SRS1 wrapping is rare in operator
-    // deployments and adds substantial spec surface).
+    // Refuse SRS double-encoding from this primitive — already-SRS0 (or
+    // SRS1) inputs chain through srs1Rewrite(), which keeps the original
+    // SRS0 body verbatim rather than re-stamping it as a fresh origin.
     if (/^SRS[01]=/i.test(localPart)) {
       throw new SrsError("srs/already-rewritten",
-        "srs.rewrite: address already SRS-encoded; chain forwarding through SRS1 is not yet supported (operator demand TBD)");
+        "srs.rewrite: address already SRS-encoded; use srs1Rewrite() to chain a further forwarding hop");
     }
     var now = typeof nowMs === "number" ? nowMs : Date.now();
     var ts  = _dayStamp(now);
@@ -173,6 +218,49 @@ function create(opts) {
     return "SRS0=" + tag + "=" + ts + "=" + domain + "=" + localPart + "@" + forwarderDomain;
   }
 
+  function srs1Rewrite(srsAddress) {
+    validateOpts.requireNonEmptyString(
+      srsAddress, "srs.srs1Rewrite.address", SrsError, "srs/bad-address");
+    var at = srsAddress.lastIndexOf("@");
+    if (at <= 0 || at === srsAddress.length - 1) {
+      throw new SrsError("srs/bad-address",
+        "srs.srs1Rewrite: address must be in localPart@domain form");
+    }
+    var localPart = srsAddress.slice(0, at);
+    // The SRS0 body is kept verbatim across the whole chain (the SRS1
+    // optimization: no new timestamp, no repeated original local-part).
+    // `priorForwarder` is the domain the bounce must ultimately reach to
+    // recover the original sender — i.e. the forwarder that MINTED the
+    // inner SRS0. From an SRS0 input that is its own @domain; from an
+    // SRS1 input (a third or later hop) it is the originator already
+    // recorded in the SRS1, NOT the immediately-preceding forwarder, so
+    // every hop's bounce routes straight back to the SRS0 originator.
+    var priorForwarder, srs0Body;
+    if (/^SRS0=/i.test(localPart)) {
+      priorForwarder = srsAddress.slice(at + 1);
+      srs0Body = localPart.slice(5);
+    } else if (/^SRS1=/i.test(localPart)) {
+      var inner = _parseSrs1(localPart);
+      priorForwarder = inner.priorForwarder;
+      srs0Body = inner.srs0Body;
+    } else {
+      throw new SrsError("srs/not-srs0",
+        "srs.srs1Rewrite: input must be an SRS0 or SRS1 address (use rewrite() for a plain address)");
+    }
+    if (!priorForwarder || priorForwarder.indexOf("=") !== -1) {
+      throw new SrsError("srs/bad-address",
+        "srs.srs1Rewrite: prior forwarder domain must be a non-empty domain without '=' (would corrupt SRS1 field parsing)");
+    }
+    var opaque = priorForwarder + "==" + srs0Body;
+    var tag = _hashTag(secret, opaque);
+    var result = "SRS1=" + tag + "=" + priorForwarder + "==" + srs0Body + "@" + forwarderDomain;
+    if (result.length > 256) {                                                                     // RFC 5321 §4.5.3.1.3 path-length cap
+      throw new SrsError("srs/too-long",
+        "srs.srs1Rewrite: rewritten address exceeds the RFC 5321 256-octet path limit (forwarding chain too deep)");
+    }
+    return result;
+  }
+
   function reverse(srsAddress, nowMs) {
     validateOpts.requireNonEmptyString(
       srsAddress, "srs.reverse.address", SrsError, "srs/bad-address");
@@ -183,13 +271,15 @@ function create(opts) {
     }
     var localPart  = srsAddress.slice(0, at);
     var rcptDomain = srsAddress.slice(at + 1);
-    // Allow case-insensitive SRS0 prefix per the spec. Check this
-    // FIRST so an obviously-non-SRS0 input (`plain@example.com`)
+    // Allow case-insensitive SRS0 / SRS1 prefixes per the spec. Check
+    // this FIRST so an obviously-non-SRS input (`plain@example.com`)
     // gets the specific not-srs0 verdict instead of the more general
     // wrong-forwarder verdict.
-    if (!/^SRS0=/i.test(localPart)) {
+    var isSrs0 = /^SRS0=/i.test(localPart);
+    var isSrs1 = /^SRS1=/i.test(localPart);
+    if (!isSrs0 && !isSrs1) {
       throw new SrsError("srs/not-srs0",
-        "srs.reverse: address local-part does not start with SRS0=");
+        "srs.reverse: address local-part does not start with SRS0= or SRS1=");
     }
     // Domain binding — the rewriter is scoped to a specific forwarder
     // domain, and reverse() must verify the bounce arrived at THAT
@@ -203,6 +293,18 @@ function create(opts) {
         "srs.reverse: bounce addressed to '" + rcptDomain + "' but rewriter " +
         "is bound to forwarderDomain '" + forwarderDomain + "'");
     }
+    if (isSrs1) {
+      var s1 = _parseSrs1(localPart);
+      if (!_timingSafeStringEqual(s1.tag, _hashTag(secret, s1.priorForwarder + "==" + s1.srs0Body))) {
+        throw new SrsError("srs/bad-tag",
+          "srs.reverse: SRS1 HMAC tag does not verify (wrong secret or tampered envelope-from)");
+      }
+      // Unwrap exactly one hop: re-address the bounce to the prior
+      // forwarder's SRS0. That forwarder owns the inner SRS0's tag +
+      // expiry, so we do NOT re-check them here — per the SRS spec each
+      // hop verifies only its OWN hash.
+      return "SRS0=" + s1.srs0Body + "@" + s1.priorForwarder;
+    }
     var rest = localPart.slice(5);
     var parts = rest.split("=");
     if (parts.length < 4) {
@@ -231,8 +333,9 @@ function create(opts) {
   }
 
   return Object.freeze({
-    rewrite:  rewrite,
-    reverse:  reverse,
+    rewrite:      rewrite,
+    srs1Rewrite:  srs1Rewrite,
+    reverse:      reverse,
     forwarderDomain: forwarderDomain,
   });
 }