stella-ops.org/git.stella-ops.org
1
0
Fork 0
Code Issues Pull Requests Actions 16 Releases Wiki Activity

up
Some checks failed
api-governance / spectral-lint (push) Has been cancelled
Details
Docs CI / lint-and-preview (push) Has been cancelled
Details
oas-ci / oas-validate (push) Has been cancelled
Details
SDK Publish & Sign / sdk-publish (push) Has been cancelled
Details
Policy Lint & Smoke / policy-lint (push) Has been cancelled
Details
Policy Simulation / policy-simulate (push) Has been cancelled
Details
devportal-offline / build-offline (push) Has been cancelled
Details

Browse Source
This commit is contained in:
StellaOps Bot
2025-11-26 20:23:28 +02:00
parent 4831c7fcb0
commit d63af51f84
139 changed files with 8010 additions and 2795 deletions
Download Patch File Download Diff File Expand all files Collapse all files

18
src/Api/StellaOps.Api.OpenApi/_shared/responses/defaults.yaml
View File

@@ -4,10 +4,24 @@ responses:
content:
application/json:
schema:
$ref: '../schemas/common.yaml#/schemas/ErrorEnvelope'
type: object
required: [code, message]
properties:
code:
type: string
message:
type: string
traceId:
type: string
HealthResponse:
description: Health envelope
content:
application/json:
schema:
$ref: '../schemas/common.yaml#/schemas/HealthEnvelope'
type: object
required: [status, service]
properties:
status:
type: string
service:
type: string

143
src/Api/StellaOps.Api.OpenApi/authority/openapi.yaml
View File

@@ -1,21 +1,26 @@
openapi: 3.1.0
info:
title: StellaOps Authority Authentication API
summary: Token issuance, introspection, revocation, and key discovery endpoints exposed by the Authority service.
description: |
The Authority service issues OAuth 2.1 access tokens for StellaOps components, enforcing tenant and scope
restrictions configured per client. This specification describes the authentication surface only; domain APIs
are documented by their owning services.
version: 0.1.0
info:
title: StellaOps Authority Authentication API
summary: Token issuance, introspection, revocation, and key discovery endpoints exposed by the Authority service.
description: |
The Authority service issues OAuth 2.1 access tokens for StellaOps components, enforcing tenant and scope
restrictions configured per client. This specification describes the authentication surface only; domain APIs
are documented by their owning services.
version: 0.1.1
contact:
name: StellaOps API Guild
email: api@stella-ops.local
jsonSchemaDialect: https://json-schema.org/draft/2020-12/schema
servers:
- url: https://authority.stellaops.local
description: Example Authority deployment
tags:
- name: Authentication
description: OAuth 2.1 token exchange, introspection, and revocation flows.
- name: Keys
description: JSON Web Key Set discovery.
tags:
- name: Authentication
description: OAuth 2.1 token exchange, introspection, and revocation flows.
- name: Keys
description: JSON Web Key Set discovery.
- name: Meta
description: Service metadata
components:
securitySchemes:
ClientSecretBasic:
@@ -442,11 +447,11 @@ components:
$ref: '#/components/schemas/Jwk'
required:
- keys
Jwk:
type: object
description: Public key material for token signature validation.
properties:
kid:
Jwk:
type: object
description: Public key material for token signature validation.
properties:
kid:
type: string
description: Key identifier.
kty:
@@ -467,19 +472,44 @@ components:
y:
type: string
description: Y coordinate for EC keys.
status:
type: string
description: Operational status metadata for the key (e.g., `active`, `retiring`).
status:
type: string
description: Operational status metadata for the key (e.g., `active`, `retiring`).
AuthorizationCodeGrantRequest:
type: object
description: Form-encoded payload for authorization code exchange.
required:
- grant_type
- code
- redirect_uri
- code_verifier
properties:
grant_type:
type: string
const: authorization_code
client_id:
type: string
client_secret:
type: string
description: Optional when HTTP Basic auth is used.
code:
type: string
redirect_uri:
type: string
format: uri
code_verifier:
type: string
paths:
/token:
post:
tags:
- Authentication
summary: Exchange credentials for tokens
description: |
Issues OAuth 2.1 bearer tokens for StellaOps clients. Supports password, client credentials,
authorization-code, device, and refresh token grants. Confidential clients must authenticate using
HTTP Basic auth or `client_secret` form fields.
/token:
post:
tags:
- Authentication
summary: Exchange credentials for tokens
description: |
Issues OAuth 2.1 bearer tokens for StellaOps clients. Supports password, client credentials,
authorization-code, device, and refresh token grants. Confidential clients must authenticate using
HTTP Basic auth or `client_secret` form fields.
operationId: authorityTokenExchange
security:
- ClientSecretBasic: []
- {}
@@ -487,11 +517,12 @@ paths:
required: true
content:
application/x-www-form-urlencoded:
schema:
oneOf:
- $ref: '#/components/schemas/PasswordGrantRequest'
- $ref: '#/components/schemas/ClientCredentialsGrantRequest'
- $ref: '#/components/schemas/RefreshTokenGrantRequest'
schema:
oneOf:
- $ref: '#/components/schemas/PasswordGrantRequest'
- $ref: '#/components/schemas/ClientCredentialsGrantRequest'
- $ref: '#/components/schemas/RefreshTokenGrantRequest'
- $ref: '#/components/schemas/AuthorizationCodeGrantRequest'
encoding:
authority_provider:
style: form
@@ -591,13 +622,15 @@ paths:
value:
error: invalid_client
error_description: Client authentication failed.
/revoke:
post:
tags:
- Authentication
summary: Revoke an access or refresh token
security:
- ClientSecretBasic: []
/revoke:
post:
tags:
- Authentication
summary: Revoke an access or refresh token
description: Revokes an access or refresh token; idempotent.
operationId: authorityRevokeToken
security:
- ClientSecretBasic: []
requestBody:
required: true
content:
@@ -637,12 +670,13 @@ paths:
value:
error: invalid_client
error_description: Client authentication failed.
/introspect:
post:
tags:
- Authentication
summary: Introspect token state
description: Returns the active status and claims for a given token. Requires a privileged client.
/introspect:
post:
tags:
- Authentication
summary: Introspect token state
description: Returns the active status and claims for a given token. Requires a privileged client.
operationId: authorityIntrospectToken
security:
- ClientSecretBasic: []
requestBody:
@@ -712,12 +746,13 @@ paths:
value:
error: invalid_client
error_description: Client authentication failed.
/jwks:
get:
tags:
- Keys
summary: Retrieve signing keys
description: Returns the JSON Web Key Set used to validate Authority-issued tokens.
/jwks:
get:
tags:
- Keys
summary: Retrieve signing keys
description: Returns the JSON Web Key Set used to validate Authority-issued tokens.
operationId: authorityGetJwks
responses:
'200':
description: JWKS document.

