Step-up authentication for AI agents

  
Agent                MCP server              Web app (browser)
  |                       |                          |
  |-- delete_environment ->|                         |
  |                       |-- create approval        |
  |<- "needs approval" ---|   (pending, 5 min TTL)   |
  |                       |                          |
  |   [agent tells the user to open the link]        |
  |                       |                          |
  |                       |         <-- user opens --|
  |                       |            checkRecentAuth
  |                       |            stale -> AuthKit re-verify
  |                       |            user reviews + approves
  |                       |-- approval: approved ----|
  |                       |                          |
  |-- check_approval ---->|                          |
  |                       |-- verify + execute       |
  |<- "done" -------------|   (mark consumed)        |
  

  
mkdir mcp-server && cd mcp-server
npm init -y
npm install @modelcontextprotocol/server @modelcontextprotocol/express @modelcontextprotocol/node express jose zod
  

  
// src/auth.ts
import { createRemoteJWKSet, jwtVerify } from 'jose';
import type { NextFunction, Request, Response } from 'express';

const AUTHKIT_DOMAIN = process.env.AUTHKIT_DOMAIN!;
const MCP_URL = process.env.MCP_URL!;

const JWKS = createRemoteJWKSet(new URL(`${AUTHKIT_DOMAIN}/oauth2/jwks`));

const WWW_AUTHENTICATE = [
  'Bearer error="unauthorized"',
  'error_description="Authorization needed"',
  `resource_metadata="${MCP_URL}/.well-known/oauth-protected-resource"`,
].join(', ');

declare global {
  namespace Express {
    interface Request {
      userId?: string;
    }
  }
}

export async function bearerTokenMiddleware(req: Request, res: Response, next: NextFunction) {
  const token = req.headers.authorization?.match(/^Bearer (.+)$/)?.[1];

  if (!token) {
    return res
      .set('WWW-Authenticate', WWW_AUTHENTICATE)
      .status(401)
      .json({ error: 'No token provided.' });
  }

  try {
    const { payload } = await jwtVerify(token, JWKS, {
      issuer: AUTHKIT_DOMAIN,
      audience: MCP_URL,
    });

    // `sub` is the WorkOS user id. Everything downstream is scoped to it.
    req.userId = payload.sub;
    next();
  } catch {
    return res
      .set('WWW-Authenticate', WWW_AUTHENTICATE)
      .status(401)
      .json({ error: 'Invalid bearer token.' });
  }
}
  

  
// src/index.ts
import { createMcpExpressApp } from '@modelcontextprotocol/express';
import { NodeStreamableHTTPServerTransport } from '@modelcontextprotocol/node';
import { McpServer } from '@modelcontextprotocol/server';
import { bearerTokenMiddleware } from './auth.js';
import { registerTools } from './tools.js';

const MCP_URL = process.env.MCP_URL!;
const AUTHKIT_DOMAIN = process.env.AUTHKIT_DOMAIN!;

const app = createMcpExpressApp();

// Discovery. Unauthenticated by design: this is how clients find AuthKit.
app.get('/.well-known/oauth-protected-resource', (_req, res) =>
  res.json({
    resource: MCP_URL,
    authorization_servers: [AUTHKIT_DOMAIN],
    bearer_methods_supported: ['header'],
  }),
);

app.post('/mcp', bearerTokenMiddleware, async (req, res) => {
  const server = new McpServer({ name: 'acme-platform', version: '1.0.0' });
  registerTools(server, { userId: req.userId! });

  const transport = new NodeStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
  await server.connect(transport);
  await transport.handleRequest(req, res, req.body);
});

app.listen(8000);
  

  
// src/sensitive.ts

/**
 * Tools that cannot execute without a fresh human approval.
 * `maxAge` is the freshness window enforced in the browser, in seconds.
 * Use 0 for actions where "you authenticated two minutes ago" is not enough.
 */
export const SENSITIVE_TOOLS = {
  delete_environment: { maxAge: 0, label: 'Delete an environment and all of its data' },
  rotate_api_keys: { maxAge: 120, label: 'Rotate all API keys' },
  invite_admin: { maxAge: 120, label: 'Grant admin access to a new user' },
  send_broadcast: { maxAge: 120, label: 'Send an email to all users' },
} as const;

