docs: add node1 runbooks, consolidation artifacts, and maintenance scripts
This commit is contained in:
Apple
42
docs/contracts/clan-artifact.schema.json
Normal file
42
docs/contracts/clan-artifact.schema.json
Normal file
@@ -0,0 +1,42 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://daarion.city/schemas/clan-artifact.schema.json",
|
||||
"title": "CLAN Artifact",
|
||||
"type": "object",
|
||||
"required": ["type", "visibility_level", "status", "content", "provenance"],
|
||||
"properties": {
|
||||
"type": {"type": "string", "minLength": 3},
|
||||
"visibility_level": {
|
||||
"type": "string",
|
||||
"enum": ["public", "interclan", "incircle", "soulsafe", "sacred"]
|
||||
},
|
||||
"status": {
|
||||
"type": "string",
|
||||
"enum": ["draft", "needs_confirmation", "waiting_for_consent", "confirmed", "proposed"]
|
||||
},
|
||||
"content": {
|
||||
"oneOf": [
|
||||
{"type": "string"},
|
||||
{"type": "object", "additionalProperties": true},
|
||||
{"type": "array", "items": {"type": "object", "additionalProperties": true}}
|
||||
]
|
||||
},
|
||||
"provenance": {"$ref": "clan-provenance.schema.json"},
|
||||
"required_confirmations": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"default": []
|
||||
},
|
||||
"links": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"default": []
|
||||
},
|
||||
"risk_flags": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"default": []
|
||||
}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
308
docs/contracts/clan-consent-adapter.openapi.yaml
Normal file
308
docs/contracts/clan-consent-adapter.openapi.yaml
Normal file
@@ -0,0 +1,308 @@
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: CLAN Consent Adapter API
|
||||
version: 1.0.0
|
||||
description: API for Consent Events and Testimony Drafts for CLAN/ZHOS flow.
|
||||
servers:
|
||||
- url: http://clan-consent-adapter:8111
|
||||
security:
|
||||
- BearerAuth: []
|
||||
tags:
|
||||
- name: health
|
||||
- name: consent
|
||||
- name: testimony
|
||||
paths:
|
||||
/health:
|
||||
get:
|
||||
tags: [health]
|
||||
summary: Service health check
|
||||
security: []
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/HealthResponse"
|
||||
/consent/events:
|
||||
post:
|
||||
tags: [consent]
|
||||
summary: Create consent event
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ConsentCreate"
|
||||
responses:
|
||||
"200":
|
||||
description: Consent event created
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ConsentCreateResponse"
|
||||
"400":
|
||||
$ref: "#/components/responses/BadRequest"
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
/consent/events/{event_id}:
|
||||
get:
|
||||
tags: [consent]
|
||||
summary: Get consent event by id
|
||||
parameters:
|
||||
- name: event_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: Consent event
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ConsentEvent"
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
"404":
|
||||
description: Not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
/testimony/drafts:
|
||||
post:
|
||||
tags: [testimony]
|
||||
summary: Create testimony draft
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/TestimonyDraftCreate"
|
||||
responses:
|
||||
"200":
|
||||
description: Testimony draft created
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/TestimonyCreateResponse"
|
||||
"400":
|
||||
$ref: "#/components/responses/BadRequest"
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
/testimony/drafts/{testimony_id}:
|
||||
get:
|
||||
tags: [testimony]
|
||||
summary: Get testimony draft by id
|
||||
parameters:
|
||||
- name: testimony_id
|
||||
in: path
|
||||
required: true
|
||||
schema:
|
||||
type: string
|
||||
responses:
|
||||
"200":
|
||||
description: Testimony draft
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/TestimonyDraft"
|
||||
"401":
|
||||
$ref: "#/components/responses/Unauthorized"
|
||||
"404":
|
||||
description: Not found
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
|
||||
components:
|
||||
securitySchemes:
|
||||
BearerAuth:
|
||||
type: http
|
||||
scheme: bearer
|
||||
bearerFormat: API key
|
||||
responses:
|
||||
BadRequest:
|
||||
description: Invalid input
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
Unauthorized:
|
||||
description: Unauthorized
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
schemas:
|
||||
VisibilityLevel:
|
||||
type: string
|
||||
enum: [public, interclan, incircle, soulsafe, sacred]
|
||||
HealthResponse:
|
||||
type: object
|
||||
required: [status, service]
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
example: ok
|
||||
service:
|
||||
type: string
|
||||
example: clan-consent-adapter
|
||||
ErrorResponse:
|
||||
type: object
|
||||
required: [detail]
|
||||
properties:
|
||||
detail:
|
||||
oneOf:
|
||||
- type: string
|
||||
- type: object
|
||||
ConsentCreate:
|
||||
type: object
|
||||
required: [circle, subject]
|
||||
properties:
|
||||
circle:
|
||||
type: string
|
||||
subject:
|
||||
type: string
|
||||
description: decision/testimony/bridge/rights
|
||||
method:
|
||||
type: string
|
||||
default: live_presence
|
||||
signers:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
default: []
|
||||
caveats:
|
||||
type: string
|
||||
nullable: true
|
||||
visibility_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
provenance:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
ConsentCreateResponse:
|
||||
type: object
|
||||
required: [consent_event_id, status, visibility_level]
|
||||
properties:
|
||||
consent_event_id:
|
||||
type: string
|
||||
format: uuid
|
||||
status:
|
||||
type: string
|
||||
example: confirmed
|
||||
visibility_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
ConsentEvent:
|
||||
type: object
|
||||
required:
|
||||
- id
|
||||
- circle
|
||||
- subject
|
||||
- method
|
||||
- signers
|
||||
- visibility_level
|
||||
- provenance
|
||||
- created_at
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
circle:
|
||||
type: string
|
||||
subject:
|
||||
type: string
|
||||
method:
|
||||
type: string
|
||||
signers:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
caveats:
|
||||
type: string
|
||||
nullable: true
|
||||
visibility_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
provenance:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
TestimonyDraftCreate:
|
||||
type: object
|
||||
required: [title, circle]
|
||||
properties:
|
||||
title:
|
||||
type: string
|
||||
circle:
|
||||
type: string
|
||||
visibility_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
content:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
status:
|
||||
type: string
|
||||
enum: [draft, needs_confirmation, confirmed]
|
||||
default: draft
|
||||
provenance:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
consent_event_id:
|
||||
type: string
|
||||
nullable: true
|
||||
TestimonyCreateResponse:
|
||||
type: object
|
||||
required: [testimony_id, status, visibility_level]
|
||||
properties:
|
||||
testimony_id:
|
||||
type: string
|
||||
format: uuid
|
||||
status:
|
||||
type: string
|
||||
enum: [draft, needs_confirmation, confirmed]
|
||||
visibility_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
TestimonyDraft:
|
||||
type: object
|
||||
required:
|
||||
- id
|
||||
- title
|
||||
- circle
|
||||
- visibility_level
|
||||
- content
|
||||
- status
|
||||
- provenance
|
||||
- created_at
|
||||
- updated_at
|
||||
properties:
|
||||
id:
|
||||
type: string
|
||||
format: uuid
|
||||
title:
|
||||
type: string
|
||||
circle:
|
||||
type: string
|
||||
visibility_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
content:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
status:
|
||||
type: string
|
||||
enum: [draft, needs_confirmation, confirmed]
|
||||
provenance:
|
||||
type: object
|
||||
additionalProperties: true
|
||||
consent_event_id:
|
||||
type: string
|
||||
nullable: true
|
||||
created_at:
|
||||
type: string
|
||||
format: date-time
|
||||
updated_at:
|
||||
type: string
|
||||
format: date-time
|
||||
429
docs/contracts/clan-consent-event.schema.json
Normal file
429
docs/contracts/clan-consent-event.schema.json
Normal file
@@ -0,0 +1,429 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://jos.local/schemas/clan-consent-event.schema.json",
|
||||
"title": "CLAN ConsentEvent Schema",
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"consent_event_id",
|
||||
"ts",
|
||||
"scope",
|
||||
"decision",
|
||||
"target",
|
||||
"confirmations",
|
||||
"quorum",
|
||||
"provenance",
|
||||
"versions"
|
||||
],
|
||||
"properties": {
|
||||
"consent_event_id": {
|
||||
"type": "string",
|
||||
"minLength": 3,
|
||||
"maxLength": 128,
|
||||
"pattern": "^ce_[A-Za-z0-9_-]+$"
|
||||
},
|
||||
"ts": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
},
|
||||
"scope": {
|
||||
"$ref": "#/$defs/scope"
|
||||
},
|
||||
"decision": {
|
||||
"$ref": "#/$defs/decision"
|
||||
},
|
||||
"target": {
|
||||
"$ref": "#/$defs/target"
|
||||
},
|
||||
"confirmations": {
|
||||
"type": "array",
|
||||
"minItems": 0,
|
||||
"maxItems": 256,
|
||||
"items": {
|
||||
"$ref": "#/$defs/confirmation"
|
||||
}
|
||||
},
|
||||
"quorum": {
|
||||
"$ref": "#/$defs/quorum"
|
||||
},
|
||||
"provenance": {
|
||||
"$ref": "#/$defs/event_provenance"
|
||||
},
|
||||
"versions": {
|
||||
"$ref": "#/$defs/versions"
|
||||
},
|
||||
"integrity": {
|
||||
"$ref": "#/$defs/integrity"
|
||||
}
|
||||
},
|
||||
"allOf": [
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"decision": {
|
||||
"properties": {
|
||||
"type": {
|
||||
"enum": [
|
||||
"approve",
|
||||
"reject"
|
||||
]
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"type"
|
||||
]
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"decision"
|
||||
]
|
||||
},
|
||||
"then": {
|
||||
"properties": {
|
||||
"confirmations": {
|
||||
"minItems": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
},
|
||||
{
|
||||
"if": {
|
||||
"properties": {
|
||||
"decision": {
|
||||
"properties": {
|
||||
"type": {
|
||||
"const": "revoke"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"type"
|
||||
]
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"decision"
|
||||
]
|
||||
},
|
||||
"then": {
|
||||
"properties": {
|
||||
"confirmations": {
|
||||
"minItems": 1
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"$defs": {
|
||||
"nonEmptyString": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"unixTimeInt": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
},
|
||||
"sha256Ref": {
|
||||
"type": "string",
|
||||
"pattern": "^(sha256:)?[A-Fa-f0-9]{12,64}$"
|
||||
},
|
||||
"visibilityLevel": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"public",
|
||||
"interclan",
|
||||
"incircle",
|
||||
"soulsafe",
|
||||
"sacred"
|
||||
]
|
||||
},
|
||||
"consentDecisionType": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"approve",
|
||||
"reject",
|
||||
"revoke"
|
||||
]
|
||||
},
|
||||
"targetType": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"artifact",
|
||||
"policy",
|
||||
"bridge_request",
|
||||
"allocation",
|
||||
"core_change"
|
||||
]
|
||||
},
|
||||
"operationType": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"execute",
|
||||
"export",
|
||||
"grant_access",
|
||||
"change_visibility",
|
||||
"merge_offline",
|
||||
"publish",
|
||||
"transfer",
|
||||
"dao_action",
|
||||
"core_update"
|
||||
]
|
||||
},
|
||||
"channelType": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"ui",
|
||||
"api",
|
||||
"telegram",
|
||||
"matrix",
|
||||
"internal",
|
||||
"webhook",
|
||||
"bridge"
|
||||
]
|
||||
},
|
||||
"confirmationMethod": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"voice",
|
||||
"biometric",
|
||||
"key_signature",
|
||||
"in_person"
|
||||
]
|
||||
},
|
||||
"scope": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"circle_id",
|
||||
"visibility_level"
|
||||
],
|
||||
"properties": {
|
||||
"circle_id": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
{
|
||||
"maxLength": 128
|
||||
}
|
||||
]
|
||||
},
|
||||
"gate_level": {
|
||||
"type": "string",
|
||||
"maxLength": 64
|
||||
},
|
||||
"visibility_level": {
|
||||
"$ref": "#/$defs/visibilityLevel"
|
||||
}
|
||||
}
|
||||
},
|
||||
"decision": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"type"
|
||||
],
|
||||
"properties": {
|
||||
"type": {
|
||||
"$ref": "#/$defs/consentDecisionType"
|
||||
},
|
||||
"reason": {
|
||||
"type": "string",
|
||||
"maxLength": 240
|
||||
},
|
||||
"expires_at": {
|
||||
"$ref": "#/$defs/unixTimeInt"
|
||||
}
|
||||
}
|
||||
},
|
||||
"target": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"target_type",
|
||||
"artifact_ids",
|
||||
"operation"
|
||||
],
|
||||
"properties": {
|
||||
"target_type": {
|
||||
"$ref": "#/$defs/targetType"
|
||||
},
|
||||
"artifact_ids": {
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"maxItems": 512,
|
||||
"items": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
{
|
||||
"maxLength": 128
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"operation": {
|
||||
"$ref": "#/$defs/operationType"
|
||||
},
|
||||
"intent": {
|
||||
"type": "string",
|
||||
"maxLength": 200
|
||||
}
|
||||
}
|
||||
},
|
||||
"confirmation": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"actor",
|
||||
"method",
|
||||
"step_up",
|
||||
"ts"
|
||||
],
|
||||
"properties": {
|
||||
"actor": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"type",
|
||||
"id"
|
||||
],
|
||||
"properties": {
|
||||
"type": {
|
||||
"type": "string",
|
||||
"const": "human"
|
||||
},
|
||||
"id": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
{
|
||||
"maxLength": 128
|
||||
}
|
||||
]
|
||||
},
|
||||
"display": {
|
||||
"type": "string",
|
||||
"maxLength": 120
|
||||
}
|
||||
}
|
||||
},
|
||||
"method": {
|
||||
"$ref": "#/$defs/confirmationMethod"
|
||||
},
|
||||
"step_up": {
|
||||
"type": "boolean"
|
||||
},
|
||||
"proof_ref": {
|
||||
"type": "string",
|
||||
"maxLength": 256
|
||||
},
|
||||
"ts": {
|
||||
"$ref": "#/$defs/unixTimeInt"
|
||||
}
|
||||
}
|
||||
},
|
||||
"quorum": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"rule",
|
||||
"required",
|
||||
"present"
|
||||
],
|
||||
"properties": {
|
||||
"rule": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"unanimous",
|
||||
"majority",
|
||||
"custom"
|
||||
]
|
||||
},
|
||||
"required": {
|
||||
"type": "integer",
|
||||
"minimum": 1,
|
||||
"maximum": 1024
|
||||
},
|
||||
"present": {
|
||||
"type": "integer",
|
||||
"minimum": 0,
|
||||
"maximum": 1024
|
||||
}
|
||||
}
|
||||
},
|
||||
"event_provenance": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"channel",
|
||||
"request_id",
|
||||
"input_hash"
|
||||
],
|
||||
"properties": {
|
||||
"channel": {
|
||||
"$ref": "#/$defs/channelType"
|
||||
},
|
||||
"request_id": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
{
|
||||
"maxLength": 128
|
||||
}
|
||||
]
|
||||
},
|
||||
"input_hash": {
|
||||
"$ref": "#/$defs/sha256Ref"
|
||||
}
|
||||
}
|
||||
},
|
||||
"versions": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"constitution_version",
|
||||
"protocol_version"
|
||||
],
|
||||
"properties": {
|
||||
"constitution_version": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
{
|
||||
"maxLength": 128
|
||||
}
|
||||
]
|
||||
},
|
||||
"protocol_version": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
{
|
||||
"maxLength": 128
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"integrity": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"required": [
|
||||
"event_hash"
|
||||
],
|
||||
"properties": {
|
||||
"event_hash": {
|
||||
"$ref": "#/$defs/sha256Ref"
|
||||
},
|
||||
"prev_hash": {
|
||||
"$ref": "#/$defs/sha256Ref"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
45
docs/contracts/clan-envelope.schema.json
Normal file
45
docs/contracts/clan-envelope.schema.json
Normal file
@@ -0,0 +1,45 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://daarion.city/schemas/clan-envelope.schema.json",
|
||||
"title": "CLAN Envelope",
|
||||
"type": "object",
|
||||
"required": [
|
||||
"request_id",
|
||||
"visibility_level_target",
|
||||
"consent_status",
|
||||
"allowed_actions",
|
||||
"expected_output",
|
||||
"input_text"
|
||||
],
|
||||
"properties": {
|
||||
"request_id": {"type": "string", "minLength": 8},
|
||||
"circle_context": {"type": "object", "additionalProperties": true},
|
||||
"visibility_level_target": {
|
||||
"type": "string",
|
||||
"enum": ["public", "interclan", "incircle", "soulsafe", "sacred"]
|
||||
},
|
||||
"sensitivity_flags": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"default": []
|
||||
},
|
||||
"consent_status": {
|
||||
"type": "string",
|
||||
"enum": ["none", "pending", "confirmed"]
|
||||
},
|
||||
"allowed_actions": {
|
||||
"type": "array",
|
||||
"items": {"type": "string"},
|
||||
"minItems": 1
|
||||
},
|
||||
"expected_output": {
|
||||
"oneOf": [
|
||||
{"type": "string"},
|
||||
{"type": "array", "items": {"type": "string"}, "minItems": 1}
|
||||
]
|
||||
},
|
||||
"input_text": {"type": "string", "minLength": 1},
|
||||
"provenance": {"type": "object", "additionalProperties": true}
|
||||
},
|
||||
"additionalProperties": false
|
||||
}
|
||||
268
docs/contracts/clan-provenance.schema.json
Normal file
268
docs/contracts/clan-provenance.schema.json
Normal file
@@ -0,0 +1,268 @@
|
||||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"$id": "https://jos.local/schemas/clan-provenance.schema.json",
|
||||
"title": "CLAN Provenance Schema",
|
||||
"type": "array",
|
||||
"minItems": 1,
|
||||
"items": {
|
||||
"$ref": "#/$defs/trail"
|
||||
},
|
||||
"$defs": {
|
||||
"nonEmptyString": {
|
||||
"type": "string",
|
||||
"minLength": 1
|
||||
},
|
||||
"unixTimeInt": {
|
||||
"type": "integer",
|
||||
"minimum": 0
|
||||
},
|
||||
"sha256Ref": {
|
||||
"type": "string",
|
||||
"pattern": "^(sha256:)?[A-Fa-f0-9]{12,64}$"
|
||||
},
|
||||
"visibilityLevel": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"public",
|
||||
"interclan",
|
||||
"incircle",
|
||||
"soulsafe",
|
||||
"sacred"
|
||||
]
|
||||
},
|
||||
"consentStatus": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"none",
|
||||
"pending",
|
||||
"confirmed"
|
||||
]
|
||||
},
|
||||
"actorType": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"human",
|
||||
"agent",
|
||||
"system",
|
||||
"external"
|
||||
]
|
||||
},
|
||||
"opType": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"created",
|
||||
"summarized",
|
||||
"redacted",
|
||||
"classified",
|
||||
"validated",
|
||||
"composed",
|
||||
"merged",
|
||||
"stamped",
|
||||
"export_validated",
|
||||
"policy_checked",
|
||||
"synced",
|
||||
"imported",
|
||||
"corrected"
|
||||
]
|
||||
},
|
||||
"versions": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"constitution_version": {
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
"agent_prompt_version": {
|
||||
"type": "string"
|
||||
},
|
||||
"router_guard_version": {
|
||||
"type": "string"
|
||||
},
|
||||
"protocol_version": {
|
||||
"type": "string"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"constitution_version"
|
||||
]
|
||||
},
|
||||
"actor": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"type": {
|
||||
"$ref": "#/$defs/actorType"
|
||||
},
|
||||
"id": {
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
"display": {
|
||||
"type": "string",
|
||||
"maxLength": 120
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"type",
|
||||
"id"
|
||||
]
|
||||
},
|
||||
"source": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"channel": {
|
||||
"type": "string",
|
||||
"enum": [
|
||||
"ui",
|
||||
"api",
|
||||
"telegram",
|
||||
"matrix",
|
||||
"dao",
|
||||
"chain",
|
||||
"import",
|
||||
"internal",
|
||||
"webhook",
|
||||
"bridge"
|
||||
]
|
||||
},
|
||||
"request_id": {
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
"session_id": {
|
||||
"type": "string",
|
||||
"maxLength": 128
|
||||
},
|
||||
"message_id": {
|
||||
"type": "string",
|
||||
"maxLength": 128
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"channel",
|
||||
"request_id"
|
||||
]
|
||||
},
|
||||
"context": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"circle_id": {
|
||||
"type": "string",
|
||||
"maxLength": 128
|
||||
},
|
||||
"circle_name": {
|
||||
"type": "string",
|
||||
"maxLength": 128
|
||||
},
|
||||
"gate_level": {
|
||||
"type": "string",
|
||||
"maxLength": 64
|
||||
},
|
||||
"visibility_level": {
|
||||
"$ref": "#/$defs/visibilityLevel"
|
||||
},
|
||||
"consent_status": {
|
||||
"$ref": "#/$defs/consentStatus"
|
||||
},
|
||||
"consent_event_ref": {
|
||||
"type": "string",
|
||||
"maxLength": 256
|
||||
}
|
||||
}
|
||||
},
|
||||
"operation": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"op": {
|
||||
"$ref": "#/$defs/opType"
|
||||
},
|
||||
"input_hash": {
|
||||
"$ref": "#/$defs/sha256Ref"
|
||||
},
|
||||
"output_hash": {
|
||||
"$ref": "#/$defs/sha256Ref"
|
||||
},
|
||||
"notes": {
|
||||
"type": "string",
|
||||
"maxLength": 200
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"op"
|
||||
]
|
||||
},
|
||||
"links": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"parent_artifact_ids": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
"maxItems": 64
|
||||
},
|
||||
"related_artifact_ids": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
"maxItems": 64
|
||||
},
|
||||
"external_refs": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
"maxItems": 64
|
||||
}
|
||||
}
|
||||
},
|
||||
"trail": {
|
||||
"type": "object",
|
||||
"additionalProperties": false,
|
||||
"properties": {
|
||||
"event_id": {
|
||||
"allOf": [
|
||||
{
|
||||
"$ref": "#/$defs/nonEmptyString"
|
||||
},
|
||||
{
|
||||
"maxLength": 128
|
||||
}
|
||||
]
|
||||
},
|
||||
"ts": {
|
||||
"$ref": "#/$defs/unixTimeInt"
|
||||
},
|
||||
"actor": {
|
||||
"$ref": "#/$defs/actor"
|
||||
},
|
||||
"source": {
|
||||
"$ref": "#/$defs/source"
|
||||
},
|
||||
"context": {
|
||||
"$ref": "#/$defs/context"
|
||||
},
|
||||
"operation": {
|
||||
"$ref": "#/$defs/operation"
|
||||
},
|
||||
"versions": {
|
||||
"$ref": "#/$defs/versions"
|
||||
},
|
||||
"links": {
|
||||
"$ref": "#/$defs/links"
|
||||
}
|
||||
},
|
||||
"required": [
|
||||
"event_id",
|
||||
"ts",
|
||||
"actor",
|
||||
"source",
|
||||
"operation",
|
||||
"versions"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
164
docs/contracts/clan-visibility-guard.openapi.yaml
Normal file
164
docs/contracts/clan-visibility-guard.openapi.yaml
Normal file
@@ -0,0 +1,164 @@
|
||||
openapi: 3.1.0
|
||||
info:
|
||||
title: CLAN Visibility Guard API
|
||||
version: 1.0.0
|
||||
description: Visibility policy checks and sensitivity classification for CLAN/ZHOS.
|
||||
servers:
|
||||
- url: http://clan-visibility-guard:8112
|
||||
tags:
|
||||
- name: health
|
||||
- name: visibility
|
||||
paths:
|
||||
/health:
|
||||
get:
|
||||
tags: [health]
|
||||
summary: Service health check
|
||||
responses:
|
||||
"200":
|
||||
description: OK
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/HealthResponse"
|
||||
/visibility/check_downgrade:
|
||||
post:
|
||||
tags: [visibility]
|
||||
summary: Check if requested visibility downgrade is allowed
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/VisibilityCheckRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: Downgrade check result
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/VisibilityCheckResponse"
|
||||
"400":
|
||||
description: Invalid visibility level
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
/visibility/classify:
|
||||
post:
|
||||
tags: [visibility]
|
||||
summary: Classify text sensitivity and recommend level
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ClassifyRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: Classification result
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ClassifyResponse"
|
||||
/visibility/redact_for_level:
|
||||
post:
|
||||
tags: [visibility]
|
||||
summary: Redact text for target visibility level
|
||||
requestBody:
|
||||
required: true
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/RedactRequest"
|
||||
responses:
|
||||
"200":
|
||||
description: Redaction result
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/RedactResponse"
|
||||
"400":
|
||||
description: Invalid visibility level
|
||||
content:
|
||||
application/json:
|
||||
schema:
|
||||
$ref: "#/components/schemas/ErrorResponse"
|
||||
|
||||
components:
|
||||
schemas:
|
||||
VisibilityLevel:
|
||||
type: string
|
||||
enum: [public, interclan, incircle, soulsafe, sacred]
|
||||
HealthResponse:
|
||||
type: object
|
||||
required: [status, service]
|
||||
properties:
|
||||
status:
|
||||
type: string
|
||||
example: ok
|
||||
service:
|
||||
type: string
|
||||
example: clan-visibility-guard
|
||||
ErrorResponse:
|
||||
type: object
|
||||
required: [detail]
|
||||
properties:
|
||||
detail:
|
||||
oneOf:
|
||||
- type: string
|
||||
- type: object
|
||||
VisibilityCheckRequest:
|
||||
type: object
|
||||
required: [current_level, requested_level]
|
||||
properties:
|
||||
current_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
requested_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
VisibilityCheckResponse:
|
||||
type: object
|
||||
required: [allowed, reason, current_level, requested_level]
|
||||
properties:
|
||||
allowed:
|
||||
type: boolean
|
||||
reason:
|
||||
type: string
|
||||
enum: [ok, downgrade_requires_consent]
|
||||
current_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
requested_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
ClassifyRequest:
|
||||
type: object
|
||||
required: [text]
|
||||
properties:
|
||||
text:
|
||||
type: string
|
||||
ClassifyResponse:
|
||||
type: object
|
||||
required: [recommended_level, sensitivity_flags]
|
||||
properties:
|
||||
recommended_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
sensitivity_flags:
|
||||
type: array
|
||||
items:
|
||||
type: string
|
||||
RedactRequest:
|
||||
type: object
|
||||
required: [text, target_level]
|
||||
properties:
|
||||
text:
|
||||
type: string
|
||||
target_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
RedactResponse:
|
||||
type: object
|
||||
required: [target_level, redacted_text, changed]
|
||||
properties:
|
||||
target_level:
|
||||
$ref: "#/components/schemas/VisibilityLevel"
|
||||
redacted_text:
|
||||
type: string
|
||||
changed:
|
||||
type: boolean
|
||||
Reference in New Issue
Block a user