@owf/mdoc 0.10.0 → 0.11.0-alpha-20261117104856

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.mts CHANGED
@@ -1297,6 +1297,97 @@ export declare class MobileSecurityObject extends CborStructure<MobileSecurityOb
1297
1297
  get status(): Status | undefined;
1298
1298
  static create(options: MobileSecurityObjectOptions): MobileSecurityObject;
1299
1299
  }
1300
+ /**
1301
+ * How the verification of an mdoc checks the status list and identifier list of its MSO
1302
+ * (ISO/IEC 18013-5 second edition § 12.3.6).
1303
+ */
1304
+ export type StatusVerificationOptions = {
1305
+ /** Don't fetch and check the status list or identifier list of the MSO. */
1306
+ disableValidation?: boolean;
1307
+ /** The maximum size in bytes the status list may inflate to, 16 MiB by default. */
1308
+ maxDecompressedBytes?: number;
1309
+ };
1310
+ export type VerifyStatusListTokenOptions = {
1311
+ statusListInfo: Pick<StatusListInfo$1, 'uri' | 'idx'>;
1312
+ /**
1313
+ * Trust anchors for the certificate chain of the list signer. Required unless
1314
+ * `disableCertificateChainValidation` is set.
1315
+ */
1316
+ trustedCertificates?: Array<Uint8Array>;
1317
+ /**
1318
+ * Verify the list with the key of the leaf of its x5chain, without validating the chain.
1319
+ */
1320
+ disableCertificateChainValidation?: boolean;
1321
+ now?: Date;
1322
+ skewSeconds?: number;
1323
+ checkFreshness?: boolean;
1324
+ /** The maximum size in bytes the status list may inflate to, 16 MiB by default. */
1325
+ maxDecompressedBytes?: number;
1326
+ };
1327
+ /** A status list served in JWT format, once verified. */
1328
+ export type VerifiedStatusListJwt = {
1329
+ header: Record<string, unknown>;
1330
+ payload: StatusListJwtPayload;
1331
+ statusList: StatusList;
1332
+ };
1333
+ export type VerifyStatusListTokenResult = {
1334
+ /** The verified list, when it was served in CWT format. */
1335
+ statusListCwt?: StatusListCwt;
1336
+ /** The verified list, when it was served in JWT format instead. */
1337
+ statusListJwt?: VerifiedStatusListJwt;
1338
+ /** The validated certificate chain of the list signer, leaf first. Not set without chain validation. */
1339
+ chain?: Array<Uint8Array>;
1340
+ };
1341
+ /**
1342
+ * Fetch and verify the status list a `StatusListInfo` points at.
1343
+ *
1344
+ * `@owf/token-status-list` owns everything status-list-shaped — fetching and content-type
1345
+ * negotiation, the CWT structure, the claim checks and reading a status by index. What lives here
1346
+ * is what that library cannot know about: the mdoc trust anchors and the `MdocContext` crypto
1347
+ * callbacks used to establish the signer, and the two rules ISO/IEC 18013-5 § 12.3.6 layers on top
1348
+ * of the Token Status List defaults — a mandatory `exp` (§ 12.3.6.3), and `Valid` as the only
1349
+ * acceptable status, since § 12.3.6.1 allows "no other status besides 'revoked'".
1350
+ *
1351
+ * § 12.3.6.3 requires the list to be a Status List Token "in CWT format, since the IssuerAuth
1352
+ * structure is a CWT", so CWT is preferred. A list served as a JWT is still accepted as a fallback,
1353
+ * verified to the same rules; the JWS checks (ECDSA only, no `crit`, the `x5c` signer chain) live
1354
+ * in `verifyStatusListJwt`.
1355
+ *
1356
+ * The signer chain of a CWT is read from the protected header, as § 12.3.6.3 requires, or else from
1357
+ * the unprotected header when a protected `x5t` matches its leaf (RFC 9360).
1358
+ */
1359
+ export declare function verifyStatusListToken({ statusListInfo, trustedCertificates, disableCertificateChainValidation, now, skewSeconds, checkFreshness, maxDecompressedBytes }: VerifyStatusListTokenOptions, ctx: Pick<MdocContext, 'fetch' | 'fetchLimits' | 'x509' | 'cose' | 'crypto'>): Promise<VerifyStatusListTokenResult>;
1360
+ export type VerifyIdentifierListTokenOptions = {
1361
+ identifierListInfo: Pick<IdentifierListInfo, 'uri' | 'id'>;
1362
+ /**
1363
+ * Trust anchors for the certificate chain of the list signer. Required unless
1364
+ * `disableCertificateChainValidation` is set.
1365
+ */
1366
+ trustedCertificates?: Array<Uint8Array>;
1367
+ /**
1368
+ * Verify the list with the key of the leaf of its x5chain, without validating the chain.
1369
+ */
1370
+ disableCertificateChainValidation?: boolean;
1371
+ now?: Date;
1372
+ skewSeconds?: number;
1373
+ checkFreshness?: boolean;
1374
+ };
1375
+ export type VerifyIdentifierListTokenResult = {
1376
+ identifierListCwt: IdentifierListCwt;
1377
+ /** The validated certificate chain of the list signer, leaf first. Not set without chain validation. */
1378
+ chain?: Array<Uint8Array>;
1379
+ };
1380
+ /**
1381
+ * Fetch and verify the identifier list an `IdentifierListInfo` points at (§ 12.3.6.4):
1382
+ * certificate chain, signature, the claim checks § 12.3.6.1 makes binding on both revocation
1383
+ * mechanisms, and finally whether the MSO's own identifier appears in it — presence means revoked.
1384
+ *
1385
+ * The counterpart of {@link verifyStatusListToken}. Unlike a status list, the identifier list is an
1386
+ * ISO addition that the Token Status List specification does not describe, so `IdentifierListCwt`
1387
+ * lives in this package rather than in `@owf/token-status-list` — built on the same `Cwt`, so the
1388
+ * two are verified the same way.
1389
+ */
1390
+ export declare function verifyIdentifierListToken({ identifierListInfo, trustedCertificates, disableCertificateChainValidation, now, skewSeconds, checkFreshness }: VerifyIdentifierListTokenOptions, ctx: Pick<MdocContext, 'fetch' | 'fetchLimits' | 'x509' | 'cose'>): Promise<VerifyIdentifierListTokenResult>;
1300
1391
  export type IssuerAuthEncodedStructure = Sign1EncodedStructure;
