@learncard/types 5.18.3 → 5.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@learncard/types",
-    "version": "5.18.3",
+    "version": "5.19.0",
     "description": "Shared types for learn card",
     "type": "module",
     "main": "./dist/index.cjs",

package/src/credential-refresh.ts

@@ -0,0 +1,336 @@
+import { z } from 'zod/v4';
+
+import { UnsignedVCValidator, VCValidator } from './vc';
+import { JWEValidator } from './crypto';
+
+/**
+ * Shared contracts for managed credential refresh (LC-2117, LC-2135, LC-2136).
+ *
+ * The generic `RefreshServiceValidator` in vc.ts intentionally remains permissive so
+ * unknown third-party refresh services keep parsing. These validators model the
+ * LearnCard-managed `LearnCardCredentialRefresh2026` service, its allocation/publication
+ * lifecycle, the holder-facing response envelopes, and safe refresh outcomes.
+ */
+
+/** LearnCard DID-auth extension descriptor for a managed refresh service */
+export const LearnCardRefreshAuthorizationValidator = z
+    .object({ type: z.literal('LearnCardDIDAuth') })
+    .catchall(z.any());
+export type LearnCardRefreshAuthorization = z.infer<typeof LearnCardRefreshAuthorizationValidator>;
+
+/**
+ * Managed refresh service descriptor.
+ *
+ * Requires a resolvable `id` and the versioned LearnCard type, and optionally carries a
+ * LearnCard authorization descriptor. This is distinct from the 1EdTech protocol.
+ */
+export const ManagedCredentialRefreshServiceValidator = z
+    .object({
+        id: z.string().min(1),
+        type: z.literal('LearnCardCredentialRefresh2026'),
+        authorization: LearnCardRefreshAuthorizationValidator.optional(),
+    })
+    .catchall(z.any());
+export type ManagedCredentialRefreshService = z.infer<
+    typeof ManagedCredentialRefreshServiceValidator
+>;
+
+/** Standard 1EdTech protocol: HTTPS GET returning a signed VC or VC-JWT. */
+export const StandardCredentialRefreshServiceValidator = z
+    .object({
+        id: z.string().min(1),
+        type: z.literal('1EdTechCredentialRefresh'),
+    })
+    .catchall(z.any());
+export const SupportedCredentialRefreshServiceValidator = z.union([
+    ManagedCredentialRefreshServiceValidator,
+    StandardCredentialRefreshServiceValidator,
+]);
+export type SupportedCredentialRefreshService = z.infer<
+    typeof SupportedCredentialRefreshServiceValidator
+>;
+
+// --- Allocation (before signing) -------------------------------------------
+
+export const AllocateCredentialRefreshInputValidator = z.object({
+    holder: z.object({
+        profileId: z.string().optional(),
+        did: z.string().min(1),
+    }),
+    credentialId: z.string().min(1),
+});
+export type AllocateCredentialRefreshInput = z.infer<
+    typeof AllocateCredentialRefreshInputValidator
+>;
+
+export const AllocateCredentialRefreshResultValidator = z.object({
+    refreshId: z.string().min(1),
+    refreshService: ManagedCredentialRefreshServiceValidator.extend({
+        authorization: LearnCardRefreshAuthorizationValidator,
+    }),
+});
+export type AllocateCredentialRefreshResult = z.infer<
+    typeof AllocateCredentialRefreshResultValidator
+>;
+
+// --- Publication ------------------------------------------------------------
+
+export const CredentialRefreshSigningModeValidator = z.enum(['issuer-signed', 'signing-authority']);
+export type CredentialRefreshSigningMode = z.infer<typeof CredentialRefreshSigningModeValidator>;
+
+const PublishCredentialRefreshBaseFields = {
+    refreshId: z.string().min(1),
+    notifyHolder: z.boolean().optional(),
+    updateSummary: z.string().optional(),
+    idempotencyKey: z.string().optional(),
+};
+
+/** Issuer-signed mode: the caller supplies a fully signed updated VC */
+export const PublishIssuerSignedRefreshValidator = z.object({
+    ...PublishCredentialRefreshBaseFields,
+    mode: z.literal('issuer-signed'),
+    signedCredential: VCValidator,
+});
+export type PublishIssuerSignedRefresh = z.infer<typeof PublishIssuerSignedRefreshValidator>;
+
+/** Signing-authority mode: the caller supplies updated unsigned claims and brain-service signs */
+export const PublishSigningAuthorityRefreshValidator = z.object({
+    ...PublishCredentialRefreshBaseFields,
+    mode: z.literal('signing-authority'),
+    credential: UnsignedVCValidator,
+    signingAuthority: z
+        .object({
+            type: z.string().min(1),
+        })
+        .catchall(z.any()),
+});
+export type PublishSigningAuthorityRefresh = z.infer<
+    typeof PublishSigningAuthorityRefreshValidator
+>;
+
+/**
+ * Top-level object form required by trpc-to-openapi.
+ *
+ * Keep the public TypeScript type discriminated even though the runtime object has
+ * optional fields for both modes. The refinement preserves the same required-field
+ * behavior as the former z.discriminatedUnion without crashing OpenAPI generation.
+ */
+export const PublishCredentialRefreshInputValidator = z
+    .object({
+        ...PublishCredentialRefreshBaseFields,
+        mode: CredentialRefreshSigningModeValidator,
+        signedCredential: VCValidator.optional(),
+        credential: UnsignedVCValidator.optional(),
+        signingAuthority: z
+            .object({
+                type: z.string().min(1),
+            })
+            .catchall(z.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 !== undefined || input.signingAuthority !== undefined)
+        ) {
+            ctx.addIssue({
+                code: 'custom',
+                path: ['mode'],
+                message: 'issuer-signed publication cannot include signing-authority fields',
+            });
+        }
+
+        if (input.mode === 'signing-authority') {
+            if (input.signedCredential !== undefined) {
+                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',
+                });
+            }
+        }
+    });
+export type PublishCredentialRefreshInput =
+    PublishIssuerSignedRefresh | PublishSigningAuthorityRefresh;
+
+export const PublishCredentialRefreshNotificationValidator = z.enum([
+    'queued',
+    'suppressed',
+    'not-applicable',
+    /** Publication succeeded, but the post-commit notification enqueue must be retried. */
+    'delivery-failed',
+]);
+export type PublishCredentialRefreshNotification = z.infer<
+    typeof PublishCredentialRefreshNotificationValidator
+>;
+
+export const PublishCredentialRefreshResultValidator = z.object({
+    refreshId: z.string().min(1),
+    version: z.number().int().positive(),
+    publishedAt: z.string().min(1),
+    notification: PublishCredentialRefreshNotificationValidator,
+});
+export type PublishCredentialRefreshResult = z.infer<
+    typeof PublishCredentialRefreshResultValidator
+>;
+
+// --- Version history (metadata only, never credential bodies) ----------------
+
+export const CredentialRefreshVersionMetadataValidator = z.object({
+    version: z.number().int().positive(),
+    publishedAt: z.string().min(1),
+    effectiveAt: z.string().optional(),
+    etag: z.string().optional(),
+    signingMode: CredentialRefreshSigningModeValidator.optional(),
+    updateSummary: z.string().optional(),
+});
+export type CredentialRefreshVersionMetadata = z.infer<
+    typeof CredentialRefreshVersionMetadataValidator
+>;
+
+export const GetCredentialRefreshHistoryInputValidator = z.object({
+    refreshId: z.string().min(1),
+    cursor: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+});
+export type GetCredentialRefreshHistoryInput = z.infer<
+    typeof GetCredentialRefreshHistoryInputValidator
+>;
+
+export const GetCredentialRefreshHistoryResultValidator = z.object({
+    records: CredentialRefreshVersionMetadataValidator.array(),
+    hasMore: z.boolean(),
+    cursor: z.string().optional(),
+});
+export type GetCredentialRefreshHistoryResult = z.infer<
+    typeof GetCredentialRefreshHistoryResultValidator
+>;
+
+// --- Holder authentication challenge ------------------------------------------
+
+/**
+ * Short-lived, single-use challenge returned by a managed refresh endpoint. Contains
+ * no holder, issuer, credential, or lifecycle information.
+ */
+export const CredentialRefreshChallengeValidator = z.object({
+    challenge: z.string().min(1),
+    expiresAt: z.string().min(1),
+    domain: z.string().optional(),
+    scheme: z.literal('LearnCardDIDAuth').optional(),
+});
+export type CredentialRefreshChallenge = z.infer<typeof CredentialRefreshChallengeValidator>;
+
+// --- Response envelopes --------------------------------------------------------
+
+/** Plain (interoperable) response: an unencrypted signed VC */
+export const PublicCredentialRefreshEnvelopeValidator = z.object({
+    format: z.literal('vc'),
+    credential: VCValidator,
+    etag: z.string().optional(),
+});
+export type PublicCredentialRefreshEnvelope = z.infer<
+    typeof PublicCredentialRefreshEnvelopeValidator
+>;
+
+/** Managed response: the credential encrypted to the holder as a JWE */
+export const JweCredentialRefreshEnvelopeValidator = z.object({
+    format: z.literal('jwe'),
+    jwe: JWEValidator,
+    etag: z.string().optional(),
+    /** Present on LearnCard-managed endpoints; optional for interoperable JWE services. */
+    version: z.number().int().positive().optional(),
+});
+export type JweCredentialRefreshEnvelope = z.infer<typeof JweCredentialRefreshEnvelopeValidator>;
+
+export const CredentialRefreshResponseEnvelopeValidator = z.discriminatedUnion('format', [
+    PublicCredentialRefreshEnvelopeValidator,
+    JweCredentialRefreshEnvelopeValidator,
+]);
+export type CredentialRefreshResponseEnvelope = z.infer<
+    typeof CredentialRefreshResponseEnvelopeValidator
+>;
+
+// --- Refresh outcomes ----------------------------------------------------------
+
+/**
+ * Safe, machine-readable failure codes. Raw response bodies are never surfaced.
+ */
+export const CredentialRefreshFailureCodeValidator = z.enum([
+    'UNAVAILABLE',
+    'TIMEOUT',
+    'UNSUPPORTED_SERVICE',
+    'UNAUTHORIZED',
+    'MALFORMED_RESPONSE',
+    'INVALID_PROOF',
+    'ISSUER_MISMATCH',
+    'ID_MISMATCH',
+    'ROLLBACK',
+    'REVOKED',
+    'UNSAFE_ENDPOINT',
+]);
+export type CredentialRefreshFailureCode = z.infer<typeof CredentialRefreshFailureCodeValidator>;
+
+export const CredentialRefreshUpdatedResultValidator = z.object({
+    status: z.literal('updated'),
+    credential: VCValidator,
+    etag: z.string().optional(),
+    managedVersion: z.number().int().positive().optional(),
+});
+export type CredentialRefreshUpdatedResult = z.infer<
+    typeof CredentialRefreshUpdatedResultValidator
+>;
+
+export const CredentialRefreshUnchangedResultValidator = z.object({
+    status: z.literal('unchanged'),
+    checkedAt: z.string().min(1),
+    etag: z.string().optional(),
+});
+export type CredentialRefreshUnchangedResult = z.infer<
+    typeof CredentialRefreshUnchangedResultValidator
+>;
+
+export const CredentialRefreshUnsupportedResultValidator = z.object({
+    status: z.literal('unsupported'),
+});
+export type CredentialRefreshUnsupportedResult = z.infer<
+    typeof CredentialRefreshUnsupportedResultValidator
+>;
+
+export const CredentialRefreshFailedResultValidator = z.object({
+    status: z.literal('failed'),
+    code: CredentialRefreshFailureCodeValidator,
+    retryable: z.boolean(),
+});
+export type CredentialRefreshFailedResult = z.infer<typeof CredentialRefreshFailedResultValidator>;
+
+export const CredentialRefreshResultValidator = z.discriminatedUnion('status', [
+    CredentialRefreshUpdatedResultValidator,
+    CredentialRefreshUnchangedResultValidator,
+    CredentialRefreshUnsupportedResultValidator,
+    CredentialRefreshFailedResultValidator,
+]);
+export type CredentialRefreshResult = z.infer<typeof CredentialRefreshResultValidator>;

