Shared Lambda Interface

Plan Metadata

• Plan type: plan
• Parent plan: N/A
• Depends on: N/A
• Status: documentation

System Intent

• What is being built: Shared API lambda invoker that can be used to apply auth and standardize input and output and simplify core functionality.
• Primary consumer(s): Python API lambda handlers.
• Boundary (black-box scope only): Input event parsing, auth header/token handling, handler invocation contract, and normalized response envelopes including preflight and error behavior.

Stage Gate Tracker

• [x] Stage 1 Mermaid approved
• [x] Stage 2 I/O contracts approved
• [x] Stage 3 pseudocode approved or skipped

1. Mermaid Diagram

Reference: .agent/skills/create-mermaid-diagram/SKILL.md

flowchart TD
  A[lambda_handler] -->|event context settings handler| B[invoke_lambda - layers/shared/python/shared/lambda_helpers.py]
  B -->|optional CORS preflight path on OPTIONS| C[maybe_handle_cors_preflight - layers/shared/python/shared/lambda_helpers.py]
  C -->|continue request lifecycle| D[maybe_require_auth_context - layers/shared/python/shared/lambda_helpers.py]
  D -->|parse request payload| E[parse_json_event_body - layers/shared/python/shared/lambda_helpers.py]
  E -->|payload and optional auth| F[handler - layers/shared/python/shared/lambda_helpers.py]
  F -->|return normalized success payload| G[build_standard_response - layers/shared/python/shared/lambda_helpers.py]
  D -->|auth validation failure| H[build_error_response - layers/shared/python/shared/lambda_helpers.py]
  F -->|application or unexpected error| H

  classDef unchanged fill:#d3d3d3,stroke:#666,stroke-width:1px;
  class A,B,C,D,E,F,G,H unchanged;

2. Black-Box Inputs and Outputs

Global Types

Define shared types used in the invoke_lambda integration contract.

LambdaInvokeInput {
  event: map<string, any> (API Gateway-style event; body may be object, JSON string, or omitted)
  context: any (lambda context)
  settings: LambdaSettings
  handler: function(payload, auth?) -> object
  require_auth_context: boolean (default true)
}

LambdaSettings {
  lambda_name: string (required)
}

AuthContext {
  user_id: string (required; Cognito subject)
  token_use: string (expected access)
  claims: map<string, any>
}

SuccessEnvelope {
  statusCode: 200
  headers: map<string, string>
  body: {
    success: true
    data: object
  }
}

TypedErrorEnvelope {
  statusCode: number
  headers: map<string, string>
  body: {
    success: false
    code: string
    message: string
  }
}

GenericErrorEnvelope {
  statusCode: 500
  headers: map<string, string>
  body: {
    success: false
    message: string
  }
}

PreflightResponse {
  statusCode: 200
  headers: map<string, string>
  body: ""
}

Flow: main/server/layers/shared/python/shared/lambda_helpers.py.invoke_lambda, main/server/tests/unit/test_invoke_lambda.py, main/server/tests/unit/test_auth_helpers.py

3. Pseudocode for Critical Flows

• Flow name:: invoke_lambda request lifecycle

  read settings.lambda_name and fail fast if missing
  derive request metadata for logging
  if http_method == OPTIONS then return 200 with CORS headers and empty body
  parse payload from event body or root event
  if require_auth_context true then resolve auth context from bearer token
  inspect handler signature to decide one-arg or two-arg call
  invoke handler and return success envelope
  if AppError or AuthError occurs then return typed error envelope
  if any other exception occurs then return generic 500 envelope
  

• Flow name:: maybe_handle_cors_preflight

  read LOCAL_CORS_ORIGIN env value
  if http_method != OPTIONS then continue request lifecycle
  if http_method == OPTIONS then return {
    statusCode: 200
    headers: {
      Access-Control-Allow-Origin: LOCAL_CORS_ORIGIN
      Access-Control-Allow-Methods: DELETE,GET,OPTIONS,POST,PUT
      Access-Control-Allow-Headers: Content-Type,Authorization,X-Amz-Date,X-Api-Key,X-Amz-Security-Token,X-Encache-Client
    }
    body: ""
  }
  

• Flow name:: maybe_require_auth_context

  if require_auth_context is false then return auth_context=None
  read Authorization header (case-insensitive)
  require format "Bearer <jwt>" else raise AuthError AUTH_MISSING or AUTH_INVALID
  require env AWS_REGION, COGNITO_USER_POOL_ID, COGNITO_APP_CLIENT_ID else raise AUTH_CONFIG_MISSING
  fetch JWKS, select key by kid, verify JWT signature and issuer
  require token_use=access, client_id matches app client id, and sub exists
  return AuthContext { user_id=sub, token_use, claims }
  

• Flow name:: auth error mapping

  if auth function raises AuthError then invoke_lambda returns TypedErrorEnvelope (401 with error code and message)
  if jwks fetch or other non-AppError auth dependency fails then invoke_lambda returns GenericErrorEnvelope (500)
  

• Implementation notes: This plan documents existing behavior in lambda_helpers.py; downstream API plans should treat these envelopes and auth semantics as shared contracts.

4. Handoff to Related Plan Reconciliation

After all stages are approved, apply .agent/skills/reconcile-plans/SKILL.md to propagate contract updates across linked plans.