# Trap 1. There is no developer API key. Do not ask the human for one.

Read this before you write a line of code and before you ask the person for any credential.
Almost every agent that has worked in W3DS has, at some point, said a sentence like
*"paste your W3DS API key here and I'll continue."* There is nothing for the person to paste.
The sentence is not merely unhelpful — it sends a non-technical owner looking for a thing
that does not exist, and they come back an hour later convinced they did something wrong.

## What a platform actually gets, and from where

A platform's identity comes from **GitW3**, the W3DS-aware Git forge, and it arrives on its
own. When the repository is created, GitW3's publisher reserves a permanent **platform
eName**, provisions the **platform eVault** for it, and writes the eName back into
`.w3ds/platform.json`. The documentation is explicit about what it does *not* do:

> It does not create or expose a reusable platform private key. The permanent platform
> identity and its eVault are provisioned automatically without an application or
> deployment key.

So there is no application key, no client secret, no dashboard that mints one, and no human
step that produces one. If you find yourself needing a credential to proceed, the answer is
**a step in GitW3 that has not been completed yet** — not a secret the person is withholding.

## The one key that does exist, and when

Exactly one private key belongs to a running deployment: the **deployment key**, in the
`w3ds-deployment-key-v1` format (ECDSA P-256, SHA-256). It is created in the repository's
**Deploy** tab, and only after a chain of earlier steps:

```
repository created ──▶ platform eName provisioned ──▶ public application URL set
        ──▶ stable semantic release published (v0.1.0)
        ──▶ PPA certificate granted for that exact version
        ──▶ Deploy tab ──▶ deployment key generated in the browser
```

The browser downloads `w3ds-deployment-key.json` **once**. GitW3 keeps only the public half
and cannot recover the private half — not through the site, not through support. The rules
around that file are in `traps/02-gitw3-registration.md`, and they are absolute: never ask
for it, never accept it if it is sent, never commit it, never let it reach the frontend.
On the server it is referenced **by path**, e.g. `W3DS_DEPLOYMENT_KEY_FILE=/path/to/file`,
never pasted into an environment variable as content.

## How a deployment proves who it is: PP Auth

The deployment key is not a bearer token you attach to requests. It is the key you **sign a
fresh challenge with**, in a handshake called **PP Auth**:

```
deployment                                  verifier
  │  POST /pp-auth/challenge                   │
  ├────────────────────────────────────────────▶
  │  { nonce, audience, issuedAt, expiresAt }  │
  ◀────────────────────────────────────────────┤
  │  sign the canonical challenge payload      │
  │  POST /pp-auth/verify                      │
  │  { challenge, evidence, signature }        │
  ├────────────────────────────────────────────▶
  │  { ok, links[], claim }                    │
  ◀────────────────────────────────────────────┤
```

The verifier checks six links, each failing closed, and reports all six — possession of the
key, a human wallet's authorisation of that key for this platform and environment, bundle
integrity, version identity (derivable by UUIDv5 from the platform eName and version, so
there is nothing to spoof), release authorship, and the association's accreditation. If all
six hold it returns a **claim**: platform, deployment, version, certification level, and the
set of domains — intersected with what the release actually asked for, so a certificate
naming more than the submission requested cannot widen it.

The challenge is single-use and short-lived, and is spent the moment it is answered whether
or not the chain holds.

The signing payload forms are fixed byte-for-byte across three codebases, so do not
improvise them:

| Signed thing | Payload |
|---|---|
| Handshake challenge | `w3ds:pp-auth:v1:` + base64url(sha256(canonical challenge)) |
| Deployment attestation bundle | `gitw3:deployment:v1:` + base64url(sha256(`signedPayload`)) |
| Release submission | `gitw3:ppa:v1:` + base64url(sha256(`JSON.stringify(statement)`)) |
| Owner access policy | `w3ds:access-policy:v1:` + base64url(sha256(canonical statement)) |

The code is documented as `@metastate-foundation/auth/platform` — `answerChallenge` and
`authenticate` on the deployment side, `verifyDeploymentChain` and `verifyHandshake` on the
verifier side, `authorize` and `permittedDomains` for the gates. **But GitW3's own Deploy
page says PP-Auth SDK integration is "coming soon."** So:

- Check whether the package actually resolves before you depend on it. Say out loud what you
  found.
- **Do not invent** a package name, an endpoint, a token format, or a wire protocol to fill
  the gap. An invented handshake does not fail loudly; it fails in six months against a real
  verifier.
- Build the platform-authentication boundary as **one narrow server-side module** with a
  documented interface, so the real implementation drops in without touching feature code.
  Leave a `// TODO(w3ds): PP-Auth integration pending — see traps/01-access-model.md`.

## The legacy token, and why you must not go looking for one

Before PP Auth, `POST /platforms/certification` on the registry minted a year-long platform
token for any name a caller typed in, and a registry-signed token bypassed access control
outright. Existing tokens keep working. **The registry has stopped minting new ones.**

