@me2em/core 0.7.0-alpha.1 → 1.0.0-rc.1

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.
Files changed (92) hide show
  1. package/README.md +242 -47
  2. package/dist/attestation.d.ts +26 -17
  3. package/dist/attestation.d.ts.map +1 -1
  4. package/dist/attestation.js +76 -29
  5. package/dist/attestation.js.map +1 -1
  6. package/dist/canonical-name.d.ts +18 -0
  7. package/dist/canonical-name.d.ts.map +1 -1
  8. package/dist/canonical-name.js +28 -1
  9. package/dist/canonical-name.js.map +1 -1
  10. package/dist/crypto/derivation-paths.d.ts +33 -2
  11. package/dist/crypto/derivation-paths.d.ts.map +1 -1
  12. package/dist/crypto/derivation-paths.js +33 -2
  13. package/dist/crypto/derivation-paths.js.map +1 -1
  14. package/dist/crypto/derivation.d.ts +47 -0
  15. package/dist/crypto/derivation.d.ts.map +1 -0
  16. package/dist/crypto/derivation.js +68 -0
  17. package/dist/crypto/derivation.js.map +1 -0
  18. package/dist/crypto/ecdh.d.ts +19 -0
  19. package/dist/crypto/ecdh.d.ts.map +1 -0
  20. package/dist/crypto/ecdh.js +33 -0
  21. package/dist/crypto/ecdh.js.map +1 -0
  22. package/dist/crypto/ed25519.d.ts +24 -3
  23. package/dist/crypto/ed25519.d.ts.map +1 -1
  24. package/dist/crypto/ed25519.js +39 -6
  25. package/dist/crypto/ed25519.js.map +1 -1
  26. package/dist/crypto/hkdf.d.ts +11 -2
  27. package/dist/crypto/hkdf.d.ts.map +1 -1
  28. package/dist/crypto/hkdf.js +13 -1
  29. package/dist/crypto/hkdf.js.map +1 -1
  30. package/dist/crypto/index.d.ts +25 -0
  31. package/dist/crypto/index.d.ts.map +1 -1
  32. package/dist/crypto/index.js +25 -0
  33. package/dist/crypto/index.js.map +1 -1
  34. package/dist/disposed-error.d.ts +24 -0
  35. package/dist/disposed-error.d.ts.map +1 -0
  36. package/dist/disposed-error.js +39 -0
  37. package/dist/disposed-error.js.map +1 -0
  38. package/dist/errors.d.ts +67 -0
  39. package/dist/errors.d.ts.map +1 -0
  40. package/dist/errors.js +54 -0
  41. package/dist/errors.js.map +1 -0
  42. package/dist/handle.d.ts +300 -14
  43. package/dist/handle.d.ts.map +1 -1
  44. package/dist/handle.js +463 -54
  45. package/dist/handle.js.map +1 -1
  46. package/dist/identity.d.ts +55 -11
  47. package/dist/identity.d.ts.map +1 -1
  48. package/dist/identity.js +105 -35
  49. package/dist/identity.js.map +1 -1
  50. package/dist/index.d.ts +10 -5
  51. package/dist/index.d.ts.map +1 -1
  52. package/dist/index.js +8 -4
  53. package/dist/index.js.map +1 -1
  54. package/dist/seed.d.ts +33 -22
  55. package/dist/seed.d.ts.map +1 -1
  56. package/dist/seed.js +59 -31
  57. package/dist/seed.js.map +1 -1
  58. package/dist/session.d.ts +42 -5
  59. package/dist/session.d.ts.map +1 -1
  60. package/dist/session.js +248 -117
  61. package/dist/session.js.map +1 -1
  62. package/dist/subhandle.d.ts +1 -125
  63. package/dist/subhandle.d.ts.map +1 -1
  64. package/dist/subhandle.js +12 -179
  65. package/dist/subhandle.js.map +1 -1
  66. package/dist/types.d.ts +22 -0
  67. package/dist/types.d.ts.map +1 -0
  68. package/dist/types.js +6 -0
  69. package/dist/types.js.map +1 -0
  70. package/dist/util.d.ts +47 -0
  71. package/dist/util.d.ts.map +1 -1
  72. package/dist/util.js +72 -20
  73. package/dist/util.js.map +1 -1
  74. package/package.json +12 -5
  75. package/src/attestation.ts +88 -38
  76. package/src/canonical-name.ts +33 -1
  77. package/src/crypto/derivation-paths.ts +37 -2
  78. package/src/crypto/derivation.ts +90 -0
  79. package/src/crypto/ecdh.ts +37 -0
  80. package/src/crypto/ed25519.ts +39 -6
  81. package/src/crypto/hkdf.ts +13 -1
  82. package/src/crypto/index.ts +28 -1
  83. package/src/disposed-error.ts +45 -0
  84. package/src/errors.ts +88 -0
  85. package/src/handle.ts +630 -65
  86. package/src/identity.ts +111 -64
  87. package/src/index.ts +13 -7
  88. package/src/seed.ts +75 -32
  89. package/src/session.ts +336 -132
  90. package/src/subhandle.ts +12 -251
  91. package/src/types.ts +26 -0
  92. package/src/util.ts +78 -20