1301
1392
  export type IssuerAuthOptions = Omit<Sign1Options, 'payload'> & {
1302
1393
  payload?: Sign1Options['payload'] | MobileSecurityObject;
@@ -1339,7 +1430,7 @@ export declare class IssuerAuth extends Sign1$1 {
1339
1430
  *
1340
1431
  * @todo return the full verified chain for audit / compliance.
1341
1432
  */
1342
- verifyStatus({ now, skewSeconds, checkFreshness, trustedStatusCertificates, disableCertificateChainValidation, maxStatusListDecompressedBytes }: {
1433
+ verifyStatus({ now, skewSeconds, checkFreshness, trustedStatusCertificates, disableCertificateChainValidation, maxDecompressedBytes }: Omit<StatusVerificationOptions, 'disableValidation'> & {
1343
1434
  now?: Date;
1344
1435
  /** Tolerance applied to the `exp` and `iat` of a revocation list. Defaults to 30 seconds. */
1345
1436
  skewSeconds?: number;
@@ -1350,8 +1441,6 @@ export declare class IssuerAuth extends Sign1$1 {
1350
1441
  * certificate chain against `trustedStatusCertificates`. The revocation status is still checked.
1351
1442
  */
1352
1443
  disableCertificateChainValidation?: boolean;
1353
- /** The maximum size in bytes the status list may inflate to, 16 MiB by default. */
1354
- maxStatusListDecompressedBytes?: number;
1355
1444
  }, ctx: Pick<MdocContext, 'fetch' | 'fetchLimits' | 'x509' | 'cose' | 'crypto'>): Promise<{
1356
1445
  statusList?: StatusListCwt;
1357
1446
  trustedStatusListChain?: Uint8Array[];
@@ -1371,10 +1460,8 @@ export declare class IssuerAuth extends Sign1$1 {
1371
1460
  status?: Uint8Array[];
1372
1461
  }>;
1373
1462
  disableCertificateChainValidation?: boolean;
1374
- disableStatusValidation?: boolean;
1375
1463
  skewSeconds?: number;
1376
- /** The maximum size in bytes the status list of an mdoc may inflate to, 16 MiB by default. */
1377
- maxStatusListDecompressedBytes?: number;
1464
+ status?: StatusVerificationOptions;
1378
1465
  }, ctx: Pick<MdocContext, 'x509' | 'cose' | 'fetch' | 'fetchLimits' | 'crypto'>): Promise<IssuerAuthVerificationResult>;
1379
1466
  }
1380
1467
  export declare const zIssuerSignedItem: z$1.ZodCodec<z$1.ZodMap<z$1.ZodUnknown, z$1.ZodUnknown>, z$1.ZodInstanceOf<import("@owf/cose").TypedMap<{
@@ -1507,10 +1594,8 @@ export declare class IssuerSigned extends CborStructure<IssuerSignedEncodedStruc
1507
1594
  status?: Uint8Array[];
1508
1595
  }>;
1509
1596
  disableCertificateChainValidation?: boolean;
1510
- disableStatusValidation?: boolean;
1511
1597
  skewSeconds?: number;
1512
- /** The maximum size in bytes the status list of an mdoc may inflate to, 16 MiB by default. */
1513
- maxStatusListDecompressedBytes?: number;
1598
+ status?: StatusVerificationOptions;
1514
1599
  }, ctx: Pick<MdocContext, 'x509' | 'crypto' | 'cose' | 'fetch' | 'fetchLimits'>): Promise<IssuerSignedVerificationResult>;
1515
1600
  static create(options: IssuerSignedOptions): IssuerSigned;
1516
1601
  }
