# Trap 3. The application needs a public address before its first line of code

## Why `localhost` cannot work

W3DS sign-in works like this: the person approves the sign-in **in the wallet on their phone**,
and the wallet then calls your application over the network itself — it posts signed data to
you.

`http://localhost:3006` means "on this same machine". On the phone, that points at the phone.
The wallet knocks on an empty door, the application never learns that the person approved, and
the screen says *waiting for confirmation* forever.

This cannot be configured around. **You need an address reachable from the internet.** It is a
precondition of the first line of authentication code, not a deployment concern to settle
later.

## The development-time answer: a tunnel

A tunnel is a program that makes your local port reachable at a public address.

### Cloudflare (recommended: no account needed)

Install:

| System | Command |
|---|---|
| macOS | `brew install cloudflared` |
| Windows | `winget install --id Cloudflare.cloudflared` |
| Linux (deb) | download the package from `https://github.com/cloudflare/cloudflared/releases` |

Run it in its own terminal window, which has to stay open:

```bash
cloudflared tunnel --url http://localhost:3006
```

Substitute your own port if the API does not listen on 3006.

The output contains a line like:

```
https://random-words-here.trycloudflare.com
```

That is the application's public address.

### ngrok (alternative, needs a free account)

```bash
ngrok http 3006
```

The address, of the form `https://….ngrok-free.dev`, appears on the `Forwarding` line.

## What to do with the address

Write it into the application's configuration as the **base URL** and build the link the
wallet receives from it:

```ts
const baseUrl = process.env.PUBLIC_BASE_URL;  // https://….trycloudflare.com
const redirectUrl = new URL("/api/auth/login", baseUrl).toString();
const offer = `w3ds://auth?redirect=${redirectUrl}&session=${sessionId}&platform=<name>`;
```

**Check it yourself before you ask a person to try anything:**

```bash
curl -s -o /dev/null -w "%{http_code}\n" https://….trycloudflare.com/api/auth/offer
```

Expect `200`. A `502` means the tunnel points at the wrong port, or the application is not
running.

## Three things people trip over

**1. The address changes every time the tunnel restarts.** A free Cloudflare tunnel issues a
new random name each time. Restart it and you must update the environment variable and restart
the API, or the wallet keeps knocking at yesterday's address. Symptom: *it worked yesterday*,
and today "waiting for confirmation" forever.

**2. Frontend and API must share one public origin.** If the frontend is served from
`https://….trycloudflare.com` but calls `http://localhost:3006`, the phone's browser cannot
reach it. Either tunnel a port that serves both, or run two tunnels and configure the API
address explicitly.

**3. A tunnel is for development only.** As soon as the application moves to real hosting, its
domain becomes the base URL and the tunnel is switched off. See
`traps/06-deploy-to-a-server.md`.

## The check that closes this gate

The person picks up their **phone**, opens the public address in the phone's browser, and sees
the application's page. Not a description of the page in your words — the page itself, on their
own screen.

Until that has happened, moving on to eID sign-in is pointless.
