@learncard/types 5.17.4 → 5.17.6

package/src/learncard.ts

@@ -0,0 +1,123 @@
+import { z } from 'zod/v4';
+import { CredentialSubjectValidator, ProfileValidator } from './vc';
+import { CredentialFormatValidator, type CredentialFormat } from './credential-format';
+
+/**
+ * Per-entry result for the credentialStatus check.
+ *
+ * Surfaced from `ssi-ldp::StatusCheckEntry` (see ssi PR
+ * `lc-status-array-and-structured-result`) through didkit's
+ * `verifyCredential` JSON output. One entry per `credentialStatus`
+ * entry on the verified credential — VC 2.0 allows multiple
+ * (e.g. one revocation entry + one suspension entry).
+ *
+ * Combine `statusPurpose` + `isSet` to render structured UI without
+ * string-matching the human-readable error in `errors`:
+ *
+ * - `statusPurpose: "revocation"`, `isSet: true`  → revoked
+ * - `statusPurpose: "suspension"`, `isSet: true`  → suspended
+ * - `isSet: false`                                → active for that purpose
+ */
+export const StatusCheckEntryValidator = z.object({
+    /**
+     * The `credentialStatus.type` as it appeared on the credential.
+     * One of `BitstringStatusListEntry`, `StatusList2021Entry`,
+     * `RevocationList2020Status`, or any future custom status type.
+     */
+    entryType: z.string(),
+    /**
+     * The claimed purpose of the entry. Standard values are
+     * `"revocation"` and `"suspension"`; the spec allows arbitrary
+     * strings.
+     */
+    statusPurpose: z.string(),
+    /**
+     * Whether the bit at the credential's index in the status list
+     * bitstring was set.
+     */
+    isSet: z.boolean(),
+    /** URL of the status list credential, when known. */
+    statusListCredential: z.string().optional(),
+    /** Original (string) index within the status list. */
+    statusListIndex: z.string().optional(),
+});
+export type StatusCheckEntry = z.infer<typeof StatusCheckEntryValidator>;
+
+export const VerificationCheckValidator = z.object({
+    checks: z.string().array(),
+    warnings: z.string().array(),
+    errors: z.string().array(),
+    /**
+     * Per-entry results for the `credentialStatus` check, populated
+     * by `@learncard/didkit-plugin` when the verified credential
+     * carries one or more `credentialStatus` entries. Empty / absent
+     * for credentials without a status entry.
+     *
+     * Marked `.optional()` because the underlying `ssi-ldp`
+     * serializer omits the field when empty (`skip_serializing_if`),
+     * so older WASM builds that pre-date the structured-status
+     * change still validate against this schema.
+     */
+    status: StatusCheckEntryValidator.array().optional(),
+});
+export type VerificationCheck = z.infer<typeof VerificationCheckValidator>;
+
+export const VerificationStatusValidator = z.enum(['Success', 'Failed', 'Error']);
+export type VerificationStatus = z.infer<typeof VerificationStatusValidator>;
+export const VerificationStatusEnum = VerificationStatusValidator.enum;
+
+export const VerificationItemValidator = z.object({
+    check: z.string(),
+    status: VerificationStatusValidator,
+    message: z.string().optional(),
+    details: z.string().optional(),
+});
+export type VerificationItem = z.infer<typeof VerificationItemValidator>;
+
+export const CredentialInfoValidator = z.object({
+    title: z.string().optional(),
+    createdAt: z.string().optional(),
+    issuer: ProfileValidator.optional(),
+    issuee: ProfileValidator.optional(),
+    credentialSubject: CredentialSubjectValidator.optional(),
+});
+export type CredentialInfo = z.infer<typeof CredentialInfoValidator>;
+
+export type CredentialRecord<Metadata extends Record<string, any> = Record<never, never>> = {
+    id: string;
+    uri: string;
+    /**
+     * Wire-format discriminator for the credential. Optional — when
+     * absent, legacy readers infer it from `vc` shape (see
+     * `toStoredCredential` in `@learncard/helpers`). Populated on new
+     * writes once the consumer is format-aware.
+     *
+     * Added in ADR-0001 Phase 1 as additive metadata; existing
+     * records without this field continue to work unchanged.
+     */
+    format?: CredentialFormat;
+    /**
+     * Optional semantic type hint for fast filtering without parsing
+     * the full credential — `vct` for SD-JWT-VC, last-non-VC type for
+     * W3C VCs, doctype for mDoc. Added in ADR-0001 Phase 1.
+     */
+    semanticType?: string;
+    /**
+     * On-the-wire representation for formats whose `vc` field cannot
+     * hold the canonical form (SD-JWT compact, JWT-VC compact, base64
+     * mDoc CBOR). Undefined for W3C VCs (`vc` IS the wire form). Added
+     * in ADR-0001 Phase 1.
+     */
+    rawWireForm?: string;
+    [key: string]: any;
+} & Metadata;
+
+export const CredentialRecordValidator = z
+    .object({
+        id: z.string(),
+        uri: z.string(),
+        format: CredentialFormatValidator.optional(),
+        semanticType: z.string().optional(),
+        rawWireForm: z.string().optional(),
+    })
+    .catchall(z.any()) satisfies z.ZodType<CredentialRecord>;

