@openwop/spec-artifacts 2.35.1 → 2.36.0

package/api/seams-v2.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: OpenWOP conformance seams profile (openwop-conformance-seams-v2)
-  version: 2.35.0
+  version: 2.36.0
   description: 'GENERATED by scripts/derive-v2-api.py. RFC 0168 §C: the seams are a versioned conformance profile with their
     own document and path space (/conformance/seams/…), validated against the canonical v2 schemas with no tolerance path,
     forbidden from the capability namespace (a host advertises the profile, never a testSeams flag). This document carries
@@ -32,6 +32,13 @@ paths:
 
         '
       operationId: getA2ATaskState
+      security:
+      - ApiKeyAuth:
+        - runs:read
+      - OAuth2:
+        - runs:read
+      - OpenIdConnect:
+        - runs:read
       parameters:
       - name: taskId
         in: path
@@ -72,6 +79,13 @@ paths:
 
         '
       operationId: listWorkspaceFiles
+      security:
+      - ApiKeyAuth:
+        - workspace:read
+      - OAuth2:
+        - workspace:read
+      - OpenIdConnect:
+        - workspace:read
       parameters:
       - $ref: '#/components/parameters/WorkspacePrefix'
       responses:
@@ -112,6 +126,13 @@ paths:
 
         '
       operationId: getWorkspaceFile
+      security:
+      - ApiKeyAuth:
+        - workspace:read
+      - OAuth2:
+        - workspace:read
+      - OpenIdConnect:
+        - workspace:read
       parameters:
       - $ref: '#/components/parameters/WorkspacePath'
       - $ref: '#/components/parameters/WorkspaceVersion'
@@ -152,6 +173,13 @@ paths:
 
         '
       operationId: putWorkspaceFile
+      security:
+      - ApiKeyAuth:
+        - workspace:write
+      - OAuth2:
+        - workspace:write
+      - OpenIdConnect:
+        - workspace:write
       parameters:
       - $ref: '#/components/parameters/WorkspacePath'
       - $ref: '#/components/parameters/IfMatch'
@@ -203,6 +231,13 @@ paths:
 
         '
       operationId: deleteWorkspaceFile
+      security:
+      - ApiKeyAuth:
+        - workspace:write
+      - OAuth2:
+        - workspace:write
+      - OpenIdConnect:
+        - workspace:write
       parameters:
       - $ref: '#/components/parameters/WorkspacePath'
       - $ref: '#/components/parameters/IdempotencyKey'
@@ -259,6 +294,13 @@ paths:
 
         '
       operationId: putTestPackTarball
+      security:
+      - ApiKeyAuth:
+        - packs:publish
+      - OAuth2:
+        - packs:publish
+      - OpenIdConnect:
+        - packs:publish
       parameters:
       - in: header
         name: OpenWOP-Pack-Signing-Method
@@ -367,6 +409,13 @@ paths:
         path is registry-service surface (`registry-operations.md`), not defined in this host document (see the `packs-test`
         tag scope note).'
       operationId: getTestPackTarball
+      security:
+      - ApiKeyAuth:
+        - packs:read
+      - OAuth2:
+        - packs:read
+      - OpenIdConnect:
+        - packs:read
       responses:
         '200':
           description: Tarball bytes.
@@ -424,6 +473,13 @@ paths:
 
         '
       operationId: deleteTestPackVersion
+      security:
+      - ApiKeyAuth:
+        - packs:publish
+      - OAuth2:
+        - packs:publish
+      - OpenIdConnect:
+        - packs:publish
       responses:
         '204':
           description: Version successfully unpublished from the test catalog.
@@ -467,6 +523,13 @@ paths:
 
         '
       operationId: getTestPackSignature
+      security:
+      - ApiKeyAuth:
+        - packs:read
+      - OAuth2:
+        - packs:read
+      - OpenIdConnect:
+        - packs:read
       responses:
         '200':
           description: Signature blob.
@@ -733,6 +796,190 @@ paths:
           $ref: '#/components/responses/ValidationError'
         '401':
           $ref: '#/components/responses/Unauthenticated'
