Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
8.9 KB
Raw Blame
import jwt from "jsonwebtoken";
import { VerificationKey } from "./keys";

export type GfsScope = "gfs.read" | "gfs.write" | "gfs.delete" | "gfs.manage_acl" | "gfs.share";

const VALID_SCOPES = new Set<string>([
  "gfs.read",
  "gfs.write",
  "gfs.delete",
  "gfs.manage_acl",
  "gfs.share",
]);

export interface GfsPathBinding {
  path: string;
  permissions: string[];
}

export interface GfsBrokeredAuthority {
  desktopUserId: string;
  controlAdminId: string;
  authoritySource: "linked-admin";
  linkLineageId?: string;
  linkGeneration?: number;
  desktopUserGeneration?: number;
}

export interface GfsVerifiedClaims {
  sub: string;
  drive: string;
  scopes: GfsScope[];
  pathBindings: GfsPathBinding[];
  /** users.lifecycle_version or control_admin_users.session_version. */
  authGeneration?: number;
  brokeredAuthority?: GfsBrokeredAuthority;
  principalType?: "user" | "control-admin";
  iat: number;
  exp: number;
}

const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

function parseBrokeredAuthority(raw: unknown, sub: string): GfsBrokeredAuthority | undefined {
  if (raw === undefined || raw === null) return undefined;
  if (typeof raw !== "object" || Array.isArray(raw)) {
    throw new GfsAuthError("brokeredAuthority must be an object");
  }
  const record = raw as Record<string, unknown>;
  const supportedKeys = new Set([
    "authoritySource",
    "controlAdminId",
    "desktopUserId",
    "linkLineageId",
    "linkGeneration",
    "desktopUserGeneration",
  ]);
  if (Object.keys(record).some((key) => !supportedKeys.has(key))) {
    throw new GfsAuthError("brokeredAuthority must contain exactly the supported fields");
  }
  const desktopUserId = record.desktopUserId;
  const controlAdminId = record.controlAdminId;
  if (typeof desktopUserId !== "string" || !UUID_RE.test(desktopUserId)) {
    throw new GfsAuthError("brokeredAuthority.desktopUserId must be a UUID");
  }
  if (typeof controlAdminId !== "string" || !UUID_RE.test(controlAdminId)) {
    throw new GfsAuthError("brokeredAuthority.controlAdminId must be a UUID");
  }
  if (record.authoritySource !== "linked-admin") {
    throw new GfsAuthError("brokeredAuthority.authoritySource is invalid");
  }
  if (sub.toLowerCase() !== controlAdminId.toLowerCase()) {
    throw new GfsAuthError("brokeredAuthority control admin must match token sub");
  }
  const linkLineageId = record.linkLineageId;
  if (
    linkLineageId !== undefined &&
    (typeof linkLineageId !== "string" || !UUID_RE.test(linkLineageId))
  ) {
    throw new GfsAuthError("brokeredAuthority.linkLineageId must be a UUID");
  }
  const parseGeneration = (value: unknown, field: string): number | undefined => {
    if (value === undefined) return undefined;
    if (!Number.isSafeInteger(value) || Number(value) < 1) {
      throw new GfsAuthError(`brokeredAuthority.${field} must be a positive integer`);
    }
    return Number(value);
  };
  return {
    desktopUserId: desktopUserId.toLowerCase(),
    controlAdminId: controlAdminId.toLowerCase(),
    authoritySource: "linked-admin",
    ...(linkLineageId === undefined ? {} : { linkLineageId: linkLineageId.toLowerCase() }),
    ...(parseGeneration(record.linkGeneration, "linkGeneration") === undefined
      ? {}
      : { linkGeneration: parseGeneration(record.linkGeneration, "linkGeneration") }),
    ...(parseGeneration(record.desktopUserGeneration, "desktopUserGeneration") === undefined
      ? {}
      : {
          desktopUserGeneration: parseGeneration(
            record.desktopUserGeneration,
            "desktopUserGeneration"
          ),
        }),
  };
}

export class GfsAuthError extends Error {
  readonly code = "unauthorized";
  constructor(message: string) {
    super(message);
    this.name = "GfsAuthError";
  }
}

export interface VerifyOptions {
  key: VerificationKey;
  audience: string;
  issuer?: string;
}

function parsePathBindings(raw: unknown): GfsPathBinding[] {
  if (raw === undefined || raw === null) return [];
  if (!Array.isArray(raw)) throw new GfsAuthError("pathBindings must be an array");
  return raw.map((entry, i) => {
    const e = entry as { path?: unknown; permissions?: unknown };
    if (typeof e.path !== "string") {
      throw new GfsAuthError(`pathBindings[${i}].path must be a string`);
    }
    if (!Array.isArray(e.permissions) || e.permissions.some((p) => typeof p !== "string")) {
      throw new GfsAuthError(`pathBindings[${i}].permissions must be a string[]`);
    }
    return { path: normalizePathBindingPath(e.path, i), permissions: e.permissions as string[] };
  });
}