package/src/learncloud.ts

@@ -0,0 +1,26 @@
+import { z } from 'zod/v4';
+
+import { PaginationResponseValidator } from './mongo';
+import { JWEValidator } from './crypto';
+
+export const EncryptedRecordValidator = z
+    .object({ encryptedRecord: JWEValidator, fields: z.string().array() })
+    .catchall(z.any());
+export type EncryptedRecord = z.infer<typeof EncryptedRecordValidator>;
+
+export const PaginatedEncryptedRecordsValidator = PaginationResponseValidator.extend({
+    records: EncryptedRecordValidator.array(),
+});
+export type PaginatedEncryptedRecordsType = z.infer<typeof PaginatedEncryptedRecordsValidator>;
+
+export const EncryptedCredentialRecordValidator = EncryptedRecordValidator.extend({
+    id: z.string(),
+});
+export type EncryptedCredentialRecord = z.infer<typeof EncryptedCredentialRecordValidator>;
+
+export const PaginatedEncryptedCredentialRecordsValidator = PaginationResponseValidator.extend({
+    records: EncryptedCredentialRecordValidator.array(),
+});
+export type PaginatedEncryptedCredentialRecordsType = z.infer<
+    typeof PaginatedEncryptedCredentialRecordsValidator
+>;

package/src/mongo.ts

@@ -0,0 +1,14 @@
+import { z } from 'zod/v4';
+
+export const PaginationOptionsValidator = z.object({
+    limit: z.number(),
+    cursor: z.string().optional(),
+    sort: z.string().optional(),
+});
+export type PaginationOptionsType = z.infer<typeof PaginationOptionsValidator>;
+
+export const PaginationResponseValidator = z.object({
+    cursor: z.string().optional(),
+    hasMore: z.boolean(),
+});
+export type PaginationResponseType = z.infer<typeof PaginationResponseValidator>;

package/src/obv3.ts

