Class Handle

Represents a context-specific cryptographic handle derived from an Identity.

A Handle encapsulates a private key tied to a specific name (context). It provides methods for signing data, verifying signatures, and deriving secondary secrets (passwords, channel keys, shared secrets) without ever exposing the underlying private key.

A Handle can also derive SubHandles for hierarchical access control (e.g., an IoT device deriving keys for its components). The private key never leaves the Handle — derivation is performed internally using HKDF.

Handles own their lifecycle: Handle.dispose zeroizes the private key, after which every capability method throws a DisposedError. Serialization (JSON.stringify, console inspection) is redacted and never emits key material.

Hierarchy (view full)

Handle
- SubHandle

Implements

Signer

Index

Methods

getId sign verify getName getMetadata getPublicKey getPath validateSessionOptions deriveSubHandle attestSubHandle derivePassword deriveChannelKey deriveSharedSecret dispose toJSON [INSPECT_SYMBOL]

Methods

getId

getId(): string
Returns a URL-safe Base64-encoded identifier for this Handle, derived from its public key.

Returns string
A unique, URL-safe string identifier.
- Defined in packages/core/src/handle.ts:206

sign

sign(data): Promise<Uint8Array>
Cryptographically signs arbitrary data using the Handle's private key (implements Signer — a Handle is acceptable as the signer argument of Attestation.issue).
Parameters
- data: Uint8Array
  The data to be signed, as a Uint8Array.
Returns Promise<Uint8Array>
A Promise resolving to the Ed25519 signature as a Uint8Array.

Throws
If the Handle has been disposed.
Implementation of Signer.sign
- Defined in packages/core/src/handle.ts:219

`Static`verify

verify(signature, data, publicKey): Promise<boolean>
Verifies an Ed25519 signature against the provided data and public key.

A signature whose length differs from the 64-byte Ed25519 size is rejected with false before any crypto runs (PR-7 pre-check) — the method therefore never throws for short/long signatures.
Parameters
- signature: Uint8Array
  The signature to verify (Uint8Array).
- data: Uint8Array
  The original data that was signed (Uint8Array).
- publicKey: Uint8Array
  The public key to verify against (Uint8Array).
Returns Promise<boolean>
A Promise resolving to true if the signature is valid, false otherwise.
- Defined in packages/core/src/handle.ts:236

getName

getName(): string
Returns string
The context name associated with this Handle.
- Defined in packages/core/src/handle.ts:248

getMetadata

getMetadata(): undefined | HandleMetadata
Returns undefined | HandleMetadata
A deep copy of the metadata object associated with this Handle — mutating the returned object does not affect the Handle. Custom metadata is deep-copied (JSON-safe structures up to depth 8); non-plain values (Date, Map, functions) remain shared by reference — same caveats as getSubMetadata().
- Defined in packages/core/src/handle.ts:259

getPublicKey

getPublicKey(): Uint8Array
Returns Uint8Array
A copy of the 32-byte Ed25519 public key — mutating the returned array does not affect the Handle.
- Defined in packages/core/src/handle.ts:267

getPath

getPath(): undefined | string[]
Returns undefined | string[]
The derivation path, or undefined for Handle (only SubHandle has a path).
- Defined in packages/core/src/handle.ts:272

validateSessionOptions

validateSessionOptions(_options): void
Validates session options against this Handle's constraints. Handle has no constraints.
Parameters
- _options: {
      audience: string;
      scopes: string[];
      ttl: number;
  }
  - audience: string
  - scopes: string[]
  - ttl: number
Returns void
- Defined in packages/core/src/handle.ts:280

deriveSubHandle

deriveSubHandle(name, metadata?): Promise<SubHandle>
Derives a SubHandle from this Handle.

This is the autonomous entry point for IoT devices and other contexts where the Identity is not available locally. The Handle uses its own private key internally (it never leaves the class) to derive a child key via HKDF-SHA256.

