From 397c868feef64b2292fcc58cb6c0008fc24ccfa0 Mon Sep 17 00:00:00 2001 From: Vilius Vystartas Date: Wed, 6 May 2026 18:29:56 +0100 Subject: [PATCH] =?UTF-8?q?spec:=20add=20identity.yaml=20=E2=80=94=20crypt?= =?UTF-8?q?ographic=20agent=20identity=20via=20Ed25519?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Implements the identity layer proposed in #70: - New identy.yaml optional file convention for agent repos - JSON Schema (spec/schemas/identity.schema.json) - SPECIFICATION.md section 3a with field spec, example, semantics - Directory structure updated Schema maps 1:1 to Works With Agents Identity Protocol (L2, CC BY 4.0): https://workswithagents.dev/specs/identity.md Fully optional. Agents without identity.yaml continue working. Production/regulated deployments get Ed25519 key binding with signing, verification, delegation, and revocation semantics. --- spec/SPECIFICATION.md | 63 ++++++++++++++++++++++ spec/schemas/identity.schema.json | 86 +++++++++++++++++++++++++++++++ 2 files changed, 149 insertions(+) create mode 100644 spec/schemas/identity.schema.json diff --git a/spec/SPECIFICATION.md b/spec/SPECIFICATION.md index 89d1721..19ea1b3 100644 --- a/spec/SPECIFICATION.md +++ b/spec/SPECIFICATION.md @@ -18,6 +18,7 @@ The standard is designed to be: my-agent/ ├── agent.yaml # [REQUIRED] Agent manifest ├── SOUL.md # [REQUIRED] Identity and personality +├── identity.yaml # [OPTIONAL] Cryptographic identity binding (Ed25519) ├── RULES.md # Hard constraints and boundaries ├── DUTIES.md # Segregation of duties policy and role declaration ├── AGENTS.md # Framework-agnostic fallback instructions @@ -322,6 +323,68 @@ tags: - regulated ``` +## 3a. identity.yaml — Cryptographic Identity (optional) + +When an agent needs verifiable identity — "is this agent really who it claims to be?" — add an `identity.yaml` file. This implements the [Works With Agents Identity Protocol](https://workswithagents.dev/specs/identity.md) (L2, CC BY 4.0), binding the manifest to an Ed25519 keypair for cryptographic verification. + +Fully optional. Agents without `identity.yaml` work identically to before. Production and regulated deployments get a seam to bolt on identity without changing the core gitagent surface. + +### Schema + +JSON Schema: [identity.schema.json](schemas/identity.schema.json) + +### Required Fields + +| Field | Type | Description | +|-------|------|-------------| +| `identity_version` | string | Identity protocol version (e.g., `"1.0.0-draft"`) | +| `agent_id` | string | Unique agent identifier (lowercase, hyphens) — SHOULD match `agent.yaml` `name` | +| `public_key` | string | Ed25519 public key in `ed25519:BASE64` format | + +### Optional Fields + +| Field | Type | Description | +|-------|------|-------------| +| `key_fingerprint` | string | SHA-256 fingerprint (`sha256:HEX`) for compact verification | +| `passport_uri` | string | URI to richer identity document (W3C DID, Agent Passport, custom) | +| `did` | string | W3C Decentralized Identifier (`did:wwa:agent-name`) | +| `created_at` | string | ISO 8601 creation timestamp | +| `expires_at` | string | ISO 8601 expiry (null or omit = no expiry until rotated) | +| `hardware_binding` | object | TPM/Secure Enclave/HSM attestation (`type`, `attestation`) | +| `owner` | object | Human owner identity (`name`, `email`, `proof`) | + +### Example + +```yaml +identity_version: "1.0.0-draft" +agent_id: "loan-reviewer" +public_key: "ed25519:iV6sDfN8kL2xQ7pR3tY9aBcE1gH4jM5oU8wZ0dF..." +key_fingerprint: "sha256:a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0" +created_at: "2026-05-06T14:30:00Z" +passport_uri: "https://registry.example.com/agents/loan-reviewer/identity.json" +did: "did:wwa:loan-reviewer" +hardware_binding: + type: "tpm" + attestation: "base64encodedattestation..." +owner: + name: "Financial Services Inc." + email: "compliance@example.com" + proof: "signed-challenge-response..." +``` + +### Runtime Semantics + +1. **Signing:** Agent signs outputs with its Ed25519 private key +2. **Verification:** Downstream tools fetch `agent.yaml` + `identity.yaml`, verify signature against `public_key` +3. **Delegation:** Repo owner signs sub-agent manifests creating a verifiable parent→child chain +4. **Revocation:** Set `expires_at` or remove/revoke the public key in the registry. Pending tasks reassigned. + +### Reference Standard + +The schema and semantics are defined by the [Works With Agents Identity Protocol](https://workswithagents.dev/specs/identity.md) (v1.0.0-draft, CC BY 4.0). The gitagent `identity.yaml` is a compatible subset — all fields map 1:1 to the Identity Protocol schema. + +--- + ## 4. SOUL.md — Identity Defines who the agent *is*. Minimal valid SOUL.md is a single paragraph. diff --git a/spec/schemas/identity.schema.json b/spec/schemas/identity.schema.json new file mode 100644 index 0000000..e32ba1b --- /dev/null +++ b/spec/schemas/identity.schema.json @@ -0,0 +1,86 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://gitagent.dev/schemas/identity.schema.json", + "title": "gitagent Identity", + "description": "Schema for identity.yaml — cryptographic identity binding for gitagent manifests. Implements the Works With Agents Identity Protocol (L2, CC BY 4.0).", + "type": "object", + "required": ["identity_version", "agent_id", "public_key"], + "properties": { + "identity_version": { + "type": "string", + "pattern": "^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?$", + "description": "Identity protocol version this conforms to (e.g., '1.0.0-draft')", + "default": "1.0.0-draft" + }, + "agent_id": { + "type": "string", + "pattern": "^[a-z][a-z0-9-]*$", + "description": "Unique agent identifier (lowercase, hyphens allowed)" + }, + "public_key": { + "type": "string", + "pattern": "^ed25519:[A-Za-z0-9+/=]+$", + "description": "Ed25519 public key in prefixed base64 format" + }, + "key_fingerprint": { + "type": "string", + "pattern": "^sha256:[A-Fa-f0-9]{64}$", + "description": "SHA-256 fingerprint of the public key for compact identity verification" + }, + "passport_uri": { + "type": "string", + "format": "uri", + "description": "Optional URI pointing to a richer identity document (W3C DID, Agent Passport, or custom)" + }, + "did": { + "type": "string", + "pattern": "^did:[a-z]+:[a-zA-Z0-9._%-]+$", + "description": "W3C Decentralized Identifier (e.g., did:wwa:agent-name)" + }, + "created_at": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 timestamp of identity creation" + }, + "expires_at": { + "type": "string", + "format": "date-time", + "description": "ISO 8601 expiry timestamp. Omit or set to null for no expiry (until rotated)" + }, + "hardware_binding": { + "type": "object", + "description": "Optional hardware key binding (TPM, Secure Enclave, etc.)", + "properties": { + "type": { + "type": "string", + "enum": ["tpm", "secure_enclave", "hsm", "none"], + "description": "Hardware binding type" + }, + "attestation": { + "type": "string", + "description": "Base64-encoded hardware attestation" + } + } + }, + "owner": { + "type": "object", + "description": "Optional human owner identity", + "properties": { + "name": { + "type": "string", + "description": "Owner name" + }, + "email": { + "type": "string", + "format": "email", + "description": "Owner email" + }, + "proof": { + "type": "string", + "description": "Signed challenge-response proving ownership" + } + } + } + }, + "additionalProperties": false +}