agentskeptic 0.2.1 → 1.0.1

package/schemas/openapi-commercial-v1.yaml

@@ -8,7 +8,7 @@ info:
     repository: https://github.com/jwekavanagh/agentskeptic
     npmPackage: https://www.npmjs.com/package/agentskeptic
     openApi: https://agentskeptic.com/openapi-commercial-v1.yaml
-  description: "State verification engine: read-only SQL checks that database state matches expectations from structured tool activity (not arbitrary logs)—not proof of execution\n\nMachine-readable contract for license preflight used by the published npm CLI.\nBase URL is your deployed app origin (same as NEXT_PUBLIC_APP_URL).\n"
+  description: "Read-only checks at verify time—not color.\n\nMachine-readable contract for license preflight used by the published npm CLI.\nBase URL is your deployed app origin (same as NEXT_PUBLIC_APP_URL).\n\nEvery path in this document returns an `x-request-id` response header on all status codes (echo a valid client `x-request-id` when supplied; otherwise server-generated). Non-2xx JSON bodies follow RFC 7807-style Problem Details (`type`, `title`, `status`, `detail`, optional `code`, `instance`) unless noted; `POST /api/v1/usage/reserve` denials additionally include legacy `allowed`, `code`, `message`, and optional `upgrade_url` for backward compatibility.\n"
 externalDocs:
   description: "First-run integration guide"
   url: https://agentskeptic.com/integrate
@@ -45,7 +45,7 @@ paths:
               schema:
                 $ref: "#/components/schemas/ReserveError"
         "401":
-          description: Invalid or revoked API key
+          description: Invalid API key or key lifecycle denial (revoked, disabled, expired)
           content:
             application/json:
               schema:
@@ -73,6 +73,142 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/CommercialPlansResponse"
+        "503":
+          description: Plans configuration unavailable
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+  /api/v1/usage/current:
+    get:
+      operationId: getCurrentUsage
+      summary: Current usage and quota status for authenticated API key principal
+      security:
+        - bearerAuth: []
+      responses:
+        "200":
+          description: Current month usage and quota status
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/UsageCurrentV1"
+        "401":
+          description: Invalid API key or key lifecycle denial
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "403":
+          description: Missing required scope
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "503":
+          description: Plans configuration unavailable or server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+  /api/v1/enforcement/baselines:
+    post:
+      operationId: createEnforcementBaseline
+      summary: Create or replace accepted enforcement baseline for a workflow
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EnforcementProjectionRequest"
+      responses:
+        "200":
+          description: Baseline created or replaced
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EnforcementStateResponse"
+        "400":
+          description: Invalid request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "401":
+          description: Invalid API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+  /api/v1/enforcement/check:
+    post:
+      operationId: checkEnforcementDrift
+      summary: Compare current run projection against accepted baseline
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EnforcementProjectionRequest"
+      responses:
+        "200":
+          description: Comparison result (ok or drift)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EnforcementCheckResponse"
+        "409":
+          description: Baseline not initialized
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+  /api/v1/enforcement/accept:
+    post:
+      operationId: acceptEnforcementDrift
+      summary: Accept current projection as new baseline
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EnforcementProjectionRequest"
+      responses:
+        "200":
+          description: Drift accepted
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EnforcementStateResponse"
+  /api/v1/enforcement/history:
+    get:
+      operationId: getEnforcementHistory
+      summary: Retrieve enforcement timeline for one workflow
+      security:
+        - bearerAuth: []
+      parameters:
+        - name: workflow_id
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+      responses:
+        "200":
+          description: Timeline events
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/EnforcementHistoryResponse"
   /api/public/verification-reports:
     post:
       operationId: createPublicVerificationReport