The resulting SubHandle is cryptographically identical to the one produced by Identity.deriveSubHandle(this.name, subName).
Parameters
- name: string
  The SubHandle name (will be normalized).
- Optionalmetadata: SubHandleMetadata
  Optional SubHandle metadata with constraints.
Returns Promise<SubHandle>
A Promise resolving to the derived SubHandle with path [this.name, name].
Example
```
// On an IoT device (no Identity available)
const connector = await stationHandle.deriveSubHandle('connector-1', {
  allowedScopes: ['charge:start'],
  maxSessionTtl: 3600
});
```
- Defined in packages/core/src/handle.ts:308

attestSubHandle

attestSubHandle(subName, grant, opts?): Promise<Attestation>
Issues an attestation for a derived SubHandle, binding its derived key to the name and grant. Autonomous: requires only this Handle's own key, no Identity and no network.

The child key is derived internally, so the attestation's subjectId always equals the key produced by identity.deriveSubHandle(this.name, subName).

Note: this method does not check this Handle's own grant — it may not have one (Mode 1). Nesting is enforced by verifiers in Session.verifyAttested (a child grant exceeding the parent's is rejected with SCOPE_EXCEEDED/TTL_EXCEEDED at level ROOT).
Parameters
- subName: string
- grant: AttestationGrant
- Optionalopts: {
      ttlSeconds?: number;
      expiresAt?: number;
      jti?: string;
      now?: number;
  }
  - OptionalttlSeconds?: number
  - OptionalexpiresAt?: number
  - Optionaljti?: string
  - Optionalnow?: number
Returns Promise<Attestation>
Example
```
const B = await station.attestSubHandle('connector-ccs', {
  audiences: ['ev-app.com'],
  scopes: ['charge:start', 'charge:stop'],
  maxSessionTtl: 7200,
}, { ttlSeconds: 1800 });
// Ship [A.token, B.token] together with the session token.
```
- Defined in packages/core/src/handle.ts:343

derivePassword

derivePassword(context, options?): string
Deterministically derives a secret (e.g., a password or API key) for a specific service context.

The private key never leaves this class, ensuring maximum security.

The context is canonicalized NFKC → lowercase → trim before use (' GitHub ', 'github' and 'ＧitHub' yield the same secret). NFKC applies to the string context only — options.revision is an integer and is canonical by construction (no normalization).

Revision model (since 0.8.0, D3): options.revision (positive integer, default 1) selects an independent secret for the same context — revision 1 is the initial secret, revision 2, 3, … are for rotation (e.g. after a breach). Revision 1 is byte-identical to the pre-revision v1.0 derivation.
Parameters
- context: string
  A unique identifier for the service (e.g., 'google', 'github').
- options: DerivePasswordOptions = {}
  Derivation options.
Returns string
A URL-safe base64 string suitable for use as a strong password.
Throws
AttestationError MALFORMED/FORMAT if revision is not a positive integer, byteLength is not an integer in [1, 8160], or the context is empty after canonicalization.
Example
```
const githubPassword = handle.derivePassword('github', { byteLength: 20 });
// after rotating the GitHub credential:
const rotated = handle.derivePassword('github', { revision: 2 });
```
- Defined in packages/core/src/handle.ts:395

deriveChannelKey

deriveChannelKey(context, options?): Uint8Array
Derives a symmetric 256-bit channel key for secure communication between the Identity (controller) and this Handle (device/context).

Both parties can independently compute this key because:
- The Handle possesses its own private key directly.
- The Identity can derive the same private key via identity.deriveHandle(name).
This enables zero-knowledge encrypted channels without key exchange protocols.

The context is canonicalized NFKC → lowercase → trim before use. NFKC applies to the string context only — options.revision is an integer and is canonical by construction (no normalization).

Revision model (since 0.8.0, D3): options.revision (positive integer, default 1) selects an independent 32-byte key for the same context — the sanctioned rotation path for a compromised channel without changing the context string. Revision 1 is byte-identical to the pre-revision v1.0 derivation.
Parameters
- context: string
  Channel identifier for domain separation (e.g., 'drone-001'). Both parties MUST use the same context and the same revision.
