Integrate with an AI Assistant

import { Module } from "@nestjs/common";
import { CanopyModule } from "@canopy-io/nestjs";

interface AuthedRequest {
  canopyToken?: { sub: string };
  params?: Record<string, string>;
}

@Module({
  imports: [
    CanopyModule.forRoot<AuthedRequest>({
      apiKey: process.env.CANOPY_API_KEY,
      verify: {
        environmentId: process.env.CANOPY_ENVIRONMENT_ID ?? "",
        // Hosted Login: your OAuth client id. Direct API: leave this out.
        audience: process.env.CANOPY_OAUTH_CLIENT_ID,
      },
      resolveIdentity: (request) => request.canopyToken?.sub,
      resolveNode: (request) => request.params?.["nodeId"],
    }),
  ],
})
export class AppModule {}

import {
  TokenVerifier,
  tokenErrorStatus,
  type CanopyTokenClaims,
} from "@canopy-io/node";

// One verifier per process: it caches the key set. It accepts identity tokens
// only (your end users); admin, staff and API-key tokens are refused.
const verifier = new TokenVerifier({
  environmentId: process.env.CANOPY_ENVIRONMENT_ID ?? "",
  // Hosted Login: your OAuth client id. Direct API: leave this out.
  audience: process.env.CANOPY_OAUTH_CLIENT_ID,
});

export async function authenticate(
  authorization: string | undefined,
): Promise<CanopyTokenClaims | null> {
  const token = authorization?.startsWith("Bearer ")
    ? authorization.slice("Bearer ".length)
    : undefined;

  if (!token) {
    return null;
  }

  try {
    return await verifier.verify(token);
  } catch (error) {
    // 401 for the token's own faults (expired, bad signature, wrong issuer),
    // 503 when the keys could not be read. error.code is for your logs.
    if (tokenErrorStatus(error).status === 401) {
      return null;
    }

    throw error;
  }
}

import { Controller, Get, Post, UseGuards } from "@nestjs/common";
import {
  CanopyGuard,
  CanopyTokenGuard,
  RequirePermission,
} from "@canopy-io/nestjs";

@Controller("nodes/:nodeId/reports")
@UseGuards(CanopyTokenGuard, CanopyGuard)
export class ReportsController {
  // Does the identity hold reports.view at :nodeId, or above it?
  @Get()
  @RequirePermission("reports.view")
  list() {
    return [];
  }

  @Post(":reportId/publish")
  @RequirePermission("reports.publish")
  publish() {
    return { published: true };
  }

  // Anywhere in the Environment: for showing a menu item, never for a
  // resource that belongs to a node.
  @Get("menu")
  @RequirePermission("reports.view", { scope: "app_wide" })
  menu() {
    return { showReports: true };
  }
}

import express, {
  type NextFunction,
  type Request,
  type Response,
} from "express";
import {
  Canopy,
  LocalAuthorizer,
  TokenVerifier,
  authorizationErrorStatus,
  tokenErrorStatus,
  type CanopyTokenClaims,
} from "@canopy-io/node";

const canopy = new Canopy({ apiKey: process.env.CANOPY_API_KEY });
const authorizer = new LocalAuthorizer(canopy.client);
const verifier = new TokenVerifier({
  environmentId: process.env.CANOPY_ENVIRONMENT_ID ?? "",
  // Hosted Login: your OAuth client id. Direct API: leave this out.
  audience: process.env.CANOPY_OAUTH_CLIENT_ID,
});

interface CanopyLocals {
  claims?: CanopyTokenClaims;
}

// 1. Authenticate: verify the bearer token, never decode it.
export async function authenticate(
  request: Request,
  response: Response,
  next: NextFunction,
) {
  const header = request.headers.authorization;
  const token = header?.startsWith("Bearer ")
    ? header.slice("Bearer ".length)
    : undefined;

  if (!token) {
    response.sendStatus(401);
    return;
  }

  try {
    // Identity tokens only, by default: admin and staff tokens are refused.
    (response.locals as CanopyLocals).claims = await verifier.verify(token);
    next();
  } catch (error) {
    // 401 when the token is at fault, 503 when the keys could not be read.
    response.sendStatus(tokenErrorStatus(error).status);
  }
}

// 2. Authorize: does the identity hold `permission` at the node `nodeOf` names?
export function requirePermission(
  permission: string,
  nodeOf: (request: Request) => unknown,
) {
  return async (request: Request, response: Response, next: NextFunction) => {
    const claims = (response.locals as CanopyLocals).claims;
    const nodeId = nodeOf(request);

    // No node, or not a single id: denied, never widened to app_wide.
    if (!claims || typeof nodeId !== "string" || nodeId === "") {
      response.sendStatus(403);
      return;
    }

    try {
      const { allowed } = await authorizer.evaluate({
        identity_id: claims.sub,
        permission,
        node_id: nodeId,
      });

      if (allowed) {
        next();
        return;
      }

      response.sendStatus(403);
    } catch (error) {
      // The mapping CanopyGuard uses. Never collapse these into one 403.
      response.sendStatus(authorizationErrorStatus(error).status);
    }
  };
}

const app = express();

app.get(
  "/nodes/:nodeId/reports",
  authenticate,
  requirePermission("reports.view", (request) => request.params["nodeId"]),
  (_request, response) => {
    response.json([]);
  },
);

export default app;