dc7c75b496
Some checks failed
Docs CI / lint-and-preview (push) Has been cancelled
feat: Implement BsonJsonConverter for converting BsonDocument and BsonArray to JSON fix: Update project file to include MongoDB.Bson package test: Add GraphOverlayExporterTests to validate NDJSON export functionality refactor: Refactor Program.cs in Attestation Tool for improved argument parsing and error handling docs: Update README for stella-forensic-verify with usage instructions and exit codes feat: Enhance HmacVerifier with clock skew and not-after checks feat: Add MerkleRootVerifier and ChainOfCustodyVerifier for additional verification methods fix: Update DenoRuntimeShim to correctly handle file paths feat: Introduce ComposerAutoloadData and related parsing in ComposerLockReader test: Add tests for Deno runtime execution and verification test: Enhance PHP package tests to include autoload data verification test: Add unit tests for HmacVerifier and verification logic
372 lines
10 KiB
YAML
372 lines
10 KiB
YAML
openapi: 3.0.3
|
|
info:
|
|
title: StellaOps Graph Gateway (draft)
|
|
version: 0.0.2-pre
|
|
description: |
|
|
Draft API surface for graph search/query/paths/diff/export with streaming tiles,
|
|
cost budgets, overlays, and RBAC headers. Aligns with sprint 0207 Wave 1 outline
|
|
(GRAPH-API-28-001..011).
|
|
servers:
|
|
- url: https://gateway.local/api
|
|
security:
|
|
- bearerAuth: []
|
|
|
|
paths:
|
|
/graph/search:
|
|
post:
|
|
summary: Search graph nodes with prefix/exact semantics and filters
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SearchRequest'
|
|
responses:
|
|
'200':
|
|
description: Stream of search tiles (NDJSON)
|
|
content:
|
|
application/x-ndjson:
|
|
schema:
|
|
$ref: '#/components/schemas/TileEnvelope'
|
|
'400': { $ref: '#/components/responses/ValidationError' }
|
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
'429': { $ref: '#/components/responses/BudgetExceeded' }
|
|
|
|
/graph/query:
|
|
post:
|
|
summary: Execute graph query with budgeted streaming tiles
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueryRequest'
|
|
responses:
|
|
'200':
|
|
description: Stream of query tiles (NDJSON)
|
|
content:
|
|
application/x-ndjson:
|
|
schema:
|
|
$ref: '#/components/schemas/TileEnvelope'
|
|
'400': { $ref: '#/components/responses/ValidationError' }
|
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
'429': { $ref: '#/components/responses/BudgetExceeded' }
|
|
|
|
/graph/paths:
|
|
post:
|
|
summary: Find constrained paths between node sets (depth ≤ 6)
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PathsRequest'
|
|
responses:
|
|
'200':
|
|
description: Stream of path tiles ordered by hop
|
|
content:
|
|
application/x-ndjson:
|
|
schema:
|
|
$ref: '#/components/schemas/TileEnvelope'
|
|
'400': { $ref: '#/components/responses/ValidationError' }
|
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
'429': { $ref: '#/components/responses/BudgetExceeded' }
|
|
|
|
/graph/diff:
|
|
post:
|
|
summary: Stream diff between two graph snapshots with overlay deltas
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/DiffRequest'
|
|
responses:
|
|
'200':
|
|
description: Stream of diff tiles (added/removed/changed)
|
|
content:
|
|
application/x-ndjson:
|
|
schema:
|
|
$ref: '#/components/schemas/TileEnvelope'
|
|
'400': { $ref: '#/components/responses/ValidationError' }
|
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
|
|
/graph/export:
|
|
post:
|
|
summary: Request export job for snapshot or query result
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ExportRequest'
|
|
responses:
|
|
'202':
|
|
description: Export job accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ExportJob'
|
|
'400': { $ref: '#/components/responses/ValidationError' }
|
|
'401': { $ref: '#/components/responses/Unauthorized' }
|
|
|
|
/graph/export/{jobId}:
|
|
get:
|
|
summary: Check export job status or download manifest
|
|
security:
|
|
- bearerAuth: []
|
|
parameters:
|
|
- $ref: '#/components/parameters/TenantHeader'
|
|
- $ref: '#/components/parameters/RequestIdHeader'
|
|
- name: jobId
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
'200':
|
|
description: Job status
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ExportJob'
|
|
'404':
|
|
description: Job not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
|
|
components:
|
|
securitySchemes:
|
|
bearerAuth:
|
|
type: http
|
|
scheme: bearer
|
|
bearerFormat: JWT
|
|
|
|
parameters:
|
|
TenantHeader:
|
|
name: X-Stella-Tenant
|
|
in: header
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Tenant identifier enforced on all routes.
|
|
RequestIdHeader:
|
|
name: X-Request-Id
|
|
in: header
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Optional caller-provided correlation id, echoed in responses.
|
|
|
|
schemas:
|
|
CostBudget:
|
|
type: object
|
|
properties:
|
|
limit:
|
|
type: integer
|
|
minimum: 1
|
|
remaining:
|
|
type: integer
|
|
minimum: 0
|
|
consumed:
|
|
type: integer
|
|
minimum: 0
|
|
required: [limit, remaining, consumed]
|
|
|
|
TileEnvelope:
|
|
type: object
|
|
properties:
|
|
type:
|
|
type: string
|
|
enum: [node, edge, stats, cursor, diagnostic]
|
|
seq:
|
|
type: integer
|
|
minimum: 0
|
|
cost:
|
|
$ref: '#/components/schemas/CostBudget'
|
|
data:
|
|
type: object
|
|
description: Payload varies by tile type (node/edge record, stats snapshot, cursor token, or diagnostic info).
|
|
required: [type, seq]
|
|
|
|
SearchRequest:
|
|
type: object
|
|
properties:
|
|
query:
|
|
type: string
|
|
description: Prefix or exact text; required unless filters present.
|
|
kinds:
|
|
type: array
|
|
items:
|
|
type: string
|
|
limit:
|
|
type: integer
|
|
default: 50
|
|
maximum: 500
|
|
filters:
|
|
type: object
|
|
additionalProperties: true
|
|
ordering:
|
|
type: string
|
|
enum: [relevance, id]
|
|
required: [kinds]
|
|
|
|
QueryRequest:
|
|
type: object
|
|
properties:
|
|
dsl:
|
|
type: string
|
|
description: DSL expression for graph traversal (mutually exclusive with filter).
|
|
filter:
|
|
type: object
|
|
description: Structured filter alternative to DSL.
|
|
budget:
|
|
type: object
|
|
properties:
|
|
nodeCap: { type: integer }
|
|
edgeCap: { type: integer }
|
|
timeMs: { type: integer }
|
|
overlays:
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum: [policy, vex, advisory]
|
|
explain:
|
|
type: string
|
|
enum: [none, minimal, full]
|
|
default: none
|
|
anyOf:
|
|
- required: [dsl]
|
|
- required: [filter]
|
|
|
|
PathsRequest:
|
|
type: object
|
|
properties:
|
|
sourceIds:
|
|
type: array
|
|
items: { type: string }
|
|
minItems: 1
|
|
targetIds:
|
|
type: array
|
|
items: { type: string }
|
|
minItems: 1
|
|
maxDepth:
|
|
type: integer
|
|
maximum: 6
|
|
default: 4
|
|
constraints:
|
|
type: object
|
|
properties:
|
|
edgeKinds:
|
|
type: array
|
|
items: { type: string }
|
|
fanoutCap:
|
|
type: integer
|
|
overlays:
|
|
type: array
|
|
items: { type: string }
|
|
required: [sourceIds, targetIds]
|
|
|
|
DiffRequest:
|
|
type: object
|
|
properties:
|
|
snapshotA: { type: string }
|
|
snapshotB: { type: string }
|
|
filters:
|
|
type: object
|
|
additionalProperties: true
|
|
required: [snapshotA, snapshotB]
|
|
|
|
ExportRequest:
|
|
type: object
|
|
properties:
|
|
snapshotId:
|
|
type: string
|
|
queryRef:
|
|
type: string
|
|
formats:
|
|
type: array
|
|
items:
|
|
type: string
|
|
enum: [graphml, csv, ndjson, png, svg]
|
|
includeOverlays:
|
|
type: boolean
|
|
default: false
|
|
anyOf:
|
|
- required: [snapshotId]
|
|
- required: [queryRef]
|
|
required: [formats]
|
|
|
|
ExportJob:
|
|
type: object
|
|
properties:
|
|
jobId: { type: string }
|
|
status: { type: string, enum: [pending, running, succeeded, failed] }
|
|
checksumManifestUrl: { type: string, format: uri }
|
|
downloadUrl: { type: string, format: uri }
|
|
createdAt: { type: string, format: date-time }
|
|
updatedAt: { type: string, format: date-time }
|
|
message: { type: string }
|
|
required: [jobId, status]
|
|
|
|
Error:
|
|
type: object
|
|
properties:
|
|
error:
|
|
type: string
|
|
enum: [GRAPH_BUDGET_EXCEEDED, GRAPH_VALIDATION_FAILED, GRAPH_RATE_LIMITED, GRAPH_UNAUTHORIZED]
|
|
message:
|
|
type: string
|
|
details:
|
|
type: object
|
|
request_id:
|
|
type: string
|
|
required: [error, message]
|
|
|
|
responses:
|
|
ValidationError:
|
|
description: Request failed validation
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
Unauthorized:
|
|
description: Missing or invalid credentials
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|
|
BudgetExceeded:
|
|
description: Budget exhausted mid-stream; includes partial cursor details
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Error'
|