Class Identity

Represents the root cryptographic identity derived from a seed phrase.

An Identity is the foundation of the Me2em protocol. It allows for the hierarchical derivation of isolated Handles and SubHandles for different contexts (e.g., email, social, specific devices) from a single master seed, ensuring zero cross-contamination of cryptographic material.

The Identity provides two derivation entry points:

  • Identity.deriveHandle — derives a top-level Handle.
  • Identity.deriveSubHandle — atomically derives a SubHandle by its full path (Handle name + SubHandle name). Used primarily for stateless session verification on the server side.

Methods

fromSeed deriveHandle deriveSubHandle attestHandle getPublicKey

Methods

StaticfromSeed

  • fromSeed(seed): Promise<Identity>

  • Initializes a new Identity from a BIP39 mnemonic seed phrase or raw seed bytes.

    Parameters

    • seed: string | Uint8Array

      A 32-byte raw Uint8Array seed, or a hex-encoded string of 32 bytes.

    Returns Promise<Identity>

    A Promise resolving to a new Identity instance.

    Throws

    If the provided seed is not exactly 32 bytes.

    Example

    const seed = await get32ByteSeedFromMnemonic('abandon abandon ... art');
    const identity = await Identity.fromSeed(seed);

deriveHandle

  • deriveHandle(name, metadata?): Promise<Handle>

  • Derives a new, cryptographically isolated Handle for a specific context.

    Each Handle is derived deterministically. The same name will always produce the same Handle from the same Identity, but different names produce completely unrelated keys.

    Parameters

    • name: string

      The context identifier (e.g., '[email protected]', 'station-001').

    • Optionalmetadata: HandleMetadata

      Optional metadata to associate with this Handle.

    Returns Promise<Handle>

    A Promise resolving to the derived Handle.

    Example

    const handle = await identity.deriveHandle('station-001', {
      displayName: 'Berlin Station #001'
    });

deriveSubHandle

  • deriveSubHandle(handleName, subName, metadata?): Promise<SubHandle>

  • Atomically derives a SubHandle from this Identity by its full path.

    This method performs the equivalent of:

    const handle = await identity.deriveHandle(handleName);
    const sub = await handle.deriveSubHandle(subName);

    but in a single call, without exposing the intermediate Handle.

    It is the recommended entry point for stateless session verification, because the server only needs the Identity and the path from the token.

    The resulting SubHandle is cryptographically identical to the one produced by Handle.deriveSubHandle(subName) on the same Identity.

    Parameters

    • handleName: string

      The parent Handle name.

    • subName: string

      The SubHandle name.

    • Optionalmetadata: SubHandleMetadata

      Optional SubHandle metadata with constraints.

    Returns Promise<SubHandle>

    A Promise resolving to the derived SubHandle with path [handleName, subName].

    Example

    // Server-side stateless verification
    const sub = await identity.deriveSubHandle('station-001', 'connector-1');
    const publicKey = sub.getPublicKey();

attestHandle

  • attestHandle(name, grant, opts?): Promise<Attestation>

  • Issues an attestation binding a derived Handle key to its name and grant. The subject public key is always derived internally — it is impossible to attest a foreign key, and the resulting subjectId always matches the handle reconstructed via Identity.deriveSubHandle.

    Parameters

    • name: string
    • grant: AttestationGrant

      Constraints verifiers will enforce for this handle and (via subNamePatterns) for the SubHandles it may attest.

    • Optionalopts: {
          ttlSeconds?: number;
          expiresAt?: number;
          jti?: string;
          now?: number;
      }
      • OptionalttlSeconds?: number
      • OptionalexpiresAt?: number
      • Optionaljti?: string
      • Optionalnow?: number

    Returns Promise<Attestation>

    An attestation signed by the Identity root key. Store it with the Handle — it is a public artifact, not a secret.

    Throws

    If the name is not canonicalizable.

    Throws

    If the grant is invalid.

    Example

    const A = await identity.attestHandle('station-001', {
      audiences: ['ev-app.com'],
      scopes: ['charge:start', 'charge:stop', 'charge:status'],
      maxSessionTtl: 7200,
      subNamePatterns: ['connector-*', 'meter-*'],
    });

getPublicKey

  • getPublicKey(): Uint8Array

  • Retrieves the public key of the root Identity.

    Returns Uint8Array

    A Uint8Array containing the 32-byte Ed25519 public key.

Settings

Member Visibility

On This Page

Methods