TheRON/kane-diagnostics
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 4 Wiki Activity

Updated

Browse Source
This commit is contained in:
TheRON
2026-06-07 16:04:40 -04:00
parent 11bd101087
commit 9d3b7dc0cc
2 changed files with 440 additions and 30 deletions
Download Patch File Download Diff File Expand all files Collapse all files

165
CRY01-SPEC.md
View File

@@ -1,16 +1,52 @@
# CRY01 — Value Layer Specification
**Project:** kane-diagnostics
**Version:** 2.0
**Version:** 3.0
**Prerequisite reading:** README.md, ADDON-SKELETON-SPEC.md, ASSOCIATION-CHANNEL-MODEL.md, FOR-PARTICIPANTS-AND-PROFESSIONALS.md
---
## Purpose
`cry01` is a value layer. It is not a payment processor, an escrow, a marketplace, or an intermediary. The platform is never a party to any transaction. What participants do with the signals recorded here is entirely between them.
`cry01` is a value layer and a credential infrastructure layer. It serves two distinct functions that reinforce each other.
The Civic Infrastructure contributes one thing: verified identity. Every signal on this platform is backed by a real name, a real address, and a real property — vouched for through the SASE process. That is the product.
**As a value layer:** It is not a payment processor, an escrow, a marketplace, or an intermediary. The platform is never a party to any transaction. What participants do with the signals recorded here is entirely between them. The Civic Infrastructure contributes one thing: verified identity. Every signal on this platform is backed by a real name, a real address, and a real property — vouched for through the SASE process.
**As a credential infrastructure layer:** `cry01` provides the cryptographic underpinning that makes significant diagnostic results independently verifiable — by attorneys, courts, regulators, and the general public — without trusting the Civic Infrastructure at all. This is the foundational service that `poll01` and all future significant diagnostic result addons depend on.
---
## The Credential Stack
Every significant diagnostic result produced by the Civic Infrastructure — a poll result, a quorum determination, a bylaw amendment vote — is anchored by the following credential stack. Each layer adds independent verifiability.
### Layer 1 — SASE Identity
The participant's identity has been verified as a current resident member of a specific association through the SASE process. Real name, real address, real property. Vouched for by the association channel operator. Stored in the Hubzilla `pgrp_member` table with a timestamp.
This is the foundation. Without it, no other layer has meaning.
### Layer 2 — Ğ1 Web of Trust Certification
The SASE process satisfies the requirements for Ğ1 (June) web of trust certification. A verified SASE participant can be certified as a Ğ1 member by the operator, linking their Hubzilla identity to their Duniter public key. This certification is broadcast to the Duniter network and is permanently recorded on the Ğ1 blockchain.
A Ğ1-certified participant's identity is now vouched for by two independent systems: the Civic Infrastructure's SASE process and the Duniter network's web of trust. These are structurally equivalent vouching mechanisms that arrived at the same conclusion independently.
### Layer 3 — W3C Verifiable Credential
Each significant diagnostic result — a ballot cast, a poll result, a SASE admission — is issued as a W3C Verifiable Credential by the Civic Infrastructure. The VC is cryptographically signed by the operator, identifies the subject by their Hubzilla xchan expressed as a `did:web` identifier, and contains the structured claim.
A VC is machine-readable and independently verifiable by any system that implements the W3C VC standard. It does not require contacting the Civic Infrastructure to verify. An attorney receiving a poll result VC can verify its authenticity offline.
### Layer 4 — OpenTimestamps
Every significant diagnostic result is timestamped against the Bitcoin blockchain via OpenTimestamps at the moment it enters the orchestrator spool. The timestamp proof anchors the SHA-256 hash of the result document to a specific Bitcoin block. No one can claim the document was produced after the fact.
OpenTimestamps requires no account, no token, no Bitcoin transaction fee (proofs are aggregated by public calendar servers), and no understanding of the Civic Infrastructure. Any person with the document and the proof file can verify the timestamp independently using the `ots` command line tool or the OpenTimestamps web verifier.
### Layer 5 — DANE (DNS-Based Authentication of Named Entities)
The domain serving the Civic Infrastructure's diagnostic records is bound to its TLS certificate via TLSA records in DNS, secured by DNSSEC. A document served from `directory.diagnostics.kane-il.us` cannot be impersonated — the DNS record cryptographically identifies the server. This prevents man-in-the-middle attacks and domain spoofing when attorneys or regulators retrieve diagnostic records.
---
@@ -67,11 +103,11 @@ Automated certification signing is a future version feature, pending operator de
---
## Three Functions
## Four Functions
### 1. Display
The operator's verified Ğ1 balance is shown publicly on the association channel. This is read-only from the Duniter blockchain. No keys are involved. No custody changes. The balance is cached locally and refreshed on a schedule defined in `config.json`.
The operator's verified Ğ1 balance is shown publicly on the association channel. This is read-only from the Duniter blockchain via the local Duniter mirror node on the orchestrator. No keys are involved. No custody changes. The balance is cached locally and refreshed on a schedule defined in `config.json`.
If the Duniter node is unreachable, the display renders the last cached balance with a staleness timestamp. It does not fail silently. It does not show zero.
@@ -79,19 +115,22 @@ If the Duniter node is unreachable, the display renders the last cached balance
A SASE-verified participant registers a capacity signal against their verified identity. The signal describes what they are offering or seeking, denominated in Ğ1. The platform records the signal. No transaction occurs at registration time.
A signal contains:
- The participant's Ğ1 public key (self-reported, linked to their SASE xchan)
- A plain-language description of the capacity being offered or sought
- A Ğ1 denomination (the amount the participant considers fair exchange)
- A duration (how long the capacity is available)
- An optional service category tag from the operator-defined list
Signals are visible to all SASE participants on the association channel. They are not visible to public (unauthenticated) visitors.
At signal registration, the orchestrator:
- Accepts the signal via the spool receiver
- Issues a W3C Verifiable Credential for the signal
- Generates an OpenTimestamps proof anchoring the signal to the Bitcoin blockchain
- Stores the signal, VC, and OTS proof together in the spool
### 3. Ğ1 Certification Bridge
The operator sees a candidate list of all SASE participants who have registered a Ğ1 public key. For each candidate, the addon builds a Duniter-compatible attestation document. The operator reviews it and certifies manually via their Ğ1 wallet. The platform does not sign anything automatically.
### 4. Credential Service (shared infrastructure)
`cry01` exposes a credential issuance endpoint on the orchestrator that other addons (`poll01` and future significant diagnostic result addons) call to issue VCs and OTS proofs for their own results. This endpoint is internal — accessible only over the Wireguard tunnel — and authenticated with the node token.
This is the function that makes `cry01` a dependency of `poll01`. A poll result is not just a count of votes. It is a VC issued by the Civic Infrastructure, timestamped on Bitcoin, carried by verified identities that have been independently certified through SASE and optionally through Ğ1.
---
## Route Structure
@@ -119,6 +158,16 @@ Access state resolution follows the same pattern as `vs01`, `dsc01`, and `scn01`
---
## Orchestrator Components
The orchestrator node (`orchestrator1`) runs two services that support `cry01` and all future credential-dependent addons:
**`duniter-mirror.service`** — Duniter v2 mirror node, synced to Ğ1 mainnet. Provides the RPC endpoint at `ws://127.0.0.1:9944` for balance queries and attestation document construction. Accessible to the Hubzilla node via Wireguard tunnel at `http://10.0.0.105:9944`.
**`civic-orchestrator.service`** — FastAPI spool receiver. Accepts signal POST requests from `cry01_spool.php`, validates the node token, issues VCs, generates OTS proofs, and writes the complete spool entry. Listens on `http://10.0.0.105:8700`. The credential issuance endpoint (`/cry01/credential/issue`) is the shared service that `poll01` and future addons call.
---
## Skeleton File Structure
```
@@ -140,6 +189,8 @@ hubzilla/addon/cry01/
contracts/
signal-v1.json — the capacity signal spool envelope contract
attestation-v1.json — the Ğ1 attestation document contract
vc-v1.json — the W3C Verifiable Credential envelope contract
ots-v1.json — the OpenTimestamps proof envelope contract
README.md
```
@@ -152,10 +203,13 @@ hubzilla/addon/cry01/
```json
{
"_note": "Copy to config.json. Do not commit config.json — it contains installation-specific values.",
"g1_rpc_endpoint": "REPLACE — local Duniter node endpoint, e.g. http://localhost:10901",
"g1_rpc_endpoint": "REPLACE — Duniter node RPC over Wireguard, e.g. http://10.0.0.105:9944",
"orchestrator_url": "REPLACE — spool receiver base URL, e.g. http://10.0.0.105:8700",
"operator_g1_pubkey": "REPLACE — operator Ğ1 public key (not private key — never store private keys)",
"operator_did": "REPLACE — operator did:web identifier, e.g. did:web:directory.diagnostics.kane-il.us",
"cache_file": "REPLACE — absolute path to balance cache JSON on the host",
"cache_max_age_seconds": 3600,
"ots_calendar_url": "https://alice.btc.calendar.opentimestamps.org",
"signal_categories": [
{
"_note": "Operator-defined capacity categories. Participants tag their signals with these.",
@@ -179,7 +233,7 @@ hubzilla/addon/cry01/
"description": "General availability — labor, assistance, or presence."
}
],
"receiver_url": "REPLACE — orchestrator receiver endpoint",
"receiver_url": "REPLACE — orchestrator spool receiver endpoint",
"node_token": "REPLACE — shared secret for node-to-orchestrator auth",
"listings_file": "REPLACE — absolute path to listings.json on the host",
"directory_default_tab": "core"
@@ -188,6 +242,66 @@ hubzilla/addon/cry01/
---
## W3C Verifiable Credential Contract — `contracts/vc-v1.json`
```json
{
"_meta": {
"contract": "cry01-vc",
"version": "1.0",
"purpose": "W3C Verifiable Credential envelope for Civic Infrastructure diagnostic results."
},
"_note": "This contract describes the VC structure. The actual VC is a JSON-LD document signed by the operator. The _payload field contains the claim specific to the issuing addon (signal, ballot, poll result, etc.).",
"vc_structure": {
"@context": ["https://www.w3.org/2018/credentials/v1"],
"type": ["VerifiableCredential"],
"issuer": "did:web:directory.diagnostics.kane-il.us",
"issuanceDate": "ISO 8601 timestamp",
"credentialSubject": {
"id": "did:web:directory.diagnostics.kane-il.us/channel/{xchan}",
"association": "association slug",
"claim_type": "signal | ballot | poll_result | sase_admission",
"claim": "addon-specific structured claim — see issuing addon spec"
},
"proof": {
"type": "Ed25519Signature2020",
"created": "ISO 8601 timestamp",
"verificationMethod": "did:web:directory.diagnostics.kane-il.us#operator-key",
"proofValue": "base58-encoded signature"
}
}
}
```
---
## OpenTimestamps Contract — `contracts/ots-v1.json`
```json
{
"_meta": {
"contract": "cry01-ots",
"version": "1.0",
"purpose": "OpenTimestamps proof envelope anchoring a diagnostic result to the Bitcoin blockchain."
},
"_header": {
"document_hash": "SHA-256 hash of the document being timestamped.",
"hash_algorithm": "sha256",
"timestamped_at": "ISO 8601 timestamp of OTS submission to calendar server.",
"calendar_url": "The OTS calendar server used.",
"addon": "The addon that generated this document (cry01, poll01, etc.)",
"association_slug": "The association this document pertains to."
},
"_payload": {
"ots_proof_base64": "Base64-encoded .ots proof file. Verifiable offline with the ots tool.",
"bitcoin_block": "Bitcoin block number in which the timestamp was confirmed. Null until confirmed.",
"confirmed_at": "ISO 8601 timestamp of Bitcoin confirmation. Null until confirmed."
}
}
```
---
## Capacity Signal Contract — `contracts/signal-v1.json`
```json
@@ -211,6 +325,10 @@ hubzilla/addon/cry01/
"duration_days": "How many days this capacity is available from submission date.",
"category_id": "One of the operator-defined signal_categories ids from config.json.",
"direction": "offer or seek — whether the participant is providing or requesting this capacity."
},
"_credentials": {
"vc": "The W3C Verifiable Credential issued for this signal. See contracts/vc-v1.json.",
"ots": "The OpenTimestamps proof for this signal. See contracts/ots-v1.json."
}
}
```
@@ -261,20 +379,6 @@ No changes to `CivicNav.php` or any PDL are required.
---
## What the Operator Will Decide Before This Is Built
1. **Duniter node setup** — the operator must run a local Duniter node. Duniter is lightweight and can run on the existing Hubzilla host. The operator confirms the node is running and the RPC endpoint is accessible before any code is written.
2. **Operator Ğ1 keypair** — the operator needs a Ğ1 keypair. Cesium wallet is the standard tool. The public key goes in `config.json`. The private key never leaves the operator's wallet and is never stored on the server.
3. **Signal category list** — the four categories in the config template (storage, transport, skill, time) are proposals. The operator confirms, modifies, or extends this list before the skeleton is built.
4. **Signal visibility** — signals are visible to SASE participants by default. The operator decides whether signals should also be visible to civic professionals, or restricted further.
5. **Signal duration policy** — when a signal's duration expires, does it disappear automatically or remain marked as expired? The operator decides.
---
## Build Sequence Within cry01
1. `cry01_chain.php` — Duniter RPC stubs, cache read/write
@@ -282,7 +386,8 @@ No changes to `CivicNav.php` or any PDL are required.
3. `cry01_renderer.php` — balance display, signal board, signal form, Ğ1 candidate list
4. `cry01_spool.php` — signal POST handler
5. Widget, PDL, CSS, JS
6. Ğ1 attestation builder — last, after all other functions confirmed working
6. Credential issuance — VC and OTS — integrated into spool receiver on orchestrator
7. Ğ1 attestation builder — last, after all other functions confirmed working
---