4. Add endpoints
Your endpoints go in src/routes/index.ts. Open it. It has one endpoint so far:
app.get("/api/hello", { preHandler: auth.requireAuth }, async (req) => {
return { hello: auth.context(req)!.user.email, database: db ? "connected" : "in-memory" };
});Three parts to notice:
preHandler: auth.requireAuthis a guard. Fastify runs it before your function, and it answers401if nobody's signed in. Your function only runs for signed-in users.auth.context(req)tells you who's calling:.userId,.user.email,.rolesand.permissions. It's always worked out on the server from the session, so the caller can't fake it.- Whatever you return is sent as JSON. You don't need
reply.sendunless you want a status other than200.
A public endpoint
Some endpoints don't need anyone to be signed in, like a status page. Leave the guard out. Add this above /api/hello:
// Anyone can call this one.
app.get("/api/about", async () => {
return { app: "notes", version: 1 };
});Save. The server restarts by itself. Try it without signing in:
curl localhost:3000/api/about{"app":"notes","version":1}An endpoint that reads what you send
Now one that takes a message in the request body and sends it back with your email. First import HttpError at the top of the file:
import { HttpError } from "../http/errors.ts";Then add the endpoint below /api/hello:
// Only signed-in users, with what they sent.
app.post("/api/echo", { preHandler: auth.requireAuth }, async (req) => {
const message = (req.body as { message?: unknown } | undefined)?.message;
if (typeof message !== "string" || message.length > 200) {
throw new HttpError(400, "VALIDATION_FAILED", "message must be text, at most 200 characters.");
}
return { from: auth.context(req)!.user.email, message };
});Never trust the body. Anyone can send anything, so check the type and the size before you use it. That's why the body is read as unknown first: TypeScript then makes you check it before you use it. Throwing an HttpError gives the caller the same error format SelfAuth uses everywhere, and the user never sees a stack trace.
Sign in again (the commands are in chapter 2), then:
curl "${H[@]}" localhost:3000/api/echo -d '{"message":"hi there"}'{"from":"maya@example.com","message":"hi there"}Check it worked
Send something that isn't text:
curl "${H[@]}" localhost:3000/api/echo -d '{"message":42}'{"error":{"code":"VALIDATION_FAILED","message":"message must be text, at most 200 characters.","requestId":"42914e74-c33f-47fe-902a-1b54bf3fc0df"}}And call it without a session. Here that means without -b jar:
curl -s -H 'Content-Type: application/json' -H 'X-SelfAuth-CSRF: 1' localhost:3000/api/echo -d '{"message":"hi"}'{"error":{"code":"UNAUTHENTICATED","message":"Authentication required.","requestId":"22d5a85d-d61c-46b4-9d90-19c10e955d51"}}Things to keep in mind
- Every endpoint that changes something needs the CSRF header. That's already true for
/api/echo. APOSTwithoutX-SelfAuth-CSRF: 1is refused before your code runs. The generated React and Vue clients send it for you. - Put routes under
/api. With a frontend, the development server forwards/apiand/authto Fastify, so these paths work from the browser without extra setup. - Want every route in a group guarded?
auth.protectedRoutes(app, "/api/admin")gives you a set of routes that are denied unless a guard explicitly allows each one, so a route you forget to guard is refused rather than open. The server API reference shows it. - When the file grows, move groups of routes into their own files. You'll do that for the notes in chapter 7.
If something went wrong
NOT_FOUND. The path is wrong, or the file didn't save. Check the server's terminal for a restart message.CSRF_FAILED. The request is aPOSTand the header is missing. Did you use"${H[@]}"?HttpError is not defined. Add the import at the top of the file.
Next: Add permissions