Institutions¶

Institutions are first-class entities in Diogenes that anchor trust for their members. Universities, publishers, research labs, and open-source foundations can establish cryptographic identities that vouch for individual participants.

How Institutions Work¶

graph TD
    OP["Operator"] -->|designates| INST["Institution Key
(e.g. MIT)"]
    INST -->|endorses| M1["Member A
(release-signer)"]
    INST -->|endorses| M2["Member B
(security-reviewer)"]
    INST -->|endorses| M3["Member C
(affiliated)"]
    M1 -->|signs| R["Release Attestation"]
    M2 -->|signs| SR["Security Review"]

The operator designates a key as an institutional key (a one-time bootstrap operation).
The institution registers a profile with display name, domain, description, and contact info.
The institution endorses members with role-based endorsements.
Members sign attestations, and verifiers trace the trust chain back through the institution.

Designation¶

Institutional designation is a special endorsement (x-diogenes:institutional_designation) issued by the operator. It is the only endorsement that bypasses the normal offer/accept flow -- the operator issues it directly.

Designating an Institution¶

# The institution must first register a key
diogenes key register \
  --pseudonym "MIT" \
  --algorithm ed25519 \
  --password "secret" \
  --server-url http://localhost:8000

# The operator designates the key as an institution
diogenes operator designate-institution <institution-fp> \
  --name "MIT" \
  --domain "mit.edu"

Setting an Institution Profile¶

Once designated, the institution creates its public profile:

diogenes institution set-profile \
  --fingerprint <institution-fp> \
  --display-name "Massachusetts Institute of Technology" \
  --domain "mit.edu" \
  --description "Research university" \
  --website "https://mit.edu" \
  --contact-email "trust@mit.edu" \
  --password "secret" \
  --server-url http://localhost:8000

Viewing an Institution¶

diogenes institution show <institution-fp>

Or via the API:

GET /api/v1/institutions/<fingerprint>

Institutional Endorsements¶

Institutions endorse their members using the institutional_endorsement category. Each endorsement includes a role that defines what the member is authorized to do.

Roles¶

Role	Purpose
`release-signer`	Authorized to sign software releases for an OSS project
`security-reviewer`	Authorized to publish security review attestations
`affiliated`	General affiliation with the institution
`alumnus`	Former member of the institution
`curator`	Authorized to curate or manage collections

Endorsing a Member¶

diogenes key endorse \
  --fingerprint <institution-fp> \
  --target <member-fp> \
  --category institutional_endorsement \
  --role release-signer \
  --password "secret" \
  --server-url http://localhost:8000

For OSS projects, use the convenience command:

diogenes project add-maintainer \
  --fingerprint <project-fp> \
  --target <maintainer-fp> \
  --role release-signer \
  --password "secret"

Removing a Member¶

diogenes project remove-maintainer \
  --fingerprint <project-fp> \
  --target <maintainer-fp> \
  --password "secret"

Trust Chain¶

When a verifier checks a document, the institutional endorsement chain is a key part of the Layer 2 and Layer 3 verification:

graph LR
    V["Verifier"] -->|trusts| INST["Institution"]
    INST -->|endorses
role: release-signer| M["Maintainer"]
    M -->|signed| DOC["Release v1.2.3"]

Layer 2 checks that the signer has a valid institutional endorsement with the correct role (e.g., release-signer for release attestations).
Layer 3 evaluates whether the verifier trusts the institution, either directly or through endorsement chains.

Multiple Institutions¶

A participant can be endorsed by multiple institutions. The verifier's trust policy determines how overlapping endorsements are evaluated -- some profiles require at least one institutional endorsement, others weight trust by the number and proximity of endorsing institutions.

Institution Profile Fields¶

Field	Required	Description
`display_name`	Yes	Public display name
`domain`	Yes	Institution domain (e.g. `mit.edu`)
`description`	No	Free-text description
`website`	No	Institution website URL
`contact_email`	No	Public contact email
`logo_url`	No	URL to institution logo
`external_identifiers`	No	JSONB map of external IDs (e.g. ORCID org ID, ROR ID)

API Endpoints¶

Endpoint	Method	Auth	Description
`/api/v1/institutions`	GET	Public	List all institutions (paginated)
`/api/v1/institutions/<fp>`	GET	Public	Get institution profile
`/api/v1/institutions/<fp>`	PUT	JWT	Update institution profile

Listing All Institutions¶

# Via CLI
diogenes operator list-institutions

# Via API
curl http://localhost:8000/api/v1/institutions