Merge pull request #4 from ThirdKeyAI/feature/v0.3.0-go-sdk

Add Go SDK (P1.1) — v0.2.0 surface parity

Author: jaschadub

.github/workflows/go.yml

@@ -0,0 +1,34 @@
+name: Go CI
+on:
+  push:
+    branches: [main, dev]
+    paths: ['go/**', '.github/workflows/go.yml']
+  pull_request:
+    paths: ['go/**', '.github/workflows/go.yml']
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        go-version: ['1.21', '1.22']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-go@v5
+        with:
+          go-version: ${{ matrix.go-version }}
+      - name: gofmt
+        working-directory: go
+        run: |
+          out=$(gofmt -l .)
+          if [ -n "$out" ]; then
+            echo "::error::gofmt would reformat the following files:"
+            echo "$out"
+            exit 1
+          fi
+      - name: go vet
+        working-directory: go
+        run: go vet ./...
+      - name: go test
+        working-directory: go
+        run: go test ./...

.github/workflows/release.yml

@@ -14,11 +14,13 @@ jobs:
           RUST_VER=$(grep '^version' crates/agentpin/Cargo.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
           PY_VER=$(grep 'version' python/pyproject.toml | head -1 | sed 's/.*"\(.*\)"/\1/')
           JS_VER=$(node -e "console.log(require('./javascript/package.json').version)")
+          GO_VER=$(grep -E '^const Version' go/internal/version/version.go | sed 's/.*"\(.*\)".*/\1/')
           echo "Rust: $RUST_VER"
           echo "Python: $PY_VER"
           echo "JavaScript: $JS_VER"
-          if [ "$RUST_VER" != "$PY_VER" ] || [ "$RUST_VER" != "$JS_VER" ]; then
-            echo "::error::Version mismatch! Rust=$RUST_VER Python=$PY_VER JavaScript=$JS_VER"
+          echo "Go: $GO_VER"
+          if [ "$RUST_VER" != "$PY_VER" ] || [ "$RUST_VER" != "$JS_VER" ] || [ "$RUST_VER" != "$GO_VER" ]; then
+            echo "::error::Version mismatch! Rust=$RUST_VER Python=$PY_VER JavaScript=$JS_VER Go=$GO_VER"
             exit 1
           fi
           echo "All versions match: $RUST_VER"

.gitignore

@@ -5,6 +5,10 @@ Cargo.lock
 # Private keys — NEVER commit these
 *.private.pem
 *.private.jwk.json
+# Exception: cross-language interop test fixtures under testdata/ ARE
+# deliberately committed throwaway keypairs used only for SDK interop tests.
+# They are NOT used to sign anything in production.
+!go/pkg/verification/testdata/*.private.pem
 
 # IDE
 .idea/

CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to the AgentPin project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0-alpha.1] - 2026-05-01
+
+### Added
+
+#### A2A AgentCard Extension Types & Resolvers (Rust)
+
+- **`AllowedDomains` type** in `types::discovery` — typed wrapper over the list of domains an agent is permitted to interact with. Extracted from `Constraints::allowed_domains` via the new `Constraints::allowed_domains_typed()` helper. Empty list = no restriction (all domains trusted) per the established cross-protocol convention. Includes `intersect()` for composing with cross-protocol callers (most importantly SchemaPin v1.4's `A2aVerificationContext`, which scopes tool verification to the intersection of caller and provider domains).
+- **`A2aAgentCard` + supporting types** in `types::a2a` — minimal A2A AgentCard subset (`A2aAgentCard`, `A2aAgentCapabilities`, `A2aAgentSkill`) plus the AgentPin-specific `AgentpinExtension` payload (`agentpin_endpoint`, `public_key_jwk`, `signature`). Inline definition rather than depending on the upstream `a2a-types` crate while the A2A spec is still draft — the public surface lets us re-export from upstream once it stabilises without breaking callers.
+- **`A2aAgentCardBuilder`** in new `a2a` module — turns an `AgentDeclaration` into a signed `A2aAgentCard`. Maps capabilities to skills via `capability_to_skill`, propagates `Constraints::allowed_domains` into `A2aAgentCapabilities::allowed_domains`. Detached ECDSA P-256 signature covers the canonical bytes of the AgentCard with the extension cleared.
+- **`verify_agentpin_extension(card)`** — verifies the AgentPin extension signature against the JWK embedded in the extension. Sorted-key canonical JSON; matches the canonicalisation pattern used by SchemaPin.
+- **`LocalAgentCardStore`** in new `resolver_local` module — in-memory store of pre-registered AgentCards keyed by their AgentPin discovery domain. Implements `DiscoveryResolver` (always available, no `fetch` feature). Verifies the AgentPin extension signature at registration time and pre-derives a `DiscoveryDocument` so the rest of the AgentPin verification stack runs unchanged. Supports Symbiont v1.7.0's push-based external-agent registration where the coordinator receives AgentCard JSON inline rather than fetching it from a `.well-known` endpoint.
+- **`A2aAgentCardResolver`** in new `resolver_a2a` module (gated on `fetch`) — fetches `https://{domain}/.well-known/agent-card.json`, verifies the AgentPin extension, cross-checks that the embedded `agentpin_endpoint` host matches the fetched domain, and derives a `DiscoveryDocument`. `last_card()` exposes the original A2A representation alongside the derived doc for callers that want both.
+- **`a2a_endpoint` field** on `DiscoveryDocument` — optional URL of the entity's A2A AgentCard endpoint, enabling cross-protocol discovery.
+
+#### DNS TXT Cross-Verification at `_agentpin.{domain}` (Rust)
+
+- **New `dns` module** with `DnsTxtRecord`, `parse_txt_record`, `verify_dns_match`, and `txt_record_name`. Always available; the parser/matcher have no DNS dependencies.
+- **`fetch_dns_txt(domain)`**: async lookup behind the new `dns` Cargo feature. Brings in `hickory-resolver`, `tokio`, and `async-trait`.
+- **TXT record format**: `_agentpin.{domain}` IN TXT `"v=agentpin1; kid=...; fp=sha256:<hex>"` — whitespace-tolerant parser, case-insensitive on `fp`, ignores unknown fields for forward compatibility. Mirrors SchemaPin's `_schemapin.{domain}` shape exactly with the version tag changed.
+- **Multi-key match semantics**: AgentPin discovery docs may carry several keys for rotation; a published TXT record need only match one of them. When the TXT carries an explicit `kid`, the matching key MUST also carry the same `kid`.
+- **Fail-closed on mismatch**: a publisher who *intentionally* publishes a TXT record has signaled that DNS is part of their trust chain — divergence between DNS and `.well-known` indicates compromise of one channel and is treated as a hard failure.
+
+#### Go SDK (Fourth Language Port)
+
+- **New `go/` SDK** — wire-compatible with Rust, JavaScript, and Python at the v0.2.0 surface. Mirrors the package layout of the SchemaPin Go SDK. Closes the long-standing four-language-parity gap.
+- **Module path**: `github.com/ThirdKeyAi/agentpin/go`
+- **Packages**: `crypto`, `jwk`, `jwt`, `types`, `discovery`, `credential`, `verification`, `revocation`, `pinning`, `delegation`, `mutual`, `nonce`, `bundle`, `resolver`
+- **CLI**: `cmd/agentpin` with `keygen`, `issue`, `verify`, `bundle` subcommands matching the Rust binary
+- **ES256-only** enforcement is implemented inline using `crypto/ecdsa`. The JWT verifier rejects `none`, `HS256`, `RS256`, `ES384`, and any other algorithm before any signature work. No third-party JWT dependency.
+- **Cross-language interop tests** under `go/pkg/verification/cross_language_test.go` validate that Rust-generated PEM keypairs, JWKs, discovery documents, and JWTs round-trip correctly through the Go SDK.
+- **CI**: new `.github/workflows/go.yml` runs `go test`, `go vet`, and `gofmt -l` on every PR touching `go/**`. Version-consistency check extended to also validate the Go SDK's declared version.
+- **Note**: this initial Go port covers the v0.2.0 stable surface only. The two v0.3.0-alpha.1 features above (A2A AgentCard types and DNS TXT cross-verification) follow in a Go-side `0.3.0-alpha.2` PR.
+
+### Notes
+
+- This is the first v0.3.0 alpha — the unblock for **Symbiont v1.8.0 Phase 3** (AgentPin-verified AgentCards, A2A auth middleware) and **SchemaPin v1.4.0 `A2aVerificationContext`** (which consumes `AllowedDomains` for tool-verification scoping). Both downstream releases were waiting on this surface.
+- DNS TXT defends against HTTPS-origin compromise (compromised hosting account, expired domain not removed from CDN, ACME ownership-validation bypass) and TLS cert mis-issuance — the DNS credential chain (registrar, DNS provider, optionally DNSSEC) is independent of the HTTPS hosting chain. Spec § 4.8.3 reserved this slot in v0.1; this PR ships the implementation.
+- All additions are purely additive — v0.2.0 callers are unaffected. Discovery documents without `a2a_endpoint`, AgentCards without an `agentpin` extension, and absent `_agentpin` TXT records all behave exactly as before.
+- JavaScript and Python SDK ports of the new A2A + DNS surface follow in `0.3.0-alpha.2`.
+
 ## [0.2.0] - 2026-02-12
 
 ### Added

README.md

@@ -16,7 +16,7 @@ AgentPin lets organizations publish verifiable identity for their AI agents. Iss
 - **Credential revocation** at credential, agent, and key level
 - **Mutual authentication** with challenge-response
 - **Trust bundles** for air-gapped and enterprise environments
-- **Cross-language** — Rust, JavaScript, and Python SDKs produce interoperable credentials
+- **Cross-language** — Rust, JavaScript, Python, and Go SDKs produce interoperable credentials
 
 ## Quick Start
 
@@ -58,6 +58,13 @@ npm install agentpin
 pip install agentpin
 ```
 
+### Go
+
+```bash
+go install github.com/ThirdKeyAi/agentpin/go/cmd/agentpin@latest
+go get github.com/ThirdKeyAi/agentpin/go
+```
+
 ## Documentation
 
 | Topic | Link |
@@ -80,6 +87,7 @@ crates/
 └── agentpin-server/   # HTTP server for .well-known endpoints
 javascript/            # JavaScript/Node.js SDK
 python/                # Python SDK
+go/                    # Go SDK
 ```
 
 ## License

ROADMAP.md

@@ -14,7 +14,8 @@
 |---------|--------|----------|--------|
 | **v0.1.0** | 2026-01 | Core identity, verification, delegation | Shipped |
 | **v0.2.0** | 2026-02 | Trust bundles, alternative discovery, directory listing | Shipped |
-| **v0.3.0** | Q2 2026 | A2A AgentCard extension types + resolver | Planning |
+| **v0.3.0-alpha.1** | 2026-05-01 | A2A AgentCard types + resolvers + AllowedDomains (Rust) | **Shipped** |
+| **v0.3.0** | Q2 2026 | A2A AgentCard extension types + resolver, JS/Python ports, full A2A integration | In progress |
 | **v0.4.0** | Q3 2026 | Mutual auth as A2A handshake, cross-language parity | Planning |
 | **v1.0.0** | Q4 2026 | Stable API, full specification compliance | Planning |
 
@@ -28,7 +29,7 @@ See [CHANGELOG.md](CHANGELOG.md) for full release notes.
 
 ---
 
-## v0.3.0 — A2A AgentCard Types + Resolver (Q2 2026)
+## v0.3.0 — A2A AgentCard Types + Resolver (Q2 2026) — **Rust shipped (alpha.1)**
 
 AgentPin becomes the cryptographic identity layer for A2A (Agent-to-Agent) networks. This release defines extension types for A2A AgentCards and a resolver that discovers AgentPin identity from A2A endpoints.
 
@@ -124,4 +125,4 @@ We welcome input on roadmap priorities:
 
 ---
 
-*Last updated: 2026-03-01 (cross-repo alignment with Symbiont v1.7.0/v1.8.0 and SchemaPin v1.4.0)*
+*Last updated: 2026-05-01 (v0.3.0-alpha.1 — Rust A2A AgentCard types, AllowedDomains, LocalAgentCardStore, A2aAgentCardResolver)*

SKILL.md

@@ -1,8 +1,9 @@
 ---
 name: agentpin
 title: AgentPin
-description: Domain-anchored cryptographic identity protocol for AI agents — ES256 JWT credentials, 12-step verification, TOFU key pinning, revocation, delegation chains, and mutual authentication
-version: 0.2.0
+description: Domain-anchored cryptographic identity protocol for AI agents — ES256 JWT credentials, 12-step verification, TOFU key pinning, revocation, delegation chains, mutual authentication, and (v0.3.0-alpha, Rust) A2A AgentCard extension types + signed AgentCard builder + LocalAgentCardStore + A2aAgentCardResolver + AllowedDomains type for cross-protocol use with SchemaPin v1.4, plus DNS TXT cross-verification at _agentpin.{domain} for second-channel trust independent of HTTPS hosting
+version: 0.3.0-alpha.1
+stable_version: 0.2.0
 ---
 
 # AgentPin Development Skills Guide
@@ -157,6 +158,40 @@ pin_store = KeyPinStore()
 result = verify_credential(credential, discovery_doc, pin_store)
 ```
 
+### Go
+
+```bash
+go get github.com/ThirdKeyAi/agentpin/go
+go install github.com/ThirdKeyAi/agentpin/go/cmd/agentpin@latest
+```
+
+```go
+import (
+    "github.com/ThirdKeyAi/agentpin/go/pkg/credential"
+    "github.com/ThirdKeyAi/agentpin/go/pkg/crypto"
+    "github.com/ThirdKeyAi/agentpin/go/pkg/pinning"
+    "github.com/ThirdKeyAi/agentpin/go/pkg/types"
+    "github.com/ThirdKeyAi/agentpin/go/pkg/verification"
+)
+
+kp, _ := crypto.GenerateKeyPair()
+priv, _ := crypto.LoadPrivateKey(kp.PrivateKeyPEM)
+
+cred, _ := credential.IssueCredential(
+    priv, "my-key-2026", "example.com",
+    "urn:agentpin:example.com:my-agent",
+    "verifier.com",
+    []types.Capability{"read:data", "write:report"},
+    nil, nil, 3600,
+)
+
+pinStore := pinning.NewKeyPinStore()
+result := verification.VerifyCredentialOffline(
+    cred, discoveryDoc, nil, pinStore,
+    "verifier.com", verification.DefaultVerifierConfig(),
+)
+```
+
 ### Serve .well-known Endpoints
 
 ```bash
@@ -193,14 +228,14 @@ Serves:
 
 ### Language API Reference
 
-| Operation | Rust | JavaScript | Python |
-|-----------|------|------------|--------|
-| Generate keys | `crypto::generate_keypair()` | `generateKeypair()` | `generate_keypair()` |
-| Issue credential | `CredentialBuilder::new().sign()` | `issueCredential()` | `issue_credential()` |
-| Verify credential | `verify_credential()` | `verifyCredential()` | `verify_credential()` |
-| Key pinning | `KeyPinStore` | `KeyPinStore` | `KeyPinStore` |
-| Trust bundle | `TrustBundle::from_json()` | `TrustBundle.fromJson()` | `TrustBundle.from_json()` |
-| Mutual auth | `MutualAuth::challenge()` | `createChallenge()` | `create_challenge()` |
+| Operation | Rust | JavaScript | Python | Go |
+|-----------|------|------------|--------|-----|
+| Generate keys | `crypto::generate_key_pair()` | `generateKeypair()` | `generate_keypair()` | `crypto.GenerateKeyPair()` |
+| Issue credential | `credential::issue_credential()` | `issueCredential()` | `issue_credential()` | `credential.IssueCredential()` |
+| Verify credential | `verification::verify_credential_offline()` | `verifyCredentialOffline()` | `verify_credential_offline()` | `verification.VerifyCredentialOffline()` |
+| Key pinning | `KeyPinStore` | `KeyPinStore` | `KeyPinStore` | `pinning.KeyPinStore` |
+| Trust bundle | `TrustBundle::new()` | `new TrustBundle()` | `TrustBundle()` | `bundle.NewTrustBundle()` |
+| Mutual auth | `mutual::create_challenge()` | `createChallenge()` | `create_challenge()` | `mutual.CreateChallenge()` |
 
 ### Feature Flags
 
@@ -348,4 +383,4 @@ cargo fmt --check
 7. **Feature-gate HTTP** — use the `fetch` feature only when online discovery is needed; default is offline-capable
 8. **Cross-compatible with SchemaPin** — both use ECDSA P-256, same crypto primitives
 9. **Trust bundles** are ideal for CI/CD and air-gapped deployments — pre-package discovery + revocation data
-10. **JavaScript and Python SDKs** provide identical verification guarantees to the Rust crate
+10. **JavaScript, Python, and Go SDKs** provide identical verification guarantees to the Rust crate

context7.json

@@ -3,14 +3,15 @@
   "url": "https://context7.com/thirdkeyai/agentpin",
   "public_key": "pk_Ehy7QXQTu2Keb0e5BNeyx",
   "projectTitle": "AgentPin",
-  "description": "Domain-anchored cryptographic identity protocol for AI agents — ES256 JWT credentials, 12-step verification, TOFU key pinning, revocation checking, delegation chains, and mutual authentication. Implementations in Rust, JavaScript, and Python. Part of the ThirdKey trust stack.",
+  "description": "Domain-anchored cryptographic identity protocol for AI agents — ES256 JWT credentials, 12-step verification, TOFU key pinning, revocation checking, delegation chains, mutual authentication, and (v0.3.0-alpha, Rust) A2A AgentCard extension types + signed AgentCard builder + LocalAgentCardStore + A2aAgentCardResolver + AllowedDomains type for cross-protocol use, plus DNS TXT cross-verification at _agentpin.{domain} (`v=agentpin1; kid=...; fp=sha256:...`) for second-channel trust independent of HTTPS hosting. Implementations in Rust, JavaScript, Python, and Go (Go is at v0.2.0 surface parity; A2A + DNS in Go follow in alpha.2). Part of the ThirdKey trust stack: SchemaPin (tool integrity) → AgentPin (agent identity) → Symbiont (runtime).",
   "folders": [
     "SKILL.md",
     "README.md",
     "AGENTPIN_TECHNICAL_SPECIFICATION.md",
     "ROADMAP.md",
     "javascript/README.md",
     "python/README.md",
+    "go/README.md",
     "docs/index.md",
     "docs/getting-started.md",
     "docs/verification-flow.md",
@@ -37,6 +38,7 @@
     "**/*.py",
     "**/*.ts",
     "**/*.js",
+    "**/*.go",
     "**/*.lock",
     "**/*.toml",
     "**/*.cfg",

crates/agentpin-server/src/routes.rs

@@ -80,6 +80,7 @@ mod tests {
             revocation_endpoint: None,
             policy_url: None,
             schemapin_endpoint: None,
+            a2a_endpoint: None,
             max_delegation_depth: 2,
             updated_at: "2026-01-01T00:00:00Z".to_string(),
         };

crates/agentpin/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "agentpin"
-version = "0.2.0"
+version = "0.3.0-alpha.1"
 edition = "2021"
 rust-version = "1.70"
 description = "Domain-anchored cryptographic identity protocol for AI agents"
@@ -13,6 +13,7 @@ categories = ["authentication", "cryptography"]
 [features]
 default = []
 fetch = ["reqwest", "tokio", "async-trait"]
+dns = ["hickory-resolver", "tokio", "async-trait"]
 
 [dependencies]
 p256 = { version = "0.13", features = ["ecdsa", "pem", "jwk"] }
@@ -31,5 +32,8 @@ reqwest = { version = "0.12", features = ["json"], optional = true }
 tokio = { version = "1.0", optional = true }
 tempfile = { version = "3.0", optional = true }
 
+# Optional dependency for DNS TXT cross-verification (v0.3.0)
+hickory-resolver = { version = "0.24", optional = true }
+
 [dev-dependencies]
 tempfile = "3.0"