4.5.bThree-layer defense for browser → Lambda

1. Why three layers, not one

Single-layer auth is fragile because one bug breaks everything. The substrate already enforces this at the network layer: Network Firewall blocks egress, DNS Firewall blocks resolution, VPC endpoint policies block service-level calls. Three independent enforcement layers, three different teams, three different failure modes.

At the app layer we had only one: in-function JWT validation. That meant:

• If the JWT verifier had a bug, the API was open.
• If a developer accidentally checked-in a route without auth, the API was open.
• If the Lambda dependency packaging broke (which actually happened — aws-jwt-verify was missing for a day), the function crashed at module-load and silently failed open in a different way.

The SCP rejection forced us to add two more layers above the application. The result is the doctrine we should have started with: three independent layers, three different operator concerns.

2. Layer 1: AWS Org SCP

3. Layer 2: CloudFront Origin Access Control for Lambda

4. Layer 3: Application JWT validation

5. Full request flow

One signed-in user clicking a tab in the obs vibe app, all the way through:

Three checkpoints, three different teams, three different failure messages. Easy to triage which layer rejected by looking at the response.

6. The OAC + Authorization header conflict

Industry-standard fix: pick a different header for the application's auth token. We use X-Auth-Token. The SPA's fetch() sends:

headers: {
  'X-Auth-Token': `Bearer ${getAccessToken()}`,
}

And Lambda reads:

const authHeader =
  event.headers?.['x-auth-token'] ||
  event.headers?.['X-Auth-Token'] || '';

The Lambda Function URL CORS configuration must include x-auth-token in allow_headers; AWS strips any unallowed header before forwarding. For symmetry we also include content-type for POST bodies.

7. Failure modes — what each layer catches

The right-most column is the operator's signal — the shape of the failure tells you which layer rejected and which team should triage. A generic 403 with the AWS error message means layer 2; a JSON 401 means layer 3; a Terraform apply error means layer 1.

8. Reusable for vibe apps 2 and 3

This pattern is the canonical browser-to-Lambda design for every future vibe app. The decisions made here do not need to be re-made:

• Lambda Function URL: always AuthType = AWS_IAM. Never NONE. The org SCP enforces this regardless.
• CloudFront origin for Lambda: always use an OAC with origin_access_control_origin_type = "lambda". Per-distribution OAC; do not share OACs across distributions.
• Lambda resource policy: always include the cloudfront.amazonaws.com service principal with both lambda:InvokeFunctionUrl and lambda:InvokeFunction, each scoped by AWS:SourceArn to the specific distribution. AWS docs only mention the first; the second is required in practice.
• JWT carrier: always X-Auth-Token. Never Authorization. CORS allow_headers must include x-auth-token.
• Function URL CORS allow_methods: only GET and POST (each method name must be ≤ 6 chars by AWS validation, so OPTIONS is auto-handled and never listed).
• Function URL CORS allow_origins: ["*"]. The defense-in-depth means Origin enforcement is not the right boundary here; OAC and JWT are.

The vibecode SDK will ship a module template (vibecode/sdk/app-template/browser-lambda.tf) that wires all of this once. Future vibe apps consume the template; they do not redo the decisions.

9. Integration with the Vibe Code SDK

The browser-to-Lambda pattern is captured in MODULES.md as part of the vibecode SDK roadmap. Specifically:

• vibecode/sdk/app-template/browser-lambda.tf — Terraform module that takes (app name, lambda source dir, JWT issuer config) and emits a complete browser-to-Lambda stack: CloudFront distribution, OAC for both S3 and Lambda, Function URL with AWS_IAM auth, Lambda resource policy, IAM execution role with permission boundary, CloudWatch log group on the correct governance CMK. Wires Step.4.5.a (data governance grid) and Step.4.5.b (three-layer defense) doctrines into one consumable.
• vibecode/sdk/lambda/jwt.ts — Lambda runtime helper that reads X-Auth-Token, calls aws-jwt-verify with the discovered client ID, and exposes the parsed claims (including cognito:groups) to the route handler. Standardizes the application-layer auth check.
• vibecode/sdk/spa/auth-fetch.ts — browser-side helper that wraps fetch() with the X-Auth-Token header, token-expiry checks, and signOut-on-401 semantics. Standardizes the browser-side auth-aware client.

Future vibe apps consume the template by declaring an app_name, a governance_cell (from Step.4.5.a), and a routes manifest. The substrate handles the rest.

10. Doctrine

This step encodes the substrate's defense-in-depth doctrine extended into the application layer. The substrate already enforced this at network and identity layers:

• Network: NFW for egress; DNS Firewall for resolution; VPC endpoint policies for service-level boundaries.
• Identity: KMS CMKs per trust zone; permission boundaries on every role; tier-based access grants.
• Application (this step): Org SCP at the resource-creation boundary; CloudFront OAC at the transport; Cognito JWT at the application.

The unifying principle: every layer enforces independently. No layer trusts that the layers above caught everything. This is the same principle that made the network layer work; we just extended it up the stack.

Three more doctrines specific to this step:

• The org SCP is the substrate, not an obstacle. When the org rejected our public Function URL, the right response was to discover the SCP-compliant pattern, not to ask for an exemption. The exemption path would have been an exception that other apps follow; the compliant pattern is reusable.
• Standardize the auth header at the SDK level. Every vibe app must use X-Auth-Token. Apps don't get to choose. The header name is part of the platform's API contract.
• Failure-mode legibility is a first-class doctrine. If layer 1 rejects, the operator should know it was layer 1. Same for 2 and 3. The shapes of the responses (Terraform error / AWS-issued 403 / JSON 401) are intentionally distinct.