registry-cli

registry-cli

A CLI tool for building TS11-compliant Catalogue of Attestations sites from credential schemas discovered across GitHub repositories.

Overview

registry-cli discovers credential type metadata (VCTMs) from configured source repositories, validates them against the TS11 schema-meta model, and produces a static site with:

• Per-credential detail pages with TS11 metadata
• Rendered rulebooks (from co-located rulebook.md)
• A JSON API (/api/v1/schemas.json) with per-schema endpoints
• An OpenAPI specification
• Optional JWS signing of all API responses

Installation

go install github.com/sirosfoundation/registry-cli/cmd/registry-cli@latest

Usage

Build a site

registry-cli build \
  --sources sources.yaml \
  --output dist \
  --base-url https://registry.siros.org \
  --templates templates-go \
  --static static

Sign API responses (requires PKCS#11 or dev key)

registry-cli sign \
  --input dist/api/v1 \
  --key-mode dev

Sources manifest

The sources.yaml file declares where to find credential repositories:

defaults:
  branch: vctm

sources:
  # Auto-discover by GitHub topic
  - "github:topic/vctm?org=sirosfoundation"

  # Explicit repository
  - "git:https://github.com/org/repo.git"

  # Local directory with explicit organization label
  - url: "file:///path/to/local/credentials"
    organization: "MyOrg"

  # Remote repo with custom org label
  - url: "git:https://github.com/other/repo.git"
    organization: "CustomLabel"

Source entries can be plain strings or structs with url and optional organization fields. Local (file://) sources default to organization "Local" if no label is provided.

Schema-meta: TS11 Governance Metadata

Each credential must have a co-located .schema-meta.yaml file (or .schema-meta.json) providing TS11 Catalogue of Attestations compliance metadata. Only two fields are required; all others are inferred automatically.

Required Fields

Optional Fields

Auto-Generated Fields (do NOT set these)

The following fields are inferred automatically at build time:

Minimal Example

attestation_los: iso_18045_high
binding_type: key

Full Example

attestation_los: iso_18045_high
binding_type: key
version: "1.0.0"
rulebook_uri: https://example.com/credentials/my-credential/rulebook
trusted_authorities:
  - framework_type: etsi_tl
    value: "https://tl.etsi.org/export/trustlist.xml"
    is_lote: false
  - framework_type: eidas
    value: "https://eidas.ec.europa.eu"
    is_lote: false
    trust_mark_id: "https://eidas.ec.europa.eu/markers/high"
    trust_mark_issuers:
      - "https://issuer.example.com"

Trusted Authorities

Trusted authority entries define governance frameworks and trust marks:

File Placement

Place the .schema-meta.yaml file in the same directory and with the same base name as your credential files:

credentials/
├── my-credential.md              (markdown source)
├── my-credential.schema-meta.yaml (TS11 metadata)
├── my-credential.vctm.json       (auto-generated or pre-built)
├── my-credential.mdoc.json       (auto-generated or pre-built)
└── my-credential.vc.json         (auto-generated or pre-built)

Publishing Without Schema-Meta

Credentials discovered without a .schema-meta.yaml file appear in the human-readable site but are excluded from TS11 API responses (/api/v1/schemas.json). This allows incremental migration to TS11 compliance.

Packages

Output Formats

registry-cli convert transforms Markdown credential definitions into the following formats:

By default all formats are generated. Use --format or formats: front matter to select specific formats.

Serve (development)

registry-cli serve --sources sources.yaml --output dist --port 8080

Docker

# Build and run with docker compose
docker compose up --build

# Or build the image directly
docker build -t registry-cli:latest .
docker run -p 8080:8080 -v ./sources:/data/sources:ro registry-cli:latest

Security

Markdown and Content Sanitization

registry-cli processes potentially untrusted content from external credential repositories (rulebooks, VCTM metadata). All user-generated content is sanitized to prevent XSS attacks:

Rulebook Markdown Sanitization

Attestation rulebooks are converted from Markdown to HTML and sanitized using a strict content security policy:

Allowed elements: paragraphs, headings, bold, italic, links, tables, lists, code blocks, blockquotes

Blocked elements: script tags, objects, embeds, SVGs, style tags, iframe, form

Blocked attributes: event handlers (onclick, onerror, etc.), style attributes, javascript: URIs, data: URIs

Example attack prevention:

<!-- Blocked: scripts are stripped -->
<script>alert('xss')</script>

<!-- Blocked: event handlers are removed -->
<img src=x onerror="alert(1)">

<!-- Blocked: style attributes prevent CSS injection -->
<p style="position:fixed;...">Overlay</p>

<!-- Blocked: javascript: URIs are filtered -->
[Click me](javascript:alert(1))

<!-- Allowed: safe links are preserved -->
[Documentation](https://example.com/docs)

SVG and Image URI Validation

Credential metadata (VCTM) may reference images for logos and backgrounds:

• Allowed: https:// and http:// URIs pointing to external image files
• Blocked: data: URIs (inline data), blob: URIs, javascript: protocols, file:// URIs

Invalid image URIs are silently removed from rendered credential pages. The implementation is in pkg/render/vctm.go::SanitizeVCTM().

Testing

Comprehensive security tests verify sanitization effectiveness:

go test ./pkg/render -run "Sanitize" -v

Tests cover:

• XSS via script tags and event handlers
• CSS injection via style attributes
• SVG and object attacks
• Data URI attacks
• JavaScript protocol handlers
• Safe content preservation (links, tables, lists)

Recommendations for Repository Maintainers

When publishing credentials with rulebooks:

1. Avoid HTML in Markdown: Write rulebooks using standard Markdown syntax
2. Don't embed SVGs: Reference SVGs via URLs only, never inline
3. Use safe links: Only use https:// links to trusted documentation
4. No styling: Don't use HTML style attributes or CSS; format using Markdown
5. No JavaScript: Avoid any JavaScript references or data URIs

Example safe rulebook structure:

# PID Attestation Rulebook

## Overview
This rulebook governs Personal ID credentials.

- [Framework documentation](https://example.com/pid-framework)
- [Technical specifications](https://example.com/pid-spec)

## Requirements
- Attestation LoS: high
- Binding type: key

## See also
- [PID Rulebook v1.5](https://example.com/pid-rulebook-1.5)

Testing

make test              # Unit tests
make test-softhsm      # Include SoftHSM PKCS#11 integration tests
make coverage           # Coverage report
make lint               # Run linter

License

See LICENSE.