# OpenCred Documentation

OpenCred is a local-first platform for issuing and verifying W3C Verifiable Credentials. It ships as a **Desktop Client** (Electron) for interactive use and a **Docker Image** (headless HTTP API + CLI) for cloud and CI/CD deployment. Issuer private keys never leave the issuer's environment — all signing happens locally on the issuer's machine or inside the issuer-operated container.

OpenCred is published by [NFH Trust Labs](https://github.com/nfh-trust-labs).

> **🧪 Beta release.** OpenCred is in early-access beta. Functionality is feature-complete and the protocols are stable, but desktop installer polish is still in progress — on first launch macOS shows a one-time approval prompt (see the [installation guide](/docs/desktop-app/installation.md#macos-first-launch)). Windows installers will follow.
>
> **Support:** for bug reports, feature requests, or questions, [open an issue](https://github.com/nfh-trust-labs/opencred-releases/issues).

## Get OpenCred

|                             | Where                                                          | How                                                                  |
| --------------------------- | -------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Desktop** (macOS / Linux) | <https://github.com/nfh-trust-labs/opencred-releases/releases> | Download the `.dmg` / `.AppImage` / `.deb` for your platform         |
| **Docker server**           | `ghcr.io/nfh-trust-labs/opencred/opencred-server:latest`       | `docker pull ghcr.io/nfh-trust-labs/opencred/opencred-server:latest` |

Both are public — no authentication required. The source code is private; bug reports and contact channels are listed in this documentation.

## Start Here

Pick the path that matches your role.

| You are...                                  | Start here                                                                                 |
| ------------------------------------------- | ------------------------------------------------------------------------------------------ |
| New to verifiable credentials               | [Concepts](/docs/concepts/concepts.md) — what VCs, DIDs, and trust chains are              |
| Running a workshop or evaluating end-to-end | [Bootcamp Guide](/docs/bootcamp/bootcamp.md) — guided 3-hour path through the Docker image |
| Installing the desktop app                  | [Desktop User Guide](/docs/desktop-app/desktop.md)                                         |
| Deploying the Docker image                  | [Docker Operator Guide](/docs/docker-image/docker.md)                                      |
| **Verifying a credential someone gave you** | [Verifying credentials](#verifying-a-credential) (below)                                   |
| Reviewing OpenCred's security posture       | [Security Model](/docs/security/security.md)                                               |
| Contributing or building from source        | [Developer Guide](/docs/developer-guide/development.md)                                    |

## Verifying a credential

Anyone holding an OpenCred-issued credential has four supported ways to verify it. All four run the same `@opencred/verification` engine — pick the surface that matches your environment.

| Path                                              | Best for                                                  | Inputs accepted                                                                                                                                                                           |
| ------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Desktop app — Verify tab**                      | Casual / one-off verification by humans                   | Pasted JSON · drag-dropped `.json` / `.jsonld` · QR-code image upload (PNG/JPG) · `.pdf` upload · live camera QR scan · pasted compact tokens (vc-jwt, sd-jwt-vc, bare PixelPass QR data) |
| **Docker server — `POST /v1/credentials/verify`** | Programmatic / server-to-server / CI/CD                   | JSON body for text-shaped formats (auto-detected: JSON-LD VC, vc-jwt, sd-jwt-vc, PixelPass QR data) **or** raw PDF body with `Content-Type: application/pdf`                              |
| **`opencred verify` CLI**                         | One-shot verification from a shell, no HTTP server needed | File path or stdin. Auto-detects JSON-LD, vc-jwt, sd-jwt-vc, PixelPass QR data, or PDF. `--json` flag for scripted consumers. Ships inside the public Docker image.                       |
| **`@opencred/verification` library**              | Embedding verification inside another Node.js app         | Same formats as above, via `verifyCredential` and `verifyPdf`                                                                                                                             |

In every case the result has the same shape: a top-level `valid: true|false`, an enum `code` (`VALID`, `REVOKED`, `EXPIRED`, `INVALID`, `UNRESOLVABLE`, `CONTEXT_MISSING`), and a per-check breakdown — signature, expiry, key resolution, x5c chain (where applicable), revocation, schema, context.

**`did:key`-issued credentials verify fully offline.** `did:web` credentials need network access to fetch the issuer's DID document. DSC-backed credentials carrying an `x5c` chain need a CSCA trust store on disk — see [Trust chains](/docs/concepts/trust-chains.md) and [Docker → API reference → Verify](/docs/docker-image/api-reference.md#post-v1credentialsverify).

**PDF certificates.** OpenCred packages credentials as printable PDFs with a scannable QR embedded **and** a copy of the credential payload tucked into the PDF's info dictionary. Either path works: drop the PDF into the desktop Verify tab, POST it to `/v1/credentials/verify`, or pipe it into `opencred verify --input -`. Older PDFs issued before the info-dict embedding shipped (no payload in metadata) surface as a clear "scan the QR or extract the embedded JSON" message rather than a generic failure.

For full step-by-step, see [Desktop → Verifying credentials](/docs/desktop-app/verifying-credentials.md) or [Docker → API reference](/docs/docker-image/api-reference.md#post-v1credentialsverify).

## Documentation Sections

### Concepts

Background reading for anyone working with OpenCred.

* [Concepts overview](/docs/concepts/concepts.md)
* [Verifiable Credentials](/docs/concepts/verifiable-credentials.md) — what a VC is, payload structure, proof formats, status
* [DIDs](/docs/concepts/dids.md) — `did:key`, `did:jwk`, and `did:web`, and when to use each
* [Trust chains](/docs/concepts/trust-chains.md) — the three issuer types and how trust flows
* [Revocation](/docs/concepts/revocation.md) — how OpenCred handles status checks and DeDi

### Desktop Client

Interactive credential issuance and verification on macOS, Windows, and Linux.

* [Desktop overview](/docs/desktop-app/desktop.md)
* [Installation](/docs/desktop-app/installation.md)
* [Getting started](/docs/desktop-app/getting-started.md) — first launch and onboarding wizard
* [Key management](/docs/desktop-app/key-management.md) — DSC import, hardware tokens, OS cert store, generated keys
* [Issuing credentials](/docs/desktop-app/issuing-credentials.md) — single and batch issuance
* [Verifying credentials](/docs/desktop-app/verifying-credentials.md)
* [Settings and logging](/docs/desktop-app/settings-and-logging.md)

### Docker Image

Headless deployment for cloud, on-prem, and CI/CD pipelines. The Docker image runs in **your** infrastructure — no data is sent to OpenCred or NFH Trust Labs.

* [Docker overview](/docs/docker-image/docker.md)
* [Deployment](/docs/docker-image/deployment.md) — `docker run`, Compose, environment variables, volumes
* [API reference](/docs/docker-image/api-reference.md) — HTTP endpoints
* [CLI reference](/docs/docker-image/cli-reference.md) — `opencred` command-line tool
* [Cloud HSM](/docs/docker-image/cloud-hsm.md) — AWS KMS, Azure Key Vault, GCP Cloud KMS
* [Observability](/docs/docker-image/observability.md) — logging, health checks, metrics
* [OID4VCI](/docs/docker-image/oid4vci.md) — OpenID for Verifiable Credential Issuance (planned)

### Bootcamp

A guided, hands-on 3-hour path attendees follow at workshops or that you can use to evaluate the project end-to-end. Two parallel tracks: laptops only, or one shared cloud VM.

* [Bootcamp overview](/docs/bootcamp/bootcamp.md)
* [Local Docker track](/docs/bootcamp/local-docker.md) — every attendee runs the container on their own laptop
* [GCP VM track](/docs/bootcamp/gcp-vm.md) — one shared GCP VM, IAP-tunnelled SSH, optional Cloud KMS

### Security Model

How OpenCred handles keys, what it protects against, and where the guarantees are enforced.

* [Security overview](/docs/security/security.md)
* [Threat model](/docs/security/threat-model.md) — what we protect against and what we don't
* [Key handling](/docs/security/key-handling.md) — the never-touch-issuer-keys guarantee
* [Invariants](/docs/security/invariants.md) — the seven mandatory rules and where they're enforced

### Developer Guide

Contributing to OpenCred itself.

* [Developer overview](/docs/developer-guide/development.md)
* [Package layout](/docs/developer-guide/package-layout.md) — monorepo structure
* [Building](/docs/developer-guide/building.md) — pnpm, Turborepo, native addons
* [Testing](/docs/developer-guide/testing.md) — vitest, integration tests, coverage

## Reference Docs

Standalone reference documents for quick access:

* [Server API Reference](https://github.com/nfh-trust-labs/opencred/blob/new-opencred-dev/docs/api-reference.md) -- all HTTP endpoints with request/response schemas and curl examples
* [Deployment Guide](https://github.com/nfh-trust-labs/opencred/blob/new-opencred-dev/docs/deployment-guide.md) -- Docker, Compose, nginx reverse proxy, environment variables, production checklist
* [Credential Customization](https://github.com/nfh-trust-labs/opencred/blob/new-opencred-dev/docs/credential-customization.md) -- branding colors, logos, display names for packaged credentials
* [Architecture Overview](https://github.com/nfh-trust-labs/opencred/blob/new-opencred-dev/docs/architecture.md) -- monorepo structure, package responsibilities, key flows, security model

## Source of Truth

OpenCred's source code is maintained in a private repository at NFH Trust Labs. Distributed binaries (Desktop installers, the Docker image) are public; source, issues, and per-PR review history are not.

For end users:

* **Download a release**: <https://github.com/nfh-trust-labs/opencred-releases/releases>
* **Pull the Docker image**: `docker pull ghcr.io/nfh-trust-labs/opencred/opencred-server:latest`
* **Bug reports / feature requests**: <https://github.com/nfh-trust-labs/opencred-releases/issues>

For internal contributors with source access: requirements live in `OpenCred_PRD.md`, the implementation plan in `implementation-plan.md`, per-issue work on the private repo's GitHub Issues, and the contributor protocol in `CLAUDE.md`.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://opencred.gitbook.io/docs/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.