@learncard/sss-key-manager 0.2.7 → 0.3.0

package/dist/sss-strategy.d.ts

@@ -37,6 +37,32 @@ export interface SSSStrategyConfig {
     escrow?: {
         enabled: boolean;
         attestation: EscrowAttestationPolicy;
+        /**
+         * The escrow authority's tenant label: the enclave's measured
+         * `ESCROW_AUTHORITY_TENANT`, which it signs into every authority record and
+         * requires in every signed enrollment intent. Used for everything the
+         * enclave verifies (intent tenant, authority state, hold, code-delivery and
+         * persisted recovery expectations). Everything else (X-Tenant-Id, email
+         * branding, same-tenant guards) keeps using {@link SSSStrategyConfig.tenantId}.
+         *
+         * Defaults to `tenantId` (then `'learncard'`). Set it explicitly when this app
+         * shares another tenant's single-tenant enclave, e.g. VetPass on LearnCard's
+         * (`'learncard'`). Must match `/^[A-Za-z0-9_-]{1,128}$/`.
+         */
+        authorityTenant?: string;
+        /**
+         * Display name sealed into the escrow blob for enclave-sent emails
+         * (D21, `recoveryBrand`), e.g. `'VetPass'`. Sealed only when the
+         * recovery email and language are (nitro enroll/replace), never on a
+         * carry. Unset: the enclave brands emails from its measured tenant label.
+         *
+         * Set only after every live enclave host runs the brand-aware image: an
+         * older image drops the field whenever it re-encrypts the blob.
+         * Must pass {@link canonicalEscrowEmailBrand} (ASCII letters, digits,
+         * space, `-`, `'`, `&`; 1-32 characters); `createSSSStrategy` throws
+         * otherwise.
+         */
+        emailBrand?: string;
     };
     /** Report enrollment failures without logging recovery material. */
     onEscrowError?: (err: unknown) => void;

package/dist/sss-strategy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sss-strategy.d.ts","sourceRoot":"","sources":["../src/sss-strategy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"sss-strategy.d.ts","sourceRoot":"","sources":["../src/sss-strategy.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/sss-key-manager",
-    "version": "0.2.7",
+    "version": "0.3.0",
     "description": "Shamir Secret Sharing key manager for LearnCard - replaces Web3Auth SFA",
     "main": "./dist/index.js",
     "module": "./dist/sss-key-manager.esm.js",
@@ -39,7 +39,7 @@
         "vitest": "4.1.11"
     },
     "dependencies": {
-        "@learncard/types": "5.24.2",
+        "@learncard/types": "6.0.0",
         "@noble/ed25519": "^2.0.0",
         "@peculiar/x509": "^2.1.0",
         "@scure/bip39": "^1.2.1",

package/src/__fixtures__/escrow-authority-brand-names-v1.json

@@ -0,0 +1,29 @@
+{
+    "description": "Authority label -> fallback email brand. Rust brand_name (escrow-enclave-app/src/authority/email.rs) and TS escrowAuthorityBrandName (learn-card-base/src/config/authConfig.ts) must both map every case exactly; changing either side means updating this file.",
+    "cases": [
+        {
+            "label": "learncard",
+            "brand": "LearnCard"
+        },
+        {
+            "label": "scouts",
+            "brand": "ScoutPass"
+        },
+        {
+            "label": "vetpass",
+            "brand": "vetpass"
+        },
+        {
+            "label": "other",
+            "brand": "other"
+        },
+        {
+            "label": "LearnCard",
+            "brand": "LearnCard"
+        },
+        {
+            "label": "scoutpass",
+            "brand": "scoutpass"
+        }
+    ]
+}

package/src/__fixtures__/escrow-carry-contact-contract-v1.json

@@ -1,5 +1,5 @@
 {
-    "description": "P2-d cross-language contract: the enclave authority policy (apply_enrollment_intent, authority.rs) rejects a Carry target blob whose PLAINTEXT already carries a non-null recoveryEmail/recoveryLanguage — on carry the enclave always fills those fields in from the source blob instead — but accepts the identical blob shape for Enroll/Replace (where the signed intent is required to bind a matching contact instead). Rust (policy/authority/tests.rs) builds and submits a real target blob with each case's fields and asserts apply_enrollment_intent's accept/reject outcome through the real enclave policy; TypeScript (escrow-authority.test.ts) asserts the same outcome via resolveEscrowEnrollmentAction plus the same rule the enclave enforces. Each case is independent: did/shareVersion/epoch are illustrative, not cross-referenced. recoveryEmail/recoveryLanguage are always both-null or both-set, matching the blob plaintext's own format invariant.",
+    "description": "P2-d cross-language contract: the enclave authority policy (apply_enrollment_intent, authority.rs) rejects a Carry target blob whose PLAINTEXT already carries a non-null recoveryEmail/recoveryLanguage — on carry the enclave always fills those fields in from the source blob instead — but accepts the identical blob shape for Enroll/Replace (where the signed intent is required to bind a matching contact instead). Rust (policy/authority/tests.rs) builds and submits a real target blob with each case's fields and asserts apply_enrollment_intent's accept/reject outcome through the real enclave policy; TypeScript (escrow-authority.test.ts) asserts the same outcome via resolveEscrowEnrollmentAction plus the same rule the enclave enforces. Each case is independent: did/shareVersion/epoch are illustrative, not cross-referenced. recoveryEmail/recoveryLanguage are always both-null or both-set, matching the blob plaintext's own format invariant. D21: blobRecoveryBrand (optional; absent means null) follows the same Carry rule: a Carry target that claims a sealed email brand is refused (the enclave inherits the source's), while Enroll/Replace keep whatever brand the owner sealed (the brand is not in the signed intent).",
     "cases": [
         {
             "name": "enroll accepts a target with contact fields",
@@ -28,6 +28,30 @@
             "blobRecoveryEmail": null,
             "blobRecoveryLanguage": null,
             "expected": "accept"
+        },
+        {
+            "name": "enroll accepts a target with contact fields and a sealed brand",
+            "action": "enroll",
+            "blobRecoveryEmail": "owner@example.com",
+            "blobRecoveryLanguage": "en",
+            "blobRecoveryBrand": "VetPass",
+            "expected": "accept"
+        },
+        {
+            "name": "replace accepts a target with contact fields and a sealed brand",
+            "action": "replace",
+            "blobRecoveryEmail": "owner@example.com",
+            "blobRecoveryLanguage": "en",
+            "blobRecoveryBrand": "VetPass",
+            "expected": "accept"
+        },
+        {
+            "name": "carry rejects a target that carries only a sealed brand",
+            "action": "carry",
+            "blobRecoveryEmail": null,
+            "blobRecoveryLanguage": null,
+            "blobRecoveryBrand": "VetPass",
+            "expected": "reject"
         }
     ]
 }

package/src/__fixtures__/escrow-email-brand-contract-v1.json

@@ -0,0 +1,225 @@
+{
+    "description": "D21 cross-language contract for the owner-sealed escrow email brand (recoveryBrand). Rust canonical_brand (services/escrow-enclave-app/src/crypto.rs) and TypeScript canonicalEscrowEmailBrand (escrow-crypto.ts) must map every input to the same canonical form, or both reject it (expected: null). Rules: trim and collapse runs of ASCII space (0x20) only; any other whitespace or control character rejects; allowed characters are A-Z a-z 0-9, space, '-', ''' and '&'; first character a letter; 1-32 characters after canonicalization; at most 3 digits in total (not per run); no 'http' or 'www' in any case. Never make these rules stricter without a migration: stored blobs are re-checked on every decrypt.",
+    "cases": [
+        {
+            "name": "plain brand",
+            "input": "VetPass",
+            "expected": "VetPass"
+        },
+        {
+            "name": "LearnCard",
+            "input": "LearnCard",
+            "expected": "LearnCard"
+        },
+        {
+            "name": "ScoutPass",
+            "input": "ScoutPass",
+            "expected": "ScoutPass"
+        },
+        {
+            "name": "trims and collapses ASCII spaces",
+            "input": "  Learn   Card ",
+            "expected": "Learn Card"
+        },
+        {
+            "name": "allowed punctuation",
+            "input": "Learn-Card's & Co",
+            "expected": "Learn-Card's & Co"
+        },
+        {
+            "name": "three digits allowed",
+            "input": "Pass 123",
+            "expected": "Pass 123"
+        },
+        {
+            "name": "exactly 32 characters",
+            "input": "Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+            "expected": "Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa"
+        },
+        {
+            "name": "32 after collapsing",
+            "input": "  Aaaaaaaaaaaaaaaa    bbbbbbbbbbbbbbb ",
+            "expected": "Aaaaaaaaaaaaaaaa bbbbbbbbbbbbbbb"
+        },
+        {
+            "name": "33 characters",
+            "input": "Aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
+            "expected": null
+        },
+        {
+            "name": "empty",
+            "input": "",
+            "expected": null
+        },
+        {
+            "name": "only spaces",
+            "input": "    ",
+            "expected": null
+        },
+        {
+            "name": "leading digit",
+            "input": "1Pass",
+            "expected": null
+        },
+        {
+            "name": "leading hyphen",
+            "input": "-Pass",
+            "expected": null
+        },
+        {
+            "name": "four-digit run",
+            "input": "a1234",
+            "expected": null
+        },
+        {
+            "name": "code split by spaces",
+            "input": "Code 123 456 78",
+            "expected": null
+        },
+        {
+            "name": "phone split by hyphens",
+            "input": "A 555-123-456",
+            "expected": null
+        },
+        {
+            "name": "pin split into pairs",
+            "input": "Pin 12-34-56-78",
+            "expected": null
+        },
+        {
+            "name": "four digits apart",
+            "input": "A1 B2 C3 D4",
+            "expected": null
+        },
+        {
+            "name": "three digits apart",
+            "input": "A1 B2 C3",
+            "expected": "A1 B2 C3"
+        },
+        {
+            "name": "phone look-alike",
+            "input": "Call 5551234",
+            "expected": null
+        },
+        {
+            "name": "http substring",
+            "input": "http",
+            "expected": null
+        },
+        {
+            "name": "HTTP any case",
+            "input": "MyHttpBrand",
+            "expected": null
+        },
+        {
+            "name": "www substring",
+            "input": "Www Brand",
+            "expected": null
+        },
+        {
+            "name": "carriage return",
+            "input": "Vet\rPass",
+            "expected": null
+        },
+        {
+            "name": "line feed",
+            "input": "Vet\nPass",
+            "expected": null
+        },
+        {
+            "name": "CRLF header injection",
+            "input": "VetPass\r\nBcc: x",
+            "expected": null
+        },
+        {
+            "name": "tab",
+            "input": "Vet\tPass",
+            "expected": null
+        },
+        {
+            "name": "leading tab is not trimmed",
+            "input": "\tVetPass",
+            "expected": null
+        },
+        {
+            "name": "NBSP",
+            "input": "Vet Pass",
+            "expected": null
+        },
+        {
+            "name": "line separator",
+            "input": "Vet
Pass",
+            "expected": null
+        },
+        {
+            "name": "RLO bidi override",
+            "input": "Vet‮Pass",
+            "expected": null
+        },
+        {
+            "name": "LRI bidi isolate",
+            "input": "Vet⁦Pass",
+            "expected": null
+        },
+        {
+            "name": "zero-width space",
+            "input": "Vet​Pass",
+            "expected": null
+        },
+        {
+            "name": "Cyrillic homoglyph",
+            "input": "VеtPass",
+            "expected": null
+        },
+        {
+            "name": "accented letter",
+            "input": "Café",
+            "expected": null
+        },
+        {
+            "name": "less-than",
+            "input": "Vet<Pass",
+            "expected": null
+        },
+        {
+            "name": "double quote",
+            "input": "Vet\"Pass",
+            "expected": null
+        },
+        {
+            "name": "backslash",
+            "input": "Vet\\Pass",
+            "expected": null
+        },
+        {
+            "name": "at sign",
+            "input": "Vet@Pass",
+            "expected": null
+        },
+        {
+            "name": "dot",
+            "input": "vetpass.com",
+            "expected": null
+        },
+        {
+            "name": "slash",
+            "input": "Vet/Pass",
+            "expected": null
+        },
+        {
+            "name": "colon",
+            "input": "Vet:Pass",
+            "expected": null
+        },
+        {
+            "name": "percent",
+            "input": "Vet%Pass",
+            "expected": null
+        },
+        {
+            "name": "NUL",
+            "input": "Vet\u0000Pass",
+            "expected": null
+        }
+    ]
+}

package/src/escrow-authority.test.ts

@@ -288,6 +288,7 @@ describe('violatesCarryContactRule (P2-d cross-language contract)', () => {
                 action: 'enroll' | 'replace' | 'disable' | 'carry';
                 blobRecoveryEmail: string | null;
                 blobRecoveryLanguage: string | null;
+                blobRecoveryBrand?: string | null;
                 expected: 'accept' | 'reject';
             }[]
         ).map(c => [c.name, c] as const)
@@ -295,6 +296,7 @@ describe('violatesCarryContactRule (P2-d cross-language contract)', () => {
         const violates = violatesCarryContactRule(testCase.action, {
             recoveryEmail: testCase.blobRecoveryEmail ?? undefined,
             recoveryLanguage: testCase.blobRecoveryLanguage ?? undefined,
+            recoveryBrand: testCase.blobRecoveryBrand ?? undefined,
         });
         expect(violates).toBe(testCase.expected === 'reject');
     });

package/src/escrow-authority.ts

@@ -1,6 +1,10 @@
 import { base64ToBuffer, bufferToBase64, bytesToHex } from './crypto';
 import { parseEscrowEnvelope } from './escrow-crypto';
-import { EscrowEvidenceError } from './escrow-authority.types';
+import {
+    ESCROW_AUTHORITY_TENANT_PATTERN,
+    EscrowAuthorityTenantMismatchError,
+    EscrowEvidenceError,
+} from './escrow-authority.types';
 import type { HistoricalEscrowEvidence } from './escrow-authority.types';
 import type { EscrowAttestationPolicy } from './types';
 import {
@@ -100,6 +104,14 @@ export const verifyEscrowCodeDelivery = async (
 const requireEvidence = (condition: boolean): void => {
     if (!condition) fail();
 };
+/** Only after the signature verified: a well-formed but different signed tenant is a
+ * deployment misconfiguration (wrong `escrowAuthorityTenant`), reported specifically. */
+const requireAuthorityTenant = (signedTenant: unknown, expectedTenant: string): void => {
+    if (signedTenant === expectedTenant) return;
+    if (typeof signedTenant === 'string' && ESCROW_AUTHORITY_TENANT_PATTERN.test(signedTenant))
+        throw new EscrowAuthorityTenantMismatchError(expectedTenant, signedTenant);
+    fail();
+};
 const object = (value: unknown): Record<string, unknown> => {
     if (!value || typeof value !== 'object' || Array.isArray(value)) return fail();
     return value as Record<string, unknown>;
@@ -335,7 +347,8 @@ export const verifyEscrowAuthorityState = async (
     const { payload } = await verifyRecord(raw.proof, 'snapshot', identity);
     if (!Array.isArray(payload) || payload.length !== 2 || payload[0] !== nonce) return fail();
     const signed = state(payload[1]);
-    requireEvidence(signed.tenant === tenant && signed.did === did);
+    requireEvidence(signed.did === did);
+    requireAuthorityTenant(signed.tenant, tenant);
     requireEvidence(JSON.stringify(signed) === JSON.stringify(state(raw.state)));
     if (signed.envelope) {
         requireEvidence(
@@ -497,7 +510,8 @@ export const verifyEscrowHoldRecord = async (
     keys(commit, ['schemaVersion', 'binding', 'executionId', 'revisions', 'transactionDigest']);
     const binding = object(commit.binding);
     keys(binding, ['tenant', 'generation', 'didHash']);
-    requireEvidence(commit.schemaVersion === 1 && binding.tenant === expected.tenant);
+    requireEvidence(commit.schemaVersion === 1);
+    requireAuthorityTenant(binding.tenant, expected.tenant);
     const authorityGeneration = text(binding.generation, 128);
     if (historical) requireEvidence(authorityGeneration === historical.authorityGeneration);
     requireEvidence(bytesToHex(bytes(binding.didHash, 32)) === (await hash(utf8(expected.did))));
@@ -608,16 +622,19 @@ export const resolveEscrowEnrollmentAction = (
 /** P2-d cross-language contract: mirrors the enclave's Carry contact-field
  * rejection rule (`apply_enrollment_intent` in authority.rs) — true means
  * the enclave would refuse this target blob. The enclave always fills
- * recoveryEmail/recoveryLanguage in from the source blob on carry, so a
- * target that already claims either field is refused. Shared by
+ * recoveryEmail/recoveryLanguage (and, D21, the sealed recoveryBrand) in from
+ * the source blob on carry, so a target that already claims any of them is
+ * refused. Shared by
  * `escrow-carry-contact-contract-v1.json`'s TS and Rust tests, and by any
  * caller (e.g. a test fake) that wants to fail the same way the real
  * enclave does instead of accepting a shape it would reject. */
 export const violatesCarryContactRule = (
     action: EscrowEnrollmentIntent['action'],
-    target: Pick<EscrowBlobPlaintext, 'recoveryEmail' | 'recoveryLanguage'> | null
+    target: Pick<EscrowBlobPlaintext, 'recoveryEmail' | 'recoveryLanguage' | 'recoveryBrand'> | null
 ): boolean =>
-    action === 'carry' && !!target && (!!target.recoveryEmail || !!target.recoveryLanguage);
+    action === 'carry' &&
+    !!target &&
+    (!!target.recoveryEmail || !!target.recoveryLanguage || !!target.recoveryBrand);
 
 /** Owner-only mutation selection. Recovery itself never calls this helper.
  * P9.1 (attack C): `recoveryEmail`/`recoveryLanguage` are always supplied by the

package/src/escrow-authority.types.ts

@@ -8,6 +8,33 @@ export class EscrowEvidenceError extends Error {
     }
 }
 
+/** Shape of an escrow authority tenant label (mirrors the enclave's measured label check). */
+export const ESCROW_AUTHORITY_TENANT_PATTERN = /^[A-Za-z0-9_-]{1,128}$/;
+
+/**
+ * Validly signed evidence bound to a different authority tenant than this client expects.
+ * The enclave is single-tenant (its measured `ESCROW_AUTHORITY_TENANT` label), so this is
+ * a deployment misconfiguration, not a forgery: the app's `escrowAuthorityTenant` does not
+ * match the enclave it talks to. Still an {@link EscrowEvidenceError}, so every existing
+ * fail-closed path treats it the same way; only the message is specific. Labels are public
+ * deployment identifiers, never user data.
+ */
+export class EscrowAuthorityTenantMismatchError extends EscrowEvidenceError {
+    readonly expectedTenant: string;
+    readonly signedTenant: string;
+
+    constructor(expectedTenant: string, signedTenant: string) {
+        super();
+        this.name = 'EscrowAuthorityTenantMismatchError';
+        this.expectedTenant = expectedTenant;
+        this.signedTenant = signedTenant;
+        this.message =
+            `Escrow authority tenant mismatch: the enclave signed for "${signedTenant}" but this ` +
+            `app expects "${expectedTenant}". Set auth.sss.escrowAuthorityTenant to the ` +
+            `enclave's ESCROW_AUTHORITY_TENANT.`;
+    }
+}
+
 /** Opt-in for previously issued hold evidence only. Measurements are SHA-256
  * hashes of complete configured PCR0/1/2 tuples, never server-supplied values.
  * The original authority generation and current attested ledger key remain pinned.

package/src/escrow-crypto.test.ts

@@ -7,6 +7,7 @@ import {
     ESCROW_CLIENT_KEY_ID,
     ESCROW_ENVELOPE_VERSION,
     ESCROW_RELEASE_INFO,
+    canonicalEscrowEmailBrand,
     decryptEscrowBlob,
     encryptEscrowBlob,
     generateEscrowKeyPair,
@@ -17,6 +18,7 @@ import {
     sealEscrowRelease,
 } from './escrow-crypto';
 import type { EscrowEnvelope } from './escrow-crypto';
+import brandContract from './__fixtures__/escrow-email-brand-contract-v1.json';
 
 const blob = {
     recoveryShare: `0001${'ab'.repeat(48)}`,
@@ -379,3 +381,76 @@ describe('escrow parsing', () => {
         expect(parseEscrowReleasePlaintext(maximum)).toEqual(maximum);
     });
 });
+
+// D21 cross-language contract: the enclave's `canonical_brand` (crypto.rs)
+// loads the same fixture and must reach the identical result for each case.
+describe('escrow email brand (D21)', () => {
+    const cases = brandContract.cases as { name: string; input: string; expected: string | null }[];
+    const contact = { recoveryEmail: 'owner@example.com', recoveryLanguage: 'en' };
+
+    it.each(cases.map(c => [c.name, c] as const))('canonicalizes %s', (_name, testCase): void => {
+        expect(canonicalEscrowEmailBrand(testCase.input)).toBe(testCase.expected ?? undefined);
+        if (testCase.expected !== null) {
+            expect(canonicalEscrowEmailBrand(testCase.expected)).toBe(testCase.expected);
+        }
+    });
+
+    it.each(cases.map(c => [c.name, c] as const))(
+        'blob and release parsers keep the canonical brand or omit it, never throw: %s',
+        (_name, testCase): void => {
+            const parsed = parseEscrowBlobPlaintext({
+                ...plaintext,
+                ...contact,
+                recoveryBrand: testCase.input,
+            });
+            const released = parseEscrowReleasePlaintext({
+                ...releasePlaintext,
+                ...contact,
+                recoveryBrand: testCase.input,
+            });
+            if (testCase.expected === null) {
+                expect(parsed).not.toHaveProperty('recoveryBrand');
+                expect(released).not.toHaveProperty('recoveryBrand');
+            } else {
+                expect(parsed.recoveryBrand).toBe(testCase.expected);
+                expect(released.recoveryBrand).toBe(testCase.expected);
+            }
+        }
+    );
+
+    it.each([null, 7, ['VetPass'], { name: 'VetPass' }, true])(
+        'drops a mistyped brand %j instead of rejecting the plaintext',
+        (recoveryBrand): void => {
+            expect(parseEscrowBlobPlaintext({ ...plaintext, ...contact, recoveryBrand })).toEqual({
+                ...plaintext,
+                ...contact,
+            });
+        }
+    );
+
+    it('keeps the brand through encryptEscrowBlob/decryptEscrowBlob and sealing (regression guard: the parser used to drop unknown fields)', async (): Promise<void> => {
+        const keys = await generateEscrowKeyPair();
+        const envelope = await encryptEscrowBlob(
+            { ...blob, ...contact, recoveryBrand: '  Vet   Pass ' },
+            keys.publicKey,
+            'enclave-1'
+        );
+        expect(await decryptEscrowBlob(envelope, keys.privateKey)).toEqual({
+            ...plaintext,
+            ...contact,
+            recoveryBrand: 'Vet Pass',
+        });
+        const sealed = await sealEscrowRelease(
+            { ...release, ...contact, recoveryBrand: 'VetPass' },
+            keys.publicKey
+        );
+        expect((await openEscrowRelease(sealed, keys.privateKey)).recoveryBrand).toBe('VetPass');
+    });
+
+    it('keeps a brand with no contact (inert), matching the enclave', (): void => {
+        expect(parseEscrowBlobPlaintext({ ...plaintext, recoveryBrand: 'VetPass' })).toEqual({
+            ...plaintext,
+            recoveryBrand: 'VetPass',
+        });
+    });
+});

package/src/escrow-crypto.ts

@@ -35,7 +35,11 @@ export const RECOVERY_LANGUAGES = ['en', 'es', 'fr', 'ar'] as const;
 /** Recovery share bound to an identity and a positive share version.
  * `recoveryEmail`/`recoveryLanguage`: bound by the user's own device at
  * enrollment, never by lca-api. Always both-present or both-absent; changing
- * the address requires a fresh `replace` enrollment, not an edit. */
+ * the address requires a fresh `replace` enrollment, not an edit.
+ * `recoveryBrand` (D21): display name for enclave-sent recovery emails, sealed
+ * by the owner's device at enrollment alongside the contact. Not in the signed
+ * intent; canonical per `canonicalEscrowEmailBrand`, and silently dropped
+ * (never an error) when invalid so recovery is never refused over display text. */
 export interface EscrowBlobPlaintext {
     version: typeof ESCROW_ENVELOPE_VERSION;
     recoveryShare: string;
@@ -44,6 +48,7 @@ export interface EscrowBlobPlaintext {
     pinVerifier?: string;
     recoveryEmail?: string;
     recoveryLanguage?: string;
+    recoveryBrand?: string;
 }
 
 /** Released recovery share additionally bound to its recovery hold. */
@@ -51,6 +56,38 @@ export interface EscrowReleasePlaintext extends EscrowBlobPlaintext {
     holdId: string;
 }
 
+/** D21: longest canonical email brand, in characters (ASCII only, so also bytes). */
+export const MAX_ESCROW_EMAIL_BRAND_LENGTH = 32;
+
+/** D21: most digits an escrow email brand may contain, in total (not per run). */
+export const MAX_ESCROW_EMAIL_BRAND_DIGITS = 3;
+
+/** D21: canonical form of an owner-sealed escrow email brand, or `undefined` if
+ * it is not acceptable display text. Mirrors the enclave's `canonical_brand`
+ * (crypto.rs) exactly; both are pinned by escrow-email-brand-contract-v1.json.
+ * Trims and collapses runs of ASCII space only (every other whitespace or
+ * control character rejects); allows only `A-Z a-z 0-9`, space, `-`, `'`, `&`;
+ * must start with a letter, be 1-32 characters, contain at most 3 digits in total
+ * (not per run, so `Code 123 456 78` rejects) and no `http`/`www` in any case. ASCII-only by design: no URL, address, bidi or
+ * homoglyph can be formed, and no RFC 2047 encoding is ever needed. */
+export const canonicalEscrowEmailBrand = (raw: unknown): string | undefined => {
+    if (typeof raw !== 'string') return undefined;
+    const brand = raw
+        .split(' ')
+        .filter(word => word.length > 0)
+        .join(' ');
+    if (
+        brand.length === 0 ||
+        brand.length > MAX_ESCROW_EMAIL_BRAND_LENGTH ||
+        !/^[A-Za-z][A-Za-z0-9 '&-]*$/.test(brand) ||
+        (brand.match(/[0-9]/g)?.length ?? 0) > MAX_ESCROW_EMAIL_BRAND_DIGITS ||
+        /http|www/i.test(brand)
+    ) {
+        return undefined;
+    }
+    return brand;
+};
+
 const encodeUtf8 = (value: string): Uint8Array<ArrayBuffer> => {
     const bytes = new TextEncoder().encode(value);
     const copy = new Uint8Array(new ArrayBuffer(bytes.byteLength));
@@ -142,6 +179,10 @@ export const parseEscrowBlobPlaintext = (value: unknown): EscrowBlobPlaintext =>
         }
         recoveryContact = { recoveryEmail: email, recoveryLanguage: language };
     }
+    // D21: lenient on read, exactly like the enclave's `normalize`: an invalid
+    // or mistyped brand is omitted, never an error. Independent of the contact
+    // (kept but inert without one).
+    const recoveryBrand = canonicalEscrowEmailBrand(value.recoveryBrand);
     return {
         version: ESCROW_ENVELOPE_VERSION,
         recoveryShare: requireString(value, 'recoveryShare', {
@@ -161,6 +202,7 @@ export const parseEscrowBlobPlaintext = (value: unknown): EscrowBlobPlaintext =>
               }
             : {}),
         ...recoveryContact,
+        ...(recoveryBrand !== undefined ? { recoveryBrand } : {}),
     };
 };