coreason-urn-authority 0.45.1

# CLI Reference: CoReason URN Authority

The `urn-authority` command-line utility serves as the administrative trust anchor interface for OCI registries, Zero-Trust attestations, model proof validation, and thermodynamic cost tracking.

---

## 🔑 1. OCI Capability Ledger Commands

### Resolve URN
Resolves a given capability URN to its verified OCI registry URI.
```bash
urn-authority resolve <URN> [--ledger-path <PATH>] [--json]
```
*   `--ledger-path`: Custom path to the YAML ledger index. (Defaults to `src/coreason_urn_authority/ledger/index.yaml`).
*   `--json`: Output resolution receipt as raw JSON.

### List Ledger
Lists all capability URNs registered in the local capability ledger index.
```bash
urn-authority list [--ledger-path <PATH>] [--json]
```

### Promote URN
Promotes a new capability URN from testing networks to the globally verified production ledger. Automatically formats values, performs atomic Git Ops (commits and pushes), and handles lockouts.
```bash
urn-authority promote \
  --urn <URN> \
  --oci-uri <OCI_URI> \
  --did <DID> \
  [--tenant-cid <TENANT_CID>] \
  [--mcp-namespace <NAMESPACE>] \
  [--dependency <DEP_URN>] \
  [--royalty-share <SHARE>] \
  [--payment-splitter-address <ADDRESS>] \
  [--ledger-path <PATH>] \
  [--skip-git]
```
*   `--urn`: Target URN (must start with `urn:coreason:`).
*   `--oci-uri`: Target OCI registry endpoint (e.g. `ghcr.io/coreason-ai/solver:latest`).
*   `--did`: Signer DID format (must start with `did:key:`).
*   `--dependency`: Dependent capability URNs. (Can specify multiple).
*   `--royalty-share`: Share definitions formatted as `did:key:xyz=percentage` (Must sum to exactly 100).
*   `--skip-git`: Bypasses Git commit/push triggers in non-GitOps testing setups.

---

## 🔒 2. Security & Zero-Trust Validation

### Verify Attestation
Verifies the cryptographic integrity of a runtime source code file against an expected fingerprint or signature block.
```bash
urn-authority verify-attestation <CODE_FILE> [--expected-hash <FINGERPRINT>]
```

### Scan PII / DLP Violations
Uses a high-performance scanning engine to analyze a text payload or files for active credentials, access tokens, SSH private keys, SSNs, credit card leaks, and private signing keys.
```bash
urn-authority scan-dlp [--payload <TEXT>] [--payload-file <PATH>]
```

### Verify Inference Proof
Verifies the zk-SNARK proof produced by `EZKL` models to mathematically guarantee Proof-of-Valid-Inference.
```bash
urn-authority verify-proof \
  --proof <PROOF_PATH> \
  --vk <VK_PATH> \
  --settings <SETTINGS_PATH>
```

---

## 🧠 3. Autonomic Epistemics

### Epistemic Root
Calculates the cryptographic Merkle Root hash of the workspace directory at the specified manifest version level.
```bash
urn-authority epistemic-root \
  --project-path <PROJECT_DIR> \
  [--manifest-version <VERSION>]
```

### Workspace Initialization
Detects total RAM, CPU core allocation, GPU models, hashes the provided KYC files into a secure IPFS Content Identifier (CID), and generates strict local egress rule sets.
```bash
urn-authority init-workspace \
  --target-path <TARGET_DIR> \
  --categories <CATEGORIES> \
  --kyc <KYC_JSON>
```
*   `--categories`: Comma-separated list of tool/sandbox capabilities.
*   `--kyc`: JSON metadata specifying client trust configurations.

---

## 🛰️ 4. NATS Distributed Capability Registry

### NATS Register
Registers a capability URN within the highly available distributed NATS JetStream Key-Value store.
```bash
urn-authority nats-register \
  --urn <URN> \
  [--clearance <CLEARANCE>] \
  [--epistemic-status <STATUS>] \
  [--capability-metadata <JSON_STRING>] \
  [--content-hash <HASH>] \
  [--nats-url <URL>] \
  [--bucket <BUCKET>]
```

### NATS Resolve
Resolves a URN capability definition directly from the NATS JetStream registry.
```bash
urn-authority nats-resolve --urn <URN> [--nats-url <URL>] [--bucket <BUCKET>]
```

### NATS List
Lists all registered capabilities and their clearance status in the NATS bucket.
```bash
urn-authority nats-list [--nats-url <URL>] [--bucket <BUCKET>] [--json]
```

---

## 📊 5. Thermodynamic Cost Engine

### Cost Tracker Schema
Outputs the standard PostgreSQL schema structure required for cost ledgering database migrations.
```bash
urn-authority cost-tracker-schema
```

### Cost Tracker Verification
Cryptographically verifies an incoming `ThermodynamicCostRecord` block against a user's target budget, appending the validated costs if it passes.
```bash
urn-authority cost-tracker-verify \
  --budget <BUDGET_AMOUNT> \
  --records-json <ARRAY_OF_OLD_RECORDS> \
  --new-record-json <NEW_COST_RECORD>
```

### Ledger Access Control Checks
Evaluates if a specific tenant's licensing tier and clearance level is authorized to invoke a target capability URN.
```bash
urn-authority ledger-check-access \
  --urn <URN> \
  --tenant-tier <TIER> \
  --tenant-license <LICENSE> \
  [--ledger-path <PATH>]
```