@@ -94,10 +230,226 @@ paths:
                 $ref: "#/components/schemas/PublicVerificationReportCreated"
         "400":
           description: Invalid JSON or failed schema validation
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
         "413":
           description: Request body exceeds maximum allowed size
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "500":
+          description: Server error storing report
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
         "503":
           description: Public report ingestion disabled or server unavailable
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+  /api/v1/funnel/verify-outcome:
+    post:
+      operationId: postVerifyOutcomeBeacon
+      summary: Licensed verify-outcome beacon (idempotent per API key + run_id)
+      description: >
+        POST after a successful `POST /api/v1/usage/reserve` for the same `run_id`. Success is HTTP 204 with an empty body.
+        Requires Bearer API key. Body schemaVersion must be 2.
+      security:
+        - bearerAuth: []
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/VerifyOutcomeRequestV2"
+      responses:
+        "204":
+          description: Beacon accepted (or duplicate ignored)
+        "400":
+          description: Invalid JSON or validation failure
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "401":
+          description: Invalid API key
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "404":
+          description: No reservation for this run_id
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "410":
+          description: Reservation too old
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "503":
+          description: Server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+  /api/oss/claim-ticket:
+    post:
+      operationId: postOssClaimTicket
+      summary: Mint OSS claim ticket (CLI only; product activation headers required)
+      description: >
+        Creates or returns a handoff URL for linking a verification run to a web account.
+        Requires `X-AgentSkeptic-Cli-Product` and `X-AgentSkeptic-Cli-Version` headers (see website/src/lib/funnelProductActivationConstants.ts).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OssClaimTicketRequest"
+      responses:
+        "200":
+          description: Handoff URL returned
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OssClaimTicketHandoffResponse"
+        "204":
+          description: Ticket already claimed (idempotent)
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "403":
+          description: Forbidden (unsupported CLI client)
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "413":
+          description: Payload too large
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "429":
+          description: Rate limited
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "503":
+          description: Server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+  /api/oss/claim-redeem:
+    post:
+      operationId: postOssClaimRedeem
+      summary: Redeem OSS claim ticket (browser session; optional claim_secret in body)
+      description: Requires an authenticated session; prefers pending cookie from GET /verify/link.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OssClaimRedeemRequest"
+      responses:
+        "200":
+          description: Redeemed; returns run summary
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/OssClaimRedeemOk"
+        "400":
+          description: Claim failed or expired
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "401":
+          description: Not signed in
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "409":
+          description: Already linked to another account
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "429":
+          description: Rate limited
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "503":
+          description: Server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+  /api/oss/claim-continuation:
+    post:
+      operationId: postOssClaimContinuation
+      summary: Record browser-open acknowledgement for interactive-human tickets (CLI only)
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/OssClaimContinuationRequest"
+      responses:
+        "204":
+          description: Recorded or already recorded
+        "400":
+          description: Bad request
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "403":
+          description: Not applicable or forbidden
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "413":
+          description: Payload too large
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+        "503":
+          description: Server error
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ProblemDetails"
+  /api/oss/claim-handoff:
+    get:
+      operationId: getOssClaimHandoffLegacy
+      summary: Legacy handoff redirect (308 to /verify/link)
+      parameters:
+        - name: h
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        "308":
+          description: Redirect to /verify/link?h=…
 components:
   securitySchemes:
     bearerAuth:
@@ -105,10 +457,169 @@ components:
       scheme: bearer
       bearerFormat: API key
   schemas:
