archon-keymaster

What this skill does

# Archon Keymaster - Core DID Toolkit

Core toolkit for Archon decentralized identities (DIDs). Manages identity lifecycle, encrypted communication, cryptographic operations, and authorization.

**Related skills:**
- `archon-vault` — Vault management and encrypted distributed backups
- `archon-cashu` — Cashu ecash with DID-locked tokens

## Capabilities

- **Identity Management** - Create, manage multiple DIDs, recover from mnemonic
- **Verifiable Credentials** - Create schemas, issue/accept/revoke credentials
- **Encrypted Messaging (Dmail)** - Send/receive end-to-end encrypted messages between DIDs
- **Nostr Integration** - Derive Nostr keypairs from your DID (same secp256k1 key)
- **File Encryption** - Encrypt files for specific DIDs
- **Digital Signatures** - Sign and verify files with your DID
- **DID Aliasing** - Friendly names for DIDs (contacts, schemas, credentials)
- **Authorization** - Challenge/response verification between DIDs
- **Groups** - Create and manage DID groups for access control and multi-party operations
- **Polls** - Cryptographic voting with transparent or secret ballots
- **Assets** - Store and retrieve content-addressed assets in the registry

## Prerequisites

- Node.js installed (for `npx @didcid/keymaster`)
- Environment: `~/.archon.env` with:
  - `ARCHON_WALLET_PATH` - path to your wallet file (required)
  - `ARCHON_PASSPHRASE` - wallet encryption passphrase (required)
  - `ARCHON_GATEKEEPER_URL` - gatekeeper endpoint (optional, defaults to public)
- All created automatically by `create-id.sh`

## Security Notes

This skill handles cryptographic identity operations:

1. **Passphrase in environment**: `ARCHON_PASSPHRASE` is stored in `~/.archon.env` for non-interactive script execution. The file should be `chmod 600`.

2. **Sensitive files accessed**:
   - `~/.archon.wallet.json` — encrypted wallet containing DID private keys
   - `~/.archon.env` — wallet encryption passphrase

3. **Network**: Data is encrypted before transmission to Archon gatekeeper/hyperswarm. Only intended recipients can decrypt.

4. **Key recovery**: Your 12-word mnemonic is the master recovery key. Store it offline, never in digital form.

## Quick Start

### First-Time Setup

```bash
./scripts/identity/create-id.sh [wallet-path]
```

Creates your first DID, generates passphrase, saves to `~/.archon.env`. 

- Default wallet location: `~/.archon.wallet.json`
- You can specify a custom path: `./scripts/identity/create-id.sh ~/my-wallet.json`
- **Write down your 12-word mnemonic** - it's your master recovery key.

### Load Environment

All scripts require `~/.archon.env` to be configured. Simply run:

```bash
source ~/.archon.env
```

The environment file sets `ARCHON_WALLET_PATH` and `ARCHON_PASSPHRASE`. Scripts will error if these are not set.

## Identity Management

### Create Additional Identity

```bash
./scripts/identity/create-additional-id.sh <name>
```

Create pseudonymous personas or role-separated identities (all share same mnemonic).

### List All DIDs

```bash
./scripts/identity/list-ids.sh
```

### Switch Active Identity

```bash
./scripts/identity/switch-id.sh <name>
```

### Recovery

For disaster recovery and vault restore operations, see the `archon-backup` skill.

## Verifiable Credential Schemas

Create and manage schemas for verifiable credentials.

### Create Schema

```bash
./scripts/schemas/create-schema.sh <schema-file.json>
```

Create a credential schema from a JSON file.

**Example schema (proof-of-human.json):**
```json
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$credentialContext": [
    "https://www.w3.org/ns/credentials/v2",
    "https://archetech.com/schemas/credentials/agent/v1"
  ],
  "$credentialType": [
    "VerifiableCredential",
    "AgentCredential",
    "ProofOfHumanCredential"
  ],
  "name": "proof-of-human",
  "description": "Verifies human status",
  "properties": {
    "credence": {
      "type": "number",
      "minimum": 0,
      "maximum": 1,
      "description": "Confidence level (0-1) that subject is human"
    }
  },
  "required": ["credence"]
}
```

