pikakit 1.0.0

package/specs/REGISTRY_V2_SPEC.md

@@ -0,0 +1,334 @@
+# REGISTRY_V2_SPEC.md  
+## Signed Remote Skill Registry Specification
+
+**Status:** Stable  
+**Version:** 2.0  
+**Applies to:** `@dataguruin/add-skill >= 1.0`  
+**Audience:** Registry operators, platform engineers, security engineers, AI agents
+
+---
+
+## 1. Purpose
+
+Registry v2 defines a **signed, remote, read-only index** for discovering and resolving **Agent Skills**.
+
+The registry provides **metadata only**.  
+It never distributes executables, never installs code, and never mutates environments.
+
+Registry v2 exists to enable:
+
+- Global skill discovery
+- Publisher attribution
+- Version resolution
+- Cryptographic integrity guarantees
+
+---
+
+## 2. Design Principles (NON-NEGOTIABLE)
+
+1. Registry data is **read-only**
+2. Registry index is **cryptographically signed**
+3. Registry is **advisory**, never authoritative
+4. Lock files always override registry data
+5. Registry never executes or distributes code
+6. Verification is mandatory, silence is forbidden
+
+---
+
+## 3. Threat Model
+
+Registry v2 explicitly defends against:
+
+- Registry tampering
+- CDN compromise
+- Man-in-the-middle attacks
+- Skill version substitution
+- Silent metadata modification
+
+Registry v2 does **not** attempt to:
+
+- Protect against compromised publishers
+- Enforce business logic or licensing
+- Execute or sandbox code
+
+---
+
+## 4. Architecture Overview
+
+```
+
+[ Registry Operator ]
+|
+|  (signed index.json)
+v
+[ Static Hosting / CDN ]
+|
+v
+[ add-skill Client ]
+
+````
+
+Characteristics:
+
+- Static file hosting only
+- HTTPS transport
+- Offline-cacheable
+- No authentication required for read access
+
+---
+
+## 5. Registry Index File
+
+### 5.1 File Name
+
+```txt
+index.json
+````
+
+---
+
+### 5.2 Canonical Schema
+
+```json
+{
+  "registryVersion": 2,
+  "generatedAt": "2026-01-23T14:00:00Z",
+  "registryPublisher": "dataguruin",
+  "signature": {
+    "algorithm": "ed25519",
+    "keyId": "dataguruin-registry-v1",
+    "value": "BASE64_SIGNATURE"
+  },
+  "skills": {
+    "coinpika-swipe-tabs": {
+      "repo": "dataguruin/coinpika-skills",
+      "publisher": "dataguruin",
+      "description": "Universal swipe-tab architecture for mobile PWA",
+      "latest": "1.2.3",
+      "versions": {
+        "1.2.3": {
+          "ref": "v1.2.3",
+          "checksum": "sha256:abcd...",
+          "engines": ["antigravity", "gemini"],
+          "tags": ["ui", "mobile", "swipe"]
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## 6. Signature Model
+
+### 6.1 Signed Payload
+
+The registry signature covers **all fields except `signature` itself**, including:
+
+* `registryVersion`
+* `generatedAt`
+* `registryPublisher`
+* Entire `skills` object
+
+Any modification to these fields invalidates the signature.
+
+---
+
+### 6.2 Algorithm Requirements
+
+* **Required:** `ed25519`
+* **Encoding:** Base64
+* **Key identification:** `keyId` MUST be globally unique per registry
+
+---
+
+### 6.3 Public Key Trust Store
+
+Registry public keys are stored locally at:
+
+```txt
+~/.add-skill/trusted-registries.json
+```
+
+Example:
+
+```json
+{
+  "dataguruin": {
+    "keys": {
+      "dataguruin-registry-v1": "BASE64_PUBLIC_KEY"
+    }
+  }
+}
+```
+
+Rules:
+
+* Unknown registry → WARN (FAIL in `--strict`)
+* Invalid signature → FAIL (always)
+* Expired or rotated keys MUST be explicitly trusted
+
+---
+
+## 7. Client Resolution Flow
+
+### 7.1 Fetch & Cache
+
+1. Download `index.json`
+2. Verify signature
+3. Cache locally
+4. Use cached copy when offline
+
+Signature verification is mandatory even when using cached data.
+
+---
+
+### 7.2 Install Resolution Order
+
+When installing a skill, the client resolves metadata in the following order:
+
+```
+1. skill-lock.json (--locked mode)
+2. Local registry (registry.json)
+3. Remote registry v2 (signed index)
+4. Explicit org/repo reference
+```
+
+The first successful resolution wins.
+
+---
+
+## 8. Registry Semantics
+
+### 8.1 Registry vs Lock File
+
+| Aspect     | Registry  | Lock File   |
+| ---------- | --------- | ----------- |
+| Purpose    | Discovery | Determinism |
+| Mutability | Mutable   | Immutable   |
+| Authority  | Advisory  | Absolute    |
+| CI Usage   | Optional  | Mandatory   |
+
+Registry data must **never** override lock file constraints.
+
+---
+
+### 8.2 Version Semantics
+
+* Each version entry is immutable
+* Checksum MUST NOT change after publication
+* `latest` is a convenience pointer, not authoritative
+
+---
+
+## 9. Client Commands (Registry-Aware)
+
+### 9.1 Add Registry
+
+```bash
+add-skill registry add https://registry.example.com/index.json
+```
+
+---
+
+### 9.2 List Registries
+
+```bash
+add-skill registry list
+```
+
+---
+
+### 9.3 Search Skills
+
+```bash
+add-skill search <query>
+```
+
+Search includes:
+
+* Skill name
+* Description
+* Tags
+
+---
+
+### 9.4 Skill Information
+
+```bash
+add-skill info <skill-name>
+```
+
+Displays:
+
+* Publisher
+* Repository
+* Available versions
+* Registry source
+* Signature status
+
+---
+
+## 10. Security Guarantees
+
+Registry v2 guarantees:
+
+* Registry tampering is detectable
+* Skill substitution is prevented by checksum verification
+* CDN compromise does not bypass trust
+* Silent metadata modification is impossible
+
+---
+
+## 11. Failure Modes (EXPLICIT)
+
+| Condition           | Client Behavior          |
+| ------------------- | ------------------------ |
+| Invalid signature   | FAIL                     |
+| Unknown registry    | WARN / FAIL (`--strict`) |
+| Network unavailable | Use cached registry      |
+| Skill missing       | FAIL                     |
+| Checksum mismatch   | FAIL                     |
+
+---
+
+## 12. Governance Recommendations
+
+* One registry per publisher identity
+* Separate keys for:
+
+  * Registry signing
+  * Skill signing
+* Key rotation via `keyId`
+* Public audit of registry history
+
+---
+
+## 13. Forward Compatibility
+
+Registry v2 is designed to support future extensions, including:
+
+* Paid skills
+* License metadata
+* Organization namespaces
+* Policy enforcement
+* Audit logs
+* Marketplace integration
+
+Backward compatibility must be preserved.
+
+---
+
+## 14. Design Philosophy
+
+Registry metadata is **signed policy**, not documentation.
+
+Trust must be explicit.
+Verification must be mandatory.
+Distribution must be passive.
+Silence is a bug.
+
+---
+
+**END OF REGISTRY V2 SPEC**