@@ -34,18 +34,39 @@ export declare function sign(message: Uint8Array, privateKey: Uint8Array): Uint8
34
34
  */
35
35
  export declare function verify(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array, opts?: VerifyOpts): boolean;
36
36
  /**
37
- * Asynchronous variant of {@link getPublicKey}; same contract.
37
+ * Derives the Ed25519 public key for a private key (asynchronous
38
+ * variant of {@link getPublicKey}; same contract).
39
+ *
40
+ * @param privateKey - 32-byte Ed25519 private key.
41
+ * @returns A Promise resolving to the 32-byte public key.
42
+ * @throws `TypeError` if the key length is invalid.
43
+ * @throws `RangeError` if the key length is invalid.
38
44
  */
39
45
  export declare function getPublicKeyAsync(privateKey: Uint8Array): Promise<Uint8Array>;
40
46
  /**
41
- * Asynchronous variant of {@link sign}; same contract.
47
+ * Signs a message with an Ed25519 private key (asynchronous variant of
48
+ * {@link sign}; same contract).
49
+ *
50
+ * @param message - The bytes to sign.
51
+ * @param privateKey - 32-byte Ed25519 private key.
52
+ * @returns A Promise resolving to the 64-byte signature.
53
+ * @throws `TypeError` if an input length is invalid.
54
+ * @throws `RangeError` if an input length is invalid.
42
55
  */
43
56
  export declare function signAsync(message: Uint8Array, privateKey: Uint8Array): Promise<Uint8Array>;
44
57
  /**
45
- * Asynchronous variant of {@link verify}; same contract.
58
+ * Verifies an Ed25519 signature (asynchronous variant of
59
+ * {@link verify}; same contract).
46
60
  *
61
+ * @param signature - The 64-byte signature.
62
+ * @param message - The signed message bytes.
63
+ * @param publicKey - The 32-byte signer public key.
47
64
  * @param opts - Optional verification options, forwarded to the
48
65
  * underlying implementation.
66
+ * @returns A Promise resolving to `true` if the signature is valid,
67
+ * `false` otherwise.
68
+ * @throws `TypeError` if an input length is invalid.
69
+ * @throws `RangeError` if an input length is invalid.
49
70
  */
50
71
  export declare function verifyAsync(signature: Uint8Array, message: Uint8Array, publicKey: Uint8Array, opts?: Parameters<typeof ed.verifyAsync>[3]): Promise<boolean>;
51
72
  export {};