@@ -0,0 +1,252 @@
+import { z } from 'zod/v4';
+import {
+    UnsignedVCValidator,
+    ProofValidator,
+    ProfileValidator,
+    ImageValidator,
+    IdentifierEntryValidator,
+} from './vc';
+
+export const AlignmentTargetTypeValidator = z
+    .enum([
+        'ceasn:Competency',
+        'ceterms:Credential',
+        'CFItem',
+        'CFRubric',
+        'CFRubricCriterion',
+        'CFRubricCriterionLevel',
+        'CTDL',
+    ])
+    .or(z.string());
+export type AlignmentTargetType = z.infer<typeof AlignmentTargetTypeValidator>;
+
+export const AlignmentValidator = z.object({
+    type: z.string().array().nonempty(),
+    targetCode: z.string().optional(),
+    targetDescription: z.string().optional(),
+    targetName: z.string(),
+    targetFramework: z.string().optional(),
+    targetType: AlignmentTargetTypeValidator.optional(),
+    targetUrl: z.string(),
+});
+export type Alignment = z.infer<typeof AlignmentValidator>;
+
+export const KnownAchievementTypeValidator = z.enum([
+    'Achievement',
+    'ApprenticeshipCertificate',
+    'Assessment',
+    'Assignment',
+    'AssociateDegree',
+    'Award',
+    'Badge',
+    'BachelorDegree',
+    'Certificate',
+    'CertificateOfCompletion',
+    'Certification',
+    'CommunityService',
+    'Competency',
+    'Course',
+    'CoCurricular',
+    'Degree',
+    'Diploma',
+    'DoctoralDegree',
+    'Fieldwork',
+    'GeneralEducationDevelopment',
+    'JourneymanCertificate',
+    'LearningProgram',
+    'License',
+    'Membership',
+    'ProfessionalDoctorate',
+    'QualityAssuranceCredential',
+    'MasterCertificate',
+    'MasterDegree',
+    'MicroCredential',
+    'ResearchDoctorate',
+    'SecondarySchoolDiploma',
+]);
+export type KnownAchievementType = z.infer<typeof KnownAchievementTypeValidator>;
+
+export const AchievementTypeValidator = KnownAchievementTypeValidator.or(z.string());
+export type AchievementType = z.infer<typeof AchievementTypeValidator>;
+
+export const CriteriaValidator = z
+    .object({ id: z.string().optional(), narrative: z.string().optional() })
+    .catchall(z.any());
+export type Criteria = z.infer<typeof CriteriaValidator>;
+
+export const EndorsementSubjectValidator = z.object({
+    id: z.string(),
+    type: z.string().array().nonempty(),
+    endorsementComment: z.string().optional(),
+});
+export type EndorsementSubject = z.infer<typeof EndorsementSubjectValidator>;
+
+export const EndorsementCredentialValidator = UnsignedVCValidator.extend({
+    credentialSubject: EndorsementSubjectValidator,
+    proof: ProofValidator.or(ProofValidator.array()).optional(),
+});
+export type EndorsementCredential = z.infer<typeof EndorsementCredentialValidator>;
+
+export const RelatedValidator = z.object({
+    id: z.string(),
+    '@language': z.string().optional(),
+    version: z.string().optional(),
+});
+export type Related = z.infer<typeof RelatedValidator>;
+
+export const ResultTypeValidator = z
+    .enum([
+        'GradePointAverage',
+        'LetterGrade',
+        'Percent',
+        'PerformanceLevel',
+        'PredictedScore',
+        'RawScore',
+        'Result',
+        'RubricCriterion',
+        'RubricCriterionLevel',
+        'RubricScore',
+        'ScaledScore',
+        'Status',
+    ])
+    .or(z.string());
+export type ResultType = z.infer<typeof ResultTypeValidator>;
+
+export const RubricCriterionValidator = z
+    .object({
+        id: z.string(),
+        type: z.string().array().nonempty(),
+        alignment: AlignmentValidator.array().optional(),
+        description: z.string().optional(),
+        level: z.string().optional(),
+        name: z.string(),
+        points: z.string().optional(),
+    })
+    .catchall(z.any());
+export type RubricCriterion = z.infer<typeof RubricCriterionValidator>;
+
+export const ResultDescriptionValidator = z
+    .object({
+        id: z.string(),
+        type: z.string().array().nonempty(),
+        alignment: AlignmentValidator.array().optional(),
+        allowedValue: z.string().array().optional(),
+        name: z.string(),
+        requiredLevel: z.string().optional(),
+        requiredValue: z.string().optional(),
+        resultType: ResultTypeValidator,
+        rubricCriterionLevel: RubricCriterionValidator.array().optional(),
+        valueMax: z.string().optional(),
+        valueMin: z.string().optional(),
+    })
+    .catchall(z.any());
+export type ResultDescription = z.infer<typeof ResultDescriptionValidator>;
+
+export const EvidenceValidator = z
+    .object({
+        id: z.string().optional(),
+        type: z.array(z.string()).nonempty(),
+        name: z.string().optional(),
+        narrative: z.string().optional(),
+        description: z.string().optional(),
+        genre: z.string().optional(),
+        audience: z.string().optional(),
+    })
+    .catchall(z.any());
+
+export type Evidence = z.infer<typeof EvidenceValidator>;
+
+export const AchievementValidator = z
+    .object({
+        id: z.string().optional(),
+        type: z.array(z.string()).nonempty(),
+        alignment: AlignmentValidator.array().optional(),
+        achievementType: AchievementTypeValidator.optional(),
+        creator: ProfileValidator.optional(),
+        creditsAvailable: z.number().optional(),
+        criteria: CriteriaValidator,
+        description: z.string(),
+        endorsement: EndorsementCredentialValidator.array().optional(),
+        fieldOfStudy: z.string().optional(),
+        humanCode: z.string().optional(),
+        image: ImageValidator.optional(),
+        '@language': z.string().optional(),
+        name: z.string(),
+        otherIdentifier: IdentifierEntryValidator.array().optional(),
+        related: RelatedValidator.array().optional(),
+        resultDescription: ResultDescriptionValidator.array().optional(),
+        specialization: z.string().optional(),
+        tag: z.array(z.string()).optional(),
+        version: z.string().optional(),
+    })
+    .catchall(z.any());
+export type Achievement = z.infer<typeof AchievementValidator>;
+
+export const IdentityObjectValidator = z.object({
+    type: z.string(),
+    hashed: z.boolean(),
+    identityHash: z.string(),
+    identityType: z.string(),
+    salt: z.string().optional(),
+});
+export type IdentityObject = z.infer<typeof IdentityObjectValidator>;
+
+export const ResultStatusTypeValidator = z.enum([
+    'Completed',
+    'Enrolled',
+    'Failed',
+    'InProgress',
+    'OnHold',
+    'Withdrew',
+]);
+export type ResultStatusType = z.infer<typeof ResultStatusTypeValidator>;
+
+export const ResultValidator = z
+    .object({
+        type: z.string().array().nonempty(),
+        achievedLevel: z.string().optional(),
+        alignment: AlignmentValidator.array().optional(),
+        resultDescription: z.string().optional(),
+        status: ResultStatusTypeValidator.optional(),
+        value: z.string().optional(),
+    })
+    .catchall(z.any());
+export type Result = z.infer<typeof ResultValidator>;
+
+export const AchievementSubjectValidator = z
+    .object({
+        id: z.string().optional(),
+        type: z.string().array().nonempty(),
+        activityEndDate: z.string().optional(),
+        activityStartDate: z.string().optional(),
+        creditsEarned: z.number().optional(),
+        achievement: AchievementValidator.optional(),
+        identifier: IdentityObjectValidator.array().optional(),
+        image: ImageValidator.optional(),
+        licenseNumber: z.string().optional(),
+        narrative: z.string().optional(),
+        result: ResultValidator.array().optional(),
+        role: z.string().optional(),
+        source: ProfileValidator.optional(),
+        term: z.string().optional(),
+    })
+    .catchall(z.any());
+export type AchievementSubject = z.infer<typeof AchievementSubjectValidator>;
+
+export const UnsignedAchievementCredentialValidator = UnsignedVCValidator.extend({
+    name: z.string().optional(),
+    description: z.string().optional(),
+    image: ImageValidator.optional(),
+    credentialSubject: AchievementSubjectValidator.or(
+        AchievementSubjectValidator.array()
+    ) as z.ZodUnion<
+        [typeof AchievementSubjectValidator, z.ZodArray<typeof AchievementSubjectValidator>]
+    >,
+    endorsement: UnsignedVCValidator.array().optional(),
+});
+export type UnsignedAchievementCredential = z.infer<typeof UnsignedAchievementCredentialValidator>;
+
+export const AchievementCredentialValidator = UnsignedAchievementCredentialValidator.extend({
+    proof: ProofValidator.or(ProofValidator.array()),
+});
+export type AchievementCredential = z.infer<typeof AchievementCredentialValidator>;