export type SensitiveTool = keyof typeof SENSITIVE_TOOLS;
  

  
// src/approvals.ts
import { createHash, randomUUID } from 'node:crypto';
import type { SensitiveTool } from './sensitive.js';

export type Approval = {
  id: string;
  userId: string;
  tool: SensitiveTool;
  args: Record<string, unknown>;
  argsHash: string;
  status: 'pending' | 'approved' | 'denied' | 'consumed';
  createdAt: Date;
  expiresAt: Date;
  approvedAt: Date | null;
  authenticatedAt: Date | null;
};

const TTL_MS = 5 * 60 * 1000;

/**
 * Stable hash of the tool arguments. Approval is bound to this value, so a
 * request approved for one set of arguments cannot be redeemed for another.
 */
export function hashArgs(args: Record<string, unknown>): string {
  const canonical = JSON.stringify(args, Object.keys(args).sort());
  return createHash('sha256').update(canonical).digest('hex');
}

export async function createApproval(
  userId: string,
  tool: SensitiveTool,
  args: Record<string, unknown>,
): Promise<Approval> {
  const now = new Date();

  return db.approvals.insert({
    id: randomUUID(),
    userId,
    tool,
    args,
    argsHash: hashArgs(args),
    status: 'pending',
    createdAt: now,
    expiresAt: new Date(now.getTime() + TTL_MS),
    approvedAt: null,
    authenticatedAt: null,
  });
}

/**
 * Atomically claim an approved request for execution. Returns null unless the
 * approval exists, belongs to this user, targets this tool, was approved for
 * exactly these arguments, and has not expired or been used.
 *
 * The status transition must be atomic. Two concurrent tool calls racing on the
 * same approval must not both win.
 */
export async function consumeApproval(
  id: string,
  userId: string,
  tool: SensitiveTool,
  args: Record<string, unknown>,
): Promise<Approval | null> {
  return db.approvals.updateOneWhere(
    {
      id,
      userId,
      tool,
      argsHash: hashArgs(args),
      status: 'approved',
      expiresAt: { gt: new Date() },
    },
    { status: 'consumed' },
  );
}
  

  
// src/tools.ts
import type { McpServer } from '@modelcontextprotocol/server';
import * as z from 'zod/v4';
import { createApproval, consumeApproval } from './approvals.js';
import { SENSITIVE_TOOLS } from './sensitive.js';

const APP_URL = process.env.APP_URL!;

export function registerTools(server: McpServer, ctx: { userId: string }) {
  server.registerTool(
    'delete_environment',
    {
      description:
        'Permanently delete an environment and all of its data. Requires human approval: ' +
        'call once to request approval, then call again with approvalId once the user has approved.',
      inputSchema: z.object({
        environmentId: z.string(),
        approvalId: z.string().optional(),
      }),
    },
    async ({ environmentId, approvalId }) => {
      const args = { environmentId };

      // Second call: the user has approved, so redeem it.
      if (approvalId) {
        const approval = await consumeApproval(approvalId, ctx.userId, 'delete_environment', args);

        if (!approval) {
          return {
            content: [
              {
                type: 'text',
                text:
                  'That approval is not valid for this request. It may have expired, already ' +
                  'been used, or been approved for different arguments. Request a new approval.',
              },
            ],
            isError: true,
          };
        }

        await platform.deleteEnvironment(environmentId);

        return {
          content: [{ type: 'text', text: `Environment ${environmentId} has been deleted.` }],
        };
      }

      // First call: pause and ask for a human.
      const approval = await createApproval(ctx.userId, 'delete_environment', args);
      const { label } = SENSITIVE_TOOLS.delete_environment;

      return {
        content: [
          {
            type: 'text',
            text: [
              `This action requires approval from the account owner: ${label}.`,
              '',
              'Ask the user to open this link and confirm. They will be asked to verify their',
              'identity before approving.',
              '',
              `${APP_URL}/approvals/${approval.id}`,
              '',
              'Do not retry automatically. Once the user says they have approved, call this tool',
              `again with approvalId="${approval.id}" and the same environmentId.`,
              'The approval expires in 5 minutes.',
            ].join('\n'),
          },
        ],
      };
    },
  );
}
  

  
// app/approvals/[id]/page.tsx
import { notFound, redirect } from 'next/navigation';
import { withAuth, checkRecentAuth } from '@workos-inc/authkit-nextjs';
import { SENSITIVE_TOOLS } from '@/lib/sensitive';
import { ApproveForm } from './approve-form';

