agentleFS
Atlas-AuthorizationAtlas-Authorization/atlas-claude-skills/skills/atlas-verify-backend/SKILL.md

atlas-verify-backend

Skill0 starsChanged 42 days agoMITView on GitHub

Verify an Atlas (atlasauth.net) session token / JWT in a backend or API — use @atlasauth/backend (Node) or the per-language SDK (Rust atlasauth, atlas-java, atlas-go, atlas-backend Python, atlas-auth Ruby, atlas-php). Covers AtlasBackend.verify / authenticateRequest, the FAPI JWKS endpoint, the SessionClaims shape, and has()/protect() role/permission/plan gating. Use when protecting API routes, checking a Bearer token or __session cookie, or validating an Atlas JWT server-side.

  • Reads credentials
  • Installs packages

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    All pin RS256, enforce iss, and reject OP access tokens / id_tokens being replayed as sessions.

    line 67

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Verify an Atlas session on the backend

Atlas mints a short-lived RS256 session JWT signed by the instance's per-instance key. Backends verify it locally against the instance JWKS — no Atlas round-trip on the hot path. Keys are cached and refetched only on an unknown kid (rate-limited to protect the JWKS endpoint).

Key facts:

  • JWKS URL: https://<slug>-fapi.atlasauth.net/.well-known/jwks.json
  • Issuer (iss): https://<slug>-fapi.atlasauth.net — always pass it; an unchecked issuer accepts tokens from any instance.
  • Session JWT arrives as Authorization: Bearer <jwt> OR the __session cookie (header wins).
  • Secret key sk_… is for the Backend API, NOT for verifying session JWTs — don't ship it to verify sessions.

Node / TypeScript — @atlasauth/backend

import { AtlasBackend } from '@atlasauth/backend';

const atlas = new AtlasBackend({
  jwksUrl: process.env.ATLAS_JWKS_URL!,          // the FAPI /.well-known/jwks.json
  issuer: process.env.ATLAS_ISSUER!,             // https://<slug>-fapi.atlasauth.net
  // audience: process.env.ATLAS_INSTANCE_ID,    // optional (ins_… ) — pins aud, recommended
  // authorizedParties: ['https://app.example.com'], // optional azp allowlist
});

// verify a raw token
const result = await atlas.verify(token);
if (!result.ok) return res.status(401).end();     // result.reason: malformed|no_keys|invalid|unauthorized_party
const { claims, has, protect } = result;

// or verify straight from a request (reads Bearer header or __session cookie)
const r = await atlas.authenticateRequest(req);    // req.headers.get(name) OR a plain headers object

Framework middleware (same jwksUrl + issuer config):

  • Express: @atlasauth/express — requireAuth() / withAuth() middleware, reads req.auth.
  • Fastify: @atlasauth/fastify — register the plugin, use request.auth.
  • Hono: @atlasauth/hono — atlas() middleware, c.get('auth').
  • NestJS: @atlasauth/nestjs — AtlasGuard / @Auth() decorator.
  • Next.js: auth() / currentUser() from @atlasauth/nextjs/server.

Claims shape (SessionClaims)

iss, sub (user id), sid (session id), exp, iat; sv (session version), mfa; org context org_id, org_slug, org_role, org_permissions[]; entitlements pla (plan slug), fea[] (feature keys); act ({ sub } on impersonation only); email/external_id (only when the instance opts into session.includeEmailClaim).

Authorize with has() / protect()

if (!has({ role: 'admin' })) return res.status(403).end();
has({ permission: 'org:billing:manage' });
has({ plan: 'pro' });            // checks pla
has({ feature: 'exports' });     // checks fea
protect({ role: 'admin' });      // returns claims or throws ForbiddenError (map to 403)

Standalone helpers also exist: hasPermission(claims, 'x'), hasRole(claims, 'admin'), has(claims, cond), protect(claims, cond).

verifyOnline (the slow path)

For the rare irreversible op where a ~60s revocation window is unacceptable, call atlas.verifyOnline(token) (needs secretKey + bapiBaseUrl); it does a local verify PLUS POST /v1/tokens/verify and fails closed. Don't use it everywhere — it makes Atlas's uptime your uptime.

Per-language backend SDKs (same semantics / claim names)

  • Rust — crate atlasauth (atlasauth = "0.6"): AtlasBackend::new(...), local JWKS verify; also verifies end-user API keys (ak_…).
  • Go — go get github.com/Atlas-Authorization/atlas-go; verify via the SDK's session verifier.
  • Python — pip install atlas-backend; from atlas_backend import AtlasClient (management) + the session verifier against cached JWKS.
  • Java — Maven net.atlasauth:atlas-java; AtlasClient (management) + SessionVerifier (local JWKS, Java 17+).
  • Ruby — gem "atlas-auth"; Atlas::Client + local session verification (dep: jwt).
  • PHP — composer require atlas-auth/atlas-php; Atlas\Client + SessionVerifier (PSR-18, PHP 8.1+).

All pin RS256, enforce iss, and reject OP access tokens / id_tokens being replayed as sessions. For offline/CI tests, @atlasauth/backend/testing createTestIssuer() mints tokens against a static JWKS you pass as { jwks }.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.