@@ -1664,7 +1749,6 @@ export declare class DeviceResponse extends CborStructure<DeviceResponseEncodedS
1664
1749
  sessionTranscript: SessionTranscript | Uint8Array;
1665
1750
  ephemeralReaderKey?: CoseKey$1;
1666
1751
  disableCertificateChainValidation?: boolean;
1667
- disableStatusValidation?: boolean;
1668
1752
  trustedCertificates: Array<{
1669
1753
  issuance: Uint8Array[];
1670
1754
  status?: Uint8Array[];
@@ -1672,8 +1756,7 @@ export declare class DeviceResponse extends CborStructure<DeviceResponseEncodedS
1672
1756
  now?: Date;
1673
1757
  onCheck?: VerificationCallback;
1674
1758
  skewSeconds?: number;
1675
- /** The maximum size in bytes the status list of an mdoc may inflate to, 16 MiB by default. */
1676
- maxStatusListDecompressedBytes?: number;
1759
+ status?: StatusVerificationOptions;
1677
1760
  }, ctx: Pick<MdocContext, 'cose' | 'x509' | 'crypto' | 'fetch' | 'fetchLimits'>): Promise<DeviceResponseVerificationResult>;
1678
1761
  get encodedForOid4Vp(): string;
1679
1762
  static fromEncodedForOid4Vp(encoded: string): DeviceResponse;
@@ -2580,87 +2663,6 @@ export declare class EngagementToAppHandover extends Handover<EngagementToAppHan
2580
2663
  get requiresDeviceEngagement(): boolean;
2581
2664
  static create(readerEngagementBytesHash: Uint8Array): EngagementToAppHandover;
2582
2665
  }