package/src/index.ts

@@ -16,3 +16,4 @@ export * from './queries';
 export * from './auth';
 export * from './bitstring-status-list';
 export * from './inAppMessages';
+export * from './credential-refresh';

package/src/lcn.ts

@@ -512,6 +512,15 @@ export const SendOptionsValidator = z.object({
         .email()
         .optional()
         .describe('Guardian email that must approve before student can claim'),
+    expiresInDays: z
+        .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.'
+        ),
 });
 export type SendOptions = z.infer<typeof SendOptionsValidator>;
 
@@ -972,6 +981,7 @@ export const LCNNotificationTypeEnumValidator = z.enum([
     'CREDENTIAL_REVOKED',
     'CREDENTIAL_SUSPENDED',
     'CREDENTIAL_UNSUSPENDED',
+    'CREDENTIAL_REFRESHED',
 ]);
 
 export type LCNNotificationTypeEnum = z.infer<typeof LCNNotificationTypeEnumValidator>;
@@ -1186,12 +1196,16 @@ export type CreateContactMethodSessionResponseType = z.infer<
 // Inbox Credentials
 export const InboxCredentialValidator = z.object({
     id: z.string(),
-    credential: z.string(),
+    credential: z.string().optional(),
     isSigned: z.boolean(),
     currentStatus: LCNInboxStatusEnumValidator,
     isAccepted: z.boolean().optional(),
     expiresAt: z.string(),
     createdAt: z.string(),
+    finalizedAt: z.string().optional(),
+    expiredAt: z.string().optional(),
+    credentialName: z.string().optional(),
+    achievementType: z.string().optional(),
     issuerDid: z.string(),
     webhookUrl: z.string().optional(),
     boostUri: z.string().optional(),
@@ -1278,10 +1292,13 @@ export const IssueInboxCredentialValidator = z
                     .describe('The webhook URL to receive credential issuance events.'),
                 expiresInDays: z
                     .number()
+                    .int()
                     .min(1)
-                    .max(365)
+                    .max(720)
                     .optional()
-                    .describe('The number of days the credential will be valid for.'),
+                    .describe(
+                        'How many days the encrypted inbox payload remains claimable. This does not change the credential validity period.'
+                    ),
                 templateData: z
                     .record(z.string(), z.unknown())
                     .optional()
@@ -1401,6 +1418,15 @@ export const ClaimInboxCredentialValidator = z.object({
     configuration: z
         .object({
             publishableKey: z.string(),
+            expiresInDays: z
+                .number()
+                .int()
+                .min(1)
+                .max(720)
+                .optional()
+                .describe(
+                    'Inbox claim window in days. Defaults to 720; use a shorter window for sensitive records.'
+                ),
             signingAuthorityName: z.string().optional(),
             listingId: z.string().optional(),
             listingSlug: z.string().optional(),