package/src/queries.ts

@@ -0,0 +1,56 @@
+import { z } from 'zod/v4';
+
+// Helper to extract flags and pattern from regex string
+const parseRegexString = (regexStr: string) => {
+    const match = regexStr.match(/^\/(.*)\/([gimsuy]*)$/);
+    if (!match) throw new Error('Invalid RegExp string format');
+    return { pattern: match[1], flags: match[2] };
+};
+
+// TRPC validator that converts Regex strings into RegExps
+const RegExpStringValidator = z
+    .string()
+    .refine(
+        str => {
+            try {
+                parseRegexString(str);
+                return true;
+            } catch {
+                return false;
+            }
+        },
+        {
+            message: "Invalid RegExp string format. Must be in format '/pattern/flags'",
+        }
+    )
+    .transform(str => {
+        const { pattern, flags } = parseRegexString(str);
+
+        try {
+            return new RegExp(pattern, flags);
+        } catch (error) {
+            throw new Error(`Invalid RegExp: ${(error as Error).message}`);
+        }
+    })
+    .meta({ override: { type: 'string' } });
+
+// Do not use z.instanceof(RegExp) here: it is a `custom` Zod type that crashes
+// zod-openapi document generation at service boot, and `.meta({ override })` is
+// not honored for custom types. Coercing a RegExp to its `/source/flags` string
+// keeps the OpenAPI schema a plain string while still accepting RegExp inputs.
+export const RegExpValidator = z.preprocess(
+    value => (value instanceof RegExp ? `/${value.source}/${value.flags}` : value),
+    RegExpStringValidator
+);
+
+const BaseStringQuery = z
+    .string()
+    .or(z.object({ $in: z.string().array() }))
+    .or(z.object({ $regex: RegExpValidator }));
+
+export const StringQuery = z.union([
+    BaseStringQuery,
+    z.object({
+        $or: BaseStringQuery.array(),
+    }),
+]);

package/src/registries.ts

@@ -0,0 +1,9 @@
+export type KnownDIDRegistryType = {
+    source: string;
+    results:
+        | {
+              matchingIssuers: any[];
+              uncheckedRegistries: any[];
+          }
+        | {};
+};