{
    "openapi": "3.0.3",
    "info": {
        "title": "QUIQQER Package Server",
        "version": "0.1.0"
    },
    "paths": {
        "/packages.json": {
            "get": {
                "description": "Composer 2 public index. Revalidate on every use. Supports HEAD and conditional GET.",
                "operationId": "composerIndex",
                "parameters": [
                    {
                        "$ref": "#/components/parameters/IfNoneMatch"
                    },
                    {
                        "$ref": "#/components/parameters/IfModifiedSince"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Public package names and metadata-url",
                        "headers": {
                            "ETag": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "Last-Modified": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "packages": {
                                            "type": "array",
                                            "items": {},
                                            "maxItems": 0
                                        },
                                        "metadata-url": {
                                            "type": "string",
                                            "example": "/p2/%package%.json"
                                        },
                                        "available-packages": {
                                            "type": "array",
                                            "items": {
                                                "type": "string"
                                            }
                                        }
                                    },
                                    "required": [
                                        "packages",
                                        "metadata-url",
                                        "available-packages"
                                    ]
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Unchanged; empty body"
                    },
                    "500": {
                        "description": "Storage error"
                    }
                }
            }
        },
        "/p2/{vendor}/{name}.json": {
            "get": {
                "description": "Composer 2 P2 document. Append ~dev for source-only branches. Private packages return 404.",
                "operationId": "composerPackage",
                "parameters": [
                    {
                        "name": "vendor",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "name",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "core~dev"
                    },
                    {
                        "$ref": "#/components/parameters/IfNoneMatch"
                    },
                    {
                        "$ref": "#/components/parameters/IfModifiedSince"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Release or dev versions; an existing package may have an empty version list",
                        "headers": {
                            "ETag": {
                                "schema": {
                                    "type": "string"
                                }
                            },
                            "Last-Modified": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "packages": {
                                            "type": "object",
                                            "additionalProperties": {
                                                "type": "array",
                                                "items": {
                                                    "type": "object"
                                                }
                                            }
                                        }
                                    },
                                    "required": [
                                        "packages"
                                    ]
                                }
                            }
                        }
                    },
                    "304": {
                        "description": "Unchanged; empty body"
                    },
                    "404": {
                        "description": "Unknown or non-public package",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Storage error"
                    }
                }
            }
        },
        "/downloads/{vendor}/{name}/{version}.zip": {
            "get": {
                "description": "Unchanged ZIP stream. HEAD uses identical authorization, without a body. No caching, redirects, conditional 304 or range responses. Public packages need no credentials. Private/internal require the complete version/licenseId/downloadKey query, both license headers, or a valid store key. Query and license headers cannot mix without a store key. A supplied store key is exclusive. Query version must exactly match the stored tag; invalid queries never bypass validation.",
                "operationId": "downloadRelease",
                "parameters": [
                    {
                        "name": "vendor",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "name",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "version",
                        "in": "path",
                        "description": "Release tag or Composer-normalized alias, e.g. v1.2.0, 1.2.0.0 or 2.0.0.0-RC1",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "version",
                        "in": "query",
                        "description": "Exact stored original tag. Supply all three query parameters once, or none.",
                        "schema": {
                            "type": "string"
                        },
                        "example": "v1.2.0"
                    },
                    {
                        "name": "licenseId",
                        "in": "query",
                        "description": "Customer license ID, URL-encoded; cannot mix with license headers.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "downloadKey",
                        "in": "query",
                        "description": "Customer download key from the license server. Never a server API key.",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "X-License-Id",
                        "in": "header",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "X-Download-Key",
                        "in": "header",
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "X-Package-Store-Key",
                        "in": "header",
                        "schema": {
                            "type": "string"
                        }
                    }
                ],
                "responses": {
                    "200": {
                        "description": "ZIP; Cache-Control: no-store",
                        "headers": {
                            "Content-Length": {
                                "schema": {
                                    "type": "integer"
                                }
                            },
                            "Content-Disposition": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        },
                        "content": {
                            "application/zip": {
                                "schema": {
                                    "type": "string",
                                    "format": "binary"
                                }
                            }
                        }
                    },
                    "400": {
                        "description": "Malformed, incomplete, duplicate or mixed query parameters, or tag mismatch",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "403": {
                        "description": "Missing, malformed or denied credentials",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Unknown release or branch without archive",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "405": {
                        "description": "Method not allowed",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "409": {
                        "description": "State changed during authorization; repeat request",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "description": "License server unavailable, unconfigured or unexpected response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Storage or application error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/health": {
            "get": {
                "description": "Application liveness only; does not check storage or external services.",
                "operationId": "health",
                "responses": {
                    "200": {
                        "description": "Application bootstrapped",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object",
                                    "properties": {
                                        "status": {
                                            "type": "string",
                                            "enum": [
                                                "ok"
                                            ]
                                        },
                                        "service": {
                                            "type": "string",
                                            "enum": [
                                                "package-server"
                                            ]
                                        }
                                    },
                                    "required": [
                                        "status",
                                        "service"
                                    ],
                                    "additionalProperties": false
                                }
                            }
                        }
                    },
                    "500": {
                        "description": "Internal error",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/openapi.json": {
            "get": {
                "description": "The checked-in OpenAPI document served directly by the webserver. Supports HEAD.",
                "operationId": "openApiDocument",
                "responses": {
                    "200": {
                        "description": "OpenAPI 3 document",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "type": "object"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/api/releases": {
            "post": {
                "description": "Upload the already built release ZIP (256 MiB maximum, multipart 257 MiB). OIDC authorizes the project; the supplied release commit may differ from the token SHA. No authenticated GitLab reads. License synchronization precedes local publication. No query parameters. Identical retries are idempotent; immutable release or revision conflicts return 409.",
                "operationId": "releasePublication",
                "requestBody": {
                    "content": {
                        "multipart/form-data": {
                            "schema": {
                                "$ref": "#/components/schemas/ReleaseRequest"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Release published or already published; Cache-Control: no-store",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Publication"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/PublicationBadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/PublicationUnauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/PublicationForbidden"
                    },
                    "405": {
                        "$ref": "#/components/responses/PublicationMethodNotAllowed"
                    },
                    "409": {
                        "description": "Immutable release, package binding or concurrent update conflict",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "413": {
                        "$ref": "#/components/responses/PublicationTooLarge"
                    },
                    "415": {
                        "$ref": "#/components/responses/PublicationMediaType"
                    },
                    "422": {
                        "description": "Invalid request fields, ref, metadata or ZIP",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "$ref": "#/components/responses/PublicationUnavailable"
                    },
                    "500": {
                        "$ref": "#/components/responses/PublicationFailure"
                    }
                },
                "security": [
                    {
                        "OidcToken": []
                    }
                ]
            }
        },
        "/api/branches": {
            "post": {
                "description": "Publish the supplied branch commit and complete Composer metadata, without ZIP. OIDC authorizes the project; no authenticated GitLab reads. JSON at most 2 MiB. License synchronization precedes local publication; no query parameters. Local revision conflicts return 409; sequential delayed publications may move a branch backwards.",
                "operationId": "branchPublication",
                "requestBody": {
                    "content": {
                        "application/json": {
                            "schema": {
                                "$ref": "#/components/schemas/BranchRequest"
                            }
                        }
                    },
                    "required": true
                },
                "responses": {
                    "200": {
                        "description": "Branch updated; Cache-Control: no-store",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Publication"
                                }
                            }
                        }
                    },
                    "400": {
                        "$ref": "#/components/responses/PublicationBadRequest"
                    },
                    "401": {
                        "$ref": "#/components/responses/PublicationUnauthorized"
                    },
                    "403": {
                        "$ref": "#/components/responses/PublicationForbidden"
                    },
                    "405": {
                        "$ref": "#/components/responses/PublicationMethodNotAllowed"
                    },
                    "409": {
                        "description": "Package binding or concurrent branch/package update conflict",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "413": {
                        "$ref": "#/components/responses/PublicationTooLarge"
                    },
                    "415": {
                        "$ref": "#/components/responses/PublicationMediaType"
                    },
                    "422": {
                        "description": "Invalid request fields, branch or metadata",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "$ref": "#/components/schemas/Error"
                                }
                            }
                        }
                    },
                    "503": {
                        "$ref": "#/components/responses/PublicationUnavailable"
                    },
                    "500": {
                        "$ref": "#/components/responses/PublicationFailure"
                    }
                },
                "security": [
                    {
                        "OidcToken": []
                    }
                ]
            }
        },
        "/": {
            "get": {
                "description": "Public package overview and Composer usage. Supports HEAD; no-store.",
                "operationId": "websiteIndex",
                "responses": {
                    "200": {
                        "description": "HTML overview, including an empty catalogue",
                        "content": {
                            "text/html": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        },
        "/packages/{vendor}/{name}": {
            "get": {
                "description": "Public package details. Private, internal, empty and unknown packages return the same HTML 404. Supports HEAD; no-store.",
                "operationId": "websitePackage",
                "parameters": [
                    {
                        "name": "vendor",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        }
                    },
                    {
                        "name": "name",
                        "in": "path",
                        "required": true,
                        "schema": {
                            "type": "string"
                        },
                        "example": "core"
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Releases, source-only branches and Composer usage",
                        "content": {
                            "text/html": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    },
                    "404": {
                        "description": "Package not publicly available",
                        "content": {
                            "text/html": {
                                "schema": {
                                    "type": "string"
                                }
                            }
                        }
                    }
                }
            }
        }
    },
    "components": {
        "schemas": {
            "Error": {
                "type": "object",
                "properties": {
                    "error": {
                        "type": "object",
                        "properties": {
                            "code": {
                                "type": "string",
                                "example": "not_found"
                            },
                            "message": {
                                "type": "string",
                                "example": "Route not found."
                            }
                        },
                        "required": [
                            "code",
                            "message"
                        ],
                        "additionalProperties": false
                    }
                },
                "required": [
                    "error"
                ],
                "additionalProperties": false
            },
            "Publication": {
                "type": "object",
                "properties": {
                    "status": {
                        "type": "string",
                        "enum": [
                            "published",
                            "already_published",
                            "updated"
                        ]
                    },
                    "package": {
                        "type": "string"
                    },
                    "version": {
                        "type": "string"
                    },
                    "commit": {
                        "type": "string"
                    }
                },
                "required": [
                    "status",
                    "package",
                    "version",
                    "commit"
                ],
                "additionalProperties": false
            },
            "ReleaseRequest": {
                "type": "object",
                "properties": {
                    "project_id": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "package": {
                        "type": "string",
                        "pattern": "^[a-z0-9]+(?:[_.-][a-z0-9]+)*/[a-z0-9]+(?:[_.-][a-z0-9]+|--[a-z0-9]+)*$"
                    },
                    "tag": {
                        "type": "string",
                        "description": "Composer release tag including alpha/beta/RC; dev stability is rejected.",
                        "minLength": 1,
                        "maxLength": 255,
                        "pattern": "^[vV]?[0-9][0-9A-Za-z.+_-]*$"
                    },
                    "commit": {
                        "type": "string",
                        "pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$"
                    },
                    "archive": {
                        "type": "string",
                        "format": "binary",
                        "description": "ZIP, at most 256 MiB."
                    },
                    "committed_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Optional real commit timestamp, RFC3339 seconds; omitted means unknown."
                    }
                },
                "required": [
                    "package",
                    "tag",
                    "commit",
                    "archive"
                ],
                "additionalProperties": false
            },
            "BranchRequest": {
                "type": "object",
                "properties": {
                    "project_id": {
                        "type": "integer",
                        "minimum": 1
                    },
                    "package": {
                        "type": "string",
                        "pattern": "^[a-z0-9]+(?:[_.-][a-z0-9]+)*/[a-z0-9]+(?:[_.-][a-z0-9]+|--[a-z0-9]+)*$"
                    },
                    "branch": {
                        "type": "string",
                        "description": "Publish the pipeline-supplied commit; no GitLab head lookup.",
                        "minLength": 1,
                        "maxLength": 255,
                        "pattern": "^(?:main|master|next-[a-zA-Z0-9_-]+\\.x)$"
                    },
                    "commit": {
                        "type": "string",
                        "pattern": "^(?:[a-f0-9]{40}|[a-f0-9]{64})$"
                    },
                    "composer": {
                        "type": "object",
                        "description": "Complete composer.json object, at most 1 MiB when encoded.",
                        "properties": {
                            "name": {
                                "type": "string",
                                "pattern": "^[a-z0-9]+(?:[_.-][a-z0-9]+)*/[a-z0-9]+(?:[_.-][a-z0-9]+|--[a-z0-9]+)*$"
                            }
                        },
                        "required": [
                            "name"
                        ],
                        "additionalProperties": true
                    },
                    "committed_at": {
                        "type": "string",
                        "format": "date-time",
                        "description": "Optional real commit timestamp, RFC3339 seconds; omitted means unknown."
                    }
                },
                "required": [
                    "package",
                    "branch",
                    "commit",
                    "composer"
                ],
                "additionalProperties": false
            }
        },
        "responses": {
            "PublicationBadRequest": {
                "description": "Malformed JSON or query parameters",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "PublicationUnauthorized": {
                "description": "Missing, invalid or expired OIDC ID token",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "PublicationForbidden": {
                "description": "Untrusted origin, group or job project",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "PublicationMethodNotAllowed": {
                "description": "Method not allowed",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "PublicationTooLarge": {
                "description": "ZIP exceeds 256 MiB, multipart exceeds 257 MiB or JSON exceeds 2 MiB",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "PublicationMediaType": {
                "description": "Use multipart/form-data for releases or application/json for branches",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "PublicationUnavailable": {
                "description": "License synchronization failed after at most three attempts, unconfigured license server, OIDC key service unavailable or writer busy",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            },
            "PublicationFailure": {
                "description": "Local storage, configuration or unexpected application failure; repeat to repair after remote success",
                "content": {
                    "application/json": {
                        "schema": {
                            "$ref": "#/components/schemas/Error"
                        }
                    }
                }
            }
        },
        "parameters": {
            "IfNoneMatch": {
                "name": "If-None-Match",
                "in": "header",
                "description": "ETag or list; takes precedence over If-Modified-Since.",
                "schema": {
                    "type": "string"
                }
            },
            "IfModifiedSince": {
                "name": "If-Modified-Since",
                "in": "header",
                "description": "HTTP date. Ambiguous timestamps (same-second changes, clock rollback or unknown history) return 200; use ETag for precise validation.",
                "schema": {
                    "type": "string"
                }
            }
        },
        "securitySchemes": {
            "OidcToken": {
                "type": "http",
                "scheme": "bearer",
                "bearerFormat": "JWT"
            }
        }
    }
}