export default async function ApprovalPage({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params;
  const { user } = await withAuth({ ensureSignedIn: true });

  const approval = await db.approvals.findById(id);

  // Do not distinguish "does not exist" from "belongs to someone else".
  if (!approval || approval.userId !== user.id) notFound();

  if (approval.status !== 'pending' || approval.expiresAt < new Date()) {
    return <Expired status={approval.status} />;
  }

  const { maxAge, label } = SENSITIVE_TOOLS[approval.tool];

  // The gate. If the user has not authenticated inside the window, send them
  // through AuthKit and bring them right back here.
  const { isStale } = await checkRecentAuth({ maxAge });

  if (isStale) {
    redirect(`/step-up?returnTo=${encodeURIComponent(`/approvals/${id}`)}&maxAge=${maxAge}`);
  }

  return (
    <main className="mx-auto max-w-lg p-8">
      <p className="text-sm text-gray-500">An AI assistant is requesting permission to:</p>
      <h1 className="mt-2 text-xl font-semibold">{label}</h1>

      <dl className="mt-6 rounded border border-gray-200 p-4 text-sm">
        {Object.entries(approval.args).map(([key, value]) => (
          <div key={key} className="flex justify-between gap-4 py-1">
            <dt className="text-gray-500">{key}</dt>
            <dd className="font-mono">{String(value)}</dd>
          </div>
        ))}
      </dl>

      <p className="mt-4 text-sm text-gray-500">
        Requested {approval.createdAt.toLocaleTimeString()}. Expires in 5 minutes.
      </p>

      <ApproveForm approvalId={id} />
    </main>
  );
}
  

  
// app/step-up/route.ts
import { getSignInUrl } from '@workos-inc/authkit-nextjs';
import { redirect } from 'next/navigation';
import type { NextRequest } from 'next/server';

export const GET = async (request: NextRequest) => {
  const params = request.nextUrl.searchParams;

  const requested = params.get('returnTo') ?? '/';
  const returnTo = requested.startsWith('/') && !requested.startsWith('//') ? requested : '/';

  const parsed = Number(params.get('maxAge'));
  const maxAge = Number.isInteger(parsed) && parsed >= 0 && parsed <= 900 ? parsed : 0;

  return redirect(await getSignInUrl({ maxAge, returnTo }));
};
  

  
// app/approvals/[id]/actions.ts
'use server';

import { checkRecentAuth, withAuth } from '@workos-inc/authkit-nextjs';
import { SENSITIVE_TOOLS } from '@/lib/sensitive';

export async function approve(approvalId: string) {
  const { user } = await withAuth({ ensureSignedIn: true });

  const approval = await db.approvals.findById(approvalId);
  if (!approval || approval.userId !== user.id) return { ok: false };
  if (approval.status !== 'pending' || approval.expiresAt < new Date()) return { ok: false };

  // Check again here. The page-level check decided what to render; this one
  // decides what happens. A user could sit on the page past the window.
  const { isStale, authenticatedAt } = await checkRecentAuth({
    maxAge: SENSITIVE_TOOLS[approval.tool].maxAge,
  });

  if (isStale) return { ok: false, reason: 'stale' as const };

  await db.approvals.update(approvalId, {
    status: 'approved',
    approvedAt: new Date(),
    authenticatedAt,
  });

  return { ok: true };
}

export async function deny(approvalId: string) {
  const { user } = await withAuth({ ensureSignedIn: true });
  await db.approvals.updateWhere({ id: approvalId, userId: user.id }, { status: 'denied' });
  return { ok: true };
}
  

  
User:  delete the staging-old environment

Agent: [calls delete_environment { environmentId: "env_staging_old" }]

       This action requires approval from the account owner. Please open
       https://app.example.com/approvals/8f3c... and confirm. You will be
       asked to verify your identity.

User:  [opens the link, gets challenged by AuthKit, sees exactly
        "Delete an environment and all of its data / environmentId: env_staging_old",
        clicks approve]

       approved

Agent: [calls delete_environment { environmentId: "env_staging_old",
                                   approvalId: "8f3c..." }]

       Environment env_staging_old has been deleted.