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

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 +179 -32
  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 +10 -1
  27. package/dist/crypto/hkdf.d.ts.map +1 -1
  28. package/dist/crypto/hkdf.js +10 -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 +15 -11
  55. package/dist/seed.d.ts.map +1 -1
  56. package/dist/seed.js +23 -17
  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 +10 -4
  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 +10 -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 +11 -6
  88. package/src/seed.ts +27 -17
  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
@@ -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"}
package/dist/handle.d.ts CHANGED
@@ -1,5 +1,6 @@
1
- import type { SubHandleMetadata, SubHandle } from './subhandle.js';
2
1
  import { Attestation, type AttestationGrant } from './attestation.js';
2
+ import type { Signer } from './types.js';
3
+ import { INSPECT_SYMBOL } from './util.js';
3
4
  /**
4
5
  * Metadata associated with a {@link Handle}.
5
6
  *
@@ -17,6 +18,59 @@ export interface HandleMetadata {
17
18
  /** Arbitrary additional fields. */
18
19
  [key: string]: unknown;
19
20
  }
21
+ /**
22
+ * Options for {@link Handle.derivePassword}.
23
+ *
24
+ * All fields are optional; the defaults reproduce the frozen v1.0
25
+ * derivation exactly (specs/v1.0.md §3).
26
+ *
27
+ * @category Types
28
+ */
29
+ export interface DerivePasswordOptions {
30
+ /**
31
+ * Positive integer revision of the secret (default `1`).
32
+ *
33
+ * Revision `1` — the initial secret — is byte-identical to the
34
+ * pre-revision derivation. Revision `N ≥ 2` derives a secret that is
35
+ * cryptographically independent of revision 1 for the same context:
36
+ * the sanctioned rotation path when a credential leaks, without
37
+ * changing the context string.
38
+ *
39
+ * Canonical by construction: NFKC normalization applies to the string
40
+ * `context` only. Integers have no Unicode representation, so no
41
+ * normalization is needed or performed on `revision`.
42
+ */
43
+ revision?: number;
44
+ /**
45
+ * Length of the derived raw bytes in `[1, 8160]` (default `16` —
46
+ * ≈ 22 base64url chars). Upper bound is the RFC 5869 HKDF-SHA256
47
+ * limit (`255 × 32`); note the output is prefix-stable, so the first
48
+ * `n` bytes of a longer derivation equal the `n`-byte derivation.
49
+ */
50
+ byteLength?: number;
51
+ }
52
+ /**
53
+ * Options for {@link Handle.deriveChannelKey}.
54
+ *
55
+ * All fields are optional; the defaults reproduce the frozen v1.0
56
+ * derivation exactly (specs/v1.0.md §3).
57
+ *
58
+ * @category Types
59
+ */
60
+ export interface DeriveChannelKeyOptions {
61
+ /**
62
+ * Positive integer revision of the channel key (default `1`).
63
+ *
64
+ * Revision `N ≥ 2` derives a key that is independent of revision 1 for
65
+ * the same context — rotate a compromised channel by bumping the
66
+ * revision on **both** peers in lockstep.
67
+ *
68
+ * Canonical by construction: NFKC normalization applies to the string
69
+ * `context` only. Integers have no Unicode representation, so no
70
+ * normalization is needed or performed on `revision`.
71
+ */
72
+ revision?: number;
73
+ }
20
74
  /**
21
75
  * Represents a context-specific cryptographic handle derived from an {@link Identity}.
22
76
  *
@@ -29,13 +83,15 @@ export interface HandleMetadata {
29
83
  * (e.g., an IoT device deriving keys for its components). The private key
30
84
  * **never leaves the Handle** — derivation is performed internally using HKDF.
31
85
  *
86
+ * Handles own their lifecycle: {@link Handle.dispose} zeroizes the private
87
+ * key, after which every capability method throws a {@link DisposedError}.
88
+ * Serialization (`JSON.stringify`, console inspection) is redacted and never
89
+ * emits key material.
90
+ *
32
91
  * @category Core Primitives
33
92
  */