+  /conformance/seams/sample/a2ui/emit-surface:
+    post:
+      tags:
+      - Seams
+      operationId: emitA2uiSurface
+      summary: Admit one `ui.a2ui-surface` envelope into a run through the production envelope-admission path — RFC 0209 witness
+      description: 'A real `ui.a2ui-surface` envelope is emitted by a model inside a node turn, so the suite cannot choose
+        one from the canonical wire. This seam supplies the envelope ONLY. The host MUST admit it through its PRODUCTION envelope-admission
+        path — the envelope-kind catalog (`supportedEnvelopes`, `schemaVersions`, `envelopeStrictness`, events.md §"The envelope-kind
+        catalog"), validation against the ONE per-kind branch the schema version selects (never the `anyOf` union), the RFC
+        0209 cross-field rules (every message `surfaceId` equals the payload `surfaceId`; a `createSurface.catalogId` equals
+        the payload `catalogId`), the surface-fold guard (spec/v2/ext/a2uiSurface/README.md §"The fold"), trust propagation
+        and SR-1 redaction — and MUST record it exactly as production would. It MUST NOT be a mock that records without those
+        rules. `envelope.nodeId`, when present, binds the surface to that node, so a surface emitted at a node suspended on
+        an `approval` interrupt is the surface whose `resume` action would resolve it (§"Trust": a tainted fold blocks that
+        interrupt). Refusals use the canonical error envelope: `422 unknown_schema_version` above the floor or under `strict`
+        below it, `422 envelope_invalid` for a payload that fails its branch, a cross-field rule or the fold guard, `422 unknown_envelope_kind`
+        when the host does not list the kind; `details` SHOULD name the rule. A host that has not wired the seam answers `404`/`405`,
+        and the scenario records `inapplicable`.'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+              - runId
+              - envelope
+              properties:
+                runId:
+                  $ref: ../schemas/v2/ids.schema.json#/$defs/runId
+                envelope:
+                  $ref: ../schemas/v2/ai-envelope.schema.json
+                  description: A complete AI envelope whose `type` is `ui.a2ui-surface`; `schemaVersion` selects the payload
+                    branch.
+      responses:
+        '201':
+          description: Admitted and recorded; `sequence` is the run event that records the envelope.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required:
+                - sequence
+                properties:
+                  sequence:
+                    type: integer
+                    minimum: 0
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          description: Refused by envelope admission (`unknown_schema_version`, `envelope_invalid`, `unknown_envelope_kind`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /conformance/seams/sample/oauth/authorize-start:
+    post:
+      tags:
+      - Seams
+      operationId: startOAuthAuthorization
+      summary: Begin an authorization-code grant for the caller through the production authorization-URL builder — RFC 0199
+        §A/§B witness
+      description: 'Points `provider` at the given endpoints (the suite''s authorization-server double) — a test-only provider
+        definition, or, with `connection`, the connection pack''s provider through the host''s PRODUCTION registration path,
+        which runs the RFC 0199 §B.3 discovery and pins its tuple — and then begins an authorization-code grant for the AUTHENTICATED
+        caller by calling the host''s PRODUCTION authorization-URL builder, returning the URL a user agent would be redirected
+        to. The builder MUST be the one production uses (PKCE S256, a fresh `state` bound to the caller''s Subject and the
+        provider, the provider''s fixed redirect URI, `iss` expectations, `resource` for an MCP reach); a seam that assembles
+        its own URL measures a stub, and a bundle citing it MUST say which. The grant completes on the host''s PRODUCTION
+        callback route, which the suite calls as the user agent. `redirectUri` is a probe: the host MUST ignore it (the redirect
+        URI is fixed per provider, oauth.md rule 5). A refused grant — an MCP-reach provider with no `issuer`, `pkce: "unsupported"`,
+        or discovered metadata that disagrees with the manifest or the pinned tuple — is `422 connection_auth_metadata_mismatch`
+        and no authorization URL is issued. A host that has not wired the seam answers `404`, and the scenarios record `blocked`.'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+              - provider
+              properties:
+                provider:
+                  type: string
+                  minLength: 1
+                  description: An advertised `oauth.providers[].id`, or the `provider.id` of `connection`.
+                authUrl:
+                  type: string
+                  format: uri
+                tokenUrl:
+                  type: string
+                  format: uri
+                issuer:
+                  type: string
+                  format: uri
+                  description: The provider's issuer identifier; absent ⇒ an issuer-less provider (provider-unique redirect
+                    URI).
+                pkce:
+                  type: string
+                  enum:
+                  - S256
+                  - unsupported
+                scopes:
+                  type: array
+                  items:
+                    type: string
+                    minLength: 1
+                connection:
+                  $ref: ../schemas/v2/connection-pack-manifest.schema.json
+                  description: A connection pack whose provider is reached as an MCP server (RFC 0199 §B); registered through
+                    the production path.
+                redirectUri:
+                  type: string
+                  description: A probe the host MUST ignore.
+      responses:
+        '201':
+          description: The authorization URL the user agent would be sent to.
+          content:
+            application/json:
+              schema:
+                type: object
+                additionalProperties: false
+                required:
+                - authorizationUrl
+                properties:
+                  authorizationUrl:
+                    type: string
+                    format: uri
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '422':
+          description: The grant is refused (`connection_auth_metadata_mismatch`, `oauth_provider_unsupported`); no authorization
+            URL is issued.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /conformance/seams/sample/oauth/expire-refresh:
+    post:
+      tags:
+      - Seams
+      operationId: expireOAuthAccessToken
+      summary: Expire the caller's stored access token for a provider so its next use refreshes — RFC 0199 §C.2(b) / RFC 0047
+        §C.3 witness
+      description: 'Marks the access token of the caller''s stored credential for `provider` expired. Nothing else: the next
+        node that uses it refreshes through the host''s PRODUCTION refresh path against the provider''s token endpoint (the
+        suite''s double, which decides whether the refresh token is still good). A terminal refresh failure then follows oauth.md
+        §Token lifecycle — `connector.auth-expired`, and either the node fails `connector_auth_expired` or, under `oauth.credentialInterrupt`,
+        it suspends on a `credential` interrupt with `reason: "expired"`. `404` when the caller holds no credential for the
+        provider.'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+              - provider
+              properties:
+                provider:
+                  type: string
+                  minLength: 1
+      responses:
+        '204':
+          description: The access token is expired.
+        '400':
+          $ref: '#/components/responses/ValidationError'
+        '401':
+          $ref: '#/components/responses/Unauthenticated'
+        '404':
+          $ref: '#/components/responses/NotFound'
 components:
   securitySchemes:
     ApiKeyAuth:
@@ -749,6 +996,88 @@ components:
 
         See `auth.md`.
 
+        '
+    OAuth2:
+      type: oauth2
+      description: 'RFC 0200 §F. OAuth 2.0 lanes — v1 `openwop-auth-oauth2-client-credentials`,
+
+        v2 `auth.lanes[].lane: "oauth2"`. Discovery is RFC 9728 Protected Resource
+
+        Metadata at the path-inserted well-known URI (`identity.md` §2.5).
+
+        Placeholder URLs.
+
+        '
+      flows:
+        clientCredentials:
+          tokenUrl: https://issuer.example/oauth2/token
+          scopes:
+            manifest:read: Read workflow / canvas-type / endpoint manifests
+            runs:create: Create new runs
+            runs:read: Read run state and event stream
+            runs:cancel: Cancel an in-flight run
+            runs:annotate: Record a quality annotation on a run
+            artifacts:read: Read artifacts produced by runs
+            webhooks:manage: Register/unregister webhook subscriptions
+            approvals:respond: Respond to HITL approval gates
+            packs:publish: Publish node-pack versions
+            packs:read: Fetch a published node-pack tarball or signature
+            packs:yank: Yank a node-pack version
+            packs:yank-revert: Reinstate a yanked node-pack version
+            audit:read: Verify audit-log integrity
+            workspace:read: Read agent-workspace files
+            workspace:write: Write agent-workspace files
+            prompts:read: Read and render prompt templates
+            prompts:write: Create, update and delete prompt templates
+            content:read: Read authored content pages and locale settings
+            content:write: Create, publish and translate authored content pages
+            deploy:*: Drive an agent deployment state transition
+        authorizationCode:
+          authorizationUrl: https://issuer.example/oauth2/authorize
+          tokenUrl: https://issuer.example/oauth2/token
+          scopes:
+            manifest:read: Read workflow / canvas-type / endpoint manifests
+            runs:create: Create new runs
+            runs:read: Read run state and event stream
+            runs:cancel: Cancel an in-flight run
+            runs:annotate: Record a quality annotation on a run
+            artifacts:read: Read artifacts produced by runs
+            webhooks:manage: Register/unregister webhook subscriptions
+            approvals:respond: Respond to HITL approval gates
+            packs:publish: Publish node-pack versions
+            packs:read: Fetch a published node-pack tarball or signature
+            packs:yank: Yank a node-pack version
+            packs:yank-revert: Reinstate a yanked node-pack version
+            audit:read: Verify audit-log integrity
+            workspace:read: Read agent-workspace files
+            workspace:write: Write agent-workspace files
+            prompts:read: Read and render prompt templates
+            prompts:write: Create, update and delete prompt templates
+            content:read: Read authored content pages and locale settings
+            content:write: Create, publish and translate authored content pages
+            deploy:*: Drive an agent deployment state transition
+    OpenIdConnect:
+      type: openIdConnect
+      openIdConnectUrl: https://issuer.example/.well-known/openid-configuration
+      description: 'RFC 0200 §F. v1 `openwop-auth-oidc-user-bearer` / v2 `auth.lanes[].lane: "oidc"`.
+
+        An ID token MAY be the bearer only when its `aud` equals the host''s configured
+
+        audience (`identity.md` §2.1); any other `aud` is `audience_mismatch`.
+
+        Placeholder URL.
+
+        '
+    MutualTLS:
+      type: mutualTLS
+      description: 'RFC 0200 §F. v1 `openwop-auth-mtls` / v2 `auth.lanes[].lane: "mtls"`. In OpenWOP
+
+        mTLS is required *in addition to* a bearer, never instead of one, so it appears
+
+        in no canonical requirement below: a host that requires it adds `MutualTLS: []`
+
+        inside each requirement object (AND).
+
         '
   parameters:
     IdempotencyKey:
@@ -833,12 +1162,24 @@ components:
   responses:
     Unauthenticated:
       description: Missing or invalid credential.
+      headers:
+        WWW-Authenticate:
+          description: RFC 0200 §B — `Bearer` challenge; `resource_metadata` and `error="invalid_token"` on a host with an
+            oauth2/oidc lane. Never on a non-disclosure 404.
+          schema:
+            type: string
       content:
         application/json:
           schema:
             $ref: '#/components/schemas/Error'
     Forbidden:
       description: Credential valid but lacks required scope or fails resource binding.
+      headers:
+        WWW-Authenticate:
+          description: RFC 0200 §B — `error="insufficient_scope"` with every required `scope` on a scope refusal; absent on
+            a resource-binding 403.
+          schema:
+            type: string
       content:
         application/json:
           schema:

package/api/v2/asyncapi.yaml

@@ -1,7 +1,7 @@
 asyncapi: 3.1.0
 info:
   title: OpenWOP v2 event streams
-  version: 2.35.0
+  version: 2.36.0
   description: GENERATED by scripts/derive-v2-api.py (RFC 0171 §E.1, RFC 0172 §C.2). One run-events channel whose address
     is the OpenAPI path key; the server pathname is empty (bare origin). streamMode is a pattern over the closed set and its
     comma-separated combinations (`values` never combines). hostEvents has a real address (RFC 0171 §E.1) — the documented