@suss/contract-aws-apigateway 0.0.1

package/dist/index.js

@@ -0,0 +1,557 @@
+// src/http.ts
+import { restBinding as restBinding2 } from "@suss/behavioral-ir";
+
+// src/shared.ts
+import { restBinding } from "@suss/behavioral-ir";
+var FRAMEWORK = "apigateway";
+var PROTOCOL = "http";
+function throttleEnforces(throttle) {
+  const enforces = (v) => v !== void 0 && v > 0;
+  return enforces(throttle.burstLimit) || enforces(throttle.rateLimit);
+}
+function integrationCanTimeOut(integration) {
+  return integration.type !== "mock" && integration.type !== "unknown";
+}
+function integrationCanFail(integration) {
+  return integration.type !== "mock" && integration.type !== "unknown";
+}
+function buildCorsPreflightSummary(options) {
+  const { apiId, path, cors, sourceFile, extraMetadata } = options;
+  const ownerKey = `${apiId}:OPTIONS:${path}:cors`;
+  const headers = {
+    "Access-Control-Allow-Origin": {
+      type: "literal",
+      value: cors.allowOrigins.join(",")
+    },
+    "Access-Control-Allow-Methods": {
+      type: "literal",
+      value: cors.allowMethods.join(",")
+    }
+  };
+  if (cors.allowHeaders !== void 0 && cors.allowHeaders.length > 0) {
+    headers["Access-Control-Allow-Headers"] = {
+      type: "literal",
+      value: cors.allowHeaders.join(",")
+    };
+  }
+  if (cors.exposeHeaders !== void 0 && cors.exposeHeaders.length > 0) {
+    headers["Access-Control-Expose-Headers"] = {
+      type: "literal",
+      value: cors.exposeHeaders.join(",")
+    };
+  }
+  if (cors.allowCredentials === true) {
+    headers["Access-Control-Allow-Credentials"] = {
+      type: "literal",
+      value: "true"
+    };
+  }
+  if (cors.maxAge !== void 0) {
+    headers["Access-Control-Max-Age"] = {
+      type: "literal",
+      value: String(cors.maxAge)
+    };
+  }
+  const transition = {
+    id: `${ownerKey}:platform:204`,
+    conditions: [
+      {
+        type: "opaque",
+        sourceText: "aws:apigateway:cors-preflight",
+        reason: "externalFunction"
+      }
+    ],
+    output: {
+      type: "response",
+      statusCode: { type: "literal", value: 204 },
+      body: null,
+      headers
+    },
+    effects: [],
+    location: { start: 0, end: 0 },
+    isDefault: false,
+    confidence: { source: "derived", level: "high" },
+    metadata: {
+      source: "aws::apigateway::platform",
+      platform: "apiGateway",
+      causes: ["cors-preflight"],
+      ...cors.configRef !== void 0 ? { configRefs: [cors.configRef] } : {}
+    }
+  };
+  return {
+    kind: "handler",
+    location: {
+      file: `${sourceFile}:${ownerKey}`,
+      range: { start: 0, end: 0 },
+      exportName: null
+    },
+    identity: {
+      name: ownerKey,
+      exportPath: null,
+      boundaryBinding: restBinding({
+        transport: PROTOCOL,
+        method: "OPTIONS",
+        path,
+        recognition: FRAMEWORK
+      })
+    },
+    inputs: [],
+    transitions: [transition],
+    gaps: [],
+    confidence: { source: "derived", level: "high" },
+    metadata: {
+      apiId,
+      synthetic: "cors-preflight",
+      ...extraMetadata ?? {}
+    }
+  };
+}
+
+// src/transitions.ts
+function makeContribution(cause, configRef) {
+  if (configRef === void 0) {
+    return { cause };
+  }
+  return { cause, configRef };
+}
+function handlerTransition(args) {
+  return {
+    id: `${args.ownerKey}:integration:${args.statusCode}`,
+    conditions: [],
+    output: {
+      type: "response",
+      statusCode: { type: "literal", value: args.statusCode },
+      body: null,
+      headers: {}
+    },
+    effects: [],
+    location: { start: 0, end: 0 },
+    isDefault: false,
+    confidence: { source: "derived", level: "high" },
+    metadata: {
+      source: args.source,
+      ...args.configRef !== void 0 ? { configRef: args.configRef } : {}
+    }
+  };
+}
+function platformTransition(args) {
+  if (args.contributions.length === 0) {
+    return null;
+  }
+  const causes = unique(args.contributions.map((c) => c.cause));
+  const refs = args.contributions.map((c) => c.configRef).filter((r) => r !== void 0);
+  const predicate = {
+    type: "opaque",
+    sourceText: `aws:apigateway:status-${args.statusCode}`,
+    reason: "externalFunction"
+  };
+  return {
+    id: `${args.ownerKey}:platform:${args.statusCode}`,
+    conditions: [predicate],
+    output: {
+      type: "response",
+      statusCode: { type: "literal", value: args.statusCode },
+      body: null,
+      headers: {}
+    },
+    effects: [],
+    location: { start: 0, end: 0 },
+    isDefault: false,
+    confidence: { source: "derived", level: "high" },
+    metadata: {
+      source: "aws::apigateway::platform",
+      platform: "apiGateway",
+      causes,
+      ...refs.length > 0 ? { configRefs: refs } : {}
+    }
+  };
+}
+function unique(values) {
+  return Array.from(new Set(values));
+}
+
+// src/http.ts
+function httpApiToSummaries(config) {
+  const sourceFile = config.source ?? `aws-apigateway:${config.id}`;
+  const summaries = [];
+  for (const route of config.routes) {
+    const parsed = parseRouteKey(route.routeKey);
+    if (parsed === null) {
+      continue;
+    }
+    summaries.push(buildRouteSummary(route, parsed, config, sourceFile));
+  }
+  if (config.cors !== void 0) {
+    for (const path of uniquePaths(config.routes)) {
+      summaries.push(
+        buildCorsPreflightSummary({
+          apiId: config.id,
+          path,
+          cors: config.cors,
+          sourceFile,
+          extraMetadata: { apiVersion: "v2" }
+        })
+      );
+    }
+  }
+  return summaries;
+}
+function parseRouteKey(routeKey) {
+  const trimmed = routeKey.trim();
+  if (trimmed === "" || trimmed === "$default") {
+    return null;
+  }
+  const space = trimmed.indexOf(" ");
+  if (space < 0) {
+    return null;
+  }
+  const method = trimmed.slice(0, space).toUpperCase();
+  const path = trimmed.slice(space + 1).trim();
+  if (method === "" || path === "") {
+    return null;
+  }
+  return { method, path };
+}
+function buildRouteSummary(route, parsed, api, sourceFile) {
+  const ownerKey = route.name ?? `${api.id}:${parsed.method}:${parsed.path}`;
+  const transitions = [];
+  for (const code of route.integration.statusCodes) {
+    transitions.push(
+      handlerTransition({
+        ownerKey,
+        statusCode: code,
+        source: `aws::apigateway::integration.${route.integration.type}`,
+        configRef: route.integration.configRef
+      })
+    );
+  }
+  const platformByStatus = collectPlatformContributions(route, api);
+  for (const [status, contributions] of platformByStatus) {
+    const transition = platformTransition({
+      ownerKey,
+      statusCode: status,
+      contributions
+    });
+    if (transition !== null) {
+      transitions.push(transition);
+    }
+  }
+  if (transitions.length === 0) {
+    transitions.push({
+      id: `${ownerKey}:integration:default`,
+      conditions: [],
+      output: {
+        type: "response",
+        statusCode: null,
+        body: null,
+        headers: {}
+      },
+      effects: [],
+      location: { start: 0, end: 0 },
+      isDefault: true,
+      confidence: { source: "derived", level: "low" },
+      metadata: {
+        source: `aws::apigateway::integration.${route.integration.type}`
+      }
+    });
+  }
+  return {
+    kind: "handler",
+    location: {
+      file: `${sourceFile}:${ownerKey}`,
+      range: { start: 0, end: 0 },
+      exportName: null
+    },
+    identity: {
+      name: ownerKey,
+      exportPath: null,
+      boundaryBinding: restBinding2({
+        transport: PROTOCOL,
+        method: parsed.method,
+        path: parsed.path,
+        recognition: FRAMEWORK
+      })
+    },
+    inputs: [],
+    transitions,
+    gaps: [],
+    confidence: { source: "derived", level: "high" },
+    metadata: {
+      apiId: api.id,
+      apiVersion: "v2",
+      integrationType: route.integration.type,
+      http: {
+        declaredContract: {
+          framework: FRAMEWORK,
+          provenance: "independent",
+          responses: route.integration.statusCodes.map((statusCode) => ({
+            statusCode
+          }))
+        },
+        // Additive pointer to the code that implements this route (SAM
+        // Lambda proxy Handler), so a checker can correlate the declared
+        // route with the extracted handler summary carrying the same
+        // REST binding.
+        ...route.implementingHandler !== void 0 ? { implementingHandler: route.implementingHandler } : {}
+      }
+    }
+  };
+}
+function collectPlatformContributions(route, api) {
+  const buckets = /* @__PURE__ */ new Map();
+  const add = (status, contribution) => {
+    const existing = buckets.get(status);
+    if (existing === void 0) {
+      buckets.set(status, [contribution]);
+    } else {
+      existing.push(contribution);
+    }
+  };
+  const authorizer = resolveAuthorizer(route, api);
+  if (authorizer !== null) {
+    if (authorizer.identitySourceRequired !== false) {
+      add(401, makeContribution("authorization", authorizer.configRef));
+    }
+    add(403, makeContribution("authorization", authorizer.configRef));
+  }
+  const throttle = resolveThrottle(route, api);
+  if (throttle !== null && throttleEnforces(throttle)) {
+    add(429, makeContribution("throttle", throttle.configRef));
+  }
+  if (integrationCanTimeOut(route.integration)) {
+    add(
+      504,
+      makeContribution("integration-timeout", route.integration.configRef)
+    );
+  }
+  if (integrationCanFail(route.integration)) {
+    add(
+      502,
+      makeContribution("integration-failure", route.integration.configRef)
+    );
+  }
+  return buckets;
+}
+function resolveAuthorizer(route, api) {
+  if (route.authorizer === null) {
+    return null;
+  }
+  if (route.authorizer !== void 0) {
+    return route.authorizer;
+  }
+  return api.defaultAuthorizer ?? null;
+}
+function resolveThrottle(route, api) {
+  if (route.throttle !== void 0) {
+    return route.throttle;
+  }
+  return api.defaultThrottle ?? null;
+}
+function uniquePaths(routes) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const r of routes) {
+    const parsed = parseRouteKey(r.routeKey);
+    if (parsed === null || seen.has(parsed.path)) {
+      continue;
+    }
+    seen.add(parsed.path);
+    out.push(parsed.path);
+  }
+  return out;
+}
+
+// src/rest.ts
+import { restBinding as restBinding3 } from "@suss/behavioral-ir";
+function restApiToSummaries(config) {
+  const sourceFile = config.source ?? `aws-apigateway:${config.id}`;
+  const summaries = [];
+  for (const endpoint of config.endpoints) {
+    summaries.push(buildEndpointSummary(endpoint, config, sourceFile));
+  }
+  if (config.cors !== void 0) {
+    for (const endpoint of dedupeByPath(config.endpoints)) {
+      summaries.push(
+        buildCorsPreflightSummary({
+          apiId: config.id,
+          path: endpoint.path,
+          cors: config.cors,
+          sourceFile
+        })
+      );
+    }
+  }
+  return summaries;
+}
+function buildEndpointSummary(endpoint, api, sourceFile) {
+  const method = endpoint.method.toUpperCase();
+  const ownerKey = endpoint.name ?? `${api.id}:${method}:${endpoint.path}`;
+  const transitions = [];
+  for (const code of endpoint.integration.statusCodes) {
+    transitions.push(
+      handlerTransition({
+        ownerKey,
+        statusCode: code,
+        source: `aws::apigateway::integration.${endpoint.integration.type}`,
+        configRef: endpoint.integration.configRef
+      })
+    );
+  }
+  const platformByStatus = collectPlatformContributions2(endpoint, api);
+  for (const [status, contributions] of platformByStatus) {
+    const transition = platformTransition({
+      ownerKey,
+      statusCode: status,
+      contributions
+    });
+    if (transition !== null) {
+      transitions.push(transition);
+    }
+  }
+  if (transitions.length === 0) {
+    transitions.push({
+      id: `${ownerKey}:integration:default`,
+      conditions: [],
+      output: {
+        type: "response",
+        statusCode: null,
+        body: null,
+        headers: {}
+      },
+      effects: [],
+      location: { start: 0, end: 0 },
+      isDefault: true,
+      confidence: { source: "derived", level: "low" },
+      metadata: {
+        source: `aws::apigateway::integration.${endpoint.integration.type}`
+      }
+    });
+  }
+  return {
+    kind: "handler",
+    location: {
+      file: `${sourceFile}:${ownerKey}`,
+      range: { start: 0, end: 0 },
+      exportName: null
+    },
+    identity: {
+      name: ownerKey,
+      exportPath: null,
+      boundaryBinding: restBinding3({
+        transport: PROTOCOL,
+        method,
+        path: endpoint.path,
+        recognition: FRAMEWORK
+      })
+    },
+    inputs: [],
+    transitions,
+    gaps: [],
+    confidence: { source: "derived", level: "high" },
+    metadata: {
+      apiId: api.id,
+      integrationType: endpoint.integration.type,
+      http: {
+        // The integration's declared status codes (from MethodResponses
+        // in the CFN template) are the declared contract here. Platform-
+        // injected transitions (authorizer 401/403, throttle 429, etc.)
+        // come from SEPARATE config fields and so are independent from
+        // this contract — contract-consistency comparison is meaningful
+        // and will surface template-internal inconsistencies.
+        declaredContract: {
+          framework: FRAMEWORK,
+          provenance: "independent",
+          responses: endpoint.integration.statusCodes.map((statusCode) => ({
+            statusCode
+          }))
+        },
+        // Additive pointer to the code that implements this endpoint
+        // (SAM Lambda proxy Handler), so a checker can correlate the
+        // declared route with the extracted handler summary carrying the
+        // same REST binding.
+        ...endpoint.implementingHandler !== void 0 ? { implementingHandler: endpoint.implementingHandler } : {}
+      }
+    }
+  };
+}
+function collectPlatformContributions2(endpoint, api) {
+  const buckets = /* @__PURE__ */ new Map();
+  const add = (status, contribution) => {
+    const existing = buckets.get(status);
+    if (existing === void 0) {
+      buckets.set(status, [contribution]);
+    } else {
+      existing.push(contribution);
+    }
+  };
+  const authorizer = resolveAuthorizer2(endpoint, api);
+  if (authorizer !== null) {
+    if (authorizer.identitySourceRequired !== false) {
+      add(401, makeContribution("authorization", authorizer.configRef));
+    }
+    add(403, makeContribution("authorization", authorizer.configRef));
+  }
+  if (endpoint.apiKeyRequired === true) {
+    add(403, makeContribution("api-key", endpoint.configRef));
+  }
+  if (endpoint.requestValidation !== void 0) {
+    const v = endpoint.requestValidation;
+    if (v.body === true || v.params === true || v.headers === true) {
+      add(
+        400,
+        makeContribution(
+          "request-validation",
+          v.configRef ?? endpoint.configRef
+        )
+      );
+    }
+  }
+  const throttle = resolveThrottle2(endpoint, api);
+  if (throttle !== null && throttleEnforces(throttle)) {
+    add(429, makeContribution("throttle", throttle.configRef));
+  }
+  if (integrationCanTimeOut(endpoint.integration)) {
+    add(
+      504,
+      makeContribution("integration-timeout", endpoint.integration.configRef)
+    );
+  }
+  if (integrationCanFail(endpoint.integration)) {
+    add(
+      502,
+      makeContribution("integration-failure", endpoint.integration.configRef)
+    );
+  }
+  return buckets;
+}
+function resolveAuthorizer2(endpoint, api) {
+  if (endpoint.authorizer === null) {
+    return null;
+  }
+  if (endpoint.authorizer !== void 0) {
+    return endpoint.authorizer;
+  }
+  return api.defaultAuthorizer ?? null;
+}
+function resolveThrottle2(endpoint, api) {
+  if (endpoint.throttle !== void 0) {
+    return endpoint.throttle;
+  }
+  return api.defaultThrottle ?? null;
+}
+function dedupeByPath(endpoints) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const e of endpoints) {
+    if (seen.has(e.path)) {
+      continue;
+    }
+    seen.add(e.path);
+    out.push(e);
+  }
+  return out;
+}
+export {
+  httpApiToSummaries,
+  restApiToSummaries
+};

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@suss/contract-aws-apigateway",
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Generate suss behavioral summaries for AWS API Gateway resources (REST + HTTP API), independent of how they were deployed.",
+  "keywords": [
+    "suss",
+    "behavioral-summary",
+    "aws",
+    "api-gateway",
+    "apigateway"
+  ],
+  "license": "Apache-2.0",
+  "author": "Nimbus Cloud AI LLC",
+  "homepage": "https://github.com/nimbuscloud-ai/suss/tree/main/packages/contract/aws-apigateway#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nimbuscloud-ai/suss.git",
+    "directory": "packages/contract/aws-apigateway"
+  },
+  "bugs": {
+    "url": "https://github.com/nimbuscloud-ai/suss/issues"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@suss/behavioral-ir": "0.0.1"
+  },
+  "devDependencies": {
+    "tsup": "*",
+    "typescript": "*",
+    "vitest": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}