So a platform created today has no path to one, and an agent that tries to obtain one — or
that asks the human to find theirs — is working from an obsolete model. Two more things are
true even for platforms that still hold a legacy token:

- A valid registry-issued token satisfies only the *legacy* ACL path. **A record carrying an
  `_acl` policy is decided by that policy for every caller**, token or not. That bypass is
  exactly what a policy exists to close.
- Never design a feature around "signed by the platform vault." A provisioned platform
  vault's `/whois` returns an **empty** `keyBindingCertificates` array, so there is nothing
  to verify a platform signature against. Only an end user's wallet signature is evidence.
  See `reference/access-and-exposure.md`.

## Three gates, in order, each able only to narrow the previous one

This is the whole access model. Nothing else opens a record.

1. **The certificate.** Was this exact release assessed for this domain? A social platform
   certified for `social` and `communication` has no path to `finance` data — not because the
   eVault recognises it as a social platform, but because `finance` is not in its certificate
   and nothing it can present puts it there.
2. **The owner's access policy.** A signed statement by the eVault owner: `minimumLevel`,
   `reputationEngine` and `minimumReputation`, `allowedDomains`, `deniedDomains`. The newest
   statement for a subject is the one in force; an owner who has never set one is treated as
   requiring **L2**. A policy can only narrow a certificate, never widen it.
3. **The grants.** An `AccessGrant` names a grantee, a resource, and permissions written as
   `resource:Action` (`social:Read`, `finance:Write`). Grants are **deny by default** and
   **append-only** — withdrawing access marks the grant revoked while keeping the permissions
   it used to carry, so "your access was withdrawn" stays distinguishable from "you never had
   access."

**Certification is a trust statement, not a permission.** It says what a release was found to
be. The eVault stays sovereign and decides for itself what that is worth.

What this means for how you talk to the person: when the app cannot reach data, the honest
sentence is *"this version needs its PPA certificate before it may read that, and the data's
owner also has to permit it"* — followed by the specific GitW3 step. Never *"give me a key."*

## What you can do today, while none of that exists yet

For the whole of local development, and for the app's own data, the working rules are simple.

- **Every eVault call carries `X-ENAME: @<vault owner>`.** It is not a credential — it
  *selects which vault the query addresses*. A missing `X-ENAME` is the single most common
  cause of "nothing was found" and of 400s. See `reference/access-and-exposure.md`.
- **`storeMetaEnvelope` needs only `X-ENAME`** — no bearer token. So writing a new record to
  the signed-in person's own vault works from day one.
- **Other mutations go through the Access Guard** and may need an `Authorization: Bearer`
  credential; `updateMetaEnvelope` is the one you will meet first. Structure your eVault
  client so the credential is one injected value, obtained in one place. Do not sprinkle it.
- **Never ship whatever server-side credential you do hold to the browser.** A vault's
  resolved URI may even be plain `http://`, which an HTTPS page cannot call at all — so a
  thin server-side proxy is the way through, and that is also where any credential belongs.
- **The person's own identity is the credential that matters.** They sign in with their eID
  wallet; that signature is the only real boundary in the system. Build on it.

## The one API key in this ecosystem that is real

**Awareness-as-a-Service (AaaS)** issues keys of the form `aaas_…`, and they are genuine. You
need one only to query awareness **history** (`GET /api/packets`) or to manage subscriptions
by hand. Live webhook delivery does not need one: AaaS reconciles a catch-all subscription
for every platform in the registry, pointing at `<platform>/api/webhook`. So implement that
route first and see whether packets arrive before asking for anything.

If a key really is needed, the person gets it themselves, and you must not ask them to paste
it into a chat message:

> 1. Open `https://aaas.w3ds.metastate.foundation` and sign in with W3DS — scan the deeplink
>    with your eID wallet.
> 2. Submit an access application. An administrator has to approve it; this takes time and is
>    not something either of us can hurry.
> 3. Once approved, open your dashboard and create an API key. **It is shown exactly once.**
> 4. Put it straight into the application's secrets file yourself — I will tell you the file
>    and the variable name. Do not send it to me in a message.

See `traps/05-awareness-webhook.md` for the trap that makes a subscription look healthy while
delivering nothing.

## Checklist for this file

- [ ] Nowhere in your code, config, prompts or messages do you ask for a "W3DS API key",
      "developer key", or "platform token".
- [ ] The platform's identity comes from a GitW3 repository, and you can name the
      `.w3ds/platform.json` field where its eName lives.
- [ ] Platform authentication sits behind one narrow server-side module, with the PP-Auth
      boundary marked as pending rather than invented.
- [ ] Every eVault call carries `X-ENAME`.
- [ ] No credential of any kind reaches the browser bundle.
- [ ] When access is refused, the explanation you give names a gate (certificate, policy,
      grant) and a next step — not a missing key.