- options: DeriveChannelKeyOptions = {}
  Derivation options.
Returns Uint8Array
A 32-byte Uint8Array suitable for AES-256-GCM encryption.
Throws
AttestationError MALFORMED/FORMAT if revision is not a positive integer or the context is empty after canonicalization.
Example
```
// AES-GCM helpers are application-side; the protocol provides
// only the key:
const channelKey = droneHandle.deriveChannelKey('telemetry-v1');
// after rotating the channel (both sides migrate in lockstep):
const rotatedKey = droneHandle.deriveChannelKey('telemetry-v1', { revision: 2 });
```
- Defined in packages/core/src/handle.ts:444

deriveSharedSecret

deriveSharedSecret(otherPublicKey): Promise<Uint8Array>
Derives a shared secret using ECDH (X25519) for P2P key exchange.

Converts the Ed25519 keypair to X25519 for Diffie-Hellman key agreement, then applies HKDF-SHA256 to produce a clean 32-byte channel key.
Parameters
- otherPublicKey: Uint8Array
  The Ed25519 public key of the other party (32 bytes).
Returns Promise<Uint8Array>
A Promise resolving to a 32-byte shared secret suitable for AES-256-GCM.
Example
```
const aliceShared = await aliceHandle.deriveSharedSecret(bobHandle.getPublicKey());
const bobShared = await bobHandle.deriveSharedSecret(aliceHandle.getPublicKey());
// aliceShared === bobShared
```
- Defined in packages/core/src/handle.ts:469

dispose

dispose(): void
Permanently destroys this Handle's key material.

The private key bytes are zeroized; afterwards every capability method (sign, deriveSubHandle, attestSubHandle, derivePassword, deriveChannelKey, deriveSharedSecret) throws a DisposedError. Informational getters (getName, getId, getPublicKey, getMetadata) keep working — they never touch key material.

SubHandles inherit dispose(). Calling it more than once is a no-op (idempotent).

Returns void
- Defined in packages/core/src/handle.ts:518

toJSON

toJSON(): {
    kind: string;
    id: string;
    name: string;
}
Redacted serialization contract: JSON.stringify(handle) exposes only the object kind, the public identifier and the context name — never key material or metadata.

Returns {
    kind: string;
    id: string;
    name: string;
}
- kind: string
- id: string
- name: string
- Defined in packages/core/src/handle.ts:533

[INSPECT_SYMBOL]

[INSPECT_SYMBOL](): string
Returns string
- Defined in packages/core/src/handle.ts:541

Class Handle

Hierarchy (view full)

Implements

Index

Methods

Methods

getId

Returns string

sign

Parameters

Returns Promise<Uint8Array>

Throws

Staticverify

Parameters

Returns Promise<boolean>

getName

Returns string

getMetadata

Returns undefined | HandleMetadata

getPublicKey

Returns Uint8Array

getPath

Returns undefined | string[]

validateSessionOptions

Parameters

audience: string

scopes: string[]

ttl: number

Returns void

deriveSubHandle

Parameters

Returns Promise<SubHandle>

Example

attestSubHandle

Parameters

OptionalttlSeconds?: number

OptionalexpiresAt?: number

Optionaljti?: string

Optionalnow?: number

Returns Promise<Attestation>

Example

derivePassword

Parameters

Returns string

Throws

Example

deriveChannelKey

Parameters

Returns Uint8Array

Throws

Example

deriveSharedSecret

Parameters

Returns Promise<Uint8Array>

Example

dispose

Returns void

toJSON

Returns { kind: string; id: string; name: string; }

kind: string

id: string

name: string

[INSPECT_SYMBOL]

Returns string

Settings

On This Page

`Static`verify

`Optional`ttlSeconds?: number

`Optional`expiresAt?: number

`Optional`jti?: string

`Optional`now?: number

Returns {
kind: string;
id: string;
name: string;
}