@me2em/core 0.4.4-alpha.2 → 0.7.0-alpha.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 (70) hide show
  1. package/README.md +294 -546
  2. package/dist/attestation.d.ts +151 -0
  3. package/dist/attestation.d.ts.map +1 -0
  4. package/dist/attestation.js +279 -0
  5. package/dist/attestation.js.map +1 -0
  6. package/dist/canonical-name.d.ts +3 -0
  7. package/dist/canonical-name.d.ts.map +1 -0
  8. package/dist/canonical-name.js +12 -0
  9. package/dist/canonical-name.js.map +1 -0
  10. package/dist/crypto/derivation-paths.d.ts +41 -0
  11. package/dist/crypto/derivation-paths.d.ts.map +1 -0
  12. package/dist/crypto/derivation-paths.js +50 -0
  13. package/dist/crypto/derivation-paths.js.map +1 -0
  14. package/dist/crypto/ed25519.d.ts +48 -8
  15. package/dist/crypto/ed25519.d.ts.map +1 -1
  16. package/dist/crypto/ed25519.js +63 -8
  17. package/dist/crypto/ed25519.js.map +1 -1
  18. package/dist/crypto/hkdf.d.ts.map +1 -1
  19. package/dist/crypto/hkdf.js +1 -0
  20. package/dist/crypto/hkdf.js.map +1 -1
  21. package/dist/crypto/index.d.ts +1 -0
  22. package/dist/crypto/index.d.ts.map +1 -1
  23. package/dist/crypto/index.js +2 -0
  24. package/dist/crypto/index.js.map +1 -1
  25. package/dist/crypto/init.d.ts.map +1 -1
  26. package/dist/crypto/init.js +1 -0
  27. package/dist/crypto/init.js.map +1 -1
  28. package/dist/handle.d.ts +149 -35
  29. package/dist/handle.d.ts.map +1 -1
  30. package/dist/handle.js +180 -40
  31. package/dist/handle.js.map +1 -1
  32. package/dist/identity.d.ts +99 -19
  33. package/dist/identity.d.ts.map +1 -1
  34. package/dist/identity.js +128 -32
  35. package/dist/identity.js.map +1 -1
  36. package/dist/index.d.ts +5 -1
  37. package/dist/index.d.ts.map +1 -1
  38. package/dist/index.js +4 -0
  39. package/dist/index.js.map +1 -1
  40. package/dist/seed.d.ts +38 -39
  41. package/dist/seed.d.ts.map +1 -1
  42. package/dist/seed.js +36 -41
  43. package/dist/seed.js.map +1 -1
  44. package/dist/session.d.ts +207 -17
  45. package/dist/session.d.ts.map +1 -1
  46. package/dist/session.js +428 -11
  47. package/dist/session.js.map +1 -1
  48. package/dist/subhandle.d.ts +126 -0
  49. package/dist/subhandle.d.ts.map +1 -0
  50. package/dist/subhandle.js +182 -0
  51. package/dist/subhandle.js.map +1 -0
  52. package/dist/util.d.ts +9 -0
  53. package/dist/util.d.ts.map +1 -0
  54. package/dist/util.js +34 -0
  55. package/dist/util.js.map +1 -0
  56. package/package.json +3 -3
  57. package/src/attestation.ts +364 -0
  58. package/src/canonical-name.ts +12 -0
  59. package/src/crypto/derivation-paths.ts +56 -0
  60. package/src/crypto/ed25519.ts +82 -8
  61. package/src/crypto/hkdf.ts +2 -0
  62. package/src/crypto/index.ts +3 -1
  63. package/src/crypto/init.ts +1 -0
  64. package/src/handle.ts +227 -42
  65. package/src/identity.ts +164 -35
  66. package/src/index.ts +5 -1
  67. package/src/seed.ts +59 -59
  68. package/src/session.ts +637 -24
  69. package/src/subhandle.ts +254 -0
  70. package/src/util.ts +35 -0
@@ -1,12 +1,67 @@
1
+ // packages/core/src/crypto/ed25519.ts
2
+ //
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.
1
7
  import { ed } from './init.js';
