README

Biometric Scan App

A serverless biometric identity verification pipeline on AWS. The system accepts an ID image and a selfie, compares faces with Amazon Rekognition, and stores verification state in DynamoDB.

Python 3.13 AWS Lambda Amazon Rekognition DynamoDB S3 API Gateway Secrets Manager AWS SAM AWS WAF v2

Architecture Overview

Upload Subservice (API Lambda)

Exposes POST /upload, accepts base64 image payloads, stores images in S3, and triggers the verification worker asynchronously after selfie upload.

Verification Worker (Background Lambda)

Calls Rekognition CompareFaces and writes verification status and similarity score to DynamoDB.

AWS Resources (SAM)

The SAM template provisions:

One encrypted S3 bucket for uploaded images
One DynamoDB table (creativespark-onboarding-users)
One Secrets Manager secret for the API auth token
API Gateway with route POST /upload
API Gateway stage throttling (burst/rate limits)
AWS WAF v2 Web ACL - managed common protections, known bad input protections, and IP rate limiting
- Note: the managed SizeRestrictions_BODY sub-rule is set to Count because /upload accepts large base64 image payloads.
Two Lambda functions: cs-upload-subservice and cs-verify-worker

Authentication Model

Clients first request INIT_SESSION with a user_id.
The backend issues a short-lived signed session_token (5 minute TTL).
UPLOAD_ID, UPLOAD, and STATUS require session_token in request bodies.
Tokens are validated server-side with an HMAC signature derived from the Secrets Manager secret.
Temporary rollout compatibility: a static token fallback can be enabled only with ALLOW_LEGACY_STATIC_TOKEN=true. The secure default is disabled.

API Contract

Endpoint: POST /upload

Supported actions

INIT_SESSION - required: user_id. Returns session_token, expires_in.
UPLOAD_ID - required: session_token, user_id, id_image_base64.
UPLOAD - required: session_token, user_id, selfie_image_base64. Triggers the async verify worker.
STATUS - required: session_token, user_id. Returns status and similarity.

Notes: user_id must match ^[a-zA-Z0-9_\-]{3,64}$. CORS is currently restricted to https://app.joesparkman.com. If Rekognition processing fails, the worker writes a terminal ERROR status to DynamoDB to avoid indefinite PENDING states.

Frontend Configuration

frontend/config.js: set APP_CONFIG.API_URL to the deployed SAM API base URL (e.g. https://<api-id>.execute-api.<region>.amazonaws.com/Prod).
frontend/index.html: the app automatically requests a short-lived session token from the backend before upload.

Important security note: short-lived tokens reduce exposure, but browser-visible tokens are still bearer credentials. Production would add user authentication and issue scoped server-side sessions.

Deployment

Prerequisites: AWS CLI configured (aws configure) and the AWS SAM CLI installed.

sam build
sam deploy --guided

After deployment: copy the output ApiEndpoint value, update frontend/config.js's API_URL, and ensure the Secrets Manager secret contains the signing secret used by the session token system.

Security tuning knobs (template parameters)

ApiThrottleBurstLimit: default 40
ApiThrottleRateLimit: default 20
WafRateLimitPerIp: default 1200 requests per 5 minutes

Local / Integration Test Script

upload_subservice/test_api.py reads the local environment variable API_URL.

Security & Repository Hygiene

.env is ignored in .gitignore.
No secrets or real tokens are committed.

Open App Story Visual Diagram Back to Portfolio