+    EnforcementProjectionRequest:
+      type: object
+      required: [run_id, workflow_id, projection_hash, projection]
+      properties:
+        run_id:
+          type: string
+        workflow_id:
+          type: string
+        projection_hash:
+          type: string
+        projection:
+          type: object
+          additionalProperties: true
+    EnforcementStateResponse:
+      type: object
+      required: [schema_version, status, workflow_id]
+      properties:
+        schema_version:
+          type: integer
+          const: 1
+        status:
+          type: string
+        workflow_id:
+          type: string
+    EnforcementCheckResponse:
+      allOf:
+        - $ref: "#/components/schemas/EnforcementStateResponse"
+        - type: object
+          required: [expected_projection_hash, actual_projection_hash]
+          properties:
+            expected_projection_hash:
+              type: string
+            actual_projection_hash:
+              type: string
+    EnforcementHistoryResponse:
+      type: object
+      required: [schema_version, workflow_id, events]
+      properties:
+        schema_version:
+          type: integer
+          const: 1
+        workflow_id:
+          type: string
+        events:
+          type: array
+          items:
+            type: object
+            additionalProperties: true
+    ProblemDetails:
+      type: object
+      required: [type, title, status, detail]
+      properties:
+        type:
+          type: string
+          format: uri
+        title:
+          type: string
+        status:
+          type: integer
+        detail:
+          type: string
+        instance:
+          type: string
+        code:
+          type: string
+    VerifyOutcomeRequestV2:
+      type: object
+      required:
+        - schema_version
+        - run_id
+        - workflow_id
+        - trust_decision
+        - reason_codes
+        - terminal_status
+        - workload_class
+        - subcommand
+      properties:
+        schema_version:
+          type: integer
+          const: 2
+        run_id:
+          type: string
+          maxLength: 256
+        workflow_id:
+          type: string
+          maxLength: 512
+        trust_decision:
+          type: string
+          enum: [safe, unsafe, unknown]
+        reason_codes:
+          type: array
+          maxItems: 8
+          items:
+            type: string
+        terminal_status:
+          type: string
+          enum: [complete, inconsistent, incomplete]
+        workload_class:
+          type: string
+          enum: [bundled_examples, non_bundled]
+        subcommand:
+          type: string
+          enum: [batch_verify, quick_verify, verify_integrator_owned]
+    OssClaimTicketRequest:
+      type: object
+      description: v1 or v2 OSS claim ticket wire shape (see website/src/lib/ossClaimTicketPayload.ts).
+      additionalProperties: true
+    OssClaimTicketHandoffResponse:
+      type: object
+      required: [schema_version, handoff_url]
+      properties:
+        schema_version:
+          type: integer
+          const: 2
+        handoff_url:
+          type: string
+          format: uri
+    OssClaimRedeemRequest:
+      type: object
+      properties:
+        claim_secret:
+          type: string
+          pattern: "^[0-9a-f]{64}$"
+      additionalProperties: true
+    OssClaimRedeemOk:
+      type: object
+      required:
+        - schema_version
+        - run_id
+        - terminal_status
+        - workload_class
+        - subcommand
+        - build_profile
+        - claimed_at
+      properties:
+        schema_version:
+          type: integer
+          const: 1
+        run_id:
+          type: string
+        terminal_status:
+          type: string
+        workload_class:
+          type: string
+        subcommand:
+          type: string
+        build_profile:
+          type: string
+        claimed_at:
+          type: string
+          format: date-time
+    OssClaimContinuationRequest:
+      type: object
+      required: [claim_secret]
+      properties:
+        claim_secret:
+          type: string
+          pattern: "^[0-9a-f]{64}$"
+      additionalProperties: false
     PublicVerificationReportCreate:
       description: >
-        Discriminated envelope (schemaVersion 1). Workflow branch includes WorkflowResult + truth report text.
-        Quick branch includes QuickVerifyReport + human report text + workflowDisplayId for labeling.
+        POST accepts schemaVersion 2 only: { "schemaVersion": 2, "certificate": <OutcomeCertificateV1> } per
+        schemas/public-verification-report-v2.schema.json. Legacy v1 envelopes are rejected with HTTP 400.
       type: object
       additionalProperties: true
     PublicVerificationReportCreated:
@@ -121,7 +632,7 @@ components:
       properties:
         schemaVersion:
           type: integer
-          const: 1
+          const: 2
         id:
           type: string
           format: uuid
@@ -146,7 +657,10 @@ components:
           type: string
           enum: [verify, enforce]
           default: verify
-          description: enforce requires paid plan with active subscription; verify requires active subscription on individual/team/business/enterprise
+          description: >
+            enforce requires a paid plan (not Starter) with active subscription; verify is allowed
+            for Starter (free included quota) and for paid plans with active subscription; overage
+            is permitted past included for paid plans with allowOverage in plan catalog
     ReserveAllowed:
       type: object
       required:
