From 830648cbfa2fe21d9208e7da3b9c3482aed648fe Mon Sep 17 00:00:00 2001 From: DIDX Date: Wed, 10 Jun 2026 23:30:52 +0800 Subject: [PATCH] Add public TASK OpenAPI draft --- openapi/passpod-task.public.yaml | 232 +++++++++++++++++++++++++++++++ tools/check-public-task-repo.sh | 4 +- 2 files changed, 235 insertions(+), 1 deletion(-) create mode 100644 openapi/passpod-task.public.yaml diff --git a/openapi/passpod-task.public.yaml b/openapi/passpod-task.public.yaml new file mode 100644 index 0000000..7261789 --- /dev/null +++ b/openapi/passpod-task.public.yaml @@ -0,0 +1,232 @@ +openapi: 3.1.0 +info: + title: Passpod TASK Public Reference API + version: 0.1.0-draft + summary: Public draft API shape for Passpod TASK receipt validation. + description: > + This OpenAPI file is a public reference shape for Passpod TASK Core. + It describes schema inspection, public demo receipt validation, and receipt + lookup response shape. It does not define production receipt issuance, + production-valid signatures, scoped key generation, Passpod Hub internals, + issuer internals, or hosted Pilot Access behavior. + contact: + name: Passpod Pilot Access + email: pilots@passpod.io + license: + name: See repository LICENSE +servers: + - url: https://api.passpod.example + description: Placeholder reference URL; not a live production endpoint. +tags: + - name: Spec + description: Public draft standard metadata. + - name: Receipts + description: Public demo receipt validation and lookup response shapes. +paths: + /v1/spec: + get: + tags: [Spec] + summary: Get public TASK draft metadata. + description: > + Returns public draft metadata and points clients to the Trust Action + Receipt JSON Schema. This endpoint shape is informational and does not + create, sign, or issue receipts. + operationId: getTaskSpec + responses: + "200": + description: Public TASK draft metadata. + content: + application/json: + schema: + $ref: "#/components/schemas/PublicSpec" + examples: + publicDraft: + value: + name: Passpod TASK Core + status: public_draft + category: Sensitive Action Control + receipt_schema: https://passpod.io/schemas/trust-action-receipt.schema.json + production_issuance: false + pilot_access: pilots@passpod.io + /v1/receipts/validate: + post: + tags: [Receipts] + summary: Validate a Trust Action Receipt against the public schema. + description: > + Validates a provided Trust Action Receipt against the public JSON Schema + and public demo safety rules. A successful response means schema-valid + public draft receipt only. It does not mean the receipt was issued, + signed, verified, or production-valid. + operationId: validateTrustActionReceipt + requestBody: + required: true + content: + application/json: + schema: + $ref: "#/components/schemas/TrustActionReceipt" + responses: + "200": + description: Validation result for a public draft receipt. + content: + application/json: + schema: + $ref: "#/components/schemas/ReceiptValidationResult" + examples: + validDemoReceipt: + value: + valid: true + production_valid: false + status: schema_valid_public_demo + errors: [] + message: Schema-valid public demo receipt; not production issuance. + "400": + description: Invalid JSON body or invalid public receipt shape. + content: + application/json: + schema: + $ref: "#/components/schemas/ReceiptValidationResult" + /v1/receipts/{receipt_id}: + get: + tags: [Receipts] + summary: Get a receipt lookup response shape. + description: > + Defines the public response shape for receipt lookup. This reference + route does not imply that public demo receipts are hosted, production + receipts are publicly retrievable, or issuer authority is exposed. + Hosted verification belongs to Pilot Access. + operationId: getReceiptById + parameters: + - name: receipt_id + in: path + required: true + description: Public reference receipt identifier. + schema: + type: string + responses: + "200": + description: Receipt lookup response shape. + content: + application/json: + schema: + $ref: "#/components/schemas/ReceiptLookupResult" + "404": + description: Receipt not found or not publicly available. + content: + application/json: + schema: + $ref: "#/components/schemas/ErrorResponse" +components: + schemas: + PublicSpec: + type: object + required: [name, status, category, receipt_schema, production_issuance, pilot_access] + properties: + name: + type: string + example: Passpod TASK Core + status: + type: string + enum: [public_draft] + category: + type: string + enum: [Sensitive Action Control] + receipt_schema: + type: string + format: uri + production_issuance: + type: boolean + const: false + pilot_access: + type: string + format: email + TrustActionReceipt: + type: object + required: + - receipt_type + - scenario_id + - actor + - subject + - action + - decision + - evidence + - issued_at + properties: + receipt_type: + type: string + const: trust_action_receipt + scenario_id: + type: string + module: + type: string + actor: + type: string + subject: + type: string + action: + type: string + decision: + type: string + enum: [allow, deny, review_required, freeze, revoke] + evidence: + type: array + items: + type: string + issued_at: + type: string + format: date-time + signature: + type: string + description: Public examples use demo signatures only. + receipt_id: + type: string + description: Optional response field; public examples must not claim production receipt IDs. + policy_ref: + type: string + description: Optional response field; production workflow mapping requires Pilot Access. + proof_ref: + type: string + description: Optional response field; hosted verification requires Pilot Access. + additionalProperties: true + ReceiptValidationResult: + type: object + required: [valid, production_valid, status, errors] + properties: + valid: + type: boolean + production_valid: + type: boolean + const: false + status: + type: string + enum: + - schema_valid_public_demo + - schema_invalid + - public_safety_rejected + errors: + type: array + items: + type: string + message: + type: string + ReceiptLookupResult: + type: object + required: [receipt_id, production_valid, receipt] + properties: + receipt_id: + type: string + production_valid: + type: boolean + const: false + receipt: + $ref: "#/components/schemas/TrustActionReceipt" + message: + type: string + example: Public reference lookup shape; production verification requires Pilot Access. + ErrorResponse: + type: object + required: [error] + properties: + error: + type: string + message: + type: string diff --git a/tools/check-public-task-repo.sh b/tools/check-public-task-repo.sh index 76ff083..89a8e3a 100755 --- a/tools/check-public-task-repo.sh +++ b/tools/check-public-task-repo.sh @@ -2,12 +2,14 @@ set -euo pipefail fail() { echo "❌ $1" >&2; exit 1; } -required_files=(README.md SPEC.md PILOT_ACCESS.md ADOPTION.md SECURITY.md CONTRIBUTING.md GOVERNANCE.md VERSIONING.md requirements.txt schemas/trust-action-receipt.schema.json examples/remote-worker.receipt.json docs/public-vs-pilot.md docs/production-checklist.md docs/standardization-roadmap.md tools/validate-receipts.py) +required_files=(README.md SPEC.md PILOT_ACCESS.md ADOPTION.md SECURITY.md CONTRIBUTING.md GOVERNANCE.md VERSIONING.md requirements.txt schemas/trust-action-receipt.schema.json examples/remote-worker.receipt.json openapi/passpod-task.public.yaml docs/public-vs-pilot.md docs/production-checklist.md docs/standardization-roadmap.md tools/validate-receipts.py) for f in "${required_files[@]}"; do [ -f "$f" ] || fail "Missing required file: $f" done +find openapi -type f | grep -q . || fail "openapi/ must contain a public reference draft" + grep -R "No receipt, no sensitive action" README.md SPEC.md >/dev/null || fail "Canonical doctrine missing" grep -R "Sensitive Action Control" README.md SPEC.md ADOPTION.md >/dev/null || fail "Sensitive Action Control category missing" grep -R "public draft standard proposal" README.md SPEC.md ADOPTION.md >/dev/null || fail "Public draft standard proposal wording missing"