Authentication Module

Scenario

You maintain a TypeScript API with a dedicated authentication module.

Authentication handles:

• login;
• session creation;
• token verification;
• password hashing;
• logout.

Because authentication is security-sensitive, the team wants coding agents to preserve the existing security model rather than invent new authentication flows during unrelated tasks.

Repository Structure

api/
├── src/
│   ├── auth/
│   │   ├── auth-service.ts
│   │   ├── password.ts
│   │   ├── session.ts
│   │   └── token.ts
│   ├── middleware/
│   │   └── authenticate.ts
│   ├── routes/
│   │   └── auth.ts
│   └── users/
├── tests/
│   └── auth/
└── AGENTS.md

AGENTS.md

# Project Instructions

## Authentication

- Keep authentication logic inside the existing auth module.
- Use the existing authentication middleware for protected endpoints.
- Do not implement independent token parsing or session validation in feature modules.
- Preserve the established authentication flow unless the task explicitly changes it.

## Passwords

- Use the existing password hashing and verification helpers.
- Never store or log plaintext passwords.
- Do not introduce custom password hashing or cryptographic implementations.

## Tokens and Sessions

- Use the existing token and session utilities.
- Preserve current expiration and revocation behavior unless intentionally changing authentication policy.
- Do not log authentication tokens or session secrets.

## Errors

- Preserve existing authentication error behavior.
- Avoid exposing internal authentication details through client-facing errors.

## Testing

For authentication changes:

- test successful authentication;
- test invalid credentials;
- test expired or invalid sessions where relevant;
- run the existing auth test suite.

What This Does

This tells the agent that authentication has an established implementation boundary.

For example, a protected route should reuse:

authenticate middleware

rather than implementing something like:

const token = request.headers.authorization?.replace("Bearer ", "");

const user = decodeTokenManually(token);

inside every endpoint.

The repository already owns authentication through dedicated modules.

What This Does NOT Do

The file does not explain how JWTs, password hashing, or cryptography work.

It also does not prescribe a universal authentication architecture.

Another repository might use:

server sessions
OAuth
Supabase Auth
Auth0
Clerk
custom identity provider

The instructions should describe the authentication system that actually exists.

The file also does not say that authentication behavior can never change.

If the task explicitly introduces a new authentication mechanism, then changing the architecture may be appropriate.

Why These Instructions Matter

Security-sensitive code is a poor place for unnecessary parallel implementations.

Suppose the application already verifies sessions through:

authenticateRequest(request);

An agent might decide that decoding the token directly is simpler.

That can accidentally bypass:

expiration checks
revocation
issuer validation
audience validation
session state

that the existing helper performs.

The local implementation may appear correct while weakening the overall authentication model.

The instruction:

- Use the existing authentication middleware for protected endpoints.

reduces that risk.

Key Decisions

Centralize authentication behavior

Authentication rules should not be independently recreated across features.

Reuse security primitives

Password hashing, token validation, and session handling should use established libraries and repository helpers.

Protect sensitive values

Passwords, tokens, and session secrets should not appear in logs or error output.

Test failure paths

Authentication tests should not cover only:

valid credentials → success

They should also verify important rejection behavior.

Change authentication deliberately

Authentication architecture changes can affect the entire application.

They should be intentional rather than side effects of feature work.

When to Use This Pattern

Use this pattern when:

• the application has centralized authentication;
• multiple routes require authentication;
• tokens or sessions contain sensitive information;
• password handling exists;
• inconsistent authentication logic would create security risk.

The core principle is simple:

reuse the repository's authentication boundary instead of recreating security logic locally.