civicos-signer¶

Portable attestation signing service for organizations that issue CivicOS attestation codes.

Location: packages/civicos-signer/

Purpose¶

When multiple organizations are trusted to issue attestations for a jurisdiction (civic groups, libraries, city offices), each needs to hold its own signing key. civicos-signer is a self-contained service that holds an organization's private key and signs kind-30850 attestation events when the CivicOS relay requests it.

This separates attestation authority from relay operation — the relay operator and the attestation issuer are different parties with different keys.

How It Works¶

Resident redeems code → CivicOS relay → org's signer → signed attestation → resident

The relay never sees the organization's private key. The signer never sees the relay's database. The boundary is clean.

CLI¶

civicos-signer keygen      # Generate issuer keypair + bearer token
civicos-signer serve       # Start the signing server
civicos-signer register    # Register with a CivicOS relay
civicos-signer verify      # Verify a signed attestation event

Endpoints¶

Endpoint	Auth	Purpose
`GET /health`	No	Returns issuer pubkey, org name, jurisdiction
`POST /sign`	Bearer token	Signs a kind-30850 attestation event
`GET /audit`	Bearer token	Signing operation log

Dependencies¶

Two external dependencies: coincurve (secp256k1 signatures) and pydantic (models). Server mode adds fastapi and uvicorn.

Deployment¶

# Python
pip install civicos-signer[server]
civicos-signer serve

# Docker
docker run -v ./config:/config -p 8850:8850 civicos-signer

Configuration¶

All via environment variables (or .env.signer file generated by keygen):

Variable	Required	Purpose
`CIVICOS_SIGNER_PRIVATE_KEY`	Yes	Issuer private key (hex)
`CIVICOS_SIGNER_JURISDICTION`	Yes	Jurisdiction code
`CIVICOS_SIGNER_ORGANIZATION`	Yes	Organization name
`CIVICOS_SIGNER_BEARER_TOKEN`	Yes	Shared secret with relay
`CIVICOS_SIGNER_ALLOWED_TYPES`	No	Attestation types (default: `physical`)
`CIVICOS_SIGNER_PORT`	No	Port (default: `8850`)

See packages/civicos-signer/README.md for the full setup guide and security documentation.