# Authentication
Every socket carries a **channel JWT**. This page is what the two authorizer
packages do with it on the way in, and what an authorizer can and cannot
promise. The token itself — how a player gets one, what its claims mean, how
long it lives — is settled by `docs/auth-game-contract.md` and
`services/auth/README.md` in the
[`service`](https://github.com/yingyeothon/service) repository.
```ts
import { createJwtRequestAuthorizer } from "@yingyeothon/lambda-authorizer-jwt";
```
**Reference:** [`lambda-authorizer`](../packages/lambda-authorizer/README.md), [`lambda-authorizer-jwt`](../packages/lambda-authorizer-jwt/README.md) — each carries its own `## Public API`, its
options and defaults, and its migration notes.
## Sign in from a game
`auth-client` implements config, login URL and nonce-checked redirect parsing,
provider credential exchange and token verification. It is the client half;
these authorizer packages remain the server half. `game-kit` adds the popup
login and optional host storage policy. See [auth-client](../packages/auth-client/README.md)
and [Game kit](game-kit.md). Remove callback fragments after reading them and
never treat local token decoding as signature verification.
## TOKEN or REQUEST is decided by the API, not by preference
```mermaid
flowchart TD
A{"which API?"}
A -->|"REST"| B["createAuthorizer, a TOKEN authorizer
or createRequestAuthorizer"]
A -->|"WebSocket $connect"| C["createRequestAuthorizer only"]
C --> D["a WebSocket API supports no other Lambda authorizer type"]
A -->|"WebSocket $default or $disconnect"| E["no authorizer at all"]
E --> F["the member was decided at $connect"]
```
`createJwtAuthorizer` is the TOKEN one: it also _issues_, exchanging a `Basic`
login for a freshly signed JWT. `createJwtRequestAuthorizer` only verifies —
a handshake has no response body to hand a token back through — so keep the
login exchange behind a REST endpoint.
## `$connect`, end to end
```mermaid
sequenceDiagram
participant C as client
participant AG as API Gateway $connect
participant AU as createJwtRequestAuthorizer
participant H as your $connect handler
C->>AG: Upgrade, Sec-WebSocket-Protocol bearer plus the JWT
AG->>AU: REQUEST event, result cache TTL 0
AU->>AU: read the credential from the subprotocol source
AU->>AU: verify the signature, then exp, and issuer and audience if pinned
alt verified
AU-->>AG: Allow, principalId, context memberId
AG->>H: requestContext.authorizer.memberId
H-->>C: 101, echoing only the subprotocol it selected
else bad signature, expired, wrong issuer or audience
AU-->>AG: throws Unauthorized, no policy at all
AG-->>C: 401
else wrong scheme, no exp, or an empty context
AU-->>AG: a Deny policy, with the context stripped
AG-->>C: 403
end
```
**A refusal takes one of two routes, and most take the first.** Anything the
verification throws — a bad signature, an expired token, the wrong `issuer` or
`audience`, a missing credential — is caught and re-thrown as `Unauthorized`, so
API Gateway never receives a policy at all. Only three cases actually build a
`Deny`: a scheme that is not `Bearer`, a token with no `exp`, and a
`buildContext` that returned nothing.
Either way the client cannot tell the two apart. Every refusal reaches a browser
as a close before open, which is why `maxHandshakeFailures` exists to stop it
retrying a dead token forever.
**A browser cannot set headers on a WebSocket handshake.** The credential
travels as `new WebSocket(url, ["bearer", token])`, which arrives as
`Sec-WebSocket-Protocol: bearer, ` — and the server **must echo the
subprotocol it selected** or the browser aborts. That is what `handleConnect`'s
`selectSubprotocol` is for.
**That callback is handed the raw credential.** With the arrangement above,
`offered` is `["bearer", ""]`. Never log it.
Verifying on a WebSocket `$connect`:
```ts
export const handler = createJwtRequestAuthorizer({
jwtSecret: process.env.JWT_SECRET_KEY!,
// Pin both. A signature proves who minted the token, not who for.
verifyOptions: { issuer: "yyt-auth/auth_0123", audience: "my-dungeon" },
});
```
Then read the verified identity in `$connect`, so the member id is never the
client's to choose:
```ts
export const connect = (event: APIGatewayProxyEvent) =>
handleConnect({
event,
context,
...prefixes,
queueTtlSeconds: 900,
resolveMemberId: (connecting) => {
const memberId: unknown =
connecting.requestContext.authorizer?.["memberId"];
return typeof memberId === "string" ? memberId : undefined; // fails closed
},
// A browser aborts unless the server echoes the subprotocol it selected.
selectSubprotocol: (offered) =>
offered.includes("bearer") ? "bearer" : undefined,
});
```
## Where the credential is read from
`AuthorizationSource` is **data**, not a callback:
`{ from: "header", name? }`, `{ from: "subprotocol" }`, or
`{ from: "queryString", name }` — where `name` is **required**, because there is
no conventional parameter to default to. The space is closed and enumerable, so
it is inspectable and trivially testable, and it mirrors the vocabulary API
Gateway already uses. `parseAuthorization` turns what was read into `Basic`,
`Bearer` or `Unknown`.
Prefer the subprotocol. A query string is written to access logs.
## Verification, not decoding
- **Require an expiry.** A token with no `exp` is denied; a bearer credential
that never expires makes every "the allow cannot outlive the credential"
guarantee vacuous. `requireExpiry: false` opts out deliberately.
- **Pin `issuer` and `audience` — nothing pins them for you.** The signature is
always verified; `issuer` and `audience` are checked only when you pass them
in `verifyOptions`, and the default passes neither. A valid signature proves
who minted a token, not who it was minted _for_, and **with a shared
symmetric secret every holder can mint any identity** — so the secret is a
signing capability, not a verification key.
- **An empty context is a refusal.** If `buildContext` returns `{}` the token is
denied rather than allowed with no identity: an authorizer whose job is to
establish who is calling must not say yes when it established nobody. The
default, `memberIdFromSubject`, publishes `{ memberId: claims.sub }` —
falling back to `claims.id`, which is what this package's own
`buildJWTPayload` default issues — and nothing else. That value also becomes
the `principalId`, which otherwise defaults to a constant, making every caller
look like the same one.
## The context is narrow on purpose
It stays with the connection and reaches `$connect`, `$default` and
`$disconnect` as `event.requestContext.authorizer`. It carries only strings,
numbers and booleans, so claims must be flattened.
Keep it small, because **`$context.authorizer.*` can be configured into access
logs**: a token or an email placed there is a token or an email in the logs. A
verified bearer token is never echoed back into the context — the caller already
has it. The one exception is the `Basic` exchange, where the JWT the authorizer
just issued is the only way the caller receives it; on an API using that
exchange, keep the authorizer context out of access logs.
**Strip the context from a `Deny`.** A refused request reaches the access log
too, and the reason an authorizer refused is usually more sensitive than the
reason it allowed.
## Set the `$connect` cache TTL to 0
`$connect` runs once per connection, so caching buys nothing and lets an allow
outlive the credential's expiry.
It has a second effect worth knowing: **identity sources are enforced only when
caching is on.** With caching enabled, every declared source must be present and
non-empty or API Gateway answers 401 without invoking your function; with it off
the function is invoked regardless. The TTL-0 recommendation and "declare only
the source your clients actually send" are the same decision seen twice.
## What an authorizer cannot do
**It cannot revoke an established connection.** Once the handshake succeeds, no
policy touches that socket again. Ejecting a player mid-game is the
application's job, through `Transport.drop`.
And refusing a message type is not authentication. `handleMessages` refuses
`enter` and `leave` from clients so `$default` cannot rebind a connection to
another member — but identity itself comes from the verified principal, which is
why `handleConnect` takes `resolveMemberId`. A resolver that returns `undefined`
rejects: an identity seam whose failure mode is "fall back to what the client
said" is not a seam.
## Read next
[The game actor § Who the connection speaks for](game-actor.md#who-the-connection-speaks-for)
for the other half of this, and [Logging](logging.md) for what must never reach
a log line.