@@ -1 +1 @@
1
- {"version":3,"file":"ed25519.d.ts","sourceRoot":"","sources":["../../src/crypto/ed25519.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAE/B,wEAAwE;AACxE,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAE/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,GAAG,UAAU,CAE5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CACpB,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,EACrB,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAET;AAED;;GAEG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAEnF;AAED;;GAEG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAEhG;AAED;;;;;GAKG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,EACrB,IAAI,CAAC,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAC1C,OAAO,CAAC,OAAO,CAAC,CAElB"}
1
+ {"version":3,"file":"ed25519.d.ts","sourceRoot":"","sources":["../../src/crypto/ed25519.ts"],"names":[],"mappings":"AAmBA,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAE/B,wEAAwE;AACxE,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,UAAU,GAAG,UAAU,CAE/D;AAED;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,GAAG,UAAU,CAE5E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,MAAM,CACpB,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,EACrB,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAET;AAED;;;;;;;;GAQG;AACH,wBAAsB,iBAAiB,CAAC,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAEnF;AAED;;;;;;;;;GASG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC,CAEhG;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAsB,WAAW,CAC/B,SAAS,EAAE,UAAU,EACrB,OAAO,EAAE,UAAU,EACnB,SAAS,EAAE,UAAU,EACrB,IAAI,CAAC,EAAE,UAAU,CAAC,OAAO,EAAE,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC,GAC1C,OAAO,CAAC,OAAO,CAAC,CAElB"}
@@ -1,9 +1,21 @@
1
1
  // packages/core/src/crypto/ed25519.ts
2
2
  //
3
3
  // Documented wrappers around the @noble/ed25519 primitives used by the
4
- // protocol. These are real functions rather than alias re-exports, so
5
- // generated documentation is fully owned by this package and never
6
- // inherits comments (or broken links) from the upstream library.
4
+ // protocol. These are real functions rather than alias re-exports, for
5
+ // two stable reasons (see also the BACKLOG.md house rule):
6
+ //
7
+ // 1. Documentation ownership — generated documentation is fully owned
8
+ // by this package and never inherits comments (or broken links)
9
+ // from the upstream library; TypeDoc renders these TSDoc blocks
10
+ // verbatim on the docs site (TSDoc is the source of truth).
11
+ // 2. Typing isolation — the upstream `ed` entity's typing produces
12
+ // TypeDoc warnings that fail the `treatWarningsAsErrors: true`
13
+ // docs build; local wrappers keep the public surface clean.
14
+ //
15
+ // The wrappers are public API surface (the `crypto` namespace,
16
+ // specs/v1.0.md §12) and are pinned by test/arch-cycle.spec.ts parity
17
+ // tests. Removing them is a breaking 2.0.0 decision — do not propose
18
+ // (PLAN amendment A5).
7
19
  import { ed } from './init.js';
8
20
  /**
9
21
  * Derives the Ed25519 public key for a private key (synchronous).
@@ -44,22 +56,43 @@ export function verify(signature, message, publicKey, opts) {
44
56
  return ed.verify(signature, message, publicKey, opts);
45
57
  }
46
58
  /**
47
- * Asynchronous variant of {@link getPublicKey}; same contract.
59
+ * Derives the Ed25519 public key for a private key (asynchronous
60
+ * variant of {@link getPublicKey}; same contract).
61
+ *
62
+ * @param privateKey - 32-byte Ed25519 private key.
63
+ * @returns A Promise resolving to the 32-byte public key.
64
+ * @throws `TypeError` if the key length is invalid.
65
+ * @throws `RangeError` if the key length is invalid.
48
66
  */
49
67
  export async function getPublicKeyAsync(privateKey) {
50
68
  return ed.getPublicKeyAsync(privateKey);
51
69
  }
52
70
  /**
53
- * Asynchronous variant of {@link sign}; same contract.
71
+ * Signs a message with an Ed25519 private key (asynchronous variant of
72
+ * {@link sign}; same contract).
73
+ *
74
+ * @param message - The bytes to sign.
75
+ * @param privateKey - 32-byte Ed25519 private key.
76
+ * @returns A Promise resolving to the 64-byte signature.
77
+ * @throws `TypeError` if an input length is invalid.
78
+ * @throws `RangeError` if an input length is invalid.
54
79
  */
55
80
  export async function signAsync(message, privateKey) {
56
81
  return ed.signAsync(message, privateKey);
57
82
  }
58
83
  /**
59
- * Asynchronous variant of {@link verify}; same contract.
84
+ * Verifies an Ed25519 signature (asynchronous variant of
85
+ * {@link verify}; same contract).
60
86
  *
87
+ * @param signature - The 64-byte signature.
88
+ * @param message - The signed message bytes.
89
+ * @param publicKey - The 32-byte signer public key.
61
90
  * @param opts - Optional verification options, forwarded to the
62
91
  * underlying implementation.
92
+ * @returns A Promise resolving to `true` if the signature is valid,
93
+ * `false` otherwise.
94
+ * @throws `TypeError` if an input length is invalid.
95
+ * @throws `RangeError` if an input length is invalid.
63
96
  */
64
97
  export async function verifyAsync(signature, message, publicKey, opts) {
65
98
  return ed.verifyAsync(signature, message, publicKey, opts);
@@ -1 +1 @@
1
- {"version":3,"file":"ed25519.js","sourceRoot":"","sources":["../../src/crypto/ed25519.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,uEAAuE;AACvE,sEAAsE;AACtE,mEAAmE;AACnE,iEAAiE;AAEjE,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAK/B;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,UAAsB;IACjD,OAAO,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,IAAI,CAAC,OAAmB,EAAE,UAAsB;IAC9D,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CACpB,SAAqB,EACrB,OAAmB,EACnB,SAAqB,EACrB,IAAiB;IAEjB,OAAO,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;AACxD,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,UAAsB;IAC5D,OAAO,EAAE,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;AAC1C,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAmB,EAAE,UAAsB;IACzE,OAAO,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,SAAqB,EACrB,OAAmB,EACnB,SAAqB,EACrB,IAA2C;IAE3C,OAAO,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;AAC7D,CAAC"}
1
+ {"version":3,"file":"ed25519.js","sourceRoot":"","sources":["../../src/crypto/ed25519.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,EAAE;AACF,uEAAuE;AACvE,uEAAuE;AACvE,2DAA2D;AAC3D,EAAE;AACF,sEAAsE;AACtE,mEAAmE;AACnE,mEAAmE;AACnE,+DAA+D;AAC/D,mEAAmE;AACnE,kEAAkE;AAClE,+DAA+D;AAC/D,EAAE;AACF,+DAA+D;AAC/D,sEAAsE;AACtE,qEAAqE;AACrE,uBAAuB;AAEvB,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAK/B;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,UAAsB;IACjD,OAAO,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;AACrC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,IAAI,CAAC,OAAmB,EAAE,UAAsB;IAC9D,OAAO,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AACtC,CAAC;AAED;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,MAAM,CACpB,SAAqB,EACrB,OAAmB,EACnB,SAAqB,EACrB,IAAiB;IAEjB,OAAO,EAAE,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;AACxD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CAAC,UAAsB;IAC5D,OAAO,EAAE,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,OAAmB,EAAE,UAAsB;IACzE,OAAO,EAAE,CAAC,SAAS,CAAC,OAAO,EAAE,UAAU,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,SAAqB,EACrB,OAAmB,EACnB,SAAqB,EACrB,IAA2C;IAE3C,OAAO,EAAE,CAAC,WAAW,CAAC,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,CAAC;AAC7D,CAAC"}
@@ -1,4 +1,3 @@
1
- import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js';
2
1
  /**
3
2
  * HKDF-SHA256 wrapper for me2em protocol
4
3
  *
@@ -9,5 +8,15 @@ import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js';
9
8
  * @returns Derived key as Uint8Array
10
9
  */
11
10
  export declare function hkdf(ikm: Uint8Array, salt: Uint8Array, info: Uint8Array, length: number): Uint8Array;
12
- export { nobleSha256 as sha256 };
11
+ /**
12
+ * SHA-256 hash function (wrapper over `@noble/hashes/sha2`).
13
+ *
14
+ * Exposed as a building block for application-side tooling that needs
15
+ * the same hash the protocol's derivation uses; the derivation module
16
+ * consumes it internally.
17
+ *
18
+ * @param input - The bytes to hash.
19
+ * @returns The 32-byte SHA-256 digest.
20
+ */
21
+ export declare function sha256(input: Uint8Array): Uint8Array;
13
22
  //# sourceMappingURL=hkdf.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"hkdf.d.ts","sourceRoot":"","sources":["../../src/crypto/hkdf.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAClB,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GACb,UAAU,CAEZ;AAED,OAAO,EAAE,WAAW,IAAI,MAAM,EAAE,CAAC"}
1
+ {"version":3,"file":"hkdf.d.ts","sourceRoot":"","sources":["../../src/crypto/hkdf.ts"],"names":[],"mappings":"AAKA;;;;;;;;GAQG;AACH,wBAAgB,IAAI,CAClB,GAAG,EAAE,UAAU,EACf,IAAI,EAAE,UAAU,EAChB,IAAI,EAAE,UAAU,EAChB,MAAM,EAAE,MAAM,GACb,UAAU,CAEZ;AAED;;;;;;;;;GASG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,CAEpD"}
@@ -13,5 +13,17 @@ import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js';
13
13
  export function hkdf(ikm, salt, info, length) {
14
14
  return nobleHkdf(nobleSha256, ikm, salt, info, length);
15
15
  }
16
- export { nobleSha256 as sha256 };
16
+ /**
17
+ * SHA-256 hash function (wrapper over `@noble/hashes/sha2`).
18
+ *
19
+ * Exposed as a building block for application-side tooling that needs
20
+ * the same hash the protocol's derivation uses; the derivation module
21
+ * consumes it internally.
22
+ *
23
+ * @param input - The bytes to hash.
24
+ * @returns The 32-byte SHA-256 digest.
25
+ */
26
+ export function sha256(input) {
27
+ return nobleSha256(input);
28
+ }
17
29
  //# sourceMappingURL=hkdf.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"hkdf.js","sourceRoot":"","sources":["../../src/crypto/hkdf.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,UAAU,IAAI,CAClB,GAAe,EACf,IAAgB,EAChB,IAAgB,EAChB,MAAc;IAEd,OAAO,SAAS,CAAC,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC;AAED,OAAO,EAAE,WAAW,IAAI,MAAM,EAAE,CAAC"}
1
+ {"version":3,"file":"hkdf.js","sourceRoot":"","sources":["../../src/crypto/hkdf.ts"],"names":[],"mappings":"AAAA,mCAAmC;AAEnC,OAAO,EAAE,IAAI,IAAI,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAC1D,OAAO,EAAE,MAAM,IAAI,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,UAAU,IAAI,CAClB,GAAe,EACf,IAAgB,EAChB,IAAgB,EAChB,MAAc;IAEd,OAAO,SAAS,CAAC,WAAW,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,MAAM,CAAC,KAAiB;IACtC,OAAO,WAAW,CAAC,KAAK,CAAC,CAAC;AAC5B,CAAC"}
@@ -1,4 +1,29 @@
1
+ /**
2
+ * The `crypto` namespace: low-level cryptographic primitives and the
3
+ * derivation module of the protocol.
4
+ *
5
+ * Two groups live here:
6
+ *
7
+ * - **Derivation (HKDF-SHA256, RFC 5869):** `deriveRootKey`,
8
+ * `deriveHandleKey`, `deriveSubHandleKey`, `rawX25519SharedSecret`,
9
+ * plus the frozen {@link DERIVATION_PATHS} info-string registry.
10
+ * These are the derivation functions of specs/v1.0.md §3 —
11
+ * deterministic, versioned, byte-pinned by the golden vectors.
12
+ * - **Raw primitives (Ed25519, RFC 8032):** `getPublicKey`, `sign`,
13
+ * `verify` and their `*Async` variants, plus the `hkdf` / `sha256`
14
+ * helpers — documented wrappers around the configured `@noble`
15
+ * backend (see the ed25519 module header for why they exist as real
16
+ * functions). Building blocks for tooling outside the token flow;
17
+ * the protocol itself signs through `Identity` / `Handle` /
18
+ * `SubHandle`, which implement `Signer`.
19
+ *
20
+ * The namespace is part of the frozen public API (specs/v1.0.md §12).
21
+ * Note: `derivePassword` and `deriveChannelKey` are `Handle` methods,
22
+ * not namespace members.
23
+ */
1
24
  export * from './ed25519.js';
2
25
  export * from './hkdf.js';
3
26
  export * from './derivation-paths.js';
27
+ export * from './derivation.js';
28
+ export * from './ecdh.js';
4
29
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AACA,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,uBAAuB,CAAC"}
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC"}
@@ -1,5 +1,30 @@
1
1
  // packages/core/src/crypto/index.ts
2
+ /**
3
+ * The `crypto` namespace: low-level cryptographic primitives and the
4
+ * derivation module of the protocol.
5
+ *
6
+ * Two groups live here:
7
+ *
8
+ * - **Derivation (HKDF-SHA256, RFC 5869):** `deriveRootKey`,
9
+ * `deriveHandleKey`, `deriveSubHandleKey`, `rawX25519SharedSecret`,
10
+ * plus the frozen {@link DERIVATION_PATHS} info-string registry.
11
+ * These are the derivation functions of specs/v1.0.md §3 —
12
+ * deterministic, versioned, byte-pinned by the golden vectors.
13
+ * - **Raw primitives (Ed25519, RFC 8032):** `getPublicKey`, `sign`,
14
+ * `verify` and their `*Async` variants, plus the `hkdf` / `sha256`
15
+ * helpers — documented wrappers around the configured `@noble`
16
+ * backend (see the ed25519 module header for why they exist as real
17
+ * functions). Building blocks for tooling outside the token flow;
18
+ * the protocol itself signs through `Identity` / `Handle` /
19
+ * `SubHandle`, which implement `Signer`.
20
+ *
21
+ * The namespace is part of the frozen public API (specs/v1.0.md §12).
22
+ * Note: `derivePassword` and `deriveChannelKey` are `Handle` methods,
23
+ * not namespace members.
24
+ */
2
25
  export * from './ed25519.js';
3
26
  export * from './hkdf.js';
4
27
  export * from './derivation-paths.js';
28
+ export * from './derivation.js';
29
+ export * from './ecdh.js';
5
30
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AACpC,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,uBAAuB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;AAEpC;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC;AAC1B,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,WAAW,CAAC"}
@@ -0,0 +1,24 @@
1
+ import { AttestationError } from './errors.js';
2
+ /**
3
+ * Thrown when a method that requires key material is called on an
4
+ * {@link Identity} or a {@link Handle}/{@link SubHandle} that has been
5
+ * disposed via {@link Identity.dispose} / {@link Handle.dispose}.
6
+ *
7
+ * The private key bytes are zeroized by `dispose()`; calling a capability
8
+ * method afterwards is always a programming error, never a recoverable
9
+ * state — match on `e.name === 'DisposedError'` (or `instanceof`).
10
+ * As an {@link AttestationError} subclass it carries `code === 'DISPOSED'`
11
+ * and `level === 'FORMAT'`.
12
+ *
13
+ * @category Errors
14
+ */
15
+ export declare class DisposedError extends AttestationError {
16
+ /** Name of the disposed class, e.g. `'Identity'`, `'Handle'`, `'SubHandle'`. */
17
+ readonly className: string;
18
+ /**
19
+ * @param className - Name of the disposed class, used in the message and
20
+ * exposed as {@link DisposedError.className}.
21
+ */
22
+ constructor(className: string);
23
+ }
24
+ //# sourceMappingURL=disposed-error.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"disposed-error.d.ts","sourceRoot":"","sources":["../src/disposed-error.ts"],"names":[],"mappings":"AAYA,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAc,SAAQ,gBAAgB;IACjD,gFAAgF;IAChF,SAAgB,SAAS,EAAE,MAAM,CAAC;IAElC;;;OAGG;gBACS,SAAS,EAAE,MAAM;CAS9B"}
@@ -0,0 +1,39 @@
1
+ // disposed-error.ts
2
+ //
3
+ // Thrown by Identity/Handle/SubHandle methods that require key material
4
+ // after the object has been disposed. Informational getters (name, path,
5
+ // public key, metadata) deliberately keep working after dispose() — only
6
+ // capabilities are revoked.
7
+ //
8
+ // Since PR-7 the class extends {@link AttestationError} with the
9
+ // `DISPOSED` code (level `FORMAT`), so the whole package surface is
10
+ // catchable as a single error type while `instanceof DisposedError`
11
+ // keeps working for targeted handling.
12
+ import { AttestationError } from './errors.js';
13
+ /**
14
+ * Thrown when a method that requires key material is called on an
15
+ * {@link Identity} or a {@link Handle}/{@link SubHandle} that has been
16
+ * disposed via {@link Identity.dispose} / {@link Handle.dispose}.
17
+ *
18
+ * The private key bytes are zeroized by `dispose()`; calling a capability
19
+ * method afterwards is always a programming error, never a recoverable
20
+ * state — match on `e.name === 'DisposedError'` (or `instanceof`).
21
+ * As an {@link AttestationError} subclass it carries `code === 'DISPOSED'`
22
+ * and `level === 'FORMAT'`.
23
+ *
24
+ * @category Errors
25
+ */
26
+ export class DisposedError extends AttestationError {
27
+ /** Name of the disposed class, e.g. `'Identity'`, `'Handle'`, `'SubHandle'`. */
28
+ className;
29
+ /**
30
+ * @param className - Name of the disposed class, used in the message and
31
+ * exposed as {@link DisposedError.className}.
32
+ */
33
+ constructor(className) {
34
+ super('DISPOSED', 'FORMAT', `${className} has been disposed; its key material has been zeroized`);
35
+ this.name = 'DisposedError';
36
+ this.className = className;
37
+ }
38
+ }
39
+ //# sourceMappingURL=disposed-error.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"disposed-error.js","sourceRoot":"","sources":["../src/disposed-error.ts"],"names":[],"mappings":"AAAA,oBAAoB;AACpB,EAAE;AACF,wEAAwE;AACxE,yEAAyE;AACzE,yEAAyE;AACzE,4BAA4B;AAC5B,EAAE;AACF,iEAAiE;AACjE,oEAAoE;AACpE,oEAAoE;AACpE,uCAAuC;AAEvC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAE/C;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,aAAc,SAAQ,gBAAgB;IACjD,gFAAgF;IAChE,SAAS,CAAS;IAElC;;;OAGG;IACH,YAAY,SAAiB;QAC3B,KAAK,CACH,UAAU,EACV,QAAQ,EACR,GAAG,SAAS,wDAAwD,CACrE,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;IAC7B,CAAC;CACF"}
@@ -0,0 +1,67 @@
1
+ /**
2
+ * Machine-readable failure codes for the {@link AttestationError} type.
3
+ *
4
+ * Verification-mode codes (see specs/v1.0.md §7.2): `MALFORMED`,
5
+ * `BAD_SIGNATURE`, `EXPIRED`, `NOT_YET_VALID`, `REVOKED`,
6
+ * `PATH_MISMATCH`, `NAME_NOT_PERMITTED`, `SCOPE_EXCEEDED`,
7
+ * `AUDIENCE_NOT_PERMITTED`, `TTL_EXCEEDED`, `CHAIN_INCOMPLETE`,
8
+ * `SUBJECT_MISMATCH`, `SESSION_OUTLIVES_ATTESTATION`.
9
+ *
10
+ * Library-level codes outside the verification table: `MAX_DEPTH_EXCEEDED`
11
+ * (derivation-tree limit — a leaf {@link SubHandle} cannot derive
12
+ * children) and `DISPOSED` (a capability method was called on a disposed
13
+ * {@link Identity}/{@link Handle}).
14
+ */
15
+ export type AttestationErrorCode = 'MALFORMED' | 'BAD_SIGNATURE' | 'EXPIRED' | 'NOT_YET_VALID' | 'REVOKED' | 'PATH_MISMATCH' | 'NAME_NOT_PERMITTED' | 'SCOPE_EXCEEDED' | 'AUDIENCE_NOT_PERMITTED' | 'TTL_EXCEEDED' | 'CHAIN_INCOMPLETE' | 'SUBJECT_MISMATCH' | 'SESSION_OUTLIVES_ATTESTATION' | 'MAX_DEPTH_EXCEEDED' | 'DISPOSED';
16
+ /**
17
+ * The layer that produced an {@link AttestationError}.
18
+ *
19
+ * `ROOT` / `HANDLE_ATTESTATION` / `SUB_ATTESTATION` identify the
20
+ * attestation-chain level; `SESSION` identifies the session token or
21
+ * session-constraint layer; `FORMAT` identifies structural/usage
22
+ * failures detected before any signature or trust material is consulted
23
+ * (token shape, field validation, derivation-tree and lifecycle rules).
24
+ */
25
+ export type AttestationLevel = 'ROOT' | 'HANDLE_ATTESTATION' | 'SUB_ATTESTATION' | 'SESSION' | 'FORMAT';
26
+ /**
27
+ * The single error type thrown by @me2em/core: a failure with a stable
28
+ * `code`, the `level` that produced it and a message prefixed with
29
+ * `[<level>/<code>]` for human diagnostics.
30
+ *
31
+ * Every failure — including token parsing, issuance validation and
32
+ * `Session.verifyStateless` — throws this type; there is no plain-`Error`
33
+ * path left in the package. `DisposedError` is a subclass with the
34
+ * `DISPOSED` code, so a single `catch (e) { if (e instanceof
35
+ * AttestationError) … }` covers the whole surface.
36
+ *
37
+ * @example
38
+ * ```ts
39
+ * import { AttestationError } from '@me2em/core';
40
+ *
41
+ * try {
42
+ * await Session.verifyAttested(token, rootPub, chain, 'ev-app.com');
43
+ * } catch (e) {
44
+ * if (e instanceof AttestationError) {
45
+ * // e.g. code 'SCOPE_EXCEEDED', level 'SESSION'
46
+ * log.warn(`${e.level}/${e.code}`);
47
+ * }
48
+ * throw new Error('Unauthorized');
49
+ * }
50
+ * ```
51
+ *
52
+ * @category Errors
53
+ */
54
+ export declare class AttestationError extends Error {
55
+ /** Stable machine-readable failure code — match on this, not on messages. */
56
+ readonly code: AttestationErrorCode;
57
+ /** Layer that produced the failure (see {@link AttestationLevel}). */
58
+ readonly level: AttestationLevel;
59
+ /**
60
+ * @param code - Machine-readable failure code.
61
+ * @param level - Layer that produced the failure.
62
+ * @param msg - Human-readable description; the thrown message is
63
+ * prefixed with `[<level>/<code>]`.
64
+ */
65
+ constructor(code: AttestationErrorCode, level: AttestationLevel, msg: string);
66
+ }
67
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAQA;;;;;;;;;;;;;GAaG;AACH,MAAM,MAAM,oBAAoB,GAC5B,WAAW,GAAG,eAAe,GAAG,SAAS,GAAG,eAAe,GAC3D,SAAS,GAAG,eAAe,GAAG,oBAAoB,GAClD,gBAAgB,GAAG,wBAAwB,GAAG,cAAc,GAC5D,kBAAkB,GAAG,kBAAkB,GAAG,8BAA8B,GACxE,oBAAoB,GAAG,UAAU,CAAC;AAEtC;;;;;;;;GAQG;AACH,MAAM,MAAM,gBAAgB,GACxB,MAAM,GAAG,oBAAoB,GAAG,iBAAiB,GAAG,SAAS,GAAG,QAAQ,CAAC;AAE7E;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,6EAA6E;IAC7E,SAAgB,IAAI,EAAE,oBAAoB,CAAC;IAC3C,sEAAsE;IACtE,SAAgB,KAAK,EAAE,gBAAgB,CAAC;IAExC;;;;;OAKG;gBACS,IAAI,EAAE,oBAAoB,EAAE,KAAK,EAAE,gBAAgB,EAAE,GAAG,EAAE,MAAM;CAM7E"}
package/dist/errors.js ADDED
@@ -0,0 +1,54 @@
1
+ // errors.ts
2
+ //
3
+ // Unified error model for @me2em/core (PR-7): every failure the library
4
+ // throws is an {@link AttestationError} carrying a stable
5
+ // machine-readable `code` and the verification `level` that produced it.
6
+ // Integrators match on `code`/`level`, never on message text
7
+ // (specs/v1.0.md §7.2).
8
+ /**
9
+ * The single error type thrown by @me2em/core: a failure with a stable
10
+ * `code`, the `level` that produced it and a message prefixed with
11
+ * `[<level>/<code>]` for human diagnostics.
12
+ *
13
+ * Every failure — including token parsing, issuance validation and
14
+ * `Session.verifyStateless` — throws this type; there is no plain-`Error`
15
+ * path left in the package. `DisposedError` is a subclass with the
16
+ * `DISPOSED` code, so a single `catch (e) { if (e instanceof
17
+ * AttestationError) … }` covers the whole surface.
18
+ *
19
+ * @example
20
+ * ```ts
21
+ * import { AttestationError } from '@me2em/core';
22
+ *
23
+ * try {
24
+ * await Session.verifyAttested(token, rootPub, chain, 'ev-app.com');
25
+ * } catch (e) {
26
+ * if (e instanceof AttestationError) {
27
+ * // e.g. code 'SCOPE_EXCEEDED', level 'SESSION'
28
+ * log.warn(`${e.level}/${e.code}`);
29
+ * }
30
+ * throw new Error('Unauthorized');
31
+ * }
32
+ * ```
33
+ *
34
+ * @category Errors
35
+ */
36
+ export class AttestationError extends Error {
37
+ /** Stable machine-readable failure code — match on this, not on messages. */
38
+ code;
39
+ /** Layer that produced the failure (see {@link AttestationLevel}). */
40
+ level;
41
+ /**
42
+ * @param code - Machine-readable failure code.
43
+ * @param level - Layer that produced the failure.
44
+ * @param msg - Human-readable description; the thrown message is
45
+ * prefixed with `[<level>/<code>]`.
46
+ */
47
+ constructor(code, level, msg) {
48
+ super(`[${level}/${code}] ${msg}`);
49
+ this.name = 'AttestationError';
50
+ this.code = code;
51
+ this.level = level;
52
+ }
53
+ }
54
+ //# sourceMappingURL=errors.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,YAAY;AACZ,EAAE;AACF,wEAAwE;AACxE,0DAA0D;AAC1D,yEAAyE;AACzE,6DAA6D;AAC7D,wBAAwB;AAmCxB;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACzC,6EAA6E;IAC7D,IAAI,CAAuB;IAC3C,sEAAsE;IACtD,KAAK,CAAmB;IAExC;;;;;OAKG;IACH,YAAY,IAA0B,EAAE,KAAuB,EAAE,GAAW;QAC1E,KAAK,CAAC,IAAI,KAAK,IAAI,IAAI,KAAK,GAAG,EAAE,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;IACrB,CAAC;CACF"}