```bash
./scripts/schemas/create-schema.sh proof-of-human.json
# Returns: did:cid:bagaaiera4yl4xi...
```

### List Your Schemas

```bash
./scripts/schemas/list-schemas.sh
```

Lists all schemas you own.

### Get Schema

```bash
./scripts/schemas/get-schema.sh <schema-did-or-alias>
```

Retrieve schema definition by DID or alias.

## Verifiable Credentials

Issue, accept, and manage verifiable credentials.

### Issuing Credentials (3-step process)

#### 1. Bind Credential to Subject

```bash
./scripts/credentials/bind-credential.sh <schema-did-or-alias> <subject-did-or-alias>
```

Creates a bound credential template file for the subject.

**Example:**
```bash
./scripts/credentials/bind-credential.sh proof-of-human-schema alice
# Creates: bagaaierb...BOUND.json  (subject DID without 'did:cid:' prefix)
```

#### 2. Fill in Credential Data

Edit the `.BOUND.json` file and fill in the `credentialSubject` data:

```json
{
  "credentialSubject": {
    "id": "did:cid:bagaaierb...",
    "credence": 0.97
  }
}
```

#### 3. Issue Credential

```bash
./scripts/credentials/issue-credential.sh <bound-file.json>
```

Signs and encrypts the credential. Returns the credential DID. The underlying `@didcid/keymaster` command may save output files - refer to Keymaster documentation for exact file output behavior.

**Example:**
```bash
./scripts/credentials/issue-credential.sh bagaaierb...BOUND.json
# Returns credential DID: did:cid:bagaaierc...
```

### Accepting Credentials

```bash
./scripts/credentials/accept-credential.sh <credential-did>
```

Accept and save a credential issued to you.

**Example:**
```bash
./scripts/credentials/accept-credential.sh did:cid:bagaaierc...
```

### Managing Credentials

#### List Your Credentials

```bash
./scripts/credentials/list-credentials.sh
```

Lists all credentials you've received.

#### List Issued Credentials

```bash
./scripts/credentials/list-issued.sh
```

Lists all credentials you've issued to others.

#### Get Credential

```bash
./scripts/credentials/get-credential.sh <credential-did-or-alias>
```

Retrieve full credential details.

### Publishing & Revoking

#### Publish Credential

```bash
./scripts/credentials/publish-credential.sh <credential-did>
```

Add credential to your public DID manifest (makes it visible to others).

#### Revoke Credential

```bash
./scripts/credentials/revoke-credential.sh <credential-did>
```

Revoke a credential you issued (invalidates it).

### Complete Example: Issuing Proof-of-Human

```bash
# 1. Create schema
./scripts/schemas/create-schema.sh proof-of-human.json
# Returns: did:cid:bagaaiera4yl4xi...

# 2. Add alias for convenience
./scripts/aliases/add-alias.sh proof-of-human-schema did:cid:bagaaiera4yl4xi...

# 3. Bind credential to Alice
./scripts/credentials/bind-credential.sh proof-of-human-schema alice
# Creates: bagaaierb...BOUND.json  (alice's DID without prefix)

# 4. Edit file, set credence: 0.97

# 5. Issue credential
./scripts/credentials/issue-credential.sh bagaaierb...BOUND.json
# Returns: did:cid:bagaaierc...

# 6. Alice accepts it
./scripts/credentials/accept-credential.sh did:cid:bagaaierc...

# 7. Alice publishes to her manifest
./scripts/credentials/publish-credential.sh did:cid:bagaaierc...
```

## Encrypted Messaging (Dmail)

End-to-end encrypted messages between DIDs with attachment support.

### Send Message

```bash
./scripts/messaging/send.sh <recipient-did-or-alias> <subject> <body> [cc-did...]
```

Examples:
```bash
./scripts/messaging/send.sh alice "Meeting" "Let's sync tomorrow"
./scripts/messaging/send.sh did:cid:bag... "Update" "Status report" did:cid:bob...
```

### Check Inbox

```bash
./scripts/messaging/refresh.sh   # Poll for new messages
./scripts/messaging/list.sh      # List inbox
./scripts/messaging/list.sh unread  # Filter unread
```

### Read Message

```bash
./scripts/messaging/read.sh <dmail-did>
```

### Reply/Forward/Ar