@learncard/sss-key-manager 0.2.6 → 0.3.0

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 } : {}),
     };
 };
 

package/src/escrow-enrollment-intent.ts

@@ -1,6 +1,7 @@
 import { ExtendedPoint, getPublicKeyAsync, signAsync } from '@noble/ed25519';
 import { base64ToBuffer, bufferToBase64, bytesToHex, hexToBytes } from './crypto';
 import { parseEscrowEnvelope } from './escrow-crypto';
+import { ESCROW_AUTHORITY_TENANT_PATTERN } from './escrow-authority.types';
 import type { EscrowEnvelope } from './escrow-crypto';
 import type {
     EscrowEnrollmentIntent,
@@ -101,7 +102,7 @@ export const encodeEscrowEnrollmentIntent = (
             FIELDS.every(field => Object.prototype.hasOwnProperty.call(intent, field))
     );
     requireIntent(intent.version === 2 && typeof intent.allowRewrap === 'boolean');
-    requireIntent(matches(intent.tenant, /^[A-Za-z0-9_-]{1,128}$/));
+    requireIntent(matches(intent.tenant, ESCROW_AUTHORITY_TENANT_PATTERN));
     requireIntent(matches(intent.authorityGeneration, /^[A-Za-z0-9_-]{1,128}$/));
     requireIntent(matches(intent.requestId, /^[A-Za-z0-9._-]{1,112}$/));
     didPublicKey(intent.did);

package/src/index.ts

@@ -68,6 +68,9 @@ export {
     parseEscrowEnvelope,
     parseEscrowBlobPlaintext,
     parseEscrowReleasePlaintext,
+    canonicalEscrowEmailBrand,
+    MAX_ESCROW_EMAIL_BRAND_LENGTH,
+    MAX_ESCROW_EMAIL_BRAND_DIGITS,
     generateEscrowKeyPair,
     encryptEscrowBlob,
     decryptEscrowBlob,
@@ -87,7 +90,11 @@ export type {
     SignedEscrowEnrollmentIntent,
 } from './escrow-enrollment-intent.types';
 export { verifyEnclaveAttestation } from './escrow-attestation';
-export { EscrowEvidenceError } from './escrow-authority.types';
+export {
+    EscrowEvidenceError,
+    EscrowAuthorityTenantMismatchError,
+    ESCROW_AUTHORITY_TENANT_PATTERN,
+} from './escrow-authority.types';
 export type { HistoricalEscrowEvidence } from './escrow-authority.types';
 export type { EscrowRecoveryExpectations } from '@learncard/types';
 export {
@@ -108,7 +115,12 @@ export type {
 } from './escrow-authority.types';
 export { verifyNitroAttestationDocument, NitroAttestationError } from './escrow-nitro-attestation';
 export type { NitroAttestationReason } from './escrow-nitro-attestation';
-export type { EscrowAttestationPolicy, EscrowHoldStatus, EscrowRecoveryStart } from './types';
+export type {
+    EscrowAttestationPolicy,
+    EscrowHoldStatus,
+    EscrowPinAttemptContext,
+    EscrowRecoveryStart,
+} from './types';
 export type {
     EscrowEnrollmentOptions,
     EscrowEnrollmentState,