---
title: Glyph Protocol — Documentation
url: https://glyphp.com/docs
---

[![Glyph Protocol](uploads/glyphp.png)Glyphdocs](https://glyphp.com/index.html)

wire protocol 1.0 · stable[← Home](https://glyphp.com/index.html)[GitHub ↗](https://github.com/Monoperro0207/glyph-protocol)

On this page

-   [Overview](https://glyphp.com/docs#overview)
-   [What's new](https://glyphp.com/docs#whats-new)
-   [The glyph card](https://glyphp.com/docs#glyph-card)
-   [Lifecycle](https://glyphp.com/docs#lifecycle)
-   [Architecture](https://glyphp.com/docs#architecture)
-   [Security & audit](https://glyphp.com/docs#security)
-   [What Glyph proves](https://glyphp.com/docs#guarantees)
-   [Resilient updates](https://glyphp.com/docs#resilience)
-   [How it compares](https://glyphp.com/docs#compare)
-   [Adoption](https://glyphp.com/docs#adoption)
-   [Install & quickstart](https://glyphp.com/docs#install)
-   [Packages](https://glyphp.com/docs#packages)
-   [Conformance & spec](https://glyphp.com/docs#conformance)
-   [References](https://glyphp.com/docs#references)

§ documentation

# Glyph Protocol

Token-efficient, cryptographically signed tools for AI agents — verify, approve, and audit every single call. No blind function calling. No trust-without-verify.

[NewExecution attestation, hardened adapters & a one-call production client↓](https://glyphp.com/docs#whats-new)

§01

## Overview

Modern agents call tools by name and trust whatever schema they are handed. That is _blind function calling_: nothing proves a tool is what it claims to be, nothing records what actually ran, and a swapped or poisoned definition is invisible until it is too late.

Glyph Protocol adds a verification layer on top of the tools you already call. Every tool publishes a **glyph** — a self-describing, content-addressed card that carries not only its JSON Schema but also its `intent`, `cost`, `risk`, and `reversibility`. Agents discover glyphs, verify their `ed25519` signatures, and execute them with audit-grade receipts.

It does not replace MCP, OpenAPI or your tool-calling stack — it **layers onto them**. It is wire-compatible across TypeScript, Python and Go, and any MCP server or OpenAPI document can be adapted into glyphs without rewriting the underlying tools — so you keep your tools and gain verification, risk gates and receipts.

§ latest release

## What's new

The September–October releases close the gaps between _looks attested_ and is attested: `@glyphp/core 2.0.0` binds digest attestations to the artifact you pinned, `@glyphp/attestation-sigstore 1.0.0` ships real cryptographic verification, and the client's `secureMode` now fails closed on missing or replayed receipts. The wire protocol is unchanged (`PROTOCOL_VERSION '1.0'`, receipts `0.3`).

core 2.0.0 · breaking

`DigestVerifier` now enforces the RFC-0008 §3.2 subject-digest binding. Pass `new DigestVerifier({ expectedDigest: 'sha256:…' })`; without it the verifier reports `trusted: false` and can't open the `requireAttestation` gate. A mismatch fails closed; `details.subjectBound` reports the binding.

attestation-sigstore 1.0.0

First public release. `SigstoreBundleVerifier` checks the DSSE signature and certificate chain against caller-supplied trust material plus the subject-digest binding — the only verifier that returns `trusted: true`. Opt-in, so core and client take no new runtime dependencies.

client 1.3.4 · receipts fail closed

In `secureMode`, a missing or unverifiable receipt throws `GlyphVerificationError`, the receipt is always checked against the pinned card, and its `clientCallId` must equal the `callId` sent — no replaying an old envelope. Servers that don't sign receipts or echo the callId need `verifyReceipts: false`.

Deprecations & fixes

Client 1.3.3 deprecates the shape-only `SigstoreVerifier` and `SlsaVerifier` (always `trusted: false`). Core 1.6.0 adds `keylessSubjectDigest()`, fixing a circular keyless binding (RFC-0007 §3.1.1). Server 1.4.3 raises the `hono` floor to `^4.13.12` (GHSA-hxh3-vqpv-xpqv).

### Earlier in this line

The June releases moved provenance from _described_ to enforced: cards can carry execution attestation that gates dangerous calls, adapters got hardening limits for untrusted upstreams, and the safe production posture became a single factory call. Canonicalization is byte-for-byte identical across all three SDKs.

Execution attestation · RFC-0008

The `requireAttestation` gate (`'none' | 'danger' | 'all'`) refuses an unattested `danger` tool before its handler runs. Attestation lives in the card's canonical content — stripping it changes the `id` and breaks the pin, so the gate can't be downgraded silently.

Production client · one call

`GlyphClient.production({ baseUrl, pins })` applies the hardened posture in one factory: `secureMode` + receipt verification on, TOFU and auto-approve off — and it throws without a PinStore instead of silently degrading.

Untrusted-MCP hardening

Opt-in limits on the MCP adapter for hostile upstreams: `maxTools` caps the advertised tool surface, `redactDescriptions` neutralizes smuggled card text, `sanitizeErrors` strips upstream error content, and `listToolsTimeoutMs` bounds a hung import.

x-glyph-risk · OpenAPI

A vendor extension lets the API author set the risk tier explicitly (`safe | caution | danger`), overriding the HTTP-method heuristic — an unrecognised value is rejected, and `sideEffects` / `reversible`stay factual to the method.

JCS canonicalization · RFC 8785

TypeScript, Go and Python now share JCS (RFC 8785) canonical JSON, verified against the same `spec/canonical` test vectors — byte-for-byte interop on ids, hashes and signatures across all three SDKs.

Multi-replica deployments

Pluggable `ConfirmationStore` and `RateLimitStore` let replicas share Redis-backed state — confirmation tokens consume atomically across instances. A new deployment guide covers Docker, secrets and key rotation.

Publisher identity · RFC-0009

A draft spec for making `provider` a cryptographic claim rather than a label. Also new: `registerAsync()` on the server signs through async signers, so KMS/HSM-held keys work without exposing key material.

The wave before that — resilient updates, trust-on-first-use, the autonomous audit layer, registry discovery (RFC-0003), keyless signing (RFC-0007) — is covered in [§ resilient updates & trust](https://glyphp.com/docs#resilience). It also shipped the `glyphp` interactive shell: an Ink-based menu with read-only panels for pins and keys, plus confirmation-gated approve / revoke. The one-shot`glyph <command>` binary is unchanged for scripting and CI.

glyphp · interactive shell

$ glyphp

▦Glyph Protocol· interactive shell

❯ Pinsapproved tools and their status

Approvereview + pin a card (file or URL)

Revokeblock a previously approved tool

Keyslocal key registry

Helpcommands and shortcuts

Quitexit glyphp

↑/↓ move · enter select · q quit

§02

## The glyph card

A glyph is a canonicalized JSON card. Its identity is its content: the card is hashed with`sha256` and the resulting digest _is_ the glyph ID. Any change to a behavior-defining field produces a different ID, so a tool can never silently mutate behind a stable name.

Change any behavior-defining field and the content hash — and therefore the glyph ID — changes.

The card embeds the provider's `ed25519` public key and a signature over the canonical bytes, so integrity and provenance travel _with_ the card — verification needs no out-of-band trust root.

§03

## Lifecycle of a call

Every tool call runs through the same pipeline. Discovery and ranking pick a glyph for an intent; verification refuses anything whose signature, hash, or pin does not match; high-risk operations pause for an explicit confirmation; and only then does the tool run.

discoververify cardcheck pin / trustconfirm (if risky)callvalidate outputsanitizesigned receipt

Signatures are checked at verify; high-risk calls pause at confirm; the output is validated and sanitized (Unicode/injection channels stripped) before every successful call emits a signed receipt.

The final stage is non-optional book-keeping: each successful call produces a signed CallReceipt that downstream audit hooks can stream to a log, a database, or an OpenTelemetry pipeline.

§04

## Architecture

The protocol is split into a small set of composable packages. A `GlyphServer`(built on Hono) signs and serves cards; a `GlyphClient` verifies, pins, and renders them; adapters turn existing MCP/OpenAPI tools into glyphs; and a pluggable resolver maps an intent to the best-ranked glyph.

§05

## Security & audit

Glyph treats every call as untrusted until proven otherwise. The defenses span both sides of the wire.

Server-side

-   · Optional bearer-token auth + rate limiting
-   · Confirmation gates for high-risk ops
-   · Single-use tokens (5-min expiry) bound to exact glyph + inputs
-   · Unicode sanitization (zero-width, bidi, C0/C1, tag block)

Client-side

-   · Card pinning — refuse new / changed / revoked tools before handlers run
-   · Spotlighting wraps results as inert data in a per-render random boundary — removes invisible injection channels (visible malicious text still needs host/model policy)
-   · Signature + hash verification on every fetch
-   · Under `secureMode`, receipts fail closed — checked against the pin and bound to the sent `callId` (no replay)
-   · Execution attestation gate — `requireAttestation` refuses unattested `danger` tools before they run (RFC-0008)

Each successful call yields a signed, tamper-evident receipt:

CallReceipt · json

```
{
  "callId":     "01J…",
  "glyphId":    "sha256:9f4c…",
  "inputHash":  "sha256:11ab…",
  "outputHash": "sha256:7d2e…",
  "riskTier":   "elevated",
  "latencyMs":  214,
  "timestamp":  "2026-05-28T20:00:00Z",
  "provider":   "ed25519:MCw…",
  "sig":        "ed25519:5Qe…"
}
```

### Supply chain

Trust does not stop at the wire. Core packages — `@glyphp/core`, `server`, `client` and `conformance` — ship a required CycloneDX SBOM and cosign attestation on every release (a failing core attestation marks the release incomplete); all other packages are _best-effort_. So a consumer can verify provenance of the package itself, not just the cards it serves. The full [threat model](https://github.com/Monoperro0207/glyph-protocol/blob/main/spec/threat-model.md) and [security disclosure policy](https://github.com/Monoperro0207/glyph-protocol/blob/main/spec/security.md) are part of the spec.

Cards can also carry execution attestation (RFC-0008) binding the card to the code that runs it. The honest limit: the structure-only `SigstoreVerifier` / `SlsaVerifier` in the client (now deprecated) return `trusted: false`, which keeps the gate _closed_, and core's `DigestVerifier` stays untrusted unless you give it the `expectedDigest` of the serving artifact. The verifier built to open the gate is `SigstoreBundleVerifier` from `@glyphp/attestation-sigstore`. Validity of shape is never confused with trust.

attestation · typescript

```
import { GlyphClient } from '@glyphp/client';
import { toTrustMaterial } from '@sigstore/verify';
import { SigstoreBundleVerifier } from '@glyphp/attestation-sigstore';

const client = new GlyphClient({
  baseUrl: 'https://glyph.example',
  requireAttestation: 'danger',
  attestationVerifiers: [
    new SigstoreBundleVerifier({
      trustMaterial: toTrustMaterial(myTrustedRoot),  // injected, never fetched
      expectedSubjectDigest: '9f4c…',                 // hex sha256 of the serving artifact (RFC-0008 §3.2)
      thresholds: { tlog: 1 },
    }),
  ],
});

// Digest-only alternative (core 2.0): bind it to the pinned artifact
// new DigestVerifier({ expectedDigest: 'sha256:…' })
```

A chain-valid, digest-bound attestation proves _which code_ ran — never that its behavior matches the card's intent.

§ guarantees

## What Glyph proves

Honest scope matters more than a long feature list. Glyph gives you cryptographic guarantees about the _contract_ and an audit trail of the _call_ — but it is a layer, not a sandbox. Here is exactly where the line sits.

Glyph proves

-   · Card authenticity & integrity — sha256 content id + ed25519 signature
-   · A tool's contract changed since you approved it (pin + diff)
-   · Every call has a signed, tamper-evident receipt (in/out hashes)
-   · Output Unicode is sanitized, and the sanitization is itself audited
-   · Tool output is wrapped as inert data with a random boundary

Glyph does not prove (alone)

-   · That the handler behind a glyph is correct or non-malicious
-   · Global, real-world identity of a provider (it verifies a key, not a legal entity)
-   · Transport security on its own — you still need TLS
-   · Immunity to _visible_ prompt injection — that needs host/model policy

In short: Glyph raises the floor and makes every call accountable. It composes with — and does not replace — TLS, your model's safety policy, and server-side authorization.

§06

## Resilient updates & trust

A tool's card can change after you approve it — a new schema, a higher risk tier, a rotated key. The default stance is strict: a changed card is rejected until re-approved. The resilient-update layer keeps that guarantee while letting an agent keep working on the last known-good version and audit the change out of band.

Enable the opt-in modes on the client. Both default to `false`, so existing behavior is unchanged unless you ask for it:

GlyphClient · typescript

```
const client = new GlyphClient({
  baseUrl: 'https://tools.example.com',
  pins: new FilePinStore('./glyph-pins.json'),  // required for tofu + resilient updates
  tofu: true,               // auto-pin a brand-new tool on first call (after sig verifies)
  resilientUpdates: true,   // park changed cards, keep running the stable pin
});

// Later, audit the parked updates — read-only, never promotes:
const reports = await client.auditPending();

// Or let a policy-gated background runner re-pin the ones that pass:
client.startAuditRunner({
  allowBreaking: false,     // every change class is opt-in
  requireManifest: true,
});
```

The flow below shows where a changed card diverges: a verified-but-unapproved update is parked rather than thrown, calls continue on the stable pin, and promotion stays a separate, policy-gated decision (CLI `glyph approve` or the autonomous runner).

Under `secureMode`, receipts are still verified against the stable pin, so a server that quietly swapped to the unaudited card has its output rejected — resilience never softens the cryptographic checks.

§ compare

## How it compares

Glyph is not a competitor to MCP, OpenAPI or plain tool-calling — it is the verification and audit layer they lack. An honest side-by-side:

capabilityGlyphMCPOpenAPIfn-calling

Signed, content-addressed contract✓✗✗✗

Detects a changed contract (pin + diff)✓✗✗✗

Risk tier + confirmation gates✓✗~✗

Signed, tamper-evident call receipts✓✗✗✗

Output sanitization / inert-data wrap✓✗✗✗

Tool discovery✓✓✓~

Layers onto existing tools✓✓✓✓

✓ built-in · ~ partial / out of scope · ✗ not provided. MCP and OpenAPI describe tools; Glyph proves and audits the call.

§ adoption

## Adoption

Pick the path that matches what you already have. Each is additive — your existing tools keep working.

I have an MCP server

@glyphp/adapter-mcp

Convert an MCP server's tools into signed glyphs — keep the server, gain verification + receipts.

shell

```
pnpm add @glyphp/adapter-mcp
```

I have an OpenAPI doc

@glyphp/adapter-openapi

Turn an OpenAPI document into glyphs, no rewrite of the underlying API.

shell

```
pnpm add @glyphp/adapter-openapi
```

I write native tools

@glyphp/server + core

Author glyphs directly with a GlyphServer (Hono) that signs and serves cards.

shell

```
pnpm add @glyphp/server @glyphp/core
```

I need production

@glyphp/cli + client

Scaffold with the CLI, then harden the client in one factory call — GlyphClient.production().

shell

```
pnpm exec glyph init my-server
```

### MCP → Glyph in three steps

Take any MCP serverGenerate signed glyphsRun with approval + receipts

import-mcp · shell

```
# Adapt an existing MCP server into signed glyphs
pnpm exec glyph import mcp ./my-mcp-server
```

### The hardened client, in one call

`GlyphClient.production()` makes safe configuration the easy path: `secureMode` and receipt verification on, TOFU and auto-approve off — every default overridable, but a missing `PinStore` throws instead of silently degrading. Since client 1.3.4 a missing, unverifiable or replayed receipt throws `GlyphVerificationError`; a server that doesn't sign receipts or echo the client `callId` (RFC-0005) needs an explicit `verifyReceipts: false`.

production · typescript

```
import { GlyphClient, FilePinStore } from '@glyphp/client';

const client = GlyphClient.production({
  baseUrl: 'https://glyph.example',
  pins: new FilePinStore('./pins.json'),
});
```

For running it: the [deployment guide](https://github.com/Monoperro0207/glyph-protocol/blob/main/docs/deployment.md) covers Docker, TLS, secrets and key rotation, and multi-replica scaling with Redis-backed `ConfirmationStore` / `RateLimitStore`.

§07

## Install & quickstart

Add the protocol to an agent / client project:

~ install · glyph-protocol

ready

`pnpm add @glyphp/core @glyphp/client`

Other ecosystems:

python · shell

```
pip install glyph-protocol
```

go · shell

```
go get github.com/Monoperro0207/glyph-protocol/sdks/go/glyphprotocol
```

The CLI installs two binaries — `glyph` for scripting and CI, `glyphp` for the interactive shell:

cli · shell

```
npm install -g @glyphp/cli
```

Run the canonical hello-glyph example from the monorepo:

quickstart · shell

```
cd examples/01-hello-glyph
pnpm run server   # terminal 1
pnpm run client   # terminal 2
```

Or scaffold a production server:

scaffold · shell

```
pnpm exec glyph init my-server
cd my-server && pnpm install && pnpm start
```

§08

## Packages

Core protocol packages, published under the `@glyphp` npm org:

`@glyphp/types`Pure TypeScript interfaces

`@glyphp/core`Hash, sign, validate, sanitize

`@glyphp/server`GlyphServer (Hono)

`@glyphp/client`GlyphClient + spotlighting render layer

`@glyphp/resolver`Intent → glyph resolver (pluggable scorers)

`@glyphp/attestation-sigstore`Opt-in verifier: real Sigstore DSSE + chain verification with RFC-0008 subject-digest binding

`@glyphp/adapter-openapi`Convert an OpenAPI document into glyphs

`@glyphp/adapter-mcp`Convert an MCP server's tools into glyphs

`@glyphp/adapter-mcp-server`Expose a Glyph server to any MCP client

`@glyphp/conformance`Executable spec conformance suite (4 levels)

`@glyphp/cli`glyph inspect / verify / diff-card / pins / approve / revoke / audit / manifest / init / import / keys · plus the glyphp interactive shell

### Framework integrations

`@glyphp/integration-vercel-ai`Tools for the Vercel AI SDK

`@glyphp/integration-langchain`LangChain StructuredTools

`@glyphp/integration-llamaindex`LlamaIndex.TS FunctionTools

`@glyphp/integration-openai-agents`OpenAI Agents SDK tools

`@glyphp/exporter-otel`OpenTelemetry receipt exporter

### SDKs

`TypeScript · full`npm @glyphp/\* (core 2.x, others 1.x)

`Python · 1.2`pip install glyph-protocol

`Go · 1.0`sdks/go/glyphprotocol

### Latest published versions

Current releases on the `@glyphp` npm org — the wire format stays 1.0 (stable) across all of them.

`@glyphp/types`1.5.0

`@glyphp/core`2.0.0 · breaking: DigestVerifier needs expectedDigest

`@glyphp/server`1.4.3

`@glyphp/client`1.3.4

`@glyphp/cli`1.3.6

`@glyphp/resolver`1.0.5

`@glyphp/conformance`1.0.8

`@glyphp/attestation-sigstore`1.0.0 · first public release

`@glyphp/adapter-openapi`3.1.4

`@glyphp/adapter-mcp`1.1.4

`@glyphp/adapter-mcp-server`1.0.10

`@glyphp/exporter-otel`0.2.4

`@glyphp/integration-* (vercel-ai, langchain, llamaindex, openai-agents)`1.1.10

`glyph-protocol (PyPI)`1.2.0

`glyphprotocol (Go module)`v1.0.0

§09

## Conformance & spec

The wire protocol is 1.0 (stable) and interoperates across npm`@glyphp/*` (core 2.x, the rest 1.x — package majors are independent of the wire version), Python `glyph-protocol 1.x`, and Go`glyphprotocol v1.0.x`.

Every SDK is tested against the same canonical test vectors under`spec/canonical/`: a card canonicalized, hashed and signed by one implementation verifies identically in all the others. The executable `glyph-conformance` suite grades an implementation across **four levels** — discovery, execution, security, and governance — from basic card validation up to full server confirmation, receipt semantics and update governance.

conformance · shell

```
pnpm exec glyph-conformance ./my-implementation
```

§10

## References & sources

Everything this protocol is built on, and where to read more:

[Source repository↗](https://github.com/Monoperro0207/glyph-protocol)[Wire protocol spec↗](https://github.com/Monoperro0207/glyph-protocol/blob/main/spec/protocol.md)[Interactive protocol map↗](https://github.com/Monoperro0207/glyph-protocol/blob/main/docs/protocol-map.html)[RFC-0003 — public providers registry (implemented)↗](https://github.com/Monoperro0207/glyph-protocol/blob/main/spec/rfcs/RFC-0003-public-registry.md)[RFC-0007 — keyless signing (implemented)↗](https://github.com/Monoperro0207/glyph-protocol/blob/main/spec/rfcs/RFC-0007-keyless-signing.md)[RFC-0008 — execution attestation (implemented)↗](https://github.com/Monoperro0207/glyph-protocol/blob/main/spec/rfcs/RFC-0008-execution-attestation.md)[RFC-0009 — publisher identity (draft)↗](https://github.com/Monoperro0207/glyph-protocol/blob/main/spec/rfcs/RFC-0009-publisher-identity.md)[Deployment guide↗](https://github.com/Monoperro0207/glyph-protocol/blob/main/docs/deployment.md)[Update governance↗](https://github.com/Monoperro0207/glyph-protocol/blob/main/spec/update-governance.md)[Threat model↗](https://github.com/Monoperro0207/glyph-protocol/blob/main/spec/threat-model.md)[Security disclosure↗](https://github.com/Monoperro0207/glyph-protocol/blob/main/spec/security.md)[Canonical test vectors↗](https://github.com/Monoperro0207/glyph-protocol/tree/main/spec/canonical)[npm — @glyphp org↗](https://www.npmjs.com/org/glyphp)[PyPI — glyph-protocol↗](https://pypi.org/project/glyph-protocol/)[ed25519 (RFC 8032)↗](https://www.rfc-editor.org/rfc/rfc8032)[SHA-256 (RFC 6234)↗](https://www.rfc-editor.org/rfc/rfc6234)[JCS canonical JSON (RFC 8785)↗](https://www.rfc-editor.org/rfc/rfc8785)[Model Context Protocol↗](https://modelcontextprotocol.io/)[OpenAPI Specification↗](https://www.openapis.org/)[Hono↗](https://hono.dev/)[OpenTelemetry↗](https://opentelemetry.io/)

Glyph Protocol · wire 1.0 · sha256 · ed25519Created by [Monoperro0207](https://github.com/Monoperro0207) · apache-2.0