2
8
  /**
3
- * @internal
4
- * Low-level Ed25519 implementation wrapper.
9
+ * Derives the Ed25519 public key for a private key (synchronous).
10
+ *
11
+ * @param privateKey - 32-byte Ed25519 private key.
12
+ * @returns The 32-byte public key.
13
+ * @throws `TypeError` if the key length is invalid.
14
+ * @throws `RangeError` if the key length is invalid.
5
15
  */
6
- export const getPublicKey = ed.getPublicKey;
7
- export const sign = ed.sign;
8
- export const verify = ed.verify;
9
- export const getPublicKeyAsync = ed.getPublicKeyAsync;
10
- export const signAsync = ed.signAsync;
11
- export const verifyAsync = ed.verifyAsync;
16
+ export function getPublicKey(privateKey) {
17
+ return ed.getPublicKey(privateKey);
18
+ }
19
+ /**
20
+ * Signs a message with an Ed25519 private key (synchronous).
21
+ *
22
+ * @param message - The bytes to sign.
23
+ * @param privateKey - 32-byte Ed25519 private key.
24
+ * @returns The 64-byte signature.
25
+ * @throws `TypeError` if an input length is invalid.
26
+ * @throws `RangeError` if an input length is invalid.
27
+ */
28
+ export function sign(message, privateKey) {
29
+ return ed.sign(message, privateKey);
30
+ }
31
+ /**
32
+ * Verifies an Ed25519 signature (synchronous).
33
+ *
34
+ * @param signature - The 64-byte signature.
35
+ * @param message - The signed message bytes.
36
+ * @param publicKey - The 32-byte signer public key.
37
+ * @param opts - Optional verification options, forwarded to the
38
+ * underlying implementation.
39
+ * @returns `true` if the signature is valid, `false` otherwise.
40
+ * @throws `TypeError` if an input length is invalid.
41
+ * @throws `RangeError` if an input length is invalid.
42
+ */
43
+ export function verify(signature, message, publicKey, opts) {
44
+ return ed.verify(signature, message, publicKey, opts);
45
+ }
46
+ /**
47
+ * Asynchronous variant of {@link getPublicKey}; same contract.
48
+ */
49
+ export async function getPublicKeyAsync(privateKey) {
50
+ return ed.getPublicKeyAsync(privateKey);
51
+ }
52
+ /**
53
+ * Asynchronous variant of {@link sign}; same contract.
54
+ */
55
+ export async function signAsync(message, privateKey) {
56
+ return ed.signAsync(message, privateKey);
57
+ }
58
+ /**
59
+ * Asynchronous variant of {@link verify}; same contract.
60
+ *
61
+ * @param opts - Optional verification options, forwarded to the
62
+ * underlying implementation.
63
+ */
64
+ export async function verifyAsync(signature, message, publicKey, opts) {
65
+ return ed.verifyAsync(signature, message, publicKey, opts);
66
+ }
12
67
  //# sourceMappingURL=ed25519.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"ed25519.js","sourceRoot":"","sources":["../../src/crypto/ed25519.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAE/B;;;GAGG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,EAAE,CAAC,YAAY,CAAC;AAC5C,MAAM,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC,IAAI,CAAC;AAC5B,MAAM,CAAC,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,CAAC;AAChC,MAAM,CAAC,MAAM,iBAAiB,GAAG,EAAE,CAAC,iBAAiB,CAAC;AACtD,MAAM,CAAC,MAAM,SAAS,GAAG,EAAE,CAAC,SAAS,CAAC;AACtC,MAAM,CAAC,MAAM,WAAW,GAAG,EAAE,CAAC,WAAW,CAAC"}
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 +1 @@
1
- {"version":3,"file":"hkdf.d.ts","sourceRoot":"","sources":["../../src/crypto/hkdf.ts"],"names":[],"mappings":"AACA,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":"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,3 +1,4 @@
1
+ // packages/core/src/crypto/hkdf.ts
1
2
  import { hkdf as nobleHkdf } from '@noble/hashes/hkdf.js';
2
3
  import { sha256 as nobleSha256 } from '@noble/hashes/sha2.js';
3
4
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"hkdf.js","sourceRoot":"","sources":["../../src/crypto/hkdf.ts"],"names":[],"mappings":"AAAA,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,OAAO,EAAE,WAAW,IAAI,MAAM,EAAE,CAAC"}
@@ -1,3 +1,4 @@
1
1
  export * from './ed25519.js';
