Identity Standard

Create and verify motebit.md agent identity files — the motebit/identity@1.0 specification.

A motebit.md is a human-readable, cryptographically signed agent identity file. It gives an agent a provable identity — an Ed25519 keypair that persists across sessions, devices, and providers.

The file is YAML frontmatter containing identity, governance, privacy, and memory configuration, signed with an Ed25519 signature embedded as an HTML comment. Anyone can verify it. No central authority required.

Create an identity

npm create motebit

This scaffolds a project directory containing:

motebit.md — the signed identity file (commit this to your repo)

The Ed25519 private key is encrypted with your passphrase (PBKDF2 + AES-256-GCM) and stored as cli_encrypted_key in ~/.motebit/config.json — a JSON object with ciphertext, nonce, tag, and salt fields, all hex-encoded. Never commit this file.

  + Created ./my-agent

    motebit.md         Signed agent identity
    verify.js          Verification example
    package.json       Node project
    .env.example       Environment variable template
    .gitignore         Secrets excluded

  Identity stored in ~/.motebit/config.json
  Motebit ID: 486d9bf5-88d3-4f1f-93f8-a934c4ed72c5

Verify a signature

npx create-motebit verify motebit.md

Returns exit code 0 if valid, 1 if tampered or malformed.

Programmatic verification

Install the standalone verifier:

npm install @motebit/crypto

@motebit/crypto verifies any Motebit artifact — identity files, execution receipts, verifiable credentials, and presentations. One function, zero monorepo dependencies, Apache-2.0 licensed.

import { verify } from "@motebit/crypto";
import fs from "node:fs";

// Identity file
const result = await verify(fs.readFileSync("motebit.md", "utf-8"));
if (result.type === "identity" && result.valid) {
  console.log("Verified:", result.identity.motebit_id);
  console.log("DID:", result.did);
  console.log("Trust mode:", result.identity.governance.trust_mode);
}

// Execution receipt — self-verifiable via embedded public key
const r = await verify(receipt, { expectedType: "receipt" });
if (r.type === "receipt" && r.valid) {
  console.log("Signer:", r.signer);   // did:key of the executing agent
}

// Verifiable credential (W3C VC 2.0, eddsa-jcs-2022)
const c = await verify(credential, { expectedType: "credential" });
if (c.type === "credential" && c.valid) {
  console.log("Issuer:", c.issuer);
}

All verification is offline — no network calls, no relay lookup. Everything needed is embedded in the artifact.

What's in a motebit.md

---
spec: "motebit/identity@1.0"
motebit_id: "486d9bf5-88d3-4f1f-93f8-a934c4ed72c5"
created_at: "2026-01-15T00:00:00.000Z"
owner_id: "owner"

identity:
  algorithm: "Ed25519"
  public_key: "a1b2c3d4..."

governance:
  trust_mode: "guarded"
  max_risk_auto: "R1_DRAFT"
  require_approval_above: "R1_DRAFT"
  deny_above: "R4_MONEY"
  operator_mode: false

privacy:
  default_sensitivity: "personal"
  retention_days:
    none: 365
    personal: 90
    medical: 30
    financial: 30
    secret: 7
  fail_closed: true

memory:
  half_life_days: 7
  confidence_threshold: 0.3
  per_turn_limit: 5

devices: []

# Optional: organizational custody (enterprise agents)
guardian:
  public_key: "e5f6a7b8..."
  organization: "Acme Corp"
  organization_id: "org-acme-123"
  established_at: "2026-01-01T00:00:00.000Z"
  attestation: "c3d4e5f6..."

# Optional: key rotation history
succession:
  - old_public_key: "a1b2c3d4..."
    new_public_key: "b2c3d4e5..."
    timestamp: 1711929600000
    reason: "routine rotation"
    old_key_signature: "d4e5f6..."
    new_key_signature: "e5f6a7..."
---
<!-- motebit:sig:Ed25519:BASE64URL_SIGNATURE -->

Key sections

Section	Purpose
identity	Ed25519 public key — proves who signed the file
governance	Risk thresholds that gate tool execution (see Governance)
privacy	Sensitivity levels and retention rules (see Governance)
memory	Decay parameters for semantic memory (see Memory)
devices	Registered device public keys for multi-device identity
guardian	Optional organizational custody key for enterprise recovery (spec §3.3)
succession	Key rotation history — dual-signed chain from genesis to current key (spec §3.8)

Signature

The Ed25519 signature covers the exact UTF-8 bytes of the YAML frontmatter (between --- delimiters, exclusive). Any modification — even a single character — invalidates the signature.

The signature is stored as a base64url-encoded value in an HTML comment after the closing ---. This keeps the file human-readable while remaining cryptographically verifiable.

Threat model

Threat	Mitigation
Frontmatter tampering	Ed25519 signature — any change invalidates
Private key theft	Encrypted at rest (PBKDF2 + AES-256-GCM) in config or OS keychain; never in the identity file
Identity impersonation	Public key is self-certifying; verification requires the matching keypair
Key compromise (with succession)	Old key signs succession record delegating to new key; chain is verifiable end-to-end
Key compromise (guardian recovery)	Guardian signs recovery succession; `motebit_id` and trust preserved
Key compromise (no succession)	Generate new keypair + new `motebit_id`; old identity is abandoned
YAML injection	Restricted parser; no anchors/aliases/tags

A valid signature proves the holder has the private key. It does not prove the holder is trustworthy. Trust is accumulated at the application layer through history, governance, and memory — not by the identity file alone.

CI verification

Use the GitHub Action to verify signatures in pull requests:

# .github/workflows/verify-identity.yml
name: Verify Agent Identity
on: [push, pull_request]

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: motebit/motebit/packages/github-action@main

Full specification

The complete motebit/identity@1.0 specification — including field definitions, signing algorithm pseudocode, verification algorithm, and security considerations — is available in spec/identity-v1.md.

Identity Standard

On this page