{ "openapi": "3.1.0", "info": { "title": "NOMOI appliance management API", "version": "0.1.0", "description": "Appliance API: bootstrap, TA authentication and its operator login gate, scope authorization, durable TA provisioning, operators, known identities, policy drafts, serialized asynchronous publications, suspension and audit history. TA creation registers the supplied initial administrator as both a root identity and an operator; it never imports the appliance operator identity. JSON metadata does not redefine signed protocol identity." }, "servers": [ { "url": "/api/v1" } ], "paths": { "/tas/{ta_id}/inspection/operators/{operator_id}": { "delete": { "operationId": "removeInspectedOperator", "summary": "Remove an operator of an inspected local TA", "description": "Operator-authorized removal of a local operator registration from any inspected TA, including the self TA, initial administrators, published roots and pending roots. Published root grants, saved and queued publication snapshots, and bootstrap enrollment are independent and are retained. Accepted changes are audited in both TAs.", "x-implementation-phase": 7, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.operator.remove", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "Operator belongs to the inspected local TA; the session belongs to the authorizing operator TA.", "context_requirements": [ "Verified operator TA session; administration or the exact declared action grant.", "Target TA must be locally registered.", "Inspection removes only the local registration; published and pending roots and bootstrap enrollment remain intact." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "operator_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for administration sessions; required for login-only subjects using an exact operator.remove action grant.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The operator was removed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "operator_id": { "type": "string" }, "removed": { "type": "boolean" } }, "required": [ "operator_id", "removed" ] } } } }, "default": { "description": "Application failure. Operator registrations are removable independently of published roots and publication snapshots.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tas/{ta_id}/inspection/drafts": { "get": { "operationId": "listInspectedDrafts", "summary": "List saved policy drafts", "description": "Saved editable drafts in the target TA partition, ordered by opaque draft ID with cursor pagination. Includes drafts whose base is no longer the published head.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.inspect", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "Resources belong to the inspected local TA; authority belongs to the operator TA.", "context_requirements": [ "Verified operator TA session; administration or the exact declared action grant.", "Target TA must be locally registered." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraftList" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] }, "post": { "operationId": "createInspectedDraft", "summary": "Inspector: createDraft", "description": "Operator-authorized operation in the inspected local TA partition. Changes are audited in both TAs. See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.policy", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "Resources belong to the inspected local TA; authority belongs to the operator TA.", "context_requirements": [ "Verified operator TA session; administration or the exact declared action grant.", "Target TA must be locally registered." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraft" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tas/{ta_id}/inspection/drafts/{draft_id}": { "delete": { "operationId": "deleteInspectedDraft", "summary": "Delete a saved policy draft", "description": "Deletes only the saved editable draft at the submitted revision. Published policy, publication history and immutable publication snapshots are retained, including queued snapshots. Audited in the authorizing TA and, for inspection, the inspected TA.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.policy", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "Resources belong to the inspected local TA; authority belongs to the operator TA.", "context_requirements": [ "Verified operator TA session; administration or the exact declared action grant.", "Target TA must be locally registered." ], "resources": [ { "kind": "ta_draft", "parameter": "draft_id" } ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDeleted" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDeletion" } } } } }, "get": { "operationId": "getInspectedDraft", "summary": "Inspector: getDraft", "description": "Operator-authorized operation in the inspected local TA partition. Changes are audited in both TAs. See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.inspect", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "Resources belong to the inspected local TA; authority belongs to the operator TA.", "context_requirements": [ "Verified operator TA session; administration or the exact declared action grant.", "Target TA must be locally registered." ], "resources": [ { "kind": "ta_draft", "parameter": "draft_id" } ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraft" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ] }, "put": { "operationId": "editInspectedDraft", "summary": "Inspector: editDraft", "description": "Operator-authorized operation in the inspected local TA partition. Changes are audited in both TAs. Replace policy fields with revision conflict protection. A TA administration session covers all fields; auth-only sessions require ta.edit and the additional per-field action authorities.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.policy", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "Resources belong to the inspected local TA; authority belongs to the operator TA.", "context_requirements": [ "Verified operator TA session; administration or the exact declared action grant.", "Target TA must be locally registered." ], "resources": [ { "kind": "ta_draft", "parameter": "draft_id" } ], "additional_scopes_on_fields": { "root_identity_ids": ".nomos.web.tas.policy.operator", "whitelist": ".nomos.web.tas.policy.whitelist", "revocations": ".nomos.web.tas.policy.revoke" }, "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraft" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InspectedTADraftEdit" } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/verifiers": { "get": { "operationId": "listVerifiers", "summary": "List public Trust Anchor verifiers", "description": "Ready TAs that opted into public listing, plus the private ready TA of the currently authenticated administrator. Ordered by scope prefix and IPNS ID. Includes only scope_prefix and ipns_id. Suspended, failed and provisioning TAs are excluded. Listing governs only this directory: publicVerify, publicChallenge and publicChallengeResponse answer for any ready TA by its IPNS ID.", "x-implementation-phase": 7, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Public verifier directory", "content": { "application/json": { "schema": { "type": "object", "required": ["items"], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": ["scope_prefix", "ipns_id"], "additionalProperties": false, "properties": { "scope_prefix": { "type": "string" }, "ipns_id": { "type": "string" } } } } } } } } }, "503": { "description": "Verifier directory unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/verifiers/{ipns_id}/verify": { "post": { "operationId": "publicVerify", "summary": "Verify a mandate chain with a TA's verifier", "description": "Runs the full verification (§6.3) of a chain, named by CID or presented inline, on the verifier of the ready TA with this IPNS ID, whether or not it is listed. Needs no session. Acceptance says the chain is sound, not who holds it. Nothing is retained.", "x-implementation-phase": 9, "x-authorization": { "mode": "public" }, "security": [], "parameters": [ { "name": "ipns_id", "in": "path", "required": true, "description": "The Trust Anchor's bare IPNS ID (k51...), not its TA ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MandateInput" } } } }, "responses": { "200": { "description": "Chain accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicVerification" } } } }, "417": { "description": "The chain is not valid: every problem found and what of it was decoded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRejection" } } } }, "default": { "description": "Rejected, inconclusive or unusable. 503 is inconclusive and carries no code; retry. 404 names no hosted TA; 422 an unusable request, or a mandate the verifier could not read, with its reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/verifiers/{ipns_id}/challenge": { "post": { "operationId": "publicChallenge", "summary": "Challenge the holder of a verified mandate", "description": "Verifies the chain as publicVerify does, then issues a nonce for the key its leaf delegates to (§6.9). Sign it with nomos sign, or with a browser key, and answer with publicChallengeResponse on the same TA before expires_at.", "x-implementation-phase": 9, "x-authorization": { "mode": "public" }, "security": [], "parameters": [ { "name": "ipns_id", "in": "path", "required": true, "description": "The Trust Anchor's bare IPNS ID (k51...), not its TA ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MandateInput" } } } }, "responses": { "200": { "description": "Chain accepted and challenge issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicChallenge" } } } }, "417": { "description": "The chain is not valid, so no challenge was issued: every problem found and what of it was decoded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRejection" } } } }, "default": { "description": "Rejected, inconclusive or unusable. 503 is inconclusive and carries no code; retry. 404 names no hosted TA; 422 an unusable request, or a mandate the verifier could not read, with its reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/verifiers/{ipns_id}/challenge/response": { "post": { "operationId": "publicChallengeResponse", "summary": "Prove possession of the challenged key", "description": "Submits only the nonce and the raw signature (§6.9) to the verifier that issued the nonce. The nonce is consumed whether or not the signature verifies; request a new challenge to retry.", "x-implementation-phase": 9, "x-authorization": { "mode": "public" }, "security": [], "parameters": [ { "name": "ipns_id", "in": "path", "required": true, "description": "The Trust Anchor's bare IPNS ID (k51...), not its TA ID.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ChallengeAnswer" } } } }, "responses": { "200": { "description": "Key possession proven", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicProof" } } } }, "417": { "description": "The signature does not prove possession, or the nonce is unknown or spent: its problems", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicRejection" } } } }, "default": { "description": "Signature rejected, nonce unknown or expired, inconclusive or unusable. 503 is inconclusive and carries no code; retry. 404 names no hosted TA; 422 an unusable request, or a mandate the verifier could not read, with its reason.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/roots/{fingerprint}": { "get": { "operationId": "listRootAnchors", "summary": "List the Trust Anchors hosted here that a key is a root of", "description": "Every hosted TA, in any state and whether or not its verifier is listed, whose last published state registers the key as a root identity, with that state's CID: what a browser key needs to issue a root mandate before any session exists. Read from the appliance's own records, not the transport; the operator's enrollment state stands in until its first sign-in. Ordered by scope prefix and IPNS ID.", "x-implementation-phase": 8, "x-authorization": { "mode": "public" }, "security": [], "parameters": [ { "name": "fingerprint", "in": "path", "required": true, "description": "The key's fingerprint: its public key bytes in lowercase hex.", "schema": { "type": "string", "pattern": "^([0-9a-f]{2}){1,256}$" } } ], "responses": { "200": { "description": "Trust Anchors the key is a root of", "content": { "application/json": { "schema": { "type": "object", "required": ["items"], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": ["scope_prefix", "ipns_id", "operator", "published_cid"], "additionalProperties": false, "properties": { "scope_prefix": { "type": "string" }, "ipns_id": { "type": "string" }, "operator": { "type": "boolean" }, "published_cid": { "type": "string", "description": "The TA state that registers the key; a root mandate's Issuer." } } } } } } } } }, "422": { "description": "Not a fingerprint", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Root directory unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/health": { "get": { "operationId": "health", "summary": "health", "description": "See platform API integration guide.", "x-implementation-phase": 1, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ready": { "get": { "operationId": "readiness", "summary": "readiness", "description": "Bounded aggregate readiness: metadata, bootstrap, shared Kubo identity, expected TA workers and pending/retrying publications. Pending jobs and unavailable dependencies return 503. Suspended workers are excluded. No customer identifiers are exposed.", "x-implementation-phase": 1, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Readiness" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Not ready", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/Readiness" }, { "$ref": "#/components/schemas/Error" } ] } } } } } } }, "/openapi.json": { "get": { "operationId": "openapi", "summary": "openapi", "description": "The OpenAPI document itself.", "x-implementation-phase": 1, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bootstrap": { "get": { "operationId": "bootstrapStatus", "summary": "bootstrapStatus", "description": "Public setup state, operator identifier and authentication scope, current publication progress and retry diagnostics. Poll until awaiting_enrollment, then enroll; poll until awaiting_nomoi_login before authenticating.", "x-implementation-phase": 3, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapStatus" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/bootstrap/sessions": { "post": { "operationId": "bootstrapAuthenticate", "summary": "bootstrapAuthenticate", "description": "See platform API integration guide.", "x-implementation-phase": 3, "x-authorization": { "mode": "public" }, "security": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapSession" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BootstrapCredentials" } } } } } }, "/bootstrap/enrollment": { "post": { "operationId": "bootstrapEnroll", "summary": "bootstrapEnroll", "description": "See platform API integration guide.", "x-implementation-phase": 3, "x-authorization": { "mode": "bootstrap" }, "security": [ { "bootstrapBearer": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EnrollmentResult" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrollment" } } } }, "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Same actor, operation and key reuse one durable job; different payload yields 409.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tas/{ta_id}/login-attempts": { "post": { "operationId": "beginLogin", "summary": "beginLogin", "description": "Select only a ready TA from the trusted registry; verify its exact authentication or administration scope and capture leaf, subject, algorithm, nonce and chain expiry. Until bootstrap is active, operator login requires the enrolled subject. Cookie transport requires the configured Origin and sets a separate HttpOnly browser-binding cookie for this attempt; bearer transport returns an opaque binding token without cookies.", "x-implementation-phase": 4, "x-authorization": { "mode": "public", "scope_template": ".nomos.web.auth", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The selected ta must be ready.", "context_requirements": [ "Prove possession through the selected ta challenge-response flow." ], "administration_scope_template": ".nomos.web" }, "security": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAttempt" } } }, "headers": { "Set-Cookie": { "description": "Cookie transport only: HttpOnly, SameSite=Strict, Path=/, Secure for HTTPS. Begin sets an attempt-specific binding; completion clears it and rotates the session.", "schema": { "type": "string" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Origin", "in": "header", "required": false, "description": "Required for cookie login and completion and cookie-authenticated mutations; must exactly equal NOMOS_PLATFORM_PUBLIC_ORIGIN. Forwarded headers are not trusted.", "schema": { "type": "string" } } ] } }, "/tas/{ta_id}/login-attempts/{attempt_id}/response": { "post": { "operationId": "completeLogin", "summary": "completeLogin", "description": "Submit only signature and binding_token. Cookie attempts additionally require their browser-binding cookie and configured Origin. Atomically claim the attempt, consume the stored nonce on its original verifier, revalidate the original mandate and create one session. Failed/interrupted proof consumes the attempt. First enrolled-operator login permanently closes bootstrap. Cookie completion sets a new session cookie and returns csrf_token without a bearer token.", "x-implementation-phase": 4, "x-authorization": { "mode": "public" }, "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionResult" } } }, "headers": { "Set-Cookie": { "description": "Cookie transport only: HttpOnly, SameSite=Strict, Path=/, Secure for HTTPS. Begin sets an attempt-specific binding; completion clears it and rotates the session.", "schema": { "type": "string" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginResponse" } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "attempt_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "Origin", "in": "header", "required": false, "description": "Required for cookie login and completion and cookie-authenticated mutations; must exactly equal NOMOS_PLATFORM_PUBLIC_ORIGIN. Forwarded headers are not trusted.", "schema": { "type": "string" } } ] } }, "/session": { "get": { "operationId": "currentSession", "summary": "currentSession", "description": "Revalidate the stored login mandate on every read using its selected TA verifier. Confirmed rejection invalidates the session; infrastructure failure returns inconclusive 503 and retains it for retry. Sessions expire after at most one hour, bounded by the earliest chain expiry. Cookie responses include the session CSRF token. No management authority is implied.", "x-implementation-phase": 4, "x-authorization": { "mode": "session" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] }, { "localSessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/session/logout": { "post": { "operationId": "logout", "summary": "logout", "description": "Delete the application session. Cookie requests require the configured Origin and X-CSRF-Token. Does not contact the verifier, so logout remains available during outages. Bearer and cookie credentials cannot be interchanged or combined.", "x-implementation-phase": 4, "x-authorization": { "mode": "session" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] }, { "localSessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "Origin", "in": "header", "required": false, "description": "Required for cookie login and completion and cookie-authenticated mutations; must exactly equal NOMOS_PLATFORM_PUBLIC_ORIGIN. Forwarded headers are not trusted.", "schema": { "type": "string" } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required with cookie transport. Obtain the session-bound value from login completion or GET /session.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tas": { "get": { "operationId": "listTAs", "summary": "listTAs", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.read", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator manages registered tas; the operator cannot be suspended.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TAList" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] }, "post": { "operationId": "createTA", "summary": "createTA", "description": "Reserve a durable provisioning job and register the supplied initial administrator as both root identity and operator. Reusing Idempotency-Key with the same input returns the original response; different input returns 409. Poll GET /tas/{ta_id} for progress and verifier readiness.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.add", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator manages registered tas; the operator cannot be suspended.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TA" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TACreate" } } } }, "parameters": [ { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Same actor, operation and key reuse one durable job; different payload yields 409.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tas/{ta_id}/operators": { "get": { "operationId": "listOperators", "summary": "List operators", "description": "Lists the public keys registered with this TA as operators, by fingerprint. Only an operator can be a root of the TA's policy.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.operator.read", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OperatorList" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] }, "post": { "operationId": "registerOperator", "summary": "Register an operator", "description": "Registers a public key as an operator of this TA, so that a draft can name it as a root. It enrolls and publishes nothing; registering the same key again returns the existing operator.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.operator.add", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrollment" } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tas/{ta_id}/operators/{operator_id}": { "delete": { "operationId": "removeOperator", "summary": "Remove an operator", "description": "Removes an operator from this TA. Registration removal is independent of published roots, saved and pending publication snapshots, and bootstrap enrollment. Initial administrators and current or pending roots can be unregistered. Removing an operator does not revoke a published mandate or Trust Anchor; change and publish the policy to withdraw authority.", "x-implementation-phase": 7, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.operator.remove", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and operator must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "operator_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for administration sessions; required for login-only subjects using an exact operator.remove action grant.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The operator was removed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "operator_id": { "type": "string" }, "removed": { "type": "boolean" } }, "required": ["operator_id", "removed"] } } } }, "default": { "description": "Application failure. Operator registrations are removable independently of published roots and publication snapshots.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tas/{ta_id}/known-identities": { "get": { "operationId": "listKnownIdentities", "summary": "List known identities", "description": "Lists the public keys this TA's administrators have named as known identities, ordered by name ignoring ASCII case, then by fingerprint. The cursor is the last fingerprint of a page; if that identity has since been removed, the request fails and the listing starts again.", "x-implementation-phase": 8, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.known.read", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Known identities are an address book for issuing mandates. Adding or removing one grants, revokes and publishes nothing.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for administration sessions; required for login-only subjects using an exact known.read action grant.", "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnownIdentityList" } } } }, "default": { "description": "Application failure. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "addKnownIdentity", "summary": "Add or rename a known identity", "description": "Names a public key so that mandates can be issued to it without pasting the key. Adding a key that is already known under another name renames it. A known identity is not an operator: it cannot be a policy root, and adding one grants no authority.", "x-implementation-phase": 8, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.known.add", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Known identities are an address book for issuing mandates. Adding or removing one grants, revokes and publishes nothing.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for administration sessions; required for login-only subjects using an exact known.add action grant.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnownIdentityInput" } } } }, "responses": { "201": { "description": "The identity was added.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnownIdentity" } } } }, "200": { "description": "The identity was already known; it carries the given name.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KnownIdentity" } } } }, "default": { "description": "Application failure; invalid_name for an empty or overlong name, identity_conflict for the same fingerprint under another algorithm.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tas/{ta_id}/known-identities/{identity_id}": { "delete": { "operationId": "removeKnownIdentity", "summary": "Remove a known identity", "description": "Forgets a known identity. Mandates already issued to it are unaffected; revoke them in the policy to withdraw authority.", "x-implementation-phase": 8, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.known.remove", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and known identity must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Known identities are an address book for issuing mandates. Adding or removing one grants, revokes and publishes nothing.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "identity_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for administration sessions; required for login-only subjects using an exact known.remove action grant.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session.", "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "The known identity was removed.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "identity_id": { "type": "string" }, "removed": { "type": "boolean" } }, "required": ["identity_id", "removed"] } } } }, "default": { "description": "Application failure.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/tas/{ta_id}/publications": { "get": { "operationId": "listPublications", "summary": "listPublications", "description": "Publication jobs, newest first by created_at; next_cursor is the last job's ID. See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.ta.read", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationJobList" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] }, "post": { "operationId": "publishDraft", "summary": "publishDraft", "description": "Freeze the requested draft revision in a durable publication job and remove the draft. One job may be pending per TA; competing requests or stale draft bases return 409. Reusing the same Idempotency-Key returns the original job. Publication happens asynchronously.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.ta.publish", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "resources": [ { "kind": "ta_draft", "body_field": "draft_id" } ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationJob" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationRequest" } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Same actor, operation and key reuse one durable job; different payload yields 409.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tas/{ta_id}/audit-events": { "get": { "operationId": "listAuditEvents", "summary": "listAuditEvents", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.audit.read", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuditEventList" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] } }, "/tas/{ta_id}": { "get": { "operationId": "getTA", "summary": "getTA", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.read", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator manages registered tas; the operator cannot be suspended.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TA" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ] }, "patch": { "operationId": "setTAState", "summary": "setTAState", "description": "Suspension retains all data. Resumption uses the same permission. The operator TA cannot be suspended through this route.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.suspend", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator manages registered tas; the operator cannot be suspended.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "tas.suspend authorizes both suspension and resumption of ordinary tas.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TA" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TAState" } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } } ] }, "delete": { "operationId": "deleteTA", "summary": "Delete a suspended Trust Anchor", "description": "Permanently removes a suspended customer TA: its Kubo publishing key, worker and snapshot directories, sessions, operators, known identities, drafts, publications and audit log. Its IPNS name can never publish again. Published states stay pinned. The operator's audit log records the deletion. This cannot be undone.", "x-implementation-phase": 8, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.delete", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "Only a suspended customer TA may be deleted; the operator TA cannot be.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Suspend the TA first. The revision must match its current lifecycle revision.", "The session must belong to the operator ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TADeleted"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TADeletion"}}}}, "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": {"type": "string", "minLength": 1}}, {"name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport.", "schema": {"type": "string", "minLength": 1}} ] } }, "/tas/{ta_id}/auth": { "patch": { "operationId": "setTAAuth", "summary": "Set platform login access for a Trust Anchor", "description": "Customer TA login is disabled by default. This gate affects new login attempts, not existing sessions, verifier routing, or published policy. The operator TA remains enabled.", "x-implementation-phase": 7, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.auth", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "Only fully provisioned customer TAs may change platform login access; the operator TA remains enabled.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the operator ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Updated TA", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TA"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TAAuth"}}}}, "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Required for login-only sessions using a tas.auth action grant.", "schema": {"type": "string", "minLength": 1}}, {"name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport.", "schema": {"type": "string", "minLength": 1}} ] } }, "/tas/{ta_id}/verifier-visibility": { "get": { "operationId": "getVerifierVisibility", "summary": "Read verifier directory visibility", "x-implementation-phase": 7, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.verifier.visibility", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and setting must belong to the target ta.", "context_requirements": ["Reverify the ta session on every read.", "The session must belong to the target ta."], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "parameters": [{"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string"}}], "responses": { "200": {"description": "Current setting", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerifierVisibility"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } }, "patch": { "operationId": "setVerifierVisibility", "summary": "Set verifier directory visibility", "x-implementation-phase": 7, "description": "Only the target Trust Anchor administrator or an exact verifier.visibility action grant can change this setting. Revision conflicts return 409. This changes directory listing, not direct verifier access.", "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.verifier.visibility", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and setting must belong to the target ta.", "context_requirements": ["Reverify the ta session and any action grant.", "The session must belong to the target ta."], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "parameters": [{"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string"}}, {"name": "X-CSRF-Token", "in": "header", "required": false, "schema": {"type": "string"}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "schema": {"type": "string"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerifierVisibility"}}}}, "responses": { "200": {"description": "Updated setting", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/VerifierVisibility"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } } }, "/tas/{ta_id}/scope-schema": { "get": { "operationId": "getScopeSchema", "summary": "getScopeSchema", "description": "See platform API integration guide.", "x-implementation-phase": 5, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.schema.read", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScopeSchema" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tas/{ta_id}/ta": { "get": { "operationId": "getTrustAnchor", "summary": "getTrustAnchor", "description": "Read the selected TA's published Trust Anchor policy. A verified session for that TA may read it; editing and publishing still require administration or action authority.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "session_read": true, "scope_template": ".nomos.web.ta.read", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "When an action mandate is supplied, its subject and algorithm must match the authenticated session.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session for the target ta may read its published Trust Anchor policy. Editing and publishing require administration or exact action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrustAnchor" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tas/{ta_id}/ta/drafts": { "get": { "operationId": "listDrafts", "summary": "List saved policy drafts", "description": "Saved editable drafts in the target TA partition, ordered by opaque draft ID with cursor pagination. Includes drafts whose base is no longer the published head.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.ta.read", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraftList" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } } ] }, "post": { "operationId": "createDraft", "summary": "createDraft", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.ta.edit", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraft" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tas/{ta_id}/ta/drafts/{draft_id}": { "delete": { "operationId": "deleteDraft", "summary": "Delete a saved policy draft", "description": "Deletes only the saved editable draft at the submitted revision. Published policy, publication history and immutable publication snapshots are retained, including queued snapshots. Audited in the authorizing TA and, for inspection, the inspected TA.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.ta.edit", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "resources": [ { "kind": "ta_draft", "parameter": "draft_id" } ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDeleted" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DraftDeletion" } } } } }, "get": { "operationId": "getDraft", "summary": "getDraft", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.ta.read", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "resources": [ { "kind": "ta_draft", "parameter": "draft_id" } ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraft" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ] }, "put": { "operationId": "editDraft", "summary": "editDraft", "description": "Replace policy fields with revision conflict protection. A TA administration session covers all fields; auth-only sessions require ta.edit and the additional per-field action authorities.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.ta.edit", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Without an administration session, every submitted policy field requires its additional mandate, even if unchanged; null is always invalid.", "The session must belong to the authorizing ta." ], "resources": [ { "kind": "ta_draft", "parameter": "draft_id" } ], "additional_scopes_on_fields": { "root_identity_ids": ".nomos.web.operator.add", "whitelist": ".nomos.web.whitelist.edit", "revocations": ".nomos.web.revoke.add" }, "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraft" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TADraftEdit" } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "draft_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tas/{ta_id}/publications/{job_id}": { "get": { "operationId": "getPublication", "summary": "getPublication", "description": "See platform API integration guide.", "x-implementation-phase": 6, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.ta.read", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session and all referenced resources must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "resources": [ { "kind": "publication", "parameter": "job_id" } ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationJob" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "job_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } } ] } }, "/tas/{ta_id}/mandates": { "post": { "operationId": "storeMandate", "summary": "Store a mandate for publication", "description": "Commits a mandate issued under this TA, and every inline envelope of its chain, to the content store and retains them. Accepts a PEM presentation or the CID of a mandate already retrievable. Publishes nothing: list the returned CID in a draft's mandates and publish the draft. To publish a mandate without listing it, from any TA, use publishMandate. The mandate is not verified; the index surfaces mandates without vouching for them.", "x-implementation-phase": 8, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.ta.edit", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session must belong to the target ta, and the mandate must be issued under its TA.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StoredMandate"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MandateInput"}}}}, "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": {"type": "string", "minLength": 1}}, {"name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport.", "schema": {"type": "string", "minLength": 1}} ] } }, "/mandates": { "post": { "operationId": "publishMandate", "summary": "Publish any mandate", "description": "Commits a mandate, whatever TA issued it, and every inline envelope of its chain, to the content store and retains them, so that verifiers can fetch it by CID. Accepts a PEM presentation or the CID of a mandate already retrievable. Any signed-in session may publish: a mandate's bytes are its holder's to publish anywhere, and the session only makes the node's storage accountable. The request is audited under the session's TA. Lists nothing and verifies nothing; expired mandates are accepted.", "x-implementation-phase": 8, "x-authorization": { "mode": "session" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/StoredMandate"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/MandateInput"}}}}, "parameters": [ {"name": "Origin", "in": "header", "required": false, "description": "Required with cookie transport; must exactly equal NOMOS_PLATFORM_PUBLIC_ORIGIN.", "schema": {"type": "string"}}, {"name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport.", "schema": {"type": "string", "minLength": 1}} ] } }, "/tas/{ta_id}/ta/history": { "get": { "operationId": "getTrustAnchorHistory", "summary": "Walk the TA's published history", "description": "Resolves the TA's IPNS name afresh and follows previous-cid back, newest first, as `nomos TA audit` does. Read from the transport, so CLI publications appear too. A walk cut short by the limit, a missing state or the time budget says where it stopped.", "x-implementation-phase": 8, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.ta.read", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "The session must belong to the target ta.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TrustAnchorHistory"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": {"type": "string", "minLength": 1}}, {"name": "limit", "in": "query", "description": "States to walk, newest first.", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}} ] } }, "/tas/{ta_id}/ta/resolution": { "get": { "operationId": "resolveTrustAnchor", "summary": "Resolve a TA to trust", "description": "Resolves an IPNS ID or DNSLink domain to the bare IPNS identifier a whitelist entry stores, and reads that TA's current state, so that an editor can review what a draft would trust before adding it. A domain is only the way there: whitelists hold the identifier, never the domain (§5.5.2). When a domain names a state directly, the identifier is what that state declares, and declared says so. Nothing is cached or retained, and nothing is written to the policy.", "x-implementation-phase": 8, "x-authorization": { "mode": "ta", "scope_template": ".nomos.web.ta.edit", "matching": "exact", "authorizing_ta": "target", "resource_constraint": "Read-only, and reaches no appliance record: the TA is read from the transport.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The appliance fetches whatever the name points to. Each resolution is audited in the authorizing ta's log.", "The session must belong to the authorizing ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TrustAnchorResolution"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "name", "in": "query", "required": true, "description": "An IPNS ID, in any encoding or as /ipns/…, or a DNSLink domain.", "schema": {"type": "string", "minLength": 1, "maxLength": 253}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": {"type": "string", "minLength": 1}} ] } }, "/tas/{ta_id}/inspection/ta": { "get": { "operationId": "inspectTrustAnchor", "summary": "Inspect a TA's published policy", "description": "The operator's read-only view of getTrustAnchor for any registered TA.", "x-implementation-phase": 8, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.inspect", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator reads any registered TA, in any state; inspection reaches no write.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Inspection is read-only. Each read is audited in the operator's log and the inspected TA's, except that reading an audit log does not add to it.", "The session must belong to the operator ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TrustAnchor"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": {"type": "string", "minLength": 1}} ] } }, "/tas/{ta_id}/inspection/operators": { "post": { "operationId": "registerInspectedOperator", "summary": "Inspector: Register an operator", "description": "Operator-authorized operation in the inspected local TA partition. Changes are audited in both TAs. Registers a public key as an operator of this TA, so that a draft can name it as a root. It enrolls and publishes nothing; registering the same key again returns the existing operator.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.policy", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "Resources belong to the inspected local TA; authority belongs to the operator TA.", "context_requirements": [ "Verified operator TA session; administration or the exact declared action grant.", "Target TA must be locally registered." ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Operator" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Enrollment" } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } } ] }, "get": { "operationId": "inspectOperators", "summary": "Inspect a TA's operators", "description": "The operator's read-only view of listOperators for any registered TA.", "x-implementation-phase": 8, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.inspect", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator reads any registered TA, in any state; inspection reaches no write.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Inspection is read-only. Each read is audited in the operator's log and the inspected TA's, except that reading an audit log does not add to it.", "The session must belong to the operator ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OperatorList"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": {"type": "string", "minLength": 1}}, {"name": "cursor", "in": "query", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}} ] } }, "/tas/{ta_id}/inspection/known-identities": { "get": { "operationId": "inspectKnownIdentities", "summary": "Inspect a TA's known identities", "description": "The operator's view of listKnownIdentities for any registered TA, in the same order and paged by the same cursor.", "x-implementation-phase": 8, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.inspect", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator reads any registered TA, in any state; inspection reaches no write.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Inspection is read-only. Each read is audited in the operator's log and the inspected TA's, except that reading an audit log does not add to it.", "The session must belong to the operator ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KnownIdentityList"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": {"type": "string", "minLength": 1}}, {"name": "cursor", "in": "query", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}} ] }, "post": { "operationId": "addInspectedKnownIdentity", "summary": "Add or rename a known identity of an inspected TA", "description": "addKnownIdentity, by the operator, for any registered TA: the key is named in that TA's known identities, for its administrators to issue mandates to.", "x-implementation-phase": 8, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.known.add", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator names keys for any registered TA, in any state; the known identity belongs to that TA.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Known identities are an address book for issuing mandates. Adding or removing one grants, revokes and publishes nothing, which is why it is the one inspection write.", "Each change is audited in the operator's log and the inspected TA's.", "The session must belong to the operator ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for administration sessions; required for login-only subjects using an exact tas.known.add action grant.", "schema": {"type": "string", "minLength": 1}}, {"name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session.", "schema": {"type": "string", "minLength": 1}} ], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KnownIdentityInput"}}}}, "responses": { "201": {"description": "The identity was added.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KnownIdentity"}}}}, "200": {"description": "The identity was already known; it carries the given name.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/KnownIdentity"}}}}, "default": {"description": "Application failure; invalid_name for an empty or overlong name, identity_conflict for the same fingerprint under another algorithm, ta_deleting while the TA is being deleted.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } } }, "/tas/{ta_id}/inspection/known-identities/{identity_id}": { "delete": { "operationId": "removeInspectedKnownIdentity", "summary": "Remove a known identity of an inspected TA", "description": "removeKnownIdentity, by the operator, for any registered TA. Mandates already issued to it are unaffected.", "x-implementation-phase": 8, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.known.remove", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator forgets known identities of any registered TA, in any state.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Known identities are an address book for issuing mandates. Adding or removing one grants, revokes and publishes nothing, which is why it is the one inspection write.", "Each change is audited in the operator's log and the inspected TA's.", "The session must belong to the operator ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "identity_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for administration sessions; required for login-only subjects using an exact tas.known.remove action grant.", "schema": {"type": "string", "minLength": 1}}, {"name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session.", "schema": {"type": "string", "minLength": 1}} ], "responses": { "200": {"description": "The known identity was removed.", "content": {"application/json": {"schema": {"type": "object", "additionalProperties": false, "properties": {"identity_id": {"type": "string"}, "removed": {"type": "boolean"}}, "required": ["identity_id", "removed"]}}}}, "default": {"description": "Application failure; ta_deleting while the TA is being deleted.", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} } } }, "/tas/{ta_id}/inspection/publications": { "post": { "operationId": "publishInspectedDraft", "summary": "Publish an inspected local TA draft", "description": "Operator-authorized publication of a saved draft in the inspected local TA partition. Uses the same immutable snapshot, draft removal, revision, stale-head and idempotency checks as TA administration. Audited in both TAs.", "x-implementation-phase": 6, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.publish", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "Draft belongs to the inspected local TA; authority belongs to the operator TA.", "context_requirements": [ "Verified operator TA session; administration or exact tas.publish grant.", "Target TA is locally registered." ], "resources": [ { "kind": "ta_draft", "body_field": "draft_id" } ], "administration_scope_template": ".nomos.web" }, "security": [ { "sessionBearer": [] }, { "sessionCookie": [] } ], "responses": { "202": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationJob" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicationRequest" } } } }, "parameters": [ { "name": "ta_id", "in": "path", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": { "type": "string", "minLength": 1 } }, { "name": "X-CSRF-Token", "in": "header", "required": false, "description": "Required for cookie transport, bound to the session. Bearer clients do not use ambient cookies.", "schema": { "type": "string", "minLength": 1 } }, { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Same actor, operation and key reuse one durable job; different payload yields 409.", "schema": { "type": "string", "minLength": 1 } } ] }, "get": { "operationId": "inspectPublications", "summary": "Inspect a TA's publication jobs", "description": "The operator's read-only view of listPublications for any registered TA.", "x-implementation-phase": 8, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.inspect", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator reads any registered TA, in any state; inspection reaches no write.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Inspection is read-only. Each read is audited in the operator's log and the inspected TA's, except that reading an audit log does not add to it.", "The session must belong to the operator ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/PublicationJobList"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": {"type": "string", "minLength": 1}}, {"name": "cursor", "in": "query", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}} ] } }, "/tas/{ta_id}/inspection/audit-events": { "get": { "operationId": "inspectAuditEvents", "summary": "Inspect a TA's audit log", "description": "The operator's read-only view of listAuditEvents for any registered TA.", "x-implementation-phase": 8, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.inspect", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator reads any registered TA, in any state; inspection reaches no write.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Inspection is read-only. Each read is audited in the operator's log and the inspected TA's, except that reading an audit log does not add to it.", "The session must belong to the operator ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/AuditEventList"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": {"type": "string", "minLength": 1}}, {"name": "cursor", "in": "query", "schema": {"type": "string"}}, {"name": "limit", "in": "query", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 50}} ] } }, "/tas/{ta_id}/inspection/history": { "get": { "operationId": "inspectHistory", "summary": "Inspect a TA's published history", "description": "The operator's view of getTrustAnchorHistory for any registered TA with a publishing identity.", "x-implementation-phase": 8, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.inspect", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "The operator reads any registered TA, in any state; inspection reaches no write.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "Inspection is read-only. Each read is audited in the operator's log and the inspected TA's, except that reading an audit log does not add to it.", "The session must belong to the operator ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TrustAnchorHistory"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "parameters": [ {"name": "ta_id", "in": "path", "required": true, "schema": {"type": "string", "minLength": 1}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": {"type": "string", "minLength": 1}}, {"name": "limit", "in": "query", "description": "States to walk, newest first.", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}} ] } }, "/inspection/history": { "get": { "operationId": "inspectForeignHistory", "summary": "Inspect any TA's published history", "description": "Walks the published history of a Trust Anchor this appliance need not manage, given exactly one of name or cid, as getTrustAnchorHistory does for a registered TA. From a CID the walk starts at that state, so a superseded state or one whose anchor no longer resolves can be read. A state's declared identifier is what it claims, not something the walk checked.", "x-implementation-phase": 8, "x-authorization": { "mode": "operator", "scope_template": ".nomos.web.tas.inspect", "matching": "exact", "authorizing_ta": "operator", "resource_constraint": "Read-only, and reaches no appliance record: the TA is read from the transport.", "context_requirements": [ "Authenticated subject and algorithm must match action mandate.", "Reverify session authority and any separate action grants against current trust policy for every protected action.", "A verified session of the enrolled administrator of the authorizing ta, or an exact administration-scope session, authorizes management. Other authentication-only subjects require action grants.", "The appliance fetches whatever the name or CID points to. Each walk is audited in the operator's log.", "The session must belong to the operator ta." ], "administration_scope_template": ".nomos.web" }, "security": [{"sessionBearer": []}, {"sessionCookie": []}], "responses": { "200": {"description": "Success", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/TrustAnchorHistory"}}}}, "default": {"description": "Application failure", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}} }, "parameters": [ {"name": "name", "in": "query", "description": "An IPNS ID, in any encoding or as /ipns/…, or a DNSLink domain. The walk starts at its current head.", "schema": {"type": "string", "minLength": 1, "maxLength": 253}}, {"name": "cid", "in": "query", "description": "A TA state CID, or /ipfs/…. The walk starts at that state, current or not.", "schema": {"type": "string", "minLength": 1, "maxLength": 253}}, {"name": "limit", "in": "query", "description": "States to walk, newest first.", "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}}, {"name": "X-Nomoi-Mandate", "in": "header", "required": false, "description": "Optional for enrolled-operator or administration sessions; required for other authentication-only subjects using individual action grants.", "schema": {"type": "string", "minLength": 1}} ] } }, "/login-attempts": { "post": { "operationId": "discoverLogin", "summary": "Start login using the mandate Trust Anchor", "description": "Infer the TA from the presented leaf mandate Trust Anchor, matching only the trusted TA registry. Accepts CID and PEM presentations. Then apply the same TA readiness, verification, scope, enrollment and browser binding checks as TA-specific login.", "x-implementation-phase": 4, "x-authorization": { "mode": "public" }, "security": [], "responses": { "201": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginAttempt" } } }, "headers": { "Set-Cookie": { "description": "Cookie transport only: HttpOnly, SameSite=Strict, Path=/, Secure for HTTPS. Begin sets an attempt-specific binding; completion clears it and rotates the session.", "schema": { "type": "string" } } } }, "default": { "description": "Application failure; verification failures include a tagged outcome. Infrastructure failures never include a NOMOI code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginRequest" } } } }, "parameters": [ { "name": "Origin", "in": "header", "required": false, "description": "Required for cookie login and completion and cookie-authenticated mutations; must exactly equal NOMOS_PLATFORM_PUBLIC_ORIGIN. Forwarded headers are not trusted.", "schema": { "type": "string" } } ] } } }, "components": { "securitySchemes": { "bootstrapBearer": { "type": "http", "scheme": "bearer", "description": "Setup-only credential, permanently disabled after operator NOMOI login." }, "sessionBearer": { "type": "http", "scheme": "bearer" }, "sessionCookie": { "type": "apiKey", "in": "cookie", "name": "__Host-nomos_session", "description": "HTTPS cookie: Secure, HttpOnly, SameSite=Strict, Path=/, no Domain. Cookie mutations require Origin and the session CSRF token." }, "localSessionCookie": { "type": "apiKey", "in": "cookie", "name": "nomos_session", "description": "Loopback HTTP development only. Same protections as the HTTPS cookie except Secure and the __Host- prefix." } }, "schemas": { "DraftDeleted": { "type": "object", "required": [ "draft_id", "deleted" ], "properties": { "draft_id": { "type": "string" }, "deleted": { "type": "boolean" } } }, "DraftDeletion": { "type": "object", "additionalProperties": false, "required": [ "revision" ], "properties": { "revision": { "type": "integer", "minimum": 1 } } }, "TADraftList": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TADraft" } }, "next_cursor": { "type": "string" } } }, "InspectedTADraftEdit": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "root_identity_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "whitelist": { "type": "array", "items": { "$ref": "#/components/schemas/WhitelistEntry" } }, "revocations": { "type": "array", "items": { "$ref": "#/components/schemas/Revocation" } }, "mandates": { "type": [ "array", "null" ], "description": "The inspected TA mandate index. Omitted or null keeps the saved index; listing has no effect on mandate validity.", "items": { "type": "string", "minLength": 1 } }, "action_authorities": { "type": "object", "additionalProperties": false, "properties": { "tas.policy.operator": { "$ref": "#/components/schemas/MandateInput" }, "tas.policy.whitelist": { "$ref": "#/components/schemas/MandateInput" }, "tas.policy.revoke": { "$ref": "#/components/schemas/MandateInput" } } } }, "required": [ "revision", "root_identity_ids", "whitelist", "revocations" ] }, "Outcome": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "outcome": { "const": "accepted" }, "code": { "const": 0 } }, "required": [ "outcome", "code" ] }, { "type": "object", "additionalProperties": false, "properties": { "outcome": { "const": "rejected" }, "code": { "type": "integer", "minimum": 1, "maximum": 4294967295 } }, "required": [ "outcome", "code" ] }, { "type": "object", "additionalProperties": false, "properties": { "outcome": { "const": "inconclusive" } }, "required": [ "outcome" ] } ] }, "Error": { "type": "object", "additionalProperties": false, "properties": { "error": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string" }, "message": { "type": "string" }, "verification": { "$ref": "#/components/schemas/Outcome" } }, "required": [ "kind", "message" ] } }, "required": [ "error" ] }, "Health": { "type": "object", "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "status" ] }, "Readiness": { "type": "object", "additionalProperties": false, "properties": { "api": { "type": "string", "enum": [ "ready" ] }, "metadata": { "type": "string", "enum": [ "ready" ] }, "bootstrap": { "type": "string", "enum": [ "not_implemented", "provisioning", "awaiting_enrollment", "awaiting_nomoi_login", "active" ] }, "ready": { "type": "boolean" }, "kubo": { "type": "string", "enum": [ "ready", "unavailable" ] }, "workers": { "type": "object", "additionalProperties": false, "properties": { "expected": { "type": "integer", "minimum": 0 }, "ready": { "type": "integer", "minimum": 0 }, "unavailable": { "type": "integer", "minimum": 0 } }, "required": [ "expected", "ready", "unavailable" ] }, "publications": { "type": "object", "additionalProperties": false, "properties": { "pending": { "type": "integer", "minimum": 0 }, "retrying": { "type": "integer", "minimum": 0 } }, "required": [ "pending", "retrying" ] } }, "required": [ "api", "metadata", "bootstrap", "ready" ] }, "BootstrapStatus": { "type": "object", "additionalProperties": false, "properties": { "state": { "type": "string", "enum": [ "provisioning", "awaiting_enrollment", "awaiting_nomoi_login", "active" ] }, "operator_ta_id": { "type": "string", "minLength": 1 }, "default_password_enabled": { "type": "boolean" }, "publication": { "$ref": "#/components/schemas/PublicationJob" }, "operator_ipns_id": { "type": "string", "description": "Canonical bare Kubo self IPNS ID; empty before discovery." }, "management_prefix": { "type": "string" }, "auth_scope": { "type": "string" }, "last_error": { "type": "string", "description": "Diagnostic for retryable provisioning or publication failure; never a NOMOI verdict." }, "administration_scope": { "type": "string", "description": "Present a mandate with this exact scope to sign in and administer the operator TA." } }, "required": [ "state", "default_password_enabled", "operator_ta_id", "operator_ipns_id", "management_prefix", "auth_scope", "publication", "administration_scope" ] }, "BootstrapCredentials": { "type": "object", "additionalProperties": false, "properties": { "password": { "type": "string", "minLength": 1, "writeOnly": true } }, "required": [ "password" ] }, "BootstrapSession": { "type": "object", "additionalProperties": false, "properties": { "token": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time" } }, "required": [ "token", "expires_at" ], "description": "Opaque setup bearer credential, valid for 15 minutes and invalidated permanently at first successful operator login." }, "Enrollment": { "type": "object", "additionalProperties": false, "properties": { "public_key": { "type": "string", "contentEncoding": "base64" }, "algorithm": { "type": "string", "minLength": 1 } }, "required": [ "public_key", "algorithm" ] }, "EnrollmentResult": { "type": "object", "additionalProperties": false, "properties": { "operator": { "$ref": "#/components/schemas/Operator" }, "publication": { "$ref": "#/components/schemas/PublicationJob" } }, "required": [ "operator", "publication" ] }, "TA": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "ipns_id": { "type": "string", "description": "Canonical bare Kubo IPNS publishing-key ID; assigned by Kubo, never selected by request." }, "scope_prefix": { "type": "string", "minLength": 1 }, "operator": { "type": "boolean" }, "state": { "type": "string", "enum": [ "provisioning", "ready", "failed", "suspended" ] }, "provisioning_step": { "type": "string" }, "revision": { "type": "integer", "minimum": 1 }, "publication": { "$ref": "#/components/schemas/PublicationJob" }, "last_error": { "type": "string" }, "verifier_public": { "type": "boolean", "description": "Whether the verifier appears in the public dropdown; defaults to false." }, "auth_enabled": { "type": "boolean", "description": "Whether this TA accepts new platform login attempts. Customer TAs default to false; the operator TA remains true." }, "auth_revision": { "type": "integer", "minimum": 1, "description": "Revision of the login gate, independent of the TA lifecycle revision." }, "verifier_ready": { "type": "boolean", "description": "Current verifier probe, present on individual TA reads." } }, "required": [ "id", "scope_prefix", "operator", "state", "provisioning_step", "revision", "verifier_public", "auth_enabled", "auth_revision" ] }, "TACreate": { "type": "object", "additionalProperties": false, "properties": { "scope_prefix": { "type": "string", "minLength": 1 }, "administrator": { "$ref": "#/components/schemas/Enrollment" } }, "required": [ "scope_prefix", "administrator" ], "description": "The designated administrator is enrolled as the initial root signer for scope_prefix. Supply only its public key. Idempotency-Key is scoped to the operator TA, authenticated subject and algorithm, and operation." }, "VerifierVisibility": { "type": "object", "additionalProperties": false, "properties": { "public": {"type": "boolean"}, "revision": {"type": "integer", "minimum": 1} }, "required": ["public", "revision"] }, "TAAuth": { "type": "object", "additionalProperties": false, "properties": { "enabled": {"type": "boolean"}, "revision": {"type": "integer", "minimum": 1, "description": "Current auth_revision from the TA response."} }, "required": ["enabled", "revision"] }, "StoredMandate": { "type": "object", "additionalProperties": false, "properties": { "cid": {"type": "string", "minLength": 1, "description": "The leaf mandate's CID, for a draft's mandates."}, "stored": {"type": "array", "description": "Envelopes committed and retained by this request, leaf first. Links presented by CID reference are not included.", "items": {"type": "string"}} }, "required": ["cid", "stored"] }, "TADeletion": { "type": "object", "additionalProperties": false, "properties": { "revision": {"type": "integer", "minimum": 1, "description": "Current lifecycle revision from the TA response."} }, "required": ["revision"] }, "TADeleted": { "type": "object", "additionalProperties": false, "properties": { "ta_id": {"type": "string", "minLength": 1}, "deleted": {"type": "boolean", "const": true} }, "required": ["ta_id", "deleted"] }, "ScopeBinding": { "type": "object", "additionalProperties": false, "description": "A root identity fingerprint or whitelisted identifier, with its scopes. An empty whitelist entry denies.", "properties": { "id": {"type": "string", "minLength": 1}, "scopes": {"type": "array", "items": {"type": "string"}} }, "required": ["id", "scopes"] }, "TrustAnchorState": { "type": "object", "additionalProperties": false, "properties": { "cid": {"type": "string", "minLength": 1}, "published_at": {"type": "string", "format": "date-time"}, "previous_cid": {"type": "string", "description": "Absent on the genesis state."}, "declared_ipns_id": {"type": "string", "description": "The IPNS identifier the state declares in nomoi/transports. A claim, not checked against how the state was reached."}, "dns": {"type": "string", "description": "The DNSLink domain the state declares, if any."}, "roots": {"type": "array", "items": {"$ref": "#/components/schemas/ScopeBinding"}}, "whitelist": {"type": "array", "items": {"$ref": "#/components/schemas/ScopeBinding"}}, "revoked_identities": {"type": "array", "items": {"type": "string"}}, "revoked_mandates": {"type": "array", "items": {"type": "string"}}, "mandates": {"type": "array", "description": "The state's nomoi/mandates/ discoverability index.", "items": {"type": "string"}}, "error": {"type": "string", "description": "Why this state could not be read. The walk stopped here."} }, "required": ["cid"] }, "TrustAnchorHistory": { "type": "object", "additionalProperties": false, "properties": { "ipns_id": {"type": "string", "minLength": 1, "description": "The identifier the walk resolved. For a walk from a CID, the one its first state declares, when that state could be read."}, "start": {"type": "string", "minLength": 1, "description": "What the walk began from: an IPNS ID, DNSLink domain or state CID."}, "complete": {"type": "boolean", "description": "The walk reached the genesis state."}, "truncated": {"type": "boolean", "description": "The walk stopped at the requested limit."}, "next_cid": {"type": "string", "description": "The walk ran out of time after reading at least one state. Walking from this CID (inspectForeignHistory with cid) continues it."}, "states": {"type": "array", "items": {"$ref": "#/components/schemas/TrustAnchorState"}} }, "required": ["start", "complete", "truncated", "states"] }, "TrustAnchorResolution": { "type": "object", "additionalProperties": false, "properties": { "name": {"type": "string", "minLength": 1, "description": "What was resolved: an IPNS ID in canonical form, or a DNSLink domain."}, "ipns_id": {"type": "string", "minLength": 1, "description": "The bare IPNS identifier to whitelist."}, "declared": {"type": "boolean", "description": "The domain names a state directly, so ipns_id is what that state declares rather than what was resolved."}, "mismatch": {"type": "boolean", "description": "The state declares a different IPNS identifier from the one the name resolved to."}, "state": {"$ref": "#/components/schemas/TrustAnchorState"} }, "required": ["name", "ipns_id", "state"] }, "TAState": { "type": "object", "additionalProperties": false, "properties": { "state": { "type": "string", "enum": [ "suspended", "ready" ] }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "state", "revision" ] }, "Operator": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "ta_id": { "type": "string", "minLength": 1 }, "public_key": { "type": "string", "contentEncoding": "base64" }, "algorithm": { "type": "string", "minLength": 1 }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "id", "ta_id", "public_key", "algorithm", "revision" ] }, "PublicVerification": { "type": "object", "additionalProperties": false, "properties": { "cid": { "type": "string", "description": "The leaf mandate's CID." }, "chain": { "type": "array", "description": "The verified mandates, root first, as the verifier decoded them.", "items": { "type": "object" } }, "verification": { "$ref": "#/components/schemas/Outcome" } }, "required": ["cid", "chain", "verification"] }, "PublicChallenge": { "type": "object", "additionalProperties": false, "properties": { "cid": { "type": "string" }, "chain": { "type": "array", "items": { "type": "object" } }, "verification": { "$ref": "#/components/schemas/Outcome" }, "nonce": { "type": "string", "contentEncoding": "base64" }, "mandate_cid": { "type": "string", "minLength": 1, "description": "The challenged leaf mandate, for nomos sign --mandate-cid." }, "expires_at": { "type": "string", "format": "date-time", "description": "When the verifier stops accepting an answer: its own nonce timeout (60 seconds by default) after issue, bounded by the earliest chain expiry." }, "presentation": { "type": "string", "description": "The challenged leaf as an inline NOMOI presentation PEM, however it was presented. Absent when the verifier did not return the envelope." } }, "required": ["cid", "chain", "verification", "nonce", "mandate_cid", "expires_at"] }, "PublicRejection": { "type": "object", "additionalProperties": false, "description": "A verdict (417): the verifier checked the chain and it is not valid. Do not retry until the chain changes. error carries the combined NOMOI code; problems lists each of its codes.", "properties": { "error": { "$ref": "#/components/schemas/ErrorDetail" }, "cid": { "type": "string", "description": "The leaf mandate's CID, when the verifier could name it." }, "chain": { "type": "array", "description": "What of the chain the verifier decoded, root first. Empty when it stopped before decoding one.", "items": { "type": "object" } }, "problems": { "type": "array", "description": "Every §10.2 code in the verdict, lowest first. Bits the registry does not define are reported together as unregistered.", "items": { "type": "object", "additionalProperties": false, "properties": { "code": { "type": "integer", "minimum": 1 }, "description": { "type": "string" } }, "required": ["code", "description"] } } }, "required": ["error", "chain", "problems"] }, "ChallengeAnswer": { "type": "object", "additionalProperties": false, "properties": { "nonce": { "type": "string", "contentEncoding": "base64" }, "signature": { "type": "string", "contentEncoding": "base64" } }, "required": ["nonce", "signature"] }, "PublicProof": { "type": "object", "additionalProperties": false, "properties": { "verified": { "const": true }, "verification": { "$ref": "#/components/schemas/Outcome" } }, "required": ["verified", "verification"] }, "MandateInput": { "oneOf": [ { "type": "object", "additionalProperties": false, "properties": { "cid": { "type": "string", "minLength": 1 } }, "required": [ "cid" ] }, { "type": "object", "additionalProperties": false, "properties": { "presentation": { "type": "string", "minLength": 1, "description": "PEM presentation containing canonical signed bytes." } }, "required": [ "presentation" ] } ] }, "LoginRequest": { "type": "object", "additionalProperties": false, "properties": { "mandate": { "$ref": "#/components/schemas/MandateInput" }, "transport": { "type": "string", "enum": [ "cookie", "bearer" ], "description": "Cookie binds to this browser and configured Origin. Bearer is an explicit remote API transport; the same verification and session policy apply." } }, "required": [ "mandate", "transport" ] }, "LoginAttempt": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "ta_id": { "type": "string", "minLength": 1 }, "state": { "type": "string", "enum": [ "pending", "completed", "expired", "failed" ] }, "nonce": { "type": "string", "contentEncoding": "base64" }, "mandate_cid": { "type": "string", "minLength": 1 }, "expires_at": { "type": "string", "format": "date-time" }, "binding_token": { "type": "string", "description": "Opaque application correlation secret; required with signature. Never a caller-selected nonce." }, "presentation": { "type": "string", "description": "The challenged leaf mandate as an inline NOMOI presentation PEM, however it was presented. A browser holding the leaf subject key signs the challenge over its envelope after checking that it is mandate_cid. Absent when the verifier did not return the envelope." } }, "required": [ "id", "ta_id", "state", "nonce", "mandate_cid", "expires_at", "binding_token" ], "description": "Pending login expires with the verifier's nonce timeout (60 seconds by default), bounded by the earliest chain expiry. Wrong binding does not claim the attempt; failed or interrupted proof does. Begin a new attempt to retry." }, "LoginResponse": { "type": "object", "additionalProperties": false, "properties": { "signature": { "type": "string", "contentEncoding": "base64" }, "binding_token": { "type": "string", "minLength": 1 } }, "required": [ "signature", "binding_token" ] }, "Session": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "ta_id": { "type": "string", "minLength": 1 }, "ipns_id": { "type": "string", "minLength": 1, "description": "Bare IPNS publishing-key ID of the authenticated TA." }, "scope_prefix": { "type": "string", "minLength": 1, "description": "Trust Anchor scope prefix of the authenticated TA." }, "subject": { "type": "string", "contentEncoding": "base64" }, "subject_algorithm": { "type": "string", "minLength": 1 }, "mandate_cid": { "type": "string", "minLength": 1 }, "expires_at": { "type": "string", "format": "date-time" }, "csrf_token": { "type": "string", "description": "Cookie sessions only. Required as X-CSRF-Token on session mutations." }, "scope": { "type": "string", "description": "Exact scope of the mandate presented at sign-in." }, "administration": { "type": "boolean", "description": "Management authority derived from the verified mandate scope or the enrolled administrator subject and algorithm of that TA. Recomputed on session revalidation." } }, "required": [ "id", "ta_id", "ipns_id", "scope_prefix", "subject", "subject_algorithm", "mandate_cid", "expires_at", "scope", "administration" ] }, "SessionResult": { "type": "object", "additionalProperties": false, "properties": { "session": { "$ref": "#/components/schemas/Session" }, "token": { "type": "string", "description": "Bearer transport only. Store securely; session secrets are hashed in metadata. Expires after at most one hour, bounded by the earliest chain expiry." }, "csrf_token": { "type": "string", "description": "Cookie transport only; the session secret is delivered solely by Set-Cookie." } }, "required": [ "session" ], "oneOf": [ { "required": [ "token" ] }, { "required": [ "csrf_token" ] } ] }, "ScopeOperation": { "type": "object", "additionalProperties": false, "properties": { "operation_id": { "type": "string", "minLength": 1 }, "scope_template": { "type": "string", "minLength": 1 }, "matching": { "type": "string", "enum": [ "exact" ] }, "authorizing_ta": { "type": "string", "enum": [ "operator", "target" ] }, "resource_constraint": { "type": "string" }, "context_requirements": { "type": "array", "items": { "type": "string" } }, "mode": { "type": "string", "enum": [ "public", "operator", "ta" ] }, "method": { "type": "string" }, "path": { "type": "string" }, "additional_scopes_on_fields": { "type": "object", "additionalProperties": { "type": "string" } }, "session_read": { "type": "boolean", "description": "A verified session of the target TA may read this operation without a separate action mandate." }, "resources": { "type": "array", "items": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string" }, "parameter": { "type": "string" }, "body_field": { "type": "string" } }, "required": [ "kind" ] } }, "administration_scope_template": { "type": "string", "const": ".nomos.web" } }, "required": [ "operation_id", "scope_template", "matching", "authorizing_ta", "resource_constraint", "context_requirements", "mode", "method", "path", "administration_scope_template" ] }, "ScopeSchema": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "version": { "type": "integer", "minimum": 1 }, "operations": { "type": "array", "items": { "$ref": "#/components/schemas/ScopeOperation" } } }, "required": [ "id", "version", "operations" ] }, "TrustAnchor": { "type": "object", "additionalProperties": false, "properties": { "ta_id": { "type": "string", "minLength": 1 }, "published_cid": { "type": "string", "minLength": 1 }, "revision": { "type": "integer", "minimum": 1 }, "root_identity_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "whitelist": { "type": "array", "items": { "$ref": "#/components/schemas/WhitelistEntry" } }, "revocations": { "type": "array", "items": { "$ref": "#/components/schemas/Revocation" } }, "mandates": {"type": "array", "description": "The nomoi/mandates/ discoverability index: canonical CIDs of mandates surfaced to auditors and counterparties. It has no effect on validity.", "items": {"type": "string", "minLength": 1}}, "mandate_expiry": { "type": "object", "description": "ExpiresAt of each revoked mandate the server could retrieve, keyed by mandate CID. An absent CID means its expiry is unknown: its revocation can still be removed (§5.3.1), but nothing confirms the mandate has expired.", "additionalProperties": { "type": "string", "format": "date-time" } } }, "required": [ "ta_id", "revision", "root_identity_ids", "whitelist", "revocations", "mandate_expiry" ] }, "WhitelistEntry": { "type": "object", "additionalProperties": false, "properties": { "ipns_id": { "type": "string", "minLength": 1 }, "scope_prefix": { "type": "string", "minLength": 1 } }, "required": [ "ipns_id", "scope_prefix" ] }, "Revocation": { "type": "object", "description": "Revocations are not permanent (§5.3.1). Removing an identity revocation lifts it at any time. Removing a mandate revocation from the published policy fails with revocation_in_force while the server can read the mandate and finds it within its ExpiresAt. A mandate the server cannot retrieve has no known expiry, and its revocation is removed on the administrator's word.", "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "identity", "mandate" ] }, "identifier": { "type": "string", "minLength": 1 } }, "required": [ "kind", "identifier" ] }, "TADraftEdit": { "type": "object", "additionalProperties": false, "properties": { "revision": { "type": "integer", "minimum": 1 }, "root_identity_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "whitelist": { "type": "array", "items": { "$ref": "#/components/schemas/WhitelistEntry" } }, "revocations": { "type": "array", "items": { "$ref": "#/components/schemas/Revocation" } }, "mandates": {"type": ["array", "null"], "description": "The nomoi/mandates/ discoverability index, replaced like the other arrays. Omitted or null keeps the draft's index. Listing needs no grant beyond ta.edit: the index has no effect on validity.", "items": {"type": "string", "minLength": 1}}, "action_authorities": { "type": "object", "additionalProperties": false, "properties": { "operator.add": { "$ref": "#/components/schemas/MandateInput" }, "whitelist.edit": { "$ref": "#/components/schemas/MandateInput" }, "revoke.add": { "$ref": "#/components/schemas/MandateInput" } } } }, "required": [ "revision", "root_identity_ids", "whitelist", "revocations" ] }, "TADraft": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "ta_id": { "type": "string", "minLength": 1 }, "revision": { "type": "integer", "minimum": 1 }, "base_published_cid": { "type": "string", "minLength": 1 }, "root_identity_ids": { "type": "array", "items": { "type": "string", "minLength": 1 } }, "whitelist": { "type": "array", "items": { "$ref": "#/components/schemas/WhitelistEntry" } }, "revocations": { "type": "array", "items": { "$ref": "#/components/schemas/Revocation" } }, "mandates": {"type": "array", "description": "The nomoi/mandates/ discoverability index: canonical CIDs of mandates surfaced to auditors and counterparties. It has no effect on validity.", "items": {"type": "string", "minLength": 1}} }, "required": [ "id", "ta_id", "revision", "root_identity_ids", "whitelist", "revocations" ] }, "PublicationRequest": { "type": "object", "additionalProperties": false, "properties": { "draft_id": { "type": "string", "minLength": 1 }, "revision": { "type": "integer", "minimum": 1 } }, "required": [ "draft_id", "revision" ] }, "PublicationJob": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "created_at": { "type": "string", "format": "date-time", "description": "When the job was accepted. Lists are newest first by it. A job accepted before it was recorded has it only when the audit log named the job, and is listed after every job that has it." }, "ta_id": { "type": "string", "minLength": 1 }, "draft_id": { "type": "string", "minLength": 1 }, "draft_revision": { "type": "integer", "minimum": 1 }, "state": { "type": "string", "enum": [ "queued", "preparing", "publishing", "published", "observed", "failed" ] }, "published_cid": { "type": "string", "minLength": 1 }, "error": { "$ref": "#/components/schemas/ErrorDetail", "description": "Retryable diagnostics; state retains the last completed stage and the job resumes automatically. A suspended TA pauses work." } }, "required": [ "id", "ta_id", "draft_id", "draft_revision", "state" ] }, "ErrorDetail": { "type": "object", "additionalProperties": false, "properties": { "kind": { "type": "string" }, "message": { "type": "string" }, "verification": { "$ref": "#/components/schemas/Outcome" } }, "required": [ "kind", "message" ] }, "AuditEvent": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "ta_id": { "type": "string", "minLength": 1 }, "occurred_at": { "type": "string", "format": "date-time" }, "actor_subject": { "type": "string", "contentEncoding": "base64" }, "actor_algorithm": { "type": "string", "minLength": 1 }, "action": { "type": "string", "minLength": 1 }, "mandate_cid": { "type": "string", "minLength": 1 }, "result": { "type": "string" }, "publication_job_id": { "type": "string", "minLength": 1 }, "published_cid": { "type": "string" }, "resource_id": { "type": "string" }, "local_operator": { "type": "string", "description": "Local OS uid for an offline recovery action." }, "reason": { "type": "string", "maxLength": 512 } }, "required": [ "id", "ta_id", "occurred_at", "action", "result" ] }, "TAList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TA" } }, "next_cursor": { "type": "string" } }, "required": [ "items" ] }, "OperatorList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Operator" } }, "next_cursor": { "type": "string" } }, "required": [ "items" ] }, "KnownIdentity": { "type": "object", "additionalProperties": false, "properties": { "id": { "type": "string", "minLength": 1 }, "ta_id": { "type": "string", "minLength": 1 }, "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "public_key": { "type": "string", "contentEncoding": "base64" }, "algorithm": { "type": "string", "minLength": 1 }, "revision": { "type": "integer", "minimum": 1 } }, "required": ["id", "ta_id", "name", "public_key", "algorithm", "revision"] }, "KnownIdentityInput": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 64 }, "public_key": { "type": "string", "contentEncoding": "base64" }, "algorithm": { "type": "string", "minLength": 1 } }, "required": ["name", "public_key", "algorithm"] }, "KnownIdentityList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/KnownIdentity" } }, "next_cursor": { "type": "string" } }, "required": ["items"] }, "PublicationJobList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/PublicationJob" } }, "next_cursor": { "type": "string" } }, "required": [ "items" ] }, "AuditEventList": { "type": "object", "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AuditEvent" } }, "next_cursor": { "type": "string" } }, "required": [ "items" ] } } }, "x-scope-schema": { "id": "nomos.management", "version": 17 } }