@learncard/sss-key-manager 0.1.21 → 0.1.22

package/README.md

@@ -8,14 +8,14 @@ This package provides a secure, self-hosted alternative to Web3Auth Single Facto
 
 ## Features
 
--   **Key Splitting**: Split ed25519 private keys into 3 shares with 2-of-3 threshold
--   **Device Storage**: Encrypted local storage using AES-GCM with IndexedDB
--   **Server Storage**: Encrypted auth share stored on server with envelope encryption
--   **Recovery Methods**:
-    -   Password-based (Argon2id KDF)
-    -   Passkey/WebAuthn PRF (coming soon)
-    -   Backup file export/import
--   **Migration**: Seamless migration from Web3Auth SFA
+- **Key Splitting**: Split ed25519 private keys into 3 shares with 2-of-3 threshold
+- **Device Storage**: Encrypted local storage using AES-GCM with IndexedDB
+- **Server Storage**: Encrypted auth share stored on server with envelope encryption
+- **Recovery Methods**:
+    - Password-based (Argon2id KDF)
+    - Passkey/WebAuthn PRF (coming soon)
+    - Backup file export/import
+- **Migration**: Seamless migration from Web3Auth SFA
 
 ## Installation
 
@@ -115,19 +115,19 @@ const privateKey = await keyManager.recover({
 
 ## Security Model
 
--   **Device Share**: Encrypted with non-extractable AES-GCM key stored in IndexedDB
--   **Auth Share**: Server-side envelope encryption (DEK + KMS-encrypted DEK)
--   **Recovery Share**: Password-based uses Argon2id KDF with secure parameters
--   **Threshold**: Any 2 of 3 shares can reconstruct the key
+- **Device Share**: Encrypted with non-extractable AES-GCM key stored in IndexedDB
+- **Auth Share**: Server-side envelope encryption (DEK + KMS-encrypted DEK)
+- **Recovery Share**: Password-based uses Argon2id KDF with secure parameters
+- **Threshold**: Any 2 of 3 shares can reconstruct the key
 
 ## Auth Provider Support
 
 The package is designed to work with any authentication provider:
 
--   Firebase Authentication (default for production)
--   SuperTokens (recommended for self-hosting/local dev)
--   Keycloak (enterprise SSO)
--   Any OIDC-compliant provider
+- Firebase Authentication (default for production)
+- SuperTokens (recommended for self-hosting/local dev)
+- Keycloak (enterprise SSO)
+- Any OIDC-compliant provider
 
 ## API Reference
 
@@ -167,6 +167,147 @@ Exports an encrypted backup file.
 
 Returns the current security level based on configured recovery methods.
 
+## Four shares
+
+`SSS_TOTAL_SHARES = 4` and `SSS_THRESHOLD = 2`: any two shares reconstruct the private key, while one share alone reveals nothing about it.
+
+| Share          | Where it lives                                                                     | Purpose                            |
+| -------------- | ---------------------------------------------------------------------------------- | ---------------------------------- |
+| Device share   | Local IndexedDB                                                                    | Same-device sign-in                |
+| Auth share     | LearnCard API server, encrypted at rest                                            | Authenticated sign-in and recovery |
+| Recovery share | Passkey-protected server record, offline phrase, or password-encrypted backup file | User-controlled recovery           |
+| Email share    | Recovery email backup, encrypted before delivery                                   | Optional additional recovery path  |
+
+Passkeys protect the recovery share using a key derived from WebAuthn PRF output. A recovery phrase encodes the share as a mnemonic; a backup file encrypts it using Argon2id password derivation and AES-GCM, with its salt and KDF parameters stored in the file.
+
+### Server-side encryption
+
+The `lca-api` service derives an AES-256-GCM key from its server `SEED` using HKDF-SHA256, with salt `lca-auth-share-encryption` and info `v1`. Each auth-share encryption uses a fresh 12-byte IV; the stored ciphertext includes the 16-byte authentication tag.
+
+This implementation encrypts the share directly with the derived key. It does **not** generate a per-share Data Encryption Key (DEK) wrapped by a separate Key Encryption Key (KEK): the `encryptedDek` field holds the format marker `server-v1`, not a wrapped DEK. Password backup encryption and server auth-share encryption are separate mechanisms.
+
+## Key Types
+
+### ContactMethod
+
+Identifies a user by their primary contact method:
+
+```typescript
+type ContactMethodType = 'email' | 'phone';
+
+interface ContactMethod {
+    type: ContactMethodType;
+    value: string;
+}
+```
+
+### SecurityLevel
+
+Describes how well-protected a user's key is:
+
+```typescript
+type SecurityLevel = 'basic' | 'enhanced' | 'advanced';
+```
+
+- **basic** — device + server share only (no recovery method)
+- **enhanced** — at least one recovery method configured
+- **advanced** — multiple recovery methods configured
+
+### RecoveryInput
+
+What the user provides to recover their key:
+
+```typescript
+type RecoveryInput =
+    | { method: 'passkey'; credentialId: string }
+    | { method: 'phrase'; phrase: string }
+    | { method: 'backup'; fileContents: string; password: string }
+    | { method: 'email'; emailShare: string };
+```
+
+### RecoverySetupInput
+
+What the user provides to set up a new recovery method:
+
+```typescript
+type RecoverySetupInput =
+    | { method: 'passkey' }
+    | { method: 'phrase' }
+    | { method: 'backup'; password: string; did: string }
+    | { method: 'email' };
+```
+
+### BackupFile
+
+The JSON structure of a downloadable backup file:
+
+```typescript
+interface BackupFile {
+    version: 1;
+    createdAt: string;
+    primaryDid: string;
+    shareVersion?: number;
+    encryptedShare: {
+        ciphertext: string;
+        iv: string;
+        salt: string;
+        kdfParams: {
+            algorithm: 'argon2id';
+            timeCost: number;
+            memoryCost: number;
+            parallelism: number;
+        };
+    };
+}
+```
+
+## SSSStrategy
+
+The main class that implements `KeyDerivationStrategy`. It is typically instantiated by the AuthCoordinator, not directly by application code.
+
+### Configuration
+
+```typescript
+interface SSSStrategyConfig {
+    serverUrl: string;
+    enableEmailBackupShare?: boolean;
+}
+```
+
+| Option                   | Default | Description                                                            |
+| ------------------------ | ------- | ---------------------------------------------------------------------- |
+| `serverUrl`              | —       | Base URL of the lca-api server (e.g., `https://api.example.com/api`)   |
+| `enableEmailBackupShare` | `false` | Automatically send a backup share to the user's email during key setup |
+
+### Key Methods
+
+| Method                                             | Purpose                                                               |
+| -------------------------------------------------- | --------------------------------------------------------------------- |
+| `fetchServerKeyStatus(token, providerType)`        | Check if a key record exists on the server for the authenticated user |
+| `setupNewKey(token, providerType, signVp)`         | Generate a new key, split it, store shares on device and server       |
+| `reconstructKey(token, providerType)`              | Reconstruct the key from device share + auth share                    |
+| `recoverKey(token, providerType, input)`           | Recover the key using a recovery method + auth share                  |
+| `hasLocalKey()`                                    | Check if a device share exists in IndexedDB                           |
+| `clearLocalKey()`                                  | Remove the device share from IndexedDB                                |
+| `setupRecoveryMethod(params)`                      | Set up a new recovery method (passkey, phrase, backup, email)         |
+| `getAvailableRecoveryMethods(token, providerType)` | List the user's configured recovery methods                           |
+
+## API Client
+
+The `api-client.ts` module provides a typed fetch wrapper for all lca-api `/keys/*` and `/qr-login/*` routes. It is used internally by the SSS strategy but can also be used directly:
+
+```typescript
+import { createApiClient } from '@learncard/sss-key-manager';
+
+const client = createApiClient({ serverUrl: 'https://api.example.com/api' });
+
+const status = await client.getAuthShare({
+    authToken: token,
+    providerType: 'firebase',
+    contactMethod: { type: 'email', value: 'user@example.com' },
+});
+```
+
 ## License
 
 MIT

package/dist/sss-key-manager.cjs.development.js

@@ -66,6 +66,8 @@ var require_types_cjs_development = __commonJS({
       AgeRatingValidator: /* @__PURE__ */ __name(() => AgeRatingValidator, "AgeRatingValidator"),
       AlignmentTargetTypeValidator: /* @__PURE__ */ __name(() => AlignmentTargetTypeValidator, "AlignmentTargetTypeValidator"),
       AlignmentValidator: /* @__PURE__ */ __name(() => AlignmentValidator, "AlignmentValidator"),
+      AllocateCredentialRefreshInputValidator: /* @__PURE__ */ __name(() => AllocateCredentialRefreshInputValidator, "AllocateCredentialRefreshInputValidator"),
+      AllocateCredentialRefreshResultValidator: /* @__PURE__ */ __name(() => AllocateCredentialRefreshResultValidator, "AllocateCredentialRefreshResultValidator"),
       AllocateCredentialStatusInputValidator: /* @__PURE__ */ __name(() => AllocateCredentialStatusInputValidator, "AllocateCredentialStatusInputValidator"),
       AllocatedBitstringStatusListEntryValidator: /* @__PURE__ */ __name(() => AllocatedBitstringStatusListEntryValidator, "AllocatedBitstringStatusListEntryValidator"),
       AllowConnectionRequestsEnum: /* @__PURE__ */ __name(() => AllowConnectionRequestsEnum, "AllowConnectionRequestsEnum"),
@@ -147,6 +149,16 @@ var require_types_cjs_development = __commonJS({
       CredentialInfoValidator: /* @__PURE__ */ __name(() => CredentialInfoValidator, "CredentialInfoValidator"),
       CredentialNameRefValidator: /* @__PURE__ */ __name(() => CredentialNameRefValidator, "CredentialNameRefValidator"),
       CredentialRecordValidator: /* @__PURE__ */ __name(() => CredentialRecordValidator, "CredentialRecordValidator"),
+      CredentialRefreshChallengeValidator: /* @__PURE__ */ __name(() => CredentialRefreshChallengeValidator, "CredentialRefreshChallengeValidator"),
+      CredentialRefreshFailedResultValidator: /* @__PURE__ */ __name(() => CredentialRefreshFailedResultValidator, "CredentialRefreshFailedResultValidator"),
+      CredentialRefreshFailureCodeValidator: /* @__PURE__ */ __name(() => CredentialRefreshFailureCodeValidator, "CredentialRefreshFailureCodeValidator"),
+      CredentialRefreshResponseEnvelopeValidator: /* @__PURE__ */ __name(() => CredentialRefreshResponseEnvelopeValidator, "CredentialRefreshResponseEnvelopeValidator"),
+      CredentialRefreshResultValidator: /* @__PURE__ */ __name(() => CredentialRefreshResultValidator, "CredentialRefreshResultValidator"),
+      CredentialRefreshSigningModeValidator: /* @__PURE__ */ __name(() => CredentialRefreshSigningModeValidator, "CredentialRefreshSigningModeValidator"),
+      CredentialRefreshUnchangedResultValidator: /* @__PURE__ */ __name(() => CredentialRefreshUnchangedResultValidator, "CredentialRefreshUnchangedResultValidator"),
+      CredentialRefreshUnsupportedResultValidator: /* @__PURE__ */ __name(() => CredentialRefreshUnsupportedResultValidator, "CredentialRefreshUnsupportedResultValidator"),
+      CredentialRefreshUpdatedResultValidator: /* @__PURE__ */ __name(() => CredentialRefreshUpdatedResultValidator, "CredentialRefreshUpdatedResultValidator"),
+      CredentialRefreshVersionMetadataValidator: /* @__PURE__ */ __name(() => CredentialRefreshVersionMetadataValidator, "CredentialRefreshVersionMetadataValidator"),
       CredentialSchemaValidator: /* @__PURE__ */ __name(() => CredentialSchemaValidator, "CredentialSchemaValidator"),
       CredentialStatusValidator: /* @__PURE__ */ __name(() => CredentialStatusValidator, "CredentialStatusValidator"),
       CredentialSubjectValidator: /* @__PURE__ */ __name(() => CredentialSubjectValidator, "CredentialSubjectValidator"),
@@ -167,6 +179,8 @@ var require_types_cjs_development = __commonJS({
       GeoCoordinatesValidator: /* @__PURE__ */ __name(() => GeoCoordinatesValidator, "GeoCoordinatesValidator"),
       GetCounterEventValidator: /* @__PURE__ */ __name(() => GetCounterEventValidator, "GetCounterEventValidator"),
       GetCountersEventValidator: /* @__PURE__ */ __name(() => GetCountersEventValidator, "GetCountersEventValidator"),
+      GetCredentialRefreshHistoryInputValidator: /* @__PURE__ */ __name(() => GetCredentialRefreshHistoryInputValidator, "GetCredentialRefreshHistoryInputValidator"),
+      GetCredentialRefreshHistoryResultValidator: /* @__PURE__ */ __name(() => GetCredentialRefreshHistoryResultValidator, "GetCredentialRefreshHistoryResultValidator"),
       GetFullSkillTreeInputValidator: /* @__PURE__ */ __name(() => GetFullSkillTreeInputValidator, "GetFullSkillTreeInputValidator"),
       GetFullSkillTreeResultValidator: /* @__PURE__ */ __name(() => GetFullSkillTreeResultValidator, "GetFullSkillTreeResultValidator"),
       GetSkillPathInputValidator: /* @__PURE__ */ __name(() => GetSkillPathInputValidator, "GetSkillPathInputValidator"),
@@ -191,6 +205,7 @@ var require_types_cjs_development = __commonJS({
       JWEValidator: /* @__PURE__ */ __name(() => JWEValidator, "JWEValidator"),
       JWKValidator: /* @__PURE__ */ __name(() => JWKValidator, "JWKValidator"),
       JWKWithPrivateKeyValidator: /* @__PURE__ */ __name(() => JWKWithPrivateKeyValidator, "JWKWithPrivateKeyValidator"),
+      JweCredentialRefreshEnvelopeValidator: /* @__PURE__ */ __name(() => JweCredentialRefreshEnvelopeValidator, "JweCredentialRefreshEnvelopeValidator"),
       KnownAchievementTypeValidator: /* @__PURE__ */ __name(() => KnownAchievementTypeValidator, "KnownAchievementTypeValidator"),
       LCNAuthedProfileValidator: /* @__PURE__ */ __name(() => LCNAuthedProfileValidator, "LCNAuthedProfileValidator"),
       LCNBoostClaimLinkOptionsValidator: /* @__PURE__ */ __name(() => LCNBoostClaimLinkOptionsValidator, "LCNBoostClaimLinkOptionsValidator"),
@@ -228,7 +243,9 @@ var require_types_cjs_development = __commonJS({
       LCNSigningAuthorityValidator: /* @__PURE__ */ __name(() => LCNSigningAuthorityValidator, "LCNSigningAuthorityValidator"),
       LCNVisibleProfileValidator: /* @__PURE__ */ __name(() => LCNVisibleProfileValidator, "LCNVisibleProfileValidator"),
       LaunchTypeValidator: /* @__PURE__ */ __name(() => LaunchTypeValidator, "LaunchTypeValidator"),
+      LearnCardRefreshAuthorizationValidator: /* @__PURE__ */ __name(() => LearnCardRefreshAuthorizationValidator, "LearnCardRefreshAuthorizationValidator"),
       LinkProviderFrameworkInputValidator: /* @__PURE__ */ __name(() => LinkProviderFrameworkInputValidator, "LinkProviderFrameworkInputValidator"),
+      ManagedCredentialRefreshServiceValidator: /* @__PURE__ */ __name(() => ManagedCredentialRefreshServiceValidator, "ManagedCredentialRefreshServiceValidator"),
       PaginatedAppStoreListingsValidator: /* @__PURE__ */ __name(() => PaginatedAppStoreListingsValidator, "PaginatedAppStoreListingsValidator"),
       PaginatedBoostRecipientsValidator: /* @__PURE__ */ __name(() => PaginatedBoostRecipientsValidator, "PaginatedBoostRecipientsValidator"),
       PaginatedBoostRecipientsWithChildrenValidator: /* @__PURE__ */ __name(() => PaginatedBoostRecipientsWithChildrenValidator, "PaginatedBoostRecipientsWithChildrenValidator"),
@@ -258,6 +275,12 @@ var require_types_cjs_development = __commonJS({
       ProfileVisibilityEnum: /* @__PURE__ */ __name(() => ProfileVisibilityEnum, "ProfileVisibilityEnum"),
       PromotionLevelValidator: /* @__PURE__ */ __name(() => PromotionLevelValidator, "PromotionLevelValidator"),
       ProofValidator: /* @__PURE__ */ __name(() => ProofValidator, "ProofValidator"),
+      PublicCredentialRefreshEnvelopeValidator: /* @__PURE__ */ __name(() => PublicCredentialRefreshEnvelopeValidator, "PublicCredentialRefreshEnvelopeValidator"),
+      PublishCredentialRefreshInputValidator: /* @__PURE__ */ __name(() => PublishCredentialRefreshInputValidator, "PublishCredentialRefreshInputValidator"),
+      PublishCredentialRefreshNotificationValidator: /* @__PURE__ */ __name(() => PublishCredentialRefreshNotificationValidator, "PublishCredentialRefreshNotificationValidator"),
+      PublishCredentialRefreshResultValidator: /* @__PURE__ */ __name(() => PublishCredentialRefreshResultValidator, "PublishCredentialRefreshResultValidator"),
+      PublishIssuerSignedRefreshValidator: /* @__PURE__ */ __name(() => PublishIssuerSignedRefreshValidator, "PublishIssuerSignedRefreshValidator"),
+      PublishSigningAuthorityRefreshValidator: /* @__PURE__ */ __name(() => PublishSigningAuthorityRefreshValidator, "PublishSigningAuthorityRefreshValidator"),
       RefreshServiceValidator: /* @__PURE__ */ __name(() => RefreshServiceValidator, "RefreshServiceValidator"),
       RegExpValidator: /* @__PURE__ */ __name(() => RegExpValidator, "RegExpValidator"),
       RelatedValidator: /* @__PURE__ */ __name(() => RelatedValidator, "RelatedValidator"),
@@ -298,11 +321,13 @@ var require_types_cjs_development = __commonJS({
       SkillTreeNodeInputValidator: /* @__PURE__ */ __name(() => SkillTreeNodeInputValidator, "SkillTreeNodeInputValidator"),
       SkillTreeNodeValidator: /* @__PURE__ */ __name(() => SkillTreeNodeValidator, "SkillTreeNodeValidator"),
       SkillValidator: /* @__PURE__ */ __name(() => SkillValidator, "SkillValidator"),
+      StandardCredentialRefreshServiceValidator: /* @__PURE__ */ __name(() => StandardCredentialRefreshServiceValidator, "StandardCredentialRefreshServiceValidator"),
       StatusCheckEntryValidator: /* @__PURE__ */ __name(() => StatusCheckEntryValidator, "StatusCheckEntryValidator"),
       StoredCredentialEnvelopeValidator: /* @__PURE__ */ __name(() => StoredCredentialEnvelopeValidator, "StoredCredentialEnvelopeValidator"),
       StringQuery: /* @__PURE__ */ __name(() => StringQuery, "StringQuery"),
       SummaryCredentialDataValidator: /* @__PURE__ */ __name(() => SummaryCredentialDataValidator, "SummaryCredentialDataValidator"),
       SummaryCredentialKeywordValidator: /* @__PURE__ */ __name(() => SummaryCredentialKeywordValidator, "SummaryCredentialKeywordValidator"),
+      SupportedCredentialRefreshServiceValidator: /* @__PURE__ */ __name(() => SupportedCredentialRefreshServiceValidator, "SupportedCredentialRefreshServiceValidator"),
       SyncFrameworkInputValidator: /* @__PURE__ */ __name(() => SyncFrameworkInputValidator, "SyncFrameworkInputValidator"),
       TagValidator: /* @__PURE__ */ __name(() => TagValidator, "TagValidator"),
       TemplateRenderMethodValidator: /* @__PURE__ */ __name(() => TemplateRenderMethodValidator, "TemplateRenderMethodValidator"),
@@ -16506,7 +16531,10 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       webhookUrl: external_exports.string().url().optional().describe("Webhook URL to receive claim notifications"),
       suppressDelivery: external_exports.boolean().optional().describe("If true, returns claimUrl without sending email/SMS"),
       branding: SendBrandingOptionsValidator.optional().describe("Branding for email/SMS delivery"),
-      guardianEmail: external_exports.string().email().optional().describe("Guardian email that must approve before student can claim")
+      guardianEmail: external_exports.string().email().optional().describe("Guardian email that must approve before student can claim"),
+      expiresInDays: external_exports.number().int().min(1).max(720).optional().describe(
+        "How many days the credential stays claimable in the Universal Inbox (default 30). Does not change the credential validity period."
+      )
     });
     var SendBoostInputValidator = external_exports.object({
       type: external_exports.literal("boost"),
@@ -16801,7 +16829,8 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       "APP_NOTIFICATION",
       "CREDENTIAL_REVOKED",
       "CREDENTIAL_SUSPENDED",
-      "CREDENTIAL_UNSUSPENDED"
+      "CREDENTIAL_UNSUSPENDED",
+      "CREDENTIAL_REFRESHED"
     ]);
     var LCNNotificationMessageValidator = external_exports.object({
       title: external_exports.string().optional(),
@@ -16933,12 +16962,16 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
     });
     var InboxCredentialValidator = external_exports.object({
       id: external_exports.string(),
-      credential: external_exports.string(),
+      credential: external_exports.string().optional(),
       isSigned: external_exports.boolean(),
       currentStatus: LCNInboxStatusEnumValidator,
       isAccepted: external_exports.boolean().optional(),
       expiresAt: external_exports.string(),
       createdAt: external_exports.string(),
+      finalizedAt: external_exports.string().optional(),
+      expiredAt: external_exports.string().optional(),
+      credentialName: external_exports.string().optional(),
+      achievementType: external_exports.string().optional(),
       issuerDid: external_exports.string(),
       webhookUrl: external_exports.string().optional(),
       boostUri: external_exports.string().optional(),
@@ -16992,7 +17025,9 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
           "The signing authority to use for the credential. If not provided, the users default signing authority will be used if the credential is not signed."
         ),
         webhookUrl: external_exports.string().url().optional().describe("The webhook URL to receive credential issuance events."),
-        expiresInDays: external_exports.number().min(1).max(365).optional().describe("The number of days the credential will be valid for."),
+        expiresInDays: external_exports.number().int().min(1).max(720).optional().describe(
+          "How many days the encrypted inbox payload remains claimable. This does not change the credential validity period."
+        ),
         templateData: external_exports.record(external_exports.string(), external_exports.unknown()).optional().describe(
           "Template data to render into the boost credential template using Mustache syntax. Only used when boostUri is provided."
         ),
@@ -17055,6 +17090,9 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       credential: VCValidator.or(VPValidator).or(UnsignedVCValidator).or(CredentialNameRefValidator).describe("The credential to issue, or a { name } reference to resolve a boost template."),
       configuration: external_exports.object({
         publishableKey: external_exports.string(),
+        expiresInDays: external_exports.number().int().min(1).max(720).optional().describe(
+          "Inbox claim window in days. Defaults to 720; use a shorter window for sensitive records."
+        ),
         signingAuthorityName: external_exports.string().optional(),
         listingId: external_exports.string().optional(),
         listingSlug: external_exports.string().optional()
@@ -17692,6 +17730,191 @@ Set the \`cycles\` parameter to \`"ref"\` to resolve cyclical schemas with defs.
       const result = inAppMessagesFlagValidator.safeParse(raw);
       return result.success ? result.data : EMPTY_IN_APP_MESSAGES_FLAG;
     }, "parseInAppMessagesFlag");
+    var LearnCardRefreshAuthorizationValidator = external_exports.object({ type: external_exports.literal("LearnCardDIDAuth") }).catchall(external_exports.any());
+    var ManagedCredentialRefreshServiceValidator = external_exports.object({
+      id: external_exports.string().min(1),
+      type: external_exports.literal("LearnCardCredentialRefresh2026"),
+      authorization: LearnCardRefreshAuthorizationValidator.optional()
+    }).catchall(external_exports.any());
+    var StandardCredentialRefreshServiceValidator = external_exports.object({
+      id: external_exports.string().min(1),
+      type: external_exports.literal("1EdTechCredentialRefresh")
+    }).catchall(external_exports.any());
+    var SupportedCredentialRefreshServiceValidator = external_exports.union([
+      ManagedCredentialRefreshServiceValidator,
+      StandardCredentialRefreshServiceValidator
+    ]);
+    var AllocateCredentialRefreshInputValidator = external_exports.object({
+      holder: external_exports.object({
+        profileId: external_exports.string().optional(),
+        did: external_exports.string().min(1)
+      }),
+      credentialId: external_exports.string().min(1)
+    });
+    var AllocateCredentialRefreshResultValidator = external_exports.object({
+      refreshId: external_exports.string().min(1),
+      refreshService: ManagedCredentialRefreshServiceValidator.extend({
+        authorization: LearnCardRefreshAuthorizationValidator
+      })
+    });
+    var CredentialRefreshSigningModeValidator = external_exports.enum(["issuer-signed", "signing-authority"]);
+    var PublishCredentialRefreshBaseFields = {
+      refreshId: external_exports.string().min(1),
+      notifyHolder: external_exports.boolean().optional(),
+      updateSummary: external_exports.string().optional(),
+      idempotencyKey: external_exports.string().optional()
+    };
+    var PublishIssuerSignedRefreshValidator = external_exports.object({
+      ...PublishCredentialRefreshBaseFields,
+      mode: external_exports.literal("issuer-signed"),
+      signedCredential: VCValidator
+    });
+    var PublishSigningAuthorityRefreshValidator = external_exports.object({
+      ...PublishCredentialRefreshBaseFields,
+      mode: external_exports.literal("signing-authority"),
+      credential: UnsignedVCValidator,
+      signingAuthority: external_exports.object({
+        type: external_exports.string().min(1)
+      }).catchall(external_exports.any())
+    });
+    var PublishCredentialRefreshInputValidator = external_exports.object({
+      ...PublishCredentialRefreshBaseFields,
+      mode: CredentialRefreshSigningModeValidator,
+      signedCredential: VCValidator.optional(),
+      credential: UnsignedVCValidator.optional(),
+      signingAuthority: external_exports.object({
+        type: external_exports.string().min(1)
+      }).catchall(external_exports.any()).optional()
+    }).superRefine((input, ctx) => {
+      if (input.mode === "issuer-signed" && !input.signedCredential) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["signedCredential"],
+          message: "signedCredential is required for issuer-signed publication"
+        });
+      }
+      if (input.mode === "issuer-signed" && (input.credential !== void 0 || input.signingAuthority !== void 0)) {
+        ctx.addIssue({
+          code: "custom",
+          path: ["mode"],
+          message: "issuer-signed publication cannot include signing-authority fields"
+        });
+      }
+      if (input.mode === "signing-authority") {
+        if (input.signedCredential !== void 0) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["signedCredential"],
+            message: "signing-authority publication cannot include signedCredential"
+          });
+        }
+        if (!input.credential) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["credential"],
+            message: "credential is required for signing-authority publication"
+          });
+        }
+        if (!input.signingAuthority) {
+          ctx.addIssue({
+            code: "custom",
+            path: ["signingAuthority"],
+            message: "signingAuthority is required for signing-authority publication"
+          });
+        }
+      }
+    });
+    var PublishCredentialRefreshNotificationValidator = external_exports.enum([
+      "queued",
+      "suppressed",
+      "not-applicable",
+      /** Publication succeeded, but the post-commit notification enqueue must be retried. */
+      "delivery-failed"
+    ]);
+    var PublishCredentialRefreshResultValidator = external_exports.object({
+      refreshId: external_exports.string().min(1),
+      version: external_exports.number().int().positive(),
+      publishedAt: external_exports.string().min(1),
+      notification: PublishCredentialRefreshNotificationValidator
+    });
+    var CredentialRefreshVersionMetadataValidator = external_exports.object({
+      version: external_exports.number().int().positive(),
+      publishedAt: external_exports.string().min(1),
+      effectiveAt: external_exports.string().optional(),
+      etag: external_exports.string().optional(),
+      signingMode: CredentialRefreshSigningModeValidator.optional(),
+      updateSummary: external_exports.string().optional()
+    });
+    var GetCredentialRefreshHistoryInputValidator = external_exports.object({
+      refreshId: external_exports.string().min(1),
+      cursor: external_exports.string().optional(),
+      limit: external_exports.number().int().positive().optional()
+    });
+    var GetCredentialRefreshHistoryResultValidator = external_exports.object({
+      records: CredentialRefreshVersionMetadataValidator.array(),
+      hasMore: external_exports.boolean(),
+      cursor: external_exports.string().optional()
+    });
+    var CredentialRefreshChallengeValidator = external_exports.object({
+      challenge: external_exports.string().min(1),
+      expiresAt: external_exports.string().min(1),
+      domain: external_exports.string().optional(),
+      scheme: external_exports.literal("LearnCardDIDAuth").optional()
+    });
+    var PublicCredentialRefreshEnvelopeValidator = external_exports.object({
+      format: external_exports.literal("vc"),
+      credential: VCValidator,
+      etag: external_exports.string().optional()
+    });
+    var JweCredentialRefreshEnvelopeValidator = external_exports.object({
+      format: external_exports.literal("jwe"),
+      jwe: JWEValidator,
+      etag: external_exports.string().optional(),
+      /** Present on LearnCard-managed endpoints; optional for interoperable JWE services. */
+      version: external_exports.number().int().positive().optional()
+    });
+    var CredentialRefreshResponseEnvelopeValidator = external_exports.discriminatedUnion("format", [
+      PublicCredentialRefreshEnvelopeValidator,
+      JweCredentialRefreshEnvelopeValidator
+    ]);
+    var CredentialRefreshFailureCodeValidator = external_exports.enum([
+      "UNAVAILABLE",
+      "TIMEOUT",
+      "UNSUPPORTED_SERVICE",
+      "UNAUTHORIZED",
+      "MALFORMED_RESPONSE",
+      "INVALID_PROOF",
+      "ISSUER_MISMATCH",
+      "ID_MISMATCH",
+      "ROLLBACK",
+      "REVOKED",
+      "UNSAFE_ENDPOINT"
+    ]);
+    var CredentialRefreshUpdatedResultValidator = external_exports.object({
+      status: external_exports.literal("updated"),
+      credential: VCValidator,
+      etag: external_exports.string().optional(),
+      managedVersion: external_exports.number().int().positive().optional()
+    });
+    var CredentialRefreshUnchangedResultValidator = external_exports.object({
+      status: external_exports.literal("unchanged"),
+      checkedAt: external_exports.string().min(1),
+      etag: external_exports.string().optional()
+    });
+    var CredentialRefreshUnsupportedResultValidator = external_exports.object({
+      status: external_exports.literal("unsupported")
+    });
+    var CredentialRefreshFailedResultValidator = external_exports.object({
+      status: external_exports.literal("failed"),
+      code: CredentialRefreshFailureCodeValidator,
+      retryable: external_exports.boolean()
+    });
+    var CredentialRefreshResultValidator = external_exports.discriminatedUnion("status", [
+      CredentialRefreshUpdatedResultValidator,
+      CredentialRefreshUnchangedResultValidator,
+      CredentialRefreshUnsupportedResultValidator,
+      CredentialRefreshFailedResultValidator
+    ]);
   }
 });