@inklok/api-spec 7.2.0

package/README.md

@@ -0,0 +1,134 @@
+# OpenAPI Specification — OpaqueInk Core API
+
+This directory contains the **canonical OpenAPI v3 specification** for OpaqueInk core Lambda endpoints.
+
+## Ownership
+
+**This specification is owned by `opaqueink_infra` and is the single source of truth for API contracts.**
+
+- API Gateway routes are generated from this specification
+- Terraform uses this spec to configure API Gateway integrations
+- `opaqueink_core` consumes this spec but does not own it
+- All API changes must be made here first, then propagated to implementations
+
+## API URL Configuration
+
+**⚠️ IMPORTANT: The API server URL is configured in `openapi.yaml` under the `servers` section.**
+
+To update the API Gateway URL, edit the `servers` section in `openapi.yaml`:
+
+```yaml
+servers:
+  - url: https://YOUR-API-GATEWAY-URL/prod
+    description: Production API Gateway
+```
+
+The Scalar documentation build script automatically reads this URL from the OpenAPI spec, so updating it here will update the documentation as well.
+
+**Current API URL:** `https://4rh4k08rih.execute-api.us-east-2.amazonaws.com/prod`
+
+## Structure
+
+- **`openapi.yaml`** - Complete OpenAPI v3 specification with inline component references
+- **`components/`** - Modular component definitions (for maintainability, but consolidated into openapi.yaml for API Gateway)
+  - `schemas.yaml` - Data model schemas
+  - `responses.yaml` - Standard response definitions
+  - `security.yaml` - Security scheme definitions
+- **`package.json`** - Node.js dependencies for validation and deployment
+
+## Building and Validation
+
+### Install Dependencies
+
+```bash
+cd api
+npm install
+```
+
+### Validate the Specification
+
+**Using basic validation:**
+```bash
+npm install
+npm run validate-basic
+# or directly:
+node validate-basic.js
+```
+
+**Using the validation script** (includes multiple fallbacks):
+```bash
+chmod +x validate.sh
+./validate.sh
+```
+
+### Build Documentation
+
+```bash
+npm run build-docs
+```
+
+This builds the Scalar API documentation with interactive "Try-It-Out" functionality.
+
+### Deploy Documentation
+
+```bash
+export S3_BUCKET_NAME="your-bucket-name"
+export CLOUDFRONT_DISTRIBUTION_ID="your-distribution-id"
+npm run deploy-docs
+```
+
+This builds and deploys the documentation to S3/CloudFront.
+
+## Integration with API Gateway
+
+The `openapi.yaml` file uses `x-amazon-apigateway-*` extensions to define:
+
+- Lambda integrations (`x-amazon-apigateway-integration`)
+- Authentication configuration
+- Request/response mappings
+- CORS behavior
+
+Terraform in `../api_gateway/` imports this specification to configure API Gateway.
+
+## API Versioning
+
+**⚠️ HARD REQUIREMENT: All new endpoints MUST be versioned using `/v1/` path prefix.**
+
+See [API_VERSIONING.md](API_VERSIONING.md) for the complete versioning strategy and requirements.
+
+**Quick Reference:**
+- ✅ New endpoint: `/v1/orgs/{orgId}/members`
+- ❌ Missing version: `/orgs/{orgId}/members` (not allowed for new endpoints)
+
+## Adding New Endpoints
+
+1. **⚠️ Ensure path includes `/v1/` prefix** (see [API_VERSIONING.md](API_VERSIONING.md))
+2. **Add the path definition** to `openapi.yaml` under `paths:`
+3. **Add the Lambda integration** using `x-amazon-apigateway-integration` extension
+4. **Add schemas** to `components/schemas` if needed
+5. **Add responses** using component references (e.g., `$ref: '#/components/responses/Unauthorized'`)
+6. **Run validation**: `npm run validate-basic`
+7. **Update Terraform** in `../api_gateway/` to reference the new Lambda function
+
+## Editing Guidelines
+
+- **⚠️ Versioning**: All new endpoints MUST use `/v1/` path prefix (see [API_VERSIONING.md](API_VERSIONING.md))
+- **Operation IDs** must be unique and descriptive (use kebab-case)
+- **All endpoints** require Bearer JWT authentication (defined globally)
+- **Error responses** should use component references from `components/responses`
+- **Schemas** should be defined in `components/schemas` and referenced
+- **Tags** should be used consistently to group related operations
+
+## Publishing to npm
+
+This package is published to the public npm registry as `@inklok/api-spec` so `opaqueink_core` and other repos can consume it for codegen and type generation.
+
+- **Manual publish:** See [PUBLISH.md](PUBLISH.md) for setup and `npm publish` instructions
+- **CI publish:** Create a GitHub Release to trigger `.github/workflows/publish-api-spec.yml`
+- **Consuming:** `npm install @inklok/api-spec`
+
+## Reference
+
+- [OpenAPI 3.0 Specification](https://swagger.io/specification/)
+- [API Gateway OpenAPI Extensions](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-swagger-extensions.html)
+- [Scalar API Reference](https://github.com/scalar/scalar)

package/components/responses.yaml

@@ -0,0 +1,36 @@
+components:
+  responses:
+    BadRequest:
+      description: Bad request
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    
+    Unauthorized:
+      description: Unauthorized - Missing or invalid Bearer token
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    
+    Forbidden:
+      description: Forbidden - Insufficient role permissions
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    
+    NotFound:
+      description: Resource not found
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+    
+    InternalServerError:
+      description: Internal server error
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'

package/components/schemas.yaml

@@ -0,0 +1,55 @@
+components:
+  schemas:
+    Error:
+      type: object
+      description: Error response
+      properties:
+        error:
+          type: string
+          description: Error message
+        message:
+          type: string
+          nullable: true
+          description: Additional error details
+    
+    OrkMetadata:
+      type: object
+      description: Organization Root Key metadata
+      properties:
+        PK:
+          type: string
+          description: Partition key (ORG#{orgId})
+        SK:
+          type: string
+          description: Sort key (ORK#{orkId})
+        orkId:
+          type: string
+          description: Unique ORK identifier
+        alias:
+          type: string
+          description: KMS alias for the key
+        status:
+          type: string
+          enum:
+            - ACTIVE
+            - INACTIVE
+          description: ORK status
+        createdAt:
+          type: string
+          format: date-time
+          description: Creation timestamp
+        lastRotatedAt:
+          type: string
+          format: date-time
+          nullable: true
+          description: Last rotation timestamp
+        staleWrappedKeyCount:
+          type: integer
+          description: Count of keys wrapped by this ORK that are now stale
+        kmsKeyArn:
+          type: string
+          description: KMS key ARN
+        rotatedFrom:
+          type: string
+          nullable: true
+          description: Previous ORK identifier (if rotated)

package/components/security.yaml

@@ -0,0 +1,9 @@
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+      bearerFormat: JWT
+      description: |
+        Bearer JWT token for internal authorization.
+        Token should be included in the Authorization header as: "Bearer <token>"