34
- export declare class Handle {
35
- private readonly privateKey;
36
- private readonly publicKey;
37
- private readonly _name;
38
- private readonly _metadata?;
93
+ export declare class Handle implements Signer {
94
+ #private;
39
95
  /**
40
96
  * Creates a new Handle instance.
41
97
  *
@@ -43,8 +99,12 @@ export declare class Handle {
43
99
  * {@link Handle.deriveSubHandle}. Direct construction is discouraged.
44
100
  *
45
101
  * @param privateKey - The 32-byte Ed25519 private key for this handle.
102
+ * Copied on input — later mutation of the caller's buffer has no effect.
46
103
  * @param name - The context name this handle represents.
47
104
  * @param metadata - Optional metadata associated with this handle.
105
+ * Custom metadata is deep-copied (JSON-safe structures up to depth 8);
106
+ * non-plain values (Date, Map, functions) remain shared by reference —
107
+ * same caveats as `getSubMetadata()`.
48
108
  */
49
109
  constructor(privateKey: Uint8Array, name: string, metadata?: HandleMetadata);
50
110
  /**
@@ -55,15 +115,22 @@ export declare class Handle {
55
115
  */
56
116
  getId(): string;
57
117
  /**
58
- * Cryptographically signs arbitrary data using the Handle's private key.
118
+ * Cryptographically signs arbitrary data using the Handle's private key
119
+ * (implements {@link Signer} — a `Handle` is acceptable as the `signer`
120
+ * argument of {@link Attestation.issue}).
59
121
  *
60
122
  * @param data - The data to be signed, as a Uint8Array.
61
123
  * @returns A Promise resolving to the Ed25519 signature as a Uint8Array.
124
+ * @throws {DisposedError} If the Handle has been disposed.
62
125
  */
63
126
  sign(data: Uint8Array): Promise<Uint8Array>;
64
127
  /**
65
128
  * Verifies an Ed25519 signature against the provided data and public key.
66
129
  *
130
+ * A signature whose length differs from the 64-byte Ed25519 size is
131
+ * rejected with `false` before any crypto runs (PR-7 pre-check) — the
132
+ * method therefore never throws for short/long signatures.
133
+ *
67
134
  * @param signature - The signature to verify (Uint8Array).
68
135
  * @param data - The original data that was signed (Uint8Array).
69
136
  * @param publicKey - The public key to verify against (Uint8Array).
@@ -72,9 +139,18 @@ export declare class Handle {
72
139
  static verify(signature: Uint8Array, data: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
73
140
  /** @returns The context name associated with this Handle. */
74
141
  getName(): string;
75
- /** @returns The metadata object associated with this Handle. */
142
+ /**
143
+ * @returns A deep copy of the metadata object associated with this
144
+ * Handle — mutating the returned object does not affect the Handle.
145
+ * Custom metadata is deep-copied (JSON-safe structures up to depth 8);
146
+ * non-plain values (Date, Map, functions) remain shared by reference —
147
+ * same caveats as `getSubMetadata()`.
148
+ */
76
149
  getMetadata(): HandleMetadata | undefined;
77
- /** @returns A Uint8Array containing the 32-byte Ed25519 public key. */
150
+ /**
151
+ * @returns A copy of the 32-byte Ed25519 public key — mutating the
152
+ * returned array does not affect the Handle.
153
+ */
78
154
  getPublicKey(): Uint8Array;
79
155
  /** @returns The derivation path, or undefined for Handle (only SubHandle has a path). */
80
156
  getPath(): string[] | undefined;
@@ -148,16 +224,32 @@ export declare class Handle {
148
224
  *
149
225
  * The private key **never leaves this class**, ensuring maximum security.
150
226
  *
227
+ * The `context` is canonicalized NFKC → lowercase → trim before use
228
+ * (`' GitHub '`, `'github'` and `'GitHub'` yield the same secret).
229
+ * NFKC applies to the string `context` only — `options.revision` is
230
+ * an integer and is canonical by construction (no normalization).
231
+ *
232
+ * **Revision model (since 0.8.0, D3):** `options.revision` (positive
233
+ * integer, default `1`) selects an independent secret for the same
234
+ * context — revision 1 is the initial secret, revision 2, 3, … are for
235
+ * rotation (e.g. after a breach). Revision 1 is byte-identical to the
236
+ * pre-revision v1.0 derivation.
237
+ *
151
238
  * @param context - A unique identifier for the service (e.g., `'google'`, `'github'`).
152
- * @param length - Length of the derived raw bytes (default: 16 bytes ≈ 22 chars base64url).
239
+ * @param options - Derivation options.
153
240
  * @returns A URL-safe base64 string suitable for use as a strong password.
241
+ * @throws AttestationError `MALFORMED`/`FORMAT` if `revision` is not a
242
+ * positive integer, `byteLength` is not an integer in `[1, 8160]`, or
243
+ * the context is empty after canonicalization.
154
244
  *
155
245
  * @example
156
246
  * ```ts
157
- * const githubPassword = handle.derivePassword('github', 20);
247
+ * const githubPassword = handle.derivePassword('github', { byteLength: 20 });
248
+ * // after rotating the GitHub credential:
249
+ * const rotated = handle.derivePassword('github', { revision: 2 });
158
250
  * ```
159
251
  */
160
- derivePassword(context: string, length?: number): string;
252
+ derivePassword(context: string, options?: DerivePasswordOptions): string;
161
253
  /**
162
254
  * Derives a symmetric 256-bit channel key for secure communication between
163
255
  * the Identity (controller) and this Handle (device/context).
@@ -168,18 +260,33 @@ export declare class Handle {
168
260
  *
169
261
  * This enables zero-knowledge encrypted channels without key exchange protocols.
170
262
  *
263
+ * The `context` is canonicalized NFKC → lowercase → trim before use.
264
+ * NFKC applies to the string `context` only — `options.revision` is
265
+ * an integer and is canonical by construction (no normalization).
266
+ *
267
+ * **Revision model (since 0.8.0, D3):** `options.revision` (positive
268
+ * integer, default `1`) selects an independent 32-byte key for the same
269
+ * context — the sanctioned rotation path for a compromised channel
270
+ * without changing the context string. Revision 1 is byte-identical to
271
+ * the pre-revision v1.0 derivation.
272
+ *
171
273
  * @param context - Channel identifier for domain separation (e.g., `'drone-001'`).
172
- * Both parties **MUST** use the same context.
274
+ * Both parties **MUST** use the same context **and** the same revision.
275
+ * @param options - Derivation options.
173
276
  * @returns A 32-byte Uint8Array suitable for AES-256-GCM encryption.
277
+ * @throws AttestationError `MALFORMED`/`FORMAT` if `revision` is not a
278
+ * positive integer or the context is empty after canonicalization.
174
279
  *
175
280
  * @example
176
281
  * ```ts
177
282
  * // AES-GCM helpers are application-side; the protocol provides
178
283
  * // only the key:
179
284
  * const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
285
+ * // after rotating the channel (both sides migrate in lockstep):
286
+ * const rotatedKey = droneHandle.deriveChannelKey('telemetry-v1', { revision: 2 });
180
287
  * ```
181
288
  */
182
- deriveChannelKey(context: string): Uint8Array;
289
+ deriveChannelKey(context: string, options?: DeriveChannelKeyOptions): Uint8Array;
183
290
  /**
184
291
  * Derives a shared secret using ECDH (X25519) for P2P key exchange.
185
292
  *
@@ -197,5 +304,184 @@ export declare class Handle {
197
304
  * ```
198
305
  */
199
306
  deriveSharedSecret(otherPublicKey: Uint8Array): Promise<Uint8Array>;
307
+ /**
308
+ * Permanently destroys this Handle's key material.
309
+ *
310
+ * The private key bytes are zeroized; afterwards every capability method
311
+ * ({@link sign}, {@link deriveSubHandle}, {@link attestSubHandle},
312
+ * {@link derivePassword}, {@link deriveChannelKey},
313
+ * {@link deriveSharedSecret}) throws a {@link DisposedError}.
314
+ * Informational getters ({@link getName}, {@link getId},
315
+ * {@link getPublicKey}, {@link getMetadata}) keep working — they never
316
+ * touch key material.
317
+ *
318
+ * SubHandles inherit `dispose()`. Calling it more than once is a no-op
319
+ * (idempotent).
320
+ */
321
+ dispose(): void;
322
+ /**
323
+ * Redacted serialization contract: `JSON.stringify(handle)` exposes only
324
+ * the object kind, the public identifier and the context name — never
325
+ * key material or metadata.
326
+ */
327
+ toJSON(): {
328
+ kind: string;
329
+ id: string;
330
+ name: string;
331
+ };
332
+ [INSPECT_SYMBOL](): string;
333
+ }
334
+ /**
335
+ * Metadata for a {@link SubHandle}, extending {@link HandleMetadata} with
336
+ * constraints that govern session creation.
337
+ *
338
+ * All constraint fields are optional. When present, they are enforced by
339
+ * {@link SubHandle.validateSessionOptions} at session creation time.
340
+ *
341
+ * @category Types
342
+ */
343
+ export interface SubHandleMetadata extends HandleMetadata {
344
+ /**
345
+ * Restricts the set of audiences this SubHandle may create sessions for.
346
+ * `undefined` = unrestricted; `[]` = deny all.
347
+ */
348
+ allowedAudiences?: string[];
349
+ /**
350
+ * Restricts the set of scopes this SubHandle may request in sessions.
351
+ * `undefined` = unrestricted; `[]` = deny all.
352
+ */
353
+ allowedScopes?: string[];
354
+ /**
355
+ * Maximum allowed TTL (in seconds) for sessions created by this SubHandle.
356
+ * Attempts to create a session with a larger TTL will be rejected.
357
+ */
358
+ maxSessionTtl?: number;
359
+ /**
360
+ * Unix timestamp (in seconds) at which this SubHandle itself expires.
361
+ * After this time, any attempt to create a session will fail.
362
+ * Useful for temporary access grants (e.g., contractor access for 2 weeks).
363
+ */
364
+ expiresAt?: number;
365
+ }
366
+ /**
367
+ * Represents a context-isolated child Handle in the Me2eM hierarchy.
368
+ *
369
+ * A SubHandle is always derived from a parent {@link Handle} and represents
370
+ * a leaf node in the derivation tree (MAX_DEPTH = 2). It inherits all
371
+ * cryptographic capabilities of Handle (signing, key derivation, etc.) but
372
+ * adds:
373
+ *
374
+ * - A **derivation path** (`[handleName, subName]`) carried in session tokens.
375
+ * - **Constraint enforcement** on audience, scopes, and TTL at session creation.
376
+ * - An optional **expiration timestamp** for temporary access grants.
377
+ *
378
+ * SubHandle is used for polymorphism in {@link Session}: both Handle and
379
+ * SubHandle can create and verify sessions, but SubHandle sessions carry
380
+ * the additional `hPath` field for hierarchical auditing.
381
+ *
382
+ * The class is defined in the same module as {@link Handle} on purpose
383
+ * (D4, PR-10): `SubHandle extends Handle` plus a static import of the
384
+ * subclass from `handle.ts` would form an ESM module cycle that crashes
385
+ * at import time depending on the graph root; co-location keeps the
386
+ * graph acyclic. `subhandle.ts` re-exports this class unchanged, so the
387
+ * public import paths are unaffected.
388
+ *
389
+ * @category Core Primitives
390
+ */
391
+ export declare class SubHandle extends Handle implements Signer {
392
+ #private;
393
+ /**
394
+ * Creates a new SubHandle instance.
395
+ *
396
+ * @internal Typically created via {@link Handle.deriveSubHandle} or
397
+ * {@link Identity.deriveSubHandle}. Direct construction is discouraged.
398
+ *
399
+ * @param privateKey - The 32-byte Ed25519 private key for this SubHandle.
400
+ * Copied on input by the Handle constructor.
401
+ * @param name - The SubHandle name.
402
+ * @param path - The derivation path, must have exactly 2 elements: `[handleName, subName]`.
403
+ * Copied on input — later mutation of the caller's array has no effect.
404
+ * @param subMetadata - Optional constraints and metadata.
405
+ * Copied on input (constraint arrays are duplicated).
406
+ * @throws {Error} If the path does not have exactly 2 elements.
407
+ */
408
+ constructor(privateKey: Uint8Array, name: string, path: string[], subMetadata?: SubHandleMetadata);
409
+ /**
410
+ * Returns the full derivation path of this SubHandle.
411
+ *
412
+ * @returns A copy of the path array, e.g. `["station-001", "connector-1"]`.
413
+ */
414
+ getPath(): string[];
415
+ /**
416
+ * Returns the derivation path as a slash-separated string.
417
+ *
418
+ * @returns The path string, e.g. `"station-001/connector-1"`.
419
+ */
420
+ getPathString(): string;
421
+ /**
422
+ * Returns the depth of this SubHandle in the derivation hierarchy.
423
+ *
424
+ * With MAX_DEPTH = 2, this is always `2` (Identity = 0, Handle = 1, SubHandle = 2).
425
+ *
426
+ * @returns The depth, always `2`.
427
+ */
428
+ getDepth(): number;
429
+ /**
430
+ * Returns whether this SubHandle is a leaf node.
431
+ *
432
+ * With MAX_DEPTH = 2, a SubHandle is **always** a leaf and cannot derive children.
433
+ *
434
+ * @returns Always `true`.
435
+ */
436
+ isLeaf(): boolean;
437
+ /**
438
+ * SubHandle is a leaf node (depth = 2) and cannot derive children.
439
+ * Overrides the inherited `Handle.deriveSubHandle` to throw
440
+ * `AttestationError` `MAX_DEPTH_EXCEEDED`/`FORMAT`.
441
+ */
442
+ deriveSubHandle(): Promise<never>;
443
+ /**
444
+ * Returns the SubHandle-specific metadata (constraints).
445
+ *
446
+ * The returned object is a **deep copy** (PR-7): JSON-safe nested
447
+ * structures (plain objects, arrays) are fully duplicated, so mutating
448
+ * the result — at any depth — cannot alter the constraints this
449
+ * SubHandle enforces. Non-plain values (Date, Map, class instances)
450
+ * are shared by reference; functions abort the deep copy and fall
451
+ * back to the shallow constraint-array-duplicating copy.
452
+ *
453
+ * @returns A deep copy of the SubHandleMetadata object.
454
+ */
455
+ getSubMetadata(): SubHandleMetadata;
456
+ /**
457
+ * Validates session options against this SubHandle's constraints.
458
+ *
459
+ * Called internally by {@link Session.create} before signing. Throws if
460
+ * any constraint is violated:
461
+ * - `audience` not in `allowedAudiences`
462
+ * - any `scope` not in `allowedScopes`
463
+ * - `ttl` exceeds `maxSessionTtl`
464
+ * - current time is past `expiresAt`
465
+ *
466
+ * @param options - The session options to validate.
467
+ * @throws {Error} If any constraint is violated.
468
+ */
469
+ validateSessionOptions(options: {
470
+ audience: string;
471
+ scopes: string[];
472
+ ttl: number;
473
+ }): void;
474
+ /**
475
+ * Redacted serialization contract: `JSON.stringify(sub)` exposes only the
476
+ * object kind, the public identifier, the name and the derivation path —
477
+ * never key material or constraint metadata.
478
+ */
479
+ toJSON(): {
480
+ kind: string;
481
+ id: string;
482
+ name: string;
483
+ path: string[];
484
+ };
485
+ [INSPECT_SYMBOL](): string;
200
486
  }
201
487
  //# sourceMappingURL=handle.d.ts.map