2583
- export type VerifyStatusListTokenOptions = {
2584
- statusListInfo: Pick<StatusListInfo$1, 'uri' | 'idx'>;
2585
- /**
2586
- * Trust anchors for the certificate chain of the list signer. Required unless
2587
- * `disableCertificateChainValidation` is set.
2588
- */
2589
- trustedCertificates?: Array<Uint8Array>;
2590
- /**
2591
- * Verify the list with the key of the leaf of its x5chain, without validating the chain.
2592
- */
2593
- disableCertificateChainValidation?: boolean;
2594
- now?: Date;
2595
- skewSeconds?: number;
2596
- checkFreshness?: boolean;
2597
- /** The maximum size in bytes the status list may inflate to, 16 MiB by default. */
2598
- maxDecompressedBytes?: number;
2599
- };
2600
- /** A status list served in JWT format, once verified. */
2601
- export type VerifiedStatusListJwt = {
2602
- header: Record<string, unknown>;
2603
- payload: StatusListJwtPayload;
2604
- statusList: StatusList;
2605
- };
2606
- export type VerifyStatusListTokenResult = {
2607
- /** The verified list, when it was served in CWT format. */
2608
- statusListCwt?: StatusListCwt;
2609
- /** The verified list, when it was served in JWT format instead. */
2610
- statusListJwt?: VerifiedStatusListJwt;
2611
- /** The validated certificate chain of the list signer, leaf first. Not set without chain validation. */
2612
- chain?: Array<Uint8Array>;
2613
- };
2614
- /**
2615
- * Fetch and verify the status list a `StatusListInfo` points at.
2616
- *
2617
- * `@owf/token-status-list` owns everything status-list-shaped — fetching and content-type
2618
- * negotiation, the CWT structure, the claim checks and reading a status by index. What lives here
2619
- * is what that library cannot know about: the mdoc trust anchors and the `MdocContext` crypto
2620
- * callbacks used to establish the signer, and the two rules ISO/IEC 18013-5 § 12.3.6 layers on top
2621
- * of the Token Status List defaults — a mandatory `exp` (§ 12.3.6.3), and `Valid` as the only
2622
- * acceptable status, since § 12.3.6.1 allows "no other status besides 'revoked'".
2623
- *
2624
- * § 12.3.6.3 requires the list to be a Status List Token "in CWT format, since the IssuerAuth
2625
- * structure is a CWT", so CWT is preferred. A list served as a JWT is still accepted as a fallback,
2626
- * verified to the same rules; the JWS checks (ECDSA only, no `crit`, the `x5c` signer chain) live
2627
- * in `verifyStatusListJwt`.
2628
- *
2629
- * The signer chain of a CWT is read from the protected header, as § 12.3.6.3 requires, or else from
2630
- * the unprotected header when a protected `x5t` matches its leaf (RFC 9360).
2631
- */
2632
- export declare function verifyStatusListToken({ statusListInfo, trustedCertificates, disableCertificateChainValidation, now, skewSeconds, checkFreshness, maxDecompressedBytes }: VerifyStatusListTokenOptions, ctx: Pick<MdocContext, 'fetch' | 'fetchLimits' | 'x509' | 'cose' | 'crypto'>): Promise<VerifyStatusListTokenResult>;
2633
- export type VerifyIdentifierListTokenOptions = {
2634
- identifierListInfo: Pick<IdentifierListInfo, 'uri' | 'id'>;
2635
- /**
2636
- * Trust anchors for the certificate chain of the list signer. Required unless
2637
- * `disableCertificateChainValidation` is set.
2638
- */
2639
- trustedCertificates?: Array<Uint8Array>;
2640
- /**
2641
- * Verify the list with the key of the leaf of its x5chain, without validating the chain.
2642
- */
2643
- disableCertificateChainValidation?: boolean;
2644
- now?: Date;
2645
- skewSeconds?: number;
2646
- checkFreshness?: boolean;
2647
- };
2648
- export type VerifyIdentifierListTokenResult = {
2649
- identifierListCwt: IdentifierListCwt;
2650
- /** The validated certificate chain of the list signer, leaf first. Not set without chain validation. */
2651
- chain?: Array<Uint8Array>;
2652
- };
2653
- /**
2654
- * Fetch and verify the identifier list an `IdentifierListInfo` points at (§ 12.3.6.4):
2655
- * certificate chain, signature, the claim checks § 12.3.6.1 makes binding on both revocation
2656
- * mechanisms, and finally whether the MSO's own identifier appears in it — presence means revoked.
2657
- *
2658
- * The counterpart of {@link verifyStatusListToken}. Unlike a status list, the identifier list is an
2659
- * ISO addition that the Token Status List specification does not describe, so `IdentifierListCwt`
2660
- * lives in this package rather than in `@owf/token-status-list` — built on the same `Cwt`, so the
2661
- * two are verified the same way.
2662
- */
2663
- export declare function verifyIdentifierListToken({ identifierListInfo, trustedCertificates, disableCertificateChainValidation, now, skewSeconds, checkFreshness }: VerifyIdentifierListTokenOptions, ctx: Pick<MdocContext, 'fetch' | 'fetchLimits' | 'x509' | 'cose'>): Promise<VerifyIdentifierListTokenResult>;
2664
2666
  declare const zNfcHandoverEncoded: z.ZodTuple<[z.ZodInstanceOf<Uint8Array<ArrayBufferLike>>, z.ZodNullable<z.ZodInstanceOf<Uint8Array<ArrayBufferLike>>>], null>;
