@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
package/src/errors.ts ADDED
@@ -0,0 +1,88 @@
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
+ /**
10
+ * Machine-readable failure codes for the {@link AttestationError} type.
11
+ *
12
+ * Verification-mode codes (see specs/v1.0.md §7.2): `MALFORMED`,
13
+ * `BAD_SIGNATURE`, `EXPIRED`, `NOT_YET_VALID`, `REVOKED`,
14
+ * `PATH_MISMATCH`, `NAME_NOT_PERMITTED`, `SCOPE_EXCEEDED`,
15
+ * `AUDIENCE_NOT_PERMITTED`, `TTL_EXCEEDED`, `CHAIN_INCOMPLETE`,
16
+ * `SUBJECT_MISMATCH`, `SESSION_OUTLIVES_ATTESTATION`.
17
+ *
18
+ * Library-level codes outside the verification table: `MAX_DEPTH_EXCEEDED`
19
+ * (derivation-tree limit — a leaf {@link SubHandle} cannot derive
20
+ * children) and `DISPOSED` (a capability method was called on a disposed
21
+ * {@link Identity}/{@link Handle}).
22
+ */
23
+ export type AttestationErrorCode =
24
+ | 'MALFORMED' | 'BAD_SIGNATURE' | 'EXPIRED' | 'NOT_YET_VALID'
25
+ | 'REVOKED' | 'PATH_MISMATCH' | 'NAME_NOT_PERMITTED'
26
+ | 'SCOPE_EXCEEDED' | 'AUDIENCE_NOT_PERMITTED' | 'TTL_EXCEEDED'
27
+ | 'CHAIN_INCOMPLETE' | 'SUBJECT_MISMATCH' | 'SESSION_OUTLIVES_ATTESTATION'
28
+ | 'MAX_DEPTH_EXCEEDED' | 'DISPOSED';
29
+
30
+ /**
31
+ * The layer that produced an {@link AttestationError}.
32
+ *
33
+ * `ROOT` / `HANDLE_ATTESTATION` / `SUB_ATTESTATION` identify the
34
+ * attestation-chain level; `SESSION` identifies the session token or
35
+ * session-constraint layer; `FORMAT` identifies structural/usage
36
+ * failures detected before any signature or trust material is consulted
37
+ * (token shape, field validation, derivation-tree and lifecycle rules).
38
+ */
39
+ export type AttestationLevel =
40
+ | 'ROOT' | 'HANDLE_ATTESTATION' | 'SUB_ATTESTATION' | 'SESSION' | 'FORMAT';
41
+
42
+ /**
43
+ * The single error type thrown by @me2em/core: a failure with a stable
44
+ * `code`, the `level` that produced it and a message prefixed with
45
+ * `[<level>/<code>]` for human diagnostics.
46
+ *
47
+ * Every failure — including token parsing, issuance validation and
48
+ * `Session.verifyStateless` — throws this type; there is no plain-`Error`
49
+ * path left in the package. `DisposedError` is a subclass with the
50
+ * `DISPOSED` code, so a single `catch (e) { if (e instanceof
51
+ * AttestationError) … }` covers the whole surface.
52
+ *
53
+ * @example
54
+ * ```ts
55
+ * import { AttestationError } from '@me2em/core';
56
+ *
57
+ * try {
58
+ * await Session.verifyAttested(token, rootPub, chain, 'ev-app.com');
59
+ * } catch (e) {
60
+ * if (e instanceof AttestationError) {
61
+ * // e.g. code 'SCOPE_EXCEEDED', level 'SESSION'
62
+ * log.warn(`${e.level}/${e.code}`);
63
+ * }
64
+ * throw new Error('Unauthorized');
65
+ * }
66
+ * ```
67
+ *
68
+ * @category Errors
69
+ */
70
+ export class AttestationError extends Error {
71
+ /** Stable machine-readable failure code — match on this, not on messages. */
72
+ public readonly code: AttestationErrorCode;
73
+ /** Layer that produced the failure (see {@link AttestationLevel}). */
74
+ public readonly level: AttestationLevel;
75
+
76
+ /**
77
+ * @param code - Machine-readable failure code.
78
+ * @param level - Layer that produced the failure.
79
+ * @param msg - Human-readable description; the thrown message is
80
+ * prefixed with `[<level>/<code>]`.
81
+ */
82
+ constructor(code: AttestationErrorCode, level: AttestationLevel, msg: string) {
83
+ super(`[${level}/${code}] ${msg}`);
84
+ this.name = 'AttestationError';
85
+ this.code = code;
86
+ this.level = level;
87
+ }
88
+ }