Publishing a Mirror Endpoint

Scenario: You have an organisation (a company, a research group, a regulator) that publishes information people and AI systems rely on. Right now it lives on a website. You want AI systems to retrieve it verifiably rather than guess at it.

This example walks from zero to a live, validated /.well-known/aiep/ surface. All commands are real. All outputs shown are representative outputs from the SDK.

Estimated time: under 30 minutes.

What you are building

A Mirror endpoint is a small set of JSON files served at a predictable path:

/.well-known/aiep/
  index.json           ← surface map
  metadata.json        ← publisher identity
  schemas/             ← artefact schemas (optional)
  ledger/              ← artefact records
  compliance/          ← compliance signals (optional)

Once live, any AIEP-aware system (AI agent, validator, retrieval tool) can discover and verify your artefacts without scraping, guessing, or calling an API.

Step 1 — Install the mirror package

pip install https://aiep.dev/downloads/repos/aiep_mirror-2.1.0-py3-none-any.whl

Verify:

aiep-mirror --version
# aiep-mirror v2.1.0  AIEP-GENOME-LOCKFILE-MATCH

The lockfile match confirms your installed copy uses the same canonical GENOME kernel (R1–R8) as every other conformant AIEP implementation.

Step 2 — Initialise the surface

mkdir my-org-mirror
cd my-org-mirror
aiep-mirror init

The init command prompts for:

Publisher name: Acme Compliance Ltd
Publisher domain: acme.example.com
Publisher URL: https://acme.example.com
Contact email: [email protected]

It generates:

.well-known/
  aiep/
    index.json
    metadata.json

metadata.json at this stage:

{
  "publisher": "Acme Compliance Ltd",
  "domain": "acme.example.com",
  "contact": "[email protected]",
  "schema_version": "1.0.0",
  "surfaces": ["metadata", "index"],
  "generated_at": "2026-04-14T09:00:00Z",
  "manifest_hash": "sha256:a3f1c9d2e8b7f4a0c6d5e3b1a9f2d4c8e7b0a5f3d6c2e1b8a4f7d9c0e2b5a3f1"
}

The manifest_hash is computed by the GENOME R1–R8 canonical kernel. It commits the surface state at generation time.

Step 3 — Add an artefact

You want to publish your organisation’s GDPR compliance policy as a machine-readable, verifiable artefact.

aiep-mirror add-artefact \
  --label "GDPR Compliance Policy" \
  --kind "compliance-policy" \
  --version "2.3.0" \
  --source "./docs/gdpr-policy-v2.3.0.md" \
  --schema "aiep.compliance.v1"

Output:

Computing GENOME hash for: gdpr-policy-v2.3.0.md
  R1 sorted-keys        ✓
  R2 compact-separators ✓
  R3 nfc-unicode        ✓
  R4 nan-rejection      ✓
  R5 neg-zero-rejection ✓
  R6 empty-str-reject   ✓
  R7 type-coerce-reject ✓
  R8 canonical-hash     ✓
Content hash: sha256:7da3d0cf50986a44d34dfd66e46d54b26d6685d508dfdada80f79153c855d7e8

Artefact written: .well-known/aiep/ledger/gdpr-policy-v2.3.0.json

The generated ledger entry:

{
  "artefact_id": "acme-gdpr-policy",
  "label": "GDPR Compliance Policy",
  "kind": "compliance-policy",
  "version": "2.3.0",
  "schema": "aiep.compliance.v1",
  "content_hash": "sha256:7da3d0cf50986a44d34dfd66e46d54b26d6685d508dfdada80f79153c855d7e8",
  "published_at": "2026-04-14T09:05:00Z",
  "issuer": "acme.example.com",
  "path": "/downloads/gdpr-policy-v2.3.0.md"
}

Step 4 — Build the surface

aiep-mirror build

This:

1. Computes the R1–R8 canonical hash of every artefact in the ledger
2. Writes the surface manifest
3. Updates index.json with the current ledger state
4. Outputs a SHA256SUMS.txt for the complete surface

BUILD COMPLETE
  Artefacts indexed: 1
  Surface hash:      sha256:b1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2
  SHA256SUMS written: .well-known/aiep/SHA256SUMS.txt

Step 5 — Verify

aiep-mirror verify

VERIFYING .well-known/aiep/
  metadata.json        PASS — hash match
  index.json           PASS — hash match
  ledger/gdpr-policy-v2.3.0.json  PASS — content hash match
ALL CHECKS PASS (3/3)

Verification confirms that every file in the surface matches its committed hash. If any file was modified after build, verification fails and identifies exactly which file changed.

Step 6 — Deploy

Copy the .well-known/ directory to your web server root, CDN, or static site. It must be served at https://yourdomain.com/.well-known/aiep/.

For Cloudflare Pages, Netlify, or GitHub Pages, a static deploy is sufficient. No server-side processing is required — these are static JSON files.

Ensure:

• Files are served over HTTPS (TLS required)
• Content-Type: application/json
• No authentication required on /.well-known/aiep/index.json (discovery must be public)

Step 7 — Validate the live endpoint

# After deployment
node repos/aiep-hub-validator/dist/cli.js --site https://acme.example.com

AIEP HUB VALIDATOR v2.0.0
Checking: https://acme.example.com

  [1/15] /.well-known/aiep/index.json accessible     PASS
  [2/15] index.json schema valid                      PASS
  [3/15] metadata.json accessible                     PASS
  [4/15] metadata.json contains publisher field       PASS
  [5/15] manifest_hash present                        PASS
  [6/15] manifest_hash format valid (sha256:...)      PASS
  [7/15] HTTPS enforced                               PASS
  [8/15] TLS certificate valid                        PASS
  [9/15] SSRF guard — private IP range check          PASS
 [10/15] ledger accessible                            PASS
 [11/15] ledger content_hash format valid             PASS
 [12/15] content_hash recomputable from artefact      PASS
 [13/15] Surface hash matches SHA256SUMS.txt          PASS
 [14/15] No broken ledger references                  PASS
 [15/15] schema_version present and semver-valid      PASS

15/15 checks PASS
AIEP-COMPLIANT v1.1.0

A 15/15 result means your surface is conformant. You can now request listing in the AIEP Registry.

What this achieves

Any AI system that queries https://acme.example.com/.well-known/aiep/ can now:

• Retrieve your GDPR policy as a structured artefact (not an HTML page)
• Verify the content hash to confirm it has not been altered since publication
• Confirm the current version and published date
• Detect if the surface has been tampered with (hash mismatch is mechanically detectable)

No API key. No scraping. No ambiguity about whether the retrieved content is current.

Adding more artefacts

Run aiep-mirror add-artefact for each document you want to publish. Common kinds:

After each addition, run aiep-mirror build and aiep-mirror verify before deploying.

Next: Integration Guide · Mirror Protocol · Showcase — aiep-mirror