@me2em/core 0.7.0-alpha.2 → 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.
- package/README.md +179 -32
- package/dist/attestation.d.ts +26 -17
- package/dist/attestation.d.ts.map +1 -1
- package/dist/attestation.js +76 -29
- package/dist/attestation.js.map +1 -1
- package/dist/canonical-name.d.ts +18 -0
- package/dist/canonical-name.d.ts.map +1 -1
- package/dist/canonical-name.js +28 -1
- package/dist/canonical-name.js.map +1 -1
- package/dist/crypto/derivation-paths.d.ts +33 -2
- package/dist/crypto/derivation-paths.d.ts.map +1 -1
- package/dist/crypto/derivation-paths.js +33 -2
- package/dist/crypto/derivation-paths.js.map +1 -1
- package/dist/crypto/derivation.d.ts +47 -0
- package/dist/crypto/derivation.d.ts.map +1 -0
- package/dist/crypto/derivation.js +68 -0
- package/dist/crypto/derivation.js.map +1 -0
- package/dist/crypto/ecdh.d.ts +19 -0
- package/dist/crypto/ecdh.d.ts.map +1 -0
- package/dist/crypto/ecdh.js +33 -0
- package/dist/crypto/ecdh.js.map +1 -0
- package/dist/crypto/ed25519.d.ts +24 -3
- package/dist/crypto/ed25519.d.ts.map +1 -1
- package/dist/crypto/ed25519.js +39 -6
- package/dist/crypto/ed25519.js.map +1 -1
- package/dist/crypto/hkdf.d.ts +10 -1
- package/dist/crypto/hkdf.d.ts.map +1 -1
- package/dist/crypto/hkdf.js +10 -1
- package/dist/crypto/hkdf.js.map +1 -1
- package/dist/crypto/index.d.ts +25 -0
- package/dist/crypto/index.d.ts.map +1 -1
- package/dist/crypto/index.js +25 -0
- package/dist/crypto/index.js.map +1 -1
- package/dist/disposed-error.d.ts +24 -0
- package/dist/disposed-error.d.ts.map +1 -0
- package/dist/disposed-error.js +39 -0
- package/dist/disposed-error.js.map +1 -0
- package/dist/errors.d.ts +67 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +54 -0
- package/dist/errors.js.map +1 -0
- package/dist/handle.d.ts +300 -14
- package/dist/handle.d.ts.map +1 -1
- package/dist/handle.js +463 -54
- package/dist/handle.js.map +1 -1
- package/dist/identity.d.ts +55 -11
- package/dist/identity.d.ts.map +1 -1
- package/dist/identity.js +105 -35
- package/dist/identity.js.map +1 -1
- package/dist/index.d.ts +9 -5
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +7 -4
- package/dist/index.js.map +1 -1
- package/dist/seed.d.ts +15 -11
- package/dist/seed.d.ts.map +1 -1
- package/dist/seed.js +23 -17
- package/dist/seed.js.map +1 -1
- package/dist/session.d.ts +42 -5
- package/dist/session.d.ts.map +1 -1
- package/dist/session.js +248 -117
- package/dist/session.js.map +1 -1
- package/dist/subhandle.d.ts +1 -125
- package/dist/subhandle.d.ts.map +1 -1
- package/dist/subhandle.js +12 -179
- package/dist/subhandle.js.map +1 -1
- package/dist/types.d.ts +22 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +6 -0
- package/dist/types.js.map +1 -0
- package/dist/util.d.ts +47 -0
- package/dist/util.d.ts.map +1 -1
- package/dist/util.js +72 -20
- package/dist/util.js.map +1 -1
- package/package.json +10 -4
- package/src/attestation.ts +88 -38
- package/src/canonical-name.ts +33 -1
- package/src/crypto/derivation-paths.ts +37 -2
- package/src/crypto/derivation.ts +90 -0
- package/src/crypto/ecdh.ts +37 -0
- package/src/crypto/ed25519.ts +39 -6
- package/src/crypto/hkdf.ts +10 -1
- package/src/crypto/index.ts +28 -1
- package/src/disposed-error.ts +45 -0
- package/src/errors.ts +88 -0
- package/src/handle.ts +630 -65
- package/src/identity.ts +111 -64
- package/src/index.ts +10 -6
- package/src/seed.ts +27 -17
- package/src/session.ts +336 -132
- package/src/subhandle.ts +12 -251
- package/src/types.ts +26 -0
- package/src/util.ts +78 -20
package/dist/crypto/index.d.ts
CHANGED
|
@@ -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":"
|
|
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"}
|
package/dist/crypto/index.js
CHANGED
|
@@ -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
|
package/dist/crypto/index.js.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/crypto/index.ts"],"names":[],"mappings":"AAAA,oCAAoC;
|
|
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"}
|
package/dist/errors.d.ts
ADDED
|
@@ -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
|
|
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
|
-
/**
|
|
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
|
-
/**
|
|
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
|
|
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,
|
|
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
|