@portpowered/reference-data 0.0.0-stage → 0.4.0

package/generated/public/docs/for-ai/operations/getJWKS.md

@@ -0,0 +1,76 @@
+# getJWKS
+
+GET `/.well-known/jwks.json`
+
+JSON Web Key Set
+
+Returns the JSON Web Key Set (JWKS) containing the public keys used to verify JWT signatures. This endpoint is publicly accessible and does not require authentication. Responses are cached for one hour.
+
+
+## Authorization
+
+```yaml
+path: /.well-known/jwks.json
+runtimePath: /.well-known/jwks.json
+method: GET
+operationId: getJWKS
+security: []
+delegated: false
+resourcePermissionRequired: false
+```
+
+## Complete operation contract
+
+```yaml
+path: /.well-known/jwks.json
+get:
+  operationId: getJWKS
+  tags:
+    - Infrastructure
+  summary: JSON Web Key Set
+  description: >
+    Returns the JSON Web Key Set (JWKS) containing the public keys used to verify JWT signatures.
+    This endpoint is publicly accessible and does not require authentication. Responses are cached
+    for one hour.
+  security: []
+  responses:
+    '200':
+      description: JWKS retrieved successfully
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              keys:
+                type: array
+                items:
+                  type: object
+                  properties:
+                    kty:
+                      type: string
+                      description: Key type
+                      example: RSA
+                    alg:
+                      type: string
+                      description: Algorithm
+                      example: RS256
+                    kid:
+                      type: string
+                      description: Key ID
+                    use:
+                      type: string
+                      description: Public key use
+                      example: sig
+                    'n':
+                      type: string
+                      description: RSA modulus (Base64url encoded)
+                    e:
+                      type: string
+                      description: RSA exponent (Base64url encoded)
+          example:
+            key: value
+  x-portos-delegated: false
+  x-portos-resource-permission: false
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

package/generated/public/docs/for-ai/operations/getMCPOAuthProtectedResourceMetadata.md

@@ -0,0 +1,77 @@
+# getMCPOAuthProtectedResourceMetadata
+
+GET `/.well-known/oauth-protected-resource/mcp`
+
+MCP OAuth protected resource metadata
+
+Returns OAuth 2.0 Protected Resource Metadata for the MCP endpoint as defined by RFC 9728. This endpoint is publicly accessible and does not require authentication. Responses are cached for one hour.
+
+
+## Authorization
+
+```yaml
+path: /.well-known/oauth-protected-resource/mcp
+runtimePath: /.well-known/oauth-protected-resource/mcp
+method: GET
+operationId: getMCPOAuthProtectedResourceMetadata
+security: []
+delegated: false
+resourcePermissionRequired: false
+```
+
+## Complete operation contract
+
+```yaml
+path: /.well-known/oauth-protected-resource/mcp
+get:
+  operationId: getMCPOAuthProtectedResourceMetadata
+  tags:
+    - Infrastructure
+  summary: MCP OAuth protected resource metadata
+  description: >
+    Returns OAuth 2.0 Protected Resource Metadata for the MCP endpoint as defined by RFC 9728. This
+    endpoint is publicly accessible and does not require authentication. Responses are cached for
+    one hour.
+  security: []
+  responses:
+    '200':
+      description: MCP protected resource metadata retrieved successfully
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              resource:
+                type: string
+                description: The protected resource identifier
+                example: https://portpowered.com/mcp
+              authorization_servers:
+                type: array
+                items:
+                  type: string
+                description: Authorization servers that can issue tokens for this resource
+                example:
+                  - https://portpowered.com
+              scopes_supported:
+                type: array
+                items:
+                  type: string
+                description: Scopes supported by this resource
+                example:
+                  - mcp:read
+                  - mcp:write
+                  - mcp:admin
+              bearer_methods_supported:
+                type: array
+                items:
+                  type: string
+                description: Methods supported for presenting bearer tokens
+                example:
+                  - header
+          example:
+            key: value
+  x-portos-delegated: false
+  x-portos-resource-permission: false
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

package/generated/public/docs/for-ai/operations/getMetrics.md