2517
src/Api/StellaOps.Api.OpenApi/baselines/stella-baseline.yaml
View File

File diff suppressed because it is too large Load Diff

45
src/Api/StellaOps.Api.OpenApi/compose.mjs
View File

@@ -38,8 +38,24 @@ function mergeSpecs(services) {
title: 'StellaOps Aggregate API',
version: '0.0.1',
description: 'Composed OpenAPI from per-service specs. This file is generated by compose.mjs.',
contact: {
name: 'StellaOps API Guild',
email: 'api@stella-ops.local',
},
},
servers: [],
tags: [
{ name: 'Authentication', description: 'OAuth 2.1 token exchange, introspection, and revocation flows.' },
{ name: 'Keys', description: 'JSON Web Key Set discovery.' },
{ name: 'Health', description: 'Liveness endpoints' },
{ name: 'Meta', description: 'Readiness/metadata endpoints' },
{ name: 'Bundles', description: 'Export bundle access' },
{ name: 'Graphs', description: 'Graph build status and traversal APIs' },
{ name: 'Jobs', description: 'Job submission and status APIs' },
{ name: 'Evaluation', description: 'Policy evaluation APIs' },
{ name: 'Policies', description: 'Policy management APIs' },
{ name: 'Queues', description: 'Queue metrics APIs' },
],
paths: {},
components: { schemas: {}, parameters: {}, securitySchemes: {}, responses: {} },
};
@@ -58,6 +74,15 @@ function mergeSpecs(services) {
}
}
// tags
if (Array.isArray(doc.tags)) {
for (const tag of doc.tags) {
if (!aggregate.tags.some((t) => t.name === tag.name)) {
aggregate.tags.push(tag);
}
}
}
// paths
for (const [p, pathItem] of Object.entries(doc.paths || {})) {
const namespacedPath = normalizePath(`/${name}${p}`);
@@ -83,6 +108,14 @@ function mergeSpecs(services) {
}
aggregate.components.schemas[key] = rewriteRefs(schemaDef, name);
}
// security schemes (non-namespaced)
const securitySchemes = doc.components?.securitySchemes || {};
for (const [schemeName, schemeDef] of Object.entries(securitySchemes)) {
if (!aggregate.components.securitySchemes[schemeName]) {
aggregate.components.securitySchemes[schemeName] = schemeDef;
}
}
}
// de-duplicate servers
@@ -127,7 +160,7 @@ function sortPathItem(pathItem) {
}
function writeAggregate(doc) {
const str = yaml.stringify(doc, { sortMapEntries: true });
const str = yaml.stringify(doc, { sortMapEntries: false });
fs.writeFileSync(OUTPUT, str, 'utf8');
console.log(`[stella-compose] wrote aggregate spec to ${OUTPUT}`);
}
@@ -161,6 +194,16 @@ function normalizeRef(refValue, serviceName) {
return `#/components/schemas/${name}`;
}
if (refValue.startsWith('../_shared/responses/')) {
const name = refValue.split('#/responses/')[1];
return `#/components/responses/${name}`;
}
if (refValue.startsWith('../_shared/parameters/')) {
const name = refValue.split('#/parameters/')[1];
return `#/components/parameters/${name}`;
}
const prefix = '#/components/schemas/';
if (refValue.startsWith(prefix)) {
const name = refValue.slice(prefix.length);

61
src/Api/StellaOps.Api.OpenApi/export-center/openapi.yaml
View File

@@ -1,9 +1,18 @@
openapi: 3.1.0
info:
title: StellaOps Export Center API (stub)
version: 0.0.1
description: Health and metadata scaffold for Export Center; replace with real contracts
as authored.
version: 0.0.2
description: Health and metadata scaffold for Export Center; bundle list/manifest examples added.
contact:
name: StellaOps API Guild
email: api@stella-ops.local
tags:
- name: Health
description: Liveness endpoints
- name: Meta
description: Readiness/metadata endpoints
- name: Bundles
description: Export bundle access
servers:
- url: https://export.stellaops.local
description: Example Export Center endpoint
@@ -13,6 +22,8 @@ paths:
tags:
- Health
summary: Liveness probe
description: Returns OK when Export Center is reachable.
operationId: exportHealth
responses:
'200':
description: Service is up
@@ -40,6 +51,8 @@ paths:
summary: Service health
tags:
- Meta
description: Readiness probe for Export Center dependencies.
operationId: exportHealthz
responses:
'200':
description: Service healthy
@@ -58,19 +71,21 @@ paths:
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
$ref: '../_shared/schemas/common.yaml#/schemas/ErrorEnvelope'
examples:
unavailable:
summary: Unhealthy response
value:
code: service_unavailable
message: mirror bundle backlog exceeds SLA
traceId: 3
traceId: "3"
/bundles/{bundleId}:
get:
tags:
- Bundles
summary: Download export bundle by id
operationId: exportGetBundle
description: Streams an export bundle archive.
parameters:
- name: bundleId
in: path
@@ -78,6 +93,9 @@ paths:
schema:
type: string
example: bundle-2025-11-18-001
security:
- OAuthClientCredentials: []
- BearerAuth: []
responses:
'200':
description: Bundle stream
@@ -87,12 +105,15 @@ paths:
download:
summary: Zip payload
value: binary data
checksumMismatch:
summary: Expected sha256 mismatch example
value: binary data
'404':
description: Bundle not found
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
$ref: '../_shared/schemas/common.yaml#/schemas/ErrorEnvelope'
examples:
notFound:
summary: Bundle missing
@@ -105,10 +126,15 @@ paths:
tags:
- Bundles
summary: List export bundles
operationId: exportListBundles
description: Returns paginated export bundles for the tenant.
parameters:
- $ref: '../_shared/parameters/tenant.yaml#/parameters/TenantParam'
- $ref: '../_shared/parameters/paging.yaml#/parameters/LimitParam'
- $ref: '../_shared/parameters/paging.yaml#/parameters/CursorParam'
security:
- OAuthClientCredentials: []
- BearerAuth: []
responses:
'200':
description: Bundle page
@@ -132,10 +158,12 @@ paths:
createdAt: '2025-11-18T12:00:00Z'
status: ready
sizeBytes: 1048576
sha256: sha256:abc123
- bundleId: bundle-2025-11-18-000
createdAt: '2025-11-18T10:00:00Z'
status: ready
sizeBytes: 2048
sha256: sha256:def456
metadata:
hasMore: true
nextCursor: eyJyIjoiMjAyNS0xMS0xOC0wMDIifQ
@@ -157,12 +185,17 @@ paths:
tags:
- Bundles
summary: Fetch bundle manifest metadata
description: Returns manifest metadata for a bundle id.
operationId: exportGetBundleManifest
parameters:
- name: bundleId
in: path
required: true
schema:
type: string
security:
- OAuthClientCredentials: []
- BearerAuth: []
responses:
'200':
description: Manifest metadata
@@ -179,6 +212,8 @@ paths:
digest: sha256:abc123
- type: vex
digest: sha256:def456
sizeBytes: 1048576
sha256: sha256:fedcba
createdAt: '2025-11-18T12:00:00Z'
'404':
description: Bundle not found
@@ -187,6 +222,18 @@ paths:
schema:
$ref: '../_shared/schemas/common.yaml#/schemas/ErrorEnvelope'
components:
securitySchemes:
OAuthClientCredentials:
type: oauth2
description: OAuth 2.1 client credentials flow scoped per service.
flows:
clientCredentials:
tokenUrl: /token
scopes: {}
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
BundleSummary:
type: object
@@ -233,5 +280,3 @@ components:
format: date-time
HealthResponse:
$ref: ../_shared/schemas/common.yaml#/schemas/HealthEnvelope
Error:
$ref: ../_shared/schemas/common.yaml#/schemas/ErrorEnvelope

61
src/Api/StellaOps.Api.OpenApi/graph/openapi.yaml
View File

@@ -1,9 +1,16 @@
openapi: 3.1.0
info:
title: StellaOps Graph API (stub)
version: 0.0.1
description: Health and dataset status scaffold for Graph service; replace with
full contract as authored.
version: 0.0.2
description: Health and dataset status scaffold for Graph service; added status/nodes examples with tenant context.
contact:
name: StellaOps API Guild
email: api@stella-ops.local
tags:
- name: Meta
description: Service health
- name: Graphs
description: Graph build status and traversal APIs
servers:
- url: https://graph.stellaops.local
description: Example Graph endpoint
@@ -13,6 +20,8 @@ paths:
summary: Service health
tags:
- Meta
description: Readiness probe for Graph API.
operationId: graphHealthz
responses:
'200':
description: Service healthy
@@ -38,12 +47,14 @@ paths:
value:
code: service_unavailable
message: indexer lag exceeds threshold
traceId: 5
traceId: "5"
/graphs/{graphId}/status:
get:
summary: Get graph build status
tags:
- Graphs
operationId: graphGetStatus
description: Returns build status for a graph id.
parameters:
- name: graphId
in: path
@@ -63,7 +74,14 @@ paths:
value:
graphId: graph-01JF0XYZ
status: ready
builtAt: 2025-11-18 12:00:00+00:00
builtAt: 2025-11-18T12:00:00Z
tenant: tenant-alpha
building:
value:
graphId: graph-01JF0BUILD
status: building
builtAt: 2025-11-18T12:05:00Z
tenant: tenant-alpha
'404':
description: Graph not found
content:
@@ -75,6 +93,8 @@ paths:
summary: List graph nodes
tags:
- Graphs
operationId: graphListNodes
description: Lists nodes for a graph with paging.
parameters:
- name: graphId
in: path
@@ -97,12 +117,25 @@ paths:
- id: node-1
kind: artifact
label: registry.stella-ops.local/runtime/api
tenant: tenant-alpha
- id: node-2
kind: policy
label: policy:baseline
tenant: tenant-alpha
metadata:
hasMore: true
nextCursor: eyJuIjoiMjAyNS0xMS0xOCJ9
filtered:
summary: Policy nodes only
value:
nodes:
- id: node-99
kind: policy
label: policy:runtime-allowlist
tenant: tenant-beta
metadata:
hasMore: false
nextCursor: ""
'404':
description: Graph not found
content:
@@ -111,6 +144,24 @@ paths:
$ref: ../_shared/schemas/common.yaml#/schemas/ErrorEnvelope
components:
schemas:
HealthEnvelope:
type: object
properties:
status:
type: string
service:
type: string
required: [status, service]
ErrorEnvelope:
type: object
properties:
code:
type: string
message:
type: string
traceId:
type: string
required: [code, message]
GraphStatus:
type: object
required:

118
src/Api/StellaOps.Api.OpenApi/orchestrator/openapi.yaml
View File

@@ -1,9 +1,19 @@
openapi: 3.1.0
info:
title: StellaOps Orchestrator API (stub)
version: 0.0.1
version: 0.0.2
description: Health and job orchestration scaffold for Orchestrator service; replace
with real contracts as contracts are authored.
contact:
name: StellaOps API Guild
email: api@stella-ops.local
tags:
- name: Health
description: Liveness endpoints
- name: Meta
description: Readiness/metadata endpoints
- name: Jobs
description: Job submission and status APIs
servers:
- url: https://orchestrator.stellaops.local
description: Example Orchestrator endpoint
@@ -13,6 +23,8 @@ paths:
tags:
- Health
summary: Liveness probe
description: Returns OK when Orchestrator is reachable.
operationId: orchestratorHealth
responses:
'200':
description: Service is up
@@ -40,6 +52,8 @@ paths:
summary: Service health
tags:
- Meta
description: Readiness probe for orchestrator dependencies.
operationId: orchestratorHealthz
responses:
'200':
description: Service healthy
@@ -65,12 +79,22 @@ paths:
value:
code: service_unavailable
message: outbound queue lag exceeds threshold
traceId: 1
traceId: "1"
/jobs:
post:
tags:
- Jobs
summary: Submit a job to the orchestrator queue
operationId: orchestratorSubmitJob
description: Enqueue a job for asynchronous execution.
parameters:
- in: header
name: Idempotency-Key
description: Optional idempotency key to safely retry job submissions.
required: false
schema:
type: string
maxLength: 128
requestBody:
required: true
content:
@@ -122,6 +146,8 @@ paths:
tags:
- Jobs
summary: List jobs
operationId: orchestratorListJobs
description: Returns jobs for the tenant with optional status filter.
parameters:
- in: query
name: status
@@ -132,6 +158,7 @@ paths:
- running
- failed
- completed
description: Optional status filter
- $ref: ../_shared/parameters/paging.yaml#/parameters/LimitParam
- $ref: ../_shared/parameters/tenant.yaml#/parameters/TenantParam
responses:
@@ -144,22 +171,53 @@ paths:
items:
$ref: '#/components/schemas/JobSummary'
examples:
sample:
default:
summary: Mixed queues
value:
- jobId: job_01JF04ABCD
status: queued
queue: scan
tenant: tenant-alpha
enqueuedAt: '2025-11-18T12:00:00Z'
- jobId: job_01JF04EFGH
status: running
queue: policy-eval
tenant: tenant-alpha
enqueuedAt: '2025-11-18T11:55:00Z'
startedAt: '2025-11-18T11:56:10Z'
queuedOnly:
summary: Filtered by status=queued with page limit
value:
- jobId: job_01JF0500QUE
status: queued
queue: export
tenant: tenant-beta
enqueuedAt: '2025-11-18T12:05:00Z'
- jobId: job_01JF0501QUE
status: queued
queue: scan
tenant: tenant-beta
enqueuedAt: '2025-11-18T12:04:10Z'
'400':
description: Invalid request
content:
application/json:
schema:
$ref: ../_shared/schemas/common.yaml#/schemas/ErrorEnvelope
examples:
invalidStatus:
summary: Bad status filter
value:
code: orch.invalid_request
message: status must be one of queued,running,failed,completed.
traceId: 01JF04ERR1
/jobs/{jobId}:
get:
tags:
- Jobs
summary: Get job status
operationId: orchestratorGetJob
description: Fetch the current status of a job by id.
parameters:
- name: jobId
in: path
@@ -187,7 +245,29 @@ paths:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
components:
securitySchemes:
OAuthClientCredentials:
type: oauth2
description: OAuth 2.1 client credentials flow scoped per service.
flows:
clientCredentials:
tokenUrl: /token
scopes: {}
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
ErrorEnvelope:
type: object
properties:
code:
type: string
message:
type: string
traceId:
type: string
required: [code, message]
JobSummary:
type: object
required:
@@ -218,3 +298,35 @@ components:
format: date-time
tenant:
type: string
JobCreateRequest:
type: object
required:
- kind
- payload
properties:
kind:
type: string
description: Job kind identifier.
payload:
type: object
description: Job payload (kind-specific fields).
priority:
type: string
enum: [low, normal, high]
tenant:
type: string
JobCreateResponse:
type: object
required:
- jobId
- status
properties:
jobId:
type: string
status:
type: string
queue:
type: string
enqueuedAt:
type: string
format: date-time

126
src/Api/StellaOps.Api.OpenApi/policy/openapi.yaml
View File

@@ -1,9 +1,20 @@
openapi: 3.1.0
info:
title: StellaOps Policy Engine API (stub)
version: 0.0.1
description: Health + evaluation scaffold for Policy Engine; replace with real contracts
as authored.
version: 0.0.3
description: Health + evaluation scaffold for Policy Engine; examples added for evaluation and list endpoints.
contact:
name: StellaOps API Guild
email: api@stella-ops.local
tags:
- name: Health
description: Liveness endpoints
- name: Meta
description: Readiness/metadata endpoints
- name: Evaluation
description: Policy evaluation APIs
- name: Policies
description: Policy management APIs
servers:
- url: https://policy.stellaops.local
description: Example Policy Engine endpoint
@@ -13,6 +24,8 @@ paths:
tags:
- Health
summary: Liveness probe
description: Returns OK when the Policy Engine is reachable.
operationId: policyHealth
responses:
'200':
description: Service is up
@@ -40,6 +53,8 @@ paths:
summary: Service health
tags:
- Meta
description: Readiness probe for orchestrators.
operationId: policyHealthz
responses:
'200':
description: Service healthy
@@ -65,12 +80,14 @@ paths:
value:
code: service_unavailable
message: projector backlog exceeds SLA
traceId: 2
traceId: "2"
/evaluate:
post:
tags:
- Evaluation
summary: Evaluate policy for an artifact
description: Evaluate the active policy version for an artifact and return allow/deny decision.
operationId: policyEvaluate
requestBody:
required: true
content:
@@ -86,6 +103,7 @@ paths:
inputs:
tenant: acme
branch: main
environment: prod
responses:
'200':
description: Evaluation succeeded
@@ -105,6 +123,20 @@ paths:
latencyMs: 42
obligations:
- record: evidence
deny:
summary: Deny decision with obligations
value:
decision: deny
policyVersion: 2025.10.1
traceId: 01JF040DENY
reasons:
- missing attestation
- vulnerable runtime package
metadata:
latencyMs: 55
obligations:
- quarantine: true
- notify: security-team
schema:
$ref: '#/components/schemas/EvaluationResponse'
'400':
@@ -123,8 +155,94 @@ paths:
security:
- OAuthClientCredentials: []
- BearerAuth: []
/policies:
get:
tags:
- Policies
summary: List policies
description: Returns a paginated list of policy documents filtered by tenant and status.
operationId: policyList
parameters:
- $ref: '../_shared/parameters/tenant.yaml#/parameters/TenantParam'
- $ref: '../_shared/parameters/paging.yaml#/parameters/LimitParam'
- $ref: '../_shared/parameters/paging.yaml#/parameters/CursorParam'
- in: query
name: status
description: Optional status filter (draft, active, retired)
schema:
type: string
enum: [draft, active, retired]
responses:
'200':
description: Policy list page
content:
application/json:
schema:
$ref: '#/components/schemas/PolicyListResponse'
examples:
default:
summary: First page of active policies
value:
items:
- id: pol-1234
name: Critical CVE blocker
status: active
version: 5
tenant: tenant-alpha
updatedAt: 2025-11-20T12:00:00Z
- id: pol-5678
name: Runtime Allowlist
status: active
version: 2
tenant: tenant-alpha
updatedAt: 2025-11-18T09:14:00Z
pageSize: 50
nextPageToken: eyJvZmZzZXQiOiIxMDAifQ==
'400':
$ref: '../_shared/responses/defaults.yaml#/responses/ErrorResponse'
'401':
$ref: '../_shared/responses/defaults.yaml#/responses/ErrorResponse'
components:
securitySchemes:
OAuthClientCredentials:
type: oauth2
description: OAuth 2.1 client credentials flow scoped per service.
flows:
clientCredentials:
tokenUrl: /token
scopes: {}
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
schemas:
PolicyListResponse:
type: object
required:
- items
properties:
items:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
status:
type: string
version:
type: integer
tenant:
type: string
updatedAt:
type: string
format: date-time
pageSize:
type: integer
nextPageToken:
type: string
EvaluationRequest:
type: object
required:

48
src/Api/StellaOps.Api.OpenApi/scheduler/openapi.yaml
View File

@@ -1,8 +1,18 @@
openapi: 3.1.0
info:
title: StellaOps Scheduler API (stub)
version: 0.0.1
description: Health and queue status scaffold for Scheduler service; replace with full contract as authored.
version: 0.0.3
description: Health and queue status scaffold for Scheduler service; added queue status examples.
contact:
name: StellaOps API Guild
email: api@stella-ops.local
tags:
- name: Health
description: Liveness endpoints
- name: Meta
description: Readiness/metadata endpoints
- name: Queues
description: Queue metrics APIs
servers:
- url: https://scheduler.stellaops.local
description: Example Scheduler endpoint
@@ -12,6 +22,8 @@ paths:
tags:
- Health
summary: Liveness probe
description: Returns OK when Scheduler is reachable.
operationId: schedulerHealth
responses:
'200':
description: Service is up
@@ -39,6 +51,8 @@ paths:
summary: Service health
tags:
- Meta
description: Readiness probe for queue connectivity.
operationId: schedulerHealthz
responses:
'200':
description: Service healthy
@@ -64,12 +78,14 @@ paths:
value:
code: service_unavailable
message: queue backlog exceeds threshold
traceId: 4
traceId: "4"
/queues/{name}:
get:
tags:
- Queues
summary: Get queue status
description: Returns depth, inflight, and age metrics for a queue.
operationId: schedulerGetQueueStatus
parameters:
- name: name
in: path
@@ -93,6 +109,14 @@ paths:
inflight: 2
oldestAgeSeconds: 45
updatedAt: '2025-11-18T12:00:00Z'
empty:
summary: Empty queue
value:
name: export
depth: 0
inflight: 0
oldestAgeSeconds: 0
updatedAt: '2025-11-18T12:05:00Z'
'404':
description: Queue not found
content:
@@ -108,6 +132,24 @@ paths:
traceId: 01JF04NF2
components:
schemas:
HealthEnvelope:
type: object
properties:
status:
type: string
service:
type: string
required: [status, service]
ErrorEnvelope:
type: object
properties:
code:
type: string
message:
type: string
traceId:
type: string
required: [code, message]
QueueStatus:
type: object
required:

2592
src/Api/StellaOps.Api.OpenApi/stella.yaml
View File

File diff suppressed because it is too large Load Diff

4
src/Api/StellaOps.Api.OpenApi/tasks.md
View File

@@ -4,7 +4,7 @@
| --- | --- | --- |
| OAS-61-001 | DONE | Scaffold per-service OpenAPI 3.1 files with shared components, info blocks, and initial path stubs. |
| OAS-61-002 | DONE (2025-11-18) | Composer (`compose.mjs`) emits `stella.yaml` with namespaced paths/components; CI job validates aggregate stays up to date. |
| OAS-62-001 | DOING | Populate request/response examples for top 50 endpoints, including standard error envelope. |
| OAS-62-002 | TODO | Add custom lint rules enforcing pagination, idempotency headers, naming conventions, and example coverage. |
| OAS-62-001 | DONE (2025-11-26) | Added examples across Authority, Policy, Orchestrator, Scheduler, Export, and Graph stubs covering top flows; standard error envelopes present via shared components. |
| OAS-62-002 | DOING | Added rules for 2xx examples and /jobs Idempotency-Key; extend to pagination/idempotency/naming coverage (current lint is warning-free). |
| OAS-63-001 | TODO | Implement compatibility diff tooling comparing previous release specs; classify breaking vs additive changes. |
| OAS-63-002 | DONE (2025-11-24) | Discovery endpoint metadata and schema extensions added; composed spec exports `/.well-known/openapi` entry. |