mikoshi-construct 0.1.0

package/templates/stacks/http-contract/contracts/api/openapi.yaml.eta

@@ -0,0 +1,62 @@
+openapi: 3.1.0
+info:
+  title: {{projectName}} API
+  version: 0.1.0
+  description: What this service promises to its consumers. API changes start here; the implementation conforms to the contract and consumers read the generated types.
+security:
+  - {}
+servers:
+  - url: /
+    description: Same origin. Local development serves the contract on the port PORT names, 3000 by default.
+tags:
+  - name: public
+    description: Anonymous endpoints.
+paths:
+  /health:
+    get:
+      operationId: getHealth
+      tags: [public]
+      summary: Liveness
+      responses:
+        '200':
+          description: The service is up.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthResponse'
+        '503':
+          description: A dependency did not answer.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/HealthResponse'
+        default:
+          description: Unexpected error.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+components:
+  schemas:
+    HealthResponse:
+      type: object
+      additionalProperties: false
+      required: [status, service, time]
+      properties:
+        status:
+          type: string
+          enum: [ok, error]
+        service:
+          type: string
+        time:
+          type: string
+          format: date-time
+    ErrorResponse:
+      type: object
+      additionalProperties: false
+      required: [error, message]
+      properties:
+        error:
+          type: string
+        message:
+          type: string

package/templates/stacks/http-contract/package.json.eta

@@ -0,0 +1,13 @@
+{
+  "name": "{{projectName}}",
+  "scripts": {
+    "contracts:lint": "redocly lint",
+    "contracts:types": "node scripts/contracts/types.mjs",
+    "contracts:check": "pnpm contracts:lint && node scripts/contracts/types.mjs --check",
+    "quality": "pnpm contracts:check && pnpm composition:check && pnpm lint && pnpm typecheck && pnpm test"
+  },
+  "devDependencies": {
+    "@redocly/cli": "^2.52.0",
+    "openapi-typescript": "^7.13.0"
+  }
+}

package/templates/stacks/http-contract/redocly.yaml.eta

@@ -0,0 +1,8 @@
+apis:
+  {{projectName}}@v1:
+    root: {{contractPath}}
+extends:
+  - recommended
+rules:
+  operation-4xx-response: off
+  info-license: off

package/templates/stacks/http-contract/scripts/contracts/types.mjs.eta

@@ -0,0 +1,20 @@
+import { readFileSync, writeFileSync } from 'node:fs'
+import process from 'node:process'
+import { pathToFileURL } from 'node:url'
+import openapiTS, { astToString } from 'openapi-typescript'
+
+const CONTRACT = '{{contractPath}}'
+const OUTPUT = '{{contractTypesOutput}}'
+
+const generated = astToString(await openapiTS(pathToFileURL(CONTRACT)))
+
+if (process.argv.includes('--check')) {
+  const committed = readFileSync(OUTPUT, 'utf8')
+  if (committed !== generated) {
+    console.error(`${OUTPUT} is out of date with ${CONTRACT}; run pnpm contracts:types`)
+    process.exit(1)
+  }
+}
+else {
+  writeFileSync(OUTPUT, generated)
+}

package/templates/stacks/http-contract/scripts/tests/contracts/security.test.ts.eta

@@ -0,0 +1,86 @@
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+import { parse } from 'yaml'
+
+interface SchemaNode {
+  $ref?: string
+  additionalProperties?: boolean | SchemaNode
+}
+
+interface MediaTypes {
+  content?: Record<string, { schema: SchemaNode }>
+}
+
+interface Operation {
+  operationId: string
+  security?: Array<Record<string, unknown>>
+  requestBody?: MediaTypes
+  responses?: Record<string, MediaTypes>
+}
+
+interface ContractDocument {
+  paths: Record<string, Record<string, Operation>>
+  components: { schemas: Record<string, SchemaNode> }
+}
+
+const contract = parse(readFileSync(new URL('../../../{{contractPath}}', import.meta.url), 'utf8')) as ContractDocument
+
+const PROTECTED_PREFIXES = ['/v1/admin', '/v1/me']
+
+function operations(prefix: string): Array<{ route: string, method: string, operation: Operation }> {
+  return Object.entries(contract.paths)
+    .filter(([route]) => route.startsWith(prefix))
+    .flatMap(([route, methods]) => Object.entries(methods).map(([method, operation]) => ({ route, method, operation })))
+}
+
+function resolveSchema(schema: SchemaNode): SchemaNode {
+  return schema.$ref == null
+    ? schema
+    : resolveSchema(contract.components.schemas[schema.$ref.replace('#/components/schemas/', '')])
+}
+
+function jsonRequestBodies(): Array<{ route: string, method: string, schema: SchemaNode }> {
+  return Object.entries(contract.paths).flatMap(([route, methods]) =>
+    Object.entries(methods).flatMap(([method, operation]) => {
+      const schema = operation.requestBody?.content?.['application/json']?.schema
+      return schema == null ? [] : [{ route, method, schema: resolveSchema(schema) }]
+    }))
+}
+
+function jsonResponseBodies(): Array<{ route: string, method: string, status: string, schema: SchemaNode }> {
+  return Object.entries(contract.paths).flatMap(([route, methods]) =>
+    Object.entries(methods).flatMap(([method, operation]) =>
+      Object.entries(operation.responses ?? {}).flatMap(([status, response]) => {
+        const schema = response.content?.['application/json']?.schema
+        return schema == null ? [] : [{ route, method, status, schema: resolveSchema(schema) }]
+      })))
+}
+
+function requires(operation: Operation, scheme: string): boolean {
+  const schemes = operation.security ?? []
+  return schemes.length > 0 && schemes.every(entry => scheme in entry)
+}
+
+describe('security invariants stated by the contract', () => {
+  it('declares every operation with an operationId', () => {
+    for (const { route, method, operation } of operations('/'))
+      expect({ route, method, operationId: typeof operation.operationId }).toEqual({ route, method, operationId: 'string' })
+  })
+
+  it('requires a bearer session on every operation under a protected prefix', () => {
+    for (const prefix of PROTECTED_PREFIXES) {
+      for (const { route, method, operation } of operations(prefix))
+        expect({ route, method, bearer: requires(operation, 'bearer') }).toEqual({ route, method, bearer: true })
+    }
+  })
+
+  it('closes every documented JSON request body, so no write can set a field the contract does not expose', () => {
+    for (const { route, method, schema } of jsonRequestBodies())
+      expect({ route, method, closed: schema.additionalProperties }).toEqual({ route, method, closed: false })
+  })
+
+  it('closes every documented JSON response body, so no response can leak a field the contract does not expose', () => {
+    for (const { route, method, status, schema } of jsonResponseBodies())
+      expect({ route, method, status, closed: schema.additionalProperties }).toEqual({ route, method, status, closed: false })
+  })
+})