@@ -0,0 +1,47 @@
+# getMetrics
+
+GET `/metrics`
+
+Prometheus metrics
+
+Returns server metrics in Prometheus text exposition format. This endpoint is intentionally unauthenticated so that Prometheus can scrape it.
+
+## Authorization
+
+```yaml
+path: /metrics
+runtimePath: /metrics
+method: GET
+operationId: getMetrics
+security: []
+delegated: false
+resourcePermissionRequired: false
+```
+
+## Complete operation contract
+
+```yaml
+path: /metrics
+get:
+  operationId: getMetrics
+  tags:
+    - Infrastructure
+  summary: Prometheus metrics
+  description: >-
+    Returns server metrics in Prometheus text exposition format. This endpoint is intentionally
+    unauthenticated so that Prometheus can scrape it.
+  security: []
+  responses:
+    '200':
+      description: Prometheus metrics retrieved successfully
+      content:
+        text/plain:
+          schema:
+            type: string
+            description: Prometheus text exposition format metrics
+          example: pong
+  x-portos-delegated: false
+  x-portos-resource-permission: false
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

package/generated/public/docs/for-ai/operations/getOAuthAuthorizationServerMetadata.md

@@ -0,0 +1,90 @@
+# getOAuthAuthorizationServerMetadata
+
+GET `/.well-known/oauth-authorization-server`
+
+Discover OAuth and DCR endpoints
+
+Discover the canonical issuer and endpoints for the deployed environment. Public REST grants use issuer as resource; MCP grants use issuer/mcp. Only allowlisted CIMD identifiers are accepted. Registration is anonymous; device access requires user consent.
+
+## Authorization
+
+```yaml
+path: /.well-known/oauth-authorization-server
+runtimePath: /.well-known/oauth-authorization-server
+method: GET
+operationId: getOAuthAuthorizationServerMetadata
+security: []
+delegated: false
+resourcePermissionRequired: false
+```
+
+## Complete operation contract
+
+```yaml
+path: /.well-known/oauth-authorization-server
+get:
+  operationId: getOAuthAuthorizationServerMetadata
+  tags:
+    - Infrastructure
+  summary: Discover OAuth and DCR endpoints
+  security: []
+  x-portos-delegated: false
+  x-portos-resource-permission: false
+  description: >-
+    Discover the canonical issuer and endpoints for the deployed environment. Public REST grants use
+    issuer as resource; MCP grants use issuer/mcp. Only allowlisted CIMD identifiers are accepted.
+    Registration is anonymous; device access requires user consent.
+  responses:
+    '200':
+      description: Authorization server metadata.
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - issuer
+              - authorization_endpoint
+              - token_endpoint
+              - registration_endpoint
+              - revocation_endpoint
+              - scopes_supported
+            properties:
+              issuer:
+                type: string
+                format: uri
+              authorization_endpoint:
+                type: string
+                format: uri
+              token_endpoint:
+                type: string
+                format: uri
+              registration_endpoint:
+                type: string
+                format: uri
+              revocation_endpoint:
+                type: string
+                format: uri
+              jwks_uri:
+                type: string
+                format: uri
+              scopes_supported:
+                type: array
+                items:
+                  type: string
+              code_challenge_methods_supported:
+                type: array
+                items:
+                  type: string
+                  enum:
+                    - S256
+              token_endpoint_auth_methods_supported:
+                type: array
+                items:
+                  type: string
+              client_id_metadata_document_supported:
+                type: boolean
+              authorization_response_iss_parameter_supported:
+                type: boolean
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

package/generated/public/docs/for-ai/operations/getOAuthClient.md

@@ -0,0 +1,130 @@
+# getOAuthClient
+
+GET `/port1/{principalType}/{principalId}/oauth-clients/{clientId}`
+
+
+
+Retrieves details of a specific OAuth client
+
+Requires a signed user/session or the existing authenticated client flow. The anonymous DCR delegated device profile cannot invoke this operation.
+
+## Authorization
+
+```yaml
+path: /port1/{principalType}/{principalId}/oauth-clients/{clientId}
+runtimePath: /{namespace}/{principalType}/{principalId}/oauth-clients/{clientId}
+method: GET
+operationId: getOAuthClient
+security:
+  - oauth2: []
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: true
+```
+
+## Complete operation contract
+
+```yaml
+path: /port1/{principalType}/{principalId}/oauth-clients/{clientId}
+get:
+  operationId: getOAuthClient
+  tags:
+    - Clients
+  description: >-
+    Retrieves details of a specific OAuth client
+
+
+    Requires a signed user/session or the existing authenticated client flow. The anonymous DCR
+    delegated device profile cannot invoke this operation.
+  parameters:
+    - name: principalType
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The type of principal that owns the OAuth client
+    - name: principalId
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The ID of the principal that owns the OAuth client
+    - name: clientId
+      in: path
+      required: true
+      schema:
+        type: string
+      description: The ID of the OAuth client to retrieve
+    - name: expand
+      in: query
+      description: Expansion tokens that request related or computed fields for the returned resource.
+      required: false
+      schema:
+        type: array
+        items:
+          type: string
+      style: form
+      explode: false
+      examples:
+        include-related:
+          value:
+            - metadata
+  responses:
+    '200':
+      description: OAuth client retrieved successfully
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/OAuthClient'
+    '400':
+      description: Invalid request payload
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Invalid request payload
+            type: BAD_REQUEST
+            family: BAD_REQUEST
+            code: bad-request
+    '401':
+      description: Unauthorized - invalid or missing authentication token
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Unauthorized - invalid or missing authentication token
+            type: UNAUTHORIZED
+            family: AUTHENTICATION
+            code: unauthorized
+    '404':
+      description: OAuth client not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: OAuth client not found
+            type: INVALID_VALUE
+            family: NOT_FOUND
+            code: oauth-client-not-found
+    '500':
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          example:
+            message: Internal server error
+            type: INTERNAL_SERVER_ERROR
+            family: INTERNAL_SERVER_ERROR
+            code: internal-server-error
+  x-portos-delegated: false
+  x-portos-resource-permission: true
+  security:
+    - oauth2: []
+    - bearerAuth: []
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

package/generated/public/docs/for-ai/operations/getOAuthProtectedResourceMetadata.md

@@ -0,0 +1,76 @@
+# getOAuthProtectedResourceMetadata
+
+GET `/.well-known/oauth-protected-resource`
+
+OAuth protected resource metadata
+
+Returns OAuth 2.0 Protected Resource Metadata as defined by RFC 9728. This endpoint is publicly accessible and does not require authentication. Responses are cached for one hour.
+
+
+## Authorization
+
+```yaml
+path: /.well-known/oauth-protected-resource
+runtimePath: /.well-known/oauth-protected-resource
+method: GET
+operationId: getOAuthProtectedResourceMetadata
+security: []
+delegated: false
+resourcePermissionRequired: false
+```
+
+## Complete operation contract
+
+```yaml
+path: /.well-known/oauth-protected-resource
+get:
+  operationId: getOAuthProtectedResourceMetadata
+  tags:
+    - Infrastructure
+  summary: OAuth protected resource metadata
+  description: >
+    Returns OAuth 2.0 Protected Resource Metadata as defined by RFC 9728. This endpoint is publicly
+    accessible and does not require authentication. Responses are cached for one hour.
+  security: []
+  responses:
+    '200':
+      description: Protected resource metadata retrieved successfully
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              resource:
+                type: string
+                description: The protected resource identifier
+                example: https://portpowered.com/mcp
+              authorization_servers:
+                type: array
+                items:
+                  type: string
+                description: Authorization servers that can issue tokens for this resource
+                example:
+                  - https://portpowered.com
+              scopes_supported:
+                type: array
+                items:
+                  type: string
+                description: Scopes supported by this resource
+                example:
+                  - mcp:read
+                  - mcp:write
+                  - mcp:admin
+              bearer_methods_supported:
+                type: array
+                items:
+                  type: string
+                description: Methods supported for presenting bearer tokens
+                example:
+                  - header
+          example:
+            key: value
+  x-portos-delegated: false
+  x-portos-resource-permission: false
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

package/generated/public/docs/for-ai/operations/getOpenIDConfiguration.md

@@ -0,0 +1,89 @@
+# getOpenIDConfiguration
+
+GET `/.well-known/openid-configuration`
+
+OpenID Connect discovery
+
+Returns the OpenID Connect discovery document as defined by the OpenID Connect Discovery 1.0 specification. This endpoint is publicly accessible and does not require authentication.
+
+
+## Authorization
+
+```yaml
+path: /.well-known/openid-configuration
+runtimePath: /.well-known/openid-configuration
+method: GET
+operationId: getOpenIDConfiguration
+security: []
+delegated: false
+resourcePermissionRequired: false
+```
+
+## Complete operation contract
+
+```yaml
+path: /.well-known/openid-configuration
+get:
+  operationId: getOpenIDConfiguration
+  tags:
+    - Infrastructure
+  summary: OpenID Connect discovery
+  description: >
+    Returns the OpenID Connect discovery document as defined by the OpenID Connect Discovery 1.0
+    specification. This endpoint is publicly accessible and does not require authentication.
+  security: []
+  responses:
+    '200':
+      description: OpenID Connect configuration retrieved successfully
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              issuer:
+                type: string
+                description: The issuer identifier
+                example: https://portpowered.com
+              jwks_uri:
+                type: string
+                description: URL of the JSON Web Key Set document
+                example: https://portpowered.com/.well-known/jwks.json
+              token_endpoint:
+                type: string
+                description: URL of the token endpoint
+                example: https://portpowered.com/auth/token
+              response_types_supported:
+                type: array
+                items:
+                  type: string
+                example:
+                  - code
+              subject_types_supported:
+                type: array
+                items:
+                  type: string
+                example:
+                  - public
+              id_token_signing_alg_values_supported:
+                type: array
+                items:
+                  type: string
+                example:
+                  - RS256
+              grant_types_supported:
+                type: array
+                items:
+                  type: string
+                example:
+                  - authorization_code
+                  - client_credentials
+                  - refresh_token
+                  - urn:ietf:params:oauth:grant-type:token-exchange
+                  - urn:ietf:params:oauth:grant-type:device_code
+          example:
+            key: value
+  x-portos-delegated: false
+  x-portos-resource-permission: false
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).

package/generated/public/docs/for-ai/operations/getPendingOAuthConsent.md

@@ -0,0 +1,82 @@
+# getPendingOAuthConsent
+
+GET `/oauth/authorization-request`
+
+Read a pending request for the signed-in consent page
+
+Returns server-stored consent details to the authenticated website. Descriptive
+client metadata is unverified. Agents use the public authorization endpoint and
+wait for the user; a delegated device token cannot read this session-only endpoint.
+
+
+## Authorization
+
+```yaml
+path: /oauth/authorization-request
+runtimePath: /oauth/authorization-request
+method: GET
+operationId: getPendingOAuthConsent
+security:
+  - bearerAuth: []
+delegated: false
+resourcePermissionRequired: false
+```
+
+## Complete operation contract
+
+```yaml
+path: /oauth/authorization-request
+get:
+  operationId: getPendingOAuthConsent
+  tags:
+    - Auth
+  summary: Read a pending request for the signed-in consent page
+  description: |
+    Returns server-stored consent details to the authenticated website. Descriptive
+    client metadata is unverified. Agents use the public authorization endpoint and
+    wait for the user; a delegated device token cannot read this session-only endpoint.
+  security:
+    - bearerAuth: []
+  x-portos-delegated: false
+  x-portos-resource-permission: false
+  parameters:
+    - in: query
+      name: request_id
+      required: true
+      schema:
+        type: string
+  responses:
+    '200':
+      description: Pending consent details. Response is not cacheable.
+      content:
+        application/json:
+          schema:
+            type: object
+            required:
+              - client_id
+              - client_name
+              - redirect_uri
+              - resource
+              - scopes
+            properties:
+              client_id:
+                type: string
+              client_name:
+                type: string
+              redirect_uri:
+                type: string
+                format: uri
+              resource:
+                type: string
+                format: uri
+              scopes:
+                type: array
+                items:
+                  type: string
+    '400':
+      description: Invalid, expired or consumed request.
+    '401':
+      description: User sign-in required.
+```
+
+Resolve component references against [OpenAPI](/docs/references/openapi.yaml). [Auth guide](/docs/for-ai/guides/authentication-and-dcr.md).