2
2
  export * from './hkdf.js';
3
+ export * from './derivation-paths.js';
3
4
  //# sourceMappingURL=index.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
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,3 +1,5 @@
1
+ // packages/core/src/crypto/index.ts
1
2
  export * from './ed25519.js';
2
3
  export * from './hkdf.js';
4
+ export * from './derivation-paths.js';
3
5
  //# sourceMappingURL=index.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAC;AAC7B,cAAc,WAAW,CAAC"}
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 +1 @@
1
- {"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/crypto/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAKlC;AAKD,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC"}
1
+ {"version":3,"file":"init.d.ts","sourceRoot":"","sources":["../../src/crypto/init.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C;;;GAGG;AACH,wBAAgB,WAAW,IAAI,IAAI,CAKlC;AAKD,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC"}
@@ -1,3 +1,4 @@
1
+ // packages/core/src/crypto/init.ts
1
2
  import * as ed from '@noble/ed25519';
2
3
  import { sha512 } from '@noble/hashes/sha2.js';
3
4
  /**
@@ -1 +1 @@
1
- {"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/crypto/init.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,wEAAwE;IACxE,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,2BAA2B;AAC3B,WAAW,EAAE,CAAC;AAEd,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC"}
1
+ {"version":3,"file":"init.js","sourceRoot":"","sources":["../../src/crypto/init.ts"],"names":[],"mappings":"AAAA,mCAAmC;AACnC,OAAO,KAAK,EAAE,MAAM,gBAAgB,CAAC;AACrC,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C;;;GAGG;AACH,MAAM,UAAU,WAAW;IACzB,wEAAwE;IACxE,IAAI,CAAC,EAAE,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;QACtB,EAAE,CAAC,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IAC5B,CAAC;AACH,CAAC;AAED,2BAA2B;AAC3B,WAAW,EAAE,CAAC;AAEd,OAAO,EAAE,EAAE,EAAE,MAAM,EAAE,CAAC"}
package/dist/handle.d.ts CHANGED
@@ -1,6 +1,20 @@
1
+ import type { SubHandleMetadata, SubHandle } from './subhandle.js';
2
+ import { Attestation, type AttestationGrant } from './attestation.js';
3
+ /**
4
+ * Metadata associated with a {@link Handle}.
5
+ *
6
+ * All fields are optional and application-defined. The protocol does not
7
+ * interpret metadata; it is carried for convenience and may be serialized
8
+ * into tokens or stored by the application.
9
+ *
10
+ * @category Types
11
+ */
1
12
  export interface HandleMetadata {
13
+ /** Human-readable display name. */
2
14
  displayName?: string;
15
+ /** URL or data-URI of an avatar image. */
3
16
  avatar?: string;
17
+ /** Arbitrary additional fields. */
4
18
  [key: string]: unknown;
5
19
  }
6
20
  /**
@@ -8,8 +22,12 @@ export interface HandleMetadata {
8
22
  *
9
23
  * A Handle encapsulates a private key tied to a specific name (context).
10
24
  * It provides methods for signing data, verifying signatures, and deriving
11
- * secondary secrets (like passwords or channel keys) without ever exposing
12
- * the underlying private key.
25
+ * secondary secrets (passwords, channel keys, shared secrets) without ever
26
+ * exposing the underlying private key.
27
+ *
28
+ * A Handle can also derive {@link SubHandle}s for hierarchical access control
29
+ * (e.g., an IoT device deriving keys for its components). The private key
30
+ * **never leaves the Handle** — derivation is performed internally using HKDF.
13
31
  *
14
32
  * @category Core Primitives
15
33
  */
@@ -19,29 +37,38 @@ export declare class Handle {
19
37
  private readonly _name;
20
38
  private readonly _metadata?;
21
39
  /**
22
- * Creates a new Handle instance.
23
- * @internal Typically created via {@link Identity.deriveHandle}.
24
- *
25
- * @param privateKey - The 32-byte Ed25519 private key for this handle.
26
- * @param name - The context name this handle represents.
27
- * @param metadata - Optional metadata associated with this handle.
28
- */
40
+ * Creates a new Handle instance.
41
+ *
42
+ * @internal Typically created via {@link Identity.deriveHandle} or
43
+ * {@link Handle.deriveSubHandle}. Direct construction is discouraged.
44
+ *
45
+ * @param privateKey - The 32-byte Ed25519 private key for this handle.
46
+ * @param name - The context name this handle represents.
47
+ * @param metadata - Optional metadata associated with this handle.
48
+ */
29
49
  constructor(privateKey: Uint8Array, name: string, metadata?: HandleMetadata);
30
- /** @returns The unique context identifier for this Handle. */
50
+ /**
51
+ * Returns a URL-safe Base64-encoded identifier for this Handle,
52
+ * derived from its public key.
53
+ *
54
+ * @returns A unique, URL-safe string identifier.
55
+ */
31
56
  getId(): string;
32
57
  /**
33
- * Cryptographically signs arbitrary data using the Handle's private key.
34
- * @param data - The data to be signed, as a Uint8Array.
35
- * @returns A Promise resolving to the Ed25519 signature as a Uint8Array.
36
- */
58
+ * Cryptographically signs arbitrary data using the Handle's private key.
59
+ *
60
+ * @param data - The data to be signed, as a Uint8Array.
61
+ * @returns A Promise resolving to the Ed25519 signature as a Uint8Array.
62
+ */
37
63
  sign(data: Uint8Array): Promise<Uint8Array>;
38
64
  /**
39
- * Verifies an Ed25519 signature against the provided data and public key.
40
- * @param signature - The signature to verify (Uint8Array).
41
- * @param data - The original data that was signed (Uint8Array).
42
- * @param publicKey - The public key to verify against (Uint8Array).
43
- * @returns A Promise resolving to true if the signature is valid, false otherwise.
44
- */
65
+ * Verifies an Ed25519 signature against the provided data and public key.
66
+ *
67
+ * @param signature - The signature to verify (Uint8Array).
68
+ * @param data - The original data that was signed (Uint8Array).
69
+ * @param publicKey - The public key to verify against (Uint8Array).
70
+ * @returns A Promise resolving to `true` if the signature is valid, `false` otherwise.
71
+ */
45
72
  static verify(signature: Uint8Array, data: Uint8Array, publicKey: Uint8Array): Promise<boolean>;
46
73
  /** @returns The context name associated with this Handle. */
47
74
  getName(): string;
@@ -49,13 +76,86 @@ export declare class Handle {
49
76
  getMetadata(): HandleMetadata | undefined;
50
77
  /** @returns A Uint8Array containing the 32-byte Ed25519 public key. */
51
78
  getPublicKey(): Uint8Array;
79
+ /** @returns The derivation path, or undefined for Handle (only SubHandle has a path). */
80
+ getPath(): string[] | undefined;
81
+ /**
82
+ * Validates session options against this Handle's constraints.
83
+ * Handle has no constraints.
84
+ */
85
+ validateSessionOptions(_options: {
86
+ audience: string;
87
+ scopes: string[];
88
+ ttl: number;
89
+ }): void;
90
+ /**
91
+ * Derives a {@link SubHandle} from this Handle.
92
+ *
93
+ * This is the **autonomous entry point** for IoT devices and other contexts
94
+ * where the Identity is not available locally. The Handle uses its own
95
+ * private key internally (it never leaves the class) to derive a child key
96
+ * via HKDF-SHA256.
97
+ *
98
+ * The resulting SubHandle is cryptographically identical to the one produced
99
+ * by `Identity.deriveSubHandle(this.name, subName)`.
100
+ *
101
+ * @param name - The SubHandle name (will be normalized).
102
+ * @param metadata - Optional SubHandle metadata with constraints.
103
+ * @returns A Promise resolving to the derived SubHandle with path `[this.name, name]`.
104
+ *
105
+ * @example
106
+ * ```ts
107
+ * // On an IoT device (no Identity available)
108
+ * const connector = await stationHandle.deriveSubHandle('connector-1', {
109
+ * allowedScopes: ['charge:start'],
110
+ * maxSessionTtl: 3600
111
+ * });
112
+ * ```
113
+ */
114
+ deriveSubHandle(name: string, metadata?: SubHandleMetadata): Promise<SubHandle>;
115
+ /**
116
+ * Issues an attestation for a derived SubHandle, binding its
117
+ * derived key to the name and grant. Autonomous: requires only
118
+ * this Handle's own key, no Identity and no network.
119
+ *
120
+ * The child key is derived internally, so the attestation's
121
+ * `subjectId` always equals the key produced by
122
+ * `identity.deriveSubHandle(this.name, subName)`.
123
+ *
124
+ * Note: this method does not check this Handle's own grant — it may
125
+ * not have one (Mode 1). Nesting is enforced by verifiers in
126
+ * `Session.verifyAttested` (a child grant exceeding the parent's is
127
+ * rejected with `SCOPE_EXCEEDED`/`TTL_EXCEEDED` at level ROOT).
128
+ *
129
+ * @example
130
+ * ```ts
131
+ * const B = await station.attestSubHandle('connector-ccs', {
132
+ * audiences: ['ev-app.com'],
133
+ * scopes: ['charge:start', 'charge:stop'],
134
+ * maxSessionTtl: 7200,
135
+ * }, { ttlSeconds: 1800 });
136
+ * // Ship [A.token, B.token] together with the session token.
137
+ * ```
138
+ */
139
+ attestSubHandle(subName: string, grant: AttestationGrant, opts?: {
140
+ ttlSeconds?: number;
141
+ expiresAt?: number;
142
+ jti?: string;
143
+ now?: number;
144
+ }): Promise<Attestation>;
52
145
  /**
53
- * Deterministically derives a secret (e.g., a password or API key) for a specific service context.
54
- * The private key NEVER leaves this class, ensuring maximum security.
146
+ * Deterministically derives a secret (e.g., a password or API key) for a
147
+ * specific service context.
55
148
  *
56
- * @param context - A unique identifier for the service (e.g., 'google', 'github', 'wifi-router').
57
- * @param length - Length of the derived raw bytes (default: 16 bytes = ~22 chars base64url).
149
+ * The private key **never leaves this class**, ensuring maximum security.
150
+ *
151
+ * @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).
58
153
  * @returns A URL-safe base64 string suitable for use as a strong password.
154
+ *
155
+ * @example
156
+ * ```ts
157
+ * const githubPassword = handle.derivePassword('github', 20);
158
+ * ```
59
159
  */
60
160
  derivePassword(context: string, length?: number): string;
61
161
  /**
@@ -63,25 +163,39 @@ export declare class Handle {
63
163
  * the Identity (controller) and this Handle (device/context).
64
164
  *
65
165
  * Both parties can independently compute this key because:
66
- * 1. The Handle possesses its own private key directly.
67
- * 2. The Identity can derive the same private key via `identity.deriveHandle(name)`.
166
+ * - The Handle possesses its own private key directly.
167
+ * - The Identity can derive the same private key via `identity.deriveHandle(name)`.
68
168
  *
69
169
  * This enables zero-knowledge encrypted channels without key exchange protocols.
70
170
  *
71
- * @param context - Channel identifier for domain separation (e.g., 'drone-001', 'session-abc'). Both parties MUST use the same context.
171
+ * @param context - Channel identifier for domain separation (e.g., `'drone-001'`).
172
+ * Both parties **MUST** use the same context.
72
173
  * @returns A 32-byte Uint8Array suitable for AES-256-GCM encryption.
73
- * @example
74
- * ```typescript
75
- * // On the drone (Handle side):
76
- * const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
77
- * const encrypted = await encryptAESGCM(telemetry, channelKey);
78
174
  *
79
- * // On the control center (Identity side):
80
- * const droneHandle = await centerIdentity.deriveHandle('drone-001');
175
+ * @example
176
+ * ```ts
177
+ * // AES-GCM helpers are application-side; the protocol provides
178
+ * // only the key:
81
179
  * const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
82
- * const decrypted = await decryptAESGCM(encrypted, channelKey);
83
180
  * ```
84
181
  */
85
182
  deriveChannelKey(context: string): Uint8Array;
183
+ /**
184
+ * Derives a shared secret using ECDH (X25519) for P2P key exchange.
185
+ *
186
+ * Converts the Ed25519 keypair to X25519 for Diffie-Hellman key agreement,
187
+ * then applies HKDF-SHA256 to produce a clean 32-byte channel key.
188
+ *
189
+ * @param otherPublicKey - The Ed25519 public key of the other party (32 bytes).
190
+ * @returns A Promise resolving to a 32-byte shared secret suitable for AES-256-GCM.
191
+ *
192
+ * @example
193
+ * ```ts
194
+ * const aliceShared = await aliceHandle.deriveSharedSecret(bobHandle.getPublicKey());
195
+ * const bobShared = await bobHandle.deriveSharedSecret(aliceHandle.getPublicKey());
196
+ * // aliceShared === bobShared
197
+ * ```
198
+ */
199
+ deriveSharedSecret(otherPublicKey: Uint8Array): Promise<Uint8Array>;
86
200
  }
87
201
  //# sourceMappingURL=handle.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAIA,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAiB;IAE1C;;;;;;;KAOC;gBACS,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc;IAO3E,8DAA8D;IAC9D,KAAK,IAAI,MAAM;IAOb;;;;KAIC;IACG,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAI/C;;;;;;KAMC;WACU,MAAM,CAAC,SAAS,EAAE,UAAU,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC;IAIrG,6DAA6D;IAC7D,OAAO,IAAI,MAAM;IAEjB,gEAAgE;IAChE,WAAW,IAAI,cAAc,GAAG,SAAS;IAExC,uEAAuE;IACxE,YAAY,IAAI,UAAU;IAE1B;;;;;;;OAOG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,MAAM;IAc5D;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;CAK9C"}
1
+ {"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,iBAAiB,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAEnE,OAAO,EAAE,WAAW,EAAE,KAAK,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEtE;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,mCAAmC;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,0CAA0C;IAC1C,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,mCAAmC;IACnC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAa;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAa;IACvC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAiB;IAE5C;;;;;;;;;OASG;gBACS,UAAU,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,cAAc;IAO3E;;;;;OAKG;IACH,KAAK,IAAI,MAAM;IAOf;;;;;OAKG;IACG,IAAI,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;IAIjD;;;;;;;OAOG;WACU,MAAM,CACjB,SAAS,EAAE,UAAU,EACrB,IAAI,EAAE,UAAU,EAChB,SAAS,EAAE,UAAU,GACpB,OAAO,CAAC,OAAO,CAAC;IAInB,6DAA6D;IAC7D,OAAO,IAAI,MAAM;IAIjB,gEAAgE;IAChE,WAAW,IAAI,cAAc,GAAG,SAAS;IAIzC,uEAAuE;IACvE,YAAY,IAAI,UAAU;IAI1B,yFAAyF;IACzF,OAAO,IAAI,MAAM,EAAE,GAAG,SAAS;IAI/B;;;OAGG;IACH,sBAAsB,CAAC,QAAQ,EAAE;QAC/B,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,GAAG,EAAE,MAAM,CAAC;KACjD,GAAG,IAAI;IAER;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,SAAS,CAAC;IAkBrF;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,eAAe,CACnB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,gBAAgB,EACvB,IAAI,CAAC,EAAE;QAAE,UAAU,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GAC7E,OAAO,CAAC,WAAW,CAAC;IAYvB;;;;;;;;;;;;;;OAcG;IACH,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,MAAM;IAU5D;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAM7C;;;;;;;;;;;;;;;OAeG;IACG,kBAAkB,CAAC,cAAc,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;CAgC1E"}