function normalizePathBindingPath(path: string, index: number): string {
  if (path.length === 0 || path.trim() !== path) {
    throw new GfsAuthError(`pathBindings[${index}].path must be a canonical absolute path`);
  }
  if (!path.startsWith("/")) {
    throw new GfsAuthError(`pathBindings[${index}].path must be absolute`);
  }
  if (path !== "/" && /^\/+$/.test(path)) {
    throw new GfsAuthError(`pathBindings[${index}].path must not be slash-only`);
  }

  const normalized = path.length > 1 ? path.replace(/\/+$/, "") : path;
  if (normalized === "/") return normalized;

  const segments = normalized.slice(1).split("/");
  if (segments.some((segment) => segment.length === 0 || segment === "." || segment === "..")) {
    throw new GfsAuthError(`pathBindings[${index}].path contains an invalid segment`);
  }
  return normalized;
}

/**
 * Verify a gfs access token. Checks, in order: the `kid` matches the key gfsc
 * holds, then the RS256 signature, audience, issuer, and expiry, then the claim
 * shape. FAIL CLOSED — every failure throws GfsAuthError (→ 401); a token is
 * never trusted on a partial check.
 *
 * The token is only an UPPER BOUND on authority. The permission store is the
 * source of truth and is re-checked on every op (P1-S08); these verified
 * scopes/pathBindings never, by themselves, grant access.
 */
export function verifyGfsToken(token: string, opts: VerifyOptions): GfsVerifiedClaims {
  const decoded = jwt.decode(token, { complete: true });
  if (!decoded || typeof decoded === "string") {
    throw new GfsAuthError("malformed token");
  }
  if (decoded.header.kid !== opts.key.keyId) {
    throw new GfsAuthError("token kid does not match the configured signing key");
  }

  let payload: jwt.JwtPayload;
  try {
    const verified = jwt.verify(token, opts.key.publicKey, {
      algorithms: ["RS256"],
      audience: opts.audience,
      issuer: opts.issuer ?? "control-api",
    });
    if (typeof verified === "string") throw new GfsAuthError("unexpected string payload");
    payload = verified;
  } catch (err) {
    if (err instanceof GfsAuthError) throw err;
    throw new GfsAuthError(err instanceof Error ? err.message : "token verification failed");
  }

  const record = payload as Record<string, unknown>;
  const sub = record.sub;
  const drive = record.drive;
  const rawScopes = record.scopes;
  const iat = record.iat;
  const exp = record.exp;
  const principalType = record.principalType;
  const rawAuthGeneration = record.authGeneration;

  if (typeof sub !== "string" || sub.length === 0) throw new GfsAuthError("missing sub");
  if (typeof drive !== "string" || drive.length === 0) throw new GfsAuthError("missing drive");
  if (!Array.isArray(rawScopes)) throw new GfsAuthError("missing scopes");
  if (!Number.isSafeInteger(iat)) throw new GfsAuthError("missing or invalid iat");
  if (!Number.isSafeInteger(exp)) throw new GfsAuthError("missing or invalid exp");
  if (
    principalType !== undefined &&
    principalType !== "user" &&
    principalType !== "control-admin"
  ) {
    throw new GfsAuthError("invalid principalType");
  }
  if (
    rawAuthGeneration !== undefined &&
    (!Number.isSafeInteger(rawAuthGeneration) || Number(rawAuthGeneration) < 0)
  ) {
    throw new GfsAuthError("invalid authGeneration");
  }
  if (
    (principalType === "user" || principalType === "control-admin") &&
    rawAuthGeneration !== undefined &&
    Number(rawAuthGeneration) < 1
  ) {
    throw new GfsAuthError("human principal authGeneration must be positive");
  }
  const issuedAt = iat as number;
  const expiresAt = exp as number;
  if (expiresAt <= issuedAt) throw new GfsAuthError("token exp must be after iat");

  const scopes: GfsScope[] = [];
  for (const scope of rawScopes) {
    if (typeof scope !== "string" || !VALID_SCOPES.has(scope)) {
      throw new GfsAuthError(`invalid scope: ${String(scope)}`);
    }
    scopes.push(scope as GfsScope);
  }

  const brokeredAuthority = parseBrokeredAuthority(record.brokeredAuthority, sub);
  if (brokeredAuthority && principalType !== "control-admin") {
    throw new GfsAuthError("brokeredAuthority requires control-admin principalType");
  }

  return {
    sub,
    drive,
    scopes,
    pathBindings: parsePathBindings(record.pathBindings),
    ...(rawAuthGeneration === undefined ? {} : { authGeneration: Number(rawAuthGeneration) }),
    ...(brokeredAuthority ? { brokeredAuthority } : {}),
    ...(principalType ? { principalType } : {}),
    iat: issuedAt,
    exp: expiresAt,
  };
}