@@ -154,6 +668,8 @@ components:
         - plan
         - limit
         - used
+        - included_monthly
+        - overage_count
       properties:
         allowed:
           type: boolean
@@ -163,25 +679,90 @@ components:
           enum: [starter, individual, team, business, enterprise]
         limit:
           type: integer
+          description: Included verifications in the current billing month (not enterprise unlimited sentinel)
         used:
           type: integer
+          description: Total verifications counted this month for this API key
+        included_monthly:
+          oneOf:
+            - type: integer
+            - type: "null"
+          description: Same as limit for finite plans; null for enterprise unlimited
+        overage_count:
+          type: integer
+          description: max(0, used - included_monthly) when the plan has a finite cap
     ReserveError:
+      allOf:
+        - $ref: "#/components/schemas/ProblemDetails"
+        - type: object
+          required: [allowed, code, message]
+          properties:
+            allowed:
+              type: boolean
+              enum: [false]
+            code:
+              type: string
+              description: >
+                Examples BAD_REQUEST, INVALID_KEY, QUOTA_EXCEEDED, ENFORCEMENT_REQUIRES_PAID_PLAN,
+                VERIFICATION_REQUIRES_SUBSCRIPTION, SUBSCRIPTION_INACTIVE, BILLING_PRICE_UNMAPPED,
+                INSUFFICIENT_SCOPE, KEY_EXPIRED, KEY_REVOKED, KEY_DISABLED, SERVER_ERROR
+            message:
+              type: string
+            upgrade_url:
+              type: string
+              format: uri
+              description: Present for some 403 entitlement responses
+    UsageCurrentV1:
       type: object
+      required:
+        - schema_version
+        - plan
+        - year_month
+        - period_start_utc
+        - period_end_utc
+        - used_total
+        - included_monthly
+        - allow_overage
+        - overage_count
+        - quota_state
+        - allowed_next
+        - estimated_overage_usd
       properties:
-        allowed:
-          type: boolean
-          enum: [false]
-        code:
+        schema_version:
+          type: integer
+          const: 1
+        plan:
           type: string
-          description: >
-            Examples BAD_REQUEST, INVALID_KEY, QUOTA_EXCEEDED, VERIFICATION_REQUIRES_SUBSCRIPTION,
-            ENFORCEMENT_REQUIRES_PAID_PLAN, SUBSCRIPTION_INACTIVE, BILLING_PRICE_UNMAPPED, SERVER_ERROR
-        message:
+          enum: [starter, individual, team, business, enterprise]
+        year_month:
           type: string
-        upgrade_url:
+          pattern: "^[0-9]{4}-[0-9]{2}$"
+        period_start_utc:
           type: string
-          format: uri
-          description: Present for some 403 entitlement responses
+          format: date-time
+        period_end_utc:
+          type: string
+          format: date-time
+        used_total:
+          type: integer
+          minimum: 0
+        included_monthly:
+          oneOf:
+            - type: integer
+            - type: "null"
+        allow_overage:
+          type: boolean
+        overage_count:
+          type: integer
+          minimum: 0
+        quota_state:
+          type: string
+          enum: [ok, notice, warning, in_overage, at_cap]
+        allowed_next:
+          type: boolean
+        estimated_overage_usd:
+          type: string
+          example: "24.00"
     CommercialPlansResponse:
       type: object
       required:
@@ -205,8 +786,26 @@ components:
           oneOf:
             - type: integer
             - type: "null"
+        yearlyUsdCents:
+          oneOf:
+            - type: integer
+            - type: "null"
         displayPrice:
           type: string
+        displayPriceYearly:
+          oneOf:
+            - type: string
+            - type: "null"
+        overageMicrousdPerVerification:
+          oneOf:
+            - type: integer
+            - type: "null"
+        allowOverage:
+          type: boolean
+        overageDisplayLabel:
+          oneOf:
+            - type: string
+            - type: "null"
         marketingHeadline:
           type: string
         audience: