Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

8.0 KB
Raw Blame
import { randomUUID } from "node:crypto";
import type { RateLimitDecision } from "./apiRateLimit.js";
import { parseOAuthScopes, statementsFromApiKeyPermissions, type ScopeStatements } from "./scopes.js";

/**
 * Shared bearer-credential resolution for the MCP gate and the REST guards.
 *
 * Leaf module: imports only scopes.js (a leaf) and node:crypto β€” never auth.js
 * β€” so the MCP layer and its tests can use it without loading the better-auth
 * init chain. Callers inject the verify/lookup dependencies.
 */

/** Canonical bearer parser. The gate and REST must agree, or a request that
 *  authenticates at one layer fails at the other. Mirrors the REST layer's
 *  historical `startsWith("Bearer ") ? substring(7) : null`. */
export function extractBearerToken(authorization: string | string[] | undefined): string | null {
  if (typeof authorization !== "string") {
    return null;
  }
  if (!authorization.startsWith("Bearer ")) {
    return null;
  }
  return authorization.substring(7) || null;
}

export { ORG_API_KEY_CONFIG_ID } from "@rybbit/shared";
import { ORG_API_KEY_CONFIG_ID } from "@rybbit/shared";

export interface ApiKeyVerification {
  valid: boolean;
  key?: { referenceId?: string | null; permissions?: unknown; configId?: string | null } | null;
  error?: { code?: string } | null;
}

export type OAuthTokenLookup = {
  userId?: string | null;
  accessTokenExpiresAt?: Date | string | null;
  scopes?: string | null;
} | null;

export interface BearerResolverDeps {
  verifyApiKey: (token: string) => Promise<ApiKeyVerification>;
  getOAuthSession: (token: string) => Promise<OAuthTokenLookup>;
  /**
   * Charge one request against the owner's burst bucket and daily quota.
   * Optional so tests and the MCP layer can resolve identities without a
   * limiter; when absent, no request is charged. Returning null means the
   * deployment is not metered (self-hosted), which is not a denial.
   */
  consumeRateLimit?: (identity: {
    userId?: string;
    organizationId?: string;
  }) => Promise<RateLimitDecision | null>;
}

export type BearerIdentityStatus = "valid" | "invalid" | "rate_limited" | "verify_error";

export interface BearerIdentity {
  status: BearerIdentityStatus;
  /** Set when the credential resolves to a person: user API key or OAuth token. */
  userId?: string;
  /** Set when the credential is an organization-owned API key. Exactly one of
   *  userId/organizationId is set on a valid identity. */
  organizationId?: string;
  /** null = unrestricted (legacy key / full OAuth grant); enforced by callers. */
  statements: ScopeStatements | null;
  /**
   * The rate-limit outcome for this request, carried so callers can report the
   * remaining budget in response headers. Present on rate_limited identities
   * too β€” that is where the retry-after comes from.
   */
  rateLimit?: RateLimitDecision;
}

export function isUsableOAuthToken(token: OAuthTokenLookup): token is NonNullable<OAuthTokenLookup> {
  if (!token?.userId) {
    return false;
  }
  // Defense in depth: reject expired tokens even if the lookup returned one.
  return !token.accessTokenExpiresAt || new Date(token.accessTokenExpiresAt).getTime() > Date.now();
}

/**
 * The one credential-resolution ladder: API key, then OAuth access token.
 * Returns identity (userId + scope statements) only β€” org-role resolution is a
 * cheap DB query the caller does per route, and it never touches the rate
 * limiter, so it does not need deduplicating.
 */
/**
 * Charge a resolved identity against its owner's budget, converting a denial
 * into a rate_limited result. A limiter failure is never fatal: the identity
 * passes through uncharged rather than locking out a valid credential.
 */
async function applyRateLimit(identity: BearerIdentity, deps: BearerResolverDeps): Promise<BearerIdentity> {
  if (!deps.consumeRateLimit) {
    return identity;
  }
  let decision: RateLimitDecision | null;
  try {
    decision = await deps.consumeRateLimit({ userId: identity.userId, organizationId: identity.organizationId });
  } catch {
    return identity;
  }
  if (!decision) {
    return identity;
  }
  if (!decision.allowed) {
    return { status: "rate_limited", statements: null, rateLimit: decision };
  }
  return { ...identity, rateLimit: decision };
}

// API keys are a prefix plus letters (prefixes allow only [A-Za-z0-9_-]), so a
// dotted token is a JWT access token and can skip the API-key lookup.
function looksLikeJwt(token: string): boolean {
  return token.split(".").length === 3;
}

export async function resolveBearerIdentity(token: string, deps: BearerResolverDeps): Promise<BearerIdentity> {
  let verifyError = false;
  let verification: ApiKeyVerification | null = null;
  if (!looksLikeJwt(token)) {
    try {
      verification = await deps.verifyApiKey(token);
    } catch {
      verifyError = true;
    }
  }

  if (verification?.valid && verification.key?.referenceId) {
    const statements = statementsFromApiKeyPermissions(verification.key.permissions);
    // referenceId is a user id or an organization id depending on which key
    // configuration minted the key (legacy keys have a NULL configId = user).
    if (verification.key.configId === ORG_API_KEY_CONFIG_ID) {
      return applyRateLimit({ status: "valid", organizationId: verification.key.referenceId, statements }, deps);
    }
    return applyRateLimit({ status: "valid", userId: verification.key.referenceId, statements }, deps);
  }

  if (verification?.error?.code === "RATE_LIMITED") {
    return { status: "rate_limited", statements: null };
  }

  // Not a valid API key β€” try it as an OAuth access token. Tolerate lookup
  // failures (e.g. OAuth tables not migrated yet) so API-key auth is unaffected.
  let oauth: OAuthTokenLookup = null;
  try {
    oauth = await deps.getOAuthSession(token);
  } catch {
    oauth = null;
  }

  if (isUsableOAuthToken(oauth)) {
    return applyRateLimit(
      {
        status: "valid",
        userId: oauth.userId as string,
        statements: parseOAuthScopes(typeof oauth.scopes === "string" ? oauth.scopes : null),
      },
      deps
    );
  }

  return { status: verifyError ? "verify_error" : "invalid", statements: null };
}

/**
 * In-process handoff so the MCP gate's one verification is not repeated by the
 * REST route it proxies to (better-auth's verifyApiKey has no non-counting
 * mode, so a second call would consume the rate limit twice per tool call).
 *
 * A pure optimization that fails safe: a missing, stale, or mismatched nonce
 * simply falls through to normal verification. The nonce is a crypto-random
 * handle to in-memory state that only the in-process proxy sets, and it is
 * additionally bound to the exact credential β€” so a forged header can never
 * authenticate as another user.
 */
export const INTERNAL_BEARER_HANDOFF_HEADER = "x-rybbit-mcp-bearer";

interface HandoffEntry {
  token: string;
  identity: BearerIdentity;
  /** A handoff covers exactly one REST call β€” see consumeBearerHandoff. */
  spent: boolean;
}
const handoffs = new Map<string, HandoffEntry>();

export function registerBearerHandoff(token: string, identity: BearerIdentity): string {
  const nonce = randomUUID();
  handoffs.set(nonce, { token, identity, spent: false });
  return nonce;
}

export function releaseBearerHandoff(nonce: string | undefined): void {
  if (nonce) {
    handoffs.delete(nonce);
  }
}

export function consumeBearerHandoff(
  nonce: string | string[] | undefined,
  token: string | null
): BearerIdentity | null {
  if (typeof nonce !== "string" || !token) {
    return null;
  }
  const entry = handoffs.get(nonce);
  if (!entry || entry.token !== token) {
    return null;
  }
  // One handoff covers one REST call. The MCP request already paid for that
  // call at the gate, but a single HTTP request can carry a whole JSON-RPC
  // batch β€” reusing the nonce for all of them would let a client run any
  // number of tool calls on one unit of budget. Later calls fall through to
  // normal verification, which charges them.
  if (entry.spent) {
    return null;
  }
  entry.spent = true;
  return entry.identity;
}