@me2em/core 0.4.4-alpha.2 → 0.6.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.
- package/README.md +293 -546
- package/dist/attestation.d.ts +151 -0
- package/dist/attestation.d.ts.map +1 -0
- package/dist/attestation.js +279 -0
- package/dist/attestation.js.map +1 -0
- package/dist/canonical-name.d.ts +3 -0
- package/dist/canonical-name.d.ts.map +1 -0
- package/dist/canonical-name.js +12 -0
- package/dist/canonical-name.js.map +1 -0
- package/dist/crypto/derivation-paths.d.ts +41 -0
- package/dist/crypto/derivation-paths.d.ts.map +1 -0
- package/dist/crypto/derivation-paths.js +50 -0
- package/dist/crypto/derivation-paths.js.map +1 -0
- package/dist/crypto/ed25519.d.ts +48 -8
- package/dist/crypto/ed25519.d.ts.map +1 -1
- package/dist/crypto/ed25519.js +63 -8
- package/dist/crypto/ed25519.js.map +1 -1
- package/dist/crypto/hkdf.d.ts.map +1 -1
- package/dist/crypto/hkdf.js +1 -0
- package/dist/crypto/hkdf.js.map +1 -1
- package/dist/crypto/index.d.ts +1 -0
- package/dist/crypto/index.d.ts.map +1 -1
- package/dist/crypto/index.js +2 -0
- package/dist/crypto/index.js.map +1 -1
- package/dist/crypto/init.d.ts.map +1 -1
- package/dist/crypto/init.js +1 -0
- package/dist/crypto/init.js.map +1 -1
- package/dist/handle.d.ts +147 -28
- package/dist/handle.d.ts.map +1 -1
- package/dist/handle.js +178 -33
- package/dist/handle.js.map +1 -1
- package/dist/identity.d.ts +99 -19
- package/dist/identity.d.ts.map +1 -1
- package/dist/identity.js +128 -32
- package/dist/identity.js.map +1 -1
- package/dist/index.d.ts +5 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +4 -0
- package/dist/index.js.map +1 -1
- package/dist/seed.d.ts +22 -35
- package/dist/seed.d.ts.map +1 -1
- package/dist/seed.js +26 -36
- package/dist/seed.js.map +1 -1
- package/dist/session.d.ts +207 -17
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +428 -11
- package/dist/session.js.map +1 -1
- package/dist/subhandle.d.ts +126 -0
- package/dist/subhandle.d.ts.map +1 -0
- package/dist/subhandle.js +158 -0
- package/dist/subhandle.js.map +1 -0
- package/dist/util.d.ts +9 -0
- package/dist/util.d.ts.map +1 -0
- package/dist/util.js +34 -0
- package/dist/util.js.map +1 -0
- package/package.json +3 -3
- package/src/attestation.ts +364 -0
- package/src/canonical-name.ts +12 -0
- package/src/crypto/derivation-paths.ts +56 -0
- package/src/crypto/ed25519.ts +82 -8
- package/src/crypto/hkdf.ts +2 -0
- package/src/crypto/index.ts +3 -1
- package/src/crypto/init.ts +1 -0
- package/src/handle.ts +226 -36
- package/src/identity.ts +164 -35
- package/src/index.ts +5 -1
- package/src/seed.ts +41 -54
- package/src/session.ts +637 -24
- package/src/subhandle.ts +230 -0
- package/src/util.ts +35 -0
package/dist/crypto/ed25519.js
CHANGED
|
@@ -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
|
-
*
|
|
4
|
-
*
|
|
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
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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;
|
|
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":"
|
|
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"}
|
package/dist/crypto/hkdf.js
CHANGED
package/dist/crypto/hkdf.js.map
CHANGED
|
@@ -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"}
|
package/dist/crypto/index.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"
|
|
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"}
|
package/dist/crypto/index.js
CHANGED
package/dist/crypto/index.js.map
CHANGED
|
@@ -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":"
|
|
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"}
|
package/dist/crypto/init.js
CHANGED
package/dist/crypto/init.js.map
CHANGED
|
@@ -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 (
|
|
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
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
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
|
-
/**
|
|
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
|
-
|
|
34
|
-
|
|
35
|
-
|
|
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
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
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
|
|
54
|
-
*
|
|
146
|
+
* Deterministically derives a secret (e.g., a password or API key) for a
|
|
147
|
+
* specific service context.
|
|
148
|
+
*
|
|
149
|
+
* The private key **never leaves this class**, ensuring maximum security.
|
|
55
150
|
*
|
|
56
|
-
* @param context - A unique identifier for the service (e.g., 'google'
|
|
57
|
-
* @param length - Length of the derived raw bytes (default: 16 bytes
|
|
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,15 +163,17 @@ 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
|
-
*
|
|
67
|
-
*
|
|
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'
|
|
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.
|
|
174
|
+
*
|
|
73
175
|
* @example
|
|
74
|
-
* ```
|
|
176
|
+
* ```ts
|
|
75
177
|
* // On the drone (Handle side):
|
|
76
178
|
* const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
|
|
77
179
|
* const encrypted = await encryptAESGCM(telemetry, channelKey);
|
|
@@ -83,5 +185,22 @@ export declare class Handle {
|
|
|
83
185
|
* ```
|
|
84
186
|
*/
|
|
85
187
|
deriveChannelKey(context: string): Uint8Array;
|
|
188
|
+
/**
|
|
189
|
+
* Derives a shared secret using ECDH (X25519) for P2P key exchange.
|
|
190
|
+
*
|
|
191
|
+
* Converts the Ed25519 keypair to X25519 for Diffie-Hellman key agreement,
|
|
192
|
+
* then applies HKDF-SHA256 to produce a clean 32-byte channel key.
|
|
193
|
+
*
|
|
194
|
+
* @param otherPublicKey - The Ed25519 public key of the other party (32 bytes).
|
|
195
|
+
* @returns A Promise resolving to a 32-byte shared secret suitable for AES-256-GCM.
|
|
196
|
+
*
|
|
197
|
+
* @example
|
|
198
|
+
* ```ts
|
|
199
|
+
* const aliceShared = await aliceHandle.deriveSharedSecret(bobHandle.getPublicKey());
|
|
200
|
+
* const bobShared = await bobHandle.deriveSharedSecret(aliceHandle.getPublicKey());
|
|
201
|
+
* // aliceShared === bobShared
|
|
202
|
+
* ```
|
|
203
|
+
*/
|
|
204
|
+
deriveSharedSecret(otherPublicKey: Uint8Array): Promise<Uint8Array>;
|
|
86
205
|
}
|
|
87
206
|
//# sourceMappingURL=handle.d.ts.map
|
package/dist/handle.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"handle.d.ts","sourceRoot":"","sources":["../src/handle.ts"],"names":[],"mappings":"
|
|
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;;;;;;;;;;;;;;;;;;;;;;;QAuBI;IACG,eAAe,CACpB,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;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,UAAU;IAM7C;;;;;;;;;;;;;;;OAeG;IACG,kBAAkB,CAAC,cAAc,EAAE,UAAU,GAAG,OAAO,CAAC,UAAU,CAAC;CAgC1E"}
|