API Gateway Audio and Video Endpoints Authorization

AudioMetadataRequest {
  memory_id: string (required) — source_session_id or segment id
}

AudioMetadataResponse {
  presigned_url: string | null — null when processing is not yet complete
  duration_seconds: number
  processing_status: "pending" | "complete" | "failed"
}

StandardError {
  status: number (HTTP status)
  code: string (stable machine-readable code)
  message: string (human-readable summary)
}

# API Gateway route for POST /memories/audio-metadata
# MUST have explicit Auth: Authorizer: CognitoAuth in template.yaml Event properties
# Without it, SAM may create the route without an authorizer → 403 from API Gateway

getAuthContext(event):
  # API Gateway injects validated claims into requestContext.authorizer.claims
  # This avoids a JWKS fetch inside the VPC (no NAT gateway)
  agw_claims = event.requestContext.authorizer.claims
  if agw_claims.sub:
    return { user_id: agw_claims.sub, ... }
  # Fallback: verify JWT directly (local testing only)

implementation(payload, auth):
  memory_id = payload.memory_id
  segment = query WorldMMSegment WHERE user_id=auth.user_id AND source_session_id=memory_id
  if not segment: raise NotFoundError
  if not segment.source_session_id or segment.source_window_index is None:
    raise NotFoundError("AUDIO_NOT_FOUND")
  audio_key = "sessions/{source_session_id}/window_{source_window_index:03d}/audio.wav"
  if segment.processing_status == "complete":
    head_object(audio_key)  # raises 404 if missing
    presigned_url = generate_presigned_url(audio_key, ExpiresIn=3600)
  return { presigned_url, duration_seconds, processing_status }

VideoRequest {
  memory_id: string (required)
}

VideoResponse {
  presigned_url: string  — empty string ("") when processing_status != "complete"
  duration_seconds: number (30)
  frame_count?: number   — count of frame_*.jpg objects in S3; returned for both complete and non-complete responses when the segment has an s3_frames_key (always true in practice, since segments without one are filtered out before this response is built)
  processing_status: "complete" | "pending" | "failed"
}

StandardError {
  status: number (HTTP status)
  code: string (stable machine-readable code)
  message: string (human-readable summary)
}

implementation(payload, auth):
  segment = _find_visual_segment(payload.memory_id, auth.user_id)
  if not segment: raise NotFoundError("MEMORY_NOT_FOUND")

  processing_status = segment.processing_status or "pending"
  if processing_status != "complete":
    # Count frames without downloading (lets frontend show metadata)
    frame_count = count s3 objects at frames_dir/frame_* if s3_frames_key set
    return {
      presigned_url: "",
      duration_seconds: 30.0,
      processing_status: processing_status,
      frame_count: frame_count,  # omitted if None
    }

  # processing_status == "complete": download frames + audio, encode, upload, sign
  frames_dir = segment.s3_frames_key.rsplit("/", 1)[0]
  download all frame_*.jpg from S3 to tmpdir
  download audio.wav from S3 to tmpdir
  run FFmpeg: frames + audio → output.mp4 (libx264, aac, -shortest, timeout=90s)
  upload output.mp4 to temp/videos/<uuid>.mp4
  return {
    presigned_url: generate_presigned_url(temp_key, ExpiresIn=3600),
    duration_seconds: 30.0,
    frame_count: len(frame_keys),
    processing_status: "complete",
  }

# main/server/template.yaml, lines 64-69
Globals:
  Api:
    Auth:
      DefaultAuthorizer: CognitoAuth
      Authorizers:
        CognitoAuth:
          UserPoolArn: !Sub "arn:aws:cognito-idp:${AWS::Region}:${AWS::AccountId}:userpool/{{resolve:ssm:/encache/auth/user_pool_id}}"
      AddDefaultAuthorizerToCorsPreflight: false

# CURRENT (missing Auth — may not get CognitoAuth attached on first deploy)
Events:
  MemoriesAudio:
    Type: Api
    Properties:
      Path: /memories/audio
      Method: post
      # No Auth: block

  MemoriesAudioMetadata:
    Type: Api
    Properties:
      Path: /memories/audio-metadata
      Method: post
      # No Auth: block

# FIXED
Events:
  MemoriesAudio:
    Type: Api
    Properties:
      Path: /memories/audio
      Method: post
      Auth:
        Authorizer: CognitoAuth    # explicit — no ambiguity on first deploy

  MemoriesAudioMetadata:
    Type: Api
    Properties:
      Path: /memories/audio-metadata
      Method: post
      Auth:
        Authorizer: CognitoAuth    # explicit — no ambiguity on first deploy

Client → POST /memories/audio-metadata (Authorization: Bearer <cognito-id-token>)
  → API Gateway: validates token against Cognito User Pool
  → API Gateway: injects requestContext.authorizer.claims = { sub, token_use, ... }
  → Lambda invoked with enriched event
  → getAuthContext(): reads agw_claims.sub as user_id (no JWKS fetch needed inside VPC)
  → implementation(): queries WorldMMSegment WHERE user_id=sub AND source_session_id=memory_id
  → returns { presigned_url, duration_seconds, processing_status }

Auth:
  Authorizer: NONE