proxmox/docs/03-deployment/DBIS_IDENTITY_COMPLETION_PACKAGE_RUNBOOK.md

# DBIS Identity Completion Package Runbook

**Last updated:** 2026-03-29  
**Purpose:** Convert the remaining Aries / AnonCreds / Indy completion blocker into a concrete operator package so the final issuer bootstrap can be finished without guessing.

## Why this exists

The live environment already proves:

- Indy primary `6400` runs a healthy four-node local pool.
- Aries / AnonCreds primary `6500` runs a healthy ACA-Py agent on the `askar-anoncreds` wallet path.
- Complete Credential and SMOA can already reach the live agent and use its status / proof-request surfaces.

The remaining blocker is narrower:

- the agent does not yet have a write-capable public DID path
- no repo-backed operator package exists for endorser / NYM registration / schema publication
- no canonical schema and credential-definition catalog is frozen for the first real issuance path

This runbook supplies the missing package structure.

## Current ledger target

Based on repo-backed deployment evidence, the current first publication target is:

- a custom DBIS local Indy pool
- specifically the four-node pool hosted on primary `6400`
- with trust scope best described as `sovereign-internal-first`

The repo does not currently evidence:

- Sovrin as the active publication target
- Indicio as the active publication target
- a hybrid trust fabric already wired for first publication

So the correct current answer is:

- publish first against the DBIS-controlled Indy network already deployed here
- then decide later whether to mirror, federate, or bridge trust into a broader external network

## Recommended default

Use an **author + endorser** model, not an ad hoc seed-only model.

Reason:

- the current ACA-Py runtime already proved wallet DID creation but not direct public-DID publication
- seed support is not enabled in the current agent build
- an endorser flow is the safer and more portable way to complete Indy / AnonCreds publication work

## Root endorser control model

The current repo now freezes the `dbis-root-endorser` as a **multisig-governed authority**.

Important Indy / Aries reality:

- the DID itself remains a single-key Indy object
- multisig is enforced around governance, approval, and key-use control
- the current frozen implementation phase is `procedural-multisig`
- the current quorum is `3-of-5`

Canonical artifact:

- [multisig-governance-model.json](../../reports/identity-completion/multisig-governance-model.json)

## Required repo-backed inputs

Before final completion, create real copies of these templates:

| Artifact | Purpose |
|----------|---------|
| `config/production/dbis-identity-public-did-package.json` | Non-secret identity completion contract: agent URLs, ledger mode, DID ownership model, schema catalog, evidence paths |
| `config/production/dbis-identity-public-did-secrets.env` | Secret or operator-held values: admin API key, connection IDs, approver refs, optional NYM transaction file references |

Templates are shipped in:

- [config/production/dbis-identity-public-did-package.example.json](../../config/production/dbis-identity-public-did-package.example.json)
- [config/production/dbis-identity-public-did-secrets.example.env](../../config/production/dbis-identity-public-did-secrets.example.env)

The current repo now also includes pre-frozen governance artifacts:

- [governance-freeze.json](../../reports/identity-completion/governance-freeze.json)
- [dbis-namespace-reservation.json](../../reports/identity-completion/dbis-namespace-reservation.json)
- [multisig-governance-model.json](../../reports/identity-completion/multisig-governance-model.json)

Validate them with:

```bash
bash scripts/validation/validate-dbis-identity-package.sh \
  --package config/production/dbis-identity-public-did-package.json \
  --secrets config/production/dbis-identity-public-did-secrets.env
```

To validate the examples only:

```bash
bash scripts/validation/validate-dbis-identity-package.sh \
  --package config/production/dbis-identity-public-did-package.example.json \
  --secrets config/production/dbis-identity-public-did-secrets.example.env \
  --allow-placeholders
```

## Minimum information that must be filled

### Agent and ledger contract

- Aries admin URL for `6500`
- Aries public DIDComm endpoint
- ledger type and pool name
- target ledger network and trust scope
- genesis file source or mounted location
- DID method to use for publication
- NYM write mode: `endorser` or another explicitly approved model

### Governance / authority contract

- who owns the issuer DID
- who approves NYM registration
- change ticket / control reference for the DID promotion
- endorser DID and alias
- endorser connection ID or invitation path
- evidence directory where publication output will be saved

### Schema and credential-definition contract

At least one canonical schema must be frozen with:

- schema name
- schema version
- attribute list
- issuer alias
- credential-definition tag
- revocation decision

### Verification / relying-party contract

At least one first relying-party flow must be named with:

- verifier system
- proof-request profile ID
- requested attributes
- acceptance criteria

## Completion sequence

### 1. Freeze the identity package

Create the real package and secrets files from the examples, then validate them.

Done when:

- the validator passes without `--allow-placeholders`
- no `<fill-me>` markers remain

### 2. Confirm the live runtime still matches the package

Check:

- ACA-Py admin on `6500`
- Indy pool on `6400`
- referenced genesis file path
- DIDComm endpoint routing

Done when:

- `/status/live` and `/status/ready` both pass
- the ledger reference in the package matches the actual mounted genesis

### 3. Establish the write-capable DID path

Use the chosen governance model to promote the issuer from a wallet-only DID to a public/write-capable DID path.

For the recommended author + endorser model, freeze:

- author DID alias
- endorser DID
- connection ID
- NYM registration approval / evidence reference

Done when:

- the public DID is recorded in the secrets file or referenced evidence
- the agent can use the chosen issuer DID for ledger-backed publication

### 4. Publish the first canonical schema

Publish the agreed schema from the package catalog.

Capture:

- schema ID
- publish timestamp
- issuer DID used
- evidence file location

Done when:

- the schema ID is written back into the package or its evidence directory

### 5. Publish the first credential definition

Use the first schema entry and publish the associated credential definition.

Capture:

- credential definition ID
- tag
- revocation mode
- evidence output

Done when:

- the credential definition ID is recorded

### 6. Prove one real issuance and one real verification path

The recommended first proof path is:

1. Complete Credential as issuer
2. Aries / AnonCreds on `6500` as credential runtime
3. SMOA as verifier-facing integration surface

Done when:

- one credential issuance finishes against the published schema / credential definition
- one presentation request succeeds against the same catalog entry
- evidence is saved under the configured completion evidence directory

## Evidence that should exist after completion

- validated identity package JSON
- validated identity secrets env
- NYM / endorser approval reference
- public DID record
- schema ID record
- credential definition ID record
- one issuance result
- one verification result
- one timestamped operator note tying the evidence set together

## What this runbook does not claim

This runbook does not claim that:

- a trustee seed must be stored in the repo
- the current ACA-Py runtime supports seed-based DID creation
- the public DID can be promoted without an external governance or endorser step

Those are precisely the items that must be supplied through the completion package.

## Related artifacts

- [DBIS_HYPERLEDGER_IDENTITY_STACK_DECISION.md](DBIS_HYPERLEDGER_IDENTITY_STACK_DECISION.md)
- [DBIS_IDENTITY_ENDORSER_HANDSHAKE_RUNBOOK.md](DBIS_IDENTITY_ENDORSER_HANDSHAKE_RUNBOOK.md)
- [DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md](DBIS_RTGS_E2E_REQUIREMENTS_MATRIX.md)
- [DBIS_HYPERLEDGER_RUNTIME_STATUS.md](DBIS_HYPERLEDGER_RUNTIME_STATUS.md)
- [DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md](DBIS_PHASE3_E2E_PRODUCTION_SIMULATION_RUNBOOK.md)