2665
2667
  declare const zNfcHandoverDecoded: z.ZodObject<{
2666
2668
  selectMessage: z.ZodInstanceOf<Uint8Array<ArrayBufferLike>>;
@@ -2887,14 +2889,12 @@ export declare class Holder {
2887
2889
  verificationCallback?: VerificationCallback;
2888
2890
  now?: Date;
2889
2891
  disableCertificateChainValidation?: boolean;
2890
- disableStatusValidation?: boolean;
2891
2892
  trustedCertificates?: Array<{
2892
2893
  issuance: Uint8Array[];
2893
2894
  status?: Uint8Array[];
2894
2895
  }>;
2895
2896
  skewSeconds?: number;
2896
- /** The maximum size in bytes the status list of an mdoc may inflate to, 16 MiB by default. */
2897
- maxStatusListDecompressedBytes?: number;
2897
+ status?: StatusVerificationOptions;
2898
2898
  }, ctx: Pick<MdocContext, 'cose' | 'x509' | 'crypto' | 'fetch' | 'fetchLimits'>): Promise<IssuerSignedVerificationResult>;
2899
2899
  static verifyDeviceRequest(options: {
2900
2900
  deviceRequest: Uint8Array | DeviceRequest;
@@ -3136,12 +3136,10 @@ export declare class IsoMdocDcApi {
3136
3136
  status?: Array<Uint8Array>;
3137
3137
  }>;
3138
3138
  disableCertificateChainValidation?: boolean;
3139
- disableStatusValidation?: boolean;
3140
3139
  onCheck?: VerificationCallback;
3141
3140
  now?: Date;
3142
3141
  skewSeconds?: number;
3143
- /** The maximum size in bytes the status list of an mdoc may inflate to, 16 MiB by default. */
3144
- maxStatusListDecompressedBytes?: number;
3142
+ status?: StatusVerificationOptions;
3145
3143
  }, ctx: Pick<MdocContext, 'crypto' | 'cose' | 'x509' | 'fetch' | 'fetchLimits'>): Promise<{
3146
3144
  deviceResponse: DeviceResponse;
3147
3145
  verificationResult: DeviceResponseVerificationResult;
@@ -3223,7 +3221,6 @@ export declare class Verifier {
3223
3221
  sessionTranscript: SessionTranscript | Uint8Array;
3224
3222
  ephemeralReaderKey?: CoseKey$1;
3225
3223
  disableCertificateChainValidation?: boolean;
3226
- disableStatusValidation?: boolean;
3227
3224
  trustedCertificates: Array<{
3228
3225
  issuance: Uint8Array[];
3229
3226
  status?: Uint8Array[];
@@ -3231,8 +3228,7 @@ export declare class Verifier {
3231
3228
  now?: Date;
3232
3229
  onCheck?: VerificationCallback;
3233
3230
  skewSeconds?: number;
3234
- /** The maximum size in bytes the status list of an mdoc may inflate to, 16 MiB by default. */
3235
- maxStatusListDecompressedBytes?: number;
3231
+ status?: StatusVerificationOptions;
3236
3232
  }, ctx: Pick<MdocContext, 'cose' | 'x509' | 'crypto' | 'fetch' | 'fetchLimits'>): Promise<DeviceResponseVerificationResult>;
3237
3233
  /**
3238
3234
  * Match a device response against the device request it answers, without verifying it. See
package/dist/index.mjs CHANGED
@@ -2865,7 +2865,7 @@ var IssuerAuth = class extends Sign1$1 {
2865
2865
  *
2866
2866
  * @todo return the full verified chain for audit / compliance.
2867
2867
  */
2868
- async verifyStatus({ now = /* @__PURE__ */ new Date(), skewSeconds, checkFreshness, trustedStatusCertificates, disableCertificateChainValidation, maxStatusListDecompressedBytes }, ctx) {
2868
+ async verifyStatus({ now = /* @__PURE__ */ new Date(), skewSeconds, checkFreshness, trustedStatusCertificates, disableCertificateChainValidation, maxDecompressedBytes }, ctx) {
2869
2869
  const status = this.mobileSecurityObject.status;
2870
2870
  if (!status || !status.statusList && !status.identifierList) return {};
2871
2871
  const statusListResult = status.statusList ? await verifyStatusListToken({
@@ -2875,7 +2875,7 @@ var IssuerAuth = class extends Sign1$1 {
2875
2875
  now,
2876
2876
  skewSeconds,
2877
2877
  checkFreshness,
2878
- maxDecompressedBytes: maxStatusListDecompressedBytes
2878
+ maxDecompressedBytes
2879
2879
  }, ctx) : void 0;
2880
2880
  const identifierListResult = status.identifierList ? await verifyIdentifierListToken({
2881
2881
  identifierListInfo: status.identifierList,
@@ -2917,7 +2917,7 @@ var IssuerAuth = class extends Sign1$1 {
2917
2917
  const verificationCallback = options.verificationCallback ?? defaultVerificationCallback;
2918
2918
  const now = options.now ?? /* @__PURE__ */ new Date();
2919
2919
  const disableCertificateChainValidation = options.disableCertificateChainValidation ?? false;
2920
- const disableStatusValidation = options.disableStatusValidation ?? false;
2920
+ const disableStatusValidation = options.status?.disableValidation ?? false;
2921
2921
  const trustedCertificates = options.trustedCertificates ?? [];
2922
2922
  const skewSeconds = options.skewSeconds ?? 30;
2923
2923
  const onCheck = onCategoryCheck(verificationCallback, "ISSUER_AUTH");
@@ -2985,7 +2985,7 @@ var IssuerAuth = class extends Sign1$1 {
2985
2985
  skewSeconds,
2986
2986
  checkFreshness: true,
2987
2987
  trustedStatusCertificates,
2988
- maxStatusListDecompressedBytes: options.maxStatusListDecompressedBytes
2988
+ maxDecompressedBytes: options.status?.maxDecompressedBytes
2989
2989
  }, ctx));
2990
2990
  } catch (err) {
2991
2991
  const { statusList: statusListInfo, identifierList: identifierListInfo } = this.mobileSecurityObject.status ?? {};
@@ -4450,8 +4450,7 @@ var DeviceResponse = class DeviceResponse extends CborStructure {
4450
4450
  now: options.now,
4451
4451
  trustedCertificates: options.trustedCertificates,
4452
4452
  skewSeconds: options.skewSeconds,
4453
- disableStatusValidation: options.disableStatusValidation,
4454
- maxStatusListDecompressedBytes: options.maxStatusListDecompressedBytes
4453
+ status: options.status
4455
4454
  }, ctx);
4456
4455
  const mobileSecurityObjectDocType = document.issuerSigned.issuerAuth.mobileSecurityObject.docType;
4457
4456
  onCheck({
@@ -5373,11 +5372,10 @@ var IsoMdocDcApi = class IsoMdocDcApi {
5373
5372
  sessionTranscript,
5374
5373
  trustedCertificates: options.trustedCertificates,
5375
5374
  disableCertificateChainValidation: options.disableCertificateChainValidation,
5376
- disableStatusValidation: options.disableStatusValidation,
5377
5375
  onCheck: options.onCheck,
5378
5376
  now: options.now,
5379
5377
  skewSeconds: options.skewSeconds,
5380
- maxStatusListDecompressedBytes: options.maxStatusListDecompressedBytes
5378
+ status: options.status
5381
5379
  }, ctx)
5382
5380
  };
5383
5381
  }